IBM Security Access Manager 9.0.2This ePUB version of the IBM Security Access Manager 9.0.2 documentation contains all of the information from the IBM Knowledge Center version, excluding the messages.

IBM Security Access Manager 9.0.2

This ePUB version of the IBM Security Access Manager 9.0.2 documentation contains all of the information from the IBM Knowledge Center version, excluding the messages.

IBM Security Access Manager Virtual ApplianceQuick Start GuideVersion 9.0.2This guide describes the installation and initial configuration of the IBM Security Access Manager virtual appliance. CF4KGML National Language Version: To obtain the Quick Start Guide in other languages, print the language-specific PDF file from the installation media. IBM Security Access Manager Virtual Appliance 9.0.2 Licensed Materials - Property of IBM. © Copyright IBM Corp. 2015, 2016. U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the web at Copyright and trademark information (www.ibm.com/legal/copytrade.shtml). Product overviewThe IBM Security Access Manager virtual appliance helps organizations secure and manage user access and protect applications against fraudulent and unauthorized access.Evaluate the system configuration Evaluate your hypervisor and browser versions based on the product requirements in the following website: http://www.ibm.com/support/docview.wss?uid=swg27048193. Access the softwareIf you download your product from Passport Advantage, follow the instructions in the download document at http://www.ibm.com/support/docview.wss?uid=swg24042307. The download includes the IBM Security Access Manager virtual appliance firmware. It also includes either an .iso image or a Virtual Hard Disk (VHD) file. Use the VHD for the XenServer hypervisor and the .iso for other supported hypervisors. Gather network informationUse either DHCP or a static IP address to manage the appliance for networking. For a static IP address, use the following list to record important information for configuring the appliance network:Host nameManagement IP addressManagement Subnet MaskManagement GatewayManagement DNS serverFor DHCP, the appliance obtains a dynamically leased IP address from the local DHCP server when it is powered on. You can use DHCP discovery software to locate this IP address, or you can connect directly to the appliance console to manage the interface settings. Configure the virtual networkCorrectly configure the network before you install and run the virtual appliance. The appliance can use up to eight network devices. You must define and enable at least one device for the system to function properly. (Option 1) Install the firmware in a virtual machine environment other than the XenServer hypervisor Create a new virtual machine with the following minimum specifications: Disk space requirement: 100 GBMemory requirement: 4 GBVirtual network devices: 1 (Maximum 8)Virtual DVD/CD-ROM driveConfigure the virtual machine to start from the supplied .iso file.Start the virtual machine. The firmware installer starts automatically.(Previously partitioned virtual disk only) Select a language from the list of available languages.(Previously partitioned virtual disk only) The system prompts you to install the firmware. Enter yes.(Previously partitioned virtual disk only) When the firmware installation is complete, the system prompts you to restart. The virtual machine restarts to the appliance console unconfigured login prompt. If a previously partitioned disk does not exist, the system automatically shuts down after the installation is complete. (Option 2) Install the appliance on a XenServer hypervisor by using XenCenter In the XenCenter console, expand the XenCenter icon on the left.Right-click the attached hypervisor and select Import. In the Import Source window, click Browse and select the VHD image to be imported. Click Open and then Next.In the VM Definition window, specify the name, number of CPUs, and memory of the virtual machine and click Next. In most scenarios, assign the virtual machine at least one processor and 2 GB of memory. These settings can be adjusted after the virtual machine starts running.In the Location window, select the destination hypervisor from the drop-down list on the right and click Next.In the Storage window, select Place imported virtual disks onto specified target SRs and click Next.In the Networking window, select the network for the first management interface and click Next.In the OS Fixup Settings window, select Don't use Operating System Fixup and click Next.In the Transfer VM Settings window, specify the settings for your network environment and click Next. If DHCP is not available in the network, you must specify a valid IP address, subnet, and gateway.In the Finish window, click Finish. The import operation might by lengthy. You can click the Logs tab to check the progress of the import.When the import is complete, run the following commands on the XenServer console to set the image to paravirtualized mode: xe vm-list (to get the uuid for the VM) xe vm-param-set uuid=<vm uuid> HVM-boot-policy="" xe vm-param-set uuid=<vm uuid> PV-bootloader=pygrub xe vm-disk-list (to get the uuid for the disk - VBD entry) xe vbd-param-set uuid=<disk uuid> bootable=trueStart the imported virtual machine. You must configure at least one network interface for the appliance to start. Sometimes the XenCenter must be restarted before the new virtual appliance can be started correctly. To install the appliance by using XenAPI or xe command line, see the IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSPREK/welcome. Get started Access the appliance console or the local management interface to start the wizard. To use the local management interface, browse to the IP address of the appliance. By default, when the virtual image starts, it attempts to obtain an IP address from the local DHCP server. You can use DHCP discovery software to obtain the allocated IP address. Log in as admin. The default password is admin. To secure the appliance, change the password immediately when prompted by the wizard.Use the Appliance Setup wizard to complete the initial configuration. The following list is a subset of the tasks:Read and accept the License Agreement. For the local management interface, install the license file. You must have a license that is installed to download the firmware updates.Set the appliance password.Configure the networking, which includes the host name, management interface settings, and DNS configuration.Configure the date and time settings.When you complete the basic configuration, a summary is displayed. For the local management interface, review the details on the Completion page and click Complete Setup. For the appliance console, follow the prompts to Accept the configuration.Download the activation key from your account on Passport Advantage at https://www.ibm.com/software/howtobuy/softwareandservices/passportadvantage. More informationSee the IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSPREK/welcome

IBM Security Access Manager Virtual Appliance

Version 9.0.2

Quick Start Guide

This guide describes the installation and initial configuration of the IBM Security Access Manager virtual appliance.

National Language Version: To obtain the Quick Start Guide in other languages, print the language-specific PDF file from the installation media.

Product overview

The IBM Security Access Manager virtual appliance helps organizations secure and manage user access and protect applications against fraudulent and unauthorized access.

Step 1: Evaluate the system configuration

Evaluate your hypervisor and browser versions based on the product requirements in the following website: http://www.ibm.com/support/docview.wss?uid=swg27048193.

Step 2: Access the software

If you download your product from Passport Advantage®, follow the instructions in the download document at http://www.ibm.com/support/docview.wss?uid=swg24042307. The download includes the IBM Security Access Manager virtual appliance firmware. It also includes either an .iso image or a Virtual Hard Disk (VHD) file. Use the VHD for the XenServer hypervisor and the .iso for other supported hypervisors.

Step 3: Gather network information

Use either DHCP or a static IP address to manage the appliance for networking. For a static IP address, use the following list to record important information for configuring the appliance network:

Host name

Management IP address

Management Subnet Mask

Management Gateway

Management DNS server

For DHCP, the appliance obtains a dynamically leased IP address from the local DHCP server when it is powered on. You can use DHCP discovery software to locate this IP address, or you can connect directly to the appliance console to manage the interface settings.

Step 4: Configure the virtual network

Correctly configure the network before you install and run the virtual appliance. The appliance can use up to eight network devices. You must define and enable at least one device for the system to function properly.

Step 5: (Option 1) Install the firmware in a virtual machine environment other than the XenServer hypervisor

Create a new virtual machine with the following minimum specifications:

Disk space requirement: 100 GB

Memory requirement: 4 GB

Virtual network devices: 1 (Maximum 8)

Virtual DVD/CD-ROM drive

Configure the virtual machine to start from the supplied .iso file.

Start the virtual machine. The firmware installer starts automatically.

(Previously partitioned virtual disk only) Select a language from the list of available languages.

(Previously partitioned virtual disk only) The system prompts you to install the firmware. Enter yes.

(Previously partitioned virtual disk only) When the firmware installation is complete, the system prompts you to restart. The virtual machine restarts to the appliance console unconfigured login prompt. If a previously partitioned disk does not exist, the system automatically shuts down after the installation is complete.

Step 6: (Option 2) Install the appliance on a XenServer hypervisor by using XenCenter

In the XenCenter console, expand the XenCenter icon on the left.

Right-click the attached hypervisor and select Import. In the Import Source window, click Browse and select the VHD image to be imported. Click Open and then Next.

In the VM Definition window, specify the name, number of CPUs, and memory of the virtual machine and click Next. In most scenarios, assign the virtual machine at least one processor and 2 GB of memory. These settings can be adjusted after the virtual machine starts running.

In the Location window, select the destination hypervisor from the drop-down list on the right and click Next.

In the Storage window, select Place imported virtual disks onto specified target SRs and click Next.

In the Networking window, select the network for the first management interface and click Next.

In the OS Fixup Settings window, select Don't use Operating System Fixup and click Next.

In the Transfer VM Settings window, specify the settings for your network environment and click Next. If DHCP is not available in the network, you must specify a valid IP address, subnet, and gateway.

In the Finish window, click Finish. The import operation might by lengthy. You can click the Logs tab to check the progress of the import.

When the import is complete, run the following commands on the XenServer console to set the image to paravirtualized mode:

xe vm-list (to get the uuid for the VM)
xe vm-param-set uuid=<vm uuid> HVM-boot-policy=""
xe vm-param-set uuid=<vm uuid> PV-bootloader=pygrub
xe vm-disk-list (to get the uuid for the disk - VBD entry)
xe vbd-param-set uuid=<disk uuid> bootable=true

Start the imported virtual machine. You must configure at least one network interface for the appliance to start. Sometimes the XenCenter must be restarted before the new virtual appliance can be started correctly.

Note: To install the appliance by using XenAPI or xe command line, see the IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSPREK/welcome.

Step 7: Get started

Access the appliance console or the local management interface to start the wizard. To use the local management interface, browse to the IP address of the appliance. By default, when the virtual image starts, it attempts to obtain an IP address from the local DHCP server. You can use DHCP discovery software to obtain the allocated IP address.

Log in as admin. The default password is admin.

To secure the appliance, change the password immediately when prompted by the wizard.

Use the Appliance Setup wizard to complete the initial configuration. The following list is a subset of the tasks:

Read and accept the License Agreement. For the local management interface, install the license file. You must have a license that is installed to download the firmware updates.

Set the appliance password.

Configure the networking, which includes the host name, management interface settings, and DNS configuration.

Configure the date and time settings.

When you complete the basic configuration, a summary is displayed. For the local management interface, review the details on the Completion page and click Complete Setup. For the appliance console, follow the prompts to Accept the configuration.

Download the activation key from your account on Passport Advantage at https://www.ibm.com/software/howtobuy/softwareandservices/passportadvantage.

More information

See the IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSPREK/welcome

IBM® Security Access Manager Virtual Appliance 9.0.2 Licensed Materials - Property of IBM. © Copyright IBM Corp. 2015, 2016. U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the web at "Copyright and trademark information" (www.ibm.com/legal/copytrade.shtml).

Part Number: CF4KGML

IBM Security Access Manager Hardware ApplianceQuick Start GuideVersion 9.0This guide describes how to connect, configure, and maintain the IBM Security Access Manager hardware appliance. National Language Version: Printed copies of the translated Quick Start Guide are shipped with the IBM Security Access Manager Hardware Appliance package.IBM Security Access Manager Hardware Appliance, version 9.0 Licensed Materials - Property of IBM. © Copyright IBM Corp. 2015. U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and trademark information (www.ibm.com/legal/copytrade.shtml). Product overviewThe IBM Security Access Manager hardware appliance helps organizations secure and manage user access and protect applications against fraudulent or unauthorized access.Become familiar with the hardware components This product offering includes the following components:IBM Security Access Manager Hardware Appliance Ethernet cableTwo power cordsSerial console cable: Your appliance package might contain a USB serial console cable and a DB-9 serial console cable, or the package might contain only a DB-9 serial console cable. If you use the USB serial console cable and your PC does not recognize the cable, you might need to install the device driver. The device drivers are available for download from http://public.dhe.ibm.com/software/security/products/infrastructure_protection/USBDeviceDrivers or from the driver supplier at http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41. Appliance front panel Appliance rear panel Gather network information Use either DHCP or a static IP address to configure the appliance. For static IP address users, use this list to record important network information for configuring the appliance: Host nameManagement IP addressManagement Subnet MaskManagement GatewayManagement DNS server If you use DHCP, the appliance obtains a dynamically leased IP address from the local DHCP server when it is powered on. You can use DHCP discovery software to locate this IP address, or you can connect directly to the appliance console to manage the interface settings. You can also use the LCD panel to view the assigned IP address. The documentation provides details about configuring the IP settings. Prepare to run the Appliance Setup wizard To configure the initial appliance settings, follow the steps in the Appliance Setup wizard. You can use either the appliance console by connecting the serial console cable to the appliance, or use the local management interface in a web browser. The local management interface offers more advanced configuration options. To use the local management interface, you must browse to the IP address of the appliance. If you do not know the IP address, use the appliance console to connect the appliance and access the Appliance Setup wizard. The following sections provide details about this process. Install the appliance and power it on Connect both power cords to the appliance to prevent visual warning signals such as flashing lights.Use the supplied Ethernet cable to connect the network to the management interface. The management ports are on the front panel.For appliance console users, configure the IP settings by using the supplied serial console cable to connect the appliance to a terminal. The serial console port is on the front panel. If the chosen terminal does not have a serial port, use a serial to USB converter to connect to a USB port. Turn on the appliance by pressing the power button on the front panel.When the LCD display reads "IBM Security Access Manager", go to Step 5: Get Started. Get started Access the appliance console or the local management interface to start the wizard. Log in as the admin user. The default password is admin. To secure the appliance, change the password immediately when prompted by the wizard.Use the Appliance Setup wizard to complete the initial configuration. Follow the wizard prompts to configure the required details. The tasks in the wizard include: Reading and accepting the License Agreement. For local management interface users: download and install the license file. You must install a license before you can download firmware updates.Setting the appliance password.Configuring the network, which includes the host name, management interface settings, and DNS configuration.Configuring the date and time settings.When you complete the basic configuration, a summary screen displays. For local management interface users: review the details on the Completion page and click Complete Setup. For appliance console users: follow the prompts to Accept the configuration.Download the activation key from your account on Passport Advantage at https://www.ibm.com/software/howtobuy/softwareandservices/passportadvantage. More informationSee the IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSPREK/welcome

IBM Security Access Manager Hardware Appliance

Version 9.0

Quick Start Guide

This guide describes how to connect, configure, and maintain the IBM Security Access Manager hardware appliance.

National Language Version: Printed copies of the translated Quick Start Guide are shipped with the IBM® Security Access Manager Hardware Appliance package.

Product overview

The IBM Security Access Manager hardware appliance helps organizations secure and manage user access and protect applications against fraudulent or unauthorized access.

Step 1: Become familiar with the hardware components

This product offering includes the following components:

IBM Security Access Manager Hardware Appliance

Ethernet cable

Two power cords

Serial console cable: Your appliance package might contain a USB serial console cable and a DB-9 serial console cable, or the package might contain only a DB-9 serial console cable. If you use the USB serial console cable and your PC does not recognize the cable, you might need to install the device driver. The device drivers are available for download from http://public.dhe.ibm.com/software/security/products/infrastructure_protection/USBDeviceDrivers or from the driver supplier at http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41.

Appliance front panel

Appliance rear panel

Step 2: Gather network information

Use either DHCP or a static IP address to configure the appliance. For static IP address users, use this list to record important network information for configuring the appliance:

Host name

Management IP address

Management Subnet Mask

Management Gateway

Management DNS server

If you use DHCP, the appliance obtains a dynamically leased IP address from the local DHCP server when it is powered on. You can use DHCP discovery software to locate this IP address, or you can connect directly to the appliance console to manage the interface settings. You can also use the LCD panel to view the assigned IP address. The documentation provides details about configuring the IP settings.

Step 3: Prepare to run the Appliance Setup wizard

To configure the initial appliance settings, follow the steps in the Appliance Setup wizard. You can use either the appliance console by connecting the serial console cable to the appliance, or use the local management interface in a web browser. The local management interface offers more advanced configuration options. To use the local management interface, you must browse to the IP address of the appliance. If you do not know the IP address, use the appliance console to connect the appliance and access the Appliance Setup wizard. The following sections provide details about this process.

Step 4: Install the appliance and power it on

Connect both power cords to the appliance to prevent visual warning signals such as flashing lights.

Use the supplied Ethernet cable to connect the network to the management interface. The management ports are on the front panel.

For appliance console users, configure the IP settings by using the supplied serial console cable to connect the appliance to a terminal. The serial console port is on the front panel. If the chosen terminal does not have a serial port, use a serial to USB converter to connect to a USB port.

Turn on the appliance by pressing the power button on the front panel.

When the LCD display reads "IBM Security Access Manager", go to Step 5: Get Started.

Step 5: Get started

Access the appliance console or the local management interface to start the wizard.

Log in as the admin user. The default password is admin. To secure the appliance, change the password immediately when prompted by the wizard.

Use the Appliance Setup wizard to complete the initial configuration. Follow the wizard prompts to configure the required details. The tasks in the wizard include:

Reading and accepting the License Agreement. For local management interface users: download and install the license file. You must install a license before you can download firmware updates.

Setting the appliance password.

Configuring the network, which includes the host name, management interface settings, and DNS configuration.

Configuring the date and time settings.

When you complete the basic configuration, a summary screen displays. For local management interface users: review the details on the Completion page and click Complete Setup. For appliance console users: follow the prompts to Accept the configuration.

Download the activation key from your account on Passport Advantage at https://www.ibm.com/software/howtobuy/softwareandservices/passportadvantage.

More information

See the IBM Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSPREK/welcome

IBM Security Access Manager Hardware Appliance, version 9.0 Licensed Materials - Property of IBM. © Copyright IBM Corp. 2015. U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" (www.ibm.com/legal/copytrade.shtml).

Accessibility features for Security Access ManagerAccessibility features assist users who have a disability, such as restricted mobility or limited vision, to use information technology content successfully.accessibility features for this productAccessibility features Security Access Manager includes the following major accessibility features: Accessibility featuresSupports interfaces commonly used by screen readers. This feature applies to applications on Windows operating systems only.Can be operated by using only the keyboard.Allows the user to request more time to complete timed responses.Supports customization of display attributes such as color, contrast, and font size.Communicates all information independently of color.Supports interfaces commonly used by screen magnifiers. This feature applies to applications on Windows operating systems only.Allows the user to access the interfaces without inducing seizures due to photosensitivity. Security Access Manager uses the latest W3C Standard, WAI-ARIA 1.0 (http://www.w3.org/TR/wai-aria/), to ensure compliance to US Section 508 (http://www.access-board.gov/guidelines-and-standards/communications-and-it/about-the-section-508-standards/section-508-standards), and Web Content Accessibility Guidelines (WCAG) 2.0 (http://www.w3.org/TR/WCAG20/). To take advantage of accessibility features, use the latest release of your screen reader in combination with the latest web browser that is supported by this product. The Security Access Manager online product documentation in IBM Knowledge Center is enabled for accessibility. The accessibility features of IBM Knowledge Center are described at http://www.ibm.com/support/knowledgecenter/doc/kc_help.html#accessibility.Keyboard navigationThis product uses standard navigation keys. Interface information The Security Access Manager user interfaces do not have content that flashes 2 - 55 times per second. The Security Access Manager web user interfaces and the IBM Knowledge Center rely on cascading style sheets to render content properly and to provide a usable experience. The application provides an equivalent way for low-vision users to use a user’s system display settings, including high-contrast mode. You can control font size by using the device or web browser settings. The Security Access Manager web user interface includes WAI-ARIA navigational landmarks that you can use to quickly navigate to functional areas in the application. Related accessibility informationIn addition to standard IBM help desk and support websites, IBM has established a TTY telephone service for use by deaf or hard of hearing customers to access sales and support services: TTY service 800-IBM-3383 (800-426-3383) (within North America)IBM and accessibilityFor more information about the commitment that IBM has to accessibility, see IBM Accessibility (www.ibm.com/able).

Accessibility features for Security Access Manager

Accessibility features assist users who have a disability, such as restricted mobility or limited vision, to use information technology content successfully.

Accessibility features

Security Access Manager includes the following major accessibility features:

Accessibility features

Supports interfaces commonly used by screen readers. This feature applies to applications on Windows operating systems only.

Can be operated by using only the keyboard.

Allows the user to request more time to complete timed responses.

Supports customization of display attributes such as color, contrast, and font size.

Communicates all information independently of color.

Supports interfaces commonly used by screen magnifiers. This feature applies to applications on Windows operating systems only.

Allows the user to access the interfaces without inducing seizures due to photosensitivity.

Security Access Manager uses the latest W3C Standard, WAI-ARIA 1.0 (http://www.w3.org/TR/wai-aria/), to ensure compliance to US Section 508 (http://www.access-board.gov/guidelines-and-standards/communications-and-it/about-the-section-508-standards/section-508-standards), and Web Content Accessibility Guidelines (WCAG) 2.0 (http://www.w3.org/TR/WCAG20/). To take advantage of accessibility features, use the latest release of your screen reader in combination with the latest web browser that is supported by this product.

The Security Access Manager online product documentation in IBM® Knowledge Center is enabled for accessibility. The accessibility features of IBM Knowledge Center are described at http://www.ibm.com/support/knowledgecenter/doc/kc_help.html#accessibility.

Keyboard navigation

This product uses standard navigation keys.

Interface information

The Security Access Manager user interfaces do not have content that flashes 2 - 55 times per second.

The Security Access Manager web user interfaces and the IBM Knowledge Center rely on cascading style sheets to render content properly and to provide a usable experience. The application provides an equivalent way for low-vision users to use a user’s system display settings, including high-contrast mode. You can control font size by using the device or web browser settings.

The Security Access Manager web user interface includes WAI-ARIA navigational landmarks that you can use to quickly navigate to functional areas in the application.

Related accessibility information

In addition to standard IBM help desk and support websites, IBM has established a TTY telephone service for use by deaf or hard of hearing customers to access sales and support services:

TTY service 800-

IBM

-3383 (800-426-3383) (within North America)

IBM and accessibility

For more information about the commitment that IBM has to accessibility, see IBM Accessibility (www.ibm.com/able).

Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.release informationproduct overviewoverview of productwhat is newPDF and EPUB formats of the documentation are also available.Documentation for getting startedThe IBM Knowledge Center provides documentation that can help you get started with the IBM Security Access Manager Version 9.0.2 product.What's new in this releaseIBM Security Access Manager provides new features and extended functions for Version 9.0.2.Product requirementsYou can view Software Product Compatibility Reports that list the system requirements and appliance specifications for the product.Documentation for an activation levelIBM Security Access Manager uses the listed activation levels, depending on the modules you purchase. Use the information in the tables to determine which topics to start with in the documentation.Upgrading to the current versionComplete this task if you are upgrading an existing Access Manager for Web, Access Manager for Mobile, or Access Manager installation to the current version. APARs fixed in this versionSeveral APARs were fixed with this version of the product.Compatibility with earlier versions of the productIBM Security Access Manager V9.0.* is compatible with previous versions of Security Access Manager for Web, Tivoli Access Manager for e-business, and Security Access Manager for Mobile.Documentation updates for known limitationsYou can view the known software limitations, problems, and workarounds on the IBM® Security Access Manager Support site.Security Access Manager appliance FRU/CRU documentation in PDF formatDocumentation in PDF format for IBM Security Access Manager Field Replacement Unit (FRU) parts and Customer Replacement Unit (CRU) parts is available for download.

Product overview

The Product overview includes a description of the new features and important information about this specific release of the product.

Note: PDF and EPUB formats of the documentation are also available.

Documentation for getting started
The IBM Knowledge Center provides documentation that can help you get started with the IBM Security Access Manager Version 9.0.2 product.

What's new in this release
IBM® Security Access Manager provides new features and extended functions for Version 9.0.2.

Product requirements
You can view Software Product Compatibility Reports that list the system requirements and appliance specifications for the product.

Documentation for an activation level
IBM Security Access Manager uses the listed activation levels, depending on the modules you purchase. Use the information in the tables to determine which topics to start with in the documentation.

Upgrading to the current version
Complete this task if you are upgrading an existing Access Manager for Web, Access Manager for Mobile, or Access Manager installation to the current version.

APARs fixed in this version
Several APARs were fixed with this version of the product.

Compatibility with earlier versions of the product
IBM Security Access Manager V9.0.* is compatible with previous versions of Security Access Manager for Web, Tivoli Access Manager for e-business, and Security Access Manager for Mobile.

Documentation updates for known limitations
You can view the known software limitations, problems, and workarounds on the IBM® Security Access Manager Support site.

Security Access Manager appliance FRU/CRU documentation in PDF format
Documentation in PDF format for IBM Security Access Manager Field Replacement Unit (FRU) parts and Customer Replacement Unit (CRU) parts is available for download.

Documentation for getting startedGetting startedThe IBM Knowledge Center provides documentation that can help you get started with the IBM Security Access Manager Version 9.0.2 product.getting started IBM Security Access Manager Version 9.0.2 is a new modification of the Security Access Manager product available from Passport Advantage. You can use this distribution to either configure a new deployment or upgrade a previous version of the product. If you are upgrading from a previous version of IBM Security Access Manager for Web 8.*, IBM Security Access Manager for Mobile 8.*, or IBM Security Access Manager 9.0 be sure to review Upgrading to the current versionComplete this task if you are upgrading an existing Access Manager for Web, Access Manager for Mobile, or Access Manager installation to the current version. . If applicable, you must complete these steps before you configure the product. See Product activations overviewEach activation level on the IBM Security Access Manager appliance offers different features. Consider the needs of your environment to determine which activation levels you require. to review the features you can use when you activate the Security Access Manager Platform, the Advanced Access Control Module, or the Federation Module.Configure the appliance by using the instructions in Getting StartedComplete the following tasks that apply to your appliance format..Complete the initial setup of your Security Access Manager appliance deployment by following the instructions in Initial configurationSeveral initial configuration tasks are required for your IBM Security Access Manager environment..(Advanced Access Control Module only) Complete the initial setup of this module by following the instructions in Getting Started with Advanced Access ControlSeveral configuration tasks must be completed in order to start using Advanced Access Control.. Security Access Manager Platform includes an optional Java ADK, available for download. To install the Java ADK, see Installing IBM Security Access Manager Runtime for JavaExtract the contents of the runtime package file to install the IBM Security Access Manager Runtime for Java system and use the pdjrtecfg utility to configure it.. See Administering Web Reverse ProxyIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level. for instructions on how to use the local management interface on the appliance to configure and administer Security Access Manager Platform. Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

Documentation for getting started

The IBM Knowledge Center provides documentation that can help you get started with the IBM Security Access Manager Version 9.0.2 product.

IBM Security Access Manager Version 9.0.2 is a new modification of the Security Access Manager product available from Passport Advantage. You can use this distribution to either configure a new deployment or upgrade a previous version of the product.

If you are upgrading from a previous version of IBM Security Access Manager for Web 8.*, IBM Security Access Manager for Mobile 8.*, or IBM Security Access Manager 9.0 be sure to review Upgrading to the current version. If applicable, you must complete these steps before you configure the product.

See Product activations overview to review the features you can use when you activate the Security Access Manager Platform, the Advanced Access Control Module, or the Federation Module.

Configure the appliance by using the instructions in Getting Started.

Complete the initial setup of your Security Access Manager appliance deployment by following the instructions in Initial configuration.

(Advanced Access Control Module only) Complete the initial setup of this module by following the instructions in Getting Started with Advanced Access Control.

Security Access Manager Platform includes an optional Java ADK, available for download. To install the Java ADK, see Installing IBM Security Access Manager Runtime for Java.

See Administering Web Reverse Proxy for instructions on how to use the local management interface on the appliance to configure and administer Security Access Manager Platform.

Parent topic: Product overview

What's new in this releaseIBM Security Access Manager provides new features and extended functions for Version 9.0.2.what's newnew featuresAccess ManagerfeaturesSecurity Access ManagerfeaturesFind the new features listed by activation level:Access Manager Supporting ComponentsAccess Manager PlatformAdvanced Access ControlFederationAccess Manager Supporting Components Clustering improvementsRestricted nodes no longer contain replicas of the data that is stored by the embedded LDAP server. This change helps to remove sensitive data from being stored in the DMZ. See Restricted nodes in a clusterYou can restrict nodes that are in the DMZ so that your network is secure. You can specify which nodes are restricted in the local management interface..Tracing specifications for the local management interfaceYou can now control the tracing specifications for the different components of the local management interface. See Configuring tracing for the local management interfaceUse the LMI Tracing page to configure the tracing specifications for different components of the local management interface.. Configuring the maximum size and maximum number of the trace.log, messages.log files, and their rollover filesUse the Maximum Log File Size parameter to define the maximum size in megabytes that the log files can grow to before they are rolled over. Use the Maximum Log Files parameter to define the maximum number of log files and rollover files that can be kept on the system. See Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. or Configuring administrator settingsUse the Administrator Settings management page to tune the local management interface so that it can run more efficiently..Supported DB2 versionsSupport for DB2 Version 11.1 is added in this release. Security Access Manager now supports the following DB2 versions for running applications, developing applications, and performing database administration tasks:Version 9.5Version 9.7Version 9.8Version 10.1Version 11.1See http://www.ibm.com/support/docview.wss?uid=swg27048193 for the most up-to-date list of system requirements. Setting the signature algorithm for a new self-signed certificate or certificate requestWhen you create a self-signed certificate or a certificate request, you can specify the signature algorithm to be used. See Managing personal certificates in a certificate database To manage personal certificates in a certificate database with the local management interface, use the SSL Certificates management page. and Managing certificate requests in a certificate databaseTo manage certificate requests in a certificate database with the local management interface, use the SSL Certificates management page. In particular, you can create, view, export, or delete certificate requests, and list all certificate request names..View the size of application log filesThe Application Log Files page provides a Details View option, which displays the file details including log file size. See Viewing application log filesUse the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager..Access Manager Platform Flexible ACL permission bits for Web Reverse ProxyYou can change the mapping of HTTP request methods to ACL permission bits by specifying values in the [http-method-perms] stanza of the Web Reverse Proxy configuration file. See Changing the mapping of HTTP request methodsYou can change the mapping of HTTP request methods to ACL permission bits by specifying values in the [http-method-perms] stanza of the Web Reverse Proxy configuration file..WebSocket supportThe Web Reverse Proxy supports WebSocket connections between clients and junctioned web servers. See WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.. SSL support for front end load balancerYou can use SSL connections between the load balancer and the back-end server. See Configuring front-end load balancer To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page..Automatically compress rollover log filesSet the Compress option to Yes so that all rollover Security Access Manager auditing, tracing, and log files are automatically compressed to save disk space. See Modifying the tracing settings for a componentTo modify the trace level, flush interval, rollover size, maximum rollover files, and whether rollover files are automatically compressed for a component, use the Reverse Proxy management page or the Authorization Server management page., Managing transaction logging components and data filesTo manage transaction logging components and data files with the local management interface, use the Reverse Proxy management page., and Modifying the statistics settings for a componentTo modify the statistics settings for a particular component with the local management interface, use the Reverse Proxy management page..Advanced Access Control Enabling flexible User Self-Care work flowsYou can enable flexible User Self-Care work flows though the existing authentication service by using the following new authentication mechanisms.Email Message mechanismThis mechanism provides arbitrary information about a user through email messages. See Configuring an Email Message authentication mechanismThe Email Message mechanism provides arbitrary information about a user via either email, webpage, or JSON for consumption by users or applications..Info Map mechanismThis mechanism exposes a JavaScript mapping rule, which can be used to prompt the user for authentication data and then perform arbitrary operations on this authentication data, including modifying the user's profile via SCIM. See Configuring an Info Map authentication mechanismUse this mechanism in your policy to return a template form and perform validation on the responding POST data. This mechanism is intended to work in conjunction with the Email Message mechanism. .ReCAPTCHA Verification mechanism This mechanism provides anti-robot protection by prompting the user to complete simple Turing tests that can tell human from computers. See Configuring a ReCAPTCHA Verification authentication mechanismThe reCAPTCHA Verification authentication mechanism provides anti-robot protection..Pre-defined User Self-Care workflowsSecurity Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval. See SCIM account managementSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. The SCIM interface can be used as a consolidated API for accessing user data from various data sources..Automatic reload of the runtime configurationYou no longer need to restart the runtime when you make certain configuration changes. These configuration changes require the runtime be reloaded. Unlike runtime restart, runtime reload does not stop the runtime server. As a result, you can make configuration changes without bringing the runtime server down. See Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. .Disable automatic restart or reload of the runtimeBy default, the Advanced Access Control and Federation runtime is automatically restarted or reloaded after certain changes are made. You can disable this automatic restart or reload function if you prefer manual restart. See Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. .RESTful web service for user identity dataA new SCIM-based web service is available, which provides access to user data. This web service can be used for user data access in User Self-Care applications. The types of data that can be managed by this web service include user registry, Security Access Manager user entry, user knowledge questions, and Mobile Multi Factor Authentication data management. See the RESTful API documentation for details.You can also use the SCIM Configuration page in the local management interface to configure the SCIM application. See SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. .Load balancer support for stickiness based on OAuth authorization headerFor HA scenarios, runtime performance is maximized when a front end load balancer routes OAuth client requests to the same web reverse proxy instance. Such HTTP request header balancing can be achieved by specifying the virtual server advanced tuning parameter balance. See Benefits of layer 7 load balancingThe main benefit of layer 7 load balancing is the ability to use and manipulate the HTTP headers in requests and responses..Macro pre-populated with client metadata Use the oauth20.clientDataToInclude advanced configuration property to specify which client information to return as JSON data. See Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..The @OAUTH_CLIENT_DATA_MACRO@ replacement macro can be used to store the OAuth client information. Customizing OAuth tokensYou can customize the format of the tokens that are issued by your OAuth definition. See Customizing OAuth tokens through the pre-token mapping ruleYou can customize the format of the tokens that are issued by your OAuth definition. .OAuth utility to update token dataNew methods are available within the OAuth mapping rule utilities to allow further token retrieval, deletion, and some modification of tokens, for example, updating the tokens lifetime. See the Javadoc documentation that is available from the appliance File Downloads area for details.Push notification registrationSecurity Access Manager supports push notification on both iOS and Android platforms. You must register your endpoints before you can use push notification. See Push notification registrationSecurity Access Manager supports push notifications on both iOS and Android platforms..Mobile Multi-Factor AuthenticationSecurity Access Manager supports Mobile Multi-Factor Authentication. See Mobile Multi-Factor AuthenticationThe IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol. .New RESTful web services are available for setting up Mobile Multi-Factor Authentication:Configuring Mobile Multi-Factor Authentication reverse proxy points of contactDefining Mobile Multi-Factor Authentication token endpoint detailsRegistration of authenticators via User Self-CareRegistration of authentication methods via the Mobile Multi-Factor Authentication runtimeSee the RESTful API documentation for details.Mobile User Approved authentication mechanismMobile User Approved authentication mechanism can be used for fingerprint authentication. See Configuring a Mobile User Approved authentication mechanismThe Mobile User Approved authentication mechanism prompts the user to sign a random challenge string with a private key that is associated with one of the key values that are provided during the authentication flow..Controlled cleanup for expired OAuth 2.0 tokensSet advanced configuration parameter, oauth20.cleanupThread.batchsize, to delete a specified number of records per batch. See Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..Controlled cleanup for expired registered devicesSet advanced configuration parameter, deviceRegistration.cleanupThread.batchsize, to delete a specified number of records per batch. See Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..Federation Custom category for mapping rulesWhen you create or upload a mapping rule, you can specify a custom category, in addition to selecting one of the predefined categories. See Managing JavaScript mapping rulesCreate, edit, or delete JavaScript mapping rules.. JSON Web Token (JWT) moduleThe appliance provides a JWT module that can be used to consume or issue JWT tokens. See JSON Web Token (JWT)A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC..New query string parameters in SP-initiated SAML SSOIncludeIsPassiveIncludeForceAuthnIncludeAllowCreateYou can use these parameters to include or exclude the IsPassive, ForceAuthn, and AllowCreate attributes from the SAML authentication request. See SAML 2.0 profile initial URLsIn a federated environment, specially formed URLs can be used for user-initiated single sign-on actions. You can initiate a single sign-on flow from the service provider or identity provider. .Automatic reload of the runtime configurationYou no longer need to restart the runtime when you make certain configuration changes. These configuration changes require the runtime be reloaded. Unlike runtime restart, runtime reload does not stop the runtime server. As a result, you can make configuration changes without bringing the runtime server down. See Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. .Disable automatic restart or reload of the runtimeBy default, the Advanced Access Control and Federation runtime is automatically restarted or reloaded after certain changes are made. You can disable this automatic restart or reload function if you prefer manual restart. See Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. .CRL enhancementsIf a certificate revocation list (CRL) site is not available, the federation runtime can mark the status as unknown and keep the certificate in memory, instead of revoking it. See the kess.crlEnabled property in Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..You can set an interval between successive CRL checks by using a new advanced configuration property, kess.crlInterval. See Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..Point of contact profile upgradeBe aware of changes that might affect your point of contact configuration after an upgrade. See Point of contact profile configuration after an upgradeThe point of contact profile configuration process changed compared to how it was handled before release 9.0.1. .Some poc.* advanced configuration properties are deprecated and one is removed. See Point of contact advanced configuration property updatesThe use of several point of contact advanced configuration properties has changed; some properties are deprecated and one is removed after an upgrade..Addition of information about auditing federation eventsSee Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access..Addition of information about how to access STSRequest and STSResponse objects using a JavaScript mapping ruleThis function was available in 9.0.1. See STSRequest and STSResponse access using a JavaScript mapping ruleBy using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects..Nested single sign-on flows for federationsFederation supports nesting of single sign-on flows for SAML and Open ID Connect protocols. See Nested single sign-on flowsYou can nest SAML or OpenID Connect single sign-on flows. That is, you can resume an initial SSO flow after the completion of a second SSO flow. .JWT and SAML bearer grant type flowsThe JWT and SAML bearer grant type flows are added as supported OAuth 2.0 grants. See OAuth 2.0 workflow.Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

What's new in this release

IBM® Security Access Manager provides new features and extended functions for Version 9.0.2.

Find the new features listed by activation level:

Access Manager Supporting Components

Access Manager Platform

Advanced Access Control

Federation

Access Manager Supporting Components

Clustering improvements

Restricted nodes no longer contain replicas of the data that is stored by the embedded LDAP server. This change helps to remove sensitive data from being stored in the DMZ. See Restricted nodes in a cluster.

Tracing specifications for the local management interface

You can now control the tracing specifications for the different components of the local management interface. See Configuring tracing for the local management interface.

Configuring the maximum size and maximum number of the trace.log, messages.log files, and their rollover files

Use the Maximum Log File Size parameter to define the maximum size in megabytes that the log files can grow to before they are rolled over. Use the Maximum Log Files parameter to define the maximum number of log files and rollover files that can be kept on the system. See Tuning runtime application parameters and tracing specifications or Configuring administrator settings.

Supported DB2 versions

Support for DB2 Version 11.1 is added in this release. Security Access Manager now supports the following DB2 versions for running applications, developing applications, and performing database administration tasks:

Version 9.5

Version 9.7

Version 9.8

Version 10.1

Version 11.1

See http://www.ibm.com/support/docview.wss?uid=swg27048193 for the most up-to-date list of system requirements.

Setting the signature algorithm for a new self-signed certificate or certificate request

When you create a self-signed certificate or a certificate request, you can specify the signature algorithm to be used. See Managing personal certificates in a certificate database and Managing certificate requests in a certificate database.

View the size of application log files

The Application Log Files page provides a Details View option, which displays the file details including log file size. See Viewing application log files.

Access Manager Platform

Flexible ACL permission bits for Web Reverse Proxy

You can change the mapping of HTTP request methods to ACL permission bits by specifying values in the [http-method-perms] stanza of the Web Reverse Proxy configuration file. See Changing the mapping of HTTP request methods.

WebSocket support

The Web Reverse Proxy supports WebSocket connections between clients and junctioned web servers. See WebSockets.

SSL support for front end load balancer

You can use SSL connections between the load balancer and the back-end server. See Configuring front-end load balancer.

Automatically compress rollover log files

Set the Compress option to Yes so that all rollover Security Access Manager auditing, tracing, and log files are automatically compressed to save disk space. See Modifying the tracing settings for a component, Managing transaction logging components and data files, and Modifying the statistics settings for a component.

Advanced Access Control

Enabling flexible User Self-Care work flows

You can enable flexible User Self-Care work flows though the existing authentication service by using the following new authentication mechanisms.

Email Message mechanism

This mechanism provides arbitrary information about a user through email messages. See Configuring an Email Message authentication mechanism

.

Info Map mechanism

This mechanism exposes a JavaScript mapping rule, which can be used to prompt the user for authentication data and then perform arbitrary operations on this authentication data, including modifying the user's profile via SCIM. See Configuring an Info Map authentication mechanism.

ReCAPTCHA Verification mechanism

This mechanism provides anti-robot protection by prompting the user to complete simple Turing tests that can tell human from computers. See Configuring a ReCAPTCHA Verification authentication mechanism.

Pre-defined User Self-Care workflows

Security Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval. See SCIM account management.

Automatic reload of the runtime configuration

You no longer need to restart the runtime when you make certain configuration changes. These configuration changes require the runtime be reloaded. Unlike runtime restart, runtime reload does not stop the runtime server. As a result, you can make configuration changes without bringing the runtime server down. See Tuning runtime application parameters and tracing specifications.

Disable automatic restart or reload of the runtime

By default, the Advanced Access Control and Federation runtime is automatically restarted or reloaded after certain changes are made. You can disable this automatic restart or reload function if you prefer manual restart. See Tuning runtime application parameters and tracing specifications.

RESTful web service for user identity data

A new SCIM-based web service is available, which provides access to user data. This web service can be used for user data access in User Self-Care applications. The types of data that can be managed by this web service include user registry, Security Access Manager user entry, user knowledge questions, and Mobile Multi Factor Authentication data management. See the RESTful API documentation for details.

You can also use the SCIM Configuration page in the local management interface to configure the SCIM application. See SCIM configuration.

Load balancer support for stickiness based on OAuth authorization header

For HA scenarios, runtime performance is maximized when a front end load balancer routes OAuth client requests to the same web reverse proxy instance. Such HTTP request header balancing can be achieved by specifying the virtual server advanced tuning parameter balance. See Benefits of layer 7 load balancing.

Macro pre-populated with client metadata

Use the oauth20.clientDataToInclude advanced configuration property to specify which client information to return as JSON data. See Advanced configuration properties.

The @OAUTH_CLIENT_DATA_MACRO@ replacement macro can be used to store the OAuth client information.

Customizing OAuth tokens

You can customize the format of the tokens that are issued by your OAuth definition. See Customizing OAuth tokens through the pre-token mapping rule.

OAuth utility to update token data

New methods are available within the OAuth mapping rule utilities to allow further token retrieval, deletion, and some modification of tokens, for example, updating the tokens lifetime. See the Javadoc documentation that is available from the appliance File Downloads area for details.

Push notification registration

Security Access Manager supports push notification on both iOS and Android platforms. You must register your endpoints before you can use push notification. See Push notification registration.

Mobile Multi-Factor Authentication

Security Access Manager supports Mobile Multi-Factor Authentication. See Mobile Multi-Factor Authentication.

New RESTful web services are available for setting up Mobile Multi-Factor Authentication:

Configuring Mobile Multi-Factor Authentication reverse proxy points of contact

Defining Mobile Multi-Factor Authentication token endpoint details

Registration of authenticators via User Self-Care

Registration of authentication methods via the Mobile Multi-Factor Authentication runtime

See the RESTful API documentation for details.

Mobile User Approved authentication mechanism

Mobile User Approved authentication mechanism can be used for fingerprint authentication. See Configuring a Mobile User Approved authentication mechanism.

Controlled cleanup for expired OAuth 2.0 tokens

Set advanced configuration parameter, oauth20.cleanupThread.batchsize, to delete a specified number of records per batch. See Advanced configuration properties.

Controlled cleanup for expired registered devices

Set advanced configuration parameter, deviceRegistration.cleanupThread.batchsize, to delete a specified number of records per batch. See Advanced configuration properties.

Federation

Custom category for mapping rules

When you create or upload a mapping rule, you can specify a custom category, in addition to selecting one of the predefined categories. See Managing JavaScript mapping rules.

JSON Web Token (JWT) module

The appliance provides a JWT module that can be used to consume or issue JWT tokens. See JSON Web Token (JWT).

New query string parameters in SP-initiated SAML SSO

IncludeIsPassive

IncludeForceAuthn

IncludeAllowCreate

You can use these parameters to include or exclude the IsPassive, ForceAuthn, and AllowCreate attributes from the SAML authentication request. See SAML 2.0 profile initial URLs.

Automatic reload of the runtime configuration

You no longer need to restart the runtime when you make certain configuration changes. These configuration changes require the runtime be reloaded. Unlike runtime restart, runtime reload does not stop the runtime server. As a result, you can make configuration changes without bringing the runtime server down. See Tuning runtime application parameters and tracing specifications.

Disable automatic restart or reload of the runtime

By default, the Advanced Access Control and Federation runtime is automatically restarted or reloaded after certain changes are made. You can disable this automatic restart or reload function if you prefer manual restart. See Tuning runtime application parameters and tracing specifications.

CRL enhancements

If a certificate revocation list (CRL) site is not available, the federation runtime can mark the status as unknown and keep the certificate in memory, instead of revoking it. See the kess.crlEnabled property in Advanced configuration properties.

You can set an interval between successive CRL checks by using a new advanced configuration property, kess.crlInterval. See Advanced configuration properties.

Point of contact profile upgrade

Be aware of changes that might affect your point of contact configuration after an upgrade. See Point of contact profile configuration after an upgrade.

Some poc.* advanced configuration properties are deprecated and one is removed. See Point of contact advanced configuration property updates.

Addition of information about auditing federation events

See Auditing Federation.

Addition of information about how to access STSRequest and STSResponse objects using a JavaScript mapping rule

This function was available in 9.0.1. See STSRequest and STSResponse access using a JavaScript mapping rule.

Nested single sign-on flows for federations

Federation supports nesting of single sign-on flows for SAML and Open ID Connect protocols. See Nested single sign-on flows.

JWT and SAML bearer grant type flows

The JWT and SAML bearer grant type flows are added as supported OAuth 2.0 grants. See OAuth 2.0 workflow.

Parent topic: Product overview

Product requirementsProduct requirementsProduct requirementsYou can view Software Product Compatibility Reports that list the system requirements and appliance specifications for the product.product requirementssystem requirementsappliance specificationsdisk usagesupported softwaresupported hypervisorshypervisors supportedWebSEAL suportcookie managementreverse proxyRFC 2616The reports provide current information about hardware and software support and requirements for IBM Security Access Manager.System requirements for hardware appliance:Prerequisite software, including supported databases, user registries, and browsersAppliance specifications such as disk size, memory, network ports, physical characteristics, and electrical and environmental parametersSystem requirements for the virtual appliance:Supported hypervisors, databases, user registries, and browsersDisk space and memory requirements for virtual imagesIBM Security Access Manager versions 8.0 and 9.0 are not available as a software distribution. They are available only as a virtual or hardware-based appliance.To view the reports, see IBM Security Access Manager System Requirements.WebSEAL client support When acting as a reverse proxy, WebSEAL generally supports clients that conform to the HTTP 1.1 standard as defined by RFC 2616. The preceding statement is not a comprehensive statement of support. WebSEAL relies on a number of client characteristics that are either not defined or are loosely defined by RFC 2616. Examples of such characteristics include, but are not limited to: Cookie managementSSL supportConcurrency of multiple connections Widely used browsers such as Firefox, Chrome, Safari, and Internet Explorer support such characteristics during typical use. The extension of browser capabilities that modify these characteristics can, however, introduce compatibility problems with WebSEAL. The same is true of other client types, such as mobile applications or rich clients. Compatibility complications that cannot be resolved through modification of the environment or configuration of the WebSEAL product are not supported.Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

Product requirements

You can view Software Product Compatibility Reports that list the system requirements and appliance specifications for the product.

The reports provide current information about hardware and software support and requirements for IBM Security Access Manager.

System requirements for hardware appliance:

Prerequisite software, including supported databases, user registries, and browsers

Appliance specifications such as disk size, memory, network ports, physical characteristics, and electrical and environmental parameters

System requirements for the virtual appliance:

Supported hypervisors, databases, user registries, and browsers

Disk space and memory requirements for virtual images

Note: IBM Security Access Manager versions 8.0 and 9.0 are not available as a software distribution. They are available only as a virtual or hardware-based appliance.

To view the reports, see IBM Security Access Manager System Requirements.

WebSEAL client support

When acting as a reverse proxy, WebSEAL generally supports clients that conform to the HTTP 1.1 standard as defined by RFC 2616. The preceding statement is not a comprehensive statement of support. WebSEAL relies on a number of client characteristics that are either not defined or are loosely defined by RFC 2616. Examples of such characteristics include, but are not limited to:

Cookie management

SSL support

Concurrency of multiple connections

Widely used browsers such as Firefox, Chrome, Safari, and Internet Explorer support such characteristics during typical use.

The extension of browser capabilities that modify these characteristics can, however, introduce compatibility problems with WebSEAL. The same is true of other client types, such as mobile applications or rich clients. Compatibility complications that cannot be resolved through modification of the environment or configuration of the WebSEAL product are not supported.

Parent topic: Product overview

Documentation for an activation levelIBM Security Access Manager uses the listed activation levels, depending on the modules you purchase. Use the information in the tables to determine which topics to start with in the documentation.Access Manager Supporting ComponentsSupporting ComponentscomponentssupportingAccess Manager PlatformplatformAccess ManagerAccess Manager Supporting Components No activation key is required for these functions.Access Manager Supporting Components functions and topic links FunctionTopic Appliance Management: Local management interface Appliance ManagementThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Appliance Management: REST APIs REST API documentationPolicy Server Policy server administration tasksThe policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.Embedded LDAP server Embedded LDAP server managementWhen you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry. Authorization ServerAuthorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.Access Manager PlatformAn activation key is required for these functions. Access Manager Platform functions and topic linksFunctionTopicWeb Reverse ProxyWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy. and Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Layer 4/7 load balancerLoad balancing layerSecurity Access Manager supports load balancing at layer 4 or layer 7 of the Open Systems Interconnection (OSI) network model.X-Force threat protection Configuring web application firewall To configure web application firewall with the local management interface, use the Reverse Proxy management page.Distributed session cache Distribued session cacheAdvanced Access Control ModuleThis module is an add-on feature that requires an activation key. Advanced Access Control functions and topic linksFunctionTopicAuthenticationAuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.OAuth 2.0 API protection Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client. Context-based access Overview of context-based accessContext-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.Device fingerprinting Device fingerprintsDevice registration is the process that stores the device fingerprint of the user in the context-based access database. Device registrationConsent-based device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration. HOTP and TOTP Key ManagerManaging OTP secret keysTo help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability. Fine-grained authorization/XACML 2.0 Access control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.Runtime security services Runtime security services external authorization serviceThe runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.Policy distribution (Policy administration point)Risk management overviewContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.Federation ModuleThis module is an add-on feature that requires an activation key. Federation functions and topic linksFunctionTopicSAML 2.0 FederationsSAML 2.0 federations The Federation Module supports SAML 2.0 federations.Open ID Connect FederationsOpenID Connect federationsThe Federation Module supports OpenID Connect federations.Module chainsManage module chainsUse the Security Token Service page to achieve token conversions through the WS-Trust interface. and Configuring STS modulesConfigure Security Token Service (STS) modules to validate and exchange security token types.Related informationProduct activations overviewEach activation level on the IBM Security Access Manager appliance offers different features. Consider the needs of your environment to determine which activation levels you require. Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

Documentation for an activation level

IBM Security Access Manager uses the listed activation levels, depending on the modules you purchase. Use the information in the tables to determine which topics to start with in the documentation.

Access Manager Supporting Components

No activation key is required for these functions.

Table 1. Access Manager Supporting Components functions and topic links

Function | Topic
Appliance Management: Local management interface | Appliance Management
Appliance Management: REST APIs | REST API documentation
Policy Server | Policy server administration tasks
Embedded LDAP server | Embedded LDAP server management
Authorization Server | Authorization servers

Access Manager Platform

An activation key is required for these functions.

Table 2. Access Manager Platform functions and topic links

Function | Topic
Web Reverse Proxy | Web Reverse Proxy configuration and Web Reverse Proxy administration
Layer 4/7 load balancer | Load balancing layer
X-Force threat protection | Configuring web application firewall
Distributed session cache | Distribued session cache

Advanced Access Control Module

This module is an add-on feature that requires an activation key.

Table 3. Advanced Access Control functions and topic links

Function | Topic
Authentication | Authentication
OAuth 2.0 API protection | Configuring API protection
Context-based access | Overview of context-based access
Device fingerprinting | Device fingerprints
Device registration | Consent-based device registration
HOTP and TOTP Key Manager | Managing OTP secret keys
Fine-grained authorization/XACML 2.0 | Access control policies
Runtime security services | Runtime security services external authorization service
Policy distribution (Policy administration point) | Risk management overview

Federation Module

This module is an add-on feature that requires an activation key.

Table 4. Federation functions and topic links

Function | Topic
SAML 2.0 Federations | SAML 2.0 federations
Open ID Connect Federations | OpenID Connect federations
Module chains | Manage module chains and Configuring STS modules

Related information

Product activations overview

Parent topic: Product overview

Upgrading to the current versionComplete this task if you are upgrading an existing Access Manager for Web, Access Manager for Mobile, or Access Manager installation to the current version. upgradeapplianceapplianceupgradeIf you are installing the virtual appliance for the first time, download the .iso image and follow the installation instructions in the Virtual Appliance Quick Start Guide.Review the following tasks and complete the tasks that are appropriate to your environment:Clear the browser cache As part of the upgrade process, clear your browser cache to reduce the likelihood of encountering issues with cached items. USB drive for an updateIf you use a USB drive for an update, it must be formatted with a FAT file system.Risk engine reportsAny risk engine reports that you generated before you begin the upgrade task are not preserved. Export copies of the risk reports and save them locally by completing the following steps: Log in to the local management interface.Click Monitor Analysis and DiagnosticsApplication Log Files. Expand access_control and select the risk reports to export.Click Export and save the files.Database failover in a clusterFor information about how the upgrade affects database failover in a cluster, see http://www.ibm.com/support/docview.wss?uid=swg21666968.Choose one of the following upgrade methods and complete the steps:Use the online update server.Meet the following conditions: A valid license is installed on the appliance.The appliance has network connectivity to the online update server.If you are upgrading a cluster, prepare the cluster as follows:Log in to the local management interface.Select Manage System SettingsCluster ConfigurationGeneral.Do not change the Primary Master setting.Remove the Secondary Master and other high-availability cluster member settings.Click Export and save the files.Wait for the cluster to synchronize.On the primary node, continue with the remaining steps to install the upgrade.Log in to the local management interface.Select Manage System SettingsUpdates and LicensingAvailable Updates.Click Refresh.Select the firmware update.Click Install. The firmware update might take a long time to complete, depending on the bandwidth that is available to the appliance. After the update is successfully applied, the appliance automatically restarts.If you installed the upgrade on a cluster, complete the installation: Repeat steps 1.b through 1.f on each appliance in the cluster.From the local management interface on the master node, update the cluster configuration to set the high-availability cluster members back to the settings you want.Wait for the cluster to synchronize. The firmware for each appliance in the cluster is now upgraded and the cluster is operational.Use the local management interface for a single appliance not in a cluster.Download the .pkg file.Log in to the local management interface.Select Manage System SettingsUpdates and LicensingAvailable Updates.Click Upload. The New Update window opens.Click Select Update.Browse to the .pkg file.Click Open.Click Save Configuration. The upload process might take several minutes.Select the new firmware and click Install. The installation of the new firmware takes a few minutes. After the update is successfully applied, the appliance restarts automatically.Use the local management interface for a cluster of appliances.To upgrade a cluster configuration, you must change the cluster configuration temporarily before the upgrade so that changes can be written to the database. Download the .pkg file.Log in to the local management interface.Select Manage System SettingsCluster ConfigurationGeneral.Do not change the Primary Master setting.Remove the Secondary Master and other high-availability cluster member settings.Click Export and save the files.Wait for the cluster to synchronize.Upload and install the firmware .pkg file on the primary node appliance. This step includes the automatic restart of the appliance.Upload and install the firmware .pkg file on each appliance in the cluster, and restart each one.From the local management interface on the master node, update the cluster configuration to set the high-availability cluster members back to the settings you want.Wait for the cluster to synchronize. The firmware for each appliance in the cluster is now upgraded and the cluster is operational.Use a USB drive. (Only for upgrading a hardware appliance.)Download the .pkg file.Copy the firmware update from the .pkg file to a USB flash drive.Insert the USB flash drive into the hardware appliance.Log in to the appliance console as admin or use Secure Shell.Type updates and press Enter.Type install and press Enter.Select the following options:Type 1 for a firmware update.Type 1 to install the update from a USB drive.Type YES to confirm that the USB drive is plugged into the appliance.Type the index number to select the appliance firmware from the list.Type YES to confirm the update and start the update process.The firmware update takes a few minutes to complete and the appliance automatically restarts. If you are upgrading an existing appliance, your Access Manager Platform is ready to use.If you are upgrading an existing Access Manager for Mobile appliance or Advanced Access Control module to the current version, continue with the Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks. instructions.If you are upgrading an existing Federation module to the current version, continue with the Upgrading configurationAfter upgrading your Security Access Manager appliance, be aware of some changes to your configuration. instructions. Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

Upgrading to the current version

Complete this task if you are upgrading an existing Access Manager for Web, Access Manager for Mobile, or Access Manager installation to the current version.

Before you begin

If you are installing the virtual appliance for the first time, download the .iso image and follow the installation instructions in the Virtual Appliance Quick Start Guide.

Review the following tasks and complete the tasks that are appropriate to your environment:

Clear the browser cache

As part of the upgrade process, clear your browser cache to reduce the likelihood of encountering issues with cached items.

USB drive for an update

If you use a USB drive for an update, it must be formatted with a FAT file system.

Risk engine reports

Any risk engine reports that you generated before you begin the upgrade task are not preserved. Export copies of the risk reports and save them locally by completing the following steps:

Log in to the local management interface.

Click Monitor Analysis and Diagnostics > Application Log Files.

Expand access_control and select the risk reports to export.

Click Export and save the files.

Database failover in a cluster

For information about how the upgrade affects database failover in a cluster, see http://www.ibm.com/support/docview.wss?uid=swg21666968.

Procedure

Choose one of the following upgrade methods and complete the steps:

Use the online update server.

Meet the following conditions:

A valid license is installed on the appliance.

The appliance has network connectivity to the online update server.

If you are upgrading a cluster, prepare the cluster as follows:

Log in to the local management interface.

Select Manage System Settings > Cluster Configuration > General.

Do not change the Primary Master setting.

Remove the Secondary Master and other high-availability cluster member settings.

Click Export and save the files.

Wait for the cluster to synchronize.

On the primary node, continue with the remaining steps to install the upgrade.

Log in to the local management interface.

Select Manage System Settings > Updates and Licensing > Available Updates.

Click Refresh.

Select the firmware update.

Click Install. The firmware update might take a long time to complete, depending on the bandwidth that is available to the appliance. After the update is successfully applied, the appliance automatically restarts.

If you installed the upgrade on a cluster, complete the installation:

Repeat steps 1.b through 1.f on each appliance in the cluster.

From the local management interface on the master node, update the cluster configuration to set the high-availability cluster members back to the settings you want.

Wait for the cluster to synchronize. The firmware for each appliance in the cluster is now upgraded and the cluster is operational.

Use the local management interface for a single appliance not in a cluster.

Download the .pkg file.

Log in to the local management interface.

Select Manage System Settings > Updates and Licensing > Available Updates.

Click Upload. The New Update window opens.

Click Select Update.

Browse to the .pkg file.

Click Open.

Click Save Configuration. The upload process might take several minutes.

Select the new firmware and click Install. The installation of the new firmware takes a few minutes. After the update is successfully applied, the appliance restarts automatically.

Use the local management interface for a cluster of appliances.

To upgrade a cluster configuration, you must change the cluster configuration temporarily before the upgrade so that changes can be written to the database.

Download the .pkg file.

Log in to the local management interface.

Select Manage System Settings > Cluster Configuration > General.

Do not change the Primary Master setting.

Remove the Secondary Master and other high-availability cluster member settings.

Click Export and save the files.

Wait for the cluster to synchronize.

Upload and install the firmware .pkg file on the primary node appliance. This step includes the automatic restart of the appliance.

Upload and install the firmware .pkg file on each appliance in the cluster, and restart each one.

From the local management interface on the master node, update the cluster configuration to set the high-availability cluster members back to the settings you want.

Wait for the cluster to synchronize. The firmware for each appliance in the cluster is now upgraded and the cluster is operational.

Use a USB drive. (Only for upgrading a hardware appliance.)

Download the .pkg file.

Copy the firmware update from the .pkg file to a USB flash drive.

Insert the USB flash drive into the hardware appliance.

Log in to the appliance console as admin or use Secure Shell.

Type updates and press Enter.

Type install and press Enter.

Select the following options:

Type 1 for a firmware update.

Type 1 to install the update from a USB drive.

Type YES to confirm that the USB drive is plugged into the appliance.

Type the index number to select the appliance firmware from the list.

Type YES to confirm the update and start the update process.

Note: The firmware update takes a few minutes to complete and the appliance automatically restarts.

What to do next

If you are upgrading an existing appliance, your Access Manager Platform is ready to use.

If you are upgrading an existing Access Manager for Mobile appliance or Advanced Access Control module to the current version, continue with the Upgrading configuration instructions.

If you are upgrading an existing Federation module to the current version, continue with the Upgrading configuration instructions.

Parent topic: Product overview

APARs fixed in this versionAPARs fixed in this versionAPARs fixed in this versionSeveral APARs were fixed with this version of the product.APARs fixedfixesAPARsFor the latest list, see http://www.ibm.com/support/docview.wss?uid=swg21984149. Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

APARs fixed in this version

Several APARs were fixed with this version of the product.

For the latest list, see http://www.ibm.com/support/docview.wss?uid=swg21984149.

Parent topic: Product overview

Compatibility with earlier versions of the productCompatibilityIBM Security Access Manager V9.0.* is compatible with previous versions of Security Access Manager for Web, Tivoli Access Manager for e-business, and Security Access Manager for Mobile.backwards compatibilitycompatible server versionscompatible interfacessession managementbackwards compatibilitysingle sign-onbackwards compatibilityThe Version 9.0.* policy server can communicate with some previous versions of Security Access Manager for Web, Tivoli Access Manager for e-business, and Security Access Manager for Mobile. The following compatibility with earlier versions is supported:Policy server compatibility with servers in prior versions Compatibility with single sign-on targets Limited compatibility with earlier versions for session managementPolicy server compatibility with servers in prior versionsThe Version 9.0.* policy server is compatible with prior releases of other servers, as specified in the following table. Compatibility with earlier versions of serversList of server types and the versions of the product that support them.Compatible serversCompatible versionsWebSEAL serverTivoli Access Manager for e-business, Version 6.1.1 and newerSecurity Access Manager for Web, Version 7.0 and newerAuthorization serverWeb plug-insVersion 9.0.* interfaces are compatible with prior releases of the product, as specified in the following table. Compatibility with earlier versions of interfacesList of interfaces and the versions of the product that support them.Version 9.0.* interfacesCompatible versionsC AdministrationTivoli Access Manager for e-business, Version 6.1 and newerSecurity Access Manager for Web, Version 7.0 and newerJava AdministrationExternal AuthenticationC AuthorizationJava Authorization Registry DirectTivoli Access Manager for e-business, Version 6.1.1 and newerSecurity Access Manager for Web, Version 7.0 and newerCompatibility with single sign-on targetsIBM Security Access Manager maintains compatibility with earlier versions for all single sign-on information that is sent over HTTP to applications behind WebSEAL junctions. Applications that are written to use single sign-on information that is supplied by previous versions of the product can use the same information that is provided by Version 9.0.*. This compatibility applies to both custom applications and IBM applications such as the Trust Association Interceptor. The Trust Association interface is a service provider API that enables the integration of third-party security service (for example, a reverse proxy) with WebSphere Application Server. Security Access Manager, version 9.0.*, is compatible with all versions of the Trust Association Interceptor.Limited compatibility with earlier versions of session management IBM Security Access Manager for Web Version 8.0 introduced the Distributed Session Cache. This component replaces the Session Management Server that was provided in previous releases of the product.The following limitations apply to deployments that combine IBM Security Access Manager, Version 9.0.* with prior versions, such as IBM Security Access Manager for Web, Version 7.0.0:You cannot use both the Distributed Session Cache and the Session Management Server in the same deployment.The IBM Security Access Manager Version 9.0.* WebSEAL server cannot communicate with the Session Management Server.IBM Security Access Manager for Web Version 7.0.* WebSEAL server can communicate with the Distributed Session Cache in Version 9.0, but only if IBM Security Access Manager for Web Fix Pack 2 (Version 7.0.0.2) or newer is applied. Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

Compatibility with earlier versions of the product

IBM Security Access Manager V9.0.* is compatible with previous versions of Security Access Manager for Web, Tivoli Access Manager for e-business, and Security Access Manager for Mobile.

The Version 9.0.* policy server can communicate with some previous versions of Security Access Manager for Web, Tivoli Access Manager for e-business, and Security Access Manager for Mobile. The following compatibility with earlier versions is supported:

Policy server compatibility with servers in prior versions

Compatibility with single sign-on targets

Limited compatibility with earlier versions for session management

Policy server compatibility with servers in prior versions

The Version 9.0.* policy server is compatible with prior releases of other servers, as specified in the following table.

Table 5. Compatibility with earlier versions of servers.

Compatible servers
Compatible versions

WebSEAL server

Tivoli Access Manager for e-business, Version 6.1.1 and newer

Security Access Manager for Web, Version 7.0 and newer

Authorization server

Web plug-ins

Version 9.0.* interfaces are compatible with prior releases of the product, as specified in the following table.

Table 6. Compatibility with earlier versions of interfaces.

Version 9.0.* interfaces
Compatible versions

C Administration

Tivoli Access Manager for e-business, Version 6.1 and newer

Security Access Manager for Web, Version 7.0 and newer

Java Administration

External Authentication

C Authorization

Java Authorization

Registry Direct

Tivoli Access Manager for e-business, Version 6.1.1 and newer

Security Access Manager for Web, Version 7.0 and newer

Compatibility with single sign-on targets

IBM® Security Access Manager maintains compatibility with earlier versions for all single sign-on information that is sent over HTTP to applications behind WebSEAL junctions. Applications that are written to use single sign-on information that is supplied by previous versions of the product can use the same information that is provided by Version 9.0.*.

This compatibility applies to both custom applications and IBM applications such as the Trust Association Interceptor. The Trust Association interface is a service provider API that enables the integration of third-party security service (for example, a reverse proxy) with WebSphere Application Server. Security Access Manager, version 9.0.*, is compatible with all versions of the Trust Association Interceptor.

Limited compatibility with earlier versions of session management

IBM Security Access Manager for Web Version 8.0 introduced the Distributed Session Cache. This component replaces the Session Management Server that was provided in previous releases of the product.

The following limitations apply to deployments that combine IBM Security Access Manager, Version 9.0.* with prior versions, such as IBM Security Access Manager for Web, Version 7.0.0:

You cannot use both the Distributed Session Cache and the Session Management Server in the same deployment.

The IBM Security Access Manager Version 9.0.* WebSEAL server cannot communicate with the Session Management Server.

IBM Security Access Manager for Web Version 7.0.* WebSEAL server can communicate with the Distributed Session Cache in Version 9.0, but only if IBM Security Access Manager for Web Fix Pack 2 (Version 7.0.0.2) or newer is applied.

Parent topic: Product overview

Documentation updates for known limitationsKnown limitationsKnown limitationsYou can view the known software limitations, problems, and workarounds on the IBM® Security Access Manager Support site.documentation updatesknown limitationsThe Support site describes not only the limitations and problems that exist when the product is released, but also any additional items that are found after product release. As limitations and problems are discovered and resolved, the IBM Software Support team updates the online knowledge base. By searching the knowledge base, you can find workarounds or solutions to problems that you experience. Also, check the TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager. topics.Known limitations for Security Access Manager The embedded LDAP server does not support TLS v1.2.The embedded LDAP server does not currently support connections over TLS v1.2. Due to this limitation, the embedded LDAP server is not supported for any production deployments that require NIST SP800-131a strict mode. Under the NIST SP800-131a strict mode, the SSL connection to the embedded LDAP server that is running on the secured port 636 fails. The SSL connection fails because the embedded LDAP server does not support TLS v1.2 and strict mode permits only TLS v1.2. To avoid this issue, do not set the nist.sp800-131a.strict advanced tuning parameter to true.A system error is displayed briefly when the Mozilla Firefox browser is refreshed. When you use the Mozilla Firefox browser to access the local management interface, sometimes a system error is displayed briefly during a browser refresh. This error is displayed because the browser refresh causes an XMLHttpRequest (XHR) request to be canceled before the request finishes. The error does not indicate impact to normal operations and can be ignored.Unable to remove local users or groups from authorization roles with Mozilla Firefox on Mac OS X. When you use the local management interface through a Mozilla Firefox browser version on a Mac OS X system, you might not be able to remove a user or group from an authorization role. On the Management Authorization page of the local management interface, when you click Edit, the Edit Local Members window is displayed. To remove a user or group, normally you uncheck the check box for that user or group and then click OK to save the changes. However, if you use Firefox on Mac OS X to complete such operation, the browser does not properly recognize the change and does not display any error messages. The user or group list remains unchanged after you click OK. To avoid such issue on Mac OS X, you have two options: Use a different browser to access the local management interface.Use the REST API. See the REST API documentation and browse to Manage: System SettingsSystem SettingsManagement AuthorizationUpdating an authorization role.Lower throughput observed with certificate revocation list enabledEnabling certificate revocation list (CRL) validation might result in a lower throughput from the system. If your certificate does not have a CRL, you might want to disable CRL checking by using the advanced configuration parameter kess.crlEnabled. Alternatively, you might want to reduce the frequency of CRL checking by using the advanced configuration parameter kess.crlInterval.Client certificate authentication for federated directories is not supported for UsernameTokenSTSModuleWhen you configure a federated directory, do not select a client certificate.In rare circumstances, an OAuth access token validation might fail.These instances have been observed very shortly after a restart of the Advanced Access Control runtime server. The symptoms and conditions include: Restart the Advanced Access Control runtime server.Execute an OAuth flow, such as the Resource Owner Password Credential flow, to obtain a valid access and refresh token pair. Attempt to use the access token to access a resource that is protected by the API Definition associated with the OAuth client that has been granted the access token. Step 3 has been observed to fail on some rare occasions. The cause is due to delayed restart initialization of some internal Advanced Access Control runtime components. Normal successful processing has been observed when the request for the protected resource in step 3 is resubmitted.Junction type for Security Access Manager Oracle PeopleSoft PeopleTools integrationWhen you access the PeopleSoft Workcenter Dashboard via WebSEAL using a standard junction type, the dashboard is not displayed correctly. The browser issues a message "Only secure content is displayed" with a button "Show all content". When this button is clicked, an Oracle authentication login panel is displayed. Note that the full URI of the server is used instead of just the junction name. Because the content contains an absolute address that WebSEAL cannot filter when a standard junction type is used, for example: <DIV id="ptasjs1"> http://hostaddress/cs/path/cache /PT_PORTAL_UTIL_JS_MIN_1.js</DIV> In this case, a virtual host junction type must be adopted to negate the limitations associated with the use of standard junction script filtering.Tooltips display issueTooltips might not display if you use the keyboard (for example, the Tab key) to navigate to a field. Tooltips are displayed properly when you use a mouse to navigate to the field.Creating PIP resource when the server connection for database and LDAP is not available returns the wrong response.For example, when you use the following command:curl -k -b whatigot -s -S --ciphers "DES-CBC3-SHA" -X "POST" -H "Accept:application/json" -H "Content-Type: application/json" --data-binary "{\"name\":\"tldap1234\",\"description\":\"\"\"attributes\":[{\"name\":\"trusteer.pinpoint.csid\",\"selector\":\"wrongtestLdap\"}]\"type\":\"LDAP\",\"predefined\":false,\"properties\":[{\"datatype\":\"String\",\"readOnly\":false,\"sensitive\":false,\"value\":\"objectclass=abc\",\"key\":\"searchBaseDN\"},{\"datatype\":\"String\",\"readOnly\":false,\"sensitive\":false,\"value\":\"cn=*\",\"key\":\"searchFilter\"},{\"datatype\":\"String\",\"readOnly\":false,\"sensitive\":false,\"value\":\"0cdebb0c-49d9-4179-a47a-52f759a4ff57\",\"key\":\"dataSource\"}]}" --user admin:admin -D whatigot "https://{appliance_host}/iam/access/v8/pips/"The expected response is as follows:HTTP/1.1 400 Bad RequestBut the actual response is as follows:HTTP/1.1 201 CreatedThe error message "illegal character" when you modify an SSO rule is always displayed in English.The error message "illegal character" is always displayed in English no matter which locale your browser uses.Audit events cannot be sent to the remote syslog server if certain information is not provided.If you choose to send the audit events to a remote machine, you must specify the correct details on the Audit Configuration page for host, port, protocol, and certificates. Otherwise, the audit events cannot be sent to the remote machine. Attribute sources that are being used by a federation or partner is deletable.Users can accidentally delete attribute sources that are in use by a federation or partner. Such operation causes errors to the federation. You must ensure that an attribute source is not in use before you delete it.Federation Module: The email address name ID format requires a mapping ruleIf you use an email address name ID format in a SAML 2.0 federation, you must set the type of STS Universal User attribute, whose name is "name", to: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"You can accomplish this by using a mapping rule. Following is an example:// Get the current principal name. var principalName = stsuu.getPrincipalName(); // Set the type of principal name attribute "name" to //"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress". stsuu.addPrincipalAttribute(new Attribute("name", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", principalName));Personal certificates are not included in the list of selections when you choose certificates to use for encryption or signature validation with the SAML 2.0 partner management GUIIf you use the local management interface to choose certificates to be used for encryption or signature validation, only signer certificates are available for selection. Personal certificates are not included in the list of selections. A work-around is to use the REST API for such operations.The upgrade from Security Access Manager 8.0, 8.0.0.1, and 8.0.0.2 does not correctly migrate the authentication module policies for Security Access Manager for Mobile. The work-around is to create the default set of authentication policies with the local management interface or REST API. The following link creates a customized query of the live Support knowledge base for items specific to IBM® Security Access Manager, Version 9.0, and its fix packs. IBM Security Access Manager technical documents You can also create your own search query on the IBM Support Portal. For example: Go to the IBM Support Portal:http://www.ibm.com/support/entry/portal/supportIn the "Search support and downloads" field, enter: Access Manager. Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

Documentation updates for known limitations

You can view the known software limitations, problems, and workarounds on the IBM® Security Access Manager Support site.

The Support site describes not only the limitations and problems that exist when the product is released, but also any additional items that are found after product release. As limitations and problems are discovered and resolved, the IBM Software Support team updates the online knowledge base. By searching the knowledge base, you can find workarounds or solutions to problems that you experience.

Also, check the Troubleshooting topics.

Known limitations for Security Access Manager

The embedded LDAP server does not support TLS v1.2.

The embedded LDAP server does not currently support connections over TLS v1.2. Due to this limitation, the embedded LDAP server is not supported for any production deployments that require NIST SP800-131a strict mode.

Under the NIST SP800-131a strict mode, the SSL connection to the embedded LDAP server that is running on the secured port 636 fails. The SSL connection fails because the embedded LDAP server does not support TLS v1.2 and strict mode permits only TLS v1.2.

To avoid this issue, do not set the nist.sp800-131a.strict advanced tuning parameter to true.

A system error is displayed briefly when the Mozilla Firefox browser is refreshed.

When you use the Mozilla Firefox browser to access the local management interface, sometimes a system error is displayed briefly during a browser refresh.

This error is displayed because the browser refresh causes an XMLHttpRequest (XHR) request to be canceled before the request finishes. The error does not indicate impact to normal operations and can be ignored.

Unable to remove local users or groups from authorization roles with Mozilla Firefox on Mac OS X.

When you use the local management interface through a Mozilla Firefox browser version on a Mac OS X system, you might not be able to remove a user or group from an authorization role.

On the Management Authorization page of the local management interface, when you click Edit, the Edit Local Members window is displayed. To remove a user or group, normally you uncheck the check box for that user or group and then click OK to save the changes. However, if you use Firefox on Mac OS X to complete such operation, the browser does not properly recognize the change and does not display any error messages. The user or group list remains unchanged after you click OK.

To avoid such issue on Mac OS X, you have two options:

Use a different browser to access the local management interface.

Use the REST API. See the REST API documentation and browse to Manage: System Settings > System Settings > Management Authorization > Updating an authorization role.

Lower throughput observed with certificate revocation list enabled

Enabling certificate revocation list (CRL) validation might result in a lower throughput from the system. If your certificate does not have a CRL, you might want to disable CRL checking by using the advanced configuration parameter kess.crlEnabled. Alternatively, you might want to reduce the frequency of CRL checking by using the advanced configuration parameter kess.crlInterval.

Client certificate authentication for federated directories is not supported for UsernameTokenSTSModule

When you configure a federated directory, do not select a client certificate.

In rare circumstances, an OAuth access token validation might fail.

These instances have been observed very shortly after a restart of the Advanced Access Control runtime server. The symptoms and conditions include:

Restart the Advanced Access Control runtime server.

Execute an OAuth flow, such as the Resource Owner Password Credential flow, to obtain a valid access and refresh token pair.

Attempt to use the access token to access a resource that is protected by the API Definition associated with the OAuth client that has been granted the access token.

Step 3 has been observed to fail on some rare occasions. The cause is due to delayed restart initialization of some internal Advanced Access Control runtime components. Normal successful processing has been observed when the request for the protected resource in step 3 is resubmitted.

Junction type for Security Access Manager Oracle PeopleSoft PeopleTools integration

When you access the PeopleSoft Workcenter Dashboard via WebSEAL using a standard junction type, the dashboard is not displayed correctly. The browser issues a message "Only secure content is displayed" with a button "Show all content". When this button is clicked, an Oracle authentication login panel is displayed.

Note that the full URI of the server is used instead of just the junction name. Because the content contains an absolute address that WebSEAL cannot filter when a standard junction type is used, for example:

<DIV id="ptasjs1"> http://hostaddress/cs/path/cache
/PT_PORTAL_UTIL_JS_MIN_1.js</DIV>

In this case, a virtual host junction type must be adopted to negate the limitations associated with the use of standard junction script filtering.

Tooltips display issue

Tooltips might not display if you use the keyboard (for example, the Tab key) to navigate to a field. Tooltips are displayed properly when you use a mouse to navigate to the field.

Creating PIP resource when the server connection for database and LDAP is not available returns the wrong response.

For example, when you use the following command:

curl -k -b whatigot -s -S --ciphers "DES-CBC3-SHA" -X "POST" -H "Accept:application/json" -H "Content-Type: application/json" --data-binary "{\"name\":\"tldap1234\",\"description\":\"\"\"attributes\":[{\"name\":\"trusteer.pinpoint.csid\",\"selector\":\"wrongtestLdap\"}]\"type\":\"LDAP\",\"predefined\":false,\"properties\":[{\"datatype\":\"String\",\"readOnly\":false,\"sensitive\":false,\"value\":\"objectclass=abc\",\"key\":\"searchBaseDN\"},{\"datatype\":\"String\",\"readOnly\":false,\"sensitive\":false,\"value\":\"cn=*\",\"key\":\"searchFilter\"},{\"datatype\":\"String\",\"readOnly\":false,\"sensitive\":false,\"value\":\"0cdebb0c-49d9-4179-a47a-52f759a4ff57\",\"key\":\"dataSource\"}]}" --user admin:admin -D whatigot "https://{appliance_host}/iam/access/v8/pips/"

The expected response is as follows:

HTTP/1.1 400 Bad Request

But the actual response is as follows:

HTTP/1.1 201 Created

The error message "illegal character" when you modify an SSO rule is always displayed in English.

The error message "illegal character" is always displayed in English no matter which locale your browser uses.

Audit events cannot be sent to the remote syslog server if certain information is not provided.

If you choose to send the audit events to a remote machine, you must specify the correct details on the Audit Configuration page for host, port, protocol, and certificates. Otherwise, the audit events cannot be sent to the remote machine.

Attribute sources that are being used by a federation or partner is deletable.

Users can accidentally delete attribute sources that are in use by a federation or partner. Such operation causes errors to the federation. You must ensure that an attribute source is not in use before you delete it.

Federation Module: The email address name ID format requires a mapping rule

If you use an email address name ID format in a SAML 2.0 federation, you must set the type of STS Universal User attribute, whose name is "name", to:

"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

You can accomplish this by using a mapping rule. Following is an example:

// Get the current principal name.
var principalName = stsuu.getPrincipalName();
// Set the type of principal name attribute "name" to
//"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress".
stsuu.addPrincipalAttribute(new Attribute("name",
"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", principalName));

Personal certificates are not included in the list of selections when you choose certificates to use for encryption or signature validation with the SAML 2.0 partner management GUI

If you use the local management interface to choose certificates to be used for encryption or signature validation, only signer certificates are available for selection. Personal certificates are not included in the list of selections. A work-around is to use the REST API for such operations.

The upgrade from Security Access Manager 8.0, 8.0.0.1, and 8.0.0.2 does not correctly migrate the authentication module policies for Security Access Manager for Mobile.

The work-around is to create the default set of authentication policies with the local management interface or REST API.

The following link creates a customized query of the live Support knowledge base for items specific to IBM® Security Access Manager, Version 9.0, and its fix packs.

IBM Security Access Manager technical documents

You can also create your own search query on the IBM Support Portal. For example:

Go to the IBM Support Portal:http://www.ibm.com/support/entry/portal/support

In the "Search support and downloads" field, enter: Access Manager.

Parent topic: Product overview

Security Access Manager appliance FRU/CRU documentation in PDF formatDocumentation in PDF format for IBM Security Access Manager Field Replacement Unit (FRU) parts and Customer Replacement Unit (CRU) parts is available for download.See http://public.dhe.ibm.com/software/security/products/infrastructure_protection/FRU_CRU/docs/ISAM_V9.0.Product overviewThe Product overview includes a description of the new features and important information about this specific release of the product.

Security Access Manager appliance FRU/CRU documentation in PDF format

Documentation in PDF format for IBM Security Access Manager Field Replacement Unit (FRU) parts and Customer Replacement Unit (CRU) parts is available for download.

See http://public.dhe.ibm.com/software/security/products/infrastructure_protection/FRU_CRU/docs/ISAM_V9.0.

Parent topic: Product overview

ConfiguringConfiguring is an activity in which you modify the default settings of various parts of the product.ConfiguringThe Configuring topics are geared towards your initial configuration and customization of the product, although you can adjust the product at any time.User registry configurationUse the topics in this hierarchy to configure user registries for IBM Security Access Manager.Web Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Federation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.

Configuring

Configuring is an activity in which you modify the default settings of various parts of the product.

The Configuring topics are geared towards your initial configuration and customization of the product, although you can adjust the product at any time.

User registry configuration
Use the topics in this hierarchy to configure user registries for IBM Security Access Manager.

Web Reverse Proxy configuration
Use the topics in this hierarchy to configure the Web Reverse Proxy.

Advanced Access Control configuration
Use the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Federation configuration
Use the topics in this hierarchy to configure the Federation features, if you have activated this module.

User registry configurationUse the topics in this hierarchy to configure user registries for IBM Security Access Manager.User registry configuration This section provides configuration procedures for user registries.ConfiguringConfiguring is an activity in which you modify the default settings of various parts of the product.Supported registriesSecurity Access Manager supports several user registries and their supported operating systems.User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.Security Access Manager management domainsIf you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources. Security Directory Server proxy environment setupA Security Directory Server proxy is a special type of IBM Security Directory Server that provides request routing, load balancing, fail over, distributed authentication and support for distributed/membership groups and partitioning of containers.Security Access Manager registry adapter for WebSphere federated repositoriesThe Security Access Manager registry adapter for WebSphere federated repositories uses the Security Access Manager Registry Direct Java API to perform registry-related operations.

User registry configuration

Use the topics in this hierarchy to configure user registries for IBM Security Access Manager.

User registry configuration This section provides configuration procedures for user registries.

Supported registries
Security Access Manager supports several user registries and their supported operating systems.

User registry server installation and configuration
Set up a registry server for use with Security Access Manager so that you can establish a management domain.

Security Access Manager management domains
If you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources.

Security Directory Server proxy environment setup
A Security Directory Server proxy is a special type of IBM® Security Directory Server that provides request routing, load balancing, fail over, distributed authentication and support for distributed/membership groups and partitioning of containers.

Security Access Manager registry adapter for WebSphere federated repositories
The Security Access Manager registry adapter for WebSphere® federated repositories uses the Security Access Manager Registry Direct Java™ API to perform registry-related operations.

Parent topic: Configuring

Supported registriesSupported registriesSupported registriesSecurity Access Manager supports several user registries and their supported operating systems.user registriessupported See the IBM Security Access Manager Knowledge Center or Technotes in the support knowledge database to ensure that you reviewed the most recent release information, including product requirementsYou can view Software Product Compatibility Reports that list the system requirements and appliance specifications for the product., disk space requirements, and known defects and limitations. Ensure that all necessary operating system patches are installed.user registriesSecurity Directory ServersupportSecurity Directory Serverregistry supportIBM Security Directory ServerSecurity Access Manager supports the use of IBM Security Directory Server as a registry. Take note of the following information: IBM Security Directory Server is included with Security Access Manager.IBM Security Directory Server client is required when an LDAP user registry is selected during installation.You can install the IBM Security Directory Server client on the same system as a previous version (such as 6.3, 6.2, 6.1, or 6.0) of the IBM Security Directory Server client.If you have an existing IBM Security Directory Server that you want to use for Security Access Manager, ensure that you upgrade the server to a supported level.user registriesIBM z/OSsupportSecurity Directory Server for z/OSregistry supportIBM Security Directory Server for z/OSSecurity Access Manager supports the use of IBM Security Directory Server for z/OS. For product information, see the z/OS Internet Library.Customers can also obtain softcopy publications on DVD z/OS: Collection, SK3T-4269.user registriesActive DirectorysupportMicrosoft Active Directoryregistry supportMicrosoft Active DirectoryActive Directory can only be used to authenticate users. A separate user registry must be used to store the Security Access Manager suffix.Active Directory users can run Security Access Manager on all platforms that are currently supported in the Security Access Manager 7.0 product.user registriesADLDSsupportMicrosoft Active Directory Lightweight Directory Serviceregistry supportMicrosoft Active Directory Lightweight Directory Service (ADLDS)Security Access Manager supports the use of Microsoft Active Directory Lightweight Directory Service as a user registry. ADLDS users can run Security Access Manager with supported versions of Windows Server. See the Security Access Manager Release Notes in the IBM Knowledge Center for the list of supported versions.user registriesSun Java System Directory ServersupportSun Java System Directory Serverregistry supportOracle Directory ServerSun Java System Directory Server Sun Java System Directory ServerSecurity Access Manager supports the use of the Sun Java System Directory Server as a user registry. For installation information, consult the product documentation that came with your server. Sun Java System Directory Server product documentation is available at:http://docs.sun.com/app/docs/prod/entsysuser registriesNovell eDirectorysupportNovell eDirectory serverregistry supportNovell eDirectorySecurity Access Manager supports the use of Novell eDirectory as a user registry. For installation information, consult the product documentation that came with your Novell eDirectory server. Novell eDirectory product documentation is available at:http://www.novell.com/documentation/a-z.htmlThe latest patches to these products are available at:http://support.novell.com/patches.htmlIf you have an existing Novell eDirectory server that you want to use for Security Access Manager, ensure that you upgrade the server to a supported level.User registry configurationUse the topics in this hierarchy to configure user registries for IBM Security Access Manager.

Supported registries

Security Access Manager supports several user registries and their supported operating systems.

See the IBM Security Access Manager Knowledge Center or Technotes in the support knowledge database to ensure that you reviewed the most recent release information, including product requirements, disk space requirements, and known defects and limitations. Ensure that all necessary operating system patches are installed.

IBM Security Directory Server

Security Access Manager supports the use of IBM® Security Directory Server as a registry.

Take note of the following information:

IBM Security Directory Server is included with Security Access Manager.

IBM Security Directory Server client is required when an LDAP user registry is selected during installation.

You can install the IBM Security Directory Server client on the same system as a previous version (such as 6.3, 6.2, 6.1, or 6.0) of the IBM Security Directory Server client.

Attention: If you have an existing IBM Security Directory Server that you want to use for Security Access Manager, ensure that you upgrade the server to a supported level.

IBM Security Directory Server for z/OS

Security Access Manager supports the use of IBM Security Directory Server for z/OS®.

For product information, see the z/OS Internet Library.

Customers can also obtain softcopy publications on DVD z/OS: Collection, SK3T-4269.

Microsoft Active Directory

Active Directory can only be used to authenticate users. A separate user registry must be used to store the Security Access Manager suffix.

Active Directory users can run Security Access Manager on all platforms that are currently supported in the Security Access Manager 7.0 product.

Microsoft Active Directory Lightweight Directory Service (ADLDS)

Security Access Manager supports the use of Microsoft Active Directory Lightweight Directory Service as a user registry.

ADLDS users can run Security Access Manager with supported versions of Windows Server. See the Security Access Manager Release Notes in the IBM Knowledge Center for the list of supported versions.

Sun Java System Directory Server

Security Access Manager supports the use of the Sun Java™ System Directory Server as a user registry.

For installation information, consult the product documentation that came with your server. Sun Java System Directory Server product documentation is available at:

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

Novell eDirectory

Security Access Manager supports the use of Novell eDirectory as a user registry.

For installation information, consult the product documentation that came with your Novell eDirectory server. Novell eDirectory product documentation is available at:

http://www.novell.com/documentation/a-z.html

The latest patches to these products are available at:

http://support.novell.com/patches.html

Attention: If you have an existing Novell eDirectory server that you want to use for Security Access Manager, ensure that you upgrade the server to a supported level.

Parent topic: User registry configuration

User registry server installation and configurationUser registry server installation and configurationUser registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.user registriessetting upReview the information in user registry considerationsSecurity Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries. .To install and configure a registry, do one of the following tasks: To install and configure IBM Security Directory Server version 6.4, which is included with Security Access Manager, follow the instructions in the following tech note: http://www.ibm.com/support/docview.wss?uid=swg21983164The instructions in the following topics are for Directory Server version 6.3.Installing Security Directory Server with a wizardInstall IBM Security Directory Server by using the installation wizard in the typical installation path. It uses default values and automatically installs all the required Security Directory Server components for Security Access Manager. Installing Security Directory Server with a script (AIX, Linux, Solaris)Use the script file to automate the installation of Security Directory Server.Installing Security Directory Server with a script (Windows)Use the script file to automate the installation of Security Directory Server.Installing Security Directory Server with Launchpad (Windows)Use the Launchpad installation method to install Security Directory Server and its prerequisite software on a computer that is running the Windows operating system. You also can consult the IBM Security Directory Server documentation available on the web at:http://www.ibm.com/software/tivoli/products/directory-serverTo install a supported registry other than IBM Security Directory Server, use the registry product's documentation. For a list of supported registries, see Product requirementsYou can view Software Product Compatibility Reports that list the system requirements and appliance specifications for the product.. Ensure that all necessary operating system patches are installed. The IBM Security Directory Server client must be used as the registry client for LDAP-based user registries.To use an existing registry server with Security Access Manager, ensure that you upgraded the server to a version that is supported by this release of Security Access Manager. For other supported registries, consult the registry product's documentation. Follow the instructions to configure your registry for use with Security Access Manager.User registry configurationUse the topics in this hierarchy to configure user registries for IBM Security Access Manager.User registry considerationsSecurity Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries. Maximum lengths for names by user registryThe maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry in the environment.Security Directory Server installation and configurationSecurity Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.IBM Tivoli Directory Server for z/OS installation and configurationPrepare the LDAP server on z/OS for Security Access Manager.Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.Novell eDirectory installation and configurationYou can set up Novell eDirectory as the user registry in your Security Access Manager environment.Installing and configuring the Sun Java System Directory ServerYou can use a supported version of Sun Java System Directory Server as the user registry for Security Access Manager.

User registry server installation and configuration

Set up a registry server for use with Security Access Manager so that you can establish a management domain.

Review the information in user registry considerations.

To install and configure a registry, do one of the following tasks:

To install and configure IBM® Security Directory Server version 6.4, which is included with Security Access Manager, follow the instructions in the following tech note: http://www.ibm.com/support/docview.wss?uid=swg21983164

The instructions in the following topics are for Directory Server version 6.3.

Installing Security Directory Server with a wizard

Installing Security Directory Server with a script (AIX, Linux, Solaris)

Installing Security Directory Server with a script (Windows)

Installing Security Directory Server with Launchpad (Windows)

You also can consult the IBM Security Directory Server documentation available on the web at:

http://www.ibm.com/software/tivoli/products/directory-server

To install a supported registry other than IBM Security Directory Server, use the registry product's documentation. For a list of supported registries, see Product requirements. Ensure that all necessary operating system patches are installed.

Note: The IBM Security Directory Server client must be used as the registry client for LDAP-based user registries.

To use an existing registry server with Security Access Manager, ensure that you upgraded the server to a version that is supported by this release of Security Access Manager. For other supported registries, consult the registry product's documentation. Follow the instructions to configure your registry for use with Security Access Manager.

User registry considerations
Security Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries.

Maximum lengths for names by user registry
The maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry in the environment.

Security Directory Server installation and configuration
Security Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.

IBM Tivoli Directory Server for z/OS installation and configuration
Prepare the LDAP server on z/OS® for Security Access Manager.

Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration
You must prepare the AD LDS server for use with Security Access Manager.

Novell eDirectory installation and configuration
You can set up Novell eDirectory as the user registry in your Security Access Manager environment.

Installing and configuring the Sun Java System Directory Server
You can use a supported version of Sun Java System Directory Server as the user registry for Security Access Manager.

Parent topic: User registry configuration

User registry considerationsUser registry considerationsUser registry considerationsSecurity Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries. user registriesdifferencesuser registriesLDAPdifferencesuser registriesLDAPuser registry typesSupported LDAP user registriesSecurity Access Manager supports the following LDAP user registries: Security Directory ServerIBM z/OS Security Server LDAP ServerNovell eDirectory ServerSun Java System Directory ServerMicrosoft Active Directory Lightweight Directory Services (ADLDS)Name limitations for supported registriesReview this information before you configure a user registry for your environment. Avoid forward slashes (/) in names for users and groups when you define that name with distinguished names strings. Each user registry treats this character differently. Avoid leading and trailing blanks in user and group names. Each user registry treats blanks differently.LDAP configuration informationReview this information before you configure an LDAP registry for your environment. Security Access Manager requires no configuration steps so that it supports LDAP's Password Policy. It does not assume the existence or non-existence of LDAP's Password Policy. Security Access Manager enforces its own Password Policy first. Security Access Manager attempts to update password in LDAP only when the provided password passes Security Access Manager's own Password Policy check. A Security Access Manager tries to accommodate LDAP' Password Policy with the return code that it receives from LDAP during a password-related update. If Security Access Manager can map this return code without any ambiguity with the corresponding Security Access Manager error code, it does so and returns an error message. To take advantage of the multi-domain support in Security Access Manager, you must use an LDAP user registry. With an LDAP user registry, the capability to own global sign-on credentials must be explicitly granted to a user. After this capability is granted, you can remove it. Leading and trailing blanks in user names and group names are ignored in an LDAP user registry in a Security Access Manager secure domain. To ensure consistent processing regardless of the user registry, define user names and group names without leading or trailing blanks. Attempting to add a single duplicate user to a group does not produce an error in an LDAP user registry. The Security Access Manager authorization API provides a credentials attribute entitlements service. This service is used to retrieve user attributes from a user registry. When this service is used with an LDAP user registry, the retrieved attributes can be string data or binary data.LDAP data formatThe following LDAP data formats are available for user and group tracking information.MinimalMinimal format uses fewer LDAP objects to maintain user and group tracking information. Using this format reduces the size of your user registry information because minimal user and group tracking information is stored.StandardStandard format uses more LDAP objects to maintain user and group tracking. This format was also used in versions of IBM Tivoli Access Manager for e-business before version 6.0.If the user and group information in the LDAP registry is used by other Security Access Manager products, such as IBM Tivoli Access Manager for Operating Systems or IBM Tivoli Federated Identity Manager, the same LDAP data format must be used for all products.Sun Java System Directory Server look-through limitWhen the directory server is installed, the default value for look-through limit is 5000. If the user registry contains more entries than the defined look-through limit, the directory server might return the following status that Security Access Manager treats as an error:LDAP_ADMINLIMIT_EXCEEDEDYou can modify this value from the Sun Java™ System Directory Server Console:Select the Configuration tab. Expand the Data entry. Select Database Settings. Select the LDBM Plug-in Settings tab. In the Look-through Limit field, type one of the following responses:The maximum number of entries that you want the server to check in response to the search, or type-1 to define no maximum limit.If you bind the directory as the Directory Manager, the look-through limit is unlimited and overrides any settings that are specified in this field.Microsoft Active Directory Lightweight Directory Services (AD LDS) Review this information before you configure a Microsoft AD LDS registry for your environment. For IBM Security Access Manager version 9, there is no option for standard or minimal data model. Standard data model is only available for a migrated policy server. Because AD LDS requires a single naming attribute for creating LDAP objects, AD LDS requires the minimal data model. Regardless of which data model you choose, Security Access Manager always uses the minimal data model if you select AD LDS as the user registry. The common name (cn) attribute is a single-value attribute and can store only one value. The AD LDS registry requires the value of cn to be the same as the cn naming attribute in the distinguished name (dn) attribute. When you create a user or group in Security Access Manager, specify the same value for cn as the cn naming attribute in the dn. Security Access Manager ignores the value of the cn attribute if it is different from the value of the cn naming attribute in the dn. For example, you cannot use the following command to create a user because the value of the cn attribute, fred, is different from the cn naming attribute in the dn, user1:pdadmin user create user1 cn=user1,o=ibm,c=us fred smith password1User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.

User registry considerations

Security Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries.

Supported LDAP user registries

Security Access Manager supports the following LDAP user registries:

Security Directory Server

IBM® z/OS® Security Server LDAP Server

Novell eDirectory Server

Sun Java™ System Directory Server

Microsoft Active Directory Lightweight Directory Services (ADLDS)

Name limitations for supported registries

Review this information before you configure a user registry for your environment.

Avoid forward slashes (/) in names for users and groups when you define that name with distinguished names strings. Each user registry treats this character differently.

Avoid leading and trailing blanks in user and group names. Each user registry treats blanks differently.

LDAP configuration information

Review this information before you configure an LDAP registry for your environment.

Security Access Manager requires no configuration steps so that it supports LDAP's Password Policy. It does not assume the existence or non-existence of LDAP's Password Policy.

Security Access Manager enforces its own Password Policy first. Security Access Manager attempts to update password in LDAP only when the provided password passes Security Access Manager's own Password Policy check.

A Security Access Manager tries to accommodate LDAP' Password Policy with the return code that it receives from LDAP during a password-related update.

If Security Access Manager can map this return code without any ambiguity with the corresponding Security Access Manager error code, it does so and returns an error message.

To take advantage of the multi-domain support in Security Access Manager, you must use an LDAP user registry.

With an LDAP user registry, the capability to own global sign-on credentials must be explicitly granted to a user. After this capability is granted, you can remove it.

Leading and trailing blanks in user names and group names are ignored in an LDAP user registry in a Security Access Manager secure domain. To ensure consistent processing regardless of the user registry, define user names and group names without leading or trailing blanks.

Attempting to add a single duplicate user to a group does not produce an error in an LDAP user registry.

The Security Access Manager authorization API provides a credentials attribute entitlements service. This service is used to retrieve user attributes from a user registry. When this service is used with an LDAP user registry, the retrieved attributes can be string data or binary data.

LDAP data format

The following LDAP data formats are available for user and group tracking information.

Minimal

Minimal format uses fewer LDAP objects to maintain user and group tracking information. Using this format reduces the size of your user registry information because minimal user and group tracking information is stored.

Standard

Standard format uses more LDAP objects to maintain user and group tracking. This format was also used in versions of IBM Tivoli® Access Manager for e-business before version 6.0.

If the user and group information in the LDAP registry is used by other Security Access Manager products, such as IBM Tivoli Access Manager for Operating Systems or IBM Tivoli Federated Identity Manager, the same LDAP data format must be used for all products.

Sun Java System Directory Server look-through limit

When the directory server is installed, the default value for look-through limit is 5000. If the user registry contains more entries than the defined look-through limit, the directory server might return the following status that Security Access Manager treats as an error:

LDAP_ADMINLIMIT_EXCEEDED

You can modify this value from the Sun Java™ System Directory Server Console:

Select the Configuration tab.

Expand the Data entry.

Select Database Settings.

Select the LDBM Plug-in Settings tab.

In the Look-through Limit field, type one of the following responses:

The maximum number of entries that you want the server to check in response to the search, or type

-1 to define no maximum limit.

Note: If you bind the directory as the Directory Manager, the look-through limit is unlimited and overrides any settings that are specified in this field.

Microsoft Active Directory Lightweight Directory Services (AD LDS)

Review this information before you configure a Microsoft AD LDS registry for your environment.

For IBM Security Access Manager version 9, there is no option for standard or minimal data model. Standard data model is only available for a migrated policy server. Because AD LDS requires a single naming attribute for creating LDAP objects, AD LDS requires the minimal data model. Regardless of which data model you choose, Security Access Manager always uses the minimal data model if you select AD LDS as the user registry.

The common name (cn) attribute is a single-value attribute and can store only one value. The AD LDS registry requires the value of cn to be the same as the cn naming attribute in the distinguished name (dn) attribute. When you create a user or group in Security Access Manager, specify the same value for cn as the cn naming attribute in the dn. Security Access Manager ignores the value of the cn attribute if it is different from the value of the cn naming attribute in the dn. For example, you cannot use the following command to create a user because the value of the cn attribute, fred, is different from the cn naming attribute in the dn, user1:

pdadmin user create user1 cn=user1,o=ibm,c=us fred smith password1

Parent topic: User registry server installation and configuration

Maximum lengths for names by user registryMaximum lengths for names by user registryMaximum lengths for names by user registryThe maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry in the environment.user registrieslength of user namesTable 1 shows the maximum lengths that are allowed for each user registry that is supported by Security Access Manager. Maintaining these maximum lengths ensures compatibility. Maximum lengths for names by user registry and the optimal length across user registriesuser registrymaximum valuesNameIBM Security Directory ServerIBM z/OS Security ServerNovell eDirectory ServerSun Java System Directory ServerMicrosoft Active Directory ServerActive Directory Lightweight Directory Service (ADLDS)Optimal lengthFirst name (LDAP CN)256256 64256646464Middle name128128128128646464Last name (surname)128128128128646464Registry UID (LDAP DN)102410241024102420481024255Security Access Manager user identity256256256256646464User passwordunlimitedunlimitedunlimitedunlimited256128256User description1024102410241024102410241024Group name256256256256646464Group description1024102410241024102410241024Single sign-on resource name2402402402406024060Single sign-on resource description1024102410241024102410241024Single sign-on user ID2402402402406024060Single sign-on passwordunlimitedunlimitedunlimitedunlimited256unlimited256Single sign-on group name2402402402406024060Single sign-on group description1024102410241024102410241024Action name1111111Action description, action typeunlimitedunlimitedunlimitedunlimitedunlimitedunlimited unlimitedObject name, object descriptionunlimitedunlimitedunlimitedunlimitedunlimitedunlimited unlimitedObject space name, object space descriptionunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedACL name, ACL descriptionsunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedPOP name, POP descriptionunlimitedunlimitedunlimitedunlimitedunlimitedunlimited unlimitedAlthough the maximum length of an Active Directory distinguished name (registry UID) is 2048, the maximum length of each relative distinguished name (RDN) is 64.If you configure Security Access Manager to use multiple Active Directory domains, the maximum length of the user identity and group name does not include the domain suffix. When you use multiple domains, the format of a user identity is user_id@domain_suffix. The maximum length of 64 applies only to the user_id portion. If you use an email address or other alternative format for the Security Access Manager user identity in the Active Directory, the maximum name length remains the same, but includes the suffix.suffixesin multiple domainsAlthough the lengths of some names can be of unlimited, excessive lengths can result in policy that is difficult to manage and might result in poor system performance. Choose maximum values that are logical for your environment.User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.

Maximum lengths for names by user registry

The maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry in the environment.

Table 7 shows the maximum lengths that are allowed for each user registry that is supported by Security Access Manager. Maintaining these maximum lengths ensures compatibility.

Table 7. Maximum lengths for names by user registry and the optimal length across user registries

Name | IBM® Security Directory Server | IBM z/OS® Security Server | Novell eDirectory Server | Sun Java™ System Directory Server | Microsoft Active Directory Server | Active Directory Lightweight Directory Service (ADLDS) | Optimal length
First name (LDAP CN) | 256 | 256 | 64 | 256 | 64 | 64 | 64
Middle name | 128 | 128 | 128 | 128 | 64 | 64 | 64
Last name (surname) | 128 | 128 | 128 | 128 | 64 | 64 | 64
Registry UID (LDAP DN) | 1024 | 1024 | 1024 | 1024 | 2048 | 1024 | 255
Security Access Manager user identity | 256 | 256 | 256 | 256 | 64 | 64 | 64
User password | unlimited | unlimited | unlimited | unlimited | 256 | 128 | 256
User description | 1024 | 1024 | 1024 | 1024 | 1024 | 1024 | 1024
Group name | 256 | 256 | 256 | 256 | 64 | 64 | 64
Group description | 1024 | 1024 | 1024 | 1024 | 1024 | 1024 | 1024
Single sign-on resource name | 240 | 240 | 240 | 240 | 60 | 240 | 60
Single sign-on resource description | 1024 | 1024 | 1024 | 1024 | 1024 | 1024 | 1024
Single sign-on user ID | 240 | 240 | 240 | 240 | 60 | 240 | 60
Single sign-on password | unlimited | unlimited | unlimited | unlimited | 256 | unlimited | 256
Single sign-on group name | 240 | 240 | 240 | 240 | 60 | 240 | 60
Single sign-on group description | 1024 | 1024 | 1024 | 1024 | 1024 | 1024 | 1024
Action name | 1 | 1 | 1 | 1 | 1 | 1 | 1
Action description, action type | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited
Object name, object description | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited
Object space name, object space description | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited
ACL name, ACL descriptions | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited
POP name, POP description | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited | unlimited

Although the maximum length of an Active Directory distinguished name (registry UID) is 2048, the maximum length of each relative distinguished name (RDN) is 64.

If you configure Security Access Manager to use multiple Active Directory domains, the maximum length of the user identity and group name does not include the domain suffix. When you use multiple domains, the format of a user identity is user_id@domain_suffix. The maximum length of 64 applies only to the user_id portion. If you use an email address or other alternative format for the Security Access Manager user identity in the Active Directory, the maximum name length remains the same, but includes the suffix.

Although the lengths of some names can be of unlimited, excessive lengths can result in policy that is difficult to manage and might result in poor system performance. Choose maximum values that are logical for your environment.

Parent topic: User registry server installation and configuration

Security Directory Server installation and configurationSecurity Directory Server installation and configurationSecurity Directory Server installation and configurationSecurity Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.Security Directory Serverinstallation overviewReview the information in user registry considerationsSecurity Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries. . Then, choose an installation method. If you use an existing registry server with Security Access Manager, ensure that you upgraded the server to a version that is supported by this release of Security Access Manager. For other supported registries, consult the registry product's documentation. Then, follow the instructions to configure your registry for use with Security Access Manager.User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.Installing Security Directory Server with a wizardInstall IBM Security Directory Server by using the installation wizard in the typical installation path. It uses default values and automatically installs all the required Security Directory Server components for Security Access Manager. Installing Security Directory Server with a script (AIX, Linux, Solaris)Use the script file to automate the installation of Security Directory Server.Installing Security Directory Server with a script (Windows)Use the script file to automate the installation of Security Directory Server.Installing Security Directory Server with Launchpad (Windows)Use the Launchpad installation method to install Security Directory Server and its prerequisite software on a computer that is running the Windows operating system.Configuring IBM Tivoli Directory Server for SSL accessEnable SSL to secure communication between the Tivoli Directory Server and the Security Access Manager components.

Security Directory Server installation and configuration

Security Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.

Review the information in user registry considerations. Then, choose an installation method. If you use an existing registry server with Security Access Manager, ensure that you upgraded the server to a version that is supported by this release of Security Access Manager. For other supported registries, consult the registry product's documentation. Then, follow the instructions to configure your registry for use with Security Access Manager.

Installing Security Directory Server with a wizard
Install IBM Security Directory Server by using the installation wizard in the typical installation path. It uses default values and automatically installs all the required Security Directory Server components for Security Access Manager.

Installing Security Directory Server with a script (AIX, Linux, Solaris)
Use the script file to automate the installation of Security Directory Server.

Installing Security Directory Server with a script (Windows)
Use the script file to automate the installation of Security Directory Server.

Installing Security Directory Server with Launchpad (Windows)
Use the Launchpad installation method to install Security Directory Server and its prerequisite software on a computer that is running the Windows operating system.

Configuring IBM Tivoli Directory Server for SSL access
Enable SSL to secure communication between the Tivoli® Directory Server and the Security Access Manager components.

Parent topic: User registry server installation and configuration

Installing Security Directory Server with a wizardInstalling Security Directory Server with a wizardInstalling Security Directory Server with a wizardInstall IBM Security Directory Server by using the installation wizard in the typical installation path. It uses default values and automatically installs all the required Security Directory Server components for Security Access Manager. DB2installation wizardSecurity Directory Serverinstallinguser registriesSecurity Directory Serversetting updirectory server instancecreatingThe information in this topic is for Directory Server version 6.3. Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0. If Security Directory Server packages, such as client packages, are already installed at a level greater than 6.3.0.0, remove the packages before you run the installation wizard.Complete the following tasks before you set up IBM Security Directory Server:Review the user registry considerationsSecurity Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries. .Access the instructions for the Typical installation path method in the IBM Security Directory Server version 6.3 IBM Knowledge Center. Go to the IBM Security Directory Server version 6.3 IBM Knowledge Center. Search for Typical installation path. This task completes installations of the following components:All components that are required by Security Directory Server.All the corequisite products that are required by Security Directory Server, if they are not already installed. GSKitDB2The embedded version of WebSphere Application Server. This software is required by the Web Administration tool, which is installed automatically as part of the Typical installation path method.This task also completes the following configuration:Deploys the Web Administration tool.Creates a default directory server instance named dsrdbm01.Creates the operating system user ID named dsrdbm01 that owns the instance.Creates an Administrator DN named cn=root.Creates a default suffix named o=sample.suffixesSecurity Directory Server defaultLog on to the system.AIX, Linux, or SolarisLog on as root.WindowsLog on as an administrator.Use the following steps to prepare and start the installation program:Access the DVD or extract the files from the archive file that you downloaded from Passport Advantage.For AIX, Linux, or Solaris systems: Install the Security Directory Server license files by running the idsLicense script in the image_path/tdsV6.3FP/license directory, where image_path is the path to the DVD image, or where you downloaded the archive file from Passport Advantage.Change to the platform/tdsV6.3/tds directory.Run the installation program.AIX, Linux, or SolarisRun install_tds.bin.WindowsDouble-click the install_tds.exe icon.Complete the installation by using the Typical installation path instructions in the IBM Security Directory Server IBM Knowledge Center.For more information, see the Security Directory Server Knowledge Center.Record any passwords that you set during the installation so that you can use them in subsequent installation steps.Complete the following steps when the Security Directory Server Instance Administration tool opens.Verify that the default instance is listed in the configuration. If you are using Red Hat Enterprise Linux 6, the default instance is not displayed in the tool. To verify that it is listed in the configuration, use the idsilist command. See the IBM Security Directory Server version 6.3 IBM Knowledge Center for details about the command. By default, this command is in /opt/ibm/ldap/V6.3/sbin/.Do not start the instance.Exit the tool.Start the configuration process by using the command line. Create the suffix where Security Access Manager maintains its metadata with the idscfgsuf command.suffixesadding to Security Directory Serveridscfgsuf -s "secAuthority=domain_name"The command is in the following locations by default:AIX, Linux, or Solaris/opt/ibm/ldap/V6.3/sbin/idscfgsufWindowsc:\Program Files\IBM\LDAP\V6.3\sbin\idscfgsufwhere domain_name is the management domain name. The default suffix is Default; for example: idscfgsuf -s "secAuthority=Default"If you specify a location for the metadata that is not a stand-alone suffix, ensure that the location exists in the LDAP server.This suffix is added to the ibmslapd.conf file for the default instance. If you have more than one instance, specify the instance name by using the -I option.You can create more suffixes to maintain user and group definitions.idscfgsuf -s "c=US"Start the LDAP server. AIX, Linux, or Solaris ibmslapd& WindowsFrom the Services window, start the following services: IBM Security Directory Server Instance V6.3 - instance_nameFor AIX, Linux, or Solaris systems only: Update the installation to the appropriate fix pack level.For Windows installations, the installation image includes the appropriate fix pack level.Stop all Security Directory Server services.Access the DVD or extract the files from the archive file that you downloaded from Passport Advantage.Change to the appropriate directory for your operating system.platform/tdsV6.3FPSee the readme file that is included with the fix pack for information and installation instructions.Run the installation program../idsinstall –u -fWhen the installation completes, verify the installed versions.Open a command prompt.Type:idsversionIf you are setting up SSL communication, see Configuring IBM Tivoli Directory Server for SSL accessEnable SSL to secure communication between the Tivoli Directory Server and the Security Access Manager components.. Security Directory Server installation and configurationSecurity Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.

Installing Security Directory Server with a wizard

Install IBM Security Directory Server by using the installation wizard in the typical installation path. It uses default values and automatically installs all the required Security Directory Server components for Security Access Manager.

Before you begin

Note:

The information in this topic is for Directory Server version 6.3. Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0.

If Security Directory Server packages, such as client packages, are already installed at a level greater than 6.3.0.0, remove the packages before you run the installation wizard.

Complete the following tasks before you set up IBM Security Directory Server:

Review the user registry considerations.

Access the instructions for the Typical installation path method in the IBM Security Directory Server version 6.3 IBM Knowledge Center.

Go to the IBM Security Directory Server version 6.3 IBM Knowledge Center.

Search for Typical installation path.

About this task

This task completes installations of the following components:

All components that are required by Security Directory Server.

All the corequisite products that are required by Security Directory Server, if they are not already installed.

GSKit

DB2

The embedded version of WebSphere Application Server. This software is required by the Web Administration tool, which is installed automatically as part of the Typical installation path method.

This task also completes the following configuration:

Deploys the Web Administration tool.

Creates a default directory server instance named dsrdbm01.

Creates the operating system user ID named dsrdbm01 that owns the instance.

Creates an Administrator DN named cn=root.

Creates a default suffix named o=sample.

Procedure

Log on to the system.

AIX, Linux, or Solaris

Log on as root.

Windows

Log on as an administrator.

Use the following steps to prepare and start the installation program:

Access the DVD or extract the files from the archive file that you downloaded from Passport Advantage.

For AIX, Linux, or Solaris systems: Install the Security Directory Server license files by running the idsLicense script in the image_path/tdsV6.3FP/license directory, where image_path is the path to the DVD image, or where you downloaded the archive file from Passport Advantage®.

Change to the platform/tdsV6.3/tds directory.

Run the installation program.

AIX, Linux, or Solaris

Run install_tds.bin.

Windows

Double-click the install_tds.exe icon.

Complete the installation by using the Typical installation path instructions in the IBM Security Directory Server IBM Knowledge Center. For more information, see the Security Directory Server Knowledge Center.

Note: Record any passwords that you set during the installation so that you can use them in subsequent installation steps.

Complete the following steps when the Security Directory Server Instance Administration tool opens.

Verify that the default instance is listed in the configuration.

Note: If you are using Red Hat Enterprise Linux 6, the default instance is not displayed in the tool. To verify that it is listed in the configuration, use the idsilist command. See the IBM Security Directory Server version 6.3 IBM Knowledge Center for details about the command. By default, this command is in /opt/ibm/ldap/V6.3/sbin/.

Do not start the instance.

Exit the tool.

Start the configuration process by using the command line. Create the suffix where Security Access Manager maintains its metadata with the idscfgsuf command.

idscfgsuf -s "secAuthority=domain_name"

The command is in the following locations by default:

AIX, Linux, or Solaris

/opt/ibm/ldap/V6.3/sbin/idscfgsuf

Windows

c:\Program Files\IBM\LDAP\V6.3\sbin\idscfgsuf

where domain_name is the management domain name.

The default suffix is Default; for example:

idscfgsuf -s "secAuthority=Default"

If you specify a location for the metadata that is not a stand-alone suffix, ensure that the location exists in the LDAP server.

This suffix is added to the ibmslapd.conf file for the default instance. If you have more than one instance, specify the instance name by using the -I option.

Optional: You can create more suffixes to maintain user and group definitions.

idscfgsuf -s "c=US"

Start the LDAP server.

AIX, Linux, or Solaris

ibmslapd&

Windows

From the Services window, start the following services:

IBM Security Directory Server Instance V6.3 - instance_name

Optional: For AIX, Linux, or Solaris systems only: Update the installation to the appropriate fix pack level.

Note: For Windows installations, the installation image includes the appropriate fix pack level.

Stop all Security Directory Server services.

Access the DVD or extract the files from the archive file that you downloaded from Passport Advantage.

Change to the appropriate directory for your operating system.

platform/tdsV6.3FP

See the readme file that is included with the fix pack for information and installation instructions.

Run the installation program.

./idsinstall –u -f

When the installation completes, verify the installed versions.

Open a command prompt.

Type:

idsversion

What to do next

If you are setting up SSL communication, see Configuring IBM Tivoli Directory Server for SSL access.

Parent topic: Security Directory Server installation and configuration

Installing Security Directory Server with a script (AIX, Linux, Solaris)Installing Security Directory Server with a script (AIX, Linux, Solaris)Installing Security Directory Server with a script (AIX, Linux, Solaris)Use the script file to automate the installation of Security Directory Server.Tivoli Directory Serverautomating installationThe information in this topic is for Directory Server version 6.3. Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0. Automated installations can complete unattended silent installations. This task uses the idsNative Install command.Log on to the system with root privileges.Access the product DVD or extract the files from the archive file that you downloaded from Passport Advantage.Extract the Security Directory Server archive file to a directory with adequate disk space.For example, /tdsV6.3/. If you use a DVD to install Security Directory Server, the files are in the tdsV6.3 directory.Locate the following script files and change the permissions so that you can write to the files:chmod +w image_path/tdsV6.3/responsefile.txt chmod +w image_path/scripts/ISAMConfigTDS.sh chmod +w image_path/scripts/ISAMGenSSLCert.sh chmod +w image_path/platform/tdsV6.3/idsConfigServerSSL.shInstall the Security Directory Server license files by completing the following steps:Navigate to the image_path/tdsV6.3FP/license directory.Run the following script:idsLicense -qwhere the -q option installs the license files without displaying the license. If you use the -q option, you automatically accept the license without viewing it. In the tdsV6.3 directory, locate the installation program file and the response file:idsNativeInstall.shresponseFile.txtThese files must be in the same directory.Update the following entries in the responseFile.txt file.By default, the values of the variable are set to false and their corresponding path variables are not set.To install DB2, set the db2FeatureInstall variable to true. Update the db2InstallimagePath variable with the absolute path where the DB2 installation files are located.For example:db2FeatureInstall=true db2InstallimagePath=/image_path/platform/tdsV6.3/db2To install GSKit, set the gskitFeatureInstall variable to true. Update the gskitInstallimagePath with the absolute path to where the GSKit installation files are located. For example:gskitFeatureInstall=true gskitInstallimagePath=/image_path/platform/tdsV6.3/gskitTo install embedded WebSphere Application Server (eWAS), set the eWasFeatureInstall variable to true. Update the eWasInstallimagePath with the absolute path to where the embedded WebSphere Application Server installation files are located. For example:eWasFeatureInstall=true eWasInstallimagePath=/image_path/platform/tdsV6.3/appsrvTo install Security Directory Server, update the tdsInstallimagePath with the absolute path to where the Security Directory Server installation files are located. Update the tdsFixPackInstallimagePath variable with the absolute path to where the Security Directory Server fix pack installation files are located. For example:tdsInstallimagePath=/image_path/platform/tdsV6.3/ tdsFixPackInstallimagePath=/image_path/platform/tdsV6.3FPIf you want to install the full Security Directory Server , but there are already some Security Directory Server packages installed, such as the client packages, remove the images before you run this script.Save the responseFile.txt file.For Solaris systems only: Check that the /export/home directory exists. If the directory does not exist, create it.Ensure that the following kernel parameters in the /etc/system file are set appropriately for your system. The following values are suggested as starting values:set msgsys:msginfo_msgmax = 65535 set msgsys:msginfo_msgmnb = 65535 set shmsys:shminfo_shmmax = 2134020096For more information, see the Solaris tuning documentation.Open a command prompt and start the installation by typing idsNativeInstall.shVerify the installation by checking the installation log:/var/idsldap/V6.3/idsNativeInstall_timestamp.logFor AIX, Linux, or Solaris systems only: Update the installation to the appropriate fix pack level.For Windows installations, the installation image includes the appropriate fix pack level.Stop all Security Directory Server services.Access the DVD or extract the files from the archive file that you downloaded from Passport Advantage.Change to the appropriate directory for your operating system.platform/tdsV6.3FPSee the readme file that is included with the fix pack for information and installation instructions.Run the installation program../idsinstall –u -fIf you want to use the Security Directory Server Web Administration Tool, deploy Security Directory Server into the embedded version of WebSphere Application Server:Open a command prompt.Run ldaphome/idstools/deploy_IDSWebApp.Replace ldaphome with the installation path.Create the default instance and suffix:suffixesadding to Tivoli Directory ServerOpen a command prompt.Change to the following directory: image_path/platform/tdsV6.3/Run the following command:idsdefinst -p passworddn -w passworduser -e encryptseedwhere:passworddnThe administration DN password. For example, cn=root password.passworduserThe database owner password. For example, the password for the user ID dsrdbm01.encryptseedThe encryption seed value. This value is used to create is used to generate a set of Advanced Encryption Standard (AES) secret key values. The length must be 12 - 1016 characters.Configure Security Directory Server for Security Access Manager:Locate the image_path/scripts/ISAMConfigTDS.sh file.Open the file in a text editor.Set the adminPW to the cn=root password.This password was created when the idsdefinst tool was run.Review the other settings in the file. If you used the default values during the installation of Security Directory Server, no further modification is required.Save and close the ISAMConfigTDS.sh file.Open a command prompt.Run image_path/scripts/ISAMConfigTDS.sh.Replace image_path with the path to the script files.Review output messages and verify that the script completed successfully.If you used an improper database name, the script might exit with a return code of zero. Review all messages to ensure that the script completed successfully. The default database name is dsrdbm01. You do not need to change the default name if you used the defaults with the idsdefinst command.If you are setting up Suite B and NIST compliance between your user registry and Security Access Manager components, see Configuring IBM Tivoli Directory Server for SSL accessEnable SSL to secure communication between the Tivoli Directory Server and the Security Access Manager components.. If you want to configure basic SSL, continue with the following steps:To create a self-signed certificate:Open image_path/scripts/ISAMGenSSLCert.sh in a text editor.Set the password for the key database with the KEYFILEPWD variable.Save and close the file.Run image_path/scripts/ISAMGenSSLCert.sh. Replace image_path with the path to the script files. The self-signed certificate is extracted to am_key.der.To enable SSL with Security Directory Server: Open image_path/platform/tdsV6.3/idsConfigServerSSL.sh in a text editor.Set the values for the following variables. Values in bold are the typical default values. Use values that are specific and correct for your environment.tdsinstancename=dsrdbm01 port=389 ssl_port=636 serverpwd= serverlabel=AMLDAP serverkeywithpath=/am_key.kdb user_dn=cn=root password_dn=The password fields must be set to your passwords.Save and close the file.Run image_path/platform/tdsV6.3/idsConfigServerSSL.sh. Replace image_path/platform with the path to the Security Directory Server installation files.Security Directory Server installation and configurationSecurity Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.

Installing Security Directory Server with a script (AIX, Linux, Solaris)

Use the script file to automate the installation of Security Directory Server.

Before you begin

The information in this topic is for Directory Server version 6.3. Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0.

About this task

Automated installations can complete unattended silent installations. This task uses the idsNative Install command.

Procedure

Log on to the system with root privileges.

Access the product DVD or extract the files from the archive file that you downloaded from Passport Advantage®.

Extract the Security Directory Server archive file to a directory with adequate disk space. For example, /tdsV6.3/. If you use a DVD to install Security Directory Server, the files are in the tdsV6.3 directory.

Locate the following script files and change the permissions so that you can write to the files:

chmod +w image_path/tdsV6.3/responsefile.txt
chmod +w image_path/scripts/ISAMConfigTDS.sh
chmod +w image_path/scripts/ISAMGenSSLCert.sh
chmod +w image_path/platform/tdsV6.3/idsConfigServerSSL.sh

Install the Security Directory Server license files by completing the following steps:

Navigate to the image_path/tdsV6.3FP/license directory.

Run the following script:

idsLicense -q

where the -q option installs the license files without displaying the license. If you use the -q option, you automatically accept the license without viewing it.

In the tdsV6.3 directory, locate the installation program file and the response file:

idsNativeInstall.sh

responseFile.txt

These files must be in the same directory.

Update the following entries in the responseFile.txt file. By default, the values of the variable are set to false and their corresponding path variables are not set.

To install DB2, set the db2FeatureInstall variable to true. Update the db2InstallimagePath variable with the absolute path where the DB2 installation files are located.

For example:

db2FeatureInstall=true
db2InstallimagePath=/image_path/platform/tdsV6.3/db2

To install GSKit, set the gskitFeatureInstall variable to true. Update the gskitInstallimagePath with the absolute path to where the GSKit installation files are located. For example:

gskitFeatureInstall=true
gskitInstallimagePath=/image_path/platform/tdsV6.3/gskit

To install embedded WebSphere Application Server (eWAS), set the eWasFeatureInstall variable to true. Update the eWasInstallimagePath with the absolute path to where the embedded WebSphere Application Server installation files are located. For example:

eWasFeatureInstall=true
eWasInstallimagePath=/image_path/platform/tdsV6.3/appsrv

To install Security Directory Server, update the tdsInstallimagePath with the absolute path to where the Security Directory Server installation files are located. Update the tdsFixPackInstallimagePath variable with the absolute path to where the Security Directory Server fix pack installation files are located. For example:

tdsInstallimagePath=/image_path/platform/tdsV6.3/
tdsFixPackInstallimagePath=/image_path/platform/tdsV6.3FP

Note: If you want to install the full Security Directory Server , but there are already some Security Directory Server packages installed, such as the client packages, remove the images before you run this script.

Save the responseFile.txt file.

For Solaris systems only:

Check that the /export/home directory exists. If the directory does not exist, create it.

Ensure that the following kernel parameters in the /etc/system file are set appropriately for your system. The following values are suggested as starting values:

set msgsys:msginfo_msgmax = 65535
set msgsys:msginfo_msgmnb = 65535
set shmsys:shminfo_shmmax = 2134020096

For more information, see the Solaris tuning documentation.

Open a command prompt and start the installation by typing idsNativeInstall.sh

Verify the installation by checking the installation log: /var/idsldap/V6.3/idsNativeInstall_timestamp.log

For AIX, Linux, or Solaris systems only: Update the installation to the appropriate fix pack level.

Note: For Windows installations, the installation image includes the appropriate fix pack level.

Stop all Security Directory Server services.

Access the DVD or extract the files from the archive file that you downloaded from Passport Advantage.

Change to the appropriate directory for your operating system.

platform/tdsV6.3FP

See the readme file that is included with the fix pack for information and installation instructions.

Run the installation program.

./idsinstall –u -f

Optional: If you want to use the Security Directory Server Web Administration Tool, deploy Security Directory Server into the embedded version of WebSphere Application Server:

Open a command prompt.

Run ldaphome/idstools/deploy_IDSWebApp. Replace ldaphome with the installation path.

Create the default instance and suffix:

Open a command prompt.

Change to the following directory: image_path/platform/tdsV6.3/

Run the following command:

idsdefinst -p passworddn -w passworduser -e encryptseed

where:

passworddn

The administration DN password. For example, cn=root password.

passworduser

The database owner password. For example, the password for the user ID dsrdbm01.

encryptseed

The encryption seed value. This value is used to create is used to generate a set of Advanced Encryption Standard (AES) secret key values. The length must be 12 - 1016 characters.

Configure Security Directory Server for Security Access Manager:

Locate the image_path/scripts/ISAMConfigTDS.sh file.

Open the file in a text editor.

Set the adminPW to the cn=root password. This password was created when the idsdefinst tool was run.

Review the other settings in the file. If you used the default values during the installation of Security Directory Server, no further modification is required.

Save and close the ISAMConfigTDS.sh file.

Open a command prompt.

Run image_path/scripts/ISAMConfigTDS.sh. Replace image_path with the path to the script files.

Review output messages and verify that the script completed successfully.

Note: If you used an improper database name, the script might exit with a return code of zero. Review all messages to ensure that the script completed successfully. The default database name is dsrdbm01. You do not need to change the default name if you used the defaults with the idsdefinst command.

Optional: If you are setting up Suite B and NIST compliance between your user registry and Security Access Manager components, see Configuring IBM Tivoli Directory Server for SSL access. If you want to configure basic SSL, continue with the following steps:

To create a self-signed certificate:

Open image_path/scripts/ISAMGenSSLCert.sh in a text editor.

Set the password for the key database with the KEYFILEPWD variable.

Save and close the file.

Run image_path/scripts/ISAMGenSSLCert.sh. Replace image_path with the path to the script files.

Note: The self-signed certificate is extracted to am_key.der.

To enable SSL with Security Directory Server:

Open image_path/platform/tdsV6.3/idsConfigServerSSL.sh in a text editor.

Set the values for the following variables. Values in bold are the typical default values. Use values that are specific and correct for your environment.

tdsinstancename=dsrdbm01
port=389
ssl_port=636
serverpwd=
serverlabel=AMLDAP
serverkeywithpath=/am_key.kdb
user_dn=cn=root
password_dn=

Note: The password fields must be set to your passwords.

Save and close the file.

Run image_path/platform/tdsV6.3/idsConfigServerSSL.sh. Replace image_path/platform with the path to the Security Directory Server installation files.

Parent topic: Security Directory Server installation and configuration

Installing Security Directory Server with a script (Windows)Installing Security Directory Server with a script (Windows)Installing Security Directory Server with a script (Windows)Use the script file to automate the installation of Security Directory Server.The information in this topic is for Directory Server version 6.3. Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0. Automated installations can perform unattended silent installations. This task uses the install_tdsSilent command.Log on to the system with Administrator privileges.Extract the Security Directory Server archive file to a directory with adequate disk space, for example, /tdsV6.3/. If you use a DVD to install Security Directory Server, the files are in the tdsV6.3 directory.Locate the following script files and change the permissions so that you can write to the files:image_path\tds\optionsFile\InstallServer.txt image_path\scripts\ISAMConfigTDS.bat image_path\scripts\ISAMGenSSLCert.bat image_path\Windows\tdsV6.3\idsConfigServerSSL.batFor example:For each file previously listed, right-click the file and click Properties.Click the Security tab.In the Name list box, select the user or group that you want to change.In the Permissions box, select Write.Click OK.In the directory, locate the installation program file and the response file.image_path\windows\tdsV6.3\tds\install_tdsSilent.exeimage_path\windows\tdsV6.3\tds\optionsFile\InstallServer.txtUpdate the entries in the InstallServer.txt file with the appropriate values for your installation.Use the instructions in the text file. For more information, see the topics about the options files for silent installation in the Security Directory Server IBM Knowledge Center.Save the InstallServer.txt file.Open a command prompt and change to the following directory:image_path\windows\tdsV6.3\tdsStart the installation by running the following command:install_tdsSilent -is:silent -options image_path\optionsFiles\InstallServer.txt where image_path is the full path to the optionsFiles directory.Verify the installation by checking the installation log:C:\Program Files\IBM\LDAP\V6.3\var\ldapinst.logCreate the default instance and suffix:suffixesadding to Security Directory ServerOpen a command prompt.Change to the following directory:ldap_home\idstoolsRun the following command:idsdefinst -p passworddn -w passworduser -e encryptseedwhere:passworddnThe administration DN password. For example, cn=root password.passworduserThe database owner password. For example, the password for the user ID dsrdbm01.encryptseedThe encryption seed value. This value is used to create is used to generate a set of Advanced Encryption Standard (AES) secret key values. The length must be 12 - 1016 characters.Configure Security Directory Server for Security Access Manager:Locate the image_path\scripts\ISAMConfigTDS.bat file.Open the file in a text editor.Set the adminPW to the cn=root password.Review the other settings in the file. If you used the default values during the installation of Security Directory Server, no further modification is required.Save and close the ISAMConfigTDS.bat file.Open a command prompt.Run image_path\scripts\ISAMConfigTDS.bat. Replace image_path with the path to the script files.Verify the configuration by checking the configuration log:C:\Users\Administrator\ConfigTDSforISAM.logIf you are setting up Suite B and NIST compliance between your user registry and Security Access Manager components, see Configuring IBM Tivoli Directory Server for SSL accessEnable SSL to secure communication between the Tivoli Directory Server and the Security Access Manager components.. If you want to configure basic SSL, continue with the following steps:To create a self-signed certificate:Open image_path\scripts\ISAMGenSSLCert.bat in a text editor.Set the password for the key database with the KEYFILEPWD variable.Save and close the file.Run image_path\scripts\ISAMGenSSLCert.bat. Replace image_path with the path to the script files. The self-signed certificate is extracted to am_key.der.To enable SSL with Security Directory Server: Open image_path\Windows\tdsV6.3\idsConfigServerSSL.bat in a text editor.Set the values for the following variables. Values in bold are the typical default values. Use values that are specific and correct for your environment.tdsinstancename=dsrdbm01 port=389 ssl_port=636 serverpwd= serverlabel=AMLDAP serverkeywithpath=C:\am_key.kdb user_dn=cn=root password_dn=The password fields must be set to your passwords.Save and close the file.Run image_path\Windows\tdsV6.3\idsConfigServerSSL.bat. Replace image_path with the path to the Security Directory Server installation files.Security Directory Server installation and configurationSecurity Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.

Installing Security Directory Server with a script (Windows)

Use the script file to automate the installation of Security Directory Server.

Before you begin

The information in this topic is for Directory Server version 6.3. Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0.

About this task

Automated installations can perform unattended silent installations. This task uses the install_tdsSilent command.

Procedure

Log on to the system with Administrator privileges.

Extract the Security Directory Server archive file to a directory with adequate disk space, for example, /tdsV6.3/. If you use a DVD to install Security Directory Server, the files are in the tdsV6.3 directory.

Locate the following script files and change the permissions so that you can write to the files:

image_path\tds\optionsFile\InstallServer.txt
image_path\scripts\ISAMConfigTDS.bat
image_path\scripts\ISAMGenSSLCert.bat
image_path\Windows\tdsV6.3\idsConfigServerSSL.bat

For example:

For each file previously listed, right-click the file and click Properties.

Click the Security tab.

In the Name list box, select the user or group that you want to change.

In the Permissions box, select Write.

Click OK.

In the directory, locate the installation program file and the response file.

image_path\windows\tdsV6.3\tds\install_tdsSilent.exe

image_path\windows\tdsV6.3\tds\optionsFile\InstallServer.txt

Update the entries in the InstallServer.txt file with the appropriate values for your installation. Use the instructions in the text file. For more information, see the topics about the options files for silent installation in the Security Directory Server IBM Knowledge Center.

Save the InstallServer.txt file.

Open a command prompt and change to the following directory:

image_path\windows\tdsV6.3\tds

Start the installation by running the following command:

install_tdsSilent -is:silent -options image_path\optionsFiles\InstallServer.txt

where image_path is the full path to the optionsFiles directory.

Verify the installation by checking the installation log:

C:\Program Files\IBM\LDAP\V6.3\var\ldapinst.log

Create the default instance and suffix:

Open a command prompt.

Change to the following directory: ldap_home\idstools

Run the following command:

idsdefinst -p passworddn -w passworduser -e encryptseed

where:

passworddn

The administration DN password. For example, cn=root password.

passworduser

The database owner password. For example, the password for the user ID dsrdbm01.

encryptseed

The encryption seed value. This value is used to create is used to generate a set of Advanced Encryption Standard (AES) secret key values. The length must be 12 - 1016 characters.

Configure Security Directory Server for Security Access Manager:

Locate the image_path\scripts\ISAMConfigTDS.bat file.

Open the file in a text editor.

Set the adminPW to the cn=root password.

Review the other settings in the file. If you used the default values during the installation of Security Directory Server, no further modification is required.

Save and close the ISAMConfigTDS.bat file.

Open a command prompt.

Run image_path\scripts\ISAMConfigTDS.bat. Replace image_path with the path to the script files.

Verify the configuration by checking the configuration log:

C:\Users\Administrator\ConfigTDSforISAM.log

Optional: If you are setting up Suite B and NIST compliance between your user registry and Security Access Manager components, see Configuring IBM Tivoli Directory Server for SSL access. If you want to configure basic SSL, continue with the following steps:

To create a self-signed certificate:

Open image_path\scripts\ISAMGenSSLCert.bat in a text editor.

Set the password for the key database with the KEYFILEPWD variable.

Save and close the file.

Run image_path\scripts\ISAMGenSSLCert.bat. Replace image_path with the path to the script files.

Note: The self-signed certificate is extracted to am_key.der.

To enable SSL with Security Directory Server:

Open image_path\Windows\tdsV6.3\idsConfigServerSSL.bat in a text editor.

Set the values for the following variables. Values in bold are the typical default values. Use values that are specific and correct for your environment.

tdsinstancename=dsrdbm01
port=389
ssl_port=636
serverpwd=
serverlabel=AMLDAP
serverkeywithpath=C:\am_key.kdb
user_dn=cn=root
password_dn=

Note: The password fields must be set to your passwords.

Save and close the file.

Run image_path\Windows\tdsV6.3\idsConfigServerSSL.bat. Replace image_path with the path to the Security Directory Server installation files.

Parent topic: Security Directory Server installation and configuration

Installing Security Directory Server with Launchpad (Windows)Installing Security Directory Server with LaunchpadInstalling Security Directory Server with LaunchpadUse the Launchpad installation method to install Security Directory Server and its prerequisite software on a computer that is running the Windows operating system.Launchpad installationSecurity Directory ServerSecurity Directory Serverinstalling from LaunchpadDB2installing from Launchpaddirectory server instancecreatingComplete the following tasks before you set up IBM Security Directory Server:Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0. The information in this topic is for Directory Server version 6.3. Review the User registry considerationsSecurity Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries. .Access the instructions for the "Typical installation path" method in the IBM Security Directory Server version 6.3 IBM Knowledge Center. The Launchpad uses a graphical user interface for the step-by-step installation and initial configuration. The Launchpad installs all the prerequisite software, if it is not already installed. Then, the Launchpad starts the graphical user interface installation for the Security Directory Server component. This task installs the following components:All components that are required by Security Directory Server.All the corequisite products that are required by Security Directory Server, if they are not already installed.GSKitDB2The embedded version of WebSphere Application Server. This software is required by the Web Administration tool, which is installed automatically as part of the "Typical installation path" method.This task also completes the following configuration:Deploys the Web Administration tool.Creates a default directory server instance named dsrdbm01.Creates the operating system user ID named dsrdbm01 that owns the instance.Creates an Administrator DN named cn=root.Creates a default suffix named o=sample.suffixesSecurity Directory Server defaultStart the Launchpad.Locate the launchpad64.exe file.If you are using archive files, ensure that all of them are extracted into the same directory. For example, ensure that the archive files for the IBM Security Access Manager package and the Security Directory Server packages are extracted into the same directory.Double-click the file to start the Launchpad.Select the language that you want to use during the installation and click OK.The Launchpad Welcome window opens.Click Next.Select the IBM Security Directory Server component.Click Next.The list on the left displays the component that you selected and any prerequisite software that is required by that component but that is not already installed.Click Next.The installation pane for the first component that is listed is displayed. An arrow next to a component name on the left indicates that the component is being installed. A check mark next to a component name indicates that the component is installed.If the current component is IBM Global Security Kit, click Install IBM Global Security Kit to install it. When it completes, continue with step 8.Click Next.Respond to the prompts presented during the installation.Click Next at the bottom of the Launchpad. The installation wizard for Security Directory Server opens.Respond to the prompts presented during the installation.When prompted for the installation type, select Typical.Complete the installation by using the "Typical installation path" instructions in the IBM Security Directory Server IBM Knowledge Center.For more information, see IBMSecurity Directory Server version 6.3 IBM Knowledge Center.Record any passwords that you set during the installation so that you can use them in subsequent installation steps.Complete the following steps when the Security Directory Server Administrator tool opens. Verify that the default instance is listed in the configuration. Do not start the instance.Exit the tool.After Security Directory Server is installed, you are prompted for the cn=root password that you provided during the installation.Click Configure IBM Security Directory Server.When all installations and configurations are completed, a success or failure message is displayed. Take one of the following actions: If the installation completed successfully, click Next.If the installation failed or an error is displayed, review the log file in the default %USERPROFILE% location, such as C:\Users\Administrator\ConfigTDSforISAM.log. Make corrections or reinstall Security Directory Server as indicated by the log file.Click Finish to close the Launchpad.If you are setting up SSL communication, see Configuring IBM Tivoli Directory Server for SSL accessEnable SSL to secure communication between the Tivoli Directory Server and the Security Access Manager components. Security Directory Server installation and configurationSecurity Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.

Installing Security Directory Server with Launchpad (Windows)

Use the Launchpad installation method to install Security Directory Server and its prerequisite software on a computer that is running the Windows operating system.

Before you begin

Complete the following tasks before you set up IBM® Security Directory Server:

Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0. The information in this topic is for Directory Server version 6.3.

Review the User registry considerations.

Access the instructions for the "Typical installation path" method in the IBM Security Directory Server version 6.3 IBM Knowledge Center.

About this task

The Launchpad uses a graphical user interface for the step-by-step installation and initial configuration. The Launchpad installs all the prerequisite software, if it is not already installed.

Then, the Launchpad starts the graphical user interface installation for the Security Directory Server component.

This task installs the following components:

All components that are required by Security Directory Server.

All the corequisite products that are required by Security Directory Server, if they are not already installed.

GSKit

DB2®

The embedded version of WebSphere® Application Server. This software is required by the Web Administration tool, which is installed automatically as part of the "Typical installation path" method.

This task also completes the following configuration:

Deploys the Web Administration tool.

Creates a default directory server instance named dsrdbm01.

Creates the operating system user ID named dsrdbm01 that owns the instance.

Creates an Administrator DN named cn=root.

Creates a default suffix named o=sample.

Procedure

Start the Launchpad.

Locate the launchpad64.exe file.

Note: If you are using archive files, ensure that all of them are extracted into the same directory. For example, ensure that the archive files for the IBM Security Access Manager package and the Security Directory Server packages are extracted into the same directory.

Double-click the file to start the Launchpad.

Select the language that you want to use during the installation and click OK. The Launchpad Welcome window opens.

Click Next.

Select the IBM Security Directory Server component.

Click Next. The list on the left displays the component that you selected and any prerequisite software that is required by that component but that is not already installed.

Click Next. The installation pane for the first component that is listed is displayed. An arrow next to a component name on the left indicates that the component is being installed. A check mark next to a component name indicates that the component is installed.

If the current component is IBM Global Security Kit, click Install IBM Global Security Kit to install it. When it completes, continue with step 8.

Click Next.

Respond to the prompts presented during the installation.

Click Next at the bottom of the Launchpad. The installation wizard for Security Directory Server opens.

Respond to the prompts presented during the installation.

When prompted for the installation type, select Typical.

Complete the installation by using the "Typical installation path" instructions in the IBM Security Directory Server IBM Knowledge Center. For more information, see IBMSecurity Directory Server version 6.3 IBM Knowledge Center.

Note: Record any passwords that you set during the installation so that you can use them in subsequent installation steps.

Complete the following steps when the Security Directory Server Administrator tool opens.

Verify that the default instance is listed in the configuration.

Do not start the instance.

Exit the tool.

After Security Directory Server is installed, you are prompted for the cn=root password that you provided during the installation.

Click Configure IBM Security Directory Server.

When all installations and configurations are completed, a success or failure message is displayed. Take one of the following actions:

If the installation completed successfully, click Next.

If the installation failed or an error is displayed, review the log file in the default %USERPROFILE% location, such as C:\Users\Administrator\ConfigTDSforISAM.log. Make corrections or reinstall Security Directory Server as indicated by the log file.

Click Finish to close the Launchpad.

What to do next

If you are setting up SSL communication, see Configuring IBM Tivoli Directory Server for SSL access

Parent topic: Security Directory Server installation and configuration

Configuring IBM Tivoli Directory Server for SSL accessConfiguring IBM Tivoli Directory Server for SSL accessConfiguring IBM Tivoli Directory Server for SSL accessEnable SSL to secure communication between the Tivoli Directory Server and the Security Access Manager components.SSL configurationfor Tivoli Directory ServerSSL configurationfor Tivoli Directory Serveruser registriesTivoli Directory Serverconfiguring SSLTivoli Directory ServerSSL configurationself-signed certificatesTivoli Directory Serverkey database filefor Tivoli Directory ServerComplete the following tasks:Install and configure Tivoli Directory Server.Install GSKit.Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0. The information in this topic is for Directory Server version 6.3. The following high-level steps are required to enable SSL support for Tivoli Directory Server for server authentication. See the information for securing directory communications in the Tivoli Directory Server Knowledge Center for the details of each step. These steps assume that you already installed and configured the Tivoli Directory Server.Create the key database, associated password stash file, and password on the Tivoli Directory Server system. For example, use the gsk8capicmd_64 to create a database, stash file, and password.gsk8capicmd_64 -keydb -create -db /key/myldap.kdb -pw passw0rd -type cms -stash -emptyIf you do not already have a personal certificate or self-signed certificate, do one of the following procedures:For a personal certificate:Request a personal certificate from a certificate authority (CA).Receive that personal certificate into the key database file.Add a signer certificate for the certificate authority to the key database file.For a self-signed certificate:Create a self-signed certificate. For example,gsk8capicmd_64 -cert -create -db /key/myldap.kdb -pw serverpwd \ -sigalg algorithm_id -label serverlabel -dn "cn=LDAP_Server,o=sample" -size keysizewhere:dbSpecifies the .kdb file that is the key database.pwSpecifies the password to access the key database.sigalgSpecifies the signing algorithm that is used to sign the message. Acceptable values that correspond to a compliance mode are listed in the following table. This setting requires a minimum version of Tivoli Directory Server 6.3.0.17. Skip this setting if you are using an earlier version of Tivoli Directory Server or if your environment does not require a compliance configuration.Compliance values for the keyfileCompliance mode that is planned for Security Access Manager 7.0algorithm_id valuekeysize valuenoneSHA1WithRSA2048fipsSHA1WithRSA2048sp800-131-transitionSHA256WithRSA2048sp800-131-strictSHA256WithRSA2048suite-b-128SHA256WithECDSA256suite-b-192SHA384WithECDSA384labelSpecifies the label that is attached to the certificate. The label name is configured in Security Directory Server. Either the label name must match the Security Directory Server configured value, or you must update the name value in Security Directory Server to match the label that you set here.dnIndicates an X.500 distinguished name. An example format: CN=common_name, O=organization, C=country.sizeThe size of the new key pair to be created. This size ranges in value and depends on the key type. For some algorithms, you can specify a 0 value to use the default key size. This size is typically the minimum size that is considered secure. The following list contains the valid values.For RSA algorithms:512-4096; key sizes in this range must be selected as NIST SP800-131; 8192 is supported for validation only. Available key sizes might vary according to security configurations. For example, you cannot generate 512-bit RSA keys in FIPS mode. The default value is 1024. For EC algorithms:224 - 512 GSKit EC key generation supports P256, P384, and P521 curves only. P521 curve keys use a 512-bit SHA2 hash. The following list contains the default values.256 (SHA256)384 (SHA384)512 (SHA512)Extract the certificate in ASCII format. For example, type: gsk8capicmd_64 -cert -extract -db /key/myldap.kdb -pw serverpwd -label myldap -format ascii -target myldap.certIn a subsequent configuration task, you import this certificate to the signer section of the key database on all client systems that securely communicate with the server. A client system is: Any Security Access Manager server system.Any other system that uses the Tivoli Directory Server client to securely communicate with the Tivoli Directory Server.Any system that uses the Security Access Manager Runtime componentConfigure the Tivoli Directory Server instance to use the certificate in the configuration file. Create an ldif file with the appropriate configuration values in it to perform this step. For more information about ldif files, see the Tivoli Directory Server Knowledge Center. If you do not create an ldif file for this step, you must use standard input to enter the configuration.Create an ldif file that contains the following values.Use your own value for the values that are shown in italics.dn: cn=SSL, cn=Configuration changetype: modify replace: ibm-slapdSslAuth ibm-slapdSslAuth: serverAuthUse serverAuth or the value that is appropriate for your environment. The other valid value is serverClientAuth.dn: cn=SSL, cn=Configuration changetype: modify replace: ibm-slapdSecurity ibm-slapdSecurity: SSLUse SSL or the value that is appropriate for your environment. The valid values are none, SSL, SSlOnly, TLS, SSLTLS.dn: cn=SSL, cn=Configuration changetype: modify replace: ibm-slapdSslKeyDatabase ibm-slapdSslKeyDatabase: /key/myldap.kdbdn: cn=SSL, cn=Configuration changetype: modify replace: ibm-slapdSslCertificate ibm-slapdSslCertificate: serverlabel dn: cn=SSL, cn=Configuration changetype: modify replace: ibm-slapdSslKeyDatabasepw ibm-slapdSslKeyDatabasepw: serverpwdSave the file and name it. For example, name itserverauth.ldif.Run the ldapmodify command.idsldapmodify -h server.in.ibm.com -p 389 -D cn=root -w root \ -i /home/dsrdbm01/serverauth.ldifwhere:h hostnameSpecifies the host on which the LDAP server is running. p port_numberSpecifies an alternative TCP port where the LDAP server is listening. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP SSL port 636 is used.D binddnUsebinddn to bind to the LDAP directory. binddn is a string-represented DN. When used with -m DIGEST-MD5, it specifies the authorization ID. It can be either a DN or an authzId string that starts with u: or dn:.-D binddn -w passwd does not call bind functions on superuser DNs. i filenameSpecifies the entry modification information from an LDIF file instead of from standard input. If an LDIF file is not specified, you must use standard input to specify the update records in LDIF format. Update the compliance type (such as FIPS), if required for your environment.This step requires a minimum version of Tivoli Directory Server 6.3.0.17. Skip this step if you are using an earlier version of Tivoli Directory Server or if your environment does not require a compliance configuration.Create an ldif file with the appropriate configuration values in it to perform this step. For more information about ldif files, see the Tivoli Directory Server Knowledge Center. If you do not create an ldif file for this step, you must use standard input to enter the configuration.Choose the compliance mode that you want to use in your environment.nonefipssp800-131-transitionsp800-131-strictsuite-b-128suite-b-192For descriptions of these compliance modes, see the documentation that came with the Tivoli Directory Server fix pack.Create an ldif file that contains the appropriate values for the compliance mode you want to use.Compliance attribute valuesCompliance mode Values for cn=Front End, cn=ConfigurationAttributes for cn=SSL, cn=Configurationnoneibm-slapdSetenv: IBMSLAPD_SECURITY_PROTOCOL= SSLV3,TLS10,TLS11,TLS12ibm-slapdSecurity: SSLTLS ibm-slapdSslFIPSModeEnabled: false ibm-slapdSslFIPSProcessingMode: false ibm-slapdSslCipherSpec: AES ibm-slapdSslCipherSpec: AES-128 ibm-slapdSslCipherSpec: RC4-128-MD5 ibm-slapdSslCipherSpec: RC4-128-SHA ibm-slapdSslCipherSpec: TripleDES-168 ibm-slapdSslCipherSpec: DES-56 ibm-slapdSslCipherSpec: RC2-40-MD5 ibm-slapdSslCipherSpec: RC4-40-MD5 ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_RSA_WITH_RC4_128_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_RC4_128_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_RC4_128_SHAfipsibm-slapdSetenv: IBMSLAPD_SECURITY_PROTOCOL= TLS10,TLS11,TLS12ibm-slapdSecurity: SSLTLS ibm-slapdSslFIPsProcessingMode: true ibm-slapdSslCipherSpec: AES ibm-slapdSslCipherSpec: AES-128 ibm-slapdSslCipherSpec: TripleDES-168 ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384sp800-131-transitionibm-slapdSetenv: IBMSLAPD_SECURITY_PROTOCOL= TLS10,TLS11,TLS12ibm-slapdSecurity: SSLTLS ibm-slapdSslFIPsProcessingMode: true ibm-slapdSslCipherSpec: AES ibm-slapdSslCipherSpec: AES-128 ibm-slapdSslCipherSpec: TripleDES-168 ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384sp800-131-strictibm-slapdSetenv: IBMSLAPD_SECURITY_PROTOCOL=TLS12 ibm-slapdSetenv: IBMSLAPD_SSL_EXTN_SIGALG= GSK_TLS_SIGALG_RSA_WITH_SHA224, GSK_TLS_SIGALG_RSA_WITH_SHA256, GSK_TLS_SIGALG_RSA_WITH_SHA384, GSK_TLS_SIGALG_RSA_WITH_SHA512, GSK_TLS_SIGALG_ECDSA_WITH_SHA224, GSK_TLS_SIGALG_ECDSA_WITH_SHA256, GSK_TLS_SIGALG_ECDSA_WITH_SHA384, GSK_TLS_SIGALG_ECDSA_WITH_SHA512ibm-slapdSecurity: SSLTLS ibm-slapdSslFIPsProcessingMode: true ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384suite-b-128ibm-slapdSetenv: IBMSLAPD_SUITEB_MODE=128ibm-slapdSecurity: SSLTLSsuite-b-192ibm-slapdSetenv: IBMSLAPD_SUITEB_MODE=192ibm-slapdSecurity: SSLTLSSave the file and name it.For example, name it compmode.ldif.Run the ldapmodify command.Replace the values in italics with your own values.idsldapmodify -h server.in.ibm.com -p 389 -D cn=root -w root \ -i /home/dsrdbm01/compmode.ldifwhere:h hostnameSpecifies the host on which the LDAP server is running. p port_numberSpecifies an alternative TCP port where the LDAP server is listening. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP SSL port 636 is used.D binddnUse binddn to bind to the LDAP directory.binddn is a string-represented DN. When used with -m DIGEST-MD5, it specifies the authorization ID. It can be either a DN or an authzId string that starts with u: or dn:. -D binddn -w passwd does not call bind functions on superuser DNs. i filenameSpecifies the entry modification information from an LDIF file instead of from standard input. If an LDIF file is not specified, you must use standard input to specify the update records in LDIF format. Make a note of the SSL secure port number on this server.The default secure port number is 636.Copy the signer certificate and have it available to copy onto the computer on which Security Access Manager components are installed and with which you want to enable SSL communication. In a subsequent task, you add this certificate to the key database on that computer.Security Directory Server installation and configurationSecurity Directory Server is provided with the Security Access Manager product. You can use a new installation or an existing installation of Security Directory Server in your environment.

Configuring IBM® Tivoli Directory Server for SSL access

Enable SSL to secure communication between the Tivoli® Directory Server and the Security Access Manager components.

Before you begin

Complete the following tasks:

Install and configure Tivoli Directory Server.

Install GSKit.

Use the information and links in the tech note for the configuration instructions for Security Directory Server 6.4 and Security Directory Suite 8.0. The information in this topic is for Directory Server version 6.3.

About this task

The following high-level steps are required to enable SSL support for Tivoli Directory Server for server authentication. See the information for securing directory communications in the Tivoli Directory Server Knowledge Center for the details of each step. These steps assume that you already installed and configured the Tivoli Directory Server.

Procedure

Create the key database, associated password stash file, and password on the Tivoli Directory Server system. For example, use the gsk8capicmd_64 to create a database, stash file, and password.

gsk8capicmd_64 -keydb -create -db /key/myldap.kdb -pw passw0rd
  -type cms -stash -empty

If you do not already have a personal certificate or self-signed certificate, do one of the following procedures:

For a personal certificate:

Request a personal certificate from a certificate authority (CA).

Receive that personal certificate into the key database file.

Add a signer certificate for the certificate authority to the key database file.

For a self-signed certificate:

Create a self-signed certificate. For example,

gsk8capicmd_64 -cert -create -db /key/myldap.kdb -pw serverpwd \
-sigalg algorithm_id -label serverlabel
-dn "cn=LDAP_Server,o=sample" -size keysize

where:

db

Specifies the .kdb file that is the key database.

pw

Specifies the password to access the key database.

sigalg

Specifies the signing algorithm that is used to sign the message. Acceptable values that correspond to a compliance mode are listed in the following table.

Note: This setting requires a minimum version of Tivoli Directory Server 6.3.0.17. Skip this setting if you are using an earlier version of Tivoli Directory Server or if your environment does not require a compliance configuration.

Table 8. Compliance values for the keyfile

Compliance mode that is planned for Security Access Manager 7.0
algorithm_id value

keysize value

none
SHA1WithRSA
2048

fips
SHA1WithRSA
2048

sp800-131-transition
SHA256WithRSA
2048

sp800-131-strict
SHA256WithRSA
2048

suite-b-128
SHA256WithECDSA
256

suite-b-192
SHA384WithECDSA
384

label

Specifies the label that is attached to the certificate. The label name is configured in Security Directory Server. Either the label name must match the Security Directory Server configured value, or you must update the name value in Security Directory Server to match the label that you set here.

dn

Indicates an X.500 distinguished name. An example format: CN=common_name, O=organization, C=country.

size

The size of the new key pair to be created. This size ranges in value and depends on the key type.

Note: For some algorithms, you can specify a 0 value to use the default key size. This size is typically the minimum size that is considered secure. The following list contains the valid values.

For RSA algorithms:

512-4096; key sizes in this range must be selected as NIST SP800-131; 8192 is supported for validation only.

Note: Available key sizes might vary according to security configurations. For example, you cannot generate 512-bit RSA keys in FIPS mode. The default value is 1024.

For EC algorithms:

224 - 512

Note: GSKit EC key generation supports P256, P384, and P521 curves only. P521 curve keys use a 512-bit SHA2 hash. The following list contains the default values.

256 (SHA256)

384 (SHA384)

512 (SHA512)

Extract the certificate in ASCII format. For example, type:

gsk8capicmd_64 -cert -extract -db /key/myldap.kdb -pw serverpwd
-label myldap -format ascii -target myldap.cert

In a subsequent configuration task, you import this certificate to the signer section of the key database on all client systems that securely communicate with the server.

Note: A client system is:

Any Security Access Manager server system.

Any other system that uses the Tivoli Directory Server client to securely communicate with the Tivoli Directory Server.

Any system that uses the Security Access Manager Runtime component

Configure the Tivoli Directory Server instance to use the certificate in the configuration file.

Note: Create an ldif file with the appropriate configuration values in it to perform this step. For more information about ldif files, see the Tivoli Directory Server Knowledge Center. If you do not create an ldif file for this step, you must use standard input to enter the configuration.

Create an ldif file that contains the following values. Use your own value for the values that are shown in italics.

dn: cn=SSL, cn=Configuration
changetype: modify
replace: ibm-slapdSslAuth
ibm-slapdSslAuth: serverAuth

Note: Use serverAuth or the value that is appropriate for your environment. The other valid value is serverClientAuth.

dn: cn=SSL, cn=Configuration
changetype: modify
replace: ibm-slapdSecurity
ibm-slapdSecurity: SSL

Note: Use SSL or the value that is appropriate for your environment. The valid values are none, SSL, SSlOnly, TLS, SSLTLS.

dn: cn=SSL, cn=Configuration
changetype: modify
replace: ibm-slapdSslKeyDatabase
ibm-slapdSslKeyDatabase: /key/myldap.kdb

dn: cn=SSL, cn=Configuration
changetype: modify
replace: ibm-slapdSslCertificate
ibm-slapdSslCertificate: serverlabel

dn: cn=SSL, cn=Configuration
changetype: modify
replace: ibm-slapdSslKeyDatabasepw
ibm-slapdSslKeyDatabasepw: serverpwd

Save the file and name it. For example, name itserverauth.ldif.

Run the ldapmodify command.

idsldapmodify -h server.in.ibm.com -p 389 -D cn=root -w root \
-i /home/dsrdbm01/serverauth.ldif

where:

h hostname

Specifies the host on which the LDAP server is running.

p port_number

Specifies an alternative TCP port where the LDAP server is listening. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP SSL port 636 is used.

D binddn

Usebinddn to bind to the LDAP directory. binddn is a string-represented DN. When used with -m DIGEST-MD5, it specifies the authorization ID. It can be either a DN or an authzId string that starts with u: or dn:.

Note: -D binddn -w passwd does not call bind functions on superuser DNs.

i filename

Specifies the entry modification information from an LDIF file instead of from standard input. If an LDIF file is not specified, you must use standard input to specify the update records in LDIF format.

Update the compliance type (such as FIPS), if required for your environment.

Note: This step requires a minimum version of Tivoli Directory Server 6.3.0.17. Skip this step if you are using an earlier version of Tivoli Directory Server or if your environment does not require a compliance configuration.

Create an ldif file with the appropriate configuration values in it to perform this step. For more information about ldif files, see the Tivoli Directory Server Knowledge Center. If you do not create an ldif file for this step, you must use standard input to enter the configuration.

Choose the compliance mode that you want to use in your environment.

none

fips

sp800-131-transition

sp800-131-strict

suite-b-128

suite-b-192

For descriptions of these compliance modes, see the documentation that came with the Tivoli Directory Server fix pack.

Create an ldif file that contains the appropriate values for the compliance mode you want to use.

Table 9. Compliance attribute values

Compliance mode
Values for cn=Front End, cn=Configuration
Attributes for

cn=SSL, cn=Configuration

none

ibm-slapdSetenv:
IBMSLAPD_SECURITY_PROTOCOL=
SSLV3,TLS10,TLS11,TLS12

ibm-slapdSecurity: SSLTLS
ibm-slapdSslFIPSModeEnabled: false
ibm-slapdSslFIPSProcessingMode: false
ibm-slapdSslCipherSpec: AES
ibm-slapdSslCipherSpec: AES-128
ibm-slapdSslCipherSpec: RC4-128-MD5
ibm-slapdSslCipherSpec: RC4-128-SHA
ibm-slapdSslCipherSpec: TripleDES-168
ibm-slapdSslCipherSpec: DES-56
ibm-slapdSslCipherSpec: RC2-40-MD5
ibm-slapdSslCipherSpec: RC4-40-MD5
ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_RSA_WITH_RC4_128_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_RC4_128_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_RC4_128_SHA

fips

ibm-slapdSetenv:
IBMSLAPD_SECURITY_PROTOCOL=
TLS10,TLS11,TLS12

ibm-slapdSecurity: SSLTLS
ibm-slapdSslFIPsProcessingMode: true
ibm-slapdSslCipherSpec: AES
ibm-slapdSslCipherSpec: AES-128
ibm-slapdSslCipherSpec: TripleDES-168
ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

sp800-131-transition

ibm-slapdSetenv:
IBMSLAPD_SECURITY_PROTOCOL=
TLS10,TLS11,TLS12

ibm-slapdSecurity: SSLTLS
ibm-slapdSslFIPsProcessingMode: true
ibm-slapdSslCipherSpec: AES
ibm-slapdSslCipherSpec: AES-128
ibm-slapdSslCipherSpec: TripleDES-168
ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

sp800-131-strict

ibm-slapdSetenv:
IBMSLAPD_SECURITY_PROTOCOL=TLS12
ibm-slapdSetenv:
IBMSLAPD_SSL_EXTN_SIGALG=
GSK_TLS_SIGALG_RSA_WITH_SHA224,
GSK_TLS_SIGALG_RSA_WITH_SHA256,
GSK_TLS_SIGALG_RSA_WITH_SHA384,
GSK_TLS_SIGALG_RSA_WITH_SHA512,
GSK_TLS_SIGALG_ECDSA_WITH_SHA224,
GSK_TLS_SIGALG_ECDSA_WITH_SHA256,
GSK_TLS_SIGALG_ECDSA_WITH_SHA384,
GSK_TLS_SIGALG_ECDSA_WITH_SHA512

ibm-slapdSecurity: SSLTLS
ibm-slapdSslFIPsProcessingMode: true
ibm-slapdSslCipherSpec: TLS_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_RSA_WITH_AES_256_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
ibm-slapdSslCipherSpec: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

suite-b-128

ibm-slapdSetenv:
IBMSLAPD_SUITEB_MODE=128

ibm-slapdSecurity: SSLTLS

suite-b-192

ibm-slapdSetenv:
IBMSLAPD_SUITEB_MODE=192

ibm-slapdSecurity: SSLTLS

Save the file and name it. For example, name it compmode.ldif.

Run the ldapmodify command. Replace the values in italics with your own values.

idsldapmodify -h server.in.ibm.com -p 389 -D cn=root -w root \
-i /home/dsrdbm01/compmode.ldif

where:

h hostname

Specifies the host on which the LDAP server is running.

p port_number

Specifies an alternative TCP port where the LDAP server is listening. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP SSL port 636 is used.

D binddn

Use binddn to bind to the LDAP directory.binddn is a string-represented DN. When used with -m DIGEST-MD5, it specifies the authorization ID. It can be either a DN or an authzId string that starts with u: or dn:.

Note: -D binddn -w passwd does not call bind functions on superuser DNs.

i filename

Specifies the entry modification information from an LDIF file instead of from standard input. If an LDIF file is not specified, you must use standard input to specify the update records in LDIF format.

Make a note of the SSL secure port number on this server. The default secure port number is 636.

Copy the signer certificate and have it available to copy onto the computer on which Security Access Manager components are installed and with which you want to enable SSL communication. In a subsequent task, you add this certificate to the key database on that computer.

Parent topic: Security Directory Server installation and configuration

IBM Tivoli Directory Server for z/OS installation and configurationIBM Tivoli Directory Server for z/OS installation and configurationIBM Tivoli Directory Server for z/OS installation and configurationPrepare the LDAP server on z/OS for Security Access Manager.Tivoli Directory Server for z/OSsetting upuser registriesTivoli Directory Server for z/OSsetting upParticular emphasis is given to configuring Security Access Manager against a Tivoli Directory Server for z/OS that is configured to use its native authentication facility. This native authentication facility uses a System Authorization Facility (SAF) registry.These guidelines assume a new LDAP server instance that is dedicated to the Security Access Manager registry. For more information, see the LDAP Server Administration and Use manual for your particular release of z/OS. This document is available in the z/OS library. User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.Schema file updatesYou must update the z/OS schema to support the current version of Security Access Manager.Suffix creationSecurity Access Manager requires that you create a suffix that maintains Security Access Manager metadata.Suffix definitionsSecurity Access Manager processes all defined LDAP suffixes by default.Native authentication user administrationNative authentication provides the added feature of many-to-one mapping of Security Access Manager users to SAF user IDs.Configuring IBM Security Directory Server for z/OS for SSL accessWhen Security Access Manager and LDAP services are not on the same protected network, enable SSL communication between the LDAP server and the clients that support Security Access Manager. This protocol provides secure and encrypted communications between each server and client. Security Access Manager uses these communications channels as part of the process for making authentication and authorization decisions.

IBM® Tivoli Directory Server for z/OS installation and configuration

Prepare the LDAP server on z/OS® for Security Access Manager.

Particular emphasis is given to configuring Security Access Manager against a Tivoli Directory Server for z/OS that is configured to use its native authentication facility. This native authentication facility uses a System Authorization Facility (SAF) registry.

These guidelines assume a new LDAP server instance that is dedicated to the Security Access Manager registry. For more information, see the LDAP Server Administration and Use manual for your particular release of z/OS. This document is available in the z/OS library.

Schema file updates
You must update the z/OS schema to support the current version of Security Access Manager.

Suffix creation
Security Access Manager requires that you create a suffix that maintains Security Access Manager metadata.

Suffix definitions
Security Access Manager processes all defined LDAP suffixes by default.

Native authentication user administration
Native authentication provides the added feature of many-to-one mapping of Security Access Manager users to SAF user IDs.

Configuring IBM Security Directory Server for z/OS for SSL access
When Security Access Manager and LDAP services are not on the same protected network, enable SSL communication between the LDAP server and the clients that support Security Access Manager. This protocol provides secure and encrypted communications between each server and client. Security Access Manager uses these communications channels as part of the process for making authentication and authorization decisions.

Parent topic: User registry server installation and configuration

Schema file updatesSchema file updatesSchema file updatesYou must update the z/OS schema to support the current version of Security Access Manager.Security Directory Server for z/OSupdating schema filesschema filesupdating Security Directory Server for z/OS This step must be done following the application of the schema.user.ldif and schema.IBM.ldif files that are supplied with the server. For instructions on applying these schema files, see the IBM Security Directory Server for z/OS Administration and Use documentation.To apply the Security Access Manager schema to the Security Directory Server, use the ivrgy_tool utility. For instructions, see the Reference topics in the IBM Knowledge Center.IBM Tivoli Directory Server for z/OS installation and configurationPrepare the LDAP server on z/OS for Security Access Manager.

Schema file updates

You must update the z/OS® schema to support the current version of Security Access Manager.

This step must be done following the application of the schema.user.ldif and schema.IBM.ldif files that are supplied with the server. For instructions on applying these schema files, see the IBM® Security Directory Server for z/OS Administration and Use documentation.

To apply the Security Access Manager schema to the Security Directory Server, use the ivrgy_tool utility. For instructions, see the Reference topics in the IBM Knowledge Center.

Parent topic: IBM Tivoli Directory Server for z/OS installation and configuration

Suffix creationSuffix creationSuffix creationSecurity Access Manager requires that you create a suffix that maintains Security Access Manager metadata.Security Directory Server for z/OSadding suffixessuffixesadding to Security Directory Server for z/OS You must add the suffix only once when you first configure the LDAP server. The suffix enables Security Access Manager to easily locate and manage the data. It also secures access to the data, avoiding integrity or corruption problems. For more information about management domains and creating a location for the metadata, see Security Access Manager management domainsIf you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources. and Management domain location exampleIf you want to specify a nondefault location for the management domain, you can use any location within the LDAP DIT..To add suffixes to the LDAP server’s slapd.conf file, see the Security Directory Server for z/OS Administration and Use.Restart the LDAP server for changes to take effect.If you decide to add suffixes after the Security Access Manager policy server is configured, you must apply the appropriate ACLs to the newly created suffix. You can use the ivrgy-tool to apply the ACLs to the new suffix. For more information about the ivrgy-tool, see the Reference topics in the IBM Knowledge Center.See the Security Directory Server for z/OS Administration and Use for details on updating the security server configuration file.IBM Tivoli Directory Server for z/OS installation and configurationPrepare the LDAP server on z/OS for Security Access Manager.

Suffix creation

Security Access Manager requires that you create a suffix that maintains Security Access Manager metadata.

You must add the suffix only once when you first configure the LDAP server. The suffix enables Security Access Manager to easily locate and manage the data. It also secures access to the data, avoiding integrity or corruption problems.

For more information about management domains and creating a location for the metadata, see Security Access Manager management domains and Management domain location example.

To add suffixes to the LDAP server’s slapd.conf file, see the Security Directory Server for z/OS Administration and Use.

Note: Restart the LDAP server for changes to take effect.

If you decide to add suffixes after the Security Access Manager policy server is configured, you must apply the appropriate ACLs to the newly created suffix. You can use the ivrgy-tool to apply the ACLs to the new suffix. For more information about the ivrgy-tool, see the Reference topics in the IBM Knowledge Center.

See the Security Directory Server for z/OS Administration and Use for details on updating the security server configuration file.

Parent topic: IBM Tivoli Directory Server for z/OS installation and configuration

Suffix definitionsSuffix definitions for Security Access ManagerSuffix definitions for Security Access ManagerSecurity Access Manager processes all defined LDAP suffixes by default.Tivoli Directory Server for z/OSconfiguringIf suffixes are defined on the LDAP server that must not be used by Security Access Manager, add them to the /access_mgr_install_dir/etc/ldap.conf file by using the ignore-suffix keyword when you configure Security Access Manager for LDAP on z/OS.For example: ignore-suffix = sysplex=UTCPLXJ8 ignore-suffix = "o=Your Company" ignore-suffix = o=MQuser In this example, the sysplex=UTCPLXJ8 suffix is used to access the z/OS SDBM (RACF) database. The LDAP administrator ID used by Security Access Manager during configuration is not a RACF user ID on the z/OS system and does not have the authority to do SDBM searches. If this suffix was not added to the ignore-suffix list, Security Access Manager receives a return code x'32' - LDAP_INSUFFICIENT_ACCESS, during configuration.The other suffixes in the list are used by other applications on z/OS and can be ignored by Security Access Manager.Security Access Manager supports LDAP failover and load balancing for read operations. If you configured a replica server, you can provide the replica host name to Security Access Manager in the ldap.conf file, which is installed with Security Access Manager in the etc subdirectory.IBM Tivoli Directory Server for z/OS installation and configurationPrepare the LDAP server on z/OS for Security Access Manager.

Suffix definitions

Security Access Manager processes all defined LDAP suffixes by default.

If suffixes are defined on the LDAP server that must not be used by Security Access Manager, add them to the /access_mgr_install_dir/etc/ldap.conf file by using the ignore-suffix keyword when you configure Security Access Manager for LDAP on z/OS®.

For example:

ignore-suffix = sysplex=UTCPLXJ8
ignore-suffix = "o=Your Company"
ignore-suffix = o=MQuser

In this example, the sysplex=UTCPLXJ8 suffix is used to access the z/OS SDBM (RACF®) database. The LDAP administrator ID used by Security Access Manager during configuration is not a RACF user ID on the z/OS system and does not have the authority to do SDBM searches. If this suffix was not added to the ignore-suffix list, Security Access Manager receives a return code x'32' - LDAP_INSUFFICIENT_ACCESS, during configuration.

The other suffixes in the list are used by other applications on z/OS and can be ignored by Security Access Manager.

Security Access Manager supports LDAP failover and load balancing for read operations. If you configured a replica server, you can provide the replica host name to Security Access Manager in the ldap.conf file, which is installed with Security Access Manager in the etc subdirectory.

Parent topic: IBM Tivoli Directory Server for z/OS installation and configuration

Native authentication user administrationNative authentication user administrationNative authentication user administrationNative authentication provides the added feature of many-to-one mapping of Security Access Manager users to SAF user IDs.Security Directory Server for z/OSnative authenticationnative authenticationSecurity Directory Server for z/OSdocumentationMost of the existing administrative tasks work similarly with native authentication. Operations such as user create, user show, adding a user to an ACL entry or group, and all user modify commands (except password) work the same as Security Access Manager configured against any other LDAP registry. Users can change their own SAF passwords with the web-based pkmspasswd utility.commandspkmspasswdpkmspasswd command Multiple users can have the same ibm-nativeId, and all bind with the same password. For this reason, prevent many-to-one mapped users from changing the SAF password. Otherwise, there is an increased risk that users might inadvertently lock their peers out of their accounts.pdadmin sec_master> group modify SAFusers add user1 pdadmin sec_master> acl create deny_pkms pdadmin sec_master> acl modify deny_pkms set group SAFusers T pdadmin sec_master> acl attach /Webseal/server_name/pkmspasswd deny_pkmsThere is no administration command ready for immediate use to set the ibm-nativeId entry for a user. To that end, the following instructions assist the management of Security Access Manager users with an associated nativeId.The user create command does not change: pdadmin sec_master> user create user1 cn=user1,o=tivoli,c=us user1 user1 ChangeMe1 pdadmin sec_master> user modify user1 account-valid yesThe password (ChangeMe1, in this example) is set to the user’s userpassword entry in LDAP, which has no effect with native authentication enabled. In production environments, use the utility program that is provided with the Security Directory Server for z/OS to remove userpassword values from LDAP. This prevents password access if native authentication is inadvertently disabled.To set the ibm-nativeId entry for a user, create an ldif file, called a schema file, similar to the following: dn: cn=user1,o=tivoli,c=us changetype: modify objectclass: ibm-nativeAuthentication ibm-nativeId: SAF_usernameYou can load the ldif file by using the ldapmodify command on z/OS as follows: commandsldapmodifyldapmodify command ldapmodify -h host_name -p port -D bind_DN -w bind_pwd -f schema_file To run the idsldapmodify from an Security Directory Server client on a distributed system, the format of the ldif file changes slightly. dn: cn=user1,o=tivoli,c=us objectclass: inetOrgPerson objectclass: ibm-nativeAuthentication ibm-nativeId: SAF_usernameThe SAF command to reset a user’s password is as follows: ALTUSER SAF_username PASSWORD(new_password)In addition to resetting the password, the command marks the password as expired, which requires the password to be changed during the next login. If wanted, the NOEXPIRED option can be added to the command to prevent that behavior. The SAF_username must be defined as a z/OS UNIX System Services user. That is, the SAF_username must be defined on z/OS with an OMVS segment. The following line is an example of a SAF command to define SAF_username as a UNIX System Services user: altuser SAF_username omvs(home(/u/SAF_username) program(/bin/sh) uid(123456))To use native authentication, you must turn off the auth-using-compare stanza entry. To do so, edit the [ldap] stanza of the ivmgrd.conf and webseald.conf file and change the line as follows: auth-using-compare = no By default, authentications to LDAP are made with a compare operation, rather than a bind.For more information about setting up native authentication, see the IBM Security Directory Server for z/OS Administration and Use.After you configure the IBM Security Directory Server for z/OS for use with Security Access Manager, the next step is to set up the policy server. IBM Tivoli Directory Server for z/OS installation and configurationPrepare the LDAP server on z/OS for Security Access Manager.

Native authentication user administration

Native authentication provides the added feature of many-to-one mapping of Security Access Manager users to SAF user IDs.

Most of the existing administrative tasks work similarly with native authentication. Operations such as user create, user show, adding a user to an ACL entry or group, and all user modify commands (except password) work the same as Security Access Manager configured against any other LDAP registry. Users can change their own SAF passwords with the web-based pkmspasswd utility.

Multiple users can have the same ibm-nativeId, and all bind with the same password. For this reason, prevent many-to-one mapped users from changing the SAF password. Otherwise, there is an increased risk that users might inadvertently lock their peers out of their accounts.

pdadmin sec_master> group modify SAFusers add user1
pdadmin sec_master> acl create deny_pkms
pdadmin sec_master> acl modify deny_pkms set group SAFusers T
pdadmin sec_master> acl attach /Webseal/server_name/pkmspasswd deny_pkms

There is no administration command ready for immediate use to set the ibm-nativeId entry for a user. To that end, the following instructions assist the management of Security Access Manager users with an associated nativeId.

The user create command does not change:

pdadmin sec_master> user create user1 cn=user1,o=tivoli,c=us user1 user1 ChangeMe1
pdadmin sec_master> user modify user1 account-valid yes

The password (ChangeMe1, in this example) is set to the user’s userpassword entry in LDAP, which has no effect with native authentication enabled. In production environments, use the utility program that is provided with the Security Directory Server for z/OS to remove userpassword values from LDAP. This prevents password access if native authentication is inadvertently disabled.

To set the ibm-nativeId entry for a user, create an ldif file, called a schema file, similar to the following:

dn: cn=user1,o=tivoli,c=us
changetype: modify
objectclass: ibm-nativeAuthentication
ibm-nativeId: SAF_username

You can load the ldif file by using the ldapmodify command on z/OS® as follows:

ldapmodify -h host_name -p port -D bind_DN
-w bind_pwd -f schema_file

Note: To run the idsldapmodify from an Security Directory Server client on a distributed system, the format of the ldif file changes slightly.

dn: cn=user1,o=tivoli,c=us
objectclass: inetOrgPerson
objectclass: ibm-nativeAuthentication
ibm-nativeId: SAF_username

The SAF command to reset a user’s password is as follows:

ALTUSER SAF_username PASSWORD(new_password)

In addition to resetting the password, the command marks the password as expired, which requires the password to be changed during the next login. If wanted, the NOEXPIRED option can be added to the command to prevent that behavior.

Note: The SAF_username must be defined as a z/OS UNIX System Services user. That is, the SAF_username must be defined on z/OS with an OMVS segment. The following line is an example of a SAF command to define SAF_username as a UNIX System Services user:

altuser SAF_username omvs(home(/u/SAF_username) program(/bin/sh) uid(123456))

To use native authentication, you must turn off the auth-using-compare stanza entry. To do so, edit the [ldap] stanza of the ivmgrd.conf and webseald.conf file and change the line as follows:

auth-using-compare = no

By default, authentications to LDAP are made with a compare operation, rather than a bind.

For more information about setting up native authentication, see the IBM® Security Directory Server for z/OS Administration and Use.

After you configure the IBM Security Directory Server for z/OS for use with Security Access Manager, the next step is to set up the policy server.

Parent topic: IBM Tivoli Directory Server for z/OS installation and configuration

Configuring IBM Security Directory Server for z/OS for SSL accessConfiguring IBM Security Directory Server for z/OS for SSL accessConfiguring IBM Security Directory Server for z/OS for SSL accessWhen Security Access Manager and LDAP services are not on the same protected network, enable SSL communication between the LDAP server and the clients that support Security Access Manager. This protocol provides secure and encrypted communications between each server and client. Security Access Manager uses these communications channels as part of the process for making authentication and authorization decisions.SSLfor Security Directory Server for z/OSSSL configurationfor Security Directory Server for z/OSSecurity Directory Server for z/OSconfiguring SSLTo configure SSL/TLS communications, see the IBM Security Directory Server for z/OS for Administration and Use for your particular release of z/OS. The following high-level steps are required to enable SSL/TLS support on z/OS. These steps assume that you installed and configured the LDAP directory server, installed z/OS Cryptographic Services System SSL, and set STEPLIB, LPALIB, or LINKLIST.Configure the LDAP server to listen for LDAP requests on the SSL port for server authentication and optionally, client authentication. See Security options in the ibmslapd.conf fileYou can modify the ibmslapd.conf file so that you can configure the options for SSL..Generate the LDAP server private key and server certificate. Mark the certificate as the default in the key database or key ring, or identify the certificate by using its label on the sslCertificate option in the configuration file. The z/OS LDAP Server can use certificates in a key ring that is managed with the RACF RACDCERT command. The gskkyman utility, which was used in previous releases, also can be used and an example of using that utility to create a key database file can be found in Creating a key database fileUse the gskkyman utility so that you can create a key database file.. More information about the RACDCERT command can be found in the IBMz/OS Security Server RACF Command Language Reference for your particular release of z/OS. Restart the LDAP server. IBM Tivoli Directory Server for z/OS installation and configurationPrepare the LDAP server on z/OS for Security Access Manager.Security options in the ibmslapd.conf fileYou can modify the ibmslapd.conf file so that you can configure the options for SSL.Creating a key database fileUse the gskkyman utility so that you can create a key database file.

Configuring IBM Security Directory Server for z/OS for SSL access

When Security Access Manager and LDAP services are not on the same protected network, enable SSL communication between the LDAP server and the clients that support Security Access Manager. This protocol provides secure and encrypted communications between each server and client. Security Access Manager uses these communications channels as part of the process for making authentication and authorization decisions.

About this task

To configure SSL/TLS communications, see the IBM® Security Directory Server for z/OS® for Administration and Use for your particular release of z/OS.

The following high-level steps are required to enable SSL/TLS support on z/OS. These steps assume that you installed and configured the LDAP directory server, installed z/OS Cryptographic Services System SSL, and set STEPLIB, LPALIB, or LINKLIST.

Procedure

Configure the LDAP server to listen for LDAP requests on the SSL port for server authentication and optionally, client authentication. See Security options in the ibmslapd.conf file.

Generate the LDAP server private key and server certificate. Mark the certificate as the default in the key database or key ring, or identify the certificate by using its label on the sslCertificate option in the configuration file.

The z/OS LDAP Server can use certificates in a key ring that is managed with the RACF® RACDCERT command.

The gskkyman utility, which was used in previous releases, also can be used and an example of using that utility to create a key database file can be found in Creating a key database file.

More information about the RACDCERT command can be found in the IBMz/OS Security Server RACF Command Language Reference for your particular release of z/OS.

Restart the LDAP server.

Security options in the ibmslapd.conf file
You can modify the ibmslapd.conf file so that you can configure the options for SSL.

Creating a key database file
Use the gskkyman utility so that you can create a key database file.

Parent topic: IBM Tivoli Directory Server for z/OS installation and configuration

Security options in the ibmslapd.conf fileSecurity options in the ibmslapd.conf fileSecurity options in the ibmslapd.conf fileYou can modify the ibmslapd.conf file so that you can configure the options for SSL.security optionsinstallation commandsWeb security development systemconfigurationWeb security development systemslapd.confconfiguration filesslapd.conf listen ldap_URLSpecifies, in LDAP URL format, the IP address, or host name and the port number where the LDAP server listens to incoming client requests. This parameter can be specified more than one time in the configuration file.sslAuth serverAuth | serverClientAuthSpecifies the SSL/TLS authentication method. The serverAuth method allows the LDAP client to validate the LDAP server on the initial contact between the client and the server. The serverAuth method is the default.sslCertificate certificateLabel | noneSpecifies the label of the certificate that is used for server authentication. This option is needed if a default certificate is not set in the key database file or key ring, or if a certificate other than the default one is required. If this option is omitted, the default certificate is used.sslCipherSpecs string | ANYSpecifies the SSL/TLS cipher specifications that can be accepted from clients. For a complete list of the ciphers that are supported by your z/OS LDAP Server, see the IBMSecurity Directory Server for z/OS Administration and Use manual for your particular release of z/OS. sslKeyRingFile filename | keyringSpecifies the path and file name of the SSL/TLS key database file or key ring for the server.sslKeyRingFilePW stringSpecifies the password that protects access to the SSL/TLS key database file. When a RACF key ring is used instead of a key database file, do not specify this option in the configuration file. Use of the sslKeyRingFilePW configuration option is discouraged. As an alternative, use either the RACF key ring support or the sslKeyRingPWStashFile configuration option. This option eliminates this password from the configuration file.sslKeyRingPWStashFile filenameSpecifies a file name where the password for the server key database file is stashed. If this option is present, then the password from this stash file overrides the value that is specified for the sslKeyRingFilePW configuration option. Use the gskkyman utility with the –s option to create a key database password stash file. When a RACF key ring is used instead of a key database file, do not specify this option in the configuration file. Configuring IBM Security Directory Server for z/OS for SSL accessWhen Security Access Manager and LDAP services are not on the same protected network, enable SSL communication between the LDAP server and the clients that support Security Access Manager. This protocol provides secure and encrypted communications between each server and client. Security Access Manager uses these communications channels as part of the process for making authentication and authorization decisions.

Security options in the ibmslapd.conf file

You can modify the ibmslapd.conf file so that you can configure the options for SSL.

listen ldap_URL

Specifies, in LDAP URL format, the IP address, or host name and the port number where the LDAP server listens to incoming client requests. This parameter can be specified more than one time in the configuration file.

sslAuth serverAuth | serverClientAuth

Specifies the SSL/TLS authentication method. The serverAuth method allows the LDAP client to validate the LDAP server on the initial contact between the client and the server. The serverAuth method is the default.

sslCertificate certificateLabel | none

Specifies the label of the certificate that is used for server authentication. This option is needed if a default certificate is not set in the key database file or key ring, or if a certificate other than the default one is required. If this option is omitted, the default certificate is used.

sslCipherSpecs string | ANY

Specifies the SSL/TLS cipher specifications that can be accepted from clients. For a complete list of the ciphers that are supported by your z/OS® LDAP Server, see the IBM®Security Directory Server for z/OS Administration and Use manual for your particular release of z/OS.

sslKeyRingFile filename | keyring

Specifies the path and file name of the SSL/TLS key database file or key ring for the server.

sslKeyRingFilePW string

Specifies the password that protects access to the SSL/TLS key database file.

When a RACF® key ring is used instead of a key database file, do not specify this option in the configuration file.

Note: Use of the sslKeyRingFilePW configuration option is discouraged. As an alternative, use either the RACF key ring support or the sslKeyRingPWStashFile configuration option. This option eliminates this password from the configuration file.

sslKeyRingPWStashFile filename

Specifies a file name where the password for the server key database file is stashed. If this option is present, then the password from this stash file overrides the value that is specified for the sslKeyRingFilePW configuration option. Use the gskkyman utility with the –s option to create a key database password stash file.

When a RACF key ring is used instead of a key database file, do not specify this option in the configuration file.

Parent topic: Configuring IBM Security Directory Server for z/OS for SSL access

Creating a key database fileCreating a key database fileCreating a key database fileUse the gskkyman utility so that you can create a key database file.Security Directory Server for z/OScreating key database filekey database filecreating for LDAP servercommandsgskkymangskkyman commandStart the gskkyman utility from a shell prompt (OMVS or rlogin session) as follows: $ gskkyman Enter option 1 to create a new key database file.Type a key database name or accept the default key.kdb.Press EnterCreate a password to protect the key database.Enter the database password for verification.Type a password expiration interval in days or accept the default (no expiration date).Type a database record length or accept the default 2500.The key database is created and a message is displayed indicating the success or failure of this operationFrom the Key Management menu, select option 6 to create a self-signed server certificate and follow the prompts.After the certificate is created, you must extract this certificate so it can be sent to the LDAP client system and added as a trusted CA certificate. To do so, follow these steps:Select option 1 to manage keys and certificates.From the Key and Certificate List, enter the label number of the certificate to be exported.From the Key and Certificate menu, enter option 6to export the certificate to a file.From the Export File Format dialog, select the export format. For example, select option 1 to export to Binary ASN.1 DER.Enter the export file name.The certificate is exported. You can now transfer the exported file to the LDAP client system and add it as a trusted CA certificate. Since the file format of binary DER is specified on the export, this same file type must be specified to the gsk7ikm utility on the LDAP client system during the Add operation.Configuring IBM Security Directory Server for z/OS for SSL accessWhen Security Access Manager and LDAP services are not on the same protected network, enable SSL communication between the LDAP server and the clients that support Security Access Manager. This protocol provides secure and encrypted communications between each server and client. Security Access Manager uses these communications channels as part of the process for making authentication and authorization decisions.

Creating a key database file

Use the gskkyman utility so that you can create a key database file.

Procedure

Start the gskkyman utility from a shell prompt (OMVS or rlogin session) as follows:

$ gskkyman

Enter option 1 to create a new key database file.

Type a key database name or accept the default key.kdb.

Press Enter

Create a password to protect the key database.

Enter the database password for verification.

Type a password expiration interval in days or accept the default (no expiration date).

Type a database record length or accept the default 2500.
The key database is created and a message is displayed indicating the success or failure of this operation

From the Key Management menu, select option 6 to create a self-signed server certificate and follow the prompts.

After the certificate is created, you must extract this certificate so it can be sent to the LDAP client system and added as a trusted CA certificate. To do so, follow these steps:

Select option 1 to manage keys and certificates.

From the Key and Certificate List, enter the label number of the certificate to be exported.

From the Key and Certificate menu, enter option 6to export the certificate to a file.

From the Export File Format dialog, select the export format. For example, select option 1 to export to Binary ASN.1 DER.

Enter the export file name.

Results

The certificate is exported. You can now transfer the exported file to the LDAP client system and add it as a trusted CA certificate. Since the file format of binary DER is specified on the export, this same file type must be specified to the gsk7ikm utility on the LDAP client system during the Add operation.

Parent topic: Configuring IBM Security Directory Server for z/OS for SSL access

Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationMicrosoft Active Directory Lightweight Directory Service installation and configurationMicrosoft Active Directory Lightweight Directory Service installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.Microsoft Active Directory Lightweight Directory Servicesetting upuser registriesADLDSsetting upBefore you install Microsoft Active Directory Lightweight Directory Service, read Installing and configuring Active Directory Lightweight Directory Service (AD LDS)Install and configure Active Directory Lightweight Directory Service (AD LDS) so that you can use it as a user registry with Security Access Manager., which provides a summary of important Security Access Manager considerations and requirements when you install and configure AD LDS. For complete download, installation and configuration instructions, see the AD LDS documentation that is provided by Microsoft Corporation. User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.Installing and configuring Active Directory Lightweight Directory Service (AD LDS)Install and configure Active Directory Lightweight Directory Service (AD LDS) so that you can use it as a user registry with Security Access Manager.Installing Security Access Manager with support for Active Directory Lightweight Directory Service (AD LDS)To use AD LDS with Security Access Manager, you must copy the tam-adamschema.ldf file to the AD LDS server. This file can be obtained from the File Downloads section of the appliance in the isam folder.Configuring the Security Access Manager schemaSecurity Access Manager defines its own set of LDAP entry types and attributes that it uses to track user, group, and policy information. Add the Security Access Manager schema extensions so that Active Directory Lightweight Directory Service support is enabled.Management domain data locationThe user registry creates and stores metadata that tracks information about the Security Access Manager management domain. You must specify the location for the metadata storage.Configuring a Security Access Manager directory partitionBy default, Security Access Manager maintains its metadata information in a specific Active Directory Lightweight Directory Service (AD LDS) directory partition that is also known as a naming context or suffix. This default Security Access Manager metadata directory partition is called secAuthority=Default. To create the default Security Access Manager metadata directory partition, use the AD LDS administration tool ldp.exe. Adding an administrator to the Security Access Manager metadata directory partitionAfter you add a Security Access Manager schema to the Active Directory Lightweight Directory Service (AD LDS) instance and specified the Security Access Manager metadata directory location, you must add an AD LDS user administrator for the Security Access Manager metadata directory partition.Allowing anonymous bindIn order for Security Access Manager to be configured with Active Directory Lightweight Directory Service (AD LDS), AD LDS must be configured to allow anonymous bind.Configuring Active Directory Lightweight Directory Service (AD LDS) to use SSLEnable SSL to secure communication between the Active Directory Lightweight Directory Service and the Security Access Manager components.

Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

You must prepare the AD LDS server for use with Security Access Manager.

Before you install Microsoft Active Directory Lightweight Directory Service, read Installing and configuring Active Directory Lightweight Directory Service (AD LDS), which provides a summary of important Security Access Manager considerations and requirements when you install and configure AD LDS.

For complete download, installation and configuration instructions, see the AD LDS documentation that is provided by Microsoft Corporation.

Installing and configuring Active Directory Lightweight Directory Service (AD LDS)
Install and configure Active Directory Lightweight Directory Service (AD LDS) so that you can use it as a user registry with Security Access Manager.

Installing Security Access Manager with support for Active Directory Lightweight Directory Service (AD LDS)
To use AD LDS with Security Access Manager, you must copy the tam-adamschema.ldf file to the AD LDS server. This file can be obtained from the File Downloads section of the appliance in the isam folder.

Configuring the Security Access Manager schema
Security Access Manager defines its own set of LDAP entry types and attributes that it uses to track user, group, and policy information. Add the Security Access Manager schema extensions so that Active Directory Lightweight Directory Service support is enabled.

Management domain data location
The user registry creates and stores metadata that tracks information about the Security Access Manager management domain. You must specify the location for the metadata storage.

Configuring a Security Access Manager directory partition
By default, Security Access Manager maintains its metadata information in a specific Active Directory Lightweight Directory Service (AD LDS) directory partition that is also known as a naming context or suffix. This default Security Access Manager metadata directory partition is called secAuthority=Default. To create the default Security Access Manager metadata directory partition, use the AD LDS administration tool ldp.exe.

Adding an administrator to the Security Access Manager metadata directory partition
After you add a Security Access Manager schema to the Active Directory Lightweight Directory Service (AD LDS) instance and specified the Security Access Manager metadata directory location, you must add an AD LDS user administrator for the Security Access Manager metadata directory partition.

Allowing anonymous bind
In order for Security Access Manager to be configured with Active Directory Lightweight Directory Service (AD LDS), AD LDS must be configured to allow anonymous bind.

Configuring Active Directory Lightweight Directory Service (AD LDS) to use SSL
Enable SSL to secure communication between the Active Directory Lightweight Directory Service and the Security Access Manager components.

Parent topic: User registry server installation and configuration

Installing and configuring Active Directory Lightweight Directory Service (AD LDS) Installing and configuring Active Directory Lightweight Directory Service (AD LDS) for Security Access ManagerInstalling and configuring Active Directory Lightweight Directory Service (AD LDS) for Security Access ManagerInstall and configure Active Directory Lightweight Directory Service (AD LDS) so that you can use it as a user registry with Security Access Manager.Microsoft Active Directory Lightweight Directory ServiceoverviewLog on to the system by using an account that belongs to the local Administrators group. Use the Active Directory Lightweight Directory Service Setup Wizard to configure your AD LDS instance.When you create an AD LDS instance, you must specify an AD LDS instance name that is used to uniquely identify the instance and name the AD LDS service.Specify the ports that are used for both non-SSL and SSL connection types in the AD LDS instance. Make note of the port numbers you specify because they must be entered when you configure Security Access Manager.On the Application Directory Partition pane of the Active Directory Lightweight Directory Service Setup Wizard, create an application directory partition to contain the user and group definitions that you use.Below the directory partition, you can create other Directory Information Tree (DIT) entries as needed.On the File Locations pane, specify the directories that are used to store the files that are associated with this instance.On the Service Account Select pane, select the account that is used to assign permissions to this instance.On the AD LDS Administrators pane, select the account that has administrative control of this instance.On the Importing LDIF Files pane of the Active Directory Lightweight Directory Service Setup Wizard, import the following LDIF files to update the schema that is used by this instance of AD LDS:MS-InetOrgPerson.LDFMS-User.LDF MS-UserProxy.LDFWhen you finish installing AD LDS, ensure that the installation completed successfully and did not contain any errors. adamsetup.log and adamsetup_loader.log contain information that can help you troubleshoot AD LDS setup failure. Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Installing and configuring Active Directory Lightweight Directory Service (AD LDS)

Install and configure Active Directory Lightweight Directory Service (AD LDS) so that you can use it as a user registry with Security Access Manager.

Procedure

Log on to the system by using an account that belongs to the local Administrators group. Use the Active Directory Lightweight Directory Service Setup Wizard to configure your AD LDS instance.

When you create an AD LDS instance, you must specify an AD LDS instance name that is used to uniquely identify the instance and name the AD LDS service.

Specify the ports that are used for both non-SSL and SSL connection types in the AD LDS instance. Make note of the port numbers you specify because they must be entered when you configure Security Access Manager.

On the Application Directory Partition pane of the Active Directory Lightweight Directory Service Setup Wizard, create an application directory partition to contain the user and group definitions that you use.

Below the directory partition, you can create other Directory Information Tree (DIT) entries as needed.

On the File Locations pane, specify the directories that are used to store the files that are associated with this instance.

On the Service Account Select pane, select the account that is used to assign permissions to this instance.

On the AD LDS Administrators pane, select the account that has administrative control of this instance.

On the Importing LDIF Files pane of the Active Directory Lightweight Directory Service Setup Wizard, import the following LDIF files to update the schema that is used by this instance of AD LDS:

MS-InetOrgPerson.LDF

MS-User.LDF

MS-UserProxy.LDF

When you finish installing AD LDS, ensure that the installation completed successfully and did not contain any errors. adamsetup.log and adamsetup_loader.log contain information that can help you troubleshoot AD LDS setup failure.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Installing Security Access Manager with support for Active Directory Lightweight Directory Service (AD LDS)Installing Security Access Manager with support for Active Directory Lightweight Directory Service (AD LDS)Installing Security Access Manager with support for Active Directory Lightweight Directory Service (AD LDS)To use AD LDS with Security Access Manager, you must copy the tam-adamschema.ldf file to the AD LDS server. This file can be obtained from the File Downloads section of the appliance in the isam folder.Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Installing Security Access Manager with support for Active Directory Lightweight Directory Service (AD LDS)

To use AD LDS with Security Access Manager, you must copy the tam-adamschema.ldf file to the AD LDS server. This file can be obtained from the File Downloads section of the appliance in the isam folder.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Configuring the Security Access Manager schema Configuring the Security Access Manager schema for Active Directory Lightweight Directory Service (AD LDS)Configuring the Security Access Manager schema for Active Directory Lightweight Directory Service (AD LDS)Security Access Manager defines its own set of LDAP entry types and attributes that it uses to track user, group, and policy information. Add the Security Access Manager schema extensions so that Active Directory Lightweight Directory Service support is enabled.Microsoft Active Directory Lightweight Directory ServiceconfiguringMicrosoft Active Directory Lightweight Directory Serviceinstalling support forBefore you add Security Access Manager schema extensions, ensure that you defined inetOrgPerson and user schema definitions included with AD LDS. If the inetOrgPerson and user schema extensions are not added yet, they can also be added by using the ldifde.exe command-line tool and must be done before you add the Security Access Manager schema. toolsldifde.exeThese extensions to the basic LDAP server schema must be added to Active Directory Lightweight Directory Service (AD LDS) before you configure Security Access Manager. After you install AD LDS and configure the AD LDS instance by using the Active Directory Lightweight Directory Service Setup Wizard, the Security Access Manager schema extensions can be added to AD LDS by using the ldifde.exe command-line tool included with AD LDS.To add inetOrgPerson and user schema extensions, use the following procedure. After you run these commands, the AD LDS schema includes the AD LDS, inetOrgPerson, and user objectclasses and attribute definitions. If these schema extensions are already added, you can skip this procedure.Apply the tam-adamschema.ldf schema file on the AD LDS server.The file is in the downloads section of the appliance. In the local management interface, navigate to Manage System SettingsSecure SettingsFile Downloadsisam.Click StartAll ProgramsAccessories.Right-click Command Prompt.Change to the directory that houses the ldf files for AD LDS. The path is similar to the following line:C:\Windows\winsxs\amd64_microsoft-windows-d..services-adam-setup _31bf3856ad364e35_6.1.7600.16385_none_981a296d97d2c90aClick Run as administrator.At the command prompt, type the following command and then press Enter:ldifde –i –f ms-inetorgperson.ldf –s servername:portnumber –k –j . –c “CN=Schema,CN=Configuration,DC=X” #schemaNamingContext where servername represents the workstation name and portnumber is the LDAP connection port of your AD LDS instance. If AD LDS is running on your local workstation, you can also use localhost as the workstation name. Type the following command, and then press Enter: ldifde –i –f ms-user.ldf –s servername:portnumber –k –j . –c “CN=Schema,CN=Configuration,DC=X” #schemaNamingContext where servername represents the workstation name and portnumber is the LDAP connection port of your AD LDS instance. If AD LDS is running on your local workstation, you can also use localhost as the workstation name.After you ensured that the AD LDS schema includes the inetOrgPerson and user definitions, add the Security Access Manager schema extensions:Click StartAll ProgramsAccessories.Right-click Command Prompt.Click Run as administrator.Change to the directory that contains the tam-adamschema.ldf file.At the command prompt, type the following command and then press Enter:ldifde –i –e –f tam-adamschema.ldf –s servername:portnumber –k –j . –c “CN=Schema,CN=Configuration” #schemaNamingContext where servername represents the workstation name and portnumber is the LDAP connection port of your AD LDS instance. If AD LDS is running on your local workstation, you can also use localhost as the workstation name. The tam-adamschema.ldf file is included in the File Downloads area of the Security Access Manager appliance. Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Configuring the Security Access Manager schema

Security Access Manager defines its own set of LDAP entry types and attributes that it uses to track user, group, and policy information. Add the Security Access Manager schema extensions so that Active Directory Lightweight Directory Service support is enabled.

Before you begin

Before you add Security Access Manager schema extensions, ensure that you defined inetOrgPerson and user schema definitions included with AD LDS. If the inetOrgPerson and user schema extensions are not added yet, they can also be added by using the ldifde.exe command-line tool and must be done before you add the Security Access Manager schema.

About this task

These extensions to the basic LDAP server schema must be added to Active Directory Lightweight Directory Service (AD LDS) before you configure Security Access Manager.

After you install AD LDS and configure the AD LDS instance by using the Active Directory Lightweight Directory Service Setup Wizard, the Security Access Manager schema extensions can be added to AD LDS by using the ldifde.exe command-line tool included with AD LDS.

To add inetOrgPerson and user schema extensions, use the following procedure. After you run these commands, the AD LDS schema includes the AD LDS, inetOrgPerson, and user objectclasses and attribute definitions. If these schema extensions are already added, you can skip this procedure.

Procedure

Apply the tam-adamschema.ldf schema file on the AD LDS server.

Note: The file is in the downloads section of the appliance. In the local management interface, navigate to Manage System Settings > Secure Settings > File Downloads > isam.

Click Start > All Programs > Accessories.

Right-click Command Prompt.

Change to the directory that houses the ldf files for AD LDS. The path is similar to the following line:

C:\Windows\winsxs\amd64_microsoft-windows-d..services-adam-setup
_31bf3856ad364e35_6.1.7600.16385_none_981a296d97d2c90a

Click Run as administrator.

At the command prompt, type the following command and then press Enter:

ldifde –i –f ms-inetorgperson.ldf –s servername:portnumber –k –j . –c
	“CN=Schema,CN=Configuration,DC=X” #schemaNamingContext

where servername represents the workstation name and portnumber is the LDAP connection port of your AD LDS instance. If AD LDS is running on your local workstation, you can also use localhost as the workstation name.

Type the following command, and then press Enter:

ldifde –i –f ms-user.ldf –s servername:portnumber –k –j . –c
	“CN=Schema,CN=Configuration,DC=X” #schemaNamingContext

where servername represents the workstation name and portnumber is the LDAP connection port of your AD LDS instance. If AD LDS is running on your local workstation, you can also use localhost as the workstation name.

After you ensured that the AD LDS schema includes the inetOrgPerson and user definitions, add the Security Access Manager schema extensions:

Click Start > All Programs > Accessories.

Right-click Command Prompt.

Click Run as administrator.

Change to the directory that contains the tam-adamschema.ldf file.

At the command prompt, type the following command and then press Enter:

ldifde –i –e –f tam-adamschema.ldf –s servername:portnumber –k –j . –c
	“CN=Schema,CN=Configuration” #schemaNamingContext

where servername represents the workstation name and portnumber is the LDAP connection port of your AD LDS instance. If AD LDS is running on your local workstation, you can also use localhost as the workstation name. The tam-adamschema.ldf file is included in the File Downloads area of the Security Access Manager appliance.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Management domain data location Management domain data locationManagement domain data locationThe user registry creates and stores metadata that tracks information about the Security Access Manager management domain. You must specify the location for the metadata storage.Microsoft Active Directory Lightweight Directory Serviceconfiguring locationThe management domain is created when the Security Access Manager policy server is configured. The management domain is the initial security domain.During policy server configuration, the administrator specifies the name of the management domain or uses the default name of Default.The administrator also specifies the location in the registry where this metadata is stored by specifying the management domain location DN. The location that is specified must exist in the user registry. If the administrator chooses to use the default management domain location, the information is maintained in specific Active Directory Lightweight Directory Service (AD LDS) partition, which must be called secAuthority=management_domain_name where management_domain_name is the management domain name specified. For example, if the default management domain name is used, the partition would be called secAuthority=Default. If the administrator does not use the default location and specifies the management domain location DN, any existing location within the AD LDS registry can be used if it is a container object. You must choose a location DN within the same directory partition where the user and group information is stored. AD LDS requires the policy server to exist in the same directory partition as the user and group information. The policy server cannot maintain user and group information that is outside of the AD LDS directory partition where the policy server itself is defined. For this reason, do not use the default management location during policy server configuration when AD LDS is used as the Security Access Manager registry. Instead, choose a management domain location within the AD LDS partition in which you want to maintain the user and groups that reflects your enterprise structure.If you chose the default management location during policy server configuration, the option to permanently remove domain information from registry deletes all data in the AD LDS partition of the default domain management location, including registry-specific data, when you unconfigure the Security Access Manager. To retain registry-specific data, choose the management domain location in the AD LDS partition in which you want to maintain users and groups. The default management location is the location for Security Access Manager metadata.Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Management domain data location

The user registry creates and stores metadata that tracks information about the Security Access Manager management domain. You must specify the location for the metadata storage.

The management domain is created when the Security Access Manager policy server is configured. The management domain is the initial security domain.

During policy server configuration, the administrator specifies the name of the management domain or uses the default name of Default.

The administrator also specifies the location in the registry where this metadata is stored by specifying the management domain location DN. The location that is specified must exist in the user registry. If the administrator chooses to use the default management domain location, the information is maintained in specific Active Directory Lightweight Directory Service (AD LDS) partition, which must be called

secAuthority=management_domain_name

where management_domain_name is the management domain name specified. For example, if the default management domain name is used, the partition would be called secAuthority=Default. If the administrator does not use the default location and specifies the management domain location DN, any existing location within the AD LDS registry can be used if it is a container object.

Note: You must choose a location DN within the same directory partition where the user and group information is stored. AD LDS requires the policy server to exist in the same directory partition as the user and group information.

The policy server cannot maintain user and group information that is outside of the AD LDS directory partition where the policy server itself is defined.

For this reason, do not use the default management location during policy server configuration when AD LDS is used as the Security Access Manager registry. Instead, choose a management domain location within the AD LDS partition in which you want to maintain the user and groups that reflects your enterprise structure.

Attention: If you chose the default management location during policy server configuration, the option to permanently remove domain information from registry deletes all data in the AD LDS partition of the default domain management location, including registry-specific data, when you unconfigure the Security Access Manager. To retain registry-specific data, choose the management domain location in the AD LDS partition in which you want to maintain users and groups. The default management location is the location for Security Access Manager metadata.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Configuring a Security Access Manager directory partitionConfiguring a Security Access Manager directory partitionConfiguring a Security Access Manager directory partitionBy default, Security Access Manager maintains its metadata information in a specific Active Directory Lightweight Directory Service (AD LDS) directory partition that is also known as a naming context or suffix. This default Security Access Manager metadata directory partition is called secAuthority=Default. To create the default Security Access Manager metadata directory partition, use the AD LDS administration tool ldp.exe. Microsoft Active Directory Lightweight Directory Serviceconfiguring partition (default)Active Directory Lightweight Directory Service administration tooltoolsldp.exeMicrosoft Active Directory Lightweight Directory Serviceconfiguring partition (non-default)You must create the partition after the Security Access Manager schema extensions are added to AD LDS and before the Security Access Manager Policy Server is configured. For more information about adding schema extensions, see Configuring the Security Access Manager schemaSecurity Access Manager defines its own set of LDAP entry types and attributes that it uses to track user, group, and policy information. Add the Security Access Manager schema extensions so that Active Directory Lightweight Directory Service support is enabled..toolsThe ldp.exe tool is installed as part of the AD LDS administration tool set. To use theldp.exe tool, you must connect and bind to the AD LDS instance by using the following procedure.Alternatively, you can choose a non-default Management Domain name and location DN. The Management Domain name must be unique within the LDAP server and the location DN must exist. You must choose a location DN within the same directory partition where you store user and group information. This step is required because AD LDS requires that the policy server must exist in the same directory partition in which user and group information is maintained. The policy server cannot maintain user and group information outside the directory partition in which the policy server itself is defined. Connect to the AD LDS instance: At a command prompt, type ldp and then press ENTER. The ldp window is displayed.On the Connection menu, click Connect…. In the Server field, type the host or DNS name of the system that runs AD LDS. When the AD LDS instance is running locally, you can also type localhost for this field value. In the Port field, type the LDAP or SSL port number for the AD LDS instance to which you want to connect. Then, click OK. The ldp tool connects to the AD LDS instance and displays progress information that is obtained from the root DSE in the pane on the right side of the window. Bind to the AD LDS instance: From the Connection menu, select Bind… To bind by using the credentials that you are logged on with, click Bind as currently logged on user. When you are finished specifying bind options, click OK. The ldp tool binds the AD LDS instance by using the method and credentials specified. Add the children.From the Browse menu, select Add child. In the Dn field, type secAuthority=Default as the distinguished name for the new directory partition. In the Edit Entry field, type the following and then click ENTER. In the Attribute field, type ObjectClass. In the Values field, type secAuthorityInfo. In the Edit Entry field, type the following and then click ENTER. In the Attribute field, type secAuthority. In the Values field, type Default. In the Edit Entry field, type the following and then click ENTER. In the Attribute field, type version. In the Values field, type 8.0. In the Edit Entry field, type the following and then click ENTER.In the Attribute field, type cn In the Values field, type secAuthority In the Edit Entry field, type the following and then click ENTER. In the Attribute field, type instanceType. In the Values field, type 5. The set of attributes and values appear in the Entry List pane. Ensure the Synchronous option is selected and click Run. This step adds the Security Access Manager metadata directory partition to the AD LDS instance. To verify that the partition is properly added, you can use the AD LDS ADSI Edit tool to connect to and view the partition.Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Configuring a Security Access Manager directory partition

By default, Security Access Manager maintains its metadata information in a specific Active Directory Lightweight Directory Service (AD LDS) directory partition that is also known as a naming context or suffix. This default Security Access Manager metadata directory partition is called secAuthority=Default. To create the default Security Access Manager metadata directory partition, use the AD LDS administration tool ldp.exe.

About this task

You must create the partition after the Security Access Manager schema extensions are added to AD LDS and before the Security Access Manager Policy Server is configured. For more information about adding schema extensions, see Configuring the Security Access Manager schema.

The ldp.exe tool is installed as part of the AD LDS administration tool set. To use theldp.exe tool, you must connect and bind to the AD LDS instance by using the following procedure.

Alternatively, you can choose a non-default Management Domain name and location DN. The Management Domain name must be unique within the LDAP server and the location DN must exist.

Note: You must choose a location DN within the same directory partition where you store user and group information. This step is required because AD LDS requires that the policy server must exist in the same directory partition in which user and group information is maintained. The policy server cannot maintain user and group information outside the directory partition in which the policy server itself is defined.

Procedure

Connect to the AD LDS instance:

At a command prompt, type ldp and then press ENTER. The ldp window is displayed.

On the Connection menu, click Connect….

In the Server field, type the host or DNS name of the system that runs AD LDS. When the AD LDS instance is running locally, you can also type localhost for this field value.

In the Port field, type the LDAP or SSL port number for the AD LDS instance to which you want to connect. Then, click OK. The ldp tool connects to the AD LDS instance and displays progress information that is obtained from the root DSE in the pane on the right side of the window.

Bind to the AD LDS instance:

From the Connection menu, select Bind…

To bind by using the credentials that you are logged on with, click Bind as currently logged on user.

When you are finished specifying bind options, click OK. The ldp tool binds the AD LDS instance by using the method and credentials specified.

Add the children.

From the Browse menu, select Add child.

In the Dn field, type secAuthority=Default as the distinguished name for the new directory partition.

In the Edit Entry field, type the following and then click ENTER.

In the Attribute field, type ObjectClass.

In the Values field, type secAuthorityInfo.

In the Edit Entry field, type the following and then click ENTER.

In the Attribute field, type secAuthority.

In the Values field, type Default.

In the Edit Entry field, type the following and then click ENTER.

In the Attribute field, type version.

In the Values field, type 8.0.

In the Edit Entry field, type the following and then click ENTER.

In the Attribute field, type cn

In the Values field, type secAuthority

In the Edit Entry field, type the following and then click ENTER.

In the Attribute field, type instanceType.

In the Values field, type 5.

The set of attributes and values appear in the Entry List pane.

Ensure the Synchronous option is selected and click Run. This step adds the Security Access Manager metadata directory partition to the AD LDS instance. To verify that the partition is properly added, you can use the AD LDS ADSI Edit tool to connect to and view the partition.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Adding an administrator to the Security Access Manager metadata directory partitionAdding an administrator to the Security Access Manager metadata directory partitionAdding an administrator to the Security Access Manager metadata directory partitionAfter you add a Security Access Manager schema to the Active Directory Lightweight Directory Service (AD LDS) instance and specified the Security Access Manager metadata directory location, you must add an AD LDS user administrator for the Security Access Manager metadata directory partition.Microsoft Active Directory Lightweight Directory Serviceadding an administrator The AD LDS user has administrative authority for the Security Access Manager metadata directory partition and is specified as the LDAP administrator during Security Access Manager configuration. The following example assumes that you accepted the default management domain and location. If you specified a different domain name or location, add the AD LDS user administrator to the AD LDS partition you specified. Create the AD LDS LDAP administrator: Start the ADSI Edit program (Adsiedit.msc).On the Action menu, click Connect ToIn the Connection name field, you can type a label under which this connection appears in the console tree of AD LDS ADSI Edit. For this connection, type: secAuthority. Under Connection Point, enter secAuthority=Default in the Select or type a Distinguished Name or Naming Context section. If you use a different directory partition, select that partition. This example assumes the default partition. Under Computer, enter the server name and port for the AD LDS instance in the Select or type a domain or server section. If the AD LDS instance is on the local system, you can use localhost as the server name.Click OK. The term, secAuthority, must now appear in the console tree. Select user attributes: Expand the secAuthority tree by double-clicking secAuthority and then double-click SECAUTHORITY=DEFAULT.Highlight and right-click the SECAUTHORITY=DEFAULT container, point to New, and then click Object… Under Select a class, click user.Click Next. For the value of the cn attribute, type the common name for the administrator you want to create. For example, type tam.Click Next.Click More Attributes. Select and set the following properties:msDS-UserDontExpirePasswordSet to True. This setting prevents the default password expiration time policy from applying to this administrator. If you would prefer that the password policy applies to this administrator, then this property can be left unset. msDS-UserAccountDisabledSet to False. This setting enables the instance that you created.Click OK. No additional attributes are required but if you want to set more attributes, click More Attributes, select the attributes that you want to set and enter the values. When you are finished, click Finish. The user is created with a Distinguished Name (DN) of cn=tam,secAuthority=Default. To set the administrator password, highlight and then right-click the user that you created. Select Reset password… In the "Reset Password" pane, enter and confirm the password that you want to use. When finished, click OK. Remember the user DN and password that you create because these details are specified as the LDAP Administrator DN and password when Security Access Manager is configured.Add the user to the Administrators group for the partition: Within the SECAUTHORITY=DEFAULT directory partition, three containers are called CN=LostAndFound, CN=NTDSQuotas, and CN=Roles. Highlight the CN=Roles container by single clicking it. In the details pane on the right side of the AD LDS ADSI Edit tool, the groups within the Roles container are displayed. Highlight the CN=Administrators group by clicking it.Right-click on the CN=Administrators group and select Properties. The CN=Administrators Properties page is displayed. Under Attributes, scroll down and select the member attribute. Click Edit. Click Add DN. Type the distinguished name of the administrator user that you created into the DN field. Click OK. The administrator user is added to the Administrators group and is displayed as a member. Click OK to complete the membership update. Click OK.Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Adding an administrator to the Security Access Manager metadata directory partition

After you add a Security Access Manager schema to the Active Directory Lightweight Directory Service (AD LDS) instance and specified the Security Access Manager metadata directory location, you must add an AD LDS user administrator for the Security Access Manager metadata directory partition.

About this task

The AD LDS user has administrative authority for the Security Access Manager metadata directory partition and is specified as the LDAP administrator during Security Access Manager configuration. The following example assumes that you accepted the default management domain and location. If you specified a different domain name or location, add the AD LDS user administrator to the AD LDS partition you specified.

Procedure

Create the AD LDS LDAP administrator:

Start the ADSI Edit program (Adsiedit.msc).

On the Action menu, click Connect To

In the Connection name field, you can type a label under which this connection appears in the console tree of AD LDS ADSI Edit. For this connection, type: secAuthority.

Under Connection Point, enter "secAuthority=Default" in the Select or type a Distinguished Name or Naming Context section. If you use a different directory partition, select that partition. This example assumes the default partition.

Under Computer, enter the server name and port for the AD LDS instance in the Select or type a domain or server section. If the AD LDS instance is on the local system, you can use localhost as the server name.

Click OK. The term, secAuthority, must now appear in the console tree.

Select user attributes:

Expand the secAuthority tree by double-clicking secAuthority and then double-click SECAUTHORITY=DEFAULT.

Highlight and right-click the SECAUTHORITY=DEFAULT container, point to New, and then click Object…

Under Select a class, click user.

Click Next.

For the value of the cn attribute, type the common name for the administrator you want to create. For example, type tam.

Click Next.

Click More Attributes.

Select and set the following properties:

msDS-UserDontExpirePassword

Set to True. This setting prevents the default password expiration time policy from applying to this administrator. If you would prefer that the password policy applies to this administrator, then this property can be left unset.

msDS-UserAccountDisabled

Set to False. This setting enables the instance that you created.

Click OK.

No additional attributes are required but if you want to set more attributes, click More Attributes, select the attributes that you want to set and enter the values. When you are finished, click Finish. The user is created with a Distinguished Name (DN) of cn=tam,secAuthority=Default.

To set the administrator password, highlight and then right-click the user that you created. Select Reset password…

In the "Reset Password" pane, enter and confirm the password that you want to use. When finished, click OK. Remember the user DN and password that you create because these details are specified as the LDAP Administrator DN and password when Security Access Manager is configured.

Add the user to the Administrators group for the partition:

Within the SECAUTHORITY=DEFAULT directory partition, three containers are called CN=LostAndFound, CN=NTDSQuotas, and CN=Roles.

Highlight the CN=Roles container by single clicking it. In the details pane on the right side of the AD LDS ADSI Edit tool, the groups within the Roles container are displayed.

Highlight the CN=Administrators group by clicking it.

Right-click on the CN=Administrators group and select Properties. The CN=Administrators Properties page is displayed.

Under Attributes, scroll down and select the member attribute.

Click Edit.

Click Add DN. Type the distinguished name of the administrator user that you created into the DN field.

Click OK. The administrator user is added to the Administrators group and is displayed as a member.

Click OK to complete the membership update. Click OK.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Allowing anonymous bindAllowing anonymous bindAllowing anonymous bindIn order for Security Access Manager to be configured with Active Directory Lightweight Directory Service (AD LDS), AD LDS must be configured to allow anonymous bind.Microsoft Active Directory Lightweight Directory Serviceallowing anonymous bind By default, AD LDS does not allow anonymous bind. Security Access Manager configuration, however, uses anonymous bind to check on the validity of the configured LDAP host name, port, and SSL parameters. If you want to disable anonymous bind during normal operation, you can reset the option on the AD LDS server after configuration is complete. Start the ADSI Edit program Adsiedit.msc.On the Action menu, click Connect To. In the Connection name field, you can type a label under which this connection appears in the console tree of AD LDS ADSI Edit. For this connection, type: Configuration. Under Connection Point, select well known Naming Context and choose Configuration from the list.Under Computer, enter the server name and port for the AD LDS instance in the Select or type a domain or server section. If the AD LDS instance is on the local system, you can use localhost as the server name.Click OK. The term, Configuration, must now appear in the console tree. Expand the Configuration subtree by double-clicking Configuration.Double-click CN=Configuration,CN=GUID, where GUID was generated when the configuration of the AD LDS instance was performed. Double-click the CN=Services folder to expand it, and then double-click CN=Windows NT.Highlight and right-click CN=Directory Service and click Properties. Click dsHeuristics.Click Edit. Edit the value. Modify the seventh character (counting from the left) to 2. The value must be similar to 0000002001001 in the String Attribute Editor. Click OK. Click OK. Anonymous bind is now allowed.If you are setting up SSL communication, see Configuring Active Directory Lightweight Directory Service (AD LDS) to use SSLEnable SSL to secure communication between the Active Directory Lightweight Directory Service and the Security Access Manager components.. Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Allowing anonymous bind

In order for Security Access Manager to be configured with Active Directory Lightweight Directory Service (AD LDS), AD LDS must be configured to allow anonymous bind.

About this task

By default, AD LDS does not allow anonymous bind. Security Access Manager configuration, however, uses anonymous bind to check on the validity of the configured LDAP host name, port, and SSL parameters.

If you want to disable anonymous bind during normal operation, you can reset the option on the AD LDS server after configuration is complete.

Procedure

Start the ADSI Edit program Adsiedit.msc.

On the Action menu, click Connect To.

In the Connection name field, you can type a label under which this connection appears in the console tree of AD LDS ADSI Edit. For this connection, type: Configuration.

Under Connection Point, select well known Naming Context and choose Configuration from the list.

Under Computer, enter the server name and port for the AD LDS instance in the Select or type a domain or server section. If the AD LDS instance is on the local system, you can use localhost as the server name.

Click OK. The term, Configuration, must now appear in the console tree.

Expand the Configuration subtree by double-clicking Configuration.

Double-click CN=Configuration,CN=GUID, where GUID was generated when the configuration of the AD LDS instance was performed.

Double-click the CN=Services folder to expand it, and then double-click CN=Windows NT.

Highlight and right-click CN=Directory Service and click Properties.

Click dsHeuristics.

Click Edit.

Edit the value. Modify the seventh character (counting from the left) to 2. The value must be similar to 0000002001001 in the String Attribute Editor.

Click OK.

Click OK. Anonymous bind is now allowed.

What to do next

If you are setting up SSL communication, see Configuring Active Directory Lightweight Directory Service (AD LDS) to use SSL.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Configuring Active Directory Lightweight Directory Service (AD LDS) to use SSLConfiguring Active Directory Lightweight Directory Service (AD LDS) to use SSLConfiguring Active Directory Lightweight Directory Service (AD LDS) to use SSLEnable SSL to secure communication between the Active Directory Lightweight Directory Service and the Security Access Manager components.SSL configurationfor Active Directory Lightweight Directory ServiceMicrosoft Active Directory Lightweight Directory Serviceconfiguring SSL (example)Install and configure Active Directory Lightweight Directory Service, including the Internet Information Service and the Web Management Service.SSL encrypts the data that is transmitted between the Security Access Manager services and Active Directory Lightweight Directory Service. Consider enabling SSL to protect information such as user passwords and private data. SSL is not required for Security Access Manager to operate. The following task summarizes the steps that are required for enabling SSL communications. For details about enabling SSL on Active Directory Lightweight Directory Service, see the Microsoft documentation for Windows 2008 and Active Directory Lightweight Directory Service. Create a certificate that contains the public and private key on the computer where Active Directory Lightweight Directory Service is installed.Export the certificate with its private key.Locate the exported key file, double-click it, and install the certificate in all the folders in the Personal and Trusted Authorities folder.Using the mmc console, import this certificate into the Personal and Trusted Root certificate authorities folders for the Active Directory Lightweight Directory Service instance.Change the file permissions of the private keys in the certificate.See the Microsoft documentation for details.Restart the Active Directory Lightweight Directory Service instance.Using the mmc console, export the certificate (do not export the private key) from the AD_LDS_instance\Personal folder and save the certificate as a .cer file.Import the .cer file into an SSL certificate database on the appliance. Use this certificate to configure Security Access Manager with SSL enabled. Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configurationYou must prepare the AD LDS server for use with Security Access Manager.

Configuring Active Directory Lightweight Directory Service (AD LDS) to use SSL

Enable SSL to secure communication between the Active Directory Lightweight Directory Service and the Security Access Manager components.

Before you begin

Install and configure Active Directory Lightweight Directory Service, including the Internet Information Service and the Web Management Service.

About this task

SSL encrypts the data that is transmitted between the Security Access Manager services and Active Directory Lightweight Directory Service. Consider enabling SSL to protect information such as user passwords and private data. SSL is not required for Security Access Manager to operate.

The following task summarizes the steps that are required for enabling SSL communications.

Note: For details about enabling SSL on Active Directory Lightweight Directory Service, see the Microsoft documentation for Windows 2008 and Active Directory Lightweight Directory Service.

Procedure

Create a certificate that contains the public and private key on the computer where Active Directory Lightweight Directory Service is installed.

Export the certificate with its private key.

Locate the exported key file, double-click it, and install the certificate in all the folders in the Personal and Trusted Authorities folder.

Using the mmc console, import this certificate into the Personal and Trusted Root certificate authorities folders for the Active Directory Lightweight Directory Service instance.

Change the file permissions of the private keys in the certificate. See the Microsoft documentation for details.

Restart the Active Directory Lightweight Directory Service instance.

Using the mmc console, export the certificate (do not export the private key) from the AD_LDS_instance\Personal folder and save the certificate as a .cer file.

Import the .cer file into an SSL certificate database on the appliance. Use this certificate to configure Security Access Manager with SSL enabled.

Parent topic: Microsoft Active Directory Lightweight Directory Service (AD LDS) installation and configuration

Novell eDirectory installation and configurationNovell eDirectory installation and configurationNovell eDirectory installation and configurationYou can set up Novell eDirectory as the user registry in your Security Access Manager environment.Novell eDirectory serversetting upuser registriesNovell eDirectorysetting upNovell eDirectory serverdocumentationBefore you begin, ensure that you completed the basic server installation and configuration for Novell eDirectory and the ConsoleOne tool as described in the Novell product documentation.User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.Configuring the Novell eDirectory for Security Access ManagerIf you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed on the Novell eDirectory Server (NSD) automatically when the Security Access Manager policy server is configured. However, before you configure the policy server, you must make several modifications to Novell eDirectory server. Users and groups in Novell eDirectoryNovell eDirectory defines the objectclassesUser and Group as part of its base schema. Instances of the objectclasses are created when an eDirectory administrator defines a user or a group.Management domain locationSecurity Access Manager permits you to specify a management domain location that maintains Security Access Manager metadata unless you use the default management domain location. SSL access on Novell eDirectory serverSecure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.

Novell eDirectory installation and configuration

You can set up Novell eDirectory as the user registry in your Security Access Manager environment.

Before you begin, ensure that you completed the basic server installation and configuration for Novell eDirectory and the ConsoleOne tool as described in the Novell product documentation.

Configuring the Novell eDirectory for Security Access Manager
If you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed on the Novell eDirectory Server (NSD) automatically when the Security Access Manager policy server is configured. However, before you configure the policy server, you must make several modifications to Novell eDirectory server.

Users and groups in Novell eDirectory
Novell eDirectory defines the objectclassesUser and Group as part of its base schema. Instances of the objectclasses are created when an eDirectory administrator defines a user or a group.

Management domain location
Security Access Manager permits you to specify a management domain location that maintains Security Access Manager metadata unless you use the default management domain location.

SSL access on Novell eDirectory server
Secure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.

Parent topic: User registry server installation and configuration

Configuring the Novell eDirectory for Security Access ManagerConfiguring the Novell eDirectory for Security Access ManagerConfiguring the Novell eDirectory for Security Access ManagerIf you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed on the Novell eDirectory Server (NSD) automatically when the Security Access Manager policy server is configured. However, before you configure the policy server, you must make several modifications to Novell eDirectory server. Novell eDirectory serverconfiguringThe default Novell eDirectory schema assumes that the directory does not use the X.500 object classes of inetOrgPerson or groupOfNames. By default, these classes are mapped into the eDirectory classes of User and Group. Because Security Access Manager uses the inetOrgPerson and groupOfNames object classes for creating its own users and groups, modifications to the default eDirectory schema are required.You can configure the Novell eDirectory for Security Access Manager by using either of the following tools:Novell eDirectory ConsoleOne directory management utilityNovell iManager web-based administration consoleTo configure Novell eDirectory for Security Access Manager by using the Novell eDirectory ConsoleOne directory management utility, complete the following steps: ProcedureStart the Novell ConsoleOne directory management utility.Select the organization object within your Novell eDirectory tree. A list of objects is displayed on the right side of the ConsoleOne window.Right-click the LDAP group object (not LDAP server), and click Properties from the menu.Click the Class Map tab and the table of LDAP class names. The Novell eDirectory class names are displayed.Delete the entries with LDAP classes of inetOrgPerson and groupOfNames.Click Apply.Click Close.Click the Attribute Map tab and the table of LDAP attribute names. The Novell eDirectory attribute names are displayed.Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, then no change is needed. If the attribute is showing the default value of uniqueMember, you need to modify it as follows. Click Modify. The Attribute Mapping window is displayed.Change the Primary LDAP Attribute field from uniqueMember to member.Change the Secondary LDAP attribute field from member to uniqueMember.In the Attribute window, click OK to accept the changes. If you are using Solaris, proceed to the next step. If you are using Windows NT, you might add another mapping for the LDAP attribute ndsHomeDirectory as follows: On the right side of the Attribute Mappings window, click Add. The Attribute Mapping window repaints and is displayed again.From the Novell eDirectory NSD Attribute field menu, click Home Directory.In the Primary LDAP Attribute field, click ndsHomeDirectory.In the Attribute Mapping window, click OK to accept the changes.In the Properties window, click OK.To configure Novell eDirectory for Security Access Manager by using the Novell iManager web-based administration console, complete the following steps: ProcedureLaunch the iManager web page and log in as the administrator for the Novell eDirectory tree to be updated. Click the Roles and Tasks icon at the top of the iManager window to open the Roles and Tasks view.In the Roles and Tasks navigation frame, expand the LDAP category. In the expanded list, click the LDAP Options task.On the LDAP Options page, click the LDAP Group that is listed.If the LDAP group object is missing, make sure that the plug-ins for eDirectory were installed when eDirectory was installed. You can download the eDir_88_iMan27_Plugins.npm from the Novell Download Site at http://download.novell.com.Click Class Map to display the Novell eDirectory class to LDAP class mappings. Remove mappings to inetOrgPerson and groupOfNames. Scroll through the list and look for mappings of eDirectory classes to the LDAP class inetOrgPerson.If a mapping exists, select the row and click the Remove Mapping icon to remove the mapping.Click OK in the pop-up window to confirm the removal of the mapping.Click Apply to apply the changes.Repeat this step to remove a mapping for the LDAP class groupOfNames.Click OK, to accept the changes that you made.In the Roles and Tasks navigation frame, expand the LDAP category. In the expanded list, click the LDAP Options task.On the LDAP Options page, click the LDAP Group that is listed. Click Attribute Map to access the Novell eDirectory attribute to LDAP attribute mappings. Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, no change is needed. If the attribute is showing the default value of uniqueMember, you need to modify it as follows: Select the row and click the View/Edit Mapping icon.Change the Primary LDAP Attribute field from uniqueMember to member.Change the Secondary LDAP attribute field from member to uniqueMember.Click OK in the pop-up window to confirm the change.Click Apply to apply the changes.Enable LDAP clear-text passwords.Follow steps 1 - 10 of the Enabling LDAP Clear-Text Passwords procedure from the Novell Access Manager 3.1 Documentation section in 6.4.4 Configuring an Identity Injection Policy for Basic Authentication.If you are using Solaris, proceed to the next step. If you are using Windows, you might need to add another mapping for the LDAP attribute ndsHomeDirectory. To add another mapping for the LDAP attribute ndsHomeDirectory: Click the Add Mapping icon in the right side of the window. A pop-up window to define the mapping is displayed.In the eDirectory Attribute field, select Home Directory. In the Primary LDAP Attribute field, type ndsHomeDirectory.Click OK to confirm the mapping and close the pop-up window.Click OK in the Attribute Map window to accept the changes.After you set up Novell eDirectory for use with Security Access Manager, the next step is to set up the policy server. Novell eDirectory installation and configurationYou can set up Novell eDirectory as the user registry in your Security Access Manager environment.

Configuring the Novell eDirectory for Security Access Manager

If you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed on the Novell eDirectory Server (NSD) automatically when the Security Access Manager policy server is configured. However, before you configure the policy server, you must make several modifications to Novell eDirectory server.

About this task

Note: The default Novell eDirectory schema assumes that the directory does not use the X.500 object classes of inetOrgPerson or groupOfNames. By default, these classes are mapped into the eDirectory classes of User and Group. Because Security Access Manager uses the inetOrgPerson and groupOfNames object classes for creating its own users and groups, modifications to the default eDirectory schema are required.

You can configure the Novell eDirectory for Security Access Manager by using either of the following tools:

Novell eDirectory ConsoleOne directory management utility

Novell iManager web-based administration console

To configure Novell eDirectory for Security Access Manager by using the Novell eDirectory ConsoleOne directory management utility, complete the following steps:

Procedure

Start the Novell ConsoleOne directory management utility.

Select the organization object within your Novell eDirectory tree. A list of objects is displayed on the right side of the ConsoleOne window.

Right-click the LDAP group object (not LDAP server), and click Properties from the menu.

Click the Class Map tab and the table of LDAP class names. The Novell eDirectory class names are displayed.

Delete the entries with LDAP classes of inetOrgPerson and groupOfNames.

Click Apply.

Click Close.

Click the Attribute Map tab and the table of LDAP attribute names. The Novell eDirectory attribute names are displayed.

Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, then no change is needed. If the attribute is showing the default value of uniqueMember, you need to modify it as follows.

Click Modify. The Attribute Mapping window is displayed.

Change the Primary LDAP Attribute field from uniqueMember to member.

Change the Secondary LDAP attribute field from member to uniqueMember.

In the Attribute window, click OK to accept the changes.

If you are using Solaris, proceed to the next step. If you are using Windows NT, you might add another mapping for the LDAP attribute ndsHomeDirectory as follows:

On the right side of the Attribute Mappings window, click Add. The Attribute Mapping window repaints and is displayed again.

From the Novell eDirectory NSD Attribute field menu, click Home Directory.

In the Primary LDAP Attribute field, click ndsHomeDirectory.

In the Attribute Mapping window, click OK to accept the changes.

In the Properties window, click OK.

To configure Novell eDirectory for Security Access Manager by using the Novell iManager web-based administration console, complete the following steps:

Procedure

Launch the iManager web page and log in as the administrator for the Novell eDirectory tree to be updated.

Click the Roles and Tasks icon at the top of the iManager window to open the Roles and Tasks view.

In the Roles and Tasks navigation frame, expand the LDAP category.

In the expanded list, click the LDAP Options task.

On the LDAP Options page, click the LDAP Group that is listed.

Note: If the LDAP group object is missing, make sure that the plug-ins for eDirectory were installed when eDirectory was installed. You can download the eDir_88_iMan27_Plugins.npm from the Novell Download Site at http://download.novell.com.

Click Class Map to display the Novell eDirectory class to LDAP class mappings.

Remove mappings to inetOrgPerson and groupOfNames.

Scroll through the list and look for mappings of eDirectory classes to the LDAP class inetOrgPerson.

If a mapping exists, select the row and click the Remove Mapping icon to remove the mapping.

Click OK in the pop-up window to confirm the removal of the mapping.

Click Apply to apply the changes.

Repeat this step to remove a mapping for the LDAP class groupOfNames.

Click OK, to accept the changes that you made.

In the Roles and Tasks navigation frame, expand the LDAP category.

In the expanded list, click the LDAP Options task.

On the LDAP Options page, click the LDAP Group that is listed.

Click Attribute Map to access the Novell eDirectory attribute to LDAP attribute mappings.

Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, no change is needed. If the attribute is showing the default value of uniqueMember, you need to modify it as follows:

Select the row and click the View/Edit Mapping icon.

Change the Primary LDAP Attribute field from uniqueMember to member.

Change the Secondary LDAP attribute field from member to uniqueMember.

Click OK in the pop-up window to confirm the change.

Click Apply to apply the changes.

Enable LDAP clear-text passwords.

Follow steps 1 - 10 of the Enabling LDAP Clear-Text Passwords procedure from the Novell Access Manager 3.1 Documentation section in 6.4.4 Configuring an Identity Injection Policy for Basic Authentication.

If you are using Solaris, proceed to the next step. If you are using Windows, you might need to add another mapping for the LDAP attribute ndsHomeDirectory. To add another mapping for the LDAP attribute ndsHomeDirectory:

Click the Add Mapping icon in the right side of the window. A pop-up window to define the mapping is displayed.

In the eDirectory Attribute field, select Home Directory.

In the Primary LDAP Attribute field, type ndsHomeDirectory.

Click OK to confirm the mapping and close the pop-up window.

Click OK in the Attribute Map window to accept the changes.

After you set up Novell eDirectory for use with Security Access Manager, the next step is to set up the policy server.

Parent topic: Novell eDirectory installation and configuration

Users and groups in Novell eDirectoryUsers and groups in Novell eDirectoryUsers and groups in Novell eDirectoryNovell eDirectory defines the objectclassesUser and Group as part of its base schema. Instances of the objectclasses are created when an eDirectory administrator defines a user or a group.Novell eDirectory serveruse of objectclassesBoth of these objectclasses are defined by eDirectory as leaf nodes. eDirectory adds an attribute X-NDS_NOT_CONTAINER '1' to each of these objectclass definitions that specifies that they are not container objects. Objects that are not specified as container objects cannot be defined beneath instances of these objectclasses.Security Access Manager requires the ability to append its own objects beneath pre-existing eDirectory users and groups to import them and make them usable by Security Access Manager. When Security Access Manager adds its own objectclass definitions to the eDirectory schema, it also redefines the eDirectory User and Group objectclasses to allow instances of these classes to be container objects. Novell eDirectory allows this change to its schema definition.The following Novell eDirectory administrator actions cause the Security Access Manager modification to the User objectclass to be undone. The Group objectclass is not affected. toolseDirectory repairRunning the eDirectory database repair tool, ndsrepair by using the rebuild schema option.Running Basic Repair from the iManager console and running local database repair by using the rebuild operational schema option.Applying a patch update to Novell eDirectory. Upgrading Novell eDirectory to a more recent version. If it is necessary to perform any of these operations after Security Access Manager is configured into the eDirectory server, run the following Security Access Manager utility immediately to ensure that the definition of the User objectclass is restored. ivrgy_tool -h host -p port -D dn -w password schemawhere: hostSpecifies the LDAP server (Novell eDirectory) host name, which is required.portSpecifies the LDAP server (Novell eDirectory) port number.dnSpecifies the LDAP server (Novell eDirectory) bind distinguished name.passwordSpecifies the LDAP server (Novell eDirectory) bind password.schemaSpecifies the name of the Novell eDirectory schema file.The ivrgy_tool.exe is in the sbin subdirectory. For example:commandsivrgy_tool.exeivrgy_tool.exetoolsivrgy_tool On Windows systems: d:\Program Files\Tivoli\Policy Director\sbinOn AIX, Linux, or Solaris systems: /opt/PolicyDirector/sbinYou must run this utility from the sbin directory because Security Access Manager does not add the sbin directory to the system PATH. For more information about this utility, see the Reference topics in the IBM Knowledge Center.Novell eDirectory installation and configurationYou can set up Novell eDirectory as the user registry in your Security Access Manager environment.

Users and groups in Novell eDirectory

Novell eDirectory defines the objectclassesUser and Group as part of its base schema. Instances of the objectclasses are created when an eDirectory administrator defines a user or a group.

Both of these objectclasses are defined by eDirectory as leaf nodes. eDirectory adds an attribute X-NDS_NOT_CONTAINER '1' to each of these objectclass definitions that specifies that they are not container objects. Objects that are not specified as container objects cannot be defined beneath instances of these objectclasses.

Security Access Manager requires the ability to append its own objects beneath pre-existing eDirectory users and groups to import them and make them usable by Security Access Manager. When Security Access Manager adds its own objectclass definitions to the eDirectory schema, it also redefines the eDirectory User and Group objectclasses to allow instances of these classes to be container objects. Novell eDirectory allows this change to its schema definition.

The following Novell eDirectory administrator actions cause the Security Access Manager modification to the User objectclass to be undone. The Group objectclass is not affected.

Running the eDirectory database repair tool, ndsrepair by using the rebuild schema option.

Running Basic Repair from the iManager console and running local database repair by using the rebuild operational schema option.

Applying a patch update to Novell eDirectory.

Upgrading Novell eDirectory to a more recent version.

If it is necessary to perform any of these operations after Security Access Manager is configured into the eDirectory server, run the following Security Access Manager utility immediately to ensure that the definition of the User objectclass is restored.

ivrgy_tool -h host -p port -D dn -w password schema

where:

host

Specifies the LDAP server (Novell eDirectory) host name, which is required.

port

Specifies the LDAP server (Novell eDirectory) port number.

dn

Specifies the LDAP server (Novell eDirectory) bind distinguished name.

password

Specifies the LDAP server (Novell eDirectory) bind password.

schema

Specifies the name of the Novell eDirectory schema file.

The ivrgy_tool.exe is in the sbin subdirectory. For example:

On Windows systems: d:\Program Files\Tivoli\Policy Director\sbin

On AIX, Linux, or Solaris systems: /opt/PolicyDirector/sbin

You must run this utility from the sbin directory because Security Access Manager does not add the sbin directory to the system PATH. For more information about this utility, see the Reference topics in the IBM Knowledge Center.

Parent topic: Novell eDirectory installation and configuration

Management domain locationManagement domain locationManagement domain locationSecurity Access Manager permits you to specify a management domain location that maintains Security Access Manager metadata unless you use the default management domain location. Novell eDirectory serverdomain locationCreate this location in the Novell eDirectory server before you configure the Security Access Manager policy server.Security Access Manager extends the Novell eDirectory schema to add Security Access Manager metadata objectclasses and attributes. The secAuthorityInfo objectclass, a Security Access Manager-defined objectclass, is explicitly defined to be contained under the following common objectclasses: treeRootcontainerorganizationorganizationalUnitdomaincountryThe Novell eDirectory strictly enforces the containment rule. If you specify a management domain location with an objectclass other than the common objectclasses listed here, you must manually modify the schema file novschema.def to include the objectclass. You must modify the schema file before you configure the Security Access Manager.The complete Security Access Manager Novell eDirectory schema file path is [Security Access Manager installation directory]/etc/novschema.def. The following example illustrates how to modify the schema file.Open the schema file.Replace this portion: dn: cn=schema changetype: modify delete: objectclasses objectClasses: ( 1.3.6.1.4.1.4228.1.8 NAME 'secAuthorityInfo' DESC 'Security Authority Information' SUP 'eApplicationSystem' STRUCTURAL MUST ( secAuthority $ version ) X-NDS_NAMING 'secAuthority' X-NDS_CONTAINMENT ( 'treeRoot' ) ) - add: objectclasses objectClasses: ( 1.3.6.1.4.1.4228.1.8 NAME 'secAuthorityInfo' DESC 'Security Authority Information' SUP 'eApplicationSystem' STRUCTURAL MUST ( secAuthority $ version ) X-NDS_NAMING 'secAuthority' X-NDS_CONTAINMENT ( 'treeRoot' 'container' 'organization' 'organizationalUnit' 'domain' 'country') ) with dn: cn=schema changetype: modify delete: objectclasses objectClasses: ( 1.3.6.1.4.1.4228.1.8 NAME 'secAuthorityInfo' DESC 'Security Authority Information' SUP 'eApplicationSystem' STRUCTURAL MUST ( secAuthority $ version ) X-NDS_NAMING 'secAuthority' X-NDS_CONTAINMENT ( 'treeRoot' ) ) - add: objectclasses objectClasses: ( 1.3.6.1.4.1.4228.1.8 NAME 'secAuthorityInfo' DESC 'Security Authority Information' SUP 'eApplicationSystem' STRUCTURAL MUST ( secAuthority $ version ) X-NDS_NAMING 'secAuthority' X-NDS_CONTAINMENT ( 'treeRoot' 'container' 'organization' 'organizationalUnit' 'domain' 'country' 'your_object_class_goes_here') )For more information about management domains and creating a location for the metadata, see Security Access Manager management domainsIf you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources. and Management domain location exampleIf you want to specify a nondefault location for the management domain, you can use any location within the LDAP DIT..Novell eDirectory installation and configurationYou can set up Novell eDirectory as the user registry in your Security Access Manager environment.

Management domain location

Security Access Manager permits you to specify a management domain location that maintains Security Access Manager metadata unless you use the default management domain location.

Create this location in the Novell eDirectory server before you configure the Security Access Manager policy server.

Security Access Manager extends the Novell eDirectory schema to add Security Access Manager metadata objectclasses and attributes. The secAuthorityInfo objectclass, a Security Access Manager-defined objectclass, is explicitly defined to be contained under the following common objectclasses:

treeRoot

container

organization

organizationalUnit

domain

country

The Novell eDirectory strictly enforces the containment rule. If you specify a management domain location with an objectclass other than the common objectclasses listed here, you must manually modify the schema file novschema.def to include the objectclass.

Note: You must modify the schema file before you configure the Security Access Manager.

The complete Security Access Manager Novell eDirectory schema file path is [Security Access Manager installation directory]/etc/novschema.def. The following example illustrates how to modify the schema file.

Open the schema file.

Replace this portion:

dn: cn=schema
changetype: modify
delete: objectclasses
objectClasses: (
1.3.6.1.4.1.4228.1.8
NAME 'secAuthorityInfo'
DESC 'Security Authority Information'
SUP 'eApplicationSystem'
STRUCTURAL
MUST ( secAuthority $ version )
X-NDS_NAMING 'secAuthority'
X-NDS_CONTAINMENT ( 'treeRoot' )
 )
-
add: objectclasses
objectClasses: (
1.3.6.1.4.1.4228.1.8
NAME 'secAuthorityInfo'
DESC 'Security Authority Information'
SUP 'eApplicationSystem'
STRUCTURAL
MUST ( secAuthority $ version )
X-NDS_NAMING 'secAuthority'
X-NDS_CONTAINMENT ( 'treeRoot' 'container' 'organization'
 'organizationalUnit' 'domain' 'country')
 )

with

dn: cn=schema
changetype: modify
delete: objectclasses
objectClasses: (
1.3.6.1.4.1.4228.1.8
NAME 'secAuthorityInfo'
DESC 'Security Authority Information'
SUP 'eApplicationSystem'
STRUCTURAL
MUST ( secAuthority $ version )
X-NDS_NAMING 'secAuthority'
X-NDS_CONTAINMENT ( 'treeRoot' )
 )
-
add: objectclasses
objectClasses: (
1.3.6.1.4.1.4228.1.8
NAME 'secAuthorityInfo'
DESC 'Security Authority Information'
SUP 'eApplicationSystem'
STRUCTURAL
MUST ( secAuthority $ version )
X-NDS_NAMING 'secAuthority'
X-NDS_CONTAINMENT ( 'treeRoot' 'container' 'organization'
'organizationalUnit' 'domain' 'country'
 'your_object_class_goes_here')
 )

For more information about management domains and creating a location for the metadata, see Security Access Manager management domains and Management domain location example.

Parent topic: Novell eDirectory installation and configuration

SSL access on Novell eDirectory serverSSL access on Novell eDirectory serverSSL access on Novell eDirectory serverSecure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.SSL configurationfor Novell eDirectory serverSSL configurationfor Novell eDirectory serverNovell eDirectory serverconfiguring SSLAdministrators must enable SSL to protect information, such as user passwords and private data. However, SSL is not required for Security Access Manager to operate. If SSL is not required in your Security Access Manager environment, skip this section. Security Access Manager supports server-side authentication with Novell eDirectory only. To configure the Novell eDirectory server for SSL, ensure that the ConsoleOne tool is installed and complete the following sections. For more information, see the Novell product documentation.Novell eDirectory installation and configurationYou can set up Novell eDirectory as the user registry in your Security Access Manager environment.Creating an organizational certificate authority objectYou can ceate an NDSPKI:Certificate Authority object during installation of eDirectory by using ConsoleOne.Creating a self-signed certificateTo enable SSL, you need a certificate. You can create a self-signed certificate to meet this requirement.Creating a server certificate for the LDAP serverYou must create a server certificate for the LDAP server so that SSL is enabled.Enabling SSLUse the ConsoleOne so that you can enable SSL with Novell eDirectory.

SSL access on Novell eDirectory server

Secure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.

Administrators must enable SSL to protect information, such as user passwords and private data. However, SSL is not required for Security Access Manager to operate. If SSL is not required in your Security Access Manager environment, skip this section.

Security Access Manager supports server-side authentication with Novell eDirectory only. To configure the Novell eDirectory server for SSL, ensure that the ConsoleOne tool is installed and complete the following sections.

Note: For more information, see the Novell product documentation.

Creating an organizational certificate authority object
You can ceate an NDSPKI:Certificate Authority object during installation of eDirectory by using ConsoleOne.

Creating a self-signed certificate
To enable SSL, you need a certificate. You can create a self-signed certificate to meet this requirement.

Creating a server certificate for the LDAP server
You must create a server certificate for the LDAP server so that SSL is enabled.

Enabling SSL
Use the ConsoleOne so that you can enable SSL with Novell eDirectory.

Parent topic: Novell eDirectory installation and configuration

Creating an organizational certificate authority objectCreating an organizational certificate authority objectCreating an organizational certificate authority objectYou can ceate an NDSPKI:Certificate Authority object during installation of eDirectory by using ConsoleOne.certificatescreating authority objectorganizational certificate authority objectcertificate authority objectauthority objectNovell eDirectory servercreating organizational certificate authority objectThe subject name, not the object name, must be a valid signatory. The subject name must have an organization field and a country field to be recognized as valid by Security Access Manager. The default subject name is as follows: 0=organizational_entry_name.OU=Organizational DVDThis sample is not a valid signatory. To change it, you must re-create the certificate authority object with a valid subject name. To do so, follow these steps:Start ConsoleOne.Select the Security container object. Objects are displayed in the right pane of the window.Select the Organization CA object and delete it.Right-click the Security container object again and click New → Object. From the list box in the New Object dialog, double-click NDSPKI: certificate authority. The Create an Organizational Certificate Authority Object dialog is displayed. Follow the online instructions.Select the target server and enter an eDirectory object name. For example:Host Server Field = C22Knt_NDS.AMObject Name Field = C22KNT-CAIn Creation Method, select Custom.Click Next. Depending on the installed version of Novell eDirectory, two more screens might display. Click Next twice to continue.Accept the default Subject name or enter a valid distinguished name for the certificate authority that is being defined. All certificates that are generated by the certificate authority are placed in this location.The Organizational certificate authority is displayed in ConsoleOne as C22KNT-CA.SSL access on Novell eDirectory serverSecure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.

Creating an organizational certificate authority object

You can ceate an NDSPKI:Certificate Authority object during installation of eDirectory by using ConsoleOne.

About this task

The subject name, not the object name, must be a valid signatory. The subject name must have an organization field and a country field to be recognized as valid by Security Access Manager. The default subject name is as follows:

0=organizational_entry_name.OU=Organizational DVD

This sample is not a valid signatory. To change it, you must re-create the certificate authority object with a valid subject name. To do so, follow these steps:

Procedure

Start ConsoleOne.

Select the Security container object. Objects are displayed in the right pane of the window.

Select the Organization CA object and delete it.

Right-click the Security container object again and click New → Object.

From the list box in the New Object dialog, double-click NDSPKI: certificate authority. The Create an Organizational Certificate Authority Object dialog is displayed. Follow the online instructions.

Select the target server and enter an eDirectory object name.
For example:
Host Server Field = C22Knt_NDS.AM

Object Name Field = C22KNT-CA

In Creation Method, select Custom.

Click Next. Depending on the installed version of Novell eDirectory, two more screens might display.

Click Next twice to continue.

Accept the default Subject name or enter a valid distinguished name for the certificate authority that is being defined. All certificates that are generated by the certificate authority are placed in this location.

The Organizational certificate authority is displayed in ConsoleOne as C22KNT-CA.

Parent topic: SSL access on Novell eDirectory server

Creating a self-signed certificateCreating a self-signed certificateCreating a self-signed certificateTo enable SSL, you need a certificate. You can create a self-signed certificate to meet this requirement.certificatesextracting self-signed for Novell eDirectory serverself-signed certificatesNovell eDirectory serverNovell eDirectory serverextracting a self-signed certificateGo to the properties of the Organizational certificate authority C22KNT-CA. The Properties window is displayed.Select the Certificate tab and then select Self Signed Certificate from the menu.Validate the certificate.Export the certificate. The Export a Certificate window is displayed.Accept the default values and write down the location where the self-signed certificate is saved.For example: c:\c22knt\CA-SelfSignedCert.derTransfer (FTP) the file to the Security Access Manager host directory.For example: c:\Program Files\Tivoli\Policy Directory\keytab This file is a binary file.SSL access on Novell eDirectory serverSecure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.

Creating a self-signed certificate

To enable SSL, you need a certificate. You can create a self-signed certificate to meet this requirement.

Procedure

Go to the properties of the Organizational certificate authority C22KNT-CA. The Properties window is displayed.

Select the Certificate tab and then select Self Signed Certificate from the menu.

Validate the certificate.

Export the certificate. The Export a Certificate window is displayed.

Accept the default values and write down the location where the self-signed certificate is saved. For example:

c:\c22knt\CA-SelfSignedCert.der

Transfer (FTP) the file to the Security Access Manager host directory. For example:

c:\Program Files\Tivoli\Policy Directory\keytab

This file is a binary file.

Parent topic: SSL access on Novell eDirectory server

Creating a server certificate for the LDAP serverCreating a server certificate for the LDAP serverCreating a server certificate for the LDAP serverYou must create a server certificate for the LDAP server so that SSL is enabled.certificatescreating for LDAP serverTo create a server certificate for the LDAP server, right-click the Organization entry.Click New → Object. A New Object window is displayed.Select NDSPKI: Key Material.Click OK. The Create Server Certificate (Key Material) window is displayed.Enter the certificate name.For example, AMSelect Custom for the creation method.Click Next.Use the default values for Specify the certificate authority option, which signs the certificate.Click Next.Specify the key size, and accept default values for all other options.Click Next.The default key size for Novell eDirectory Version 8.6.2 is 1024 bits; 2048 bits for Version 8.7.In the Specify the Certificate Parameters window, click Edit next to the Subject Name field. The Edit Subject window is displayed.Enter the subject name.Click OK. The Create Server Certificate (Key Material) window is displayed with the Subject Name field updated. Click Next to continue.To accept the default values in the following windows, click Next twice.Click Finish to create a key material.The Creating Certificate window is temporarily displayed. When it clears, the right pane of ConsoleOne is updated with a Key Material entry named AM. This entry is the server certificate.SSL access on Novell eDirectory serverSecure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.

Creating a server certificate for the LDAP server

You must create a server certificate for the LDAP server so that SSL is enabled.

Procedure

To create a server certificate for the LDAP server, right-click the Organization entry.

Click New → Object. A New Object window is displayed.

Select NDSPKI: Key Material.

Click OK. The Create Server Certificate (Key Material) window is displayed.

Enter the certificate name. For example, AM

Select Custom for the creation method.

Click Next.

Use the default values for Specify the certificate authority option, which signs the certificate.

Click Next.

Specify the key size, and accept default values for all other options.

Click Next.

Note: The default key size for Novell eDirectory Version 8.6.2 is 1024 bits; 2048 bits for Version 8.7.

In the Specify the Certificate Parameters window, click Edit next to the Subject Name field. The Edit Subject window is displayed.

Enter the subject name.

Click OK. The Create Server Certificate (Key Material) window is displayed with the Subject Name field updated.

Click Next to continue.

To accept the default values in the following windows, click Next twice.

Click Finish to create a key material. The Creating Certificate window is temporarily displayed. When it clears, the right pane of ConsoleOne is updated with a Key Material entry named AM. This entry is the server certificate.

Parent topic: SSL access on Novell eDirectory server

Enabling SSLEnabling SSLEnabling SSLUse the ConsoleOne so that you can enable SSL with Novell eDirectory.SSLenabling for NovellIn the right pane of ConsoleOne, locate an entry that is named LDAP Server – hostname and right-click it.From the menu, select Properties. From the Properties notebook, select the SSL Configuration tab.Click the Tree Search icon next to the SSL Certificate field. The Select SSL Certificate window is displayed. The SSL Certificate List pane displays the certificates that are known to the organization.Select the AM certificate.Click OK. The Properties of LDAP Server – hostname window is redisplayed with an updated SSL Certificate field.Copy the signer certificate and have it available to copy to the Security Access Manager servers that you want to set up SSL communication with.SSL access on Novell eDirectory serverSecure Socket Layer (SSL) allows the data, which is transmitted between the Security Access Manager services and the Novell eDirectory server, to be encrypted to provide data privacy and integrity.

Enabling SSL

Use the ConsoleOne so that you can enable SSL with Novell eDirectory.

Procedure

In the right pane of ConsoleOne, locate an entry that is named LDAP Server – hostname and right-click it.

From the menu, select Properties. From the Properties notebook, select the SSL Configuration tab.

Click the Tree Search icon next to the SSL Certificate field. The Select SSL Certificate window is displayed. The SSL Certificate List pane displays the certificates that are known to the organization.

Select the AM certificate.

Click OK. The Properties of LDAP Server – hostname window is redisplayed with an updated SSL Certificate field.

Copy the signer certificate and have it available to copy to the Security Access Manager servers that you want to set up SSL communication with.

Parent topic: SSL access on Novell eDirectory server

Installing and configuring the Sun Java System Directory ServerInstalling and configuring the Sun Java System Directory ServerInstalling and configuring the Sun Java System Directory ServerYou can use a supported version of Sun Java System Directory Server as the user registry for Security Access Manager.Sun Java System Directory Serversetting upuser registriesSun Java System Directory Serversetting upsuffixesadding to Sun Java System Directory ServerReview the User registry considerationsSecurity Access Manager supports several LDAP registries. Before you configure a registry, consider the naming limitations, how the LDAP registry works with Security Access Manager in your environment, and the requirements for specific registries. before you configure the Sun Java System Directory Server in your environment:Complete the basic server installation and configuration as described in the Sun Java System Directory Server product documentation. For example, for Sun Java System Directory Server version 7.0, see: Installation GuideAdministration GuideThen, use the same documentation to create a suffix for Security Access Manager. Create the management domain location that maintains Security Access Manager data. Use the suffix DN of the location; for example: secAuthority=Default. The name must be in the relative distinguished name (DN) format and consist of one attribute-value pair. If multiple attribute-value pairs, separate the pairs by commas. The default location is secAuthority=Default. For more information about management domains, and creating a location for the metadata, see:Security Access Manager management domainsIf you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources. Management domain location exampleIf you want to specify a nondefault location for the management domain, you can use any location within the LDAP DIT. Change the name of the database when you create a suffix.Do not accept the default value for the database name when you create a suffix. By default, the location of database files for this suffix is chosen automatically by the server. By default, the suffix maintains only the system indexes. No attributes are encrypted, and replication is not configured. If you accept the default value, the Sun Java Directory Server stores the suffix under the Default database name. Your data is removed when the Sun Java Directory Server is restarted.Ensure that the suffix was created. If you chose to create a suffix to maintain user and group data, follow this procedure again to create another suffix either in the default database or in a new database. For example, you might create a suffix that are named o=ibm,c=us in the same database.Complete the appropriate action:If you did not add any suffixes other than the management domain location, configuration is complete. A directory entry for the management domain location is automatically added when the policy server is configured.If you added suffixes other than the management domain location, create directory entries for each new suffix.If you want to enable SSL communication between the Directory Server and Security Access Manager, continue with the remaining steps:Start the instance of the Sun Java System Directory Server.Obtain a certificate for the instance and store it in the key database. The certificate can be issued by a certificate authority (CA) or it can be self-signed. The certificate includes a server certificate and a private key. Use the methods that are described in the Sun Java System Directory Server documentation.Make a note of the secure SSL port number on the server. The default port number is 636.Obtain the signer certificate.If the certificate is issued by a CA, the server certificate includes a signer certificate. If the certificate is self-signed, the server certificate acts as the signer certificate.Copy the signer certificate to a temporary directory on the computer where Security Access Manager components are installed and with which you want to enable SSL communication. After you set up the Directory Server for use with Security Access Manager, you can set up the policy server. Use the following values in your configuration:Value of LDAP administrator ID for the Sun Directory Server is cn=Directory Manager. The default value for this attribute is cn=root, however, it is not appropriate for the Sun Directory Server. Value of LDAP management domain location DN for the Sun Directory Server is a suffix (for example, dc=ibm,dc=isam) created under the directory instance. The default value for this attribute is blank and it is not appropriate for the Sun Directory Server.User registry server installation and configurationSet up a registry server for use with Security Access Manager so that you can establish a management domain.

Installing and configuring the Sun Java System Directory Server

You can use a supported version of Sun Java System Directory Server as the user registry for Security Access Manager.

Before you begin

Review the User registry considerations before you configure the Sun Java System Directory Server in your environment:

About this task

Complete the basic server installation and configuration as described in the Sun Java™ System Directory Server product documentation. For example, for Sun Java System Directory Server version 7.0, see:

Installation Guide

Administration Guide

Then, use the same documentation to create a suffix for Security Access Manager.

Procedure

Create the management domain location that maintains Security Access Manager data.

Use the suffix DN of the location; for example: secAuthority=Default.

The name must be in the relative distinguished name (DN) format and consist of one attribute-value pair. If multiple attribute-value pairs, separate the pairs by commas. The default location is secAuthority=Default.

For more information about management domains, and creating a location for the metadata, see:

Security Access Manager management domains

Management domain location example

Change the name of the database when you create a suffix.

Attention: Do not accept the default value for the database name when you create a suffix. By default, the location of database files for this suffix is chosen automatically by the server. By default, the suffix maintains only the system indexes. No attributes are encrypted, and replication is not configured. If you accept the default value, the Sun Java Directory Server stores the suffix under the Default database name. Your data is removed when the Sun Java Directory Server is restarted.

Ensure that the suffix was created. If you chose to create a suffix to maintain user and group data, follow this procedure again to create another suffix either in the default database or in a new database. For example, you might create a suffix that are named o=ibm,c=us in the same database.

Complete the appropriate action:

If you did not add any suffixes other than the management domain location, configuration is complete. A directory entry for the management domain location is automatically added when the policy server is configured.

If you added suffixes other than the management domain location, create directory entries for each new suffix.

If you want to enable SSL communication between the Directory Server and Security Access Manager, continue with the remaining steps:

Start the instance of the Sun Java System Directory Server.

Obtain a certificate for the instance and store it in the key database. The certificate can be issued by a certificate authority (CA) or it can be self-signed. The certificate includes a server certificate and a private key. Use the methods that are described in the Sun Java System Directory Server documentation.

Make a note of the secure SSL port number on the server. The default port number is 636.

Obtain the signer certificate.

Note: If the certificate is issued by a CA, the server certificate includes a signer certificate. If the certificate is self-signed, the server certificate acts as the signer certificate.

Copy the signer certificate to a temporary directory on the computer where Security Access Manager components are installed and with which you want to enable SSL communication.

What to do next

After you set up the Directory Server for use with Security Access Manager, you can set up the policy server. Use the following values in your configuration:

Value of LDAP administrator ID for the Sun Directory Server is cn=Directory Manager. The default value for this attribute is cn=root, however, it is not appropriate for the Sun Directory Server.

Value of LDAP management domain location DN for the Sun Directory Server is a suffix (for example, dc=ibm,dc=isam) created under the directory instance. The default value for this attribute is blank and it is not appropriate for the Sun Directory Server.

Parent topic: User registry server installation and configuration

Security Access Manager management domainsSecurity Access Manager management domainsSecurity Access Manager management domainsIf you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources. management domainspolicy serverDepending on the installed resource managers, resources can be any physical or logical entity, including objects such as files, directories, web pages, printer and network services, and message queues. Any security policy that is implemented in a domain affects only the objects in that domain. Users with authority to complete tasks in one domain do not necessarily have the authority to complete those tasks in other domains.The initial domain in an LDAP registry is called the management domain and is created when the policy server is configured. During policy server configuration, you are prompted for the management domain name and the management domain location Distinguished Name (DN) within the LDAP Directory Information Tree (DIT) on the LDAP server where the information about the domain is maintained. If the management domain location is not specified, the management domain location is assumed to be a stand-alone suffix on the LDAP server. Whether you use the default location or specify a different location in the LDAP DIT, the location that is specified for the management domain must exist unless the user registry is Novell eDirectory. For Novell eDirectory, if you do not specify the management domain location, Security Access Manager uses the root location as the management domain location. The root location is a domain location that does not have a suffix. If you enter a specific location for the management domain, ensure that the location you are specifying exists.When a Security Access Manager domain is created, including the initial management domain, an entry is created in the LDAP server that is called a secAuthorityInfo object. This object represents the Security Access Manager domain and is named according to the secAuthority attribute with the name of the domain as its value; for example: secAuthority=<domain_name>.If you do not provide a different name, the default name of the management domain is Default, making the secAuthorityInfo object name secAuthority=Default.User registry configurationUse the topics in this hierarchy to configure user registries for IBM Security Access Manager.Management domain location exampleIf you want to specify a nondefault location for the management domain, you can use any location within the LDAP DIT.Management domain location for an Active Directory Lightweight Directory Service (AD LDS) registryIf Active Directory Lightweight Directory Service (AD LDS) is being used as the LDAP registry, you must choose a location DN within the same directory partition where you want to store user and group information.

Security Access Manager management domains

If you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources.

Depending on the installed resource managers, resources can be any physical or logical entity, including objects such as files, directories, web pages, printer and network services, and message queues. Any security policy that is implemented in a domain affects only the objects in that domain. Users with authority to complete tasks in one domain do not necessarily have the authority to complete those tasks in other domains.

The initial domain in an LDAP registry is called the management domain and is created when the policy server is configured. During policy server configuration, you are prompted for the management domain name and the management domain location Distinguished Name (DN) within the LDAP Directory Information Tree (DIT) on the LDAP server where the information about the domain is maintained.

If the management domain location is not specified, the management domain location is assumed to be a stand-alone suffix on the LDAP server. Whether you use the default location or specify a different location in the LDAP DIT, the location that is specified for the management domain must exist unless the user registry is Novell eDirectory. For Novell eDirectory, if you do not specify the management domain location, Security Access Manager uses the root location as the management domain location. The root location is a domain location that does not have a suffix. If you enter a specific location for the management domain, ensure that the location you are specifying exists.

When a Security Access Manager domain is created, including the initial management domain, an entry is created in the LDAP server that is called a secAuthorityInfo object. This object represents the Security Access Manager domain and is named according to the secAuthority attribute with the name of the domain as its value; for example: secAuthority=<domain_name>.

If you do not provide a different name, the default name of the management domain is Default, making the secAuthorityInfo object name secAuthority=Default.

Management domain location example
If you want to specify a nondefault location for the management domain, you can use any location within the LDAP DIT.

Management domain location for an Active Directory Lightweight Directory Service (AD LDS) registry
If Active Directory Lightweight Directory Service (AD LDS) is being used as the LDAP registry, you must choose a location DN within the same directory partition where you want to store user and group information.

Parent topic: User registry configuration

Management domain location exampleManagement domain location exampleManagement domain location exampleIf you want to specify a nondefault location for the management domain, you can use any location within the LDAP DIT.management domainscreatingFor example, if the LDAP server is configured with a suffix of c=us, and the administrator specifies the management domain location DN as ou=austin,o=ibm,c=us, this object might be created by using a file that contains the following LDIF: dn: c=us objectClass: top objectClass: country c: US dn: o=ibm,c=us objectClass: top objectClass: organization o: IBM dn: ou=austin,o=ibm,c=us objectClass: top objectClass: organizationalunit ou: Austin The object might then be created by using the idsldapadd command-line utility as follows: idsldapadd –h <ldap_hostname> -p <ldap_port> -D <ldap_admin_DN> -w <ldap_admin_pwd> -v –f example_DITwhere: ldap_hostname is the host name of the LDAP server.ldap_port is the port of the LDAP server.ldap_admin_DN is the Distinguished Name of the LDAP server administrator.ldap_admin_pwd is the password of the LDAP server administrator. example_DIT is the name of the file that contains the LDIF. Modify this example for the specific LDAP namespace appropriate for your organization. After the LDAP object is created, you can specify it as the management domain location DN during policy server configuration. If the following conditions exist, a WebSEAL instance cannot change user passwords because of the absence of ACL settings that are required to search domain locations: You configured the policy server in a nondefault location that is a location other than secAuthority=Default.You create Security Access Manager subdomains under the new location.You configured a WebSEAL instance in any of the new subdomains.If you configure the policy server in a nondefault location and find that these other conditions exist, see the Troubleshooting topics in the IBM Knowledge Center for information about setting the correct ACL. Security Access Manager management domainsIf you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources.

Management domain location example

If you want to specify a nondefault location for the management domain, you can use any location within the LDAP DIT.

For example, if the LDAP server is configured with a suffix of c=us, and the administrator specifies the management domain location DN as ou=austin,o=ibm,c=us, this object might be created by using a file that contains the following LDIF:

dn: c=us
objectClass: top
objectClass: country
c: US

dn: o=ibm,c=us
objectClass: top
objectClass: organization
o: IBM

dn: ou=austin,o=ibm,c=us
objectClass: top
objectClass: organizationalunit
ou: Austin

The object might then be created by using the idsldapadd command-line utility as follows:

 idsldapadd –h <ldap_hostname> -p <ldap_port> -D <ldap_admin_DN>
	-w <ldap_admin_pwd> -v –f example_DIT

where:

ldap_hostname is the host name of the LDAP server.

ldap_port is the port of the LDAP server.

ldap_admin_DN is the Distinguished Name of the LDAP server administrator.

ldap_admin_pwd is the password of the LDAP server administrator.

example_DIT is the name of the file that contains the LDIF.

Modify this example for the specific LDAP namespace appropriate for your organization.

After the LDAP object is created, you can specify it as the management domain location DN during policy server configuration.

Note:

If the following conditions exist, a WebSEAL instance cannot change user passwords because of the absence of ACL settings that are required to search domain locations:

You configured the policy server in a nondefault location that is a location other than secAuthority=Default.

You create Security Access Manager subdomains under the new location.

You configured a WebSEAL instance in any of the new subdomains.

If you configure the policy server in a nondefault location and find that these other conditions exist, see the Troubleshooting topics in the IBM Knowledge Center for information about setting the correct ACL.

Parent topic: Security Access Manager management domains

Management domain location for an Active Directory Lightweight Directory Service (AD LDS) registryManagement domain location for an Active Directory Lightweight Directory Service (AD LDS) registryManagement domain location for an Active Directory Lightweight Directory Service (AD LDS) registryIf Active Directory Lightweight Directory Service (AD LDS) is being used as the LDAP registry, you must choose a location DN within the same directory partition where you want to store user and group information.management domainslocation for Active Directory Lightweight Directory Service registryMicrosoft Active Directory Lightweight Directory Servicemanagement domain location forAD LDS has a restriction that the policy server must exist in the same directory partition in which user and group information is maintained. The policy server cannot maintain user and group information outside the directory partition in which the policy server itself is defined. Security Access Manager management domainsIf you use LDAP as your user registry, Security Access Manager provides for one or more administrative domains. A domain consists of all the users, groups, and resources that require protection along with the associated security policy used to protect those resources.

Management domain location for an Active Directory Lightweight Directory Service (AD LDS) registry

If Active Directory Lightweight Directory Service (AD LDS) is being used as the LDAP registry, you must choose a location DN within the same directory partition where you want to store user and group information.

AD LDS has a restriction that the policy server must exist in the same directory partition in which user and group information is maintained. The policy server cannot maintain user and group information outside the directory partition in which the policy server itself is defined.

Parent topic: Security Access Manager management domains

Security Directory Server proxy environment setupSecurity Directory Server proxy environment setupSecurity Directory Server proxy environment setupA Security Directory Server proxy is a special type of IBM Security Directory Server that provides request routing, load balancing, fail over, distributed authentication and support for distributed/membership groups and partitioning of containers.proxy serverssetting upIBM Security Access Manager customers who want to use the Security Directory Server proxy server must purchase a separate Security Directory Server entitlement. The version of Security Directory Server that is part of the Security Access Manager package does not allow IBM Security Access Manager customer-use of the Security Directory Server proxy server.If you have the appropriate entitlement, see the proxy server instructions in the IBM Security Directory Server Administration Guide.Then, return to this document for instructions about setting up the proxy server to work with IBM Security Access Manager.Security Access Manager stores its metadata within a required suffix called secAuthority=Default. Metadata includes information that is used to track user and group status information specific to Security Access Manager. When you use a proxy, the secAuthority=Default object itself cannot be modified by using the proxy because the object at a proxy partition split point cannot be modified through the proxy. Therefore, Security Access Manager cannot be configured directly through the proxy because Security Access Manager must modify the secAuthority=Default object during configuration.In a proxy environment, the administrator must decide on the back-end server that the secAuthority=Default subtree is hosted and set up that back-end server and the proxy partition information to reflect that topology. This example configures Server A to host the secAuthority=Default subtree.Data under a proxy partition split point (for example, o=ibm,c=us) is hashed to determine which back-end server has the subtree. In this example, Proxy is configured to hash RDN values immediately after o=ibm,c=us among two servers. This example also means the RDN values more than 1 away from o=ibm,c=us will map to the same server as values immediately after o=ibm,c=us. For this reason, it is more advantageous to configure the proxy with a single partition for the secAuthority=Default suffix. If you want to distribute the Security Access Manager metadata within the secAuthority=Default suffix among multiple back-end servers, it is best to split the partition below the cn=Users,secAuthority=Default container. Entries are made on behalf of each user who is defined, below the cn=Users,secAuthority=Default container and therefore splitting this user information can help distribute the data more evenly across the back-end servers. This example does not distribute the data but instead maintain the entire secAuthority=Default subtree within Server A.User registry configurationUse the topics in this hierarchy to configure user registries for IBM Security Access Manager.Adding the Security Access Manager suffix to the proxyFor the proxy to work with Security Access Manager, you must configure the secAuthority=Default suffix.Security Access Manager configuration with the proxyAfter the Security Directory Server proxy server and back-end servers are configured with the Directory Information Tree (DIT) partitioning setup, you can configureSecurity Access Manager to use the proxy. The proxy server provides a unified view of the directory and shields the LDAP application (Security Access Manager for example) from having to be aware of the DIT partitioning.

Security Directory Server proxy environment setup

A Security Directory Server proxy is a special type of IBM® Security Directory Server that provides request routing, load balancing, fail over, distributed authentication and support for distributed/membership groups and partitioning of containers.

Attention: IBM Security Access Manager customers who want to use the Security Directory Server proxy server must purchase a separate Security Directory Server entitlement. The version of Security Directory Server that is part of the Security Access Manager package does not allow IBM Security Access Manager customer-use of the Security Directory Server proxy server.

If you have the appropriate entitlement, see the proxy server instructions in the IBM Security Directory Server Administration Guide.

Then, return to this document for instructions about setting up the proxy server to work with IBM Security Access Manager.

Security Access Manager stores its metadata within a required suffix called secAuthority=Default. Metadata includes information that is used to track user and group status information specific to Security Access Manager. When you use a proxy, the secAuthority=Default object itself cannot be modified by using the proxy because the object at a proxy partition split point cannot be modified through the proxy. Therefore, Security Access Manager cannot be configured directly through the proxy because Security Access Manager must modify the secAuthority=Default object during configuration.

In a proxy environment, the administrator must decide on the back-end server that the secAuthority=Default subtree is hosted and set up that back-end server and the proxy partition information to reflect that topology. This example configures Server A to host the secAuthority=Default subtree.

Data under a proxy partition split point (for example, o=ibm,c=us) is hashed to determine which back-end server has the subtree. In this example, Proxy is configured to hash RDN values immediately after o=ibm,c=us among two servers. This example also means the RDN values more than 1 away from o=ibm,c=us will map to the same server as values immediately after o=ibm,c=us. For this reason, it is more advantageous to configure the proxy with a single partition for the secAuthority=Default suffix.

If you want to distribute the Security Access Manager metadata within the secAuthority=Default suffix among multiple back-end servers, it is best to split the partition below the cn=Users,secAuthority=Default container. Entries are made on behalf of each user who is defined, below the cn=Users,secAuthority=Default container and therefore splitting this user information can help distribute the data more evenly across the back-end servers. This example does not distribute the data but instead maintain the entire secAuthority=Default subtree within Server A.

Adding the Security Access Manager suffix to the proxy
For the proxy to work with Security Access Manager, you must configure the secAuthority=Default suffix.

Security Access Manager configuration with the proxy
After the Security Directory Server proxy server and back-end servers are configured with the Directory Information Tree (DIT) partitioning setup, you can configureSecurity Access Manager to use the proxy. The proxy server provides a unified view of the directory and shields the LDAP application (Security Access Manager for example) from having to be aware of the DIT partitioning.

Parent topic: User registry configuration

Adding the Security Access Manager suffix to the proxyAdding the Security Access Manager suffix to the proxyAdding the Security Access Manager suffix to the proxyFor the proxy to work with Security Access Manager, you must configure the secAuthority=Default suffix.proxy serversadding suffixsuffixesadding for proxy serverLog in to Server A as the local LDAP administrator.For example, cn=root.Select Server administration→Manage server properties. Select the Suffixes property.In the Suffix DN field, type secAuthority=Default.Click Add.When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit.The suffix is available until the server is restarted. In the navigation pane, select Server administration and then select Start/stop/restart server. Ensure the Start/restart in configuration only mode check box is not selected.Click Restart. After a message is displayed that the restart request was sent, go to Server administration and check the status of the server. Wait until the server restarts successfully and is running before you continue.Log in to Proxy as the local LDAP administrator.For example, cn=root.From the navigation pane, expand Proxy administration.On the Proxy administration page, click Manage proxy properties.In the Suffix DN field, type secAuthority=Default.Click Add.Click OK to save your changes and return to the Introduction window.From the navigation pane, click Proxy administration and then click Manage partition bases.From the Manage partition bases menu, click Add.In the Split Name field, type: Split 1In the Partition base DN field, type: secAuthority=DefaultIn the Number of partitions field, type: 1In the Partition bases table, select secAuthority=Default.Click View servers and then verify that secAuthority=Default is displayed in the Partition base DN field.In the Back-end directory servers for partition base table, click Add.From the Add Back-end directory server menu, click Back-end directory server→Server A.Ensure that 1 is displayed in the Partition index field.Click OK.When you are finished, click Close.Restart Proxy for the changes to take effect.Security Directory Server proxy environment setupA Security Directory Server proxy is a special type of IBM Security Directory Server that provides request routing, load balancing, fail over, distributed authentication and support for distributed/membership groups and partitioning of containers.

Adding the Security Access Manager suffix to the proxy

For the proxy to work with Security Access Manager, you must configure the secAuthority=Default suffix.

Procedure

Log in to Server A as the local LDAP administrator. For example, cn=root.

Select Server administration > → > Manage server properties. Select the Suffixes property.

In the Suffix DN field, type secAuthority=Default.

Click Add.

When you are finished, click Apply to save your changes without exiting, or click OK to apply your changes and exit.

The suffix is available until the server is restarted. In the navigation pane, select Server administration and then select Start/stop/restart server.

Ensure the Start/restart in configuration only mode check box is not selected.

Click Restart.

After a message is displayed that the restart request was sent, go to Server administration and check the status of the server. Wait until the server restarts successfully and is running before you continue.

Log in to Proxy as the local LDAP administrator. For example, cn=root.

From the navigation pane, expand Proxy administration.

On the Proxy administration page, click Manage proxy properties.

In the Suffix DN field, type secAuthority=Default.

Click Add.

Click OK to save your changes and return to the Introduction window.

From the navigation pane, click Proxy administration and then click Manage partition bases.

From the Manage partition bases menu, click Add.

In the Split Name field, type: Split 1

In the Partition base DN field, type: secAuthority=Default

In the Number of partitions field, type: 1

In the Partition bases table, select secAuthority=Default.

Click View servers and then verify that secAuthority=Default is displayed in the Partition base DN field.

In the Back-end directory servers for partition base table, click Add.

From the Add Back-end directory server menu, click Back-end directory server > → > Server A.

Ensure that 1 is displayed in the Partition index field.

Click OK.

When you are finished, click Close.

Restart Proxy for the changes to take effect.

Parent topic: Security Directory Server proxy environment setup

Security Access Manager configuration with the proxySecurity Access Manager configuration with the proxySecurity Access Manager configuration with the proxyAfter the Security Directory Server proxy server and back-end servers are configured with the Directory Information Tree (DIT) partitioning setup, you can configureSecurity Access Manager to use the proxy. The proxy server provides a unified view of the directory and shields the LDAP application (Security Access Manager for example) from having to be aware of the DIT partitioning.proxy serversconfiguring for use When configured to use the Security Directory Server proxy server, Security Access Manager is only aware of the proxy and performs all operations through the proxy, as if it represented the entire DIT namespace. To provide failover support, multiple Security Directory Server proxy servers can also be configured. For information about configuring multiple Security Directory Server proxy servers to provide failover support, see the IBM Tivoli Directory Server Administration Guide. When you configure multiple proxy servers to provide failover support, Security Access Manager must be configured to treat each of the proxy servers as a directory server replica. The example scenario that is described here assumes a single proxy.Because Security Access Manager cannot be configured directly to the Security Directory Server proxy server, Security Access Manager must first be configured to the back-end server that hosts the secAuthority=Default subtree. When you configure the Security Access Manager Runtime component for use with this back-end server, select LDAP as the registry type. When the pdconfig utility requests the LDAP hostname, type the host name and LDAP port number of Server A (the back-end server that hosts the secAuthority=Default subtree); do not type the host name of the Security Directory Server proxy server (Proxy). Configure SSL information for setting up an SSL connection with Server A, if SSL is to be used. When you use SSL, Proxy needs to be configured with a server certificate that is generated by the same certificate authority (CA) that was used to create the server certificate for Server A. Specify the LDAP DN (for example cn=root) and the LDAP administrator password for Server A. After the Security Access Manager policy server is configured successfully to the back-end server (Server A), you can then retarget the Security Access Manager policy server system to the Security Directory Server proxy server. Exit the pdconfig utility.Security Directory Server proxy environment setupA Security Directory Server proxy is a special type of IBM Security Directory Server that provides request routing, load balancing, fail over, distributed authentication and support for distributed/membership groups and partitioning of containers.Redirecting the policy server to the proxyTo retarget the Security Access Manager policy server system to the proxy, edit the policy server ldap.conf and pd.conf configuration files.Setting access controls for the proxyAccess control lists (ACLs) cannot be managed from the Security Directory Server proxy server. When a proxy server is used, it is the back-end server that enforces access control. The LDAP administrator must ensure that the proper ACLs are created on each of the back-end servers if the ACLs exist on the top-level object of the partition split point.

Security Access Manager configuration with the proxy

After the Security Directory Server proxy server and back-end servers are configured with the Directory Information Tree (DIT) partitioning setup, you can configureSecurity Access Manager to use the proxy. The proxy server provides a unified view of the directory and shields the LDAP application (Security Access Manager for example) from having to be aware of the DIT partitioning.

When configured to use the Security Directory Server proxy server, Security Access Manager is only aware of the proxy and performs all operations through the proxy, as if it represented the entire DIT namespace.

To provide failover support, multiple Security Directory Server proxy servers can also be configured. For information about configuring multiple Security Directory Server proxy servers to provide failover support, see the IBM® Directory Server Administration Guide.

When you configure multiple proxy servers to provide failover support, Security Access Manager must be configured to treat each of the proxy servers as a directory server replica. The example scenario that is described here assumes a single proxy.

Because Security Access Manager cannot be configured directly to the Security Directory Server proxy server, Security Access Manager must first be configured to the back-end server that hosts the secAuthority=Default subtree. When you configure the Security Access Manager Runtime component for use with this back-end server, select LDAP as the registry type. When the pdconfig utility requests the LDAP hostname, type the host name and LDAP port number of Server A (the back-end server that hosts the secAuthority=Default subtree); do not type the host name of the Security Directory Server proxy server (Proxy).

Configure SSL information for setting up an SSL connection with Server A, if SSL is to be used. When you use SSL, Proxy needs to be configured with a server certificate that is generated by the same certificate authority (CA) that was used to create the server certificate for Server A. Specify the LDAP DN (for example cn=root) and the LDAP administrator password for Server A. After the Security Access Manager policy server is configured successfully to the back-end server (Server A), you can then retarget the Security Access Manager policy server system to the Security Directory Server proxy server. Exit the pdconfig utility.

Redirecting the policy server to the proxy
To retarget the Security Access Manager policy server system to the proxy, edit the policy server ldap.conf and pd.conf configuration files.

Setting access controls for the proxy
Access control lists (ACLs) cannot be managed from the Security Directory Server proxy server. When a proxy server is used, it is the back-end server that enforces access control. The LDAP administrator must ensure that the proper ACLs are created on each of the back-end servers if the ACLs exist on the top-level object of the partition split point.

Parent topic: Security Directory Server proxy environment setup

Redirecting the policy server to the proxyRedirecting the policy server to the proxyRedirecting the policy server to the proxyTo retarget the Security Access Manager policy server system to the proxy, edit the policy server ldap.conf and pd.conf configuration files.proxy serversredirecting from the policy serverpolicy serverredirecting to proxy serverLog in the local management interface.From the top menu, select Secure Web SettingsManageRuntime Component.Click ManageConfiguration Files.Select ldap.conf.Specify the host name and port number of the proxy server.ldap host proxy_hostnameldap port proxy_portClick Save. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert. Click ManageConfiguration Files.Select pd.conf.Specify the host name and port number of the proxy server.pdrte user-reg-server proxy_hostnamepdrte user-reg-host proxy_hostnamepdrte user-reg-hostportproxy_portClick Save. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert. Security Access Manager configuration with the proxyAfter the Security Directory Server proxy server and back-end servers are configured with the Directory Information Tree (DIT) partitioning setup, you can configureSecurity Access Manager to use the proxy. The proxy server provides a unified view of the directory and shields the LDAP application (Security Access Manager for example) from having to be aware of the DIT partitioning.

Redirecting the policy server to the proxy

To retarget the Security Access Manager policy server system to the proxy, edit the policy server ldap.conf and pd.conf configuration files.

Procedure

Log in the local management interface.

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Click Manage > Configuration Files.

Select ldap.conf.

Specify the host name and port number of the proxy server.

ldap host proxy_hostname

ldap port proxy_port

Click Save. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert.

Click Manage > Configuration Files.

Select pd.conf.

Specify the host name and port number of the proxy server.

pdrte user-reg-server proxy_hostname

pdrte user-reg-host proxy_hostname

pdrte user-reg-hostportproxy_port

Click Save. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert.

Parent topic: Security Access Manager configuration with the proxy

Setting access controls for the proxySetting access controls for the proxySetting access controls for the proxyAccess control lists (ACLs) cannot be managed from the Security Directory Server proxy server. When a proxy server is used, it is the back-end server that enforces access control. The LDAP administrator must ensure that the proper ACLs are created on each of the back-end servers if the ACLs exist on the top-level object of the partition split point. proxy serverssetting access controlsSecurity Access Manager must have proper access control to allow it to manage users and groups within the suffixes where user and group definitions are maintained. To set the necessary ACLs on the back-end servers to allow Security Access Manager to manage the partition suffixes, use the Security Access Manager ivrgy_tool utility with the add-acls parameter. Run the ivrgy_tool utility from any system where the Security Access Manager Runtime component is installed. For example, the system where the policy server is installed.To apply the proper ACLs on each of the back-end servers, run the following command:ivrgy_tool -h backend_host -p backend_port -D ldap_admin_DN \ -w ldap_admin_pwd -d [-Z] [-K ssl_keyfile] [-P ssl_keyfile_pwd] \ [-N label] add-acls domainFor more information about the ivrgy_tool utility, see the Reference topics in the IBM Knowledge Center.The policy server is the only Security Access Manager component that must be retargeted to the Security Directory Server proxy server as described in Security Access Manager configuration with the proxyAfter the Security Directory Server proxy server and back-end servers are configured with the Directory Information Tree (DIT) partitioning setup, you can configureSecurity Access Manager to use the proxy. The proxy server provides a unified view of the directory and shields the LDAP application (Security Access Manager for example) from having to be aware of the DIT partitioning.. Other Security Access Manager components, such as the authorization server or WebSEAL, do not need to be retargeted. After the policy server is configured, other Security Access Manager components can be configured normally. When you configure Security Access Manager Runtime for other components, the Security Directory Server proxy server host name and port must be specified for the LDAP host name. It is not necessary to indicate any of the back-end servers.Security Access Manager configuration with the proxyAfter the Security Directory Server proxy server and back-end servers are configured with the Directory Information Tree (DIT) partitioning setup, you can configureSecurity Access Manager to use the proxy. The proxy server provides a unified view of the directory and shields the LDAP application (Security Access Manager for example) from having to be aware of the DIT partitioning.

Setting access controls for the proxy

Access control lists (ACLs) cannot be managed from the Security Directory Server proxy server. When a proxy server is used, it is the back-end server that enforces access control. The LDAP administrator must ensure that the proper ACLs are created on each of the back-end servers if the ACLs exist on the top-level object of the partition split point.

About this task

Security Access Manager must have proper access control to allow it to manage users and groups within the suffixes where user and group definitions are maintained. To set the necessary ACLs on the back-end servers to allow Security Access Manager to manage the partition suffixes, use the Security Access Manager ivrgy_tool utility with the add-acls parameter.

Procedure

Run the ivrgy_tool utility from any system where the Security Access Manager Runtime component is installed. For example, the system where the policy server is installed.

To apply the proper ACLs on each of the back-end servers, run the following command:

ivrgy_tool -h backend_host -p backend_port -D ldap_admin_DN \
-w ldap_admin_pwd -d [-Z] [-K ssl_keyfile] [-P ssl_keyfile_pwd] \
[-N label] add-acls domain

For more information about the ivrgy_tool utility, see the Reference topics in the IBM Knowledge Center.

Results

The policy server is the only Security Access Manager component that must be retargeted to the Security Directory Server proxy server as described in Security Access Manager configuration with the proxy. Other Security Access Manager components, such as the authorization server or WebSEAL, do not need to be retargeted.

After the policy server is configured, other Security Access Manager components can be configured normally.

When you configure Security Access Manager Runtime for other components, the Security Directory Server proxy server host name and port must be specified for the LDAP host name. It is not necessary to indicate any of the back-end servers.

Parent topic: Security Access Manager configuration with the proxy

Security Access Manager registry adapter for WebSphere federated repositoriesSecurity Access Manager registry adapter for WebSphere federated repositoriesSecurity Access Manager registry adapter for WebSphere federated repositoriesThe Security Access Manager registry adapter for WebSphere federated repositories uses the Security Access Manager Registry Direct Java API to perform registry-related operations.registry adapterfor WebSphere federated repositoriesThe adapter: Is a virtual member manager (VMM) adapter. For detailed information about VMM, see the Virtual member manager documentation in the IBMWebSphere Application Server IBM Knowledge Center .Supports a single Security Access Manager domain. However, the Security Access Manager supports multiple secure domains support when configured with the LDAP registry.Supports the Security Access Manager registries supported by the Registry Direct Java API.User registry configurationUse the topics in this hierarchy to configure user registries for IBM Security Access Manager.

Security Access Manager registry adapter for WebSphere federated repositories

The Security Access Manager registry adapter for WebSphere® federated repositories uses the Security Access Manager Registry Direct Java™ API to perform registry-related operations.

The adapter:

Is a virtual member manager (VMM) adapter. For detailed information about VMM, see the Virtual member manager documentation in the IBM®WebSphere Application Server IBM Knowledge Center .

Supports a single Security Access Manager domain. However, the Security Access Manager supports multiple secure domains support when configured with the LDAP registry.

Supports the Security Access Manager registries supported by the Registry Direct Java API.

Parent topic: User registry configuration

Web Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Web Reverse Proxy configuration This section provides configuration procedures for the Web Reverse Proxy.ConfiguringConfiguring is an activity in which you modify the default settings of various parts of the product.AdministrationWith the centralized policy management solution for distributed applications in IBM Security Access Manager, you can build secure and well-managed intranets for Internet-based applications. You must understand how WebSEAL protects your resources so that you can successfully administer the WebSEAL server.ConfigurationAuthenticationSession StateDistributed session cacheAuthorizationStandard WebSEAL JunctionsVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.Single Signon SolutionsDeploymentAuthorization decision information retrievalGuidelines for changing configuration filesCommand reference

Web Reverse Proxy configuration

Use the topics in this hierarchy to configure the Web Reverse Proxy.

Web Reverse Proxy configuration This section provides configuration procedures for the Web Reverse Proxy.

Administration
With the centralized policy management solution for distributed applications in IBM Security Access Manager, you can build secure and well-managed intranets for Internet-based applications. You must understand how WebSEAL protects your resources so that you can successfully administer the WebSEAL server.

Configuration

Authentication

Session State

Distributed session cache

Authorization

Standard WebSEAL Junctions

Virtual Hosting
Use the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Single Signon Solutions

Deployment

Authorization decision information retrieval

Guidelines for changing configuration files

Command reference

Parent topic: Configuring

AdministrationAdministration: IBM Security Access Manager for WebAdministration: IBM Security Access Manager for WebWith the centralized policy management solution for distributed applications in IBM Security Access Manager, you can build secure and well-managed intranets for Internet-based applications. You must understand how WebSEAL protects your resources so that you can successfully administer the WebSEAL server.IBM Security Access Manager for WebadministrationWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Server administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.

Administration

With the centralized policy management solution for distributed applications in IBM Security Access Manager, you can build secure and well-managed intranets for Internet-based applications. You must understand how WebSEAL protects your resources so that you can successfully administer the WebSEAL server.

IBM Security Access Manager WebSEAL overview
WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.

Server administration
You must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.

Parent topic: Web Reverse Proxy configuration

IBM Security Access Manager WebSEAL overview WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.WebSEALoverviewIBM Security Access ManagerAdministrationWith the centralized policy management solution for distributed applications in IBM Security Access Manager, you can build secure and well-managed intranets for Internet-based applications. You must understand how WebSEAL protects your resources so that you can successfully administer the WebSEAL server.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

IBM Security Access Manager WebSEAL overview

WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.

Introduction to IBM Security Access Manager
IBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets.

WebSEAL introduction
WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.

IBM Security Access Manager appliance
The IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.

WebSEAL functionality on the appliance
The appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section.

Security concepts for a WebSEAL deployment
You must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Authorization process
The authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain.

Security policy planning and implementation
A corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.

Content types and levels of protection
As the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.

WebSEAL authentication
Authentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.

Standard WebSEAL junctions
A WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server.

Web space scalability
WebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Parent topic: Administration

Introduction to IBM Security Access ManagerIntroduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. Security Access Manageroverviewsecuritypoliciesmanagement solutionsIn addition to state-of-the-art security policy management, IBM Security Access Manager provides authentication, authorization, data security, and centralized resource management capabilities. IBM Security Access Manager offers the following features:AuthenticationProvides a wide range of built-in authenticators and supports external authenticators.Authorization Provides permit and deny decisions for protected resources requests in the secure domain through the authorization API.Data security and centralized resource management Manages secure access to private internal network-based resources by using the public Internet's broad connectivity and ease of use with a corporate firewall system.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Introduction to IBM Security Access Manager

IBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets.

In addition to state-of-the-art security policy management, IBM Security Access Manager provides authentication, authorization, data security, and centralized resource management capabilities.

IBM Security Access Manager offers the following features:

Authentication

Provides a wide range of built-in authenticators and supports external authenticators.

Authorization

Provides permit and deny decisions for protected resources requests in the secure domain through the authorization API.

Data security and centralized resource management

Manages secure access to private internal network-based resources by using the public Internet's broad connectivity and ease of use with a corporate firewall system.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

WebSEAL introductionWebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.WebSEALoverviewHTTPrequestsWebSEAL acts as a reverse web proxy by receiving HTTP/HTTPS requests from a web browser and delivering content from its own web server or from junctioned back-end web application servers. Requests passing through WebSEAL are evaluated by the Security Access Manager authorization service to determine whether the user is authorized to access the requested resource.WebSEAL provides the following features: Supports multiple authentication methods.Integrates with Security Access Manager authorization service.Accepts HTTP and HTTPS requests.Integrates and protects back-end server resources through WebSEAL junction technology. Provides a unified view of a combined protected object space.Manages fine-grained access control for the local and back-end server resources. Supported resources include URLs, URL-based regular expressions, CGI programs, HTML files, Java servlets, and Java class files.Performs as a reverse web proxy. WebSEAL appears as a web server to clients and appears as a web browser to the junctioned back-end servers it is protecting.Provides single sign-on capabilities.Protecting resources with WebSEALProtecting resources with WebSEALIBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

WebSEAL introduction

WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.

WebSEAL acts as a reverse web proxy by receiving HTTP/HTTPS requests from a web browser and delivering content from its own web server or from junctioned back-end web application servers. Requests passing through WebSEAL are evaluated by the Security Access Manager authorization service to determine whether the user is authorized to access the requested resource.

WebSEAL provides the following features:

Supports multiple authentication methods.

Integrates with Security Access Manager authorization service.

Accepts HTTP and HTTPS requests.

Integrates and protects back-end server resources through WebSEAL junction technology.

Provides a unified view of a combined protected object space.

Manages fine-grained access control for the local and back-end server resources.

Supported resources include URLs, URL-based regular expressions, CGI programs, HTML files, Java™ servlets, and Java class files.

Performs as a reverse web proxy.

WebSEAL appears as a web server to clients and appears as a web browser to the junctioned back-end servers it is protecting.

Provides single sign-on capabilities.

Figure 1. Protecting resources with WebSEAL

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

IBM Security Access Manager applianceIBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.applianceIBM Security Web Gateway ApplianceThe appliance uses WebSEAL to enable scalability and protection of the applications from invalid access and threats. WebSEAL is located between the users and the back-end application servers.There are two appliance offerings: Virtual offeringHardware offeringThe appliance has a local management interface for administrative purposes. You can use the it to manage the WebSEAL instances in your environment. For more information about using the local management interface, see the Administration topics in the IBM Knowledge Center.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

IBM Security Access Manager appliance

The IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.

The appliance uses WebSEAL to enable scalability and protection of the applications from invalid access and threats. WebSEAL is located between the users and the back-end application servers.

There are two appliance offerings:

Virtual offering

Hardware offering

The appliance has a local management interface for administrative purposes. You can use the it to manage the WebSEAL instances in your environment. For more information about using the local management interface, see the Administration topics in the IBM Knowledge Center.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

WebSEAL functionality on the applianceWebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. WebSEALfunctionality on the applianceserversintermediate authorizationARSWebSEAL features that the appliance does not supportFeatureDescriptionCustom libraries, including CDAS and EASThe appliance does not support custom CDAS modules. As a result, the appliance does not support the following authentication mechanisms:IP addressHTTP headerPost password changeWebSEAL does not provide CDAS modules for these mechanisms.The appliance does support the IBM Security Identity Manager Password Synchronization Plug-in. For more information, see the [itim] stanza in the Web Reverse Proxy Stanza Reference..Local junctionsThe following limitations apply to local junction support on the appliance: The appliance can support a single fixed file system path for the local junction of a WebSEAL instance. Local junctions on the appliance cannot run any CGI scripts.Hardware Based CryptographyThe appliance does not support any hardware-based cryptography. However, the hardware appliance does include AES-NI support in the i7-2600 processor, which can handle cryptographic operations.Application Response Measurement (ARM)WebSEAL software includes ARM to monitor transactions throughout the request and response processing stream. The appliance does not include ARM. Tivoli Common Directory Logging The Tivoli Common Directory Logging feature stores all log files for IBM Security software applications in a common file system directory. The appliance does not support this common logging. Logging for the appliance is managed through the LMI. Auditing to a pipeThe appliance cannot send audit records directly to a pipe. It can however, use an intermediate Security Access Manager authorization server to indirectly send audit records to the destinations. The appliance can also send audit data to remote syslog.ARS (web service)The IBM Security Access Manager ARS web service can send request information to an external ARS server for authorization. ARS is not available on the appliance.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

WebSEAL functionality on the appliance

The appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section.

Table 10. WebSEAL features that the appliance does not support.

Feature
Description

Custom libraries, including CDAS and EAS
The appliance does not support custom CDAS modules. As a result, the appliance does not support the following authentication mechanisms:

IP address

HTTP header

Post password change

WebSEAL does not provide CDAS modules for these mechanisms.

Note: The appliance does support the IBM Security Identity Manager Password Synchronization Plug-in. For more information, see the [itim] stanza in the Web Reverse Proxy Stanza Reference..

Local junctions
The following limitations apply to local junction support on the appliance:

The appliance can support a single fixed file system path for the local junction of a WebSEAL instance.

Local junctions on the appliance cannot run any CGI scripts.

Hardware Based Cryptography
The appliance does not support any hardware-based cryptography. However, the hardware appliance does include AES-NI support in the i7-2600 processor, which can handle cryptographic operations.

Application Response Measurement (ARM)
WebSEAL software includes ARM to monitor transactions throughout the request and response processing stream. The appliance does not include ARM.

Tivoli® Common Directory Logging
The Tivoli Common Directory Logging feature stores all log files for IBM® Security software applications in a common file system directory. The appliance does not support this common logging. Logging for the appliance is managed through the LMI.

Auditing to a pipe
The appliance cannot send audit records directly to a pipe. It can however, use an intermediate Security Access Manager authorization server to indirectly send audit records to the destinations. The appliance can also send audit data to remote syslog.

ARS (web service)
The IBM Security Access Manager ARS web service can send request information to an external ARS server for authorization. ARS is not available on the appliance.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

Security concepts for a WebSEAL deploymentSecurity concepts for a WebSEAL deploymentSecurity concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.securitymodel conceptsWebSEAL deploymentdeploymentWebSEALsecurity conceptsWebSEALdeploymentIBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site. Secure domain overviewThe computing environment in which Security Access Manager enforces security policies for authentication, authorization, and access control is called a secure domain.The role of the user registry and master authorization database in securityThe user registry and the master authorization database are two key security structures that govern and maintain the security policy of a Security Access Manager secure domain.The protected object space and system resourceThe protected object space is a hierarchical representation of resources that belong to a Security Access Manager secure domain. The system resource is the actual physical file or application.Access control lists and protected object policiesSecurity administrators define and apply the access control list (ACL) and protected object policy (POP) to protect resources in the Security Access Manager system. These rules are applied to the object representations of the resources in the protected object space.Access control list policiesAn access control list policy, or ACL policy, controls what operations a user can perform on the resource and who can perform them. Protected object policiesProtected object policies, or POPs, are policies that contain extra conditions on the requests that are sent to the Security Access Manager and WebSEAL along with the yes ACL policy decision from the authorization service.Explicit and inherited policyPolicies can be explicitly applied or inherited. The protected object space supports inherited and explicit ACL and POP attributes.Policy administration: The Web Portal ManagerThe Web Portal Manager is a web-based graphical application that manages the security policy in a Security Access Manager secure domain. Use the Web Portal Manager to manage the user registry, the master authorization policy database, and the Security Access Manager servers.

Security concepts for a WebSEAL deployment

You must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Secure domain overview
The computing environment in which Security Access Manager enforces security policies for authentication, authorization, and access control is called a secure domain.

The role of the user registry and master authorization database in security
The user registry and the master authorization database are two key security structures that govern and maintain the security policy of a Security Access Manager secure domain.

The protected object space and system resource
The protected object space is a hierarchical representation of resources that belong to a Security Access Manager secure domain. The system resource is the actual physical file or application.

Access control lists and protected object policies
Security administrators define and apply the access control list (ACL) and protected object policy (POP) to protect resources in the Security Access Manager system. These rules are applied to the object representations of the resources in the protected object space.

Access control list policies
An access control list policy, or ACL policy, controls what operations a user can perform on the resource and who can perform them.

Protected object policies
Protected object policies, or POPs, are policies that contain extra conditions on the requests that are sent to the Security Access Manager and WebSEAL along with the yes ACL policy decision from the authorization service.

Explicit and inherited policy
Policies can be explicitly applied or inherited. The protected object space supports inherited and explicit ACL and POP attributes.

Policy administration: The Web Portal Manager
The Web Portal Manager is a web-based graphical application that manages the security policy in a Security Access Manager secure domain. Use the Web Portal Manager to manage the user registry, the master authorization policy database, and the Security Access Manager servers.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Authorization process

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

Secure domain overviewSecure domain overviewThe computing environment in which Security Access Manager enforces security policies for authentication, authorization, and access control is called a secure domain.securitydomain overviewmanagementoverviewdomainspoliciesserversserverspoliciesuser registriesuse in management domainThe initial secure domain, called the management domain, is created when you install and configure the following systems: Policy serverMaintains the master authorization database for the management domain. In addition, it updates authorization database replicas and maintains location information about other Security Access Manager servers.RegistryProvides a database of the user identities that are known to Security Access Manager. It also provides a representation of groups in Security Access Manager roles that are associated with users.These core systems must exist for Security Access Manager to complete fundamental operations, such as permitting or denying user access to protected objects (resources). All other Security Access Manager services and components are built on this base.You can deploy Security Access Manager on multiple systems to configure and use the management domain on one stand-alone system. A single system setup is useful only when prototyping a deployment or developing and testing an application.After you configure the policy server and registry server, you can set up more systems in the management domain. For example, you could set up an authorization server or application development system. You can also create more secure domains (if you use an LDAP registry) to securely partition data into separate, logical groupings. For information about creating multiple domains, see the Administering topics in the IBM Knowledge Center.Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Secure domain overview

The computing environment in which Security Access Manager enforces security policies for authentication, authorization, and access control is called a secure domain.

The initial secure domain, called the management domain, is created when you install and configure the following systems:

Policy server

Maintains the master authorization database for the management domain. In addition, it updates authorization database replicas and maintains location information about other Security Access Manager servers.

Registry

Provides a database of the user identities that are known to Security Access Manager. It also provides a representation of groups in Security Access Manager roles that are associated with users.

These core systems must exist for Security Access Manager to complete fundamental operations, such as permitting or denying user access to protected objects (resources). All other Security Access Manager services and components are built on this base.

You can deploy Security Access Manager on multiple systems to configure and use the management domain on one stand-alone system. A single system setup is useful only when prototyping a deployment or developing and testing an application.

After you configure the policy server and registry server, you can set up more systems in the management domain. For example, you could set up an authorization server or application development system. You can also create more secure domains (if you use an LDAP registry) to securely partition data into separate, logical groupings. For information about creating multiple domains, see the Administering topics in the IBM Knowledge Center.

Parent topic: Security concepts for a WebSEAL deployment

The role of the user registry and master authorization database in securityThe role of the user registry and master authorization database in securityThe role of the user registry and master authorization database in securityThe user registry and the master authorization database are two key security structures that govern and maintain the security policy of a Security Access Manager secure domain.securitymodel conceptsuser registrymaster authorization databaseuser registriesrolesmaster authorization databasesdatabasessecurityrolesauthorizationmaster databasesA user registry, such as IBM Tivoli Directory Server or Microsoft Active Directory, contains all users and groups who can participate in the Security Access Manager environment. This environment is the secure domain.The authorization database contains a representation of all resources in the domain. The security administrator can dictate any level of security by applying rules to the resources that require protection. These rules are known as access control list (ACL) policies and protected object policies (POPs).The process of authentication proves the identity of a user to WebSEAL. A user can participate in the secure domain as authenticated or unauthenticated. Authenticated users must have an account in the user registry. Using ACLs and POPs, the security administrator can ensure:Certain resources are publicly available to unauthenticated usersOther resources are available only to certain authenticated usersWhen a user successfully authenticates, WebSEAL creates a set of identification information that is known as a credential. The credential contains the user identity, any group memberships, and any special extended security attributes. A user requires a credential to fully participate in the secure domain. The Security Access Manager authorization service enforces security policies by comparing a user's authentication credentials with the policy permissions assigned to the requested resource. The authorization service passes the resulting recommendation to the resource manager, for example, WebSEAL, which completes the response to the original request.Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

The role of the user registry and master authorization database in security

The user registry and the master authorization database are two key security structures that govern and maintain the security policy of a Security Access Manager secure domain.

A user registry, such as IBM® Tivoli® Directory Server or Microsoft Active Directory, contains all users and groups who can participate in the Security Access Manager environment. This environment is the secure domain.

The authorization database contains a representation of all resources in the domain. The security administrator can dictate any level of security by applying rules to the resources that require protection. These rules are known as access control list (ACL) policies and protected object policies (POPs).

The process of authentication proves the identity of a user to WebSEAL. A user can participate in the secure domain as authenticated or unauthenticated.

Authenticated users must have an account in the user registry. Using ACLs and POPs, the security administrator can ensure:

Certain resources are publicly available to unauthenticated users

Other resources are available only to certain authenticated users

When a user successfully authenticates, WebSEAL creates a set of identification information that is known as a credential. The credential contains the user identity, any group memberships, and any special extended security attributes.

A user requires a credential to fully participate in the secure domain. The Security Access Manager authorization service enforces security policies by comparing a user's authentication credentials with the policy permissions assigned to the requested resource. The authorization service passes the resulting recommendation to the resource manager, for example, WebSEAL, which completes the response to the original request.

Parent topic: Security concepts for a WebSEAL deployment

The protected object space and system resourceThe protected object space and system resourceThe protected object space and system resourceThe protected object space is a hierarchical representation of resources that belong to a Security Access Manager secure domain. The system resource is the actual physical file or application.protected object spacesuser-defined objectsmanagement objectsWeb objectssystem resourcesprotected objectsuser-defined objectsmanagementobjectsWeb objectssystem resourcesauthorizationservicesThe authorization service, Web Portal Manager, and other Security Access Manager management utilities use the protected object space.You can attach policies to objects in the object space so that resources are protected. The authorization service makes authorization decisions that are based on these policies.The combined installation of Security Access Manager base and WebSEAL provides the following object space categories:Web objectsRepresent any resource that can be addressed by an HTTP URL. These objects can include static web pages and dynamic URLs that are converted to database queries or some other type of application. The WebSEAL server is responsible for protecting web objects.Management objectsRepresent the management activities that administrators can perform through policy administration. The objects represent the tasks that define users and set security policy. Security Access Manager supports delegation of management activities and can restrict an administrator's ability to set security policy to a subset of the object space.User-defined objectsRepresent customer-defined tasks or network resources that are protected by applications that access the authorization service through the Security Access Manager authorization API.Protected object spaceProtected object spaceSecurity concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

The protected object space and system resource

The protected object space is a hierarchical representation of resources that belong to a Security Access Manager secure domain. The system resource is the actual physical file or application.

The authorization service, Web Portal Manager, and other Security Access Manager management utilities use the protected object space.

You can attach policies to objects in the object space so that resources are protected. The authorization service makes authorization decisions that are based on these policies.

The combined installation of Security Access Manager base and WebSEAL provides the following object space categories:

Web objects

Represent any resource that can be addressed by an HTTP URL. These objects can include static web pages and dynamic URLs that are converted to database queries or some other type of application. The WebSEAL server is responsible for protecting web objects.

Management objects

Represent the management activities that administrators can perform through policy administration. The objects represent the tasks that define users and set security policy. Security Access Manager supports delegation of management activities and can restrict an administrator's ability to set security policy to a subset of the object space.

User-defined objects

Represent customer-defined tasks or network resources that are protected by applications that access the authorization service through the Security Access Manager authorization API.

Figure 2. Protected object space

Parent topic: Security concepts for a WebSEAL deployment

Access control lists and protected object policiesAccess control lists and protected object policiesAccess control lists and protected object policiesSecurity administrators define and apply the access control list (ACL) and protected object policy (POP) to protect resources in the Security Access Manager system. These rules are applied to the object representations of the resources in the protected object space.ACLintroductionPOPintroductionsecurityadministratorsThe Security Access Manager authorization service authorizes decisions that are based on the policies that are applied to these objects. When a requested operation on a protected object is permitted, the application responsible for the resource implements it.One policy can dictate the protection parameters of many objects. Any change to the rule affects all objects to which the ACL or POP is attached.Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Access control lists and protected object policies

Security administrators define and apply the access control list (ACL) and protected object policy (POP) to protect resources in the Security Access Manager system. These rules are applied to the object representations of the resources in the protected object space.

The Security Access Manager authorization service authorizes decisions that are based on the policies that are applied to these objects. When a requested operation on a protected object is permitted, the application responsible for the resource implements it.

One policy can dictate the protection parameters of many objects. Any change to the rule affects all objects to which the ACL or POP is attached.

Parent topic: Security concepts for a WebSEAL deployment

Access control list policiesAccess control list policiesAccess control list policiesAn access control list policy, or ACL policy, controls what operations a user can perform on the resource and who can perform them. ACLconceptspoliciesaccess control listACLIt is a set of rules or permissions that specify the conditions that are necessary to perform certain operations on a resource.ACL policy definitions are components of the security policy that establish the secure domain. ACL policies define organizational security requirements to the resources in the protected object space. ACL policies also provide the authorization service with information to make a yes or no determination for a request to access a protected object.An ACL policy controls: What operations can be performed on the resourceWho can perform these operations An ACL policy is composed of one or more entries that include user and group designations and their specific permissions or rights. An ACL can also contain rules that apply to unauthenticated users.ACL policyACL policySecurity concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Access control list policies

An access control list policy, or ACL policy, controls what operations a user can perform on the resource and who can perform them.

It is a set of rules or permissions that specify the conditions that are necessary to perform certain operations on a resource.

ACL policy definitions are components of the security policy that establish the secure domain. ACL policies define organizational security requirements to the resources in the protected object space.

ACL policies also provide the authorization service with information to make a yes or no determination for a request to access a protected object.

An ACL policy controls:

What operations can be performed on the resource

Who can perform these operations

An ACL policy is composed of one or more entries that include user and group designations and their specific permissions or rights. An ACL can also contain rules that apply to unauthenticated users.

Figure 3. ACL policy

Parent topic: Security concepts for a WebSEAL deployment

Protected object policiesProtected object policiesProtected object policiesProtected object policies, or POPs, are policies that contain extra conditions on the requests that are sent to the Security Access Manager and WebSEAL along with the yes ACL policy decision from the authorization service.POPconceptsprotected object policiesPOPauditinglevels The Security Access Manager and the resource manager enforce the POP conditions.The following tables list the available attributes for a POP: Listing of POP attributes for Security Access Manager and a description of each one.Enforced by Security Access ManagerPOP AttributeDescriptionNameName of the policy. This attribute becomes the <pop-name> argument in the pdadmin pop commands.DescriptionDescriptive text for the policy. This attribute appears in the pop show command.Warning ModeProvides administrators a means to test ACL and POP policies.Audit LevelSpecifies the type of auditing: all, none, successful access, denied access, errors.Time-of-Day AccessDay and time restrictions for successful access to the protected object. Listing of POP attributes for WebSEAL and a description of each one.Enforced by Resource Manager (WebSEAL)POP AttributeDescriptionQuality of ProtectionSpecifies the degree of data protection: none, integrity, privacy.IP Endpoint Authentication Method PolicySpecifies the authentication requirements for access from members of external networks.Document Cache ControlSpecifies the caching instructions for the handling of specific documents.Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Protected object policies

Protected object policies, or POPs, are policies that contain extra conditions on the requests that are sent to the Security Access Manager and WebSEAL along with the yes ACL policy decision from the authorization service.

The Security Access Manager and the resource manager enforce the POP conditions.

The following tables list the available attributes for a POP:

Enforced by Security Access Manager
POP Attribute | Description
Name | Name of the policy. This attribute becomes the <pop-name> argument in the pdadmin pop commands.
Description | Descriptive text for the policy. This attribute appears in the pop show command.
Warning Mode | Provides administrators a means to test ACL and POP policies.
Audit Level | Specifies the type of auditing: all, none, successful access, denied access, errors.
Time-of-Day Access | Day and time restrictions for successful access to the protected object.

Enforced by Resource Manager (WebSEAL)
POP Attribute | Description
Quality of Protection | Specifies the degree of data protection: none, integrity, privacy.
IP Endpoint Authentication Method Policy | Specifies the authentication requirements for access from members of external networks.
Document Cache Control | Specifies the caching instructions for the handling of specific documents.

Parent topic: Security concepts for a WebSEAL deployment

Explicit and inherited policy Explicit and inherited policyExplicit and inherited policyPolicies can be explicitly applied or inherited. The protected object space supports inherited and explicit ACL and POP attributes.explicit ACL policiesinherited ACL policiesACLexplicitinheritedsecurityadministratorsinheritanceInheritance is an important management feature for the security administrator. The administrator must apply explicit policies only at points in the hierarchy where the rules must change.Explicit and inherited policiesExplicit and inherited policiesSecurity concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Explicit and inherited policy

Policies can be explicitly applied or inherited. The protected object space supports inherited and explicit ACL and POP attributes.

Inheritance is an important management feature for the security administrator. The administrator must apply explicit policies only at points in the hierarchy where the rules must change.

Figure 4. Explicit and inherited policies

Parent topic: Security concepts for a WebSEAL deployment

Policy administration: The Web Portal Manager Policy administration: The Web Portal Manager Policy administration: The Web Portal Manager The Web Portal Manager is a web-based graphical application that manages the security policy in a Security Access Manager secure domain. Use the Web Portal Manager to manage the user registry, the master authorization policy database, and the Security Access Manager servers. Web Portal Manageruser registriesmanagementYou can add and delete users and groups and apply ACLs and POPs to network objects. The pdadmin command-line utility provides the same administration capabilities as the Web Portal Manager, plus some commands that are not supported by the Web Portal Manager.To access Web Portal Manager from the appliance, go to Secure Web SettingsManagePolicy Administration.Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.

Policy administration: The Web Portal Manager

The Web Portal Manager is a web-based graphical application that manages the security policy in a Security Access Manager secure domain. Use the Web Portal Manager to manage the user registry, the master authorization policy database, and the Security Access Manager servers.

You can add and delete users and groups and apply ACLs and POPs to network objects.

The pdadmin command-line utility provides the same administration capabilities as the Web Portal Manager, plus some commands that are not supported by the Web Portal Manager.

To access Web Portal Manager from the appliance, go to Secure Web Settings > Manage > Policy Administration.

Parent topic: Security concepts for a WebSEAL deployment

Authorization processAuthorization processAuthorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. authorizationprocessservicesauthenticationauthorization processresource managerpoliciesenforcersPOPcheckingsecurityauthorizationWhen WebSEAL enforces security in a secure domain, each user must provide proof of its identity. In turn, Security Access Manager security policy determines whether that user is permitted to perform an operation on a requested resource. Because access to every Web resource in a secure domain is controlled by WebSEAL, WebSEAL's requirements for authentication and authorization can provide comprehensive network security.In security systems, authorization is distinct from authentication. Authentication can validate the identity of a user, but says nothing about the user's right to perform operations on a protected resource.In the Security Access Manager authorization model, authorization policy is implemented independently of the mechanism that is used for user authentication. Users can authenticate their identity by using either public and private key, secret key, or customer-defined mechanisms. Part of the authentication process involves the creation of a credential that describes the identity of the user. Authorization decisions that are made by an authorization service are based on user credentials.The resources in a secure domain receive a level of protection as dictated by the security policy for the domain. The security policy defines the legitimate participants of the secure domain and the degree of protection that surrounds each resource that is being protected.The authorization process consists of the following basic components: A resource manager is responsible for implementing the requested operation when authorization is granted. WebSEAL is a resource manager. A component of the resource manager is a policy enforcer that directs the request to the authorization service for processing.Traditional applications bundle the policy enforcer and resource manager into one process. Examples of this structure include WebSEAL and third-party applications.An authorization service performs the decision-making action on the request.The following diagram illustrates the complete authorization process: Web space protectionWeb space protectionA request for a resource from an authenticated user is directed to the resource manager and intercepted by the policy enforcer process. The resource manager can be WebSEAL (for HTTP, HTTPS access) or a third-party application.The policy enforcer process uses the Security Access Manager authorization API to call the authorization service for an authorization decision. The authorization service performs an authorization check on the resource, represented as an object in the protected object space. Security Access Manager POPs are checked first.Next the ACL policy that is attached to the object is checked against the client's credentials.Finally, POPs enforced by the resource manager are checked.The decision to accept or deny the request is returned as a recommendation to the resource manager (through the policy enforcer).If the request is finally approved, the resource manager passes the request on to the application responsible for the resource.The user receives the results of the requested operation.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Authorization process

The authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain.

When WebSEAL enforces security in a secure domain, each user must provide proof of its identity. In turn, Security Access Manager security policy determines whether that user is permitted to perform an operation on a requested resource. Because access to every Web resource in a secure domain is controlled by WebSEAL, WebSEAL's requirements for authentication and authorization can provide comprehensive network security.

In security systems, authorization is distinct from authentication. Authentication can validate the identity of a user, but says nothing about the user's right to perform operations on a protected resource.

In the Security Access Manager authorization model, authorization policy is implemented independently of the mechanism that is used for user authentication. Users can authenticate their identity by using either public and private key, secret key, or customer-defined mechanisms.

Part of the authentication process involves the creation of a credential that describes the identity of the user. Authorization decisions that are made by an authorization service are based on user credentials.

The resources in a secure domain receive a level of protection as dictated by the security policy for the domain. The security policy defines the legitimate participants of the secure domain and the degree of protection that surrounds each resource that is being protected.

The authorization process consists of the following basic components:

A resource manager is responsible for implementing the requested operation when authorization is granted. WebSEAL is a resource manager.

A component of the resource manager is a policy enforcer that directs the request to the authorization service for processing.

Note: Traditional applications bundle the policy enforcer and resource manager into one process. Examples of this structure include WebSEAL and third-party applications.

An authorization service performs the decision-making action on the request.

The following diagram illustrates the complete authorization process:

Figure 5. Web space protection

A request for a resource from an authenticated user is directed to the resource manager and intercepted by the policy enforcer process.

The resource manager can be WebSEAL (for HTTP, HTTPS access) or a third-party application.

The policy enforcer process uses the Security Access Manager authorization API to call the authorization service for an authorization decision.

The authorization service performs an authorization check on the resource, represented as an object in the protected object space.

Security Access Manager POPs are checked first.

Next the ACL policy that is attached to the object is checked against the client's credentials.

Finally, POPs enforced by the resource manager are checked.

The decision to accept or deny the request is returned as a recommendation to the resource manager (through the policy enforcer).

If the request is finally approved, the resource manager passes the request on to the application responsible for the resource.

The user receives the results of the requested operation.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

Security policy planning and implementationSecurity policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.securitypoliciesplanningimplementationauthorizationservicesACLsecurity mechanismssecuritymechanismsPOPsecurity mechanismsSecurity Access Manager uses a virtual representation of these web resources, called the protected object space. The protected object space contains objects that represent actual physical resources in your network.Security mechanisms include: Access control list (ACL) policies ACL policies identify user types that can be considered for access and specify the operations permitted on the object.Protected object policies (POPs) A POP specifies additional conditions governing the access to the protected object, such as privacy, integrity, auditing, and time-of-day access.Extended attributes Extended attributes are additional values placed on an object, ACL, or POP that can be read and interpreted by third-party applications (such as an external authorization service).The core component of Security Access Manager is the Security Access Manager authorization service. This service permits or denies access to protected objects (resources) based on the user's credentials and the access controls placed on the objects.To successfully implement the security policy, you must logically organize the different content types (as described in Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.) and apply the appropriate ACL and POP policies. Access control management can be very complex and is made much easier by careful categorization of the content types.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Security policy planning and implementation

A corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.

Security Access Manager uses a virtual representation of these web resources, called the protected object space. The protected object space contains objects that represent actual physical resources in your network.

Security mechanisms include:

Access control list (ACL) policies

ACL policies identify user types that can be considered for access and specify the operations permitted on the object.

Protected object policies (POPs)

A POP specifies additional conditions governing the access to the protected object, such as privacy, integrity, auditing, and time-of-day access.

Extended attributes

Extended attributes are additional values placed on an object, ACL, or POP that can be read and interpreted by third-party applications (such as an external authorization service).

The core component of Security Access Manager is the Security Access Manager authorization service. This service permits or denies access to protected objects (resources) based on the user's credentials and the access controls placed on the objects.

To successfully implement the security policy, you must logically organize the different content types (as described in Content types and levels of protection) and apply the appropriate ACL and POP policies. Access control management can be very complex and is made much easier by careful categorization of the content types.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

Content types and levels of protectionContent types and levels of protection As the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.securitypoliciesidentifying content typeslevels of protectionscenariosEach security scenario demands different protection requirements and an associated WebSEAL configuration. You must take note of the following responsibilities.Know your web contentIdentify the types of users that require access to this contentUnderstand the strengths and weaknesses of the available WebSEAL configuration options for securing this contentProtection of web content falls into three broad categories: Public content – access requires no protection Unauthenticated users can access resources by using HTTP.An unauthenticated credential is used for access control to resources.Basic WebSEAL configuration requirements provide protection.Public content – access requires privacy (encryption) Unauthenticated users can access resources by using HTTPS.Encryption, which is required by the application server, is used to protect sensitive data (such as credit card numbers and user account information).An unauthenticated credential is used for access control to resources.WebSEAL configuration needs to stipulate privacy.Private content – access requires authentication Authenticated clients can access resources by using HTTP or HTTPS.The administrator determines the need for encryption.An authenticated credential is used for access control to resources; each user must have an account that is defined in the Security Access Manager user registry.WebSEAL configuration is complex and all options must be considered carefully to determine the impact of the security policy.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Content types and levels of protection

As the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.

Each security scenario demands different protection requirements and an associated WebSEAL configuration.

You must take note of the following responsibilities.

Know your web content

Identify the types of users that require access to this content

Understand the strengths and weaknesses of the available WebSEAL configuration options for securing this content

Protection of web content falls into three broad categories:

Public content – access requires no protection

Unauthenticated users can access resources by using HTTP.

An unauthenticated credential is used for access control to resources.

Basic WebSEAL configuration requirements provide protection.

Public content – access requires privacy (encryption)

Unauthenticated users can access resources by using HTTPS.

Encryption, which is required by the application server, is used to protect sensitive data (such as credit card numbers and user account information).

An unauthenticated credential is used for access control to resources.

WebSEAL configuration needs to stipulate privacy.

Private content – access requires authentication

Authenticated clients can access resources by using HTTP or HTTPS.

The administrator determines the need for encryption.

An authenticated credential is used for access control to resources; each user must have an account that is defined in the Security Access Manager user registry.

WebSEAL configuration is complex and all options must be considered carefully to determine the impact of the security policy.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

WebSEAL authentication

Standard WebSEAL junctions

Web space scalability

WebSEAL authentication WebSEAL authentication Authentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.authenticationoverviewWebSEALsecurityauthenticationserversauthenticationThe following conditions apply to the WebSEAL authentication process:WebSEAL supports several authentication methods by default and can be customized to use other methods.When both server and client require authentication, the exchange is known as mutual authentication.The WebSEAL server process is independent of the authentication method.The result of successful authentication to WebSEAL is a Security Access Manager user identity. WebSEAL uses this identity to build a credential for that user. The authorization service uses this credential to permit or deny access to protected objects after it evaluates the ACL permissions and POP conditions that govern the policy for each requested resource.This flexible approach to authentication allows security policy to be based on business requirements and not physical network topology.For a complete overview of WebSEAL authentication concepts, see Authentication overview.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

WebSEAL authentication

Authentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.

The following conditions apply to the WebSEAL authentication process:

WebSEAL supports several authentication methods by default and can be customized to use other methods.

When both server and client require authentication, the exchange is known as mutual authentication.

The WebSEAL server process is independent of the authentication method.

The result of successful authentication to WebSEAL is a Security Access Manager user identity.

WebSEAL uses this identity to build a credential for that user.

The authorization service uses this credential to permit or deny access to protected objects after it evaluates the ACL permissions and POP conditions that govern the policy for each requested resource.

This flexible approach to authentication allows security policy to be based on business requirements and not physical network topology.

For a complete overview of WebSEAL authentication concepts, see Authentication overview.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

Content types and levels of protection

Standard WebSEAL junctions

Web space scalability

Standard WebSEAL junctions Standard WebSEAL junctions A WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. junctionsoverviewstandardunified Web spaceWebSEAL junction resultsserversjunctionsSecurity Access Manager provides authentication, authorization, and management services for a network. In a web-based network, these services are best provided by one or more front-end WebSEAL servers that integrate and protect web resources and applications that are on back-end web servers. The connection between a WebSEAL server and a back-end web application server is known as a standard WebSEAL junction. WebSEAL also supports virtual hosting through another form of junctions called virtual host junctions.The back-end server can be another WebSEAL server or, more commonly, a third-party web application server. The back-end server web space is connected to the WebSEAL server at a specially designated junction (mount) point in the WebSEAL web space. Junctions connect WebSEAL with back-end resourcesJunctions connect WebSEAL with back-end resourcesA junction allows WebSEAL to provide protective services on behalf of the back-end server. WebSEAL authenticates and authorizes all requests before it passes those requests on to the back-end server. If the back-end server requires fine-grained access control on its objects, you must perform additional configuration steps, by using the query_contents CGI program, to describe the third-party web space to the Security Access Manager security service.Junctions provide a scalable, secure environment that allows load balancing, high availability, and state management capabilities, all performed transparently to clients. As an administrator, you can benefit from this centralized management of the web space.WebSEAL junctions provide the added value of logically combining the web space of a back-end server with the web space of the WebSEAL server. Junctions between cooperating servers result in a single, unified, distributed web space that is seamless and transparent to users. The client never needs to know the physical location of a web resource. WebSEAL translates logical URL addresses into the physical addresses that a back-end server expects. Web objects can be moved from server to server without affecting the way that the client can access those objects.A unified web space simplifies the management of all resources for the system administrator. Additional administrative benefits include scalability, load balancing, and high availability. WebSEAL junction results in a unified web spaceWebSEAL junction results in a unified web spaceMost commercial web servers cannot define a logical web object space. Instead, their access control is connected to the physical file and directory structure. WebSEAL junctions can transparently define an object space that reflects organizational structure rather than the physical machine and directory structure that is commonly encountered on standard web servers.With WebSEAL junctions, you can create single signon solutions. A single signon configuration allows a user to access a resource, regardless of the resource's location, by using only one initial login. Any further login requirements from back-end servers are handled transparently to the user.WebSEAL junctions are an important tool for making your Web site scalable. With junctions, you can respond to increasing demands on a website by attaching additional servers.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Standard WebSEAL junctions

A WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server.

Security Access Manager provides authentication, authorization, and management services for a network. In a web-based network, these services are best provided by one or more front-end WebSEAL servers that integrate and protect web resources and applications that are on back-end web servers.

The connection between a WebSEAL server and a back-end web application server is known as a standard WebSEAL junction.

Note: WebSEAL also supports virtual hosting through another form of junctions called virtual host junctions.

The back-end server can be another WebSEAL server or, more commonly, a third-party web application server. The back-end server web space is connected to the WebSEAL server at a specially designated junction (mount) point in the WebSEAL web space.

Figure 6. Junctions connect WebSEAL with back-end resources

A junction allows WebSEAL to provide protective services on behalf of the back-end server. WebSEAL authenticates and authorizes all requests before it passes those requests on to the back-end server. If the back-end server requires fine-grained access control on its objects, you must perform additional configuration steps, by using the query_contents CGI program, to describe the third-party web space to the Security Access Manager security service.

Junctions provide a scalable, secure environment that allows load balancing, high availability, and state management capabilities, all performed transparently to clients. As an administrator, you can benefit from this centralized management of the web space.

WebSEAL junctions provide the added value of logically combining the web space of a back-end server with the web space of the WebSEAL server. Junctions between cooperating servers result in a single, unified, distributed web space that is seamless and transparent to users.

The client never needs to know the physical location of a web resource. WebSEAL translates logical URL addresses into the physical addresses that a back-end server expects. Web objects can be moved from server to server without affecting the way that the client can access those objects.

A unified web space simplifies the management of all resources for the system administrator. Additional administrative benefits include scalability, load balancing, and high availability.

Figure 7. WebSEAL junction results in a unified web space

Most commercial web servers cannot define a logical web object space. Instead, their access control is connected to the physical file and directory structure. WebSEAL junctions can transparently define an object space that reflects organizational structure rather than the physical machine and directory structure that is commonly encountered on standard web servers.

With WebSEAL junctions, you can create single signon solutions. A single signon configuration allows a user to access a resource, regardless of the resource's location, by using only one initial login. Any further login requirements from back-end servers are handled transparently to the user.

WebSEAL junctions are an important tool for making your Web site scalable. With junctions, you can respond to increasing demands on a website by attaching additional servers.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Web space scalability

Web space scalability Web space scalability Web space scalability WebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site. scalabilityweb spacejunctionsscalabilityserversaddingAdditional servers can be added for the following reasons: To extend the web space with additional content.To duplicate existing content for load balancing, failover capability, and high availability.IBM Security Access Manager WebSEAL overview WebSEAL is a high performance, multi-threaded web server that applies fine-grained security policies to the Security Access Manager protected web object space. Use WebSEAL so that you can manage access to your private and internal resources.Introduction to IBM Security Access ManagerIBM Security Access Manager is a complete authorization and network security policy management solution. It provides end-to-end protection of resources over geographically dispersed intranets and extranets. WebSEAL introduction WebSEAL is a resource manager that protects web-based information and resources. It can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.IBM Security Access Manager applianceThe IBM Security Access Manager appliance provides access and authentication management for user to web application sessions and helps protect applications from threats.WebSEAL functionality on the applianceThe appliance web reverse proxy includes most of the features offered by a standard software installation of WebSEAL. However, there are some differences, as detailed in this section. Security concepts for a WebSEAL deploymentYou must understand the security model concepts so that you can successfully deploy WebSEAL and protect your resources. Basic concepts include protected object space, access control lists, and protected object policies.Authorization processThe authorization process determines whether an authenticated user has the right to perform an operation on a specific resource in a secure domain. Security policy planning and implementationA corporate security policy for web resources identifies the web resources that require protection and the level of protection. You can implement the security policy by applying the appropriate security mechanisms to the objects requiring protection.Content types and levels of protectionAs the security administrator of your web space, you must correctly identify the types of content available to various user types. Some content must be highly protected and available only to specific users; other content is for general public view.WebSEAL authenticationAuthentication is the method of identifying an individual process or entity that is attempting to log in to a secure domain. WebSEAL can enforce a high degree of security in a secure domain by requiring each user to provide proof of its identity.Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. Replicated front-end WebSEAL serversJunction support for back-end servers starts with at least one front-end WebSEAL server. Replicated front-end WebSEAL servers provide the site with load balancing during periods of heavy demand.Junctioned back-end serversWebsite content can be served by the WebSEAL server itself, back-end servers, or a combination of both. WebSEAL junction support for back-end servers allows you to scale the website through additional content and resources.Replicated back-end serversTo extend scalability features to a back-end server configuration, you can replicate the back-end servers. As is the case with replicated front-end servers, replicated back-end servers must contain web spaces that are mirror images of each other.

Web space scalability

WebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Additional servers can be added for the following reasons:

To extend the web space with additional content.

To duplicate existing content for load balancing, failover capability, and high availability.

Replicated front-end WebSEAL servers
Junction support for back-end servers starts with at least one front-end WebSEAL server. Replicated front-end WebSEAL servers provide the site with load balancing during periods of heavy demand.

Junctioned back-end servers
Website content can be served by the WebSEAL server itself, back-end servers, or a combination of both. WebSEAL junction support for back-end servers allows you to scale the website through additional content and resources.

Replicated back-end servers
To extend scalability features to a back-end server configuration, you can replicate the back-end servers. As is the case with replicated front-end servers, replicated back-end servers must contain web spaces that are mirror images of each other.

Parent topic: IBM Security Access Manager WebSEAL overview

Related concepts:

Introduction to IBM Security Access Manager

WebSEAL introduction

IBM Security Access Manager appliance

WebSEAL functionality on the appliance

Security concepts for a WebSEAL deployment

Authorization process

Security policy planning and implementation

Content types and levels of protection

WebSEAL authentication

Standard WebSEAL junctions

Replicated front-end WebSEAL servers Replicated front-end WebSEAL servers Junction support for back-end servers starts with at least one front-end WebSEAL server. Replicated front-end WebSEAL servers provide the site with load balancing during periods of heavy demand.scalabilityreplicated front-end serversuser registriesfront-end serversserversfront-endreplicationThe load balancing process is handled by a third-party device such as Cisco Local Director. Front-end replication also provides the site with failover capability. If a server fails for some reason, the remaining replica servers continue to provide access to the site. Successful load balancing and failover capability results in high availability for users of the site. When you replicate front-end WebSEAL servers, each server must contain an exact copy of the web space and the junction database.Account information for authentication is in a user registry that is independent of the front-end servers.Web space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Replicated front-end WebSEAL servers

Junction support for back-end servers starts with at least one front-end WebSEAL server. Replicated front-end WebSEAL servers provide the site with load balancing during periods of heavy demand.

The load balancing process is handled by a third-party device such as Cisco Local Director.

Front-end replication also provides the site with failover capability. If a server fails for some reason, the remaining replica servers continue to provide access to the site. Successful load balancing and failover capability results in high availability for users of the site.

When you replicate front-end WebSEAL servers, each server must contain an exact copy of the web space and the junction database.

Account information for authentication is in a user registry that is independent of the front-end servers.

Parent topic: Web space scalability

Junctioned back-end serversJunctioned back-end serversJunctioned back-end servers in IBM Security Access Manager for WebWebsite content can be served by the WebSEAL server itself, back-end servers, or a combination of both. WebSEAL junction support for back-end servers allows you to scale the website through additional content and resources.back-end serversillustrationsunified Web spaceillustrationsWebSEALjunctionsback-end serversback-end serversjunctionedjunctionsback-end serversserversback-endEach unique back-end server must be junctioned to a separate junction mount point. As the demand for additional content grows, more servers can be added through junctions. This scenario provides a solution for networks that have a large existing investment in third-party web servers. Junctioned back-end serversJunctioned back-end serversThe combined web spaces of the two back-end servers are transparent to the user and allows for centralized management. Unified web spaceUnified web spaceWeb space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Junctioned back-end servers

Website content can be served by the WebSEAL server itself, back-end servers, or a combination of both. WebSEAL junction support for back-end servers allows you to scale the website through additional content and resources.

Each unique back-end server must be junctioned to a separate junction mount point. As the demand for additional content grows, more servers can be added through junctions. This scenario provides a solution for networks that have a large existing investment in third-party web servers.

Figure 8. Junctioned back-end servers

The combined web spaces of the two back-end servers are transparent to the user and allows for centralized management.

Figure 9. Unified web space

Parent topic: Web space scalability

Replicated back-end servers Replicated back-end servers To extend scalability features to a back-end server configuration, you can replicate the back-end servers. As is the case with replicated front-end servers, replicated back-end servers must contain web spaces that are mirror images of each other.scalabilityreplicated back-end serversback-end serversreplicatedserversback-endreplicationWebSEAL balances loads across the replicated servers by using a least-busy scheduling algorithm. This algorithm directs each new request to the server with the fewest connections already in progress.WebSEAL also correctly fails over when a server is down and starts reusing that server after it is restarted.If the back-end application requires its state to be maintained over several pages, stateful junctions can be used to ensure that each session returns to the same back-end server. Replicated back-end serversReplicated back-end serversWeb space scalabilityWebSEAL junctions create a scalable web space. As the demands on the web space grow, more servers can easily be added to expand the capabilities of the site.

Replicated back-end servers

To extend scalability features to a back-end server configuration, you can replicate the back-end servers. As is the case with replicated front-end servers, replicated back-end servers must contain web spaces that are mirror images of each other.

WebSEAL balances loads across the replicated servers by using a least-busy scheduling algorithm. This algorithm directs each new request to the server with the fewest connections already in progress.

WebSEAL also correctly fails over when a server is down and starts reusing that server after it is restarted.

If the back-end application requires its state to be maintained over several pages, stateful junctions can be used to ensure that each session returns to the same back-end server.

Figure 10. Replicated back-end servers

Parent topic: Web space scalability

Server administrationServer administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.serversadministrationclusterssupportconfigurationcluster supportdatasynchronizationdeploymentupdatesAdministrationWith the centralized policy management solution for distributed applications in IBM Security Access Manager, you can build secure and well-managed intranets for Internet-based applications. You must understand how WebSEAL protects your resources so that you can successfully administer the WebSEAL server.WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.Error message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Server administration

You must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.

WebSEAL instance management
You can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.

Deploying WebSEAL updates in the LMI
When there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.

Synchronization of WebSEAL data across multiple servers
You can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.

Error message logging
WebSEAL uses a routing file to control the display of error messages and the logging of message data.

WebSEAL server activity auditing
The Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.

Traditional auditing and logging of HTTP events
Configure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.

Configuration data log file
Use the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Parent topic: Administration

WebSEAL instance managementWebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Reverse proxy management pageLMIjunction managementmanagement rootlogging inWebSEAL instancesconfigurationWebSEAL instance managementmanagementWebSEAL instancesrestartingWebSEAL instancesFrom the LMI top menu, select Secure Web Settings > Manage > Reverse Proxy. The Reverse Proxy management page displays.You can use this page to manage each WebSEAL instance. Select the WebSEAL instance that you want to manage from the list of available instances. The available options for managing the WebSEAL instances are detailed in the following table:WebSEAL instance managementOptionDescriptionNewCreate a WebSEAL instance.EditComplete basic configuration.DeleteDelete a WebSEAL instance.StartStart a WebSEAL instance.StopStop a WebSEAL instance.RestartRestart a WebSEAL instance.RefreshRefresh the list of WebSEAL instances and the associated details.ManageSelect from the following menu of management options: ConfigurationProvides advanced configuration options. You can modify the WebSEAL configuration file directly from this menu.TroubleshootingIncludes troubleshooting resources such as trace and statistics.Management RootProvides access to the WebSEAL root files.Junction ManagementIncludes junction creation and management.LoggingProvides access to the WebSEAL log files.Server administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.Error message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

WebSEAL instance management

You can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.

From the LMI top menu, select Secure Web Settings > Manage > Reverse Proxy. The Reverse Proxy management page displays.

You can use this page to manage each WebSEAL instance. Select the WebSEAL instance that you want to manage from the list of available instances. The available options for managing the WebSEAL instances are detailed in the following table:

Table 11. WebSEAL instance management

Option
Description

New
Create a WebSEAL instance.

Edit
Complete basic configuration.

Delete
Delete a WebSEAL instance.

Start
Start a WebSEAL instance.

Stop
Stop a WebSEAL instance.

Restart
Restart a WebSEAL instance.

Refresh
Refresh the list of WebSEAL instances and the associated details.

Manage
Select from the following menu of management options:

Configuration

Provides advanced configuration options. You can modify the WebSEAL configuration file directly from this menu.

Troubleshooting

Includes troubleshooting resources such as trace and statistics.

Management Root

Provides access to the WebSEAL root files.

Junction Management

Includes junction creation and management.

Logging

Provides access to the WebSEAL log files.

Parent topic: Server administration

Related concepts:

Error message logging

Traditional auditing and logging of HTTP events

Configuration data log file

Related tasks:

Deploying WebSEAL updates in the LMI

Related reference:

Synchronization of WebSEAL data across multiple servers

WebSEAL server activity auditing

Deploying WebSEAL updates in the LMIDeploying WebSEAL updates in the LMIDeploying WebSEAL updates in IBM Security Access Manager for WebWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.deploymentWebSEALupdatesWebSEALupdatesLMIWebSEAL updatesAny changes that affect running reverse proxy instances require a restart of the effected instances before the changes can take effect.Click the Click here to review the changes or apply them to the system link in the warning message.In the Deploy Pending Changes page:To view the details of changes that are made to a particular module, click the link to that module.To deploy the changes, click Deploy.To abandon the changes, click Roll Back.To close the pop-up page without any actions against the changes, click Cancel.Server administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.Error message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Deploying WebSEAL updates in the LMI

When there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.

About this task

Any changes that affect running reverse proxy instances require a restart of the effected instances before the changes can take effect.

Procedure

Click the Click here to review the changes or apply them to the system link in the warning message.

In the Deploy Pending Changes page:

To view the details of changes that are made to a particular module, click the link to that module.

To deploy the changes, click Deploy.

To abandon the changes, click Roll Back.

To close the pop-up page without any actions against the changes, click Cancel.

Parent topic: Server administration

Related concepts:

WebSEAL instance management

Error message logging

Traditional auditing and logging of HTTP events

Configuration data log file

Related reference:

Synchronization of WebSEAL data across multiple servers

WebSEAL server activity auditing

Synchronization of WebSEAL data across multiple serversSynchronization of WebSEAL data across multiple serversWebSEAL data synchronization across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.WebSEALdata synchronizationWebSEAL serverssync commandserverssync commandsynchronizationconfigurationWebSEAL serversdatasynchronizationYou can synchronize servers of the same type only. The WebSEAL server type is either a:WebSEAL running on an appliance.WebSEAL running on a standard operating system.You can use the following list of server task commands for various tasks, including: Synchronizing one replicated WebSEAL server with another of the same type.Migrating one WebSEAL environment to another (for example, from test to production). server syncUsed to synchronize the configuration of the supplied WebSEAL server to the current WebSEAL server. The server sync command invokes the other commands on this list for a complete synchronization operation. The data that can be synchronized includes configuration entries, the junction database, and selected data files, but not the object space or policy. Configuration entries and data files to be synchronized can be customized in the WebSEAL configuration file. For details, see server task server syncThe server task server sync command synchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework. .server restartUsed to restart the WebSEAL instance. For details, see server task server restartThe server task server restart command restarts a WebSEAL server by using the Security Access Manager server task framework. . The following list describes the flow of communication for the server sync command:The server sync command is issued from the administration console.The request for data is issued from the WebSEAL server as a new server task command. The source WebSEAL server gathers the data for synchronization and sends it to the target WebSEAL server.The target WebSEAL server applies the data retrieved.The request for data is issued from the WebSEAL server that is processing the server sync task. Data is pulled from one WebSEAL server to another with authorization automatically applied by the Security Access Manager server task framework. By using an existing communication channel, there is no need to open up more ports for the WebSEAL server.Server administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.Error message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation. Automating synchronization

Synchronization of WebSEAL data across multiple servers

You can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.

Note: You can synchronize servers of the same type only. The WebSEAL server type is either a:

WebSEAL running on an appliance.

WebSEAL running on a standard operating system.

You can use the following list of server task commands for various tasks, including:

Synchronizing one replicated WebSEAL server with another of the same type.

Migrating one WebSEAL environment to another (for example, from test to production).

server sync

Used to synchronize the configuration of the supplied WebSEAL server to the current WebSEAL server. The server sync command invokes the other commands on this list for a complete synchronization operation. The data that can be synchronized includes configuration entries, the junction database, and selected data files, but not the object space or policy. Configuration entries and data files to be synchronized can be customized in the WebSEAL configuration file. For details, see server task server sync.

server restart

Used to restart the WebSEAL instance. For details, see server task server restart.

The following list describes the flow of communication for the server sync command:

The server sync command is issued from the administration console.

The request for data is issued from the WebSEAL server as a new server task command.

The source WebSEAL server gathers the data for synchronization and sends it to the target WebSEAL server.

The target WebSEAL server applies the data retrieved.

The request for data is issued from the WebSEAL server that is processing the server sync task. Data is pulled from one WebSEAL server to another with authorization automatically applied by the Security Access Manager server task framework. By using an existing communication channel, there is no need to open up more ports for the WebSEAL server.

Automating synchronization

Parent topic: Server administration

Related concepts:

WebSEAL instance management

Error message logging

Traditional auditing and logging of HTTP events

Configuration data log file

Related tasks:

Deploying WebSEAL updates in the LMI

Related reference:

WebSEAL server activity auditing

Automating synchronizationAutomating synchronizationWebSEALcluster supportsynchronizationclustersWebSEALconfigurationWebSEAL serversserversWebSEALYou can configure more than one WebSEAL server in your environment. The term cluster refers to a group of WebSEAL servers that are configured to work together. You can use WebSEAL clusters to automate the synchronization of configuration information between different WebSEAL servers. Clustering can also improve system availability and performance. All cluster members must be the same server type. The WebSEAL server type for the cluster is either a:WebSEAL running on appliances.WebSEAL running on standard operating systems.In a clustered environment, you must nominate a master server that is responsible for all cluster configuration changes. The remaining servers in the cluster are designated as slaves. Whenever a slave is restarted, it checks the configuration information about the cluster master. If the slave's internal configuration information is not up to date then the slave automatically synchronizes with the master. You can synchronize all servers in the cluster by using the cluster restart server task command.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.Cluster restartTo synchronize the various WebSEAL servers, first select a master server. For example, default-webseald-master.ibm.com houses the generic configuration. Any configuration changes that you want made available to all servers must first be manually changed for the master server that includes the configuration files and junction definitions.Configure WebSEAL for cluster supportUse the [cluster] configuration stanza entries so that you can configure each of the WebSEAL servers in your clustered environment.

Automating synchronization

You can configure more than one WebSEAL server in your environment. The term cluster refers to a group of WebSEAL servers that are configured to work together. You can use WebSEAL clusters to automate the synchronization of configuration information between different WebSEAL servers. Clustering can also improve system availability and performance.

Note: All cluster members must be the same server type. The WebSEAL server type for the cluster is either a:

WebSEAL running on appliances.

WebSEAL running on standard operating systems.

In a clustered environment, you must nominate a master server that is responsible for all cluster configuration changes. The remaining servers in the cluster are designated as slaves.

Whenever a slave is restarted, it checks the configuration information about the cluster master. If the slave's internal configuration information is not up to date then the slave automatically synchronizes with the master. You can synchronize all servers in the cluster by using the cluster restart server task command.

Cluster restart
To synchronize the various WebSEAL servers, first select a master server. For example, default-webseald-master.ibm.com houses the generic configuration. Any configuration changes that you want made available to all servers must first be manually changed for the master server that includes the configuration files and junction definitions.

Configure WebSEAL for cluster support
Use the [cluster] configuration stanza entries so that you can configure each of the WebSEAL servers in your clustered environment.

Parent topic: Synchronization of WebSEAL data across multiple servers

Cluster restartCluster restartCluster restartIBM Security Access Manager for WebTo synchronize the various WebSEAL servers, first select a master server. For example, default-webseald-master.ibm.com houses the generic configuration. Any configuration changes that you want made available to all servers must first be manually changed for the master server that includes the configuration files and junction definitions.clustersrestartillustrationsserver task commandserversmastersconfiguration filesjunctionssynchronizationrestartingclustersYou must only modify the configuration information on the master. If you modify the configuration on a slave, you risk losing information during the next restart of the server when the slave synchronizes its configuration information with the master.When you configure a WebSEAL cluster in your environment, you can issue a cluster restart server task command from the master server to apply any configuration changes and restart the updated servers. You can use the -ripple option to specify whether to restart the clustered WebSEAL servers in parallel or in sequence. There is also a -status option that you can use to monitor the progress of a cluster restart. See server task cluster restartThe server task cluster restart command applies any configuration changes to the entire cluster and restarts the updated servers. . Cluster SupportCluster restartFigure 1 shows the cluster restart process that involves the following high-level steps:Run the cluster restart server task command on the master server to initiate the restart.The master issues a server restart command on each of the slaves in the cluster. This is either done in parallel or in sequence depending on whether the -ripple option was used in the cluster restart command.The slave retrieves the timestamp that indicates when the master configuration information was last modified.If the configuration data stored locally on the slave is not up to date, then the slave synchronizes with the master configuration data.If the slave configuration data was updated in step 4, then the slave server restarts. If the local configuration database on the slave did not need updating, then the slave does not restart.The slave notifies the master that its operation is complete.Once all slaves are updated and restarted where required, the master server restarts.Automating synchronization

Cluster restart

To synchronize the various WebSEAL servers, first select a master server. For example, default-webseald-master.ibm.com houses the generic configuration. Any configuration changes that you want made available to all servers must first be manually changed for the master server that includes the configuration files and junction definitions.

About this task

You must only modify the configuration information on the master. If you modify the configuration on a slave, you risk losing information during the next restart of the server when the slave synchronizes its configuration information with the master.

When you configure a WebSEAL cluster in your environment, you can issue a cluster restart server task command from the master server to apply any configuration changes and restart the updated servers. You can use the -ripple option to specify whether to restart the clustered WebSEAL servers in parallel or in sequence. There is also a -status option that you can use to monitor the progress of a cluster restart. See server task cluster restart.

Figure 11.  Cluster SupportCluster restart

Figure 11. shows the cluster restart process that involves the following high-level steps:

Procedure

Run the cluster restart server task command on the master server to initiate the restart.

The master issues a server restart command on each of the slaves in the cluster.

Note: This is either done in parallel or in sequence depending on whether the -ripple option was used in the cluster restart command.

The slave retrieves the timestamp that indicates when the master configuration information was last modified.

If the configuration data stored locally on the slave is not up to date, then the slave synchronizes with the master configuration data.

If the slave configuration data was updated in step 4, then the slave server restarts. If the local configuration database on the slave did not need updating, then the slave does not restart.

The slave notifies the master that its operation is complete.

Once all slaves are updated and restarted where required, the master server restarts.

Parent topic: Automating synchronization

Configure WebSEAL for cluster supportConfigure WebSEAL for cluster supportUse the [cluster] configuration stanza entries so that you can configure each of the WebSEAL servers in your clustered environment. WebSEALcluster supportconfigurationclusterssupportWebSEALconfigurationWebSEAL for cluster supportYou must identify one server to be the master of the WebSEAL cluster. The is-master configuration entry is set to yes for the master server. You can also configure a max-wait-time on the master that represents the maximum number of seconds that the master server waits for each slave server to be restarted.All other servers in the cluster must have the is-master configuration entry set to no. These servers are the slaves in the cluster. You must configure an additional configuration entry called master-name on each of the slaves. The master-name configuration entry specifies the authorization server name of the master server. For example, default-webseald-master.ibm.com.For more information about [cluster] stanza, see the the Reference topics in the IBM Knowledge Center.For failover considerations in a clustered environment, see Failover to a new master.Automating synchronization

Configure WebSEAL for cluster support

Use the [cluster] configuration stanza entries so that you can configure each of the WebSEAL servers in your clustered environment.

You must identify one server to be the master of the WebSEAL cluster. The is-master configuration entry is set to yes for the master server. You can also configure a max-wait-time on the master that represents the maximum number of seconds that the master server waits for each slave server to be restarted.

All other servers in the cluster must have the is-master configuration entry set to no. These servers are the slaves in the cluster. You must configure an additional configuration entry called master-name on each of the slaves. The master-name configuration entry specifies the authorization server name of the master server. For example, default-webseald-master.ibm.com.

For more information about [cluster] stanza, see the the Reference topics in the IBM® Knowledge Center.

Note: For failover considerations in a clustered environment, see Failover to a new master.

Parent topic: Automating synchronization

Error message loggingError message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.UTF-8messages in UTF-8 formatservicability messagesERROR error messageWARNING error messageFATAL error messagerouting filesmessage severity levelsmessage log roll overformatoperationtemplate locationerror message logsmessages in UTF-8 formatTivoli message formatrouting filesWebSEALmessagesmessages in UTF-8 formatmessage ID formatTivoli Common DirectoryWebSEAL log filesrouting filesTivoli message formatloggingNOTICE_VERBOSE error messageNOTICE error messageTivoli Common DirectoryTivoli message formaterror message logsTivoli Common Directorymsg_webseald-instance-name.logloggingerror messagesserverserror messagesWebSEAL server error messages are formatted by using a standard format. By default, WebSEAL uses a single log file to record server error message data.The WebSEAL routing file controls default message routing. The routing file can be modified for customized message logging.For complete information about the WebSEAL routing file and error message logging, see the Troubleshooting topics in the IBM Knowledge Center.Server administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Error message logging

WebSEAL uses a routing file to control the display of error messages and the logging of message data.

WebSEAL server error messages are formatted by using a standard format. By default, WebSEAL uses a single log file to record server error message data.

The WebSEAL routing file controls default message routing. The routing file can be modified for customized message logging.

For complete information about the WebSEAL routing file and error message logging, see the Troubleshooting topics in the IBM Knowledge Center.

Parent topic: Server administration

Related concepts:

WebSEAL instance management

Traditional auditing and logging of HTTP events

Configuration data log file

Related tasks:

Deploying WebSEAL updates in the LMI

Related reference:

Synchronization of WebSEAL data across multiple servers

WebSEAL server activity auditing

WebSEAL server activity auditingWebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.auditingevent loggingWebSEAL server activitytrail filespdaudit-filter stanzaCARSpdaudit.confpdaudit.conf configuration filelogsHTTPHTTPlogsusing event logsevent logsHTTPlogcfg stanza entryevent logslogcfgaznapi-configuration stanzaHTTPevent poolshttp.clf event poolhttp.agent event poolhttp.cof event pool (NCSA)http.ref event poolNCSA combined formatevent poolhttphttp.clfhttp.refhttp.agenthttp.cofserversWebSEALTo implement event logging, you use the logcfg event logging stanza entry to define one or more log agents (loggers) that gather a specific category of audit information from the event pool and direct this information to a destination. The logcfg stanza entries are entered in the [pdaudit-filter] stanza of the pdaudit.conf configuration file. The pdaudit.conf configuration file is a component of the Common Auditing and Reporting Service (CARS).WebSEAL still supports event logging configuration through the [aznapi-configuration] stanza in the WebSEAL configuration file. The format of the logcfg event logging stanza entries remains the same whether entered in the [pdaudit-filter] stanza of the pdaudit.conf configuration file or the [aznapi-configuration] stanza of the WebSEAL configuration file.For complete information about the event logging mechanism, see the Auditing topics in the IBM Knowledge Center. WebSEAL also supports traditional auditing and logging of HTTP events. Use this traditional mechanism only for situations that require compatibility with older installations of Security Access Manager. See Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events. and Traditional auditing mechanismTraditional auditing is configured by supplying a value for each the following stanza entries in the [aznapi-configuration] stanza of the WebSEAL configuration file..Server administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.Error message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation. Traditional auditing mechanismTraditional auditing is configured by supplying a value for each the following stanza entries in the [aznapi-configuration] stanza of the WebSEAL configuration file.

WebSEAL server activity auditing

The Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.

To implement event logging, you use the logcfg event logging stanza entry to define one or more log agents (loggers) that gather a specific category of audit information from the event pool and direct this information to a destination.

The logcfg stanza entries are entered in the [pdaudit-filter] stanza of the pdaudit.conf configuration file. The pdaudit.conf configuration file is a component of the Common Auditing and Reporting Service (CARS).

WebSEAL still supports event logging configuration through the [aznapi-configuration] stanza in the WebSEAL configuration file. The format of the logcfg event logging stanza entries remains the same whether entered in the [pdaudit-filter] stanza of the pdaudit.conf configuration file or the [aznapi-configuration] stanza of the WebSEAL configuration file.

For complete information about the event logging mechanism, see the Auditing topics in the IBM Knowledge Center.

Note: WebSEAL also supports traditional auditing and logging of HTTP events. Use this traditional mechanism only for situations that require compatibility with older installations of Security Access Manager. See Traditional auditing and logging of HTTP events and Traditional auditing mechanism.

Traditional auditing mechanism
Traditional auditing is configured by supplying a value for each the following stanza entries in the [aznapi-configuration] stanza of the WebSEAL configuration file.

Parent topic: Server administration

Related concepts:

WebSEAL instance management

Error message logging

Traditional auditing and logging of HTTP events

Configuration data log file

Related tasks:

Deploying WebSEAL updates in the LMI

Related reference:

Synchronization of WebSEAL data across multiple servers

Traditional auditing mechanismTraditional auditing mechanismTraditional auditing is configured by supplying a value for each the following stanza entries in the [aznapi-configuration] stanza of the WebSEAL configuration file.logaudit stanza entryauditcfg stanza entryauditlog stanza entrylogsize stanza entrylogflush stanza entryauditingtraditional[aznapi-configuration] logaudit auditcfg logsize logflushUse of this method is comparable to the event logging method when directing output to a file. Note, however, that the event logging method provides more control over buffer size and event queues. Also, traditional auditing does not support output to consoles, pipes, or remote servers.For more information about traditional auditing configuration settings for authentication, authorization, and HTTP events, see the Auditing topics in the IBM Knowledge Center.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.

Traditional auditing mechanism

Traditional auditing is configured by supplying a value for each the following stanza entries in the [aznapi-configuration] stanza of the WebSEAL configuration file.

[aznapi-configuration]
logaudit
auditcfg
logsize
logflush

Use of this method is comparable to the event logging method when directing output to a file. Note, however, that the event logging method provides more control over buffer size and event queues. Also, traditional auditing does not support output to consoles, pipes, or remote servers.

For more information about traditional auditing configuration settings for authentication, authorization, and HTTP events, see the Auditing topics in the IBM Knowledge Center.

Parent topic: WebSEAL server activity auditing

Traditional auditing and logging of HTTP eventsTraditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.logsHTTPrequest.logreferer.logagent.logrequestsstanza entryauditingtraditionalHTTP eventsreferers stanza entryagents stanza entryrequests-file stanza entryreferers-file stanza entryagents-file stanza entryHTTPlogsenablingdisablingtimestamplog file rollover thresholdbuffer flush frequencyHTTP common log formatutf8 encodinggmt-time stanza entrymax-size stanza entryflush-time stanza entryHTTPcommon log formatcommon log formatlog dataUTF-8log dataloggingstanzaHTTP eventsMIME-typesresponse codesWebSEAL maintains three traditional HTTP log files that record HTTP activity: request.log agent.log referer.log The request log can be customized by adding a request-log-format entry to the [logging] stanza. For more information about customized logging and traditional auditing and logging of HTTP events, see the Auditing topics in the IBM Knowledge Center.HTTP resource access audit events can be filtered by document MIME-types and response codes by using the following stanza entries in the [logging] stanza of the WebSEAL configuration file: [logging] audit-mime-types audit-response-codesServer administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.Error message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Traditional auditing and logging of HTTP events

Configure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.

WebSEAL maintains three traditional HTTP log files that record HTTP activity:

request.log

agent.log

referer.log

The request log can be customized by adding a request-log-format entry to the [logging] stanza. For more information about customized logging and traditional auditing and logging of HTTP events, see the Auditing topics in the IBM Knowledge Center.

HTTP resource access audit events can be filtered by document MIME-types and response codes by using the following stanza entries in the [logging] stanza of the WebSEAL configuration file:

[logging]
audit-mime-types
audit-response-codes

Parent topic: Server administration

Related concepts:

WebSEAL instance management

Error message logging

Configuration data log file

Related tasks:

Deploying WebSEAL updates in the LMI

Related reference:

Synchronization of WebSEAL data across multiple servers

WebSEAL server activity auditing

Configuration data log fileConfiguration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation. config-data-logconfigurationdata log filesoverviewproblem determinationconfiguration data log fileWebSEALconfigurationdata log filesdataconfigurationEach WebSEAL instance records the complete contents of its configuration file in a log file every time that instance is started. Many WebSEAL problems are often the result of incorrect or incomplete configuration file settings. The logged configuration data provides an accurate snapshot of the current configuration settings for any WebSEAL instance.When asked to troubleshoot a WebSEAL-related problem, IBM Support can rely on the information that is contained in this logged configuration data. The accuracy and completeness of this information increases the efficiency of the troubleshooting process. Alternatively, you can use this logged configuration data to perform your own diagnosis of a WebSEAL problem.Server administrationYou must understand the different server management tasks so that you can successfully administer WebSEAL. You can manage instances, deploy updates, synchronize data, configure cluster support, and access log files.WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance.Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes.Synchronization of WebSEAL data across multiple serversYou can use the WebSEAL server sync command to synchronize the configuration of one WebSEAL server with another.Error message loggingWebSEAL uses a routing file to control the display of error messages and the logging of message data.WebSEAL server activity auditingThe Security Access Manager event logging mechanism can capture common events and activity that is generated by WebSEAL. Event logging provides a structured hierarchy for capturing information for auditing purposes. Event logging also supports the use of alternative destinations for logging output, such as files and remote servers.Traditional auditing and logging of HTTP eventsConfigure the [logging] stanza of the WebSEAL configuration file so that you can audit and log HTTP events.Configuration data log file locationUse the appliance local management interface to access the configuration data log files. Notes on configuration data log file growthTake note of the following details about the size of log files.Configuration data log file formatIn the WebSEAL configuration file, a default value for a stanza entry is provided by WebSEAL during initial installation and configuration. If an administrator later modifies a value in the configuration file, that custom value becomes non-default. Messages relating to the configuration data log fileA serviceability message is entered in the WebSEAL log file that specifies the location of the log file every time a configuration data log file is created.StatisticsWebSEAL provides a series of built-in software modules to monitor specific server activity and collect information about those activities. You can view the statistics from any active module. You can also direct the statistics information to the log files. Trace utilityThe trace utility captures information about error conditions and program control flow in Security Access Manager, WebSEAL, and Plug-in for Web Servers. This information is stored in a file and used for debugging and problem determination purposes.

Configuration data log file

Use the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Each WebSEAL instance records the complete contents of its configuration file in a log file every time that instance is started. Many WebSEAL problems are often the result of incorrect or incomplete configuration file settings. The logged configuration data provides an accurate snapshot of the current configuration settings for any WebSEAL instance.

When asked to troubleshoot a WebSEAL-related problem, IBM® Support can rely on the information that is contained in this logged configuration data. The accuracy and completeness of this information increases the efficiency of the troubleshooting process. Alternatively, you can use this logged configuration data to perform your own diagnosis of a WebSEAL problem.

Configuration data log file location
Use the appliance local management interface to access the configuration data log files.

Notes on configuration data log file growth
Take note of the following details about the size of log files.

Configuration data log file format
In the WebSEAL configuration file, a default value for a stanza entry is provided by WebSEAL during initial installation and configuration. If an administrator later modifies a value in the configuration file, that custom value becomes non-default.

Messages relating to the configuration data log file
A serviceability message is entered in the WebSEAL log file that specifies the location of the log file every time a configuration data log file is created.

Statistics
WebSEAL provides a series of built-in software modules to monitor specific server activity and collect information about those activities. You can view the statistics from any active module. You can also direct the statistics information to the log files.

Trace utility
The trace utility captures information about error conditions and program control flow in Security Access Manager, WebSEAL, and Plug-in for Web Servers. This information is stored in a file and used for debugging and problem determination purposes.

Parent topic: Server administration

Related concepts:

WebSEAL instance management

Error message logging

Traditional auditing and logging of HTTP events

Related tasks:

Deploying WebSEAL updates in the LMI

Related reference:

Synchronization of WebSEAL data across multiple servers

WebSEAL server activity auditing

Configuration data log file locationConfiguration data log file locationUse the appliance local management interface to access the configuration data log files. LMIManage Reverse Proxy Log Files management pagesconfigurationdata log fileslocationsdataconfigurationSelect Secure Web SettingsManageReverse Proxy. Select the appropriate WebSEAL instance and click Manage > Logging. Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Configuration data log file location

Use the appliance local management interface to access the configuration data log files.

Select Secure Web Settings > Manage > Reverse Proxy. Select the appropriate WebSEAL instance and click Manage > Logging.

Parent topic: Configuration data log file

Notes on configuration data log file growthNotes on configuration data log file growthTake note of the following details about the size of log files.dataconfigurationconfigurationdata log filesgrowth Only 1 log file is created when a WebSEAL instance is started for the first time.Data from the complete WebSEAL configuration file is recorded in the log file each time that WebSEAL instance is started.The configuration file data for each subsequent startup is appended to the same log file.Each entry in the log file begins with a timestamp. The timestamp entry distinguishes each data entry from the others.The log file continues to grow in size with each new entry. You can use the local management interface to control the size of this file.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Notes on configuration data log file growth

Take note of the following details about the size of log files.

Only 1 log file is created when a WebSEAL instance is started for the first time.

Data from the complete WebSEAL configuration file is recorded in the log file each time that WebSEAL instance is started.

The configuration file data for each subsequent startup is appended to the same log file.

Each entry in the log file begins with a timestamp. The timestamp entry distinguishes each data entry from the others.

The log file continues to grow in size with each new entry. You can use the local management interface to control the size of this file.

Parent topic: Configuration data log file

Configuration data log file formatConfiguration data log file formatIn the WebSEAL configuration file, a default value for a stanza entry is provided by WebSEAL during initial installation and configuration. If an administrator later modifies a value in the configuration file, that custom value becomes non-default. datalog file formatconfigurationconfigurationdata log filesformatIn the configuration data log file, a special marker ([default]) identifies any stanza entry value that is default. Non-default values do not contain this marker. For example: ... https = yes https-port = [default] 443 http = yes http-port = [default] 80 ...The information in the configuration data log file is grouped according to the same stanzas that occur in the actual WebSEAL configuration file. The following partial view of a configuration data log file shows stanza entries and values that are grouped by stanzas. This example also includes a sample timestamp line: ============================================ Configuration Data Logged: Fri Jul 23 15:37:02 2004 ... [gso-cache] gso-cache-enabled = [default] no gso-cache-size = [default] 1024 gso-cache-entry-lifetime = [default] 900 gso-cache-entry-idle-timeout = [default] 120 [ltpa-cache] ltpa-cache-enabled = [default] yes ltpa-cache-size = [default] 4096 ltpa-cache-entry-lifetime = [default] 3600 ltpa-cache-entry-idle-timeout = [default] 600 [ba] ba-auth = [default] https [forms] forms-auth = [default] none [certificate] accept-client-certs = [default] never cert-cache-max-entries = [default] 1024 cert-cache-timeout = [default] 120 ...Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Configuration data log file format

In the WebSEAL configuration file, a default value for a stanza entry is provided by WebSEAL during initial installation and configuration. If an administrator later modifies a value in the configuration file, that custom value becomes non-default.

In the configuration data log file, a special marker ([default]) identifies any stanza entry value that is default. Non-default values do not contain this marker. For example:

...
https = yes
https-port = [default] 443
http = yes
http-port = [default] 80
...

The information in the configuration data log file is grouped according to the same stanzas that occur in the actual WebSEAL configuration file. The following partial view of a configuration data log file shows stanza entries and values that are grouped by stanzas. This example also includes a sample timestamp line:

============================================
Configuration Data Logged: Fri Jul 23 15:37:02 2004
...
[gso-cache]
gso-cache-enabled = [default] no
gso-cache-size = [default] 1024
gso-cache-entry-lifetime = [default] 900
gso-cache-entry-idle-timeout = [default] 120

[ltpa-cache]
ltpa-cache-enabled = [default] yes
ltpa-cache-size = [default] 4096
ltpa-cache-entry-lifetime = [default] 3600
ltpa-cache-entry-idle-timeout = [default] 600

[ba]
ba-auth = [default] https

[forms]
forms-auth = [default] none

[certificate]
accept-client-certs = [default] never
cert-cache-max-entries = [default] 1024
cert-cache-timeout = [default] 120

...

Parent topic: Configuration data log file

Messages relating to the configuration data log fileMessages relating to the configuration data log fileA serviceability message is entered in the WebSEAL log file that specifies the location of the log file every time a configuration data log file is created.dataconfigurationconfig-data-logconfigurationdata log filesmessagesmessagesconfiguration data log file "The configuration data for this WebSEAL instance has been logged in %s" The %s macro is replaced by the string containing the name of the log file.If for any reason the configuration file data cannot be logged during a WebSEAL startup, the WebSEAL startup proceeds without interruption and an error message is recorded in the WebSEAL log file: "An error occurred trying to log the WebSEAL configuration data at startup."Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Messages relating to the configuration data log file

A serviceability message is entered in the WebSEAL log file that specifies the location of the log file every time a configuration data log file is created.

"The configuration data for this WebSEAL instance has been logged in %s"

The %s macro is replaced by the string containing the name of the log file.

If for any reason the configuration file data cannot be logged during a WebSEAL startup, the WebSEAL startup proceeds without interruption and an error message is recorded in the WebSEAL log file:

"An error occurred trying to log the WebSEAL configuration data at startup."

Parent topic: Configuration data log file

StatisticsStatisticsWebSEAL provides a series of built-in software modules to monitor specific server activity and collect information about those activities. You can view the statistics from any active module. You can also direct the statistics information to the log files. statistics utilityWebSEALstatistics utilitiesproblem determinationstatistics utilitiesEach active module captures statistics information. You can configure WebSEAL to capture statistics at regular intervals and view a snapshot of this information at any time. The appliance collects flow data. Flow data provides performance and throughput statistics for WebSEAL. The appliance records the statistics in a separate database for each WebSEAL instance. You can use the local management interface to retrieve these statistics.Use the [flow-data] and [user-agent] stanzas to configure the flow data statistics for the appliance. For more information, see the Administration topics in the IBM Knowledge Center.Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Statistics

WebSEAL provides a series of built-in software modules to monitor specific server activity and collect information about those activities. You can view the statistics from any active module. You can also direct the statistics information to the log files.

Each active module captures statistics information. You can configure WebSEAL to capture statistics at regular intervals and view a snapshot of this information at any time.

The appliance collects flow data. Flow data provides performance and throughput statistics for WebSEAL. The appliance records the statistics in a separate database for each WebSEAL instance. You can use the local management interface to retrieve these statistics.

Use the [flow-data] and [user-agent] stanzas to configure the flow data statistics for the appliance. For more information, see the Administration topics in the IBM Knowledge Center.

Parent topic: Configuration data log file

Trace utilityTrace utilityThe trace utility captures information about error conditions and program control flow in Security Access Manager, WebSEAL, and Plug-in for Web Servers. This information is stored in a file and used for debugging and problem determination purposes. WebSEALtrace utilitiestrace utilitiesproblem determinationtrace utilitiesLMIManage Reverse Proxy Tracing management pagesThe trace utility is provided primarily to assist support personnel in diagnosing problems that occur with the functions of the Security Access Manager. As a user, you might find some of the Security Access Manager, WebSEAL, and Plug-in for Web Servers tracing components useful. However, most of the components are of little benefit unless you are diagnosing complex problems with the assistance of technical support personnel.Trace data is intended primarily for use by IBM Tivoli Software Support personnel and might be requested as part of diagnosing a reported problem. However, experienced product administrators can also use trace data to diagnose and correct problems in the Security Access Manager environment.You can use the appliance local management interface to access the trace files. Select Secure Web SettingsManage Reverse Proxy. Select the appropriate WebSEAL instance and click Manage > Troubleshooting > Tracing. Configuration data log fileUse the configuration data so that you can troubleshoot problems with WebSEAL installation and operation.

Trace utility

The trace utility captures information about error conditions and program control flow in Security Access Manager, WebSEAL, and Plug-in for Web Servers. This information is stored in a file and used for debugging and problem determination purposes.

The trace utility is provided primarily to assist support personnel in diagnosing problems that occur with the functions of the Security Access Manager. As a user, you might find some of the Security Access Manager, WebSEAL, and Plug-in for Web Servers tracing components useful. However, most of the components are of little benefit unless you are diagnosing complex problems with the assistance of technical support personnel.

Trace data is intended primarily for use by IBM® Tivoli® Software Support personnel and might be requested as part of diagnosing a reported problem. However, experienced product administrators can also use trace data to diagnose and correct problems in the Security Access Manager environment.

You can use the appliance local management interface to access the trace files. Select Secure Web Settings > Manage > Reverse Proxy. Select the appropriate WebSEAL instance and click Manage > Troubleshooting > Tracing.

Parent topic: Configuration data log file

ConfigurationConfigurationWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Web server response configurationWeb server security configurationDefault port numbersThe installation uses several port numbers by default.

Configuration

Web server configuration
Configure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.

Web server response configuration

Web server security configuration

Default port numbers
The installation uses several port numbers by default.

Parent topic: Web Reverse Proxy configuration

Web server configurationWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.web serversconfigurationconfigurationweb serversConfigurationSpecifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Web server configuration

Configure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.

Specifying the WebSEAL host name
Typically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.

Modifying the configuration file settings
The operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.

Content caching
WebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.

Communication protocol configuration
You can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

IPv4 and IPv6 overview
Beginning with Tivoli® Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).

Configuring WebSEAL for IPv6 and IPv4 requests
By default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6.

IPv6: Compatibility support
Before you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.

IPv6: Upgrade notes
When you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.

IP levels for credential attributes
Network information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level.

LDAP directory server configuration
When Security Access Manager is configured to use an LDAP-based user registry, such as IBM®Tivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server.

WebSEAL worker thread configuration
The number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.

WebSEAL worker threads
WebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.

Global allocation of worker threads for junctions
You can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server.

Per-junction allocation of worker threads for junctions
Use the pdadmin command so that you can limit worker thread consumption on a per-junction basis.

Allocation view of worker threads for junctions
Use the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.

HTTP data compression
The WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.

WebSEAL data handling by using UTF-8
WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.

UTF-8 dependency on user registry configuration
For optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.

UTF-8 data conversion issues
WebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output.

UTF-8 impact on authentication
The use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.

UTF-8 impact on authorization (dynamic URL)
WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.

Encoding type usage
WebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.

UTF-8 support for uniform resource locators
There are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.

UTF-8 support in POST body information (forms)
Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.

UTF-8 support in query strings
You can enable UTF-8 support in query strings by editing the WebSEAL configuration file.

UTF-8 encoding of tokens for cross domain single signon
The use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.

UTF-8 encoding of tokens for e-community single signon
The use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.

UTF-8 encoding of cookies for failover authentication
You can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.

UTF-8 encoding of cookies for LTPA authentication
WebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding.

UTF-8 encoding in junction requests
By default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.

Validation of character encoding in request data
WebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.

Supported wildcard pattern matching characters
WebSEAL supports wildcard pattern matching characters.

Setting system environment variables
Use the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Parent topic: Configuration

Specifying the WebSEAL host nameSpecifying the WebSEAL host nameSpecifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.WebSEALweb-host-name stanza entryweb-host-name stanza entryYou must understand the WebSEAL server name in the following situations.In the configuration fileThe name uniquely identifies a WebSEAL server process. You can install and configure multiple WebSEAL servers on one computer system. Therefore, each WebSEAL server process must have a unique name. Each WebSEAL server process is known as an instance. Each WebSEAL instance has its own configuration file. The server-name stanza entry in the [server] stanza of the configuration file for each WebSEAL instance specifies the unique name for that WebSEAL instance. The server-name stanza entry is a combination of the host name of the physical computer where WebSEAL is installed and the WebSEAL instance name. Both names are specified during WebSEAL configuration.[server] server-name = host_name-instance_nameA computer host name always has a fully qualified name, for example, abc.ibm.com). It also can have a short name, for example, abc. When prompted for the host name during WebSEAL configuration, you can specify either the fully qualified name or the short name. In the following example, the WebSEAL instance name web1 is on a computer with a fully qualified host name of abc.ibm.com, as specified during WebSEAL configuration.[server] server-name = abc.ibm.com-web1The initial WebSEAL server is automatically assigned an instance name of default, unless you modify this name during WebSEAL configuration. For example:[server] server-name = abc.ibm.com-defaultIn the pdadmin server list commandThe instance name also affects how the WebSEAL server is listed with the pdadmin server list command. Because the pdadmin command serves the entire Security Access Manager family, a product component name is required in the command syntax. The component name for WebSEAL is webseald. For the pdadmin server list command, the WebSEAL server name has the following format.instance_name-webseald-host_nameThe following example shows the output from pdadmin server list for the instance web1 installed on the host abc.ibm.com:web1-webseald-abc.ibm.comThe following pdadmin server list command output displays an initial default WebSEAL server and a second WebSEAL instance named web1:pdadmin> server list web1-webseald-abc.ibm.com default-webseald-abc.ibm.comIn the protected object spaceEach WebSEAL instance is represented as a member of the /WebSEAL container object in the protected object space. Two WebSEAL instances (default and web1), on the host abc.ibm.com, appear in the protected object space in the following format:/WebSEAL/abc.ibm.com-web1 /WebSEAL/abc.ibm.com-defaultYou can manually specify the host name in the web-host-name stanza entry in the [server] stanza of the WebSEAL configuration file. The value must be the fully qualified name. This manual setting resolves any conflicts in determining the host name that is used, for example, by WebSEAL HTTP/HTTPS responses and authentication mechanisms in a traditional junction environment. By default, web-host-name is not enabled and has no value. When required, WebSEAL attempts to automatically determine the host name.Stop the WebSEAL server process. Manually edit the WebSEAL configuration file to provide a value for the stanza entry.Uncomment the line. Restart WebSEAL.[server] web-host-name = abc.ibm.comNotice the difference in syntax between the server-name and the web-host-name values. For example:[server] server-name = abc.ibm.com-default web-host-name = abc.ibm.comWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Specifying the WebSEAL host name

Typically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.

Before you begin

You must understand the WebSEAL server name in the following situations.

In the configuration file

The name uniquely identifies a WebSEAL server process. You can install and configure multiple WebSEAL servers on one computer system. Therefore, each WebSEAL server process must have a unique name. Each WebSEAL server process is known as an instance.

Each WebSEAL instance has its own configuration file. The server-name stanza entry in the [server] stanza of the configuration file for each WebSEAL instance specifies the unique name for that WebSEAL instance.

The server-name stanza entry is a combination of the host name of the physical computer where WebSEAL is installed and the WebSEAL instance name. Both names are specified during WebSEAL configuration.

[server]
server-name = host_name-instance_name

A computer host name always has a fully qualified name, for example, abc.ibm.com). It also can have a short name, for example, abc. When prompted for the host name during WebSEAL configuration, you can specify either the fully qualified name or the short name. In the following example, the WebSEAL instance name web1 is on a computer with a fully qualified host name of abc.ibm.com, as specified during WebSEAL configuration.

[server]
server-name = abc.ibm.com-web1

The initial WebSEAL server is automatically assigned an instance name of default, unless you modify this name during WebSEAL configuration. For example:

[server]
server-name = abc.ibm.com-default

In the pdadmin server list command

The instance name also affects how the WebSEAL server is listed with the pdadmin server list command. Because the pdadmin command serves the entire Security Access Manager family, a product component name is required in the command syntax. The component name for WebSEAL is webseald. For the pdadmin server list command, the WebSEAL server name has the following format.

instance_name-webseald-host_name

The following example shows the output from pdadmin server list for the instance web1 installed on the host abc.ibm.com:

web1-webseald-abc.ibm.com

The following pdadmin server list command output displays an initial default WebSEAL server and a second WebSEAL instance named web1:

pdadmin> server list
web1-webseald-abc.ibm.com
default-webseald-abc.ibm.com

In the protected object space

Each WebSEAL instance is represented as a member of the /WebSEAL container object in the protected object space. Two WebSEAL instances (default and web1), on the host abc.ibm.com, appear in the protected object space in the following format:

/WebSEAL/abc.ibm.com-web1
/WebSEAL/abc.ibm.com-default

About this task

You can manually specify the host name in the web-host-name stanza entry in the [server] stanza of the WebSEAL configuration file. The value must be the fully qualified name. This manual setting resolves any conflicts in determining the host name that is used, for example, by WebSEAL HTTP/HTTPS responses and authentication mechanisms in a traditional junction environment.

By default, web-host-name is not enabled and has no value. When required, WebSEAL attempts to automatically determine the host name.

Procedure

Stop the WebSEAL server process.

Manually edit the WebSEAL configuration file to provide a value for the stanza entry.

Uncomment the line.

Restart WebSEAL.

Example

[server]
web-host-name = abc.ibm.com

Notice the difference in syntax between the server-name and the web-host-name values. For example:

[server]
server-name = abc.ibm.com-default
web-host-name = abc.ibm.com

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Modifying the configuration file settingsModifying the configuration file settingsModifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.configurationfilesmodifying settingsWebSEALLMIAdvanced Configuration File EditorReverse Proxy Basic ConfigurationFor details on the stanza entries that you can use in the WebSEAL configuration file, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.Configuration file organizationThe configuration file contains sections that control specific portions of WebSEAL. Each section contains further divisions that are called stanzas.Stanza labels appear in brackets.[stanza_name]For example, the [ssl] stanza defines the SSL configuration settings for use by the WebSEAL server. Each stanza in a Security Access Manager configuration file contains one or more stanza entries. A stanza entry consists of a key value pair, which contains information that is expressed as a paired set of stanza entries. Each stanza entry has the following format: key = valueThe initial installation of WebSEAL establishes many of the default values. Some values are static and never change; other values can be modified to customize server function and performance.The ASCII-based text file can be edited with a common text editor. Configuration file name and locationA unique WebSEAL configuration file is created for each WebSEAL instance. The name of the configuration file includes the instance name. webseald-instance_name.confThe administrator can use the local management interface to configure more WebSEAL instances and specify each new instance_name. The configuration utility uses the specified instance_name to name the new WebSEAL configuration file. For example, if you name the new WebSEAL instance webseal2, the following configuration file is created: webseald-webseal2.confFor more information about WebSEAL instance configuration, see WebSEAL instance deploymentThis chapter discusses techniques for deploying one or more instances of WebSEAL..Log in to the local management interface.Select Secure Web SettingsManageReverse Proxy.Select the appropriate WebSEAL instance.Select ManageConfigurationEdit Configuration File. To complete basic configuration file updates, select the WebSEAL instance and click Edit. Make the required changes to the configuration. Save your changes. The local management interface displays a warning message that states about an undeployed change.Click Click here to review the changes or apply them to the system. Review the change and click Deploy.A System Warning displays to indicate that the deployment is complete and a restart is required. Restart the WebSEAL instance from the Reverse Proxy Management page for these changes to take effect.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Modifying the configuration file settings

The operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.

About this task

For details on the stanza entries that you can use in the WebSEAL configuration file, see the Web Reverse Proxy Stanza Reference topics in the IBM® Knowledge Center.

Configuration file organization

The configuration file contains sections that control specific portions of WebSEAL. Each section contains further divisions that are called stanzas.

Stanza labels appear in brackets.

[stanza_name]

For example, the [ssl] stanza defines the SSL configuration settings for use by the WebSEAL server.

Each stanza in a Security Access Manager configuration file contains one or more stanza entries. A stanza entry consists of a key value pair, which contains information that is expressed as a paired set of stanza entries. Each stanza entry has the following format:

key = value

The initial installation of WebSEAL establishes many of the default values. Some values are static and never change; other values can be modified to customize server function and performance.

The ASCII-based text file can be edited with a common text editor.

Configuration file name and location

A unique WebSEAL configuration file is created for each WebSEAL instance. The name of the configuration file includes the instance name.

 webseald-instance_name.conf

The administrator can use the local management interface to configure more WebSEAL instances and specify each new instance_name.

The configuration utility uses the specified instance_name to name the new WebSEAL configuration file. For example, if you name the new WebSEAL instance webseal2, the following configuration file is created:

 webseald-webseal2.conf

For more information about WebSEAL instance configuration, see WebSEAL instance deployment.

Procedure

Log in to the local management interface.

Select Secure Web Settings > Manage > Reverse Proxy.

Select the appropriate WebSEAL instance.

Select Manage > Configuration > Edit Configuration File.

Note: To complete basic configuration file updates, select the WebSEAL instance and click Edit.

Make the required changes to the configuration.

Save your changes. The local management interface displays a warning message that states about an undeployed change.

Click Click here to review the changes or apply them to the system. Review the change and click Deploy. A System Warning displays to indicate that the deployment is complete and a restart is required.

Restart the WebSEAL instance from the Reverse Proxy Management page for these changes to take effect.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Content cachingContent cachingContent cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.content cachingcachecontentdocument cachingcontent cachingKey caching conceptsUsers can often experience extended times for network access and file download due to poor web document retrieval performance. Poor performance can occur because the WebSEAL server is waiting for documents that are retrieved from junctioned back-end servers. Caching web content gives you the flexibility of serving documents locally from WebSEAL rather than from a back-end server across a junction. With the content caching feature, you can store commonly accessed web document types in the WebSEAL server memory. Clients can experience much faster response to follow up requests for documents that were cached in the WebSEAL server. Cached content can include static text documents and graphic images. Dynamically generated documents, such as database query results, cannot be cached. Caching is based on MIME type. When you configure WebSEAL for content caching, identify the following settings: Document MIME type Type of storage medium Size of storage medium Maximum age if expiry information is missing from the original responseConfiguration of content cachingYou configure content caching in the [content-cache] stanza of the WebSEAL configuration file. The following syntax applies:<mime-type> = <cache-type>:<cache-size>VariableDescriptionmime-typeRepresents any valid MIME type conveyed in an HTTP Content-Type: response header. This value can contain an asterisk (*). A value of */* represents a default object cache that holds any object that does not correspond to an explicitly configured cache. The asterisk is a wildcard only for a MIME-type directory and its contents. The asterisk is not a wildcard for regular expression matching.cache-typeSpecifies the type of storage medium to use for the cache. This release of Security Access Manager supports only "memory" caches.cache-sizeSpecifies the maximum size in KB that the specified cache can grow before objects are removed according to a Least Recently Used algorithm.def-max-ageSpecifies the maximum age (in seconds) if expiry information is missing from the original response. If no value is provided, a default maximum age of 3600 (1 hour) is applied.Conditions affecting content caching configurationThe content caching mechanism observes the following conditions:Content caching occurs only when a cache is defined in the WebSEAL configuration file. By default, no content caches are defined at installation. If you do not specify a default content cache, documents that do not match any explicit cache are not cached. Authorization is still performed on all requests for cached information. The content caching mechanism does not cache responses to requests that contain query strings. The content caching mechanism does not cache responses to requests over junctions that are configured with the –c and –C options.Impact of HTTP headers on WebSEAL content cachingThe following table describes how specificHTTP Request headers from the client affect whether WebSEAL uses the cache to produce the requested resource or send the request to the destination server.HTTP Response headers from the junction affect whether WebSEAL allows caching of the resource,WebSEAL does not process <meta> tags with http-equiv attributes for Response headers.Response HeaderImpact of HTTP Response headers in the requestImpact of HTTP Request Headers in the requestAccept-encodingNot applicableAllows the response to come from the cache if the value matches the cached encoding type.AgeCalculates whether data in the cache is fresh enough to use.Not applicableAuthorizationNot applicableIf the DocumentCacheControl=public POP value is not set, stops the response from the cache unless the junction has the -b filter set. See Cache control for specific documents.AgeCalculates whether data in the cache is fresh enough to use.Not applicableCache-controlThe no-cache, no-store, or private values stop the resource from being stored in the content cache.The public value stores the resource in the content cache even if user-identifying data is passed to the junction.The no-cache stops the response from the cache.The no-store value stops the response from the cache and being stored in the cache.The max-age, max-stale, or min-fresh values determine whether the cache is used for the response.Content-rangeStops the resource from being stored in the content cache.Not applicableDateIf the value of Date is greater than the value of Expires, the resource is not stored in the cache, which complies with HTTP/1.0 specification. Calculates whether data in the cache is fresh enough to use.Not applicableExpiresStores the resource in the content cache even if user-identifying data is passed to the junction.Calculates whether data in the cache is fresh enough to use.Not applicableLast dateCalculates whether data in the cache is fresh enough to use.Not applicablePragmaThe non-cache value stops the resource from being stored in the content cache.The non-cache value stops the response from the cache.RangeNot applicableStops the response from the cache and the response from being stored in the cache.Transfer-encodingWebSEAL strips the TE: header from the request sent to the junction, so it does not expect a Transfer-Encoding: header to be sent back. However, if a Transfer-Encoding: header is sent back, WebSEAL stops the resource from being stored in the content cache.Not applicableVaryStops the resource from being stored in the content cache.Not applicableImpact of other conditions on WebSEAL content cachingOther conditions affect WebSEAL content caching.WebSEAL does not cache content if the response from the junction does not have the status 200 OK. WebSEAL does not cache content if the request URL contains a query string. WebSEAL flushes a cache entry if a PUT, POST, or DELETEis used in the URL. WebSEAL returns only values from the cache for HEAD and GET requests. WebSEAL does not cache the response from junctions toHEAD requests. WebSEAL does not cache the response if the junction has -b gso, -b supply, C, or -cset, unless one of the following conditions exists: There is a POP on the object with value DocumentCacheControl=public. See Cache control for specific documents. The response has an Expires: header. The response has Cache-Control: public set. WebSEAL does not cache the response if there is a POP on the object with the value DocumentCacheControl=no-cache. See Cache control for specific documents. You cannot override the calculations that are based on date headers (Date, Age, Last-modified, Expires, and the related Cache-control header values. You cannot override all other headers.Flushing all cachesYou can use the pdadmin utility to flush all configured content caches. You cannot flush individual caches with pdadmin.You must log in to the secure domain as the Security Access Manager administrator sec_master before you can use pdadmin.To flush all content caches, use the following pdadmin command:pdadmin> server task instance_name-webseald-host_name cache flush allCache control for specific documentsYou can control caching for specific documents by attaching a special protected object policy (POP) to those objects. This POP must contain an extended attribute called document-cache-control.The document-cache-control extended attribute recognizes the following two values:ValueDescriptionno-cacheThe no-cache value instructs WebSEAL not to cache this document. All children of the object with the POP also inherit the POP conditions. publicThe public value allows WebSEAL to cache the document by ignoring the fact that the junction was created with a –c or –C option. In addition, this value also allows caching of this document when the request is sent with an authorization header (such as Basic Authentication). This condition also includes a request where WebSEAL inserts BA information on behalf of the client (such as with GSO or –b supply junctions). Normally, proxy servers do not cache the response documents to requests that include authorization headers.Use the pdadmin pop create, pdadmin pop modify, and pdadmin pop attach commands to set a POP on a protected object. The following example illustrates creating a POP called "doc-cache" (with the document-cache-control extended attribute) and attaching it to an object (budget.html):pdadmin> pop create doc-cache pdadmin> pop modify doc-cache set attribute document-cache-control no-cache pdadmin> pop attach /WebSEAL/hostA/junction/budget.html doc-cacheThe budget.html document is never cached by WebSEAL. Each request for this document must be made directly to the back-end server where it is located.Details about the pdadmin command-line utility can be found in the Command Reference topics in the IBM Knowledge Center.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Content caching

WebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.

Key caching concepts

Users can often experience extended times for network access and file download due to poor web document retrieval performance. Poor performance can occur because the WebSEAL server is waiting for documents that are retrieved from junctioned back-end servers.

Caching web content gives you the flexibility of serving documents locally from WebSEAL rather than from a back-end server across a junction. With the content caching feature, you can store commonly accessed web document types in the WebSEAL server memory. Clients can experience much faster response to follow up requests for documents that were cached in the WebSEAL server.

Cached content can include static text documents and graphic images. Dynamically generated documents, such as database query results, cannot be cached.

Caching is based on MIME type. When you configure WebSEAL for content caching, identify the following settings:

Document MIME type

Type of storage medium

Size of storage medium

Maximum age if expiry information is missing from the original response

Configuration of content caching

You configure content caching in the [content-cache] stanza of the WebSEAL configuration file. The following syntax applies:

<mime-type> = <cache-type>:<cache-size>

Variable
Description

mime-type
Represents any valid MIME type conveyed in an HTTP Content-Type: response header. This value can contain an asterisk (*). A value of */* represents a default object cache that holds any object that does not correspond to an explicitly configured cache.

Note: The asterisk is a wildcard only for a MIME-type directory and its contents. The asterisk is not a wildcard for regular expression matching.

cache-type
Specifies the type of storage medium to use for the cache. This release of Security Access Manager supports only "memory" caches.

cache-size
Specifies the maximum size in KB that the specified cache can grow before objects are removed according to a Least Recently Used algorithm.

def-max-age
Specifies the maximum age (in seconds) if expiry information is missing from the original response. If no value is provided, a default maximum age of 3600 (1 hour) is applied.

Conditions affecting content caching configuration

The content caching mechanism observes the following conditions:

Content caching occurs only when a cache is defined in the WebSEAL configuration file.

By default, no content caches are defined at installation.

If you do not specify a default content cache, documents that do not match any explicit cache are not cached.

Authorization is still performed on all requests for cached information.

The content caching mechanism does not cache responses to requests that contain query strings.

The content caching mechanism does not cache responses to requests over junctions that are configured with the –c and –C options.

Impact of HTTP headers on WebSEAL content caching

The following table describes how specific

HTTP Request headers from the client affect whether WebSEAL uses the cache to produce the requested resource or send the request to the destination server.

HTTP Response headers from the junction affect whether WebSEAL allows caching of the resource,

Note: WebSEAL does not process <meta> tags with http-equiv attributes for Response headers.

Response Header
Impact of HTTP Response headers in the request
Impact of HTTP Request Headers in the request

Accept-encoding
Not applicable
Allows the response to come from the cache if the value matches the cached encoding type.

Age
Calculates whether data in the cache is fresh enough to use.
Not applicable

Authorization
Not applicable
If the DocumentCacheControl=public POP value is not set, stops the response from the cache unless the junction has the -b filter set. See Cache control for specific documents.

Age
Calculates whether data in the cache is fresh enough to use.
Not applicable

Cache-control

The no-cache, no-store, or private values stop the resource from being stored in the content cache.

The public value stores the resource in the content cache even if user-identifying data is passed to the junction.

The no-cache stops the response from the cache.

The no-store value stops the response from the cache and being stored in the cache.

The max-age, max-stale, or min-fresh values determine whether the cache is used for the response.

Content-range
Stops the resource from being stored in the content cache.
Not applicable

Date

Note: If the value of Date is greater than the value of Expires, the resource is not stored in the cache, which complies with HTTP/1.0 specification.

Calculates whether data in the cache is fresh enough to use.
Not applicable

Expires

Stores the resource in the content cache even if user-identifying data is passed to the junction.

Calculates whether data in the cache is fresh enough to use.

Not applicable

Last date
Calculates whether data in the cache is fresh enough to use.
Not applicable

Pragma
The non-cache value stops the resource from being stored in the content cache.
The non-cache value stops the response from the cache.

Range
Not applicable
Stops the response from the cache and the response from being stored in the cache.

Transfer-encoding
WebSEAL strips the TE: header from the request sent to the junction, so it does not expect a Transfer-Encoding: header to be sent back. However, if a Transfer-Encoding: header is sent back, WebSEAL stops the resource from being stored in the content cache.
Not applicable

Vary
Stops the resource from being stored in the content cache.
Not applicable

Impact of other conditions on WebSEAL content caching

Other conditions affect WebSEAL content caching.

WebSEAL does not cache content if the response from the junction does not have the status 200 OK.

WebSEAL does not cache content if the request URL contains a query string.

WebSEAL flushes a cache entry if a PUT, POST, or DELETEis used in the URL.

WebSEAL returns only values from the cache for HEAD and GET requests.

WebSEAL does not cache the response from junctions toHEAD requests.

WebSEAL does not cache the response if the junction has -b gso, -b supply, C, or -cset, unless one of the following conditions exists:

There is a POP on the object with value DocumentCacheControl=public. See Cache control for specific documents.

The response has an Expires: header.

The response has Cache-Control: public set.

WebSEAL does not cache the response if there is a POP on the object with the value DocumentCacheControl=no-cache. See Cache control for specific documents.

You cannot override the calculations that are based on date headers (Date, Age, Last-modified, Expires, and the related Cache-control header values.

You cannot override all other headers.

Flushing all caches

You can use the pdadmin utility to flush all configured content caches. You cannot flush individual caches with pdadmin.

Note: You must log in to the secure domain as the Security Access Manager administrator sec_master before you can use pdadmin.

To flush all content caches, use the following pdadmin command:

pdadmin> server task instance_name-webseald-host_name cache flush all

Cache control for specific documents

You can control caching for specific documents by attaching a special protected object policy (POP) to those objects. This POP must contain an extended attribute called document-cache-control.

The document-cache-control extended attribute recognizes the following two values:

Value
Description

no-cache
The no-cache value instructs WebSEAL not to cache this document. All children of the object with the POP also inherit the POP conditions.

public
The public value allows WebSEAL to cache the document by ignoring the fact that the junction was created with a –c or –C option. In addition, this value also allows caching of this document when the request is sent with an authorization header (such as Basic Authentication). This condition also includes a request where WebSEAL inserts BA information on behalf of the client (such as with GSO or –b supply junctions). Normally, proxy servers do not cache the response documents to requests that include authorization headers.

Use the pdadmin pop create, pdadmin pop modify, and pdadmin pop attach commands to set a POP on a protected object.

The following example illustrates creating a POP called "doc-cache" (with the document-cache-control extended attribute) and attaching it to an object (budget.html):

pdadmin> pop create doc-cache
pdadmin> pop modify doc-cache set attribute document-cache-control no-cache
pdadmin> pop attach /WebSEAL/hostA/junction/budget.html doc-cache

The budget.html document is never cached by WebSEAL. Each request for this document must be made directly to the back-end server where it is located.

Details about the pdadmin command-line utility can be found in the Command Reference topics in the IBM® Knowledge Center.

Parent topic: Web server configuration

Related concepts:

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Communication protocol configurationCommunication protocol configurationCommunication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.communicationprotocol configurationstanza entriesWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.Configuring WebSEAL HTTP requestsConfigure the WebSEAL HTTP requests so that you can define how WebSEAL handles HTTP requests from unauthenticated users.Configuring WebSEAL HTTPS requestsConfigure WebSEAL HTTPS requests to determine how WebSEAL handles HTTPS requests from unauthenticated users.Restrictions on connections from specific SSL versionsThe stanza entries that control connections for specific SSL and TLS versions are in the [ssl] stanza of the WebSEAL configuration file. By default SSL version 2 is disabled. All other SSL and TLS versions are enabled by default.Persistent HTTP connectionsAt the HTTP communication layer, WebSEAL maintains persistent connections between the client browser and WebSEAL, and between junctioned web servers and WebSEAL. WebSEAL configuration for handling HTTPOnly cookiesTo help reduce the risk of cross-site scripting, an HTTPOnly attribute was added to cookies, preventing them from being accessed through client-side scripts.Configuring WebSEAL connection timeout settingsEdit the WebSEAL configuration file so that you can configure the timeout settings for HTTP and HTTPS communication. WebSEAL server timeout settingsThe WebSEAL server timeout settings are set in the WebSEAL configuration file.WebDAV supportWeb-based Distributed Authoring and Versioning (WebDAV) is a set of extensions to the HTTP protocol that users can use to edit and manage files on remote web servers.Microsoft RPC over HTTP supportMicrosoft Remote Procedure Call over HTTP is a protocol that is used to communicate RPC traffic over an HTTP connection. Microsoft Outlook clients use this protocol to access Microsoft Exchange servers over HTTP. Chunked transfer coding supportWebSEAL supports chunked transfer coding as defined by the HTTP/1.1 specification.

Communication protocol configuration

You can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Configuring WebSEAL HTTP requests
Configure the WebSEAL HTTP requests so that you can define how WebSEAL handles HTTP requests from unauthenticated users.

Configuring WebSEAL HTTPS requests
Configure WebSEAL HTTPS requests to determine how WebSEAL handles HTTPS requests from unauthenticated users.

Restrictions on connections from specific SSL versions
The stanza entries that control connections for specific SSL and TLS versions are in the [ssl] stanza of the WebSEAL configuration file. By default SSL version 2 is disabled. All other SSL and TLS versions are enabled by default.

Persistent HTTP connections
At the HTTP communication layer, WebSEAL maintains persistent connections between the client browser and WebSEAL, and between junctioned web servers and WebSEAL.

WebSEAL configuration for handling HTTPOnly cookies
To help reduce the risk of cross-site scripting, an HTTPOnly attribute was added to cookies, preventing them from being accessed through client-side scripts.

Configuring WebSEAL connection timeout settings
Edit the WebSEAL configuration file so that you can configure the timeout settings for HTTP and HTTPS communication.

WebSEAL server timeout settings
The WebSEAL server timeout settings are set in the WebSEAL configuration file.

WebDAV support
Web-based Distributed Authoring and Versioning (WebDAV) is a set of extensions to the HTTP protocol that users can use to edit and manage files on remote web servers.

Microsoft RPC over HTTP support
Microsoft Remote Procedure Call over HTTP is a protocol that is used to communicate RPC traffic over an HTTP connection. Microsoft Outlook clients use this protocol to access Microsoft Exchange servers over HTTP.

Chunked transfer coding support
WebSEAL supports chunked transfer coding as defined by the HTTP/1.1 specification.

Parent topic: Web server configuration

Related concepts:

Content caching

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Configuring WebSEAL HTTP requestsConfiguring WebSEAL HTTP requestsConfiguring WebSEAL HTTP requestsConfigure the WebSEAL HTTP requests so that you can define how WebSEAL handles HTTP requests from unauthenticated users.http stanza entryWebSEALHTTP requestsIt is typical to allow anonymous users read-only access to selected documents on the public section of your website. Enable or disable access to selected documents by editing the stanza entries for handling HTTP requests over TCP in the [server] stanza of the WebSEAL configuration file.Log in to the local management interface.Select Secure Web SettingsManageReverse Proxy.Select your instance.Select ManageConfigurationEdit Configuration File.Add the following line under the [server] stanza.[server] http = {yes|no}Set the HTTPS access port value by adding the following line under the [server] stanza.IBM HTTP Server, WebSphere Application Server, and WebSEAL all use port 80 as the default port.[server] http-port = 80Save and deploy your changes.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Configuring WebSEAL HTTP requests

Configure the WebSEAL HTTP requests so that you can define how WebSEAL handles HTTP requests from unauthenticated users.

About this task

It is typical to allow anonymous users read-only access to selected documents on the public section of your website. Enable or disable access to selected documents by editing the stanza entries for handling HTTP requests over TCP in the [server] stanza of the WebSEAL configuration file.

Procedure

Log in to the local management interface.

Select Secure Web Settings > Manage > Reverse Proxy.

Select your instance.

Select Manage > Configuration > Edit Configuration File.

Add the following line under the [server] stanza.

[server]
http = {yes|no}

Set the HTTPS access port value by adding the following line under the [server] stanza. IBM® HTTP Server, WebSphere® Application Server, and WebSEAL all use port 80 as the default port.

[server]
http-port = 80

Save and deploy your changes.

Parent topic: Communication protocol configuration

Configuring WebSEAL HTTPS requestsConfiguring WebSEAL HTTPS requestsConfiguring WebSEAL HTTPS requestsConfigure WebSEAL HTTPS requests to determine how WebSEAL handles HTTPS requests from unauthenticated users.HTTPSrequestsstanza entryLog in to the local management interface.Select Secure Web SettingsManageReverse Proxy.Select your instance.Select ManageConfigurationEdit Configuration File.Enable or disable HTTPS access by adding the following line under the [server] stanza.[server] https = {yes|no}Set the HTTPS access port value by adding the following line under the [server] stanza.The default port for HTTPS access is 443: [server] https-port = 443 To change to port 4343, for example, set: [server] https-port = 4343Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Configuring WebSEAL HTTPS requests

Configure WebSEAL HTTPS requests to determine how WebSEAL handles HTTPS requests from unauthenticated users.

Procedure

Log in to the local management interface.

Select Secure Web Settings > Manage > Reverse Proxy.

Select your instance.

Select Manage > Configuration > Edit Configuration File.

Enable or disable HTTPS access by adding the following line under the [server] stanza.

[server]
https = {yes|no}

Set the HTTPS access port value by adding the following line under the [server] stanza.

The default port for HTTPS access is 443:

[server]
https-port = 443

To change to port 4343, for example, set:

[server]
https-port = 4343

Parent topic: Communication protocol configuration

Restrictions on connections from specific SSL versionsRestrictions on connections from specific SSL versions Restrictions on connections from specific SSL versions The stanza entries that control connections for specific SSL and TLS versions are in the [ssl] stanza of the WebSEAL configuration file. By default SSL version 2 is disabled. All other SSL and TLS versions are enabled by default.disable-ssl-v2 stanza entryssl stanzadisable-ssl-v3 stanza entryssl stanzadisable-tls-v1 stanza entryssl stanzadisable-tls-v11 stanza entryssl stanzadisable-tls-v12 stanza entryssl stanzaSSL connectivityTLS connectivityTransport Layer Security (TLS)You can independently enable and disable connectivity for the following communication protocol versions: Secure Sockets Layer (SSL) version 2SSL version 3Transport Layer Security (TLS) version 1TLS version 1.1TLS version 1.2 [ssl] disable-ssl-v2 = {yes|no} disable-ssl-v3 = {yes|no} disable-tls-v1 = {yes|no} disable-tls-v11 = {yes|no} disable-tls-v12 = {yes|no}Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Restrictions on connections from specific SSL versions

The stanza entries that control connections for specific SSL and TLS versions are in the [ssl] stanza of the WebSEAL configuration file. By default SSL version 2 is disabled. All other SSL and TLS versions are enabled by default.

You can independently enable and disable connectivity for the following communication protocol versions:

Secure Sockets Layer (SSL) version 2

SSL version 3

Transport Layer Security (TLS) version 1

TLS version 1.1

TLS version 1.2

[ssl]
disable-ssl-v2 = {yes|no}
disable-ssl-v3 = {yes|no}
disable-tls-v1 = {yes|no}
disable-tls-v11 = {yes|no}
disable-tls-v12 = {yes|no}

Parent topic: Communication protocol configuration

Persistent HTTP connectionsPersistent HTTP connectionsPersistent HTTP connectionsAt the HTTP communication layer, WebSEAL maintains persistent connections between the client browser and WebSEAL, and between junctioned web servers and WebSEAL. HTTPpersistent connectionspersistent connectionsClient connections are controlled by the following entries in the [server] stanza of the WebSEAL configuration file: max-idle-persistent-connectionsThis entry controls the maximum number of idle client persistent connections. persistent-con-timeoutThis entry controls the maximum number of seconds that WebSEAL holds an HTTP persistent connection open for a new request before the connection is shut down. disable-timeout-reductionThis entry determines whether WebSEAL reduces the timeout duration to help control the number of active worker threads. By default, WebSEAL automatically reduces the timeout duration for threads as the number of in-use worker threads increases. Junction connections are controlled by the following entries in the [junction] stanza of the WebSEAL configuration file: max-cached-persistent-connectionsThis entry controls the maximum number of persistent connections that will be stored in the cache for future use. persistent-con-timeoutThis entry controls the maximum number of seconds a persistent connection can remain idle in the cache before WebSEAL closes the connection. WebSEAL supports HTTP/1.1 persistent connections. HTTP/1.0 persistent connections are not supported.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Persistent HTTP connections

At the HTTP communication layer, WebSEAL maintains persistent connections between the client browser and WebSEAL, and between junctioned web servers and WebSEAL.

Client connections are controlled by the following entries in the [server] stanza of the WebSEAL configuration file:

max-idle-persistent-connections

This entry controls the maximum number of idle client persistent connections.

persistent-con-timeout

This entry controls the maximum number of seconds that WebSEAL holds an HTTP persistent connection open for a new request before the connection is shut down.

disable-timeout-reduction

This entry determines whether WebSEAL reduces the timeout duration to help control the number of active worker threads. By default, WebSEAL automatically reduces the timeout duration for threads as the number of in-use worker threads increases.

Junction connections are controlled by the following entries in the [junction] stanza of the WebSEAL configuration file:

max-cached-persistent-connections

This entry controls the maximum number of persistent connections that will be stored in the cache for future use.

persistent-con-timeout

This entry controls the maximum number of seconds a persistent connection can remain idle in the cache before WebSEAL closes the connection.

Note: WebSEAL supports HTTP/1.1 persistent connections. HTTP/1.0 persistent connections are not supported.

Parent topic: Communication protocol configuration

WebSEAL configuration for handling HTTPOnly cookiesWebSEAL configuration for handling HTTPOnly cookiesWebSEAL configuration for handling HTTPOnly cookiesTo help reduce the risk of cross-site scripting, an HTTPOnly attribute was added to cookies, preventing them from being accessed through client-side scripts.HTTPOnly cookiesHTTPHTTPOnly cookiesCross-site scripting is among the most common security problems for web servers and can expose sensitive information about the users of a website. WebSEAL includes the option to enable WebSEAL to add the HTTPOnly attribute to the Set-Cookie headers it uses for sessions, failover, and LTPA cookies. WebSEAL can also be configured to pass the HTTP-only Set-Cookie header attribute from back-end junction servers to web browsers.To configure WebSEAL to add the HTTPOnly attribute to Session, Failover and LTPA Set-Cookie headers, change the value of use-http-only-cookies in the [server] stanza of the WebSEAL configuration file to yes. The default value is no. [server] use-http-only-cookies = yesTo configure WebSEAL to pass the HTTPOnly attribute from Set-Cookie headers sent by junctioned servers, change the value of pass-http-only-cookie-attr in the [junction] stanza of the WebSEAL configuration file to yes. The default value is no. [junction] pass-http-only-cookie-attr = yesFor more information about these entries, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center. Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

WebSEAL configuration for handling HTTPOnly cookies

To help reduce the risk of cross-site scripting, an HTTPOnly attribute was added to cookies, preventing them from being accessed through client-side scripts.

Cross-site scripting is among the most common security problems for web servers and can expose sensitive information about the users of a website. WebSEAL includes the option to enable WebSEAL to add the HTTPOnly attribute to the Set-Cookie headers it uses for sessions, failover, and LTPA cookies. WebSEAL can also be configured to pass the HTTP-only Set-Cookie header attribute from back-end junction servers to web browsers.

To configure WebSEAL to add the HTTPOnly attribute to Session, Failover and LTPA Set-Cookie headers, change the value of use-http-only-cookies in the [server] stanza of the WebSEAL configuration file to yes. The default value is no.

[server]
use-http-only-cookies = yes

To configure WebSEAL to pass the HTTPOnly attribute from Set-Cookie headers sent by junctioned servers, change the value of pass-http-only-cookie-attr in the [junction] stanza of the WebSEAL configuration file to yes. The default value is no.

[junction]
pass-http-only-cookie-attr = yes

For more information about these entries, see the Web Reverse Proxy Stanza Reference topics in the IBM® Knowledge Center.

Parent topic: Communication protocol configuration

Configuring WebSEAL connection timeout settingsConfiguring WebSEAL connection timeout settingsConfiguring WebSEAL connection timeout settingsEdit the WebSEAL configuration file so that you can configure the timeout settings for HTTP and HTTPS communication. timeout settingsHTTP and HTTPStimeout settingsHTTPHTTPSclient-connect-timeout stanza entrytimeout settingsclient-connect-timeoutintra-connection-timeout stanza entrytimeout settingsintra-connection-timeoutpersistent-con-timeout stanza entrytimeout settingspersistent-con-timeoutThe following flow diagram shows where the timeout settings affect an example request and response exchange. The number of fragments that are indicated for the request and the response are for sample purposes only.Timeout settings for HTTP and HTTPS communicationTimeout settings for HTTP and HTTPS communicationThe stanza entries for timeout settings are in the server stanza of the WebSEAL configuration file.client-connect-timeoutSpecifies how long WebSEAL holds the connection open for the initial HTTP or HTTPS request after the initial connection handshake. The default value is 120 seconds. [server] client-connect-timeout = 120intra-connection-timeoutSpecifies the number of seconds, between each request data fragment when request and response data is sent as two or more fragments.The stanza entry also governs the timeout between response data fragments after the first data fragment is returned by WebSEAL. The default value is 60 seconds.[server] intra-connection-timeout = 60If the value of this stanza entry is 0, connection timeouts between data fragments are governed by the client-connect-timeout stanza entry. The exception to this rule occurs for responses that are returned over HTTP or TCP. In this case, there is no timeout between response fragments.If a connection timeout occurs on a non-first data fragment due to the intra-connection-timeout setting, a TCP reset packet is sent.persistent-con-timeoutControls the maximum number of seconds that WebSEAL holds an HTTP persistent connection open for a new client request before the connection is shut down. The HTTP persistent connection opens after the HTTP request and server response exchange is complete. The default value is 5 seconds. [server] persistent-con-timeout = 5If the value of this stanza entry is 0, the connection does not remain open for future requests. A value of zero causes WebSEAL to set the Connection: close header and then close the connection on every response.The timeout setting on the junction side is set by the persistent-con-timeout entry in the [junction] stanza.Log in to the local management interface.From the top menu, select Secure Web SettingsManageReverse Proxy.Select your instance.Select ManageConfigurationEdit Configuration File. Edit the stanza by using the information in About this task.Save and deploy your changes.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Configuring WebSEAL connection timeout settings

Edit the WebSEAL configuration file so that you can configure the timeout settings for HTTP and HTTPS communication.

About this task

The following flow diagram shows where the timeout settings affect an example request and response exchange. The number of fragments that are indicated for the request and the response are for sample purposes only.

Figure 12. Timeout settings for HTTP and HTTPS communication

The stanza entries for timeout settings are in the server stanza of the WebSEAL configuration file.

client-connect-timeout

Specifies how long WebSEAL holds the connection open for the initial HTTP or HTTPS request after the initial connection handshake. The default value is 120 seconds.

[server]
client-connect-timeout = 120

intra-connection-timeout

Specifies the number of seconds, between each request data fragment when request and response data is sent as two or more fragments.

The stanza entry also governs the timeout between response data fragments after the first data fragment is returned by WebSEAL. The default value is 60 seconds.

[server]
intra-connection-timeout = 60

If the value of this stanza entry is 0, connection timeouts between data fragments are governed by the client-connect-timeout stanza entry. The exception to this rule occurs for responses that are returned over HTTP or TCP. In this case, there is no timeout between response fragments.

If a connection timeout occurs on a non-first data fragment due to the intra-connection-timeout setting, a TCP reset packet is sent.

persistent-con-timeout

Controls the maximum number of seconds that WebSEAL holds an HTTP persistent connection open for a new client request before the connection is shut down.

The HTTP persistent connection opens after the HTTP request and server response exchange is complete. The default value is 5 seconds.

[server]
persistent-con-timeout = 5

If the value of this stanza entry is 0, the connection does not remain open for future requests. A value of zero causes WebSEAL to set the Connection: close header and then close the connection on every response.

Note: The timeout setting on the junction side is set by the persistent-con-timeout entry in the [junction] stanza.

Procedure

Log in to the local management interface.

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select your instance.

Select Manage > Configuration > Edit Configuration File.

Edit the stanza by using the information in About this task.

Save and deploy your changes.

Parent topic: Communication protocol configuration

WebSEAL server timeout settingsWebSEAL server timeout settingsWebSEAL server timeout settingsThe WebSEAL server timeout settings are set in the WebSEAL configuration file.timeoutsettingspint-time (junctions)cg-timeouthttps-timeouthttp-timeout (junctions)ping-time (junctions)cgi-timeout stanza entryhttps-timeout stanza entry (junctions)http-timeout stanza entry (junctions)Stanza EntryDescription Default Value [junction] http-timeout The timeout value for sending to and reading from a back-end server over a TCP junction.120 [junction] https-timeout The timeout value for sending to and reading from a back-end server over an SSL junction.120 [junction] ping-time WebSEAL performs a periodic background ping of each junctioned server to determine whether it is running. This value sets the time interval between these pings. To turn off the ping, set this entry to zero. If this entry is set to zero, the recovery-ping-time must be set.300 [junction] recovery-ping-time This optional entry sets the interval, in seconds, between pings when the server is determined not to be running. If this entry is not set, the value defaults to the ping-time setting.300Optionally, you can also customize the http-timeout and https-timeout settings for any particular WebSEAL junction by manually creating a junction-specific stanza for example, [junction:/WebApp] in the WebSEAL configuration file. The stanza can be customized for a particular junction by adding the adjusted configuration items to a [junction:junction_name] stanza, where junction_name refers to the junction point for a standard junction (including the leading '/'), or the virtual host label for a virtual host junction. If specified, the following settings override the default settings that are indicated in the previous table.Stanza EntryDescription Default Value (seconds) [junction:junction_name] http-timeout The timeout value for sending to and reading from a back-end server over a specific TCP junction. 120 [junction:junction_name] https-timeout The timeout value for sending to and reading from a back-end server over a specific SSL junction.120Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

WebSEAL server timeout settings

The WebSEAL server timeout settings are set in the WebSEAL configuration file.

Stanza Entry
Description

Default Value

[junction]
http-timeout

The timeout value for sending to and reading from a back-end server over a TCP junction.

120

[junction]
https-timeout

The timeout value for sending to and reading from a back-end server over an SSL junction.

120

[junction]
ping-time

WebSEAL performs a periodic background ping of each junctioned server to determine whether it is running. This value sets the time interval between these pings.

To turn off the ping, set this entry to zero. If this entry is set to zero, the recovery-ping-time must be set.

300

[junction]
recovery-ping-time

This optional entry sets the interval, in seconds, between pings when the server is determined not to be running. If this entry is not set, the value defaults to the ping-time setting.

300

Optionally, you can also customize the http-timeout and https-timeout settings for any particular WebSEAL junction by manually creating a junction-specific stanza for example, [junction:/WebApp] in the WebSEAL configuration file.

The stanza can be customized for a particular junction by adding the adjusted configuration items to a [junction:junction_name] stanza, where junction_name refers to the junction point for a standard junction (including the leading '/'), or the virtual host label for a virtual host junction. If specified, the following settings override the default settings that are indicated in the previous table.

Stanza Entry
Description

Default Value

(seconds)

[junction:junction_name]
http-timeout

The timeout value for sending to and reading from a back-end server over a specific TCP junction.

120

[junction:junction_name]
https-timeout

The timeout value for sending to and reading from a back-end server over a specific SSL junction.

120

Parent topic: Communication protocol configuration

WebDAV supportWebDAV supportWebDAV supportWeb-based Distributed Authoring and Versioning (WebDAV) is a set of extensions to the HTTP protocol that users can use to edit and manage files on remote web servers.WebDAVWeb-based Distributed Authoring and VersioningWebSEAL supports the use of WebDAV methods in client requests for junctioned applications. WebSEAL does not support WebDAV methods when it acts as a web server that serves local content. Authorization for all WebDAV methods is controlled through the r ACL bit.WebSEAL forwards requests to junctioned applications by using the following WebDAV methods: ACL BASELINE-CONTROL BCOPY BDELETE BIND BMOVE BPROPPATCH CHECKIN CHECKOUT COPY LABEL LINK LOCK MERGE MKACTIVITY MKCOL MKREDIRECTREF MKWORKSPACE MOVE NOTIFY ORDERPATCH PATCH POLL PROPFIND PROPPATCH REBIND REPORT SEARCH SUBSCRIBE SUBSCRIPTIONS UNBIND UNCHECKOUT UNLINK UNLOCK UNSUBSCRIBE UPDATE UPDATEDIRECTREF VERSIONCONTROLCommunication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

WebDAV support

Web-based Distributed Authoring and Versioning (WebDAV) is a set of extensions to the HTTP protocol that users can use to edit and manage files on remote web servers.

WebSEAL supports the use of WebDAV methods in client requests for junctioned applications. WebSEAL does not support WebDAV methods when it acts as a web server that serves local content. Authorization for all WebDAV methods is controlled through the r ACL bit.

WebSEAL forwards requests to junctioned applications by using the following WebDAV methods:

ACL

BASELINE-CONTROL

BCOPY

BDELETE

BIND

BMOVE

BPROPPATCH

CHECKIN

CHECKOUT

COPY

LABEL

LINK

LOCK

MERGE

MKACTIVITY

MKCOL

MKREDIRECTREF

MKWORKSPACE

MOVE

NOTIFY

ORDERPATCH

PATCH

POLL

PROPFIND

PROPPATCH

REBIND

REPORT

SEARCH

SUBSCRIBE

SUBSCRIPTIONS

UNBIND

UNCHECKOUT

UNLINK

UNLOCK

UNSUBSCRIBE

UPDATE

UPDATEDIRECTREF

VERSIONCONTROL

Parent topic: Communication protocol configuration

Microsoft RPC over HTTP supportMicrosoft RPC over HTTP supportMicrosoft RPC over HTTP supportMicrosoft Remote Procedure Call over HTTP is a protocol that is used to communicate RPC traffic over an HTTP connection. Microsoft Outlook clients use this protocol to access Microsoft Exchange servers over HTTP. Microsoft OfficeRPC over HTTPRemote Procedure CallRPCWebSEAL does not natively support Microsoft RPC over HTTP operations. WebSEAL does support the forwarding of RPC over HTTP version 2 methods to junctioned applications. Authorization for all RPC over HTTP methods is controlled through the r ACL bit.WebSEAL forwards requests to junctioned applications by using the following RPC over HTTP methods:RPC_IN_DATARPC_OUT_DATACommunication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Microsoft RPC over HTTP support

Microsoft Remote Procedure Call over HTTP is a protocol that is used to communicate RPC traffic over an HTTP connection. Microsoft Outlook clients use this protocol to access Microsoft Exchange servers over HTTP.

WebSEAL does not natively support Microsoft RPC over HTTP operations. WebSEAL does support the forwarding of RPC over HTTP version 2 methods to junctioned applications. Authorization for all RPC over HTTP methods is controlled through the r ACL bit.

WebSEAL forwards requests to junctioned applications by using the following RPC over HTTP methods:

RPC_IN_DATA

RPC_OUT_DATA

Parent topic: Communication protocol configuration

Chunked transfer coding supportChunked transfer coding supportChunked transfer coding supportWebSEAL supports chunked transfer coding as defined by the HTTP/1.1 specification. chunked transfer codingsupportHTTP/1.1 specification Chunks from the client are transmitted as they are received to junctioned web servers.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.

Chunked transfer coding support

WebSEAL supports chunked transfer coding as defined by the HTTP/1.1 specification.

Chunks from the client are transmitted as they are received to junctioned web servers.

Parent topic: Communication protocol configuration

IPv4 and IPv6 overviewIPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).IPv4overviewIPv6overview IPv6 improves upon IPv4 in the following ways:IPv6 allocates 128 bits for the address space; IPv4 only allocates 32 bits for the address space.IPv6 can decrease the size of static, non-default routing tables, used to route packets through the Internet backbone.IPv6 provides end-to-end security by requiring adherence to the IP Security protocols (IPSec).The primary format of an IPv4 address is a 32-bit numeric address that is written as four numbers that are separated by periods. For example:x.x.x.xThe valid range for each number is zero to 255. For example:1.160.10.240One primary format of an IPv6 address is a 128-bit numeric address that is written as eight numbers that are separated by colons. For example:x:x:x:x:x:x:x:xThe valid range for each number is zero to ffff (hexadecimal). For example:fec0:fff:0000:0000:0000:0000:0000:1The IPv6 address can be expressed in an abbreviated form by collapsing the contiguous fields that contain only zeros. For example, 0009:0000:0000:0000:0000:0008:0007:0006 can be represented as 9::8:7:6. Refer to the RFC 2373 standard to determine what constitutes a valid representation of an IPv6 address. IBM Security Access Manager supports any of the valid forms for an IPv6 address that is described in Section 2.2 of RFC 2373. IBM Security Access Manager does not support prefix notation for a netmask.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

IPv4 and IPv6 overview

Beginning with Tivoli® Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).

IPv6 improves upon IPv4 in the following ways:

IPv6 allocates 128 bits for the address space; IPv4 only allocates 32 bits for the address space.

IPv6 can decrease the size of static, non-default routing tables, used to route packets through the Internet backbone.

IPv6 provides end-to-end security by requiring adherence to the IP Security protocols (IPSec).

The primary format of an IPv4 address is a 32-bit numeric address that is written as four numbers that are separated by periods. For example:

x.x.x.x

The valid range for each number is zero to 255. For example:

1.160.10.240

One primary format of an IPv6 address is a 128-bit numeric address that is written as eight numbers that are separated by colons. For example:

x:x:x:x:x:x:x:x

The valid range for each number is zero to ffff (hexadecimal). For example:

fec0:fff:0000:0000:0000:0000:0000:1

The IPv6 address can be expressed in an abbreviated form by collapsing the contiguous fields that contain only zeros. For example, 0009:0000:0000:0000:0000:0008:0007:0006 can be represented as 9::8:7:6.

Refer to the RFC 2373 standard to determine what constitutes a valid representation of an IPv6 address. IBM Security Access Manager supports any of the valid forms for an IPv6 address that is described in Section 2.2 of RFC 2373. IBM Security Access Manager does not support prefix notation for a netmask.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Configuring WebSEAL for IPv6 and IPv4 requestsConfiguring WebSEAL for IPv6 and IPv4 requestsConfiguring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. ipv6-supportstanza entryIPv6ipv6-support stanza entryIPv4ipv6-support stanza entryYou determine the supported network by setting the following values in the ipv6-support stanza. yes IPv6 and IPv4 networks are supported. This value is the default setting.When both IPv6 and IPv4 networks are supported, WebSEAL listens for incoming HTTP and HTTPS requests that are IPV4 protocol-based or IPV6 protocol-based.If the host name for a junction maps only to an IPv6 address, then IPv6 is used. If the host name maps to an IPv4 address, then an IPv4 address is used. If the DNS name maps to both an IPv6 and an IPv4 address, then the choice is arbitrary. To specify a particular protocol, use the IPv6 or IPv4 address of the host when you create the junction.If no IPV6 interface is available, WebSEAL listens only for IPv4 requests. If there are both IPv6 and IPv4 interfaces available, by default WebSEAL listens for requests on both protocols. If you do not want WebSEAL to accept IPv6 connections, set ipv6-support = no.noOnly IPv4 networks are supported.Log in to the local management interface.Select Secure Web SettingsManageReverse Proxy.Select your instance.Select ManageConfigurationEdit Configuration File.Edit the ipv6-support stanza.[server] ipv6-support = {yes|no}Save and deploy your changes.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Configuring WebSEAL for IPv6 and IPv4 requests

By default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6.

About this task

You determine the supported network by setting the following values in the ipv6-support stanza.

yes

IPv6 and IPv4 networks are supported. This value is the default setting.

When both IPv6 and IPv4 networks are supported, WebSEAL listens for incoming HTTP and HTTPS requests that are IPV4 protocol-based or IPV6 protocol-based.

If the host name for a junction maps only to an IPv6 address, then IPv6 is used. If the host name maps to an IPv4 address, then an IPv4 address is used.

If the DNS name maps to both an IPv6 and an IPv4 address, then the choice is arbitrary. To specify a particular protocol, use the IPv6 or IPv4 address of the host when you create the junction.

If no IPV6 interface is available, WebSEAL listens only for IPv4 requests. If there are both IPv6 and IPv4 interfaces available, by default WebSEAL listens for requests on both protocols. If you do not want WebSEAL to accept IPv6 connections, set ipv6-support = no.

no

Only IPv4 networks are supported.

Procedure

Log in to the local management interface.

Select Secure Web Settings > Manage > Reverse Proxy.

Select your instance.

Select Manage > Configuration > Edit Configuration File.

Edit the ipv6-support stanza.

[server]
ipv6-support = {yes|no}

Save and deploy your changes.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

IPv6: Compatibility supportIPv6: Compatibility supportIPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.ipv6-supportcompatibility supportIPv6compatibility supportIPv4compatibility supportIf the ipv6-support is set to no, then WebSEAL provides support for IPv4 as it did in previous releases, but does not support IPv6. For example, the iv-remote-address-ipv6 HTTP header and XAUTHN_IPADDR_IPV6 identifier, which is used with the external authentication C API are not available. For more information, see the Reference topics in the IBM Knowledge Center.If ipv6-support is set to yes, IPv6 is supported. Attributes containing IPv4 addresses continue to hold IPv4 addresses. Custom modules that are written for previous releases still continue to work.However, if WebSEAL passes an IPv6-only address to an older custom module that is not written to support IPv6 format, the older module might require updating to handle the IPv6 address format.The address range for IPv6 is larger than the range available to IPv4. With older modules, WebSEAL maps an IPv6 address to an IPv4 format when possible. For example, the IPv6 address ::c0a8:1 maps to the IPv4 address 192.168.0.1.If the IPv6 address exceeds the range for IPv4, WebSEAL maps the address by default to 0.0.0.0 in IPv4 format. For example, the IPv6 address fec0::1 has no IPv4 equivalent and therefore is mapped to the IPv4 address 0.0.0.0.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

IPv6: Compatibility support

Before you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.

If the ipv6-support is set to no, then WebSEAL provides support for IPv4 as it did in previous releases, but does not support IPv6.

For example, the iv-remote-address-ipv6 HTTP header and XAUTHN_IPADDR_IPV6 identifier, which is used with the external authentication C API are not available. For more information, see the Reference topics in the IBM® Knowledge Center.

If ipv6-support is set to yes, IPv6 is supported. Attributes containing IPv4 addresses continue to hold IPv4 addresses. Custom modules that are written for previous releases still continue to work.

However, if WebSEAL passes an IPv6-only address to an older custom module that is not written to support IPv6 format, the older module might require updating to handle the IPv6 address format.

The address range for IPv6 is larger than the range available to IPv4. With older modules, WebSEAL maps an IPv6 address to an IPv4 format when possible. For example, the IPv6 address ::c0a8:1 maps to the IPv4 address 192.168.0.1.

If the IPv6 address exceeds the range for IPv4, WebSEAL maps the address by default to 0.0.0.0 in IPv4 format. For example, the IPv6 address fec0::1 has no IPv4 equivalent and therefore is mapped to the IPv4 address 0.0.0.0.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

IPv6: Upgrade notesIPv6: Upgrade notesIPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.ipv6-supportWebSEAL upgradeIPv6upgradeIPv4upgrade The upgrade module sets ipv6-support = no in the instance-specific configuration file. After an upgrade, you can enable support for IPv6 by manually editing the WebSEAL configuration to change the value of ipv6-support to yes.For more information, see Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. .Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

IPv6: Upgrade notes

When you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.

The upgrade module sets ipv6-support = no in the instance-specific configuration file. After an upgrade, you can enable support for IPv6 by manually editing the WebSEAL configuration to change the value of ipv6-support to yes.

For more information, see Configuring WebSEAL for IPv6 and IPv4 requests.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

IP levels for credential attributesIP levels for credential attributesIP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. ip-support-level stanza entryipv6-supportcredential attributesIPv6ip-support-levelIPv4ip-support-levelThere are different format structures available to hold IPv4 and IPv6 information. Adding attributes to credentials can affect WebSEAL performance. The following values are available in the ip-support-level stanza entry in the [server] stanza of the WebSEAL configuration file.displaced-only WebSEAL generates the IPv4 attribute only when it builds user credentials and when authenticating users through external authentication C API modules. This value is the default for migrated WebSEAL installations (ipv6-support=no): [server] ip-support-level = displaced-only This value is not permitted when ipv6-support=yes.generic-only WebSEAL generates new generic attributes that support both IPv4 and IPv6 only when it builds user credentials and when authenticating users through external authentication C API modules. This value is the default for new WebSEAL installations (ipv6-support=yes): [server] ip-support-level = generic-onlydisplaced-and-generic Both sets of attribute types (produced by displaced-only and generic-only) are used when it builds user credentials and when authenticating users through external authentication C API modules. [server] ip-support-level = displaced-and-genericWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

IP levels for credential attributes

Network information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level.

There are different format structures available to hold IPv4 and IPv6 information. Adding attributes to credentials can affect WebSEAL performance.

The following values are available in the ip-support-level stanza entry in the [server] stanza of the WebSEAL configuration file.

displaced-only

WebSEAL generates the IPv4 attribute only when it builds user credentials and when authenticating users through external authentication C API modules.

This value is the default for migrated WebSEAL installations (ipv6-support=no):

[server]
ip-support-level = displaced-only

This value is not permitted when ipv6-support=yes.

generic-only

WebSEAL generates new generic attributes that support both IPv4 and IPv6 only when it builds user credentials and when authenticating users through external authentication C API modules.

This value is the default for new WebSEAL installations (ipv6-support=yes):

[server]
ip-support-level = generic-only

displaced-and-generic

Both sets of attribute types (produced by displaced-only and generic-only) are used when it builds user credentials and when authenticating users through external authentication C API modules.

[server]
ip-support-level = displaced-and-generic

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

LDAP directory server configurationLDAP directory server configurationLDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. LDAP directory server configurationldap.confbind-pwdbind-dnbind-pwdbind-dnenabled LDAP configurationportLDAP configurationssl-portmax-search-sizereplicasLDAP configurationldap.conf (LDAP configuration)LDAP directory server configurationenabledhostportssl-portmax-search-sizereplicaThe location of the LDAP server and its configuration file ldap.conf is provided during Security Access Manager runtime configuration. A combination of stanza entries and values from the ldap.conf and the WebSEAL configuration file webseald.conf provides the appropriate information to WebSEAL as the LDAP client.WebSEAL determines that the configured user registry is an LDAP-based directory server. The following stanza entries in the [ldap] stanza of webseald.conf are valid: host port ssl-port max-search-size replica auth-using-compare cache-enabled prefer-readwrite-server ssl-enabled ssl-keyfile ssl-keyfile-dn timeout auth-timeout search-timeout default-policy-override-support user-and-group-in-same-suffix login-failures-persistentAdditionally, the values for the following stanza entries in ldap.conf override any existing values in webseald.conf: host port ssl-port max-search-size replicaFor information about the stanza entries, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

LDAP directory server configuration

When Security Access Manager is configured to use an LDAP-based user registry, such as IBM®Tivoli® Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server.

The location of the LDAP server and its configuration file ldap.conf is provided during Security Access Manager runtime configuration. A combination of stanza entries and values from the ldap.conf and the WebSEAL configuration file webseald.conf provides the appropriate information to WebSEAL as the LDAP client.

WebSEAL determines that the configured user registry is an LDAP-based directory server.

The following stanza entries in the [ldap] stanza of webseald.conf are valid:

host
port
ssl-port
max-search-size
replica
auth-using-compare
cache-enabled
prefer-readwrite-server
ssl-enabled
ssl-keyfile
ssl-keyfile-dn
timeout
auth-timeout
search-timeout
default-policy-override-support
user-and-group-in-same-suffix
login-failures-persistent

Additionally, the values for the following stanza entries in ldap.conf override any existing values in webseald.conf:

host
port
ssl-port
max-search-size
replica

For information about the stanza entries, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

WebSEAL worker thread configurationWebSEAL worker thread configurationWebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.worker threadsWebSEALworker threadsconfigurationworker-threads stanza entryOther connections that arrive when all worker threads are busy are buffered until a worker thread is available.This configuration stanza entry does not impose an upper boundary on the number of simultaneous connections. This stanza entry specifies the number of threads made available to service a potentially unlimited work queue.Configure the number of worker threads carefully. Choosing the optimal number of worker threads depends on understanding the quantity and type of traffic on your network. In all cases, you must enter only a value that is less than the worker threads limit imposed by the operating system.By increasing the number of threads, you are decreasing the average time that it takes to finish the requests. However, increasing the number of threads impacts other factors that might have an adverse effect on server performance.WebSEAL maintains a single, generic worker list and worker threads pool for handling requests from clients by using TCP or SSL. This enhanced mechanism enables WebSEAL to use fewer system resources while it handles greater load. You can configure the worker thread pool size by setting the worker-threads stanza entry in the [server] stanza portion of the WebSEAL configuration file. [server] worker-threads = 50 The value of this stanza entry must remain within the worker threads limits set by the operating system.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

WebSEAL worker thread configuration

The number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.

Other connections that arrive when all worker threads are busy are buffered until a worker thread is available.

This configuration stanza entry does not impose an upper boundary on the number of simultaneous connections. This stanza entry specifies the number of threads made available to service a potentially unlimited work queue.

Configure the number of worker threads carefully. Choosing the optimal number of worker threads depends on understanding the quantity and type of traffic on your network. In all cases, you must enter only a value that is less than the worker threads limit imposed by the operating system.

By increasing the number of threads, you are decreasing the average time that it takes to finish the requests. However, increasing the number of threads impacts other factors that might have an adverse effect on server performance.

WebSEAL maintains a single, generic worker list and worker threads pool for handling requests from clients by using TCP or SSL. This enhanced mechanism enables WebSEAL to use fewer system resources while it handles greater load.

You can configure the worker thread pool size by setting the worker-threads stanza entry in the [server] stanza portion of the WebSEAL configuration file.

[server]
worker-threads = 50

Note: The value of this stanza entry must remain within the worker threads limits set by the operating system.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

WebSEAL worker threadsWebSEAL worker threadsWebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.worker threadsWebSEALprocessing multiple requestsmultiple requestsworker threads However, the worker thread pool can be quickly drained if a particular back-end application is unusually slow when it processes a high volume of requests. A depletion of the worker thread pool by this one application renders WebSEAL incapable of responding to requests for services on the remaining junctioned application servers. When no worker threads are available to handle incoming requests, users experience a WebSEAL server that is not responding.You can adjust the worker threads value according to your WebSEAL implementation. The number of worker threads available to WebSEAL is specified by the worker-threads stanza entry in the WebSEAL configuration file.The configuration mechanism maintains a fair distribution of worker threads across all junctions and prevents depletion of the worker thread pool by any one junction. This configuration also prevents any application from claiming more than its share of worker threads.To configure the allocation of WebSEAL worker threads across multiple junctions, see Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. . To configure the allocation of WebSEAL worker threads for every junction, see Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis..Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

WebSEAL worker threads

WebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.

However, the worker thread pool can be quickly drained if a particular back-end application is unusually slow when it processes a high volume of requests. A depletion of the worker thread pool by this one application renders WebSEAL incapable of responding to requests for services on the remaining junctioned application servers.

When no worker threads are available to handle incoming requests, users experience a WebSEAL server that is not responding.

You can adjust the worker threads value according to your WebSEAL implementation. The number of worker threads available to WebSEAL is specified by the worker-threads stanza entry in the WebSEAL configuration file.

The configuration mechanism maintains a fair distribution of worker threads across all junctions and prevents depletion of the worker thread pool by any one junction. This configuration also prevents any application from claiming more than its share of worker threads.

To configure the allocation of WebSEAL worker threads across multiple junctions, see Global allocation of worker threads for junctions.

To configure the allocation of WebSEAL worker threads for every junction, see Per-junction allocation of worker threads for junctions.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Global allocation of worker threads for junctions Global allocation of worker threads for junctionsGlobal allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. worker threadsglobal allocationjunctionsstanzaworker-thread-soft-limit stanza entryworker-thread-hard-limit stanza entryThe values that are used for these stanza entries are expressed as percentages within the range of 0 to 100. worker-thread-soft-limit This stanza entry is set to send a warning before the hard limit is reached. When the worker-thread-soft-limit is exceeded, warning messages are sent, every 30 seconds, to the WebSEAL error log file. For example, when worker-threads = 50, a setting of 60 (%) causes warning messages to be displayed when the junction uses more than 30 worker threads. All requests above 30 worker threads are still processed until the hard limit is reached.The default value is 90 percent.worker-thread-hard-limit This stanza entry determines the cut-off point for servicing requests across a junction. When the worker-thread-hard-limit is exceeded, error messages are sent, every 30 seconds, to the WebSEAL error log file. In addition, the user is sent a 503 Service Unavailable message. For example, when worker-threads = 50, a setting of 80 (%) causes error messages to be displayed when the junction tries to use more than 40 worker threads. All requests that represent greater than 40 worker threads on the junction are returned with a 503 Service Unavailable message.The default value of 100 (%) indicates that there is no limit.These global settings apply equally to all configured junctions. When you configure these two stanza entries, it is logical to set the soft limit to a lower value than the hard limit.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Global allocation of worker threads for junctions

You can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server.

The values that are used for these stanza entries are expressed as percentages within the range of 0 to 100.

worker-thread-soft-limit

This stanza entry is set to send a warning before the hard limit is reached. When the worker-thread-soft-limit is exceeded, warning messages are sent, every 30 seconds, to the WebSEAL error log file.

For example, when worker-threads = 50, a setting of 60 (%) causes warning messages to be displayed when the junction uses more than 30 worker threads. All requests above 30 worker threads are still processed until the hard limit is reached.

The default value is 90 percent.

worker-thread-hard-limit

This stanza entry determines the cut-off point for servicing requests across a junction. When the worker-thread-hard-limit is exceeded, error messages are sent, every 30 seconds, to the WebSEAL error log file. In addition, the user is sent a 503 Service Unavailable message.

For example, when worker-threads = 50, a setting of 80 (%) causes error messages to be displayed when the junction tries to use more than 40 worker threads. All requests that represent greater than 40 worker threads on the junction are returned with a 503 Service Unavailable message.

The default value of 100 (%) indicates that there is no limit.

These global settings apply equally to all configured junctions. When you configure these two stanza entries, it is logical to set the soft limit to a lower value than the hard limit.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Per-junction allocation of worker threads for junctionsPer-junction allocation of worker threads for junctionsPer-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.worker threadsallocationjunctionsallocationper-junctionjunctionsworker thread allocationSpecify hard and soft worker thread limits on a specific junction by using the following options in the pdadmin server task create command.–l percent_value This option sets a value (percent) on the junction that defines the soft limit for consumption of worker threads. As in the global soft limit setting, this option causes warning messages to be displayed when the junction uses more worker threads than allowed by the setting.–L percent_value This option sets a value (percent) on the junction that defines the hard limit for consumption of worker threads. As in the global hard limit setting, this option causes warning messages to be displayed when the junction tries to use more worker threads than allowed by the setting. In addition, the user is sent a 503 Service Unavailable message.This example must be entered in one line.pdadmin> server task webseald-<server-name> create -t tcp -h <host-name> -l 60 -L 80 jct-pointPer-junction settings always override the global settings in the WebSEAL configuration file. Ensure that the settings on a specific junction do not adversely affect the policy that is established by the global settings.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Per-junction allocation of worker threads for junctions

Use the pdadmin command so that you can limit worker thread consumption on a per-junction basis.

Specify hard and soft worker thread limits on a specific junction by using the following options in the pdadmin server task create command.

–l percent_value

This option sets a value (percent) on the junction that defines the soft limit for consumption of worker threads. As in the global soft limit setting, this option causes warning messages to be displayed when the junction uses more worker threads than allowed by the setting.

–L percent_value

This option sets a value (percent) on the junction that defines the hard limit for consumption of worker threads. As in the global hard limit setting, this option causes warning messages to be displayed when the junction tries to use more worker threads than allowed by the setting. In addition, the user is sent a 503 Service Unavailable message.

This example must be entered in one line.

pdadmin> server task webseald-<server-name> create -t tcp -h <host-name>
-l 60 -L 80 jct-point

Per-junction settings always override the global settings in the WebSEAL configuration file. Ensure that the settings on a specific junction do not adversely affect the policy that is established by the global settings.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Allocation view of worker threads for junctionsAllocation view of worker threads for junctionsAllocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.worker threadsallocationjunctionsstanza You can use the pdadmin server task show command to view the number of active worker threads on a specific junction.pdadmin> server task webseald-<server-name> show /<jct-point>If you specify a soft limit value that is greater than the hard limit value on a specific junction, the junction is not created.You must specify both soft and hard limit values, both –l and –L options, on a specific junction.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Allocation view of worker threads for junctions

Use the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.

You can use the pdadmin server task show command to view the number of active worker threads on a specific junction.

pdadmin> server task webseald-<server-name> show /<jct-point>

If you specify a soft limit value that is greater than the hard limit value on a specific junction, the junction is not created.

You must specify both soft and hard limit values, both –l and –L options, on a specific junction.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Supported wildcard pattern matching characters

HTTP data compressionHTTP data compressionHTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.HTTPdata compressioncompressionHTTP datadata compressionHTTPgzipgzipWebSEAL uses the gzip compression algorithm that is described in RFC 1952. Gzip is supported by all major browsers. HTTP compression in WebSEAL can be configured based on the following types.MIME-typebrowser typeprotected object policies or POPsWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.Compression based on MIME-typeYou can create an entry in the WebSEAL configuration file for each MIME-type or group of MIME-types for which data compression is needed. Compression based on user agent typeWebSEAL returns compressed data to user agents that request them. A user agent is a client that initiates a request. Use the WebSEAL configuration file to explicitly enable or disable compression for various browsers.Compression policy in POPsAttach a protected object policy or POP to an object so that WebSEAL disables compression of that object. Data compression limitationThe transfer of compressed data between WebSEAL and back-end servers is not supported. Configuring data compression policyEdit the WebSEAL configuration file so that you can specify data compression policy for communication between WebSEAL and client browsers.

HTTP data compression

The WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.

WebSEAL uses the gzip compression algorithm that is described in RFC 1952. Gzip is supported by all major browsers.

HTTP compression in WebSEAL can be configured based on the following types.

MIME-type

browser type

protected object policies or POPs

Compression based on MIME-type
You can create an entry in the WebSEAL configuration file for each MIME-type or group of MIME-types for which data compression is needed.

Compression based on user agent type
WebSEAL returns compressed data to user agents that request them. A user agent is a client that initiates a request. Use the WebSEAL configuration file to explicitly enable or disable compression for various browsers.

Compression policy in POPs
Attach a protected object policy or POP to an object so that WebSEAL disables compression of that object.

Data compression limitation
The transfer of compressed data between WebSEAL and back-end servers is not supported.

Configuring data compression policy
Edit the WebSEAL configuration file so that you can specify data compression policy for communication between WebSEAL and client browsers.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Compression based on MIME-typeCompression based on MIME-typeCompression based on MIME-typeYou can create an entry in the WebSEAL configuration file for each MIME-type or group of MIME-types for which data compression is needed. compressionbased on MIME-typedata compressionbased on MIME-typecompress-mime-types stanza[compress-mime-types] mime_type = minimum_doc_size[:compression_level]The mime-type can specify one particular MIME type or can use wildcard characters to specify a class of MIME types. Each mime-type declaration is a separate entry in the [compress-mime-types] stanza. The wildcard character (*) is limited to entries of one collection of MIME types. For example, text/*. Any MIME-type not listed in the stanza is not compressed. Order is important. The first entry that matches a returned document is used for that document. The minimum_doc_size value specifies the policy on the size of documents that are compressed. This value is an integer. Valid values are shown in the following list.-1When the minimum size is -1, documents of the specified MIME-type are never compressed.0 When the minimum size is 0, documents of the specified MIME-type are always compressed.Integer greater than zero When the minimum size is greater than zero, documents of the specified MIME-type are compressed when the number of bytes in the response to WebSEAL exceeds this integer value.Any negative number other than -1 generates an error message.When WebSEAL receives a request from a browser, the server examines the content-length field in the HTTP header to determine the size of the incoming data. However, not all HTTP responses contain the content-length field. When the content-length field is not found, WebSEAL compresses the document unless the applicable MIME-type is configured to never be compressed. For example, minimum_doc_size of -1.The compression_level is an optional setting that specifies the data compression level. Valid values are integers 1 - 9. The larger the integer, the greater the amount of compression that takes place. The greater the amount of compression, the greater the load that is placed on the CPU. The value of increased compression must be weighed against any performance impacts. When the compression_level is not specified, a default level of 1 is used.The following example compresses all documents of a size greater than 1000 bytes:[compress-mime-type] */* = 1000The following set of entries:disables compression for all imagesdisables compression for CSS filesenables compression at level 5 for all PDF documentsenables compression for HTML documents of size greater than 2000 bytesenables compression for all other text documents, regardless of size,[compress-mime-type] image/* = -1 text/css = -1 application/pdf = 0:5 text/html = 2000 text/* = 0HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.

Compression based on MIME-type

You can create an entry in the WebSEAL configuration file for each MIME-type or group of MIME-types for which data compression is needed.

[compress-mime-types]
mime_type = minimum_doc_size[:compression_level]

The mime-type can specify one particular MIME type or can use wildcard characters to specify a class of MIME types. Each mime-type declaration is a separate entry in the [compress-mime-types] stanza. The wildcard character (*) is limited to entries of one collection of MIME types. For example, text/*. Any MIME-type not listed in the stanza is not compressed. Order is important. The first entry that matches a returned document is used for that document.

The minimum_doc_size value specifies the policy on the size of documents that are compressed. This value is an integer. Valid values are shown in the following list.

-1

When the minimum size is -1, documents of the specified MIME-type are never compressed.

0

When the minimum size is 0, documents of the specified MIME-type are always compressed.

Integer greater than zero

When the minimum size is greater than zero, documents of the specified MIME-type are compressed when the number of bytes in the response to WebSEAL exceeds this integer value.

Any negative number other than -1 generates an error message.

When WebSEAL receives a request from a browser, the server examines the content-length field in the HTTP header to determine the size of the incoming data. However, not all HTTP responses contain the content-length field. When the content-length field is not found, WebSEAL compresses the document unless the applicable MIME-type is configured to never be compressed. For example, minimum_doc_size of -1.

The compression_level is an optional setting that specifies the data compression level. Valid values are integers 1 - 9. The larger the integer, the greater the amount of compression that takes place. The greater the amount of compression, the greater the load that is placed on the CPU. The value of increased compression must be weighed against any performance impacts. When the compression_level is not specified, a default level of 1 is used.

The following example compresses all documents of a size greater than 1000 bytes:

[compress-mime-type]
*/* = 1000

The following set of entries:

disables compression for all images

disables compression for CSS files

enables compression at level 5 for all PDF documents

enables compression for HTML documents of size greater than 2000 bytes

enables compression for all other text documents, regardless of size

,

[compress-mime-type]

image/* = -1
text/css = -1
application/pdf = 0:5
text/html = 2000
text/* = 0

Parent topic: HTTP data compression

Compression based on user agent typeCompression based on user agent typeCompression based on user agent typeWebSEAL returns compressed data to user agents that request them. A user agent is a client that initiates a request. Use the WebSEAL configuration file to explicitly enable or disable compression for various browsers.compressionbased on user agent typedata compressionbased on user agent typecompress-users-agents stanzaExamples of user agents include browsers, editors, spiders (web-traversing robots), or other tools. WebSEAL does not return compressed data to user agents that do not request it. However, some user agents request compressed data but do not know how to handle the data properly. The following entry is the syntax.[compress-user-agents] user_agent_pattern = {yes|no}The user_agent_pattern consists of wildcard patterns that match characters that are found in the user-agent header sent to WebSEAL. The value yes means to compress data that is returned to the browser. The value no means to return the data uncompressed.When the user-agent header does not match any of the stanza entries in the WebSEAL configuration file, WebSEAL allows the accept-encoding header that is sent by the browser.For example, the following entry enables compression for Internet Explorer 6, but disables compression for all other browsers:[compress-user-agents] *MSIE 6.0" = yes * = noHTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.

Compression based on user agent type

WebSEAL returns compressed data to user agents that request them. A user agent is a client that initiates a request. Use the WebSEAL configuration file to explicitly enable or disable compression for various browsers.

Examples of user agents include browsers, editors, spiders (web-traversing robots), or other tools. WebSEAL does not return compressed data to user agents that do not request it. However, some user agents request compressed data but do not know how to handle the data properly.

The following entry is the syntax.

[compress-user-agents]
user_agent_pattern = {yes|no}

The user_agent_pattern consists of wildcard patterns that match characters that are found in the user-agent header sent to WebSEAL. The value yes means to compress data that is returned to the browser. The value no means to return the data uncompressed.

When the user-agent header does not match any of the stanza entries in the WebSEAL configuration file, WebSEAL allows the accept-encoding header that is sent by the browser.

For example, the following entry enables compression for Internet Explorer 6, but disables compression for all other browsers:

[compress-user-agents]
*MSIE 6.0" = yes
* = no

Parent topic: HTTP data compression

Compression policy in POPsCompression policy in POPsCompression policy in POPsAttach a protected object policy or POP to an object so that WebSEAL disables compression of that object. compressionPOP policydata compressionPOP policyYou can specify a compression policy of do not compress in a POP. To specify this policy, add the following attribute to the POP:document-compression = noA POP without this attribute set, or with this attribute set to any value other than no, allows documents to be compressed.The following example shows how to disable compression for the junction /appOne.pdadmin> pop create appOnePop pdadmin> pop modify appOnePop set attribute document-compression no pdadmin> pop attach /WebSEAL/host/appOne appOnePopTo allow compression for a subdirectory beneath /appOne with an overriding POP, attach a different POP that does not have the document-compression attribute. For example:pdadmin> pop create dataPop pdadmin> pop attach /WebSEAL/host/appOne/data dataPopThis method of applying compression policy can be used with URLs. For example, to disable compression that is based on wildcard patterns that are applied to URLs, you can use dynurl. To disable compression for all requests to a junction that have a particular argument in the query string, you can create a dynurl.conf file with the following entries./disableCompression /appOne/*\?want-response=text/xmlYou can then attach a POP to /WebSEAL/host/disableCompression with the document-compression attribute set to no.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.

Compression policy in POPs

Attach a protected object policy or POP to an object so that WebSEAL disables compression of that object.

You can specify a compression policy of do not compress in a POP. To specify this policy, add the following attribute to the POP:

document-compression = no

A POP without this attribute set, or with this attribute set to any value other than no, allows documents to be compressed.

The following example shows how to disable compression for the junction /appOne.

pdadmin> pop create appOnePop
pdadmin> pop modify appOnePop set attribute document-compression no
pdadmin> pop attach /WebSEAL/host/appOne appOnePop

To allow compression for a subdirectory beneath /appOne with an overriding POP, attach a different POP that does not have the document-compression attribute. For example:

pdadmin> pop create dataPop
pdadmin> pop attach /WebSEAL/host/appOne/data dataPop

This method of applying compression policy can be used with URLs. For example, to disable compression that is based on wildcard patterns that are applied to URLs, you can use dynurl. To disable compression for all requests to a junction that have a particular argument in the query string, you can create a dynurl.conf file with the following entries.

/disableCompression     /appOne/*\?want-response=text/xml

You can then attach a POP to /WebSEAL/host/disableCompression with the document-compression attribute set to no.

Parent topic: HTTP data compression

Data compression limitationData compression limitationData compression limitationThe transfer of compressed data between WebSEAL and back-end servers is not supported. data compressionlimitationscompressiondatalimitationsWebSEAL filters URLs for various purposes. However, WebSEAL does not filter compressed data.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.

Data compression limitation

The transfer of compressed data between WebSEAL and back-end servers is not supported.

WebSEAL filters URLs for various purposes. However, WebSEAL does not filter compressed data.

Parent topic: HTTP data compression

Configuring data compression policyConfiguring data compression policyConfiguring data compression policyEdit the WebSEAL configuration file so that you can specify data compression policy for communication between WebSEAL and client browsers.compressionconfiguring data compression policydata compressiondatapolicyLog in to the local management interface.Select Secure Web SettingsManageReverse Proxy.Select your instance.Select ManageConfigurationEdit Configuration File.Specify each MIME-type for which a data compression policy applies. Assign a value that enforces the policy.[compress-mime-types] mime_type = minimum_doc_size The default setting leaves all data uncompressed: [compress-mime-types] */* = -1For more information, see Compression based on MIME-typeYou can create an entry in the WebSEAL configuration file for each MIME-type or group of MIME-types for which data compression is needed. .Specify each type of user agent (browser) for which a data compression policy applies. Enable data compression by assigning the value yes. Disable data compression by assigning the value no.[compress-user-agents] user_agent = {yes|no}No entries are set by default. When no entry matches the user-agent's accept-encoding header, the value in the accept-encoding header is allowed. For more information, see the [compress-user-agents] stanza in the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.Specify compression policies in POPs, and apply the POPs to the appropriate objects in the protected object space. For more information, see Compression policy in POPsAttach a protected object policy or POP to an object so that WebSEAL disables compression of that object. .HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.

Configuring data compression policy

Edit the WebSEAL configuration file so that you can specify data compression policy for communication between WebSEAL and client browsers.

Procedure

Log in to the local management interface.

Select Secure Web Settings > Manage > Reverse Proxy.

Select your instance.

Select Manage > Configuration > Edit Configuration File.

Specify each MIME-type for which a data compression policy applies. Assign a value that enforces the policy.

[compress-mime-types] mime_type = minimum_doc_size

The default setting leaves all data uncompressed:

[compress-mime-types]
*/* = -1

For more information, see Compression based on MIME-type.

Specify each type of user agent (browser) for which a data compression policy applies. Enable data compression by assigning the value yes. Disable data compression by assigning the value no.

[compress-user-agents]
user_agent = {yes|no}

No entries are set by default. When no entry matches the user-agent's accept-encoding header, the value in the accept-encoding header is allowed. For more information, see the [compress-user-agents] stanza in the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.

Optional: Specify compression policies in POPs, and apply the POPs to the appropriate objects in the protected object space. For more information, see Compression policy in POPs.

Parent topic: HTTP data compression

WebSEAL data handling by using UTF-8WebSEAL data handling by using UTF-8WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8WebSEAL data handlingWebSEALdata handing using UTF-8WebSEAL adopts UTF-8 as the default code page for all internal data handling. This support enables WebSEAL to process data from multiple languages at the same time. WebSEAL administrators can configure how WebSEAL handles data input and output. An example of data input is characters that are sent to WebSEAL by a browser, such as user logins and forms data. An example of data output is logging information that is written out to the file system by the Security Access Manager event-logging manager.WebSEAL handles data internally in UTF-8 regardless of the locale in which the WebSEAL process is running. When locale-specific data is needed as input or output, the locale in which the WebSEAL process is running becomes important. Most operating systems do not use UTF-8 by default. Administrators expecting locale-specific behavior need to know which locale is being used, and need to set WebSEAL UTF-8 configuration options to match the required behavior.The system locale consists of two parts: the language and the local code page. Local code pages can be UTF-8 or not UTF-8. Historically, most operating systems use a local code page that is not UTF-8. For example, a common local code page that is used to represent the 8-bit ASCII character set for United States English is en_US.ISO88591, which uses the ISO-8859-1 character set. Administrators running systems that need to process client requests and forms data in the local code page can modify the default settings for URL support (utf8-url-support-enabled) and forms support (utf8-forms-support-enabled). The default WebSEAL setting is to process data in UTF-8 format only.For example, you might need to change default settings for systems that process client requests and forms data that uses non-UTF-8 local code pages. For example:A single-byte Latin character set, such as Spanish, French, or GermanA multi-byte character set, such as Japanese or Chinese If you are running systems that need to provide true multi-locale support to handle users and data in multiple languages, review the following settings: Your local code page setting. You might consider converting to a UTF-8 code page.The default WebSEAL multi-locale UTF-8 settings.You can customize these configuration settings to best fit your deployment.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

WebSEAL data handling by using UTF-8

WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.

WebSEAL adopts UTF-8 as the default code page for all internal data handling. This support enables WebSEAL to process data from multiple languages at the same time.

WebSEAL administrators can configure how WebSEAL handles data input and output. An example of data input is characters that are sent to WebSEAL by a browser, such as user logins and forms data. An example of data output is logging information that is written out to the file system by the Security Access Manager event-logging manager.

WebSEAL handles data internally in UTF-8 regardless of the locale in which the WebSEAL process is running. When locale-specific data is needed as input or output, the locale in which the WebSEAL process is running becomes important. Most operating systems do not use UTF-8 by default. Administrators expecting locale-specific behavior need to know which locale is being used, and need to set WebSEAL UTF-8 configuration options to match the required behavior.

The system locale consists of two parts: the language and the local code page. Local code pages can be UTF-8 or not UTF-8. Historically, most operating systems use a local code page that is not UTF-8. For example, a common local code page that is used to represent the 8-bit ASCII character set for United States English is en_US.ISO88591, which uses the ISO-8859-1 character set.

Administrators running systems that need to process client requests and forms data in the local code page can modify the default settings for URL support (utf8-url-support-enabled) and forms support (utf8-forms-support-enabled). The default WebSEAL setting is to process data in UTF-8 format only.

For example, you might need to change default settings for systems that process client requests and forms data that uses non-UTF-8 local code pages. For example:

A single-byte Latin character set, such as Spanish, French, or German

A multi-byte character set, such as Japanese or Chinese

If you are running systems that need to provide true multi-locale support to handle users and data in multiple languages, review the following settings:

Your local code page setting. You might consider converting to a UTF-8 code page.

The default WebSEAL multi-locale UTF-8 settings.

You can customize these configuration settings to best fit your deployment.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 dependency on user registry configurationUTF-8 dependency on user registry configurationUTF-8 dependency on user registry configuration in IBM Security Access Manager for WebFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8dependency on user registry configurationuser registriesUTF-8 dependencyMost user registries support UTF-8 by default. Some LDAP user registries, and their supporting databases, can optionally be configured to not support UTF-8. Ensure that the LDAP user registry and database that is used with Security Access Manager uses UTF-8. IBM Tivoli Directory Server is by default that is configured to use UTF-8.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 dependency on user registry configuration

For optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.

Most user registries support UTF-8 by default. Some LDAP user registries, and their supporting databases, can optionally be configured to not support UTF-8. Ensure that the LDAP user registry and database that is used with Security Access Manager uses UTF-8.

IBM® Tivoli® Directory Server is by default that is configured to use UTF-8.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 data conversion issuesUTF-8 data conversion issuesUTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8data conversiondata conversion issuesUTF-8When WebSEAL reads data in, it must convert the data from non-UTF-8 to UTF-8. When WebSEAL writes out data, it must convert the data from UTF-8 to non-UTF-8.If conversion to a local code page is required, no data loss occurs when it runs in a UTF-8 locale.The conversion from a UTF-8 locale to a non-UTF-8 locale (local code page) can, in some situations, result in data loss. For example, if WebSEAL is running in an en_US.ISO8859 environment, and a Japanese user name must be converted to the local code page, the result is a string of question marks ("????"). This result occurs because there is no way to represent Japanese characters in ISO-8859-1. For this reason, WebSEAL must be run by using UTF-8.There is a risk of data loss when it runs administrative commands (pdadmin) from a non-UTF-8 environment. Before version 5.1, WebSEAL always ran in the same locale as the pdadmin utility. With multi-locale support, WebSEAL can now run in a different locale. WebSEAL must return messages to the administrator in the administrator's chosen language. To do so, WebSEAL obtains messages from the appropriate language pack, as determined by the locale presented that is by pdadmin. All messages are transmitted in UTF-8, but pdadmin converts those messages to local code page before it displays them. When the local code page is non-UTF-8, data loss is potentially possible. When pdadmin is run in a UTF-8 environment, there is no data loss.WebSEAL generates logging and auditing data by using UTF-8. To prevent possible data loss, use UTF-8 to write the data to the appropriate logging and auditing files. When the local code page is non-UTF-8, data must be converted to non-UTF-8 before it can be written. In this case, the possibility of data loss exists.All log audit files that are generated by WebSEAL are in the language that is specified by the locale in which the server runs. The code page that is used to write the messages is configurable in the WebSEAL routing file. For example, on UNIX and Linux systems, the file is /opt/pdweb/etc/routing.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 data conversion issues

WebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output.

When WebSEAL reads data in, it must convert the data from non-UTF-8 to UTF-8. When WebSEAL writes out data, it must convert the data from UTF-8 to non-UTF-8.

If conversion to a local code page is required, no data loss occurs when it runs in a UTF-8 locale.

The conversion from a UTF-8 locale to a non-UTF-8 locale (local code page) can, in some situations, result in data loss. For example, if WebSEAL is running in an en_US.ISO8859 environment, and a Japanese user name must be converted to the local code page, the result is a string of question marks ("????"). This result occurs because there is no way to represent Japanese characters in ISO-8859-1. For this reason, WebSEAL must be run by using UTF-8.

There is a risk of data loss when it runs administrative commands (pdadmin) from a non-UTF-8 environment. Before version 5.1, WebSEAL always ran in the same locale as the pdadmin utility. With multi-locale support, WebSEAL can now run in a different locale. WebSEAL must return messages to the administrator in the administrator's chosen language. To do so, WebSEAL obtains messages from the appropriate language pack, as determined by the locale presented that is by pdadmin. All messages are transmitted in UTF-8, but pdadmin converts those messages to local code page before it displays them. When the local code page is non-UTF-8, data loss is potentially possible. When pdadmin is run in a UTF-8 environment, there is no data loss.

WebSEAL generates logging and auditing data by using UTF-8. To prevent possible data loss, use UTF-8 to write the data to the appropriate logging and auditing files. When the local code page is non-UTF-8, data must be converted to non-UTF-8 before it can be written. In this case, the possibility of data loss exists.

All log audit files that are generated by WebSEAL are in the language that is specified by the locale in which the server runs. The code page that is used to write the messages is configurable in the WebSEAL routing file. For example, on UNIX and Linux systems, the file is /opt/pdweb/etc/routing.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 impact on authenticationUTF-8 impact on authenticationUTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8authentication impactsauthenticationimpactsUTF-8The following list describes the impact of the usage of UTF-8 for internal data handling.UTF-8 logins over basic authentication are not supported. Use of UTF-8 with basic authentication login is not supported. UTF-8 logins with basic authentication cannot be supported because browsers transmit data in inconsistent ways. WebSEAL does not support multi-byte basic authentication logins because of browser inconsistency.WebSEAL uses basic authentication login strings with the expectation that they are in the local code page. WebSEAL supports 7-bit ASCII and single-byte Latin code pages. For example, a server that wants to allow French users to use basic authentication logins must run in a Latin locale. WebSEAL uses the basic authentication login string and converts it to UTF-8 internally. However, if the French user has a UTF-8 code page, basic authentication login is not available because the login string is multi-byte.Forms login. In previous versions of WebSEAL, forms login data was always used by WebSEAL with the auto function. WebSEAL examined the login data to see whether it was in UTF-8 format. If the data was not in UTF-8 format, the data was processed as local code page. For WebSEAL version 5.1 and greater, this setting is configurable as described in UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms..Cross-domain single signon, e-community single signon, and failover authentication Each of these authentication methods employs encoded tokens. The encoding of these tokens must be configured to use either UTF-8 encoding or non-UTF-8 encoding. Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 impact on authentication

The use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.

The following list describes the impact of the usage of UTF-8 for internal data handling.

UTF-8 logins over basic authentication are not supported.

Use of UTF-8 with basic authentication login is not supported. UTF-8 logins with basic authentication cannot be supported because browsers transmit data in inconsistent ways. WebSEAL does not support multi-byte basic authentication logins because of browser inconsistency.

WebSEAL uses basic authentication login strings with the expectation that they are in the local code page. WebSEAL supports 7-bit ASCII and single-byte Latin code pages. For example, a server that wants to allow French users to use basic authentication logins must run in a Latin locale. WebSEAL uses the basic authentication login string and converts it to UTF-8 internally. However, if the French user has a UTF-8 code page, basic authentication login is not available because the login string is multi-byte.

Forms login.

In previous versions of WebSEAL, forms login data was always used by WebSEAL with the auto function. WebSEAL examined the login data to see whether it was in UTF-8 format. If the data was not in UTF-8 format, the data was processed as local code page.

For WebSEAL version 5.1 and greater, this setting is configurable as described in UTF-8 support in POST body information (forms).

Cross-domain single signon, e-community single signon, and failover authentication

Each of these authentication methods employs encoded tokens. The encoding of these tokens must be configured to use either UTF-8 encoding or non-UTF-8 encoding.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 impact on authorization (dynamic URL)UTF-8 impact on authorization (dynamic URL)UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.UTF-8impact on authorization (dynamic URL)authorization impactUTF-8dyanmic URLThis restriction is important to consider when you enable the WebSEAL dynamic URL feature. WebSEAL dynamic URL processes data from POST bodies and from query strings. Data from both POST bodies and query strings need to be in a character encoding that is known to WebSEAL for successful mapping of character patterns to authorization objects.By design, WebSEAL dynamic URL processes the query string portion of a request, where the dynamic data destined for the web application interface is located. The GET request standard uses this query string format. To support the query string requirement for dynamic URL, WebSEAL converts any data that is contained in the body of a POST request into the query string format.When dynamic URL is enabled, WebSEAL maps the data from query strings to objects that require protection or access control. To securely map query strings to objects, the string data needs to use the same character set known to WebSEAL and the back-end application server. Otherwise, dynamic URL access control might be circumvented by a request that uses a character that is accepted by the back-end application, but not accepted by WebSEAL. If WebSEAL receives dynamic data (in a POST body or query string) by using characters that are not UTF-8 or from the character set in which WebSEAL runs, WebSEAL rejects the request and returns an error.If WebSEAL (with dynamic URL enabled) is running in a non-UTF-8 environment, and request POST bodies or query strings contain UTF-8 characters, you can configure the utf8-form-support-enabled stanza entry in the [server] stanza of the WebSEAL configuration file to allow WebSEAL to decode the UTF-8 coding in these requests. For more information, see Dynamic URLs.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 impact on authorization (dynamic URL)

WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.

This restriction is important to consider when you enable the WebSEAL dynamic URL feature. WebSEAL dynamic URL processes data from POST bodies and from query strings. Data from both POST bodies and query strings need to be in a character encoding that is known to WebSEAL for successful mapping of character patterns to authorization objects.

By design, WebSEAL dynamic URL processes the query string portion of a request, where the dynamic data destined for the web application interface is located. The GET request standard uses this query string format. To support the query string requirement for dynamic URL, WebSEAL converts any data that is contained in the body of a POST request into the query string format.

When dynamic URL is enabled, WebSEAL maps the data from query strings to objects that require protection or access control. To securely map query strings to objects, the string data needs to use the same character set known to WebSEAL and the back-end application server. Otherwise, dynamic URL access control might be circumvented by a request that uses a character that is accepted by the back-end application, but not accepted by WebSEAL. If WebSEAL receives dynamic data (in a POST body or query string) by using characters that are not UTF-8 or from the character set in which WebSEAL runs, WebSEAL rejects the request and returns an error.

If WebSEAL (with dynamic URL enabled) is running in a non-UTF-8 environment, and request POST bodies or query strings contain UTF-8 characters, you can configure the utf8-form-support-enabled stanza entry in the [server] stanza of the WebSEAL configuration file to allow WebSEAL to decode the UTF-8 coding in these requests.

For more information, see Dynamic URLs.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Encoding type usageEncoding type usageEncoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.URLsingle encodingencoding typesencodingURLsWhen URLs contain multiple character encoding types, WebSEAL cannot guarantee the accuracy of the data in the request because the decoded value of the UTF-8 characters might not match the decoded value of the same characters in the local code page. This possible inaccuracy in the data might cause WebSEAL to mistakenly grant unauthorized users access to protected objects.When WebSEAL encounters a URL with multiple character encoding types, the URL is returned as a Bad Request.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Encoding type usage

WebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.

When URLs contain multiple character encoding types, WebSEAL cannot guarantee the accuracy of the data in the request because the decoded value of the UTF-8 characters might not match the decoded value of the same characters in the local code page. This possible inaccuracy in the data might cause WebSEAL to mistakenly grant unauthorized users access to protected objects.

When WebSEAL encounters a URL with multiple character encoding types, the URL is returned as a Bad Request.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 support for uniform resource locatorsUTF-8 support for uniform resource locatorsUTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8supportuniform resource locators (URLs)Browsers are limited to a defined character set that can legally be used in a uniform resource locator (URL). This range is defined to be the printable characters in the ASCII character set (between hex code 0x20 and 0x7e). For languages other than English, and other purposes, characters outside the printable ASCII character set are often required in URLs. These characters can be encoded by using printable characters for transmission and interpretation.The manner in which WebSEAL processes the URLs from browsers can be specified in the WebSEAL configuration file.utf8-url-support-enabled[server] utf8-url-support-enabled = {yes|no|auto}The three possible values are as follows:yes In this mode, WebSEAL recognizes only URI encoded UTF-8 data in URL strings and they are used without modification. These UTF-8 characters are then validated and taken into account when it determines access rights to the URL. WebSEAL supports both raw UTF-8 and URI encoded UTF-8 strings in URLs. In this mode, other encoding techniques are not accepted. This value is the default and is appropriate for most environments.Servers that run in a 7-bit ASCII English locale must use this value.no In this mode, WebSEAL does not recognize UTF-8 format data in URL strings. This setting is used for local code page only. If the string can be validated, it is converted to UTF-8 for internal use. Servers that do not need to process multi-byte input and are running in a single-byte Latin locale, such as French, German, or Spanish, must use this setting.Use this setting when applications and web servers do not function correctly with WebSEAL if UTF-8 support is enabled. These applications might use DBCS (such as Shift-JIS) or other encoding mechanisms in the URL.When you set this value to no, ensure that all junctioned servers do NOT accept UTF-8 format URLs. It is important from a security perspective, that WebSEAL interprets URLs in the same manner as the junctioned servers.auto WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. WebSEAL correctly processes any correctly constructed UTF-8 encoding. If the encoding does not appear to be UTF-8, then the coding is processed as DBCS or Unicode. If a URL has Unicode in the format "%uHHHH", WebSEAL converts it to UTF-8. The rest of the decoding proceeds as if the configuration setting was yes. If the double-byte-encoding option in the [server] stanza is set to yes, WebSEAL converts %HH%HH to UTF-8.Servers running in a single-byte Latin locale that need to process multi-byte strings must use the auto setting.Servers running in a multi-byte locale but that need to support only one language, for example, Japanese can use the auto setting.The following list is a sample deployment strategy.Unless required for content purposes, immediately check and set the default-webseal ACL on existing production deployments to NOT allow unauthenticated r access. This setting limits security exposure to users who have a valid account in the Security Access Manager domain.Ensure that the utf8-url-support-enabled stanza entry is set to the default value of yes.Test your applications. If they function correctly, use this setting.If any applications fail with Bad Request errors, try the application with the utf8-url-support-enabled stanza entry set to no. If this step works, you can deploy with this setting. Ensure, however, that no junctioned web server is configured to accept UTF-8 encoded URLs.If the application continues to have problems, try setting utf8-url-support-enabled to auto.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 support for uniform resource locators

There are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.

Browsers are limited to a defined character set that can legally be used in a uniform resource locator (URL). This range is defined to be the printable characters in the ASCII character set (between hex code 0x20 and 0x7e). For languages other than English, and other purposes, characters outside the printable ASCII character set are often required in URLs. These characters can be encoded by using printable characters for transmission and interpretation.

The manner in which WebSEAL processes the URLs from browsers can be specified in the WebSEAL configuration file.

[server]
utf8-url-support-enabled = {yes|no|auto}

The three possible values are as follows:

yes

In this mode, WebSEAL recognizes only URI encoded UTF-8 data in URL strings and they are used without modification. These UTF-8 characters are then validated and taken into account when it determines access rights to the URL. WebSEAL supports both raw UTF-8 and URI encoded UTF-8 strings in URLs. In this mode, other encoding techniques are not accepted.

This value is the default and is appropriate for most environments.

Servers that run in a 7-bit ASCII English locale must use this value.

no

In this mode, WebSEAL does not recognize UTF-8 format data in URL strings. This setting is used for local code page only. If the string can be validated, it is converted to UTF-8 for internal use.

Servers that do not need to process multi-byte input and are running in a single-byte Latin locale, such as French, German, or Spanish, must use this setting.

Use this setting when applications and web servers do not function correctly with WebSEAL if UTF-8 support is enabled. These applications might use DBCS (such as Shift-JIS) or other encoding mechanisms in the URL.

Note: When you set this value to no, ensure that all junctioned servers do NOT accept UTF-8 format URLs. It is important from a security perspective, that WebSEAL interprets URLs in the same manner as the junctioned servers.

auto

WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. WebSEAL correctly processes any correctly constructed UTF-8 encoding. If the encoding does not appear to be UTF-8, then the coding is processed as DBCS or Unicode.

If a URL has Unicode in the format "%uHHHH", WebSEAL converts it to UTF-8. The rest of the decoding proceeds as if the configuration setting was yes. If the double-byte-encoding option in the [server] stanza is set to yes, WebSEAL converts %HH%HH to UTF-8.

Servers running in a single-byte Latin locale that need to process multi-byte strings must use the auto setting.

Servers running in a multi-byte locale but that need to support only one language, for example, Japanese can use the auto setting.

The following list is a sample deployment strategy.

Unless required for content purposes, immediately check and set the default-webseal ACL on existing production deployments to NOT allow unauthenticated r access. This setting limits security exposure to users who have a valid account in the Security Access Manager domain.

Ensure that the utf8-url-support-enabled stanza entry is set to the default value of yes.

Test your applications. If they function correctly, use this setting.

If any applications fail with Bad Request errors, try the application with the utf8-url-support-enabled stanza entry set to no. If this step works, you can deploy with this setting. Ensure, however, that no junctioned web server is configured to accept UTF-8 encoded URLs.

If the application continues to have problems, try setting utf8-url-support-enabled to auto.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 support in POST body information (forms)UTF-8 support in POST body information (forms)UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8supportutf8-form-support-enabledPOSTbody informationThe forms that provide data to the server are forms that are part of WebSEAL, such as login forms. These forms all declare the character set to be UTF-8. Thus the default value is yes. If an administrator edits these forms and changes the character set to a non-UTF-8 setting, such as a local code page, this configuration setting must be changed. If some forms use UTF-8 and some use a local code page, use the auto value. If all forms are modified to use a non-UTF-8 setting, use the no value.[server] utf8-form-support-enabled = {yes|no|auto}The three possible values are as follows:yes WebSEAL recognizes only UTF-8 encoding in forms and the data is used without modification. These UTF-8 characters are then validated and taken into account when it processes the data. Other encoding techniques are not accepted. When double-byte-encoding is set to yes, Unicode of the form %HH%HH is supported. When a double-byte Unicode character is detected, the entire string must be double-byte encoded. This value is the default value and appropriate for most environments.no WebSEAL does not recognize UTF-8 encoding in forms. Used for local code page only. If the form data can be validated, it is converted to UTF-8 for internal use.auto WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. WebSEAL correctly processes any correctly constructed UTF-8 input. If the encoding does not appear to be UTF-8, then the coding is processed as non-UTF-8.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 support in POST body information (forms)

Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.

The forms that provide data to the server are forms that are part of WebSEAL, such as login forms. These forms all declare the character set to be UTF-8. Thus the default value is yes. If an administrator edits these forms and changes the character set to a non-UTF-8 setting, such as a local code page, this configuration setting must be changed. If some forms use UTF-8 and some use a local code page, use the auto value. If all forms are modified to use a non-UTF-8 setting, use the no value.

[server]
utf8-form-support-enabled = {yes|no|auto}

The three possible values are as follows:

yes

WebSEAL recognizes only UTF-8 encoding in forms and the data is used without modification. These UTF-8 characters are then validated and taken into account when it processes the data. Other encoding techniques are not accepted.

When double-byte-encoding is set to yes, Unicode of the form %HH%HH is supported. When a double-byte Unicode character is detected, the entire string must be double-byte encoded.

This value is the default value and appropriate for most environments.

no

WebSEAL does not recognize UTF-8 encoding in forms. Used for local code page only. If the form data can be validated, it is converted to UTF-8 for internal use.

auto

WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. WebSEAL correctly processes any correctly constructed UTF-8 input. If the encoding does not appear to be UTF-8, then the coding is processed as non-UTF-8.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 support in query strings UTF-8 support in query strings UTF-8 support in query strings You can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8supportquery stringsquery stringsUTF-8 supportutf8-qstring-support-enabledThe default setting is no. Therefore, WebSEAL default behavior is to assume that all query strings are local code page.[server] utf8-qstring-support-enabled = {yes|no|enabled}The three possible values are as follows:yes WebSEAL recognizes only UTF-8 encoding in query strings and the data is used without modification. These UTF-8 characters are then validated and taken into account when it processes the data. Other encoding techniques are not accepted. Use this setting when your WebSEAL server must process query strings that use UTF-8. Servers that operate in a single-byte Latin locale, such as French, German, or Spanish, and process queries from an application that uses UTF-8, must use this setting. Servers that operate in a multi-byte locale and process only UTF-8 query strings can use this setting.no WebSEAL does not recognize UTF-8 encoding in query strings. Used for local code page only. If the form data can be validated, it is converted to UTF-8 for internal use. This setting is the default value, appropriate for most environments. Servers that operate in a 7-bit ASCII English locale can use this setting.auto WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding (DBCS and Unicode). WebSEAL correctly processes any correctly constructed UTF-8 encoding. If the encoding does not appear to be UTF-8, then the coding is processed as DBCS or Unicode. Servers that operate in a multi-byte locale and process a mixture of UTF-8 and non-UTF-8 query strings can use this setting. Servers that operate in a single-byte Latin locale, such as French, German, or Spanish, and process a mixture of UTF-8 and non-UTF-8 query strings can use this setting.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 support in query strings

You can enable UTF-8 support in query strings by editing the WebSEAL configuration file.

The default setting is no. Therefore, WebSEAL default behavior is to assume that all query strings are local code page.

[server]
utf8-qstring-support-enabled = {yes|no|enabled}

The three possible values are as follows:

yes

WebSEAL recognizes only UTF-8 encoding in query strings and the data is used without modification. These UTF-8 characters are then validated and taken into account when it processes the data. Other encoding techniques are not accepted.

Use this setting when your WebSEAL server must process query strings that use UTF-8.

Servers that operate in a single-byte Latin locale, such as French, German, or Spanish, and process queries from an application that uses UTF-8, must use this setting. Servers that operate in a multi-byte locale and process only UTF-8 query strings can use this setting.

no

WebSEAL does not recognize UTF-8 encoding in query strings. Used for local code page only. If the form data can be validated, it is converted to UTF-8 for internal use.

This setting is the default value, appropriate for most environments.

Servers that operate in a 7-bit ASCII English locale can use this setting.

auto

WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding (DBCS and Unicode). WebSEAL correctly processes any correctly constructed UTF-8 encoding. If the encoding does not appear to be UTF-8, then the coding is processed as DBCS or Unicode.

Servers that operate in a multi-byte locale and process a mixture of UTF-8 and non-UTF-8 query strings can use this setting.

Servers that operate in a single-byte Latin locale, such as French, German, or Spanish, and process a mixture of UTF-8 and non-UTF-8 query strings can use this setting.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 encoding of tokens for cross domain single signonUTF-8 encoding of tokens for cross domain single signonUTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8encoding of tokenscross domain single signoncross-domain single signonUTF-8encoding of tokensencodingtokenscross-domain single signonuse-utf8cdsso stanza[cdsso] use-utf8 = {true|false}The default value is true.When use-utf8 is set to false, strings are encoded by using the local code page. Use this value when you implement cross domain single signon with versions of WebSEAL before version 5.1. WebSEAL versions before 5.1 do not use UTF-8 encoding for tokens. When you deploy an environment that includes these older servers, configure WebSEAL to not use UTF-8 encoding. This setting is necessary for compatibility with an earlier version.When this value is set to false, data loss can occur during conversion from UTF-8 to a non-UTF-8 local code page.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 encoding of tokens for cross domain single signon

The use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.

[cdsso]
use-utf8 = {true|false}

The default value is true.

When use-utf8 is set to false, strings are encoded by using the local code page. Use this value when you implement cross domain single signon with versions of WebSEAL before version 5.1. WebSEAL versions before 5.1 do not use UTF-8 encoding for tokens. When you deploy an environment that includes these older servers, configure WebSEAL to not use UTF-8 encoding. This setting is necessary for compatibility with an earlier version.

Note: When this value is set to false, data loss can occur during conversion from UTF-8 to a non-UTF-8 local code page.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 encoding of tokens for e-community single signonUTF-8 encoding of tokens for e-community single signonUTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8encoding of tokense-community single signonencodingtokensUTF-8e-community single signone-community single signonencoding of tokensuse-utf8e-community-sso stanza[e-community-sso] use-utf8 = {yes|no}The default value is yes.When use-utf8 is set to no, strings are encoded by using the local code page. Use this value when you implement an e-community single signon with versions of WebSEAL before version 5.1. WebSEAL versions before 5.1 do not use UTF-8 encoding for tokens. When you deploy an environment that includes these older servers, configure the WebSEAL server to not use UTF-8 encoding. This setting is necessary for compatibility with an earlier version.When this value is set to no, data loss can occur during conversion from UTF-8 to a non-UTF-8 local code page.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 encoding of tokens for e-community single signon

The use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.

[e-community-sso]
use-utf8 = {yes|no}

The default value is yes.

When use-utf8 is set to no, strings are encoded by using the local code page. Use this value when you implement an e-community single signon with versions of WebSEAL before version 5.1. WebSEAL versions before 5.1 do not use UTF-8 encoding for tokens. When you deploy an environment that includes these older servers, configure the WebSEAL server to not use UTF-8 encoding. This setting is necessary for compatibility with an earlier version.

Note: When this value is set to no, data loss can occur during conversion from UTF-8 to a non-UTF-8 local code page.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 encoding of cookies for failover authenticationUTF-8 encoding of cookies for failover authenticationUTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8encoding of cookiesfailover authenticationencodingcookiesfailover authenticationfailover authenticationencoding of cookiesuse-utf8failover stanza[failover] use-utf8 = {yes|no}The default value is yes.When use-utf8 is set to no, failover authentication cookies are encoded by using the local code page. Use this value when you implement failover authentication with versions of WebSEAL before version 5.1. WebSEAL versions before 5.1 do not use UTF-8 encoding for failover authentication cookies. When you deploy an environment that includes these older servers, configure the WebSEAL server to not use UTF-8 encoding. This setting is necessary for compatibility with an earlier version.When this value is set to no, data loss can occur during conversion from UTF-8 to a non-UTF-8 local code page.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 encoding of cookies for failover authentication

You can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.

[failover]
use-utf8 = {yes|no}

The default value is yes.

When use-utf8 is set to no, failover authentication cookies are encoded by using the local code page. Use this value when you implement failover authentication with versions of WebSEAL before version 5.1. WebSEAL versions before 5.1 do not use UTF-8 encoding for failover authentication cookies. When you deploy an environment that includes these older servers, configure the WebSEAL server to not use UTF-8 encoding. This setting is necessary for compatibility with an earlier version.

Note: When this value is set to no, data loss can occur during conversion from UTF-8 to a non-UTF-8 local code page.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 encoding of cookies for LTPA authenticationUTF-8 encoding of cookies for LTPA authenticationUTF-8 encoding of cookies for LTPA authentication in WebSEALWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. LTPAauthenticationUTF-8 encoding for authentication cookiesauthenticationcookiesLTPAUTF-8 encodingUTF-8 encodingDue to this requirement, there is no option to enable or disable UTF-8 encoding for LTPA cookies. LTPA cookies are always UTF-8 encoded.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 encoding of cookies for LTPA authentication

WebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding.

Due to this requirement, there is no option to enable or disable UTF-8 encoding for LTPA cookies. LTPA cookies are always UTF-8 encoded.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

UTF-8 encoding in junction requestsUTF-8 encoding in junction requestsUTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.UTF-8junction requestsjunctionsrequestsutf8_uriutf8_binlcp_urilcp_binWebSEAL inserts information into HTTP headers for requests to the back-end server. This information can include extended attributes or user data. In WebSEAL versions before version 5.1, the headers were added to the request by using the local code page. In WebSEAL version 5.1 and greater, the header data is transmitted in a configurable format. The -e option for creating junctions specifies the encoding of user name, groups, and other extended attributes that are sent within the HTTP header to the back-end server. The encode option can take one of the following arguments:ArgumentDescriptionutf8_uri URI encoded UTF-8 data. All white space and non-ASCII bytes are encoded %XY, where X and Y are hex values (0–F). Encoding applies also to the following entries: ASCII characters below 0x1F and above 0x7FEscape characters for tab, carriage return, and line feedPercent symbolutf8_bin Unencoded UTF-8 data. This setting allows data to be transmitted without data loss, and the user does not need to URI-decode the data. This setting must be used with caution because it is not part of the HTTP specification.lcp_uri URI encoded local code page data. Any UTF-8 characters that cannot be converted to a local code page are converted to question marks (?). Use this option with caution and only in environments where the local code page produces the wanted strings.lcp_bin Unencoded local code page data. This mode was used by versions of WebSEAL before version 5.1. Use of this mode enables migration from previous versions, and is used in upgrade environments. Data loss can potentially occur with this mode. Use with caution.Web server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

UTF-8 encoding in junction requests

By default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.

WebSEAL inserts information into HTTP headers for requests to the back-end server. This information can include extended attributes or user data. In WebSEAL versions before version 5.1, the headers were added to the request by using the local code page. In WebSEAL version 5.1 and greater, the header data is transmitted in a configurable format.

The -e option for creating junctions specifies the encoding of user name, groups, and other extended attributes that are sent within the HTTP header to the back-end server. The encode option can take one of the following arguments:

Argument
Description

utf8_uri

URI encoded UTF-8 data.

All white space and non-ASCII bytes are encoded %XY, where X and Y are hex values (0–F).

Encoding applies also to the following entries:

ASCII characters below 0x1F and above 0x7F

Escape characters for tab, carriage return, and line feed

Percent symbol

utf8_bin

Unencoded UTF-8 data.

This setting allows data to be transmitted without data loss, and the user does not need to URI-decode the data.

This setting must be used with caution because it is not part of the HTTP specification.

lcp_uri

URI encoded local code page data.

Any UTF-8 characters that cannot be converted to a local code page are converted to question marks (?). Use this option with caution and only in environments where the local code page produces the wanted strings.

lcp_bin

Unencoded local code page data.

This mode was used by versions of WebSEAL before version 5.1. Use of this mode enables migration from previous versions, and is used in upgrade environments.

Data loss can potentially occur with this mode. Use with caution.

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Validation of character encoding in request dataValidation of character encoding in request dataValidation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.character encodingvalidating data in requestsencodingvalidating data in requestsdecode-query stanza entryutf8-qstring-support-enabled stanza entryutf8-form-support-enabled stanza entrydynamic URLshandling invalid characters in URL query stringdynamic URLsdisdabledynurl-map stanza entryThe problem of invalid character encoding is also caused by the specific requirements of the back-end server application. In a typical scenario, the client makes a request to this back-end application. The request includes a query string, which is required by the back-end application, that contains character encoding unknown to WebSEAL. WebSEAL rejects the request and returns a Bad Request (400) error. The error log contains a message such as Illegal character in URL.One solution to the problem of incorrect validation of character encoding is to configure WebSEAL to not validate the query string and POST body data of requests. The request data can then be passed unchanged to the back-end application.To instruct WebSEAL to not validate query string and POST body data, set the value of the decode-query stanza entry in the [server] stanza of the WebSEAL configuration file to "no":[server] decode-query = noThe following setting is the default.decode-query = yesIf decode-query is set to yes, WebSEAL validates the query string in requests according to the utf8-qstring-support-enabled stanza entry. See UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.. This setting applies to POST body data in requests when dynamic URL is enabled. Dynamic URL converts the POST body data in a request to query string format. See Conversion of POST body dynamic data to query string format.If decode-query is set to yes, WebSEAL validates the POST body in requests according to the utf8-form-support-enabled stanza entry. See UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms..If you set decode-query=no, you must understand the possible consequences to securing protected objects. In particular, if WebSEAL is configured to not validate query strings in requests (decode-query=no), then dynamic URL mapping for authorization checking, if enabled, must be disabled.To disable the dynamic URL feature, comment out the dynurl-map stanza entry in the [server] stanza of the WebSEAL configuration file:[server] #dynurl-map = bin/dynurl.confWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Validation of character encoding in request data

WebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.

The problem of invalid character encoding is also caused by the specific requirements of the back-end server application. In a typical scenario, the client makes a request to this back-end application. The request includes a query string, which is required by the back-end application, that contains character encoding unknown to WebSEAL. WebSEAL rejects the request and returns a Bad Request (400) error. The error log contains a message such as Illegal character in URL.

One solution to the problem of incorrect validation of character encoding is to configure WebSEAL to not validate the query string and POST body data of requests. The request data can then be passed unchanged to the back-end application.

To instruct WebSEAL to not validate query string and POST body data, set the value of the decode-query stanza entry in the [server] stanza of the WebSEAL configuration file to "no":

[server]
decode-query = no

The following setting is the default.

decode-query = yes

If decode-query is set to yes, WebSEAL validates the query string in requests according to the utf8-qstring-support-enabled stanza entry. See UTF-8 support in query strings. This setting applies to POST body data in requests when dynamic URL is enabled. Dynamic URL converts the POST body data in a request to query string format. See Conversion of POST body dynamic data to query string format.

If decode-query is set to yes, WebSEAL validates the POST body in requests according to the utf8-form-support-enabled stanza entry. See UTF-8 support in POST body information (forms).

If you set decode-query=no, you must understand the possible consequences to securing protected objects. In particular, if WebSEAL is configured to not validate query strings in requests (decode-query=no), then dynamic URL mapping for authorization checking, if enabled, must be disabled.

To disable the dynamic URL feature, comment out the dynurl-map stanza entry in the [server] stanza of the WebSEAL configuration file:

[server]
#dynurl-map = bin/dynurl.conf

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Supported wildcard pattern matching charactersSupported wildcard pattern matching charactersSupported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.wildcard characterspattern matching (wildcard characters)Supported wildcard matching charactersCharacterDescription\ The character that follows the backslash is part of a special sequence. For example, \t is the TAB character. Can be used to escape the other pattern matching characters: ( ? * [ ] ^ ). To match the backslash character, use \\.? Wildcard that matches a single character. For example, the string abcde is matched by the expression ab?de* Wildcard that matches zero or more characters.[] Defines a set of characters, from which any can match. For example, the string abcde is matched with the regular expression ab[cty]de.^ Indicates a negation. For example, the expression [^ab] matches anything but the a or b characters.For more examples of pattern matching by using wildcards, see the following topics.Extended attributes to add to tokenExtended attributes to add to tokenMapping ACL and POP objects to dynamic URLsWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Setting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Supported wildcard pattern matching characters

WebSEAL supports wildcard pattern matching characters.

Table 12. Supported wildcard matching characters

Character
Description

\

The character that follows the backslash is part of a special sequence. For example, \t is the TAB character. Can be used to escape the other pattern matching characters: ( ? * [ ] ^ ). To match the backslash character, use \\.

?

Wildcard that matches a single character. For example, the string abcde is matched by the expression ab?de

*

Wildcard that matches zero or more characters.

[]

Defines a set of characters, from which any can match. For example, the string abcde is matched with the regular expression ab[cty]de.

^

Indicates a negation. For example, the expression [^ab] matches anything but the a or b characters.

For more examples of pattern matching by using wildcards, see the following topics.

Extended attributes to add to token

Extended attributes to add to token

Mapping ACL and POP objects to dynamic URLs

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Setting system environment variables

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Setting system environment variablesSetting system environment variablesSetting system environment variablesUse the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.system-environment-variables stanzaenv-namestanza entrySystem environment variablesThis function is not supported in Windows.The environment variable names are case-sensitive.The following line is the format of each configuration entry.<env-name> = <env-value><env-name> The name of the system environment variable.<env-value> The value of the system environment variable.For example:[system-environment-variables] LANG = deWeb server configurationConfigure the web server capabilities of WebSEAL such as content caching, communication protocol, LDAP directory server, worker thread, and HTTP data compression.Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one.Modifying the configuration file settingsThe operation of the WebSEAL server is controlled by using the WebSEAL configuration file and a corresponding obfuscated file that is used for sensitive data. Use the local management interface to modify the configuration file.Content cachingWebSEAL can cache static web contents to increase the response time of a transaction. You must understand the key concepts, configuration variables, and conditions that affect content caching and the impact of HTTP headers. You can flush all caches and set cache control for specific documents.Communication protocol configurationYou can configure the WebSEAL communication protocols to control how WebSEAL handles requests and creates connections. There are many stanza entries available to configure the communication protocols.IPv4 and IPv6 overviewBeginning with Tivoli Access Manager for Web version 6.0, WebSEAL supports Internet Protocol version 6 (IPv6).Configuring WebSEAL for IPv6 and IPv4 requestsBy default Security Access Manager WebSEAL, version 6.0 or later, supports IPv6 networks. You can configure it to support either IPv4 only or both IPv4 and IPv6. IPv6: Compatibility supportBefore you enable IPv6 support, you must understand how IP version compatibility is maintained for previous versions of Security Access Manager.IPv6: Upgrade notesWhen you upgrade to Security Access Manager WebSEAL version 7.0 from a previous version, IPv6 support is automatically disabled.IP levels for credential attributesNetwork information can be stored as an extended attribute in a user's credential. You can control the amount of network information that is stored in a credential by specifying the required IP level. LDAP directory server configurationWhen Security Access Manager is configured to use an LDAP-based user registry, such as IBMTivoli Directory Server, WebSEAL must be configured as an LDAP client so it can communicate with the LDAP server. WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL.WebSEAL worker threadsWebSEAL draws from its pool of worker threads to process multiple requests. Worker threads handle incoming requests to applications on multiple junctioned back-end servers.Global allocation of worker threads for junctionsYou can modify the entries in the [junction] stanza of the WebSEAL configuration file to control the global allocation of worker threads across all junctions for a particular WebSEAL server. Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.Allocation view of worker threads for junctionsUse the allocation view when you want to determine the location of a junction that is absorbing more than its share of worker thread resources.HTTP data compressionThe WebSEAL servers can be configured to compress data that is transferred over HTTP between the WebSEAL server and the client.WebSEAL data handling by using UTF-8WebSEAL implements multi-locale support by internally maintaining and handling all data by using UCS Transformation Format 8 byte (UTF-8) encoding. UTF-8 is a multi-byte code page with variable width.UTF-8 dependency on user registry configurationFor optimal multi-locale support, store all the users in one common user registry, regardless of which language they prefer.UTF-8 data conversion issuesWebSEAL can be deployed into environments where the local code page uses UTF-8. Similarly, WebSEAL can also be deployed into environments where the local code page does not use UTF-8. The use of WebSEAL with operating system environments that use non-UTF-8 local code pages requires WebSEAL to convert data upon data input and output. UTF-8 impact on authenticationThe use of UTF-8 for internal data handling has impacts on the processing of authentication requests by WebSEAL.UTF-8 impact on authorization (dynamic URL)WebSEAL restricts all requests that require authorization checks to requests that use UTF-8 or the locale setting of the WebSEAL host. All back-end servers are also bound by these settings. WebSEAL must enforce this restriction so it can apply security policy on known protected objects.Encoding type usageWebSEAL requires that any URL presented for processing must contain only a single character encoding type such as UTF-8 or ShiftJIS.UTF-8 support for uniform resource locatorsThere are a number of different encoding methods for transmitting characters outside the printable ASCII range. WebSEAL, acting as a web proxy, must be able to handle all these cases. The UTF-8 locale support addresses this need.UTF-8 support in POST body information (forms)Edit WebSEAL configuration file so that you can configure how WebSEAL processes data in POST bodies that contain information from forms.UTF-8 support in query stringsYou can enable UTF-8 support in query strings by editing the WebSEAL configuration file.UTF-8 encoding of tokens for cross domain single signonThe use of UTF-8 encoding for strings within tokens that are used for cross domain single signon is specified in the WebSEAL configuration file.UTF-8 encoding of tokens for e-community single signonThe use of UTF-8 encoding for strings within tokens that are used for e-community single signon is specified in the WebSEAL configuration file.UTF-8 encoding of cookies for failover authenticationYou can specify the use of UTF-8 encoding for strings within failover authentication cookies in the WebSEAL configuration file.UTF-8 encoding of cookies for LTPA authenticationWebSEAL supports LTPA version 2 cookies only for LTPA authentication. The specification for this version of LTPA cookies requires the use of UTF-8 encoding. UTF-8 encoding in junction requestsBy default, WebSEAL adds information to HTTP headers by using a UTF-8 code page. This action prevents any potential data loss that can occur when it converts to a non-UTF-8 code page. This data is sent URI encoded. For compatibility with an earlier version, the format of the header data can be configured to the local code page. In addition, two other formats are supported, raw UTF-8 and URI encoded local code page.Validation of character encoding in request dataWebSEAL parses requests to ensure that character encoding is compatible with the back-end server requirements. For example, it is possible for the query string of a request to contain character encoding, such as raw binary data, that is unacceptable to WebSEAL, and therefore rejected by WebSEAL.Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.

Setting system environment variables

Use the system-environment-variables stanza to list the system environment variables that the WebSEAL daemon exports during initialization. Include a separate entry for each system environment variable that you want to export.

Note:

This function is not supported in Windows.

The environment variable names are case-sensitive.

The following line is the format of each configuration entry.

<env-name> = <env-value>

<env-name>

The name of the system environment variable.

<env-value>

The value of the system environment variable.

For example:

[system-environment-variables]
LANG = de

Parent topic: Web server configuration

Related concepts:

Content caching

Communication protocol configuration

IPv4 and IPv6 overview

IPv6: Compatibility support

IP levels for credential attributes

LDAP directory server configuration

WebSEAL worker thread configuration

WebSEAL worker threads

Global allocation of worker threads for junctions

Per-junction allocation of worker threads for junctions

HTTP data compression

WebSEAL data handling by using UTF-8

UTF-8 dependency on user registry configuration

UTF-8 data conversion issues

UTF-8 impact on authentication

UTF-8 impact on authorization (dynamic URL)

Encoding type usage

UTF-8 support for uniform resource locators

UTF-8 support in POST body information (forms)

UTF-8 support in query strings

UTF-8 encoding of tokens for cross domain single signon

UTF-8 encoding of tokens for e-community single signon

UTF-8 encoding of cookies for failover authentication

UTF-8 encoding of cookies for LTPA authentication

UTF-8 encoding in junction requests

Validation of character encoding in request data

Related tasks:

Specifying the WebSEAL host name

Modifying the configuration file settings

Configuring WebSEAL for IPv6 and IPv4 requests

Related reference:

IPv6: Upgrade notes

Allocation view of worker threads for junctions

Supported wildcard pattern matching characters

Web server response configurationWeb server response configurationWebSEAL serversresponsesweb serversresponsesThis chapter discusses the resources available to the WebSEAL server for responding to client requests.Topic Index:ConfigurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirection

Web server response configuration

This chapter discusses the resources available to the WebSEAL server for responding to client requests.

Topic Index:

Static HTML server response pages
WebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests.

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration
When WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.

Multi-locale support for server responses

Handling the favicon.ico file with Mozilla Firefox

Adding custom headers to server response pages
You can add headers, which contain information about a custom response, to generated server responses.

Configuring the location URL format in redirect responses

Local response redirection

HTML redirection

Parent topic: Configuration

Static HTML server response pages Static HTML server response pages WebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTMLserver response pagesstaticserver response pagesHTMLstaticresponsesserverHTML pagesacct_locked.htmlcertfailure.htmlcertlogin.htmlcertstepuphttp.htmldefault.htmldeletesuccess.htmlhelp.htmllogin.htmllogin_success.htmllogout.htmlnexttoken.htmlpasswd.htmlpasswd_exp.htmlpasswd_rep.htmlpasswd_warn.htmlputsuccess.htmlquery_contents.htmlrelocated.htmlstepuplogin.htmlswitchuser.htmltemplate.htmltokenlogin.htmltoo_many_sessions.htmlwebsealerror.htmlThese pages include:Error messagesInformational messagesLogin formsPassword management formsYou can modify the contents of these pages to include site-specific messages or perform site-specific actions. Most pages are appropriate for forms and basic authentication over HTTP or HTTPS.The names, content, and descriptions of the HTML message pages are listed in the following table. The following codes are used to indicate the message type:ER - error messageIN - informational messageLG - login formPW - password management formNA - not applicableFilenameStatus and HTTP CodeDescriptionType132120c8.html Authentication Failed (HTTP 403) Credentials cannot be retrieved for the client certificate used. Possible reasons include: The user supplied an incorrect certificate.The user's credentials are missing from the authentication database. ER38ad52fa.html Non-empty Directory (HTTP 500) The requested operation requires the removal of a non-empty directory. The requested operation is an illegal operation. ER38b9a4b0.html Application Server is Offline (HTTP 503) The application server you are accessing has been taken offline by the system administrator. Returned when a request is blocked due to a junction that has been placed in a throttled or offline operational state. ER38b9a4b1.html Service Unavailable (HTTP 503) The WebSEAL server is unable to service a request because a needed resource is unavailable. ER38b9a41f.html Additional Login Denied (HTTP 200) You have already logged in to this Web server from another client. No more new logins are permitted until your initial session has ended. ER38cf013d.html Request Caching Failed (HTTP 500)The request-max-cache or request-body-max-read values have been exceeded. ER38cf0259.html Could Not Sign User On (HTTP 500) The resource requested requires the WebSEAL server to sign the user on to another Web server. However, a problem occurred while WebSEAL was attempting to retrieve the information. ER38cf025a.html User Has No Single Signon Information (HTTP 500) WebSEAL could not locate the GSO user for the requested resource. ER38cf025b.html No Single Signon Target for User (HTTP 500) WebSEAL could not locate the GSO target for the requested resource. ER38cf025c.html Multiple Signon Targets for User (HTTP 500) Multiple GSO targets are defined for the requested resource. This is an incorrect configuration. ER38cf025d.html Login Required (HTTP 500) The resource requested is protected by a junctioned back-end Web server, requiring WebSEAL to sign the user on to that Web server. In order to do this, user must first log in to WebSEAL. ER38cf025e.html Could Not Sign User On (HTTP 500) The resource requested requires WebSEAL to sign the user on to another Web server. However, the signon information for the user account is incorrect. ER38cf025f.html Unexpected Authentication Challenge (HTTP 500) WebSEAL received an unexpected authentication challenge from a junctioned back-end Web server. ER38cf0421.html Moved Temporarily (HTTP 302) The requested resource has been temporarily moved. This event usually occurs if there has been a mishandled redirect. ER38cf0424.html Bad Request (HTTP 400) WebSEAL received an HTTP request that is not valid. ER38cf0425.html Login Required (HTTP 401) The resource you have requested is secured by WebSEAL, and in order to access it, you must first log in. ER38cf0427.html Forbidden (HTTP 403) The user does not have permissions to access the requested resource. ER38cf0428.html Not Found (HTTP 404) The requested resource cannot be located. ER38cf0432.html Service Unavailable (HTTP 503) A service required by WebSEAL to complete the request is currently not available. ER38cf0434.html Privacy required (HTTP 403) Quality of protection at the privacy level is required. ER38cf0437.html Server Suspended (HTTP 500) The WebSEAL server has been temporarily suspended by the System Administrator. No requests will be handled until the server is returned to service by the administrator. ER38cf0439.html Session Information Lost (HTTP 500) The browser and server interaction was a stateful session with a junctioned back-end server that is no longer responding. WebSEAL requires a service located on this server to complete your request. ER38cf0442.html Service Unavailable (HTTP 503) The service required by WebSEAL is located on a junctioned back-end server where SSL mutual authentication has failed. ER38cf04c6.html Third-party server not responding (HTTP 500) The requested resource is located on a third-party server. WebSEAL has tried to contact that server, but the server is not responding. ER38cf04d7.html Third-party server not responding (HTTP 500) The requested resource is located on a third-party server. WebSEAL has tried to contact that server, but the server is not responding. ER38cf07aa.html CGI Program Failed (HTTP 500) A CGI program failed to execute properly. ER38cf08cc.html Access Denied (HTTP 403) The resource you have requested is protected by a policy that restricts access to specific time periods. The current time is outside of those permitted time periods. ERacct_locked.html Account locked (HTTP 200) Page displayed in these circumstances: Authentication failed because the user's account was temporarily locked due after too many unsuccessful login attempts.nsAccountLock is true for a user (in Sun Directory Server) when they attempt to login. This is only displayed if the user provides the correct password during login. When using basic authentication (BA-auth) with Security Access Manager, the acct_locked.html file cannot be customized to contain additional images. Although you can embed images in the file, subsequent requests to access the embedded images will fail. ERcertfailure.html Certification authentication failed (HTTP 200) An attempt to authenticate with a client certificate failed. Page displayed if client fails to authenticate with a certificate when accept-client-certs = required. A valid client certificate is required to make this connection. ERcertlogin.html Access Manager Login (HTTP 200) Certificate login form used when accept-client-certs = prompt_as_needed. LGcertstepuphttp.html Attempt to Step-up to Certification authentication failed (HTTP 200) An attempt to step-up to certificates over HTTP failed. Use of HTTPS is required. Try re-accessing the page over HTTPS. ERdefault.html Server Error (HTTP 500) WebSEAL could not complete your request due to an unexpected error. ERdeletesuccess.html Success (HTTP 200) The client-initiated DELETE request completed successfully. INhelp.html PKMS Administration (HTTP 200)Help information for pkmslogout and pkmspasswd. INlogin.html Access Manager Login (HTTP 200) Standard request form for user name and password LGlogin_success.html Success (HTTP 200) Normally, WebSEAL caches the URL of the requested resource, and returns the resource to the user upon successful login. The login_success.html page is displayed after successful login if for some reason WebSEAL cannot determine the URL of the originally requested resource. INlogout.html PKMS Administration: User Log Out (HTTP 200) Page displayed after successful logout. User USERNAME has logged out. INpasswd.html PKMS Administration: Change Password (HTTP 200) Change password form. Also displayed if password change request failed. PWpasswd_exp.html PKMS Administration: Expired Password (HTTP 200) Page displayed if user authentication failed due to an expired password. Change expired password. PWpasswd_rep.html PKMS Administration: Change Password (HTTP 200) Page displayed if password change request was successful. PWpasswd_warn.html Password Administration The password will expire at approximately... (HTTP 200) Page displayed if user LDAP password is due to expire soon. PWputsuccess.html Success (HTTP 200) The client-initiated PUT operation completed successfully. INquery_contents.html Junctioning Win32 Web Servers (HTTP 200) Installation and configuration information for making a junction from an Access Manager WebSEAL server to third-party Web servers running on the Win32 platform. INrelocated.html Temporarily Moved (HTTP 302) The requested resource has temporarily moved. INstepuplogin.html Access Manager Step Up Login (HTTP 200) Login form for step-up authentication. LGswitchuser.html Access Manager Switch User (HTTP 200) Login form for switch user. LGtemplate.html Template Template form for custom error messages. NAtoo_many_sessions.html PKMS Administration: Session Displacement (HTTP xxx) Error message when exceeding the limit of concurrent logins by a single user. ERwebsealerror.html WebSEAL Server Error (HTTP 400) WebSEAL server internal error. ERWeb server response configurationHTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirection

Static HTML server response pages

WebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests.

These pages include:

Error messages

Informational messages

Login forms

Password management forms

You can modify the contents of these pages to include site-specific messages or perform site-specific actions. Most pages are appropriate for forms and basic authentication over HTTP or HTTPS.

The names, content, and descriptions of the HTML message pages are listed in the following table. The following codes are used to indicate the message type:

ER - error message

IN - informational message

LG - login form

PW - password management form

NA - not applicable

Filename
Status and HTTP Code
Description
Type

132120c8.html

Authentication Failed

(HTTP 403)

Credentials cannot be retrieved for the client certificate used. Possible reasons include:

The user supplied an incorrect certificate.

The user's credentials are missing from the authentication database.

ER

38ad52fa.html

Non-empty Directory

(HTTP 500)

The requested operation requires the removal of a non-empty directory. The requested operation is an illegal operation.

ER

38b9a4b0.html

Application Server

is Offline

(HTTP 503)

The application server you are accessing has been taken offline by the system administrator. Returned when a request is blocked due to a junction that has been placed in a throttled or offline operational state.

ER

38b9a4b1.html

Service Unavailable

(HTTP 503)

The WebSEAL server is unable to service a request because a needed resource is unavailable.

ER

38b9a41f.html

Additional Login Denied

(HTTP 200)

You have already logged in to this Web server from another client. No more new logins are permitted until your initial session has ended.

ER

38cf013d.html

Request Caching Failed

(HTTP 500)

The request-max-cache or request-body-max-read values have been exceeded.

ER

38cf0259.html

Could Not Sign User On

(HTTP 500)

The resource requested requires the WebSEAL server to sign the user on to another Web server. However, a problem occurred while WebSEAL was attempting to retrieve the information.

ER

38cf025a.html

User Has No Single

Signon Information

(HTTP 500)

WebSEAL could not locate the GSO user for the requested resource.

ER

38cf025b.html

No Single Signon

Target for User

(HTTP 500)

WebSEAL could not locate the GSO target for the requested resource.

ER

38cf025c.html

Multiple Signon

Targets for User

(HTTP 500)

Multiple GSO targets are defined for the requested resource. This is an incorrect configuration.

ER

38cf025d.html

Login Required

(HTTP 500)

The resource requested is protected by a junctioned back-end Web server, requiring WebSEAL to sign the user on to that Web server. In order to do this, user must first log in to WebSEAL.

ER

38cf025e.html

Could Not Sign User On

(HTTP 500)

The resource requested requires WebSEAL to sign the user on to another Web server. However, the signon information for the user account is incorrect.

ER

38cf025f.html

Unexpected Authentication

Challenge

(HTTP 500)

WebSEAL received an unexpected authentication challenge from a junctioned back-end Web server.

ER

38cf0421.html

Moved Temporarily

(HTTP 302)

The requested resource has been temporarily moved. This event usually occurs if there has been a mishandled redirect.

ER

38cf0424.html

Bad Request

(HTTP 400)

WebSEAL received an HTTP request that is not valid.

ER

38cf0425.html

Login Required

(HTTP 401)

The resource you have requested is secured by WebSEAL, and in order to access it, you must first log in.

ER

38cf0427.html

Forbidden

(HTTP 403)

The user does not have permissions to access the requested resource.

ER

38cf0428.html

Not Found

(HTTP 404)

The requested resource cannot be located.

ER

38cf0432.html

Service Unavailable

(HTTP 503)

A service required by WebSEAL to complete the request is currently not available.

ER

38cf0434.html

Privacy required

(HTTP 403)

Quality of protection at the privacy level is required.

ER

38cf0437.html

Server Suspended

(HTTP 500)

The WebSEAL server has been temporarily suspended by the System Administrator. No requests will be handled until the server is returned to service by the administrator.

ER

38cf0439.html

Session Information Lost

(HTTP 500)

The browser and server interaction was a stateful session with a junctioned back-end server that is no longer responding. WebSEAL requires a service located on this server to complete your request.

ER

38cf0442.html

Service Unavailable

(HTTP 503)

The service required by WebSEAL is located on a junctioned back-end server where SSL mutual authentication has failed.

ER

38cf04c6.html

Third-party server

not responding

(HTTP 500)

The requested resource is located on a third-party server. WebSEAL has tried to contact that server, but the server is not responding.

ER

38cf04d7.html

Third-party server

not responding

(HTTP 500)

The requested resource is located on a third-party server. WebSEAL has tried to contact that server, but the server is not responding.

ER

38cf07aa.html

CGI Program Failed

(HTTP 500)

A CGI program failed to execute properly.

ER

38cf08cc.html

Access Denied

(HTTP 403)

The resource you have requested is protected by a policy that restricts access to specific time periods. The current time is outside of those permitted time periods.

ER

acct_locked.html

Account locked

(HTTP 200)

Page displayed in these circumstances:

Authentication failed because the user's account was temporarily locked due after too many unsuccessful login attempts.

nsAccountLock is true for a user (in Sun Directory Server) when they attempt to login. This is only displayed if the user provides the correct password during login.

Note: When using basic authentication (BA-auth) with Security Access Manager, the acct_locked.html file cannot be customized to contain additional images. Although you can embed images in the file, subsequent requests to access the embedded images will fail.

ER

certfailure.html

Certification authentication

failed

(HTTP 200)

An attempt to authenticate with a client certificate failed. Page displayed if client fails to authenticate with a certificate when accept-client-certs = required. A valid client certificate is required to make this connection.

ER

certlogin.html

Access Manager Login

(HTTP 200)

Certificate login form used when accept-client-certs = prompt_as_needed.

LG

certstepuphttp.html

Attempt to Step-up to

Certification authentication

failed

(HTTP 200)

An attempt to step-up to certificates over HTTP failed. Use of HTTPS is required. Try re-accessing the page over HTTPS.

ER

default.html

Server Error

(HTTP 500)

WebSEAL could not complete your request due to an unexpected error.

ER

deletesuccess.html

Success

(HTTP 200)

The client-initiated DELETE request completed successfully.

IN

help.html

PKMS Administration

(HTTP 200)

Help information for pkmslogout and pkmspasswd.

IN

login.html

Access Manager Login

(HTTP 200)

Standard request form for user name and password

LG

login_success.html

Success

(HTTP 200)

Normally, WebSEAL caches the URL of the requested resource, and returns the resource to the user upon successful login. The login_success.html page is displayed after successful login if for some reason WebSEAL cannot determine the URL of the originally requested resource.

IN

logout.html

PKMS Administration: User

Log Out

(HTTP 200)

Page displayed after successful logout. User USERNAME has logged out.

IN

passwd.html

PKMS Administration:

Change Password

(HTTP 200)

Change password form. Also displayed if password change request failed.

PW

passwd_exp.html

PKMS Administration:

Expired Password

(HTTP 200)

Page displayed if user authentication failed due to an expired password. Change expired password.

PW

passwd_rep.html

PKMS Administration:

Change Password

(HTTP 200)

Page displayed if password change request was successful.

PW

passwd_warn.html

Password Administration

The password will expire

at approximately...

(HTTP 200)

Page displayed if user LDAP password is due to expire soon.

PW

putsuccess.html

Success

(HTTP 200)

The client-initiated PUT operation completed successfully.

IN

query_contents.html

Junctioning Win32 Web

Servers

(HTTP 200)

Installation and configuration information for making a junction from an Access Manager WebSEAL server to third-party Web servers running on the Win32 platform.

IN

relocated.html

Temporarily Moved

(HTTP 302)

The requested resource has temporarily moved.

IN

stepuplogin.html

Access Manager

Step Up Login

(HTTP 200)

Login form for step-up authentication.

LG

switchuser.html

Access Manager

Switch User

(HTTP 200)

Login form for switch user.

LG

template.html

Template

Template form for custom error messages.

NA

too_many_sessions.html

PKMS Administration:

Session Displacement

(HTTP xxx)

Error message when exceeding the limit of concurrent logins by a single user.

ER

websealerror.html

WebSEAL Server Error

(HTTP 400)

WebSEAL server internal error.

ER

Parent topic: Web server response configuration

Related concepts:

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

HTML server response page locationsHTML server response page locationsHTMLserver response pagespage locationsFor storage location purposes on the WebSEAL server, static HTML server response pages are grouped into three general categories:Account management pagesError message pagesJunction-specific static server response pagesThe location of these three storage categories is configurable, as described in the following sections:Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirectionManagement RootOn the appliance, you can use the local management interface to access the Management Root file structure. Account management page locationAccount management pages include login forms, password management forms, and some informational messages.Error message page locationJunction-specific static server response pagesYou can customize static server response pages on a per-junction basis.

HTML server response page locations

For storage location purposes on the WebSEAL server, static HTML server response pages are grouped into three general categories:

Account management pages

Error message pages

Junction-specific static server response pages

The location of these three storage categories is configurable, as described in the following sections:

Management Root
On the appliance, you can use the local management interface to access the Management Root file structure.

Account management page location
Account management pages include login forms, password management forms, and some informational messages.

Error message page location

Junction-specific static server response pages
You can customize static server response pages on a per-junction basis.

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page modification

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Management RootOn the appliance, you can use the local management interface to access the Management Root file structure. notationManage Reverse Proxy Management Root pageLMIManage Reverse Proxy Management Root pageReverse Proxy management pageReverse Proxy management pagepath namesdirectorynamesnotationmanagementdirectoryerrorsdirectoryOAuthdirectoryjunction-root directoryThe file structure is available on the Manage Reverse Proxy Management Root page for each instance. To open this Management Root page and access the file structure from the LMI web interface, you must: Select Secure Web Settings > Manage > Reverse Proxy from the top menu. The Reverse Proxy management page displays.Click the instance that you want to manage from the available list of Instance Names. Select Manage > Management root. The Manage Reverse Proxy Management Root page for the selected instance displays with the available file structure.The available directories include:managementerrorsoauthjunction-rootHTML server response page locations

Management Root

On the appliance, you can use the local management interface to access the Management Root file structure.

The file structure is available on the Manage Reverse Proxy Management Root page for each instance. To open this Management Root page and access the file structure from the LMI web interface, you must:

Select Secure Web Settings > Manage > Reverse Proxy from the top menu. The Reverse Proxy management page displays.

Click the instance that you want to manage from the available list of Instance Names.

Select Manage > Management root. The Manage Reverse Proxy Management Root page for the selected instance displays with the available file structure.

The available directories include:

management

errors

oauth

junction-root

Parent topic: HTML server response page locations

Account management page locationAccount management page locationAccount management pages include login forms, password management forms, and some informational messages.HTMLserver response pagesaccount management page locationsserver response pagesHTMLaccount management page locationmgt-pages-root stanza entryYou can use the LMI to access the account management pages. Open the management directory on the Manage Reverse Proxy Management Root page. Pages are located in language-specific subdirectories at this location. The subdirectory specific to your locale is automatically appended to the end of the directory hierarchy during WebSEAL installation and configuration.The default United States English directory is: management/CThe Japanese locale directory is: management/JPSee Multi-locale support for server responses for further information on multi-locale support.HTML server response page locations

Account management page location

Account management pages include login forms, password management forms, and some informational messages.

You can use the LMI to access the account management pages. Open the management directory on the Manage Reverse Proxy Management Root page. Pages are located in language-specific subdirectories at this location. The subdirectory specific to your locale is automatically appended to the end of the directory hierarchy during WebSEAL installation and configuration.

The default United States English directory is:

management/C

The Japanese locale directory is:

management/JP

See Multi-locale support for server responses for further information on multi-locale support.

Parent topic: HTML server response page locations

Error message page locationError message page locationHTMLserver response pageserror page locationserver response pagesHTMLerror page locationerror-dir stanza entryPages are in language-specific subdirectories of the errors directory. You can access these directories from the Manage Reverse Proxy Management Root page. The subdirectory specific to your locale is automatically appended to the end of the directory hierarchy during WebSEAL installation and configuration.The default United States English directory is: errors/CThe Japanese locale directory is: errors/JPSee Multi-locale support for server responses for further information on multi-locale support.For information on creating junction-specific static server response pages, see Junction-specific static server response pagesYou can customize static server response pages on a per-junction basis..HTML server response page locations

Error message page location

Pages are in language-specific subdirectories of the errors directory. You can access these directories from the Manage Reverse Proxy Management Root page. The subdirectory specific to your locale is automatically appended to the end of the directory hierarchy during WebSEAL installation and configuration.

The default United States English directory is:

errors/C

The Japanese locale directory is:

errors/JP

See Multi-locale support for server responses for further information on multi-locale support.

For information on creating junction-specific static server response pages, see Junction-specific static server response pages.

Parent topic: HTML server response page locations

Junction-specific static server response pagesJunction-specific static server response pagesYou can customize static server response pages on a per-junction basis.junctionsstatic server response pagesstatic server response pagesjunction-specificcustomizingper-junctionAdd the customized static server response page files into a junction-specific directory: errors/language/junction_idwhere junction_id refers to the junction point for a standard junction (excluding the leading / character) or the virtual host label for a virtual host junction. For example: errors/C/test_junctionWebSEAL searches for static server response page files in the following sequence, returning the first file found to the client:errors/language/junction_id/page.html errors/language/junction_id/default.html errors/language/page.html errors/language/default.html You can use the / character in the junction name. For example, if you created a junction directory named test under the jct directory, the junction is specified as /jct/test. In this instance WebSEAL searches for files in the errors/language/jct/test directory. HTML server response page locations

Junction-specific static server response pages

You can customize static server response pages on a per-junction basis.

Add the customized static server response page files into a junction-specific directory:

errors/language/junction_id

where junction_id refers to the junction point for a standard junction (excluding the leading / character) or the virtual host label for a virtual host junction. For example:

errors/C/test_junction

WebSEAL searches for static server response page files in the following sequence, returning the first file found to the client:

errors/language/junction_id/page.html

errors/language/junction_id/default.html

errors/language/page.html

errors/language/default.html

You can use the / character in the junction name. For example, if you created a junction directory named test under the jct directory, the junction is specified as /jct/test. In this instance WebSEAL searches for files in the errors/language/jct/test directory.

Parent topic: HTML server response page locations

HTML server response page modificationHTML server response page modificationlogin formscustomizeformslogincustomizeloginsformscustomizationThis section contains the following topics:Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirectionGuidelines for customizing HTML response pagesMacro resources for customizing HTML response pagesMacros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages. Macros embedded in a templateAdding an image to a custom login form

HTML server response page modification

This section contains the following topics:

Guidelines for customizing HTML response pages

Macro resources for customizing HTML response pages
Macros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages.

Macros embedded in a template

Adding an image to a custom login form

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Guidelines for customizing HTML response pages Guidelines for customizing HTML response pages HTMLserver response pagescustomize guidelinesserver response pagesHTMLcustomize guidelinesYou can customize the static HTML server response pages to better reflect your current WebSEAL implementation. Observe the following notes: Do not modify the name of the file. The hexadecimal number is used by WebSEAL to display the proper error file.Use an HTML or text editor to modify page contents. Ensure that you use valid HTML tagging.Specify server-relative URIs (rather than relative URIs) for any URIs for resources such as images or CSS. If virtual host junctions are being used for WebSEAL, you must use absolute URIs for such resources.WebSEAL supplies a set of macros that you can use to capture dynamic information. See Macro resources for customizing HTML response pagesMacros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages. .HTML server response page modification

Guidelines for customizing HTML response pages

You can customize the static HTML server response pages to better reflect your current WebSEAL implementation. Observe the following notes:

Do not modify the name of the file. The hexadecimal number is used by WebSEAL to display the proper error file.

Use an HTML or text editor to modify page contents. Ensure that you use valid HTML tagging.

Specify server-relative URIs (rather than relative URIs) for any URIs for resources such as images or CSS. If virtual host junctions are being used for WebSEAL, you must use absolute URIs for such resources.

WebSEAL supplies a set of macros that you can use to capture dynamic information. See Macro resources for customizing HTML response pages.

Parent topic: HTML server response page modification

Macro resources for customizing HTML response pages Macro resources for customizing HTML response pages Macro resources for customizing HTML response pages in IBM Security Access Manager for WebMacros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages. HTMLserver response pagesmacro resourcesserver response pagesHTMLmacro resourcesmacrossupportHTML server response pagesHTML server response pagesOLDSESSIONBACK_NAMEAUTHNLEVELCERTAUTHNBASICAUTHNBACK_URLERROR_TEXTERROR_CODEERROREXPIRE_SECSHOSTNAMEFAILREASONEAIAUTHNUSERNAMEURL_ENCODEDURLTOKENAUTHNREFERERREFERER_ENCODEDSTEPUPPROTOCOLMETHODLOCATIONHTTP_BASEHTTPS_BASEWhen WebSEAL responds with a static HTML page, it parses the page and searches for occurrences of macros. When a macro is found, the appropriate content is dynamically substituted. Macros are populated only when the value is relevant to that page.For example, WebSEAL returns a static server response page in response to a request that results in an error. If WebSEAL encounters the ERROR macro in the static server response page, WebSEAL substitutes a string representation of the error code that was generated when handling the request.The following macros occur in some of the static HTML server response pages provided by WebSEAL, and are available for use in customizing these pages:MacroDescriptionAUTHNLEVELSubstitutes the authentication level used in authentication strength policy (step-up).BACK_NAME Substitutes the value "BACK" if a referer header is present in the request, or "NONE" if no referer header is present in the request.BACK_URL Substitutes the value of the referer header from the request, or "/" if none.BASICAUTHNUsed to control the display of information in the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.CERTAUTHNUsed to control the display of information in the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.CREDATTR{name}The value of the user credential attribute that has the specified name. For example, CREDATTR{tagvalue_session_index} returns the session token.EAIAUTHNUsed to control the display of information in the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.ERROR The hard-coded error message returned from Security Access Manager. Same as ERROR_TEXT. Both macros exist for compatibility with prior versions of WebSEAL.ERROR_CODE The numeric value of the error code.ERROR_TEXT The text associated with an error code in the message catalog. Same as ERROR. Both macros exist for compatibility with prior versions of WebSEAL.EXPIRE_SECS Contains the numbers of seconds before the password expires. This can be submitted into the password warning form (passwd_warn.html) to display the time left the user has to change their password.FAILREASONError message.HOSTNAME Fully qualified host name.HTTP_BASE Base HTTP URL of the server "http://host:tcpport/".HTTPS_BASE Base HTTPS URL of the server, "https://host:sslport/".HTTPHDR{name} Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro will contain the text: ’Unknown’. For example, the macro name to include the ’Host’ HTTP header would be HTTPHDR{Host}.LOCATIONContains the URL to which the client is being redirected. Sent only in redirects.METHOD The HTTP method requested by the client.OLDSESSION When WebSEAL receives a user request that contains an old ("stale") session cookie that no longer matches any existing entry in the WebSEAL session cache, the macro (normally set to "0") is set to the value of "1". The macro is set whenever WebSEAL sees a session cookie that is not recognized. Unrecognized session cookies can occur, for example, during session timeouts, session displacement, and when a user switches WebSEAL servers. Used in the standard WebSEAL login form to provide a trigger mechanism for a customized response to the user. This custom response could more accurately explain to the user why the session is not valid anymore. See Customized responses for old session cookies.PROTOCOLThe client connection protocol used. Can be HTTP or HTTPS.REFERER The value of the HTTP referer header from the request, or "Unknown", if none.REFERER_ENCODEDA URI encoded version of the HTTP referer header and macro.STEPUPA message specifying the step-up level required. Only sent when returning a step-up login formURL The URL requested by the client.URL_ENCODEDA URI encoded version of the URI and macro.USERNAME The name of the user responsible for the request. (See also Customization of login forms for reauthenticationWebSEAL supports reauthentication for both forms authentication methods..)HTML server response page modificationMacro data string format

Macro resources for customizing HTML response pages

Macros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages.

When WebSEAL responds with a static HTML page, it parses the page and searches for occurrences of macros. When a macro is found, the appropriate content is dynamically substituted. Macros are populated only when the value is relevant to that page.

For example, WebSEAL returns a static server response page in response to a request that results in an error. If WebSEAL encounters the ERROR macro in the static server response page, WebSEAL substitutes a string representation of the error code that was generated when handling the request.

The following macros occur in some of the static HTML server response pages provided by WebSEAL, and are available for use in customizing these pages:

Macro
Description

AUTHNLEVEL
Substitutes the authentication level used in authentication strength policy (step-up).

BACK_NAME

Substitutes the value "BACK" if a referer header is present in the request, or "NONE" if no referer header is present in the request.

BACK_URL

Substitutes the value of the referer header from the request, or "/" if none.

BASICAUTHN
Used to control the display of information in the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.

CERTAUTHN
Used to control the display of information in the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.

CREDATTR{name}
The value of the user credential attribute that has the specified name. For example, CREDATTR{tagvalue_session_index} returns the session token.

EAIAUTHN
Used to control the display of information in the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.

ERROR

The hard-coded error message returned from Security Access Manager.

Same as ERROR_TEXT. Both macros exist for compatibility with prior versions of WebSEAL.

ERROR_CODE

The numeric value of the error code.

ERROR_TEXT

The text associated with an error code in the message catalog.

Same as ERROR. Both macros exist for compatibility with prior versions of WebSEAL.

EXPIRE_SECS

Contains the numbers of seconds before the password expires.

This can be submitted into the password warning form (passwd_warn.html) to display the time left the user has to change their password.

FAILREASON
Error message.

HOSTNAME

Fully qualified host name.

HTTP_BASE

Base HTTP URL of the server "http://host:tcpport/".

HTTPS_BASE

Base HTTPS URL of the server, "https://host:sslport/".

HTTPHDR{name}

Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro will contain the text: ’Unknown’.

For example, the macro name to include the ’Host’ HTTP header would be HTTPHDR{Host}.

LOCATION
Contains the URL to which the client is being redirected. Sent only in redirects.

METHOD

The HTTP method requested by the client.

OLDSESSION

When WebSEAL receives a user request that contains an old ("stale") session cookie that no longer matches any existing entry in the WebSEAL session cache, the macro (normally set to "0") is set to the value of "1". The macro is set whenever WebSEAL sees a session cookie that is not recognized. Unrecognized session cookies can occur, for example, during session timeouts, session displacement, and when a user switches WebSEAL servers.

Used in the standard WebSEAL login form to provide a trigger mechanism for a customized response to the user. This custom response could more accurately explain to the user why the session is not valid anymore.

See Customized responses for old session cookies.

PROTOCOL
The client connection protocol used. Can be HTTP or HTTPS.

REFERER

The value of the HTTP referer header from the request, or "Unknown", if none.

REFERER_ENCODED
A URI encoded version of the HTTP referer header and macro.

STEPUP
A message specifying the step-up level required. Only sent when returning a step-up login form

URL

The URL requested by the client.

URL_ENCODED
A URI encoded version of the URI and macro.

USERNAME

The name of the user responsible for the request.

(See also Customization of login forms for reauthentication.)

Macro data string format

Parent topic: HTML server response page modification

Macro data string formatMacro data string formatHTMLserver response pagesmacro data string formatserver response pagesHTMLmacro data string formatUTF-8HTML macrosutf8-template-macros-enabled stanza entryWebSEAL provides a configuration stanza entry that specifies the format of macro data strings that are inserted into HTML server response pages. The default setting specifies UTF-8 format.[content] utf8-template-macros-enabled = yesStatic HTML server response pages use a UTF-8 character set by default. If you modify the character set to specify the local code page, set this entry to “no”.Note that this setting affects the pages that are generated by WebSEAL, as defined in the [acnt-mgt] stanza of the WebSEAL configuration file.Macro resources for customizing HTML response pagesMacros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages.

Macro data string format

WebSEAL provides a configuration stanza entry that specifies the format of macro data strings that are inserted into HTML server response pages. The default setting specifies UTF-8 format.

[content]
utf8-template-macros-enabled = yes

Static HTML server response pages use a UTF-8 character set by default. If you modify the character set to specify the local code page, set this entry to “no”.

Note that this setting affects the pages that are generated by WebSEAL, as defined in the [acnt-mgt] stanza of the WebSEAL configuration file.

Parent topic: Macro resources for customizing HTML response pages

Macros embedded in a templateMacros embedded in a templatemacrosembedding in templatetemplatesembedding macrosSecurity Access Manager verifies macro values before embedding the macros in templates, but additional changes might be necessary in some customer environments, depending on how the templates have been customized. Macros used in Security Access Manager templates are either URL macros or non-URL macros. URL macros are used to represent URLs, such as the HTTP request URL and the referer URL. Non-URL macros are used to represent other values, such as user names and error messages.The following macros are URL macros: %LOCATION%%URL%%REFERER%%BACK_URL%%HOSTNAME%%HTTP_BASE%%HTTPS_BASE%%REFERER_ENCODED%%URL_ENCODED%All other macros used in Security Access Manager are non-URL macros.HTML server response page modificationHow Security Access Manager encodes macrosSecurity Access Manager encodes macros before embedding the macros in an HTML template. Use of macros in a templateHTML tags and attributesUse of JavaScript to work with macros

Macros embedded in a template

Security Access Manager verifies macro values before embedding the macros in templates, but additional changes might be necessary in some customer environments, depending on how the templates have been customized. Macros used in Security Access Manager templates are either URL macros or non-URL macros. URL macros are used to represent URLs, such as the HTTP request URL and the referer URL. Non-URL macros are used to represent other values, such as user names and error messages.

The following macros are URL macros:

%LOCATION%

%URL%

%REFERER%

%BACK_URL%

%HOSTNAME%

%HTTP_BASE%

%HTTPS_BASE%

%REFERER_ENCODED%

%URL_ENCODED%

All other macros used in Security Access Manager are non-URL macros.

How Security Access Manager encodes macros
Security Access Manager encodes macros before embedding the macros in an HTML template.

Use of macros in a template

HTML tags and attributes

Use of JavaScript to work with macros

Parent topic: HTML server response page modification

How Security Access Manager encodes macrosHow Security Access Manager encodes macrosSecurity Access Manager encodes macros before embedding the macros in an HTML template. Security Access ManagermacrosmacrosencodingEncoding ensures that macro values are interpreted as text and not JavaScript or HTML meta-characters. URL macros are encoded as Uniform Resource Identifier (URI) characters. For example, the left bracket (<) character in a URL is converted to %3c during encoding. Non-URL macros are encoded using HTML entities. For example, left (<) and right (>) bracket characters are encoded as &lt; and &gt;, respectively. Other HTML meta-characters in non-URL macros are encoded using numeric character references. For example, a double quotation mark (") is rendered as &#34;. Security Access Manager encodes the following characters in both URL and non-URL macros: Characters encoded in URL and non-URL macrosCommon NameCharacter or Descriptionless-than symbol<greater-than symbol>colon:apostrophe'quotation mark"backslash\All values less than ASCII 0x20Examples include escape, tab, carriage return, newline, formfeed, backspace, null byte.In addition, Security Access Manager encodes the ampersand (&) character in non-URL macros.Access Manger verifies that all URL macros except HOSTNAME are either absolute or server-relative URLs and use either HTTP or HTTPS protocol. The HOSTNAME macro must contain only alpha-numeric ASCII characters, dots, and hyphens.Macros embedded in a template

How Security Access Manager encodes macros

Security Access Manager encodes macros before embedding the macros in an HTML template.

Encoding ensures that macro values are interpreted as text and not JavaScript or HTML meta-characters. URL macros are encoded as Uniform Resource Identifier (URI) characters. For example, the left bracket (<) character in a URL is converted to %3c during encoding. Non-URL macros are encoded using HTML entities. For example, left (<) and right (>) bracket characters are encoded as &lt; and &gt;, respectively. Other HTML meta-characters in non-URL macros are encoded using numeric character references. For example, a double quotation mark (") is rendered as &#34;.

Security Access Manager encodes the following characters in both URL and non-URL macros:

Table 13. Characters encoded in URL and non-URL macros

Common Name | Character or Description
less-than symbol | <
greater-than symbol | >
colon | :
apostrophe | '
quotation mark | "
backslash | \
All values less than ASCII 0x20 | Examples include escape, tab, carriage return, newline, formfeed, backspace, null byte.

In addition, Security Access Manager encodes the ampersand (&) character in non-URL macros.

Access Manger verifies that all URL macros except HOSTNAME are either absolute or server-relative URLs and use either HTTP or HTTPS protocol. The HOSTNAME macro must contain only alpha-numeric ASCII characters, dots, and hyphens.

Parent topic: Macros embedded in a template

Use of macros in a templateUse of macros in a templatemacrostemplatestemplatesmacrosCaution must be exercised when embedding macros in HTML templates to avoid introducing cross-site scripting vulnerabilities to the Security Access Manager environment. Use the following guidelines when embedding macros: URL macros may be safely used as HTML text. To use a macro as HTML text, embed the macro between HTML tags. For example: <b>%URL%</b>URL macros may be safely used as HTML attribute values for HTML attributes, but only for attribute values that are intended for use with URLs. When using macros as HTML attribute values, the macro must be surrounded by double or single-quotes. For example: <a href="%URL%">clickable link</a>URL macros may be safely used as JavaScript string values, but must be surrounded by double or single-quotes. For example: var url = '%URL%';Non-URL macros may be safely used as HTML text. To use a macro as HTML text, embed the macro between HTML tags. For example: <b>%USERNAME%</b>Non-URL macros may be safely used as HTML attribute values, but only for attribute values that are NOT intended for use with URLs. When using macros as HTML attribute values, the macro must be surrounded by double or single-quotes. For example: <input type="text" name="user" value="%USERNAME%">Non-URL macros may be safely used as JavaScript string values, but must be surrounded by double or single-quotes. For example: var user = '%USERNAME%';Macros embedded in a template

Use of macros in a template

Caution must be exercised when embedding macros in HTML templates to avoid introducing cross-site scripting vulnerabilities to the Security Access Manager environment. Use the following guidelines when embedding macros:

URL macros may be safely used as HTML text. To use a macro as HTML text, embed the macro between HTML tags. For example:

<b>%URL%</b>

URL macros may be safely used as HTML attribute values for HTML attributes, but only for attribute values that are intended for use with URLs. When using macros as HTML attribute values, the macro must be surrounded by double or single-quotes. For example:

<a href="%URL%">clickable link</a>

URL macros may be safely used as JavaScript string values, but must be surrounded by double or single-quotes. For example:

var url = '%URL%';

Non-URL macros may be safely used as HTML text. To use a macro as HTML text, embed the macro between HTML tags. For example:

<b>%USERNAME%</b>

Non-URL macros may be safely used as HTML attribute values, but only for attribute values that are NOT intended for use with URLs. When using macros as HTML attribute values, the macro must be surrounded by double or single-quotes. For example:

<input type="text" name="user" value="%USERNAME%">

Non-URL macros may be safely used as JavaScript string values, but must be surrounded by double or single-quotes. For example:

var user = '%USERNAME%';

Parent topic: Macros embedded in a template

HTML tags and attributesHTML tags and attributesHTMLtagsattributesattributesHTMLBoth URL and non-URL macros can be safely used with most basic HTML tags. However, there are certain HTML tags and attributes that use special syntax that is different from typical HTML tags. For example, the content of <style> tags is interpreted as cascading style sheet rather than typical HTML. Security Access Manager macros are encoded for use with typical HTML tags and attributes and should not be used within tags whose content is not interpreted as HTML. In general, there is no reason to include Security Access Manager macros in HTML tags whose contents do not follow typical HTML syntax. If you are unsure of the syntax used by particular HTML tags, refer to W3C HTML specifications and your Web browser documentation for additional information. Note also that non-URL macros such as %USERNAME% should not be used as HTML attribute values for attributes that are intended for URLs. Using non-URL macros as URLs can introduce cross-site scripting vulnerabilities in your deployed Security Access Manager environment.Macros embedded in a template

HTML tags and attributes

Both URL and non-URL macros can be safely used with most basic HTML tags. However, there are certain HTML tags and attributes that use special syntax that is different from typical HTML tags. For example, the content of <style> tags is interpreted as cascading style sheet rather than typical HTML. Security Access Manager macros are encoded for use with typical HTML tags and attributes and should not be used within tags whose content is not interpreted as HTML.

In general, there is no reason to include Security Access Manager macros in HTML tags whose contents do not follow typical HTML syntax. If you are unsure of the syntax used by particular HTML tags, refer to W3C HTML specifications and your Web browser documentation for additional information.

Note also that non-URL macros such as %USERNAME% should not be used as HTML attribute values for attributes that are intended for URLs. Using non-URL macros as URLs can introduce cross-site scripting vulnerabilities in your deployed Security Access Manager environment.

Parent topic: Macros embedded in a template

Use of JavaScript to work with macrosUse of JavaScript to work with macrosmacrosJavaScriptJavaScriptworking with macrosThere are two methods of using JavaScript to work with Security Access Manager macros. You can use macros as JavaScript strings or you can use JavaScript to work with the HTML Document Object Model (DOM). To use a macro as a JavaScript string, simply insert the macro name between double or single quotes. For example: var username = "%USERNAME%"; When using a macro as a JavaScript string, be aware that the macro value may contain URI encoding or HTML entity encoding. You can use the JavaScript unescape() function to remove URI encoding from macro values.The recommended method for removing HTML entity encoding is to use JavaScript to work with the HTML DOM. For example, the following HTML code can be used to remove entity encoding from the %USERNAME% macro: <span id='user' style='visibility: hidden'>%USERNAME%</span> <script> var user = document.getElementById('user'); if (user && user.firstChild) { var name = user.firstChild.nodeValue; } </script> The name variable contains the contents of the %USERNAME% macro; you can then use the variable as needed. However, use caution to avoid introducing DOM-based cross-site scripting vulnerabilities to the HTML template pages when using macro values.Macros embedded in a template

Use of JavaScript to work with macros

There are two methods of using JavaScript to work with Security Access Manager macros. You can use macros as JavaScript strings or you can use JavaScript to work with the HTML Document Object Model (DOM). To use a macro as a JavaScript string, simply insert the macro name between double or single quotes. For example:

var username = "%USERNAME%";

When using a macro as a JavaScript string, be aware that the macro value may contain URI encoding or HTML entity encoding. You can use the JavaScript unescape() function to remove URI encoding from macro values.

The recommended method for removing HTML entity encoding is to use JavaScript to work with the HTML DOM. For example, the following HTML code can be used to remove entity encoding from the %USERNAME% macro:

<span id='user' style='visibility: hidden'>%USERNAME%</span>
<script>
	var user = document.getElementById('user');
	if (user && user.firstChild)
		{
		var name = user.firstChild.nodeValue;
		}
</script>

The name variable contains the contents of the %USERNAME% macro; you can then use the variable as needed. However, use caution to avoid introducing DOM-based cross-site scripting vulnerabilities to the HTML template pages when using macro values.

Parent topic: Macros embedded in a template

Adding an image to a custom login formAdding an image to a custom login formlogin formsadding an imageformsloginadding an imageHTMLserver response pagesadding an imageserver response pagesHTMLadding an imagecustomizing login formsadding an image When you customize a server response page, such as a login form, you can add images (graphics) to the page or form. Perform the following steps:Place the image file in an appropriate subdirectory under junction-root. You can use the LMI to manage this directory. Go to the Manage Reverse Proxy Management Root page.A suggested location for the image might be:junction-root/icons You can use HTML code similar to the following example to describe the image in the custom login form:<image src="/icons/logo.jpg" alt="Company Logo">Ensure the definition of the image's file format is listed in the [content-mime-types] of the WebSEAL configuration file. For example:[content-mime-types] jpg = image/jpegCreate an ACL that allows unauthenticated access to logo.jpg. Since this is the login page, there is no user ID established at the point of access. Therefore you must allow unauthenticated access to the image file object or directory object containing the image (such as the icons directory). The minimum permission required are "Tr" for both Unauthenticated and Any-other. For example:pdadmin> acl show icons-acl ACL name: icons-acl Description: Entries: Any-other Tr Unauthenticated Tr User sec_master TcmdbsvaBRrlNote: When setting the permissions on the Unauthenticated ACL entry, you must have as a minimum the same permissions as the Any-other ACL entry. For this example, attach this ACL explicitly to the icons directory (or ensure that the unauthenticated permission is inherited to this point). For example:pdadmin> acl attach /WebSEAL/abc.ibm.com-default/icons icons-aclHTML server response page modification

Adding an image to a custom login form

About this task

When you customize a server response page, such as a login form, you can add images (graphics) to the page or form. Perform the following steps:

Procedure

Place the image file in an appropriate subdirectory under junction-root. You can use the LMI to manage this directory. Go to the Manage Reverse Proxy Management Root page. A suggested location for the image might be:

junction-root/icons

You can use HTML code similar to the following example to describe the image in the custom login form:

<image src="/icons/logo.jpg" alt="Company Logo">

Ensure the definition of the image's file format is listed in the [content-mime-types] of the WebSEAL configuration file. For example:

[content-mime-types]
jpg = image/jpeg

Create an ACL that allows unauthenticated access to logo.jpg. Since this is the login page, there is no user ID established at the point of access. Therefore you must allow unauthenticated access to the image file object or directory object containing the image (such as the icons directory). The minimum permission required are "Tr" for both Unauthenticated and Any-other. For example:

pdadmin> acl show icons-acl
ACL name: icons-acl
Description:
Entries:
   Any-other Tr
   Unauthenticated Tr
   User sec_master TcmdbsvaBRrl

Note: When setting the permissions on the Unauthenticated ACL entry, you must have as a minimum the same permissions as the Any-other ACL entry.

For this example, attach this ACL explicitly to the icons directory (or ensure that the unauthenticated permission is inherited to this point). For example:

pdadmin> acl attach /WebSEAL/abc.ibm.com-default/icons icons-acl

Parent topic: HTML server response page modification

Account management page configurationAccount management page configurationmanagementpagesaccountsmanagement pagesThis section contains the following topics:Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirectionConfiguration file stanza entries and valuesThe following HTML response page stanza entries and values are located in the [acnt-mgt] stanza of the WebSEAL configuration file. Some pages are used only by the Forms login method of providing identity information. Configuration of the account expiration error messageConfiguration of the password policy options

Account management page configuration

This section contains the following topics:

Configuration file stanza entries and values
The following HTML response page stanza entries and values are located in the [acnt-mgt] stanza of the WebSEAL configuration file. Some pages are used only by the Forms login method of providing identity information.

Configuration of the account expiration error message

Configuration of the password policy options

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Error message page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Configuration file stanza entries and valuesConfiguration file stanza entries and valuesThe following HTML response page stanza entries and values are located in the [acnt-mgt] stanza of the WebSEAL configuration file. Some pages are used only by the Forms login method of providing identity information. HTMLserver response pagesvaluesconfiguration file entriesserver response pagesHTMLconfiguration file entriesvalueslogin stanza entry (login form)login-success stanza entrylogout stanza entryaccount-locked stanza entrypasswd-expired stanza entrypasswd-change stanza entrypasswd-change-success stanza entrypasswd-change-failure stanza entryhelptoken-login stanza entrynext-token stanza entrystepup-login stanza entryswitch-user stanza entrycert-failure stanza entrycertificate-login stanza entrycert-stepup-http stanza entryeai-auth-error stanzatoo-many-sessions stanza entryredirect stanza entryStanza EntryHTML Response PageUsagelogin =login.htmlForms loginlogin-success =login_success.htmlForms loginlogout =logout.htmlForms loginaccount-inactivated =acct_locked.htmlAny methodaccount-locked =acct_locked.htmlAny methodpasswd-expired =passwd_exp.htmlAny methodpasswd-change = passwd.htmlAny methodpasswd-change-success = passwd_rep.htmlAny methodpasswd-change-failure = passwd.htmlAny methodpasswd-warn = passwd_warn.htmlAny methodpasswd-warn-failure = passwd_warn.htmlAny methodhelp = help.htmlAny methodcertificate-login =certlogin.htmlCertificate logincert-stepup-http =certstepuphttp.htmlCertificate loginstepup-login = stepuplogin.htmlStep-up authenticationswitch-user = switchuser.htmlAny methodcert-failure = certfailure.htmlCertificate logineai-auth-error = eaiautherror.htmlExternal authentication interface login error pagetoo-many-sessions = too_many_sessions.htmlToo many concurrent sessions error pagehtml-redirect = redirect.htmlHTML redirectionAccount management page configuration

Configuration file stanza entries and values

The following HTML response page stanza entries and values are located in the [acnt-mgt] stanza of the WebSEAL configuration file. Some pages are used only by the Forms login method of providing identity information.

Stanza Entry | HTML Response Page | Usage
login = | login.html | Forms login
login-success = | login_success.html | Forms login
logout = | logout.html | Forms login
account-inactivated = | acct_locked.html | Any method
account-locked = | acct_locked.html | Any method
passwd-expired = | passwd_exp.html | Any method
passwd-change = | passwd.html | Any method
passwd-change-success = | passwd_rep.html | Any method
passwd-change-failure = | passwd.html | Any method
passwd-warn = | passwd_warn.html | Any method
passwd-warn-failure = | passwd_warn.html | Any method
help = | help.html | Any method
certificate-login = | certlogin.html | Certificate login
cert-stepup-http = | certstepuphttp.html | Certificate login
stepup-login = | stepuplogin.html | Step-up authentication
switch-user = | switchuser.html | Any method
cert-failure = | certfailure.html | Certificate login
eai-auth-error = | eaiautherror.html | External authentication interface login error page
too-many-sessions = | too_many_sessions.html | Too many concurrent sessions error page
html-redirect = | redirect.html | HTML redirection

Parent topic: Account management page configuration

Configuration of the account expiration error messageConfiguration of the account expiration error messageHTMLserver response pagesconfiguration of account expiration error messageserver response pagesHTMLconfigure account expiration error messagesaccountsexpiration account-expiry-notification stanza entryWebSEAL returns an error message to a user when a login attempt fails. The message is conveyed through the ERROR macro contained in the appropriate account management page returned to the user. The generic error message ("Login failed") applies to a variety of situations where the user has supplied authentication information that is not valid, such as an incorrect user name or password. You can use the account-expiry-notification stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file to control whether additional information is revealed in the error message when the login failure is due to an expired account.The default "no" setting allows only the generic error message ("Login failed") to be returned when the user login fails due to an expired user account:[acnt-mgt] account-expiry-notification = noA "yes" setting for the account-expiry-notification stanza entry allows a more detailed error message to be returned when the user login fails due to an expired user account. This more detailed error message ("Account expired") indicates the exact reason for the failure (an expired account):[acnt-mgt] account-expiry-notification = yesNote that the "Account expired" message implies that the correct user name is being used. This level of information might be considered a security exposure in some environments.Account management page configuration

Configuration of the account expiration error message

WebSEAL returns an error message to a user when a login attempt fails. The message is conveyed through the ERROR macro contained in the appropriate account management page returned to the user. The generic error message ("Login failed") applies to a variety of situations where the user has supplied authentication information that is not valid, such as an incorrect user name or password.

You can use the account-expiry-notification stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file to control whether additional information is revealed in the error message when the login failure is due to an expired account.

The default "no" setting allows only the generic error message ("Login failed") to be returned when the user login fails due to an expired user account:

[acnt-mgt]
account-expiry-notification = no

A "yes" setting for the account-expiry-notification stanza entry allows a more detailed error message to be returned when the user login fails due to an expired user account. This more detailed error message ("Account expired") indicates the exact reason for the failure (an expired account):

[acnt-mgt]
account-expiry-notification = yes

Note that the "Account expired" message implies that the correct user name is being used. This level of information might be considered a security exposure in some environments.

Parent topic: Account management page configuration

Configuration of the password policy optionsConfiguration of the password policy optionsHTMLserver response pagesconfiguration of password policy optionsserver response pagesHTMLconfigure password policy optionspasswordpolicy configurationexpirationpasswd-warn stanza entrypasswd-warn-failure stanza entryenable-passwd-warn stanza entryaccount-inactivated stanza entryThe following WebSEAL options are available in the [acnt-mgt] stanza to use the password policy and account state for LDAP users. [acnt-mgt] enable-passwd-warn = yes passwd-warn = passwd_warn.html passwd-warn-failure = passwd_warn.html account-inactivated = acct_locked.htmlThese options have no effect unless the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes) and is supported for the particular LDAP registry type.The enable-passwd-warn stanza entry enables WebSEAL to detect the attribute REGISTRY_PASSWORD_EXPIRE_TIME added to a user's credential when the LDAP password policy indicates that the user's password is soon to expire. The value of this new attribute is the number of seconds until the user's password expires. If this attribute is detected, a password warning form will be displayed when the user logs in to WebSEAL.The page macro EXPIRE_SECS is available containing the number of seconds before the password expires. You can use this macro in the password warning form to display the time left for the user to change his password.The account-inactivated stanza entry specifies a page to display if the value of nsAccountLock is true for a user in the Sun Directory when he attempts to log in. This page is only displayed if the user provides the correct password during login. The passwd-warn stanza entry specifies the page to display after login if WebSEAL detects the LDAP password is soon to expire.The passwd-warn-failure stanza entry specifies the page to display if the user fails to change his password that is due to expire. This page is often the same as the one specified by the passwd-warn stanza entry to give the users another chance to change their password. Pages specified by the passwd-warn and passwd-warn-failure entries must provide a (hidden) field called warn when posting to the /pkmspasswd.form. Keep the value of the warn field short, as the value is ignored. The /pkmspasswd.form management URL detects this hidden field and proceeds to use the warning versions of the password change page. If the warn field is not detected then the non-warning forms are used instead. <input type="HIDDEN" name="warn" value="*">You can use the /pkmsskip WebSEAL Management URL to allow the passwd-warn page to skip changing the password and continue on with the login. This URL effectively redirects the users to the page that they were originally trying to access before being interrupted by the login process.You can use the local response redirect options: passwd_warn, passwd_warn_failure, and acct_inactivated. See Operation for local response redirectionWhen WebSEAL receives a client request, it determines the appropriate operation required in response to the request. for more information.Account management page configuration

Configuration of the password policy options

The following WebSEAL options are available in the [acnt-mgt] stanza to use the password policy and account state for LDAP users.

[acnt-mgt]
enable-passwd-warn = yes
passwd-warn = passwd_warn.html
passwd-warn-failure = passwd_warn.html
account-inactivated = acct_locked.html

These options have no effect unless the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes) and is supported for the particular LDAP registry type.

The enable-passwd-warn stanza entry enables WebSEAL to detect the attribute REGISTRY_PASSWORD_EXPIRE_TIME added to a user's credential when the LDAP password policy indicates that the user's password is soon to expire. The value of this new attribute is the number of seconds until the user's password expires. If this attribute is detected, a password warning form will be displayed when the user logs in to WebSEAL.

The page macro EXPIRE_SECS is available containing the number of seconds before the password expires. You can use this macro in the password warning form to display the time left for the user to change his password.

The account-inactivated stanza entry specifies a page to display if the value of nsAccountLock is true for a user in the Sun Directory when he attempts to log in. This page is only displayed if the user provides the correct password during login.

The passwd-warn stanza entry specifies the page to display after login if WebSEAL detects the LDAP password is soon to expire.

The passwd-warn-failure stanza entry specifies the page to display if the user fails to change his password that is due to expire. This page is often the same as the one specified by the passwd-warn stanza entry to give the users another chance to change their password.

Pages specified by the passwd-warn and passwd-warn-failure entries must provide a (hidden) field called warn when posting to the /pkmspasswd.form. Keep the value of the warn field short, as the value is ignored. The /pkmspasswd.form management URL detects this hidden field and proceeds to use the warning versions of the password change page. If the warn field is not detected then the non-warning forms are used instead.

<input type="HIDDEN" name="warn" value="*">

You can use the /pkmsskip WebSEAL Management URL to allow the passwd-warn page to skip changing the password and continue on with the login. This URL effectively redirects the users to the page that they were originally trying to access before being interrupted by the login process.

You can use the local response redirect options: passwd_warn, passwd_warn_failure, and acct_inactivated. See Operation for local response redirection for more information.

Parent topic: Account management page configuration

Error message page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.error message pageconfigurationfailed requestserror message page configurationThe error message pages are installed when the WebSEAL instance is configured. Each error message page is a separate static HTML file. The names of the files are the hexadecimal values of the returned error codes. Do not modify these file names. You must specify server-relative URIs (rather than relative URIs) for any URIs for resources such as images or CSS. If virtual host junctions are being used for WebSEAL, you must use absolute URIs for such resources.This section contains the following topics:Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationMulti-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirectionEnabling the time of day error pageCreating new HTML error message pagesCompatibility with previous versions of WebSEAL

Error message page configuration

When WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.

The error message pages are installed when the WebSEAL instance is configured. Each error message page is a separate static HTML file. The names of the files are the hexadecimal values of the returned error codes. Do not modify these file names.

Note: You must specify server-relative URIs (rather than relative URIs) for any URIs for resources such as images or CSS. If virtual host junctions are being used for WebSEAL, you must use absolute URIs for such resources.

This section contains the following topics:

Enabling the time of day error page

Creating new HTML error message pages

Compatibility with previous versions of WebSEAL

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Account management page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Enabling the time of day error pageEnabling the time of day error pageHTMLserver response pagesenabling the time of day error pageserver response pagesHTMLenabling the time of day error pageclient-notify-todThe 38cf08cc.html error message page is used when access is denied because a protected object policy (POP) time of day policy was not satisfied. WebSEAL controls the use of this error message page through a configuration file setting. To enable WebSEAL to display 38cf08cc.html, you must set the following entry in the WebSEAL configuration file: [acnt-mgt] client-notify-tod = yes When client-notify-tod = yes, WebSEAL sends the client an error message stating that the authorization failure was due to a failed time-of-day POP access check. This entry is set to “no” by default. A 403 error is always logged, regardless of the value assigned to client-notify-tod.Error message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.

Enabling the time of day error page

About this task

The 38cf08cc.html error message page is used when access is denied because a protected object policy (POP) time of day policy was not satisfied. WebSEAL controls the use of this error message page through a configuration file setting.

To enable WebSEAL to display 38cf08cc.html, you must set the following entry in the WebSEAL configuration file:

[acnt-mgt]
client-notify-tod = yes

When client-notify-tod = yes, WebSEAL sends the client an error message stating that the authorization failure was due to a failed time-of-day POP access check.

This entry is set to “no” by default.

Note: A 403 error is always logged, regardless of the value assigned to client-notify-tod.

Parent topic: Error message page configuration

Creating new HTML error message pagesCreating new HTML error message pagesHTMLserver response pagescreating new HTML error message pagesserver response pagesHTMLcreate new HTML error message pages You can create new error message pages for hexadecimal errors returned by WebSEAL. The hexadecimal errors returned by WebSEAL are documented in the IBM Security Access Manager Error messages section in the Knowledge Center. For example, when WebSEAL encounters an invalid HTTP header, it returns the following error: wand_s_jct_invalid_http_header 0x38cf04d5 To create a new error message page for this error, complete the following steps:Create a new HTML file. To name the file, delete the 0x (hex) prefix characters from the error number and supply the .html suffix. For example, 0x38cf04d5 becomes:38cf04d5.htmlOptionally, you can use one of the existing HTTP error files as a template. Copy it and rename it.Consult the Error messages section in the Knowledge Center for information about the exact error encountered. Use this information to edit the body of the HTML page.Optionally, you can use the macros described in Macro resources for customizing HTML response pagesMacros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages. .Save the new file in the same directory as the rest of the HTTP error messages. If you want to create customized error message pages for a specific junction, you must place the customized HTML files in a junction-specific location. For more information, see Junction-specific static server response pagesYou can customize static server response pages on a per-junction basis..Error message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.

Creating new HTML error message pages

About this task

You can create new error message pages for hexadecimal errors returned by WebSEAL. The hexadecimal errors returned by WebSEAL are documented in the IBM Security Access Manager Error messages section in the Knowledge Center.

For example, when WebSEAL encounters an invalid HTTP header, it returns the following error:

wand_s_jct_invalid_http_header              0x38cf04d5

To create a new error message page for this error, complete the following steps:

Procedure

Create a new HTML file. To name the file, delete the 0x (hex) prefix characters from the error number and supply the .html suffix. For example, 0x38cf04d5 becomes:

38cf04d5.html

Optionally, you can use one of the existing HTTP error files as a template. Copy it and rename it.

Consult the Error messages section in the Knowledge Center for information about the exact error encountered. Use this information to edit the body of the HTML page.

Optionally, you can use the macros described in Macro resources for customizing HTML response pages.

Save the new file in the same directory as the rest of the HTTP error messages.

Results

If you want to create customized error message pages for a specific junction, you must place the customized HTML files in a junction-specific location. For more information, see Junction-specific static server response pages.

Parent topic: Error message page configuration

Compatibility with previous versions of WebSEALCompatibility with previous versions of WebSEALHTMLserver response pagescompatibility with previous versions of WebSEALserver response pagesHTMLcompatibility with previous versions of WebSEALbackward compatibilityWebSEAL version 5.1 introduced the following new error pages:38cf04d7.html38cf04c6.htmlThese messages provide information indicating that the encountered failure originated with a back-end server, not with WebSEAL. In past releases, WebSEAL returned the default error page only. If you want to retain the previous behavior, remove the new error message pages from the error message page directory.Error message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.

Compatibility with previous versions of WebSEAL

WebSEAL version 5.1 introduced the following new error pages:

38cf04d7.html

38cf04c6.html

These messages provide information indicating that the encountered failure originated with a back-end server, not with WebSEAL.

In past releases, WebSEAL returned the default error page only. If you want to retain the previous behavior, remove the new error message pages from the error message page directory.

Parent topic: Error message page configuration

Multi-locale support for server responsesMulti-locale support for server responsesHTMLserver response pagesmulti-locale supportserver response pagesHTMLmulti-locale supportmulti-locale supportserver responsesStandard WebSEAL server responses to client browsers, such as error messages, custom HTML login and logout pages, and serviceability messages, can be delivered in the preferred language of the client.This section contains the following topics: Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Handling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirectionThe accept-language HTTP headerProcess flow for multi-locale supportConditions affecting multi-locale support on WebSEAL

Multi-locale support for server responses

Standard WebSEAL server responses to client browsers, such as error messages, custom HTML login and logout pages, and serviceability messages, can be delivered in the preferred language of the client.

This section contains the following topics:

The accept-language HTTP header

Process flow for multi-locale support

Conditions affecting multi-locale support on WebSEAL

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

The accept-language HTTP headerThe accept-language HTTP headermulti-locale supportAccept-Language HTTP headerAccept-Language HTTP headerHTTPheadersAccept-LanguageWebSEAL supports multi-locale capabilities by using the values that are contained in the Accept-Language HTTP header to determine the correct language for server-generated messages and HTML pages. The Accept-Language header can include more than one language. Each additional language is separated by a comma. For example:accept-language: es-mx,es,enThe order in which the values appear in the header determines the hierarchy of importance. WebSEAL checks the first listed value to see whether it is a supported language. If it is not a supported language, WebSEAL checks the next language in the list. If no supported languages are found, WebSEAL defaults to English. The Accept-Language header can use a "q=x.x" attribute to express a preference level for a language. This attribute is not recognized by WebSEAL. The listed order of languages in the header determines the order of priority for WebSEAL.Multi-locale support for server responses

The accept-language HTTP header

WebSEAL supports multi-locale capabilities by using the values that are contained in the Accept-Language HTTP header to determine the correct language for server-generated messages and HTML pages.

The Accept-Language header can include more than one language. Each additional language is separated by a comma. For example:

accept-language: es-mx,es,en

The order in which the values appear in the header determines the hierarchy of importance. WebSEAL checks the first listed value to see whether it is a supported language. If it is not a supported language, WebSEAL checks the next language in the list. If no supported languages are found, WebSEAL defaults to English.

Note: The Accept-Language header can use a "q=x.x" attribute to express a preference level for a language. This attribute is not recognized by WebSEAL. The listed order of languages in the header determines the order of priority for WebSEAL.

Parent topic: Multi-locale support for server responses

Process flow for multi-locale supportProcess flow for multi-locale supportmulti-locale supportprocess flowprocess flowmulti-locale supportThe following example process flow illustrates how WebSEAL evaluates the Accept-Language header:The Accept-Language header contains pt-br as the first value in the list.The pt-br language is converted to pt_BR, representing the WebSEAL language subdirectory for this language.If this subdirectory does not exist for the required message (for example, no language pack is installed for this language), WebSEAL checks for a pt directory.If no pt directory exists, WebSEAL attempts to find message subdirectories for the next language listed in the header.If there are no installed language packs for all languages listed in the header, WebSEAL defaults to the language environment that WebSEAL is running in, as determined by the LC_ALL or LANG environment variables set in the operating system's environment when WebSEAL is started.Multi-locale support for server responses

Process flow for multi-locale support

The following example process flow illustrates how WebSEAL evaluates the Accept-Language header:

The Accept-Language header contains pt-br as the first value in the list.

The pt-br language is converted to pt_BR, representing the WebSEAL language subdirectory for this language.

If this subdirectory does not exist for the required message (for example, no language pack is installed for this language), WebSEAL checks for a pt directory.

If no pt directory exists, WebSEAL attempts to find message subdirectories for the next language listed in the header.

If there are no installed language packs for all languages listed in the header, WebSEAL defaults to the language environment that WebSEAL is running in, as determined by the LC_ALL or LANG environment variables set in the operating system's environment when WebSEAL is started.

Parent topic: Multi-locale support for server responses

Conditions affecting multi-locale support on WebSEALConditions affecting multi-locale support on WebSEALmulti-locale supportconditionsHTTPheadersAccept-LanguageAccept-CharsetAccept-Language HTTP headerAccept Charset HTTP header Multi-locale support is enabled at all times on the WebSEAL server.Installation of specific language packs determines what languages are supported.If WebSEAL receives a message with no Accept-Language HTTP header, WebSEAL defaults to C.WebSEAL always returns the UTF-8 character set to the user, regardless of what the Accept-Charset HTTP header value requests.If WebSEAL accesses a locale directory for a translated message, and the directory is empty (for example, the contents were removed by the administrator), a server error page is returned.Multi-locale support for server responses

Conditions affecting multi-locale support on WebSEAL

Multi-locale support is enabled at all times on the WebSEAL server.

Installation of specific language packs determines what languages are supported.

If WebSEAL receives a message with no Accept-Language HTTP header, WebSEAL defaults to C.

WebSEAL always returns the UTF-8 character set to the user, regardless of what the Accept-Charset HTTP header value requests.

If WebSEAL accesses a locale directory for a translated message, and the directory is empty (for example, the contents were removed by the administrator), a server error page is returned.

Parent topic: Multi-locale support for server responses

Handling the favicon.ico file with Mozilla FirefoxHandling the favicon.ico file with Mozilla Firefoxfavicon.icoMozilla FirefoxFirefox Problem background: The favicon.ico file is a small graphic icon that is used by some browsers (including Microsoft Internet Explorer and Mozilla Firefox) to enhance the display of address bar information and "favorites" bookmark lists. When requesting a resource, these browsers also try to locate the site's custom favicon.ico file. There is a difference, however, in the way Internet Explorer and Mozilla Firefox decide when to request the favicon.ico file: Internet Explorer requests favicon.ico only when the returned page is bookmarked.Mozilla Firefox requests favicon.ico at the same time as the request for the page. The request and response exchange between a Mozilla Firefox browser and a WebSEAL server can result in an HTTP 404 "Not found" message for the user when the favicon.ico does not exist. In a protected WebSEAL environment, Mozilla Firefox's attempt to access the favicon.ico file triggers a login prompt. WebSEAL caches /favicon.ico as its "last requested URL." Once the user successfully logs in, WebSEAL redirects the request to this "last requested URL" location. The file (being non-existent in this example) is not found and a 404 "Not found" error is returned to the user. The originally requested page is never accessed because of the redirection process. Solution: The following steps solve this problem:Place a favicon.ico file in the junction-root directory. You can access this directory from the Manage Reverse Proxy Management Root page of the LMI.Add a definition for the ico file format in the [content-mime-types] of the WebSEAL configuration file:[content-mime-types] ico = image/x-iconCreate an ACL that allows unauthenticated access to /favicon.ico. For example:pdadmin> acl show favicon ACL name: favicon Description: Entries: Any-other Tr Unauthenticated Tr User sec_master TcmdbsvaBRrlAttach this ACL explicitly to /favicon.ico or ensure that the unauthenticated permission is inherited to this point. For example:pdadmin> acl attach /WebSEAL/abc.ibm.com-default/favicon.ico favicon If you do not want to create and install a favicon.ico file, the problem can be solved by following steps 3 and 4 only. An ACL can be attached to an object space representation of a resource, even if the resource does not physically exist. Although the browser still does not find the file, the unauthenticated ACL prevents a login prompt. The browser handles the 404 error internally and proceeds to access the requested page.Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionHTML redirection

Handling the favicon.ico file with Mozilla Firefox

About this task

Problem background:

The favicon.ico file is a small graphic icon that is used by some browsers (including Microsoft Internet Explorer and Mozilla Firefox) to enhance the display of address bar information and "favorites" bookmark lists. When requesting a resource, these browsers also try to locate the site's custom favicon.ico file.

There is a difference, however, in the way Internet Explorer and Mozilla Firefox decide when to request the favicon.ico file:

Internet Explorer requests favicon.ico only when the returned page is bookmarked.

Mozilla Firefox requests favicon.ico at the same time as the request for the page.

The request and response exchange between a Mozilla Firefox browser and a WebSEAL server can result in an HTTP 404 "Not found" message for the user when the favicon.ico does not exist.

In a protected WebSEAL environment, Mozilla Firefox's attempt to access the favicon.ico file triggers a login prompt. WebSEAL caches /favicon.ico as its "last requested URL." Once the user successfully logs in, WebSEAL redirects the request to this "last requested URL" location. The file (being non-existent in this example) is not found and a 404 "Not found" error is returned to the user. The originally requested page is never accessed because of the redirection process.

Solution:

The following steps solve this problem:

Procedure

Place a favicon.ico file in the junction-root directory. You can access this directory from the Manage Reverse Proxy Management Root page of the LMI.

Add a definition for the ico file format in the [content-mime-types] of the WebSEAL configuration file:

[content-mime-types]
ico = image/x-icon

Create an ACL that allows unauthenticated access to /favicon.ico. For example:

pdadmin> acl show favicon
ACL name: favicon
Description:
Entries:
   Any-other Tr
   Unauthenticated Tr
   User sec_master TcmdbsvaBRrl

Attach this ACL explicitly to /favicon.ico or ensure that the unauthenticated permission is inherited to this point. For example:

pdadmin> acl attach /WebSEAL/abc.ibm.com-default/favicon.ico favicon

Results

If you do not want to create and install a favicon.ico file, the problem can be solved by following steps 3 and 4 only. An ACL can be attached to an object space representation of a resource, even if the resource does not physically exist. Although the browser still does not find the file, the unauthenticated ACL prevents a login prompt. The browser handles the 404 error internally and proceeds to access the requested page.

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Adding custom headers to server response pagesAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. server response pagesadd custom headersauthenticationdata included in each requestUse the macros in the following table to define the information in the custom headers:Macros for defining custom headersMacroDescriptionTAM_OPThe operation code for the response. The values for this macro are identical to the values for local response redirects. See Operation for local response redirectionWhen WebSEAL receives a client request, it determines the appropriate operation required in response to the request..AUTHNLEVELAuthentication level required by the authentication strength policy (step-up).ERROR_CODEThe hexadecimal value of the error code.ERROR_TEXTThe error message text that is associated with the error code in the message catalog. This text is supplied by WebSEAL.USERNAMEThe name of the logged in user. WebSEAL uses the value "unauthenticated" for users who are not logged in.CREDATTR{name}The value of the user credential attribute that has the specified name. For example, CREDATTR{tagvalue_session_index} returns the session token.The http-rsp-header configuration entry defines the headers that are included with the server response pages. This configuration entry is in the [acnt-mgt] stanza of the WebSEAL configuration file. The format of the configuration entry is: http-rsp-header = <header-name>:<macro>where<header-name>The name of the header to hold the value.<macro>The type of value that is to be inserted as described in Table 1. For example, the following configuration entry includes the error message text from WebSEAL in a header named error_msg:[acnt-mgt] http-rsp-header = error_msg:ERROR_TEXTYou can specify this configuration entry multiple times to include more than one custom header in the response.For example:[acnt-mgt] http-rsp-header = error_msg:ERROR_TEXT http-rsp-header = tam-error-code:ERROR_CODEFor further information, see the http-rsp-header configuration entry in the [acnt-mgt] stanza in the IBM Knowledge Center.Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxConfiguring the location URL format in redirect responsesLocal response redirectionHTML redirection

Adding custom headers to server response pages

You can add headers, which contain information about a custom response, to generated server responses.

Use the macros in the following table to define the information in the custom headers:

Table 14. Macros for defining custom headers

Macro | Description
TAM_OP | The operation code for the response. The values for this macro are identical to the values for local response redirects. See Operation for local response redirection.
AUTHNLEVEL | Authentication level required by the authentication strength policy (step-up).
ERROR_CODE | The hexadecimal value of the error code.
ERROR_TEXT | The error message text that is associated with the error code in the message catalog. This text is supplied by WebSEAL.
USERNAME | The name of the logged in user. WebSEAL uses the value "unauthenticated" for users who are not logged in.
CREDATTR{name} | The value of the user credential attribute that has the specified name. For example, CREDATTR{tagvalue_session_index} returns the session token.

The http-rsp-header configuration entry defines the headers that are included with the server response pages. This configuration entry is in the [acnt-mgt] stanza of the WebSEAL configuration file.

The format of the configuration entry is:

http-rsp-header = <header-name>:<macro>

where

<header-name>

The name of the header to hold the value.

<macro>

The type of value that is to be inserted as described in Table 14.

For example, the following configuration entry includes the error message text from WebSEAL in a header named error_msg:

[acnt-mgt]
http-rsp-header = error_msg:ERROR_TEXT

Note: You can specify this configuration entry multiple times to include more than one custom header in the response.

For example:

[acnt-mgt]
http-rsp-header = error_msg:ERROR_TEXT
http-rsp-header = tam-error-code:ERROR_CODE

For further information, see the http-rsp-header configuration entry in the [acnt-mgt] stanza in the IBM Knowledge Center.

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Configuring the location URL format in redirect responsesConfiguring the location URL format in redirect responsesHTTPheaderslocationlocation headerredirect location header formatHTTPredirectionconfiguring location header URL formatredirect-using-relative stanza entryWhen WebSEAL responds to a request with an HTTP 302 redirect response, the format of the URL in the Location header is, by default, expressed as an absolute path. For example: Location: http://www.example.com/images/logo.jpg If your environment requires the use of a server-relative format for the URL in the Location header, you can configure this specification in the WebSEAL configuration file. Manually add the redirect-using-relative stanza entry to the [server] stanza and set the value to "true": [server] redirect-using-relative = true With this configuration, the above Location header example will now appear as follows: Location: /images/logo.jpg This hidden configuration option normally defaults to "false". This configuration change affects all redirect responses generated by WebSEAL. These redirect situations include: Redirect after authenticationRedirect after logoutRedirect after changing passwordRedirects during the e-community single signon authentication processRedirects during the cross-domain single signon authentication processSwitch user processingCertificate authentication (prompt-as-needed only)Session displacement This configuration change does not affect redirect responses that are returned from back-end application servers.Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Local response redirectionHTML redirection

Configuring the location URL format in redirect responses

About this task

When WebSEAL responds to a request with an HTTP 302 redirect response, the format of the URL in the Location header is, by default, expressed as an absolute path. For example:

Location: http://www.example.com/images/logo.jpg

If your environment requires the use of a server-relative format for the URL in the Location header, you can configure this specification in the WebSEAL configuration file.

Manually add the redirect-using-relative stanza entry to the [server] stanza and set the value to "true":

[server]
redirect-using-relative = true

With this configuration, the above Location header example will now appear as follows:

Location: /images/logo.jpg

This hidden configuration option normally defaults to "false".

This configuration change affects all redirect responses generated by WebSEAL. These redirect situations include:

Redirect after authentication

Redirect after logout

Redirect after changing password

Redirects during the e-community single signon authentication process

Redirects during the cross-domain single signon authentication process

Switch user processing

Certificate authentication (prompt-as-needed only)

Session displacement

This configuration change does not affect redirect responses that are returned from back-end application servers.

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

Local response redirection

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Related reference:

Multi-locale support for server responses

Local response redirectionLocal response redirectionlocal response redirectionredirectionlocal responsesThis section contains the following topics:Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesHTML redirectionLocal response redirection overviewLocal response redirection process flowEnabling and disabling local response redirectionContents of a redirected responseURI for local response redirectionOperation for local response redirectionWhen WebSEAL receives a client request, it determines the appropriate operation required in response to the request.Macro support for local response redirectionLocal response redirection configuration exampleTechnical notes for local response redirectionRemote response handling with local authentication

Local response redirection

This section contains the following topics:

Local response redirection overview

Local response redirection process flow

Enabling and disabling local response redirection

Contents of a redirected response

URI for local response redirection

Operation for local response redirection
When WebSEAL receives a client request, it determines the appropriate operation required in response to the request.

Macro support for local response redirection

Local response redirection configuration example

Technical notes for local response redirection

Remote response handling with local authentication

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

HTML redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Local response redirection overviewLocal response redirection overviewlocal response redirectionoverviewredirectionlocal responsesWebSEAL provides a number of static HTML server response pages that can be used to provide server responses to client requests. These pages include:Error messagesInformational messagesLogin formsPassword management formsIn some environments, it might be beneficial to extend or modify server responses beyond what WebSEAL provides with its default set of static HTML pages. Local response redirection provides a means to externalize the handling of such responses to an external server.When using local response redirection, WebSEAL no longer has the responsibility of generating responses to client requests. WebSEAL's default "local response" is now redirected to a separate server that runs a custom application designed to generate appropriate responses.When local response redirection is enabled, the redirection is used for all local WebSEAL response types: login, error, informational, and password management.You can combine an external authentication interface application and a local response redirection application to create a complete remote solution for handling authentication and server response. Alternatively, you can implement local response redirection without using the external authentication interface for authentication handling. In this case, the server response handling is performed remotely and authentication is handled locally by WebSEAL. See Remote response handling with local authentication. Local response redirection

Local response redirection overview

WebSEAL provides a number of static HTML server response pages that can be used to provide server responses to client requests. These pages include:

Error messages

Informational messages

Login forms

Password management forms

In some environments, it might be beneficial to extend or modify server responses beyond what WebSEAL provides with its default set of static HTML pages. Local response redirection provides a means to externalize the handling of such responses to an external server.

When using local response redirection, WebSEAL no longer has the responsibility of generating responses to client requests. WebSEAL's default "local response" is now redirected to a separate server that runs a custom application designed to generate appropriate responses.

When local response redirection is enabled, the redirection is used for all local WebSEAL response types: login, error, informational, and password management.

You can combine an external authentication interface application and a local response redirection application to create a complete remote solution for handling authentication and server response. Alternatively, you can implement local response redirection without using the external authentication interface for authentication handling. In this case, the server response handling is performed remotely and authentication is handled locally by WebSEAL. See Remote response handling with local authentication.

Parent topic: Local response redirection

Local response redirection process flowLocal response redirection process flowlocal response redirectionprocess flowprocess flowlocal response redirectionThe local response redirection solution takes advantage of the fact that most devices handle HTTP 302 redirection. The following process flow illustrates how local response redirection works at a high level: WebSEAL receives the client request.WebSEAL determines that it must return a response that would normally be handled by returning a static HTML page, such as a login or error page.WebSEAL builds a Location header in the response that contains the URI of a custom response handling application located on a separate server.WebSEAL includes, as an attribute in the query string of the Location header, the type of operation required (such as “login required”, “expired password”, or "error") and an optional set of configurable WebSEAL macros and their values.WebSEAL redirects the client to this custom response handling application.The custom response handling application is responsible for presenting an appropriate response or set of responses to the client. Local response redirection

Local response redirection process flow

The local response redirection solution takes advantage of the fact that most devices handle HTTP 302 redirection. The following process flow illustrates how local response redirection works at a high level:

WebSEAL receives the client request.

WebSEAL determines that it must return a response that would normally be handled by returning a static HTML page, such as a login or error page.

WebSEAL builds a Location header in the response that contains the URI of a custom response handling application located on a separate server.

WebSEAL includes, as an attribute in the query string of the Location header, the type of operation required (such as “login required”, “expired password”, or "error") and an optional set of configurable WebSEAL macros and their values.

WebSEAL redirects the client to this custom response handling application.

The custom response handling application is responsible for presenting an appropriate response or set of responses to the client.

Parent topic: Local response redirection

Enabling and disabling local response redirectionEnabling and disabling local response redirectionlocal response redirectionenablingdisablingenable-local-response-redirect stanza entrylocation headerlocal response redirectionThe enable-local-response-redirect stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file allows you to explicitly enable or disable local response redirection. Valid values are “yes” (enable) and “no” (disable).Local response redirection is disabled by default. For example:[acnt-mgt] enable-local-response-redirect = noYou can customize this configuration item for a particular junction by adding the adjusted configuration item to a [acnt-mgt:{junction_name}] stanza. where {junction_name} is the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.Local response redirection

Enabling and disabling local response redirection

About this task

The enable-local-response-redirect stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file allows you to explicitly enable or disable local response redirection. Valid values are “yes” (enable) and “no” (disable).

Local response redirection is disabled by default. For example:

[acnt-mgt]
enable-local-response-redirect = no

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [acnt-mgt:{junction_name}] stanza.

where {junction_name} is the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Parent topic: Local response redirection

Contents of a redirected responseContents of a redirected responselocal response redirectioncontents of a redirected responseredirected responsesRedirected responses resulting from local response redirection are standard HTTP 302 redirect responses containing a specially constructed Location header.The Location header contains the following components:A configurable destination URI.A query string indicating the required server response operation, and an optional set of configurable WebSEAL macros and their values.The Location header has the following format:Location header = location-URI?TAM_OP=operation-value[&optional-macros]For details on each of the components of the Location header, refer to the following sections:URI for local response redirectionOperation for local response redirectionWhen WebSEAL receives a client request, it determines the appropriate operation required in response to the request.Macro support for local response redirectionLocal response redirection

Contents of a redirected response

Redirected responses resulting from local response redirection are standard HTTP 302 redirect responses containing a specially constructed Location header.

The Location header contains the following components:

A configurable destination URI.

A query string indicating the required server response operation, and an optional set of configurable WebSEAL macros and their values.

The Location header has the following format:

Location header = location-URI?TAM_OP=operation-value[&optional-macros]

For details on each of the components of the Location header, refer to the following sections:

URI for local response redirection

Operation for local response redirection

Macro support for local response redirection

Parent topic: Local response redirection

URI for local response redirectionURI for local response redirectionlocal response redirectionspecify location URIlocal-response-redirect-uri stanza entryThe local-response-redirect-uri stanza entry in the [local-response-redirect] stanza of the WebSEAL configuration file specifies the location (URI) of the custom application that provides the response handling service. WebSEAL uses this URI to construct the value of the Location header required by the HTTP 302 response. The server used for local response redirection can be a junctioned server or an entirely separate server.The format of the URI value for the local-response-redirect-uri stanza entry can be absolute or server-relative. Server-relative URIs must contain an appropriate junction name.In the following example:jct is the name of the WebSEAL junctionredirect-app is the name of the custom redirection applicationresponse-handler is the name of the custom response handling service (such as a servlet, JSP, or CGI)[local-response-redirect] local-response-redirect-uri = /jct/redirect-app/response-handlerThe local-response-redirect-uri stanza entry must be specified when enable-local-response-redirect = yes. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [local-response-redirect:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.Local response redirection

URI for local response redirection

The local-response-redirect-uri stanza entry in the [local-response-redirect] stanza of the WebSEAL configuration file specifies the location (URI) of the custom application that provides the response handling service. WebSEAL uses this URI to construct the value of the Location header required by the HTTP 302 response.

The server used for local response redirection can be a junctioned server or an entirely separate server.

The format of the URI value for the local-response-redirect-uri stanza entry can be absolute or server-relative. Server-relative URIs must contain an appropriate junction name.

In the following example:

jct is the name of the WebSEAL junction

redirect-app is the name of the custom redirection application

response-handler is the name of the custom response handling service (such as a servlet, JSP, or CGI)

[local-response-redirect]
local-response-redirect-uri = /jct/redirect-app/response-handler

The local-response-redirect-uri stanza entry must be specified when enable-local-response-redirect = yes.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [local-response-redirect:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Parent topic: Local response redirection

Operation for local response redirectionOperation for local response redirectionWhen WebSEAL receives a client request, it determines the appropriate operation required in response to the request.local response redirectionspecify operationTAM_OPTo respond appropriately, the response handler application must be informed of the required response operation, as determined by WebSEAL. Example operations include serving a standard login form, a change password form, or an access denied error message.The required operation is provided as an argument in the query string of the HTTP 302 Location URI header. The label for the operation argument is TAM_OP. The following table lists the valid values for the TAM_OP query string argument: Values for TAM_OP Operation ArgumentDescriptionacct_inactivated User has provided correct authentication details, but nsAccountLock is set to true for the user in Sun Java System Directory Server.acct_locked User authentication failed due to a locked (invalid) account.cert_login User must login with a certificate when accept-client-certs = prompt_as_needed.cert_stepup_http User tried to step-up to certificate authentication over HTTP, which is not allowed (HTTPS is required).eai_auth_error External authentication interface information returned to WebSEAL is invalid. error An error occurred. Check the ERROR_CODE macro for the hexadecimal error code. See the Error messages section of the IBM Knowledge Center.failed_cert An attempt to authenticate with a client certificate failed. Client failed to authenticate with a certificate when accept-client-certs = required. A valid client certificate is required to make this connection. User's certificate is invalid.help User performed an action that makes no sense, such as requesting /pkmslogout while logged in using basic authentication.login User needs to authenticate.login_success User successfully authenticated, but there is no last cached URL to redirect to.logout User has logged out.passwd User requests password change.passwd_exp User's password has expired.passwd_rep_failure Password change request failed.passwd_rep_success Password change request succeeded.passwd_warn Password is soon to expire.passwd_warn_failure Password change not performed after notification that the password is soon to expire.stepup User must step-up to another authentication level. Check the AUTHNLEVEL macro for the required authentication level.switch_user User requested the switch user login page.too_many_sessions User has reached or exceeded the maximum number of allowed sessions.The following example header shows a Location URI with a password change operation indicated in the query string:Location: https://webseal/jct/handler-svr/handler?TAM_OP=passwdLocal response redirection

Operation for local response redirection

When WebSEAL receives a client request, it determines the appropriate operation required in response to the request.

To respond appropriately, the response handler application must be informed of the required response operation, as determined by WebSEAL. Example operations include serving a standard login form, a change password form, or an access denied error message.

The required operation is provided as an argument in the query string of the HTTP 302 Location URI header. The label for the operation argument is TAM_OP.

The following table lists the valid values for the TAM_OP query string argument:

Values for TAM_OP Operation Argument
Description

acct_inactivated

User has provided correct authentication details, but nsAccountLock is set to true for the user in Sun Java™ System Directory Server.

acct_locked

User authentication failed due to a locked (invalid) account.

cert_login

User must login with a certificate when accept-client-certs = prompt_as_needed.

cert_stepup_http

User tried to step-up to certificate authentication over HTTP, which is not allowed (HTTPS is required).

eai_auth_error

External authentication interface information returned to WebSEAL is invalid.

error

An error occurred. Check the ERROR_CODE macro for the hexadecimal error code. See the Error messages section of the IBM Knowledge Center.

failed_cert

An attempt to authenticate with a client certificate failed. Client failed to authenticate with a certificate when accept-client-certs = required. A valid client certificate is required to make this connection. User's certificate is invalid.

help

User performed an action that makes no sense, such as requesting /pkmslogout while logged in using basic authentication.

login

User needs to authenticate.

login_success

User successfully authenticated, but there is no last cached URL to redirect to.

logout

User has logged out.

passwd

User requests password change.

passwd_exp

User's password has expired.

passwd_rep_failure

Password change request failed.

passwd_rep_success

Password change request succeeded.

passwd_warn

Password is soon to expire.

passwd_warn_failure

Password change not performed after notification that the password is soon to expire.

stepup

User must step-up to another authentication level. Check the AUTHNLEVEL macro for the required authentication level.

switch_user

User requested the switch user login page.

too_many_sessions

User has reached or exceeded the maximum number of allowed sessions.

The following example header shows a Location URI with a password change operation indicated in the query string:

Location: https://webseal/jct/handler-svr/handler?TAM_OP=passwd

Parent topic: Local response redirection

Macro support for local response redirectionMacro support for local response redirectionlocal response redirectionspecify macro supportmacrossupportlocal response redirectionLocal response redirection provides support for a subset of the macros provided by WebSEAL to customize static server response pages. Macros allow dynamic substitution of information from WebSEAL. As with the operation information (provided by the TAM_OP argument), macros are specified as an argument in the query string of the location header. Specific characters in the macro values are URI-encoded (see Encoding of macro contents).Valid WebSEAL macros for use in local response redirection include:MacroDescriptionAUTHNLEVEL Authentication level required by authentication strength policy (step-up).CREDATTR{name} Used to include the contents of a specified attribute in the user credential. If the specified credential attribute does not exist in the request, the macro contains the text: 'Unknown'. For example, use the following macro name to include the tagvalue_session_index attribute, which contains the secret token for the session: CREDATTR{tagvalue_session_index}.ERROR_CODE The hexadecimal value of the error code.ERROR_TEXT The WebSEAL-supplied error message text associated with an error code in the message catalog.FAILREASON Error message text associated with a Boolean rules operation.HOSTNAME Fully qualified host name.HTTPHDR{name} Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist in the request, the macro contains the text: 'Unknown'. For example, the macro name to include the "Host" HTTP header is HTTPHDR{Host}.METHOD The HTTP method requested by the client.PROTOCOL The client connection protocol used. Can be HTTP or HTTPS.REFERER The value of the HTTP referer header from the request, or "Unknown", if none.URL The URL requested by the client.USERNAME The name of the logged in user. For users that are not logged in, the name that they used to attempt to log in is the one that is used. (See also Customization of login forms for reauthenticationWebSEAL supports reauthentication for both forms authentication methods..)When using local response redirection, WebSEAL also uses the value "unauthenticated" after an inactivity timeout. This behavior differs from the processing that occurs when WebSEAL serves static pages. You can configure WebSEAL to set the USERNAME macro value to the authenticated username as it does when serving static pages. To achieve this behavior, set the use-existing-username-macro-in-custom-redirects configuration entry in the [server] stanza to yes. You must restart WebSEAL for this change to take effect.For example, the originally requested URL might be required by an external authentication interface server that provides authentication services. The standard WebSEAL URL macro can be included in the query string of the Location header of the HTTP 302 response. The value of the macro is dynamically provided by WebSEAL.To specify macro-supplied information (to be returned in the Location header query string), uncomment the appropriate macro stanza entries in the [local-response-macros] stanza of the WebSEAL configuration file. For example:[local-response-macros] macro = TAM_OP #macro = USERNAME #macro = METHOD #macro = REFERER #macro = HOSTNAME #macro = AUTHNLEVEL #macro = FAILREASON #macro = PROTOCOL #macro = ERROR_CODE #macro = ERROR_TEXT #macro = HTTPHDR{header_name} macro = URLWebSEAL inserts the TAM_OP macro in all local redirect responses regardless of whether it is included in the configuration file.The following example header shows a Location URI with the TAM_OP and URL macros (and values) indicated in the query string (entered as one line):Location: https://webseal/jct/handler-svr/handler?TAM_OP=login& URL=%2FjctB%2Fresource.htmlIn this example, the forward slash character (/) in the value of the URL macro is encoded as %2F. See Encoding of macro contents.If a configured macro contains no information, the macro name and the “=” delimiter still appear in the query string. For example (entered as one line):Location: https://webseal/jct/handler-svr/handler?TAM_OP=stepup&USERNAME=eric& FAILREASON=&AUTHNLEVEL=2The HTTPHDR macro is used to include a specified HTTP header in the query string. The desired header name should be configured in the [local-response-macros] stanza. For example, to insert the Host header into the query string, the following configuration entry should be added to the [local-response-macros] stanza:macro = HTTPHDR{Host}This will result in a query string similar to the following:Location: https://webseal/jct/handler-svr/handler?TAM_OP=login&HTTPHDR_Host=websealLocal response redirectionCustomizing macro field namesEncoding of macro contentsMacro content length considerations

Macro support for local response redirection

Local response redirection provides support for a subset of the macros provided by WebSEAL to customize static server response pages. Macros allow dynamic substitution of information from WebSEAL.

As with the operation information (provided by the TAM_OP argument), macros are specified as an argument in the query string of the location header. Specific characters in the macro values are URI-encoded (see Encoding of macro contents).

Valid WebSEAL macros for use in local response redirection include:

Macro
Description

AUTHNLEVEL

Authentication level required by authentication strength policy (step-up).

CREDATTR{name}

Used to include the contents of a specified attribute in the user credential. If the specified credential attribute does not exist in the request, the macro contains the text: 'Unknown'.

For example, use the following macro name to include the tagvalue_session_index attribute, which contains the secret token for the session: CREDATTR{tagvalue_session_index}.

ERROR_CODE

The hexadecimal value of the error code.

ERROR_TEXT

The WebSEAL-supplied error message text associated with an error code in the message catalog.

FAILREASON

Error message text associated with a Boolean rules operation.

HOSTNAME

Fully qualified host name.

HTTPHDR{name}

Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist in the request, the macro contains the text: 'Unknown'.

For example, the macro name to include the "Host" HTTP header is HTTPHDR{Host}.

METHOD

The HTTP method requested by the client.

PROTOCOL

The client connection protocol used. Can be HTTP or HTTPS.

REFERER

The value of the HTTP referer header from the request, or "Unknown", if none.

URL

The URL requested by the client.

USERNAME

The name of the logged in user. For users that are not logged in, the name that they used to attempt to log in is the one that is used. (See also Customization of login forms for reauthentication.)

When using local response redirection, WebSEAL also uses the value "unauthenticated" after an inactivity timeout. This behavior differs from the processing that occurs when WebSEAL serves static pages. You can configure WebSEAL to set the USERNAME macro value to the authenticated username as it does when serving static pages. To achieve this behavior, set the use-existing-username-macro-in-custom-redirects configuration entry in the [server] stanza to yes. You must restart WebSEAL for this change to take effect.

For example, the originally requested URL might be required by an external authentication interface server that provides authentication services. The standard WebSEAL URL macro can be included in the query string of the Location header of the HTTP 302 response. The value of the macro is dynamically provided by WebSEAL.

To specify macro-supplied information (to be returned in the Location header query string), uncomment the appropriate macro stanza entries in the [local-response-macros] stanza of the WebSEAL configuration file. For example:

[local-response-macros]
macro = TAM_OP
#macro = USERNAME
#macro = METHOD
#macro = REFERER
#macro = HOSTNAME
#macro = AUTHNLEVEL
#macro = FAILREASON
#macro = PROTOCOL
#macro = ERROR_CODE
#macro = ERROR_TEXT
#macro = HTTPHDR{header_name}
macro = URL

Note: WebSEAL inserts the TAM_OP macro in all local redirect responses regardless of whether it is included in the configuration file.

The following example header shows a Location URI with the TAM_OP and URL macros (and values) indicated in the query string (entered as one line):

Location: https://webseal/jct/handler-svr/handler?TAM_OP=login&
 URL=%2FjctB%2Fresource.html

In this example, the forward slash character (/) in the value of the URL macro is encoded as %2F. See Encoding of macro contents.

If a configured macro contains no information, the macro name and the “=” delimiter still appear in the query string. For example (entered as one line):

Location: https://webseal/jct/handler-svr/handler?TAM_OP=stepup&USERNAME=eric&
 FAILREASON=&AUTHNLEVEL=2

The HTTPHDR macro is used to include a specified HTTP header in the query string. The desired header name should be configured in the [local-response-macros] stanza. For example, to insert the Host header into the query string, the following configuration entry should be added to the [local-response-macros] stanza:

macro = HTTPHDR{Host}

This will result in a query string similar to the following:

Location: https://webseal/jct/handler-svr/handler?TAM_OP=login&HTTPHDR_Host=webseal

Customizing macro field names

Encoding of macro contents

Macro content length considerations

Parent topic: Local response redirection

Customizing macro field namesCustomizing macro field nameslocal response redirectioncustomize macro field namesmacrosfield namescustomizing macro field namesYou can customize the names that WebSEAL uses for the Location URL macros in the generated query strings. To configure these values, place a colon after the macro name followed by the customized name. For example:[local-response-macros] macro = TAM_OP:myOperation #macro = USERNAME #macro = METHOD #macro = REFERER #macro = HOSTNAME #macro = AUTHNLEVEL #macro = FAILREASON #macro = PROTOCOL #macro = ERROR_CODE #macro = ERROR_TEXT #macro = HTTPHDR{header_name} #macro = CREDATTR{name} macro = URL:destinationThis example configuration causes WebSEAL to generate a Location URI that contains the URL and TAM_OP macros. WebSEAL inserts the specified custom values, rather than the WebSEAL macro name, into the query string. For this example, the generated Location URI is similar to the following query string:Location: https://webseal/jct/handler-svr/handler?myOperation=login&destination =%2FjctB%2Fresource.htmlIf you configure a custom name for the HTTPHDR macro then the name of the header (header_name) is not included in the query string. For example, consider the following example entry in the [local-response-macros] stanza:macro = HTTPHDR{Host}:myHostThe resulting query string looks similar to the following example:Location: https://webseal/jct/handler-svr/handler?myOperation=login&destination= %2FjctB%2Fresource.html&myHost=webseal You can configure multiple HTTPHDR entries to be included in the query string. You can customize the macro field names for each of these entries. WebSEAL inserts the TAM_OP macro in all local redirect responses regardless of whether it is included in the configuration file. You can configure the name that WebSEAL uses for this macro by including a customized name in the configuration file.Macro support for local response redirection

Customizing macro field names

You can customize the names that WebSEAL uses for the Location URL macros in the generated query strings. To configure these values, place a colon after the macro name followed by the customized name.

For example:

[local-response-macros]
macro = TAM_OP:myOperation
#macro = USERNAME
#macro = METHOD
#macro = REFERER
#macro = HOSTNAME
#macro = AUTHNLEVEL
#macro = FAILREASON
#macro = PROTOCOL
#macro = ERROR_CODE
#macro = ERROR_TEXT
#macro = HTTPHDR{header_name}
#macro = CREDATTR{name}
macro = URL:destination

This example configuration causes WebSEAL to generate a Location URI that contains the URL and TAM_OP macros. WebSEAL inserts the specified custom values, rather than the WebSEAL macro name, into the query string. For this example, the generated Location URI is similar to the following query string:

Location: https://webseal/jct/handler-svr/handler?myOperation=login&destination
=%2FjctB%2Fresource.html

If you configure a custom name for the HTTPHDR macro then the name of the header (header_name) is not included in the query string. For example, consider the following example entry in the [local-response-macros] stanza:

macro = HTTPHDR{Host}:myHost

The resulting query string looks similar to the following example:

Location: https://webseal/jct/handler-svr/handler?myOperation=login&destination=
%2FjctB%2Fresource.html&myHost=webseal

You can configure multiple HTTPHDR entries to be included in the query string. You can customize the macro field names for each of these entries.

Note: WebSEAL inserts the TAM_OP macro in all local redirect responses regardless of whether it is included in the configuration file. You can configure the name that WebSEAL uses for this macro by including a customized name in the configuration file.

Parent topic: Macro support for local response redirection

Encoding of macro contentsEncoding of macro contentslocal response redirectionURI encoding for macrosURI encoding for macrosSome macro content contains user-provided data such as the requested URI or the Referer header of that request. It is important for security reasons to ensure that reserved, or special characters in client-supplied data are encoded. WebSEAL URI encodes macro contents to ensure that the content does not return reserved, or special characters back to the client. URI encoding is an international standard that allows you to map the wide range of characters used worldwide into the limited character-set used by a URI.Notes on encoding macro contents:WebSEAL always applies URI encoding to macro contents, even if the original data has already been encoded.Encoded macro contents must be decoded using standard URI decoding rules.URI encoding increases the string length of macro content, and therefore the Location header (where the content is embedded in the query string). For a discussion of Location header length issues, see Macro content length considerations.Macro support for local response redirection

Encoding of macro contents

Some macro content contains user-provided data such as the requested URI or the Referer header of that request. It is important for security reasons to ensure that reserved, or special characters in client-supplied data are encoded.

WebSEAL URI encodes macro contents to ensure that the content does not return reserved, or special characters back to the client. URI encoding is an international standard that allows you to map the wide range of characters used worldwide into the limited character-set used by a URI.

Notes on encoding macro contents:

WebSEAL always applies URI encoding to macro contents, even if the original data has already been encoded.

Encoded macro contents must be decoded using standard URI decoding rules.

URI encoding increases the string length of macro content, and therefore the Location header (where the content is embedded in the query string). For a discussion of Location header length issues, see Macro content length considerations.

Parent topic: Macro support for local response redirection

Macro content length considerationsMacro content length considerationslocal response redirectionmacro content lengthlocal response redirectionmacro content lengthInformation supplied by macros increases the string length of the Location URI header. URI encoding of macro content further increases this string length. Some client applications (such as WAP browsers on cellular phones) have URI length limitations due to the small memory capacity of the device. If a URI exceeds the length limitation on such a client device, errors can occur and the link will likely fail. WebSEAL does not impose any length restrictions on the Location URI header. Therefore, when configuring macros for local response redirection, you must carefully consider the possible limitations of client devices that access your site. You can estimate the length of the Location header by determining the fixed lengths of the URI and factoring in the expected sizes of any macros used in the query string.The following table provides information about the possible lengths of the content provided by the macros used for local response redirection:MacroSize of ContentAUTHNLEVELNo more than 10 characters.ERROR_CODENo more than 20 characters.ERROR_TEXTThe error message length.FAILREASONThe error message length.HOSTNAMEThe length of the HOST header of the corresponding request, or the fully qualified host name of the WebSEAL system if the HOST header is not present.METHODLength of request method (such as GET or POST). No more than 20 characters.PROTOCOLNo more than 10 characters.REFERERThe length of the REFERER header of the corresponding request.URLLength of the request URI.USERNAMEMaximum length defined by user name length policy for this implementation of WebSEAL.HTTPHDR{name}Length of the specified HTTP header.CREDATTR{name}Length of the contents for the specified attribute in the user credential.Macro support for local response redirection

Macro content length considerations

Information supplied by macros increases the string length of the Location URI header. URI encoding of macro content further increases this string length.

Some client applications (such as WAP browsers on cellular phones) have URI length limitations due to the small memory capacity of the device. If a URI exceeds the length limitation on such a client device, errors can occur and the link will likely fail.

WebSEAL does not impose any length restrictions on the Location URI header. Therefore, when configuring macros for local response redirection, you must carefully consider the possible limitations of client devices that access your site. You can estimate the length of the Location header by determining the fixed lengths of the URI and factoring in the expected sizes of any macros used in the query string.

The following table provides information about the possible lengths of the content provided by the macros used for local response redirection:

Macro | Size of Content
AUTHNLEVEL | No more than 10 characters.
ERROR_CODE | No more than 20 characters.
ERROR_TEXT | The error message length.
FAILREASON | The error message length.
HOSTNAME | The length of the HOST header of the corresponding request, or the fully qualified host name of the WebSEAL system if the HOST header is not present.
METHOD | Length of request method (such as GET or POST). No more than 20 characters.
PROTOCOL | No more than 10 characters.
REFERER | The length of the REFERER header of the corresponding request.
URL | Length of the request URI.
USERNAME | Maximum length defined by user name length policy for this implementation of WebSEAL.
HTTPHDR{name} | Length of the specified HTTP header.
CREDATTR{name} | Length of the contents for the specified attribute in the user credential.

Parent topic: Macro support for local response redirection

Local response redirection configuration exampleLocal response redirection configuration examplelocal response redirectionexample configurationconfigurationexamplesThe following example steps summarize the configuration required to implement local response redirection. This example illustrates the combined implementation of local response redirection with an external authentication interface service.The following variables are used in this example: jct is the name of the WebSEAL junctioneai-redirect-app is the name of the custom application that provides combined external authentication interface and local response redirection servicesauthn-handler is the name of the custom authentication service (such as a servlet, JSP, or CGI)response-handler is the name of the custom response handling service (such as a servlet, JSP, or CGI)Example: A custom external authentication interface service is implemented on the junctioned server to handle the WebSEAL authentication process: webseal/jct/eai-redirect-app/authn-handlerEnable local response redirection to handle responses to requests: [acnt-mgt] enable-local-response-redirect = yesSpecify the location of the custom response handling application (Location URI): [local-response-redirect] local-response-redirect-uri = /jct/eai-redirect-app/response-handlerSpecify that the URL requested by the client (supplied by the URL macro) be returned in the Location URI query string of the local response redirection: [local-response-macros] macro = URLClient requests a resource requiring authentication: https://webseal/jctB/resource.htmlWebSEAL returns an HTTP 302 response containing the following Location URI header (entered as one line). The login operation required is specified in the query string as: TAM_OP=login: Location: https://webseal/jct/eai-redirect-app/response-handler?TAM_OP=login& URL=http%3A//webseal/jctB/resource.htmlThe custom response handling application provides a response to the client (consistent with a login operation) and makes use of the resource URL information provided.The client completes one or more interactions with the custom response handler and is eventually routed to the external authentication interface where the actual authentication is performed.Local response redirection

Local response redirection configuration example

The following example steps summarize the configuration required to implement local response redirection. This example illustrates the combined implementation of local response redirection with an external authentication interface service.

The following variables are used in this example:

jct is the name of the WebSEAL junction

eai-redirect-app is the name of the custom application that provides combined external authentication interface and local response redirection services

authn-handler is the name of the custom authentication service (such as a servlet, JSP, or CGI)

response-handler is the name of the custom response handling service (such as a servlet, JSP, or CGI)

Example:

A custom external authentication interface service is implemented on the junctioned server to handle the WebSEAL authentication process:

webseal/jct/eai-redirect-app/authn-handler

Enable local response redirection to handle responses to requests:

[acnt-mgt]
enable-local-response-redirect = yes

Specify the location of the custom response handling application (Location URI):

[local-response-redirect]
local-response-redirect-uri = /jct/eai-redirect-app/response-handler

Specify that the URL requested by the client (supplied by the URL macro) be returned in the Location URI query string of the local response redirection:

[local-response-macros]
macro = URL

Client requests a resource requiring authentication:

https://webseal/jctB/resource.html

WebSEAL returns an HTTP 302 response containing the following Location URI header (entered as one line). The login operation required is specified in the query string as: TAM_OP=login:

Location: https://webseal/jct/eai-redirect-app/response-handler?TAM_OP=login&
URL=http%3A//webseal/jctB/resource.html

The custom response handling application provides a response to the client (consistent with a login operation) and makes use of the resource URL information provided.

The client completes one or more interactions with the custom response handler and is eventually routed to the external authentication interface where the actual authentication is performed.

Parent topic: Local response redirection

Technical notes for local response redirectionTechnical notes for local response redirectionTechnical notes for local response redirection in IBM Security Access Manager for Weblocal response redirectiontechnical notestechnical noteslocal response redirection If a client makes a bad or erroneous request to WebSEAL as a result of a redirected error page, WebSEAL returns a static error message page rather than initiating another redirection operation.To avoid a possible redirection loop condition, the custom message handling application must be a resource that is available to unauthenticated users. Security Access Manager ACLs must be configured to ensure this availability to unauthenticated users.When implementing external authentication interface and local response redirection together, ensure that the configured location URI is not the same as any external authentication interface trigger URLs.All requests that are redirected by local response redirection are cached in the same manner as for default response handling.Local response redirection

Technical notes for local response redirection

If a client makes a bad or erroneous request to WebSEAL as a result of a redirected error page, WebSEAL returns a static error message page rather than initiating another redirection operation.

To avoid a possible redirection loop condition, the custom message handling application must be a resource that is available to unauthenticated users. Security Access Manager ACLs must be configured to ensure this availability to unauthenticated users.

When implementing external authentication interface and local response redirection together, ensure that the configured location URI is not the same as any external authentication interface trigger URLs.

All requests that are redirected by local response redirection are cached in the same manner as for default response handling.

Parent topic: Local response redirection

Remote response handling with local authenticationRemote response handling with local authenticationpkmslogin.formremote response handlinglocal authenticationYou can implement local response redirection without using the external authentication interface. In this case, the server response handling is performed remotely and authentication is handled locally by WebSEAL. For example, the remote response handler can serve a login page that requires a local WebSEAL authentication handler such as pkmslogin.form to implement the authentication process. In this example, the login page served by the remote response handler contains a FORM tag with an ACTION attribute. The value of the ACTION attribute points to the location of the local WebSEAL authentication handler (pkmslogin.form). When the client submits the completed login form, the data is directed to this handler.When WebSEAL receives a request for pkmslogin.form, it responds by invoking the appropriate authentication mechanism and passing the appropriate authentication data to this mechanism.The pkmslogin.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.You can use the appropriate static HTML response pages provided by WebSEAL as templates for your custom pages. If necessary, edit the pages to customize the content for your environment. Ensure that all URLs are expressed to correctly satisfy the filtering rules of WebSEAL.Local response redirectionJunction filtering issues for the ACTION URL

Remote response handling with local authentication

You can implement local response redirection without using the external authentication interface. In this case, the server response handling is performed remotely and authentication is handled locally by WebSEAL. For example, the remote response handler can serve a login page that requires a local WebSEAL authentication handler such as pkmslogin.form to implement the authentication process.

In this example, the login page served by the remote response handler contains a FORM tag with an ACTION attribute. The value of the ACTION attribute points to the location of the local WebSEAL authentication handler (pkmslogin.form). When the client submits the completed login form, the data is directed to this handler.

When WebSEAL receives a request for pkmslogin.form, it responds by invoking the appropriate authentication mechanism and passing the appropriate authentication data to this mechanism.

Note: The pkmslogin.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

You can use the appropriate static HTML response pages provided by WebSEAL as templates for your custom pages. If necessary, edit the pages to customize the content for your environment. Ensure that all URLs are expressed to correctly satisfy the filtering rules of WebSEAL.

Junction filtering issues for the ACTION URL

Parent topic: Local response redirection

Junction filtering issues for the ACTION URLJunction filtering issues for the ACTION URLpkmslogin.formjunctionsfiltering issuesACTION URLThe login page served by a response handler located on a junctioned server is filtered by WebSEAL when it is returned to the client over the junction. The page might contain a FORM tag similar to WebSEAL's standard static HTML login response page (login.html): <FORM METHOD=POST ACTION="/pkmslogin.form">If this FORM tag appears in a page served by a remote response handler located on a junctioned server, WebSEAL filters the server-relative ACTION URL by prepending the junction name to the path: /jct/pkmslogin.formBecause the pkmslogin.form authentication handler is local to WebSEAL, WebSEAL cannot find the filtered version of the URL and the request for an authentication operation from WebSEAL fails.You must ensure that the response handler serves a login page with an ACTION attribute that correctly points to pkmslogin.form. Use a relative path expression to navigate upwards from the location where the custom login page is served. For example, if the login page is served from the following JSP (JavaServer Pages) application: /jct/redirect-app/custom-login.jspthe ACTION URL in this page must be expressed as follows: <FORM METHOD=POST ACTION="../../pkmslogin.form">WebSEAL does not filter relative path names. Therefore, this path is correctly resolved by the client browser as being located in the document root space of the WebSEAL server.For complete information about WebSEAL filtering rules, see Filter rules for tag-based static URLs.Remote response handling with local authentication

Junction filtering issues for the ACTION URL

The login page served by a response handler located on a junctioned server is filtered by WebSEAL when it is returned to the client over the junction. The page might contain a FORM tag similar to WebSEAL's standard static HTML login response page (login.html):

<FORM METHOD=POST ACTION="/pkmslogin.form">

If this FORM tag appears in a page served by a remote response handler located on a junctioned server, WebSEAL filters the server-relative ACTION URL by prepending the junction name to the path:

/jct/pkmslogin.form

Because the pkmslogin.form authentication handler is local to WebSEAL, WebSEAL cannot find the filtered version of the URL and the request for an authentication operation from WebSEAL fails.

You must ensure that the response handler serves a login page with an ACTION attribute that correctly points to pkmslogin.form. Use a relative path expression to navigate upwards from the location where the custom login page is served. For example, if the login page is served from the following JSP (JavaServer Pages) application:

/jct/redirect-app/custom-login.jsp

the ACTION URL in this page must be expressed as follows:

<FORM METHOD=POST ACTION="../../pkmslogin.form">

WebSEAL does not filter relative path names. Therefore, this path is correctly resolved by the client browser as being located in the document root space of the WebSEAL server.

For complete information about WebSEAL filtering rules, see Filter rules for tag-based static URLs.

Parent topic: Remote response handling with local authentication

HTML redirectionHTML redirectionHTMLredirectionoverviewredirectionHTMLWhen a user successfully authenticates, WebSEAL typically uses an HTTP 302 response to redirect the user back to the resource that was originally requested. This process causes problems for applications that rely on HTML fragments as the fragment information is stored locally in the browser and is lost during redirection.Alternatively, you can configure WebSEAL to enable HTML redirection. HTML redirection causes WebSEAL to send a static page back to the browser instead of a 302 redirect. The browser can then use JavaScript or any other code that is embedded in this static page to perform the redirect. WebSEAL provides the macro LOCATION, which contains the URL for the redirection.Web server response configurationStatic HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. HTML server response page locationsHTML server response page modificationAccount management page configurationError message page configurationWhen WebSEAL is unable to process a request from a client, WebSEAL returns an HTML error message page to the client. The error message page explains why the request failed.Multi-locale support for server responsesHandling the favicon.ico file with Mozilla FirefoxAdding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. Configuring the location URL format in redirect responsesLocal response redirectionEnabling HTML redirectionPreserving HTML fragments on redirection

HTML redirection

When a user successfully authenticates, WebSEAL typically uses an HTTP 302 response to redirect the user back to the resource that was originally requested. This process causes problems for applications that rely on HTML fragments as the fragment information is stored locally in the browser and is lost during redirection.

Alternatively, you can configure WebSEAL to enable HTML redirection. HTML redirection causes WebSEAL to send a static page back to the browser instead of a 302 redirect. The browser can then use JavaScript or any other code that is embedded in this static page to perform the redirect. WebSEAL provides the macro LOCATION, which contains the URL for the redirection.

Enabling HTML redirection

Preserving HTML fragments on redirection

Parent topic: Web server response configuration

Related concepts:

Static HTML server response pages

HTML server response page locations

HTML server response page modification

Account management page configuration

Error message page configuration

Adding custom headers to server response pages

Local response redirection

Related tasks:

Handling the favicon.ico file with Mozilla Firefox

Configuring the location URL format in redirect responses

Related reference:

Multi-locale support for server responses

Enabling HTML redirectionEnabling HTML redirectionHTMLredirectionenablingdisablingenable-html-redirect stanza entryUse the enable-html-redirect stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file to enable or disable HTML redirection. You can use HTML redirection, in conjunction with some JavaScript code, to preserve the HTML fragment in the response.Valid values are “yes” (enable) and “no” (disable). HTML redirection is disabled by default. For example:[acnt-mgt] enable-html-redirect = noIf you enable this configuration entry, WebSEAL returns the redirect page that is specified by html-redirect in the [acnt-mgt] stanza instead of an HTTP 302 response. For example:[acnt-mgt] html-redirect = redirect.htmlThis configuration for HTML redirection does not affect redirect responses that are returned by junctioned web servers.HTML redirection

Enabling HTML redirection

About this task

Use the enable-html-redirect stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file to enable or disable HTML redirection. You can use HTML redirection, in conjunction with some JavaScript code, to preserve the HTML fragment in the response.

Valid values are “yes” (enable) and “no” (disable). HTML redirection is disabled by default. For example:

[acnt-mgt]
enable-html-redirect = no

If you enable this configuration entry, WebSEAL returns the redirect page that is specified by html-redirect in the [acnt-mgt] stanza instead of an HTTP 302 response. For example:

[acnt-mgt]
html-redirect = redirect.html

Note: This configuration for HTML redirection does not affect redirect responses that are returned by junctioned web servers.

Parent topic: HTML redirection

Preserving HTML fragments on redirectionPreserving HTML fragments on redirectionHTMLredirectionpreserve HTML fragmentsenable-html-redirect stanza entryWebSEAL provides an example configuration of HTML redirection. This example uses cookies to store the original URL in the browser and JavaScript to later read that URL and perform the redirection. The example shows how to save the HTML fragment during an authentication operation.In addition to enabling HTML redirection, you must modify the JavaScript on the user interface form (such as login.html) to store the HTML fragment for the subsequent redirect. The page before redirection must store the originally requested resource, complete with HTML fragment, in a cookie in the client web browser cookie jar. When the redirection page returns, the example JavaScript reads the cookie value and redirects the client to the originally requested resource while preserving the HTML fragment.You can use this configuration with any of the login mechanisms for which WebSEAL provides a login page. You must uncomment the line of JavaScript that sets the TAMOriginalURL cookie in the corresponding WebSEAL templates. These WebSEAL templates include: login.html, stepuplogin.html and certlogin.html.For example, to preserve the HTML fragment with forms-based authentication you must complete the following steps:Update the login.html page. Uncomment the bold line of JavaScript to set a cookie named TAMOriginalURL on the client browser with a URI encoded copy of the originally requested URL. This JavaScript is included in the default login.html file that is supplied with WebSEAL.<SCRIPT LANGUAGE=JavaScript> var warningString = "<B>WARNING:</B> To maintain your login session, make sure that your browser is configured to accept Cookies."; document.cookie = 'acceptsCookies=yes'; if(document.cookie == ''){ document.write(warningString); } else{ document.cookie = 'acceptsCookies=yes; expires=Fri, 13-Apr-1970 00:00:00 GMT'; document.cookie = 'TAMOriginalURL=' + encodeURIComponent(window.location) + "; Path=/;"; } </SCRIPT>Ensure that the html-redirect configuration entry in the [acnt-mgt] stanza specifies the redirect.html file that is supplied with WebSEAL. This file contains the following script, which parses the cookies in the browser and looks for the TAMOriginalURL cookie set by the preceding page. When this cookie is found, it is URI decoded and set to expire immediately. The line containing window.location.href then performs the redirection.<SCRIPT LANGUAGE=JavaScript> var redirect = "TAMOriginalURL="; var cookies = document.cookie.split(';'); var redirectURL = "%LOCATION%"; for(var i=0; i<cookies.length; i++) { var cookie = cookies[i]; while (cookie.charAt(0)==' ') { cookie = cookie.substring(1, cookie.length); if (cookie.indexOf(redirect) == 0) { redirectURL = cookie.substring(redirect.length, cookie.length); document.cookie = 'TAMOriginalURL=; expires=Thu, 01-Jan-70 00:00:01 GMT;'; i = cookies.length; break; } } } window.location.href = decodeURIComponent(redirectURL); </SCRIPT>In some situations it is not possible to set a cookie before the redirection is to take place, such as when a local response redirect is performed. For these situations, WebSEAL includes the macro %LOCATION%, which is inserted into the static redirect page. This macro contains the complete URL of the redirection and can be used when cookies cannot be set. However, in this situation any HTTP fragment information is lost.HTML redirection

Preserving HTML fragments on redirection

About this task

WebSEAL provides an example configuration of HTML redirection. This example uses cookies to store the original URL in the browser and JavaScript to later read that URL and perform the redirection. The example shows how to save the HTML fragment during an authentication operation.

In addition to enabling HTML redirection, you must modify the JavaScript on the user interface form (such as login.html) to store the HTML fragment for the subsequent redirect. The page before redirection must store the originally requested resource, complete with HTML fragment, in a cookie in the client web browser cookie jar. When the redirection page returns, the example JavaScript reads the cookie value and redirects the client to the originally requested resource while preserving the HTML fragment.

You can use this configuration with any of the login mechanisms for which WebSEAL provides a login page. You must uncomment the line of JavaScript that sets the TAMOriginalURL cookie in the corresponding WebSEAL templates. These WebSEAL templates include: login.html, stepuplogin.html and certlogin.html.

For example, to preserve the HTML fragment with forms-based authentication you must complete the following steps:

Procedure

Update the login.html page. Uncomment the bold line of JavaScript to set a cookie named TAMOriginalURL on the client browser with a URI encoded copy of the originally requested URL. This JavaScript is included in the default login.html file that is supplied with WebSEAL.

<SCRIPT LANGUAGE=JavaScript>
var warningString = "<B>WARNING:</B> To maintain your login session,
				make sure that your browser is configured to accept Cookies.";
document.cookie = 'acceptsCookies=yes';
if(document.cookie == ''){
	document.write(warningString);
}
else{
document.cookie = 'acceptsCookies=yes; expires=Fri, 13-Apr-1970 00:00:00 GMT';
document.cookie = 'TAMOriginalURL=' + encodeURIComponent(window.location) +
			"; Path=/;";
}
</SCRIPT>

Ensure that the html-redirect configuration entry in the [acnt-mgt] stanza specifies the redirect.html file that is supplied with WebSEAL. This file contains the following script, which parses the cookies in the browser and looks for the TAMOriginalURL cookie set by the preceding page. When this cookie is found, it is URI decoded and set to expire immediately. The line containing window.location.href then performs the redirection.

<SCRIPT LANGUAGE=JavaScript>
var redirect = "TAMOriginalURL=";
var cookies = document.cookie.split(';');
var redirectURL = "%LOCATION%";
for(var i=0; i<cookies.length; i++) {
	var cookie = cookies[i];
	while (cookie.charAt(0)==' ') {
		cookie = cookie.substring(1, cookie.length);
		if (cookie.indexOf(redirect) == 0) {
			redirectURL = cookie.substring(redirect.length, cookie.length);
			document.cookie = 'TAMOriginalURL=; expires=Thu, 01-Jan-70 00:00:01 GMT;';
			i = cookies.length;
			break;
		}
	}
}
window.location.href = decodeURIComponent(redirectURL);
</SCRIPT>

Note: In some situations it is not possible to set a cookie before the redirection is to take place, such as when a local response redirect is performed. For these situations, WebSEAL includes the macro %LOCATION%, which is inserted into the static redirect page. This macro contains the complete URL of the redirection and can be used when cookies cannot be set. However, in this situation any HTTP fragment information is lost.

Parent topic: HTML redirection

Web server security configurationWeb server security configurationweb serverssecuritysecurityweb serversThis chapter contains information about configuring added security for the WebSEAL server.Topic Index:ConfigurationCryptographic hardware for encryption and key storageConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Configuring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Suppression of WebSEAL and back-end server identityDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Platform for Privacy Preferences (P3P)

Web server security configuration

This chapter contains information about configuring added security for the WebSEAL server.

Topic Index:

Cryptographic hardware for encryption and key storage

Configuring WebSEAL to support only Suite B ciphers
You can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.

Configuring NIST SP800-131A compliance
Special Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.

Prevention of vulnerability caused by cross-site scripting
Cross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.

Prevention of Cross-site Request Forgery (CSRF) attacks
Cross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts.

Suppression of WebSEAL and back-end server identity

Disabling HTTP methods
You can block the use of HTTP methods to request local or remote resources to reduce security vulnerability.

Platform for Privacy Preferences (P3P)

Parent topic: Configuration

Cryptographic hardware for encryption and key storageCryptographic hardware for encryption and key storagecryptographic hardwareconfigurationSSL accelerationsecure key storageBHAPIPKCS#11BHAPIBSAFE (RSA)PKCS#11Web server security configurationConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Configuring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Suppression of WebSEAL and back-end server identityDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Platform for Privacy Preferences (P3P)Cryptographic hardware conceptsWebSEAL uses GSKit for SSL communication and key management to provide interface support for cryptographic hardware.Conditions for using IBM 4758-023On Windows platforms, the IBM 4758–023 cryptographic card has an access limitation of 32 worker threads. Therefore, WebSEAL must be configured to use no more than 32 worker threads. 30 worker threads is the suggested configuration. The default setting for worker threads at WebSEAL installation time is 50 worker threads.Configuration of the Cipher engine and FIPS mode processingYou can use the WebSEAL configuration file to specify the Cipher engine used by GSKit.Configuring WebSEAL for cryptographic hardwareConfiguring network Hardware Security Module (HSM) supportYou can register a network HSM device with the local management interface. WebSEAL can then be configured to use this HSM for the secure storage of SSL keys.Configuring RSA one-time password supportConfigure the Web Reverse Proxy to use RSA tokens as an authentication mechanism.

Cryptographic hardware for encryption and key storage

Cryptographic hardware concepts
WebSEAL uses GSKit for SSL communication and key management to provide interface support for cryptographic hardware.

Conditions for using IBM 4758-023
On Windows platforms, the IBM® 4758–023 cryptographic card has an access limitation of 32 worker threads. Therefore, WebSEAL must be configured to use no more than 32 worker threads. 30 worker threads is the suggested configuration. The default setting for worker threads at WebSEAL installation time is 50 worker threads.

Configuration of the Cipher engine and FIPS mode processing
You can use the WebSEAL configuration file to specify the Cipher engine used by GSKit.

Configuring WebSEAL for cryptographic hardware

Configuring network Hardware Security Module (HSM) support
You can register a network HSM device with the local management interface. WebSEAL can then be configured to use this HSM for the secure storage of SSL keys.

Configuring RSA one-time password support
Configure the Web Reverse Proxy to use RSA tokens as an authentication mechanism.

Parent topic: Web server security configuration

Related concepts:

Prevention of vulnerability caused by cross-site scripting

Prevention of Cross-site Request Forgery (CSRF) attacks

Suppression of WebSEAL and back-end server identity

Platform for Privacy Preferences (P3P)

Related tasks:

Configuring WebSEAL to support only Suite B ciphers

Configuring NIST SP800-131A compliance

Disabling HTTP methods

Cryptographic hardware conceptsCryptographic hardware conceptsWebSEAL uses GSKit for SSL communication and key management to provide interface support for cryptographic hardware.cryptographic hardwareconceptsGSKitSSL communicationkey managementCryptographic hardware can provide one or both of the following features:Accelerated and secure SSL encryption and decryption tasks for performance improvements during multiple online transactionsAccelerated and secure digital certificate key storage and management for highly secure architecture during online transactionsWebSEAL supports several hardware devices for selected platforms. For a complete list of supported hardware devices, search for IBM Global Security Kit, Version 8 - PKCS#11 Device Integration in the IBM developerWorks Technical Library at https://www.ibm.com/developerworks. For an example of how to configure WebSEAL to use cryptographic hardware, search for the SSL Acceleration in WebSEAL with a Hardware Security Module developerWorks topic.Hardware cryptographic acceleration and key storage apply to the following WebSEAL connections:Browser to WebSEALWebSEAL to back-end junctioned serverThe following product functions or features do not currently support cryptographic hardware integration: Symmetric key operations (including key storage), such as eCSSO, CDSSO, LTPA, and any other SSL connections.Any cryptographic operations (including certificate and key storage) completed with SSL configured between the Security Access Manager directory client and directory server.Any cryptographic operations (including certificate and key storage) completed when Security Access Manager components communicate as part of the authorization database management (pdadmin or database replication).Any cryptographic operations (including certificate and key storage) completed with SSL configured between WebSEAL and the Security Access Manager session management server.Cryptographic hardware for encryption and key storage

Cryptographic hardware concepts

WebSEAL uses GSKit for SSL communication and key management to provide interface support for cryptographic hardware.

Cryptographic hardware can provide one or both of the following features:

Accelerated and secure SSL encryption and decryption tasks for performance improvements during multiple online transactions

Accelerated and secure digital certificate key storage and management for highly secure architecture during online transactions

WebSEAL supports several hardware devices for selected platforms. For a complete list of supported hardware devices, search for IBM Global Security Kit, Version 8 - PKCS#11 Device Integration in the IBM® developerWorks® Technical Library at https://www.ibm.com/developerworks. For an example of how to configure WebSEAL to use cryptographic hardware, search for the SSL Acceleration in WebSEAL with a Hardware Security Module developerWorks topic.

Hardware cryptographic acceleration and key storage apply to the following WebSEAL connections:

Browser to WebSEAL

WebSEAL to back-end junctioned server

The following product functions or features do not currently support cryptographic hardware integration:

Symmetric key operations (including key storage), such as eCSSO, CDSSO, LTPA, and any other SSL connections.

Any cryptographic operations (including certificate and key storage) completed with SSL configured between the Security Access Manager directory client and directory server.

Any cryptographic operations (including certificate and key storage) completed when Security Access Manager components communicate as part of the authorization database management (pdadmin or database replication).

Any cryptographic operations (including certificate and key storage) completed with SSL configured between WebSEAL and the Security Access Manager session management server.

Parent topic: Cryptographic hardware for encryption and key storage

Conditions for using IBM 4758-023Conditions for using IBM 4758-023Conditions for using IBM 4758-023 in IBM Security Access Manager for WebOn Windows platforms, the IBM 4758–023 cryptographic card has an access limitation of 32 worker threads. Therefore, WebSEAL must be configured to use no more than 32 worker threads. 30 worker threads is the suggested configuration. The default setting for worker threads at WebSEAL installation time is 50 worker threads.IBM 4758--023 cryptographic cardconditions of useaccess limitationsaccesslimitationsIBM 4758–023See WebSEAL worker thread configurationThe number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by a server. You can set the number of threads available to service incoming connections to WebSEAL. for information about worker thread configuration.Additional monitoring threads are used for any junctions configured with the –K option (WebSEAL authenticates with a client-side certificate) where the key (certificate) is stored on the IBM 4758 hardware. In this situation, further reduce the number of worker threads by 1 for each SSL –K junction using keys stored on the IBM 4758 card.Cryptographic hardware for encryption and key storage

Conditions for using IBM 4758-023

On Windows platforms, the IBM® 4758–023 cryptographic card has an access limitation of 32 worker threads. Therefore, WebSEAL must be configured to use no more than 32 worker threads. 30 worker threads is the suggested configuration. The default setting for worker threads at WebSEAL installation time is 50 worker threads.

IBM 4758–023

See WebSEAL worker thread configuration for information about worker thread configuration.

Additional monitoring threads are used for any junctions configured with the –K option (WebSEAL authenticates with a client-side certificate) where the key (certificate) is stored on the IBM 4758 hardware. In this situation, further reduce the number of worker threads by 1 for each SSL –K junction using keys stored on the IBM 4758 card.

Parent topic: Cryptographic hardware for encryption and key storage

Configuration of the Cipher engine and FIPS mode processingConfiguration of the Cipher engine and FIPS mode processingYou can use the WebSEAL configuration file to specify the Cipher engine used by GSKit.cipher engineconfigurationFIPS mode processingconfigurationbase-crypto-library stanza entryICCRSAFIPS (Federal Information Process Standards )fips-mode-processing stanza entryFederal Information Process Standards (FIPS)fips-mode-processing stanza entry[ssl] base-crypto-library = DefaultValid values for this entry are:Default This value tells GSKit to select the optimal cryptographic base to use. For WebSEAL Version 7, the default cryptographic base is ICC.ICCYou can specify whether to enable FIPS mode processing. FIPS mode processing is disabled by default. To enable FIPS mode processing, set the following entry:fips-mode-processing stanza entry[ssl] fips-mode-processing = yesSet the value to "yes" when you are using ICC and you want to use the FIPS 140-1 approved protocols and ciphers.Cryptographic hardware for encryption and key storage

Configuration of the Cipher engine and FIPS mode processing

You can use the WebSEAL configuration file to specify the Cipher engine used by GSKit.

[ssl]
base-crypto-library = Default

Valid values for this entry are:

Default

This value tells GSKit to select the optimal cryptographic base to use. For WebSEAL Version 7, the default cryptographic base is ICC.

ICC

You can specify whether to enable FIPS mode processing. FIPS mode processing is disabled by default. To enable FIPS mode processing, set the following entry:

[ssl]
fips-mode-processing = yes

Set the value to "yes" when you are using ICC and you want to use the FIPS 140-1 approved protocols and ciphers.

Parent topic: Cryptographic hardware for encryption and key storage

Configuring WebSEAL for cryptographic hardwareConfiguring WebSEAL for cryptographic hardwarecryptographic hardwareconfigurationWebSEALWebSEALcryptographic hardwarePerform the following steps to configure WebSEAL for cryptographic hardware:Cryptographic hardware for encryption and key storage1. Install the cryptographic card and device driverFollow the instructions provided by the specific vendor to install the cryptographic card and its device driver (with PKCS#11) for the specific cryptographic hardware you are using. This procedure involves shutting down and restarting the computer machine.2. Create a token device label and password to store WebSEAL keyscryptographic hardwareconfigurationtoken stanza entrytoken stanza entryIn the context of cryptographic hardware and the associated device drivers, a token is a logical device that acts as a "container" for storing key, data, and certificate objects. Key objects can include public keys and private keys. When you configure a cryptographic card to perform key storage (using the PKCS#11 interface), you must define one or more tokens (or "containers") that store keys for different situations.When you configure a cryptographic card to perform key storage tasks for WebSEAL (GSKit), you must specify a token label (and password) that represents the token device that stores the WebSEAL public/private key pair. WebSEAL sends the public key in the server-side certificate that it uses to authenticate itself to any client.Use the instructions provided with the installed cryptographic hardware to create a label for the token device that stores the WebSEAL key.For example:token = websealtoken password = secret3. Configure iKeyman to use the PKCS#11 moduleiKeymancryptographic hardware configurationjava.security fileThe iKeyman utility is packaged with the Java Runtime Environment version 6.0 or later. You must configure iKeyman for the PKCS#11 device module (shared library) of the installed cryptographic hardware device. The iKeyman utility uses this module to understand the following components: The WebSEAL token label for the hardware device.The password or PIN for the token.The key label of any WebSEAL key stored on the device.Locate the java.security file in the directory location that is applicable to your environment:Solaris:User-defined location during Java installation. For example, /usr/java.Linux:/opt/ibm/java-s390x-60/jre/lib/securityAIX:/usr/java6_64/jre/lib/securityWindows:C:\Program Files\IBM\Java60\jre\lib\securityEdit this file by adding a line to include the IBMPKCS11Impl provider in the provider list. That is, com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl.For example: # # List of providers and their preference orders: # security.provider.1=com.ibm.crypto.provider.IBMJCE security.provider.2=com.ibm.jsse.IBMJSSEProvider security.provider.3=com.ibm.jsse2.IBMJSSEProvider2 security.provider.4=com.ibm.security.jgss.IBMJGSSProvider security.provider.5=com.ibm.security.cert.IBMCertPath security.provider.6=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl security.provider.7=com.ibm.security.cmskeystore.CMSProvider security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGOSave these updates.When the shared library is configured, the iKeyman utility includes a new menu option: PKCS11Direct. Now you can use iKeyman to create, store, and manipulate keys for WebSEAL on the cryptographic hardware.4. Use iKeyman to open the WebSEAL token deviceStart the iKeyman utility that is packaged with the Java Runtime Environment version 6.0 or later.Select Key Database File, then Open.A separate Open dialog box displays.In the Open dialog window, select Cryptographic Tokens from the Key database type menu.If you have the cryptographic token specified in the java.security file, the dialog box contains both the path and the library. If you do not see the library, you can use the Browse menu option. Click OK when this step is complete.Additionally, if you want to open an existing secondary key database (for key data not stored on the cryptographic hardware-such as CA root certificates), check Open Existing Key Database.Browse for and select the default WebSEAL key database:UNIX or Linux/var/pdweb/www-instance/certs/pdsrv.kdbWindowsC:\Program Files\Tivoli\pdweb\www-instance\certs\pdsrv.kdbClick OK.The Token Password dialogue box displays.Enter the default password pdsrv. Click OK.The main iKeyman window returns.5. Request and store the WebSEAL server certificateWebSEALserverscertificatesFollow instructions in the IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide to request a secure, signed digital certificate for WebSEAL from a Certificate Authority (CA).Follow instructions in the IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide to receive the WebSEAL certificate from the CA and store it in a key database. When performing this procedure, select the token device representing the cryptographic hardware as the storage location for the certificate.When it is stored on the token device, the key (certificate) appears (for example) as:websealtoken:websealThe WebSEAL key is stored on the cryptographic hardware and assigned to the token device labeled "websealtoken".6. Configure WebSEAL and GSKit to use the PKCS#11 shared librarypkcs-11-driver-pathpkcs11-driver-path stanza entrypkcs11-token-pwd stanza entrypkcs11-token-label stanza entrycryptographic hardware configurationpkcs11-driver-path stanza entrypkcs11-token-label stanza entrypkcs11-token-pwd stanza entryIn the WebSEAL configuration file, specify the names of the token label and password under the [ssl] stanza: For this example:[ssl] pkcs11-token-label = websealtoken pkcs11-token-pwd = secret(For IBM 4960 only) In the WebSEAL configuration file, modify the WebSEAL instance UNIX group account configuration to specify group pkcs11. This allows WebSEAL to access the PKCS token:[server] unix-group = pkcs117. Modify the WebSEAL server certificate labelcryptographic hardwareconfigurationwebseal-cert-keyfile-labelwebseal-cert-keyfile-label stanza entryConfigure WebSEAL to use this new hardware-based key rather than the default key in its communications with browser clients. Modify the webseal-cert-keyfile-label stanza entry in the [ssl] stanza of the WebSEAL configuration file to designate the new key label.[ssl] webseal-cert-keyfile-label = <token-name>:<key-label>For this example:[ssl] webseal-cert-keyfile-label = websealtoken:webseal8. Configure WebSEAL for PKCS#11 symmetric algorithmspkcs11-symmetric-cipher-support stanza entryYou can configure WebSEAL to support the GSKit option for using PKCS#11 for symmetric algorithms.To enable PKCS#11 for symmetric algorithms, uncomment the pkcs11-symmetric-cipher-support stanza entry in the [ssl] stanza of the WebSEAL configuration file and set the value to "yes". For example:[ssl] pkcs11-symmetric-cipher-support = yesTo disable support for symmetric algorithms, uncomment the pkcs11-symmetric-cipher-support stanza entry in the [ssl] stanza of the WebSEAL configuration file and set the value to "no". For example:[ssl] pkcs11-symmetric-cipher-support = noThe PKCS#11 symmetric cipher support does not include removable devices. If a removable device is encountered, it is ignored even if the support has been requested. Additionally, not all devices support symmetric ciphers. Refer to the appropriate vendor documentation for the device you are using.9. Restart WebSEALRestart WebSEAL for all cryptographic hardware configuration to take effect.Verify that WebSEAL is using the cryptographic hardware by examining entries contained in the msg_webseald.log file.

Configuring WebSEAL for cryptographic hardware

About this task

Perform the following steps to configure WebSEAL for cryptographic hardware:

Parent topic: Cryptographic hardware for encryption and key storage

1. Install the cryptographic card and device driver

About this task

Follow the instructions provided by the specific vendor to install the cryptographic card and its device driver (with PKCS#11) for the specific cryptographic hardware you are using. This procedure involves shutting down and restarting the computer machine.

2. Create a token device label and password to store WebSEAL keys

About this task

In the context of cryptographic hardware and the associated device drivers, a token is a logical device that acts as a "container" for storing key, data, and certificate objects. Key objects can include public keys and private keys. When you configure a cryptographic card to perform key storage (using the PKCS#11 interface), you must define one or more tokens (or "containers") that store keys for different situations.

When you configure a cryptographic card to perform key storage tasks for WebSEAL (GSKit), you must specify a token label (and password) that represents the token device that stores the WebSEAL public/private key pair. WebSEAL sends the public key in the server-side certificate that it uses to authenticate itself to any client.

Use the instructions provided with the installed cryptographic hardware to create a label for the token device that stores the WebSEAL key.

For example:

token = websealtoken
password = secret

3. Configure iKeyman to use the PKCS#11 module

About this task

The iKeyman utility is packaged with the Java™ Runtime Environment version 6.0 or later. You must configure iKeyman for the PKCS#11 device module (shared library) of the installed cryptographic hardware device. The iKeyman utility uses this module to understand the following components:

The WebSEAL token label for the hardware device.

The password or PIN for the token.

The key label of any WebSEAL key stored on the device.

Procedure

Locate the java.security file in the directory location that is applicable to your environment:

Solaris:

User-defined location during Java installation. For example, /usr/java.

Linux:

/opt/ibm/java-s390x-60/jre/lib/security

AIX®:

/usr/java6_64/jre/lib/security

Windows:

C:\Program Files\IBM\Java60\jre\lib\security

Edit this file by adding a line to include the IBMPKCS11Impl provider in the provider list. That is, com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl. For example:

#
# List of providers and their preference orders:
#
security.provider.1=com.ibm.crypto.provider.IBMJCE
security.provider.2=com.ibm.jsse.IBMJSSEProvider
security.provider.3=com.ibm.jsse2.IBMJSSEProvider2
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath
security.provider.6=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl
security.provider.7=com.ibm.security.cmskeystore.CMSProvider
security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO

Save these updates.

Results

When the shared library is configured, the iKeyman utility includes a new menu option: PKCS11Direct. Now you can use iKeyman to create, store, and manipulate keys for WebSEAL on the cryptographic hardware.

4. Use iKeyman to open the WebSEAL token device

Procedure

Start the iKeyman utility that is packaged with the Java Runtime Environment version 6.0 or later.

Select Key Database File, then Open.
A separate Open dialog box displays.

In the Open dialog window, select Cryptographic Tokens from the Key database type menu.

If you have the cryptographic token specified in the java.security file, the dialog box contains both the path and the library. If you do not see the library, you can use the Browse menu option. Click OK when this step is complete.

Additionally, if you want to open an existing secondary key database (for key data not stored on the cryptographic hardware-such as CA root certificates), check Open Existing Key Database.

Browse for and select the default WebSEAL key database:
UNIX or Linux
/var/pdweb/www-instance/certs/pdsrv.kdb
Windows
C:\Program Files\Tivoli\pdweb\www-instance\certs\pdsrv.kdb

Click OK.
The Token Password dialogue box displays.

Enter the default password pdsrv. Click OK.

Results

The main iKeyman window returns.

5. Request and store the WebSEAL server certificate

Procedure

Follow instructions in the IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide to request a secure, signed digital certificate for WebSEAL from a Certificate Authority (CA).

Follow instructions in the IBM Global Security Kit: Secure Sockets Layer Introduction and iKeyman User's Guide to receive the WebSEAL certificate from the CA and store it in a key database. When performing this procedure, select the token device representing the cryptographic hardware as the storage location for the certificate.

Results

When it is stored on the token device, the key (certificate) appears (for example) as:websealtoken:webseal
The WebSEAL key is stored on the cryptographic hardware and assigned to the token device labeled "websealtoken".

6. Configure WebSEAL and GSKit to use the PKCS#11 shared library

Procedure

In the WebSEAL configuration file, specify the names of the token label and password under the [ssl] stanza:
For this example:
[ssl] pkcs11-token-label = websealtoken pkcs11-token-pwd = secret

(For IBM® 4960 only) In the WebSEAL configuration file, modify the WebSEAL instance UNIX group account configuration to specify group pkcs11. This allows WebSEAL to access the PKCS token:

[server]
unix-group = pkcs11

7. Modify the WebSEAL server certificate label

About this task

Configure WebSEAL to use this new hardware-based key rather than the default key in its communications with browser clients. Modify the webseal-cert-keyfile-label stanza entry in the [ssl] stanza of the WebSEAL configuration file to designate the new key label.

[ssl]
webseal-cert-keyfile-label = <token-name>:<key-label>

For this example:

[ssl]
webseal-cert-keyfile-label = websealtoken:webseal

8. Configure WebSEAL for PKCS#11 symmetric algorithms

About this task

You can configure WebSEAL to support the GSKit option for using PKCS#11 for symmetric algorithms.

To enable PKCS#11 for symmetric algorithms, uncomment the pkcs11-symmetric-cipher-support stanza entry in the [ssl] stanza of the WebSEAL configuration file and set the value to "yes". For example:

[ssl]
pkcs11-symmetric-cipher-support = yes

To disable support for symmetric algorithms, uncomment the pkcs11-symmetric-cipher-support stanza entry in the [ssl] stanza of the WebSEAL configuration file and set the value to "no". For example:

[ssl]
pkcs11-symmetric-cipher-support = no

The PKCS#11 symmetric cipher support does not include removable devices. If a removable device is encountered, it is ignored even if the support has been requested. Additionally, not all devices support symmetric ciphers. Refer to the appropriate vendor documentation for the device you are using.

9. Restart WebSEAL

Procedure

Restart WebSEAL for all cryptographic hardware configuration to take effect.

Verify that WebSEAL is using the cryptographic hardware by examining entries contained in the msg_webseald.log file.

Configuring network Hardware Security Module (HSM) supportYou can register a network HSM device with the local management interface. WebSEAL can then be configured to use this HSM for the secure storage of SSL keys. The appliance supports the use of the following HSM devices:Thales nShield Connect The appliance firmware embeds the Thales Security World Client software version 11.70.SafeNet Luna SA v5.xThe appliance can connect to a maximum of one Thales nShield Connect device and multiple SafeNet Luna SA v5.x devices. Perform the following steps to configure WebSEAL for the network HSM device. Create a network key file with the local management interface. From the top menu, select Manage System SettingsSecure SettingsSSL Certificates.From the menu bar, click New.On the Create SSL Certificate Database page, enter the name of the certificate database that you want to create.Select Network as the type of the certificate database.Complete the Token Label and Passcode fields.Select the HSM type.If you select Thales nShield Connect as the HSM type, complete the HSM IP Address and RFS IP Address fields on the Thales tab. The rest of the fields are optional.If you select SafeNet Luna SA as the HSM type, complete the IP Address and Admin Password fields on the SafeNet tab.You can use the appliance to manage the certificates that are contained on the HSM device. However, some operations, such as certificate extract, are not supported.Click Save. Edit the WebSEAL configuration file directly or through the Edit panel in the local management interface to make the following changes. Set the value of the pkcs11-keyfile configuration entry in the [ssl] stanza to be the name of the pkcs11 key file that contains the configuration information for the network HSM device. Set the webseal-cert-keyfile-label configuration entry in the [ssl] stanza, which defines the WebSEAL key file label, to use a key from the HSM device. Restart WebSEAL for the changes to take effect.Cryptographic hardware for encryption and key storageRegistering the appliance as a client in the SafeNet Luna SA HSMConfigure the Luna SA HSM to allow the appliance to access the required partitions. Deleting a client from the SafeNet Luna SA HSMIf all SSL certificates that refer to a Luna SA HSM are deleted from the appliance, remember to delete the client from that HSM.

Configuring network Hardware Security Module (HSM) support

You can register a network HSM device with the local management interface. WebSEAL can then be configured to use this HSM for the secure storage of SSL keys.

About this task

The appliance supports the use of the following HSM devices:

Thales nShield Connect

The appliance firmware embeds the Thales Security World Client software version 11.70.

SafeNet Luna SA v5.x

Note: The appliance can connect to a maximum of one Thales nShield Connect device and multiple SafeNet Luna SA v5.x devices.

Perform the following steps to configure WebSEAL for the network HSM device.

Procedure

Create a network key file with the local management interface.

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

From the menu bar, click New.

On the Create SSL Certificate Database page, enter the name of the certificate database that you want to create.

Select Network as the type of the certificate database.

Complete the Token Label and Passcode fields.

Select the HSM type.

If you select Thales nShield Connect as the HSM type, complete the HSM IP Address and RFS IP Address fields on the Thales tab. The rest of the fields are optional.

If you select SafeNet Luna SA as the HSM type, complete the IP Address and Admin Password fields on the SafeNet tab.

Note: You can use the appliance to manage the certificates that are contained on the HSM device. However, some operations, such as certificate extract, are not supported.

Click Save.

Edit the WebSEAL configuration file directly or through the Edit panel in the local management interface to make the following changes.

Set the value of the pkcs11-keyfile configuration entry in the [ssl] stanza to be the name of the pkcs11 key file that contains the configuration information for the network HSM device.

Set the webseal-cert-keyfile-label configuration entry in the [ssl] stanza, which defines the WebSEAL key file label, to use a key from the HSM device.

Restart WebSEAL for the changes to take effect.

Registering the appliance as a client in the SafeNet Luna SA HSM
Configure the Luna SA HSM to allow the appliance to access the required partitions.

Deleting a client from the SafeNet Luna SA HSM
If all SSL certificates that refer to a Luna SA HSM are deleted from the appliance, remember to delete the client from that HSM.

Parent topic: Cryptographic hardware for encryption and key storage

Registering the appliance as a client in the SafeNet Luna SA HSMConfigure the Luna SA HSM to allow the appliance to access the required partitions. After you create an SSL certificate database on the appliance for the HSM, the appliance generates a certificate and transfers it to the HSM. Before you start these steps, check if the certificate exists on the HSM. The IP address that the appliance uses to communicate with the HSM is required to complete these steps. This IP address can be found on the Details tab of the certificate database on the appliance. Configure only one client on a single HSM for the appliance, regardless of how many certificate databases are created for that HSM.Use SSH to access the Luna SA HSM as admin.Run the following command:client register -client <client_name> -hostname <client_ip> where client_name is a name that represents the appliance and client_ip is the IP address that is listed on the Details tab.Run the following command:client assignPartition -client <client_name> -partition <partition_name> where client_name is the name that is used in the previous step and partition_name is the partition against which the SSL Certificate database was configured.Configuring network Hardware Security Module (HSM) supportYou can register a network HSM device with the local management interface. WebSEAL can then be configured to use this HSM for the secure storage of SSL keys.

Registering the appliance as a client in the SafeNet Luna SA HSM

Configure the Luna SA HSM to allow the appliance to access the required partitions.

Before you begin

After you create an SSL certificate database on the appliance for the HSM, the appliance generates a certificate and transfers it to the HSM. Before you start these steps, check if the certificate exists on the HSM.

The IP address that the appliance uses to communicate with the HSM is required to complete these steps. This IP address can be found on the Details tab of the certificate database on the appliance.

Note: Configure only one client on a single HSM for the appliance, regardless of how many certificate databases are created for that HSM.

Procedure

Use SSH to access the Luna SA HSM as admin.

Run the following command:

client register -client <client_name> -hostname <client_ip>

where client_name is a name that represents the appliance and client_ip is the IP address that is listed on the Details tab.

Run the following command:

client assignPartition -client <client_name> -partition <partition_name>

where client_name is the name that is used in the previous step and partition_name is the partition against which the SSL Certificate database was configured.

Parent topic: Configuring network Hardware Security Module (HSM) support

Deleting a client from the SafeNet Luna SA HSMIf all SSL certificates that refer to a Luna SA HSM are deleted from the appliance, remember to delete the client from that HSM.Use SSH to access the Luna SA HSM as admin.Run the following command:client delete -client <client_name> where client_name is the name that is used to represent the appliance.Configuring network Hardware Security Module (HSM) supportYou can register a network HSM device with the local management interface. WebSEAL can then be configured to use this HSM for the secure storage of SSL keys.

Deleting a client from the SafeNet Luna SA HSM

If all SSL certificates that refer to a Luna SA HSM are deleted from the appliance, remember to delete the client from that HSM.

Procedure

Use SSH to access the Luna SA HSM as admin.

Run the following command:

client delete -client <client_name>

where client_name is the name that is used to represent the appliance.

Parent topic: Configuring network Hardware Security Module (HSM) support

Configuring RSA one-time password supportConfigure the Web Reverse Proxy to use RSA tokens as an authentication mechanism. The appliance embeds an RSA agent. It is compatible with the following RSA server versions:RSA Authentication Manager 6.1 or laterRSA Authentication Manager 7.1 or later On your RSA server, generate the sdconf.rec file, which is the configuration file for connecting to the RSA Authentication server. See your RSA Authentication server documentation for details on how to create this file.Upload the generated sdconf.rec file to the appliance.Log in to the local management interface of the appliance.Go to Secure Web SettingsGlobal SettingsRSA SecurID Configuration.Click Upload to upload the sdconf.rec file. The status area indicates one of two statuses:UnavailableUpload is not completed. AvailableUpload is complete.To remove the contents of a previously loaded file, click Clear.Register the appliance with the RSA Server.The appliance must be registered with the RSA server before the Test button or RSA authentication can be used. Take note of the values that are displayed in the RSA Server and Agent IP Address fields on the RSA Configuration page of the appliance local management interface.On the RSA server, create an authentication agent with the Agent IP Address in the previous step. For Agent type, choose Standard.Generate the node secret file. The node secret file is automatically generated on the first authentication attempt.On the RSA Configuration page of the appliance local management interface, click Test to perform a test authentication. Enter the user name and passcode for a valid RSA user.Click OK to generate the node secret file. The status area of the node secret file indicates one of two statuses:UnavailableThe node secret file was not generated.Auto-generatedThe node secret file was automatically generated.To remove the contents of a previously generated node secret file, click Clear.This step must be performed if the node secret file is changed on the RSA server. If the node secret file is cleared on the appliance, then it must also be cleared for the configured authentication agent on the RSA Manager manually. Errors occur until the node secret file is cleared on the RSA Manager.Cryptographic hardware for encryption and key storage

Configuring RSA one-time password support

Configure the Web Reverse Proxy to use RSA tokens as an authentication mechanism.

Before you begin

The appliance embeds an RSA agent. It is compatible with the following RSA server versions:

RSA Authentication Manager 6.1 or later

RSA Authentication Manager 7.1 or later

On your RSA server, generate the sdconf.rec file, which is the configuration file for connecting to the RSA Authentication server. See your RSA Authentication server documentation for details on how to create this file.

Procedure

Upload the generated sdconf.rec file to the appliance.

Log in to the local management interface of the appliance.

Go to Secure Web Settings > Global Settings > RSA SecurID Configuration.

Click Upload to upload the sdconf.rec file. The status area indicates one of two statuses:

Unavailable

Upload is not completed.

Available

Upload is complete.

Optional: To remove the contents of a previously loaded file, click Clear.

Register the appliance with the RSA Server.

Note: The appliance must be registered with the RSA server before the Test button or RSA authentication can be used.

Take note of the values that are displayed in the RSA Server and Agent IP Address fields on the RSA Configuration page of the appliance local management interface.

On the RSA server, create an authentication agent with the Agent IP Address in the previous step. For Agent type, choose Standard.

Generate the node secret file. The node secret file is automatically generated on the first authentication attempt.

On the RSA Configuration page of the appliance local management interface, click Test to perform a test authentication.

Enter the user name and passcode for a valid RSA user.

Click OK to generate the node secret file. The status area of the node secret file indicates one of two statuses:

Unavailable

The node secret file was not generated.

Auto-generated

The node secret file was automatically generated.

Optional: To remove the contents of a previously generated node secret file, click Clear.

Note: This step must be performed if the node secret file is changed on the RSA server. If the node secret file is cleared on the appliance, then it must also be cleared for the configured authentication agent on the RSA Manager manually. Errors occur until the node secret file is cleared on the RSA Manager.

Parent topic: Cryptographic hardware for encryption and key storage

Configuring WebSEAL to support only Suite B ciphersConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Suite B ciphersgsk-attr-name stanza entry Suite B is a set of cryptographic standards, protocols, and algorithms that the National Security Agency (NSA) developed in 2005. This suite defines security standards for protecting classified information. NSA Suite B includes the Advanced Encryption Standard (AES) and a set of cryptographic algorithms for key exchange, digital signatures, and hashing.Suite B meets the NSA security standards for classified government communications up to the SECRET level. For more information, go to the NSA website at http://www.nsa.gov and search for Suite B Cryptography.Use the gsk-attr-name and jct-gsk-attr-name entries to configure WebSEAL support for Suite B ciphers. Set GSKit attribute 454 to the value 1. The gsk-attr-name configuration entry is available in the [ssl], [dsess-cluster], and [tfim-cluster:<cluster>] stanzas. The [ssl] stanza also includes the jct-gsk-attr-name configuration entry. These stanza entries specify the additional GSKit attributes to use when initializing SSL connections as follows:[ssl] stanzaThe gsk-attr-name applies to SSL connections with clients.The jct-gsk-attr-name applies to SSL connections with junctioned servers.[dsess-cluster] stanzaThe gsk-attr-name applies to SSL connections with the distributed session cache.[tfim-cluster:<cluster>]The gsk-attr-name applies to SSL connections with Tivoli Federated Identity Manager. The following entry configures WebSEAL to use only Suite B ciphers for client connections:[ssl] gsk-attr-name = enum:454:1Web server security configurationCryptographic hardware for encryption and key storageConfiguring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Suppression of WebSEAL and back-end server identityDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Platform for Privacy Preferences (P3P)

Configuring WebSEAL to support only Suite B ciphers

You can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.

About this task

Suite B is a set of cryptographic standards, protocols, and algorithms that the National Security Agency (NSA) developed in 2005. This suite defines security standards for protecting classified information. NSA Suite B includes the Advanced Encryption Standard (AES) and a set of cryptographic algorithms for key exchange, digital signatures, and hashing.

Suite B meets the NSA security standards for classified government communications up to the SECRET level. For more information, go to the NSA website at http://www.nsa.gov and search for Suite B Cryptography.

Use the gsk-attr-name and jct-gsk-attr-name entries to configure WebSEAL support for Suite B ciphers. Set GSKit attribute 454 to the value 1.

The gsk-attr-name configuration entry is available in the [ssl], [dsess-cluster], and [tfim-cluster:<cluster>] stanzas. The [ssl] stanza also includes the jct-gsk-attr-name configuration entry. These stanza entries specify the additional GSKit attributes to use when initializing SSL connections as follows:

[ssl] stanza

The gsk-attr-name applies to SSL connections with clients.

The jct-gsk-attr-name applies to SSL connections with junctioned servers.

[dsess-cluster] stanza

The gsk-attr-name applies to SSL connections with the distributed session cache.

[tfim-cluster:<cluster>]

The gsk-attr-name applies to SSL connections with Tivoli Federated Identity Manager.

Example

The following entry configures WebSEAL to use only Suite B ciphers for client connections:

[ssl]
gsk-attr-name = enum:454:1

Parent topic: Web server security configuration

Related concepts:

Cryptographic hardware for encryption and key storage

Prevention of vulnerability caused by cross-site scripting

Prevention of Cross-site Request Forgery (CSRF) attacks

Suppression of WebSEAL and back-end server identity

Platform for Privacy Preferences (P3P)

Related tasks:

Configuring NIST SP800-131A compliance

Disabling HTTP methods

Configuring NIST SP800-131A complianceConfiguring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.NIST SP800-131A compliancessl stanzatfim-cluster:<cluster> stanzartss-cluster:<cluster> stanzadsess-cluster stanzassl-nist-compliance entryjunction stanzanist-compliancessl stanzassl-nist-compliancertss-cluster:<cluster> stanzatfim-cluster:<cluster> stanzadsess-cluster stanzajct-nist-compliancejunction stanzaUse the nist-compliance, ssl-nist-compliance, and jct-nist-compliance entries to configure NIST SP800-131A compliance.Enabling NIST SP800-131A compliance automatically configures the following settings:Enables FIPS mode processing. Enables TLS v1.2. TLS v1 and TLS v1.1 are not disabled.Enables the appropriate signature algorithms.Sets the minimum RSA key size to 2048 bytes.You can individually enable NIST SP800-131A for specific communication channels by using the following configuration entries:[ssl] stanzaWebSEAL uses the nist-compliance configuration entry as the global NIST setting for SSL connections with clients. If the ssl-nist-compliance configuration entries are not present in the WebSEAL configuration file, WebSEAL uses the nist-compliance value as the default NIST setting for all client connections.[dsess-cluster] stanzaThe ssl-nist-compliance configuration entry controls NIST SP800-131A compliance for SSL connections with the distributed session cache.[rtss-cluster:<cluster>] stanzaThe ssl-nist-compliance configuration entry controls NIST SP800-131A compliance for runtime security services SOAP communication.[tfim-cluster:<cluster>] stanzaThe ssl-nist-compliance controls NIST SP800-131A compliance for SSL connections with Tivoli Federated Identity Manager.[junction] stanzaThe jct-nist-compliance configuration entry controls NIST SP800-131A compliance for SSL connections to junctioned servers.For more information about these configuration entries, see the Reference topics in the IBM Knowledge Center. For example, the following configuration disables NIST SP800-131A compliance for SSL connections with the distributed session cache, but enables NIST SP800-131A compliance for other client connections.[dsess-cluster] ssl-nist-compliance = no [ssl] nist-compliance = yesWeb server security configurationCryptographic hardware for encryption and key storageConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Suppression of WebSEAL and back-end server identityDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Platform for Privacy Preferences (P3P)

Configuring NIST SP800-131A compliance

Special Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.

About this task

Use the nist-compliance, ssl-nist-compliance, and jct-nist-compliance entries to configure NIST SP800-131A compliance.

Enabling NIST SP800-131A compliance automatically configures the following settings:

Enables FIPS mode processing.

Enables TLS v1.2.

Note: TLS v1 and TLS v1.1 are not disabled.

Enables the appropriate signature algorithms.

Sets the minimum RSA key size to 2048 bytes.

You can individually enable NIST SP800-131A for specific communication channels by using the following configuration entries:

[ssl] stanza

WebSEAL uses the nist-compliance configuration entry as the global NIST setting for SSL connections with clients. If the ssl-nist-compliance configuration entries are not present in the WebSEAL configuration file, WebSEAL uses the nist-compliance value as the default NIST setting for all client connections.

[dsess-cluster] stanza

The ssl-nist-compliance configuration entry controls NIST SP800-131A compliance for SSL connections with the distributed session cache.

[rtss-cluster:<cluster>] stanza

The ssl-nist-compliance configuration entry controls NIST SP800-131A compliance for runtime security services SOAP communication.

[tfim-cluster:<cluster>] stanza

The ssl-nist-compliance controls NIST SP800-131A compliance for SSL connections with Tivoli Federated Identity Manager.

[junction] stanza

The jct-nist-compliance configuration entry controls NIST SP800-131A compliance for SSL connections to junctioned servers.

For more information about these configuration entries, see the Reference topics in the IBM Knowledge Center.

Example

For example, the following configuration disables NIST SP800-131A compliance for SSL connections with the distributed session cache, but enables NIST SP800-131A compliance for other client connections.

[dsess-cluster]
ssl-nist-compliance = no

[ssl]
nist-compliance = yes

Parent topic: Web server security configuration

Related concepts:

Cryptographic hardware for encryption and key storage

Prevention of vulnerability caused by cross-site scripting

Prevention of Cross-site Request Forgery (CSRF) attacks

Suppression of WebSEAL and back-end server identity

Platform for Privacy Preferences (P3P)

Related tasks:

Configuring WebSEAL to support only Suite B ciphers

Disabling HTTP methods

Prevention of vulnerability caused by cross-site scripting Prevention of vulnerability caused by cross-site scripting Cross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.cross-site scriptingpreventing vulnerabilityillegal-url-substrings stanzacross-site scriptingillegal-url-substrings stanzaWebSEAL provides limited protection against cross-site scripting for junctioned applications through URL string filtering. Other solutions, such as the Web Content Protection feature of the appliance, can also help protect against these types of attacks.Configuration of URL string filteringYou can configure WebSEAL to reject an incoming request if the request URL contains a defined string pattern. WebSEAL rejects incoming URL requests if they contain any of the string patterns that are defined in the [illegal-url-substrings] stanza.The [illegal-url-substrings] feature is deprecated. IBM might remove this feature in a subsequent release of the product.In the WebSEAL configuration file, add a separate entry in the [illegal-url-substrings] stanza to represent each string pattern that you want WebSEAL to reject. For example:[illegal-url-substrings] substring = <script substring = <applet substring = <embedIf WebSEAL detects any configured string fragment in the requested URL, WebSEAL rejects the request and returns a 400 "Bad Request" error page.WebSEAL, by default, filters strings that contain <script. If you require additional filtering, you must create the [illegal-url-substrings] stanza and list all substrings individually.You can completely disable the URL string filtering feature, including the default behavior, by placing an empty [illegal-url-substrings] stanza in the WebSEAL configuration file.Functional notes:Substring entries in the configuration file must be ASCII. WebSEAL decodes URLs before checking for the presence of these strings. Therefore, if these strings are present in the URL in another encoding, WebSEAL still filters them.WebSEAL locates these substrings by using a search that is not case sensitive.Substring filtering accommodates multi-byte characters.Web server security configurationCryptographic hardware for encryption and key storageConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Configuring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Suppression of WebSEAL and back-end server identityDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Platform for Privacy Preferences (P3P)

Prevention of vulnerability caused by cross-site scripting

Cross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.

WebSEAL provides limited protection against cross-site scripting for junctioned applications through URL string filtering. Other solutions, such as the Web Content Protection feature of the appliance, can also help protect against these types of attacks.

Configuration of URL string filtering

You can configure WebSEAL to reject an incoming request if the request URL contains a defined string pattern. WebSEAL rejects incoming URL requests if they contain any of the string patterns that are defined in the [illegal-url-substrings] stanza.

Note: The [illegal-url-substrings] feature is deprecated. IBM® might remove this feature in a subsequent release of the product.

In the WebSEAL configuration file, add a separate entry in the [illegal-url-substrings] stanza to represent each string pattern that you want WebSEAL to reject. For example:

[illegal-url-substrings]
substring = <script
substring = <applet
substring = <embed

If WebSEAL detects any configured string fragment in the requested URL, WebSEAL rejects the request and returns a 400 "Bad Request" error page.

WebSEAL, by default, filters strings that contain <script. If you require additional filtering, you must create the [illegal-url-substrings] stanza and list all substrings individually.

You can completely disable the URL string filtering feature, including the default behavior, by placing an empty [illegal-url-substrings] stanza in the WebSEAL configuration file.

Functional notes:

Substring entries in the configuration file must be ASCII. WebSEAL decodes URLs before checking for the presence of these strings. Therefore, if these strings are present in the URL in another encoding, WebSEAL still filters them.

WebSEAL locates these substrings by using a search that is not case sensitive.

Substring filtering accommodates multi-byte characters.

Parent topic: Web server security configuration

Related concepts:

Cryptographic hardware for encryption and key storage

Prevention of Cross-site Request Forgery (CSRF) attacks

Suppression of WebSEAL and back-end server identity

Platform for Privacy Preferences (P3P)

Related tasks:

Configuring WebSEAL to support only Suite B ciphers

Configuring NIST SP800-131A compliance

Disabling HTTP methods

Prevention of Cross-site Request Forgery (CSRF) attacksPrevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Cross-site request forgerypreventionCSRFattacksprevent vulnerabilityCSRF uses the trust that a site has in the browser of an authenticated user for malicious attacks. CSRF uses links or scripts to send involuntary HTTP requests to a target site where the user is authenticated. Unless precautions are taken, the WebSEAL management pages, such as /pkmslogout, are susceptible to a CSRF attack. For example, an attacker might get an authenticated WebSEAL user to involuntarily log out by getting their browser to follow a link to /pkmslogout. You can configure WebSEAL to help mitigate this type of vulnerability. Web server security configurationCryptographic hardware for encryption and key storageConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Configuring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Suppression of WebSEAL and back-end server identityDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Platform for Privacy Preferences (P3P)Secret token validationYou can configure WebSEAL to require that certain management operation requests include a secret token. WebSEAL uses the secret token in the received request to validate its authenticity. Referrer validationTo help mitigate CSRF attacks, you can configure WebSEAL to validate the referer header in incoming HTTP requests. WebSEAL compares this referer header with a list of configured allowed-referers to determine whether the request is valid. Reject unsolicited authentication requestsFor extra mitigation against cross-site request forgery (CSRF), you can configure WebSEAL to reject any unsolicited login requests. This configuration ensures that WebSEAL does not process login requests without first issuing a login form.

Prevention of Cross-site Request Forgery (CSRF) attacks

Cross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts.

CSRF uses the trust that a site has in the browser of an authenticated user for malicious attacks. CSRF uses links or scripts to send involuntary HTTP requests to a target site where the user is authenticated. Unless precautions are taken, the WebSEAL management pages, such as /pkmslogout, are susceptible to a CSRF attack. For example, an attacker might get an authenticated WebSEAL user to involuntarily log out by getting their browser to follow a link to /pkmslogout.

You can configure WebSEAL to help mitigate this type of vulnerability.

Secret token validation
You can configure WebSEAL to require that certain management operation requests include a secret token. WebSEAL uses the secret token in the received request to validate its authenticity.

Referrer validation
To help mitigate CSRF attacks, you can configure WebSEAL to validate the referer header in incoming HTTP requests. WebSEAL compares this referer header with a list of configured allowed-referers to determine whether the request is valid.

Reject unsolicited authentication requests
For extra mitigation against cross-site request forgery (CSRF), you can configure WebSEAL to reject any unsolicited login requests. This configuration ensures that WebSEAL does not process login requests without first issuing a login form.

Parent topic: Web server security configuration

Related concepts:

Cryptographic hardware for encryption and key storage

Prevention of vulnerability caused by cross-site scripting

Suppression of WebSEAL and back-end server identity

Platform for Privacy Preferences (P3P)

Related tasks:

Configuring WebSEAL to support only Suite B ciphers

Configuring NIST SP800-131A compliance

Disabling HTTP methods

Secret token validationSecret token validationYou can configure WebSEAL to require that certain management operation requests include a secret token. WebSEAL uses the secret token in the received request to validate its authenticity. CSRFpreventionsecret token validationenable-secret-token-validationacnt-mgt stanzaacnt-mgt stanzaenable-secret-token-validationSecret token validation affects the following WebSEAL management pages: /pkmslogin.form/pkmslogout/pkmslogout-nomas/pkmssu.form/pkmsskip/pkmsdisplace/pkmspaswd.formUse the enable-secret-token-validation configuration entry in the [acnt-mgt] stanza to enable secret token validation. By default, enable-secret-token-validation is set to false, which disables secret token validation. If you want WebSEAL to use secret token validation, set this entry to true:[acnt-mgt] enable-secret-token-validation = trueWhen secret token validation is enabled, WebSEAL adds a token to each session and validates the "token" query argument for these account management requests. For example, the request to /pkmslogout changes to pkmslogout?token=<value>, where <value> is the unique session token. This setting modifies the URLs for these WebSEAL management pages. Each of the affected management requests must contain a "token" argument with the current session token. For example, /pkmslogout?token=a861582a-c445-4462-94c9-b1074e135b9f. If secret token validation is enabled and the token argument is missing from the request or does not match the real session token, WebSEAL returns a "400 Bad Request" error page.If you are using secret token validation then WebSEAL includes the session token as the tagvalue_session_index attribute in the user credential. WebSEAL provides a CREDATTR macro that you can use to access a credential attribute and insert it into the following locations:Generated HTML pages (for example, /pkmshelp). Local response redirect URLs. See Macro support for local response redirection.HTTP response headers (http-rsp-header configuration item). See Adding custom headers to server response pagesYou can add headers, which contain information about a custom response, to generated server responses. . To reference the secret token, use the CREDATTR{tagvalue_session_index} macro. Secret token validation does not affect the CDSSO or eCSSO functionality in WebSEAL. Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts.

Secret token validation

You can configure WebSEAL to require that certain management operation requests include a secret token. WebSEAL uses the secret token in the received request to validate its authenticity.

Secret token validation affects the following WebSEAL management pages:

/pkmslogin.form

/pkmslogout

/pkmslogout-nomas

/pkmssu.form

/pkmsskip

/pkmsdisplace

/pkmspaswd.form

Use the enable-secret-token-validation configuration entry in the [acnt-mgt] stanza to enable secret token validation. By default, enable-secret-token-validation is set to false, which disables secret token validation.

If you want WebSEAL to use secret token validation, set this entry to true:

[acnt-mgt]
enable-secret-token-validation = true

When secret token validation is enabled, WebSEAL adds a token to each session and validates the "token" query argument for these account management requests. For example, the request to /pkmslogout changes to pkmslogout?token=<value>, where <value> is the unique session token.

Note: This setting modifies the URLs for these WebSEAL management pages. Each of the affected management requests must contain a "token" argument with the current session token. For example, /pkmslogout?token=a861582a-c445-4462-94c9-b1074e135b9f.

If secret token validation is enabled and the token argument is missing from the request or does not match the real session token, WebSEAL returns a "400 Bad Request" error page.

If you are using secret token validation then WebSEAL includes the session token as the tagvalue_session_index attribute in the user credential. WebSEAL provides a CREDATTR macro that you can use to access a credential attribute and insert it into the following locations:

Generated HTML pages (for example, /pkmshelp).

Local response redirect URLs. See Macro support for local response redirection.

HTTP response headers (http-rsp-header configuration item). See Adding custom headers to server response pages.

To reference the secret token, use the CREDATTR{tagvalue_session_index} macro.

Note: Secret token validation does not affect the CDSSO or eCSSO functionality in WebSEAL.

Parent topic: Prevention of Cross-site Request Forgery (CSRF) attacks

Referrer validationReferrer validationTo help mitigate CSRF attacks, you can configure WebSEAL to validate the referer header in incoming HTTP requests. WebSEAL compares this referer header with a list of configured allowed-referers to determine whether the request is valid. CSRFpreventionreferrer validationallowed-referersacnt-mgt stanzaacnt-mgt stanzaallowed referersReferrer validation affects the following WebSEAL management pages: /pkmslogout/pkmslogout-nomas/pkmspasswd.form/pkmscdsso/pkmsvouchfor/pkmsskip/pkmsdisplaceUse the allowed-referers configuration entry in the [acnt-mgt] stanza to define valid referer headers. The value for this entry can contain alphanumeric characters, spaces, periods, and wildcard characters.You can specify this entry multiple times to define multiple valid referer headers. WebSEAL uses all of these entries to validate the referrer.You can set the allowed-referers to %HOST%, which is a special filter. This filter indicates to WebSEAL that a referrer is valid if the host name portion of the referer HTTP Request header matches the host HTTP Request header.If you want WebSEAL to use referrer validation, you must include at least one allowed-referers entry. For example:[acnt-mgt] allowed-referers = %HOST%When attempting to validate an incoming request, if WebSEAL does not find an allowed-referers entry that matches the referer header in the request then the request fails. WebSEAL returns an error page. If there are no allowed-referers entries, referrer validation is disabled and WebSEAL does not validate the referer headers in incoming requests.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts.

Referrer validation

To help mitigate CSRF attacks, you can configure WebSEAL to validate the referer header in incoming HTTP requests. WebSEAL compares this referer header with a list of configured allowed-referers to determine whether the request is valid.

Referrer validation affects the following WebSEAL management pages:

/pkmslogout

/pkmslogout-nomas

/pkmspasswd.form

/pkmscdsso

/pkmsvouchfor

/pkmsskip

/pkmsdisplace

Use the allowed-referers configuration entry in the [acnt-mgt] stanza to define valid referer headers. The value for this entry can contain alphanumeric characters, spaces, periods, and wildcard characters.

Note: You can specify this entry multiple times to define multiple valid referer headers. WebSEAL uses all of these entries to validate the referrer.

You can set the allowed-referers to %HOST%, which is a special filter. This filter indicates to WebSEAL that a referrer is valid if the host name portion of the referer HTTP Request header matches the host HTTP Request header.

If you want WebSEAL to use referrer validation, you must include at least one allowed-referers entry. For example:

[acnt-mgt]
allowed-referers = %HOST%

When attempting to validate an incoming request, if WebSEAL does not find an allowed-referers entry that matches the referer header in the request then the request fails. WebSEAL returns an error page.

Note: If there are no allowed-referers entries, referrer validation is disabled and WebSEAL does not validate the referer headers in incoming requests.

Parent topic: Prevention of Cross-site Request Forgery (CSRF) attacks

Reject unsolicited authentication requestsReject unsolicited authentication requestsFor extra mitigation against cross-site request forgery (CSRF), you can configure WebSEAL to reject any unsolicited login requests. This configuration ensures that WebSEAL does not process login requests without first issuing a login form.CSRFpreventionallow-unsolicited-loginsCross-site request forgerypreventionallow-unsolicited-loginsserver stanzaserversallowing unsolicited loginsThe following steps outline the general process for a client to authenticate to WebSEAL and access a protected resource:The client requests the protected resource.WebSEAL detects that the client is not authenticated so WebSEAL returns a login form to the client.The client enters login information and submits the form to WebSEAL.WebSEAL processes the login information as follows:Authenticates the user.Creates a session.Sends a redirect to the requested resource.The client requests the protected resource.WebSEAL detects that the user is authenticated and returns the resource to the client.By default, it is possible for a client to skip directly to step 3 and initiate authentication with WebSEAL by sending through an unsolicited login request. However, you can configure WebSEAL to reject these unsolicited requests. You can set allow-unsolicited-logins in the [server] stanza to no to ensure that the first two steps are required for a client to gain access to a resource. If you set this option to no, WebSEAL must always issue a login form to unauthenticated clients. By default, allow-unsolicited-logins is set to yes, which means that WebSEAL does accept unsolicited authentication requests. Set this entry to no if you are concerned that CSRF might cause a user to inadvertently authenticate with authentication data provided by an attacker. [server] allow-unsolicited-logins = noPrevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts.

Reject unsolicited authentication requests

For extra mitigation against cross-site request forgery (CSRF), you can configure WebSEAL to reject any unsolicited login requests. This configuration ensures that WebSEAL does not process login requests without first issuing a login form.

The following steps outline the general process for a client to authenticate to WebSEAL and access a protected resource:

The client requests the protected resource.

WebSEAL detects that the client is not authenticated so WebSEAL returns a login form to the client.

The client enters login information and submits the form to WebSEAL.

WebSEAL processes the login information as follows:

Authenticates the user.

Creates a session.

Sends a redirect to the requested resource.

The client requests the protected resource.

WebSEAL detects that the user is authenticated and returns the resource to the client.

By default, it is possible for a client to skip directly to step 3 and initiate authentication with WebSEAL by sending through an unsolicited login request. However, you can configure WebSEAL to reject these unsolicited requests. You can set allow-unsolicited-logins in the [server] stanza to no to ensure that the first two steps are required for a client to gain access to a resource. If you set this option to no, WebSEAL must always issue a login form to unauthenticated clients.

By default, allow-unsolicited-logins is set to yes, which means that WebSEAL does accept unsolicited authentication requests.

Set this entry to no if you are concerned that CSRF might cause a user to inadvertently authenticate with authentication data provided by an attacker.

[server]
allow-unsolicited-logins = no

Parent topic: Prevention of Cross-site Request Forgery (CSRF) attacks

Suppression of WebSEAL and back-end server identity Suppression of WebSEAL and back-end server identity suppress-server-identity stanza entryHTTPsuppressing server identityserversidentityHTTPsuppressingheadersHTTPThis section contains the following topics:Web server security configurationCryptographic hardware for encryption and key storageConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Configuring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Disabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Platform for Privacy Preferences (P3P)Suppressing WebSEAL server identityHTTP responses normally include a Server header containing the identity and version of the server that is sending the response.Suppressing back-end application server identity

Suppression of WebSEAL and back-end server identity

This section contains the following topics:

Suppressing WebSEAL server identity
HTTP responses normally include a Server header containing the identity and version of the server that is sending the response.

Suppressing back-end application server identity

Parent topic: Web server security configuration

Related concepts:

Cryptographic hardware for encryption and key storage

Prevention of vulnerability caused by cross-site scripting

Prevention of Cross-site Request Forgery (CSRF) attacks

Platform for Privacy Preferences (P3P)

Related tasks:

Configuring WebSEAL to support only Suite B ciphers

Configuring NIST SP800-131A compliance

Disabling HTTP methods

Suppressing WebSEAL server identitySuppressing WebSEAL server identitySuppressing WebSEAL server identity in IBM Security Access Manager for WebHTTP responses normally include a Server header containing the identity and version of the server that is sending the response.WebSEALsuppress server identityserverssuppressing identity The following example illustrates the header output for a response sent from WebSEAL: Content-Type: text/html Date: Tue, 09 Nov 2004 02:34:18 GMT Content-length: 515 Server: WebSEAL/6.0.0 Last-Modified: Thu, 04 Nov 2004 08:03:46 GMT Connection: close For security reasons, you might want WebSEAL to suppress the Server header in its responses to clients. To suppress WebSEAL server identity in HTTP server responses, set the suppress-server-identity stanza entry in the [server] stanza of the WebSEAL configuration file to "yes": [server] suppress-server-identity = yes The default setting is "no".Suppression of WebSEAL and back-end server identity

Suppressing WebSEAL server identity

HTTP responses normally include a Server header containing the identity and version of the server that is sending the response.

About this task

The following example illustrates the header output for a response sent from WebSEAL:

Content-Type: text/html
Date: Tue, 09 Nov 2004 02:34:18 GMT
Content-length: 515
Server: WebSEAL/6.0.0
Last-Modified: Thu, 04 Nov 2004 08:03:46 GMT
Connection: close

For security reasons, you might want WebSEAL to suppress the Server header in its responses to clients.

To suppress WebSEAL server identity in HTTP server responses, set the suppress-server-identity stanza entry in the [server] stanza of the WebSEAL configuration file to "yes":

[server]
suppress-server-identity = yes

The default setting is "no".

Parent topic: Suppression of WebSEAL and back-end server identity

Suppressing back-end application server identitySuppressing back-end application server identityHTTPheadersserversuppressing server identityserversheadersHTTPidentityHTTPsuppressingsuppress-backend-server-identity stanza entry HTTP responses normally include a Server header containing the identity and version of the server that is sending the response. The following example illustrates the header output for a response sent from a back-end junctioned application server: Content-Type: text/html Date: Tue, 09 Nov 2004 03:34:18 GMT Content-Length: 515 Server: IBM_HTTP_SERVER/1.3.19Apache/1.3.20 (Win32) Last-Modified: Thu, 04 Nov 2004 09:03:46 GMT Connection: close To suppress back-end application server identity in HTTP server responses, set the suppress-backend-server-identity stanza entry in the [server] stanza of the WebSEAL configuration file to "yes": [server] suppress-backend-server-identity = yes The default setting is "no".Suppression of WebSEAL and back-end server identity

Suppressing back-end application server identity

About this task

HTTP responses normally include a Server header containing the identity and version of the server that is sending the response. The following example illustrates the header output for a response sent from a back-end junctioned application server:

Content-Type: text/html
Date: Tue, 09 Nov 2004 03:34:18 GMT
Content-Length: 515
Server: IBM_HTTP_SERVER/1.3.19Apache/1.3.20 (Win32)
Last-Modified: Thu, 04 Nov 2004 09:03:46 GMT
Connection: close

To suppress back-end application server identity in HTTP server responses, set the suppress-backend-server-identity stanza entry in the [server] stanza of the WebSEAL configuration file to "yes":

[server]
suppress-backend-server-identity = yes

The default setting is "no".

Parent topic: Suppression of WebSEAL and back-end server identity

Disabling HTTP methodsDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. HTTPmethodshttp-method-disabled-local stanza entryhttp-method-disabled-remote stanza entryModify the WebSEAL configuration file to disable specific HTTP methods. Use the http-method-disabled-local stanza entry in the [server] stanza to disable the use of specific methods to request resources over a local junction. Use the http-method-disabled-remote stanza entry in the [server] stanza to disable the use of specific methods to request remote resources.You can use a comma (,) to separate multiple methods. For example, the following configuration entry blocks access to the TRACE and PUT methods over local junctions:[server] http-method-disabled-local = TRACE,PUT By default, WebSEAL disables the TRACE, PUT, DELETE, CONNECT methods. The default values for these configuration entries are as follows:[server] http-method-disabled-local = TRACE,PUT,DELETE,CONNECT http-method-disabled-remote = TRACE,PUT,DELETE,CONNECT You can enable a blocked method by removing the method name from these two entries in the WebSEAL configuration file. To enable all HTTP methods for local responses, set the following entry: [server] http-method-disabled-local = To enable all HTTP methods for junctioned responses, set the following entry: [server] http-method-disabled-remote = Web server security configurationCryptographic hardware for encryption and key storageConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Configuring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Suppression of WebSEAL and back-end server identityPlatform for Privacy Preferences (P3P)

Disabling HTTP methods

You can block the use of HTTP methods to request local or remote resources to reduce security vulnerability.

About this task

Modify the WebSEAL configuration file to disable specific HTTP methods.

Procedure

Use the http-method-disabled-local stanza entry in the [server] stanza to disable the use of specific methods to request resources over a local junction.

Use the http-method-disabled-remote stanza entry in the [server] stanza to disable the use of specific methods to request remote resources.

You can use a comma (,) to separate multiple methods. For example, the following configuration entry blocks access to the TRACE and PUT methods over local junctions:

[server]
http-method-disabled-local = TRACE,PUT

By default, WebSEAL disables the TRACE, PUT, DELETE, CONNECT methods. The default values for these configuration entries are as follows:

[server]
http-method-disabled-local  = TRACE,PUT,DELETE,CONNECT
http-method-disabled-remote = TRACE,PUT,DELETE,CONNECT

Note:

You can enable a blocked method by removing the method name from these two entries in the WebSEAL configuration file.

To enable all HTTP methods for local responses, set the following entry:

[server]
http-method-disabled-local =

To enable all HTTP methods for junctioned responses, set the following entry:

[server]
http-method-disabled-remote =

Parent topic: Web server security configuration

Related concepts:

Cryptographic hardware for encryption and key storage

Prevention of vulnerability caused by cross-site scripting

Prevention of Cross-site Request Forgery (CSRF) attacks

Suppression of WebSEAL and back-end server identity

Platform for Privacy Preferences (P3P)

Related tasks:

Configuring WebSEAL to support only Suite B ciphers

Configuring NIST SP800-131A compliance

Platform for Privacy Preferences (P3P) Platform for Privacy Preferences (P3P) P3Poverviewplatform for privacy preferencesThis section contains the following topics:Web server security configurationCryptographic hardware for encryption and key storageConfiguring WebSEAL to support only Suite B ciphersYou can configure WebSEAL to use only Suite B ciphers when negotiating an SSL connection.Configuring NIST SP800-131A complianceSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. You can configure WebSEAL to comply with NIST SP800-131A when it is negotiating SSL connections.Prevention of vulnerability caused by cross-site scriptingCross-site scripting is a known technique for deploying malicious scripts on browsers. Web servers that incorrectly reflect user-supplied data to the browser without properly escaping the data are vulnerable to this type of attack.Prevention of Cross-site Request Forgery (CSRF) attacksCross-site request forgery (CSRF) is a type of malicious website attack. A CSRF attack is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. Suppression of WebSEAL and back-end server identityDisabling HTTP methodsYou can block the use of HTTP methods to request local or remote resources to reduce security vulnerability. Compact policy overviewCompact policy declarationJunction header preservationDefault compact policy in the P3P headerConfiguring the P3P headerSpecifying a custom P3P compact policyP3P configuration troubleshooting

Platform for Privacy Preferences (P3P)

This section contains the following topics:

Compact policy overview

Compact policy declaration

Junction header preservation

Default compact policy in the P3P header

Configuring the P3P header

Specifying a custom P3P compact policy

P3P configuration troubleshooting

Parent topic: Web server security configuration

Related concepts:

Cryptographic hardware for encryption and key storage

Prevention of vulnerability caused by cross-site scripting

Prevention of Cross-site Request Forgery (CSRF) attacks

Suppression of WebSEAL and back-end server identity

Related tasks:

Configuring WebSEAL to support only Suite B ciphers

Configuring NIST SP800-131A compliance

Disabling HTTP methods

Compact policy overviewCompact policy overviewP3Ppolicy overviewcompact policiesoverviewWebSEAL supports the Platform for Privacy Preferences (P3P) 1.0 specification. P3P is a standard for the declaration of privacy policies in a machine-readable format. The standard allows user agents to make decisions on the part of the user regarding whether to access certain URIs or accept certain cookies based on the policy presented by the Web site. In the absence of a policy, the decision can be made based on a set of assumptions about the site's policy.Commercial browsers support P3P, particularly as part of the decision process for accepting or rejecting cookies. Microsoft Internet Explorer 6 has P3P-based cookie filtering enabled by default. Browsers based on Mozilla provide optional P3P cookie filtering. WebSEAL provides P3P support to ensure that these browsers accept WebSEAL session cookies.The P3P specification describes a compact policy and a full policy. A compact policy is a subset of a full policy. WebSEAL provides a default compact policy and also provides configuration settings to enable customization of the compact policy. WebSEAL does not provide a full policy. Full policies are specific to the vendor, application, or security environment into which WebSEAL is deployed. Implementation of a full policy is the responsibility of the vendor (service provider). WebSEAL includes a configuration setting that can be used to point clients to the location of a full policy. The P3P specification states that an HTTP header can have only a single P3P header (additional P3P headers are ignored). However, an HTTP response can have multiple cookies. Therefore, the compact policy specified in the HTTP header applies to all cookies in the response. Because there can be only a single policy, the policy must represent the most strict of the actual policies for the cookies. For WebSEAL, this means, for example, that if session cookies are accepted in a response but failover cookies are not, the worst case P3P policy should be returned for all cookies. The worst case is defined to be the minimum set of conditions that would cause the browser to reject the cookie.WebSEAL returns four types of cookies to the user agent (browser):Session cookieFailover cookiee-community cookieLTPA cookieThere is no need to configure policy for the e-community cookie. The cookie contents are limited to specifying the location of the Web server to which the user authenticated. This cookie contains no information that identifies the user.The session cookie links to session data, and the failover cookie contains enough session information to enable reconstruction of the session. The session cookie is intended only for the origin server, is not retained past the end of the session, and assists in the process of session maintenance. The failover cookie is intended for the failover (replicated) server, is not retained past the end of the session, and also assists in the process of session maintenance. Thus, session and failover cookies have the same P3P policy. This means that the combined worst case policy for the cookies is the session cookie policy.Platform for Privacy Preferences (P3P)

Compact policy overview

WebSEAL supports the Platform for Privacy Preferences (P3P) 1.0 specification. P3P is a standard for the declaration of privacy policies in a machine-readable format. The standard allows user agents to make decisions on the part of the user regarding whether to access certain URIs or accept certain cookies based on the policy presented by the Web site. In the absence of a policy, the decision can be made based on a set of assumptions about the site's policy.

Commercial browsers support P3P, particularly as part of the decision process for accepting or rejecting cookies. Microsoft Internet Explorer 6 has P3P-based cookie filtering enabled by default. Browsers based on Mozilla provide optional P3P cookie filtering. WebSEAL provides P3P support to ensure that these browsers accept WebSEAL session cookies.

The P3P specification describes a compact policy and a full policy. A compact policy is a subset of a full policy. WebSEAL provides a default compact policy and also provides configuration settings to enable customization of the compact policy. WebSEAL does not provide a full policy. Full policies are specific to the vendor, application, or security environment into which WebSEAL is deployed. Implementation of a full policy is the responsibility of the vendor (service provider). WebSEAL includes a configuration setting that can be used to point clients to the location of a full policy.

The P3P specification states that an HTTP header can have only a single P3P header (additional P3P headers are ignored). However, an HTTP response can have multiple cookies. Therefore, the compact policy specified in the HTTP header applies to all cookies in the response. Because there can be only a single policy, the policy must represent the most strict of the actual policies for the cookies. For WebSEAL, this means, for example, that if session cookies are accepted in a response but failover cookies are not, the worst case P3P policy should be returned for all cookies. The worst case is defined to be the minimum set of conditions that would cause the browser to reject the cookie.

WebSEAL returns four types of cookies to the user agent (browser):

Session cookie

Failover cookie

e-community cookie

LTPA cookie

There is no need to configure policy for the e-community cookie. The cookie contents are limited to specifying the location of the Web server to which the user authenticated. This cookie contains no information that identifies the user.

The session cookie links to session data, and the failover cookie contains enough session information to enable reconstruction of the session. The session cookie is intended only for the origin server, is not retained past the end of the session, and assists in the process of session maintenance. The failover cookie is intended for the failover (replicated) server, is not retained past the end of the session, and also assists in the process of session maintenance. Thus, session and failover cookies have the same P3P policy. This means that the combined worst case policy for the cookies is the session cookie policy.

Parent topic: Platform for Privacy Preferences (P3P)

Compact policy declarationCompact policy declarationP3Ppolicy declarationcompact policiesdeclarationThe WebSEAL configuration file provides a set of configuration options that match the compact policy XML syntax as specified in the World Wide Web Consortium Platform for Privacy Preferences specification. The complete specification can be accessed at the following URL:http://www.w3.org/TR/P3P/WebSEAL provides configuration file entries that map to the following XML elements in the compact policy:access Indicates whether the site provides access to various kinds of information. categories Type of information stored in the cookie.disputes Specifies whether the full P3P policy contains some information regarding disputes over the information contained within the cookie.non-identifiable Signifies that either no data is collected (including Web logs), or that the organization collecting the data will make the data anonymous. purpose Purposes for data processing relevant to the Web.recipients Legal entity, or domain, beyond the service provider and its agents where data can be distributed. remedies Remedies in case a policy breach occurs. retention Type of retention policy in effect.p3p-element Specifies any elements to add to the P3P header in addition to the compact policy. This element can be used to supply a reference to a full XML policy.The values for purpose (except current) and recipients (except ours) have an additional option describing how the cookie data can be used. This option defines whether the user is given a choice to opt-in or opt-out.Platform for Privacy Preferences (P3P)

Compact policy declaration

The WebSEAL configuration file provides a set of configuration options that match the compact policy XML syntax as specified in the World Wide Web Consortium Platform for Privacy Preferences specification. The complete specification can be accessed at the following URL:

http://www.w3.org/TR/P3P/

WebSEAL provides configuration file entries that map to the following XML elements in the compact policy:

access

Indicates whether the site provides access to various kinds of information.

categories

Type of information stored in the cookie.

disputes

Specifies whether the full P3P policy contains some information regarding disputes over the information contained within the cookie.

non-identifiable

Signifies that either no data is collected (including Web logs), or that the organization collecting the data will make the data anonymous.

purpose

Purposes for data processing relevant to the Web.

recipients

Legal entity, or domain, beyond the service provider and its agents where data can be distributed.

remedies

Remedies in case a policy breach occurs.

retention

Type of retention policy in effect.

p3p-element

Specifies any elements to add to the P3P header in addition to the compact policy. This element can be used to supply a reference to a full XML policy.

The values for purpose (except current) and recipients (except ours) have an additional option describing how the cookie data can be used. This option defines whether the user is given a choice to opt-in or opt-out.

Parent topic: Platform for Privacy Preferences (P3P)

Junction header preservationJunction header preservationP3Pheaderspreservationjunctionsheader preservationWebSEAL enables you to specify whether P3P headers from junctioned applications are preserved or replaced. Note that this is not part of the P3P compact policy, but is a WebSEAL function.The configuration file entry is:preserve-p3p-policy stanza entry[p3p-header] preserve-p3p-policy = {yes|no}The default setting is "no". This means that P3P headers from junctioned servers are replaced.WebSEAL replaces back-end P3P policy headers by default to ensure that WebSEAL cookies are not excluded due to a more strict policy set by the back-end server. When using the default setting, you might find that cookies that the back-end server sets are not allowed due to the WebSEAL compact policy. In this case, you should choose one of the following options:Set preserve-p3p-policy = yes to force WebSEAL to preserve the compact policy set by the back-end server.Modify the WebSEAL compact policy header to make the policy more permissive, so that back-end cookies are allowed.When WebSEAL processes responses from back-end servers, WebSEAL's actions can include the addition of a cookie to the response. This addition occurs when the WebSEAL junction has been created to generate junction cookies. These cookies are used to map URLs across junctions, to ensure connectivity between the browser and the back-end server. When the administrator chooses to preserve the compact policy set by the back-end server (preserve-p3p-policy = yes), the administrator must ensure that the compact policy is permissive enough to accept the addition of the WebSEAL junction cookie. When the compact policy forbids the addition of the junction cookie, the URL requests from the browser will not successfully resolve to the URLs on the back-end server.Platform for Privacy Preferences (P3P)

Junction header preservation

WebSEAL enables you to specify whether P3P headers from junctioned applications are preserved or replaced. Note that this is not part of the P3P compact policy, but is a WebSEAL function.

The configuration file entry is:

[p3p-header]
preserve-p3p-policy = {yes|no}

The default setting is "no". This means that P3P headers from junctioned servers are replaced.

WebSEAL replaces back-end P3P policy headers by default to ensure that WebSEAL cookies are not excluded due to a more strict policy set by the back-end server.

When using the default setting, you might find that cookies that the back-end server sets are not allowed due to the WebSEAL compact policy. In this case, you should choose one of the following options:

Set preserve-p3p-policy = yes to force WebSEAL to preserve the compact policy set by the back-end server.

Modify the WebSEAL compact policy header to make the policy more permissive, so that back-end cookies are allowed.

When WebSEAL processes responses from back-end servers, WebSEAL's actions can include the addition of a cookie to the response. This addition occurs when the WebSEAL junction has been created to generate junction cookies. These cookies are used to map URLs across junctions, to ensure connectivity between the browser and the back-end server. When the administrator chooses to preserve the compact policy set by the back-end server (preserve-p3p-policy = yes), the administrator must ensure that the compact policy is permissive enough to accept the addition of the WebSEAL junction cookie. When the compact policy forbids the addition of the junction cookie, the URL requests from the browser will not successfully resolve to the URLs on the back-end server.

Parent topic: Platform for Privacy Preferences (P3P)

Default compact policy in the P3P header Default compact policy in the P3P header P3Pdefault policydefaultcompact policiesP3Pheadersdefault compact policyWebSEAL adds a P3P header to every response in which cookies are set. The header contains a P3P Compact Policy. The policy is a sequence of terms that describe the policy regarding information contained within the cookies in the response. The following WebSEAL configuration file entries represent the default P3P compact policy:[p3p-header] access = none purpose = current purpose = other-purpose:opt-in recipients = ours retention = no-retention categories = uniqueidThe default configuration file entries result in a P3P header with the following contents:P3P: CP="NON CUR OTPi OUR NOR UNI"The following table explains the values in the default policy header:P3P default header valuesTermDefinitionNONUser has no access to information either in the cookie or linked to by the cookie. CURCookie helps provide the current service. The current service is the access to the protected Web site.OTPiCookie provides another service, to which the user has opted-in.OURThe Web site itself is the only recipient of the cookie and the information linked to by the cookie.NORNeither the cookie data nor the data to which it links is retained after the user logs out or after the user session expires.UNIThe cookie uses a unique identifier that represents the user, by using the session ID and the user name.Platform for Privacy Preferences (P3P)

Default compact policy in the P3P header

WebSEAL adds a P3P header to every response in which cookies are set. The header contains a P3P Compact Policy. The policy is a sequence of terms that describe the policy regarding information contained within the cookies in the response.

The following WebSEAL configuration file entries represent the default P3P compact policy:

[p3p-header]
access = none
purpose = current
purpose = other-purpose:opt-in
recipients = ours
retention = no-retention
categories = uniqueid

The default configuration file entries result in a P3P header with the following contents:

P3P: CP="NON CUR OTPi OUR NOR UNI"

The following table explains the values in the default policy header:

Table 15. P3P default header values

Term | Definition
NON | User has no access to information either in the cookie or linked to by the cookie.
CUR | Cookie helps provide the current service. The current service is the access to the protected Web site.
OTPi | Cookie provides another service, to which the user has opted-in.
OUR | The Web site itself is the only recipient of the cookie and the information linked to by the cookie.
NOR | Neither the cookie data nor the data to which it links is retained after the user logs out or after the user session expires.
UNI | The cookie uses a unique identifier that represents the user, by using the session ID and the user name.

Parent topic: Platform for Privacy Preferences (P3P)

Configuring the P3P headerConfiguring the P3P headerP3Pconfigurationaccesscategoriesdisputesremediesnon-identifiablepurposerecipientretentionfull compact policyheadersconfiguration Administrators who deploy WebSEAL servers as part of the security solution for their Web servers must specify the P3P compact policy for their site. This step requires determining policy for each of the privacy settings defined by the P3P specification. WebSEAL provides a default policy that is accepted by the default settings for the Microsoft Internet Explorer 6 browser. Web administrators should modify the default policy as needed to match the site policies for handling of user data in cookies. Web administrators should test use of their policies with Internet Explorer 6 to ensure that the WebSEAL cookies continue to be accepted by Internet Explorer 6 browsers.Web administrators should consult the P3P specification when defining their site policy.Multiple values are allowed for each configuration entry, with the exception of the entries that require a value of "yes" or "no". When a particular configuration entry is not declared, no indicators are added to the compact policy for that entry.To configure the P3P compact policy for use with WebSEAL, complete the following steps:Open the WebSEAL configuration file for editing. Go to the [server] stanza.Decide if P3P headers from junctioned servers will be replaced or preserved. Set the following value:[p3p-header] preserve-p3p-policy = {yes|no}The default value is "no". Set this to "yes" if you want to preserve P3P headers. For more information, see Junction header preservationGo to the [p3p-header] stanza. Specify the access that the user will have to the information in the cookie. Set the value for the following entry:[p3p-header] access = {none|all|nonident|contact-and-other|ident-contact|other-ident}. The default setting is: [p3p-header] access = noneSupported values for the access entryValueDescriptionnoneNo access to identified data is given. allAccess is given to all identified data.nonidentWeb site does not collect identified data. contact-and-otherAccess is given to identified online and physical contact information as well as to certain other identified data.ident-contactAccess is given to identified online and physical contact information. For example, users can access things such as a postal address. other-identAccess is given to certain other identified data. For example, users can access things such as their online account charges.Specify the type of information stored in the cookies or linked to by the cookies. Set the value for the following entry: [p3p-header] categories = {physical|online |uniqueid|purchase|financial|computer |navigation| interactive|demographic |content|state|political|health |preference|location| government|other-category} The default setting is:[p3p-header] categories = uniqueid Supported values for the categories entryValueDescriptionphysicalInformation that allows an individual to be contacted or located in the physical world. For example, telephone number or address.onlineInformation that allows an individual to be contacted or located on the Internet. uniqueidNon-financial identifiers, excluding government-issued identifiers, issued for purposes of consistently identifying or recognizing the individual.purchaseInformation actively generated by the purchase of a product or service, including information about the method of payment. financialInformation about an individual's finances including account status and activity information such as account balance, payment or overdraft history, and information about an individual's purchase or use of financial instruments including credit or debit card information. computerInformation about the computer system that the individual is using to access the network. For example, IP number, domain name, browser type, or operating system. navigationData passively generated by browsing the Web site. For example, which pages are visited, and how long users stay on each page.interactiveData actively generated from or reflecting explicit interactions with a service provider through its site. For example, queries to a search engine, or logs of account activity. demographicData about an individual's characteristics. For example, gender, age, and income. contentThe words and expressions contained in the body of a communication. For example, the text of email, bulletin board postings, or chat room communications.stateMechanisms for maintaining a stateful session with a user or automatically recognizing users who have visited a particular site or accessed particular content previously. For example, HTTP cookies. politicalMembership in or affiliation with groups such as religious organizations, trade unions, professional associations and political parties. healthInformation about an individual's physical or mental health, sexual orientation, use or inquiry into health care services or products, and purchase of health care services or products.preferenceData about an individual's likes and dislikes. For example, favorite color or musical tastes.locationInformation that can be used to identify an individual's current physical location and track them as their location changes. For example, Global Positioning System position data.governmentIdentifiers issued by a government for purposes of consistently identifying the individual.other-categoryOther types of data not captured by the above definitions. Specify whether the full P3P policy contains some information regarding disputes over the information contained within the cookie. Set the value for the following entry:[p3p-header] disputes = {yes|no}The disputes entry is not specified by default in the WebSEAL configuration file. The P3P specification states that when the dispute entry is not specified, the default value no is automatically assigned.Supported values for the disputes entryValueDescriptionyes The full P3P policy contains information regarding disputes over the information contained within the cookie.noThe full P3P policy does not contain information regarding disputes over the information contained within the cookie.Specify the types of remedies in case a policy breach occurs. Set the value for the following entry:[p3p-header] remedies = {correct|money|law}The default setting is: [p3p-header] remedies = correctSupported values for the remedies entryValueDescriptioncorrectErrors or wrongful actions arising in connection with the privacy policy will be remedied by the service.moneyIf the service provider violates its privacy policy, it will pay the individual an amount specified in the human readable privacy policy or the amount of damages. lawRemedies for breaches of the policy statement will be determined based on the law referenced in the human readable description. Specify either that no data is collected (including Web logs), or that the organization collecting the data will make anonymous any information that identifies the user. Set the value for the following entry:[p3p-header] non-identifiable = {yes|no}The non-identifiable entry is not specified in the WebSEAL configuration file. The P3P specification states that when the non-identifiableentry is not specified, the default value is automatically assigned no.Supported values for the non-identifiable entryValueDescriptionyesData that is collected identifies the user.noNo data is collected (including Web logs), or the information collected does not identify the user.Specify the purpose of the information in the cookie. Set the value for the following entry:[p3p-header] purpose = {current|admin|develop|tailoring|pseudo-analysis|pseudo-decision| individual-analysis|individual-decision|contact|historical| telemarketing|other-purpose} [:[opt-in|opt-out|always]]The default setting is: [p3p-header] purpose = currentSupported values for the purpose entryValueDescriptioncurrentInformation can be used by the service provider to complete the activity for which it was provided.adminInformation can be used for the technical support of the Web site and its computer system. developInformation can be used to enhance, evaluate, or otherwise review the site, service, product, or market. tailoringInformation can be used to tailor or modify content or design of the site where the information is used only for a single visit to the site pseudo-analysisInformation can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals for purpose of research, analysis and reporting. pseudo-decisionInformation can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals to make a decision that directly affects that individual.individual-analysisInformation can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data for the purpose of research, analysis and reporting. individual-decisionInformation can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data to make a decision that directly affects that individual. contactInformation can be used to contact the individual, through a communications channel other than voice telephone, for the promotion of a product or service. historicalInformation can be archived or stored for the purpose of preserving social history as governed by an existing law or policy. telemarketingInformation can be used to contact the individual with a voice telephone call for promotion of a product or service. other-purposeInformation can be used in other ways not captured by the above definitions.For each value specified for purpose, except the value current, you can optionally specify the opt-in policy. The syntax consists of a colon ( : ) immediately following the purpose value, followed by one of the supported values for the opt-in policy. For example: [p3p-header] purpose = telemarketing:opt-in. The following table lists the supported values:Supported values for the opt-in or opt-out policyValueDescriptionopt-inData can be used for this purpose only when the user affirmatively requests this use.opt-outData can be used for this purpose unless the user requests that it not be used in this way.alwaysUsers cannot opt-in or opt-out of this use of their data.This is the default value. When the opt-in policy is not specified, the always policy applies.Specify the recipients of the information in the cookie. Set the value for the following entry (enter recipient value on one line):[p3p-header] recipient = {ours|delivery|same|unrelated|public|other-recipient} [:[opt-in|opt-out|always]]The default setting is: [p3p-header] recipient = oursSupported values for the recipient entryValueDescriptionoursOurselves and/or entities acting as our agents, or entities for whom we are acting as an agent. An agent is a third party that processes data only on behalf of the service provider. deliveryLegal entities performing delivery services that may use data for purposes other than completion of the stated purpose.sameLegal entities following our practices. These are legal entities who use the data on their own behalf under equable practices.unrelatedUnrelated third parties. These are legal entities whose data usage practices are not known by the original service provider. publicPublic forums. These are public forums such as bulletin boards, public directories, or commercial CD-ROM directories. other-recipientLegal entities following different practices. These are legal entities that are constrained by and accountable to the original service provider, but may use the data in a way not specified in the service provider's practices.For each value specified for recipient, excepting ours, you can optionally specify the opt-in policy. The syntax consists of a colon ( : ) immediately following the recipient, followed by one of the supported values for the opt-in policy. For example:[p3p-header] recipient = delivery:opt-inThe following table lists the supported values:Opt-in policy valuesValueDescriptionopt-inData can be used for this purpose only when the user affirmatively requests this use.opt-outData can be used for this purpose unless the user requests that it not be used in this way.alwaysUsers cannot opt-in or opt-out of this use of their data.This is the default value. When the opt-in policy is not specified, the always policy applies.Specifies how long the information in the cookie is retained. Set the value for the following entry:[p3p-header] retention = {no-retention|stated-purpose|legal-requirement|business-practices| indefinitely}The default setting is: [p3p-header] retention = no-retentionSupported values for the retention entryValueDescriptionno-retentionInformation is not retained for more than the brief period of time necessary to make use of it during the course of a single online interaction.stated-purposeInformation is retained to meet the stated purpose, and is to be discarded at the earliest time possible. legal-requirementInformation is retained to meet a stated purpose, but the retention period is longer because of a legal requirement or liability.business-practicesInformation is retained under a service provider's stated business practices.indefinitelyInformation is retained for an indeterminate period of time.Optionally, specify a reference to a full XML compact policy file. Specify a value for the following entry:[p3p-header] p3p-element = policyref=url_to_default_location_of_full_policyThis entry is present but commented out, and therefore not active, in the default WebSEAL configuration file. The default entry is the default location for the full policy on any Web site.[p3p-header] # p3p-element = policyref=="/w3c/p3p.xml" When p3p-element is not set, browsers look by default for the full policy in /w3c/p3p.xml. Note that some browsers might not refer to p3p-element but proceed directly to /w3c/p3p.xml. Note: Ensure that unauthenticated access is granted to /w3c/p3p.xml. See P3P configuration troubleshooting.Platform for Privacy Preferences (P3P)

Configuring the P3P header

About this task

Administrators who deploy WebSEAL servers as part of the security solution for their Web servers must specify the P3P compact policy for their site. This step requires determining policy for each of the privacy settings defined by the P3P specification. WebSEAL provides a default policy that is accepted by the default settings for the Microsoft Internet Explorer 6 browser. Web administrators should modify the default policy as needed to match the site policies for handling of user data in cookies. Web administrators should test use of their policies with Internet Explorer 6 to ensure that the WebSEAL cookies continue to be accepted by Internet Explorer 6 browsers.

Web administrators should consult the P3P specification when defining their site policy.

Multiple values are allowed for each configuration entry, with the exception of the entries that require a value of "yes" or "no". When a particular configuration entry is not declared, no indicators are added to the compact policy for that entry.

To configure the P3P compact policy for use with WebSEAL, complete the following steps:

Procedure

Open the WebSEAL configuration file for editing. Go to the [server] stanza.

Decide if P3P headers from junctioned servers will be replaced or preserved. Set the following value:[p3p-header] preserve-p3p-policy = {yes|no}
The default value is "no". Set this to "yes" if you want to preserve P3P headers. For more information, see Junction header preservation

Go to the [p3p-header] stanza. Specify the access that the user will have to the information in the cookie. Set the value for the following entry:

[p3p-header]
access = {none|all|nonident|contact-and-other|ident-contact|other-ident}

. The default setting is:

[p3p-header]
access = none

Table 16. Supported values for the access entry

Value
Description

none

No access to identified data is given.

all

Access is given to all identified data.

nonident

Web site does not collect identified data.

contact-and-other

Access is given to identified online and physical contact information as well as to certain other identified data.

ident-contact

Access is given to identified online and physical contact information. For example, users can access things such as a postal address.

other-ident

Access is given to certain other identified data. For example, users can access things such as their online account charges.

Specify the type of information stored in the cookies or linked to by the cookies. Set the value for the following entry:

[p3p-header] categories = {physical|online
|uniqueid|purchase|financial|computer
|navigation| interactive|demographic
|content|state|political|health
|preference|location|
government|other-category}

The default setting is:

[p3p-header]
categories = uniqueid

Table 17. Supported values for the categories entry

Value
Description

physical

Information that allows an individual to be contacted or located in the physical world. For example, telephone number or address.

online

Information that allows an individual to be contacted or located on the Internet.

uniqueid

Non-financial identifiers, excluding government-issued identifiers, issued for purposes of consistently identifying or recognizing the individual.

purchase

Information actively generated by the purchase of a product or service, including information about the method of payment.

financial

Information about an individual's finances including account status and activity information such as account balance, payment or overdraft history, and information about an individual's purchase or use of financial instruments including credit or debit card information.

computer

Information about the computer system that the individual is using to access the network. For example, IP number, domain name, browser type, or operating system.

navigation

Data passively generated by browsing the Web site. For example, which pages are visited, and how long users stay on each page.

interactive

Data actively generated from or reflecting explicit interactions with a service provider through its site. For example, queries to a search engine, or logs of account activity.

demographic

Data about an individual's characteristics. For example, gender, age, and income.

content

The words and expressions contained in the body of a communication. For example, the text of email, bulletin board postings, or chat room communications.

state

Mechanisms for maintaining a stateful session with a user or automatically recognizing users who have visited a particular site or accessed particular content previously. For example, HTTP cookies.

political

Membership in or affiliation with groups such as religious organizations, trade unions, professional associations and political parties.

health

Information about an individual's physical or mental health, sexual orientation, use or inquiry into health care services or products, and purchase of health care services or products.

preference

Data about an individual's likes and dislikes. For example, favorite color or musical tastes.

location

Information that can be used to identify an individual's current physical location and track them as their location changes. For example, Global Positioning System position data.

government

Identifiers issued by a government for purposes of consistently identifying the individual.

other-category

Other types of data not captured by the above definitions.

Specify whether the full P3P policy contains some information regarding disputes over the information contained within the cookie. Set the value for the following entry:

[p3p-header]
disputes = {yes|no}

The disputes entry is not specified by default in the WebSEAL configuration file. The P3P specification states that when the dispute entry is not specified, the default value no is automatically assigned.

Table 18. Supported values for the disputes entry

Value | Description
yes | The full P3P policy contains information regarding disputes over the information contained within the cookie.
no | The full P3P policy does not contain information regarding disputes over the information contained within the cookie.

Specify the types of remedies in case a policy breach occurs. Set the value for the following entry:

[p3p-header]
remedies = {correct|money|law}

The default setting is:

[p3p-header]
remedies = correct

Table 19. Supported values for the remedies entry

Value | Description
correct | Errors or wrongful actions arising in connection with the privacy policy will be remedied by the service.
money | If the service provider violates its privacy policy, it will pay the individual an amount specified in the human readable privacy policy or the amount of damages.
law | Remedies for breaches of the policy statement will be determined based on the law referenced in the human readable description.

Specify either that no data is collected (including Web logs), or that the organization collecting the data will make anonymous any information that identifies the user. Set the value for the following entry:

[p3p-header]
non-identifiable = {yes|no}

The non-identifiable entry is not specified in the WebSEAL configuration file. The P3P specification states that when the non-identifiableentry is not specified, the default value is automatically assigned no.

Table 20. Supported values for the non-identifiable entry

Value | Description
yes | Data that is collected identifies the user.
no | No data is collected (including Web logs), or the information collected does not identify the user.

Specify the purpose of the information in the cookie. Set the value for the following entry:

[p3p-header]
purpose = {current|admin|develop|tailoring|pseudo-analysis|pseudo-decision|
		individual-analysis|individual-decision|contact|historical|
		telemarketing|other-purpose} [:[opt-in|opt-out|always]]

The default setting is:

[p3p-header]
purpose = current

Table 21. Supported values for the purpose entry

Value
Description

current

Information can be used by the service provider to complete the activity for which it was provided.

admin

Information can be used for the technical support of the Web site and its computer system.

develop

Information can be used to enhance, evaluate, or otherwise review the site, service, product, or market.

tailoring

Information can be used to tailor or modify content or design of the site where the information is used only for a single visit to the site

pseudo-analysis

Information can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals for purpose of research, analysis and reporting.

pseudo-decision

Information can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals to make a decision that directly affects that individual.

individual-analysis

Information can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data for the purpose of research, analysis and reporting.

individual-decision

Information can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data to make a decision that directly affects that individual.

contact

Information can be used to contact the individual, through a communications channel other than voice telephone, for the promotion of a product or service.

historical

Information can be archived or stored for the purpose of preserving social history as governed by an existing law or policy.

telemarketing

Information can be used to contact the individual with a voice telephone call for promotion of a product or service.

other-purpose

Information can be used in other ways not captured by the above definitions.

For each value specified for purpose, except the value current, you can optionally specify the opt-in policy. The syntax consists of a colon ( : ) immediately following the purpose value, followed by one of the supported values for the opt-in policy. For example: [p3p-header] purpose = telemarketing:opt-in.

The following table lists the supported values:

Table 22. Supported values for the opt-in or opt-out policy

Value
Description

opt-in

Data can be used for this purpose only when the user affirmatively requests this use.

opt-out

Data can be used for this purpose unless the user requests that it not be used in this way.

always

Users cannot opt-in or opt-out of this use of their data.

This is the default value. When the opt-in policy is not specified, the always policy applies.

Specify the recipients of the information in the cookie. Set the value for the following entry (enter recipient value on one line):

[p3p-header]
recipient = {ours|delivery|same|unrelated|public|other-recipient}
		[:[opt-in|opt-out|always]]

The default setting is:

[p3p-header]
recipient = ours

Table 23. Supported values for the recipient entry

Value
Description

ours

Ourselves and/or entities acting as our agents, or entities for whom we are acting as an agent. An agent is a third party that processes data only on behalf of the service provider.

delivery

Legal entities performing delivery services that may use data for purposes other than completion of the stated purpose.

same

Legal entities following our practices. These are legal entities who use the data on their own behalf under equable practices.

unrelated

Unrelated third parties. These are legal entities whose data usage practices are not known by the original service provider.

public

Public forums. These are public forums such as bulletin boards, public directories, or commercial CD-ROM directories.

other-recipient

Legal entities following different practices. These are legal entities that are constrained by and accountable to the original service provider, but may use the data in a way not specified in the service provider's practices.

For each value specified for recipient, excepting ours, you can optionally specify the opt-in policy. The syntax consists of a colon ( : ) immediately following the recipient, followed by one of the supported values for the opt-in policy. For example:[p3p-header] recipient = delivery:opt-inThe following table lists the supported values:

Table 24. Opt-in policy values

Value
Description

opt-in

Data can be used for this purpose only when the user affirmatively requests this use.

opt-out

Data can be used for this purpose unless the user requests that it not be used in this way.

always

Users cannot opt-in or opt-out of this use of their data.

This is the default value. When the opt-in policy is not specified, the always policy applies.

Specifies how long the information in the cookie is retained. Set the value for the following entry:

[p3p-header]
retention = {no-retention|stated-purpose|legal-requirement|business-practices|
		indefinitely}

The default setting is:

[p3p-header]
retention = no-retention

Table 25. Supported values for the retention entry

Value
Description

no-retention

Information is not retained for more than the brief period of time necessary to make use of it during the course of a single online interaction.

stated-purpose

Information is retained to meet the stated purpose, and is to be discarded at the earliest time possible.

legal-requirement

Information is retained to meet a stated purpose, but the retention period is longer because of a legal requirement or liability.

business-practices

Information is retained under a service provider's stated business practices.

indefinitely

Information is retained for an indeterminate period of time.

Optionally, specify a reference to a full XML compact policy file. Specify a value for the following entry:[p3p-header] p3p-element = policyref=url_to_default_location_of_full_policy
This entry is present but commented out, and therefore not active, in the default WebSEAL configuration file. The default entry is the default location for the full policy on any Web site.
[p3p-header] # p3p-element = policyref=="/w3c/p3p.xml"
When p3p-element is not set, browsers look by default for the full policy in /w3c/p3p.xml. Note that some browsers might not refer to p3p-element but proceed directly to /w3c/p3p.xml.
Note: Ensure that unauthenticated access is granted to /w3c/p3p.xml. See P3P configuration troubleshooting.

Parent topic: Platform for Privacy Preferences (P3P)

Specifying a custom P3P compact policySpecifying a custom P3P compact policyP3Pcustom compact policycustom compact policyspecifyingP3P As an alternative to setting values for the entries in the WebSEAL configuration file, you can specify the exact contents of the P3P header. This configuration can be useful, for example, when your compact policy string has been generated by another utility, and you want to use that string for the P3P policy. To specify a custom P3P compact policy, complete the following steps:Comment out or remove the predefined policy elements from the WebSEAL configuration file. For example, change the default WebSEAL entries to the following:[p3p-header] #access = #purpose = #purpose = #recipients = #retention = #categories =Add your custom compact policy string to the p3p-element entry:[p3p-header] p3p-element = CP="your_series_of_compact_policy_abbreviations"Any number of values can be added. The order of the values is not significant.Platform for Privacy Preferences (P3P)

Specifying a custom P3P compact policy

About this task

As an alternative to setting values for the entries in the WebSEAL configuration file, you can specify the exact contents of the P3P header. This configuration can be useful, for example, when your compact policy string has been generated by another utility, and you want to use that string for the P3P policy.

To specify a custom P3P compact policy, complete the following steps:

Procedure

Comment out or remove the predefined policy elements from the WebSEAL configuration file. For example, change the default WebSEAL entries to the following:

[p3p-header]
#access =
#purpose =
#purpose =
#recipients =
#retention =
#categories =

Add your custom compact policy string to the p3p-element entry:

[p3p-header]
p3p-element =	CP="your_series_of_compact_policy_abbreviations"

Any number of values can be added. The order of the values is not significant.

Parent topic: Platform for Privacy Preferences (P3P)

P3P configuration troubleshootingP3P configuration troubleshootingP3Pconfiguration troubleshootingconfigurationtroubleshootingProblem:Browser cannot access the full P3P policy file.Solution:When the p3p-element stanza entry is used to specify the location of a file containing the full policy, the browser attempts to access the file. The P3P specification does not require browsers to submit cookies with the request for the full policy. Internet Explorer 6 does not submit a session cookie when accessing the full policy. Therefore access to the full policy must be granted to unauthenticated users. When the browser receives either a login form or a 401 error, modify the permissions on the full policy to allow access by unauthenticated users.Platform for Privacy Preferences (P3P)

P3P configuration troubleshooting

Problem:

Browser cannot access the full P3P policy file.

Solution:

When the p3p-element stanza entry is used to specify the location of a file containing the full policy, the browser attempts to access the file. The P3P specification does not require browsers to submit cookies with the request for the full policy. Internet Explorer 6 does not submit a session cookie when accessing the full policy.

Therefore access to the full policy must be granted to unauthenticated users. When the browser receives either a login form or a 401 error, modify the permissions on the full policy to allow access by unauthenticated users.

Parent topic: Platform for Privacy Preferences (P3P)

Default port numbersThe installation uses several port numbers by default.portnumbersdefaultneeded during installationDefault port numbers used during Security Access Manager installationInstallation componentsFields to be completedDefault port Security Access Manager Policy ServerPolicy server port 7135Security Access Manager Policy Server Security Access Manager Runtime Security Access Manager Runtime for JavaPolicy server SSL port7135Security Access Manager Authorization ServerAuthorization request port 7136Security Access Manager Authorization ServerAdministration request port 7137Security Access Manager WebSEALWebSEAL listening port 7234LDAP serversNon-SSL port 389LDAP serversSSL port 636Security Access Manager WebSEALHTTP port 80Security Access Manager WebSEALHTTPS port 443Configuration

Default port numbers

The installation uses several port numbers by default.

Table 26. Default port numbers used during Security Access Manager installation

Installation components
Fields to be completed
Default port

Security Access Manager Policy Server
Policy server port

7135

Security Access Manager Policy Server

Security Access Manager Runtime

Security Access Manager Runtime for Java

Policy server SSL port
7135

Security Access Manager Authorization Server
Authorization request port
7136

Security Access Manager Authorization Server
Administration request port
7137

Security Access Manager WebSEAL
WebSEAL listening port
7234

LDAP servers
Non-SSL port
389

LDAP servers
SSL port
636

Security Access Manager WebSEAL
HTTP port
80

Security Access Manager WebSEAL
HTTPS port
443

Parent topic: Configuration

AuthenticationAuthenticationWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Authentication overviewAuthentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Advanced authentication methodsPost-authentication processingPassword processingCredential processingExternal authentication interface

Authentication

Authentication overview

Authentication methods
This chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.

Advanced authentication methods

Post-authentication processing

Password processing

Credential processing

External authentication interface

Parent topic: Web Reverse Proxy configuration

Authentication overviewAuthentication overviewauthenticationoverviewWebSEALThis chapter discusses basic concepts of WebSEAL authentication.Topic Index:AuthenticationDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. Information in a user requestClient identities and credentialsAuthentication process flowAuthenticated and unauthenticated access to resourcesSupported authentication methodsAlthough WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. Authentication challenge based on user agentWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Authentication overview

This chapter discusses basic concepts of WebSEAL authentication.

Topic Index:

Definition and purpose of authentication
Authentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge.

Information in a user request

Client identities and credentials

Authentication process flow

Authenticated and unauthenticated access to resources

Supported authentication methods
Although WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain.

Authentication challenge based on user agent
WebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Parent topic: Authentication

Definition and purpose of authenticationDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. authenticationoverviewdefinitionpurposeWebSEAL provides several built-in authentication methods by default. WebSEAL also provides the flexibility to customize the authentication mechanism.The result of successful authentication to WebSEAL is a Security Access Manager client identity. WebSEAL uses this client identity to build a credential for that user. The authorization service uses this credential to permit or deny access to protected resources after evaluating the authorization policies governing each object.Authentication overviewInformation in a user requestClient identities and credentialsAuthentication process flowAuthenticated and unauthenticated access to resourcesSupported authentication methodsAlthough WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. Authentication challenge based on user agentWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Definition and purpose of authentication

Authentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge.

WebSEAL provides several built-in authentication methods by default.

WebSEAL also provides the flexibility to customize the authentication mechanism.

The result of successful authentication to WebSEAL is a Security Access Manager client identity.

WebSEAL uses this client identity to build a credential for that user.

The authorization service uses this credential to permit or deny access to protected resources after evaluating the authorization policies governing each object.

Parent topic: Authentication overview

Related concepts:

Client identities and credentials

Authentication process flow

Authenticated and unauthenticated access to resources

Related reference:

Information in a user request

Supported authentication methods

Authentication challenge based on user agent

Information in a user requestInformation in a user requestrequestsclient authentication datasession keyexamine client requestWebSEALWebSEALsession IDsession IDWebSEALDuring authentication, WebSEAL examines a user request for the following information: Session key A session key is a piece of data that is stored with a client and sent with every request to WebSEAL made by that client. The session key is used by WebSEAL to identify a series of requests as coming from the same client. It allows WebSEAL to avoid the overhead of performing authentication for each request. The session key is a locator index to the associated session data stored in the WebSEAL server session cache. The session key is also known as the WebSEAL session ID.Authentication data Authentication data is information found in the user request that identifies the user to the WebSEAL server. Examples of authentication data types include client-side certificates, passwords, and token codes.When WebSEAL receives a user request, WebSEAL always looks for the session key first, followed by authentication data. Authentication overviewDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. Client identities and credentialsAuthentication process flowAuthenticated and unauthenticated access to resourcesSupported authentication methodsAlthough WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. Authentication challenge based on user agentWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Information in a user request

During authentication, WebSEAL examines a user request for the following information:

Session key

A session key is a piece of data that is stored with a client and sent with every request to WebSEAL made by that client. The session key is used by WebSEAL to identify a series of requests as coming from the same client. It allows WebSEAL to avoid the overhead of performing authentication for each request. The session key is a locator index to the associated session data stored in the WebSEAL server session cache. The session key is also known as the WebSEAL session ID.

Authentication data

Authentication data is information found in the user request that identifies the user to the WebSEAL server. Examples of authentication data types include client-side certificates, passwords, and token codes.

When WebSEAL receives a user request, WebSEAL always looks for the session key first, followed by authentication data.

Parent topic: Authentication overview

Related concepts:

Definition and purpose of authentication

Client identities and credentials

Authentication process flow

Authenticated and unauthenticated access to resources

Related reference:

Supported authentication methods

Authentication challenge based on user agent

Client identities and credentialsClient identities and credentialsauthenticationclient identitiescredentialscredentialsdefinitionidentity informationThe result of authentication is a client identity. WebSEAL requires the client identity to build a credential for the user. The authorization service uses this credential to permit or deny access to protected resources requested by the user. The following process flow explains the relationship between authentication, a client identity, and a credential: WebSEAL always builds an unauthenticated credential for unauthenticated users. An unauthenticated user can still participate in the secure domain because ACLs can contain rules that specifically govern unauthenticated users.When a user requests a protected object and is required to authenticate, WebSEAL first examines the user request for authentication data. Authentication data includes method-specific authentication information, such as passwords and certificates, that represent physical identity properties of the user. The result of successful authentication is a client identity. The client identity is a data structure that includes the user name and any extended attribute information that is to be added to the resulting credential.Security Access Manager uses the client identity information to build a credential for that user. Security Access Manager matches the client identity with a registered Security Access Manager user and builds a credential appropriate to this user. This action is known as credentials acquisition. The credential is a complex structure that includes the user name, any group memberships, and any special extended security attributes associated with the user's session. The credential describes the user in a specific context and is valid only for the lifetime of that session. The authorization service uses this credential to permit or deny access to protected resources after evaluating the authorization policies governing each object. Credential acquisition can succeed only if the user has an account defined in the Security Access Manager user registry. If credential acquisition fails (the user is not a member of the Security Access Manager user registry), WebSEAL returns an error.Credentials can be used by any Security Access Manager service that requires information about the user. Credentials allow Security Access Manager to securely perform a multitude of services such as authorization, auditing, and delegation.Authentication overviewDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. Information in a user requestAuthentication process flowAuthenticated and unauthenticated access to resourcesSupported authentication methodsAlthough WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. Authentication challenge based on user agentWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Client identities and credentials

The result of authentication is a client identity. WebSEAL requires the client identity to build a credential for the user. The authorization service uses this credential to permit or deny access to protected resources requested by the user.

The following process flow explains the relationship between authentication, a client identity, and a credential:

WebSEAL always builds an unauthenticated credential for unauthenticated users.

An unauthenticated user can still participate in the secure domain because ACLs can contain rules that specifically govern unauthenticated users.

When a user requests a protected object and is required to authenticate, WebSEAL first examines the user request for authentication data.

Authentication data includes method-specific authentication information, such as passwords and certificates, that represent physical identity properties of the user.

The result of successful authentication is a client identity.

The client identity is a data structure that includes the user name and any extended attribute information that is to be added to the resulting credential.

Security Access Manager uses the client identity information to build a credential for that user.

Security Access Manager matches the client identity with a registered Security Access Manager user and builds a credential appropriate to this user. This action is known as credentials acquisition.

The credential is a complex structure that includes the user name, any group memberships, and any special extended security attributes associated with the user's session. The credential describes the user in a specific context and is valid only for the lifetime of that session.

The authorization service uses this credential to permit or deny access to protected resources after evaluating the authorization policies governing each object.

Credential acquisition can succeed only if the user has an account defined in the Security Access Manager user registry.

If credential acquisition fails (the user is not a member of the Security Access Manager user registry), WebSEAL returns an error.

Credentials can be used by any Security Access Manager service that requires information about the user. Credentials allow Security Access Manager to securely perform a multitude of services such as authorization, auditing, and delegation.

Parent topic: Authentication overview

Related concepts:

Definition and purpose of authentication

Authentication process flow

Authenticated and unauthenticated access to resources

Related reference:

Information in a user request

Supported authentication methods

Authentication challenge based on user agent

Authentication process flowAuthentication process flowauthenticationprocess flowprocess flowauthenticationThe following diagram illustrates the general process flow for WebSEAL authentication when an external authentication interface (EAI) is not being used:Authentication process flowAuthentication process flowThe user presents authentication information to WebSEAL (for example, password, certificate, HTTP header) during a request for a resource in the protected object space.WebSEAL invokes the configured authentication module for that type of authentication information.The authentication module validates the authentication information and returns an identity to WebSEAL.WebSEAL uses this identity to create a credential for that user, based on data stored for that user in the user registry. This credential is used during authorization decisions for requests made by this user.The external authentication interface (EAI) supports external authentication.Authentication overviewDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. Information in a user requestClient identities and credentialsAuthenticated and unauthenticated access to resourcesSupported authentication methodsAlthough WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. Authentication challenge based on user agentWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Authentication process flow

The following diagram illustrates the general process flow for WebSEAL authentication when an external authentication interface (EAI) is not being used:

Figure 13. Authentication process flow

The user presents authentication information to WebSEAL (for example, password, certificate, HTTP header) during a request for a resource in the protected object space.

WebSEAL invokes the configured authentication module for that type of authentication information.

The authentication module validates the authentication information and returns an identity to WebSEAL.

WebSEAL uses this identity to create a credential for that user, based on data stored for that user in the user registry. This credential is used during authorization decisions for requests made by this user.

Note: The external authentication interface (EAI) supports external authentication.

Parent topic: Authentication overview

Related concepts:

Definition and purpose of authentication

Client identities and credentials

Authenticated and unauthenticated access to resources

Related reference:

Information in a user request

Supported authentication methods

Authentication challenge based on user agent

Authenticated and unauthenticated access to resources Authenticated and unauthenticated access to resources authenticationunauthenticated access to resourcesunauthenticated userscontrolauthenticated access to resourcesunauthenticated access to resourcesIn a Security Access Manager environment, the identity of a user is proven to WebSEAL through the process of authentication. But WebSEAL can accept requests from both authenticated and unauthenticated users over HTTP and HTTPS. WebSEAL then relies on the authorization service to enforce security policy by permitting or denying access to protected resources. In general, a user can participate in the secure domain as authenticated or unauthenticated. In either case, the Security Access Manager authorization service requires a user credential to make authorization decisions on requests for resources in the secure domain. WebSEAL handles authenticated user credentials differently from unauthenticated user credentials.The credential for an unauthenticated user is a generic passport that allows the user to participate in the secure domain and access resources that are available to unauthenticated users.The credential for an authenticated user is a unique passport that describes a specific user who belongs to the Security Access Manager user registry. The authenticated user credential contains the user identity, any group memberships, and any special extended security attributes. Authentication overviewDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. Information in a user requestClient identities and credentialsAuthentication process flowSupported authentication methodsAlthough WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. Authentication challenge based on user agentWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL. Request process for authenticated usersRequest process for unauthenticated usersAccess conditions over SSLForcing user loginUse of unauthenticated HTTPS

Authenticated and unauthenticated access to resources

In a Security Access Manager environment, the identity of a user is proven to WebSEAL through the process of authentication. But WebSEAL can accept requests from both authenticated and unauthenticated users over HTTP and HTTPS. WebSEAL then relies on the authorization service to enforce security policy by permitting or denying access to protected resources. In general, a user can participate in the secure domain as authenticated or unauthenticated.

In either case, the Security Access Manager authorization service requires a user credential to make authorization decisions on requests for resources in the secure domain. WebSEAL handles authenticated user credentials differently from unauthenticated user credentials.

The credential for an unauthenticated user is a generic passport that allows the user to participate in the secure domain and access resources that are available to unauthenticated users.

The credential for an authenticated user is a unique passport that describes a specific user who belongs to the Security Access Manager user registry. The authenticated user credential contains the user identity, any group memberships, and any special extended security attributes.

Request process for authenticated users

Request process for unauthenticated users

Access conditions over SSL

Forcing user login

Use of unauthenticated HTTPS

Parent topic: Authentication overview

Related concepts:

Definition and purpose of authentication

Client identities and credentials

Authentication process flow

Related reference:

Information in a user request

Supported authentication methods

Authentication challenge based on user agent

Request process for authenticated usersRequest process for authenticated users:authenticated usersauthentication process flowrequest processThe following conditions describe the request process for authenticated users: A user makes a request for a resource protected by WebSEAL. The protection on the resource requires that the user be authenticated. WebSEAL prompts the user to log in.Successful authentication can occur only if the user is a member of the Security Access Manager user registry.A WebSEAL session and key is created for the user.A credential for this user is built from information contained in the registry about this user (such as group memberships).The session key and credential, plus other data, are stored as an entry in the WebSEAL session cache.As WebSEAL processes this request (and future requests during this session), it keeps the credential information available.Whenever an authorization check is required, the Security Access Manager authorization service uses the credential information during the decision-making process.When the user logs off, the cache entry for that user is removed and the session is terminated.Authenticated and unauthenticated access to resources

Request process for authenticated users

The following conditions describe the request process for authenticated users:

A user makes a request for a resource protected by WebSEAL. The protection on the resource requires that the user be authenticated. WebSEAL prompts the user to log in.

Successful authentication can occur only if the user is a member of the Security Access Manager user registry.

A WebSEAL session and key is created for the user.

A credential for this user is built from information contained in the registry about this user (such as group memberships).

The session key and credential, plus other data, are stored as an entry in the WebSEAL session cache.

As WebSEAL processes this request (and future requests during this session), it keeps the credential information available.

Whenever an authorization check is required, the Security Access Manager authorization service uses the credential information during the decision-making process.

When the user logs off, the cache entry for that user is removed and the session is terminated.

Parent topic: Authenticated and unauthenticated access to resources

Request process for unauthenticated usersRequest process for unauthenticated users:unauthenticated usersauthentication process flowrequest processThe following conditions describe the request process for unauthenticated users: A user makes a request for a resource protected by WebSEAL. The protection on the resource does not require that the user be authenticated. WebSEAL does not prompt the user to log in.WebSEAL builds an unauthenticated credential for the user.No entry is created in the WebSEAL session cache.The request proceeds, with this credential, to the protected Web object.The authorization service checks the permissions on the unauthenticated entry of the ACL for this object, and permits or denies the requested operation. The user can access resources that contain the correct permissions for the unauthenticated type category of user.Successful access to this object depends on the unauthenticated ACL entry containing at least the read (r) and traverse (T) permissions.If the user requires access to a resource not available to unauthenticated users, WebSEAL prompts the user to log in.A successful login changes the user's status to authenticated.If login is unsuccessful, a 403 "Forbidden" message is returned. However, the user can still continue to access other resources that are available to unauthenticated users.Authenticated and unauthenticated access to resources

Request process for unauthenticated users

The following conditions describe the request process for unauthenticated users:

A user makes a request for a resource protected by WebSEAL. The protection on the resource does not require that the user be authenticated. WebSEAL does not prompt the user to log in.

WebSEAL builds an unauthenticated credential for the user.

No entry is created in the WebSEAL session cache.

The request proceeds, with this credential, to the protected Web object.

The authorization service checks the permissions on the unauthenticated entry of the ACL for this object, and permits or denies the requested operation. The user can access resources that contain the correct permissions for the unauthenticated type category of user.

Successful access to this object depends on the unauthenticated ACL entry containing at least the read (r) and traverse (T) permissions.

If the user requires access to a resource not available to unauthenticated users, WebSEAL prompts the user to log in.

A successful login changes the user's status to authenticated.

If login is unsuccessful, a 403 "Forbidden" message is returned. However, the user can still continue to access other resources that are available to unauthenticated users.

Parent topic: Authenticated and unauthenticated access to resources

Access conditions over SSLAccess conditions over SSLauthenticated usersaccess conditions over SSLSSLaccess conditionsaccessconditionsThe following conditions apply to unauthenticated users who access WebSEAL over SSL: The exchange of information between the unauthenticated user and WebSEAL is encrypted—just as it is with an authenticated user.An SSL connection between an unauthenticated user and WebSEAL requires only server-side authentication. Authenticated and unauthenticated access to resources

Access conditions over SSL

The following conditions apply to unauthenticated users who access WebSEAL over SSL:

The exchange of information between the unauthenticated user and WebSEAL is encrypted—just as it is with an authenticated user.

An SSL connection between an unauthenticated user and WebSEAL requires only server-side authentication.

Parent topic: Authenticated and unauthenticated access to resources

Forcing user login Forcing user login unauthenticated usersforcing user loginloginforcing user loginYou can force an unauthenticated user to log in by correctly setting the appropriate permissions on the unauthenticated entry in the ACL policy that protects the requested object. The read (r) and traverse (T) permissions allow unauthenticated access to an object. To force an unauthenticated user to log in, remove the read (r) permission from the unauthenticated entry in the ACL policy that protects the object. The user receives a login prompt (basic authentication or forms).Authenticated and unauthenticated access to resources

Forcing user login

About this task

You can force an unauthenticated user to log in by correctly setting the appropriate permissions on the unauthenticated entry in the ACL policy that protects the requested object.

The read (r) and traverse (T) permissions allow unauthenticated access to an object.

To force an unauthenticated user to log in, remove the read (r) permission from the unauthenticated entry in the ACL policy that protects the object.

The user receives a login prompt (basic authentication or forms).

Parent topic: Authenticated and unauthenticated access to resources

Use of unauthenticated HTTPSUse of unauthenticated HTTPSunauthenticated usersusing unauthenticated HTTPSHTTPSunauthenticatedThere are many practical business reasons for supporting unauthenticated access to WebSEAL over HTTPS: Some applications do not require a personal login, but require sensitive information, such as addresses and credit card numbers. Examples include online purchases of airline tickets and other merchandise.Some applications require that you register for an account with the business before you can proceed with further transactions. Again, sensitive information must be passed over the network.Authenticated and unauthenticated access to resources

Use of unauthenticated HTTPS

There are many practical business reasons for supporting unauthenticated access to WebSEAL over HTTPS:

Some applications do not require a personal login, but require sensitive information, such as addresses and credit card numbers. Examples include online purchases of airline tickets and other merchandise.

Some applications require that you register for an account with the business before you can proceed with further transactions. Again, sensitive information must be passed over the network.

Parent topic: Authenticated and unauthenticated access to resources

Supported authentication methods Supported authentication methods Although WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain. authentication methodssummaryauthenticationsupported methodsTo obtain the necessary identity information for credentials acquisition, WebSEAL relies on the information gained from the authentication process.The following table lists the authentication methods supported by WebSEAL for credentials acquisition. When WebSEAL examines a client request, it searches for authentication data in the order specified in this table.Authentication MethodSupported Connection TypeFailover cookieHTTP and HTTPSLTPA cookieHTTP and HTTPSCDSSO ID tokenHTTP and HTTPSClient-side certificateHTTPS Forms authentication (username and password)HTTP and HTTPS Basic authentication (username and password)HTTP and HTTPSExternal Authentication InterfaceHTTP and HTTPSOpen Authentication (OAuth)HTTP and HTTPSAuthentication methods can be independently enabled and disabled for both HTTP and HTTPS transports. If no authentication methods are enabled for a particular transport, the authentication process is inactive for clients using that transport.Authentication overviewDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. Information in a user requestClient identities and credentialsAuthentication process flowAuthenticated and unauthenticated access to resourcesAuthentication challenge based on user agentWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Supported authentication methods

Although WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain.

To obtain the necessary identity information for credentials acquisition, WebSEAL relies on the information gained from the authentication process.

The following table lists the authentication methods supported by WebSEAL for credentials acquisition. When WebSEAL examines a client request, it searches for authentication data in the order specified in this table.

Authentication Method | Supported Connection Type
Failover cookie | HTTP and HTTPS
LTPA cookie | HTTP and HTTPS
CDSSO ID token | HTTP and HTTPS
Client-side certificate | HTTPS
Forms authentication (username and password) | HTTP and HTTPS
Basic authentication (username and password) | HTTP and HTTPS
External Authentication Interface | HTTP and HTTPS
Open Authentication (OAuth) | HTTP and HTTPS

Authentication methods can be independently enabled and disabled for both HTTP and HTTPS transports. If no authentication methods are enabled for a particular transport, the authentication process is inactive for clients using that transport.

Parent topic: Authentication overview

Related concepts:

Definition and purpose of authentication

Client identities and credentials

Authentication process flow

Authenticated and unauthenticated access to resources

Related reference:

Information in a user request

Authentication challenge based on user agent

Authentication challenge based on user agentAuthentication challenge based on user agentAuthentication challenge based on user agent in IBM Security Access Manager for WebWebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL. user agentsauthentication challengeuser agentEach authentication type, as specified by the auth-challenge-type configuration entry, can be qualified with a set of rules. These rules define the user agent strings that are included or excluded for different authentication types. For example: auth-challenge-type = [-msie*+ms*]ba, [+mozilla*; +msie]forms; eaiBased on the configuration example, WebSEAL:Does not return a basic authentication challenge to user agent strings beginning with msie, but does return a basic authentication challenge for agents beginning with ms.Returns a forms based authentication challenge client to user agents beginning with mozilla or msie.Returns an EAI authentication challenge to any user agent.User Agent StringAuthentication Challengesmsieforms, eaims_office_wordba, eaimozillaforms, eaichromeeaiRule SyntaxEach authentication challenge type can be defined only once in the auth-challenge-type string. The rules must precede the authentication type enclosed in square brackets with different patterns separated by semicolons. A plus (+) or minus (-) character indicates whether that challenge type is included or excluded for that user agent string respectively.The pattern can contain alphanumeric characters, spaces, periods, and wildcard characters, such as, question mark (?) and asterisk (*). When WebSEAL evaluates these rules based on the user agent, the first rule with a pattern that matches the current string is applied. Any other rules that match the given authentication mechanism are ignored. WebSEAL performs these evaluations in the order in which the rules are defined. An authentication type with no defined rule set will match any user agent string. If you do not want the authentication type to match any user agent string, indicate the given authentication challenge by using a negative wildcard string, such as [-*]ba. The Authentication challenge based on the user agent functionality must not be used as a security or enforcement measure. Authentication overviewDefinition and purpose of authenticationAuthentication is the process of identifying an individual process or entity that is attempting to log in to a secure domain. Requests for protected resources by unauthenticated users always result in an authentication challenge. Information in a user requestClient identities and credentialsAuthentication process flowAuthenticated and unauthenticated access to resourcesSupported authentication methodsAlthough WebSEAL functions independently of the authentication process, WebSEAL uses credentials to monitor all users participating in the secure domain.

Authentication challenge based on user agent

WebSEAL provides a mechanism that allows the authentication challenge type to be configured based on the user agent of a client requesting a protected resource. This mechanism allows for tight integration and fine grained control over how different clients can authenticate to WebSEAL.

Each authentication type, as specified by the auth-challenge-type configuration entry, can be qualified with a set of rules. These rules define the user agent strings that are included or excluded for different authentication types.

For example: auth-challenge-type = [-msie*+ms*]ba, [+mozilla*; +msie]forms; eai

Based on the configuration example, WebSEAL:

Does not return a basic authentication challenge to user agent strings beginning with msie, but does return a basic authentication challenge for agents beginning with ms.

Returns a forms based authentication challenge client to user agents beginning with mozilla or msie.

Returns an EAI authentication challenge to any user agent.

User Agent String | Authentication Challenges
msie | forms, eai
ms_office_word | ba, eai
mozilla | forms, eai
chrome | eai

Rule Syntax

Each authentication challenge type can be defined only once in the auth-challenge-type string. The rules must precede the authentication type enclosed in square brackets with different patterns separated by semicolons. A plus (+) or minus (-) character indicates whether that challenge type is included or excluded for that user agent string respectively.

The pattern can contain alphanumeric characters, spaces, periods, and wildcard characters, such as, question mark (?) and asterisk (*).

When WebSEAL evaluates these rules based on the user agent, the first rule with a pattern that matches the current string is applied. Any other rules that match the given authentication mechanism are ignored. WebSEAL performs these evaluations in the order in which the rules are defined.

An authentication type with no defined rule set will match any user agent string.

If you do not want the authentication type to match any user agent string, indicate the given authentication challenge by using a negative wildcard string, such as [-*]ba.

Note: The Authentication challenge based on the user agent functionality must not be used as a security or enforcement measure.

Parent topic: Authentication overview

Related concepts:

Definition and purpose of authentication

Client identities and credentials

Authentication process flow

Authenticated and unauthenticated access to resources

Related reference:

Information in a user request

Supported authentication methods

Authentication methodsAuthentication methodsAuthentication methods in IBM Security Access Manager for WebThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.authenticationmethodsmethodsSuccessful authentication results in a Security Access Manager identity that represents the user. WebSEAL uses this identity to acquire credentials for that user. Credentials allow the user to participate in the secure domain and are used by the authorization service to permit or deny access to protected resources.Topic Index:AuthenticationAuthentication terminologyLogout and password change operationsBasic authenticationForms authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.

Authentication methods

This chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.

Successful authentication results in a Security Access Manager identity that represents the user. WebSEAL uses this identity to acquire credentials for that user. Credentials allow the user to participate in the secure domain and are used by the authorization service to permit or deny access to protected resources.

Topic Index:

Authentication terminology

Logout and password change operations

Basic authentication

Forms authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)
The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance.

Windows desktop single sign-on
This chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins.

LTPA authentication

OAuth Authentication
Security Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.

Parent topic: Authentication

Authentication terminologyAuthentication terminologyauthenticationmethodsmechanismsmodulesoperationsThe following terminology is used when discussing authentication in this document: method An authentication method describes the overall process and strategy of an authentication type. Examples of authentication methods include, but are not limited to: Username/passwordCertificate Typically, but not always, authentication methods have a one to one relationship with a particular type of data used to prove a user's identity.operations An authentication operation describes any action that supports the authentication method. For example: Performing an LDAP lookup during username and password authentication.Changing a user password.Verifying that a new password meets certain criteria.Adding attributes to an authenticated identity. Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Logout and password change operationsBasic authenticationForms authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.

Authentication terminology

The following terminology is used when discussing authentication in this document:

method

An authentication method describes the overall process and strategy of an authentication type. Examples of authentication methods include, but are not limited to:

Username/password

Certificate

Typically, but not always, authentication methods have a one to one relationship with a particular type of data used to prove a user's identity.

operations

An authentication operation describes any action that supports the authentication method. For example:

Performing an LDAP lookup during username and password authentication.

Changing a user password.

Verifying that a new password meets certain criteria.

Adding attributes to an authenticated identity.

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

LTPA authentication

OAuth Authentication

Related reference:

Logout and password change operations

Logout and password change operationsLogout and password change operationsauthenticationlogout and password utilitiesSecurity Access Manager provides authenticated users with the following resources for managing logout and password change operations: Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyBasic authenticationForms authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.Logging out: pkmslogoutControlling custom response pages for pkmslogoutThe pkmslogout command allows the default HTML response page (such as logout.html) to be replaced by a custom response page. Changing passwords: pkmspasswdPassword change issue with Active Directory on Windows

Logout and password change operations

Security Access Manager provides authenticated users with the following resources for managing logout and password change operations:

Logging out: pkmslogout

Controlling custom response pages for pkmslogout
The pkmslogout command allows the default HTML response page (such as logout.html) to be replaced by a custom response page.

Changing passwords: pkmspasswd

Password change issue with Active Directory on Windows

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

LTPA authentication

OAuth Authentication

Related reference:

Authentication terminology

Logging out: pkmslogout Logging out: pkmslogout pkmslogoutlogoutpkmslogoutFor some authentication methods, users can use the pkmslogout command to log out from the current session. The pkmslogout command is not appropriate for authentication methods that supply authentication data with each request, such as basic authentication, certificates, or IP address authentication. In these cases, you must close the browser to log out. Run the pkmslogout command to log out from the current session. For example: https://www.example.com/pkmslogoutWhen this request is made, WebSEAL returns the appropriate logout form defined in the WebSEAL configuration file: [acnt-mgt]logout = logout.htmlModify the contents of the appropriate response page (such as logout.html) to meet your specific requirements.Logout and password change operations

Logging out: pkmslogout

About this task

For some authentication methods, users can use the pkmslogout command to log out from the current session.

The pkmslogout command is not appropriate for authentication methods that supply authentication data with each request, such as basic authentication, certificates, or IP address authentication. In these cases, you must close the browser to log out.

Procedure

Run the pkmslogout command to log out from the current session. For example: https://www.example.com/pkmslogout When this request is made, WebSEAL returns the appropriate logout form defined in the WebSEAL configuration file: [acnt-mgt]logout = logout.html

Modify the contents of the appropriate response page (such as logout.html) to meet your specific requirements.

Parent topic: Logout and password change operations

Controlling custom response pages for pkmslogoutControlling custom response pages for pkmslogoutpkmslogoutThe pkmslogout command allows the default HTML response page (such as logout.html) to be replaced by a custom response page. user-filename-for-pkmslogout stanza entrylogoutuse-filename-for-pkmslogout stanza entryThe custom response page is specified through a query string that is appended to the pkmslogout URL. For example: https://www.example.com/pkmslogout?filename=custom_logout_file where custom_logout_file is the file name of the custom logout response page. This file must be located in the same management/lang directory that contains the default HTML response forms (such as logout.html) in the LMI. The custom response page feature allows, for example, multiple logout response pages when the network architecture requires different exit screens for users logging out of distinctly different back-end systems. You can control whether or not the appended query string is allowed to override the default response page through the use-filename-for-pkmslogout stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file. A no value (default) disables the use of the query string. Any query string in a pkmslogout URL that specifies a custom response page is ignored. Only the default response page is used upon logout. A yes value enables the use of the query string. If a query string in a pkmslogout URL specifies a custom response page, that custom page is used instead of the default page. For example: [acnt-mgt] use-filename-for-pkmslogout = yes See also Customized responses for old session cookies.Logout and password change operations

Controlling custom response pages for pkmslogout

The pkmslogout command allows the default HTML response page (such as logout.html) to be replaced by a custom response page.

The custom response page is specified through a query string that is appended to the pkmslogout URL. For example:

https://www.example.com/pkmslogout?filename=custom_logout_file

where custom_logout_file is the file name of the custom logout response page. This file must be located in the same management/lang directory that contains the default HTML response forms (such as logout.html) in the LMI.

The custom response page feature allows, for example, multiple logout response pages when the network architecture requires different exit screens for users logging out of distinctly different back-end systems.

You can control whether or not the appended query string is allowed to override the default response page through the use-filename-for-pkmslogout stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file.

A no value (default) disables the use of the query string. Any query string in a pkmslogout URL that specifies a custom response page is ignored. Only the default response page is used upon logout.

A yes value enables the use of the query string. If a query string in a pkmslogout URL specifies a custom response page, that custom page is used instead of the default page. For example:

[acnt-mgt]
use-filename-for-pkmslogout = yes

See also Customized responses for old session cookies.

Parent topic: Logout and password change operations

Changing passwords: pkmspasswd Changing passwords: pkmspasswd pkmspasswdpasswordchangepkmspasswdUsers can use this command to change their login password when using basic authentication (BA) or forms authentication. For example: https://www.example.com/pkmspasswdTo assure maximum security when BA is used with WebSEAL, this command has the following behavior for a BA client:The password is changed.The client user is logged out from the current session.When the client makes an additional request, the browser presents the client with a BA prompt.The client must log back in to continue making requests.This scenario applies only to a client using basic authentication.The pkmspasswd management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.Logout and password change operations

Changing passwords: pkmspasswd

About this task

Users can use this command to change their login password when using basic authentication (BA) or forms authentication. For example:

https://www.example.com/pkmspasswd

Results

To assure maximum security when BA is used with WebSEAL, this command has the following behavior for a BA client:

The password is changed.

The client user is logged out from the current session.

When the client makes an additional request, the browser presents the client with a BA prompt.

The client must log back in to continue making requests.

This scenario applies only to a client using basic authentication.

Note: The pkmspasswd management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

Parent topic: Logout and password change operations

Password change issue with Active Directory on WindowsPassword change issue with Active Directory on Windowspasswordchangeissue with Active Directory on WindowsThe following problem occurs for password changes when using Active Directory as the Security Access Manager user registry and the Active Directory server is running on Windows. Depending on certain Active Directory policy settings, old passwords can still be used to log in to Security Access Manager after a password change has occurred. By default, both the old and the new passwords continue to work for approximately one hour after the password change. After one hour, the old password stops working. Windows introduced this behavior into Active Directory. See the Microsoft KB article 906305 for information about what occurs and for instructions on disabling the behavior if necessary.http://support.microsoft.com/?id=906305Logout and password change operations

Password change issue with Active Directory on Windows

The following problem occurs for password changes when using Active Directory as the Security Access Manager user registry and the Active Directory server is running on Windows. Depending on certain Active Directory policy settings, old passwords can still be used to log in to Security Access Manager after a password change has occurred. By default, both the old and the new passwords continue to work for approximately one hour after the password change. After one hour, the old password stops working.

Windows introduced this behavior into Active Directory. See the Microsoft KB article 906305 for information about what occurs and for instructions on disabling the behavior if necessary.

http://support.microsoft.com/?id=906305

Parent topic: Logout and password change operations

Basic authentication Basic authentication authenticationbasic authenticationbasic authenticationconfigurationBasic authentication (BA) is a standard method for providing a username and password to the authentication mechanism. BA is defined by the HTTP protocol and can be implemented over HTTP and over HTTPS.Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsForms authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.Enabling and disabling basic authenticationSetting the realm name

Basic authentication

Basic authentication (BA) is a standard method for providing a username and password to the authentication mechanism. BA is defined by the HTTP protocol and can be implemented over HTTP and over HTTPS.

Enabling and disabling basic authentication

Setting the realm name

Parent topic: Authentication methods

Related concepts:

Forms authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

LTPA authentication

OAuth Authentication

Related reference:

Authentication terminology

Logout and password change operations

Enabling and disabling basic authenticationEnabling and disabling basic authenticationba-auth stanza entrybasic authenticationenablingdisabling The ba-auth stanza entry, located in the [ba] stanza of the WebSEAL configuration file, enables and disables the basic authentication method. Basic authentication is enabled by default. To configure basic authentication:Stop the WebSEAL server.Edit the WebSEAL configuration file. In the [ba] stanza, specify the protocols to support in your network environment.The protocols are shown in the following table. Configuring basic authenticationProtocol to SupportConfiguration File EntryHTTP ba-auth = httpHTTPS ba-auth = httpsBoth HTTP and HTTPS ba-auth = bothDisable basic authentication ba-auth = noneFor example, to support both protocols: [ba] ba-auth = bothRestart the WebSEAL server.Basic authentication

Enabling and disabling basic authentication

About this task

The ba-auth stanza entry, located in the [ba] stanza of the WebSEAL configuration file, enables and disables the basic authentication method.

Basic authentication is enabled by default. To configure basic authentication:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. In the [ba] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.

Table 27. Configuring basic authentication

Protocol to Support
Configuration File Entry

HTTP

ba-auth = http

HTTPS

ba-auth = https

Both HTTP and HTTPS

ba-auth = both

Disable basic authentication

ba-auth = none

For example, to support both protocols:

[ba]
ba-auth = both

Restart the WebSEAL server.

Parent topic: Basic authentication

Setting the realm name Setting the realm name basic-auth-realmrealm namessetting realm name The realm name is the text that is displayed in the dialog box that appears when the browser prompts the user for login data. The realm name is also the name of the realm to which the user will be authenticated when the user login succeeds. The basic-auth-realm stanza entry located in the [ba] stanza of the WebSEAL configuration file sets the realm name. For example: [ba] basic-auth-realm = Access Manager The dialog box would display (for example): Enter username for Access Manager at www.ibm.com:Basic authentication

Setting the realm name

About this task

The realm name is the text that is displayed in the dialog box that appears when the browser prompts the user for login data. The realm name is also the name of the realm to which the user will be authenticated when the user login succeeds.

The basic-auth-realm stanza entry located in the [ba] stanza of the WebSEAL configuration file sets the realm name.

For example:

[ba]
basic-auth-realm = Access Manager

The dialog box would display (for example):

Enter username for Access Manager at www.ibm.com:

Parent topic: Basic authentication

Forms authentication Forms authentication formsauthenticationauthenticationformsSecurity Access Manager provides forms authentication as an alternative to the standard basic authentication mechanism. This method produces a custom HTML login form from Security Access Manager instead of the standard login prompt resulting from a basic authentication challenge.When you use forms-based login, the browser does not cache the username and password information as it does in basic authentication.By default, the Web Reverse Proxy is configured for forms-based authentication.Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsBasic authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.Enabling and disabling forms authenticationCustomizing HTML response formsForms authentication requires you to use a custom login form called login.html. Submitting login form data directly to WebSEAL

Forms authentication

Security Access Manager provides forms authentication as an alternative to the standard basic authentication mechanism. This method produces a custom HTML login form from Security Access Manager instead of the standard login prompt resulting from a basic authentication challenge.

When you use forms-based login, the browser does not cache the username and password information as it does in basic authentication.

By default, the Web Reverse Proxy is configured for forms-based authentication.

Enabling and disabling forms authentication

Customizing HTML response forms
Forms authentication requires you to use a custom login form called login.html.

Submitting login form data directly to WebSEAL

Parent topic: Authentication methods

Related concepts:

Basic authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

LTPA authentication

OAuth Authentication

Related reference:

Authentication terminology

Logout and password change operations

Enabling and disabling forms authentication Enabling and disabling forms authentication forms-auth stanza entryformsauthenticationenablingdisabling The forms-auth stanza entry, located in the [forms] stanza of the WebSEAL configuration file, enables and disables the forms authentication method. Forms authentication is disabled by default. To configure forms authentication:Stop the WebSEAL server.Edit the WebSEAL configuration file. In the [forms] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table. Configuring forms authenticationProtocol to SupportConfiguration File EntryHTTP forms-auth = httpHTTPS forms-auth = httpsBoth HTTP and HTTPS forms-auth = bothDisable forms authentication (default) forms-auth = noneFor example, to support both protocols: [forms] forms-auth = bothRestart the WebSEAL server.Forms authentication

Enabling and disabling forms authentication

About this task

The forms-auth stanza entry, located in the [forms] stanza of the WebSEAL configuration file, enables and disables the forms authentication method.

Forms authentication is disabled by default. To configure forms authentication:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. In the [forms] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.

Table 28. Configuring forms authentication

Protocol to Support
Configuration File Entry

HTTP

forms-auth = http

HTTPS

forms-auth = https

Both HTTP and HTTPS

forms-auth = both

Disable forms authentication (default)

forms-auth = none

For example, to support both protocols:

[forms]
forms-auth = both

Restart the WebSEAL server.

Parent topic: Forms authentication

Customizing HTML response forms Customizing HTML response forms Forms authentication requires you to use a custom login form called login.html. login.htmlHTMLresponse formsresponsesforms You can use the LMI access the default login.html form. You can customize the content and design of this form. For detailed information on the available HTML forms that you can customize, see Static HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. .Forms authentication

Customizing HTML response forms

Forms authentication requires you to use a custom login form called login.html.

About this task

You can use the LMI access the default login.html form.

You can customize the content and design of this form.

For detailed information on the available HTML forms that you can customize, see Static HTML server response pages.

Parent topic: Forms authentication

Submitting login form data directly to WebSEALSubmitting login form data directly to WebSEALauthenticationdirect posting of login datalogindirect posting of login dataPOSTmethodlogin datapkmslogin.formlogin_success.htmldirect posting of login data It is possible to perform forms authentication to WebSEAL without being prompted by WebSEAL. The following sequence describes the events that occur during a typical WebSEAL login where the user is prompted by WebSEAL with a login form:The user requests a protected resource. WebSEAL caches the user's request.WebSEAL returns a login form to the user.The user fills in the login form fields (providing the user name and password) and clicks a submit button.The submit button triggers a POST request to /pkmslogin.form. The request body contains the form field data. The pkmslogin.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following three locations:The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured. See Automatic redirection after authentication.The user's originally requested resource (if known).The generic login_success.html page. See Static HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. . Some application integration implementations might require logging in directly without making an initial request for a protected resource or being prompted by WebSEAL to login. Such a direct login can be accomplished using a POST request directly to /pkmslogin.form. The following sequence describes the events that occur during a direct login: The client sends a POST request to /pkmslogin.form with the proper form field data in the body of the request. WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following two locations: The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured. See Automatic redirection after authentication.The generic login_success.html page. See Static HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. . The format of the POST data must follow these conventions: The POST must be made to /pkmslogin.form.The POST request body must contain the field data for three fields: usernamepasswordlogin-form-typeThe value of login-form-type must be "pwd" for forms logins.The content-length header must indicate the length of the resulting request body. Example (using telnet): prompt> telnet webseal.example.com 80 Connected to webseal.example.com. Escape character is '^]'. POST /pkmslogin.form HTTP/1.1 host: webseal.webseal.com content-length: 56 username=testuser&password=my0passwd&login-form-type=pwdForms authentication

Submitting login form data directly to WebSEAL

About this task

It is possible to perform forms authentication to WebSEAL without being prompted by WebSEAL.

The following sequence describes the events that occur during a typical WebSEAL login where the user is prompted by WebSEAL with a login form:

Procedure

The user requests a protected resource.

WebSEAL caches the user's request.

WebSEAL returns a login form to the user.

The user fills in the login form fields (providing the user name and password) and clicks a submit button.

The submit button triggers a POST request to /pkmslogin.form. The request body contains the form field data.

Note: The pkmslogin.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following three locations:

The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured. See Automatic redirection after authentication.

The user's originally requested resource (if known).

The generic login_success.html page. See Static HTML server response pages.

Results

Some application integration implementations might require logging in directly without making an initial request for a protected resource or being prompted by WebSEAL to login. Such a direct login can be accomplished using a POST request directly to /pkmslogin.form.

The following sequence describes the events that occur during a direct login:

The client sends a POST request to /pkmslogin.form with the proper form field data in the body of the request.

WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following two locations:

The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured.

See Automatic redirection after authentication.

The generic login_success.html page.

See Static HTML server response pages.

The format of the POST data must follow these conventions:

The POST must be made to /pkmslogin.form.

The POST request body must contain the field data for three fields:

username

password

login-form-type

The value of login-form-type must be "pwd" for forms logins.

The content-length header must indicate the length of the resulting request body.

Example (using telnet):

prompt> telnet webseal.example.com 80
Connected to webseal.example.com.
Escape character is '^]'.
POST /pkmslogin.form HTTP/1.1
host: webseal.webseal.com
content-length: 56

username=testuser&password=my0passwd&login-form-type=pwd

Parent topic: Forms authentication

Client-side certificate authentication Client-side certificate authentication certificate authenticationauthenticationcertificateThis section contains the following topics:Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsBasic authenticationForms authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.Client-side certificate authentication modesCertificate authentication configuration task summaryEnabling certificate authenticationConfiguration of the certificate authentication mechanismYou can use the External Authentication Interface (EAI) protocol to configure a junctioned web application to handle certificate authentication on behalf of WebSEAL.Certificate login error pageAdministrators can choose to use the default error page, customize the error message, or specify an entirely different customized error page. Typically, administrators use the default page but might customize the contents of the error message.Certificate login formDisabling SSL session IDs for session trackingEnabling and configuring the Certificate SSL ID cacheSetting the timeout for Certificate SSL ID cacheError page for incorrect protocolDisabling certificate authenticationDisabling the Certificate SSL ID cacheTechnical notes for certificate authenticationFor all certificate configurations, a client-side certificate can be presented only once per browser session.

Client-side certificate authentication

This section contains the following topics:

Client-side certificate authentication modes

Certificate authentication configuration task summary

Enabling certificate authentication

Configuration of the certificate authentication mechanism
You can use the External Authentication Interface (EAI) protocol to configure a junctioned web application to handle certificate authentication on behalf of WebSEAL.

Certificate login error page
Administrators can choose to use the default error page, customize the error message, or specify an entirely different customized error page. Typically, administrators use the default page but might customize the contents of the error message.

Certificate login form

Disabling SSL session IDs for session tracking

Enabling and configuring the Certificate SSL ID cache

Setting the timeout for Certificate SSL ID cache

Error page for incorrect protocol

Disabling certificate authentication

Disabling the Certificate SSL ID cache

Technical notes for certificate authentication
For all certificate configurations, a client-side certificate can be presented only once per browser session.

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

LTPA authentication

OAuth Authentication

Related reference:

Authentication terminology

Logout and password change operations

Client-side certificate authentication modesClient-side certificate authentication modesclient-side certificatesClient-side certificate authentication enables a user to use a client-side digital certificate to request an authenticated identity for use within a Security Access Manager secure domain. When authentication is successful, WebSEAL obtains a Security Access Manager identity that is used to build a credential for the user. The credential specifies the permissions and authorities to be granted to the user. Client-side certificate authentication is disabled by default.WebSEAL supports client-side certificate authentication in three different modes. The administrator must specify the appropriate mode at configuration time. The following sections describe each mode:Client-side certificate authenticationRequired certificate authentication modeIn the required certificate authentication mode, WebSEAL always requires a client-side certificate with the first HTTPS request.Optional certificate authentication modeDelayed certificate authentication mode

Client-side certificate authentication modes

Client-side certificate authentication enables a user to use a client-side digital certificate to request an authenticated identity for use within a Security Access Manager secure domain. When authentication is successful, WebSEAL obtains a Security Access Manager identity that is used to build a credential for the user. The credential specifies the permissions and authorities to be granted to the user.

Client-side certificate authentication is disabled by default.

WebSEAL supports client-side certificate authentication in three different modes. The administrator must specify the appropriate mode at configuration time. The following sections describe each mode:

Required certificate authentication mode
In the required certificate authentication mode, WebSEAL always requires a client-side certificate with the first HTTPS request.

Optional certificate authentication mode

Delayed certificate authentication mode

Parent topic: Client-side certificate authentication

Required certificate authentication modeRequired certificate authentication modeRequired certificate authentication mode in IBM Security Access Manager for WebIn the required certificate authentication mode, WebSEAL always requires a client-side certificate with the first HTTPS request.certificate authenticationmode requirementsauthentication modecertificateWhen the user requests access to a resource over SSL, WebSEAL provides its server-side certificate, which allows the user to establish an SSL session. WebSEAL then asks the user for a client-side certificate. If the user does not present a valid certificate, the SSL connection with the user is closed and client-side certificate authentication is not attempted. To be valid, the data in the certificate must not be corrupted and the certificate itself must not have been revoked by a certificate revocation list (CRL).If a valid certificate is presented, but the authentication or authorization of the Distinguished Name (DN) in the certificate fails, the connection is established and an unauthenticated session is created. Access to protected resources is not allowed.Client-side certificate authentication modes

Required certificate authentication mode

In the required certificate authentication mode, WebSEAL always requires a client-side certificate with the first HTTPS request.

When the user requests access to a resource over SSL, WebSEAL provides its server-side certificate, which allows the user to establish an SSL session. WebSEAL then asks the user for a client-side certificate.

If the user does not present a valid certificate, the SSL connection with the user is closed and client-side certificate authentication is not attempted.

Note: To be valid, the data in the certificate must not be corrupted and the certificate itself must not have been revoked by a certificate revocation list (CRL).

If a valid certificate is presented, but the authentication or authorization of the Distinguished Name (DN) in the certificate fails, the connection is established and an unauthenticated session is created. Access to protected resources is not allowed.

Parent topic: Client-side certificate authentication modes

Optional certificate authentication modeOptional certificate authentication modecertificate authenticationoptional modeauthentication modeoptional certificateIn this mode, WebSEAL requests a client-side certificate with the first HTTPS request, but does not require it. When the user requests access to a resource over SSL, WebSEAL provides its server-side certificate, which allows the user to establish an SSL session. WebSEAL then asks the user for a client-side certificate. If the user presents a client-side certificate, WebSEAL uses it to initiate a certificate-based authentication session. If the user does not present a client-side certificate, WebSEAL allows the SSL session to continue but the user remains unauthenticated to Security Access Manager.Client-side certificate authentication modes

Optional certificate authentication mode

In this mode, WebSEAL requests a client-side certificate with the first HTTPS request, but does not require it.

When the user requests access to a resource over SSL, WebSEAL provides its server-side certificate, which allows the user to establish an SSL session. WebSEAL then asks the user for a client-side certificate. If the user presents a client-side certificate, WebSEAL uses it to initiate a certificate-based authentication session. If the user does not present a client-side certificate, WebSEAL allows the SSL session to continue but the user remains unauthenticated to Security Access Manager.

Parent topic: Client-side certificate authentication modes

Delayed certificate authentication modeDelayed certificate authentication modecertificate authenticationdelayedauthentication modedelayed certificateIn this mode, WebSEAL does not request a client-side certificate for the purpose of client-side certificate authentication until the user attempts to access a protected resource that requires certificate-based authentication. When the user requests access to a resource over SSL, WebSEAL provides its server-side certificate, which allows the user to establish an SSL session. WebSEAL checks the security policy on the requested resource to determine if certificate authentication is required. The security policy is described in the contents of an access control list (ACL) or protected object policy (POP) that has been attached to the protected resource.If the security policy does not require certificate authentication, WebSEAL does not request a client-side digital certificate.If the security policy does require certificate authentication, WebSEAL returns a login form. The user clicks a button contained in this form to initiate the certificate exchange.In this mode, the SSL session ID cannot be used to track user session activity, because the SSL session will be renegotiated (resulting in a new SSL session ID). All connections for the existing SSL session will be closed.Delayed certificate authentication is used in two scenarios, based on the user's authentication status at the time that the user requests a resource that requires certificate authentication. In both scenarios, a user can have an unlimited number of exchanges with the WebSEAL server prior to establishing a need to authenticate using certificates.The two scenarios include the following:User is unauthenticated In this scenario, the user remains unauthenticated because the user does not attempt to access any resources that require any authentication. When the user eventually attempts to access a resource that requires authentication because of an ACL, WebSEAL presents a certificate login form, and the user can initiate certificate transfer (by clicking the button on this form). WebSEAL retains the entry in the session cache for the unauthenticated user, but obtains a new SSL ID from GSKit. The old SSL session ID is discarded. When the user successfully authenticates, WebSEAL replaces the old unauthenticated user credentials from the session cache data with the new user credentials. The user is now authenticated, and is able to request access to resources that require authentication (because of an ACL).User has previously authenticated using another authentication method In this scenario (know as authentication strength policy or step-up authentication), the user was required to authenticate to Security Access Manager during the previous exchanges with WebSEAL. The previous authentication took place through a different authentication method, such as forms authentication. The user eventually attempts to access a resource that is protected by a protected object policy (POP) that requires client-side certificate authentication in order to access the resource. WebSEAL examines the current WebSEAL authentication strength policy configuration to determine the ranking of the enabled authentication methods. (The authentication strength policy ranks authentication methods in a hierarchy from weakest to strongest.) When certificate authentication is ranked stronger than the user's current authentication method, WebSEAL serves the user a step-up login form that contains the certificate login button. The user can click the button to initiate the certificate exchange. When the user successfully authenticates using a certificate, the user's authentication strength level is increased for the duration of the current session. WebSEAL retains the user's entry in the session cache, but obtains a new SSL session ID from GSKit. The old SSL session ID is discarded. WebSEAL replaces the old user credentials (which were based the user's previous authentication method) with the new user credentials. The authentication strength policy enables a user to move between different authentication levels during a session. Certificate authentication is one of the authentication levels that can be entered when a user needs to increase (step-up) authentication level in order to access protected object resources. To enable a user to move up to a certificate authentication level, administrators must modify the WebSEAL configuration file to include certificate authentication in the list of supported levels for authentication strength. For authentication strength policy configuration instructions, see Authentication strength policy (step-up).Client-side certificate authentication modes

Delayed certificate authentication mode

In this mode, WebSEAL does not request a client-side certificate for the purpose of client-side certificate authentication until the user attempts to access a protected resource that requires certificate-based authentication.

When the user requests access to a resource over SSL, WebSEAL provides its server-side certificate, which allows the user to establish an SSL session. WebSEAL checks the security policy on the requested resource to determine if certificate authentication is required. The security policy is described in the contents of an access control list (ACL) or protected object policy (POP) that has been attached to the protected resource.

If the security policy does not require certificate authentication, WebSEAL does not request a client-side digital certificate.

If the security policy does require certificate authentication, WebSEAL returns a login form. The user clicks a button contained in this form to initiate the certificate exchange.

In this mode, the SSL session ID cannot be used to track user session activity, because the SSL session will be renegotiated (resulting in a new SSL session ID). All connections for the existing SSL session will be closed.

Delayed certificate authentication is used in two scenarios, based on the user's authentication status at the time that the user requests a resource that requires certificate authentication. In both scenarios, a user can have an unlimited number of exchanges with the WebSEAL server prior to establishing a need to authenticate using certificates.

The two scenarios include the following:

User is unauthenticated

In this scenario, the user remains unauthenticated because the user does not attempt to access any resources that require any authentication. When the user eventually attempts to access a resource that requires authentication because of an ACL, WebSEAL presents a certificate login form, and the user can initiate certificate transfer (by clicking the button on this form).

WebSEAL retains the entry in the session cache for the unauthenticated user, but obtains a new SSL ID from GSKit. The old SSL session ID is discarded. When the user successfully authenticates, WebSEAL replaces the old unauthenticated user credentials from the session cache data with the new user credentials. The user is now authenticated, and is able to request access to resources that require authentication (because of an ACL).

User has previously authenticated using another authentication method

In this scenario (know as authentication strength policy or step-up authentication), the user was required to authenticate to Security Access Manager during the previous exchanges with WebSEAL. The previous authentication took place through a different authentication method, such as forms authentication.

The user eventually attempts to access a resource that is protected by a protected object policy (POP) that requires client-side certificate authentication in order to access the resource. WebSEAL examines the current WebSEAL authentication strength policy configuration to determine the ranking of the enabled authentication methods. (The authentication strength policy ranks authentication methods in a hierarchy from weakest to strongest.)

When certificate authentication is ranked stronger than the user's current authentication method, WebSEAL serves the user a step-up login form that contains the certificate login button. The user can click the button to initiate the certificate exchange. When the user successfully authenticates using a certificate, the user's authentication strength level is increased for the duration of the current session.

WebSEAL retains the user's entry in the session cache, but obtains a new SSL session ID from GSKit. The old SSL session ID is discarded. WebSEAL replaces the old user credentials (which were based the user's previous authentication method) with the new user credentials.

The authentication strength policy enables a user to move between different authentication levels during a session. Certificate authentication is one of the authentication levels that can be entered when a user needs to increase (step-up) authentication level in order to access protected object resources.

To enable a user to move up to a certificate authentication level, administrators must modify the WebSEAL configuration file to include certificate authentication in the list of supported levels for authentication strength.

For authentication strength policy configuration instructions, see Authentication strength policy (step-up).

Parent topic: Client-side certificate authentication modes

Certificate authentication configuration task summaryCertificate authentication configuration task summarycertificate authenticationconfiguration summaryconfiguration taskcertificate authenticationAll of the certificate authentication modes share a common set of configuration tasks. The delayed certificate authentication mode requires additional tasks.To enable client-side certificate authentication in any of the supported modes, complete the following tasks:Enabling certificate authenticationConfiguration of the certificate authentication mechanismYou can use the External Authentication Interface (EAI) protocol to configure a junctioned web application to handle certificate authentication on behalf of WebSEAL.Certificate login error pageAdministrators can choose to use the default error page, customize the error message, or specify an entirely different customized error page. Typically, administrators use the default page but might customize the contents of the error message.When enabling delayed certificate authentication mode, complete the following additional tasks:Certificate login formDisabling SSL session IDs for session trackingEnabling and configuring the Certificate SSL ID cacheSetting the timeout for Certificate SSL ID cacheError page for incorrect protocolThe WebSEAL server must be stopped and restarted to activate the new configuration settings.To disable (unconfigure) client-side certificate authentication, complete the following tasks:Disabling certificate authenticationDisabling the Certificate SSL ID cacheTechnical notes for certificate authentication:Technical notes for certificate authenticationFor all certificate configurations, a client-side certificate can be presented only once per browser session. The WebSEAL configuration file settings for certificate authentication are summarized in the Web Reverse Proxy Stanza Reference section.Client-side certificate authentication

Certificate authentication configuration task summary

All of the certificate authentication modes share a common set of configuration tasks. The delayed certificate authentication mode requires additional tasks.

To enable client-side certificate authentication in any of the supported modes, complete the following tasks:

Enabling certificate authentication

Configuration of the certificate authentication mechanism

Certificate login error page

When enabling delayed certificate authentication mode, complete the following additional tasks:

Certificate login form

Disabling SSL session IDs for session tracking

Enabling and configuring the Certificate SSL ID cache

Setting the timeout for Certificate SSL ID cache

Error page for incorrect protocol

Note: The WebSEAL server must be stopped and restarted to activate the new configuration settings.

To disable (unconfigure) client-side certificate authentication, complete the following tasks:

Disabling certificate authentication

Disabling the Certificate SSL ID cache

Technical notes for certificate authentication:

Technical notes for certificate authentication

The WebSEAL configuration file settings for certificate authentication are summarized in the Web Reverse Proxy Stanza Reference section.

Parent topic: Client-side certificate authentication

Enabling certificate authenticationEnabling certificate authenticationaccept-client-certs stanza entrycertificatesprompt_as_neededprompt_as_neededCertificate authentication is disabled by default. To enable certificate authentication: Edit the WebSEAL configuration file. In the [certificate] stanza, specify a value to the accept-client-certs stanza entry that instructs WebSEAL how to handle client-side certificate authentication requests. The following table provides the valid values:Configuring certificate authenticationConfigurationDescriptionaccept-client-certs = optionalClient can optionally use certificate-based authentication. WebSEAL asks clients for an X.509 certificate. If the user supplies a certificate, certificate-based authentication is used.accept-client-certs = requiredClient must use certificate-based authentication. WebSEAL asks clients for an X.509 certificate. If the user does not present a certificate, WebSEAL does not allow a connection. accept-client-certs = prompt_as_neededThe user is not required to authenticate with a certificate at session start-up. The user can later initiate certificate authentication. This setting enables delayed certificate authentication mode. For example, to prompt users for a client-side certificate only when the user encounters a resource that requires certificate authentication, enter: [certificate] accept-client-certs = prompt_as_needed This setting is used when implementing an authentication strength policy (step-up) for certificate authentication.Client-side certificate authentication

Enabling certificate authentication

About this task

Certificate authentication is disabled by default. To enable certificate authentication:

Procedure

Edit the WebSEAL configuration file. In the [certificate] stanza, specify a value to the accept-client-certs stanza entry that instructs WebSEAL how to handle client-side certificate authentication requests. The following table provides the valid values:

Table 29. Configuring certificate authentication

Configuration
Description

accept-client-certs = optional

Client can optionally use certificate-based authentication.

WebSEAL asks clients for an X.509 certificate. If the user supplies a certificate, certificate-based authentication is used.

accept-client-certs = required

Client must use certificate-based authentication.

WebSEAL asks clients for an X.509 certificate. If the user does not present a certificate, WebSEAL does not allow a connection.

accept-client-certs = prompt_as_needed

The user is not required to authenticate with a certificate at session start-up. The user can later initiate certificate authentication.

This setting enables delayed certificate authentication mode.

For example, to prompt users for a client-side certificate only when the user encounters a resource that requires certificate authentication, enter:

[certificate]
accept-client-certs = prompt_as_needed

This setting is used when implementing an authentication strength policy (step-up) for certificate authentication.

Parent topic: Client-side certificate authentication

Configuration of the certificate authentication mechanism Configuration of the certificate authentication mechanism You can use the External Authentication Interface (EAI) protocol to configure a junctioned web application to handle certificate authentication on behalf of WebSEAL.libsslauthn (shared library)sslauthn (DLL)cert-ssl stanza entryFor more information about EAI, see External authentication interface.Client-side certificate authenticationEAI certificate authenticationAn external application can also be used to authenticate the client certificate. This external application uses the EAI protocol to provide the authentication data that WebSEAL uses when generating the user credential.

Configuration of the certificate authentication mechanism

You can use the External Authentication Interface (EAI) protocol to configure a junctioned web application to handle certificate authentication on behalf of WebSEAL.

Note: For more information about EAI, see External authentication interface.

EAI certificate authentication
An external application can also be used to authenticate the client certificate. This external application uses the EAI protocol to provide the authentication data that WebSEAL uses when generating the user credential.

Parent topic: Client-side certificate authentication

EAI certificate authenticationEAI certificate authenticationEAI certificate authenticationAn external application can also be used to authenticate the client certificate. This external application uses the EAI protocol to provide the authentication data that WebSEAL uses when generating the user credential.The following diagram highlights the process flow for the authentication operation:EAI certificate authentication process flowA request is made for a resource which is protected by WebSEAL. WebSEAL negotiates the client certificate based on the setting of the accept-client-certs configuration entry.WebSEAL creates a sub-request, which is then sent to the configured EAI application. The URI for the EAI application is configured through the eai-uri configuration entry.The EAI application authenticates the user (based on the client certificate data) and provides the necessary EAI headers so that WebSEAL is able to correctly construct the credential for the user. If the authentication fails, the EAI should return no authentication data, which indicates to WebSEAL that an authentication error has occurred. At this point WebSEAL will generate an authentication error page and return this to the client.WebSEAL uses the authentication data to build a credential for the user.Now that the user has been correctly authenticated, WebSEAL continues to process the original request.The response to the original request is passed back to the client.Configuration of the certificate authentication mechanismYou can use the External Authentication Interface (EAI) protocol to configure a junctioned web application to handle certificate authentication on behalf of WebSEAL.

EAI certificate authentication

An external application can also be used to authenticate the client certificate. This external application uses the EAI protocol to provide the authentication data that WebSEAL uses when generating the user credential.

The following diagram highlights the process flow for the authentication operation:

A request is made for a resource which is protected by WebSEAL. WebSEAL negotiates the client certificate based on the setting of the accept-client-certs configuration entry.

WebSEAL creates a sub-request, which is then sent to the configured EAI application. The URI for the EAI application is configured through the eai-uri configuration entry.

The EAI application authenticates the user (based on the client certificate data) and provides the necessary EAI headers so that WebSEAL is able to correctly construct the credential for the user. If the authentication fails, the EAI should return no authentication data, which indicates to WebSEAL that an authentication error has occurred. At this point WebSEAL will generate an authentication error page and return this to the client.

WebSEAL uses the authentication data to build a credential for the user.

Now that the user has been correctly authenticated, WebSEAL continues to process the original request.

The response to the original request is passed back to the client.

Parent topic: Configuration of the certificate authentication mechanism

Certificate login error pageCertificate login error pageCertificate login error pageAdministrators can choose to use the default error page, customize the error message, or specify an entirely different customized error page. Typically, administrators use the default page but might customize the contents of the error message.certificate login error pageerror pagescertificate loginWebSEAL returns a default HTML response page containing an error message that is displayed when a user fails to successfully authenticate using client-side certificate authentication. Specifically, the error page is returned when the certificate is valid, but does not correspond to a Security Access Manager user.This page is not returned when a revoked certificate is presented. Certificate revocation is handled by SSL. When a revoked certificate is presented, the SSL connection is immediately closed, resulting in a browser error page (and not the WebSEAL error page).Administrators who choose to create a new HTML error page must edit the WebSEAL configuration file to indicate the location of the new page.The default WebSEAL configuration file entry is:[acnt-mgt] cert-failure = certfailure.htmlClient-side certificate authentication

Certificate login error page

Administrators can choose to use the default error page, customize the error message, or specify an entirely different customized error page. Typically, administrators use the default page but might customize the contents of the error message.

WebSEAL returns a default HTML response page containing an error message that is displayed when a user fails to successfully authenticate using client-side certificate authentication. Specifically, the error page is returned when the certificate is valid, but does not correspond to a Security Access Manager user.

This page is not returned when a revoked certificate is presented. Certificate revocation is handled by SSL. When a revoked certificate is presented, the SSL connection is immediately closed, resulting in a browser error page (and not the WebSEAL error page).

Administrators who choose to create a new HTML error page must edit the WebSEAL configuration file to indicate the location of the new page.

The default WebSEAL configuration file entry is:

[acnt-mgt]
cert-failure = certfailure.html

Parent topic: Client-side certificate authentication

Certificate login formCertificate login formcertificate-login stanza entrylogincertificate formscertificateslogin formWebSEAL provides an HTML page containing a login form, to be presented to users when the need for delayed certificate authentication has been identified.Administrators can choose to use the default login form, customize the login form, or specify an entirely different customized login page. Typically, administrators use the default file but customize the contents of the form.Administrators who choose to create a new HTML file must edit the WebSEAL configuration file to indicate the location of the new file.The default WebSEAL configuration file entry is:[acnt-mgt] certificate-login = certlogin.htmlClient-side certificate authentication

Certificate login form

WebSEAL provides an HTML page containing a login form, to be presented to users when the need for delayed certificate authentication has been identified.

Administrators can choose to use the default login form, customize the login form, or specify an entirely different customized login page. Typically, administrators use the default file but customize the contents of the form.

Administrators who choose to create a new HTML file must edit the WebSEAL configuration file to indicate the location of the new file.

The default WebSEAL configuration file entry is:

[acnt-mgt]
certificate-login = certlogin.html

Parent topic: Client-side certificate authentication

Disabling SSL session IDs for session trackingDisabling SSL session IDs for session trackingssl-id-sessions stanza entrySSLsession IDsdisabling This configuration step applies only when delayed certificate authentication has been enabled. Disable the use of SSL session IDs to track session state. Verify the default "no" value for the ssl-id-sessions stanza entry in the WebSEAL configuration file:[session] ssl-id-sessions = noIn this case, SSL IDs cannot be used to maintain user sessions because when the user is prompted for a certificate, the user's SSL ID will change. If ssl-id-sessions is set to "yes", WebSEAL generates an error message upon startup and shuts down.Client-side certificate authentication

Disabling SSL session IDs for session tracking

About this task

This configuration step applies only when delayed certificate authentication has been enabled.

Procedure

Disable the use of SSL session IDs to track session state. Verify the default "no" value for the ssl-id-sessions stanza entry in the WebSEAL configuration file:

[session]
ssl-id-sessions = no

Note: In this case, SSL IDs cannot be used to maintain user sessions because when the user is prompted for a certificate, the user's SSL ID will change. If ssl-id-sessions is set to "yes", WebSEAL generates an error message upon startup and shuts down.

Parent topic: Client-side certificate authentication

Enabling and configuring the Certificate SSL ID cacheEnabling and configuring the Certificate SSL ID cacheCertificate SSL ID cachecert-cache-max-entriesssl-max-entries This configuration step applies only when delayed certificate authentication has been enabled. To configure the cache, complete the following steps:Verify that certificate authentication is enabled. See Enabling certificate authentication.Specify the maximum number of entries allowed in the cache. Edit the WebSEAL configuration file. In the [certificate] stanza, assign a value to cert-cache-max-entries. For example: [certificate] cert-cache-max-entries = 1024The value corresponds to the maximum number of concurrent certificate authentications. The default value is one quarter of the default number of entries in the SSL ID cache. (Most SSL sessions do not require certificate logins or require certificate authentication only once for the session). The number of entries in the SSL ID cache is set in the [ssl] stanza. For example:[ssl] ssl-max-entries = 4096Therefore, the default value for cert-cache-max-entries is 1024, which is one quarter of the default value for ssl-max-entries, which is 4096. Most user requests to WebSEAL occur over SSL connections, and all requests over SSL connections without certificates must check the cache. Keeping the cache size smaller can significantly improve performance.Client-side certificate authentication

Enabling and configuring the Certificate SSL ID cache

About this task

This configuration step applies only when delayed certificate authentication has been enabled.

To configure the cache, complete the following steps:

Procedure

Verify that certificate authentication is enabled.

See Enabling certificate authentication.

Specify the maximum number of entries allowed in the cache. Edit the WebSEAL configuration file. In the [certificate] stanza, assign a value to cert-cache-max-entries. For example:

[certificate]
cert-cache-max-entries = 1024

The value corresponds to the maximum number of concurrent certificate authentications. The default value is one quarter of the default number of entries in the SSL ID cache. (Most SSL sessions do not require certificate logins or require certificate authentication only once for the session). The number of entries in the SSL ID cache is set in the [ssl] stanza. For example:

[ssl]
ssl-max-entries = 4096

Therefore, the default value for cert-cache-max-entries is 1024, which is one quarter of the default value for ssl-max-entries, which is 4096.

Note: Most user requests to WebSEAL occur over SSL connections, and all requests over SSL connections without certificates must check the cache. Keeping the cache size smaller can significantly improve performance.

Parent topic: Client-side certificate authentication

Setting the timeout for Certificate SSL ID cacheSetting the timeout for Certificate SSL ID cachecert-cache-timeout stanza entrycertificate authenticationdelayed This configuration step applies only when delayed certificate authentication has been enabled. Complete the following steps:Verify that certificate authentication is enabled. See Enabling certificate authentication.Edit the WebSEAL configuration file. In the [certificate] stanza, adjust the value of cert-cache-timeout as necessary. For example:[certificate] cert-cache-timeout = 120 The value is the maximum lifetime for an entry in the cache, expressed as a number of seconds. Use the default value unless your conditions warrant modifying it. Possible reasons to modify the value include: Systems with memory restrictions might need a reduced expiration time.The expiration time might need to be increased if there is a significant lag between the time when the user initiates a certificate transfer and when the user actually submits the certificate.Lower values clean out the cache sooner when no certificate authentications are required. Cleaning the cache frees system memory.Client-side certificate authentication

Setting the timeout for Certificate SSL ID cache

About this task

This configuration step applies only when delayed certificate authentication has been enabled.

Complete the following steps:

Procedure

Verify that certificate authentication is enabled.
See Enabling certificate authentication.

Edit the WebSEAL configuration file. In the [certificate] stanza, adjust the value of cert-cache-timeout as necessary. For example:

[certificate]
cert-cache-timeout = 120

The value is the maximum lifetime for an entry in the cache, expressed as a number of seconds. Use the default value unless your conditions warrant modifying it. Possible reasons to modify the value include:

Systems with memory restrictions might need a reduced expiration time.

The expiration time might need to be increased if there is a significant lag between the time when the user initiates a certificate transfer and when the user actually submits the certificate.

Lower values clean out the cache sooner when no certificate authentications are required. Cleaning the cache frees system memory.

Parent topic: Client-side certificate authentication

Error page for incorrect protocolError page for incorrect protocolcert-stepup-http stanza entryincorrect protocolerror pageserror pagesincorrect protocolThis configuration step applies only when delayed certificate authentication has been enabled. WebSEAL provides a default HTML page containing an error message to be displayed when an authenticated user attempts to increase the authentication strength level to certificate authentication from an HTTP session. Users attempting to increase the authentication level to certificate authentication must use the HTTPS protocol.Administrators can choose to use the default error page, customize the error message, or specify an entirely different customized error page. Typically, administrators use the default page but might customize the contents of the error message.Administrators who choose to create a new HTML error page must edit the WebSEAL configuration file to indicate the location of the new page.The default WebSEAL configuration file entry is:[acnt-mgt] cert-stepup-http = certstepuphttp.htmlClient-side certificate authentication

Error page for incorrect protocol

This configuration step applies only when delayed certificate authentication has been enabled.

WebSEAL provides a default HTML page containing an error message to be displayed when an authenticated user attempts to increase the authentication strength level to certificate authentication from an HTTP session. Users attempting to increase the authentication level to certificate authentication must use the HTTPS protocol.

Administrators can choose to use the default error page, customize the error message, or specify an entirely different customized error page. Typically, administrators use the default page but might customize the contents of the error message.

Administrators who choose to create a new HTML error page must edit the WebSEAL configuration file to indicate the location of the new page.

The default WebSEAL configuration file entry is:

[acnt-mgt]
cert-stepup-http = certstepuphttp.html

Parent topic: Client-side certificate authentication

Disabling certificate authenticationDisabling certificate authenticationaccept-clients-certs stanza entrycertificate authenticationdisabling To disable certificate authentication:Stop the WebSEAL server.Edit the WebSEAL configuration file. In the [certificate] stanza, specify the following key = value pair:[certificate] accept-client-certs = neverRestart the WebSEAL server.Client-side certificate authentication

Disabling certificate authentication

About this task

To disable certificate authentication:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. In the [certificate] stanza, specify the following key = value pair:

[certificate]
accept-client-certs = never

Restart the WebSEAL server.

Parent topic: Client-side certificate authentication

Disabling the Certificate SSL ID cacheDisabling the Certificate SSL ID cacheCertificate SSL ID cachedisabling The Certificate SSL ID cache is used only with delayed certificate authentication or authentication strength step-up to certificate authentication.The cache is disabled automatically, based on the configuration settings for certificate authentication. To verify that the cache is disabled, examine the value for accept-client-certs in the [certificate] stanza. Verify that the value is one of the following:requiredoptionalneverVerify that the value is not prompt_as_needed.Client-side certificate authentication

Disabling the Certificate SSL ID cache

About this task

The Certificate SSL ID cache is used only with delayed certificate authentication or authentication strength step-up to certificate authentication.

The cache is disabled automatically, based on the configuration settings for certificate authentication.

Procedure

To verify that the cache is disabled, examine the value for accept-client-certs in the [certificate] stanza. Verify that the value is one of the following:

required

optional

never

Verify that the value is not prompt_as_needed.

Parent topic: Client-side certificate authentication

Technical notes for certificate authenticationTechnical notes for certificate authenticationTechnical notes for certificate authentication in IBM Security Access Manager for WebFor all certificate configurations, a client-side certificate can be presented only once per browser session.certificate authenticationtechnical notestechnical notescertificate authenticationIf the client-side certificate exchange fails, WebSEAL requires that the browser session be restarted before a client-side certificate can be presented again.Client-side certificate authentication

Technical notes for certificate authentication

For all certificate configurations, a client-side certificate can be presented only once per browser session.

If the client-side certificate exchange fails, WebSEAL requires that the browser session be restarted before a client-side certificate can be presented again.

Parent topic: Client-side certificate authentication

Token authentication Token authentication token authenticationauthenticationtokenSecurity Access Manager supports authentication using a token passcode supplied by the client.Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsBasic authenticationForms authenticationClient-side certificate authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.Token authentication conceptsToken authentication configuration task summaryEnabling token authenticationDisabling token authenticationSubmitting login form data directly to WebSEAL

Token authentication

Security Access Manager supports authentication using a token passcode supplied by the client.

Token authentication concepts

Token authentication configuration task summary

Enabling token authentication

Disabling token authentication

Submitting login form data directly to WebSEAL

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Client-side certificate authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

LTPA authentication

OAuth Authentication

Related reference:

Authentication terminology

Logout and password change operations

Token authentication conceptsToken authentication conceptsToken authentication concepts in IBM Security Access Manager for Webtoken authenticationconceptsconceptstoken authenticationThis section contains the following topics:Token authenticationToken authentication moduleSecurID Token authenticationAuthentication process flow for tokens in new PIN mode

Token authentication concepts

This section contains the following topics:

Token authentication module

SecurID Token authentication

Authentication process flow for tokens in new PIN mode

Parent topic: Token authentication

Token authentication moduleToken authentication moduletoken authenticationmodulemodulestoken authenticationSecurID (RSA) authenticationRSA SecurID authenticationRSA ACE/Agenttoken authenticationRSA ACE/ServerTwo-factor authentication requires users to provide two forms of identification.For example, a single factor of identification, such as a password, plus a second factor in the form of an authentication token.A simple two-factor method --- based on something the user knows plus something the user possesses -- provides a more reliable level of user authentication than reusable passwords.Security Access Manager reverse proxies have a built-in client that is compatible with the RSA SecurID authentication server(RSA ACE/Server) and is written against the RSA Authentication API. WebSEAL provides RSA authentication client functions (RSA ACE/Agent), and is certified as RSA SecurID Ready. By default, this built-in module for token authentication is hard-coded to map RSA SecurID token passcode data. This token authentication mechanism expects the user name used by the client to map to an existing user account in the Security Access Manager LDAP registry. Token authentication concepts

Token authentication module

Two-factor authentication requires users to provide two forms of identification.For example, a single factor of identification, such as a password, plus a second factor in the form of an authentication token.A simple two-factor method --- based on something the user knows plus something the user possesses -- provides a more reliable level of user authentication than reusable passwords.

Security Access Manager reverse proxies have a built-in client that is compatible with the RSA SecurID authentication server(RSA ACE/Server) and is written against the RSA Authentication API. WebSEAL provides RSA authentication client functions (RSA ACE/Agent), and is certified as RSA SecurID Ready.

By default, this built-in module for token authentication is hard-coded to map RSA SecurID token passcode data. This token authentication mechanism expects the user name used by the client to map to an existing user account in the Security Access Manager LDAP registry.

Parent topic: Token authentication concepts

SecurID Token authentication SecurID Token authentication token authenticationRSA SecurIDPIN modeThe reverse proxy token authentication process uses the RSA ACE/Agent client version 8.1.2. RSA ACE/Servers authenticate several different tokens, including software tokens and hand-held microprocessor-controlled devices. RSA SecurID authenticators (tokens) are binary programs running on a workstation, installed on a smartcard, or running as a plug-in to a Web browser. RSA SecurID authenticators can run as an application. The application displays a window into which a user enters a Personal Identification Number (PIN), and the Software Token computes the passcode. The user can then authenticate to WebSEAL by entering the passcode into a login form.The most typical form of RSA SecurID authenticator (token) is the hand-held device. The device is usually a key fob or slim card. The token can have a PIN pad, onto which a user enters a PIN, in order to generate a passcode. When the token has no PIN pad, the passcode is created by concatenating the user's PIN and tokencode. A tokencode is changing number displayed on the key fob. The tokencode is a number generated by the RSA SecurID authenticator at one minute intervals. A user then enters the PIN and tokencode to authenticate to the RSA ACE/Server.WebSEAL supports both RSA token modes:Next tokencode mode This mode is used when the user enters the correct PIN but an incorrect tokencode. Typically, the tokencode must be entered incorrectly three times in a row to send the tokencard into next tokencode mode. When the user enters the correct passcode, the tokencode is automatically changed. The user waits for the new tokencode, and then enters the passcode again.New PIN mode The token can be in New PIN mode when the old PIN is still assigned. The token is placed in this mode when the administrator wants to enforce a maximum password age policy. The token is also in New PIN mode when the PIN is cleared or has not been assigned. Newly assigned tokens might not yet have a PIN. A PIN can be cleared by an administrator when the user has forgotten it or suspects that it has been compromised.RSA SecurID PINs can be created in different ways:User-definedSystem-generatedUser-selectablePINs modes are defined by the method of creation, and by rules that specify parameters for password creation and device type. WebSEAL supports the following types of user-defined PINs:4-8 alphanumeric characters,non-PINPAD token4-8 alphanumeric characters,password5–7 numeric characters, non-PINPAD token5-7 numeric characters, PINPAD token5-7 numeric characters, Deny 4-digit PIN5-7 numeric characters, Deny alphanumericWebSEAL does not support the following types of new PINs:System-generated, non-PINPAD tokenSystem-generated, PINPAD tokenUser-selectable, non-PINPAD tokenUser-selectable, PINPAD tokenToken users cannot reset their PIN without an ACE administrator first clearing the token or putting it in new PIN mode. This means users with valid PINs cannot post to pkmspassword.form. Attempts to access this form return an error message. Token authentication concepts

SecurID Token authentication

The reverse proxy token authentication process uses the RSA ACE/Agent client version 8.1.2.

RSA ACE/Servers authenticate several different tokens, including software tokens and hand-held microprocessor-controlled devices. RSA SecurID authenticators (tokens) are binary programs running on a workstation, installed on a smartcard, or running as a plug-in to a Web browser. RSA SecurID authenticators can run as an application. The application displays a window into which a user enters a Personal Identification Number (PIN), and the Software Token computes the passcode. The user can then authenticate to WebSEAL by entering the passcode into a login form.

The most typical form of RSA SecurID authenticator (token) is the hand-held device. The device is usually a key fob or slim card. The token can have a PIN pad, onto which a user enters a PIN, in order to generate a passcode. When the token has no PIN pad, the passcode is created by concatenating the user's PIN and tokencode. A tokencode is changing number displayed on the key fob. The tokencode is a number generated by the RSA SecurID authenticator at one minute intervals. A user then enters the PIN and tokencode to authenticate to the RSA ACE/Server.

WebSEAL supports both RSA token modes:

Next tokencode mode

This mode is used when the user enters the correct PIN but an incorrect tokencode. Typically, the tokencode must be entered incorrectly three times in a row to send the tokencard into next tokencode mode. When the user enters the correct passcode, the tokencode is automatically changed. The user waits for the new tokencode, and then enters the passcode again.

New PIN mode

The token can be in New PIN mode when the old PIN is still assigned. The token is placed in this mode when the administrator wants to enforce a maximum password age policy. The token is also in New PIN mode when the PIN is cleared or has not been assigned. Newly assigned tokens might not yet have a PIN. A PIN can be cleared by an administrator when the user has forgotten it or suspects that it has been compromised.

RSA SecurID PINs can be created in different ways:

User-defined

System-generated

User-selectable

PINs modes are defined by the method of creation, and by rules that specify parameters for password creation and device type.

WebSEAL supports the following types of user-defined PINs:

4-8 alphanumeric characters,non-PINPAD token

4-8 alphanumeric characters,password

5–7 numeric characters, non-PINPAD token

5-7 numeric characters, PINPAD token

5-7 numeric characters, Deny 4-digit PIN

5-7 numeric characters, Deny alphanumeric

WebSEAL does not support the following types of new PINs:

System-generated, non-PINPAD token

System-generated, PINPAD token

User-selectable, non-PINPAD token

User-selectable, PINPAD token

Token users cannot reset their PIN without an ACE administrator first clearing the token or putting it in new PIN mode. This means users with valid PINs cannot post to pkmspassword.form. Attempts to access this form return an error message.

Parent topic: Token authentication concepts

Authentication process flow for tokens in new PIN modeAuthentication process flow for tokens in new PIN modeAuthentication process flow for tokens in new PIN mode in IBM Security Access Manager for Webauthentication process flowfor tokens in new PIN modetoken authenticationnew PIN modeprocess flowA user requests a protected Web object that requires token authentication.WebSEAL returns an authentication page, requesting username and passcode. The user types the username and tokencode and submits the form to WebSEAL's authentication module. When the user has no PIN, either because the tokencard is new or the administrator reset the PIN, the tokencode is the same as the passcode. When the user has a PIN, but the tokencard is in New PIN mode, the user enters the PIN plus the tokencode.The WebSEAL token authentication module sends the authentication request to the RSA ACE/Server.The RSA ACE/Server processes the request as follows: If the authentication is unsuccessful, the result is returned to WebSEAL by the WebSEAL token authentication module. WebSEAL displays an error page to the client (return to step 2).If the token was not in new PIN mode, the user is authenticated. The WebSEAL token authentication module returns success to the WebSEAL server, which serves the requested protected Web object. (End of authentication workflow).If the token is in new PIN mode, the RSA ACE/Server returns the NEW_PIN error code to the WebSEAL token authentication module.WebSEAL presents the password expired form to the user.The user enters tokencode or passcode and the new PIN and posts it to WebSEAL.WebSEAL checks to see if a password strength module is configured. If no password strength module is configured, WebSEAL continues to step 9.If a password strength module is configured, WebSEAL checks the new PIN. If the PIN is valid, WebSEAL continues to step 9. If the PIN is not valid, WebSEAL returns to step 6.The WebSEAL authentication module sends the tokencode and new PIN to the RSA ACE/Server.The RSA ACE/Server returns a response code.If the PIN set call to the RSA ACE/Server is successful, WebSEAL returns the originally requested protected Web object to the client. If the PIN set call fails, authentication workflow returns to step 6.Token authentication concepts

Authentication process flow for tokens in new PIN mode

A user requests a protected Web object that requires token authentication.

WebSEAL returns an authentication page, requesting username and passcode.

The user types the username and tokencode and submits the form to WebSEAL's authentication module.

When the user has no PIN, either because the tokencard is new or the administrator reset the PIN, the tokencode is the same as the passcode. When the user has a PIN, but the tokencard is in New PIN mode, the user enters the PIN plus the tokencode.

The WebSEAL token authentication module sends the authentication request to the RSA ACE/Server.

The RSA ACE/Server processes the request as follows:

If the authentication is unsuccessful, the result is returned to WebSEAL by the WebSEAL token authentication module. WebSEAL displays an error page to the client (return to step 2).

If the token was not in new PIN mode, the user is authenticated. The WebSEAL token authentication module returns success to the WebSEAL server, which serves the requested protected Web object. (End of authentication workflow).

If the token is in new PIN mode, the RSA ACE/Server returns the NEW_PIN error code to the WebSEAL token authentication module.

WebSEAL presents the password expired form to the user.

The user enters tokencode or passcode and the new PIN and posts it to WebSEAL.

WebSEAL checks to see if a password strength module is configured.

If no password strength module is configured, WebSEAL continues to step 9.

If a password strength module is configured, WebSEAL checks the new PIN. If the PIN is valid, WebSEAL continues to step 9. If the PIN is not valid, WebSEAL returns to step 6.

The WebSEAL authentication module sends the tokencode and new PIN to the RSA ACE/Server.

The RSA ACE/Server returns a response code.

If the PIN set call to the RSA ACE/Server is successful, WebSEAL returns the originally requested protected Web object to the client. If the PIN set call fails, authentication workflow returns to step 6.

Parent topic: Token authentication concepts

Token authentication configuration task summaryToken authentication configuration task summaryToken authentication configuration task summary in IBM Security Access Manager for Webtoken authenticationconfiguration tasksconfiguration tasktoken authenticationTo configure token authentication, the instructions in the following sections must be completed: Enabling token authenticationWhen a password strength module is used with token authentication, the instructions in the following section must be completed: Password strengthThe password strength module validates the strength of new passwords. To unconfigure token authentication, complete the instructions in the following section: Disabling token authenticationTo submit login form data directly to WebSEAL: Submitting login form data directly to WebSEALToken authentication

Token authentication configuration task summary

To configure token authentication, the instructions in the following sections must be completed:

Enabling token authentication

When a password strength module is used with token authentication, the instructions in the following section must be completed:

Password strength

To unconfigure token authentication, complete the instructions in the following section:

Disabling token authentication

To submit login form data directly to WebSEAL:

Submitting login form data directly to WebSEAL

Parent topic: Token authentication

Enabling token authenticationEnabling token authenticationtoken-auth stanza entrytoken authenticationenabling The token-auth stanza entry, located in the [token] stanza of the WebSEAL configuration file, enables and disables the token authentication method. Token authentication is disabled by default. To configure token authentication:Stop the WebSEAL server.Edit the WebSEAL configuration file. In the [token] stanza, specify the protocols to support in your network environment.The protocols are shown in the following table. Configuring token authenticationProtocol to SupportConfiguration File EntryHTTP token-auth = httpHTTPS token-auth = httpsBoth HTTP and HTTPS token-auth = bothDisable token authentication (default) token-auth = noneFor example, to support both protocols: [token] token-auth = bothRestart the WebSEAL server.Token authentication

Enabling token authentication

About this task

The token-auth stanza entry, located in the [token] stanza of the WebSEAL configuration file, enables and disables the token authentication method.

Token authentication is disabled by default. To configure token authentication:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. In the [token] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.

Table 30. Configuring token authentication

Protocol to Support
Configuration File Entry

HTTP

token-auth = http

HTTPS

token-auth = https

Both HTTP and HTTPS

token-auth = both

Disable token authentication (default)

token-auth = none

For example, to support both protocols:

[token]
token-auth = both

Restart the WebSEAL server.

Parent topic: Token authentication

Disabling token authenticationDisabling token authenticationDisabling token authentication in IBM Security Access Manager for Webtoken authenticationdisabling To disable token authentication: Stop the WebSEAL server.Edit the WebSEAL configuration file. Set token-auth to "none":[token] token-auth = noneRestart the WebSEAL server. Token authentication is disabled by default.Token authentication

Disabling token authentication

About this task

To disable token authentication:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. Set token-auth to "none":[token] token-auth = none

Restart the WebSEAL server.

Results

Token authentication is disabled by default.

Parent topic: Token authentication

Submitting login form data directly to WebSEALSubmitting login form data directly to WebSEALauthenticationdirect posting of login datalogindirect posting of login dataPOSTmethodlogin datapkmslogin.formlogin_success.htmldirect posting of login data It is possible to perform token (or forms) authentication to WebSEAL without being prompted by WebSEAL. The following sequence describes the events that occur during a typical WebSEAL login where the user is prompted by WebSEAL with a login form.The user requests a protected resource. WebSEAL caches the user's request.WebSEAL returns a login form to the user.The user fills in the login form fields (providing the user name and passcode) and clicks a submit button.The submit button triggers a POST request to /pkmslogin.form. The request body contains the form field data. The pkmslogin.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following three locations:The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured. See Automatic redirection after authentication.The user's originally requested resource (if known).The generic login_success.html page. See Static HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. . Some application integration implementations might require logging in directly without making an initial request for a protected resource or being prompted by WebSEAL to login. Such a direct login can be accomplished using a POST request directly to /pkmslogin.form. The following sequence describes the events that occur during a direct login: The client sends a POST request to /pkmslogin.form with the proper form field data in the body of the request. WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following two locations: The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured. See Automatic redirection after authentication.The generic login_success.html page. See Static HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. . The format of the POST data must follow these conventions: The POST must be made to /pkmslogin.form.The POST request body must contain the field data for three fields: usernamepasswordlogin-form-typeThe value of login-form-type must be "token" for token logins.The content-length header must indicate the length of the resulting request body. Example (using telnet): prompt> telnet webseal.example.com 80 Connected to webseal.example.com. Escape character is '^]'. POST /pkmslogin.form HTTP/1.1 host: webseal.webseal.com content-length: 58 username=testuser&password=123456789&login-form-type=tokenToken authentication

Submitting login form data directly to WebSEAL

About this task

It is possible to perform token (or forms) authentication to WebSEAL without being prompted by WebSEAL.

The following sequence describes the events that occur during a typical WebSEAL login where the user is prompted by WebSEAL with a login form.

Procedure

The user requests a protected resource.

WebSEAL caches the user's request.

WebSEAL returns a login form to the user.

The user fills in the login form fields (providing the user name and passcode) and clicks a submit button.

The submit button triggers a POST request to /pkmslogin.form. The request body contains the form field data.

Note: The pkmslogin.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following three locations:

The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured.

See Automatic redirection after authentication.

The user's originally requested resource (if known).

The generic login_success.html page.

See Static HTML server response pages.

Results

Some application integration implementations might require logging in directly without making an initial request for a protected resource or being prompted by WebSEAL to login. Such a direct login can be accomplished using a POST request directly to /pkmslogin.form.

The following sequence describes the events that occur during a direct login:

The client sends a POST request to /pkmslogin.form with the proper form field data in the body of the request.

WebSEAL authenticates the user and, upon successful authentication, follows an order of precedence for redirecting the user to one of the following two locations:

The location specified by the login-redirect-page entry in the [acnt-mgt] stanza, if configured.

See Automatic redirection after authentication.

The generic login_success.html page.

See Static HTML server response pages.

The format of the POST data must follow these conventions:

The POST must be made to /pkmslogin.form.

The POST request body must contain the field data for three fields:

username

password

login-form-type

The value of login-form-type must be "token" for token logins.

The content-length header must indicate the length of the resulting request body.

Example (using telnet):

prompt> telnet webseal.example.com 80
Connected to webseal.example.com.
Escape character is '^]'.
POST /pkmslogin.form HTTP/1.1
host: webseal.webseal.com
content-length: 58

username=testuser&password=123456789&login-form-type=token

Parent topic: Token authentication

Kerberos authentication through an External Authentication Interface (EAI)Kerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. authenticationKerberosWindowssingle sign-onKerberos authenticationsingle sign-onWindows desktopKerberosauthenticationEAIThe junctioned web server acts as an External Authentication Interface (EAI) application and completes the Kerberos authentication. This web server, known as the Kerberos Authenticator, then passes the authenticated user identity back to the appliance in an EAI header. For more information about EAI, see External authentication interface.Topic index:Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsBasic authenticationForms authenticationClient-side certificate authenticationToken authenticationWindows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.Configuring Kerberos authentication with an external Kerberos AuthenticatorYou can achieve Windows desktop single signon by configuring a Kerberos Authenticator to authenticate clients on behalf of the appliance.LimitationsWhen using an external Kerberos authenticator, the appliance can support Kerberos authentication only. It cannot support NTLM authentication.

Kerberos authentication through an External Authentication Interface (EAI)

The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance.

The junctioned web server acts as an External Authentication Interface (EAI) application and completes the Kerberos authentication. This web server, known as the Kerberos Authenticator, then passes the authenticated user identity back to the appliance in an EAI header. For more information about EAI, see External authentication interface.

Topic index:

Configuring Kerberos authentication with an external Kerberos Authenticator
You can achieve Windows desktop single signon by configuring a Kerberos Authenticator to authenticate clients on behalf of the appliance.

Limitations
When using an external Kerberos authenticator, the appliance can support Kerberos authentication only. It cannot support NTLM authentication.

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Client-side certificate authentication

Token authentication

Windows desktop single sign-on

LTPA authentication

OAuth Authentication

Related reference:

Authentication terminology

Logout and password change operations

Configuring Kerberos authentication with an external Kerberos AuthenticatorConfiguring Kerberos authentication with an external Kerberos AuthenticatorYou can achieve Windows desktop single signon by configuring a Kerberos Authenticator to authenticate clients on behalf of the appliance.KerberosauthenticationconfigurationWindowssingle signonconfiguration stepsKerberos authenticationYou can configure a junctioned web server to complete the actual authentication and return the authenticated identity to the appliance. External Kerberos authenticationConfiguring Windows desktop single signon for the IBM Security Web Gateway applianceComplete the following steps to configure an external Kerberos Authenticator to do the authentication on behalf of the appliance. An example is provided for each step. Collectively, these examples describe one possible configuration that supports Windows desktop single signon. Install the Policy Server and configure its user registry. For example, Active Directory.Configure a web server that supports Kerberos Authentication. This web server is the Kerberos Authenticator. For example, install WebSEAL on the domain controller and configure Kerberos authentication. See Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. .Configure the External Authentication Interface (EAI) application on the Kerberos Authenticator. For example, create a simple Common Gateway Interface (CGI) to act as the EAI. This CGI creates an EAI response, setting the am-eai-user-id header field as the name of the authenticated user. You can now verify the configuration of the Kerberos Authenticator. Add a Windows client to the domain. Verify that Windows desktop single signon occurs when you access the WebSEAL server from this client. You can install a network protocol analyzer, such as Wireshark, on the domain controller to monitor and validate the network traffic.Configure WebSEAL on the appliance to use the external Kerberos Authenticator for authentication. For example, follow these steps: Create a junction to the Kerberos authenticator.Configure the CGI script as an EAI application.Set the strip-www-authenticate-headers configuration entry to no.If the strip-www-authenticate-headers configuration entry is set to yes, WebSEAL removes the Negotiate www-authenticate and NTLM www-authenticate headers from junctioned server responses. Therefore, you must set the value to no to keep these www-authenticate headers in the junctioned server responses. For more information about this configuration entry, see the Reference information in the IBM Knowledge Center.You can now verify that Windows desktop single signon is available on the appliance. Send a request from the Windows client, through the WebSEAL server on the appliance, to the EAI application. Single signon occurs. That is, the user can access the WebSEAL server on the appliance as an authenticated user. Again, you can use a network protocol analyzer to monitor and validate the network traffic.Kerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance.

Configuring Kerberos authentication with an external Kerberos Authenticator

You can achieve Windows desktop single signon by configuring a Kerberos Authenticator to authenticate clients on behalf of the appliance.

About this task

You can configure a junctioned web server to complete the actual authentication and return the authenticated identity to the appliance.

Figure 14. External Kerberos authentication

Complete the following steps to configure an external Kerberos Authenticator to do the authentication on behalf of the appliance. An example is provided for each step. Collectively, these examples describe one possible configuration that supports Windows desktop single signon.

Procedure

Install the Policy Server and configure its user registry. For example, Active Directory.

Configure a web server that supports Kerberos Authentication. This web server is the Kerberos Authenticator. For example, install WebSEAL on the domain controller and configure Kerberos authentication.

See Windows desktop single sign-on.

Configure the External Authentication Interface (EAI) application on the Kerberos Authenticator. For example, create a simple Common Gateway Interface (CGI) to act as the EAI. This CGI creates an EAI response, setting the am-eai-user-id header field as the name of the authenticated user.

You can now verify the configuration of the Kerberos Authenticator. Add a Windows client to the domain. Verify that Windows desktop single signon occurs when you access the WebSEAL server from this client.

You can install a network protocol analyzer, such as Wireshark, on the domain controller to monitor and validate the network traffic.

Configure WebSEAL on the appliance to use the external Kerberos Authenticator for authentication. For example, follow these steps:

Create a junction to the Kerberos authenticator.

Configure the CGI script as an EAI application.

Set the strip-www-authenticate-headers configuration entry to no.

If the strip-www-authenticate-headers configuration entry is set to yes, WebSEAL removes the Negotiate www-authenticate and NTLM www-authenticate headers from junctioned server responses. Therefore, you must set the value to no to keep these www-authenticate headers in the junctioned server responses.

For more information about this configuration entry, see the Reference information in the IBM Knowledge Center.

You can now verify that Windows desktop single signon is available on the appliance.

Send a request from the Windows client, through the WebSEAL server on the appliance, to the EAI application. Single signon occurs. That is, the user can access the WebSEAL server on the appliance as an authenticated user. Again, you can use a network protocol analyzer to monitor and validate the network traffic.

Parent topic: Kerberos authentication through an External Authentication Interface (EAI)

LimitationsLimitationsIBM Security Access Manager for Web limitationsWhen using an external Kerberos authenticator, the appliance can support Kerberos authentication only. It cannot support NTLM authentication.limitationsoverviewThe Windows NTLM implementation requires that the same connection is used during the multiple stages of the authentication process. WebSEAL cannot always provide the same connection for use throughout the authentication process. Therefore, you cannot use a server that supports only NTLM authentication as the Kerberos Authenticator. You must use a server that supports Kerberos authentication as the Kerberos Authenticator. Microsoft Internet Information Services (IIS) uses NTLM authentication by default. Kerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance.

Limitations

When using an external Kerberos authenticator, the appliance can support Kerberos authentication only. It cannot support NTLM authentication.

The Windows NTLM implementation requires that the same connection is used during the multiple stages of the authentication process. WebSEAL cannot always provide the same connection for use throughout the authentication process.

Therefore, you cannot use a server that supports only NTLM authentication as the Kerberos Authenticator. You must use a server that supports Kerberos authentication as the Kerberos Authenticator.

Note: Microsoft Internet Information Services (IIS) uses NTLM authentication by default.

Parent topic: Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-onWindows desktop single sign-onWindows desktop single sign-on in IBM Security Access Manager for WebThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. Windowssingle signonoverviewsingle sign-onWindows desktopAuthentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsBasic authenticationForms authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. LTPA authenticationOAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.Windows desktop single sign-on conceptsConfigure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.Configuration notes for a load balancer environmentThe following notes address the configuration of Windows desktop single sign-on using SPNEGO in an environment with multiple WebSEAL servers operating behind a load balancer.

Windows desktop single sign-on

This chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins.

Windows desktop single sign-on concepts

Configure Windows desktop single sign-on
There are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Configuration notes for a load balancer environment
The following notes address the configuration of Windows desktop single sign-on using SPNEGO in an environment with multiple WebSEAL servers operating behind a load balancer.

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

LTPA authentication

OAuth Authentication

Related reference:

Authentication terminology

Logout and password change operations

Windows desktop single sign-on conceptsWindows desktop single sign-on conceptsWindows desktop single sign-on conceptsIBM Security Access Manager for WebWindows desktopsingle sign-onconceptssingle sign-onconceptsWindows desktopThis section discusses the following topics:Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.Configuration notes for a load balancer environmentThe following notes address the configuration of Windows desktop single sign-on using SPNEGO in an environment with multiple WebSEAL servers operating behind a load balancer.SPNEGO protocol and Kerberos authenticationMicrosoft provides an authentication solution so that Windows clients can use Microsoft Internet Explorer to access resources on Microsoft Internet Information Servers (IIS) without reauthenticating. User registry and platform support for SPNEGOSPNEGO compatibility with other authentication methodsWebSEAL support for Kerberos authentication is compatible with several WebSEAL authentication methods.Mapping of user names from multi-domain Active Directory registriesBy default, when WebSEAL is mapping user names to certain user registries, it truncates the user names that are provided by Kerberos authentication. Using truncated user names can cause name resolution conflicts if the same name is in multiple domains. However, you can control whether WebSEAL truncates the user name.Multiple Active Directory domain supportActive Directory uses domains and forests to represent the logical structure of the directory hierarchy. Domains are used to manage the various populations of users, computers, and network resources in your enterprise. The forest represents the security boundary for Active Directory. Kerberos authentication limitationsSome WebSEAL features are not supported with Kerberos authentication.

Windows desktop single sign-on concepts

This section discusses the following topics:

SPNEGO protocol and Kerberos authentication
Microsoft provides an authentication solution so that Windows clients can use Microsoft Internet Explorer to access resources on Microsoft Internet Information Servers (IIS) without reauthenticating.

User registry and platform support for SPNEGO

SPNEGO compatibility with other authentication methods
WebSEAL support for Kerberos authentication is compatible with several WebSEAL authentication methods.

Mapping of user names from multi-domain Active Directory registries
By default, when WebSEAL is mapping user names to certain user registries, it truncates the user names that are provided by Kerberos authentication. Using truncated user names can cause name resolution conflicts if the same name is in multiple domains. However, you can control whether WebSEAL truncates the user name.

Multiple Active Directory domain support
Active Directory uses domains and forests to represent the logical structure of the directory hierarchy. Domains are used to manage the various populations of users, computers, and network resources in your enterprise. The forest represents the security boundary for Active Directory.

Kerberos authentication limitations
Some WebSEAL features are not supported with Kerberos authentication.

Parent topic: Windows desktop single sign-on

Related concepts:

Configure Windows desktop single sign-on

Related reference:

Configuration notes for a load balancer environment

SPNEGO protocol and Kerberos authenticationSPNEGO protocol and Kerberos authenticationSPNEGO protocol and Kerberos authentication in IBM Security Access Manager for WebMicrosoft provides an authentication solution so that Windows clients can use Microsoft Internet Explorer to access resources on Microsoft Internet Information Servers (IIS) without reauthenticating. SPNEGOprotocolKerberosauthenticationSPNEGO protocolThis single sign-on solution relies on proprietary Microsoft HTTP authentication mechanisms. IBM Security Access Manager WebSEAL provides an equivalent authentication solution that enables Internet Explorer clients to access WebSEAL servers without reauthenticating.Users with an Internet Explorer browser can access resources that are protected by Security Access Manager without reentering their user name and password. The user must log in only once to the Windows domain, as is typically done when a user logs in to Windows on a desktop workstation.WebSEAL supplies an implementation of the same HTTP authentication method that is used by Microsoft. This implementation involves two components:Simple and Protected GSS-API Negotiation Mechanism (SPNEGO)Kerberos authenticationThe SPNEGO protocol enables WebSEAL to negotiate with the browser to establish the authentication mechanism to use. The browser supplies Kerberos authentication information. WebSEAL knows how to use the user's Kerberos authentication information when it processes a user request to access resources protected by Security Access Manager.On WebSEAL, this implementation is called Windows desktop single sign-on. Deployment of this single sign-on solution requires enabling and configuring the SPNEGO protocol on the WebSEAL server. In addition, the WebSEAL server must have connectivity to an Active Directory domain controller. The Active Directory domain controller must act as a Kerberos Key Distribution Center (KDC). WebSEAL servers must use the Active Directory domain controller as their Kerberos KDC. The WebSEAL configuration steps vary depending on the operating system platform and type of Security Access Manager user registry.Use of SPNEGO requires that a time synchronization service is deployed across the Active Directory server, the WebSEAL server, and any clients (browsers) that use SPNEGO to authenticate.WebSEAL and IIS handle session management differently. IIS maintains session state with clients by using the SPNEGO protocol to reauthenticate each new TCP connection. SPNEGO and Kerberos are both designed for secure authentication over insecure networks. In other words, they are supposed to provide for secure authentication even when using an insecure transport such as HTTP.The IIS method of maintaining session state can potentially have an adverse effect on performance. WebSEAL avoids this problem by using different session state methods. The WebSEAL session state methods are based on a security model that expects WebSEAL to be deployed either over a secure network or using a secure transport such as SSL. WebSEAL optimizes performance by maintaining state using SSL session IDs or HTTP cookies. Also, WebSEAL provides a scalable, secure environment by supporting junctions between WebSEAL and back-end servers. Therefore, single sign-on solutions using SPNEGO to WebSEAL must be deployed only over a secure network or over a secure transport such as SSL.Windows desktop single sign-on concepts

SPNEGO protocol and Kerberos authentication

Microsoft provides an authentication solution so that Windows clients can use Microsoft Internet Explorer to access resources on Microsoft Internet Information Servers (IIS) without reauthenticating.

This single sign-on solution relies on proprietary Microsoft HTTP authentication mechanisms. IBM® Security Access Manager WebSEAL provides an equivalent authentication solution that enables Internet Explorer clients to access WebSEAL servers without reauthenticating.

Users with an Internet Explorer browser can access resources that are protected by Security Access Manager without reentering their user name and password. The user must log in only once to the Windows domain, as is typically done when a user logs in to Windows on a desktop workstation.

WebSEAL supplies an implementation of the same HTTP authentication method that is used by Microsoft. This implementation involves two components:

Simple and Protected GSS-API Negotiation Mechanism (SPNEGO)

Kerberos authentication

The SPNEGO protocol enables WebSEAL to negotiate with the browser to establish the authentication mechanism to use. The browser supplies Kerberos authentication information. WebSEAL knows how to use the user's Kerberos authentication information when it processes a user request to access resources protected by Security Access Manager.

On WebSEAL, this implementation is called Windows desktop single sign-on.

Deployment of this single sign-on solution requires enabling and configuring the SPNEGO protocol on the WebSEAL server. In addition, the WebSEAL server must have connectivity to an Active Directory domain controller. The Active Directory domain controller must act as a Kerberos Key Distribution Center (KDC). WebSEAL servers must use the Active Directory domain controller as their Kerberos KDC.

The WebSEAL configuration steps vary depending on the operating system platform and type of Security Access Manager user registry.

Note: Use of SPNEGO requires that a time synchronization service is deployed across the Active Directory server, the WebSEAL server, and any clients (browsers) that use SPNEGO to authenticate.

WebSEAL and IIS handle session management differently. IIS maintains session state with clients by using the SPNEGO protocol to reauthenticate each new TCP connection. SPNEGO and Kerberos are both designed for secure authentication over insecure networks. In other words, they are supposed to provide for secure authentication even when using an insecure transport such as HTTP.

The IIS method of maintaining session state can potentially have an adverse effect on performance. WebSEAL avoids this problem by using different session state methods. The WebSEAL session state methods are based on a security model that expects WebSEAL to be deployed either over a secure network or using a secure transport such as SSL. WebSEAL optimizes performance by maintaining state using SSL session IDs or HTTP cookies. Also, WebSEAL provides a scalable, secure environment by supporting junctions between WebSEAL and back-end servers. Therefore, single sign-on solutions using SPNEGO to WebSEAL must be deployed only over a secure network or over a secure transport such as SSL.

Parent topic: Windows desktop single sign-on concepts

User registry and platform support for SPNEGOUser registry and platform support for SPNEGOSPNEGOsupported platformsuser registryuser registriesSPNEGOWebSEAL SPNEGO support provides single sign-on from Internet Explorer on Windows client workstations that are configured into an Active Directory domain.When Active Directory is not the Security Access Manager user registry, users must be replicated between the client Active Directory registry and the Security Access Manager user registry.Kerberos authentication is only possible with browsers and platforms that support the SPNEGO protocol. Client computers and browsers must be properly configured to enable Kerberos authentication. SPNEGO single sign-on to WebSEAL functions successfully with Firefox and Internet Explorer browsers. For additional configuration instructions, see the appropriate browser documentation or contact the support organization for the browser software.Internet Explorer must be configured to participate in the Windows desktop single sign-on solution.Windows desktop single sign-on concepts

User registry and platform support for SPNEGO

WebSEAL SPNEGO support provides single sign-on from Internet Explorer on Windows client workstations that are configured into an Active Directory domain.

When Active Directory is not the Security Access Manager user registry, users must be replicated between the client Active Directory registry and the Security Access Manager user registry.

Kerberos authentication is only possible with browsers and platforms that support the SPNEGO protocol. Client computers and browsers must be properly configured to enable Kerberos authentication. SPNEGO single sign-on to WebSEAL functions successfully with Firefox and Internet Explorer browsers. For additional configuration instructions, see the appropriate browser documentation or contact the support organization for the browser software.

Internet Explorer must be configured to participate in the Windows desktop single sign-on solution.

Parent topic: Windows desktop single sign-on concepts

SPNEGO compatibility with other authentication methodsSPNEGO compatibility with other authentication methodsWebSEAL support for Kerberos authentication is compatible with several WebSEAL authentication methods.SPNEGOauthentication compatibilityauthentication methodsSPNEGO compatibilityThe following WebSEAL authentication methods are compatible: Basic authenticationForms authenticationHTTP header authenticationLTPA authenticationFailover authentication The failover cookie failover mechanism supports SPNEGO authenticated users.Cross domain single sign-onSSL certificate authenticationExternal authentication interfaceWhen SPNEGO is configured with another authentication method, WebSEAL simultaneously sends both an SPNEGO challenge and an HTML form login to the browser. Browsers that support SPNEGO respond with Kerberos authentication. Browsers that do not support SPNEGO display the login form.Compatibility between Kerberos authentication and WebSEAL e-community single sign-on is limited. A WebSEAL server can be an e-community master authentication server (MAS) and support SPNEGO. However, a WebSEAL server cannot be an e-community subordinate and also support SPNEGO. WebSEAL authentication strength policy (step-up authentication) from Kerberos authentication to other authentication methods is supported.When Kerberos authentication is enabled, only the following methods of maintaining session state are supported: SSL session IDsHTTP cookiesHTTP header session keysKerberos authentication is compatible with the automatic tag-value retrieval support provided by the Security Access Manager entitlements service. Therefore, it is possible to add extended attributes to a user's credential after the user has authenticated with SPNEGO.Windows desktop single sign-on concepts

SPNEGO compatibility with other authentication methods

WebSEAL support for Kerberos authentication is compatible with several WebSEAL authentication methods.

The following WebSEAL authentication methods are compatible:

Basic authentication

Forms authentication

HTTP header authentication

LTPA authentication

Failover authentication

The failover cookie failover mechanism supports SPNEGO authenticated users.

Cross domain single sign-on

SSL certificate authentication

External authentication interface

When SPNEGO is configured with another authentication method, WebSEAL simultaneously sends both an SPNEGO challenge and an HTML form login to the browser. Browsers that support SPNEGO respond with Kerberos authentication. Browsers that do not support SPNEGO display the login form.

Compatibility between Kerberos authentication and WebSEAL e-community single sign-on is limited. A WebSEAL server can be an e-community master authentication server (MAS) and support SPNEGO. However, a WebSEAL server cannot be an e-community subordinate and also support SPNEGO.

WebSEAL authentication strength policy (step-up authentication) from Kerberos authentication to other authentication methods is supported.

When Kerberos authentication is enabled, only the following methods of maintaining session state are supported:

SSL session IDs

HTTP cookies

HTTP header session keys

Kerberos authentication is compatible with the automatic tag-value retrieval support provided by the Security Access Manager entitlements service. Therefore, it is possible to add extended attributes to a user's credential after the user has authenticated with SPNEGO.

Parent topic: Windows desktop single sign-on concepts

Mapping of user names from multi-domain Active Directory registriesMapping of user names from multi-domain Active Directory registriesBy default, when WebSEAL is mapping user names to certain user registries, it truncates the user names that are provided by Kerberos authentication. Using truncated user names can cause name resolution conflicts if the same name is in multiple domains. However, you can control whether WebSEAL truncates the user name.use-domain-qualified-name stanza entryuser namesmappingmulti-domain Active Directory registriesWindows desktop single sign-on conceptsUser name formats from differing user registriesWebSEAL maps the user name that the Kerberos authentication process provides to the Security Access Manager user registry. This mapping process depends on the type of user registry.Setup for user name truncation handlingYou can use the Use Domain Qualified Name check box in the Authentication tab of the Reverse Proxy management page to control whether or not WebSEAL truncates the user name received from Kerberos authentication.

Mapping of user names from multi-domain Active Directory registries

By default, when WebSEAL is mapping user names to certain user registries, it truncates the user names that are provided by Kerberos authentication. Using truncated user names can cause name resolution conflicts if the same name is in multiple domains. However, you can control whether WebSEAL truncates the user name.

User name formats from differing user registries
WebSEAL maps the user name that the Kerberos authentication process provides to the Security Access Manager user registry. This mapping process depends on the type of user registry.

Setup for user name truncation handling
You can use the Use Domain Qualified Name check box in the Authentication tab of the Reverse Proxy management page to control whether or not WebSEAL truncates the user name received from Kerberos authentication.

Parent topic: Windows desktop single sign-on concepts

User name formats from differing user registriesUser name formats from differing user registriesUser name formats from differing user registries in IBM Security Access Manager for WebWebSEAL maps the user name that the Kerberos authentication process provides to the Security Access Manager user registry. This mapping process depends on the type of user registry.user registriesuser name formatsSPNEGOauthentication processKerberos authentication provides Security Access Manager with a user name in the following form:user@domain.comWhen multiple-domain Active Directory is used as the Security Access Manager user registry, the user name listed in the Active Directory registry uses the same format as the user name provided by the Kerberos authentication process.If the Security Access Manager user registry is not Active Directory, WebSEAL, by default, truncates the user name that is provided by Kerberos authentication. WebSEAL maps this truncated user name to the user registry. For example, the following format is received from Kerberos authentication:user@domain.comWebSEAL truncates this name by removing the domain designation and leaving only the short-name:userWebSEAL creates a credential for that user based on the short-name.This mapping from the full Active Directory user name to the short-name of the user is not always appropriate and can cause conflicts when resolving user names. For example, consider the scenario of two users with the same short-name in different Active Directory domains. When WebSEAL truncates the user names for each of these users, the users are mapped incorrectly to the same Security Access Manager user. When truncation does not occur, the users are correctly mapped to unique Security Access Manager users (for example user@domainA.com and user@domainB.com). Mapping of user names from multi-domain Active Directory registriesBy default, when WebSEAL is mapping user names to certain user registries, it truncates the user names that are provided by Kerberos authentication. Using truncated user names can cause name resolution conflicts if the same name is in multiple domains. However, you can control whether WebSEAL truncates the user name.

User name formats from differing user registries

WebSEAL maps the user name that the Kerberos authentication process provides to the Security Access Manager user registry. This mapping process depends on the type of user registry.

Kerberos authentication provides Security Access Manager with a user name in the following form:

user@domain.com

When multiple-domain Active Directory is used as the Security Access Manager user registry, the user name listed in the Active Directory registry uses the same format as the user name provided by the Kerberos authentication process.

If the Security Access Manager user registry is not Active Directory, WebSEAL, by default, truncates the user name that is provided by Kerberos authentication. WebSEAL maps this truncated user name to the user registry.

For example, the following format is received from Kerberos authentication:

user@domain.com

WebSEAL truncates this name by removing the domain designation and leaving only the short-name:

user

WebSEAL creates a credential for that user based on the short-name.

This mapping from the full Active Directory user name to the short-name of the user is not always appropriate and can cause conflicts when resolving user names. For example, consider the scenario of two users with the same short-name in different Active Directory domains. When WebSEAL truncates the user names for each of these users, the users are mapped incorrectly to the same Security Access Manager user. When truncation does not occur, the users are correctly mapped to unique Security Access Manager users (for example user@domainA.com and user@domainB.com).

Parent topic: Mapping of user names from multi-domain Active Directory registries

Setup for user name truncation handlingSetup for user name truncation handlingSetup for user name truncation handling in WebSEALYou can use the Use Domain Qualified Name check box in the Authentication tab of the Reverse Proxy management page to control whether or not WebSEAL truncates the user name received from Kerberos authentication. use-domain-qualified-name stanzaWebSEAL configuration[spnego] stanzauser namestruncation handling setupThis configuration option is appropriate when WebSEAL receives user names from Kerberos authentication (in a multiple-domain Active directory environment) that must be mapped to a default Security Access Manager user registry that is not Active Directory. A setting of yes prevents WebSEAL from removing the domain from the SPNEGO user name format. In this case, WebSEAL uses the fully-qualified user name to build the credential (in the non-Active Directory registry) for the user.In the following example, Kerberos authentication provides the following user ID: user@example.comIf use-domain-qualified-name = no, the Security Access Manager user ID becomes:userIf use-domain-qualified-name = yes, the Security Access Manager user ID becomes:user@example.comThe use-domain-qualified-name stanza entry has no effect if multiple-domain Active Directory is used as the Security Access Manager user registry. In this case, the domain name is always included as part of the Security Access Manager user name.You can use the Authentication tab in the LMI to configure the main settings for Kerberos Authentication on the appliance. For more information, see the Kerberos Authentication details in the "Configuration entry and file management" section of the Administering topics in the Knowledge Center.Mapping of user names from multi-domain Active Directory registriesBy default, when WebSEAL is mapping user names to certain user registries, it truncates the user names that are provided by Kerberos authentication. Using truncated user names can cause name resolution conflicts if the same name is in multiple domains. However, you can control whether WebSEAL truncates the user name.

Setup for user name truncation handling

You can use the Use Domain Qualified Name check box in the Authentication tab of the Reverse Proxy management page to control whether or not WebSEAL truncates the user name received from Kerberos authentication.

This configuration option is appropriate when WebSEAL receives user names from Kerberos authentication (in a multiple-domain Active directory environment) that must be mapped to a default Security Access Manager user registry that is not Active Directory. A setting of yes prevents WebSEAL from removing the domain from the SPNEGO user name format.

In this case, WebSEAL uses the fully-qualified user name to build the credential (in the non-Active Directory registry) for the user.

In the following example, Kerberos authentication provides the following user ID:

user@example.com

If use-domain-qualified-name = no, the Security Access Manager user ID becomes:

user

If use-domain-qualified-name = yes, the Security Access Manager user ID becomes:

user@example.com

The use-domain-qualified-name stanza entry has no effect if multiple-domain Active Directory is used as the Security Access Manager user registry. In this case, the domain name is always included as part of the Security Access Manager user name.

Note: You can use the Authentication tab in the LMI to configure the main settings for Kerberos Authentication on the appliance. For more information, see the Kerberos Authentication details in the "Configuration entry and file management" section of the Administering topics in the Knowledge Center.

Parent topic: Mapping of user names from multi-domain Active Directory registries

Multiple Active Directory domain supportMultiple Active Directory domain supportMultiple Active Directory domain support in IBM Security Access Manager for WebActive Directory uses domains and forests to represent the logical structure of the directory hierarchy. Domains are used to manage the various populations of users, computers, and network resources in your enterprise. The forest represents the security boundary for Active Directory. Multiple Active Directory domain supportdomain supportMultiple Active DirectoryKerberos authentication for users from multiple Active Directory domains is supported by Security Access Manager only if an appropriate trust relationship between the domains is established. This trust exists automatically for domains that are part of the same Active Directory forest. For Kerberos authentication to work across multiple forests, a forest trust relationship must be established.For details on establishing a trust relationship between multiple Active Directory domains, refer to the appropriate Active Directory documentation from Microsoft.Windows desktop single sign-on concepts

Multiple Active Directory domain support

Active Directory uses domains and forests to represent the logical structure of the directory hierarchy. Domains are used to manage the various populations of users, computers, and network resources in your enterprise. The forest represents the security boundary for Active Directory.

Kerberos authentication for users from multiple Active Directory domains is supported by Security Access Manager only if an appropriate trust relationship between the domains is established. This trust exists automatically for domains that are part of the same Active Directory forest. For Kerberos authentication to work across multiple forests, a forest trust relationship must be established.

For details on establishing a trust relationship between multiple Active Directory domains, refer to the appropriate Active Directory documentation from Microsoft.

Parent topic: Windows desktop single sign-on concepts

Kerberos authentication limitationsKerberos authentication limitationsSome WebSEAL features are not supported with Kerberos authentication.SPNEGOauthentication limitsKerberosauthenticationlimitationsIf you are using Kerberos authentication, the following limitations apply: POP or session-timer-based reauthentication of Kerberos authenticated clients is not supported.Using pkmspasswd to change a password is not supported.Clients who are currently authenticated with SPNEGO cannot log out of WebSEAL. Clients must log out from the workstation. Clients that access the WebSEAL pkms command pages, except switch user, receive the PKMS help page.Reauthentication when the inactive session timer expires is not supported for SPNEGO clients.The user cache entry is deleted. Information in the header received from the SPNEGO client is used to reauthenticate. The client is not required to log in again, but the client receives a new session cache entry.WebSEAL does not support reauthentication when a user accesses an object with a reauthentication policy attached. In this case, access is denied and the user receives a message that states reauthentication is required.Microsoft NT LAN Manager (NTLM) authentication is not supported.Using alternate user principal name (UPN) format is not supported.The default format for the userPrincipalName attribute in Active Directory is user_shortname@domain, where domain is the Active Directory domain in which the user was created. For example, a user that is created in the Active Directory domain child.domain.com might have a UPN of user@child.domain.com. However, a user can be created with an alternate UPN format, also called e-mail format, where the domain need not be the actual Active Directory domain name. For example, the user user@domain.com can be created in the child.domain.com Active Directory domain. Security Access Manager Kerberos authentication only supports the default format of the userPrincipalName attribute as the Active Directory user identity. The use of the alternate UPN format is not supported if you are using Kerberos authentication. Windows desktop single sign-on concepts

Kerberos authentication limitations

Some WebSEAL features are not supported with Kerberos authentication.

If you are using Kerberos authentication, the following limitations apply:

POP or session-timer-based reauthentication of Kerberos authenticated clients is not supported.

Using pkmspasswd to change a password is not supported.

Clients who are currently authenticated with SPNEGO cannot log out of WebSEAL. Clients must log out from the workstation. Clients that access the WebSEAL pkms command pages, except switch user, receive the PKMS help page.

Reauthentication when the inactive session timer expires is not supported for SPNEGO clients.

The user cache entry is deleted. Information in the header received from the SPNEGO client is used to reauthenticate. The client is not required to log in again, but the client receives a new session cache entry.

WebSEAL does not support reauthentication when a user accesses an object with a reauthentication policy attached.

In this case, access is denied and the user receives a message that states reauthentication is required.

Microsoft NT LAN Manager (NTLM) authentication is not supported.

Using alternate user principal name (UPN) format is not supported.

The default format for the userPrincipalName attribute in Active Directory is user_shortname@domain, where domain is the Active Directory domain in which the user was created.

For example, a user that is created in the Active Directory domain child.domain.com might have a UPN of user@child.domain.com. However, a user can be created with an alternate UPN format, also called e-mail format, where the domain need not be the actual Active Directory domain name. For example, the user user@domain.com can be created in the child.domain.com Active Directory domain.

Security Access Manager Kerberos authentication only supports the default format of the userPrincipalName attribute as the Active Directory user identity. The use of the alternate UPN format is not supported if you are using Kerberos authentication.

Parent topic: Windows desktop single sign-on concepts

Configure Windows desktop single sign-onConfigure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.SPNEGOconfiguration steps (UNIX)Windowssingle sign-onconfiguration stepsUNIXTo configure WebSEAL on the appliance for SPNEGO authentication, complete each of the following tasks:For troubleshooting information, see Troubleshooting for Windows desktop single sign-on.Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. Windows desktop single sign-on conceptsConfiguration notes for a load balancer environmentThe following notes address the configuration of Windows desktop single sign-on using SPNEGO in an environment with multiple WebSEAL servers operating behind a load balancer.Configuring the embedded Kerberos clientYou must configure the Kerberos client that is embedded in Security Access Manager. Creating an identity for WebSEAL in an Active Directory domainTo participate in a Kerberos exchange with a browser, a WebSEAL server needs an identity in the Active Directory Kerberos domain. Mapping a Kerberos principal to an Active Directory userYou must map a Kerberos principal to the Active Directory user that represents the WebSEAL instance.Verifying the authentication of the web server principalVerify the authentication of the web server principal to the KDC.Verifying WebSEAL authentication with the keytab fileEnsure that WebSEAL can use the generated keytab file to authenticate to the KDC.Adding service name and keytab file entriesYou must configure the Kerberos service name and the name of the keytab file.Enabling SPNEGO for WebSEALYou must configure WebSEAL to enable SPNEGO.Removing cached tokens from the Windows clientFor SPNEGO to work correctly, you must remove any cached Kerberos tokens from the Windows client. When a client contains cached Active Directory credentials, SPNEGO might not work correctly on the client until it obtains the new credentials. Configuring the Internet Explorer clientIf you use Internet Explorer, you must configure the browser to use the SPNEGO protocol.Troubleshooting for Windows desktop single sign-on

Configure Windows desktop single sign-on

There are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

To configure WebSEAL on the appliance for SPNEGO authentication, complete each of the following tasks:

For troubleshooting information, see Troubleshooting for Windows desktop single sign-on.

Configuring the embedded Kerberos client
You must configure the Kerberos client that is embedded in Security Access Manager.

Creating an identity for WebSEAL in an Active Directory domain
To participate in a Kerberos exchange with a browser, a WebSEAL server needs an identity in the Active Directory Kerberos domain.

Mapping a Kerberos principal to an Active Directory user
You must map a Kerberos principal to the Active Directory user that represents the WebSEAL instance.

Verifying the authentication of the web server principal
Verify the authentication of the web server principal to the KDC.

Verifying WebSEAL authentication with the keytab file
Ensure that WebSEAL can use the generated keytab file to authenticate to the KDC.

Adding service name and keytab file entries
You must configure the Kerberos service name and the name of the keytab file.

Enabling SPNEGO for WebSEAL
You must configure WebSEAL to enable SPNEGO.

Removing cached tokens from the Windows client
For SPNEGO to work correctly, you must remove any cached Kerberos tokens from the Windows client. When a client contains cached Active Directory credentials, SPNEGO might not work correctly on the client until it obtains the new credentials.

Configuring the Internet Explorer client
If you use Internet Explorer, you must configure the browser to use the SPNEGO protocol.

Troubleshooting for Windows desktop single sign-on

Parent topic: Windows desktop single sign-on

Related concepts:

Windows desktop single sign-on concepts

Related reference:

Configuration notes for a load balancer environment

Configuring the embedded Kerberos clientConfigure the embedded Kerberos clientYou must configure the Kerberos client that is embedded in Security Access Manager. mkkrb5clntKerberosclientembeddedconfigurationTo complete this configuration, modify the Kerberos configuration in the LMI.For more details, see "Managing Kerberos configuration" in the Administering section of the IBM Knowledge Center. Open the Kerberos Configuration management page in the LMI. From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration.Open the Defaults tab to configure the libdefaults section of the corresponding Kerberos configuration file.Set the following entries:default_realmSpecifies the Active Directory domain name in uppercase.default_tkt_enctypesSpecifies the cipher suite names supported by the Active Directory Server that you are using to encrypt the WebSEAL AD Kerberos user key.default_tgs_enctypesSpecifies the cipher suite names supported by the Active Directory Server that you are using to encrypt the WebSEAL AD Kerberos user key.For example:[libdefaults] default_realm = EXAMPLE.COM default_tkt_enctypes = rc4-hmac default_tgs_enctypes = rc4-hmac Open the Realms tab to configure the realms section of the corresponding Kerberos configuration file.Create a realm entry for the default realm that was specified as the default_realm in the Defaults tab. Set the following entries:kdcSpecify the fully qualified host name of the Active Directory Key Distribution Center (KDC), which is the host name of the Domain Controller. For example, mykdc.example.com:88.default_domainSpecify the local DNS domain of the server that runs WebSEAL. This value is the domain that client browsers use to access WebSEAL for Windows single sign-on. For example, example.com.An example for the default realm of EXAMPLE.COM is: [realms] EXAMPLE.COM = { kdc = mykdc.example.com:88 default_domain = example.com }Open the Domains tab to configure the domain_realm section of the corresponding Kerberos configuration file.Configure entries to map local domains and domain names to the Active Directory Kerberos realm. Use the WebSEAL host names specified in step 5.For example: [domain_realm] www.examplefancy.com = EXAMPLE.COM .examplefancy.com = EXAMPLE.COMTo use SPNEGO as the authentication type at a junction level, create a [server:jct_id] stanza in the WebSEAL configuration file and add an auth-challenge-type entry with a value of spnego. where:jct_idThe junction point for a standard junction, including the leading "/" character, or the virtual host label for a virtual host junction.For example:[server:/test-jct] auth-challenge-type = spnegoConfigure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Configuring the embedded Kerberos client

You must configure the Kerberos client that is embedded in Security Access Manager.

About this task

To complete this configuration, modify the Kerberos configuration in the LMI.

Note: For more details, see "Managing Kerberos configuration" in the Administering section of the IBM Knowledge Center.

Procedure

Open the Kerberos Configuration management page in the LMI. From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration.

Open the Defaults tab to configure the libdefaults section of the corresponding Kerberos configuration file.

Set the following entries:

default_realm

Specifies the Active Directory domain name in uppercase.

default_tkt_enctypes

Specifies the cipher suite names supported by the Active Directory Server that you are using to encrypt the WebSEAL AD Kerberos user key.

default_tgs_enctypes

Specifies the cipher suite names supported by the Active Directory Server that you are using to encrypt the WebSEAL AD Kerberos user key.

For example:

[libdefaults]
default_realm = EXAMPLE.COM
default_tkt_enctypes = rc4-hmac
default_tgs_enctypes = rc4-hmac

Open the Realms tab to configure the realms section of the corresponding Kerberos configuration file.

Create a realm entry for the default realm that was specified as the default_realm in the Defaults tab. Set the following entries:

kdc

Specify the fully qualified host name of the Active Directory Key Distribution Center (KDC), which is the host name of the Domain Controller. For example, mykdc.example.com:88.

default_domain

Specify the local DNS domain of the server that runs WebSEAL. This value is the domain that client browsers use to access WebSEAL for Windows single sign-on. For example, example.com.

An example for the default realm of EXAMPLE.COM is:

[realms]
EXAMPLE.COM = {
        kdc = mykdc.example.com:88
        default_domain = example.com
}

Open the Domains tab to configure the domain_realm section of the corresponding Kerberos configuration file.

Configure entries to map local domains and domain names to the Active Directory Kerberos realm. Use the WebSEAL host names specified in step 5.

For example:

[domain_realm]
www.examplefancy.com = EXAMPLE.COM
 .examplefancy.com = EXAMPLE.COM

Optional: To use SPNEGO as the authentication type at a junction level, create a [server:jct_id] stanza in the WebSEAL configuration file and add an auth-challenge-type entry with a value of spnego.

where:

jct_id

The junction point for a standard junction, including the leading "/" character, or the virtual host label for a virtual host junction.

For example:

[server:/test-jct]
auth-challenge-type = spnego

Parent topic: Configure Windows desktop single sign-on

Creating an identity for WebSEAL in an Active Directory domainCreate an identity for WebSEAL in an Active Directory domainCreating an identity for WebSEAL in an Active Directory domainTo participate in a Kerberos exchange with a browser, a WebSEAL server needs an identity in the Active Directory Kerberos domain. WebSEALidentity in an Active Directory domainActive DirectoryWebSEAL identity domainCreating the identity, and copying the keytab to the WebSEAL server on UNIX, provides a similar function as joining a Windows system to an Active Directory domain. The browser can then obtain a Kerberos ticket from the Active Directory domain controller and use the ticket to access the WebSEAL server.These instructions assume that the user name is the shortened DNS name that clients use to contact the WebSEAL server. For example, if clients contact the WebSEAL server at https://diamond.example.com, the WebSEAL server principal in Active Directory would have a user name of diamond. However, any identifying name can be used. See the appropriate Microsoft documentation for instructions on how to add a WebSEAL server host identity into an Active Directory domain.Follow these conditions:Match the user name with the host name that clients use to contact the WebSEAL server. Do not use the full domain name. For example, for the website, diamond.example.com, create a user, diamond. Do not require the user to change password at next login.Do not set the password to expire.Configure DNS properly for the host name that clients use to contact the WebSEAL server. To confirm the configuration is correct, run forward and reverse nslookup for that host name on each of the following systems: the client, the WebSEAL server, and the Active Directory domain controller.The account must not be set to use DES ciphers.If you intend to use AES encryption for tickets and keys that are placed in the keytab, modify the following user account properties to enable it:This account supports Kerberos AES 128 bit encryptionThis account supports Kerberos AES 256 bit encryption Multiple WebSEAL instances are supported by SPNEGO when each WebSEAL server has a unique IP address and host name. Multiple instances are not supported when the instances listen on different ports but share IP addresses.This step is only relevant if you use multiple WebSEAL instances or virtual host junctions. To configure SPNEGO for multiple WebSEAL servers on the same system, you must create a separate user in Active Directory for each instance. Similarly, if you use virtual host junctions, create a separate user for each virtual host junction.For example, if the WebSEAL server is serving requests for the host names www.example.com, sales.example.com, and eng.example.com, you must create three users in Active Directory, one for each DNS name. Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Creating an identity for WebSEAL in an Active Directory domain

To participate in a Kerberos exchange with a browser, a WebSEAL server needs an identity in the Active Directory Kerberos domain.

About this task

Creating the identity, and copying the keytab to the WebSEAL server on UNIX, provides a similar function as joining a Windows system to an Active Directory domain. The browser can then obtain a Kerberos ticket from the Active Directory domain controller and use the ticket to access the WebSEAL server.

These instructions assume that the user name is the shortened DNS name that clients use to contact the WebSEAL server. For example, if clients contact the WebSEAL server at https://diamond.example.com, the WebSEAL server principal in Active Directory would have a user name of diamond. However, any identifying name can be used.

Procedure

See the appropriate Microsoft documentation for instructions on how to add a WebSEAL server host identity into an Active Directory domain.

Follow these conditions:

Match the user name with the host name that clients use to contact the WebSEAL server. Do not use the full domain name. For example, for the website, diamond.example.com, create a user, diamond.

Do not require the user to change password at next login.

Do not set the password to expire.

Configure DNS properly for the host name that clients use to contact the WebSEAL server.

To confirm the configuration is correct, run forward and reverse nslookup for that host name on each of the following systems: the client, the WebSEAL server, and the Active Directory domain controller.

The account must not be set to use DES ciphers.

If you intend to use AES encryption for tickets and keys that are placed in the keytab, modify the following user account properties to enable it:

This account supports Kerberos AES 128 bit encryption

This account supports Kerberos AES 256 bit encryption

Multiple WebSEAL instances are supported by SPNEGO when each WebSEAL server has a unique IP address and host name. Multiple instances are not supported when the instances listen on different ports but share IP addresses.

Optional: This step is only relevant if you use multiple WebSEAL instances or virtual host junctions. To configure SPNEGO for multiple WebSEAL servers on the same system, you must create a separate user in Active Directory for each instance. Similarly, if you use virtual host junctions, create a separate user for each virtual host junction.

For example, if the WebSEAL server is serving requests for the host names www.example.com, sales.example.com, and eng.example.com, you must create three users in Active Directory, one for each DNS name.

Parent topic: Configure Windows desktop single sign-on

Mapping a Kerberos principal to an Active Directory userMap a Kerberos principal to an Active Directory userYou must map a Kerberos principal to the Active Directory user that represents the WebSEAL instance.ktpassActive DirectoryKerberos principalKerberosprincipalThis mapping requires the Windows ktpass utility. The ktpass utility might not be loaded on the Windows system by default. You can obtain the utility from the Windows Support Tools package.On a Windows client system, the browser makes a URL request, so the Kerberos client makes a request to the KDC in the following format:HTTP/hostname_of_web_site@ACTIVE_DIRECTORY_DOMAIN_NAMEThe domain name is in uppercase.For WebSEAL on UNIX systems, create a keytab file for verifying Kerberos tickets in addition to creating the user. On the Active Directory domain controller, run the ktpass command, entering the following syntax on one line:ktpass -princ hostname_of_web_site@ACTIVE_DIRECTORY_DOMAIN_NAME {-pass your_password | +rndPass} -mapuser WebSEAL_server_instance -out full_path_to_keytab_file -mapOp set -crypto cipher -ptype KRB5_NT_PRINCIPALwhere:hostname_of_web_siteSpecifies the name of the website.ACTIVE_DIRECTORY_DOMAIN_NAMESpecifies the Active Directory domain name in all uppercase. The domain name must map to the Active Directory user that represents the WebSEAL instance, as created in Creating an identity for WebSEAL in an Active Directory domainTo participate in a Kerberos exchange with a browser, a WebSEAL server needs an identity in the Active Directory Kerberos domain. .your_passwordSpecifies a password to set when the -pass parameter is used. The specified password resets the password for the Active Directory user. A highly secure password, such as a randomly generated password, is preferred. If you use a known password, retain it for use in Verifying the authentication of the web server principalVerify the authentication of the web server principal to the KDC. to test your Kerberos configuration. You need this password to test authentication from the Appliance to the Active Directory Key Distribution Center.WebSEAL_server_instanceSpecifies the WebSEAL server instance user identity. The user identity is the Active Directory user that was created in Creating an identity for WebSEAL in an Active Directory domainTo participate in a Kerberos exchange with a browser, a WebSEAL server needs an identity in the Active Directory Kerberos domain. .full_path_to_keytab_fileSpecifies the fully qualified path to the keytab file. The location of the keytab file is arbitrary. cipherSpecifies the cipher to use. Windows Server 2008 R2 and Windows 7 clients have DES ciphers disabled by default. For Windows Server 2003, this restriction leaves RC4-HMAC-NT for the -crypto cipher.For Windows Server 2008 R2, this restriction leaves the following values for -crypto cipher:RC4-HMAC-NTKerberos client cipher rc4-hmac.AES256-SHA1Kerberos client cipher aes256-cts.AES128-SHA1Kerberos client cipher aes128-cts.ALLGenerates keys in the keytab file for all ciphers. Use this value when you require a mix of AES and RC4 clients. The following example command, entered as one line, uses the values that are listed in the included table:ktpass -princ HTTP/diamond.example.com@EXAMPLE.COM +rndPass -mapuser diamond -out C:\diamond_HTTP.keytab -mapOp set -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPALConfiguration settingValueWebSEAL host systemdiamond.example.comUser identity for the WebSEAL instancediamondActive Directory domainEXAMPLE.COMpasswordA random value. The +rndPass argument prevents anyone from knowing the password of the mapuser. If the diamond user password must be known for other purposes, use the -pass option and provide a secure password.Keytab fileC:\diamond_HTTP.keytab-mapOp: Flush other Service Principal Names that are associated with the user and set the one provided by -princsetCipher of the key to store in the keytab fileRC4-HMAC-NT To configure SPNEGO for virtual host junctions, create a separate keytab file for each virtual host. Repeat the ktpass command for each principal in Active Directory. For example, see the following three commands, each one entered as one line:ktpass -princ HTTP/www.example.com@EXAMPLE.COM -pass mypassw0rd -mapuser www -out www_HTTP.keytab -mapOp set -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL ktpass -princ HTTP/sales.example.com@EXAMPLE.COM -pass mypassw0rd -mapuser sales -out sales_HTTP.keytab -mapOp set -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL ktpass -princ HTTP/eng.example.com@EXAMPLE.COM -pass mypassw0rd -mapuser eng -out eng_HTTP.keytab -mapOp set -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPALImport the keytab files on to the appliance. For more information, see "Managing keytab files" in the Administering topics in the Knowledge Center.As a best security practice, delete the keytab files from the Windows client system.To configure SPNEGO for multiple virtual hosts, combine all keytabs into a single file using the Combine function in the Keyfiles tab on the Kerberos Configuration management page in the LMI.You can remove redundant keys from the list of key files as they are no longer required.Kerberos can have alternate names for a particular cipher. For example, arcfour-hmac is an alias for rc4-hmac, the Windows RC4-HMAC-NT cipher.Repeat these steps for each WebSEAL instance.Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Mapping a Kerberos principal to an Active Directory user

You must map a Kerberos principal to the Active Directory user that represents the WebSEAL instance.

Before you begin

This mapping requires the Windows ktpass utility. The ktpass utility might not be loaded on the Windows system by default. You can obtain the utility from the Windows Support Tools package.

About this task

On a Windows client system, the browser makes a URL request, so the Kerberos client makes a request to the KDC in the following format:

HTTP/hostname_of_web_site@ACTIVE_DIRECTORY_DOMAIN_NAME

Note: The domain name is in uppercase.

For WebSEAL on UNIX systems, create a keytab file for verifying Kerberos tickets in addition to creating the user.

Procedure

On the Active Directory domain controller, run the ktpass command, entering the following syntax on one line:

ktpass -princ hostname_of_web_site@ACTIVE_DIRECTORY_DOMAIN_NAME
 {-pass your_password | +rndPass} -mapuser WebSEAL_server_instance
-out full_path_to_keytab_file -mapOp set -crypto cipher -ptype
KRB5_NT_PRINCIPAL

where:

hostname_of_web_site

Specifies the name of the website.

ACTIVE_DIRECTORY_DOMAIN_NAME

Specifies the Active Directory domain name in all uppercase.

The domain name must map to the Active Directory user that represents the WebSEAL instance, as created in Creating an identity for WebSEAL in an Active Directory domain.

your_password

Specifies a password to set when the -pass parameter is used. The specified password resets the password for the Active Directory user. A highly secure password, such as a randomly generated password, is preferred.

If you use a known password, retain it for use in Verifying the authentication of the web server principal to test your Kerberos configuration. You need this password to test authentication from the Appliance to the Active Directory Key Distribution Center.

WebSEAL_server_instance

Specifies the WebSEAL server instance user identity. The user identity is the Active Directory user that was created in Creating an identity for WebSEAL in an Active Directory domain.

full_path_to_keytab_file

Specifies the fully qualified path to the keytab file. The location of the keytab file is arbitrary.

cipher

Specifies the cipher to use.

Note: Windows Server 2008 R2 and Windows 7 clients have DES ciphers disabled by default.

For Windows Server 2003, this restriction leaves RC4-HMAC-NT for the -crypto cipher.

For Windows Server 2008 R2, this restriction leaves the following values for -crypto cipher:

RC4-HMAC-NT

Kerberos client cipher rc4-hmac.

AES256-SHA1

Kerberos client cipher aes256-cts.

AES128-SHA1

Kerberos client cipher aes128-cts.

ALL

Generates keys in the keytab file for all ciphers. Use this value when you require a mix of AES and RC4 clients.

The following example command, entered as one line, uses the values that are listed in the included table:

ktpass -princ HTTP/diamond.example.com@EXAMPLE.COM +rndPass
-mapuser diamond -out C:\diamond_HTTP.keytab -mapOp set
-crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

Configuration setting | Value
WebSEAL host system | diamond.example.com
User identity for the WebSEAL instance | diamond
Active Directory domain | EXAMPLE.COM
password | A random value. The +rndPass argument prevents anyone from knowing the password of the mapuser. If the diamond user password must be known for other purposes, use the -pass option and provide a secure password.
Keytab file | C:\diamond_HTTP.keytab
-mapOp: Flush other Service Principal Names that are associated with the user and set the one provided by -princ | set
Cipher of the key to store in the keytab file | RC4-HMAC-NT

Optional: To configure SPNEGO for virtual host junctions, create a separate keytab file for each virtual host. Repeat the ktpass command for each principal in Active Directory.

For example, see the following three commands, each one entered as one line:

ktpass -princ HTTP/www.example.com@EXAMPLE.COM
-pass mypassw0rd -mapuser www
-out www_HTTP.keytab -mapOp set
-crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

ktpass -princ HTTP/sales.example.com@EXAMPLE.COM
-pass mypassw0rd -mapuser sales
-out sales_HTTP.keytab -mapOp set
-crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

ktpass -princ HTTP/eng.example.com@EXAMPLE.COM
-pass mypassw0rd -mapuser eng
-out eng_HTTP.keytab -mapOp set
-crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL

Import the keytab files on to the appliance. For more information, see "Managing keytab files" in the Administering topics in the Knowledge Center.

As a best security practice, delete the keytab files from the Windows client system.

Optional: To configure SPNEGO for multiple virtual hosts, combine all keytabs into a single file using the Combine function in the Keyfiles tab on the Kerberos Configuration management page in the LMI.

Note:

You can remove redundant keys from the list of key files as they are no longer required.

Kerberos can have alternate names for a particular cipher. For example, arcfour-hmac is an alias for rc4-hmac, the Windows RC4-HMAC-NT cipher.

Repeat these steps for each WebSEAL instance.

Parent topic: Configure Windows desktop single sign-on

Verifying the authentication of the web server principalVerify the authentication of the web server principalVerify the authentication of the web server principal in IBM Security Access Manager for WebVerify the authentication of the web server principal to the KDC.web serversprincipalsauthenticationverificationweb server principalSkip this task if you used the +rndPass option when you generated the keytab files.To open the Kerberos Configuration management page in the LMI, select Secure Web Settings > Global Settings > Kerberos Configuration.Click Test on any of the tabs other than Keyfiles on the Kerberos Configuration management page. This test checks whether the Kerberos principal for the WebSEAL instance can authenticate to the KDC.Check the output message to determine the success of the authentication.If the authentication is successful, a success message is displayed. If the authentication fails, an error message is displayed.Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Verifying the authentication of the web server principal

Verify the authentication of the web server principal to the KDC.

Before you begin

Skip this task if you used the +rndPass option when you generated the keytab files.

Procedure

To open the Kerberos Configuration management page in the LMI, select Secure Web Settings > Global Settings > Kerberos Configuration.

Click Test on any of the tabs other than Keyfiles on the Kerberos Configuration management page. This test checks whether the Kerberos principal for the WebSEAL instance can authenticate to the KDC.

Check the output message to determine the success of the authentication.

If the authentication is successful, a success message is displayed.

If the authentication fails, an error message is displayed.

Parent topic: Configure Windows desktop single sign-on

Verifying WebSEAL authentication with the keytab fileVerify WebSEAL authentication with the keytab fileEnsure that WebSEAL can use the generated keytab file to authenticate to the KDC.am_kinitSPNEGOverify WebSEAL authenticationam_kinitVerify that the WebSEAL server can authenticate with the keytab file that you created in Mapping a Kerberos principal to an Active Directory userYou must map a Kerberos principal to the Active Directory user that represents the WebSEAL instance.. To open the Kerberos Configuration management page in the LMI, select Secure Web Settings > Global Settings > Kerberos Configuration.Click Test on the Keyfiles tab on the Kerberos Configuration management page to verify that the WebSEAL instance can use the service name to authenticate to the KDC.Check the output message to determine the success of the authentication. If the authentication is successful, a success message is displayed. If the authentication fails, an error message is displayed.Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Verifying WebSEAL authentication with the keytab file

Ensure that WebSEAL can use the generated keytab file to authenticate to the KDC.

About this task

Verify that the WebSEAL server can authenticate with the keytab file that you created in Mapping a Kerberos principal to an Active Directory user.

Procedure

To open the Kerberos Configuration management page in the LMI, select Secure Web Settings > Global Settings > Kerberos Configuration.

Click Test on the Keyfiles tab on the Kerberos Configuration management page to verify that the WebSEAL instance can use the service name to authenticate to the KDC.

Check the output message to determine the success of the authentication.

If the authentication is successful, a success message is displayed.

If the authentication fails, an error message is displayed.

Parent topic: Configure Windows desktop single sign-on

Adding service name and keytab file entriesAdd service name and keytab file entriesYou must configure the Kerberos service name and the name of the keytab file.spnego stanzaservice namesaddingkeytab file entriesModify the Kerberos authentication settings in the LMI to add the Kerberos service name and the name of the keytab file. From the top menu of the LMI, select Secure Web Settings > Manage > Reverse Proxy. The Reverse Proxy management page displays.Select the reverse proxy instance that you want to manage.Select Edit.Select the Authentication tab.In the Kerberos Authentication settings, add the Kerberos service name to the list of Kerberos Service Names. This Kerberos Service Names field in the LMI adds an spnego-krb-service-name stanza entry to the [spnego] stanza in the WebSEAL configuration file.There is one spnego-krb-service-name stanza entry for the standard WebSEAL server junctions and one for each virtual host junction.The first entry in the list is used for authentication to standard junctions. For example:# The principal HTTP@www.example.com will be used for authentication # to standard junctions. spnego-krb-service-name = HTTP@www.example.com # The principal HTTP@sales.example.com will be used for the virtual # host junction sales.example.com spnego-krb-service-name = HTTP@sales.example.com # The principal HTTP@eng.example.com will be used for the virtual # host junction eng.example.com spnego-krb-service-name = HTTP@eng.example.comThese entries are set by updating the Kerberos settings on the Authentication tab for a Reverse Proxy instance.In the Kerberos Authentication settings, add the name of the keytab file in the Keytab File field.The keytab file must contain an entry for each principal listed. To configure SPNEGO authentication for virtual host junctions, specify the combined keytab file. For example, spnego.keytab.This Keytab File field in the LMI sets the value of the spnego-krb-keytab-file entry in the [spnego] stanza in the WebSEAL configuration file.Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Adding service name and keytab file entries

You must configure the Kerberos service name and the name of the keytab file.

About this task

Modify the Kerberos authentication settings in the LMI to add the Kerberos service name and the name of the keytab file.

Procedure

From the top menu of the LMI, select Secure Web Settings > Manage > Reverse Proxy. The Reverse Proxy management page displays.

Select the reverse proxy instance that you want to manage.

Select Edit.

Select the Authentication tab.

In the Kerberos Authentication settings, add the Kerberos service name to the list of Kerberos Service Names. This Kerberos Service Names field in the LMI adds an spnego-krb-service-name stanza entry to the [spnego] stanza in the WebSEAL configuration file.

There is one spnego-krb-service-name stanza entry for the standard WebSEAL server junctions and one for each virtual host junction.

The first entry in the list is used for authentication to standard junctions.

For example:

# The principal HTTP@www.example.com will be used for authentication
# to standard junctions.
spnego-krb-service-name = HTTP@www.example.com

# The principal HTTP@sales.example.com will be used for the virtual
# host junction sales.example.com
spnego-krb-service-name = HTTP@sales.example.com

# The principal HTTP@eng.example.com will be used for the virtual
# host junction eng.example.com
spnego-krb-service-name = HTTP@eng.example.com

Note: These entries are set by updating the Kerberos settings on the Authentication tab for a Reverse Proxy instance.

In the Kerberos Authentication settings, add the name of the keytab file in the Keytab File field.

The keytab file must contain an entry for each principal listed. To configure SPNEGO authentication for virtual host junctions, specify the combined keytab file. For example, spnego.keytab.

Note: This Keytab File field in the LMI sets the value of the spnego-krb-keytab-file entry in the [spnego] stanza in the WebSEAL configuration file.

Parent topic: Configure Windows desktop single sign-on

Enabling SPNEGO for WebSEALEnable SPNEGO for WebSEALYou must configure WebSEAL to enable SPNEGO.kerberosv5 stanza entryspnego-auth stanza entryFrom the top menu of the LMI, select Secure Web Settings > Manage > Reverse Proxy. The Reverse Proxy management page displays.Select the reverse proxy instance that you want to manage.Select Edit.Select the Authentication tab.In the Kerberos Authentication settings, select HTTPS for the Transport field to enable SPNEGO over SSL.This Transport field in the LMI sets the value of the spnego-auth entry in the [spnego] stanza in the WebSEAL configuration file.Edit the [spnego] stanza in the WebSEAL configuration file to enable adding the security identifier (SID) of the user as an extended attribute to the credential during authentication.[spnego] spnego-sid-attr-name = attribute_namewhere attribute_name defines the name of the attribute that stores the SID.Click Save.Deploy the updates as described in Deploying WebSEAL updates in the LMIWhen there are pending changes, a warning message is displayed at the top of the main pane. You can deploy or roll back the pending changes..Restart the reverse proxy instance as described in WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance..Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Enabling SPNEGO for WebSEAL

You must configure WebSEAL to enable SPNEGO.

Procedure

From the top menu of the LMI, select Secure Web Settings > Manage > Reverse Proxy. The Reverse Proxy management page displays.

Select the reverse proxy instance that you want to manage.

Select Edit.

Select the Authentication tab.

In the Kerberos Authentication settings, select HTTPS for the Transport field to enable SPNEGO over SSL.

Note: This Transport field in the LMI sets the value of the spnego-auth entry in the [spnego] stanza in the WebSEAL configuration file.

Optional: Edit the [spnego] stanza in the WebSEAL configuration file to enable adding the security identifier (SID) of the user as an extended attribute to the credential during authentication.

[spnego]
spnego-sid-attr-name = attribute_name

where attribute_name defines the name of the attribute that stores the SID.

Click Save.

Deploy the updates as described in Deploying WebSEAL updates in the LMI.

Restart the reverse proxy instance as described in WebSEAL instance management.

Parent topic: Configure Windows desktop single sign-on

Removing cached tokens from the Windows clientRemove cached tokens from Windows clientRemove cached tokens from the Windows clientFor SPNEGO to work correctly, you must remove any cached Kerberos tokens from the Windows client. When a client contains cached Active Directory credentials, SPNEGO might not work correctly on the client until it obtains the new credentials. Windowsrestarting clientklist purgeRun klist on the Windows desktop client to determine the presence of old Kerberos tokens. If old tokens are present, take one of the following actions: Run klist purge to delete each token. Restart the Windows desktop. Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Removing cached tokens from the Windows client

For SPNEGO to work correctly, you must remove any cached Kerberos tokens from the Windows client. When a client contains cached Active Directory credentials, SPNEGO might not work correctly on the client until it obtains the new credentials.

Procedure

Run klist on the Windows desktop client to determine the presence of old Kerberos tokens.

If old tokens are present, take one of the following actions:

Run klist purge to delete each token.

Restart the Windows desktop.

Parent topic: Configure Windows desktop single sign-on

Configuring the Internet Explorer clientConfigure the Internet Explorer clientConfigure the Internet Explorer client for SPNEGO protocol in IBM Security Access Manager for WebIf you use Internet Explorer, you must configure the browser to use the SPNEGO protocol.Internet ExplorerSPNEGO protocol configurationbrowser configurationYou must configure the Internet Explorer client to use the SPNEGO protocol to negotiate authentication mechanisms. Consult the Microsoft Internet Explorer documentation for configuration instructions.Keep the following points in mind during the configuration:The Internet Explorer browser must recognize the WebSEAL server as an Intranet site. Otherwise, the Internet Explorer client does not automatically send an SPNEGO authorization token for the logged in user to the WebSEAL server. The Internet Explorer client must add the WebSEAL server to the Intranet Sites list. If required, you can add the WebSEAL server to the Trusted Sites instead of Intranet Sites. By default, Automatic logon occurs only in the Intranet zone. Therefore, you must create a Custom Security Level for Trusted Sites that sets the User AuthenticationLogon setting to Automatic logon. You must provide the current user name and password for this configuration. You must configure Internet Explorer 6 to enable single sign-on. Use the menu item for Internet Options... and select the Advanced tab.The Windows client must use the correct DNS name to access the WebSEAL server. When an incorrect DNS name is used, Internet Explorer might attempt to use NT LAN Manager (NTLM) protocol to contact WebSEAL. WebSEAL does not support NTLM.Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Configuring the Internet Explorer client

If you use Internet Explorer, you must configure the browser to use the SPNEGO protocol.

About this task

You must configure the Internet Explorer client to use the SPNEGO protocol to negotiate authentication mechanisms. Consult the Microsoft Internet Explorer documentation for configuration instructions.

Keep the following points in mind during the configuration:

The Internet Explorer browser must recognize the WebSEAL server as an Intranet site. Otherwise, the Internet Explorer client does not automatically send an SPNEGO authorization token for the logged in user to the WebSEAL server. The Internet Explorer client must add the WebSEAL server to the Intranet Sites list.

If required, you can add the WebSEAL server to the Trusted Sites instead of Intranet Sites.

By default, Automatic logon occurs only in the Intranet zone. Therefore, you must create a Custom Security Level for Trusted Sites that sets the User Authentication > Logon setting to Automatic logon. You must provide the current user name and password for this configuration.

You must configure Internet Explorer 6 to enable single sign-on. Use the menu item for Internet Options... and select the Advanced tab.

The Windows client must use the correct DNS name to access the WebSEAL server. When an incorrect DNS name is used, Internet Explorer might attempt to use NT LAN Manager (NTLM) protocol to contact WebSEAL. WebSEAL does not support NTLM.

Parent topic: Configure Windows desktop single sign-on

Troubleshooting for Windows desktop single sign-onTroubleshooting for Windows desktop single sign-onTroubleshooting for Windows desktop single sign-on in IBM Security Access Manager for WebtroubleshootingWindows desktop single sign-onWindowssingle sign-ontroubleshootingSee the section describing solutions to common Web security SPNEGO problems in the Troubleshooting section of the IBM Knowledge Center.Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Troubleshooting for Windows desktop single sign-on

See the section describing solutions to common Web security SPNEGO problems in the Troubleshooting section of the IBM Knowledge Center.

Parent topic: Configure Windows desktop single sign-on

Configuration notes for a load balancer environmentConfiguration notes for a load balancer environmentConfiguration notes for a load balancer environment in IBM Security Access Manager for WebThe following notes address the configuration of Windows desktop single sign-on using SPNEGO in an environment with multiple WebSEAL servers operating behind a load balancer.load balancersconfigurationSPNEGOwith multiple WebSEAL serversConditions: Host name that is used by clients contacting the WebSEAL servers: lb.example.comWebSEAL servers: websealA.example.comwebsealB.example.comwebsealC.example.comwebsealD.example.comActive Directory domain: MYDOMAINGeneral procedures: Create a user ID in Active Directory for the various WebSEAL services to run as. For this example, the ID is webseal.On the Active Directory server, run the following command: ktpass -princ HTTP/lb.example.com@MYDOMAIN -mapuser webseal -pass mypassw0rd -out lb_HTTP.keytab -mapOp set The DNS name that is specified to the ktpass command must match the DNS name clients use to contact the load balanced WebSEAL servers.The following message displays: Successfully mapped HTTP/lb.example.com to webseal.You must also complete standard SPNEGO configuration for WebSEAL and Internet Explorer as described in the following section: Configure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance. Ensure that you add lb.example.com to the Internet Explorer Trusted Sites list.If you point a browser at http://lb.example.com, you are automatically authenticated to WebSEAL. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. Windows desktop single sign-on conceptsConfigure Windows desktop single sign-onThere are many configuration tasks that you must complete to implement Windows desktop single sign-on using Kerberos authentication for WebSEAL on the appliance.

Configuration notes for a load balancer environment

The following notes address the configuration of Windows desktop single sign-on using SPNEGO in an environment with multiple WebSEAL servers operating behind a load balancer.

Conditions:

Host name that is used by clients contacting the WebSEAL servers:

lb.example.com

WebSEAL servers:

websealA.example.com

websealB.example.com

websealC.example.com

websealD.example.com

Active Directory domain: MYDOMAIN

General procedures:

Create a user ID in Active Directory for the various WebSEAL services to run as. For this example, the ID is webseal.

On the Active Directory server, run the following command:

ktpass -princ HTTP/lb.example.com@MYDOMAIN -mapuser webseal -pass mypassw0rd
-out lb_HTTP.keytab -mapOp set

Note: The DNS name that is specified to the ktpass command must match the DNS name clients use to contact the load balanced WebSEAL servers.

The following message displays:

Successfully mapped HTTP/lb.example.com to webseal.

You must also complete standard SPNEGO configuration for WebSEAL and Internet Explorer as described in the following section:

Configure Windows desktop single sign-on

Ensure that you add lb.example.com to the Internet Explorer Trusted Sites list.

If you point a browser at http://lb.example.com, you are automatically authenticated to WebSEAL.

Parent topic: Windows desktop single sign-on

Related concepts:

Windows desktop single sign-on concepts

Configure Windows desktop single sign-on

LTPA authenticationLTPA authenticationLTPA authentication in IBM Security Access Manager for WebLTPAauthenticationoverviewauthenticationLTPAoverviewSecurity Access Manager supports authentication using an LTPA cookie received from the client. This section contains the following topics: Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsBasic authenticationForms authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. OAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.LTPA authentication overviewVarious IBM servers provide support for the cookie-based lightweight third-party authentication mechanism (LTPA). Among these servers are WebSphere and DataPower. To achieve a single signon solution to one or more of these servers, you can configure WebSEAL to support LTPA authentication.Enabling LTPA authenticationThe ltpa-auth stanza entry is located in the [ltpa] stanza of the WebSEAL configuration file. It enables and disables the LTPA authentication method.Key file informationThe LTPA token is encrypted by a password-protected secret key. The key itself is generated by WebSphere and is contained in a key file. This key file is password-protected by a clear text key. Specifying the cookie name for clientsYou can configure the name of the cookie containing the LTPA token that WebSEAL issues to clients. Specifying the cookie name for junctionsYou can configure the name of the cookie that contains the LTPA token for junctioned web servers.Controlling the lifetime of the LTPA TokenDisabling LTPA authentication

LTPA authentication

Security Access Manager supports authentication using an LTPA cookie received from the client. This section contains the following topics:

LTPA authentication overview
Various IBM® servers provide support for the cookie-based lightweight third-party authentication mechanism (LTPA). Among these servers are WebSphere® and DataPower®. To achieve a single signon solution to one or more of these servers, you can configure WebSEAL to support LTPA authentication.

Enabling LTPA authentication
The ltpa-auth stanza entry is located in the [ltpa] stanza of the WebSEAL configuration file. It enables and disables the LTPA authentication method.

Key file information
The LTPA token is encrypted by a password-protected secret key. The key itself is generated by WebSphere and is contained in a key file. This key file is password-protected by a clear text key.

Specifying the cookie name for clients
You can configure the name of the cookie containing the LTPA token that WebSEAL issues to clients.

Specifying the cookie name for junctions
You can configure the name of the cookie that contains the LTPA token for junctioned web servers.

Controlling the lifetime of the LTPA Token

Disabling LTPA authentication

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

OAuth Authentication

Related reference:

Authentication terminology

Logout and password change operations

LTPA authentication overview LTPA authentication overview IBM Security Access Manager for Web LTPA authenticationVarious IBM servers provide support for the cookie-based lightweight third-party authentication mechanism (LTPA). Among these servers are WebSphere and DataPower. To achieve a single signon solution to one or more of these servers, you can configure WebSEAL to support LTPA authentication.LTPAauthenticationoverviewauthenticationLTPAoverviewThe LTPA cookie, which serves as an authentication token for WebSphere/DataPower, contains the user identity, key and token data, buffer length, and expiration information. This information is encrypted using a password-protected secret key that is shared between WebSEAL and the other LTPA enabled servers.When an unauthenticated user makes a request for a WebSEAL protected resource, it will first determine whether an LTPA cookie is available. If an LTPA cookie is available, it will validate the contents of the cookie and, if successful, create a new session based on the user name and expiry time contained within the cookie. If no LTPA cookie is available, WebSEAL will continue to authenticate the user using the other configured authentication mechanisms. Once the authentication operation has been completed, a new LTPA cookie will inserted into the HTTP response and passed back to the client for consumption by other LTPA enabled authentication servers.WebSEAL only supports LTPA version 2 (LtpaToken2) cookies. LtpaToken2 contains stronger encryption than prior versions of the token and enables you to add multiple attributes to the token. This token contains the authentication identity and additional information, such as the attributes that are used for contacting the original login server, and the unique cache key for looking up the Subject when considering more than just the identity in determining uniqueness. LtpaToken2 is generated for WebSphere Application Server Version 5.1.0.2 (for z/OS) and for version 5.1.1 (for distributed) and beyond.LTPA authentication

LTPA authentication overview

Various IBM® servers provide support for the cookie-based lightweight third-party authentication mechanism (LTPA). Among these servers are WebSphere® and DataPower®. To achieve a single signon solution to one or more of these servers, you can configure WebSEAL to support LTPA authentication.

The LTPA cookie, which serves as an authentication token for WebSphere/DataPower, contains the user identity, key and token data, buffer length, and expiration information. This information is encrypted using a password-protected secret key that is shared between WebSEAL and the other LTPA enabled servers.

When an unauthenticated user makes a request for a WebSEAL protected resource, it will first determine whether an LTPA cookie is available. If an LTPA cookie is available, it will validate the contents of the cookie and, if successful, create a new session based on the user name and expiry time contained within the cookie. If no LTPA cookie is available, WebSEAL will continue to authenticate the user using the other configured authentication mechanisms. Once the authentication operation has been completed, a new LTPA cookie will inserted into the HTTP response and passed back to the client for consumption by other LTPA enabled authentication servers.

WebSEAL only supports LTPA version 2 (LtpaToken2) cookies. LtpaToken2 contains stronger encryption than prior versions of the token and enables you to add multiple attributes to the token. This token contains the authentication identity and additional information, such as the attributes that are used for contacting the original login server, and the unique cache key for looking up the Subject when considering more than just the identity in determining uniqueness. LtpaToken2 is generated for WebSphere Application Server Version 5.1.0.2 (for z/OS®) and for version 5.1.1 (for distributed) and beyond.

Parent topic: LTPA authentication

Enabling LTPA authenticationEnabling LTPA authenticationEnabling LTPA authentication in IBM Security Access Manager for WebThe ltpa-auth stanza entry is located in the [ltpa] stanza of the WebSEAL configuration file. It enables and disables the LTPA authentication method.LTPAauthenticationenablingauthenticationLTPAenablingLTPA authentication is disabled by default. To configure LTPA authentication, complete the following steps: Stop the WebSEAL server. Edit the WebSEAL configuration file. In the [ltpa] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table. Configuring LTPA authenticationProtocol to SupportConfiguration File EntryHTTPltpa-auth = httpHTTPSltpa-auth = httpsBoth HTTP and HTTPSltpa-auth = bothDisable LTPA authentication (default)ltpa-auth = noneFor example, to support both protocols: [ltpa] ltpa-auth = both Customize the entries contained within the [ltpa] stanza. Restart the WebSEAL server.LTPA authentication

Enabling LTPA authentication

The ltpa-auth stanza entry is located in the [ltpa] stanza of the WebSEAL configuration file. It enables and disables the LTPA authentication method.

About this task

LTPA authentication is disabled by default. To configure LTPA authentication, complete the following steps:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. In the [ltpa] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.

Table 31. Configuring LTPA authentication

Protocol to Support | Configuration File Entry
HTTP | ltpa-auth = http
HTTPS | ltpa-auth = https
Both HTTP and HTTPS | ltpa-auth = both
Disable LTPA authentication (default) | ltpa-auth = none

For example, to support both protocols: [ltpa] ltpa-auth = both

Customize the entries contained within the [ltpa] stanza.

Restart the WebSEAL server.

Parent topic: LTPA authentication

Key file informationKey file informationKey file information in IBM Security Access Manager for WebThe LTPA token is encrypted by a password-protected secret key. The key itself is generated by WebSphere and is contained in a key file. This key file is password-protected by a clear text key. key file informationThe name of the key file that WebSEAL uses is defined by the keyfile configuration entry in the [ltpa] stanza. The permissions on the file must give read access to the user who is running the WebSEAL binary file.The keyfile-password configuration entry in the [ltpa] stanza defines the password, which is used to protect the key file. If the password is sensitive, it can alternatively be stored in the corresponding configuration entry in the WebSEAL obfuscated database. You can use the Local Management Interface (LMI) to manage this password.LTPA authentication

Key file information

The LTPA token is encrypted by a password-protected secret key. The key itself is generated by WebSphere® and is contained in a key file. This key file is password-protected by a clear text key.

The name of the key file that WebSEAL uses is defined by the keyfile configuration entry in the [ltpa] stanza. The permissions on the file must give read access to the user who is running the WebSEAL binary file.

The keyfile-password configuration entry in the [ltpa] stanza defines the password, which is used to protect the key file. If the password is sensitive, it can alternatively be stored in the corresponding configuration entry in the WebSEAL obfuscated database.

You can use the Local Management Interface (LMI) to manage this password.

Parent topic: LTPA authentication

Specifying the cookie name for clientsSpecifying the cookie name for clientsSpecifying the cookie name for clients in IBM Security Access Manager for WebYou can configure the name of the cookie containing the LTPA token that WebSEAL issues to clients. cookie namefor clientsspecificationBy default, WebSEAL uses a cookie named Ltpatoken2 to contain the LTPA token. Both WebSphere and DataPower expect this name by default. To customize the name of the client cookie that contains the LTPA token, change the value of the cookie-name configuration entry in the [ltpa] stanza. For example:[ltpa] cookie-name = Ltpatoken2 LTPA authentication

Specifying the cookie name for clients

You can configure the name of the cookie containing the LTPA token that WebSEAL issues to clients.

By default, WebSEAL uses a cookie named Ltpatoken2 to contain the LTPA token. Both WebSphere® and DataPower® expect this name by default. To customize the name of the client cookie that contains the LTPA token, change the value of the cookie-name configuration entry in the [ltpa] stanza.

For example:

[ltpa] cookie-name = Ltpatoken2

Parent topic: LTPA authentication

Specifying the cookie name for junctionsSpecifying the cookie name for junctionsSpecifying the cookie name for junctions in IBM Security Access Manager for WebYou can configure the name of the cookie that contains the LTPA token for junctioned web servers.cookie namefor junctionsspecificationWebSphere Application Server and WebSEAL use the same default values for the LTPA cookie name:LtpaToken for LTPA tokens.LtpaToken2 for LTPA version 2 tokens.You can use the entry jct-ltpa-cookie-name in the [ltpa] stanza to configure the name of the LTPA cookies sent from WebSEAL across junctions on the backend. You can configure this item globally or on a per junction basis. To set a cookie name for WebSEAL to use across all junctions, configure the entry in the [ltpa] stanza. For example:[ltpa] jct-ltpa-cookie-name = myGlobalLTPAcookie To set a cookie name specific to a particular junction, configure the entry in an [ltpa:/jct] stanza. where:jctName of the junction to the backend server.For example:[ltpa:/jct] jct-ltpa-cookie-name = myLTPACookieForJctIf you use a custom LTPA cookie name in WebSEAL, you must also configure the same cookie name in WebSphere to achieve single sign-on. If you do not configure the jct-ltpa-cookie-name entry, WebSEAL uses the default cookie name. LTPA authentication

Specifying the cookie name for junctions

You can configure the name of the cookie that contains the LTPA token for junctioned web servers.

WebSphere® Application Server and WebSEAL use the same default values for the LTPA cookie name:

LtpaToken for LTPA tokens.

LtpaToken2 for LTPA version 2 tokens.

You can use the entry jct-ltpa-cookie-name in the [ltpa] stanza to configure the name of the LTPA cookies sent from WebSEAL across junctions on the backend. You can configure this item globally or on a per junction basis.

To set a cookie name for WebSEAL to use across all junctions, configure the entry in the [ltpa] stanza. For example:

[ltpa]
jct-ltpa-cookie-name = myGlobalLTPAcookie

To set a cookie name specific to a particular junction, configure the entry in an [ltpa:/jct] stanza.

where:

jct

Name of the junction to the backend server.

For example:

[ltpa:/jct]
jct-ltpa-cookie-name = myLTPACookieForJct

If you use a custom LTPA cookie name in WebSEAL, you must also configure the same cookie name in WebSphere to achieve single sign-on. If you do not configure the jct-ltpa-cookie-name entry, WebSEAL uses the default cookie name.

Parent topic: LTPA authentication

Controlling the lifetime of the LTPA TokenControlling the lifetime of the LTPA TokenControlling the lifetime of the LTPA Token in IBM Security Access Manager for WebLTPAcontrol token lifetimetokensLTPABy default, the lifetime of the LTPA cookie is set to the lifetime of the session that was used to create the token. For a more fine-grained approach, you can modify the update-cookie configuration entry in the [ltpa] stanza. This entry controls the frequency at which the token is updated with a new lifetime timeout. This configuration entry affects the LTPA cookie that WebSEAL issues to clients. It is the lifetime of the cookie that is specified by the cookie-name configuration entry in the [ltpa] stanza.The default value of -1 indicates that the token is never updated and the lifetime of the token is equal to the maximum session lifetime.A value of zero indicates that the lifetime of the token is updated on every request. This configuration provides the functional equivalent of the inactivity timeout to the token.A positive number indicates the number of seconds that elapse between updates of the token. This configuration provides a less fine-grained equivalent of the inactivity timeout to the token. Carefully consider whether to enable this configuration entry in your environment. The cost of creating the LTPA token and adding it to the HTTP response can outweigh the benefits gained by achieving an inactivity timeout for the token.LTPA authentication

Controlling the lifetime of the LTPA Token

By default, the lifetime of the LTPA cookie is set to the lifetime of the session that was used to create the token. For a more fine-grained approach, you can modify the update-cookie configuration entry in the [ltpa] stanza. This entry controls the frequency at which the token is updated with a new lifetime timeout.

Note: This configuration entry affects the LTPA cookie that WebSEAL issues to clients. It is the lifetime of the cookie that is specified by the cookie-name configuration entry in the [ltpa] stanza.

The default value of -1 indicates that the token is never updated and the lifetime of the token is equal to the maximum session lifetime.

A value of zero indicates that the lifetime of the token is updated on every request. This configuration provides the functional equivalent of the inactivity timeout to the token.

A positive number indicates the number of seconds that elapse between updates of the token. This configuration provides a less fine-grained equivalent of the inactivity timeout to the token.

Carefully consider whether to enable this configuration entry in your environment. The cost of creating the LTPA token and adding it to the HTTP response can outweigh the benefits gained by achieving an inactivity timeout for the token.

Parent topic: LTPA authentication

Disabling LTPA authentication Disabling LTPA authentication LTPAauthenticationdisablingauthenticationLTPAdisablingTo disable LTPA authentication, complete the following steps: Stop the WebSEAL server. Edit the WebSEAL configuration file, setting ltpa-auth to none:[ltpa] ltpa-auth = none Restart the WebSEAL server.LTPA authentication is disabled by default.LTPA authentication

Disabling LTPA authentication

About this task

To disable LTPA authentication, complete the following steps:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file, setting ltpa-auth to none:

[ltpa] ltpa-auth = none

Restart the WebSEAL server.

Results

Note: LTPA authentication is disabled by default.

Parent topic: LTPA authentication

OAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.OAuth is an HTTP-based authorization protocol. It provides third-party applications with scoped access to a protected resource on behalf of the resource owner. It provides scoped access by creating an approval interaction between the resource owner, the client, and the resource server. Users receive the ability to share their private resources between sites without providing user names and passwords.When OAuth Authentication is enabled, the WebSEAL configuration parameter session lifetime timeout, which is controlled by the timeout entry in the [session] stanza of the WebSEAL configuration file, is ignored. The session lifetime is set to the OAuth token expiry time.For a complete description of the OAuth specifications, see the OAuth website: http://www.oauth.netFor more general information about OAuth support in Security Access Manager, see OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards..Authentication methodsThis chapter presents information about how to configure the core set of authentication methods supported by WebSEAL.Authentication terminologyLogout and password change operationsBasic authenticationForms authenticationClient-side certificate authenticationToken authenticationKerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. Windows desktop single sign-onThis chapter discusses the concepts and configuration steps required to implement an authentication solution that enables browser clients to access WebSEAL servers without multiple logins. LTPA authenticationEnabling and disabling OAuth authenticationThe oauth-auth stanza entry, located in the [oauth] stanza of the WebSEAL configuration file, enables and disables the OAuth authentication method. By default, OAuth authentication is disabled.Sample OAuth flowThe OAuth authentication supported by Security Access Manager is OAuth version 2.0. The method of providing the access token is through an HTTP header named Authorization. Other forms of providing the access token are not supported. Here is a typical work flow to make use of OAuth authentication.The user-identity-attribute stanza entryOAuth authentication must create a user credential. To do this, OAuth authentication must be provided with a user identity to use when creating this credential. The appliance's implementation of OAuth authentication provides the definition of the user identity through an attribute that is returned by the OAuth server.

OAuth Authentication

Security Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.

OAuth is an HTTP-based authorization protocol. It provides third-party applications with scoped access to a protected resource on behalf of the resource owner. It provides scoped access by creating an approval interaction between the resource owner, the client, and the resource server. Users receive the ability to share their private resources between sites without providing user names and passwords.

When OAuth Authentication is enabled, the WebSEAL configuration parameter session lifetime timeout, which is controlled by the timeout entry in the [session] stanza of the WebSEAL configuration file, is ignored. The session lifetime is set to the OAuth token expiry time.

For a complete description of the OAuth specifications, see the OAuth website: http://www.oauth.net

For more general information about OAuth support in Security Access Manager, see OAuth 2.0 support.

Enabling and disabling OAuth authentication
The oauth-auth stanza entry, located in the [oauth] stanza of the WebSEAL configuration file, enables and disables the OAuth authentication method. By default, OAuth authentication is disabled.

Sample OAuth flow
The OAuth authentication supported by Security Access Manager is OAuth version 2.0. The method of providing the access token is through an HTTP header named "Authorization". Other forms of providing the access token are not supported. Here is a typical work flow to make use of OAuth authentication.

The user-identity-attribute stanza entry
OAuth authentication must create a user credential. To do this, OAuth authentication must be provided with a user identity to use when creating this credential. The appliance's implementation of OAuth authentication provides the definition of the user identity through an attribute that is returned by the OAuth server.

Parent topic: Authentication methods

Related concepts:

Basic authentication

Forms authentication

Client-side certificate authentication

Token authentication

Kerberos authentication through an External Authentication Interface (EAI)

Windows desktop single sign-on

LTPA authentication

Related reference:

Authentication terminology

Logout and password change operations

Enabling and disabling OAuth authenticationThe oauth-auth stanza entry, located in the [oauth] stanza of the WebSEAL configuration file, enables and disables the OAuth authentication method. By default, OAuth authentication is disabled.Stop the WebSEAL server.Edit the WebSEAL configuration file. In the [oauth] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.Configuring OAuth authenticationProtocol to supportConfiguration file entryHTTPoauth-auth = httpHTTPSoauth-auth = httpsBoth HTTP and HTTPSoauth-auth = bothDisable OAuthc authenticationoauth-auth = noneFor example, to support both HTTP and HTTPS protocols:[oauth] oauth-auth = bothRestart the WebSEAL server.OAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.

Enabling and disabling OAuth authentication

The oauth-auth stanza entry, located in the [oauth] stanza of the WebSEAL configuration file, enables and disables the OAuth authentication method. By default, OAuth authentication is disabled.

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. In the [oauth] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.

Table 32. Configuring OAuth authentication

Protocol to support | Configuration file entry
HTTP | oauth-auth = http
HTTPS | oauth-auth = https
Both HTTP and HTTPS | oauth-auth = both
Disable OAuthc authentication | oauth-auth = none

For example, to support both HTTP and HTTPS protocols:

[oauth]
oauth-auth = both

Restart the WebSEAL server.

Parent topic: OAuth Authentication

Sample OAuth flowThe OAuth authentication supported by Security Access Manager is OAuth version 2.0. The method of providing the access token is through an HTTP header named Authorization. Other forms of providing the access token are not supported. Here is a typical work flow to make use of OAuth authentication.Acquire an access token from the OAuth server. Using curl, this could be accomplished as follows:curl -k -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=client_credentials&client_id=<CLIENT_ID> &client_secret=<CLIENT_SECRET>&redirect_uri=" https://<WEBSEAL_SERVER>/mga/sps/oauth/oauth20/tokenWhere:CLIENT_ID is the client ID that is created in the API Protection portion of the appliance LMI.CLIENT_SECRET is the secret associated with the client created in the API Protection portion of the appliance LMI. The curl call above would return output resembling the following result:{"expires_in":3599,"access_token":"iCIFH6k7KUq0oP55ZZFd", "token_type":"bearer","scope":""}Note that the returned result contains the access_token and its value, which is obtained from the OAuth server.Access an API-protected resource. Using curl, this could be accomplished as follows:curl -k -c auth.txt -H "Authorization: Bearer iCIFH6k7KUq0oP55ZZFd" https://<WEBSEAL_SERVER>/<API_protected resource>Notice the HTTP header provided, named Authorization. The value of this header is the key word Bearer followed by the access_token that was obtained in Step 1. This access token is fed to the OAuth server and will allow the HTTP request to be satisfied for the API-protected resource.OAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.

Sample OAuth flow

The OAuth authentication supported by Security Access Manager is OAuth version 2.0. The method of providing the access token is through an HTTP header named "Authorization". Other forms of providing the access token are not supported. Here is a typical work flow to make use of OAuth authentication.

Acquire an access token from the OAuth server.

Using curl, this could be accomplished as follows:

curl -k -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
-d "grant_type=client_credentials&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>&redirect_uri="
https://<WEBSEAL_SERVER>/mga/sps/oauth/oauth20/token

Where:

CLIENT_ID is the client ID that is created in the API Protection portion of the appliance LMI.

CLIENT_SECRET is the secret associated with the client created in the API Protection portion of the appliance LMI.

The curl call above would return output resembling the following result:

{"expires_in":3599,"access_token":"iCIFH6k7KUq0oP55ZZFd",
"token_type":"bearer","scope":""}

Note that the returned result contains the access_token and its value, which is obtained from the OAuth server.

Access an API-protected resource.

Using curl, this could be accomplished as follows:

curl  -k -c auth.txt -H "Authorization: Bearer iCIFH6k7KUq0oP55ZZFd"
https://<WEBSEAL_SERVER>/<API_protected resource>

Notice the HTTP header provided, named "Authorization". The value of this header is the key word Bearer followed by the access_token that was obtained in Step 1. This access token is fed to the OAuth server and will allow the HTTP request to be satisfied for the API-protected resource.

Parent topic: OAuth Authentication

The user-identity-attribute stanza entryOAuth authentication must create a user credential. To do this, OAuth authentication must be provided with a user identity to use when creating this credential. The appliance's implementation of OAuth authentication provides the definition of the user identity through an attribute that is returned by the OAuth server.The user-identity-attribute entry in the [oauth] stanza defines the name of the attribute that is returned by the OAuth server. This stanza entry's value is the user identity that is used when creating a credential for the OAuth authentication. By default, this entry has a value of username. What that tells the appliance is to take the value of the username attribute from the OAuth server response and use that as the user identity for the credential that will be created. By default, the username value in the OAuth server response is the client ID of the API protection client. That client ID must exist as an Security Access Manager user for OAuth authentication to be able to create a valid credential. You can modify the OAuth server to provide the user identity in a different attribute, that is, something other than the username attribute. If you do that, modify the user-identity-attribute entry in the [oauth] stanza of the webseald.conf file, to provide that attribute name.For more information, see the [oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings. documentation in the IBM Knowledge Center.OAuth AuthenticationSecurity Access Manager supports OAuth 2.0 authentication. The implementation of OAuth in Security Access Manager strictly follows the OAuth standards.

The user-identity-attribute stanza entry

OAuth authentication must create a user credential. To do this, OAuth authentication must be provided with a user identity to use when creating this credential. The appliance's implementation of OAuth authentication provides the definition of the user identity through an attribute that is returned by the OAuth server.

The user-identity-attribute entry in the [oauth] stanza defines the name of the attribute that is returned by the OAuth server. This stanza entry's value is the user identity that is used when creating a credential for the OAuth authentication. By default, this entry has a value of username. What that tells the appliance is to take the value of the username attribute from the OAuth server response and use that as the user identity for the credential that will be created. By default, the username value in the OAuth server response is the client ID of the API protection client. That client ID must exist as an Security Access Manager user for OAuth authentication to be able to create a valid credential.

You can modify the OAuth server to provide the user identity in a different attribute, that is, something other than the username attribute. If you do that, modify the user-identity-attribute entry in the [oauth] stanza of the webseald.conf file, to provide that attribute name.

For more information, see the [oauth] stanza documentation in the IBM Knowledge Center.

Parent topic: OAuth Authentication

Advanced authentication methodsAdvanced authentication methodsauthentication methodsadvancedadvanced authentication methodsThis chapter contains information that describes advanced WebSEAL authentication functionality. Topic Index:AuthenticationMultiplexing proxy agentsSwitch user authenticationReauthenticationAuthentication strength policy (step-up)External authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords.

Advanced authentication methods

This chapter contains information that describes advanced WebSEAL authentication functionality.

Topic Index:

Multiplexing proxy agents

Switch user authentication

Reauthentication

Authentication strength policy (step-up)

External authentication interface

Client Certificate User Mapping
The Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.

Authenticated User Mapping
You can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

External user mapping
Use the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.

Password strength
The password strength module validates the strength of new passwords.

Parent topic: Authentication

Multiplexing proxy agents Multiplexing proxy agents MPAauthenticationmultiplexing proxy agentsmultiplexing proxy agents (authentication)authenticationmultiplexing proxy agents (MPA)This section contains the following topics:Advanced authentication methodsSwitch user authenticationReauthenticationAuthentication strength policy (step-up)External authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords. Multiplexing proxy agents overviewValid session data types and authentication methodsDifferent session data types and authentication methods are valid depending on whether the session is for a Multiplexing proxy agent (MPA) or a client.Authentication process flow for MPA and multiple clientsEnabling and disabling MPA authenticationCreation of a user account for the MPAAddition of the MPA account to the webseal-mpa-servers groupMPA authentication limitations

Multiplexing proxy agents

This section contains the following topics:

Multiplexing proxy agents overview

Valid session data types and authentication methods
Different session data types and authentication methods are valid depending on whether the session is for a Multiplexing proxy agent (MPA) or a client.

Authentication process flow for MPA and multiple clients

Enabling and disabling MPA authentication

Creation of a user account for the MPA

Addition of the MPA account to the webseal-mpa-servers group

MPA authentication limitations

Parent topic: Advanced authentication methods

Related concepts:

Switch user authentication

Reauthentication

Authentication strength policy (step-up)

External authentication interface

Client Certificate User Mapping

Authenticated User Mapping

External user mapping

Password strength

Multiplexing proxy agents overviewMultiplexing proxy agents overviewproxyagentsSecurity Access Manager provides solutions for securing networks that use a multiplexing proxy agent (MPA).Standard Proxy Agents (SPA) are gateways that support per-client sessions between clients and the origin server over SSL or HTTP. WebSEAL can apply normal SSL or HTTP authentication to these per-client sessions.Multiplexing proxy agents (MPA) are gateways that accommodate multiple client access. These gateways are sometimes known as WAP gateways when clients access using Wireless Access Protocol (WAP). Gateways establish a single authenticated channel to the origin server and "tunnel" all client requests and responses through this channel.To WebSEAL, the information across this channel initially appears as multiple requests from one client. WebSEAL must distinguish between the authentication of the MPA server and the additional authentication of each individual client. Communication over an MPA GatewayCommunication over an MPA GatewayBecause WebSEAL maintains an authenticated session for the MPA, it must simultaneously maintain separate sessions for each client. Therefore, the authentication method and session data used for the MPA must be distinct (different) from the session data and authentication method used by the client.Multiplexing proxy agents

Multiplexing proxy agents overview

Security Access Manager provides solutions for securing networks that use a multiplexing proxy agent (MPA).

Standard Proxy Agents (SPA) are gateways that support per-client sessions between clients and the origin server over SSL or HTTP. WebSEAL can apply normal SSL or HTTP authentication to these per-client sessions.

Multiplexing proxy agents (MPA) are gateways that accommodate multiple client access. These gateways are sometimes known as WAP gateways when clients access using Wireless Access Protocol (WAP). Gateways establish a single authenticated channel to the origin server and "tunnel" all client requests and responses through this channel.

To WebSEAL, the information across this channel initially appears as multiple requests from one client. WebSEAL must distinguish between the authentication of the MPA server and the additional authentication of each individual client.

Figure 15. Communication over an MPA Gateway

Because WebSEAL maintains an authenticated session for the MPA, it must simultaneously maintain separate sessions for each client. Therefore, the authentication method and session data used for the MPA must be distinct (different) from the session data and authentication method used by the client.

Parent topic: Multiplexing proxy agents

Valid session data types and authentication methodsValid session data types and authentication methodsDifferent session data types and authentication methods are valid depending on whether the session is for a Multiplexing proxy agent (MPA) or a client.sessiondata typesauthenticationmethodsThe following table lists the valid session types for the MPA and the client:Valid session typesSession TypesMPA-to-WebSEALClient-to-WebSEALSSL Session IDYesNot validHTTP HeaderYesYesIP AddressYesNot validSession CookieYesYesThe session data type used by the MPA to WebSEAL must be distinct from the session data type used by the client to WebSEAL. As an example, if the MPA uses a session cookie for the session data type, the client must use the HTTP Header session data type.The client cannot use an SSL session ID as the session data type.If MPA support is enabled, the function of ssl-id-sessions changes. Normally, if ssl-id-sessions = yes, only the SSL session ID is used to maintain sessions for HTTPS clients. To allow the MPA to maintain a session with an SSL session ID and have clients maintain sessions by using another method, this restriction is removed. See also Valid session key data typesYou can configure the session key data type that WebSEAL uses for each authentication method..The following table lists the valid authentication methods for the MPA and the client:Valid authentication typesAuthentication TypesMPA-to-WebSEALClient-to-WebSEALBasic authenticationYesYesForms authenticationYesYesCertificateYesNot validExternal authentication interfaceYesNot validThe authentication method used by the MPA to WebSEAL must be distinct from the authentication method used by the client to WebSEAL. As an example, if the MPA uses basic authentication, the client must use forms authentication.Certificates and external authentication interface authentication methods are not valid for use by the client.Normally, if forms authentication is enabled for a particular transport, basic authentication is automatically disabled for that transport. If MPA support is enabled, this restriction is removed. The MPA is then allowed to log in, for example, with forms and clients to log in with basic authentication over the same transport.Multiplexing proxy agents

Valid session data types and authentication methods

Different session data types and authentication methods are valid depending on whether the session is for a Multiplexing proxy agent (MPA) or a client.

The following table lists the valid session types for the MPA and the client:

Table 33. Valid session types

Session Types | MPA-to-WebSEAL | Client-to-WebSEAL
SSL Session ID | Yes | Not valid
HTTP Header | Yes | Yes
IP Address | Yes | Not valid
Session Cookie | Yes | Yes

The session data type used by the MPA to WebSEAL must be distinct from the session data type used by the client to WebSEAL. As an example, if the MPA uses a session cookie for the session data type, the client must use the HTTP Header session data type.

The client cannot use an SSL session ID as the session data type.

If MPA support is enabled, the function of ssl-id-sessions changes. Normally, if ssl-id-sessions = yes, only the SSL session ID is used to maintain sessions for HTTPS clients. To allow the MPA to maintain a session with an SSL session ID and have clients maintain sessions by using another method, this restriction is removed. See also Valid session key data types.

The following table lists the valid authentication methods for the MPA and the client:

Table 34. Valid authentication types

Authentication Types | MPA-to-WebSEAL | Client-to-WebSEAL
Basic authentication | Yes | Yes
Forms authentication | Yes | Yes
Certificate | Yes | Not valid
External authentication interface | Yes | Not valid

The authentication method used by the MPA to WebSEAL must be distinct from the authentication method used by the client to WebSEAL. As an example, if the MPA uses basic authentication, the client must use forms authentication.

Certificates and external authentication interface authentication methods are not valid for use by the client.

Normally, if forms authentication is enabled for a particular transport, basic authentication is automatically disabled for that transport. If MPA support is enabled, this restriction is removed. The MPA is then allowed to log in, for example, with forms and clients to log in with basic authentication over the same transport.

Parent topic: Multiplexing proxy agents

Authentication process flow for MPA and multiple clients Authentication process flow for MPA and multiple clients webseal-mpa-servers groupMPAmultiple clientsauthenticationprocess flowmultiple clientsauthentication process flowMPAThe WebSEAL administrator performs the following preliminary configuration: Enable support for multiplexing proxy agents.Create a Security Access Manager account for the specific MPA gateway.Add this MPA account to the webseal-mpa-servers group.Clients connect to the MPA gateway.The gateway translates the request to an HTTP request.The gateway authenticates the client.The gateway establishes a connection with WebSEAL with the client request.The MPA authenticates to WebSEAL (using a method distinct from the client) and an identity is derived for the MPA (which already has a WebSEAL account).WebSEAL verifies the MPA’s membership in the webseal-mpa-servers group.A credential is built for the MPA and flagged as a special MPA type in the cache. Although this MPA credential accompanies each future client request, it is not used for authorization checks on these requests.Now WebSEAL needs to further identify the owner of the request. The MPA is able to distinguish the multiple clients for proper routing of login prompts.The client logs in and authenticates using a method distinct from the authentication type used for the MPA.WebSEAL builds a credential from the client authentication data.Session data type used by each client must be distinct from the session data type used by the MPA.The authorization service permits or denies access to protected objects based on the user credential and the object’s ACL permissions.Multiplexing proxy agents

Authentication process flow for MPA and multiple clients

The WebSEAL administrator performs the following preliminary configuration:

Enable support for multiplexing proxy agents.

Create a Security Access Manager account for the specific MPA gateway.

Add this MPA account to the webseal-mpa-servers group.

Clients connect to the MPA gateway.

The gateway translates the request to an HTTP request.

The gateway authenticates the client.

The gateway establishes a connection with WebSEAL with the client request.

The MPA authenticates to WebSEAL (using a method distinct from the client) and an identity is derived for the MPA (which already has a WebSEAL account).

WebSEAL verifies the MPA’s membership in the webseal-mpa-servers group.

A credential is built for the MPA and flagged as a special MPA type in the cache.

Although this MPA credential accompanies each future client request, it is not used for authorization checks on these requests.

Now WebSEAL needs to further identify the owner of the request.

The MPA is able to distinguish the multiple clients for proper routing of login prompts.

The client logs in and authenticates using a method distinct from the authentication type used for the MPA.

WebSEAL builds a credential from the client authentication data.

Session data type used by each client must be distinct from the session data type used by the MPA.

The authorization service permits or denies access to protected objects based on the user credential and the object’s ACL permissions.

Parent topic: Multiplexing proxy agents

Enabling and disabling MPA authentication Enabling and disabling MPA authentication mpa stanza entryMPAauthenticationenablingdisablingThe mpa stanza entry, located in the [mpa] stanza of the WebSEAL configuration file, enables and disables MPA authentication: To enable the MPA authentication method, enter "yes".To disable the MPA authentication method, enter "no".[mpa] mpa = yesMultiplexing proxy agents

Enabling and disabling MPA authentication

About this task

The mpa stanza entry, located in the [mpa] stanza of the WebSEAL configuration file, enables and disables MPA authentication:

Procedure

To enable the MPA authentication method, enter "yes".

To disable the MPA authentication method, enter "no".

Example

[mpa]
mpa = yes

Parent topic: Multiplexing proxy agents

Creation of a user account for the MPA Creation of a user account for the MPA MPAcreating user accountsuser accountscreationsMPASee the Administering Security Access Manager Base administration information to learn how to create an account.Multiplexing proxy agents

Creation of a user account for the MPA

See the Administering Security Access Manager Base administration information to learn how to create an account.

Parent topic: Multiplexing proxy agents

Addition of the MPA account to the webseal-mpa-servers group Addition of the MPA account to the webseal-mpa-servers group webseal-mpa-servers groupwebseal-mpa-servers groupMPAaccount additionRefer to the Configuring topics in the Knowledge Center for information on managing groups.Multiplexing proxy agents

Addition of the MPA account to the webseal-mpa-servers group

Refer to the Configuring topics in the Knowledge Center for information on managing groups.

Parent topic: Multiplexing proxy agents

MPA authentication limitations MPA authentication limitations MPAauthenticationlimitationsauthentication limitationsMPASecurity Access Manager supports only one MPA per WebSEAL server.MPA authentication is not supported with step-up authentication configuration.MPA is not supported with use-same-session = yesMultiplexing proxy agents

MPA authentication limitations

Security Access Manager supports only one MPA per WebSEAL server.

MPA authentication is not supported with step-up authentication configuration.

MPA is not supported with use-same-session = yes

Parent topic: Multiplexing proxy agents

Switch user authenticationSwitch user authenticationauthenticationswitch usersuser switchingThis section contains the following topics:Advanced authentication methodsMultiplexing proxy agentsReauthenticationAuthentication strength policy (step-up)External authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords. Overview of the switch user functionConfiguration of switch user authenticationUsing switch userAdditional switch user feature support

Switch user authentication

This section contains the following topics:

Overview of the switch user function

Configuration of switch user authentication

Using switch user

Additional switch user feature support

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Reauthentication

Authentication strength policy (step-up)

External authentication interface

Client Certificate User Mapping

Authenticated User Mapping

External user mapping

Password strength

Overview of the switch user functionOverview of the switch user functionswitch useroverviewfunctionalityswitch usersThe WebSEAL switch user function allows administrators to assume the identity of a user who is a member of the Security Access Manager secure domain. The ability to assume a user's identity can help an administrator in a Help Desk environment to troubleshoot and diagnose problems. Switch user can also be used to test a user's access to resources and to perform application integration testing.The switch user implementation is similar to the su command in UNIX environments. In the WebSEAL environment, the administrator acquires the user's credentials and interacts with resources and back-end applications with exactly the same abilities as the actual user. The administrator uses a special HTML form to supply switch user information. WebSEAL processes the form and calls a special authentication mechanism that returns the specified user's credential without the requirement of knowing the user's password.The following sequence describes the switch user process flow:su-admins groupswitch usersu-admins groupAn administrator authenticates to WebSEAL. WebSEAL establishes a session for the administrator, and creates an entry for the administrator in the WebSEAL session cache. The session cache entry contains a cache data structure. This data structure stores the administrator's credential. During the switch user process flow, the cache data will be manipulated. For more information on WebSEAL session caches, see WebSEAL session cache structure.The administrator requests a pre-configured switch user HTML form, and completes the form. On the form, the administrator specifies: The name of the user identity that the administrator needs to assume.A destination URL.An authentication method.This action results in a POST request being sent to /pkmssu.form. The contents of the switch user HTML form can be modified before making it available for use by WebSEAL. See Configuring the switch user HTML formWebSEAL provides a default HTML form that the administrator accesses to use the switch user function. The default form can be used without modification. Optionally, you can edit the form for customized appearance and functionality.. You can also extend the capabilities of the form. See Designing additional input forms. The pkmssu.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.WebSEAL determines whether to allow the switch user request by performing the following checks: WebSEAL examines the membership of the Security Access Manager su-admins group to determine if the administrator has permission to invoke the switch user function. Administrators requesting use of switch user authentication must be members of the su-admins group. Membership in this group must be configured before switch user can be used. For more information, see Configuring user access.WebSEAL examines the membership of the Security Access Manager su-adminssecuritygroupsu-excluded groups to ensure that the user identity supplied in the switch user form is not a member of one of these groups. User identities that belong to any of these groups cannot be accessed by the switch user function. The WebSEAL administrator must configure memberships in these groups before administrators use the switch user function. For configuration instructions and more information on these groups, see Configuring user accessWhen WebSEAL decides to allow the switch user request, WebSEAL calls the appropriate switch user module to perform the special switch user authentication. WebSEAL supports a variety of authentication mechanisms. Each authentication mechanism has a corresponding switch user authentication mechanism. WebSEAL provides built-in modules that contain the special switch user function. When authentication of the designated user succeeds, the switch user module returns a valid credential for the user—without requiring the user password for input.WebSEAL manipulates the contents of the appropriate entry in the WebSEAL session cache by: Removing the administrator's WebSEAL session cache data and storing it in a separate location.Inserting the switched-to user's cache data, including the user's credential, in place of the administrator's cache data. Swapping administrator and user cache data during switch userSwapping administrator and user cache data during switch userWebSEAL sends a redirect to the browser for the destination URL supplied in the switch user form. The request is processed normally, using the user's credential.The administrator can continue to make other requests. All authorization decisions for these requests are based on the credential of the user. When using switch user functionality, administrators might need to establish and manage sessions with additional applications. These sessions need to be established using the identity of the new user. To enable this, the new user credential also contains a new User Session ID. This User Session ID is used, for example, when troubleshooting the user's ability to access and use additional Web resources. For more information on WebSEAL session caches, see WebSEAL session cache configuration and WebSEAL session cache structure.The administrator ends the switch user session using the standard Security Access Manager /pkmslogout utility. Upon successful log out: The user's cache data is deleted.The administrator's original cache data (and credential) is restored.The administrator is returned to the original page from which the switch user form was requested. The authorization service uses the original credential of the administrator for all subsequent requests.Switch user authentication

Overview of the switch user function

The WebSEAL switch user function allows administrators to assume the identity of a user who is a member of the Security Access Manager secure domain. The ability to assume a user's identity can help an administrator in a Help Desk environment to troubleshoot and diagnose problems. Switch user can also be used to test a user's access to resources and to perform application integration testing.

The switch user implementation is similar to the su command in UNIX environments. In the WebSEAL environment, the administrator acquires the user's credentials and interacts with resources and back-end applications with exactly the same abilities as the actual user.

The administrator uses a special HTML form to supply switch user information. WebSEAL processes the form and calls a special authentication mechanism that returns the specified user's credential without the requirement of knowing the user's password.

The following sequence describes the switch user process flow:

An administrator authenticates to WebSEAL. WebSEAL establishes a session for the administrator, and creates an entry for the administrator in the WebSEAL session cache.

The session cache entry contains a cache data structure. This data structure stores the administrator's credential. During the switch user process flow, the cache data will be manipulated.

For more information on WebSEAL session caches, see WebSEAL session cache structure.

The administrator requests a pre-configured switch user HTML form, and completes the form. On the form, the administrator specifies:

The name of the user identity that the administrator needs to assume.

A destination URL.

An authentication method.

This action results in a POST request being sent to /pkmssu.form.

The contents of the switch user HTML form can be modified before making it available for use by WebSEAL. See Configuring the switch user HTML form.

You can also extend the capabilities of the form. See Designing additional input forms.

Note: The pkmssu.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

WebSEAL determines whether to allow the switch user request by performing the following checks:

WebSEAL examines the membership of the Security Access Manager su-admins group to determine if the administrator has permission to invoke the switch user function.

Administrators requesting use of switch user authentication must be members of the su-admins group. Membership in this group must be configured before switch user can be used. For more information, see Configuring user access.

WebSEAL examines the membership of the Security Access Manager su-admins > securitygroup > su-excluded groups to ensure that the user identity supplied in the switch user form is not a member of one of these groups.

User identities that belong to any of these groups cannot be accessed by the switch user function. The WebSEAL administrator must configure memberships in these groups before administrators use the switch user function. For configuration instructions and more information on these groups, see Configuring user access

When WebSEAL decides to allow the switch user request, WebSEAL calls the appropriate switch user module to perform the special switch user authentication.

WebSEAL supports a variety of authentication mechanisms. Each authentication mechanism has a corresponding switch user authentication mechanism. WebSEAL provides built-in modules that contain the special switch user function.

When authentication of the designated user succeeds, the switch user module returns a valid credential for the user—without requiring the user password for input.

WebSEAL manipulates the contents of the appropriate entry in the WebSEAL session cache by:

Removing the administrator's WebSEAL session cache data and storing it in a separate location.

Inserting the switched-to user's cache data, including the user's credential, in place of the administrator's cache data.

Figure 16. Swapping administrator and user cache data during switch user

WebSEAL sends a redirect to the browser for the destination URL supplied in the switch user form.

The request is processed normally, using the user's credential.

The administrator can continue to make other requests. All authorization decisions for these requests are based on the credential of the user.

When using switch user functionality, administrators might need to establish and manage sessions with additional applications. These sessions need to be established using the identity of the new user. To enable this, the new user credential also contains a new User Session ID. This User Session ID is used, for example, when troubleshooting the user's ability to access and use additional Web resources.

For more information on WebSEAL session caches, see WebSEAL session cache configuration and WebSEAL session cache structure.

The administrator ends the switch user session using the standard Security Access Manager /pkmslogout utility. Upon successful log out:

The user's cache data is deleted.

The administrator's original cache data (and credential) is restored.

The administrator is returned to the original page from which the switch user form was requested.

The authorization service uses the original credential of the administrator for all subsequent requests.

Parent topic: Switch user authentication

Configuration of switch user authenticationConfiguration of switch user authenticationswitch usersconfigurationauthenticationswitch userThe WebSEAL administrator must complete several configuration steps before administrators can use the switch user functionality. To configure switch user, complete the instructions in each of the following sections:Switch user authenticationConfiguring user accessConfiguring the switch user HTML formWebSEAL provides a default HTML form that the administrator accesses to use the switch user function. The default form can be used without modification. Optionally, you can edit the form for customized appearance and functionality.Designing additional input formsStopping and restarting WebSEAL

Configuration of switch user authentication

The WebSEAL administrator must complete several configuration steps before administrators can use the switch user functionality. To configure switch user, complete the instructions in each of the following sections:

Configuring user access

Configuring the switch user HTML form
WebSEAL provides a default HTML form that the administrator accesses to use the switch user function. The default form can be used without modification. Optionally, you can edit the form for customized appearance and functionality.

Designing additional input forms

Stopping and restarting WebSEAL

Parent topic: Switch user authentication

Configuring user accessConfiguring user accessswitch usersu-excluded groupsecuritygroupsu-admins groupexclude userssu-admins groupsu-excluded groupsecuritygroup During WebSEAL installation, the WebSEAL configuration process automatically creates several groups for use by the switch user functionality. The WebSEAL administrator controls switch user capability by adding users to the groups. To configure user access, complete the following steps:Add users to the su-admins group.To use switch user function, a user must be a member of a special administrative group called su-admins. This group is automatically created by default during installation of a WebSEAL server. There are no users in this group by default. The WebSEAL administrator must manually add users to this group. Typically, only administrative users are added to this group.Users who have been granted membership in su-admins can switch user to most other user identities, but cannot switch to the identity of any other user that is also a member of the su-admins group. Therefore, as soon as an administrator is granted switch user privileges by being added to su-admins, the administrator's account is protected from access by any other user that gains switch user privileges. Add users to the su-excluded groupThis group contains the names of users whose identities should not be accessed through the switch user capability. During WebSEAL installation, the WebSEAL configuration process automatically creates this group. There are no users in this group by default. A WebSEAL administrator typically adds to this group the names of users who are not members of the administrative group su-admins, but for whom switch user access should still be blocked When switch user is used, WebSEAL also checks the memberships of the Security Access Manager group called securitygroup. This group contains the name of the Security Access Manager administrative user sec_master, plus a number of WebSEAL processes that must be excluded from access through switch user capability. The securitygroup group is automatically created by default during installation of a WebSEAL server. The following identities are automatically added to this group during installation: sec_master — the Security Access Manager administratoracld — the Security Access Manager authorization server daemonwebseald — the WebSEAL daemon WebSEAL administrators should not add any users to the securitygroup group. To control user access to switch user, use either su-admins or su-excluded.Configuration of switch user authentication

Configuring user access

About this task

During WebSEAL installation, the WebSEAL configuration process automatically creates several groups for use by the switch user functionality. The WebSEAL administrator controls switch user capability by adding users to the groups.

To configure user access, complete the following steps:

Procedure

Add users to the su-admins group.
To use switch user function, a user must be a member of a special administrative group called su-admins. This group is automatically created by default during installation of a WebSEAL server. There are no users in this group by default. The WebSEAL administrator must manually add users to this group. Typically, only administrative users are added to this group.

Users who have been granted membership in su-admins can switch user to most other user identities, but cannot switch to the identity of any other user that is also a member of the su-admins group. Therefore, as soon as an administrator is granted switch user privileges by being added to su-admins, the administrator's account is protected from access by any other user that gains switch user privileges.

Add users to the su-excluded group
This group contains the names of users whose identities should not be accessed through the switch user capability. During WebSEAL installation, the WebSEAL configuration process automatically creates this group. There are no users in this group by default. A WebSEAL administrator typically adds to this group the names of users who are not members of the administrative group su-admins, but for whom switch user access should still be blocked

Results

When switch user is used, WebSEAL also checks the memberships of the Security Access Manager group called securitygroup. This group contains the name of the Security Access Manager administrative user sec_master, plus a number of WebSEAL processes that must be excluded from access through switch user capability.

The securitygroup group is automatically created by default during installation of a WebSEAL server. The following identities are automatically added to this group during installation:

sec_master — the Security Access Manager administrator

acld — the Security Access Manager authorization server daemon

webseald — the WebSEAL daemon

WebSEAL administrators should not add any users to the securitygroup group. To control user access to switch user, use either su-admins or su-excluded.

Parent topic: Configuration of switch user authentication

Configuring the switch user HTML formConfiguring the switch user HTML formWebSEAL provides a default HTML form that the administrator accesses to use the switch user function. The default form can be used without modification. Optionally, you can edit the form for customized appearance and functionality.HTMLswitch userswitch userHTML formserver-root stanza entryswitch uservalid authentication methods This step is optional. The default form is named switchuser.html. You can modify the name of this file.You can use the LMI to access this file in the management/lang directory. The value of the lang directory is specific to the locale. For example, the lang directory for a US English locale is called "C". Form contents The form contains requests for: User name The name of the user whose credentials the administrator wants to access.Destination URL This page displays after a successful switch user operation.Authentication method The authentication method stanza entries specify which authentication mechanism WebSEAL uses to build the user credential. Each of these entries is required. WebSEAL verifies that all required data is present in the submitted form. If data is missing, the form is returned to the administrator with a descriptive message. When all required data is present, WebSEAL submits data from the switch user form data to the /pkmssu.form action URL. Only members of the su-admins group can invoke the form. An ACL is not required on this file. WebSEAL performs an internally hardcoded group membership check. WebSEAL returns a 404 "Not Found" error when the group membership check fails. Customizing the HTML form To customize the switch user form, open the form for editing, and complete the following steps:Specify the location and contents of the destination URL. You can configure this URL as hidden input, which contains an appropriate home page or a successful switch user confirmation page.Specify the authentication methods. You can configure this field as hidden input. Valid values for the authentication method include:su-ba su-forms su-certificate su-http-request su-cdssoThe methods in this list map directly to authentication mechanisms specified in the WebSEAL configuration file. Note, however, that the su-basu-forms methods both map to the su-password authentication mechanism. Both basic authentication (ba) and forms authentication (forms) use the su-password authentication module. Note that a WebSEAL deployment can support basic authentication without supporting forms authentication. Therefore separate configuration values are maintained for each authentication type (su-basu-forms). Configuration of switch user authentication

Configuring the switch user HTML form

WebSEAL provides a default HTML form that the administrator accesses to use the switch user function. The default form can be used without modification. Optionally, you can edit the form for customized appearance and functionality.

About this task

This step is optional.

The default form is named switchuser.html. You can modify the name of this file.

You can use the LMI to access this file in the management/lang directory. The value of the lang directory is specific to the locale. For example, the lang directory for a US English locale is called "C".

Form contents

The form contains requests for:

User name

The name of the user whose credentials the administrator wants to access.

Destination URL

This page displays after a successful switch user operation.

Authentication method

The authentication method stanza entries specify which authentication mechanism WebSEAL uses to build the user credential.

Each of these entries is required. WebSEAL verifies that all required data is present in the submitted form. If data is missing, the form is returned to the administrator with a descriptive message. When all required data is present, WebSEAL submits data from the switch user form data to the /pkmssu.form action URL.

Note: Only members of the su-admins group can invoke the form. An ACL is not required on this file. WebSEAL performs an internally hardcoded group membership check. WebSEAL returns a 404 "Not Found" error when the group membership check fails.

Customizing the HTML form

To customize the switch user form, open the form for editing, and complete the following steps:

Procedure

Specify the location and contents of the destination URL.
You can configure this URL as hidden input, which contains an appropriate home page or a successful switch user confirmation page.

Specify the authentication methods.
You can configure this field as hidden input. Valid values for the authentication method include:
su-ba su-forms su-certificate su-http-request su-cdsso
The methods in this list map directly to authentication mechanisms specified in the WebSEAL configuration file. Note, however, that the su-ba > su-forms methods both map to the su-password authentication mechanism. Both basic authentication (ba) and forms authentication (forms) use the su-password authentication module. Note that a WebSEAL deployment can support basic authentication without supporting forms authentication. Therefore separate configuration values are maintained for each authentication type (su-ba > su-forms).

Parent topic: Configuration of switch user authentication

Designing additional input formsDesigning additional input formsinputsformsdesigning input forms This step is optional. You can design additional forms to validate or process data to be submitted to /pkmssu.form. These forms can be used to assist the administrator by populating some of the entries on the switch user form. Some examples are: An administrator might have chosen to have different destination URLs, to be accessed based on the user identity. Another form could be written to build and present a list of these URLs, from which the administrator could select the appropriate entry.A form could be developed to call another program, such as a CGI script, to supply a list of user identities for whom switch user is allowed. This list could help administrators determine if access to a user identity through switch user is allowed.A form could be developed to display a list of user identities for whom switch user is not allowed. This list would be based on the memberships of the su-excluded and securitygroup groups.Configuration of switch user authentication

Designing additional input forms

About this task

This step is optional.

You can design additional forms to validate or process data to be submitted to /pkmssu.form. These forms can be used to assist the administrator by populating some of the entries on the switch user form.

Some examples are:

An administrator might have chosen to have different destination URLs, to be accessed based on the user identity. Another form could be written to build and present a list of these URLs, from which the administrator could select the appropriate entry.

A form could be developed to call another program, such as a CGI script, to supply a list of user identities for whom switch user is allowed. This list could help administrators determine if access to a user identity through switch user is allowed.

A form could be developed to display a list of user identities for whom switch user is not allowed. This list would be based on the memberships of the su-excluded and securitygroup groups.

Parent topic: Configuration of switch user authentication

Stopping and restarting WebSEALStopping and restarting WebSEALWebSEALstoppingrestarting To activate the new configuration changes you must stop and restart WebSEAL. This enables WebSEAL to use the new values that were specified to the WebSEAL configuration file in Configuring user access. The methods for stopping and restarting the WebSEAL server are described in WebSEAL instance managementYou can use the Reverse Proxy management page of the LMI to manage the WebSEAL instances on the appliance..Configuration of switch user authentication

Stopping and restarting WebSEAL

About this task

To activate the new configuration changes you must stop and restart WebSEAL. This enables WebSEAL to use the new values that were specified to the WebSEAL configuration file in Configuring user access.

The methods for stopping and restarting the WebSEAL server are described in WebSEAL instance management.

Parent topic: Configuration of switch user authentication

Using switch userUsing switch userswitch userusage When the configuration steps in the previous section have been completed, WebSEAL administrators can use the switch user function. To use the switch user function, complete the following steps:Log in as a user who has permission to access the switch user function. This function is usually accessed by administrators. The user must be a member of the su-admins group.Request the switch user HTML form. The default file name is switchuser.html. For information about this file, see Configuring the switch user HTML formWebSEAL provides a default HTML form that the administrator accesses to use the switch user function. The default form can be used without modification. Optionally, you can edit the form for customized appearance and functionality..On the form, specify: The name of the user identity that you want to assume.A destination URL.An authentication method.This action results in a POST request being sent to /pkmssu.form. WebSEAL sends a redirect to the browser for the destination URL supplied in the switch user form. The request is processed using the user's credential, and the URL is accessed. The pkmssu.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it. Make other requests as necessary. All authorization decisions for these requests are based on the credential of the user.When finished, end the switch user session by using the standard Security Access Manager /pkmslogout utility. For more information on how the switch user function works, see Overview of the switch user function.Switch user authentication

Using switch user

About this task

When the configuration steps in the previous section have been completed, WebSEAL administrators can use the switch user function.

To use the switch user function, complete the following steps:

Procedure

Log in as a user who has permission to access the switch user function.

This function is usually accessed by administrators. The user must be a member of the su-admins group.

Request the switch user HTML form.

The default file name is switchuser.html. For information about this file, see Configuring the switch user HTML form.

On the form, specify:

The name of the user identity that you want to assume.

A destination URL.

An authentication method.

This action results in a POST request being sent to /pkmssu.form. WebSEAL sends a redirect to the browser for the destination URL supplied in the switch user form. The request is processed using the user's credential, and the URL is accessed.

Note: The pkmssu.form management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

Make other requests as necessary.

All authorization decisions for these requests are based on the credential of the user.

When finished, end the switch user session by using the standard Security Access Manager /pkmslogout utility.

Results

For more information on how the switch user function works, see Overview of the switch user function.

Parent topic: Switch user authentication

Additional switch user feature supportAdditional switch user feature supportswitch userfeature supportfeature supportThis section describes switch user support for additional features such as reauthentication, user session management, and auditing.Switch user authenticationSupport for session cache timeoutSupport for reauthenticationWebSEAL reauthentication functionality is recognized by the switch user operation. Support for user session managementThe switch user operation supports user session management.Support for tag-valueSupport for auditing

Additional switch user feature support

This section describes switch user support for additional features such as reauthentication, user session management, and auditing.

Support for session cache timeout

Support for reauthentication
WebSEAL reauthentication functionality is recognized by the switch user operation.

Support for user session management
The switch user operation supports user session management.

Support for tag-value

Support for auditing

Parent topic: Switch user authentication

Support for session cache timeoutSupport for session cache timeoutsessioncache timeout supporttimeoutsupportThe functionality of the configured WebSEAL session cache inactivity and lifetime timeout values is not affected by the switch user operation. The inactivity and lifetime timers are associated with the administrator's session cache entry and not the cache data that changes during a switch user operation.The inactivity timer continues to be reset while the administrator performs requests as the "switched-to" user. When the administrator ends the switch user session, the inactivity is still valid for the re-established administrator session.The lifetime value is not extended because of a switch user operation. It is possible for the lifetime timeout of the session cache entry to expire during a switch user operation. If this timeout occurs, the session cache is deleted and the administrator is logged off. The administrator must reauthenticate and begin the switch user operation again.Additional switch user feature support

Support for session cache timeout

The functionality of the configured WebSEAL session cache inactivity and lifetime timeout values is not affected by the switch user operation. The inactivity and lifetime timers are associated with the administrator's session cache entry and not the cache data that changes during a switch user operation.

The inactivity timer continues to be reset while the administrator performs requests as the "switched-to" user. When the administrator ends the switch user session, the inactivity is still valid for the re-established administrator session.

The lifetime value is not extended because of a switch user operation. It is possible for the lifetime timeout of the session cache entry to expire during a switch user operation. If this timeout occurs, the session cache is deleted and the administrator is logged off. The administrator must reauthenticate and begin the switch user operation again.

Parent topic: Additional switch user feature support

Support for reauthenticationSupport for reauthenticationWebSEAL reauthentication functionality is recognized by the switch user operation. reauthenticationsupportsupportreauthenticationIf reauthentication is required during a switch user operation, the administrator must authenticate as the "switched-to" user.The administrator must know the "switched-to" user's password to successfully reauthenticate.Additional switch user feature support

Support for reauthentication

WebSEAL reauthentication functionality is recognized by the switch user operation.

If reauthentication is required during a switch user operation, the administrator must authenticate as the "switched-to" user.

Note: The administrator must know the "switched-to" user's password to successfully reauthenticate.

Parent topic: Additional switch user feature support

Support for user session managementSupport for user session managementThe switch user operation supports user session management.user sessionsmanagement supportsupportuser session managementThe administrator has a unique User Session ID. Additionally, during a switch user operation, a unique User Session ID exists for the "switched-to" user. The terminate single user sessions task and terminate all user sessions task perform as expected.Additional switch user feature support

Support for user session management

The switch user operation supports user session management.

The administrator has a unique User Session ID. Additionally, during a switch user operation, a unique User Session ID exists for the "switched-to" user. The terminate single user sessions task and terminate all user sessions task perform as expected.

Parent topic: Additional switch user feature support

Support for tag-valueSupport for tag-valuetag-valuesupportsupporttag-valueThe tag-value capability often used by custom authentication modules is recognized and supported by the switch user functionality.Additional switch user feature support

Support for tag-value

The tag-value capability often used by custom authentication modules is recognized and supported by the switch user functionality.

Parent topic: Additional switch user feature support

Support for auditingSupport for auditingauditingsupportsupportauditingIt is possible to audit the administrator during a switch user operation. The switch user functionality adds an extended attribute to the "switch-to" user credential that identifies the administrator. su-admin extended attributeswitch usersu-admin extended attributeThe extended attribute, as stored in the credential, is called tagvalue_su-admin:tagvalue_su-admin = su-admin-nameThis extended attribute is available to any auditing mechanism.Additional switch user feature support

Support for auditing

It is possible to audit the administrator during a switch user operation. The switch user functionality adds an extended attribute to the "switch-to" user credential that identifies the administrator. The extended attribute, as stored in the credential, is called tagvalue_su-admin:

tagvalue_su-admin = su-admin-name

This extended attribute is available to any auditing mechanism.

Parent topic: Additional switch user feature support

ReauthenticationReauthenticationreauthenticationbased on security (POP) policybased on session inactivityauthenticationreauthentication (security policy)reauthentication (session inactivity)This section contains the following topics:Advanced authentication methodsMultiplexing proxy agentsSwitch user authenticationAuthentication strength policy (step-up)External authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords. Reauthentication conceptsSecurity Access Manager WebSEAL can force a user to perform an additional login (reauthentication) to ensure that a user who is accessing a protected resource is the same person who initially authenticated at the start of the session. Forced reauthentication provides additional protection for sensitive resources in the secure domain.Reauthentication based on security policyReauthentication POP: creating and applyingReauthentication based on session inactivityEnabling of reauthentication based on session inactivityResetting of the session cache entry lifetime valueExtension of the session cache entry lifetime valuePrevention of session removal when the session lifetime expiresRemoval of a user session at login failure policy limitCustomization of login forms for reauthenticationWebSEAL supports reauthentication for both forms authentication methods.

Reauthentication

This section contains the following topics:

Reauthentication concepts
Security Access Manager WebSEAL can force a user to perform an additional login (reauthentication) to ensure that a user who is accessing a protected resource is the same person who initially authenticated at the start of the session. Forced reauthentication provides additional protection for sensitive resources in the secure domain.

Reauthentication based on security policy

Reauthentication POP: creating and applying

Reauthentication based on session inactivity

Enabling of reauthentication based on session inactivity

Resetting of the session cache entry lifetime value

Extension of the session cache entry lifetime value

Prevention of session removal when the session lifetime expires

Removal of a user session at login failure policy limit

Customization of login forms for reauthentication
WebSEAL supports reauthentication for both forms authentication methods.

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Switch user authentication

Authentication strength policy (step-up)

External authentication interface

Client Certificate User Mapping

Authenticated User Mapping

External user mapping

Password strength

Reauthentication conceptsReauthentication conceptsSecurity Access Manager WebSEAL can force a user to perform an additional login (reauthentication) to ensure that a user who is accessing a protected resource is the same person who initially authenticated at the start of the session. Forced reauthentication provides additional protection for sensitive resources in the secure domain.reauthenticationconceptsconceptsreauthenticationReauthentication can be activated by:A protected object policy (POP) on the protected object.Expiration of the inactivity timeout value of a WebSEAL session cache entry.Reauthentication is supported by the following WebSEAL authentication methods:Forms (user name and password) authenticationExternal authentication interfaceIn addition, a custom user name and password module can be written to support reauthentication.Reauthentication assumes that the user has initially logged in to the secure domain and that a valid session (credential) exists for the user. The reauth-at-any-level option in the [reauthentication] stanza of the WebSEAL configuration file determines how WebSEAL handles a reauthentication operation: If the value for this option is no, the user must login using the same identity, authentication method, and authentication level that generated the existing credential. WebSEAL preserves the user's original session information, including the credential, during reauthentication. The credential is not replaced during reauthentication.If the value for this option is yes, the user must use the same identity but can be authenticated using a different authentication method or level from that which is currently held by the user. In this case, the user's credential can change one or more times during the lifetime of the user's session, and the user's credential is updated upon successful reauthentication. Note that this might have several consequences that must be carefully considered. If the credential changes during the course of an established session, then operations that utilize credential attributes, such as authorization decisions and auditing, might return different results mid-session. Care must be taken to ensure a consistent user experience and to account for these types of changes in audit records.During reauthentication, WebSEAL also caches the request that prompted the reauthentication. Upon successful reauthentication, the cached data is used to rebuild the request. See Server-side request caching.If reauthentication fails, WebSEAL returns the login prompt again. If reauthentication succeeds, but the ACL check fails for that resource, a 403 error ("Forbidden") is returned and the user is denied access to the requested resource. In either case, the user is not logged off (the exception to this outcome is when the max-login-failures policy limit has been reached). Using a still valid credential, the user can terminate the reauthentication process (by requesting another URL) and still participate in the secure domain by accessing other resources that do not require reauthentication.A configuration option exists that requires WebSEAL to remove the user's session cache entry and log the user out when the reauthentication attempts reach the max-login-failures policy limit.Another configuration option is available to reset the lifetime timer of WebSEAL session cache entries. In addition, a grace period can be configured to allow sufficient time for the reauthentication process to complete before the lifetime timeout of a session cache entry expires.Reauthentication

Reauthentication concepts

Security Access Manager WebSEAL can force a user to perform an additional login (reauthentication) to ensure that a user who is accessing a protected resource is the same person who initially authenticated at the start of the session. Forced reauthentication provides additional protection for sensitive resources in the secure domain.

Reauthentication can be activated by:

A protected object policy (POP) on the protected object.

Expiration of the inactivity timeout value of a WebSEAL session cache entry.

Reauthentication is supported by the following WebSEAL authentication methods:

Forms (user name and password) authentication

External authentication interface

In addition, a custom user name and password module can be written to support reauthentication.

Reauthentication assumes that the user has initially logged in to the secure domain and that a valid session (credential) exists for the user. The reauth-at-any-level option in the [reauthentication] stanza of the WebSEAL configuration file determines how WebSEAL handles a reauthentication operation:

If the value for this option is no, the user must login using the same identity, authentication method, and authentication level that generated the existing credential. WebSEAL preserves the user's original session information, including the credential, during reauthentication. The credential is not replaced during reauthentication.

If the value for this option is yes, the user must use the same identity but can be authenticated using a different authentication method or level from that which is currently held by the user. In this case, the user's credential can change one or more times during the lifetime of the user's session, and the user's credential is updated upon successful reauthentication. Note that this might have several consequences that must be carefully considered. If the credential changes during the course of an established session, then operations that utilize credential attributes, such as authorization decisions and auditing, might return different results mid-session. Care must be taken to ensure a consistent user experience and to account for these types of changes in audit records.

During reauthentication, WebSEAL also caches the request that prompted the reauthentication. Upon successful reauthentication, the cached data is used to rebuild the request. See Server-side request caching.

If reauthentication fails, WebSEAL returns the login prompt again. If reauthentication succeeds, but the ACL check fails for that resource, a 403 error ("Forbidden") is returned and the user is denied access to the requested resource.

In either case, the user is not logged off (the exception to this outcome is when the max-login-failures policy limit has been reached). Using a still valid credential, the user can terminate the reauthentication process (by requesting another URL) and still participate in the secure domain by accessing other resources that do not require reauthentication.

A configuration option exists that requires WebSEAL to remove the user's session cache entry and log the user out when the reauthentication attempts reach the max-login-failures policy limit.

Another configuration option is available to reset the lifetime timer of WebSEAL session cache entries. In addition, a grace period can be configured to allow sufficient time for the reauthentication process to complete before the lifetime timeout of a session cache entry expires.

Parent topic: Reauthentication

Reauthentication based on security policyReauthentication based on security policysecuritypoliciesreauthenticationreauthenticationsecurity policyReauthentication based on security policy is activated by a specific extended attribute in a POP that protects the requested resource object. The POP can be directly attached to the object, or the object can inherit the POP conditions from a parent object. Reauthentication

Reauthentication based on security policy

Reauthentication based on security policy is activated by a specific extended attribute in a POP that protects the requested resource object. The POP can be directly attached to the object, or the object can inherit the POP conditions from a parent object.

Parent topic: Reauthentication

Reauthentication POP: creating and applyingReauthentication POP: creating and applyingreauth POP extended attributereauthenticationreauth POP extended attributePOPreauth extended attributeextended attributesreauth (POP extended attribute)Forced reauthentication based on security policy is configured by creating a protected object policy (POP) with a special extended attribute named "reauth". You can attach this POP to any object that requires the extra protection provided by forced reauthentication. Remember that all children of the object with the POP also inherit the POP conditions. Each requested child object requires a separate reauthentication.Use the pdadmin pop create, pdadmin pop modify, and pdadmin pop attach commands to create and apply the reauthentication POP. The following example illustrates creating a POP called "secure" with the reauth extended attribute and attaching it to an object (budget.html):pdadmin> pop create secure pdadmin> pop modify secure set attribute reauth true pdadmin> pop attach /WebSEAL/hostA/junction/budget.html secureAnyone attempting to access budget.html is forced to reauthenticate using the same identity and authentication method that generated the existing credential.If the user requesting the resource is unauthenticated, the POP forces the user to authenticate. No reauthentication is necessary for this resource after successful initial login.Details about the pdadmin pop commands can be found in the Command reference topics in the Knowledge Center. Reauthentication

Reauthentication POP: creating and applying

Forced reauthentication based on security policy is configured by creating a protected object policy (POP) with a special extended attribute named "reauth". You can attach this POP to any object that requires the extra protection provided by forced reauthentication.

Remember that all children of the object with the POP also inherit the POP conditions. Each requested child object requires a separate reauthentication.

Use the pdadmin pop create, pdadmin pop modify, and pdadmin pop attach commands to create and apply the reauthentication POP. The following example illustrates creating a POP called "secure" with the reauth extended attribute and attaching it to an object (budget.html):

pdadmin> pop create secure
pdadmin> pop modify secure set attribute reauth true
pdadmin> pop attach /WebSEAL/hostA/junction/budget.html secure

Anyone attempting to access budget.html is forced to reauthenticate using the same identity and authentication method that generated the existing credential.

If the user requesting the resource is unauthenticated, the POP forces the user to authenticate. No reauthentication is necessary for this resource after successful initial login.

Details about the pdadmin pop commands can be found in the Command reference topics in the Knowledge Center.

Parent topic: Reauthentication

Reauthentication based on session inactivityReauthentication based on session inactivitysession inactivityreauthenticationsession inactivityReauthentication based on session inactivity is enabled by a configuration stanza entry and is activated by the expiration of the inactivity timeout value of a session cache entry. A user's session is normally regulated by a session inactivity value and a session lifetime value. When WebSEAL is configured for reauthentication based on session inactivity, the user's session cache entry is "flagged" whenever the session inactivity timeout value expires. The session cache entry (containing the user credential) is not removed. The user can proceed to access unprotected resources. However, if the user requests a protected resource, WebSEAL sends a login prompt. After successful reauthentication, the inactive session "flag" is removed and the inactivity timer is reset. If reauthentication fails, WebSEAL returns the login prompt again. The session cache entry remains "flagged" and the user can proceed to request unprotected resources until the session cache entry lifetime value expires.Two other conditions can end a user session: the user can explicitly log out or an administrator can terminate a user session. See Terminating user sessions.Reauthentication

Reauthentication based on session inactivity

Reauthentication based on session inactivity is enabled by a configuration stanza entry and is activated by the expiration of the inactivity timeout value of a session cache entry.

A user's session is normally regulated by a session inactivity value and a session lifetime value. When WebSEAL is configured for reauthentication based on session inactivity, the user's session cache entry is "flagged" whenever the session inactivity timeout value expires. The session cache entry (containing the user credential) is not removed. The user can proceed to access unprotected resources. However, if the user requests a protected resource, WebSEAL sends a login prompt. After successful reauthentication, the inactive session "flag" is removed and the inactivity timer is reset.

If reauthentication fails, WebSEAL returns the login prompt again. The session cache entry remains "flagged" and the user can proceed to request unprotected resources until the session cache entry lifetime value expires.

Two other conditions can end a user session: the user can explicitly log out or an administrator can terminate a user session. See Terminating user sessions.

Parent topic: Reauthentication

Enabling of reauthentication based on session inactivityEnabling of reauthentication based on session inactivityreauth-for-inactive stanza entryreauthenticationreauth-for-inactive stanza entryTo configure WebSEAL to "flag" inactive sessions rather than remove them from the session cache, set the value for the reauth-for-inactive stanza entry to yes in the [reauthentication] stanza of the webseald.conf configuration file:[reauthentication] reauth-for-inactive = yesThe default value for this stanza entry is no.For information about enabling reauthentication based on session inactivity for the distributed session cache, see Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. .Reauthentication

Enabling of reauthentication based on session inactivity

To configure WebSEAL to "flag" inactive sessions rather than remove them from the session cache, set the value for the reauth-for-inactive stanza entry to yes in the [reauthentication] stanza of the webseald.conf configuration file:

[reauthentication]
reauth-for-inactive = yes

The default value for this stanza entry is no.

For information about enabling reauthentication based on session inactivity for the distributed session cache, see Adjustment of the last access time update frequency for the distributed session cache.

Parent topic: Reauthentication

Resetting of the session cache entry lifetime valueResetting of the session cache entry lifetime valuereauthenticationreset the session cache entry lifetime valuereauth-reset-lifetime stanza entrytimeoutstanzareauth-reset-lifetime stanzaThe user's session cache entry has a limited lifetime, as specified by the timeout stanza entry in the [session] stanza of the webseald.conf configuration file. The default value, in seconds, is 3600 (1 hour):[session] timeout = 3600Regardless of session activity or inactivity, the session cache entry is removed when the lifetime value is reached, at which point the user is logged off. However, you can configure the lifetime of the session cache entry to be reset whenever reauthentication occurs. With this configuration, the user session no longer has a single maximum lifetime value. Each time reauthentication occurs, the lifetime value of the session cache entry is reset.You can configure session cache entry lifetime reset with the reauth-reset-lifetime stanza entry in the [reauthentication] stanza of the webseald.conf configuration file:[reauthentication] reauth-reset-lifetime = yesThe default value is "no".Reauthentication

Resetting of the session cache entry lifetime value

The user's session cache entry has a limited lifetime, as specified by the timeout stanza entry in the [session] stanza of the webseald.conf configuration file. The default value, in seconds, is 3600 (1 hour):

[session]
timeout = 3600

Regardless of session activity or inactivity, the session cache entry is removed when the lifetime value is reached, at which point the user is logged off.

However, you can configure the lifetime of the session cache entry to be reset whenever reauthentication occurs. With this configuration, the user session no longer has a single maximum lifetime value. Each time reauthentication occurs, the lifetime value of the session cache entry is reset.

You can configure session cache entry lifetime reset with the reauth-reset-lifetime stanza entry in the [reauthentication] stanza of the webseald.conf configuration file:

[reauthentication]
reauth-reset-lifetime = yes

The default value is "no".

Parent topic: Reauthentication

Extension of the session cache entry lifetime valueExtension of the session cache entry lifetime valuereauthenticationextend the session cache entry lifetime valuereauth-extend-lifetime stanza entrysession cachelifetime value extensionreauth-extend-lifetime stanza entryIt is possible for the lifetime value of a session cache entry to expire while the user is performing a reauthentication. This situation occurs under the following conditions:The user requests a resource protected by a reauthentication POPThe user's session cache entry lifetime value is very near expirationThe lifetime of a session cache entry can expire after the reauthentication login form is sent to the user and before the completed login form is returned. When the session cache entry lifetime value expires, the session cache entry is deleted. When the login form is returned to WebSEAL, there is no longer a session for that user. In addition, all cached user request data is lost.You can configure a time extension, or "grace period," for the session cache entry lifetime value if the session cache entry lifetime expires during reauthentication. The reauth-extend-lifetime stanza entry in the [reauthentication] stanza of the webseald.conf configuration file provides this time extension, in seconds. For example (5 minutes):[reauthentication] reauth-extend-lifetime = 300The default value, "0", provides no extension to the session cache entry timeout value. The reauth-extend-lifetime stanza entry applies to users with existing session cache entries and who are required to reauthenticate. For example:Users performing reauthentication resulting from POP security policyUsers performing reauthentication resulting from session cache inactivityUsers performing step-up authenticationThe reauth-extend-lifetime option is intended to be used in conjunction with the reauth-reset-lifetime=yes option.Reauthentication

Extension of the session cache entry lifetime value

It is possible for the lifetime value of a session cache entry to expire while the user is performing a reauthentication. This situation occurs under the following conditions:

The user requests a resource protected by a reauthentication POP

The user's session cache entry lifetime value is very near expiration

The lifetime of a session cache entry can expire after the reauthentication login form is sent to the user and before the completed login form is returned. When the session cache entry lifetime value expires, the session cache entry is deleted. When the login form is returned to WebSEAL, there is no longer a session for that user. In addition, all cached user request data is lost.

You can configure a time extension, or "grace period," for the session cache entry lifetime value if the session cache entry lifetime expires during reauthentication. The reauth-extend-lifetime stanza entry in the [reauthentication] stanza of the webseald.conf configuration file provides this time extension, in seconds. For example (5 minutes):

[reauthentication]
reauth-extend-lifetime = 300

The default value, "0", provides no extension to the session cache entry timeout value.

The reauth-extend-lifetime stanza entry applies to users with existing session cache entries and who are required to reauthenticate. For example:

Users performing reauthentication resulting from POP security policy

Users performing reauthentication resulting from session cache inactivity

Users performing step-up authentication

The reauth-extend-lifetime option is intended to be used in conjunction with the reauth-reset-lifetime=yes option.

Parent topic: Reauthentication

Prevention of session removal when the session lifetime expiresPrevention of session removal when the session lifetime expiresreauthenticationprevent session cache entry removalsession removalpreventionThe session cache entry lifetime value usually determines the maximum session length. It is possible for a user to remain active for the full duration of a session lifetime. When the session lifetime value expires, the session cache entry is normally removed and the user is logged off, regardless of activity. To prevent this sudden session termination, you can configure WebSEAL to allow the user to reauthenticate after the session timeout value has expired. After successful reauthentication, the lifetime value of the session cache entry is reset.WebSEAL allows resetting of the session lifetime value, after it has expired, under the following conditions:Reauthentication based on inactivity policy is enabled (reauth-for-inactive=yes)The session lifetime value (timeout) has expired The time extension ("grace period") for the session lifetime is enabled and set to a reasonable value (for example, reauth-extend-lifetime=300)The user activates the reauthentication prompt by requesting a protected resource before the time extension ("grace period") expires (WebSEAL does not allow repeated additions of the time extension to an end of session lifetime event.)Resetting the session cache lifetime is configured to be true (reauth-reset-lifetime=yes)At the occurrence of a session lifetime expiration, WebSEAL checks the conditions listed above. If all conditions are met, the lifetime timeout is extended by the reauth-extend-lifetime value and the user's session cache entry is "flagged" as extended. The session cache entry (containing the user credential) is not removed and the user can proceed to access unprotected resources. When the user requests a protected resource, WebSEAL prompts the user to reauthenticate.The reauth-extend-lifetime value should be set to a reasonable value so the user has enough time to trigger the reauthentication prompt. Note that if the user does not access a protected object during the "grace period", the reauthentication process is not activated. In this case, it is possible for the reauth-extend-lifetime value to expire, in which case the session cache entry is removed.Typically, however, reauthentication policy is implemented to secure an application that is serving predominantly protected resources. A time extension ("grace period") of 5–10 minutes should be adequate time to allow an active user to trigger the reauthentication process, and therefore reset the session lifetime value.Reauthentication

Prevention of session removal when the session lifetime expires

The session cache entry lifetime value usually determines the maximum session length. It is possible for a user to remain active for the full duration of a session lifetime. When the session lifetime value expires, the session cache entry is normally removed and the user is logged off, regardless of activity.

To prevent this sudden session termination, you can configure WebSEAL to allow the user to reauthenticate after the session timeout value has expired. After successful reauthentication, the lifetime value of the session cache entry is reset.

WebSEAL allows resetting of the session lifetime value, after it has expired, under the following conditions:

Reauthentication based on inactivity policy is enabled (reauth-for-inactive=yes)

The session lifetime value (timeout) has expired

The time extension ("grace period") for the session lifetime is enabled and set to a reasonable value (for example, reauth-extend-lifetime=300)

The user activates the reauthentication prompt by requesting a protected resource before the time extension ("grace period") expires

(WebSEAL does not allow repeated additions of the time extension to an end of session lifetime event.)

Resetting the session cache lifetime is configured to be true (reauth-reset-lifetime=yes)

At the occurrence of a session lifetime expiration, WebSEAL checks the conditions listed above. If all conditions are met, the lifetime timeout is extended by the reauth-extend-lifetime value and the user's session cache entry is "flagged" as extended. The session cache entry (containing the user credential) is not removed and the user can proceed to access unprotected resources. When the user requests a protected resource, WebSEAL prompts the user to reauthenticate.

The reauth-extend-lifetime value should be set to a reasonable value so the user has enough time to trigger the reauthentication prompt. Note that if the user does not access a protected object during the "grace period", the reauthentication process is not activated. In this case, it is possible for the reauth-extend-lifetime value to expire, in which case the session cache entry is removed.

Typically, however, reauthentication policy is implemented to secure an application that is serving predominantly protected resources. A time extension ("grace period") of 5–10 minutes should be adequate time to allow an active user to trigger the reauthentication process, and therefore reset the session lifetime value.

Parent topic: Reauthentication

Removal of a user session at login failure policy limitRemoval of a user session at login failure policy limitreauthenticationremove user's session at login failure policy limituser sessionsremovalIf a reauthentication attempt fails, WebSEAL normally returns the login prompt again. Because the user still has a valid session and credential, the user can terminate the reauthentication process (by requesting another URL) and still participate in the secure domain by accessing other resources that do not require reauthentication.However, the reauthentication process is impacted by the login failure policy (max-login-failures) if the user continues failed attempts to reauthenticate. When the number of failed reauthentication attempts reaches or exceeds the max-login-failures limit, WebSEAL responds according to the terminate-on-reauth-lockout configuration.The terminate-on-reauth-lockout stanza entry is located in the [reauthentication] stanza of the WebSEAL configuration file. The purpose of this stanza entry is to control whether or not the user's session cache entry is completely removed upon reaching the max-login-failures policy limit. The default setting is "yes". When the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is logged out of the original session and the user's session cache entry is removed. For example:[reauthentication] terminate-on-reauth-lockout = yesNow the user no longer has a valid session and credential. Although the user can still access unprotected resources, the user is required to login again for any request made to any protected resource.A value of "no" for the terminate-on-reauth-lockout stanza entry is provided as backward compatibility for versions of WebSEAL prior to version 6.0. [reauthentication] terminate-on-reauth-lockout = noWith the "no" setting, the user is not logged out and the initial login session is still valid. The user can still access other resources that are not protected by a reauth POP.When the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is locked out from accessing that resource as specified by the disable-time-interval policy setting, and notified of the lockout as specified by the late-lockout-notification configuration setting.For both values of terminate-on-reauth-lockout, the specific response to the user is governed by the disable-time-interval and late-lockout-notification settings. If the disable-time-interval policy is set to a number of seconds, the error message indicates that the account is temporarily locked out.If the disable-time-interval policy is set to "disable", the error message indicates that the account has been disabled and that an administrator is required to reset (unlock) the account.For complete details on the login failure policy mechanism, see Login failure policy ("three strikes" login policy).Reauthentication

Removal of a user session at login failure policy limit

If a reauthentication attempt fails, WebSEAL normally returns the login prompt again. Because the user still has a valid session and credential, the user can terminate the reauthentication process (by requesting another URL) and still participate in the secure domain by accessing other resources that do not require reauthentication.

However, the reauthentication process is impacted by the login failure policy (max-login-failures) if the user continues failed attempts to reauthenticate. When the number of failed reauthentication attempts reaches or exceeds the max-login-failures limit, WebSEAL responds according to the terminate-on-reauth-lockout configuration.

The terminate-on-reauth-lockout stanza entry is located in the [reauthentication] stanza of the WebSEAL configuration file. The purpose of this stanza entry is to control whether or not the user's session cache entry is completely removed upon reaching the max-login-failures policy limit.

The default setting is "yes". When the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is logged out of the original session and the user's session cache entry is removed. For example:

[reauthentication]
terminate-on-reauth-lockout = yes

Now the user no longer has a valid session and credential. Although the user can still access unprotected resources, the user is required to login again for any request made to any protected resource.

A value of "no" for the terminate-on-reauth-lockout stanza entry is provided as backward compatibility for versions of WebSEAL prior to version 6.0.

[reauthentication]
terminate-on-reauth-lockout = no

With the "no" setting, the user is not logged out and the initial login session is still valid. The user can still access other resources that are not protected by a reauth POP.

When the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is locked out from accessing that resource as specified by the disable-time-interval policy setting, and notified of the lockout as specified by the late-lockout-notification configuration setting.

For both values of terminate-on-reauth-lockout, the specific response to the user is governed by the disable-time-interval and late-lockout-notification settings.

If the disable-time-interval policy is set to a number of seconds, the error message indicates that the account is temporarily locked out.

If the disable-time-interval policy is set to "disable", the error message indicates that the account has been disabled and that an administrator is required to reset (unlock) the account.

For complete details on the login failure policy mechanism, see Login failure policy ("three strikes" login policy).

Parent topic: Reauthentication

Customization of login forms for reauthenticationCustomization of login forms for reauthenticationWebSEAL supports reauthentication for both forms authentication methods.reauthenticationcustomize login forms for reauthenticationUSERNAME macromacrosHTML server response pagesBy default, forms authentication uses the login.html page to request user name and password information from the client (see Static HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. ). This default login page is also used during reauthentication.It is possible to have the user name field in these login pages automatically filled in during reauthentication by using the USERNAME macro (see Macro resources for customizing HTML response pagesMacros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages. ). The user needs to complete only the password (passcode) field.For example, modify the following line in the login.html page:<TD><INPUT NAME="username" SIZE="15"></TD>to include the USERNAME macro:<TD><INPUT NAME="username" SIZE="15" VALUE="%USERNAME%"></TD>During an initial login (unauthenticated user), the value for the USERNAME macro is empty and the user name text field displayed on the login page appears with the entry "unknown". For a reauthenticating client, the USERNAME macro would contain the value of the client user name. The user name text field on the login page appears with the user's name automatically provided.Reauthentication

Customization of login forms for reauthentication

WebSEAL supports reauthentication for both forms authentication methods.

By default, forms authentication uses the login.html page to request user name and password information from the client (see Static HTML server response pages). This default login page is also used during reauthentication.

It is possible to have the user name field in these login pages automatically filled in during reauthentication by using the USERNAME macro (see Macro resources for customizing HTML response pages). The user needs to complete only the password (passcode) field.

For example, modify the following line in the login.html page:

<TD><INPUT NAME="username" SIZE="15"></TD>

to include the USERNAME macro:

<TD><INPUT NAME="username" SIZE="15" VALUE="%USERNAME%"></TD>

During an initial login (unauthenticated user), the value for the USERNAME macro is empty and the user name text field displayed on the login page appears with the entry "unknown".

For a reauthenticating client, the USERNAME macro would contain the value of the client user name. The user name text field on the login page appears with the user's name automatically provided.

Parent topic: Reauthentication

Authentication strength policy (step-up)Authentication strength policy (step-up)authentication strength policy (step-up)step-up authentication (authentication strength)POPauthentication strength policy (step-up)authenticationauthentication strength policy (step-up)step-upThis section contains the following topics:Advanced authentication methodsMultiplexing proxy agentsSwitch user authenticationReauthenticationExternal authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords. Authentication strength conceptsAuthentication strength configuration task summaryEstablishing an authentication strength policySpecifying authentication levelsSpecifying the authentication strength login formCreating a protected object policySpecifying network-based access restrictionsAttaching a protected object policy to a protected resourceEnforcing user identity match across authentication levelsControlling the login response for unauthenticated usersStepping up authentication at higher levels

Authentication strength policy (step-up)

This section contains the following topics:

Authentication strength concepts

Authentication strength configuration task summary

Establishing an authentication strength policy

Specifying authentication levels

Specifying the authentication strength login form

Creating a protected object policy

Specifying network-based access restrictions

Attaching a protected object policy to a protected resource

Enforcing user identity match across authentication levels

Controlling the login response for unauthenticated users

Stepping up authentication at higher levels

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Switch user authentication

Reauthentication

External authentication interface

Client Certificate User Mapping

Authenticated User Mapping

External user mapping

Password strength

Authentication strength conceptsAuthentication strength conceptsauthentication strength policy (step-up)conceptsconceptsauthentication strengthWebSEAL supports many authentication methods. These include basic authentication, forms authentication, certificate authentication, and others. Any client that accesses a WebSEAL server has an authentication state, such as unauthenticated or certificate, which indicates the method by which the client last authenticated with WebSEAL.WebSEAL provides a feature that enables administrators to assign a ranking or level to some of the supported authentication methods. Administrators can define an ordered list that ranks each authentication method from lowest to highest. This hierarchical ranking can be arbitrarily tailored to each individual WebSEAL deployment.There is no absolute ranking between the authentication methods. No one authentication method is inherently better or stronger than another method. The ranking is simply a method for an administrator to define a relative level for each authentication method for use with a specific Security Access Manager WebSEAL protected object namespace. The only rule governing the assignment of levels is that the unauthenticated level is always lower than all other authenticated levels. This set of authentication levels can be used to implement an authentication strength policy. Authentication strength is sometimes called step-up authentication. Note, however, that step-up authentication is not a unique authentication method like forms authentication or certificate authentication. Instead, it is a defined process for requiring users to change their current authentication method to another authentication method.The concept of changing the authentication method is useful as a way of providing additional protection for selected resources in the WebSEAL protected object namespace. For example, a user can log in using certificate authentication, and then access many resources that are protected by Security Access Manager security. When the user attempts to access a more sensitive resource, which has been marked to require a higher level of access, the user is prompted to log in to a different authentication level. Note that when a user activates authentication strength by attempting to access a protected object, the user does not have to log out first. Instead, the user is presented with a login prompt, and simply logs in again to the higher level.Users can change authentication strength multiple times per authentication session. The authentication level specified in the controlling POP governs the level at which the user must be authenticated.The following authentication methods can be assigned an authentication level:Unauthenticated Password authentication Password authentication is limited to forms authentication. Basic authentication is not supported as a step-up authentication level.Certificate authenticationExternal authentication interfaceAuthentication strength is supported over both HTTP and HTTPS, with the exception of certificate authentication. Because certificates are valid only over an SSL connection, it is not possible to step up to certificates over HTTP. If an object that requires certificate authentication is requested over HTTP, an error page is served, as specified by the cert-stepup-http stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file.Administrators apply an authentication level to a protected resource by declaring and attaching a standard Security Access Manager protected object policy (POP) to the resource object. Authentication strength policy is set and stored in a POP attribute called an IP Endpoint Authentication Method. The attribute takes an integer value that represents the authentication level. The lowest level, unauthenticated, is always 0. Each level increases the integer index up to the total number of authentication methods that have been assigned a level.When clients first authenticate to WebSEAL, the initial authentication method used is stored as an extended attribute in the client's credential. The Security Access Manager authorization service compares the authentication method (level) in the credential against the authentication level for the requested resource, as specified in the POP. When the level in the POP exceeds the level in the credential, the user is prompted to authenticate at the higher authentication strength level.The IP Endpoint Authentication Method attribute can also optionally be used to restrict access to a resource, based on the network address of the client that sent the access request. The access can be restricted based on an individual network (IP) address, or a range of network addresses.WebSEAL uses the following algorithm to process the conditions in a POP: Check the IP endpoint authentication method policy on the POP.Check ACL permissions.Check time-of-day policy on the POP.Check the audit level policy on the POP.Authentication strength policy (step-up)

Authentication strength concepts

WebSEAL supports many authentication methods. These include basic authentication, forms authentication, certificate authentication, and others. Any client that accesses a WebSEAL server has an authentication state, such as unauthenticated or certificate, which indicates the method by which the client last authenticated with WebSEAL.

WebSEAL provides a feature that enables administrators to assign a ranking or level to some of the supported authentication methods. Administrators can define an ordered list that ranks each authentication method from lowest to highest. This hierarchical ranking can be arbitrarily tailored to each individual WebSEAL deployment.

There is no absolute ranking between the authentication methods. No one authentication method is inherently better or stronger than another method. The ranking is simply a method for an administrator to define a relative level for each authentication method for use with a specific Security Access Manager WebSEAL protected object namespace. The only rule governing the assignment of levels is that the unauthenticated level is always lower than all other authenticated levels.

This set of authentication levels can be used to implement an authentication strength policy. Authentication strength is sometimes called step-up authentication. Note, however, that step-up authentication is not a unique authentication method like forms authentication or certificate authentication. Instead, it is a defined process for requiring users to change their current authentication method to another authentication method.

The concept of changing the authentication method is useful as a way of providing additional protection for selected resources in the WebSEAL protected object namespace. For example, a user can log in using certificate authentication, and then access many resources that are protected by Security Access Manager security. When the user attempts to access a more sensitive resource, which has been marked to require a higher level of access, the user is prompted to log in to a different authentication level.

Note that when a user activates authentication strength by attempting to access a protected object, the user does not have to log out first. Instead, the user is presented with a login prompt, and simply logs in again to the higher level.

Users can change authentication strength multiple times per authentication session. The authentication level specified in the controlling POP governs the level at which the user must be authenticated.

The following authentication methods can be assigned an authentication level:

Unauthenticated

Password authentication

Password authentication is limited to forms authentication. Basic authentication is not supported as a step-up authentication level.

Certificate authentication

External authentication interface

Authentication strength is supported over both HTTP and HTTPS, with the exception of certificate authentication. Because certificates are valid only over an SSL connection, it is not possible to step up to certificates over HTTP. If an object that requires certificate authentication is requested over HTTP, an error page is served, as specified by the cert-stepup-http stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file.

Administrators apply an authentication level to a protected resource by declaring and attaching a standard Security Access Manager protected object policy (POP) to the resource object. Authentication strength policy is set and stored in a POP attribute called an IP Endpoint Authentication Method. The attribute takes an integer value that represents the authentication level. The lowest level, unauthenticated, is always 0. Each level increases the integer index up to the total number of authentication methods that have been assigned a level.

When clients first authenticate to WebSEAL, the initial authentication method used is stored as an extended attribute in the client's credential. The Security Access Manager authorization service compares the authentication method (level) in the credential against the authentication level for the requested resource, as specified in the POP. When the level in the POP exceeds the level in the credential, the user is prompted to authenticate at the higher authentication strength level.

The IP Endpoint Authentication Method attribute can also optionally be used to restrict access to a resource, based on the network address of the client that sent the access request. The access can be restricted based on an individual network (IP) address, or a range of network addresses.

WebSEAL uses the following algorithm to process the conditions in a POP:

Check the IP endpoint authentication method policy on the POP.

Check ACL permissions.

Check time-of-day policy on the POP.

Check the audit level policy on the POP.

Parent topic: Authentication strength policy (step-up)

Authentication strength configuration task summaryAuthentication strength configuration task summaryauthentication strength policy (step-up)configuration task summarystrength configurationauthenticationtask summary To configure authentication strength levels, complete the instructions in each of the following sections:Establishing an authentication strength policySpecifying authentication levelsSpecifying the authentication strength login formCreating a protected object policySpecifying network-based access restrictionsAttaching a protected object policy to a protected resourceEnforcing user identity match across authentication levelsControlling the login response for unauthenticated usersStepping up authentication at higher levelsAuthentication strength policy (step-up)

Authentication strength configuration task summary

To configure authentication strength levels, complete the instructions in each of the following sections:

Establishing an authentication strength policy

Specifying authentication levels

Specifying the authentication strength login form

Creating a protected object policy

Specifying network-based access restrictions

Attaching a protected object policy to a protected resource

Enforcing user identity match across authentication levels

Controlling the login response for unauthenticated users

Stepping up authentication at higher levels

Parent topic: Authentication strength policy (step-up)

Establishing an authentication strength policy Establishing an authentication strength policy authenticationestablishing strength policystrength policy This section consists of planning steps to be taken before specifying authentication strength settings in the WebSEAL configuration file. Complete the following steps:Compile a list of protected objects for which access will be limited only to users who have successfully authenticated through a specific authentication method. For each protected object, specify the authentication method that applies.Compile a complete list of all authentication mechanisms that will be active (enabled) on the WebSEAL server system.Determine a hierarchy (ranking) for the active authentication mechanisms. Order the mechanisms from weakest to strongest.Determine if, during authentication strength level step-up, the user identity must be identical across the increased authentication level.Determine if any protected resources require access restriction based on the network address of the requesting client.Stop the WebSEAL server.Authentication strength policy (step-up)

Establishing an authentication strength policy

About this task

This section consists of planning steps to be taken before specifying authentication strength settings in the WebSEAL configuration file.

Complete the following steps:

Procedure

Compile a list of protected objects for which access will be limited only to users who have successfully authenticated through a specific authentication method. For each protected object, specify the authentication method that applies.

Compile a complete list of all authentication mechanisms that will be active (enabled) on the WebSEAL server system.

Determine a hierarchy (ranking) for the active authentication mechanisms. Order the mechanisms from weakest to strongest.

Determine if, during authentication strength level step-up, the user identity must be identical across the increased authentication level.

Determine if any protected resources require access restriction based on the network address of the requesting client.

Stop the WebSEAL server.

Parent topic: Authentication strength policy (step-up)

Specifying authentication levelsSpecifying authentication levelsauthentication-levels stanzalevel (authentication)Complete the following steps to specify authentication levels.Edit the [authentication-levels] stanza in the WebSEAL configuration file. For each authentication method to be used for authentication level step-up, add an entry to the stanza.The supported authentication methods are described in the following table: Authentication methods supported for authentication strengthAuthentication MethodConfiguration File EntryNonelevel = unauthenticatedForms authentication level = passwordCertificate authenticationlevel = sslExternal authentication interfacelevel = ext-auth-interfaceLightwight Third-Party Authentication (LTPA)level = ltpaThe default entries are: [authentication-levels] level = unauthenticated level = passwordThe following entry must always be the first in the list: level = unauthenticated. Additional entries can be placed in any order. For example, to enable authentication strength levels for certificate authentication at the highest level, the completed stanza entry is: [authentication-levels] level = unauthenticated level = password level = sslVerify that each authentication method listed in [authentication-levels] is enabled. To determine if an authentication method is enabled, check the appropriate entries in the WebSEAL configuration file. To review the necessary entries and access the authentication configuration instructions, see the following sections: Enabling and disabling basic authenticationEnabling and disabling forms authenticationEnabling certificate authenticationBasic authentication is enabled by default.Authentication strength policy (step-up)Using multiple authentication levelsYou can associate more than one authentication level with a particular authentication mechanism.

Specifying authentication levels

About this task

Complete the following steps to specify authentication levels.

Procedure

Edit the [authentication-levels] stanza in the WebSEAL configuration file. For each authentication method to be used for authentication level step-up, add an entry to the stanza. The supported authentication methods are described in the following table:

Table 35. Authentication methods supported for authentication strength

Authentication Method | Configuration File Entry
None | level = unauthenticated
Forms authentication | level = password
Certificate authentication | level = ssl
External authentication interface | level = ext-auth-interface
Lightwight Third-Party Authentication (LTPA) | level = ltpa

The default entries are:

[authentication-levels]
level = unauthenticated
level = password

The following entry must always be the first in the list: level = unauthenticated. Additional entries can be placed in any order. For example, to enable authentication strength levels for certificate authentication at the highest level, the completed stanza entry is:

[authentication-levels]
level = unauthenticated
level = password
level = ssl

Verify that each authentication method listed in [authentication-levels] is enabled. To determine if an authentication method is enabled, check the appropriate entries in the WebSEAL configuration file. To review the necessary entries and access the authentication configuration instructions, see the following sections:

Enabling and disabling basic authentication

Enabling and disabling forms authentication

Enabling certificate authentication

Note: Basic authentication is enabled by default.

Using multiple authentication levels
You can associate more than one authentication level with a particular authentication mechanism.

Parent topic: Authentication strength policy (step-up)

Using multiple authentication levelsYou can associate more than one authentication level with a particular authentication mechanism. authenticationmultiple levelsmultiple levelsauthenticationAuthentication mechanisms can set the authentication level, which results from a successful authentication, directly into the credential as an attribute. If so, this overrides the level set in the credential by the placement of the authentication mechanism in the [authentication-levels] stanza. You can use this method to specify the authentication level that will be set in the resulting Security Access Manager credential. Use it when you want to associate more than one level with a particular authentication mechanism.The reasons to enter an authentication mechanism more than once in the [authentication-levels] stanza are:To control the prompt that is displayed to a user when they are required to step-up.To satisfy the Policy Server requirement that a method exists that can handle every configured POP level.This is likely to be a consideration when using an External Authentication Interface (EAI) server to perform authentication. It is common to want the EAI to handle multiple authentication levels. An EAI server can return an authentication level either as an attribute in a Privilege Attribute Certificate (PAC), if it returns one, or as an extended attribute header if it returns a User Id. The EAI authentication mechanism can then be specified in multiple lines of the [authentication-levels] stanza. For example, if an EAI server is configured to handle authenticating users at levels 2 and 3, while Forms authentication is used to authenticate users at level 1, the [authentication-levels] stanza would contain the following entries: [authentication-levels] #---------------------- # STEP UP #---------------------- # authentication levels # # Syntax: # level = <method-name> # # Valid method names are: # unauthenticated # password # ssl # ext-auth-interface # ltpa # level = unauthenticated level = password level = ext-auth-interface level = ext-auth-interfaceSpecifying authentication levels

Using multiple authentication levels

You can associate more than one authentication level with a particular authentication mechanism.

Authentication mechanisms can set the authentication level, which results from a successful authentication, directly into the credential as an attribute. If so, this overrides the level set in the credential by the placement of the authentication mechanism in the [authentication-levels] stanza. You can use this method to specify the authentication level that will be set in the resulting Security Access Manager credential. Use it when you want to associate more than one level with a particular authentication mechanism.

The reasons to enter an authentication mechanism more than once in the [authentication-levels] stanza are:

To control the prompt that is displayed to a user when they are required to step-up.

To satisfy the Policy Server requirement that a method exists that can handle every configured POP level.

This is likely to be a consideration when using an External Authentication Interface (EAI) server to perform authentication. It is common to want the EAI to handle multiple authentication levels. An EAI server can return an authentication level either as an attribute in a Privilege Attribute Certificate (PAC), if it returns one, or as an extended attribute header if it returns a User Id. The EAI authentication mechanism can then be specified in multiple lines of the [authentication-levels] stanza. For example, if an EAI server is configured to handle authenticating users at levels 2 and 3, while Forms authentication is used to authenticate users at level 1, the [authentication-levels] stanza would contain the following entries:

[authentication-levels]
#----------------------
# STEP UP
#----------------------
# authentication levels
#
# Syntax:
# level = <method-name>
#
# Valid method names are:
#   unauthenticated
#   password
#   ssl
#   ext-auth-interface
#   ltpa
#
level = unauthenticated
level = password
level = ext-auth-interface
level = ext-auth-interface

Parent topic: Specifying authentication levels

Specifying the authentication strength login form Specifying the authentication strength login form stepup-login stanza entrystepuplogin.htmlacnt-mgt stanzaauthentication strength login form When an authenticated client attempts to access a protected resource, and is required to reauthenticate to a higher authentication strength level, WebSEAL presents a special HTML form. The client uses the form to supply the information needed for the type of authentication required. WebSEAL supplies a default login form. Administrators can either use the default login form or customize it to fit the local WebSEAL deployment. The location of the default login form is specified in the WebSEAL configuration file: [acnt-mgt] stepup-login = stepuplogin.html Complete the following steps:Specify the name of the authentication strength login form. To use the default location for the form, verify that the WebSEAL configuration file stanza entry, stepup-login, contains the default value, stepuplogin.html.Optionally, customize the contents of the authentication strength login form. This file contains macros, in the form of %TEXT% sequences, which are replaced with the appropriate values. This substitution occurs within WebSEAL's template file processing functions and allows the form to be used for the supported authentication methods with correct formatting. It also allows other information, such as error message and authentication method name, to be supplied in the form for the user. For more information on using macros, see Macro resources for customizing HTML response pagesMacros are predefined, specially formatted strings that are used to dynamically add information to static HTML server response pages. .Restart the WebSEAL server. The configuration of authentication strength levels is now complete.Authentication strength policy (step-up)

Specifying the authentication strength login form

About this task

When an authenticated client attempts to access a protected resource, and is required to reauthenticate to a higher authentication strength level, WebSEAL presents a special HTML form. The client uses the form to supply the information needed for the type of authentication required.

WebSEAL supplies a default login form. Administrators can either use the default login form or customize it to fit the local WebSEAL deployment.

The location of the default login form is specified in the WebSEAL configuration file:

[acnt-mgt]
stepup-login = stepuplogin.html

Complete the following steps:

Procedure

Specify the name of the authentication strength login form.

To use the default location for the form, verify that the WebSEAL configuration file stanza entry, stepup-login, contains the default value, stepuplogin.html.

Optionally, customize the contents of the authentication strength login form.

This file contains macros, in the form of %TEXT% sequences, which are replaced with the appropriate values. This substitution occurs within WebSEAL's template file processing functions and allows the form to be used for the supported authentication methods with correct formatting. It also allows other information, such as error message and authentication method name, to be supplied in the form for the user.

For more information on using macros, see Macro resources for customizing HTML response pages.

Restart the WebSEAL server.

Results

The configuration of authentication strength levels is now complete.

Parent topic: Authentication strength policy (step-up)

Creating a protected object policy Creating a protected object policy POPcreateIP Endpoint Authentication Method PolicyIP Endpoint Authentication Method Policy Complete the following steps:Create a POP. For example, use pdadmin to create a new POP named test:pdadmin> pop create testDisplay the contents of the new POP:pdadmin> pop show test The new POP contains new settings similar to the following:pdadmin> pop show test Protected object policy: test Description: Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0Note the default values in the POP for the attribute IP Endpoint Authentication Method Policy. ... ... IP Endpoint Authentication Method Policy Any Other Network 0 ...The IP Endpoint Authentication Method Policy attribute is used to specify two different attributes: Authentication strength level. The default value is 0.Network-based access policy. The default value is Any Other Network.Use pdadmin pop modify to modify the IP Endpoint Authentication Method Policy attribute to specify the authentication strength level that you want to apply to the resources identified in Establishing an authentication strength policy. The syntax is: pdadmin> pop modify pop-name set ipauth anyothernw level-indexThe value level-index is an integer. The default value is 0. The default value maps to the authentication strength level unauthenticated. Specify the index that corresponds to the necessary authentication strength level. To determine the correct level-index, examine the [authentication-level] stanza in the WebSEAL configuration file. For example:authentication-levels stanza[authentication-levels] level = unauthenticated level = password level = sslFor the above entry, the index values are described in the following table: Example integer values for authentication strength levelsAuthentication methodIndex valueunauthenticated0password1ssl2For example, to add the password authentication strength level (index value 1) to the test POP, enter:pdadmin> pop modify test set ipauth anyothernw 1To verify the modification, display the POP: pdadmin> pop show test Protected object policy: test Description: Test POP Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 1Note: In this example, the only valid index values are: 0,1,2. If any other index value is configured, WebSEAL presents an error page whenever a client requests any object with that has the POP attached.Authentication strength policy (step-up)

Creating a protected object policy

About this task

Complete the following steps:

Procedure

Create a POP. For example, use pdadmin to create a new POP named test:

pdadmin> pop create test

Display the contents of the new POP:

pdadmin> pop show test

The new POP contains new settings similar to the following:

pdadmin> pop show test
       Protected object policy:  test
       Description:
       Warning:  no
       Audit level: none
       Quality of protection:  none
       Time of day access: sun, mon, tue, wed, thu, fri, sat:
          anytime:local
       IP Endpoint Authentication Method Policy
          Any Other Network 0

Note the default values in the POP for the attribute IP Endpoint Authentication Method Policy.

...
...
IP Endpoint Authentication Method Policy
           Any Other Network 0
...

The IP Endpoint Authentication Method Policy attribute is used to specify two different attributes:

Authentication strength level.

The default value is 0.

Network-based access policy.

The default value is Any Other Network.

Use pdadmin pop modify to modify the IP Endpoint Authentication Method Policy attribute to specify the authentication strength level that you want to apply to the resources identified in Establishing an authentication strength policy. The syntax is:

pdadmin> pop modify pop-name set ipauth anyothernw level-index

The value level-index is an integer. The default value is 0. The default value maps to the authentication strength level unauthenticated.

Specify the index that corresponds to the necessary authentication strength level. To determine the correct level-index, examine the [authentication-level] stanza in the WebSEAL configuration file.

For example:[authentication-levels]
level = unauthenticated
level = password
level = ssl

For the above entry, the index values are described in the following table:

Table 36. Example integer values for authentication strength levels

Authentication method | Index value
unauthenticated | 0
password | 1
ssl | 2

For example, to add the password authentication strength level (index value 1) to the test POP, enter:pdadmin> pop modify test set ipauth anyothernw 1 To verify the modification, display the POP:

pdadmin> pop show test
       Protected object policy:  test
       Description:  Test POP
       Warning:  no
       Audit level: none
       Quality of protection: none
       Time of day access: sun, mon, tue, wed, thu, fri, sat:
          anytime:local
       IP Endpoint Authentication Method Policy
          Any Other Network 1

Note: In this example, the only valid index values are: 0,1,2. If any other index value is configured, WebSEAL presents an error page whenever a client requests any object with that has the POP attached.

Parent topic: Authentication strength policy (step-up)

Specifying network-based access restrictionsSpecifying network-based access restrictionsipauthPOPnetwork-based access restrictions Security Access Manager supports an optional POP configuration setting that enables the application of authentication strength levels to client requests originating from specified network addresses. The network addresses can be defined as either a single IP address, or as a range of IP addresses. In most deployments, user access is not restricted based on the IP address within POPs. In most deployments, this configuration section can be skipped. The pdadmin pop modify set ipauth command is used to specify IP addresses. Note that this is the same pdadmin command used to specify authentication levels. The default usage of pdadmin pop modify set ipauth does not impose any network-based access restrictions. This usage consists of specifying the command line argument anyothernw as the value for the IP Endpoint Authentication Method Policy attribute. This setting applies to all user access, regardless of the IP address of the requestor, and requires all users to authenticate at the specified level. The syntax is: pdadmin> pop modify pop-name set ipauth anyothernw level_index For example, in Creating a protected object policy above, the following command created a POP that required all users to authenticate at authentication level 1, and did not impose any network-based access requirements: pdadmin> pop modify test set ipauth anyothernw 1 The following network-based access restrictions can be applied:Require a specific authentication strength level when the IP address of the requesting client is within a defined range of IP addresses. Syntax:pdadmin> pop modify pop_name set ipauth add network netmask level_indexNote that the pdadmin pop modify set ipauth add command specifies both the network addresses and the required authentication level in the IP Endpoint Authentication Method attribute.For example, to require users from IP address range 9.1.2.[0–255] to use authentication strength level 1:pdadmin> pop modify test set ipauth add 9.1.2.1 255.255.255.0 1Note that the value specified for the netmask determines the range of network addresses affected. The number 0 in the netmask serves as a wildcard to mean all IP addresses for that subnet. See the example that follows.Examples of using netmask to specify a network range (IPv4)IPv4 AddressNetmaskNetwork range affected9.1.2.3255.255.255.09.1.2.[0–255]9.1.2.3255.255.0.09.1.[0–255].[0–255]9.1.2.3255.0.0.09.[0–255].[0–255].[0–255]Examples of using netmask to specify a network range (IPv6)IPv6 AddressNetmaskNetwork range affectedfec0::1fff0::fec[0-f]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]fec0:ffff::1ffff:fff0::fec0:fff[0-f]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]Require requests from one specific IP address to use a specified authentication strength level.For example, to require requests from IP address 9.1.2.3 to use authentication strength level 1:pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.255 1 To require requests from all IP addresses on subnet 9.1.2.x to use authentication strength level 1:pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.0 1 Disable use of authentication strength level step-up by all requests from a range of network addresses.The syntax is:pdadmin> pop modify pop_name set ipauth remove network netmask For example, to disable all requests from the range of IP addresses on the 9.1.2.x subnet:pdadmin> pop modify test set ipauth remove 9.1.2.1 255.255.255.0 Allow access to the protected resource based solely on IP address, or range of IP addresses, regardless of the authentication strength level.This restriction is enforced by specifying the IP address or addresses, and assigning an authentication level of zero (0). For example, to allow requests from IP address 9.1.2.3, regardless of authentication strength level:pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.255 0 Likewise, to allow requests from all IP addresses on the 9.1.2.x subnet, regardless of authentication strength level:pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.0 0 Deny access based solely on IP address, or range of IP addresses, regardless of authentication strength level.This restriction is enforced by using the key word forbidden as the final parameter.For example, to restrict only the client at IP address 9.1.2.3 from accessing the protected resource:pdadmin> pop modify test set ipauth 9.1.2.3 255.255.255.255 forbiddenLikewise, to restrict requests from all IP addresses on the 9.1.2.x subnet from accessing the resource:pdadmin> pop modify test set ipauth 9.1.2.3 255.255.255.0 forbiddenPrevent requests from all IP addresses from accessing the protected object, unless the IP address has been enabled by a previous pop modify set ipauth add command.For example, in a use case above, a range of IP addresses were required to access the protected resource by using authentication strength level 1:pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.0 1 The administrator can, in addition, specify that requests from all other IP addresses will be denied, regardless of authentication strength level, in the following pdadmin command:pdadmin> pop modify test set ipauth anyothernw forbidden The option anyothernw means any other network address, and the option forbidden enforces the denial policy.Authentication strength policy (step-up)

Specifying network-based access restrictions

About this task

Security Access Manager supports an optional POP configuration setting that enables the application of authentication strength levels to client requests originating from specified network addresses. The network addresses can be defined as either a single IP address, or as a range of IP addresses.

Note: In most deployments, user access is not restricted based on the IP address within POPs. In most deployments, this configuration section can be skipped.

The pdadmin pop modify set ipauth command is used to specify IP addresses. Note that this is the same pdadmin command used to specify authentication levels.

The default usage of pdadmin pop modify set ipauth does not impose any network-based access restrictions. This usage consists of specifying the command line argument anyothernw as the value for the IP Endpoint Authentication Method Policy attribute. This setting applies to all user access, regardless of the IP address of the requestor, and requires all users to authenticate at the specified level.

The syntax is:

pdadmin> pop modify pop-name set ipauth anyothernw level_index

For example, in Creating a protected object policy above, the following command created a POP that required all users to authenticate at authentication level 1, and did not impose any network-based access requirements:

pdadmin> pop modify test set ipauth anyothernw 1

Procedure

The following network-based access restrictions can be applied:

Require a specific authentication strength level when the IP address of the requesting client is within a defined range of IP addresses.

Syntax:

pdadmin> pop modify pop_name set ipauth add network netmask level_index

Note that the pdadmin pop modify set ipauth add command specifies both the network addresses and the required authentication level in the IP Endpoint Authentication Method attribute.

For example, to require users from IP address range 9.1.2.[0–255] to use authentication strength level 1:

pdadmin> pop modify test set ipauth add 9.1.2.1 255.255.255.0 1

Note that the value specified for the netmask determines the range of network addresses affected. The number 0 in the netmask serves as a wildcard to mean all IP addresses for that subnet. See the example that follows.

Table 37. Examples of using netmask to specify a network range (IPv4)

IPv4 Address | Netmask | Network range affected
9.1.2.3 | 255.255.255.0 | 9.1.2.[0–255]
9.1.2.3 | 255.255.0.0 | 9.1.[0–255].[0–255]
9.1.2.3 | 255.0.0.0 | 9.[0–255].[0–255].[0–255]

Table 38. Examples of using netmask to specify a network range (IPv6)

IPv6 Address
Netmask
Network range affected

fec0::1
fff0::

fec[0-f]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]

fec0:ffff::1
ffff:fff0::

fec0:fff[0-f]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]:[0-ffff]

Require requests from one specific IP address to use a specified authentication strength level.

For example, to require requests from IP address 9.1.2.3 to use authentication strength level 1:

pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.255 1

To require requests from all IP addresses on subnet 9.1.2.x to use authentication strength level 1:

pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.0 1

Disable use of authentication strength level step-up by all requests from a range of network addresses.

The syntax is:

pdadmin> pop modify pop_name set ipauth remove network netmask

For example, to disable all requests from the range of IP addresses on the 9.1.2.x subnet:

pdadmin> pop modify test set ipauth remove 9.1.2.1 255.255.255.0

Allow access to the protected resource based solely on IP address, or range of IP addresses, regardless of the authentication strength level.

This restriction is enforced by specifying the IP address or addresses, and assigning an authentication level of zero (0). For example, to allow requests from IP address 9.1.2.3, regardless of authentication strength level:

pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.255 0

Likewise, to allow requests from all IP addresses on the 9.1.2.x subnet, regardless of authentication strength level:

pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.0 0

Deny access based solely on IP address, or range of IP addresses, regardless of authentication strength level.

This restriction is enforced by using the key word forbidden as the final parameter.

For example, to restrict only the client at IP address 9.1.2.3 from accessing the protected resource:

pdadmin> pop modify test set ipauth 9.1.2.3 255.255.255.255 forbidden

Likewise, to restrict requests from all IP addresses on the 9.1.2.x subnet from accessing the resource:

pdadmin> pop modify test set ipauth 9.1.2.3 255.255.255.0 forbidden

Prevent requests from all IP addresses from accessing the protected object, unless the IP address has been enabled by a previous pop modify set ipauth add command.

For example, in a use case above, a range of IP addresses were required to access the protected resource by using authentication strength level 1:

pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.0 1

The administrator can, in addition, specify that requests from all other IP addresses will be denied, regardless of authentication strength level, in the following pdadmin command:

pdadmin> pop modify test set ipauth anyothernw forbidden

The option anyothernw means any other network address, and the option forbidden enforces the denial policy.

Parent topic: Authentication strength policy (step-up)

Attaching a protected object policy to a protected resourceAttaching a protected object policy to a protected resourcePOPattach to an objectprotected resourcesattaching a POP to a protected resource After a protected object policy (POP) has been defined and created, it must be attached to the protected resources to which it applies. The syntax for attaching a POP is: pdadmin pop attach object_name pop_name For example, an authentication policy for a WebSEAL deployment could be defined as follows: The deployment will use forms authentication and certificate authentication. Forms authentication is the first authentication strength level (1) and certificate authentication is the second (stronger) authentication level (2). Users must authenticate using forms authentication or stronger to access the following protected resource (a WebSEAL junction): /WebSEAL/hostA/junctionUsers must authenticate using certificate authentication to access the following protected resource (an application): /WebSEAL/hostA/junction/applicationA To implement this policy, the following configuration steps must take place.Modify the WebSEAL configuration file to grant forms authentication an authentication strength of 1 and certificate authentication a strength of 2:[authentication-levels] level = unauthenticated level = password level = sslCreate a POP for authentication level 1 (forms authentication).pdadmin> pop create test1 pdadmin> pop modify test1 set ipauth anyothernw 1Create a POP for authentication level 2 (certificate authentication).pdadmin> pop create test2 pdadmin> pop modify test2 set ipauth anyothernw 2Attach the POP test1 to /WebSEAL/hostA/junction.pdadmin> pop attach /WebSEAL/hostA/junction test1Attach the POP test2 to /WebSEAL/hostA/junction/application.pdadmin> pop attach /WebSEAL/hostA/junction/applicationA test2 For more information on the administration of POPs, see the Administering Security Access Manager Base administration information. For information on pdadmin syntax, see the Command Reference topics in the Knowledge Center.Authentication strength policy (step-up)

Attaching a protected object policy to a protected resource

About this task

After a protected object policy (POP) has been defined and created, it must be attached to the protected resources to which it applies. The syntax for attaching a POP is:

pdadmin pop attach object_name pop_name

For example, an authentication policy for a WebSEAL deployment could be defined as follows:

The deployment will use forms authentication and certificate authentication. Forms authentication is the first authentication strength level (1) and certificate authentication is the second (stronger) authentication level (2).

Users must authenticate using forms authentication or stronger to access the following protected resource (a WebSEAL junction):

/WebSEAL/hostA/junction

Users must authenticate using certificate authentication to access the following protected resource (an application):

/WebSEAL/hostA/junction/applicationA

To implement this policy, the following configuration steps must take place.

Procedure

Modify the WebSEAL configuration file to grant forms authentication an authentication strength of 1 and certificate authentication a strength of 2:

[authentication-levels]
level = unauthenticated
level = password
level = ssl

Create a POP for authentication level 1 (forms authentication).

pdadmin> pop create test1
pdadmin> pop modify test1 set ipauth anyothernw 1

Create a POP for authentication level 2 (certificate authentication).

pdadmin> pop create test2
pdadmin> pop modify test2 set ipauth anyothernw 2

Attach the POP test1 to /WebSEAL/hostA/junction.

pdadmin> pop attach /WebSEAL/hostA/junction test1

Attach the POP test2 to /WebSEAL/hostA/junction/application.

pdadmin> pop attach /WebSEAL/hostA/junction/applicationA test2

Results

Note: For more information on the administration of POPs, see the Administering Security Access Manager Base administration information. For information on pdadmin syntax, see the Command Reference topics in the Knowledge Center.

Parent topic: Authentication strength policy (step-up)

Enforcing user identity match across authentication levelsEnforcing user identity match across authentication levelsuser identitymatch with step-upverify-step-up-user By default, WebSEAL requires the user identity that performs the authentication strength (step-up) operation to match the user identity used to perform the initial authentication operation. WebSEAL verifies that the user identity in the new user credential matches the user identity in the original credential. If the user identities do not match, WebSEAL denies the authentication step-up, logs an error and returns an error page to the user. This function is enabled by default.To disable this function, edit the WebSEAL configuration file, and set the value of verify-step-up-user to no:[step-up] verify-step-up-user = yesAuthentication strength policy (step-up)

Enforcing user identity match across authentication levels

About this task

By default, WebSEAL requires the user identity that performs the authentication strength (step-up) operation to match the user identity used to perform the initial authentication operation.

WebSEAL verifies that the user identity in the new user credential matches the user identity in the original credential. If the user identities do not match, WebSEAL denies the authentication step-up, logs an error and returns an error page to the user.

Procedure

This function is enabled by default.

To disable this function, edit the WebSEAL configuration file, and set the value of verify-step-up-user to no:

[step-up]
verify-step-up-user = yes

Parent topic: Authentication strength policy (step-up)

Controlling the login response for unauthenticated usersControlling the login response for unauthenticated usersshow-all-auth-prompts stanza entrylogincontrol step-up login for unauthenticated users You can control the login prompt response for an unauthenticated user who requests an object protected by a step-up authentication POP attribute. By default, WebSEAL presents only the login prompt for the specific authentication level required by the POP. The show-all-auth-prompts stanza entry in the [step-up] stanza of the WebSEAL configuration file controls this response. The default value is "no":[step-up] show-all-auth-prompts = noIn previous versions of WebSEAL, multiple login prompts—one for each enabled authentication method—were presented to the unauthenticated user on one login page. To support this previous behavior, set the value of the show-all-auth-prompts stanza entry to "yes":[step-up] show-all-auth-prompts = yesThe show-all-auth-prompts function is triggered only by a POP on an object. If an unauthenticated user is asked to authenticate for reasons that do not involve a POP on an object, the functionality of show-all-auth-prompts is not used.Authentication strength policy (step-up)

Controlling the login response for unauthenticated users

About this task

You can control the login prompt response for an unauthenticated user who requests an object protected by a step-up authentication POP attribute.

By default, WebSEAL presents only the login prompt for the specific authentication level required by the POP. The show-all-auth-prompts stanza entry in the [step-up] stanza of the WebSEAL configuration file controls this response. The default value is "no":

[step-up]
show-all-auth-prompts = no

Procedure

In previous versions of WebSEAL, multiple login prompts—one for each enabled authentication method—were presented to the unauthenticated user on one login page. To support this previous behavior, set the value of the show-all-auth-prompts stanza entry to "yes":

[step-up]
show-all-auth-prompts = yes

Note: The show-all-auth-prompts function is triggered only by a POP on an object. If an unauthenticated user is asked to authenticate for reasons that do not involve a POP on an object, the functionality of show-all-auth-prompts is not used.

Parent topic: Authentication strength policy (step-up)

Stepping up authentication at higher levelsStepping up authentication at higher levelsstep-up-at-higher-level stanza entryauthenticationhigher levels You can configure WebSEAL to accept authentication mechanisms that are configured at a higher level than the level specified in the POP. With this configuration, the user can authenticate directly at the higher level. To accept higher authentication levels during step-up operations, you must set the value of the step-up-at-higher-level stanza entry to "yes".[step-up] step-up-at-higher-level = yesTo disallow higher authentication levels during step-up operations, set the value of the step-up-at-higher-level stanza entry to "no".[step-up] step-up-at-higher-level = noThe default value is "no" if you do not configure this configuration entry. That is, by default WebSEAL does not accept higher authentication levels.Authentication strength policy (step-up)

Stepping up authentication at higher levels

About this task

You can configure WebSEAL to accept authentication mechanisms that are configured at a higher level than the level specified in the POP. With this configuration, the user can authenticate directly at the higher level.

Procedure

To accept higher authentication levels during step-up operations, you must set the value of the step-up-at-higher-level stanza entry to "yes".

[step-up]
step-up-at-higher-level = yes

To disallow higher authentication levels during step-up operations, set the value of the step-up-at-higher-level stanza entry to "no".

[step-up]
step-up-at-higher-level = no

Results

The default value is "no" if you do not configure this configuration entry. That is, by default WebSEAL does not accept higher authentication levels.

Parent topic: Authentication strength policy (step-up)

External authentication interfaceExternal authentication interfaceexternal authentication interfaceoverviewauthenticationexternal authentication interfaceSecurity Access Manager provides an external authentication interface that enables you to extend the functionality of the WebSEAL authentication process. The external authentication interface allows third-party systems to supply an authenticated identity to WebSEAL and Web-server plug-ins. The identity information is then used to generate a credential. This extended authentication functionality is similar to the existing custom authentication module capability provided by the Web security external authentication C API. However, the external authentication interface allows the user identity to be supplied in HTTP Response headers rather than through the authentication module interface.For complete information on configuring external authentication interface authentication, refer to External authentication interface.Advanced authentication methodsMultiplexing proxy agentsSwitch user authenticationReauthenticationAuthentication strength policy (step-up)Client Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords. External authentication interface for mobile applicationsThe standard EAI flow can involve multiple Moved Temporarily (302) operations, which are not mobile application friendly. WebSEAL provides configuration options to help reduce the number of 302 operations.

External authentication interface

Security Access Manager provides an external authentication interface that enables you to extend the functionality of the WebSEAL authentication process. The external authentication interface allows third-party systems to supply an authenticated identity to WebSEAL and Web-server plug-ins. The identity information is then used to generate a credential.

This extended authentication functionality is similar to the existing custom authentication module capability provided by the Web security external authentication C API. However, the external authentication interface allows the user identity to be supplied in HTTP Response headers rather than through the authentication module interface.

For complete information on configuring external authentication interface authentication, refer to External authentication interface.

External authentication interface for mobile applications
The standard EAI flow can involve multiple Moved Temporarily (302) operations, which are not mobile application friendly. WebSEAL provides configuration options to help reduce the number of 302 operations.

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Switch user authentication

Reauthentication

Authentication strength policy (step-up)

Client Certificate User Mapping

Authenticated User Mapping

External user mapping

Password strength

External authentication interface for mobile applicationsThe standard EAI flow can involve multiple Moved Temporarily (302) operations, which are not mobile application friendly. WebSEAL provides configuration options to help reduce the number of 302 operations. The following topics illustrate the various scenarios based on the authentication information transport mechanism.External authentication interfaceAuthentication through 401 WWW-AuthenticateUse this scenario as an example where the authentication information is provided as an HTTP header, for example, basic-authentication.Authentication through formsUse this flow as an example to reduce 302 operations for forms authentication.

External authentication interface for mobile applications

The standard EAI flow can involve multiple Moved Temporarily (302) operations, which are not mobile application friendly. WebSEAL provides configuration options to help reduce the number of 302 operations.

The following topics illustrate the various scenarios based on the authentication information transport mechanism.

Authentication through 401 WWW-Authenticate
Use this scenario as an example where the authentication information is provided as an HTTP header, for example, basic-authentication.

Authentication through forms
Use this flow as an example to reduce 302 operations for forms authentication.

Parent topic: External authentication interface

Authentication through 401 WWW-AuthenticateUse this scenario as an example where the authentication information is provided as an HTTP header, for example, basic-authentication.This flow uses Local Response Redirects where requests to any page that requires an authenticated user is intercepted and redirected to the junctioned EAI application for authentication.The junction that provides this EAI application must be created with HTTP Basic Authentication Header set to ignore. Assume that the following configuration entries have been set in the WebSEAL configuration file.[ba] ba-auth = none [eai] eai-auth = https [eai-trigger-urls] trigger = /jct/cgi-bin/eai [acnt-mgt] enable-local-response-redirect = yes [local-response-redirect] local-response-redirect-uri = [login] /jct/cgi-bin/eaiThe traditional flow is shown as follows: The traditional flow.The /index.html file is just an example. It can be any document from WebSEAL or its junctions that require an authenticated session for access.To configure WebSEAL to internally process 302 operations, first specify the maximum number of 302 operations it can sequentially follow. A value of 2 is suitable for typical scenarios:[server] maximum-followed-redirects = 2Secondly, configure WebSEAL to process 302 redirects internally for any request that results in a Local Response Redirect with the following entry:[server] follow-redirects-for = !LRR!This configuration avoids the initial Local Response Redirect 302 (shown at point 1). The client now receives the 401 WWW-Authenticate header for /index.html instead of a redirect to the EAI URL. So the client sends the authorization header with a GET for /index.html. Thirdly, set WebSEAL to process redirects internally for any request that would result in a 302 redirect back to the same URL that was originally requested (shown at point 2). To achieve this, add the following configuration entry:[server] follow-redirects-for = GET /jct/cgi-bin/eai*The original request from the client was for /index.html. In this flow, WebSEAL internally redirects the client to /index.html. So the resulting page content that is returned from WebSEAL matches what the client is expecting to receive. Relative URLs in this page will operate as expected.The final flow is shown as follows:The final flow with the redirects.Two sequential 302 operations are internally processed by WebSEAL (shown at 3 and 2) in the flow, which is why the value of 2 was used for the maximum-followed-redirects entry.External authentication interface for mobile applicationsThe standard EAI flow can involve multiple Moved Temporarily (302) operations, which are not mobile application friendly. WebSEAL provides configuration options to help reduce the number of 302 operations.

Authentication through 401 WWW-Authenticate

Use this scenario as an example where the authentication information is provided as an HTTP header, for example, basic-authentication.

This flow uses Local Response Redirects where requests to any page that requires an authenticated user is intercepted and redirected to the junctioned EAI application for authentication.

The junction that provides this EAI application must be created with HTTP Basic Authentication Header set to ignore.

Assume that the following configuration entries have been set in the WebSEAL configuration file.

[ba]
ba-auth = none

[eai]
eai-auth = https

[eai-trigger-urls]
trigger = /jct/cgi-bin/eai

[acnt-mgt]
enable-local-response-redirect = yes

[local-response-redirect]
local-response-redirect-uri = [login] /jct/cgi-bin/eai

The traditional flow is shown as follows:

Note: The /index.html file is just an example. It can be any document from WebSEAL or its junctions that require an authenticated session for access.

To configure WebSEAL to internally process 302 operations, first specify the maximum number of 302 operations it can sequentially follow. A value of 2 is suitable for typical scenarios:

[server]
maximum-followed-redirects = 2

Secondly, configure WebSEAL to process 302 redirects internally for any request that results in a Local Response Redirect with the following entry:

[server]
follow-redirects-for = !LRR!

This configuration avoids the initial Local Response Redirect 302 (shown at point 1). The client now receives the 401 WWW-Authenticate header for /index.html instead of a redirect to the EAI URL. So the client sends the authorization header with a GET for /index.html.

Thirdly, set WebSEAL to process redirects internally for any request that would result in a 302 redirect back to the same URL that was originally requested (shown at point 2). To achieve this, add the following configuration entry:

[server]
follow-redirects-for = GET /jct/cgi-bin/eai*

The original request from the client was for /index.html. In this flow, WebSEAL internally redirects the client to /index.html. So the resulting page content that is returned from WebSEAL matches what the client is expecting to receive. Relative URLs in this page will operate as expected.

The final flow is shown as follows:

Note: Two sequential 302 operations are internally processed by WebSEAL (shown at 3 and 2) in the flow, which is why the value of 2 was used for the maximum-followed-redirects entry.

Parent topic: External authentication interface for mobile applications

Authentication through formsUse this flow as an example to reduce 302 operations for forms authentication.Assume that the following configuration entries have been set in the WebSEAL configuration file.[eai] eai-auth = https [eai-trigger-urls] trigger = /jct/cgi-bin/eai-post [acnt-mgt] enable-local-response-redirect = yes [local-response-redirect] local-response-redirect-uri = [login] /jct/cgi-bin/eaiThe traditional flow is as follows:The traditional flow.The /index.html file is just an example. It can be any document from WebSEAL or its junctions that require an authenticated session for access.To configure WebSEAL to internally process 302 operations, first specify the maximum number of 302 operations it can sequentially follow. A value of 2 is suitable for typical scenarios:[server] maximum-followed-redirects = 2Secondly, configure WebSEAL to process 302 redirects internally for any request that results in a Local Response Redirect with the following entry:[server] follow-redirects-for = !LRR!This configuration avoids the initial Local Response Redirect 302 (shown at point 1). Ensure that the browser does not cache the form that is returned from the EAI against the resource that is being accessed (/index.html). Also, as the browser believes that the request for /index.html returned the form, all page-relative URLs in the form are relative to /index.html, not/jct/cgi-bin/eai.Thirdly, set WebSEAL to process redirects internally for any request that would result in a 302 redirect back to the same URL that was originally requested (shown at point 2). To achieve this, add the following configuration entry:[server] follow-redirects-for = POST /jct/cgi-bin/eai-post*WebSEAL returns the content of /index.html for what the browser believes to be the resource /jct/cgi-bin/eai-post. All page-relative URLs in index.html or any other URLs that were intercepted by the authentication are relative to /jct/cgi-bin/eai-post from the browser's point of view. Thus do not use any page-relative URLs if you use this technique. To solve this issue, it might be necessary to not remove the second 302 (shown at point 2).The final flow is shown as follows:The final flow to reduce 302 operations.External authentication interface for mobile applicationsThe standard EAI flow can involve multiple Moved Temporarily (302) operations, which are not mobile application friendly. WebSEAL provides configuration options to help reduce the number of 302 operations.

Authentication through forms

Use this flow as an example to reduce 302 operations for forms authentication.

Assume that the following configuration entries have been set in the WebSEAL configuration file.

[eai]
eai-auth = https

[eai-trigger-urls]
trigger = /jct/cgi-bin/eai-post

[acnt-mgt]
enable-local-response-redirect = yes

[local-response-redirect]
local-response-redirect-uri = [login] /jct/cgi-bin/eai

The traditional flow is as follows:

Note: The /index.html file is just an example. It can be any document from WebSEAL or its junctions that require an authenticated session for access.

To configure WebSEAL to internally process 302 operations, first specify the maximum number of 302 operations it can sequentially follow. A value of 2 is suitable for typical scenarios:

[server]
maximum-followed-redirects = 2

Secondly, configure WebSEAL to process 302 redirects internally for any request that results in a Local Response Redirect with the following entry:

[server]
follow-redirects-for = !LRR!

This configuration avoids the initial Local Response Redirect 302 (shown at point 1).

Note: Ensure that the browser does not cache the form that is returned from the EAI against the resource that is being accessed (/index.html). Also, as the browser believes that the request for /index.html returned the form, all page-relative URLs in the form are relative to /index.html, not/jct/cgi-bin/eai.

Thirdly, set WebSEAL to process redirects internally for any request that would result in a 302 redirect back to the same URL that was originally requested (shown at point 2). To achieve this, add the following configuration entry:

[server]
follow-redirects-for = POST /jct/cgi-bin/eai-post*

Note: WebSEAL returns the content of /index.html for what the browser believes to be the resource /jct/cgi-bin/eai-post. All page-relative URLs in index.html or any other URLs that were intercepted by the authentication are relative to /jct/cgi-bin/eai-post from the browser's point of view. Thus do not use any page-relative URLs if you use this technique. To solve this issue, it might be necessary to not remove the second 302 (shown at point 2).

The final flow is shown as follows:

Parent topic: External authentication interface for mobile applications

Client Certificate User MappingClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.clientscertificatesuser mappinguser mappingclient certificatesThis section introduces the advanced Client Certificate User Mapping functionality, describes key concepts and components, and details how to deploy the functionality within a Security Access Manager environment. Advanced authentication methodsMultiplexing proxy agentsSwitch user authenticationReauthenticationAuthentication strength policy (step-up)External authentication interfaceAuthenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords. IntroductionWebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.User mapping rules evaluatorHow to manage the CDASConfiguring WebSEAL to use the certificate mapping module

Client Certificate User Mapping

The Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.

This section introduces the advanced Client Certificate User Mapping functionality, describes key concepts and components, and details how to deploy the functionality within a Security Access Manager environment.

Introduction
WebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.

User mapping rules evaluator

How to manage the CDAS

Configuring WebSEAL to use the certificate mapping module

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Switch user authentication

Reauthentication

Authentication strength policy (step-up)

External authentication interface

Authenticated User Mapping

External user mapping

Password strength

Introduction Introduction WebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.CDASoverviewThe client certificate user-mapping CDAS provides a mechanism by which WebSEAL can use the details of a client certificate to determine the corresponding Security Access Manager user identity. The rules that govern the mapping of the client certificate are defined in XSL style notation.If no rules file is provided, by default the Security Access Manager user identity is determined by the Subject DN from the certificate.The CDAS supports all user registries that Security Access Manager supports. The rules evaluation can return an LDAP search string. This string representation of the LDAP search filter must be in accordance with the format described in RFC 2254.Client Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Example RulesThe new CDAS gives the user more flexibility in mapping attributes contained within the certificate to the Security Access Manager user identity. Certificate User Mapping Rule languageUMI XML document modelContainers and XML UMI container namesXML certificate model

Introduction

WebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.

The client certificate user-mapping CDAS provides a mechanism by which WebSEAL can use the details of a client certificate to determine the corresponding Security Access Manager user identity. The rules that govern the mapping of the client certificate are defined in XSL style notation.

Note: If no rules file is provided, by default the Security Access Manager user identity is determined by the Subject DN from the certificate.

The CDAS supports all user registries that Security Access Manager supports.

The rules evaluation can return an LDAP search string. This string representation of the LDAP search filter must be in accordance with the format described in RFC 2254.

Example Rules
The new CDAS gives the user more flexibility in mapping attributes contained within the certificate to the Security Access Manager user identity.

Certificate User Mapping Rule language

UMI XML document model

Containers and XML UMI container names

XML certificate model

Parent topic: Client Certificate User Mapping

Example RulesExample RulesThe new CDAS gives the user more flexibility in mapping attributes contained within the certificate to the Security Access Manager user identity. CDASexample rulesexamplesCDASThe following list illustrates some of the mapping functionality supported by this CDAS. If issuer DN = X, and subject DN = Y, then Security Access Manager DN also = Y.The certificate itself is stored as a userCertificate attribute on the inetOrgPerson entry, and a search is done for the Base64 encoded version of the certificate within the user registry.Take the issuer DN and the subject DN from the certificate, and combine them to look like this: <certDN>subjectName</certDN><issuerDN>issuerName</issuerDN>Then look for an entry with this value for the attribute: ibm-certificateSubjectAndIssuerIf issuer DN = X, the subjectAltName is the same as the DN of the inetOrgPerson entry.If issuer DN = X, the serialNumber maps to the secCertSerialNumber attribute of the inetOrgPerson.If issuer DN = X, the cn from the subjectDN field will map to the cn of the inetOrgPerson entry. If issuer DN = X, the subjectDN maps to secCertDN in the inetOrgPerson entry.IntroductionWebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.

Example Rules

The new CDAS gives the user more flexibility in mapping attributes contained within the certificate to the Security Access Manager user identity.

The following list illustrates some of the mapping functionality supported by this CDAS.

If issuer DN = X, and subject DN = Y, then Security Access Manager DN also = Y.

The certificate itself is stored as a userCertificate attribute on the inetOrgPerson entry, and a search is done for the Base64 encoded version of the certificate within the user registry.

Take the issuer DN and the subject DN from the certificate, and combine them to look like this:

<certDN>subjectName</certDN><issuerDN>issuerName</issuerDN>

Then look for an entry with this value for the attribute:

ibm-certificateSubjectAndIssuer

If issuer DN = X, the subjectAltName is the same as the DN of the inetOrgPerson entry.

If issuer DN = X, the serialNumber maps to the secCertSerialNumber attribute of the inetOrgPerson.

If issuer DN = X, the cn from the subjectDN field will map to the cn of the inetOrgPerson entry.

If issuer DN = X, the subjectDN maps to secCertDN in the inetOrgPerson entry.

Parent topic: Introduction

Certificate User Mapping Rule languageCertificate User Mapping Rule languageXMLuser mapping rulesExtensible Style LanguageExtensible Markup LanguageXSLuser mapping rulesCertificate User Mapping Rule languagelanguagesExtensible Style Language (XSL) is the language used to specify rules, while Extensible Markup Language (XML) is the language used for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both the inputs to the rules evaluator and the rules themselves.XML also provides the ability to express complex data types in a structured and standard manner in text format. This text format allows rules for processing the XML data to be written without having to cater to platform and programming language specifics.XSL is a functional stylesheet language that can be used to perform simple or complex tasks, depending on your needs. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation. XSL is built on other XML-based standards such as XPath, which is the expression language at the core of a Certificate User Mapping Rule.To implement the user mapping rules, it is necessary to impose a number of constraints on the XSL rules, including the requirements that the output of the rule evaluation be simple text, and that the output conforms to one of a known set of result strings. For more information about the format and constraints of user mapping rules, see Format and constraints of rules.IntroductionWebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.

Certificate User Mapping Rule language

Extensible Style Language (XSL) is the language used to specify rules, while Extensible Markup Language (XML) is the language used for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both the inputs to the rules evaluator and the rules themselves.

XML also provides the ability to express complex data types in a structured and standard manner in text format. This text format allows rules for processing the XML data to be written without having to cater to platform and programming language specifics.

XSL is a functional stylesheet language that can be used to perform simple or complex tasks, depending on your needs. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation. XSL is built on other XML-based standards such as XPath, which is the expression language at the core of a Certificate User Mapping Rule.

To implement the user mapping rules, it is necessary to impose a number of constraints on the XSL rules, including the requirements that the output of the rule evaluation be simple text, and that the output conforms to one of a known set of result strings. For more information about the format and constraints of user mapping rules, see Format and constraints of rules.

Parent topic: Introduction

UMI XML document modelUMI XML document modelUMIXML document modelXMLUMI document modeldocument model for UMImodelsThe Universal Management Infrastructure XML document model (or UMI XML model) is a set of restrictions placed on the XSL/XML model by the user mapping rules implementation, which enables the interface to be simple and yet functional for certificate purposes. The model constrains the certificate rules to function within a predetermined XML document format, with the same top-level XML document element for all rules. The XML UMI that is imported by the rules evaluator from certificate attributes must be inserted into this XML document before the data can be used by the certificate. Similarly, to simplify the process of defining rules, the certificate rules must operate within the confines of the UMI XML model. The UMI XML model requires the XML document to contain the following top-level XML element, into which all target UMI for a particular rule evaluation is inserted. The XMLUMI element is created automatically as part of the rule evaluation process by the user mapping engine.<XMLUMI> <!--XML formatted UMI are inserted here. --> </XMLUMI>As a result of this restriction, the XPath to the data used in a Certificate User Mapping Rule must include the prefix /XMLUMI in order to access a particular data element within the model. For example, if a UMI item of stsuuser:STSUniversalUser is added to the document, you must specify the XPath /XMLUMI/stsuuser:STSUniversalUser in order to access the data contained in the XML object stsuuser:STSUniversalUser.An XPath is the path to a particular child element within the hierarchy of a structured XML data object. Much like a directory path on a hard drive is used to access a specific file, an XPath designation starts from the root of the document (in this case /XMLUMI) and traces a path from this root down through its child elements to the specific element that is being referenced. For example, using the example entitlement stsuuser:STSUniversalUser in the XML certificate model as a reference, you would use the following XPath to access the Version element of /XMLUMI/stsuuser:STSUniversalUser:"/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser: Attribute[@name='Version']/stsuuser:Value"XPaths like this example are the means by which user mapping rules access the UMI data values that are needed to make attribute-based user mapping decisions.Because all data elements are restricted to work within the UMI XML model, the user mapping rules must also be restricted to operate on or match XPaths within the model. Therefore, XSL template match statements are also restricted to matching XPaths starting from /XMLUMI within the UMI XML document. For additional information, see Format and constraints of rules.IntroductionWebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.

UMI XML document model

The Universal Management Infrastructure XML document model (or UMI XML model) is a set of restrictions placed on the XSL/XML model by the user mapping rules implementation, which enables the interface to be simple and yet functional for certificate purposes. The model constrains the certificate rules to function within a predetermined XML document format, with the same top-level XML document element for all rules. The XML UMI that is imported by the rules evaluator from certificate attributes must be inserted into this XML document before the data can be used by the certificate. Similarly, to simplify the process of defining rules, the certificate rules must operate within the confines of the UMI XML model.

The UMI XML model requires the XML document to contain the following top-level XML element, into which all target UMI for a particular rule evaluation is inserted. The XMLUMI element is created automatically as part of the rule evaluation process by the user mapping engine.

<XMLUMI>
<!--XML formatted UMI are inserted here.    -->
</XMLUMI>

As a result of this restriction, the XPath to the data used in a Certificate User Mapping Rule must include the prefix /XMLUMI in order to access a particular data element within the model. For example, if a UMI item of stsuuser:STSUniversalUser is added to the document, you must specify the XPath /XMLUMI/stsuuser:STSUniversalUser in order to access the data contained in the XML object stsuuser:STSUniversalUser.

An XPath is the path to a particular child element within the hierarchy of a structured XML data object. Much like a directory path on a hard drive is used to access a specific file, an XPath designation starts from the root of the document (in this case /XMLUMI) and traces a path from this root down through its child elements to the specific element that is being referenced. For example, using the example entitlement stsuuser:STSUniversalUser in the XML certificate model as a reference, you would use the following XPath to access the Version element of /XMLUMI/stsuuser:STSUniversalUser:

"/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:
Attribute[@name='Version']/stsuuser:Value"

XPaths like this example are the means by which user mapping rules access the UMI data values that are needed to make attribute-based user mapping decisions.

Because all data elements are restricted to work within the UMI XML model, the user mapping rules must also be restricted to operate on or match XPaths within the model. Therefore, XSL template match statements are also restricted to matching XPaths starting from /XMLUMI within the UMI XML document. For additional information, see Format and constraints of rules.

Parent topic: Introduction

Containers and XML UMI container namesContainers and XML UMI container namesUMIcontainers and container namesXMLUMI containers and container namescontainer namesUMI containersWhen data is requested from a resource manager, the granularity of the XML data returned is at the level of a single container of information. The container is normally also the smallest data element (for example, elements that might be considered for billing purposes). This convention also applies to the UMI XML model. The UMI that is used in user mapping rules is also defined and manipulated as containers of XML data. For example, the stsuuser:STSUniversalUser XML object defined in XML certificate model is an example of a UMI container.The topmost element in the definition of an item of UMI is referred to as the container name of that item of UMI. When defining a Certificate User Mapping Rule, the XPath to the XML definition of data in any UMI container must always be referenced using the name of the container as the first element following /XMLUMI in the XPath specification for the data element.Returning to the example UMI item stsuuser:STSUniversalUser, to access any element within the stsuuser:STSUniversalUser container, the XPath specification must be prefixed with stsuuser:STSUniversalUser. For example, "/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value" refers to the SerialNumber value. To access this information from within a Certificate User Mapping Rule, this XPath must also be prefixed by the top-level element of the XML target UMI input document, which is XMLUMI (for example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value"). A template match statement can be used to remove the need to completely specify the entire path. The example rule file contains a template match statement of /XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList, which means that all attributes of the certificate can be specified without a prefix. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value" is the same as "stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value". For additional information, see Format and constraints of rules.IntroductionWebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.

Containers and XML UMI container names

When data is requested from a resource manager, the granularity of the XML data returned is at the level of a single container of information. The container is normally also the smallest data element (for example, elements that might be considered for billing purposes). This convention also applies to the UMI XML model. The UMI that is used in user mapping rules is also defined and manipulated as containers of XML data. For example, the stsuuser:STSUniversalUser XML object defined in XML certificate model is an example of a UMI container.

The topmost element in the definition of an item of UMI is referred to as the container name of that item of UMI. When defining a Certificate User Mapping Rule, the XPath to the XML definition of data in any UMI container must always be referenced using the name of the container as the first element following /XMLUMI in the XPath specification for the data element.

Returning to the example UMI item stsuuser:STSUniversalUser, to access any element within the stsuuser:STSUniversalUser container, the XPath specification must be prefixed with stsuuser:STSUniversalUser. For example, "/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value" refers to the SerialNumber value. To access this information from within a Certificate User Mapping Rule, this XPath must also be prefixed by the top-level element of the XML target UMI input document, which is XMLUMI (for example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value").

A template match statement can be used to remove the need to completely specify the entire path. The example rule file contains a template match statement of /XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList, which means that all attributes of the certificate can be specified without a prefix. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value" is the same as "stsuuser:Attribute[@name='SerialNumber']/stsuuser:Value". For additional information, see Format and constraints of rules.

Parent topic: Introduction

XML certificate modelXML certificate modelXMLcertificate examplecertificatesXML exampleThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a Certificate User Mapping Rule. The document contains one container named stsuuser. The attribute value of the container stsuuser:STSUniversalUser is defined in XML. The certificate evaluator automatically encompasses all of the data under the XML top-level node declaration XMLUMI when the UMI XML document is created, so this top-level element is added for clarity.The XML document is automatically created by the CDAS, based on the attributes available within the client certificate. The XML document that is passed to the evaluation routines by the user mapping rules evaluator is as follows: <XMLUMI> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> -- Subject DN from certificate -- </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="--attr-name--" type="urn:ibm:security:gskit"> <stsuuser:Value>--attr-value--</stsuuser:Value> </stsuuser:Attribute> ... </stsuuser:AttributeList> </stsuuser:STSUniversalUser> </XMLUMI>For example: <?xml version="1.0" encoding='UTF-8'?> <XMLUMI> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> CN=testuser,O=ibm,C=au </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="SubjectDN" type="urn:ibm:security:gskit"> <stsuuser:Value>CN=testuser,O=ibm,C=au</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="IssuerDN" type="urn:ibm:security:gskit"> <stsuuser:Value>CN=ca,O=ibm,C=au</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="ValidFromEx" type="urn:ibm:security:gskit"> <stsuuser:Value>00:29:26 08-06-2009</stsuuser:Value> </stsuuser:Attribute> </stsuuser:AttributeList> </stsuuser:STSUniversalUser> </XMLUMI>For a full list of available attributes, see Valid certificate attributesThe client certificate attributes that are made available to the mapping rules are defined by the GSKit toolkit. .When referencing a particular UMI item within the XMLUMI document available to a rule, the XPath path specifier can begin from the container name of the XML element (for example, stsuuser:STSUniversalUser) . If the callers want to specify their own template match statement explicitly, they can do so.For additional information, see Format and constraints of rules.IntroductionWebSEAL uses the Cross Domain Authentication Service (CDAS) to authenticate a user and provide a Security Access Manager user identity.

XML certificate model

The following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a Certificate User Mapping Rule.

The document contains one container named stsuuser. The attribute value of the container stsuuser:STSUniversalUser is defined in XML.

The certificate evaluator automatically encompasses all of the data under the XML top-level node declaration XMLUMI when the UMI XML document is created, so this top-level element is added for clarity.

The XML document is automatically created by the CDAS, based on the attributes available within the client certificate. The XML document that is passed to the evaluation routines by the user mapping rules evaluator is as follows:

<XMLUMI>
<stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
<stsuuser:Principal>
<stsuuser:Attribute name="name">
<stsuuser:Value>
-- Subject DN from certificate --
</stsuuser:Value>
</stsuuser:Attribute>
</stsuuser:Principal>
<stsuuser:AttributeList>
<stsuuser:Attribute name="--attr-name--" type="urn:ibm:security:gskit">
<stsuuser:Value>--attr-value--</stsuuser:Value>
</stsuuser:Attribute>
...
</stsuuser:AttributeList>
</stsuuser:STSUniversalUser>
</XMLUMI>

For example:

<?xml version="1.0" encoding='UTF-8'?>

<XMLUMI>
<stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
<stsuuser:Principal>
<stsuuser:Attribute name="name">
<stsuuser:Value>
CN=testuser,O=ibm,C=au
</stsuuser:Value>
</stsuuser:Attribute>
</stsuuser:Principal>
<stsuuser:AttributeList>
<stsuuser:Attribute name="SubjectDN" type="urn:ibm:security:gskit">
<stsuuser:Value>CN=testuser,O=ibm,C=au</stsuuser:Value>
</stsuuser:Attribute>

<stsuuser:Attribute name="IssuerDN" type="urn:ibm:security:gskit">
<stsuuser:Value>CN=ca,O=ibm,C=au</stsuuser:Value>
</stsuuser:Attribute>

<stsuuser:Attribute name="ValidFromEx" type="urn:ibm:security:gskit">
<stsuuser:Value>00:29:26 08-06-2009</stsuuser:Value>
</stsuuser:Attribute>

</stsuuser:AttributeList>
</stsuuser:STSUniversalUser>
</XMLUMI>

For a full list of available attributes, see Valid certificate attributes.

When referencing a particular UMI item within the XMLUMI document available to a rule, the XPath path specifier can begin from the container name of the XML element (for example, stsuuser:STSUniversalUser) . If the callers want to specify their own template match statement explicitly, they can do so.

For additional information, see Format and constraints of rules.

Parent topic: Introduction

User mapping rules evaluatorUser mapping rules evaluatoruser mappingrulesevaluatordelimitersevaluatoruser mapping rulesdelimitersThe user mapping rules evaluator evaluates user mapping rules within the constraints that are required by the user mapping engine. Pre-configured rules are supplied in a configuration file to the new CDAS.The user mapping rules evaluator takes the rule policy along with the XML representation of the certificate and passes this to the XSL processor for evaluation. The input for the transformation is the XML version of the client certificate (as defined above). XSL transformation rules decide how the Security Access Manager user name is mapped from the supplied certificate information. Two inputs are used when making the decision: the XML representation of the client certificate, andthe XSL rule, which determines how the XML is interpreted.The output from the decision is a single string which is used to determine the Security Access Manager user identity.The user mapping engine expects the rules evaluation to result in the return of one of the string identifiers listed below. These identifiers ensure uniqueness in the event that an XSL rule is written incorrectly and the evaluation returns incorrect information. Delimiting the identifiers with an exclamation point (!) enables the evaluator to identify errant cases. The string must conform to one of the following definitions:!free format text!Free format text, which could also include elements from the source XML. This string will be used as the Security Access Manager user identity. For example: !cn=testuser,o=ibm,c=au! !<xsl:value-of select="stsuuser:Attribute[@name='SerialNumber']/ stsuuser:Value"/>!!userreg base='%base%' attr='%name%'!%ldap-search-filter%! Indicates that the user registry should be searched for the Security Access Manager user identity, based on the supplied search string. The attr value is used to define the name of the LDAP attribute which holds the Security Access Manager user identity. The search string should conform to RFC 2254. For example: !userreg base='o=ibm,c=au' attr='cn'! (&amp;(objectClass=ePerson) (serialNum=<xsl:value-of select="stsuuser:Attribute[@name= 'SerialNumber']/stsuuser:Value"/>))! !no-matching-rule!Indicates that no matching rule was found for the supplied client certificate. If this string is returned from the rule evaluation the CDAS will return an error. For example: !no-matching-rule!The ampersand (&) character cannot be used in XSLT documents or it will produce errors when processed. This character must be transcribed as &amp;.Client Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Format and constraints of rulesExamples of user mapping rules

User mapping rules evaluator

The user mapping rules evaluator evaluates user mapping rules within the constraints that are required by the user mapping engine. Pre-configured rules are supplied in a configuration file to the new CDAS.

The user mapping rules evaluator takes the rule policy along with the XML representation of the certificate and passes this to the XSL processor for evaluation.

The input for the transformation is the XML version of the client certificate (as defined above). XSL transformation rules decide how the Security Access Manager user name is mapped from the supplied certificate information. Two inputs are used when making the decision:

the XML representation of the client certificate, and

the XSL rule, which determines how the XML is interpreted.

The output from the decision is a single string which is used to determine the Security Access Manager user identity.

The user mapping engine expects the rules evaluation to result in the return of one of the string identifiers listed below. These identifiers ensure uniqueness in the event that an XSL rule is written incorrectly and the evaluation returns incorrect information. Delimiting the identifiers with an exclamation point (!) enables the evaluator to identify errant cases.

The string must conform to one of the following definitions:

!free format text!

Free format text, which could also include elements from the source XML. This string will be used as the Security Access Manager user identity. For example:

!cn=testuser,o=ibm,c=au!
!<xsl:value-of select="stsuuser:Attribute[@name='SerialNumber']/
stsuuser:Value"/>!

!userreg base='%base%' attr='%name%'!%ldap-search-filter%!

Indicates that the user registry should be searched for the Security Access Manager user identity, based on the supplied search string. The attr value is used to define the name of the LDAP attribute which holds the Security Access Manager user identity. The search string should conform to RFC 2254. For example:

!userreg base='o=ibm,c=au' attr='cn'! (&amp;(objectClass=ePerson)
(serialNum=<xsl:value-of select="stsuuser:Attribute[@name=
'SerialNumber']/stsuuser:Value"/>))!

!no-matching-rule!

Indicates that no matching rule was found for the supplied client certificate. If this string is returned from the rule evaluation the CDAS will return an error. For example:

!no-matching-rule!

Note: The ampersand (&) character cannot be used in XSLT documents or it will produce errors when processed. This character must be transcribed as &amp;.

Format and constraints of rules

Examples of user mapping rules

Parent topic: Client Certificate User Mapping

Format and constraints of rulesFormat and constraints of rulesuser mappingrulesformat and constraintsformatuser mapping rulesconstraintsuser mapping rulesstringsidentifiersazn_entitlement_get_entitlements() methodxsl:template statementXSLxsl:template statementA Certificate User Mapping Rule must be defined as an XSL template in an XSL stylesheet. The rule must be written in a valid XSL template rule format. It must return a text document that contains one of the string identifiers shown in User mapping rules evaluator.The identifiers must be the only text in the output document, although they can be surrounded by white space. If a value other than the defined values or an empty document is returned, the user mapping fails and an error code is returned to the CDAS to indicate that the rule is not compliant. The result of the XSL transformation performed by an XSL Certificate User Mapping Rule must be a text output document that contains only one of the supported string identifiers.The following Certificate User Mapping Rule example references the XML data item that is defined in stsuuser:STSUniversalUser. The condition that the rule evaluates is expressed as follows: <?xml version="1.0" encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser= "urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0"> <!-- Required to constrain output of rule evaluation --> <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8' indent= "no"/> <!-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template> <!-- Let's make it easier by matching the constant part of our XML name --> <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList"> <!-- If this certificate was issued by our CA, just use the subject dn --> <xsl:when test='stsuuser:Attribute[@name="IssuerDN"]/stsuuser:Value = "cn=ca,o=ibm,c=au"'> !<xsl:value-of select="stsuuser:Attribute[@name='SubjectDN']/ stsuuser:Value"/>! </xsl:when> <!-- If this certificate was issued by the tivoli CA, search for the certificate serial number --> <xsl:when test='stsuuser:Attribute[@name="IssuerDN"]/stsuuser:Value = "cn=ca,o=tivoli,c=au"'> !userreg base='o=ibm,c=us' attr='cn'!secCertSerialNumber=<xsl: value-of select="stsuuser:Attribute[@name='SerialNumber']/ stsuuser:Value"/>! </xsl:when> <!-- Otherwise we don't have a matching rule.'no-matching-rule' is a special string. --> <xsl:otherwise> !no-matching-rule! </xsl:otherwise> </xsl:template> </xsl:stylesheet> Everything up to and including the template match is static for all rules. Remaining parts of the XSL rule can be customized. To reference any data item in the document, the XPath to each node must include the XMLUMI node. When a rule is built, the rule writer must understand what the correct XPath is from the current point in the tree, in order to access the XML data nodes and subnodes. The current point in the tree is selected by using the template match statement. The template match statement allows an XSL programmer to shorten the XPath to each data element by specifying that the XPath processing must occur further down the XML document tree.The <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList"> statement tells the XSL processor that all relative XPaths within the bounds of the template statement should be assumed to be relative to the node "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList". For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='IssuerDN']/stsuuser:Value" can be referred to as simply "stsuuser:Attribute[@name='IssuerDN']/stsuuser:Value".User mapping rules evaluator

Format and constraints of rules

A Certificate User Mapping Rule must be defined as an XSL template in an XSL stylesheet. The rule must be written in a valid XSL template rule format. It must return a text document that contains one of the string identifiers shown in User mapping rules evaluator.

The identifiers must be the only text in the output document, although they can be surrounded by white space. If a value other than the defined values or an empty document is returned, the user mapping fails and an error code is returned to the CDAS to indicate that the rule is not compliant.

The result of the XSL transformation performed by an XSL Certificate User Mapping Rule must be a text output document that contains only one of the supported string identifiers.

The following Certificate User Mapping Rule example references the XML data item that is defined in stsuuser:STSUniversalUser. The condition that the rule evaluates is expressed as follows:

<?xml version="1.0" encoding='UTF-8'?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser=
"urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0">

<!-- Required to constrain output of rule evaluation -->
<xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8' indent=
"no"/>

<!-- Need this to ensure default text node printing is off -->
<xsl:template match="text()"></xsl:template>

<!-- Let's make it easier by matching the constant part of our XML name -->
<xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList">

<!-- If this certificate was issued by our CA, just use the subject dn -->
<xsl:when test='stsuuser:Attribute[@name="IssuerDN"]/stsuuser:Value =
"cn=ca,o=ibm,c=au"'>
!<xsl:value-of select="stsuuser:Attribute[@name='SubjectDN']/
stsuuser:Value"/>!
</xsl:when>

<!-- If this certificate was issued by the tivoli CA, search for the
certificate serial number -->
<xsl:when test='stsuuser:Attribute[@name="IssuerDN"]/stsuuser:Value =
"cn=ca,o=tivoli,c=au"'>
!userreg base='o=ibm,c=us' attr='cn'!secCertSerialNumber=<xsl:
value-of select="stsuuser:Attribute[@name='SerialNumber']/
stsuuser:Value"/>!
</xsl:when>

<!-- Otherwise we don't have a matching rule.'no-matching-rule' is a
special string. -->
<xsl:otherwise>
!no-matching-rule!
</xsl:otherwise>

</xsl:template>

</xsl:stylesheet>

Note: Everything up to and including the template match is static for all rules. Remaining parts of the XSL rule can be customized.

To reference any data item in the document, the XPath to each node must include the XMLUMI node. When a rule is built, the rule writer must understand what the correct XPath is from the current point in the tree, in order to access the XML data nodes and subnodes. The current point in the tree is selected by using the template match statement. The template match statement allows an XSL programmer to shorten the XPath to each data element by specifying that the XPath processing must occur further down the XML document tree.

The <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList"> statement tells the XSL processor that all relative XPaths within the bounds of the template statement should be assumed to be relative to the node "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList". For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='IssuerDN']/stsuuser:Value" can be referred to as simply "stsuuser:Attribute[@name='IssuerDN']/stsuuser:Value".

Parent topic: User mapping rules evaluator

Examples of user mapping rulesExamples of user mapping rulesuser mappingrulesUMI examplesattributesazn_cred_principal_nameazn_cred_groupsazn_cred_registry_idazn_cred_principal_name attributeazn_cred_groups attributeazn_cred_registry_id attributexsl:when statementThis section provides two examples of output XSLT evaluation, first using a free format text string and then searching the user registry for the user DN. In the first example, the rule works on a string from the client certificate: if the string matches then it selects the Distinguished Name (DN) from the client certificate. Rule: <!-- Test a valid 'free format' string. --> <xsl:when test='stsuuser:Attribute[@name="SubjectDN"] /stsuuser:Value = "cn=testuser,o=ibm,c=au"'> !<xsl:value-of select="stsuuser:Attribute[@name='SubjectDN']/ stsuuser:Value"/>! </xsl:when>Details from Client Certificate: <stsuuser:STSUniversalUser xmlns:stsuuser= "urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> CN=testuser,O=ibm,C=au </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="SubjectDN" type= "urn:ibm:security:gskit"> <stsuuser:Value>CN=testuser,O=ibm,C=au</stsuuser:Value> </stsuuser:Attribute> ... </stsuuser:AttributeList> </stsuuser:STSUniversalUser>String returned by CDAS: CN=testuser,O=ibm,C=auIn the second example, the rule searches the user registry for an attribute and returns the user Common Name (CN) from the registry. In this case the search of the registry is on the e-mail address from the client certificate. Rule: <!-- Test a matching 'userreg' string. --> <xsl:when test='stsuuser:Attribute[@name="SubjectDN"] /stsuuser:Value = "cn=testuser3,o=ibm,c=au"'> !userreg base='o=ibm,c=au' attr='cn'!(description=<xsl:value-of select="stsuuser:Attribute[@name='SubjectEmail']/ stsuuser:Value"/>)! </xsl:when>Details from Client Certificate: <stsuuser:STSUniversalUser xmlns:stsuuser= "urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> cn=testuser3,o=ibm,c=au </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="SubjectDN" type= "urn:ibm:security:gskit"> <stsuuser:Value>cn=testuser3,o=ibm,c=au</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="SubjectEmail" type= "urn:ibm:security:gskit"> <stsuuser:Value>testuser3@ibm.com</stsuuser:Value> </stsuuser:Attribute> ... </stsuuser:AttributeList> </stsuuser:STSUniversalUser>String returned from user registry: cn=testuser3User mapping rules evaluator

Examples of user mapping rules

This section provides two examples of output XSLT evaluation, first using a free format text string and then searching the user registry for the user DN.

In the first example, the rule works on a string from the client certificate: if the string matches then it selects the Distinguished Name (DN) from the client certificate.

Rule:

<!-- Test a valid 'free format' string. -->
<xsl:when test='stsuuser:Attribute[@name="SubjectDN"]
/stsuuser:Value = "cn=testuser,o=ibm,c=au"'>
!<xsl:value-of select="stsuuser:Attribute[@name='SubjectDN']/
stsuuser:Value"/>!
</xsl:when>

Details from Client Certificate:

<stsuuser:STSUniversalUser xmlns:stsuuser=
"urn:ibm:names:ITFIM:1.0:stsuuser">
<stsuuser:Principal>
<stsuuser:Attribute name="name">
<stsuuser:Value>
CN=testuser,O=ibm,C=au
</stsuuser:Value>
</stsuuser:Attribute>
</stsuuser:Principal>
<stsuuser:AttributeList>
<stsuuser:Attribute name="SubjectDN" type=
"urn:ibm:security:gskit">
<stsuuser:Value>CN=testuser,O=ibm,C=au</stsuuser:Value>
</stsuuser:Attribute>
...
</stsuuser:AttributeList>
</stsuuser:STSUniversalUser>

String returned by CDAS:

CN=testuser,O=ibm,C=au

In the second example, the rule searches the user registry for an attribute and returns the user Common Name (CN) from the registry. In this case the search of the registry is on the e-mail address from the client certificate.

Rule:

<!-- Test a matching 'userreg' string. -->
<xsl:when test='stsuuser:Attribute[@name="SubjectDN"]
/stsuuser:Value = "cn=testuser3,o=ibm,c=au"'>
!userreg base='o=ibm,c=au' attr='cn'!(description=<xsl:value-of
select="stsuuser:Attribute[@name='SubjectEmail']/
stsuuser:Value"/>)!
</xsl:when>

Details from Client Certificate:

<stsuuser:STSUniversalUser xmlns:stsuuser=
"urn:ibm:names:ITFIM:1.0:stsuuser">
<stsuuser:Principal>
<stsuuser:Attribute name="name">
<stsuuser:Value>
cn=testuser3,o=ibm,c=au
</stsuuser:Value>
</stsuuser:Attribute>
</stsuuser:Principal>
<stsuuser:AttributeList>
<stsuuser:Attribute name="SubjectDN" type=
"urn:ibm:security:gskit">
<stsuuser:Value>cn=testuser3,o=ibm,c=au</stsuuser:Value>
</stsuuser:Attribute>
<stsuuser:Attribute name="SubjectEmail" type=
"urn:ibm:security:gskit">
<stsuuser:Value>testuser3@ibm.com</stsuuser:Value>
</stsuuser:Attribute>
...
</stsuuser:AttributeList>
</stsuuser:STSUniversalUser>

String returned from user registry:

cn=testuser3

Parent topic: User mapping rules evaluator

How to manage the CDASHow to manage the CDASCDASmanageThis section describes how to add the CDAS into WebSEAL, and how to configure the CDAS.Client Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Enabling the CDAS functionalityYou can enable the extended CDAS functionality.Valid certificate attributesThe client certificate attributes that are made available to the mapping rules are defined by the GSKit toolkit.

How to manage the CDAS

This section describes how to add the CDAS into WebSEAL, and how to configure the CDAS.

Enabling the CDAS functionality
You can enable the extended CDAS functionality.

Valid certificate attributes
The client certificate attributes that are made available to the mapping rules are defined by the GSKit toolkit.

Parent topic: Client Certificate User Mapping

Enabling the CDAS functionalityEnabling the CDAS functionalityYou can enable the extended CDAS functionality.LMIClient Certificate Mapping management pageCDASenabling functionalityfunctionality To enable the extended CDAS functionality: You must update the [cert-map-authn] stanza in the WebSEAL configuration file as follows: [cert-map-authn] rules-file = file debug-level = level where: fileThe name of the rules file for the certificate mapping CDAS to use.levelControls the trace level for the module. For example:[cert-map-authn] rules-file = cert-rules.txt debug-level = 5 The level variable indicates the trace level, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing. You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.certmap. This trace component is only available after the first HTTP request is processed.You can use the Local Management Interface (LMI) to modify the rules file (for example, cert-rules.txt) as required: Select Secure Web Settings > Global Settings > Client Certificate Mapping from the top menu. The Client Certificate Mapping management page displays.(Optional) If no rules files exist, you can click New to create a new rules file. Enter a name for the new file such as cert-rules.txt and click Save. A new file is generated that is based on the default template. Click the file that you want to manage, such as cert-rules.txt, from the available list of File Names. Click Edit.Update the file.Click Save.How to manage the CDAS

Enabling the CDAS functionality

You can enable the extended CDAS functionality.

About this task

To enable the extended CDAS functionality:

Procedure

You must update the [cert-map-authn] stanza in the WebSEAL configuration file as follows:

[cert-map-authn]
rules-file = file
debug-level = level

where:

file

The name of the rules file for the certificate mapping CDAS to use.

level

Controls the trace level for the module.

For example:

[cert-map-authn]
rules-file = cert-rules.txt
debug-level = 5

Note: The level variable indicates the trace level, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing. You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.certmap. This trace component is only available after the first HTTP request is processed.

You can use the Local Management Interface (LMI) to modify the rules file (for example, cert-rules.txt) as required:

Select Secure Web Settings > Global Settings > Client Certificate Mapping from the top menu. The Client Certificate Mapping management page displays.

(Optional) If no rules files exist, you can click New to create a new rules file. Enter a name for the new file such as cert-rules.txt and click Save. A new file is generated that is based on the default template.

Click the file that you want to manage, such as cert-rules.txt, from the available list of File Names.

Click Edit.

Update the file.

Click Save.

Parent topic: How to manage the CDAS

Valid certificate attributesValid certificate attributesThe client certificate attributes that are made available to the mapping rules are defined by the GSKit toolkit. certificate attributesvalidFor WebSEAL, this can be any of the following attributes: * Base64Certificate * SerialNumber * SubjectCN * SubjectLocality * SubjectState * SubjectCountry * SubjectOrganization * SubjectOrganizationalUnit * SubjectDN * SubjectPostalCode * SubjectEmail * SubjectUniqueID * IssuerCN * IssuerLocality * IssuerState * IssuerCountry * IssuerOrganization * IssuerOrganizationUnit * IssuerDN * IssuerPostalCode * IssuerEmail * IssuerUniqueID * Version * SignatureAlgorithm * ValidFrom * ValidFromEx * ValidTo * ValidToEx * PublicKeyAlgorithm * PublicKey * PublicKeySize * FingerprintAlgorithm * Fingerprint * BasicConstraintsCA * BasicConstraintsPathLength * DerCertificate * CertificatePolicyID * CRLDistributionPoints * DerSubjectDN * DerIssuerDN * KeyUsage * AlternativeDirectoryName * AlternativeDNSName * AlternativeIPAddress * AlternativeURI * AlternativeEmailFor more information about GSKit, see the IBM Secure Sockets Layer Introduction and iKeyman User's Guide.How to manage the CDAS

Valid certificate attributes

The client certificate attributes that are made available to the mapping rules are defined by the GSKit toolkit.

For WebSEAL, this can be any of the following attributes:

* Base64Certificate
* SerialNumber
* SubjectCN
* SubjectLocality
* SubjectState
* SubjectCountry
* SubjectOrganization
* SubjectOrganizationalUnit
* SubjectDN
* SubjectPostalCode
* SubjectEmail
* SubjectUniqueID
* IssuerCN
* IssuerLocality
* IssuerState
* IssuerCountry
* IssuerOrganization
* IssuerOrganizationUnit
* IssuerDN
* IssuerPostalCode
* IssuerEmail
* IssuerUniqueID
* Version
* SignatureAlgorithm
* ValidFrom
* ValidFromEx
* ValidTo
* ValidToEx
* PublicKeyAlgorithm
* PublicKey
* PublicKeySize
* FingerprintAlgorithm
* Fingerprint
* BasicConstraintsCA
* BasicConstraintsPathLength
* DerCertificate
* CertificatePolicyID
* CRLDistributionPoints
* DerSubjectDN
* DerIssuerDN
* KeyUsage
* AlternativeDirectoryName
* AlternativeDNSName
* AlternativeIPAddress
* AlternativeURI
* AlternativeEmail

For more information about GSKit, see the IBM® Secure Sockets Layer Introduction and iKeyman User's Guide.

Parent topic: How to manage the CDAS

Configuring WebSEAL to use the certificate mapping moduleConfiguring WebSEAL to use the certificate mapping moduleConfiguring WebSEAL to use the certificate mapping moduleWebSEALcertificate mapping modulecertificate mapping moduleCheck the accept-client-certs entry within the [certificate] stanza. The value of this entry should be required, optional, or prompt_as_needed. This determines if and when a user is prompted to provide a client certificate by the browser. For more details about the different values for this entry, see Client-side certificate authentication modes.Save the configuration file. Restart WebSEAL to implement the updates.Client Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Constructing the XSLT rules fileYou can use the mapping module to define flexible rules that allow mapping of certificate attributes to a user identity. The user identity can be a Security Access Manager user ID. For example, testuser. Alternatively, the user identity can be the user DN as found in the registry. For example, cn=testuser, o=ibm,c=au.Validating a successful module mappingTo confirm a successful module mapping for users, ensure that a Security Access Manager policy is set for a protected resource to refuse unauthenticated users and allow authenticated ones.

Configuring WebSEAL to use the certificate mapping module

Procedure

Check the accept-client-certs entry within the [certificate] stanza. The value of this entry should be required, optional, or prompt_as_needed. This determines if and when a user is prompted to provide a client certificate by the browser.

For more details about the different values for this entry, see Client-side certificate authentication modes.

Save the configuration file.

Restart WebSEAL to implement the updates.

Constructing the XSLT rules file
You can use the mapping module to define flexible rules that allow mapping of certificate attributes to a user identity. The user identity can be a Security Access Manager user ID. For example, testuser. Alternatively, the user identity can be the user DN as found in the registry. For example, cn=testuser, o=ibm,c=au.

Validating a successful module mapping
To confirm a successful module mapping for users, ensure that a Security Access Manager policy is set for a protected resource to refuse unauthenticated users and allow authenticated ones.

Parent topic: Client Certificate User Mapping

Constructing the XSLT rules fileConstructing the XSLT rules fileConstructing the XSLT rules fileYou can use the mapping module to define flexible rules that allow mapping of certificate attributes to a user identity. The user identity can be a Security Access Manager user ID. For example, testuser. Alternatively, the user identity can be the user DN as found in the registry. For example, cn=testuser, o=ibm,c=au.XSLT rules filerulesXSLT fileUpon receiving a user certificate, the module creates an XML document that lists all of its attributes. The XML document conforms to the Universal Management Infrastructure (UMI) XML document model. For example, the module could create a document that looks like this:<?xml version="1.0" encoding='UTF-8'?> <XMLUMI> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> CN=testuser,O=ibm,C=au </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="SubjectDN" type="urn:ibm:security:gskit"> <stsuuser:Value>CN=testuser,O=ibm,C=au</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="IssuerDN" type="urn:ibm:security:gskit"> <stsuuser:Value>CN=ca,O=ibm,C=au</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="ValidFromEx" type="urn:ibm:security:gskit"> <stsuuser:Value>00:29:26 08-06-2009</stsuuser:Value> </stsuuser:Attribute> </stsuuser:AttributeList> </stsuuser:STSUniversalUser> </XMLUMI>The XSLT file defines how to transform the XML document. The result of the transformation must be in one of these forms:!identifier!A Security Access Manager user ID or user DN. This form is used when no registry search is required, such as when the identifier can be retrieved directly from the certificate.!userreg base='baseDN' attr='attrName'! ldapSearchFilter !baseDN is the base distinguished name, attrName is the LDAP attribute name that corresponds to a user identity, and ldapSearchFilter is the LDAP search filter. This form is used when certificate information is used to search the registry for the corresponding user. You can also use the module with Active Directory.!no-matching-rule!This form indicates that you cannot use any rule to find the required information to authenticate the user.The following example is the cert-rules-template.txt file installed in the $WEBRTE_HOME/etc/ directory:<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0"> <!-- Required to constrain output of rule evaluation --> <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/> <!-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template> <!-- Let's make it easier by matching the constant part of our XML name --> <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser: AttributeList"> !<xsl:value-of select="stsuuser:Attribute[@name='SubjectDN']/stsuuser: Value"/>! </xsl:template> </xsl:stylesheet> This XSLT document transforms the UMI XML document created by the authentication module and outputs the subject DN of the certificate it receives between ! characters. For example, !cn=testuser,o=ibm,c=au!.In this case, no user registry search is performed. This <xsl:output> element is required to indicate that text, not an XML document, is the output of the transformation. This first <xsl:template> element ensures that any remaining text nodes in the document are not copied to the output.The next example shows how to direct the mapping module to perform a user registry, for example, LDAP, search with data from the certificate. It extracts the value of the SubjectEmail attribute from the certificate and searches for a user with an LDAP mail attribute equal to this address. The base DN for the search is o=ibm,c=au. The value of the cn attribute is printed in the output. In this case, the result will probably be a Security Access Manager user ID, rather than a user DN.<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0"> <!-- Required to constrain output of rule evaluation --> <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/> <!-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template> <!-- Let's make it easier by matching the constant part of our XML name --> <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser: AttributeList"> !userreg base='o=ibm,c=au' attr='cn'!(mail=<xsl:value-of select="stsuuser:Attribute[@name='SubjectEmail']/stsuuser: Value"/>)! </xsl:template> </xsl:stylesheet>Because the & character is used in XML to demarcate the start of an entity, it cannot be used as is in the LDAP search filter. If an LDAP query contains multiple terms that need to be joined, the &amp; entity needs to be used instead.Configuring WebSEAL to use the certificate mapping module

Constructing the XSLT rules file

You can use the mapping module to define flexible rules that allow mapping of certificate attributes to a user identity. The user identity can be a Security Access Manager user ID. For example, testuser. Alternatively, the user identity can be the user DN as found in the registry. For example, cn=testuser, o=ibm,c=au.

Upon receiving a user certificate, the module creates an XML document that lists all of its attributes. The XML document conforms to the Universal Management Infrastructure (UMI) XML document model. For example, the module could create a document that looks like this:

<?xml version="1.0" encoding='UTF-8'?>

<XMLUMI>
  <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
    <stsuuser:Principal>
      <stsuuser:Attribute name="name">
        <stsuuser:Value>
          CN=testuser,O=ibm,C=au
        </stsuuser:Value>
      </stsuuser:Attribute>
    </stsuuser:Principal>
    <stsuuser:AttributeList>
      <stsuuser:Attribute name="SubjectDN" type="urn:ibm:security:gskit">
        <stsuuser:Value>CN=testuser,O=ibm,C=au</stsuuser:Value>
      </stsuuser:Attribute>

      <stsuuser:Attribute name="IssuerDN" type="urn:ibm:security:gskit">
        <stsuuser:Value>CN=ca,O=ibm,C=au</stsuuser:Value>
      </stsuuser:Attribute>

      <stsuuser:Attribute name="ValidFromEx" type="urn:ibm:security:gskit">
        <stsuuser:Value>00:29:26 08-06-2009</stsuuser:Value>
      </stsuuser:Attribute>

     </stsuuser:AttributeList>
  </stsuuser:STSUniversalUser>
</XMLUMI>

The XSLT file defines how to transform the XML document. The result of the transformation must be in one of these forms:

!identifier!

A Security Access Manager user ID or user DN. This form is used when no registry search is required, such as when the identifier can be retrieved directly from the certificate.

!userreg base='baseDN' attr='attrName'! ldapSearchFilter !

baseDN is the base distinguished name, attrName is the LDAP attribute name that corresponds to a user identity, and ldapSearchFilter is the LDAP search filter.

This form is used when certificate information is used to search the registry for the corresponding user. You can also use the module with Active Directory.

!no-matching-rule!

This form indicates that you cannot use any rule to find the required information to authenticate the user.

The following example is the cert-rules-template.txt file installed in the $WEBRTE_HOME/etc/ directory:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0">

    <!-- Required to constrain output of rule evaluation -->
    <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8'
indent="no"/>

    <!-- Need this to ensure default text node printing is off -->
    <xsl:template match="text()"></xsl:template>

    <!-- Let's make it easier by matching the constant part of our XML name -->
    <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:
AttributeList">
        !<xsl:value-of select="stsuuser:Attribute[@name='SubjectDN']/stsuuser:
Value"/>!
    </xsl:template>

</xsl:stylesheet>

This XSLT document transforms the UMI XML document created by the authentication module and outputs the subject DN of the certificate it receives between ! characters. For example, !cn=testuser,o=ibm,c=au!.

In this case, no user registry search is performed. This <xsl:output> element is required to indicate that text, not an XML document, is the output of the transformation.

This first <xsl:template> element ensures that any remaining text nodes in the document are not copied to the output.

The next example shows how to direct the mapping module to perform a user registry, for example, LDAP, search with data from the certificate. It extracts the value of the SubjectEmail attribute from the certificate and searches for a user with an LDAP mail attribute equal to this address.

The base DN for the search is o=ibm,c=au. The value of the cn attribute is printed in the output. In this case, the result will probably be a Security Access Manager user ID, rather than a user DN.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0">

    <!-- Required to constrain output of rule evaluation -->
    <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8'
indent="no"/>

    <!-- Need this to ensure default text node printing is off -->
    <xsl:template match="text()"></xsl:template>

    <!-- Let's make it easier by matching the constant part of our XML name -->
    <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:
AttributeList">
        !userreg base='o=ibm,c=au' attr='cn'!(mail=<xsl:value-of
				select="stsuuser:Attribute[@name='SubjectEmail']/stsuuser:
Value"/>)!
    </xsl:template>

</xsl:stylesheet>

Note: Because the & character is used in XML to demarcate the start of an entity, it cannot be used as is in the LDAP search filter. If an LDAP query contains multiple terms that need to be joined, the &amp; entity needs to be used instead.

Parent topic: Configuring WebSEAL to use the certificate mapping module

Validating a successful module mappingValidating a successful module mappingValidating a successful module mappingTo confirm a successful module mapping for users, ensure that a Security Access Manager policy is set for a protected resource to refuse unauthenticated users and allow authenticated ones.modulesmapping success validationmodule mappingBefore accessing this resource in a browser, ensure that the client certificate is imported into the browser. See your browser help for instructions on how to import.When attempting to access a protected resource, the browser prompts you to select a client certificate. Select the client certificate which you just imported into the browser.The WebSEAL log contains trace messages pertinent to the mapping module, indicating success or failure, assuming that the debugging level was set appropriately in the WebSEAL configuration file as described in Configuring WebSEAL to use the certificate mapping module.The result of the XSLT transformation dictates whether the mapping module must perform a user registry search or not. The mapping module conducts a user registry search if the result is in the following form:!userreg base='baseDN' attr='attrName' ! ldapSearchFilter!Otherwise, the mapping module does not conduct a user registry search. The result of the search is a Security Access Manager user ID or a DN of a user. If the mapping is successful and a search was performed in the user registry, the following message displays in the WebSEAL log. The WebSEAL log is typically at /var/pdweb/log/msg_webseal-instance.log on UNIX machines. It is at C:\Program Files\Tivoli\PDWeb\log\msg_webseal-instance.log on Windows machines:2012-06-07-16:37:11.113+10:00I----- thread(2) trace.pd.cas.certmap:5 /sandbox/amwebrte611/src/pdwebrte/authn/modules/certmapauthn/AMWCertLDAPUserRegistry.cpp:146: ISAM user identity: testuserIf no search was performed in the registry, only a message similar to the following is displayed:2012-06-07-18:34:29.200+10:00I----- thread(2) trace.pd.cas.certmap:3 /sandbox/amwebrte611/src/pdwebrte/authn/modules/certmapauthn/AMWCertRulesEngine.cpp:219: result: CN=testuser,O=IBM,C=AUConfiguring WebSEAL to use the certificate mapping module

Validating a successful module mapping

To confirm a successful module mapping for users, ensure that a Security Access Manager policy is set for a protected resource to refuse unauthenticated users and allow authenticated ones.

Before you begin

Before accessing this resource in a browser, ensure that the client certificate is imported into the browser. See your browser help for instructions on how to import.

Procedure

When attempting to access a protected resource, the browser prompts you to select a client certificate. Select the client certificate which you just imported into the browser. The WebSEAL log contains trace messages pertinent to the mapping module, indicating success or failure, assuming that the debugging level was set appropriately in the WebSEAL configuration file as described in Configuring WebSEAL to use the certificate mapping module.

The result of the XSLT transformation dictates whether the mapping module must perform a user registry search or not. The mapping module conducts a user registry search if the result is in the following form:

!userreg base='baseDN' attr='attrName' ! ldapSearchFilter!

Otherwise, the mapping module does not conduct a user registry search. The result of the search is a Security Access Manager user ID or a DN of a user.

If the mapping is successful and a search was performed in the user registry, the following message displays in the WebSEAL log. The WebSEAL log is typically at /var/pdweb/log/msg_webseal-instance.log on UNIX machines. It is at C:\Program Files\Tivoli\PDWeb\log\msg_webseal-instance.log on Windows machines:

2012-06-07-16:37:11.113+10:00I----- thread(2) trace.pd.cas.certmap:5 /sandbox/amwebrte611/src/pdwebrte/authn/modules/certmapauthn/AMWCertLDAPUserRegistry.cpp:146: ISAM user identity: testuser

If no search was performed in the registry, only a message similar to the following is displayed:

2012-06-07-18:34:29.200+10:00I----- thread(2) trace.pd.cas.certmap:3 /sandbox/amwebrte611/src/pdwebrte/authn/modules/certmapauthn/AMWCertRulesEngine.cpp:219: result: CN=testuser,O=IBM,C=AU

Parent topic: Configuring WebSEAL to use the certificate mapping module

Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. authenticated usersmappingoverviewDuring the authentication process, Security Access Manager takes an XML representation of the authentication data and then evaluates the data against an XSLT rule to produce the appropriate user identity. The result is either a static user identity or an LDAP search string that you can use to locate the user identity. In addition, one or more attributes might be added to the generated credential for the user.The authenticated user mapping module cannot be invoked if an EAI authentication takes place, where a privileged attribute certificate (PAC) is supplied as the authentication data.Advanced authentication methodsMultiplexing proxy agentsSwitch user authenticationReauthenticationAuthentication strength policy (step-up)External authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strengthThe password strength module validates the strength of new passwords. Authenticated user mapping rule languageExtensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is the language for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both the inputs to the rules evaluator and the rules themselves.UMI XML document modelThe Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the user mapping rules implementation. This model enables the interface to be simple and yet functional for user mapping purposes.Containers and XML UMI container namesWhen data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element. For example, elements that might be considered for billing purposes.XML user mapping modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of an authenticated user mapping rule. User mapping rules evaluatorThe user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module.Enabling authenticated user mappingThe authenticated user mapping module is disabled by default. You must enable it before you can map an authenticated user name to a different Security Access Manager user identity.Valid user mapping attributesA list of authenticated user mapping attributes can be used in the mapping rules.

Authenticated User Mapping

You can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

During the authentication process, Security Access Manager takes an XML representation of the authentication data and then evaluates the data against an XSLT rule to produce the appropriate user identity. The result is either a static user identity or an LDAP search string that you can use to locate the user identity. In addition, one or more attributes might be added to the generated credential for the user.

Note: The authenticated user mapping module cannot be invoked if an EAI authentication takes place, where a privileged attribute certificate (PAC) is supplied as the authentication data.

Authenticated user mapping rule language
Extensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is the language for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both the inputs to the rules evaluator and the rules themselves.

UMI XML document model
The Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the user mapping rules implementation. This model enables the interface to be simple and yet functional for user mapping purposes.

Containers and XML UMI container names
When data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element. For example, elements that might be considered for billing purposes.

XML user mapping model
The following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of an authenticated user mapping rule.

User mapping rules evaluator
The user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module.

Enabling authenticated user mapping
The authenticated user mapping module is disabled by default. You must enable it before you can map an authenticated user name to a different Security Access Manager user identity.

Valid user mapping attributes
A list of authenticated user mapping attributes can be used in the mapping rules.

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Switch user authentication

Reauthentication

Authentication strength policy (step-up)

External authentication interface

Client Certificate User Mapping

External user mapping

Password strength

Authenticated user mapping rule languageExtensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is the language for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both the inputs to the rules evaluator and the rules themselves.XMLuser mapping rulesXSLuser mapping rulesExtensible Style LanguageExtensible Markup LanguageXML expresses complex data types in a structured and standard manner in text format. Using this text format, you can write processing rules for the XML data that is independent of operating systems and programming languages. XSL is a functional style sheet language that can perform simple or complex tasks. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation. XSL is built on other XML-based standards such as XPath, which is the expression language at the core of an authenticated user mapping rule.To implement the user mapping rules, it is necessary to impose some constraints on the XSL rules. These constraints include the requirements that the output of the rule evaluation conforms to one of a known set of result strings. For more information about the format and constraints of user mapping rules, see Format and constraints of rulesDefine an authenticated user mapping rule as an XSL template in an XSL style sheet. .Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

Authenticated user mapping rule language

Extensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is the language for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both the inputs to the rules evaluator and the rules themselves.

XML expresses complex data types in a structured and standard manner in text format. Using this text format, you can write processing rules for the XML data that is independent of operating systems and programming languages.

XSL is a functional style sheet language that can perform simple or complex tasks. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation. XSL is built on other XML-based standards such as XPath, which is the expression language at the core of an authenticated user mapping rule.

To implement the user mapping rules, it is necessary to impose some constraints on the XSL rules. These constraints include the requirements that the output of the rule evaluation conforms to one of a known set of result strings. For more information about the format and constraints of user mapping rules, see Format and constraints of rules.

Parent topic: Authenticated User Mapping

UMI XML document modelThe Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the user mapping rules implementation. This model enables the interface to be simple and yet functional for user mapping purposes.UMIXML document modelXMLUMI document modelThe model constrains the rules to function in a predetermined XML document format with the same top-level XML document element for all rules. The XML UMI that is imported by the rules evaluator from user attributes must be inserted into this XML document before the data can be used. Similarly, to simplify the process of defining rules, the rules must operate in the confines of the UMI XML model. The UMI XML model requires the XML document to contain the following top-level XML element into which all target UMI for a particular rule evaluation is inserted. The XMLUMI element is created automatically as part of the rule evaluation process by the user mapping engine.<XMLUMI> <!--XML formatted UMI are inserted here. --> </XMLUMI>As a result of this restriction, the XPath to the data in a rule must include the prefix /XMLUMI to access a particular data element within the model. For example, if you add a UMI item of stsuuser:STSUniversalUser to the document, you must specify the XPath /XMLUMI/stsuuser:STSUniversalUser to access the data in the XML object stsuuser:STSUniversalUser.An XPath is the path to a particular child element in the hierarchy of a structured XML data object. It is similar to the mechanism that a directory path on a hard disk uses to access a specific file. An XPath designation starts from the root of the document and traces a path from this root through its child elements to the specific element that is referenced. For example, to use the example entitlement stsuuser:STSUniversalUser in the XML user mapping modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of an authenticated user mapping rule. , the following XPath accesses the address element of /XMLUMI/stsuuser:STSUniversalUser:"/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser: Attribute[@name='address']/stsuuser:Value"XPaths like this example are the means by which user mapping rules access the UMI data values for attribute-based user mapping decisions.Because all data elements are restricted to work in the UMI XML model, the user mapping rules must also be restricted to operate on or match XPaths in the model. Therefore, XSL template match statements are also restricted to matching XPaths starting from /XMLUMI in the UMI XML document. For more information, see Format and constraints of rulesDefine an authenticated user mapping rule as an XSL template in an XSL style sheet. .Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

UMI XML document model

The Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the user mapping rules implementation. This model enables the interface to be simple and yet functional for user mapping purposes.

The model constrains the rules to function in a predetermined XML document format with the same top-level XML document element for all rules. The XML UMI that is imported by the rules evaluator from user attributes must be inserted into this XML document before the data can be used. Similarly, to simplify the process of defining rules, the rules must operate in the confines of the UMI XML model.

The UMI XML model requires the XML document to contain the following top-level XML element into which all target UMI for a particular rule evaluation is inserted. The XMLUMI element is created automatically as part of the rule evaluation process by the user mapping engine.

<XMLUMI>
<!--XML formatted UMI are inserted here.    -->
</XMLUMI>

As a result of this restriction, the XPath to the data in a rule must include the prefix /XMLUMI to access a particular data element within the model. For example, if you add a UMI item of stsuuser:STSUniversalUser to the document, you must specify the XPath /XMLUMI/stsuuser:STSUniversalUser to access the data in the XML object stsuuser:STSUniversalUser.

An XPath is the path to a particular child element in the hierarchy of a structured XML data object. It is similar to the mechanism that a directory path on a hard disk uses to access a specific file. An XPath designation starts from the root of the document and traces a path from this root through its child elements to the specific element that is referenced. For example, to use the example entitlement stsuuser:STSUniversalUser in the XML user mapping model, the following XPath accesses the address element of /XMLUMI/stsuuser:STSUniversalUser:

"/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:
Attribute[@name='address']/stsuuser:Value"

XPaths like this example are the means by which user mapping rules access the UMI data values for attribute-based user mapping decisions.

Because all data elements are restricted to work in the UMI XML model, the user mapping rules must also be restricted to operate on or match XPaths in the model. Therefore, XSL template match statements are also restricted to matching XPaths starting from /XMLUMI in the UMI XML document. For more information, see Format and constraints of rules.

Parent topic: Authenticated User Mapping

Containers and XML UMI container namesWhen data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element. For example, elements that might be considered for billing purposes.UMIcontainers and container namesXMLUMI containers and container namescontainer namesUMI containersThis convention also applies to the UMI XML model. The UMI that is used in user mapping rules is also defined and manipulated as containers of XML data. For example, the stsuuser:STSUniversalUser XML object that is defined in XML user mapping modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of an authenticated user mapping rule. is an example of a UMI container. The topmost element in the definition of an item of UMI is the container name of that item. When you define an authenticated user mapping rule, the XPath to the XML definition of data in any UMI container must be referenced with the name of the container as the first element after /XMLUMI. To access any element in the stsuuser:STSUniversalUser container in the UMI item stsuuser:STSUniversalUser example, prefix the XPath specification with stsuuser:STSUniversalUser. For example, "/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='username']/stsuuser:Value" refers to the username value. To access this information from an authenticated user mapping rule, prefix this XPath with the top-level element of the XML target UMI input document, which is XMLUMI. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='username']/stsuuser:Value". The example rule file contains a template match statement of /XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList, which means that you can specify all attributes of the user mapping file without a prefix. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='username']/stsuuser:Value" is the same as "stsuuser:Attribute[@name='username']/stsuuser:Value". For more information, see Format and constraints of rulesDefine an authenticated user mapping rule as an XSL template in an XSL style sheet. .Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

Containers and XML UMI container names

When data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element. For example, elements that might be considered for billing purposes.

This convention also applies to the UMI XML model. The UMI that is used in user mapping rules is also defined and manipulated as containers of XML data. For example, the stsuuser:STSUniversalUser XML object that is defined in XML user mapping model is an example of a UMI container.

The topmost element in the definition of an item of UMI is the container name of that item. When you define an authenticated user mapping rule, the XPath to the XML definition of data in any UMI container must be referenced with the name of the container as the first element after /XMLUMI.

To access any element in the stsuuser:STSUniversalUser container in the UMI item stsuuser:STSUniversalUser example, prefix the XPath specification with stsuuser:STSUniversalUser. For example, "/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='username']/stsuuser:Value" refers to the username value.

To access this information from an authenticated user mapping rule, prefix this XPath with the top-level element of the XML target UMI input document, which is XMLUMI. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='username']/stsuuser:Value".

The example rule file contains a template match statement of /XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList, which means that you can specify all attributes of the user mapping file without a prefix. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='username']/stsuuser:Value" is the same as "stsuuser:Attribute[@name='username']/stsuuser:Value". For more information, see Format and constraints of rules.

Parent topic: Authenticated User Mapping

XML user mapping modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of an authenticated user mapping rule. XMLuser mapping exampleuser mappingexample XMLThe document contains one container that is named stsuuser. The attribute value of the container stsuuser:STSUniversalUser is defined in XML. The evaluator automatically encompasses all of the data under the XML top-level node declaration XMLUMI when the UMI XML document is created, so this top-level element is added for clarity.The XML document is automatically created by Security Access Manager with the attributes that are in the authentication request. The XML document that is passed to the evaluation routines by the user mapping rules evaluator is as follows: <?xml version="1.0" encoding='UTF-8'?> <XMLUMI> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> - authenticated user identity - </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="-attrname-"> <stsuuser:Value>-attrvalue-</stsuuser:Value> </stsuuser:Attribute> ... </stsuuser:AttributeList> </stsuuser:STSUniversalUser> </XMLUMI>For a full list of available attributes, see Valid user mapping attributesA list of authenticated user mapping attributes can be used in the mapping rules. .When you reference a particular UMI item in the XMLUMI document available to a rule, the XPath path specifier can begin from the container name of the XML element (for example, stsuuser:STSUniversalUser). If the callers want to specify their own template match statement explicitly, they can do so.For more information, see Format and constraints of rulesDefine an authenticated user mapping rule as an XSL template in an XSL style sheet. .Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

XML user mapping model

The following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of an authenticated user mapping rule.

The document contains one container that is named stsuuser. The attribute value of the container stsuuser:STSUniversalUser is defined in XML.

The evaluator automatically encompasses all of the data under the XML top-level node declaration XMLUMI when the UMI XML document is created, so this top-level element is added for clarity.

The XML document is automatically created by Security Access Manager with the attributes that are in the authentication request. The XML document that is passed to the evaluation routines by the user mapping rules evaluator is as follows:

<?xml version="1.0" encoding='UTF-8'?>

<XMLUMI>
  <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
    <stsuuser:Principal>
      <stsuuser:Attribute name="name">
        <stsuuser:Value>
          - authenticated user identity -
        </stsuuser:Value>
      </stsuuser:Attribute>
    </stsuuser:Principal>
    <stsuuser:AttributeList>
      <stsuuser:Attribute name="-attrname-">
        <stsuuser:Value>-attrvalue-</stsuuser:Value>
      </stsuuser:Attribute>
      ...
    </stsuuser:AttributeList>
  </stsuuser:STSUniversalUser>
</XMLUMI>

For a full list of available attributes, see Valid user mapping attributes.

When you reference a particular UMI item in the XMLUMI document available to a rule, the XPath path specifier can begin from the container name of the XML element (for example, stsuuser:STSUniversalUser). If the callers want to specify their own template match statement explicitly, they can do so.

For more information, see Format and constraints of rules.

Parent topic: Authenticated User Mapping

User mapping rules evaluatorThe user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module.user mappingrulesevaluatorevaluatoruser mapping rulesThe user mapping rules evaluator sends the rule policy with the XML representation of the authentication request to the XSL processor for evaluation. The input for the transformation is the XML version of the authentication request. XSL transformation rules decide how the Security Access Manager user name is mapped from the supplied user attributes information. Two inputs are used for decision making:The XML representation of the authentication request.The XSL rule, which determines how the XML is interpreted.The output from the decision determines the Security Access Manager user identity and attributes. Evaluation outputXML ElementDescriptionExample<identity>Contains the new user identity. The original user identity, as determined by the authentication module, is used if no identity container is provided. If an identity container is provided but the identity cannot be determined, it is an authentication error. An example of this situation is a failed LDAP search.<identity>cn=testuser,o=ibm,c=us</identity><attribute>Contains the name and value of an attribute that is added to the constructed credential. You can supply multiple attributes in the response.Use a unique name for each attribute that you want to add to the user credential. If you add more than one attribute with the same name in the XSLT rules, only one of the attributes with that name is added to the user credential.<attribute name=qop>test-qop</attribute>The value for the identity or attribute can either be a static string or an LDAP search query. The LDAP search query uses the following format:<userreg base='%base%' attr='%name%'>%ldap-search-filter%</userreg>Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. Format and constraints of rulesDefine an authenticated user mapping rule as an XSL template in an XSL style sheet. Sample user mapping ruleThis example XSLT rule sets a new user identity that is derived from an LDAP search and two new attributes.Troubleshooting user mapping rule problemsAn error in the XSLT rule might cause the authentication to fail. The following table details some of the common problems in the XSLT rules and the corresponding failure scenarios.

User mapping rules evaluator

The user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module.

The user mapping rules evaluator sends the rule policy with the XML representation of the authentication request to the XSL processor for evaluation.

The input for the transformation is the XML version of the authentication request. XSL transformation rules decide how the Security Access Manager user name is mapped from the supplied user attributes information. Two inputs are used for decision making:

The XML representation of the authentication request.

The XSL rule, which determines how the XML is interpreted.

The output from the decision determines the Security Access Manager user identity and attributes.

Table 39. Evaluation output

XML Element
Description
Example

<identity>

Contains the new user identity. The original user identity, as determined by the authentication module, is used if no identity container is provided. If an identity container is provided but the identity cannot be determined, it is an authentication error. An example of this situation is a failed LDAP search.

<identity>cn=testuser,o=ibm,c=us</identity>

<attribute>

Contains the name and value of an attribute that is added to the constructed credential. You can supply multiple attributes in the response.

Note: Use a unique name for each attribute that you want to add to the user credential. If you add more than one attribute with the same name in the XSLT rules, only one of the attributes with that name is added to the user credential.

<attribute name=qop>test-qop</attribute>

The value for the identity or attribute can either be a static string or an LDAP search query. The LDAP search query uses the following format:

<userreg base='%base%' attr='%name%'>%ldap-search-filter%</userreg>

Format and constraints of rules
Define an authenticated user mapping rule as an XSL template in an XSL style sheet.

Sample user mapping rule
This example XSLT rule sets a new user identity that is derived from an LDAP search and two new attributes.

Troubleshooting user mapping rule problems
An error in the XSLT rule might cause the authentication to fail. The following table details some of the common problems in the XSLT rules and the corresponding failure scenarios.

Parent topic: Authenticated User Mapping

Format and constraints of rulesDefine an authenticated user mapping rule as an XSL template in an XSL style sheet. user mappingrulesformat and constraintsformatuser mapping rulesconstraintsuser mapping rulesWrite the rule in a valid XSL template rule format by using XSLT version 1.0. It must return a text document that contains the string identifiers in User mapping rules evaluatorThe user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module..The following authenticated user mapping rule example references the XML data that is defined in stsuuser:STSUniversalUser to add an attribute that is called authn_method to the user credential.<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser= "urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0"> <!-- Required to constrain output of rule evaluation --> <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/> <!-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template> <!-- Let's make it easier by matching the constant part of our XML name --> <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList"> <attribute name='authn_method'><xsl:value-of select="stsuuser:Attribute [@name='method']/stsuuser:Value"/></attribute> </xsl:template> </xsl:stylesheet>User mapping rules evaluatorThe user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module.

Format and constraints of rules

Define an authenticated user mapping rule as an XSL template in an XSL style sheet.

Write the rule in a valid XSL template rule format by using XSLT version 1.0. It must return a text document that contains the string identifiers in User mapping rules evaluator.

The following authenticated user mapping rule example references the XML data that is defined in stsuuser:STSUniversalUser to add an attribute that is called authn_method to the user credential.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser=
"urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0">

<!-- Required to constrain output of rule evaluation -->
<xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/>

<!-- Need this to ensure default text node printing is off -->
<xsl:template match="text()"></xsl:template>

<!-- Let's make it easier by matching the constant part of our XML name -->
<xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList">
    <attribute name='authn_method'><xsl:value-of select="stsuuser:Attribute
    [@name='method']/stsuuser:Value"/></attribute>
</xsl:template>

</xsl:stylesheet>

Parent topic: User mapping rules evaluator

Sample user mapping ruleThis example XSLT rule sets a new user identity that is derived from an LDAP search and two new attributes.user mappingrulessamplesUMI example<?xml version="1.0" encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0"> <!-- Required to constrain output of rule evaluation --> <xsl:output method="xml" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/> <!-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template> <!-- Let's make it easier by matching the constant part of our XML name --> <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList"> <attribute name='method'><xsl:value-of select="stsuuser:Attribute [@name='method']/stsuuser:Value"/></attribute> <attribute name='user_email'><userreg base='dc=iswga' attr='email'> (cn=<xsl:value-of select="stsuuser:Attribute[@name='username']/stsuuser:Value"/>) </userreg></attribute> <identity><userreg base='dc=iswga' attr='dn'> (cn=<xsl:value-of select="stsuuser:Attribute[@name='username']/stsuuser:Value"/>) </userreg></identity> </xsl:template> </xsl:stylesheet> The first attribute method contains the method that was used for authentication. This information is extracted from the XML representation of the authentication data. The second attribute that the rule adds to the user credential is user_email. This attribute is populated by a user registry search. A search is performed, where the CN in the user registry is matched against the supplied user name. The email attribute is then returned for the matched user. An LDAP search is also performed, where the CN in the user registry is matched against the supplied user name. The dn attribute of the matched user is then used as the Security Access Manager user identity. User mapping rules evaluatorThe user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module.

Sample user mapping rule

This example XSLT rule sets a new user identity that is derived from an LDAP search and two new attributes.

<?xml version="1.0" encoding='UTF-8'?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0">

<!-- Required to constrain output of rule evaluation -->
<xsl:output method="xml" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/>

<!-- Need this to ensure default text node printing is off -->
<xsl:template match="text()"></xsl:template>

<!-- Let's make it easier by matching the constant part of our XML name -->
<xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList">
 <attribute name='method'><xsl:value-of select="stsuuser:Attribute
 [@name='method']/stsuuser:Value"/></attribute>
 <attribute name='user_email'><userreg base='dc=iswga' attr='email'>
 (cn=<xsl:value-of select="stsuuser:Attribute[@name='username']/stsuuser:Value"/>)
 </userreg></attribute>
 <identity><userreg base='dc=iswga' attr='dn'>
 (cn=<xsl:value-of select="stsuuser:Attribute[@name='username']/stsuuser:Value"/>)
 </userreg></identity>
</xsl:template>

</xsl:stylesheet>

The first attribute method contains the method that was used for authentication. This information is extracted from the XML representation of the authentication data.

The second attribute that the rule adds to the user credential is user_email. This attribute is populated by a user registry search. A search is performed, where the CN in the user registry is matched against the supplied user name. The email attribute is then returned for the matched user.

An LDAP search is also performed, where the CN in the user registry is matched against the supplied user name. The dn attribute of the matched user is then used as the Security Access Manager user identity.

Parent topic: User mapping rules evaluator

Troubleshooting user mapping rule problemsAn error in the XSLT rule might cause the authentication to fail. The following table details some of the common problems in the XSLT rules and the corresponding failure scenarios.Typical user mapping rule problems and failure scenariosRule problemExampleExpected failureInvalid XSLT A missing slash (/) in the closing tagHPDIA0110E An authentication mechanism module specific error occurred.The logged details also include the output from the SAXParseException. For example, SAXParseException: Expected end of tag 'identity'.Referencing an XML attribute that does not exist<attribute name='TESTAttr'> <xsl:value-of select= "stsuuser:Attribute[@name= 'notexist']/stsuuser :Value"/> </attribute> <identity> <xsl:value-of select= "stsuuser:Attribute [@name='invalid']/ stsuuser:Value"/> </identity>Any references to XML attributes that do not exist are disregarded by the user mapping module. In this example, the authentication proceeds as the original authenticated user. No identity mapping takes place because the identity container references a non-existent XML attribute. Similarly, the user credential does not contain an attribute that is called TESTAttr because the attribute container references an XML attribute that does not exist. Referencing an unknown LDAP attribute in the rule<identity> <userreg base='dc=iswga' attr='dn'> (unknownLDAPattr =<xsl:value-of select= "stsuuser:Attribute [@name='username'] /stsuuser:Value"/>) </userreg> </identity>1 2014-07-29-13:28:23.110+10:00I----- 0x1005B308 webseald ERROR acl mgmt AMWUserMapLDAPUserRegistry.cpp 157 0x7f830cc74700 -- HPDAC0776E The DN specified was not found in the registry. 2 2014-07-29-13:28:23.111+10:00I----- 0x1005B3B5 webseald ERROR acl authzn usermapauthn.cpp 482 0x7f830cc74700 -- HPDAC0949E Validation of the rule text for rule object "usermapauthn" failed. Error code 0x1005b3b4 was returned along with error message "<identity xmlns:stsuuser="urn:ibm :names:ITFIM:1.0:stsuuser"> <userreg base="dc=iswga"attr="dn"> (unknownLDAPattr=userA)</userreg> </identity>". 3 2014-07-29-13:28:23.111+10:00I----- 0x13212065 webseald WARNING ias general pdauthn.cpp 1813 0x7f830cc74700 -- HPDIA0101E An unexpected error code was encountered.Returning an LDAP search string that does not have a matching entry in LDAP<identity> <userreg base='dc=iswga' attr='cn'>(description= DescThatDoesNotExistInLDAP) </userreg> </identity>1 2014-07-29-13:31:58.256+10:00I----- 0x1005B308 webseald ERROR acl mgmt AMWUserMapLDAPUserRegistry.cpp 157 0x7f61fc4c5700 --HPDAC0776E The DN specified was not found in the registry. 2 2014-07-29-13:31:58.256+10:00I----- 0x1005B3B5 webseald ERROR acl authzn usermapauthn.cpp 482 0x7f61fc4c5700 -- HPDAC0949E Validation of the rule text for rule object "usermapauthn" failed. Error code 0x1005b3b4 was returned along with error message "<identity xmlns:stsuuser="urn:ibm :names:ITFIM:1.0:stsuuser"> <userreg base="dc=iswga" attr="cn"> (description=DescThatDoesNotExistInLDAP) </userreg></identity>". 3 2014-07-29-13:31:58.257+10:00I----- 0x13212065 webseald WARNING ias general pdauthn.cpp 1813 0x7f61fc4c5700 -- HPDIA0101E An unexpected error code was encountered.Return a static string identity that is not a valid IBM Security Access Manager user<identity>does-not-exist </identity>HPDIA0219W An unknown user, <login username>, was presented to Security Access Manager. In this instance, the login username that is mentioned in the log might be a valid IBM Security Access Manager user. However, the XSLT rules attempt to map the user to an unknown IBM Security Access Manager user. So the authentication fails.User mapping rules evaluatorThe user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module.

Troubleshooting user mapping rule problems

An error in the XSLT rule might cause the authentication to fail. The following table details some of the common problems in the XSLT rules and the corresponding failure scenarios.

Table 40. Typical user mapping rule problems and failure scenarios

Rule problem
Example
Expected failure

Invalid XSLT
A missing slash (/) in the closing tag
HPDIA0110E An authentication mechanism module specific error occurred.

The logged details also include the output from the SAXParseException. For example, SAXParseException: Expected end of tag 'identity'.

Referencing an XML attribute that does not exist

<attribute name='TESTAttr'>
<xsl:value-of select=
"stsuuser:Attribute[@name=
'notexist']/stsuuser
:Value"/>
</attribute>
<identity>
<xsl:value-of select=
"stsuuser:Attribute
[@name='invalid']/
stsuuser:Value"/>
</identity>

Any references to XML attributes that do not exist are disregarded by the user mapping module. In this example, the authentication proceeds as the original authenticated user. No identity mapping takes place because the identity container references a non-existent XML attribute. Similarly, the user credential does not contain an attribute that is called TESTAttr because the attribute container references an XML attribute that does not exist.

Referencing an unknown LDAP attribute in the rule

<identity>
<userreg base='dc=iswga'
attr='dn'>
(unknownLDAPattr
=<xsl:value-of select=
"stsuuser:Attribute
[@name='username']
/stsuuser:Value"/>)
</userreg>
</identity>

1    2014-07-29-13:28:23.110+10:00I-----
0x1005B308 webseald ERROR acl mgmt
AMWUserMapLDAPUserRegistry.cpp 157
0x7f830cc74700 --  HPDAC0776E
The DN specified was not found in the
registry.
2    2014-07-29-13:28:23.111+10:00I-----
0x1005B3B5 webseald ERROR acl authzn
usermapauthn.cpp 482 0x7f830cc74700
-- HPDAC0949E    Validation of the
rule text for rule object "usermapauthn"
failed. Error code 0x1005b3b4 was
returned along with error message
"<identity xmlns:stsuuser="urn:ibm
:names:ITFIM:1.0:stsuuser">
<userreg base="dc=iswga"attr="dn">
(unknownLDAPattr=userA)</userreg>
</identity>".
3    2014-07-29-13:28:23.111+10:00I-----
0x13212065 webseald WARNING ias general
pdauthn.cpp 1813 0x7f830cc74700
-- HPDIA0101E   An unexpected error code
was encountered.

Returning an LDAP search string that does not have a matching entry in LDAP

<identity>
<userreg base='dc=iswga'
attr='cn'>(description=
DescThatDoesNotExistInLDAP)
</userreg>
</identity>

1    2014-07-29-13:31:58.256+10:00I-----
0x1005B308 webseald ERROR acl mgmt
AMWUserMapLDAPUserRegistry.cpp 157
0x7f61fc4c5700 --HPDAC0776E    The DN
specified was not found in the registry.
2    2014-07-29-13:31:58.256+10:00I-----
0x1005B3B5 webseald ERROR acl authzn
usermapauthn.cpp 482 0x7f61fc4c5700
-- HPDAC0949E   Validation of the rule
text for rule object "usermapauthn"
failed. Error code 0x1005b3b4 was
returned along with error message
"<identity xmlns:stsuuser="urn:ibm
:names:ITFIM:1.0:stsuuser">
<userreg base="dc=iswga" attr="cn">
(description=DescThatDoesNotExistInLDAP)
</userreg></identity>".
3    2014-07-29-13:31:58.257+10:00I-----
0x13212065 webseald WARNING ias general
pdauthn.cpp 1813 0x7f61fc4c5700
-- HPDIA0101E An unexpected error code
was encountered.

Return a static string identity that is not a valid IBM Security Access Manager user

<identity>does-not-exist
</identity>

HPDIA0219W   An unknown user,
<login username>, was presented to
Security Access Manager.

In this instance, the login username that is mentioned in the log might be a valid IBM Security Access Manager user. However, the XSLT rules attempt to map the user to an unknown IBM Security Access Manager user. So the authentication fails.

Parent topic: User mapping rules evaluator

Enabling authenticated user mappingThe authenticated user mapping module is disabled by default. You must enable it before you can map an authenticated user name to a different Security Access Manager user identity.authenticated usersmappingenablinguser mappingauthenticationAccess the local management interface to configure an XSLT rules file to define the rules for the authenticated user mapping module. The following steps use auth-rules.xsl as an example. Select Secure Web SettingsGlobal SettingsUser Name Mapping from the top menu. The User Name Mapping management page displays. Take one of the following actions:If rules files exist, select the file that you want to enable, such as auth-rules.xsl, from the available list of File Names. If no rules files exist: Click New to create a new rules file. Enter a name for the new file such as auth-rules.xsl.Click Save. The system generates a new file that is based on the default template.Click Edit.Update the file to reflect the rules you want to set.Click Save.Access the WebSEAL configuration file for your instance.Update the [user-map-authn] stanza in the WebSEAL configuration file as follows: [user-map-authn] rules-file = file debug-level = level where: fileSpecifies the name of the rules file for the authenticated user mapping module.If you rename the rules file that WebSEAL is configured to use, you must manually update this rules-file configuration entry to match the new name of the rules file. Otherwise, WebSEAL cannot locate and use the rules file after the rename operation.levelControls the trace level for the module.[user-map-authn] rules-file = auth-rules.xsl debug-level = 5The level variable indicates the trace level; 1 designates a minimal amount of tracing, and 9 designates the maximum. The Security Access Manager pdadmin trace command also modifies the trace level by using the trace component name of pd.cas.usermap. This trace component is only available after the first HTTP request is processed.If you do not specify a debug level, 0 is used by default. If an invalid numerical value is configured, the module defaults to a level of 0. If a non-numeric value is configured for the entry, the authentication mechanism module fails with an error in the WebSEAL log, which indicates that the debug-level is invalid. Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

Enabling authenticated user mapping

The authenticated user mapping module is disabled by default. You must enable it before you can map an authenticated user name to a different Security Access Manager user identity.

Procedure

Access the local management interface to configure an XSLT rules file to define the rules for the authenticated user mapping module. The following steps use auth-rules.xsl as an example.

Select Secure Web Settings > Global Settings > User Name Mapping from the top menu. The User Name Mapping management page displays.

Take one of the following actions:

If rules files exist, select the file that you want to enable, such as auth-rules.xsl, from the available list of File Names.

If no rules files exist:

Click New to create a new rules file.

Enter a name for the new file such as auth-rules.xsl.

Click Save. The system generates a new file that is based on the default template.

Click Edit.

Update the file to reflect the rules you want to set.

Click Save.

Access the WebSEAL configuration file for your instance.

Update the [user-map-authn] stanza in the WebSEAL configuration file as follows:

[user-map-authn]
rules-file = file
debug-level = level

where:

file

Specifies the name of the rules file for the authenticated user mapping module.

Note: If you rename the rules file that WebSEAL is configured to use, you must manually update this rules-file configuration entry to match the new name of the rules file. Otherwise, WebSEAL cannot locate and use the rules file after the rename operation.

level

Controls the trace level for the module.

[user-map-authn]
rules-file = auth-rules.xsl
debug-level = 5

Notes:

The level variable indicates the trace level; 1 designates a minimal amount of tracing, and 9 designates the maximum. The Security Access Manager pdadmin trace command also modifies the trace level by using the trace component name of pd.cas.usermap. This trace component is only available after the first HTTP request is processed.

If you do not specify a debug level, 0 is used by default.

If an invalid numerical value is configured, the module defaults to a level of 0.

If a non-numeric value is configured for the entry, the authentication mechanism module fails with an error in the WebSEAL log, which indicates that the debug-level is invalid.

Parent topic: Authenticated User Mapping

Valid user mapping attributesA list of authenticated user mapping attributes can be used in the mapping rules. certificate attributesvaliduser mappingvalid attributesThe following table lists the available attributes. Valid user attributesAttributeDescriptionaddressThe address of the client that originates the authentication request.qopA string that represents the quality-of-protection of the incoming request.browserAn identifier for the browser that originates the request.methodA string that identifies the method that is used to authenticate the user.attr:<xxx>Any extended attributes that are provided by the authentication mechanism. If the selected authentication method requires a user name and password, the following extended attributes are available: Extended attributes - user name and passwordAttributeDescriptionusernameThe name of the user during the authentication. passwordThe password that is used during the authentication. The value of this attribute is masked in the associated logged output for security reasons. You can configure an External Authentication Interface (EAI) for WebSEAL authentications. If the EAI returns a username value, you can use the authenticated user mapping function. However, EAIs that return an Extended Privilege Attribute Certificate (EPAC) cannot use this function. If the selected authentication method requires an SSO token, the following extended attributes are available. Extended attributes - SSO tokenAttributeDescriptionqueryThe query string from the request. refererThe referer header from the request. token_typeThe type of token. The value can be auth, ecc, vft. If the selected authentication method requires a certificate, the following extended attributes are available. Extended attributes - certificateAttributeDescriptionx509.base64_certificateA base64 encoded representation of the certificate.x509.basic_constraints_caThe constraints that are associated with the CA who issued the certificate.x509.basic_constraints_path_lenThe depth of valid certification paths that include this certificate.x509.certificate_policy_idAn identifier that names the policy that is acceptable to the certificate user.x509.crl_distribution_pointsThe distribution points for the CRL information.x509.der_certificateA DER encoded representation of the certificate.x509.fingerprintThe fingerprint that is associated with the certificate.x509.fingerprint_algorithmThe algorithm that is used to generate the fingerprint that is associated with the certificate.x509.issuer_cnThe common name of the issuer of the certificate.x509.issuer_countryThe country identifier that is associated with the issuer of the certificate.x509.issuer_dnThe full domain name of the issuer of the certificate.x509.issuer_dn_derA DER encoded representation of the domain name of the issuer of the certificate.x509.issuer_emailThe email address that is associated with the issuer of the certificate.x509.issuer_localityThe locality that is associated with the issuer of the certificate.x509.issuer_orgThe name of the organization that is associated with the issuer of the certificate.x509.issuer_org_unitThe name of the organizational unit that is associated with the issuer of the certificate.x509.issuer_postal_codeThe postal code of the issuer of the certificate.x509.issuer_stateThe name of the state that is provided by the issuer of the certificate.x509.issuer_unique_idA unique identifier for the issuer of the certificate.x509.key_usageDefines the purpose of the key that is contained in the certificate.x509.public_keyThe public key that is used by the certificate.x509.public_key_algorithmThe key algorithm that is used by the certificate.x509.public_key_sizeThe size of the public key.x509.serial_numberThe serial number that is associated with the certificate.x509.signature_algorithmThe algorithm that is used to generate the certificate signature.x509.subject_alternative_dirnameA directory name that is associated with the subject of the certificate.x509.subject_alternative_dnsnameA DNS name that is associated with the subject of the certificate.x509.subject_alternative_emailThe email address that is associated with the subject of the certificate.x509.subject_alternative_ipaddrThe IP address that is associated with the subject of the certificate.x509.subject_alternative_uriA URI that is associated with the subject of the certificate.x509.subject_cnThe common name of the subject of the certificate.x509.subject_countryThe country identifier that is associated with the subject of the certificate.x509.subject_dnThe full domain name of the subject of the certificate.x509.subject_dn_derA DER encoded representation of the domain name of the subject of the certificate.x509.subject_emailThe email address that is associated with the subject of the certificate.x509.subject_localityThe locality that is associated with the subject of the certificate.x509.subject_orgThe name of the organization that is associated with the subject of the certificate.x509.subject_org_unitThe name of the organizational unit that is associated with the subject of the certificate.x509.subject_postal_codeThe postal code of the subject of the certificate.x509.subject_stateThe name of the state that is provided by the subject of the certificate.x509.subject_unique_idA unique identifier for the subject of the certificate.x509.valid_fromThe date from which the certificate is valid. The date is the number of seconds since epoch.x509.valid_from_exThe date from which the certificate is valid. The date format is hh:mm:ss dd-mm-yyyy.x509.valid_toThe date to which the certificate is valid. The date is the number of seconds since epoch.x509.valid_to_exThe date to which the certificate is valid. The date format is hh:mm:ss dd-mm-yyyy.x509.versionThe certificate version number.x509.ext.xxxEach of the attributes that are contained in the x509 certificate extension is included. They are prefixed with the name x509.ext. The x509 data, except for the x509 extensions, is included in the constructed XML document only if it is required by the rule. This design decreases the size of the constructed XML document, which improves performance.All data is XML encoded. Non-printable data is encoded as \xhh;, where hh is the code point in hexadecimal form. If the selected authentication method is Kerberos authentication, an extended attribute that represents the security identifier (SID) is available in the XML representation of the authentication data. The name of the attribute is attr:<spnego-sid-attr-name>, which corresponds to the spnego-sid-attr-name configuration entry in the [spnego] stanza.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity.

Valid user mapping attributes

A list of authenticated user mapping attributes can be used in the mapping rules.

The following table lists the available attributes.

Table 41. Valid user attributes

Attribute | Description
address | The address of the client that originates the authentication request.
qop | A string that represents the quality-of-protection of the incoming request.
browser | An identifier for the browser that originates the request.
method | A string that identifies the method that is used to authenticate the user.
attr:<xxx> | Any extended attributes that are provided by the authentication mechanism.

If the selected authentication method requires a user name and password, the following extended attributes are available:

Table 42. Extended attributes - user name and password

Attribute | Description
username | The name of the user during the authentication.
password | The password that is used during the authentication. The value of this attribute is masked in the associated logged output for security reasons.

Note: You can configure an External Authentication Interface (EAI) for WebSEAL authentications. If the EAI returns a username value, you can use the authenticated user mapping function. However, EAIs that return an Extended Privilege Attribute Certificate (EPAC) cannot use this function.

If the selected authentication method requires an SSO token, the following extended attributes are available.

Table 43. Extended attributes - SSO token

Attribute | Description
query | The query string from the request.
referer | The referer header from the request.
token_type | The type of token. The value can be auth, ecc, vft.

If the selected authentication method requires a certificate, the following extended attributes are available.

Table 44. Extended attributes - certificate

Attribute | Description
x509.base64_certificate | A base64 encoded representation of the certificate.
x509.basic_constraints_ca | The constraints that are associated with the CA who issued the certificate.
x509.basic_constraints_path_len | The depth of valid certification paths that include this certificate.
x509.certificate_policy_id | An identifier that names the policy that is acceptable to the certificate user.
x509.crl_distribution_points | The distribution points for the CRL information.
x509.der_certificate | A DER encoded representation of the certificate.
x509.fingerprint | The fingerprint that is associated with the certificate.
x509.fingerprint_algorithm | The algorithm that is used to generate the fingerprint that is associated with the certificate.
x509.issuer_cn | The common name of the issuer of the certificate.
x509.issuer_country | The country identifier that is associated with the issuer of the certificate.
x509.issuer_dn | The full domain name of the issuer of the certificate.
x509.issuer_dn_der | A DER encoded representation of the domain name of the issuer of the certificate.
x509.issuer_email | The email address that is associated with the issuer of the certificate.
x509.issuer_locality | The locality that is associated with the issuer of the certificate.
x509.issuer_org | The name of the organization that is associated with the issuer of the certificate.
x509.issuer_org_unit | The name of the organizational unit that is associated with the issuer of the certificate.
x509.issuer_postal_code | The postal code of the issuer of the certificate.
x509.issuer_state | The name of the state that is provided by the issuer of the certificate.
x509.issuer_unique_id | A unique identifier for the issuer of the certificate.
x509.key_usage | Defines the purpose of the key that is contained in the certificate.
x509.public_key | The public key that is used by the certificate.
x509.public_key_algorithm | The key algorithm that is used by the certificate.
x509.public_key_size | The size of the public key.
x509.serial_number | The serial number that is associated with the certificate.
x509.signature_algorithm | The algorithm that is used to generate the certificate signature.
x509.subject_alternative_dirname | A directory name that is associated with the subject of the certificate.
x509.subject_alternative_dnsname | A DNS name that is associated with the subject of the certificate.
x509.subject_alternative_email | The email address that is associated with the subject of the certificate.
x509.subject_alternative_ipaddr | The IP address that is associated with the subject of the certificate.
x509.subject_alternative_uri | A URI that is associated with the subject of the certificate.
x509.subject_cn | The common name of the subject of the certificate.
x509.subject_country | The country identifier that is associated with the subject of the certificate.
x509.subject_dn | The full domain name of the subject of the certificate.
x509.subject_dn_der | A DER encoded representation of the domain name of the subject of the certificate.
x509.subject_email | The email address that is associated with the subject of the certificate.
x509.subject_locality | The locality that is associated with the subject of the certificate.
x509.subject_org | The name of the organization that is associated with the subject of the certificate.
x509.subject_org_unit | The name of the organizational unit that is associated with the subject of the certificate.
x509.subject_postal_code | The postal code of the subject of the certificate.
x509.subject_state | The name of the state that is provided by the subject of the certificate.
x509.subject_unique_id | A unique identifier for the subject of the certificate.
x509.valid_from | The date from which the certificate is valid. The date is the number of seconds since epoch.
x509.valid_from_ex | The date from which the certificate is valid. The date format is hh:mm:ss dd-mm-yyyy.
x509.valid_to | The date to which the certificate is valid. The date is the number of seconds since epoch.
x509.valid_to_ex | The date to which the certificate is valid. The date format is hh:mm:ss dd-mm-yyyy.
x509.version | The certificate version number.
x509.ext.xxx | Each of the attributes that are contained in the x509 certificate extension is included. They are prefixed with the name x509.ext.

Notes:

The x509 data, except for the x509 extensions, is included in the constructed XML document only if it is required by the rule. This design decreases the size of the constructed XML document, which improves performance.

All data is XML encoded. Non-printable data is encoded as \xhh;, where hh is the code point in hexadecimal form.

If the selected authentication method is Kerberos authentication, an extended attribute that represents the security identifier (SID) is available in the XML representation of the authentication data. The name of the attribute is attr:<spnego-sid-attr-name>, which corresponds to the spnego-sid-attr-name configuration entry in the [spnego] stanza.

Parent topic: Authenticated User Mapping

External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.The HTTP Callout Mapping Module can be optionally used by the runtime during federation mapping operations. The module can call out to external services in one of these formats: XML, JSON, and WS-Trust. The following code shows an example of the JSON configuration data:{ "uri": "http:mywebserver.com", "sslKeyStore" : "keystore", "autType": "BASIC, NONE, CERTIFICATE", "basicauthusername": "username", "basicauthpassword": "password", "messageFormat":"XML, JSON, WSTRUST", "certKeyStore": "keystore", "certKeyAlias": "keyalias", "issuerUri":"urn:itfim:wstrust:issuer", "appliesTo" : "urn:itfim:wstrust:tamToken", } If the message format is WSTRUST, the SOAP body of the message is the XML representation of STSUU. If the message format is XML or JSON, then those formats represent the request body. The response has the same message format of the request.Advanced authentication methodsMultiplexing proxy agentsSwitch user authenticationReauthenticationAuthentication strength policy (step-up)External authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. Password strengthThe password strength module validates the strength of new passwords.

External user mapping

Use the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.

The HTTP Callout Mapping Module can be optionally used by the runtime during federation mapping operations. The module can call out to external services in one of these formats: XML, JSON, and WS-Trust. The following code shows an example of the JSON configuration data:

{
 "uri": "http:mywebserver.com",
 "sslKeyStore" : "keystore",
 "autType": "BASIC, NONE, CERTIFICATE",
 "basicauthusername": "username",
 "basicauthpassword": "password",
 "messageFormat":"XML, JSON, WSTRUST",
 "certKeyStore": "keystore",
 "certKeyAlias": "keyalias",
 "issuerUri":"urn:itfim:wstrust:issuer",
 "appliesTo" : "urn:itfim:wstrust:tamToken",
 }

If the message format is WSTRUST, the SOAP body of the message is the XML representation of STSUU. If the message format is XML or JSON, then those formats represent the request body. The response has the same message format of the request.

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Switch user authentication

Reauthentication

Authentication strength policy (step-up)

External authentication interface

Client Certificate User Mapping

Authenticated User Mapping

Password strength

Password strengthThe password strength module validates the strength of new passwords. This module is started by a password change operation, which is initiated by the /pkmspasswd command. It evaluates the new password against an XSLT rule to determine whether the new password meets the configured criteria.Security Access Manager uses the password strength rules that are configured by this module in addition to the password policy rules that are set in pdadmin to evaluate each password. The new password must meet both the password policy settings and the XSLT rules that are imposed by this module. Advanced authentication methodsMultiplexing proxy agentsSwitch user authenticationReauthenticationAuthentication strength policy (step-up)External authentication interfaceClient Certificate User MappingThe Client Certificate User Mapping functionality will be deprecated in a future release in favor of the Authenticated User Mapping functionality.Authenticated User MappingYou can use the authenticated user mapping module to map an authenticated user name to a different Security Access Manager user identity. External user mappingUse the HTTP Callout Mapping Module to invoke a web service to perform the STSUU enrichment and return the modified content back into the flow of the federation.Password strength validation rule languageExtensible Style Language (XSL) specifies rules. Extensible Markup Language (XML) is the language for the data. It forms an input to the rules. The combination of XML and XSL provides a platform-independent method of expressing both the inputs to the rules evaluator and the rules themselves.UMI XML document modelThe Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the password strength validation rules implementation. This model enables the interface to be both simple and functional for password strength validation purposes.Containers and XML UMI container namesWhen data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element, for example, elements that might be considered for billing purposes.XML password strength validation modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a password strength validation rule. Password strength rules evaluatorThe evaluator evaluates password strength rules in the constraints that are required by the password strength validation engine. A configuration file that you specify supplies the pre-configured rules to the password strength validation module.Enabling password strength validationThe password strength validation module is disabled by default. You must enable it before you can validate whether a new password meets the configured criteria.Password strength validation attributesYou can use these attributes in the password strength validation rules.

Password strength

The password strength module validates the strength of new passwords.

This module is started by a password change operation, which is initiated by the /pkmspasswd command. It evaluates the new password against an XSLT rule to determine whether the new password meets the configured criteria.

Security Access Manager uses the password strength rules that are configured by this module in addition to the password policy rules that are set in pdadmin to evaluate each password. The new password must meet both the password policy settings and the XSLT rules that are imposed by this module.

Password strength validation rule language
Extensible Style Language (XSL) specifies rules. Extensible Markup Language (XML) is the language for the data. It forms an input to the rules. The combination of XML and XSL provides a platform-independent method of expressing both the inputs to the rules evaluator and the rules themselves.

UMI XML document model
The Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the password strength validation rules implementation. This model enables the interface to be both simple and functional for password strength validation purposes.

Containers and XML UMI container names
When data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element, for example, elements that might be considered for billing purposes.

XML password strength validation model
The following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a password strength validation rule.

Password strength rules evaluator
The evaluator evaluates password strength rules in the constraints that are required by the password strength validation engine. A configuration file that you specify supplies the pre-configured rules to the password strength validation module.

Enabling password strength validation
The password strength validation module is disabled by default. You must enable it before you can validate whether a new password meets the configured criteria.

Password strength validation attributes
You can use these attributes in the password strength validation rules.

Parent topic: Advanced authentication methods

Related concepts:

Multiplexing proxy agents

Switch user authentication

Reauthentication

Authentication strength policy (step-up)

External authentication interface

Client Certificate User Mapping

Authenticated User Mapping

External user mapping

Password strength validation rule languageExtensible Style Language (XSL) specifies rules. Extensible Markup Language (XML) is the language for the data. It forms an input to the rules. The combination of XML and XSL provides a platform-independent method of expressing both the inputs to the rules evaluator and the rules themselves.XMLpassword strength validation rulesXSLpassword strength validation rulesExtensible Style LanguageExtensible Markup LanguageXML expresses complex data types in a structured and standard manner in text format. Using this text format, you can write processing rules for the XML data that are independent of operating systems and programming languages. XSL is a functional style sheet language that can accomplish simple or complex tasks. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation. XSL is built on other XML-based standards, such as XPath, which is the expression language at the core of a password strength validation rule.To implement the password strength validation rules, it is necessary to impose some constraints on the XSL rules. The output of the rule evaluation must conform to one of a known set of result strings. For more information about the format and constraints of password strength validation rules, see Format and constraints of rulesDefine a password strength rule as an XSL template in an XSL style sheet. .Password strengthThe password strength module validates the strength of new passwords.

Password strength validation rule language

Extensible Style Language (XSL) specifies rules. Extensible Markup Language (XML) is the language for the data. It forms an input to the rules. The combination of XML and XSL provides a platform-independent method of expressing both the inputs to the rules evaluator and the rules themselves.

XML expresses complex data types in a structured and standard manner in text format. Using this text format, you can write processing rules for the XML data that are independent of operating systems and programming languages.

XSL is a functional style sheet language that can accomplish simple or complex tasks. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation. XSL is built on other XML-based standards, such as XPath, which is the expression language at the core of a password strength validation rule.

To implement the password strength validation rules, it is necessary to impose some constraints on the XSL rules. The output of the rule evaluation must conform to one of a known set of result strings. For more information about the format and constraints of password strength validation rules, see Format and constraints of rules.

Parent topic: Password strength

UMI XML document modelThe Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the password strength validation rules implementation. This model enables the interface to be both simple and functional for password strength validation purposes.UMIXML document modelXMLUMI document modelThe model constrains the rules to function in a predetermined XML document format with the same top-level XML document element for all rules. The XML UMI that is imported by the rules evaluator from user attributes must be inserted into this XML document before the data can be used. To simplify the process of defining rules, the rules must operate in the confines of the UMI XML model. The UMI XML model requires the XML document to contain the following top-level XML element into which all target UMI for a particular rule evaluation is inserted. The XMLUMI element is created automatically as part of the rule evaluation process by the password strength validation engine.<XMLUMI> <!--XML formatted UMI are inserted here. --> </XMLUMI>As a result of this restriction, the XPath to the data in a rule must include the prefix /XMLUMI to access a particular data element in the model. For example, if you add a UMI item of stsuuser:STSUniversalUser to the document, you must specify the XPath /XMLUMI/stsuuser:STSUniversalUser to access the data in the XML object stsuuser:STSUniversalUser.An XPath is the path to a particular child element in the hierarchy of a structured XML data object. It is similar to the mechanism that a directory path on a hard disk uses to access a specific file. An XPath designation starts from the root of the document and traces a path from this root through its child elements to the specific element that is referenced. For example, to use the example entitlement stsuuser:STSUniversalUser in the XML password strength validation modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a password strength validation rule. , the following XPath accesses the address element of /XMLUMI/stsuuser:STSUniversalUser:"/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser: Attribute[@name='password']/stsuuser:Value"XPaths like this example are the means by which password strength validation rules access the UMI data values for attribute-based password strength validation decisions.Because all data elements are restricted to work in the UMI XML model, the password strength validation rules must also be restricted to operate on or match XPaths in the model. Therefore, XSL template match statements are also restricted to matching XPaths that start from /XMLUMI in the UMI XML document. For more information, see Format and constraints of rulesDefine a password strength rule as an XSL template in an XSL style sheet. .Password strengthThe password strength module validates the strength of new passwords.

UMI XML document model

The Universal Management Infrastructure XML document model (UMI XML model) is a set of restrictions that are placed on the XSL or XML model by the password strength validation rules implementation. This model enables the interface to be both simple and functional for password strength validation purposes.

The model constrains the rules to function in a predetermined XML document format with the same top-level XML document element for all rules. The XML UMI that is imported by the rules evaluator from user attributes must be inserted into this XML document before the data can be used. To simplify the process of defining rules, the rules must operate in the confines of the UMI XML model.

The UMI XML model requires the XML document to contain the following top-level XML element into which all target UMI for a particular rule evaluation is inserted. The XMLUMI element is created automatically as part of the rule evaluation process by the password strength validation engine.

<XMLUMI>
<!--XML formatted UMI are inserted here.    -->
</XMLUMI>

As a result of this restriction, the XPath to the data in a rule must include the prefix /XMLUMI to access a particular data element in the model. For example, if you add a UMI item of stsuuser:STSUniversalUser to the document, you must specify the XPath /XMLUMI/stsuuser:STSUniversalUser to access the data in the XML object stsuuser:STSUniversalUser.

An XPath is the path to a particular child element in the hierarchy of a structured XML data object. It is similar to the mechanism that a directory path on a hard disk uses to access a specific file. An XPath designation starts from the root of the document and traces a path from this root through its child elements to the specific element that is referenced. For example, to use the example entitlement stsuuser:STSUniversalUser in the XML password strength validation model, the following XPath accesses the address element of /XMLUMI/stsuuser:STSUniversalUser:

"/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:
Attribute[@name='password']/stsuuser:Value"

XPaths like this example are the means by which password strength validation rules access the UMI data values for attribute-based password strength validation decisions.

Because all data elements are restricted to work in the UMI XML model, the password strength validation rules must also be restricted to operate on or match XPaths in the model. Therefore, XSL template match statements are also restricted to matching XPaths that start from /XMLUMI in the UMI XML document. For more information, see Format and constraints of rules.

Parent topic: Password strength

Containers and XML UMI container namesWhen data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element, for example, elements that might be considered for billing purposes.UMIcontainers and container namesXMLUMI containers and container namescontainers for UMIcontainer namesfor UMI containersThis convention also applies to the UMI XML model. The UMI that is used in password strength validation rules is also defined and manipulated as containers of XML data. For example, the stsuuser:STSUniversalUser XML object that is defined in XML password strength validation modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a password strength validation rule. is an example of a UMI container. The topmost element in the definition of an item of UMI is the container name of that item. When you define a password strength validation rule, the XPath to the XML definition of data in any UMI container must be referenced with the name of the container as the first element after /XMLUMI. To access any element in the stsuuser:STSUniversalUser container in the UMI item stsuuser:STSUniversalUser example, prefix the XPath specification with stsuuser:STSUniversalUser. For example, "/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='password']/stsuuser:Value" refers to the password value. To access this information from a password strength validation rule, prefix this XPath with the top-level element of the XML target UMI input document, which is XMLUMI. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='password']/stsuuser:Value". The example rule file contains a template match statement of /XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList, which means that you can specify all attributes of the password strength validation file without a prefix. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='password']/stsuuser:Value" is the same as "stsuuser:Attribute[@name='password']/stsuuser:Value". For more information, see Format and constraints of rulesDefine a password strength rule as an XSL template in an XSL style sheet. .Password strengthThe password strength module validates the strength of new passwords.

Containers and XML UMI container names

When data is requested from a resource manager, the granularity of the returned XML data is at the level of a single container of information. The container is normally also the smallest data element, for example, elements that might be considered for billing purposes.

This convention also applies to the UMI XML model. The UMI that is used in password strength validation rules is also defined and manipulated as containers of XML data. For example, the stsuuser:STSUniversalUser XML object that is defined in XML password strength validation model is an example of a UMI container.

The topmost element in the definition of an item of UMI is the container name of that item. When you define a password strength validation rule, the XPath to the XML definition of data in any UMI container must be referenced with the name of the container as the first element after /XMLUMI.

To access any element in the stsuuser:STSUniversalUser container in the UMI item stsuuser:STSUniversalUser example, prefix the XPath specification with stsuuser:STSUniversalUser. For example, "/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='password']/stsuuser:Value" refers to the password value.

To access this information from a password strength validation rule, prefix this XPath with the top-level element of the XML target UMI input document, which is XMLUMI. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='password']/stsuuser:Value".

The example rule file contains a template match statement of /XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList, which means that you can specify all attributes of the password strength validation file without a prefix. For example, "/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList/stsuuser:Attribute[@name='password']/stsuuser:Value" is the same as "stsuuser:Attribute[@name='password']/stsuuser:Value". For more information, see Format and constraints of rules.

Parent topic: Password strength

XML password strength validation modelThe following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a password strength validation rule. XMLpassword strength validation examplepassword strength validation exampleXMLThe document contains one container that is named stsuuser. The attribute value of the container stsuuser:STSUniversalUser is defined in XML. The evaluator automatically encompasses all of the data under the XML top-level node declaration XMLUMI when the UMI XML document is created, so this top-level element is added for clarity.The XML document is automatically created by Security Access Manager with the attributes that are in the password change request. The XML document that is passed to the evaluation routines by the password strength validation rules evaluator is as follows: <?xml version="1.0" encoding='UTF-8'?> <XMLUMI> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> - user identity - </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="old-password"> <stsuuser:Value>-attrvalue-</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="password"> <stsuuser:Value>-attrvalue-</stsuuser:Value> </stsuuser:Attribute> </stsuuser:AttributeList> </stsuuser:STSUniversalUser> </XMLUMI>When you reference a particular UMI item in the XMLUMI document for a rule, the XPath path specifier can begin from the container name of the XML element, for example, stsuuser:STSUniversalUser. If the callers want to specify their own template match statement explicitly, they can.For more information, see Format and constraints of rulesDefine a password strength rule as an XSL template in an XSL style sheet. .Password strengthThe password strength module validates the strength of new passwords.

XML password strength validation model

The following UMI XML document shows the data that is passed to the XSL processor from the rules evaluator during the evaluation of a password strength validation rule.

The document contains one container that is named stsuuser. The attribute value of the container stsuuser:STSUniversalUser is defined in XML.

The evaluator automatically encompasses all of the data under the XML top-level node declaration XMLUMI when the UMI XML document is created, so this top-level element is added for clarity.

The XML document is automatically created by Security Access Manager with the attributes that are in the password change request. The XML document that is passed to the evaluation routines by the password strength validation rules evaluator is as follows:

<?xml version="1.0" encoding='UTF-8'?>

<XMLUMI>
  <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
    <stsuuser:Principal>
      <stsuuser:Attribute name="name">
        <stsuuser:Value>
          - user identity -
        </stsuuser:Value>
      </stsuuser:Attribute>
    </stsuuser:Principal>
    <stsuuser:AttributeList>
      <stsuuser:Attribute name="old-password">
        <stsuuser:Value>-attrvalue-</stsuuser:Value>
      </stsuuser:Attribute>
      <stsuuser:Attribute name="password">
        <stsuuser:Value>-attrvalue-</stsuuser:Value>
      </stsuuser:Attribute>
    </stsuuser:AttributeList>
  </stsuuser:STSUniversalUser>
</XMLUMI>

When you reference a particular UMI item in the XMLUMI document for a rule, the XPath path specifier can begin from the container name of the XML element, for example, stsuuser:STSUniversalUser. If the callers want to specify their own template match statement explicitly, they can.

For more information, see Format and constraints of rules.

Parent topic: Password strength

Password strength rules evaluatorThe evaluator evaluates password strength rules in the constraints that are required by the password strength validation engine. A configuration file that you specify supplies the pre-configured rules to the password strength validation module.password strength rulesevaluatorevaluatorpassword strength rulesThe password strength validation rules evaluator sends the rule policy with the XML representation of the password change request to the XSL processor for evaluation.The input into the rule evaluation is an XML representation of the change password data. For example:<?xml version="1.0" encoding='UTF-8'?> <XMLUMI> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal> <stsuuser:Attribute name="name"> <stsuuser:Value> testuser </stsuuser:Value> </stsuuser:Attribute> </stsuuser:Principal> <stsuuser:AttributeList> <stsuuser:Attribute name="old-password"> <stsuuser:Value>passw0rd</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="password"> <stsuuser:Value>newPassw0rd</stsuuser:Value> </stsuuser:Attribute> </stsuuser:AttributeList> </stsuuser:STSUniversalUser> </XMLUMI>The output of the evaluation is as follows: <valid>result</valid>where result is either true or false.If the XSLT rules do not generate a result of either true or false, the password change fails, and an authentication error is printed in the WebSEAL log. For example: HPDAC0949E Validation of the rule text for rule object "pwdstrengthauthn" failed. Error code 0x1005b3b4 was returned along with error message "<valid xmlns:stsuuser=" urn:ibm:names:ITFIM:1.0:stsuuser">invalidResponse</valid>". 50 2014-07-29-17:52:01.670+10:00I----- 0x132120DD webseald WARNING ias authsvc pdauthn.cpp 1497 0x7f9c811a8700 -- HPDIA0221W Authentication for user userA failed. You have used an invalid user name, password or client certificate. Password strengthThe password strength module validates the strength of new passwords. Format and constraints of rulesDefine a password strength rule as an XSL template in an XSL style sheet. Sample password strength ruleThis example XSLT rule ensures that a password is at least 8 characters long.

Password strength rules evaluator

The evaluator evaluates password strength rules in the constraints that are required by the password strength validation engine. A configuration file that you specify supplies the pre-configured rules to the password strength validation module.

The password strength validation rules evaluator sends the rule policy with the XML representation of the password change request to the XSL processor for evaluation.

The input into the rule evaluation is an XML representation of the change password data. For example:

<?xml version="1.0" encoding='UTF-8'?>

<XMLUMI>
  <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
    <stsuuser:Principal>
      <stsuuser:Attribute name="name">
        <stsuuser:Value>
          testuser
        </stsuuser:Value>
      </stsuuser:Attribute>
    </stsuuser:Principal>
    <stsuuser:AttributeList>
      <stsuuser:Attribute name="old-password">
        <stsuuser:Value>passw0rd</stsuuser:Value>
      </stsuuser:Attribute>
      <stsuuser:Attribute name="password">
        <stsuuser:Value>newPassw0rd</stsuuser:Value>
      </stsuuser:Attribute>
    </stsuuser:AttributeList>
  </stsuuser:STSUniversalUser>
</XMLUMI>

The output of the evaluation is as follows:

<valid>result</valid>

where result is either true or false.

If the XSLT rules do not generate a result of either true or false, the password change fails, and an authentication error is printed in the WebSEAL log. For example:

HPDAC0949E   Validation of the rule text for rule object "pwdstrengthauthn" failed.
Error code 0x1005b3b4 was returned along with error message "<valid xmlns:stsuuser="
urn:ibm:names:ITFIM:1.0:stsuuser">invalidResponse</valid>".
50        2014-07-29-17:52:01.670+10:00I----- 0x132120DD webseald WARNING ias authsvc
pdauthn.cpp 1497 0x7f9c811a8700 -- HPDIA0221W   Authentication for user userA failed.
You have used an invalid user name, password or client certificate.

Format and constraints of rules
Define a password strength rule as an XSL template in an XSL style sheet.

Sample password strength rule
This example XSLT rule ensures that a password is at least 8 characters long.

Parent topic: Password strength

Format and constraints of rulesDefine a password strength rule as an XSL template in an XSL style sheet. user mapping rulesformat and constraintsformatuser mapping rulesconstraintsuser mapping rulesWrite the rule in a valid XSL template rule format with XSLT version 1.0. It must return a text document that contains the string identifiers in User mapping rules evaluatorThe user mapping rules evaluator evaluates user mapping rules in the constraints that are required by the user mapping engine. A configuration file that you specify supplies the pre-configured rules to the authenticated user mapping module..Password strength rules evaluatorThe evaluator evaluates password strength rules in the constraints that are required by the password strength validation engine. A configuration file that you specify supplies the pre-configured rules to the password strength validation module.

Format and constraints of rules

Define a password strength rule as an XSL template in an XSL style sheet.

Write the rule in a valid XSL template rule format with XSLT version 1.0. It must return a text document that contains the string identifiers in User mapping rules evaluator.

Parent topic: Password strength rules evaluator

Sample password strength ruleThis example XSLT rule ensures that a password is at least 8 characters long.<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0"> <!-- Required to constrain output of rule evaluation --> <xsl:output method="xml" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/> <!-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template> <!-- Let's make it easier by matching the constant part of our XML name --> <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList">A <xsl:choose> <xsl:when test="string-length(stsuuser:Attribute [@name='password']/stsuuser:Value) >= 8"> <valid>true</valid> </xsl:when> <xsl:otherwise> <valid>false</valid> </xsl:otherwise> </xsl:choose> </xsl:template> </xsl:stylesheet>Password strength rules evaluatorThe evaluator evaluates password strength rules in the constraints that are required by the password strength validation engine. A configuration file that you specify supplies the pre-configured rules to the password strength validation module.

Sample password strength rule

This example XSLT rule ensures that a password is at least 8 characters long.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0">

    <!-- Required to constrain output of rule evaluation -->
    <xsl:output method="xml" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/>

    <!-- Need this to ensure default text node printing is off -->
    <xsl:template match="text()"></xsl:template>

    <!-- Let's make it easier by matching the constant part of our XML name -->
    <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList">A
      <xsl:choose>
        <xsl:when test="string-length(stsuuser:Attribute
        [@name='password']/stsuuser:Value) >= 8">
          <valid>true</valid>
        </xsl:when>
        <xsl:otherwise>
          <valid>false</valid>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:template>

</xsl:stylesheet>

Parent topic: Password strength rules evaluator

Enabling password strength validationThe password strength validation module is disabled by default. You must enable it before you can validate whether a new password meets the configured criteria.password strength validationenableAccess the local management interface to configure an XSLT rules file to define the password strength rules. The following steps use password-rules.xslt as an example. Select Secure Web SettingsGlobal SettingsPassword Strength from the top menu. The Password Strength management page displays. Take one of the following actions:If rules files exist, select the file that you want to enable, such as password-rules.xslt, from the available list of File Names. If no rules files exist: Click New to create a new rules file. Enter a name for the new file such as password-rules.xslt.Click Save. The system generates a new file that is based on the default template.Click Edit.Update the file to reflect the rules you want to set.Click Save.Access the WebSEAL configuration file for your instance.Update the [password-strength] stanza in the WebSEAL configuration file as follows: [password-strength] rules-file = file debug-level = level where: fileSpecifies the name of the rules file for the password strength validation module.levelControls the trace level for the module.[password-strength] rules-file = password-rules.xslt debug-level = 5 The level variable indicates the trace level; 1 designates a minimal amount of tracing, and 9 designates the maximum. The Security Access Manager pdadmin trace command also modifies the trace level by using the trace component name of pd.cas.pwdstrength. This trace component is only available after the first change password operation is processed.Password strengthThe password strength module validates the strength of new passwords.

Enabling password strength validation

The password strength validation module is disabled by default. You must enable it before you can validate whether a new password meets the configured criteria.

Procedure

Access the local management interface to configure an XSLT rules file to define the password strength rules. The following steps use password-rules.xslt as an example.

Select Secure Web Settings > Global Settings > Password Strength from the top menu. The Password Strength management page displays.

Take one of the following actions:

If rules files exist, select the file that you want to enable, such as password-rules.xslt, from the available list of File Names.

If no rules files exist:

Click New to create a new rules file.

Enter a name for the new file such as password-rules.xslt.

Click Save. The system generates a new file that is based on the default template.

Click Edit.

Update the file to reflect the rules you want to set.

Click Save.

Access the WebSEAL configuration file for your instance.

Update the [password-strength] stanza in the WebSEAL configuration file as follows:

[password-strength]
rules-file = file
debug-level = level

where:

file

Specifies the name of the rules file for the password strength validation module.

level

Controls the trace level for the module.

[password-strength]
rules-file = password-rules.xslt
debug-level = 5

Note: The level variable indicates the trace level; 1 designates a minimal amount of tracing, and 9 designates the maximum. The Security Access Manager pdadmin trace command also modifies the trace level by using the trace component name of pd.cas.pwdstrength. This trace component is only available after the first change password operation is processed.

Parent topic: Password strength

Password strength validation attributesYou can use these attributes in the password strength validation rules. password strength attributesvalidValid password strength validation attributesAttributeDescriptionold-passwordThe original password for the user.passwordThe new password for the user.Password strengthThe password strength module validates the strength of new passwords.

Password strength validation attributes

You can use these attributes in the password strength validation rules.

Table 45. Valid password strength validation attributes

Attribute | Description
old-password | The original password for the user.
password | The new password for the user.

Parent topic: Password strength

Post-authentication processingPost-authentication processingpost-authentication processingprocessingpost-authenticationThis chapter discusses supplemental post-authentication processes.Topic Index:AuthenticationAutomatic redirection after authenticationServer-side request caching

Post-authentication processing

This chapter discusses supplemental post-authentication processes.

Topic Index:

Automatic redirection after authentication

Server-side request caching

Parent topic: Authentication

Automatic redirection after authenticationAutomatic redirection after authenticationauthenticationforced redirectionautomatic redirectionredirectionautomatichome pageautomatic redirectionhome pageforced redirectionhome pageThis section contains the following topics:Post-authentication processingServer-side request cachingOverview of automatic redirectionWhen a user makes a request for a resource in a WebSEAL domain, WebSEAL sends the resource to the user upon successful authentication and policy checks. As an alternative to this standard response, you can configure WebSEAL to automatically redirect the user to a specially designated home or welcome page.Enabling automatic redirectionDisabling automatic redirectionLimitationsMacro support for automatic redirection

Automatic redirection after authentication

This section contains the following topics:

Overview of automatic redirection
When a user makes a request for a resource in a WebSEAL domain, WebSEAL sends the resource to the user upon successful authentication and policy checks. As an alternative to this standard response, you can configure WebSEAL to automatically redirect the user to a specially designated home or welcome page.

Enabling automatic redirection

Disabling automatic redirection

Limitations

Macro support for automatic redirection

Parent topic: Post-authentication processing

Related concepts:

Server-side request caching

Overview of automatic redirectionOverview of automatic redirectionWhen a user makes a request for a resource in a WebSEAL domain, WebSEAL sends the resource to the user upon successful authentication and policy checks. As an alternative to this standard response, you can configure WebSEAL to automatically redirect the user to a specially designated home or welcome page.automatic redirectionoverviewThe customized redirection can be further configured with a range of macros specifying the user's authorization level, username, host name and so forth.This forced redirection after login is appropriate, for example, when users enter the WebSEAL domain through a portal page. Automatic redirection also overrides user attempts to directly access specific pages within the domain by selecting user bookmarks.The automatic redirection process flow is as follows:The user sends a request and successfully authenticates.WebSEAL builds a custom response and returns it to the browser as a redirect. This redirect response contains the URL value specified by the login-redirect-page stanza entry in the WebSEAL configuration file.The browser follows the redirect response (containing the configured URL).WebSEAL returns the page located at the configured URL.Automatic redirection after login is enabled and disabled independently for each authentication method. Automatic redirection is supported for the following authentication methods:Forms authenticationBasic authenticationExternal authentication interfaceAutomatic redirection after authentication

Overview of automatic redirection

When a user makes a request for a resource in a WebSEAL domain, WebSEAL sends the resource to the user upon successful authentication and policy checks. As an alternative to this standard response, you can configure WebSEAL to automatically redirect the user to a specially designated home or welcome page.

The customized redirection can be further configured with a range of macros specifying the user's authorization level, username, host name and so forth.

This forced redirection after login is appropriate, for example, when users enter the WebSEAL domain through a portal page. Automatic redirection also overrides user attempts to directly access specific pages within the domain by selecting user bookmarks.

The automatic redirection process flow is as follows:

The user sends a request and successfully authenticates.

WebSEAL builds a custom response and returns it to the browser as a redirect.

This redirect response contains the URL value specified by the login-redirect-page stanza entry in the WebSEAL configuration file.

The browser follows the redirect response (containing the configured URL).

WebSEAL returns the page located at the configured URL.

Automatic redirection after login is enabled and disabled independently for each authentication method. Automatic redirection is supported for the following authentication methods:

Forms authentication

Basic authentication

External authentication interface

Parent topic: Automatic redirection after authentication

Enabling automatic redirectionEnabling automatic redirectionautomatic redirectionenablingenable-redirects stanzaredirect stanza entrylogin-redirect-page stanza entryacnt-mgt stanzaenabling automatic redirection To configure automatic redirection, complete the following steps:Open the WebSEAL configuration file for editing. Enable automatic redirection for each of the applicable authentication methods by uncommenting the entry for each method in the [enable-redirects] stanza: [enable-redirects] redirect = forms-auth redirect = basic-auth redirect = cert-auth redirect = ext-auth-interfaceThe example above enables automatic redirection for forms authentication, basic authentication, certificate authentication, and EAI authentication.Specify the URL to which the user is redirected after login. The URL can be expressed as either an absolute URL or a server-relative URL, with or without an embedded macro.For example: [acnt-mgt] login-redirect-page = http://www.ibm.comor:[acnt-mgt] login-redirect-page = /jct/intro-page.htmlor:[acnt-mgt] login-redirect-page = /jct/intro-page.html?level=%AUTHNLEVEL%&url=%URL%Stop and restart the WebSEAL server.Automatic redirection after authentication

Enabling automatic redirection

About this task

To configure automatic redirection, complete the following steps:

Procedure

Open the WebSEAL configuration file for editing.

Enable automatic redirection for each of the applicable authentication methods by uncommenting the entry for each method in the [enable-redirects] stanza:

[enable-redirects]
redirect = forms-auth
redirect = basic-auth
redirect = cert-auth
redirect = ext-auth-interface

The example above enables automatic redirection for forms authentication, basic authentication, certificate authentication, and EAI authentication.

Specify the URL to which the user is redirected after login. The URL can be expressed as either an absolute URL or a server-relative URL, with or without an embedded macro. For example:

[acnt-mgt]
login-redirect-page = http://www.ibm.com

or:

[acnt-mgt]
login-redirect-page = /jct/intro-page.html

or:

[acnt-mgt]
login-redirect-page = /jct/intro-page.html?level=%AUTHNLEVEL%&url=%URL%

Stop and restart the WebSEAL server.

Parent topic: Automatic redirection after authentication

Disabling automatic redirectionDisabling automatic redirectionenable-redirects stanzaredirect stanza entryautomatic redirectiondisabling To disable automatic redirection, complete the following steps:Open the WebSEAL configuration file for editing. Disable automatic redirection for each of the applicable authentication methods by commenting or removing the entry for each authentication method in the [enable-redirects] stanza: [enable-redirects] #redirect = forms-auth #redirect = basic-auth #redirect = cert-auth #redirect = ext-auth-interface Note that the hash character ( # ) is added to the start of each line. The example above disables automatic redirection for forms authentication, basic authentication, certificate authentication, and EAI authentication.Stop and restart the WebSEAL server.Automatic redirection after authentication

Disabling automatic redirection

About this task

To disable automatic redirection, complete the following steps:

Procedure

Open the WebSEAL configuration file for editing.

Disable automatic redirection for each of the applicable authentication methods by commenting or removing the entry for each authentication method in the [enable-redirects] stanza:

[enable-redirects]
#redirect = forms-auth
#redirect = basic-auth
#redirect = cert-auth
#redirect = ext-auth-interface

Note that the hash character ( # ) is added to the start of each line. The example above disables automatic redirection for forms authentication, basic authentication, certificate authentication, and EAI authentication.

Stop and restart the WebSEAL server.

Parent topic: Automatic redirection after authentication

LimitationsLimitationsWebSEALlimitationslimitationsWebSEALWebSEAL does not support automatic redirection at login under the following conditions: During reauthentication.When the browser is reopened while using basic authentication. Redirection works as expected the first time a user visits a page with a browser and authenticates with a valid user name and password. However, if that instance of the browser is closed and another opened, the redirected page is not displayed after the user is authenticated.Automatic redirection after authentication

Limitations

WebSEAL does not support automatic redirection at login under the following conditions:

During reauthentication.

When the browser is reopened while using basic authentication.

Redirection works as expected the first time a user visits a page with a browser and authenticates with a valid user name and password. However, if that instance of the browser is closed and another opened, the redirected page is not displayed after the user is authenticated.

Parent topic: Automatic redirection after authentication

Macro support for automatic redirectionMacro support for automatic redirectionautomatic redirectionspecify macro supportmacrossupportautomatic redirectionAutomatic redirection provides support for a subset of the macros provided by WebSEAL to customize the static redirect URL. Macros allow dynamic substitution of information from WebSEAL. Macros are specified as an argument in the query string of the redirection URL. Specific characters in the macro values are URI-encoded (see Encoding of macro contents).Valid WebSEAL macros for use in automatic redirection are:MacroDescriptionAUTHNLEVEL Authentication level required by authentication strength policy (step-up).HOSTNAME Fully qualified host name.PROTOCOL The client connection protocol used. Can be HTTP or HTTPS.URL The URL requested by the client.USERNAME The name of the logged in user. The value "unauthenticated" is used for users who are not logged in. (See also Customization of login forms for reauthenticationWebSEAL supports reauthentication for both forms authentication methods..)HTTPHDR{name} Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro contains the text: Unknown. For example, the macro name to include the "Host" HTTP header is HTTPHDR{Host}.CREDATTR{name} Used to include the contents of a specified attribute in the user credential. If the specified credential attribute does not exist in the request, the macro contains the text: 'Unknown'. For example, use the following macro name to include the tagvalue_session_index attribute, which contains the secret token for the session: CREDATTR{tagvalue_session_index}.Automatic redirection after authenticationEncoding of macro contentsMacro content length considerations

Macro support for automatic redirection

Automatic redirection provides support for a subset of the macros provided by WebSEAL to customize the static redirect URL. Macros allow dynamic substitution of information from WebSEAL.

Macros are specified as an argument in the query string of the redirection URL. Specific characters in the macro values are URI-encoded (see Encoding of macro contents).

Valid WebSEAL macros for use in automatic redirection are:

Macro
Description

AUTHNLEVEL

Authentication level required by authentication strength policy (step-up).

HOSTNAME

Fully qualified host name.

PROTOCOL

The client connection protocol used. Can be HTTP or HTTPS.

URL

The URL requested by the client.

USERNAME

The name of the logged in user. The value "unauthenticated" is used for users who are not logged in. (See also Customization of login forms for reauthentication.)

HTTPHDR{name}

Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro contains the text: Unknown.

For example, the macro name to include the "Host" HTTP header is HTTPHDR{Host}.

CREDATTR{name}

Used to include the contents of a specified attribute in the user credential. If the specified credential attribute does not exist in the request, the macro contains the text: 'Unknown'.

For example, use the following macro name to include the tagvalue_session_index attribute, which contains the secret token for the session: CREDATTR{tagvalue_session_index}.

Encoding of macro contents

Macro content length considerations

Parent topic: Automatic redirection after authentication

Encoding of macro contentsEncoding of macro contentsautomatic redirectionURI encoding for macrosURI encoding for macrosSome macro content contains user-provided data such as the requested URI or the Referer header of that request. It is important for security reasons to ensure that reserved, or special characters in client-supplied data are encoded. WebSEAL URI encodes macro contents to ensure that the content does not return reserved, or special characters back to the client. URI encoding is an international standard that allows you to map the wide range of characters used worldwide into the limited character-set used by a URI.Notes on encoding macro contents:WebSEAL always applies URI encoding to macro contents, even if the original data has already been encoded.Encoded macro contents must be decoded using standard URI decoding rules.URI encoding increases the string length of macro content, and therefore the Location header (where the content is embedded in the query string). For a discussion of Location header length issues, see Macro content length considerations.Macro support for automatic redirection

Encoding of macro contents

Some macro content contains user-provided data such as the requested URI or the Referer header of that request. It is important for security reasons to ensure that reserved, or special characters in client-supplied data are encoded.

WebSEAL URI encodes macro contents to ensure that the content does not return reserved, or special characters back to the client. URI encoding is an international standard that allows you to map the wide range of characters used worldwide into the limited character-set used by a URI.

Notes on encoding macro contents:

WebSEAL always applies URI encoding to macro contents, even if the original data has already been encoded.

Encoded macro contents must be decoded using standard URI decoding rules.

URI encoding increases the string length of macro content, and therefore the Location header (where the content is embedded in the query string). For a discussion of Location header length issues, see Macro content length considerations.

Parent topic: Macro support for automatic redirection

Macro content length considerationsMacro content length considerationsautomatic redirectionmacro content lengthmacroscontent length considerationsInformation supplied by macros increases the string length of the Location URI header. URI encoding of macro content further increases this string length. Some client applications (such as WAP browsers on cellular phones) have URI length limitations due to the small memory capacity of the device. If a URI exceeds the length limitation on such a client device, errors can occur and the link will likely fail. WebSEAL does not impose any length restrictions on the Location URI header. Therefore, when configuring macros for local response redirection, you must carefully consider the possible limitations of client devices that access your site. You can estimate the length of the Location header by determining the fixed lengths of the URI and the TAM_OP values, and factor in expected sizes of any macros used in the query string.The following table provides information about the possible lengths of the content provided by the macros used for local response redirection:MacroSize of ContentAUTHNLEVELNo more than 10 characters.HOSTNAMEThe length of the HOST header of the corresponding request, or the fully qualified host name of the WebSEAL system if the HOST header is not present.PROTOCOLNo more than 10 characters.URLLength of the request URI.USERNAMEMaximum length defined by user name length policy for this implementation of WebSEAL.HTTPHDR{name}Length of the specified HTTP header.CREDATTR{name}Length of the contents for the specified attribute in the user credential.Macro support for automatic redirection

Macro content length considerations

Information supplied by macros increases the string length of the Location URI header. URI encoding of macro content further increases this string length.

Some client applications (such as WAP browsers on cellular phones) have URI length limitations due to the small memory capacity of the device. If a URI exceeds the length limitation on such a client device, errors can occur and the link will likely fail.

WebSEAL does not impose any length restrictions on the Location URI header. Therefore, when configuring macros for local response redirection, you must carefully consider the possible limitations of client devices that access your site. You can estimate the length of the Location header by determining the fixed lengths of the URI and the TAM_OP values, and factor in expected sizes of any macros used in the query string.

The following table provides information about the possible lengths of the content provided by the macros used for local response redirection:

Macro | Size of Content
AUTHNLEVEL | No more than 10 characters.
HOSTNAME | The length of the HOST header of the corresponding request, or the fully qualified host name of the WebSEAL system if the HOST header is not present.
PROTOCOL | No more than 10 characters.
URL | Length of the request URI.
USERNAME | Maximum length defined by user name length policy for this implementation of WebSEAL.
HTTPHDR{name} | Length of the specified HTTP header.
CREDATTR{name} | Length of the contents for the specified attribute in the user credential.

Parent topic: Macro support for automatic redirection

Server-side request caching Server-side request caching server-side request cachingrequestcachingPOSTrequestscachingauthenticationserver-side request cachingThis section contains the following topics:Post-authentication processingAutomatic redirection after authenticationServer-side request caching conceptsProcess flow for server-side request cachingConfiguration of server-side caching

Server-side request caching

This section contains the following topics:

Server-side request caching concepts

Process flow for server-side request caching

Configuration of server-side caching

Parent topic: Post-authentication processing

Related concepts:

Automatic redirection after authentication

Server-side request caching conceptsServer-side request caching conceptsserver side cacherequest conceptsIn past versions of WebSEAL, WebSEAL created a cache entry for the URL of a user request whenever authentication was required. Upon successful authentication, WebSEAL sent an HTTP redirect to the browser that included this URL. The browser then followed the redirect to the original resource location.A limitation of this implementation became apparent when, for example, a POST request was interrupted by a session timeout that required the user to login again. Because WebSEAL only cached the URL of the original request, the POST data (including the Method and Message-body) were lost during the HTTP redirect. The user had to rebuild the POST request.WebSEAL now caches a more complete set of request data and uses this cached data to rebuild the request during the HTTP redirect whenever the request processing is interrupted and the user is required to login again. This solution particularly benefits POST and PUT requests, because these requests types can include a message body in the request.Server-side request caching is supported for forms, external authentication interface, e-community single signon, and certificate authentication methods whenever the request processing is interrupted by a login requirement, a reauthentication requirement, or an authentication strength (step-up) requirement.Server-side request caching

Server-side request caching concepts

In past versions of WebSEAL, WebSEAL created a cache entry for the URL of a user request whenever authentication was required. Upon successful authentication, WebSEAL sent an HTTP redirect to the browser that included this URL. The browser then followed the redirect to the original resource location.

A limitation of this implementation became apparent when, for example, a POST request was interrupted by a session timeout that required the user to login again. Because WebSEAL only cached the URL of the original request, the POST data (including the Method and Message-body) were lost during the HTTP redirect. The user had to rebuild the POST request.

WebSEAL now caches a more complete set of request data and uses this cached data to rebuild the request during the HTTP redirect whenever the request processing is interrupted and the user is required to login again. This solution particularly benefits POST and PUT requests, because these requests types can include a message body in the request.

Server-side request caching is supported for forms, external authentication interface, e-community single signon, and certificate authentication methods whenever the request processing is interrupted by a login requirement, a reauthentication requirement, or an authentication strength (step-up) requirement.

Parent topic: Server-side request caching

Process flow for server-side request cachingProcess flow for server-side request cachingserver side cacherequest process flowprocess flowserver-side request cachingWhen an additional authentication requirement interrupts a request, the user is prompted to login again. After successful authentication, WebSEAL sends a redirect to the browser for the original resource. Upon receiving this request, WebSEAL rebuilds the request using the cached data and processes the request with that data.Cached request data includes URL, Method, Message-body, query strings, and all other HTTP headers (including cookies). This data is temporarily stored in the WebSEAL session cache.The following diagram illustrates a typical server-side request caching process flow:The user successfully logs in and submits an HTTP request for a resource involving a CGI-generated data form. WebSEAL creates a session cache entry for the user.The back-end application server returns the form to the user.During the time it takes the user to fill in the form, the configured session timeout for the user expires. WebSEAL removes the user's cache entry (including credentials) and session ID.Not aware of the session timeout, the user eventually submits the completed form (POST). WebSEAL finds no session cache entry for the user and creates a new cache entry. Because WebSEAL finds no credentials for this user, the user must authenticate. WebSEAL temporarily caches the complete information contained in the POST request and sends a login form to the user.The user submits the completed login form to WebSEAL. Authentication is successful. The cache now contains the user's credentials, as well as the data from the originally cached request.WebSEAL returns a redirect response to the browser containing the URL of the originally requested resource.The browser follows the redirect. WebSEAL intercepts the redirect and rebuilds the original request (the CGI-generated data form) using the cached POST data. The restored form is delivered to the URL destination.Example WebSEAL request caching process flowExample WebSEAL request caching process flowServer-side request caching

Process flow for server-side request caching

When an additional authentication requirement interrupts a request, the user is prompted to login again.

After successful authentication, WebSEAL sends a redirect to the browser for the original resource. Upon receiving this request, WebSEAL rebuilds the request using the cached data and processes the request with that data.

Cached request data includes URL, Method, Message-body, query strings, and all other HTTP headers (including cookies). This data is temporarily stored in the WebSEAL session cache.

The following diagram illustrates a typical server-side request caching process flow:

The user successfully logs in and submits an HTTP request for a resource involving a CGI-generated data form. WebSEAL creates a session cache entry for the user.

The back-end application server returns the form to the user.

During the time it takes the user to fill in the form, the configured session timeout for the user expires. WebSEAL removes the user's cache entry (including credentials) and session ID.

Not aware of the session timeout, the user eventually submits the completed form (POST). WebSEAL finds no session cache entry for the user and creates a new cache entry.

Because WebSEAL finds no credentials for this user, the user must authenticate. WebSEAL temporarily caches the complete information contained in the POST request and sends a login form to the user.

The user submits the completed login form to WebSEAL. Authentication is successful. The cache now contains the user's credentials, as well as the data from the originally cached request.

WebSEAL returns a redirect response to the browser containing the URL of the originally requested resource.

The browser follows the redirect. WebSEAL intercepts the redirect and rebuilds the original request (the CGI-generated data form) using the cached POST data. The restored form is delivered to the URL destination.

Figure 17. Example WebSEAL request caching process flow

Parent topic: Server-side request caching

Configuration of server-side cachingConfiguration of server-side cachingcacheserver sideserver side cacheconfigurationYou can modify settings in the [server] stanza of the WebSEAL configuration file to specify limits to the size of the requests that WebSEAL reads and caches. Usage notes for server-side request caching:Server-side caching helps protect WebSEAL from denial of service attack types that could cause WebSEAL to cache more data than it can handle.Server-side request caching does not function correctly if the user session time out value expires during the login process. In this situation, the cache entry is lost.Server-side request caching can cause limitations with the browser's ability to manipulate the resource. The browser is unaware that WebSEAL has rebuilt the HTTP redirect. Therefore the browser's reload/refresh function and caching ability can be hindered.The following sections describe the settings that you can modify:Server-side request cachingModification of request-body-max-readThe request-body-max-read stanza entry specifies the maximum number of bytes of content to read from the body of POST requests.Modification of request-max-cache

Configuration of server-side caching

You can modify settings in the [server] stanza of the WebSEAL configuration file to specify limits to the size of the requests that WebSEAL reads and caches.

Usage notes for server-side request caching:

Server-side caching helps protect WebSEAL from denial of service attack types that could cause WebSEAL to cache more data than it can handle.

Server-side request caching does not function correctly if the user session time out value expires during the login process. In this situation, the cache entry is lost.

Server-side request caching can cause limitations with the browser's ability to manipulate the resource. The browser is unaware that WebSEAL has rebuilt the HTTP redirect. Therefore the browser's reload/refresh function and caching ability can be hindered.

The following sections describe the settings that you can modify:

Modification of request-body-max-read
The request-body-max-read stanza entry specifies the maximum number of bytes of content to read from the body of POST requests.

Modification of request-max-cache

Parent topic: Server-side request caching

Modification of request-body-max-readModification of request-body-max-readThe request-body-max-read stanza entry specifies the maximum number of bytes of content to read from the body of POST requests.request-body-max-read stanza entrymodificationThis configuration is used for dynurl, authentication, and request caching. The request-body-max-read stanza entry affects the request body only. It does not impose limits on other components of a request, such as request line and headers. See the max-client-read configuration entry in the Web Reverse Proxy Stanza Reference topics in the Knowledge Center.The value of the request-body-max-read stanza entry affects the amount of data that WebSEAL caches for users who must authenticate before their request can be fulfilled. For example, a user name and password submitted with a login form must fit into the request-body-max-read limit. This stanza entry affects all requests that have body content, such as POST and PUT requests.This stanza entry impacts forms authentication, because it limits the size of the POST data that is processed when performing such authentication. To maintain a request body size sufficient for forms authentication, WebSEAL sets an absolute minimum of 512 bytes on request-body-max-read. If you specify a value below that minimum, the setting is ignored and the value 512 is used. There is no maximum value limit. This stanza entry also impacts dynamic URL processing because the query portion of a POST request URI is contained in the request body.This setting does not limit the maximum POST size. The maximum POST size is unlimited.The default value is 4096 bytes:[server] request-body-max-read = 4096When the server-side cache setting for request-body-max-read is exceeded during a request, WebSEAL ends the request caching process. WebSEAL returns a Request Caching Failed error message to the browser, and writes the error to the log file. You can customize this error message. See Guidelines for customizing HTML response pages.The value of request-body-max-read also affects the value specified for request-max-cache. See Modification of request-max-cache.Configuration of server-side caching

Modification of request-body-max-read

The request-body-max-read stanza entry specifies the maximum number of bytes of content to read from the body of POST requests.

This configuration is used for dynurl, authentication, and request caching. The request-body-max-read stanza entry affects the request body only. It does not impose limits on other components of a request, such as request line and headers. See the max-client-read configuration entry in the Web Reverse Proxy Stanza Reference topics in the Knowledge Center.

The value of the request-body-max-read stanza entry affects the amount of data that WebSEAL caches for users who must authenticate before their request can be fulfilled. For example, a user name and password submitted with a login form must fit into the request-body-max-read limit. This stanza entry affects all requests that have body content, such as POST and PUT requests.

This stanza entry impacts forms authentication, because it limits the size of the POST data that is processed when performing such authentication. To maintain a request body size sufficient for forms authentication, WebSEAL sets an absolute minimum of 512 bytes on request-body-max-read. If you specify a value below that minimum, the setting is ignored and the value 512 is used. There is no maximum value limit.

This stanza entry also impacts dynamic URL processing because the query portion of a POST request URI is contained in the request body.

Note: This setting does not limit the maximum POST size. The maximum POST size is unlimited.

The default value is 4096 bytes:

[server]
request-body-max-read = 4096

When the server-side cache setting for request-body-max-read is exceeded during a request, WebSEAL ends the request caching process. WebSEAL returns a Request Caching Failed error message to the browser, and writes the error to the log file. You can customize this error message. See Guidelines for customizing HTML response pages.

The value of request-body-max-read also affects the value specified for request-max-cache. See Modification of request-max-cache.

Parent topic: Configuration of server-side caching

Modification of request-max-cacheModification of request-max-cacherequest-max-cache stanza entryrequest-max-cachemodificationWhen a user is prompted to authenticate before a request can be fulfilled, the data from that request is cached for processing after the completion of the authentication. The maximum amount of data cached per request is specified by the request-max-cache stanza entry.To ensure that you cache the full value of request-body-max-read, you must account for the maximum size of all the other request components in this value. For example, if you want to cache 2048 bytes of request body content, and you anticipate that the maximum size of all request headers and cookies is 4096 bytes:Set request-body-max-read = 2048 Set request-max-cache = 2048 + 4096 = 6144 The default value for request-max-cache is 8192.[server] request-max-cache = 8192When the server-side cache setting for request-max-cache is exceeded during a request, WebSEAL ends the request caching process. WebSEAL returns a Request Caching Failed error message to the browser, and writes the error to the log file. You can customize this error message. See Guidelines for customizing HTML response pages.There is no maximum size for this value other than the maximum imposed by the data type. However, increasing the size can possibly adversely affect performance and system security. Allocating larger buffers increases memory usage and therefore could possibly decrease performance. More importantly, allocating very large buffers increases the risk of a successful denial-of-service attack by a malicious user. The risk is increased simply because WebSEAL is loading and holding more data into memory, which provides the user with a larger buffer from which to attempt an attack.Configuration of server-side caching

Modification of request-max-cache

When a user is prompted to authenticate before a request can be fulfilled, the data from that request is cached for processing after the completion of the authentication. The maximum amount of data cached per request is specified by the request-max-cache stanza entry.

To ensure that you cache the full value of request-body-max-read, you must account for the maximum size of all the other request components in this value. For example, if you want to cache 2048 bytes of request body content, and you anticipate that the maximum size of all request headers and cookies is 4096 bytes:

Set request-body-max-read = 2048

Set request-max-cache = 2048 + 4096 = 6144

The default value for request-max-cache is 8192.

[server]
request-max-cache = 8192

When the server-side cache setting for request-max-cache is exceeded during a request, WebSEAL ends the request caching process. WebSEAL returns a Request Caching Failed error message to the browser, and writes the error to the log file. You can customize this error message. See Guidelines for customizing HTML response pages.

There is no maximum size for this value other than the maximum imposed by the data type. However, increasing the size can possibly adversely affect performance and system security. Allocating larger buffers increases memory usage and therefore could possibly decrease performance. More importantly, allocating very large buffers increases the risk of a successful denial-of-service attack by a malicious user. The risk is increased simply because WebSEAL is loading and holding more data into memory, which provides the user with a larger buffer from which to attempt an attack.

Parent topic: Configuration of server-side caching

Password processingPassword processingpasswordprocessingWebSEALpassword processingThis chapter discusses password processing options available during WebSEAL authentication.Topic Index:AuthenticationLogin failure policy ("three strikes" login policy)Password strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Password processing

This chapter discusses password processing options available during WebSEAL authentication.

Topic Index:

Login failure policy ("three strikes" login policy)

Password strength policy
Password strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Parent topic: Authentication

Login failure policy ("three strikes" login policy)Login failure policy ("three strikes" login policy)three strikes login policiesauthenticationthree strikes login policieslogin failure policiesloginthree strikes login policiesfailure policiesThis section contains the following topics:Password processingPassword strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.Login failure policy conceptsSetting the login failure policySetting the account disable time intervalConfiguring the account disable notification responseLogin failure policy with replicated WebSEAL servers

Login failure policy ("three strikes" login policy)

This section contains the following topics:

Login failure policy concepts

Setting the login failure policy

Setting the account disable time interval

Configuring the account disable notification response

Login failure policy with replicated WebSEAL servers

Parent topic: Password processing

Related concepts:

Password strength policy

Login failure policy conceptsLogin failure policy conceptsmax-login-failures policydisable-time-interval policyThe login failure ("three strikes") policy, available for Security Access Manager installations using an LDAP-based user registry, enables you to specify a maximum number of failed login attempts (n) and a penalty lockout time (x), such that after "n" failed login attempts a user is locked out for "x" seconds (or, alternatively, the account is disabled).The login failure policy can help prevent computer password attacks. The policy creates a condition where a user must wait a period of time before making additional login attempts. For example, a policy could dictate 3 failed attempts followed by a 180 second lockout penalty. This type of login policy can prevent random computer-generated login attempts that occur many times a second. The login failure policy requires the joint contribution of two policy settings: Maximum number of failed login attempts: max-login-failuresPenalty for reaching or exceeding the failed login attempt setting: disable-time-interval The penalty setting can include a temporary account lockout time interval or a complete disabling of the account.WebSEAL returns a server response error page (acct_locked.html) that notifies the user of the penalty. The late-lockout-notification stanza entry in the [server] stanza of the WebSEAL configuration file specifies whether this notification occurs when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit.See also Removal of a user session at login failure policy limit.Login failure policy ("three strikes" login policy)

Login failure policy concepts

The login failure ("three strikes") policy, available for Security Access Manager installations using an LDAP-based user registry, enables you to specify a maximum number of failed login attempts (n) and a penalty lockout time (x), such that after "n" failed login attempts a user is locked out for "x" seconds (or, alternatively, the account is disabled).

The login failure policy can help prevent computer password attacks. The policy creates a condition where a user must wait a period of time before making additional login attempts. For example, a policy could dictate 3 failed attempts followed by a 180 second lockout penalty. This type of login policy can prevent random computer-generated login attempts that occur many times a second.

The login failure policy requires the joint contribution of two policy settings:

Maximum number of failed login attempts:

max-login-failures

Penalty for reaching or exceeding the failed login attempt setting:

disable-time-interval

The penalty setting can include a temporary account lockout time interval or a complete disabling of the account.

WebSEAL returns a server response error page (acct_locked.html) that notifies the user of the penalty. The late-lockout-notification stanza entry in the [server] stanza of the WebSEAL configuration file specifies whether this notification occurs when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit.

See also Removal of a user session at login failure policy limit.

Parent topic: Login failure policy ("three strikes" login policy)

Setting the login failure policySetting the login failure policypdadmin policiesmax-login-failurespoliciesmax-login-failures Login failure policy controls the maximum number of failed login attempts allowed before an account lockout penalty is imposed. Use the pdadmin policy command to set the login failure policy. Use the following syntax to set the login failure policy:policy set max-login-failures {number|unset} [-user username]Use the following syntax to display the current login failure policy setting:policy get max-login-failures [-user username]The number argument specifies the number of failed login attempts allowed before the penalty is applied. By default, the policy is enabled with a setting of 10 login attempts. For example:pdadmin> policy get max-login-failures Maximum login failures: 10The unset argument disables the policy. With this setting, the policy contains no value and the policy is not checked or enforced.You can apply max-login-failures policy to a specific user or apply the policy globally to all users listed in the user registry. Example global setting:pdadmin> policy set max-login-failures 3 Example user-specific setting:pdadmin> policy set max-login-failures 5 -user lauraThe account lockout penalty value is specified by the disable-time-interval policy. See Setting the account disable time interval.Login failure policy ("three strikes" login policy)

Setting the login failure policy

About this task

Login failure policy controls the maximum number of failed login attempts allowed before an account lockout penalty is imposed.

Procedure

Use the pdadmin policy command to set the login failure policy. Use the following syntax to set the login failure policy:

policy set max-login-failures {number|unset} [-user username]

Use the following syntax to display the current login failure policy setting:

policy get max-login-failures [-user username]

The number argument specifies the number of failed login attempts allowed before the penalty is applied. By default, the policy is enabled with a setting of 10 login attempts. For example:

pdadmin> policy get max-login-failures
Maximum login failures: 10

The unset argument disables the policy. With this setting, the policy contains no value and the policy is not checked or enforced.

You can apply max-login-failures policy to a specific user or apply the policy globally to all users listed in the user registry.

Example

Example global setting:

pdadmin> policy set max-login-failures 3

Example user-specific setting:

pdadmin> policy set max-login-failures 5 -user laura

The account lockout penalty value is specified by the disable-time-interval policy. See Setting the account disable time interval.

Parent topic: Login failure policy ("three strikes" login policy)

Setting the account disable time intervalSetting the account disable time intervalpdadmin policiesdisable-time-intervalpoliciesdisable-time-interval Login failure policy controls the maximum number of failed login attempts allowed before an account lockout penalty is imposed. Use the pdadmin policy command to set the penalty time interval for the login failure policy. Use the following syntax to set the penalty time interval:policy set disable-time-interval {number|unset|disable} [-user username]Use the following syntax to display the current penalty time interval setting:policy get disable-time-interval [-user username]The number argument specifies the number of seconds that an account is locked out if the maximum number of failed login attempts is reached or exceeded. By default, the lockout time interval is 180 seconds. For example:pdadmin> policy get disable-time-interval Disable time interval: 180The unset argument disables the policy. With this setting, the policy contains no value and the policy is not checked or enforced.The disable argument permanently locks the user out of the account after reaching or exceeding the login attempt limit and the LDAP account valid attribute for this user is set to "no". An administrator can re-enable the account by using the Web Portal Manager or pdadmin utility.Setting the disable-time-interval to "disable" results in additional administration overhead, because the account must be manually re-enabled by the administrator. After the account is re-enabled, the updated account valid LDAP attribute information might not be immediately available. This situation can occur when using WebSEAL with an LDAP environment that includes replicated LDAP servers. In this case, the updated information is propagated to the LDAP replicas according to the LDAP configuration settings that specify the time interval for performing updates. You can apply disable-time-interval policy to a specific user or apply the policy globally to all users listed in the user registry. Example global setting:pdadmin> policy set disable-time-interval 60 Example user-specific setting:pdadmin> policy set disable-time-interval disable -user lauraThe late-lockout-notification stanza entry in the [server] stanza of the WebSEAL configuration file specifies whether this account lockout notification occurs when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit. See Configuring the account disable notification response.Login failure policy ("three strikes" login policy)

Setting the account disable time interval

About this task

Login failure policy controls the maximum number of failed login attempts allowed before an account lockout penalty is imposed.

Procedure

Use the pdadmin policy command to set the penalty time interval for the login failure policy. Use the following syntax to set the penalty time interval:

policy set disable-time-interval {number|unset|disable} [-user username]

Use the following syntax to display the current penalty time interval setting:

policy get disable-time-interval [-user username]

The number argument specifies the number of seconds that an account is locked out if the maximum number of failed login attempts is reached or exceeded. By default, the lockout time interval is 180 seconds. For example:

pdadmin> policy get disable-time-interval
Disable time interval: 180

The unset argument disables the policy. With this setting, the policy contains no value and the policy is not checked or enforced.

The disable argument permanently locks the user out of the account after reaching or exceeding the login attempt limit and the LDAP account valid attribute for this user is set to "no". An administrator can re-enable the account by using the Web Portal Manager or pdadmin utility.

Note: Setting the disable-time-interval to "disable" results in additional administration overhead, because the account must be manually re-enabled by the administrator. After the account is re-enabled, the updated account valid LDAP attribute information might not be immediately available. This situation can occur when using WebSEAL with an LDAP environment that includes replicated LDAP servers. In this case, the updated information is propagated to the LDAP replicas according to the LDAP configuration settings that specify the time interval for performing updates.

You can apply disable-time-interval policy to a specific user or apply the policy globally to all users listed in the user registry.

Example

Example global setting:

pdadmin> policy set disable-time-interval 60

Example user-specific setting:

pdadmin> policy set disable-time-interval disable -user laura

The late-lockout-notification stanza entry in the [server] stanza of the WebSEAL configuration file specifies whether this account lockout notification occurs when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit. See Configuring the account disable notification response.

Parent topic: Login failure policy ("three strikes" login policy)

Configuring the account disable notification responseConfiguring the account disable notification responselate-lockout-notification stanza entryaccountsdisable notification responseWebSEAL returns a server response error page (acct_locked.html) that notifies the user of the penalty for reaching or exceeding the max-login-failures limit. The late-lockout-notification stanza entry in the [server] stanza of the WebSEAL configuration file specifies whether this error page is returned when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit. The action of account lockout or account disable does not remove the session cache entry of the user, but it does prevent future logins by that user until the account is unlocked.The default late-lockout-notification setting for new installations of WebSEAL is "no". Upon reaching the maximum value set by the max-login-failures policy, WebSEAL immediately sends the account disabled error page to the user. For example:[server] late-lockout-notification = noThe default setting for migrated installations of WebSEAL is "yes". Upon reaching the maximum value set by the max-login-failures policy, WebSEAL returns another login prompt to the user. WebSEAL does not send the account disabled error page to the user until the next login attempt. This setting represents the pre-version 6.0 behavior for the max-login-failures policy. For example:[server] late-lockout-notification = yesIf the disable-time-interval policy is set to a number of seconds, the error message indicates that the account is temporarily locked out.If the disable-time-interval policy is set to "disable", the error message indicates that the account has been disabled and that an administrator is required to reset (unlock) the account.Login failure policy ("three strikes" login policy)

Configuring the account disable notification response

About this task

WebSEAL returns a server response error page (acct_locked.html) that notifies the user of the penalty for reaching or exceeding the max-login-failures limit.

The late-lockout-notification stanza entry in the [server] stanza of the WebSEAL configuration file specifies whether this error page is returned when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit.

The action of account lockout or account disable does not remove the session cache entry of the user, but it does prevent future logins by that user until the account is unlocked.

Procedure

The default late-lockout-notification setting for new installations of WebSEAL is "no". Upon reaching the maximum value set by the max-login-failures policy, WebSEAL immediately sends the account disabled error page to the user. For example:

[server]
late-lockout-notification = no

The default setting for migrated installations of WebSEAL is "yes". Upon reaching the maximum value set by the max-login-failures policy, WebSEAL returns another login prompt to the user. WebSEAL does not send the account disabled error page to the user until the next login attempt. This setting represents the pre-version 6.0 behavior for the max-login-failures policy. For example:

[server]
late-lockout-notification = yes

If the disable-time-interval policy is set to a number of seconds, the error message indicates that the account is temporarily locked out.

If the disable-time-interval policy is set to "disable", the error message indicates that the account has been disabled and that an administrator is required to reset (unlock) the account.

Parent topic: Login failure policy ("three strikes" login policy)

Login failure policy with replicated WebSEAL serversLogin failure policy with replicated WebSEAL serversWebSEALreplicated serverlogin failure policiesYou use the login failure policy to ensure that an account is locked after a specified number of failed login attempts. This policy performs as expected in a configuration involving one WebSEAL server. In a configuration involving multiple front-end WebSEAL servers with a load-balancing mechanism, the results of the policy are affected by the fact that each WebSEAL server maintains its own local count of failed login attempts by default.For example, if the max-login-failures value is set to three (3) attempts, and the client fails the first three attempts, the account on this server is locked. However, as the client continues login attempts, the load-balancing mechanism—detecting a failure to connect to the first server—redirects the request to another available replicated WebSEAL server. Now the client has three more opportunities to attempt a successful login.For "n" attempts configured on each WebSEAL server, and "m" front-end replicated WebSEAL servers, you are guaranteed an initial account lock on one server after "n" attempts. You are also guaranteed "n" x "m" total attempts to log in across all configured servers. However, after "n" attempts, it is not clear whether subsequent authentication failures are due to the lock on a particular server, or due to continuing incorrect login attempts across the remaining replicated servers.The "n" x "m" calculation provides a fixed maximum upper limit on the total number of consecutive login attempts before a complete lockout occurs. A case can be made that this number is still probably far less than the number of attempts statistically required to "break" a password.If your business security solution requires a login failure policy, you should understand the implications of a load-balanced, multiple front-end WebSEAL configuration on this policy.Login failure policy ("three strikes" login policy)Decreasing the number of possible login attemptsUse the login-failures-persistent stanza entry to decrease the upper limit on the total number of consecutive login attempts.

Login failure policy with replicated WebSEAL servers

You use the login failure policy to ensure that an account is locked after a specified number of failed login attempts. This policy performs as expected in a configuration involving one WebSEAL server. In a configuration involving multiple front-end WebSEAL servers with a load-balancing mechanism, the results of the policy are affected by the fact that each WebSEAL server maintains its own local count of failed login attempts by default.

For example, if the max-login-failures value is set to three (3) attempts, and the client fails the first three attempts, the account on this server is locked. However, as the client continues login attempts, the load-balancing mechanism—detecting a failure to connect to the first server—redirects the request to another available replicated WebSEAL server. Now the client has three more opportunities to attempt a successful login.

For "n" attempts configured on each WebSEAL server, and "m" front-end replicated WebSEAL servers, you are guaranteed an initial account lock on one server after "n" attempts. You are also guaranteed "n" x "m" total attempts to log in across all configured servers. However, after "n" attempts, it is not clear whether subsequent authentication failures are due to the lock on a particular server, or due to continuing incorrect login attempts across the remaining replicated servers.

The "n" x "m" calculation provides a fixed maximum upper limit on the total number of consecutive login attempts before a complete lockout occurs. A case can be made that this number is still probably far less than the number of attempts statistically required to "break" a password.

If your business security solution requires a login failure policy, you should understand the implications of a load-balanced, multiple front-end WebSEAL configuration on this policy.

Decreasing the number of possible login attempts
Use the login-failures-persistent stanza entry to decrease the upper limit on the total number of consecutive login attempts.

Parent topic: Login failure policy ("three strikes" login policy)

Decreasing the number of possible login attemptsDecreasing the number of possible login attemptsUse the login-failures-persistent stanza entry to decrease the upper limit on the total number of consecutive login attempts.logindecreasing attemptsnumber of possible login attemptsdecreasing number of possible login attempts The login-failures-persistent entry is located in the [ldap] stanza of the WebSEAL configuration file. This entry controls whether login failures are tracked in the local cache of the WebSEAL system or in the LDAP registry. If the failures are tracked in the registry, all replicas that share the registry share the count. This configuration reduces the maximum number of attempts to “n” instead of “n” x “m”. There is a minor performance impact as a result of enabling login-failures-persistent because a write operation to the LDAP server has to occur for each login attempt. Login failure policy with replicated WebSEAL servers

Decreasing the number of possible login attempts

Use the login-failures-persistent stanza entry to decrease the upper limit on the total number of consecutive login attempts.

About this task

The login-failures-persistent entry is located in the [ldap] stanza of the WebSEAL configuration file. This entry controls whether login failures are tracked in the local cache of the WebSEAL system or in the LDAP registry. If the failures are tracked in the registry, all replicas that share the registry share the count. This configuration reduces the maximum number of attempts to “n” instead of “n” x “m”. There is a minor performance impact as a result of enabling login-failures-persistent because a write operation to the LDAP server has to occur for each login attempt.

Parent topic: Login failure policy with replicated WebSEAL servers

Password strength policy Password strength policy Password strength policy refers to the stipulations placed on the construction of a password by password policy rules.passwordchangestrength policiesauthenticationpassword strength policiesloginpassword strength policiesThis section contains the following topics:Password processingLogin failure policy ("three strikes" login policy)Password strength policy conceptsYou can control the password strength policy.Password strength policiesSyntax for password strength policy commandsThe pdadmin policy commands, used to set password strength policy, are appropriate for use only with an LDAP type of user registry. Default password strength policy valuesValid and not valid password examplesSpecifying user and global settings

Password strength policy

Password strength policy refers to the stipulations placed on the construction of a password by password policy rules.

This section contains the following topics:

Password strength policy concepts
You can control the password strength policy.

Password strength policies

Syntax for password strength policy commands
The pdadmin policy commands, used to set password strength policy, are appropriate for use only with an LDAP type of user registry.

Default password strength policy values

Valid and not valid password examples

Specifying user and global settings

Parent topic: Password processing

Related concepts:

Login failure policy ("three strikes" login policy)

Password strength policy conceptsPassword strength policy conceptsYou can control the password strength policy.passwordstrengthpolicy conceptspoliciesconceptsSecurity Access Manager provides five pdadmin policy commands to control the password strength policy. See the Command Reference topics in the Knowledge Center for information on these pdadmin policy commands.Password strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Password strength policy concepts

You can control the password strength policy.

Security Access Manager provides five pdadmin policy commands to control the password strength policy. See the Command Reference topics in the Knowledge Center for information on these pdadmin policy commands.

Parent topic: Password strength policy

Password strength policiesPassword strength policiespdadmin policiesmax-password-repeated-charspassword-spacesmin-password-non-alphasmin-password-lengthmin-password-alphaspoliciesmax-password-repeated-charspassword-spacesmin-password-non-alphasmin-password-alphasmin-password-lengthmax-password-repeated-chars policypassword-spaces policymin-password-non-alphas policymin-password-alphas policymin-password-length policyThe five password strength policies implemented through the pdadmin policy command include: Minimum password length (min-password-length)Minimum alphabetic characters (min-password-alphas)Minimum non-alphabetic characters (min-password-non-alphas)Maximum repeated characters (max-password-repeated-chars)Spaces allowed (password-spaces)These policies are enforced when you create a user with the Web Portal Manager or pdadmin utility, and when a password is changed with the Web Portal Manager or pdadmin utility, or the pkmspasswd utility.Password strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Password strength policies

The five password strength policies implemented through the pdadmin policy command include:

Minimum password length (min-password-length)

Minimum alphabetic characters (min-password-alphas)

Minimum non-alphabetic characters (min-password-non-alphas)

Maximum repeated characters (max-password-repeated-chars)

Spaces allowed (password-spaces)

These policies are enforced when you create a user with the Web Portal Manager or pdadmin utility, and when a password is changed with the Web Portal Manager or pdadmin utility, or the pkmspasswd utility.

Parent topic: Password strength policy

Syntax for password strength policy commandsSyntax for password strength policy commandsThe pdadmin policy commands, used to set password strength policy, are appropriate for use only with an LDAP type of user registry. password strengthstrengthsyntaxpolicy commandsThe unset option disables this policy attribute; that is, the policy is not enforced. policy set min-password-length {number|unset} [-user username]policy get min-password-length [-user username]Manages the policy that controls the minimum length of a password. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.The default setting is 8.policy set min-password-alphas {number|unset} [-user username]policy get min-password-alphas [-user username]Manages the policy controlling the minimum number of alphabetic characters allowed in a password.As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.The default setting is 4.policy set min-password-non-alphas {number|unset} [-user username]policy get min-password-non-alphas [-user username]Manages the policy controlling the minimum number of non-alphabetic (numeric) characters allowed in a password. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.The default setting is 1.policy set max-password-repeated-chars {number|unset} [-user username]policy get max-password-repeated-chars [-user username]Manages the policy controlling the maximum number of repeated characters allowed in a password. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.The default setting is 2.policy set password-spaces {yes|no|unset} [-user username]policy get password-spaces [-user username]Manages the policy controlling whether a password can contain spaces. As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry. The default setting is unset.Password strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Syntax for password strength policy commands

The pdadmin policy commands, used to set password strength policy, are appropriate for use only with an LDAP type of user registry.

The unset option disables this policy attribute; that is, the policy is not enforced.

policy set min-password-length {number|unset} [-user username]

policy get min-password-length [-user username]

Manages the policy that controls the minimum length of a password.

As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.

The default setting is 8.

policy set min-password-alphas {number|unset} [-user username]

policy get min-password-alphas [-user username]

Manages the policy controlling the minimum number of alphabetic characters allowed in a password.

As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.

The default setting is 4.

policy set min-password-non-alphas {number|unset} [-user username]

policy get min-password-non-alphas [-user username]

Manages the policy controlling the minimum number of non-alphabetic (numeric) characters allowed in a password.

As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.

The default setting is 1.

policy set max-password-repeated-chars {number|unset} [-user username]

policy get max-password-repeated-chars [-user username]

Manages the policy controlling the maximum number of repeated characters allowed in a password.

As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.

The default setting is 2.

policy set password-spaces {yes|no|unset} [-user username]

policy get password-spaces [-user username]

Manages the policy controlling whether a password can contain spaces.

As the administrator, you can apply this policy to a specific user or apply the policy globally to all users listed in the default registry.

The default setting is unset.

Parent topic: Password strength policy

Default password strength policy valuesDefault password strength policy valuesdefaultpasswordpassword strengthstrengthpolicy valuesThe following table lists the password strength policies and the default values: PolicyDefault Valuemin-password-length 8min-password-alphas 4min-password-non-alphas 1max-password-repeated-chars 2password-spaces not setTo create the password policy behavior found in earlier releases of Security Access Manager, apply the unset option to each of the five password policies listed above.Password strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Default password strength policy values

The following table lists the password strength policies and the default values:

Policy
Default Value

min-password-length

8

min-password-alphas

4

min-password-non-alphas

1

max-password-repeated-chars

2

password-spaces

not set

To create the password policy behavior found in earlier releases of Security Access Manager, apply the unset option to each of the five password policies listed above.

Parent topic: Password strength policy

Valid and not valid password examplesValid and not valid password examplespasswordvalid examplesinvalid examplesThe following table illustrates several password examples and the results based on the default values for the five password strength policies: ExampleResultpasswordNot valid: must contain at least one non-alphabetic character.passNot valid: must contain at least 8 characters.passs1234Not valid: contains more than two repeated characters.12345678Not valid: must contain at least four alphabetic characters.password3Valid.Password strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Valid and not valid password examples

The following table illustrates several password examples and the results based on the default values for the five password strength policies:

Example
Result

password

Not valid: must contain at least one non-alphabetic character.

pass

Not valid: must contain at least 8 characters.

passs1234

Not valid: contains more than two repeated characters.

12345678

Not valid: must contain at least four alphabetic characters.

password3

Valid.

Parent topic: Password strength policy

Specifying user and global settings Specifying user and global settings user settingsglobal settings The pdadmin policy commands can be set for a specific user (with the - user option) or globally (by not using the - user option). Any user-specific setting overrides a global setting for the policy. You can also disable a policy (with the unset argument). The policy contains no value and the policy is not checked or enforced. A global minimum password length policy of 8 characters is created. As an exception to this policy, user matt is given a minimum password length policy of 4 characters.pdadmin> policy set min-password-length 8 pdadmin> policy set min-password-length 4 -user matt pdadmin> policy get min-password-length Minimum password length: 8 pdadmin> policy get min-password-length -user matt Minimum password length: 4***The specific minimum password length policy for user matt is unset. User matt is now governed by the global minimum password length policy of 8 characters.pdadmin> policy set min-password-length unset -user matt pdadmin> policy get min-password-length -user matt Minimum password length: 8***The global minimum password length policy is unset. All users, including user matt, now have no minimum password length policy.pdadmin> policy set min-password-length unset pdadmin> policy get min-password-length Minimum password length: unsetPassword strength policyPassword strength policy refers to the stipulations placed on the construction of a password by password policy rules.

Specifying user and global settings

About this task

The pdadmin policy commands can be set for a specific user (with the - user option) or globally (by not using the - user option). Any user-specific setting overrides a global setting for the policy.

You can also disable a policy (with the unset argument). The policy contains no value and the policy is not checked or enforced.

Example

A global minimum password length policy of 8 characters is created. As an exception to this policy, user matt is given a minimum password length policy of 4 characters.

pdadmin> policy set min-password-length 8
pdadmin> policy set min-password-length 4 -user matt
pdadmin> policy get min-password-length
Minimum password length: 8
pdadmin> policy get min-password-length -user matt
Minimum password length: 4

***

The specific minimum password length policy for user matt is unset. User matt is now governed by the global minimum password length policy of 8 characters.

pdadmin> policy set min-password-length unset -user matt
pdadmin> policy get min-password-length -user matt
Minimum password length: 8

***

The global minimum password length policy is unset. All users, including user matt, now have no minimum password length policy.

pdadmin> policy set min-password-length unset
pdadmin> policy get min-password-length
Minimum password length: unset

Parent topic: Password strength policy

Credential processingCredential processingcredential processingThis chapter discusses features that affect processing of the WebSEAL user credential.Topic Index:AuthenticationExtended attributes for credentialsCredential refresh

Credential processing

This chapter discusses features that affect processing of the WebSEAL user credential.

Topic Index:

Extended attributes for credentials

Credential refresh

Parent topic: Authentication

Extended attributes for credentialsExtended attributes for credentialsLDAP data in HTTP headerscredentialsextended attributes (tag/value)entitlements serviceextended attributescredentialsentitlements serviceentitlements servicecredentialscredential attribute entitlements serviceThis section contains the following topics:Credential processingCredential refreshMechanisms for adding registry attributes to a credentialYou can configure an external service to add attributes to a user credential. Configure a registry attribute entitlement serviceJunction handling of extended credential attributes

Extended attributes for credentials

This section contains the following topics:

Mechanisms for adding registry attributes to a credential
You can configure an external service to add attributes to a user credential.

Configure a registry attribute entitlement service

Junction handling of extended credential attributes

Parent topic: Credential processing

Related concepts:

Credential refresh

Mechanisms for adding registry attributes to a credentialMechanisms for adding registry attributes to a credentialYou can configure an external service to add attributes to a user credential. registry attributesaddingmechanismentitlement serviceThe WebSEAL authentication process accesses the Security Access Manager user registry and builds a credential for the user. The credential contains user information that is needed to make access decisions such as the user name and the list of groups to which the user belongs.WebSEAL supports several different mechanisms (services) that allow administrators and application developers to extend the authentication process. When WebSEAL conducts the authentication process, it checks to see if any external services have been implemented and configured. When they have, WebSEAL calls those services. The services can do their own processing to build a list of extended attributes about the user identity. These extended attributes are added to the user credential.The following service is supported: Registry attribute entitlement serviceThis entitlement service is built-in to Security Access Manager by default. This service is an implementation of a class of Security Access Manager entitlement services known as credential attribute entitlement services. The registry attribute entitlement service obtains specified user information from a user registry (such as an LDAP user registry) and inserts the data into an attribute list in the user credential. This built-in registry attribute entitlement service is a generic entitlement service that can be used by many resource managers. This service takes the place of a previous method that required administrators to add "tag/value" entries to the [ldap-ext-creds-tag] stanza in the pd.conf configuration file. For configuration information, see Configure a registry attribute entitlement service. Note that Security Access Manager provides additional built-in entitlement services that can be used to add additional information. These additional services, however, obtain the additional information from sources other than user registry entries. For example, the extended attribute entitlement service obtains information from ACLs and POPs in the protected resource object space. For more information about entitlement services, see the IBM Knowledge Center.Extended attributes for credentials

Mechanisms for adding registry attributes to a credential

You can configure an external service to add attributes to a user credential.

The WebSEAL authentication process accesses the Security Access Manager user registry and builds a credential for the user. The credential contains user information that is needed to make access decisions such as the user name and the list of groups to which the user belongs.

WebSEAL supports several different mechanisms (services) that allow administrators and application developers to extend the authentication process. When WebSEAL conducts the authentication process, it checks to see if any external services have been implemented and configured. When they have, WebSEAL calls those services. The services can do their own processing to build a list of extended attributes about the user identity. These extended attributes are added to the user credential.

The following service is supported:

Registry attribute entitlement service

This entitlement service is built-in to Security Access Manager by default. This service is an implementation of a class of Security Access Manager entitlement services known as credential attribute entitlement services. The registry attribute entitlement service obtains specified user information from a user registry (such as an LDAP user registry) and inserts the data into an attribute list in the user credential. This built-in registry attribute entitlement service is a generic entitlement service that can be used by many resource managers. This service takes the place of a previous method that required administrators to add "tag/value" entries to the [ldap-ext-creds-tag] stanza in the pd.conf configuration file. For configuration information, see Configure a registry attribute entitlement service.

Note: Note that Security Access Manager provides additional built-in entitlement services that can be used to add additional information. These additional services, however, obtain the additional information from sources other than user registry entries. For example, the extended attribute entitlement service obtains information from ACLs and POPs in the protected resource object space. For more information about entitlement services, see the IBM Knowledge Center.

Parent topic: Extended attributes for credentials

Configure a registry attribute entitlement serviceConfigure a registry attribute entitlement serviceregistry attributesentitlement serviceComplete the instructions in the following sections:Extended attributes for credentialsDetermine the attributes to add to the credentialYou must determine which attributes you want added to the user credential.Specify the attributes to add to the credentialThe attributes to add to the credential are configured in several stanzas.

Configure a registry attribute entitlement service

Complete the instructions in the following sections:

Determine the attributes to add to the credential
You must determine which attributes you want added to the user credential.

Specify the attributes to add to the credential
The attributes to add to the credential are configured in several stanzas.

Parent topic: Extended attributes for credentials

Determine the attributes to add to the credentialDetermine the attributes to add to the credentialYou must determine which attributes you want added to the user credential.attributesaddingdetermination You must define each user attribute that you want to add to the user credential in a Security Access Manager configuration file. Typically, this configuration is done in the WebSEAL configuration file.Go to the Security Access Manager user registry (for example, an LDAP user registry).Make a list of the names of each user registry entry that you want the credential attributes entitlement service to extract from the registry and place into the user credential. You also need the user DN and group DN.Configure a registry attribute entitlement service

Determine the attributes to add to the credential

You must determine which attributes you want added to the user credential.

About this task

You must define each user attribute that you want to add to the user credential in a Security Access Manager configuration file. Typically, this configuration is done in the WebSEAL configuration file.

Procedure

Go to the Security Access Manager user registry (for example, an LDAP user registry).

Make a list of the names of each user registry entry that you want the credential attributes entitlement service to extract from the registry and place into the user credential. You also need the user DN and group DN.

Parent topic: Configure a registry attribute entitlement service

Specify the attributes to add to the credentialSpecify the attributes to add to the credentialThe attributes to add to the credential are configured in several stanzas. tag-valuecredential attributesattributesspecifyingaddingcredential Add this information to the WebSEAL configuration file. Review the following example entry. [TAM_CRED_ATTRS_SVC] eperson = azn_cred_registry_id group = cn=enterprise, o=tivoli [TAM_CRED_ATTRS_SVC:eperson] tagvalue_credattrs_lastname = sn tagvalue_credattrs_employeetype = employeetype tagvalue_credattrs_address = homepostaladdress tagvalue_credattrs_email = mail [TAM_CRED_ATTRS_SVC:group] tagvalue_credattrs_businesscategory = businesscategory The stanza name [TAM_CRED_ATTRS_SVC] is the Service ID. Inside this stanza are sources of attributes to be retrieved. The source names, such as eperson and group are used to identify the source location in the registry. You need to define these. The values for these sources are registry identifiers that exist in the registry. The values can be existing credential attribute names. If this is the case, the service automatically finds and uses the respective values. Configure the registry attributes for each of the sources under the service stanza in a separate stanza. The syntax of the separate stanza is the service ID library name followed by a colon (:) and then the source name. This connection is necessary because more than one service can be configured in the same file. The configuration file entries contain mappings of user registry attributes to user-defined credential attributes.For example, in an LDAP user registry, the DN for a user might be cn=joeuser, o=tivoliFor this user, the LDAP user registry entries might be:sn=Smith employeetype=bankteller homepostaladdress="3004 Mission St Santa Cruz CA 95060" mail=joeuser@bigco.comFor the group cn=enterprise,o=tivoli, the LDAP group registry entry might be:businesscategory=financeUsing these example configuration entries, the attribute list returned has the following entries:Attribute nameAttribute valuecredattrs_lastnameSmithcredattrs_employeetypebanktellercredattrs_address3004 Mission St Santa Cruz CA 95060credattrs_emailjoeuser@example.comcredattrs_businesscategoryfinanceNote that the service, source, and attributes can be multi-valued. If you specify the same attribute name as a stanza entry keyword, then the attributes retrieved will be added as a multi-valued attribute even when they come from different sources.For example, more than one entitlement service can be chained together. This enables values retrieved from one service to be used as input values for another service. Likewise, attributes can be retrieved from more than one DN in the user registry. Thus, using the example above, you could add values from multiple users (DNs) to one credattrs_businesscategory attribute, if you wanted a list of all the businesscategory entries for a group of users.For example, if you want to build an attribute called myemployeeinfo to add to the credential, and you want this attribute to contain the last name and employee type of everyone that authenticates, you could then define the following: [myID] source = azn_cred_authzn_id [myID:source] myemployeeinfo = lastname myemployeeinfo = employeetype Configure a registry attribute entitlement service

Specify the attributes to add to the credential

The attributes to add to the credential are configured in several stanzas.

About this task

Add this information to the WebSEAL configuration file.

Review the following example entry.

[TAM_CRED_ATTRS_SVC]
eperson = azn_cred_registry_id
group = cn=enterprise, o=tivoli

[TAM_CRED_ATTRS_SVC:eperson]
tagvalue_credattrs_lastname = sn
tagvalue_credattrs_employeetype = employeetype
tagvalue_credattrs_address = homepostaladdress
tagvalue_credattrs_email = mail

[TAM_CRED_ATTRS_SVC:group]
tagvalue_credattrs_businesscategory = businesscategory

The stanza name [TAM_CRED_ATTRS_SVC] is the Service ID. Inside this stanza are sources of attributes to be retrieved. The source names, such as eperson and group are used to identify the source location in the registry. You need to define these. The values for these sources are registry identifiers that exist in the registry. The values can be existing credential attribute names. If this is the case, the service automatically finds and uses the respective values.

Procedure

Configure the registry attributes for each of the sources under the service stanza in a separate stanza. The syntax of the separate stanza is the service ID library name followed by a colon (:) and then the source name. This connection is necessary because more than one service can be configured in the same file. The configuration file entries contain mappings of user registry attributes to user-defined credential attributes.

For example, in an LDAP user registry, the DN for a user might be

cn=joeuser, o=tivoli

For this user, the LDAP user registry entries might be:

sn=Smith
employeetype=bankteller
homepostaladdress="3004 Mission St Santa Cruz CA 95060"
mail=joeuser@bigco.com

For the group cn=enterprise,o=tivoli, the LDAP group registry entry might be:

businesscategory=finance

Using these example configuration entries, the attribute list returned has the following entries:

Attribute name | Attribute value
credattrs_lastname | Smith
credattrs_employeetype | bankteller
credattrs_address | 3004 Mission St Santa Cruz CA 95060
credattrs_email | joeuser@example.com
credattrs_businesscategory | finance

Note that the service, source, and attributes can be multi-valued. If you specify the same attribute name as a stanza entry keyword, then the attributes retrieved will be added as a multi-valued attribute even when they come from different sources.

For example, more than one entitlement service can be chained together. This enables values retrieved from one service to be used as input values for another service. Likewise, attributes can be retrieved from more than one DN in the user registry. Thus, using the example above, you could add values from multiple users (DNs) to one credattrs_businesscategory attribute, if you wanted a list of all the businesscategory entries for a group of users.

For example, if you want to build an attribute called myemployeeinfo to add to the credential, and you want this attribute to contain the last name and employee type of everyone that authenticates, you could then define the following:

[myID]
source = azn_cred_authzn_id

[myID:source]
myemployeeinfo = lastname
myemployeeinfo = employeetype

Parent topic: Configure a registry attribute entitlement service

Junction handling of extended credential attributesJunction handling of extended credential attributesjunctionsHTTP-Tag-Value junction attributetag-valueHTTP-Tag-Value junction attributeHTTP-Tag-Value junction attributecredentialsinserting credential information in HTTP headersextended attributesHTTP-Tag-Value (junction attribute)The user-defined credential information created in the previous section can be placed in an HTTP header of the request that is sent across a junction to a back-end server.You must configure the junction to extract extended attribute data from the credential and insert the data into the HTTP header of the request. This functionality is achieved by setting a junction extended attribute, called HTTP-Tag-Value, on the junction object in the WebSEAL protected object space.You use the pdadmin object modify set attribute command to set extended attributes on a junction object in the WebSEAL protected object space.pdadmin> object modify object_name set attribute attr_name attr_valueThe above command must be entered as one continuous command line.An extended attribute (attr_name) enables the junction to perform a specific type of functionality. The HTTP-Tag-Value extended attribute instructs the junction to extract a particular value from a user's credential and send the value to the back-end server in an HTTP header. The value of the HTTP-Tag-Value extended attribute uses the following format:credential_extended_attribute_name = http_header_nameThe credential_extended_attribute_name entry is the same as the attribute specified in the WebSEAL configuration file but without the "tagvalue_" prefix. The entry is not case-sensitive. The http_header_name entry specifies the name of the HTTP header used to deliver the data across the junction.For example (entered as one line):pdadmin> object modify /WebSEAL/WS1/junctionA set attribute HTTP-Tag-Value credattrs_lastname=surnameWhen WebSEAL processes a user request to a back-end application server, it looks for any HTTP-Tag-Value attributes configured on the junction object.In this example, the configured junction looks at the credential of the user making the request, extracts the value of the tagvalue_credattrs_lastname credential extended attribute, and places it in an HTTP header as:surname:SmithIn summary:HTTP header example descriptionDescriptionHeader textValue of HTTP-Tag-Value attribute set on the junction object:credattrs_lastname=surnameAttribute name and value as they appear in the user credential (since tagvalue_credattrs_lastname=sn):tagvalue_credattrs_lastname:SmithHTTP header name and value:surname:SmithIf the back-end application is a CGI application, the CGI specification dictates that HTTP headers are made available to CGI programs as environment variables in the form:HTTP_http_header_nameFor example:HTTP_PD_USER_SESSION_IDHTTP_surname=SmithMultiple user attribute data can be passed to the junctioned server in HTTP headers by using multiple pdadmin object modify set attribute commands to specify multiple HTTP-Tag-Value junction attributes (one attribute is specified per command).Extended attributes for credentialsHTTP-Tag-Value extended attributes must be attached directly to the junctiontagvalue_always extended attributeIf an authentication mechanism supports the addition of attributes to the credential, you can use the tagvalue_always attribute to define which attributes are always inserted into the HTTP stream. Examples of such authentication mechanisms include EAI and OAuth authentication.

Junction handling of extended credential attributes

The user-defined credential information created in the previous section can be placed in an HTTP header of the request that is sent across a junction to a back-end server.

You must configure the junction to extract extended attribute data from the credential and insert the data into the HTTP header of the request. This functionality is achieved by setting a junction extended attribute, called HTTP-Tag-Value, on the junction object in the WebSEAL protected object space.

You use the pdadmin object modify set attribute command to set extended attributes on a junction object in the WebSEAL protected object space.

pdadmin> object modify object_name set attribute attr_name attr_value

Note: The above command must be entered as one continuous command line.

An extended attribute (attr_name) enables the junction to perform a specific type of functionality. The HTTP-Tag-Value extended attribute instructs the junction to extract a particular value from a user's credential and send the value to the back-end server in an HTTP header. The value of the HTTP-Tag-Value extended attribute uses the following format:

credential_extended_attribute_name = http_header_name

The credential_extended_attribute_name entry is the same as the attribute specified in the WebSEAL configuration file but without the "tagvalue_" prefix. The entry is not case-sensitive. The http_header_name entry specifies the name of the HTTP header used to deliver the data across the junction.

For example (entered as one line):

pdadmin> object modify /WebSEAL/WS1/junctionA set attribute
HTTP-Tag-Value credattrs_lastname=surname

When WebSEAL processes a user request to a back-end application server, it looks for any HTTP-Tag-Value attributes configured on the junction object.

In this example, the configured junction looks at the credential of the user making the request, extracts the value of the tagvalue_credattrs_lastname credential extended attribute, and places it in an HTTP header as:

surname:Smith

In summary:

Table 46. HTTP header example description

Description
Header text

Value of

HTTP-Tag-Value

attribute

set on the junction object:

credattrs_lastname=surname

Attribute name and value as they

appear in the user credential

(since

tagvalue_credattrs_lastname=sn

):

tagvalue_credattrs_lastname:Smith

HTTP header name and value:

surname:Smith

If the back-end application is a CGI application, the CGI specification dictates that HTTP headers are made available to CGI programs as environment variables in the form:

HTTP_http_header_name

For example:

HTTP_surname=Smith

Multiple user attribute data can be passed to the junctioned server in HTTP headers by using multiple pdadmin object modify set attribute commands to specify multiple HTTP-Tag-Value junction attributes (one attribute is specified per command).

HTTP-Tag-Value extended attributes must be attached directly to the junction

tagvalue_always extended attribute
If an authentication mechanism supports the addition of attributes to the credential, you can use the tagvalue_always attribute to define which attributes are always inserted into the HTTP stream. Examples of such authentication mechanisms include EAI and OAuth authentication.

Parent topic: Extended attributes for credentials

HTTP-Tag-Value extended attributes must be attached directly to the junctionHTTP-Tag-Value extended attributes must be attached directly to the junctionHTTP-Tag-Value attributejunctiondirect attachmentWhen an evaluation is performed to determine what credential attributes should be passed for a particular object below a junction point, the evaluation is performed not for the child object, but for the junction object. For example, if you create HTTP-Tag-Value extended attributes for a junction object named /WebSEAL/myinstance/jct1and you also create HTTP-Tag-Value extended attributes for a child object of the junction named /WebSEAL/myinstance/jct1/childthen when a client accesses /WebSEAL/myinstance/jct1/child only the attributes attached to /WebSEAL/myinstance/jct1 will be used; the child attributes will be ignored. Therefore, the HTTP-Tag-Value extended attributes must be attached directly to the junction. It is important to understand that this is due not to inheritance but to the fact that WebSEAL determines the junction object associated with a child and finds the HTTP-Tag-Value attributes for the junction object itself. In fact, while inheritance of extended attributes was introduced in version 6.0, the processing of the HTTP-Tag-Value attributes does not use this inheritance. So, for example, if you create a junction at /WebSEAL/myinstance/jct1 with no HTTP-Tag-Value attributes attached to it, and instead attach the attributes to the parent at /WebSEAL/myinstance/then those attributes will not be used for jct1 or any of its children. You must attach the HTTP-Tag-Value extended attributes directly to /WebSEAL/myinstance/jct1.Junction handling of extended credential attributes

HTTP-Tag-Value extended attributes must be attached directly to the junction

When an evaluation is performed to determine what credential attributes should be passed for a particular object below a junction point, the evaluation is performed not for the child object, but for the junction object. For example, if you create HTTP-Tag-Value extended attributes for a junction object named

/WebSEAL/myinstance/jct1

and you also create HTTP-Tag-Value extended attributes for a child object of the junction named

/WebSEAL/myinstance/jct1/child

then when a client accesses /WebSEAL/myinstance/jct1/child only the attributes attached to /WebSEAL/myinstance/jct1 will be used; the child attributes will be ignored. Therefore, the HTTP-Tag-Value extended attributes must be attached directly to the junction.

It is important to understand that this is due not to inheritance but to the fact that WebSEAL determines the junction object associated with a child and finds the HTTP-Tag-Value attributes for the junction object itself. In fact, while inheritance of extended attributes was introduced in version 6.0, the processing of the HTTP-Tag-Value attributes does not use this inheritance. So, for example, if you create a junction at

/WebSEAL/myinstance/jct1

with no HTTP-Tag-Value attributes attached to it, and instead attach the attributes to the parent at

/WebSEAL/myinstance/

then those attributes will not be used for jct1 or any of its children. You must attach the HTTP-Tag-Value extended attributes directly to /WebSEAL/myinstance/jct1.

Parent topic: Junction handling of extended credential attributes

tagvalue_always extended attributeIf an authentication mechanism supports the addition of attributes to the credential, you can use the tagvalue_always attribute to define which attributes are always inserted into the HTTP stream. Examples of such authentication mechanisms include EAI and OAuth authentication.tagvalue_always attributeAdd the extended attribute tagvalue_always to the credential to define the attributes that are always included in the HTTP stream. The format of this attribute is:<attribute name>[:<header name>],...The attribute name and header name cannot contain a comma (,) or colon (:) character. These characters are reserved by the system. The attribute name field corresponds to the name of the attribute that is to be inserted into the HTTP stream. The optional header name field contains the name of the HTTP header that holds the attribute value. The attribute name is used as the name of the HTTP header if no header name field is specified. Multiple attributes can be specified, with each attribute delineated by a comma. Attributes with multiple values are inserted into a single header with each attribute value separated by a comma.Junction handling of extended credential attributes

tagvalue_always extended attribute

If an authentication mechanism supports the addition of attributes to the credential, you can use the tagvalue_always attribute to define which attributes are always inserted into the HTTP stream. Examples of such authentication mechanisms include EAI and OAuth authentication.

Add the extended attribute tagvalue_always to the credential to define the attributes that are always included in the HTTP stream. The format of this attribute is:

<attribute name>[:<header name>],...

Note: The attribute name and header name cannot contain a comma (,) or colon (:) character. These characters are reserved by the system.

The attribute name field corresponds to the name of the attribute that is to be inserted into the HTTP stream. The optional header name field contains the name of the HTTP header that holds the attribute value. The attribute name is used as the name of the HTTP header if no header name field is specified. Multiple attributes can be specified, with each attribute delineated by a comma. Attributes with multiple values are inserted into a single header with each attribute value separated by a comma.

Parent topic: Junction handling of extended credential attributes

Credential refreshCredential refreshcredentialscredential refreshcredential refreshThis section contains the following topics:Credential processingExtended attributes for credentialsCredential refresh conceptsConfigure credential refreshCredential refresh usage

Credential refresh

This section contains the following topics:

Credential refresh concepts

Configure credential refresh

Credential refresh usage

Parent topic: Credential processing

Related concepts:

Extended attributes for credentials

Credential refresh conceptsCredential refresh conceptscredential refreshoverviewconceptsThis section contains the following topics:Credential refreshCredential refresh overviewYou can configure the credential refresh feature in WebSEAL.Credential refresh rulesRefresh of cached credential informationSome user registries maintain cached information. Cached data is kept for a specific amount of time, and is then discarded. After the cached data has expired, it is not reloaded into the cache until the next time the user registry is accessed. Therefore, when changes are made to user registry data, the data is not immediately cached in memory. Likewise, when using a replicated LDAP user registry, the updates to the replicated registries do not occur immediately.Configuration file syntax and usageDefault settings for preserve and refreshLimitations

Credential refresh concepts

This section contains the following topics:

Credential refresh overview
You can configure the credential refresh feature in WebSEAL.

Credential refresh rules

Refresh of cached credential information
Some user registries maintain cached information. Cached data is kept for a specific amount of time, and is then discarded. After the cached data has expired, it is not reloaded into the cache until the next time the user registry is accessed. Therefore, when changes are made to user registry data, the data is not immediately cached in memory. Likewise, when using a replicated LDAP user registry, the updates to the replicated registries do not occur immediately.

Configuration file syntax and usage

Default settings for preserve and refresh

Limitations

Parent topic: Credential refresh

Credential refresh overview Credential refresh overview You can configure the credential refresh feature in WebSEAL.credential refreshoverviewWhen a user authenticates to WebSEAL, the authentication process accesses the Security Access Manager user registry and builds a credential for the user. The credential contains information about the user that is needed by Security Access Manager to decide whether to grant the user access to the requested resource. An example of credential information is a list of groups to which the user belongs.During a user session, changes in user information can take place. For example, the user might be added to a new group. When this occurs, there might be a need to update or refresh the contents of the user credential, to reflect the new user information. WebSEAL provides a mechanism to enable a credential refresh without requiring the user to log out and then authenticate again.You can control how the credential refresh feature occurs. WebSEAL provides configuration settings that enable you to specify credential attributes to refresh (update) and credential attributes to preserve (retain). This ability enables you to have precise control over how user credentials are manipulated during a user session.Use of the credential refresh configuration settings can be important when the authentication process on your WebSEAL server includes call outs to mechanisms that provide additional or extended information about a user. These mechanisms include:Credential attribute entitlement service. This service is built into Security Access Manager by default.For more information on the credential attribute services listed above, see Mechanisms for adding registry attributes to a credentialYou can configure an external service to add attributes to a user credential. .When credential refresh occurs, the default credential attribute entitlement services is run.The credential refresh configuration settings enable you to preserve attributes obtained during the initial use of an entitlement service. For example, if an attribute contained a timestamp for the start of the user session, you might want to preserve the timestamp even though the credential was refreshed.The credential refresh configuration settings also enable you to preserve attributes obtained from a credential extended attribute authentication module. Because custom authentication modules are not run again during the rebuilding of the credential, you use the configuration file settings to specify attributes to be added to the new credential.Credential refresh concepts

Credential refresh overview

You can configure the credential refresh feature in WebSEAL.

When a user authenticates to WebSEAL, the authentication process accesses the Security Access Manager user registry and builds a credential for the user. The credential contains information about the user that is needed by Security Access Manager to decide whether to grant the user access to the requested resource. An example of credential information is a list of groups to which the user belongs.

During a user session, changes in user information can take place. For example, the user might be added to a new group. When this occurs, there might be a need to update or refresh the contents of the user credential, to reflect the new user information. WebSEAL provides a mechanism to enable a credential refresh without requiring the user to log out and then authenticate again.

You can control how the credential refresh feature occurs. WebSEAL provides configuration settings that enable you to specify credential attributes to refresh (update) and credential attributes to preserve (retain). This ability enables you to have precise control over how user credentials are manipulated during a user session.

Use of the credential refresh configuration settings can be important when the authentication process on your WebSEAL server includes call outs to mechanisms that provide additional or extended information about a user. These mechanisms include:

Credential attribute entitlement service.

This service is built into Security Access Manager by default.

For more information on the credential attribute services listed above, see Mechanisms for adding registry attributes to a credential.

When credential refresh occurs, the default credential attribute entitlement services is run.

The credential refresh configuration settings enable you to preserve attributes obtained during the initial use of an entitlement service. For example, if an attribute contained a timestamp for the start of the user session, you might want to preserve the timestamp even though the credential was refreshed.

The credential refresh configuration settings also enable you to preserve attributes obtained from a credential extended attribute authentication module. Because custom authentication modules are not run again during the rebuilding of the credential, you use the configuration file settings to specify attributes to be added to the new credential.

Parent topic: Credential refresh concepts

Credential refresh rulesCredential refresh rulescredential refreshrulesrulescredential refreshCredential refresh involves the generation of a new credential for user identity, followed by an evaluation of the contents of the new credential against the contents of the old credential that was obtained during initial user authentication. The contents of the two credentials are combined into a merged credential according to the following rules:When an attribute occurs in the new credential but not the old credential, it is added to the merged credential.The following attributes are added to the merged credential based only on their value in the old credential. These attributes are used by the authorization API. They are not changed by values in the new credential. AZN_CRED_AUTHNMECH_INFO AZN_CRED_BROWSER_INFO AZN_CRED_IP_ADDRESS AZN_CRED_PRINCIPAL_NAME AZN_CRED_AUTH_METHOD AZN_CRED_USER_INFO AZN_CRED_QOP_INFOFor each attribute in the old credential for which there is a corresponding attribute in the new credential, the following rules apply: When there is an entry in the configuration file that matches it, the attribute in the merged credential is preserved or refreshed according to the value of the entry in the configuration file.When there is not an entry in the configuration file that matches it, the attribute in the merged credential is assigned the value from the new credential.For each attribute in the old credential for which there is not a corresponding attribute in the new credential, the following rules apply: When there is a configuration file entry for the attribute specifying refresh, the attribute is not added to the merged credential.When there is a configuration file entry for the attribute specifying preserve, the attribute is added to the merged credential.When the configuration file does not contain an entry for the attribute, the attribute is not added to the merged credential.Credential refresh concepts

Credential refresh rules

Credential refresh involves the generation of a new credential for user identity, followed by an evaluation of the contents of the new credential against the contents of the old credential that was obtained during initial user authentication. The contents of the two credentials are combined into a merged credential according to the following rules:

When an attribute occurs in the new credential but not the old credential, it is added to the merged credential.

The following attributes are added to the merged credential based only on their value in the old credential. These attributes are used by the authorization API. They are not changed by values in the new credential.

AZN_CRED_AUTHNMECH_INFO
AZN_CRED_BROWSER_INFO
AZN_CRED_IP_ADDRESS
AZN_CRED_PRINCIPAL_NAME
AZN_CRED_AUTH_METHOD
AZN_CRED_USER_INFO
AZN_CRED_QOP_INFO

For each attribute in the old credential for which there is a corresponding attribute in the new credential, the following rules apply:

When there is an entry in the configuration file that matches it, the attribute in the merged credential is preserved or refreshed according to the value of the entry in the configuration file.

When there is not an entry in the configuration file that matches it, the attribute in the merged credential is assigned the value from the new credential.

For each attribute in the old credential for which there is not a corresponding attribute in the new credential, the following rules apply:

When there is a configuration file entry for the attribute specifying refresh, the attribute is not added to the merged credential.

When there is a configuration file entry for the attribute specifying preserve, the attribute is added to the merged credential.

When the configuration file does not contain an entry for the attribute, the attribute is not added to the merged credential.

Parent topic: Credential refresh concepts

Refresh of cached credential informationRefresh of cached credential informationSome user registries maintain cached information. Cached data is kept for a specific amount of time, and is then discarded. After the cached data has expired, it is not reloaded into the cache until the next time the user registry is accessed. Therefore, when changes are made to user registry data, the data is not immediately cached in memory. Likewise, when using a replicated LDAP user registry, the updates to the replicated registries do not occur immediately.credential informationcache refreshcacherefreshcredential informationThe default lifetime of data in the WebSEAL user cache is 30 seconds. This lifetime begins when the data first enters the cache, such as when a user first authenticates, or when the cached data has expired and WebSEAL contacts the registry to update the data. WebSEAL contacts the registry to update the data during a credential refresh event. The cached information is valid for 30 seconds after it is first obtained from the registry. After 30 seconds, any credential refresh operations go directly to the user registry. The access to the user registry also causes the user data to be reloaded into the cache.The following example shows the algorithm for updating the user cache:The user authenticates at time auth_time.The user is added to a group at time auth_time + 120 secondsThe user's credential is refreshed at time auth_time + 130 seconds Because the user cache data expired at time auth_time + 30 seconds, the new group membership will be added to the user's credential. User is then added to another group at time auth_time + 135 secondsUser's credential is refreshed at time auth_time + 140 secondsWhen the user credential is refreshed at auth_time + 140 seconds, it does not pick up the new group membership. This is because the user credential is built off cached user data when the cached user data is considered valid (has not expired). Because the user cache data was updated at time auth_time + 130 seconds, it is not scheduled to be updated until auth_time + 160 seconds. Therefore, the administrator must wait until time auth_time + 160 seconds to run the refresh command. At that time, the user credential will pick up the new group memberships.Credential refresh concepts

Refresh of cached credential information

Some user registries maintain cached information. Cached data is kept for a specific amount of time, and is then discarded. After the cached data has expired, it is not reloaded into the cache until the next time the user registry is accessed. Therefore, when changes are made to user registry data, the data is not immediately cached in memory. Likewise, when using a replicated LDAP user registry, the updates to the replicated registries do not occur immediately.

The default lifetime of data in the WebSEAL user cache is 30 seconds. This lifetime begins when the data first enters the cache, such as when a user first authenticates, or when the cached data has expired and WebSEAL contacts the registry to update the data. WebSEAL contacts the registry to update the data during a credential refresh event. The cached information is valid for 30 seconds after it is first obtained from the registry. After 30 seconds, any credential refresh operations go directly to the user registry. The access to the user registry also causes the user data to be reloaded into the cache.

The following example shows the algorithm for updating the user cache:

The user authenticates at time auth_time.

The user is added to a group at time auth_time + 120 seconds

The user's credential is refreshed at time auth_time + 130 seconds

Because the user cache data expired at time auth_time + 30 seconds, the new group membership will be added to the user's credential.

User is then added to another group at time auth_time + 135 seconds

User's credential is refreshed at time auth_time + 140 seconds

When the user credential is refreshed at auth_time + 140 seconds, it does not pick up the new group membership. This is because the user credential is built off cached user data when the cached user data is considered valid (has not expired). Because the user cache data was updated at time auth_time + 130 seconds, it is not scheduled to be updated until auth_time + 160 seconds. Therefore, the administrator must wait until time auth_time + 160 seconds to run the refresh command. At that time, the user credential will pick up the new group memberships.

Parent topic: Credential refresh concepts

Configuration file syntax and usageConfiguration file syntax and usagecredential refreshconfiguration syntaxcredential-refresh-attributes stanzaThe credential refresh behavior is controlled by entries in the [credential-refresh-attributes] stanza in the WebSEAL configuration file. The format is:attribute_name_pattern = {preserve|refresh}The attribute name pattern is used to select a given set of attributes. Wildcard matching is supported.A particular attribute can possibly be matched by many different wildcard patterns. Therefore, the order of elements in the configuration file is important. The firs pattern that matches a given attribute is the only pattern that applies to that attribute.Attribute names in attribute_name_pattern should not be case-sensitive because attribute names in credentials are not case-sensitive.Example – Preserve all of the tag value attributes added by an extended attribute external authentication C API module:[credential-refresh-attributes] tagvalue_* = preserveExample – Update the tagvalue_last_refresh_time attribute with the value from the new credential, but preserve all other attributes that begin with tagvalue_: [credential-refresh-attributes] tagvalue_last_refresh_time = refresh tagvalue_* = preserveNote that the ordering of attributes in the file is important. In the following example, tagvalue_last_refresh_time will not be refreshed because it is first matched by the tagvalue_* entry, which is set to preserve:[credential-refresh-attributes] tagvalue_* = preserve tagvalue_last_refresh_time = refreshAvoid preserving attributes that begin with the letters AZN_. Such attributes are typically used internally by the authorization API during authorization decisions. See information about obtaining attribute lists from credentials in the IBM Knowledge Center.Credential refresh concepts

Configuration file syntax and usage

The credential refresh behavior is controlled by entries in the [credential-refresh-attributes] stanza in the WebSEAL configuration file. The format is:

attribute_name_pattern = {preserve|refresh}

The attribute name pattern is used to select a given set of attributes. Wildcard matching is supported.

A particular attribute can possibly be matched by many different wildcard patterns. Therefore, the order of elements in the configuration file is important. The firs pattern that matches a given attribute is the only pattern that applies to that attribute.

Attribute names in attribute_name_pattern should not be case-sensitive because attribute names in credentials are not case-sensitive.

Example – Preserve all of the tag value attributes added by an extended attribute external authentication C API module:

[credential-refresh-attributes]
tagvalue_* = preserve

Example – Update the tagvalue_last_refresh_time attribute with the value from the new credential, but preserve all other attributes that begin with tagvalue_:

[credential-refresh-attributes]
tagvalue_last_refresh_time = refresh
tagvalue_* = preserve

Note that the ordering of attributes in the file is important. In the following example, tagvalue_last_refresh_time will not be refreshed because it is first matched by the tagvalue_* entry, which is set to preserve:

[credential-refresh-attributes]
tagvalue_* = preserve
tagvalue_last_refresh_time = refresh

Avoid preserving attributes that begin with the letters AZN_. Such attributes are typically used internally by the authorization API during authorization decisions. See information about obtaining attribute lists from credentials in the IBM Knowledge Center.

Parent topic: Credential refresh concepts

Default settings for preserve and refreshDefault settings for preserve and refreshcredential refreshpreserverefreshdefault settingsThe default settings in the WebSEAL configuration file are: [credential-refresh-attributes] authentication_level = preserve tagvalue_* = preserveThese settings result in the following behavior: The user authentication level is preserved when credentials are refreshed. During a user session, the user authentication level can change when authentication strength policy (step-authentication) is applied. In most cases, you want to preserve the modified authentication level during a credential refresh. If you do not want to preserve the authentication level, change the configuration file entry: authentication_level = refreshThe tagvalue_* entry preserves all credential attributes whose name begins with the characters tagvalue_. Attributes with the prefix tagvalue_ are typically supplied by external authentication C API services that want to add user information to the credential. The prefix is needed to ensure that the credentials are included when WebSEAL inserts credential data into an HTTP header to send across a junction.Credential refresh concepts

Default settings for preserve and refresh

The default settings in the WebSEAL configuration file are:

[credential-refresh-attributes]
authentication_level = preserve
tagvalue_* = preserve

These settings result in the following behavior:

The user authentication level is preserved when credentials are refreshed. During a user session, the user authentication level can change when authentication strength policy (step-authentication) is applied. In most cases, you want to preserve the modified authentication level during a credential refresh.

If you do not want to preserve the authentication level, change the configuration file entry:

authentication_level = refresh

The tagvalue_* entry preserves all credential attributes whose name begins with the characters tagvalue_.

Attributes with the prefix tagvalue_ are typically supplied by external authentication C API services that want to add user information to the credential. The prefix is needed to ensure that the credentials are included when WebSEAL inserts credential data into an HTTP header to send across a junction.

Parent topic: Credential refresh concepts

Limitationscredential refreshlimitationslimitationscredential refreshIt is not possible to avoid calling the credentials attribute entitlement service during credential refresh. When you have an attribute that should be set only once (during initial authentication) use an extended attribute external authentication C API module to set the attribute.Credential refresh concepts

Limitations

It is not possible to avoid calling the credentials attribute entitlement service during credential refresh. When you have an attribute that should be set only once (during initial authentication) use an extended attribute external authentication C API module to set the attribute.

Parent topic: Credential refresh concepts

Configure credential refreshConfigure credential refreshcredential refreshconfigurationTo configure credential refresh, complete the following steps:Credential refresh1. Specifying attributes to preserve or refresh2. Enabling user session IDs3. Enabling placement of server name into junction headerYou can configure WebSEAL to add the server name in the junction header.

Configure credential refresh

To configure credential refresh, complete the following steps:

1. Specifying attributes to preserve or refresh

2. Enabling user session IDs

3. Enabling placement of server name into junction header
You can configure WebSEAL to add the server name in the junction header.

Parent topic: Credential refresh

1. Specifying attributes to preserve or refresh1. Specifying attributes to preserve or refreshcredential refreshspecify attributes to preserve or refreshspecifying attributesStop the WebSEAL server.Edit the WebSEAL configuration file.Add entries for attributes to preserve. For example:[credential-refresh-attributes] my_cred_attribute1 = preserve my_cred_attribute2 = preserveAdd entries to refresh:[credential-refresh-attributes] my_cred_attribute3 = refresh my_cred_attribute4 = refreshWhen appropriate, use the order of the entries to handle both specific entries and groups of entries. For example, to preserve the attribute special_cred_attr1, but refresh all other attributes with the naming construct of special_cred_attr*, add the following entries:[credential-refresh-attributes] special_cred_attr1 = preserve special_cred_attr* = refreshConfigure credential refresh

1. Specifying attributes to preserve or refresh

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file.

Add entries for attributes to preserve. For example:

[credential-refresh-attributes]
my_cred_attribute1 = preserve
my_cred_attribute2 = preserve

Add entries to refresh:

[credential-refresh-attributes]
my_cred_attribute3 = refresh
my_cred_attribute4 = refresh

When appropriate, use the order of the entries to handle both specific entries and groups of entries. For example, to preserve the attribute special_cred_attr1, but refresh all other attributes with the naming construct of special_cred_attr*, add the following entries:

[credential-refresh-attributes]
special_cred_attr1 = preserve
special_cred_attr* = refresh

Parent topic: Configure credential refresh

2. Enabling user session IDs2. Enabling user session IDsuser sessionsenabling IDs Ensure that user session IDs are enabled for the WebSEAL instance. The credential refresh administration command does not work when user session IDs are not enabled. user-session-ids stanza entry[session] user-session-ids = yesConfigure credential refresh

2. Enabling user session IDs

About this task

Ensure that user session IDs are enabled for the WebSEAL instance. The credential refresh administration command does not work when user session IDs are not enabled.

[session]
user-session-ids = yes

Parent topic: Configure credential refresh

3. Enabling placement of server name into junction header3. Enabling placement of server name into junction headerConfigure WebSEAL to add the server name in the junction headerYou can configure WebSEAL to add the server name in the junction header. header-data stanza entry (header-names stanza)credential refreshheader-data stanza entry (header-names stanza)Use the [header-names] <header-data> stanza entry to configure WebSEAL to add a header with the URI-encoded authorization API administration server name to requests for junctioned applications. If you do not configure this entry, WebSEAL does not add any headers to the request.The <header-data> entry has the following format:[header-names] <header-data> = <header-name>where:<header-data>The type of data that WebSEAL adds to the <header-name> header of the request.Use the value server-name to add the Security Access Manager authorization server name for the WebSEAL server.<header-name>The name of the header that holds the data.The following value is set in the default WebSEAL configuration file.[header-names] server-name = iv_server_nameThis setting adds a header that is called iv_server_name to pass the name of the server to junctioned applications. For this example, if the WebSEAL instance is default-webseald-diamond.subnet1.ibm.com, WebSEAL passes the following header to the junction:iv_server_name:default-webseald-diamond.subnet1.ibm.comTypically, the default value iv_server_name is used. However, you can replace it with any valid string. Valid strings are limited to the following characters: A-Z, a-z, 0–9, hyphen ( - ), or underscore ( _ ).Ensure that the <header-data> stanza entry is set with a <header-data> value of server-name in the configuration file for the WebSEAL instance. For example:[header-names] server-name = iv_server_nameRestart the WebSEAL server.Configure credential refresh

3. Enabling placement of server name into junction header

You can configure WebSEAL to add the server name in the junction header.

Use the [header-names] <header-data> stanza entry to configure WebSEAL to add a header with the URI-encoded authorization API administration server name to requests for junctioned applications. If you do not configure this entry, WebSEAL does not add any headers to the request.

The <header-data> entry has the following format:

[header-names]
<header-data> = <header-name>

where:

<header-data>

The type of data that WebSEAL adds to the <header-name> header of the request.

Note: Use the value server-name to add the Security Access Manager authorization server name for the WebSEAL server.

<header-name>

The name of the header that holds the data.

The following value is set in the default WebSEAL configuration file.

[header-names]
server-name = iv_server_name

This setting adds a header that is called iv_server_name to pass the name of the server to junctioned applications. For this example, if the WebSEAL instance is default-webseald-diamond.subnet1.ibm.com, WebSEAL passes the following header to the junction:

iv_server_name:default-webseald-diamond.subnet1.ibm.com

Typically, the default value iv_server_name is used. However, you can replace it with any valid string. Valid strings are limited to the following characters: A-Z, a-z, 0–9, hyphen ( - ), or underscore ( _ ).

Ensure that the <header-data> stanza entry is set with a <header-data> value of server-name in the configuration file for the WebSEAL instance. For example:

[header-names]
server-name = iv_server_name

Restart the WebSEAL server.

Parent topic: Configure credential refresh

Credential refresh usageCredential refresh usagecredential refreshusageThis section contains the following topics:Credential refreshRefreshing credentials for a specified userYou can send a command to the WebSEAL server, instructing it to perform a credential refresh operation for all of the sessions of the specified user on the WebSEAL server.Troubleshooting for credential refresh

Credential refresh usage

This section contains the following topics:

Refreshing credentials for a specified user
You can send a command to the WebSEAL server, instructing it to perform a credential refresh operation for all of the sessions of the specified user on the WebSEAL server.

Troubleshooting for credential refresh

Parent topic: Credential refresh

Refreshing credentials for a specified userRefreshing credentials for a specified userYou can send a command to the WebSEAL server, instructing it to perform a credential refresh operation for all of the sessions of the specified user on the WebSEAL server.credential refreshfor specific userpdadmin server taskrefresh all_sessions The refresh all_sessions command is not supported in a distributed session cache environment. The syntax is (entered as one line): pdadmin> server task instance_name-webseald-host_name refresh all_sessions user_nameEnter the above command as one continuous command line.To obtain the server name in the correct format, use the pdadmin server list command. Then enter the pdadmin command to refresh all sessions. For example, when logged in to pdadmin as the administrative user sec_master: pdadmin sec_master> server list default-webseald-diamond.subnet1.ibm.com default-webseald-cmd pdadmin sec_master> server task default-webseald-diamond.subnet1.ibm.com refresh all_sessions brian DPWWA2043IThe user's credential was updated.Note that the pdadmin server task command must each be entered as one continuous command line.A warning message is returned if the user is not logged in to the WebSEAL server.Usage notes: Configure credential refresh for WebSEAL before using this pdadmin command. See Configure credential refresh.You must issue a separate pdadmin command for each user whose credentials are to be refreshed. You cannot refresh credentials for more than one user at a time.The user invoking this command must have server admin (the s ACL bit) permission on the /WebSEAL/hostname_instance_name server object. This permission prevents unauthorized users from performing credential refresh operations. Note that the name of the hostname_instance_name server object is different from the server name. To determine the exact name of the server object, use pdadmin object list. For example, when logged in to pdadmin as the administrative user sec_master: pdadmin sec_master> object list /WebSEAL /WebSEAL/cmd-default /WebSEAL/diamond.subnet1.ibm.com-defaultCredential refresh usage

Refreshing credentials for a specified user

You can send a command to the WebSEAL server, instructing it to perform a credential refresh operation for all of the sessions of the specified user on the WebSEAL server.

Note: The refresh all_sessions command is not supported in a distributed session cache environment.

The syntax is (entered as one line):

pdadmin> server task instance_name-webseald-host_name
 refresh all_sessions user_name

Enter the above command as one continuous command line.

To obtain the server name in the correct format, use the pdadmin server list command. Then enter the pdadmin command to refresh all sessions. For example, when logged in to pdadmin as the administrative user sec_master:

pdadmin sec_master> server list
default-webseald-diamond.subnet1.ibm.com
default-webseald-cmd
pdadmin sec_master> server task default-webseald-diamond.subnet1.ibm.com
refresh all_sessions brian
DPWWA2043IThe user's credential was updated.

Note that the pdadmin server task command must each be entered as one continuous command line.

A warning message is returned if the user is not logged in to the WebSEAL server.

Usage notes:

Configure credential refresh for WebSEAL before using this pdadmin command. See Configure credential refresh.

You must issue a separate pdadmin command for each user whose credentials are to be refreshed. You cannot refresh credentials for more than one user at a time.

The user invoking this command must have server admin (the s ACL bit) permission on the /WebSEAL/hostname_instance_name server object. This permission prevents unauthorized users from performing credential refresh operations.

Note that the name of the hostname_instance_name server object is different from the server name. To determine the exact name of the server object, use pdadmin object list. For example, when logged in to pdadmin as the administrative user sec_master:

pdadmin sec_master> object list /WebSEAL
/WebSEAL/cmd-default
/WebSEAL/diamond.subnet1.ibm.com-default

Parent topic: Credential refresh usage

Troubleshooting for credential refreshTroubleshooting for credential refreshtroubleshootingcredential refreshcredential refreshtroubleshootingProblem:When a new group entry is added to a user's information in a user registry, a credential refresh command does not obtain the new entry.Solution:Some user registries maintain cached information. The cache is updated periodically. The cache update must take place before the credential refresh can succeed. Likewise, when using a replicated LDAP user registry, the updates to the replicated registries do not occur immediately. Wait 30 seconds and try credential refresh again. For more information, see Refresh of cached credential informationSome user registries maintain cached information. Cached data is kept for a specific amount of time, and is then discarded. After the cached data has expired, it is not reloaded into the cache until the next time the user registry is accessed. Therefore, when changes are made to user registry data, the data is not immediately cached in memory. Likewise, when using a replicated LDAP user registry, the updates to the replicated registries do not occur immediately..Credential refresh usage

Troubleshooting for credential refresh

Problem:

When a new group entry is added to a user's information in a user registry, a credential refresh command does not obtain the new entry.

Solution:

Some user registries maintain cached information. The cache is updated periodically. The cache update must take place before the credential refresh can succeed. Likewise, when using a replicated LDAP user registry, the updates to the replicated registries do not occur immediately. Wait 30 seconds and try credential refresh again. For more information, see Refresh of cached credential information.

Parent topic: Credential refresh usage

External authentication interfaceExternal authentication interfaceexternal authentication interfaceoverviewauthenticationexternal interfaceEAIexternal authentication interfaceThis chapter discusses the external authentication interface (sometimes referred to as EAI).Topic Index:Configuration of the certificate authentication mechanismYou can use the External Authentication Interface (EAI) protocol to configure a junctioned web application to handle certificate authentication on behalf of WebSEAL.Kerberos authentication through an External Authentication Interface (EAI)The appliance internally supports Kerberos authentication for use with Windows clients to achieve Windows desktop single sign-on. Alternatively, you can configure a junctioned web server to handle Kerberos authentication on behalf of the appliance. AuthenticationExternal authentication interface overviewExternal authentication interface process flowExternal authentication interface configurationExternal authentication interface HTTP header referenceUse of external authentication interface with existing WebSEAL features

External authentication interface

This chapter discusses the external authentication interface (sometimes referred to as EAI).

Topic Index:

External authentication interface overview

External authentication interface process flow

External authentication interface configuration

External authentication interface HTTP header reference

Use of external authentication interface with existing WebSEAL features

Parent topic: Authentication

Related concepts:

Configuration of the certificate authentication mechanism

Kerberos authentication through an External Authentication Interface (EAI)

External authentication interface overviewExternal authentication interface overviewexternal authentication interfaceoverviewSecurity Access Manager provides an external authentication interface that enables you to extend the authentication process for WebSEAL. The external authentication interface allows an independent remote service to handle the authentication process for WebSEAL. The identity information returned by the external authentication interface service is used to generate user credentials. Security Access Manager can accept identity information from EAI for the following types of users:Users that exist in the Security Access Manager internal user registry.Users that do not exist in the Security Access Manager internal user registry, but only exist in a registry external to Security Access Manager.This extended authentication functionality is similar to the existing custom authentication module capability provided by the Web security external authentication C API. The difference, however, is that the external authentication interface returns user identity information in HTTP response headers rather than through the authentication module interface.When using the external authentication interface, the authentication operation is performed external to WebSEAL by a custom application located on a remote, junctioned server. The design, methodology, and code for the custom authentication application is entirely the responsibility of the application developer. This developer reference document does not provide any instructions for the construction of this custom authentication operation. However, the requirement of this application is to return identity information resulting from the custom authentication process in specially named HTTP response headers.External authentication interfaceExternal authentication interface process flowExternal authentication interface configurationExternal authentication interface HTTP header referenceUse of external authentication interface with existing WebSEAL features

External authentication interface overview

Security Access Manager provides an external authentication interface that enables you to extend the authentication process for WebSEAL. The external authentication interface allows an independent remote service to handle the authentication process for WebSEAL. The identity information returned by the external authentication interface service is used to generate user credentials.

Security Access Manager can accept identity information from EAI for the following types of users:

Users that exist in the Security Access Manager internal user registry.

Users that do not exist in the Security Access Manager internal user registry, but only exist in a registry external to Security Access Manager.

This extended authentication functionality is similar to the existing custom authentication module capability provided by the Web security external authentication C API. The difference, however, is that the external authentication interface returns user identity information in HTTP response headers rather than through the authentication module interface.

When using the external authentication interface, the authentication operation is performed external to WebSEAL by a custom application located on a remote, junctioned server. The design, methodology, and code for the custom authentication application is entirely the responsibility of the application developer. This developer reference document does not provide any instructions for the construction of this custom authentication operation. However, the requirement of this application is to return identity information resulting from the custom authentication process in specially named HTTP response headers.

Parent topic: External authentication interface

Related concepts:

External authentication interface process flow

External authentication interface configuration

External authentication interface HTTP header reference

Use of external authentication interface with existing WebSEAL features

External authentication interface process flowExternal authentication interface process flowexternal authentication interfaceprocess flowprocess flowexternal authentication interfaceThe following diagram and detailed steps illustrate the process flow for external authentication interface authentication. The components of this example process flow scenario include:WebSEAL.Junctioned server with an external authentication application that uses the external authentication interface.External authentication interface process flowExternal authentication interface process flowAuthentication process is initiated. There are many possibilities for initiating the authentication process. A typical example: An unauthenticated user requests a protected resource.WebSEAL intercepts the request and returns a redirect to a customized login.html response page. The login.html page is customized to contain a submit link to the external authentication application.The user provides login information (user name and password) on the form and clicks the submit link to send the data to the external authentication application. Other examples of initiating the authentication process can include: Manually typing an appropriate link to the external authentication application.Signon requirement in a CDSSO environment.Cached page.In an IBM Tivoli Federated Identity Management scenario, the user is redirected to the external authentication application from a service provider, with the goal of having an identity provided for that user. A hidden configuration option enables you to give priority to an EAI header to redirect a successful login to a URL. To enable this feature, add the following option and value to the [eai] stanza: eai-redir-url-priority = yesAuthentication request and response exchange. The process of authentication might require a number of exchanges between the external authentication application and the client. Exchanges are streamed through (not intercepted) by WebSEAL. The final authenticating request to the external authentication application must be directed to a distinct URL. This URL could, for example, include a query string that indicates the login task, such as state=perform-login. This final URL is specified, in part or whole, in the WebSEAL configuration file as the trigger URL. WebSEAL examines each request for this trigger URL. If the trigger URL is detected, WebSEAL examines the corresponding response for authentication data located in HTTP headers (specified in the WebSEAL configuration file). WebSEAL supports EAI logout. An HTTP header returned from the EAI enables it to instruct WebSEAL to logout a session. The header emulates the pdadmin server task command line input, and therefore is analogous to the hidden WebSEAL pdadmin command of the same name. The syntax for the header is am-eai-server-task: terminate session <user-sess-id>, where terminate session is a non-translatable keyword pair, and <user-sess-id> is a user session ID of the same format and contents as that used to perform the terminate session command using pdadmin. Example exchange 1: The user clicks a submit link on a custom login page. This link is the trigger URL.The recognition of the trigger URL in the request causes WebSEAL to look for authentication data in the corresponding response.The external authentication application authenticates the user and, in its response, populates the special HTTP headers with authentication data. Example exchange 2: The external authentication application requires several exchanges with the user to receive the required login information.Each request to the external authentication application uses the trigger URL. Therefore, for each response, WebSEAL looks for authentication data. WebSEAL examines each corresponding response for authentication data returned from the external authentication interface in HTTP headers.When no authentication takes place, these headers are empty in each response. WebSEAL continues streaming the requests and responses without taking any action.After several exchanges, the external authentication application receives all the login information it needs. The external authentication application authenticates the user and, in its final response, populates the special HTTP headers with authentication data. Example exchange 3: The external authentication application requires several exchanges with the user to receive the required login information.Each request to the external authentication application uses a URL that does not match the trigger URL. Therefore, for each corresponding response, WebSEAL does not look for authentication dataWebSEAL streams the requests and responses without taking any action.The final request to the external authentication application uses the trigger URL.The recognition of the trigger URL in this final request causes WebSEAL to look for authentication data in the corresponding response.The external authentication authenticates the user and, in its final response, populates the special HTTP headers with authentication data.Authentication response. WebSEAL examines the corresponding response and finds the authentication data in the HTTP headers. WebSEAL uses the authentication data to build a credential for the user.WebSEAL sends a response to the user using the following precedence: If automatic redirection is enabled, the user is redirected to the location specified in the WebSEAL configuration file. See WebSEAL-specified (automatic) redirection.If the response from the external authentication application contains the streaming flag, WebSEAL streams the original response to the client. See External authentication interface - authentication flags.If the initial request was cached, the request is reprocessed for the user. See Request caching with external authentication interface.If the response from the external authentication application contains a redirection URL header, the user is redirected to the location specified by that URL. See External authentication interface-specified redirection.Otherwise, WebSEAL responds with the standard login_success.html page. See Static HTML server response pagesWebSEAL provides a number of static HTML server response pages that can be used to provide responses to client requests. .External authentication interfaceExternal authentication interface overviewExternal authentication interface configurationExternal authentication interface HTTP header referenceUse of external authentication interface with existing WebSEAL features

External authentication interface process flow

The following diagram and detailed steps illustrate the process flow for external authentication interface authentication. The components of this example process flow scenario include:

WebSEAL.

Junctioned server with an external authentication application that uses the external authentication interface.

Figure 18. External authentication interface process flow

Authentication process is initiated.

There are many possibilities for initiating the authentication process. A typical example:

An unauthenticated user requests a protected resource.

WebSEAL intercepts the request and returns a redirect to a customized login.html response page.

The login.html page is customized to contain a submit link to the external authentication application.

The user provides login information (user name and password) on the form and clicks the submit link to send the data to the external authentication application.

Other examples of initiating the authentication process can include:

Manually typing an appropriate link to the external authentication application.

Signon requirement in a CDSSO environment.

Cached page.

In an IBM® Tivoli® Federated Identity Management scenario, the user is redirected to the external authentication application from a service provider, with the goal of having an identity provided for that user.

Note: A hidden configuration option enables you to give priority to an EAI header to redirect a successful login to a URL. To enable this feature, add the following option and value to the [eai] stanza:

eai-redir-url-priority = yes

Authentication request and response exchange.

The process of authentication might require a number of exchanges between the external authentication application and the client. Exchanges are streamed through (not intercepted) by WebSEAL.

The final authenticating request to the external authentication application must be directed to a distinct URL. This URL could, for example, include a query string that indicates the login task, such as state=perform-login. This final URL is specified, in part or whole, in the WebSEAL configuration file as the trigger URL. WebSEAL examines each request for this trigger URL.

If the trigger URL is detected, WebSEAL examines the corresponding response for authentication data located in HTTP headers (specified in the WebSEAL configuration file).

WebSEAL supports EAI logout. An HTTP header returned from the EAI enables it to instruct WebSEAL to logout a session. The header emulates the pdadmin server task command line input, and therefore is analogous to the hidden WebSEAL pdadmin command of the same name. The syntax for the header is am-eai-server-task: terminate session <user-sess-id>, where terminate session is a non-translatable keyword pair, and <user-sess-id> is a user session ID of the same format and contents as that used to perform the terminate session command using pdadmin.

Example exchange 1:

The user clicks a submit link on a custom login page. This link is the trigger URL.

The recognition of the trigger URL in the request causes WebSEAL to look for authentication data in the corresponding response.

The external authentication application authenticates the user and, in its response, populates the special HTTP headers with authentication data.

Example exchange 2:

The external authentication application requires several exchanges with the user to receive the required login information.

Each request to the external authentication application uses the trigger URL. Therefore, for each response, WebSEAL looks for authentication data.

WebSEAL examines each corresponding response for authentication data returned from the external authentication interface in HTTP headers.

When no authentication takes place, these headers are empty in each response. WebSEAL continues streaming the requests and responses without taking any action.

After several exchanges, the external authentication application receives all the login information it needs. The external authentication application authenticates the user and, in its final response, populates the special HTTP headers with authentication data.

Example exchange 3:

The external authentication application requires several exchanges with the user to receive the required login information.

Each request to the external authentication application uses a URL that does not match the trigger URL. Therefore, for each corresponding response, WebSEAL does not look for authentication data

WebSEAL streams the requests and responses without taking any action.

The final request to the external authentication application uses the trigger URL.

The recognition of the trigger URL in this final request causes WebSEAL to look for authentication data in the corresponding response.

The external authentication authenticates the user and, in its final response, populates the special HTTP headers with authentication data.

Authentication response.

WebSEAL examines the corresponding response and finds the authentication data in the HTTP headers.

WebSEAL uses the authentication data to build a credential for the user.

WebSEAL sends a response to the user using the following precedence:

If automatic redirection is enabled, the user is redirected to the location specified in the WebSEAL configuration file.

See WebSEAL-specified (automatic) redirection.

If the response from the external authentication application contains the streaming flag, WebSEAL streams the original response to the client.

See External authentication interface - authentication flags.

If the initial request was cached, the request is reprocessed for the user.

See Request caching with external authentication interface.

If the response from the external authentication application contains a redirection URL header, the user is redirected to the location specified by that URL.

See External authentication interface-specified redirection.

Otherwise, WebSEAL responds with the standard login_success.html page.

See Static HTML server response pages.

Parent topic: External authentication interface

Related concepts:

External authentication interface overview

External authentication interface configuration

External authentication interface HTTP header reference

Use of external authentication interface with existing WebSEAL features

External authentication interface configurationExternal authentication interface configurationexternal authentication interfaceconfigurationThis section describes how to configure WebSEAL to use the external authentication interface.External authentication interfaceExternal authentication interface overviewExternal authentication interface process flowExternal authentication interface HTTP header referenceUse of external authentication interface with existing WebSEAL featuresEnabling the external authentication interfaceInitiating the authentication processConfiguration of the external authentication interface trigger URLThe external authentication interface authentication process supports multiple request-response exchanges. For efficiency and the security of the WebSEAL server, these exchanges are typically streamed through WebSEAL. WebSEAL intercepts this exchange only when there is an occurrence of a special trigger URL in a request. HTTP header names for authentication dataYou must specify the names of the HTTP headers that contain the authentication data returned from the external authentication application. Extracting authentication data from special HTTP headersHow to generate the credentialExternal authentication interface credential replacementValidating the user identityHow to write an external authentication application

External authentication interface configuration

This section describes how to configure WebSEAL to use the external authentication interface.

Enabling the external authentication interface

Initiating the authentication process

Configuration of the external authentication interface trigger URL
The external authentication interface authentication process supports multiple request-response exchanges. For efficiency and the security of the WebSEAL server, these exchanges are typically streamed through WebSEAL. WebSEAL intercepts this exchange only when there is an occurrence of a special trigger URL in a request.

HTTP header names for authentication data
You must specify the names of the HTTP headers that contain the authentication data returned from the external authentication application.

Extracting authentication data from special HTTP headers

How to generate the credential

External authentication interface credential replacement

Validating the user identity

How to write an external authentication application

Parent topic: External authentication interface

Related concepts:

External authentication interface overview

External authentication interface process flow

External authentication interface HTTP header reference

Use of external authentication interface with existing WebSEAL features

Enabling the external authentication interfaceEnabling the external authentication interfaceexternal authentication interfaceenablingdisablingeai-auth stanza entry The eai-auth stanza entry, located in the [eai] stanza of the WebSEAL configuration file, enables and disables the external authentication interface functionality. The external authentication interface can be implemented over HTTP, HTTPS, or both. External authentication interface authentication is disabled by default. To configure the external authentication interface:Stop the WebSEAL server.Edit the WebSEAL configuration file. In the [eai] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.Configuring the external authentication interfaceProtocol to SupportConfiguration File EntryHTTPeai-auth = httpHTTPSeai-auth = httpsBoth HTTP and HTTPSeai-auth = bothDisable external authentication interface (default)eai-auth = noneFor example, to support both protocols: [eai] eai-auth = both.Restart the WebSEAL server. When eai-auth = none (disabled), all other configured external authentication interface-related stanza entries have no effect.External authentication interface configuration

Enabling the external authentication interface

About this task

The eai-auth stanza entry, located in the [eai] stanza of the WebSEAL configuration file, enables and disables the external authentication interface functionality. The external authentication interface can be implemented over HTTP, HTTPS, or both.

External authentication interface authentication is disabled by default.

To configure the external authentication interface:

Procedure

Stop the WebSEAL server.

Edit the WebSEAL configuration file. In the [eai] stanza, specify the protocols to support in your network environment. The protocols are shown in the following table.

Table 47. Configuring the external authentication interface

Protocol to Support | Configuration File Entry
HTTP | eai-auth = http
HTTPS | eai-auth = https
Both HTTP and HTTPS | eai-auth = both
Disable external authentication interface (default) | eai-auth = none

For example, to support both protocols:

[eai]
eai-auth = both

.

Restart the WebSEAL server.

Results

When eai-auth = none (disabled), all other configured external authentication interface-related stanza entries have no effect.

Parent topic: External authentication interface configuration

Initiating the authentication processInitiating the authentication processexternal authentication interfaceinitiating the authentication processauthentication processinitiationTypically, external authentication interface authentication can be initiated from redirection commands or custom links placed in external application pages. In an external authentication interface scenario, WebSEAL does not provide any built-in methods for initiating the authentication process. WebSEAL does not provide any special prompts or login pages. You can modify WebSEAL's existing login.html form to include a custom link to the external authentication application. Modification of the login.html form is necessary to support reauthentication and authentication strength (step-up).See Login page and macro support with external authentication interface.You can also implement local response redirection to handle server responses to client requests. See Local response redirectionExternal authentication interface configuration

Initiating the authentication process

About this task

Typically, external authentication interface authentication can be initiated from redirection commands or custom links placed in external application pages. In an external authentication interface scenario, WebSEAL does not provide any built-in methods for initiating the authentication process. WebSEAL does not provide any special prompts or login pages.

Procedure

You can modify WebSEAL's existing login.html form to include a custom link to the external authentication application. Modification of the login.html form is necessary to support reauthentication and authentication strength (step-up).

See Login page and macro support with external authentication interface.

You can also implement local response redirection to handle server responses to client requests. See Local response redirection

Parent topic: External authentication interface configuration

Configuration of the external authentication interface trigger URLConfiguration of the external authentication interface trigger URLThe external authentication interface authentication process supports multiple request-response exchanges. For efficiency and the security of the WebSEAL server, these exchanges are typically streamed through WebSEAL. WebSEAL intercepts this exchange only when there is an occurrence of a special trigger URL in a request. external authentication interfacetrigger URLtrigger URLA trigger URL is a server-relative or absolute URL in the WebSEAL configuration file. The trigger URL usually requests authentication from the external authentication application. For example, the trigger URL might be the URL to the external authentication application in a special link on a customized login page.When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.Trigger URL stringsCan use standard wildcard patterns. Pattern matching is appropriate only for ASCII-based strings and it is not case-sensitive.Must be in ASCII format if they use pattern-matching. The matching URLs in the requests must be in ASCII format.Must be as specific as possible in the configured URL to limit the number of times that WebSEAL intercepts the request-response exchange.Specify trigger URL strings in the trigger stanza entry in the [eai-trigger-urls] stanza of the WebSEAL configuration file.Virtual host junctions Match a trigger if their protocol, virtual host name, and port match the virtual host definition. The virtual host name matching is not case-sensitive.Do not use regular WebSEAL junction triggers, such as the ones that do not match a virtual host definition. Regular WebSEAL junctions do not use virtual host junction triggers.trigger stanza entryeai-trigger-urls stanzaExamples of authentication requests to an external authentication application:Junction typeURLCorresponding trigger URLstandardhttp://webseal.example.com/ eai-jct/login.asp?url=/ return_authn_data.asp[eai-trigger-urls] trigger = /eai-jct/login.asp*authn*virtual hosthttp://vhj.webseal.example.com/ login.asp?url=/return_authn_ data.asp[eai-trigger-urls] trigger = http://vhj.webseal. example.com/login.asp*authn*External authentication interface configuration

Configuration of the external authentication interface trigger URL

The external authentication interface authentication process supports multiple request-response exchanges. For efficiency and the security of the WebSEAL server, these exchanges are typically streamed through WebSEAL. WebSEAL intercepts this exchange only when there is an occurrence of a special trigger URL in a request.

A trigger URL is a server-relative or absolute URL in the WebSEAL configuration file. The trigger URL usually requests authentication from the external authentication application. For example, the trigger URL might be the URL to the external authentication application in a special link on a customized login page.

When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.

Trigger URL strings

Can use standard wildcard patterns. Pattern matching is appropriate only for ASCII-based strings and it is not case-sensitive.

Must be in ASCII format if they use pattern-matching. The matching URLs in the requests must be in ASCII format.

Must be as specific as possible in the configured URL to limit the number of times that WebSEAL intercepts the request-response exchange.

Specify trigger URL strings in the trigger stanza entry in the [eai-trigger-urls] stanza of the WebSEAL configuration file.

Virtual host junctions

Match a trigger if their protocol, virtual host name, and port match the virtual host definition. The virtual host name matching is not case-sensitive.

Do not use regular WebSEAL junction triggers, such as the ones that do not match a virtual host definition. Regular WebSEAL junctions do not use virtual host junction triggers.

Table 48. Examples of authentication requests to an external authentication application:

Junction type
URL
Corresponding trigger URL

standard

http://webseal.example.com/
eai-jct/login.asp?url=/
return_authn_data.asp

[eai-trigger-urls]
trigger = /eai-jct/login.asp*authn*

virtual host

http://vhj.webseal.example.com/
login.asp?url=/return_authn_
data.asp

[eai-trigger-urls]
trigger = http://vhj.webseal.
example.com/login.asp*authn*

Parent topic: External authentication interface configuration

HTTP header names for authentication dataHTTP header names for authentication dataYou must specify the names of the HTTP headers that contain the authentication data returned from the external authentication application. external authentication interfaceHTTP header namesauthentication dataHTTP header namesThere are four categories of HTTP headers that hold authentication data:Privilege Attribute Certificate (PAC) format The PAC is an ASN.1 data structure used to express identity information. Authentication data returned to WebSEAL in PAC format can be directly converted to a credential.WebSEAL user identity structure The WebSEAL user identity structure is the same structure generated by WebSEAL's default built-in authentication modules. When the user identity format type is used, the information is processed by the eaiauthn authentication module and a credential is built by the Security Access Manager authorization API. Distributed session cache session identifier The session identifier is for a distributed session that is managed by the distributed session cache. See Sharing sessions across multiple DNS domainsWhen operating in a multi-domain environment, you must use a different mechanism to communicate the session identifier to the WebSEAL servers in the different DNS domains..WebSEAL external user identify structureSecurity Access Manager can accept identity information from the EAI for external users; that is, users that only exist in a registry external to Security Access Manager. The eai-xattrs-header entry also applies to external users. See External authentication interface overview. For more information about the [eai] stanza, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.Common The common header category holds additional information and can be used with either the PAC or user identity formats.Complete details about these special headers can be found in the External authentication interface HTTP header reference.Use the [eai] stanza of the WebSEAL configuration file to specify the names of the HTTP headers that contain the authentication data returned from the external authentication interface server. The header names can be customized. The custom external authentication interface authentication module must be written to use the header names as configured.The following examples show the default header names used in the WebSEAL configuration file:PAC headers:eai-pac-headereai-pac-svc-header[eai] eai-pac-header = am-eai-pac eai-pac-svc-header = am-eai-pac-svcUser identity headers:eai-user-id-headereai-auth-level-headereai-xattrs-header[eai] eai-user-id-header = am-eai-user-id eai-auth-level-header = am-eai-auth-level eai-xattrs-header = am-eai-xattrsExternal user identity headers:[eai] eai-ext-user-id-header = am-eai-ext-user-id eai-ext-user-groups-header = am-eai-ext-user-groupsDistributed session cache session identifier:distributed session cachesession identifier[eai] eai-session-id-header = am-eai-session-idCommon headers:eai-redir-url-headereai-flags-header[eai] eai-flags-header = am-eai-flags eai-redir-url-header = am-eai-redir-urlFor more information about using the eai-flags-header common header, see External authentication interface - authentication flagsFor more information about using the eai-redir-url-header common header, see External authentication interface-specified redirection.External authentication interface configuration

HTTP header names for authentication data

You must specify the names of the HTTP headers that contain the authentication data returned from the external authentication application.

There are four categories of HTTP headers that hold authentication data:

Privilege Attribute Certificate (PAC) format

The PAC is an ASN.1 data structure used to express identity information. Authentication data returned to WebSEAL in PAC format can be directly converted to a credential.

WebSEAL user identity structure

The WebSEAL user identity structure is the same structure generated by WebSEAL's default built-in authentication modules. When the user identity format type is used, the information is processed by the eaiauthn authentication module and a credential is built by the Security Access Manager authorization API.

Distributed session cache session identifier

The session identifier is for a distributed session that is managed by the distributed session cache. See Sharing sessions across multiple DNS domains.

WebSEAL external user identify structure

Security Access Manager can accept identity information from the EAI for external users; that is, users that only exist in a registry external to Security Access Manager. The eai-xattrs-header entry also applies to external users. See External authentication interface overview. For more information about the [eai] stanza, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.

Common

The common header category holds additional information and can be used with either the PAC or user identity formats.

Complete details about these special headers can be found in the External authentication interface HTTP header reference.

Use the [eai] stanza of the WebSEAL configuration file to specify the names of the HTTP headers that contain the authentication data returned from the external authentication interface server. The header names can be customized. The custom external authentication interface authentication module must be written to use the header names as configured.

The following examples show the default header names used in the WebSEAL configuration file:

PAC headers:

[eai]
eai-pac-header = am-eai-pac
eai-pac-svc-header = am-eai-pac-svc

User identity headers:

[eai]
eai-user-id-header = am-eai-user-id
eai-auth-level-header = am-eai-auth-level
eai-xattrs-header = am-eai-xattrs

External user identity headers:

[eai]
eai-ext-user-id-header = am-eai-ext-user-id
eai-ext-user-groups-header = am-eai-ext-user-groups

Distributed session cache session identifier:

[eai]
eai-session-id-header = am-eai-session-id

Common headers:

[eai]
eai-flags-header = am-eai-flags
eai-redir-url-header = am-eai-redir-url

For more information about using the eai-flags-header common header, see External authentication interface - authentication flags

For more information about using the eai-redir-url-header common header, see External authentication interface-specified redirection.

Parent topic: External authentication interface configuration

Extracting authentication data from special HTTP headersExtracting authentication data from special HTTP headersexternal authentication interfaceextracting authentication data from HTTP headersHTTP headersextracting authentication dataWebSEAL examines a response for special headers when a trigger URL is detected in the corresponding request. The special HTTP headers contain authentication data provided by the custom external authentication application. The presence of either the PAC header or the user identity header causes WebSEAL to extract the authentication data from the headers and build a credential for the user. The session identifier header causes WebSEAL to retrieve the specified session from the distributed session cache. WebSEAL follows a specific sequence for processing the special HTTP authentication headers:If the session identifier header is present, it takes precedence over the other authentication headers.If both headers are present, the PAC data takes precedence and any user identity data is ignored.If neither header is present, the response is streamed back to the client. This behavior also allows the external authentication application to perform authentication error handling.If either the PAC or user identity header is present, but the header value is NULL or corrupted, an error is returned. Such an error can occur if an external authentication interface server is incorrectly configured.External authentication interface configuration

Extracting authentication data from special HTTP headers

About this task

WebSEAL examines a response for special headers when a trigger URL is detected in the corresponding request.

The special HTTP headers contain authentication data provided by the custom external authentication application. The presence of either the PAC header or the user identity header causes WebSEAL to extract the authentication data from the headers and build a credential for the user. The session identifier header causes WebSEAL to retrieve the specified session from the distributed session cache.

WebSEAL follows a specific sequence for processing the special HTTP authentication headers:

Procedure

If the session identifier header is present, it takes precedence over the other authentication headers.

If both headers are present, the PAC data takes precedence and any user identity data is ignored.

If neither header is present, the response is streamed back to the client. This behavior also allows the external authentication application to perform authentication error handling.

If either the PAC or user identity header is present, but the header value is NULL or corrupted, an error is returned. Such an error can occur if an external authentication interface server is incorrectly configured.

Parent topic: External authentication interface configuration

How to generate the credentialHow to generate the credentialexternal authentication interfacegenerating credentialgenerating credentialexternal authentication interfaceWebSEAL can build a credential directly from PAC header data. The authorization API builds the credential for user identity header data.Other authentication data can be supplied by the WebSEAL system itself when building a credential from user identity authentication data. WebSEAL has additional information about the client system that is required to construct the credential. This information is supplied when authentication data from the external authentication interface is used to generate a credential.Some of these values can be overridden by the eaiauthn module using extended attributes to the header data.Supplemental credential data provided by WebSEALFieldSourceCan external authentication interface override value?Client IP AddressDerived from the initial client request.yesBrowser InformationDerived from the initial client request.yesRegistry TypeDetermined from the current WebSEAL configuration.noDomainDetermined from the current WebSEAL configuration.noExternal authentication interface configuration

How to generate the credential

WebSEAL can build a credential directly from PAC header data. The authorization API builds the credential for user identity header data.

Other authentication data can be supplied by the WebSEAL system itself when building a credential from user identity authentication data. WebSEAL has additional information about the client system that is required to construct the credential. This information is supplied when authentication data from the external authentication interface is used to generate a credential.

Some of these values can be overridden by the eaiauthn module using extended attributes to the header data.

Table 49. Supplemental credential data provided by WebSEAL

Field
Source

Can external authentication interface override value?

Client IP Address
Derived from the initial client request.
yes

Browser Information
Derived from the initial client request.
yes

Registry Type
Determined from the current WebSEAL configuration.
no

Domain
Determined from the current WebSEAL configuration.
no

Parent topic: External authentication interface configuration

External authentication interface credential replacementExternal authentication interface credential replacementexternal authentication interfacecredential replacementcredential replacementexternal authentication interfaceWebSEAL allows a previously authenticated user to request authentication again through the external authentication interface trigger URL and establish a new session. WebSEAL deletes the old session cache entry, builds a new session cache entry containing a new credential for that user (credential replacement), and provides the user with a new session key.Operation conditions for external authentication interface credential replacement:If a trigger URL is used by a previously authenticated user to make a request, that request is allowed to pass through to the external authentication application. In earlier versions of the external authentication interface, a previously authenticated user was forced to log out and log in again when making a request using a trigger URL.If the external authentication interface response to the user request contains authentication data, and the user's session cache entry is flagged for authentication strength policy (step-up) or reauthentication, then WebSEAL enforces the step-up or reauthentication process. The existing session cache (and credential) for the user is not replaced.If the external authentication interface response to the user request contains authentication data, and the user's cache entry is not flagged as step-up or reauthentication, then: The existing session cache entry is deleted and replaced with a new entry containing a new credential for the user.If the user uses session cookies to maintain session state, a new session key is created and returned to the user.If the user uses SSL session IDs or HTTP headers to maintain session state, the existing session key is reused.If a failover cookie is used, a new failover cookie is created and returned to the user.If user session IDs are used, the user session ID mapping to the WebSEAL session ID is updated.If an LTPA cookie is used, a new LTPA cookie is created and returned to the user.The external authentication interface credential replace function is important to support, for example, the account-linking features that the Liberty federate function provides. A Tivoli Federated Identity Manager environment requires the ability to reauthenticate a previously authenticated user to achieve the Liberty federate function (Liberty Alliance Project). A federate operation allows a local account at a service provider to be linked with an account at an identity provider. To achieve this, a user must first sign into the user's service provider and consent to linking the user's account with the identity provider. Once the federate operation has occurred, the browser focus returns to the service provider where the user's credential is updated with the new credential generated by the identity provider. External authentication interface configuration

External authentication interface credential replacement

WebSEAL allows a previously authenticated user to request authentication again through the external authentication interface trigger URL and establish a new session. WebSEAL deletes the old session cache entry, builds a new session cache entry containing a new credential for that user (credential replacement), and provides the user with a new session key.

Operation conditions for external authentication interface credential replacement:

If a trigger URL is used by a previously authenticated user to make a request, that request is allowed to pass through to the external authentication application.

Note: In earlier versions of the external authentication interface, a previously authenticated user was forced to log out and log in again when making a request using a trigger URL.

If the external authentication interface response to the user request contains authentication data, and the user's session cache entry is flagged for authentication strength policy (step-up) or reauthentication, then WebSEAL enforces the step-up or reauthentication process. The existing session cache (and credential) for the user is not replaced.

If the external authentication interface response to the user request contains authentication data, and the user's cache entry is not flagged as step-up or reauthentication, then:

The existing session cache entry is deleted and replaced with a new entry containing a new credential for the user.

If the user uses session cookies to maintain session state, a new session key is created and returned to the user.

If the user uses SSL session IDs or HTTP headers to maintain session state, the existing session key is reused.

If a failover cookie is used, a new failover cookie is created and returned to the user.

If user session IDs are used, the user session ID mapping to the WebSEAL session ID is updated.

If an LTPA cookie is used, a new LTPA cookie is created and returned to the user.

The external authentication interface credential replace function is important to support, for example, the account-linking features that the Liberty federate function provides. A Tivoli® Federated Identity Manager environment requires the ability to reauthenticate a previously authenticated user to achieve the Liberty federate function (Liberty Alliance Project). A federate operation allows a local account at a service provider to be linked with an account at an identity provider.

To achieve this, a user must first sign into the user's service provider and consent to linking the user's account with the identity provider. Once the federate operation has occurred, the browser focus returns to the service provider where the user's credential is updated with the new credential generated by the identity provider.

Parent topic: External authentication interface configuration

Validating the user identityValidating the user identityexternal authentication interfacevalidating the user nameuser identityvalidationEAI applications can re-authenticate a user by returning new authentication information for a previously authenticated session. By default, WebSEAL does not validate this new authentication information. However, you can configure WebSEAL to verify that the user identity does not change during subsequent EAI authentications.WebSEAL uses the principal name (azn_cred_principal_name attribute) to validate the user identity. The principal name that is contained in the newly constructed credential is compared with the principal name contained in the existing credential. If the two names differ, the validation process fails and WebSEAL returns an authentication error to the user.eai-verify-user-identity stanza entryeai stanzaTo validate user identities during subsequent EAI authentication operations, set the eai-verify-user-identity stanza entry to yes. This entry is located in the [eai] stanza of the WebSEAL configuration file:[eai] eai-verify-user-identity = yesExternal authentication interface configuration

Validating the user identity

EAI applications can re-authenticate a user by returning new authentication information for a previously authenticated session. By default, WebSEAL does not validate this new authentication information. However, you can configure WebSEAL to verify that the user identity does not change during subsequent EAI authentications.

WebSEAL uses the principal name (azn_cred_principal_name attribute) to validate the user identity. The principal name that is contained in the newly constructed credential is compared with the principal name contained in the existing credential. If the two names differ, the validation process fails and WebSEAL returns an authentication error to the user.

To validate user identities during subsequent EAI authentication operations, set the eai-verify-user-identity stanza entry to yes. This entry is located in the [eai] stanza of the WebSEAL configuration file:

[eai]
eai-verify-user-identity = yes

Parent topic: External authentication interface configuration

How to write an external authentication applicationHow to write an external authentication applicationexternal authentication interfacewriting custom applicationexternal authentication applicationswritingcustomThe design, methodology, and code for the external authentication application is entirely the responsibility of the application developer. This developer reference document does not provide any instructions for the construction of this authentication operation.However, the following conditions for the operation of external authentication interface should be considered when developing the custom application:The external authentication interface server is junctioned to WebSEAL.Identity information resulting from the custom authentication process is returned to WebSEAL in specially named HTTP response headers (as configured in the WebSEAL configuration file).Multi-step authentications are allowed.The external authentication application must be available to unauthenticated users.WebSEAL checks its user registry for credential information. Therefore, the external authentication application must either share the same registry with WebSEAL, or the external authentication application must return user information that matches an entry in the WebSEAL user registry.External authentication interface configurationExternal authentication interface - authentication flags

How to write an external authentication application

The design, methodology, and code for the external authentication application is entirely the responsibility of the application developer. This developer reference document does not provide any instructions for the construction of this authentication operation.

However, the following conditions for the operation of external authentication interface should be considered when developing the custom application:

The external authentication interface server is junctioned to WebSEAL.

Identity information resulting from the custom authentication process is returned to WebSEAL in specially named HTTP response headers (as configured in the WebSEAL configuration file).

Multi-step authentications are allowed.

The external authentication application must be available to unauthenticated users.

WebSEAL checks its user registry for credential information. Therefore, the external authentication application must either share the same registry with WebSEAL, or the external authentication application must return user information that matches an entry in the WebSEAL user registry.

External authentication interface - authentication flags

Parent topic: External authentication interface configuration

External authentication interface - authentication flagsEAI flags headerexternal authentication interfaceflags headerWhen an EAI application performs a successful authentication, it constructs and returns the response to a trigger URL. WebSEAL detects this authentication information in the trigger URL response. You can provide authentication flags with this response to help control the authentication processing by WebSEAL. These authentication flags are contained in the HTTP header. eai-flags-header stanza entryeai stanzaUse the eai-flags-header stanza entry in the [eai] stanza of the WebSEAL configuration file to specify name of the flags header.WebSEAL supports the following flags:streamBy default, WebSEAL replaces the EAI-generated response with a WebSEAL-generated response for the authentication operation. You can override this default behavior and configure WebSEAL to stream the EAI-generated response back to the client. That is, after a successful EAI authentication, WebSEAL can strip the EAI-specific headers from the response and stream it back to the client.To achieve this EAI response streaming, the flags header must contain the stream flag.Example EAI flags header:am-eai-flags: streamThe eai-flags-header configuration entry specifies the name of the HTTP header that contains the flags. For example:[eai] eai-flags-header = am-eai-flagsHow to write an external authentication application

External authentication interface - authentication flags

When an EAI application performs a successful authentication, it constructs and returns the response to a trigger URL. WebSEAL detects this authentication information in the trigger URL response. You can provide authentication flags with this response to help control the authentication processing by WebSEAL.

These authentication flags are contained in the HTTP header. Use the eai-flags-header stanza entry in the [eai] stanza of the WebSEAL configuration file to specify name of the flags header.

WebSEAL supports the following flags:

stream

By default, WebSEAL replaces the EAI-generated response with a WebSEAL-generated response for the authentication operation. You can override this default behavior and configure WebSEAL to stream the EAI-generated response back to the client. That is, after a successful EAI authentication, WebSEAL can strip the EAI-specific headers from the response and stream it back to the client.

To achieve this EAI response streaming, the flags header must contain the stream flag.

Example EAI flags header:

am-eai-flags: stream

The eai-flags-header configuration entry specifies the name of the HTTP header that contains the flags. For example:

[eai]
eai-flags-header = am-eai-flags

Parent topic: How to write an external authentication application

External authentication interface HTTP header referenceExternal authentication interface HTTP header referenceexternal authentication interfaceHTTP header referenceseai-pac-header stanza entryeai-pac-svc-header stanza entryeai-xattrs-header stanza entryeai-user-id-header stanza entryeai-auth-level-header stanza entryeai-redir-url-header stanza entryPAC headersDescription Stanza Entry Default Header NameRequiredNotesPAC [eai] eai-pac-headeram-eai-pacyes Authentication data in PAC format. Direct conversion to credential. This header takes precedence over the user identity header. Place this header before others in the response headers.PAC Service ID [eai] eai-pac-svc-headeram-eai-pac-svcno The service ID that should be used to convert the PAC into a credential. If no service ID is specified the default PAC service will be used.User identity headersDescription Stanza Entry Default Header NameRequiredNotesUser Identity [eai] eai-user-id-headeram-eai-user-idyes The ID of the user to generate the credential for. This header should precede all others in the HTTP response. Authentication Level [eai] eai-auth-level-headeram-eai-auth-levelno The authentication strength level for the generated credential. If no value is specified, a default value of 1 is used.Extended Attribute List [eai] eai-xattrs-headeram-eai-xattrsno A comma delimited list of HTTP header names that should be added to the credential as extended attributes. If attributes of the same name are specified by a custom authentication module build with the external authentication C API, the attributes from the custom module take precedence over the HTTP header attributes. External user identity[eai] eai-ext-user-id-headeram-eai-ext-user-idnoSpecifies the name of the header that contains the ID of the external (not in the Security Access Manager user registry) user to use when creating a credential.External group identity[eai] eai-ext-user-groups-headeram-eai-ext-user-groupsnoSpecifies the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential. This entry is only used when the eai-ext-user-id-header stanza entry's value is provided.Session identifier headersDescription Stanza Entry Default Header NameRequiredNotesSession Identifier [eai] eai-session-id-headeram-eai-session-idyesThe identify of the distributed session managed by the Session Management Server.Common headersDescription Stanza Entry Default Header NameRequiredNotesRedirect URL [eai] eai-redir-url-headeram-eai-redir-urlno Only used if WebSEAL does not have a cached request or when automatic redirection is not enabled. Specifies the URI that the client is redirected to upon successful authentication. If no URI is specified, the "login-success" page is returned.Flags header[eai] eai-flags-headeram-eai-flagsnoThe only supported flag is stream. Example: am-eai-flags: streamExternal authentication interfaceExternal authentication interface overviewExternal authentication interface process flowExternal authentication interface configurationUse of external authentication interface with existing WebSEAL features

External authentication interface HTTP header reference

Table 50. PAC headers

Description

Stanza Entry

Default

Header Name

Required
Notes

PAC

[eai]
eai-pac-header

am-eai-pac
yes

Authentication data in PAC format. Direct conversion to credential.

This header takes precedence over the user identity header.

Place this header before others in the response headers.

PAC Service ID

[eai]
eai-pac-svc-header

am-eai-pac-svc
no

The service ID that should be used to convert the PAC into a credential.

If no service ID is specified the default PAC service will be used.

Table 51. User identity headers

Description

Stanza Entry

Default

Header Name

Required
Notes

User Identity

[eai]
eai-user-id-header

am-eai-user-id
yes

The ID of the user to generate the credential for.

This header should precede all others in the HTTP response.

Authentication Level

[eai]
eai-auth-level-header

am-eai-auth-level
no

The authentication strength level for the generated credential.

If no value is specified, a default value of 1 is used.

Extended Attribute List

[eai]
eai-xattrs-header

am-eai-xattrs
no

A comma delimited list of HTTP header names that should be added to the credential as extended attributes.

If attributes of the same name are specified by a custom authentication module build with the external authentication C API, the attributes from the custom module take precedence over the HTTP header attributes.

External user identity

[eai]
eai-ext-user-id-header

am-eai-ext-user-id
no

Specifies the name of the header that contains the ID of the external (not in the Security Access Manager user registry) user to use when creating a credential.

External group identity

[eai]
eai-ext-user-groups-header

am-eai-ext-user-groups
no
Specifies the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential. This entry is only used when the eai-ext-user-id-header stanza entry's value is provided.

Table 52. Session identifier headers

Description

Stanza Entry

Default

Header Name

Required
Notes

Session Identifier

[eai]
eai-session-id-header

am-eai-session-id
yes
The identify of the distributed session managed by the Session Management Server.

Table 53. Common headers

Description

Stanza Entry

Default

Header Name

Required
Notes

Redirect URL

[eai]
eai-redir-url-header

am-eai-redir-url
no

Only used if WebSEAL does not have a cached request or when automatic redirection is not enabled.

Specifies the URI that the client is redirected to upon successful authentication.

If no URI is specified, the "login-success" page is returned.

Flags header

[eai]
eai-flags-header

am-eai-flags
no

The only supported flag is stream.

Example:

am-eai-flags: stream

Parent topic: External authentication interface

Related concepts:

External authentication interface overview

External authentication interface process flow

External authentication interface configuration

Use of external authentication interface with existing WebSEAL features

Use of external authentication interface with existing WebSEAL featuresUse of external authentication interface with existing WebSEAL featuresWebSEALexternal authentication interfaceexternal authentication interfaceuse with existing WebSEAL featuresThis section contains the following topics:External authentication interfaceExternal authentication interface overviewExternal authentication interface process flowExternal authentication interface configurationExternal authentication interface HTTP header referenceRequest caching with external authentication interfacePost-authentication redirection with external authentication interfaceSession handling with external authentication interfaceAuthentication strength level with external authentication interfaceReauthentication with external authentication interfaceLogin page and macro support with external authentication interfaceSetting a client-specific session cache entry lifetime valueSetting a client-specific session cache entry inactivity timeout value

Use of external authentication interface with existing WebSEAL features

This section contains the following topics:

Request caching with external authentication interface

Post-authentication redirection with external authentication interface

Session handling with external authentication interface

Authentication strength level with external authentication interface

Reauthentication with external authentication interface

Login page and macro support with external authentication interface

Setting a client-specific session cache entry lifetime value

Setting a client-specific session cache entry inactivity timeout value

Parent topic: External authentication interface

Related concepts:

External authentication interface overview

External authentication interface process flow

External authentication interface configuration

External authentication interface HTTP header reference

Request caching with external authentication interfaceRequest caching with external authentication interfaceexternal authentication interfacerequest cachingrequestcachingServer-side request caching occurs for external authentication interface authentication when WebSEAL returns a login prompt as a consequence of:An unauthenticated user requesting a protected resource.An authenticated user requesting a resource protected by reauthentication.An authenticated user requesting a resource protected by authentication strength policy (step-up).When one of these events occurs, WebSEAL caches the initial request. WebSEAL retains the cached request during any authentication interaction with the external authentication application. WebSEAL reprocesses the cached request only when an authentication has succeeded. No modifications are necessary to support standard request caching for authentication using the external authentication interface. See Server-side request caching.Use of external authentication interface with existing WebSEAL features

Request caching with external authentication interface

Server-side request caching occurs for external authentication interface authentication when WebSEAL returns a login prompt as a consequence of:

An unauthenticated user requesting a protected resource.

An authenticated user requesting a resource protected by reauthentication.

An authenticated user requesting a resource protected by authentication strength policy (step-up).

When one of these events occurs, WebSEAL caches the initial request. WebSEAL retains the cached request during any authentication interaction with the external authentication application. WebSEAL reprocesses the cached request only when an authentication has succeeded.

No modifications are necessary to support standard request caching for authentication using the external authentication interface.

See Server-side request caching.

Parent topic: Use of external authentication interface with existing WebSEAL features

Post-authentication redirection with external authentication interfacePost-authentication redirection with external authentication interfaceexternal authentication interfacepost-authentication redirectionpost-authentication redirectionUse of external authentication interface with existing WebSEAL featuresWebSEAL-specified (automatic) redirectionExternal authentication interface-specified redirection

Post-authentication redirection with external authentication interface

WebSEAL-specified (automatic) redirection

External authentication interface-specified redirection

Parent topic: Use of external authentication interface with existing WebSEAL features

WebSEAL-specified (automatic) redirectionWebSEAL-specified (automatic) redirectionexternal authentication interfaceWebSEAL-specified (automatic) redirectionredirectionWebSEAL-specifiedautomaticWebSEAL-specifiedredirect stanza entryIf automatic redirection during user login is enabled through WebSEAL, clients are redirected to the specified resource upon successful external authentication interface authentication.[enable-redirects] redirect = ext-auth-interfaceSee Automatic redirection after authentication.Post-authentication redirection with external authentication interface

WebSEAL-specified (automatic) redirection

If automatic redirection during user login is enabled through WebSEAL, clients are redirected to the specified resource upon successful external authentication interface authentication.

[enable-redirects]
redirect = ext-auth-interface

See Automatic redirection after authentication.

Parent topic: Post-authentication redirection with external authentication interface

External authentication interface-specified redirectionExternal authentication interface-specified redirectionexternal authentication interfacespecified redirectionredirectionexternal authenticationeai-redir-url-header stanza entryThe external authentication application can be written to send a special HTTP header in the authentication response that specifies a redirection URL. Upon successful authentication, the client is redirected to this URL.This optional header is configured in the same manner as other special external authentication interface headers (see HTTP header names for authentication dataYou must specify the names of the HTTP headers that contain the authentication data returned from the external authentication application. ). For example:[eai] eai-redir-url-header = am-eai-redir-urlPost-authentication redirection with external authentication interface

External authentication interface-specified redirection

The external authentication application can be written to send a special HTTP header in the authentication response that specifies a redirection URL. Upon successful authentication, the client is redirected to this URL.

This optional header is configured in the same manner as other special external authentication interface headers (see HTTP header names for authentication data).

For example:

[eai]
eai-redir-url-header = am-eai-redir-url

Parent topic: Post-authentication redirection with external authentication interface

Session handling with external authentication interfaceSession handling with external authentication interfaceexternal authentication interfacesession handlingsession handlingThe existing options for maintaining sessions, handling session cookies, and configuring session cache parameters apply for external authentication interface authentication.Use of external authentication interface with existing WebSEAL features

Session handling with external authentication interface

The existing options for maintaining sessions, handling session cookies, and configuring session cache parameters apply for external authentication interface authentication.

Parent topic: Use of external authentication interface with existing WebSEAL features

Authentication strength level with external authentication interfaceAuthentication strength level with external authentication interfaceexternal authentication interfacestrength leveleai-auth-level-header stanza entryAuthentication strength policy (step-up authentication) is supported for external authentication interface authentication.[authentication-levels] level = ext-auth-interfaceSee Authentication strength policy (step-up).You can associate an authentication strength level with an authentication performed by an external authentication interface module. An optional HTTP header can be returned by the external authentication interface module to specify this authentication level.This header is configured in the same manner as other special external authentication interface headers (see HTTP header names for authentication dataYou must specify the names of the HTTP headers that contain the authentication data returned from the external authentication application. ). For example:[eai] eai-auth-level-header = am-eai-auth-levelThe authentication strength level value becomes an attribute of the identity structure and the resulting credential. The authentication strength level attribute allows you to implement step-up authentication functionality by operating multiple external authentication interface authentication modules on a single external authentication interface server. Each module can process a different authentication method.If the authentication strength level does not exist or contains an empty value, the default mechanisms for assigning an authentication level are used. You must modify the standard WebSEAL login pages appropriately if you enable step-up authentication with external authentication interface authentication. See Login page and macro support with external authentication interface.Use of external authentication interface with existing WebSEAL features

Authentication strength level with external authentication interface

Authentication strength policy (step-up authentication) is supported for external authentication interface authentication.

[authentication-levels]
level = ext-auth-interface

See Authentication strength policy (step-up).

You can associate an authentication strength level with an authentication performed by an external authentication interface module. An optional HTTP header can be returned by the external authentication interface module to specify this authentication level.

This header is configured in the same manner as other special external authentication interface headers (see HTTP header names for authentication data).

For example:

[eai]
eai-auth-level-header = am-eai-auth-level

The authentication strength level value becomes an attribute of the identity structure and the resulting credential. The authentication strength level attribute allows you to implement step-up authentication functionality by operating multiple external authentication interface authentication modules on a single external authentication interface server. Each module can process a different authentication method.

If the authentication strength level does not exist or contains an empty value, the default mechanisms for assigning an authentication level are used.

You must modify the standard WebSEAL login pages appropriately if you enable step-up authentication with external authentication interface authentication. See Login page and macro support with external authentication interface.

Parent topic: Use of external authentication interface with existing WebSEAL features

Reauthentication with external authentication interfaceReauthentication with external authentication interfaceexternal authentication interfacereauthenticationreauthenticationexternal authentication interfaceReauthentication is supported for external authentication interface authentication.Reauthentication requires that the method used by the client to reauthenticate is the same as that used by the client to initially authenticate. When WebSEAL receives the authentication response from the custom external authentication application, a check is performed (as with other reauthentication processing) to ensure:The authentication method used is the same as that used to create the initial credentialThe user name matchesAny external authentication interface-specified authentication level is verified to match the existing levelYou must modify the standard WebSEAL login pages appropriately if you enable reauthentication with external authentication interface authentication. See Login page and macro support with external authentication interface.Use of external authentication interface with existing WebSEAL features

Reauthentication with external authentication interface

Reauthentication is supported for external authentication interface authentication.

Reauthentication requires that the method used by the client to reauthenticate is the same as that used by the client to initially authenticate. When WebSEAL receives the authentication response from the custom external authentication application, a check is performed (as with other reauthentication processing) to ensure:

The authentication method used is the same as that used to create the initial credential

The user name matches

Any external authentication interface-specified authentication level is verified to match the existing level

You must modify the standard WebSEAL login pages appropriately if you enable reauthentication with external authentication interface authentication. See Login page and macro support with external authentication interface.

Parent topic: Use of external authentication interface with existing WebSEAL features

Login page and macro support with external authentication interfaceLogin page and macro support with external authentication interfaceexternal authentication interfacelogin pagemacro supportEAIAUTHN macroAUTHNLEVEL macroThe WebSEAL login pages can be modified to cause a redirection to the external authentication interface server to perform the authentication, or to contain a link (or button) that a user can click to initiate the authentication exchange with the external authentication interface server. This modified login page is required if you enable reauthentication or step-up to external authentication interface.An external authentication interface-specific macro (%EAIAUTHN%) is used to selectively add or mask sections from the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.To facilitate the passing of the required authentication level for step-up as an argument in a query string, WebSEAL passes another macro (%AUTHNLEVEL%) to the stepuplogin.html login form.Neither of these macros are present in the default login forms. The macros must be manually added.You can also implement local response redirection to handle server responses to client requests.Use of external authentication interface with existing WebSEAL features

Login page and macro support with external authentication interface

The WebSEAL login pages can be modified to cause a redirection to the external authentication interface server to perform the authentication, or to contain a link (or button) that a user can click to initiate the authentication exchange with the external authentication interface server. This modified login page is required if you enable reauthentication or step-up to external authentication interface.

An external authentication interface-specific macro (%EAIAUTHN%) is used to selectively add or mask sections from the certlogin.html and stepuplogin.html login forms. When the authentication method (indicated by the macro name) is valid, the section in the form governed by the macro is displayed. When the authentication method is not valid, the macro is replaced by a start comment delimiter (<!--). All subsequent information in the form is commented out until a comment closing delimiter (-->) is reached.

To facilitate the passing of the required authentication level for step-up as an argument in a query string, WebSEAL passes another macro (%AUTHNLEVEL%) to the stepuplogin.html login form.

Neither of these macros are present in the default login forms. The macros must be manually added.

You can also implement local response redirection to handle server responses to client requests.

Parent topic: Use of external authentication interface with existing WebSEAL features

Setting a client-specific session cache entry lifetime valueSetting a client-specific session cache entry lifetime valuetimeoutstanzasession cachelifetime timeout (per-user setting)WebSEAL session cachelifetime timeout (per-user setting)session timeoutsession expirationFederated Identity Manager (TFIM) supportsession cache entry lifetime (per-user setting)TFIM (Federated Identity Manager) supportsession cache entry lifetime (per-user setting)The timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, globally sets the maximum lifetime timeout value for all client session information stored in the WebSEAL session cache. You can override this global lifetime value with a per-client lifetime value that is provided as a header in the authentication response from an external authentication interface service. This value is extracted by WebSEAL and stored as an extended attribute in the user's credential. WebSEAL receives the client-specific timeout information as the value of a header in the authentication response from the external authentication interface. WebSEAL uses the value of that header to set the lifetime timeout of the new session cache entry for that client. This value overrides the value of the timeout stanza entry. The value must represent an absolute time expressed as the number of seconds since 00:00:00 UTC, January 1, 1970. The output of the UNIX time () function, for example, represents the correct format of this absolute time value. The following steps summarize the necessary configuration for setting a client-specific cache entry lifetime timeout value:Configure the custom external authentication interface program to provide, in its authentication response, an HTTP header containing the session cache lifetime timeout value appropriate for that client. The required name of this header is:am_eai_xattr_session_lifetimeNote: The name of this particular header is not configurable.For example:am_eai_xattr_session_lifetime:1129225478Configure the custom external authentication interface program to additionally provide an HTTP header that specifies a comma-delimited list of HTTP header names that contain extended attribute values. You must configure WebSEAL to look for this header name (see step 4). The default name for this header is am-eai-xattrs. (The am-eai-xattrs header name is configurable.)Configure the custom external authentication interface program to include the am_eai_xattr_session_lifetime header name as a value to the am-eai-xattrs header. For example:am-eai-xattrs: am_eai_xattr_session_lifetimeUse the [eai] stanza of the WebSEAL configuration file to specify the names of the HTTP headers that contain authentication data returned from the external authentication interface server. In the [eai] stanza, ensure that WebSEAL looks for the am-eai-xattrs header name: [eai]eai-xattrs-header = am-eai-xattrsNote: Header names used for the external authentication interface can be customized. Ensure that the custom external authentication interface module is written to use the header names as configured.If the am_eai_xattr_inactive_timeout header is present in a flagged response from the external authentication interface, WebSEAL adds the value to the user’s credential as an extended attribute. The entry in the credential for this example appears as follows:am_eai_xattr_session_lifetime:1129225478After the credential is successfully built, WebSEAL creates and entry in the session cache for that client and uses the value of the extended attribute to set the inactivity timeout for that client’s session cache entry.If the am_eai_xattr_session_lifetime header is not supplied. WebSEAL uses the default timeout value provided by the timeout stanza entry.Example:For example, in a Tivoli Federated Identity Manager environment, there is an optional element of a Liberty authentication response that is used by an identity provider to dictate to a service provider the duration of a user’s session at the service provider.By modifying the external authentication interface used to authenticate users, a single attribute (the value derived from the identity provider token) can be returned to WebSEAL and used to set the lifetime timeout of session cache entry for that user. The service provider should always request a new single signon interaction with the identity provider once this cache entry lifetime value has expired.See also: Customized responses for old session cookiesCache entry lifetime timeout valueSetting a client-specific session cache entry inactivity timeout valueUse of external authentication interface with existing WebSEAL featuresWebSEAL session cache configuration

Setting a client-specific session cache entry lifetime value

About this task

The timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, globally sets the maximum lifetime timeout value for all client session information stored in the WebSEAL session cache. You can override this global lifetime value with a per-client lifetime value that is provided as a header in the authentication response from an external authentication interface service. This value is extracted by WebSEAL and stored as an extended attribute in the user's credential.

WebSEAL receives the client-specific timeout information as the value of a header in the authentication response from the external authentication interface. WebSEAL uses the value of that header to set the lifetime timeout of the new session cache entry for that client. This value overrides the value of the timeout stanza entry.

The value must represent an absolute time expressed as the number of seconds since 00:00:00 UTC, January 1, 1970. The output of the UNIX time () function, for example, represents the correct format of this absolute time value.

The following steps summarize the necessary configuration for setting a client-specific cache entry lifetime timeout value:

Procedure

Configure the custom external authentication interface program to provide, in its authentication response, an HTTP header containing the session cache lifetime timeout value appropriate for that client. The required name of this header is:

am_eai_xattr_session_lifetime

Note: The name of this particular header is not configurable.
For example:

am_eai_xattr_session_lifetime:1129225478

Configure the custom external authentication interface program to additionally provide an HTTP header that specifies a comma-delimited list of HTTP header names that contain extended attribute values.
You must configure WebSEAL to look for this header name (see step 4). The default name for this header is am-eai-xattrs. (The am-eai-xattrs header name is configurable.)

Configure the custom external authentication interface program to include the am_eai_xattr_session_lifetime header name as a value to the am-eai-xattrs header. For example:
am-eai-xattrs: am_eai_xattr_session_lifetime

Use the [eai] stanza of the WebSEAL configuration file to specify the names of the HTTP headers that contain authentication data returned from the external authentication interface server.
In the [eai] stanza, ensure that WebSEAL looks for the am-eai-xattrs header name:
[eai]
eai-xattrs-header = am-eai-xattrs

Note: Header names used for the external authentication interface can be customized. Ensure that the custom external authentication interface module is written to use the header names as configured.

Results

If the am_eai_xattr_inactive_timeout header is present in a flagged response from the external authentication interface, WebSEAL adds the value to the user’s credential as an extended attribute. The entry in the credential for this example appears as follows:
am_eai_xattr_session_lifetime:1129225478

After the credential is successfully built, WebSEAL creates and entry in the session cache for that client and uses the value of the extended attribute to set the inactivity timeout for that client’s session cache entry.

If the am_eai_xattr_session_lifetime header is not supplied. WebSEAL uses the default timeout value provided by the timeout stanza entry.

Example:

For example, in a Tivoli® Federated Identity Manager environment, there is an optional element of a Liberty authentication response that is used by an identity provider to dictate to a service provider the duration of a user’s session at the service provider.

By modifying the external authentication interface used to authenticate users, a single attribute (the value derived from the identity provider token) can be returned to WebSEAL and used to set the lifetime timeout of session cache entry for that user. The service provider should always request a new single signon interaction with the identity provider once this cache entry lifetime value has expired.

See also:

Customized responses for old session cookies

Cache entry lifetime timeout value

Setting a client-specific session cache entry inactivity timeout value

Parent topic: Use of external authentication interface with existing WebSEAL features

Parent topic: WebSEAL session cache configuration

Setting a client-specific session cache entry inactivity timeout valueSetting a client-specific session cache entry inactivity timeout valueinactivity timeout stanza entrysession stanzasession cacheinactivity timeout (per-user setting)WebSEAL session cacheinactivity timeout (per-user setting)session timeoutsession expirationFederated Identity Manager (TFIM) supportsession cache entry inactivity (per-user setting)TFIM (Federated Identity Manager) supportsession cache entry inactivity (per-user setting)The inactive-timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, globally sets the maximum lifetime of inactive entries contained within the WebSEAL session cache. You can override this global inactivity timeout value with a per-client value that is provided as a header in the authentication response from an external authentication interface service. This value is extracted by WebSEAL and stored as an extended attribute in the user's credential.WebSEAL receives the client-specific inactivity timeout information as the value of a header in the authentication response from the external authentication interface. WebSEAL uses the value of that header to set the inactivity timeout of the new session cache entry for that client. This value overrides the value of the inactive-timeout stanza entry.The value represents the maximum number of seconds that the session can be inactive before it is removed from the WebSEAL session cache.The following steps summarize the necessary configuration for setting a client-specific cache entry inactivity timeout value:Configure the custom external authentication interface program to provide, in its authentication response, an HTTP header containing the session cache inactivity timeout value appropriate for that client. The required name of this header is am_eai_xattr_session_inactive_timeoutNote: The name of this particular header is not configurable. For example: am_eai_xattr_session_inactive_timeout:120Configure the custom external authentication interface program to additionally provide an HTTP header that specifies a comma-delimited list of HTTP header names that contain extended attribute values. You must configure WebSEAL to look for this header name (see step 4). The default name for this header is am-eai-xattrs. (The am-eai-xattrs header name is configurable.)Configure the custom external authentication interface program to include the am_eai_xattr_session_inactive_timeout header name as a value to the am-eai-xattrs header. For example: am-eai-xattrs: am_eai_xattr_session_inactive_timeoutUse the [eai] stanza of the WebSEAL configuration file to specify the names of the HTTP headers that contain authentication data returned from the external authentication interface server. In the [eai] stanza, ensure that WebSEAL looks for the am-eai-xattrs header name:[eai] eai-xattrs-header = am-eai-xattrsNote: Header names used for the external authentication interface can be customized. Ensure that the custom external authentication interface module is written to use the header names as configured. If the am_eai_xattr_session_inactive_timeout header is present in a flagged response from the external authentication interface, WebSEAL adds the value to the user's credential as an extended attribute. The entry in the credential for this example appears as follows: am_eai_xattr_session_inactive_timeout:120 After the credential is successfully built, WebSEAL creates an entry in the session cache for that client and uses the value of the extended attribute to set the inactivity timeout for that client's session cache entry. If the am_eai_xattr_session_inactive_timeout header is not supplied, WebSEAL uses the default timeout value provided by the inactive-timeout stanza entry. See also: Customized responses for old session cookiesCache entry lifetime timeout valueSetting a client-specific session cache entry lifetime valueUse of external authentication interface with existing WebSEAL features

Setting a client-specific session cache entry inactivity timeout value

About this task

The inactive-timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, globally sets the maximum lifetime of inactive entries contained within the WebSEAL session cache. You can override this global inactivity timeout value with a per-client value that is provided as a header in the authentication response from an external authentication interface service. This value is extracted by WebSEAL and stored as an extended attribute in the user's credential.

WebSEAL receives the client-specific inactivity timeout information as the value of a header in the authentication response from the external authentication interface. WebSEAL uses the value of that header to set the inactivity timeout of the new session cache entry for that client. This value overrides the value of the inactive-timeout stanza entry.

The value represents the maximum number of seconds that the session can be inactive before it is removed from the WebSEAL session cache.

The following steps summarize the necessary configuration for setting a client-specific cache entry inactivity timeout value:

Procedure

Configure the custom external authentication interface program to provide, in its authentication response, an HTTP header containing the session cache inactivity timeout value appropriate for that client. The required name of this header is

am_eai_xattr_session_inactive_timeout

Note: The name of this particular header is not configurable. For example:

am_eai_xattr_session_inactive_timeout:120

Configure the custom external authentication interface program to additionally provide an HTTP header that specifies a comma-delimited list of HTTP header names that contain extended attribute values.

You must configure WebSEAL to look for this header name (see step 4). The default name for this header is am-eai-xattrs. (The am-eai-xattrs header name is configurable.)

Configure the custom external authentication interface program to include the am_eai_xattr_session_inactive_timeout header name as a value to the am-eai-xattrs header. For example:

am-eai-xattrs: am_eai_xattr_session_inactive_timeout

Use the [eai] stanza of the WebSEAL configuration file to specify the names of the HTTP headers that contain authentication data returned from the external authentication interface server.
In the [eai] stanza, ensure that WebSEAL looks for the am-eai-xattrs header name:

[eai]
eai-xattrs-header = am-eai-xattrs

Note: Header names used for the external authentication interface can be customized. Ensure that the custom external authentication interface module is written to use the header names as configured.

Results

If the am_eai_xattr_session_inactive_timeout header is present in a flagged response from the external authentication interface, WebSEAL adds the value to the user's credential as an extended attribute. The entry in the credential for this example appears as follows:

am_eai_xattr_session_inactive_timeout:120

After the credential is successfully built, WebSEAL creates an entry in the session cache for that client and uses the value of the extended attribute to set the inactivity timeout for that client's session cache entry.

If the am_eai_xattr_session_inactive_timeout header is not supplied, WebSEAL uses the default timeout value provided by the inactive-timeout stanza entry.

See also:

Customized responses for old session cookies

Cache entry lifetime timeout value

Setting a client-specific session cache entry lifetime value

Parent topic: Use of external authentication interface with existing WebSEAL features

Session StateSession StateWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Session state overviewSession cache configurationFailover solutionsUse the failover cookie solution to maintain session state in clustered environments.Session state in non-clustered environments

Session State

Session state overview

Session cache configuration

Failover solutions
Use the failover cookie solution to maintain session state in clustered environments.

Session state in non-clustered environments

Parent topic: Web Reverse Proxy configuration

Session state overviewSession state overviewsession stateoverviewThis chapter discusses basic concepts of how WebSEAL maintains session state.Topic Index:Session StateSession state conceptsSupported session ID data typesInformation retrieved from a client requestValidation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.WebSEAL session cache structureDeployment considerations for clustered environmentsOptions for handling failover in clustered environments

Session state overview

This chapter discusses basic concepts of how WebSEAL maintains session state.

Topic Index:

Session state concepts

Supported session ID data types

Information retrieved from a client request

Validation of the client identifier for a session
You can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.

WebSEAL session cache structure

Deployment considerations for clustered environments

Options for handling failover in clustered environments

Parent topic: Session State

Session state concepts Session state concepts authenticationsupported session ID typessession IDsupported data typesWebSEALsession stateoverviewsession keyWebSEALA client/server session is a series of related interactions between a single client and a server that take place over a period of time. With an established session, the server can identify the client associated with each request, and has the ability to remember—over numerous requests—a specific client. Without an established session, the communication between the client and the server must be renegotiated for each subsequent request. Session state information improves performance in the following ways:For client authentication methods such as basic authentication, where authentication data is included with every request to the WebSEAL server, session state information eliminates the need to validate the user name and password with every request.For other client authentication methods that require prompting the user to log in, session state information eliminates the need to prompt the user to log in with every request to the WebSEAL server. The client can log in once and make numerous requests without performing a separate login for each request.Session state overviewSupported session ID data typesInformation retrieved from a client requestValidation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.WebSEAL session cache structureDeployment considerations for clustered environmentsOptions for handling failover in clustered environments

Session state concepts

A client/server session is a series of related interactions between a single client and a server that take place over a period of time. With an established session, the server can identify the client associated with each request, and has the ability to remember—over numerous requests—a specific client.

Without an established session, the communication between the client and the server must be renegotiated for each subsequent request. Session state information improves performance in the following ways:

For client authentication methods such as basic authentication, where authentication data is included with every request to the WebSEAL server, session state information eliminates the need to validate the user name and password with every request.

For other client authentication methods that require prompting the user to log in, session state information eliminates the need to prompt the user to log in with every request to the WebSEAL server. The client can log in once and make numerous requests without performing a separate login for each request.

Parent topic: Session state overview

Related concepts:

Supported session ID data types

Information retrieved from a client request

Validation of the client identifier for a session

WebSEAL session cache structure

Deployment considerations for clustered environments

Options for handling failover in clustered environments

Supported session ID data typesSupported session ID data typessession statesupported session ID data typessession IDsupported data typesWebSEAL can maintain session state with both HTTP and HTTPS clients. The SSL transport protocol is specifically designed to provide a session ID to maintain session state information. In contrast, HTTP is a "stateless" protocol and does not provide any means of distinguishing one request from another. (HTTP communication can be encapsulated over SSL to become HTTPS.)However, WebSEAL must often handle HTTP communication from unauthenticated clients. There are also times when the SSL session ID is not an appropriate solution. To maintain session state with clients over HTTP or HTTPS, WebSEAL can use one of several data types to provide a client-identifying session key, known as the WebSEAL session ID. WebSEAL maintains the specific client identity and session information in a session cache. Each session cache entry is indexed by a session key (the WebSEAL session ID). The following supported data types can provide the session key used by WebSEAL to maintain session state with a client: SSL session ID (defined by the SSL protocol)Server-specific session cookieWhen WebSEAL examines a client request, it searches for the session key in the order specified in this list.Session state overviewSession state conceptsInformation retrieved from a client requestValidation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.WebSEAL session cache structureDeployment considerations for clustered environmentsOptions for handling failover in clustered environments

Supported session ID data types

WebSEAL can maintain session state with both HTTP and HTTPS clients. The SSL transport protocol is specifically designed to provide a session ID to maintain session state information. In contrast, HTTP is a "stateless" protocol and does not provide any means of distinguishing one request from another. (HTTP communication can be encapsulated over SSL to become HTTPS.)

However, WebSEAL must often handle HTTP communication from unauthenticated clients. There are also times when the SSL session ID is not an appropriate solution.

To maintain session state with clients over HTTP or HTTPS, WebSEAL can use one of several data types to provide a client-identifying session key, known as the WebSEAL session ID.

WebSEAL maintains the specific client identity and session information in a session cache. Each session cache entry is indexed by a session key (the WebSEAL session ID).

The following supported data types can provide the session key used by WebSEAL to maintain session state with a client:

SSL session ID (defined by the SSL protocol)

Server-specific session cookie

When WebSEAL examines a client request, it searches for the session key in the order specified in this list.

Parent topic: Session state overview

Related concepts:

Session state concepts

Information retrieved from a client request

Validation of the client identifier for a session

WebSEAL session cache structure

Deployment considerations for clustered environments

Options for handling failover in clustered environments

Information retrieved from a client requestInformation retrieved from a client requestrequestsexamining clientsession keysession keyexamine client requestWebSEALsession IDWebSEALWebSEALsession IDSession identification is the process of examining the information associated with an HTTP request (such as the URL, HTTP headers and cookies, IP address, and SSL session ID) to retrieve a session ID that can be used to associate a particular client with the request.WebSEAL examines a client request for the following information: Session key A session key is information that identifies a specific connection between the client and the WebSEAL server. The session key is stored with the client and accompanies subsequent requests by that client. It is used to re-identify the client session to the WebSEAL server and avoid the overhead of establishing a new session for each request. The session key is a locator index to the associated session data stored in the WebSEAL server session cache. The session key is also known as the WebSEAL session ID.Authentication data Authentication data is information from the client that identifies the client to the WebSEAL server. Examples of authentication data types include client-side certificates, passwords, and token codes.When WebSEAL receives a client request, WebSEAL always looks for the session key and associated session data first, followed by authentication data.Session state overviewSession state conceptsSupported session ID data typesValidation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.WebSEAL session cache structureDeployment considerations for clustered environmentsOptions for handling failover in clustered environments

Information retrieved from a client request

Session identification is the process of examining the information associated with an HTTP request (such as the URL, HTTP headers and cookies, IP address, and SSL session ID) to retrieve a session ID that can be used to associate a particular client with the request.

WebSEAL examines a client request for the following information:

Session key

A session key is information that identifies a specific connection between the client and the WebSEAL server. The session key is stored with the client and accompanies subsequent requests by that client. It is used to re-identify the client session to the WebSEAL server and avoid the overhead of establishing a new session for each request. The session key is a locator index to the associated session data stored in the WebSEAL server session cache. The session key is also known as the WebSEAL session ID.

Authentication data

Authentication data is information from the client that identifies the client to the WebSEAL server. Examples of authentication data types include client-side certificates, passwords, and token codes.

When WebSEAL receives a client request, WebSEAL always looks for the session key and associated session data first, followed by authentication data.

Parent topic: Session state overview

Related concepts:

Session state concepts

Supported session ID data types

Validation of the client identifier for a session

WebSEAL session cache structure

Deployment considerations for clustered environments

Options for handling failover in clustered environments

Validation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.A client identifier can be the client's IP address or the contents of a configured HTTP header. The client identifier is associated with the session when the session is first established. WebSEAL then checks the client identifier on subsequent requests to ensure that a different client is not attempting to access the session.If the client is able to connect directly to the WebSEAL server, the IP address of the client can be used to identify the client. However, if the WebSEAL traffic is routed through a network terminating firewall, the contents of an HTTP header (for example, the X-Forwarded-For header) can be used to identify the client. You can configure the client identifier to be validated for a session with the client-identifier stanza entry. This identifier is added to the credential as the client_identifier attribute and is validated on subsequent requests to ensure that the client does not change. See client-identifierUse this entry to designate the client identifier for the session. for more information.If failover cookies are used, add the client_identifier credential attribute to the failover cookie by modifying the [failover-add-attributes] and [failover-restore-attributes] stanzas so that the client identifier can persist across a failover event. This step prevents an attacker from establishing a new session from a different client with the failover cookie.Session state overviewSession state conceptsSupported session ID data typesInformation retrieved from a client requestWebSEAL session cache structureDeployment considerations for clustered environmentsOptions for handling failover in clustered environments

Validation of the client identifier for a session

You can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.

A client identifier can be the client's IP address or the contents of a configured HTTP header. The client identifier is associated with the session when the session is first established. WebSEAL then checks the client identifier on subsequent requests to ensure that a different client is not attempting to access the session.

If the client is able to connect directly to the WebSEAL server, the IP address of the client can be used to identify the client. However, if the WebSEAL traffic is routed through a network terminating firewall, the contents of an HTTP header (for example, the X-Forwarded-For header) can be used to identify the client.

You can configure the client identifier to be validated for a session with the client-identifier stanza entry. This identifier is added to the credential as the client_identifier attribute and is validated on subsequent requests to ensure that the client does not change. See client-identifier for more information.

Note: If failover cookies are used, add the client_identifier credential attribute to the failover cookie by modifying the [failover-add-attributes] and [failover-restore-attributes] stanzas so that the client identifier can persist across a failover event. This step prevents an attacker from establishing a new session from a different client with the failover cookie.

Parent topic: Session state overview

Related concepts:

Session state concepts

Supported session ID data types

Information retrieved from a client request

WebSEAL session cache structure

Deployment considerations for clustered environments

Options for handling failover in clustered environments

WebSEAL session cache structure WebSEAL session cache structure session cacheoverviewstructureWebSEAL session cacheWebSEAL session cachestructuresession stateWebSEAL session cachecredentialsdefinitionThe WebSEAL session cache can be represented as an internal table where WebSEAL stores information about all sessions established by authenticated users. The session key, stored with the client, is a locator index to the associated session data stored in the WebSEAL session cache.WebSEAL session cacheWebSEAL session cacheEach user session is represented by an entry in the cache table.Each cache entry contains the following types of information:Session key The session key (the WebSEAL session ID) is a unique identifier, or key, that is sent with each request made by that user. The session key identifies the specific cache entry for that user. Cache data The most important data stored in the cache entry is the user credential. The credential is required whenever the user requests protected resources. The authorization service uses the credential information to permit or deny access to the resource. WebSEAL can mark, or "flag", a cache entry to support certain functionality. For example, when session inactivity reauthentication is enabled, a cache entry is "flagged" when the session inactivity value has expired.Timestamps The creation timestamp for the cache entry becomes the reference point for the session lifetime value. The "last active" timestamp for the cache entry becomes the reference point for the session inactivity timer.The user credential is an encoded opaque data structure representing the authenticated user. The credential contents can include:User nameGroup membershipsExtended attributes Extended attributes allow you to store customized data in the user credential. Session state overviewSession state conceptsSupported session ID data typesInformation retrieved from a client requestValidation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.Deployment considerations for clustered environmentsOptions for handling failover in clustered environments

WebSEAL session cache structure

The WebSEAL session cache can be represented as an internal table where WebSEAL stores information about all sessions established by authenticated users. The session key, stored with the client, is a locator index to the associated session data stored in the WebSEAL session cache.

Figure 19. WebSEAL session cache

Each user session is represented by an entry in the cache table.

Each cache entry contains the following types of information:

Session key

The session key (the WebSEAL session ID) is a unique identifier, or key, that is sent with each request made by that user. The session key identifies the specific cache entry for that user.

Cache data

The most important data stored in the cache entry is the user credential. The credential is required whenever the user requests protected resources. The authorization service uses the credential information to permit or deny access to the resource.

WebSEAL can mark, or "flag", a cache entry to support certain functionality. For example, when session inactivity reauthentication is enabled, a cache entry is "flagged" when the session inactivity value has expired.

Timestamps

The creation timestamp for the cache entry becomes the reference point for the session lifetime value. The "last active" timestamp for the cache entry becomes the reference point for the session inactivity timer.

The user credential is an encoded opaque data structure representing the authenticated user. The credential contents can include:

User name

Group memberships

Extended attributes

Extended attributes allow you to store customized data in the user credential.

Parent topic: Session state overview

Related concepts:

Session state concepts

Supported session ID data types

Information retrieved from a client request

Validation of the client identifier for a session

Deployment considerations for clustered environments

Options for handling failover in clustered environments

Deployment considerations for clustered environmentsDeployment considerations for clustered environmentssession statedeployment considerations for clustered environmentsclustersdeployment considerationserver clustersdeployment considerations for clustered environmentsConsider the following topics when you deploy multiple replica WebSEAL servers in a clustered environment for fault-tolerance or performance reasons:Session state overviewSession state conceptsSupported session ID data typesInformation retrieved from a client requestValidation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.WebSEAL session cache structureOptions for handling failover in clustered environmentsConsistent configuration on all WebSEAL replica serversTo maintain a consistent user experience regardless of which WebSEAL server a client accesses, all WebSEAL replica servers must be identically configured. Client-to-server session affinity at the load balancerWhenever possible, load balancers should be configured to maintain session affinity. Failover to a new masterFailover from one WebSEAL server to anotherWhen clients failover from one WebSEAL server to another, there must be some mechanism for the new WebSEAL server to identify the client.

Deployment considerations for clustered environments

Consider the following topics when you deploy multiple replica WebSEAL servers in a clustered environment for fault-tolerance or performance reasons:

Consistent configuration on all WebSEAL replica servers
To maintain a consistent user experience regardless of which WebSEAL server a client accesses, all WebSEAL replica servers must be identically configured.

Client-to-server session affinity at the load balancer
Whenever possible, load balancers should be configured to maintain session affinity.

Failover to a new master

Failover from one WebSEAL server to another
When clients failover from one WebSEAL server to another, there must be some mechanism for the new WebSEAL server to identify the client.

Parent topic: Session state overview

Related concepts:

Session state concepts

Supported session ID data types

Information retrieved from a client request

Validation of the client identifier for a session

WebSEAL session cache structure

Options for handling failover in clustered environments

Consistent configuration on all WebSEAL replica serversConsistent configuration on all WebSEAL replica serversTo maintain a consistent user experience regardless of which WebSEAL server a client accesses, all WebSEAL replica servers must be identically configured. WebSEALreplica serversFor example, if a junction exists on one WebSEAL server and not on another, clients can receive errors when they access the WebSEAL server that does not have the proper junction definition. All configuration (for example, dynamic URLs, junction mapping table, authentication, and authorization) must be identical across all the WebSEAL servers in the cluster. The server-name configuration option in the [server] stanza of the WebSEAL configuration file can be used to force all WebSEAL servers to perform authorization checks on the same protected object space. This configuration allows you to apply ACLs and POPs only once. Most other WebSEAL configuration options must be set individually for every server in the cluster.Deployment considerations for clustered environments

Consistent configuration on all WebSEAL replica servers

To maintain a consistent user experience regardless of which WebSEAL server a client accesses, all WebSEAL replica servers must be identically configured.

For example, if a junction exists on one WebSEAL server and not on another, clients can receive errors when they access the WebSEAL server that does not have the proper junction definition. All configuration (for example, dynamic URLs, junction mapping table, authentication, and authorization) must be identical across all the WebSEAL servers in the cluster.

The server-name configuration option in the [server] stanza of the WebSEAL configuration file can be used to force all WebSEAL servers to perform authorization checks on the same protected object space. This configuration allows you to apply ACLs and POPs only once. Most other WebSEAL configuration options must be set individually for every server in the cluster.

Parent topic: Deployment considerations for clustered environments

Client-to-server session affinity at the load balancerClient-to-server session affinity at the load balancerWhenever possible, load balancers should be configured to maintain session affinity. client-to-server session affinityload balancersload balancersclient-to-server session affinitySession affinity provides improved performance, improved user experience, and simplifies WebSEAL configuration.Deployment considerations for clustered environments

Client-to-server session affinity at the load balancer

Whenever possible, load balancers should be configured to maintain session affinity.

Session affinity provides improved performance, improved user experience, and simplifies WebSEAL configuration.

Parent topic: Deployment considerations for clustered environments

Failover to a new masterFailover to a new masterfailovernew mastermastersIf the cluster master becomes unavailable for an extended period, re-configure the slaves to use a different master. To configure the new master, modify the master-name configuration entry in the [cluster] stanza for each slave WebSEAL server. Ensure that the newly designated master has the most up-to-date configuration.Deployment considerations for clustered environments

Failover to a new master

If the cluster master becomes unavailable for an extended period, re-configure the slaves to use a different master. To configure the new master, modify the master-name configuration entry in the [cluster] stanza for each slave WebSEAL server. Ensure that the newly designated master has the most up-to-date configuration.

Parent topic: Deployment considerations for clustered environments

Failover from one WebSEAL server to anotherFailover from one WebSEAL server to anotherWhen clients failover from one WebSEAL server to another, there must be some mechanism for the new WebSEAL server to identify the client. failoverfrom one WebSEAL server to anotherWebSEAL serversfailoverSecurity architects must choose from several possible options for handling failover events. Each option involves different trade-offs in complexity, security, and performance. In addition, some options for handling failover events can provide additional functionality, such as single-signon or more flexible session management tools for use by software support personnel and WebSEAL administrators. Deployment considerations for clustered environments

Failover from one WebSEAL server to another

When clients failover from one WebSEAL server to another, there must be some mechanism for the new WebSEAL server to identify the client.

Security architects must choose from several possible options for handling failover events. Each option involves different trade-offs in complexity, security, and performance.

In addition, some options for handling failover events can provide additional functionality, such as single-signon or more flexible session management tools for use by software support personnel and WebSEAL administrators.

Parent topic: Deployment considerations for clustered environments

Options for handling failover in clustered environmentsOptions for handling failover in clustered environmentssession stateoptions for handling failover in clustered environmentsclustersoptions for handling failoverserver clustersoptions for handling failover in clustered environmentsWebSEAL offers several solutions to the challenge of providing secure sharing of session state across multiple servers in a clustered environment. The following sections describe the options available for handling failover events in clustered environments:Session state overviewSession state conceptsSupported session ID data typesInformation retrieved from a client requestValidation of the client identifier for a sessionYou can configure IBM Security Access Manager to validate the client identifier to ensure that different clients do not attempt to use the session.WebSEAL session cache structureDeployment considerations for clustered environmentsOption 1: No WebSEAL handling of failover eventsIf the load balancer in front of the WebSEAL cluster is able to maintain session affinity for long periods of time, failover events can be very rare. Option 2: Authentication data included in each requestSome authentication methods such as basic authentication or client-side certificates provide authentication data with every request. Option 3: Failover cookiesOption 4: The distributed session cacheThe distributed session cache is used for session storage by all WebSEAL servers in the cluster. When a client fails over, the new WebSEAL server can retrieve the user's session data from the distributed session cache and therefore avoid prompting the user to log in again.Option 5: LTPA cookie

Options for handling failover in clustered environments

WebSEAL offers several solutions to the challenge of providing secure sharing of session state across multiple servers in a clustered environment. The following sections describe the options available for handling failover events in clustered environments:

Option 1: No WebSEAL handling of failover events
If the load balancer in front of the WebSEAL cluster is able to maintain session affinity for long periods of time, failover events can be very rare.

Option 2: Authentication data included in each request
Some authentication methods such as basic authentication or client-side certificates provide authentication data with every request.

Option 3: Failover cookies

Option 4: The distributed session cache
The distributed session cache is used for session storage by all WebSEAL servers in the cluster. When a client fails over, the new WebSEAL server can retrieve the user's session data from the distributed session cache and therefore avoid prompting the user to log in again.

Option 5: LTPA cookie

Parent topic: Session state overview

Related concepts:

Session state concepts

Supported session ID data types

Information retrieved from a client request

Validation of the client identifier for a session

WebSEAL session cache structure

Deployment considerations for clustered environments

Option 1: No WebSEAL handling of failover eventsOption 1: No WebSEAL handling of failover eventsIf the load balancer in front of the WebSEAL cluster is able to maintain session affinity for long periods of time, failover events can be very rare. failover eventsWebSEALhandling failover eventsWhen failover events do occur, clients are forced to log in again. This option is relatively easy to configure, but contains the risk of a poor user experience if a WebSEAL server becomes unavailable for any reason or if the load balancer is unable to maintain session affinity.Options for handling failover in clustered environments

Option 1: No WebSEAL handling of failover events

If the load balancer in front of the WebSEAL cluster is able to maintain session affinity for long periods of time, failover events can be very rare.

When failover events do occur, clients are forced to log in again.

This option is relatively easy to configure, but contains the risk of a poor user experience if a WebSEAL server becomes unavailable for any reason or if the load balancer is unable to maintain session affinity.

Parent topic: Options for handling failover in clustered environments

Option 2: Authentication data included in each requestOption 2: Authentication data included in each requestSome authentication methods such as basic authentication or client-side certificates provide authentication data with every request. authenticationdata included in each requestrequestsauthentication dataIf the WebSEAL servers in the cluster are configured to use such an authentication method, then failover events result in automatic authentication of the user without prompting the user to login again.This method of handling failover events is relatively easy to configure and provides a good user experience. However, this method does not allow the use of certain WebSEAL features such as reauthentication and pkmslogout. Options for handling failover in clustered environments

Option 2: Authentication data included in each request

Some authentication methods such as basic authentication or client-side certificates provide authentication data with every request.

If the WebSEAL servers in the cluster are configured to use such an authentication method, then failover events result in automatic authentication of the user without prompting the user to login again.

This method of handling failover events is relatively easy to configure and provides a good user experience. However, this method does not allow the use of certain WebSEAL features such as reauthentication and pkmslogout.

Parent topic: Options for handling failover in clustered environments

Option 3: Failover cookiesOption 3: Failover cookiesfailover cookiesoverviewcookiesfailoverThe failover cookie is a mechanism for transparently reauthenticating the user and is not actually a mechanism for maintaining sessions. Failover cookies contain encrypted user authentication data that a WebSEAL server can use to validate a user's identity. A failover cookie maintains the following information:User credential informationSession inactivity timeout valueSession lifetime timeout valueAll other session state data, however, is not captured or maintained by failover cookies. Failover cookie configuration requires the distribution of a shared secret key to all of the WebSEAL servers in the cluster, and requires more configuration than the first two options discussed. Failover cookies pose a greater security risk than normal session cookies. If an attacker hijacks a session cookie, the session cookie is only valid until the WebSEAL server deletes the associated session. Failover cookies are valid until the lifetime or inactivity timeout in the failover cookie is reached. Failover cookies do allow the enforcement of session lifetime timeouts, inactivity timeouts, and pkmslogout. Failover cookies can also provide single-signon across multiple WebSEAL clusters in the same DNS domain.For further information on the failover cookie mechanism, see Failover solutionsUse the failover cookie solution to maintain session state in clustered environments..Options for handling failover in clustered environments

Option 3: Failover cookies

The failover cookie is a mechanism for transparently reauthenticating the user and is not actually a mechanism for maintaining sessions. Failover cookies contain encrypted user authentication data that a WebSEAL server can use to validate a user's identity. A failover cookie maintains the following information:

User credential information

Session inactivity timeout value

Session lifetime timeout value

All other session state data, however, is not captured or maintained by failover cookies.

Failover cookie configuration requires the distribution of a shared secret key to all of the WebSEAL servers in the cluster, and requires more configuration than the first two options discussed.

Failover cookies pose a greater security risk than normal session cookies. If an attacker hijacks a session cookie, the session cookie is only valid until the WebSEAL server deletes the associated session. Failover cookies are valid until the lifetime or inactivity timeout in the failover cookie is reached.

Failover cookies do allow the enforcement of session lifetime timeouts, inactivity timeouts, and pkmslogout. Failover cookies can also provide single-signon across multiple WebSEAL clusters in the same DNS domain.

For further information on the failover cookie mechanism, see Failover solutions.

Parent topic: Options for handling failover in clustered environments

Option 4: The distributed session cacheOption 4: The distributed session cacheThe distributed session cache is used for session storage by all WebSEAL servers in the cluster. When a client fails over, the new WebSEAL server can retrieve the user's session data from the distributed session cache and therefore avoid prompting the user to log in again.distributed session cacheoverviewWebSEALsession storageLike failover cookies, the distributed session cache allows consistent inactivity and lifetime timeout tracking across all of the WebSEAL servers in the cluster. Also like failover cookies, the distributed session cache allows for single-signon across multiple WebSEAL clusters in the same DNS domain.The distributed session cache reduces the security risk that is posed by the failover cookie, since only a normal session cookie is used. The distributed session cache also provides extra features that are not available with any other method of maintaining session state across server clusters. For example, the distributed session cache allows customer support personnel and WebSEAL administrators to view all of the users who are logged in to the cluster at a given time. The distributed session cache also supports a max-concurrent-web-sessions policy that limits the number of concurrent sessions that are allowed per user. For more information about the distributed session cache, see Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution..Options for handling failover in clustered environments

Option 4: The distributed session cache

The distributed session cache is used for session storage by all WebSEAL servers in the cluster. When a client fails over, the new WebSEAL server can retrieve the user's session data from the distributed session cache and therefore avoid prompting the user to log in again.

Like failover cookies, the distributed session cache allows consistent inactivity and lifetime timeout tracking across all of the WebSEAL servers in the cluster. Also like failover cookies, the distributed session cache allows for single-signon across multiple WebSEAL clusters in the same DNS domain.

The distributed session cache reduces the security risk that is posed by the failover cookie, since only a normal session cookie is used.

The distributed session cache also provides extra features that are not available with any other method of maintaining session state across server clusters. For example, the distributed session cache allows customer support personnel and WebSEAL administrators to view all of the users who are logged in to the cluster at a given time.

The distributed session cache also supports a max-concurrent-web-sessions policy that limits the number of concurrent sessions that are allowed per user.

For more information about the distributed session cache, see Advanced configuration for the distributed session cache.

Parent topic: Options for handling failover in clustered environments

Option 5: LTPA cookieOption 5: LTPA cookieLTPAcookiescookiesLTPAThe failover cookie is primarily a mechanism for transparently authenticating the user and is not actually a mechanism for maintaining sessions. LTPA cookies contain encrypted user authentication data that a WebSEAL server can use to validate a user’s identity. An LTPA cookie maintains the following information:User nameSession lifetime timeout valueAll other session state data, however, is not captured or maintained by LTPA cookies. LTPA cookie configuration requires the distribution of a shared secret key to all of the servers in the cluster, and requires more configuration than the first two options discussed. LTPA cookies pose a greater security risk than normal session cookies. If an attacker hijacks a session cookie, the session cookie is only valid until the WebSEAL server deletes the associated session. LTPA cookies are valid until the lifetime timeout in the LTPA cookie is reached. LTPA cookies do allow the enforcement of session lifetime timeouts, and pkmslogout. LTPA cookies can also provide single-signon across multiple WebSEAL clusters in the same DNS domain, along with single-signon across other LTPA-enabled servers in the same DNS domain (for example, WebSphere Application Server, DataPower). If you are using a cookie-based failover approach, you should use the failover cookie, mentioned in option 3, over the LTPA cookie option. The LTPA cookie is mostly designed to enable single-signon to third-party servers (for example WebSphere Application Server, DataPower). For further information on the LTPA cookie mechanism, see LTPA authentication.Options for handling failover in clustered environments

Option 5: LTPA cookie

The failover cookie is primarily a mechanism for transparently authenticating the user and is not actually a mechanism for maintaining sessions. LTPA cookies contain encrypted user authentication data that a WebSEAL server can use to validate a user’s identity. An LTPA cookie maintains the following information:

User name

Session lifetime timeout value

All other session state data, however, is not captured or maintained by LTPA cookies. LTPA cookie configuration requires the distribution of a shared secret key to all of the servers in the cluster, and requires more configuration than the first two options discussed.

LTPA cookies pose a greater security risk than normal session cookies. If an attacker hijacks a session cookie, the session cookie is only valid until the WebSEAL server deletes the associated session. LTPA cookies are valid until the lifetime timeout in the LTPA cookie is reached.

LTPA cookies do allow the enforcement of session lifetime timeouts, and pkmslogout. LTPA cookies can also provide single-signon across multiple WebSEAL clusters in the same DNS domain, along with single-signon across other LTPA-enabled servers in the same DNS domain (for example, WebSphere® Application Server, DataPower®).

If you are using a cookie-based failover approach, you should use the failover cookie, mentioned in option 3, over the LTPA cookie option. The LTPA cookie is mostly designed to enable single-signon to third-party servers (for example WebSphere Application Server, DataPower).

For further information on the LTPA cookie mechanism, see LTPA authentication.

Parent topic: Options for handling failover in clustered environments

Session cache configurationSession cache configurationsession cacheconfigurationThis chapter talks about configuring the SSL session cache and the WebSEAL session cache.Topic Index:Session StateSession cache configuration overviewSSL session ID cache configurationWebSEAL session cache configuration

Session cache configuration

This chapter talks about configuring the SSL session cache and the WebSEAL session cache.

Topic Index:

Session cache configuration overview

SSL session ID cache configuration

WebSEAL session cache configuration

Parent topic: Session State

Session cache configuration overviewSession cache configuration overviewsession cacheconfigurationconfigurationsession cacheA session cache allows a server to store session information from multiple clients. WebSEAL uses two types of session caches to accommodate both HTTPS and HTTP session state information between clients and WebSEAL: WebSEAL session cache session cacheWebSEAL session cache The WebSEAL session cache stores information about all sessions established by authenticated and unauthenticated users. The session key, stored with the client, is a locator index to the associated session data stored in the WebSEAL session cache. The WebSEAL session cache stores, among other data, the credential information obtained for each client. Credential information is cached to eliminate repetitive queries to the user registry database during authorization checks.SSL session ID cache session cacheSSL session cache The SSL session cache stores the SSL session ID used to maintain SSL session state. SSL session IDs can be used as the session index for the WebSEAL session cache. Configuration file entries for configuring the WebSEAL session cache and the SSL session ID cache are summarized in the following diagram:Session cache configuration file entriesSession cache configuration stanza entriesFor an overview of session state concepts, see Session state overview.Session cache configurationSSL session ID cache configurationWebSEAL session cache configuration

Session cache configuration overview

A session cache allows a server to store session information from multiple clients. WebSEAL uses two types of session caches to accommodate both HTTPS and HTTP session state information between clients and WebSEAL:

WebSEAL session cache

The WebSEAL session cache stores information about all sessions established by authenticated and unauthenticated users. The session key, stored with the client, is a locator index to the associated session data stored in the WebSEAL session cache.

The WebSEAL session cache stores, among other data, the credential information obtained for each client. Credential information is cached to eliminate repetitive queries to the user registry database during authorization checks.

SSL session ID cache

The SSL session cache stores the SSL session ID used to maintain SSL session state.

SSL session IDs can be used as the session index for the WebSEAL session cache.

Configuration file entries for configuring the WebSEAL session cache and the SSL session ID cache are summarized in the following diagram:

Figure 20. Session cache configuration file entries

For an overview of session state concepts, see Session state overview.

Parent topic: Session cache configuration

Related concepts:

SSL session ID cache configuration

WebSEAL session cache configuration

SSL session ID cache configurationSSL session ID cache configurationsession cacheconfiguring SSL cachetimeoutsettingsSSL session cachesession stateconfiguring SSL session ID cacheThe following configuration tasks are available for the SSL session ID cache: Session cache configurationSession cache configuration overviewWebSEAL session cache configurationCache entry timeout valueMaximum concurrent SSL sessions value

SSL session ID cache configuration

The following configuration tasks are available for the SSL session ID cache:

Cache entry timeout value

Maximum concurrent SSL sessions value

Parent topic: Session cache configuration

Related concepts:

Session cache configuration overview

WebSEAL session cache configuration

Cache entry timeout value Cache entry timeout value ssl-v2-timeout stanza entryssl-v3-timeout stanza entryThe stanza entries for setting the maximum lifetime timeout for an entry in the SSL session ID cache are located in the [ssl] stanza of the WebSEAL configuration file. There are two stanza entries: one for SSL v2 connections (ssl-v2-timeout) and one for SSL v3 connections (ssl-v3-timeout). The SSL v3 session timeout is also used for TLS v1 connections.The default SSL v2 session timeout (in seconds) is 100 (with a possible range of 1-100): [ssl] ssl-v2-timeout = 100The default SSL v3 session timeout (in seconds) is 7200 (with a possible range of 1-86400): [ssl] ssl-v3-timeout = 7200SSL session ID cache configuration

Cache entry timeout value

The stanza entries for setting the maximum lifetime timeout for an entry in the SSL session ID cache are located in the [ssl] stanza of the WebSEAL configuration file. There are two stanza entries: one for SSL v2 connections (ssl-v2-timeout) and one for SSL v3 connections (ssl-v3-timeout). The SSL v3 session timeout is also used for TLS v1 connections.

The default SSL v2 session timeout (in seconds) is 100 (with a possible range of 1-100):

[ssl]
ssl-v2-timeout = 100

The default SSL v3 session timeout (in seconds) is 7200 (with a possible range of 1-86400):

[ssl]
ssl-v3-timeout = 7200

Parent topic: SSL session ID cache configuration

Maximum concurrent SSL sessions value Maximum concurrent SSL sessions value ssl-max-entries stanza entrymaximum concurrent SSL sessions valueThe ssl-max-entries stanza entry, located in the [ssl] stanza of the WebSEAL configuration file, sets the maximum number of concurrent SSL sessions in the SSL session ID cache. This value limits the number of SSL sessions the WebSEAL server tracks at any given time. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm. If a client whose SSL session was discarded contacts the WebSEAL server again, WebSEAL automatically negotiates a new SSL session with the client. If SSL session IDs are being used as the session index for the WebSEAL session cache, the client's WebSEAL session ID changes because of the renegotiation. The client must reauthenticate to WebSEAL. The default number of concurrent SSL sessions is 4096: [ssl] ssl-max-entries = 4096SSL session ID cache configuration

Maximum concurrent SSL sessions value

The ssl-max-entries stanza entry, located in the [ssl] stanza of the WebSEAL configuration file, sets the maximum number of concurrent SSL sessions in the SSL session ID cache.

This value limits the number of SSL sessions the WebSEAL server tracks at any given time. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm. If a client whose SSL session was discarded contacts the WebSEAL server again, WebSEAL automatically negotiates a new SSL session with the client.

If SSL session IDs are being used as the session index for the WebSEAL session cache, the client's WebSEAL session ID changes because of the renegotiation. The client must reauthenticate to WebSEAL.

The default number of concurrent SSL sessions is 4096:

[ssl]
ssl-max-entries = 4096

Parent topic: SSL session ID cache configuration

WebSEAL session cache configurationWebSEAL session cache configurationWebSEAL session cacheconfigurationtimeoutsettingsWebSEAL session cachesession stateconfiguring WebSEAL session cachesession cacheconfiguring WebSEAL cacheWebSEAL maintains two separate session caches, one for authenticated users and the other for users who are in the process of authenticating. Once a user is authenticated, their session cache entry is moved from the unauthenticated session cache to the authenticated session cache.The following sections describe configuration and use of WebSEAL session caches: Session cache configurationSession cache configuration overviewSSL session ID cache configurationMaximum session cache entries valueCache entry lifetime timeout valueSetting a client-specific session cache entry lifetime valueCache entry inactivity timeout valueConcurrent session limitsYou can configure WebSEAL to limit the number of concurrent requests for a single user session.Session cache limitation

WebSEAL session cache configuration

WebSEAL maintains two separate session caches, one for authenticated users and the other for users who are in the process of authenticating. Once a user is authenticated, their session cache entry is moved from the unauthenticated session cache to the authenticated session cache.

The following sections describe configuration and use of WebSEAL session caches:

Maximum session cache entries value

Cache entry lifetime timeout value

Setting a client-specific session cache entry lifetime value

Cache entry inactivity timeout value

Concurrent session limits
You can configure WebSEAL to limit the number of concurrent requests for a single user session.

Session cache limitation

Parent topic: Session cache configuration

Related concepts:

Session cache configuration overview

SSL session ID cache configuration

Maximum session cache entries value Maximum session cache entries value max-entries stanza entryWebSEAL session cachemaximum entriessession cachemaximum entriesThe max-entries stanza entry, located in the [session] stanza of the WebSEAL configuration file, specifies the maximum number of session cache entries in the WebSEAL unauthenticated and authenticated session caches. This value corresponds to the number of concurrent login sessions. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm to allow new incoming logins.The following conditions affect the specified value:If the specified value is less than or equal to 0, the cache size becomes unlimited.If the specified value is between 0 and 8192, the actual number of entries allowed is rounded up to the next multiple of 32.Any specified value greater than 8192 is accepted as given.WebSEAL does not impose a maximum value. See the guidelines on maximum size of integer values in Guidelines for changing configuration files.The default number of concurrent login sessions is 4096: [session] max-entries = 4096The value for a particular session cache (either unauthenticated or authenticated) can be supplied by prefixing the configuration entry with the session cache name (either unauth or auth). For example: unauth-max-entries = 1024WebSEAL session cache configuration

Maximum session cache entries value

The max-entries stanza entry, located in the [session] stanza of the WebSEAL configuration file, specifies the maximum number of session cache entries in the WebSEAL unauthenticated and authenticated session caches.

This value corresponds to the number of concurrent login sessions. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm to allow new incoming logins.

The following conditions affect the specified value:

If the specified value is less than or equal to 0, the cache size becomes unlimited.

If the specified value is between 0 and 8192, the actual number of entries allowed is rounded up to the next multiple of 32.

Any specified value greater than 8192 is accepted as given.

WebSEAL does not impose a maximum value. See the guidelines on maximum size of integer values in Guidelines for changing configuration files.

The default number of concurrent login sessions is 4096:

[session]
max-entries = 4096

The value for a particular session cache (either unauthenticated or authenticated) can be supplied by prefixing the configuration entry with the session cache name (either unauth or auth). For example:

unauth-max-entries = 1024

Parent topic: WebSEAL session cache configuration

Cache entry lifetime timeout valueCache entry lifetime timeout valuetimeout stanzastanzasession cachelifetime timeout (global setting)WebSEAL session cachelifetime timeout (global setting)session timeoutsession expirationThe timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, sets the maximum lifetime timeout value for all user session information stored in the WebSEAL authenticated or unauthenticated session caches.WebSEAL caches credential information internally, so the session cache timeout stanza entry dictates the length of time authorization credential information remains in memory on WebSEAL. The stanza entry is not an inactivity timeout. The value maps to a "credential lifetime" rather than a "session inactivity timeout". Its purpose is to enhance security by forcing the user to reauthenticate when the specified timeout limit is reached.The default session cache entry lifetime timeout (in seconds) is 3600: [session] timeout = 3600The value for a particular session cache (either unauthenticated or authenticated) can be supplied by prefixing the configuration entry with the session cache name (either unauth or auth). For example: unauth-max-entries = 1024WebSEAL does not impose a maximum value for this stanza entry.A value of "0" disables this timeout feature (lifetime value is unlimited). The control of cache entries is then governed by the inactive-timeout and max-entries stanza entries. When a cache is full, the entries are cleared based on a least-recently-used algorithm. See Maximum session cache entries value. This stanza entry is ineffective for authentication methods that include authentication data in every request to the WebSEAL server, such as basic authentication (BA), SPNEGO, and some forms of certificate authentication. Those authentication methods automatically reauthenticate the user to the WebSEAL server if the user's session has been deleted due to inactivity or lifetime timeouts. The result is repeated resetting of the inactive and lifetime timeout values.You can configure WebSEAL to return session timeout information to the client by adding a <header-name> = %SESSION_EXPIRY% entry to the [rsp-header-names] stanza. See [rsp-header-names] stanzaDefines static HTTP headers that will be added to every HTTP response from the WebSEAL server..WebSEAL session cache configuration

Cache entry lifetime timeout value

The timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, sets the maximum lifetime timeout value for all user session information stored in the WebSEAL authenticated or unauthenticated session caches.

WebSEAL caches credential information internally, so the session cache timeout stanza entry dictates the length of time authorization credential information remains in memory on WebSEAL.

The stanza entry is not an inactivity timeout. The value maps to a "credential lifetime" rather than a "session inactivity timeout". Its purpose is to enhance security by forcing the user to reauthenticate when the specified timeout limit is reached.

The default session cache entry lifetime timeout (in seconds) is 3600:

[session]
timeout = 3600

The value for a particular session cache (either unauthenticated or authenticated) can be supplied by prefixing the configuration entry with the session cache name (either unauth or auth). For example:

unauth-max-entries = 1024

WebSEAL does not impose a maximum value for this stanza entry.

A value of "0" disables this timeout feature (lifetime value is unlimited). The control of cache entries is then governed by the inactive-timeout and max-entries stanza entries.

When a cache is full, the entries are cleared based on a least-recently-used algorithm. See Maximum session cache entries value.

Note: This stanza entry is ineffective for authentication methods that include authentication data in every request to the WebSEAL server, such as basic authentication (BA), SPNEGO, and some forms of certificate authentication. Those authentication methods automatically reauthenticate the user to the WebSEAL server if the user's session has been deleted due to inactivity or lifetime timeouts. The result is repeated resetting of the inactive and lifetime timeout values.

Tip: You can configure WebSEAL to return session timeout information to the client by adding a "<header-name> = %SESSION_EXPIRY%" entry to the [rsp-header-names] stanza. See [rsp-header-names] stanza.

Parent topic: WebSEAL session cache configuration

Cache entry inactivity timeout value Cache entry inactivity timeout value session cacheinactivity timeoutWebSEAL session cacheinactivity timeoutinactive-timeout stanza entrysession stanzasession timeoutsession expirationThe inactive-timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, sets the timeout value for user session inactivity.For example, if a user is inactive for a period of time longer than the inactivity timeout, WebSEAL either deletes the user's session entirely or flags the session as requiring re-authentication. For information on requiring re-authentication for inactive sessions, refer Reauthentication with external authentication interface.The default login session inactivity timeout (in seconds) is 600: [session] inactive-timeout = 600The value for a particular session cache (either unauthenticated or authenticated) can be supplied by prefixing the configuration entry with the session cache name (either unauth or auth). For example: unauth-inactive-timeout = 300WebSEAL does not impose a maximum value for this stanza entry.A value of "0" disables this inactivity timeout feature (inactivity timeout value is unlimited). The control of cache entries is then governed only by the timeout and max-entries stanza entries. When a cache is full, the entries are cleared based on a least-recently-used algorithm. See Maximum session cache entries value. This stanza entry is ineffective for authentication methods that include authentication data in every request to the WebSEAL server, such as basic authentication (BA), SPNEGO, and some forms of certificate authentication. Those authentication methods automatically reauthenticate the user to the WebSEAL server if the user's session has been deleted due to inactivity or lifetime timeouts. The result is repeated resetting of the inactive and lifetime timeout values.Preserve inactivity timeoutIn some circumstances, you might not want the requests for a particular resource to affect the inactivity timeout for a session. For example, you might want to preserve the inactivity timeout when a server is polled by an Ajax script running in the background of a client browser.You can create security policies to specify the resources that must not affect the inactivity timeout of the user session. To define this security policy, you must create a protected object policy (POP) with an extended attribute named preserve-inactivity-time. You can attach this POP to any object that requires the inactivity timeout to be unaffected by a request. Remember that all children of the object with the POP also inherit the POP conditions.Use the following commands to create and apply the preserve-inactivity-time POP:pdadmin pop createpdadmin pop modifypdadmin pop attachThe following example creates a POP called robot with the preserve-inactivity-time extended attribute and attaches it to the status.html object:pdadmin> pop create robot pdadmin> pop modify robot set attribute preserve-inactivity-time true pdadmin> pop attach /WebSEAL/hostA/junction/status.html robotWhen this policy is in place, requests made to status.html will not impact the inactivity timeout for the user session. You can configure WebSEAL to return session timeout information to the client by adding a <header-name> = %SESSION_EXPIRY% entry to the [rsp-header-names] stanza. See [rsp-header-names] stanzaDefines static HTTP headers that will be added to every HTTP response from the WebSEAL server..WebSEAL session cache configuration

Cache entry inactivity timeout value

The inactive-timeout stanza entry, located in the [session] stanza of the WebSEAL configuration file, sets the timeout value for user session inactivity.

For example, if a user is inactive for a period of time longer than the inactivity timeout, WebSEAL either deletes the user's session entirely or flags the session as requiring re-authentication. For information on requiring re-authentication for inactive sessions, refer Reauthentication with external authentication interface.

The default login session inactivity timeout (in seconds) is 600:

[session]
inactive-timeout = 600

The value for a particular session cache (either unauthenticated or authenticated) can be supplied by prefixing the configuration entry with the session cache name (either unauth or auth). For example:

unauth-inactive-timeout = 300

WebSEAL does not impose a maximum value for this stanza entry.

A value of "0" disables this inactivity timeout feature (inactivity timeout value is unlimited). The control of cache entries is then governed only by the timeout and max-entries stanza entries.

When a cache is full, the entries are cleared based on a least-recently-used algorithm. See Maximum session cache entries value.

Note: This stanza entry is ineffective for authentication methods that include authentication data in every request to the WebSEAL server, such as basic authentication (BA), SPNEGO, and some forms of certificate authentication. Those authentication methods automatically reauthenticate the user to the WebSEAL server if the user's session has been deleted due to inactivity or lifetime timeouts. The result is repeated resetting of the inactive and lifetime timeout values.

Preserve inactivity timeout

In some circumstances, you might not want the requests for a particular resource to affect the inactivity timeout for a session. For example, you might want to preserve the inactivity timeout when a server is polled by an Ajax script running in the background of a client browser.

You can create security policies to specify the resources that must not affect the inactivity timeout of the user session. To define this security policy, you must create a protected object policy (POP) with an extended attribute named preserve-inactivity-time. You can attach this POP to any object that requires the inactivity timeout to be unaffected by a request. Remember that all children of the object with the POP also inherit the POP conditions.

Use the following commands to create and apply the preserve-inactivity-time POP:

pdadmin pop create

pdadmin pop modify

pdadmin pop attach

The following example creates a POP called robot with the preserve-inactivity-time extended attribute and attaches it to the status.html object:

pdadmin> pop create robot
pdadmin> pop modify robot set attribute preserve-inactivity-time true
pdadmin> pop attach /WebSEAL/hostA/junction/status.html robot

When this policy is in place, requests made to status.html will not impact the inactivity timeout for the user session.

Tip: You can configure WebSEAL to return session timeout information to the client by adding a "<header-name> = %SESSION_EXPIRY%" entry to the [rsp-header-names] stanza. See [rsp-header-names] stanza.

Parent topic: WebSEAL session cache configuration

Concurrent session limitsConcurrent session limitsYou can configure WebSEAL to limit the number of concurrent requests for a single user session.session cacheconcurrent session limitsWebSEAL session cacheconcurrent session limitsconcurrent-session-threads-hard-limit stanza entryconcurrent-session-threads-soft-limit stanza entryConcurrent session threads hard limitThe hard limit is the maximum number of concurrent threads that a single user session can consume. When a user session reaches its thread limit, WebSEAL stops processing any new requests for the user session and returns an error to the client.Use the concurrent-session-threads-hard-limit configuration entry in the [server] stanza to configure the session hard limit.If you do not specify a value for this entry, there is no limit to the number of concurrent threads that a user session can consume.For example, the following configuration results in a maximum of 10 concurrent threads for a single user session:[server] concurrent-session-threads-hard-limit = 10Concurrent session threads soft limitYou can use the concurrent-session-threads-soft-limit configuration entry in the [server] stanza to configure the session soft limit.The soft limit is maximum number of concurrent threads that a single user session can consume before WebSEAL generates warning messages. WebSEAL continues processing requests for this session until it reaches the configured concurrent-session-threads-hard-limit.For example, if the following entries are set then WebSEAL generates warnings when the number of threads for a user session exceeds the soft limit of five. WebSEAL continues to process requests until the hard limit of 10 is reached. Any further requests cause WebSEAL to return an error to the client. [server] concurrent-session-threads-soft-limit = 5 concurrent-session-threads-hard-limit = 10WebSEAL session cache configuration

Concurrent session limits

You can configure WebSEAL to limit the number of concurrent requests for a single user session.

Concurrent session threads hard limit

The hard limit is the maximum number of concurrent threads that a single user session can consume. When a user session reaches its thread limit, WebSEAL stops processing any new requests for the user session and returns an error to the client.

Use the concurrent-session-threads-hard-limit configuration entry in the [server] stanza to configure the session hard limit.

If you do not specify a value for this entry, there is no limit to the number of concurrent threads that a user session can consume.

For example, the following configuration results in a maximum of 10 concurrent threads for a single user session:

[server]
concurrent-session-threads-hard-limit = 10

Concurrent session threads soft limit

You can use the concurrent-session-threads-soft-limit configuration entry in the [server] stanza to configure the session soft limit.

The soft limit is maximum number of concurrent threads that a single user session can consume before WebSEAL generates warning messages. WebSEAL continues processing requests for this session until it reaches the configured concurrent-session-threads-hard-limit.

For example, if the following entries are set then WebSEAL generates warnings when the number of threads for a user session exceeds the soft limit of five. WebSEAL continues to process requests until the hard limit of 10 is reached. Any further requests cause WebSEAL to return an error to the client.

[server]
concurrent-session-threads-soft-limit = 5
concurrent-session-threads-hard-limit = 10

Parent topic: WebSEAL session cache configuration

Session cache limitationSession cache limitationWebSEALsession cache limitationsession cacheWebSEAL limitationLimitation:When you delete a user from the registry, the credentials of that user in the WebSEAL session cache are not removed. If the user has a browser session active at the time the account is deleted, the user can continue to browse, based on the existing session cache entry. The credentials of the user are not reevaluated, based on the current information in the user registry, until either a new login occurs or the session cache entry expires. The contents of the WebSEAL session cache are cleared when the user logs out of the browser session.Workaround: As the administrator, you can force an immediate halt to user activity in a domain by adding an explicit entry to the default WebSEAL ACL policy for the deleted user with the traverse (T) permission removed. You can also terminate the session manually, using either from a command line or using a Security Access Manager administration API function. See Terminating user sessions.WebSEAL session cache configuration

Session cache limitation

Limitation:

When you delete a user from the registry, the credentials of that user in the WebSEAL session cache are not removed. If the user has a browser session active at the time the account is deleted, the user can continue to browse, based on the existing session cache entry.

The credentials of the user are not reevaluated, based on the current information in the user registry, until either a new login occurs or the session cache entry expires. The contents of the WebSEAL session cache are cleared when the user logs out of the browser session.

Workaround:

As the administrator, you can force an immediate halt to user activity in a domain by adding an explicit entry to the default WebSEAL ACL policy for the deleted user with the traverse (T) permission removed. You can also terminate the session manually, using either from a command line or using a Security Access Manager administration API function. See Terminating user sessions.

Parent topic: WebSEAL session cache configuration

Failover solutionsFailover solutionsUse the failover cookie solution to maintain session state in clustered environments.authenticationfailoversolutionsfailoversolutionsTopic Index:Failover cookies and the distributed session cache are alternate solutions to the same challenge of maintaining session state in clustered server environments. See also Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution..Session StateFailover authentication conceptsFailover authentication configurationFailover for non-sticky failover environmentsChange password operation in a failover environment

Failover solutions

Use the failover cookie solution to maintain session state in clustered environments.

Topic Index:

Failover cookies and the distributed session cache are alternate solutions to the same challenge of maintaining session state in clustered server environments. See also Advanced configuration for the distributed session cache.

Failover authentication concepts

Failover authentication configuration

Failover for non-sticky failover environments

Change password operation in a failover environment

Parent topic: Session State

Failover authentication conceptsFailover authentication conceptssession statefailover cookiesfailover authenticationoverviewWebSEAL provides an authentication method that preserves an authenticated session between a client and WebSEAL when the WebSEAL server becomes unavailable in a replicated server (fault-tolerant) environment. The method is called failover authentication. This section contains the following topics:See also Failover authentication configuration.Failover solutionsUse the failover cookie solution to maintain session state in clustered environments.Failover authentication configurationFailover for non-sticky failover environmentsChange password operation in a failover environmentThe failover environmentFailover cookieWebSEAL supports failover authentication of a user through a failover cookie. The failover cookie can be a server-specific cookie or a domain cookie. Failover authentication process flowExample failover configurationIn this example, a WebSEAL server is configured to support forms authentication and failover authentication.Addition of data to a failover cookieExtraction of data from a failover cookieDomain-wide failover authentication

Failover authentication concepts

WebSEAL provides an authentication method that preserves an authenticated session between a client and WebSEAL when the WebSEAL server becomes unavailable in a replicated server (fault-tolerant) environment. The method is called failover authentication.

This section contains the following topics:

See also Failover authentication configuration.

The failover environment

Failover cookie
WebSEAL supports failover authentication of a user through a failover cookie. The failover cookie can be a server-specific cookie or a domain cookie.

Failover authentication process flow

Example failover configuration
In this example, a WebSEAL server is configured to support forms authentication and failover authentication.

Addition of data to a failover cookie

Extraction of data from a failover cookie

Domain-wide failover authentication

Parent topic: Failover solutions

Related concepts:

Failover authentication configuration

Failover for non-sticky failover environments

Change password operation in a failover environment

The failover environmentThe failover environmentfailoverenvironmentenvironmentsfailoverThe failover cookie is not actually a mechanism for maintaining sessions; it is a mechanism for transparently reauthenticating the user. Failover authentication is most commonly used in a scenario where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers. The replicated servers have identical configuration. They contain replica copies of the WebSEAL protected object space, junction database, and (optionally) dynurl database.The client is not aware of the replicated front-end server configuration. The load balancing mechanism is the single point of contact for the requested resource. The load balancer connects the client with an available server.Failover for replicated WebSEAL serversFailover for replicated WebSEAL serversIf the server where the client is connected suddenly becomes unavailable, the load balancer redirects the request to one of the other replicated servers. This action causes the loss of the original session-to-credential mapping. The client is new to this substitute server and is normally forced to login again.The purpose of failover authentication is to prevent forced login when the WebSEAL server that has the original session with the client suddenly becomes unavailable. Failover authentication enables the client to connect to another WebSEAL server, and create an authentication session containing the same user session data and user credentials.Failover authentication in a replicated server deployment provides two useful features: Performance improvements through load balancingFailover of client sessions between WebSEAL serversReferences:For more information on the replication of WebSEAL servers, see Replicating front-end WebSEAL servers.For information on failover solutions in an environment without session affinity (non-sticky), see Failover for non-sticky failover environments.Failover authentication concepts

The failover environment

The failover cookie is not actually a mechanism for maintaining sessions; it is a mechanism for transparently reauthenticating the user. Failover authentication is most commonly used in a scenario where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers.

The replicated servers have identical configuration. They contain replica copies of the WebSEAL protected object space, junction database, and (optionally) dynurl database.

The client is not aware of the replicated front-end server configuration. The load balancing mechanism is the single point of contact for the requested resource. The load balancer connects the client with an available server.

Figure 21. Failover for replicated WebSEAL servers

If the server where the client is connected suddenly becomes unavailable, the load balancer redirects the request to one of the other replicated servers. This action causes the loss of the original session-to-credential mapping. The client is new to this substitute server and is normally forced to login again.

The purpose of failover authentication is to prevent forced login when the WebSEAL server that has the original session with the client suddenly becomes unavailable. Failover authentication enables the client to connect to another WebSEAL server, and create an authentication session containing the same user session data and user credentials.

Failover authentication in a replicated server deployment provides two useful features:

Performance improvements through load balancing

Failover of client sessions between WebSEAL servers

References:

For more information on the replication of WebSEAL servers, see Replicating front-end WebSEAL servers.

For information on failover solutions in an environment without session affinity (non-sticky), see Failover for non-sticky failover environments.

Parent topic: Failover authentication concepts

Failover cookie Failover cookie WebSEAL supports failover authentication of a user through a failover cookie. The failover cookie can be a server-specific cookie or a domain cookie. failover authenticationfailover cookiesdescriptioncookiesfailoverfailover cookiesoverviewThe failover cookie contains encrypted client-specific data, such as:User nameCookie-creation time stampOriginal authentication methodAttribute listBy default, the attribute list contains the user's current authentication level. WebSEAL can be configured to add additional extended attributes to the attribute list. See Failover for non-sticky failover environments for a failover solution that stores the client's session ID as an extended attribute.The cookie is placed on the browser when the client first connects. If the initial WebSEAL server becomes temporarily unavailable, the cookie is presented to the substitute server. The replicated WebSEAL servers share a common key that can decrypt the cookie information. When the substitute replica WebSEAL server receives this cookie, it decrypts the cookie, and uses the user name and authentication method to regenerate the client's credential. WebSEAL can also be configured to copy any extended attributes from the cookie to the user credential. The client can now establish a new session with a replica WebSEAL server without being prompted to log in. The failover cookie is not a mechanism for maintaining session state. The failover cookie is a mechanism for transparently reauthenticating a user.You can use the failover-cookie-name entry in the [failover] stanza to configure the name of the failover cookie. By default, WebSEAL uses the name PD-ID for the failover cookie.Failover cookies can be used over either HTTP or HTTPS.Failover authentication concepts

Failover cookie

WebSEAL supports failover authentication of a user through a failover cookie. The failover cookie can be a server-specific cookie or a domain cookie.

The failover cookie contains encrypted client-specific data, such as:

User name

Cookie-creation time stamp

Original authentication method

Attribute list

By default, the attribute list contains the user's current authentication level. WebSEAL can be configured to add additional extended attributes to the attribute list. See Failover for non-sticky failover environments for a failover solution that stores the client's session ID as an extended attribute.

The cookie is placed on the browser when the client first connects. If the initial WebSEAL server becomes temporarily unavailable, the cookie is presented to the substitute server.

The replicated WebSEAL servers share a common key that can decrypt the cookie information. When the substitute replica WebSEAL server receives this cookie, it decrypts the cookie, and uses the user name and authentication method to regenerate the client's credential. WebSEAL can also be configured to copy any extended attributes from the cookie to the user credential.

The client can now establish a new session with a replica WebSEAL server without being prompted to log in.

The failover cookie is not a mechanism for maintaining session state. The failover cookie is a mechanism for transparently reauthenticating a user.

You can use the failover-cookie-name entry in the [failover] stanza to configure the name of the failover cookie. By default, WebSEAL uses the name PD-ID for the failover cookie.

Note: Failover cookies can be used over either HTTP or HTTPS.

Parent topic: Failover authentication concepts

Failover authentication process flowFailover authentication process flowfailover authenticationprocess flowprocess flowfailover authenticationThe following steps explain the sequence of events for a failover authentication event:The client (browser) attempts to access a protected resource. The client request goes to a load balancer that controls access to the replicated WebSEAL servers.The load balancer selects a target WebSEAL server and forwards the user request.The client successfully authenticates to WebSEAL using one of the supported authentication methods.WebSEAL creates a failover authentication cookie that contains client authentication information, and sends the cookie to the client browser.The browser sends the cookie through the load balancer to WebSEAL with each subsequent request. The WebSEAL server processes each request.If the load balancer finds that the original WebSEAL server is no longer available, the client request is directed to another replicated WebSEAL server.The replicated WebSEAL server is configured to check for the existence of a failover authentication cookie every time it attempts to authenticate a user.The replicated WebSEAL server uses the information in the cookie to establish a session with the client, without requiring the client to manually log in again. The client's session data and user credential are built, and the request for the protected resource is processed.The change of session from one WebSEAL server to another WebSEAL server is transparent to the client. Because the WebSEAL servers contain identical resources, the client session continues uninterrupted.Failover authentication concepts

Failover authentication process flow

The following steps explain the sequence of events for a failover authentication event:

The client (browser) attempts to access a protected resource. The client request goes to a load balancer that controls access to the replicated WebSEAL servers.

The load balancer selects a target WebSEAL server and forwards the user request.

The client successfully authenticates to WebSEAL using one of the supported authentication methods.

WebSEAL creates a failover authentication cookie that contains client authentication information, and sends the cookie to the client browser.

The browser sends the cookie through the load balancer to WebSEAL with each subsequent request. The WebSEAL server processes each request.

If the load balancer finds that the original WebSEAL server is no longer available, the client request is directed to another replicated WebSEAL server.

The replicated WebSEAL server is configured to check for the existence of a failover authentication cookie every time it attempts to authenticate a user.

The replicated WebSEAL server uses the information in the cookie to establish a session with the client, without requiring the client to manually log in again. The client's session data and user credential are built, and the request for the protected resource is processed.

The change of session from one WebSEAL server to another WebSEAL server is transparent to the client. Because the WebSEAL servers contain identical resources, the client session continues uninterrupted.

Parent topic: Failover authentication concepts

Example failover configurationExample failover configurationIn this example, a WebSEAL server is configured to support forms authentication and failover authentication.failover authenticationexample configurationexamplesfailover authentication The user authenticates to WebSEAL using forms authentication.The WebSEAL server sends a failover authentication cookie to each client (browser). The cookie data specifies that the cookie was created in a forms authentication environment.When the WebSEAL server becomes unavailable, the failover cookie is sent to a second WebSEAL server. The second WebSEAL server receives the failover cookie, and examines it to determine the user's previous authentication method.The second WebSEAL server uses data from the cookie to authenticate the user and build a user credential.Configuration instructions in this chapter: Adding the authentication strength levelFailover authentication concepts

Example failover configuration

In this example, a WebSEAL server is configured to support forms authentication and failover authentication.

The user authenticates to WebSEAL using forms authentication.

The WebSEAL server sends a failover authentication cookie to each client (browser).

The cookie data specifies that the cookie was created in a forms authentication environment.

When the WebSEAL server becomes unavailable, the failover cookie is sent to a second WebSEAL server.

The second WebSEAL server receives the failover cookie, and examines it to determine the user's previous authentication method.

The second WebSEAL server uses data from the cookie to authenticate the user and build a user credential.

Configuration instructions in this chapter:

Adding the authentication strength level

Parent topic: Failover authentication concepts

Addition of data to a failover cookieAddition of data to a failover cookiefailover cookiesadding data and attributessession lifetime timestampsession activity timestampfailover authenticationfailover cookiesdataattributessession lifetime timestampsession activity timestampsession activity timestampsession lifetime timestampWebSEAL automatically adds specific data from the user session to each failover authentication cookie. WebSEAL can be configured to add additional information from the client data maintained in the credential cache. By default WebSEAL adds the following data to each cookie:User name This name corresponds to the name used to identify the user in the user registry When an authenticated user has used the WebSEAL switch user function to obtain the effective identity of another user, the identity of the other user is not added to the cookie. Only the original authenticated user identity is added to the cookie.Authentication method The authentication method used to authenticate the user to WebSEAL.Cookie creation time The system time when the cookie was created. WebSEAL also creates an attribute list containing additional data. By default, the attribute list contains one value:Authentication strength level An integer value that corresponds to the WebSEAL authentication strength level (also an integer value) that is assigned on the local WebSEAL server to the current authentication method. Authentication strength, also known as step-up authentication, enables a user to authenticate to a different authentication method without having to logout.WebSEAL defines additional user data that can be added to the cookie attribute list:Session lifetime timestamp When a user authenticates, WebSEAL tracks the age or lifetime of the user entry in the WebSEAL session cache. The session lifetime timestamp consists of the current time, advanced by the number of seconds configured for the maximum time that a user's session data can remain in the session cache. When the current system time exceeds the timestamp value, WebSEAL invalidates the user's entry in the session cache (including the user credentials). WebSEAL can be configured to add the session lifetime timestamp to the cookie. When this timestamp is added to the cookie, the session lifetime timer can be preserved across failover events. WebSEAL administrators can choose whether or not to reset the client's session timer when the client session is established on a replicated server. Note that successful use of this feature is dependent on synchronization of clocks between replicated WebSEAL servers. If clock skew becomes great, sessions can expire at unintended times.Session activity timestamp The session activity timestamp is a time value placed as an attribute in the failover cookie when it is created at the server that responds to the initial request. This timestamp differs from the session inactivity timeout maintained for the WebSEAL session cache. The system activity timestamp for failover cookies is calculated by combining the Current system time with the Maximum time. The timestamp is updated at a frequency determined by the Time interval. Current system timeThe current time on the WebSEAL server in the HH:MMformat. Example value: 13:30.Maximum timeThe number of seconds that a user's session can remain inactive ([session], inactive-timeout). Example value: 600Time intervalThe number of seconds between updates to the failover authentication cookie ([failover], failover-update-cookie). Example value: 300 The timestamp value in the failover cookie in the preceding example is 13:40. If a future request during this session is failed-over from Server 1 to Server2, Server2 accepts the request only if the time on Server2 is less than 13:40. If the time on Server2 is greater than or equal to 13:40, Server2 rejects the request and prompts the user to login to Server2. The setting for the interval between failover cookie updates affects performance. Administrators must choose a balance between optimal performance and absolute accuracy of the timestamp in the cookie. To keep the timestamp most accurate, failover cookies should be updated every time the user makes a request. However, frequent updating of cookie contents incurs overhead and decreases performance. Each administrator must choose an interval that best fits the WebSEAL deployment. In some cases, an update of the failover cookie with every user request is appropriate. In other cases, the administrator might choose to never update the timestamp in the failover cookie.Additional extended attributes Administrators can configure WebSEAL to insert a customized set of attributes into a failover cookie. Attributes can be specified individually or in a group. To specify a group of attributes, use wildcard pattern matching in configuration file entries. This feature is useful in deployments that also use customized authentication modules to insert special attributes into a user credential. By specifying those attributes in the WebSEAL configuration file, the administrator can ensure that the attributes are available to add to the recreated user credential during failover authentication.The maximum size of a failover authentication cookie is 4 kilobytes (4096 bytes)Configuration instructions in this chapter:Adding the authentication strength levelAddition of session lifetime timestampAdding the session activity timestampAddition of an interval for updating the activity timestampAddition of extended attributesFailover authentication concepts

Addition of data to a failover cookie

WebSEAL automatically adds specific data from the user session to each failover authentication cookie. WebSEAL can be configured to add additional information from the client data maintained in the credential cache.

By default WebSEAL adds the following data to each cookie:

User name

This name corresponds to the name used to identify the user in the user registry

Note: When an authenticated user has used the WebSEAL switch user function to obtain the effective identity of another user, the identity of the other user is not added to the cookie. Only the original authenticated user identity is added to the cookie.

Authentication method

The authentication method used to authenticate the user to WebSEAL.

Cookie creation time

The system time when the cookie was created.

WebSEAL also creates an attribute list containing additional data. By default, the attribute list contains one value:

Authentication strength level

An integer value that corresponds to the WebSEAL authentication strength level (also an integer value) that is assigned on the local WebSEAL server to the current authentication method. Authentication strength, also known as step-up authentication, enables a user to authenticate to a different authentication method without having to logout.

WebSEAL defines additional user data that can be added to the cookie attribute list:

Session lifetime timestamp

When a user authenticates, WebSEAL tracks the age or lifetime of the user entry in the WebSEAL session cache. The session lifetime timestamp consists of the current time, advanced by the number of seconds configured for the maximum time that a user's session data can remain in the session cache. When the current system time exceeds the timestamp value, WebSEAL invalidates the user's entry in the session cache (including the user credentials).

WebSEAL can be configured to add the session lifetime timestamp to the cookie. When this timestamp is added to the cookie, the session lifetime timer can be preserved across failover events. WebSEAL administrators can choose whether or not to reset the client's session timer when the client session is established on a replicated server.

Note that successful use of this feature is dependent on synchronization of clocks between replicated WebSEAL servers. If clock skew becomes great, sessions can expire at unintended times.

Session activity timestamp

The session activity timestamp is a time value placed as an attribute in the failover cookie when it is created at the server that responds to the initial request.

This timestamp differs from the session inactivity timeout maintained for the WebSEAL session cache. The system activity timestamp for failover cookies is calculated by combining the Current system time with the Maximum time. The timestamp is updated at a frequency determined by the Time interval.

Current® system time

The current time on the WebSEAL server in the HH:MMformat.

Example value: 13:30.

Maximum time

The number of seconds that a user's session can remain inactive ([session], inactive-timeout).

Example value: 600

Time interval

The number of seconds between updates to the failover authentication cookie ([failover], failover-update-cookie).

Example value: 300

The timestamp value in the failover cookie in the preceding example is 13:40. If a future request during this session is failed-over from Server 1 to Server2, Server2 accepts the request only if the time on Server2 is less than 13:40. If the time on Server2 is greater than or equal to 13:40, Server2 rejects the request and prompts the user to login to Server2.

The setting for the interval between failover cookie updates affects performance. Administrators must choose a balance between optimal performance and absolute accuracy of the timestamp in the cookie. To keep the timestamp most accurate, failover cookies should be updated every time the user makes a request. However, frequent updating of cookie contents incurs overhead and decreases performance.

Each administrator must choose an interval that best fits the WebSEAL deployment. In some cases, an update of the failover cookie with every user request is appropriate. In other cases, the administrator might choose to never update the timestamp in the failover cookie.

Additional extended attributes

Administrators can configure WebSEAL to insert a customized set of attributes into a failover cookie. Attributes can be specified individually or in a group. To specify a group of attributes, use wildcard pattern matching in configuration file entries.

This feature is useful in deployments that also use customized authentication modules to insert special attributes into a user credential. By specifying those attributes in the WebSEAL configuration file, the administrator can ensure that the attributes are available to add to the recreated user credential during failover authentication.

Note: The maximum size of a failover authentication cookie is 4 kilobytes (4096 bytes)

Configuration instructions in this chapter:

Adding the authentication strength level

Addition of session lifetime timestamp

Adding the session activity timestamp

Addition of an interval for updating the activity timestamp

Addition of extended attributes

Parent topic: Failover authentication concepts

Extraction of data from a failover cookieExtraction of data from a failover cookiefailover cookiesextracting datafailover authenticationextracting cookie dataWhen a failover authentication event occurs, a replica WebSEAL server receives a failover authentication cookie and by default extracts the following data from each cookie:User nameAuthentication methodCookie creation time WebSEAL first determines if the cookie is valid by subtracting the cookie creation time from the system time, and comparing this value against the WebSEAL configuration file entry for failover cookie lifetime. If the cookie lifetime has been exceeded, the cookie is not valid, and failover authentication is not attempted. If the cookie lifetime has not been exceeded, WebSEAL uses the user name and authentication method to authenticate the user and build a user credential. WebSEAL next checks configuration settings to determine if additional cookie data should be extracted and evaluated. Note that the WebSEAL server does not by default extract any other attributes from the failover authentication cookie. Each additional attribute to be extracted must be specified in the WebSEAL configuration file. Wildcard pattern matching can be used to obtain groups of attributes.WebSEAL can be configured to extract the following defined attributes:Authentication strength level When this value is extracted, WebSEAL uses it to ensure that the user is authenticated with the authentication method necessary to maintain the specified authentication level. Note that WebSEAL can obtain authentication strength levels from several different places: Failover cookieFailover authentication libraryCross-domain authentication serviceEntitlements service The authentication strength level extracted from the failover cookie takes precedence over levels obtained from the other places.Session lifetime timestamp WebSEAL can use this timestamp to determine if the user's entry in the original server's session cache would have expired. If it would have, WebSEAL discards the cookie and all its potential credential attributes. The session lifetime is not preserved, and the user is prompted to log in.Session inactivity timestamp WebSEAL can use this timestamp to determine if the user's entry in the original server's session cache would have been inactive for too long. If it would have, WebSEAL discards the cookie and all its potential credential attributes. The session lifetime is not preserved, and the user is prompted to log in. Successful use of these timestamps requires synchronization of clocks between replicated WebSEAL servers. If clock skew becomes great, sessions will expire or become inactive at unintended times.Additional extended attributes These include user-defined customized attributes, such as those generated by cross-domain authentication services. WebSEAL adds the attributes to the user credential.Attributes that are not specified in the WebSEAL configuration file will be ignored and not extracted. In addition, administrators can specify that certain attributes must be ignored during failover cookie extraction. Although ignore is the default behavior, this specification can be useful, for example, to ensure that user attributes are obtained from the user registry instead of from the failover cookie.Failover authentication concepts

Extraction of data from a failover cookie

When a failover authentication event occurs, a replica WebSEAL server receives a failover authentication cookie and by default extracts the following data from each cookie:

User name

Authentication method

Cookie creation time

WebSEAL first determines if the cookie is valid by subtracting the cookie creation time from the system time, and comparing this value against the WebSEAL configuration file entry for failover cookie lifetime.

If the cookie lifetime has been exceeded, the cookie is not valid, and failover authentication is not attempted. If the cookie lifetime has not been exceeded, WebSEAL uses the user name and authentication method to authenticate the user and build a user credential.

WebSEAL next checks configuration settings to determine if additional cookie data should be extracted and evaluated. Note that the WebSEAL server does not by default extract any other attributes from the failover authentication cookie. Each additional attribute to be extracted must be specified in the WebSEAL configuration file. Wildcard pattern matching can be used to obtain groups of attributes.

WebSEAL can be configured to extract the following defined attributes:

Authentication strength level

When this value is extracted, WebSEAL uses it to ensure that the user is authenticated with the authentication method necessary to maintain the specified authentication level.

Note that WebSEAL can obtain authentication strength levels from several different places:

Failover cookie

Failover authentication library

Cross-domain authentication service

Entitlements service

The authentication strength level extracted from the failover cookie takes precedence over levels obtained from the other places.

Session lifetime timestamp

WebSEAL can use this timestamp to determine if the user's entry in the original server's session cache would have expired. If it would have, WebSEAL discards the cookie and all its potential credential attributes. The session lifetime is not preserved, and the user is prompted to log in.

Session inactivity timestamp

WebSEAL can use this timestamp to determine if the user's entry in the original server's session cache would have been inactive for too long. If it would have, WebSEAL discards the cookie and all its potential credential attributes. The session lifetime is not preserved, and the user is prompted to log in.

Note: Successful use of these timestamps requires synchronization of clocks between replicated WebSEAL servers. If clock skew becomes great, sessions will expire or become inactive at unintended times.

Additional extended attributes

These include user-defined customized attributes, such as those generated by cross-domain authentication services. WebSEAL adds the attributes to the user credential.

Attributes that are not specified in the WebSEAL configuration file will be ignored and not extracted. In addition, administrators can specify that certain attributes must be ignored during failover cookie extraction. Although ignore is the default behavior, this specification can be useful, for example, to ensure that user attributes are obtained from the user registry instead of from the failover cookie.

Parent topic: Failover authentication concepts

Domain-wide failover authenticationDomain-wide failover authenticationfailover authenticationdomain-wideauthenticationfailoverdomain-wideWebSEAL supports an optional configuration that enables failover authentication cookies to be marked as available for use during failover authentication to any and all other WebSEAL servers in the DNS domain. This configuration option enables failover authentication cookies to be used in deployments that do not necessarily have a load balancer and replicated WebSEAL servers.When a client session goes through a failover authentication event to a replicated WebSEAL server, the client continues to access the same set of protected resources. When a client session goes through a failover authentication event to a WebSEAL server that is not replicated, it is possible that a different set of resources will be available to the client. In large deployments, this partitioning of resources within the DNS domain is common. This partitioning can be done for performance reasons and for administrative purposes.Domain-wide failover authentication can be used to redirect a client to another WebSEAL server at a time when the client's requests have led it to request a resource that is not available through the local WebSEAL server. In this case, the client (browser) is redirected to another WebSEAL server. The receiving WebSEAL server can be configured to look for failover authentication cookies. The WebSEAL server attempts to authenticate the client and recognizes the failover authentication cookie. By using the cookie, the WebSEAL server does not need to prompt the client for login information, but instead can establish a session with the client and construct a valid set of user credentials.Enabling domain-wide failover authentication introduces additional security risks to the WebSEAL deployment, because the failover cookie can be sent to any server that is in the same DNS domain as the WebSEAL server. If an attacker controls any Web server in the domain or can compromise the DNS server for the domain, they can hijack failover cookies and impersonate users.Configuration instructions in this chapter:Enabling domain-wide failover cookiesFailover authentication concepts

Domain-wide failover authentication

WebSEAL supports an optional configuration that enables failover authentication cookies to be marked as available for use during failover authentication to any and all other WebSEAL servers in the DNS domain. This configuration option enables failover authentication cookies to be used in deployments that do not necessarily have a load balancer and replicated WebSEAL servers.

When a client session goes through a failover authentication event to a replicated WebSEAL server, the client continues to access the same set of protected resources. When a client session goes through a failover authentication event to a WebSEAL server that is not replicated, it is possible that a different set of resources will be available to the client. In large deployments, this partitioning of resources within the DNS domain is common. This partitioning can be done for performance reasons and for administrative purposes.

Domain-wide failover authentication can be used to redirect a client to another WebSEAL server at a time when the client's requests have led it to request a resource that is not available through the local WebSEAL server. In this case, the client (browser) is redirected to another WebSEAL server. The receiving WebSEAL server can be configured to look for failover authentication cookies. The WebSEAL server attempts to authenticate the client and recognizes the failover authentication cookie. By using the cookie, the WebSEAL server does not need to prompt the client for login information, but instead can establish a session with the client and construct a valid set of user credentials.

Note: Enabling domain-wide failover authentication introduces additional security risks to the WebSEAL deployment, because the failover cookie can be sent to any server that is in the same DNS domain as the WebSEAL server. If an attacker controls any Web server in the domain or can compromise the DNS server for the domain, they can hijack failover cookies and impersonate users.

Configuration instructions in this chapter:

Enabling domain-wide failover cookies

Parent topic: Failover authentication concepts

Failover authentication configurationFailover authentication configurationfailover authenticationconfigurationThis section contains the following topics:See also Failover authentication concepts.Failover solutionsUse the failover cookie solution to maintain session state in clustered environments.Failover authentication conceptsFailover for non-sticky failover environmentsChange password operation in a failover environmentConfiguring failover authenticationYou can configure WebSEAL for failover authentication.Protocol for failover cookiesGenerating a key pair to encrypt and decrypt cookie dataSpecifying the failover cookie lifetimeSpecifying UTF-8 encoding on cookie stringsAdding the authentication strength levelReissue of missing failover cookiesAddition of session lifetime timestampAdding the session activity timestampAddition of an interval for updating the activity timestampAddition of extended attributesAttributes for extractionEnabling domain-wide failover cookiesEnabling compatibility for failover cookiesSecurity Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode failover cookies. Failover cookies that are generated with this default cipher are not compatible with failover cookies that are generated by earlier versions of WebSEAL.Validation of a lifetime timestampValidation of an activity timestamp

Failover authentication configuration

This section contains the following topics:

See also Failover authentication concepts.

Configuring failover authentication
You can configure WebSEAL for failover authentication.

Protocol for failover cookies

Generating a key pair to encrypt and decrypt cookie data

Specifying the failover cookie lifetime

Specifying UTF-8 encoding on cookie strings

Adding the authentication strength level

Reissue of missing failover cookies

Addition of session lifetime timestamp

Adding the session activity timestamp

Addition of an interval for updating the activity timestamp

Addition of extended attributes

Attributes for extraction

Enabling domain-wide failover cookies

Enabling compatibility for failover cookies
Security Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode failover cookies. Failover cookies that are generated with this default cipher are not compatible with failover cookies that are generated by earlier versions of WebSEAL.

Validation of a lifetime timestamp

Validation of an activity timestamp

Parent topic: Failover solutions

Related concepts:

Failover authentication concepts

Failover for non-sticky failover environments

Change password operation in a failover environment

Configuring failover authenticationConfiguring failover authenticationYou can configure WebSEAL for failover authentication.failover authenticationconfiguration To configure failover authentication, complete the following tasks:For more information about the configuration entries that are related to these tasks, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.Stop the WebSEAL server.To enable failover authentication, complete each of the following tasks:Protocol for failover cookiesGenerating a key pair to encrypt and decrypt cookie dataSpecifying the failover cookie lifetimeSpecifying UTF-8 encoding on cookie stringsAdding the authentication strength levelReissue of missing failover cookiesOptionally, you can configure WebSEAL to maintain session state across failover authentication sessions. If this configuration is appropriate for your deployment, complete the following instructions:Addition of session lifetime timestampAdding the session activity timestampAddition of an interval for updating the activity timestampOptionally, you can configure WebSEAL to add extended attributes to the failover cookie:Addition of extended attributesWhen WebSEAL is configured to add attributes to the failover cookie, you must configure WebSEAL to extract the attributes when reading the cookie:Attributes for extractionOptionally, you can enable failover authentication cookies for use on any WebSEAL server in the domain. If this configuration is appropriate for your deployment, see:Enabling domain-wide failover cookiesTo maintain compatibility with failover authentication cookies generated by WebSEAL servers from versions before version 8.0, complete the instructions in Enabling compatibility for failover cookiesSecurity Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode failover cookies. Failover cookies that are generated with this default cipher are not compatible with failover cookies that are generated by earlier versions of WebSEAL..To maintain compatibility with failover authentication cookies generated by WebSEAL servers from versions before version 6.0, complete the following instructions: Specifying UTF-8 encoding on cookie stringsValidation of a lifetime timestampValidation of an activity timestampAfter completing all the instructions applicable to your deployment, restart the WebSEAL server.Failover authentication configuration

Configuring failover authentication

You can configure WebSEAL for failover authentication.

About this task

To configure failover authentication, complete the following tasks:

Note:

For more information about the configuration entries that are related to these tasks, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.

Procedure

Stop the WebSEAL server.

To enable failover authentication, complete each of the following tasks:

Protocol for failover cookies

Generating a key pair to encrypt and decrypt cookie data

Specifying the failover cookie lifetime

Specifying UTF-8 encoding on cookie strings

Adding the authentication strength level

Reissue of missing failover cookies

Optionally, you can configure WebSEAL to maintain session state across failover authentication sessions. If this configuration is appropriate for your deployment, complete the following instructions:

Addition of session lifetime timestamp

Adding the session activity timestamp

Addition of an interval for updating the activity timestamp

Optionally, you can configure WebSEAL to add extended attributes to the failover cookie:

Addition of extended attributes

When WebSEAL is configured to add attributes to the failover cookie, you must configure WebSEAL to extract the attributes when reading the cookie:

Attributes for extraction

Optionally, you can enable failover authentication cookies for use on any WebSEAL server in the domain. If this configuration is appropriate for your deployment, see:

Enabling domain-wide failover cookies

To maintain compatibility with failover authentication cookies generated by WebSEAL servers from versions before version 8.0, complete the instructions in Enabling compatibility for failover cookies.

To maintain compatibility with failover authentication cookies generated by WebSEAL servers from versions before version 6.0, complete the following instructions:

Specifying UTF-8 encoding on cookie strings

Validation of a lifetime timestamp

Validation of an activity timestamp

After completing all the instructions applicable to your deployment, restart the WebSEAL server.

Parent topic: Failover authentication configuration

Protocol for failover cookiesProtocol for failover cookiesfailover authenticationenablingfailover-auth stanza entryfailover cookiesprotocolFailover authentication cookies are disabled by default. To enable failover cookies, edit the WebSEAL configuration file.In the [failover] stanza, specify a value that instructs WebSEAL how to handle requests with failover cookies. The following table shows the valid values.Supported protocols for failover cookiesStanza EntryDescriptionfailover-auth = httpFailover cookies enabled over HTTP protocol.failover-auth = httpsFailover cookies enabled over HTTPS (SSL) protocol.failover-auth = bothFailover cookies enabled over both HTTP and HTTPS (SSL) protocol.Enabling failover authentication to either HTTP or HTTPS causes cookies to be written to clients connecting over all protocols. The value specified in the failover-auth stanza entry dictates the protocol over which cookies will be accepted for authentication during a failover authentication event.Failover authentication configuration

Protocol for failover cookies

Failover authentication cookies are disabled by default. To enable failover cookies, edit the WebSEAL configuration file.

In the [failover] stanza, specify a value that instructs WebSEAL how to handle requests with failover cookies. The following table shows the valid values.

Table 54. Supported protocols for failover cookies

Stanza Entry
Description

failover-auth = http

Failover cookies enabled over HTTP protocol.

failover-auth = https

Failover cookies enabled over HTTPS (SSL) protocol.

failover-auth = both

Failover cookies enabled over both HTTP and HTTPS (SSL) protocol.

Note: Enabling failover authentication to either HTTP or HTTPS causes cookies to be written to clients connecting over all protocols. The value specified in the failover-auth stanza entry dictates the protocol over which cookies will be accepted for authentication during a failover authentication event.

Parent topic: Failover authentication configuration

Generating a key pair to encrypt and decrypt cookie data Generating a key pair to encrypt and decrypt cookie data failover-cookies-keyfilecdsso_key_genfailover authenticationencrypting/decrypting cookie dataLMISSO keys management pageUse the LMI to generate a key pair that can secure the cookie data. WebSEAL provides this utility. You can generate a symmetric key pair that can encrypt and decrypt the data in a failover cookie.Do not reuse key pairs (used to encrypt and decrypt cookie data) generated for a specific load-balanced environment (configured for failover) in any other load-balanced environments. Always generate unique key pairs for each load-balanced environment configured for failover authentication.If you do not configure WebSEAL to encrypt failover authentication cookies, and you have enabled failover authentication, WebSEAL generates an error and refuses to start. Failover authentication cookies must be encrypted.Use the LMI to generate the key file, such as ws.key. Use the SSO Keys management page to create the key file. To access this page, go to Secure - Reverse Proxy Settings > Global Keys > SSO Keys.Edit the WebSEAL configuration file. In the [failover] stanza, specify the key file.[failover] failover-cookies-keyfile = keyfile_nameManually copy the key file to each of the remaining replicated servers.On each replicated server, edit the WebSEAL configuration file to supply the correct path name to failover-cookies-keyfile in the [failover] stanza.Failover authentication configuration

Generating a key pair to encrypt and decrypt cookie data

About this task

Use the LMI to generate a key pair that can secure the cookie data. WebSEAL provides this utility. You can generate a symmetric key pair that can encrypt and decrypt the data in a failover cookie.

Note:

Do not reuse key pairs (used to encrypt and decrypt cookie data) generated for a specific load-balanced environment (configured for failover) in any other load-balanced environments. Always generate unique key pairs for each load-balanced environment configured for failover authentication.

If you do not configure WebSEAL to encrypt failover authentication cookies, and you have enabled failover authentication, WebSEAL generates an error and refuses to start. Failover authentication cookies must be encrypted.

Procedure

Use the LMI to generate the key file, such as ws.key. Use the SSO Keys management page to create the key file. To access this page, go to Secure - Reverse Proxy Settings > Global Keys > SSO Keys.

Edit the WebSEAL configuration file. In the [failover] stanza, specify the key file.

[failover]
failover-cookies-keyfile = keyfile_name

Manually copy the key file to each of the remaining replicated servers.

On each replicated server, edit the WebSEAL configuration file to supply the correct path name to failover-cookies-keyfile in the [failover] stanza.

Parent topic: Failover authentication configuration

Specifying the failover cookie lifetime Specifying the failover cookie lifetime failover-cookie-lifetime stanza entryfailover authenticationconfigure cookie lifetime Specify the failover cookie lifetime value in the WebSEAL configuration file. Edit the WebSEAL configuration file. Specify the valid lifetime (in minutes) for the failover cookie.The default lifetime is 60 minutes. For example: [failover] failover-cookie-lifetime = 60 NOTE: WebSEAL does not use the expires attribute that is contained in a standard HTTP failover cookie. Instead it uses an expiration value that is contained within the token itself. As a result, the lifetime of the cookie expires when the session ends, such as exiting the browser, or when the token expires.Failover authentication configuration

Specifying the failover cookie lifetime

About this task

Specify the failover cookie lifetime value in the WebSEAL configuration file.

Procedure

Edit the WebSEAL configuration file. Specify the valid lifetime (in minutes) for the failover cookie. The default lifetime is 60 minutes. For example:

[failover]
failover-cookie-lifetime = 60

NOTE: WebSEAL does not use the expires attribute that is contained in a standard HTTP failover cookie. Instead it uses an expiration value that is contained within the token itself. As a result, the lifetime of the cookie expires when the session ends, such as exiting the browser, or when the token expires.

Parent topic: Failover authentication configuration

Specifying UTF-8 encoding on cookie stringsSpecifying UTF-8 encoding on cookie stringsfailover authenticationutf-8 encoding for failover cookiescookiesstringsUTF-8 encoding Use UTF-8 when user names or credential attributes in the cookie are not encoded in the same code page as the one that the WebSEAL server is using. By default, WebSEAL servers use UTF-8 encoding. When all WebSEAL servers in the WebSEAL deployment use UTF-8 encoding, leave this value at the default setting of "yes".Edit the WebSEAL configuration file. Specify whether or not WebSEAL should use UTF-8 encoding on strings within the failover cookies.[failover] use-utf8 = yes The default value is "yes". Failover authentication configuration

Specifying UTF-8 encoding on cookie strings

About this task

Use UTF-8 when user names or credential attributes in the cookie are not encoded in the same code page as the one that the WebSEAL server is using. By default, WebSEAL servers use UTF-8 encoding. When all WebSEAL servers in the WebSEAL deployment use UTF-8 encoding, leave this value at the default setting of "yes".

Procedure

Edit the WebSEAL configuration file. Specify whether or not WebSEAL should use UTF-8 encoding on strings within the failover cookies.

[failover]
use-utf8 = yes

The default value is "yes".

Parent topic: Failover authentication configuration

Adding the authentication strength levelAdding the authentication strength levelfailover authenticationadding authentication levelAUTHENTICATION_LEVEL stanza entry To specify authentication strength level in the failover authentication cookie, add the authentication level to the WebSEAL configuration file. Use the AUTHENTICATON_LEVEL stanza entry as follows:[failover-add-attributes] AUTHENTICATION_LEVEL = add The actual value for AUTHENTICATION_LEVEL is an integer that WebSEAL tracks internally. You do not need to specify the integer in this stanza.Failover authentication configuration

Adding the authentication strength level

About this task

To specify authentication strength level in the failover authentication cookie, add the authentication level to the WebSEAL configuration file.

Procedure

Use the AUTHENTICATON_LEVEL stanza entry as follows:

[failover-add-attributes]
AUTHENTICATION_LEVEL = add

The actual value for AUTHENTICATION_LEVEL is an integer that WebSEAL tracks internally. You do not need to specify the integer in this stanza.

Parent topic: Failover authentication configuration

Reissue of missing failover cookiesReissue of missing failover cookiesfailover authenticationreissuing missing failover cookiesfailover cookiesresissuing missing failover cookiesreissue-mission-failover-cookie stanza entryIn certain proxied environments, it is possible for a client with a valid session to lose a failover cookie. Such a client can continue to maintain a session with the initial WebSEAL system. However, without the failover cookie, the client cannot failover to a new system.You can use the reissue-missing-failover-cookie stanza entry in the [failover] stanza of the WebSEAL configuration file to help ensure that a client always has a failover cookie for the duration of the session when failover authentication is enabled. Valid values are “yes” (enable) and “no” (disable).The failover cookie reissue mechanism is disabled by default. For example:[failover] reissue-missing-failover-cookie = noWhen reissue-missing-failover-cookie = yes, WebSEAL saves any failover cookie generated for a client in the WebSEAL session cache entry for that client. If previous cookie contents are already stored in the cache entry, they are removed and replaced with the new cookie data.If the client makes a subsequent request to that WebSEAL server and does not supply the failover cookie in the request, WebSEAL reissues the cached original failover cookie in the response to the client, based on the following conditions:The failover cookie reissue mechanism is enabled: reissue-missing-failover-cookie = yesThe client has a valid session.Failover authentication is enabled for this client type.A failover cookie for this client has been stored in the session cache entry for that client.No other mechanism has generated a new failover cookie for this request.Failover authentication configuration

Reissue of missing failover cookies

In certain proxied environments, it is possible for a client with a valid session to lose a failover cookie. Such a client can continue to maintain a session with the initial WebSEAL system. However, without the failover cookie, the client cannot failover to a new system.

You can use the reissue-missing-failover-cookie stanza entry in the [failover] stanza of the WebSEAL configuration file to help ensure that a client always has a failover cookie for the duration of the session when failover authentication is enabled. Valid values are “yes” (enable) and “no” (disable).

The failover cookie reissue mechanism is disabled by default. For example:

[failover]
reissue-missing-failover-cookie = no

When reissue-missing-failover-cookie = yes, WebSEAL saves any failover cookie generated for a client in the WebSEAL session cache entry for that client. If previous cookie contents are already stored in the cache entry, they are removed and replaced with the new cookie data.

If the client makes a subsequent request to that WebSEAL server and does not supply the failover cookie in the request, WebSEAL reissues the cached original failover cookie in the response to the client, based on the following conditions:

The failover cookie reissue mechanism is enabled:

reissue-missing-failover-cookie = yes

The client has a valid session.

Failover authentication is enabled for this client type.

A failover cookie for this client has been stored in the session cache entry for that client.

No other mechanism has generated a new failover cookie for this request.

Parent topic: Failover authentication configuration

Addition of session lifetime timestampAddition of session lifetime timestampfailover authenticationsession lifetime timestampfailover cookiessession lifetime timestampsession-lifetime-timestamp stanza entryWebSEAL calculates the session lifetime timestamp by combining the following values: Current system time.Maximum lifetime in seconds that an entry is allowed to exist in the WebSEAL credential cache. This maximum lifetime in seconds is specified in the WebSEAL configuration file [session] stanza: [session] timeout = 3600To add this value to the failover authentication cookie, manually edit the WebSEAL configuration file and add the following entry:[failover-add-attributes] session-lifetime-timestamp = addWhen a failover incident occurs, the session lifetime value is used to determine the time remaining for the life of the user's session (the session lifetime value is not reset at failover). If the session lifetime has expired, the user must login.Note that this attribute cannot be set by wildcard matching. The exact entry session-lifetime-timestamp must be entered.Failover authentication configuration

Addition of session lifetime timestamp

WebSEAL calculates the session lifetime timestamp by combining the following values:

Current® system time.

Maximum lifetime in seconds that an entry is allowed to exist in the WebSEAL credential cache.

This maximum lifetime in seconds is specified in the WebSEAL configuration file [session] stanza:

[session]
timeout = 3600

To add this value to the failover authentication cookie, manually edit the WebSEAL configuration file and add the following entry:

[failover-add-attributes]
session-lifetime-timestamp = add

When a failover incident occurs, the session lifetime value is used to determine the time remaining for the life of the user's session (the session lifetime value is not reset at failover). If the session lifetime has expired, the user must login.

Note that this attribute cannot be set by wildcard matching. The exact entry session-lifetime-timestamp must be entered.

Parent topic: Failover authentication configuration

Adding the session activity timestampAdding the session activity timestampfailover authenticationsession activity timestamp WebSEAL calculates the session activity timestamp by adding together the following three values: Current system time. For example: 13:30Maximum time (seconds) that a user's session can remain inactive. The maximum lifetime for inactive cache entries is set in the [session] stanza in the WebSEAL configuration file. For exampleinactive-timeout stanza entrysession stanza [session] inactive-timeout = 600 The default value is 600 seconds.Time interval (seconds) between updates to the failover authentication cookie. This value is set in the [failover] stanza in the WebSEAL configuration file. For example:failover-update-cookie stanza entry [failover] failover-update-cookie = 300 The default value is -1 seconds. For more information, see Addition of an interval for updating the activity timestamp. The timestamp value in this example is 13:50. Edit the WebSEAL configuration file and add the following entry:session-activity-timestamp stanza entry[failover-add-attributes] session-activity-timestamp = addThe attribute cannot be set by wildcard matching. The exact entry session-activity-timestamp must be entered. When you set failover-update-cookie to a number greater than zero, ensure that you also set session-activity-timestamp = add. If you do not set session-activity-timestamp = add, WebSEAL decodes the failover cookie on each user access. This repetitive action could adversely affect performance.Failover authentication configuration

Adding the session activity timestamp

About this task

WebSEAL calculates the session activity timestamp by adding together the following three values:

Current® system time.

For example: 13:30

Maximum time (seconds) that a user's session can remain inactive.

The maximum lifetime for inactive cache entries is set in the [session] stanza in the WebSEAL configuration file. For example

[session]
inactive-timeout = 600

The default value is 600 seconds.

Time interval (seconds) between updates to the failover authentication cookie.

This value is set in the [failover] stanza in the WebSEAL configuration file. For example:

[failover]
failover-update-cookie = 300

The default value is -1 seconds. For more information, see Addition of an interval for updating the activity timestamp.

The timestamp value in this example is 13:50.

Procedure

Edit the WebSEAL configuration file and add the following entry:

[failover-add-attributes]
session-activity-timestamp = add

Note: The attribute cannot be set by wildcard matching. The exact entry session-activity-timestamp must be entered.

Note: When you set failover-update-cookie to a number greater than zero, ensure that you also set session-activity-timestamp = add. If you do not set session-activity-timestamp = add, WebSEAL decodes the failover cookie on each user access. This repetitive action could adversely affect performance.

Parent topic: Failover authentication configuration

Addition of an interval for updating the activity timestampAddition of an interval for updating the activity timestampfailover-update-cookie stanza entryOptionally, the session activity timestamp in the failover cookie can be updated during the user's session. This entry contains an integer value that specifies the interval (in seconds) used to update the failover cookie's activity timestamp. The default entry is:[failover] failover-update-cookie = -1When failover-update-cookie is set to 0, the last activity timestamp is updated with each request.When failover-update-cookie is set to an integer less than 0 (any negative number), the last activity timestamp is never updated.When failover-update-cookie is set to an integer greater than 0, the session activity timestamp in the cookie is updated at intervals of this number of seconds. The value chosen for this stanza entry can affect performance. See Addition of data to a failover cookie.When you set failover-update-cookie to a number greater than zero, ensure that you also set session-activity-timestamp = add. If you do not set session-activity-timestamp = add, WebSEAL will decode the failover cookie on each user access. This repetitive action could adversely affect performance. See Adding the session activity timestamp.Failover authentication configuration

Addition of an interval for updating the activity timestamp

Optionally, the session activity timestamp in the failover cookie can be updated during the user's session.

This entry contains an integer value that specifies the interval (in seconds) used to update the failover cookie's activity timestamp.

The default entry is:

[failover]
failover-update-cookie = -1

When failover-update-cookie is set to 0, the last activity timestamp is updated with each request.

When failover-update-cookie is set to an integer less than 0 (any negative number), the last activity timestamp is never updated.

When failover-update-cookie is set to an integer greater than 0, the session activity timestamp in the cookie is updated at intervals of this number of seconds.

The value chosen for this stanza entry can affect performance. See Addition of data to a failover cookie.

Note: When you set failover-update-cookie to a number greater than zero, ensure that you also set session-activity-timestamp = add. If you do not set session-activity-timestamp = add, WebSEAL will decode the failover cookie on each user access. This repetitive action could adversely affect performance. See Adding the session activity timestamp.

Parent topic: Failover authentication configuration

Addition of extended attributesAddition of extended attributesfailover authenticationadding extended attributesfailover cookiesextended attributesWebSEAL can optionally be configured to place a copy of specified extended attributes from a user credential into a failover authentication cookie. No extended attributes are configured by default. To add extended attributes, add entries to the [failover-add-attributes] stanza in the WebSEAL configuration file. The syntax is:[failover-add-attributes] attribute_pattern = add The attribute_pattern can be either a specific attribute name, or a not case sensitive wildcard expression that matches more than one attribute name. For example, to specify all attributes with the prefix tagvalue_, add the following entry:[failover-add-attributes] tagvalue_* = addThe order of the stanza entries is important. Rules that appear earlier in the [failover-add-attributes] stanza take priority over those placed later in the stanza.Attributes that do not match any of the wildcard patterns, or are not explicitly specified, are not added to the failover cookie.Failover authentication configuration

Addition of extended attributes

WebSEAL can optionally be configured to place a copy of specified extended attributes from a user credential into a failover authentication cookie. No extended attributes are configured by default.

To add extended attributes, add entries to the [failover-add-attributes] stanza in the WebSEAL configuration file. The syntax is:

[failover-add-attributes]
attribute_pattern = add

The attribute_pattern can be either a specific attribute name, or a not case sensitive wildcard expression that matches more than one attribute name. For example, to specify all attributes with the prefix tagvalue_, add the following entry:

[failover-add-attributes]
tagvalue_* = add

The order of the stanza entries is important. Rules that appear earlier in the [failover-add-attributes] stanza take priority over those placed later in the stanza.

Attributes that do not match any of the wildcard patterns, or are not explicitly specified, are not added to the failover cookie.

Parent topic: Failover authentication configuration

Attributes for extractionAttributes for extractionfailover authenticationspecifying attributes for extractionfailover-restore-attributes stanzaWebSEAL can optionally be configured to extract attributes from a failover authentication cookie and place them into a user credential. No attributes are configured for extraction by default. Attributes to be extracted are declared in the [failover-restore-attributes] stanza in the WebSEAL configuration file. The syntax is:[failover-restore-attributes] attribute_pattern = {preserve|refresh} The value preserve tells WebSEAL to extract the attribute and add it to the credential.The value refresh tells WebSEAL to ignore the attribute, and not extract it from the cookie.The attribute_pattern can be either a specific attribute name, or a case-insensitive wildcard expression that matches more than one attribute name. For example, to extract all attributes with the prefix tagvalue_, add the following entry:[failover-restore-attributes] tagvalue_* = preserve Attributes that do not match any patterns specified with the preserve value are not extracted from the failover authentication cookie.The order of the stanza entries is important. Rules that appear earlier in [failover-restore-attributes] take priority over those placed later in the stanza.The following attributes cannot be matched by a wildcard pattern, but must be explicitly defined for extraction:Authentication level [failover-restore-attributes] AUTHENTICATION_LEVEL = preserveSession lifetime timestamp [failover-restore-attributes] session-lifetime-timestamp = preserveSession activity timestamp [failover-restore-attributes] session-activity-timestamp = preserveFailover authentication configuration

Attributes for extraction

WebSEAL can optionally be configured to extract attributes from a failover authentication cookie and place them into a user credential. No attributes are configured for extraction by default.

Attributes to be extracted are declared in the [failover-restore-attributes] stanza in the WebSEAL configuration file. The syntax is:

[failover-restore-attributes]
attribute_pattern = {preserve|refresh}

The value preserve tells WebSEAL to extract the attribute and add it to the credential.

The value refresh tells WebSEAL to ignore the attribute, and not extract it from the cookie.

The attribute_pattern can be either a specific attribute name, or a case-insensitive wildcard expression that matches more than one attribute name. For example, to extract all attributes with the prefix tagvalue_, add the following entry:

[failover-restore-attributes]
tagvalue_* = preserve

Attributes that do not match any patterns specified with the preserve value are not extracted from the failover authentication cookie.

The order of the stanza entries is important. Rules that appear earlier in [failover-restore-attributes] take priority over those placed later in the stanza.

The following attributes cannot be matched by a wildcard pattern, but must be explicitly defined for extraction:

Authentication level

[failover-restore-attributes]
AUTHENTICATION_LEVEL = preserve

Session lifetime timestamp

[failover-restore-attributes]
session-lifetime-timestamp = preserve

Session activity timestamp

[failover-restore-attributes]
session-activity-timestamp = preserve

Parent topic: Failover authentication configuration

Enabling domain-wide failover cookies Enabling domain-wide failover cookies enable-failover-cookie-for-domain stanza entryfailover authenticationenabling domain-wide cookies You can allow a failover authentication cookie to be used by any WebSEAL server within the same domain as the WebSEAL server that creates the cookie. This feature is controlled by a stanza entry in the [failover] stanza. By default, domain-wide failover cookie functionality is disabled: [failover] enable-failover-cookie-for-domain = no To enable the domain-wide failover cookie functionality, set enable-failover-cookie-for-domain to "yes":[failover] enable-failover-cookie-for-domain = yes For information on the effects of enabling this stanza entry, see Domain-wide failover authentication.Failover authentication configuration

Enabling domain-wide failover cookies

About this task

You can allow a failover authentication cookie to be used by any WebSEAL server within the same domain as the WebSEAL server that creates the cookie. This feature is controlled by a stanza entry in the [failover] stanza.

By default, domain-wide failover cookie functionality is disabled:

[failover]
enable-failover-cookie-for-domain = no

Procedure

To enable the domain-wide failover cookie functionality, set enable-failover-cookie-for-domain to "yes":

[failover]
enable-failover-cookie-for-domain = yes

For information on the effects of enabling this stanza entry, see Domain-wide failover authentication.

Parent topic: Failover authentication configuration

Enabling compatibility for failover cookiesEnabling compatibility for failover cookiesSecurity Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode failover cookies. Failover cookies that are generated with this default cipher are not compatible with failover cookies that are generated by earlier versions of WebSEAL.pre-800-compatible-tokens stanza entryfailover cookiescompatibilityenabling compatibility If you integrate failover authentication cookies with WebSEAL servers that include versions of Security Access Manager earlier than version 8.0, you can use the pre-800-compatible-tokens stanza entry in the [server] stanza to enable compatibility. Compatibility with previous versions of WebSEAL is not enabled by default:[server] pre-800-compatible-tokens = no To enable compatibility, set pre-800-compatible-tokens to yes:[server] pre-800-compatible-tokens = yes Failover authentication configuration

Enabling compatibility for failover cookies

Security Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode failover cookies. Failover cookies that are generated with this default cipher are not compatible with failover cookies that are generated by earlier versions of WebSEAL.

About this task

If you integrate failover authentication cookies with WebSEAL servers that include versions of Security Access Manager earlier than version 8.0, you can use the pre-800-compatible-tokens stanza entry in the [server] stanza to enable compatibility.

Compatibility with previous versions of WebSEAL is not enabled by default:

[server]
pre-800-compatible-tokens = no

Procedure

To enable compatibility, set pre-800-compatible-tokens to yes:

[server]
pre-800-compatible-tokens = yes

Parent topic: Failover authentication configuration

Validation of a lifetime timestampValidation of a lifetime timestampfailover-require-lifetime-timestamp-validation stanza entrylifetime timestamp validationWebSEAL servers can optionally be configured to require that each failover authentication cookie contain a session lifetime timestamp. The session lifetime timestamp is not required by default. The default configuration file entry is:[failover] failover-require-lifetime-timestamp-validation = no This stanza entry is used primarily for compatibility with prior versions of WebSEAL. Failover authentication cookies created by WebSEAL servers prior to version 5.1 do not contain this timestamp. For compatibility with failover cookies created by WebSEAL servers prior to version 5.1, set this entry to "no". When this value is "no", and the session lifetime timestamp is missing from the failover cookie, the receiving server will view the cookie as valid.When this value is "yes", and the session lifetime timestamp is missing from the failover cookie, the receiving server will view the cookie as not valid.When this value is either "no" or "yes", and the session lifetime timestamp is present in the failover cookie, the receiving server evaluates the timestamp. If the timestamp is not valid, the authentication fails. If the timestamp is valid, the authentication process proceeds.The session lifetime timestamp is configured separately from the session activity timestamp.Failover authentication configuration

Validation of a lifetime timestamp

WebSEAL servers can optionally be configured to require that each failover authentication cookie contain a session lifetime timestamp. The session lifetime timestamp is not required by default. The default configuration file entry is:

[failover]
failover-require-lifetime-timestamp-validation = no

This stanza entry is used primarily for compatibility with prior versions of WebSEAL. Failover authentication cookies created by WebSEAL servers prior to version 5.1 do not contain this timestamp. For compatibility with failover cookies created by WebSEAL servers prior to version 5.1, set this entry to "no".

When this value is "no", and the session lifetime timestamp is missing from the failover cookie, the receiving server will view the cookie as valid.

When this value is "yes", and the session lifetime timestamp is missing from the failover cookie, the receiving server will view the cookie as not valid.

When this value is either "no" or "yes", and the session lifetime timestamp is present in the failover cookie, the receiving server evaluates the timestamp. If the timestamp is not valid, the authentication fails. If the timestamp is valid, the authentication process proceeds.

Note: The session lifetime timestamp is configured separately from the session activity timestamp.

Parent topic: Failover authentication configuration

Validation of an activity timestampValidation of an activity timestampfailover-require-activity-timestamp-validation stanza entryactivity timestampWebSEAL servers can optionally be configured to require that each failover authentication cookie contain a session activity timestamp. The session activity timestamp is not required by default. The default configuration file entry is:[failover] failover-require-activity-timestamp-validation = no This stanza entry is used primarily for compatibility with prior versions of WebSEAL. When this value is "no", and the session activity timestamp is missing from the failover cookie, the receiving server will view the cookie as valid.When this value is "yes", and the session activity timestamp is missing from the failover cookie, the receiving server will view the cookie as not valid.When this value is either "no" or "yes", and the session activity timestamp is present in the failover cookie, the receiving server evaluates the timestamp. If the timestamp is not valid, the authentication fails. If the timestamp is valid, the authentication process proceeds.The session activity timestamp is configured separately from the session lifetime timestamp.Failover authentication configuration

Validation of an activity timestamp

WebSEAL servers can optionally be configured to require that each failover authentication cookie contain a session activity timestamp. The session activity timestamp is not required by default. The default configuration file entry is:

[failover]
failover-require-activity-timestamp-validation = no

This stanza entry is used primarily for compatibility with prior versions of WebSEAL.

When this value is "no", and the session activity timestamp is missing from the failover cookie, the receiving server will view the cookie as valid.

When this value is "yes", and the session activity timestamp is missing from the failover cookie, the receiving server will view the cookie as not valid.

When this value is either "no" or "yes", and the session activity timestamp is present in the failover cookie, the receiving server evaluates the timestamp. If the timestamp is not valid, the authentication fails. If the timestamp is valid, the authentication process proceeds.

Note: The session activity timestamp is configured separately from the session lifetime timestamp.

Parent topic: Failover authentication configuration

Failover for non-sticky failover environmentsFailover for non-sticky failover environmentsfailover authenticationnon-sticky failover solutionnon-stickyfailover solutionsThis section contains the following topics:Failover solutionsUse the failover cookie solution to maintain session state in clustered environments.Failover authentication conceptsFailover authentication configurationChange password operation in a failover environmentNon-sticky failover conceptsConfiguring the non-sticky failover solutionUse of failover cookies with existing WebSEAL features

Failover for non-sticky failover environments

This section contains the following topics:

Non-sticky failover concepts

Configuring the non-sticky failover solution

Use of failover cookies with existing WebSEAL features

Parent topic: Failover solutions

Related concepts:

Failover authentication concepts

Failover authentication configuration

Change password operation in a failover environment

Non-sticky failover conceptsNon-sticky failover conceptssticky load balancingnon-stickyload balancingload balancing environmentsstickynon-stickysession affinityfailover authenticationnon-sticky failover conceptsWebSEAL failover authentication is an appropriate solution for a fault-tolerant environment where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers (see Failover authentication concepts). Each replica server contains the same content and configuration. If the server where the client is connected suddenly becomes unavailable, the load balancer redirects the requests to one of the other replicated servers. WebSEAL can handle such failover events by issuing an encrypted failover cookie during the initial authentication of the user. The replica servers share a common encryption key that is used to encrypt and decrypt this failover cookie. This cookie, when presented to another WebSEAL replica, contains sufficient information (along with proof of the replica's own identity) to authenticate the user, build a user credential, and create a new session on the new replica. The user never receives an additional login prompt when a failover occurs.In a fault-tolerant environment, the load balancer manages the physical distribution of the request load. This discussion uses the terms "sticky" and "non-sticky" to describe the ability of the load balancing mechanism to maintain (or not maintain) a connection between the client and a specific server. Sticky load distribution maintains a connection between the client and a specific server. This condition is also described as stateful, or observing server affinity.Non-sticky distribution does not maintain a connection between the client and a specific server. This condition is also described as stateless, or not maintaining server affinity.In a sticky environment scenario, the load-balancer keeps the client communicating with one replica for the duration of the session. In the rare case of that replica failing, all subsequent requests go to another replica, which is determined by the load balancer.In non-sticky environments, the load-balancer does not hold the client to one replica. During the course of a user session, multiple requests can be directed to any of the available replica servers at any time. In either environment, the servers do not share session information and it is WebSEAL's responsibility to maintain session state between the client and the servers. WebSEAL maintains session state through use of a session cookie that is placed on the client browser.When a client request is switched to another replica server, the failover cookie prevents an additional login. However, the new replica has no knowledge of any session state on any other replica and builds a new session cookie that replaces the previous session cookie. In a non-sticky load balancing environment, the task of frequently issuing new cookies and establishing new sessions significantly degrades both the responsiveness of the user's session and the performance of WebSEAL.This performance problem can be reduced by ensuring that all replicas reuse the original session cookie issued to the client. WebSEAL can be configured to store the user's original session ID as an extended attribute in the failover cookie. Each replica involved in handling the client's requests builds a session cache entry using the original session ID. During subsequent returns to a replica, the server ID is verified in a secure manner by comparing the ID in the failover cookie attribute to the ID in the session cookie. If the ID match is successful, the server uses the existing session cache entry does not issue a new session cookie to the browser. Whenever possible, configure load balancers to maintain session affinity. Session affinity provides improved performance, improved user experience, and makes WebSEAL configuration simpler.Failover for non-sticky failover environments

Non-sticky failover concepts

WebSEAL failover authentication is an appropriate solution for a fault-tolerant environment where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers (see Failover authentication concepts). Each replica server contains the same content and configuration. If the server where the client is connected suddenly becomes unavailable, the load balancer redirects the requests to one of the other replicated servers.

WebSEAL can handle such failover events by issuing an encrypted failover cookie during the initial authentication of the user. The replica servers share a common encryption key that is used to encrypt and decrypt this failover cookie. This cookie, when presented to another WebSEAL replica, contains sufficient information (along with proof of the replica's own identity) to authenticate the user, build a user credential, and create a new session on the new replica. The user never receives an additional login prompt when a failover occurs.

In a fault-tolerant environment, the load balancer manages the physical distribution of the request load. This discussion uses the terms "sticky" and "non-sticky" to describe the ability of the load balancing mechanism to maintain (or not maintain) a connection between the client and a specific server.

Sticky load distribution maintains a connection between the client and a specific server. This condition is also described as stateful, or observing server affinity.

Non-sticky distribution does not maintain a connection between the client and a specific server. This condition is also described as stateless, or not maintaining server affinity.

In a sticky environment scenario, the load-balancer keeps the client communicating with one replica for the duration of the session. In the rare case of that replica failing, all subsequent requests go to another replica, which is determined by the load balancer.

In non-sticky environments, the load-balancer does not hold the client to one replica. During the course of a user session, multiple requests can be directed to any of the available replica servers at any time.

In either environment, the servers do not share session information and it is WebSEAL's responsibility to maintain session state between the client and the servers. WebSEAL maintains session state through use of a session cookie that is placed on the client browser.

When a client request is switched to another replica server, the failover cookie prevents an additional login. However, the new replica has no knowledge of any session state on any other replica and builds a new session cookie that replaces the previous session cookie. In a non-sticky load balancing environment, the task of frequently issuing new cookies and establishing new sessions significantly degrades both the responsiveness of the user's session and the performance of WebSEAL.

This performance problem can be reduced by ensuring that all replicas reuse the original session cookie issued to the client. WebSEAL can be configured to store the user's original session ID as an extended attribute in the failover cookie.

Each replica involved in handling the client's requests builds a session cache entry using the original session ID. During subsequent returns to a replica, the server ID is verified in a secure manner by comparing the ID in the failover cookie attribute to the ID in the session cookie. If the ID match is successful, the server uses the existing session cache entry does not issue a new session cookie to the browser.

Note: Whenever possible, configure load balancers to maintain session affinity. Session affinity provides improved performance, improved user experience, and makes WebSEAL configuration simpler.

Parent topic: Failover for non-sticky failover environments

Configuring the non-sticky failover solutionConfiguring the non-sticky failover solutionfailover authenticationconfiguring non-sticky failover solutionfailover solutionsconfiguring non-sticky failover solution The following configuration steps enable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment. WebSEAL reuses the original session ID by storing the ID as an extended attribute to the failover cookie. failover-include-session-id stanza entryTo enable the functionality of including the user's original session ID in the failover cookie, set the failover-include-session-id stanza entry in the [failover] stanza of the WebSEAL configuration file to "yes": [failover] failover-include-session-id = yes When you enable the non-sticky failover solution (failover-include-session-id = yes), you must configure the following four stanza entries correctly. WebSEAL reports a startup error and fails to start if any of these settings are incorrect:The non-sticky failover solution requires the use of the WebSEAL session cookie, rather than the SSL session ID, to maintain session state over HTTPS. Verify that the ssl-id-sessions stanza entry in the [session] stanza of the WebSEAL configuration file is set to "no" (default):ssl-id-sessions stanza entry[session] ssl-id-sessions = noTo encode the user's original session ID as an extended attribute in the failover cookie, set the tagvalue_failover_amweb_session_id stanza entry in the [failover-add-attributes] stanza of the WebSEAL configuration file to "add":tagvalue_failover_amweb_session_id stanza entryfailover-add-attributes stanza[failover-add-attributes] tagvalue_failover_amweb_session_id = addWhen the user session is switched to another replica for the first time, WebSEAL (on that replica) must build a credential and session cache entry for the user, using the information contained in the failover cookie. To ensure that the session ID (encoded in the failover cookie) is added to the user credential, set the tagvalue_failover_amweb_session_id stanza entry in the [failover-restore-attributes] stanza of the WebSEAL configuration file to "preserve":tagvalue_failover_amweb_session_id stanza entryfailover-restore-attributes stanza[failover-restore-attributes] tagvalue_failover_amweb_session_id = preserveThe credential refresh feature allows you to update the contents of a user credential on demand by issuing a pdadmin command (see Credential refresh). To preserve the session ID attribute used in the non-sticky failover performance solution during a credential refresh, you must set the tagvalue_failover_amweb_session_id stanza entry in the [credential-refresh-attributes] stanza of the WebSEAL configuration file to "preserve":tagvalue_failover_amweb_session_id stanza entrycredential-refresh-attributes stanza[credential-refresh-attributes] tagvalue_failover_amweb_session_id = preserveFailover for non-sticky failover environments

Configuring the non-sticky failover solution

About this task

The following configuration steps enable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment. WebSEAL reuses the original session ID by storing the ID as an extended attribute to the failover cookie.

To enable the functionality of including the user's original session ID in the failover cookie, set the failover-include-session-id stanza entry in the [failover] stanza of the WebSEAL configuration file to "yes":

[failover]
failover-include-session-id = yes

When you enable the non-sticky failover solution (failover-include-session-id = yes), you must configure the following four stanza entries correctly. WebSEAL reports a startup error and fails to start if any of these settings are incorrect:

Procedure

The non-sticky failover solution requires the use of the WebSEAL session cookie, rather than the SSL session ID, to maintain session state over HTTPS. Verify that the ssl-id-sessions stanza entry in the [session] stanza of the WebSEAL configuration file is set to "no" (default):

[session]
ssl-id-sessions = no

To encode the user's original session ID as an extended attribute in the failover cookie, set the tagvalue_failover_amweb_session_id stanza entry in the [failover-add-attributes] stanza of the WebSEAL configuration file to "add":

[failover-add-attributes]
tagvalue_failover_amweb_session_id = add

When the user session is switched to another replica for the first time, WebSEAL (on that replica) must build a credential and session cache entry for the user, using the information contained in the failover cookie. To ensure that the session ID (encoded in the failover cookie) is added to the user credential, set the tagvalue_failover_amweb_session_id stanza entry in the [failover-restore-attributes] stanza of the WebSEAL configuration file to "preserve":

[failover-restore-attributes]
tagvalue_failover_amweb_session_id = preserve

The credential refresh feature allows you to update the contents of a user credential on demand by issuing a pdadmin command (see Credential refresh). To preserve the session ID attribute used in the non-sticky failover performance solution during a credential refresh, you must set the tagvalue_failover_amweb_session_id stanza entry in the [credential-refresh-attributes] stanza of the WebSEAL configuration file to "preserve":

[credential-refresh-attributes]
tagvalue_failover_amweb_session_id = preserve

Parent topic: Failover for non-sticky failover environments

Use of failover cookies with existing WebSEAL featuresUse of failover cookies with existing WebSEAL featuresWebSEALfailover cookiesfailover cookiesexisting WebSEAL featuresThe following information discusses the impact of the non-sticky failover solution to other WebSEAL features.Switch-user Failover authentication is not supported for the switch user feature. Therefore, the non-sticky failover solution is also not supported.Authentication methods The non-sticky failover solution does not affect other supported WebSEAL authentication methods.Reauthentication The non-sticky failover solution does not affect reauthentication because reauthentication does not change the user's session ID.Authentication strength (step-up) The non-sticky failover solution does not affect authentication strength policy (step-up) because authentication strength does not change the user's session ID.Credential refresh The tagvalue_failover_amweb_session_id stanza entry in the [credential-refresh-attributes] stanza of the WebSEAL configuration file allows you to preserve the session ID information in a user's credential during a credential refresh operation. However, the credential refresh command cannot be used to control credential refresh across multiple replica servers. If you perform a credential refresh operation in a server cluster environment, you must issue the credential refresh command to each replica member of the replica set.Failover for non-sticky failover environments

Use of failover cookies with existing WebSEAL features

The following information discusses the impact of the non-sticky failover solution to other WebSEAL features.

Switch-user

Failover authentication is not supported for the switch user feature. Therefore, the non-sticky failover solution is also not supported.

Authentication methods

The non-sticky failover solution does not affect other supported WebSEAL authentication methods.

Reauthentication

The non-sticky failover solution does not affect reauthentication because reauthentication does not change the user's session ID.

Authentication strength (step-up)

The non-sticky failover solution does not affect authentication strength policy (step-up) because authentication strength does not change the user's session ID.

Credential refresh

The tagvalue_failover_amweb_session_id stanza entry in the [credential-refresh-attributes] stanza of the WebSEAL configuration file allows you to preserve the session ID information in a user's credential during a credential refresh operation. However, the credential refresh command cannot be used to control credential refresh across multiple replica servers. If you perform a credential refresh operation in a server cluster environment, you must issue the credential refresh command to each replica member of the replica set.

Parent topic: Failover for non-sticky failover environments

Change password operation in a failover environmentChange password operation in a failover environmentchange-password-auth stanza entryfailover authenticationchange-password-auth stanza entrychanging password operationchanging password operationexpired password operationpassword expirationThe password change operation during authentication can be adversely affected in a non-sticky load balancing environment. For example, a user receives the expired password form and completes the password change information required on the form. When sending the completed form, the load balancer connects to a different replica server. Because this new server is not aware of the previous contact with the original server, it prompts the user to log in. The user provides the old password and is again presented with the expired password form.The change-password-auth stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file allows you to prevent additional login requests during change password operations. Setting change-password-auth = yes allows the new replica server to use the existing authentication information in the change password request (user name, original password, and new password) to authenticate the user and change the user's password.To enable this controlled change password operation in a failover environment, set:[acnt-mgt] change-password-auth = yesFor compatibility with versions of WebSEAL prior to version 6.0, the default setting is "no". Failover solutionsUse the failover cookie solution to maintain session state in clustered environments.Failover authentication conceptsFailover authentication configurationFailover for non-sticky failover environments

Change password operation in a failover environment

The password change operation during authentication can be adversely affected in a non-sticky load balancing environment. For example, a user receives the expired password form and completes the password change information required on the form. When sending the completed form, the load balancer connects to a different replica server. Because this new server is not aware of the previous contact with the original server, it prompts the user to log in. The user provides the old password and is again presented with the expired password form.

The change-password-auth stanza entry in the [acnt-mgt] stanza of the WebSEAL configuration file allows you to prevent additional login requests during change password operations. Setting change-password-auth = yes allows the new replica server to use the existing authentication information in the change password request (user name, original password, and new password) to authenticate the user and change the user's password.

To enable this controlled change password operation in a failover environment, set:

[acnt-mgt]
change-password-auth = yes

For compatibility with versions of WebSEAL prior to version 6.0, the default setting is "no".

Parent topic: Failover solutions

Related concepts:

Failover authentication concepts

Failover authentication configuration

Failover for non-sticky failover environments

Session state in non-clustered environmentsSession state in non-clustered environmentssession statenon-clustered environmentsnon-clustered environmentssession stateThis chapter discusses basic concepts and procedures for managing session state between clients and a single WebSEAL server (non-clustered server environment). For environments where more than one WebSEAL server provides protection to resources, see Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution..To terminate individual user sessions or all user sessions, see User session management for back-end servers.Topic Index:Session StateMaintain session state in non-clustered environmentsSession cookiesCustomized responses for old session cookiesMaintain session state with HTTP headersShare sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.

Session state in non-clustered environments

This chapter discusses basic concepts and procedures for managing session state between clients and a single WebSEAL server (non-clustered server environment).

For environments where more than one WebSEAL server provides protection to resources, see Advanced configuration for the distributed session cache.

To terminate individual user sessions or all user sessions, see User session management for back-end servers.

Topic Index:

Maintain session state in non-clustered environments

Session cookies

Customized responses for old session cookies

Maintain session state with HTTP headers

Share sessions with Microsoft Office applications
You can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.

Parent topic: Session State

Maintain session state in non-clustered environmentsMaintain session state in non-clustered environmentsnon-clustered environmentsmaintaining session statesession statemaintenance in non-clustered environmentsThis section contains the following topics:Session state in non-clustered environmentsSession cookiesCustomized responses for old session cookiesMaintain session state with HTTP headersShare sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.Control on session state information over SSLUse of the same session key over different transportsValid session key data typesYou can configure the session key data type that WebSEAL uses for each authentication method.Effective session timeout valueNetscape 4.7x limitation for use-same-session

Maintain session state in non-clustered environments

This section contains the following topics:

Control on session state information over SSL

Use of the same session key over different transports

Valid session key data types
You can configure the session key data type that WebSEAL uses for each authentication method.

Effective session timeout value

Netscape 4.7x limitation for use-same-session

Parent topic: Session state in non-clustered environments

Related concepts:

Session cookies

Customized responses for old session cookies

Maintain session state with HTTP headers

Share sessions with Microsoft Office applications

Control on session state information over SSLControl on session state information over SSLssl-id-sessions stanza entrySSLseesion IDscontrolsession statecontrol session key data typeSSL session IDThe ssl-id-sessions stanza entry, located in the [session] stanza of the WebSEAL configuration file, allows you to control whether the SSL session ID or another session key data type is used to maintain the login session for clients accessing over HTTPS. If the stanza entry value is set to "yes", the SSL session ID is used for all authentication methods. For example:[session] ssl-id-sessions = yesIf the stanza entry value is set to "no" (default), session cookies are used for most authentication methods. For example:[session] ssl-id-sessions = noA configuration setting of "no" for this stanza entry results in the following conditions for clients accessing over HTTPS: The SSL session ID is never used to maintain session state.The HTTP header is used as session ID data for clients authenticating with HTTP headers.The IP address is used as session ID data for clients authenticating with IP addresses.Cookies is used to maintain sessions with clients authenticating with all other methods.See Valid session key data typesYou can configure the session key data type that WebSEAL uses for each authentication method..Maintain session state in non-clustered environments

Control on session state information over SSL

The ssl-id-sessions stanza entry, located in the [session] stanza of the WebSEAL configuration file, allows you to control whether the SSL session ID or another session key data type is used to maintain the login session for clients accessing over HTTPS.

If the stanza entry value is set to "yes", the SSL session ID is used for all authentication methods. For example:

[session]
ssl-id-sessions = yes

If the stanza entry value is set to "no" (default), session cookies are used for most authentication methods. For example:

[session]
ssl-id-sessions = no

A configuration setting of "no" for this stanza entry results in the following conditions for clients accessing over HTTPS:

The SSL session ID is never used to maintain session state.

The HTTP header is used as session ID data for clients authenticating with HTTP headers.

The IP address is used as session ID data for clients authenticating with IP addresses.

Cookies is used to maintain sessions with clients authenticating with all other methods.

See Valid session key data types.

Parent topic: Maintain session state in non-clustered environments

Use of the same session key over different transportsUse of the same session key over different transportsuse-same-session stanza entrysession statesame session key over different transportsYou can configure WebSEAL to use the same session, or not, when a client authenticates over one type of transport (HTTP, for example), establishes a session, and then connects over another type of transport (HTTPS, for example). The use-same-session stanza entry, located in the [session] stanza of the WebSEAL configuration file, provides the following two choices:No When a client authenticates over one transport, establishes a session, and then connects over another transport, the client must authenticate again. A separate session is created using a second session key. The two sessions are maintained independently in the WebSEAL session cache. The appropriate session key used for future connections is determined by the transport that the client uses. [session] use-same-session = noYes When a client authenticates over one transport, establishes a session, and then connects over another transport, the client uses the same session and corresponding session key that was created for the first transport. The client is not required to authenticate a second time. [session] use-same-session = yesA "yes" configuration setting for this stanza entry results in the following conditions: The HTTP header is used to maintain sessions for clients accessing with HTTP headers over all transport types.The IP address is used to maintain sessions for clients accessing with IP addresses.Session cookies are used to maintain sessions for all other authentication methods.The ssl-id-sessions configuration is ignored; the resulting behavior is the same as if ssl-id-sessions were set to “no”. This logic is important because HTTP clients do not have an SSL session ID available as session data.Because the cookies are available to both HTTP and HTTPS clients, they are not flagged with the "secure" cookie attribute.See Valid session key data typesYou can configure the session key data type that WebSEAL uses for each authentication method..Maintain session state in non-clustered environments

Use of the same session key over different transports

You can configure WebSEAL to use the same session, or not, when a client authenticates over one type of transport (HTTP, for example), establishes a session, and then connects over another type of transport (HTTPS, for example).

The use-same-session stanza entry, located in the [session] stanza of the WebSEAL configuration file, provides the following two choices:

No

When a client authenticates over one transport, establishes a session, and then connects over another transport, the client must authenticate again. A separate session is created using a second session key. The two sessions are maintained independently in the WebSEAL session cache. The appropriate session key used for future connections is determined by the transport that the client uses.

[session]
use-same-session = no

Yes

When a client authenticates over one transport, establishes a session, and then connects over another transport, the client uses the same session and corresponding session key that was created for the first transport. The client is not required to authenticate a second time.

[session]
use-same-session = yes

A "yes" configuration setting for this stanza entry results in the following conditions:

The HTTP header is used to maintain sessions for clients accessing with HTTP headers over all transport types.

The IP address is used to maintain sessions for clients accessing with IP addresses.

Session cookies are used to maintain sessions for all other authentication methods.

The ssl-id-sessions configuration is ignored; the resulting behavior is the same as if ssl-id-sessions were set to “no”.

This logic is important because HTTP clients do not have an SSL session ID available as session data.

Because the cookies are available to both HTTP and HTTPS clients, they are not flagged with the "secure" cookie attribute.

See Valid session key data types.

Parent topic: Maintain session state in non-clustered environments

Valid session key data types Valid session key data types You can configure the session key data type that WebSEAL uses for each authentication method.session statevalid session key data typessession keyvalid session key data typessession-http-headers stanzaThe session key data type used with an authentication method is determined by specific combinations of the following configuration items: Setting for the ssl-id-sessions stanza entry.Setting for the use-same-session stanza entry.Header names defined in the [session-http-headers] stanza.Table legend: C (session cookie); H (HTTP header); IP (IP address); SSL (SSL session ID)S-I-S (ssl-id-sessions); U-S-S (use-same-session); S-H-H ([session-http-headers])If a stanza entry appears in the table header, the value of the entry is "yes". Otherwise, the value is "no".Valid Session Key Data Types for HTTPS ClientsAuthn Method- - -S-I-S - -- S-H-H -- - U-S-SS-I-S S-H-H -S-I-S - U-S-S- S-H-H U-S-SS-I-S S-H-H U-S-SBACSSLHCSSLCHHCDSSOCSSLHCSSLCHHCertificateCSSLHCSSLCHHExternal authn interfaceCSSLHCSSLCHHFailover cookieCSSLHCSSLCHHLTPA cookieCSSLHCSSLCHHFormsCSSLHCSSLCHHValid Session Key Data Types for HTTP ClientsAuthn Method- - -- S-H-H -- - U-S-S- S-H-H U-S-SBACHCHCDSSOCHCHCertificateCHCHExternal authentication interfaceCHCHFailover cookieCHCHLTPA cookieCHCHFormsCHCHMaintain session state in non-clustered environments

Valid session key data types

You can configure the session key data type that WebSEAL uses for each authentication method.

The session key data type used with an authentication method is determined by specific combinations of the following configuration items:

Setting for the ssl-id-sessions stanza entry.

Setting for the use-same-session stanza entry.

Header names defined in the [session-http-headers] stanza.

Table legend:

C (session cookie); H (HTTP header); IP (IP address); SSL (SSL session ID)

S-I-S (ssl-id-sessions); U-S-S (use-same-session); S-H-H ([session-http-headers])

If a stanza entry appears in the table header, the value of the entry is "yes". Otherwise, the value is "no".

Table 55. Valid Session Key Data Types for HTTPS Clients

Authn Method

-

-

-

S-I-S

-

-

-

S-H-H

-

-

-

U-S-S

S-I-S

S-H-H

-

S-I-S

-

U-S-S

-

S-H-H

U-S-S

S-I-S

S-H-H

U-S-S

BA
C
SSL
H
C
SSL
C
H
H

CDSSO
C
SSL
H
C
SSL
C
H
H

Certificate
C
SSL
H
C
SSL
C
H
H

External

authn

interface

C
SSL
H
C
SSL
C
H
H

Failover cookie
C
SSL
H
C
SSL
C
H
H

LTPA cookie
C
SSL
H
C
SSL
C
H
H

Forms
C
SSL
H
C
SSL
C
H
H

Table 56. Valid Session Key Data Types for HTTP Clients

Authn Method

-

-

-

-

S-H-H

-

-

-

U-S-S

-

S-H-H

U-S-S

BA
C
H
C
H

CDSSO
C
H
C
H

Certificate
C
H
C
H

External

authentication

interface

C
H
C
H

Failover cookie
C
H
C
H

LTPA cookie
C
H
C
H

Forms
C
H
C
H

Parent topic: Maintain session state in non-clustered environments

Effective session timeout valueEffective session timeout valuesession statedetermining session timeoutsession timeouttimeoutstanzainactive-timeout stanza entrysession stanzassl-v2-timeout stanza entryssl-v3-timeout stanza entryWhen ssl-id-sessions is set to "yes", several different values can determine the actual timeout for the session. The session cache entry lifetime timeout is set in the timeout entry in the [session] stanza.The session inactivity timeout is set by the inactive-timeout entry in the same stanza. SSL timeouts are set in the [ssl] stanza, where both ssl-v2–timeout and ssl-v3–timeout stanza entries are declared. When ssl-id-sessions = yes, the actual effective session timeout is set to the lowest of the values set for each of the following timeout settings:[session] timeout inactive-timeout [ssl] ssl-v2-timeout ssl-v3-timeoutMaintain session state in non-clustered environments

Effective session timeout value

When ssl-id-sessions is set to "yes", several different values can determine the actual timeout for the session.

The session cache entry lifetime timeout is set in the timeout entry in the [session] stanza.

The session inactivity timeout is set by the inactive-timeout entry in the same stanza.

SSL timeouts are set in the [ssl] stanza, where both ssl-v2–timeout and ssl-v3–timeout stanza entries are declared.

When ssl-id-sessions = yes, the actual effective session timeout is set to the lowest of the values set for each of the following timeout settings:

[session]
timeout
inactive-timeout

[ssl]
ssl-v2-timeout
ssl-v3-timeout

Parent topic: Maintain session state in non-clustered environments

Netscape 4.7x limitation for use-same-sessionNetscape 4.7x limitation for use-same-sessionsession stateNetscape 4.7x limitationuse-same-session stanza entryProblem:The use-same-session feature fails on Netscape Navigator Version 4.7x when requests made to WebSEAL include the port number in the URL, such as: http://webseal:80Explanation:When WebSEAL is configured for the default HTTP/HTTPS ports, and the port number is not included in the URL, the request succeeds. Requests fail when WebSEAL is configured on non-default ports and the use-same-session = yes configuration option is enabled.Netscape 4.7x does not consider host names with non-standard port numbers to be in the same domain as those with different port numbers. For example, when you access:https://hostname:443WebSEAL sets a cookie. When you later access:http://hostname:80Netscape does not send the cookie because domain:80 is not the same as domain:443.Workaround: Upgrade to Netscape Navigator version 6.2, or higher.Maintain session state in non-clustered environments

Netscape 4.7x limitation for use-same-session

Problem:

The use-same-session feature fails on Netscape Navigator Version 4.7x when requests made to WebSEAL include the port number in the URL, such as: http://webseal:80

Explanation:

When WebSEAL is configured for the default HTTP/HTTPS ports, and the port number is not included in the URL, the request succeeds. Requests fail when WebSEAL is configured on non-default ports and the use-same-session = yes configuration option is enabled.

Netscape 4.7x does not consider host names with non-standard port numbers to be in the same domain as those with different port numbers. For example, when you access:

https://hostname:443

WebSEAL sets a cookie. When you later access:

http://hostname:80

Netscape does not send the cookie because domain:80 is not the same as domain:443.

Workaround:

Upgrade to Netscape Navigator version 6.2, or higher.

Parent topic: Maintain session state in non-clustered environments

Session cookies Session cookies session cookiesoverviewsession statecookiessessionThis section contains the following topics:Session state in non-clustered environmentsMaintain session state in non-clustered environmentsCustomized responses for old session cookiesMaintain session state with HTTP headersShare sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.Session cookies conceptsConditions for using session cookiesCustomization of the session cookie nameSending session cookies with each request

Session cookies

This section contains the following topics:

Session cookies concepts

Conditions for using session cookies

Customization of the session cookie name

Sending session cookies with each request

Parent topic: Session state in non-clustered environments

Related concepts:

Maintain session state in non-clustered environments

Customized responses for old session cookies

Maintain session state with HTTP headers

Share sessions with Microsoft Office applications

Session cookies conceptsSession cookies conceptssession cookiesconceptsconceptssession cookiesOne method of maintaining session state between a client and a server is to use a cookie to hold this session information. The server packages the session key for a particular client in a cookie and sends it to the client's browser. For each new request, the browser re-identifies itself by sending the cookie (with the session key) back to the server.Session cookies offer a possible solution for situations when the client uses a browser that renegotiates its SSL session after very short periods of time. For example, some versions of the Microsoft Internet Explorer browser renegotiate SSL sessions every two or three minutes. The session cookie is a server-specific cookie that cannot be passed to any machine other than the one that generated the cookie. The session cookie allows the browser to re-identify itself to the single, unique server to which the client had previously authenticated. When using session cookies, WebSEAL does not need to prompt the client for another login.The session key stored in the session cookie contains only a random number identifier (“key”) that is used to index the server's session cache. There is no other information exposed in the session cookie.Session cookies

Session cookies concepts

One method of maintaining session state between a client and a server is to use a cookie to hold this session information. The server packages the session key for a particular client in a cookie and sends it to the client's browser. For each new request, the browser re-identifies itself by sending the cookie (with the session key) back to the server.

Session cookies offer a possible solution for situations when the client uses a browser that renegotiates its SSL session after very short periods of time. For example, some versions of the Microsoft Internet Explorer browser renegotiate SSL sessions every two or three minutes.

The session cookie is a server-specific cookie that cannot be passed to any machine other than the one that generated the cookie. The session cookie allows the browser to re-identify itself to the single, unique server to which the client had previously authenticated. When using session cookies, WebSEAL does not need to prompt the client for another login.

The session key stored in the session cookie contains only a random number identifier (“key”) that is used to index the server's session cache. There is no other information exposed in the session cookie.

Parent topic: Session cookies

Conditions for using session cookiesConditions for using session cookiessession cookiesconditionsThe following basic conditions apply to session cookies: The session cookie contains session information only; it does not contain identity information.The session cookie is located only in the browser memory (it is not written to the browser cookie jar on the disk).The session cookie has a limited lifetime. The session cookie is a server-specific cookie; the browser can send this cookie in a request only to the same host where the cookie was created.Client browsers can be configured to either accept or reject cookies. If a client browser rejects a session cookie and then successfully logs in, WebSEAL must, for each additional request by the client, establish a new session by reauthenticating the user. With basic authentication (BA) however, WebSEAL uses BA header information to reauthenticate the user and the user never experiences a prompt to re-login. However, the overhead of reauthentication and session creation can reduce server performance. Session cookies

Conditions for using session cookies

The following basic conditions apply to session cookies:

The session cookie contains session information only; it does not contain identity information.

The session cookie is located only in the browser memory (it is not written to the browser cookie jar on the disk).

The session cookie has a limited lifetime.

The session cookie is a server-specific cookie; the browser can send this cookie in a request only to the same host where the cookie was created.

Client browsers can be configured to either accept or reject cookies. If a client browser rejects a session cookie and then successfully logs in, WebSEAL must, for each additional request by the client, establish a new session by reauthenticating the user. With basic authentication (BA) however, WebSEAL uses BA header information to reauthenticate the user and the user never experiences a prompt to re-login. However, the overhead of reauthentication and session creation can reduce server performance.

Parent topic: Session cookies

Customization of the session cookie nameCustomization of the session cookie namesession cookiescustomizing cookie nametcp-session-cookie-name stanza entryssl-session-cookie-name stanza entryPD-H-SESSION-ID (default session cookie name)PD-S-SESSION-ID (default session cookie name)You can customize the names of the WebSEAL session cookies. The WebSEAL configuration file provides different default names for session cookies used over TCP and SSL connections:[session] tcp-session-cookie-name = PD-H-SESSION-ID ssl-session-cookie-name = PD-S-SESSION-IDConditions for modifying the default cookie names:Cookie names must be alphanumeric.Cookie names must be unique.To use the same cookie for both TCP and SSL communication, configure use-same-session=yes.These stanza entries affect both host and domain type cookies.Session cookies

Customization of the session cookie name

You can customize the names of the WebSEAL session cookies. The WebSEAL configuration file provides different default names for session cookies used over TCP and SSL connections:

[session]
tcp-session-cookie-name = PD-H-SESSION-ID
ssl-session-cookie-name = PD-S-SESSION-ID

Conditions for modifying the default cookie names:

Cookie names must be alphanumeric.

Cookie names must be unique.

To use the same cookie for both TCP and SSL communication, configure use-same-session=yes.

These stanza entries affect both host and domain type cookies.

Parent topic: Session cookies

Sending session cookies with each requestSending session cookies with each requestresend-webseal-cookies stanza entrysession cookiesresend-webseal-cookiesfailover cookiesresend-webseal-cookiese-community cookieresend-webseal-cookiesWhen you use cookies to maintain session state, the cookie is sent to the browser only once, following a successful login. However, some browsers enforce a limit on the number of in-memory cookies they can store concurrently. In some environments, applications can place a large number of in-memory cookies per domain on client systems. In this case, any configured WebSEAL session cookie, failover cookie or LTPA cookie can be easily replaced by another cookie. When you configure WebSEAL to use session cookies, you can additionally set the resend-webseal-cookies stanza entry, located in the [session] stanza of the WebSEAL configuration file. This stanza entry instructs WebSEAL to re-send the session cookie to the browser for all responses to requests that originally contained a session cookie. This action helps to ensure that the session cookie remains in the browser memory. The resend-webseal-cookies stanza entry has a default setting of "no": [session] resend-webseal-cookies = noEnable WebSEAL to examine each request for a session cookie and include the cookie in the corresponding response by configuring the stanza entry to "yes".[session] resend-webseal-cookies = yesThe resend-webseal-cookies stanza entry produces the same results for failover cookies, e-community cookies and LTPA cookies.Session cookies

Sending session cookies with each request

About this task

When you use cookies to maintain session state, the cookie is sent to the browser only once, following a successful login. However, some browsers enforce a limit on the number of in-memory cookies they can store concurrently.

In some environments, applications can place a large number of in-memory cookies per domain on client systems. In this case, any configured WebSEAL session cookie, failover cookie or LTPA cookie can be easily replaced by another cookie.

When you configure WebSEAL to use session cookies, you can additionally set the resend-webseal-cookies stanza entry, located in the [session] stanza of the WebSEAL configuration file. This stanza entry instructs WebSEAL to re-send the session cookie to the browser for all responses to requests that originally contained a session cookie. This action helps to ensure that the session cookie remains in the browser memory.

The resend-webseal-cookies stanza entry has a default setting of "no":

[session]
resend-webseal-cookies = no

Procedure

Enable WebSEAL to examine each request for a session cookie and include the cookie in the corresponding response by configuring the stanza entry to "yes".

[session]
resend-webseal-cookies = yes

Note: The resend-webseal-cookies stanza entry produces the same results for failover cookies, e-community cookies and LTPA cookies.

Parent topic: Session cookies

Customized responses for old session cookiesCustomized responses for old session cookiessession cachecustom login response for old session cookiessession cookiescustomized responseslogincustom login response for old session cookiesThis section contains the following topics:Session state in non-clustered environmentsMaintain session state in non-clustered environmentsSession cookiesMaintain session state with HTTP headersShare sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.Session removal and old session cookie conceptsWhen a user uses the /pkmslogout command to log out of a session, the entry for that user in the WebSEAL session cache is automatically removed.Enabling customized responses for old session cookiesYou can configure WebSEAL to enable customized responses for old session cookies.

Customized responses for old session cookies

This section contains the following topics:

Session removal and old session cookie concepts
When a user uses the /pkmslogout command to log out of a session, the entry for that user in the WebSEAL session cache is automatically removed.

Enabling customized responses for old session cookies
You can configure WebSEAL to enable customized responses for old session cookies.

Parent topic: Session state in non-clustered environments

Related concepts:

Maintain session state in non-clustered environments

Session cookies

Maintain session state with HTTP headers

Share sessions with Microsoft Office applications

Session removal and old session cookie conceptsSession removal and old session cookie conceptsWebSEAL session removal and old session cookie conceptsWhen a user uses the /pkmslogout command to log out of a session, the entry for that user in the WebSEAL session cache is automatically removed.session removalold session cookie conceptsold session cookiesconceptssession cookiesold conceptssession displacementsession timeoutsesion termination If the session cookie for that session remains on the browser of the user, it becomes an old, or stale cookie. A stale cookie no longer maps to an existing entry in the WebSEAL session cache. When the user makes a subsequent request for a protected object, WebSEAL requires authentication and returns a login form. The response to the new request under these conditions must be expected by the user. If the user session was removed from the WebSEAL session cache for unknown reasons, the original session cookie remaining on the browser of the user becomes a stale cookie. The stale cookie does not map to an existing entry in the WebSEAL session cache. Session timeout, session displacement, or session termination are some of the reasons which might cause the session removal from WebSEAL, and might be unknown to the user. When the user requests for a protected object, WebSEAL requires authentication, and returns a login form. This response to the new request under these conditions might be unexpected to the user.You can customize the login response to contain additional information that helps to explain the reason for an unexpected login prompt. Follow these steps to provide a customized response:Trigger a custom login response whenever WebSEAL receives a stale session cookie that does not map to any existing entry in the session cache. See Triggering a custom login responseThe standard WebSEAL login forms contain a macro called OLDSESSION. The OLDSESSION macro can be blank by default, or have a value of 1. When WebSEAL receives a stale session cookie that does not map to any existing entry in the session cache, the OLDSESSION macro value is set to 1..Configure WebSEAL to attempt to remove the session cookie from browsers during standard logouts by using the /pkmslogout command. See Removing cookies from browsers during normal logoutBy default, WebSEAL does not remove cookies from client systems during session termination, regardless of the cause of the termination. The termination might either be initiated by a client logout or by the server. This means that the value of the OLDSESSION macro is always set to 1 when a user makes a subsequent request after the session termination. The scenario makes it impossible to trigger a custom login response..Customized responses for old session cookiesTriggering a custom login responseThe standard WebSEAL login forms contain a macro called OLDSESSION. The OLDSESSION macro can be blank by default, or have a value of 1. When WebSEAL receives a stale session cookie that does not map to any existing entry in the session cache, the OLDSESSION macro value is set to 1.Removing cookies from browsers during normal logoutBy default, WebSEAL does not remove cookies from client systems during session termination, regardless of the cause of the termination. The termination might either be initiated by a client logout or by the server. This means that the value of the OLDSESSION macro is always set to 1 when a user makes a subsequent request after the session termination. The scenario makes it impossible to trigger a custom login response.

Session removal and old session cookie concepts

When a user uses the /pkmslogout command to log out of a session, the entry for that user in the WebSEAL session cache is automatically removed.

If the session cookie for that session remains on the browser of the user, it becomes an old, or stale cookie. A stale cookie no longer maps to an existing entry in the WebSEAL session cache. When the user makes a subsequent request for a protected object, WebSEAL requires authentication and returns a login form. The response to the new request under these conditions must be expected by the user. If the user session was removed from the WebSEAL session cache for unknown reasons, the original session cookie remaining on the browser of the user becomes a stale cookie. The stale cookie does not map to an existing entry in the WebSEAL session cache. Session timeout, session displacement, or session termination are some of the reasons which might cause the session removal from WebSEAL, and might be unknown to the user.

When the user requests for a protected object, WebSEAL requires authentication, and returns a login form. This response to the new request under these conditions might be unexpected to the user.

You can customize the login response to contain additional information that helps to explain the reason for an unexpected login prompt. Follow these steps to provide a customized response:

Trigger a custom login response whenever WebSEAL receives a stale session cookie that does not map to any existing entry in the session cache.

See Triggering a custom login response.

Configure WebSEAL to attempt to remove the session cookie from browsers during standard logouts by using the /pkmslogout command.

See Removing cookies from browsers during normal logout.

Triggering a custom login response
The standard WebSEAL login forms contain a macro called OLDSESSION. The OLDSESSION macro can be blank by default, or have a value of 1. When WebSEAL receives a stale session cookie that does not map to any existing entry in the session cache, the OLDSESSION macro value is set to 1.

Removing cookies from browsers during normal logout
By default, WebSEAL does not remove cookies from client systems during session termination, regardless of the cause of the termination. The termination might either be initiated by a client logout or by the server. This means that the value of the OLDSESSION macro is always set to 1 when a user makes a subsequent request after the session termination. The scenario makes it impossible to trigger a custom login response.

Parent topic: Customized responses for old session cookies

Triggering a custom login responseTriggering a custom login responseTriggering a custom login response in WebSEALThe standard WebSEAL login forms contain a macro called OLDSESSION. The OLDSESSION macro can be blank by default, or have a value of 1. When WebSEAL receives a stale session cookie that does not map to any existing entry in the session cache, the OLDSESSION macro value is set to 1.session cachecustom login response for removed sessionssession cookiescustom login response for removed sessionsmacrosHTML server response pagesOLDSESSION macroYou can cause the appropriate WebSEAL login form, such as login.html, to do the following actions:Read the value of the OLDSESSION macro.Trigger a custom response to the user when the value of the macro equals 1.The custom response informs the user that it is possible that their session was terminated because of inactivity.Session removal and old session cookie conceptsWhen a user uses the /pkmslogout command to log out of a session, the entry for that user in the WebSEAL session cache is automatically removed.

Triggering a custom login response

The standard WebSEAL login forms contain a macro called OLDSESSION. The OLDSESSION macro can be blank by default, or have a value of 1. When WebSEAL receives a stale session cookie that does not map to any existing entry in the session cache, the OLDSESSION macro value is set to 1.

You can cause the appropriate WebSEAL login form, such as login.html, to do the following actions:

Read the value of the OLDSESSION macro.

Trigger a custom response to the user when the value of the macro equals 1.

The custom response informs the user that it is possible that their session was terminated because of inactivity.

Parent topic: Session removal and old session cookie concepts

Removing cookies from browsers during normal logoutRemoving cookies from browsers during normal logoutRemoving cookies from browsers during normal logoutBy default, WebSEAL does not remove cookies from client systems during session termination, regardless of the cause of the termination. The termination might either be initiated by a client logout or by the server. This means that the value of the OLDSESSION macro is always set to 1 when a user makes a subsequent request after the session termination. The scenario makes it impossible to trigger a custom login response.session cookiesremoving cookies from browsers during normal logoutlogout-remove-cookie stanza entrymacros used in HTML server response pagesOLDSESSIONOLDSESSION macropkmslogoutConfigure WebSEAL to attempt to remove cookies from client systems when the user logs out by sending a cookie in the corresponding response. Typically, the only time WebSEAL receives stale cookies is when the terminated sessions were not initiated by the user. The scenario requires a custom login response.While typically successful, there are times when configuring WebSEAL to remove a cookie might not remove cookies from client systems. For example, following a request for /pkmslogout and a successful session termination at WebSEAL, a network issue might interfere with the logout response transmission. In the scenario, the stale session cookie is left on the client system. For this reason, security-sensitive decisions must not be based on the presence of the cookie, or the OLDSESSION macro value.An intentional logout does not leave a user with a stale cookie because it is normal browser operation to remove session cookies when a browser closes. A user logs out intentionally by closing the browser application, and the OLDSESSION macro is not set during the next request by that user. However, the user session cache entry remains on the WebSEAL server, or Session Management Server. It continues to count against the max-concurrent-web-sessions policy setting until the cache entry expires because of lifetime or inactivity timeout.Session removal and old session cookie conceptsWhen a user uses the /pkmslogout command to log out of a session, the entry for that user in the WebSEAL session cache is automatically removed.

Removing cookies from browsers during normal logout

By default, WebSEAL does not remove cookies from client systems during session termination, regardless of the cause of the termination. The termination might either be initiated by a client logout or by the server. This means that the value of the OLDSESSION macro is always set to 1 when a user makes a subsequent request after the session termination. The scenario makes it impossible to trigger a custom login response.

Procedure

Configure WebSEAL to attempt to remove cookies from client systems when the user logs out by sending a cookie in the corresponding response.

Typically, the only time WebSEAL receives stale cookies is when the terminated sessions were not initiated by the user. The scenario requires a custom login response.

Important: While typically successful, there are times when configuring WebSEAL to remove a cookie might not remove cookies from client systems. For example, following a request for /pkmslogout and a successful session termination at WebSEAL, a network issue might interfere with the logout response transmission. In the scenario, the stale session cookie is left on the client system.

For this reason, security-sensitive decisions must not be based on the presence of the cookie, or the OLDSESSION macro value.

Note: An intentional logout does not leave a user with a stale cookie because it is normal browser operation to remove session cookies when a browser closes. A user logs out intentionally by closing the browser application, and the OLDSESSION macro is not set during the next request by that user.

However, the user session cache entry remains on the WebSEAL server, or Session Management Server. It continues to count against the max-concurrent-web-sessions policy setting until the cache entry expires because of lifetime or inactivity timeout.

Parent topic: Session removal and old session cookie concepts

Enabling customized responses for old session cookiesEnabling customized responses for old session cookiesConfigure WebSEAL to enable customized responses for old session cookiesYou can configure WebSEAL to enable customized responses for old session cookies.old session cookiesenabling customized responsescustomized responsesold session cookiesConfigure WebSEAL to remove session cookies from the browsers of users who logs out in a standard manner. The logout-remove-cookie stanza entry in the [session] WebSEAL configuration file stanza controls the removal of session cookies from the browsers of users who does a standard log out. The user enters the /pkmslogout command in the command line to log out in a standard manner.A value of yes sets WebSEAL to attempt to remove the cookies from the browsers of users who logs out in a standard manner. For example:[session] logout-remove-cookie = yes.Customize the appropriate WebSEAL login form, such as login.html to do the following actions: To read the value of the OLDSESSION macro.To generate a custom response to the user when the macro value is set to 1.You can use any of the following tools to check the OLDSESSION macro in the login form:JavascriptHTML Meta tagsLocal response redirection See Local response redirection for details.Compatibility with WebSEAL versions before version 6.0:The logout-remove-cookie = no default setting sets WebSEAL not to remove cookies from the browsers of users who logs out in a standard manner. For example:[session] logout-remove-cookie = noThe default no value exists for compatibility with WebSEAL versions before version 6.0.Customized responses for old session cookies

Enabling customized responses for old session cookies

You can configure WebSEAL to enable customized responses for old session cookies.

Procedure

Configure WebSEAL to remove session cookies from the browsers of users who logs out in a standard manner.

The logout-remove-cookie stanza entry in the [session] WebSEAL configuration file stanza controls the removal of session cookies from the browsers of users who does a standard log out.

The user enters the /pkmslogout command in the command line to log out in a standard manner.

A value of yes sets WebSEAL to attempt to remove the cookies from the browsers of users who logs out in a standard manner. For example:[session] logout-remove-cookie = yes.

Customize the appropriate WebSEAL login form, such as login.html to do the following actions:

To read the value of the OLDSESSION macro.

To generate a custom response to the user when the macro value is set to 1.

You can use any of the following tools to check the OLDSESSION macro in the login form:

Javascript

HTML Meta tags

Local response redirection

See Local response redirection for details.

Results

Compatibility with WebSEAL versions before version 6.0:

The logout-remove-cookie = no default setting sets WebSEAL not to remove cookies from the browsers of users who logs out in a standard manner. For example:

[session]
logout-remove-cookie = no

The default no value exists for compatibility with WebSEAL versions before version 6.0.

Parent topic: Customized responses for old session cookies

Maintain session state with HTTP headersMaintain session state with HTTP headerssession stateHTTP headersHTTP headerssession state maintenanceFederated Identity Manager (TFIM) supportmaintain session state with HTTP headersTFIM (Federated Identity Manager) supportmaintain session state with HTTP headersThis section contains the following topics:Session state in non-clustered environmentsMaintain session state in non-clustered environmentsSession cookiesCustomized responses for old session cookiesShare sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.HTTP header session key conceptsWebSEAL provides support for maintaining session state using HTTP headers as session keys, independent of the authentication method used.Configuring HTTP headers to maintain session stateSetup for requiring requests from an MPA

Maintain session state with HTTP headers

This section contains the following topics:

HTTP header session key concepts
WebSEAL provides support for maintaining session state using HTTP headers as session keys, independent of the authentication method used.

Configuring HTTP headers to maintain session state

Setup for requiring requests from an MPA

Parent topic: Session state in non-clustered environments

Related concepts:

Maintain session state in non-clustered environments

Session cookies

Customized responses for old session cookies

Share sessions with Microsoft Office applications

HTTP header session key conceptsHTTP header session key conceptsWebSEAL provides support for maintaining session state using HTTP headers as session keys, independent of the authentication method used.HTTP headerssession key conceptskey conceptsFor example, to allow simultaneous mobile device and internet user support, a Tivoli Federated Identity Manager environment requires that WebSEAL use a pre-supplied HTTP header to maintain session state for wireless device clients.In this scenario, mobile device users connect to a WebSEAL-protected intranet through an authenticated multiplexing proxy agent (MPA) gateway. The WAP gateway serves as a Liberty-enabled proxy (LEP). An LEP is a networking standard created by the Liberty Alliance Project (LAP).Session state with clients is maintained and managed through Mobile Station Integrated Services Digital Network (MSISDN) HTTP headers. HTTP headers used as session keys are only accepted by WebSEAL when requests are proxied through an authenticated multiplexing proxy agent (MPA).Maintain session state with HTTP headers

HTTP header session key concepts

WebSEAL provides support for maintaining session state using HTTP headers as session keys, independent of the authentication method used.

For example, to allow simultaneous mobile device and internet user support, a Tivoli® Federated Identity Manager environment requires that WebSEAL use a pre-supplied HTTP header to maintain session state for wireless device clients.

In this scenario, mobile device users connect to a WebSEAL-protected intranet through an authenticated multiplexing proxy agent (MPA) gateway. The WAP gateway serves as a Liberty-enabled proxy (LEP). An LEP is a networking standard created by the Liberty Alliance Project (LAP).

Session state with clients is maintained and managed through Mobile Station Integrated Services Digital Network (MSISDN) HTTP headers. HTTP headers used as session keys are only accepted by WebSEAL when requests are proxied through an authenticated multiplexing proxy agent (MPA).

Parent topic: Maintain session state with HTTP headers

Configuring HTTP headers to maintain session stateConfiguring HTTP headers to maintain session statestanzassession-http-headerssession-http-headers stanzastanzassession-http-headerssession-http-headers stanzaTo configure HTTP headers to maintain session state, specify the header names in the [session-http-headers] stanza of the WebSEAL configuration file. Each header is listed on a per-transport basis. The same header can be listed for both transports. Valid transports include "http" and "https". Use the following syntax: [session-http-headers] header-name = http|https For example: [session-http-headers] entrust-client = http entrust-client = https Conditions for HTTP header session key configuration: To allow HTTP headers to be used for maintaining session state, you must set: [session] ssl-id-sessions = noIf ssl-id-sessions = yes, the [session-http-headers] stanza is ignored. An exception occurs if MPA support is enabled: [mpa] mpa = yesWebSEAL must be configured to accept only HTTP headers in requests proxied through an authenticated multiplexing proxy agent (MPA). See Setup for requiring requests from an MPA.List all headers that are to be used for maintaining sessions.Limit the header list to no more than 20 entries per transport. Do not include the colon (:) character in the header names.HTTP headers can be enabled and disabled on a per-transport basis. Process flow for establishing session state with HTTP headers: Session cookies always take precedence over HTTP headers for maintaining session state. Upon receiving a request, WebSEAL first looks for a session cookie before continuing to look for configured HTTP headers. If an incoming request contains a WebSEAL session cookie, WebSEAL does not look for any configured HTTP headers.If a request (containing no session cookie) has an HTTP header matching an entry in the [session-http-headers] stanza, that HTTP header is used to maintain session state for that client.More than one header can be entered into the [session-http-headers] stanza. WebSEAL stops searching requests when the first matching HTTP header is found, regardless of whether or not the header is a key to an existing cache entry. For example, two headers are configured in the order header A, then header B. A session is established using header B. Header A is for some reason added to a later request from the same client. WebSEAL searches the [session-http-headers] stanza and finds a match with header A. Because the existing entry for that client in the session cache is based on header B, WebSEAL does not find an existing session cache entry and prompts the user to authenticate.If no entries exist in the [session-http-headers] stanza, WebSEAL uses session cookies to maintain session state.If ssl-id-sessions = no and none of the configured HTTP headers are found in an incoming request, WebSEAL uses session cookies to maintain sessions.Maintain session state with HTTP headers

Configuring HTTP headers to maintain session state

About this task

To configure HTTP headers to maintain session state, specify the header names in the [session-http-headers] stanza of the WebSEAL configuration file.

Each header is listed on a per-transport basis. The same header can be listed for both transports. Valid transports include "http" and "https". Use the following syntax:

[session-http-headers]
header-name = http|https

For example:

[session-http-headers]
entrust-client = http
entrust-client = https

Conditions for HTTP header session key configuration:

To allow HTTP headers to be used for maintaining session state, you must set:

[session]
ssl-id-sessions = no

If ssl-id-sessions = yes, the [session-http-headers] stanza is ignored. An exception occurs if MPA support is enabled:

[mpa]
mpa = yes

WebSEAL must be configured to accept only HTTP headers in requests proxied through an authenticated multiplexing proxy agent (MPA). See Setup for requiring requests from an MPA.

List all headers that are to be used for maintaining sessions.

Limit the header list to no more than 20 entries per transport.

Do not include the colon (:) character in the header names.

HTTP headers can be enabled and disabled on a per-transport basis.

Process flow for establishing session state with HTTP headers:

Session cookies always take precedence over HTTP headers for maintaining session state.

Upon receiving a request, WebSEAL first looks for a session cookie before continuing to look for configured HTTP headers.

If an incoming request contains a WebSEAL session cookie, WebSEAL does not look for any configured HTTP headers.

If a request (containing no session cookie) has an HTTP header matching an entry in the [session-http-headers] stanza, that HTTP header is used to maintain session state for that client.

More than one header can be entered into the [session-http-headers] stanza. WebSEAL stops searching requests when the first matching HTTP header is found, regardless of whether or not the header is a key to an existing cache entry.

For example, two headers are configured in the order header A, then header B. A session is established using header B. Header A is for some reason added to a later request from the same client. WebSEAL searches the [session-http-headers] stanza and finds a match with header A. Because the existing entry for that client in the session cache is based on header B, WebSEAL does not find an existing session cache entry and prompts the user to authenticate.

If no entries exist in the [session-http-headers] stanza, WebSEAL uses session cookies to maintain session state.

If ssl-id-sessions = no and none of the configured HTTP headers are found in an incoming request, WebSEAL uses session cookies to maintain sessions.

Parent topic: Maintain session state with HTTP headers

Setup for requiring requests from an MPASetup for requiring requests from an MPArequire-mpa stanza entryrequire-mpa stanza entryMPArequiring requestsThe use of HTTP headers to maintain session state involves the risk that the session keys can be stolen and user sessions spoofed. In an environment involving clients with mobile devices, MSISDN telephone numbers are used as the values of the session keys. Unlike the large size and random nature of session cookie key values, telephone numbers have a smaller, more predictable, and therefore less secure format.In a secure WebSEAL environment, HTTP header session keys are only valid when requests are proxied through an authenticated multiplexing proxy agent (MPA). The require-mpa stanza entry in the [session] stanza of the WebSEAL configuration file allows you to control this requirement.A "yes" setting instructs WebSEAL to only accept HTTP headers from requests that are proxied through an authenticated multiplexing proxy agent (MPA). WebSEAL must authenticate the gateway itself before accepting proxied client connections. For example:[session] require-mpa = yesA "no" setting allows WebSEAL to accept HTTP headers under any condition. For example:[session] require-mpa = noA WebSEAL implementation with an MPA must adhere to the following conditions:To avoid conflicts, the MPA cannot use the same session key type as a client accessing WebSEAL through the MPA. For example, if the MPA maintains sessions using session cookies, a client session must be maintained sessions by a different mechanism.To avoid conflicts, the MPA cannot use the same authentication method as a client accessing WebSEAL through the MPA. For example, if the MPA uses forms authentication, the client must authenticate using some other mechanism, such as the external authentication interface. In a typical scenario, the MPA uses basic authentication or certificate authentication, and the client uses the external authentication interface. If WebSEAL is upgraded to 6.1 or later from a previous release that supports HTTP header authentication, the default value for require-mpa changes from no to yes. If HTTP header authentication is being used, the upgrade causes authentication to fail until require-mpa is set to no.Maintain session state with HTTP headers

Setup for requiring requests from an MPA

The use of HTTP headers to maintain session state involves the risk that the session keys can be stolen and user sessions spoofed. In an environment involving clients with mobile devices, MSISDN telephone numbers are used as the values of the session keys. Unlike the large size and random nature of session cookie key values, telephone numbers have a smaller, more predictable, and therefore less secure format.

In a secure WebSEAL environment, HTTP header session keys are only valid when requests are proxied through an authenticated multiplexing proxy agent (MPA). The require-mpa stanza entry in the [session] stanza of the WebSEAL configuration file allows you to control this requirement.

A "yes" setting instructs WebSEAL to only accept HTTP headers from requests that are proxied through an authenticated multiplexing proxy agent (MPA). WebSEAL must authenticate the gateway itself before accepting proxied client connections. For example:

[session]
require-mpa = yes

A "no" setting allows WebSEAL to accept HTTP headers under any condition. For example:

[session]
require-mpa = no

A WebSEAL implementation with an MPA must adhere to the following conditions:

To avoid conflicts, the MPA cannot use the same session key type as a client accessing WebSEAL through the MPA.

For example, if the MPA maintains sessions using session cookies, a client session must be maintained sessions by a different mechanism.

To avoid conflicts, the MPA cannot use the same authentication method as a client accessing WebSEAL through the MPA.

For example, if the MPA uses forms authentication, the client must authenticate using some other mechanism, such as the external authentication interface. In a typical scenario, the MPA uses basic authentication or certificate authentication, and the client uses the external authentication interface.

Note: If WebSEAL is upgraded to 6.1 or later from a previous release that supports HTTP header authentication, the default value for require-mpa changes from no to yes. If HTTP header authentication is being used, the upgrade causes authentication to fail until require-mpa is set to no.

Parent topic: Maintain session state with HTTP headers

Share sessions with Microsoft Office applicationsShare sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.Microsoft OfficeSession sharingsession sharingMicrosoft Office applicationssession sharingMicrosoft Office applicationsMicrosoft Officesession sharingSession state in non-clustered environmentsMaintain session state in non-clustered environmentsSession cookiesCustomized responses for old session cookiesMaintain session state with HTTP headersOverview of session sharing with Microsoft Office applicationsConfigure the temporary session cacheYou can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.Configure shared sessions with Microsoft Office applicationsYou can configure WebSEAL to use the temporary session cache so that both Internet Explorer and Microsoft Office products can reference the same user session.

Share sessions with Microsoft Office applications

You can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.

Overview of session sharing with Microsoft Office applications

Configure the temporary session cache
You can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.

Configure shared sessions with Microsoft Office applications
You can configure WebSEAL to use the temporary session cache so that both Internet Explorer and Microsoft Office products can reference the same user session.

Parent topic: Session state in non-clustered environments

Related concepts:

Maintain session state in non-clustered environments

Session cookies

Customized responses for old session cookies

Maintain session state with HTTP headers

Overview of session sharing with Microsoft Office applicationsOverview of session sharing with Microsoft Office applicationsMicrosoft Officesession sharingsession sharingoverviewYou can configure WebSEAL to use cookies to maintain client sessions. For security reasons, WebSEAL uses non-persistent cookies. Since Internet Explorer and Microsoft Office are only capable of sharing persistent cookies, the Microsoft Office applications cannot share the WebSEAL user session by default. You can configure WebSEAL to create a short-lived persistent session cookie. This cookie stores an index into a temporary session cache that WebSEAL uses to locate the corresponding session in the standard session cache. You can configure this temporary cache entry for a single use or multiple uses by WebSEAL. The cache is not shared between WebSEAL instances. Microsoft Office applications can use the persistent cookie to locate the corresponding user session from Internet Explorer.A request for the /pkmstempsession URI triggers the creation of this temporary session cookie. You can include a target redirect URL in the /pkmstempsession request. WebSEAL redirects the client to this URL when the processing of the /pkmstempsession request is complete. If no redirect URL is provided, WebSEAL returns a default results page to the client.http://<server>/pkmstempsession?url=<requested_resource>where:<server>The fully qualified host name of the WebSEAL server.<requested_resource>The location of the target resource. For example, a Microsoft Office document: /server/test.doc.The request resource URL can optionally contain query string arguments. These arguments remain unchanged in the resulting WebSEAL redirect request. The short-lived persistent cookie is created by sending a request to the /pkmstempsession URI. This cookie creation must occur before the client switches context from WebSEAL to Microsoft Office. See Configure shared sessions with Microsoft Office applicationsYou can configure WebSEAL to use the temporary session cache so that both Internet Explorer and Microsoft Office products can reference the same user session. for configuration details of two common use cases in a Microsoft Office environment.Share sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.

Overview of session sharing with Microsoft Office applications

You can configure WebSEAL to use cookies to maintain client sessions. For security reasons, WebSEAL uses non-persistent cookies. Since Internet Explorer and Microsoft Office are only capable of sharing persistent cookies, the Microsoft Office applications cannot share the WebSEAL user session by default.

You can configure WebSEAL to create a short-lived persistent session cookie. This cookie stores an index into a temporary session cache that WebSEAL uses to locate the corresponding session in the standard session cache.

You can configure this temporary cache entry for a single use or multiple uses by WebSEAL. The cache is not shared between WebSEAL instances. Microsoft Office applications can use the persistent cookie to locate the corresponding user session from Internet Explorer.

A request for the /pkmstempsession URI triggers the creation of this temporary session cookie. You can include a target redirect URL in the /pkmstempsession request. WebSEAL redirects the client to this URL when the processing of the /pkmstempsession request is complete. If no redirect URL is provided, WebSEAL returns a default results page to the client.

http://<server>/pkmstempsession?url=<requested_resource>

where:

<server>

The fully qualified host name of the WebSEAL server.

<requested_resource>

The location of the target resource.

For example, a Microsoft Office document: /server/test.doc.

Note: The request resource URL can optionally contain query string arguments. These arguments remain unchanged in the resulting WebSEAL redirect request.

The short-lived persistent cookie is created by sending a request to the /pkmstempsession URI. This cookie creation must occur before the client switches context from WebSEAL to Microsoft Office. See Configure shared sessions with Microsoft Office applications for configuration details of two common use cases in a Microsoft Office environment.

Parent topic: Share sessions with Microsoft Office applications

Configure the temporary session cacheConfigure the temporary session cacheYou can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.session sharingtemporary session cachetemporary session cachesession cachetemporaryThe following WebSEAL configuration settings are related to the temporary session cache.Configuring the lifetime of entries in the temporary session cacheYou can configure the maximum lifetime of entries in the temporary session cache that WebSEAL uses for session sharing with Microsoft Office applications.Controlling whether the temporary session cache cookies are single useYou can control whether the client can access an entry in the temporary session cache more than once. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie. Configuring the name of the temporary session cookieYou can configure the name of the temporary session cookie that WebSEAL creates to share a session with Microsoft Office applications.Configuring the temporary cache response pageShare sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.Configuring the lifetime of entries in the temporary session cacheYou can configure the maximum lifetime of entries in the temporary session cache that WebSEAL uses for session sharing with Microsoft Office applications.Controlling whether the temporary session cache cookies are single useYou can control whether the client can access an entry in the temporary session cache more than once. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie. Configuring the name of the temporary session cookieYou can configure the name of the temporary session cookie that WebSEAL creates to share a session with Microsoft Office applications.Configuring the temporary cache response page

Configure the temporary session cache

You can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.

The following WebSEAL configuration settings are related to the temporary session cache.

Configuring the lifetime of entries in the temporary session cache

Controlling whether the temporary session cache cookies are single use

Configuring the name of the temporary session cookie

Configuring the temporary cache response page

Configuring the lifetime of entries in the temporary session cache
You can configure the maximum lifetime of entries in the temporary session cache that WebSEAL uses for session sharing with Microsoft Office applications.

Controlling whether the temporary session cache cookies are single use
You can control whether the client can access an entry in the temporary session cache more than once. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie.

Configuring the name of the temporary session cookie
You can configure the name of the temporary session cookie that WebSEAL creates to share a session with Microsoft Office applications.

Configuring the temporary cache response page

Parent topic: Share sessions with Microsoft Office applications

Configuring the lifetime of entries in the temporary session cacheConfiguring the lifetime of entries in the temporary session cacheYou can configure the maximum lifetime of entries in the temporary session cache that WebSEAL uses for session sharing with Microsoft Office applications.Microsoft Officeconfiguring lifetime of entriessession sharingconfigurationtemporary session lifetimetemp-session-max-lifetime stanza entry[session] stanzaThe temporary session cache stores a short-lived session. WebSEAL uses this cache to create an intermediate session that maps between the short-lived session and the standard session. The index into the temporary session cache is returned to the client as a persistent cookie.Use the temp-session-max-lifetime entry in the [session] stanza of the WebSEAL configuration file to set the maximum lifetime (in seconds) of entries in the temporary session cache.Set the temp-session-max-lifetime value to 0 to disable the use of the temporary session cache. The following example configures a maximum lifetime duration of 10 seconds:[session] temp-session-max-lifetime = 10Configure the temporary session cacheYou can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.

Configuring the lifetime of entries in the temporary session cache

You can configure the maximum lifetime of entries in the temporary session cache that WebSEAL uses for session sharing with Microsoft Office applications.

About this task

The temporary session cache stores a short-lived session. WebSEAL uses this cache to create an intermediate session that maps between the short-lived session and the standard session. The index into the temporary session cache is returned to the client as a persistent cookie.

Use the temp-session-max-lifetime entry in the [session] stanza of the WebSEAL configuration file to set the maximum lifetime (in seconds) of entries in the temporary session cache.

Procedure

Set the temp-session-max-lifetime value to 0 to disable the use of the temporary session cache.

Example

The following example configures a maximum lifetime duration of 10 seconds:

[session]
temp-session-max-lifetime = 10

Parent topic: Configure the temporary session cache

Controlling whether the temporary session cache cookies are single useControlling whether the temporary session cache cookies are single useYou can control whether the client can access an entry in the temporary session cache more than once. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie. Microsoft Officesingle use session cache cookiessession sharingconfigurationsingle-use cookiesession sharingtemp-session-one-time-use stanza entrysession sharing[session] stanzaThe temporary session cache stores a short-lived session. WebSEAL uses this cache to create an intermediate session that maps between the short-lived session and the standard session. The index into the temporary session cache is returned to the client as a persistent cookie.Locate the [session] stanza in the WebSEAL configuration file.Set the temp-session-one-time-use entry to one of the following values:trueSpecifies that the client can use the temporary session cookie one time.falseSpecifies that the client can access and use the temporary session entry multiple times until temp-session-max-lifetime expires. Use this setting if you want to share sessions with Microsoft Office applications, such as Microsoft SharePoint.In the following example, WebSEAL creates a single-use cookie in the temporary session cache:[session] temp-session-one-time-use = trueConfigure the temporary session cacheYou can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.

Controlling whether the temporary session cache cookies are single use

You can control whether the client can access an entry in the temporary session cache more than once. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie.

About this task

The temporary session cache stores a short-lived session. WebSEAL uses this cache to create an intermediate session that maps between the short-lived session and the standard session. The index into the temporary session cache is returned to the client as a persistent cookie.

Procedure

Locate the [session] stanza in the WebSEAL configuration file.

Set the temp-session-one-time-use entry to one of the following values:

true

Specifies that the client can use the temporary session cookie one time.

false

Specifies that the client can access and use the temporary session entry multiple times until temp-session-max-lifetime expires. Use this setting if you want to share sessions with Microsoft Office applications, such as Microsoft SharePoint.

Example

In the following example, WebSEAL creates a single-use cookie in the temporary session cache:

[session]
temp-session-one-time-use = true

Parent topic: Configure the temporary session cache

Configuring the name of the temporary session cookieConfiguring the name of the temporary session cookieYou can configure the name of the temporary session cookie that WebSEAL creates to share a session with Microsoft Office applications.Microsoft Officename of temporary session cookiesession sharingconfigurationtemporary session cookie nametemp-session-cookie-name stanza entry[session] stanzaWebSEAL creates the short-lived session cookie in response to a request for the /pkmstempsession management page. This cookie stores an index into the temporary session cache that WebSEAL uses later to locate the corresponding session in the standard session cache.Use the temp-session-cookie-name entry in the [session] stanza of the WebSEAL configuration file to specify the name of the temporary session cookie.This configuration item is valid only when the temporary session cache is enabled. To enable the cache, you must set a non-zero value for the temp-session-cookie-name entry in the [session] stanza.The following example configures a cookie name of PD-TEMP-SESSION-ID:[session] temp-session-cookie-name = PD-TEMP-SESSION-IDConfigure the temporary session cacheYou can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.

Configuring the name of the temporary session cookie

You can configure the name of the temporary session cookie that WebSEAL creates to share a session with Microsoft Office applications.

About this task

WebSEAL creates the short-lived session cookie in response to a request for the /pkmstempsession management page. This cookie stores an index into the temporary session cache that WebSEAL uses later to locate the corresponding session in the standard session cache.

Procedure

Use the temp-session-cookie-name entry in the [session] stanza of the WebSEAL configuration file to specify the name of the temporary session cookie.

Note: This configuration item is valid only when the temporary session cache is enabled. To enable the cache, you must set a non-zero value for the temp-session-cookie-name entry in the [session] stanza.

Example

The following example configures a cookie name of PD-TEMP-SESSION-ID:

[session]
temp-session-cookie-name = PD-TEMP-SESSION-ID

Parent topic: Configure the temporary session cache

Configuring the temporary cache response pageConfiguring the temporary cache response pageMicrosoft Officeconfiguring temporary cache response pagesession sharingconfigurationtemporary cache response pagetemp-cache-response stanza entry[acnt-mgt] stanzaUse the temp-cache-response entry in the [acnt-mgt] stanza of the WebSEAL configuration file to set the default management page. WebSEAL returns this page after processing a pkmstempsession request if no redirect URL is supplied in the pkmstempsession request. By default, WebSEAL returns temp_cache_response.html.[acnt-mgt] temp-cache-response = temp_cache_response.htmlThe following example illustrates a typical request: http://<server>/pkmstempsession?url=<requested_resource>If the url argument is not included in the request then WebSEAL returns the page specified by the temp-cache-response configuration entry.Configure the temporary session cacheYou can configure the temporary session cache that WebSEAL uses for its session sharing functionality. In particular, you can control the lifetime of cache entries, specify the name of the temporary session cookie, and configure the default results page.

Configuring the temporary cache response page

About this task

Use the temp-cache-response entry in the [acnt-mgt] stanza of the WebSEAL configuration file to set the default management page. WebSEAL returns this page after processing a pkmstempsession request if no redirect URL is supplied in the pkmstempsession request.

By default, WebSEAL returns temp_cache_response.html.

[acnt-mgt]
temp-cache-response = temp_cache_response.html

Example

The following example illustrates a typical request:

http://<server>/pkmstempsession?url=<requested_resource>

If the url argument is not included in the request then WebSEAL returns the page specified by the temp-cache-response configuration entry.

Parent topic: Configure the temporary session cache

Configure shared sessions with Microsoft Office applicationsConfigure shared sessions with Microsoft Office applicationsYou can configure WebSEAL to use the temporary session cache so that both Internet Explorer and Microsoft Office products can reference the same user session.Microsoft Officesession sharingsession sharingconfigurationshared sessionsA request to the /pkmstempsession management page creates a temporary session cookie. Both Internet Explorer and Microsoft Office products can access this session cookie. You can use Ajax requests to automatically request this management page and trigger the creation of a persistent session cookie. Through this process, you can achieve session sharing with applications that are accessed through Internet Explorer. Share sessions with Microsoft Office applicationsYou can configure WebSEAL to instruct browsers to share session information with Microsoft Office applications. Sharing session information avoids the need for the Microsoft Office applications to re-authenticate the user.Microsoft SharePoint 2007 serverYou can modify the JavaScript on the Microsoft SharePoint 2007 server so that Internet Explorer and Microsoft Office can share the same session when accessing a SharePoint resource.

Configure shared sessions with Microsoft Office applications

You can configure WebSEAL to use the temporary session cache so that both Internet Explorer and Microsoft Office products can reference the same user session.

A request to the /pkmstempsession management page creates a temporary session cookie. Both Internet Explorer and Microsoft Office products can access this session cookie.

You can use Ajax requests to automatically request this management page and trigger the creation of a persistent session cookie. Through this process, you can achieve session sharing with applications that are accessed through Internet Explorer.

Microsoft SharePoint 2007 server
You can modify the JavaScript on the Microsoft SharePoint 2007 server so that Internet Explorer and Microsoft Office can share the same session when accessing a SharePoint resource.

Parent topic: Share sessions with Microsoft Office applications

Microsoft SharePoint 2007 serverMicrosoft SharePoint serverYou can modify the JavaScript on the Microsoft SharePoint 2007 server so that Internet Explorer and Microsoft Office can share the same session when accessing a SharePoint resource.Microsoft OfficeSharePoint serversession sharingconfigurationMicrosoft SharePoint serverTo achieve session sharing with Microsoft SharePoint server, the SharePoint administrator must determine when to create the persistent session cookie for sharing sessions. The goal is to request the pkmstempsession management page immediately before the context switch for the requested resource. SharePoint does not send any notification to WebSEAL before this context switch. However, you can create a custom JavaScript file on the SharePoint server, to automatically send an Ajax request to WebSEAL before accessing the requested resource. This Ajax HTTP request can collect the session cookie for the temporary session cache. You must configure SharePoint to use this custom JavaScript file instead of core.js.Do not directly update the core.js file on the SharePoint Server. Updating this file directly is not a supported SharePoint modification. Instead, create a custom JavaScript file and custom master page to override the required functions of core.js. Use the custom master page to configure your site collections to use these updated JavaScript functions.Sharing WebSEAL sessions with Microsoft SharePoint serverSharing sessions with Microsoft SharePoint serverFigure 1 illustrates the temporary session cache sequence of operations.When WebSEAL starts, it initializes the temporary cache.The client authenticates to the WebSEAL server.The client sends a request for a SharePoint resource.SharePoint sends a response back to the client that includes JavaScript (customcore.js).Before sending the SharePoint resource request, the updated JavaScript sends an Ajax HTTP request for /pkmstempsession.WebSEAL adds an entry for the session in the temporary cache.WebSEAL sets a short-lived cookie with the session information.WebSEAL adds the short-lived cookie to the response that is returned to the client browser.The client switches context to MS Office/ActiveX and the application uses the GET method to send the SharePoint document request.WebSEAL retrieves the session information from the temporary cache and then deletes the entry so that the cookie cannot be used again.WebSEAL fetches the requested resource from the SharePoint server.WebSEAL returns the document to the client with the session cookie set.Copy the core.js file. Paste the copy into the folder that contains the core.js file and rename it as customcore.js.In a default SharePoint 2007 installation, you can find the core.js file at: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ TEMPLATE\LAYOUTS\core.jsOpen the custom JavaScript file (customcore.js) for editing. You must modify the JavaScript to make an out of band Ajax HTTP request to the /pkmstempsession page. Add the following JavaScript to any link that opens the Office Document by using the ActiveX Controls. In particular, add the new JavaScript at the beginning of the following functions in the customcore.js file on the SharePoint Server:function DispEx(...)function createNewDocumentWithProgIDCore(...)Remove all of the other JavaScript functions from customcore.js so that it contains only the functions that are being overridden. Deleting the functions that are not needed improves processing efficiency.Example JavaScriptvar cookieRequest = false; try { cookieRequest = new XMLHttpRequest(); } catch (trymicrosoft) { try { cookieRequest = new ActiveXObject("Msxml2.XMLHTTP"); } catch (othermicrosoft) { try { cookieRequest = new ActiveXObject("Microsoft.XMLHTTP"); } catch (failed) { cookieRequest = false; } } } if (cookieRequest) { var url = "/pkmstempsession"; cookieRequest.open("GET", url, false); cookieRequest.send(null); if (cookieRequest.status != 200){ alert("ERROR: Single-Signon Cookie Request Failed!,Application may not load Document"); } }If you are using the default.master page as the master page in your SharePoint site, make a copy of the default.master page. Rename the copy as custom.master.In a default SharePoint 2007 installation, you can find the default.master file at: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ TEMPLATE\GLOBAL\default.masterIn the custom.master page, add a line to use the customcore.js file. Insert this new entry immediately after the existing entry that references core.js as follows:<SharePoint:ScriptLink language="javascript" name="core.js" Defer="true" runat="server"/> <SharePoint:ScriptLink language="javascript" name="customcore.js" Defer="true" runat="server"/>You must keep a reference to the original core.js file in this custom master page. You must set the Defer="true" property to override the original core.js file.Save the custom.master page and upload it to the master pages gallery of the site. Set the custom.master page as the default master page for the site:Log in to your site in SharePoint.Go to Site ActionSite SettingsModify All Site SettingsLook and FeelMaster Page.Select Specify a master page to be used by this site and all sites that inherit from it.Select custom.master from the drop-down list.The Defer="true" setting specifies the load order of the SharePoint functions. Including two entries with Defer="true" effectively merges the JavaScript files together. The entry for the customcore.js file is included in the master page source after the entry for the core.js file because SharePoint runs the deferred scripts in order. SharePoint runs core.js first, followed by the overriding customcore.js script.Be aware of the following considerations if you use custom JavaScript functions to override core.js:To minimize the amount of script that is transmitted during processing, keep only the methods that you want to customize in the customcore.js file.If you upgrade the SharePoint product or install a patch, review your custom scripts against the updated core.js to ensure that the override scripts are still applicable.Configure shared sessions with Microsoft Office applicationsYou can configure WebSEAL to use the temporary session cache so that both Internet Explorer and Microsoft Office products can reference the same user session.

Microsoft SharePoint 2007 server

You can modify the JavaScript on the Microsoft SharePoint 2007 server so that Internet Explorer and Microsoft Office can share the same session when accessing a SharePoint resource.

About this task

To achieve session sharing with Microsoft SharePoint server, the SharePoint administrator must determine when to create the persistent session cookie for sharing sessions. The goal is to request the pkmstempsession management page immediately before the context switch for the requested resource.

SharePoint does not send any notification to WebSEAL before this context switch. However, you can create a custom JavaScript file on the SharePoint server, to automatically send an Ajax request to WebSEAL before accessing the requested resource. This Ajax HTTP request can collect the session cookie for the temporary session cache. You must configure SharePoint to use this custom JavaScript file instead of core.js.

Note: Do not directly update the core.js file on the SharePoint Server. Updating this file directly is not a supported SharePoint modification. Instead, create a custom JavaScript file and custom master page to override the required functions of core.js. Use the custom master page to configure your site collections to use these updated JavaScript functions.

Figure 22. Sharing WebSEAL sessions with Microsoft SharePoint server

Figure 22. illustrates the temporary session cache sequence of operations.

When WebSEAL starts, it initializes the temporary cache.

The client authenticates to the WebSEAL server.

The client sends a request for a SharePoint resource.

SharePoint sends a response back to the client that includes JavaScript (customcore.js).

Before sending the SharePoint resource request, the updated JavaScript sends an Ajax HTTP request for /pkmstempsession.

WebSEAL adds an entry for the session in the temporary cache.

WebSEAL sets a short-lived cookie with the session information.

WebSEAL adds the short-lived cookie to the response that is returned to the client browser.

The client switches context to MS Office/ActiveX and the application uses the GET method to send the SharePoint document request.

WebSEAL retrieves the session information from the temporary cache and then deletes the entry so that the cookie cannot be used again.

WebSEAL fetches the requested resource from the SharePoint server.

WebSEAL returns the document to the client with the session cookie set.

Procedure

Copy the core.js file. Paste the copy into the folder that contains the core.js file and rename it as customcore.js.

In a default SharePoint 2007 installation, you can find the core.js file at:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\
TEMPLATE\LAYOUTS\core.js

Open the custom JavaScript file (customcore.js) for editing.

You must modify the JavaScript to make an out of band Ajax HTTP request to the /pkmstempsession page. Add the following JavaScript to any link that opens the Office Document by using the ActiveX Controls. In particular, add the new JavaScript at the beginning of the following functions in the customcore.js file on the SharePoint Server:

function DispEx(...)

function createNewDocumentWithProgIDCore(...)

Note: Remove all of the other JavaScript functions from customcore.js so that it contains only the functions that are being overridden. Deleting the functions that are not needed improves processing efficiency.

Example JavaScript

var cookieRequest = false;
try {
	cookieRequest = new XMLHttpRequest();
}
catch (trymicrosoft) {
	try {
		cookieRequest = new ActiveXObject("Msxml2.XMLHTTP");
	} catch (othermicrosoft) {
		try {
			cookieRequest = new ActiveXObject("Microsoft.XMLHTTP");
		} catch (failed) {
			cookieRequest = false;
		}
	}
}
if (cookieRequest) {
	var url = "/pkmstempsession";
	cookieRequest.open("GET", url, false);
	cookieRequest.send(null);
	if (cookieRequest.status != 200){
		alert("ERROR: Single-Signon Cookie Request Failed!,Application may not load Document");
	}
}

If you are using the default.master page as the master page in your SharePoint site, make a copy of the default.master page. Rename the copy as custom.master.

In a default SharePoint 2007 installation, you can find the default.master file at:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\
TEMPLATE\GLOBAL\default.master

In the custom.master page, add a line to use the customcore.js file. Insert this new entry immediately after the existing entry that references core.js as follows:

<SharePoint:ScriptLink language="javascript" name="core.js" Defer="true"
			runat="server"/>
<SharePoint:ScriptLink language="javascript" name="customcore.js" Defer="true"
			runat="server"/>

Note: You must keep a reference to the original core.js file in this custom master page. You must set the Defer="true" property to override the original core.js file.

Save the custom.master page and upload it to the master pages gallery of the site.

Set the custom.master page as the default master page for the site:

Log in to your site in SharePoint.

Go to Site Action > Site Settings > Modify All Site Settings > Look and Feel > Master Page.

Select Specify a master page to be used by this site and all sites that inherit from it.

Select custom.master from the drop-down list.

Results

The Defer="true" setting specifies the load order of the SharePoint functions. Including two entries with Defer="true" effectively merges the JavaScript files together. The entry for the customcore.js file is included in the master page source after the entry for the core.js file because SharePoint runs the deferred scripts in order. SharePoint runs core.js first, followed by the overriding customcore.js script.

Note: Be aware of the following considerations if you use custom JavaScript functions to override core.js:

To minimize the amount of script that is transmitted during processing, keep only the methods that you want to customize in the customcore.js file.

If you upgrade the SharePoint product or install a patch, review your custom scripts against the updated core.js to ensure that the override scripts are still applicable.

Parent topic: Configure shared sessions with Microsoft Office applications

Distributed session cacheDistributed session cacheWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.Quickstart guide for WebSEAL to use the distributed session cacheThe process for configuring WebSEAL to use the distributed session cache depends on whether WebSEAL is running on an appliance in the same cluster as the distributed session cache server. Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.

Distributed session cache

Distributed session cache overview
The following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Quickstart guide for WebSEAL to use the distributed session cache
The process for configuring WebSEAL to use the distributed session cache depends on whether WebSEAL is running on an appliance in the same cluster as the distributed session cache server.

Advanced configuration for the distributed session cache
There are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.

Parent topic: Web Reverse Proxy configuration

Distributed session cache overviewDistributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.distributed session cacheconceptsoverviewFailover cookies and the distributed session cache are alternate solutions to the same challenge of maintaining session state in clustered server environments. See also Failover solutionsUse the failover cookie solution to maintain session state in clustered environments..The distributed session cache replaces the session management server solution that was available in earlier releases of IBM Security Access Manager.Topic Index:Distributed session cacheThe failover environmentThe distributed session cache is most commonly used in a scenario where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers. The distributed session cacheThe distributed session cache is an independent service that acts as a centralized session repository for a clustered WebSEAL server environment. Servers in the cluster can use the distributed session cache to provide failover for user sessions.Failover for the distributed session cacheThe distributed session cache server is configured in a clustered environment. You can configure up to four master nodes in the cluster to ensure high availability for the distributed session cache.Replica setsA cluster of Security Access Manager servers that use the distributed session cache to share sessions is called a replica set. Distributed session cache process flowIn a distributed session cache environment, the client browser sends requests to the WebSEAL server cluster, which interacts with the distributed session cache for session management.Sharing sessions across multiple DNS domainsWhen operating in a multi-domain environment, you must use a different mechanism to communicate the session identifier to the WebSEAL servers in the different DNS domains.Advantages of using the distributed session cache to maintain session stateThe distributed session cache solution has many advantages over the failover cookies solution for maintaining session state. Migrating from a Session Management Server (SMS) environmentThe distributed session cache replaces the session management server (SMS) solution that was available in earlier releases of IBM Security Access Manager. You can configure IBM Security Access Manager, version 7.0 servers, which previously used the SMS, to use a distributed session cache server in your environment.

Distributed session cache overview

The following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Failover cookies and the distributed session cache are alternate solutions to the same challenge of maintaining session state in clustered server environments. See also Failover solutions.

The distributed session cache replaces the session management server solution that was available in earlier releases of IBM Security Access Manager.

Topic Index:

The failover environment
The distributed session cache is most commonly used in a scenario where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers.

The distributed session cache
The distributed session cache is an independent service that acts as a centralized session repository for a clustered WebSEAL server environment. Servers in the cluster can use the distributed session cache to provide failover for user sessions.

Failover for the distributed session cache
The distributed session cache server is configured in a clustered environment. You can configure up to four master nodes in the cluster to ensure high availability for the distributed session cache.

Replica sets
A cluster of Security Access Manager servers that use the distributed session cache to share sessions is called a replica set.

Distributed session cache process flow
In a distributed session cache environment, the client browser sends requests to the WebSEAL server cluster, which interacts with the distributed session cache for session management.

Sharing sessions across multiple DNS domains
When operating in a multi-domain environment, you must use a different mechanism to communicate the session identifier to the WebSEAL servers in the different DNS domains.

Advantages of using the distributed session cache to maintain session state
The distributed session cache solution has many advantages over the failover cookies solution for maintaining session state.

Migrating from a Session Management Server (SMS) environment
The distributed session cache replaces the session management server (SMS) solution that was available in earlier releases of IBM Security Access Manager. You can configure IBM Security Access Manager, version 7.0 servers, which previously used the SMS, to use a distributed session cache server in your environment.

Parent topic: Distributed session cache

The failover environmentThe failover environmentThe distributed session cache is most commonly used in a scenario where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers. distributed session cachefailover environmentfailoverenvironmentThe replicated servers are identical. They contain replica copies of the WebSEAL protected object space, junction database, and (optionally) dynurl database.The client is not aware of the replicated front-end server configuration. The load balancing mechanism is the single point of contact for the requested resource. The load balancer connects the client with an available server.Failover for replicated WebSEAL serversFailover for replicated WebSEAL serversIf the server where the client is connected suddenly becomes unavailable, the load balancer redirects the request to one of the other replicated servers. This action causes the loss of the original session-to-credential mapping. The client is new to this substitute server and is normally forced to login again.The purpose of the distributed session cache is to prevent forced login when the WebSEAL server that has the original session with the client suddenly becomes unavailable. The distributed session cache enables the client to connect to another WebSEAL server, and create an authentication session containing the same user session data and user credentials.Whenever possible, configure load balancers to maintain session affinity. Session affinity provides improved performance, improved user experience, and makes WebSEAL configuration simpler.Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

The failover environment

The distributed session cache is most commonly used in a scenario where client requests are directed by a load balancing mechanism to two or more replicated WebSEAL servers.

The replicated servers are identical. They contain replica copies of the WebSEAL protected object space, junction database, and (optionally) dynurl database.

The client is not aware of the replicated front-end server configuration. The load balancing mechanism is the single point of contact for the requested resource. The load balancer connects the client with an available server.

Figure 23. Failover for replicated WebSEAL servers

If the server where the client is connected suddenly becomes unavailable, the load balancer redirects the request to one of the other replicated servers. This action causes the loss of the original session-to-credential mapping. The client is new to this substitute server and is normally forced to login again.

The purpose of the distributed session cache is to prevent forced login when the WebSEAL server that has the original session with the client suddenly becomes unavailable. The distributed session cache enables the client to connect to another WebSEAL server, and create an authentication session containing the same user session data and user credentials.

Note: Whenever possible, configure load balancers to maintain session affinity. Session affinity provides improved performance, improved user experience, and makes WebSEAL configuration simpler.

Parent topic: Distributed session cache overview

The distributed session cacheThe distributed session cacheThe distributed session cache is an independent service that acts as a centralized session repository for a clustered WebSEAL server environment. Servers in the cluster can use the distributed session cache to provide failover for user sessions.distributed session cachebenefitssession sources - supportedThe primary master of the cluster acts as the distributed session cache server. You can use a stand-alone cluster with only a single node for the distributed session cache. However, you can specify up to three supplementary masters to ensure high availability of the distributed session cache. These supplementary masters maintain slave copies of the distributed session cache for failover purposes. For more information about how to configure a cluster of IBM Security Access Manager appliances, see the "Cluster Support" topics in the Administering Web Reverse Proxy topics in the Knowledge Center.The distributed session cache server can manage sessions from any of the following sources:Appliance-based WebSEAL instances that are members of the same cluster as the distributed session cache server.Appliance-based WebSEAL instances that are on appliances that are not in the same cluster as the distributed session cache server. However, it is best to include the appliance in the same cluster as the distributed session cache server where possible.Software-based WebSEAL, version 7.0, instances.The distributed session cache provides the following benefits:Manages sessions across clustered Web security servers.Resolves session inactivity and session lifetime timeout consistency issues in a replicated Web security server environment.Provides secure failover and single sign-on among replicated Web security servers.Provides controls over the maximum number of allowed concurrent sessions per user.Provides single sign-on capabilities and single sign-off among other websites in the same DNS domain.Provides performance and high availability protection to the server environment in the event of hardware or software failure.Allows administrators to view and modify sessions on the WebSEAL server.Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

The distributed session cache

The distributed session cache is an independent service that acts as a centralized session repository for a clustered WebSEAL server environment. Servers in the cluster can use the distributed session cache to provide failover for user sessions.

The primary master of the cluster acts as the distributed session cache server. You can use a stand-alone cluster with only a single node for the distributed session cache. However, you can specify up to three supplementary masters to ensure high availability of the distributed session cache. These supplementary masters maintain slave copies of the distributed session cache for failover purposes.

For more information about how to configure a cluster of IBM Security Access Manager appliances, see the "Cluster Support" topics in the Administering Web Reverse Proxy topics in the Knowledge Center.

The distributed session cache server can manage sessions from any of the following sources:

Appliance-based WebSEAL instances that are members of the same cluster as the distributed session cache server.

Appliance-based WebSEAL instances that are on appliances that are not in the same cluster as the distributed session cache server. However, it is best to include the appliance in the same cluster as the distributed session cache server where possible.

Software-based WebSEAL, version 7.0, instances.

The distributed session cache provides the following benefits:

Manages sessions across clustered Web security servers.

Resolves session inactivity and session lifetime timeout consistency issues in a replicated Web security server environment.

Provides secure failover and single sign-on among replicated Web security servers.

Provides controls over the maximum number of allowed concurrent sessions per user.

Provides single sign-on capabilities and single sign-off among other websites in the same DNS domain.

Provides performance and high availability protection to the server environment in the event of hardware or software failure.

Allows administrators to view and modify sessions on the WebSEAL server.

Parent topic: Distributed session cache overview

Failover for the distributed session cacheFailover for the distributed session cacheThe distributed session cache server is configured in a clustered environment. You can configure up to four master nodes in the cluster to ensure high availability for the distributed session cache.failoverdistributed session cachedistributed session cachefailureerror messagefailoverThe primary master of the cluster provides the distributed session cache service to the cluster. If the distributed session cache on the primary master fails, an error is printed in the WebSEAL log. For example:2013-12-10-12:44:25.525+10:00I----- 0x38CF0B24 webseald ERROR wwa soap AMWSOAPHandle.cpp 261 0x7f8cac0ac720 -- DPWWA2852E An error occurred when attempting to communicate with the SOAP server URL http://10.150.21.1:2028/DSess/services/DSess: HTTPTransportException:Client failed to open Failed to open connection to server: --hostname='10.150.21.1' -- service='2028' -- Error Message='Connection refused' Error Code='111' -- (error code: 12/0xc).If there are no supplementary masters specified, the distributed session cache service is unavailable until the primary master is restored. However, if there is a secondary master configured, the distributed session cache fails over to the secondary master. You can also configure tertiary and quaternary masters to provide extra failover for the distributed session cache. For more information, search for "Failover in a cluster" in the Administering Web Reverse Proxy topics in the Knowledge Center.Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Failover for the distributed session cache

The distributed session cache server is configured in a clustered environment. You can configure up to four master nodes in the cluster to ensure high availability for the distributed session cache.

The primary master of the cluster provides the distributed session cache service to the cluster. If the distributed session cache on the primary master fails, an error is printed in the WebSEAL log.

For example:

2013-12-10-12:44:25.525+10:00I----- 0x38CF0B24 webseald ERROR wwa soap
AMWSOAPHandle.cpp 261 0x7f8cac0ac720 --
DPWWA2852E   An error occurred when attempting to communicate
with the SOAP server URL http://10.150.21.1:2028/DSess/services/DSess:
HTTPTransportException:Client failed to open Failed to open connection to server:
--hostname='10.150.21.1' -- service='2028' --
Error Message='Connection refused'  Error Code='111' --  (error code: 12/0xc).

If there are no supplementary masters specified, the distributed session cache service is unavailable until the primary master is restored. However, if there is a secondary master configured, the distributed session cache fails over to the secondary master. You can also configure tertiary and quaternary masters to provide extra failover for the distributed session cache. For more information, search for "Failover in a cluster" in the Administering Web Reverse Proxy topics in the Knowledge Center.

Parent topic: Distributed session cache overview

Replica setsReplica setsA cluster of Security Access Manager servers that use the distributed session cache to share sessions is called a replica set. distributed session cacheserver clustersreplica setsServers in the replica set can use the distributed session cache to provide failover of user sessions. A client session created by one member of a replica set can be used unmodified by another. Certain policies, including maximum concurrent session policy and policies that affect credential change, can apply consistently across a replica set. From the user and administrator points of view, sessions exist as a single entity across a replica set. Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Replica sets

A cluster of Security Access Manager servers that use the distributed session cache to share sessions is called a replica set.

Servers in the replica set can use the distributed session cache to provide failover of user sessions. A client session created by one member of a replica set can be used unmodified by another.

Certain policies, including maximum concurrent session policy and policies that affect credential change, can apply consistently across a replica set. From the user and administrator points of view, sessions exist as a single entity across a replica set.

Parent topic: Distributed session cache overview

Distributed session cache process flowdistributed session cache process flowIn a distributed session cache environment, the client browser sends requests to the WebSEAL server cluster, which interacts with the distributed session cache for session management.distributed session cacheprocess flowprocess flowdistributed session cacheThe following diagram shows the basic process flow for session management in an environment where WebSEAL is configured to use the distributed session cache. The example contains the following conditions: WebSEAL 1 and WebSEAL 2 are configured with replica virtual hosts (vhostA).The replica virtual hosts belong to a replica set. Distributed session cache process flowDistributed session cache process flow A user makes a request for a protected object located in the Web space of vhostA. WebSEAL A intercepts the request and creates a local cache entry for the user. WebSEAL A prompts the user to log in.The user provides authentication data to WebSEAL. WebSEAL updates the local session cache entry with the client's credential. Maintaining a local session cache improves the performance of that specific WebSEAL server during future requests for resources.WebSEAL A notifies the distributed session cache of the new session and the associated credential information. The distributed session cache maintains this information in its own database.WebSEAL A sends a session cookie to the user's browser.An additional request for a resource on vhostA by the same user, using the same session cookie, fails over to another server in the replica set (WebSEAL B).Using the session cookie, WebSEAL B consults the distributed session cache to determine whether the user has already authenticated. The distributed session cache replies with the user's cached credential. WebSEAL B uses the credential to trust the user and allows the request for the resource to proceed. The user is not prompted to login again.Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Distributed session cache process flow

In a distributed session cache environment, the client browser sends requests to the WebSEAL server cluster, which interacts with the distributed session cache for session management.

The following diagram shows the basic process flow for session management in an environment where WebSEAL is configured to use the distributed session cache. The example contains the following conditions:

WebSEAL 1 and WebSEAL 2 are configured with replica virtual hosts (vhostA).

The replica virtual hosts belong to a replica set.

Figure 24. Distributed session cache process flow

A user makes a request for a protected object located in the Web space of vhostA. WebSEAL A intercepts the request and creates a local cache entry for the user. WebSEAL A prompts the user to log in.

The user provides authentication data to WebSEAL. WebSEAL updates the local session cache entry with the client's credential.

Maintaining a local session cache improves the performance of that specific WebSEAL server during future requests for resources.

WebSEAL A notifies the distributed session cache of the new session and the associated credential information. The distributed session cache maintains this information in its own database.

WebSEAL A sends a session cookie to the user's browser.

An additional request for a resource on vhostA by the same user, using the same session cookie, fails over to another server in the replica set (WebSEAL B).

Using the session cookie, WebSEAL B consults the distributed session cache to determine whether the user has already authenticated. The distributed session cache replies with the user's cached credential.

WebSEAL B uses the credential to trust the user and allows the request for the resource to proceed. The user is not prompted to login again.

Parent topic: Distributed session cache overview

Sharing sessions across multiple DNS domainsSharing sessions across multiple DNS domainsWhen operating in a multi-domain environment, you must use a different mechanism to communicate the session identifier to the WebSEAL servers in the different DNS domains.session sharingacross multiple DNS domainsdistributed session cachesharing sessionsThe index into the distributed session cache is stored and transmitted in a domain cookie. Clients do not present this cookie to servers that reside outside of the source DNS domain. Extensions to the external authentication interface (EAI) allow an EAI application to supply WebSEAL with a session identifier instead of authentication data. For more details, see External authentication interface HTTP header reference. This session identifier corresponds to the session index into the distributed session cache. The mechanism by which the EAI application receives the session identifier depends on the implementation of the EAI application. For example, you can configure: Tivoli Federated Identity Manager to supply the identifier as a part of a SAML assertion.An identity provider to add the session identifier into a SAML assertion. The service provider then retrieves the session identifier from the SAML assertion and passes the information back to WebSEAL.For this mechanism to work, designate a single WebSEAL server or multiple load-balanced Web servers in the same DNS domain as the primary authentication server. This WebSEAL server establishes the authenticated session. It also hosts the identity provider, which communicates the session identifier back to the EAI application. To make the session identifier available to the identity provider application, see User session management for back-end servers.The following diagram shows the basic process flow for session management in a multi-domain environment where WebSEAL is configured to use the distributed session cache. The example is based on the following conditions:WebSEAL A is configured as the primary authentication server.WebSEAL A & B reside in different DNS domains.No session is established in either WebSEAL server.A user makes a request for a protected object located in the Web space of WebSEAL B, which:Intercepts the request.Creates a local cache entry for the user.Sends a redirect back to the identity provider application that is behind the primary authentication server. You can either set this redirect as a meta-header within the login form or specify it using the local-response-redirect functionality.The identity provider is a protected application that requires authentication. WebSEAL A:Intercepts the request. Creates a local cache entry for the user that contains the requested URL for the identity provider.Prompts the user to log in.The user provides authentication data to WebSEAL, which performs a local authentication and updates the local session cache entry with the credential of the client.WebSEAL A notifies the distributed session cache of the new session and the associated credential information. The distributed session cache maintains this information in its database.WebSEAL A sends:A session cookie to the browser of the user.A redirect to the cached URL for the identity provider.The identity provider:Extracts the session identifier from the HTTP request headers.Sends a redirect to the EAI application junctioned behind WebSEAL B. The mechanism for passing the session identifier to the EAI application is implementation-specific.The EAI application:Locates the session identifier supplied by the identity provider.Passes the identifier back to WebSEAL B in the appropriate HTTP header.WebSEAL B retrieves the corresponding session from the distributed session cache.WebSEAL B sends:A session cookie to the browser of the user.A redirect to the original cached URL.WebSEAL B:Uses the session cookie set in step 9 to locate the appropriate local session and credential.Allows the request for the resource to proceed.Does not prompt the user to log in again.Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Sharing sessions across multiple DNS domains

When operating in a multi-domain environment, you must use a different mechanism to communicate the session identifier to the WebSEAL servers in the different DNS domains.

About this task

The index into the distributed session cache is stored and transmitted in a domain cookie. Clients do not present this cookie to servers that reside outside of the source DNS domain.

Extensions to the external authentication interface (EAI) allow an EAI application to supply WebSEAL with a session identifier instead of authentication data. For more details, see External authentication interface HTTP header reference. This session identifier corresponds to the session index into the distributed session cache. The mechanism by which the EAI application receives the session identifier depends on the implementation of the EAI application. For example, you can configure:

Tivoli® Federated Identity Manager to supply the identifier as a part of a SAML assertion.

An identity provider to add the session identifier into a SAML assertion. The service provider then retrieves the session identifier from the SAML assertion and passes the information back to WebSEAL.

For this mechanism to work, designate a single WebSEAL server or multiple load-balanced Web servers in the same DNS domain as the primary authentication server. This WebSEAL server establishes the authenticated session. It also hosts the identity provider, which communicates the session identifier back to the EAI application.

To make the session identifier available to the identity provider application, see User session management for back-end servers.

The following diagram shows the basic process flow for session management in a multi-domain environment where WebSEAL is configured to use the distributed session cache. The example is based on the following conditions:

WebSEAL A is configured as the primary authentication server.

WebSEAL A & B reside in different DNS domains.

No session is established in either WebSEAL server.

Procedure

A user makes a request for a protected object located in the Web space of WebSEAL B, which:

Intercepts the request.

Creates a local cache entry for the user.

Sends a redirect back to the identity provider application that is behind the primary authentication server. You can either set this redirect as a meta-header within the login form or specify it using the local-response-redirect functionality.

The identity provider is a protected application that requires authentication. WebSEAL A:

Intercepts the request.

Creates a local cache entry for the user that contains the requested URL for the identity provider.

Prompts the user to log in.

The user provides authentication data to WebSEAL, which performs a local authentication and updates the local session cache entry with the credential of the client.

WebSEAL A notifies the distributed session cache of the new session and the associated credential information. The distributed session cache maintains this information in its database.

WebSEAL A sends:

A session cookie to the browser of the user.

A redirect to the cached URL for the identity provider.

The identity provider:

Extracts the session identifier from the HTTP request headers.

Sends a redirect to the EAI application junctioned behind WebSEAL B. The mechanism for passing the session identifier to the EAI application is implementation-specific.

The EAI application:

Locates the session identifier supplied by the identity provider.

Passes the identifier back to WebSEAL B in the appropriate HTTP header.

WebSEAL B retrieves the corresponding session from the distributed session cache.

WebSEAL B sends:

A session cookie to the browser of the user.

A redirect to the original cached URL.

WebSEAL B:

Uses the session cookie set in step 9 to locate the appropriate local session and credential.

Allows the request for the resource to proceed.

Does not prompt the user to log in again.

Parent topic: Distributed session cache overview

Advantages of using the distributed session cache to maintain session stateAdvantages of using the distributed session cacheThe distributed session cache solution has many advantages over the failover cookies solution for maintaining session state. distributed session cacheadvantagessession statedistributed session cacheComparison of the distributed session cache solution TopicFailover cookiesDistributed session cacheSecuritySlightly less secure than the distributed session cache as identity information is stored in an encrypted cookie.Provides defense in depth with the distributed session cache located behind the DMZ. Failover between WebSEAL instancesHigher CPU usage is required for WebSEAL to decrypt the failover cookie. A new session is established, which means that you do not share session semantics such as timeout information with other WebSEAL instances. The distributed session cache shares sessions rather than using a single sign-on mechanism. Session semantics such as timeout information are shared between the various WebSEAL instances.Session policyNo concurrent session policy enforcement.No central administration of sessions.Concurrent session policy enforcement.Central management of sessions, including session termination by using the dscadmin tool.You can list the number of failed login attempts on an account since a successful login.MaintenanceRequires periodic renewal of failover cookie keys in line with corporate policy. This process is manual. The distributed session cache does not require encryption keys. CookiesThe failover cookie is larger than the distributed session cache session cookie. The failover cookie can be configured to include many attributes, which can significantly increase its size.The distributed session cache uses a basic session cookie, which is relatively small. The cookies in a distributed session cache environment are typically less than 100 bytes. LogoutIn browser scenarios, you cannot successfully log out with failover cookies turned on.You can logout from browser session when you use the distributed session cache.Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Advantages of using the distributed session cache to maintain session state

The distributed session cache solution has many advantages over the failover cookies solution for maintaining session state.

Table 57. Comparison of the distributed session cache solution .

Topic
Failover cookies
Distributed session cache

Security
Slightly less secure than the distributed session cache as identity information is stored in an encrypted cookie.
Provides defense in depth with the distributed session cache located behind the DMZ.

Failover between WebSEAL instances
Higher CPU usage is required for WebSEAL to decrypt the failover cookie. A new session is established, which means that you do not share session semantics such as timeout information with other WebSEAL instances.
The distributed session cache shares sessions rather than using a single sign-on mechanism. Session semantics such as timeout information are shared between the various WebSEAL instances.

Session policy

No concurrent session policy enforcement.

No central administration of sessions.

Concurrent session policy enforcement.

Central management of sessions, including session termination by using the dscadmin tool.

You can list the number of failed login attempts on an account since a successful login.

Maintenance
Requires periodic renewal of failover cookie keys in line with corporate policy. This process is manual.
The distributed session cache does not require encryption keys.

Cookies
The failover cookie is larger than the distributed session cache session cookie. The failover cookie can be configured to include many attributes, which can significantly increase its size.
The distributed session cache uses a basic session cookie, which is relatively small. The cookies in a distributed session cache environment are typically less than 100 bytes.

Logout
In browser scenarios, you cannot successfully log out with failover cookies turned on.
You can logout from browser session when you use the distributed session cache.

Parent topic: Distributed session cache overview

Migrating from a Session Management Server (SMS) environmentMigrating from an SMS environmentThe distributed session cache replaces the session management server (SMS) solution that was available in earlier releases of IBM Security Access Manager. You can configure IBM Security Access Manager, version 7.0 servers, which previously used the SMS, to use a distributed session cache server in your environment.SMS to distributed session cachemigrationmigrationdistributed session cachesupported versionsThe IBM Security Access Manager, version 8.0, distributed session cache can interoperate with IBM Security Access Manager, version 7.0 servers. You can introduce anIBM Security Access Manager version 8.0 appliance to provide a distributed session cache that manages sessions for WebSEAL version 7.0 and version 8.0 servers.The following component versions are supported:Policy ServerIBM Security Access Manager versions 7.0 and 8.0.WebSEALIBM Security Access Manager versions 7.0 and 8.0. The WebSEAL servers can be appliance-based or software-based. Distributed Session Cache ServerIBM Security Access Manager version 8.0 appliance.To configure an IBM Security Access Manager, version 7.0, WebSEAL server to use the distributed session cache, complete the steps that are described in Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache..You can use the local management interface to configure IBM Security Access Manager, version 8.0 appliances in the cluster to use the distributed session cache. For more information, see Configuring a WebSEAL instance on a cluster member to use the distributed session cacheFor nodes that are in the distributed session cache server cluster, use the local management interface (LMI) to configure WebSEAL to use the distributed session cache..Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments.

Migrating from a Session Management Server (SMS) environment

The distributed session cache replaces the session management server (SMS) solution that was available in earlier releases of IBM Security Access Manager. You can configure IBM Security Access Manager, version 7.0 servers, which previously used the SMS, to use a distributed session cache server in your environment.

The IBM Security Access Manager, version 8.0, distributed session cache can interoperate with IBM Security Access Manager, version 7.0 servers. You can introduce anIBM Security Access Manager version 8.0 appliance to provide a distributed session cache that manages sessions for WebSEAL version 7.0 and version 8.0 servers.

The following component versions are supported:

Policy Server

IBM Security Access Manager versions 7.0 and 8.0.

WebSEAL

IBM Security Access Manager versions 7.0 and 8.0. The WebSEAL servers can be appliance-based or software-based.

Distributed Session Cache Server

IBM Security Access Manager version 8.0 appliance.

To configure an IBM Security Access Manager, version 7.0, WebSEAL server to use the distributed session cache, complete the steps that are described in Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache.

Note: You can use the local management interface to configure IBM Security Access Manager, version 8.0 appliances in the cluster to use the distributed session cache. For more information, see Configuring a WebSEAL instance on a cluster member to use the distributed session cache.

Parent topic: Distributed session cache overview

Quickstart guide for WebSEAL to use the distributed session cacheQuickstart guide for WebSEAL to use the distributed session cacheThe process for configuring WebSEAL to use the distributed session cache depends on whether WebSEAL is running on an appliance in the same cluster as the distributed session cache server. WebSEALdistributed session cacheWebSEALdistributed session cachedistributed session cacheWebSEALQuickstart guideWebSEAL instance that is internal to the distributed session cache server clusterIf WebSEAL is on an appliance in the same cluster, there is a configuration option in the local management interface (LMI) to configure WebSEAL to use the distributed session cache. For more information, see Configuring a WebSEAL instance on a cluster member to use the distributed session cacheFor nodes that are in the distributed session cache server cluster, use the local management interface (LMI) to configure WebSEAL to use the distributed session cache..WebSEAL instance that is external to the distributed session cache server clusterFor a WebSEAL instance that is not on an appliance in the distributed session cache server cluster, you can manually configure WebSEAL to use the distributed session cache. This manual configuration is required for WebSEAL instances that fall into the following two categories: Software-based WebSEAL instances, such as ISAM 7.0 software installations.Appliance-based WebSEAL instances that are not in the same cluster as the distributed session cache server.For more information, see Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache..Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution. describes the distributed session cache manual configuration options in greater detail.Distributed session cacheConfiguring a WebSEAL instance on a cluster member to use the distributed session cacheFor nodes that are in the distributed session cache server cluster, use the local management interface (LMI) to configure WebSEAL to use the distributed session cache.Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Quickstart guide for WebSEAL to use the distributed session cache

The process for configuring WebSEAL to use the distributed session cache depends on whether WebSEAL is running on an appliance in the same cluster as the distributed session cache server.

WebSEAL instance that is internal to the distributed session cache server cluster

If WebSEAL is on an appliance in the same cluster, there is a configuration option in the local management interface (LMI) to configure WebSEAL to use the distributed session cache. For more information, see Configuring a WebSEAL instance on a cluster member to use the distributed session cache.

WebSEAL instance that is external to the distributed session cache server cluster

For a WebSEAL instance that is not on an appliance in the distributed session cache server cluster, you can manually configure WebSEAL to use the distributed session cache. This manual configuration is required for WebSEAL instances that fall into the following two categories:

Software-based WebSEAL instances, such as ISAM 7.0 software installations.

Appliance-based WebSEAL instances that are not in the same cluster as the distributed session cache server.

For more information, see Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache.

Advanced configuration for the distributed session cache describes the distributed session cache manual configuration options in greater detail.

Configuring a WebSEAL instance on a cluster member to use the distributed session cache
For nodes that are in the distributed session cache server cluster, use the local management interface (LMI) to configure WebSEAL to use the distributed session cache.

Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache
You can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Parent topic: Distributed session cache

Configuring a WebSEAL instance on a cluster member to use the distributed session cacheConfiguring a WebSEAL instance on a cluster member to use the distributed session cacheFor nodes that are in the distributed session cache server cluster, use the local management interface (LMI) to configure WebSEAL to use the distributed session cache.distributed session cacheconfigure WebSEALinternal cluster memberWebSEALconfigurationdistributed session cache For an appliance-based WebSEAL instance that is internal to the distributed session cache server cluster, the configuration occurs automatically when you enable the distributed session cache in the LMI.In the LMI, select Secure Web Settings > Manage > Reverse Proxy. Select the WebSEAL instance that you want to use the distributed session cache. Click Edit.Select the Session tab.Select Enable Distributed Session Cache.Save and deploy the configuration changes. Restart the WebSEAL instance.WebSEAL is automatically configured to use the distributed session cache. WebSEAL uses SSL to communicate with the distributed session cache. A message is printed in the WebSEAL log regarding the synchronization between the local session cache and the distributed session cache. No further manual configuration is required.You can use the local management interface to view and manage the servers in the replica set. Go to Secure Web Settings > Manage > Distributed Session Cache.The dscadmin tool is also available for session management. For more information about this tool, search for "dscadmin command" in the Configuring Web Reverse Proxy topics in the Knowledge Center.By default, all WebSEAL instances are added to the default replica set. If you want to group the WebSEAL instances into separate replica sets, change the name of the replica set that is associated with each instance in the WebSEAL configuration file. For more information about this configuration, see Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. .You can configure the maximum concurrent sessions policy, as described in Set the maximum concurrent sessions policySet the maximum concurrent sessions policy for your environment.. By default, there is no concurrent limit.You can use the steps that are described in Test the configurationWhen the configuration for the distributed session cache environment is complete, you can test the configuration. to verify that the environment is working correctly.Quickstart guide for WebSEAL to use the distributed session cacheThe process for configuring WebSEAL to use the distributed session cache depends on whether WebSEAL is running on an appliance in the same cluster as the distributed session cache server. Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Configuring a WebSEAL instance on a cluster member to use the distributed session cache

For nodes that are in the distributed session cache server cluster, use the local management interface (LMI) to configure WebSEAL to use the distributed session cache.

About this task

For an appliance-based WebSEAL instance that is internal to the distributed session cache server cluster, the configuration occurs automatically when you enable the distributed session cache in the LMI.

Procedure

In the LMI, select Secure Web Settings > Manage > Reverse Proxy.

Select the WebSEAL instance that you want to use the distributed session cache.

Click Edit.

Select the Session tab.

Select Enable Distributed Session Cache.

Save and deploy the configuration changes.

Restart the WebSEAL instance.

Results

WebSEAL is automatically configured to use the distributed session cache. WebSEAL uses SSL to communicate with the distributed session cache.

A message is printed in the WebSEAL log regarding the synchronization between the local session cache and the distributed session cache. No further manual configuration is required.

What to do next

You can use the local management interface to view and manage the servers in the replica set. Go to Secure Web Settings > Manage > Distributed Session Cache.

The dscadmin tool is also available for session management. For more information about this tool, search for "dscadmin command" in the Configuring Web Reverse Proxy topics in the Knowledge Center.

By default, all WebSEAL instances are added to the default replica set. If you want to group the WebSEAL instances into separate replica sets, change the name of the replica set that is associated with each instance in the WebSEAL configuration file. For more information about this configuration, see Replica set configuration.

You can configure the maximum concurrent sessions policy, as described in Set the maximum concurrent sessions policy. By default, there is no concurrent limit.

You can use the steps that are described in Test the configuration to verify that the environment is working correctly.

Parent topic: Quickstart guide for WebSEAL to use the distributed session cache

Related reference:

Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheConfiguration for WebSEAL instances that are external to the cluster to use the distributed session cacheConfiguration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.distributed session cacheconfigure WebSEALexternal to the clusterWebSEALconfigurationdistributed session cachePrerequisitesFamiliarize yourself with the concepts that relate to the distributed session cache. For more information about the distributed session cache, see Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments..See Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution. for information about advanced configuration for your environment.This configuration summary assumes the following requirements for the WebSEAL environment: Forms authentication to WebSEAL. Forms authentication is not required for the environment with the distributed session cache. However, basic authentication (the default WebSEAL authentication method) is not suitable for use with session displacement.Mutual authentication (SSL) between WebSEAL and the distributed session cache. The maximum concurrent sessions policy is enforced.Manual configuration stepsThe following manual configuration steps are required for WebSEAL instances that are running on appliances, which are external to the distributed session cache server cluster. These external appliances can be either software-based WebSEAL instances or appliance-based WebSEAL instances that are not in the same cluster as the distributed session cache server.Information gatheringConfiguring WebSEAL to use the distributed session cache requires that you gather information..WebSEAL configuration file settingsThe following lists of stanzas and stanza entries in the WebSEAL configuration file represent the complete set of options required for configuring WebSEAL to use the distributed session cache. .Restart the WebSEAL serverAfter updating the WebSEAL configuration for the distributed session cache, you must restart the WebSEAL server..Create junctions for virtual hostsIf you are using virtual hosts, create virtual host junctions..Set the maximum concurrent sessions policySet the maximum concurrent sessions policy for your environment..Test the configurationWhen the configuration for the distributed session cache environment is complete, you can test the configuration..Quickstart guide for WebSEAL to use the distributed session cacheThe process for configuring WebSEAL to use the distributed session cache depends on whether WebSEAL is running on an appliance in the same cluster as the distributed session cache server. Configuring a WebSEAL instance on a cluster member to use the distributed session cacheFor nodes that are in the distributed session cache server cluster, use the local management interface (LMI) to configure WebSEAL to use the distributed session cache.Information gatheringConfiguring WebSEAL to use the distributed session cache requires that you gather information.WebSEAL configuration file settingsThe following lists of stanzas and stanza entries in the WebSEAL configuration file represent the complete set of options required for configuring WebSEAL to use the distributed session cache. Restart the WebSEAL serverAfter updating the WebSEAL configuration for the distributed session cache, you must restart the WebSEAL server.Create junctions for virtual hostsIf you are using virtual hosts, create virtual host junctions.Set the maximum concurrent sessions policySet the maximum concurrent sessions policy for your environment.Test the configurationWhen the configuration for the distributed session cache environment is complete, you can test the configuration.

Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

You can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Prerequisites

Familiarize yourself with the concepts that relate to the distributed session cache. For more information about the distributed session cache, see Distributed session cache overview.

See Advanced configuration for the distributed session cache for information about advanced configuration for your environment.

This configuration summary assumes the following requirements for the WebSEAL environment:

Forms authentication to WebSEAL.

Forms authentication is not required for the environment with the distributed session cache. However, basic authentication (the default WebSEAL authentication method) is not suitable for use with session displacement.

Mutual authentication (SSL) between WebSEAL and the distributed session cache.

The maximum concurrent sessions policy is enforced.

Manual configuration steps

The following manual configuration steps are required for WebSEAL instances that are running on appliances, which are external to the distributed session cache server cluster. These external appliances can be either software-based WebSEAL instances or appliance-based WebSEAL instances that are not in the same cluster as the distributed session cache server.

Information gathering.

WebSEAL configuration file settings.

Restart the WebSEAL server.

Create junctions for virtual hosts.

Set the maximum concurrent sessions policy.

Test the configuration.

Information gathering
Configuring WebSEAL to use the distributed session cache requires that you gather information.

WebSEAL configuration file settings
The following lists of stanzas and stanza entries in the WebSEAL configuration file represent the complete set of options required for configuring WebSEAL to use the distributed session cache.

Restart the WebSEAL server
After updating the WebSEAL configuration for the distributed session cache, you must restart the WebSEAL server.

Create junctions for virtual hosts
If you are using virtual hosts, create virtual host junctions.

Set the maximum concurrent sessions policy
Set the maximum concurrent sessions policy for your environment.

Test the configuration
When the configuration for the distributed session cache environment is complete, you can test the configuration.

Parent topic: Quickstart guide for WebSEAL to use the distributed session cache

Related tasks:

Configuring a WebSEAL instance on a cluster member to use the distributed session cache

Information gatheringInformation gatheringConfiguring WebSEAL to use the distributed session cache requires that you gather information.distributed session cachegathering information for WebSEALinformationgatheringYou need the following details:The host name and port number of the distributed session cache server. A key database and stash file for SSL communication with the distributed session cache. The database must contain the SSL certificate that the distributed session cache uses. You can find this certificate in the local management interface of the distributed session cache server. Go to the cluster configuration page under Manage > System Settings > Cluster Configuration and select the Session Cache tab. There is an SSL Certificates link that you can use to access the key database for the distributed session cache and manage the certificates. Update the following entries in the WebSEAL configuration file with the key file details so that WebSEAL can access the SSL certificate for the distributed session cache: [dsess-cluster], ssl-keyfile, [dsess-cluster], ssl-keyfile-label, and [dsess-cluster], ssl-keyfile-stash. These stanza entries and values appear in the configuration file as follows: [dsess-cluster] ssl-keyfile = default-webseald.kdb ssl-keyfile-label = dsc_cert ssl-keyfile-stash = default-webseald.sthIf the [dsess-cluster] entries are not set in a software-based WebSEAL environment, WebSEAL uses the corresponding values in the [ssl] stanza. That is, the following entries in the [ssl] stanza are used if the [dsess-cluster] values are not available:[ssl] ssl-keyfile = /var/pdweb/keytab-default/default-webseald.kdb ssl-keyfile-label = dsc_cert ssl-keyfile-stash = /var/pdweb/keytab-default/default-webseald.sthConfiguration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Information gathering

Configuring WebSEAL to use the distributed session cache requires that you gather information.

You need the following details:

The host name and port number of the distributed session cache server.

A key database and stash file for SSL communication with the distributed session cache. The database must contain the SSL certificate that the distributed session cache uses.

You can find this certificate in the local management interface of the distributed session cache server. Go to the cluster configuration page under Manage > System Settings > Cluster Configuration and select the Session Cache tab. There is an SSL Certificates link that you can use to access the key database for the distributed session cache and manage the certificates.

Update the following entries in the WebSEAL configuration file with the key file details so that WebSEAL can access the SSL certificate for the distributed session cache: [dsess-cluster], ssl-keyfile, [dsess-cluster], ssl-keyfile-label, and [dsess-cluster], ssl-keyfile-stash. These stanza entries and values appear in the configuration file as follows:

[dsess-cluster]
ssl-keyfile = default-webseald.kdb
ssl-keyfile-label = dsc_cert
ssl-keyfile-stash = default-webseald.sth

Note: If the [dsess-cluster] entries are not set in a software-based WebSEAL environment, WebSEAL uses the corresponding values in the [ssl] stanza. That is, the following entries in the [ssl] stanza are used if the [dsess-cluster] values are not available:

[ssl]
ssl-keyfile = /var/pdweb/keytab-default/default-webseald.kdb
ssl-keyfile-label = dsc_cert
ssl-keyfile-stash = /var/pdweb/keytab-default/default-webseald.sth

Parent topic: Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

WebSEAL configuration file settingsWebSEAL configuration file settingsThe following lists of stanzas and stanza entries in the WebSEAL configuration file represent the complete set of options required for configuring WebSEAL to use the distributed session cache. WebSEALconfiguration distributed session cacheWhere necessary, edit the WebSEAL configuration file to set these options. Some options may be set by default, based on the original WebSEAL configuration file template.[ses sion] logout-remove-cookie = yes dsess-enabled = yes prompt-for-displacement = yes dsess-last-access-update-interval = 60 standard-junction-replica-set = replica_set_for_standard_junctions[replica-sets] replica-set = replica_set_for_standard_junctions replica-set = replica_set_for_a_virtual_host_junction ... repeat for all of the replica sets in which this WebSEAL server participates ...[dsess] dsess-sess-id-pool-size = 125 dsess-cluster-name = DSC cluster name[dsess-cluster] server = [0-9],<URL> response-by = 60 handle-pool-size = 10 handle-idle-timeout = 240 timeout = 30 Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

WebSEAL configuration file settings

The following lists of stanzas and stanza entries in the WebSEAL configuration file represent the complete set of options required for configuring WebSEAL to use the distributed session cache.

Where necessary, edit the WebSEAL configuration file to set these options. Some options may be set by default, based on the original WebSEAL configuration file template.

[ses sion]
logout-remove-cookie = yes
dsess-enabled = yes
prompt-for-displacement = yes
dsess-last-access-update-interval = 60
standard-junction-replica-set = replica_set_for_standard_junctions

[replica-sets]
replica-set = replica_set_for_standard_junctions
replica-set = replica_set_for_a_virtual_host_junction
... repeat for all of the replica sets in which
this WebSEAL server participates ...

[dsess]
dsess-sess-id-pool-size = 125
dsess-cluster-name = DSC cluster name

[dsess-cluster]
server = [0-9],<URL>
response-by = 60
handle-pool-size = 10
handle-idle-timeout = 240
timeout = 30

Parent topic: Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

Restart the WebSEAL serverRestart the WebSEAL serverAfter updating the WebSEAL configuration for the distributed session cache, you must restart the WebSEAL server.WebSEALserversrestartingrestartingWebSEAL serversRestart the WebSEAL server.Check the WebSEAL server log file for any errors or warnings that occur during the startup process. Some warning messages are normal and do not indicate a problem. For example:WebSEAL received notification that the distributed session cache for replica-set "replica-set" was cleared. All local reference to sessions are being discarded to synchronize the local session cache with the distributed session cache.If other warnings or errors occur that are cause for concern, investigate and resolve the problems.Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Restart the WebSEAL server

After updating the WebSEAL configuration for the distributed session cache, you must restart the WebSEAL server.

Procedure

Restart the WebSEAL server.

Check the WebSEAL server log file for any errors or warnings that occur during the startup process. Some warning messages are normal and do not indicate a problem. For example:

WebSEAL received notification that the distributed session cache
for replica-set "replica-set" was cleared.
All local reference to sessions are being discarded to
synchronize the local session cache with the distributed session cache.

If other warnings or errors occur that are cause for concern, investigate and resolve the problems.

Parent topic: Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

Create junctions for virtual hostsCreate junctions for virtual hostsIf you are using virtual hosts, create virtual host junctions.virtual hostscreating junctionsjunctionscreatingvirtual hostsUse the -z option to specify the name of the replica set for each virtual host junction.Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Create junctions for virtual hosts

If you are using virtual hosts, create virtual host junctions.

Procedure

Use the -z option to specify the name of the replica set for each virtual host junction.

Parent topic: Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

Set the maximum concurrent sessions policySet the maximum concurrent sessions policySet the maximum concurrent sessions policy for your environment.concurrent sessions policy The following example command sets the maximum concurrent sessions policy: pdadmin> policy set max-concurrent-web-sessions displaceConfiguration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Set the maximum concurrent sessions policy

Set the maximum concurrent sessions policy for your environment.

About this task

The following example command sets the maximum concurrent sessions policy:

pdadmin> policy set max-concurrent-web-sessions displace

Parent topic: Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

Test the configurationTest the configurationWhen the configuration for the distributed session cache environment is complete, you can test the configuration.WebSEALconfigurationtesttestingconfiguration Check whether any problems occur during the following steps. Examine any errors that are displayed in the browser or in the WebSEAL server log file to help correct the issue. Test that logging in works properly:Access the following URL: https://webseal You must be prompted to log in.Log in as a test user. You must be allowed access to the website.Verify that the maximum concurrent session policy is enforced:From another server, access the following URL: https://webseal You must be prompted to login. Log in as your test user with the correct password. You must be prompted to displace your old session.Click the Terminate existing login link. You must be allowed access to the Web site.Return to your old browser and access the following URL again: https://webseal If your browser cached the front page of the Web site, you may need to reload (refresh) the page with the Shift key held down. You must be prompted to login, because your original session was displaced.Configuration for WebSEAL instances that are external to the cluster to use the distributed session cacheYou can manually configure a WebSEAL instance that is on an appliance, which is external to the distributed session cache server cluster, to use the distributed session cache.

Test the configuration

When the configuration for the distributed session cache environment is complete, you can test the configuration.

About this task

Check whether any problems occur during the following steps. Examine any errors that are displayed in the browser or in the WebSEAL server log file to help correct the issue.

Procedure

Test that logging in works properly:

Access the following URL:

https://webseal

You must be prompted to log in.

Log in as a test user.

You must be allowed access to the website.

Verify that the maximum concurrent session policy is enforced:

From another server, access the following URL:

https://webseal

You must be prompted to login.

Log in as your test user with the correct password.

You must be prompted to displace your old session.

Click the Terminate existing login link.

You must be allowed access to the Web site.

Return to your old browser and access the following URL again:

https://webseal

If your browser cached the front page of the Web site, you may need to reload (refresh) the page with the Shift key held down.

You must be prompted to login, because your original session was displaced.

Parent topic: Configuration for WebSEAL instances that are external to the cluster to use the distributed session cache

Advanced configuration for the distributed session cacheAdvanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.session stateclustered environmentsdistributed session cacheadvanced configurationThese advanced configuration tasks are primarily for configuring WebSEAL instances that are external to the distributed session cache server cluster. However, these tasks can also be useful to fine-tune the configuration on appliances that are internal to the distributed session cache server cluster. Topic Index:Distributed session cacheDistributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Maximum concurrent sessions policySingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.

Advanced configuration for the distributed session cache

There are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.

These advanced configuration tasks are primarily for configuring WebSEAL instances that are external to the distributed session cache server cluster. However, these tasks can also be useful to fine-tune the configuration on appliances that are internal to the distributed session cache server cluster.

Topic Index:

Distributed session cache configuration for WebSEAL
There are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.

Replica set configuration
A replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another.

Adjustment of the last access time update frequency for the distributed session cache
The dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache.

Communication timeout configuration for the distributed session cache
There are two configuration entries to control the communication timeout values for the distributed session cache environment.

Performance configuration for the distributed session cache
You can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.

SSL configuration for WebSEAL and the distributed session cache
When the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.

Maximum concurrent sessions policy

Single signon in a replica set
A distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.

Parent topic: Distributed session cache

Distributed session cache configuration for WebSEALDistributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.distributed session cacheconfigure WebSEALovreviewThis section contains the following topics:Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Maximum concurrent sessions policySingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.Enabling and disabling the distributed session cache for WebSEALUse the dsess-enabled stanza entry in the [session] stanza of the WebSEAL configuration file to enable and disable use of the distributed session cache by WebSEAL.Specifying the distributed session cache cluster and locationTo configure WebSEAL to use the distributed session cache, you must specify the distributed session cache server cluster and location in the [dsess] and [dsess-cluster] stanzas.Retrieving the maximum concurrent sessions policy valueYou can use the maximum concurrent sessions policy (pdadmin policy set max-concurrent-web-sessions) to control the number of sessions each user can have at one time in a distributed session cache environment.

Distributed session cache configuration for WebSEAL

There are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.

This section contains the following topics:

Enabling and disabling the distributed session cache for WebSEAL
Use the dsess-enabled stanza entry in the [session] stanza of the WebSEAL configuration file to enable and disable use of the distributed session cache by WebSEAL.

Specifying the distributed session cache cluster and location
To configure WebSEAL to use the distributed session cache, you must specify the distributed session cache server cluster and location in the [dsess] and [dsess-cluster] stanzas.

Retrieving the maximum concurrent sessions policy value
You can use the maximum concurrent sessions policy (pdadmin policy set max-concurrent-web-sessions) to control the number of sessions each user can have at one time in a distributed session cache environment.

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Replica set configuration

Adjustment of the last access time update frequency for the distributed session cache

Communication timeout configuration for the distributed session cache

Performance configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cache

Maximum concurrent sessions policy

Single signon in a replica set

Enabling and disabling the distributed session cache for WebSEALEnabling and disabling the distributed session cache for WebSEALUse the dsess-enabled stanza entry in the [session] stanza of the WebSEAL configuration file to enable and disable use of the distributed session cache by WebSEAL.dsess-enabled stanza entrydistributed session cacheconfigurationenablingdisablingWebSEAL When the distributed session cache is enabled for a clustered WebSEAL server environment, session cookies are used to maintain distributed session state information. The [session] ssl-id-sessions stanza entry does not apply when the distributed session cache is in use.The phrase "dsess" refers to "distributed session". To enable WebSEAL to use the distributed session cache to maintain user sessions, enter a value of yes. For example:[session] dsess-enabled = yesTo disable WebSEAL from using the distributed session cache to maintain user sessions, enter a value of no (default). For example:[session] dsess-enabled = noDistributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.

Enabling and disabling the distributed session cache for WebSEAL

Use the dsess-enabled stanza entry in the [session] stanza of the WebSEAL configuration file to enable and disable use of the distributed session cache by WebSEAL.

About this task

When the distributed session cache is enabled for a clustered WebSEAL server environment, session cookies are used to maintain distributed session state information. The [session] ssl-id-sessions stanza entry does not apply when the distributed session cache is in use.

Note: The phrase "dsess" refers to "distributed session".

Procedure

To enable WebSEAL to use the distributed session cache to maintain user sessions, enter a value of yes. For example:

[session]
dsess-enabled = yes

To disable WebSEAL from using the distributed session cache to maintain user sessions, enter a value of no (default). For example:

[session]
dsess-enabled = no

Parent topic: Distributed session cache configuration for WebSEAL

Specifying the distributed session cache cluster and locationSpecifying the distributed session cache cluster and locationTo configure WebSEAL to use the distributed session cache, you must specify the distributed session cache server cluster and location in the [dsess] and [dsess-cluster] stanzas.server stanza entrydsess-cluster stanzadistributed session cacheconfigurationspecifying clusterspecifying cache locationlocationGather the following information about the cluster that contains the distributed session cache server:The IP address of the primary master.The IP addresses of the supplementary masters, including the secondary, tertiary, and quaternary masters (if applicable). The port for the distributed session cache.Use the LMI of the primary master to view the General and Session Cache tabs of Cluster Configuration page to obtain these details. For more information about the cluster configuration fields, search for "Managing cluster configuration" in the Administering Web Reverse Proxy topics in the Knowledge Center.Configuration entries for using the distributed session cache are located in the [dsess] and [dsess-cluster] stanzas of the WebSEAL configuration file.To specify the location of the distributed session cache, define a cluster name in the dsess-cluster-name entry of the [dsess] stanza. For example:[dsess] dsess-cluster-name = dsess You can assign any name to this cluster. This value is not set as part of the cluster configuration process. Next, define the details for the cluster in a corresponding [dsess-cluster:<cluster-name>] stanza. Use the server entry to specify the location of the distributed session cache server in the following format: https://<IP_Address>:<Port>/DSess/services/DSess. Where: <IP_Address>The IP address of the distributed session cache server. For example, 10.150.21.80.<Port>The port for the distributed session cache. For example, 2126.The default parameters and values to define a cluster of distributed session cache servers are provided in the [dsess-cluster] stanza. For architectures where more than one distributed session cache is installed in a failover configuration, create multiple instances of this configuration entry. You can specify multiple server entries for failover purposes. The complete set of these server entries defines the membership of a distributed session cache cluster. You must specify a priority level for each distributed session cache server by including a number, 1-9, before the URL. This digit represents the priority of the server in the cluster (9 being the highest, 0 being lowest). You must assign the highest priority to the primary master, the next highest priority to the secondary master, and the following priorities to the tertiary and quaternary masters if present.For example:[dsess-cluster:dsess] server = 9,https://<primary_master_IP_address>:<port>/DSess/services/DSess server = 8,https://<secondary_master_IP_address>:<port>/DSess/services/DSess server = 7,https://<tertiary_master_IP_address>:<port>/DSess/services/DSess server = 6,https://<quaternary_master_IP_address>:<port>/DSess/services/DSessWhen the server entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. See SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates..Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.

Specifying the distributed session cache cluster and location

To configure WebSEAL to use the distributed session cache, you must specify the distributed session cache server cluster and location in the [dsess] and [dsess-cluster] stanzas.

Before you begin

Gather the following information about the cluster that contains the distributed session cache server:

The IP address of the primary master.

The IP addresses of the supplementary masters, including the secondary, tertiary, and quaternary masters (if applicable).

The port for the distributed session cache.

Use the LMI of the primary master to view the General and Session Cache tabs of Cluster Configuration page to obtain these details. For more information about the cluster configuration fields, search for "Managing cluster configuration" in the Administering Web Reverse Proxy topics in the Knowledge Center.

About this task

Configuration entries for using the distributed session cache are located in the [dsess] and [dsess-cluster] stanzas of the WebSEAL configuration file.

Procedure

To specify the location of the distributed session cache, define a cluster name in the dsess-cluster-name entry of the [dsess] stanza. For example:

[dsess]
dsess-cluster-name = dsess

Note: You can assign any name to this cluster. This value is not set as part of the cluster configuration process.

Next, define the details for the cluster in a corresponding [dsess-cluster:<cluster-name>] stanza. Use the server entry to specify the location of the distributed session cache server in the following format: https://<IP_Address>:<Port>/DSess/services/DSess.

Where:

<IP_Address>

The IP address of the distributed session cache server. For example, 10.150.21.80.

<Port>

The port for the distributed session cache. For example, 2126.

Note: The default parameters and values to define a cluster of distributed session cache servers are provided in the [dsess-cluster] stanza.

For architectures where more than one distributed session cache is installed in a failover configuration, create multiple instances of this configuration entry. You can specify multiple server entries for failover purposes. The complete set of these server entries defines the membership of a distributed session cache cluster.

You must specify a priority level for each distributed session cache server by including a number, 1-9, before the URL. This digit represents the priority of the server in the cluster (9 being the highest, 0 being lowest). You must assign the highest priority to the primary master, the next highest priority to the secondary master, and the following priorities to the tertiary and quaternary masters if present.

For example:

[dsess-cluster:dsess]
server = 9,https://<primary_master_IP_address>:<port>/DSess/services/DSess
server = 8,https://<secondary_master_IP_address>:<port>/DSess/services/DSess
server = 7,https://<tertiary_master_IP_address>:<port>/DSess/services/DSess
server = 6,https://<quaternary_master_IP_address>:<port>/DSess/services/DSess

When the server entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. See SSL configuration for WebSEAL and the distributed session cache.

Parent topic: Distributed session cache configuration for WebSEAL

Retrieving the maximum concurrent sessions policy valueRetrieving the maximum concurrent sessions policy valueYou can use the maximum concurrent sessions policy (pdadmin policy set max-concurrent-web-sessions) to control the number of sessions each user can have at one time in a distributed session cache environment. cred-attribute-entitlement-services stanza entryentitlements serviceazn_ent_registry_svcamwcredpolsvcamwcredpolsvc entitlements serviceazn_ent_registry_svc entitlements serviceenforce-max-sessions-policy stanza entry By default, this policy is enabled: [session] enforce-max-sessions-policy = yes As the administrator, you can apply this policy to a specific user or apply the policy globally to all users registered in this secure domain. The policy is stored in the Security Access Manager user registry. To be enforced by the authentication process in a distributed session cache environment, the policy must be retrieved from the registry and stored as an extended attribute in each user's credential. Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.

Retrieving the maximum concurrent sessions policy value

You can use the maximum concurrent sessions policy (pdadmin policy set max-concurrent-web-sessions) to control the number of sessions each user can have at one time in a distributed session cache environment.

About this task

By default, this policy is enabled:

[session]
enforce-max-sessions-policy = yes

As the administrator, you can apply this policy to a specific user or apply the policy globally to all users registered in this secure domain. The policy is stored in the Security Access Manager user registry. To be enforced by the authentication process in a distributed session cache environment, the policy must be retrieved from the registry and stored as an extended attribute in each user's credential.

Parent topic: Distributed session cache configuration for WebSEAL

Replica set configurationReplica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. distributed session cachereplica set configurationreplicasconfigurationsetsYou must specify the name of each replica set used in your server environment. By convention, set the replica set names to match the DNS name (fully-qualified host name) used by a website. For example, if the website DNS name is www.example.com, set the replica set name for the website to www.example.com.You must specify each replica set name in the configuration file of each WebSEAL instance that participates in those replica sets. Additionally, you must assign each junctioned or virtual host to the appropriate replica set. There are different procedures for assigning standard junctions and virtual hosts to a replica set. See: Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Maximum concurrent sessions policySingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.Configuring WebSEAL to participate in multiple replica setsEach replica set that WebSEAL participates in must be listed in the [replica-sets] stanza of the WebSEAL configuration file.Assigning standard junctions to a replica setYou must configure the standard junction replica set for the distributed session cache.Virtual hosts assigned to a replica setIn contrast to standard junctions, virtual hosts can be individually assigned to different replica sets by using the -z option of the pdadmin server task virtualhost create command.

Replica set configuration

A replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another.

You must specify the name of each replica set used in your server environment. By convention, set the replica set names to match the DNS name (fully-qualified host name) used by a website. For example, if the website DNS name is www.example.com, set the replica set name for the website to www.example.com.

You must specify each replica set name in the configuration file of each WebSEAL instance that participates in those replica sets. Additionally, you must assign each junctioned or virtual host to the appropriate replica set. There are different procedures for assigning standard junctions and virtual hosts to a replica set. See:

Configuring WebSEAL to participate in multiple replica sets
Each replica set that WebSEAL participates in must be listed in the [replica-sets] stanza of the WebSEAL configuration file.

Assigning standard junctions to a replica set
You must configure the standard junction replica set for the distributed session cache.

Virtual hosts assigned to a replica set
In contrast to standard junctions, virtual hosts can be individually assigned to different replica sets by using the -z option of the pdadmin server task virtualhost create command.

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Distributed session cache configuration for WebSEAL

Adjustment of the last access time update frequency for the distributed session cache

Communication timeout configuration for the distributed session cache

Performance configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cache

Maximum concurrent sessions policy

Single signon in a replica set

Configuring WebSEAL to participate in multiple replica setsConfiguring WebSEAL to participate in multiple replica setsConfiguring WebSEAL to participate in multiple replica sets in IBM Security Access Manager for WebEach replica set that WebSEAL participates in must be listed in the [replica-sets] stanza of the WebSEAL configuration file.WebSEALconfigurationmultiple replica setsmultiple replica setsIf WebSEAL participates in replica sets named vhostA.example.com, vhostB.example.com, and www.example.com, the stanza is configured as follows:[replica-sets] replica-set = vhostA.example.com replica-set = vhostB.example.com replica-set = www.example.comReplica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another.

Configuring WebSEAL to participate in multiple replica sets

Each replica set that WebSEAL participates in must be listed in the [replica-sets] stanza of the WebSEAL configuration file.

Example

If WebSEAL participates in replica sets named vhostA.example.com, vhostB.example.com, and www.example.com, the stanza is configured as follows:

[replica-sets]
replica-set = vhostA.example.com
replica-set = vhostB.example.com
replica-set = www.example.com

Parent topic: Replica set configuration

Assigning standard junctions to a replica setAssigning standard junctions to a replica setYou must configure the standard junction replica set for the distributed session cache.replica-sets stanza entrystandard-junction-replica-set stanza entrydistributed session cacheassign standard junctions to a replica setjunctionsreplica set assignmentstandard junctions By design, all standard junctions for a WebSEAL instance are assigned to one replica set, as specified by the standard-junction-replica-set stanza entry in the [session] stanza for the WebSEAL configuration file.To use the distributed session cache, the standard-junction-replica-set stanza entry value must also be listed in the [replica-sets] stanza. If the standard-junction-replica-set value is not present in the [replica-sets] stanza, WebSEAL does not start. [session] standard-junction-replica-set = replica-set-name [replica-sets] replica-set = replica-set-name [session] standard-junction-replica-set = www.example.com [replica-sets] replica-set = www.example.comReplica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another.

Assigning standard junctions to a replica set

You must configure the standard junction replica set for the distributed session cache.

About this task

By design, all standard junctions for a WebSEAL instance are assigned to one replica set, as specified by the standard-junction-replica-set stanza entry in the [session] stanza for the WebSEAL configuration file.

To use the distributed session cache, the standard-junction-replica-set stanza entry value must also be listed in the [replica-sets] stanza. If the standard-junction-replica-set value is not present in the [replica-sets] stanza, WebSEAL does not start.

[session]
standard-junction-replica-set = replica-set-name

[replica-sets]
replica-set = replica-set-name

Example

[session]
standard-junction-replica-set = www.example.com

[replica-sets]
replica-set = www.example.com

Parent topic: Replica set configuration

Virtual hosts assigned to a replica setVirtual hosts assigned to a replica setIn contrast to standard junctions, virtual hosts can be individually assigned to different replica sets by using the -z option of the pdadmin server task virtualhost create command.distributed session cacheassigning virtual hosts to a replica setjunctionsreplica set assignmentvirtual host junctionsWhen the distributed session cache is in operation, the -z option specifies the replica set that sessions on the virtual host junction are managed under. If WebSEAL is configured to use the distributed session cache, then the replica set for a virtual host junction can be specified with the -z option. Different virtual host junctions must be assigned to different replica sets. If the -z option is not used, then WebSEAL uses the virtual host name of the junction as the name of the replica set. Additionally, the name of the replica set used by this virtual host must be defined by the replica-set stanza entry in the [replica-sets] stanza of the configuration file for the WebSEAL instance:[replica-sets] replica-set = replica-set-nameExample conditions:Virtual host type: TCPHost name for the machine where the virtual host resides: abc.example.comVirtual host name: vh1.example.comVirtual host belongs to this replica set: vh1.example.comVirtual host junction label: vhost-vh1-httpExample virtual host create command (entered as one line):pdadmin> server task default-webseald-webseal.example.com virtualhost create -t tcp -h abc.example.com -v vh1.example.com -z vh1.example.com vhost-vh1-httpExample WebSEAL configuration for replica sets:[replica-sets] replica-set = vh1.example.comReplica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another.

Virtual hosts assigned to a replica set

In contrast to standard junctions, virtual hosts can be individually assigned to different replica sets by using the -z option of the pdadmin server task virtualhost create command.

When the distributed session cache is in operation, the -z option specifies the replica set that sessions on the virtual host junction are managed under. If WebSEAL is configured to use the distributed session cache, then the replica set for a virtual host junction can be specified with the -z option. Different virtual host junctions must be assigned to different replica sets. If the -z option is not used, then WebSEAL uses the virtual host name of the junction as the name of the replica set.

Additionally, the name of the replica set used by this virtual host must be defined by the replica-set stanza entry in the [replica-sets] stanza of the configuration file for the WebSEAL instance:

[replica-sets]
replica-set = replica-set-name

Example conditions:

Virtual host type: TCP

Host name for the machine where the virtual host resides: abc.example.com

Virtual host name: vh1.example.com

Virtual host belongs to this replica set: vh1.example.com

Virtual host junction label: vhost-vh1-http

Example virtual host create command (entered as one line):

pdadmin> server task default-webseald-webseal.example.com virtualhost create
-t tcp -h abc.example.com -v vh1.example.com -z vh1.example.com vhost-vh1-http

Example WebSEAL configuration for replica sets:

[replica-sets]
replica-set = vh1.example.com

Parent topic: Replica set configuration

Adjustment of the last access time update frequency for the distributed session cacheAdjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. dsess-last-access-update-interval stanza entrydistributed session cachelast access time updateIf you are adjusting session inactivity timeouts or configuring reauthentication based on session inactivity policy (reauth-for-inactive = yes), and you are using the distributed session cache, you might need to adjust this value.Smaller values offer more accurate inactivity timeout tracking, at the expense of sending updates to the distributed session cache more frequently. Values of less than 1 second are not permitted. The default value is 60 seconds. For example:[session] dsess-last-access-update-interval = 60As an example, consider the following configuration:[session] inactive-timeout = 600 dsess-last-access-update-interval = 60With these configuration values, a user's session may be flagged as "inactive" at the distributed session cache anywhere between 540 seconds and 600 seconds after the user's last access to the WebSEAL server. Small values for the dsess-last-access-update-interval parameter are not recommended and can seriously impact WebSEAL server performance.See also Reauthentication with external authentication interface.See also Cache entry inactivity timeout valueAdvanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Maximum concurrent sessions policySingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.

Adjustment of the last access time update frequency for the distributed session cache

The dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache.

If you are adjusting session inactivity timeouts or configuring reauthentication based on session inactivity policy (reauth-for-inactive = yes), and you are using the distributed session cache, you might need to adjust this value.

Smaller values offer more accurate inactivity timeout tracking, at the expense of sending updates to the distributed session cache more frequently. Values of less than 1 second are not permitted. The default value is 60 seconds. For example:

[session]
dsess-last-access-update-interval = 60

As an example, consider the following configuration:

[session]
inactive-timeout = 600
dsess-last-access-update-interval = 60

With these configuration values, a user's session may be flagged as "inactive" at the distributed session cache anywhere between 540 seconds and 600 seconds after the user's last access to the WebSEAL server.

Small values for the dsess-last-access-update-interval parameter are not recommended and can seriously impact WebSEAL server performance.

See also Reauthentication with external authentication interface.

See also Cache entry inactivity timeout value

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Distributed session cache configuration for WebSEAL

Replica set configuration

Communication timeout configuration for the distributed session cache

Performance configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cache

Maximum concurrent sessions policy

Single signon in a replica set

Communication timeout configuration for the distributed session cacheCommunication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.distributed session cachecommunication timeout configurationcommunicationtimeoutThis section contains the following topics:Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Maximum concurrent sessions policySingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.Configuring the response timeout for the distributed session cacheYou can configure the maximum amount of time that WebSEAL waits for a response from the distributed session cache.Configuring connection timeout for broadcast eventsYou can control the maximum amount of time that WebSEAL keeps its connection open and waits for a broadcast event from the distributed session cache cluster.

Communication timeout configuration for the distributed session cache

There are two configuration entries to control the communication timeout values for the distributed session cache environment.

This section contains the following topics:

Configuring the response timeout for the distributed session cache
You can configure the maximum amount of time that WebSEAL waits for a response from the distributed session cache.

Configuring connection timeout for broadcast events
You can control the maximum amount of time that WebSEAL keeps its connection open and waits for a broadcast event from the distributed session cache cluster.

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Distributed session cache configuration for WebSEAL

Replica set configuration

Adjustment of the last access time update frequency for the distributed session cache

Performance configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cache

Maximum concurrent sessions policy

Single signon in a replica set

Configuring the response timeout for the distributed session cacheConfiguring the response timeout for the distributed session cacheYou can configure the maximum amount of time that WebSEAL waits for a response from the distributed session cache.timeoutstanzadistributed session cacheresponse timeout Use the timeout stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file to specify the amount of time (in seconds) WebSEAL can wait for a response from the distributed session cache. The default value is 30 seconds. For example: [dsess-cluster] timeout = 30 If the timeout limit is reached with no response from the distributed session cache, WebSEAL assumes the distributed session cache is unavailable. When this occurs, the following actions are taken: A separate WebSEAL server thread begins attempting to contact the distributed session cache every 60 seconds to see if the distributed session cache has recovered or a backup has come online.All attempts to create or access a session on the WebSEAL server receive an HTTP "503 Service Unavailable" error page from the WebSEAL server (38b9a4b1.html). You can customize this page by creating an error page for error status "0x38b9a4b1" as described in HTML server response page modification. When the distributed session cache recovers, WebSEAL attempts to determine whether the outage was due to a temporary network outage or if the distributed session cache server was restarted. If the distributed session cache server was restarted, the local WebSEAL session cache is cleared. All sessions on the WebSEAL server are deleted. This is done so that sessions across all of the WebSEAL servers in the cluster remain synchronized. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.

Configuring the response timeout for the distributed session cache

You can configure the maximum amount of time that WebSEAL waits for a response from the distributed session cache.

About this task

Use the timeout stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file to specify the amount of time (in seconds) WebSEAL can wait for a response from the distributed session cache.

The default value is 30 seconds. For example:

[dsess-cluster]
timeout = 30

If the timeout limit is reached with no response from the distributed session cache, WebSEAL assumes the distributed session cache is unavailable. When this occurs, the following actions are taken:

A separate WebSEAL server thread begins attempting to contact the distributed session cache every 60 seconds to see if the distributed session cache has recovered or a backup has come online.

All attempts to create or access a session on the WebSEAL server receive an HTTP "503 Service Unavailable" error page from the WebSEAL server (38b9a4b1.html). You can customize this page by creating an error page for error status "0x38b9a4b1" as described in HTML server response page modification.

When the distributed session cache recovers, WebSEAL attempts to determine whether the outage was due to a temporary network outage or if the distributed session cache server was restarted. If the distributed session cache server was restarted, the local WebSEAL session cache is cleared. All sessions on the WebSEAL server are deleted. This is done so that sessions across all of the WebSEAL servers in the cluster remain synchronized.

Parent topic: Communication timeout configuration for the distributed session cache

Configuring connection timeout for broadcast eventsConfiguring connection timeout for broadcast eventsYou can control the maximum amount of time that WebSEAL keeps its connection open and waits for a broadcast event from the distributed session cache cluster.response-by stanza entrydistributed session cacheconnection timeout for broadcast events Some clustered server architectures may implement a firewall between the WebSEAL cluster members and the appliance that runs the distributed session cache. Firewalls often restrict the flow of communication to one direction. WebSEAL communicates through the firewall to send session information to the distributed session cache. To additionally receive broadcast events from the distributed session cache, WebSEAL must open another connection through the firewall. The firewall timeout policy can shut down this connection while WebSEAL is waiting for broadcast events from the distributed session cache. Use the response-by stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file to specify the length of time (in seconds) that WebSEAL keeps a connection open to the distributed session cache for receiving broadcast events for the distributed session cache cluster. When the timeout value is reached, WebSEAL recreates a new connection. [dsess-cluster] response-by = 60 To ensure the most optimal conditions for keeping this connection open, set the response-by stanza entry value to be less than the internal firewall timeout value. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.

Configuring connection timeout for broadcast events

You can control the maximum amount of time that WebSEAL keeps its connection open and waits for a broadcast event from the distributed session cache cluster.

About this task

Some clustered server architectures may implement a firewall between the WebSEAL cluster members and the appliance that runs the distributed session cache. Firewalls often restrict the flow of communication to one direction. WebSEAL communicates through the firewall to send session information to the distributed session cache.

To additionally receive broadcast events from the distributed session cache, WebSEAL must open another connection through the firewall. The firewall timeout policy can shut down this connection while WebSEAL is waiting for broadcast events from the distributed session cache.

Procedure

Use the response-by stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file to specify the length of time (in seconds) that WebSEAL keeps a connection open to the distributed session cache for receiving broadcast events for the distributed session cache cluster. When the timeout value is reached, WebSEAL recreates a new connection.

[dsess-cluster]
response-by = 60

To ensure the most optimal conditions for keeping this connection open, set the response-by stanza entry value to be less than the internal firewall timeout value.

Parent topic: Communication timeout configuration for the distributed session cache

Performance configuration for the distributed session cachePerformance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.distributed session cacheperformance configurationperformance configurationThis section contains the following topics:Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Maximum concurrent sessions policySingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.Maximum pre-allocated session IDsThe dsess-sess-id-pool-size stanza entry in the [dsess] stanza of the WebSEAL configuration file specifies the maximum number of session IDs that are pre-allocated in the session ID pool.Configuration of the handle pool sizeThe handle-pool-size stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file specifies the maximum number of idle Simple Access Object Protocol (SOAP) handles that the distributed session client maintains at any given time.

Performance configuration for the distributed session cache

You can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.

This section contains the following topics:

Maximum pre-allocated session IDs
The dsess-sess-id-pool-size stanza entry in the [dsess] stanza of the WebSEAL configuration file specifies the maximum number of session IDs that are pre-allocated in the session ID pool.

Configuration of the handle pool size
The handle-pool-size stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file specifies the maximum number of idle Simple Access Object Protocol (SOAP) handles that the distributed session client maintains at any given time.

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Distributed session cache configuration for WebSEAL

Replica set configuration

Adjustment of the last access time update frequency for the distributed session cache

Communication timeout configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cache

Maximum concurrent sessions policy

Single signon in a replica set

Maximum pre-allocated session IDsMaximum pre-allocated session IDsThe dsess-sess-id-pool-size stanza entry in the [dsess] stanza of the WebSEAL configuration file specifies the maximum number of session IDs that are pre-allocated in the session ID pool.dsess-sess-id-pool-size stanza entrydistributed session cachemaximum pre-allocated session IDsThis stanza entry is used by the server cluster. This setting is required when the distributed session cache is enabled.[dsess] dsess-sess-id-pool-size = 125Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.

Maximum pre-allocated session IDs

The dsess-sess-id-pool-size stanza entry in the [dsess] stanza of the WebSEAL configuration file specifies the maximum number of session IDs that are pre-allocated in the session ID pool.

This stanza entry is used by the server cluster. This setting is required when the distributed session cache is enabled.

[dsess]
dsess-sess-id-pool-size = 125

Parent topic: Performance configuration for the distributed session cache

Configuration of the handle pool sizeConfiguration of the handle pool sizeThe handle-pool-size stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file specifies the maximum number of idle Simple Access Object Protocol (SOAP) handles that the distributed session client maintains at any given time. handle-pool-size stanza entrydistributed session cachehandle pool sizeThese handles are used for anticipated exchanges with the distributed session cache. The default value is 10. For example:[dsess-cluster] handle-pool-size = 10The default value is adequate for most environments. The value can be increased if communication between WebSEAL and the distributed session cache is slow because all handles are in use. If you decide to modify this value, be aware that each handle reserves a file descriptor on the WebSEAL server. A large value can prevent other WebSEAL functionality that requires file descriptors from working properly.The maximum value for the handle-pool-size depends on both the platform on which the WebSEAL server is running and various WebSEAL configuration options. In general, do not increase the handle-pool-size beyond 25 handles.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.

Configuration of the handle pool size

The handle-pool-size stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file specifies the maximum number of idle Simple Access Object Protocol (SOAP) handles that the distributed session client maintains at any given time.

These handles are used for anticipated exchanges with the distributed session cache. The default value is 10.

For example:

[dsess-cluster]
handle-pool-size = 10

The default value is adequate for most environments.

The value can be increased if communication between WebSEAL and the distributed session cache is slow because all handles are in use. If you decide to modify this value, be aware that each handle reserves a file descriptor on the WebSEAL server. A large value can prevent other WebSEAL functionality that requires file descriptors from working properly.

The maximum value for the handle-pool-size depends on both the platform on which the WebSEAL server is running and various WebSEAL configuration options. In general, do not increase the handle-pool-size beyond 25 handles.

Parent topic: Performance configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cacheSSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.distributed session cacheSSLconfigurationSSL configurationdistributed session cacheConfiguring WebSEAL for SSL communication with the distributed session cache requires that you provide WebSEAL the following information:The CA certificate used to sign the distributed session cache SSL server certificate.The DN contained in the distributed session cache SSL server certificate.You can also configure additional GSKit attributes to use when initializing the SSL connection with the distributed session cache.This SSL configuration is only required for WebSEAL instances that are external to the distributed session cache server cluster. For appliances that are in the same cluster as the distributed session cache, no manual SSL configuration is required. The SSL configuration is automatically set up by the Enable Distributed Session Cache option. This section contains the following topics:Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.Maximum concurrent sessions policySingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.Configuring the WebSEAL key databaseWebSEAL stores client-side certificates and CA root certificates, used for SSL communication with the distributed session cache, in a key database file.Specifying the SSL certificate distinguished name (DN)The CA root certificate that is stored in a WebSEAL key database file validates that a certificate received from the distributed session cache is authentic. By additionally checking the DN value in the certificate, you can ensure that the server certificate received by WebSEAL from the distributed session cache is the expected certificate.GSKit configuration for distributed session cache connectionsThere are a number of GSKit attributes that you can use to control how GSKit creates SSL connections. You can configure WebSEAL to use particular GSKit attributes when it initializes SSL connections.

SSL configuration for WebSEAL and the distributed session cache

When the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.

Configuring WebSEAL for SSL communication with the distributed session cache requires that you provide WebSEAL the following information:

The CA certificate used to sign the distributed session cache SSL server certificate.

The DN contained in the distributed session cache SSL server certificate.

You can also configure additional GSKit attributes to use when initializing the SSL connection with the distributed session cache.

Note: This SSL configuration is only required for WebSEAL instances that are external to the distributed session cache server cluster. For appliances that are in the same cluster as the distributed session cache, no manual SSL configuration is required. The SSL configuration is automatically set up by the Enable Distributed Session Cache option.

This section contains the following topics:

Configuring the WebSEAL key database
WebSEAL stores client-side certificates and CA root certificates, used for SSL communication with the distributed session cache, in a key database file.

Specifying the SSL certificate distinguished name (DN)
The CA root certificate that is stored in a WebSEAL key database file validates that a certificate received from the distributed session cache is authentic. By additionally checking the DN value in the certificate, you can ensure that the server certificate received by WebSEAL from the distributed session cache is the expected certificate.

GSKit configuration for distributed session cache connections
There are a number of GSKit attributes that you can use to control how GSKit creates SSL connections. You can configure WebSEAL to use particular GSKit attributes when it initializes SSL connections.

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Distributed session cache configuration for WebSEAL

Replica set configuration

Adjustment of the last access time update frequency for the distributed session cache

Communication timeout configuration for the distributed session cache

Performance configuration for the distributed session cache

Maximum concurrent sessions policy

Single signon in a replica set

Configuring the WebSEAL key databaseConfiguring the WebSEAL key databaseWebSEAL stores client-side certificates and CA root certificates, used for SSL communication with the distributed session cache, in a key database file.ssl-keyfile stanza entryssl-keyfile-lablel stanza entrydsess-cluster stanzassl-keyfile-stash stanza entrydsess-cluster stanzadistributed session cacheWebSEAL key database configurationThe purpose of each certificate is as follows:The CA root certificate is used to validate the server certificate returned by the distributed session cache.The client-side certificate is used by WebSEAL to communicate with the distributed session cache server. To specify the key database file, use the ssl-keyfile stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file. For example:[dsess-cluster] ssl-keyfile = key-file-nameUnless Security Access Manager SSL certificates are being used for communication between WebSEAL and the distributed session cache, use a separate key file from the other WebSEAL key files as the value for ssl-keyfile.To specify the key database stash file (containing password information for access to the database file), use the ssl-keyfile-stash stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file. For example:[dsess-cluster] ssl-keyfile-stash = key-file-nameTo specify the label name for the client-side certificate, use the ssl-keyfile-label stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file. For example:[dsess-cluster] ssl-keyfile-label = label-nameSSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.

Configuring the WebSEAL key database

WebSEAL stores client-side certificates and CA root certificates, used for SSL communication with the distributed session cache, in a key database file.

About this task

The purpose of each certificate is as follows:

The CA root certificate is used to validate the server certificate returned by the distributed session cache.

The client-side certificate is used by WebSEAL to communicate with the distributed session cache server.

Procedure

To specify the key database file, use the ssl-keyfile stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file. For example:

[dsess-cluster]
ssl-keyfile = key-file-name

Unless Security Access Manager SSL certificates are being used for communication between WebSEAL and the distributed session cache, use a separate key file from the other WebSEAL key files as the value for ssl-keyfile.

To specify the key database stash file (containing password information for access to the database file), use the ssl-keyfile-stash stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file. For example:

[dsess-cluster]
ssl-keyfile-stash = key-file-name

To specify the label name for the client-side certificate, use the ssl-keyfile-label stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file. For example:

[dsess-cluster]
ssl-keyfile-label = label-name

Parent topic: SSL configuration for WebSEAL and the distributed session cache

Specifying the SSL certificate distinguished name (DN)Specifying the SSL certificate distinguished name (DN)The CA root certificate that is stored in a WebSEAL key database file validates that a certificate received from the distributed session cache is authentic. By additionally checking the DN value in the certificate, you can ensure that the server certificate received by WebSEAL from the distributed session cache is the expected certificate.ssl-valid-server-dn stanza entrydistributed session cacheSSLcertificate DN configuration To specify the accepted certificate DN values, use the ssl-valid-server-dn stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file. [dsess-cluster] ssl-valid-server-dn = DN-valueSSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Obtaining the server certificate DN valueThe ssl-valid-server-dn in the [dsess-cluster] stanza of the WebSEAL configuration file requires the value of the DN found in a valid server certificate sent by the distributed session cache during its communication with WebSEAL.

Specifying the SSL certificate distinguished name (DN)

The CA root certificate that is stored in a WebSEAL key database file validates that a certificate received from the distributed session cache is authentic. By additionally checking the DN value in the certificate, you can ensure that the server certificate received by WebSEAL from the distributed session cache is the expected certificate.

About this task

To specify the accepted certificate DN values, use the ssl-valid-server-dn stanza entry in the [dsess-cluster] stanza of the WebSEAL configuration file.

Obtaining the server certificate DN value
The ssl-valid-server-dn in the [dsess-cluster] stanza of the WebSEAL configuration file requires the value of the DN found in a valid server certificate sent by the distributed session cache during its communication with WebSEAL.

Example

[dsess-cluster]
ssl-valid-server-dn = DN-value

Parent topic: SSL configuration for WebSEAL and the distributed session cache

Obtaining the server certificate DN valueObtaining the server certificate DN valueThe ssl-valid-server-dn in the [dsess-cluster] stanza of the WebSEAL configuration file requires the value of the DN found in a valid server certificate sent by the distributed session cache during its communication with WebSEAL.serverscertificatesDN valueYou can obtain the DN value from the distributed session cache administrator directly.Alternatively, you can indirectly determine the value by performing the following procedure:Enable the distributed session cache for WebSEAL:[session] dsess-enabled = yesEnsure that the distributed session cache is configured for SSL. The URL to the distributed session cache requires the HTTPS protocol:[dsess-cluster] server = https://server/DSess/services/DSessFollow the procedures for configuring the ssl-keyfile, ssl-keyfile-stash, and ssl-keyfile-label stanza entries in the [dsess-cluster] stanza of the WebSEAL configuration file. See Configuring the WebSEAL key databaseWebSEAL stores client-side certificates and CA root certificates, used for SSL communication with the distributed session cache, in a key database file..Enter a test value for the ssl-valid-server-dn stanza entry. For example:[dsess-cluster] ssl-valid-server-dn = testRestart the WebSEAL server.WebSEAL returns the following error message:The DN contained within the server certificate, <DN>, is not a configured DN.The DN listed in the message is the DN of the certificate presented by the distributed session cache.Use this value to correctly specify the value for the ssl-valid-server-dn stanza entry.To verify you are communicating with the right SSL server, confirm, with the distributed session cache administrator, the value for the DN returned in the error message.Once you are sure you have the right value for the DN of the distributed session cache server certificate, use that DN for the value of the ssl-valid-server-dn stanza entry.Specifying the SSL certificate distinguished name (DN)The CA root certificate that is stored in a WebSEAL key database file validates that a certificate received from the distributed session cache is authentic. By additionally checking the DN value in the certificate, you can ensure that the server certificate received by WebSEAL from the distributed session cache is the expected certificate.

Obtaining the server certificate DN value

The ssl-valid-server-dn in the [dsess-cluster] stanza of the WebSEAL configuration file requires the value of the DN found in a valid server certificate sent by the distributed session cache during its communication with WebSEAL.

About this task

You can obtain the DN value from the distributed session cache administrator directly.

Alternatively, you can indirectly determine the value by performing the following procedure:

Procedure

Enable the distributed session cache for WebSEAL:

[session] dsess-enabled = yes

Ensure that the distributed session cache is configured for SSL. The URL to the distributed session cache requires the HTTPS protocol:

[dsess-cluster] server = https://server/DSess/services/DSess

Follow the procedures for configuring the ssl-keyfile, ssl-keyfile-stash, and ssl-keyfile-label stanza entries in the [dsess-cluster] stanza of the WebSEAL configuration file. See Configuring the WebSEAL key database.

Enter a test value for the ssl-valid-server-dn stanza entry. For example:

[dsess-cluster] ssl-valid-server-dn = test

Restart the WebSEAL server.

WebSEAL returns the following error message:

The DN contained within the server certificate, <DN>, is not a configured DN.

The DN listed in the message is the DN of the certificate presented by the distributed session cache.

Use this value to correctly specify the value for the ssl-valid-server-dn stanza entry.

To verify you are communicating with the right SSL server, confirm, with the distributed session cache administrator, the value for the DN returned in the error message.

Once you are sure you have the right value for the DN of the distributed session cache server certificate, use that DN for the value of the ssl-valid-server-dn stanza entry.

Parent topic: Specifying the SSL certificate distinguished name (DN)

GSKit configuration for distributed session cache connectionsGSKit configuration for distributed session cache connectionsThere are a number of GSKit attributes that you can use to control how GSKit creates SSL connections. You can configure WebSEAL to use particular GSKit attributes when it initializes SSL connections. GSKitconfigurationdistributed session cacheGSKitThe gsk-attr-name configuration entry in the [dsess-cluster] stanza controls the GSKit attributes that WebSEAL uses when initializing a connection with the distributed session cache. You can specify this configuration entry multiple times. Include each desired GSKit attribute as a new entry.[dsess-cluster] gsk-attr-name = {enum | string | number}:id:valueSimilar configuration entries exist in the [ssl] stanza for connections with clients and junctioned web servers. For further details about these configuration entries, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.

GSKit configuration for distributed session cache connections

There are a number of GSKit attributes that you can use to control how GSKit creates SSL connections. You can configure WebSEAL to use particular GSKit attributes when it initializes SSL connections.

The gsk-attr-name configuration entry in the [dsess-cluster] stanza controls the GSKit attributes that WebSEAL uses when initializing a connection with the distributed session cache. You can specify this configuration entry multiple times. Include each desired GSKit attribute as a new entry.

[dsess-cluster]
gsk-attr-name = {enum | string | number}:id:value

Note: Similar configuration entries exist in the [ssl] stanza for connections with clients and junctioned web servers.

For further details about these configuration entries, see the Web Reverse Proxy Stanza Reference topics in the IBM Knowledge Center.

Parent topic: SSL configuration for WebSEAL and the distributed session cache

Maximum concurrent sessions policyMaximum concurrent sessions policydistributed session cachemaximum concurrent sessions policymaximum concurrent sessions policyThis section contains the following topics:Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Single signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.Setting the maximum concurrent sessions policyYou can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions.Enforcing the maximum concurrent sessions policyUse the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy.Switch user and maximum concurrent sessions policyWhen an administrator uses switch user to impersonate another user, the session at the distributed session cache is considered to belong to the switch user administrator. The maximum concurrent sessions policy applies to the switch user administrator, and not the impersonated user.

Maximum concurrent sessions policy

This section contains the following topics:

Setting the maximum concurrent sessions policy
You can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions.

Enforcing the maximum concurrent sessions policy
Use the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy.

Switch user and maximum concurrent sessions policy
When an administrator uses switch user to impersonate another user, the session at the distributed session cache is considered to belong to the switch user administrator. The maximum concurrent sessions policy applies to the switch user administrator, and not the impersonated user.

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Distributed session cache configuration for WebSEAL

Replica set configuration

Adjustment of the last access time update frequency for the distributed session cache

Communication timeout configuration for the distributed session cache

Performance configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cache

Single signon in a replica set

Setting the maximum concurrent sessions policySetting the maximum concurrent sessions policyYou can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions.pdadmin policymax-concurrent-web-sessionspoliciesmax-concurrent-web-sessionsmax-concurrent-web-sessions policymaximum concurrent sessions policysetting As the administrator, you can apply this policy to a specific user or apply the policy globally to all users registered in this secure domain. See Per user and global settingsThe pdadmin policy commands can be set for a specific user (with the -user option) or globally (by not using the -user option). Any user-specific setting overrides a global setting for the policy. . Use the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy. See Enforcing the maximum concurrent sessions policyUse the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy.. Command syntax for pdadmin policy (each entered as one line): policy set max-concurrent-web-sessions {unset|number|displace|unlimited} [-user username] policy get max-concurrent-web-sessions [-user username] Argument descriptions for pdadmin policy set: unset Disables the max-concurrent-web-sessions policy. With this setting, the policy contains no value. The effective policy for the user is the same as the unlimited setting. The unset setting is the default policy. For example (global setting): pdadmin> policy set max-concurrent-web-sessions unsetnumber Specifies the number of concurrent sessions allowed per user. The user is prevented from establishing more sessions beyond this number. For example (global setting): pdadmin> policy set max-concurrent-web-sessions 2 A error response page (38b9a41f.html "Additional Login Denied") is returned to the user when a login attempt is made that exceeds this value.unlimited Allows an unlimited number of concurrent sessions per user. For example (global setting): pdadmin> policy set max-concurrent-web-sessions unlimiteddisplace Limits users to one active session at one time by forcing a value of 1 session for max-concurrent-web-sessions policy. For example (global setting): pdadmin> policy set max-concurrent-web-sessions displace The response to additional login attempts is governed by the prompt-for-displacement in the [session] stanza of the WebSEAL configuration file. See Interactive displacement and Non-interactive displacement.Maximum concurrent sessions policyInteractive displacementNon-interactive displacementPer user and global settingsThe pdadmin policy commands can be set for a specific user (with the -user option) or globally (by not using the -user option). Any user-specific setting overrides a global setting for the policy.

Setting the maximum concurrent sessions policy

You can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions.

About this task

As the administrator, you can apply this policy to a specific user or apply the policy globally to all users registered in this secure domain. See Per user and global settings.

Use the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy. See Enforcing the maximum concurrent sessions policy.

Command syntax for pdadmin policy (each entered as one line):

policy set max-concurrent-web-sessions {unset|number|displace|unlimited}
[-user username]

policy get max-concurrent-web-sessions [-user username]

Argument descriptions for pdadmin policy set:

unset

Disables the max-concurrent-web-sessions policy. With this setting, the policy contains no value. The effective policy for the user is the same as the unlimited setting.

The unset setting is the default policy.

For example (global setting):

pdadmin> policy set max-concurrent-web-sessions unset

number

Specifies the number of concurrent sessions allowed per user. The user is prevented from establishing more sessions beyond this number.

For example (global setting):

pdadmin> policy set max-concurrent-web-sessions 2

A error response page (38b9a41f.html "Additional Login Denied") is returned to the user when a login attempt is made that exceeds this value.

unlimited

Allows an unlimited number of concurrent sessions per user.

For example (global setting):

pdadmin> policy set max-concurrent-web-sessions unlimited

displace

Limits users to one active session at one time by forcing a value of 1 session for max-concurrent-web-sessions policy.

For example (global setting):

pdadmin> policy set max-concurrent-web-sessions displace

The response to additional login attempts is governed by the prompt-for-displacement in the [session] stanza of the WebSEAL configuration file.

See Interactive displacement and Non-interactive displacement.

Interactive displacement

Non-interactive displacement

Per user and global settings
The pdadmin policy commands can be set for a specific user (with the -user option) or globally (by not using the -user option). Any user-specific setting overrides a global setting for the policy.

Parent topic: Maximum concurrent sessions policy

Interactive displacementInteractive displacementprompt-for-displacement stanza entrysession cachesession displacementsession statesession displacementsession displacementdisplacementsessionpkmsdisplacepkmslogoutOLDSESSIONmacrosHTML server response pagesThe prompt-for-displacement stanza entry in the [session] stanza of the WebSEAL configuration file determines whether or not a user is prompted for appropriate action when the max-concurrent-web-sessions displace policy has been exceeded. This section discusses the interactive option (prompt-for-displacement = yes), where the user is prompted for appropriate action.Example configuration:Policy setting (global example): pdadmin> policy set max-concurrent-web-sessions displacePrompt setting: [session] prompt-for-displacement = yesWhen a second login is attempted, the user receives the too_many_sessions.html response page. You can customize the contents of this page. The default message on this page states:You are already logged in from another client. Do you want to terminate your existing login or cancel this new login request? Terminate existing login Cancel this new loginAction descriptions:Terminate existing login The terminate action calls the WebSEAL /pkmsdisplace function. This function terminates the existing (original) login, creates a new session for the user, logs the user in transparently, and redirects the user to the requested URL. The pkmsdisplace management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it. The original session cookie remaining on the user's original browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. If the user attempts to access another protected resource from the original (older) login session, WebSEAL requires authentication and responds with the standard login form. The OLDSESSION macro contained in this form is set to the value of "1", indicating that the request contains an old ("stale") cookie that no longer matches any entry in the WebSEAL session cache. You can use the value of the OLDSESSION macro as a trigger mechanism for a customized response to the user. This custom response could more accurately explain to the user why the session is not valid anymore. For further information on this feature, see Customized responses for old session cookies.Cancel this new login The cancel action calls the WebSEAL /pkmslogout function. This function closes the current login attempt and returns the standard WebSEAL logout page to the user. The original (older) login session can continue accessing resources.Prerequisite: Maximum concurrent sessions policy must be enabled through an additional configuration. See Enforcing the maximum concurrent sessions policyUse the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy..Setting the maximum concurrent sessions policyYou can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions.

Interactive displacement

The prompt-for-displacement stanza entry in the [session] stanza of the WebSEAL configuration file determines whether or not a user is prompted for appropriate action when the max-concurrent-web-sessions displace policy has been exceeded. This section discusses the interactive option (prompt-for-displacement = yes), where the user is prompted for appropriate action.

Example configuration:

Policy setting (global example):

pdadmin> policy set max-concurrent-web-sessions displace

Prompt setting:

[session]
prompt-for-displacement = yes

When a second login is attempted, the user receives the too_many_sessions.html response page. You can customize the contents of this page. The default message on this page states:

You are already logged in from another client. Do you want to terminate
your existing login or cancel this new login request?

Terminate existing login
Cancel this new login

Action descriptions:

Terminate existing login

The terminate action calls the WebSEAL /pkmsdisplace function. This function terminates the existing (original) login, creates a new session for the user, logs the user in transparently, and redirects the user to the requested URL.

Note: The pkmsdisplace management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

The original session cookie remaining on the user's original browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. If the user attempts to access another protected resource from the original (older) login session, WebSEAL requires authentication and responds with the standard login form.

The OLDSESSION macro contained in this form is set to the value of "1", indicating that the request contains an old ("stale") cookie that no longer matches any entry in the WebSEAL session cache. You can use the value of the OLDSESSION macro as a trigger mechanism for a customized response to the user. This custom response could more accurately explain to the user why the session is not valid anymore.

For further information on this feature, see Customized responses for old session cookies.

Cancel this new login

The cancel action calls the WebSEAL /pkmslogout function. This function closes the current login attempt and returns the standard WebSEAL logout page to the user. The original (older) login session can continue accessing resources.

Prerequisite: Maximum concurrent sessions policy must be enabled through an additional configuration. See Enforcing the maximum concurrent sessions policy.

Parent topic: Setting the maximum concurrent sessions policy

Non-interactive displacementNon-interactive displacementprompt-for-displacement stanza entrysession displacementsession cachesession displacementsession statesession displacementdisplacementsessionmacrosHTML server response pagesOLDSESSIONThe prompt-for-displacement stanza entry in the [session] stanza of the WebSEAL configuration file determines whether or not a user is prompted for appropriate action when the max-concurrent-web-sessions displace policy has been exceeded. This section discusses the non-interactive option (prompt-for-displacement = no), where the user is not prompted for appropriate action.Example configuration:Policy setting (global example): pdadmin> policy set max-concurrent-web-sessions displacePrompt setting: [session] prompt-for-displacement = noWhen a second login is attempted, the original (older) login session is automatically terminated with no prompt. A new session is created for the user and the user is logged in to this new session transparently. The original (older) session is no longer valid.The original session cookie remaining on the user's original browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. If the user attempts to access another protected resource from the original (older) login session, WebSEAL requires authentication and responds with the standard login form. The OLDSESSION macro contained in this form is set to the value of "1", indicating that the request contains an old ("stale") cookie that no longer matches any existing entry in the WebSEAL session cache. You can use the value of the OLDSESSION macro as a trigger mechanism for a customized response to the user. This custom response could more accurately explain to the user why the session is not valid anymore.For further information on this feature, see Customized responses for old session cookies.Setting the maximum concurrent sessions policyYou can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions.

Non-interactive displacement

The prompt-for-displacement stanza entry in the [session] stanza of the WebSEAL configuration file determines whether or not a user is prompted for appropriate action when the max-concurrent-web-sessions displace policy has been exceeded. This section discusses the non-interactive option (prompt-for-displacement = no), where the user is not prompted for appropriate action.

Example configuration:

Policy setting (global example):

pdadmin> policy set max-concurrent-web-sessions displace

Prompt setting:

[session]
prompt-for-displacement = no

When a second login is attempted, the original (older) login session is automatically terminated with no prompt. A new session is created for the user and the user is logged in to this new session transparently. The original (older) session is no longer valid.

The original session cookie remaining on the user's original browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. If the user attempts to access another protected resource from the original (older) login session, WebSEAL requires authentication and responds with the standard login form.

The OLDSESSION macro contained in this form is set to the value of "1", indicating that the request contains an old ("stale") cookie that no longer matches any existing entry in the WebSEAL session cache. You can use the value of the OLDSESSION macro as a trigger mechanism for a customized response to the user. This custom response could more accurately explain to the user why the session is not valid anymore.

For further information on this feature, see Customized responses for old session cookies.

Parent topic: Setting the maximum concurrent sessions policy

Per user and global settings Per user and global settings The pdadmin policy commands can be set for a specific user (with the -user option) or globally (by not using the -user option). Any user-specific setting overrides a global setting for the policy. pdadmin policycommandsper user settingsglobal settingsYou can also disable a policy (with the unset argument). With this setting, the policy contains no value. Examples: A global maximum concurrent web sessions policy of 1 session per user is created. As an exception to this policy, user brian is given a maximum concurrent web sessions policy of 4 sessions.pdadmin> policy set max-concurrent-web-sessions 1 pdadmin> policy set max-concurrent-web-sessions 4 -user brian pdadmin> policy get max-concurrent-web-sessions Maximum concurrent web sessions: 1 pdadmin> policy get max-concurrent-web-sessions -user brian Maximum concurrent web sessions: 4***The specific maximum concurrent web sessions policy for user brian is unset. User brian now has no maximum concurrent web sessions policy. However, user Brian is effectively governed by the current global maximum concurrent web sessions policy of 1 session.pdadmin> policy set max-concurrent-web-sessions unset -user brian pdadmin> policy get max-concurrent-web-sessions -user brian Maximum concurrent web sessions: unset***The global maximum concurrent web sessions policy is unset. All users, including user brian, now have no maximum concurrent web sessions policy. However, the effective policy for all users is the same as the unlimited setting.pdadmin> policy set max-concurrent-web-sessions unset pdadmin> policy get max-concurrent-web-sessions Maximum concurrent web sessions: unsetSetting the maximum concurrent sessions policyYou can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions.

Per user and global settings

The pdadmin policy commands can be set for a specific user (with the -user option) or globally (by not using the -user option). Any user-specific setting overrides a global setting for the policy.

You can also disable a policy (with the unset argument). With this setting, the policy contains no value.

Examples:

A global maximum concurrent web sessions policy of 1 session per user is created. As an exception to this policy, user brian is given a maximum concurrent web sessions policy of 4 sessions.

pdadmin> policy set max-concurrent-web-sessions 1
pdadmin> policy set max-concurrent-web-sessions 4 -user brian

pdadmin> policy get max-concurrent-web-sessions
Maximum concurrent web sessions: 1
pdadmin> policy get max-concurrent-web-sessions -user brian
Maximum concurrent web sessions: 4

***

The specific maximum concurrent web sessions policy for user brian is unset. User brian now has no maximum concurrent web sessions policy. However, user Brian is effectively governed by the current global maximum concurrent web sessions policy of 1 session.

pdadmin> policy set max-concurrent-web-sessions unset -user brian

pdadmin> policy get max-concurrent-web-sessions -user brian
Maximum concurrent web sessions: unset

***

The global maximum concurrent web sessions policy is unset. All users, including user brian, now have no maximum concurrent web sessions policy. However, the effective policy for all users is the same as the unlimited setting.

pdadmin> policy set max-concurrent-web-sessions unset

pdadmin> policy get max-concurrent-web-sessions
Maximum concurrent web sessions: unset

Parent topic: Setting the maximum concurrent sessions policy

Enforcing the maximum concurrent sessions policyEnforcing the maximum concurrent sessions policyUse the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy.enforce-max-sessions-policy stanza entrymaximum concurrent sessions policyenforcingTo set this WebSEAL instance to enforce the max-concurrent-web-sessions policy, enter a value of yes (default). For example:[session] enforce-max-sessions-policy = yesTo set this WebSEAL instance to not enforce the max-concurrent-web-sessions policy, enter a value of no. For example:[session] enforce-max-sessions-policy = noThis stanza entry is effective only when you have configured the distributed session cache to manage sessions for your environment.[session] dsess-enabled=yesBy default, all systems in the distributed session environment enforce this policy:[session] enforce-max-sessions-policy = yesYou can modify the enforce-max-sessions-policy stanza entry for specific WebSEAL instances in the same environment to disable enforcement of the max-concurrent-web-sessions policy:[session] enforce-max-sessions-policy = noUsers accessing those WebSEAL servers with enforce-max-sessions-policy = no can have unlimited login sessions.For information on setting the maximum concurrent sessions policy, see Setting the maximum concurrent sessions policyYou can control the number of sessions each user can have at one time in a distributed session environment managed by the distributed session cache. The pdadmin policy set max-concurrent-web-sessions command specifies this maximum number of concurrent sessions..Maximum concurrent sessions policy is enforced on a per replica set basis.Use the pdadmin policy set command to globally specify a maximum concurrent session policy of 1:pdadmin> policy set max-concurrent-web-sessions 1Maximum concurrent sessions policy

Enforcing the maximum concurrent sessions policy

Use the enforce-max-sessions-policy stanza entry in the [session] stanza of the WebSEAL configuration file to control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy.

Procedure

To set this WebSEAL instance to enforce the max-concurrent-web-sessions policy, enter a value of yes (default). For example:

[session]
enforce-max-sessions-policy = yes

To set this WebSEAL instance to not enforce the max-concurrent-web-sessions policy, enter a value of no. For example:

[session]
enforce-max-sessions-policy = no

Note: This stanza entry is effective only when you have configured the distributed session cache to manage sessions for your environment.

[session]
dsess-enabled=yes

By default, all systems in the distributed session environment enforce this policy:

[session]
enforce-max-sessions-policy = yes

You can modify the enforce-max-sessions-policy stanza entry for specific WebSEAL instances in the same environment to disable enforcement of the max-concurrent-web-sessions policy:

[session]
enforce-max-sessions-policy = no

Users accessing those WebSEAL servers with enforce-max-sessions-policy = no can have unlimited login sessions.

For information on setting the maximum concurrent sessions policy, see Setting the maximum concurrent sessions policy.

Note: Maximum concurrent sessions policy is enforced on a per replica set basis.

Example

Use the pdadmin policy set command to globally specify a maximum concurrent session policy of 1:

pdadmin> policy set max-concurrent-web-sessions 1

Parent topic: Maximum concurrent sessions policy

Switch user and maximum concurrent sessions policySwitch user and maximum concurrent sessions policyWhen an administrator uses switch user to impersonate another user, the session at the distributed session cache is considered to belong to the switch user administrator. The maximum concurrent sessions policy applies to the switch user administrator, and not the impersonated user.switch usermaximum concurrent sessions policymax-concurrent-web-sessions policymaximum concurrent sessions policywith switch userFor example: if the user "brian" has a maximum concurrent sessions policy of 1 and is logged in to the WebSEAL server, a switch user administrator is still able to impersonate "brian." The maximum concurrent sessions policy for user "brian" does not apply to the impersonated session.Maximum concurrent sessions policy

Switch user and maximum concurrent sessions policy

When an administrator uses switch user to impersonate another user, the session at the distributed session cache is considered to belong to the switch user administrator. The maximum concurrent sessions policy applies to the switch user administrator, and not the impersonated user.

For example: if the user "brian" has a maximum concurrent sessions policy of 1 and is logged in to the WebSEAL server, a switch user administrator is still able to impersonate "brian." The maximum concurrent sessions policy for user "brian" does not apply to the impersonated session.

Parent topic: Maximum concurrent sessions policy

Single signon in a replica setSingle signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.distributed session cachesingle signon in a replica setsession sharingsession sharingreplica setsingle signonreplica setTopic index:Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.Distributed session cache configuration for WebSEALThere are numerous configuration entries in the [session], [dsess], and [dsess-cluster] stanzas for configuring WebSEAL to use the distributed session cache.Replica set configurationA replica set consists of clustered servers that share sessions. A client session created by one member of a replica set can be used unmodified by another. Adjustment of the last access time update frequency for the distributed session cacheThe dsess-last-access-update-interval stanza entry in the [session] stanza of the WebSEAL configuration file specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Communication timeout configuration for the distributed session cacheThere are two configuration entries to control the communication timeout values for the distributed session cache environment.Performance configuration for the distributed session cacheYou can configure the maximum number of pre-allocated session IDs and the handle pool size to fine-tune the performance of the distributed session cache.SSL configuration for WebSEAL and the distributed session cacheWhen the [dsess-cluster] server stanza entry specifies the HTTPS protocol in the URL, you must configure WebSEAL for SSL communication with the distributed session cache. WebSEAL can authenticate to the distributed session cache with client certificates.Maximum concurrent sessions policyReplica set and session sharing conceptsA replica set is a collection of Web security servers that are configured to share sessions. Session sharing allows single signon among all servers in the replica set while enforcing concurrent session limitations and session terminations. Configuring session sharingThere are two high level steps to configure session sharing in a distributed session cache environment.

Single signon in a replica set

A distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.

Topic index:

Replica set and session sharing concepts
A replica set is a collection of Web security servers that are configured to share sessions. Session sharing allows single signon among all servers in the replica set while enforcing concurrent session limitations and session terminations.

Configuring session sharing
There are two high level steps to configure session sharing in a distributed session cache environment.

Parent topic: Advanced configuration for the distributed session cache

Related concepts:

Distributed session cache configuration for WebSEAL

Replica set configuration

Adjustment of the last access time update frequency for the distributed session cache

Communication timeout configuration for the distributed session cache

Performance configuration for the distributed session cache

SSL configuration for WebSEAL and the distributed session cache

Maximum concurrent sessions policy

Replica set and session sharing conceptsReplica set and session sharing conceptsA replica set is a collection of Web security servers that are configured to share sessions. Session sharing allows single signon among all servers in the replica set while enforcing concurrent session limitations and session terminations. distributed session cachereplica setsdomain cookiesreplicassession sharing conceptssetsdomaincookiesdistributed session cachecookiesdomain (with the distributed session cache)A user can log on to any server in the replica set without authenticating again.For example, as a user, you log in to the main website for your company: www.example.com. The www.example.com site is handled by a WebSEAL cluster where all WebSEAL servers belong to the "www.example.com" replica set.WebSEAL is configured to provide you (as an authenticated user) with a domain session cookie for .example.com.Later in the session, you access sales.example.com, which is the main website for the company's sales department. The sales.example.com site is handled by a WebSEAL cluster where all WebSEAL servers belong to the "sales.example.com" replica set.The distributed session cache configuration manages all of the replica sets. In this example, www.example.com and sales.example.com are both configured as replica sets.The sales.example.com WebSEAL cluster uses your domain session cookie to acquire your session information at www.example.com. With this session information, you are not asked to authenticate again and single signon is achieved.For session sharing to function correctly, all of the following conditions must be met: The values for session lifetime and inactivity timeouts on all servers in the replica sets must be identical. Authentication configuration and policy on all servers in the replica sets must be compatible. As an example of an incompatible configuration, consider the following: www.example.com is configured for forms authentication.test.example.com is configured for EAI authentication.The resource www.example.com/action.jsp is protected by a POP requiring reauthentication. If a user logs on to test.example.com and then accesses www.example.com, the user is able to access most resources on www.example.com. However, the user is not able to access www.example.com/action.jsp because the user cannot perform an EAI reauthentication on www.example.com.Single signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.

Replica set and session sharing concepts

A replica set is a collection of Web security servers that are configured to share sessions. Session sharing allows single signon among all servers in the replica set while enforcing concurrent session limitations and session terminations.

A user can log on to any server in the replica set without authenticating again.

For example, as a user, you log in to the main website for your company: www.example.com. The www.example.com site is handled by a WebSEAL cluster where all WebSEAL servers belong to the "www.example.com" replica set.

WebSEAL is configured to provide you (as an authenticated user) with a domain session cookie for .example.com.

Later in the session, you access sales.example.com, which is the main website for the company's sales department. The sales.example.com site is handled by a WebSEAL cluster where all WebSEAL servers belong to the "sales.example.com" replica set.

The distributed session cache configuration manages all of the replica sets. In this example, www.example.com and sales.example.com are both configured as replica sets.

The sales.example.com WebSEAL cluster uses your domain session cookie to acquire your session information at www.example.com. With this session information, you are not asked to authenticate again and single signon is achieved.

For session sharing to function correctly, all of the following conditions must be met:

The values for session lifetime and inactivity timeouts on all servers in the replica sets must be identical.

Authentication configuration and policy on all servers in the replica sets must be compatible.

As an example of an incompatible configuration, consider the following:

www.example.com is configured for forms authentication.

test.example.com is configured for EAI authentication.

The resource www.example.com/action.jsp is protected by a POP requiring reauthentication.

If a user logs on to test.example.com and then accesses www.example.com, the user is able to access most resources on www.example.com. However, the user is not able to access www.example.com/action.jsp because the user cannot perform an EAI reauthentication on www.example.com.

Parent topic: Single signon in a replica set

Configuring session sharingConfiguring session sharingThere are two high level steps to configure session sharing in a distributed session cache environment.session sharingconfigurationoverview Configure all Web security servers in the replica set to use the same name for session cookies. See Configuring session cookie namesConfigure all Web security servers in the replica set to use the same name for session cookies..Configure all Web security servers in the same replica set with a list of DNS domains that should be used for domain session cookies. See Configuring DNS domainsConfigure all of the Web security servers in the same replica set with a list of DNS domains that are used for domain session cookies. .Single signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set.Configuring session cookie namesConfigure all Web security servers in the replica set to use the same name for session cookies.Configuring DNS domainsConfigure all of the Web security servers in the same replica set with a list of DNS domains that are used for domain session cookies.

Configuring session sharing

There are two high level steps to configure session sharing in a distributed session cache environment.

About this task

Configure all Web security servers in the replica set to use the same name for session cookies.

See Configuring session cookie names.

Configure all Web security servers in the same replica set with a list of DNS domains that should be used for domain session cookies.

See Configuring DNS domains.

Configuring session cookie names
Configure all Web security servers in the replica set to use the same name for session cookies.

Configuring DNS domains
Configure all of the Web security servers in the same replica set with a list of DNS domains that are used for domain session cookies.

Parent topic: Single signon in a replica set

Configuring session cookie names Configuring session cookie names Configure all Web security servers in the replica set to use the same name for session cookies.distributed session cachessl-session-cookie-name stanza entryssl-session-cookie-name stanza entry The cookie name used for WebSEAL session cookies is specified by the tcp-session-cookie-name and ssl-session-cookie-name stanza entries in the [session] stanza of the WebSEAL configuration file. For example (default WebSEAL cookie names for TCP and SSL sessions): [session] tcp-session-cookie-name = PD-H-SESSION-ID ssl-session-cookie-name = PD-S-SESSION-ID See also Customization of the session cookie name. Configuring session sharingThere are two high level steps to configure session sharing in a distributed session cache environment.

Configuring session cookie names

Configure all Web security servers in the replica set to use the same name for session cookies.

About this task

The cookie name used for WebSEAL session cookies is specified by the tcp-session-cookie-name and ssl-session-cookie-name stanza entries in the [session] stanza of the WebSEAL configuration file. For example (default WebSEAL cookie names for TCP and SSL sessions):

[session]
tcp-session-cookie-name = PD-H-SESSION-ID
ssl-session-cookie-name = PD-S-SESSION-ID

See also Customization of the session cookie name.

Parent topic: Configuring session sharing

Configuring DNS domainsConfiguring DNS domainsConfigure all of the Web security servers in the same replica set with a list of DNS domains that are used for domain session cookies. domainstanza entrysession-cookie-domains stanza WebSEAL session cookies are the required session ID data type used in a WebSEAL environment using the distributed session cache. Normally, session cookies are server-specific (or host) cookies. A browser only returns a host type cookie to the server that originally sent the cookie. To enable session sharing across multiple clusters in the same DNS domain, it is necessary to use domain type cookies. You define participating domains in the domain stanza entry, located in the [session-cookie-domains] stanza of the WebSEAL configuration file. When a domain stanza entry is uncommented and provided with a value, WebSEAL session cookies automatically become domain type cookies. For example: [session-cookie-domains] domain = example1.com domain = example2.com WebSEAL decides what domain to use for domain session cookies based on the website the user connects to and the [session-cookie-domains] stanza. Add an entry to this stanza matching the domain used for the replica set. As an example, consider a WebSEAL server with three virtual hosts: www.example.com www.abc.ibm.com www.tivoli.com The following conditions apply to this example: The www.example.com site participates in the "example.com" replica set.The www.abc.ibm.com site participates in the "abc.ibm.com" replica set.The www.tivoli.com site does not share sessions with other Web security servers, so is not assigned to a replica set. To configure domain session cookies for both the example.com and abc.ibm.com domains, set the following configuration options in each participating Web security server: [session-cookie-domains] domain = example.com domain = abc.ibm.comConfiguring session sharingThere are two high level steps to configure session sharing in a distributed session cache environment.

Configuring DNS domains

Configure all of the Web security servers in the same replica set with a list of DNS domains that are used for domain session cookies.

About this task

WebSEAL session cookies are the required session ID data type used in a WebSEAL environment using the distributed session cache. Normally, session cookies are server-specific (or host) cookies. A browser only returns a host type cookie to the server that originally sent the cookie.

To enable session sharing across multiple clusters in the same DNS domain, it is necessary to use domain type cookies.

You define participating domains in the domain stanza entry, located in the [session-cookie-domains] stanza of the WebSEAL configuration file.

When a domain stanza entry is uncommented and provided with a value, WebSEAL session cookies automatically become domain type cookies. For example:

[session-cookie-domains]
domain = example1.com
domain = example2.com

WebSEAL decides what domain to use for domain session cookies based on the website the user connects to and the [session-cookie-domains] stanza. Add an entry to this stanza matching the domain used for the replica set.

As an example, consider a WebSEAL server with three virtual hosts:

www.example.com
www.abc.ibm.com
www.tivoli.com

The following conditions apply to this example:

The www.example.com site participates in the "example.com" replica set.

The www.abc.ibm.com site participates in the "abc.ibm.com" replica set.

The www.tivoli.com site does not share sessions with other Web security servers, so is not assigned to a replica set.

To configure domain session cookies for both the example.com and abc.ibm.com domains, set the following configuration options in each participating Web security server:

[session-cookie-domains]
domain = example.com
domain = abc.ibm.com

Parent topic: Configuring session sharing

AuthorizationAuthorizationWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Configuration for authorizationKey management

Authorization

Configuration for authorization

Key management

Parent topic: Web Reverse Proxy configuration

Configuration for authorizationConfiguration for authorizationauthorizationconfigurationThis chapter discusses WebSEAL functions that affect the authorization service and process.Topic Index:AuthorizationWebSEAL-specific ACL policies

Configuration for authorization

This chapter discusses WebSEAL functions that affect the authorization service and process.

Topic Index:

WebSEAL-specific ACL policies

Parent topic: Authorization

WebSEAL-specific ACL policies WebSEAL-specific ACL policies ACLpoliciesWebSEAL-specificThe following security considerations apply for the /WebSEAL container in the protected object space: The WebSEAL object begins the chain of ACL inheritance for the WebSEAL region of the object space.If you do not apply any other explicit ACLs, this object defines (through inheritance) the security policy for the entire Web space.The traverse permission is required for access to any object below this point.Configuration for authorization/WebSEAL/host-instance_name/WebSEAL/host-instance_name/fileThis subdirectory entry represents the resource object checked for HTTP access.WebSEAL ACL permissionsDefault /WebSEAL ACL policyValid characters for ACL namesQuality of protection POPConfiguration of authorization database updates and pollingConfiguring quality of protection levelsAuthorization decision information from HTTP requestsWebSEAL can pass configured elements from the HTTP request to the authorization framework for use when it is making authorization decisions.Support for OAuth authorization decisionsOAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.

WebSEAL-specific ACL policies

The following security considerations apply for the /WebSEAL container in the protected object space:

The WebSEAL object begins the chain of ACL inheritance for the WebSEAL region of the object space.

If you do not apply any other explicit ACLs, this object defines (through inheritance) the security policy for the entire Web space.

The traverse permission is required for access to any object below this point.

/WebSEAL/host-instance_name

/WebSEAL/host-instance_name/file
This subdirectory entry represents the resource object checked for HTTP access.

WebSEAL ACL permissions

Default /WebSEAL ACL policy

Valid characters for ACL names

Quality of protection POP

Configuration of authorization database updates and polling

Configuring quality of protection levels

Authorization decision information from HTTP requests
WebSEAL can pass configured elements from the HTTP request to the authorization framework for use when it is making authorization decisions.

Support for OAuth authorization decisions
OAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.

Parent topic: Configuration for authorization

/WebSEAL/host-instance_name/WebSEAL/host-instance_nameWebSEAL/host-instance_nameWebSEALhost-instance_nameThis subdirectory entry represents the beginning of the Web space for a particular WebSEAL instance. The following security considerations apply for this object: The traverse permission is required for access to any object below this point.If you do not apply any other explicit ACLs, this object defines (through inheritance) the security policy for the entire object space on this machine.WebSEAL-specific ACL policies

/WebSEAL/host-instance_name

This subdirectory entry represents the beginning of the Web space for a particular WebSEAL instance. The following security considerations apply for this object:

The traverse permission is required for access to any object below this point.

If you do not apply any other explicit ACLs, this object defines (through inheritance) the security policy for the entire object space on this machine.

Parent topic: WebSEAL-specific ACL policies

/WebSEAL/host-instance_name/file/WebSEAL/host-instance_name/fileThis subdirectory entry represents the resource object checked for HTTP access.WebSEALhost-instance_nameWebSEAL/host-instance_nameThe permissions checked depend on the operation being requested.WebSEAL-specific ACL policies

/WebSEAL/host-instance_name/file

This subdirectory entry represents the resource object checked for HTTP access.

The permissions checked depend on the operation being requested.

Parent topic: WebSEAL-specific ACL policies

WebSEAL ACL permissions WebSEAL ACL permissions ACLpermissionsWebSEALACLThe following table describes the ACL permissions applicable for the WebSEAL region of the object space: OperationDescriptionrreadView the Web object.xexecuteRun the CGI program. ddeleteRemove the Web object from the Web space.mmodifyPUT an HTTP object. (Place - publish - an HTTP object in the WebSEAL object space.)llistRequired by policy server to generate an automated directory listing of the Web space. This permission also governs whether a client can see the directory contents listing when the default "index.html" page is not present.WebSEAL-specific ACL policies

WebSEAL ACL permissions

The following table describes the ACL permissions applicable for the WebSEAL region of the object space:

Operation
Description

r

read

View the Web object.

x

execute

Run the CGI program.

d

delete

Remove the Web object from the Web space.

m

modify

PUT an HTTP object. (Place - publish - an HTTP object in the WebSEAL object space.)

l

list

Required by policy server to generate an automated directory listing of the Web space.

This permission also governs whether a client can see the directory contents listing when the default "index.html" page is not present.

Parent topic: WebSEAL-specific ACL policies

Default /WebSEAL ACL policy Default /WebSEAL ACL policy WebSEALACLDefault/WebSEAL ACL policyCore entries for the WebSEAL ACL, default-webseal, include: Group iv-admin Tcmdbsvarxl Group webseal-servers Tgmdbsrxl User sec_master Tcmdbsvarxl Any-other Trx Unauthenticated TAt installation, this default ACL is attached to the /WebSEAL container object in the object space.The group, webseal-servers, contains an entry for each WebSEAL server in the secure domain. The default permissions allow the servers to respond to browser requests.The traverse permission allows expansion of the Web space. The list permission allows the Web Portal Manager to display the contents of the Web space.WebSEAL-specific ACL policies

Default /WebSEAL ACL policy

Core entries for the WebSEAL ACL, default-webseal, include:

Group iv-admin             Tcmdbsvarxl
Group webseal-servers      Tgmdbsrxl
User sec_master            Tcmdbsvarxl
Any-other                  Trx
Unauthenticated            T

At installation, this default ACL is attached to the /WebSEAL container object in the object space.

The group, webseal-servers, contains an entry for each WebSEAL server in the secure domain. The default permissions allow the servers to respond to browser requests.

The traverse permission allows expansion of the Web space. The list permission allows the Web Portal Manager to display the contents of the Web space.

Parent topic: WebSEAL-specific ACL policies

Valid characters for ACL names Valid characters for ACL names ACLpoliciesvalid characters for ACL namesnamesThe following characters are valid for creating ACL names: A-Za-z0-9underscore (_)hyphen (-)backslash (\)Any character from a double-byte character setFor detailed information about creating ACL names, see the Web command reference topics in the IBM Knowledge Center.WebSEAL-specific ACL policies

Valid characters for ACL names

The following characters are valid for creating ACL names:

A-Z

a-z

0-9

underscore (_)

hyphen (-)

backslash (\)

Any character from a double-byte character set

For detailed information about creating ACL names, see the Web command reference topics in the IBM Knowledge Center.

Parent topic: WebSEAL-specific ACL policies

Quality of protection POPQuality of protection POPquality of protectionPOPPOPquality of protectionThe protected object policy (POP) attribute for quality of protection allows you to specify what level of data protection is required when performing an operation on an object.The quality of protection POP attribute is used to determine whether access will be granted to a requested resource. When an ACL check for a resource succeeds, the quality of protection POP is checked. If a quality of protection POP exists, and the resource manager (WebSEAL) cannot guarantee the required level of protection, the request is denied.The syntax for setting the quality of protection POP attribute is as follows:pdadmin> pop modify pop-name set qop {none|integrity|privacy}When the quality of protection level is set to either integrity or privacy, WebSEAL requires data encryption through the use of Secure Socket Layer (SSL).For example: pdadmin> pop modify test set qop privacyWebSEAL-specific ACL policies

Quality of protection POP

The protected object policy (POP) attribute for quality of protection allows you to specify what level of data protection is required when performing an operation on an object.

The quality of protection POP attribute is used to determine whether access will be granted to a requested resource. When an ACL check for a resource succeeds, the quality of protection POP is checked. If a quality of protection POP exists, and the resource manager (WebSEAL) cannot guarantee the required level of protection, the request is denied.

The syntax for setting the quality of protection POP attribute is as follows:

pdadmin> pop modify pop-name set qop {none|integrity|privacy}

When the quality of protection level is set to either integrity or privacy, WebSEAL requires data encryption through the use of Secure Socket Layer (SSL).

For example:

pdadmin> pop modify test set qop privacy

Parent topic: WebSEAL-specific ACL policies

Configuration of authorization database updates and polling Configuration of authorization database updates and polling authorizationdatabaseupdatespollingThis section contains the following topics:WebSEAL-specific ACL policiesDatabase update and polling conceptsConfiguration of update notification listeningConfiguration of authorization database polling

Configuration of authorization database updates and polling

This section contains the following topics:

Database update and polling concepts

Configuration of update notification listening

Configuration of authorization database polling

Parent topic: WebSEAL-specific ACL policies

Database update and polling conceptsDatabase update and polling conceptsauthorizationdatabaseupdatespollingreplica locationupdate notification listeningconceptspolling authorization databaseconceptsaznapi-configuration stanzadb-file stanza entryreplicasauthorization database locationThe Security Access Manager policy server (pdmgrd) manages the master authorization policy database and maintains location information about other Security Access Manager servers in the secure domain. A Security Access Manager administrator can make security policy changes to the secure domain at any time. The policy server makes the necessary adjustments to the master authorization database whenever security policy changes are implemented.When the policy server makes a change to the master authorization database, it can send out notification of this change to all replica databases in the secure domain that support individual policy enforcers (such as WebSEAL). The policy enforcers must then request an actual database update from the master authorization database.WebSEAL, as a resource manager and policy enforcer, has three options to obtain information about authorization database changes: Listen for update notifications from the policy server (configurable and enabled by default).Check (poll) the master authorization database at regular intervals (configurable and disabled by default).Enable both listening and polling.The [aznapi-configuration] stanza of the WebSEAL configuration file contains stanza entries for configuring update notification listening and database polling.Configuration of authorization database updates and polling

Database update and polling concepts

The Security Access Manager policy server (pdmgrd) manages the master authorization policy database and maintains location information about other Security Access Manager servers in the secure domain. A Security Access Manager administrator can make security policy changes to the secure domain at any time. The policy server makes the necessary adjustments to the master authorization database whenever security policy changes are implemented.

When the policy server makes a change to the master authorization database, it can send out notification of this change to all replica databases in the secure domain that support individual policy enforcers (such as WebSEAL). The policy enforcers must then request an actual database update from the master authorization database.

WebSEAL, as a resource manager and policy enforcer, has three options to obtain information about authorization database changes:

Listen for update notifications from the policy server (configurable and enabled by default).

Check (poll) the master authorization database at regular intervals (configurable and disabled by default).

Enable both listening and polling.

The [aznapi-configuration] stanza of the WebSEAL configuration file contains stanza entries for configuring update notification listening and database polling.

Parent topic: Configuration of authorization database updates and polling

Configuration of update notification listening Configuration of update notification listening listen-flags stanza entryssl-listening-port stanza entryauthorizationdatabaseconfiguring update notification listeningupdate notification listeningconfigurationThe listen-flags stanza entry, located in the [aznapi-configuration] stanza of the WebSEAL configuration file, enables and disables update notification listening by WebSEAL. By default, notification listening is enabled. To disable notification listening, enter "disable".[aznapi-configuration] listen-flags = enableThe ssl-listening-port stanza entry, located in the [ssl] stanza of the WebSEAL configuration file, specifies the SSL port for the notification listener:[ssl] ssl-listening-port = 7234Do not change the ssl-listening-port entry directly; this option should be modified only by issuing the scrsslcfg -chgport command so that the policy server can detect that the listening port has been changed. Otherwise, the resource manager cannot receive policy update notifications or pdadmin server task commands.Configuration of authorization database updates and polling

Configuration of update notification listening

The listen-flags stanza entry, located in the [aznapi-configuration] stanza of the WebSEAL configuration file, enables and disables update notification listening by WebSEAL. By default, notification listening is enabled. To disable notification listening, enter "disable".

[aznapi-configuration]
listen-flags = enable

The ssl-listening-port stanza entry, located in the [ssl] stanza of the WebSEAL configuration file, specifies the SSL port for the notification listener:

[ssl]
ssl-listening-port = 7234

Note: Do not change the ssl-listening-port entry directly; this option should be modified only by issuing the scrsslcfg -chgport command so that the policy server can detect that the listening port has been changed. Otherwise, the resource manager cannot receive policy update notifications or pdadmin server task commands.

Parent topic: Configuration of authorization database updates and polling

Configuration of authorization database polling Configuration of authorization database polling refresh-interval stanza entrypolling authorization databaseconfigurationauthorizationdatabasepollingYou can configure WebSEAL to regularly poll the master authorization database for update information. The cache-refresh-interval stanza entry can be set to "default", "disable", or a specific time interval in seconds. The "default" setting is equal to 600 seconds. By default, polling is disabled.[aznapi-configuration] cache-refresh-interval = disableConfiguration of authorization database updates and polling

Configuration of authorization database polling

You can configure WebSEAL to regularly poll the master authorization database for update information. The cache-refresh-interval stanza entry can be set to "default", "disable", or a specific time interval in seconds. The "default" setting is equal to 600 seconds. By default, polling is disabled.

[aznapi-configuration]
cache-refresh-interval = disable

Parent topic: Configuration of authorization database updates and polling

Configuring quality of protection levels Configuring quality of protection levels ssl-qop-mgmt stanza entryssl-qop-mgmt-default stanzaquality of protectiondefault levelcipherssupportedYou can control the default level of encryption required for access to WebSEAL over SSL (HTTPS) by configuring the quality of protection (QOP). Default quality of protection management is controlled using stanza entries in the "SSL QUALITY OF PROTECTION MANAGEMENT" section of the WebSEAL configuration file: Enable and disable QOP management with the ssl-qop-mgmt stanza entry.Specify allowed encryption levels in the [ssl-qop-mgmt-default] stanza.Enable quality of protection management: [ssl-qop] ssl-qop-mgmt = yesSpecify the default encryption level for HTTPS access. The syntax is: default = {ALL|NONE|cipher_level}Supported values for cipher_level are: NONE, ALL, NULL, DES-56, FIPS-DES-56, DES-168, FIPS-DES-168, RC2-40, RC2-128, RC4-40, RC4-56, RC4-128, AES-128, AES-256 The value "NONE" disables encryption. For example: [ssl-qop-mgmt-default] default = ALL Note that you can also specify a selected group of ciphers: [ssl-qop-mgmt-default] default = RC4-128 default = RC2-128 default = DES-168 Notes: NONE means that no SSL connection is allowed.NULL means that unencrypted SSL connection is allowed.ALL means that all types of SSL connections are allowed.There can be multiple cipher/MAC levels made available to the connection for a given quality of protection cipher selection. These configurations will still have the same encryption bit strength, just different MAC methods (SHA1 or MD5)RC2-128 is available only with SSLv2. If it is the only cipher selection, WebSEAL will disable SSLv3 and TLSv1 for the affected connection.NULL, FIPS-DES-56, FIPS-DES-168, RC4-56, AES-128, and AES-256 are available only with SSLv3 and TLSv1. If they are the only ciphers available to a given connection, SSLv2 will be disabled for the affected connection.AES Support is determined automatically by GSKit based on the base-crypto-library setting. AES-128 and AES-256 are available only if AES Support is enabled by GSKit, else they will be ignored.FIPS-DES-56 and FIPS-DES-168 are available only when fips-mode-processing is enabled (set to yes). Otherwise they are ignoredSecurity Access Manager uses GSKit 8. The Cipher specifications supported by GSKIT 8 when used in SSLv2/TLS in Internet security are:SSL_RSA_WITH_NULL_MD5 SSL_RSA_WITH_NULL_SHA SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSL_RSA_WITH_RC4_128_MD5 SSL_RSA_WITH_RC4_128_SHA SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 SSL_RSA_EXPORT_WITH_DES40_CBC_SHA SSL_RSA_WITH_DES_CBC_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA TLS_RSA_EXPORT1024_WITH_RC4_56_SHA SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHAThese TLS cipher specifications are also used with SSLV3. WebSEAL-specific ACL policiesConfiguration of QOP for individual hosts and networks

Configuring quality of protection levels

You can control the default level of encryption required for access to WebSEAL over SSL (HTTPS) by configuring the quality of protection (QOP). Default quality of protection management is controlled using stanza entries in the "SSL QUALITY OF PROTECTION MANAGEMENT" section of the WebSEAL configuration file:

Enable and disable QOP management with the ssl-qop-mgmt stanza entry.

Specify allowed encryption levels in the [ssl-qop-mgmt-default] stanza.

Enable quality of protection management:

[ssl-qop]
ssl-qop-mgmt = yes

Specify the default encryption level for HTTPS access. The syntax is:

default = {ALL|NONE|cipher_level}

Supported values for cipher_level are:

NONE, ALL, NULL, DES-56, FIPS-DES-56, DES-168, FIPS-DES-168,
 RC2-40, RC2-128, RC4-40, RC4-56, RC4-128, AES-128, AES-256

The value "NONE" disables encryption.

For example:

[ssl-qop-mgmt-default]
default = ALL

Note that you can also specify a selected group of ciphers:

[ssl-qop-mgmt-default]
default = RC4-128
default = RC2-128
default = DES-168

Notes:

NONE means that no SSL connection is allowed.

NULL means that unencrypted SSL connection is allowed.

ALL means that all types of SSL connections are allowed.

There can be multiple cipher/MAC levels made available to the connection for a given quality of protection cipher selection. These configurations will still have the same encryption bit strength, just different MAC methods (SHA1 or MD5)

RC2-128 is available only with SSLv2. If it is the only cipher selection, WebSEAL will disable SSLv3 and TLSv1 for the affected connection.

NULL, FIPS-DES-56, FIPS-DES-168, RC4-56, AES-128, and AES-256 are available only with SSLv3 and TLSv1. If they are the only ciphers available to a given connection, SSLv2 will be disabled for the affected connection.

AES Support is determined automatically by GSKit based on the base-crypto-library setting. AES-128 and AES-256 are available only if AES Support is enabled by GSKit, else they will be ignored.

FIPS-DES-56 and FIPS-DES-168 are available only when fips-mode-processing is enabled (set to yes). Otherwise they are ignored

Security Access Manager uses GSKit 8. The Cipher specifications supported by GSKIT 8 when used in SSLv2/TLS in Internet security are:

SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA
TLS_RSA_EXPORT1024_WITH_RC4_56_SHA
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA

These TLS cipher specifications are also used with SSLV3.

Configuration of QOP for individual hosts and networks

Parent topic: WebSEAL-specific ACL policies

Configuration of QOP for individual hosts and networks Configuration of QOP for individual hosts and networks ssl-qop-mgmt-hosts stanzassl-qop-mgmt-networks stanzaquality of protectionhostsnetworksThe ssl-qop-mgmt = yes stanza entry also enables any settings that appear in the [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas. These stanzas allow quality of protection management by specific host/network/netmask IP address. The [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas are provided for compatibility with prior versions of WebSEAL only. It is recommended that you not use them for Security Access Manager configuration. Additionally, Internet Protocol version 6 (IPv6) addresses are not supported by these stanzas.The [ssl-qop-mgmt-default] stanza lists the ciphers used for all IP addresses not matched in the [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas.Example configuration syntax for hosts: [ssl-qop-mgmt-hosts] xxx.xxx.xxx.xxx = ALL yyy.yyy.yyy.yyy = RC2-128Example configuration syntax for network/netmask: [ssl-qop-mgmt-networks] xxx.xxx.xxx.xxx/255.255.255.0 = RC4-128 yyy.yyy.yyy.yyy/255.255.0.0 = DES-56Note that the entry for an IP address specified under [ssl-qop-mgmt-hosts] takes priority over an entry for the same address in [ssl-qop-mgmt-networks]. Likewise, an entry in [ssl-qop-mgmt-networks] takes priority over an entry for the same address in [ssl-qop-mgmt-default]. If you must use [ssl-qop-mgmt-hosts] or [ssl-qop-mgmt-networks] for compatibility concerns, review the IP address settings under all stanzas to ensure that a specific IP address is not listed under more than one stanza. If an IP address is listed under more than one stanza, ensure that the order of evaluation yields the desired configuration.Configuring quality of protection levels

Configuration of QOP for individual hosts and networks

The ssl-qop-mgmt = yes stanza entry also enables any settings that appear in the [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas. These stanzas allow quality of protection management by specific host/network/netmask IP address.

Note: The [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas are provided for compatibility with prior versions of WebSEAL only. It is recommended that you not use them for Security Access Manager configuration. Additionally, Internet Protocol version 6 (IPv6) addresses are not supported by these stanzas.

The [ssl-qop-mgmt-default] stanza lists the ciphers used for all IP addresses not matched in the [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas.

Example configuration syntax for hosts:

[ssl-qop-mgmt-hosts]
xxx.xxx.xxx.xxx = ALL
yyy.yyy.yyy.yyy = RC2-128

Example configuration syntax for network/netmask:

[ssl-qop-mgmt-networks]
xxx.xxx.xxx.xxx/255.255.255.0 = RC4-128
yyy.yyy.yyy.yyy/255.255.0.0 = DES-56

Note that the entry for an IP address specified under [ssl-qop-mgmt-hosts] takes priority over an entry for the same address in [ssl-qop-mgmt-networks]. Likewise, an entry in [ssl-qop-mgmt-networks] takes priority over an entry for the same address in [ssl-qop-mgmt-default].

If you must use [ssl-qop-mgmt-hosts] or [ssl-qop-mgmt-networks] for compatibility concerns, review the IP address settings under all stanzas to ensure that a specific IP address is not listed under more than one stanza. If an IP address is listed under more than one stanza, ensure that the order of evaluation yields the desired configuration.

Parent topic: Configuring quality of protection levels

Authorization decision information from HTTP requestsAuthorization decision information from HTTP requestsAuthorization decision information in WebSEALWebSEAL can pass configured elements from the HTTP request to the authorization framework for use when it is making authorization decisions.authorizationdecision informationHTTP requestsauthorization decision informationThe following HTTP request elements can be passed to the authorization framework:The HTTP method of the requestThe HTTP scheme of the requestThe request URIThe client IP addressSpecific HTTP headers contained in the requestSpecific POST data elements that are contained in the request. WebSEAL supports two types of POST data:Normal FORM data, which is the application/x-www-form-urlencoded content-type.JavaScript Object Notation (JSON) data, which is the application/json content-type. For more information about the JSON syntax, see http://www.json.org.The [azn-decision-info] stanza in the WebSEAL configuration file specifies the extra information that is passed to the authorization framework. For more information about how to configure WebSEAL to pass extra information to the authorization framework, see the Web Reverse Proxy Stanza Reference topics. WebSEAL-specific ACL policies

Authorization decision information from HTTP requests

WebSEAL can pass configured elements from the HTTP request to the authorization framework for use when it is making authorization decisions.

The following HTTP request elements can be passed to the authorization framework:

The HTTP method of the request

The HTTP scheme of the request

The request URI

The client IP address

Specific HTTP headers contained in the request

Specific POST data elements that are contained in the request. WebSEAL supports two types of POST data:

Normal FORM data, which is the application/x-www-form-urlencoded content-type.

JavaScript Object Notation (JSON) data, which is the application/json content-type. For more information about the JSON syntax, see http://www.json.org.

The [azn-decision-info] stanza in the WebSEAL configuration file specifies the extra information that is passed to the authorization framework.

For more information about how to configure WebSEAL to pass extra information to the authorization framework, see the Web Reverse Proxy Stanza Reference topics.

Parent topic: WebSEAL-specific ACL policies

Support for OAuth authorization decisionsSupport for OAuth authorization decisionsSupport for OAuth authorization decisions OAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.WebSEALOAuthOAuthauthorization decision supportWebSEAL supports the EAS plug-in, which leverages OAuth 2.0 capabilities. This plug-in allows OAuth decisions to be made as a part of the standard authorization on WebSEAL requests. This functionality uses the authorization server of the Advanced Access Control Module to reject or authorize OAuth tokens in your environment. For more information, see OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards..WebSEAL-specific ACL policiesHigh level overview of the OAuth EASConfiguring WebSEAL to include OAuth decisionsError responsesTroubleshootingThe EAS provides trace information through the standard Security Access Manager tracing mechanism.

Support for OAuth authorization decisions

OAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.

WebSEAL supports the EAS plug-in, which leverages OAuth 2.0 capabilities. This plug-in allows OAuth decisions to be made as a part of the standard authorization on WebSEAL requests. This functionality uses the authorization server of the Advanced Access Control Module to reject or authorize OAuth tokens in your environment. For more information, see OAuth 2.0 support.

High level overview of the OAuth EAS

Configuring WebSEAL to include OAuth decisions

Error responses

Troubleshooting
The EAS provides trace information through the standard Security Access Manager tracing mechanism.

Parent topic: WebSEAL-specific ACL policies

High level overview of the OAuth EASHigh level overview of the OAuth EASOAuthEASoverviewEASOAuthAt a high level, the EAS framework allows a custom module to be called during an authorization decision to add customized decision making logic to the authorization decision. The configuration of the EAS controls whether the module is invoked when a specific POP is encountered, or whether it is invoked when a specific permission bit is applied to the authorization decision. Logical flow of the OAuth EASFlowchart representing the logical flow of OAuth authorization decisionsFigure 1 shows the logical flow through the OAuth EAS when making an authorization decision. The following steps outline this authorization process:The OAuth EAS receives the authorization request.The OAuth EAS determines whether the required OAuth data is present.If there is missing OAuth data, then a 401 response is generated and no further processing takes place. If the required OAuth data is available, then proceed to the next step.EAS verifies that all required data is available in the request. If there is missing data, then a 400 response is generated and no further processing takes place. If all of the data is available, then the EAS constructs a Request Security Token (RST) and sends it to the authorization server, which is part of the Advanced Access Control Module.The authorization server processes the request. If the processing fails, then a 502 response is generated and no further processing takes place. Otherwise, the authorization server returns the access decision to the OAuth EAS.If the request is authorized, then access is granted to the requested resource. If the request is not authorized, then a 401 response is generated. Support for OAuth authorization decisionsOAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.

High level overview of the OAuth EAS

At a high level, the EAS framework allows a custom module to be called during an authorization decision to add customized decision making logic to the authorization decision. The configuration of the EAS controls whether the module is invoked when a specific POP is encountered, or whether it is invoked when a specific permission bit is applied to the authorization decision.

Figure 25. Logical flow of the OAuth EAS

Figure 25. shows the logical flow through the OAuth EAS when making an authorization decision. The following steps outline this authorization process:

The OAuth EAS receives the authorization request.

The OAuth EAS determines whether the required OAuth data is present.

If there is missing OAuth data, then a 401 response is generated and no further processing takes place. If the required OAuth data is available, then proceed to the next step.

EAS verifies that all required data is available in the request.

If there is missing data, then a 400 response is generated and no further processing takes place. If all of the data is available, then the EAS constructs a Request Security Token (RST) and sends it to the authorization server, which is part of the Advanced Access Control Module.

The authorization server processes the request. If the processing fails, then a 502 response is generated and no further processing takes place. Otherwise, the authorization server returns the access decision to the OAuth EAS.

If the request is authorized, then access is granted to the requested resource. If the request is not authorized, then a 401 response is generated.

Parent topic: Support for OAuth authorization decisions

Configuring WebSEAL to include OAuth decisionsConfiguring WebSEAL to include OAuth decisionsWebSEALOAuthOAuthWebSEAL configuration decisionsTo make an OAuth authorization decision, the authorization server requires specific information regarding the request. The required data includes the following: Authorization data. This data is obtained from either the authorization header, the query string or the POST data.Resource information. This data is obtained from the HTTP request and is used to validate the OAuth signature. WebSEAL uses the EAS plug-in to provide this required data and to use the OAuth functionality in the Advanced Access Control Module. To include OAuth decisions as part of the standard authorization on WebSEAL requests, you need to perform the following tasks: Configure the required authorization decision data.Configure the extra EAS specific data.This configuration ensures that the correct data is passed to the EAS for each request. Support for OAuth authorization decisionsOAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.Authorization decision dataTo correctly construct the RST, the EAS requires various information from the request itself. WebSEAL must be configured to provide this information to the EAS.EAS specific dataThe EAS requires specific configuration data to function correctly. This data is mostly contained in the [oauth] and [oauth-eas] stanzas.

Configuring WebSEAL to include OAuth decisions

To make an OAuth authorization decision, the authorization server requires specific information regarding the request. The required data includes the following:

Authorization data. This data is obtained from either the authorization header, the query string or the POST data.

Resource information. This data is obtained from the HTTP request and is used to validate the OAuth signature.

WebSEAL uses the EAS plug-in to provide this required data and to use the OAuth functionality in the Advanced Access Control Module.

To include OAuth decisions as part of the standard authorization on WebSEAL requests, you need to perform the following tasks:

Configure the required authorization decision data.

Configure the extra EAS specific data.

This configuration ensures that the correct data is passed to the EAS for each request.

Authorization decision data
To correctly construct the RST, the EAS requires various information from the request itself. WebSEAL must be configured to provide this information to the EAS.

EAS specific data
The EAS requires specific configuration data to function correctly. This data is mostly contained in the [oauth] and [oauth-eas] stanzas.

Parent topic: Support for OAuth authorization decisions

Authorization decision dataAuthorization decision dataWebSEAL authorization decision data in IBM Security Access Manager for WebTo correctly construct the RST, the EAS requires various information from the request itself. WebSEAL must be configured to provide this information to the EAS.authorizationdecision informationThe majority of the required data is provided on every authorization request by specifying these HTTP request elements in the [azn-decision-info] stanza. See Authorization decision information from HTTP requestsWebSEAL can pass configured elements from the HTTP request to the authorization framework for use when it is making authorization decisions..In certain situations, the POST data is also required. For efficiency, the EAS plug-in does not provide the POST data on every authorization decision request. Instead, the plug-in uses the existing dynamic access decision information within WebSEAL to optionally request the POST data when required. WebSEAL recognizes the request for POST data based on the resource-manager-provided-adi configuration entry in the [aznapi-configuration] stanza.It is vital that this configuration stanza is correct so that the data is passed to the EAS. The following configuration entries are required in order for the EAS to function correctly:[azn-decision-info] # # The following information will be provided to the authorization # framework for every authorization request. This information # is required by the OAuth EAS when validating an OAuth token. # HTTP_REQUEST_METHOD = method HTTP_REQUEST_SCHEME = scheme HTTP_REQUEST_URI = uri HTTP_HOST_HDR = header:host HTTP_CONTENT_TYPE_HDR = header:content-type HTTP_TRANSFER_ENCODING_HDR = header:transfer-encoding HTTP_AZN_HDR = header:authorization [aznapi-configuration] resource-manager-provided-adi = AMWS_pb_Configuring WebSEAL to include OAuth decisions

Authorization decision data

To correctly construct the RST, the EAS requires various information from the request itself. WebSEAL must be configured to provide this information to the EAS.

The majority of the required data is provided on every authorization request by specifying these HTTP request elements in the [azn-decision-info] stanza. See Authorization decision information from HTTP requests.

Note: In certain situations, the POST data is also required. For efficiency, the EAS plug-in does not provide the POST data on every authorization decision request. Instead, the plug-in uses the existing dynamic access decision information within WebSEAL to optionally request the POST data when required. WebSEAL recognizes the request for POST data based on the resource-manager-provided-adi configuration entry in the [aznapi-configuration] stanza.

It is vital that this configuration stanza is correct so that the data is passed to the EAS. The following configuration entries are required in order for the EAS to function correctly:

[azn-decision-info]

#
# The following information will be provided to the authorization
# framework for every authorization request.  This information
# is required by the OAuth EAS when validating an OAuth token.
#

HTTP_REQUEST_METHOD        = method
HTTP_REQUEST_SCHEME        = scheme
HTTP_REQUEST_URI           = uri
HTTP_HOST_HDR              = header:host
HTTP_CONTENT_TYPE_HDR      = header:content-type
HTTP_TRANSFER_ENCODING_HDR = header:transfer-encoding
HTTP_AZN_HDR               = header:authorization

[aznapi-configuration]

resource-manager-provided-adi = AMWS_pb_

Parent topic: Configuring WebSEAL to include OAuth decisions

EAS specific dataEAS specific dataEAS specific data in IBM Security Access Manager for WebThe EAS requires specific configuration data to function correctly. This data is mostly contained in the [oauth] and [oauth-eas] stanzas. WebSEALoauth_eas.conf.templateoauth stanzaOne of the required configuration entries in the [oauth] stanza is cluster-name, which specifies the name of the authorization server. You must configure a corresponding [tfim-cluster:<cluster>] stanza to define the specified cluster.The following excerpt provides an example of the required stanzas:[oauth] # This stanza contains definitions for OAuth specific information. # .... [tfim-cluster:oauth-cluster] # # This stanza contains definitions for the cluster of authorization # servers that hosts the OAuth service. # # ....For details of the required configuration entries for each of these stanzas, see the [aznapi-external-authzn-services] stanzaUse the [aznapi-external-authzn-services] stanza to configure the OAuth External Authorization Service (EAS). , [oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings., and [oauth-eas] stanza documentation in the Web Reverse Proxy Stanza Reference topics.Configuring WebSEAL to include OAuth decisions

EAS specific data

The EAS requires specific configuration data to function correctly. This data is mostly contained in the [oauth] and [oauth-eas] stanzas.

One of the required configuration entries in the [oauth] stanza is cluster-name, which specifies the name of the authorization server. You must configure a corresponding [tfim-cluster:<cluster>] stanza to define the specified cluster.

The following excerpt provides an example of the required stanzas:

[oauth]

# This stanza contains definitions for OAuth specific information.

# ....

[tfim-cluster:oauth-cluster]

#
# This stanza contains definitions for the cluster of authorization
# servers that hosts the OAuth service.
#

# ....

For details of the required configuration entries for each of these stanzas, see the [aznapi-external-authzn-services] stanza, [oauth] stanza, and [oauth-eas] stanza documentation in the Web Reverse Proxy Stanza Reference topics.

Parent topic: Configuring WebSEAL to include OAuth decisions

Error responsesError responsesError responses in IBM Security Access Manager for WebOAuthEASerror responseserror responsesHTTPIn some circumstances HTTP error responses need to be returned to the client including: 400 Bad Request401 Unauthorized502 Bad GatewayIn the case of a 401 response, an additional WWW-Authenticate header is added to the response in the following format: WWW-Authenticate: OAuth realm = <realm-name>The HTML component of the responses are pre-loaded from files that have been specified in the EAS configuration. Namely the [bad-request-rsp-file],[unauthorized-rsp-file] and [bad-gateway-rsp-file] configuration entries in the [oauth-eas] stanza. For more information about the [oauth-eas] stanza, see the Web Reverse Proxy Stanza Reference topics.Support for OAuth authorization decisionsOAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.

Error responses

In some circumstances HTTP error responses need to be returned to the client including:

400 Bad Request

401 Unauthorized

502 Bad Gateway

In the case of a 401 response, an additional WWW-Authenticate header is added to the response in the following format:

WWW-Authenticate: OAuth realm = <realm-name>

The HTML component of the responses are pre-loaded from files that have been specified in the EAS configuration. Namely the [bad-request-rsp-file],[unauthorized-rsp-file] and [bad-gateway-rsp-file] configuration entries in the [oauth-eas] stanza. For more information about the [oauth-eas] stanza, see the Web Reverse Proxy Stanza Reference topics.

Parent topic: Support for OAuth authorization decisions

TroubleshootingTroubleshootingTroubleshooting EAS in IBM Security Access Manager for WebThe EAS provides trace information through the standard Security Access Manager tracing mechanism.server task commandstraceEAStrace informationSecurity Access Managertrace mechanismoauth-eas stanzaThis mechanism is controlled using the Security Access Manager server task command: trace. You can use the trace-component configuration entry within the [oauth-eas] stanza to specify the name of the of the trace component that is associated with the EAS.Support for OAuth authorization decisionsOAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end user). It also provides a process for end-users to authorize third party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.

Troubleshooting

The EAS provides trace information through the standard Security Access Manager tracing mechanism.

This mechanism is controlled using the Security Access Manager server task command: trace. You can use the trace-component configuration entry within the [oauth-eas] stanza to specify the name of the of the trace component that is associated with the EAS.

Parent topic: Support for OAuth authorization decisions

Key managementKey managementkey managementoverviewThis chapter contains information that describes tasks you can perform to manage certificate handling by the WebSEAL server. Topic Index:AuthorizationKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Key management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Client-side and server-side certificate conceptsConfiguration of the WebSEAL key database fileCertificate revocation in WebSEALCRL distribution pointsConfiguration of the CRL cacheUse of the WebSEAL test certificate for SSL connections

Key management

This chapter contains information that describes tasks you can perform to manage certificate handling by the WebSEAL server.

Topic Index:

Key management overview
The LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.

Key management in the Local Management Interface
You can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:

Client-side and server-side certificate concepts

Configuration of the WebSEAL key database file

Certificate revocation in WebSEAL

CRL distribution points

Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

Parent topic: Authorization

Key management overviewKey management overviewKey management configuration for SSL communication between WebSEAL and other Security Access Manager componentsThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.key managementoverviewYou can use the LMI to create key database files and manage the digital certificates that are stored in these key database files.Figure 1 summarizes the key management configuration that WebSEAL uses for SSL communication with other components of the Security Access Manager environment. The configuration stanzas and stanza entries are in the WebSEAL configuration file. Keyfile management configurationKeyfile management configurationKey managementKey management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Client-side and server-side certificate conceptsConfiguration of the WebSEAL key database fileCertificate revocation in WebSEALCRL distribution pointsConfiguration of the CRL cacheUse of the WebSEAL test certificate for SSL connections

Key management overview

The LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.

You can use the LMI to create key database files and manage the digital certificates that are stored in these key database files.

Figure 26. summarizes the key management configuration that WebSEAL uses for SSL communication with other components of the Security Access Manager environment. The configuration stanzas and stanza entries are in the WebSEAL configuration file.

Figure 26. Keyfile management configuration

Parent topic: Key management

Related concepts:

Key management in the Local Management Interface

Client-side and server-side certificate concepts

Configuration of the WebSEAL key database file

Certificate revocation in WebSEAL

CRL distribution points

Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

Key management in the Local Management InterfaceKey management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:key managementLMISSL certificatescertificatesSSO keysLTPAkeysLMISSO Keys management pageLTPA Keys management pageSSL Certificates management pageSSL CertificatesUse the SSL Certificates management page to complete the following tasks:List or retrieve all current SSL certificate database names.Create a certificate database.Rename a certificate database.Describe a certificate database.Delete a certificate database.Import a certificate database.Export a certificate database.Manage signer certificates.Manage personal certificates.Manage certificate requests.SSO KeysUse the SSO Keys management page to complete the following tasks:List all current SSO key files.Create a new SSO key file.Import an existing SSO key file.Export an SSO key file.Delete an SSO key file.LTPA KeysUse the LTPA Keys management page to complete the following tasks:Retrieve all current LTPA key files.Rename an LTPA key file.Delete an LTPA key file.Export an LTPA key file.Import an LTPA key file.See the Appliance administration topics for detailed information about using the LMI to complete these key management tasks.Key managementKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Client-side and server-side certificate conceptsConfiguration of the WebSEAL key database fileCertificate revocation in WebSEALCRL distribution pointsConfiguration of the CRL cacheUse of the WebSEAL test certificate for SSL connections

Key management in the Local Management Interface

You can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:

SSL Certificates

Use the SSL Certificates management page to complete the following tasks:

List or retrieve all current SSL certificate database names.

Create a certificate database.

Rename a certificate database.

Describe a certificate database.

Delete a certificate database.

Import a certificate database.

Export a certificate database.

Manage signer certificates.

Manage personal certificates.

Manage certificate requests.

SSO Keys

Use the SSO Keys management page to complete the following tasks:

List all current SSO key files.

Create a new SSO key file.

Import an existing SSO key file.

Export an SSO key file.

Delete an SSO key file.

LTPA Keys

Use the LTPA Keys management page to complete the following tasks:

Retrieve all current LTPA key files.

Rename an LTPA key file.

Delete an LTPA key file.

Export an LTPA key file.

Import an LTPA key file.

See the Appliance administration topics for detailed information about using the LMI to complete these key management tasks.

Parent topic: Key management

Related concepts:

Key management overview

Client-side and server-side certificate concepts

Configuration of the WebSEAL key database file

Certificate revocation in WebSEAL

CRL distribution points

Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

Client-side and server-side certificate conceptsClient-side and server-side certificate conceptscertificatesmanagementiKeymanLMIGSKitkey managementmanaging client-side certificatesmanaging server-side certificatesGSKitclient-side conceptsserver-side certificate conceptsiKeymanclient-side conceptsserver-side certificate conceptsThis section describes the administration and configuration tasks required to set up WebSEAL to handle client-side and server-side digital certificates used for authentication over SSL.WebSEAL requires certificates for the following situations: WebSEAL identifies itself to SSL clients with its server-side certificateWebSEAL identifies itself to a junctioned back-end server (configured for mutual authentication) with a client-side certificateWebSEAL refers to its database of Certificate Authority (CA) root certificates to validate clients accessing with client-side certificatesWebSEAL refers to its database of Certificate Authority (CA) root certificates to validate junctioned back-end servers WebSEAL uses the IBM Global Security Kit (GSKit) implementation of SSL to configure and administer digital certificates. The appliance provides the LMI to set up and manage the certificate key database. This database contains one or more WebSEAL server/client certificates and the CA root certificates.WebSEAL includes the following components at installation to support SSL authentication using digital certificates: A default key database (pdsrv.kdb)A default key database stash file (pdsrv.sth) and password ("pdsrv")Several common CA root certificatesA self-signed test certificate that WebSEAL can use to identify itself to SSL clients Before using WebSEAL in a production environment, apply for a commonly recognized certificate from a known Certificate Authority to use instead of this test certificate.Key managementKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Key management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Configuration of the WebSEAL key database fileCertificate revocation in WebSEALCRL distribution pointsConfiguration of the CRL cacheUse of the WebSEAL test certificate for SSL connections

Client-side and server-side certificate concepts

This section describes the administration and configuration tasks required to set up WebSEAL to handle client-side and server-side digital certificates used for authentication over SSL.

WebSEAL requires certificates for the following situations:

WebSEAL identifies itself to SSL clients with its server-side certificate

WebSEAL identifies itself to a junctioned back-end server (configured for mutual authentication) with a client-side certificate

WebSEAL refers to its database of Certificate Authority (CA) root certificates to validate clients accessing with client-side certificates

WebSEAL refers to its database of Certificate Authority (CA) root certificates to validate junctioned back-end servers

WebSEAL uses the IBM® Global Security Kit (GSKit) implementation of SSL to configure and administer digital certificates. The appliance provides the LMI to set up and manage the certificate key database. This database contains one or more WebSEAL server/client certificates and the CA root certificates.

WebSEAL includes the following components at installation to support SSL authentication using digital certificates:

A default key database (pdsrv.kdb)

A default key database stash file (pdsrv.sth) and password ("pdsrv")

Several common CA root certificates

A self-signed test certificate that WebSEAL can use to identify itself to SSL clients

Before using WebSEAL in a production environment, apply for a commonly recognized certificate from a known Certificate Authority to use instead of this test certificate.

Parent topic: Key management

Related concepts:

Key management overview

Key management in the Local Management Interface

Configuration of the WebSEAL key database file

Certificate revocation in WebSEAL

CRL distribution points

Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

Configuration of the WebSEAL key database fileConfiguration of the WebSEAL key database filewebseal-cert-keyfile stanza entrywebseal-cert-keyfile-stash stanza entrywebseal-cert-keyfile-pwd stanza entrywebseal-cert-keyfile-label stanza entrywebseal-cert-keyfile-sni stanza entrykey managementconfiguring WebSEAL key database stanza entriesThis section contains the following topics:Key managementKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Key management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Client-side and server-side certificate conceptsCertificate revocation in WebSEALCRL distribution pointsConfiguration of the CRL cacheUse of the WebSEAL test certificate for SSL connectionsWebSEAL key database fileDuring installation, WebSEAL provides a default certificate key database that is used to authenticate both clients and junctioned servers. WebSEAL also provides an optional, separate certificate key database that can be used to authenticate junctioned servers.Key database file passwordWebSEAL provides a stash file that contains the password for the default certificate key database pdsrv.kdb.WebSEAL test certificateServer Name IndicationWebSEAL can use Server Name Indication to identify the host name in the request and send a server certificate that contains a matching host name. You can configure the certificate that WebSEAL uses for each host.

Configuration of the WebSEAL key database file

This section contains the following topics:

WebSEAL key database file
During installation, WebSEAL provides a default certificate key database that is used to authenticate both clients and junctioned servers. WebSEAL also provides an optional, separate certificate key database that can be used to authenticate junctioned servers.

Key database file password
WebSEAL provides a stash file that contains the password for the default certificate key database pdsrv.kdb.

WebSEAL test certificate

Server Name Indication
WebSEAL can use Server Name Indication to identify the host name in the request and send a server certificate that contains a matching host name. You can configure the certificate that WebSEAL uses for each host.

Parent topic: Key management

Related concepts:

Key management overview

Key management in the Local Management Interface

Client-side and server-side certificate concepts

Certificate revocation in WebSEAL

CRL distribution points

Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

WebSEAL key database fileWebSEAL key database fileWebSEAL key database file in IBM Security Access Manager for WebDuring installation, WebSEAL provides a default certificate key database that is used to authenticate both clients and junctioned servers. WebSEAL also provides an optional, separate certificate key database that can be used to authenticate junctioned servers.WebSEALkey database fileoverviewwebseal-cert-keyfile stanzaBy default, the junction certificate key database option is commented out in the WebSEAL configuration file. Unless this option is enabled, junctions maintain the default behavior of using a shared key database for clients and junctioned servers. When a separate certificate key database is used for junctioned servers, it is not possible for a user to use a client certificate that is validated by a CA certificate stored in the junction key database. Similarly, it is not possible for a junctioned server to use a certificate that is validated by a CA certificate contained in the default certificate database.The webseal-cert-keyfile stanza entry, located in the [ssl] stanza of the WebSEAL configuration file, identifies the default certificate key database. For example: [ssl] webseal-cert-keyfile = pdsrv.kdb The jct-cert-keyfile stanza entry in the [junction] stanza for the WebSEAL configuration file, identifies the optional, separate junction certificate key database. For example: [junction] jct-cert-keyfile = pdjct.kdbYou can use the SSL Certificates management page of the LMI to create a new key database. However, you must enter the name and location of this new key file in the webseal-cert-keyfile stanza entry so that WebSEAL can find and use the certificates contained in that database.Configuration of the WebSEAL key database file

WebSEAL key database file

During installation, WebSEAL provides a default certificate key database that is used to authenticate both clients and junctioned servers. WebSEAL also provides an optional, separate certificate key database that can be used to authenticate junctioned servers.

By default, the junction certificate key database option is commented out in the WebSEAL configuration file. Unless this option is enabled, junctions maintain the default behavior of using a shared key database for clients and junctioned servers.

Note: When a separate certificate key database is used for junctioned servers, it is not possible for a user to use a client certificate that is validated by a CA certificate stored in the junction key database. Similarly, it is not possible for a junctioned server to use a certificate that is validated by a CA certificate contained in the default certificate database.

The webseal-cert-keyfile stanza entry, located in the [ssl] stanza of the WebSEAL configuration file, identifies the default certificate key database. For example:

[ssl]
webseal-cert-keyfile = pdsrv.kdb

The jct-cert-keyfile stanza entry in the [junction] stanza for the WebSEAL configuration file, identifies the optional, separate junction certificate key database. For example:

[junction]
jct-cert-keyfile = pdjct.kdb

You can use the SSL Certificates management page of the LMI to create a new key database. However, you must enter the name and location of this new key file in the webseal-cert-keyfile stanza entry so that WebSEAL can find and use the certificates contained in that database.

Parent topic: Configuration of the WebSEAL key database file

Key database file passwordKey database file passwordKey database file password in WebSEALWebSEAL provides a stash file that contains the password for the default certificate key database pdsrv.kdb.WebSEALkey database filepassworddefault certificate key databasewebseal-cert-keyfile-pwd stanza The following stanza entry specifies the name of the stash file: [ssl] webseal-cert-keyfile-stash = pdsrv.sthThe default password encrypted in the pdsrv.sth stash file is pdsrv. During installation, WebSEAL uses the stash file to obtain the key file password. Configuration of the WebSEAL key database file

Key database file password

WebSEAL provides a stash file that contains the password for the default certificate key database pdsrv.kdb.

The following stanza entry specifies the name of the stash file:

[ssl]
webseal-cert-keyfile-stash = pdsrv.sth

The default password encrypted in the pdsrv.sth stash file is pdsrv.

During installation, WebSEAL uses the stash file to obtain the key file password.

Parent topic: Configuration of the WebSEAL key database file

WebSEAL test certificateWebSEAL test certificateiKeymanWebSEAL test certificateWebSEALtest certificateDuring installation, WebSEAL provides a non-secure self-signed test certificate. The test certificate, acting as a server-side certificate, allows WebSEAL to identify itself to SSL clients. To better control how this test certificate is used, the certificate is not installed as a default certificate. Instead, the webseal-cert-keyfile-label stanza entry designates the certificate as the active server-side certificate and overrides any other certificate designated as "default" in the keyfile database. [ssl] webseal-cert-keyfile-label = WebSEAL-Test-Only WebSEAL uses GSKit certificate handling functionality. GSKit allows but does not require that a certificate in keyfile databases be designated the default certificate. Although this test certificate allows WebSEAL to respond to an SSL-enabled browser request, it cannot be verified by the browser (which does not contain an appropriate root CA certificate). Because the private key for this default certificate is contained in every WebSEAL distribution, this certificate offers no true secure communication. You can use the LMI to generate a certificate request that can be sent to a Certificate Authority (CA). Use the LMI to install and label the returned server certificate.If you use different certificates for other scenarios (such as –K junctions), you can use the LMI to create, install, and label these certificates. The keyfile label must not contain spaces.WebSEAL (which by default runs as user ivmgr) must have read (r) permission on these key database files. Configuration of the WebSEAL key database file

WebSEAL test certificate

During installation, WebSEAL provides a non-secure self-signed test certificate. The test certificate, acting as a server-side certificate, allows WebSEAL to identify itself to SSL clients.

To better control how this test certificate is used, the certificate is not installed as a default certificate. Instead, the webseal-cert-keyfile-label stanza entry designates the certificate as the active server-side certificate and overrides any other certificate designated as "default" in the keyfile database.

[ssl]
webseal-cert-keyfile-label = WebSEAL-Test-Only

Note: WebSEAL uses GSKit certificate handling functionality. GSKit allows but does not require that a certificate in keyfile databases be designated the default certificate.

Although this test certificate allows WebSEAL to respond to an SSL-enabled browser request, it cannot be verified by the browser (which does not contain an appropriate root CA certificate). Because the private key for this default certificate is contained in every WebSEAL distribution, this certificate offers no true secure communication.

You can use the LMI to generate a certificate request that can be sent to a Certificate Authority (CA). Use the LMI to install and label the returned server certificate.

If you use different certificates for other scenarios (such as –K junctions), you can use the LMI to create, install, and label these certificates. The keyfile label must not contain spaces.

WebSEAL (which by default runs as user ivmgr) must have read (r) permission on these key database files.

Parent topic: Configuration of the WebSEAL key database file

Server Name IndicationServer Name IndicationConfigure WebSEAL to use Server Name Indication to send a separate certificate to each hostWebSEAL can use Server Name Indication to identify the host name in the request and send a server certificate that contains a matching host name. You can configure the certificate that WebSEAL uses for each host. Server Name IndicationWebSEALkey database fileServer Name Indicationwebseal-cert-keyfile-sni stanza entryServer Name Indication is an extension to the SSL and TLS protocols. Server Name Indication identifies the host name to which the browser is requesting a connection.By default, WebSEAL sends the same certificate to all hosts. However, by using Server Name Indication, WebSEAL can send a different certificate for each requested host.To support Server Name Indication, the request must meet the following requirements: Use TLS over SSL to connect to WebSEAL. SSLv2 and SSLv3 are not supported.Use a browser that supports Server Name Indication.Use the webseal-cert-keyfile-sni configuration entry in the [ssl] stanza of the WebSEAL configuration file to specify the certificate that WebSEAL sends for a particular host name. For example:[ssl] webseal-cert-keyfile-sni = <host_name>:<label>where:<host_name>The name of the host to which WebSEAL returns the certificate.<label>The name of the certificate for WebSEAL to use.Specify the certificate that contains a dn value of cn=<host_name>.You can specify this configuration entry multiple times. Specify a separate entry for each server certificate.If WebSEAL does not find an entry for the host name in the browser request, WebSEAL sends the default certificate that is specified by the webseal-cert-keyfile-label entry. WebSEAL also uses the default certificate if the request does not meet the Server Name Indication requirements. For example, if the browser does not support Server Name Indication. If you do not configure webseal-cert-keyfile-sni entries, WebSEAL can send only a single certificate, which means that WebSEAL cannot differentiate between different hosts. A certificate mismatch error results in the browser when a user uses SSL to connect to a host that does not match the default certificate.Server Name Indication solves this problem. Use the webseal-cert-keyfile-sni to configure WebSEAL to provide a matching certificate for each host name. Configuration of the WebSEAL key database file

Server Name Indication

WebSEAL can use Server Name Indication to identify the host name in the request and send a server certificate that contains a matching host name. You can configure the certificate that WebSEAL uses for each host.

Server Name Indication is an extension to the SSL and TLS protocols. Server Name Indication identifies the host name to which the browser is requesting a connection.

By default, WebSEAL sends the same certificate to all hosts. However, by using Server Name Indication, WebSEAL can send a different certificate for each requested host.

To support Server Name Indication, the request must meet the following requirements:

Use TLS over SSL to connect to WebSEAL. SSLv2 and SSLv3 are not supported.

Use a browser that supports Server Name Indication.

Use the webseal-cert-keyfile-sni configuration entry in the [ssl] stanza of the WebSEAL configuration file to specify the certificate that WebSEAL sends for a particular host name. For example:

[ssl]
webseal-cert-keyfile-sni = <host_name>:<label>

where:

<host_name>

The name of the host to which WebSEAL returns the certificate.

<label>

The name of the certificate for WebSEAL to use.

Note: Specify the certificate that contains a dn value of cn=<host_name>.

You can specify this configuration entry multiple times. Specify a separate entry for each server certificate.

If WebSEAL does not find an entry for the host name in the browser request, WebSEAL sends the default certificate that is specified by the webseal-cert-keyfile-label entry. WebSEAL also uses the default certificate if the request does not meet the Server Name Indication requirements. For example, if the browser does not support Server Name Indication.

If you do not configure webseal-cert-keyfile-sni entries, WebSEAL can send only a single certificate, which means that WebSEAL cannot differentiate between different hosts. A certificate mismatch error results in the browser when a user uses SSL to connect to a host that does not match the default certificate.

Server Name Indication solves this problem. Use the webseal-cert-keyfile-sni to configure WebSEAL to provide a matching certificate for each host name.

Parent topic: Configuration of the WebSEAL key database file

Certificate revocation in WebSEALCertificate revocation in WebSEALcertificate revocationWebSEALWebSEALcertificate revocationCertificates can be revoked for various reasons. Before using a certificate, WebSEAL must check an up-to-date source to ensure that it is valid.Key managementKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Key management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Client-side and server-side certificate conceptsConfiguration of the WebSEAL key database fileCRL distribution pointsConfiguration of the CRL cacheUse of the WebSEAL test certificate for SSL connectionsCertificate revocation list (CRL)Configuration of CRL checking

Certificate revocation in WebSEAL

Certificates can be revoked for various reasons. Before using a certificate, WebSEAL must check an up-to-date source to ensure that it is valid.

Certificate revocation list (CRL)

Configuration of CRL checking

Parent topic: Key management

Related concepts:

Key management overview

Key management in the Local Management Interface

Client-side and server-side certificate concepts

Configuration of the WebSEAL key database file

CRL distribution points

Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

Certificate revocation list (CRL)Certificate revocation listscertificate revocationlistoverviewCRLoverviewThe certificate revocation list (CRL) is a method of preventing the validation of unwanted certificates. The CRL contains the identities of certificates that are deemed untrustworthy. WebSEAL uses a GSKit implementation of SSL that supports CRL checking. WebSEAL can use GSKit to perform CRL checking on client-side certificates and certificates from SSL junctions.A certificate authority (CA) provides a CRL that is valid for a limited amount of time. The CA specifies the lifetime validity of the CRL. The CA is responsible for maintaining this information. Contact the CA to find out their policies for updating the CRL.You can configure WebSEAL to use OCSP, CRL, or both for managing certificates. By default, WebSEAL (using GSKit) tries OCSP first, followed by CRL. If these first two methods fail, WebSEAL can then try LDAP (if configured). This search order is defined by an RFC and cannot be changed. WebSEAL must be able to connect to the CRL Distribution Point (CDP) as specified by the CA in the certificate. If WebSEAL is installed on a server behind a firewall, you must allow communication through to the CDP. Otherwise, performance could be affected and you risk certificates being validated against an out of date CRL.There is no time limitation for using an outdated CRL. However, allowing the use of an outdated CRL creates security exposures. If GSKit determines that the CRL is out of date, it returns an UNDETERMINED status message. The application can then decide the best course of action. You can configure the course of action in WebSEAL by setting the configuration option undetermined-revocation-cert-action in the [ssl] stanza to one of: ignore, log, or reject. Certificate revocation in WebSEAL

Certificate revocation list (CRL)

The certificate revocation list (CRL) is a method of preventing the validation of unwanted certificates. The CRL contains the identities of certificates that are deemed untrustworthy. WebSEAL uses a GSKit implementation of SSL that supports CRL checking. WebSEAL can use GSKit to perform CRL checking on client-side certificates and certificates from SSL junctions.

A certificate authority (CA) provides a CRL that is valid for a limited amount of time. The CA specifies the lifetime validity of the CRL. The CA is responsible for maintaining this information. Contact the CA to find out their policies for updating the CRL.

You can configure WebSEAL to use OCSP, CRL, or both for managing certificates. By default, WebSEAL (using GSKit) tries OCSP first, followed by CRL. If these first two methods fail, WebSEAL can then try LDAP (if configured). This search order is defined by an RFC and cannot be changed.

WebSEAL must be able to connect to the CRL Distribution Point (CDP) as specified by the CA in the certificate. If WebSEAL is installed on a server behind a firewall, you must allow communication through to the CDP. Otherwise, performance could be affected and you risk certificates being validated against an out of date CRL.

There is no time limitation for using an outdated CRL. However, allowing the use of an outdated CRL creates security exposures. If GSKit determines that the CRL is out of date, it returns an UNDETERMINED status message. The application can then decide the best course of action. You can configure the course of action in WebSEAL by setting the configuration option undetermined-revocation-cert-action in the [ssl] stanza to one of: ignore, log, or reject.

Parent topic: Certificate revocation in WebSEAL

Configuration of CRL checking Configuration of CRL checking CRLcheckingkey managementconfigure CRL checkingcertificate revocationlistconfiguring CRL checkingcrl-ldap-server stanza entryssl stanzajunction stanzacrl-ldap-server-port stanza entryssl stanzajunction stanzacrl-ldap-user stanza entryssl stanzajunction stanzacrl-ldap-user-password stanza entryssl stanzajunction stanzaWebSEAL must know the location of the CRL list in order to perform CRL checking. Stanza entries for the location of the LDAP server that can be referenced for CRL checking during client-side certificate authentication are found in the [ssl] stanza of the WebSEAL configuration file: [ssl] #crl-ldap-server = server-name #crl-ldap-server-port = port-id #crl-ldap-user = webseal-admin-name #crl-ldap-user-password = admin-passwordStanza entries for the location of the LDAP server that can be referenced for CRL checking during authentication across SSL junctions are found in the [junction] stanza of the WebSEAL configuration file: [junction] #crl-ldap-server = server-name #crl-ldap-server-port = port-id #crl-ldap-user = webseal-admin-name #crl-ldap-user-password = admin-passwordBy default, CRL checking is disabled (stanza entries are commented out). To enable CRL checking during certificate authentication, uncomment each stanza entry and enter the appropriate values.A null value for the crl-ldap-user stanza entry indicates that the SSL authentication mechanism should bind to the LDAP server as an anonymous user. Certificate revocation in WebSEAL

Configuration of CRL checking

WebSEAL must know the location of the CRL list in order to perform CRL checking. Stanza entries for the location of the LDAP server that can be referenced for CRL checking during client-side certificate authentication are found in the [ssl] stanza of the WebSEAL configuration file:

[ssl]
#crl-ldap-server = server-name
#crl-ldap-server-port = port-id
#crl-ldap-user = webseal-admin-name
#crl-ldap-user-password = admin-password

Stanza entries for the location of the LDAP server that can be referenced for CRL checking during authentication across SSL junctions are found in the [junction] stanza of the WebSEAL configuration file:

[junction]
#crl-ldap-server = server-name
#crl-ldap-server-port = port-id
#crl-ldap-user = webseal-admin-name
#crl-ldap-user-password = admin-password

By default, CRL checking is disabled (stanza entries are commented out). To enable CRL checking during certificate authentication, uncomment each stanza entry and enter the appropriate values.

A null value for the crl-ldap-user stanza entry indicates that the SSL authentication mechanism should bind to the LDAP server as an anonymous user.

Parent topic: Certificate revocation in WebSEAL

CRL distribution pointsCRL distribution pointsCRLdistribution pointsdistribution pointsA CA specifies in the certificate where you can obtain revocation information. These details are not provided by WebSEAL or the GSKit library.Although rare, a certificate can have more than one CDP. The primary reason for more than one CDP is to offer different protocols such as LDAP and HTTP. If a certificate is configured with more one CDP, WebSEAL contacts each CDP until a valid result is returned.You can use Certificates from different CAs. Each CRL is signed by each CA so they cannot be confused. Each certificate contains its own CDP.Key managementKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Key management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Client-side and server-side certificate conceptsConfiguration of the WebSEAL key database fileCertificate revocation in WebSEALConfiguration of the CRL cacheUse of the WebSEAL test certificate for SSL connections

CRL distribution points

A CA specifies in the certificate where you can obtain revocation information. These details are not provided by WebSEAL or the GSKit library.

Although rare, a certificate can have more than one CDP. The primary reason for more than one CDP is to offer different protocols such as LDAP and HTTP. If a certificate is configured with more one CDP, WebSEAL contacts each CDP until a valid result is returned.

You can use Certificates from different CAs. Each CRL is signed by each CA so they cannot be confused. Each certificate contains its own CDP.

Parent topic: Key management

Related concepts:

Key management overview

Key management in the Local Management Interface

Client-side and server-side certificate concepts

Configuration of the WebSEAL key database file

Certificate revocation in WebSEAL

Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

Configuration of the CRL cache Configuration of the CRL cache CRLcacheconfigurationGSKitCRL cachekey managementconfiguring the CRL cachecertificate revocationlistconfiguring CRL cacheGSKit allows WebSEAL to perform CRL checking on client-side certificates and certificates from SSL junctions. To improve CRL checking performance, you can cache the CRL from a particular Certificate Authority (CA). Subsequent CRL checks are made against this cached version of the list.The settings for the two configuration file stanza entries discussed in this section are passed directly to the GSKit utility. For further information about GSKit functionality, refer to the GSKit documentation.Key managementKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Key management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Client-side and server-side certificate conceptsConfiguration of the WebSEAL key database fileCertificate revocation in WebSEALCRL distribution pointsUse of the WebSEAL test certificate for SSL connectionsSet the maximum number of cache entriesSet the GSKit cache lifetime timeout valueEnable the CRL cache

Configuration of the CRL cache

GSKit allows WebSEAL to perform CRL checking on client-side certificates and certificates from SSL junctions. To improve CRL checking performance, you can cache the CRL from a particular Certificate Authority (CA). Subsequent CRL checks are made against this cached version of the list.

The settings for the two configuration file stanza entries discussed in this section are passed directly to the GSKit utility. For further information about GSKit functionality, refer to the GSKit documentation.

Set the maximum number of cache entries

Set the GSKit cache lifetime timeout value

Enable the CRL cache

Parent topic: Key management

Related concepts:

Key management overview

Key management in the Local Management Interface

Client-side and server-side certificate concepts

Configuration of the WebSEAL key database file

Certificate revocation in WebSEAL

CRL distribution points

Use of the WebSEAL test certificate for SSL connections

Set the maximum number of cache entries Set the maximum number of cache entries gsk-cerl-cache-size stanza entryCRLcacheconfigurationgsk-crl-cache-sizeThe gsk-crl-cache-size stanza entry specifies the maximum number of entries in the GSKit CRL cache. Each entry represents an entire CRL for a particular certificate authority. The default setting is "0". A value greater than "0" is required to activate the cache. CRL entries can use a large amount of memory. Therefore, try to specify the minimal value for the gsk-crl-cache-size.[ssl] gsk-crl-cache-size = 0 Configuration of the CRL cache

Set the maximum number of cache entries

The gsk-crl-cache-size stanza entry specifies the maximum number of entries in the GSKit CRL cache. Each entry represents an entire CRL for a particular certificate authority. The default setting is "0". A value greater than "0" is required to activate the cache.

Note: CRL entries can use a large amount of memory. Therefore, try to specify the minimal value for the gsk-crl-cache-size.

[ssl]
gsk-crl-cache-size = 0

Parent topic: Configuration of the CRL cache

Set the GSKit cache lifetime timeout value Set the GSKit cache lifetime timeout value gsk-crl-cache-entry-lifetime stanzaCRLcachegsl-crl-cache-entry-lifetimeThe gsk-crl-cache-entry-lifetime stanza entry specifies the lifetime timeout value for all entries in the GSKit CRL cache. The value is expressed in seconds and can have a range of 0-86400 seconds. The default value is 0. There is no maximum limit imposed by either WebSEAL or GSKit, but the value must be contained in a 64-bit integer. [ssl] gsk-crl-cache-entry-lifetime = 0 Configuration of the CRL cache

Set the GSKit cache lifetime timeout value

The gsk-crl-cache-entry-lifetime stanza entry specifies the lifetime timeout value for all entries in the GSKit CRL cache. The value is expressed in seconds and can have a range of 0-86400 seconds. The default value is 0.

Note: There is no maximum limit imposed by either WebSEAL or GSKit, but the value must be contained in a 64-bit integer.

[ssl]
gsk-crl-cache-entry-lifetime = 0

Parent topic: Configuration of the CRL cache

Enable the CRL cacheEnable the CRL cachegsk-crl-cache-sizeCRLcachegsk-crl-cache-sizeWhen the gsk-crl-cache-size and gsk-crl-cache-entry-lifetime stanza entries are both set to "0" (default), CRL caching is disabled.To enable the cache, change the setting for either or both of the gsk-crl-cache-size and gsk-crl-cache-entry-lifetime to a value other than zero. If both values are zero, the cache is disabled. The cache is enabled if one or both of these stanza entries has a non-zero value configured.If either configuration entry has a value of 0 while the other is non-zero, GSKit automatically assigns a default value to the entry with the zero value. GSKit uses the following process:If gsk-crl-cache-entry-lifetime is configured with a non-zero value, but gsk-crl-cache-size is configured as 0 then the CRL cache is enabled. In this case, GSKit uses the following default value for the gsk-crl-cache-size: gsk-crl-cache-size = 50If gsk-crl-cache-size is configured with a non-zero value, but gsk-crl-cache-entry-lifetime is configured as 0 then the CRL cache is enabled. In this case, GSKit uses the following default value for the gsk-crl-cache-entry-lifetime: gsk-crl-cache-entry-lifetime = 43200If the CDP in the certificate specifies an HTTP source for the CRL then WebSEAL does not use the gsk-crl-cache-size and gsk-crl-cache-entry-lifetime configuration settings. CRLs from HTTP sources are never cached. If OCSP is not an option and a large CRL must be read using HTTP, you can use the GSKit environment variable GSK_HTTP_CDP_MAX_RESPONSE_SIZE.Configuration of the CRL cache

Enable the CRL cache

When the gsk-crl-cache-size and gsk-crl-cache-entry-lifetime stanza entries are both set to "0" (default), CRL caching is disabled.

To enable the cache, change the setting for either or both of the gsk-crl-cache-size and gsk-crl-cache-entry-lifetime to a value other than zero. If both values are zero, the cache is disabled. The cache is enabled if one or both of these stanza entries has a non-zero value configured.

If either configuration entry has a value of 0 while the other is non-zero, GSKit automatically assigns a default value to the entry with the zero value. GSKit uses the following process:

If gsk-crl-cache-entry-lifetime is configured with a non-zero value, but gsk-crl-cache-size is configured as 0 then the CRL cache is enabled. In this case, GSKit uses the following default value for the gsk-crl-cache-size:

gsk-crl-cache-size = 50

If gsk-crl-cache-size is configured with a non-zero value, but gsk-crl-cache-entry-lifetime is configured as 0 then the CRL cache is enabled. In this case, GSKit uses the following default value for the gsk-crl-cache-entry-lifetime:

gsk-crl-cache-entry-lifetime = 43200

If the CDP in the certificate specifies an HTTP source for the CRL then WebSEAL does not use the gsk-crl-cache-size and gsk-crl-cache-entry-lifetime configuration settings. CRLs from HTTP sources are never cached. If OCSP is not an option and a large CRL must be read using HTTP, you can use the GSKit environment variable GSK_HTTP_CDP_MAX_RESPONSE_SIZE.

Parent topic: Configuration of the CRL cache

Use of the WebSEAL test certificate for SSL connectionsUse of the WebSEAL test certificate for SSL connectionsiKeymanWebSEAL test certificatetest certificatecertificatesWebSEAL test certificatewebseal-cert-keyfile-labelcrl-ldap-server stanza entryssl stanzacrl-ldap-server-port stanza entryssl stanzacrl-ldap-user stanza entryssl stanzacrl-ldap-user-password stanza entryssl stanzagsk-crl-cache-size stanza entrygsk-crl-cache-entry-lifetime stanza entryClient-side certificate authentication must take place over a Secure Socket Layer (SSL) connection. The SSL connection is established prior to the certificate authentication process. The SSL connection can be established when a client attempts to access a resource over HTTPS. When the resource does not require authenticated access, the client negotiates an SSL session with the WebSEAL server. The SSL session is established when the client and server (WebSEAL) examine each other's certificate and accept the validity of the signing authority.In order to enable the establishment of SSL sessions on a new WebSEAL server, WebSEAL contains a self-signed test server certificate. WebSEAL can present the self-signed certificate to the client. If the client accepts the certificate, the SSL session is established.This test certificate is not suitable for permanent use by the WebSEAL server. Although this test certificate allows WebSEAL to respond to an SSL-enabled browser request, it cannot be verified by the browser. This is because the browser does not contain an appropriate root Certificate Authority (CA) certificate — as is the case for when the browser receives any self-signed certificate for which a root CA certificate does not exist. Because the private key for this default certificate is contained in every WebSEAL distribution, this certificate offers no true secure communication. To ensure secure communication over SSL, WebSEAL administrators must obtain a unique site server certificate from a trusted Certificate Authority (CA). You can use the LMI to generate a certificate request that is sent to the CA. You can also use the LMI to install and label the new site certificate.Use the webseal-cert-keyfile-label stanza entry in the [ssl] stanza of the WebSEAL configuration file to designate the certificate as the active WebSEAL server-side certificate (this setting overrides any certificate designated as “default” in the keyfile database).If you require different certificates for other scenarios (such as for mutually authenticated junctions), you can use the LMI to create, install, and label these additional certificates. See Configuration of the WebSEAL key database file.It is also important to ensure that validation of certificates includes checking of Certificate Revocation Lists (CRLs). Configure WebSEAL to access the appropriate LDAP server as an LDAP user with sufficient permission to access the appropriate CRLs. Supply values for the following configuration file entries:[ssl] crl-ldap-server crl-ldap-server-port crl-ldap-user crl-ldap-user-passwordWebSEAL can be configured to cache CRLs. To configure the cache, supply values for the following configuration file entries:[ssl] gsk-crl-cache-size gsk-crl-cache-entry-lifetimeInstructions for setting values that affect CRL access and handling, including valid ranges for cache settings, are in the Web Reverse Proxy Stanza Reference topics. See also Configuration of the CRL cache.Key managementKey management overviewThe LMI manages the keys that are required to enable SSL communication between WebSEAL and other components of the Security Access Manager domain.Key management in the Local Management InterfaceYou can use the LMI to manage the digital certificates that WebSEAL uses. In the LMI, go to the Secure Web Settings > Global Keys menu to access the following key management pages:Client-side and server-side certificate conceptsConfiguration of the WebSEAL key database fileCertificate revocation in WebSEALCRL distribution pointsConfiguration of the CRL cache

Use of the WebSEAL test certificate for SSL connections

Client-side certificate authentication must take place over a Secure Socket Layer (SSL) connection. The SSL connection is established prior to the certificate authentication process. The SSL connection can be established when a client attempts to access a resource over HTTPS. When the resource does not require authenticated access, the client negotiates an SSL session with the WebSEAL server. The SSL session is established when the client and server (WebSEAL) examine each other's certificate and accept the validity of the signing authority.

In order to enable the establishment of SSL sessions on a new WebSEAL server, WebSEAL contains a self-signed test server certificate. WebSEAL can present the self-signed certificate to the client. If the client accepts the certificate, the SSL session is established.

This test certificate is not suitable for permanent use by the WebSEAL server. Although this test certificate allows WebSEAL to respond to an SSL-enabled browser request, it cannot be verified by the browser. This is because the browser does not contain an appropriate root Certificate Authority (CA) certificate — as is the case for when the browser receives any self-signed certificate for which a root CA certificate does not exist. Because the private key for this default certificate is contained in every WebSEAL distribution, this certificate offers no true secure communication.

To ensure secure communication over SSL, WebSEAL administrators must obtain a unique site server certificate from a trusted Certificate Authority (CA). You can use the LMI to generate a certificate request that is sent to the CA. You can also use the LMI to install and label the new site certificate.

Use the webseal-cert-keyfile-label stanza entry in the [ssl] stanza of the WebSEAL configuration file to designate the certificate as the active WebSEAL server-side certificate (this setting overrides any certificate designated as “default” in the keyfile database).

If you require different certificates for other scenarios (such as for mutually authenticated junctions), you can use the LMI to create, install, and label these additional certificates. See Configuration of the WebSEAL key database file.

It is also important to ensure that validation of certificates includes checking of Certificate Revocation Lists (CRLs). Configure WebSEAL to access the appropriate LDAP server as an LDAP user with sufficient permission to access the appropriate CRLs. Supply values for the following configuration file entries:

[ssl]
crl-ldap-server
crl-ldap-server-port
crl-ldap-user
crl-ldap-user-password

WebSEAL can be configured to cache CRLs. To configure the cache, supply values for the following configuration file entries:

[ssl]
gsk-crl-cache-size
gsk-crl-cache-entry-lifetime

Instructions for setting values that affect CRL access and handling, including valid ranges for cache settings, are in the Web Reverse Proxy Stanza Reference topics.

See also Configuration of the CRL cache.

Parent topic: Key management

Related concepts:

Key management overview

Key management in the Local Management Interface

Client-side and server-side certificate concepts

Configuration of the WebSEAL key database file

Certificate revocation in WebSEAL

CRL distribution points

Configuration of the CRL cache

Standard WebSEAL JunctionsStandard WebSEAL JunctionsWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Standard WebSEAL junctionsAdvanced junction configurationMost standard junction options are also supported by virtual host junctions.Modification of URLs to junctioned resourcesHTTP transformationsMicrosoft RPC over HTTPCommand option summary: standard junctions

Standard WebSEAL Junctions

Standard WebSEAL junctions

Advanced junction configuration
Most standard junction options are also supported by virtual host junctions.

Modification of URLs to junctioned resources

HTTP transformations

Microsoft RPC over HTTP

Command option summary: standard junctions

Parent topic: Web Reverse Proxy configuration

Standard WebSEAL junctionsStandard WebSEAL junctionsWebSEAL junctionsjunctionsjunctionsstandardThis chapter provides information for configuring standard WebSEAL junctions.Most standard junction options are also supported by virtual host junctions. Topic Index: Standard WebSEAL JunctionsWebSEAL junctions overviewJunction management in the Local Management InterfaceManaging junctions with the pdadmin utilityStandard WebSEAL junction configurationTransparent path junctionsTechnical notes for using WebSEAL junctionsHow to generate a back-end server Web space (query_contents)

Standard WebSEAL junctions

This chapter provides information for configuring standard WebSEAL junctions.

Most standard junction options are also supported by virtual host junctions.

Topic Index:

WebSEAL junctions overview

Junction management in the Local Management Interface

Managing junctions with the pdadmin utility

Standard WebSEAL junction configuration

Transparent path junctions

Technical notes for using WebSEAL junctions

How to generate a back-end server Web space (query_contents)

Parent topic: Standard WebSEAL Junctions

WebSEAL junctions overview WebSEAL junctions overview junctionsoverviewA WebSEAL junction is an HTTP or HTTPS connection between a front-end WebSEAL server and a back-end Web application server. Junctions logically combine the Web space of the back-end server with the Web space of the WebSEAL server, resulting in a unified view of the entire Web object space. A junction allows WebSEAL to provide protective services on behalf of the back-end server. WebSEAL performs authentication and authorization checks on all requests for resources before passing those requests across a junction to the back-end server. Junctions also allow a variety of single signon solutions between a client and the junctioned back-end applications.You can create WebSEAL junctions with either the pdadmin command-line utility or the LMI.Standard WebSEAL junctionsJunction management in the Local Management InterfaceManaging junctions with the pdadmin utilityStandard WebSEAL junction configurationTransparent path junctionsTechnical notes for using WebSEAL junctionsHow to generate a back-end server Web space (query_contents)Junction typesApplying coarse-grained access control: summaryApplying fine-grained access control: summaryA protective ACL placed on the junction object provides coarse-grained control over the back-end resources. The ACL provides a general overall coarse-grained set of permissions every individual resource accessed through the junction.Additional references for WebSEAL junctions

WebSEAL junctions overview

A WebSEAL junction is an HTTP or HTTPS connection between a front-end WebSEAL server and a back-end Web application server. Junctions logically combine the Web space of the back-end server with the Web space of the WebSEAL server, resulting in a unified view of the entire Web object space.

A junction allows WebSEAL to provide protective services on behalf of the back-end server. WebSEAL performs authentication and authorization checks on all requests for resources before passing those requests across a junction to the back-end server. Junctions also allow a variety of single signon solutions between a client and the junctioned back-end applications.

You can create WebSEAL junctions with either the pdadmin command-line utility or the LMI.

Junction types

Applying coarse-grained access control: summary

Applying fine-grained access control: summary
A protective ACL placed on the junction object provides coarse-grained control over the back-end resources. The ACL provides a general overall coarse-grained set of permissions every individual resource accessed through the junction.

Additional references for WebSEAL junctions

Parent topic: Standard WebSEAL junctions

Related concepts:

Junction management in the Local Management Interface

Standard WebSEAL junction configuration

Transparent path junctions

How to generate a back-end server Web space (query_contents)

Related tasks:

Managing junctions with the pdadmin utility

Related reference:

Technical notes for using WebSEAL junctions

Junction typesJunction typesJunction types in IBM Security Access Manager for WebjunctionstypesYou can create the following WebSEAL junction types: WebSEAL to back-end server over TCP connectionWebSEAL to back-end server over TCP connection using HTTP proxy serverWebSEAL to back-end server over SSL connectionWebSEAL to back-end server over SSL connection using HTTPS proxy serverWebSEAL to WebSEAL over SSL connectionWebSEAL to back-end server over mutual junctionYou must address the following two concerns when creating any junction: Decide where to junction (mount) the Web application server in the WebSEAL object space.Choose the type of junction.WebSEAL junctions overview

Junction types

You can create the following WebSEAL junction types:

WebSEAL to back-end server over TCP connection

WebSEAL to back-end server over TCP connection using HTTP proxy server

WebSEAL to back-end server over SSL connection

WebSEAL to back-end server over SSL connection using HTTPS proxy server

WebSEAL to WebSEAL over SSL connection

WebSEAL to back-end server over mutual junction

You must address the following two concerns when creating any junction:

Decide where to junction (mount) the Web application server in the WebSEAL object space.

Choose the type of junction.

Parent topic: WebSEAL junctions overview

Applying coarse-grained access control: summaryApplying coarse-grained access control: summaryWebSEALcourse grained access controlACL A protective ACL placed on the junction object provides coarse-grained control over the back-end resources. The ACL provides a general overall coarse-grained set of permissions every individual resource accessed through the junction.Use the pdadmin utility to create a junction between WebSEAL and the back-end server.Place an appropriate ACL policy on the junction point to provide coarse-grained control to the back-end server.WebSEAL junctions overview

Applying coarse-grained access control: summary

About this task

A protective ACL placed on the junction object provides coarse-grained control over the back-end resources. The ACL provides a general overall coarse-grained set of permissions every individual resource accessed through the junction.

Procedure

Use the pdadmin utility to create a junction between WebSEAL and the back-end server.

Place an appropriate ACL policy on the junction point to provide coarse-grained control to the back-end server.

Parent topic: WebSEAL junctions overview

Applying fine-grained access control: summaryApplying fine-grained access control: summaryApplying fine-grained access control: summary in IBM Security Access Manager for WebA protective ACL placed on the junction object provides coarse-grained control over the back-end resources. The ACL provides a general overall coarse-grained set of permissions every individual resource accessed through the junction.WebSEALACLquery_contentsfine grained access controlfine grained access controlYou can also provide fine-grained protection to the resources accessed through the junction by explicitly placing ACLs on individual resource objects or groups of objects. WebSEAL cannot automatically see and understand a back-end file system. You must inform WebSEAL of the back-end object space using a special application, called query_contents, that inventories the back-end Web space and reports the structure and contents to WebSEAL.Use the pdadmin utility to create a junction between WebSEAL and the back-end server. Copy the query_contents program to the back-end server.Apply ACL policy to appropriate objects in the object space revealed by the query_contents program.WebSEAL junctions overview

Applying fine-grained access control: summary

A protective ACL placed on the junction object provides coarse-grained control over the back-end resources. The ACL provides a general overall coarse-grained set of permissions every individual resource accessed through the junction.

About this task

You can also provide fine-grained protection to the resources accessed through the junction by explicitly placing ACLs on individual resource objects or groups of objects. WebSEAL cannot automatically see and understand a back-end file system. You must inform WebSEAL of the back-end object space using a special application, called query_contents, that inventories the back-end Web space and reports the structure and contents to WebSEAL.

Procedure

Use the pdadmin utility to create a junction between WebSEAL and the back-end server.

Copy the query_contents program to the back-end server.

Apply ACL policy to appropriate objects in the object space revealed by the query_contents program.

Parent topic: WebSEAL junctions overview

Additional references for WebSEAL junctionsAdditional references for WebSEAL junctionsjunctionsadditional referencesWebSEAL junctionsreferencesSee Standard WebSEAL junctionsA WebSEAL junction is a TCP/IP connection between a front-end WebSEAL server and a back-end server. for a conceptual overview of WebSEAL junctions.See Advanced junction configurationMost standard junction options are also supported by virtual host junctions. for advanced junction options.See Command option summary: standard junctions for a summary of the junction command options by functional categories.WebSEAL junctions overview

Additional references for WebSEAL junctions

See Standard WebSEAL junctions for a conceptual overview of WebSEAL junctions.

See Advanced junction configuration for advanced junction options.

See Command option summary: standard junctions for a summary of the junction command options by functional categories.

Parent topic: WebSEAL junctions overview

Junction management in the Local Management InterfaceJunction management in the Local Management Interfacejunction managementLMIjunction management pageYou can use the LMI to manage standard and virtual junctions. To access the junction management page in the LMI, go to the Reverse Proxy Management page and select the appropriate WebSEAL instance. Click Manage > Junction Management to open the Junction Management page for the selected instance. From the Junction Management page, you can complete the following tasks:Retrieve a list of standard and virtual junctions.Retrieve the parameters for a single standard or virtual junction.Delete a standard or virtual junction.Create a standard or virtual junction.Add a back-end server to an existing standard or virtual junction.See the IBM Security Web Gateway appliance: Administration Guide for detailed information about how to use the LMI to complete these junction management tasks.Standard WebSEAL junctionsWebSEAL junctions overviewManaging junctions with the pdadmin utilityStandard WebSEAL junction configurationTransparent path junctionsTechnical notes for using WebSEAL junctionsHow to generate a back-end server Web space (query_contents)

Junction management in the Local Management Interface

You can use the LMI to manage standard and virtual junctions. To access the junction management page in the LMI, go to the Reverse Proxy Management page and select the appropriate WebSEAL instance. Click Manage > Junction Management to open the Junction Management page for the selected instance.

From the Junction Management page, you can complete the following tasks:

Retrieve a list of standard and virtual junctions.

Retrieve the parameters for a single standard or virtual junction.

Delete a standard or virtual junction.

Create a standard or virtual junction.

Add a back-end server to an existing standard or virtual junction.

See the IBM Security Web Gateway appliance: Administration Guide for detailed information about how to use the LMI to complete these junction management tasks.

Parent topic: Standard WebSEAL junctions

Related concepts:

WebSEAL junctions overview

Standard WebSEAL junction configuration

Transparent path junctions

How to generate a back-end server Web space (query_contents)

Related tasks:

Managing junctions with the pdadmin utility

Related reference:

Technical notes for using WebSEAL junctions

Managing junctions with the pdadmin utilityManaging junctions with the pdadmin utilitypdadmin server taskcreate junctionsjunctionspdadmin server task Before using the pdadmin utility, you must login to a secure domain as a user with administration authorization, such as sec_master. For example: UNIX or Linux: # pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin> To create WebSEAL junctions, you use the pdadmin server task create command: pdadmin> server task instance_name-webseald-host_name create options For example, if the configured name of a single WebSEAL instance is web1 , installed on a host named www.example.com, the complete server name would be expressed as follows: web1-webseald-www.example.com pdadmin server listUse the pdadmin server list command to display the correct format of the complete server name: pdadmin> server list web1-webseald-www.example.com For more information, see the reference page for pdadmin server task create, The pdadmin server task create command.Standard WebSEAL junctionsWebSEAL junctions overviewJunction management in the Local Management InterfaceStandard WebSEAL junction configurationTransparent path junctionsTechnical notes for using WebSEAL junctionsHow to generate a back-end server Web space (query_contents)

Managing junctions with the pdadmin utility

About this task

Before using the pdadmin utility, you must login to a secure domain as a user with administration authorization, such as sec_master.

For example:

UNIX or Linux:

# pdadmin
pdadmin> login
Enter User ID: sec_master
Enter Password:
pdadmin>

To create WebSEAL junctions, you use the pdadmin server task create command:

pdadmin> server task instance_name-webseald-host_name create options

For example, if the configured name of a single WebSEAL instance is web1 , installed on a host named www.example.com, the complete server name would be expressed as follows:

web1-webseald-www.example.com

Use the pdadmin server list command to display the correct format of the complete server name:

pdadmin> server list
web1-webseald-www.example.com

For more information, see the reference page for pdadmin server task create, The pdadmin server task create command.

Parent topic: Standard WebSEAL junctions

Related concepts:

WebSEAL junctions overview

Junction management in the Local Management Interface

Standard WebSEAL junction configuration

Transparent path junctions

How to generate a back-end server Web space (query_contents)

Related reference:

Technical notes for using WebSEAL junctions

Standard WebSEAL junction configurationStandard WebSEAL junction configurationjunctionsconfiguring basic junctionThis section contains the following topics:Standard WebSEAL junctionsWebSEAL junctions overviewJunction management in the Local Management InterfaceManaging junctions with the pdadmin utilityTransparent path junctionsTechnical notes for using WebSEAL junctionsHow to generate a back-end server Web space (query_contents)The pdadmin server task create commandCreating TCP type standard junctionsCreating SSL type standard junctionsCreating mutual junctionsSSL-based standard junctionsAdding multiple back-end servers to a standard junctionLocal type standard junctionDisable local junctionsDisable the local junction functionality so that the WebSEAL instance cannot serve locally stored pages.

Standard WebSEAL junction configuration

This section contains the following topics:

The pdadmin server task create command

Creating TCP type standard junctions

Creating SSL type standard junctions

Creating mutual junctions

SSL-based standard junctions

Adding multiple back-end servers to a standard junction

Local type standard junction

Disable local junctions
Disable the local junction functionality so that the WebSEAL instance cannot serve locally stored pages.

Parent topic: Standard WebSEAL junctions

Related concepts:

WebSEAL junctions overview

Junction management in the Local Management Interface

Transparent path junctions

How to generate a back-end server Web space (query_contents)

Related tasks:

Managing junctions with the pdadmin utility

Related reference:

Technical notes for using WebSEAL junctions

The pdadmin server task create commandThe pdadmin server task create commandjunctionsbasic junction commandpdadmin policyserver task create commandWebSEAL supports both standard non-secure TCP (HTTP) and secure SSL (HTTPS) junctions between WebSEAL and back-end Web application servers.The junction between WebSEAL and the back-end server is independent of the type of connection (and its level of security) between the client (browser) and the WebSEAL server. The mandatory command options required to create a basic WebSEAL junction using pdadmin server task create include: Host name of the back-end application server ( –h option)Junction type: tcp, ssl, tcpproxy, sslproxy, local ( –t option)Junction point (mount point)Command syntax (entered as one line):pdadmin> server task instance_name-webseald-host-name create -t type -h host_name jct_pointFor example:pdadmin> server task web1-webseald-cruz create -t tcp -h doc.ibm.com /pubsAlways use the fully qualified domain name of the back-end server when specifying the argument to the –h option.Standard WebSEAL junction configuration

The pdadmin server task create command

WebSEAL supports both standard non-secure TCP (HTTP) and secure SSL (HTTPS) junctions between WebSEAL and back-end Web application servers.

The junction between WebSEAL and the back-end server is independent of the type of connection (and its level of security) between the client (browser) and the WebSEAL server.

The mandatory command options required to create a basic WebSEAL junction using pdadmin server task create include:

Host name of the back-end application server ( –h option)

Junction type: tcp, ssl, tcpproxy, sslproxy, local ( –t option)

Junction point (mount point)

Command syntax (entered as one line):

pdadmin> server task instance_name-webseald-host-name
 create -t type -h host_name jct_point

For example:

pdadmin> server task web1-webseald-cruz create -t tcp -h doc.ibm.com /pubs

Note: Always use the fully qualified domain name of the back-end server when specifying the argument to the –h option.

Parent topic: Standard WebSEAL junction configuration

Creating TCP type standard junctions Creating TCP type standard junctions junctionsconfiguring TCP type junction A WebSEAL junction over a TCP connection provides the basic properties of a junction but does not provide secure communication across the junction. Non-secure TCP (HTTP) junctionNon-secure TCP (HTTP) junction To create a secure TCP junction and add an initial server, use the create command with the –t tcp option (entered as one line):pdadmin> server task instance_name-webseald-host_name create -t tcp -h host-name [-p port] jct-pointThe default port value for a TCP junction (if not specified) is 80.Standard WebSEAL junction configuration

Creating TCP type standard junctions

About this task

A WebSEAL junction over a TCP connection provides the basic properties of a junction but does not provide secure communication across the junction.

Figure 27. Non-secure TCP (HTTP) junction

Procedure

To create a secure TCP junction and add an initial server, use the create command with the –t tcp option (entered as one line):

pdadmin> server task instance_name-webseald-host_name create -t tcp
-h host-name [-p port] jct-point

The default port value for a TCP junction (if not specified) is 80.

Parent topic: Standard WebSEAL junction configuration

Creating SSL type standard junctions Creating SSL type standard junctions junctionsconfiguring SSL type junctionSSLjunctionscreating SSL junctions function exactly like TCP junctions, with the added value that all communication between WebSEAL and the back-end server is encrypted. Secure SSL (HTTPS) junctionSecure SSL (HTTPS) junction SSL junctions allow secure end-to-end browser-to-application transactions. You can use SSL to secure communications from the client to WebSEAL and from WebSEAL to the back-end server. The back-end server must be HTTPS-enabled when you use an SSL junction. To create a secure SSL junction and add an initial server, use the create command with the –t ssl option (entered as one line):pdadmin> server task instance_name-webseald-host-name create -t ssl -h host_name [-p port] jct_pointThe default port value for an SSL junction (if not specified) is 443.For more information on configuring SSL-based standard junctions, see SSL-based standard junctions.Standard WebSEAL junction configuration

Creating SSL type standard junctions

About this task

SSL junctions function exactly like TCP junctions, with the added value that all communication between WebSEAL and the back-end server is encrypted.

Figure 28. Secure SSL (HTTPS) junction

SSL junctions allow secure end-to-end browser-to-application transactions. You can use SSL to secure communications from the client to WebSEAL and from WebSEAL to the back-end server. The back-end server must be HTTPS-enabled when you use an SSL junction.

Procedure

To create a secure SSL junction and add an initial server, use the create command with the –t ssl option (entered as one line):

pdadmin> server task instance_name-webseald-host-name create -t ssl
-h host_name [-p port] jct_point

The default port value for an SSL junction (if not specified) is 443.

For more information on configuring SSL-based standard junctions, see SSL-based standard junctions.

Parent topic: Standard WebSEAL junction configuration

Creating mutual junctions Creating mutual junctions junctionsconfiguring mutual junctionsmutually authenticated junctions Mutual junctions provide the ability to send junction requests over HTTP or HTTPS, governed by the communication protocol over which the request was received. If a request comes in to a mutual junction over HTTP, then the request goes to the junctioned server via HTTP. If the request comes in over HTTPS then it goes to the junctioned server over HTTPS. To create a mutual junction and add an initial server, use the create command with the –t mutual option. Use the -p option for a HTTP port and the -P option for a HTTPS port. Similarly, use the -V option to specify the virtual host name for HTTP requests, and the -V option to specify the virtual host name for HTTPS requests. For example (entered as one line):pdadmin> server task instance_name-webseald-host-name create -t mutual -h host_name [-p HTTP_port] [-P HTTPS_port] [-v HTTP_virtual_host_name] [-V HTTPS_virtual_host_name]jct_pointThe default HTTP port value for a mutual junction (if not specified) is 80.The default HTTPS port value for a mutual junction (if not specified) is 443.Standard WebSEAL junction configuration

Creating mutual junctions

About this task

Mutual junctions provide the ability to send junction requests over HTTP or HTTPS, governed by the communication protocol over which the request was received.

If a request comes in to a mutual junction over HTTP, then the request goes to the junctioned server via HTTP. If the request comes in over HTTPS then it goes to the junctioned server over HTTPS.

Procedure

To create a mutual junction and add an initial server, use the create command with the –t mutual option. Use the -p option for a HTTP port and the -P option for a HTTPS port. Similarly, use the -V option to specify the virtual host name for HTTP requests, and the -V option to specify the virtual host name for HTTPS requests. For example (entered as one line):

pdadmin> server task instance_name-webseald-host-name create -t mutual
-h host_name [-p HTTP_port] [-P HTTPS_port] [-v HTTP_virtual_host_name]
[-V HTTPS_virtual_host_name]jct_point

The default HTTP port value for a mutual junction (if not specified) is 80.

The default HTTPS port value for a mutual junction (if not specified) is 443.

Parent topic: Standard WebSEAL junction configuration

SSL-based standard junctionsSSL-based standard junctionsjunctionsSSL typeSSLjunctionsoverviewStandard WebSEAL junction configurationVerification of the back-end server certificateExamples of SSL junctionsDisabling SSL protocol versions for junctions

SSL-based standard junctions

Verification of the back-end server certificate

Examples of SSL junctions

Disabling SSL protocol versions for junctions

Parent topic: Standard WebSEAL junction configuration

Verification of the back-end server certificate Verification of the back-end server certificate iKeymanSSL junctionsback-end serverscertificatesverificationWhen a client makes a request for a resource on the back-end server, WebSEAL, in its role as a security server, performs the request on behalf of the client. The SSL protocol specifies that when a request is made to the back-end server, that server must provide proof of its identity using a server-side certificate.When WebSEAL receives this certificate from the back-end server, it must verify its authenticity by matching the certificate against a list of root CA certificates stored in its certificate database.Security Access Manager uses the IBM Global Security Kit (GSKit) implementation of SSL. You can use the LMI to add the root certificate of the CA who signed the back-end server certificate to the WebSEAL certificate keyfile (pdsrv.kdb).SSL-based standard junctions

Verification of the back-end server certificate

When a client makes a request for a resource on the back-end server, WebSEAL, in its role as a security server, performs the request on behalf of the client. The SSL protocol specifies that when a request is made to the back-end server, that server must provide proof of its identity using a server-side certificate.

When WebSEAL receives this certificate from the back-end server, it must verify its authenticity by matching the certificate against a list of root CA certificates stored in its certificate database.

Security Access Manager uses the IBM® Global Security Kit (GSKit) implementation of SSL. You can use the LMI to add the root certificate of the CA who signed the back-end server certificate to the WebSEAL certificate keyfile (pdsrv.kdb).

Parent topic: SSL-based standard junctions

Examples of SSL junctionsExamples of SSL junctionsSSLjunctionsexamplesJunction host sales.ibm.com at junction point /sales over SSL (entered as one line):pdadmin> server task web1-webseald-cruz create -t ssl -h sales.ibm.com /salesIn this sales example, the –t ssl option dictates a default port of 443.Junction host travel.ibm.com on port 4443 at junction point /travel over SSL (entered as one line): pdadmin> server task web1-webseald-cruz create -t ssl -p 4443 -h travel.ibm.com /travelSSL-based standard junctions

Examples of SSL junctions

Junction host sales.ibm.com at junction point /sales over SSL (entered as one line):

pdadmin> server task web1-webseald-cruz  create -t ssl -h
sales.ibm.com /sales

Note: In this sales example, the –t ssl option dictates a default port of 443.

Junction host travel.ibm.com on port 4443 at junction point /travel over SSL (entered as one line):

pdadmin> server task web1-webseald-cruz create -t ssl -p 4443
-h travel.ibm.com /travel

Parent topic: SSL-based standard junctions

Disabling SSL protocol versions for junctionsDisabling SSL protocol versions for junctionsdisable-ssl-v2 stanza entryjunction stanzadisable-ssl-v3 stanza entryjunction stanzadisable-tls-v1 stanza entryjunction stanzaSSLjunctionsprotocol You can optionally disable one or more SSL protocol versions for junction connections. By default, SSL v2 is disabled. All other supported SSL versions are enabled. The WebSEAL configuration file provides the following entries by default: [junction] disable-ssl-v2 = yes disable-ssl-v3 = no disable-tls-v1 = no disable-tls-v11 = no disable-tls-v12 = no To disable an SSL protocol version for junctions, set the corresponding entry to yes.SSL-based standard junctions

Disabling SSL protocol versions for junctions

About this task

You can optionally disable one or more SSL protocol versions for junction connections. By default, SSL v2 is disabled. All other supported SSL versions are enabled. The WebSEAL configuration file provides the following entries by default:

[junction]
disable-ssl-v2 = yes
disable-ssl-v3 = no
disable-tls-v1 = no
disable-tls-v11 = no
disable-tls-v12 = no

Procedure

To disable an SSL protocol version for junctions, set the corresponding entry to yes.

Parent topic: SSL-based standard junctions

Adding multiple back-end servers to a standard junctionAdding multiple back-end servers to a standard junctionjunctionsadding multiple back-end replica servers to a junctionback-end serversadding to a standard junctionSee Adding multiple back-end servers to the same junction.Standard WebSEAL junction configuration

Adding multiple back-end servers to a standard junction

About this task

See Adding multiple back-end servers to the same junction.

Parent topic: Standard WebSEAL junction configuration

Local type standard junctionLocal type standard junctionjunctionsconfiguring local type junctionslocal typesstandard junctionA local type junction (-t local) is a mount point for specific content located locally on the WebSEAL server. Like the content from junctioned remote servers, local junction content is incorporated into WebSEAL's unified protected object space view.The following junction options are appropriate for local type junctions:Local type junction optionsOptionDescription –t type Type of junction (local). –f Force the replacement of an existing junction. See Forcing a new junction. –l percent-value Defines the soft limit for consumption of worker threads. –L percent-value Defines the hard limit for consumption of worker threads.Standard WebSEAL junction configuration

Local type standard junction

A local type junction (-t local) is a mount point for specific content located locally on the WebSEAL server. Like the content from junctioned remote servers, local junction content is incorporated into WebSEAL's unified protected object space view.

The following junction options are appropriate for local type junctions:

Table 58. Local type junction options

Option
Description

–t type

Type of junction (local).

–f

Force the replacement of an existing junction.

See Forcing a new junction.

–l percent-value

Defines the soft limit for consumption of worker threads.

–L percent-value

Defines the hard limit for consumption of worker threads.

Parent topic: Standard WebSEAL junction configuration

Disable local junctionsDisable local junctionsDisable the local junction functionality so that the WebSEAL instance cannot serve locally stored pages.disable local junctionsdisable-local-junctionslocal junctionsdisablingSet the disable-local-junctions entry in the [junction] stanza of the WebSEAL configuration file to yes to disable the local junction functionality:[junction] disable-local-junctions = yesIf you enable the disable-local-junctions configuration item, new local junctions are not created. If existing local junctions are in the WebSEAL instance, those junctions are not loaded when the instance starts.Standard WebSEAL junction configuration

Disable local junctions

Disable the local junction functionality so that the WebSEAL instance cannot serve locally stored pages.

Set the disable-local-junctions entry in the [junction] stanza of the WebSEAL configuration file to yes to disable the local junction functionality:

[junction]
disable-local-junctions = yes

If you enable the disable-local-junctions configuration item, new local junctions are not created. If existing local junctions are in the WebSEAL instance, those junctions are not loaded when the instance starts.

Parent topic: Standard WebSEAL junction configuration

Transparent path junctionsTransparent path junctionsjunctionstransparent path junctions (-x)transparent path junctionoverviewThis section contains the following topics:Standard WebSEAL junctionsWebSEAL junctions overviewJunction management in the Local Management InterfaceManaging junctions with the pdadmin utilityStandard WebSEAL junction configurationTechnical notes for using WebSEAL junctionsHow to generate a back-end server Web space (query_contents)Filtering concepts in standard WebSEAL junctionsIn standard junction configuration, a configured junction represents a specific back-end host machine. The junction and its name are represented as a subdirectory in the WebSEAL protected object space.Transparent path junction conceptsConfiguring transparent path junctionsExample transparent path junction

Transparent path junctions

This section contains the following topics:

Filtering concepts in standard WebSEAL junctions
In standard junction configuration, a configured junction represents a specific back-end host machine. The junction and its name are represented as a subdirectory in the WebSEAL protected object space.

Transparent path junction concepts

Configuring transparent path junctions

Example transparent path junction

Parent topic: Standard WebSEAL junctions

Related concepts:

WebSEAL junctions overview

Junction management in the Local Management Interface

Standard WebSEAL junction configuration

How to generate a back-end server Web space (query_contents)

Related tasks:

Managing junctions with the pdadmin utility

Related reference:

Technical notes for using WebSEAL junctions

Filtering concepts in standard WebSEAL junctionsFiltering concepts in standard WebSEAL junctionsFiltering concepts in standard WebSEAL junctions in IBM Security Access Manager for WebIn standard junction configuration, a configured junction represents a specific back-end host machine. The junction and its name are represented as a subdirectory in the WebSEAL protected object space.WebSEALstandard junctionsstandard junctionsfiltering conceptsThe following example uses the pdadmin server task command to create a junction (/jct) to the back-end server pubs.ibm.com:pdadmin> server task web1-webseald-www.cruz.com create -t tcp -h pubs.ibm.com /jctA subdirectory named /jct is created in the WebSEAL object space. This junction mount point represents the back-end server pubs.ibm.com.A response page returned from pubs.ibm.com contains the following link (URL) in the HTML of that page:http://pubs.ibm.com/docs/readme.htmlWebSEAL's standard filtering mechanism for standard junctions parses the HTML in the response page and modifies this link by adding the name of the junction configured for this back-end server. Additionally, the original absolute expression of the URL is changed to a server-relative expression. This is the link as it now appears to the user:/jct/docs/readme.htmlIf rewrite-absolute-with-absolute was set to "yes", the link would appear as: http://www.cruz.com/jct/docs/readme.htmlSee Configuring the rewrite-absolute-with-absolute option.Now the user clicks the link to access the back-end resource (readme.html).The portion of the URL representing the junction name (/jct) is mapped by WebSEAL to the back-end server, pubs.ibm.com. By design, a junction points to the root of the back-end server document space. Any path expression following the junction name in the URL represents the path to the resource from the server's root location.As a conclusion to the example, WebSEAL successfully locates the resource at:http://pubs.ibm.com/docs/readme.htmlNotice that in the end, the junction name has been removed from the path and the URL reads as it originally appeared on the response page.Transparent path junctions

Filtering concepts in standard WebSEAL junctions

In standard junction configuration, a configured junction represents a specific back-end host machine. The junction and its name are represented as a subdirectory in the WebSEAL protected object space.

The following example uses the pdadmin server task command to create a junction (/jct) to the back-end server pubs.ibm.com:

pdadmin> server task web1-webseald-www.cruz.com create -t tcp -h pubs.ibm.com /jct

A subdirectory named /jct is created in the WebSEAL object space. This junction mount point represents the back-end server pubs.ibm.com.

A response page returned from pubs.ibm.com contains the following link (URL) in the HTML of that page:

http://pubs.ibm.com/docs/readme.html

WebSEAL's standard filtering mechanism for standard junctions parses the HTML in the response page and modifies this link by adding the name of the junction configured for this back-end server. Additionally, the original absolute expression of the URL is changed to a server-relative expression. This is the link as it now appears to the user:

/jct/docs/readme.html

Note: If rewrite-absolute-with-absolute was set to "yes", the link would appear as:

http://www.cruz.com/jct/docs/readme.html

See Configuring the rewrite-absolute-with-absolute option.

Now the user clicks the link to access the back-end resource (readme.html).

The portion of the URL representing the junction name (/jct) is mapped by WebSEAL to the back-end server, pubs.ibm.com. By design, a junction points to the root of the back-end server document space. Any path expression following the junction name in the URL represents the path to the resource from the server's root location.

As a conclusion to the example, WebSEAL successfully locates the resource at:

http://pubs.ibm.com/docs/readme.html

Notice that in the end, the junction name has been removed from the path and the URL reads as it originally appeared on the response page.

Parent topic: Transparent path junctions

Transparent path junction conceptsTransparent path junction conceptstransparent path junctionconceptstransparent path junctionconceptsjunctionstransparent path conceptsFor standard WebSEAL junctions, a link to a resource on a back-end junctioned server can only succeed if the URL in the request received by WebSEAL contains the identity of the junction. Junctions use both default and optional filtering solutions to force URLs found in HTML response pages to appear correct when viewed as a part of WebSEAL's single host document space. See Modification of URLs to junctioned resources.There are three parts of a URL that must be considered in a filtering solution: protocolhost name:portpathOf the three parts of a URL, the path is often the most problematic and restricting part to filter. The transparent path junction option (-x) implements a variation on the standard junction mechanism that eliminates the need to filter the path portion of a URL. A transparent path junction observes a crucial requirement: the configured junction name must match the name of a subdirectory under the root of the back-end server document space. All resources accessed through this junction must be located under this subdirectory. The transparent path junction name represents the name of the actual subdirectory on the back-end server.Transparent path junctions are really the same as standard junctions except that the junction name, instead of being an addition to the URL path, is based on the path already present on the back-end application. Transparent path junctions allow WebSEAL to route requests to a junction based on the URL path of the back-end server resources rather than based on a junction name added to the path.For example, if the configured junction name is /docs, all resources controlled by this junction must be located on the back-end server under a subdirectory called /docs.The transparent path junction mechanism prevents WebSEAL from filtering the path portion of links to the resources protected by this junction. The junction name has now become part of the actual path expression describing the location of a resource and no longer requires filtering. The junction name is not added to or removed from the path portion of URLs, as it is in junctions created without the transparent path option.WebSEAL does support nested paths. For example, the following three junctions are all valid and can be made on the same WebSEAL system: /financing/tools /financing/tools/gars /financing/tools/gars/customThe pattern-matching within WebSEAL is sensitive enough to map to the most "specific" junction first, /financing/tools/gars/custom in this example.Transparent path junctions

Transparent path junction concepts

For standard WebSEAL junctions, a link to a resource on a back-end junctioned server can only succeed if the URL in the request received by WebSEAL contains the identity of the junction. Junctions use both default and optional filtering solutions to force URLs found in HTML response pages to appear correct when viewed as a part of WebSEAL's single host document space. See Modification of URLs to junctioned resources.

There are three parts of a URL that must be considered in a filtering solution:

protocol

host name:port

path

Of the three parts of a URL, the path is often the most problematic and restricting part to filter. The transparent path junction option (-x) implements a variation on the standard junction mechanism that eliminates the need to filter the path portion of a URL.

A transparent path junction observes a crucial requirement: the configured junction name must match the name of a subdirectory under the root of the back-end server document space. All resources accessed through this junction must be located under this subdirectory. The transparent path junction name represents the name of the actual subdirectory on the back-end server.

Transparent path junctions are really the same as standard junctions except that the junction name, instead of being an addition to the URL path, is based on the path already present on the back-end application. Transparent path junctions allow WebSEAL to route requests to a junction based on the URL path of the back-end server resources rather than based on a junction name added to the path.

For example, if the configured junction name is /docs, all resources controlled by this junction must be located on the back-end server under a subdirectory called /docs.

The transparent path junction mechanism prevents WebSEAL from filtering the path portion of links to the resources protected by this junction. The junction name has now become part of the actual path expression describing the location of a resource and no longer requires filtering. The junction name is not added to or removed from the path portion of URLs, as it is in junctions created without the transparent path option.

WebSEAL does support nested paths. For example, the following three junctions are all valid and can be made on the same WebSEAL system:

/financing/tools
/financing/tools/gars
/financing/tools/gars/custom

The pattern-matching within WebSEAL is sensitive enough to map to the most "specific" junction first, /financing/tools/gars/custom in this example.

Parent topic: Transparent path junctions

Configuring transparent path junctionsConfiguring transparent path junctionstransparent path junctionconfiguration To configure a transparent path junction:Use the pdadmin server task command to create the transparent path junction. Create the junction like you would a standard WebSEAL junction, but include the -x option. In the following example (entered as one line), the junction name is /files/docs:pdadmin> server task web1-webseald-www.cruz.com create -t tcp -x-h pubs.ibm.com /files/docsEnsure that all resources protected by this junction are contained on the back-end server (in this example, pubs.ibm.com) under a subdirectory called /files/docs/. The junction name (and its associated subdirectory on the back-end server) must be unique among all other protected servers in the WebSEAL environment.Transparent path junctions

Configuring transparent path junctions

About this task

To configure a transparent path junction:

Procedure

Use the pdadmin server task command to create the transparent path junction. Create the junction like you would a standard WebSEAL junction, but include the -x option. In the following example (entered as one line), the junction name is /files/docs:pdadmin> server task web1-webseald-www.cruz.com create -t tcp -x-h pubs.ibm.com /files/docs

Ensure that all resources protected by this junction are contained on the back-end server (in this example, pubs.ibm.com) under a subdirectory called /files/docs/.

Results

The junction name (and its associated subdirectory on the back-end server) must be unique among all other protected servers in the WebSEAL environment.

Parent topic: Transparent path junctions

Example transparent path junctionExample transparent path junctiontransparent path junctionexamplesexamplestransparent path junctionsThe following example uses the pdadmin command (entered as one line) to create a transparent path junction (/docs) to the back-end server pubs.ibm.com:pdadmin> server task web1-webseald-www.cruz.com create -t tcp -x -h pubs.ibm.com /docsAfter a client request for a back-end resource is made (via the WebSEAL proxy server), a response page is returned from pubs.ibm.com containing the following link (URL) in the HTML of that page:http://pubs.ibm.com/docs/readme.htmlWebSEAL's standard filtering mechanism for junctions parses the HTML in the response page and modifies this link by changing the original absolute expression of the URL to a server-relative expression. However, the path is not filtered, because this is a transparent path junction (-x). This is the link as it now appears to the user:/docs/readme.htmlIf rewrite-absolute-with-absolute was set to "yes", the link would appear as: http://www.cruz.com/docs/readme.htmlSee Configuring the rewrite-absolute-with-absolute option.Now the user clicks the link to access the back-end resource (readme.html).The portion of the URL representing the junction name (/docs) is recognized by WebSEAL as associated with the /docs subdirectory on the back-end server, pubs.ibm.com. As a conclusion to the example, WebSEAL successfully locates the resource at:http://pubs.ibm.com/docs/readme.htmlSome benefits of transparent path junctions include:Several different transparent path junctions to the same back-end server can be created to point to different regions (subdirectories) of that server.Each individual transparent path junction can handle a different authentication requirement and ACL control.Transparent path junctions

Example transparent path junction

The following example uses the pdadmin command (entered as one line) to create a transparent path junction (/docs) to the back-end server pubs.ibm.com:

pdadmin> server task web1-webseald-www.cruz.com create -t tcp -x
-h pubs.ibm.com /docs

After a client request for a back-end resource is made (via the WebSEAL proxy server), a response page is returned from pubs.ibm.com containing the following link (URL) in the HTML of that page:

http://pubs.ibm.com/docs/readme.html

WebSEAL's standard filtering mechanism for junctions parses the HTML in the response page and modifies this link by changing the original absolute expression of the URL to a server-relative expression. However, the path is not filtered, because this is a transparent path junction (-x). This is the link as it now appears to the user:

/docs/readme.html

Note: If rewrite-absolute-with-absolute was set to "yes", the link would appear as:

http://www.cruz.com/docs/readme.html

See Configuring the rewrite-absolute-with-absolute option.

Now the user clicks the link to access the back-end resource (readme.html).

The portion of the URL representing the junction name (/docs) is recognized by WebSEAL as associated with the /docs subdirectory on the back-end server, pubs.ibm.com.

As a conclusion to the example, WebSEAL successfully locates the resource at:

http://pubs.ibm.com/docs/readme.html

Some benefits of transparent path junctions include:

Several different transparent path junctions to the same back-end server can be created to point to different regions (subdirectories) of that server.

Each individual transparent path junction can handle a different authentication requirement and ACL control.

Parent topic: Transparent path junctions

Technical notes for using WebSEAL junctionsTechnical notes for using WebSEAL junctionsjunctionstechnical notestechnical notesjunctionsThis section contains the following topics:Standard WebSEAL junctionsWebSEAL junctions overviewJunction management in the Local Management InterfaceManaging junctions with the pdadmin utilityStandard WebSEAL junction configurationTransparent path junctionsHow to generate a back-end server Web space (query_contents)Guidelines for creating WebSEAL junctionsAdding multiple back-end servers to the same junctionExceptions to enforcing permissions across junctionsCertificate authentication across junctionsHandling domain cookiesSupported HTTP versions for requests and responsesJunctioned application with Web Portal Manager

Technical notes for using WebSEAL junctions

This section contains the following topics:

Guidelines for creating WebSEAL junctions

Adding multiple back-end servers to the same junction

Exceptions to enforcing permissions across junctions

Certificate authentication across junctions

Handling domain cookies

Supported HTTP versions for requests and responses

Junctioned application with Web Portal Manager

Parent topic: Standard WebSEAL junctions

Related concepts:

WebSEAL junctions overview

Junction management in the Local Management Interface

Standard WebSEAL junction configuration

Transparent path junctions

How to generate a back-end server Web space (query_contents)

Related tasks:

Managing junctions with the pdadmin utility

Guidelines for creating WebSEAL junctions Guidelines for creating WebSEAL junctions junctionscreation guidelinesThe following guidelines summarize the "rules" for junctions: You can add a junction anywhere in the primary WebSEAL object space.You can junction multiple replica back-end servers at the same mount point. Multiple replica back-end servers mounted to the same junction point must be of the same type.ACL policies are inherited across junctions to back-end Web servers.The junction name should not match any directory name in the Web space of the back-end server if HTML pages from that server contain programs (such as JavaScript or applets) with server-relative URLs to that directory. For example, if pages from the back-end server contain programs with a URL of form /path/..., do not create a junction name using /path.Creating multiple WebSEAL junctions that point to the same back-end application server/port is not a secure junction configuration. Each junction can be control by unique ACLs. One junction secured with more permissive ACLs can compromise another junction secured with less permissive ACLs. This type of configuration can cause unintended control of access to resources and is therefore not a supported configuration strategy for Security Access Manager.WebSEAL supports HTTP/1.1 across junctions. Technical notes for using WebSEAL junctions

Guidelines for creating WebSEAL junctions

The following guidelines summarize the "rules" for junctions:

You can add a junction anywhere in the primary WebSEAL object space.

You can junction multiple replica back-end servers at the same mount point.

Multiple replica back-end servers mounted to the same junction point must be of the same type.

ACL policies are inherited across junctions to back-end Web servers.

The junction name should not match any directory name in the Web space of the back-end server if HTML pages from that server contain programs (such as JavaScript or applets) with server-relative URLs to that directory. For example, if pages from the back-end server contain programs with a URL of form /path/..., do not create a junction name using /path.

Creating multiple WebSEAL junctions that point to the same back-end application server/port is not a secure junction configuration. Each junction can be control by unique ACLs. One junction secured with more permissive ACLs can compromise another junction secured with less permissive ACLs. This type of configuration can cause unintended control of access to resources and is therefore not a supported configuration strategy for Security Access Manager.

WebSEAL supports HTTP/1.1 across junctions.

Parent topic: Technical notes for using WebSEAL junctions

Adding multiple back-end servers to the same junction Adding multiple back-end servers to the same junction junctionsadding multiple back-end replica servers to a junctionback-end serversadding multiple to the same junction To increase high availability of the resources protected by Security Access Manager, you can junction multiple replica back-end servers to the same junction point. There can be any number of replica servers mounted at the same point. Multiple back-end servers added to the same junction point must be replica servers with identical (mirrored) Web document spaces.Multiple back-end servers added to the same junction point must use the same protocol.Do not add dissimilar servers to the same junction point.WebSEAL uses a least busy algorithm to determine which back-end replica server has the fewest number of request connections and forwards any new request to that server. Create the initial junction. For example:pdadmin> server task web1-webseald-cruz create -t tcp -h server1 /salesAdd an additional back-end server replica. For example:pdadmin> server task web1-webseald-cruz add -h server2 /salesFrom the primary Security Access Manager server Web space, test the access to pages belonging to the junctioned servers. You must be able to access these pages (subject to permissions) and the pages must appear consistent. If a page cannot be found occasionally, or if it changes occasionally, it means that page was not replicated properly. Check that the document exists and is identical in the document tree of both replicated servers.Technical notes for using WebSEAL junctions

Adding multiple back-end servers to the same junction

About this task

To increase high availability of the resources protected by Security Access Manager, you can junction multiple replica back-end servers to the same junction point. There can be any number of replica servers mounted at the same point.

Multiple back-end servers added to the same junction point must be replica servers with identical (mirrored) Web document spaces.

Multiple back-end servers added to the same junction point must use the same protocol.

Do not add dissimilar servers to the same junction point.

WebSEAL uses a least busy algorithm to determine which back-end replica server has the fewest number of request connections and forwards any new request to that server.

Procedure

Create the initial junction. For example:

pdadmin> server task web1-webseald-cruz create -t tcp -h server1 /sales

Add an additional back-end server replica. For example:

pdadmin> server task web1-webseald-cruz add -h server2 /sales

From the primary Security Access Manager server Web space, test the access to pages belonging to the junctioned servers. You must be able to access these pages (subject to permissions) and the pages must appear consistent. If a page cannot be found occasionally, or if it changes occasionally, it means that page was not replicated properly.

Check that the document exists and is identical in the document tree of both replicated servers.

Parent topic: Technical notes for using WebSEAL junctions

Exceptions to enforcing permissions across junctions Exceptions to enforcing permissions across junctions junctionsenforcing permissionsenforcing permissionsCertain Security Access Manager permissions are not enforceable across a junction. You cannot control, for example, the execution of a CGI script with the x permission, or a directory listing with the l permission. WebSEAL has no means of accurately determining whether or not a requested object on a back-end server is, for example, a CGI program file, a dynamic directory listing, or a regular HTTP object. Access to objects across junctions, including CGI programs and directory listings, is controlled only through the r permission. Technical notes for using WebSEAL junctions

Exceptions to enforcing permissions across junctions

Certain Security Access Manager permissions are not enforceable across a junction. You cannot control, for example, the execution of a CGI script with the x permission, or a directory listing with the l permission. WebSEAL has no means of accurately determining whether or not a requested object on a back-end server is, for example, a CGI program file, a dynamic directory listing, or a regular HTTP object.

Access to objects across junctions, including CGI programs and directory listings, is controlled only through the r permission.

Parent topic: Technical notes for using WebSEAL junctions

Certificate authentication across junctions Certificate authentication across junctions webseal-cert-keyfile-label stanza entryjunctionscertificate authenticationAt installation, WebSEAL is configured with a non-default test certificate. The test certificate is designated as the active server-side certificate by the webseal-cert-keyfile-label stanza entry in the [ssl] stanza of the WebSEAL configuration file.If a junctioned back-end application server requires WebSEAL to identify itself with a client-side certificate, you must first create, install, and label this certificate using the Local Management Interface (LMI). Then, configure the junction using the –K key-label option. See Mutually authenticated SSL junctions.If the junction is not configured with –K, GSKit handles a request for mutual authentication by automatically sending the “default” certificate contained in the keyfile database. If this is not the required response, you must ensure that there are no certificates marked as "default" (an asterisk mark) in the keyfile database (pdsrv.kdb, or the junctions keyfile, if a separate junction keyfile is configured). In summary: Identify all required certificates by label name.Do not mark any certificate in the keyfile database as "default".Control the WebSEAL server-side certificate response with the webseal-cert-keyfile-label stanza entry.Control the WebSEAL client-side certificate response through the –K junction option.Technical notes for using WebSEAL junctions

Certificate authentication across junctions

At installation, WebSEAL is configured with a non-default test certificate. The test certificate is designated as the active server-side certificate by the webseal-cert-keyfile-label stanza entry in the [ssl] stanza of the WebSEAL configuration file.

If a junctioned back-end application server requires WebSEAL to identify itself with a client-side certificate, you must first create, install, and label this certificate using the Local Management Interface (LMI). Then, configure the junction using the –K key-label option. See Mutually authenticated SSL junctions.

If the junction is not configured with –K, GSKit handles a request for mutual authentication by automatically sending the “default” certificate contained in the keyfile database. If this is not the required response, you must ensure that there are no certificates marked as "default" (an asterisk mark) in the keyfile database (pdsrv.kdb, or the junctions keyfile, if a separate junction keyfile is configured).

In summary:

Identify all required certificates by label name.

Do not mark any certificate in the keyfile database as "default".

Control the WebSEAL server-side certificate response with the webseal-cert-keyfile-label stanza entry.

Control the WebSEAL client-side certificate response through the –K junction option.

Parent topic: Technical notes for using WebSEAL junctions

Handling domain cookiesHandling domain cookiescookiesdomaindomain cookiesallow-backend-domain-cookies stanza entryThe allow-backend-domain-cookies stanza entry in the [junction] stanza of the WebSEAL configuration file controls how WebSEAL handles domain attributes in cookie headers. When this stanza entry value is set to "no" (default), WebSEAL performs "tail matching" to determine if the domain (contained as an attribute in the cookie header) is valid. If the domain in the cookie header is valid, the cookie is sent to the browser with the domain attribute removed from the cookie header. When a browser receives a cookie with no domain attribute, it can return the cookie only to the originating server. If "tail matching" determines that the domain in the cookie header is not valid, the cookie is not sent to the browser. The browser has no cookies to return.[junction] allow-backend-domain-cookies = noWhen this stanza entry value is set to "yes", WebSEAL does not perform "tail matching" and allows all cookies, regardless of the domain attribute value, to be sent to the browser. The browser can return the cookies to the appropriate server or servers.[junction] allow-backend-domain-cookies = yesCustomize the allow-backend-domain-cookies configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.{junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Technical notes for using WebSEAL junctions

Handling domain cookies

About this task

The allow-backend-domain-cookies stanza entry in the [junction] stanza of the WebSEAL configuration file controls how WebSEAL handles domain attributes in cookie headers.

When this stanza entry value is set to "no" (default), WebSEAL performs "tail matching" to determine if the domain (contained as an attribute in the cookie header) is valid. If the domain in the cookie header is valid, the cookie is sent to the browser with the domain attribute removed from the cookie header. When a browser receives a cookie with no domain attribute, it can return the cookie only to the originating server. If "tail matching" determines that the domain in the cookie header is not valid, the cookie is not sent to the browser. The browser has no cookies to return.

[junction]
allow-backend-domain-cookies = no

When this stanza entry value is set to "yes", WebSEAL does not perform "tail matching" and allows all cookies, regardless of the domain attribute value, to be sent to the browser. The browser can return the cookies to the appropriate server or servers.

[junction]
allow-backend-domain-cookies = yes

Procedure

Customize the allow-backend-domain-cookies configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

{junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Parent topic: Technical notes for using WebSEAL junctions

Supported HTTP versions for requests and responsesSupported HTTP versions for requests and responsesHTTP/1.1 responsesWebSEALHTTP/1.1 responsesjunctionsHTTP/1.0 and 1.1 responsesHTTP/1.0 requests are sent to junctioned back-end servers only if those servers return a status of 400 (Bad Request), return a status of 504 (HTTP version not supported), or if the client browser specifies HTTP/1.0 in the request.Otherwise, if the back-end server accepts HTTP/1.1, WebSEAL sends HTTP/1.1 requests.However, even when WebSEAL sends an HTTP/1.0 request to a junctioned back-end server (and the back-end server returns an HTTP/1.0 response), WebSEAL always returns an HTTP/1.1 response to the client browser.Technical notes for using WebSEAL junctions

Supported HTTP versions for requests and responses

HTTP/1.0 requests are sent to junctioned back-end servers only if those servers return a status of 400 (Bad Request), return a status of 504 (HTTP version not supported), or if the client browser specifies HTTP/1.0 in the request.

Otherwise, if the back-end server accepts HTTP/1.1, WebSEAL sends HTTP/1.1 requests.

However, even when WebSEAL sends an HTTP/1.0 request to a junctioned back-end server (and the back-end server returns an HTTP/1.0 response), WebSEAL always returns an HTTP/1.1 response to the client browser.

Parent topic: Technical notes for using WebSEAL junctions

Junctioned application with Web Portal ManagerJunctioned application with Web Portal ManagerWPMjunctioned applicationProblem: Web Portal Manager sends absolute or server-relative URLs in its Javascript. These addresses are not resolved successfully by the browser and require junction cookie information to complete the path name.Solution: If an application server with Web Portal Manager is junctioned to WebSEAL, you must use the –j option when creating this junction. The junction cookie provided by the –j option allows the browser (client) to successfully issue commands to Web Portal Manager. In addition to using the –j option, you must also use the –c iv_user,iv_creds option.Technical notes for using WebSEAL junctions

Junctioned application with Web Portal Manager

Problem: Web Portal Manager sends absolute or server-relative URLs in its Javascript. These addresses are not resolved successfully by the browser and require junction cookie information to complete the path name.

Solution: If an application server with Web Portal Manager is junctioned to WebSEAL, you must use the –j option when creating this junction. The junction cookie provided by the –j option allows the browser (client) to successfully issue commands to Web Portal Manager.

In addition to using the –j option, you must also use the –c iv_user,iv_creds option.

Parent topic: Technical notes for using WebSEAL junctions

How to generate a back-end server Web space (query_contents)How to generate a back-end server Web space (query_contents)query_contentsoverviewjunctionsquery_contentsThis section contains the following topics:Standard WebSEAL junctionsWebSEAL junctions overviewJunction management in the Local Management InterfaceManaging junctions with the pdadmin utilityStandard WebSEAL junction configurationTransparent path junctionsTechnical notes for using WebSEAL junctionsquery_contents overviewIf you want to use the Security Access Manager security service to protect the resources on a back-end application Web server, you must provide WebSEAL with information about the contents of the back-end Web space. query_contents componentsThe query_contents components are available through the LMI. Go to Manage System Settings > Secure Settings > File Downloads. Then, expand the isam directory.Installing and configuring query_contents on UNIX-based Web serversThe following steps describe the installation of query_contents on back-end UNIX-based Web servers.Installing and configuring query_contents on Windows-based Web serversThe following steps describe the installation of query_contents on back-end Windows-based Web servers.General process flow for query_contentsSecuring the query_contents program

How to generate a back-end server Web space (query_contents)

This section contains the following topics:

query_contents overview
If you want to use the Security Access Manager security service to protect the resources on a back-end application Web server, you must provide WebSEAL with information about the contents of the back-end Web space.

query_contents components
The query_contents components are available through the LMI. Go to Manage System Settings > Secure Settings > File Downloads. Then, expand the isam directory.

Installing and configuring query_contents on UNIX-based Web servers
The following steps describe the installation of query_contents on back-end UNIX-based Web servers.

Installing and configuring query_contents on Windows-based Web servers
The following steps describe the installation of query_contents on back-end Windows-based Web servers.

General process flow for query_contents

Securing the query_contents program

Parent topic: Standard WebSEAL junctions

Related concepts:

WebSEAL junctions overview

Junction management in the Local Management Interface

Standard WebSEAL junction configuration

Transparent path junctions

Related tasks:

Managing junctions with the pdadmin utility

Related reference:

Technical notes for using WebSEAL junctions

query_contents overviewquery_contents overviewIf you want to use the Security Access Manager security service to protect the resources on a back-end application Web server, you must provide WebSEAL with information about the contents of the back-end Web space. query_contentsoverviewA CGI program called query_contents provides this information. The query_contents program searches the back-end Web space contents and provides this inventory information to WebSEAL. A default version of the program comes with the WebSEAL installation, but must be manually installed on the back-end Web server. There are different program file types available, depending on whether the back-end server is running UNIX or Windows.The Object Space manager of the Web Portal Manager automatically runs query_contents any time the portion of the protected object space belonging to the junction is expanded in the Object Space management panel. When the Web Portal Manager knows about the contents of the back-end Web space, you can display this information and apply policy templates to appropriate objects.The pdadmin object show command uses the query_contents program to browse Web space and enables an administrator to identify resources to which a policy can be attached. In this way, pdadmin and query_contents are used to manage and control access to objects in the Security Access Manager object space.WebSEAL includes source files for query_contents, a sample configuration file, and an HTML help file. Administrators can use these files to configure query_contents and, when needed, to modify its behavior.How to generate a back-end server Web space (query_contents)Custom query_contents program

query_contents overview

If you want to use the Security Access Manager security service to protect the resources on a back-end application Web server, you must provide WebSEAL with information about the contents of the back-end Web space.

A CGI program called query_contents provides this information. The query_contents program searches the back-end Web space contents and provides this inventory information to WebSEAL. A default version of the program comes with the WebSEAL installation, but must be manually installed on the back-end Web server. There are different program file types available, depending on whether the back-end server is running UNIX or Windows.

The Object Space manager of the Web Portal Manager automatically runs query_contents any time the portion of the protected object space belonging to the junction is expanded in the Object Space management panel. When the Web Portal Manager knows about the contents of the back-end Web space, you can display this information and apply policy templates to appropriate objects.

The pdadmin object show command uses the query_contents program to browse Web space and enables an administrator to identify resources to which a policy can be attached. In this way, pdadmin and query_contents are used to manage and control access to objects in the Security Access Manager object space.

WebSEAL includes source files for query_contents, a sample configuration file, and an HTML help file. Administrators can use these files to configure query_contents and, when needed, to modify its behavior.

Custom query_contents program

Parent topic: How to generate a back-end server Web space (query_contents)

Custom query_contents programCustom query_contents programquery_contentscustom programWhen a query_contents program is run, WebSEAL sends a simple HTTP GET request to the program and expects a simple HTTP reply along with a response body containing the requested information. The query_contents program can be written in any language and can be hosted on any HTTP-compliant application server.query_contents overviewIf you want to use the Security Access Manager security service to protect the resources on a back-end application Web server, you must provide WebSEAL with information about the contents of the back-end Web space. Program inputsProgram outputs

Custom query_contents program

When a query_contents program is run, WebSEAL sends a simple HTTP GET request to the program and expects a simple HTTP reply along with a response body containing the requested information. The query_contents program can be written in any language and can be hosted on any HTTP-compliant application server.

Program inputs

Program outputs

Parent topic: query_contents overview

Program inputsProgram inputsprogram inputsinputsprogramThe query_contents program is called with an HTTP GET request with the following syntax: <URL>?dirlist=<resource root>where <URL> is the location of the query_contents program and <resource root> is the root of the object space that should be searched.The GET request is accompanied by an HTTP cookie with the name X_QUERY_CONTENTS_URIENCODED. This cookie contains a yes or no value to indicate whether the path is URI-encoded.The following sample is an example of a GET request that WebSEAL might send to a query_contents program: GET /appserver/cgi-bin/custom_query_contents.exe?dirlist=/directory Cookie: X_QUERY_CONTENTS_URIENCODED=noCustom query_contents program

Program inputs

The query_contents program is called with an HTTP GET request with the following syntax:

<URL>?dirlist=<resource root>

where <URL> is the location of the query_contents program and <resource root> is the root of the object space that should be searched.

The GET request is accompanied by an HTTP cookie with the name X_QUERY_CONTENTS_URIENCODED. This cookie contains a yes or no value to indicate whether the path is URI-encoded.

The following sample is an example of a GET request that WebSEAL might send to a query_contents program:

GET /appserver/cgi-bin/custom_query_contents.exe?dirlist=/directory
Cookie: X_QUERY_CONTENTS_URIENCODED=no

Parent topic: Custom query_contents program

Program outputsProgram outputsprogram outputsoutputsThe query_contents program must return a response that is UTF-8 encoded, and the response must include the following header: content-type: text/plain;charset=utf8The body of the response must contain one line with a return code followed by the directory listing, with one object or container name per line: <return-code> <file or directory> <file or directory> <file or directory>where <return-code> is 100, 102, or 103, as defined in the following table. Return codesQuery StatusDescriptionQUERY_STATUS_OK = 100The directory listing operation succeeded.QUERY_STATUS_NO_EXISTS = 102The directory queried does not exist.QUERY_STATUS_NOT_DIR = 103The directory queried is not a directory.Object names and containers in the response must follow these rules: Containers end in two forward slashes, for example,: /path/directory//Punctuation "." and ".." are not included in the directory entries.Object or container data must be UTF-8 encoded and then URI encoded.Custom query_contents program

Program outputs

The query_contents program must return a response that is UTF-8 encoded, and the response must include the following header:

content-type: text/plain;charset=utf8

The body of the response must contain one line with a return code followed by the directory listing, with one object or container name per line:

<return-code>
<file or directory>
<file or directory>
<file or directory>

where <return-code> is 100, 102, or 103, as defined in the following table.

Table 59. Return codes

Query Status | Description
QUERY_STATUS_OK = 100 | The directory listing operation succeeded.
QUERY_STATUS_NO_EXISTS = 102 | The directory queried does not exist.
QUERY_STATUS_NOT_DIR = 103 | The directory queried is not a directory.

Object names and containers in the response must follow these rules:

Containers end in two forward slashes, for example,: /path/directory//

Punctuation "." and ".." are not included in the directory entries.

Object or container data must be UTF-8 encoded and then URI encoded.

Parent topic: Custom query_contents program

query_contents components query_contents components The query_contents components are available through the LMI. Go to Manage System Settings > Secure Settings > File Downloads. Then, expand the isam directory.query_contents.exequery_contents.shquery_contents.cquery_contents.htmlquery_contents.cfgquery_contentsinstallingLMIQuery Site Contents management pageThe following table shows the query_contents components.Query_contents component descriptionsFileDescriptionquery_contents.exe(Windows)Main executable program for Windows systems. Install this file in the cgi-bin directory of the back-end Web server.query_contents.cfg(Windows)The Windows configuration file that identifies the document root for the Web server.query_contents.c(Windows)Source code for Windows systems. The source is provided in case you need to modify the behavior of query_contents. In most cases, this will not be necessary.query_contents.sh(UNIX)Main executable program for UNIX systems. Install this file in the cgi-bin directory of the back-end Web server.How to generate a back-end server Web space (query_contents)

query_contents components

The query_contents components are available through the LMI. Go to Manage System Settings > Secure Settings > File Downloads. Then, expand the isam directory.

The following table shows the query_contents components.

Table 60. Query_contents component descriptions

File
Description

query_contents.exe

(Windows)

Main executable program for Windows systems. Install this file in the cgi-bin directory of the back-end Web server.

query_contents.cfg

(Windows)

The Windows configuration file that identifies the document root for the Web server.

query_contents.c

(Windows)

Source code for Windows systems. The source is provided in case you need to modify the behavior of query_contents. In most cases, this will not be necessary.

query_contents.sh

(UNIX)

Main executable program for UNIX systems. Install this file in the cgi-bin directory of the back-end Web server.

Parent topic: How to generate a back-end server Web space (query_contents)

Installing and configuring query_contents on UNIX-based Web serversInstalling and configuring query_contents on UNIX-based Web serversThe following steps describe the installation of query_contents on back-end UNIX-based Web servers.query_contentsinstall and configure on UNIXUNIXquery_contentsIn the LMI, go to Secure Web Settings > Tools > Query Site Contents to locate the shell script named query_contents.sh. Ensure that the back-end Web server has a CGI directory correctly configured.For testing purposes, ensure that a valid document exists in the document root of the back-end Web server. Copy query_contents.sh into a functioning cgi-bin directory on the back-end Web server. Consult the appropriate documentation for the Web server to identify the location of this directory.You must specify query_contents.sh as the correct file name for WebSEAL to use by using the –q location option when creating a junction to the back-end Web server.The –q location option and argument provides WebSEAL with the correct name of the file and where to find the file. For example (entered as one line and assuming other options are additionally selected ):pdadmin> server task default-webseald-www.example.com create -t tcp -h host-name <...> -q /cgi-bin/query_contents.sh /junction-nameThe location argument value is used in the actual URL string that calls the query_contents program. For example:http://unix-machine-name/cgi-bin/query_contents.sh?dirlist=/Manually edit the script file to correctly specify the document root directory.Change the value of the DOCROOTDIR variable (default is /usr/local/html) to the document root of the back-end Web server. For example (IBM HTTP Server, version 6.0):ADD_TO_ROOT= DOCROOTDIR=/opt/IBMIHS/htdocs #ADD_TO_ROOT="cgi-bin//"The blank ADD_TO_ROOT line is required for the variable initialization.Additionally, if the back-end Web server's cgi-bin directory is not located below the document root on the Web server's file system, uncomment the line for the ADD_TO_ROOT variable. For example:ADD_TO_ROOT= DOCROOTDIR=/opt/IBMIHS/htdocs ADD_TO_ROOT="cgi-bin//"Set the UNIX execute bit for the administration account of the back-end Web server.How to generate a back-end server Web space (query_contents)Testing the configuration (UNIX)

Installing and configuring query_contents on UNIX-based Web servers

The following steps describe the installation of query_contents on back-end UNIX-based Web servers.

Procedure

In the LMI, go to Secure Web Settings > Tools > Query Site Contents to locate the shell script named query_contents.sh.

Ensure that the back-end Web server has a CGI directory correctly configured.

For testing purposes, ensure that a valid document exists in the document root of the back-end Web server.

Copy query_contents.sh into a functioning cgi-bin directory on the back-end Web server. Consult the appropriate documentation for the Web server to identify the location of this directory.

You must specify query_contents.sh as the correct file name for WebSEAL to use by using the –q location option when creating a junction to the back-end Web server.

The –q location option and argument provides WebSEAL with the correct name of the file and where to find the file. For example (entered as one line and assuming other options are additionally selected ):

pdadmin> server task default-webseald-www.example.com create -t tcp -h
host-name <...> -q /cgi-bin/query_contents.sh /junction-name

The location argument value is used in the actual URL string that calls the query_contents program. For example:

http://unix-machine-name/cgi-bin/query_contents.sh?dirlist=/

Manually edit the script file to correctly specify the document root directory.

Change the value of the DOCROOTDIR variable (default is /usr/local/html) to the document root of the back-end Web server. For example (IBM® HTTP Server, version 6.0):

ADD_TO_ROOT=
DOCROOTDIR=/opt/IBMIHS/htdocs
#ADD_TO_ROOT="cgi-bin//"

Note: The blank ADD_TO_ROOT line is required for the variable initialization.

Additionally, if the back-end Web server's cgi-bin directory is not located below the document root on the Web server's file system, uncomment the line for the ADD_TO_ROOT variable. For example:

ADD_TO_ROOT=
DOCROOTDIR=/opt/IBMIHS/htdocs
ADD_TO_ROOT="cgi-bin//"

Set the UNIX execute bit for the administration account of the back-end Web server.

Results

Testing the configuration (UNIX)

Parent topic: How to generate a back-end server Web space (query_contents)

Testing the configuration (UNIX)Testing the configuration (UNIX)UNIXconfiguration testtestingUNIX configurationFrom a command prompt on the back-end UNIX-based machine, execute the query_contents program from the CGI directory as follows:# query_contents dirlist=/You should see something similar to the following output:100 index.html cgi-bin// pics//The number 100 is a return status that indicates success. It is most important to see at least the number 100 as the first (and perhaps only) value.If you see an error code instead, the document root entry might be incorrect. Check the configuration of the query_contents.sh file and make sure that the document root is specified correctly. From a browser, enter the following URL:http://unix-machine-name/cgi-bin/query_contents.sh?dirlist=/This URL should return the same result as the preceding step. If it does not return this result, the CGI configuration of your Web server is not correct. See the server's documentation to correct the problem.Installing and configuring query_contents on UNIX-based Web serversThe following steps describe the installation of query_contents on back-end UNIX-based Web servers.

Testing the configuration (UNIX)

Procedure

From a command prompt on the back-end UNIX-based machine, execute the query_contents program from the CGI directory as follows:

# query_contents dirlist=/

You should see something similar to the following output:

100
index.html
cgi-bin//
pics//

The number 100 is a return status that indicates success. It is most important to see at least the number 100 as the first (and perhaps only) value.

If you see an error code instead, the document root entry might be incorrect. Check the configuration of the query_contents.sh file and make sure that the document root is specified correctly.

From a browser, enter the following URL:

http://unix-machine-name/cgi-bin/query_contents.sh?dirlist=/

This URL should return the same result as the preceding step. If it does not return this result, the CGI configuration of your Web server is not correct. See the server's documentation to correct the problem.

Parent topic: Installing and configuring query_contents on UNIX-based Web servers

Installing and configuring query_contents on Windows-based Web servers Installing and configuring query_contents on Windows-based Web servers The following steps describe the installation of query_contents on back-end Windows-based Web servers.query_contentsinstall and configure on Windowsquery_contents script location (-q)junctionsquery_contents script location (-q)Locate the executable program named query_contents.exe and the configuration file named query_contents.cfg in the LMI. Go to Secure Web Settings > Tools > Query Site Contents.Ensure that the back-end Web server has a CGI directory correctly configured.For testing purposes, ensure that a valid document exists in the document root of the back-end Web server. Copy query_contents.exe into the cgi-bin directory of the back-end Web server. Consult the appropriate documentation for the Web server to identify the location of this directory.Copy query_contents.cfg into the "Windows" directory.Default values for this directory are shown in the table below: Operating SystemWindows DirectoryWindowsc:\windowsEdit the query_contents.cfg file to correctly specify the document root directory for the back-end Web server. The file contains a default value for the IBM HTTP Server (version 6.0):[server] docroot="C:/Program Files/IBM HTTP Server/htdocs/en_US"You must specify query_contents.exe as the correct file name for WebSEAL to use by using the –q location option when creating a junction to the back-end Web server.The –q location option and argument provides WebSEAL with the correct name of the file and where to find the file. For example (entered as one line and assuming other options are additionally selected):pdadmin> server task default-webseald-www.example.com create -t tcp -h host-name <...> -q /cgi-bin/query_contents.exe \junction-nameThe location argument value is used in the actual URL string that calls the query_contents program. For example:http://windows-machine-name/cgi-bin/query_contents.exe?dirlist=/How to generate a back-end server Web space (query_contents)Testing the configuration (Windows)

Installing and configuring query_contents on Windows-based Web servers

The following steps describe the installation of query_contents on back-end Windows-based Web servers.

Procedure

Locate the executable program named query_contents.exe and the configuration file named query_contents.cfg in the LMI. Go to Secure Web Settings > Tools > Query Site Contents.

Ensure that the back-end Web server has a CGI directory correctly configured.

For testing purposes, ensure that a valid document exists in the document root of the back-end Web server.

Copy query_contents.exe into the cgi-bin directory of the back-end Web server. Consult the appropriate documentation for the Web server to identify the location of this directory.

Copy query_contents.cfg into the "Windows" directory.

Default values for this directory are shown in the table below:

Operating System
Windows Directory

Windows

c:\windows

Edit the query_contents.cfg file to correctly specify the document root directory for the back-end Web server. The file contains a default value for the IBM® HTTP Server (version 6.0):

[server]
docroot="C:/Program Files/IBM HTTP Server/htdocs/en_US"

You must specify query_contents.exe as the correct file name for WebSEAL to use by using the –q location option when creating a junction to the back-end Web server.

The –q location option and argument provides WebSEAL with the correct name of the file and where to find the file. For example (entered as one line and assuming other options are additionally selected):

pdadmin> server task default-webseald-www.example.com create -t tcp -h
		host-name <...> -q /cgi-bin/query_contents.exe \junction-name

The location argument value is used in the actual URL string that calls the query_contents program. For example:

http://windows-machine-name/cgi-bin/query_contents.exe?dirlist=/

Testing the configuration (Windows)

Parent topic: How to generate a back-end server Web space (query_contents)

Testing the configuration (Windows)Testing the configuration (Windows)Windowsconfiguration testtestingWindows configurationFrom an MS-DOS prompt on the Windows machine, execute the query_contents program from the CGI directory as follows:MSDOS> query_contents dirlist=/You should see something similar to the following output:100 index.html cgi-bin// pics//The number 100 is a return status that indicates success. It is most important to see at least the number 100 as the first (and perhaps only) value.If you see an error code instead, then the configuration file is not in the correct place, or does not contain a valid document root entry. Check the configuration of the query_contents.cfg file and make sure that the document root exists.From a browser, enter the following URL:http://windows-machine-name/cgi-bin/query_contents.exe?dirlist=/This URL should return the same result as the preceding step. If it does not return this result, the CGI configuration of your Web server is not correct. See the server's documentation to correct the problem.Installing and configuring query_contents on Windows-based Web serversThe following steps describe the installation of query_contents on back-end Windows-based Web servers.

Testing the configuration (Windows)

Procedure

From an MS-DOS prompt on the Windows machine, execute the query_contents program from the CGI directory as follows:

MSDOS> query_contents dirlist=/

You should see something similar to the following output:

100
index.html
cgi-bin//
pics//

The number 100 is a return status that indicates success. It is most important to see at least the number 100 as the first (and perhaps only) value.

If you see an error code instead, then the configuration file is not in the correct place, or does not contain a valid document root entry. Check the configuration of the query_contents.cfg file and make sure that the document root exists.

From a browser, enter the following URL:

http://windows-machine-name/cgi-bin/query_contents.exe?dirlist=/

This URL should return the same result as the preceding step. If it does not return this result, the CGI configuration of your Web server is not correct. See the server's documentation to correct the problem.

Parent topic: Installing and configuring query_contents on Windows-based Web servers

General process flow for query_contents General process flow for query_contents query_contentsprocess flowprocess flowquery_contentsThe job of query_contents is to return the contents of directories included in a URL request.For example, to get the contents of the root directory of a server's Web space, the browser runs query_contents on a URL such as (UNIX example): http://back-end-server/cgi-bin/query_contents.sh?dirlist=/The query_contents script performs the following actions: Reads the configured value for the DOCROOTDIR variable.Reads the value of the QUERY_STRING variable from the requested URL to obtain the requested operation and get the object path. The operation value is stored in the OPERATION variable. The object path value is stored in the $OBJPATH variable. In the example, the value of the OPERATION variable is dirlist. The value of the OBJPATH variable is /. Performs a directory listing (DO) on the object path and sends the results to standard output for use by the Security Access Manager server. Entries that indicate subdirectories have a double slash (//) appended to them. Typical output looks like: 100 index.html cgi-bin// pics// The number 100 is a return status that indicates success.How to generate a back-end server Web space (query_contents)

General process flow for query_contents

The job of query_contents is to return the contents of directories included in a URL request.

For example, to get the contents of the root directory of a server's Web space, the browser runs query_contents on a URL such as (UNIX example):

http://back-end-server/cgi-bin/query_contents.sh?dirlist=/

The query_contents script performs the following actions:

Reads the configured value for the DOCROOTDIR variable.

Reads the value of the QUERY_STRING variable from the requested URL to obtain the requested operation and get the object path.

The operation value is stored in the OPERATION variable. The object path value is stored in the $OBJPATH variable. In the example, the value of the OPERATION variable is dirlist. The value of the OBJPATH variable is /.

Performs a directory listing (DO) on the object path and sends the results to standard output for use by the Security Access Manager server. Entries that indicate subdirectories have a double slash (//) appended to them.

Typical output looks like:

100
index.html
cgi-bin//
pics//

The number 100 is a return status that indicates success.

Parent topic: How to generate a back-end server Web space (query_contents)

Securing the query_contents programSecuring the query_contents programquery_contentssecuringsecurityquery_contents The query_contents CGI program is used by Security Access Manager to display junctioned Web server object spaces in the Web Portal Manager. It is very important to secure this file to prevent unauthorized users from running it. You must set a security policy that allows only the policy server (pdmgrd) identity to have access to the query_contents program. The following example ACL (query_contents_acl) meets this criteria:group ivmgrd-servers Tluser sec_master dbxTrlcamUse the pdadmin utility to attach this ACL to the query_contents.sh (UNIX) or query_contents.exe (Windows) object on the junctioned servers. For example (UNIX): pdadmin> acl attach /WebSEAL/host/junction-name/cgi-bin/query_contents.sh query_contents_aclHow to generate a back-end server Web space (query_contents)

Securing the query_contents program

About this task

The query_contents CGI program is used by Security Access Manager to display junctioned Web server object spaces in the Web Portal Manager. It is very important to secure this file to prevent unauthorized users from running it.

Procedure

You must set a security policy that allows only the policy server (pdmgrd) identity to have access to the query_contents program. The following example ACL (query_contents_acl) meets this criteria:

group ivmgrd-servers Tl

user sec_master dbxTrlcam

Use the pdadmin utility to attach this ACL to the query_contents.sh (UNIX) or query_contents.exe (Windows) object on the junctioned servers. For example (UNIX):

pdadmin> acl attach /WebSEAL/host/junction-name/cgi-bin/query_contents.sh
query_contents_acl

Parent topic: How to generate a back-end server Web space (query_contents)

Advanced junction configurationAdvanced junction configurationMost standard junction options are also supported by virtual host junctions.junctionsadvanced configurationadvanced junction configurationTopic Index:Standard WebSEAL JunctionsMutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Advanced junction configuration

Most standard junction options are also supported by virtual host junctions.

Topic Index:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Forcing a new junction

Use of /pkmslogout with virtual host junctions
Policies can be attached to pkmslogout, but WebSEAL does not always apply the policies.

Junction throttling

Management of cookies
WebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser.

Passing of session cookies to junctioned portal servers
A Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server.

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

Bypassing buffering on a per-resource basis
WebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.

WebSockets
WebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Parent topic: Standard WebSEAL Junctions

Mutually authenticated SSL junctions Mutually authenticated SSL junctions mutually authenticated junctionsjunctionsmutually authenticated (-D, -K, -B, -U, -W)SSLjunctionsmutually authenticatedThis section contains the following topics:Advanced junction configurationMost standard junction options are also supported by virtual host junctions.TCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.Mutually authenticated SSL junctions process summaryWebSEAL supports mutual authentication between a WebSEAL server and a back-end server over an SSL junction (–t ssl or –t sslproxy or –t mutual).Validation of the back-end server certificateMatching the distinguished name (DN)Authentication with a client certificateAuthentication with a BA header

Mutually authenticated SSL junctions

This section contains the following topics:

Mutually authenticated SSL junctions process summary
WebSEAL supports mutual authentication between a WebSEAL server and a back-end server over an SSL junction (–t ssl or –t sslproxy or –t mutual).

Validation of the back-end server certificate

Matching the distinguished name (DN)

Authentication with a client certificate

Authentication with a BA header

Parent topic: Advanced junction configuration

Related concepts:

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Mutually authenticated SSL junctions process summaryMutually authenticated SSL junctions process summaryWebSEAL supports mutual authentication between a WebSEAL server and a back-end server over an SSL junction (–t ssl or –t sslproxy or –t mutual).SSLjunctionsmutually authenticatedprocess summary The following outline summarizes the supported functionality for mutual authentication over SSL (command options are listed where appropriate): WebSEAL authenticates the back-end server (normal SSL process) WebSEAL validates the server certificate from the back-end server. See Validation of the back-end server certificate.WebSEAL verifies the distinguished name (DN) contained in the certificate (–D) (optional, but provides a higher level of security). See Matching the distinguished name (DN).Back-end server authenticates WebSEAL (two methods) Back-end server validates client certificate from WebSEAL (–K). See Authentication with a client certificate.Back-end server validates WebSEAL identity information in a basic Authentication (BA) header (–B, –U, –W). See Authentication with a BA header.The command options that control mutual authentication over SSL provide the following features: You can specify client certificate or BA authentication method.You can apply authentication methods on a per-junction basis.Special considerations for combining the –b options (for handling BA information) with mutual authentication over SSL are described in Client identity information across junctionsA junction can be set up to specify client identity information in BA headers. You must know the available options so that you can use the correct combination of options..Mutual authentication over SSL virtual host junctions is also supported. Mutually authenticated SSL junctions

Mutually authenticated SSL junctions process summary

WebSEAL supports mutual authentication between a WebSEAL server and a back-end server over an SSL junction (–t ssl or –t sslproxy or –t mutual).

The following outline summarizes the supported functionality for mutual authentication over SSL (command options are listed where appropriate):

WebSEAL authenticates the back-end server (normal SSL process)

WebSEAL validates the server certificate from the back-end server.

See Validation of the back-end server certificate.

WebSEAL verifies the distinguished name (DN) contained in the certificate (–D) (optional, but provides a higher level of security).

See Matching the distinguished name (DN).

Back-end server authenticates WebSEAL (two methods)

Back-end server validates client certificate from WebSEAL (–K).

See Authentication with a client certificate.

Back-end server validates WebSEAL identity information in a basic Authentication (BA) header (–B, –U, –W).

See Authentication with a BA header.

The command options that control mutual authentication over SSL provide the following features:

You can specify client certificate or BA authentication method.

You can apply authentication methods on a per-junction basis.

Special considerations for combining the –b options (for handling BA information) with mutual authentication over SSL are described in Client identity information across junctions.

Mutual authentication over SSL virtual host junctions is also supported.

Parent topic: Mutually authenticated SSL junctions

Validation of the back-end server certificateValidation of the back-end server certificateiKeymanSSL junctionsback-end serverscertificatesvalidationWebSEAL verifies a back-end server certificate according to the standard SSL protocol. The back-end server sends its server certificate to WebSEAL. WebSEAL validates the server certificate against a pre-defined list of root Certificate Authority (CA) certificates. The Certificate Authority (CA) certificates that form the trust chain for the application server certificate (from the signing CA up to and including the root certificate) must be included in the key database in use by WebSEAL.You use the LMI to create and manage the database of root CA certificates. Mutually authenticated SSL junctions

Validation of the back-end server certificate

WebSEAL verifies a back-end server certificate according to the standard SSL protocol. The back-end server sends its server certificate to WebSEAL. WebSEAL validates the server certificate against a pre-defined list of root Certificate Authority (CA) certificates.

The Certificate Authority (CA) certificates that form the trust chain for the application server certificate (from the signing CA up to and including the root certificate) must be included in the key database in use by WebSEAL.

You use the LMI to create and manage the database of root CA certificates.

Parent topic: Mutually authenticated SSL junctions

Matching the distinguished name (DN) Matching the distinguished name (DN) junctionsDistinuguied Name (DN) matching (-D)distinguished name (DN)matchingYou can enhance server-side certificate verification through distinguished name (DN) matching. To enable server DN matching, you must specify the back-end server DN when you create the SSL junction to that server. Although DN matching is an optional configuration, it provides a higher degree of security with mutual authentication over SSL junctions.During server-side certificate verification, the DN contained in the certificate is compared with the DN defined by the junction. The connection to the back-end server fails if the two DNs do not match.To enable the server DN matching, specify the back-end server DN when you create the SSL-based junction using the –D "DN" option. To preserve any blank spaces in the string, surround the DN string with double quotation marks. For example: -D "CN=Access Manager,OU=SecureWay,O=Tivoli,C=US"The –D option is appropriate only when used with the –K or –B option.Mutually authenticated SSL junctions

Matching the distinguished name (DN)

About this task

You can enhance server-side certificate verification through distinguished name (DN) matching. To enable server DN matching, you must specify the back-end server DN when you create the SSL junction to that server. Although DN matching is an optional configuration, it provides a higher degree of security with mutual authentication over SSL junctions.

During server-side certificate verification, the DN contained in the certificate is compared with the DN defined by the junction. The connection to the back-end server fails if the two DNs do not match.

Procedure

To enable the server DN matching, specify the back-end server DN when you create the SSL-based junction using the –D "DN" option. To preserve any blank spaces in the string, surround the DN string with double quotation marks. For example:

-D "CN=Access Manager,OU=SecureWay,O=Tivoli,C=US"

The –D option is appropriate only when used with the –K or –B option.

Parent topic: Mutually authenticated SSL junctions

Authentication with a client certificate Authentication with a client certificate junctionsWebSEAL client certificate (-K)client certificate (WebSEAL) (-K)clientscertificatesauthenticationauthenticationclient certificateUse the –K option to enable WebSEAL to authenticate to the junctioned back-end server using its client certificate. -K "key_label" The conditions for this scenario include: The back-end server is set up to require verification of WebSEAL's identity with a client certificate.Using the LMI to create, label, and store a special key that is used solely as WebSEAL's client certificate when authenticating to a junctioned back-end server.For greater security, additionally configure the junction for DN matching (–D).The –K option uses an argument that specifies the key-label of the required certificate as stored in the GSKit key database. Use the LMI to add new certificates to the key database.You must surround the key-label argument with quotation marks. For example: -K "cert1_Tiv"If the key is located on cryptographic hardware, you must specify the WebSEAL token device with the key label. -K "token_name:key-label"For example:-K "websealtoken:junctionkey"See Configuration of the WebSEAL key database file.Mutually authenticated SSL junctions

Authentication with a client certificate

Use the –K option to enable WebSEAL to authenticate to the junctioned back-end server using its client certificate.

-K "key_label"

The conditions for this scenario include:

The back-end server is set up to require verification of WebSEAL's identity with a client certificate.

Using the LMI to create, label, and store a special key that is used solely as WebSEAL's client certificate when authenticating to a junctioned back-end server.

For greater security, additionally configure the junction for DN matching (–D).

The –K option uses an argument that specifies the key-label of the required certificate as stored in the GSKit key database. Use the LMI to add new certificates to the key database.

You must surround the key-label argument with quotation marks. For example:

-K "cert1_Tiv"

If the key is located on cryptographic hardware, you must specify the WebSEAL token device with the key label.

-K "token_name:key-label"

For example:

-K "websealtoken:junctionkey"

See Configuration of the WebSEAL key database file.

Parent topic: Mutually authenticated SSL junctions

Authentication with a BA header Authentication with a BA header junctionsauthentication with BA header (-B, -U, -W)BA header authenticationUse the –B–U "username"–W "password" option to enable WebSEAL authentication using basic authentication. -B -U "username" -W "password" The conditions for this scenario include: The back-end server is set up to require verification of WebSEAL's identity with a BA header.Do not configure the junction with any –b option. (Internally, however, the –B option uses –b filter.)WebSEAL is configured to pass its identity information in a BA header to authenticate to the back-end server.For greater security, additionally configure the junction for DN matching (–D).You must surround the user name and password arguments with double quotation marks. For example: -U "WS1" -W "abCde"Mutually authenticated SSL junctions

Authentication with a BA header

Use the –B–U "username"–W "password" option to enable WebSEAL authentication using basic authentication.

-B -U "username" -W "password"

The conditions for this scenario include:

The back-end server is set up to require verification of WebSEAL's identity with a BA header.

Do not configure the junction with any –b option. (Internally, however, the –B option uses –b filter.)

WebSEAL is configured to pass its identity information in a BA header to authenticate to the back-end server.

For greater security, additionally configure the junction for DN matching (–D).

You must surround the user name and password arguments with double quotation marks. For example:

-U "WS1" -W "abCde"

Parent topic: Mutually authenticated SSL junctions

TCP and SSL proxy junctions TCP and SSL proxy junctions junctionsproxy junctions (-H, -P)proxyjunctionsTCP proxy junctionsSSL proxy junctionsYou can create WebSEAL junctions that allow communication to traverse network topologies that use HTTP or HTTPS proxy servers. You can configure the junction to handle requests as standard TCP communication or protected SSL communication.The create command requires one of the following arguments to the type option to establish either a TCP-based or SSL-based junction through a proxy server: –t tcpproxy–t sslproxyBoth create and add commands require the following options and arguments to identify the proxy server and the target Web server:Options for the create and add commandsOptionsDescription–H host-nameThe DNS host name or IP address of the proxy server.–P portThe TCP port of the proxy server.–h host-nameThe DNS host name or IP address of the target Web server.–p portThe TCP port of target Web server. Default is 80 for TCP junctions; 443 for SSL junctions.Example TCP proxy junction (entered as one line): pdadmin> server task web1-webseald-cruz create -t tcpproxy -H clipper -P 8081 -h www.ibm.com -p 80 /ibmExample SSL proxy junction (entered as one line): pdadmin> server task web1-webseald-cruz create -t sslproxy -H clipper -P 8081 -h www.ibm.com -p 443 /ibmExample proxy junctionExample proxy junctionTCP and SSL proxy virtual host junctions are also supported. Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

TCP and SSL proxy junctions

You can create WebSEAL junctions that allow communication to traverse network topologies that use HTTP or HTTPS proxy servers. You can configure the junction to handle requests as standard TCP communication or protected SSL communication.

The create command requires one of the following arguments to the type option to establish either a TCP-based or SSL-based junction through a proxy server:

–t tcpproxy

–t sslproxy

Both create and add commands require the following options and arguments to identify the proxy server and the target Web server:

Table 61. Options for the create and add commands

Options | Description
–H host-name | The DNS host name or IP address of the proxy server.
–P port | The TCP port of the proxy server.
–h host-name | The DNS host name or IP address of the target Web server.
–p port | The TCP port of target Web server. Default is 80 for TCP junctions; 443 for SSL junctions.

Example TCP proxy junction (entered as one line):

pdadmin> server task web1-webseald-cruz create -t tcpproxy
-H clipper -P 8081 -h www.ibm.com -p 80 /ibm

Example SSL proxy junction (entered as one line):

pdadmin> server task web1-webseald-cruz create -t sslproxy
-H clipper -P 8081 -h www.ibm.com -p 443 /ibm

Figure 29. Example proxy junction

TCP and SSL proxy virtual host junctions are also supported.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

WebSEAL-to-WebSEAL junctions over SSL WebSEAL-to-WebSEAL junctions over SSL junctionsWebSEAL-to-WebSEAL (-C)junction cookiespreventing naming conflictscookiesjunctionpreventing naming conflictshostname-junction-cookie stanza entryWebSEAL to WebSEAL junctionshostname-junction-cookie stanza entrySecurity Access Manager supports SSL junctions between a front-end WebSEAL server and a back-end WebSEAL server. Use the –C option with the create command to junction the two WebSEAL servers over SSL and provide mutual authentication.WebSEAL-to-WebSEAL junction scenarioWebSEAL-to-WebSEAL junction scenarioExample: pdadmin> server task web1-webseald-cruz create -t ssl -C -h serverA /jctAMutual authentication occurs in the following two stages: The SSL protocol allows the back-end WebSEAL server to authenticate to the front-end WebSEAL server through its server certificate. The –C option enables the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server in a Basic Authentication (BA) header.Additionally, the –C option enables single signon functionality provided by the –c option. The –c option allows you to place Security Access Manager-specific client identity and group membership information into the HTTP header of the request destined for the back-end WebSEAL server. The header names include iv-user, iv-groups, and iv-creds. See Client identity in HTTP headers (–c)Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers..The following conditions apply to WebSEAL-to-WebSEAL junctions: The junction is appropriate only with the –t ssl or –t sslproxy junction type.Both WebSEAL servers must share a common user registry. This configuration allows the back-end WebSEAL server to authenticate the front-end WebSEAL server identity information.If the WebSEAL-to-WebSEAL junction and the back-end application server junction both use the –j junction option (for junction cookies), a naming conflict can occur between the two junction cookies created by each of the two WebSEAL servers. (Refer to the diagram at the beginning of this section.) To prevent this conflict, you must configure the intermediary WebSEAL server (WebSEAL 2 in the diagram) to uniquely identify its junction cookie. On the intermediary WebSEAL server only, set the value of the hostname-junction-cookie stanza entry in the [script-filtering] stanza of the WebSEAL configuration file to "yes" (default is "no"): [script-filtering] hostname-junction-cookie = yes Junction cookies allow WebSEAL to handle server-relative URLs generated on the client-side. These URLs lack knowledge of the junction point of the destination application. The junction cookie provides this information. For complete information on junction cookies, see Modification of server-relative URLs with junction cookies.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

WebSEAL-to-WebSEAL junctions over SSL

Security Access Manager supports SSL junctions between a front-end WebSEAL server and a back-end WebSEAL server. Use the –C option with the create command to junction the two WebSEAL servers over SSL and provide mutual authentication.

Figure 30. WebSEAL-to-WebSEAL junction scenario

Example:

pdadmin> server task web1-webseald-cruz create -t ssl -C -h serverA /jctA

Mutual authentication occurs in the following two stages:

The SSL protocol allows the back-end WebSEAL server to authenticate to the front-end WebSEAL server through its server certificate.

The –C option enables the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server in a Basic Authentication (BA) header.

Additionally, the –C option enables single signon functionality provided by the –c option. The –c option allows you to place Security Access Manager-specific client identity and group membership information into the HTTP header of the request destined for the back-end WebSEAL server. The header names include iv-user, iv-groups, and iv-creds. See Client identity in HTTP headers (–c).

The following conditions apply to WebSEAL-to-WebSEAL junctions:

The junction is appropriate only with the –t ssl or –t sslproxy junction type.

Both WebSEAL servers must share a common user registry. This configuration allows the back-end WebSEAL server to authenticate the front-end WebSEAL server identity information.

If the WebSEAL-to-WebSEAL junction and the back-end application server junction both use the –j junction option (for junction cookies), a naming conflict can occur between the two junction cookies created by each of the two WebSEAL servers. (Refer to the diagram at the beginning of this section.) To prevent this conflict, you must configure the intermediary WebSEAL server (WebSEAL 2 in the diagram) to uniquely identify its junction cookie. On the intermediary WebSEAL server only, set the value of the hostname-junction-cookie stanza entry in the [script-filtering] stanza of the WebSEAL configuration file to "yes" (default is "no"):

[script-filtering]
hostname-junction-cookie = yes

Junction cookies allow WebSEAL to handle server-relative URLs generated on the client-side. These URLs lack knowledge of the junction point of the destination application. The junction cookie provides this information. For complete information on junction cookies, see Modification of server-relative URLs with junction cookies.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Stateful junctionsStateful junctionsjunctionsstatefulstateful junctionsoverviewThis section contains the following topics.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.Stateful junction conceptsConfiguration of stateful junctionsSpecifying back-end server UUIDs for stateful junctionsHandling an unavailable stateful server

Stateful junctions

This section contains the following topics.

Stateful junction concepts

Configuration of stateful junctions

Specifying back-end server UUIDs for stateful junctions

Handling an unavailable stateful server

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Stateful junction concepts Stateful junction concepts stateful junctionsconceptsjunctionsstateful junction support (-s, -u)Most Web-enabled applications maintain a "state" for a sequence of HTTP requests from a client. This state is used, for example, to: Track a user's progress through the fields in a data entry form generated by a CGI programMaintain a user's context when performing a series of database inquiriesMaintain a list of items in an online shopping cart application where a user randomly browses and selects items to purchaseBack-end servers that run Web-enabled applications can be replicated in order to improve performance through load sharing. By default, Security Access Manager balances back-end server load by distributing requests across all available replicated servers. Security Access Manager uses a "least-busy" algorithm. This algorithm directs each new request to the server with the fewest connections already in progress.However, when WebSEAL processes a request over a stateful junction, WebSEAL must ensure that all subsequent requests from that client during that session are forwarded to the same server, and not distributed among the other replicated back-end servers according to the load balancing rules.Stateful junctions

Stateful junction concepts

Most Web-enabled applications maintain a "state" for a sequence of HTTP requests from a client. This state is used, for example, to:

Track a user's progress through the fields in a data entry form generated by a CGI program

Maintain a user's context when performing a series of database inquiries

Maintain a list of items in an online shopping cart application where a user randomly browses and selects items to purchase

Back-end servers that run Web-enabled applications can be replicated in order to improve performance through load sharing. By default, Security Access Manager balances back-end server load by distributing requests across all available replicated servers. Security Access Manager uses a "least-busy" algorithm. This algorithm directs each new request to the server with the fewest connections already in progress.

However, when WebSEAL processes a request over a stateful junction, WebSEAL must ensure that all subsequent requests from that client during that session are forwarded to the same server, and not distributed among the other replicated back-end servers according to the load balancing rules.

Parent topic: Stateful junctions

Configuration of stateful junctionsConfiguration of stateful junctionsstateful junctionsconfigurationUse the pdadmin server task create command with the –s option to override load balancing rules and create a stateful junction. A stateful junction ensures that a client's requests are forwarded to the same server throughout an entire session. When the initial client request occurs over a stateful junction, WebSEAL places a cookie on the client system that contains the UUID of the designated back-end server. When the client makes future requests to the same resource during the same session, the cookie's UUID information ensures that the requests are consistently routed to the same back-end server.The –s option is appropriate for a single front-end WebSEAL server with multiple back-end servers junctioned at the same junction point. Note that as soon as the initial junction is created as stateful, the pdadmin server task add command is used without the –s option to junction the remaining replicated back-end servers to the same junction point.Stateful virtual host junctions are also supported. If the scenario involves multiple front-end WebSEAL servers, all junctioned to the same back-end servers, you must use the –u option to correctly specify each back-end server UUID to each front-end WebSEAL server. See Specifying back-end server UUIDs for stateful junctions.You can also control how WebSEAL handles a stateful server that becomes unavailable. See Handling an unavailable stateful server.Stateful junctions

Configuration of stateful junctions

Use the pdadmin server task create command with the –s option to override load balancing rules and create a stateful junction. A stateful junction ensures that a client's requests are forwarded to the same server throughout an entire session. When the initial client request occurs over a stateful junction, WebSEAL places a cookie on the client system that contains the UUID of the designated back-end server. When the client makes future requests to the same resource during the same session, the cookie's UUID information ensures that the requests are consistently routed to the same back-end server.

The –s option is appropriate for a single front-end WebSEAL server with multiple back-end servers junctioned at the same junction point. Note that as soon as the initial junction is created as stateful, the pdadmin server task add command is used without the –s option to junction the remaining replicated back-end servers to the same junction point.

Stateful virtual host junctions are also supported.

If the scenario involves multiple front-end WebSEAL servers, all junctioned to the same back-end servers, you must use the –u option to correctly specify each back-end server UUID to each front-end WebSEAL server. See Specifying back-end server UUIDs for stateful junctions.

You can also control how WebSEAL handles a stateful server that becomes unavailable. See Handling an unavailable stateful server.

Parent topic: Stateful junctions

Specifying back-end server UUIDs for stateful junctionsSpecifying back-end server UUIDs for stateful junctionsstateful junctionsback-end server UUIDsjunctionsspecify back-end UUID (-u) When a new junction is created to a back-end Web application server, WebSEAL normally generates a Unique Universal Identifier (UUID) to identify that back-end server. This UUID is used internally and also to maintain stateful junctions (create –s). When the initial client request occurs, WebSEAL places a cookie on the client system that contains the UUID of the designated back-end server. When the client makes future requests to the same resource, the cookie's UUID information ensures that the requests are consistently routed to the same back-end server. Stateful junctions use back-end server UUIDsStateful junctions use back-end server UUIDs The handling of stateful junctions becomes more complex when there are multiple front-end WebSEAL servers junctioned to multiple back-end servers. Normally, each junction between a front-end WebSEAL server to a back-end server generates a unique UUID for the back-end server. This means that a single back-end server will have a different UUID on each front-end WebSEAL server. Multiple front-end servers require a load balancing mechanism to distribute the load between the two servers. For example, an initial "state" could be established to a back-end server through WebSEAL server 1 using a specific UUID. However, if a future request from the same client is routed through WebSEAL server 2 by the load balancing mechanism, the "state" will no longer exist, unless WebSEAL server 2 uses the same UUID to identity the same back-end server. Normally, this will not be the case. The –u option allows you to supply the same UUID for a specific back-end server to each front-end WebSEAL server. The –u option is also supported on virtual host junctions. As an example, consider two replicated front-end WebSEAL servers, each with a stateful junction to two back-end servers. When you create the stateful junction between WebSEAL server 1 and back-end server 2, a unique UUID (UUID A) is generated to identify back-end server 2. However, when a stateful junction is created between WebSEAL server 2 and back-end server 2, a new and different UUID (UUID B) is generated to identify back-end server 2. Dissimilar UUIDsDissimilar UUIDs A "state" established between a client and back-end server 2, via WebSEAL server 1 will fail if a subsequent request from the client is routed through WebSEAL server 2. In the following figure, back-end server 1 is known by both WebSEAL-1 and WebSEAL-2 as UUID 1. Back-end server 2 is known by both WebSEAL-1 and WebSEAL-2 as UUID 2. Specifying back-end server UUIDs for stateful junctionsSpecifying back-end server UUIDs for stateful junctionsApply the following process for specifying a UUID during the creation of a junction:Create a junction from WebSEAL server 1 to each back-end server. Use create –s and add.List the UUID generated for each back-end server during step 1. Use show.Create a junction from WebSEAL server 2 to each back-end server and specify the UUIDs identified in Step 2. Use create –s –u and add –u.Stateful junctionsStateful junction example

Specifying back-end server UUIDs for stateful junctions

About this task

When a new junction is created to a back-end Web application server, WebSEAL normally generates a Unique Universal Identifier (UUID) to identify that back-end server. This UUID is used internally and also to maintain stateful junctions (create –s).

When the initial client request occurs, WebSEAL places a cookie on the client system that contains the UUID of the designated back-end server. When the client makes future requests to the same resource, the cookie's UUID information ensures that the requests are consistently routed to the same back-end server.

Figure 31. Stateful junctions use back-end server UUIDs

The handling of stateful junctions becomes more complex when there are multiple front-end WebSEAL servers junctioned to multiple back-end servers. Normally, each junction between a front-end WebSEAL server to a back-end server generates a unique UUID for the back-end server. This means that a single back-end server will have a different UUID on each front-end WebSEAL server.

Multiple front-end servers require a load balancing mechanism to distribute the load between the two servers. For example, an initial "state" could be established to a back-end server through WebSEAL server 1 using a specific UUID.

However, if a future request from the same client is routed through WebSEAL server 2 by the load balancing mechanism, the "state" will no longer exist, unless WebSEAL server 2 uses the same UUID to identity the same back-end server. Normally, this will not be the case.

The –u option allows you to supply the same UUID for a specific back-end server to each front-end WebSEAL server.

The –u option is also supported on virtual host junctions.

As an example, consider two replicated front-end WebSEAL servers, each with a stateful junction to two back-end servers. When you create the stateful junction between WebSEAL server 1 and back-end server 2, a unique UUID (UUID A) is generated to identify back-end server 2. However, when a stateful junction is created between WebSEAL server 2 and back-end server 2, a new and different UUID (UUID B) is generated to identify back-end server 2.

Figure 32. Dissimilar UUIDs

A "state" established between a client and back-end server 2, via WebSEAL server 1 will fail if a subsequent request from the client is routed through WebSEAL server 2.

In the following figure, back-end server 1 is known by both WebSEAL-1 and WebSEAL-2 as UUID 1. Back-end server 2 is known by both WebSEAL-1 and WebSEAL-2 as UUID 2.

Figure 33. Specifying back-end server UUIDs for stateful junctions

Procedure

Apply the following process for specifying a UUID during the creation of a junction:

Create a junction from WebSEAL server 1 to each back-end server. Use create –s and add.

List the UUID generated for each back-end server during step 1. Use show.

Create a junction from WebSEAL server 2 to each back-end server and specify the UUIDs identified in Step 2. Use create –s –u and add –u.

Stateful junction example

Parent topic: Stateful junctions

Stateful junction exampleStateful junction examplestateful junctionsexampleIn the following example, WebSEAL-1 instance is called WS1. Host name is host1.WebSEAL-2 instance is called WS2. Host name is host2.Back-end server 1 is called APP1Back-end server 2 is called APP2 pdadmin> server task WS1-webseald-host1 create -t tcp -h APP1 -s /mnt pdadmin> server task WS1-webseald-host1 add -h APP2 /mnt pdadmin> server task WS1-webseald-host1 show /mnt (output of this command reveals UUID1 and UUID2) pdadmin> server task WS2-webseald-host2 create -t tcp -h APP1 -u UUID1 -s /mnt pdadmin> server task WS2-webseald-host2 add -h APP2 -u UUID2 /mntWhen a client establishes a stateful connection with back-end server 2, it receives a cookie containing UUID2. This example now ensures that the client will always connect to back-end server 2, regardless of whether future requests are routed through WebSEAL-1 or WebSEAL-2.Specifying back-end server UUIDs for stateful junctions

Stateful junction example

In the following example,

WebSEAL-1 instance is called WS1. Host name is host1.

WebSEAL-2 instance is called WS2. Host name is host2.

Back-end server 1 is called APP1

Back-end server 2 is called APP2

pdadmin> server task WS1-webseald-host1 create -t tcp -h APP1 -s /mnt
pdadmin> server task WS1-webseald-host1 add -h APP2 /mnt
pdadmin> server task WS1-webseald-host1 show /mnt

(output of this command reveals UUID1 and UUID2)

pdadmin> server task WS2-webseald-host2 create -t tcp -h APP1 -u UUID1 -s /mnt
pdadmin> server task WS2-webseald-host2 add -h APP2 -u UUID2 /mnt

When a client establishes a stateful connection with back-end server 2, it receives a cookie containing UUID2. This example now ensures that the client will always connect to back-end server 2, regardless of whether future requests are routed through WebSEAL-1 or WebSEAL-2.

Parent topic: Specifying back-end server UUIDs for stateful junctions

Handling an unavailable stateful serverHandling an unavailable stateful serveruse-new-stateful-on-error stanza entrystateful serversYou can use the use-new-stateful-on-error stanza entry in the [junction] stanza of the WebSEAL configuration file to control how WebSEAL responds to a stateful server that becomes unavailable. When use-new-stateful-on-error is set to "yes" and the original server becomes unavailable during a session, WebSEAL directs the next request of the user to a new replica server on the same stateful junction. If a new replica server is found on that stateful junction, and is responsive to the request, WebSEAL sets a new stateful cookie on the browser of the user. Subsequent requests during this same session are directed to this same new server. When use-new-stateful-on-error is set to "no" and the original server becomes unavailable during a session, WebSEAL does not direct the subsequent requests of the user to a new replica server on the same stateful junction. Instead, WebSEAL returns an error and attempts to access the same server for subsequent requests by the user during this session. The "no" value is the default setting and maintains compatibility with versions of WebSEAL prior to version 6.0. For example: [junction] use-new-stateful-on-error = no To end the access attempts on an unresponsive server, the user must restart the browser, or the administrator must remove the unresponsive server. This configuration item may be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. For example: [junction:/WebApp]Stateful junctions

Handling an unavailable stateful server

About this task

You can use the use-new-stateful-on-error stanza entry in the [junction] stanza of the WebSEAL configuration file to control how WebSEAL responds to a stateful server that becomes unavailable.

When use-new-stateful-on-error is set to "yes" and the original server becomes unavailable during a session, WebSEAL directs the next request of the user to a new replica server on the same stateful junction. If a new replica server is found on that stateful junction, and is responsive to the request, WebSEAL sets a new stateful cookie on the browser of the user. Subsequent requests during this same session are directed to this same new server.

When use-new-stateful-on-error is set to "no" and the original server becomes unavailable during a session, WebSEAL does not direct the subsequent requests of the user to a new replica server on the same stateful junction. Instead, WebSEAL returns an error and attempts to access the same server for subsequent requests by the user during this session. The "no" value is the default setting and maintains compatibility with versions of WebSEAL prior to version 6.0. For example:

[junction]
use-new-stateful-on-error = no

To end the access attempts on an unresponsive server, the user must restart the browser, or the administrator must remove the unresponsive server.

This configuration item may be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. For example:

[junction:/WebApp]

Parent topic: Stateful junctions

Forcing a new junctionForcing a new junctionjunctionsforcing new junctions You must use the –f junction option when you want to force a new junction to overwrite an existing junction. The following example (WebSEAL instance name = cruz) illustrates this procedure: Log in to pdadmin: # pdadmin pdadmin> login Enter User ID: sec_master Enter Password: pdadmin>Use the server task list command to display all current junction points:pdadmin> server task web1-webseald-cruz list /Use the server task show command to display details of the junction:pdadmin> server task web1-webseald-cruz show / Junction point: / Type: Local Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Root Directory: /opt/pdweb/www/docs ...Create a new local junction to replace the current junction point (the -f option is required to force a new junction that overwrites an existing junction): pdadmin> server task web1-webseald-cruz create -t local -f -d /tmp/docs / Created junction at /List the new junction point:pdadmin> server task web1-webseald-cruz list /Display the details of this junction:pdadmin> server task web1-webseald-cruz show / Junction point: / Type: Local Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Root Directory: /tmp/docs ...The –f option is also supported on virtual host junctions. Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Forcing a new junction

About this task

You must use the –f junction option when you want to force a new junction to overwrite an existing junction.

The following example (WebSEAL instance name = cruz) illustrates this procedure:

Procedure

Log in to pdadmin:

# pdadmin
pdadmin> login
Enter User ID: sec_master
Enter Password:
pdadmin>

Use the server task list command to display all current junction points:

pdadmin> server task web1-webseald-cruz list
/

Use the server task show command to display details of the junction:

pdadmin> server task web1-webseald-cruz show /
Junction point: /
Type: Local
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Root Directory: /opt/pdweb/www/docs
...

Create a new local junction to replace the current junction point (the -f option is required to force a new junction that overwrites an existing junction):

pdadmin> server task web1-webseald-cruz create -t local -f -d /tmp/docs /
Created junction at /

List the new junction point:

pdadmin> server task web1-webseald-cruz list
/

Display the details of this junction:

pdadmin> server task web1-webseald-cruz show /
Junction point: /
Type: Local
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Root Directory: /tmp/docs
...

The –f option is also supported on virtual host junctions.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Bypassing buffering on a per-resource basis

Use of /pkmslogout with virtual host junctionsUse of /pkmslogout with virtual host junctionsUse of /pkmslogout with virtual host junctions in WebSEALPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.virtual host junctions/pkmslogoutallow-unauthenticated-logout[acnt-mgmt] stanza option For example, if a user authenticated to WebSEAL and tries to access pkmslogout, the pkmslogout page ends the user session without an authorization check. ACL policies are not applied to such requests. However, if a user has not authenticated to WebSEAL and tries to access pkmslogout, the request is treated as a normal request. WebSEAL conducts an authorization check. If the authorization check fails, the request proceeds as a normal authorization failure. In the default WebSEAL configuration, the user is prompted to login. If the authorization check passes, WebSEAL attempts to retrieve an object called /pkmslogout from the root junction, and this typically results in a 404 Not Found response from WebSEAL.The allow-unauthenticated-logout option in the [acnt-mgmt] stanza determines whether unauthenticated users are able to request the pkmslogout resource without authenticating first. If set to yes, WebSEAL behaves in the same manner whether the user logging out is authenticated or unauthenticated.There are several methods to achieve single logout using Security Access Manager. One method is to embed <IMG> or <IFRAME> HTML tags in a logout page so that the browser simultaneously logs the user out of multiple servers when the page is viewed. For example, the following HTML tags send requests to /pkmslogout on three different virtual hosts: <img src="https://www.example.com/pkmslogout" height="0" width="0"> <img src="https://sales.example.com/pkmslogout" height="0" width="0"> <img src="https://accts.example.com/pkmslogout" height="0" width="0"> If this technique is used for single logout, it can be beneficial to either attach ACLs to /pkmslogout or to use the [acnt-mgmt] allow-unauthenticated-logout option to control WebSEAL behavior. For more information about the allow-unauthenticated-logout option, see allow-unauthenticated-logoutUse the allow-unauthenticated-logout stanza entry to control whether unauthenticated users can request the pkmslogout resource..Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionJunction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Use of /pkmslogout with virtual host junctions

Policies can be attached to pkmslogout, but WebSEAL does not always apply the policies.

For example, if a user authenticated to WebSEAL and tries to access pkmslogout, the pkmslogout page ends the user session without an authorization check. ACL policies are not applied to such requests. However, if a user has not authenticated to WebSEAL and tries to access pkmslogout, the request is treated as a normal request. WebSEAL conducts an authorization check.

If the authorization check fails, the request proceeds as a normal authorization failure. In the default WebSEAL configuration, the user is prompted to login.

If the authorization check passes, WebSEAL attempts to retrieve an object called /pkmslogout from the root junction, and this typically results in a 404 Not Found response from WebSEAL.

The allow-unauthenticated-logout option in the [acnt-mgmt] stanza determines whether unauthenticated users are able to request the pkmslogout resource without authenticating first. If set to yes, WebSEAL behaves in the same manner whether the user logging out is authenticated or unauthenticated.

There are several methods to achieve single logout using Security Access Manager. One method is to embed <IMG> or <IFRAME> HTML tags in a logout page so that the browser simultaneously logs the user out of multiple servers when the page is viewed. For example, the following HTML tags send requests to /pkmslogout on three different virtual hosts:

<img src="https://www.example.com/pkmslogout" height="0" width="0">
<img src="https://sales.example.com/pkmslogout" height="0" width="0">
<img src="https://accts.example.com/pkmslogout" height="0" width="0">

If this technique is used for single logout, it can be beneficial to either attach ACLs to /pkmslogout or to use the [acnt-mgmt] allow-unauthenticated-logout option to control WebSEAL behavior. For more information about the allow-unauthenticated-logout option, see allow-unauthenticated-logout.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Junction throttlingJunction throttlingjunctionsjunction throttlingjunction throttlingoverviewthrottlejunctionThis section contains the following topics:Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Management of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.Junction throttling conceptsPlacing a junctioned server in a throttled stateJunctioned server in an offline stateJunctioned server in an online stateJunction throttle messagesUse of junction throttling with existing WebSEAL featuresJunction throttling has an impact on the following WebSEAL functions.

Junction throttling

This section contains the following topics:

Junction throttling concepts

Placing a junctioned server in a throttled state

Junctioned server in an offline state

Junctioned server in an online state

Junction throttle messages

Use of junction throttling with existing WebSEAL features
Junction throttling has an impact on the following WebSEAL functions.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Junction throttling conceptsJunction throttling conceptsjunction throttlingconceptsconceptsjunction throttlingRegular maintenance on equipment in a computer network environment is a crucial and necessary task. In a WebSEAL environment, data storage and application programs typically reside on junctioned back-end host machines that are protected by WebSEAL. High demand WebSEAL environments usually rely on server clusters made up of multiple machines hosting replicated content and applications.A replica server environment allows you to take individual servers offline to perform regular maintenance. The network load is redistributed across the remaining replicas allowing the user experience to proceed without disruption. Junction throttling allows you to gradually take a junctioned back-end Web server offline without interrupting the transactions of users with existing sessions. The throttling action on a junction is particularly useful for allowing stateful sessions, such as shopping cart transactions, to continue until completed.Junction throttling accomplishes the following actions:The throttled server continues to process current and subsequent requests from users with sessions created before the throttle action was taken.The throttled server blocks all requests from unauthenticated users and new authenticated users and directs these requests to other available replica servers on the same junction.As the current users finish their sessions, the throttled server eventually becomes idle and can be taken offline.Junction throttling does not require you to stop WebSEAL and does not interrupt user access to other junctioned Web servers.The pdadmin utility provides commands to place junctioned servers in one of three operational states:ThrottleOfflineOnlineThese operational states are different from the run states of a junctioned server: running, not running, unknown, not an http server. The server run states is reported in the "Server State" field of the pdadmin server task show and pdadmin server task virtualhost show commands.The commands allow you to individually or collectively control the servers on a junction. Collective control might be required, for example, in the case of a security breach.The junction throttling feature is supported on standard WebSEAL junctions and virtual host junctions. Junction throttling is not available for standard local junctions or virtual host local junctions.Junction throttling

Junction throttling concepts

Regular maintenance on equipment in a computer network environment is a crucial and necessary task. In a WebSEAL environment, data storage and application programs typically reside on junctioned back-end host machines that are protected by WebSEAL. High demand WebSEAL environments usually rely on server clusters made up of multiple machines hosting replicated content and applications.

A replica server environment allows you to take individual servers offline to perform regular maintenance. The network load is redistributed across the remaining replicas allowing the user experience to proceed without disruption.

Junction throttling allows you to gradually take a junctioned back-end Web server offline without interrupting the transactions of users with existing sessions. The throttling action on a junction is particularly useful for allowing stateful sessions, such as shopping cart transactions, to continue until completed.

Junction throttling accomplishes the following actions:

The throttled server continues to process current and subsequent requests from users with sessions created before the throttle action was taken.

The throttled server blocks all requests from unauthenticated users and new authenticated users and directs these requests to other available replica servers on the same junction.

As the current users finish their sessions, the throttled server eventually becomes idle and can be taken offline.

Junction throttling does not require you to stop WebSEAL and does not interrupt user access to other junctioned Web servers.

The pdadmin utility provides commands to place junctioned servers in one of three operational states:

Throttle

Offline

Online

Note: These operational states are different from the run states of a junctioned server: running, not running, unknown, not an http server. The server run states is reported in the "Server State" field of the pdadmin server task show and pdadmin server task virtualhost show commands.

The commands allow you to individually or collectively control the servers on a junction. Collective control might be required, for example, in the case of a security breach.

The junction throttling feature is supported on standard WebSEAL junctions and virtual host junctions. Junction throttling is not available for standard local junctions or virtual host local junctions.

Parent topic: Junction throttling

Placing a junctioned server in a throttled statePlacing a junctioned server in a throttled statejunction throttlingthrottled operational statethrottlestatePlace a junctioned server in a throttled operational state when you want a controlled and gradual transition of the server to an offline state. The throttled operational state places the following conditions on the junction: A throttled server continues to process current and subsequent requests from users with sessions created before the throttle action was taken.The throttled server blocks all requests from unauthenticated users and new authenticated users and directs these requests to other available replica servers on the same junction.When a request is blocked by a throttled server, it is retried on another replica server. If no replica servers are configured or available, an error page is returned to the user indicating the application server is offline.The throttled operational state for a junction is stored in the junction database and is maintained across any restarts of the WebSEAL server.Junction throttlingThrottle command usage for standard WebSEAL junctionsThrottle command usage for virtual host junctions

Placing a junctioned server in a throttled state

About this task

Place a junctioned server in a throttled operational state when you want a controlled and gradual transition of the server to an offline state. The throttled operational state places the following conditions on the junction:

A throttled server continues to process current and subsequent requests from users with sessions created before the throttle action was taken.

The throttled server blocks all requests from unauthenticated users and new authenticated users and directs these requests to other available replica servers on the same junction.

When a request is blocked by a throttled server, it is retried on another replica server. If no replica servers are configured or available, an error page is returned to the user indicating the application server is offline.

The throttled operational state for a junction is stored in the junction database and is maintained across any restarts of the WebSEAL server.

Throttle command usage for standard WebSEAL junctions

Throttle command usage for virtual host junctions

Parent topic: Junction throttling

Throttle command usage for standard WebSEAL junctionsThrottle command usage for standard WebSEAL junctionspdadmin server taskthrottlethrottlecommandWebSEAL junctionsThe following pdadmin command syntax is appropriate for use with standard WebSEAL junctions:server task instance_name-webseald-host_name throttle [-i server_uuid] jct_pointUse the -i option to specify the UUID of the junctioned server that is being placed in a throttled operational state. If a server is not specified using this option, then all servers located at the junction are placed in a throttled operational state.Example:The following example places the backappl server located at the /pubs junction point in a throttled operational state. To determine the UUID of this junctioned server, run the server task show command:pdadmin> server task default-webseald-cruz show /pubsOutput is similar to the following:Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Online Hostname: backapp1.diamond.example.com ... Current requests: 0 ...Then, place this server in a throttled operational state (entered as one line): pdadmin> server task default-webseald-cruz throttle -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubsPlacing a junctioned server in a throttled state

Throttle command usage for standard WebSEAL junctions

The following pdadmin command syntax is appropriate for use with standard WebSEAL junctions:

server task instance_name-webseald-host_name throttle [-i server_uuid] jct_point

Use the -i option to specify the UUID of the junctioned server that is being placed in a throttled operational state. If a server is not specified using this option, then all servers located at the junction are placed in a throttled operational state.

Example:

The following example places the backappl server located at the /pubs junction point in a throttled operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to the following:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Online
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Then, place this server in a throttled operational state (entered as one line):

pdadmin> server task default-webseald-cruz throttle
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

Parent topic: Placing a junctioned server in a throttled state

Throttle command usage for virtual host junctionsThrottle command usage for virtual host junctionspdadmin server taskvirtual hostthrottlethrottlecommandvirtual host junctionsThe following pdadmin command syntax is appropriate for use with virtual host junctions:server task instance_name-webseald-host_name virtualhost throttle [-i server_uuid] vhost_labelUse the -i option to specify the UUID of the junctioned server that is being placed in a throttled operational state. If a server is not specified using this option, then all servers located at the junction are placed in a throttled operational state.In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.There is a requirement to place the int3.ibm.com server in a throttled operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-https Output is similar to:Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Online Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1Place this server in a throttled operational state using the following command (entered as one line):pdadmin> server task default-webseald-cruz virtualhost throttle -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-httpsPlacing a junctioned server in a throttled state

Throttle command usage for virtual host junctions

The following pdadmin command syntax is appropriate for use with virtual host junctions:

server task instance_name-webseald-host_name virtualhost throttle [-i server_uuid]
vhost_label

Use the -i option to specify the UUID of the junctioned server that is being placed in a throttled operational state. If a server is not specified using this option, then all servers located at the junction are placed in a throttled operational state.

In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in a throttled operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Online
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in a throttled operational state using the following command (entered as one line):

pdadmin> server task default-webseald-cruz virtualhost throttle
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

Parent topic: Placing a junctioned server in a throttled state

Junctioned server in an offline stateJunctioned server in an offline statejunction throttlingoffline operational stateoffline statejunctioned serversPlace a junctioned server in an offline operational state when you want to block all requests from all users. The offline operational state places the following conditions on the junction:An offline server continues to process existing requests.An offline server blocks all subsequent requests from all users.When a request is blocked by an offline server, it is retried on another replica server. If no replica servers are configured or available, an error page is returned to the user indicating the application server is offline.The offline operational state for a junction is stored in the junction database and is maintained across any restarts of the WebSEAL server.Junction throttlingOffline command usage for standard WebSEAL junctionsOffline command usage for virtual host junctions

Junctioned server in an offline state

Place a junctioned server in an offline operational state when you want to block all requests from all users. The offline operational state places the following conditions on the junction:

An offline server continues to process existing requests.

An offline server blocks all subsequent requests from all users.

When a request is blocked by an offline server, it is retried on another replica server. If no replica servers are configured or available, an error page is returned to the user indicating the application server is offline.

The offline operational state for a junction is stored in the junction database and is maintained across any restarts of the WebSEAL server.

Offline command usage for standard WebSEAL junctions

Offline command usage for virtual host junctions

Parent topic: Junction throttling

Offline command usage for standard WebSEAL junctionsOffline command usage for standard WebSEAL junctionspdadmin server taskofflineThe following pdadmin command syntax is appropriate for use with standard WebSEAL junctions:server task instance_name-webseald-host_name offline [-i server_uuid] jct_pointUse the -i option to specify the UUID of the junctioned server that is being placed in an offline operational state. If a server is not specified using this option, then all servers located at the junction are placed in an offline operational state.Example:The following example places the backappl server located at the /pubs junction point in an offline operational state. To determine the UUID of this junctioned server, run the server task show command:pdadmin> server task default-webseald-cruz show /pubsOutput is similar to the following:Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Throttled Throttled at: 2005-03-01-17:07:24 Hostname: backapp1.diamond.example.com ... Current requests: 0 ...Then, place this server in an offline operational state (entered as one line): pdadmin> server task default-webseald-cruz offline -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubsJunctioned server in an offline state

Offline command usage for standard WebSEAL junctions

The following pdadmin command syntax is appropriate for use with standard WebSEAL junctions:

server task instance_name-webseald-host_name offline [-i server_uuid] jct_point

Use the -i option to specify the UUID of the junctioned server that is being placed in an offline operational state. If a server is not specified using this option, then all servers located at the junction are placed in an offline operational state.

Example:

The following example places the backappl server located at the /pubs junction point in an offline operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to the following:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Then, place this server in an offline operational state (entered as one line):

pdadmin> server task default-webseald-cruz offline
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

Parent topic: Junctioned server in an offline state

Offline command usage for virtual host junctionsOffline command usage for virtual host junctionspdadmin server taskvirtual hostofflineThe following pdadmin command syntax is appropriate for use with virtual host junctions:server task instance_name-webseald-host_name virtualhost offline [-i server_uuid] vhost_labelUse the -i option to specify the UUID of the junctioned server that is being placed in an offline operational state. If a server is not specified using this option, then all servers located at the junction are placed in an offline operational state.In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.There is a requirement to place the int3.ibm.com server in an offline operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-https Output is similar to:Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Throttled Throttled at: 2005-03-01-17:07:24 Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1Place this server in an offline operational state using the following command (entered as one line):pdadmin> server task default-webseald-cruz virtualhost offline -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-httpsJunctioned server in an offline state

Offline command usage for virtual host junctions

The following pdadmin command syntax is appropriate for use with virtual host junctions:

server task instance_name-webseald-host_name virtualhost offline [-i server_uuid]
vhost_label

Use the -i option to specify the UUID of the junctioned server that is being placed in an offline operational state. If a server is not specified using this option, then all servers located at the junction are placed in an offline operational state.

In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an offline operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in an offline operational state using the following command (entered as one line):

pdadmin> server task default-webseald-cruz virtualhost offline
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

Parent topic: Junctioned server in an offline state

Junctioned server in an online stateJunctioned server in an online statejunction throttlingonline operational stateonline statejunctioned serversPlace a junctioned server in an online operational state when you want to return the server to normal operation. The online operational state places the following conditions on the junction:An online server resumes normal operations.The online operational state for a junction is stored in the junction database and is maintained across any restarts of the WebSEAL server.Junction throttlingOnline command usage for standard WebSEAL junctionsOnline command usage for virtual host junctions

Junctioned server in an online state

Place a junctioned server in an online operational state when you want to return the server to normal operation. The online operational state places the following conditions on the junction:

An online server resumes normal operations.

The online operational state for a junction is stored in the junction database and is maintained across any restarts of the WebSEAL server.

Online command usage for standard WebSEAL junctions

Online command usage for virtual host junctions

Parent topic: Junction throttling

Online command usage for standard WebSEAL junctionsOnline command usage for standard WebSEAL junctionspdadmin server taskonlineonline command usageThe following pdadmin command syntax is appropriate for use with standard WebSEAL junctions:server task instance_name-webseald-host_name online [-i server_uuid] jct_pointUse the -i option to specify the UUID of the junctioned server that is being placed in an online operational state. If a server is not specified using this option, then all servers located at the junction are placed in an online operational state.Example:The following example places the backappl server located at the /pubs junction point in an online operational state. To determine the UUID of this junctioned server, run the server task show command:pdadmin> server task default-webseald-cruz show /pubsOutput is similar to the following:Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Offline Hostname: backapp1.diamond.example.com ... Current requests: 0 ...Then, place this server in an online operational state (entered as one line): pdadmin> server task default-webseald-cruz online -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubsJunctioned server in an online state

Online command usage for standard WebSEAL junctions

The following pdadmin command syntax is appropriate for use with standard WebSEAL junctions:

server task instance_name-webseald-host_name online [-i server_uuid] jct_point

Use the -i option to specify the UUID of the junctioned server that is being placed in an online operational state. If a server is not specified using this option, then all servers located at the junction are placed in an online operational state.

Example:

The following example places the backappl server located at the /pubs junction point in an online operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to the following:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Offline
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Then, place this server in an online operational state (entered as one line):

pdadmin> server task default-webseald-cruz online
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

Parent topic: Junctioned server in an online state

Online command usage for virtual host junctionsOnline command usage for virtual host junctionspdadmin server taskvirtual hostonlinevirtual host junctionsonline command usagejunctionsvirtual hostsThe following pdadmin command syntax is appropriate for use with virtual host junctions:server task instance_name-webseald-host_name virtualhost online [-i server_uuid] vhost_labelUse the -i option to specify the UUID of the junctioned server that is being placed in an online operational state. If a server is not specified using this option, then all servers located at the junction are placed in an online operational state.In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.There is a requirement to place the int3.ibm.com server in an online operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-https Output is similar to:Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Offline Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1Place this server in an online operational state using the following command (entered as one line):pdadmin> server task default-webseald-cruz virtualhost online -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-httpsJunctioned server in an online state

Online command usage for virtual host junctions

The following pdadmin command syntax is appropriate for use with virtual host junctions:

server task instance_name-webseald-host_name virtualhost online [-i server_uuid]
vhost_label

Use the -i option to specify the UUID of the junctioned server that is being placed in an online operational state. If a server is not specified using this option, then all servers located at the junction are placed in an online operational state.

In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an online operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Offline
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in an online operational state using the following command (entered as one line):

pdadmin> server task default-webseald-cruz virtualhost online
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

Parent topic: Junctioned server in an online state

Junction throttle messagesJunction throttle messagesJunction throttle messages in IBM Security Access Manager for Webjunction throttlingmessagesThis section contains the following topics: Junction throttlingJunction throttle error pageMonitoring of throttled server status and activity

Junction throttle messages

This section contains the following topics:

Junction throttle error page

Monitoring of throttled server status and activity

Parent topic: Junction throttling

Junction throttle error pageJunction throttle error pagejunction throttlingerror message pageserror pagesthrottled and offline junctioned serversAn error page (38b9a4b0.html) is returned to the user when a request is blocked due to a junctioned server that has been placed in a throttled or offline operational state. This error page is only sent if all servers on the junction are placed in a throttled or offline operational state.You can customize the content of this HTML error page. See HTML server response page modification.Alternatively, WebSEAL can be configured to redirect error reporting to an external error page service. See Local response redirection.Junction throttle messages

Junction throttle error page

An error page (38b9a4b0.html) is returned to the user when a request is blocked due to a junctioned server that has been placed in a throttled or offline operational state. This error page is only sent if all servers on the junction are placed in a throttled or offline operational state.

You can customize the content of this HTML error page. See HTML server response page modification.

Alternatively, WebSEAL can be configured to redirect error reporting to an external error page service. See Local response redirection.

Parent topic: Junction throttle messages

Monitoring of throttled server status and activityMonitoring of throttled server status and activitypdadmin server taskshowingvirtual hostshowthrottleserver statusYou can monitor the status and activity of a throttled server using three new fields to the pdadmin server task show and pdadmin server task virtualhost show commands:Operational state: {Throttled|Offline|Online}Current requests: number This field displays the number of worker threads actively using a junctioned server and allows you to determine when the server has become idle.Throttled at: date-time This field only displays when the server is in the throttled operational state.For example:pdadmin> server task default-webseald-cruz show /pubsOutput is similar to the following:Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Throttled Throttled at: 2005-03-01-17:07:24 Hostname: backapp1.diamond.example.com ... Current requests: 3 ...The "Current requests" field helps to determine if a server is idle. However, there are numerous conditions that prevent a completely accurate determination of the state of server activity. For example:The"Current requests" field is not updated during the lag time between the reading of the body of the response from the junctioned server and the return of the response to the client.If session lifetime resets and extensions have been configured, it becomes almost impossible to be completely sure no future operations will occur on the server.Junction throttle messages

Monitoring of throttled server status and activity

You can monitor the status and activity of a throttled server using three new fields to the pdadmin server task show and pdadmin server task virtualhost show commands:

Operational state: {Throttled|Offline|Online}

Current® requests: number

This field displays the number of worker threads actively using a junctioned server and allows you to determine when the server has become idle.

Throttled at: date-time

This field only displays when the server is in the throttled operational state.

For example:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to the following:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: backapp1.diamond.example.com
...
Current requests: 3
...

The "Current requests" field helps to determine if a server is idle. However, there are numerous conditions that prevent a completely accurate determination of the state of server activity. For example:

The"Current requests" field is not updated during the lag time between the reading of the body of the response from the junctioned server and the return of the response to the client.

If session lifetime resets and extensions have been configured, it becomes almost impossible to be completely sure no future operations will occur on the server.

Parent topic: Junction throttle messages

Use of junction throttling with existing WebSEAL featuresUse of junction throttling with existing WebSEAL featuresUse of junction throttling with existing WebSEAL features in IBM Security Access Manager for WebJunction throttling has an impact on the following WebSEAL functions.junction throttlinguse in WebSEAL featuresWebSEALfeatures Failover authentication Failover authentication transparently supports failed over sessions that continue to use a throttled junction if the original session was created before the junction was throttled. The session creation time is added as an attribute to the failover cookie so it can be restored when a failover cookie is used to authenticate. When the failover cookie is used for authentication, the session creation time from the cookie is set for the newly created failover session.Distributed session cache The distributed session cache makes the session creation time available to all processes that are sharing the session. The session creation time is important because only sessions created before a junction server is throttled are allowed continued access to the throttled junction server.Reauthentication Reauthenticated sessions are allowed continued access to a throttled junction server if the sessions are initially created before the junction was throttled. The additional effect of session lifetime extensions or resets can make it difficult for you to determine when the throttled junction is truly idle.Switch user When a switch user event occurs, a new session creation time is generated. This new creation time is used to determine accessibility to a throttled junction server. When the switch user logs out and returns to the original identity, the original session creation time becomes effective again and is used to determine accessibility to a throttled junction server.Stateful junctions Stateful junctions allow requests from a specific session to always be sent to the same server on a junction. If the junctioned server being used is throttled, the stateful session is allowed to continue accessing that server. However, new stateful sessions are blocked from using that server. If a junctioned server is taken offline, then stateful sessions are no longer allowed to access the server. These sessions must choose a new junctioned server and possibly loose the original state information. Step-up authentication Step-up authentication does not create a new session. The session creation time is therefore not affected, and the ability of the session to access a throttled junction does not change.Junction throttling

Use of junction throttling with existing WebSEAL features

Junction throttling has an impact on the following WebSEAL functions.

Failover authentication

Failover authentication transparently supports failed over sessions that continue to use a throttled junction if the original session was created before the junction was throttled. The session creation time is added as an attribute to the failover cookie so it can be restored when a failover cookie is used to authenticate. When the failover cookie is used for authentication, the session creation time from the cookie is set for the newly created failover session.

Distributed session cache

The distributed session cache makes the session creation time available to all processes that are sharing the session. The session creation time is important because only sessions created before a junction server is throttled are allowed continued access to the throttled junction server.

Reauthentication

Reauthenticated sessions are allowed continued access to a throttled junction server if the sessions are initially created before the junction was throttled. The additional effect of session lifetime extensions or resets can make it difficult for you to determine when the throttled junction is truly idle.

Switch user

When a switch user event occurs, a new session creation time is generated. This new creation time is used to determine accessibility to a throttled junction server. When the switch user logs out and returns to the original identity, the original session creation time becomes effective again and is used to determine accessibility to a throttled junction server.

Stateful junctions

Stateful junctions allow requests from a specific session to always be sent to the same server on a junction. If the junctioned server being used is throttled, the stateful session is allowed to continue accessing that server. However, new stateful sessions are blocked from using that server.

If a junctioned server is taken offline, then stateful sessions are no longer allowed to access the server. These sessions must choose a new junctioned server and possibly loose the original state information.

Step-up authentication

Step-up authentication does not create a new session. The session creation time is therefore not affected, and the ability of the session to access a throttled junction does not change.

Parent topic: Junction throttling

Management of cookiesManagement of cookiesIBM Security Access Manager for Web cookie management in WebSEALWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. WebSEALmanagement of cookiescookiesmanagement in WebSEALThe WebSEAL cookie jar is instantiated on a per-user session basis. Cookies not stored in the cookie jar are passed back to the client for storage. The cookie jar stores and handles cookies as defined by the following configuration entries in the [junction] stanza:managed-cookies-listContains a comma-separated list of pattern matched cookie names. Cookies that match the patterns on this list are stored in the cookie jar. If this list is empty, the cookie jar is effectively disabled.WebSEAL processes the cookies found in the response before attempting to add the cookies to the cookie jar. It can sometimes, based on the junction configuration, prefix the original cookie name with a junction identifier. This new cookie name will be used when WebSEAL decides whether to add a cookie to the cookie jar.reset-cookies-listDetermines which cookies to reset when the user session is logged out. The request received from the client and the response sent back to the client are both examined for matching cookies. The reset clears the cookie in the client's cache by returning an empty and expired cookie in the logout response. This essentially implements a basic logout for junctioned applications. WebSEAL processes the cookies found in the response before deciding which cookies to reset. It can sometimes, based on the junction configuration, prefix the original cookie name with a junction identifier. This new cookie name will be used when WebSEAL decides which cookies to reset.share-cookiesDetermines whether or not cookies stored in the cookie jar will be shared between different junctions. validate-backend-domain-cookieDomain checking on cookies is only performed if this entry is set to true.allow-backend-domain-cookiesDuring domain validation, if this entry is set to false, the domain is removed from the cookie. All the preceding configuration items, with the exception of share-cookies, can be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.All response cookies pass through the WebSEAL cookie jar. Cookies that match the patterns defined in managed-cookies-list are stored in the cookie jar and removed from the response stream to the browser. Those that are not stored in the cookie jar are passed back to the client. When a request to a junctioned server is sent from the browser to WebSEAL, the cookie jar is checked to see if the request requires cookies to be sent to the junctioned server. If the request does require a cookie from the cookie jar, the cookie is added to the request. If the cookie has expired, the cookie is removed from the cookie jar and not sent.Persistent cookies are not persisted to disk on the WebSEAL machines. When a user performs a logout, a reset for selected cookies that are not stored in the cookie jar is sent back in the response. WebSEAL resets any cookies with names that match the list of patterns in the reset-cookies-list stanza entry. The reset essentially implements a basic logout for junctioned applications. The distributed session cache should be deployed in situations where the cookie jar is used by multiple replicated WebSEAL servers. The distributed session cache is the mechanism by which the cookie jar can be distributed amongst the multiple replicated WebSEAL servers. In this type of environment, be careful which cookies you place in the cookie jar. Do not include cookies which get updated on a regular basis, as this will put additional load on the distributed session cache which in turn will have performance implications in the environment.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingPassing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Management of cookies

WebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser.

The WebSEAL cookie jar is instantiated on a per-user session basis. Cookies not stored in the cookie jar are passed back to the client for storage.

The cookie jar stores and handles cookies as defined by the following configuration entries in the [junction] stanza:

managed-cookies-list

Contains a comma-separated list of pattern matched cookie names. Cookies that match the patterns on this list are stored in the cookie jar. If this list is empty, the cookie jar is effectively disabled.

Note: WebSEAL processes the cookies found in the response before attempting to add the cookies to the cookie jar. It can sometimes, based on the junction configuration, prefix the original cookie name with a junction identifier. This new cookie name will be used when WebSEAL decides whether to add a cookie to the cookie jar.

reset-cookies-list

Determines which cookies to reset when the user session is logged out. The request received from the client and the response sent back to the client are both examined for matching cookies. The reset clears the cookie in the client's cache by returning an empty and expired cookie in the logout response. This essentially implements a basic logout for junctioned applications.

Note: WebSEAL processes the cookies found in the response before deciding which cookies to reset. It can sometimes, based on the junction configuration, prefix the original cookie name with a junction identifier. This new cookie name will be used when WebSEAL decides which cookies to reset.

share-cookies

Determines whether or not cookies stored in the cookie jar will be shared between different junctions.

validate-backend-domain-cookie

Domain checking on cookies is only performed if this entry is set to true.

allow-backend-domain-cookies

During domain validation, if this entry is set to false, the domain is removed from the cookie.

Note: All the preceding configuration items, with the exception of share-cookies, can be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

All response cookies pass through the WebSEAL cookie jar. Cookies that match the patterns defined in managed-cookies-list are stored in the cookie jar and removed from the response stream to the browser. Those that are not stored in the cookie jar are passed back to the client.

When a request to a junctioned server is sent from the browser to WebSEAL, the cookie jar is checked to see if the request requires cookies to be sent to the junctioned server. If the request does require a cookie from the cookie jar, the cookie is added to the request. If the cookie has expired, the cookie is removed from the cookie jar and not sent.

Persistent cookies are not persisted to disk on the WebSEAL machines.

When a user performs a logout, a reset for selected cookies that are not stored in the cookie jar is sent back in the response. WebSEAL resets any cookies with names that match the list of patterns in the reset-cookies-list stanza entry. The reset essentially implements a basic logout for junctioned applications.

Note: The distributed session cache should be deployed in situations where the cookie jar is used by multiple replicated WebSEAL servers. The distributed session cache is the mechanism by which the cookie jar can be distributed amongst the multiple replicated WebSEAL servers. In this type of environment, be careful which cookies you place in the cookie jar. Do not include cookies which get updated on a regular basis, as this will put additional load on the distributed session cache which in turn will have performance implications in the environment.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Passing of session cookies to junctioned portal serversPassing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. junctionssession cookie to portal server (-k)cookiessessionWhen a client requests a personal resource list from the portal server, the portal server builds this list by accessing resources located on other supporting application servers, also protected by WebSEAL. The session cookie allows the portal server to perform seamless single signon to these application servers, on behalf of the client. You include the –k option, without arguments, when you create the junction between WebSEAL and the back-end portal server.The –k option is also supported on virtual host junctions. The WebSEAL configuration file includes options that provide some control over how session cookies are handled during step-up authentication. The verify-step-up-user option in the [step-up] stanza determines whether the identity of the user performing the step-up operation must match the identity of the user that performed the previous authentication. If this option is set to yes, then the retain-stepup-session option can be used to determine whether the session cookie issued during the step-up operation can be reused or if a new cookie must be issued. If verify-step-up-user is set to no, then a new cookie will always be issued after step-up.The send-constant-sess option in the [session] stanza enhances the ability to track authenticated sessions. Setting this option to yes enables WebSEAL to send a separate cookie to the junctioned server in addition to the session cookie. The value of this cookie remains constant across a single session, regardless of whether the session key changes. The name of the cookie is configurable. For more details regarding the send-constant-sess option, send-constant-sess.Conditions to consider for a portal server configuration: For access using user name and password, forms authentication is required. Do not use basic authentication (BA).The value of the ssl-id-sessions stanza entry in the [session] stanza of the WebSEAL configuration files must be set to no. For HTTPS communication, this setting forces the use of a session cookie, instead of the SSL session ID, to maintain session state.If the portal server is behind a front-end WebSEAL cluster, enable the failover type cookie. The failover cookie contains encrypted credential information that allows authentication to succeed with any replicated WebSEAL server that processes the request.The retain-stepup-session option in the [step-up] stanza is only in effect if the verify-step-up-user option is set to yes.If WebSEAL is configured to use the distributed session cache for session storage, the verify-step-up-user option must be set to yes to enable step-up operations. If this option is set to no, then WebSEAL does not update the distributed session cache when user identification changes during step-up authentication.For more information about step-up authentication, see Authentication strength concepts.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Passing of session cookies to junctioned portal servers

A Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server.

When a client requests a personal resource list from the portal server, the portal server builds this list by accessing resources located on other supporting application servers, also protected by WebSEAL. The session cookie allows the portal server to perform seamless single signon to these application servers, on behalf of the client.

You include the –k option, without arguments, when you create the junction between WebSEAL and the back-end portal server.

The –k option is also supported on virtual host junctions.

The WebSEAL configuration file includes options that provide some control over how session cookies are handled during step-up authentication. The verify-step-up-user option in the [step-up] stanza determines whether the identity of the user performing the step-up operation must match the identity of the user that performed the previous authentication. If this option is set to yes, then the retain-stepup-session option can be used to determine whether the session cookie issued during the step-up operation can be reused or if a new cookie must be issued. If verify-step-up-user is set to no, then a new cookie will always be issued after step-up.

The send-constant-sess option in the [session] stanza enhances the ability to track authenticated sessions. Setting this option to yes enables WebSEAL to send a separate cookie to the junctioned server in addition to the session cookie. The value of this cookie remains constant across a single session, regardless of whether the session key changes. The name of the cookie is configurable. For more details regarding the send-constant-sess option, send-constant-sess.

Conditions to consider for a portal server configuration:

For access using user name and password, forms authentication is required. Do not use basic authentication (BA).

The value of the ssl-id-sessions stanza entry in the [session] stanza of the WebSEAL configuration files must be set to no. For HTTPS communication, this setting forces the use of a session cookie, instead of the SSL session ID, to maintain session state.

If the portal server is behind a front-end WebSEAL cluster, enable the failover type cookie. The failover cookie contains encrypted credential information that allows authentication to succeed with any replicated WebSEAL server that processes the request.

The retain-stepup-session option in the [step-up] stanza is only in effect if the verify-step-up-user option is set to yes.

If WebSEAL is configured to use the distributed session cache for session storage, the verify-step-up-user option must be set to yes to enable step-up operations. If this option is set to no, then WebSEAL does not update the distributed session cache when user identification changes during step-up authentication.

For more information about step-up authentication, see Authentication strength concepts.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Support for URLs as not case-sensitiveSupport for URLs as not case-sensitivejunctionscase-insensitive URLs (-1)URLsupportcase-sensitiveBy default, Security Access Manager treats URLs as case-sensitive when performing checks on access controls. The –i junction option is used to specify that WebSEAL treat URLs as not case-sensitive when performing authorization checks on a request to a junctioned back-end server. The –i option is also supported on virtual host junctions. When you set this option on the junction, WebSEAL does not distinguish between uppercase and lowercase characters when parsing URLs. By default, Web servers are expected to be case-sensitive.Although most HTTP servers support the HTTP specification that defines URLs as case-sensitive, some HTTP servers treat URLs as not case-sensitive. For example, on not case-sensitive servers, the following two URLS: http://server/sales/index.htm http://server/SALES/index.HTMare viewed as the same URL. This behavior requires an administrator to place the same access controls (ACLs) on both URLs. By junctioning a third-party server with the –i option, WebSEAL treats the URLs directed to that server as not case-sensitive. To correctly authorize requests for junctions that are not case sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server running on Windows treats requests for INDEX.HTM and index.htm as requests for the same file. Junctions to such a Web server should be created with the -i [or -w] flags. ACLs or POPs that are attached to objects beneath the junction point should use the lower case object name. An ACL attached to /junction/index.htm will apply to all of the following requests if the -i or -w flags are used: /junction/INDEX.HTM /junction/index.htm /junction/InDeX.HtMThis option is valid for all junctions except for the type of local. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.When using the –i option, object names must be lower case in order for WebSEAL to be able to find any ACLs or POPs attached to those objects. For more information, see ACLs and POPs must attach to lower-case object namesWhen a junction is created with the –w or –i option, WebSEAL performs ACL and POP comparisons as not case-sensitive. This means that the name of any object being evaluated for an ACL is placed into lowercase before WebSEAL checks it against the object list to which ACLs are attached..Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Junctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Support for URLs as not case-sensitive

By default, Security Access Manager treats URLs as case-sensitive when performing checks on access controls. The –i junction option is used to specify that WebSEAL treat URLs as not case-sensitive when performing authorization checks on a request to a junctioned back-end server.

The –i option is also supported on virtual host junctions.

When you set this option on the junction, WebSEAL does not distinguish between uppercase and lowercase characters when parsing URLs. By default, Web servers are expected to be case-sensitive.

Although most HTTP servers support the HTTP specification that defines URLs as case-sensitive, some HTTP servers treat URLs as not case-sensitive.

For example, on not case-sensitive servers, the following two URLS:

http://server/sales/index.htm

http://server/SALES/index.HTM

are viewed as the same URL. This behavior requires an administrator to place the same access controls (ACLs) on both URLs.

By junctioning a third-party server with the –i option, WebSEAL treats the URLs directed to that server as not case-sensitive.

To correctly authorize requests for junctions that are not case sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server running on Windows treats requests for INDEX.HTM and index.htm as requests for the same file.

Junctions to such a Web server should be created with the -i [or -w] flags. ACLs or POPs that are attached to objects beneath the junction point should use the lower case object name. An ACL attached to /junction/index.htm will apply to all of the following requests if the -i or -w flags are used:

/junction/INDEX.HTM

/junction/index.htm

/junction/InDeX.HtM

This option is valid for all junctions except for the type of local. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.

Attention: When using the –i option, object names must be lower case in order for WebSEAL to be able to find any ACLs or POPs attached to those objects. For more information, see ACLs and POPs must attach to lower-case object names.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Junctions to Windows file systemsJunctions to Windows file systemsjunctionsWindows file systems (-w)Windowsfile systems junctionsWebSEAL performs security checks on client requests to junctioned back-end servers based on the file paths specified in the URL. A compromise in this security check can occur because Win32 file systems allow two different methods for accessing long file names. The first method acknowledges the entire file name. For example:abcdefghijkl.txtThe second method recognizes the old 8.3 file name format for backward compatibility. For example:abcdef~1.txtWhen you create junctions in a Windows environments, it is important to restrict access control to one object representation only and not allow the possibility of "back doors" that bypass the security mechanism. The –w option on a junction provides the following measures of protection:Prevents the use of the 8.3 file name format When the junction is configured with the –w option, a user cannot avoid an explicit ACL on a long file name by using the short (8.3) form of the file name. The server returns a "403 Forbidden" error on any short form file name entered.Disallows trailing dots in directory and file names If a file or directory contains trailing dots, a 403 "Forbidden" error is returned.Enforces case-insensitivity by setting the –i option The –w option automatically invokes the –i option. This option specifies that WebSEAL treat URLs as case-insensitive when performing authorization checks on a request to a junctioned back-end server. After a successful ACL check, the original case of the URL is restored when the request is sent to the back-end server. If you require control over case-insensitivity only for file names, use only the –i option on the junction instead of the –w option.The –w option is also supported on virtual host junctions. Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.ExampleACLs and POPs must attach to lower-case object namesWhen a junction is created with the –w or –i option, WebSEAL performs ACL and POP comparisons as not case-sensitive. This means that the name of any object being evaluated for an ACL is placed into lowercase before WebSEAL checks it against the object list to which ACLs are attached.

Junctions to Windows file systems

WebSEAL performs security checks on client requests to junctioned back-end servers based on the file paths specified in the URL. A compromise in this security check can occur because Win32 file systems allow two different methods for accessing long file names.

The first method acknowledges the entire file name. For example:

abcdefghijkl.txt

The second method recognizes the old 8.3 file name format for backward compatibility. For example:

abcdef~1.txt

When you create junctions in a Windows environments, it is important to restrict access control to one object representation only and not allow the possibility of "back doors" that bypass the security mechanism.

The –w option on a junction provides the following measures of protection:

Prevents the use of the 8.3 file name format

When the junction is configured with the –w option, a user cannot avoid an explicit ACL on a long file name by using the short (8.3) form of the file name. The server returns a "403 Forbidden" error on any short form file name entered.

Disallows trailing dots in directory and file names

If a file or directory contains trailing dots, a 403 "Forbidden" error is returned.

Enforces case-insensitivity by setting the –i option

The –w option automatically invokes the –i option. This option specifies that WebSEAL treat URLs as case-insensitive when performing authorization checks on a request to a junctioned back-end server. After a successful ACL check, the original case of the URL is restored when the request is sent to the back-end server.

Note: If you require control over case-insensitivity only for file names, use only the –i option on the junction instead of the –w option.

The –w option is also supported on virtual host junctions.

Example

ACLs and POPs must attach to lower-case object names
When a junction is created with the –w or –i option, WebSEAL performs ACL and POP comparisons as not case-sensitive. This means that the name of any object being evaluated for an ACL is placed into lowercase before WebSEAL checks it against the object list to which ACLs are attached.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

ExampleExampleWindowsexamplescreating an aliasincluding trailing extension dotsallowing case-sensitive file namesIn a Windows environment, the file: \Program Files\Company Inc\Release.Notes can also be accessed through the following paths: \progra~1\compan~2\releas~3.not \Program Files\Company Inc.\Release.Notes\program files\company inc\release.notesExample 1 illustrates how Windows can create an alias (for DOS compatibility) that contains no spaces in the file names and conforms to the 8.3 format. The –w option causes WebSEAL to reject this format for ACL checks.Example 2 illustrates how Windows can include trailing extension dots. The –w option causes WebSEAL to reject this format for ACL checks.Example 3 illustrates how Windows allows case-insensitivity on the file name. The –w option invokes the –i option to ensure a case-insensitive ACL check.Junctions to Windows file systems

Example

In a Windows environment, the file:

\Program Files\Company Inc\Release.Notes

can also be accessed through the following paths:

\progra~1\compan~2\releas~3.not

\Program Files\Company Inc.\Release.Notes

\program files\company inc\release.notes

Example 1 illustrates how Windows can create an alias (for DOS compatibility) that contains no spaces in the file names and conforms to the 8.3 format. The –w option causes WebSEAL to reject this format for ACL checks.

Example 2 illustrates how Windows can include trailing extension dots. The –w option causes WebSEAL to reject this format for ACL checks.

Example 3 illustrates how Windows allows case-insensitivity on the file name. The –w option invokes the –i option to ensure a case-insensitive ACL check.

Parent topic: Junctions to Windows file systems

ACLs and POPs must attach to lower-case object namesACLs and POPs must attach to lower-case object namesACLs and POPs must attach to lower-case object names in WebSEALWhen a junction is created with the –w or –i option, WebSEAL performs ACL and POP comparisons as not case-sensitive. This means that the name of any object being evaluated for an ACL is placed into lowercase before WebSEAL checks it against the object list to which ACLs are attached.WebSEALACL and POP comparisonsACLattach to lower case object namesPOPattach to lower case object namesAs a result, protected objects with names that contain uppercase letters are not found during the ACL or POP checks. If these objects are not found, the ACL or POP is not applied to the protected object, and the parent policy is applied instead.To avoid the possible misapplication of policy in this configuration, you must create lowercase versions of the same names of the real protected objects to which you want to attach explicit ACLs or POPs.Junctions to Windows file systems

ACLs and POPs must attach to lower-case object names

When a junction is created with the –w or –i option, WebSEAL performs ACL and POP comparisons as not case-sensitive. This means that the name of any object being evaluated for an ACL is placed into lowercase before WebSEAL checks it against the object list to which ACLs are attached.

As a result, protected objects with names that contain uppercase letters are not found during the ACL or POP checks. If these objects are not found, the ACL or POP is not applied to the protected object, and the parent policy is applied instead.

To avoid the possible misapplication of policy in this configuration, you must create lowercase versions of the same names of the real protected objects to which you want to attach explicit ACLs or POPs.

Parent topic: Junctions to Windows file systems

Standard junctions to virtual hostsStandard junctions to virtual hostsjunctionsvirtual hostsvirtual host junctionsstandard junctionsVirtual hosting refers to the practice of maintaining more than one WebSEAL instance on the same physical machine. Virtual hosting is used to run multiple Web services, each with different host names and URLs, and which appear to be on completely separate sites. Virtual hosting is used by ISPs, hosting sites, and content providers who need to manage multiple sites but do not want to buy a new machine for each one. Multiple companies can share a single Web server but have their own unique domains, such as www.company1.com and www.company2.com. Users of virtual host domains do not need to know any extra path information. In requests to a virtual host domain, browsers simply provide the required hostname through its Host: header. In a standard junction create command, the -h host option and argument identifies the remote junctioned server machine. WebSEAL normally places this server address in the Host: header of requests to this server. The additional -v host option and argument identifies a virtual host instance on this machine. The virtual host information provided by -v is used in the Host: header instead of the -h information. Requests are now directed to the specific virtual host instance. The -h information is still used by WebSEAL to locate the physical host machine. For mutual junctions the -v host option corresponds to the virtual host name when the HTTP protocol is used to communicate with the junctioned server. The -V host option is used as the virtual host name when the HTTPS protocol is used.The following example illustrates the configuration of two virtual hosts. The junctioned application server is server.xyz.com. It runs on port 80 and hosts two virtual servers: site1.xyz.com and site2.xyz.com.Basic junctions are created as follows (each command entered as one line):pdadmin> server task default-webseald-surf.xyz.com create -t tcp -h server.xyz.com -v site1.xyz.com /jct1 pdadmin> server task default-webseald-surf.xyz.com create -t tcp -h server.xyz.com -v site2.xyz.com /jct2Configuring virtual hostsConfiguring virtual hostsSee also Complete Host header information with -v.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Standard junctions to virtual hosts

Virtual hosting refers to the practice of maintaining more than one WebSEAL instance on the same physical machine. Virtual hosting is used to run multiple Web services, each with different host names and URLs, and which appear to be on completely separate sites. Virtual hosting is used by ISPs, hosting sites, and content providers who need to manage multiple sites but do not want to buy a new machine for each one. Multiple companies can share a single Web server but have their own unique domains, such as www.company1.com and www.company2.com.

Users of virtual host domains do not need to know any extra path information. In requests to a virtual host domain, browsers simply provide the required hostname through its Host: header.

In a standard junction create command, the -h host option and argument identifies the remote junctioned server machine. WebSEAL normally places this server address in the Host: header of requests to this server.

The additional -v host option and argument identifies a virtual host instance on this machine. The virtual host information provided by -v is used in the Host: header instead of the -h information. Requests are now directed to the specific virtual host instance. The -h information is still used by WebSEAL to locate the physical host machine.

For mutual junctions the -v host option corresponds to the virtual host name when the HTTP protocol is used to communicate with the junctioned server. The -V host option is used as the virtual host name when the HTTPS protocol is used.

The following example illustrates the configuration of two virtual hosts. The junctioned application server is server.xyz.com. It runs on port 80 and hosts two virtual servers: site1.xyz.com and site2.xyz.com.

Basic junctions are created as follows (each command entered as one line):

pdadmin> server task default-webseald-surf.xyz.com create -t tcp
-h server.xyz.com -v site1.xyz.com /jct1
pdadmin> server task default-webseald-surf.xyz.com create -t tcp
-h server.xyz.com -v site2.xyz.com /jct2

Figure 34. Configuring virtual hosts

See also Complete Host header information with -v.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

UTF-8 encoding for HTTP header dataUTF-8 encoding for HTTP header dataUTF-8encoding HTTP headers over junctionsjunctionsencoding for HTTP headers (-e)WebSEAL inserts information into HTTP headers for requests to the backend server. This information can include extended attributes or user data. In WebSEAL versions prior to version 5.1, the headers were added to the request using a raw local code page. In WebSEAL versions 5.1 and later, the header data is transmitted in a configurable format. By default, WebSEAL now adds information to HTTP headers using UTF-8 encoding. This encoding prevents any potential data loss that could occur when converting to a non-UTF-8 code page. Also by default, this data is sent URI encoded. For backward compatibility, the format of the header data can be configured to raw local code page. In addition, two other formats are supported: Raw UTF-8 and URI encoded local code page.The -e junction option specifies the encoding of user name, groups, and other extended attributes which are sent within the HTTP header to the backend server. The –e option is also supported on virtual host junctions. The -e encode option can take one of the following arguments:ArgumentDescriptionutf8_uriURI encoded UTF-8 data. All white space and non-ASCII bytes are encoded %XY, where X and Y are hex values (0–F).utf8_binUnencoded UTF-8 data. This setting allows data to be transmitted without data loss, and the customer does not need to URI-decode the data. This setting should be used with caution, because it is not part of the HTTP specificationlcp_uriURI encoded local code page data. Any UTF-8 characters that cannot be converted to a local code page will be converted to question marks ( ? ). Use this option with caution and only in environments where the local code page produces the desired strings.lcp_binUnencoded local code page data. This mode was used by versions of WebSEAL prior to Version 5.1. Use of this mode enables migration from previous versions, and is used in upgrade environments. Use with caution, because data loss can potentially occur with this mode.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

UTF-8 encoding for HTTP header data

WebSEAL inserts information into HTTP headers for requests to the backend server. This information can include extended attributes or user data. In WebSEAL versions prior to version 5.1, the headers were added to the request using a raw local code page. In WebSEAL versions 5.1 and later, the header data is transmitted in a configurable format.

By default, WebSEAL now adds information to HTTP headers using UTF-8 encoding. This encoding prevents any potential data loss that could occur when converting to a non-UTF-8 code page. Also by default, this data is sent URI encoded. For backward compatibility, the format of the header data can be configured to raw local code page. In addition, two other formats are supported: Raw UTF-8 and URI encoded local code page.

The -e junction option specifies the encoding of user name, groups, and other extended attributes which are sent within the HTTP header to the backend server.

The –e option is also supported on virtual host junctions.

The -e encode option can take one of the following arguments:

Argument
Description

utf8_uri

URI encoded UTF-8 data.

All white space and non-ASCII bytes are encoded %XY, where X and Y are hex values (0–F).

utf8_bin

Unencoded UTF-8 data.

This setting allows data to be transmitted without data loss, and the customer does not need to URI-decode the data.

This setting should be used with caution, because it is not part of the HTTP specification

lcp_uri

URI encoded local code page data.

Any UTF-8 characters that cannot be converted to a local code page will be converted to question marks ( ? ). Use this option with caution and only in environments where the local code page produces the desired strings.

lcp_bin

Unencoded local code page data.

This mode was used by versions of WebSEAL prior to Version 5.1. Use of this mode enables migration from previous versions, and is used in upgrade environments.

Use with caution, because data loss can potentially occur with this mode.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

WebSockets

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Bypassing buffering on a per-resource basisBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.WebSEALinternal buffer bypassresponse-buffer-controlinternal buffer bypassrequest-buffer-controlinternal buffer bypassThis buffering typically provides performance improvement. For certain applications that send or return small amounts of data, the buffering can cause the data to be held temporarily at WebSEAL while the buffer is being filled. For some applications, it might be preferable to bypass the buffering and stream the data directly to the junctioned server or to the clients. This scheme is not efficient for general web traffic; apply it only to particular resources that require streamed data. For example, apply it to junctions configured for RPC over HTTP communication. See Microsoft RPC over HTTP.You can apply a protected object policy (POP) to individual resources that directs WebSEAL to bypass buffering for those resources. To bypass buffering for a particular resource response, attach a POP to the resource with an attribute named response-buffer-control set with the value bypass. To bypass buffering for a particular resource request, attach a POP to the resource with an attribute named request-buffer-control set with the value bypass.The following exampleCreates a POP named bypassPOP.Sets the response-buffer-control and request-buffer-control attributes to bypass.Attaches the POP to a resource named smallCGICreate a POP named bypassPOP with the appropriate attributes.pdadmin> pop create bypassPOP pdadmin> pop modify bypassPOP set attribute response-buffer-control bypass pdadmin> pop modify bypassPOP set attribute request-buffer-control bypassAttach the POP to the chosen resource.pdadmin> pop attach /WebSEAL/myinstance/myjunction/cgi-bin/smallCGI bypassPOPThis POP only affects the data in the body of the request or response that is received from the client or junction. WebSEAL still buffers the request and response headers.When buffering HTTP requests using this POP technique, there are limitations. Certain WebSEAL functions require the entire request body, and this body is not available when streaming a request to a junctioned server.The following WebSEAL functionality cannot be used when using request streaming:WebSEAL response streaming can still be applied to resources that use this WebSEAL functionality.Caching of POST data during the authentication process.Dynamic authorization decision information (dynADI) when POST data is part of the decision evaluation.Dynamic URLs (dynURL) when POST data is part of the decision evaluation.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataWebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

Bypassing buffering on a per-resource basis

WebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.

About this task

This buffering typically provides performance improvement. For certain applications that send or return small amounts of data, the buffering can cause the data to be held temporarily at WebSEAL while the buffer is being filled. For some applications, it might be preferable to bypass the buffering and stream the data directly to the junctioned server or to the clients. This scheme is not efficient for general web traffic; apply it only to particular resources that require streamed data. For example, apply it to junctions configured for RPC over HTTP communication. See Microsoft RPC over HTTP.

You can apply a protected object policy (POP) to individual resources that directs WebSEAL to bypass buffering for those resources. To bypass buffering for a particular resource response, attach a POP to the resource with an attribute named response-buffer-control set with the value bypass. To bypass buffering for a particular resource request, attach a POP to the resource with an attribute named request-buffer-control set with the value bypass.

The following example

Creates a POP named bypassPOP.

Sets the response-buffer-control and request-buffer-control attributes to bypass.

Attaches the POP to a resource named smallCGI

Procedure

Create a POP named bypassPOP with the appropriate attributes.

pdadmin> pop create bypassPOP
pdadmin> pop modify bypassPOP set attribute response-buffer-control bypass
pdadmin> pop modify bypassPOP set attribute request-buffer-control bypass

Attach the POP to the chosen resource.

pdadmin> pop attach /WebSEAL/myinstance/myjunction/cgi-bin/smallCGI bypassPOP

This POP only affects the data in the body of the request or response that is received from the client or junction. WebSEAL still buffers the request and response headers.

When buffering HTTP requests using this POP technique, there are limitations. Certain WebSEAL functions require the entire request body, and this body is not available when streaming a request to a junctioned server.

The following WebSEAL functionality cannot be used when using request streaming:

Note: WebSEAL response streaming can still be applied to resources that use this WebSEAL functionality.

Caching of POST data during the authentication process.

Dynamic authorization decision information (dynADI) when POST data is part of the decision evaluation.

Dynamic URLs (dynURL) when POST data is part of the decision evaluation.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

WebSockets

Related tasks:

Forcing a new junction

WebSocketsWebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.To enable WebSocket proxy support, update the WebSEAL configuration file and configure the [websocket] max-worker-threads to a value larger than zero.Each WebSocket created between the client and the junctioned server requires two WebSocket worker threads. The max-worker-threads setting must be configured to allow for this thread usage.If the max-worker-threads limit is reached, then any additional requests to proxy a WebSocket connection is rejected and a warning message is logged.WebSocket connections can have a non-trivial lifespan as a client can keep the connection open for extended periods of time with data traveling in both directions asynchronously. The max-worker-threads entry decides how many concurrent clients can be handled by WebSEAL. To help reduce the number of idle or blocked WebSocket connections, WebSEAL provides the following timeout settings: [websocket] jct-read-inactive-timeout[websocket] jct-writeblocked- timeout[websocket] clt-write-blocked-timeout[websocket] clt-read-inactive-timeoutThe settings that begin with jct impact the connection between WebSEAL and the junctioned server. The settings that begin with clt impact the connection between WebSEAL and the client or browser. Carefully evaluate the WebSocket data transmission behavior before you set these timeouts.WebSEAL's pdweb.snoop trace also applies to WebSocket data. Enabling pdweb.snoop trace allows tracing of the raw WebSocket data that is sent and received on each WebSocket connection. The pdweb.snoop trace can be enabled for the client traffic, the junction traffic, or both, by using pdweb.snoop.client and pdweb.snoop.jct trace elements.Statistics can be gathered on WebSockets by enabling the pdweb.websocket stats component. The provided statistics are shown in the following table.Statistic labelDescriptionrequestsTotal WebSocket proxy requests received while statistics gathering is enabled.rejectedTotal WebSocket proxy requests rejected while statistics gathering is enabled. The rejection is typically due to an insufficient number of available worker threads.timeoutThe number of timeouts that have occurred when reading or writing through a proxied WebSocket connection while statistics gathering is enabled.activeThe current number of WebSocket connections that are proxied.client bytesThe number of bytes read from the client side.junction bytesThe number of bytes read from the junction side.Advanced junction configurationMost standard junction options are also supported by virtual host junctions.Mutually authenticated SSL junctionsTCP and SSL proxy junctionsWebSEAL-to-WebSEAL junctions over SSLStateful junctionsForcing a new junctionUse of /pkmslogout with virtual host junctionsPolicies can be attached to pkmslogout, but WebSEAL does not always apply the policies.Junction throttlingManagement of cookiesWebSEAL can host cookies on behalf of browsers and provide them to backend applications in forwarded requests. These stored cookies are held in the session cache, or cookie jar, rather than being sent to the browser. Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. Support for URLs as not case-sensitiveJunctions to Windows file systemsStandard junctions to virtual hostsUTF-8 encoding for HTTP header dataBypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications.

WebSockets

WebSEAL can proxy WebSocket connections between clients and junctioned web servers. In the WebSEAL default configuration, all WebSocket requests are rejected.

To enable WebSocket proxy support, update the WebSEAL configuration file and configure the [websocket] max-worker-threads to a value larger than zero.

Each WebSocket created between the client and the junctioned server requires two WebSocket worker threads. The max-worker-threads setting must be configured to allow for this thread usage.

If the max-worker-threads limit is reached, then any additional requests to proxy a WebSocket connection is rejected and a warning message is logged.

WebSocket connections can have a non-trivial lifespan as a client can keep the connection open for extended periods of time with data traveling in both directions asynchronously. The max-worker-threads entry decides how many concurrent clients can be handled by WebSEAL. To help reduce the number of idle or blocked WebSocket connections, WebSEAL provides the following timeout settings:

[websocket] jct-read-inactive-timeout

[websocket] jct-writeblocked- timeout

[websocket] clt-write-blocked-timeout

[websocket] clt-read-inactive-timeout

The settings that begin with jct impact the connection between WebSEAL and the junctioned server. The settings that begin with clt impact the connection between WebSEAL and the client or browser. Carefully evaluate the WebSocket data transmission behavior before you set these timeouts.

WebSEAL's pdweb.snoop trace also applies to WebSocket data. Enabling pdweb.snoop trace allows tracing of the raw WebSocket data that is sent and received on each WebSocket connection. The pdweb.snoop trace can be enabled for the client traffic, the junction traffic, or both, by using pdweb.snoop.client and pdweb.snoop.jct trace elements.

Statistics can be gathered on WebSockets by enabling the pdweb.websocket stats component. The provided statistics are shown in the following table.

Statistic label | Description
requests | Total WebSocket proxy requests received while statistics gathering is enabled.
rejected | Total WebSocket proxy requests rejected while statistics gathering is enabled. The rejection is typically due to an insufficient number of available worker threads.
timeout | The number of timeouts that have occurred when reading or writing through a proxied WebSocket connection while statistics gathering is enabled.
active | The current number of WebSocket connections that are proxied.
client bytes | The number of bytes read from the client side.
junction bytes | The number of bytes read from the junction side.

Parent topic: Advanced junction configuration

Related concepts:

Mutually authenticated SSL junctions

TCP and SSL proxy junctions

WebSEAL-to-WebSEAL junctions over SSL

Stateful junctions

Use of /pkmslogout with virtual host junctions

Junction throttling

Management of cookies

Passing of session cookies to junctioned portal servers

Support for URLs as not case-sensitive

Junctions to Windows file systems

Standard junctions to virtual hosts

UTF-8 encoding for HTTP header data

Related tasks:

Forcing a new junction

Bypassing buffering on a per-resource basis

Modification of URLs to junctioned resourcesModification of URLs to junctioned resourcesfiltermodifying URLsback-end applicationsback-end applicationsmodifying URLsURLmodificationback-end resourcesThis chapter discusses the configuration options available to ensure that URL links sent from back-end application servers across standard WebSEAL junctions are reconstructed appropriately for use by clients.The challenges of URL filtering are specific to standard WebSEAL junctions. WebSEAL also supports virtual hosting and, through virtual host junctions, can eliminate the limitations of URL filtering. WebSEAL uses the HTTP Host header in client requests to direct those requests to the appropriate document spaces located on junctioned servers or on the local machine.Topic Index:Standard WebSEAL JunctionsURL modification conceptsPath types used in URLsSpecial characters in URLsHTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.Modification of URLs in responsesModification of URLs in requestsHandling cookies from servers across multiple -j junctions

Modification of URLs to junctioned resources

This chapter discusses the configuration options available to ensure that URL links sent from back-end application servers across standard WebSEAL junctions are reconstructed appropriately for use by clients.

The challenges of URL filtering are specific to standard WebSEAL junctions. WebSEAL also supports virtual hosting and, through virtual host junctions, can eliminate the limitations of URL filtering. WebSEAL uses the HTTP Host header in client requests to direct those requests to the appropriate document spaces located on junctioned servers or on the local machine.

Topic Index:

URL modification concepts

Path types used in URLs

Special characters in URLs
HTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.

Modification of URLs in responses

Modification of URLs in requests

Handling cookies from servers across multiple -j junctions

Parent topic: Standard WebSEAL Junctions

URL modification conceptsURL modification conceptsfilterURL modification conceptsURLmodificationconceptsPages returned to the client from back-end application servers often contain links to resources located on those servers. It is important that these URLs are constructed to correctly direct any client requests back to these resources.For example, in a non-WebSEAL environment, the URL entered by a client for a resource on an application server might appear as follows:http://www.example.com/file.htmlWebSEAL, as a front-end reverse proxy, provides security services to back-end application servers via the WebSEAL junctioning feature. This feature requires that the original URLs to these resources be modified to include the junction information. The standard junction feature of WebSEAL changes the server and path information that must be used to access resources on junctioned back-end systems. A link to a resource on a back-end junctioned server succeeds only if the URL contains the identity of the junction. If this same back-end server is a junctioned server in a WebSEAL environment, the URL used to access the same resource on a junctioned back-end application server must appear as follows:http://webseal.example.com/jct/file.htmlTo support the standard junction feature and maintain the integrity of URLs, WebSEAL must, where possible:Modify the URLs (links) found in responses sent to clientsModify requests for resources resulting from URLs (links) that WebSEAL could not changeWebSEAL's rules and mechanisms for modifying URLs do not apply to links that point to resources external to the Security Access Manager junctioned environment.The following diagram summarizes the solutions available to WebSEAL for modifying URLs to junctioned back-end resources:Summary: Modifying URLs to back-end resourcesSummary: Modifying URLs to back-end resourcesModification of URLs to junctioned resourcesPath types used in URLsSpecial characters in URLsHTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.Modification of URLs in responsesModification of URLs in requestsHandling cookies from servers across multiple -j junctions

URL modification concepts

Pages returned to the client from back-end application servers often contain links to resources located on those servers. It is important that these URLs are constructed to correctly direct any client requests back to these resources.

For example, in a non-WebSEAL environment, the URL entered by a client for a resource on an application server might appear as follows:

http://www.example.com/file.html

WebSEAL, as a front-end reverse proxy, provides security services to back-end application servers via the WebSEAL junctioning feature. This feature requires that the original URLs to these resources be modified to include the junction information.

The standard junction feature of WebSEAL changes the server and path information that must be used to access resources on junctioned back-end systems. A link to a resource on a back-end junctioned server succeeds only if the URL contains the identity of the junction.

If this same back-end server is a junctioned server in a WebSEAL environment, the URL used to access the same resource on a junctioned back-end application server must appear as follows:

http://webseal.example.com/jct/file.html

To support the standard junction feature and maintain the integrity of URLs, WebSEAL must, where possible:

Modify the URLs (links) found in responses sent to clients

Modify requests for resources resulting from URLs (links) that WebSEAL could not change

Note: WebSEAL's rules and mechanisms for modifying URLs do not apply to links that point to resources external to the Security Access Manager junctioned environment.

The following diagram summarizes the solutions available to WebSEAL for modifying URLs to junctioned back-end resources:

Figure 35. Summary: Modifying URLs to back-end resources

Parent topic: Modification of URLs to junctioned resources

Related concepts:

Modification of URLs in responses

Modification of URLs in requests

Related tasks:

Handling cookies from servers across multiple -j junctions

Related reference:

Path types used in URLs

Special characters in URLs

Path types used in URLs Path types used in URLs URLserver-relative pathspath typesrelative pathsabsolute pathsfilterpath types used in URLsabsolute path namesrelative path namesserver-relative path namespath namesabsoluterelativeserver-relativeAny HTML page is likely to contain URLs (links) to other resources on that back-end server or elsewhere. URL expressions can appear in the following formats: relativeserver-relativeabsoluteLinks containing URLs expressed in relative format never require any modification by WebSEAL. By default, the browser handles relative URLs in links by adding the correct scheme (protocol), server name, and directory information (including the junction) as a prefix to the relative URL. The browser derives this information from the location information of the page on which the link is located.Example relative URL expressions: abc.html ../abc.html ./abc.html sales/abc.htmlHowever, difficulties arise with server-relative and absolute path formats. A server-relative URL contains a full path expression (beginning at /), but contains to scheme (protocol) or server name. Example server-relative URL expressions: /abc.html /accounts/abc.htmlAn absolute URL contains the scheme (protocol), server name, and full path. Example absolute URL expression: http://www.example.com/doc/abc.htmlLinks to back-end resources expressed in absolute or server-relative formats succeed only if WebSEAL is able to modify the URL path expression to include junction information. WebSEAL URL modification techniques apply to absolute and server-relative URLs.To ensure successful location of resources, all programmers of Web scripts are encouraged to use relative links (not absolute or server-relative) for dynamically generated URLs. Modification of URLs to junctioned resourcesURL modification conceptsSpecial characters in URLsHTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.Modification of URLs in responsesModification of URLs in requestsHandling cookies from servers across multiple -j junctions

Path types used in URLs

Any HTML page is likely to contain URLs (links) to other resources on that back-end server or elsewhere. URL expressions can appear in the following formats:

relative

server-relative

absolute

Links containing URLs expressed in relative format never require any modification by WebSEAL. By default, the browser handles relative URLs in links by adding the correct scheme (protocol), server name, and directory information (including the junction) as a prefix to the relative URL. The browser derives this information from the location information of the page on which the link is located.

Example relative URL expressions:

abc.html
../abc.html
./abc.html
sales/abc.html

However, difficulties arise with server-relative and absolute path formats.

A server-relative URL contains a full path expression (beginning at /), but contains to scheme (protocol) or server name. Example server-relative URL expressions:

/abc.html
/accounts/abc.html

An absolute URL contains the scheme (protocol), server name, and full path. Example absolute URL expression:

http://www.example.com/doc/abc.html

Links to back-end resources expressed in absolute or server-relative formats succeed only if WebSEAL is able to modify the URL path expression to include junction information. WebSEAL URL modification techniques apply to absolute and server-relative URLs.

Note: To ensure successful location of resources, all programmers of Web scripts are encouraged to use relative links (not absolute or server-relative) for dynamically generated URLs.

Parent topic: Modification of URLs to junctioned resources

Related concepts:

URL modification concepts

Modification of URLs in responses

Modification of URLs in requests

Related tasks:

Handling cookies from servers across multiple -j junctions

Related reference:

Special characters in URLs

Special characters in URLs Special characters in URLs HTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.URLspecial HTML charactersfilterspecial HTML characters in URLsspecial HTML charactersThe HTML codes for special characters start with "&#" and end with ";". The HTML codes use the following format: &#<numeric_id>;where<numeric_id>A number or hex representation for the character. The maximum value of the number representation is 255 (Hex: 0xFF). For example, the percent sign (%) has a numerical code of &#37; and a hex code of &#x25;.For details about how WebSEAL can filter any special character encoding that exists in HTTP responses, see Modification of encoded or escaped URLsWebSEAL modifies and rewrites the URL references in outgoing responses to ensure that subsequent requests are sent through WebSEAL..Modification of URLs to junctioned resourcesURL modification conceptsPath types used in URLsModification of URLs in responsesModification of URLs in requestsHandling cookies from servers across multiple -j junctions

Special characters in URLs

HTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.

The HTML codes for special characters start with "&#" and end with ";".

The HTML codes use the following format:

&#<numeric_id>;

where

<numeric_id>

A number or hex representation for the character. The maximum value of the number representation is 255 (Hex: 0xFF).

For example, the percent sign (%) has a numerical code of &#37; and a hex code of &#x25;.

Note: For details about how WebSEAL can filter any special character encoding that exists in HTTP responses, see Modification of encoded or escaped URLs.

Parent topic: Modification of URLs to junctioned resources

Related concepts:

URL modification concepts

Modification of URLs in responses

Modification of URLs in requests

Related tasks:

Handling cookies from servers across multiple -j junctions

Related reference:

Path types used in URLs

Modification of URLs in responsesModification of URLs in responsesURLmodificationresponsesfiltermodifying URLsresponsesresponsesmodifying URLsThis section describes options for modifying URLs in responses from junctioned back-end application servers.Modification of URLs to junctioned resourcesURL modification conceptsPath types used in URLsSpecial characters in URLsHTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.Modification of URLs in requestsHandling cookies from servers across multiple -j junctionsFiltering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML). Modifying absolute URLs with script filteringConfiguring the rewrite-absolute-with-absolute optionFiltering changes the Content-Length headerLimitation with unfiltered server-relative links

Modification of URLs in responses

This section describes options for modifying URLs in responses from junctioned back-end application servers.

Filtering of tag-based static URLs
WebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

Modifying absolute URLs with script filtering

Configuring the rewrite-absolute-with-absolute option

Filtering changes the Content-Length header

Limitation with unfiltered server-relative links

Parent topic: Modification of URLs to junctioned resources

Related concepts:

URL modification concepts

Modification of URLs in requests

Related tasks:

Handling cookies from servers across multiple -j junctions

Related reference:

Path types used in URLs

Special characters in URLs

Filtering of tag-based static URLsFiltering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML). filtertag-based URL filteringtag-based static URLsfilteringThe term "filtering" is used to indicate WebSEAL's process of scanning Web documents for absolute and server-relative links and modifying the links to include junction information. An important requirement for this mechanism is that the URLs must be visible to WebSEAL. For example, tag-based content filtering cannot handle URLs that are dynamically generated on the client-side.When the preserve-base-href2 option is also set to "yes" WebSEAL only performs the minimum filtering of the BASE HREF tag necessary to insert the WebSEAL host and junction names. The value of the preserve-base-href2 option impacts the processing of any BASE HREF tags that are missing the trailing slash.REMINDER: This option has no effect if preserve-base-href is set to "no".Example 5 (BASE HREF that contains no trailing slash matches a junctioned server)WebSEAL server: www.webseal.comThe following junction was created: server task webseal-server create -tcp -h www.example.com /jctHTML before filteringNOTE: There is no trailing slash in the BASE HREF value:<HTML> <HEAD> <BASE HREF="http://www.example.com"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>HTML after filtering when preserve-base-href2 is set to "no". NOTE: WebSEAL maps the HREF to /jct and then eliminates the /jct because there is no trailing slash.<HTML> <HEAD> <BASE HREF="http://www.webseal.com/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>HTML after filtering when preserve-base-href2 is set to "yes". NOTE: WebSEAL performs the minimum filtering of the BASE HREF tag necessary to insert the WebSEAL host and junction names. The missing trailing slash does not cause the last component in the base HREF URL to be stripped.<HTML> <HEAD> <BASE HREF="http://www.webseal.com/jct/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>This section contains the following topics:Modification of URLs in responsesFilter rules for tag-based static URLsDefault filtering of tag-based static URLsModification of encoded or escaped URLsWebSEAL modifies and rewrites the URL references in outgoing responses to ensure that subsequent requests are sent through WebSEAL.Configuration of filtering for new content (MIME) typesTags and attributes for tag-based filteringHTML META tagsHTML BASE HREF tagsSchemes to ignore in pages using the BASE tag

Filtering of tag-based static URLs

WebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

The term "filtering" is used to indicate WebSEAL's process of scanning Web documents for absolute and server-relative links and modifying the links to include junction information.

An important requirement for this mechanism is that the URLs must be visible to WebSEAL. For example, tag-based content filtering cannot handle URLs that are dynamically generated on the client-side.

When the preserve-base-href2 option is also set to "yes" WebSEAL only performs the minimum filtering of the BASE HREF tag necessary to insert the WebSEAL host and junction names. The value of the preserve-base-href2 option impacts the processing of any BASE HREF tags that are missing the trailing slash.

REMINDER: This option has no effect if preserve-base-href is set to "no".

Example 5 (BASE HREF that contains no trailing slash matches a junctioned server)

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

HTML before filtering

NOTE: There is no trailing slash in the BASE HREF value:

<HTML>
<HEAD>
<BASE HREF="http://www.example.com">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

HTML after filtering when preserve-base-href2 is set to "no".

NOTE: WebSEAL maps the HREF to /jct and then eliminates the /jct because there is no trailing slash.

<HTML>
<HEAD>
<BASE HREF="http://www.webseal.com/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

HTML after filtering when preserve-base-href2 is set to "yes".

NOTE: WebSEAL performs the minimum filtering of the BASE HREF tag necessary to insert the WebSEAL host and junction names. The missing trailing slash does not cause the last component in the base HREF URL to be stripped.

<HTML>
<HEAD>
<BASE HREF="http://www.webseal.com/jct/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

This section contains the following topics:

Filter rules for tag-based static URLs

Default filtering of tag-based static URLs

Modification of encoded or escaped URLs
WebSEAL modifies and rewrites the URL references in outgoing responses to ensure that subsequent requests are sent through WebSEAL.

Configuration of filtering for new content (MIME) types

Tags and attributes for tag-based filtering

HTML META tags

HTML BASE HREF tags

Schemes to ignore in pages using the BASE tag

Parent topic: Modification of URLs in responses

Filter rules for tag-based static URLsFilter rules for tag-based static URLsfiltertag-based URL filteringrulesrelative URLsserver-relative URLsabsolute URLstag-based static URLsfilteringFilter rules for relative URLs:Relative URLs are always handled appropriately by the browser. Therefore, WebSEAL does not filter relative URLs.By default, the browser add the correct scheme, server, and directory information (including the junction) to the beginning of the relative URL. The added information is derived from the request URL for the page on which the link is located.Filter rules for server-relative URLs:WebSEAL must add the junction name to the path of server-relative URLs that refer to resources located on junctioned servers. Server-relative URLs indicate a URL position in relation to the document root of the junctioned server, for example:/dir/file.htmlServer-relative URLs are modified by adding the junction point of the junctioned server to the path name. For example: /jct/dir/file.htmlFilter rules for absolute URLs:WebSEAL must add the junction name to the path of absolute URLs that refer to resources located on junctioned servers. Absolute URLs indicate a URL position in relation to a host name or IP address (and, optionally, a network port). For example:http://host-name[:port]/file.html, or https://host-name[:port]/file.htmlAbsolute URLs are modified according to the following set of rules: If the URL is HTTP and the host/port matches a TCP junctioned server, the URL is modified to be server-relative to WebSEAL and reflect the junction point. For example: http://host-name[:port]/file.html becomes: /tcpjct/file.htmlIf the URL is HTTPS and the host/port matches an SSL junctioned server, the URL is modified to be server-relative to WebSEAL and reflect the junction point. For example: https://host-name[:port]/file.html becomes: /ssljct/file.htmlSee also Configuring the rewrite-absolute-with-absolute option.See Modifying absolute URLs with script filtering for an alternative absolute URL filtering mechanism.Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

Filter rules for tag-based static URLs

Filter rules for relative URLs:

Relative URLs are always handled appropriately by the browser. Therefore, WebSEAL does not filter relative URLs.

By default, the browser add the correct scheme, server, and directory information (including the junction) to the beginning of the relative URL. The added information is derived from the request URL for the page on which the link is located.

Filter rules for server-relative URLs:

WebSEAL must add the junction name to the path of server-relative URLs that refer to resources located on junctioned servers.

Server-relative URLs indicate a URL position in relation to the document root of the junctioned server, for example:

/dir/file.html

Server-relative URLs are modified by adding the junction point of the junctioned server to the path name. For example:

/jct/dir/file.html

Filter rules for absolute URLs:

WebSEAL must add the junction name to the path of absolute URLs that refer to resources located on junctioned servers.

Absolute URLs indicate a URL position in relation to a host name or IP address (and, optionally, a network port). For example:

http://host-name[:port]/file.html, or
https://host-name[:port]/file.html

Absolute URLs are modified according to the following set of rules:

If the URL is HTTP and the host/port matches a TCP junctioned server, the URL is modified to be server-relative to WebSEAL and reflect the junction point. For example:

http://host-name[:port]/file.html

becomes:

/tcpjct/file.html

If the URL is HTTPS and the host/port matches an SSL junctioned server, the URL is modified to be server-relative to WebSEAL and reflect the junction point. For example:

https://host-name[:port]/file.html

becomes:

/ssljct/file.html

See also Configuring the rewrite-absolute-with-absolute option.

See Modifying absolute URLs with script filtering for an alternative absolute URL filtering mechanism.

Parent topic: Filtering of tag-based static URLs

Default filtering of tag-based static URLsDefault filtering of tag-based static URLsfilterdefault filtering of tag-based static URLsfilter-content-types stanzatext/htmltext/vnd.wap.wmlfilter-url stanzaWebSEAL filters tag-based static URLs that are located in pages with content (MIME) types specified in the [filter-content-types] stanza of the WebSEAL configuration file.By default, this stanza specifies MIME types text/html and text/vnd.wap.wml. [filter-content-types] type = text/html type = text/vnd.wap.wmlThe [filter-url] stanza of the WebSEAL configuration file specifies the tags and tag attributes to be filtered in the content. Because most commonly used HTML tags and tag attributes are listed in this stanza by default, tag-based filtering for the default text/html and text/vnd.wap.wml MIME types typically operates without any additional configuration.Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

Default filtering of tag-based static URLs

WebSEAL filters tag-based static URLs that are located in pages with content (MIME) types specified in the [filter-content-types] stanza of the WebSEAL configuration file.

By default, this stanza specifies MIME types text/html and text/vnd.wap.wml.

[filter-content-types]
type = text/html
type = text/vnd.wap.wml

The [filter-url] stanza of the WebSEAL configuration file specifies the tags and tag attributes to be filtered in the content. Because most commonly used HTML tags and tag attributes are listed in this stanza by default, tag-based filtering for the default text/html and text/vnd.wap.wml MIME types typically operates without any additional configuration.

Parent topic: Filtering of tag-based static URLs

Modification of encoded or escaped URLsModification of encoded or escaped URLsModification of encoded or escaped URLs in WebSEALWebSEAL modifies and rewrites the URL references in outgoing responses to ensure that subsequent requests are sent through WebSEAL.encodingURLsescaped URLsURLmodificationencodedescapedWebSEAL rewrites each URL in its original form with the URI encoding or slash escaping. If WebSEAL encounters special character encoding, it replaces the HTML code with the special character that the code represents. The following table describes the URI encoding types that WebSEAL filters during this process.Filtered encoding typesWebSEAL filters the following encoding types.Encoding typeExample of encoded URLAmpersand encodedHTTP://host&#x3a;port/path?V1=D1&amp;V2=D2Ampersand - hex encodedHTTP&#x3a;&#x2f;&#x2f;host&#x3a;port&#x2f;Ampersand - dec encodedHTTP&#58;&#57;&#57;host&#58;port&#57;Backslash encodedHTTP:\/\/host:port\/Percent hex encodedHTTP%3A%2F%2Fhost%3Aport%2FExample: Filtering of URLsWebSEAL server: www.webseal.comThe following junction was created:server task webseal-server create -tcp -h www.example.com /jctThe HTML before the WebSEAL filtering process:<HTML> <BODY> <A HREF="http%3A%2F%2Fwww.example.com%2Findex.html">index.html</A> <A HREF="http:\/\/www.example.com\/page2.html">page2.html</A> <A HREF="http://www.example.com/page3.html">page3.html</A> <A HREF="http&#x3A;&#x2F;&#x2F;www.example.com&#x2F;page4.htm">page4.html</A> </BODY> </HTML>HTML after the WebSEAL filtering process with the configuration item [script-filtering] rewrite-absolute-with-absolute set to no:<HTML> <BODY> <A HREF="%2Fjct%2Findex.html">index.html</A> <A HREF="\/jct\/page2.html">page2.html</A> <A HREF="/jct/page3.html">page3.html</A> <A HREF="&#x2F;jct&#x2F;page4.htm">page4.html</A> </BODY> </HTML>HTML after the WebSEAL filtering process with the configuration item [script-filtering] rewrite-absolute-with-absolute set to yes:<HTML> <BODY> <A HREF="http%3A%2F%2Fwww.webseal.com%2Fjct%2Findex.html">index.html</A> <A HREF="http:\/\/www.webseal.com\/jct\/page2.html">page2.html</A> <A HREF="http://www.webseal.com/jct/page3.html">page3.html</A> <A HREF="http&#x3A;&#x2F;&#x2F;www.webseal.com&#x2F;jct&#x2F;page4.htm"> page4.html</A> </BODY> </HTML>Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

Modification of encoded or escaped URLs

WebSEAL modifies and rewrites the URL references in outgoing responses to ensure that subsequent requests are sent through WebSEAL.

WebSEAL rewrites each URL in its original form with the URI encoding or slash escaping. If WebSEAL encounters special character encoding, it replaces the HTML code with the special character that the code represents.

The following table describes the URI encoding types that WebSEAL filters during this process.

Table 62. Filtered encoding types. WebSEAL filters the following encoding types.

Encoding type | Example of encoded URL
Ampersand encoded | HTTP://host&#x3a;port/path?V1=D1&amp;V2=D2
Ampersand - hex encoded | HTTP&#x3a;&#x2f;&#x2f;host&#x3a;port&#x2f;
Ampersand - dec encoded | HTTP&#58;&#57;&#57;host&#58;port&#57;
Backslash encoded | HTTP:\/\/host:port\/
Percent hex encoded | HTTP%3A%2F%2Fhost%3Aport%2F

Example: Filtering of URLs

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

The HTML before the WebSEAL filtering process:

<HTML>
<BODY>
<A HREF="http%3A%2F%2Fwww.example.com%2Findex.html">index.html</A>
<A HREF="http:\/\/www.example.com\/page2.html">page2.html</A>
<A HREF="http://www.example.com/page3.html">page3.html</A>
<A HREF="http&#x3A;&#x2F;&#x2F;www.example.com&#x2F;page4.htm">page4.html</A>
</BODY>
</HTML>

HTML after the WebSEAL filtering process with the configuration item [script-filtering] rewrite-absolute-with-absolute set to no:

<HTML>
<BODY>
<A HREF="%2Fjct%2Findex.html">index.html</A>
<A HREF="\/jct\/page2.html">page2.html</A>
<A HREF="/jct/page3.html">page3.html</A>
<A HREF="&#x2F;jct&#x2F;page4.htm">page4.html</A>
</BODY>
</HTML>

HTML after the WebSEAL filtering process with the configuration item [script-filtering] rewrite-absolute-with-absolute set to yes:

<HTML>
<BODY>
<A HREF="http%3A%2F%2Fwww.webseal.com%2Fjct%2Findex.html">index.html</A>
<A HREF="http:\/\/www.webseal.com\/jct\/page2.html">page2.html</A>
<A HREF="http://www.webseal.com/jct/page3.html">page3.html</A>
<A HREF="http&#x3A;&#x2F;&#x2F;www.webseal.com&#x2F;jct&#x2F;page4.htm">
page4.html</A>
</BODY>
</HTML>

Parent topic: Filtering of tag-based static URLs

Configuration of filtering for new content (MIME) typesConfiguration of filtering for new content (MIME) typesfilterspecifying new content (MIME) typesfilter-nonhtml-as-xhtmlscript-filtering stanzafilter-nonhtml-as-xhtmlAdditional MIME types can be configured for URL filtering by adding appropriate entries to the [filter-content-types] stanza. The default filtering mechanism for new MIME types added to the [filter-content-types] stanza is script filtering. You must edit the WebSEAL configuration file to enable script filtering (script filtering is disabled by default):[script-filtering] script-filter = yesThe script filtering mechanism examines the entire contents of the response and is not restricted to tag-based content. However, script filtering only examines and modifies absolute URLs. See Modifying absolute URLs with script filtering.Alternatively, you can enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza. To enable tag-based static URL filtering for new configured MIME types, set the value of the filter-nonhtml-as-xhtml stanza entry in the [server] stanza of the WebSEAL configuration file to "yes":[server] filter-nonhtml-as-xhtml = yesSpecify any additional tags and tag attributes to be filtered, as described in Tags and attributes for tag-based filtering. Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

Configuration of filtering for new content (MIME) types

Additional MIME types can be configured for URL filtering by adding appropriate entries to the [filter-content-types] stanza.

The default filtering mechanism for new MIME types added to the [filter-content-types] stanza is script filtering. You must edit the WebSEAL configuration file to enable script filtering (script filtering is disabled by default):

[script-filtering]
script-filter = yes

The script filtering mechanism examines the entire contents of the response and is not restricted to tag-based content. However, script filtering only examines and modifies absolute URLs. See Modifying absolute URLs with script filtering.

Alternatively, you can enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza. To enable tag-based static URL filtering for new configured MIME types, set the value of the filter-nonhtml-as-xhtml stanza entry in the [server] stanza of the WebSEAL configuration file to "yes":

[server]
filter-nonhtml-as-xhtml = yes

Specify any additional tags and tag attributes to be filtered, as described in Tags and attributes for tag-based filtering.

Parent topic: Filtering of tag-based static URLs

Tags and attributes for tag-based filteringTags and attributes for tag-based filteringfilterspecifying tags and attributesfilter-url stanzaTag-based static URL filtering is constrained to the specific tags and tag attributes defined in the [filter-url] stanza of the WebSEAL configuration file. The filtering mechanism looks only for URLs located within the specified tags and tag attributes.You can add entries to the [filter-url] stanza to specify any additional tags and tag attributes to be filtered. Tags and tag attributes can include HTML, XML, XHTML, or custom data definitions.Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

Tags and attributes for tag-based filtering

Tag-based static URL filtering is constrained to the specific tags and tag attributes defined in the [filter-url] stanza of the WebSEAL configuration file. The filtering mechanism looks only for URLs located within the specified tags and tag attributes.

You can add entries to the [filter-url] stanza to specify any additional tags and tag attributes to be filtered. Tags and tag attributes can include HTML, XML, XHTML, or custom data definitions.

Parent topic: Filtering of tag-based static URLs

HTML META tagsHTML META tagsfilterHTML META refresh tagsHTML META tagsHTML META refresh tags are always filtered. For example: <META HTTP-EQUIV="Refresh" CONTENT="5;URL=http://server/url">Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

HTML META tags

HTML META refresh tags are always filtered. For example:

<META HTTP-EQUIV="Refresh" CONTENT="5;URL=http://server/url">

Parent topic: Filtering of tag-based static URLs

HTML BASE HREF tagsHTML BASE HREF tagsfilterHTML BASE HREF tagspreserve-base-href stanza entrypreserve-base-href2 stanza entrypreserve-base-href stanza entrypreserve-base-href2 stanza entryYou can use the preserve-base-href and the preserve-base-href2 entries in the [server] stanza to control how WebSEAL handles the HREF attributes of HTML BASE tags in filtered HTML documents. The value of preserve-base-href2 has no effect unless the preserve-base-href option is set to "yes".When preserve-base-href is set to "no", the following statements apply:WebSEAL removes the BASE HREF attributes from filtered HTML documents.When the BASE HREF URL matches a junctioned server, WebSEAL prepends the junction point, and any subdirectories, to server-relative and relative links found on the page.When the BASE HREF URL does not match a junctioned server, WebSEAL prepends the entire BASE HREF URL attribute to server-relative and relative links on the page. This action is exactly what the browser does when it renders HTML.Example 1 (BASE HREF matches a junctioned server)WebSEAL server: www.webseal.comThe following junction was created: server task webseal-server create -tcp -h www.example.com /jctHTML before filtering:<HTML> <HEAD> <BASE HREF="http://www.example.com/dir1/dir2/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>HTML after filtering:<HTML> <HEAD> <BASE> </HEAD> <BODY> <A HREF="/jct/dir1/dir2/index.html">index.html</A> </BODY> </HTML>Example 2 (BASE HREF does not match a junctioned server)WebSEAL server: www.webseal.comThe following junction was created: server task webseal-server create -tcp -h www.example.com /jctHTML before filtering:<HTML> <HEAD> <BASE HREF="http://www.example2.com/dir1/dir2/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>HTML after filtering:<HTML> <HEAD> <BASE> </HEAD> <BODY> <A HREF="http://www.example2.com/dir1/dir2/index.html">index.html</A> </BODY> </HTML>When preserve-base-href is set to "yes", the following statements apply:WebSEAL does not remove the BASE HREF attributes from filtered HTML documents.When the BASE HREF URL matches a junctioned server, WebSEAL modifies the BASE HREF URL. WebSEAL replaces the name of the junctioned server with the WebSEAL server name, plus the junction point of the junctioned server. When the browser renders the HTML, and prepends the modified HREF URL to server-relative and relative links, the resulting links can find the resources.When the BASE HREF URL does not match a junctioned server, WebSEAL does not modify the HTML. When the browser renders the HTML, and prepends the original HREF URLs to server-relative and relative links, the resulting links can find the resources.When WebSEAL filters an HTML document with a BASE HREF tag, WebSEAL does not preserve the original escaping or encoding of the URL if it contains: URI encodingEscaped slashesSpecial character encodingExample 3 (URI Encoded, slash-escaped and Special Character URLS)WebSEAL server: www.webseal.comThe following junction was created:server task webseal-server create -tcp -h www.example.com /jctHTML before filtering:<HTML> <HEAD> <BASE HREF="http://www.example2.com/dir1/"> </HEAD> <BODY> <A HREF="dir2%2Findex.html">index.html</A> <A HREF="dir2\/contents.html">contents.html</A> <A HREF="dir2&#x2F;index2.html">index2.html</A> </BODY> </HTML>HTML after filtering:<HTML> <HEAD> <BASE> </HEAD> <BODY> <A HREF="http://www.example2.com/dir1/dir2/index.html">index.html</A> <A HREF="http://www.example2.com/dir1/dir2/contents.html">contents.html</A> <A HREF="http://www.example2.com/dir1/dir2/index2.html">index2.html</A> </BODY> </HTML>Example 4 (BASE HREF matches a junctioned server)WebSEAL server: www.webseal.comThe following junction was created: server task webseal-server create -tcp -h www.example.com /jctHTML before filtering:<HTML> <HEAD> <BASE HREF="http://www.example.com/dir1/dir2/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>HTML after filtering:<HTML> <HEAD> <BASE HREF="http://www.webseal.com/jct/dir1/dir2/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>Example 5 (BASE HREF does not match a junctioned server)WebSEAL server: www.webseal.comThe following junction was created: server task webseal-server create -tcp -h www.example.com /jctHTML before filtering:<HTML> <HEAD> <BASE HREF="http://www.example2.com/dir1/dir2/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>HTML after filtering:<HTML> <HEAD> <BASE HREF="http://www.example2.com/dir1/dir2/"> </HEAD> <BODY> <A HREF="index.html">index.html</A> </BODY> </HTML>Example 6 (URI Encoded, slash-escaped and Special Character URLs)WebSEAL server: www.webseal.comThe following junction was created:server task webseal-server create -tcp -h www.example.com /jctHTML before filtering:<HTML> <HEAD> <BASE HREF="http://www.example.com/dir1/"> </HEAD> <BODY> <A HREF="dir2%2Findex.html">index.html</A> <A HREF="dir2\/contents.html">contents.html</A> <A HREF="dir2&#X2F;index2.html">index2.html</A> </BODY> </HTML>HTML after filtering:<HTML> <HEAD> <BASE HREF="http://www.webseal.com/jct/dir1/"> </HEAD> <BODY> <A HREF="dir2/index.html">index.html</A> <A HREF="dir2/contents.html">contents.html</A> <A HREF="dir2/index2.html">index2.html</A> </BODY> </HTML>Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

HTML BASE HREF tags

You can use the preserve-base-href and the preserve-base-href2 entries in the [server] stanza to control how WebSEAL handles the HREF attributes of HTML BASE tags in filtered HTML documents.

Note: The value of preserve-base-href2 has no effect unless the preserve-base-href option is set to "yes".

When preserve-base-href is set to "no", the following statements apply:

WebSEAL removes the BASE HREF attributes from filtered HTML documents.

When the BASE HREF URL matches a junctioned server, WebSEAL prepends the junction point, and any subdirectories, to server-relative and relative links found on the page.

When the BASE HREF URL does not match a junctioned server, WebSEAL prepends the entire BASE HREF URL attribute to server-relative and relative links on the page. This action is exactly what the browser does when it renders HTML.

Example 1 (BASE HREF matches a junctioned server)

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

HTML before filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.example.com/dir1/dir2/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

HTML after filtering:

<HTML>
<HEAD>
<BASE>
</HEAD>
<BODY>
<A HREF="/jct/dir1/dir2/index.html">index.html</A>
</BODY>
</HTML>

Example 2 (BASE HREF does not match a junctioned server)

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

HTML before filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.example2.com/dir1/dir2/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

HTML after filtering:

<HTML>
<HEAD>
<BASE>
</HEAD>
<BODY>
<A HREF="http://www.example2.com/dir1/dir2/index.html">index.html</A>
</BODY>
</HTML>

When preserve-base-href is set to "yes", the following statements apply:

WebSEAL does not remove the BASE HREF attributes from filtered HTML documents.

When the BASE HREF URL matches a junctioned server, WebSEAL modifies the BASE HREF URL. WebSEAL replaces the name of the junctioned server with the WebSEAL server name, plus the junction point of the junctioned server. When the browser renders the HTML, and prepends the modified HREF URL to server-relative and relative links, the resulting links can find the resources.

When the BASE HREF URL does not match a junctioned server, WebSEAL does not modify the HTML. When the browser renders the HTML, and prepends the original HREF URLs to server-relative and relative links, the resulting links can find the resources.

When WebSEAL filters an HTML document with a BASE HREF tag, WebSEAL does not preserve the original escaping or encoding of the URL if it contains:

URI encoding

Escaped slashes

Special character encoding

Example 3 (URI Encoded, slash-escaped and Special Character URLS)

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

HTML before filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.example2.com/dir1/">
</HEAD>
<BODY>
<A HREF="dir2%2Findex.html">index.html</A>
<A HREF="dir2\/contents.html">contents.html</A>
<A HREF="dir2&#x2F;index2.html">index2.html</A>
</BODY>
</HTML>

HTML after filtering:

<HTML>
<HEAD>
<BASE>
</HEAD>
<BODY>
<A HREF="http://www.example2.com/dir1/dir2/index.html">index.html</A>
<A HREF="http://www.example2.com/dir1/dir2/contents.html">contents.html</A>
<A HREF="http://www.example2.com/dir1/dir2/index2.html">index2.html</A>
</BODY>
</HTML>

Example 4 (BASE HREF matches a junctioned server)

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

HTML before filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.example.com/dir1/dir2/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

HTML after filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.webseal.com/jct/dir1/dir2/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

Example 5 (BASE HREF does not match a junctioned server)

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

HTML before filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.example2.com/dir1/dir2/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

HTML after filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.example2.com/dir1/dir2/">
</HEAD>
<BODY>
<A HREF="index.html">index.html</A>
</BODY>
</HTML>

Example 6 (URI Encoded, slash-escaped and Special Character URLs)

WebSEAL server: www.webseal.com

The following junction was created:

server task webseal-server create -tcp -h www.example.com /jct

HTML before filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.example.com/dir1/">
</HEAD>
<BODY>
<A HREF="dir2%2Findex.html">index.html</A>
<A HREF="dir2\/contents.html">contents.html</A>
<A HREF="dir2&#X2F;index2.html">index2.html</A>
</BODY>
</HTML>

HTML after filtering:

<HTML>
<HEAD>
<BASE HREF="http://www.webseal.com/jct/dir1/">
</HEAD>
<BODY>
<A HREF="dir2/index.html">index.html</A>
<A HREF="dir2/contents.html">contents.html</A>
<A HREF="dir2/index2.html">index2.html</A>
</BODY>
</HTML>

Parent topic: Filtering of tag-based static URLs

Schemes to ignore in pages using the BASE tagSchemes to ignore in pages using the BASE tagfilterschemesfilter-schemes stanzaThe [filter-schemes] stanza lists those URL schemes that are not to be filtered by WebSEAL in responses from junctioned application servers. A scheme is a protocol identifier. This list is used when WebSEAL encounters documents containing HREF attributes in HTML BASE tags. The [filter-schemes] stanza contains a set of default schemes. You can extend the list with additional protocols.The recommended practice is to not delete entries from this list.The "http" and "https" schemes are hard-coded to always be filtered.When adding entries to the stanza, the trailing colon (:) on the scheme name is optional. When the colon is missing, WebSEAL assumes it. Default scheme entries:[filter-schemes] scheme = file scheme = ftp scheme = mailto scheme = news scheme = telnetIf a URL in a response does not use a scheme from this stanza, and the scheme is not "http" or "https", then WebSEAL assumes the URL is the same scheme as the junctioned server (HTTP: or HTTPS:) with it's scheme missing.Exception! If the response contains an HTML BASE tag with an HREF URL attribute that uses a scheme from the stanza, WebSEAL filters the URL.Filtering of tag-based static URLsWebSEAL uses a set of default rules to scan for (or filter) tag-based static URLs contained in pages that are responses to client requests. This default filtering mechanism examines static URLs located within tag-based content (such as HTML or XML).

Schemes to ignore in pages using the BASE tag

The [filter-schemes] stanza lists those URL schemes that are not to be filtered by WebSEAL in responses from junctioned application servers. A scheme is a protocol identifier. This list is used when WebSEAL encounters documents containing HREF attributes in HTML BASE tags.

The [filter-schemes] stanza contains a set of default schemes.

You can extend the list with additional protocols.

The recommended practice is to not delete entries from this list.

The "http" and "https" schemes are hard-coded to always be filtered.

When adding entries to the stanza, the trailing colon (:) on the scheme name is optional. When the colon is missing, WebSEAL assumes it.

Default scheme entries:

[filter-schemes]
scheme = file
scheme = ftp
scheme = mailto
scheme = news
scheme = telnet

If a URL in a response does not use a scheme from this stanza, and the scheme is not "http" or "https", then WebSEAL assumes the URL is the same scheme as the junctioned server (HTTP: or HTTPS:) with it's scheme missing.

Exception! If the response contains an HTML BASE tag with an HREF URL attribute that uses a scheme from the stanza, WebSEAL filters the URL.

Parent topic: Filtering of tag-based static URLs

Modifying absolute URLs with script filtering Modifying absolute URLs with script filtering script-filter stanza entryscript-filtering stanzascript filtering (absolute URLs)filterabsolute URLs with script filteringscript filtering (absolute URLs) WebSEAL requires additional configuration to handle the processing of absolute URLs embedded in scripts. Web scripting languages include JavaScript, VBScript, ASP, JSP, ActiveX, and others. The script-filter stanza entry in the [script-filtering] stanza of the WebSEAL configuration file enables or disables filtering of embedded absolute URLs. Script filtering is disabled by default: [script-filtering] script-filter = no To enable script filtering, set this the value of this stanza entry to "yes": [script-filtering] script-filter = yesThe script filtering mechanism examines the entire contents of a response and is not restricted to, for example, tag-based content.The script-filter mechanism expects absolute URLs with a standard scheme, server, resource format: http://server/resourceThe script-filter mechanism replaces the scheme and server portions of the link with the correct junction information (as a relative pathname): /junction-name/resourceThis filtering solution parses a script embedded in HTML code and therefore requires additional processing overhead that can negatively impact performance. The setting applies to all junctions. Only enable the script-filter stanza entry when your WebSEAL environment requires filtering of embedded absolute URLs.The following diagram illustrates this absolute URL filtering solution: Filtering absolute URLsFiltering absolute URLsModification of URLs in responses

Modifying absolute URLs with script filtering

About this task

WebSEAL requires additional configuration to handle the processing of absolute URLs embedded in scripts. Web scripting languages include JavaScript, VBScript, ASP, JSP, ActiveX, and others. The script-filter stanza entry in the [script-filtering] stanza of the WebSEAL configuration file enables or disables filtering of embedded absolute URLs. Script filtering is disabled by default:

[script-filtering]
script-filter = no

Procedure

To enable script filtering, set this the value of this stanza entry to "yes":

[script-filtering]
script-filter = yes

The script filtering mechanism examines the entire contents of a response and is not restricted to, for example, tag-based content.

The script-filter mechanism expects absolute URLs with a standard scheme, server, resource format:

http://server/resource

The script-filter mechanism replaces the scheme and server portions of the link with the correct junction information (as a relative pathname):

/junction-name/resource

This filtering solution parses a script embedded in HTML code and therefore requires additional processing overhead that can negatively impact performance. The setting applies to all junctions. Only enable the script-filter stanza entry when your WebSEAL environment requires filtering of embedded absolute URLs.

The following diagram illustrates this absolute URL filtering solution:

Figure 36. Filtering absolute URLs

Parent topic: Modification of URLs in responses

Configuring the rewrite-absolute-with-absolute optionConfiguring the rewrite-absolute-with-absolute optionrewrite-absolute-with-absolute optionrewrite-absolute-with-absolute stanza entryfilterrewrite-absolute-with-absolute WebSEAL normally filters absolute URLs by adding the junction point and changing the format to a server-relative expression. This rule for filtering absolute URLs applies to tag-based filtering and script filtering. You can optionally configure WebSEAL to rewrite the original absolute URL as an absolute URL, instead of a relative URL. To enable this type of filtering, set the value of the rewrite-absolute-with-absolute stanza entry in the [script-filtering] stanza of the WebSEAL configuration file to equal "yes":[script-filtering] rewrite-absolute-with-absolute = yesWhen rewrite-absolute-with-absolute is enabled, the following example URL in a response from a back-end server (connected to WebSEAL through jctA):http://server/abc.htmlis modified as follows:http://webseal-hostname/jctA/abc.htmlEnabling rewrite-absolute-with-absolute affects both tag-based filtering and script filtering. See:Modifying absolute URLs with script filtering andFilter rules for tag-based static URLsModification of URLs in responses

Configuring the rewrite-absolute-with-absolute option

About this task

WebSEAL normally filters absolute URLs by adding the junction point and changing the format to a server-relative expression. This rule for filtering absolute URLs applies to tag-based filtering and script filtering. You can optionally configure WebSEAL to rewrite the original absolute URL as an absolute URL, instead of a relative URL.

Procedure

To enable this type of filtering, set the value of the rewrite-absolute-with-absolute stanza entry in the [script-filtering] stanza of the WebSEAL configuration file to equal "yes":

[script-filtering]
rewrite-absolute-with-absolute = yes

When rewrite-absolute-with-absolute is enabled, the following example URL in a response from a back-end server (connected to WebSEAL through jctA):

http://server/abc.html

is modified as follows:

http://webseal-hostname/jctA/abc.html

Enabling rewrite-absolute-with-absolute affects both tag-based filtering and script filtering. See:

Modifying absolute URLs with script filtering and

Filter rules for tag-based static URLs

Parent topic: Modification of URLs in responses

Filtering changes the Content-Length header Filtering changes the Content-Length header Content-Lenth header changes during filteringfilterContent-Length header changesX-Old-Content-LengthNormally, the Content-Length header in a response from a back-end server indicates the size of the content being returned. When WebSEAL filters URLs and adds junction information to the path of URLs contained in the page, the actual size of the page becomes larger than indicated in the Content-Length header.WebSEAL has no way of knowing what the new content length is until it actually writes the stream to the client. At this point, it is too late to insert a new Content-Length header. WebSEAL responds to this situation in the following manner:WebSEAL places the value of the original Content-Length header in a new header called X-Old-Content-LengthAny applets or applications written to look for this header can have access to the original (pre-filtered) Content-Length value.WebSEAL logs the modified (post-filtered) Content-Length value in the request.log file.The Content-Length header no longer appears.Modification of URLs in responses

Filtering changes the Content-Length header

About this task

Normally, the Content-Length header in a response from a back-end server indicates the size of the content being returned. When WebSEAL filters URLs and adds junction information to the path of URLs contained in the page, the actual size of the page becomes larger than indicated in the Content-Length header.

WebSEAL has no way of knowing what the new content length is until it actually writes the stream to the client. At this point, it is too late to insert a new Content-Length header. WebSEAL responds to this situation in the following manner:

Procedure

WebSEAL places the value of the original Content-Length header in a new header called X-Old-Content-Length

Any applets or applications written to look for this header can have access to the original (pre-filtered) Content-Length value.

WebSEAL logs the modified (post-filtered) Content-Length value in the request.log file.

The Content-Length header no longer appears.

Parent topic: Modification of URLs in responses

Limitation with unfiltered server-relative linksLimitation with unfiltered server-relative linksfilterunfiltered server-relative linkslimitationsunfiltered server-relative linksunfiltered server-relative linksserver-relative linksModification of URLs in responsesProblemWebSEAL provides solutions for processing client-side, script-generated, server-relative URLs to resources on back-end junctioned application servers. The server-relative URLs generated on the client-side by applets and scripts initially lack knowledge of the junction point in the path expression. During a client request for a resource, WebSEAL can attempt to reprocess a server-relative URL using junction cookies or a junction mapping table.Workaround:

Limitation with unfiltered server-relative links

Problem
WebSEAL provides solutions for processing client-side, script-generated, server-relative URLs to resources on back-end junctioned application servers. The server-relative URLs generated on the client-side by applets and scripts initially lack knowledge of the junction point in the path expression. During a client request for a resource, WebSEAL can attempt to reprocess a server-relative URL using junction cookies or a junction mapping table.

Workaround:

Parent topic: Modification of URLs in responses

ProblemProblemWebSEAL issue: unprocessed requestWebSEAL provides solutions for processing client-side, script-generated, server-relative URLs to resources on back-end junctioned application servers. The server-relative URLs generated on the client-side by applets and scripts initially lack knowledge of the junction point in the path expression. During a client request for a resource, WebSEAL can attempt to reprocess a server-relative URL using junction cookies or a junction mapping table.WebSEALissue unprocessed requestHowever, before the processing takes place, the request actually specifies a resource located on the local Web space of the WebSEAL server itself. The corrective reprocessing of the URL occurs only after WebSEAL receives the request and performs an ACL check. An ACL check on the unprocessed request that specifies an incorrect or nonexistent local resource, might result in an error. The error might stop the request.For example, the following sequence takes place during processing: The client makes a request for a resource using a client-side, script-generated, server-relative URL.The server-relative URL is received by WebSEAL as a request. The unprocessed URL specifies a resource located in the Web space of the WebSEAL server itself (obviously, this is not the intended resource).WebSEAL performs an ACL check on this local resource specified in the request URL. If the ACL check fails, all processing of the request stops and the client receives a 403 error (Forbidden). This error occurs because the ACL check was performed for the incorrect (and probably nonexistent) resource.If the ACL check succeeds and the resource exists in the local Web space, it is returned. This error results in the client receiving the incorrect resource.If the ACL check succeeds and the resource does not exist in the local Web space, WebSEAL modifies the request URL (using the junction cookie or junction mapping table method) and performs an internal reprocessing of the request. This behavior is correct.WebSEAL performs another ACL check on the modified URL that contains the corrected path that includes the junction point. This modified URL now allows an ACL check for the correct resource.Limitation with unfiltered server-relative links

Problem

WebSEAL provides solutions for processing client-side, script-generated, server-relative URLs to resources on back-end junctioned application servers. The server-relative URLs generated on the client-side by applets and scripts initially lack knowledge of the junction point in the path expression. During a client request for a resource, WebSEAL can attempt to reprocess a server-relative URL using junction cookies or a junction mapping table.

However, before the processing takes place, the request actually specifies a resource located on the local Web space of the WebSEAL server itself. The corrective reprocessing of the URL occurs only after WebSEAL receives the request and performs an ACL check.

An ACL check on the unprocessed request that specifies an incorrect or nonexistent local resource, might result in an error. The error might stop the request.

For example, the following sequence takes place during processing:

The client makes a request for a resource using a client-side, script-generated, server-relative URL.

The server-relative URL is received by WebSEAL as a request.

The unprocessed URL specifies a resource located in the Web space of the WebSEAL server itself (obviously, this is not the intended resource).

WebSEAL performs an ACL check on this local resource specified in the request URL.

If the ACL check fails, all processing of the request stops and the client receives a 403 error (Forbidden). This error occurs because the ACL check was performed for the incorrect (and probably nonexistent) resource.

If the ACL check succeeds and the resource exists in the local Web space, it is returned. This error results in the client receiving the incorrect resource.

If the ACL check succeeds and the resource does not exist in the local Web space, WebSEAL modifies the request URL (using the junction cookie or junction mapping table method) and performs an internal reprocessing of the request. This behavior is correct.

WebSEAL performs another ACL check on the modified URL that contains the corrected path that includes the junction point. This modified URL now allows an ACL check for the correct resource.

Parent topic: Limitation with unfiltered server-relative links

Workaround:Workaround:WebSEALworkaroundsTo solve this problem: Always write scripts that generate relative URL links. Avoid absolute and server-relative URL links.If you must use server-relative links, do not duplicate resource names and paths on both the WebSEAL server and the junctioned application server.If you must use server-relative links, design your ACL model so that more prohibitive ACLs do not affect false resources specified by unfiltered URLs.Limitation with unfiltered server-relative links

Workaround:

To solve this problem:

Always write scripts that generate relative URL links. Avoid absolute and server-relative URL links.

If you must use server-relative links, do not duplicate resource names and paths on both the WebSEAL server and the junctioned application server.

If you must use server-relative links, design your ACL model so that more prohibitive ACLs do not affect false resources specified by unfiltered URLs.

Parent topic: Limitation with unfiltered server-relative links

Modification of URLs in requests Modification of URLs in requests URLmodificationURLs in requestsfiltermodifying URLsrequestsrequestsmodifying URLsDifficulties arise when URLs are dynamically generated by client-side applications (such as applets) or embedded in scripts in the HTML code. Web scripting languages include JavaScript, VBScript, ASP, JSP, ActiveX, and others. These applets and scripts execute when the page arrives at the client browser. WebSEAL never has an opportunity to apply its standard filtering rules to these URLs that are dynamically generated on the client-side.Three options for modifying URLs in requests are available to WebSEAL and are applied in the following order of precedence:Junction mapping tableJunction cookiesHTTP Referer headerThis section describes the options for processing server-relative links (used to make requests for resources located on junctioned back-end application servers) that are dynamically generated on the client-side.There are no solutions available for handling absolute URLs generated on the client-side.Topic index:Modification of URLs to junctioned resourcesURL modification conceptsPath types used in URLsSpecial characters in URLsHTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.Modification of URLs in responsesHandling cookies from servers across multiple -j junctionsModification of server-relative URLs with junction mappingModification of server-relative URLs with junction cookiesControl on the junction cookie JavaScript blockModification of server-relative URLs using the HTTP Referer headerControlling server-relative URL processing in requests

Modification of URLs in requests

Difficulties arise when URLs are dynamically generated by client-side applications (such as applets) or embedded in scripts in the HTML code. Web scripting languages include JavaScript, VBScript, ASP, JSP, ActiveX, and others. These applets and scripts execute when the page arrives at the client browser. WebSEAL never has an opportunity to apply its standard filtering rules to these URLs that are dynamically generated on the client-side.

Three options for modifying URLs in requests are available to WebSEAL and are applied in the following order of precedence:

Junction mapping table

Junction cookies

HTTP Referer header

This section describes the options for processing server-relative links (used to make requests for resources located on junctioned back-end application servers) that are dynamically generated on the client-side.

Note: There are no solutions available for handling absolute URLs generated on the client-side.

Topic index:

Modification of server-relative URLs with junction mapping

Modification of server-relative URLs with junction cookies

Control on the junction cookie JavaScript block

Modification of server-relative URLs using the HTTP Referer header

Controlling server-relative URL processing in requests

Parent topic: Modification of URLs to junctioned resources

Related concepts:

URL modification concepts

Modification of URLs in responses

Related tasks:

Handling cookies from servers across multiple -j junctions

Related reference:

Path types used in URLs

Special characters in URLs

Modification of server-relative URLs with junction mapping Modification of server-relative URLs with junction mapping jmt-mapjmt.confjunction mappingmodifying URLstableURLmodificationserver-relativejunction mappingfiltermodifying URLsserver-relativejunction mappingpdadmin server taskjmt loadServer-relative URLs generated on the client-side by applets and scripts initially lack knowledge of the junction point. WebSEAL cannot filter the URL because it is generated on the client-side. During a client request for a resource using this URL, WebSEAL can attempt to reprocess the server-relative URL using a junction mapping table. A junction mapping table maps specific target resources to junction names. Junction mapping is an alternative to the cookie-based solution for filtering dynamically generated server-relative URLs. WebSEAL checks the location information in the server-relative URL with the data contained in the junction mapping table. WebSEAL begins searching from the top of the table and continues downward through the table. If the path information in the URL matches any entry in the table during the top-down search, WebSEAL directs the request to the junction associated with that location. The table is an ASCII text file called jmt.conf. The name of this file is specified in the [junction] stanza of the WebSEAL configuration file: jmt-map = jmt.confThe format for data entry in the table consists of the junction name, a space, and the resource location pattern. You can also use wildcard characters to express the resource location pattern. In the following example of the junction mapping configuration file, two back-end servers are junctioned to WebSEAL at /jctA and /jctB: #jmt.conf #junction-name resource-location-pattern /jctA /documents/release-notes.html /jctA /travel/index.html /jctB /accounts/* /jctB /images/weather/*.jpgYou must create the jmt.conf mapping table. This file does not exist by default. After you create the file and add data, use the jmt load command to load the data so that WebSEAL has knowledge of the new information. pdadmin> server task server-name jmt load JMT table successfully loaded.The following conditions apply to the junction mapping table solution: The junction mapping solution handles inbound requests intercepted by WebSEAL. Requests made using unfiltered absolute URLs that point to a server external to the WebSEAL environment (and therefore never intercepted by WebSEAL) are not handled by the junction mapping table solution.This solution does not require the –j option or junction cookie.The mapping table requires setup and activation by a security administrator.Resource location pattern matching must be unique across the local Web space and across junctioned Web application servers.If there is a duplicate pattern entry in the file, the mapping table does not load. However, WebSEAL continues to run.If there is an error loading the mapping table, the mapping table is not available. However, WebSEAL continues to run.If the mapping table is empty or there is an error in the table entries, the mapping table does not load. However, WebSEAL continues to run.Any errors that occur while loading the mapping table result in serviceability entries in the WebSEAL server log file (webseald.log).By default, WebSEAL modifies the names of non-domain cookies (returned in responses from back-end applications) across junctions listed in the junction mapping table. WebSEAL creates unique cookie names to prevent possible naming conflicts with cookies returned across other junctions. There are two methods for disabling this feature: See Handling cookies from servers across multiple -j junctions.See also Controlling server-relative URL processing in requests.Modification of URLs in requests

Modification of server-relative URLs with junction mapping

Server-relative URLs generated on the client-side by applets and scripts initially lack knowledge of the junction point. WebSEAL cannot filter the URL because it is generated on the client-side.

During a client request for a resource using this URL, WebSEAL can attempt to reprocess the server-relative URL using a junction mapping table. A junction mapping table maps specific target resources to junction names. Junction mapping is an alternative to the cookie-based solution for filtering dynamically generated server-relative URLs.

WebSEAL checks the location information in the server-relative URL with the data contained in the junction mapping table. WebSEAL begins searching from the top of the table and continues downward through the table. If the path information in the URL matches any entry in the table during the top-down search, WebSEAL directs the request to the junction associated with that location.

The table is an ASCII text file called jmt.conf. The name of this file is specified in the [junction] stanza of the WebSEAL configuration file:

jmt-map = jmt.conf

The format for data entry in the table consists of the junction name, a space, and the resource location pattern. You can also use wildcard characters to express the resource location pattern.

In the following example of the junction mapping configuration file, two back-end servers are junctioned to WebSEAL at /jctA and /jctB:

#jmt.conf
#junction-name resource-location-pattern
/jctA /documents/release-notes.html
/jctA /travel/index.html
/jctB /accounts/*
/jctB /images/weather/*.jpg

You must create the jmt.conf mapping table. This file does not exist by default. After you create the file and add data, use the jmt load command to load the data so that WebSEAL has knowledge of the new information.

pdadmin> server task server-name jmt load
JMT table successfully loaded.

The following conditions apply to the junction mapping table solution:

The junction mapping solution handles inbound requests intercepted by WebSEAL. Requests made using unfiltered absolute URLs that point to a server external to the WebSEAL environment (and therefore never intercepted by WebSEAL) are not handled by the junction mapping table solution.

This solution does not require the –j option or junction cookie.

The mapping table requires setup and activation by a security administrator.

Resource location pattern matching must be unique across the local Web space and across junctioned Web application servers.

If there is a duplicate pattern entry in the file, the mapping table does not load. However, WebSEAL continues to run.

If there is an error loading the mapping table, the mapping table is not available. However, WebSEAL continues to run.

If the mapping table is empty or there is an error in the table entries, the mapping table does not load. However, WebSEAL continues to run.

Any errors that occur while loading the mapping table result in serviceability entries in the WebSEAL server log file (webseald.log).

By default, WebSEAL modifies the names of non-domain cookies (returned in responses from back-end applications) across junctions listed in the junction mapping table. WebSEAL creates unique cookie names to prevent possible naming conflicts with cookies returned across other junctions. There are two methods for disabling this feature:

See Handling cookies from servers across multiple -j junctions.

See also Controlling server-relative URL processing in requests.

Parent topic: Modification of URLs in requests

Modification of server-relative URLs with junction cookiesModification of server-relative URLs with junction cookiesjunction cookiesmodifying URLscookiesIV_JCT (junction cookie header)modifyingURLsURLmodificationserver-relativejunction cookiesfiltermodifying URLsserver-relativejunction cookiesThis section contains the following topics:Modification of URLs in requestsJunction cookie conceptsConfiguration of WebSEAL junctions to support junction cookies

Modification of server-relative URLs with junction cookies

This section contains the following topics:

Junction cookie concepts

Configuration of WebSEAL junctions to support junction cookies

Parent topic: Modification of URLs in requests

Junction cookie conceptsJunction cookie conceptsjunctionscookie conceptscookiesjunction cookie conceptsIV_JCT (junction cookie header)HTML pages from back-end junctioned application servers can contain embedded applets or scripts that dynamically generate server-relative links on the client-side. WebSEAL cannot filter these URLs because they are dynamically generated on the client-side. Therefore, these server-relative URLs are expressed without knowledge of the junction point where the application server resides. This section describes a cookie-based solution to modifying server-relative URLs dynamically generated on the client-side. When a client receives a page from a junctioned server, and requests a resource using a dynamically generated server-relative URL on this page, WebSEAL can attempt to reprocess the URL using a special cookie. The cookie contains the appropriate junction information.This solution requires that you initially create the junction to the back-end application server using the -j option. The following sequence of steps explains the process flow:Client makes a request for an HTML page from a back-end junctioned application server. In addition to other content, the page contains an embedded applet that generates a server-relative URL once the page is loaded on the client's browser.The page is returned to the client across the junction that was created with the -j option. The -j option causes WebSEAL to prepend a JavaScript block at the beginning of the HTML page. The purpose of the JavaScript is to set a junction-identifying cookie on the browser.When the page is loaded on the client's browser, the JavaScript runs and sets the junction-identifying cookie in the browser's cookie cache. The cookie is a session cookie containing the name of the junction.The embedded applet on the page dynamically runs and generates the server-relative URL.The client makes a request for a resource using this server-relative URL. The junction cookie information is sent as an HTTP header in this request: IV_JCT = /junction-nameBecause the server-relative URL in the client request has not been filtered, it appears to WebSEAL as a request for a local resource.When it fails to locate the resource locally, WebSEAL immediately retries the request using the junction information supplied by the cookie.With the correct junction information in the URL expression, the resource is successfully located on the back-end application server.The following diagram illustrates the junction cookie solution for filtering server-relative URLs Processing server-relative URLs with junction cookiesProcessing server-relative URLs with junction cookiesModification of server-relative URLs with junction cookies

Junction cookie concepts

HTML pages from back-end junctioned application servers can contain embedded applets or scripts that dynamically generate server-relative links on the client-side. WebSEAL cannot filter these URLs because they are dynamically generated on the client-side. Therefore, these server-relative URLs are expressed without knowledge of the junction point where the application server resides.

This section describes a cookie-based solution to modifying server-relative URLs dynamically generated on the client-side. When a client receives a page from a junctioned server, and requests a resource using a dynamically generated server-relative URL on this page, WebSEAL can attempt to reprocess the URL using a special cookie. The cookie contains the appropriate junction information.

This solution requires that you initially create the junction to the back-end application server using the -j option. The following sequence of steps explains the process flow:

Client makes a request for an HTML page from a back-end junctioned application server.

In addition to other content, the page contains an embedded applet that generates a server-relative URL once the page is loaded on the client's browser.

The page is returned to the client across the junction that was created with the -j option.

The -j option causes WebSEAL to prepend a JavaScript block at the beginning of the HTML page.

The purpose of the JavaScript is to set a junction-identifying cookie on the browser.

When the page is loaded on the client's browser, the JavaScript runs and sets the junction-identifying cookie in the browser's cookie cache.

The cookie is a session cookie containing the name of the junction.

The embedded applet on the page dynamically runs and generates the server-relative URL.

The client makes a request for a resource using this server-relative URL. The junction cookie information is sent as an HTTP header in this request:

IV_JCT = /junction-name

Because the server-relative URL in the client request has not been filtered, it appears to WebSEAL as a request for a local resource.

When it fails to locate the resource locally, WebSEAL immediately retries the request using the junction information supplied by the cookie.

With the correct junction information in the URL expression, the resource is successfully located on the back-end application server.

The following diagram illustrates the junction cookie solution for filtering server-relative URLs

Figure 37. Processing server-relative URLs with junction cookies

Parent topic: Modification of server-relative URLs with junction cookies

Configuration of WebSEAL junctions to support junction cookiesConfiguration of WebSEAL junctions to support junction cookiesWebSEALjunction cookies supportjunction cookiessupport configurationUse the following general syntax to create a junction that supports junction cookies: pdadmin> server task instance-webseald-host create ... -j ...The following additional references contain related information:Control on the junction cookie JavaScript block.Controlling server-relative URL processing in requests.Handling cookies from servers across multiple -j junctions.WebSEAL provides an alternative, non-cookie-based solution for handling dynamically generated server-relative URLs. See Modification of server-relative URLs with junction mapping.See also: Modification of server-relative URLs using the HTTP Referer headerModification of server-relative URLs with junction cookies

Configuration of WebSEAL junctions to support junction cookies

Use the following general syntax to create a junction that supports junction cookies:

pdadmin> server task instance-webseald-host create ... -j ...

The following additional references contain related information:

Control on the junction cookie JavaScript block.

Controlling server-relative URL processing in requests.

Handling cookies from servers across multiple -j junctions.

WebSEAL provides an alternative, non-cookie-based solution for handling dynamically generated server-relative URLs. See Modification of server-relative URLs with junction mapping.

See also: Modification of server-relative URLs using the HTTP Referer header

Parent topic: Modification of server-relative URLs with junction cookies

Control on the junction cookie JavaScript blockControl on the junction cookie JavaScript blockIV_JCT (junction cookie header)controlling junction cookie JavaScript (-J)junction cookiescontrolling junction cookie JavaScript (-J)junctionscontrolling junction cookie JavaScript (-J)cookiescontrolling junction cookie JavaScript (-J)This section describes two additional configuration options that are available when you use the -j junction option to modify server-relative URLs (see Modification of server-relative URLs with junction cookies):Modification of URLs in requestsAppending the junction cookie JavaScript block (trailer)Inserting the JavaScript block for HTML 4.01 compliance (inhead)The -J junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before any HTML code. Resetting the junction cookie for multiple -j junctions (onfocus)Inserting an XHTML 1.0 compliant JavaScript block (xhtml10)The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. The default script is not compliant with XHTML 1.0 specifications.

Control on the junction cookie JavaScript block

This section describes two additional configuration options that are available when you use the -j junction option to modify server-relative URLs (see Modification of server-relative URLs with junction cookies):

Appending the junction cookie JavaScript block (trailer)

Inserting the JavaScript block for HTML 4.01 compliance (inhead)
The -J junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before any HTML code.

Resetting the junction cookie for multiple -j junctions (onfocus)

Inserting an XHTML 1.0 compliant JavaScript block (xhtml10)
The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. The default script is not compliant with XHTML 1.0 specifications.

Parent topic: Modification of URLs in requests

Appending the junction cookie JavaScript block (trailer)Appending the junction cookie JavaScript block (trailer)junction cookiesappending junction cookie JavaScript (-J trailer)junctionsappending junction cookie JavaScript (-J trailer)cookiesappending junction cookie JavaScript (-J trailer)IV_JCT (junction cookie header)appending junction cookie JavaScript (-J trailer)trailer (appending junction cookie JavaScript) The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before the <html> tag. This prepended location of the JavaScript on the page can cause HTML rendering problems in some environments. If this type of problem is encountered, you can configure WebSEAL to append the JavaScript block to the end of the document instead. To configure WebSEAL to append the junction cookie JavaScript block to the end of pages returned by the back-end server, add the -J option with the trailer argument when creating the -j junction. For example (command line fragment):pdadmin> server task instance-webseald-host create ... -j -J trailer ... If you are concerned with inserting the JavaScript block in the correct location for HTML 4.01 compliance, see Inserting the JavaScript block for HTML 4.01 compliance (inhead)The -J junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before any HTML code. .Control on the junction cookie JavaScript block

Appending the junction cookie JavaScript block (trailer)

About this task

The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before the <html> tag.

This prepended location of the JavaScript on the page can cause HTML rendering problems in some environments. If this type of problem is encountered, you can configure WebSEAL to append the JavaScript block to the end of the document instead.

Procedure

To configure WebSEAL to append the junction cookie JavaScript block to the end of pages returned by the back-end server, add the -J option with the trailer argument when creating the -j junction. For example (command line fragment):

pdadmin> server task instance-webseald-host create ... -j -J trailer ...

If you are concerned with inserting the JavaScript block in the correct location for HTML 4.01 compliance, see Inserting the JavaScript block for HTML 4.01 compliance (inhead).

Parent topic: Control on the junction cookie JavaScript block

Inserting the JavaScript block for HTML 4.01 compliance (inhead)Inserting the JavaScript block for HTML 4.01 compliance (inhead)The -J junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before any HTML code. JavaScript blockblock for HTML 4.01 compliance (inhead)HTML JavaScript block This prepended location of the JavaScript on the page can cause HTML rendering problems in some environments. Additionally, the default prepended location does not comply with HTML 4.01 specifications. The HTML 4.01 specification requires <script> tags to be located within the <head> </head> tags. To configure WebSEAL to insert the junction cookie JavaScript block between<head> </head> tags (HTML 4.01 compliant), add the -J option with the inhead argument when creating the -J junction. For example (command line fragment):pdadmin> server task instance-webseald-host create ... -j -J inhead ... The xhtml10 argument also addresses compliance with other HTML 4.01 and XHTML 1.0 specifications. See Inserting an XHTML 1.0 compliant JavaScript block (xhtml10)The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. The default script is not compliant with XHTML 1.0 specifications..The trailer argument can be used when compliance with HTML 4.01 specifications is not required. See Appending the junction cookie JavaScript block (trailer).Control on the junction cookie JavaScript block

Inserting the JavaScript block for HTML 4.01 compliance (inhead)

The -J junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before any HTML code.

About this task

This prepended location of the JavaScript on the page can cause HTML rendering problems in some environments. Additionally, the default prepended location does not comply with HTML 4.01 specifications. The HTML 4.01 specification requires <script> tags to be located within the <head> </head> tags.

Procedure

To configure WebSEAL to insert the junction cookie JavaScript block between<head> </head> tags (HTML 4.01 compliant), add the -J option with the inhead argument when creating the -J junction. For example (command line fragment):

pdadmin> server task instance-webseald-host create ... -j -J inhead ...

The xhtml10 argument also addresses compliance with other HTML 4.01 and XHTML 1.0 specifications. See Inserting an XHTML 1.0 compliant JavaScript block (xhtml10).

The trailer argument can be used when compliance with HTML 4.01 specifications is not required. See Appending the junction cookie JavaScript block (trailer).

Parent topic: Control on the junction cookie JavaScript block

Resetting the junction cookie for multiple -j junctions (onfocus)Resetting the junction cookie for multiple -j junctions (onfocus)junction cookiesjunction cookie reset (-J onfocus)junctionsjunction cookie reset (-J onfocus)cookiesjunction cookie reset (-J onfocus)IV_JCT (junction cookie header)junction cookie reset (-J onfocus)onfocus (junction cookie reset) In environments where multiple instances of a single client access multiple -j junctions simultaneously, the most recent IV_JCT cookie created by the JavaScript may erroneously refer to a different junction than the one being currently accessed. In such a situation, WebSEAL receives the wrong junction information and fails to correctly resolve links. For example, consider a scenario where a user has two browser windows open, each pointing to one of two junctions, jctA and jctB. Both junctions were created with the -j junction option.In the first browser window, the user requests a page from an application server located on jctA.The IV_JCT cookie for jctA is set in the browser.The user then leaves the first browser window open, switches to the other browser window, and requests a page from an application server located on jctB. The IV_JCT cookie for jctB is set in the browser (replacing jctA).If the user then returns to the first browser window and clicks a link to a resource located on jctA, the wrong IV_JCT cookie is sent to WebSEAL. To eliminate this problem, you can configure WebSEAL to use the onfocus event handler in the JavaScript. The onfocus handler resets the IV_JCT cookie whenever users switch the browser focus from one window to another. To use the JavaScript onfocus event handler, add the -J option with the onfocus argument when creating the -j junction. For example (command line fragment): pdadmin> server task instance-webseald-host create ... -j -J onfocus ... If you create a junction using the onfocus argument, it is best practise to use the trailer argument as well. The trailer argument ensures that the JavaScript inserted by WebSEAL does not interfere with the rendering of HTML frame sets. Use a comma character (,) and no spaces between the two arguments. For example (command line fragment): pdadmin> server task instance-webseald-host create ... -j -J trailer,onfocus ... See also Appending the junction cookie JavaScript block (trailer). If compliance with HTML 4.01 and XHTML 1.0 specifications is required, see Inserting an XHTML 1.0 compliant JavaScript block (xhtml10)The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. The default script is not compliant with XHTML 1.0 specifications.. No error message is provided if the arguments specified for the -J option are invalid. If the -J junction option does not perform as expected, make sure you are providing the correct argument.Control on the junction cookie JavaScript block

Resetting the junction cookie for multiple -j junctions (onfocus)

About this task

In environments where multiple instances of a single client access multiple -j junctions simultaneously, the most recent IV_JCT cookie created by the JavaScript may erroneously refer to a different junction than the one being currently accessed. In such a situation, WebSEAL receives the wrong junction information and fails to correctly resolve links.

For example, consider a scenario where a user has two browser windows open, each pointing to one of two junctions, jctA and jctB. Both junctions were created with the -j junction option.

Procedure

In the first browser window, the user requests a page from an application server located on jctA.
The IV_JCT cookie for jctA is set in the browser.

The user then leaves the first browser window open, switches to the other browser window, and requests a page from an application server located on jctB.
The IV_JCT cookie for jctB is set in the browser (replacing jctA).

If the user then returns to the first browser window and clicks a link to a resource located on jctA, the wrong IV_JCT cookie is sent to WebSEAL.

Results

To eliminate this problem, you can configure WebSEAL to use the onfocus event handler in the JavaScript. The onfocus handler resets the IV_JCT cookie whenever users switch the browser focus from one window to another.

To use the JavaScript onfocus event handler, add the -J option with the onfocus argument when creating the -j junction. For example (command line fragment):

pdadmin> server task instance-webseald-host create ... -j -J onfocus ...

If you create a junction using the onfocus argument, it is best practise to use the trailer argument as well. The trailer argument ensures that the JavaScript inserted by WebSEAL does not interfere with the rendering of HTML frame sets. Use a comma character (,) and no spaces between the two arguments. For example (command line fragment):

pdadmin> server task instance-webseald-host create ... -j -J trailer,onfocus ...

See also Appending the junction cookie JavaScript block (trailer).

If compliance with HTML 4.01 and XHTML 1.0 specifications is required, see Inserting an XHTML 1.0 compliant JavaScript block (xhtml10).

Note: No error message is provided if the arguments specified for the -J option are invalid. If the -J junction option does not perform as expected, make sure you are providing the correct argument.

Parent topic: Control on the junction cookie JavaScript block

Inserting an XHTML 1.0 compliant JavaScript block (xhtml10)Inserting an XHTML 1.0 compliant JavaScript block (xhtml10)The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. The default script is not compliant with XHTML 1.0 specifications.XHTML 1.0 compliant JavaScript block (xhtml10)To configure WebSEAL to insert a junction cookie JavaScript block that is compliant with XHTML 1.0 specifications (and HTML 4.01 specifications), add the -J option with the xhtml10 argument when creating the -j junction. For example (command line fragment):pdadmin> server task instance-webseald-host create ... -j -J xhtml10 ... The JavaScript inserted using this option may not execute if the Content-Type of the document it is inserted into is not text/html. This will typically not be a problem because most sites issue XHTML with Content-Type: text/html.The onfocus and xhtml10 arguments for the -J option are mutually exclusive. WebSEAL silently ignores xhtml10 if onfocus has also been specified.If you create a junction using the xhtml10 argument, it is best practise to use the inhead argument as well. The inhead argument ensures that the placement of the JavaScript within the HTML code is compliant with HTML 4.01 specifications. For example (command line fragment):pdadmin> server task instance-webseald-host create ... -j -J inhead,xhtml10 ... See also Inserting the JavaScript block for HTML 4.01 compliance (inhead)The -J junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. By default, the JavaScript block is inserted at the beginning of the page, before any HTML code. .Control on the junction cookie JavaScript block

Inserting an XHTML 1.0 compliant JavaScript block (xhtml10)

The -j junction option modifies HTML documents returned from junctioned servers by inserting a JavaScript block that sets a junction identification cookie on the browser interpreting the document. The default script is not compliant with XHTML 1.0 specifications.

Procedure

To configure WebSEAL to insert a junction cookie JavaScript block that is compliant with XHTML 1.0 specifications (and HTML 4.01 specifications), add the -J option with the xhtml10 argument when creating the -j junction. For example (command line fragment):

pdadmin> server task instance-webseald-host create ... -j -J xhtml10 ...

Note:

The JavaScript inserted using this option may not execute if the Content-Type of the document it is inserted into is not text/html. This will typically not be a problem because most sites issue XHTML with Content-Type: text/html.

The onfocus and xhtml10 arguments for the -J option are mutually exclusive. WebSEAL silently ignores xhtml10 if onfocus has also been specified.

If you create a junction using the xhtml10 argument, it is best practise to use the inhead argument as well. The inhead argument ensures that the placement of the JavaScript within the HTML code is compliant with HTML 4.01 specifications. For example (command line fragment):

pdadmin> server task instance-webseald-host create ... -j -J inhead,xhtml10 ...

See also Inserting the JavaScript block for HTML 4.01 compliance (inhead).

Parent topic: Control on the junction cookie JavaScript block

Modification of server-relative URLs using the HTTP Referer headerModification of server-relative URLs using the HTTP Referer headerURLmodificationserver-relativeReferer headerfiltermodifying URLsserver-relativeReferer headerReferer HTTP headersHTTP headersReferer headermodifying server-relative URLsHTML pages from back-end junctioned application servers can contain embedded applets or scripts that dynamically generate server-relative links on the client-side. WebSEAL cannot filter these URLs because they are dynamically generated on the client-side. Therefore, these server-relative URLs are expressed without knowledge of the junction point where the application server resides. This section describes a solution for modifying server-relative URLs dynamically generated on the client-side. This solution involves use of the standard Referer header in an HTTP request. WebSEAL uses this solution only if a junction cookie cannot be found in a request or a junction mapping table entry does not match the request.The information in the Referer header of an HTTP request can be used to identify the junction point of the application server responsible for the embedded applet or script. This solution assumes that the dynamically generated links point to resources located on the same application server (and therefore would require the same junction used by that application server)A page returned from the back-end application server (and containing the links generated by the embedded applet or script) would provide knowledge of the junction name. The junction name will appear in the URL value of the Referer header of a request that results when the user clicks on one of the client-side-generated links located on this page. For example:GET /back_end_app/images/logo.jpg Referer: http://webseal/jctA/back_end_app ...WebSEAL would not be able to find the resource using the request URL above (/back_end_app/images/logo.jpg). By using the information in the Referer header of that request, WebSEAL can modify the request URL to additionally include the junction name jctA. For example:GET /jctA/back_end_app/images/logo.jpgUsing the modified URL, WebSEAL can successfully locate the resource. This of course assumes the resource (logo.jpg) is located on the same server.If the environment results in client-side-generated links that point to resources across multiple junctions, the Referer header method for modifying URLs will not be reliable. In these environments, you must use either the junction mapping table solution or the junction cookie solution.See also:Modification of server-relative URLs with junction mappingModification of server-relative URLs with junction cookiesModification of URLs in requests

Modification of server-relative URLs using the HTTP Referer header

HTML pages from back-end junctioned application servers can contain embedded applets or scripts that dynamically generate server-relative links on the client-side. WebSEAL cannot filter these URLs because they are dynamically generated on the client-side. Therefore, these server-relative URLs are expressed without knowledge of the junction point where the application server resides.

This section describes a solution for modifying server-relative URLs dynamically generated on the client-side. This solution involves use of the standard Referer header in an HTTP request. WebSEAL uses this solution only if a junction cookie cannot be found in a request or a junction mapping table entry does not match the request.

The information in the Referer header of an HTTP request can be used to identify the junction point of the application server responsible for the embedded applet or script. This solution assumes that the dynamically generated links point to resources located on the same application server (and therefore would require the same junction used by that application server)

A page returned from the back-end application server (and containing the links generated by the embedded applet or script) would provide knowledge of the junction name. The junction name will appear in the URL value of the Referer header of a request that results when the user clicks on one of the client-side-generated links located on this page. For example:

GET /back_end_app/images/logo.jpg
Referer: http://webseal/jctA/back_end_app
...

WebSEAL would not be able to find the resource using the request URL above (/back_end_app/images/logo.jpg). By using the information in the Referer header of that request, WebSEAL can modify the request URL to additionally include the junction name jctA. For example:

GET /jctA/back_end_app/images/logo.jpg

Using the modified URL, WebSEAL can successfully locate the resource. This of course assumes the resource (logo.jpg) is located on the same server.

If the environment results in client-side-generated links that point to resources across multiple junctions, the Referer header method for modifying URLs will not be reliable. In these environments, you must use either the junction mapping table solution or the junction cookie solution.

See also:

Modification of server-relative URLs with junction mapping

Modification of server-relative URLs with junction cookies

Parent topic: Modification of URLs in requests

Controlling server-relative URL processing in requests Controlling server-relative URL processing in requests URLcontrolling server-relative URL processing in requestsprocess-root-requests stanza entryfiltercontrolling server-relative URL processing in requestsprocess-root-requests stanza entryjunctionscontrolling server-relative URL processing in requestsprocess-root-requests stanza entryprocess-root-requests stanza entryThis section contains the following topics: Modification of URLs in requestsProcess root request conceptsThis section discusses the process followed by WebSEAL when handling server-relative URLs in requests.Configuring root request processing

Controlling server-relative URL processing in requests

About this task

This section contains the following topics:

Process root request concepts
This section discusses the process followed by WebSEAL when handling server-relative URLs in requests.

Configuring root request processing

Parent topic: Modification of URLs in requests

Process root request conceptsProcess root request conceptsThis section discusses the process followed by WebSEAL when handling server-relative URLs in requests.root requestsprocess flowroot request conceptsThe process-root-requests stanza entry allows you to control the order in which WebSEAL processes a request involving a server-relative URL. For example, you can instruct WebSEAL to look for the requested resource at the WebSEAL root junction first. If the resource is "Not Found", WebSEAL continues processing the request by using any configured post-processing mechanism (such as junction cookie, junction mapping table (JMT), or Referer header).Alternatively, you can have WebSEAL initially processes a server-relative URL request using any configured post-processing mechanism (such as junction cookie, junction mapping table (JMT), or Referer header). If the resource is "Not Found" by this method, WebSEAL then searches the root junction for the resource. A third configuration allows you to filter specific path patterns.For any request involving a server-relative URL, WebSEAL searches for the resource according to the configured setting of the process-root-requests stanza entry. If a "Not Found" error is returned, WebSEAL continues to process the request according to the process-root-requests configuration.If any other error is returned, such as "Server Error" (500), WebSEAL returns the error to the client, assumes the resource is found, and stops further processing of the request. WebSEAL does not attempt to process the request on another junction. WebSEAL is functioning as intended in this situation.The purpose of the process-root-requests configuration is to prevent server-relative URL processing from being performed for incorrect resources before the intended resource is identified. This action has performance benefits and prevents false authorization or file type check failures.Controlling server-relative URL processing in requests

Process root request concepts

This section discusses the process followed by WebSEAL when handling server-relative URLs in requests.

The process-root-requests stanza entry allows you to control the order in which WebSEAL processes a request involving a server-relative URL. For example, you can instruct WebSEAL to look for the requested resource at the WebSEAL root junction first. If the resource is "Not Found", WebSEAL continues processing the request by using any configured post-processing mechanism (such as junction cookie, junction mapping table (JMT), or Referer header).

Alternatively, you can have WebSEAL initially processes a server-relative URL request using any configured post-processing mechanism (such as junction cookie, junction mapping table (JMT), or Referer header). If the resource is "Not Found" by this method, WebSEAL then searches the root junction for the resource.

A third configuration allows you to filter specific path patterns.

For any request involving a server-relative URL, WebSEAL searches for the resource according to the configured setting of the process-root-requests stanza entry. If a "Not Found" error is returned, WebSEAL continues to process the request according to the process-root-requests configuration.

If any other error is returned, such as "Server Error" (500), WebSEAL returns the error to the client, assumes the resource is found, and stops further processing of the request. WebSEAL does not attempt to process the request on another junction. WebSEAL is functioning as intended in this situation.

The purpose of the process-root-requests configuration is to prevent server-relative URL processing from being performed for incorrect resources before the intended resource is identified. This action has performance benefits and prevents false authorization or file type check failures.

Parent topic: Controlling server-relative URL processing in requests

Configuring root request processingConfiguring root request processingroot requestsprocessingroot requestsprocess-root-filter stanza Use the process-root-requests entry in the [server] stanza of the WebSEAL configuration stanza to configure root junction processing. For information on junction mapping mechanisms, see the following sections: Modification of server-relative URLs with junction cookiesModification of server-relative URLs with junction mappingSet the process-root-requests entry in the [server] stanza of the WebSEAL configuration stanza to one of the values provided. The default value is "always":[server] process-root-requests = alwaysValid values are:never WebSEAL initially processes a server-relative URL request using any configured post-processing mechanism. Mechanisms are tried in the following order: 1) junction mapping table (JMT), 2) junction cookie, 3) HTTP Referer header. If the resource is not found by this method, WebSEAL then searches the root junction for the resource. always WebSEAL attempts to process server-relative URL requests at the root junction first before attempting to use any configured post-processing mechanism (such as junction cookie, junction mapping table (JMT), or Referer header). This setting should not be used unless the root junction serves a large set of resources or no post-processing junction mapping mechanisms are configured for the set of junctions served by this WebSEAL server.filter All root junction requests are examined to determine whether they start with the path patterns specified in the [process-root-filter] stanza. If they do, they are processed at the root junction first. If they do not start with path patterns specified in the [process-root-filter] stanza, they are remapped immediately.When process-root-requests = filter, you must specify the patterns for which you want root junction requests processed at the root junction. Use the [process-root-filter] stanza. The syntax for specifying a pattern is:root = path_patternPath pattern must be expressed as a standard WebSEAL wildcard pattern. For example:[process-root-filter] root = /index.html root = /cgi-bin*Controlling server-relative URL processing in requests

Configuring root request processing

About this task

Use the process-root-requests entry in the [server] stanza of the WebSEAL configuration stanza to configure root junction processing.

For information on junction mapping mechanisms, see the following sections:

Modification of server-relative URLs with junction cookies

Modification of server-relative URLs with junction mapping

Procedure

Set the process-root-requests entry in the [server] stanza of the WebSEAL configuration stanza to one of the values provided. The default value is "always":

[server]
process-root-requests = always

Valid values are:

never

WebSEAL initially processes a server-relative URL request using any configured post-processing mechanism. Mechanisms are tried in the following order: 1) junction mapping table (JMT), 2) junction cookie, 3) HTTP Referer header. If the resource is not found by this method, WebSEAL then searches the root junction for the resource.

always

WebSEAL attempts to process server-relative URL requests at the root junction first before attempting to use any configured post-processing mechanism (such as junction cookie, junction mapping table (JMT), or Referer header). This setting should not be used unless the root junction serves a large set of resources or no post-processing junction mapping mechanisms are configured for the set of junctions served by this WebSEAL server.

filter

All root junction requests are examined to determine whether they start with the path patterns specified in the [process-root-filter] stanza. If they do, they are processed at the root junction first. If they do not start with path patterns specified in the [process-root-filter] stanza, they are remapped immediately.

When process-root-requests = filter, you must specify the patterns for which you want root junction requests processed at the root junction. Use the [process-root-filter] stanza. The syntax for specifying a pattern is:

root = path_pattern

Path pattern must be expressed as a standard WebSEAL wildcard pattern. For example:

[process-root-filter]
root = /index.html
root = /cgi-bin*

Parent topic: Controlling server-relative URL processing in requests

Handling cookies from servers across multiple -j junctionsHandling cookies from servers across multiple -j junctionsURLhandling cookies across multiple -j junctionsfiltercookies across multiple -j junctionsjunctionshandling cookies across multipe -j junctions This section describes how WebSEAL handles cookies generated by back-end applications and returned to clients across multiple -j junctions. Modification of URLs to junctioned resourcesURL modification conceptsPath types used in URLsSpecial characters in URLsHTML pages can contain ASCII special characters. The web content contains HTML codes that represent the special characters or symbols.Modification of URLs in responsesModification of URLs in requestsCookie handling: -j modifies Set-Cookie path attributeCookie handling: -j modifies Set-Cookie name attributePreservation of cookie namesCookie handling: -I ensures unique Set-Cookie name attribute

Handling cookies from servers across multiple -j junctions

About this task

This section describes how WebSEAL handles cookies generated by back-end applications and returned to clients across multiple -j junctions.

Cookie handling: -j modifies Set-Cookie path attribute

Cookie handling: -j modifies Set-Cookie name attribute

Preservation of cookie names

Cookie handling: -I ensures unique Set-Cookie name attribute

Parent topic: Modification of URLs to junctioned resources

Related concepts:

URL modification concepts

Modification of URLs in responses

Modification of URLs in requests

Related reference:

Path types used in URLs

Special characters in URLs

Cookie handling: -j modifies Set-Cookie path attributeCookie handling: -j modifies Set-Cookie path attributecookiesmodifying cookie path in -j and mapping table junctionsjunctionsmodifying cookie path in -j and mapping table junctionsIn addition to providing a junction identifier cookie to the browser, junctions configured with the –j option, or listed in a junction mapping table, also support the handling of non-domain cookies sent with responses from the back-end application. Cookie handling by the browser:If a Set-Cookie header in a response from the server contains a path attribute (such as path=/xyz), the browser returns the cookie only when a request URL (activated from the returned page) begins with this path (such as /xyz/memo.html). Problem:When the junction environment contains mixed solutions for handling visible and embedded URLs in responses, the ability of the browser to return cookies can be compromised. For example, standard WebSEAL filtering of visible server-relative URLs normally adds the junction name to the value of the path attribute of a server cookie (for example, path=/jct/xyz), in addition to modifying the URL itself. This match between URL path name and the cookie path value allows the browser to return the cookie when the link is activated by the user.However, the -j junction-cookie-based solution adds the junction name to a URL only after the link (URL) has been activated by the user. When the link is activated, the pre-modified URL path name (/xyz/memo.html) does not match the Set-Cookie path attribute value (path=/jct/xyz). The server cookie is not returned with the request.Solution:The -j option converts the value of the path attribute for any server cookie to "/" (for example, path=/). Because all server-relative path names begin with a "/", all server cookies are returned regardless of the requirements of the original path attribute specifications. Handling cookies from servers across multiple -j junctions

Cookie handling: -j modifies Set-Cookie path attribute

In addition to providing a junction identifier cookie to the browser, junctions configured with the –j option, or listed in a junction mapping table, also support the handling of non-domain cookies sent with responses from the back-end application.

Cookie handling by the browser:

If a Set-Cookie header in a response from the server contains a path attribute (such as path=/xyz), the browser returns the cookie only when a request URL (activated from the returned page) begins with this path (such as /xyz/memo.html).

Problem:

When the junction environment contains mixed solutions for handling visible and embedded URLs in responses, the ability of the browser to return cookies can be compromised. For example, standard WebSEAL filtering of visible server-relative URLs normally adds the junction name to the value of the path attribute of a server cookie (for example, path=/jct/xyz), in addition to modifying the URL itself. This match between URL path name and the cookie path value allows the browser to return the cookie when the link is activated by the user.

However, the -j junction-cookie-based solution adds the junction name to a URL only after the link (URL) has been activated by the user. When the link is activated, the pre-modified URL path name (/xyz/memo.html) does not match the Set-Cookie path attribute value (path=/jct/xyz). The server cookie is not returned with the request.

Solution:

The -j option converts the value of the path attribute for any server cookie to "/" (for example, path=/). Because all server-relative path names begin with a "/", all server cookies are returned regardless of the requirements of the original path attribute specifications.

Parent topic: Handling cookies from servers across multiple -j junctions

Cookie handling: -j modifies Set-Cookie name attributeCookie handling: -j modifies Set-Cookie name attributecookiesmodifying cookie name in -j and mapping table junctionsjunctionsmodifying cookie name in -j and mapping table junctionsJunctions configured with the –j option, or listed in a junction mapping table, also provide a solution for preserving cookies returned from servers across multiple junctions.Cookie handling by the browser:Browsers always replace any stored cookie with a newly arrived cookie that contains the same Set-Cookie name attribute, unless the path or domain attributes, or both, are unique.Problem:The previous section describes how the -j junction option modifies the value of the path attribute of a Set-Cookie header. This modification allows the browser to return cookies in an environment where WebSEAL is applying different filtering rules for visible and embedded URLs contained in the response pages.In a scenario where multiple back-end servers are connected to WebSEAL across different junctions (such as in a WebSphere environment), it is possible for each server to send cookies with the same name attribute. If the junctions use the -j option, the values of the path attribute for each cookie become identical (path=/). Because the same WebSEAL server is the point of contact for the browser, the domain attribute likewise becomes identical. Although these identical cookies arrive from unique back-end applications, the browser overwrites the identically named cookies.Solution:The -j junction option provides an additional feature that uniquely renames any cookie returned with a response from a back-end application server. A special string is added to the beginning of the name attribute of a Set-Cookie header. The string contains the identifier AMWEBJCT, plus the name of the specific junction responsible for delivering the response (with cookie). The exclamation point (!) is used as a separator character in the string.AMWEBJCT!jct-name!For example, if a cookie with the name, ORDERID, arrives across a junction called /jctA, the cookie name is changed to :AMWEBJCT!jctA!ORDERIDTo disable this default cookie-renaming feature, see Preservation of cookie names.Handling cookies from servers across multiple -j junctions

Cookie handling: -j modifies Set-Cookie name attribute

Junctions configured with the –j option, or listed in a junction mapping table, also provide a solution for preserving cookies returned from servers across multiple junctions.

Cookie handling by the browser:

Browsers always replace any stored cookie with a newly arrived cookie that contains the same Set-Cookie name attribute, unless the path or domain attributes, or both, are unique.

Problem:

The previous section describes how the -j junction option modifies the value of the path attribute of a Set-Cookie header. This modification allows the browser to return cookies in an environment where WebSEAL is applying different filtering rules for visible and embedded URLs contained in the response pages.

In a scenario where multiple back-end servers are connected to WebSEAL across different junctions (such as in a WebSphere® environment), it is possible for each server to send cookies with the same name attribute.

If the junctions use the -j option, the values of the path attribute for each cookie become identical (path=/). Because the same WebSEAL server is the point of contact for the browser, the domain attribute likewise becomes identical. Although these identical cookies arrive from unique back-end applications, the browser overwrites the identically named cookies.

Solution:

The -j junction option provides an additional feature that uniquely renames any cookie returned with a response from a back-end application server. A special string is added to the beginning of the name attribute of a Set-Cookie header. The string contains the identifier AMWEBJCT, plus the name of the specific junction responsible for delivering the response (with cookie). The exclamation point (!) is used as a separator character in the string.

AMWEBJCT!jct-name!

For example, if a cookie with the name, ORDERID, arrives across a junction called /jctA, the cookie name is changed to :

AMWEBJCT!jctA!ORDERID

To disable this default cookie-renaming feature, see Preservation of cookie names.

Parent topic: Handling cookies from servers across multiple -j junctions

Preservation of cookie namesPreservation of cookie namespreserve-cookie-names stanzajunctionspreserve all cookie names (-n)preserve specified cookie namescookiespreserving cookie names across -j junctionsBy default, WebSEAL modifies the name of cookies returned in responses from back-end applications across multiple junctions created with the -j option, or listed in the junction mapping table. WebSEAL creates unique cookie names to prevent possible naming conflicts with cookies returned across other -j junctions.WebSEAL adds a special string to the beginning of the name attribute of a Set-Cookie header. The string contains the identifier AMWEBJCT, plus the name of the specific junction responsible for delivering the response (with cookie).AMWEBJCT!jct-name!For example, if a cookie with the name, ORDERID, arrives across a junction called /jctA, the cookie name is changed to:AMWEBJCT!jctA!ORDERIDHowever, if front-end browsers and applications depend on the specific cookie name generated by the application, you can disable cookie-renaming for:All cookies across any junction configured with the -n option. Specific cookies, configured in the [preserve-cookie-names] stanza of the WebSEAL configuration file, across all junctions. Handling cookies from servers across multiple -j junctionsPreserving names of all cookiesPreserving names of specified cookiesYou can list the names of specific cookies that are not to be modified when returned from back-end application servers across junctions.

Preservation of cookie names

By default, WebSEAL modifies the name of cookies returned in responses from back-end applications across multiple junctions created with the -j option, or listed in the junction mapping table. WebSEAL creates unique cookie names to prevent possible naming conflicts with cookies returned across other -j junctions.

WebSEAL adds a special string to the beginning of the name attribute of a Set-Cookie header. The string contains the identifier AMWEBJCT, plus the name of the specific junction responsible for delivering the response (with cookie).

AMWEBJCT!jct-name!

For example, if a cookie with the name, ORDERID, arrives across a junction called /jctA, the cookie name is changed to:

AMWEBJCT!jctA!ORDERID

However, if front-end browsers and applications depend on the specific cookie name generated by the application, you can disable cookie-renaming for:

All cookies across any junction configured with the -n option.

Specific cookies, configured in the [preserve-cookie-names] stanza of the WebSEAL configuration file, across all junctions.

Preserving names of all cookies

Preserving names of specified cookies
You can list the names of specific cookies that are not to be modified when returned from back-end application servers across junctions.

Parent topic: Handling cookies from servers across multiple -j junctions

Preserving names of all cookiesPreserving names of all cookiescookiespreserve all namesname preservationall cookiesYou can prevent renaming of non-domain cookies across a specific -j junction by additionally configuring that junction with the -n option. The -n option specifies that no modification of the names of non-domain cookies are to be made. For example, use this option when client-side scripts depend on the specific names of cookies. Preservation of cookie names

Preserving names of all cookies

About this task

You can prevent renaming of non-domain cookies across a specific -j junction by additionally configuring that junction with the -n option. The -n option specifies that no modification of the names of non-domain cookies are to be made. For example, use this option when client-side scripts depend on the specific names of cookies.

Parent topic: Preservation of cookie names

Preserving names of specified cookiesPreserving names of specified cookiesYou can list the names of specific cookies that are not to be modified when returned from back-end application servers across junctions. cookiespreserving specified namesname preservationspecified cookies The name stanza entry in the [preserve-cookie-names] stanza of the WebSEAL configuration file allows you to list the specific cookie names that are not to be renamed by WebSEAL. The specified cookie names are protected across any existing junction. [preserve-cookie-names] name = cookie-name1 name = cookie-name2Preservation of cookie names

Preserving names of specified cookies

You can list the names of specific cookies that are not to be modified when returned from back-end application servers across junctions.

About this task

The name stanza entry in the [preserve-cookie-names] stanza of the WebSEAL configuration file allows you to list the specific cookie names that are not to be renamed by WebSEAL. The specified cookie names are protected across any existing junction.

Example

[preserve-cookie-names]
name = cookie-name1
name = cookie-name2

Parent topic: Preservation of cookie names

Cookie handling: -I ensures unique Set-Cookie name attributeCookie handling: -I ensures unique Set-Cookie name attributecookiesensuring unique cookie name attribute (-I)junctionsensuring unique cookie name attribute (-I)A junction configured with a -j option causes Set-Cookie headers in responses from back-end servers to have their path attribute value converted to "/", and their name attribute modified by including the junction point. Sometimes the modification of the name attribute with the junction point does not result in mutually exclusive cookies.Standard -j option operation:If the following header: Set-Cookie: ORDERID=123456; path=/ordersis received from a backend server for the -j junction /sales, then the modified header sent to the browser would be:Set-Cookie: AMWEBJCT!/sales!ORDERID=123456; path=/However, if another Set-Cookie header with the same name attribute, but a different path value, is received over the same junction, the modified header would result in the exactly same name and path information. For example:Set-Cookie: ORDERID=123456; path=/invoicesis modified to: Set-Cookie: AMWEBJCT!/sales!ORDERID=123456; path=/Because the second modified Set-Cookie header has the same cookie name and path as the first header, it overwrites the first. The junction point is not enough to uniquely identify the Set-Cookie header.Solution:You can configure a -j junction with the additional -I option to add the original path attribute value (for example, /orders) to the modified name of the cookie. Now the cookie names are unique. The following rules apply when using the -I option: If the Set-Cookie header from the junctioned server contains a path attribute, the value of that path is URI-encoded and used to modify the name attribute. If the Set-Cookie header from the junctioned server does not contain a path attribute, the basedir of the request URI is extracted, URI-encoded, and used to modify the name attribute. For example, if the client request was for /dir1/dir2/mypage.html, then the value /dir1/dir2 would be URI-encoded and used.The Set-Cookie name attribute is then modified using the junction point (unless this is the root junction "/") plus the URI-encoded path value (or basedir value).The value of the Set-Cookie path attribute is still converted to "/" For example, if the following header:Set-Cookie: ORDERID=123456; path=/ordersis received from a backend server for the -j -I junction /sales, then the modified header sent to the browser would be:Set-Cookie: AMWEBJCT!/sales/orders!ORDERID=123456; path=/ Handling cookies from servers across multiple -j junctions

Cookie handling: -I ensures unique Set-Cookie name attribute

A junction configured with a -j option causes Set-Cookie headers in responses from back-end servers to have their path attribute value converted to "/", and their name attribute modified by including the junction point. Sometimes the modification of the name attribute with the junction point does not result in mutually exclusive cookies.

Standard -j option operation:

If the following header:

Set-Cookie: ORDERID=123456; path=/orders

is received from a backend server for the -j junction /sales, then the modified header sent to the browser would be:

Set-Cookie: AMWEBJCT!/sales!ORDERID=123456; path=/

However, if another Set-Cookie header with the same name attribute, but a different path value, is received over the same junction, the modified header would result in the exactly same name and path information.

For example:

Set-Cookie: ORDERID=123456; path=/invoices

is modified to:

Set-Cookie: AMWEBJCT!/sales!ORDERID=123456; path=/

Because the second modified Set-Cookie header has the same cookie name and path as the first header, it overwrites the first. The junction point is not enough to uniquely identify the Set-Cookie header.

Solution:

You can configure a -j junction with the additional -I option to add the original path attribute value (for example, /orders) to the modified name of the cookie. Now the cookie names are unique. The following rules apply when using the -I option:

If the Set-Cookie header from the junctioned server contains a path attribute, the value of that path is URI-encoded and used to modify the name attribute.

If the Set-Cookie header from the junctioned server does not contain a path attribute, the basedir of the request URI is extracted, URI-encoded, and used to modify the name attribute.

For example, if the client request was for /dir1/dir2/mypage.html, then the value /dir1/dir2 would be URI-encoded and used.

The Set-Cookie name attribute is then modified using the junction point (unless this is the root junction "/") plus the URI-encoded path value (or basedir value).

The value of the Set-Cookie path attribute is still converted to "/"

For example, if the following header:

Set-Cookie: ORDERID=123456; path=/orders

is received from a backend server for the -j -I junction /sales, then the modified header sent to the browser would be:

Set-Cookie: AMWEBJCT!/sales/orders!ORDERID=123456; path=/

Parent topic: Handling cookies from servers across multiple -j junctions

HTTP transformationsHTTP transformationsHTTP transformationsoverviewtransformationsHTTPYou can modify HTTP requests and responses as they pass through WebSEAL with HTTP transformation rules. XSLT is used for this function. You can trigger specific rules with a Protected Object Policy (POP) or a request line pattern match.WebSEAL administrators can configure the following modifications. You can apply these transformations to HTTP requests and HTTP responses (except where otherwise noted):Add a headerRemove a headerModify an existing headerModify the URI (request only)Modify the method (request only)Modify the authorization object name (request only)Modify the HTTP version Modify the HTTP status code (response only)Modify the status reason (response only)Add a cookieRemove a cookieModify an existing cookieAdd a body (response only)It is not possible to modify the body of the request or response. Similarly, you cannot modify cookies or headers that are inserted by WebSEAL. For example, the Host, iv-user and iv-creds junction headers.WebSEAL pages under the lib/html directory are referred to as HTML server response pages. These response pages are grouped into:Account management pages.Error message pages.You can configure the names of these response pages in the [acnt-mgt] stanza. Standard WebSEAL JunctionsExtensible Stylesheet Language Transformation (XSLT)HTTP transformation rulesConfigurationExample HTTP transformation scenariosTransformation errorsMost errors are printed in the server log or returned to the browser as an error page.

HTTP transformations

You can modify HTTP requests and responses as they pass through WebSEAL with HTTP transformation rules. XSLT is used for this function. You can trigger specific rules with a Protected Object Policy (POP) or a request line pattern match.

WebSEAL administrators can configure the following modifications. You can apply these transformations to HTTP requests and HTTP responses (except where otherwise noted):

Add a header

Remove a header

Modify an existing header

Modify the URI (request only)

Modify the method (request only)

Modify the authorization object name (request only)

Modify the HTTP version

Modify the HTTP status code (response only)

Modify the status reason (response only)

Add a cookie

Remove a cookie

Modify an existing cookie

Add a body (response only)

Note:

It is not possible to modify the body of the request or response. Similarly, you cannot modify cookies or headers that are inserted by WebSEAL. For example, the Host, iv-user and iv-creds junction headers.

WebSEAL pages under the lib/html directory are referred to as HTML server response pages. These response pages are grouped into:

Account management pages.

Error message pages.

You can configure the names of these response pages in the [acnt-mgt] stanza.

Extensible Stylesheet Language Transformation (XSLT)

HTTP transformation rules

Configuration

Example HTTP transformation scenarios

Transformation errors
Most errors are printed in the server log or returned to the browser as an error page.

Parent topic: Standard WebSEAL Junctions

Extensible Stylesheet Language Transformation (XSLT)Extensible Stylesheet Language Transformation (XSLT)HTTP transformationsExtensible Stylesheet Language TransformationXSLTExtensible Stylesheet Language (XSL) is the language used to specify rules, while Extensible Markup Language (XML) is the language used for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both inputs to the rules evaluator and rules themselves.You can use XML to express complex data types in a structured and standard manner in text format. Using this text format, you can write rules for processing the XML data without having to cater to platform and programming language specifics.You can use XSL Transformation (XSLT) rules to convert an XML document into another document in XML, PDF, HTML, or other format. A transformation rule must be defined as an XSL template in an XSL stylesheet. The rule must be written in a valid XSL template rule format. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation in e-business models.The HTTP requests and responses received by WebSEAL are expressed as XML objects and can be manipulated using XSL transformations. The attributes from the credential can be added to the XML object, but the credential attributes cannot be manipulated by the XSL transformations.HTTP transformationsHTTP transformation rulesConfigurationExample HTTP transformation scenariosTransformation errorsMost errors are printed in the server log or returned to the browser as an error page.

Extensible Stylesheet Language Transformation (XSLT)

Extensible Stylesheet Language (XSL) is the language used to specify rules, while Extensible Markup Language (XML) is the language used for the data that forms an input to the rules. The combination of XML and XSL provides a platform-independent way to express both inputs to the rules evaluator and rules themselves.

You can use XML to express complex data types in a structured and standard manner in text format. Using this text format, you can write rules for processing the XML data without having to cater to platform and programming language specifics.

You can use XSL Transformation (XSLT) rules to convert an XML document into another document in XML, PDF, HTML, or other format. A transformation rule must be defined as an XSL template in an XSL stylesheet. The rule must be written in a valid XSL template rule format. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation in e-business models.

The HTTP requests and responses received by WebSEAL are expressed as XML objects and can be manipulated using XSL transformations. The attributes from the credential can be added to the XML object, but the credential attributes cannot be manipulated by the XSL transformations.

Parent topic: HTTP transformations

Related concepts:

HTTP transformation rules

Configuration

Example HTTP transformation scenarios

Transformation errors

HTTP transformation rulesHTTP transformation rulesHTTP transformationsrulestransformationsHTTP rulesThe HTTP requests and responses received by WebSEAL are expressed as XML objects and can be manipulated using XSL transformations. You can use XSLT rules to represent the changes that you want to apply to the HTTP requests and responses as they pass through WebSEAL. WebSEAL uses the following two inputs for the HTTP transformations:An XML representation of the HTTP request or HTTP response. Attributes from the credential can be added to the XML object, but the credential attributes cannot be manipulated by the XSL transformations.An XSLT that determines how the request or response is modified. The output from the transformation is an XML document that outlines the changes required to the HTTP request or HTTP response.The XSLT rules are contained in a rules file. If a rules file is changed, you must restart the WebSEAL server for the changes to take effect. Header fields must be URL encoded to avoid any XML issues. WebSEAL uses URL encoded header values during the transformation process.HTTP transformationsExtensible Stylesheet Language Transformation (XSLT)ConfigurationExample HTTP transformation scenariosTransformation errorsMost errors are printed in the server log or returned to the browser as an error page.HTTP request objectsHTTP response objectsXSL transformation rulesReplacing the HTTP responseReprocessing considerationsIf an HTTP transformation rule modifies the URI, host header, or object name of the request, WebSEAL reprocesses the transformed request.

HTTP transformation rules

The HTTP requests and responses received by WebSEAL are expressed as XML objects and can be manipulated using XSL transformations.

You can use XSLT rules to represent the changes that you want to apply to the HTTP requests and responses as they pass through WebSEAL. WebSEAL uses the following two inputs for the HTTP transformations:

An XML representation of the HTTP request or HTTP response. Attributes from the credential can be added to the XML object, but the credential attributes cannot be manipulated by the XSL transformations.

An XSLT that determines how the request or response is modified.

The output from the transformation is an XML document that outlines the changes required to the HTTP request or HTTP response.

Note:

The XSLT rules are contained in a rules file. If a rules file is changed, you must restart the WebSEAL server for the changes to take effect.

Header fields must be URL encoded to avoid any XML issues. WebSEAL uses URL encoded header values during the transformation process.

HTTP request objects

HTTP response objects

XSL transformation rules

Replacing the HTTP response

Reprocessing considerations
If an HTTP transformation rule modifies the URI, host header, or object name of the request, WebSEAL reprocesses the transformed request.

Parent topic: HTTP transformations

Related concepts:

Extensible Stylesheet Language Transformation (XSLT)

Configuration

Example HTTP transformation scenarios

Transformation errors

HTTP request objectsHTTP request objectsHTTP request objects in WebSEALHTTP transformationsHTTP request objects The following example shows the XML representation of a HTTPRequest: <?xml version="1.0" encoding="UTF-8"?> <HTTPRequest> <RequestLine> <Method>GET</Method> <URI>/en/us/</URI> <Scheme>https</Scheme> <Version>HTTP/1.1</Version> </RequestLine> <Headers> <Header name="User-Agent">curl%2F7.18.2%20(i486-pc-linux-gnu)%20libcurl %2F7.18.2%20OpenSSL%2F0.9.8g%20zlib%2F1.2.3.3%20libidn%2F1.8</Header> <Header name="Host">www.ibm.com</Header> <Header name="Accept">*%2F*</Header> </Headers> <Cookies> <Cookie name="PD-S-SESSION-ID">2_orQUNJCbjdxqIEdDPMXj31UHMXuU3hRCU</Cookie> </Cookies> <Credential> <Attribute name=AZN_CRED_PRINCIPAL_NAME>testuser</Attribute> </Credential> </HTTPRequest> HTTP transformation rules

HTTP request objects

The following example shows the XML representation of a HTTPRequest:

<?xml version="1.0" encoding="UTF-8"?>
<HTTPRequest>
	<RequestLine>
		<Method>GET</Method>
		<URI>/en/us/</URI>
		<Scheme>https</Scheme>
		<Version>HTTP/1.1</Version>
	</RequestLine>
	<Headers>
		<Header name="User-Agent">curl%2F7.18.2%20(i486-pc-linux-gnu)%20libcurl
			%2F7.18.2%20OpenSSL%2F0.9.8g%20zlib%2F1.2.3.3%20libidn%2F1.8</Header>
		<Header name="Host">www.ibm.com</Header>
		<Header name="Accept">*%2F*</Header>
  </Headers>
	<Cookies>
		<Cookie name="PD-S-SESSION-ID">2_orQUNJCbjdxqIEdDPMXj31UHMXuU3hRCU</Cookie>
	</Cookies>
	<Credential>
    <Attribute name=AZN_CRED_PRINCIPAL_NAME>testuser</Attribute>
	</Credential>
</HTTPRequest>

Parent topic: HTTP transformation rules

HTTP response objectsHTTP response objectsHTTP response objects in WebSEALHTTP transformationsHTTP response objectsThe following example shows the XML Representation of a HTTPResponse:<?xml version="1.0" encoding="UTF-8"?> <HTTPResponse> <ResponseLine> <Version>HTTP/1.1</Version> <StatusCode>200</StatusCode> <Reason>OK</Reason> </ResponseLine> <Headers> <Header name="Date">Thu%2C%2016%20Sep%202010%2010%3A57%3A52%20GMT</Header> <Header name="Server">IBM_HTTP_Server</Header> <Header name="ContentLength">4096</Header> <Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header> <Header name="Content-Language">en-US</Header> </Headers> <Cookies> <Cookie name="PD-S-SESSION-ID"> <Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content> <Path>/</Path> <Domain>domainA.ibm.com</Domain> <Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires> <Secure>1</Secure> <HTTPOnly>0</HTTPOnly> </Cookie> </Cookies> <Credential> <Attribute name=AZN_CRED_PRINCIPAL_NAME>testuser</Attribute> </Credential> </HTTPResponse>HTTP transformation rules

HTTP response objects

The following example shows the XML Representation of a HTTPResponse:

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponse>
	<ResponseLine>
		<Version>HTTP/1.1</Version>
		<StatusCode>200</StatusCode>
		<Reason>OK</Reason>
	</ResponseLine>
	<Headers>
		<Header name="Date">Thu%2C%2016%20Sep%202010%2010%3A57%3A52%20GMT</Header>
		<Header name="Server">IBM_HTTP_Server</Header>
		<Header name="ContentLength">4096</Header>
		<Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header>
		<Header name="Content-Language">en-US</Header>
	</Headers>
	<Cookies>
		<Cookie name="PD-S-SESSION-ID">
			<Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content>
			<Path>/</Path>
			<Domain>domainA.ibm.com</Domain>
			<Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires>
			<Secure>1</Secure>
			<HTTPOnly>0</HTTPOnly>
		</Cookie>
	</Cookies>
	<Credential>
    <Attribute name=AZN_CRED_PRINCIPAL_NAME>testuser</Attribute>
	</Credential>
</HTTPResponse>

Parent topic: HTTP transformation rules

XSL transformation rulesXSL transformation rulesHTTP transformationsXSL transformation rulesXSLtransformation rulesA valid XSLT document can be used to transform the contents of the HTTP requests and responses. The XSL transformation must output an XML document that defines the required changes. The output document contains a series of XML elements describing changes that must be made to the HTTP request or HTTP response.Author the XSLT documents carefully. Review and test the XSL transformation rules thoroughly before you implement it in a production environment. Incorrect syntax or badly formed XSLT might cause errors, or unexpected behavior.The following table describes the base XML elements that WebSEAL requires in the transformed document: Base elementsSource documentBase XML elementHTTP Request<HTTPRequestChange>HTTP Response<HTTPResponseChange>The XSL transformation rules must handle the contents of the HTTP input. The content includes: The ResponseLine/RequestLine element.The Headers element.The Cookies element.The Body element. (HTTPResponseChange only)If elements of the RequestLine/ResponseLine are included in the transformed XML document, WebSEAL applies the corresponding changes to the HTTP request/response.Header elements require an action attribute in the XSLT document to determine how WebSEAL transforms the header. The available actions are:add - adds a new header with a specific name and value.update - updates the value of an existing header (if the header does not exist, it is added).remove - removes the header with a specific name and value.The Cookie elements require an action attribute in the XSLT document to determine how WebSEAL transforms the cookie. The available actions are:add - adds a new cookie with the specified name and values.update - updates the value of an existing cookie. (If the cookie does not exist, it is added).remove - removes the cookie with a specific name.Cookies are represented differently in requests and responses. Only the response contains the attributes beyond name and value. When updating a cookie, specify the cookie name and the fields that you want to update. When adding a cookie, the minimum fields that you must specify are cookie name and value.You can optionally include the Body element to insert a body into an HTTP response. The content of the Body must be URL encoded. WebSEAL decodes the content when it creates the response. WebSEAL replaces any existing body in the HTTP response with the new content that is provided in this Body element. This element does not require an action.It is not possible to replace the body content in requests.The authorization object name can be customized based on an incoming request. But the object name can be changed only once. A subsequent change of the object name within the same request does not generate a new authorization decision. The ObjectName element value can be either a relative value or an absolute value. For standard junctions, the relative value format is junction-name/resource. For virtual junctions, the relative value format is resource. For standard junctions, the absolute value format is /host_name-instance_name/junction-name/resource. For virtual junctions, the absolute value format is /host_name-instance_name/@virtual-junction-name/resource. An absolute object name must begin with /. The customized authorization object names do not undergo dynamic URL processing.HTTP transformation rules

XSL transformation rules

A valid XSLT document can be used to transform the contents of the HTTP requests and responses.

The XSL transformation must output an XML document that defines the required changes. The output document contains a series of XML elements describing changes that must be made to the HTTP request or HTTP response.

Important: Author the XSLT documents carefully. Review and test the XSL transformation rules thoroughly before you implement it in a production environment. Incorrect syntax or badly formed XSLT might cause errors, or unexpected behavior.

The following table describes the base XML elements that WebSEAL requires in the transformed document:

Table 63. Base elements

Source document | Base XML element
HTTP Request | <HTTPRequestChange>
HTTP Response | <HTTPResponseChange>

The XSL transformation rules must handle the contents of the HTTP input. The content includes:

The ResponseLine/RequestLine element.

The Headers element.

The Cookies element.

The Body element. (HTTPResponseChange only)

If elements of the RequestLine/ResponseLine are included in the transformed XML document, WebSEAL applies the corresponding changes to the HTTP request/response.

Header elements require an action attribute in the XSLT document to determine how WebSEAL transforms the header. The available actions are:

add - adds a new header with a specific name and value.

update - updates the value of an existing header (if the header does not exist, it is added).

remove - removes the header with a specific name and value.

The Cookie elements require an action attribute in the XSLT document to determine how WebSEAL transforms the cookie. The available actions are:

add - adds a new cookie with the specified name and values.

update - updates the value of an existing cookie. (If the cookie does not exist, it is added).

remove - removes the cookie with a specific name.

Note: Cookies are represented differently in requests and responses. Only the response contains the attributes beyond name and value. When updating a cookie, specify the cookie name and the fields that you want to update. When adding a cookie, the minimum fields that you must specify are cookie name and value.

You can optionally include the Body element to insert a body into an HTTP response. The content of the Body must be URL encoded. WebSEAL decodes the content when it creates the response. WebSEAL replaces any existing body in the HTTP response with the new content that is provided in this Body element. This element does not require an action.

Note: It is not possible to replace the body content in requests.

The authorization object name can be customized based on an incoming request. But the object name can be changed only once. A subsequent change of the object name within the same request does not generate a new authorization decision. The ObjectName element value can be either a relative value or an absolute value. For standard junctions, the relative value format is junction-name/resource. For virtual junctions, the relative value format is resource. For standard junctions, the absolute value format is /host_name-instance_name/junction-name/resource. For virtual junctions, the absolute value format is /host_name-instance_name/@virtual-junction-name/resource. An absolute object name must begin with /. The customized authorization object names do not undergo dynamic URL processing.

Parent topic: HTTP transformation rules

Replacing the HTTP responseReplacing the HTTP responseHTTP transformationsreplacing the responseHTTP responseYou can create an entirely new HTTP response for a specified HTTP request. To achieve this behavior, modify an HTTP Request to produce an HTTPResponseChange XML document with action="replace" in the base XML element. For example:<?xml version="1.0" encoding="UTF-8"?> <HTTPResponseChange action="replace"> <Version>HTTP/1.1</Version> <StatusCode>503</StatusCode> <Reason>Not Implemented</Reason> <Body>%3Ch1%3EError%3C%2Fh1%3E%0A%3Cp%3EInvalid%20cookie%20%3C%2Fp%3E</Body> </HTTPResponseChange>See Scenario 5: Providing a response to a known HTTP requestThis scenario illustrates how a HTTPResponseChange document can be used to generate a response directly from a request. In this scenario, if a cookie with name 'invalid-cookie' exists in the HTTP Request then the XSL transformation produces an HTTP Response that indicates an invalid cookie was detected. for an example scenario.The HTTPResponseChange document can result from HTTP Request or HTTP Response modifications. If WebSEAL receives an HTTPResponseChange document with action="replace" as a result of an HTTP Request modification then WebSEAL: Interrupts the normal flow of processing and does not generate a response in the usual manner.Constructs a new HTTP response based on the provided XML document.You can use this functionality to intercept particular HTTP Requests and provide a predefined response.Similarly, if WebSEAL receives an HTTPResponseChange document with action="replace" as a result of an HTTP Response modification then WebSEAL: Discards the original response.Uses the response that is specified in the XML.HTTP transformation rules

Replacing the HTTP response

You can create an entirely new HTTP response for a specified HTTP request. To achieve this behavior, modify an HTTP Request to produce an HTTPResponseChange XML document with action="replace" in the base XML element.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponseChange action="replace">
<Version>HTTP/1.1</Version>
<StatusCode>503</StatusCode>
<Reason>Not Implemented</Reason>
<Body>%3Ch1%3EError%3C%2Fh1%3E%0A%3Cp%3EInvalid%20cookie%20%3C%2Fp%3E</Body>
</HTTPResponseChange>

See Scenario 5: Providing a response to a known HTTP request for an example scenario.

The HTTPResponseChange document can result from HTTP Request or HTTP Response modifications.

If WebSEAL receives an HTTPResponseChange document with action="replace" as a result of an HTTP Request modification then WebSEAL:

Interrupts the normal flow of processing and does not generate a response in the usual manner.

Constructs a new HTTP response based on the provided XML document.

You can use this functionality to intercept particular HTTP Requests and provide a predefined response.

Note: Similarly, if WebSEAL receives an HTTPResponseChange document with action="replace" as a result of an HTTP Response modification then WebSEAL:

Discards the original response.

Uses the response that is specified in the XML.

Parent topic: HTTP transformation rules

Reprocessing considerationsReprocessing considerationsIf an HTTP transformation rule modifies the URI, host header, or object name of the request, WebSEAL reprocesses the transformed request.HTTP transformationsreprocessing considerationsreprocessing requestsThis reprocessing ensures that the transformation does not bypass WebSEAL authorization. This behavior also means that administrators can define HTTP transformations rules to send requests to different junctions.WebSEAL performs reprocessing (and authorization) on the first HTTP transformation only. Transformed requests undergo HTTP transformation again if there is an appropriate POP attached to the associated object space. See Protected Object Policy (POP). However, WebSEAL does not reprocess the new requests that result from these subsequent transformations.HTTP transformation rules

Reprocessing considerations

If an HTTP transformation rule modifies the URI, host header, or object name of the request, WebSEAL reprocesses the transformed request.

This reprocessing ensures that the transformation does not bypass WebSEAL authorization. This behavior also means that administrators can define HTTP transformations rules to send requests to different junctions.

WebSEAL performs reprocessing (and authorization) on the first HTTP transformation only. Transformed requests undergo HTTP transformation again if there is an appropriate POP attached to the associated object space. See Protected Object Policy (POP). However, WebSEAL does not reprocess the new requests that result from these subsequent transformations.

Parent topic: HTTP transformation rules

ConfigurationConfigurationHTTP transformationsconfigurationconfigurationoverviewFor efficiency, it is important that transactions undergo the transformation process only when necessary. You can use the [http-transformations] stanza and associated POPs or request pattern matching rules to configure the objects that require HTTP transformation processing.You can attach a POP to wanted objects in the object space. The POP must contain the name of a resource as an extended attribute. This resource name is matched against the name of an entry in the [http-transformations] configuration stanza. The value of this matching [http-transformations] stanza entry specifies the name of the file that contains the applicable XSLT rules.The alternative to configuring a POP is to configure an [http-transformations:<resource_name>] stanza with a request-match entry. If a match with the pattern defined in the request-match entry is found, HTTP transformation processing is triggered.HTTP transformationsExtensible Stylesheet Language Transformation (XSLT)HTTP transformation rulesExample HTTP transformation scenariosTransformation errorsMost errors are printed in the server log or returned to the browser as an error page.Configuration file updatesYou can use the [http-transformations] stanza to define HTTP transformation resources.Protected Object Policy (POP)

Configuration

For efficiency, it is important that transactions undergo the transformation process only when necessary. You can use the [http-transformations] stanza and associated POPs or request pattern matching rules to configure the objects that require HTTP transformation processing.

You can attach a POP to wanted objects in the object space. The POP must contain the name of a resource as an extended attribute. This resource name is matched against the name of an entry in the [http-transformations] configuration stanza. The value of this matching [http-transformations] stanza entry specifies the name of the file that contains the applicable XSLT rules.

The alternative to configuring a POP is to configure an [http-transformations:<resource_name>] stanza with a request-match entry. If a match with the pattern defined in the request-match entry is found, HTTP transformation processing is triggered.

Configuration file updates
You can use the [http-transformations] stanza to define HTTP transformation resources.

Protected Object Policy (POP)

Parent topic: HTTP transformations

Related concepts:

Extensible Stylesheet Language Transformation (XSLT)

HTTP transformation rules

Example HTTP transformation scenarios

Transformation errors

Configuration file updatesConfiguration file updatesYou can use the [http-transformations] stanza to define HTTP transformation resources.http-transformations stanzaWebSEALconfigurationfile updatesUse the resource-name configuration entry to define HTTP transformation resources. The configuration entries must be in the following format:resource-name = resource-filewhere:resource-nameThe name of the HTTP transformation resource.resource-fileThe name of the resource XSL file.For more information, see [http-transformations] stanzaUse the [http-transformations] stanza to define the HTTP transformation settings..You can use the [http-transformations: <resource-name> ]stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name>  component of the stanza name must be changed to the actual name of the resource. Use the cred-attr-name configuration entry in this stanza to define the credential attribute that is included in the XML input document and used when evaluating the HTTP transformation rule. The configuration entries must be in the following format: cred-attr-name = namewhere:nameName of the credential attribute.Use the request-match configuration entry in the [http-transformations: <resource-name> ] stanza to determine whether a request should be processed or not. The format of this configuration entry is: request-match = {request|response}:<request-line>The first component of the configuration entry determines whether the processing is executed on the HTTP request or response. The second component contains the request line to be matched. A case-sensitive comparison is made between the configuration entry and the HTTP request line. The wildcard characters * and ? can be used in the comparison. You can specify multiple entries if needed.You also have the option of matching a request by using a host header. This option is useful when you need to selectively enable this functionality for a particular virtual host junction. To selectively match an entry based on a particular host header. prepend the <request-line> with the string [<host>].For more information, see [http-transformations] stanzaUse the [http-transformations] stanza to define the HTTP transformation settings..Configuration

Configuration file updates

You can use the [http-transformations] stanza to define HTTP transformation resources.

Use the resource-name configuration entry to define HTTP transformation resources. The configuration entries must be in the following format:

resource-name = resource-file

where:

resource-name

The name of the HTTP transformation resource.

resource-file

The name of the resource XSL file.

For more information, see [http-transformations] stanza.

You can use the [http-transformations: <resource-name> ]stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name>  component of the stanza name must be changed to the actual name of the resource.

Use the cred-attr-name configuration entry in this stanza to define the credential attribute that is included in the XML input document and used when evaluating the HTTP transformation rule. The configuration entries must be in the following format:

 cred-attr-name = name

where:

name

Name of the credential attribute.

Use the request-match configuration entry in the [http-transformations: <resource-name> ] stanza to determine whether a request should be processed or not. The format of this configuration entry is:

request-match = {request|response}:<request-line>

The first component of the configuration entry determines whether the processing is executed on the HTTP request or response. The second component contains the request line to be matched. A case-sensitive comparison is made between the configuration entry and the HTTP request line. The wildcard characters "*" and "?" can be used in the comparison. You can specify multiple entries if needed.

You also have the option of matching a request by using a host header. This option is useful when you need to selectively enable this functionality for a particular virtual host junction. To selectively match an entry based on a particular host header. prepend the <request-line> with the string [<host>].

For more information, see [http-transformations] stanza.

Parent topic: Configuration

Protected Object Policy (POP)Protected Object PolicyPOPoverviewProtetected Object PolicyYou can use a POP to enable the predefined XSLT resource for appropriate parts of the object space. This mechanism lets you specify the resources that need to undergo HTTP transformations.The POP must have an extended attribute with the name HTTPTransformation and a value in the form: Request=resource, orResponse=resourcewhere:resourceIdentifies one of the HTTP transformation resource names defined in the WebSEAL configuration file.Only one HTTP transformation is performed on each request and response. If multiple HTTPTransformation attributes exist with Request or Response values, the first is chosen.The following listing shows an example POP:pdadmin sec_master> pop show http-transformation-pop attribute HTTPTransformation HTTPTransformation Request=resource_a Response=resource_bConfiguration

Protected Object Policy (POP)

You can use a POP to enable the predefined XSLT resource for appropriate parts of the object space. This mechanism lets you specify the resources that need to undergo HTTP transformations.

The POP must have an extended attribute with the name HTTPTransformation and a value in the form:

Request=resource, or

Response=resource

where:

resource

Identifies one of the HTTP transformation resource names defined in the WebSEAL configuration file.

Only one HTTP transformation is performed on each request and response. If multiple HTTPTransformation attributes exist with Request or Response values, the first is chosen.

The following listing shows an example POP:

pdadmin sec_master> pop show http-transformation-pop attribute HTTPTransformation
HTTPTransformation
        Request=resource_a
        Response=resource_b

Parent topic: Configuration

Example HTTP transformation scenariosExample HTTP transformation scenariosHTTPtransformation scenariostransformationsscenariosThe following scenarios provide example input and output documents for the HTTP transformation process.HTTP transformationsExtensible Stylesheet Language Transformation (XSLT)HTTP transformation rulesConfigurationTransformation errorsMost errors are printed in the server log or returned to the browser as an error page.Scenario 1: Modifying the URI, headers, and cookies (HTTPRequest)Scenario 2: Modifying the headers only (HTTPResponse)This scenario illustrates how to modify the headers in an HTTP Response. The XSLT in this example adds a new header called RESPONSE_A with the value VALUE_A if it does not exist.Scenario 3: Modifying the ResponseLine/StatusCode only (HTTPResponse)Scenario 4: Modifying cookies only (HTTPResponse)Scenario 5: Providing a response to a known HTTP requestThis scenario illustrates how a HTTPResponseChange document can be used to generate a response directly from a request. In this scenario, if a cookie with name 'invalid-cookie' exists in the HTTP Request then the XSL transformation produces an HTTP Response that indicates an invalid cookie was detected.Scenario 6: Adding a credential attribute value to the responseThis scenario illustrates how a HTTPResponseChange document can be used to add a credential attribute value to the response.

Example HTTP transformation scenarios

The following scenarios provide example input and output documents for the HTTP transformation process.

Scenario 1: Modifying the URI, headers, and cookies (HTTPRequest)

Scenario 2: Modifying the headers only (HTTPResponse)
This scenario illustrates how to modify the headers in an HTTP Response. The XSLT in this example adds a new header called RESPONSE_A with the value VALUE_A if it does not exist.

Scenario 3: Modifying the ResponseLine/StatusCode only (HTTPResponse)

Scenario 4: Modifying cookies only (HTTPResponse)

Scenario 5: Providing a response to a known HTTP request
This scenario illustrates how a HTTPResponseChange document can be used to generate a response directly from a request. In this scenario, if a cookie with name 'invalid-cookie' exists in the HTTP Request then the XSL transformation produces an HTTP Response that indicates an invalid cookie was detected.

Scenario 6: Adding a credential attribute value to the response
This scenario illustrates how a HTTPResponseChange document can be used to add a credential attribute value to the response.

Parent topic: HTTP transformations

Related concepts:

Extensible Stylesheet Language Transformation (XSLT)

HTTP transformation rules

Configuration

Transformation errors

Scenario 1: Modifying the URI, headers, and cookies (HTTPRequest)Scenario 1: Modifying the URI, headers, and cookies (HTTPRequest)HTTPResponsemodifying URImodifyingURIheaderscookiesHTTPRequestThis scenario illustrates how to modify the RequestLine/URI element, as well as the header and cookie elements in the original HTTP request.The following changes are made to the HTTP request in this example:Append /test to the existing URI value.Add a new header called NAME_A with the value VALUE_A if it does not exist.Update the NAME_B header value to be UPDATED_B.Remove the header called NAME_C.Add a cookie called MY_COOKIE.Update the EXISTING_COOKIE cookie content to be NEW_COOKIE_VALUE.Input documentsThe following sample input documents are used for this scenario:HTTP Request<?xml version="1.0" encoding="UTF-8"?> <HTTPRequest> <RequestLine> <Method>GET</Method> <URI>/en/us/</URI> <Scheme>https</Scheme> <Version>HTTP/1.1</Version> </RequestLine> <Headers> <Header name="Host">www.ibm.com</Header> <Header name="NAME_B">ORIGINAL_B</Header> <Header name="NAME_C">ORIGINAL_C</Header> </Headers> <Cookies> <Cookie name="EXISTING_COOKIE">2_orQUNJCbjdxqIEdDPMXj31UHMXuU3hRCU...</Cookie> </Cookies> </HTTPRequest>XSLT RulesThese rules must be stored in an XSL document that is defined as a request resource with an associated POP or a request line pattern match. See Configuration. <?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!--Firstly, strip any space elements --> <xsl:strip-space elements="*" /> <!-- Perform a match on the root of the document. Output the required HTTPRequestChange elements and then process templates. --> <xsl:template match="/"> <HTTPRequestChange> <xsl:apply-templates /> <!-- Update the value of object name based on the URI --> <ObjectName> /combined-instances<xsl:value-of select="//HTTPRequest/RequestLine/URI"/> </ObjectName> </HTTPRequestChange> </xsl:template> <!-- Do nothing to the Method. --> <xsl:template match="//HTTPRequest/RequestLine/Method" /> <!-- Match on the URI. Append "test/" to the URI. --> <xsl:template match="//HTTPRequest/RequestLine/URI"> <URI> <xsl:value-of select="node()" /> test/ </URI> </xsl:template> <!-- Do nothing to the Version --> <xsl:template match="//HTTPRequest/RequestLine/Version" /> <!-- Match on the Headers. Add a new header called NAME_A if it does not exist. --> <xsl:template match="//HTTPRequest/Headers"> <xsl:choose> <xsl:when test="Header/@name='NAME_A'" /> <xsl:otherwise> <Header action="add" name="NAME_A"> VALUE_A </Header> </xsl:otherwise> </xsl:choose> <xsl:apply-templates select="//HTTPRequest/Headers/Header" /> </xsl:template> <!-- Process the header elements --> <xsl:template match="//HTTPRequest/Headers/Header"> <xsl:choose> <!-- Update the value of the NAME_B header --> <xsl:when test="@name = 'NAME_B'"> <Header action="update" name="NAME_B"> UPDATED_B </Header> </xsl:when> <!-- Delete the NAME_C header --> <xsl:when test="contains(@name, 'NAME_C')"> <Header action="remove" name="NAME_C"> <xsl:value-of select="node()" /> </Header> </xsl:when> </xsl:choose> </xsl:template> <!-- Match on the Cookies. Add a new cookie called MY_COOKIE if it does not exist. --> <xsl:template match="//HTTPRequest/Cookies"> <xsl:choose> <xsl:when test="Cookie/@name='MY_COOKIE'" /> <xsl:otherwise> <Cookie action="add" name="MY_COOKIE"> MY_COOKIE_VALUE </Cookie> </xsl:otherwise> </xsl:choose> <xsl:apply-templates select="//HTTPRequest/Cookies/Cookie" /> </xsl:template> <!-- Process the cookie elements --> <xsl:template match="//HTTPRequest/Cookies/Cookie"> <xsl:choose> <!-- Update the value of the EXISTING_COOKIE cookie --> <xsl:when test="@name = 'EXISTING_COOKIE'"> <Cookie action="update" name="EXISTING_COOKIE"> NEW_COOKIE_VALUE </Cookie> </xsl:when> </xsl:choose> </xsl:template> </xsl:stylesheet>Output XML documentIn this scenario, the following XML document is output from the XSL transformation. This document outlines changes for WebSEAL to perform on the original HTTP request.<?xml version="1.0" encoding="UTF-8"?> <HTTPRequestChange> <URI>/en/us/test/</URI> <Header action="add" name="NAME_A">VALUE_A</Header> <Header action="update" name="NAME_B">UPDATED_B</Header> <Header action="remove" name="NAME_C">ORIGINAL_C</Header> <Cookie action="add" name="MY_COOKIE">MY_COOKIE_VALUE</Cookie> <Cookie action="update" name="EXISTING_COOKIE">NEW_COOKIE_VALUE</Cookie> <ObjectName>/combined-instances/jct/resourceB</ObjectName> </HTTPRequestChange>Example HTTP transformation scenarios

Scenario 1: Modifying the URI, headers, and cookies (HTTPRequest)

This scenario illustrates how to modify the RequestLine/URI element, as well as the header and cookie elements in the original HTTP request.

The following changes are made to the HTTP request in this example:

Append /test to the existing URI value.

Add a new header called NAME_A with the value VALUE_A if it does not exist.

Update the NAME_B header value to be UPDATED_B.

Remove the header called NAME_C.

Add a cookie called MY_COOKIE.

Update the EXISTING_COOKIE cookie content to be NEW_COOKIE_VALUE.

Input documents

The following sample input documents are used for this scenario:

HTTP Request

<?xml version="1.0" encoding="UTF-8"?>
<HTTPRequest>
	<RequestLine>
		<Method>GET</Method>
		<URI>/en/us/</URI>
  <Scheme>https</Scheme>
		<Version>HTTP/1.1</Version>
	</RequestLine>
	<Headers>
		<Header name="Host">www.ibm.com</Header>
		<Header name="NAME_B">ORIGINAL_B</Header>
		<Header name="NAME_C">ORIGINAL_C</Header>
	</Headers>
	<Cookies>
		<Cookie name="EXISTING_COOKIE">2_orQUNJCbjdxqIEdDPMXj31UHMXuU3hRCU...</Cookie>
	</Cookies>
</HTTPRequest>

XSLT Rules

Note: These rules must be stored in an XSL document that is defined as a request resource with an associated POP or a request line pattern match. See Configuration.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

 <!--Firstly, strip any space elements -->
 <xsl:strip-space elements="*" />

 <!--
  Perform a match on the root of the document. Output the required
  HTTPRequestChange elements and then process templates.
 -->
 <xsl:template match="/">
  <HTTPRequestChange>
   <xsl:apply-templates />

   <!-- Update the value of object name based on the URI -->
   <ObjectName>
    /combined-instances<xsl:value-of select="//HTTPRequest/RequestLine/URI"/>
   </ObjectName>

  </HTTPRequestChange>
 </xsl:template>

 <!--
  Do nothing to the Method.
 -->
 <xsl:template match="//HTTPRequest/RequestLine/Method" />

 <!--
  Match on the URI. Append "test/" to the URI.
 -->
 <xsl:template match="//HTTPRequest/RequestLine/URI">
  <URI>
   <xsl:value-of select="node()" />
    test/
  </URI>
 </xsl:template>

 <!--
  Do nothing to the Version
 -->
 <xsl:template match="//HTTPRequest/RequestLine/Version" />

 <!--
  Match on the Headers. Add a new header called NAME_A if
  it does not exist.
 -->
 <xsl:template match="//HTTPRequest/Headers">
  <xsl:choose>
   <xsl:when test="Header/@name='NAME_A'" />
   <xsl:otherwise>
    <Header action="add" name="NAME_A">
     VALUE_A
    </Header>
   </xsl:otherwise>
  </xsl:choose>
  <xsl:apply-templates select="//HTTPRequest/Headers/Header" />
 </xsl:template>

 <!-- Process the header elements -->
 <xsl:template match="//HTTPRequest/Headers/Header">
  <xsl:choose>
   <!-- Update the value of the NAME_B header -->
   <xsl:when test="@name = 'NAME_B'">
    <Header action="update" name="NAME_B">
     UPDATED_B
    </Header>
   </xsl:when>
   <!-- Delete the NAME_C header -->
   <xsl:when test="contains(@name, 'NAME_C')">
    <Header action="remove" name="NAME_C">
     <xsl:value-of select="node()" />
    </Header>
   </xsl:when>
  </xsl:choose>
 </xsl:template>

 <!--
  Match on the Cookies. Add a new cookie called MY_COOKIE if
  it does not exist.
 -->
 <xsl:template match="//HTTPRequest/Cookies">
  <xsl:choose>
   <xsl:when test="Cookie/@name='MY_COOKIE'" />
   <xsl:otherwise>
    <Cookie action="add" name="MY_COOKIE">
     MY_COOKIE_VALUE
    </Cookie>
   </xsl:otherwise>
  </xsl:choose>
  <xsl:apply-templates select="//HTTPRequest/Cookies/Cookie" />
 </xsl:template>

 <!-- Process the cookie elements -->
 <xsl:template match="//HTTPRequest/Cookies/Cookie">
  <xsl:choose>
   <!-- Update the value of the EXISTING_COOKIE cookie -->
   <xsl:when test="@name = 'EXISTING_COOKIE'">
    <Cookie action="update" name="EXISTING_COOKIE">
     NEW_COOKIE_VALUE
    </Cookie>
   </xsl:when>
  </xsl:choose>
 </xsl:template>

</xsl:stylesheet>

Output XML document

In this scenario, the following XML document is output from the XSL transformation. This document outlines changes for WebSEAL to perform on the original HTTP request.

<?xml version="1.0" encoding="UTF-8"?>
<HTTPRequestChange>
 <URI>/en/us/test/</URI>
 <Header action="add" name="NAME_A">VALUE_A</Header>
 <Header action="update" name="NAME_B">UPDATED_B</Header>
 <Header action="remove" name="NAME_C">ORIGINAL_C</Header>
 <Cookie action="add" name="MY_COOKIE">MY_COOKIE_VALUE</Cookie>
 <Cookie action="update" name="EXISTING_COOKIE">NEW_COOKIE_VALUE</Cookie>
 <ObjectName>/combined-instances/jct/resourceB</ObjectName>
</HTTPRequestChange>

Parent topic: Example HTTP transformation scenarios

Scenario 2: Modifying the headers only (HTTPResponse)Scenario 2: Modifying the headers only (HTTPResponse)This scenario illustrates how to modify the headers in an HTTP Response. The XSLT in this example adds a new header called RESPONSE_A with the value VALUE_A if it does not exist.headersHTTPResponsemodifying headersInput documentsThe following sample input documents are used for this scenario:HTTP Response<?xml version="1.0" encoding="UTF-8"?> <HTTPResponse> <ResponseLine> <Version>HTTP/1.1</Version> <StatusCode>200</StatusCode> <Reason>OK</Reason> </ResponseLine> <Headers> <Header name="Date">Thu%2C%2016%20Sep%202010%2010 %3A57%3A52%20GMT</Header> <Header name="Server">IBM_HTTP_Server</Header> <Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header> <Header name="Content-Language">en-US</Header> </Headers> <Cookies> <Cookie name="PD-S-SESSION-ID"> <Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content> <Path>/</Path> <Domain>domainA.com</Domain> <Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires> <Secure>1</Secure> <HTTPOnly>0</HTTPOnly> </Cookie> </Cookies> </HTTPResponse>XSLT RulesThese rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!--Firstly, strip any space elements --> <xsl:strip-space elements="*" /> <!-- Perform a match on the root of the document. Output the required HTTPResponseChange elements and then process templates. --> <xsl:template match="/"> <HTTPResponseChange> <xsl:apply-templates /> </HTTPResponseChange> </xsl:template> <!-- Do nothing to the Version --> <xsl:template match="//HTTPResponse/ResponseLine/Version" /> <!-- Do nothing to the StatusCode --> <xsl:template match="//HTTPResponse/ResponseLine/StatusCode" /> <!-- Do nothing to the Reason --> <xsl:template match="//HTTPResponse/ResponseLine/Reason" /> <!-- Match on the Headers. Add a new header called RESPONSE_A if it does not exist. --> <xsl:template match="//HTTPResponse/Headers"> <xsl:choose> <xsl:when test="Header/@name='RESPONSE_A'"/> <xsl:otherwise> <Header action="add" name="RESPONSE_A"> VALUE_A </Header> </xsl:otherwise> </xsl:choose> </xsl:template> <!-- Do nothing to the Cookies --> <xsl:template match="//HTTPResponse/Cookies" /> </xsl:stylesheet>Output XML documentIn this scenario, the following XML document is output from the XSL transformation. This document outlines changes for WebSEAL to perform on the original HTTP response.<?xml version="1.0" encoding="UTF-8"?> <HTTPResponseChange> <Header action="add" name="RESPONSE_A">VALUE_A</Header> </HTTPResponseChange>Example HTTP transformation scenarios

Scenario 2: Modifying the headers only (HTTPResponse)

This scenario illustrates how to modify the headers in an HTTP Response. The XSLT in this example adds a new header called RESPONSE_A with the value VALUE_A if it does not exist.

Input documents

The following sample input documents are used for this scenario:

HTTP Response

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponse>
	<ResponseLine>
		<Version>HTTP/1.1</Version>
		<StatusCode>200</StatusCode>
		<Reason>OK</Reason>
	</ResponseLine>
	<Headers>
		<Header name="Date">Thu%2C%2016%20Sep%202010%2010
			%3A57%3A52%20GMT</Header>
		<Header name="Server">IBM_HTTP_Server</Header>
		<Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header>
		<Header name="Content-Language">en-US</Header>
	</Headers>
	<Cookies>
		<Cookie name="PD-S-SESSION-ID">
			<Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content>
			<Path>/</Path>
			<Domain>domainA.com</Domain>
			<Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires>
			<Secure>1</Secure>
			<HTTPOnly>0</HTTPOnly>
		</Cookie>
	</Cookies>
</HTTPResponse>

XSLT Rules

Note: These rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	version="1.0">

	<!--Firstly, strip any space elements -->
	<xsl:strip-space elements="*" />

	<!--
		Perform a match on the root of the document. Output the required
		HTTPResponseChange elements and then process templates.
	-->
		<xsl:template match="/">
			<HTTPResponseChange>
				<xsl:apply-templates />
			</HTTPResponseChange>
		</xsl:template>

	<!--
		Do nothing to the Version
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/Version" />

	<!--
		Do nothing to the StatusCode
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/StatusCode" />

	<!--
		Do nothing to the Reason
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/Reason" />

	<!--
		Match on the Headers. Add a new header called RESPONSE_A
		if it does not exist.
	-->
	<xsl:template match="//HTTPResponse/Headers">
		<xsl:choose>
			<xsl:when test="Header/@name='RESPONSE_A'"/>
			<xsl:otherwise>
				<Header action="add" name="RESPONSE_A">
					VALUE_A
				</Header>
			</xsl:otherwise>
		</xsl:choose>
	</xsl:template>

<!--
		Do nothing to the Cookies
	-->
	<xsl:template match="//HTTPResponse/Cookies" />

</xsl:stylesheet>

Output XML document

In this scenario, the following XML document is output from the XSL transformation. This document outlines changes for WebSEAL to perform on the original HTTP response.

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponseChange>
	<Header action="add" name="RESPONSE_A">VALUE_A</Header>
</HTTPResponseChange>

Parent topic: Example HTTP transformation scenarios

Scenario 3: Modifying the ResponseLine/StatusCode only (HTTPResponse)Scenario 3: Modifying the ResponseLine/StatusCode only (HTTPResponse)ResponseLine/StatusCode only (HTTPResponse)HTTPResponsemodifying response lineThis scenario illustrates how to modify the StatusCode and Reason elements in an HTTP Response. The XSLT in this example makes the following updates: 503 status codes are changed to be 501.When a status code update occurs, the reason is also updated to reflect the change. The reason for the 501 status is “Not Implemented".Input documentsThe following sample input documents are used for this scenario: HTTP Response<?xml version="1.0" encoding="UTF-8"?> <HTTPResponse> <ResponseLine> <Version>HTTP/1.1</Version> <StatusCode>503</StatusCode> <Reason>Service Unavailable</Reason> </ResponseLine> <Headers> <Header name="Date">Thu%2C%2016%20Sep%202010%2010 %3A57%3A52%20GMT</Header> <Header name="Server">IBM_HTTP_Server</Header> <Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header> <Header name="Content-Language">en-US</Header> </Headers> <Cookies> <Cookie name="PD-S-SESSION-ID"> <Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content> <Path>/</Path> <Domain>domainA.com</Domain> <Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires> <Secure>1</Secure> <HTTPOnly>0</HTTPOnly> </Cookie> </Cookies> </HTTPResponse>XSLT RulesThese rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!--Firstly, strip any space elements --> <xsl:strip-space elements="*" /> <!-- Perform a match on the root of the document. Output the required HTTPResponseChange elements and then process templates. --> <xsl:template match="/"> <HTTPResponseChange> <xsl:apply-templates /> </HTTPResponseChange> </xsl:template> <!-- Do nothing to the Version --> <xsl:template match="//HTTPResponse/ResponseLine/Version" /> <!-- If the original StatusCode is 503 then update the StatusCode to 501. --> <xsl:template match="//HTTPResponse/ResponseLine/StatusCode"> <xsl:choose> <xsl:when test="503"> <StatusCode>501</StatusCode> </xsl:when> </xsl:choose> </xsl:template> <!-- Update the Reason to match the StatusCode change. --> <xsl:template match="//HTTPResponse/ResponseLine/Reason"> <xsl:choose> <xsl:when test="'Service Unavailable'"> <Reason>Not Implemented</Reason> </xsl:when> </xsl:choose> </xsl:template> <!-- Do nothing to the Headers. --> <xsl:template match="//HTTPResponse/Headers" /> <!-- Do nothing to the Cookies. --> <xsl:template match="//HTTPResponse/Cookies" /> </xsl:stylesheet>Output XML documentIn this scenario, the following XML document is output from the XSL transformation. This document outlines changes for WebSEAL to perform on the original HTTP response.<?xml version="1.0" encoding="UTF-8"?> <HTTPResponseChange> <StatusCode>501</StatusCode> <Reason>Not Implemented</Reason> </HTTPResponseChange>Example HTTP transformation scenarios

Scenario 3: Modifying the ResponseLine/StatusCode only (HTTPResponse)

This scenario illustrates how to modify the StatusCode and Reason elements in an HTTP Response. The XSLT in this example makes the following updates:

503 status codes are changed to be 501.

When a status code update occurs, the reason is also updated to reflect the change. The reason for the 501 status is “Not Implemented".

Input documents

The following sample input documents are used for this scenario:

HTTP Response

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponse>
	<ResponseLine>
		<Version>HTTP/1.1</Version>
		<StatusCode>503</StatusCode>
		<Reason>Service Unavailable</Reason>
	</ResponseLine>
	<Headers>
		<Header name="Date">Thu%2C%2016%20Sep%202010%2010
			%3A57%3A52%20GMT</Header>
		<Header name="Server">IBM_HTTP_Server</Header>
		<Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header>
		<Header name="Content-Language">en-US</Header>
	</Headers>
	<Cookies>
		<Cookie name="PD-S-SESSION-ID">
			<Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content>
			<Path>/</Path>
			<Domain>domainA.com</Domain>
			<Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires>
			<Secure>1</Secure>
			<HTTPOnly>0</HTTPOnly>
		</Cookie>
	</Cookies>
</HTTPResponse>

XSLT Rules

Note: These rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	version="1.0">

	<!--Firstly, strip any space elements -->
	<xsl:strip-space elements="*" />

	<!--
		Perform a match on the root of the document. Output the required
		HTTPResponseChange elements and then process templates.
	-->
		<xsl:template match="/">
			<HTTPResponseChange>
				<xsl:apply-templates />
			</HTTPResponseChange>
		</xsl:template>

	<!--
		Do nothing to the Version
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/Version" />

	<!--
		If the original StatusCode is 503 then update the
		StatusCode to 501.
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/StatusCode">
		<xsl:choose>
			<xsl:when test="503">
				<StatusCode>501</StatusCode>
			</xsl:when>
		</xsl:choose>
	</xsl:template>

	<!--
		Update the Reason to match the StatusCode change.
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/Reason">
		<xsl:choose>
			<xsl:when test="'Service Unavailable'">
				<Reason>Not Implemented</Reason>
			</xsl:when>
		</xsl:choose>
	</xsl:template>

	<!--
		Do nothing to the Headers.
	-->
	<xsl:template match="//HTTPResponse/Headers" />

<!--
		Do nothing to the Cookies.
	-->
	<xsl:template match="//HTTPResponse/Cookies" />

</xsl:stylesheet>

Output XML document

In this scenario, the following XML document is output from the XSL transformation. This document outlines changes for WebSEAL to perform on the original HTTP response.

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponseChange>
	<StatusCode>501</StatusCode>
	<Reason>Not Implemented</Reason>
</HTTPResponseChange>

Parent topic: Example HTTP transformation scenarios

Scenario 4: Modifying cookies only (HTTPResponse)Scenario 4: Modifying cookies only (HTTPResponse)HTTPResponsemodifying cookiescookiesmodifyingThis scenario illustrates how to add, modify, and remove cookies in an HTTP Response. The XSLT in this example makes the following updates: Adds a cookie called NEW_COOKIE.Updates the EXISTING_COOKIE cookie domain to be domainB.com.Removes the cookie called OLD_COOKIE.Input documentsThe following sample input documents are used for this scenario: HTTP Response<?xml version="1.0" encoding="UTF-8"?> <HTTPResponse> <ResponseLine> <Version>HTTP/1.1</Version> <StatusCode>503</StatusCode> <Reason>Service Unavailable</Reason> </ResponseLine> <Headers> <Header name="Date">Thu%2C%2016%20Sep%202010%2010 %3A57%3A52%20GMT</Header> <Header name="Server">IBM_HTTP_Server</Header> <Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header> <Header name="Content-Language">en-US</Header> </Headers> <Cookies> <Cookie name="EXISTING_COOKIE"> <Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content> <Path>/</Path> <Domain>domainA.com</Domain> <Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires> <Secure>1</Secure> <HTTPOnly>0</HTTPOnly> </Cookie> <Cookie name="OLD_COOKIE"> <Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content> <Path>/</Path> <Domain>domainA.com</Domain> <Expires>Mon, 07 Jun 2021 11:18:21 GMT</Expires> <Secure>1</Secure> <HTTPOnly>0</HTTPOnly> </Cookie> </Cookies> </HTTPResponse>XSLT RulesThese rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!--Firstly, strip any space elements --> <xsl:strip-space elements="*" /> <!-- Perform a match on the root of the document. Output the required HTTPResponseChange elements and then process templates. --> <xsl:template match="/"> <HTTPResponseChange> <xsl:apply-templates /> </HTTPResponseChange> </xsl:template> <!-- Do nothing to the Version --> <xsl:template match="//HTTPResponse/ResponseLine/Version" /> <!-- Do nothing to the StatusCode --> <xsl:template match="//HTTPResponse/ResponseLine/StatusCode" /> <!-- Do nothing to the Reason --> <xsl:template match="//HTTPResponse/ResponseLine/Reason" /> <!-- Do nothing to the Headers. --> <xsl:template match="//HTTPResponse/Headers" /> <!-- Match on the Cookies. Add a new cookie called NEW_COOKIE if it does not exist. --> <xsl:template match="//HTTPResponse/Cookies"> <xsl:choose> <xsl:when test="Cookie/@name=’NEW_COOKIE’" /> <xsl:otherwise> <Cookie action="add" name="NEW_COOKIE"> <Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content> <Path>/</Path> <Domain>domainA.com</Domain> <Expires>Mon, 07 Jun 2021 10:12:14 GMT</Expires> <Secure>1</Secure> <HTTPOnly>0</HTTPOnly> </Cookie> </xsl:otherwise> </xsl:choose> <!-- Update the value of the EXISTING_COOKIE cookie --> <xsl:if test="Cookie/@name='EXISTING_COOKIE'"> <Cookie action="update" name="EXISTING_COOKIE"> <Domain>domainB.com</Domain> </Cookie> </xsl:if> <!-- Delete the OLD_COOKIE cookie --> <xsl:if test="Cookie/@name='OLD_COOKIE'"> <Cookie action="remove" name="OLD_COOKIE" /> </xsl:if> </xsl:template> </xsl:stylesheet>Output XML documentIn this scenario, the following XML document is output from the XSL transformation. This document defines the changes for WebSEAL to perform on the original HTTP response.<?xml version="1.0" encoding="UTF-8"?> <HTTPResponseChange> <Cookie action="add" name="NEW_COOKIE"> <Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content> <Path>/</Path> <Domain>domainA.com</Domain> <Expires>Mon, 07 Jun 2021 10:12:14 GMT</Expires> <Secure>1</Secure> <HTTPOnly>0</HTTPOnly> </Cookie> <Cookie action="update" name="EXISTING_COOKIE"> <Domain>domainB.com</Domain> </Cookie> <Cookie action="remove" name="OLD_COOKIE"></Cookie> </HTTPResponseChange>Example HTTP transformation scenarios

Scenario 4: Modifying cookies only (HTTPResponse)

This scenario illustrates how to add, modify, and remove cookies in an HTTP Response. The XSLT in this example makes the following updates:

Adds a cookie called NEW_COOKIE.

Updates the EXISTING_COOKIE cookie domain to be domainB.com.

Removes the cookie called OLD_COOKIE.

Input documents

The following sample input documents are used for this scenario:

HTTP Response

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponse>
	<ResponseLine>
		<Version>HTTP/1.1</Version>
		<StatusCode>503</StatusCode>
		<Reason>Service Unavailable</Reason>
	</ResponseLine>
	<Headers>
		<Header name="Date">Thu%2C%2016%20Sep%202010%2010
			%3A57%3A52%20GMT</Header>
		<Header name="Server">IBM_HTTP_Server</Header>
		<Header name="Content-Type">text%2Fhtml%3Bcharset%3DUTF-8</Header>
		<Header name="Content-Language">en-US</Header>
	</Headers>
	<Cookies>
		<Cookie name="EXISTING_COOKIE">
			<Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content>
			<Path>/</Path>
			<Domain>domainA.com</Domain>
			<Expires>Wed, 09 Jun 2021 10:18:14 GMT</Expires>
			<Secure>1</Secure>
			<HTTPOnly>0</HTTPOnly>
		</Cookie>
		<Cookie name="OLD_COOKIE">
			<Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content>
			<Path>/</Path>
			<Domain>domainA.com</Domain>
			<Expires>Mon, 07 Jun 2021 11:18:21 GMT</Expires>
			<Secure>1</Secure>
			<HTTPOnly>0</HTTPOnly>
		</Cookie>
	</Cookies>
</HTTPResponse>

XSLT Rules

Note: These rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	version="1.0">

	<!--Firstly, strip any space elements -->
	<xsl:strip-space elements="*" />

	<!--
		Perform a match on the root of the document. Output the required
		HTTPResponseChange elements and then process templates.
	-->
		<xsl:template match="/">
			<HTTPResponseChange>
				<xsl:apply-templates />
			</HTTPResponseChange>
		</xsl:template>

	<!--
		Do nothing to the Version
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/Version" />

	<!--
		Do nothing to the StatusCode
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/StatusCode" />

	<!--
		Do nothing to the Reason
	-->
	<xsl:template match="//HTTPResponse/ResponseLine/Reason" />

	<!--
		Do nothing to the Headers.
	-->
	<xsl:template match="//HTTPResponse/Headers" />

	<!--
		Match on the Cookies. Add a new cookie called NEW_COOKIE if
		it does not exist.
	-->
	<xsl:template match="//HTTPResponse/Cookies">

	<xsl:choose>
		<xsl:when test="Cookie/@name=’NEW_COOKIE’" />
		<xsl:otherwise>
			<Cookie action="add" name="NEW_COOKIE">
				<Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content>
				<Path>/</Path>
				<Domain>domainA.com</Domain>
				<Expires>Mon, 07 Jun 2021 10:12:14 GMT</Expires>
				<Secure>1</Secure>
				<HTTPOnly>0</HTTPOnly>
			</Cookie>
		</xsl:otherwise>
	</xsl:choose>

	<!-- Update the value of the EXISTING_COOKIE cookie -->
	<xsl:if test="Cookie/@name='EXISTING_COOKIE'">
		<Cookie action="update" name="EXISTING_COOKIE">
			<Domain>domainB.com</Domain>
		</Cookie>
	</xsl:if>

	<!-- Delete the OLD_COOKIE cookie -->
	<xsl:if test="Cookie/@name='OLD_COOKIE'">
		<Cookie action="remove" name="OLD_COOKIE" />
	</xsl:if>

	</xsl:template>
</xsl:stylesheet>

Output XML document

In this scenario, the following XML document is output from the XSL transformation. This document defines the changes for WebSEAL to perform on the original HTTP response.

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponseChange>
	<Cookie action="add" name="NEW_COOKIE">
		<Content>2_orQUNJCbjdxqIEdDPMXj31UiHMXuU3hRCUtpN7xe6J1xZhxt0</Content>
		<Path>/</Path>
		<Domain>domainA.com</Domain>
		<Expires>Mon, 07 Jun 2021 10:12:14 GMT</Expires>
		<Secure>1</Secure>
		<HTTPOnly>0</HTTPOnly>
	</Cookie>
	<Cookie action="update" name="EXISTING_COOKIE">
		<Domain>domainB.com</Domain>
	</Cookie>
	<Cookie action="remove" name="OLD_COOKIE"></Cookie>
</HTTPResponseChange>

Parent topic: Example HTTP transformation scenarios

Scenario 5: Providing a response to a known HTTP requestScenario 5: Providing a response to a known HTTP requestThis scenario illustrates how a HTTPResponseChange document can be used to generate a response directly from a request. In this scenario, if a cookie with name 'invalid-cookie' exists in the HTTP Request then the XSL transformation produces an HTTP Response that indicates an invalid cookie was detected.HTTP requestsproviding a responseHTTPResponseChangeInput documentsThe following sample input documents are used for this scenario: HTTP Request<?xml version="1.0" encoding="UTF-8"?> <HTTPRequest> <RequestLine> <Method>GET</Method> <URI>/en/us/</URI> <Scheme>https</Scheme> <Version>HTTP/1.1</Version> </RequestLine> <Headers> <Header name="User-Agent">curl%2F7.18.2%20(i486-pc-linux-gnu)%20libcurl %2F7.18.2%20OpenSSL%2F0.9.8g%20zlib%2F1.2.3.3%20libidn%2F1.8</Header> <Header name="Host">www.ibm.com</Header> <Header name="Accept">*%2F*</Header> </Headers> <Cookies> <Cookie name="invalid-cookie">0</Cookie> </Cookies> </HTTPRequest>XSLT RulesThese rules must be stored in an XSL document that is defined as a request resource with an associated POP. See Configuration. <?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!-- Firstly, strip any space elements --> <xsl:strip-space elements="*" /> <!-- Perform a match on the root of the document. Output the required HTTPRequestChange elements and then process templates. --> <xsl:template match="/"> <HTTPRequestChange /> <xsl:apply-templates /> </xsl:template> <!-- Do nothing with Method --> <xsl:template match="//HTTPRequest/RequestLine/Method" /> <!-- Do nothing with URI --> <xsl:template match="//HTTPRequest/RequestLine/URI"/> <!-- Do nothing with Version --> <xsl:template match="//HTTPRequest/RequestLine/Version" /> <!-- Do nothing with Headers --> <xsl:template match="//HTTPRequest/Headers" /> <!-- Check for the presence of a cookie name 'invalid-cookie' --> <xsl:template match="//HTTPRequest/Cookies/Cookie"> <xsl:choose> <xsl:when test="@name = 'invalid-cookie'"> <HTTPResponseChange action="replace"> <Version>HTTP/1.1</Version> <StatusCode>503</StatusCode> <Reason>Not Implemented</Reason> <Header name="Date" action="add">Thu%2C%2016%20Sep%202010%2010</Header> <Header name="Server" action="add">IBM_HTTP_Server</Header> <Header name="Content-Type" action="add">text%2Fhtml%3Bcharset%3DUTF-8</Header> <Header name="Content-Language" action="add">en-US</Header> <Body>%3Ch1%3EError%3C%2Fh1%3E%0A%3Cp%3EInvalid%20cookie%20%3C%2Fp%3E</Body> </HTTPResponseChange> </xsl:when> </xsl:choose> </xsl:template> </xsl:stylesheet>Output XML documentIn this scenario, the following XML document is output from the XSL transformation. This document defines the response that WebSEAL provides to the original HTTP request.<?xml version="1.0" encoding="UTF-8"?> <HTTPResponseChange action="replace"> <Version>HTTP/1.1</Version> <StatusCode>503</StatusCode> <Reason>Not Implemented<Reason> <Header name="Date" action="add">Thu%2C%2016%20Sep%202010%2010</Header> <Header name="Server" action="add"></Header> <Header name="Content-Type" action="add">text%2Fhtml%3Bcharset%3DUTF-8</Header> <Header name="Content-Language" action="add">en-US</Header> <Body>%3Ch1%3EError%3C%2Fh1%3E%0A%3Cp%3EInvalid%20cookie%20%3C%2Fp%3E</Body> </HTTPResponseChange>Example HTTP transformation scenarios

Scenario 5: Providing a response to a known HTTP request

This scenario illustrates how a HTTPResponseChange document can be used to generate a response directly from a request. In this scenario, if a cookie with name 'invalid-cookie' exists in the HTTP Request then the XSL transformation produces an HTTP Response that indicates an invalid cookie was detected.

Input documents

The following sample input documents are used for this scenario:

HTTP Request

<?xml version="1.0" encoding="UTF-8"?>
<HTTPRequest>
	<RequestLine>
		<Method>GET</Method>
		<URI>/en/us/</URI>
		<Scheme>https</Scheme>
		<Version>HTTP/1.1</Version>
	</RequestLine>
	<Headers>
		<Header name="User-Agent">curl%2F7.18.2%20(i486-pc-linux-gnu)%20libcurl
		%2F7.18.2%20OpenSSL%2F0.9.8g%20zlib%2F1.2.3.3%20libidn%2F1.8</Header>
		<Header name="Host">www.ibm.com</Header>
		<Header name="Accept">*%2F*</Header>
	</Headers>
	<Cookies>
		<Cookie name="invalid-cookie">0</Cookie>
	</Cookies>
</HTTPRequest>

XSLT Rules

Note: These rules must be stored in an XSL document that is defined as a request resource with an associated POP. See Configuration.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	version="1.0">

	<!-- Firstly, strip any space elements -->
	<xsl:strip-space elements="*" />

	<!--
		Perform a match on the root of the document. Output the required
		HTTPRequestChange elements and then process templates.
	-->
	<xsl:template match="/">
		<HTTPRequestChange />
		<xsl:apply-templates />
	</xsl:template>

	<!--
		Do nothing with Method
	-->
	<xsl:template match="//HTTPRequest/RequestLine/Method" />

	<!--
	Do nothing with URI
	-->
	<xsl:template match="//HTTPRequest/RequestLine/URI"/>

	<!--
	Do nothing with Version
	-->
	<xsl:template match="//HTTPRequest/RequestLine/Version" />

	<!--
	Do nothing with Headers
	-->
	<xsl:template match="//HTTPRequest/Headers" />

	<!--
	Check for the presence of a cookie name 'invalid-cookie'
	-->
	<xsl:template match="//HTTPRequest/Cookies/Cookie">
		<xsl:choose>
			<xsl:when test="@name = 'invalid-cookie'">
				<HTTPResponseChange action="replace">
					<Version>HTTP/1.1</Version>
					<StatusCode>503</StatusCode>
					<Reason>Not Implemented</Reason>
					<Header name="Date" action="add">Thu%2C%2016%20Sep%202010%2010</Header>
					<Header name="Server" action="add">IBM_HTTP_Server</Header>
					<Header name="Content-Type" action="add">text%2Fhtml%3Bcharset%3DUTF-8</Header>
					<Header name="Content-Language" action="add">en-US</Header>
					<Body>%3Ch1%3EError%3C%2Fh1%3E%0A%3Cp%3EInvalid%20cookie%20%3C%2Fp%3E</Body>
				</HTTPResponseChange>
			</xsl:when>
		</xsl:choose>
	</xsl:template>

</xsl:stylesheet>

Output XML document

In this scenario, the following XML document is output from the XSL transformation. This document defines the response that WebSEAL provides to the original HTTP request.

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponseChange action="replace">
	<Version>HTTP/1.1</Version>
	<StatusCode>503</StatusCode>
	<Reason>Not Implemented<Reason>
	<Header name="Date" action="add">Thu%2C%2016%20Sep%202010%2010</Header>
	<Header name="Server" action="add"></Header>
	<Header name="Content-Type" action="add">text%2Fhtml%3Bcharset%3DUTF-8</Header>
	<Header name="Content-Language" action="add">en-US</Header>
	<Body>%3Ch1%3EError%3C%2Fh1%3E%0A%3Cp%3EInvalid%20cookie%20%3C%2Fp%3E</Body>
</HTTPResponseChange>

Parent topic: Example HTTP transformation scenarios

Scenario 6: Adding a credential attribute value to the responseThis scenario illustrates how a HTTPResponseChange document can be used to add a credential attribute value to the response.credential attribute valueadding to the responseresponsesadding credential attribute valueInput documentsThe following sample input document is used for this scenario: XSLT RulesThese rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:strip-space elements="*" /> <xsl:template match="/"> <HTTPResponseChange> <xsl:apply-templates /> </HTTPResponseChange> </xsl:template> <xsl:template match="//HTTPResponse/ResponseLine/StatusCode"/> <xsl:template match="//HTTPResponse/ResponseLine/Reason"/> <xsl:template match="//HTTPResponse/ResponseLine/Version"/> <xsl:template match="//HTTPResponse/Credential/Attributes/Attribute"> <xsl:choose> <xsl:when test="contains(@name, 'AZN_CRED_PRINCIPAL_NAME')"> <Header action="add" name="hdr-2"><xsl:value-of select="node()"/></Header> </xsl:when> </xsl:choose> </xsl:template> </xsl:stylesheet> Output XML documentIn this scenario, the following XML document is output from the XSL transformation. This document defines the response that WebSEAL provides to the original HTTP request.<?xml version="1.0" encoding="UTF-8"?> <HTTPResponseChange action="replace"> <Version>HTTP/1.1</Version> <StatusCode>503</StatusCode> <Reason>Not Implemented<Reason> <Header name="principal-name" action="add">testuser</Header> </HTTPResponseChange>Example HTTP transformation scenarios

Scenario 6: Adding a credential attribute value to the response

This scenario illustrates how a HTTPResponseChange document can be used to add a credential attribute value to the response.

Input documents

The following sample input document is used for this scenario:

XSLT Rules

Note: These rules must be stored in an XSL document that is defined as a response resource with an associated POP. See Configuration.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        version="1.0">

  <xsl:strip-space elements="*" />

  <xsl:template match="/">
    <HTTPResponseChange>
      <xsl:apply-templates />
    </HTTPResponseChange>
  </xsl:template>

  <xsl:template match="//HTTPResponse/ResponseLine/StatusCode"/>
  <xsl:template match="//HTTPResponse/ResponseLine/Reason"/>
  <xsl:template match="//HTTPResponse/ResponseLine/Version"/>

  <xsl:template match="//HTTPResponse/Credential/Attributes/Attribute">
    <xsl:choose>
      <xsl:when test="contains(@name, 'AZN_CRED_PRINCIPAL_NAME')">
        <Header action="add" name="hdr-2"><xsl:value-of select="node()"/></Header>
      </xsl:when>
    </xsl:choose>
  </xsl:template>

</xsl:stylesheet>

Output XML document

In this scenario, the following XML document is output from the XSL transformation. This document defines the response that WebSEAL provides to the original HTTP request.

<?xml version="1.0" encoding="UTF-8"?>
<HTTPResponseChange action="replace">
	<Version>HTTP/1.1</Version>
	<StatusCode>503</StatusCode>
	<Reason>Not Implemented<Reason>
	<Header name="principal-name" action="add">testuser</Header>
</HTTPResponseChange>

Parent topic: Example HTTP transformation scenarios

Transformation errorsTransformation errorsTransformation errors in IBM Security Access Manager for WebMost errors are printed in the server log or returned to the browser as an error page.transformationserrorspdweb.http.transformationFor more detailed output, you can use the pdweb.http.transformation component to trace the HTTP transformation processing. This component traces the header information in the request, which might contain sensitive information. For example, a BA header.Invalid rules fileIf an invalid rules file is supplied to WebSEAL as part of the configuration then: The server will fail to start.An appropriate error will be logged.Undefined resourceIf you specify a resource in a POP that is not defined in the WebSEAL configuration file, a warning message will be printed in the server log.HTTP transformation errorIf an error occurs during HTTP transformation processing, a 501 Internal Server Error is returned to the browser.WebSEAL error responsesWebSEAL error responses (not related to HTTP transformation processing) will be transformed if there is an appropriate POP attached to the junction or object that caused the error.HTTP transformationsExtensible Stylesheet Language Transformation (XSLT)HTTP transformation rulesConfigurationExample HTTP transformation scenarios

Transformation errors

Most errors are printed in the server log or returned to the browser as an error page.

Note: For more detailed output, you can use the pdweb.http.transformation component to trace the HTTP transformation processing. This component traces the header information in the request, which might contain sensitive information. For example, a BA header.

Invalid rules file

If an invalid rules file is supplied to WebSEAL as part of the configuration then:

The server will fail to start.

An appropriate error will be logged.

Undefined resource

If you specify a resource in a POP that is not defined in the WebSEAL configuration file, a warning message will be printed in the server log.

HTTP transformation error

If an error occurs during HTTP transformation processing, a 501 Internal Server Error is returned to the browser.

WebSEAL error responses

WebSEAL error responses (not related to HTTP transformation processing) will be transformed if there is an appropriate POP attached to the junction or object that caused the error.

Parent topic: HTTP transformations

Related concepts:

Extensible Stylesheet Language Transformation (XSLT)

HTTP transformation rules

Configuration

Example HTTP transformation scenarios

Microsoft RPC over HTTPMicrosoft RPC over HTTPRPC over HTTPMicrosoft OfficeRPC over HTTPRPC over HTTP is a Microsoft protocol that allows Microsoft Outlook clients to access Microsoft Exchange servers over HTTP. The RPC over HTTP protocol uses one HTTP connection for request data and one HTTP connection for response data. These HTTP connections are long lived. The protocol tunnels multiple requests/responses in a single HTTP request.A typical usage scenario is an Outlook user outside the corporate network who wants to connect to an internal Exchange server. This connection is achieved by accessing a reverse proxy (such as WebSEAL) using HTTP. The HTTP connection is terminated inside the corporate network and a configured IIS relays the RPC commands to the Exchange server. Standard WebSEAL JunctionsRPC over HTTP support in WebSEALJunction configurationPOP configurationAuthentication limitationsTimeout considerationsWebSEAL server log errorsWorker thread consideration

Microsoft RPC over HTTP

RPC over HTTP is a Microsoft protocol that allows Microsoft Outlook clients to access Microsoft Exchange servers over HTTP. The RPC over HTTP protocol uses one HTTP connection for request data and one HTTP connection for response data. These HTTP connections are long lived. The protocol tunnels multiple requests/responses in a single HTTP request.

A typical usage scenario is an Outlook user outside the corporate network who wants to connect to an internal Exchange server. This connection is achieved by accessing a reverse proxy (such as WebSEAL) using HTTP. The HTTP connection is terminated inside the corporate network and a configured IIS relays the RPC commands to the Exchange server.

RPC over HTTP support in WebSEAL

Junction configuration

POP configuration

Authentication limitations

Timeout considerations

WebSEAL server log errors

Worker thread consideration

Parent topic: Standard WebSEAL Junctions

RPC over HTTP support in WebSEALRPC over HTTP support in WebSEALHTTP supportWebSEALRPCWebSEALRPC over HTTP supportWebSEAL can act as the reverse proxy if you are using the RPC over HTTP version 2 protocol. See Microsoft RPC over HTTP supportMicrosoft Remote Procedure Call over HTTP is a protocol that is used to communicate RPC traffic over an HTTP connection. Microsoft Outlook clients use this protocol to access Microsoft Exchange servers over HTTP. .WebSEAL RPC over HTTPWebSEAL acts as a reverse proxy between the Outlook client and the Exchange server.Figure 1 illustrates a typical scenario using the RPC over HTTP protocol.Microsoft Outlook makes an RPC_IN_DATA request to WebSEAL. The request contains the user name and password in a BA Header.WebSEAL authenticates and authorizes the request. WebSEAL passes the request (including the BA header) to Microsoft Exchange.Outlook makes an RPC_OUT_DATA request to WebSEAL. The request contains the user name and password in a BA Header.WebSEAL authenticates and authorizes the request. WebSEAL passes the request (including the BA header) to Exchange.Exchange sends a 200 OK response back to WebSEAL.WebSEAL forwards the response back to Outlook.Outlook sends RPC data to Exchange via WebSEAL on the RPC_IN_DATA connection.Exchange sends RPC data to Outlook via WebSEAL on the RPC_OUT_DATA connection.Microsoft RPC over HTTPJunction configurationPOP configurationAuthentication limitationsTimeout considerationsWebSEAL server log errorsWorker thread consideration

RPC over HTTP support in WebSEAL

WebSEAL can act as the reverse proxy if you are using the RPC over HTTP version 2 protocol. See Microsoft RPC over HTTP support.

Figure 38. WebSEAL RPC over HTTP

Figure 38. illustrates a typical scenario using the RPC over HTTP protocol.

Microsoft Outlook makes an RPC_IN_DATA request to WebSEAL. The request contains the user name and password in a BA Header.

WebSEAL authenticates and authorizes the request. WebSEAL passes the request (including the BA header) to Microsoft Exchange.

Outlook makes an RPC_OUT_DATA request to WebSEAL. The request contains the user name and password in a BA Header.

WebSEAL authenticates and authorizes the request. WebSEAL passes the request (including the BA header) to Exchange.

Exchange sends a 200 OK response back to WebSEAL.

WebSEAL forwards the response back to Outlook.

Outlook sends RPC data to Exchange via WebSEAL on the RPC_IN_DATA connection.

Exchange sends RPC data to Outlook via WebSEAL on the RPC_OUT_DATA connection.

Parent topic: Microsoft RPC over HTTP

Related concepts:

Junction configuration

POP configuration

Authentication limitations

Timeout considerations

WebSEAL server log errors

Worker thread consideration

Junction configurationJunction configurationjunctionsconfigurationTo use WebSEAL as a reverse proxy for RPC over HTTP requests between Outlook and Exchange, you must use a transparent path junction or a virtual host junction. When issuing an RPC over HTTP request, the Outlook client tries to access the URI /rpc/rpcproxy.dll on the junctioned IIS server that is configured to communicate with the Exchange server.To authenticate the user to WebSEAL and the Exchange server, you must use the -b ignore parameter when creating the junction. This parameter ensures that the BA header used by WebSEAL for authentication is also used to authenticate to the IIS server that communicates with the Exchange server. For more details, see Authentication limitations.You must use an SSL junction for this configuration; Outlook does not support HTTP when using BA authentication.Transparent path junctionsThe following command illustrates how to create a transparent path junction: server task instance_name-webseald-host_name create -t ssl -h exchange_host -p exchange_port -b ignore -x /rpcwhere:instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.exchange_hostSpecifies the DNS host name or IP address of the Exchange server.exchange_portSpecifies the TCP port of the Exchange server. The default value is 80 for TCP junctions and 443 for SSL junctions. Virtual host junctionsThe following command illustrates how to create a virtual host junction: server task instance_name-webseald-host_name virtualhost create -t ssl -h exchange_host -p exchange_port -v virtual_host -b ignore exchangewhere:instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.exchange_hostSpecifies the DNS host name or IP address of the Exchange server.exchange_portSpecifies the TCP port of the Exchange server. The default value is 80 for TCP junctions and 443 for SSL junctions. virtual_hostSpecifies the value of the Host header of the request sent to the Exchange server.Microsoft RPC over HTTPRPC over HTTP support in WebSEALPOP configurationAuthentication limitationsTimeout considerationsWebSEAL server log errorsWorker thread consideration

Junction configuration

To use WebSEAL as a reverse proxy for RPC over HTTP requests between Outlook and Exchange, you must use a transparent path junction or a virtual host junction. When issuing an RPC over HTTP request, the Outlook client tries to access the URI /rpc/rpcproxy.dll on the junctioned IIS server that is configured to communicate with the Exchange server.

To authenticate the user to WebSEAL and the Exchange server, you must use the -b ignore parameter when creating the junction. This parameter ensures that the BA header used by WebSEAL for authentication is also used to authenticate to the IIS server that communicates with the Exchange server. For more details, see Authentication limitations.

You must use an SSL junction for this configuration; Outlook does not support HTTP when using BA authentication.

Transparent path junctions

The following command illustrates how to create a transparent path junction:

server task instance_name-webseald-host_name create -t ssl
-h exchange_host -p exchange_port -b ignore -x /rpc

where:

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

exchange_host

Specifies the DNS host name or IP address of the Exchange server.

exchange_port

Specifies the TCP port of the Exchange server. The default value is 80 for TCP junctions and 443 for SSL junctions.

Virtual host junctions

The following command illustrates how to create a virtual host junction:

server task instance_name-webseald-host_name virtualhost create -t ssl
-h exchange_host -p exchange_port -v virtual_host -b ignore exchange

where:

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

exchange_host

Specifies the DNS host name or IP address of the Exchange server.

exchange_port

Specifies the TCP port of the Exchange server. The default value is 80 for TCP junctions and 443 for SSL junctions.

virtual_host

Specifies the value of the Host header of the request sent to the Exchange server.

Parent topic: Microsoft RPC over HTTP

Related concepts:

RPC over HTTP support in WebSEAL

POP configuration

Authentication limitations

Timeout considerations

WebSEAL server log errors

Worker thread consideration

POP configurationPOP configurationPOPconfigurationYou must configure a POP to control request and response streaming on the junction used for communication between Outlook and Exchange: Create a POP that sets the response-buffer-control and request-buffer-control attributes to bypass. For example:pdadmin> pop create streaming pdadmin> pop modify streaming set attribute response-buffer-control bypass pdadmin> pop modify streaming set attribute request-buffer-control bypassAttach this POP to the junction that you are using for the RPC over HTTP communication. Transparent Path Junction example:pdadmin> pop attach /WebSEAL/webseal-server/rpc streamingVirtual Host Junction example:pdadmin> pop attach /WebSEAL/webseal-server/@exchange streaming For details, see Bypassing buffering on a per-resource basisWebSEAL uses an internal buffer when processing data sent in requests to WebSEAL and responses from junction applications..Microsoft RPC over HTTPRPC over HTTP support in WebSEALJunction configurationAuthentication limitationsTimeout considerationsWebSEAL server log errorsWorker thread consideration

POP configuration

You must configure a POP to control request and response streaming on the junction used for communication between Outlook and Exchange:

Create a POP that sets the response-buffer-control and request-buffer-control attributes to bypass. For example:

pdadmin> pop create streaming
pdadmin> pop modify streaming set attribute response-buffer-control bypass
pdadmin> pop modify streaming set attribute request-buffer-control bypass

Attach this POP to the junction that you are using for the RPC over HTTP communication.

Transparent Path Junction example:

pdadmin> pop attach /WebSEAL/webseal-server/rpc streaming

Virtual Host Junction example:

pdadmin> pop attach /WebSEAL/webseal-server/@exchange streaming

For details, see Bypassing buffering on a per-resource basis.

Parent topic: Microsoft RPC over HTTP

Related concepts:

RPC over HTTP support in WebSEAL

Junction configuration

Authentication limitations

Timeout considerations

WebSEAL server log errors

Worker thread consideration

Authentication limitationsAuthentication limitationsauthenticationlimitationslimitationsauthenticationThe credentials presented to WebSEAL by Outlook are used in the RPC data and the authentication to Exchange. The WebSEAL user credentials must match the AD credentials for Exchange.You must configure the WebSEAL server to connect to Exchange using a BA header over HTTPS. The value for ba-auth in the [ba] stanza must be set to https.ba-auth = httpsThe BA credentials for the user must be passed through the junction to the Exchange server. Specify the -b ignore option when creating the junction Microsoft NT LAN Manager (NTLM) authentication is not supported.The /RpcWithCert endpoint is not supported. It expects client certificate authentication. WebSEAL cannot authenticate using a client certificate for the configured junction.Microsoft RPC over HTTPRPC over HTTP support in WebSEALJunction configurationPOP configurationTimeout considerationsWebSEAL server log errorsWorker thread consideration

Authentication limitations

The credentials presented to WebSEAL by Outlook are used in the RPC data and the authentication to Exchange. The WebSEAL user credentials must match the AD credentials for Exchange.

You must configure the WebSEAL server to connect to Exchange using a BA header over HTTPS. The value for ba-auth in the [ba] stanza must be set to https.

ba-auth = https

The BA credentials for the user must be passed through the junction to the Exchange server. Specify the -b ignore option when creating the junction

Note:

Microsoft NT LAN Manager (NTLM) authentication is not supported.

The /RpcWithCert endpoint is not supported. It expects client certificate authentication. WebSEAL cannot authenticate using a client certificate for the configured junction.

Parent topic: Microsoft RPC over HTTP

Related concepts:

RPC over HTTP support in WebSEAL

Junction configuration

POP configuration

Timeout considerations

WebSEAL server log errors

Worker thread consideration

Timeout considerationsTimeout considerationstimeoutconsiderationWhen you configure WebSEAL as a reverse proxy for RPC over HTTP requests, set the following values in the [server] stanza of the WebSEAL configuration file:client-connect-timeoutintra-connection-timeoutThese timeout configuration entries affect the Outlook client connection. To keep the connection open longer for data streaming, use large timeout values. For example:[server] client-connect-timeout = 36000 intra-connection-timeout = 36000When these timeout limits are reached, the Outlook client renegotiates a connection to the Exchange server. Microsoft RPC over HTTPRPC over HTTP support in WebSEALJunction configurationPOP configurationAuthentication limitationsWebSEAL server log errorsWorker thread consideration

Timeout considerations

When you configure WebSEAL as a reverse proxy for RPC over HTTP requests, set the following values in the [server] stanza of the WebSEAL configuration file:

client-connect-timeout

intra-connection-timeout

These timeout configuration entries affect the Outlook client connection. To keep the connection open longer for data streaming, use large timeout values. For example:

[server]
client-connect-timeout = 36000
intra-connection-timeout = 36000

When these timeout limits are reached, the Outlook client renegotiates a connection to the Exchange server.

Parent topic: Microsoft RPC over HTTP

Related concepts:

RPC over HTTP support in WebSEAL

Junction configuration

POP configuration

Authentication limitations

WebSEAL server log errors

Worker thread consideration

WebSEAL server log errorsWebSEAL server log errorsWebSEAL serverslog errorsloggingstanzaserver-log stanza entryserver-log-cfg stanza entrySSLstanzasuppress-client-ssl-errors stanza entry (ssl stanza)server-log stanza entry (logging stanza)server-log-cfg stanza entry (logging stanza)Due to the nature of RPC over HTTP, socket errors might be printed in the WebSEAL server log. The server-log-cfg configuration entry in the [logging] stanza specifies the logging agent configuration.For example:2010-10-26-05:45:25.836+10:00I----- 0x38AD5424 webseald ERROR wiv socket WsSslListener.cpp 1737 0xafb3fb90 DPWIV1060E Could not read from socket (406) 2010-10-26-05:45:25.838+10:00I----- 0x38AD5425 webseald ERROR wiv socket WsSslListener.cpp 1658 0xafb3fb90 DPWIV1061E Could not write to socket (406)These error messages are expected when request/response streaming is active and the connection is closed before the full content-length has been received. You can turn off these error messages by setting the suppress-client-ssl-errors in the [ssl] stanza of the WebSEAL configuration file to true. See Specifying the WebSEAL host nameTypically, the name of the WebSEAL host computer is automatically determined when this information is required. There are situations, such as with virtual host junctions, where the WebSEAL host can use several names. On systems with many host names, interfaces, or WebSEAL instances, the automatic determination might not be correct for a specific situation. You can specify the correct one. for details about the location of this configuration file.Microsoft RPC over HTTPRPC over HTTP support in WebSEALJunction configurationPOP configurationAuthentication limitationsTimeout considerationsWorker thread consideration

WebSEAL server log errors

Due to the nature of RPC over HTTP, socket errors might be printed in the WebSEAL server log.

Note: The server-log-cfg configuration entry in the [logging] stanza specifies the logging agent configuration.

For example:

2010-10-26-05:45:25.836+10:00I----- 0x38AD5424 webseald ERROR wiv socket
WsSslListener.cpp 1737 0xafb3fb90
DPWIV1060E   Could not read from socket (406)
2010-10-26-05:45:25.838+10:00I----- 0x38AD5425 webseald ERROR wiv socket
WsSslListener.cpp 1658 0xafb3fb90
DPWIV1061E   Could not write to socket (406)

These error messages are expected when request/response streaming is active and the connection is closed before the full content-length has been received.

You can turn off these error messages by setting the suppress-client-ssl-errors in the [ssl] stanza of the WebSEAL configuration file to true. See Specifying the WebSEAL host name for details about the location of this configuration file.

Parent topic: Microsoft RPC over HTTP

Related concepts:

RPC over HTTP support in WebSEAL

Junction configuration

POP configuration

Authentication limitations

Timeout considerations

Worker thread consideration

Worker thread considerationWorker thread considerationworker threadsconsiderationMicrosoft Outlook creates multiple HTTP connections when communicating with Microsoft Exchange using RPC over HTTP. Each Outlook client connection uses multiple worker threads in WebSEAL. The number of worker threads that each Outlook client uses in WebSEAL can exceed 10. These threads are held for the length of time that the Outlook client remains connected to the Exchange server. The use of numerous worker threads for every RPC over HTTP client connection via WebSEAL can lead to worker thread starvation. WebSEAL has a limited number of worker threads available. Limited threads limits the number of clients that can access WebSEAL at any point in time. When deploying WebSEAL for use with RPC over HTTP in an Outlook and Exchange environment, consider the number of worker threads being used. Microsoft RPC over HTTPRPC over HTTP support in WebSEALJunction configurationPOP configurationAuthentication limitationsTimeout considerationsWebSEAL server log errors

Worker thread consideration

Microsoft Outlook creates multiple HTTP connections when communicating with Microsoft Exchange using RPC over HTTP. Each Outlook client connection uses multiple worker threads in WebSEAL. The number of worker threads that each Outlook client uses in WebSEAL can exceed 10. These threads are held for the length of time that the Outlook client remains connected to the Exchange server. The use of numerous worker threads for every RPC over HTTP client connection via WebSEAL can lead to worker thread starvation.

WebSEAL has a limited number of worker threads available. Limited threads limits the number of clients that can access WebSEAL at any point in time. When deploying WebSEAL for use with RPC over HTTP in an Outlook and Exchange environment, consider the number of worker threads being used.

Parent topic: Microsoft RPC over HTTP

Related concepts:

RPC over HTTP support in WebSEAL

Junction configuration

POP configuration

Authentication limitations

Timeout considerations

WebSEAL server log errors

Command option summary: standard junctionsCommand option summary: standard junctionscommand option summarystandard junctionsstandard junctionscommand option summaryjunctionscommand option referencereferenceThe pdadmin utility provides an interactive command-line prompt from which you can perform WebSEAL junction tasks. This section describes the pdadmin server task command for creating standard WebSEAL junctions. See the Web command reference topics for complete syntax information for the pdadmin utility. Standard WebSEAL JunctionsUsing pdadmin server task to create junctionsServer task commands for junctionsCreation of a junction for an initial serverYou can create a new junction with the create command.Addition of server to an existing junction

Command option summary: standard junctions

The pdadmin utility provides an interactive command-line prompt from which you can perform WebSEAL junction tasks. This section describes the pdadmin server task command for creating standard WebSEAL junctions. See the Web command reference topics for complete syntax information for the pdadmin utility.

Using pdadmin server task to create junctions

Server task commands for junctions

Creation of a junction for an initial server
You can create a new junction with the create command.

Addition of server to an existing junction

Parent topic: Standard WebSEAL Junctions

Using pdadmin server task to create junctionsUsing pdadmin server task to create junctionspdadmin server taskcreatingpdadmin server listjunctionspdadmin server taskBefore using pdadmin, you must login to a secure domain as a user with administration authorization, such as sec_master. For example: pdadmin> login Enter User ID: sec_master Enter Password: pdadmin>To create WebSEAL junctions, you use the pdadmin server task create command:pdadmin> server task instance_name-webseald-host_name create optionsFor example, if the configured name of a single WebSEAL instance is web1 , installed on a host named www.pubs.com, the complete server name would be expressed as follows:web1-webseald-www.pubs.comUse the pdadmin server list command to display the correct format of the complete server name:pdadmin> server list web1-webseald-www.pubs.comFor more information, see the reference page for pdadmin server task create in Command reference or the Web command reference topics.Command option summary: standard junctionsServer task commands for junctionsCreation of a junction for an initial serverYou can create a new junction with the create command.Addition of server to an existing junction

Using pdadmin server task to create junctions

Before you begin

Before using pdadmin, you must login to a secure domain as a user with administration authorization, such as sec_master.

For example:

pdadmin> login
Enter User ID: sec_master
Enter Password:
pdadmin>

Procedure

To create WebSEAL junctions, you use the pdadmin server task create command:

pdadmin> server task instance_name-webseald-host_name create options

For example, if the configured name of a single WebSEAL instance is web1 , installed on a host named www.pubs.com, the complete server name would be expressed as follows:

web1-webseald-www.pubs.com

Use the pdadmin server list command to display the correct format of the complete server name:

pdadmin> server list
web1-webseald-www.pubs.com

For more information, see the reference page for pdadmin server task create in Command reference or the Web command reference topics.

Parent topic: Command option summary: standard junctions

Related concepts:

Creation of a junction for an initial server

Addition of server to an existing junction

Related reference:

Server task commands for junctions

Server task commands for junctionsServer task commands for junctionsWebSEAL server task commands for junctionspdadmin server taskaddingremovingdeletinglistingshowingjmt clearofflineonlinecreatingthrottleThe following junction commands are available with pdadmin server task: CommandDescriptionadd Add an additional server to an existing junction point. Syntax: add -h host-name options junction-point See Addition of server to an existing junction.create Create a new junction for an initial server. Syntax: create -t type -h host-name options junction-point See Creation of a junction for an initial serverYou can create a new junction with the create command..delete Remove the specified junction point. Syntax: delete junction-point jmt load jmt clear The jmt load command provides WebSEAL with junction mapping table data (jmt.conf) to handle processing of dynamically generated server-relative URLs. The jmt clear command removes junction mapping table data from WebSEAL.list List all configured junction points on this server. Syntax: listoffline Places the server located at this junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, then all servers located at this junction are placed in an offline operational state. Syntax: offline [-i server_uuid] junction_pointonline Places the server located at this junction in an online operational state. The server now resumes normal operation. If a server is not specified, then all servers located at this junction are placed in an online operational state. Syntax: online [-i server_uuid] junction_pointremove Remove the specified server from a junction point. Syntax: remove –i server-id junction-point Use the show command to determine the ID of a particular server.show Display the details of a junction. Syntax: show junction-pointthrottle Places the server located at this junction in a throttled operational state. While in this state, only requests from pre-established user sessions are processed. If a server is not specified, then all servers located at this junction are placed in a throttled operational state. Syntax: throttle [-i server_uuid] junction_pointCommand option summary: standard junctionsUsing pdadmin server task to create junctionsCreation of a junction for an initial serverYou can create a new junction with the create command.Addition of server to an existing junction

Server task commands for junctions

The following junction commands are available with pdadmin server task:

Command
Description

add

Add an additional server to an existing junction point.

Syntax:

add -h host-name options junction-point

See Addition of server to an existing junction.

create

Create a new junction for an initial server.

Syntax:

create -t type -h host-name options junction-point

See Creation of a junction for an initial server.

delete

Remove the specified junction point.

Syntax:

delete junction-point

jmt load

jmt clear

The jmt load command provides WebSEAL with junction mapping table data (jmt.conf) to handle processing of dynamically generated server-relative URLs.

The jmt clear command removes junction mapping table data from WebSEAL.

list

List all configured junction points on this server.

Syntax:

list

offline

Places the server located at this junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, then all servers located at this junction are placed in an offline operational state.

Syntax:

offline [-i server_uuid] junction_point

online

Places the server located at this junction in an online operational state. The server now resumes normal operation. If a server is not specified, then all servers located at this junction are placed in an online operational state.

Syntax:

online [-i server_uuid] junction_point

remove

Remove the specified server from a junction point.

Syntax:

remove –i server-id junction-point

Use the show command to determine the ID of a particular server.

show

Display the details of a junction.

Syntax:

show junction-point

throttle

Places the server located at this junction in a throttled operational state. While in this state, only requests from pre-established user sessions are processed. If a server is not specified, then all servers located at this junction are placed in a throttled operational state.

Syntax:

throttle [-i server_uuid] junction_point

Parent topic: Command option summary: standard junctions

Related concepts:

Creation of a junction for an initial server

Addition of server to an existing junction

Related tasks:

Using pdadmin server task to create junctions

Creation of a junction for an initial serverCreation of a junction for an initial serverYou can create a new junction with the create command.junctionscreating for an initial serverOperation: Creates a new junction point and junctions an initial server.Syntax:create -t type -h host-name options junction-point–t typeType of junction. One of: tcp, ssl, tcpproxy,sslproxy, local, mutual. This parameter is required. Default port for –t tcp is 80. Default port for –t ssl is 443.–h host-nameThe DNS host name or IP address of the target back-end server. This parameter is required. optionsSee Table 1.junction-pointThe name of the junction point. This parameter is required. See Standard WebSEAL junction configuration.Options on the create command for creating junctionsJunction typeParameterDescriptionStandard junction types–a addressSpecifies the local IP address that WebSEAL uses when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system. If you supply an address for a particular junction, WebSEAL will be modified to bind to this local address for all communication with the junctioned server.Standard junction types–fForces the replacement of an existing junction. See Forcing a new junction.Standard junction types–iWebSEAL server treats URLs as case insensitive. See Support for URLs as not case-sensitive.Standard junction types–q locationProvides WebSEAL with the correct name of the query_contents program file and where to find the file. By default, the Windows file is called query_contents.exe and the UNIX file is called query_contents.sh. By default, WebSEAL looks for the file in the cgi_bin directory of the back-end Web server. Required for back-end Windows and UNIX Web servers. See Installing and configuring query_contents on Windows-based Web serversThe following steps describe the installation of query_contents on back-end Windows-based Web servers..Standard junction types–T resource/resource-groupName of GSO resource or resource group. Required for and used only with –b gso option. See Configuring a GSO-enabled WebSEAL junctionUse the create command with the –b gso option to create a junction that enables GSO. .Standard junction types–wWindows filesystem support. See Junctions to Windows file systems.TCP and SSL junction types–p portTCP port of the back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions. See Creating TCP type standard junctions and Creating SSL type standard junctions.Stateful junctionsSee Stateful junctions.–sSpecifies that the junction should support stateful applications. By default, junctions are not stateful.Stateful junctionsSee Stateful junctions.–u UUIDSpecifies the UUID of a back-end server connected to WebSEAL using a stateful junction (–s).Mutual junctionsSee Stateful junctions.–p HTTP portHTTP port of the back-end third-party server. See Creating mutual junctions.Mutual junctionsSee Stateful junctions.–P HTTPS portHTTPS port of the back-end third-party server. See Creating mutual junctions.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–BWebSEAL uses BA header information to authenticate to back-end server. Requires –U, and –W options.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–D "DN"Specifies the distinguished name of back-end server certificate. This value, matched with actual certificate DN enhances authentication.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–K "key-label"Key label of WebSEAL's client-side certificate, used to authenticate to back-end server.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–U "username"WebSEAL user name. Use with –B to send BA header information to back-end server.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–W "password"WebSEAL password. Use with –B to send BA header information to back-end server.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–H host-nameThe DNS host name or IP address of the proxy server.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–P portThe TCP port of the proxy server.Supply identity information in HTTP headers–b BA-valueDefines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the back-end server. One of: filter (default), ignore, supply, gso See Client identity in HTTP BA headersYou can configure WebSEAL junctions to supply the back-end server with original or modified client identity information. Understand the options available so that you can specify the required information in the HTTP basic authentication headers..Supply identity information in HTTP headers–c header-typesInserts client identity information specific to Security Access Manager in HTTP headers across the junction. The header-types argument can include any combination of the following Access Manager HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all. See Client identity in HTTP headers (–c)Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers..Supply identity information in HTTP headers–e encoding-typeSpecifies the encoding to use when generating HTTP headers for junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. Possible values for encoding are: utf8_binutf8_urilcp_binlcp_uri See UTF-8 encoding for HTTP header data.Supply identity information in HTTP headers–ICookie handling: -I ensures unique Set-Cookie header name attribute. See Cookie handling: -I ensures unique Set-Cookie name attribute.Supply identity information in HTTP headers–jSupplies junction identification in a cookie to handle script generated server-relative URLs. See Modification of server-relative URLs with junction cookies.Supply identity information in HTTP headers–J {trailer,inhead, onfocus,xhtml10}Controls the junction cookie JavaScript block. Use –J trailer to append (rather than prepend) the junction cookie JavaScript to HTML page returned from back-end server. Use –J inhead to insert the JavaScript block between <head> </head> tags for HTML 4.01 compliance. Use –J onfocus to use the onfocus event handler in the JavaScript to ensure the correct junction cookie is used in a multiple-junction/multiple-browser-window scenario. Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and XHTML 1.0 compliant. For complete details on this option, see Control on the junction cookie JavaScript block.Supply identity information in HTTP headers–kSends session cookie to back-end portal server. See Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. .Supply identity information in HTTP headers–nSpecifies that no modification of the names of non-domain cookies are to be made. Use when client-side scripts depend on the names of cookies. By default, if a junction is listed in the JMT or if the -j junction option is used, WebSEAL prepends the names of non-domain cookies that are returned from the junction to with: AMWEBJCT_junction_point_ See Preservation of cookie names.Supply identity information in HTTP headers–rInserts incoming IP address in HTTP header across the junction. See Client IP addresses in HTTP headers (–r).Junction fairnessSee Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis..–l percent-valueDefines the soft limit for consumption of worker threads.Junction fairnessSee Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis..–L percent-valueDefines the hard limit for consumption of worker threads.WebSphere single signon (LTPA) junctionsSee LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA)..–AEnables junctions to support LTPA cookies (tokens). LTPA version 1 cookies (LtpaToken) and LTPA version 2 cookies (LtpaToken2) are both supported. LTPA version 1 cookies are specified by default. LTPA version 2 cookies must be specified with the additional -2 option. Also requires –F, and –Z options.WebSphere single signon (LTPA) junctionsSee LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA)..–2Used with the -A option, this option specifies that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.WebSphere single signon (LTPA) junctionsSee LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA)..–F "keyfile"Name of the key file used to encrypt LTPA cookie data. Only valid with -A option.WebSphere single signon (LTPA) junctionsSee LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA)..–Z "keyfile-password"Password for the key file used to encrypt LTPA cookie data. Only valid with -A option.Tivoli Federated Identity Manager SSO junctionsSingle signon with Tivoli Federated Identity ManagerUnderstand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.-YEnables Tivoli Federated Identity Manager single-signon (SSO) for the junction. NOTE: Before using this option, you must first configure the WebSEAL configuration files to support Tivoli Federated Identity Manager single-signon over junctions.WebSEAL-to-WebSEAL SSL junctionsSee WebSEAL-to-WebSEAL junctions over SSL.–CMutual authentication between a front-end WebSEAL server and a back-end WebSEAL server over SSL. Requires –t ssl or –t sslproxy type.Forms single signonSee Forms single sign-on conceptsForms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL..–S file_nameName of the forms single signon configuration file.Virtual hostsSee Standard junctions to virtual hosts.–v virtual-host-name[:HTTP-port]Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. For mutual junctions this value corresponds to the virtual host which is used for HTTP requests. You use –V when the back-end junction server expects a Host header because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.Virtual hostsSee Standard junctions to virtual hosts.–V virtual-host-name[:HTTPS-port]Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. The value corresponds to the virtual host which is used for HTTPS requests. Only used for mutual junctions. You use –V when the back-end junction server expects a Host header because you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.Transparent junctionsSee Transparent path junctions.–xCreates a transparent path junction.Command option summary: standard junctionsUsing pdadmin server task to create junctionsServer task commands for junctionsAddition of server to an existing junction

Creation of a junction for an initial server

You can create a new junction with the create command.

Operation: Creates a new junction point and junctions an initial server.

Syntax:

create -t type -h host-name options junction-point

–t type

Type of junction. One of: tcp, ssl, tcpproxy,sslproxy, local, mutual. This parameter is required.

Default port for –t tcp is 80. Default port for –t ssl is 443.

–h host-name

The DNS host name or IP address of the target back-end server. This parameter is required.

options

See Table 64.

junction-point

The name of the junction point. This parameter is required.

See Standard WebSEAL junction configuration.

Table 64. Options on the create command for creating junctions

Junction type
Parameter
Description

Standard junction types

–a address

Specifies the local IP address that WebSEAL uses when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system.

If you supply an address for a particular junction, WebSEAL will be modified to bind to this local address for all communication with the junctioned server.

Standard junction types

–f

Forces the replacement of an existing junction.

See Forcing a new junction.

Standard junction types

–i

WebSEAL server treats URLs as case insensitive.

See Support for URLs as not case-sensitive.

Standard junction types

–q location

Provides WebSEAL with the correct name of the query_contents program file and where to find the file. By default, the Windows file is called query_contents.exe and the UNIX file is called query_contents.sh. By default, WebSEAL looks for the file in the cgi_bin directory of the back-end Web server.

Required for back-end Windows and UNIX Web servers.

See Installing and configuring query_contents on Windows-based Web servers.

Standard junction types

–T resource/resource-group

Name of GSO resource or resource group. Required for and used only with –b gso option.

See Configuring a GSO-enabled WebSEAL junction.

Standard junction types

–w

Windows filesystem support.

See Junctions to Windows file systems.

TCP and SSL junction types

–p port

TCP port of the back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions.

See Creating TCP type standard junctions and Creating SSL type standard junctions.

Stateful junctions

See Stateful junctions.

–s

Specifies that the junction should support stateful applications. By default, junctions are not stateful.

Stateful junctions

See Stateful junctions.

–u UUID

Specifies the UUID of a back-end server connected to WebSEAL using a stateful junction (–s).

Mutual junctions

See Stateful junctions.

–p HTTP port

HTTP port of the back-end third-party server.

See Creating mutual junctions.

Mutual junctions

See Stateful junctions.

–P HTTPS port

HTTPS port of the back-end third-party server.

See Creating mutual junctions.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–B

WebSEAL uses BA header information to authenticate to back-end server. Requires –U, and –W options.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–D "DN"

Specifies the distinguished name of back-end server certificate. This value, matched with actual certificate DN enhances authentication.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–K "key-label"

Key label of WebSEAL's client-side certificate, used to authenticate to back-end server.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–U "username"

WebSEAL user name. Use with –B to send BA header information to back-end server.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–W "password"

WebSEAL password. Use with –B to send BA header information to back-end server.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–H host-name

The DNS host name or IP address of the proxy server.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–P port

The TCP port of the proxy server.

Supply identity information in HTTP headers

–b BA-value

Defines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the back-end server. One of:

filter (default), ignore, supply, gso

See Client identity in HTTP BA headers.

Supply identity information in HTTP headers

–c header-types

Inserts client identity information specific to Security Access Manager in HTTP headers across the junction. The header-types argument can include any combination of the following Access Manager HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all.

See Client identity in HTTP headers (–c).

Supply identity information in HTTP headers

–e encoding-type

Specifies the encoding to use when generating HTTP headers for junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. Possible values for encoding are:

utf8_bin

utf8_uri

lcp_bin

lcp_uri

See UTF-8 encoding for HTTP header data.

Supply identity information in HTTP headers

–I

Cookie handling: -I ensures unique Set-Cookie header name attribute.

See Cookie handling: -I ensures unique Set-Cookie name attribute.

Supply identity information in HTTP headers

–j

Supplies junction identification in a cookie to handle script generated server-relative URLs.

See Modification of server-relative URLs with junction cookies.

Supply identity information in HTTP headers

–J {trailer,inhead, onfocus,xhtml10}

Controls the junction cookie JavaScript block.

Use –J trailer to append (rather than prepend) the junction cookie JavaScript to HTML page returned from back-end server.

Use –J inhead to insert the JavaScript block between <head> </head> tags for HTML 4.01 compliance.

Use –J onfocus to use the onfocus event handler in the JavaScript to ensure the correct junction cookie is used in a multiple-junction/multiple-browser-window scenario.

Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and XHTML 1.0 compliant.

For complete details on this option, see Control on the junction cookie JavaScript block.

Supply identity information in HTTP headers

–k

Sends session cookie to back-end portal server.

See Passing of session cookies to junctioned portal servers.

Supply identity information in HTTP headers

–n

Specifies that no modification of the names of non-domain cookies are to be made. Use when client-side scripts depend on the names of cookies.

By default, if a junction is listed in the JMT or if the -j junction option is used, WebSEAL prepends the names of non-domain cookies that are returned from the junction to with: AMWEBJCT_junction_point_

See Preservation of cookie names.

Supply identity information in HTTP headers

–r

Inserts incoming IP address in HTTP header across the junction.

See Client IP addresses in HTTP headers (–r).

Junction fairness

See Per-junction allocation of worker threads for junctions.

–l percent-value

Defines the soft limit for consumption of worker threads.

Junction fairness

See Per-junction allocation of worker threads for junctions.

–L percent-value

Defines the hard limit for consumption of worker threads.

WebSphere single signon (LTPA) junctions

See LTPA overview.

–A

Enables junctions to support LTPA cookies (tokens). LTPA version 1 cookies (LtpaToken) and LTPA version 2 cookies (LtpaToken2) are both supported. LTPA version 1 cookies are specified by default. LTPA version 2 cookies must be specified with the additional -2 option.

Also requires –F, and –Z options.

WebSphere single signon (LTPA) junctions

See LTPA overview.

–2

Used with the -A option, this option specifies that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

WebSphere single signon (LTPA) junctions

See LTPA overview.

–F "keyfile"

Name of the key file used to encrypt LTPA cookie data. Only valid with -A option.

WebSphere single signon (LTPA) junctions

See LTPA overview.

–Z "keyfile-password"

Password for the key file used to encrypt LTPA cookie data. Only valid with -A option.

Tivoli Federated Identity Manager SSO junctions

Single signon with Tivoli Federated Identity Manager

-Y

Enables Tivoli® Federated Identity Manager single-signon (SSO) for the junction.

NOTE: Before using this option, you must first configure the WebSEAL configuration files to support Tivoli Federated Identity Manager single-signon over junctions.

WebSEAL-to-WebSEAL SSL junctions

See WebSEAL-to-WebSEAL junctions over SSL.

–C

Mutual authentication between a front-end WebSEAL server and a back-end WebSEAL server over SSL. Requires –t ssl or –t sslproxy type.

Forms single signon

See Forms single sign-on concepts.

–S file_name

Name of the forms single signon configuration file.

Virtual hosts

See Standard junctions to virtual hosts.

–v virtual-host-name[:HTTP-port]

Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. For mutual junctions this value corresponds to the virtual host which is used for HTTP requests.

You use –V when the back-end junction server expects a Host header because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.

Virtual hosts

See Standard junctions to virtual hosts.

–V virtual-host-name[:HTTPS-port]

Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. The value corresponds to the virtual host which is used for HTTPS requests. Only used for mutual junctions.

You use –V when the back-end junction server expects a Host header because you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.

Transparent junctions

See Transparent path junctions.

–x

Creates a transparent path junction.

Parent topic: Command option summary: standard junctions

Related concepts:

Addition of server to an existing junction

Related tasks:

Using pdadmin server task to create junctions

Related reference:

Server task commands for junctions

Addition of server to an existing junctionAddition of server to an existing junctionvirtual hostsadding servers to existing junctionsjunctionsadding a serverOperation: Adds an additional server to an existing junction point.Syntax:add -h host-name options junction-point–h host-nameThe DNS host name or IP address of the target back-end server to add. This parameter is required.optionsSee Table 1.junction-pointThe name of the junction point. This parameter is required. See Standard WebSEAL junction configuration.Options on the add command for adding a server to a junctionJunction typeParameterDescriptionStandard junction types–a addressSpecifies the local IP address that WebSEAL uses when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system. If you supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.Standard junction types–iWebSEAL server treats URLs as case insensitive. See Support for URLs as not case-sensitive.Standard junction types–q urlRelative path for query_contents script. By default, WebSEAL looks for query_contents in /cgi_bin/. If this directory is different or the query_contents file name is different, use this option to indicate to WebSEAL the new URL to the file. Required for back-end Windows servers. See Installing and configuring query_contents on Windows-based Web serversThe following steps describe the installation of query_contents on back-end Windows-based Web servers..Standard junction types–wWindows filesystem support. See Junctions to Windows file systems.TCP and SSL junction types–p portTCP port of the back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions. See Creating TCP type standard junctions and Creating SSL type standard junctions.Mutual junction types–p HTTP-portHTTP port of the back-end third-party server. See Creating mutual junctions.Mutual junction types–P HTTPS-portHTTPS port of the back-end third-party server. See Creating mutual junctions.Stateful junctionsSee Stateful junctions.–u UUIDSpecifies the UUID of a back-end server connected to WebSEAL via a stateful junction (–s).Mutual authentication over SSLSee Mutually authenticated SSL junctions.–D "DN"Specifies distinguished name of back-end server certificate. This value, matched with an actual certificate DN, enhances authentication.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–H host-nameDNS host name or IP address of the proxy server.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–P portThe TCP port of the proxy server.Virtual hostsSee Standard junctions to virtual hosts.–v virt-host-nameVirtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. For mutual junctions this value corresponds to the virtual host which is used for HTTP requests. You use –V when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.Virtual hostsSee Standard junctions to virtual hosts.–V virt-host-nameVirtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. The value corresponds to the virtual host which is used for HTTPS requests. Only used for mutual junctions. You use –V when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.Command option summary: standard junctionsUsing pdadmin server task to create junctionsServer task commands for junctionsCreation of a junction for an initial serverYou can create a new junction with the create command.

Addition of server to an existing junction

Operation: Adds an additional server to an existing junction point.

Syntax:

add -h host-name options junction-point

–h host-name

The DNS host name or IP address of the target back-end server to add. This parameter is required.

options

See Table 65.

junction-point

The name of the junction point. This parameter is required.

See Standard WebSEAL junction configuration.

Table 65. Options on the add command for adding a server to a junction

Junction type
Parameter
Description

Standard junction types

–a address

Specifies the local IP address that WebSEAL uses when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system.

If you supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.

Standard junction types

–i

WebSEAL server treats URLs as case insensitive.

See Support for URLs as not case-sensitive.

Standard junction types

–q url

Relative path for query_contents script. By default, WebSEAL looks for query_contents in /cgi_bin/. If this directory is different or the query_contents file name is different, use this option to indicate to WebSEAL the new URL to the file. Required for back-end Windows servers.

See Installing and configuring query_contents on Windows-based Web servers.

Standard junction types

–w

Windows filesystem support.

See Junctions to Windows file systems.

TCP and SSL junction types

–p port

TCP port of the back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions.

See Creating TCP type standard junctions and Creating SSL type standard junctions.

Mutual junction types

–p HTTP-port

HTTP port of the back-end third-party server.

See Creating mutual junctions.

Mutual junction types

–P HTTPS-port

HTTPS port of the back-end third-party server.

See Creating mutual junctions.

Stateful junctions

See Stateful junctions.

–u UUID

Specifies the UUID of a back-end server connected to WebSEAL via a stateful junction (–s).

Mutual authentication over SSL

See Mutually authenticated SSL junctions.

–D "DN"

Specifies distinguished name of back-end server certificate. This value, matched with an actual certificate DN, enhances authentication.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–H host-name

DNS host name or IP address of the proxy server.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–P port

The TCP port of the proxy server.

Virtual hosts

See Standard junctions to virtual hosts.

–v virt-host-name

Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. For mutual junctions this value corresponds to the virtual host which is used for HTTP requests.

You use –V when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.

Virtual hosts

See Standard junctions to virtual hosts.

–V virt-host-name

Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. The value corresponds to the virtual host which is used for HTTPS requests. Only used for mutual junctions.

You use –V when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.

Parent topic: Command option summary: standard junctions

Related concepts:

Creation of a junction for an initial server

Related tasks:

Using pdadmin server task to create junctions

Related reference:

Server task commands for junctions

Virtual HostingVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.Web Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Standard WebSEAL junctionsWebSEAL junctions create a scalable website. When demands on a website grow, you can add more servers to expand the capabilities of the site.Challenges of URL filteringAs an administrator, you must understand the challenges when URL filtering is used so that you can configure WebSEAL to parse HTML content correctly.Virtual hostingVirtual hosting is a web server that appears as more than one host on the Internet; the apparent host names distinguishes one host from another one. Using virtual hosting you can run multiple web services, each with a different host name and URL, that appear to be separate sites.Virtual host junction solutionWebSEAL supports virtual hosting. Through virtual host junctions, it can eliminate the limitations of URL filtering.Stanzas and stanza entries ignored by virtual host junctionsVirtual host junctions do not parse or filter URLs in HTML response pages from servers with junctions. Virtual hosts represented in the object spaceStandard WebSEAL junctions are represented in the protected object space as a mount point within the document space of WebSEAL.Configuration of a virtual host junctionDepending on the requirements of your environment, you can configure a remote or a local type virtual host junction.Scenario 1: Remote virtual host junctionsUnderstand the required configuration steps to set up junction support for two remote virtual hosts that are on a single server is implemented.Definition of interfaces for virtual host junctionsYou can configure WebSEAL to listen on multiple interfaces. You must understand the multiple interface capability because that feature is important in certificate support (SSL) for multiple virtual host junctions.Scenario 2: Virtual host junctions with interfacesLearn how to set up virtual host junctions on separate WebSEAL interfaces and two junctions that are configured to share a common protected object space.E-community single signon with virtual hostsThe E-community single signon feature can be used to do single signon between multiple virtual hosts that are on a single WebSEAL instance. Cross-domain single sign-on with virtual hostsUse cross-domain single sign-on feature to do single sign-on between multiple virtual hosts on a single WebSEAL instance. Dynamic URLs with virtual host junctionsUnderstand how virtual host junctions are expressed in the configuration file so that you can identify how they are labeled and where they map to.Using domain session cookies for virtual host single sign-onYou can use domain cookies to support single sign-on and the sharing of a single credential across multiple virtual host junctions in the same WebSEAL instance. Technical notes for using domain cookies with virtual hostsWhen you are using domain cookies with virtual hosts, consider the following points.Scenario 3: Advanced virtual host configurationLearn how to set up forms authentication, single signon using e-community, and authenticated access to specific resources.SSL session IDs not usable by virtual hostsSSL session IDs are not usable for maintaining login sessions between a browser and different virtual hosts that are on the same WebSEAL instance.Using pdadmin server task to create virtual host junctionsLearn how to use pdadmin commands so that you can create virtual host junctions. Server task commands for virtual host junctionsLearn about the available virtual junction commands so that you do actions such as add, create, and delete virtual host junctions.Creation of a virtual host junctionThe virtualhost create command creates a new virtual host junction.Addition of a server to a virtual host junctionThe virtualhost add command adds another server to a virtual host junction.

Virtual Hosting

Use the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Standard WebSEAL junctions
WebSEAL junctions create a scalable website. When demands on a website grow, you can add more servers to expand the capabilities of the site.

Challenges of URL filtering
As an administrator, you must understand the challenges when URL filtering is used so that you can configure WebSEAL to parse HTML content correctly.

Virtual hosting
Virtual hosting is a web server that appears as more than one host on the Internet; the apparent host names distinguishes one host from another one. Using virtual hosting you can run multiple web services, each with a different host name and URL, that appear to be separate sites.

Virtual host junction solution
WebSEAL supports virtual hosting. Through virtual host junctions, it can eliminate the limitations of URL filtering.

Stanzas and stanza entries ignored by virtual host junctions
Virtual host junctions do not parse or filter URLs in HTML response pages from servers with junctions.

Virtual hosts represented in the object space
Standard WebSEAL junctions are represented in the protected object space as a mount point within the document space of WebSEAL.

Configuration of a virtual host junction
Depending on the requirements of your environment, you can configure a remote or a local type virtual host junction.

Scenario 1: Remote virtual host junctions
Understand the required configuration steps to set up junction support for two remote virtual hosts that are on a single server is implemented.

Definition of interfaces for virtual host junctions
You can configure WebSEAL to listen on multiple interfaces. You must understand the multiple interface capability because that feature is important in certificate support (SSL) for multiple virtual host junctions.

Scenario 2: Virtual host junctions with interfaces
Learn how to set up virtual host junctions on separate WebSEAL interfaces and two junctions that are configured to share a common protected object space.

E-community single signon with virtual hosts
The E-community single signon feature can be used to do single signon between multiple virtual hosts that are on a single WebSEAL instance.

Cross-domain single sign-on with virtual hosts
Use cross-domain single sign-on feature to do single sign-on between multiple virtual hosts on a single WebSEAL instance.

Dynamic URLs with virtual host junctions
Understand how virtual host junctions are expressed in the configuration file so that you can identify how they are labeled and where they map to.

Using domain session cookies for virtual host single sign-on
You can use domain cookies to support single sign-on and the sharing of a single credential across multiple virtual host junctions in the same WebSEAL instance.

Technical notes for using domain cookies with virtual hosts
When you are using domain cookies with virtual hosts, consider the following points.

Scenario 3: Advanced virtual host configuration
Learn how to set up forms authentication, single signon using e-community, and authenticated access to specific resources.

SSL session IDs not usable by virtual hosts
SSL session IDs are not usable for maintaining login sessions between a browser and different virtual hosts that are on the same WebSEAL instance.

Using pdadmin server task to create virtual host junctions
Learn how to use pdadmin commands so that you can create virtual host junctions.

Server task commands for virtual host junctions
Learn about the available virtual junction commands so that you do actions such as add, create, and delete virtual host junctions.

Creation of a virtual host junction
The virtualhost create command creates a new virtual host junction.

Addition of a server to a virtual host junction
The virtualhost add command adds another server to a virtual host junction.

Parent topic: Web Reverse Proxy configuration

Standard WebSEAL junctionsStandard WebSEAL junctionsWebSEAL junctions create a scalable website. When demands on a website grow, you can add more servers to expand the capabilities of the site.virtual host junctionsfilter requirements in standard junctionsstandard junctionsWebSEALSecurity Access Manager is a product for authenticating and authorizing requests to protected web application servers. The protection of web servers is achieved by blocking direct access to the servers, and then routing the requests to WebSEAL. WebSEAL authorizes each request and, if allowed, passes on the request to the protected web server. WebSEAL returns any response back to the client. WebSEAL acts as a single host web server. WebSEAL merges all of the server document spaces into a single document space. By merging document spaces, WebSEAL can protect many web servers and still act as a single host server. The term junctioning describes the action of merging a web server's document space into WebSEAL's single unified virtual document space. For successful communication across junctions, WebSEAL must filter absolute and relative server URLs in HTML response documents that are returned from the protected web servers. Filtering correctly displays the URLs when they are viewed as part of WebSEAL's single host document space. The junction feature of WebSEAL changes the server and path information that must be used to access resources on junctioned systems. A link to a resource on a junctioned server can succeed only if the URL contains the identity of the junction. Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Standard WebSEAL junctions

WebSEAL junctions create a scalable website. When demands on a website grow, you can add more servers to expand the capabilities of the site.

Security Access Manager is a product for authenticating and authorizing requests to protected web application servers. The protection of web servers is achieved by blocking direct access to the servers, and then routing the requests to WebSEAL. WebSEAL authorizes each request and, if allowed, passes on the request to the protected web server. WebSEAL returns any response back to the client.

WebSEAL acts as a single host web server. WebSEAL merges all of the server document spaces into a single document space. By merging document spaces, WebSEAL can protect many web servers and still act as a single host server. The term junctioning describes the action of merging a web server's document space into WebSEAL's single unified virtual document space.

For successful communication across junctions, WebSEAL must filter absolute and relative server URLs in HTML response documents that are returned from the protected web servers. Filtering correctly displays the URLs when they are viewed as part of WebSEAL's single host document space. The junction feature of WebSEAL changes the server and path information that must be used to access resources on junctioned systems. A link to a resource on a junctioned server can succeed only if the URL contains the identity of the junction.

Parent topic: Virtual Hosting

Challenges of URL filteringChallenges of URL filteringAs an administrator, you must understand the challenges when URL filtering is used so that you can configure WebSEAL to parse HTML content correctly.virtual host junctionsURL filtering challengesURLfiltering challengesWebSEAL supports several solutions for filtering and processing URLs that are returned in responses from back-end junctioned application servers. All the solutions require WebSEAL to search the HTML for URLs, which can be complex.The ability of embedded JavaScript to avoid filtering by dynamically generating URLs on the client-side is also complex. See Modification of URLs to junctioned resources to understand how WebSEAL handles URL filtering over standard junctions.Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Challenges of URL filtering

As an administrator, you must understand the challenges when URL filtering is used so that you can configure WebSEAL to parse HTML content correctly.

WebSEAL supports several solutions for filtering and processing URLs that are returned in responses from back-end junctioned application servers. All the solutions require WebSEAL to search the HTML for URLs, which can be complex.

The ability of embedded JavaScript to avoid filtering by dynamically generating URLs on the client-side is also complex. See Modification of URLs to junctioned resources to understand how WebSEAL handles URL filtering over standard junctions.

Parent topic: Virtual Hosting

Virtual hostingVirtual hostingVirtual hosting is a web server that appears as more than one host on the Internet; the apparent host names distinguishes one host from another one. Using virtual hosting you can run multiple web services, each with a different host name and URL, that appear to be separate sites.virtual host junctionsbasic conceptsHTTP headerhostHost headervirtual host junctionsFor example, the following two virtual hosts can be on the same computer:www.exampleA.comwww.exampleB.comThe virtual hosts are internally configured to use unique sections of the host server's document space. A user must reference the virtual hosts only by their individual domain names. Users do not need to know any extra path information.Access to resources that use virtual hosting is possible because the HTTP/1.1 specification requires client browsers to include in any request the HTTP Host header. The Host header contains the host name of the server where the requested resource is located.Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Virtual hosting

Virtual hosting is a web server that appears as more than one host on the Internet; the apparent host names distinguishes one host from another one. Using virtual hosting you can run multiple web services, each with a different host name and URL, that appear to be separate sites.

For example, the following two virtual hosts can be on the same computer:

www.exampleA.com

www.exampleB.com

The virtual hosts are internally configured to use unique sections of the host server's document space. A user must reference the virtual hosts only by their individual domain names. Users do not need to know any extra path information.

Access to resources that use virtual hosting is possible because the HTTP/1.1 specification requires client browsers to include in any request the HTTP Host header. The Host header contains the host name of the server where the requested resource is located.

Parent topic: Virtual Hosting

Virtual host junction solutionVirtual host junction solutionWebSEAL supports virtual hosting. Through virtual host junctions, it can eliminate the limitations of URL filtering.virtual host junctionsfeaturessolutionWebSEAL can use virtual host junctions to communicate with local or remote virtual hosts. WebSEAL uses the HTTP Host header in client requests to direct those requests to the appropriate document spaces on junctioned servers or on the local computer.A user can access resources directly with the host name of the junctioned server (http://protected-server/resource). The use can do this, rather than indirectly with the host name of the WebSEAL server and a potentially modified resource path (http://webseal/junction/resource). Direct access to the resource by using the host name of the junctioned server does not require URL filtering.Virtual host junctions preserve the content of response pages in the same form as the original content on the junctioned web servers. Clients can use the unmodified absolute and server relative URL links on these response pages to successfully locate the resources.Configuration for virtual host junctions requires that the external DNS maps all virtual host names to the IP address (or addresses) of the WebSEAL server. When the user makes a request to the host name of the junctioned server, the request is routed to WebSEAL. The HTTP/1.1 specification requires that requests contain an HTTP Host header. WebSEAL uses the value of the Host header, rather than the URL of the request, to select the appropriate virtual host junction for dispatching the request. WebSEAL chooses the appropriate virtual host junction as follows:If the Host header is in the request and its value matches the host name of a configured virtual host junction, WebSEAL uses the virtual host junction. You must include the port number in the Host header when the virtual host uses a non-standard port for the protocol. The standard port for TCP is 80 and the standard port for SSL is 443. The Host header that WebSEAL sends to the virtual host junction contains the value that is specified by -v when the virtual host junction was created. In all other cases, WebSEAL uses a standard junction that is based on the URL of the request. For example, WebSEAL uses a standard junction in the following situations: If the value of the Host header does not match any virtual host junctions (-v vhost_name[:port]). If there is no Host header, such as in an HTTP/1.0 request.By default, virtual host junctions take precedence over standard junctions. You can use the match-vhj-first configuration entry in the [junction] stanza to reverse this behavior. If this configuration entry is no, WebSEAL searches for a standard junction that matches the request. If no match is found, WebSEAL checks the Host header to determine whether a virtual host junction can handle the request. If you set match-vhj-first to no in an environment that maintains sessions, you must set the shared-domain-cookie configuration entry to yes. By default, WebSEAL maintains a separate session cache for each virtual host junction and a separate session cache for all standard junctions. For session affinity, use the shared-domain-cookie parameter so that WebSEAL can use the same session, regardless of which junction services the request. You can also use the session-cookie-domain stanza to specify the domains that share session cookies. For more information about these configuration entries, see the Web Reverse Proxy Stanza Reference topics..Unlike standard junctions, WebSEAL does not define virtual host junctions as a mount point in the document space. WebSEAL accesses virtual host resources by virtual host junction designations, which are always at the root of the document space of WebSEAL. These designations are called virtual host labels.The junctioned server with the virtual host name in the HTTP Host header returns its own responses, which can contain server-relative or absolute URLs. WebSEAL returns these responses, unfiltered, directly to the client. Absolute URLs in the responses from junctioned servers that reference the server itself must use the virtual host name and not the server IP address. Clients can use the unmodified absolute and server relative URL links on these response pages to successfully locate the resources.Other features of virtual host junctions: Support for both HTTP and HTTPS protocols. To support both protocols between the client and WebSEAL, you must use two virtual host junctions. Use a separate virtual host junction for each protocol. A virtual host junction responds only to a single protocol (port). The junctioned server must support both HTTP and HTTPS so that you can create the two junctions with unique SSL and TCP ports on that server.WebSEAL can also provide multiple local virtual host junctions of its own to serve protected local content.Virtual host junctions share many configuration options with standard WebSEAL junctions. Virtual host junctions do not support several standard junction options. There are also several new options specific to virtual host junctions.Each WebSEAL instance can support multiple interfaces, ports, or both. With multiple interfaces and ports, you can configure an SSL certificate for each HTTPS interface and port on which listening occurs. If virtual host names resolve to different interfaces or ports that WebSEAL is listening on, then WebSEAL can present different certificates to the connecting clients.Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Virtual host junction solution

WebSEAL supports virtual hosting. Through virtual host junctions, it can eliminate the limitations of URL filtering.

WebSEAL can use virtual host junctions to communicate with local or remote virtual hosts. WebSEAL uses the HTTP Host header in client requests to direct those requests to the appropriate document spaces on junctioned servers or on the local computer.

A user can access resources directly with the host name of the junctioned server (http://protected-server/resource). The use can do this, rather than indirectly with the host name of the WebSEAL server and a potentially modified resource path (http://webseal/junction/resource). Direct access to the resource by using the host name of the junctioned server does not require URL filtering.

Virtual host junctions preserve the content of response pages in the same form as the original content on the junctioned web servers. Clients can use the unmodified absolute and server relative URL links on these response pages to successfully locate the resources.

Configuration for virtual host junctions requires that the external DNS maps all virtual host names to the IP address (or addresses) of the WebSEAL server. When the user makes a request to the host name of the junctioned server, the request is routed to WebSEAL.

The HTTP/1.1 specification requires that requests contain an HTTP Host header. WebSEAL uses the value of the Host header, rather than the URL of the request, to select the appropriate virtual host junction for dispatching the request.

WebSEAL chooses the appropriate virtual host junction as follows:

If the Host header is in the request and its value matches the host name of a configured virtual host junction, WebSEAL uses the virtual host junction.

You must include the port number in the Host header when the virtual host uses a non-standard port for the protocol. The standard port for TCP is 80 and the standard port for SSL is 443.

The Host header that WebSEAL sends to the virtual host junction contains the value that is specified by -v when the virtual host junction was created.

In all other cases, WebSEAL uses a standard junction that is based on the URL of the request. For example, WebSEAL uses a standard junction in the following situations:

If the value of the Host header does not match any virtual host junctions (-v vhost_name[:port]).

If there is no Host header, such as in an HTTP/1.0 request.

By default, virtual host junctions take precedence over standard junctions. You can use the match-vhj-first configuration entry in the [junction] stanza to reverse this behavior. If this configuration entry is no, WebSEAL searches for a standard junction that matches the request. If no match is found, WebSEAL checks the Host header to determine whether a virtual host junction can handle the request.

If you set match-vhj-first to no in an environment that maintains sessions, you must set the shared-domain-cookie configuration entry to yes. By default, WebSEAL maintains a separate session cache for each virtual host junction and a separate session cache for all standard junctions. For session affinity, use the shared-domain-cookie parameter so that WebSEAL can use the same session, regardless of which junction services the request. You can also use the session-cookie-domain stanza to specify the domains that share session cookies. For more information about these configuration entries, see the Web Reverse Proxy Stanza Reference topics..

Unlike standard junctions, WebSEAL does not define virtual host junctions as a mount point in the document space. WebSEAL accesses virtual host resources by virtual host junction designations, which are always at the root of the document space of WebSEAL. These designations are called virtual host labels.

The junctioned server with the virtual host name in the HTTP Host header returns its own responses, which can contain server-relative or absolute URLs. WebSEAL returns these responses, unfiltered, directly to the client. Absolute URLs in the responses from junctioned servers that reference the server itself must use the virtual host name and not the server IP address. Clients can use the unmodified absolute and server relative URL links on these response pages to successfully locate the resources.

Other features of virtual host junctions:

Support for both HTTP and HTTPS protocols. To support both protocols between the client and WebSEAL, you must use two virtual host junctions. Use a separate virtual host junction for each protocol.

A virtual host junction responds only to a single protocol (port). The junctioned server must support both HTTP and HTTPS so that you can create the two junctions with unique SSL and TCP ports on that server.

WebSEAL can also provide multiple local virtual host junctions of its own to serve protected local content.

Virtual host junctions share many configuration options with standard WebSEAL junctions. Virtual host junctions do not support several standard junction options. There are also several new options specific to virtual host junctions.

Each WebSEAL instance can support multiple interfaces, ports, or both. With multiple interfaces and ports, you can configure an SSL certificate for each HTTPS interface and port on which listening occurs.

If virtual host names resolve to different interfaces or ports that WebSEAL is listening on, then WebSEAL can present different certificates to the connecting clients.

Parent topic: Virtual Hosting

Stanzas and stanza entries ignored by virtual host junctionsStanzas and stanza entries that are ignored by virtual host junctionsVirtual host junctions do not parse or filter URLs in HTML response pages from servers with junctions. virtual host junctionsignored stanzasignored stanzasvirtual host junctionsstanzasignoredWebSEAL configuration file stanzas and stanza entries are ignored by virtual host junctions:[server], preserve-base-href[server], process-root-requests[process-root-filter][junction], jmt-map[filter-url][filter-events][filter-schemes][filter-content-types][script-filtering][preserve-cookie-names][junction], allow-backend-domain-cookiesVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Stanzas and stanza entries ignored by virtual host junctions

Virtual host junctions do not parse or filter URLs in HTML response pages from servers with junctions.

WebSEAL configuration file stanzas and stanza entries are ignored by virtual host junctions:

[server], preserve-base-href

[server], process-root-requests

[process-root-filter]

[junction], jmt-map

[filter-url]

[filter-events]

[filter-schemes]

[filter-content-types]

[script-filtering]

[preserve-cookie-names]

[junction], allow-backend-domain-cookies

Parent topic: Virtual Hosting

Virtual hosts represented in the object spaceVirtual hosts that are represented in the object spaceStandard WebSEAL junctions are represented in the protected object space as a mount point within the document space of WebSEAL.virtual hostsrepresented in the object spaceobject spacevirtual hostsJunctions are represented in the following format:/WebSEAL/instance-name/junction-name/pathVirtual host junctions are represented in the protected object space by virtual host junction designations, which are always at the root of WebSEAL's document space. These designations are called virtual host labels. For example:/WebSEAL/instance-name/@vhost-label/pathThe following example shows the representation of the resource, readme.html, under the directory, pubs, on a virtual host junction with the label support.ibm.com-http . The full path in the protected object space appears as follows: /WebSEAL/instance-name/@support.ibm.com-http/pubs/readme.htmlVirtual host junctions that are created with the -g options also appear in the protected object space so management ACLs can be placed on them. However, the directories and resources that are protected by those junctions are not displayed. Those directories and resources are only visible under the primary junction (the -g option forces WebSEAL to recognize only a single object space). For example:/WebSEAL/instance-name/@support.ibm.com-http/pubs/readme.html /WebSEAL/instance-name/@support.ibm.com-httpsVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Virtual hosts represented in the object space

Standard WebSEAL junctions are represented in the protected object space as a mount point within the document space of WebSEAL.

Junctions are represented in the following format:

/WebSEAL/instance-name/junction-name/path

Virtual host junctions are represented in the protected object space by virtual host junction designations, which are always at the root of WebSEAL's document space. These designations are called virtual host labels. For example:

/WebSEAL/instance-name/@vhost-label/path

The following example shows the representation of the resource, readme.html, under the directory, pubs, on a virtual host junction with the label support.ibm.com-http . The full path in the protected object space appears as follows:

/WebSEAL/instance-name/@support.ibm.com-http/pubs/readme.html

Virtual host junctions that are created with the -g options also appear in the protected object space so management ACLs can be placed on them. However, the directories and resources that are protected by those junctions are not displayed. Those directories and resources are only visible under the primary junction (the -g option forces WebSEAL to recognize only a single object space). For example:

/WebSEAL/instance-name/@support.ibm.com-http/pubs/readme.html
/WebSEAL/instance-name/@support.ibm.com-https

Parent topic: Virtual Hosting

Configuration of a virtual host junctionConfiguration of a virtual host junctionConfiguration of a virtual host junction in IBM Security Access Manager for WebDepending on the requirements of your environment, you can configure a remote or a local type virtual host junction.virtual hostsjunction configurationjunctionsvirtual hostconfigurationVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.Creation of a remote type virtual host junctionYou must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server.Creation of a local type virtual host junctionYou must understand how to use the available commands so that you can create a local type virtual host junction. Some of the options include the type of junction and the local directory to junction.

Configuration of a virtual host junction

Depending on the requirements of your environment, you can configure a remote or a local type virtual host junction.

Creation of a remote type virtual host junction
You must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server.

Creation of a local type virtual host junction
You must understand how to use the available commands so that you can create a local type virtual host junction. Some of the options include the type of junction and the local directory to junction.

Parent topic: Virtual Hosting

Creation of a remote type virtual host junctionCreation of a remote type virtual host junctionYou must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server.virtual host junctionsconfiguring remote TCP and SSL type junctionsremote typevirtual host labelcreating a remote typevirtual hostslabelpdadmin server taskvirtualhostremote type You can use the server task...virtualhost commands of the pdadmin utility to configure virtual host junctions. The following example (entered as one line) specifies the syntax for the pdadmin server task virtualhost create command (entered as one line): pdadmin> server task instance_name-webseald-host_name virtualhost create options vhost-labelThe following table described the common and required virtualhost create options:Remote type virtual host junction optionsOptionDescription –t type Type of junction. One of: tcp, ssl, tcpproxy, sslproxy. Required for all virtual host junctions. –h host-name The DNS host name or IP address of the target back-end server. The same host name can be used for a TCP junction and an SSL junction. The port of each virtual host differentiates one from the other so that they are each considered unique. Required by tcp, ssl, tcpproxy, and sslproxy type junctions. –v vhost name[:port] WebSEAL selects a virtual host junction. The junction processes a request if the request's HTTP Host header matches the virtual host name and port number that is specified by the -v option. The -v option is also used to specify the value of the Host header of the request sent to the back-end server. The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443. If -v is not specified for the following type of junctions, then the junction is selected from the information that is contained in the -h hostand -p port option or their default value:tcpssltcpproxysslproxy –g vhost-label If both HTTP and HTTPS protocols need to be supported between the client and WebSEAL, then two junctions to the same virtual host (-h) are required. One junction for each protocol (-t). By default, each junction recognizes its own unique protected object space even though the junctions point to a single object space. The -g option causes a second junction to share the protected object space as the initial junction. You can use a single object space reference to maintain a single access control list (ACL) on each protected object. An initial virtual host junction cannot be deleted if a second virtual host junction exists that used -g against the first. An error message is returned at such an attempt. This option is appropriate for junction pairs only (two junctions with complementary protocols). The option does not support the association of more than two junctions. Optional.Virtual host label: The virtual host label (vhost-label) is a name for the virtual host junction. By default, virtual host junctions are mounted at the root of the WebSEAL object space. You can refer to a junction in the pdadmin utility with this label. The virtual host junction label must be unique within each instance of WebSEAL.Because the label is used to represent virtual host junctions in the protected object space, the label name must not contain the forward slash character (/).Example TCP and SSL virtual host junctions:See Scenario 1: Remote virtual host junctionsUnderstand the required configuration steps to set up junction support for two remote virtual hosts that are on a single server is implemented..See Scenario 2: Virtual host junctions with interfacesLearn how to set up virtual host junctions on separate WebSEAL interfaces and two junctions that are configured to share a common protected object space..References:See Using pdadmin server task to create virtual host junctionsLearn how to use pdadmin commands so that you can create virtual host junctions. for a summary of the virtualhost junction commands.See the Web command reference topics in the IBM Knowledge Center for complete syntax information for the pdadmin utility.Configuration of a virtual host junctionDepending on the requirements of your environment, you can configure a remote or a local type virtual host junction.

Creation of a remote type virtual host junction

You must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server.

You can use the server task...virtualhost commands of the pdadmin utility to configure virtual host junctions.

The following example (entered as one line) specifies the syntax for the pdadmin server task virtualhost create command (entered as one line):

pdadmin> server task instance_name-webseald-host_name virtualhost create
options vhost-label

The following table described the common and required virtualhost create options:

Table 66. Remote type virtual host junction options

Option
Description

–t type

Type of junction. One of: tcp, ssl, tcpproxy, sslproxy.

Required for all virtual host junctions.

–h host-name

The DNS host name or IP address of the target back-end server.

The same host name can be used for a TCP junction and an SSL junction. The port of each virtual host differentiates one from the other so that they are each considered unique.

Required by tcp, ssl, tcpproxy, and sslproxy type junctions.

–v vhost name[:port]

WebSEAL selects a virtual host junction. The junction processes a request if the request's HTTP Host header matches the virtual host name and port number that is specified by the -v option.

The -v option is also used to specify the value of the Host header of the request sent to the back-end server.

The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.

If -v is not specified for the following type of junctions, then the junction is selected from the information that is contained in the -h hostand -p port option or their default value:

tcp

ssl

tcpproxy

sslproxy

–g vhost-label

If both HTTP and HTTPS protocols need to be supported between the client and WebSEAL, then two junctions to the same virtual host (-h) are required. One junction for each protocol (-t). By default, each junction recognizes its own unique protected object space even though the junctions point to a single object space.

The -g option causes a second junction to share the protected object space as the initial junction. You can use a single object space reference to maintain a single access control list (ACL) on each protected object.

An initial virtual host junction cannot be deleted if a second virtual host junction exists that used -g against the first. An error message is returned at such an attempt.

This option is appropriate for junction pairs only (two junctions with complementary protocols). The option does not support the association of more than two junctions.

Optional.

Virtual host label:

The virtual host label (vhost-label) is a name for the virtual host junction.

By default, virtual host junctions are mounted at the root of the WebSEAL object space.

You can refer to a junction in the pdadmin utility with this label.

The virtual host junction label must be unique within each instance of WebSEAL.

Because the label is used to represent virtual host junctions in the protected object space, the label name must not contain the forward slash character (/).

Example TCP and SSL virtual host junctions:

See Scenario 1: Remote virtual host junctions.

See Scenario 2: Virtual host junctions with interfaces.

References:

See Using pdadmin server task to create virtual host junctions for a summary of the virtualhost junction commands.

See the Web command reference topics in the IBM Knowledge Center for complete syntax information for the pdadmin utility.

Parent topic: Configuration of a virtual host junction

Creation of a local type virtual host junctionCreation of a local type virtual host junctionYou must understand how to use the available commands so that you can create a local type virtual host junction. Some of the options include the type of junction and the local directory to junction.virtual host junctionsconfiguring local type junctionslocal typelocal typesvirtual host junctionA local virtual host junction (-t localtcp and -t localssl) is a mount point for specific content that is located locally on the WebSEAL server. Like the content from junctioned remote servers, local junction content is incorporated into WebSEAL's unified protected object space view.The following options are appropriate for local virtual host junctions:Local type virtual host junction optionsOptionDescription –t type Type of junction (localtcp or localssl). Required. –g vhost-label The -g option causes a second junction to share the protected object space as the initial junction. See Creation of a remote type virtual host junctionYou must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server.. –v vhost name[:port] WebSEAL selects a virtual host junction. The junction processes a request if the request's HTTP Host header matches the virtual host name and port number that is specified by the -v option. The -v option is also used to specify the value of the Host header of the request sent to the back-end server. The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443. The -v option is required for localtcp and localssl type junctions. See Creation of a remote type virtual host junctionYou must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server.. –z replica-set-name Optional. Specifies the replica set that sessions on the virtual host junction are managed under. The command can group or separate login sessions among multiple virtual hosts. If -z is not used to specify the replica set for the virtual host junction, the virtual host junction is automatically assigned to a replica set. The replica set matches its virtual host name. For example, if the virtual host name is vhostA.example.com, the replica set is named vhostA.example.com. The replica set used for the virtual host junction must be present in the [replica-sets] stanza of the WebSEAL configuration file. See Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution.. –f Force the replacement of an existing junction. See Forcing a new junction. –l percent-value Defines the soft limit for consumption of worker threads. See Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis.. –L percent-value Defines the hard limit for consumption of worker threads. See Per-junction allocation of worker threads for junctionsUse the pdadmin command so that you can limit worker thread consumption on a per-junction basis..Example local virtual host junction:The first command (entered as one line) creates a local virtual junction that responds to HTTP requests with Host header value of p.s.com. pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t localtcp -v p.s.com vhost-local-ps-httpThe second command (entered as one line) creates a local virtual junction that responds to HTTPS requests with Host header value of p.s.com:444. The -g option pairs this SSL junction with the first TCP junction so that they share protected object space.pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t localssl -v p.s.com:444 -g vhost-local-ps-http vhost-local-ps-httpsConfiguration of a virtual host junctionDepending on the requirements of your environment, you can configure a remote or a local type virtual host junction.

Creation of a local type virtual host junction

You must understand how to use the available commands so that you can create a local type virtual host junction. Some of the options include the type of junction and the local directory to junction.

A local virtual host junction (-t localtcp and -t localssl) is a mount point for specific content that is located locally on the WebSEAL server. Like the content from junctioned remote servers, local junction content is incorporated into WebSEAL's unified protected object space view.

The following options are appropriate for local virtual host junctions:

Table 67. Local type virtual host junction options

Option
Description

–t type

Type of junction (localtcp or localssl). Required.

–g vhost-label

The -g option causes a second junction to share the protected object space as the initial junction.

See Creation of a remote type virtual host junction.

–v vhost name[:port]

WebSEAL selects a virtual host junction. The junction processes a request if the request's HTTP Host header matches the virtual host name and port number that is specified by the -v option.

The -v option is also used to specify the value of the Host header of the request sent to the back-end server.

The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.

The -v option is required for localtcp and localssl type junctions.

See Creation of a remote type virtual host junction.

–z replica-set-name

Optional. Specifies the replica set that sessions on the virtual host junction are managed under. The command can group or separate login sessions among multiple virtual hosts.

If -z is not used to specify the replica set for the virtual host junction, the virtual host junction is automatically assigned to a replica set. The replica set matches its virtual host name. For example, if the virtual host name is vhostA.example.com, the replica set is named vhostA.example.com. The replica set used for the virtual host junction must be present in the [replica-sets] stanza of the WebSEAL configuration file.

See Advanced configuration for the distributed session cache.

–f

Force the replacement of an existing junction.

See Forcing a new junction.

–l percent-value

Defines the soft limit for consumption of worker threads.

See Per-junction allocation of worker threads for junctions.

–L percent-value

Defines the hard limit for consumption of worker threads.

See Per-junction allocation of worker threads for junctions.

Example local virtual host junction:

The first command (entered as one line) creates a local virtual junction that responds to HTTP requests with Host header value of p.s.com.

pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t localtcp -v p.s.com vhost-local-ps-http

The second command (entered as one line) creates a local virtual junction that responds to HTTPS requests with Host header value of p.s.com:444. The -g option pairs this SSL junction with the first TCP junction so that they share protected object space.

pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t localssl -v p.s.com:444 -g vhost-local-ps-http vhost-local-ps-https

Parent topic: Configuration of a virtual host junction

Scenario 1: Remote virtual host junctionsScenario 1: Remote virtual host junctionsUnderstand the required configuration steps to set up junction support for two remote virtual hosts that are on a single server is implemented.virtual host junctionsscenario 1: basic virtual host junctionscenariosremote virtual host junctionsThe following scenario sets up junction support for two remote virtual hosts that are on a single back-end server. Refer to the accompanying diagram as you proceed through the steps.Required architecture: By default, the WebSEAL configuration file is set to support all IP addresses: [server] network-interface = 0.0.0.0 For this virtual host scenario, WebSEAL (webseal.ibm.com) is configured to use a specific network address: [server] network-interface = 9.0.0.3WebSEAL servers that are protecting two virtual hosts on one back-end junctioned server: Virtual host a.b.com (on server cruz1.ibm.com)Virtual host x.y.com (on server cruz1.ibm.com)Direct access to the protected junctioned server (cruz1.ibm.com) is prevented by appropriate firewall protection. The user is not aware of this blocked access. The external DNS used by the browser to look up the virtual host names are configured to point to WebSEAL at IP address 9.0.0.3. External DNSa.b.com9.0.0.3x.y.com9.0.0.3Virtual host a.b.com accepts HTTP access only.Virtual host x.y.com accepts secure HTTPS access. Virtual host junction scenario 1Virtual host junction scenario 1Procedure: The following pdadmin command (entered as one line) creates a virtual host junction named (labeled) vhost-ab-http that responds to the Host: a.b.com header in TCP (HTTP) requests to WebSEAL: pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t tcp -h cruz1.ibm.com -v a.b.com vhost-ab-httpThe following command (entered as one line) creates a virtual host junction named (labeled) vhost-xy-https that responds to the Host: x.y.com header in SSL (HTTPS) requests to WebSEAL: pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-httpsThe client user clicks the following (example) link on an HTML page: http://a.b.com/doc/readme.txt The (example) request for this resource appears as follows: GET /doc/readme.txt HTTP/1.1 Host: a.b.com User-Agent: Mozilla 4.0 (X; I; Linux-2.0.35i586) Accept: image/gif, image/jpeg, */* DNS determines that communication to the requested server (a.b.com) is routed to the WebSEAL host (9.0.0.3). WebSEAL detects the Host header and routes the request across the junction for virtual host a.b.com, on the back-end server cruz1.ibm.com.Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Scenario 1: Remote virtual host junctions

Understand the required configuration steps to set up junction support for two remote virtual hosts that are on a single server is implemented.

The following scenario sets up junction support for two remote virtual hosts that are on a single back-end server. Refer to the accompanying diagram as you proceed through the steps.

Required architecture:

By default, the WebSEAL configuration file is set to support all IP addresses:

[server]
network-interface = 0.0.0.0

For this virtual host scenario, WebSEAL (webseal.ibm.com) is configured to use a specific network address:

[server]
network-interface = 9.0.0.3

WebSEAL servers that are protecting two virtual hosts on one back-end junctioned server:

Virtual host a.b.com (on server cruz1.ibm.com)

Virtual host x.y.com (on server cruz1.ibm.com)

Direct access to the protected junctioned server (cruz1.ibm.com) is prevented by appropriate firewall protection. The user is not aware of this blocked access. The external DNS used by the browser to look up the virtual host names are configured to point to WebSEAL at IP address 9.0.0.3.

External DNS
a.b.com | 9.0.0.3
x.y.com | 9.0.0.3

Virtual host a.b.com accepts HTTP access only.

Virtual host x.y.com accepts secure HTTPS access.

Figure 39. Virtual host junction scenario 1

Procedure:

The following pdadmin command (entered as one line) creates a virtual host junction named (labeled) vhost-ab-http that responds to the Host: a.b.com header in TCP (HTTP) requests to WebSEAL:

pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t tcp -h cruz1.ibm.com -v a.b.com vhost-ab-http

The following command (entered as one line) creates a virtual host junction named (labeled) vhost-xy-https that responds to the Host: x.y.com header in SSL (HTTPS) requests to WebSEAL:

pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-https

The client user clicks the following (example) link on an HTML page:

http://a.b.com/doc/readme.txt

The (example) request for this resource appears as follows:

GET /doc/readme.txt HTTP/1.1
Host: a.b.com
User-Agent: Mozilla 4.0 (X; I; Linux-2.0.35i586)
Accept: image/gif, image/jpeg, */*

DNS determines that communication to the requested server (a.b.com) is routed to the WebSEAL host (9.0.0.3).

WebSEAL detects the Host header and routes the request across the junction for virtual host a.b.com, on the back-end server cruz1.ibm.com.

Parent topic: Virtual Hosting

Definition of interfaces for virtual host junctionsDefinition of interfaces for virtual host junctionsYou can configure WebSEAL to listen on multiple interfaces. You must understand the multiple interface capability because that feature is important in certificate support (SSL) for multiple virtual host junctions.virtual host junctionsinterfacesinterfacesvirtual host junctionsA digital certificate contains the name of the host that is being accessed. Therefore, it is necessary to have a unique certificate exchange for each virtual host that is configured for SSL. Browsers produce a warning message when there is a name mismatch between certificate and host.Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.Default interface specificationAs an administrator, you must understand the network interface for your environment so that you can configure the settings correctly.Defining extra interfacesAs an administrator, you can define extra interfaces so that you can configure a set of values for a specific group of settings.

Definition of interfaces for virtual host junctions

You can configure WebSEAL to listen on multiple interfaces. You must understand the multiple interface capability because that feature is important in certificate support (SSL) for multiple virtual host junctions.

A digital certificate contains the name of the host that is being accessed. Therefore, it is necessary to have a unique certificate exchange for each virtual host that is configured for SSL. Browsers produce a warning message when there is a name mismatch between certificate and host.

Default interface specification
As an administrator, you must understand the network interface for your environment so that you can configure the settings correctly.

Defining extra interfaces
As an administrator, you can define extra interfaces so that you can configure a set of values for a specific group of settings.

Parent topic: Virtual Hosting

Default interface specificationDefault interface specificationAs an administrator, you must understand the network interface for your environment so that you can configure the settings correctly.http stanza entryhttp-port stanza entryhttps stanza entryhttps-port stanza entryworker-threads stanza entrynetwork-interface stanza entrywebseal-cert-keyfile-label stanza entryaccept-client-certs stanza entryA network interface is defined as the combined set of values for a specific group of settings. Included settings:HTTP or HTTPS port IP addressWorker threadsCertificate handlingThe single default interface for a WebSEAL instance is defined by the following stanza entries in the WebSEAL configuration file:[server] http http-port https https-port worker-threads network-interface [ssl] webseal-cert-keyfile-label [certificate] accept-client-certsDefinition of interfaces for virtual host junctionsYou can configure WebSEAL to listen on multiple interfaces. You must understand the multiple interface capability because that feature is important in certificate support (SSL) for multiple virtual host junctions.

Default interface specification

As an administrator, you must understand the network interface for your environment so that you can configure the settings correctly.

A network interface is defined as the combined set of values for a specific group of settings.

Included settings:

HTTP or HTTPS port

IP address

Worker threads

Certificate handling

The single default interface for a WebSEAL instance is defined by the following stanza entries in the WebSEAL configuration file:

[server]
http
http-port
https
https-port
worker-threads
network-interface

[ssl]
webseal-cert-keyfile-label

[certificate]
accept-client-certs

Parent topic: Definition of interfaces for virtual host junctions

Defining extra interfacesDefining extra interfacesAs an administrator, you can define extra interfaces so that you can configure a set of values for a specific group of settings.interfacespropertiesdefining extraextrastanza To configure extra interfaces, define each custom-named interface within the [interfaces] stanza of the WebSEAL configuration file. Each interface definition includes a list of properties. Most properties imitate equivalent stanza entry names that are found in the WebSEAL configuration file and that are part of the default interface specification (see Default interface specificationAs an administrator, you must understand the network interface for your environment so that you can configure the settings correctly.). A custom interface specification uses the following format: [interfaces] interface-name = property=value[;property=value[;...]] The following table lists the available properties and values that are used to configure a custom interface: Valid properties and values for extra interface definitionsPropertyValuesDescription http-port port numberdisabled (default) Port number to listen for HTTP requests on the specified network-interface. The value can also be set to disabled. One of either http-port or https-port must be specified when you define an interface. https-port port numberdisabled (default) Port number to listen for HTTPS requests on the specified network-interface. The value can also be set to disabled. One of either http-port or https-port must be specified you define an interface. worker-threads countdefault (default) Number of worker threads that are used to process requests received only on this interface. The default value can be used to specify use of the worker thread pool that belongs to the default interface (see Default interface specificationAs an administrator, you must understand the network interface for your environment so that you can configure the settings correctly.). network-interface IP address0.0.0.0 (default) IP address to listen for requests on the specified http-port or https-port. Both IPv4 and IPv6 formats are supported. certificate-label key-file-label Label name of a certificate in the pdsrv.kdb key database file. Only valid when https-port is specified. The server-side certificate WebSEAL uses to authenticate to the client. accept-client-certs never (default)requiredoptionalprompt_as_needed Specifies how WebSEAL is to handle client-side certificates. Only valid when https-port is specified. See Client-side certificate authentication. Syntax rules for property values: A value that contains a semicolon (;), double quotation mark ("), or backslash (\) must be preceded by a backslash (\).Double quotation marks (") must be used to specify values that contain leading or trailing spaces.If a semicolon (;) appears inside a double-quoted value, it does not require a preceding backslash. [interfaces] support = network-interface=9.0.0.8;https-port=444;certificate-label=WS6; worker-threads=16 This example (entered as one line) creates an interface that is named "support" with the following properties: Allows WebSEAL to listen for requests at IP address 9.0.0.8, on HTTPS port 444.The HTTP port defaults to "disabled".WebSEAL authenticates to SSL clients with a server-side certificate named "WS6" stored in the WebSEAL key database file.The interface uses its own pool of 16 worker threads to service requests.The interface defaults to never requiring (prompting for) client-side certificates during authentication. When you configure WebSEAL with multiple DNS aliases that are assigned to its interfaces, each alias and interface must be assigned to a virtual host junction. WebSEAL does not support multiple DNS aliases that are assigned to its interface definitions, which are not assigned to virtual host junctions.Definition of interfaces for virtual host junctionsYou can configure WebSEAL to listen on multiple interfaces. You must understand the multiple interface capability because that feature is important in certificate support (SSL) for multiple virtual host junctions.

Defining extra interfaces

As an administrator, you can define extra interfaces so that you can configure a set of values for a specific group of settings.

About this task

To configure extra interfaces, define each custom-named interface within the [interfaces] stanza of the WebSEAL configuration file.

Each interface definition includes a list of properties. Most properties imitate equivalent stanza entry names that are found in the WebSEAL configuration file and that are part of the default interface specification (see Default interface specification).

A custom interface specification uses the following format:

[interfaces]
interface-name = property=value[;property=value[;...]]

The following table lists the available properties and values that are used to configure a custom interface:

Table 68. Valid properties and values for extra interface definitions

Property
Values
Description

http-port

port number

disabled (default)

Port number to listen for HTTP requests on the specified network-interface. The value can also be set to disabled.

One of either http-port or https-port must be specified when you define an interface.

https-port

port number

disabled (default)

Port number to listen for HTTPS requests on the specified network-interface. The value can also be set to disabled.

One of either http-port or https-port must be specified you define an interface.

worker-threads

count

default (default)

Number of worker threads that are used to process requests received only on this interface.

The default value can be used to specify use of the worker thread pool that belongs to the default interface (see Default interface specification).

network-interface

IP address

0.0.0.0 (default)

IP address to listen for requests on the specified http-port or https-port.

Both IPv4 and IPv6 formats are supported.

certificate-label

key-file-label

Label name of a certificate in the pdsrv.kdb key database file.

Only valid when https-port is specified.

The server-side certificate WebSEAL uses to authenticate to the client.

accept-client-certs

never (default)

required

optional

prompt_as_needed

Specifies how WebSEAL is to handle client-side certificates.

Only valid when https-port is specified.

See Client-side certificate authentication.

Syntax rules for property values:

A value that contains a semicolon (;), double quotation mark ("), or backslash (\) must be preceded by a backslash (\).

Double quotation marks (") must be used to specify values that contain leading or trailing spaces.

If a semicolon (;) appears inside a double-quoted value, it does not require a preceding backslash.

Example

[interfaces]
support = network-interface=9.0.0.8;https-port=444;certificate-label=WS6;
worker-threads=16

This example (entered as one line) creates an interface that is named "support" with the following properties:

Allows WebSEAL to listen for requests at IP address 9.0.0.8, on HTTPS port 444.

The HTTP port defaults to "disabled".

WebSEAL authenticates to SSL clients with a server-side certificate named "WS6" stored in the WebSEAL key database file.

The interface uses its own pool of 16 worker threads to service requests.

The interface defaults to never requiring (prompting for) client-side certificates during authentication.

Note: When you configure WebSEAL with multiple DNS aliases that are assigned to its interfaces, each alias and interface must be assigned to a virtual host junction. WebSEAL does not support multiple DNS aliases that are assigned to its interface definitions, which are not assigned to virtual host junctions.

Parent topic: Definition of interfaces for virtual host junctions

Scenario 2: Virtual host junctions with interfacesScenario 2: Virtual host junctions with interfacesLearn how to set up virtual host junctions on separate WebSEAL interfaces and two junctions that are configured to share a common protected object space.virtual host junctionsscenario 2: interfaces configurationinterfacesscenariosvirtual host junctions with interfacesweb-host-name stanza entryThe following scenario sets up: Virtual host junctions are created on separate WebSEAL interfaces.Two junctions are configured to share a common protected object space.Refer to the accompanying diagram as you proceed through the steps.Required architecture: WebSEAL protects three virtual hosts over the following protocols: a.b.com (on host cruz1.ibm.com) over HTTP and HTTPSw.x.com (on host cruz2.ibm.com) over HTTPy.z.com (on host cruz2.ibm.com) over HTTPSDirect access to the protected junctioned servers (cruz1.ibm.comcruz2.ibm.com) is prevented by appropriate firewall protection. The user is not aware of this blocked access. The external DNS entries that are used by the browser to look up the virtual host names are configured to point to WebSEAL at IP address 9.0.0.3 or 9.0.0.4.The virtual hosts are configured in the external DNS to point to the WebSEAL server: External DNSa.b.com9.0.0.3x.y.com9.0.0.3y.z.com9.0.0.4The WebSEAL server is known to browsers by the following host names: webseal.ibm.com (WebSEAL's true host name)a.b.comw.x.comy.z.comWebSEAL is configured for two interfaces (to allow serving unique server-side certificates over HTTPS for a.b.comy.z.com): 9.0.0.39.0.0.4 Virtual host junction scenario 2Virtual host junction scenario 2Procedure - general setup: Install and configure a default WebSEAL with the first of the two required interfaces (to support SSL communication with a.b.com:443): [server] network-interface = 9.0.0.3 http = yes http-port = 80 https = yes https-port = 443To support SSL communication between browsers and the a.b.com virtual host (over port 443), install a server-side certificate (named ab in this example) in WebSEAL's pdsrv.kdb key file database. This certificate must be generated and signed by a Certificate Authority (CA). WebSEAL presents this certificate, on behalf of the interface, to authenticate to client browsers. [ssl] webseal-cert-keyfile-label = ab WebSEAL provides an option to configure a separate certificate key database for junction SSL operations. You can use a separate certificate key database rather than sharing the one used for client certificates that are specified in the [ssl] stanza. For more information, see Configuration of the WebSEAL key database file and the description of the jct-cert-keyfile option in jct-cert-keyfile.Configure a second interface to support SSL communication with y.z.com:443: [interfaces] yz-interface = network-interface=9.0.0.4; certificate-label=yz; https-port=443To support SSL communication between browsers and the y.z.com virtual host (over port 443), install a server-side certificate (named yz in this example) in WebSEAL's pdsrv.kdb key file database. This certificate must be generated and signed by a Certificate Authority (CA). WebSEAL presents this certificate, on behalf of the interface, to authenticate to client browsers. WebSEAL provides an option to configure a separate certificate key database for junction SSL operations. You can use a separate certificate key database rather than sharing the one used for client certificates that are specified in the [ssl] stanza. For more information, see Configuration of the WebSEAL key database file and the description of the jct-cert-keyfile option in the jct-cert-keyfile.Assign the appropriate name as a value to the web-host-name stanza entry in the WebSEAL configuration file. You must assign the appropriate name value to ensure that the primary WebSEAL host name is used when required. [server] server-name = webseal.ibm.com-default web-host-name = webseal.ibm.comProcedure - create virtual host junctions: Create two virtual host junctions (entered as one line) to support HTTP and HTTPS communication to a.b.com. Use the -g option to allow the two junctions to share the object space: pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t tcp -h cruz1.ibm.com -v a.b.com vhost-ab-tcp pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t ssl -h cruz1.ibm.com -v a.b.com -g vhost-ab-tcp vhost-ab-sslCreate a virtual host junction (entered as one line) to support communication with w.x.com:80: pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t tcp -h cruz2.ibm.com -v w.x.com vhost-wx-tcpCreate a virtual host junction (entered as one line) to support communication with y.z.com:443: pdadmin> server task default-webseald-webseal.ibm.com virtualhost create -t ssl -h cruz2.ibm.com -v y.z.com vhost-yz-sslVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Scenario 2: Virtual host junctions with interfaces

Learn how to set up virtual host junctions on separate WebSEAL interfaces and two junctions that are configured to share a common protected object space.

The following scenario sets up:

Virtual host junctions are created on separate WebSEAL interfaces.

Two junctions are configured to share a common protected object space.

Refer to the accompanying diagram as you proceed through the steps.

Required architecture:

WebSEAL protects three virtual hosts over the following protocols:

a.b.com (on host cruz1.ibm.com) over HTTP and HTTPS

w.x.com (on host cruz2.ibm.com) over HTTP

y.z.com (on host cruz2.ibm.com) over HTTPS

Direct access to the protected junctioned servers (cruz1.ibm.com > cruz2.ibm.com) is prevented by appropriate firewall protection. The user is not aware of this blocked access. The external DNS entries that are used by the browser to look up the virtual host names are configured to point to WebSEAL at IP address 9.0.0.3 or 9.0.0.4.

The virtual hosts are configured in the external DNS to point to the WebSEAL server:

External DNS
a.b.com | 9.0.0.3
x.y.com | 9.0.0.3
y.z.com | 9.0.0.4

The WebSEAL server is known to browsers by the following host names:

webseal.ibm.com (WebSEAL's true host name)

a.b.com

w.x.com

y.z.com

WebSEAL is configured for two interfaces (to allow serving unique server-side certificates over HTTPS for a.b.com > y.z.com):

9.0.0.3

9.0.0.4

Figure 40. Virtual host junction scenario 2

Procedure - general setup:

Install and configure a default WebSEAL with the first of the two required interfaces (to support SSL communication with a.b.com:443):

[server]
network-interface = 9.0.0.3
http = yes
http-port = 80
https = yes
https-port = 443

To support SSL communication between browsers and the a.b.com virtual host (over port 443), install a server-side certificate (named ab in this example) in WebSEAL's pdsrv.kdb key file database. This certificate must be generated and signed by a Certificate Authority (CA). WebSEAL presents this certificate, on behalf of the interface, to authenticate to client browsers.

[ssl]
webseal-cert-keyfile-label = ab

Note: WebSEAL provides an option to configure a separate certificate key database for junction SSL operations. You can use a separate certificate key database rather than sharing the one used for client certificates that are specified in the [ssl] stanza. For more information, see Configuration of the WebSEAL key database file and the description of the jct-cert-keyfile option in jct-cert-keyfile.

Configure a second interface to support SSL communication with y.z.com:443:

[interfaces]
yz-interface = network-interface=9.0.0.4; certificate-label=yz; https-port=443

To support SSL communication between browsers and the y.z.com virtual host (over port 443), install a server-side certificate (named yz in this example) in WebSEAL's pdsrv.kdb key file database. This certificate must be generated and signed by a Certificate Authority (CA). WebSEAL presents this certificate, on behalf of the interface, to authenticate to client browsers.

Note: WebSEAL provides an option to configure a separate certificate key database for junction SSL operations. You can use a separate certificate key database rather than sharing the one used for client certificates that are specified in the [ssl] stanza. For more information, see Configuration of the WebSEAL key database file and the description of the jct-cert-keyfile option in the jct-cert-keyfile.

Assign the appropriate name as a value to the web-host-name stanza entry in the WebSEAL configuration file. You must assign the appropriate name value to ensure that the primary WebSEAL host name is used when required.

[server]
server-name = webseal.ibm.com-default
web-host-name = webseal.ibm.com

Procedure - create virtual host junctions:

Create two virtual host junctions (entered as one line) to support HTTP and HTTPS communication to a.b.com. Use the -g option to allow the two junctions to share the object space:

pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t tcp -h cruz1.ibm.com -v a.b.com vhost-ab-tcp
pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t ssl -h cruz1.ibm.com -v a.b.com -g vhost-ab-tcp vhost-ab-ssl

Create a virtual host junction (entered as one line) to support communication with w.x.com:80:

pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t tcp -h cruz2.ibm.com -v w.x.com vhost-wx-tcp

Create a virtual host junction (entered as one line) to support communication with y.z.com:443:

pdadmin> server task default-webseald-webseal.ibm.com virtualhost create
-t ssl -h cruz2.ibm.com -v y.z.com vhost-yz-ssl

Parent topic: Virtual Hosting

E-community single signon with virtual hostsE-community single signon with virtual hostsThe E-community single signon feature can be used to do single signon between multiple virtual hosts that are on a single WebSEAL instance. virtual hostsuse e-communitye-community authenticationvirtual hostse-community-domains stanzae-community-domains-keys: domain stanzaThe virtual hosts all share the configuration file in the WebSEAL instance.To support virtual host junctions, e-community single signon allows:A single virtual host to act as the Master authentication server (MAS) on a machine with more than one virtual hosts.Specification of per-domain single signon keys for environments with multiple virtual hosts that supporting different domains.Configuration enhancements to e-community:On a machine with multiple virtual hosts, use the master-authn-server stanza entry to designate one of the virtual hosts as the MAS. [e-community-sso] is-master-authn-server = yes master-authn-server = virtual-hostThe [e-community-domain-keys] stanza is only appropriate for use with standard WebSEAL junctions. [e-community-domain-keys]The [e-community-domains] stanza lists the domains supported by virtual hosts. [e-community-domains]The [e-community-domain-keys:domain] stanzas contain the appropriate keys for each domain that is defined in the [e-community-domains] stanza. [e-community-domain-keys:domain]Example:One WebSEAL instanceThree virtual hosts (four virtual host junctions) forming an e-community: www.ibm.com:80 www.ibm.com:443 www.lotus.com:80 www.tivoli.com:80 www.ibm.com:80 and www.ibm.com:443 are a virtual host junction protocol pair. They were created with the -g virtual host junction option and therefore share the object space. They server the single virtual host www.ibm.com.MAS is the virtual host www.ibm.comWebSEAL configuration file: [e-community-sso] is-master-authn-server = yes master-authn-server = www.ibm.com [e-community-domains] name = ibm.com name = tivoli.com name = lotus.com [e-community-sso-domain-keys:ibm.com] ibm.com = ibm.key tivoli.com = ibm-tivoli.key lotus.com = ibm-lotus.key [e-community-sso-domain-keys:tivoli.com] tivoli.com = tivoli.key ibm.com = ibm-tivoli.key [e-community-sso-domain-keys:lotus.com] lotus.com = lotus.key ibm.com = ibm-lotus.keyVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

E-community single signon with virtual hosts

The E-community single signon feature can be used to do single signon between multiple virtual hosts that are on a single WebSEAL instance.

The virtual hosts all share the configuration file in the WebSEAL instance.

To support virtual host junctions, e-community single signon allows:

A single virtual host to act as the Master authentication server (MAS) on a machine with more than one virtual hosts.

Specification of per-domain single signon keys for environments with multiple virtual hosts that supporting different domains.

Configuration enhancements to e-community:

On a machine with multiple virtual hosts, use the master-authn-server stanza entry to designate one of the virtual hosts as the MAS.

[e-community-sso]
is-master-authn-server = yes
master-authn-server = virtual-host

The [e-community-domain-keys] stanza is only appropriate for use with standard WebSEAL junctions.

[e-community-domain-keys]

The [e-community-domains] stanza lists the domains supported by virtual hosts.

[e-community-domains]

The [e-community-domain-keys:domain] stanzas contain the appropriate keys for each domain that is defined in the [e-community-domains] stanza.

[e-community-domain-keys:domain]

Example:

One WebSEAL instance

Three virtual hosts (four virtual host junctions) forming an e-community:

www.ibm.com:80
www.ibm.com:443
www.lotus.com:80
www.tivoli.com:80

Note: www.ibm.com:80 and www.ibm.com:443 are a virtual host junction protocol pair. They were created with the -g virtual host junction option and therefore share the object space. They server the single virtual host www.ibm.com.

MAS is the virtual host www.ibm.com

WebSEAL configuration file:

[e-community-sso]
is-master-authn-server = yes
master-authn-server = www.ibm.com

[e-community-domains]
name = ibm.com
name = tivoli.com
name = lotus.com

[e-community-sso-domain-keys:ibm.com]
ibm.com = ibm.key
tivoli.com = ibm-tivoli.key
lotus.com = ibm-lotus.key

[e-community-sso-domain-keys:tivoli.com]
tivoli.com = tivoli.key
ibm.com = ibm-tivoli.key

[e-community-sso-domain-keys:lotus.com]
lotus.com = lotus.key
ibm.com = ibm-lotus.key

Parent topic: Virtual Hosting

Cross-domain single sign-on with virtual hostsCross-domain single sign-on with virtual hostsUse cross-domain single sign-on feature to do single sign-on between multiple virtual hosts on a single WebSEAL instance. CDSSO authenticationcross-domain single sign-on with virtual hostscross-domain single sign-onvirtual hostscross-domain single sign-onThe virtual hosts all share the configuration file on to the WebSEAL instance. However, cross-domain single sign-on with virtual hosts has certain configuration limitations.Cross-domain single sign-on configuration does not allow specification of per-domain single sign-on keys for environments with multiple virtual hosts that support different domains. All virtual hosts that are associated with the WebSEAL instance must share the one [cdsso-peers] stanza that is used for key configuration. Therefore, the virtual hosts must share a common key that is used by each domain to communicate to another domain.In the following example, two virtual hosts on a single WebSEAL instance:a.a.comb.b.comBoth domains are owned by separate entities and each of these entities has a separate CDSSO arrangement with another WebSEAL server, c.c.com. Ideally, a.a.com and b.b.com would have separate keys to use for single sign-on with c.c.com. The ideal configuration would appear as follows:[cdsso-peers] # used by a.a.com to communicate with c.c.com c.c.com = c-a.key # used by b.b.com to communicate with c.c.com c.c.com = c-b.key This configuration is not possible on a single WebSEAL instance (hosting both a.a.com and b.b.com virtual hosts). The [cdsso-peers] stanza allows only one key to be specified for a target domain.The only configuration allowed forces both a.a.com and b.b.com to use the same key. For example:[cdsso-peers] # used by both a.a.com and b.b.com to communicate with c.c.com c.c.com = c-ab.key Each owner of the a.a.com and b.b.com domains must accept the condition that they share the key.In addition, if the one key is compromised, both a.a.com and b.b.com are compromised.Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Cross-domain single sign-on with virtual hosts

Use cross-domain single sign-on feature to do single sign-on between multiple virtual hosts on a single WebSEAL instance.

The virtual hosts all share the configuration file on to the WebSEAL instance. However, cross-domain single sign-on with virtual hosts has certain configuration limitations.

Cross-domain single sign-on configuration does not allow specification of per-domain single sign-on keys for environments with multiple virtual hosts that support different domains. All virtual hosts that are associated with the WebSEAL instance must share the one [cdsso-peers] stanza that is used for key configuration. Therefore, the virtual hosts must share a common key that is used by each domain to communicate to another domain.

In the following example, two virtual hosts on a single WebSEAL instance:

a.a.com

b.b.com

Both domains are owned by separate entities and each of these entities has a separate CDSSO arrangement with another WebSEAL server, c.c.com. Ideally, a.a.com and b.b.com would have separate keys to use for single sign-on with c.c.com. The ideal configuration would appear as follows:

[cdsso-peers]
# used by a.a.com to communicate with c.c.com
c.c.com = c-a.key
# used by b.b.com to communicate with c.c.com
c.c.com = c-b.key

This configuration is not possible on a single WebSEAL instance (hosting both a.a.com and b.b.com virtual hosts). The [cdsso-peers] stanza allows only one key to be specified for a target domain.

The only configuration allowed forces both a.a.com and b.b.com to use the same key. For example:

[cdsso-peers]
# used by both a.a.com and b.b.com to communicate with c.c.com
c.c.com = c-ab.key

Each owner of the a.a.com and b.b.com domains must accept the condition that they share the key.

In addition, if the one key is compromised, both a.a.com and b.b.com are compromised.

Parent topic: Virtual Hosting

Dynamic URLs with virtual host junctionsDynamic URLs with virtual host junctionsUnderstand how virtual host junctions are expressed in the configuration file so that you can identify how they are labeled and where they map to.virtual host junctionsdynamic URLsdynamic URLsvirtual host junctionsIn the dynurl.conf configuration file, virtual host junctions are expressed as /@<vhost-label>.For example, the following dynurl.conf configuration file entry specifies that a virtual host junction labeled test-http map all URLs under the directory /mapfrom to the protected object /@test-http/maptoin /@test-http/mapto/@test-http/mapfrom/*.Standard WebSEAL junctions and virtual host junctions can co-exist in the dynurl.conf configuration file. For example:/mapto/@test-http/mapfrom/* /@test-http/mapto/mapfrom/*Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Dynamic URLs with virtual host junctions

Understand how virtual host junctions are expressed in the configuration file so that you can identify how they are labeled and where they map to.

In the dynurl.conf configuration file, virtual host junctions are expressed as /@<vhost-label>.

For example, the following dynurl.conf configuration file entry specifies that a virtual host junction labeled test-http map all URLs under the directory /mapfrom to the protected object /@test-http/maptoin /@test-http/mapto/@test-http/mapfrom/*.

Standard WebSEAL junctions and virtual host junctions can co-exist in the dynurl.conf configuration file. For example:

/mapto/@test-http/mapfrom/*
/@test-http/mapto/mapfrom/*

Parent topic: Virtual Hosting

Using domain session cookies for virtual host single sign-onUsing domain session cookies for virtual host single sign-onYou can use domain cookies to support single sign-on and the sharing of a single credential across multiple virtual host junctions in the same WebSEAL instance. virtual hostsuse domain cookiesdomain cookiescookiesdomainsession-cookie-domains stanzaweb-host-name stanza entry WebSEAL normally uses host cookies for cookie-based session identification. A browser returns a host cookie to the originating host only. Using host cookies in a virtual host environment results in each virtual host that has its own login and credentials. Use domain cookies if all virtual hosts are on the same WebSEAL instance and contain the same network domain name. Alternatively, you can configure a distributed session cache environment to support single sign-on across multiple virtual hosts. In a distributed session cache environment, the session can be distributed between different WebSEAL instances. In an environment without the distributed session cache, you must set another configuration item for WebSEAL. Set another configuration to handle single sign-on across virtual host junctions in the same WebSEAL instance. The shared-domain-cookie configuration item in the [session] stanza of the WebSEAL configuration file must be set to yes. You do not need to use this configuration item in a distributed session cache environment. In a distributed session cache environment, this item must be set to no or not defined at all. Both standard WebSEAL junctions and virtual host junctions can support domain cookies: The domain that is used by the session cookie for a specific virtual host junction is determined by the closest match to an entry in the [session-cookie-domains] stanza.The domain that is used by the session cookie for a specific standard WebSEAL junction is determined by the closest match to the value of the web-host-name entry in the [server] stanza. If there is no match, then a host type cookie is used. Other instances of WebSEAL in the same domain also receive the same domain cookies that are configured for a particular WebSEAL instance. You can customize the names of the WebSEAL session cookies for a specific WebSEAL instance. The WebSEAL instance configuration file provides default names for both TCP and SSL cookies: [session] tcp-session-cookie-name = PD-H-SESSION-ID ssl-session-cookie-name = PD-S-SESSION-ID See, Customization of the session cookie name.To enable domain cookies, modify the WebSEAL configuration file to specify the names of the appropriate domains where domain type cookies are to be used.For example:[session-cookie-domains] domain = ibm.com domain = cruz.tivoli.comMatching example:[session-cookie-domains] domain = ibm.com domain = tivoli.comVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Using domain session cookies for virtual host single sign-on

You can use domain cookies to support single sign-on and the sharing of a single credential across multiple virtual host junctions in the same WebSEAL instance.

About this task

WebSEAL normally uses host cookies for cookie-based session identification. A browser returns a host cookie to the originating host only. Using host cookies in a virtual host environment results in each virtual host that has its own login and credentials.

Use domain cookies if all virtual hosts are on the same WebSEAL instance and contain the same network domain name.

Alternatively, you can configure a distributed session cache environment to support single sign-on across multiple virtual hosts. In a distributed session cache environment, the session can be distributed between different WebSEAL instances.

In an environment without the distributed session cache, you must set another configuration item for WebSEAL. Set another configuration to handle single sign-on across virtual host junctions in the same WebSEAL instance. The shared-domain-cookie configuration item in the [session] stanza of the WebSEAL configuration file must be set to yes. You do not need to use this configuration item in a distributed session cache environment. In a distributed session cache environment, this item must be set to no or not defined at all.

Both standard WebSEAL junctions and virtual host junctions can support domain cookies:

The domain that is used by the session cookie for a specific virtual host junction is determined by the closest match to an entry in the [session-cookie-domains] stanza.

The domain that is used by the session cookie for a specific standard WebSEAL junction is determined by the closest match to the value of the web-host-name entry in the [server] stanza.

If there is no match, then a host type cookie is used.

Other instances of WebSEAL in the same domain also receive the same domain cookies that are configured for a particular WebSEAL instance. You can customize the names of the WebSEAL session cookies for a specific WebSEAL instance. The WebSEAL instance configuration file provides default names for both TCP and SSL cookies:

[session]
tcp-session-cookie-name = PD-H-SESSION-ID
ssl-session-cookie-name = PD-S-SESSION-ID

See, Customization of the session cookie name.

Procedure

To enable domain cookies, modify the WebSEAL configuration file to specify the names of the appropriate domains where domain type cookies are to be used. For example:

[session-cookie-domains]
domain = ibm.com
domain = cruz.tivoli.com

Example

Matching example:

[session-cookie-domains]
domain = ibm.com
domain = tivoli.com

Parent topic: Virtual Hosting

Technical notes for using domain cookies with virtual hostsTechnical notes for using domain cookies with virtual hostsWhen you are using domain cookies with virtual hosts, consider the following points.virtual hostsnotes on domain cookiesdomain cookiestechnical notesvirtual hoststechnical notesdomain cookiesvirtual hosts Security warning! It is possible for an untrusted host to exist among the collection of hosts for a specific domain.To use domain cookies, all virtual hosts must be in the same DNS domain.You can do single sign-on across virtual host junctions in the same WebSEAL instance with WebSEAL alone. Alternatively, you can configure a distributed session cache environment to do single sign-on across virtual host junctions, which can be distributed across WebSEAL instances.If you are using the distributed session cache to achieve single sign-on across virtual host junctions, you must not enable the shared-domain-cookie configuration item. Enable the configuration in the WebSEAL [session] stanza.See, Single signon in a replica setA distributed session cache environment provides a single sign-on solution by sharing sessions across servers in a replica set..Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Technical notes for using domain cookies with virtual hosts

When you are using domain cookies with virtual hosts, consider the following points.

Security warning! It is possible for an untrusted host to exist among the collection of hosts for a specific domain.

To use domain cookies, all virtual hosts must be in the same DNS domain.

You can do single sign-on across virtual host junctions in the same WebSEAL instance with WebSEAL alone. Alternatively, you can configure a distributed session cache environment to do single sign-on across virtual host junctions, which can be distributed across WebSEAL instances.

If you are using the distributed session cache to achieve single sign-on across virtual host junctions, you must not enable the shared-domain-cookie configuration item. Enable the configuration in the WebSEAL [session] stanza.

See, Single signon in a replica set.

Parent topic: Virtual Hosting

Scenario 3: Advanced virtual host configurationScenario 3: Advanced virtual host configurationLearn how to set up forms authentication, single signon using e-community, and authenticated access to specific resources.virtual host junctionsscenario 3: advanced virtual host configurationscenariosadvanced virtual host configurationvirtual hostsadvanced configurationThe following scenario is based on scenario 2. The scenario additionally sets up: Forms authentication.Single signon using e-community.Authenticated access to specific resources.Required architecture: Single signon is required between all hosts and protocols. Each virtual host has its own session credential. Standard e-community SSO logout restrictions apply.Forms login is requiredAuthenticated-only access is required for the following resources: http(s)://a.b.com/sales/https://w.x.com/doc/https://y.z.com/code/ Virtual host junction scenario 3Virtual host junction scenario 3Procedure - general setup: Enable forms authentication for both HTTP and HTTPS: [ba] ba-auth = none [forms] forms-auth = bothConfigure e-community single signon: [e-community-sso] e-community-sso-auth = both e-community-name = ecomm is-master-authn-server = yes master-authn-server = a.b.com [e-community-domain-keys] [e-community-domains] name = b.com name = x.com name = z.com name = ibm.com [e-community-domain-keys:b.com] b.com = bb.key x.com = bx.key z.com = bz.key [e-community-domain-keys:x.com] x.com = xx.key b.com = bx.key [e-community-domain-keys:z.com] z.com = zz.key b.com = bz.key Use the LMI to generate the following keys:bb.keybx.keybz.keyxx.keyzz.keyRestart WebSEAL and login as sec_master to the pdadmin command.Procedure - control access to /restricted directories: Create an open (unrestricted) ACL for general unauthenticated access: pdadmin> sec_master> acl create open pdadmin> sec_master> acl modify open set user sec_master TcmdbsvaBRlrx pdadmin> sec_master> acl modify open set any-other Trx pdadmin> sec_master> acl modify open set unauthenticated Trx pdadmin> sec_master> acl modify open set group iv-admin TcmdbsvaBRrxl pdadmin> sec_master> acl modify open set group webseal-servers TgmdbsrxlCreate a restricted ACL for access that requires authentication: pdadmin> sec_master> acl create restricted pdadmin> sec_master> acl modify restricted set group iv-admin TcmdbsvaBRrxl pdadmin> sec_master> acl modify restricted set group webseal-servers Tgmdbsrxl pdadmin> sec_master> acl modify restricted set user sec_master TcmdbsvaBRlrx pdadmin> sec_master> acl modify restricted set any-other Trx pdadmin> sec_master> acl modify restricted set unauthenticated TAttach the open ACL to the default WebSEAL instance: pdadmin> sec_master> acl attach /WebSEAL/webseal.ibm.com-default openAttach the restricted ACL to the /sales directory on a.b.com (entered as one line): pdadmin sec_master> acl attach /WebSEAL/webseal.ibm.com-default/@vhost-ab-tcp/sales restrictedAttach the restricted ACL to the /doc directory on w.x.com (entered as one line): pdadmin sec_master> acl attach WebSEAL/webseal.ibm.com-default/@vhost-wx-tcp/doc restrictedAttach the restricted ACL to the /code directory on y.z.com (entered as one line): pdadmin sec_master> acl attach /WebSEAL/webseal.ibm.com-default/@vhost-yz-ssl/code restrictedVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Scenario 3: Advanced virtual host configuration

Learn how to set up forms authentication, single signon using e-community, and authenticated access to specific resources.

The following scenario is based on scenario 2. The scenario additionally sets up:

Forms authentication.

Single signon using e-community.

Authenticated access to specific resources.

Required architecture:

Single signon is required between all hosts and protocols. Each virtual host has its own session credential. Standard e-community SSO logout restrictions apply.

Forms login is required

Authenticated-only access is required for the following resources:

http(s)://a.b.com/sales/

https://w.x.com/doc/

https://y.z.com/code/

Figure 41. Virtual host junction scenario 3

Procedure - general setup:

Enable forms authentication for both HTTP and HTTPS:

[ba]
ba-auth = none

[forms]
forms-auth = both

Configure e-community single signon:

[e-community-sso]
e-community-sso-auth = both
e-community-name = ecomm
is-master-authn-server = yes
master-authn-server = a.b.com

[e-community-domain-keys]

[e-community-domains]
name = b.com
name = x.com
name = z.com
name = ibm.com

[e-community-domain-keys:b.com]
b.com = bb.key
x.com = bx.key
z.com = bz.key

[e-community-domain-keys:x.com]
x.com = xx.key
b.com = bx.key

[e-community-domain-keys:z.com]
z.com = zz.key
b.com = bz.key

Use the LMI to generate the following keys:

bb.key

bx.key

bz.key

xx.key

zz.key

Restart WebSEAL and login as sec_master to the pdadmin command.

Procedure - control access to /restricted directories:

Create an open (unrestricted) ACL for general unauthenticated access:

pdadmin> sec_master> acl create open
pdadmin> sec_master> acl modify open set user sec_master TcmdbsvaBRlrx
pdadmin> sec_master> acl modify open set any-other Trx
pdadmin> sec_master> acl modify open set unauthenticated Trx
pdadmin> sec_master> acl modify open set group iv-admin TcmdbsvaBRrxl
pdadmin> sec_master> acl modify open set group webseal-servers Tgmdbsrxl

Create a restricted ACL for access that requires authentication:

pdadmin> sec_master> acl create restricted
pdadmin> sec_master> acl modify restricted set group iv-admin TcmdbsvaBRrxl
pdadmin> sec_master> acl modify restricted set group webseal-servers Tgmdbsrxl
pdadmin> sec_master> acl modify restricted set user sec_master TcmdbsvaBRlrx
pdadmin> sec_master> acl modify restricted set any-other Trx
pdadmin> sec_master> acl modify restricted set unauthenticated T

Attach the open ACL to the default WebSEAL instance:

pdadmin> sec_master> acl attach /WebSEAL/webseal.ibm.com-default open

Attach the restricted ACL to the /sales directory on a.b.com (entered as one line):

pdadmin sec_master> acl attach
/WebSEAL/webseal.ibm.com-default/@vhost-ab-tcp/sales restricted

Attach the restricted ACL to the /doc directory on w.x.com (entered as one line):

pdadmin sec_master> acl attach
WebSEAL/webseal.ibm.com-default/@vhost-wx-tcp/doc restricted

Attach the restricted ACL to the /code directory on y.z.com (entered as one line):

pdadmin sec_master> acl attach
/WebSEAL/webseal.ibm.com-default/@vhost-yz-ssl/code restricted

Parent topic: Virtual Hosting

SSL session IDs not usable by virtual hostsSSL session IDs not usable by virtual hostsSSL session IDs are not usable for maintaining login sessions between a browser and different virtual hosts that are on the same WebSEAL instance.virtual hostsSSL session IDs not usableSSLsession IDsvirtual hostsVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

SSL session IDs not usable by virtual hosts

SSL session IDs are not usable for maintaining login sessions between a browser and different virtual hosts that are on the same WebSEAL instance.

Parent topic: Virtual Hosting

Using pdadmin server task to create virtual host junctionsUsing pdadmin server task to create virtual host junctionsLearn how to use pdadmin commands so that you can create virtual host junctions. pdadmin server taskvirtual hostcreationjunctionspdadmin server task virtualhostsvirtual host junctionspdadmin server taskpdadmin server listget full server nameYou must log in to a secure domain as a user with administration authorization, such as sec_master before you use pdadmin. For example: pdadmin> login Enter User ID: sec_master Enter Password: pdadmin>The pdadmin utility provides an interactive command-line prompt where you can do WebSEAL virtual host junction tasks. Use the pdadmin server task virtualhost command to create WebSEAL virtual host junctions. See the Web command reference topics in the IBM Knowledge Center for complete syntax information for the pdadmin utility. Options for standard WebSEAL junctions are described in Command option summary: standard junctions.To create virtual host junctions, you use the pdadmin server task virtualhost create command (entered as one line): pdadmin> server task instance_name-webseald-host_name virtualhost create options vhost-labelFor example, if the configured name of a single WebSEAL instance is web1 installed on a host that is named www.pubs.com, the complete server name is:web1-webseald-www.pubs.comUse the pdadmin server list command to display the correct format of the complete server name:pdadmin> server list web1-webseald-www.pubs.comFor more information, see the pdadmin server task virtualhost create in Command reference or server task virtualhost createThe server task virtualhost create command creates a virtual host junction..Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Using pdadmin server task to create virtual host junctions

Learn how to use pdadmin commands so that you can create virtual host junctions.

Before you begin

You must log in to a secure domain as a user with administration authorization, such as sec_master before you use pdadmin.

For example:

pdadmin> login
Enter User ID: sec_master
Enter Password:
pdadmin>

About this task

The pdadmin utility provides an interactive command-line prompt where you can do WebSEAL virtual host junction tasks. Use the pdadmin server task virtualhost command to create WebSEAL virtual host junctions. See the Web command reference topics in the IBM Knowledge Center for complete syntax information for the pdadmin utility. Options for standard WebSEAL junctions are described in Command option summary: standard junctions.

Procedure

To create virtual host junctions, you use the pdadmin server task virtualhost create command (entered as one line):

pdadmin> server task instance_name-webseald-host_name virtualhost create
options vhost-label

For example, if the configured name of a single WebSEAL instance is web1 installed on a host that is named www.pubs.com, the complete server name is:

web1-webseald-www.pubs.com

Use the pdadmin server list command to display the correct format of the complete server name:

pdadmin> server list
web1-webseald-www.pubs.com

For more information, see the pdadmin server task virtualhost create in Command reference or server task virtualhost create.

Parent topic: Virtual Hosting

Server task commands for virtual host junctionsServer task commands for virtual host junctionsWebSEAL server task commands for virtual host junctionsLearn about the available virtual junction commands so that you do actions such as add, create, and delete virtual host junctions.pdadmin server taskvirtualhostcreateaddremovethrottledeletelistshowofflineonlineThe following virtual host junction commands are available with pdadmin server task virtualhost: CommandDescriptionvirtualhost add Add more servers to an existing virtual host junction. Syntax: virtualhost add options vhost-label See Addition of a server to a virtual host junctionThe virtualhost add command adds another server to a virtual host junction. .virtualhost create Create a new virtual host junction for an initial server. Syntax: virtualhost create options vhost-label See Creation of a virtual host junctionThe virtualhost create command creates a new virtual host junction..virtualhost delete Remove the specified virtual host junction. A virtual host junction cannot be deleted if a second virtual host junction refers to it through the -g option. An error message is returned at such an attempt. Syntax: virtualhost delete vhost-labelvirtualhost list List all configured virtual host junctions by label name. Syntax: virtualhost listvirtualhost offline Places the server that is at this virtual host junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, then all servers that are at this virtual host junction are placed in an offline operational state. Syntax: virtualhost offline [-i server_uuid] vhost_labelvirtualhost online Places the server that is at this virtual host junction in an online operational state. The server now resumes normal operation. If a server is not specified, then all servers that are at this virtual host junction are placed in an online operational state. Syntax: virtualhost online [-i server_uuid] vhost_labelvirtualhost remove Remove the specified server from a virtual host junction. Syntax: virtualhost remove –i server-id vhost-label Use the virtualhost show command to determine the ID of a particular server.virtualhost show Display the details of a virtual host junction with the specified label. Syntax: virtualhost show vhost-labelvirtualhost throttle Places the server that is at this virtual host junction in a throttled operational state. Only requests from users with a session with WebSEAL before the invocation of this command continues to have their requests processed by the specified server. If a server is not specified, then all servers at this virtual host junction are placed in a throttled operational state. Syntax: virtualhost throttle [-i server_uuid] vhost_labelVirtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Server task commands for virtual host junctions

Learn about the available virtual junction commands so that you do actions such as add, create, and delete virtual host junctions.

The following virtual host junction commands are available with pdadmin server task virtualhost:

Command
Description

virtualhost add

Add more servers to an existing virtual host junction.

Syntax:

virtualhost add options vhost-label

See Addition of a server to a virtual host junction.

virtualhost create

Create a new virtual host junction for an initial server.

Syntax:

virtualhost create options vhost-label

See Creation of a virtual host junction.

virtualhost delete

Remove the specified virtual host junction.

A virtual host junction cannot be deleted if a second virtual host junction refers to it through the -g option. An error message is returned at such an attempt.

Syntax:

virtualhost delete vhost-label

virtualhost list

List all configured virtual host junctions by label name.

Syntax:

virtualhost list

virtualhost offline

Places the server that is at this virtual host junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, then all servers that are at this virtual host junction are placed in an offline operational state.

Syntax:

virtualhost offline [-i server_uuid] vhost_label

virtualhost online

Places the server that is at this virtual host junction in an online operational state. The server now resumes normal operation. If a server is not specified, then all servers that are at this virtual host junction are placed in an online operational state.

Syntax:

virtualhost online [-i server_uuid] vhost_label

virtualhost remove

Remove the specified server from a virtual host junction.

Syntax:

virtualhost remove –i server-id vhost-label

Use the virtualhost show command to determine the ID of a particular server.

virtualhost show

Display the details of a virtual host junction with the specified label.

Syntax:

virtualhost show vhost-label

virtualhost throttle

Places the server that is at this virtual host junction in a throttled operational state. Only requests from users with a session with WebSEAL before the invocation of this command continues to have their requests processed by the specified server. If a server is not specified, then all servers at this virtual host junction are placed in a throttled operational state.

Syntax:

virtualhost throttle [-i server_uuid] vhost_label

Parent topic: Virtual Hosting

Creation of a virtual host junctionCreation of a virtual host junctionThe virtualhost create command creates a new virtual host junction.virtual host junctionscreatingcreationvirtual host junctionsOperation: Creates a new virtual host junction.Syntax: virtualhost create -t type -h host-name options vhost-label -t typeType of virtual host junction. Specify tcp, ssl, tcpproxy, sslproxy, localtcp, or localssl. Default port for –t tcp is 80. Default port for –t ssl is 443.This parameter is required. -h host-nameThe DNS host name or IP address of the target back-end server. This parameter is required for tcp, ssl, tcpproxy, sslproxy type junctions. optionsSee Table 1.vhost-labelThe name for the virtual host junction. This junction label is used to indicate the junction in the display of the protected object space. You can refer to a junction in the pdadmin utility by using this label. This parameter is required. See Creation of a remote type virtual host junctionYou must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server..Options on the virtualhost create command Virtual host junction typeParameterDescriptionVirtual host option–v vhost-name[:port]]WebSEAL selects a virtual host junction to process a request if the request's HTTP Host header matches the virtual host name and port number specified by the -v option.The -v option is also used to specify the value of the Host header of the request sent to the back-end server.The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.If -v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions, then the junction is selected from the information in the -h host and -p port options.The -v option is required for localtcp and localssl type junctions.See Creation of a remote type virtual host junctionYou must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server..Virtual host option–g vhost-labelThe -g option causes a second virtual host junction to share a protected object space as the initial virtual host junction.This option is appropriate for junction pairs only (two junctions with complementary protocols). The option does not support the association of more than two junctions.Optional. See Creation of a remote type virtual host junctionYou must understand how to use the available commands so that you can create a remote type virtual host junction. Some of the options include the type of junction and the host name of the target server..General option for TCP and SSL junction types–a addressSpecifies the local IP address that WebSEAL uses when it is communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system.If you supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.General option for TCP and SSL junction types–fForce the replacement (overwrite) of an existing virtual host junction.See Forcing a new junction.General option for TCP and SSL junction types–iWebSEAL server treats URLs as case insensitive.See Support for URLs as not case-sensitive.General option for TCP and SSL junction types–p portTCP port of the back-end third-party server. Default is 80 for TCP junctions. Use 443 for SSL junctions.See Creating TCP type standard junctions and Creating SSL type standard junctions.General option for TCP and SSL junction types–q pathProvides WebSEAL with the correct name of the query_contents program file and where to find the file. By default, the Windows file is called query_contents.exe and the UNIX file is called query_contents.sh. By default, WebSEAL looks for the file in the cgi_bin directory of the back-end web server.Required for back-end Windows and UNIX web servers.See Installing and configuring query_contents on Windows-based Web serversThe following steps describe the installation of query_contents on back-end Windows-based Web servers..General option for TCP and SSL junction types–T resource/resource-groupName of GSO resource or resource group. Required for and used only with –b gso option.See Configuring a GSO-enabled WebSEAL junctionUse the create command with the –b gso option to create a junction that enables GSO. .General option for TCP and SSL junction types–wWindows 32-bit (Win32) file system support.See Junctions to Windows file systems.Stateful junctionsSee Stateful junctions.–sSpecifies that the virtual host junction support stateful applications. By default, junctions are not stateful.Stateful junctionsSee Stateful junctions.–u UUIDSpecifies the UUID of a back-end server that is connected to WebSEAL with a stateful virtual host junction (–s).Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–BWebSEAL uses BA header information to authenticate to back-end virtual host. Requires –U, and –W options.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–D "DN"Specify Distinguished Name of back-end server certificate. This value, matched with actual certificate DN enhances authentication.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–K "key-label"Key label of WebSEAL's client-side certificate, used to authenticate to back-end virtual host.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–U "username"WebSEAL user name. Use with –B to send BA header information to back-end server.Mutual authentication over Basic Authentication and SSL certificatesSee Mutually authenticated SSL junctions.–W "password"WebSEAL password. Use with –B to send BA header information to back-end server.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–H host-nameThe DNS host name or IP address of the proxy server.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–P portThe TCP port of the proxy server.Supply identity information in HTTP headers–b BA-valueDefines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the back-end virtual host. One of:filter (default), ignore, supply, gsoSee Client identity in HTTP BA headersYou can configure WebSEAL junctions to supply the back-end server with original or modified client identity information. Understand the options available so that you can specify the required information in the HTTP basic authentication headers..Supply identity information in HTTP headers–c header-typesInsert client identity information specific to Security Access Manager in HTTP headers across the virtual host junction. The header-types argument can include any combination of the following Security Access Manager HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all. See Client identity in HTTP headers (–c)Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers..Supply identity information in HTTP headers–e encoding-typeSpecifies the encoding to use when you generate HTTP headers for virtual host junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. The following list shows the possible values for encoding:utf8_binutf8_urilcp_binlcp_uriSee UTF-8 encoding for HTTP header data.Supply identity information in HTTP headers–INOT VALID. This option is not valid because cookie handling is not required over virtual host junctions.Supply identity information in HTTP headers–jNOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.Supply identity information in HTTP headers–J trailer[,onfocus]NOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.Supply identity information in HTTP headers–kSend session cookie to back-end virtual host.See Passing of session cookies to junctioned portal serversA Web portal is a server that offers a broad array of personalized resources and services. The –k junction option allows you to send the Security Access Manager session cookie (originally established between the client and WebSEAL) to a back-end portal server. .Supply identity information in HTTP headers–nNOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.Supply identity information in HTTP headers–rInsert incoming IP address in HTTP header across the virtual host junction.See Client IP addresses in HTTP headers (–r).Junction fairness–l percent-valueDefines the soft limit for consumption of worker threads.Junction fairness–L percent-valueDefines the hard limit for consumption of worker threads.WebSphere single signon (LTPA) junctionsSee Configuration of an LTPA junctionUnderstand the configuration requirements and the commands you need to set up an LTPA junction..–AEnables virtual host junctions to support LTPA cookies (tokens). LTPA version 1 cookies (LtpaToken) and LTPA version 2 cookies (LtpaToken2) are both supported. LTPA version 1 cookies are specified by default. LTPA version 2 cookies must be specified with the additional -2 option.Also requires –F, and –Z options.WebSphere single signon (LTPA) junctionsSee Configuration of an LTPA junctionUnderstand the configuration requirements and the commands you need to set up an LTPA junction..–2Used with the -A option, this option specifies that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.WebSphere single signon (LTPA) junctionsSee Configuration of an LTPA junctionUnderstand the configuration requirements and the commands you need to set up an LTPA junction..–F "keyfile"Name of the key file that is used to encrypt LTPA cookie data. Only valid with –A option.WebSphere single signon (LTPA) junctionsSee Configuration of an LTPA junctionUnderstand the configuration requirements and the commands you need to set up an LTPA junction..–Z "keyfile-password"Password for the key file that is used to encrypt LTPA cookie data. Only valid with –A option.Tivoli Federated Identity Manager SSO junctionsSingle signon with Tivoli Federated Identity ManagerUnderstand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.-YEnables Tivoli Federated Identity Manager single-signon (SSO) for the junction.Before you use this option, you must first configure the WebSEAL configuration files to support Tivoli Federated Identity Manager single-signon over junctions.WebSEAL-to-WebSEAL SSL junctionsSee WebSEAL-to-WebSEAL junctions over SSL.–CMutual authentication between a front-end WebSEAL server and a back-end WebSEAL server over SSL. Requires –t ssl or –t sslproxy type.Forms single signonSee Forms single sign-on process flowLearn about the single sign-on process so that you understand how a client browser accesses a resource..–S pathName of the forms single signon configuration file.Transparent path junctions–xNOT VALID.Distributed session cache–z replica-set-nameFor distributed session cache environments, this parameter is optional. Specifies the replica set that sessions on the virtual host junction are managed under. It is specified so that you can group or separate log in sessions among multiple virtual hosts.If -z is not used to specify the replica set for the virtual host junction, the virtual host junction is automatically assigned to a replica set. The assigned replica set matches its virtual host name. For example, if the virtual host name is vhostA.example.com, the replica set is named vhostA.example.com. The replica set used for the virtual host junction must be present in the [replica-sets] stanza of the WebSEAL configuration file.For environments that do not use the distributed session cache, this option is not applicable.See Advanced configuration for the distributed session cacheThere are many advanced configuration options for integrating WebSEAL with a distributed session cache solution..Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Creation of a virtual host junction

The virtualhost create command creates a new virtual host junction.

Operation: Creates a new virtual host junction.

Syntax:

virtualhost create -t type -h host-name options vhost-label

-t type

Type of virtual host junction. Specify tcp, ssl, tcpproxy, sslproxy, localtcp, or localssl.

Default port for –t tcp is 80. Default port for –t ssl is 443.

This parameter is required.

-h host-name

The DNS host name or IP address of the target back-end server. This parameter is required for tcp, ssl, tcpproxy, sslproxy type junctions.

options

See Table 69.

vhost-label

The name for the virtual host junction. This junction label is used to indicate the junction in the display of the protected object space. You can refer to a junction in the pdadmin utility by using this label.

This parameter is required.

See Creation of a remote type virtual host junction.

Table 69. Options on the virtualhost create command

Virtual host junction type
Parameter
Description

Virtual host option
–v vhost-name[:port]]
WebSEAL selects a virtual host junction to process a request if the request's HTTP Host header matches the virtual host name and port number specified by the -v option.

The -v option is also used to specify the value of the Host header of the request sent to the back-end server.

The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.

If -v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions, then the junction is selected from the information in the -h host and -p port options.

The -v option is required for localtcp and localssl type junctions.

See Creation of a remote type virtual host junction.

Virtual host option
–g vhost-label
The -g option causes a second virtual host junction to share a protected object space as the initial virtual host junction.

This option is appropriate for junction pairs only (two junctions with complementary protocols). The option does not support the association of more than two junctions.

Optional. See Creation of a remote type virtual host junction.

General option for TCP and SSL junction types
–a address
Specifies the local IP address that WebSEAL uses when it is communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system.

If you supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.

General option for TCP and SSL junction types
–f
Force the replacement (overwrite) of an existing virtual host junction.

See Forcing a new junction.

General option for TCP and SSL junction types
–i
WebSEAL server treats URLs as case insensitive.

See Support for URLs as not case-sensitive.

General option for TCP and SSL junction types
–p port
TCP port of the back-end third-party server. Default is 80 for TCP junctions. Use 443 for SSL junctions.

See Creating TCP type standard junctions and Creating SSL type standard junctions.

General option for TCP and SSL junction types
–q path
Provides WebSEAL with the correct name of the query_contents program file and where to find the file. By default, the Windows file is called query_contents.exe and the UNIX file is called query_contents.sh. By default, WebSEAL looks for the file in the cgi_bin directory of the back-end web server.

Required for back-end Windows and UNIX web servers.

See Installing and configuring query_contents on Windows-based Web servers.

General option for TCP and SSL junction types
–T resource/resource-group
Name of GSO resource or resource group. Required for and used only with –b gso option.

See Configuring a GSO-enabled WebSEAL junction.

General option for TCP and SSL junction types
–w
Windows 32-bit (Win32) file system support.

See Junctions to Windows file systems.

Stateful junctions

See Stateful junctions.

–s
Specifies that the virtual host junction support stateful applications. By default, junctions are not stateful.

Stateful junctions

See Stateful junctions.

–u UUID
Specifies the UUID of a back-end server that is connected to WebSEAL with a stateful virtual host junction (–s).

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–B
WebSEAL uses BA header information to authenticate to back-end virtual host. Requires –U, and –W options.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–D "DN"
Specify Distinguished Name of back-end server certificate. This value, matched with actual certificate DN enhances authentication.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–K "key-label"
Key label of WebSEAL's client-side certificate, used to authenticate to back-end virtual host.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–U "username"
WebSEAL user name. Use with –B to send BA header information to back-end server.

Mutual authentication over Basic Authentication and SSL certificates

See Mutually authenticated SSL junctions.

–W "password"
WebSEAL password. Use with –B to send BA header information to back-end server.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–H host-name
The DNS host name or IP address of the proxy server.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–P port
The TCP port of the proxy server.

Supply identity information in HTTP headers
–b BA-value
Defines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the back-end virtual host. One of:

filter (default), ignore, supply, gso

See Client identity in HTTP BA headers.

Supply identity information in HTTP headers
–c header-types
Insert client identity information specific to Security Access Manager in HTTP headers across the virtual host junction. The header-types argument can include any combination of the following Security Access Manager HTTP header types: iv-user, iv-user-l, iv-groups, iv-creds, all.

See Client identity in HTTP headers (–c).

Supply identity information in HTTP headers
–e encoding-type
Specifies the encoding to use when you generate HTTP headers for virtual host junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. The following list shows the possible values for encoding:

utf8_bin

utf8_uri

lcp_bin

lcp_uri

See UTF-8 encoding for HTTP header data.

Supply identity information in HTTP headers
–I
NOT VALID. This option is not valid because cookie handling is not required over virtual host junctions.

Supply identity information in HTTP headers
–j
NOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.

Supply identity information in HTTP headers
–J trailer[,onfocus]

NOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.

Supply identity information in HTTP headers
–k
Send session cookie to back-end virtual host.

See Passing of session cookies to junctioned portal servers.

Supply identity information in HTTP headers
–n
NOT VALID. This option is not valid because the junction cookie solution is not required over virtual host junctions.

Supply identity information in HTTP headers
–r
Insert incoming IP address in HTTP header across the virtual host junction.

See Client IP addresses in HTTP headers (–r).

Junction fairness
–l percent-value
Defines the soft limit for consumption of worker threads.

Junction fairness
–L percent-value
Defines the hard limit for consumption of worker threads.

WebSphere single signon (LTPA) junctions

See Configuration of an LTPA junction.

–A
Enables virtual host junctions to support LTPA cookies (tokens). LTPA version 1 cookies (LtpaToken) and LTPA version 2 cookies (LtpaToken2) are both supported. LTPA version 1 cookies are specified by default. LTPA version 2 cookies must be specified with the additional -2 option.

Also requires –F, and –Z options.

WebSphere single signon (LTPA) junctions

See Configuration of an LTPA junction.

–2
Used with the -A option, this option specifies that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

WebSphere single signon (LTPA) junctions

See Configuration of an LTPA junction.

–F "keyfile"
Name of the key file that is used to encrypt LTPA cookie data. Only valid with –A option.

WebSphere single signon (LTPA) junctions

See Configuration of an LTPA junction.

–Z "keyfile-password"
Password for the key file that is used to encrypt LTPA cookie data. Only valid with –A option.

Tivoli Federated Identity Manager SSO junctions

Single signon with Tivoli Federated Identity Manager

-Y
Enables Tivoli® Federated Identity Manager single-signon (SSO) for the junction.

Note: Before you use this option, you must first configure the WebSEAL configuration files to support Tivoli Federated Identity Manager single-signon over junctions.

WebSEAL-to-WebSEAL SSL junctions

See WebSEAL-to-WebSEAL junctions over SSL.

–C
Mutual authentication between a front-end WebSEAL server and a back-end WebSEAL server over SSL. Requires –t ssl or –t sslproxy type.

Forms single signon

See Forms single sign-on process flow.

–S path
Name of the forms single signon configuration file.

Transparent path junctions
–x
NOT VALID.

Distributed session cache
–z replica-set-name
For distributed session cache environments, this parameter is optional. Specifies the replica set that sessions on the virtual host junction are managed under. It is specified so that you can group or separate log in sessions among multiple virtual hosts.

If -z is not used to specify the replica set for the virtual host junction, the virtual host junction is automatically assigned to a replica set. The assigned replica set matches its virtual host name. For example, if the virtual host name is vhostA.example.com, the replica set is named vhostA.example.com. The replica set used for the virtual host junction must be present in the [replica-sets] stanza of the WebSEAL configuration file.

For environments that do not use the distributed session cache, this option is not applicable.

See Advanced configuration for the distributed session cache.

Parent topic: Virtual Hosting

Addition of a server to a virtual host junctionAddition of a server to a virtual host junctionThe virtualhost add command adds another server to a virtual host junction. virtual host junctionsadd a serverserversaddition to a virtual host junctionOperation: Adds another server to an existing virtual host junction.Syntax: virtualhost add -h host-name options vhost-label-h host-nameThe DNS host name or IP address of the proxy server. This parameter is required. See Standard WebSEAL junction configuration.optionsSee Table 1.vhost-labelThe name for the virtual host junction where the additional back-end server is added.This parameter is required. Options on the virtualhost add commandVirtual host optionParameterDescriptionGeneral option for TCP and SSL junction types–a addressSpecifies the local IP address that WebSEAL uses when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system. If you supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.General option for TCP and SSL junction types–iWebSEAL server treats URLs as case insensitive. See Support for URLs as not case-sensitive.General option for TCP and SSL junction types–p portTCP port of the back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions. See Creating TCP type standard junctions and Creating SSL type standard junctions.General option for TCP and SSL junction types–q urlRelative path for query_contents script. By default, WebSEAL looks for query_contents in /cgi_bin/. If this directory is different or the query_contents file name is different, use this option to indicate to WebSEAL the new URL to the file. Required for back-end Windows servers. See Installing and configuring query_contents on Windows-based Web serversThe following steps describe the installation of query_contents on back-end Windows-based Web servers..General option for TCP and SSL junction types–wWindows file system support. See Junctions to Windows file systems.Stateful junctionsSee Stateful junctions.–u UUIDSpecifies the UUID of a back-end server that is connected to WebSEAL in a stateful virtual host junction (–s).Mutual authentication over SSLSee Mutually authenticated SSL junctions.–D "DN"Specify Distinguished Name of back-end server certificate. This value, matched with actual certificate DN enhances authentication.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–H host nameDNS host name or IP address of the proxy server.Proxy junction (requires –t tcpproxy or –t sslproxy)See TCP and SSL proxy junctions.–P portThe TCP port of the proxy server.Virtual HostingUse the virtual hosting feature to maintain more than one server on one machine. You can use virtual hosting to run multiple web services, each with a different host name and URL.

Addition of a server to a virtual host junction

The virtualhost add command adds another server to a virtual host junction.

Operation: Adds another server to an existing virtual host junction.

Syntax:

virtualhost add -h host-name options vhost-label

-h host-name

The DNS host name or IP address of the proxy server. This parameter is required. See Standard WebSEAL junction configuration.

options

See Table 70.

vhost-label

The name for the virtual host junction where the additional back-end server is added.

This parameter is required.

Table 70. Options on the virtualhost add command

Virtual host option
Parameter
Description

General option for TCP and SSL junction types

–a address

Specifies the local IP address that WebSEAL uses when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system.

If you supply an address for a particular junction, WebSEAL binds to this local address for all communication with the junctioned server.

General option for TCP and SSL junction types

–i

WebSEAL server treats URLs as case insensitive.

See Support for URLs as not case-sensitive.

General option for TCP and SSL junction types

–p port

TCP port of the back-end third-party server. Default is 80 for TCP junctions; 443 for SSL junctions.

See Creating TCP type standard junctions and Creating SSL type standard junctions.

General option for TCP and SSL junction types

–q url

Relative path for query_contents script. By default, WebSEAL looks for query_contents in /cgi_bin/. If this directory is different or the query_contents file name is different, use this option to indicate to WebSEAL the new URL to the file. Required for back-end Windows servers.

See Installing and configuring query_contents on Windows-based Web servers.

General option for TCP and SSL junction types

–w

Windows file system support.

See Junctions to Windows file systems.

Stateful junctions

See Stateful junctions.

–u UUID

Specifies the UUID of a back-end server that is connected to WebSEAL in a stateful virtual host junction (–s).

Mutual authentication over SSL

See Mutually authenticated SSL junctions.

–D "DN"

Specify Distinguished Name of back-end server certificate. This value, matched with actual certificate DN enhances authentication.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–H host name

DNS host name or IP address of the proxy server.

Proxy junction (requires –t tcpproxy or –t sslproxy)

See TCP and SSL proxy junctions.

–P port

The TCP port of the proxy server.

Parent topic: Virtual Hosting

Single Signon SolutionsSingle Signon SolutionsWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Single signon with Tivoli Federated Identity ManagerUnderstand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.Single signon (SSO) conceptsUnderstand single signon concepts so that you can implement a solution that allows users to access resources with one initial login.Client identity in HTTP BA headersYou can configure WebSEAL junctions to supply the back-end server with original or modified client identity information. Understand the options available so that you can specify the required information in the HTTP basic authentication headers.Client identity and generic passwordAs an administrator, you must know how client identity and passwords are handled so that you understand how WebSEAL manages authentication in some scenarios.Limitations of the -b supply optionYou must understand the limitations of the -b supply option so that you can secure servers properly.Forwarding of original client BA header informationUnderstand how original client basic authentication information is sent to the back-end server without interference and the conditions that are required for this implementation. Removal of client BA header informationUnderstand how basic authentication header information is removed from client requests and the conditions that are required for this implementation.User names and passwords from GSOUnderstand how authentication information is obtained from a server that handles global signon and the conditions for this implementation.Client identity information across junctionsA junction can be set up to specify client identity information in BA headers. You must know the available options so that you can use the correct combination of options.Client identity in HTTP headers (–c)Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers.Conditions of use -c junctionsUnderstand how to use the -c junction option so that you can use the correct combinations to insert information into HTTP headers of requests.Client IP addresses in HTTP headers (–r)Limiting the size of WebSEAL-generated HTTP headersYou can limit the size of WebSEAL-generated HTTP headers that are inserted in requests to junctioned back-end servers so that they are not too large.Global sign-on overviewGlobal sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords.Authentication information mappingThe following example illustrates how the user registry provides authentication information to WebSEAL.Configuring a GSO-enabled WebSEAL junctionUse the create command with the –b gso option to create a junction that enables GSO. Configuration of the GSO cacheUse the global signon (GSO) cache function to improve the performance of GSO junctions in a high load environment.LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA).Forms single sign-on conceptsForms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.How to enable forms single signonLearn the command options to enable forms single signon so that you can configure the appropriate junction to support forms single signon.Forms single sign-on exampleThe following help site sample invokes its own forms-based login. The example shows how a forms single sign-on solution can provide seamless access to the site for its enrolled users.Single sign-on using Kerberos constrained delegationYou can set up constrained delegation by allowing WebSEAL to request a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC). The ticket can then be used by WebSEAL to impersonate the client to authenticate with the junctioned Web server.Cross-domain single signon conceptsConfiguration of cross-domain single signonExtended attributes for CDSSOCDSSO can handle extended attributes in two ways.Compatibility issues for CDSSOLTPA single signonE-community single signonE-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.Single sign-offYou can configure WebSEAL to initiate single sign-off from multiple protected web resources located on junctioned backend servers.

Single Signon Solutions

Single signon with Tivoli Federated Identity Manager
Understand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.

Single signon (SSO) concepts
Understand single signon concepts so that you can implement a solution that allows users to access resources with one initial login.

Client identity in HTTP BA headers
You can configure WebSEAL junctions to supply the back-end server with original or modified client identity information. Understand the options available so that you can specify the required information in the HTTP basic authentication headers.

Client identity and generic password
As an administrator, you must know how client identity and passwords are handled so that you understand how WebSEAL manages authentication in some scenarios.

Limitations of the -b supply option
You must understand the limitations of the -b supply option so that you can secure servers properly.

Forwarding of original client BA header information
Understand how original client basic authentication information is sent to the back-end server without interference and the conditions that are required for this implementation.

Removal of client BA header information
Understand how basic authentication header information is removed from client requests and the conditions that are required for this implementation.

User names and passwords from GSO
Understand how authentication information is obtained from a server that handles global signon and the conditions for this implementation.

Client identity information across junctions
A junction can be set up to specify client identity information in BA headers. You must know the available options so that you can use the correct combination of options.

Client identity in HTTP headers (–c)
Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers.

Conditions of use -c junctions
Understand how to use the -c junction option so that you can use the correct combinations to insert information into HTTP headers of requests.

Client IP addresses in HTTP headers (–r)

Limiting the size of WebSEAL-generated HTTP headers
You can limit the size of WebSEAL-generated HTTP headers that are inserted in requests to junctioned back-end servers so that they are not too large.

Global sign-on overview
Global sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords.

Authentication information mapping
The following example illustrates how the user registry provides authentication information to WebSEAL.

Configuring a GSO-enabled WebSEAL junction
Use the create command with the –b gso option to create a junction that enables GSO.

Configuration of the GSO cache
Use the global signon (GSO) cache function to improve the performance of GSO junctions in a high load environment.

LTPA overview
WebSEAL can provide authentication and authorization services and protection to an IBM® WebSphere® environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA).

Forms single sign-on concepts
Forms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.

How to enable forms single signon
Learn the command options to enable forms single signon so that you can configure the appropriate junction to support forms single signon.

Forms single sign-on example
The following help site sample invokes its own forms-based login. The example shows how a forms single sign-on solution can provide seamless access to the site for its enrolled users.

Single sign-on using Kerberos constrained delegation
You can set up constrained delegation by allowing WebSEAL to request a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC). The ticket can then be used by WebSEAL to impersonate the client to authenticate with the junctioned Web server.

Cross-domain single signon concepts

Configuration of cross-domain single signon

Extended attributes for CDSSO
CDSSO can handle extended attributes in two ways.

Compatibility issues for CDSSO

LTPA single signon

E-community single signon
E-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.

Single sign-off
You can configure WebSEAL to initiate single sign-off from multiple protected web resources located on junctioned backend servers.

Parent topic: Web Reverse Proxy configuration

Single signon with Tivoli Federated Identity ManagerSingle signon with Tivoli Federated Identity ManagerUnderstand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.single signonExamples of Tivoli Federated Identity Manager token types, which can be used for single sign-on: Kerberos credentials. LTPA tokens.SAML tokens.WebSEAL can obtain tokens, which can be used for single sign-on to junctions, from Tivoli Federated Identity Manager. Tivoli Federated Identity Manager can generate SSO tokens with STS modules, which are available in Tivoli Federated Identity Manager. WebSEAL retrieves Tivoli Federated Identity Manager SSO tokens by delegating the token request to the module in the following manner: The client authenticates to WebSEAL over HTTPS or HTTP and requests an object on the junctioned server. However, a Tivoli Federated Identity Manager SSO credential is required before access can be granted to the junctioned server.WebSEAL sends a Simple Object Access Protocol (SOAP) request to the STS module, requesting an SSO token.Tivoli Federated Identity Manager generates the token, which is based on the requirements of the STS module.Tivoli Federated Identity Manager returns the token to WebSEAL, and then WebSEAL forwards the token to the junction.A trust chain must be created in Tivoli Federated Identity Manager to handle the generation of the security token. The following table highlights the configuration requirements for the trust chain. Configuration requirements for a Tivoli Federated Identity Manager trust chainTrust Chain ElementRequirementRequest TypeIssue Oasis URILookup TypeUse Traditional WS-Trust Elements (AppliesTo, Issuer, and TokenType)AppliesToAddressCorresponds to the applies-to option in the [tfimsso:<jct id>]stanza of the WebSEAL configuration file.Service NameCorresponds to the service-name option in the [tfimsso:<jct id>] stanza of the WebSEAL configuration file Set fields in this entry to either: Asterisk (*) to match all service names, orThe second field must be set to the value defined by [tfimsso:<jct id>]service-nameRefer to the Tivoli Federated Identity Manager documentation for further details on configuring Trust Chains.Port TypeNot set.IssuerAddressamwebrte-sts-clientService nameNot set.Port TypeNot set.TokenTypeOne of the supported Tivoli Federated Identity Manager SSO token typesTrust Service Chain Modulescom.tivoli.am.fim.trustserver.sts.modules.STSTokenIVCred: -mode = validatecom.tivoli.am.fim.trustserver.sts.modules. any_STS_module: -mode = issueTo create a junction for Tivoli Federated Identity Manager single signon, use the junction create command (server task create) with option -Y. For more information, see "Options" under server task createThe server task create command creates a WebSEAL junction point. or server task virtualhost createThe server task virtualhost create command creates a virtual host junction.. The WebSEAL configuration file must be configured to support the specific junctions for Tivoli Federated Identity Manager single-signon before you can use the junction create command with option -Y.Configuration options for using the Tivoli Federated Identity Manager single signon approach is specified in the [tfimsso:<jct-id>] stanza. This stanza contains the Tivoli Federated Identity Manager single sign-on configuration information for a single junction. For standard junctions, the stanza name must be qualified with the name of the junction point, including the leading forward slash; for example: [tfimsso:/junction_a]. For virtual host junctions, the stanza name must be qualified with the virtual host label, for example: [tfimsso:www.ibm.com].The tfim-cluster-name option in the [tfimsso:<jct-id>] stanza defines the name of the WebSphere cluster for the Tivoli Federated Identity Manager service. Use the corresponding [tfim-cluster:<cluster>] stanza to specify options for the cluster.In the [tfim-cluster:<cluster>] server stanza entry, specify the priority level and URL for a web server that acts as a proxy for Tivoli Federated Identity Manager. The [tfim-cluster:<cluster>] stanza can contain multipleserver entries, which you can use to specify multiple server entries for failover and load balancing purposes. WebSEAL checks the status of the Tivoli Federated Identity Manager proxy web server every minute after the Tivoli Federated Identity Manager cluster is configured. Tivoli Federated Identity ManagerFor more information about these configuration options, see the [tfimsso:<jct-id>] and [tfim-cluster:<cluster>] stanzas in the IBM Security Web Gateway appliance: Web Reverse Proxy Stanza Reference.This method of single signon can be implemented only by using the STS module in Tivoli Federated Identity Manager. For more information, refer to Tivoli Federated Identity Manager documentation.Single Signon SolutionsGSKit configuration for connections with Tivoli Federated Identity ManagerThere are a number of GSKit attributes that you can use to control how GSKit creates SSL connections.Use of Kerberos credentialsKerberos delegated credentials are one of the token types that be provided by Tivoli Federated Identity Manager. Kerberos credentials that are generated by Tivoli Federated Identity Manager for single sign-on provides some advantages over traditional Asset Manager single signon mechanisms.

Single signon with Tivoli Federated Identity Manager

Understand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.

Examples of Tivoli Federated Identity Manager token types, which can be used for single sign-on:

Kerberos credentials.

LTPA tokens.

SAML tokens.

WebSEAL can obtain tokens, which can be used for single sign-on to junctions, from Tivoli Federated Identity Manager. Tivoli Federated Identity Manager can generate SSO tokens with STS modules, which are available in Tivoli Federated Identity Manager. WebSEAL retrieves Tivoli Federated Identity Manager SSO tokens by delegating the token request to the module in the following manner:

The client authenticates to WebSEAL over HTTPS or HTTP and requests an object on the junctioned server. However, a Tivoli Federated Identity Manager SSO credential is required before access can be granted to the junctioned server.

WebSEAL sends a Simple Object Access Protocol (SOAP) request to the STS module, requesting an SSO token.

Tivoli Federated Identity Manager generates the token, which is based on the requirements of the STS module.

Tivoli Federated Identity Manager returns the token to WebSEAL, and then WebSEAL forwards the token to the junction.

A trust chain must be created in Tivoli Federated Identity Manager to handle the generation of the security token. The following table highlights the configuration requirements for the trust chain.

Table 71. Configuration requirements for a Tivoli Federated Identity Manager trust chain

Trust Chain Element
Requirement

Request Type
Issue Oasis URI

Lookup Type
Use Traditional WS-Trust Elements (AppliesTo, Issuer, and TokenType)

AppliesTo

Address

Corresponds to the applies-to option in the [tfimsso:<jct id>]stanza of the WebSEAL configuration file.

Service Name

Corresponds to the service-name option in the [tfimsso:<jct id>] stanza of the WebSEAL configuration file

Note: Set fields in this entry to either:

Asterisk (*) to match all service names, or

The second field must be set to the value defined by [tfimsso:<jct id>]service-name

Refer to the Tivoli Federated Identity Manager documentation for further details on configuring Trust Chains.

Port Type

Not set.

Issuer

Address

amwebrte-sts-client

Service name

Not set.

Port Type

Not set.

TokenType
One of the supported Tivoli Federated Identity Manager SSO token types

Trust Service Chain Modules

com.tivoli.am.fim.trustserver.sts.modules.STSTokenIVCred:

-mode = validate

com.tivoli.am.fim.trustserver.sts.modules.

any_STS_module

: -mode = issue

To create a junction for Tivoli Federated Identity Manager single signon, use the junction create command (server task create) with option -Y. For more information, see "Options" under server task create or server task virtualhost create.

Note: The WebSEAL configuration file must be configured to support the specific junctions for Tivoli Federated Identity Manager single-signon before you can use the junction create command with option -Y.

Configuration options for using the Tivoli Federated Identity Manager single signon approach is specified in the [tfimsso:<jct-id>] stanza. This stanza contains the Tivoli Federated Identity Manager single sign-on configuration information for a single junction. For standard junctions, the stanza name must be qualified with the name of the junction point, including the leading forward slash; for example: [tfimsso:/junction_a]. For virtual host junctions, the stanza name must be qualified with the virtual host label, for example: [tfimsso:www.ibm.com].

The tfim-cluster-name option in the [tfimsso:<jct-id>] stanza defines the name of the WebSphere® cluster for the Tivoli Federated Identity Manager service. Use the corresponding [tfim-cluster:<cluster>] stanza to specify options for the cluster.

In the [tfim-cluster:<cluster>] server stanza entry, specify the priority level and URL for a web server that acts as a proxy for Tivoli Federated Identity Manager. The [tfim-cluster:<cluster>] stanza can contain multipleserver entries, which you can use to specify multiple server entries for failover and load balancing purposes. WebSEAL checks the status of the Tivoli Federated Identity Manager proxy web server every minute after the Tivoli Federated Identity Manager cluster is configured. Tivoli Federated Identity Manager

For more information about these configuration options, see the [tfimsso:<jct-id>] and [tfim-cluster:<cluster>] stanzas in the IBM Security Web Gateway appliance: Web Reverse Proxy Stanza Reference.

This method of single signon can be implemented only by using the STS module in Tivoli Federated Identity Manager. For more information, refer to Tivoli Federated Identity Manager documentation.

GSKit configuration for connections with Tivoli Federated Identity Manager
There are a number of GSKit attributes that you can use to control how GSKit creates SSL connections.

Use of Kerberos credentials
Kerberos delegated credentials are one of the token types that be provided by Tivoli Federated Identity Manager. Kerberos credentials that are generated by Tivoli Federated Identity Manager for single sign-on provides some advantages over traditional Asset Manager single signon mechanisms.

Parent topic: Single Signon Solutions

GSKit configuration for connections with Tivoli Federated Identity ManagerGSKit configurationThere are a number of GSKit attributes that you can use to control how GSKit creates SSL connections.GSKitconfigurationattributesWebSEALGSKit attributes for SSL connectionsYou can configure WebSEAL to use particular GSKit attributes when it initializes SSL connections. The gsk-attr-name configuration entry in the [tfim-cluster:<cluster>] stanza controls the GSKit attributes that WebSEAL uses when initializing a connection with Tivoli Federated Identity Manager. You can specify this configuration entry multiple times. Include each desired GSKit attribute as a new entry.[tfim-cluster:<cluster>] gsk-attr-name = {enum | string | number}:id:valueSimilar configuration entries exist in the [ssl] stanza for connections with clients and junctioned web servers. For further details about these configuration entries, see the Web Reverse Proxy Stanza Reference topics..Single signon with Tivoli Federated Identity ManagerUnderstand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.

GSKit configuration for connections with Tivoli Federated Identity Manager

There are a number of GSKit attributes that you can use to control how GSKit creates SSL connections.

You can configure WebSEAL to use particular GSKit attributes when it initializes SSL connections.

The gsk-attr-name configuration entry in the [tfim-cluster:<cluster>] stanza controls the GSKit attributes that WebSEAL uses when initializing a connection with Tivoli® Federated Identity Manager. You can specify this configuration entry multiple times. Include each desired GSKit attribute as a new entry.

[tfim-cluster:<cluster>]
gsk-attr-name = {enum | string | number}:id:value

Note: Similar configuration entries exist in the [ssl] stanza for connections with clients and junctioned web servers.

For further details about these configuration entries, see the Web Reverse Proxy Stanza Reference topics..

Parent topic: Single signon with Tivoli Federated Identity Manager

Use of Kerberos credentialsUse of Kerberos credentialsKerberos delegated credentials are one of the token types that be provided by Tivoli Federated Identity Manager. Kerberos credentials that are generated by Tivoli Federated Identity Manager for single sign-on provides some advantages over traditional Asset Manager single signon mechanisms.KerberoscredentialscredentialsKerberosAdvantages of using Kerberos credentials over traditional single sign-on mechanisms: Kerberos credentials are easily used by ASP.NET Web applications without requiring special code to be deployed.Kerberos credentials can be forwarded across applications and maintain a cryptographic signature, providing stronger security.There are some limitations to using Kerberos credentials as a solution for single signon to junctions in WebSEAL. Tivoli Federated Identity Manager must be running on a Windows system. Also, depending on the configuration of the environment, the introduction of a Kerberos single signon solution for junctioned servers slows down performance. Each Kerberos token is valid only for a single Kerberos authentication. Therefore, WebSEAL must request a new Kerberos token for each separate transaction. The fact that WebSEAL must request tokens indirectly, through a SOAP request to Tivoli Federated Identity Manager, can also diminish performance. This solution has the least negative effect on performance in an environment where the junctioned web server can maintain session state.Because Kerberos tokens are designed for one-time use only, WebSEAL provides the following features that help minimize performance issues: Configurable option to retrieve SSO tokens only if a 401 (authorization required) response is received from the back-end web server. If the back-end server can maintain session state, WebSEAL does not retrieve Kerberos tokens unnecessarily. Use the always-send-tokens option in the [tfimsso:<jct-id>] stanza. Use the option to specify:Whether a security token must be sent for every HTTP request, or If WebSEAL must wait for a 401 response, before the token requestMultiple SSO tokens are requested from Tivoli Federated Identity Manager in the same SOAP request, with the WS-Trust web service specification. Use the token-collection-size option in the [tfimsso:<jct-id>] stanza to specify the number of tokens to retrieve from Tivoli Federated Identity Manager. The tokens are cached in the user's session and used on subsequent requests; WebSEAL requests more tokens from Tivoli Federated Identity Manager only after all of the cached tokens are used or expired.Single signon with Tivoli Federated Identity ManagerUnderstand the available configuration options so that you can use Tivoli Federated Identity Manager to implement single sign-on.

Use of Kerberos credentials

Kerberos delegated credentials are one of the token types that be provided by Tivoli Federated Identity Manager. Kerberos credentials that are generated by Tivoli Federated Identity Manager for single sign-on provides some advantages over traditional Asset Manager single signon mechanisms.

Advantages of using Kerberos credentials over traditional single sign-on mechanisms:

Kerberos credentials are easily used by ASP.NET Web applications without requiring special code to be deployed.

Kerberos credentials can be forwarded across applications and maintain a cryptographic signature, providing stronger security.

There are some limitations to using Kerberos credentials as a solution for single signon to junctions in WebSEAL. Tivoli Federated Identity Manager must be running on a Windows system. Also, depending on the configuration of the environment, the introduction of a Kerberos single signon solution for junctioned servers slows down performance. Each Kerberos token is valid only for a single Kerberos authentication. Therefore, WebSEAL must request a new Kerberos token for each separate transaction. The fact that WebSEAL must request tokens indirectly, through a SOAP request to Tivoli Federated Identity Manager, can also diminish performance. This solution has the least negative effect on performance in an environment where the junctioned web server can maintain session state.

Because Kerberos tokens are designed for one-time use only, WebSEAL provides the following features that help minimize performance issues:

Configurable option to retrieve SSO tokens only if a 401 (authorization required) response is received from the back-end web server. If the back-end server can maintain session state, WebSEAL does not retrieve Kerberos tokens unnecessarily. Use the always-send-tokens option in the [tfimsso:<jct-id>] stanza. Use the option to specify:

Whether a security token must be sent for every HTTP request, or

If WebSEAL must wait for a 401 response, before the token request

Multiple SSO tokens are requested from Tivoli Federated Identity Manager in the same SOAP request, with the WS-Trust web service specification. Use the token-collection-size option in the [tfimsso:<jct-id>] stanza to specify the number of tokens to retrieve from Tivoli Federated Identity Manager. The tokens are cached in the user's session and used on subsequent requests; WebSEAL requests more tokens from Tivoli Federated Identity Manager only after all of the cached tokens are used or expired.

Parent topic: Single signon with Tivoli Federated Identity Manager

Single signon (SSO) concepts Single signon (SSO) concepts Understand single signon concepts so that you can implement a solution that allows users to access resources with one initial login.single signonconceptsA client that requests for access to a resource can be required to do multiple logins. Multiple logins might be required when a protected resource is on a back-end web application server. One login for the WebSEAL server and one for the back-end server might be required. Each login likely requires different login identities.Multiple loginsMultiple loginsThe problem of administering and maintaining multiple login identities can often be solved with a single signon (SSO) solution. A single signon solution allows the user to access a resource, regardless of the resource's location, with only one initial login. Any further login requirements from back-end servers are handled transparently to the user. Single Signon Solutions

Single signon (SSO) concepts

Understand single signon concepts so that you can implement a solution that allows users to access resources with one initial login.

A client that requests for access to a resource can be required to do multiple logins. Multiple logins might be required when a protected resource is on a back-end web application server. One login for the WebSEAL server and one for the back-end server might be required. Each login likely requires different login identities.

Figure 42. Multiple logins

The problem of administering and maintaining multiple login identities can often be solved with a single signon (SSO) solution. A single signon solution allows the user to access a resource, regardless of the resource's location, with only one initial login. Any further login requirements from back-end servers are handled transparently to the user.

Parent topic: Single Signon Solutions

Client identity in HTTP BA headers Client identity in HTTP BA headers You can configure WebSEAL junctions to supply the back-end server with original or modified client identity information. Understand the options available so that you can specify the required information in the HTTP basic authentication headers.single signonsupply client identity in BA headersHTTP BA headersclient identityclientsidentitiesHTTP BA headersUse the –b options to supply specific client identity information in HTTP Basic Authentication (BA) headers. As the administrator, you must analyze your network architecture and security requirements, and determine answers to the following questions: Is authentication information required by the back-end server? (WebSEAL uses the HTTP Basic Authentication header to convey authentication information.)If authentication information is required by the back-end server, where does this information come from? (What information does WebSEAL place in the HTTP header?)Does the connection between WebSEAL and the back-end server need to be secure? (TCP or SSL junction?)After the initial authentication between the client and WebSEAL, WebSEAL can build a new Basic Authentication header. The request uses this new header as it continues across the junction to the back-end server. You use the –b options to dictate what specific authentication information is supplied in this new header.Supplying authentication information to back-end application serversSupplying authentication information to back-end application serversSingle Signon Solutions

Client identity in HTTP BA headers

You can configure WebSEAL junctions to supply the back-end server with original or modified client identity information. Understand the options available so that you can specify the required information in the HTTP basic authentication headers.

Use the –b options to supply specific client identity information in HTTP Basic Authentication (BA) headers.

As the administrator, you must analyze your network architecture and security requirements, and determine answers to the following questions:

Is authentication information required by the back-end server?

(WebSEAL uses the HTTP Basic Authentication header to convey authentication information.)

If authentication information is required by the back-end server, where does this information come from?

(What information does WebSEAL place in the HTTP header?)

Does the connection between WebSEAL and the back-end server need to be secure?

(TCP or SSL junction?)

After the initial authentication between the client and WebSEAL, WebSEAL can build a new Basic Authentication header. The request uses this new header as it continues across the junction to the back-end server. You use the –b options to dictate what specific authentication information is supplied in this new header.

Figure 43. Supplying authentication information to back-end application servers

Parent topic: Single Signon Solutions

Client identity and generic password Client identity and generic password As an administrator, you must know how client identity and passwords are handled so that you understand how WebSEAL manages authentication in some scenarios.basicauth-dummy-passwd stanza entrysingle signon-b supplyjunctions-b supplyThe –b supply option instructs WebSEAL to supply the authenticated Security Access Manager user name (client's original identity) with a static, generic (dummy) password. The original client password is not used in this scenario.A generic password eliminates password administration and supports the application on a per-user basis. The dummy password is set in the basicauth-dummy-passwd stanza entry of the WebSEAL configuration file: [junction] basicauth-dummy-passwd = passwordThis scenario assumes that the back-end server requires authentication from a Security Access Manager identity. By mapping a client user to a known Security Access Manager user, WebSEAL manages authentication for the back-end server and provides a simple domain-wide single signon solution.The following conditions exist for this solution: WebSEAL is configured to supply the back-end server with the user name contained in the original client request plus a generic dummy password.The dummy password is configured in the WebSEAL configuration file.The back-end server registry must recognize the Security Access Manager identity that is supplied in the HTTP BA header.Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. Therefore, an SSL junction is appropriate.BA Header contains identity and dummy passwordBA Header contains identity and dummy passwordSingle Signon Solutions

Client identity and generic password

As an administrator, you must know how client identity and passwords are handled so that you understand how WebSEAL manages authentication in some scenarios.

The –b supply option instructs WebSEAL to supply the authenticated Security Access Manager user name (client's original identity) with a static, generic (dummy) password. The original client password is not used in this scenario.

A generic password eliminates password administration and supports the application on a per-user basis. The dummy password is set in the basicauth-dummy-passwd stanza entry of the WebSEAL configuration file:

[junction]
basicauth-dummy-passwd = password

This scenario assumes that the back-end server requires authentication from a Security Access Manager identity. By mapping a client user to a known Security Access Manager user, WebSEAL manages authentication for the back-end server and provides a simple domain-wide single signon solution.

The following conditions exist for this solution:

WebSEAL is configured to supply the back-end server with the user name contained in the original client request plus a generic dummy password.

The dummy password is configured in the WebSEAL configuration file.

The back-end server registry must recognize the Security Access Manager identity that is supplied in the HTTP BA header.

Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. Therefore, an SSL junction is appropriate.

Figure 44. BA Header contains identity and dummy password

Parent topic: Single Signon Solutions

Limitations of the -b supply optionLimitations of the -b supply optionYou must understand the limitations of the -b supply option so that you can secure servers properly.b supplyoptionslimitationsThe same Security Access Manager dummy password is used for all requests; all users have the same password in the back-end server registry. The common dummy password offers no basis for the application server to prove the legitimacy of the client that is logging in with that user name. If clients always go through WebSEAL to access the back-end server, this solution does not present any security problems. However, it is important to physically secure the back-end server from other possible means of access.Because this scenario has no password-level security, the back-end server must implicitly trust WebSEAL to verify the legitimacy of the client. The back-end server registry must also recognize the Security Access Manager identity in order to accept it. Single Signon Solutions

Limitations of the -b supply option

You must understand the limitations of the -b supply option so that you can secure servers properly.

The same Security Access Manager dummy password is used for all requests; all users have the same password in the back-end server registry. The common dummy password offers no basis for the application server to prove the legitimacy of the client that is logging in with that user name.

If clients always go through WebSEAL to access the back-end server, this solution does not present any security problems. However, it is important to physically secure the back-end server from other possible means of access.

Because this scenario has no password-level security, the back-end server must implicitly trust WebSEAL to verify the legitimacy of the client.

The back-end server registry must also recognize the Security Access Manager identity in order to accept it.

Parent topic: Single Signon Solutions

Forwarding of original client BA header information Forwarding of original client BA header information Understand how original client basic authentication information is sent to the back-end server without interference and the conditions that are required for this implementation. single signon-b ignorejunctions-b ignoreThe –b ignore option instructs WebSEAL to pass the original client basic authentication (BA) header straight to the back-end server without interference. WebSEAL can be configured to authenticate this BA client information. WebSEAL can also be configured to ignore the BA header that is supplied by the client and forward the header without modification to the back-end server. This implementation is not a true single signon mechanism, but rather a direct login to the third-party server, not apparent to WebSEAL.The following conditions exist for this solution: The back-end server requires client identity information through BA. The back-end server sends a Basic Authentication challenge back to the client. The client responds with user name and password information that the WebSEAL server passes through without modification.The back-end server maintains its own client-supplied passwords.WebSEAL is configured to supply the back-end server with the user name and password that is contained in the original client request.Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. An SSL junction is most appropriate.WebSEAL forwards original client identity informationWebSEAL forwards original client identity informationSingle Signon Solutions

Forwarding of original client BA header information

Understand how original client basic authentication information is sent to the back-end server without interference and the conditions that are required for this implementation.

The –b ignore option instructs WebSEAL to pass the original client basic authentication (BA) header straight to the back-end server without interference. WebSEAL can be configured to authenticate this BA client information. WebSEAL can also be configured to ignore the BA header that is supplied by the client and forward the header without modification to the back-end server.

Note: This implementation is not a true single signon mechanism, but rather a direct login to the third-party server, not apparent to WebSEAL.

The following conditions exist for this solution:

The back-end server requires client identity information through BA.

The back-end server sends a Basic Authentication challenge back to the client. The client responds with user name and password information that the WebSEAL server passes through without modification.

The back-end server maintains its own client-supplied passwords.

WebSEAL is configured to supply the back-end server with the user name and password that is contained in the original client request.

Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. An SSL junction is most appropriate.

Figure 45. WebSEAL forwards original client identity information

Parent topic: Single Signon Solutions

Removal of client BA header information Removal of client BA header information Understand how basic authentication header information is removed from client requests and the conditions that are required for this implementation.single signon-b filterjunctions-b filterThe –b filter option instructs WebSEAL to remove all basic authentication header information from any client requests before requests are forwarded to the back-end server. In this scenario, WebSEAL becomes the single security provider. The following conditions exist for this solution: Basic authentication is configured between the client and WebSEAL.The back-end server does not require basic authentication.The back-end server can be accessed only through WebSEAL.WebSEAL handles authentication on behalf of the back-end server.Removing client BA header informationRemoving client BA header informationIf you need to supply the back-end server with some client information, you can combine this option with the –c option to insert Security Access Manager client identity information into HTTP header fields. See Client identity in HTTP headers (–c)Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers..Single Signon Solutions

Removal of client BA header information

Understand how basic authentication header information is removed from client requests and the conditions that are required for this implementation.

The –b filter option instructs WebSEAL to remove all basic authentication header information from any client requests before requests are forwarded to the back-end server. In this scenario, WebSEAL becomes the single security provider.

The following conditions exist for this solution:

Basic authentication is configured between the client and WebSEAL.

The back-end server does not require basic authentication.

The back-end server can be accessed only through WebSEAL.

WebSEAL handles authentication on behalf of the back-end server.

Figure 46. Removing client BA header information

If you need to supply the back-end server with some client information, you can combine this option with the –c option to insert Security Access Manager client identity information into HTTP header fields. See Client identity in HTTP headers (–c).

Parent topic: Single Signon Solutions

User names and passwords from GSO User names and passwords from GSO Understand how authentication information is obtained from a server that handles global signon and the conditions for this implementation.single signon-b gsojunctions-b gsoThe –b gso option instructs WebSEAL to supply the back-end server with authentication information (user name and password) obtained from a server that handles global signon (GSO). The following conditions exist for this solution: The back-end server applications require different user names and passwords that are not contained in the WebSEAL registry.Security is important for both WebSEAL and the back-end server. Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. An SSL junction is appropriate.Single Signon Solutions

User names and passwords from GSO

Understand how authentication information is obtained from a server that handles global signon and the conditions for this implementation.

The –b gso option instructs WebSEAL to supply the back-end server with authentication information (user name and password) obtained from a server that handles global signon (GSO).

The following conditions exist for this solution:

The back-end server applications require different user names and passwords that are not contained in the WebSEAL registry.

Security is important for both WebSEAL and the back-end server.

Because sensitive authentication information (user name and password) is passed across the junction, the security of the junction is important. An SSL junction is appropriate.

Parent topic: Single Signon Solutions

Client identity information across junctions Client identity information across junctions A junction can be set up to specify client identity information in BA headers. You must know the available options so that you can use the correct combination of options.junctionsimpact of -b options on mutually authenticated junctionsclientsidentitiesinformation across junctionsjunctionsclient identity informationThe –b option allows four possible arguments: filter, supply, ignore, global signon. The –b option has an impact on the junction settings for mutual authentication and you must consider the correct combination of options. -b supply WebSEAL authentication with a BA header is not allowed with this option. This option uses the BA header for the original client user name and a dummy password.WebSEAL authentication with a client certificate is allowed with this option.-b ignoreWebSEAL authentication with a BA header is not allowed with this option. This option uses the BA header for the original client user name and password.WebSEAL authentication with a client certificate is allowed with this option.-b gsoWebSEAL authentication with a BA header is not allowed with this option. This option uses the BA header for user name and password information that is supplied by the GSO server.WebSEAL authentication with a client certificate is allowed with this option.-b filterInternally, the –b filter option is used when WebSEAL authentication is set to use BA header information. The WebSEAL BA header is used for all subsequent HTTP transactions. To the back-end server, WebSEAL appears logged on always.WebSEAL authentication with a client certificate is allowed with this option.If the back-end server requires actual client identity (from the browser), the CGI variables HTTP_IV_USER, HTTP_IV_GROUP, and HTTP_IV_CREDS can be used. For scripts and servlets, use the corresponding Security Access Manager HTTP headers: iv-user, iv-groups, iv-creds.Single Signon Solutions

Client identity information across junctions

A junction can be set up to specify client identity information in BA headers. You must know the available options so that you can use the correct combination of options.

The –b option allows four possible arguments: filter, supply, ignore, global signon.

The –b option has an impact on the junction settings for mutual authentication and you must consider the correct combination of options.

-b supply

WebSEAL authentication with a BA header is not allowed with this option. This option uses the BA header for the original client user name and a dummy password.

WebSEAL authentication with a client certificate is allowed with this option.

-b ignore

WebSEAL authentication with a BA header is not allowed with this option. This option uses the BA header for the original client user name and password.

WebSEAL authentication with a client certificate is allowed with this option.

-b gso

WebSEAL authentication with a BA header is not allowed with this option. This option uses the BA header for user name and password information that is supplied by the GSO server.

WebSEAL authentication with a client certificate is allowed with this option.

-b filter

Internally, the –b filter option is used when WebSEAL authentication is set to use BA header information.

The WebSEAL BA header is used for all subsequent HTTP transactions. To the back-end server, WebSEAL appears logged on always.

WebSEAL authentication with a client certificate is allowed with this option.

If the back-end server requires actual client identity (from the browser), the CGI variables HTTP_IV_USER, HTTP_IV_GROUP, and HTTP_IV_CREDS can be used. For scripts and servlets, use the corresponding Security Access Manager HTTP headers: iv-user, iv-groups, iv-creds.

Parent topic: Single Signon Solutions

Client identity in HTTP headers (–c) Client identity in HTTP headers (–c) Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers.junctionssupply client identity in HTTP headers (-c)iv-user headeriv-user-l headeriv-groups headeriv-creds headerHTTP_IV_USER headerHTTP_IV_USER_L headerHTTP_IV_GROUPS headerHVVP_IV_CREDS headerHTTP headersHTTP_IV_USERHTTP_IV_USER_LHTTP_IV_GROUPSHTTP_IV_CREDS This HTTP header information enables applications on junctioned third-party servers to do user-specific actions (such as single signon) based on the client's Security Access Manager identity. HTTP header information must be transformed to environment variable format for use by a service on the back-end server. To support CGI programming, header information is transformed into a CGI environment variable format. It is transformed by replacing all dashes (-) with underscores (_) and prepending HTTP to the beginning of the header string. The Security Access Manager HTTP header entries are available to CGI programs as the environment variables HTTP_IV_USER, HTTP_IV_USER_L, HTTP_IV_GROUPS, and HTTP_IV_CREDS. For other application framework products, refer to the appropriate product documentation for instructions on extracting headers from HTTP requests. HTTP Headers specific to Security Access Manager CGI Environment Variable HeadersDescriptioniv-userHTTP_IV_USER The user name of the client (login ID). Defaults to "Unauthenticated" if client is unauthenticated (unknown).iv-user-lHTTP_IV_USER_L The distinguished name (DN) of the client.iv-groupsHTTP_IV_GROUPS A list of groups to which the client belongs. Consists of comma separated quoted entries.iv-credsHTTP_IV_CREDS Encoded opaque data structure that represents an Security Access Manager credential. Supplies credentials to remote servers so mid-tier applications can use the authorization API to call the authorization service. See Authorization C API Developer Reference.The –c option to the junction create command (see Command option summary: standard junctions) specifies what Security Access Manager HTTP header data is sent across a junction to the back-end application server: -c header-typesThe header-types arguments:ArgumentDescriptioniv_user Provides the user name (short form) to the iv-user HTTP header of the request. iv_user_l Provides the full DN of the user (long form) to the iv-user-l HTTP header of the request.iv_groups Provides the user's list of groups to the iv-groups HTTP header of the request.iv_creds Provides the user's credential information to the iv-creds HTTP header of the request.all Provides identity information for iv-user, iv-groups, and iv-creds HTTP headers of the request.The –c option is also supported on virtual host junctions. Single Signon Solutions

Client identity in HTTP headers (–c)

Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers.

This HTTP header information enables applications on junctioned third-party servers to do user-specific actions (such as single signon) based on the client's Security Access Manager identity.

HTTP header information must be transformed to environment variable format for use by a service on the back-end server. To support CGI programming, header information is transformed into a CGI environment variable format. It is transformed by replacing all dashes (-) with underscores (_) and prepending HTTP to the beginning of the header string. The Security Access Manager HTTP header entries are available to CGI programs as the environment variables HTTP_IV_USER, HTTP_IV_USER_L, HTTP_IV_GROUPS, and HTTP_IV_CREDS.

For other application framework products, refer to the appropriate product documentation for instructions on extracting headers from HTTP requests.

HTTP Headers specific to

Security Access Manager

CGI Environment

Variable Headers

Description

iv-user
HTTP_IV_USER

The user name of the client (login ID). Defaults to "Unauthenticated" if client is unauthenticated (unknown).

iv-user-l
HTTP_IV_USER_L

The distinguished name (DN) of the client.

iv-groups
HTTP_IV_GROUPS

A list of groups to which the client belongs. Consists of comma separated quoted entries.

iv-creds
HTTP_IV_CREDS

Encoded opaque data structure that represents an Security Access Manager credential. Supplies credentials to remote servers so mid-tier applications can use the authorization API to call the authorization service. See Authorization C API Developer Reference.

The –c option to the junction create command (see Command option summary: standard junctions) specifies what Security Access Manager HTTP header data is sent across a junction to the back-end application server:

-c header-types

The header-types arguments:

Argument
Description

iv_user

Provides the user name (short form) to the iv-user HTTP header of the request.

iv_user_l

Provides the full DN of the user (long form) to the iv-user-l HTTP header of the request.

iv_groups

Provides the user's list of groups to the iv-groups HTTP header of the request.

iv_creds

Provides the user's credential information to the iv-creds HTTP header of the request.

all

Provides identity information for iv-user, iv-groups, and iv-creds HTTP headers of the request.

The –c option is also supported on virtual host junctions.

Parent topic: Single Signon Solutions

Conditions of use -c junctionsConditions of use for -c junctionsConditions of use for-c junctions in WebSEALUnderstand how to use the -c junction option so that you can use the correct combinations to insert information into HTTP headers of requests.WebSEAL-c junctionsc junctionsconditions of use Separate multiple arguments to the -c option with commas only. Do not enter any spaces.The -c all option passes only the iv-user (HTTP_IV_USER), iv-groups (HTTP_IV_GROUPS), and iv-creds (HTTP_IV_CREDS) headers across the junction. The -c all option does not pass iv-user-l (HTTP_IV_USER_L)) headers.You must individually specify all four header options to pass all four header types across the junction: -c iv_user,iv_user_l,iv_groups,iv_credsThe HTTP_IV_USER header is used for either iv-user and iv-user-l when only one of them is specified. If both iv-user and iv-user-l headers are specified, HTTP_IV_USER_L is used for iv-user-l.To ensure security of the iv-creds header value, use SSL junctions.The content caching mechanism does not cache responses to requests over junctions that are configured with the –c and –C options. It is possible to improve the WebSEAL performance under –c junction conditions by applying the cache configuration. -c iv_user,iv_user_lThe iv-user (HTTP_IV_USER) and iv-user-l (HTTP_IV_USER_L) headers are passed to the back-end application server.***** -c iv_user_lThe iv-user-l (HTTP_IV_USER) header is passed to the back-end application server.***** -c allThe iv-user (HTTP_IV_USER), iv-groups (HTTP_IV_GROUPS), and iv-creds (HTTP_IV_CREDS) headers are passed to the back-end application server.***** -c iv_user,iv_user_l,iv_groups,iv_credsThe iv-user (HTTP_IV_USER), iv-user-l (HTTP_IV_USER_L), iv-groups (HTTP_IV_GROUPS), and iv-creds (HTTP_IV_CREDS) headers are passed to the back-end application server.Single Signon Solutions

Conditions of use -c junctions

Understand how to use the -c junction option so that you can use the correct combinations to insert information into HTTP headers of requests.

Separate multiple arguments to the -c option with commas only. Do not enter any spaces.

The -c all option passes only the iv-user (HTTP_IV_USER), iv-groups (HTTP_IV_GROUPS), and iv-creds (HTTP_IV_CREDS) headers across the junction.

Note: The -c all option does not pass iv-user-l (HTTP_IV_USER_L)) headers.

You must individually specify all four header options to pass all four header types across the junction:

-c iv_user,iv_user_l,iv_groups,iv_creds

The HTTP_IV_USER header is used for either iv-user and iv-user-l when only one of them is specified. If both iv-user and iv-user-l headers are specified, HTTP_IV_USER_L is used for iv-user-l.

To ensure security of the iv-creds header value, use SSL junctions.

The content caching mechanism does not cache responses to requests over junctions that are configured with the –c and –C options.

Note: It is possible to improve the WebSEAL performance under –c junction conditions by applying the cache configuration.

-c iv_user,iv_user_l

The iv-user (HTTP_IV_USER) and iv-user-l (HTTP_IV_USER_L) headers are passed to the back-end application server.

*****

-c iv_user_l

The iv-user-l (HTTP_IV_USER) header is passed to the back-end application server.

*****

-c all

The iv-user (HTTP_IV_USER), iv-groups (HTTP_IV_GROUPS), and iv-creds (HTTP_IV_CREDS) headers are passed to the back-end application server.

*****

-c iv_user,iv_user_l,iv_groups,iv_creds

The iv-user (HTTP_IV_USER), iv-user-l (HTTP_IV_USER_L), iv-groups (HTTP_IV_GROUPS), and iv-creds (HTTP_IV_CREDS) headers are passed to the back-end application server.

Parent topic: Single Signon Solutions

Client IP addresses in HTTP headers (–r) Client IP addresses in HTTP headers (–r) iv-remote-address headerHTTP_IV_REMOTE_ADDRESS headerjunctionssupply IP address in HTTP headers (-r)HTTP headersHTTP_IV_REMOTE_ADDRESSThe –r junction option allows you to insert client IP address information into the HTTP headers of requests destined for junctioned application servers. The HTTP header information enables applications on junctioned third-party servers to perform actions based on this IP address information. HTTP header information must be transformed by the back-end server to environment variable format for use by a service on the back-end server. Header information is transformed into a CGI environment variable format by replacing all dashes (-) with underscores (_) and prepending "HTTP" to the beginning of the string. The value of the HTTP header becomes the value of the new environment variable. HTTP Header Field specific to Security Access Manager CGI Environment Variable EquivalentDescriptioniv-remote-addressHTTP_IV_REMOTE_ADDRESS The IP address of the client. This value could also represent the IP address of a proxy server or a network address translator (NAT).iv-remote-address-ipv6HTTP_IV_REMOTE_ADDRESS_IPV6 The IP address of the client in IPv6 format.The –r option specifies that the IP address of the incoming request be sent to the back-end application server. The option is expressed without any arguments.The –r option is also supported on virtual host junctions. Single Signon Solutions

Client IP addresses in HTTP headers (–r)

The –r junction option allows you to insert client IP address information into the HTTP headers of requests destined for junctioned application servers. The HTTP header information enables applications on junctioned third-party servers to perform actions based on this IP address information.

HTTP header information must be transformed by the back-end server to environment variable format for use by a service on the back-end server. Header information is transformed into a CGI environment variable format by replacing all dashes (-) with underscores (_) and prepending "HTTP" to the beginning of the string. The value of the HTTP header becomes the value of the new environment variable.

HTTP Header Field

specific to

Security Access Manager

CGI Environment

Variable Equivalent

Description

iv-remote-address
HTTP_IV_REMOTE_ADDRESS

The IP address of the client. This value could also represent the IP address of a proxy server or a network address translator (NAT).

iv-remote-address-ipv6
HTTP_IV_REMOTE_ADDRESS_IPV6

The IP address of the client in IPv6 format.

The –r option specifies that the IP address of the incoming request be sent to the back-end application server. The option is expressed without any arguments.

The –r option is also supported on virtual host junctions.

Parent topic: Single Signon Solutions

Limiting the size of WebSEAL-generated HTTP headers Limiting the size of WebSEAL-generated HTTP headers You can limit the size of WebSEAL-generated HTTP headers that are inserted in requests to junctioned back-end servers so that they are not too large.max-webseal-header-size stanza entryHTTP headerslimiting size The max-webseal-header-size stanza entry in the [junction] stanza of the WebSEAL configuration file specifies the maximum size, in bytes, of WebSEAL-generated HTTP headers. A value of 0 disables this function: [junction] max-webseal-header-size = 0 The max-webseal-header-size entry does not limit the maximum size of HTTP-Tag-Value headers. This stanza entry can be useful if a back-end application server rejects WebSEAL-generated HTTP headers because they are too large. For example, an iv-creds header for a user that belongs in many groups might be too large. When configured, this stanza entry causes WebSEAL-generated headers that exceed the maximum value to split across multiple headers. The following example output from a CGI application illustrates the effect of split headers: HTTP_IV_CREDS_1=Version=1, BAKs3DCCBnMMADCCBm0wggZpAgIDkDCCAYUwKzA HTTP_IV_CREDS_2=+0+8eAgI8iAICEdYCAgCkAgFUBAaSVNCJqncMOWNuPXNlY21== HTTP_IV_CREDS_SEGMENTS=2 If you enable this function, you must modify the back-end application to recognize split headers, instead of standard WebSEAL-specific HTTP headers.Single Signon Solutions

Limiting the size of WebSEAL-generated HTTP headers

You can limit the size of WebSEAL-generated HTTP headers that are inserted in requests to junctioned back-end servers so that they are not too large.

About this task

The max-webseal-header-size stanza entry in the [junction] stanza of the WebSEAL configuration file specifies the maximum size, in bytes, of WebSEAL-generated HTTP headers. A value of 0 disables this function:

[junction]
max-webseal-header-size = 0

Note: The max-webseal-header-size entry does not limit the maximum size of HTTP-Tag-Value headers.

This stanza entry can be useful if a back-end application server rejects WebSEAL-generated HTTP headers because they are too large. For example, an iv-creds header for a user that belongs in many groups might be too large.

When configured, this stanza entry causes WebSEAL-generated headers that exceed the maximum value to split across multiple headers. The following example output from a CGI application illustrates the effect of split headers:

HTTP_IV_CREDS_1=Version=1, BAKs3DCCBnMMADCCBm0wggZpAgIDkDCCAYUwKzA
HTTP_IV_CREDS_2=+0+8eAgI8iAICEdYCAgCkAgFUBAaSVNCJqncMOWNuPXNlY21==
HTTP_IV_CREDS_SEGMENTS=2

If you enable this function, you must modify the back-end application to recognize split headers, instead of standard WebSEAL-specific HTTP headers.

Parent topic: Single Signon Solutions

Global sign-on overviewGlobal sign-on overviewGlobal sign-on overview in IBM Security Access Manager for WebGlobal sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords.GSOoverviewmechanism illustrationThe integration is achieved by creating "aware" junctions between WebSEAL and back-end web servers. The GSO data can be stored in either the Security Access Manager user registry or an external source that WebSEAL communicates with through a RESTful web service. The web service must be accessed through a junction that is local to the WebSEAL instance. This setup allows all of the advanced junctioning capabilities (for example: HA, failover, SSO) to be used on these web service requests.For security purposes, this junction must be set up to prevent external access. You can achieve such setup by changing the ACL so that no user has read permission on this web service. When WebSEAL sends the GSO RESTful web service request via the junction, it automatically bypasses the policy definition for the junction.When WebSEAL receives a request for a resource that resides on a junctioned server that is configured to require GSO credential information, it attempts to locate the credential information from the Security Access Manager user registry or the external GSO data source.Single Signon SolutionsGSO embedded storageGSO data can be stored in the Security Access Manager user registry and provided to WebSEAL through its LDAP service.GSO RESTful web serviceWhen you configure the GSO capability for forms single sign-on (FSSO) and basic authentication (BA), you are required to specify a GSO resource. Use the following syntax to specify the GSO resource if you want to use a web service to communicate GSO data from an external resource. GSO junction learningYou can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication.

Global sign-on overview

Global sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords.

The integration is achieved by creating "aware" junctions between WebSEAL and back-end web servers.

The GSO data can be stored in either the Security Access Manager user registry or an external source that WebSEAL communicates with through a RESTful web service. The web service must be accessed through a junction that is local to the WebSEAL instance. This setup allows all of the advanced junctioning capabilities (for example: HA, failover, SSO) to be used on these web service requests.

Note: For security purposes, this junction must be set up to prevent external access. You can achieve such setup by changing the ACL so that no user has read permission on this web service. When WebSEAL sends the GSO RESTful web service request via the junction, it automatically bypasses the policy definition for the junction.

When WebSEAL receives a request for a resource that resides on a junctioned server that is configured to require GSO credential information, it attempts to locate the credential information from the Security Access Manager user registry or the external GSO data source.

GSO embedded storage
GSO data can be stored in the Security Access Manager user registry and provided to WebSEAL through its LDAP service.

GSO RESTful web service
When you configure the GSO capability for forms single sign-on (FSSO) and basic authentication (BA), you are required to specify a GSO resource. Use the following syntax to specify the GSO resource if you want to use a web service to communicate GSO data from an external resource.

GSO junction learning
You can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication.

Parent topic: Single Signon Solutions

GSO embedded storageGSO data can be stored in the Security Access Manager user registry and provided to WebSEAL through its LDAP service.GSO resources and GSO resource groups must first be created with the Web Portal Manager or pdadmin utility.The following figure illustrates how the GSO mechanism is used to retrieve user names and passwords for back-end application resources. Global sign-on mechanismGlobal signon mechanismThe client authenticates to WebSEAL with a request for access to an application resource on a back-end server. A Security Access Manager identity is obtained. The single signon process is independent of the initial authentication method.WebSEAL passes the Security Access Manager identity to the user registry server.The registry returns a user name and password appropriate for the user and the requested application resource.WebSEAL inserts the user name and password information in the HTTP BA header of the request or FSSO forms data. That request is sent across the junction to the back-end server. Global sign-on overviewGlobal sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords.

GSO embedded storage

GSO data can be stored in the Security Access Manager user registry and provided to WebSEAL through its LDAP service.

GSO resources and GSO resource groups must first be created with the Web Portal Manager or pdadmin utility.

The following figure illustrates how the GSO mechanism is used to retrieve user names and passwords for back-end application resources.

Figure 47. Global sign-on mechanism

The client authenticates to WebSEAL with a request for access to an application resource on a back-end server. A Security Access Manager identity is obtained.

Note: The single signon process is independent of the initial authentication method.

WebSEAL passes the Security Access Manager identity to the user registry server.

The registry returns a user name and password appropriate for the user and the requested application resource.

WebSEAL inserts the user name and password information in the HTTP BA header of the request or FSSO forms data. That request is sent across the junction to the back-end server.

Parent topic: Global sign-on overview

GSO RESTful web serviceWhen you configure the GSO capability for forms single sign-on (FSSO) and basic authentication (BA), you are required to specify a GSO resource. Use the following syntax to specify the GSO resource if you want to use a web service to communicate GSO data from an external resource. [url]{<hostname>:<port>,}<uri> [url]A static string that indicates a web service is used for this GSO resource. If a [url] designator is not present, the GSO credential information is retrieved from the Security Access Manager user registry.<hostname> The host name to use if the web service is accessed over a virtual host junction.<port>The port to use if the web service is accessed over a virtual host junction.<uri>The URI to which GSO requests are sent. This URI is relative to the root web space of the local WebSEAL server.Here is an example resource that communicates with WebSEAL through a web service:[url]www.ibm.com:80,/gso/credentialsThe web service can be used to retrieve or update the credential information for a particular user.To retrieve the GSO data for a particular user, the web service format is as follows:Method: GET URI: <web-service-root>/<isam-user-name> Response: A successful response should include a status of 200 OK, with the following JSON data included in the body: * gso-username * gso-password If the credential information is not found, a 404 NOT FOUND response is returned.To store new credential information for a particular user, the web service format is as follows:Method: PUT URI: <web-service-root>/<isam-user-name> Body: JSON data, which includes the following fields: * gso-username * gso-password Response: A successful response includes a 204 No-Content with an empty body.To delete the credential information for a particular user, the web service format is as follows:Method: DELETE URI: <web-service-root>/<isam-user-name> Response: A successful response includes a 204 No-Content with an empty body.By default, the passwords that are managed by the GSO RESTful web service are not obfuscated. If you want to obfuscate the passwords, set the gso-obfuscation-key stanza entry in the [junction] stanza to contain the obfuscation key. Setting this stanza entry enables password obfuscation for the GSO RESTful web service. For more information, see gso-obfuscation-key Use this stanza entry to set the key for obfuscating any passwords that are managed by the GSO RESTful web service..Global sign-on overviewGlobal sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords.

GSO RESTful web service

When you configure the GSO capability for forms single sign-on (FSSO) and basic authentication (BA), you are required to specify a GSO resource. Use the following syntax to specify the GSO resource if you want to use a web service to communicate GSO data from an external resource.

[url]{<hostname>:<port>,}<uri>

[url]

A static string that indicates a web service is used for this GSO resource. If a [url] designator is not present, the GSO credential information is retrieved from the Security Access Manager user registry.

<hostname>

The host name to use if the web service is accessed over a virtual host junction.

<port>

The port to use if the web service is accessed over a virtual host junction.

<uri>

The URI to which GSO requests are sent. This URI is relative to the root web space of the local WebSEAL server.

Here is an example resource that communicates with WebSEAL through a web service:

[url]www.ibm.com:80,/gso/credentials

The web service can be used to retrieve or update the credential information for a particular user.

To retrieve the GSO data for a particular user, the web service format is as follows:

Method:   GET

URI:      <web-service-root>/<isam-user-name>

Response: A successful response should include a status of 200 OK, with the
          following JSON data included in the body:
	   * gso-username
	   * gso-password
          If the credential information is not found, a 404 NOT FOUND response is returned.

To store new credential information for a particular user, the web service format is as follows:

Method:   PUT

URI:      <web-service-root>/<isam-user-name>

Body:     JSON data, which includes the following fields:
	   * gso-username
	   * gso-password

Response: A successful response includes a 204 No-Content with an empty body.

To delete the credential information for a particular user, the web service format is as follows:

Method:   DELETE

URI:      <web-service-root>/<isam-user-name>

Response: A successful response includes a 204 No-Content with an empty body.

By default, the passwords that are managed by the GSO RESTful web service are not obfuscated. If you want to obfuscate the passwords, set the gso-obfuscation-key stanza entry in the [junction] stanza to contain the obfuscation key. Setting this stanza entry enables password obfuscation for the GSO RESTful web service. For more information, see gso-obfuscation-key.

Parent topic: Global sign-on overview

GSO junction learningYou can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication. Use the gso-credential-learning stanza entry to enable the GSO junction learning function. For more information, see gso-credential-learningUse this entry to enable or disable the learning capability for GSO junctions. .If the GSO junction learning function is enabled, WebSEAL learns your user name and password information for a particular junctioned resource after you manually enter it for the first time. In future requests to the same junctioned resource, you will not be prompted for authentication as WebSEAL automatically provides such info. By default, the learning function is disabled.Global sign-on overviewGlobal sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords.

GSO junction learning

You can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication.

Use the gso-credential-learning stanza entry to enable the GSO junction learning function. For more information, see gso-credential-learning.

If the GSO junction learning function is enabled, WebSEAL learns your user name and password information for a particular junctioned resource after you manually enter it for the first time. In future requests to the same junctioned resource, you will not be prompted for authentication as WebSEAL automatically provides such info. By default, the learning function is disabled.

Parent topic: Global sign-on overview

Authentication information mapping Authentication information mapping Authentication information mapping to WebSEALThe following example illustrates how the user registry provides authentication information to WebSEAL.WebSEALauthentication information mappingauthenticationinformation mapping to WebSEALIf user Michael wants to run the travel-app application resource, WebSEAL asks the user registry server for Michael's authentication information. See the Global sign-on overviewGlobal sign-on (GSO) grants users access to the computing resources that they are authorized to use through a single login. This feature is designed for large enterprises that consist of multiple systems and applications within heterogeneous, distributed computing environments. GSO eliminates the need for users to manage multiple user names and passwords. section for details.The user registry server maintains a complete database of authentication information in the form of mappings of resources to specific authentication information. The authentication information is a user name and password combination known as a resource credential. Resource credentials can be created only for registered users. The registry contains a database for Michael that maps the resource travel-app to a specific resource credential.The following table illustrates the structure of the GSO resource credential database: MichaelPaul resource: travel-app username=mike password=123 resource: travel-app username=bundy password=abc resource: payroll-app username=powell password=456 resource: payroll-app username=jensen password=xyzIn this example, the registry returns user name "mike" and password "123" to WebSEAL. WebSEAL uses this information when it constructs the Basic Authentication header in the request sent across the junction to the back-end server.Single Signon Solutions

Authentication information mapping

The following example illustrates how the user registry provides authentication information to WebSEAL.

If user Michael wants to run the travel-app application resource, WebSEAL asks the user registry server for Michael's authentication information. See the Global sign-on overview section for details.

The user registry server maintains a complete database of authentication information in the form of mappings of resources to specific authentication information. The authentication information is a user name and password combination known as a resource credential. Resource credentials can be created only for registered users.

The registry contains a database for Michael that maps the resource travel-app to a specific resource credential.

The following table illustrates the structure of the GSO resource credential database:

Michael
Paul

resource: travel-app

      username=mike

      password=123

resource: travel-app

username=bundy

password=abc

resource: payroll-app

      username=powell

      password=456

resource: payroll-app

username=jensen

password=xyz

In this example, the registry returns user name "mike" and password "123" to WebSEAL. WebSEAL uses this information when it constructs the Basic Authentication header in the request sent across the junction to the back-end server.

Parent topic: Single Signon Solutions

Configuring a GSO-enabled WebSEAL junction Configuring a GSO-enabled WebSEAL junction Use the create command with the –b gso option to create a junction that enables GSO. junctionsgso options (-b gso, -T)GSO-enabled WebSEAL junctionconfiguration Support for GSO is configured at the junction between WebSEAL and a back-end server. The following example illustrates the syntax for the create command: create -t tcp -h host-name -b gso -T resource jct-point Options for setting up GSO junctions: OptionsDescription–b gso Specifies that GSO must provide authentication information for all requests that cross this junction.–T resource/resource-group Specifies the GSO resource or resource group. The resource name that is used as the argument to this option must exactly match the resource name as listed in the GSO database. Required for GSO junctions. A junction that is used in a WebSEAL or GSO solution can be made secure through SSL by applying the –t ssl option. Always use SSL junctions with GSO to ensure encryption of credentials and all data.Junction the application resource travel-app on host sales_svr to junction point /sales: create -t tcp -b gso -T travel-app -h sales_svr /salesJunction the application resource payroll-app on host adm_svr to junction point /admin and make the junction secure with SSL: create -t ssl -b gso -T payroll-app -h adm_svr /admin In this example, the –t ssl option dictates a default port of 443.Single Signon Solutions

Configuring a GSO-enabled WebSEAL junction

Use the create command with the –b gso option to create a junction that enables GSO.

About this task

Support for GSO is configured at the junction between WebSEAL and a back-end server.

The following example illustrates the syntax for the create command:

create -t tcp -h host-name -b gso -T resource jct-point

Options for setting up GSO junctions:

Options
Description

–b gso

Specifies that GSO must provide authentication information for all requests that cross this junction.

–T resource/resource-group

Specifies the GSO resource or resource group. The resource name that is used as the argument to this option must exactly match the resource name as listed in the GSO database. Required for GSO junctions.

A junction that is used in a WebSEAL or GSO solution can be made secure through SSL by applying the –t ssl option.

Always use SSL junctions with GSO to ensure encryption of credentials and all data.

Example

Junction the application resource travel-app on host sales_svr to junction point /sales:

create -t tcp -b gso -T travel-app -h sales_svr /sales

Junction the application resource payroll-app on host adm_svr to junction point /admin and make the junction secure with SSL:

create -t ssl -b gso -T payroll-app -h adm_svr /admin

Note: In this example, the –t ssl option dictates a default port of 443.

Parent topic: Single Signon Solutions

Configuration of the GSO cache Configuration of the GSO cache Use the global signon (GSO) cache function to improve the performance of GSO junctions in a high load environment.GSOcachesingle signonconfiguring GSO cachegso-cache-enabled stanza entrygso-cache-size stanza entrygso-cache-entry-lifetime stanza entrygso-cache-entry-idle-timeout stanza entryBy default, the GSO cache is disabled. Without the enhancement of the cache, a call to the user registry server is required for each retrieval of GSO target information.Stanza entries for configuring the GSO cache are in the [gso-cache] stanza of the WebSEAL configuration file. You must first enable the cache. The remaining stanza entries configure the cache size and the timeout values for cache entries. Larger lifetime and inactivity timeout values improve performance, but increase the risk of information that is exposed in the WebSEAL memory. Do not enable the GSO cache if GSO junctions are not used in your network solution.Stanza EntriesDescriptiongso-cache-enabledEnable and disable the GSO cache function. Values are yes or no. Default is no.gso-cache-sizeSets the maximum number of entries that are allowed in the cache hash table. Set this value to approximate the peak number of concurrent user sessions that access an application across a GSO junction. A high value uses more memory but results in faster information access. Each cache entry consumes approximately 50 bytes.gso-cache-entry-lifetimeMaximum time (in seconds) any cache entry can remain in the cache, regardless of activity. After a cache entry expires, the next request by that same user requires a new call to the user registry server. Default value is 900 seconds.gso-cache-entry-idle-timeoutMaximum time (in seconds) an inactive cache entry that can remain in the cache. Default value is 120 seconds.Single Signon Solutions

Configuration of the GSO cache

Use the global signon (GSO) cache function to improve the performance of GSO junctions in a high load environment.

By default, the GSO cache is disabled. Without the enhancement of the cache, a call to the user registry server is required for each retrieval of GSO target information.

Stanza entries for configuring the GSO cache are in the [gso-cache] stanza of the WebSEAL configuration file. You must first enable the cache. The remaining stanza entries configure the cache size and the timeout values for cache entries. Larger lifetime and inactivity timeout values improve performance, but increase the risk of information that is exposed in the WebSEAL memory. Do not enable the GSO cache if GSO junctions are not used in your network solution.

Stanza Entries
Description

gso-cache-enabled
Enable and disable the GSO cache function. Values are yes or no. Default is no.

gso-cache-size
Sets the maximum number of entries that are allowed in the cache hash table. Set this value to approximate the peak number of concurrent user sessions that access an application across a GSO junction. A high value uses more memory but results in faster information access. Each cache entry consumes approximately 50 bytes.

gso-cache-entry-lifetime
Maximum time (in seconds) any cache entry can remain in the cache, regardless of activity. After a cache entry expires, the next request by that same user requires a new call to the user registry server. Default value is 900 seconds.

gso-cache-entry-idle-timeout
Maximum time (in seconds) an inactive cache entry that can remain in the cache. Default value is 120 seconds.

Parent topic: Single Signon Solutions

LTPA overviewLTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA).LTPAoverviewWhen WebSEAL is positioned as a protective front-end to WebSphere, users are faced with two potential login points. To achieve a single signon solution to one or more IBM WebSphere servers across WebSEAL junctions, you can configure WebSEAL junctions to support LTPA.When a user makes a request for a WebSphere resource, the user must first authenticate to WebSEAL. After successful authentication, WebSEAL generates an LTPA cookie on behalf of the user. The LTPA cookie, which serves as an authentication token for WebSphere, contains the user identity, key and token data, buffer length, and expiration information. This information is encrypted with a password-protected secret key that is shared between WebSEAL and the WebSphere server.WebSEAL inserts the cookie in the HTTP header of the request that is sent across the junction to WebSphere. The back-end WebSphere server receives the request, decrypts the cookie, and authenticates the user. The user is authenticated based on the identity information that is supplied in the cookie.To improve performance, WebSEAL can store the LTPA cookie in a cache and use the cached LTPA cookie for subsequent requests during the same user session. You can configure lifetime timeout and idle (inactivity) timeout values for the cached cookie.WebSEAL supports both LTPA version 1 (LtpaToken) and LTPA version 2 (LtpaToken2) cookies. LTPA version 2 cookies are suggested for cases where the WebSphere server supports LtpaToken2. LtpaToken The LtpaToken is used for interoperating with previous releases of WebSphere Application Server. This token contains the authentication identity attribute only. LtpaToken is generated for releases before WebSphere Application Server Version 5.1.0.2 (for z/OS) or version 5.1.1 (for distributed). LtpaToken2 LtpaToken2 contains stronger encryption and you can add multiple attributes to the token. This token contains the authentication identity and additional information such as the attributes. The attributes are used for contacting the original login server and the unique cache key. It is also used for looking up the Subject when you consider more than just the identity in determining uniqueness. LtpaToken2 is generated for WebSphere Application Server Version 5.1.0.2 (for z/OS) and for version 5.1.1 (for distributed) and beyond.For more information about using LTPA single signon in peer server environments, see LTPA single signon.Single Signon SolutionsConfiguration of an LTPA junctionUnderstand the configuration requirements and the commands you need to set up an LTPA junction.Configuration of the LTPA cacheThe LTPA cache helps to improve the performance of LTPA junctions in a high load environment. Without the enhancement of the cache, a new LTPA cookie is created and encrypted for each subsequent user request. Technical notes for LTPA single sign-onUnderstand the technical notes that you must consider when you implement LTPA single sign-on.

LTPA overview

WebSEAL can provide authentication and authorization services and protection to an IBM® WebSphere® environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA).

When WebSEAL is positioned as a protective front-end to WebSphere, users are faced with two potential login points. To achieve a single signon solution to one or more IBM WebSphere servers across WebSEAL junctions, you can configure WebSEAL junctions to support LTPA.

When a user makes a request for a WebSphere resource, the user must first authenticate to WebSEAL. After successful authentication, WebSEAL generates an LTPA cookie on behalf of the user. The LTPA cookie, which serves as an authentication token for WebSphere, contains the user identity, key and token data, buffer length, and expiration information. This information is encrypted with a password-protected secret key that is shared between WebSEAL and the WebSphere server.

WebSEAL inserts the cookie in the HTTP header of the request that is sent across the junction to WebSphere. The back-end WebSphere server receives the request, decrypts the cookie, and authenticates the user. The user is authenticated based on the identity information that is supplied in the cookie.

To improve performance, WebSEAL can store the LTPA cookie in a cache and use the cached LTPA cookie for subsequent requests during the same user session. You can configure lifetime timeout and idle (inactivity) timeout values for the cached cookie.

WebSEAL supports both LTPA version 1 (LtpaToken) and LTPA version 2 (LtpaToken2) cookies. LTPA version 2 cookies are suggested for cases where the WebSphere server supports LtpaToken2.

LtpaToken

The LtpaToken is used for interoperating with previous releases of WebSphere Application Server. This token contains the authentication identity attribute only.

LtpaToken is generated for releases before WebSphere Application Server Version 5.1.0.2 (for z/OS®) or version 5.1.1 (for distributed).

LtpaToken2

LtpaToken2 contains stronger encryption and you can add multiple attributes to the token. This token contains the authentication identity and additional information such as the attributes. The attributes are used for contacting the original login server and the unique cache key. It is also used for looking up the Subject when you consider more than just the identity in determining uniqueness.

LtpaToken2 is generated for WebSphere Application Server Version 5.1.0.2 (for z/OS) and for version 5.1.1 (for distributed) and beyond.

For more information about using LTPA single signon in peer server environments, see LTPA single signon.

Configuration of an LTPA junction
Understand the configuration requirements and the commands you need to set up an LTPA junction.

Configuration of the LTPA cache
The LTPA cache helps to improve the performance of LTPA junctions in a high load environment. Without the enhancement of the cache, a new LTPA cookie is created and encrypted for each subsequent user request.

Technical notes for LTPA single sign-on
Understand the technical notes that you must consider when you implement LTPA single sign-on.

Parent topic: Single Signon Solutions

Configuration of an LTPA junction Configuration of an LTPA junction Understand the configuration requirements and the commands you need to set up an LTPA junction.junctionsLTPA (-A, -F, -Z)LTPAjunction configurationSingle signon to WebSphere with an LTPA cookie requires the following configuration tasks: Enable the LTPA mechanism.Provide the name of the key file that is used to encrypt the identity information.Provide the password to this key file.Ensure the LTPA cookie name for the WebSEAL junction matches the WebSphere LTPA cookie name. The name of the WebSEAL cookie that contains the LTPA token must match the configured name of the LTPA cookie in the WebSphere application. You can configure the jct-ltpa-cookie-name configuration item on a global or per junction basis. If you do not configure this cookie name, WebSEAL uses the same default values as WebSphere. See Specifying the cookie name for junctionsYou can configure the name of the cookie that contains the LTPA token for junctioned web servers..The first three configuration requirements are specified in the following options to the standard junction and virtual host junction create commands. The –A option enables LTPA cookies. LTPA version 1 cookies (LtpaToken) and LTPA version 2 cookies (LtpaToken2) are both supported. LTPA version 1 cookies are specified by default. LTPA version 2 cookies must be specified with the additional -2 option. Also requires –F, and –Z options.The –2 option specifies that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.The –F "keyfile" option and argument specifies the name of the key file. The key file is used to encrypt the identity information in the cookie. The shared key is originally created on the WebSphere server and copied securely to the WebSEAL server. See the appropriate WebSphere documentation for specific details for this task.The –Z " keyfile-password" specifies the password that is required to open the key file. The password appears as encrypted text in the junction XML file.Use these options in addition to other required junction options when you create the junction between WebSEAL and the back-end WebSphere server. For example, entered as one line: pdadmin> server task default-webseald-webseal.ibm.com create ... -A -F "/abc/xyz/key.file" -Z "abcdefg" ...LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA).

Configuration of an LTPA junction

Understand the configuration requirements and the commands you need to set up an LTPA junction.

Single signon to WebSphere® with an LTPA cookie requires the following configuration tasks:

Enable the LTPA mechanism.

Provide the name of the key file that is used to encrypt the identity information.

Provide the password to this key file.

Ensure the LTPA cookie name for the WebSEAL junction matches the WebSphere LTPA cookie name.

The name of the WebSEAL cookie that contains the LTPA token must match the configured name of the LTPA cookie in the WebSphere application. You can configure the jct-ltpa-cookie-name configuration item on a global or per junction basis. If you do not configure this cookie name, WebSEAL uses the same default values as WebSphere. See Specifying the cookie name for junctions.

The first three configuration requirements are specified in the following options to the standard junction and virtual host junction create commands.

The –A option enables LTPA cookies.

LTPA version 1 cookies (LtpaToken) and LTPA version 2 cookies (LtpaToken2) are both supported. LTPA version 1 cookies are specified by default. LTPA version 2 cookies must be specified with the additional -2 option.

Also requires –F, and –Z options.

The –2 option specifies that LTPA version 2 cookies (LtpaToken2) are used.

The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

The –F "keyfile" option and argument specifies the name of the key file. The key file is used to encrypt the identity information in the cookie. The shared key is originally created on the WebSphere server and copied securely to the WebSEAL server. See the appropriate WebSphere documentation for specific details for this task.

The –Z " keyfile-password" specifies the password that is required to open the key file.

The password appears as encrypted text in the junction XML file.

Use these options in addition to other required junction options when you create the junction between WebSEAL and the back-end WebSphere server. For example, entered as one line:

pdadmin> server task default-webseald-webseal.ibm.com create ...
-A -F "/abc/xyz/key.file" -Z "abcdefg" ...

Parent topic: LTPA overview

Configuration of the LTPA cacheConfiguration of the LTPA cacheThe LTPA cache helps to improve the performance of LTPA junctions in a high load environment. Without the enhancement of the cache, a new LTPA cookie is created and encrypted for each subsequent user request. LTPAcache configurationltpa-cache stanzalpta-cache-enabled stanza entrylpta-cache-size stanza entrylpta-cache-entry-lifetime stanza entrylpta-cache-entry-idle-timeout stanza entryThe creation, encryption, and decryption of LTPA cookies introduces processing overhead. By default, the LTPA cache is enabled.Stanza entries for configuring the LTPA cache are in the [ltpa-cache] stanza of the WebSEAL configuration file. Stanza entries specify the cache size and the timeout values for cache entries. Larger lifetime and inactivity timeout values improve performance, but increase the risk of information that is exposed in the WebSEAL memory.Stanza EntriesDescriptionltpa-cache-enabledEnable and disable the LTPA cache function. Values include "yes" and "no". Default value is "yes".ltpa-cache-sizeSets the maximum number of entries that are allowed in the cache hash table. Set this value to approximate the peak number of concurrent user sessions that access an application across an LTPA junction. A high value uses more memory but results in faster information access. Each cache entry consumes approximately 50 bytes. Default value is 4096 entries.ltpa-cache-entry-lifetimeMaximum time (in seconds) any cache entry can remain in the cache, regardless of activity. After a cache entry expires, the next request by that same user requires the creation of a new LTPA cookie. Default value is 3600 secondsltpa-cache-entry-idle-timeoutMaximum time (in seconds) an inactive cache entry can remain in the cache. Default value is 600 seconds.LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA).

Configuration of the LTPA cache

The LTPA cache helps to improve the performance of LTPA junctions in a high load environment. Without the enhancement of the cache, a new LTPA cookie is created and encrypted for each subsequent user request.

The creation, encryption, and decryption of LTPA cookies introduces processing overhead. By default, the LTPA cache is enabled.

Stanza entries for configuring the LTPA cache are in the [ltpa-cache] stanza of the WebSEAL configuration file. Stanza entries specify the cache size and the timeout values for cache entries. Larger lifetime and inactivity timeout values improve performance, but increase the risk of information that is exposed in the WebSEAL memory.

Stanza Entries
Description

ltpa-cache-enabled
Enable and disable the LTPA cache function. Values include "yes" and "no". Default value is "yes".

ltpa-cache-size
Sets the maximum number of entries that are allowed in the cache hash table. Set this value to approximate the peak number of concurrent user sessions that access an application across an LTPA junction. A high value uses more memory but results in faster information access. Each cache entry consumes approximately 50 bytes. Default value is 4096 entries.

ltpa-cache-entry-lifetime
Maximum time (in seconds) any cache entry can remain in the cache, regardless of activity. After a cache entry expires, the next request by that same user requires the creation of a new LTPA cookie. Default value is 3600 seconds

ltpa-cache-entry-idle-timeout
Maximum time (in seconds) an inactive cache entry can remain in the cache. Default value is 600 seconds.

Parent topic: LTPA overview

Technical notes for LTPA single sign-onTechnical notes for LTPA single sign-onTechnical notes for LTPA single sign-on IBM Security Access Manager for WebUnderstand the technical notes that you must consider when you implement LTPA single sign-on.LTPAtechnical notessingle signontechnical notesLTPA single signonThe following technical notes apply to LTPA single signon: The key file contains information about a specific WebSphere server. An LTPA junction is specific to one WebSphere server. If you add more than one server to the same junction point, all servers share the key file.For single signon to succeed, WebSEAL and the WebSphere server must share the registry information. The WebSphere server is responsible for setting up LTPA and the creation of the shared secret key. The WebSEAL participation involves the junction and cache configurations. WebSphere version 5.1.1 and later support the new LTPA version 2 cookie (LtpaToken2). In these environments, use the -2 option to specify LtpaToken2 support.WebSEAL does not use WebSphere LTPA Security Attribute Propagation to pass more attributes to the WebSphere server in the LTPA cookie.LTPA overviewWebSEAL can provide authentication and authorization services and protection to an IBM WebSphere environment. WebSphere provides support for the cookie-based lightweight third-party authentication mechanism (LTPA).

Technical notes for LTPA single sign-on

Understand the technical notes that you must consider when you implement LTPA single sign-on.

The following technical notes apply to LTPA single signon:

The key file contains information about a specific WebSphere® server. An LTPA junction is specific to one WebSphere server. If you add more than one server to the same junction point, all servers share the key file.

For single signon to succeed, WebSEAL and the WebSphere server must share the registry information.

The WebSphere server is responsible for setting up LTPA and the creation of the shared secret key. The WebSEAL participation involves the junction and cache configurations.

WebSphere version 5.1.1 and later support the new LTPA version 2 cookie (LtpaToken2). In these environments, use the -2 option to specify LtpaToken2 support.

WebSEAL does not use WebSphere LTPA Security Attribute Propagation to pass more attributes to the WebSphere server in the LTPA cookie.

Parent topic: LTPA overview

Forms single sign-on conceptsForms single sign-on conceptsForms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.single sign-onconceptsformssingle sign-on conceptsEnabling forms single sign-on authentication produces the following results: WebSEAL interrupts the authentication process that is initiated by the back-end applicationWebSEAL supplies data that is required by the login form and submits the login form on behalf of the user.WebSEAL saves and restores all cookies and headersThe user is unaware that a second login is taking place.The back-end application is unaware that the login form is not coming directly from the user.If the credential learning function is enabled, WebSEAL can learn the user name and password information so that future requests to the same junctioned resource does not prompt the user for authentication.Configure WebSEAL:To recognize and intercept the login formTo complete the appropriate authentication dataThe administrator enables forms single signon by:Creating a configuration file to specify how the login form is to be recognized, completed, and processedEnable forms single signon by configuring the appropriate junction with the –S option (which specifies the location of the configuration file)Single Signon SolutionsForms single sign-on process flowLearn about the single sign-on process so that you understand how a client browser accesses a resource.Forms single sign-on learning flowYou can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication. Requirements for application supportSingle signon for forms authentication is supported on applications that meet the specific requirements.Creation of the configuration file for forms single signonThe forms single signon configuration file is custom-created by the administrator and saved in any location.

Forms single sign-on concepts

Forms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.

Enabling forms single sign-on authentication produces the following results:

WebSEAL interrupts the authentication process that is initiated by the back-end application

WebSEAL supplies data that is required by the login form and submits the login form on behalf of the user.

WebSEAL saves and restores all cookies and headers

The user is unaware that a second login is taking place.

The back-end application is unaware that the login form is not coming directly from the user.

If the credential learning function is enabled, WebSEAL can learn the user name and password information so that future requests to the same junctioned resource does not prompt the user for authentication.

Configure WebSEAL:

To recognize and intercept the login form

To complete the appropriate authentication data

The administrator enables forms single signon by:

Creating a configuration file to specify how the login form is to be recognized, completed, and processed

Enable forms single signon by configuring the appropriate junction with the –S option (which specifies the location of the configuration file)

Forms single sign-on process flow
Learn about the single sign-on process so that you understand how a client browser accesses a resource.

Forms single sign-on learning flow
You can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication.

Requirements for application support
Single signon for forms authentication is supported on applications that meet the specific requirements.

Creation of the configuration file for forms single signon
The forms single signon configuration file is custom-created by the administrator and saved in any location.

Parent topic: Single Signon Solutions

Forms single sign-on process flowForms single sign-on process flowLearn about the single sign-on process so that you understand how a client browser accesses a resource.single signonprocess flowprocess flowsingle sign-onThe following scenario assumes that the user is authenticated in WebSEAL and that the credential learning function is disabled. When the credential learning function is enabled, the flow is discussed in Forms single sign-on learning flowYou can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication. . Forms single sign-on process flowForms single sign-on process flow Client browser requests the page: https://webseal/formsso/content.htmlWebSEAL passes the request to the junction.Because the back-end application requires the user to authenticate, a redirect to the application's login page (login.html) is sent back across the junction.WebSEAL passes the redirect to the browser.The browser follows the redirect and requests: https://webseal/formsso/login.html Everything to this point in the process flow is standard WebSEAL function.WebSEAL is configured for forms single sign-on (–S option on the junction). WebSEAL recognizes the request as a request for a login page, which is based on information in the forms SSO configuration file. The request is passed to the junction. WebSEAL saves all cookies that are sent by the browser for use in step 8.The application returns the login page and application-specific cookies. WebSEAL parses the HTML returned to identify the login form. When WebSEAL finds an HTML form, it compares the action URI in the form to the value of the login-form-action stanza entry in the custom configuration file. If there is a match, WebSEAL uses the form that it found. Otherwise, WebSEAL keeps searching for other forms. If no form in the page matches the action URI pattern from the configuration file, then WebSEAL stops forms single sign-on processing. WebSEAL then returns an error to the browser. WebSEAL parses the page to identify the request method, the action URI, and any other input fields in the form. WebSEAL then them for use in step 8.WebSEAL generates the authentication request (completes the login form) and sends it to the back-end application.The application authenticates the user with the authentication data that is supplied by WebSEAL in the form. The application returns a redirect to content.html.WebSEAL combines any cookies that are saved from the responses at step 7 and step 9, and returns these cookies with the redirect to the browser. If configured, login-success-pattern is used to inspect the response (even if credential learning is disabled). If the login is determined to be unsuccessful, the login page requested in step 5 is re-requested and returned to the user.This process completes the forms SSO-specific function.The browser follows the redirect and requests: https://webseal/formsso/content.htmlWebSEAL passes the request to the back-end application across the junction.During this process, the browser makes three requests to WebSEAL. From the user's perspective, only a single request for https://webseal/formsso/content.html is made. The other requests occur automatically through HTTP redirects.Forms single sign-on conceptsForms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.

Forms single sign-on process flow

Learn about the single sign-on process so that you understand how a client browser accesses a resource.

The following scenario assumes that the user is authenticated in WebSEAL and that the credential learning function is disabled. When the credential learning function is enabled, the flow is discussed in Forms single sign-on learning flow.

Figure 48. Forms single sign-on process flow

Client browser requests the page:

https://webseal/formsso/content.html

WebSEAL passes the request to the junction.

Because the back-end application requires the user to authenticate, a redirect to the application's login page (login.html) is sent back across the junction.

WebSEAL passes the redirect to the browser.

The browser follows the redirect and requests:

https://webseal/formsso/login.html

Note: Everything to this point in the process flow is standard WebSEAL function.

WebSEAL is configured for forms single sign-on (–S option on the junction). WebSEAL recognizes the request as a request for a login page, which is based on information in the forms SSO configuration file. The request is passed to the junction. WebSEAL saves all cookies that are sent by the browser for use in step 8.

The application returns the login page and application-specific cookies.

WebSEAL parses the HTML returned to identify the login form. When WebSEAL finds an HTML form, it compares the action URI in the form to the value of the login-form-action stanza entry in the custom configuration file. If there is a match, WebSEAL uses the form that it found. Otherwise, WebSEAL keeps searching for other forms. If no form in the page matches the action URI pattern from the configuration file, then WebSEAL stops forms single sign-on processing. WebSEAL then returns an error to the browser.

WebSEAL parses the page to identify the request method, the action URI, and any other input fields in the form. WebSEAL then them for use in step 8.

WebSEAL generates the authentication request (completes the login form) and sends it to the back-end application.

The application authenticates the user with the authentication data that is supplied by WebSEAL in the form. The application returns a redirect to content.html.

WebSEAL combines any cookies that are saved from the responses at step 7 and step 9, and returns these cookies with the redirect to the browser. If configured, login-success-pattern is used to inspect the response (even if credential learning is disabled). If the login is determined to be unsuccessful, the login page requested in step 5 is re-requested and returned to the user.

Note: This process completes the forms SSO-specific function.

The browser follows the redirect and requests:

https://webseal/formsso/content.html

WebSEAL passes the request to the back-end application across the junction.

During this process, the browser makes three requests to WebSEAL. From the user's perspective, only a single request for https://webseal/formsso/content.html is made. The other requests occur automatically through HTTP redirects.

Parent topic: Forms single sign-on concepts

Forms single sign-on learning flowYou can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication. Use the login-credential-learning stanza entry to enable the forms single sign-on learning function. Define what is a successful authentication with the login-success-pattern stanza entry.A credential learning flow In a successful learning flow, WebSEAL learns your user name and password information for a particular junctioned resource after you manually enter it for the first time. In future requests to the same junctioned resource, you will not be prompted for authentication as WebSEAL automatically provides such info. Forms single sign-on credential learning flow Client browser requests the page: https://webseal/formsso/content.htmlWebSEAL passes the request to the junction.Because the back-end application requires the user to authenticate, a redirect to the application's login page (login.html) is sent back across the junction.WebSEAL passes the redirect to the browser.The browser follows the redirect and requests: https://webseal/formsso/login.htmlWebSEAL is configured for forms single sign-on (–S option on the junction) with credential learning enabled. WebSEAL recognizes the request as a request for a login page, which is based on information in the forms SSO configuration file. The request is passed to the junction. WebSEAL saves all cookies that are sent by the browser for use in step 8.The application returns the login page and application-specific cookies. WebSEAL parses the HTML returned to identify the login form. WebSEAL detects the GSO resources associated with this junction. If WebSEAL cannot find a credential for the current user, it returns the response to the user. The user populates this form and submits it. WebSEAL inspects the request and extracts the credential information from the POST data. The request is then sent to the backing application. The application authenticates the user with the authentication data that is supplied by WebSEAL in the form.The response is examined by WebSEAL. If the response is successful, the extracted credentials are persisted to the GSO vault. WebSEAL combines any cookies that are saved from the responses and returns these cookies with the redirect to the browser. If the response is unsuccessful, WebSEAL disregards the credential and returns the response to the user.This process completes the forms single sign-on credential learning function.In the case of a successful authentication, the browser follows the redirect and requests: https://webseal/formsso/content.htmlWebSEAL passes the request to the back-end application across the junction.A credential re-learning flowThere are several cases where the learning feature might need to re-learn a set of credentials. The primary cases are:The password is reset by some out-of-band method. For example, the user is emailed a new password or password reset link.The user changes the password through a form. For example, the user is required by the system to change the password upon authentication. Forms single sign-on credential relearning flowClient browser requests the page: https://webseal/formsso/content.htmlWebSEAL passes the request to the junction.Because the back-end application requires the user to authenticate, a redirect to the application's login page (login.html) is sent back across the junction.WebSEAL passes the redirect to the browser.The browser follows the redirect and requests: https://webseal/formsso/login.htmlWebSEAL is configured for forms single sign-on (–S option on the junction) with credential learning enabled. WebSEAL recognizes the request as a request for a login page, which is based on information in the forms SSO configuration file. The request is passed to the junction. WebSEAL saves all cookies that are sent by the browser for use in step 8.The application returns the login page and application-specific cookies. WebSEAL parses the HTML returned to identify the login form. WebSEAL detects the GSO resources associated with this junction and finds a credential for the current user. WebSEAL generates the authentication request (completes the login form) and sends it to the back-end application.The authentication fails due to incorrect credentials.WebSEAL determines that the response does not satisfy any of the login success rules that are configured with the login-success-pattern stanza entry. WebSEAL returns the login page to the client. The user populates this login form and submits it. WebSEAL inspects the request and extracts the credential information from the POST data. The request is then sent to the back-end application. The application authenticates the user with the authentication data that is supplied by WebSEAL in the form. The authentication succeeds. The application returns a redirect to content.html.WebSEAL examines the response and detects that the response is successful. It updates the user's credential in the GSO vault with the extracted credential information. It also combines any cookies that were contained in the responses and returns these cookies with the redirect to the browser.This process completes the forms single sign-on credential learning function.The browser follows the redirect and requests: https://webseal/formsso/content.htmlWebSEAL passes the request to the back-end application across the junction.Example configuration [forms-sso-login-pages] login-page-stanza = myApp # If this is a learning junction. login-credential-learning = true [myApp] login-page = /login.jsp #Successful login is a 302, failure is a 200 login-success-pattern = -200 +302 [location:*/landingPage] login-form-action = /j_security_check gso-resource = myGso argument-stanza = myApp-arguments [myApp-arguments] j_username=gso:username j_password=gso:passwordForms single sign-on conceptsForms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.

Forms single sign-on learning flow

You can configure WebSEAL to learn your user name and password information so that future requests to the same junctioned resource will not prompt you for authentication.

Use the login-credential-learning stanza entry to enable the forms single sign-on learning function. Define what is a successful authentication with the login-success-pattern stanza entry.

A credential learning flow

In a successful learning flow, WebSEAL learns your user name and password information for a particular junctioned resource after you manually enter it for the first time. In future requests to the same junctioned resource, you will not be prompted for authentication as WebSEAL automatically provides such info.

Figure 49. Forms single sign-on credential learning flow

Client browser requests the page:

https://webseal/formsso/content.html

WebSEAL passes the request to the junction.

Because the back-end application requires the user to authenticate, a redirect to the application's login page (login.html) is sent back across the junction.

WebSEAL passes the redirect to the browser.

The browser follows the redirect and requests:

https://webseal/formsso/login.html

WebSEAL is configured for forms single sign-on (–S option on the junction) with credential learning enabled. WebSEAL recognizes the request as a request for a login page, which is based on information in the forms SSO configuration file. The request is passed to the junction. WebSEAL saves all cookies that are sent by the browser for use in step 8.

The application returns the login page and application-specific cookies.

WebSEAL parses the HTML returned to identify the login form. WebSEAL detects the GSO resources associated with this junction. If WebSEAL cannot find a credential for the current user, it returns the response to the user.

The user populates this form and submits it.

WebSEAL inspects the request and extracts the credential information from the POST data.

The request is then sent to the backing application.

The application authenticates the user with the authentication data that is supplied by WebSEAL in the form.

The response is examined by WebSEAL. If the response is successful, the extracted credentials are persisted to the GSO vault. WebSEAL combines any cookies that are saved from the responses and returns these cookies with the redirect to the browser. If the response is unsuccessful, WebSEAL disregards the credential and returns the response to the user.

Note: This process completes the forms single sign-on credential learning function.

In the case of a successful authentication, the browser follows the redirect and requests:

https://webseal/formsso/content.html

WebSEAL passes the request to the back-end application across the junction.

A credential re-learning flow

There are several cases where the learning feature might need to re-learn a set of credentials. The primary cases are:

The password is reset by some out-of-band method. For example, the user is emailed a new password or password reset link.

The user changes the password through a form. For example, the user is required by the system to change the password upon authentication.

Figure 50. Forms single sign-on credential relearning flow

Client browser requests the page:

https://webseal/formsso/content.html

WebSEAL passes the request to the junction.

Because the back-end application requires the user to authenticate, a redirect to the application's login page (login.html) is sent back across the junction.

WebSEAL passes the redirect to the browser.

The browser follows the redirect and requests:

https://webseal/formsso/login.html

WebSEAL is configured for forms single sign-on (–S option on the junction) with credential learning enabled. WebSEAL recognizes the request as a request for a login page, which is based on information in the forms SSO configuration file. The request is passed to the junction. WebSEAL saves all cookies that are sent by the browser for use in step 8.

The application returns the login page and application-specific cookies.

WebSEAL parses the HTML returned to identify the login form.

WebSEAL detects the GSO resources associated with this junction and finds a credential for the current user. WebSEAL generates the authentication request (completes the login form) and sends it to the back-end application.

The authentication fails due to incorrect credentials.

WebSEAL determines that the response does not satisfy any of the login success rules that are configured with the login-success-pattern stanza entry. WebSEAL returns the login page to the client.

The user populates this login form and submits it.

WebSEAL inspects the request and extracts the credential information from the POST data.

The request is then sent to the back-end application.

The application authenticates the user with the authentication data that is supplied by WebSEAL in the form. The authentication succeeds. The application returns a redirect to content.html.

WebSEAL examines the response and detects that the response is successful. It updates the user's credential in the GSO vault with the extracted credential information. It also combines any cookies that were contained in the responses and returns these cookies with the redirect to the browser.

Note: This process completes the forms single sign-on credential learning function.

The browser follows the redirect and requests:

https://webseal/formsso/content.html

WebSEAL passes the request to the back-end application across the junction.

Example configuration

[forms-sso-login-pages]
login-page-stanza = myApp
# If this is a learning junction.
login-credential-learning = true

[myApp]
login-page = /login.jsp
#Successful login is a 302, failure is a 200
login-success-pattern = -200 +302 [location:*/landingPage]
login-form-action = /j_security_check
gso-resource = myGso
argument-stanza = myApp-arguments

[myApp-arguments]
j_username=gso:username
j_password=gso:password

Parent topic: Forms single sign-on concepts

Requirements for application supportRequirements for application supportRequirements for application support in IBM Security Access Manager for WebSingle signon for forms authentication is supported on applications that meet the specific requirements.applicationsupportApplications must meet these requirements: The login page or pages for the application must be uniquely identifiable with a single regular expression or several regular expressions.The login page can include more than one HTML form. However, the login form must be identified by applying a regular expression to the action URIs of each of the login forms. Otherwise, the login form must be the first form in the login page. If you use the action attribute to identify the login form, know that the action attribute did not pass through WebSEAL's HTML filtering. The regular expression must match the action URI before it is filtered.Client-side scripting can be used to validate input data. However, it must not modify the input data, such as using JavaScript to set cookies in the user browser. Login data is submitted at only one point in the authentication process.The junction where the authentication request is directed must be the same junction where the login page is returned.Forms single sign-on conceptsForms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.

Requirements for application support

Single signon for forms authentication is supported on applications that meet the specific requirements.

Applications must meet these requirements:

The login page or pages for the application must be uniquely identifiable with a single regular expression or several regular expressions.

The login page can include more than one HTML form. However, the login form must be identified by applying a regular expression to the action URIs of each of the login forms. Otherwise, the login form must be the first form in the login page.

Note: If you use the action attribute to identify the login form, know that the action attribute did not pass through WebSEAL's HTML filtering. The regular expression must match the action URI before it is filtered.

Client-side scripting can be used to validate input data. However, it must not modify the input data, such as using JavaScript to set cookies in the user browser.

Login data is submitted at only one point in the authentication process.

The junction where the authentication request is directed must be the same junction where the login page is returned.

Parent topic: Forms single sign-on concepts

Creation of the configuration file for forms single signonCreation of the configuration file for forms single signonThe forms single signon configuration file is custom-created by the administrator and saved in any location.LMIForms Based Single Sign-on management pageconfiguration filesforms single signoncreationffso.conf.templateThe –S option on the junction enables the forms single signon functionality and specifies the name of the configuration file. See How to enable forms single signonLearn the command options to enable forms single signon so that you can configure the appropriate junction to support forms single signon.. A sample configuration file (containing commented instructions) is available through the LMI. Go to Secure Web Settings > Global Settings > Forms Based Single Sign-On to create an FSSO configuration file.The configuration file must begin with the [forms-sso-login-pages] stanza and has the following format[forms-sso-login-pages] login-page-stanza = xxxxx #login-page-stanza = aaaaa #login-page-stanza = bbbbb [xxxxx] login-page = regular-expression-page-match login-form-action = regular-expression-form-match gso-resource = gso-target argument-stanza = yyyyy [yyyyy] name = method:valueForms single sign-on conceptsForms single sign-on authentication supports existing applications that use HTML forms for authentication. It cannot be modified to directly trust the authentication that is done by WebSEAL.The [forms-sso-login-pages] stanzaThe forms single signon configuration file must always begin with the [forms-sso-login-pages] stanza. The custom login page stanzaEach custom login page stanza is used to intercept a particular URL pattern. Understand the various stanza entries so that you know how to use them in various scenarios.Use of regular expressionsKnow the special characters that are allowed in a regular expression so that you can use them in the configuration file. The argument stanzaUnderstand how you can use the argument stanza and the variables that are contained within the stanza.

Creation of the configuration file for forms single signon

The forms single signon configuration file is custom-created by the administrator and saved in any location.

The –S option on the junction enables the forms single signon functionality and specifies the name of the configuration file. See How to enable forms single signon. A sample configuration file (containing commented instructions) is available through the LMI. Go to Secure Web Settings > Global Settings > Forms Based Single Sign-On to create an FSSO configuration file.

The configuration file must begin with the [forms-sso-login-pages] stanza and has the following format

[forms-sso-login-pages]
login-page-stanza = xxxxx
#login-page-stanza = aaaaa
#login-page-stanza = bbbbb

[xxxxx]
login-page = regular-expression-page-match
login-form-action = regular-expression-form-match
gso-resource = gso-target
argument-stanza = yyyyy

[yyyyy]
name = method:value

The [forms-sso-login-pages] stanza
The forms single signon configuration file must always begin with the [forms-sso-login-pages] stanza.

The custom login page stanza
Each custom login page stanza is used to intercept a particular URL pattern. Understand the various stanza entries so that you know how to use them in various scenarios.

Use of regular expressions
Know the special characters that are allowed in a regular expression so that you can use them in the configuration file.

The argument stanza
Understand how you can use the argument stanza and the variables that are contained within the stanza.

Parent topic: Forms single sign-on concepts

The [forms-sso-login-pages] stanza The[forms-sso-login-pages] stanza The forms single signon configuration file must always begin with the [forms-sso-login-pages] stanza. forms-sso-login-pages stanzalogin-page-stanzaThe stanza contains one or more login-page-stanza entries that point to other custom-named stanzas. That stanza contains configuration information for the login pages that are found on the back-end application server.The ability to support multiple login pages on a single junction is important. It is important because a single back-end server might host several applications that each use a different authentication method.For example:[forms-sso-login-pages] login-page-stanza = loginpage1 login-page-stanza = loginpage2If you want to enable the credential learning function on this junction, add a login-credential-learning stanza entry with a value of true/yes/on to the [forms-sso-login-pages] stanza. The login-credential-learning stanza entry specifies whether the login credential learning function is enabled for this junction. If no value is provided for this stanza entry, the value defaults to false/no/off.Creation of the configuration file for forms single signonThe forms single signon configuration file is custom-created by the administrator and saved in any location.

The [forms-sso-login-pages] stanza

The forms single signon configuration file must always begin with the [forms-sso-login-pages] stanza.

The stanza contains one or more login-page-stanza entries that point to other custom-named stanzas. That stanza contains configuration information for the login pages that are found on the back-end application server.

The ability to support multiple login pages on a single junction is important. It is important because a single back-end server might host several applications that each use a different authentication method.

For example:

[forms-sso-login-pages]
login-page-stanza = loginpage1
login-page-stanza = loginpage2

If you want to enable the credential learning function on this junction, add a login-credential-learning stanza entry with a value of true/yes/on to the [forms-sso-login-pages] stanza. The login-credential-learning stanza entry specifies whether the login credential learning function is enabled for this junction. If no value is provided for this stanza entry, the value defaults to false/no/off.

Parent topic: Creation of the configuration file for forms single signon

The custom login page stanza The custom login page stanza Each custom login page stanza is used to intercept a particular URL pattern. Understand the various stanza entries so that you know how to use them in various scenarios.login-page stanza entrylogin-form-action stanza entrygso-resource stanza entryargument-stanza stanza entryThe stanza can contain the following stanza entries:Stanza EntriesDescriptionlogin-page This stanza entry specifies a pattern with a regular expression, that uniquely identifies requests for an application's login page. WebSEAL intercepts the pages and begins the forms single signon process. The regular expression is compared against the request URI and is relative to (and not including) the junction point where the server is mounted.login-form-action This stanza entry specifies a pattern, with a regular expression, that identifies which form contained in the intercepted page is the application's login form. The regular expression must match the "action" attribute of the login form.Do not use * as the value of this stanza entry if the credential learning function is enabled. The credential learning function uses the value of login-form-action to detect a POST containing credentials that might need to be learned. The * value matches on every POST to the junction. So if this entry is set to *, WebSEAL inspects every POST to extract matching values and potentially persist the values in the GSO store, even though the request might not be related to forms single sign-on at all.login-success-patternThis stanza entry defines the rules to detect whether a login attempt is successful.gso-resource This stanza entry specifies the GSO resource to use when the GSO user name and password from a GSO database is received. Leave this stanza entry blank if GSO is not used to store a GSO user name and password. If you use an external GSO data source that WebSEAL communicates with through the GSO RESTful web service, use the syntax described in GSO RESTful web serviceWhen you configure the GSO capability for forms single sign-on (FSSO) and basic authentication (BA), you are required to specify a GSO resource. Use the following syntax to specify the GSO resource if you want to use a web service to communicate GSO data from an external resource. . argument-stanza This stanza entry points to another custom stanza that lists the fields and data that is required for completing the login form.For example:[loginpage1] login-page = /cgi-bin/getloginpage* login-form-action = * gso-resource = argument-stanza = form1-dataAbout the login-page stanza entry:The value of the login-page stanza entry is a regular expression. WebSEAL uses it to determine if an incoming request is a request for a login page. If so, WebSEAL intercepts this request and begins the forms single signon processing.Only one login-page stanza entry is allowed in each custom login page stanza. You must create another custom login page stanza for each additional login-page stanza entry.The login-page regular expression is compared against the request URI, relative to the junction. In the following example, the URI of a request to a WebSEAL server called "websealA" for a resource on a junction called "junctionX" appears as:https://websealA.ibm.com/junctionX/auth/login.htmlThe part of this URL that is compared to the login-page regular expression:/auth/login.htmlAbout the login-form-action stanza entry:The login-form-action stanza entry is used to identify the login form on the intercepted page. Only one login-form-action stanza entry is allowed in each stanza.The value of the login-form-action stanza entry is a regular expression that is compared against the contents of the "action" attribute of the HTML "form" tag. The "action" attribute is a URI expressed as a relative, server-relative, or absolute path. The login-form-action stanza entry must match this path. It must match as it comes from the back-end server - even if it would normally be modified by WebSEAL before it is forwarded to the client.If multiple "action" attributes on the page match the regular expression, only the first match is accepted as the login form.If the regular expression does not match any form on the page, an error is returned to the browser. The error reports that the form might not be found.Do not use * as the value of this stanza entry if the credential learning function is enabled. The credential learning function uses the value of login-form-action to detect a POST containing credentials that might need to be learned. The * value matches on every POST to the junction. So if this entry is set to *, WebSEAL inspects every POST to extract matching values and potentially persist the values in the GSO store, even though the request might not be related to forms single sign-on at all.About the login-success-pattern stanza entryThis stanza entry contains a space separated list of rules. Each rule is made up of 3 parts.The operator, either a + or - character. A + operator means this rule is a positive rule. If it is matched, the login was successful. A match on a rule with the operator - means the authentication was unsuccessful and processing should halt.The return code pattern. This pattern is used to match the value of the status code of the request. Wildcard characters such as ? and * can be used. For example, 4* matches on all 4xx status codes.A list of header rules. This value must be contained in [] brackets and is a list of pairs. Each pair is made up of a header name and a header value pattern. Each pair must be separated with a , character. This part is optional.Only characters 0-9 and wildcard characters ? and * can be used in return code patterns. The format of the stanza entry is: {+/-}{ReturnCodePattern}{[HeaderName1:HeaderValuePattern1, HeaderName2:HeaderValuePattern2,...]}The rules for matching are as follows:The matching on header name is case insensitive. But the matching on value is case sensitive.This matching is done in the order the rules are defined and the first match halts further processing.Order the rule from the most to least specific (per return code). For example, the rule sequence "-200 +200[SuccessfulLogin:True]" is poor logic, as the second rule would never be evaluated.Trailing white space on the header name and leading white space on the header will be removed on the configured value and when the header is inspected.If no rule matches, a negative result is the default.Here is an example:[forms-sso-login-pages] login-page-stanza=fsso-cfg-args ... [fsso-cfg-args] ... #This configures 6 rules they are in order, as: # 1. Succeed if the response is a 302, with a header that looks like the pattern # "location:*/successful-login" # AND there is a set-cookie header which matches "Set-Cookie:PD-S-SESSION-ID=1_2_1*" # 2. Fail if the response is a 302 with the header which matches "location:*/failed-login" # 3. Succeed if a 200 is returned with a header like "Set-Cookie:PD-S-SESSION-ID=1_2_1*" # 4. Fail on any other 200 # 5. Fail on any response which starts with a 4 (400, 405, 415, etc) # 6. Fail on any response which starts with 50 (502, 500, etc) login-success-pattern = +302[location:*/successful-login,Set-Cookie:PD-S-SESSION-ID=1_2_1*] -302[location:*/failed-login] +200[Set-Cookie:PD-S-SESSION-ID=1_2_1*] -200 -4* -50? ...Creation of the configuration file for forms single signonThe forms single signon configuration file is custom-created by the administrator and saved in any location.

The custom login page stanza

Each custom login page stanza is used to intercept a particular URL pattern. Understand the various stanza entries so that you know how to use them in various scenarios.

The stanza can contain the following stanza entries:

Stanza Entries
Description

login-page

This stanza entry specifies a pattern with a regular expression, that uniquely identifies requests for an application's login page. WebSEAL intercepts the pages and begins the forms single signon process. The regular expression is compared against the request URI and is relative to (and not including) the junction point where the server is mounted.

login-form-action

This stanza entry specifies a pattern, with a regular expression, that identifies which form contained in the intercepted page is the application's login form. The regular expression must match the "action" attribute of the login form.

Note: Do not use * as the value of this stanza entry if the credential learning function is enabled. The credential learning function uses the value of login-form-action to detect a POST containing credentials that might need to be learned. The * value matches on every POST to the junction. So if this entry is set to *, WebSEAL inspects every POST to extract matching values and potentially persist the values in the GSO store, even though the request might not be related to forms single sign-on at all.

login-success-pattern

This stanza entry defines the rules to detect whether a login attempt is successful.

gso-resource

This stanza entry specifies the GSO resource to use when the GSO user name and password from a GSO database is received. Leave this stanza entry blank if GSO is not used to store a GSO user name and password.

If you use an external GSO data source that WebSEAL communicates with through the GSO RESTful web service, use the syntax described in GSO RESTful web service.

argument-stanza

This stanza entry points to another custom stanza that lists the fields and data that is required for completing the login form.

For example:

[loginpage1]
login-page = /cgi-bin/getloginpage*
login-form-action = *
gso-resource =
argument-stanza = form1-data

About the login-page stanza entry:

The value of the login-page stanza entry is a regular expression. WebSEAL uses it to determine if an incoming request is a request for a login page. If so, WebSEAL intercepts this request and begins the forms single signon processing.

Only one login-page stanza entry is allowed in each custom login page stanza. You must create another custom login page stanza for each additional login-page stanza entry.

The login-page regular expression is compared against the request URI, relative to the junction. In the following example, the URI of a request to a WebSEAL server called "websealA" for a resource on a junction called "junctionX" appears as:

https://websealA.ibm.com/junctionX/auth/login.html

The part of this URL that is compared to the login-page regular expression:

/auth/login.html

About the login-form-action stanza entry:

The login-form-action stanza entry is used to identify the login form on the intercepted page. Only one login-form-action stanza entry is allowed in each stanza.

The value of the login-form-action stanza entry is a regular expression that is compared against the contents of the "action" attribute of the HTML "form" tag. The "action" attribute is a URI expressed as a relative, server-relative, or absolute path. The login-form-action stanza entry must match this path. It must match as it comes from the back-end server - even if it would normally be modified by WebSEAL before it is forwarded to the client.

If multiple "action" attributes on the page match the regular expression, only the first match is accepted as the login form.

If the regular expression does not match any form on the page, an error is returned to the browser. The error reports that the form might not be found.

Note: Do not use * as the value of this stanza entry if the credential learning function is enabled. The credential learning function uses the value of login-form-action to detect a POST containing credentials that might need to be learned. The * value matches on every POST to the junction. So if this entry is set to *, WebSEAL inspects every POST to extract matching values and potentially persist the values in the GSO store, even though the request might not be related to forms single sign-on at all.

About the login-success-pattern stanza entry

This stanza entry contains a space separated list of rules. Each rule is made up of 3 parts.

The operator, either a + or - character. A + operator means this rule is a positive rule. If it is matched, the login was successful. A match on a rule with the operator - means the authentication was unsuccessful and processing should halt.

The return code pattern. This pattern is used to match the value of the status code of the request. Wildcard characters such as ? and * can be used. For example, 4* matches on all 4xx status codes.

A list of header rules. This value must be contained in [] brackets and is a list of pairs. Each pair is made up of a header name and a header value pattern. Each pair must be separated with a , character. This part is optional.

Note: Only characters 0-9 and wildcard characters ? and * can be used in return code patterns.

The format of the stanza entry is:

{+/-}{ReturnCodePattern}{[HeaderName1:HeaderValuePattern1,
HeaderName2:HeaderValuePattern2,...]}

The rules for matching are as follows:

The matching on header name is case insensitive. But the matching on value is case sensitive.

This matching is done in the order the rules are defined and the first match halts further processing.

Note: Order the rule from the most to least specific (per return code). For example, the rule sequence "-200 +200[SuccessfulLogin:True]" is poor logic, as the second rule would never be evaluated.

Trailing white space on the header name and leading white space on the header will be removed on the configured value and when the header is inspected.

If no rule matches, a negative result is the default.

Here is an example:

[forms-sso-login-pages]
login-page-stanza=fsso-cfg-args
...
[fsso-cfg-args]
...
#This configures 6 rules they are in order, as:
# 1. Succeed if the response is a 302, with a header that looks like the pattern
# "location:*/successful-login"
# AND there is a set-cookie header which matches "Set-Cookie:PD-S-SESSION-ID=1_2_1*"
# 2. Fail if the response is a 302 with the header which matches "location:*/failed-login"
# 3. Succeed if a 200 is returned with a header like "Set-Cookie:PD-S-SESSION-ID=1_2_1*"
# 4. Fail on any other 200
# 5. Fail on any response which starts with a 4 (400, 405, 415, etc)
# 6. Fail on any response which starts with 50 (502, 500, etc)
login-success-pattern = +302[location:*/successful-login,Set-Cookie:PD-S-SESSION-ID=1_2_1*]
-302[location:*/failed-login] +200[Set-Cookie:PD-S-SESSION-ID=1_2_1*] -200 -4* -50?
...

Parent topic: Creation of the configuration file for forms single signon

Use of regular expressions Use of regular expressions Know the special characters that are allowed in a regular expression so that you can use them in the configuration file. regular expressionsforms single signonlistThe following table lists the special characters that are allowed in regular expressions that are used in the forms single signon configuration file.Special characters allowed in regular expressions in the forms single signon configuration fileSpecial characters allowedDescription*Matches zero or more characters?Matches any one character\Escape character (for example, \? matches?)[acd]Matches character a, c, or d (case-sensitive)[^acd]Matches any character except a, c, or d (case-sensitive)[a-z]Matches any character between a and z (lowercase letter)[^0-9]Matches any character not 0 - 9 (not a number)[a-zA-Z]Matches any character between a and z (lowercase) or A and Z (uppercase)In most cases, special characters are not required because the login page request is a single identifiable URI. In some cases, you can use the asterisk (*) at the end of the expression. Use the asterisk (*) character so that any query data at the end of the URI does not prevent the login page from being matched.Creation of the configuration file for forms single signonThe forms single signon configuration file is custom-created by the administrator and saved in any location.

Use of regular expressions

Know the special characters that are allowed in a regular expression so that you can use them in the configuration file.

The following table lists the special characters that are allowed in regular expressions that are used in the forms single signon configuration file.

Table 72. Special characters allowed in regular expressions in the forms single signon configuration file

Special characters allowed | Description
* | Matches zero or more characters
? | Matches any one character
\ | Escape character (for example, \? matches?)
[acd] | Matches character a, c, or d (case-sensitive)
[^acd] | Matches any character except a, c, or d (case-sensitive)
[a-z] | Matches any character between a and z (lowercase letter)
[^0-9] | Matches any character not 0 - 9 (not a number)
[a-zA-Z] | Matches any character between a and z (lowercase) or A and Z (uppercase)

In most cases, special characters are not required because the login page request is a single identifiable URI. In some cases, you can use the asterisk (*) at the end of the expression. Use the asterisk (*) character so that any query data at the end of the URI does not prevent the login page from being matched.

Parent topic: Creation of the configuration file for forms single signon

The argument stanzaThe argument stanzaArgument stanza in IBM Security Access Manager for WebUnderstand how you can use the argument stanza and the variables that are contained within the stanza. argument stanzastanzasargumentsThe custom argument stanza contains one or more entries in the following form:name = method:valuenameThe value of the name variable is set to equal the value of the "name" attribute of the HTML "input" tag. For example: <input name=uid type=text>Username</input>This variable can also use the value of the name attribute of the HTML select or textarea tags.method:valueThis combination retrieves the authentication data that is required by the form. The authentication data can include:Literal string data string:text The input that is used is the text string.GSO user name and password gso:username gso:password The input is the current user's GSO user name and password (from the target that is specified in the custom login page stanza).Value of an attribute in the user's credential cred:cred-ext-attr-name By default, the credential includes information such as the user's Security Access Manager user name and DN. To use the user's Security Access Manager user name as the input value, specify the value as: cred:azn_cred_principal_name The user's DN can be accessed as: cred:azn_cred_authzn_id Custom credential attributes (added through the tag-value mechanism) can also be used.It is not necessary to specify hidden input fields in this stanza. These fields are automatically retrieved from the HTML form and submitted with the authentication request.For example:[form1-data] uid = string:brianCreation of the configuration file for forms single signonThe forms single signon configuration file is custom-created by the administrator and saved in any location.

The argument stanza

Understand how you can use the argument stanza and the variables that are contained within the stanza.

The custom argument stanza contains one or more entries in the following form:

name = method:value

name

The value of the name variable is set to equal the value of the "name" attribute of the HTML "input" tag. For example:

<input name=uid type=text>Username</input>

This variable can also use the value of the name attribute of the HTML select or textarea tags.

method:value

This combination retrieves the authentication data that is required by the form. The authentication data can include:

Literal string data

string:text

The input that is used is the text string.

GSO user name and password

gso:username
gso:password

The input is the current user's GSO user name and password (from the target that is specified in the custom login page stanza).

Value of an attribute in the user's credential

cred:cred-ext-attr-name

By default, the credential includes information such as the user's Security Access Manager user name and DN. To use the user's Security Access Manager user name as the input value, specify the value as:

cred:azn_cred_principal_name

The user's DN can be accessed as:

cred:azn_cred_authzn_id

Custom credential attributes (added through the tag-value mechanism) can also be used.

It is not necessary to specify hidden input fields in this stanza. These fields are automatically retrieved from the HTML form and submitted with the authentication request.

For example:

[form1-data]
uid = string:brian

Parent topic: Creation of the configuration file for forms single signon

How to enable forms single signon How to enable forms single signon Learn the command options to enable forms single signon so that you can configure the appropriate junction to support forms single signon.junctionsforms single signon (-S)formsenabling single signonYou must configure the appropriate junction to support forms single signon after you update the custom forms single signon configuration file. You must locate the file in an appropriate directory. Use the –S junction option with the pdadmin create command:-S config-fileThe config-file argument specifies the location of the custom forms single signon configuration file. The –S junction option enables the forms single signon function on the junction. For example:UNIX:pdadmin> server task web1-webseald-cruz create -t tcp -h websvrA -S fsso.conf /jctXThe configuration file is read when the junction is created and each time WebSEAL is started. Errors in the configuration file can cause WebSEAL to fail at start-up. Single Signon Solutions

How to enable forms single signon

Learn the command options to enable forms single signon so that you can configure the appropriate junction to support forms single signon.

You must configure the appropriate junction to support forms single signon after you update the custom forms single signon configuration file. You must locate the file in an appropriate directory. Use the –S junction option with the pdadmin create command:

-S config-file

The config-file argument specifies the location of the custom forms single signon configuration file.

The –S junction option enables the forms single signon function on the junction. For example:

UNIX:

pdadmin> server task web1-webseald-cruz create -t tcp -h websvrA
-S fsso.conf /jctX

The configuration file is read when the junction is created and each time WebSEAL is started. Errors in the configuration file can cause WebSEAL to fail at start-up.

Parent topic: Single Signon Solutions

Forms single sign-on exampleForms single sign-on exampleForms single sign-on exampleIBM Security Access Manager for WebThe following help site sample invokes its own forms-based login. The example shows how a forms single sign-on solution can provide seamless access to the site for its enrolled users.form-based loginform-basedsingle signon examplesingle signonform-based exampleThis section contains:A form section, similar to the form sent on the HTML login page returned by the help applicationThe custom forms single signon configuration file used to process this formThe form found in the intercepted HTML page: <form name="confirm" method="post" action="../files/wcls_hnb_welcomePage2.cgi"> <p> Employee Serial Number:&nbsp; <input name="data" size="10" maxlength="6"> <p> Country Name: <select name="Cntselect" size="1"> <OPTION value="notselected" selected>Select Country</OPTION> <OPTION value=675>United Arab Emirates - IBM</OPTION> <OPTION value=866>United Kingdom</OPTION> <OPTION value=897>United States</OPTION> <OPTION value=869>Uruguay</OPTION> <OPTION value=871>Venezuela</OPTION> <OPTION value=852>Vietnam</OPTION> <OPTION value=707>Yugoslavia</OPTION> <OPTION value=825>Zimbabwe</OPTION> </select> <p> <input type=submit value=Submit> </form>The custom configuration file used to process this form: helpnow FSSO configuration: [forms-sso-login-pages] login-page-stanza = helpnow [helpnow] # The HelpNow site redirects you to this page # you are required to log in. login-page = /bluebase/bin/files/wcls_hnb_welcomePage1.cgi # The login form is the first in the page, so we can just call it # '*'. login-form-action = * # The GSO resource, helpnow, contains the employee serial number. gso-resource = helpnow # Authentication arguments follow. argument-stanza = auth-data [auth-data] # The 'data' field contains the employee serial number. data = gso:username # The Cntselect field contains a number corresponding to the employee's # country of origin. The string "897" corresponds to the USA. Cntselect = string:897Single Signon Solutions

Forms single sign-on example

The following help site sample invokes its own forms-based login. The example shows how a forms single sign-on solution can provide seamless access to the site for its enrolled users.

This section contains:

A form section, similar to the form sent on the HTML login page returned by the help application

The custom forms single signon configuration file used to process this form

The form found in the intercepted HTML page:

<form name="confirm" method="post" action="../files/wcls_hnb_welcomePage2.cgi">
<p>
Employee Serial Number:&nbsp;
<input name="data" size="10" maxlength="6">
<p>
Country Name:
<select name="Cntselect" size="1">
<OPTION value="notselected" selected>Select Country</OPTION>
<OPTION value=675>United Arab Emirates - IBM</OPTION>
<OPTION value=866>United Kingdom</OPTION>
<OPTION value=897>United States</OPTION>
<OPTION value=869>Uruguay</OPTION>
<OPTION value=871>Venezuela</OPTION>
<OPTION value=852>Vietnam</OPTION>
<OPTION value=707>Yugoslavia</OPTION>
<OPTION value=825>Zimbabwe</OPTION>
</select>
<p>
<input type=submit value=Submit>
</form>

The custom configuration file used to process this form:

helpnow FSSO configuration:

[forms-sso-login-pages]
login-page-stanza = helpnow

[helpnow]
# The HelpNow site redirects you to this page
# you are required to log in.
login-page = /bluebase/bin/files/wcls_hnb_welcomePage1.cgi

# The login form is the first in the page, so we can just call it
# '*'.
login-form-action = *

# The GSO resource, helpnow, contains the employee serial number.
gso-resource = helpnow

# Authentication arguments follow.
argument-stanza = auth-data

[auth-data]
# The 'data' field contains the employee serial number.
data = gso:username

# The Cntselect field contains a number corresponding to the employee's
# country of origin. The string "897" corresponds to the USA.
Cntselect = string:897

Parent topic: Single Signon Solutions

Single sign-on using Kerberos constrained delegationYou can set up constrained delegation by allowing WebSEAL to request a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC). The ticket can then be used by WebSEAL to impersonate the client to authenticate with the junctioned Web server.Kerberosconstrained delegationsingle signonKerberos constrained delegationTwo extensions are involved in this process: Service-for-User-to-Self (S4U2Self) and Service-for-User-to-Proxy (S4U2Proxy). S4U2Self allows a service to acquire a ticket from the KDC on behalf of a client. S4U2Proxy allows a service to use the ticket obtained through S4U2Self to acquire another ticket to an external service.The diagram above shows a sample deployment of single sign-on using Kerberos constrained delegation. Client uses the standard Security Access Manager authentication process to authenticate to WebSEAL over HTTPS or HTTP and requests an object on the junctioned server. WebSEAL authorizes the request from the client, and determines that a Kerberos ticket is needed to access the junctioned application.WebSEAL requests a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC).KDC issues the Kerberos ticket to WebSEAL.The WebSEAL server forwards the Kerberos ticket along with the client request to the junctioned Web server over either HTTP or HTTPS.The junctioned Web server requests validation of the Kerberos ticket from the KDC. The KDC verifies that the Kerberos ticket is valid. The junctioned Web server returns an HTTP response to WebSEAL.WebSEAL returns the HTTP response to the client.To allow WebSEAL to perform Kerberos single sign-on for a junction, ensure that:Service users are created in Active Directory.The Kerberos Configuration and WebSEAL configuration file are updated on the appliance.The WebSEAL junction is created.Kerberos tickets rely on embedded time stamps to decide the expiration of old tickets. For this reason, it is important to ensure that the clocks on all machines in the environment are synchronized.Single Signon SolutionsCreating the WebSEAL user in Active DirectoryIn order for constrained delegation to operate correctly, WebSEAL and the target service must be running as Active Directory (AD) users that have an assigned Service Principal Name (SPN).WebSEAL Kerberos configurationComplete the Kerberos configuration on the appliance so that single sign-on with Kerberos constrained delegation can work.Configuring WebSEAL to enable Kerberos single sign-onTo enable Kerberos single sign-on for a junction, set the value of the kerberos-sso-enable entry in the [junction] stanza to yes.

Single sign-on using Kerberos constrained delegation

You can set up constrained delegation by allowing WebSEAL to request a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC). The ticket can then be used by WebSEAL to impersonate the client to authenticate with the junctioned Web server.

Two extensions are involved in this process: Service-for-User-to-Self (S4U2Self) and Service-for-User-to-Proxy (S4U2Proxy). S4U2Self allows a service to acquire a ticket from the KDC on behalf of a client. S4U2Proxy allows a service to use the ticket obtained through S4U2Self to acquire another ticket to an external service.

The diagram above shows a sample deployment of single sign-on using Kerberos constrained delegation.

Client uses the standard Security Access Manager authentication process to authenticate to WebSEAL over HTTPS or HTTP and requests an object on the junctioned server. WebSEAL authorizes the request from the client, and determines that a Kerberos ticket is needed to access the junctioned application.

WebSEAL requests a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC).

KDC issues the Kerberos ticket to WebSEAL.

The WebSEAL server forwards the Kerberos ticket along with the client request to the junctioned Web server over either HTTP or HTTPS.

The junctioned Web server requests validation of the Kerberos ticket from the KDC.

The KDC verifies that the Kerberos ticket is valid.

The junctioned Web server returns an HTTP response to WebSEAL.

WebSEAL returns the HTTP response to the client.

To allow WebSEAL to perform Kerberos single sign-on for a junction, ensure that:

Service users are created in Active Directory.

The Kerberos Configuration and WebSEAL configuration file are updated on the appliance.

The WebSEAL junction is created.

Kerberos tickets rely on embedded time stamps to decide the expiration of old tickets. For this reason, it is important to ensure that the clocks on all machines in the environment are synchronized.

Creating the WebSEAL user in Active Directory
In order for constrained delegation to operate correctly, WebSEAL and the target service must be running as Active Directory (AD) users that have an assigned Service Principal Name (SPN).

WebSEAL Kerberos configuration
Complete the Kerberos configuration on the appliance so that single sign-on with Kerberos constrained delegation can work.

Configuring WebSEAL to enable Kerberos single sign-on
To enable Kerberos single sign-on for a junction, set the value of the kerberos-sso-enable entry in the [junction] stanza to yes.

Parent topic: Single Signon Solutions

Creating the WebSEAL user in Active DirectoryIn order for constrained delegation to operate correctly, WebSEAL and the target service must be running as Active Directory (AD) users that have an assigned Service Principal Name (SPN).WebSEALcreating usersActive DirectoryActive Directorycreating WebSEAL usersThe new WebSEAL user account SPN that is created in Active Directory is used in the WebSEAL configuration as the kerberos-principal-name. The target service user account SPN is used as the kerberos-service-name. For instructions about how to configure Windows for constrained delegation, see the Developer Works article IBM Tivoli Access Manager: WebSEAL Kerberos Junctions. To create the WebSEAL user and the target service user, complete the following steps.Create and initialize the AD WebSEAL user.On the domain controller, select StartAdministrative ToolsActive Directory Users and Computers.Create a new user whose password never expires. For example, webseal.Prepare the new user so that it can be used as the WebSEAL identity through a key table file. You can use the ktpass command line utility that is provided as a part of the Windows support tools to do this. After the SPN has been set for the user, change the login name to reflect the SPN. For example:ktpass -out <Directory For Keytab> -princ HTTP/<WebSEALUser Name>@<AD DOMAIN NAME> \ -mapUser <WebSEAL UserName> -mapOp set -pass <Password> -pType KRB5_NT_PRINCIPALktpass -out C:\webseal.keytab -princ HTTP/webseal@AD_DOMAIN.COM -mapUser AD_DOMAIN\webseal -mapOp set -pass XXX -pType KRB5_NT_PRINCIPALSee Ktpass for more details.Create and initialize the AD target service user.On the domain controller, select StartAdministrative ToolsActive Directory Users and Computers. Create a new user whose password never expires. For example, targetservice.Prepare the new user so that it can execute as a Kerberos service. You can use the ktpass command line utility that is provided as a part of the Windows support tools to do this. After the SPN has been set for the user, change the login name to reflect the SPN. For example:ktpass -princ HTTP/<Target Server Name>.<DNS domain name>@<AD DOMAIN NAME> \ -mapuser <Target User Name> -mapOp setktpass -princ HTTP/target_service.ad_domain.com@AD_DOMAIN.COM -mapUser AD_DOMAIN\target_service -mapOp set -pass XXX -pType KRB5_NT_PRINCIPALBy default, the security policy of the machine does not allow an AD user to execute a local service. You must change the setting so that the new AD user is allowed to execute a local service. Select StartAdministrative ToolsLocal Security Policy.In the Local Security Policy window, select Security SettingsLocal PoliciesUser Rights Assignment.In the right panel, double-click Log on as a service.Click Add User or Group.Enter the new AD user's name and then click OK to include the user in this policy.Set the WebSEAL user to be trusted for delegation to the target service user.On the domain controller, select StartAdministrative ToolsActive Directory Users and Computers.Right-click the WebSEAL user.Click Properties.Select the Delegation tab.Select Trust this user for delegation to specified services only and Use any authentication protocol. For constrained delegation, Use Kerberos only cannot be used.Click Add.Click Users and Computers.Search for the target service user.Click OK.In the Add Services window, make sure the HTTP service is selected and then click OK.Click OK to save and exit the user properties.User accounts should also exist for the WebSEAL users that have permission to access the target service. These accounts do not require SPNs set-up with the ktpass tool.Single sign-on using Kerberos constrained delegationYou can set up constrained delegation by allowing WebSEAL to request a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC). The ticket can then be used by WebSEAL to impersonate the client to authenticate with the junctioned Web server.

Creating the WebSEAL user in Active Directory

In order for constrained delegation to operate correctly, WebSEAL and the target service must be running as Active Directory (AD) users that have an assigned Service Principal Name (SPN).

About this task

The new WebSEAL user account SPN that is created in Active Directory is used in the WebSEAL configuration as the kerberos-principal-name. The target service user account SPN is used as the kerberos-service-name. For instructions about how to configure Windows for constrained delegation, see the Developer Works article IBM Tivoli Access Manager: WebSEAL Kerberos Junctions.

To create the WebSEAL user and the target service user, complete the following steps.

Procedure

Create and initialize the AD WebSEAL user.

On the domain controller, select Start > Administrative Tools > Active Directory Users and Computers.

Create a new user whose password never expires. For example, webseal.

Prepare the new user so that it can be used as the WebSEAL identity through a key table file. You can use the ktpass command line utility that is provided as a part of the Windows support tools to do this. After the SPN has been set for the user, change the login name to reflect the SPN. For example:

ktpass -out <Directory For Keytab> -princ HTTP/<WebSEALUser Name>@<AD DOMAIN NAME> \
-mapUser <WebSEAL UserName> -mapOp set -pass <Password> -pType KRB5_NT_PRINCIPAL

ktpass -out C:\webseal.keytab -princ HTTP/webseal@AD_DOMAIN.COM
-mapUser AD_DOMAIN\webseal -mapOp set -pass XXX -pType KRB5_NT_PRINCIPAL

Note: See Ktpass for more details.

Create and initialize the AD target service user.

On the domain controller, select Start > Administrative Tools > Active Directory Users and Computers.

Create a new user whose password never expires. For example, targetservice.

Prepare the new user so that it can execute as a Kerberos service. You can use the ktpass command line utility that is provided as a part of the Windows support tools to do this. After the SPN has been set for the user, change the login name to reflect the SPN. For example:

ktpass -princ HTTP/<Target Server Name>.<DNS domain name>@<AD DOMAIN NAME> \
-mapuser <Target User Name> -mapOp set

ktpass -princ HTTP/target_service.ad_domain.com@AD_DOMAIN.COM
-mapUser AD_DOMAIN\target_service
-mapOp set -pass XXX -pType KRB5_NT_PRINCIPAL

By default, the security policy of the machine does not allow an AD user to execute a local service. You must change the setting so that the new AD user is allowed to execute a local service.

Select Start > Administrative Tools > Local Security Policy.

In the Local Security Policy window, select Security Settings > Local Policies > User Rights Assignment.

In the right panel, double-click Log on as a service.

Click Add User or Group.

Enter the new AD user's name and then click OK to include the user in this policy.

Set the WebSEAL user to be trusted for delegation to the target service user.

On the domain controller, select Start > Administrative Tools > Active Directory Users and Computers.

Right-click the WebSEAL user.

Click Properties.

Select the Delegation tab.

Select Trust this user for delegation to specified services only and Use any authentication protocol. For constrained delegation, Use Kerberos only cannot be used.

Click Add.

Click Users and Computers.

Search for the target service user.

Click OK.

In the Add Services window, make sure the HTTP service is selected and then click OK.

Click OK to save and exit the user properties.

User accounts should also exist for the WebSEAL users that have permission to access the target service. These accounts do not require SPNs set-up with the ktpass tool.

Parent topic: Single sign-on using Kerberos constrained delegation

WebSEAL Kerberos configurationWebSEAL Kerberos configurationWebSEAL Kerberos configurationComplete the Kerberos configuration on the appliance so that single sign-on with Kerberos constrained delegation can work.WebSEALKerberos configurationFrom the top menu, select Secure Web SettingsGlobal SettingsKerberos Configuration.On the Realms tab, select NewRealm.Enter the AD domain name.For example, <DOMAIN>.Click Save.Select the new realm.Click NewProperty.In the Create New Property window, select kdc.Enter the AD KDC address in the Value field. The AD KDC address is the name of the domain controller. For example, <machine>.<domain>.Click Save.On the Defaults tab, change the default_realm to be the new realm that you just created.On the Keyfiles tab, import the key table file that was generated for the WebSEAL user.Deploy the changes.From the top menu, select Manage System SettingsNetwork SettingsHosts File.Add the AD domain and KDC addresses to the hosts file.This step is only necessary if the DNS is not configured.Deploy the changes.Single sign-on using Kerberos constrained delegationYou can set up constrained delegation by allowing WebSEAL to request a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC). The ticket can then be used by WebSEAL to impersonate the client to authenticate with the junctioned Web server.

WebSEAL Kerberos configuration

Complete the Kerberos configuration on the appliance so that single sign-on with Kerberos constrained delegation can work.

Procedure

From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration.

On the Realms tab, select New > Realm.

Enter the AD domain name. For example, <DOMAIN>.

Click Save.

Select the new realm.

Click New > Property.

In the Create New Property window, select kdc.

Enter the AD KDC address in the Value field. The AD KDC address is the name of the domain controller. For example, <machine>.<domain>.

Click Save.

On the Defaults tab, change the default_realm to be the new realm that you just created.

On the Keyfiles tab, import the key table file that was generated for the WebSEAL user.

Deploy the changes.

From the top menu, select Manage System Settings > Network Settings > Hosts File.

Add the AD domain and KDC addresses to the hosts file.

Note: This step is only necessary if the DNS is not configured.

Deploy the changes.

Parent topic: Single sign-on using Kerberos constrained delegation

Configuring WebSEAL to enable Kerberos single sign-onConfiguring WebSEAL to enable Kerberos single sign-onConfiguring WebSEAL to enable Kerberos single sign-onTo enable Kerberos single sign-on for a junction, set the value of the kerberos-sso-enable entry in the [junction] stanza to yes.WebSEALKerberos single signonsingle signonenablingFor more information about the [junction] stanza, see [junction] stanza.From the top menu, select Secure Web SettingsManageReverse Proxy.Create a new WebSEAL instance.Select the instance.Click ManageConfiguration File.Locate the [junction] stanza.Update the configuration items accordingly.For example:kerberos-sso-enable = yes kerberos-keytab-file = webseal.keytab kerberos-principal-name = HTTP/webseal@AD_DOMAIN kerberos-service-name = HTTP/target_service.ad_domain.com@AD_DOMAIN.COMThese SPNs are set in Active Directory in Creating the WebSEAL user in Active DirectoryIn order for constrained delegation to operate correctly, WebSEAL and the target service must be running as Active Directory (AD) users that have an assigned Service Principal Name (SPN).. The domain names are case-sensitive and must be uppercase.To extend Kerberos SSO support to users on domains other than the WebSEAL service account domain, use the kerberos-user-identityUse the kerberos-user-identity stanza entry to enable and define a custom user principal name (UPN). The custom UPN can be constructed from either plain text or the contents of credential attributes. stanza entry to enable and define a custom user principal name (UPN).Click Save.Deploy the changes.Restart the WebSEAL instance.Single sign-on using Kerberos constrained delegationYou can set up constrained delegation by allowing WebSEAL to request a Windows Kerberos ticket on behalf of the client from the key distribution centre (KDC). The ticket can then be used by WebSEAL to impersonate the client to authenticate with the junctioned Web server.

Configuring WebSEAL to enable Kerberos single sign-on

To enable Kerberos single sign-on for a junction, set the value of the kerberos-sso-enable entry in the [junction] stanza to yes.

About this task

For more information about the [junction] stanza, see [junction] stanza.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Create a new WebSEAL instance.

Select the instance.

Click Manage > Configuration File.

Locate the [junction] stanza.

Update the configuration items accordingly. For example:

kerberos-sso-enable = yes
kerberos-keytab-file = webseal.keytab
kerberos-principal-name = HTTP/webseal@AD_DOMAIN
kerberos-service-name = HTTP/target_service.ad_domain.com@AD_DOMAIN.COM

Note: These SPNs are set in Active Directory in Creating the WebSEAL user in Active Directory. The domain names are case-sensitive and must be uppercase.

To extend Kerberos SSO support to users on domains other than the WebSEAL service account domain, use the kerberos-user-identity stanza entry to enable and define a custom user principal name (UPN).

Click Save.

Deploy the changes.

Restart the WebSEAL instance.

Parent topic: Single sign-on using Kerberos constrained delegation

Cross-domain single signon conceptsCross-domain single signon conceptsCDSSO authenticationconceptsauthenticationCDSSOsingle signonCDSOOcross-domain single signonCDSSOThis section contains the following topics:Single Signon SolutionsCross-domain single signon overviewDefault and custom authentication tokensExtended user attributes and identity mappingCDSSO process flow with attribute transfer and user mapping

Cross-domain single signon concepts

This section contains the following topics:

Cross-domain single signon overview

Default and custom authentication tokens

Extended user attributes and identity mapping

CDSSO process flow with attribute transfer and user mapping

Parent topic: Single Signon Solutions

Cross-domain single signon overviewCross-domain single signon overviewCDSSO authenticationoverviewcross-domain single signonoverviewCross-domain single signon (sometimes referred to as CDSSO) provides a default mechanism for transferring user credentials between unique servers and domains. CDSSO allows Web users to perform a single signon and move seamlessly between two separate secure domains when requesting a resource. The CDSSO authentication mechanism does not rely on a master authentication server (sometimes referred to as the MAS) (see E-community single signonE-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.).CDSSO supports the goals of scalable network architecture by allowing the integration of multiple secure domains. For example, a large corporate extranet can be set up with two or more unique domains—each with its own users and object space. CDSSO allows movement of users between the domains with a single signon.When a user makes a request to a resource located in another domain, the CDSSO mechanism transfers an encrypted user identity token from the first domain to the second domain. The identity information in this token indicates to the receiving domain that the user is successfully authenticated in the first domain. The identity does not contain password information. The receiving server uses this token to build credentials in its own cache for that user. The user is not forced to perform an additional login.Cross-domain single signon concepts

Cross-domain single signon overview

Cross-domain single signon (sometimes referred to as CDSSO) provides a default mechanism for transferring user credentials between unique servers and domains. CDSSO allows Web users to perform a single signon and move seamlessly between two separate secure domains when requesting a resource. The CDSSO authentication mechanism does not rely on a master authentication server (sometimes referred to as the MAS) (see E-community single signon).

CDSSO supports the goals of scalable network architecture by allowing the integration of multiple secure domains. For example, a large corporate extranet can be set up with two or more unique domains—each with its own users and object space. CDSSO allows movement of users between the domains with a single signon.

When a user makes a request to a resource located in another domain, the CDSSO mechanism transfers an encrypted user identity token from the first domain to the second domain. The identity information in this token indicates to the receiving domain that the user is successfully authenticated in the first domain. The identity does not contain password information. The receiving server uses this token to build credentials in its own cache for that user. The user is not forced to perform an additional login.

Parent topic: Cross-domain single signon concepts

Default and custom authentication tokensDefault and custom authentication tokensCDMFlibraryauthentication tokensCDSSO authenticationdefault and custom tokensCross-domain single signon solutions employ authentication tokens that convey an encoded version of the user identity to the destination server. The construction of these tokens by the initial server is called "token creation". The decoding and use of the token by the destination server is called "token consumption". WebSEAL uses built-in token create and token consume modules to allow default CDSSO operation.Alternatively, you can build custom token create and consume modules to meet the specific requirements of your network and Security Access Manager implementation. Complete information and API reference material for cross-domain external authentication can be found in the IBM Security Access Manager for Web: Web Security Developer Reference.Cross-domain single signon concepts

Default and custom authentication tokens

Cross-domain single signon solutions employ authentication tokens that convey an encoded version of the user identity to the destination server. The construction of these tokens by the initial server is called "token creation". The decoding and use of the token by the destination server is called "token consumption". WebSEAL uses built-in token create and token consume modules to allow default CDSSO operation.

Alternatively, you can build custom token create and consume modules to meet the specific requirements of your network and Security Access Manager implementation. Complete information and API reference material for cross-domain external authentication can be found in the IBM Security Access Manager for Web: Web Security Developer Reference.

Parent topic: Cross-domain single signon concepts

Extended user attributes and identity mappingExtended user attributes and identity mappingCDSSO authenticationextended user attributesidentity mappingThe CDSSO process is supported by the cross-domain mapping framework (sometimes referred to as CDMF) to allow the inclusion of extended attributes to further describe a user identity. CDMF is a programming interface that can handle extended user attributes during token creation and provide mapping services for the user identity during token consumption.Built-in default CDMF operation during CDSSO returns: "SUCCESS" and no extended attributes to the CDSSO token creation module"SUCCESS" and no identity mapping to the CDSSO token consumption module.You can use the cross-domain mapping framework C API to customize the handling of user attributes and the mapping of user identities. Complete information and API reference material for the cross-domain mapping framework can be found in the IBM Security Access Manager for Web: Web Security Developer Reference.Alternatively, attributes can be specified in the WebSEAL configuration file for transfer from the source server to the destination server.Cross-domain single signon concepts

Extended user attributes and identity mapping

The CDSSO process is supported by the cross-domain mapping framework (sometimes referred to as CDMF) to allow the inclusion of extended attributes to further describe a user identity. CDMF is a programming interface that can handle extended user attributes during token creation and provide mapping services for the user identity during token consumption.

Built-in default CDMF operation during CDSSO returns:

"SUCCESS" and no extended attributes to the CDSSO token creation module

"SUCCESS" and no identity mapping to the CDSSO token consumption module.

You can use the cross-domain mapping framework C API to customize the handling of user attributes and the mapping of user identities. Complete information and API reference material for the cross-domain mapping framework can be found in the IBM Security Access Manager for Web: Web Security Developer Reference.

Alternatively, attributes can be specified in the WebSEAL configuration file for transfer from the source server to the destination server.

Parent topic: Cross-domain single signon concepts

CDSSO process flow with attribute transfer and user mappingCDSSO process flow with attribute transfer and user mappingCDSSO authenticationprocess flowCDSSO process flowattribute transferuser mappingThe following process flow description is illustrated in Figure 1. Any user who wants to participate in multiple domains must have a valid user account in the initial domain and an identity that can be mapped into a valid account in each of the participating remote domains. A user cannot invoke the CDSSO functionality without initially authenticating to an initial secure domain (A) that contains the user's account.The user makes a request to access a resource in domain B using a custom link on a Web page located on the server websealA. The link is constructed using a special CDSSO management page expression: /pkmscdsso?destination-URL For example: http://websealA/pkmscdsso?https://websealB/resource.html The pkmscdsso management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.The request is first processed by the websealA server in domain A. The websealA server calls the ssocreate module to build an authentication token that contains the user's credentials, including the Security Access Manager identity (short name), the current domain ("A"), additional user information, and a time stamp. The token create module can obtain extended user attribute information that can be used by domain B during the user mapping process. Attribute information can come from two sources. First, the [cdsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries. Secondly, the CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes. Attributes from the CDMF library override any settings in the [cdcsso-token-attributes] stanza.WebSEAL triple-DES encrypts this token data with the symmetric key generated by the LMI. This key file is shared and specified in the [cdsso-peers] stanza of the WebSEAL configuration file on both domain A and domain B WebSEAL servers.The token contains a configurable time stamp (authtoken-lifetime) that defines the lifetime of the token. The time stamp, when properly configured, can prevent replay attacks.The token is placed in a redirected request to the destination server, using the URL contained in the pkmscdsso link. For example: http://websealB/resource.html?PD-ID=encoded-authn-token&PD-REFERER=websealA The PD-ID argument name in the query string is obtained from the cdsso-argument stanza entry of the WebSEAL configuration file. The ssocreate module provides the PD-REFERER argument with the name of the origin server (websealA) so that the destination server (websealB) accurately knows where the redirected request is from, without relying on the browser's Referer header information.The websealA server sends a redirect response for the resource on websealB containing the encrypted token back to the browser.The websealB server recognizes the request as one containing a CDSSO token (based on the value of the cdsso-argument stanza entry of its WebSEAL configuration file). The websealB server decodes and validates the token as coming from the referring domain. This process is performed by the "token consume" authentication module (ssoconsume).When constructing the attribute list for the new identity, the token consume module first processes the attributes according to the settings in the [cdsso-incoming-attributes] stanza of the WebSEAL configuration file. Then the module calls to the CDMF library, which performs the actual user mapping (cdmf_map_usr). The CDMF library passes the user's mapped identity, and any extended attribute information, back to the token consume module. The token consume module passes the identity to the WebSEAL server, which builds a credential.The websealB authorization service permits or denies access to protected objects based on the user's credential and the specific ACL and POP permissions associated with the requested objects. Cross-domain single signon process with CDMFCross-domain single signon process with CDMFCross-domain single signon concepts

CDSSO process flow with attribute transfer and user mapping

The following process flow description is illustrated in Figure 51..

Any user who wants to participate in multiple domains must have a valid user account in the initial domain and an identity that can be mapped into a valid account in each of the participating remote domains.

A user cannot invoke the CDSSO functionality without initially authenticating to an initial secure domain (A) that contains the user's account.

The user makes a request to access a resource in domain B using a custom link on a Web page located on the server websealA.

The link is constructed using a special CDSSO management page expression:

/pkmscdsso?destination-URL

For example:

http://websealA/pkmscdsso?https://websealB/resource.html

Note: The pkmscdsso management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

The request is first processed by the websealA server in domain A. The websealA server calls the ssocreate module to build an authentication token that contains the user's credentials, including the Security Access Manager identity (short name), the current domain ("A"), additional user information, and a time stamp.

The token create module can obtain extended user attribute information that can be used by domain B during the user mapping process.

Attribute information can come from two sources. First, the [cdsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries. Secondly, the CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes. Attributes from the CDMF library override any settings in the [cdcsso-token-attributes] stanza.

WebSEAL triple-DES encrypts this token data with the symmetric key generated by the LMI. This key file is shared and specified in the [cdsso-peers] stanza of the WebSEAL configuration file on both domain A and domain B WebSEAL servers.

The token contains a configurable time stamp (authtoken-lifetime) that defines the lifetime of the token. The time stamp, when properly configured, can prevent replay attacks.

The token is placed in a redirected request to the destination server, using the URL contained in the pkmscdsso link. For example:

http://websealB/resource.html?PD-ID=encoded-authn-token&PD-REFERER=websealA

The PD-ID argument name in the query string is obtained from the cdsso-argument stanza entry of the WebSEAL configuration file.

The ssocreate module provides the PD-REFERER argument with the name of the origin server (websealA) so that the destination server (websealB) accurately knows where the redirected request is from, without relying on the browser's Referer header information.

The websealA server sends a redirect response for the resource on websealB containing the encrypted token back to the browser.

The websealB server recognizes the request as one containing a CDSSO token (based on the value of the cdsso-argument stanza entry of its WebSEAL configuration file).

The websealB server decodes and validates the token as coming from the referring domain. This process is performed by the "token consume" authentication module (ssoconsume).

When constructing the attribute list for the new identity, the token consume module first processes the attributes according to the settings in the [cdsso-incoming-attributes] stanza of the WebSEAL configuration file. Then the module calls to the CDMF library, which performs the actual user mapping (cdmf_map_usr).

The CDMF library passes the user's mapped identity, and any extended attribute information, back to the token consume module. The token consume module passes the identity to the WebSEAL server, which builds a credential.

The websealB authorization service permits or denies access to protected objects based on the user's credential and the specific ACL and POP permissions associated with the requested objects.

Figure 51. Cross-domain single signon process with CDMF

Parent topic: Cross-domain single signon concepts

Configuration of cross-domain single signonConfiguration of cross-domain single signonCDSSO authenticationconfigurationcross-domain single signonconfigurationThis section contains the following introductory topics:The main configuration tasks are described in the following topics:Enabling and disabling CDSSO authenticationEncrypting the authentication token dataConfiguring the token time stampConfiguring the token label nameCreating the CDSSO HTML linkThe remaining topics provide supporting information:Single Signon SolutionsCDSSO configuration summaryCDSSO conditions and requirementsEnabling and disabling CDSSO authenticationEncrypting the authentication token dataConfiguring the token time stampConfiguring the token label nameCreating the CDSSO HTML linkHandling errors from CDMF during token creationProtection of the authentication tokenWhile the authentication token does not contain authentication information (such as user name and password), it does contain a user identity that is trusted within the receiving domain. The token itself must therefore be protected against theft and replay. Use of cross-domain single signon with virtual hosts

Configuration of cross-domain single signon

This section contains the following introductory topics:

The main configuration tasks are described in the following topics:

Enabling and disabling CDSSO authentication

Encrypting the authentication token data

Configuring the token time stamp

Configuring the token label name

Creating the CDSSO HTML link

The remaining topics provide supporting information:

CDSSO configuration summary

CDSSO conditions and requirements

Enabling and disabling CDSSO authentication

Encrypting the authentication token data

Configuring the token time stamp

Configuring the token label name

Creating the CDSSO HTML link

Handling errors from CDMF during token creation

Protection of the authentication token
While the authentication token does not contain authentication information (such as user name and password), it does contain a user identity that is trusted within the receiving domain. The token itself must therefore be protected against theft and replay.

Use of cross-domain single signon with virtual hosts

Parent topic: Single Signon Solutions

CDSSO configuration summaryCDSSO configuration summaryCDSSO authenticationconfigurationThe following configuration steps are explained in detail in the remaining sections of this CDSSO chapter division.Configuration of cross-domain single signonConfiguring CDSSO token create functionalityConfiguring CDSSO token consume functionality

CDSSO configuration summary

The following configuration steps are explained in detail in the remaining sections of this CDSSO chapter division.

Configuring CDSSO token create functionality

Configuring CDSSO token consume functionality

Parent topic: Configuration of cross-domain single signon

Configuring CDSSO token create functionalityConfiguring CDSSO token create functionalitytokenscreate functionalityconsume functionalitytoken consume functionalityCDSSOtoken create functionalitytoken consume functionalityconfigurationThe following procedures are appropriate for the initial WebSEAL server:Enable WebSEAL to generate CDSSO tokens (cdsso-create).Configure the built-in token creation module (sso-create).Create the key file used to encode and decode the token. Copy the key file to all appropriate participating servers ([cdsso-peers] stanza).Configure the token time stamp (authtoken-lifetime)Configure the token label (cdsso-argument).Create the CDSSO HTML link (/pkmscdsso).CDSSO configuration summary

Configuring CDSSO token create functionality

About this task

The following procedures are appropriate for the initial WebSEAL server:

Procedure

Enable WebSEAL to generate CDSSO tokens (cdsso-create).

Configure the built-in token creation module (sso-create).

Create the key file used to encode and decode the token. Copy the key file to all appropriate participating servers ([cdsso-peers] stanza).

Configure the token time stamp (authtoken-lifetime)

Configure the token label (cdsso-argument).

Create the CDSSO HTML link (/pkmscdsso).

Parent topic: CDSSO configuration summary

Configuring CDSSO token consume functionalityConfiguring CDSSO token consume functionalityCDSSOconfigurationThe following procedures are appropriate for the destination WebSEAL server:Enable WebSEAL to consume CDSSO tokens (cdsso-auth) for authentication.Configure the built-in token consumption module (sso-consume).Assign the appropriate key file ([cdsso-peers] stanza).Configure the token time stamp (authtoken-lifetime)Configure the token label (cdsso-argument).CDSSO configuration summary

Configuring CDSSO token consume functionality

About this task

The following procedures are appropriate for the destination WebSEAL server:

Procedure

Enable WebSEAL to consume CDSSO tokens (cdsso-auth) for authentication.

Configure the built-in token consumption module (sso-consume).

Assign the appropriate key file ([cdsso-peers] stanza).

Configure the token time stamp (authtoken-lifetime)

Configure the token label (cdsso-argument).

Parent topic: CDSSO configuration summary

CDSSO conditions and requirementsCDSSO conditions and requirementsCDSSO authenticationconfigurationrequirementsAll WebSEAL servers participating in CDSSO must have machine times synchronized. Authentication between servers can fail when machine time differences are too great.For CDSSO to function successfully, each participating WebSEAL server must reveal its fully qualified host name to the other participating servers in the cross-domain environment. If any host name does not include a domain, CDSSO cannot be enabled and an error message is logged in msg_webseald.log. When setting up a CDSSO environment, ensure that the machine-specific networking setup for each participating server is configured to identify the server with a fully qualified host name. Because some WebSEAL configuration requires machine host names to be described as fully qualified host names, you must ensure that your system and network can resolve machine names into fully qualified host names. For example, using fully qualified host names allows for many host names (IP addresses) per machine, as in the case of multiple WebSEAL instances.Do not reuse key pairs (used to encrypt and decrypt token data) generated for a specific CDSSO environment in any other CDSSO environments. Always generate unique key pairs for each CDSSO environment.Configuration of cross-domain single signonResolving machine namesCDSSO can be unintentionally disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names.

CDSSO conditions and requirements

All WebSEAL servers participating in CDSSO must have machine times synchronized. Authentication between servers can fail when machine time differences are too great.

For CDSSO to function successfully, each participating WebSEAL server must reveal its fully qualified host name to the other participating servers in the cross-domain environment. If any host name does not include a domain, CDSSO cannot be enabled and an error message is logged in msg_webseald.log. When setting up a CDSSO environment, ensure that the machine-specific networking setup for each participating server is configured to identify the server with a fully qualified host name.

Because some WebSEAL configuration requires machine host names to be described as fully qualified host names, you must ensure that your system and network can resolve machine names into fully qualified host names. For example, using fully qualified host names allows for many host names (IP addresses) per machine, as in the case of multiple WebSEAL instances.

Do not reuse key pairs (used to encrypt and decrypt token data) generated for a specific CDSSO environment in any other CDSSO environments. Always generate unique key pairs for each CDSSO environment.

Resolving machine names
CDSSO can be unintentionally disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names.

Parent topic: Configuration of cross-domain single signon

Resolving machine namesResolving machine namesResolving machine names in IBM Security Access Manager for WebCDSSO can be unintentionally disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names.machine namesresolving machine names The machine on which WebSEAL is located needs to be able to fully resolve an IP address. You can use the LMI to configure the DNS. The following general information is provided only as an example: Goal: Configure the machine to first look to DNS before checking the local /etc/hosts file for DNS information.Make sure that /etc/resolv.conf has valid DNS server entries.Edit /etc/nsswitch.conf so the hosts line indicates the correct order for checking DNS information:hosts dns filesAlternative goal: Configure the machine to first use local DNS information (/etc/hosts) before checking DNS. Configure the machine to check /etc/hosts before looking to DNS. Edit /etc/nsswitch.conf so the hosts line indicates the correct order for checking DNS information:hosts files dnsEnter appropriate DNS information in /etc/hosts:webseal1.fully.qualified.com 1.11.111.111webseal2.fully.qualified.com 2.22.222.222 CDSSO conditions and requirements

Resolving machine names

CDSSO can be unintentionally disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names.

About this task

The machine on which WebSEAL is located needs to be able to fully resolve an IP address. You can use the LMI to configure the DNS.

The following general information is provided only as an example:

Goal: Configure the machine to first look to DNS before checking the local /etc/hosts file for DNS information.

Procedure

Make sure that /etc/resolv.conf has valid DNS server entries.

Edit /etc/nsswitch.conf so the hosts line indicates the correct order for checking DNS information:
hosts dns files

Alternative goal: Configure the machine to first use local DNS information (/etc/hosts) before checking DNS.

Results

Configure the machine to check /etc/hosts before looking to DNS. Edit /etc/nsswitch.conf so the hosts line indicates the correct order for checking DNS information:
hosts files dns

Enter appropriate DNS information in /etc/hosts:
webseal1.fully.qualified.com 1.11.111.111
webseal2.fully.qualified.com 2.22.222.222

Parent topic: CDSSO conditions and requirements

Enabling and disabling CDSSO authentication Enabling and disabling CDSSO authentication cdsso-auth stanza entrycdsso-create stanza entry Configuration for the initial WebSEAL server: To enable the CDSSO token create module, configure the following stanza entry in the WebSEAL configuration file: [cdsso] cdsso-create = {none|http|https|both} The value both specifies both HTTP and HTTPS protocols. The value none disables the token create module. Configuration for the destination WebSEAL server: To enable the CDSSO token consume module, configure the following stanza entry in the WebSEAL configuration file: [cdsso] cdsso-auth = {none|http|https|both} The value both specifies both HTTP and HTTPS protocols. The value none disables the token consume module. You must stop and restart the WebSEAL server in order to activate changes to the WebSEAL configuration file. Complete all of the applicable configuration steps in this section and then restart WebSEAL.Configuration of cross-domain single signon

Enabling and disabling CDSSO authentication

About this task

Configuration for the initial WebSEAL server:

To enable the CDSSO token create module, configure the following stanza entry in the WebSEAL configuration file:

[cdsso]
cdsso-create = {none|http|https|both}

The value both specifies both HTTP and HTTPS protocols. The value none disables the token create module.

Configuration for the destination WebSEAL server:

To enable the CDSSO token consume module, configure the following stanza entry in the WebSEAL configuration file:

[cdsso]
cdsso-auth = {none|http|https|both}

The value both specifies both HTTP and HTTPS protocols. The value none disables the token consume module.

Note: You must stop and restart the WebSEAL server in order to activate changes to the WebSEAL configuration file. Complete all of the applicable configuration steps in this section and then restart WebSEAL.

Parent topic: Configuration of cross-domain single signon

Encrypting the authentication token data Encrypting the authentication token data cdsso_key_gencdsso-peers stanza WebSEAL must encrypt the authentication data placed in the token using a key generated through the LMI. You must "synchronize" this key by sharing the key file with each participating WebSEAL server in each participating domain. Each participating WebSEAL server in each domain needs to use the same key. Do not reuse key pairs (used to encrypt and decrypt token data) generated for a specific CDSSO environment in any other CDSSO environments. Always generate unique key pairs for each CDSSO environment. The generated key is a triple DES 192 bit key. You cannot specify a life span time on this key. The distribution of key files is not a part of the Security Access Manager CDSSO process. Specify this key file in the [cdsso-peers] stanza of the WebSEAL configuration file of the participating WebSEAL server in each domain. The format must include the fully qualified host name of the WebSEAL server and the name of the key file: [cdsso-peers] fully-qualified-host-name = keyfile-name Configuration example for server websealA in domain A: [cdsso-peers] websealB.domainB.com = A-B.key This setting specifies what key websealA uses to encrypt a token destined for websealB in domain B. Configuration example for server websealB in domain B: [cdsso-peers] websealA.domainA.com = A-B.key This setting specifies what key websealB (in domain B) uses to decrypt a token received from websealA in domain A. In this example, the A-B.key file is generated on one machine (websealA, for example) and manually (and securely) copied to the other machine (websealB, for example).Configuration of cross-domain single signon

Encrypting the authentication token data

About this task

WebSEAL must encrypt the authentication data placed in the token using a key generated through the LMI. You must "synchronize" this key by sharing the key file with each participating WebSEAL server in each participating domain. Each participating WebSEAL server in each domain needs to use the same key.

Note: Do not reuse key pairs (used to encrypt and decrypt token data) generated for a specific CDSSO environment in any other CDSSO environments. Always generate unique key pairs for each CDSSO environment.

The generated key is a triple DES 192 bit key. You cannot specify a life span time on this key.

Note: The distribution of key files is not a part of the Security Access Manager CDSSO process.

Specify this key file in the [cdsso-peers] stanza of the WebSEAL configuration file of the participating WebSEAL server in each domain. The format must include the fully qualified host name of the WebSEAL server and the name of the key file:

[cdsso-peers]
fully-qualified-host-name = keyfile-name

Configuration example for server websealA in domain A:

[cdsso-peers]
websealB.domainB.com = A-B.key

This setting specifies what key websealA uses to encrypt a token destined for websealB in domain B.

Configuration example for server websealB in domain B:

[cdsso-peers]
websealA.domainA.com = A-B.key

This setting specifies what key websealB (in domain B) uses to decrypt a token received from websealA in domain A.

In this example, the A-B.key file is generated on one machine (websealA, for example) and manually (and securely) copied to the other machine (websealB, for example).

Parent topic: Configuration of cross-domain single signon

Configuring the token time stamp Configuring the token time stamp authtoken-lifetime stanza entrytokenstime stamp configuration The token contains a configurable time stamp that defines the lifetime of the identity token. After the time stamp has expired, the token is considered not valid and is not used. The time stamp is used to help prevent replay attacks by setting a value short enough to prevent the token from being stolen and replayed within its lifetime. The authtoken-lifetime stanza entry, located in the [cdsso] stanza of the WebSEAL configuration file, sets the token lifetime value. The value is expressed in seconds. The default value is 180: [cdsso] authtoken-lifetime = 180 You must take into account any clock skew among the participating domains. Clock skew means that the system times differ on the relevant servers in each domain. When this difference approaches the value of authtoken-lifetime, the effective lifetime of the token is greatly reduced. When this difference exceeds the value of authtoken-lifetime, tokens from one domain cannot be valid for the other domain. You should adjust authtoken-lifetime accordingly. However, when clock skew requires that authtoken-lifetime be set to a large value, the risk of replay attacks increases. In this case, you should consider synchronizing the system time on the relevant servers in each domain. For more information, see authtoken-lifetimeUse the authtoken-lifetime stanza entry to specify the lifetime of the single sign-on authentication token..Configuration of cross-domain single signon

Configuring the token time stamp

About this task

The token contains a configurable time stamp that defines the lifetime of the identity token. After the time stamp has expired, the token is considered not valid and is not used. The time stamp is used to help prevent replay attacks by setting a value short enough to prevent the token from being stolen and replayed within its lifetime.

The authtoken-lifetime stanza entry, located in the [cdsso] stanza of the WebSEAL configuration file, sets the token lifetime value. The value is expressed in seconds. The default value is 180:

[cdsso]
authtoken-lifetime = 180

You must take into account any clock skew among the participating domains. Clock skew means that the system times differ on the relevant servers in each domain.

When this difference approaches the value of authtoken-lifetime, the effective lifetime of the token is greatly reduced. When this difference exceeds the value of authtoken-lifetime, tokens from one domain cannot be valid for the other domain.

You should adjust authtoken-lifetime accordingly. However, when clock skew requires that authtoken-lifetime be set to a large value, the risk of replay attacks increases. In this case, you should consider synchronizing the system time on the relevant servers in each domain.

For more information, see authtoken-lifetime.

Parent topic: Configuration of cross-domain single signon

Configuring the token label nameConfiguring the token label namecdsso-argument stanza entrytokenslabel nameconfiguration The authentication information used for a single signon transaction is placed in the redirected request as an encrypted token query string argument to the request. This token string requires a name, or label, to identify it. The label name uniquely identifies the request to the receiving WebSEAL server as a single signon request to be handled by the CDSSO token consume mechanism (module). You must configure this token label identically on both WebSEAL servers participating in the single signon functionality. To configure the token label, use the cdsso-argument stanza entry located in the [cdsso] stanza of the WebSEAL configuration file. For example (default): [cdsso] cdsso-argument = PD-ID For more information, see the cdsso-argumentUse the cdsso-argument stanza entry to specify the name of the query string argument that contains the cross-domain single sign-on token in the request..Configuration of cross-domain single signon

Configuring the token label name

About this task

The authentication information used for a single signon transaction is placed in the redirected request as an encrypted token query string argument to the request. This token string requires a name, or label, to identify it. The label name uniquely identifies the request to the receiving WebSEAL server as a single signon request to be handled by the CDSSO token consume mechanism (module).

You must configure this token label identically on both WebSEAL servers participating in the single signon functionality. To configure the token label, use the cdsso-argument stanza entry located in the [cdsso] stanza of the WebSEAL configuration file. For example (default):

[cdsso]
cdsso-argument = PD-ID

For more information, see the cdsso-argument.

Parent topic: Configuration of cross-domain single signon

Creating the CDSSO HTML link Creating the CDSSO HTML link pkmscdssoCDSSO HTML linkcreating The HTML link (located on the original WebSEAL server) that connects the user to a resource on the destination WebSEAL server must use a special CDSSO expression that directs the request to a CDSSO management page pkmscdsso: /pkmscdsso?destination-URL For example: http://websealA/pkmscdsso?https://websealB/resource.html The pkmscdsso management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it. The token create module creates and encodes an authentication token (containing the user's identity information) and includes this token in a redirect response to the resource using the destination URL information from the CDSSO link. For example: http://websealB/resource.html?PD-ID=encoded-authn-token&PD-REFERER=websealAConfiguration of cross-domain single signon

Creating the CDSSO HTML link

About this task

The HTML link (located on the original WebSEAL server) that connects the user to a resource on the destination WebSEAL server must use a special CDSSO expression that directs the request to a CDSSO management page pkmscdsso:

/pkmscdsso?destination-URL

For example:

http://websealA/pkmscdsso?https://websealB/resource.html

Note: The pkmscdsso management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

The token create module creates and encodes an authentication token (containing the user's identity information) and includes this token in a redirect response to the resource using the destination URL information from the CDSSO link. For example:

http://websealB/resource.html?PD-ID=encoded-authn-token&PD-REFERER=websealA

Parent topic: Configuration of cross-domain single signon

Handling errors from CDMF during token creationHandling errors from CDMF during token creationpropagate-cdmf-errors stanza entryCDMFerrorstoken creation During the creation of a CDSSO token, the ssocreate module calls the CDMF library to acquire any extended attributes to be included in the token. Extended attributes (that further describe the user) can be required for successful identity mapping of the user on the destination server. The CDMF API uses the cdmf_get_usr_attributes call to acquire extended attributes. It is possible for the cdmf_get_usr_attributes call to fail in obtaining the required information and return an error. In such a case, the subsequent behavior of the token creation process can be controlled through use of the propagate-cdmf-errors stanza entry located in the [cdsso] stanza. Values for this stanza entry include "yes" and "no". A "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error. A "yes" value forces the token creation process to end when CDMF fails to obtain attributes and returns an error. Example: [cdsso] propagate-cdmf-errors = no Configuration of cross-domain single signon

Handling errors from CDMF during token creation

About this task

During the creation of a CDSSO token, the ssocreate module calls the CDMF library to acquire any extended attributes to be included in the token. Extended attributes (that further describe the user) can be required for successful identity mapping of the user on the destination server. The CDMF API uses the cdmf_get_usr_attributes call to acquire extended attributes.

It is possible for the cdmf_get_usr_attributes call to fail in obtaining the required information and return an error. In such a case, the subsequent behavior of the token creation process can be controlled through use of the propagate-cdmf-errors stanza entry located in the [cdsso] stanza. Values for this stanza entry include "yes" and "no".

A "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error.

A "yes" value forces the token creation process to end when CDMF fails to obtain attributes and returns an error.

Example:

[cdsso]
propagate-cdmf-errors = no

Parent topic: Configuration of cross-domain single signon

Protection of the authentication tokenProtection of the authentication tokenProtection of the authentication token to secure communications between the WebSEAL servers and the usersWhile the authentication token does not contain authentication information (such as user name and password), it does contain a user identity that is trusted within the receiving domain. The token itself must therefore be protected against theft and replay. authenticationtoken protectionsecurityauthentication token protectionThe token is protected through the use of SSL to secure communications between the WebSEAL servers and the users. The token could conceivably be stolen from the user's browser history. The time stamp on the token should be short enough to make it unlikely that the token could be stolen and replayed during the lifetime of the token. However, a token that has expired with respect to its time stamp is still vulnerable to cryptographic attacks. If the key used to encrypt the token is discovered or otherwise compromised, malicious users could build their own tokens. Then, the tokens can be inserted into a pseudo-CDSSO flow. They would be indistinguishable from real authentication tokens to the WebSEAL servers participating in the CDSSO domain. For this reason, the keys used to protect the tokens must also be carefully managed and changed on a regular basis.Configuration of cross-domain single signon

Protection of the authentication token

While the authentication token does not contain authentication information (such as user name and password), it does contain a user identity that is trusted within the receiving domain. The token itself must therefore be protected against theft and replay.

The token is protected through the use of SSL to secure communications between the WebSEAL servers and the users. The token could conceivably be stolen from the user's browser history. The time stamp on the token should be short enough to make it unlikely that the token could be stolen and replayed during the lifetime of the token.

However, a token that has expired with respect to its time stamp is still vulnerable to cryptographic attacks. If the key used to encrypt the token is discovered or otherwise compromised, malicious users could build their own tokens.

Then, the tokens can be inserted into a pseudo-CDSSO flow. They would be indistinguishable from real authentication tokens to the WebSEAL servers participating in the CDSSO domain. For this reason, the keys used to protect the tokens must also be carefully managed and changed on a regular basis.

Parent topic: Configuration of cross-domain single signon

Use of cross-domain single signon with virtual hostsUse of cross-domain single signon with virtual hostsCDSSO authenticationcross-domain single signon with virtual hostscross-domain single signonvirtual hostsvirtual hostscross-domain single signonSee Cross-domain single sign-on with virtual hostsUse cross-domain single sign-on feature to do single sign-on between multiple virtual hosts on a single WebSEAL instance. .Configuration of cross-domain single signon

Use of cross-domain single signon with virtual hosts

See Cross-domain single sign-on with virtual hosts.

Parent topic: Configuration of cross-domain single signon

Extended attributes for CDSSOExtended attributes for CDSSOExtended attributes for CDSSO in IBM Security Access Manager for WebCDSSO can handle extended attributes in two ways.extended attributesCDSSOCDMFlibrarycdmf_get_usr_attributescdmf_get_usr_attributesTwo ways to handle extended attributes:The [cdsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries.The CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes.Attributes from the CDMF library override any settings in the [cdcsso-token-attributes] stanza.This section describes the use of the [cdsso-token-attributes] stanza and contains the following topics:Single Signon SolutionsExtended attributes to add to tokenExtended attributes to extract from a tokenIn the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to a cross-domain single sign-on token.

Extended attributes for CDSSO

CDSSO can handle extended attributes in two ways.

Two ways to handle extended attributes:

The [cdsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries.

The CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes.

Attributes from the CDMF library override any settings in the [cdcsso-token-attributes] stanza.

This section describes the use of the [cdsso-token-attributes] stanza and contains the following topics:

Extended attributes to add to token

Extended attributes to extract from a token
In the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to a cross-domain single sign-on token.

Parent topic: Single Signon Solutions

Extended attributes to add to tokenExtended attributes to add to tokencdsso-incoming-attributes stanzaIn the WebSEAL configuration file, you can specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that is added to an extended attribute list when a user credential is created. Extended attributes can be added by a number of authentication mechanisms, including custom authentication modules. The custom authentication modules can be used, for example, to obtain user information from a registry that is external to Security Access Manager.You can use this setting to customize the contents of the cross-domain single signon token. This feature enables you to tailor the token contents to match the needs of the destination domain. When you use this feature to add an attribute to a token, you must also configure the WebSEAL configuration file for the server in the destination domain. For the destination server, the [cdsso-incoming-attributes] stanza is used to specify the handling (extract or ignore) of each attribute.You can specify extended attributes by name, or you can declare a pattern that matches multiple attribute names. You can use standard Security Access Manager wildcard-matching characters. For a list of supported wildcard pattern matching characters, see Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters..Each entry is assigned the name of the domain for which the token is intended. You can include multiple entries specifying names or patterns for each domain.The syntax is:[cdsso-token-attributes] domain_name = pattern1 domain_name = pattern2 ... domain_name = patternN <default> = pattern1 <default> = pattern2 ... <default> = patternNThe <default> entry is optional. When WebSEAL does not find an entry that matches the domain name, WebSEAL looks for a <default> entry. If the configuration file contains a <default> entry, WebSEAL uses the assigned attribute patterns for the current domain. The string <default> is a keyword, and must be specified exactly as shown above, including the "<" and ">" characters.Example: You are creating a cross-domain single signon solution between two domains: example1.com and example2.com. Users log in to example1.com but can get redirected to example2.com during the user session. Your deployment includes a customized external authentication C API module that inserts information into each user credential. The information includes a fixed name attribute "job_category" and a variable number of attributes, each prefixed with the characters "my_ext_attr_". This information needs to be added to the cross-domain token. The configuration file entries would be:example2.com = job_category example2.com = my_ext_attr_*Extended attributes for CDSSOCDSSO can handle extended attributes in two ways.

Extended attributes to add to token

In the WebSEAL configuration file, you can specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that is added to an extended attribute list when a user credential is created. Extended attributes can be added by a number of authentication mechanisms, including custom authentication modules. The custom authentication modules can be used, for example, to obtain user information from a registry that is external to Security Access Manager.

You can use this setting to customize the contents of the cross-domain single signon token. This feature enables you to tailor the token contents to match the needs of the destination domain. When you use this feature to add an attribute to a token, you must also configure the WebSEAL configuration file for the server in the destination domain. For the destination server, the [cdsso-incoming-attributes] stanza is used to specify the handling (extract or ignore) of each attribute.

You can specify extended attributes by name, or you can declare a pattern that matches multiple attribute names. You can use standard Security Access Manager wildcard-matching characters. For a list of supported wildcard pattern matching characters, see Supported wildcard pattern matching characters.

Each entry is assigned the name of the domain for which the token is intended. You can include multiple entries specifying names or patterns for each domain.

The syntax is:

[cdsso-token-attributes]
domain_name = pattern1
domain_name = pattern2
...
domain_name = patternN
<default> = pattern1
<default> = pattern2
...
<default> = patternN

The <default> entry is optional. When WebSEAL does not find an entry that matches the domain name, WebSEAL looks for a <default> entry. If the configuration file contains a <default> entry, WebSEAL uses the assigned attribute patterns for the current domain. The string <default> is a keyword, and must be specified exactly as shown above, including the "<" and ">" characters.

Example: You are creating a cross-domain single signon solution between two domains: example1.com and example2.com. Users log in to example1.com but can get redirected to example2.com during the user session. Your deployment includes a customized external authentication C API module that inserts information into each user credential. The information includes a fixed name attribute "job_category" and a variable number of attributes, each prefixed with the characters "my_ext_attr_". This information needs to be added to the cross-domain token. The configuration file entries would be:

example2.com = job_category
example2.com = my_ext_attr_*

Parent topic: Extended attributes for CDSSO

Extended attributes to extract from a tokenExtended attributes to extract from a tokenExtended attributes to extract from a token in IBM Security Access Manager for WebIn the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to a cross-domain single sign-on token. cdsso-token-attributes stanzaWebSEAL configuration filecdsso-incoming-attributesextracting extended attributes from a tokenextended attributesCDSSOThe attributes can be either extracted or ignored. In some cases, you must extract the attributes because there is no way for a server in the destination domain to generate them. In other cases, you do not want to extract the tokens, because the server in the destination domain can use an independent process to gather the same extended attributes. For example, the attribute can reflect a timestamp that needs to reflect the system time on the destination server.In the token consume module, attributes that are extracted from the token are passed through to the cross-domain mapping framework module. The default cross-domain mapping framework module passes attributes directly through to the user credential. Customized cross-domain mapping framework modules can manipulate attributes as needed before passing them to the user credential.The syntax for the entries is as follows:[cdsso-incoming-attributes] attribute_pattern = {preserve|refresh}Typically, the names of the extended attributes (attribute_pattern) match the names of the attributes specified in the [cdsso-token-attributes] stanza of the configuration file for a WebSEAL server that generates the tokens. The value must be one of the following keywords:preserve Extract all attributes that match attribute_pattern.refresh Do not extract attributes that match attribute_pattern.Extended attributes in the token that do not match an entry in [cdsso-incoming-attributes] are preserved (extracted).The order of the entries in the stanza is important. The first entry that matches an attribute name is used. Other entries are ignored. For example, if you want to extract the attribute named my_special_attr1 but want to ignore all other entries with the prefix my_special_attr_, the stanza entries should be:[cdsso-incoming-attributes] my_special_attr1 = preserve my_special_attr_* = refreshUsing the examples shown above in Extended attributes to add to token, the entries in the WebSEAL configuration file for a server that operates in the example2.com domain could be:[cdsso-incoming-attributes] job_category = preserve my_cdas_attr_1 = preserve my_cdas_attr_* = refreshIn this example, the attributes job_category and my_cdas_attr_1 are extracted from the token. The remainder of the attributes with the prefix my_cdas_attr_ are ignored.Extended attributes for CDSSOCDSSO can handle extended attributes in two ways.

Extended attributes to extract from a token

In the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to a cross-domain single sign-on token.

The attributes can be either extracted or ignored. In some cases, you must extract the attributes because there is no way for a server in the destination domain to generate them. In other cases, you do not want to extract the tokens, because the server in the destination domain can use an independent process to gather the same extended attributes. For example, the attribute can reflect a timestamp that needs to reflect the system time on the destination server.

In the token consume module, attributes that are extracted from the token are passed through to the cross-domain mapping framework module. The default cross-domain mapping framework module passes attributes directly through to the user credential. Customized cross-domain mapping framework modules can manipulate attributes as needed before passing them to the user credential.

The syntax for the entries is as follows:

[cdsso-incoming-attributes]
attribute_pattern = {preserve|refresh}

Typically, the names of the extended attributes (attribute_pattern) match the names of the attributes specified in the [cdsso-token-attributes] stanza of the configuration file for a WebSEAL server that generates the tokens. The value must be one of the following keywords:

preserve

Extract all attributes that match attribute_pattern.

refresh

Do not extract attributes that match attribute_pattern.

Extended attributes in the token that do not match an entry in [cdsso-incoming-attributes] are preserved (extracted).

The order of the entries in the stanza is important. The first entry that matches an attribute name is used. Other entries are ignored. For example, if you want to extract the attribute named my_special_attr1 but want to ignore all other entries with the prefix my_special_attr_, the stanza entries should be:

[cdsso-incoming-attributes]
my_special_attr1 = preserve
my_special_attr_* = refresh

Using the examples shown above in Extended attributes to add to token, the entries in the WebSEAL configuration file for a server that operates in the example2.com domain could be:

[cdsso-incoming-attributes]
job_category = preserve
my_cdas_attr_1 = preserve
my_cdas_attr_* = refresh

In this example, the attributes job_category and my_cdas_attr_1 are extracted from the token. The remainder of the attributes with the prefix my_cdas_attr_ are ignored.

Parent topic: Extended attributes for CDSSO

Compatibility issues for CDSSOCompatibility issues for CDSSOCDSSOcompatibility issuescompatibility issuesCDSSOThis section contains the following topics: Single Signon SolutionsUTF-8 encoding of tokens for cross domain single signonToken compatibility with earlier versions of WebSEALSecurity Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.

Compatibility issues for CDSSO

This section contains the following topics:

UTF-8 encoding of tokens for cross domain single signon

Token compatibility with earlier versions of WebSEAL
Security Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.

Parent topic: Single Signon Solutions

UTF-8 encoding of tokens for cross domain single signonUTF-8 encoding of tokens for cross domain single signonCDSSO authenticationUTF-8UTF-8CDSSOuse-utf8 stanza entryCDSSO stanzaThe use of UTF-8 encoding for strings within tokens used for cross domain single signon is specified in the WebSEAL configuration file.[cdsso] use-utf8 = {true|false}The default value is true.When use-utf8 is set to "false", strings are encoded using the local code page. Use this value when implementing cross domain single signon with pre-version 5.1 WebSEAL servers. WebSEAL servers from versions prior to version 5.1 do not use UTF-8 encoding for tokens. When deploying WebSEAL in an environment that includes these older servers, configure WebSEAL to not use UTF-8 encoding. This setting is necessary for backward compatibility.Compatibility issues for CDSSO

UTF-8 encoding of tokens for cross domain single signon

The use of UTF-8 encoding for strings within tokens used for cross domain single signon is specified in the WebSEAL configuration file.

[cdsso]
use-utf8 = {true|false}

The default value is true.

When use-utf8 is set to "false", strings are encoded using the local code page. Use this value when implementing cross domain single signon with pre-version 5.1 WebSEAL servers. WebSEAL servers from versions prior to version 5.1 do not use UTF-8 encoding for tokens. When deploying WebSEAL in an environment that includes these older servers, configure WebSEAL to not use UTF-8 encoding. This setting is necessary for backward compatibility.

Parent topic: Compatibility issues for CDSSO

Token compatibility with earlier versions of WebSEALToken compatibility with earlier versions of WebSEALSecurity Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.pre-800-compatible-tokens stanza entrytoken compatibilityWebSEALtoken compatibilityIf you integrate CDSSO with servers that include versions of Security Access Manager earlier than version 8.0, you must enable the pre-800-compatible-tokens stanza entry in the [server] stanza of the WebSEAL configuration file. For example:pre-800-compatible-tokens = yesThe default setting for this stanza entry is no.Compatibility issues for CDSSO

Token compatibility with earlier versions of WebSEAL

Security Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.

If you integrate CDSSO with servers that include versions of Security Access Manager earlier than version 8.0, you must enable the pre-800-compatible-tokens stanza entry in the [server] stanza of the WebSEAL configuration file. For example:

pre-800-compatible-tokens = yes

The default setting for this stanza entry is no.

Parent topic: Compatibility issues for CDSSO

LTPA single signonLTPA single signonLTPAsingle signonsingle signonLTPAThis chapter discusses single sign-on access to peer security servers using an LTPA cookie for authentication.This section contains the following topics:Single Signon SolutionsLTPA single signon overview Single signon solutions across junctions describes how WebSphere provides single sign-on to junctioned servers using lightweight third-party authentication mechanism (LTPA). LTPA version 2 can also be used to provide single signon to peer servers. Configuring LTPA single signonTechnical notes for LTPA single signonThe following technical notes apply to LTPA single signon.

LTPA single signon

This chapter discusses single sign-on access to peer security servers using an LTPA cookie for authentication.

This section contains the following topics:

LTPA single signon overview
Single signon solutions across junctions describes how WebSphere® provides single sign-on to junctioned servers using lightweight third-party authentication mechanism (LTPA). LTPA version 2 can also be used to provide single signon to peer servers.

Configuring LTPA single signon

Technical notes for LTPA single signon
The following technical notes apply to LTPA single signon.

Parent topic: Single Signon Solutions

LTPA single signon overviewLTPA single signon overviewLTPA single sign-on overview in IBM Security Access Manager for Web Single signon solutions across junctions describes how WebSphere provides single sign-on to junctioned servers using lightweight third-party authentication mechanism (LTPA). LTPA version 2 can also be used to provide single signon to peer servers. LTPAsingle signonsingle signonoverviewLTPAWhen WebSEAL is positioned within an environment with other authentication enabled servers (e.g. DataPower) there are many potential login point. To achieve a single signon solution to one or more WebSphere or DataPower servers you can configure WebSEAL to accept and generate LTPA cookies.When a user makes a request for a WebSEAL protected resource, the user must first authenticate to WebSEAL. After successful authentication, WebSEAL generates an LTPA cookie on behalf of the user. The LTPA cookie, which serves as an authentication token, contains the user identity, key and token data, buffer length, and expiration information. This information is encrypted using a secret key shared between WebSEAL and the other LTPA-enabled servers.WebSEAL inserts the cookie in the HTTP response which is sent back to the client. The LTPA enabled server receives this cookie upon the next request, decrypts the cookie, and authenticates the user based on the identity information supplied in the cookie.WebSEAL only supports LTPA version 2 (LtpaToken2) cookies. LTPA single signon

LTPA single signon overview

Single signon solutions across junctions describes how WebSphere® provides single sign-on to junctioned servers using lightweight third-party authentication mechanism (LTPA). LTPA version 2 can also be used to provide single signon to peer servers.

When WebSEAL is positioned within an environment with other authentication enabled servers (e.g. DataPower®) there are many potential login point. To achieve a single signon solution to one or more WebSphere or DataPower servers you can configure WebSEAL to accept and generate LTPA cookies.

When a user makes a request for a WebSEAL protected resource, the user must first authenticate to WebSEAL. After successful authentication, WebSEAL generates an LTPA cookie on behalf of the user. The LTPA cookie, which serves as an authentication token, contains the user identity, key and token data, buffer length, and expiration information. This information is encrypted using a secret key shared between WebSEAL and the other LTPA-enabled servers.

WebSEAL inserts the cookie in the HTTP response which is sent back to the client. The LTPA enabled server receives this cookie upon the next request, decrypts the cookie, and authenticates the user based on the identity information supplied in the cookie.

WebSEAL only supports LTPA version 2 (LtpaToken2) cookies.

Parent topic: LTPA single signon

Configuring LTPA single signonConfiguring LTPA single signonsingle signonLTPALTPAsingle signon LTPA cookies are generated when LTPA authentication is enabled within WebSEAL. These cookies can then be used to achieve single signon to other LTPA-enabled authentication servers. For further details, see LTPA authentication. Single signon to other LTPA-enabled servers using an LTPA cookie requires the following configuration tasks:Enable the LTPA mechanism.Provide the name of the key file used to encrypt the identity information.Provide the password to this key file.Ensure the LTPA cookie name for the WebSEAL junction matches the WebSphere LTPA cookie name. The name of the WebSEAL cookie containing the LTPA token must match the configured name of the LTPA cookie in theWebSphere application. You can configure the jct-ltpa-cookie-name configuration item on a global or per junction basis. If you do not configure this cookie name, WebSEAL uses the same default values as WebSphere. See Specifying the cookie name for junctionsYou can configure the name of the cookie that contains the LTPA token for junctioned web servers..The first three configuration requirements are specified in the options to the standard junction and virtual host junction create commands. Use these options in addition to other required junction options when you create the junction between WebSEAL and the back-end WebSphere server. For example (entered as one line): pdadmin> server task default-webseald-webseal.ibm.com create ... -A -F "key.file" -Z "abcdefg" ...These options are further described in LTPA authentication.LTPA single signon

Configuring LTPA single signon

About this task

LTPA cookies are generated when LTPA authentication is enabled within WebSEAL. These cookies can then be used to achieve single signon to other LTPA-enabled authentication servers. For further details, see LTPA authentication.

Procedure

Single signon to other LTPA-enabled servers using an LTPA cookie requires the following configuration tasks:

Enable the LTPA mechanism.

Provide the name of the key file used to encrypt the identity information.

Provide the password to this key file.

Ensure the LTPA cookie name for the WebSEAL junction matches the WebSphere® LTPA cookie name.

The name of the WebSEAL cookie containing the LTPA token must match the configured name of the LTPA cookie in theWebSphere application. You can configure the jct-ltpa-cookie-name configuration item on a global or per junction basis. If you do not configure this cookie name, WebSEAL uses the same default values as WebSphere. See Specifying the cookie name for junctions.

The first three configuration requirements are specified in the options to the standard junction and virtual host junction create commands. Use these options in addition to other required junction options when you create the junction between WebSEAL and the back-end WebSphere server. For example (entered as one line):

pdadmin> server task default-webseald-webseal.ibm.com create ...
-A -F "key.file" -Z "abcdefg" ...

These options are further described in LTPA authentication.

Parent topic: LTPA single signon

Technical notes for LTPA single signonTechnical notes for LTPA single signonTechnical notes for LTPA single signon in IBM Security Access Manager for WebThe following technical notes apply to LTPA single signon.LTPAsingle signontechnical notestechnical notesLTPA single signon The key file contains information about a specific LTPA enabled authentication server. A single key file is used by WebSEAL when generating/authenticating LTPA cookies and as such all of the LTPA enabled server must share the same key file. If you add more than one server to the same junction point, all servers share the same key file.For single signon to succeed, WebSEAL and the LTPA enabled authentication server must share the same registry information. The WebSphere server is responsible for setting up LTPA and the creation of the shared secret key. WebSphere only supports LTPA version 2 cookies.WebSEAL does not use WebSphere LTPA Security Attribute Propagation to include additional attributes within the LTPA token.LTPA single signon

Technical notes for LTPA single signon

The following technical notes apply to LTPA single signon.

The key file contains information about a specific LTPA enabled authentication server. A single key file is used by WebSEAL when generating/authenticating LTPA cookies and as such all of the LTPA enabled server must share the same key file. If you add more than one server to the same junction point, all servers share the same key file.

For single signon to succeed, WebSEAL and the LTPA enabled authentication server must share the same registry information.

The WebSphere® server is responsible for setting up LTPA and the creation of the shared secret key.

WebSphere only supports LTPA version 2 cookies.

WebSEAL does not use WebSphere LTPA Security Attribute Propagation to include additional attributes within the LTPA token.

Parent topic: LTPA single signon

E-community single signonE-community single signonE-community single signon in IBM Security Access Manager for WebE-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.e-communitysingle signonsingle signone-communityThis chapter discusses the concepts and configuration steps required to implement an e-community single signon solution.Topic Index:Single Signon SolutionsE-community single signon conceptsConfiguration of e-community single sign-onExtended attributes for ECSSOCompatibility issues for ECSSO

E-community single signon

E-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.

This chapter discusses the concepts and configuration steps required to implement an e-community single signon solution.

Topic Index:

E-community single signon concepts

Configuration of e-community single sign-on

Extended attributes for ECSSO

Compatibility issues for ECSSO

Parent topic: Single Signon Solutions

E-community single signon conceptsE-community single signon conceptse-community authenticationauthenticatione-communitysingle signone-communitycross-domain single signone-communityThis section contains the following topics:E-community single signonE-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.Configuration of e-community single sign-onExtended attributes for ECSSOCompatibility issues for ECSSOE-community overviewE-community features and requirementsE-community process flowThe e-community cookieThe vouch-for request and replyThe vouch-for token

E-community single signon concepts

This section contains the following topics:

E-community overview

E-community features and requirements

E-community process flow

The e-community cookie

The vouch-for request and reply

The vouch-for token

Parent topic: E-community single signon

Related concepts:

Configuration of e-community single sign-on

Extended attributes for ECSSO

Related reference:

Compatibility issues for ECSSO

E-community overviewE-community overviewe-community authenticationoverviewmaster authentication servermaster authentication server (MAS)MAS (master authentication server)E-community single signon (sometimes referred to as ECSSO) is another implementation of cross-domain authentication in a Security Access Manager environment. The goal of cross-domain authentication is to allow users to access resources across multiple servers in multiple domains without having to perform multiple logins.An "e-community" is a group of distinct domains (Security Access Manager or DNS) that participate in a business relationship. These participating domains can be configured as part of one business (and perhaps using different DNS names for geographic reasons) or as disparate businesses with a shared relationship (for example, company headquarters, a life insurance company, and a financial management company). In either scenario, there is always one domain that is designated the "home" or "owner" domain. In the case of participating businesses, the home domain owns the business agreements that govern the e-community. In both scenarios, authentication information about the users who participate in the e-community (including the user names and passwords used for authentication) is maintained in the home domain. This arrangement allows a single point of reference for administration issues, such as help desk calls within the e-community that all refer to the home domain.Alternatively, you can use the Web Portal Manager to delegate the management of this information that participating domains have responsibility for the administration of their own users.The diagram below illustrates a sample e-community with two participating domains: domain A (dA.com) and domain B (dB.com). In this example, domain A represents the home or owner domain. Domain B is a participating, or "remote", domain. The e-community modelThe e-community modelThe home domain "owns" the users—that is, it controls the user's authentication information. Regardless of where a user makes a request for resources, the home domain is always where the user must authenticate. Authentication occurs against a master authentication server (sometimes referred to as the MAS)—a server (or set of replica servers) that is located in the home domain and configured to authenticate all users. The diagram represents the MAS as mas.dA.com. The duty of the MAS should be restricted to providing authentication services. The MAS should not contain resources that are available to users.After a user has successfully authenticated to the MAS, the MAS generates a "vouch-for" token. This token is passed back to the server where the user is making the request. The server treats this vouch-for token as proof that the user has successfully authenticated to the MAS and can participate in the e-community. The transfer of information between e-community domains is described in detail in the section E-community process flow.E-community single signon concepts

E-community overview

E-community single signon (sometimes referred to as ECSSO) is another implementation of cross-domain authentication in a Security Access Manager environment. The goal of cross-domain authentication is to allow users to access resources across multiple servers in multiple domains without having to perform multiple logins.

An "e-community" is a group of distinct domains (Security Access Manager or DNS) that participate in a business relationship. These participating domains can be configured as part of one business (and perhaps using different DNS names for geographic reasons) or as disparate businesses with a shared relationship (for example, company headquarters, a life insurance company, and a financial management company).

In either scenario, there is always one domain that is designated the "home" or "owner" domain. In the case of participating businesses, the home domain owns the business agreements that govern the e-community.

In both scenarios, authentication information about the users who participate in the e-community (including the user names and passwords used for authentication) is maintained in the home domain. This arrangement allows a single point of reference for administration issues, such as help desk calls within the e-community that all refer to the home domain.

Alternatively, you can use the Web Portal Manager to delegate the management of this information that participating domains have responsibility for the administration of their own users.

The diagram below illustrates a sample e-community with two participating domains: domain A (dA.com) and domain B (dB.com). In this example, domain A represents the home or owner domain. Domain B is a participating, or "remote", domain.

Figure 52. The e-community model

The home domain "owns" the users—that is, it controls the user's authentication information. Regardless of where a user makes a request for resources, the home domain is always where the user must authenticate.

Authentication occurs against a master authentication server (sometimes referred to as the MAS)—a server (or set of replica servers) that is located in the home domain and configured to authenticate all users. The diagram represents the MAS as mas.dA.com. The duty of the MAS should be restricted to providing authentication services. The MAS should not contain resources that are available to users.

After a user has successfully authenticated to the MAS, the MAS generates a "vouch-for" token. This token is passed back to the server where the user is making the request. The server treats this vouch-for token as proof that the user has successfully authenticated to the MAS and can participate in the e-community.

The transfer of information between e-community domains is described in detail in the section E-community process flow.

Parent topic: E-community single signon concepts

E-community features and requirements E-community features and requirements e-community authenticationfeaturesThe ECSSO model supports access using direct URLs (bookmarks) to resources. This feature contrasts with the cross-domain single signon (CDSSO) model, which relies on a specially configured pkmscdsso link (see Cross-domain single signon concepts).All users who participate in the e-community authenticate against a single master authentication server (MAS) located in the "home" domain.The e-community implementation allows for "local" authentication if the user does not have a valid account with the MAS (for example, users who belong to domain B but do not participate in the domain A-domain B e-community, where domain A is the "home" domain). Unless WebSEAL is configured to handle authentication failure at the MAS, a user who fails authentication with the MAS when requesting a resource in a non-MAS (but participating) domain is given the option to authenticate to the local server where the request is being made.The MAS (and eventually other selected servers in the remote domains) "vouches for" the user's authenticated identity.Domain-specific cookies are used to identify the server that can provide vouch-for services. Domain cookies allow servers in a remote domain to request vouch-for information locally. The encrypted contents of e-community cookies do not contain user identity or security information.Special tokens are used to pass encrypted "vouched for" user identity. The vouch-for token does not contain actual user authentication information. Integrity is provided by shared secret key (triple-DES). The token contains a timeout (lifetime) value to limit the duration of the token validity.WebSEAL provides a configuration option that, when enabled, permits only the MAS to generate "vouch-for" tokens.E-community single signon concepts

E-community features and requirements

The ECSSO model supports access using direct URLs (bookmarks) to resources. This feature contrasts with the cross-domain single signon (CDSSO) model, which relies on a specially configured pkmscdsso link (see Cross-domain single signon concepts).

All users who participate in the e-community authenticate against a single master authentication server (MAS) located in the "home" domain.

The e-community implementation allows for "local" authentication if the user does not have a valid account with the MAS (for example, users who belong to domain B but do not participate in the domain A-domain B e-community, where domain A is the "home" domain).

Unless WebSEAL is configured to handle authentication failure at the MAS, a user who fails authentication with the MAS when requesting a resource in a non-MAS (but participating) domain is given the option to authenticate to the local server where the request is being made.

The MAS (and eventually other selected servers in the remote domains) "vouches for" the user's authenticated identity.

Domain-specific cookies are used to identify the server that can provide vouch-for services. Domain cookies allow servers in a remote domain to request vouch-for information locally. The encrypted contents of e-community cookies do not contain user identity or security information.

Special tokens are used to pass encrypted "vouched for" user identity. The vouch-for token does not contain actual user authentication information. Integrity is provided by shared secret key (triple-DES). The token contains a timeout (lifetime) value to limit the duration of the token validity.

WebSEAL provides a configuration option that, when enabled, permits only the MAS to generate "vouch-for" tokens.

Parent topic: E-community single signon concepts

E-community process flow E-community process flow e-community authenticationprocess flowprocess flowe-community authenticationAn e-community consists of a master authentication WebSEAL server (MAS) and additional WebSEAL servers located in the home domain and remote domains. The MAS can exist as a single instance of a WebSEAL server, or a set of WebSEAL replicas located behind a load balancer (where the load balancer is identified as the MAS). All participating local and remote WebSEAL servers need to be configured to use the home domain MAS for initial client authentication. This configuration is a hard requirement for servers in the home domain, and a soft requirement for servers in remote domains. For example, some servers in remote domains can be configured to handle their own authentication. These servers, and the resources they protect, can operate independently of the e-community, even if they are located in a participating e-community domain.The e-community implementation is based on a vouch-for system. Typically, when a user requests a resource from a WebSEAL server where the user has not established a valid session, WebSEAL prompts the user for authentication information. In an e-community configuration, the WebSEAL server identifies a vouch-for server and requests verification from this vouch-for server that the user has authenticated.The vouch-for server has valid credential information for that user. For the user's first request, the vouch-for server is always the MAS. The MAS continues to serve as the vouch-for server for resources located in the home domain. As the user continues with resource requests across the e-community, an individual server in each remote domain can build its own credential for the user (based on user identity information from the MAS) and assume the role of vouch-for server for resources in its domain.The verification requested of the vouch-for server takes the form of a vouch-for token. The vouch-for server creates the token and returns it to the requesting WebSEAL server. The user identity information in the token is encrypted. The token contains a lifetime limit.Upon receipt of the vouch-for token, the requesting server builds credentials and a local session for that user. The user can now access the requested resource based on normal authorization controls. The user benefits from not having to log in again—a goal of the e-community model.Refer to the following diagram as you follow the e-community process flow in the remainder of this section. The process flow describes two possible FIRST access scenarios (1 and 2). These are followed by two possible NEXT access scenarios (3 and 4) which follow immediately after 2 or 3. Scenario 5 occurs any time after the initial access. Example configuration for e-community process flowExample configuration for e-community process flow"Vouch-for" Servers The MAS is always used to authenticate a user accessing any part of the e-community for the first time. The MAS should perform only as an authentication server and not as a resource provider. The MAS should not be configured to act as a master authentication server and, simultaneously, to protect resources. This recommendation addresses performance concerns and is not a security requirement.The MAS is always the vouch-for server for the home domain (domain A in this example).A domain-specific e-community cookie is used to identify the vouch-for server for all other servers within a given domain. The vouch-for server is the first server in a domain that requests a vouch-for token from the MAS. The vouch-for server provides vouch-for information for the user within the domain. Subsequent requests for vouch-for services in a given remote domain can be made locally by this server, rather than accessing the out-of-domain MAS. In the home domain, the e-community cookie identifies the MAS as the vouch-for server.(1) FIRST e-Community Local (Domain A) Access: WebSEAL 1 User requests a resource protected by WebSEAL 1 (within the same domain as MAS). The browser contains no e-community cookie for this domain. WebSEAL 1 has no cached credentials for the user.WebSEAL 1 configuration has e-community authentication enabled and specifies the location of the MAS. WebSEAL 1 redirects the browser to a special vouch-for URL on the MAS.The MAS receives the vouch-for request and, failing to find credentials for that user, prompts the user to login.After successful login, the MAS builds a credential for the user, stores it in the cache, and redirects the browser back to the originally requested URL on WebSEAL 1 with an encrypted vouch-for token. In addition, a domain A-specific e-community cookie is placed on the browser to identify the vouch-for server for this domain (in this case, the MAS). The token create module can obtain extended user attribute information that can be used by the destination server during the user mapping process. Attribute information can come from two sources. First, the [ecsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries. Secondly, the CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes. Attributes from the CDMF library override any settings in the [ecsso-token-attributes] stanza.If the login attempt is unsuccessful, the MAS returns a vouch-for token that indicates a failure status. This token is constructed to be indistinguishable from a success status vouch-for token. The requesting server reacts to a failure status token as if the user had failed local authentication.WebSEAL 1 decrypts the token. Identity mapping should not be required within the same domain. If identity mapping is required, WebSEAL 1 can use the cross-domain mapping framework (CDMF).If an attribute list for the new identity is constructed, the token consume module first processes the attributes according to the settings in the [ecsso-incoming-attributes] stanza of the WebSEAL configuration file. Then the module calls to the CDMF library, which performs the actual user mapping (cdmf_map_usr). The CDMF library passes the user's mapped identity, and any extended attribute information, back to the token consume module. The token consume module passes the identity to the WebSEAL server, which builds a credential.The authorization service permits or denies the request based on the user's credential and the specific ACL and POP permissions associated with the requested resource.(2) FIRST e-Community Remote (Domain B) Access: WebSEAL 3 User requests a resource protected by WebSEAL 3 (remote domain B). The browser contains no e-community cookie for this domain. WebSEAL 3 has no cached credentials for the user.WebSEAL 3 configuration has e-community authentication enabled and specifies the location of the MAS. WebSEAL 3 redirects the browser to a special vouch-for URL on the MAS.The MAS receives the vouch-for request and, failing to find credentials for that user, prompts the user to login.After successful login, the MAS builds a credential for the user, stores it in the cache, and redirects the browser back to the originally requested URL on WebSEAL 3 with an encrypted vouch-for token. In addition, a domain A-specific e-community cookie is placed on the browser to identify the vouch-for server for this domain (in this case, the MAS). The token create module can obtain extended user attribute information that can be used by the destination server during the user mapping process. Attribute information can come from two sources. First, the [ecsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries. Secondly, the CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes. Attributes from the CDMF library override any settings in the [ecsso-token-attributes] stanza.If the login attempt is unsuccessful, the MAS returns a vouch-for token that indicates a failure status. This token is constructed to be indistinguishable from a success status vouch-for token. If the user fails authentication at the MAS, then the user is prompted for a local authentication at WebSEAL 3. If the user's account exists on this server, authentication then succeeds. WebSEAL 3 decrypts the token.If an attribute list for the new identity is constructed, the token consume module first processes the attributes according to the settings in the [ecsso-incoming-attributes] stanza of the WebSEAL configuration file. Then the module calls to the CDMF library, which performs the actual user mapping (cdmf_map_usr). The CDMF library passes the user's mapped identity, and any extended attribute information, back to the token consume module. The token consume module passes the identity to the WebSEAL server, which builds a credential for the user.WebSEAL 3 creates and sets a second e-community cookie (valid for domain B) on the browser, identifying WebSEAL 3 as the vouch-for server for domain B.The authorization service permits or denies the request.(3) NEXT e-Community Local (Domain A) Access: WebSEAL 2 User requests a resource protected by WebSEAL 2 (within the same domain as MAS). The browser contains a domain A e-community cookie identifying the MAS as the vouch-for server. WebSEAL 2 receives this cookie. WebSEAL 2 has no cached credentials for the user.WebSEAL 2 configuration has e-community authentication enabled and specifies the location of the MAS. The presence of the domain A e-community cookie overrides the WebSEAL 2 configuration for the MAS location. The cookie provides WebSEAL 2 with the identity of the vouch-for server. (If scenario 2 occurred first, there would also be a domain B cookie maintained on the browser that would not be sent to a domain A server.)WebSEAL 2 redirects the browser to a special vouch-for URL on the domain A vouch-for server identified in the cookie (in this case the MAS, because WebSEAL 2 is in domain A).The MAS receives the vouch-for request and finds credentials for that user in the cache (this occurred in scenario 1 and 2).The MAS redirects the browser back to the originally requested URL on WebSEAL 2 with an encrypted vouch-for token. (See scenario 1 and 2 for a description of extended attribute handling.)WebSEAL 2 decrypts the token and builds its own credential for the user.The authorization service permits or denies the request.(4) NEXT e-Community Remote (Domain B) Access: WebSEAL 4 User requests a resource protected by WebSEAL 4 (remote domain B). If scenario 2 occurred first, the browser contains a domain B e-community cookie identifying WebSEAL 3 as the vouch-for server. WebSEAL 4 has no cached credentials for the user.WebSEAL 4 configuration has e-community authentication enabled and specifies the location of the MAS. The presence of a domain B e-community cookie overrides the WebSEAL 4 configuration for the MAS location. The cookie provides WebSEAL 4 with the identity of the vouch-for server. (If scenario 1 occurred first, there would only be a domain A cookie maintained on the browser that would not be sent to a domain B server. The configured MAS location would be used instead. WebSEAL 4 would then become the vouch-for server for domain B.)If scenario 2 occurred first, WebSEAL 4 redirects the browser to a special vouch-for URL on the domain B vouch-for server identified in the domain B cookie (in this case WebSEAL 3).WebSEAL 3 receives the vouch-for request and finds credentials for that user in the cache (this occurred in scenario 2).WebSEAL 3 redirects the browser back to the originally requested URL on WebSEAL 4 with an encrypted vouch-for token. (See scenario 1 and 2 for a description of extended attribute handling.)WebSEAL 4 decrypts the token and builds its own credential for the user.The authorization service permits or denies the request.(5) ANOTHER e-Community Local (Domain A) Access: WebSEAL 2 User connects to WebSEAL 2 (domain A) with a request. If scenario 3 occurred, WebSEAL 2 has cached credentials for the user.The authorization service permits or denies the request.Logout from the e-Community If the user logs out by closing the browser, all SSL sessions and all e-community cookies are cleared.If the user logs out using the /pkmslogout page, the SSL session and e-community cookie for that domain are cleared. E-community single signon concepts

E-community process flow

An e-community consists of a master authentication WebSEAL server (MAS) and additional WebSEAL servers located in the home domain and remote domains. The MAS can exist as a single instance of a WebSEAL server, or a set of WebSEAL replicas located behind a load balancer (where the load balancer is identified as the MAS).

All participating local and remote WebSEAL servers need to be configured to use the home domain MAS for initial client authentication. This configuration is a hard requirement for servers in the home domain, and a soft requirement for servers in remote domains. For example, some servers in remote domains can be configured to handle their own authentication. These servers, and the resources they protect, can operate independently of the e-community, even if they are located in a participating e-community domain.

The e-community implementation is based on a vouch-for system. Typically, when a user requests a resource from a WebSEAL server where the user has not established a valid session, WebSEAL prompts the user for authentication information. In an e-community configuration, the WebSEAL server identifies a vouch-for server and requests verification from this vouch-for server that the user has authenticated.

The vouch-for server has valid credential information for that user. For the user's first request, the vouch-for server is always the MAS. The MAS continues to serve as the vouch-for server for resources located in the home domain. As the user continues with resource requests across the e-community, an individual server in each remote domain can build its own credential for the user (based on user identity information from the MAS) and assume the role of vouch-for server for resources in its domain.

The verification requested of the vouch-for server takes the form of a vouch-for token. The vouch-for server creates the token and returns it to the requesting WebSEAL server. The user identity information in the token is encrypted. The token contains a lifetime limit.

Upon receipt of the vouch-for token, the requesting server builds credentials and a local session for that user. The user can now access the requested resource based on normal authorization controls. The user benefits from not having to log in again—a goal of the e-community model.

Refer to the following diagram as you follow the e-community process flow in the remainder of this section. The process flow describes two possible FIRST access scenarios (1 and 2). These are followed by two possible NEXT access scenarios (3 and 4) which follow immediately after 2 or 3. Scenario 5 occurs any time after the initial access.

Figure 53. Example configuration for e-community process flow

"Vouch-for" Servers

The MAS is always used to authenticate a user accessing any part of the e-community for the first time.

The MAS should perform only as an authentication server and not as a resource provider. The MAS should not be configured to act as a master authentication server and, simultaneously, to protect resources. This recommendation addresses performance concerns and is not a security requirement.

The MAS is always the vouch-for server for the home domain (domain A in this example).

A domain-specific e-community cookie is used to identify the vouch-for server for all other servers within a given domain. The vouch-for server is the first server in a domain that requests a vouch-for token from the MAS. The vouch-for server provides vouch-for information for the user within the domain. Subsequent requests for vouch-for services in a given remote domain can be made locally by this server, rather than accessing the out-of-domain MAS. In the home domain, the e-community cookie identifies the MAS as the vouch-for server.

(1) FIRST e-Community Local (Domain A) Access: WebSEAL 1

User requests a resource protected by WebSEAL 1 (within the same domain as MAS). The browser contains no e-community cookie for this domain. WebSEAL 1 has no cached credentials for the user.

WebSEAL 1 configuration has e-community authentication enabled and specifies the location of the MAS. WebSEAL 1 redirects the browser to a special vouch-for URL on the MAS.

The MAS receives the vouch-for request and, failing to find credentials for that user, prompts the user to login.

After successful login, the MAS builds a credential for the user, stores it in the cache, and redirects the browser back to the originally requested URL on WebSEAL 1 with an encrypted vouch-for token. In addition, a domain A-specific e-community cookie is placed on the browser to identify the vouch-for server for this domain (in this case, the MAS).

The token create module can obtain extended user attribute information that can be used by the destination server during the user mapping process.

Attribute information can come from two sources. First, the [ecsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries. Secondly, the CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes. Attributes from the CDMF library override any settings in the [ecsso-token-attributes] stanza.

If the login attempt is unsuccessful, the MAS returns a vouch-for token that indicates a failure status. This token is constructed to be indistinguishable from a success status vouch-for token. The requesting server reacts to a failure status token as if the user had failed local authentication.

WebSEAL 1 decrypts the token.

Note: Identity mapping should not be required within the same domain. If identity mapping is required, WebSEAL 1 can use the cross-domain mapping framework (CDMF).

If an attribute list for the new identity is constructed, the token consume module first processes the attributes according to the settings in the [ecsso-incoming-attributes] stanza of the WebSEAL configuration file. Then the module calls to the CDMF library, which performs the actual user mapping (cdmf_map_usr).

The CDMF library passes the user's mapped identity, and any extended attribute information, back to the token consume module. The token consume module passes the identity to the WebSEAL server, which builds a credential.

The authorization service permits or denies the request based on the user's credential and the specific ACL and POP permissions associated with the requested resource.

(2) FIRST e-Community Remote (Domain B) Access: WebSEAL 3

User requests a resource protected by WebSEAL 3 (remote domain B). The browser contains no e-community cookie for this domain. WebSEAL 3 has no cached credentials for the user.

WebSEAL 3 configuration has e-community authentication enabled and specifies the location of the MAS. WebSEAL 3 redirects the browser to a special vouch-for URL on the MAS.

The MAS receives the vouch-for request and, failing to find credentials for that user, prompts the user to login.

After successful login, the MAS builds a credential for the user, stores it in the cache, and redirects the browser back to the originally requested URL on WebSEAL 3 with an encrypted vouch-for token. In addition, a domain A-specific e-community cookie is placed on the browser to identify the vouch-for server for this domain (in this case, the MAS).

The token create module can obtain extended user attribute information that can be used by the destination server during the user mapping process.

Attribute information can come from two sources. First, the [ecsso-token-attributes] stanza of the WebSEAL configuration file is checked for configured stanza entries. Secondly, the CDMF library is called (cdmf_get_usr_attributes) to obtain additional attributes. Attributes from the CDMF library override any settings in the [ecsso-token-attributes] stanza.

If the login attempt is unsuccessful, the MAS returns a vouch-for token that indicates a failure status. This token is constructed to be indistinguishable from a success status vouch-for token. If the user fails authentication at the MAS, then the user is prompted for a local authentication at WebSEAL 3. If the user's account exists on this server, authentication then succeeds.

WebSEAL 3 decrypts the token.

If an attribute list for the new identity is constructed, the token consume module first processes the attributes according to the settings in the [ecsso-incoming-attributes] stanza of the WebSEAL configuration file. Then the module calls to the CDMF library, which performs the actual user mapping (cdmf_map_usr).

The CDMF library passes the user's mapped identity, and any extended attribute information, back to the token consume module. The token consume module passes the identity to the WebSEAL server, which builds a credential for the user.

WebSEAL 3 creates and sets a second e-community cookie (valid for domain B) on the browser, identifying WebSEAL 3 as the vouch-for server for domain B.

The authorization service permits or denies the request.

(3) NEXT e-Community Local (Domain A) Access: WebSEAL 2

User requests a resource protected by WebSEAL 2 (within the same domain as MAS). The browser contains a domain A e-community cookie identifying the MAS as the vouch-for server. WebSEAL 2 receives this cookie. WebSEAL 2 has no cached credentials for the user.

WebSEAL 2 configuration has e-community authentication enabled and specifies the location of the MAS. The presence of the domain A e-community cookie overrides the WebSEAL 2 configuration for the MAS location. The cookie provides WebSEAL 2 with the identity of the vouch-for server. (If scenario 2 occurred first, there would also be a domain B cookie maintained on the browser that would not be sent to a domain A server.)

WebSEAL 2 redirects the browser to a special vouch-for URL on the domain A vouch-for server identified in the cookie (in this case the MAS, because WebSEAL 2 is in domain A).

The MAS receives the vouch-for request and finds credentials for that user in the cache (this occurred in scenario 1 and 2).

The MAS redirects the browser back to the originally requested URL on WebSEAL 2 with an encrypted vouch-for token. (See scenario 1 and 2 for a description of extended attribute handling.)

WebSEAL 2 decrypts the token and builds its own credential for the user.

The authorization service permits or denies the request.

(4) NEXT e-Community Remote (Domain B) Access: WebSEAL 4

User requests a resource protected by WebSEAL 4 (remote domain B). If scenario 2 occurred first, the browser contains a domain B e-community cookie identifying WebSEAL 3 as the vouch-for server. WebSEAL 4 has no cached credentials for the user.

WebSEAL 4 configuration has e-community authentication enabled and specifies the location of the MAS. The presence of a domain B e-community cookie overrides the WebSEAL 4 configuration for the MAS location. The cookie provides WebSEAL 4 with the identity of the vouch-for server. (If scenario 1 occurred first, there would only be a domain A cookie maintained on the browser that would not be sent to a domain B server. The configured MAS location would be used instead. WebSEAL 4 would then become the vouch-for server for domain B.)

If scenario 2 occurred first, WebSEAL 4 redirects the browser to a special vouch-for URL on the domain B vouch-for server identified in the domain B cookie (in this case WebSEAL 3).

WebSEAL 3 receives the vouch-for request and finds credentials for that user in the cache (this occurred in scenario 2).

WebSEAL 3 redirects the browser back to the originally requested URL on WebSEAL 4 with an encrypted vouch-for token. (See scenario 1 and 2 for a description of extended attribute handling.)

WebSEAL 4 decrypts the token and builds its own credential for the user.

The authorization service permits or denies the request.

(5) ANOTHER e-Community Local (Domain A) Access: WebSEAL 2

User connects to WebSEAL 2 (domain A) with a request. If scenario 3 occurred, WebSEAL 2 has cached credentials for the user.

The authorization service permits or denies the request.

Logout from the e-Community

If the user logs out by closing the browser, all SSL sessions and all e-community cookies are cleared.

If the user logs out using the /pkmslogout page, the SSL session and e-community cookie for that domain are cleared.

Parent topic: E-community single signon concepts

The e-community cookie The e-community cookie e-community cookiee-community authenticatione-community cookieThe e-community cookie is a domain-specific cookie set by one WebSEAL server, is stored in the memory of the user's browser, and is transmitted to other WebSEAL servers (in the same domain) in subsequent requests.The domain-specific cookie contains the name of the vouch-for server, the e-community identity, a location (URL) of the vouch-for server and functionality, and a lifetime (timeout) value. The cookie contains no user or security information.The e-community cookie allows servers in participating domains to request vouch-for information locally. The e-community cookie for the domain where the MAS is located plays a less significant role.The cookie has a lifetime value that is set in the WebSEAL configuration file. This lifetime value specifies how long a remote server is able to provide vouch-for information for the user. When the cookie lifetime has expired, the user must be redirected to the MAS for authentication.If the value of the disable-ec-cookie option in the [e-community-sso] stanza is yes, then the MAS is the only server permitted to generate vouch-for tokens.The cookie is cleared from memory when the browser is closed. If the user logs out of a specific domain, the e-community cookie is overwritten as empty. This action effectively removes it from the browser.E-community single signon concepts

The e-community cookie

The e-community cookie is a domain-specific cookie set by one WebSEAL server, is stored in the memory of the user's browser, and is transmitted to other WebSEAL servers (in the same domain) in subsequent requests.

The domain-specific cookie contains the name of the vouch-for server, the e-community identity, a location (URL) of the vouch-for server and functionality, and a lifetime (timeout) value. The cookie contains no user or security information.

The e-community cookie allows servers in participating domains to request vouch-for information locally. The e-community cookie for the domain where the MAS is located plays a less significant role.

The cookie has a lifetime value that is set in the WebSEAL configuration file. This lifetime value specifies how long a remote server is able to provide vouch-for information for the user. When the cookie lifetime has expired, the user must be redirected to the MAS for authentication.

If the value of the disable-ec-cookie option in the [e-community-sso] stanza is yes, then the MAS is the only server permitted to generate vouch-for tokens.

The cookie is cleared from memory when the browser is closed. If the user logs out of a specific domain, the e-community cookie is overwritten as empty. This action effectively removes it from the browser.

Parent topic: E-community single signon concepts

The vouch-for request and reply The vouch-for request and reply vouch-forrequestreplypkmsvouchfore-community authenticationvouch-for request and replyThe e-community vouch-for operation requires dedicated functionality accessed through two specially constructed URLs: the vouch-for request and the vouch-for reply. E-community single signon conceptsThe vouch-for requestThe vouch-for request is triggered when a user requests a resource from a target server (configured for e-community) that contains no credential information for that user. The vouch-for replyThe vouch-for reply is the response from the vouch-for server to the target server.

The vouch-for request and reply

The e-community vouch-for operation requires dedicated functionality accessed through two specially constructed URLs: the vouch-for request and the vouch-for reply.

The vouch-for request
The vouch-for request is triggered when a user requests a resource from a target server (configured for e-community) that contains no credential information for that user.

The vouch-for reply
The vouch-for reply is the response from the vouch-for server to the target server.

Parent topic: E-community single signon concepts

The vouch-for requestThe vouch-for requestThe vouch-for request in IBM Security Access Manager for WebThe vouch-for request is triggered when a user requests a resource from a target server (configured for e-community) that contains no credential information for that user. vouch-forrequestrequestsvouch-forThe server sends a redirect to the vouch-for server, either the MAS or a delegated vouch-for server identified in an e-community cookie.The vouch-for request contains the following information: https://vouch-for-server/pkmsvouchfor?ecommunity-name&target-URLThe receiving server checks the ecommunity-name to validate the e-community identity. The receiving server uses the target-URL in the vouch-for reply to redirect the browser back to the originally requested page.The pkmsvouchfor vouch-for URL is configurable.For example: https://mas.dA.com/pkmsvouchfor?companyABC&https://ws5.dB.com/index.htmlThe pkmsvouchfor management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.The vouch-for request and reply

The vouch-for request

The vouch-for request is triggered when a user requests a resource from a target server (configured for e-community) that contains no credential information for that user.

The server sends a redirect to the vouch-for server, either the MAS or a delegated vouch-for server identified in an e-community cookie.

The vouch-for request contains the following information:

https://vouch-for-server/pkmsvouchfor?ecommunity-name&target-URL

The receiving server checks the ecommunity-name to validate the e-community identity. The receiving server uses the target-URL in the vouch-for reply to redirect the browser back to the originally requested page.

The pkmsvouchfor vouch-for URL is configurable.

For example:

https://mas.dA.com/pkmsvouchfor?companyABC&https://ws5.dB.com/index.html

Note: The pkmsvouchfor management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

Parent topic: The vouch-for request and reply

The vouch-for replyThe vouch-for replyThe vouch-for reply in IBM Security Access Manager for WebThe vouch-for reply is the response from the vouch-for server to the target server. vouch-forreplyrepliesvouch-forThe vouch-for server is either the MAS or a delegated vouch-for server in a domain remote that is from the MAS domain.The vouch-for reply contains the following information: https://target-URL?PD-VFHOST=vouch-for-server&PD-VF=encrypted-tokenThe PD-VFHOST label identifies the server that performed the vouch-for operation. The receiving (target) server uses this information to select the correct key required to decrypt the vouch-for token. The PD-VF label identifies the encrypted token in the vouch-for reply URL.For example:https://w5.dB.com/index.html?PD-VFHOST=mas.dA.com&PD-VF=3qhe9fjkp...ge56wgbThe vouch-for request and reply

The vouch-for reply

The vouch-for reply is the response from the vouch-for server to the target server.

The vouch-for server is either the MAS or a delegated vouch-for server in a domain remote that is from the MAS domain.

The vouch-for reply contains the following information:

https://target-URL?PD-VFHOST=vouch-for-server&PD-VF=encrypted-token

The PD-VFHOST label identifies the server that performed the vouch-for operation. The receiving (target) server uses this information to select the correct key required to decrypt the vouch-for token. The PD-VF label identifies the encrypted token in the vouch-for reply URL.

For example:

https://w5.dB.com/index.html?PD-VFHOST=mas.dA.com&PD-VF=3qhe9fjkp...ge56wgb

Parent topic: The vouch-for request and reply

The vouch-for token The vouch-for token e-community authenticationvouch-for tokenvouch-fortokenoverviewtokensvouch-forIn order to achieve cross-domain single signon, some user identity information must be transmitted between servers. This sensitive information is handled using a redirect that includes the identity information encrypted as part of the URL. This encrypted data is called a vouch-for token.The token contains the vouch-for success or failure status, the user's identity (if successful), the fully qualified name of the server that created the token, the e-community identity, and a creation time value.The holder of a valid vouch-for token can use this token to establish a session (and set of credentials) with a server without explicitly authenticating to that server.The token is encrypted using a shared triple-DES secret key so that its authenticity can be verified.Encrypted token information is not stored on the browser.The token is passed only once. The receiving server uses this information to build user credentials in its own cache. The server uses these credentials for future requests by that user during the same session.The token has a lifetime (timeout) value that is set in the WebSEAL configuration file. This value can be very short (seconds) to reduce the risk of a replay attack.E-community single signon concepts

The vouch-for token

In order to achieve cross-domain single signon, some user identity information must be transmitted between servers. This sensitive information is handled using a redirect that includes the identity information encrypted as part of the URL. This encrypted data is called a vouch-for token.

The token contains the vouch-for success or failure status, the user's identity (if successful), the fully qualified name of the server that created the token, the e-community identity, and a creation time value.

The holder of a valid vouch-for token can use this token to establish a session (and set of credentials) with a server without explicitly authenticating to that server.

The token is encrypted using a shared triple-DES secret key so that its authenticity can be verified.

Encrypted token information is not stored on the browser.

The token is passed only once. The receiving server uses this information to build user credentials in its own cache. The server uses these credentials for future requests by that user during the same session.

The token has a lifetime (timeout) value that is set in the WebSEAL configuration file. This value can be very short (seconds) to reduce the risk of a replay attack.

Parent topic: E-community single signon concepts

Configuration of e-community single sign-onConfiguration of e-community single sign-onConfiguration of e-community single sign-on in IBM Security Access Manager for Webe-communitysingle signonsingle signone-communityThis section contains the following introductory topics:The main configuration tasks are described in the following topics:The remaining topics provide supporting information:E-community single signonE-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.E-community single signon conceptsExtended attributes for ECSSOCompatibility issues for ECSSOE-community configuration summaryE-community conditions and requirementsEnabling and disabling e-community authenticationSpecifying an e-community nameEncrypting the vouch-for tokenConfiguring the vouch-for token label nameSpecifying the master authentication server (MAS)Specifying the vouch-for URLConfigure token and ec-cookie lifetime valuesHandling errors from CDMF during token creationEnabling unauthenticated accessLimiting the ability to generate vouch-for tokensConfiguration of the behavior for authentication failureLogout using pkmslogout-nomasUse of e-community with virtual hosts

Configuration of e-community single sign-on

This section contains the following introductory topics:

The main configuration tasks are described in the following topics:

The remaining topics provide supporting information:

E-community configuration summary

E-community conditions and requirements

Enabling and disabling e-community authentication

Specifying an e-community name

Encrypting the vouch-for token

Configuring the vouch-for token label name

Specifying the master authentication server (MAS)

Specifying the vouch-for URL

Configure token and ec-cookie lifetime values

Handling errors from CDMF during token creation

Enabling unauthenticated access

Limiting the ability to generate vouch-for tokens

Configuration of the behavior for authentication failure

Logout using pkmslogout-nomas

Use of e-community with virtual hosts

Parent topic: E-community single signon

Related concepts:

E-community single signon concepts

Extended attributes for ECSSO

Related reference:

Compatibility issues for ECSSO

E-community configuration summaryE-community configuration summarye-community authenticationconfiguration summarye-community configurationsummaryAn e-community is configured under the following conditions and guidelines:The vouch-for server (the MAS or a delegated vouch-for server) always has the token create responsibility.The receiving server (where the requested resource is located) always has the token consume responsibility.A delegated vouch-for server (for all domains remote from the MAS domain) must have both token create and token consume capabilities.The following configuration steps are explained in detail in the remaining sections of this e-community chapter division:Configuration of e-community single sign-onConfiguring token create functionality on the vouch-for serverConfiguring token consume functionality on the receiving server

E-community configuration summary

An e-community is configured under the following conditions and guidelines:

The vouch-for server (the MAS or a delegated vouch-for server) always has the token create responsibility.

The receiving server (where the requested resource is located) always has the token consume responsibility.

A delegated vouch-for server (for all domains remote from the MAS domain) must have both token create and token consume capabilities.

The following configuration steps are explained in detail in the remaining sections of this e-community chapter division:

Configuring token create functionality on the vouch-for server

Configuring token consume functionality on the receiving server

Parent topic: Configuration of e-community single sign-on

Configuring token create functionality on the vouch-for serverConfiguring token create functionality on the vouch-for servertokensvouch-forvouch-forserver The following configuration steps are explained in detail in the remaining sections of this e-community chapter division.Enable e-community authentication to process single signon requests by communication type (e-community-sso-auth).Specify the unifying name of the e-community for all participating servers (e-community-name).Configure the built-in single signon token create module (sso-create).Create the key file used to encode and decode the vouch-for token. Copy the key file to all appropriate participating servers ([e-community-domain-keys] stanza).Configure the token label used in the vouch-for reply (vf-argument).Specify if this server is the MAS or not the MAS (is-master-authn-server).Specify the vouch-for URL used in the vouch-for request (vf-url).Configure token and e-community cookie lifetime values (vf-token-lifetime and ec-cookie-lifetime).E-community configuration summary

Configuring token create functionality on the vouch-for server

About this task

The following configuration steps are explained in detail in the remaining sections of this e-community chapter division.

Procedure

Enable e-community authentication to process single signon requests by communication type (e-community-sso-auth).

Specify the unifying name of the e-community for all participating servers (e-community-name).

Configure the built-in single signon token create module (sso-create).

Create the key file used to encode and decode the vouch-for token. Copy the key file to all appropriate participating servers ([e-community-domain-keys] stanza).

Configure the token label used in the vouch-for reply (vf-argument).

Specify if this server is the MAS or not the MAS (is-master-authn-server).

Specify the vouch-for URL used in the vouch-for request (vf-url).

Configure token and e-community cookie lifetime values (vf-token-lifetime and ec-cookie-lifetime).

Parent topic: E-community configuration summary

Configuring token consume functionality on the receiving serverConfiguring token consume functionality on the receiving serverConfiguring token consume functionality on the receiving server IBM Security Access Manager for Webtoken consumereceiving server The following configuration steps are explained in detail in the remaining sections of this e-community chapter division.Enable e-community authentication to process single signon requests by communication type (e-community-sso-auth).Specify the unifying name of the e-community for all participating servers (e-community-name).Configure the built-in single signon token consume module (sso-consume).Assign the appropriate key file ([e-community-domain-keys] stanza).Configure the token label used in the vouch-for reply (vf-argument).Specify that this server is not the MAS (is-master-authn-server).Specify the vouch-for URL used in the vouch-for request (vf-url).Configure token and e-community cookie lifetime values (vf-token-lifetime and ec-cookie-lifetime).E-community configuration summary

Configuring token consume functionality on the receiving server

About this task

The following configuration steps are explained in detail in the remaining sections of this e-community chapter division.

Procedure

Enable e-community authentication to process single signon requests by communication type (e-community-sso-auth).

Specify the unifying name of the e-community for all participating servers (e-community-name).

Configure the built-in single signon token consume module (sso-consume).

Assign the appropriate key file ([e-community-domain-keys] stanza).

Configure the token label used in the vouch-for reply (vf-argument).

Specify that this server is not the MAS (is-master-authn-server).

Specify the vouch-for URL used in the vouch-for request (vf-url).

Configure token and e-community cookie lifetime values (vf-token-lifetime and ec-cookie-lifetime).

Parent topic: E-community configuration summary

E-community conditions and requirements E-community conditions and requirements e-community authenticationconditions and requirements The e-community implementation requires a consistent configuration across all WebSEAL servers in all domains participating in the e-community.For e-community to function successfully, each participating WebSEAL server must reveal its fully qualified host name to the other participating servers in the cross-domain environment. If any host name does not include a domain, e-community cannot be enabled and an error message is logged in msg_webseald.log. When setting up an e-community environment, ensure that the machine-specific networking setup for each participating server is configured to identify the server with a fully qualified host name. All WebSEAL servers participating in e-community must have machine times synchronized. Authentication between servers can fail when machine time differences are too great.The e-community implementation is supported on both HTTP and HTTPS.Individual e-community domains manage their own user identities and associated privileges. You can use the Cross-domain Mapping Function (CDMF) API to map a user from a remote domain to a valid user in the local domain. If the e-community domains share global user identities, those users could be distinguished by different passwords in the different domains. For example, a user "abc" can exist in both domain A and domain B, using different passwords for each domain.Configuration for e-community is set in the WebSEAL configuration file of each participating WebSEAL server.If the originally requested URL is not redirected back to the browser from the MAS (or vouch-for server), there could be a problem with page caching if the browser is Microsoft Internet Explorer. If this is the case, configure the browser to always check for newer versions of stored pages: Tools > Internet Options > General > Temporary Internet Files > SettingsDo not configure the MAS server on the same interface (IP address) of another participating WebSEAL instance.Because some WebSEAL configuration requires machine host names to be described as fully qualified host names, you must ensure that your system and network can resolve machine names into fully qualified host names. For example, using fully qualified host names allows for many host names (IP addresses) per machine, as in the case of multiple WebSEAL instances.Configuration of e-community single sign-onResolving machine names in an e-community environmentE-community can be disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names.

E-community conditions and requirements

The e-community implementation requires a consistent configuration across all WebSEAL servers in all domains participating in the e-community.

For e-community to function successfully, each participating WebSEAL server must reveal its fully qualified host name to the other participating servers in the cross-domain environment. If any host name does not include a domain, e-community cannot be enabled and an error message is logged in msg_webseald.log. When setting up an e-community environment, ensure that the machine-specific networking setup for each participating server is configured to identify the server with a fully qualified host name.

All WebSEAL servers participating in e-community must have machine times synchronized. Authentication between servers can fail when machine time differences are too great.

The e-community implementation is supported on both HTTP and HTTPS.

Individual e-community domains manage their own user identities and associated privileges. You can use the Cross-domain Mapping Function (CDMF) API to map a user from a remote domain to a valid user in the local domain.

If the e-community domains share global user identities, those users could be distinguished by different passwords in the different domains. For example, a user "abc" can exist in both domain A and domain B, using different passwords for each domain.

Configuration for e-community is set in the WebSEAL configuration file of each participating WebSEAL server.

If the originally requested URL is not redirected back to the browser from the MAS (or vouch-for server), there could be a problem with page caching if the browser is Microsoft Internet Explorer. If this is the case, configure the browser to always check for newer versions of stored pages:

Tools > Internet Options > General > Temporary Internet Files > Settings

Do not configure the MAS server on the same interface (IP address) of another participating WebSEAL instance.

Because some WebSEAL configuration requires machine host names to be described as fully qualified host names, you must ensure that your system and network can resolve machine names into fully qualified host names. For example, using fully qualified host names allows for many host names (IP addresses) per machine, as in the case of multiple WebSEAL instances.

Resolving machine names in an e-community environment
E-community can be disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names.

Parent topic: Configuration of e-community single sign-on

Resolving machine names in an e-community environmentResolving machine names in an e-community environmentResolving machine names in an e-community environment in IBM Security Access Manager for WebE-community can be disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names. e-communityresolving machine namesresolving machine namesmachine names The machine on which WebSEAL is located needs to be able to fully resolve an IP address. Because this functionality is very operating system-specific, it is not the role of this document to provide instructions. Always consult your system administrator if you are not sure your system has the proper capabilities. E-community conditions and requirements

Resolving machine names in an e-community environment

E-community can be disabled upon WebSEAL startup because the machine itself is not adequately configured to resolve machine names.

About this task

The machine on which WebSEAL is located needs to be able to fully resolve an IP address. Because this functionality is very operating system-specific, it is not the role of this document to provide instructions. Always consult your system administrator if you are not sure your system has the proper capabilities.

Parent topic: E-community conditions and requirements

Enabling and disabling e-community authentication Enabling and disabling e-community authentication e-community authenticationenablingdisabling The e-community-sso-auth stanza entry, located in the [e-community-sso] stanza of the WebSEAL configuration file, enables and disables the e-community authentication method, and processes single signon requests by communication type. To enable the e-community authentication method, enter "http", "https", or "both".The values "http", "https", and "both" specify the type of communication used by e-community participants. To disable the e-community authentication method, enter "none".The value "none" disables e-community for that server. The default setting is "none".For example: [e-community-sso] e-community-sso-auth = httpsYou must stop and restart the WebSEAL server in order to activate changes to the WebSEAL configuration file. Complete all of the applicable configuration steps in this section and then restart WebSEAL.Configuration of e-community single sign-on

Enabling and disabling e-community authentication

About this task

The e-community-sso-auth stanza entry, located in the [e-community-sso] stanza of the WebSEAL configuration file, enables and disables the e-community authentication method, and processes single signon requests by communication type.

Procedure

To enable the e-community authentication method, enter "http", "https", or "both".

The values "http", "https", and "both" specify the type of communication used by e-community participants.

To disable the e-community authentication method, enter "none".

The value "none" disables e-community for that server. The default setting is "none".

For example:

[e-community-sso]
e-community-sso-auth = https

Note: You must stop and restart the WebSEAL server in order to activate changes to the WebSEAL configuration file. Complete all of the applicable configuration steps in this section and then restart WebSEAL.

Parent topic: Configuration of e-community single sign-on

Specifying an e-community nameSpecifying an e-community namee-community-name stanza entrye-community namespecifyingspecifying an e-community name The e-community-name stanza entry identifies the unifying name of the e-community for all participating servers in all participating domains. For example: [e-community-sso] e-community-name = companyABC The e-community-name value must be the same for all WebSEAL servers in all domains that are participating in the e-community.Configuration of e-community single sign-on

Specifying an e-community name

About this task

The e-community-name stanza entry identifies the unifying name of the e-community for all participating servers in all participating domains. For example:

[e-community-sso]
e-community-name = companyABC

The e-community-name value must be the same for all WebSEAL servers in all domains that are participating in the e-community.

Parent topic: Configuration of e-community single sign-on

Encrypting the vouch-for token Encrypting the vouch-for token cdsso_key_gene-community-domain-keys stanzae-community authenticationencrypting vouch-for tokenvouch-fortokenencryption The distribution of key files is not a part of the Security Access Manager e-community process. You must manually and securely copy keys to each participating server. The name of the key files used to secure tokens sent between servers participating in the e-community is specified in the [e-community-domain-keys] stanza. [e-community-domain-keys] domain-name = keyfile-name domain-name = keyfile-nameConfiguration of e-community single sign-onE-community domain keysThe key files required for encrypting and decrypting the tokens exchanged among the servers participating in the e-community is specified in the [e-community-domain-keys] stanza.

Encrypting the vouch-for token

About this task

Note: The distribution of key files is not a part of the Security Access Manager e-community process. You must manually and securely copy keys to each participating server.

The name of the key files used to secure tokens sent between servers participating in the e-community is specified in the [e-community-domain-keys] stanza.

[e-community-domain-keys]
domain-name = keyfile-name
domain-name = keyfile-name

E-community domain keys
The key files required for encrypting and decrypting the tokens exchanged among the servers participating in the e-community is specified in the [e-community-domain-keys] stanza.

Parent topic: Configuration of e-community single sign-on

E-community domain keys E-community domain keys The key files required for encrypting and decrypting the tokens exchanged among the servers participating in the e-community is specified in the [e-community-domain-keys] stanza.e-community-domain-keys stanzae-community authenticationdomain keysYou must specify fully qualified domain name for each server and the name of the associated key file. The following example provides the MAS (domain A) with key files for communicating with two remote domains (dB and dC) and a key for communicating with other servers in domain A: [e-community-domain-keys] dA.com = key.fileA-A dB.com = key.fileA-B dC.com = key.fileA-CIn this example, key.fileA-A identifies the key file used between all of the servers in domainA. key.fileA-B identifies the key file used between domain A and domain B. key.fileA-C identifies the key file used between domain A and domain C.Each remote server needs to have a copy of the appropriate key file used by the MAS. To exchange tokens with the MAS (domain A), all servers in domain B require copies of key.fileA-B: [e-community-domain-keys] dA.com = key.fileA-BTo exchange tokens with the MAS (domain A), all servers in domain C require copies of key.fileA-C: [e-community-domain-keys] dA.com = key.fileA-CAny servers in domain A which use authentication services provided by the MAS must have a copy of key.fileA-A: [e-community-domain-keys] dA.com = key.fileA-AIn this example, key.fileB-B identifies the key file used between all of the servers in domainB. Also, key.fileC-C identifies the key file used between all of the servers in domainC[e-community-domain-keys] dB.com = key.fileB-B dC.com = key.fileC-CEncrypting the vouch-for token

E-community domain keys

The key files required for encrypting and decrypting the tokens exchanged among the servers participating in the e-community is specified in the [e-community-domain-keys] stanza.

You must specify fully qualified domain name for each server and the name of the associated key file.

The following example provides the MAS (domain A) with key files for communicating with two remote domains (dB and dC) and a key for communicating with other servers in domain A:

[e-community-domain-keys]
dA.com = key.fileA-A
dB.com = key.fileA-B
dC.com = key.fileA-C

In this example, key.fileA-A identifies the key file used between all of the servers in domainA.

key.fileA-B identifies the key file used between domain A and domain B.

key.fileA-C identifies the key file used between domain A and domain C.

Each remote server needs to have a copy of the appropriate key file used by the MAS. To exchange tokens with the MAS (domain A), all servers in domain B require copies of key.fileA-B:

[e-community-domain-keys]
dA.com = key.fileA-B

To exchange tokens with the MAS (domain A), all servers in domain C require copies of key.fileA-C:

[e-community-domain-keys]
dA.com = key.fileA-C

Any servers in domain A which use authentication services provided by the MAS must have a copy of key.fileA-A:

[e-community-domain-keys]
dA.com = key.fileA-A

In this example, key.fileB-B identifies the key file used between all of the servers in domainB. Also, key.fileC-C identifies the key file used between all of the servers in domainC

[e-community-domain-keys]
dB.com = key.fileB-B
dC.com = key.fileC-C

Parent topic: Encrypting the vouch-for token

Configuring the vouch-for token label nameConfiguring the vouch-for token label namevf-argument stanza entryvouch-fortokenlabel nametokenslabel namevouch-for The authentication information used for a single signon transaction is placed in the redirected request as an encrypted token query string argument to the request. This token string requires a name, or label, to identify it. The label name uniquely identifies the request to the receiving WebSEAL server as a single signon request to be handled by the single signon token consume module. You must configure this token label on both WebSEAL servers participating in the single signon functionality. For more information, see the Web Reverse Proxy Stanza Reference topics..To configure the token label, use the vf-argument stanza entry located in the [e-community-sso] stanza of the WebSEAL configuration file. For example (default): [e-community-sso] vf-argument = PD-VFConfiguration of e-community single sign-on

Configuring the vouch-for token label name

About this task

The authentication information used for a single signon transaction is placed in the redirected request as an encrypted token query string argument to the request. This token string requires a name, or label, to identify it. The label name uniquely identifies the request to the receiving WebSEAL server as a single signon request to be handled by the single signon token consume module.

You must configure this token label on both WebSEAL servers participating in the single signon functionality.

For more information, see the Web Reverse Proxy Stanza Reference topics..

Procedure

To configure the token label, use the vf-argument stanza entry located in the [e-community-sso] stanza of the WebSEAL configuration file. For example (default):

[e-community-sso]
vf-argument = PD-VF

Parent topic: Configuration of e-community single sign-on

Specifying the master authentication server (MAS)Specifying the master authentication server (MAS)master authentication server (MAS)is-master-authn-server stanza entrymaster-authn-server stanza entrymaster-http-port stanza entrymaster-https-port stanza entry You must specify which server machine in the e-community is to function as the master authentication server (MAS). You must also specify if a server machine is not the MAS. is-master-authn-server Use the is-master-authn-server stanza entry to specify whether a server is the MAS or not. Values include "yes" or "no". For example: [e-community-sso] is-master-authn-server = yes Multiple WebSEALs can be configured to act as master authentication servers and then placed behind a load balancer. In this scenario, the load balancer is "recognized" as the MAS by all other WebSEAL servers in the e-community. If the server you are configuring is not the MAS, use the master-authn-server to specify to this server the location of the MAS. master-authn-server If the is-master-authn-server stanza entry is set to "no", this stanza entry must be uncommented and specified. The stanza entry identifies the fully qualified domain name of the MAS. For example: [e-community-sso] master-authn-server = mas.dA.com Additionally, you can specify the HTTP and HTTPS listening ports used by the MAS if these port values are other than the default (port 80 for HTTP and port 443 for HTTPS). master-http-port If e-community-sso-auth enables HTTP e-community authentication and the master authentication server listens for HTTP requests on a port other than the standard HTTP port (port 80), the master-http-port stanza entry identifies the non-standard port. This stanza entry is ignored if this server is the master authentication server. By default, this stanza entry is disabled. [e-community-sso] master-http-port = port-number master-https-port If e-community-sso-auth enables HTTPS e-community authentication and the master authentication server listens for HTTPS requests on a port other than the standard HTTPS port (port 443), the master-http-port stanza entry identifies the non-standard port. This stanza entry is ignored if this server is the master authentication server. By default, this stanza entry is disabled. [e-community-sso] master-https-port = port-numberConfiguration of e-community single sign-on

Specifying the master authentication server (MAS)

About this task

You must specify which server machine in the e-community is to function as the master authentication server (MAS). You must also specify if a server machine is not the MAS.

is-master-authn-server

Use the is-master-authn-server stanza entry to specify whether a server is the MAS or not. Values include "yes" or "no".

For example:

[e-community-sso]
is-master-authn-server = yes

Multiple WebSEALs can be configured to act as master authentication servers and then placed behind a load balancer. In this scenario, the load balancer is "recognized" as the MAS by all other WebSEAL servers in the e-community.

If the server you are configuring is not the MAS, use the master-authn-server to specify to this server the location of the MAS.

master-authn-server

If the is-master-authn-server stanza entry is set to "no", this stanza entry must be uncommented and specified. The stanza entry identifies the fully qualified domain name of the MAS.

For example:

[e-community-sso]
master-authn-server = mas.dA.com

Additionally, you can specify the HTTP and HTTPS listening ports used by the MAS if these port values are other than the default (port 80 for HTTP and port 443 for HTTPS).

master-http-port

If e-community-sso-auth enables HTTP e-community authentication and the master authentication server listens for HTTP requests on a port other than the standard HTTP port (port 80), the master-http-port stanza entry identifies the non-standard port. This stanza entry is ignored if this server is the master authentication server. By default, this stanza entry is disabled.

[e-community-sso]
master-http-port = port-number

master-https-port

If e-community-sso-auth enables HTTPS e-community authentication and the master authentication server listens for HTTPS requests on a port other than the standard HTTPS port (port 443), the master-http-port stanza entry identifies the non-standard port. This stanza entry is ignored if this server is the master authentication server. By default, this stanza entry is disabled.

[e-community-sso]
master-https-port = port-number

Parent topic: Configuration of e-community single sign-on

Specifying the vouch-for URLSpecifying the vouch-for URLvouch-forURLURLvouch-forvf-url stanza entrypkmsvouchfor vf-url The vf-url stanza entry specifies the vouch-for URL. The value must begin with a forward-slash (/). The default value is /pkmsvouchfor. For example: [e-community-sso] vf-url = /pkmsvouchfor You can also express an extended URL: vf-url = /ecommA/pkmsvouchfor The extended URL is used when the client is communicating with a MAS that is not a WebSEAL server. This use of vf-url enables the client to specify access to a MAS with a specialized authentication library, such as a customized token consumption module. The pkmsvouchfor management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.Configuration of e-community single sign-on

Specifying the vouch-for URL

About this task

vf-url

The vf-url stanza entry specifies the vouch-for URL. The value must begin with a forward-slash (/). The default value is /pkmsvouchfor.

For example:

[e-community-sso]
vf-url = /pkmsvouchfor

You can also express an extended URL:

vf-url = /ecommA/pkmsvouchfor

The extended URL is used when the client is communicating with a MAS that is not a WebSEAL server. This use of vf-url enables the client to specify access to a MAS with a specialized authentication library, such as a customized token consumption module.

Note: The pkmsvouchfor management page is a management command to the WebSEAL server. It is not represented in the object space and you cannot attach policies to it.

Parent topic: Configuration of e-community single sign-on

Configure token and ec-cookie lifetime values Configure token and ec-cookie lifetime values tokenslifetime valuesec-cookie lifetime valuesconfigurationvf-token-lifetime stanza entryec-cookie-lifetime stanza entry vf-token-lifetime The vf-token-lifetime stanza entry sets the lifetime timeout value (in seconds) of the vouch-for token. This value is checked against the creation time stamped on the cookie. The default value is 180 seconds. You must take into account clock skew among participating servers. For example: [e-community-sso] vf-token-lifetime = 180 ec-cookie-lifetime The ec-cookie-lifetime stanza entry specifies the maximum lifetime (in minutes) of the e-community domain cookie. The default value is 300 minutes. For example: [e-community-sso] ec-cookie-lifetime = 300 You must take into account any clock skew among the participating domains. Clock skew means that the system times differ on the relevant servers in each domain. When this difference approaches the value of vf-token-lifetime, the effective lifetime of the token is greatly reduced. When this difference exceeds the value of vf-token-lifetime, tokens from one domain cannot be valid for the other domain. Administrators should adjust vf-token-lifetime accordingly. However, when clock skew requires that vf-token-lifetime be set to a large value, the risk of replay attacks increases. In this case, administrators should consider synchronizing the system time on the relevant servers in each domain. For more information, see the Web Reverse Proxy Stanza Reference topics..Configuration of e-community single sign-on

Configure token and ec-cookie lifetime values

About this task

vf-token-lifetime

The vf-token-lifetime stanza entry sets the lifetime timeout value (in seconds) of the vouch-for token. This value is checked against the creation time stamped on the cookie. The default value is 180 seconds. You must take into account clock skew among participating servers.

For example:

[e-community-sso]
vf-token-lifetime = 180

ec-cookie-lifetime

The ec-cookie-lifetime stanza entry specifies the maximum lifetime (in minutes) of the e-community domain cookie. The default value is 300 minutes.

For example:

[e-community-sso]
ec-cookie-lifetime = 300

You must take into account any clock skew among the participating domains. Clock skew means that the system times differ on the relevant servers in each domain. When this difference approaches the value of vf-token-lifetime, the effective lifetime of the token is greatly reduced. When this difference exceeds the value of vf-token-lifetime, tokens from one domain cannot be valid for the other domain. Administrators should adjust vf-token-lifetime accordingly. However, when clock skew requires that vf-token-lifetime be set to a large value, the risk of replay attacks increases. In this case, administrators should consider synchronizing the system time on the relevant servers in each domain.

For more information, see the Web Reverse Proxy Stanza Reference topics..

Parent topic: Configuration of e-community single sign-on

Handling errors from CDMF during token creationHandling errors from CDMF during token creationpropagate-cdmf-errors stanza entryCDMFerrorstoken creationtokenscreationCDMFerrorserrorstoken creationCDMF During the creation of a e-community token, the ssocreate module calls the CDMF library to acquire any extended attributes to be included in the token. Extended attributes (that further describe the user) can be required for successful identity mapping of the user on the destination server. The CDMF API uses the cdmf_get_usr_attributes call to acquire extended attributes. It is possible for the cdmf_get_usr_attributes call to fail in obtaining the required information and return an error. In such a case, the subsequent behavior of the token creation process can be controlled through use of the propagate-cdmf-errors stanza entry located in the [cdsso] stanza. Values for this stanza entry include "yes" and "no". A "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error. A "yes" value forces the token creation process to end when CDMF fails to obtain attributes and returns an error. Example: [cdsso] propagate-cdmf-errors = noConfiguration of e-community single sign-on

Handling errors from CDMF during token creation

About this task

During the creation of a e-community token, the ssocreate module calls the CDMF library to acquire any extended attributes to be included in the token. Extended attributes (that further describe the user) can be required for successful identity mapping of the user on the destination server. The CDMF API uses the cdmf_get_usr_attributes call to acquire extended attributes.

It is possible for the cdmf_get_usr_attributes call to fail in obtaining the required information and return an error. In such a case, the subsequent behavior of the token creation process can be controlled through use of the propagate-cdmf-errors stanza entry located in the [cdsso] stanza. Values for this stanza entry include "yes" and "no".

A "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error.

A "yes" value forces the token creation process to end when CDMF fails to obtain attributes and returns an error.

Example:

[cdsso]
propagate-cdmf-errors = no

Parent topic: Configuration of e-community single sign-on

Enabling unauthenticated accessEnabling unauthenticated accessecsso-allow-anauthe-community authenticationunauthenticated accessYou can control whether unauthenticated users are allowed access to unprotected resources on e-community SSO participating servers. When authenticated users are allowed this access, the participating server can serve the resource without requiring that the user authenticate through the master authentication server. When this policy is configured, the participating server redirects to the master authentication server only when the client requests access to a protected resource. This policy is set in the WebSEAL configuration file: [e-community-sso] ecsso-allow-unauth = {yes|no} When ecsso-allow-unauth is set to "yes", unauthenticated access is enabled. The default setting is "yes". When ecsso-allow-unauth is set to "no", unauthenticated access is disabled. In this case, clients must authenticate through the master authentication server when requesting access to a resource (protected or not protected) on an e-community SSO participating server. The default behavior changed for WebSEAL Version 5.1. In prior versions, unauthenticated access was disabled. To retain backwards compatible behavior with older versions of WebSEAL, set ecsso-allow-unauth = no. Configuration of e-community single sign-on

Enabling unauthenticated access

About this task

You can control whether unauthenticated users are allowed access to unprotected resources on e-community SSO participating servers. When authenticated users are allowed this access, the participating server can serve the resource without requiring that the user authenticate through the master authentication server. When this policy is configured, the participating server redirects to the master authentication server only when the client requests access to a protected resource.

This policy is set in the WebSEAL configuration file:

[e-community-sso]
ecsso-allow-unauth = {yes|no}

When ecsso-allow-unauth is set to "yes", unauthenticated access is enabled. The default setting is "yes".

When ecsso-allow-unauth is set to "no", unauthenticated access is disabled. In this case, clients must authenticate through the master authentication server when requesting access to a resource (protected or not protected) on an e-community SSO participating server.

Note: The default behavior changed for WebSEAL Version 5.1. In prior versions, unauthenticated access was disabled. To retain backwards compatible behavior with older versions of WebSEAL, set ecsso-allow-unauth = no.

Parent topic: Configuration of e-community single sign-on

Limiting the ability to generate vouch-for tokens Limiting the ability to generate vouch-for tokens disable-ec-cookievouch-fortokendisable-ec-cookieThe WebSEAL configuration file includes an optional parameter that enables you to limit the ability to generate vouch-for tokens to the MAS. The disable-ec-cookie option in the e-community-sso stanza is set to no by default. Changing the value of this option to yes disables the use of the e-community cookie and permits only the MAS to generate vouch-for tokens. In this case, the single-signon process always uses the MAS, allowing the MAS to detect all hosts that sign on across the e-community. This option is useful for customers who want to construct a customized ECSSO signoff process. For more information on a customized single signoff process, see Logout using pkmslogout-nomas.Configuration of e-community single sign-on

Limiting the ability to generate vouch-for tokens

About this task

The WebSEAL configuration file includes an optional parameter that enables you to limit the ability to generate vouch-for tokens to the MAS. The disable-ec-cookie option in the e-community-sso stanza is set to no by default. Changing the value of this option to yes disables the use of the e-community cookie and permits only the MAS to generate vouch-for tokens. In this case, the single-signon process always uses the MAS, allowing the MAS to detect all hosts that sign on across the e-community. This option is useful for customers who want to construct a customized ECSSO signoff process. For more information on a customized single signoff process, see Logout using pkmslogout-nomas.

Parent topic: Configuration of e-community single sign-on

Configuration of the behavior for authentication failure Configuration of the behavior for authentication failure handle-auth-failure-at-masauthenticationhandle-auth-failure-at-masWhen an unauthenticated user has an unsuccessful login at the MAS (for example, provides an incorrect password), the MAS generates a vouch-for token containing the error and, in the default configuration, redirects the Web browser back to the requesting host. When the requesting host encounters the error in the vouch-for token, it typically requests a local login. The handle-auth-failure-at-mas option in the e-community-sso stanza of the WebSEAL configuration file allows administrators to configure the behavior for authentication failure. If handle-auth-failure-at-mas is set to yes , the MAS handles login failures directly without redirecting the Web browser back to the requesting host; in this case, the MAS does not generate a vouch-for token until a successful authentication occurs.Configuration of e-community single sign-on

Configuration of the behavior for authentication failure

When an unauthenticated user has an unsuccessful login at the MAS (for example, provides an incorrect password), the MAS generates a vouch-for token containing the error and, in the default configuration, redirects the Web browser back to the requesting host. When the requesting host encounters the error in the vouch-for token, it typically requests a local login. The handle-auth-failure-at-mas option in the e-community-sso stanza of the WebSEAL configuration file allows administrators to configure the behavior for authentication failure. If handle-auth-failure-at-mas is set to yes , the MAS handles login failures directly without redirecting the Web browser back to the requesting host; in this case, the MAS does not generate a vouch-for token until a successful authentication occurs.

Parent topic: Configuration of e-community single sign-on

Logout using pkmslogout-nomas Logout using pkmslogout-nomas pkmslogout-nomaslogoutpkmslogout-nomasTo help customers who wish to construct and implement a single signoff process in which all hosts are signed off at the MAS, WebSEAL can be configured to use the pkmslogout-nomas management page. When ECSSO is configured, the pkmslogout-nomas management page can be used as an alternative to the pkmslogout command to log out from the session on the current host. For example: https://www.example.com/pkmslogout-nomasThe /pkmslogout management page causes clients that log out of a local system to be redirected to perform another logout on the MAS. The /pkmslogout-nomas management page operates exactly like the /pkmslogout management page with the exception that it does not redirect the Web browser to the MAS host /pkmslogout management page to log out the user's session. This makes it possible to chain logouts from the MAS. For example, a custom logout page can be placed on the MAS system that contains hidden links to the /pkmslogout pages on all the non-MAS systems, thus logging the user out of every system in the community.Configuration of e-community single sign-on

Logout using pkmslogout-nomas

To help customers who wish to construct and implement a single signoff process in which all hosts are signed off at the MAS, WebSEAL can be configured to use the pkmslogout-nomas management page. When ECSSO is configured, the pkmslogout-nomas management page can be used as an alternative to the pkmslogout command to log out from the session on the current host. For example:

https://www.example.com/pkmslogout-nomas

The /pkmslogout management page causes clients that log out of a local system to be redirected to perform another logout on the MAS. The /pkmslogout-nomas management page operates exactly like the /pkmslogout management page with the exception that it does not redirect the Web browser to the MAS host /pkmslogout management page to log out the user's session. This makes it possible to chain logouts from the MAS. For example, a custom logout page can be placed on the MAS system that contains hidden links to the /pkmslogout pages on all the non-MAS systems, thus logging the user out of every system in the community.

Parent topic: Configuration of e-community single sign-on

Use of e-community with virtual hostsUse of e-community with virtual hostsUse of e-community with virtual hosts in IBM Security Access Manager for Webe-communityvirtual hostsvirtual hostse-communitySee E-community single signon with virtual hostsThe E-community single signon feature can be used to do single signon between multiple virtual hosts that are on a single WebSEAL instance. .Configuration of e-community single sign-on

Use of e-community with virtual hosts

See E-community single signon with virtual hosts.

Parent topic: Configuration of e-community single sign-on

Extended attributes for ECSSOExtended attributes for ECSSOExtended attributes for ECSSO in IBM Security Access Manager for WebECSSOextended attributesextended attributesECSSOThis section contains the following topics:E-community single signonE-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.E-community single signon conceptsConfiguration of e-community single sign-onCompatibility issues for ECSSOExtended attributes to add to tokenExtended attributes to extract from tokenIn the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to an e-community single sign-on token.

Extended attributes for ECSSO

This section contains the following topics:

Extended attributes to add to token

Extended attributes to extract from token
In the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to an e-community single sign-on token.

Parent topic: E-community single signon

Related concepts:

E-community single signon concepts

Configuration of e-community single sign-on

Related reference:

Compatibility issues for ECSSO

Extended attributes to add to tokenExtended attributes to add to tokenextended attributesadd to tokentokensadd extended attributesIn the WebSEAL configuration file, you can specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that is added to an extended attribute list when a user credential is created. Extended attributes can be added by a number of authentication mechanisms, including external authentication C API services. The external authentication C API modules can be used, for example, to obtain user information from a registry that is external to Security Access Manager.You can use this setting to customize the contents of the e-community single signon token. This feature enables you to tailor the token contents to match the needs of the destination domain. When you use this feature to add an attribute to a token, you must also configure the WebSEAL configuration file for the server in the destination domain. For the destination server, the stanza [ecsso-incoming-attributes] is used to specify the handling (extract or ignore) of each attribute.You can specify extended attributes by name, or you can declare a pattern that matches multiple attribute names. You can use standard Security Access Manager wildcard-matching characters. For a list of supported wildcard pattern matching characters, see Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters..Each entry is assigned the name of the domain for which the token is intended. You can include multiple entries specifying names or patterns for each domain.The syntax is:[ecsso-token-attributes] domain_name = pattern1 domain_name = pattern2 ... domain_name = patternN <default> = pattern1 <default> = pattern2 ... <default> = patternN The <default> entry is optional. When WebSEAL does not find an entry that matches the domain name, WebSEAL looks for a <default> entry. If the configuration file contains a <default> entry, WebSEAL uses the assigned attribute patterns for the current domain. The string <default> is a keyword, and must be specified exactly as shown above, including the < and > characters.Example: You are creating an e-community single signon solution between two domains: example1.com and example2.com. Users log in to example1.com but can get redirected to example2.com during the user session. Your deployment includes a customized external authentication C API module that inserts information into each user credential. The information includes a fixed name attribute "job_category" and a variable number of attributes, each prefixed with the characters "my_ext_attr_". This information needs to be added to the cross-domain token. The configuration file entries would be:example2.com = job_category example2.com = my_ext_attr_*Extended attributes for ECSSO

Extended attributes to add to token

In the WebSEAL configuration file, you can specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that is added to an extended attribute list when a user credential is created. Extended attributes can be added by a number of authentication mechanisms, including external authentication C API services. The external authentication C API modules can be used, for example, to obtain user information from a registry that is external to Security Access Manager.

You can use this setting to customize the contents of the e-community single signon token. This feature enables you to tailor the token contents to match the needs of the destination domain. When you use this feature to add an attribute to a token, you must also configure the WebSEAL configuration file for the server in the destination domain. For the destination server, the stanza [ecsso-incoming-attributes] is used to specify the handling (extract or ignore) of each attribute.

You can specify extended attributes by name, or you can declare a pattern that matches multiple attribute names. You can use standard Security Access Manager wildcard-matching characters. For a list of supported wildcard pattern matching characters, see Supported wildcard pattern matching characters.

Each entry is assigned the name of the domain for which the token is intended. You can include multiple entries specifying names or patterns for each domain.

The syntax is:

[ecsso-token-attributes]
domain_name = pattern1
domain_name = pattern2
...
domain_name = patternN
<default> = pattern1
<default> = pattern2
...
<default> = patternN

The <default> entry is optional. When WebSEAL does not find an entry that matches the domain name, WebSEAL looks for a <default> entry. If the configuration file contains a <default> entry, WebSEAL uses the assigned attribute patterns for the current domain. The string <default> is a keyword, and must be specified exactly as shown above, including the < and > characters.

Example: You are creating an e-community single signon solution between two domains: example1.com and example2.com. Users log in to example1.com but can get redirected to example2.com during the user session. Your deployment includes a customized external authentication C API module that inserts information into each user credential. The information includes a fixed name attribute "job_category" and a variable number of attributes, each prefixed with the characters "my_ext_attr_". This information needs to be added to the cross-domain token. The configuration file entries would be:

example2.com = job_category
example2.com = my_ext_attr_*

Parent topic: Extended attributes for ECSSO

Extended attributes to extract from tokenExtended attributes to extract from tokenExtended attributes to extract from token in IBM Security Access Manager for WebIn the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to an e-community single sign-on token.extended attributesextract from ecsso tokentokensextended attributes to extract fromThe attributes can either be extracted or ignored. In some cases, you must extract the attributes because there is no way for a server in the destination domain to generate them. In other cases, you do not want to extract the tokens, because the server in the destination domain can use an independent process to gather the same extended attributes. For example, the attribute could reflect a timestamp that needs to reflect the system time on the destination server.In the built-in token consume module, attributes that are extracted from the token are passed through to the cross-domain mapping framework library. The default cross-domain mapping framework library passes attributes directly through to the user credential. Customized cross-domain mapping framework libraries can manipulate attributes as needed before passing them to the user credential.The syntax for the entries is as follows:[ecsso-incoming-attributes] attribute_pattern = {preserve|refresh}Typically, the names of the extended attributes (attribute_pattern) match the names of the attributes specified in the [ecsso-token-attributes] stanza of the configuration file for a WebSEAL server that generates the tokens. The value must be one of the following keywords:preserve Extract all attributes that match attribute_pattern.refresh Do not extract attributes that match attribute_pattern.Extended attributes in the token that do not match an entry in [ecsso-incoming-attributes] are preserved (extracted).The order of the entries in the stanza is important. The first entry that matches an attribute name is used. Other entries are ignored. For example, if you want to extract the attribute named my_special_attr1 but want to ignore all other entries with the prefix my_special_attr_, the stanza entries should be:[ecsso-incoming-attributes] my_special_attr1 = preserve my_special_attr_* = refreshUsing the examples shown above in Extended attributes to add to token, the entries in the WebSEAL configuration file for a server that operates in the example2.com domain could be:[ecsso-incoming-attributes] job_category = preserve my_cdas_attr_1 = preserve my_cdas_attr_* = refreshIn this example, the attributes job_category and my_cdas_attr_1 are extracted from the token. The remainder of the attributes with the prefix my_cdas_attr_ are ignored.Extended attributes for ECSSO

Extended attributes to extract from token

In the WebSEAL configuration file, you can specify how the token consume module handles extended attributes that have been added to an e-community single sign-on token.

The attributes can either be extracted or ignored. In some cases, you must extract the attributes because there is no way for a server in the destination domain to generate them. In other cases, you do not want to extract the tokens, because the server in the destination domain can use an independent process to gather the same extended attributes. For example, the attribute could reflect a timestamp that needs to reflect the system time on the destination server.

In the built-in token consume module, attributes that are extracted from the token are passed through to the cross-domain mapping framework library. The default cross-domain mapping framework library passes attributes directly through to the user credential. Customized cross-domain mapping framework libraries can manipulate attributes as needed before passing them to the user credential.

The syntax for the entries is as follows:

[ecsso-incoming-attributes]
attribute_pattern = {preserve|refresh}

Typically, the names of the extended attributes (attribute_pattern) match the names of the attributes specified in the [ecsso-token-attributes] stanza of the configuration file for a WebSEAL server that generates the tokens. The value must be one of the following keywords:

preserve

Extract all attributes that match attribute_pattern.

refresh

Do not extract attributes that match attribute_pattern.

Extended attributes in the token that do not match an entry in [ecsso-incoming-attributes] are preserved (extracted).

The order of the entries in the stanza is important. The first entry that matches an attribute name is used. Other entries are ignored. For example, if you want to extract the attribute named my_special_attr1 but want to ignore all other entries with the prefix my_special_attr_, the stanza entries should be:

[ecsso-incoming-attributes]
my_special_attr1 = preserve
my_special_attr_* = refresh

Using the examples shown above in Extended attributes to add to token, the entries in the WebSEAL configuration file for a server that operates in the example2.com domain could be:

[ecsso-incoming-attributes]
job_category = preserve
my_cdas_attr_1 = preserve
my_cdas_attr_* = refresh

In this example, the attributes job_category and my_cdas_attr_1 are extracted from the token. The remainder of the attributes with the prefix my_cdas_attr_ are ignored.

Parent topic: Extended attributes for ECSSO

Compatibility issues for ECSSOCompatibility issues for ECSSOECSSOcompatibility issuescompatibility issuesECSSOThis section contains the following topics: E-community single signonE-community single signon (sometimes referred to as ECSSO) allows authenticated users to access protected resources across multiple servers in multiple domains without requiring additional logins.E-community single signon conceptsConfiguration of e-community single sign-onExtended attributes for ECSSOUTF-8 encoding of tokens for e-community single signonToken compatibility with earlier versions of WebSEALSecurity Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.

Compatibility issues for ECSSO

This section contains the following topics:

UTF-8 encoding of tokens for e-community single signon

Token compatibility with earlier versions of WebSEAL
Security Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.

Parent topic: E-community single signon

Related concepts:

E-community single signon concepts

Configuration of e-community single sign-on

Extended attributes for ECSSO

UTF-8 encoding of tokens for e-community single signonUTF-8 encoding of tokens for e-community single signone-community authenticationUTF-8UTF-8e-community authenticationuse-utf8 stanza entrye-community-sso stanzaThe use of UTF-8 encoding for strings within tokens used for e-community single signon is specified in the WebSEAL configuration file.[e-community-sso] use-utf8 = {yes|no}The default value is "yes".When use-utf8 is set to "no", strings are encoded using the local code page. Use this value when implementing e-community single signon with older (pre-version 5.1) WebSEAL servers. WebSEAL servers from versions prior to 5.1 do not use UTF-8 encoding for tokens. When deploying an environment that includes these older servers, configure the WebSEAL server to not use UTF-8 encoding. This setting is necessary for backwards compatibility.Compatibility issues for ECSSO

UTF-8 encoding of tokens for e-community single signon

The use of UTF-8 encoding for strings within tokens used for e-community single signon is specified in the WebSEAL configuration file.

[e-community-sso]
use-utf8 = {yes|no}

The default value is "yes".

When use-utf8 is set to "no", strings are encoded using the local code page. Use this value when implementing e-community single signon with older (pre-version 5.1) WebSEAL servers. WebSEAL servers from versions prior to 5.1 do not use UTF-8 encoding for tokens. When deploying an environment that includes these older servers, configure the WebSEAL server to not use UTF-8 encoding. This setting is necessary for backwards compatibility.

Parent topic: Compatibility issues for ECSSO

Token compatibility with earlier versions of WebSEALToken compatibility with earlier versions of WebSEALSecurity Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.pre-800-compatible-tokens stanza entrytokensWebSEALcompatibilityWebSEALtoken compatibility If you integrate e-community single sign-on with servers that include versions of Security Access Manager earlier than version 8.0, you must enable the pre-800-compatible-tokens stanza entry in the [server] stanza of the WebSEAL configuration file. For example:pre-800-compatible-tokens = yesThe default setting for this stanza entry is no.Compatibility issues for ECSSO

Token compatibility with earlier versions of WebSEAL

Security Access Manager, version 8.0, changed the default cipher that WebSEAL uses to encode the tokens. Tokens that are generated with this default cipher are not compatible with the tokens that are generated by earlier versions of WebSEAL.

If you integrate e-community single sign-on with servers that include versions of Security Access Manager earlier than version 8.0, you must enable the pre-800-compatible-tokens stanza entry in the [server] stanza of the WebSEAL configuration file. For example:

pre-800-compatible-tokens = yes

The default setting for this stanza entry is no.

Parent topic: Compatibility issues for ECSSO

Single sign-offSingle sign-offIBM Security Access Manager for WebYou can configure WebSEAL to initiate single sign-off from multiple protected web resources located on junctioned backend servers.single signofffrom multiple protected web resourcesThe single signoff functionality is detailed in the following sections:Single Signon SolutionsOverview of the single sign-off functionalityYou can configure WebSEAL to send HTTP requests to predefined applications when a session is terminated. The applications that receive these requests can then terminate any associated sessions that are located on junctioned backend servers.Configuring single signoffSpecifications for single sign-off requests and responsesWhen you configure the single signoff functionality, the single signoff requests and responses are formatted according to these specifications.

Single sign-off

You can configure WebSEAL to initiate single sign-off from multiple protected web resources located on junctioned backend servers.

The single signoff functionality is detailed in the following sections:

Overview of the single sign-off functionality
You can configure WebSEAL to send HTTP requests to predefined applications when a session is terminated. The applications that receive these requests can then terminate any associated sessions that are located on junctioned backend servers.

Configuring single signoff

Specifications for single sign-off requests and responses
When you configure the single signoff functionality, the single signoff requests and responses are formatted according to these specifications.

Parent topic: Single Signon Solutions

Overview of the single sign-off functionalityOverview of the single sign-off functionalityOverview of the single sign-off functionality in IBM Security Access Manager for WebYou can configure WebSEAL to send HTTP requests to predefined applications when a session is terminated. The applications that receive these requests can then terminate any associated sessions that are located on junctioned backend servers.single signoffoverviewpkmslogoutWhen a session is ended, WebSEAL deletes the session and the session data that it manages. WebSEAL cannot control sessions created and managed by backend applications. This situation results in backend server sessions remaining active after the corresponding WebSEAL session is terminated. WebSEAL provides a mechanism to remove sessions on backend servers when a session ends in WebSEAL. To achieve single signoff, WebSEAL sends a request to configured single signoff URIs whenever a WebSEAL session is destroyed. Using the information provided in the request, applications on the backend servers can terminate the stale sessions. There are four different mechanisms that can terminate a WebSEAL session:User request by accessing pkmslogout.Session timeout.EAI session termination command.Session terminate command from the pdadmin tool. Using this feature in a distributed session cache environment generates a separate signoff request from each WebSEAL server containing the terminated session. Therefore, the single signoff application in a distributed session cache environment must handle multiple signoff requests for a single session - one per WebSEAL server. Single sign-offYou can configure WebSEAL to initiate single sign-off from multiple protected web resources located on junctioned backend servers.Configuring single signoffSpecifications for single sign-off requests and responsesWhen you configure the single signoff functionality, the single signoff requests and responses are formatted according to these specifications.

Overview of the single sign-off functionality

You can configure WebSEAL to send HTTP requests to predefined applications when a session is terminated. The applications that receive these requests can then terminate any associated sessions that are located on junctioned backend servers.

When a session is ended, WebSEAL deletes the session and the session data that it manages. WebSEAL cannot control sessions created and managed by backend applications. This situation results in backend server sessions remaining active after the corresponding WebSEAL session is terminated. WebSEAL provides a mechanism to remove sessions on backend servers when a session ends in WebSEAL.

To achieve single signoff, WebSEAL sends a request to configured single signoff URIs whenever a WebSEAL session is destroyed. Using the information provided in the request, applications on the backend servers can terminate the stale sessions.

There are four different mechanisms that can terminate a WebSEAL session:

User request by accessing pkmslogout.

Session timeout.

EAI session termination command.

Session terminate command from the pdadmin tool.

Note: Using this feature in a distributed session cache environment generates a separate signoff request from each WebSEAL server containing the terminated session. Therefore, the single signoff application in a distributed session cache environment must handle multiple signoff requests for a single session - one per WebSEAL server.

Parent topic: Single sign-off

Related concepts:

Specifications for single sign-off requests and responses

Related tasks:

Configuring single signoff

Configuring single signoffConfiguring single signoffsingle signoffconfigurationsinigle-signoff-uri stanza entryYou can enable single signoff in WebSEAL by specifying the URIs that receive the single signoff request. Configure a single-signoff-uri entry in the [acnt-mgt] stanza to reference each single signoff application. This resource cannot be located on a virtual host junction, and you must provide the server relative URI. For example: [acnt-mgt] single-signoff-uri = /applications/signoffEach time a WebSEAL session is terminated, WebSEAL sends a request to each of the specified URIs. Each request contains the configured headers and cookies for the junction of the specified resource. The single signoff resources are responsible for using this information to terminate any sessions on the back-end servers. WebSEAL expects to receive a response containing an HTTP status code of 200 OK. If the response contains any other status code, WebSEAL logs an error. You can perform single signoff on multiple junctioned servers. Configure more than one single-sign-off-uri entry to send a request to multiple URIs. With single-signoff-uri configured, WebSEAL does not send cookies that were sent by the browser to the backend single-signoff-uri. The WebSEAL single-signoff-uri mechanism by design, does not use cookies sent by the client. The design of the mechanism is to only use cookies stored in the WebSEAL cookie jar (managed cookies). This way WebSEAL is able to perform the single sign-off even in cases like a timeout, where there is no logout request from the browser.Single sign-offYou can configure WebSEAL to initiate single sign-off from multiple protected web resources located on junctioned backend servers.Overview of the single sign-off functionalityYou can configure WebSEAL to send HTTP requests to predefined applications when a session is terminated. The applications that receive these requests can then terminate any associated sessions that are located on junctioned backend servers.Specifications for single sign-off requests and responsesWhen you configure the single signoff functionality, the single signoff requests and responses are formatted according to these specifications.

Configuring single signoff

About this task

You can enable single signoff in WebSEAL by specifying the URIs that receive the single signoff request. Configure a single-signoff-uri entry in the [acnt-mgt] stanza to reference each single signoff application. This resource cannot be located on a virtual host junction, and you must provide the server relative URI. For example:

[acnt-mgt]
single-signoff-uri = /applications/signoff

Each time a WebSEAL session is terminated, WebSEAL sends a request to each of the specified URIs. Each request contains the configured headers and cookies for the junction of the specified resource. The single signoff resources are responsible for using this information to terminate any sessions on the back-end servers.

WebSEAL expects to receive a response containing an HTTP status code of 200 OK. If the response contains any other status code, WebSEAL logs an error.

Note: You can perform single signoff on multiple junctioned servers. Configure more than one single-sign-off-uri entry to send a request to multiple URIs.

With single-signoff-uri configured, WebSEAL does not send cookies that were sent by the browser to the backend single-signoff-uri. The WebSEAL single-signoff-uri mechanism by design, does not use cookies sent by the client. The design of the mechanism is to only use cookies stored in the WebSEAL cookie jar (managed cookies). This way WebSEAL is able to perform the single sign-off even in cases like a timeout, where there is no logout request from the browser.

Parent topic: Single sign-off

Related concepts:

Overview of the single sign-off functionality

Specifications for single sign-off requests and responses

Specifications for single sign-off requests and responsesSpecifications for single signoff requests and responsesSpecifications for single sign-off requests and responses in IBM Security Access Manager for WebWhen you configure the single signoff functionality, the single signoff requests and responses are formatted according to these specifications.single-signoff-urisingle signoffrequestsresponsesSingle sign-off requestsWebSEAL sends the request to the single signoff resource that is specified by the single-signoff-uri configuration entry. The single sign-off request contains:The HTTP GET method.Any cookies and headers configured for the junction point where the single signoff resource resides.Single sign-off responsesWebSEAL expects a response with an HTTP status code 200 OK. Any other status code results in a logged error. WebSEAL disregards the body and any other headers in the response. Single sign-offYou can configure WebSEAL to initiate single sign-off from multiple protected web resources located on junctioned backend servers.Overview of the single sign-off functionalityYou can configure WebSEAL to send HTTP requests to predefined applications when a session is terminated. The applications that receive these requests can then terminate any associated sessions that are located on junctioned backend servers.Configuring single signoff

Specifications for single sign-off requests and responses

When you configure the single signoff functionality, the single signoff requests and responses are formatted according to these specifications.

Single sign-off requests

WebSEAL sends the request to the single signoff resource that is specified by the single-signoff-uri configuration entry. The single sign-off request contains:

The HTTP GET method.

Any cookies and headers configured for the junction point where the single signoff resource resides.

Single sign-off responses

WebSEAL expects a response with an HTTP status code 200 OK. Any other status code results in a logged error. WebSEAL disregards the body and any other headers in the response.

Parent topic: Single sign-off

Related concepts:

Overview of the single sign-off functionality

Related tasks:

Configuring single signoff

DeploymentDeploymentWeb Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Deployment planningBefore you implement a particular Security Access Manager solution, you must determine the specific security and management capabilities that are required for your network.WebSEAL instance deploymentThis chapter discusses techniques for deploying one or more instances of WebSEAL.Application integrationDynamic URLsInternet Content Adaptation Protocol (ICAP) SupportThe Internet Content Adaptation Protocol (ICAP) is designed to offload the processing of Internet-based content to dedicated servers. ICAP helps free up resources and standardize how features are implemented.

Deployment

Deployment planning
Before you implement a particular Security Access Manager solution, you must determine the specific security and management capabilities that are required for your network.

WebSEAL instance deployment
This chapter discusses techniques for deploying one or more instances of WebSEAL.

Application integration

Dynamic URLs

Internet Content Adaptation Protocol (ICAP) Support
The Internet Content Adaptation Protocol (ICAP) is designed to offload the processing of Internet-based content to dedicated servers. ICAP helps free up resources and standardize how features are implemented.

Parent topic: Web Reverse Proxy configuration

Deployment planningDeployment planningBefore you implement a particular Security Access Manager solution, you must determine the specific security and management capabilities that are required for your network.deployment planningoverviewThe first step in planning the deployment of a Security Access Manager security environment is to define the security requirements for your computing environment. Defining security requirements means determining the business policies that must apply to users, programs, and data. This definition includes:Objects to be securedActions that are permitted on each objectUsers that are permitted to perform the actionsEnforcing a security policy requires an understanding of the flow of access requests through your network topology. In your plan, identify correct roles and locations for firewalls, routers, and subnets. Deploying a Security Access Manager security environment also requires identifying the optimal points within the network that evaluates user access requests, and grants or denies the requested access.Implementation of a security policy requires understanding the number of users, quantity of data, and throughput that your network must accommodate. You must evaluate performance characteristics, scalability, and the need for failover capabilities.After you have an understanding of the features that you want to deploy, you can decide which Security Access Manager systems you need in your environment.For useful planning documentation, including actual business scenarios, see supplemental product information at the following websites:http://www.ibm.com/redbooks/http://www.ibm.com/software/sysmgmt/products/support/Field_Guides.htmlDeployment

Deployment planning

Before you implement a particular Security Access Manager solution, you must determine the specific security and management capabilities that are required for your network.

The first step in planning the deployment of a Security Access Manager security environment is to define the security requirements for your computing environment. Defining security requirements means determining the business policies that must apply to users, programs, and data. This definition includes:

Objects to be secured

Actions that are permitted on each object

Users that are permitted to perform the actions

Enforcing a security policy requires an understanding of the flow of access requests through your network topology. In your plan, identify correct roles and locations for firewalls, routers, and subnets. Deploying a Security Access Manager security environment also requires identifying the optimal points within the network that evaluates user access requests, and grants or denies the requested access.

Implementation of a security policy requires understanding the number of users, quantity of data, and throughput that your network must accommodate. You must evaluate performance characteristics, scalability, and the need for failover capabilities.

After you have an understanding of the features that you want to deploy, you can decide which Security Access Manager systems you need in your environment.

For useful planning documentation, including actual business scenarios, see supplemental product information at the following websites:

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

http://www.ibm.com/software/sysmgmt/products/support/Field_Guides.html

Parent topic: Deployment

WebSEAL instance deploymentWebSEAL instance deploymentWebSEAL instance deployment in IBM Security Access Manager for WebThis chapter discusses techniques for deploying one or more instances of WebSEAL.WebSEAL instancesinstancesdeploymentdeploymentWebSEAL instancesDeploymentWebSEAL instance configuration overviewWebSEAL instance configuration tasksLoad balancing environments

WebSEAL instance deployment

This chapter discusses techniques for deploying one or more instances of WebSEAL.

WebSEAL instance configuration overview

WebSEAL instance configuration tasks

Load balancing environments

Parent topic: Deployment

WebSEAL instance configuration overviewWebSEAL instance configuration overviewWebSEALinstancesconfiguration overviewinstancesWebSEALconfigurationWebSEAL configurationoverviewThis section contains the following topics:WebSEAL instance deploymentThis chapter discusses techniques for deploying one or more instances of WebSEAL.WebSEAL instance configuration tasksLoad balancing environmentsWebSEAL instance configuration planningExample WebSEAL instance configuration valuesUnique configuration file for each WebSEAL instanceA unique WebSEAL configuration file is created for each WebSEAL instance. The name of the configuration file includes the instance name.

WebSEAL instance configuration overview

This section contains the following topics:

WebSEAL instance configuration planning

Example WebSEAL instance configuration values

Unique configuration file for each WebSEAL instance
A unique WebSEAL configuration file is created for each WebSEAL instance. The name of the configuration file includes the instance name.

Parent topic: WebSEAL instance deployment

Related concepts:

WebSEAL instance configuration tasks

Load balancing environments

WebSEAL instance configuration planningWebSEAL instance configuration planningWebSEAL configurationplanningsettingsinstancesinstancesWebSEALhost namenamevalid charactersdefinitiondefaultlistening portIP address for the primary interfacelogical network interfacelistening portprimary interfacelogical network interfaceSSL configurationWebSEAL to LDAPdocument root directorydoc-rootA WebSEAL instance is a unique WebSEAL server process with a unique configuration file and listening port. WebSEAL deployments support multiple WebSEAL instances.To configure a WebSEAL instance, you must collect some information about the Security Access Manager deployment.Unless stated otherwise, each of the following settings is required.Administrator name and password The authentication details for the Security Access Manager administrative user. By default, this is the sec_master user. You must have administrative user permissions to configure a WebSEAL instance.DomainThe Security Access Manager domain.Host name The host name that the Security Access Manager policy server uses to contact the appliance. The address that corresponds to this host name must match a management interface address of the appliance. Valid values include any valid host name or IP address. Instance name A unique name that identifies the WebSEAL instance. Multiple WebSEAL instances can be installed on one appliance. Each instance must have a unique name. Valid characters for instance names include the alphanumeric characters ([A-Z][a-z][0–9]) plus the following characters: underscore ( _ ), hyphen ( - ), and period ( . ). No other characters are valid. Example names: web1, web2, web_3, web-4, web.5 The instance name also affects how the full server name is listed during a pdadmin server list command. For this command, the full server name has the following format: instance_name-webseald-host_name For example, an instance_name of web1 installed on a host named diamond has the following full server name: web1-webseald-diamondListening port This is the port through which the WebSEAL instance communicates with the Security Access Manager policy server. The default port number is 7234. This port number must be unique for every WebSEAL instance. The default port is typically used by the default (first) WebSEAL instance. The installation automatically increments to the next available port. You can modify the port number if necessary. Any port number above 1024 is valid. Select a port that is not used for any other purpose. IP address for the primary interface The unique IP address for the WebSEAL instance. The WebSEAL server listens on this IP address for incoming requests. You must also assign each WebSEAL instance a unique HTTP and HTTPS port.HTTP protocol and HTTP port Specifies whether to accept user requests across the HTTP protocol. If you enable HTTP, you must assign a port number. The default port number is 80. This port is used by the default (first) instance. If this port is not available, the installation automatically increments to the next available port. HTTPS protocol and HTTPS port Specifies whether to accept user requests across the HTTPS protocol. If you enable HTTPS, you must assign a port number. The default port number is 443. This port is used by the default (first) instance. If this port is not available, the installation automatically increments to the next available port. User registry - SSL communication WebSEAL communicates with the LDAP server during authentication procedures. Use of SSL during communication with the LDAP server is optional. However, use of SSL is highly recommended for security reasons in all production deployments. Disabling of SSL usage can be considered for temporary testing or prototyping environments. If you want to use secure SSL communication between a WebSEAL instance and the LDAP registry server, you must use the LDAP SSL key file for this purpose. This is the key file that was created and distributed during installation of the LDAP client. If the initial WebSEAL instance is set up to use secure SSL communication with LDAP, multiple instances can use the same key file. When enabling SSL communication between WebSEAL and the LDAP server, you must provide the following information: Key file name The file that contains the LDAP SSL certificate.Certificate label The LDAP client certificate label. This is optional. When the client label is not specified, the default certificate contained in the keyfile is used. Specify the client label when the keyfile contains more than one certificate, and the certificate to be used is not the default certificate.Port The port number through which to communicate with the LDAP server. The default LDAP server port number is 636.WebSEAL instance configuration overview

WebSEAL instance configuration planning

A WebSEAL instance is a unique WebSEAL server process with a unique configuration file and listening port. WebSEAL deployments support multiple WebSEAL instances.

To configure a WebSEAL instance, you must collect some information about the Security Access Manager deployment.

Unless stated otherwise, each of the following settings is required.

Administrator name and password

The authentication details for the Security Access Manager administrative user. By default, this is the sec_master user. You must have administrative user permissions to configure a WebSEAL instance.

Domain

The Security Access Manager domain.

Host name

The host name that the Security Access Manager policy server uses to contact the appliance. The address that corresponds to this host name must match a management interface address of the appliance. Valid values include any valid host name or IP address.

Instance name

A unique name that identifies the WebSEAL instance. Multiple WebSEAL instances can be installed on one appliance. Each instance must have a unique name.

Valid characters for instance names include the alphanumeric characters ([A-Z][a-z][0–9]) plus the following characters: underscore ( _ ), hyphen ( - ), and period ( . ). No other characters are valid.

Example names: web1, web2, web_3, web-4, web.5

The instance name also affects how the full server name is listed during a pdadmin server list command. For this command, the full server name has the following format:

instance_name-webseald-host_name

For example, an instance_name of web1 installed on a host named diamond has the following full server name:

web1-webseald-diamond

Listening port

This is the port through which the WebSEAL instance communicates with the Security Access Manager policy server. The default port number is 7234. This port number must be unique for every WebSEAL instance.

The default port is typically used by the default (first) WebSEAL instance. The installation automatically increments to the next available port. You can modify the port number if necessary.

Any port number above 1024 is valid. Select a port that is not used for any other purpose.

IP address for the primary interface

The unique IP address for the WebSEAL instance. The WebSEAL server listens on this IP address for incoming requests. You must also assign each WebSEAL instance a unique HTTP and HTTPS port.

HTTP protocol and HTTP port

Specifies whether to accept user requests across the HTTP protocol. If you enable HTTP, you must assign a port number. The default port number is 80. This port is used by the default (first) instance. If this port is not available, the installation automatically increments to the next available port.

HTTPS protocol and HTTPS port

Specifies whether to accept user requests across the HTTPS protocol. If you enable HTTPS, you must assign a port number. The default port number is 443. This port is used by the default (first) instance. If this port is not available, the installation automatically increments to the next available port.

User registry - SSL communication

WebSEAL communicates with the LDAP server during authentication procedures. Use of SSL during communication with the LDAP server is optional. However, use of SSL is highly recommended for security reasons in all production deployments. Disabling of SSL usage can be considered for temporary testing or prototyping environments.

If you want to use secure SSL communication between a WebSEAL instance and the LDAP registry server, you must use the LDAP SSL key file for this purpose. This is the key file that was created and distributed during installation of the LDAP client. If the initial WebSEAL instance is set up to use secure SSL communication with LDAP, multiple instances can use the same key file.

When enabling SSL communication between WebSEAL and the LDAP server, you must provide the following information:

Key file name

The file that contains the LDAP SSL certificate.

Certificate label

The LDAP client certificate label. This is optional. When the client label is not specified, the default certificate contained in the keyfile is used. Specify the client label when the keyfile contains more than one certificate, and the certificate to be used is not the default certificate.

Port

The port number through which to communicate with the LDAP server. The default LDAP server port number is 636.

Parent topic: WebSEAL instance configuration overview

Example WebSEAL instance configuration valuesExample WebSEAL instance configuration valuesWebSEAL configurationexample configuration valuesWebSEAL instanceinstancesconfigurationThe following table contains a set of example settings for a WebSEAL instance. These example settings are used in the sample configuration commands found in the remainder of the configuration sections of this chapter.SettingValueSecurity Access Manager Administrator namesec_masterSecurity Access Manager Administrator passwordmypassw0rdSecurity Access Manager domaindomainAHost namediamond.subnet2.ibm.comInstance nameweb1Listening port7235IP address for the Primary Interface1.2.3.5Enable HTTPyesHTTP port81Enable HTTPSyesHTTPS port444Enable SSLyes Key file nameclient.kdbCertificate label(none)Port636WebSEAL instance configuration overview

Example WebSEAL instance configuration values

The following table contains a set of example settings for a WebSEAL instance. These example settings are used in the sample configuration commands found in the remainder of the configuration sections of this chapter.

Setting | Value
Security Access Manager Administrator name | sec_master
Security Access Manager Administrator password | mypassw0rd
Security Access Manager domain | domainA
Host name | diamond.subnet2.ibm.com
Instance name | web1
Listening port | 7235
IP address for the Primary Interface | 1.2.3.5
Enable HTTP | yes
HTTP port | 81
Enable HTTPS | yes
HTTPS port | 444
Enable SSL | yes
Key file name | client.kdb
Certificate label | (none)
Port | 636

Parent topic: WebSEAL instance configuration overview

Unique configuration file for each WebSEAL instanceUnique configuration file for each WebSEAL instanceA unique WebSEAL configuration file is created for each WebSEAL instance. The name of the configuration file includes the instance name. configuration filesinstancesWebSEAL configurationinstancesThe format is:webseald-instance_name.confThe newly created instance-specific configuration file is automatically configured for SSL communication between the new WebSEAL instance and internal Security Access Manager servers such as the policy server.The new file is also automatically configured to use the server certificate of the initial WebSEAL server to authenticate to client browsers.WebSEAL instance configuration overview

Unique configuration file for each WebSEAL instance

A unique WebSEAL configuration file is created for each WebSEAL instance. The name of the configuration file includes the instance name.

The format is:

webseald-instance_name.conf

The newly created instance-specific configuration file is automatically configured for SSL communication between the new WebSEAL instance and internal Security Access Manager servers such as the policy server.

The new file is also automatically configured to use the server certificate of the initial WebSEAL server to authenticate to client browsers.

Parent topic: WebSEAL instance configuration overview

WebSEAL instance configuration tasksWebSEAL instance configuration tasksWebSEAL instance configuration tasksWebSEALinstancesconfiguration tasksTasks:WebSEAL instance deploymentThis chapter discusses techniques for deploying one or more instances of WebSEAL.WebSEAL instance configuration overviewLoad balancing environmentsAdding a WebSEAL instanceRemoving a WebSEAL instance

WebSEAL instance configuration tasks

Tasks:

Adding a WebSEAL instance

Removing a WebSEAL instance

Parent topic: WebSEAL instance deployment

Related concepts:

WebSEAL instance configuration overview

Load balancing environments

Adding a WebSEAL instanceAdding a WebSEAL instanceWebSEALinstancesnewWebSEAL configurationadding a WebSEAL instanceTo add a WebSEAL instance, complete each of the following steps:Plan the configuration. Complete the following worksheet. For information on determining appropriate values for each setting, see WebSEAL instance configuration planning.Worksheet for adding a WebSEAL instanceSettingValueAdministrator nameAdministrator passwordHost nameInstance nameListening portEnable HTTPyes or noHTTP portEnable HTTPSyes or noHTTPS portEnable SSLyes or noCertificate labelKey file namePortEnsure that all configured WebSEAL instances are running. This prevents any possible conflicts between servers over port usage. Click New on the Reverse Proxy management page in the LMI to create a new WebSEAL instance. Provide settings for the fields displayed on the Instance, IBM Security Access Manager, Transport and User Registry tabs.Click Finish. A message is displayed indicated that the new instance is successfully configured.Verify that the new instance is running in the LMI. The Reverse Proxy management page indicates that the state of the instance is Started. WebSEAL instance configuration tasks

Adding a WebSEAL instance

About this task

To add a WebSEAL instance, complete each of the following steps:

Procedure

Plan the configuration. Complete the following worksheet. For information on determining appropriate values for each setting, see WebSEAL instance configuration planning.

Table 73. Worksheet for adding a WebSEAL instance

Setting | Value
Administrator name |
Administrator password |
Host name |
Instance name |
Listening port |
Enable HTTP | yes or no
HTTP port |
Enable HTTPS | yes or no
HTTPS port |
Enable SSL | yes or no
Certificate label |
Key file name |
Port |

Ensure that all configured WebSEAL instances are running. This prevents any possible conflicts between servers over port usage.

Click New on the Reverse Proxy management page in the LMI to create a new WebSEAL instance.

Provide settings for the fields displayed on the Instance, IBM Security Access Manager, Transport and User Registry tabs.

Click Finish. A message is displayed indicated that the new instance is successfully configured.

Verify that the new instance is running in the LMI. The Reverse Proxy management page indicates that the state of the instance is Started.

Parent topic: WebSEAL instance configuration tasks

Removing a WebSEAL instanceRemoving a WebSEAL instanceWebSEALinstancesremovingWebSEAL configurationremoving an instanceTo remove the configuration for a WebSEAL instance, complete the following steps:Assemble the following information:Instance nameAdministrator IDAdministrator ID passwordOn the Reverse Proxy management page in the LMI, select the instance that you want to delete.Click Delete. The Delete Reverse Proxy Instance window displays.Enter the Administrator authentication details for the selected instance. To delete the instance, click Delete in the Delete Reverse Proxy Instance window. A system notification displays to indicate that the instance was successfully deleted.WebSEAL instance configuration tasks

Removing a WebSEAL instance

About this task

To remove the configuration for a WebSEAL instance, complete the following steps:

Procedure

Assemble the following information:

Instance name

Administrator ID

Administrator ID password

On the Reverse Proxy management page in the LMI, select the instance that you want to delete.

Click Delete. The Delete Reverse Proxy Instance window displays.

Enter the Administrator authentication details for the selected instance.

To delete the instance, click Delete in the Delete Reverse Proxy Instance window. A system notification displays to indicate that the instance was successfully deleted.

Parent topic: WebSEAL instance configuration tasks

Load balancing environmentsLoad balancing environmentsload balancing environmentsenvironmentsload balancingThis section contains the following topics:WebSEAL instance deploymentThis chapter discusses techniques for deploying one or more instances of WebSEAL.WebSEAL instance configuration overviewWebSEAL instance configuration tasksReplicating front-end WebSEAL serversControlling the login_success response

Load balancing environments

This section contains the following topics:

Replicating front-end WebSEAL servers

Controlling the login_success response

Parent topic: WebSEAL instance deployment

Related concepts:

WebSEAL instance configuration overview

WebSEAL instance configuration tasks

Replicating front-end WebSEAL servers Replicating front-end WebSEAL servers load balancing environmentsreplicating front-end WebSEAL serversreplicationfront-end WebSEAL serversserver-name stanza entry (server stanza)front-end WebSEAL serversreplicating The following information replaces the former pdadmin server modify baseurl command, used in previous versions of Security Access Manager. In a heavy load environment, it is advantageous to replicate front-end WebSEAL servers to provide better load-balancing and fail-over capability. When you replicate front-end WebSEAL servers, each server must contain an exact copy of the Web space, the junction database, and the dynurl database. This version of Security Access Manager supports a manual configuration procedure to replicate front-end WebSEAL servers. The pdadmin command is no longer used for this task. In the following example, "WS1" is the host name of the primary WebSEAL server machine. "WS2" is the host name for the replica WebSEAL server machine. Install and configure WebSEAL on both WS1 and WS2 server machines.Using the pdadmin command, create a new object to be the root of the authorization space for both WebSEAL servers. For example: pdadmin> object create /WebSEAL/newroot "Description" 5 ispolicyattachable yesStop WebSEAL on WS1.On WS1, change the value of the server-name stanza entry in the WebSEAL configuration file from "WS1" to "newroot": [server] server-name = newrootRestart WebSEAL on WS1.Repeat Steps 3-5 for WS2. The WS1 and WS2 servers now use the object /WebSEAL/newroot as the base for authorization evaluations. Either the WS1 or the WS2 server can respond to object list and object show commands for objects located below /WebSEAL/newroot. Use the following procedure when unconfiguring either WS1 or WS2:Stop the WebSEAL server.Change the value of the server-name stanza entry back to its original value. For example, for WS1:[server] server-name = WS1Proceed with normal unconfiguration procedures. Conditions: Unified object space management: Although a single object hierarchy is visible to the administrator, all replicated WebSEAL servers are affected by administration commands applied to that object hierarchy and all servers are able to respond to these commands.Unified authorization evaluation: Both WS1 and WS2 use /WebSEAL/newroot as the base for authorization evaluations.Unified configuration: For front-end WebSEAL replication to function correctly, the Web space, junction database, and dynurl database configuration must be identical on each server.Load balancing environments

Replicating front-end WebSEAL servers

About this task

Note: The following information replaces the former pdadmin server modify baseurl command, used in previous versions of Security Access Manager.

In a heavy load environment, it is advantageous to replicate front-end WebSEAL servers to provide better load-balancing and fail-over capability. When you replicate front-end WebSEAL servers, each server must contain an exact copy of the Web space, the junction database, and the dynurl database.

This version of Security Access Manager supports a manual configuration procedure to replicate front-end WebSEAL servers. The pdadmin command is no longer used for this task.

In the following example, "WS1" is the host name of the primary WebSEAL server machine. "WS2" is the host name for the replica WebSEAL server machine.

Install and configure WebSEAL on both WS1 and WS2 server machines.

Using the pdadmin command, create a new object to be the root of the authorization space for both WebSEAL servers. For example:

pdadmin> object create /WebSEAL/newroot "Description" 5 ispolicyattachable yes

Stop WebSEAL on WS1.

On WS1, change the value of the server-name stanza entry in the WebSEAL configuration file from "WS1" to "newroot":

[server]
server-name = newroot

Restart WebSEAL on WS1.

Repeat Steps 3-5 for WS2.

The WS1 and WS2 servers now use the object /WebSEAL/newroot as the base for authorization evaluations. Either the WS1 or the WS2 server can respond to object list and object show commands for objects located below /WebSEAL/newroot.

Use the following procedure when unconfiguring either WS1 or WS2:

Procedure

Stop the WebSEAL server.

Change the value of the server-name stanza entry back to its original value. For example, for WS1:

[server]
server-name = WS1

Proceed with normal unconfiguration procedures.

Results

Conditions:

Unified object space management: Although a single object hierarchy is visible to the administrator, all replicated WebSEAL servers are affected by administration commands applied to that object hierarchy and all servers are able to respond to these commands.

Unified authorization evaluation: Both WS1 and WS2 use /WebSEAL/newroot as the base for authorization evaluations.

Unified configuration: For front-end WebSEAL replication to function correctly, the Web space, junction database, and dynurl database configuration must be identical on each server.

Parent topic: Load balancing environments

Controlling the login_success responseControlling the login_success responseload balancing environmentscontrolling the login_success responselogin_success.htmlcontrolling the login_success responsefront-end WebSEAL serverscontrolling the login_success responseautomatic redirectionload balancing environmentsauthenticationforced redirectionautomatic redirectionredirectionautomaticload balancing environmentsforced redirectionload balancing environmentsonLoad HTTP attributeIn a network topology involving multiple WebSEAL instances controlled by a load balancing system, the request URL can be "lost" during the communication exchange that occurs for the authentication process. For example, it is possible for one WebSEAL instance to receive the request URL (for a protected resource) and present the user with a login form. When the user submits the completed login form, a non-sticky load balancer might send the POST data to a second WebSEAL instance. (Sticky load balancing is the distribution of user requests across a set of servers in such a way that requests from a given user are consistently sent to the same server.) This second WebSEAL instance can successfully process the login POST data, but is not able to redirect to the original URL request. In this case, the second WebSEAL instance sends the login_success.html page that reports the message "Your login was successful." WebSeal does not make use of the Referer header, because if the initial unauthenticated request was a POST, a redirect to the original URI would result in a GET to a resource which should receive a POST. There are several possible solutions: Use a sticky load balancing system and configure an adequate sticky time (for example, 20-30 seconds) that allows only one WebSEAL instance to process the overall login exchange.Modify the WebSEAL configuration file to enable automatic redirection after authentication. WebSEAL can then redirect the user to a specified response page that can better handle the post-login process. With automatic redirection WebSEAL no longer uses the login_success.html response page. Automatic redirection involves the following stanzas and stanza entries: [enable-redirects] redirect = [acnt-mgt] login-redirect-page = See Automatic redirection after authentication for complete information.Modify the login_success.html response page so that it redirects the user's browser back in the request history. This technique allows the second WebSEAL instance to receive and process the original request URL. For example: <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <TITLE>Success</TITLE> </HEAD> <BODY onLoad="history.back()"> ... </BODY> </HTML>Load balancing environments

Controlling the login_success response

About this task

In a network topology involving multiple WebSEAL instances controlled by a load balancing system, the request URL can be "lost" during the communication exchange that occurs for the authentication process. For example, it is possible for one WebSEAL instance to receive the request URL (for a protected resource) and present the user with a login form. When the user submits the completed login form, a non-sticky load balancer might send the POST data to a second WebSEAL instance. (Sticky load balancing is the distribution of user requests across a set of servers in such a way that requests from a given user are consistently sent to the same server.)

This second WebSEAL instance can successfully process the login POST data, but is not able to redirect to the original URL request. In this case, the second WebSEAL instance sends the login_success.html page that reports the message "Your login was successful."

Note: WebSeal does not make use of the Referer header, because if the initial unauthenticated request was a POST, a redirect to the original URI would result in a GET to a resource which should receive a POST.

There are several possible solutions:

Use a sticky load balancing system and configure an adequate sticky time (for example, 20-30 seconds) that allows only one WebSEAL instance to process the overall login exchange.

Modify the WebSEAL configuration file to enable automatic redirection after authentication. WebSEAL can then redirect the user to a specified response page that can better handle the post-login process. With automatic redirection WebSEAL no longer uses the login_success.html response page. Automatic redirection involves the following stanzas and stanza entries:

[enable-redirects]
redirect =

[acnt-mgt]
login-redirect-page =

See Automatic redirection after authentication for complete information.

Modify the login_success.html response page so that it redirects the user's browser back in the request history. This technique allows the second WebSEAL instance to receive and process the original request URL. For example:

<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<TITLE>Success</TITLE>
</HEAD>
<BODY onLoad="history.back()">
...
</BODY>
</HTML>

Parent topic: Load balancing environments

Application integrationApplication integrationtroubleshootingP3P configurationapplicationintegrationThis chapter contains a variety of information pertaining to the integration of third-party application servers in a WebSEAL environment.Topic Index: DeploymentSupport for back-end server-side applicationsBest practices for standard junction usageCustom personalization serviceUser session management for back-end servers

Application integration

This chapter contains a variety of information pertaining to the integration of third-party application servers in a WebSEAL environment.

Topic Index:

Support for back-end server-side applications

Best practices for standard junction usage

Custom personalization service

User session management for back-end servers

Parent topic: Deployment

Support for back-end server-side applications Support for back-end server-side applications applicationsupportback-end applicationssupportserver-side application supportiv-user headeriv-user-l headeriv-groups headeriv-creds headeriv-remote-address headeriv-remote-address-ipv6 headerWebSEAL supports server-side applications that run on back-end junctioned servers and require client identity information as input. Examples of server-side applications include: Java servletsCartridges for Oracle Web ListenerServer-side plug-insWhen you create a junction to a back-end server using the -c option, WebSEAL inserts Security Access Manager-specific client identity information into the HTTP headers of requests destined for that server. Security Access Manager-specific headers include:iv-useriv-user-liv-groupsiv-credsiv-remote-addressiv-remote-address-ipv6The Security Access Manager-specific HTTP header information enables applications on junctioned third-party servers to perform user-specific actions based on the client's Security Access Manager identity. For complete information on this topic, see:Client identity in HTTP headers (–c)Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers..Client IP addresses in HTTP headers (–r).Application integrationBest practices for standard junction usageCustom personalization serviceUser session management for back-end servers

Support for back-end server-side applications

WebSEAL supports server-side applications that run on back-end junctioned servers and require client identity information as input. Examples of server-side applications include:

Java™ servlets

Cartridges for Oracle Web Listener

Server-side plug-ins

When you create a junction to a back-end server using the -c option, WebSEAL inserts Security Access Manager-specific client identity information into the HTTP headers of requests destined for that server. Security Access Manager-specific headers include:

iv-user

iv-user-l

iv-groups

iv-creds

iv-remote-address

iv-remote-address-ipv6

The Security Access Manager-specific HTTP header information enables applications on junctioned third-party servers to perform user-specific actions based on the client's Security Access Manager identity.

For complete information on this topic, see:

Client identity in HTTP headers (–c).

Client IP addresses in HTTP headers (–r).

Parent topic: Application integration

Related concepts:

Custom personalization service

User session management for back-end servers

Related reference:

Best practices for standard junction usage

Best practices for standard junction usageBest practices for standard junction usagejunctionsbest practicesstandard junctionsbest practicesThis section includes best practices recommendations when using standard WebSEAL junctions in application integration.Application integrationSupport for back-end server-side applicationsCustom personalization serviceUser session management for back-end serversComplete Host header information with -vStandard absolute URL filtering

Best practices for standard junction usage

This section includes best practices recommendations when using standard WebSEAL junctions in application integration.

Complete Host header information with -v

Standard absolute URL filtering

Parent topic: Application integration

Related concepts:

Support for back-end server-side applications

Custom personalization service

User session management for back-end servers

Complete Host header information with -v Complete Host header information with -v Host headerbest practices for junctionsbest practicessupplying Host header information (-v)junctionsvirtual host name (-v)Host header best practices (-v)Virtual host configurations and portal applications require correct IP address information for proper socket connections, and complete server name information for accurate routing.These special back-end application services require complete server name and port designation information in any requests from browsers. The Host header of a request contains this information and makes it available to the application. When using WebSEAL junctions, this information is supplied to the Host header through the use of the –v junction option.Insufficient or missing server name and port information degrades the performance of virtual hosting and portal applications. In addition, domain cookies set by these applications might not contain sufficient information.To provide the most complete information to the Host header, the “best practices” recommendation is to always use both the fully qualified domain name of the junctioned server and the connection port number in the –v option when creating or adding the junction.The –v option uses the following syntax:-v fully-qualified-host-name[:port]For example:-v xyz.ibm.com:7001The port designation should be supplied only if you are using a non-standard port number.Best practices for standard junction usage

Complete Host header information with -v

Virtual host configurations and portal applications require correct IP address information for proper socket connections, and complete server name information for accurate routing.

These special back-end application services require complete server name and port designation information in any requests from browsers. The Host header of a request contains this information and makes it available to the application. When using WebSEAL junctions, this information is supplied to the Host header through the use of the –v junction option.

Insufficient or missing server name and port information degrades the performance of virtual hosting and portal applications. In addition, domain cookies set by these applications might not contain sufficient information.

To provide the most complete information to the Host header, the “best practices” recommendation is to always use both the fully qualified domain name of the junctioned server and the connection port number in the –v option when creating or adding the junction.

The –v option uses the following syntax:

-v fully-qualified-host-name[:port]

For example:

-v xyz.ibm.com:7001

Note: The port designation should be supplied only if you are using a non-standard port number.

Parent topic: Best practices for standard junction usage

Standard absolute URL filtering Standard absolute URL filtering absolute URL filteringbest practicesabsolute URL filteringfilterbest practices for absolute URLsWebSEAL, as a front-end reverse proxy, provides security services to back-end junctioned application servers. Pages returned to the client from back-end applications most often contain URL links to resources located on the back-end junctioned server. It is important that these links include the junction name to successfully direct the requests back to the correct locations of the resources. WebSEAL uses a set of standard rules to filter static URLs and supply this junction information. Additional configuration is required to filter URLs in scripts and dynamically generated URLs. For detailed information on URL filtering, see Modification of URLs to junctioned resources.WebSEAL's ability to properly filter absolute URLs from static HTML pages requires information about the server name provided in the –h junction option. This option provides WebSEAL with the name of the back-end junctioned server. Arguments to this option can include:Fully qualified domain name of the serverShort name of the serverIP address of the serverWebSEAL identifies absolute URLs to filter based on its knowledge of the back-end junctioned server name. Depending on your network environment, the –h short-name configuration might not provide WebSEAL with sufficient information.In the following example, a junction is created using the following option and argument for a back-end server, located in the ibm.com network, with a short name of “xyz”:-h xyzA link on an HTML page from this server appears as follows:http://xyz.ibm.com/doc/release-notes.htmlWhen this page passes to the client during a request, WebSEAL might fail to filter this URL because, based on the information provided by –h, it could not recognize “xyz.ibm.com” as the server name. Without the junction name in the path, a request for the release notes document fails. To support proper filtering of static absolute URLs, the “best practices” recommendation is to always use the fully qualified domain name of the junctioned server in the –h option when creating or adding the junction.Best practices for standard junction usage

Standard absolute URL filtering

WebSEAL, as a front-end reverse proxy, provides security services to back-end junctioned application servers. Pages returned to the client from back-end applications most often contain URL links to resources located on the back-end junctioned server.

It is important that these links include the junction name to successfully direct the requests back to the correct locations of the resources. WebSEAL uses a set of standard rules to filter static URLs and supply this junction information. Additional configuration is required to filter URLs in scripts and dynamically generated URLs. For detailed information on URL filtering, see Modification of URLs to junctioned resources.

WebSEAL's ability to properly filter absolute URLs from static HTML pages requires information about the server name provided in the –h junction option. This option provides WebSEAL with the name of the back-end junctioned server. Arguments to this option can include:

Fully qualified domain name of the server

Short name of the server

IP address of the server

WebSEAL identifies absolute URLs to filter based on its knowledge of the back-end junctioned server name. Depending on your network environment, the –h short-name configuration might not provide WebSEAL with sufficient information.

In the following example, a junction is created using the following option and argument for a back-end server, located in the ibm.com® network, with a short name of “xyz”:

-h xyz

A link on an HTML page from this server appears as follows:

http://xyz.ibm.com/doc/release-notes.html

When this page passes to the client during a request, WebSEAL might fail to filter this URL because, based on the information provided by –h, it could not recognize “xyz.ibm.com” as the server name. Without the junction name in the path, a request for the release notes document fails.

To support proper filtering of static absolute URLs, the “best practices” recommendation is to always use the fully qualified domain name of the junctioned server in the –h option when creating or adding the junction.

Parent topic: Best practices for standard junction usage

Custom personalization service Custom personalization service personalization serviceoverviewcustom personalization serviceThis section contains the following topics:Application integrationSupport for back-end server-side applicationsBest practices for standard junction usageUser session management for back-end serversPersonalization service conceptsConfiguring WebSEAL for a personalization servicePersonalization service example

Custom personalization service

This section contains the following topics:

Personalization service concepts

Configuring WebSEAL for a personalization service

Personalization service example

Parent topic: Application integration

Related concepts:

Support for back-end server-side applications

User session management for back-end servers

Related reference:

Best practices for standard junction usage

Personalization service conceptsPersonalization service conceptspersonalization serviceconceptsPD_PORTAL headerA Web portal, or launch page, is an integrated Web site service that dynamically produces a customized list of Web resources available to a specific user. Resources can include corporate content, support services, and learning tools. The portal output represents a personalized list of resources based on the access permissions for the particular user. The launch page displays only those resources that have the correct access permissions for that user.You can use WebSEAL configuration options and the authorization API entitlements service to build a custom portal solution in a Security Access Manager environment. The process flow for building a custom WebSEAL portal service includes the following tasks: Secure policies are formulated and attached at the appropriate points in the protected object resource.Appropriate explicit ACLs are attached to each of these resource objects.The WebSEAL configuration file is edited to include the URL to the portal service, the path of the object space containing the portal resources, and the permission bit required by the user for access to these resources.For each user request to the portal URL, WebSEAL uses the Authorization Entitlement Service to search this object space and produce a list of resources that meet the authorization conditions for that user.WebSEAL places this information in a PD_PORTAL HTTP header that is sent to the back-end (junctioned) portal server.The custom portal service (such as a CGI or servlet) located on the back-end server reads the PD_PORTAL header contents and, for example, maps the contents to descriptions and URL links that are displayed to the user on a Web page. This information represents the personalized list of resources available to the user based on access control permissions.Custom personalization service

Personalization service concepts

A Web portal, or launch page, is an integrated Web site service that dynamically produces a customized list of Web resources available to a specific user. Resources can include corporate content, support services, and learning tools. The portal output represents a personalized list of resources based on the access permissions for the particular user. The launch page displays only those resources that have the correct access permissions for that user.

You can use WebSEAL configuration options and the authorization API entitlements service to build a custom portal solution in a Security Access Manager environment.

The process flow for building a custom WebSEAL portal service includes the following tasks:

Secure policies are formulated and attached at the appropriate points in the protected object resource.

Appropriate explicit ACLs are attached to each of these resource objects.

The WebSEAL configuration file is edited to include the URL to the portal service, the path of the object space containing the portal resources, and the permission bit required by the user for access to these resources.

For each user request to the portal URL, WebSEAL uses the Authorization Entitlement Service to search this object space and produce a list of resources that meet the authorization conditions for that user.

WebSEAL places this information in a PD_PORTAL HTTP header that is sent to the back-end (junctioned) portal server.

The custom portal service (such as a CGI or servlet) located on the back-end server reads the PD_PORTAL header contents and, for example, maps the contents to descriptions and URL links that are displayed to the user on a Web page. This information represents the personalized list of resources available to the user based on access control permissions.

Parent topic: Custom personalization service

Configuring WebSEAL for a personalization service Configuring WebSEAL for a personalization service portal-map stanzapersonalization serviceWebSEAL configurationCreate a new WebSEAL junction to the personalization service. For example (entered as one line):pdadmin> server task server_name create -t tcp -h portalhost.abc.com /portal-jctEdit the WebSEAL configuration file to add a new [portal-map] stanza:[portal-map]The entry in this stanza identifies the server-relative URL of the portal service program and the region of the object space that is searched for available protected portal resources, followed by the permission required for access. This is the list that is placed in the PD_PORTAL header.[portal-map] URL = object_space_region:permissionAfter adding the stanza and the appropriate mapping entries, WebSEAL (webseald) must be re-started.Custom personalization service

Configuring WebSEAL for a personalization service

Procedure

Create a new WebSEAL junction to the personalization service. For example (entered as one line):

pdadmin> server task server_name create -t tcp -h portalhost.abc.com /portal-jct

Edit the WebSEAL configuration file to add a new [portal-map] stanza:

[portal-map]

The entry in this stanza identifies the server-relative URL of the portal service program and the region of the object space that is searched for available protected portal resources, followed by the permission required for access. This is the list that is placed in the PD_PORTAL header.

[portal-map]
URL = object_space_region:permission

After adding the stanza and the appropriate mapping entries, WebSEAL (webseald) must be re-started.

Parent topic: Custom personalization service

Personalization service example Personalization service example personalization serviceexamplesexamplespersonalization serviceCreate a junction to the portal server: pdadmin> server task web1-webseald-cruz -t ssl -h PORTAL1 /portalDefine the region of the WebSEAL protected object space that contains resources available to the personalization service: pdadmin> objectspace create /Resources “Portal Object Hierarchy” 10 pdadmin> object create /Resources/Content ““ 10 ispolicyattachable yes pdadmin> object create /Resources/Support ““ 10 ispolicyattachable yes pdadmin> object create /Resources/Content/CGI ““ 11 ispolicyattachable yes pdadmin> object create /Resources/Support/Servlet ““ 11 ispolicyattachable yes The “ispolicyattachable” argument must be set to “yes” for each resource. The search mechanism selects only qualified resource objects with explicitly set ACLs.WebSEAL configuration file: [portal-map] /portal/servlet/PortalServlet = /Resources:rPortal URL used by the user: https://WS1/portal/servlet/PortalServletCustom personalization service

Personalization service example

Create a junction to the portal server:

pdadmin> server task web1-webseald-cruz -t ssl -h PORTAL1 /portal

Define the region of the WebSEAL protected object space that contains resources available to the personalization service:

pdadmin> objectspace create /Resources “Portal Object Hierarchy” 10
pdadmin> object create /Resources/Content ““ 10 ispolicyattachable yes
pdadmin> object create /Resources/Support ““ 10 ispolicyattachable yes
pdadmin> object create /Resources/Content/CGI ““ 11 ispolicyattachable yes
pdadmin> object create /Resources/Support/Servlet ““ 11 ispolicyattachable yes

Note: The “ispolicyattachable” argument must be set to “yes” for each resource. The search mechanism selects only qualified resource objects with explicitly set ACLs.

WebSEAL configuration file:

[portal-map]
/portal/servlet/PortalServlet = /Resources:r

Portal URL used by the user:

https://WS1/portal/servlet/PortalServlet

Parent topic: Custom personalization service

User session management for back-end servers User session management for back-end servers user session ID managementback-end serverssession statebetween clients and back-end serversuser session ID managementWebSEAL can maintain session state with clients. You can configure WebSEAL to extend this session information to back-end junctioned application servers. Back-end applications can use session information to maintain session state with clients and terminate sessions.This section contains the following topics:Application integrationSupport for back-end server-side applicationsBest practices for standard junction usageCustom personalization serviceUser session management conceptsEnabling user session ID managementInserting user session data into HTTP headersTerminating user sessionsUser event correlation for back-end servers

User session management for back-end servers

WebSEAL can maintain session state with clients. You can configure WebSEAL to extend this session information to back-end junctioned application servers. Back-end applications can use session information to maintain session state with clients and terminate sessions.

This section contains the following topics:

User session management concepts

Enabling user session ID management

Inserting user session data into HTTP headers

Terminating user sessions

User event correlation for back-end servers

Parent topic: Application integration

Related concepts:

Support for back-end server-side applications

Custom personalization service

Related reference:

Best practices for standard junction usage

User session management conceptsUser session management conceptsuser session ID managementconceptssession IDWebSEAL session IDuser session IDA client/server session is a series of related communications between a single client and a server that take place over a period of time. With an established session, the server can identify the client associated with each request, and has the ability to remember—over numerous requests—a specific client. Without an established session, the communication between a client and a server might be renegotiated for each subsequent request. Session state information improves performance by eliminating repeated closing and re-opening of client/server sessions. The client can log in once and make numerous requests without performing a separate login for each request. The WebSEAL server has the ability to maintain session state with clients and to additionally extend this session information to junctioned back-end application servers.WebSEAL uses a session identification key, called the WebSEAL session ID, to maintain session state between the client and WebSEAL. The WebSEAL session ID serves as an index to the client's session data stored in the WebSEAL session cache. See WebSEAL session cache structure and Session cache configuration overview.A separate session identification key, called the user session ID, can be used to maintain session state between the client and a junctioned back-end application server. The user session ID uniquely identifies a specific session for an authenticated user and is stored as part of the user's credential information. Back-end applications can use user session IDs to track user sessions and terminate sessions. See Enabling user session ID management.Session managementSession managementA single user that logs in multiple times (for example, from different machines) has multiple WebSEAL session IDs and a credential for each session. The user session ID is based on the WebSEAL session ID (there exists a one-to-one mapping between the two keys). Therefore, a user session ID exists for each WebSEAL session ID. There are two configuration steps required to enable session management with the user session ID:Configure WebSEAL to store a unique user session ID for each authenticated client as an extended attribute in the credential of each client.Configure an extended attribute on a junction that can provide the value of this credential extended attribute (the user session ID) to a back-end application server in an HTTP header. User session management for back-end servers

User session management concepts

A client/server session is a series of related communications between a single client and a server that take place over a period of time. With an established session, the server can identify the client associated with each request, and has the ability to remember—over numerous requests—a specific client.

Without an established session, the communication between a client and a server might be renegotiated for each subsequent request. Session state information improves performance by eliminating repeated closing and re-opening of client/server sessions. The client can log in once and make numerous requests without performing a separate login for each request.

The WebSEAL server has the ability to maintain session state with clients and to additionally extend this session information to junctioned back-end application servers.

WebSEAL uses a session identification key, called the WebSEAL session ID, to maintain session state between the client and WebSEAL. The WebSEAL session ID serves as an index to the client's session data stored in the WebSEAL session cache. See WebSEAL session cache structure and Session cache configuration overview.

A separate session identification key, called the user session ID, can be used to maintain session state between the client and a junctioned back-end application server. The user session ID uniquely identifies a specific session for an authenticated user and is stored as part of the user's credential information.

Back-end applications can use user session IDs to track user sessions and terminate sessions. See Enabling user session ID management.

Figure 54. Session management

A single user that logs in multiple times (for example, from different machines) has multiple WebSEAL session IDs and a credential for each session. The user session ID is based on the WebSEAL session ID (there exists a one-to-one mapping between the two keys). Therefore, a user session ID exists for each WebSEAL session ID.

There are two configuration steps required to enable session management with the user session ID:

Configure WebSEAL to store a unique user session ID for each authenticated client as an extended attribute in the credential of each client.

Configure an extended attribute on a junction that can provide the value of this credential extended attribute (the user session ID) to a back-end application server in an HTTP header.

Parent topic: User session management for back-end servers

Enabling user session ID management Enabling user session ID management user session ID managementenablingtagvalue_user_session_iduser-session-idssession stateenabling user session ID managementuser-session-ids stanza entrytagvalue_user_session_id credential attributeextended attributestagvalue_user_session_idcredentialstagvalue_user_session_idtag-valuetagvalue_user_session_id The user-session-ids stanza entry in the [session] stanza of the WebSEAL configuration file allows you to enable and disable the creation of a unique user session ID as an extended attribute in the credential of each client making a request. The default value is "no" (disabled): [session] user-session-ids = no To enable the creation of unique user session IDs, set:[session] user-session-ids = yesThe unique user session ID is stored in a user's credential as an extended attribute with a name and value:(credential attribute) credential attribute credential attributetagvalue_user_session_id = user-session-id-stringThis extended attribute name always appears with a “tagvalue_” prefix to prevent any conflicts with other existing information in the credential.User session management for back-end servers

Enabling user session ID management

About this task

The user-session-ids stanza entry in the [session] stanza of the WebSEAL configuration file allows you to enable and disable the creation of a unique user session ID as an extended attribute in the credential of each client making a request. The default value is "no" (disabled):

[session]
user-session-ids = no

Procedure

To enable the creation of unique user session IDs, set:

[session]
user-session-ids = yes

The unique user session ID is stored in a user's credential as an extended attribute with a name and value:

(credential attribute)
credential attribute
credential attributetagvalue_user_session_id = user-session-id-string

This extended attribute name always appears with a “tagvalue_” prefix to prevent any conflicts with other existing information in the credential.

Parent topic: User session management for back-end servers

Inserting user session data into HTTP headersInserting user session data into HTTP headers tag-valueHTTP-Tag-Value junction attributecredentialsinserting user session ID in HTTP headersextended attributes (tag/value)user session ID managementinserting user session ID in HTTP headersHTTP-Tag-Value junction attributeextended attributesHTTP-Tag-Value (junction attribute)credentialsjunctionsHTTP-Tag-Value junction attributeTo provide a client's user session ID to the back-end application server, configure the HTTP-Tag-Value extended attribute on the junction. User session management for back-end serversSetting an extended attribute on a junctionThe HTTP-Tag-Value extended attribute for junctionsSetting the HTTP-Tag-Value junction attributeProcessing the HTTP-Tag-Value junction attribute

Inserting user session data into HTTP headers

To provide a client's user session ID to the back-end application server, configure the HTTP-Tag-Value extended attribute on the junction.

Setting an extended attribute on a junction

The HTTP-Tag-Value extended attribute for junctions

Setting the HTTP-Tag-Value junction attribute

Processing the HTTP-Tag-Value junction attribute

Parent topic: User session management for back-end servers

Setting an extended attribute on a junctionSetting an extended attribute on a junctionjunctionsextended attributeextended attributesjunctionIn general, an attribute enables the junction to perform some type of operation. You use the pdadmin object modify set attribute command to set an attribute on a junction object in the WebSEAL protected object space: pdadmin> object modify object_name set attribute attr_name attr_valueInserting user session data into HTTP headers

Setting an extended attribute on a junction

About this task

In general, an attribute enables the junction to perform some type of operation. You use the pdadmin object modify set attribute command to set an attribute on a junction object in the WebSEAL protected object space:

pdadmin> object modify object_name set attribute attr_name attr_value

Parent topic: Inserting user session data into HTTP headers

The HTTP-Tag-Value extended attribute for junctionsThe HTTP-Tag-Value extended attribute for junctionsHTTP-Tag-Valueextended attribute for junctionsThe HTTP-Tag-Value extended attribute specifically instructs WebSEAL to extract a value from an extended attribute in a user credential and send that value in an HTTP header across the junction to the back-end application server with each request. The HTTP-Tag-Value attribute:Identifies a specific extended attribute in the credential.Specifies the custom name of the HTTP header that will contain the value of this attribute.The HTTP-Tag-Value attribute uses the following format:credential_extended_attribute_name=http_header_nameAttribute components:credential_extended_attribute_name The name of the credential extended attribute that contains the user session ID is user_session_id. (The format used is the extended attribute name without the "tagvalue_" prefix.) The credential extended attribute name is not case-sensitive. http_header_name The http_header_name value specifies the custom name of the HTTP header used to deliver the user session ID across the junction. The example in this section uses a header called TAM-USER-SESSION-ID. Inserting user session data into HTTP headers

The HTTP-Tag-Value extended attribute for junctions

The HTTP-Tag-Value extended attribute specifically instructs WebSEAL to extract a value from an extended attribute in a user credential and send that value in an HTTP header across the junction to the back-end application server with each request.

The HTTP-Tag-Value attribute:

Identifies a specific extended attribute in the credential.

Specifies the custom name of the HTTP header that will contain the value of this attribute.

The HTTP-Tag-Value attribute uses the following format:

credential_extended_attribute_name=http_header_name

Attribute components:

credential_extended_attribute_name

The name of the credential extended attribute that contains the user session ID is user_session_id. (The format used is the extended attribute name without the "tagvalue_" prefix.)

The credential extended attribute name is not case-sensitive.

http_header_name

The http_header_name value specifies the custom name of the HTTP header used to deliver the user session ID across the junction.

The example in this section uses a header called TAM-USER-SESSION-ID.

Parent topic: Inserting user session data into HTTP headers

Setting the HTTP-Tag-Value junction attributeSetting the HTTP-Tag-Value junction attribute HTTP-Tag-Valueset attribute for junctionsjunctionsattributesAn example pdadmin command that sets an HTTP-Tag-Value junction attribute appears as follows (entered as one line): pdadmin> object modify /WebSEAL/junctionA set attribute HTTP-Tag-Value user_session_id=TAM-USER-SESSION-IDInserting user session data into HTTP headers

Setting the HTTP-Tag-Value junction attribute

About this task

An example pdadmin command that sets an HTTP-Tag-Value junction attribute appears as follows (entered as one line):

pdadmin> object modify /WebSEAL/junctionA set attribute
HTTP-Tag-Value user_session_id=TAM-USER-SESSION-ID

Parent topic: Inserting user session data into HTTP headers

Processing the HTTP-Tag-Value junction attributeProcessing the HTTP-Tag-Value junction attributeHTTP-Tag-Valueprocess junction attributesjunctionsattributesHTTP-Tag-Valueprocessingjunction attributes When WebSEAL processes a client request to a back-end application server, it looks for any attributes configured on the junction object. In this example, WebSEAL:Detects the HTTP-Tag-Value attribute.Looks at the credential of the user making the request.Extracts the user session ID value from the tagvalue_user_session_id extended attribute in the credential.Places the value in the TAM-USER-SESSION-ID HTTP header as:TAM-USER-SESSION-ID:user-session-id-stringIn summary:Name and value of the user session ID as it appears in the user credential: tagvalue_user_session_id:user-session-id-stringExample value of HTTP-Tag-Value attribute set on the junction object: user_session_id=TAM-USER-SESSION-IDResulting example HTTP header name and value: TAM-USER-SESSION-ID:user-session-id-stringInserting user session data into HTTP headers

Processing the HTTP-Tag-Value junction attribute

About this task

When WebSEAL processes a client request to a back-end application server, it looks for any attributes configured on the junction object.

In this example, WebSEAL:

Procedure

Detects the HTTP-Tag-Value attribute.

Looks at the credential of the user making the request.

Extracts the user session ID value from the tagvalue_user_session_id extended attribute in the credential.

Places the value in the TAM-USER-SESSION-ID HTTP header as:

TAM-USER-SESSION-ID:user-session-id-string

Results

In summary:

Name and value of the user session ID as it appears in the user credential:

tagvalue_user_session_id:user-session-id-string

Example value of HTTP-Tag-Value attribute set on the junction object:

user_session_id=TAM-USER-SESSION-ID

Resulting example HTTP header name and value:

TAM-USER-SESSION-ID:user-session-id-string

Parent topic: Inserting user session data into HTTP headers

Terminating user sessionsTerminating user sessionssession terminationuser sessionsterminationUsers can terminate their current session by using the pkmslogout command. Administrators, or back-end applications, can terminate user sessions using the information provided by the user session ID string. This section contains the following topics:User session management for back-end serversUser session ID string formatCompatibility with older user session ID formatTermination of single user sessionsAn administrator or a back-end application can use the Security Access Manager administration API to terminate a specific user session based on the user session ID. Termination of all user sessionsAn administrator or a back-end application can use the Security Access Manager administration API to call the pdadmin command that terminates all sessions for a specific user based on the user's login ID.

Terminating user sessions

Users can terminate their current session by using the pkmslogout command. Administrators, or back-end applications, can terminate user sessions using the information provided by the user session ID string. This section contains the following topics:

User session ID string format

Compatibility with older user session ID format

Termination of single user sessions
An administrator or a back-end application can use the Security Access Manager administration API to terminate a specific user session based on the user session ID.

Termination of all user sessions
An administrator or a back-end application can use the Security Access Manager administration API to call the pdadmin command that terminates all sessions for a specific user based on the user's login ID.

Parent topic: User session management for back-end servers

User session ID string formatUser session ID string formatuser session ID managementuser session ID string formatuser session ID string formatstringsformatThe format of the user session ID string consists of a MIME64-encoded WebSEAL server name and the user session ID for the client:encoded-webseal-server-name_user-session-idThe WebSEAL server name is the value specified by the server-name stanza entry in the [server] stanza of the WebSEAL configuration file.The user-session-id value is able to be directly used to provide the value of the user session ID in a pdadmin server task terminate session command. See Termination of single user sessionsAn administrator or a back-end application can use the Security Access Manager administration API to terminate a specific user session based on the user session ID. .Terminating user sessions

User session ID string format

The format of the user session ID string consists of a MIME64-encoded WebSEAL server name and the user session ID for the client:

encoded-webseal-server-name_user-session-id

The WebSEAL server name is the value specified by the server-name stanza entry in the [server] stanza of the WebSEAL configuration file.

The user-session-id value is able to be directly used to provide the value of the user session ID in a pdadmin server task terminate session command. See Termination of single user sessions.

Parent topic: Terminating user sessions

Compatibility with older user session ID formatCompatibility with older user session ID formatuser-session-ids-include-replica-set stanza entrysession terminationolder user session ID formatuser session ID managementolder user session ID formatBeginning with WebSEAL verion 6.0, the format of the user session ID value additionally includes the name of the replica set.The user-session-ids-include-replica-set stanza entry in the [session] stanza of the WebSEAL configuration file controls this operation. The default value is "yes". For example:[session] user-session-ids-include-replica-set = yesA value of "yes" instructs WebSEAL to include the replica set name in the user session ID value. This setting allows you to use the pdadmin server task terminate session to terminate user sessions on virtual host junctions.If you require user session ID compatibility with versions of WebSEAL prior to version 6.0, you can disable this function. For example:[session] user-session-ids-include-replica-set = noA value of "no" instructs WebSEAL to not include the replica set name in the user session ID value. If user-session-ids-include-replica-set = no, WebSEAL assumes that the pdadmin server task terminate session command applies to members of the replica set defined by the [session], standard-junction-replica-set stanza entry. The pdadmin server task terminate session command does not succeed for sessions initiated on virtual host junctions.To assign standard junctions to a replica set, see Assigning standard junctions to a replica setYou must configure the standard junction replica set for the distributed session cache..To assign virtual hosts to a replica set, see Virtual hosts assigned to a replica setIn contrast to standard junctions, virtual hosts can be individually assigned to different replica sets by using the -z option of the pdadmin server task virtualhost create command..Terminating user sessions

Compatibility with older user session ID format

Beginning with WebSEAL verion 6.0, the format of the user session ID value additionally includes the name of the replica set.

The user-session-ids-include-replica-set stanza entry in the [session] stanza of the WebSEAL configuration file controls this operation. The default value is "yes". For example:

[session]
user-session-ids-include-replica-set = yes

A value of "yes" instructs WebSEAL to include the replica set name in the user session ID value. This setting allows you to use the pdadmin server task terminate session to terminate user sessions on virtual host junctions.

If you require user session ID compatibility with versions of WebSEAL prior to version 6.0, you can disable this function. For example:

[session]
user-session-ids-include-replica-set = no

A value of "no" instructs WebSEAL to not include the replica set name in the user session ID value.

If user-session-ids-include-replica-set = no, WebSEAL assumes that the pdadmin server task terminate session command applies to members of the replica set defined by the [session], standard-junction-replica-set stanza entry.

The pdadmin server task terminate session command does not succeed for sessions initiated on virtual host junctions.

To assign standard junctions to a replica set, see Assigning standard junctions to a replica set.

To assign virtual hosts to a replica set, see Virtual hosts assigned to a replica set.

Parent topic: Terminating user sessions

Termination of single user sessions Termination of single user sessions An administrator or a back-end application can use the Security Access Manager administration API to terminate a specific user session based on the user session ID. terminationsingle user sessionssession stateterminationsingle user sessionssession cachetermination of single user sessionspdadmin server tasksession terminationfunctionalityterminationuser session ID managementtermination of single user sessionssession terminationtermination of single user sessionsSee User session ID string format to review the structure of the user session ID string.The pdadmin server task terminate session command is supported in a distributed session cache environment.The user_session_id portion of the user session ID string can be passed to the ivadmin_server_performtask() function. This function takes an input command string from the standard pdadmin server task terminate session command. For example:pdadmin> server task instance-webseald-host terminate session user_session_idThe WebSEAL instance name can be obtained from the HTTP iv_server_name header passed in every request.Although you can manually perform this pdadmin operation, the long value of the user_session_id can make this task cumbersome.WebSEAL verifies that the back-end server initiating the terminate operation has appropriate permissions before terminating the user's session. WebSEAL then removes the corresponding session cache entry so that the session is terminated.It is important to consider the conditions under which this command might be used. If the intent is to make sure that a user is removed from the secure domain entirely, the termination of a single user is only effective when, in addition, the account for that user is also made not valid (removed). Certain authentication methods—such as basic authentication, client-side certificate, LTPA cookies and failover cookies—return cached authentication information automatically with no user intervention. The pdadmin server task terminate session action would not prevent return logins for a user using any of those authentication methods. You must additionally invalidate the appropriate user account in the registry.Refer to the Administration C API Developer Reference for further information and for ivadmin_server_performtask() syntax.When a user is logged out unexpectedly because of session termination, the original session cookie remaining on the user's browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. When the user makes a subsequent request for a protected object, WebSEAL requires authentication and returns a login form. You can customize the login response to contain additional information that explains the reason for the new login requirement. For further information on this feature, see Customized responses for old session cookies.Terminating user sessions

Termination of single user sessions

An administrator or a back-end application can use the Security Access Manager administration API to terminate a specific user session based on the user session ID.

See User session ID string format to review the structure of the user session ID string.

Note: The pdadmin server task terminate session command is supported in a distributed session cache environment.

The user_session_id portion of the user session ID string can be passed to the ivadmin_server_performtask() function. This function takes an input command string from the standard pdadmin server task terminate session command. For example:

pdadmin> server task instance-webseald-host terminate session user_session_id

The WebSEAL instance name can be obtained from the HTTP iv_server_name header passed in every request.

Note: Although you can manually perform this pdadmin operation, the long value of the user_session_id can make this task cumbersome.

WebSEAL verifies that the back-end server initiating the terminate operation has appropriate permissions before terminating the user's session. WebSEAL then removes the corresponding session cache entry so that the session is terminated.

It is important to consider the conditions under which this command might be used. If the intent is to make sure that a user is removed from the secure domain entirely, the termination of a single user is only effective when, in addition, the account for that user is also made not valid (removed).

Certain authentication methods—such as basic authentication, client-side certificate, LTPA cookies and failover cookies—return cached authentication information automatically with no user intervention. The pdadmin server task terminate session action would not prevent return logins for a user using any of those authentication methods. You must additionally invalidate the appropriate user account in the registry.

Refer to the Administration C API Developer Reference for further information and for ivadmin_server_performtask() syntax.

When a user is logged out unexpectedly because of session termination, the original session cookie remaining on the user's browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. When the user makes a subsequent request for a protected object, WebSEAL requires authentication and returns a login form. You can customize the login response to contain additional information that explains the reason for the new login requirement. For further information on this feature, see Customized responses for old session cookies.

Parent topic: Terminating user sessions

Termination of all user sessions Termination of all user sessions An administrator or a back-end application can use the Security Access Manager administration API to call the pdadmin command that terminates all sessions for a specific user based on the user's login ID.terminationall user sessionssession stateterminationall user sessionssession cachetermination of all user sessionspdadmin server taskterminate all_sessionsuser session ID managementtermination of all user sessionssession terminationtermination of all user sessions For example:pdadmin> server task instance-webseald-host terminate all_sessions login_idThe pdadmin server task terminate all_sessions command is not supported in a distributed session cache environment. Use the dscadmin session terminate command instead.The user's login ID (login_id) can be passed to the junctioned back-end server in the Security Access Manager iv-user header. To accomplish this task, you must initially create the junction using the -c iv_user option and argument. See Client identity in HTTP headers (–c)Use the –c junction option to insert client identity, group membership, and credential information specific to Security Access Manager. You can insert the information into the HTTP headers of requests that are destined for junctioned third-party application servers.. The WebSEAL session cache is organized to cross-reference the user's login ID, the WebSEAL session ID, and other cache entry information. A user always has the same login ID across multiple sessions. Each WebSEAL session ID, however, is unique. The pdadmin server task terminate all_sessions command removes all cache entries belonging to a specific user's login ID.Terminate all userA sessionsTerminate all userA sessionsWebSEAL checks for appropriate permissions on the initiator of the pdadmin command before terminating user sessions.It is important to consider the conditions under which this command might be used. If the intent is to make sure a certain group of users are removed from the secure domain entirely, the pdadmin server task terminate all_sessions command is only effective when, in addition, the accounts for those users are made not valid (removed). Certain authentication methods—such as basic authentication, client-side certificate, LTPA cookies and failover cookies—return cached authentication information automatically with no user intervention. The pdadmin server task terminate all_sessions command would not prevent return logins for users using any of those authentication methods. You must additionally invalidate the appropriate user accounts in the registry.When a user is logged out unexpectedly because of session termination, the original session cookie remaining on the user's browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. When the user makes a subsequent request for a protected object, WebSEAL requires authentication and returns a login form. You can customize the login response to contain additional information that explains the reason for the new login requirement. For further information on this feature, see Customized responses for old session cookies.Terminating user sessions

Termination of all user sessions

An administrator or a back-end application can use the Security Access Manager administration API to call the pdadmin command that terminates all sessions for a specific user based on the user's login ID.

For example:

pdadmin> server task instance-webseald-host terminate all_sessions login_id

Note: The pdadmin server task terminate all_sessions command is not supported in a distributed session cache environment. Use the dscadmin session terminate command instead.

The user's login ID (login_id) can be passed to the junctioned back-end server in the Security Access Manager iv-user header. To accomplish this task, you must initially create the junction using the -c iv_user option and argument. See Client identity in HTTP headers (–c).

The WebSEAL session cache is organized to cross-reference the user's login ID, the WebSEAL session ID, and other cache entry information. A user always has the same login ID across multiple sessions. Each WebSEAL session ID, however, is unique. The pdadmin server task terminate all_sessions command removes all cache entries belonging to a specific user's login ID.

Figure 55. Terminate all userA sessions

WebSEAL checks for appropriate permissions on the initiator of the pdadmin command before terminating user sessions.

It is important to consider the conditions under which this command might be used. If the intent is to make sure a certain group of users are removed from the secure domain entirely, the pdadmin server task terminate all_sessions command is only effective when, in addition, the accounts for those users are made not valid (removed).

Certain authentication methods—such as basic authentication, client-side certificate, LTPA cookies and failover cookies—return cached authentication information automatically with no user intervention. The pdadmin server task terminate all_sessions command would not prevent return logins for users using any of those authentication methods. You must additionally invalidate the appropriate user accounts in the registry.

When a user is logged out unexpectedly because of session termination, the original session cookie remaining on the user's browser becomes an old, or "stale" cookie that no longer maps to an existing entry in the WebSEAL session cache. When the user makes a subsequent request for a protected object, WebSEAL requires authentication and returns a login form. You can customize the login response to contain additional information that explains the reason for the new login requirement. For further information on this feature, see Customized responses for old session cookies.

Parent topic: Terminating user sessions

User event correlation for back-end serversUser event correlation for back-end serversevent correlationback-end serversback-end serversevent correlationSometimes you must correlate individual events between WebSEAL and junctioned Web servers. A WebSEAL event can be uniquely identified by a combination of the session identifier and the transaction identifier.User session management for back-end serversInserting event correlation data into HTTP headersInserting event correlation data into the WebSEAL request logYou can use the request-log-format configuration entry to customize the contents of the WebSEAL request log to include event correlation data.

User event correlation for back-end servers

Sometimes you must correlate individual events between WebSEAL and junctioned Web servers. A WebSEAL event can be uniquely identified by a combination of the session identifier and the transaction identifier.

Inserting event correlation data into HTTP headers

Inserting event correlation data into the WebSEAL request log
You can use the request-log-format configuration entry to customize the contents of the WebSEAL request log to include event correlation data.

Parent topic: User session management for back-end servers

Inserting event correlation data into HTTP headersInserting event correlation data into HTTP headersdataevent correlationHTTP headersinserting event correlationFor information on how to insert the session identifier into the HTTP stream, see User session management for back-end servers. You can insert the transaction identifier into the HTTP stream using the WebSEAL HTTP-Tag-Value functionality. Use this function to insert elements from the user session into the HTTP stream. An extended attribute on a junction object in the WebSEAL protected object space defines the session elements that are included in the forwarded request. The pdadmin object modify set attribute command sets an attribute on an object: <pdadmin> object modify <object_name> set attribute <attr-name> <attr-value> The <attr-name> value should always be set to "HTTP-Tag-Value". The format of the <attr-value> should be: <session_data_name>=<http_header_name> To include the transaction identifier in the HTTP stream, set the <session_data_name> value to session:tid. The <http_header_name> value specifies the custom name of the HTTP header that delivers the transaction identifier across the junction. The following example shows the pdadmin command that sets an HTTP-Tag-Value junction attribute. Enter the command on one line. <pdadmin> object modify /WebSEAL/junctionA set attribute HTTP-Tag-Value session:tid=TAM-TRANSACTION-IDUser event correlation for back-end servers

Inserting event correlation data into HTTP headers

About this task

For information on how to insert the session identifier into the HTTP stream, see User session management for back-end servers.

You can insert the transaction identifier into the HTTP stream using the WebSEAL HTTP-Tag-Value functionality. Use this function to insert elements from the user session into the HTTP stream. An extended attribute on a junction object in the WebSEAL protected object space defines the session elements that are included in the forwarded request. The pdadmin object modify set attribute command sets an attribute on an object:

<pdadmin> object modify <object_name> set attribute <attr-name> <attr-value>

The <attr-name> value should always be set to "HTTP-Tag-Value". The format of the <attr-value> should be:

<session_data_name>=<http_header_name>

To include the transaction identifier in the HTTP stream, set the <session_data_name> value to session:tid. The <http_header_name> value specifies the custom name of the HTTP header that delivers the transaction identifier across the junction.

The following example shows the pdadmin command that sets an HTTP-Tag-Value junction attribute. Enter the command on one line.

<pdadmin> object modify /WebSEAL/junctionA
set attribute HTTP-Tag-Value session:tid=TAM-TRANSACTION-ID

Parent topic: User event correlation for back-end servers

Inserting event correlation data into the WebSEAL request logInserting event correlation data into the WebSEAL request logYou can use the request-log-format configuration entry to customize the contents of the WebSEAL request log to include event correlation data. dataevent correlationWebSEAL request logrequest logs Format specifiers define the contents of the log text. The following format specifiers add the event correlation data to the request log: DataFormat Specifiertransaction identifier%dsession identifier%{tagvalue_user_session_id}CFor more information, see request-log-format.User event correlation for back-end servers

Inserting event correlation data into the WebSEAL request log

You can use the request-log-format configuration entry to customize the contents of the WebSEAL request log to include event correlation data.

About this task

Format specifiers define the contents of the log text. The following format specifiers add the event correlation data to the request log:

Data | Format Specifier
transaction identifier | %d
session identifier | %{tagvalue_user_session_id}C

For more information, see request-log-format.

Parent topic: User event correlation for back-end servers

Dynamic URLsDynamic URLsdynamic URLsoverviewURLdynamicThis chapter discusses providing protection for dynamic URLs.Topic Index:DeploymentAccess control for dynamic URLsDynamic URL example: The Travel Kingdom

Dynamic URLs

This chapter discusses providing protection for dynamic URLs.

Topic Index:

Access control for dynamic URLs

Dynamic URL example: The Travel Kingdom

Parent topic: Deployment

Access control for dynamic URLs Access control for dynamic URLs dynamic URLsaccess controlaccesscontroldynamic URLsThe current Web environment gives users immediate access to rapidly changing information. Many Web applications dynamically generate Uniform Resource Locators (URLs) in response to each user request. These dynamic URLs usually exist only for a short time. Despite their temporary nature, dynamic URLs still need strong protection from unwanted use or access.Dynamic URLsDynamic URL example: The Travel KingdomDynamic URL componentsAccess control for dynamic URLs: dynurl.confWebSEAL uses the protected object space model, access control lists (ACL), and protected object policies (POP) to secure dynamically generated URLs, such as those generated by database requests. Conversion of POST body dynamic data to query string formatMapping ACL and POP objects to dynamic URLsCharacter encoding and query string validationUpdating WebSEAL for dynamic URLsResolve dynamic URLs in the object spaceConfiguration of limitations on POST requestsDynamic URLs summary and technical notes

Access control for dynamic URLs

The current Web environment gives users immediate access to rapidly changing information. Many Web applications dynamically generate Uniform Resource Locators (URLs) in response to each user request. These dynamic URLs usually exist only for a short time. Despite their temporary nature, dynamic URLs still need strong protection from unwanted use or access.

Dynamic URL components

Access control for dynamic URLs: dynurl.conf
WebSEAL uses the protected object space model, access control lists (ACL), and protected object policies (POP) to secure dynamically generated URLs, such as those generated by database requests.

Conversion of POST body dynamic data to query string format

Mapping ACL and POP objects to dynamic URLs

Character encoding and query string validation

Updating WebSEAL for dynamic URLs

Resolve dynamic URLs in the object space

Configuration of limitations on POST requests

Dynamic URLs summary and technical notes

Parent topic: Dynamic URLs

Related reference:

Dynamic URL example: The Travel Kingdom

Dynamic URL components Dynamic URL components dynamic URLsproviding access controlcomponentsoverviewSome Web application tools use dynamic URLs and hidden form elements to communicate requested operations (and values) to application servers. A dynamic URL augments the standard URL address with information about the specific operation and its values. The dynamic data (operations, parameters, and values) provided to the Web application interface are located in the query string portion of the request URL.Passing data in the query string of a request URLPassing data in the query string of a request URLAccess control for dynamic URLs

Dynamic URL components

Some Web application tools use dynamic URLs and hidden form elements to communicate requested operations (and values) to application servers. A dynamic URL augments the standard URL address with information about the specific operation and its values.

The dynamic data (operations, parameters, and values) provided to the Web application interface are located in the query string portion of the request URL.

Figure 56. Passing data in the query string of a request URL

Parent topic: Access control for dynamic URLs

Access control for dynamic URLs: dynurl.confAccess control for dynamic URLs: dynurl.confWebSEAL uses the protected object space model, access control lists (ACL), and protected object policies (POP) to secure dynamically generated URLs, such as those generated by database requests. dynamic URLsenablingdynurl.confdynurl.confLMIURL Mapping management pageEach request to WebSEAL is resolved to a specific object as the first step in the authorization process. An ACL or POP applied to the object dictates the required protection on any dynamic URL mapped to that object.Because dynamic URLs exist only temporarily, it is not possible to have entries for them in a pre-configured authorization policy database. Security Access Manager solves this problem by providing a mechanism where many dynamic URLs can be mapped to a single static protected object.Mappings from objects to patterns are kept in a plain text configuration file called dynurl.conf.You can use the LMI to manage the dynamic URL configuration file. Go to Secure Web Settings > Global Settings > URL mapping.The name of this file is defined by the dynurl-map stanza entry in the [server] stanza of the WebSEAL configuration file:[server] dynurl-map = dynurl.confYou must create this file; the file does not exist by default. The existence of this file (with entries) during WebSEAL startup enables the dynamic URL capability. Access control for dynamic URLs

Access control for dynamic URLs: dynurl.conf

WebSEAL uses the protected object space model, access control lists (ACL), and protected object policies (POP) to secure dynamically generated URLs, such as those generated by database requests.

Each request to WebSEAL is resolved to a specific object as the first step in the authorization process. An ACL or POP applied to the object dictates the required protection on any dynamic URL mapped to that object.

Because dynamic URLs exist only temporarily, it is not possible to have entries for them in a pre-configured authorization policy database. Security Access Manager solves this problem by providing a mechanism where many dynamic URLs can be mapped to a single static protected object.

Mappings from objects to patterns are kept in a plain text configuration file called dynurl.conf.

You can use the LMI to manage the dynamic URL configuration file. Go to Secure Web Settings > Global Settings > URL mapping.

The name of this file is defined by the dynurl-map stanza entry in the [server] stanza of the WebSEAL configuration file:

[server]
dynurl-map = dynurl.conf

You must create this file; the file does not exist by default.

The existence of this file (with entries) during WebSEAL startup enables the dynamic URL capability.

Parent topic: Access control for dynamic URLs

Conversion of POST body dynamic data to query string formatConversion of POST body dynamic data to query string formatGET requestsPOSTrequestsquery string formatdynamic URLsGET requestsPOST requestshanding dynamic data in URL query stringsWhen you map a URL regular expression to an object space entry, the query string format as produced from the GET request method must be used—regardless of the request method (POST or GET).In a GET request, the dynamic data (operations, parameters, and values) provided to the Web application interface are located in the query string portion of the request URL.In a POST request, the dynamic data (operations, parameters, and values) provided to the Web application interface are located in the request body.To maintain the required query string structure required for access control evaluation, the POST request body should be in the query string format, as is done with the default POST media type of application/x-www-form-urlencoded. For example, a POST request has the following request URL:http://server/login.formDynamic data (login information provided by the user) is located in the body of this POST request:name=ibm&password=secureTo achieve the query string structure required for dynamic URL evaluation, WebSEAL appends the POST body information to the request URL:http://server/login.form?name=ibm&password=secureIf the request body uses a different media type, such as multipart/form-data, and might include unencoded binary or reserved URL characters, the [server] suppress-dynurl-parsing-of-posts parameter should be set to 'yes'.Access control for dynamic URLs

Conversion of POST body dynamic data to query string format

When you map a URL regular expression to an object space entry, the query string format as produced from the GET request method must be used—regardless of the request method (POST or GET).

In a GET request, the dynamic data (operations, parameters, and values) provided to the Web application interface are located in the query string portion of the request URL.

In a POST request, the dynamic data (operations, parameters, and values) provided to the Web application interface are located in the request body.

To maintain the required query string structure required for access control evaluation, the POST request body should be in the query string format, as is done with the default POST media type of application/x-www-form-urlencoded. For example, a POST request has the following request URL:

http://server/login.form

Dynamic data (login information provided by the user) is located in the body of this POST request:

name=ibm&password=secure

To achieve the query string structure required for dynamic URL evaluation, WebSEAL appends the POST body information to the request URL:

http://server/login.form?name=ibm&password=secure

If the request body uses a different media type, such as multipart/form-data, and might include unencoded binary or reserved URL characters, the [server] suppress-dynurl-parsing-of-posts parameter should be set to 'yes'.

Parent topic: Access control for dynamic URLs

Mapping ACL and POP objects to dynamic URLs Mapping ACL and POP objects to dynamic URLs dynamic URLsmapping ACL objectsdynurl-mapdynurl-map stanza entryregular expressionsdynamic URLs To specify access control of dynamic URLs, create the dynurl.conf configuration file and edit the file to map resource objects to patterns. Entries in the file are of the format: object template Security Access Manager uses a subset of UNIX shell pattern matching (including wildcards) to define the set of parameters that constitute one object in the object space. Any dynamic URL that matches those parameters is mapped to that object. For a list of supported wildcard pattern matching characters, see Supported wildcard pattern matching charactersWebSEAL supports wildcard pattern matching characters.. The following example illustrates the form of a dynamic URL (from a GET request) that performs credit balance lookup: http://server-name/home-bank/owa/acct.bal?acc=account-number The object that represents this dynamic URL would appear as follows: http://server-name/home-bank/owa/acct.bal?acc=* Careful examination of the dynamic URL in this example shows that it describes a specific account number. The object for account balances at home-bank shows that the ACL and POP permissions apply to any account, because the last portion of the entry (acc=*) uses the asterisk wildcard which matches all characters. The following figure illustrates a complete scenario of a specific dynamic URL mapped to a specific protected object: Authorization on a dynamic URLAuthorization on a dynamic URLAccess control for dynamic URLs

Mapping ACL and POP objects to dynamic URLs

About this task

To specify access control of dynamic URLs, create the dynurl.conf configuration file and edit the file to map resource objects to patterns. Entries in the file are of the format:

object template

Security Access Manager uses a subset of UNIX shell pattern matching (including wildcards) to define the set of parameters that constitute one object in the object space. Any dynamic URL that matches those parameters is mapped to that object. For a list of supported wildcard pattern matching characters, see Supported wildcard pattern matching characters.

The following example illustrates the form of a dynamic URL (from a GET request) that performs credit balance lookup:

http://server-name/home-bank/owa/acct.bal?acc=account-number

The object that represents this dynamic URL would appear as follows:

http://server-name/home-bank/owa/acct.bal?acc=*

Careful examination of the dynamic URL in this example shows that it describes a specific account number. The object for account balances at home-bank shows that the ACL and POP permissions apply to any account, because the last portion of the entry (acc=*) uses the asterisk wildcard which matches all characters.

The following figure illustrates a complete scenario of a specific dynamic URL mapped to a specific protected object:

Figure 57. Authorization on a dynamic URL

Parent topic: Access control for dynamic URLs

Character encoding and query string validationCharacter encoding and query string validationdynamic URLscharacter encodingquery string validationcharacter encodingquery stringsvalidationWhen dynamic URL is enabled, WebSEAL maps the dynamic data in the query strings of requests to objects requiring protection (access control). If WebSEAL receives dynamic data (in a POST body or query string) using characters that are neither UTF-8 nor from the character set in which WebSEAL runs, WebSEAL rejects the request and returns an error.To securely map query strings to objects, the strings need to use the same character set known to WebSEAL and the back-end application server. Otherwise, dynamic URL access control could be circumvented by a request that uses a character accepted by the back-end application, but not accepted by WebSEAL. The dynamic URL feature is affected by the value of the decode-query stanza entry in the [server] stanza of the WebSEAL configuration file. If WebSEAL is configured to not validate query strings in requests (decode-query=no), then dynamic URL mapping for authorization checking, if enabled, must be disabled. WebSEAL will not start if this condition is not met.If WebSEAL (with dynamic URL enabled and decode-query=yes) is running in a non-UTF-8 environment, and request POST bodies (or query strings) contain UTF-8 characters, you can use the utf8-form-support-enabled stanza entry in the [server] stanza of the WebSEAL configuration file to allow WebSEAL to decode the UTF-8 coding in these requests. Access control for dynamic URLs

Character encoding and query string validation

When dynamic URL is enabled, WebSEAL maps the dynamic data in the query strings of requests to objects requiring protection (access control). If WebSEAL receives dynamic data (in a POST body or query string) using characters that are neither UTF-8 nor from the character set in which WebSEAL runs, WebSEAL rejects the request and returns an error.

To securely map query strings to objects, the strings need to use the same character set known to WebSEAL and the back-end application server. Otherwise, dynamic URL access control could be circumvented by a request that uses a character accepted by the back-end application, but not accepted by WebSEAL.

The dynamic URL feature is affected by the value of the decode-query stanza entry in the [server] stanza of the WebSEAL configuration file. If WebSEAL is configured to not validate query strings in requests (decode-query=no), then dynamic URL mapping for authorization checking, if enabled, must be disabled. WebSEAL will not start if this condition is not met.

If WebSEAL (with dynamic URL enabled and decode-query=yes) is running in a non-UTF-8 environment, and request POST bodies (or query strings) contain UTF-8 characters, you can use the utf8-form-support-enabled stanza entry in the [server] stanza of the WebSEAL configuration file to allow WebSEAL to decode the UTF-8 coding in these requests.

Parent topic: Access control for dynamic URLs

Updating WebSEAL for dynamic URLs Updating WebSEAL for dynamic URLs pdadmin server taskdynurl updatedynamic URLsupdatingdynurl updatedynurl updateUse the dynurl update command to update the WebSEAL protected object space with entries made in the dynurl.conf configuration file.Create, edit, or delete a dynamic URL entry in the dynurl.conf configuration file.After making your changes, use the dynurl update command to update the server: pdadmin> server task instance_name-webseald-host_name dynurl update The server-name argument represents the unqualified host name of the WebSEAL machine.Access control for dynamic URLs

Updating WebSEAL for dynamic URLs

Procedure

Use the dynurl update command to update the WebSEAL protected object space with entries made in the dynurl.conf configuration file.

Create, edit, or delete a dynamic URL entry in the dynurl.conf configuration file.

After making your changes, use the dynurl update command to update the server:

pdadmin> server task instance_name-webseald-host_name dynurl update

The server-name argument represents the unqualified host name of the WebSEAL machine.

Parent topic: Access control for dynamic URLs

Resolve dynamic URLs in the object space Resolve dynamic URLs in the object spacedynamic URLsresolvingobject spaceobject spacedynamic URLsResolving a dynamic URL to an object is dependent on the ordering of the entries in the dynurl.conf configuration file.When attempting to map a dynamic URL to an object entry, the list of mappings in the dynurl.conf file is scanned from top to bottom until the first matching pattern is found. When the first match is found, the corresponding object entry is used for the subsequent authorization check.If no matches are found, WebSEAL uses the URL itself, minus the http://server portion of the path.Keep the mappings that correspond to the most restrictive ACLs higher up in the list. For example, if the book.sales procedure of a sales order application is to be restricted to just a book club group, but the rest of the sales order application can be accessed by all users, then the mappings should be in the order shown in the following table: Object Space EntryURL Template/ows/sales/bksale/ows/db-apps/owa/book.sales*/ows/sales/general/ows/db-apps/owa/*Note that if the mapping entries were in the reverse order, all stored procedures in the /ows/db-apps/owa directory would map to the /ows/sales/general object. This could lead to possible breaches of security, due to this incorrect object space resolution. Access control for dynamic URLsACL and POP Evaluation

Resolve dynamic URLs in the object space

Resolving a dynamic URL to an object is dependent on the ordering of the entries in the dynurl.conf configuration file.

When attempting to map a dynamic URL to an object entry, the list of mappings in the dynurl.conf file is scanned from top to bottom until the first matching pattern is found. When the first match is found, the corresponding object entry is used for the subsequent authorization check.

If no matches are found, WebSEAL uses the URL itself, minus the http://server portion of the path.

Keep the mappings that correspond to the most restrictive ACLs higher up in the list. For example, if the book.sales procedure of a sales order application is to be restricted to just a book club group, but the rest of the sales order application can be accessed by all users, then the mappings should be in the order shown in the following table:

Object Space Entry | URL Template
/ows/sales/bksale | /ows/db-apps/owa/book.sales*
/ows/sales/general | /ows/db-apps/owa/*

Note that if the mapping entries were in the reverse order, all stored procedures in the /ows/db-apps/owa directory would map to the /ows/sales/general object. This could lead to possible breaches of security, due to this incorrect object space resolution.

ACL and POP Evaluation

Parent topic: Access control for dynamic URLs

ACL and POP Evaluation ACL and POP Evaluation evaluationACLPOPACLevaluationPOPevaluationAs soon as the dynamic URL has been resolved to an object space entry, the standard ACL or POP inheritance model is used to determine if the request should be processed or forbidden (due to insufficient privilege). Resolve dynamic URLs in the object space

ACL and POP Evaluation

As soon as the dynamic URL has been resolved to an object space entry, the standard ACL or POP inheritance model is used to determine if the request should be processed or forbidden (due to insufficient privilege).

Parent topic: Resolve dynamic URLs in the object space

Configuration of limitations on POST requests Configuration of limitations on POST requests dynamic URLsplacing limitations on POST requestsrequest-body-max-readdynurl-allow-large-postsPOSTrequestslimitationsmethodlimitationslimitationsPOST requestsrequest-body-max-read stanza entrydynurl-allow-large-posts stanza entryThe content of a POST request is contained in the body of the request. In addition, a POST request contains the browser-determined length of this content and lists the value in bytes. request-body-max-readThe request-body-max-read stanza entry in the [server] stanza of the WebSEAL configuration file limits the impact of large POST requests on WebSEAL by specifying the maximum number of bytes to read in as content from the body of POST requests. The content read in by WebSEAL is subject to authorization checks, as described earlier in this section.The request-body-max-read stanza entry value is considered when the POST request is used for dynamic URL processing or Forms authentication. The default value is 4096 bytes:[server] request-body-max-read = 4096Note that this stanza entry does not limit the maximum POST content size (which is unlimited). The stanza entry protects WebSEAL from processing a POST request of unreasonable size. For more information on modifying request-body-max-read, see Modification of request-body-max-readThe request-body-max-read stanza entry specifies the maximum number of bytes of content to read from the body of POST requests..dynurl-allow-large-postsAlthough the request-body-max-read stanza entry limits the amount of POST content read and processed by WebSEAL, it does not prevent the request, in its entirety, from being passed through to the application server. In this scenario, content that has not been validated is passed through to the application server. If the application server does not have its own authorization capabilities, the situation might result in a security risk.The dynurl-allow-large-posts stanza entry allows you to control the way WebSEAL handles POST requests that have a content length larger than that specified by request-body-max-read. If the stanza entry value is set to “no” (default), WebSEAL rejects, in total, any POST request with a content length larger than that specified by request-body-max-read.[server] dynurl-allow-large-posts = noIf the stanza entry value is set to “yes”, WebSEAL accepts the entire POST request, but only validates the amount of content equal to the request-body-max-read value.[server] dynurl-allow-large-posts = yesExample 1:A large POST request is received (greater than the request-body-max-read value).dynurl-allow-large-posts = noDynamic URLs are enabled.Result: 500 “Server Error”Example 2:A large POST request is received (greater than the post-request-body-max-read).dynurl-allow-large-posts = yesDynamic URLs are enabled.Result: WebSEAL compares the amount of content up to request-body-max-read with each of the regular expressions in the dynurl.conf configuration file, and performs an authorization check on the corresponding object if a match is found. Otherwise, the authorization check is performed on the object corresponding to the URL received, as usual. The portion of the request body past request-body-max-read is not validated.The following template contains the type of pattern matching arrangement that invites misuse by a large POST request: /rtpi153/webapp/examples/HitCount\?*action=reset*Access control for dynamic URLs

Configuration of limitations on POST requests

The content of a POST request is contained in the body of the request. In addition, a POST request contains the browser-determined length of this content and lists the value in bytes.

request-body-max-read

The request-body-max-read stanza entry in the [server] stanza of the WebSEAL configuration file limits the impact of large POST requests on WebSEAL by specifying the maximum number of bytes to read in as content from the body of POST requests. The content read in by WebSEAL is subject to authorization checks, as described earlier in this section.

The request-body-max-read stanza entry value is considered when the POST request is used for dynamic URL processing or Forms authentication. The default value is 4096 bytes:

[server]
request-body-max-read = 4096

Note that this stanza entry does not limit the maximum POST content size (which is unlimited). The stanza entry protects WebSEAL from processing a POST request of unreasonable size. For more information on modifying request-body-max-read, see Modification of request-body-max-read.

dynurl-allow-large-posts

Although the request-body-max-read stanza entry limits the amount of POST content read and processed by WebSEAL, it does not prevent the request, in its entirety, from being passed through to the application server. In this scenario, content that has not been validated is passed through to the application server. If the application server does not have its own authorization capabilities, the situation might result in a security risk.

The dynurl-allow-large-posts stanza entry allows you to control the way WebSEAL handles POST requests that have a content length larger than that specified by request-body-max-read. If the stanza entry value is set to “no” (default), WebSEAL rejects, in total, any POST request with a content length larger than that specified by request-body-max-read.

[server]
dynurl-allow-large-posts = no

If the stanza entry value is set to “yes”, WebSEAL accepts the entire POST request, but only validates the amount of content equal to the request-body-max-read value.

[server]
dynurl-allow-large-posts = yes

Example 1:

A large POST request is received (greater than the request-body-max-read value).

dynurl-allow-large-posts = no

Dynamic URLs are enabled.

Result: 500 “Server Error”

Example 2:

A large POST request is received (greater than the post-request-body-max-read).

dynurl-allow-large-posts = yes

Dynamic URLs are enabled.

Result: WebSEAL compares the amount of content up to request-body-max-read with each of the regular expressions in the dynurl.conf configuration file, and performs an authorization check on the corresponding object if a match is found. Otherwise, the authorization check is performed on the object corresponding to the URL received, as usual. The portion of the request body past request-body-max-read is not validated.

The following template contains the type of pattern matching arrangement that invites misuse by a large POST request:

/rtpi153/webapp/examples/HitCount\?*action=reset*

Parent topic: Access control for dynamic URLs

Dynamic URLs summary and technical notes Dynamic URLs summary and technical notes dynamic URLssummarytechnical notestechnical notesdynamic URLsAccess control for dynamic URLsSummaryThe following points summarize the WebSEAL configuration for securely handling dynamic URLs.Technical notes

Dynamic URLs summary and technical notes

Summary
The following points summarize the WebSEAL configuration for securely handling dynamic URLs.

Technical notes

Parent topic: Access control for dynamic URLs

SummarySummaryThe following points summarize the WebSEAL configuration for securely handling dynamic URLs.WebSEALconfigurationsummarysummary To configure WebSEAL to securely handle dynamic URLs, create a dynamic URL configuration file (such as dynurl.conf). In the LMI, go to Secure Web Settings > Global Settings > URL mapping to create this file.The file must contain one or more lines of the format: object templateIf the file does not exist at WebSEAL startup, or is empty, dynamic URL capability is not enabled.After the file has been processed, the object name appears as a child resource in the WebSEAL object space.The template can contain a subset of the standard pattern matching characters. The template can also be an exact string with no pattern matching characters.The following sample dynurl.conf file defines four objects representing some of the sample Web applications that are part of the IBM WebSphere product:Object EntryURL Template /app_showconfig /rtpi153/webapp/examples/ShowConfig* /app_snoop /rtpi153/servlet/snoop /app_snoop /rtpi025/servlet/snoop /app_hitcount/ejb /rtpi153/webapp/examples/HitCount\?source=EJB /app_hitcount /rtpi153/webapp/examples/HitCount*Dynamic URLs summary and technical notes

Summary

The following points summarize the WebSEAL configuration for securely handling dynamic URLs.

To configure WebSEAL to securely handle dynamic URLs, create a dynamic URL configuration file (such as dynurl.conf). In the LMI, go to Secure Web Settings > Global Settings > URL mapping to create this file.

The file must contain one or more lines of the format:

object template

If the file does not exist at WebSEAL startup, or is empty, dynamic URL capability is not enabled.

After the file has been processed, the object name appears as a child resource in the WebSEAL object space.

The template can contain a subset of the standard pattern matching characters. The template can also be an exact string with no pattern matching characters.

The following sample dynurl.conf file defines four objects representing some of the sample Web applications that are part of the IBM® WebSphere® product:

Object Entry
URL Template

/app_showconfig

/rtpi153/webapp/examples/ShowConfig*

/app_snoop

/rtpi153/servlet/snoop

/app_snoop

/rtpi025/servlet/snoop

/app_hitcount/ejb

/rtpi153/webapp/examples/HitCount\?source=EJB

/app_hitcount

/rtpi153/webapp/examples/HitCount*

Parent topic: Dynamic URLs summary and technical notes

Technical notesTechnical notestechnical notesoverviewMultiple URL templates can be mapped to the same object (for example, app_snoop maps to URLs on two different servers).Objects can be nested (for example, app_hitcount and app_hitcount/ejb).An incoming URL request is compared against templates in order, from top to bottom. When a match is found, processing stops. Therefore, place the more restrictive templates at the top of the file.To activate the definitions in the dynurl.conf file, issue the dynurl update command (use pdadmin server task). The update occurs immediately and the objects appear in the Web Portal Manager when you refresh the protected object space view.Avoid uppercase characters in the object name. Use lowercase characters only.Do not use an object name that already exists in the protected object space.Before deleting an object in the dynurl.conf file, remove any ACLs attached to the object.If WebSEAL receives a POST body that contains characters that are not UTF-8 or not from the character set (code page) used by WebSEAL, WebSEAL will reject the request.Because dynamic URL evaluation operates on all requests and uses character pattern matching, any requests containing binary data in the query string (GET) or request body (POST) is rejected with a 500 Server Error.Dynamic URLs summary and technical notes

Technical notes

Multiple URL templates can be mapped to the same object (for example, app_snoop maps to URLs on two different servers).

Objects can be nested (for example, app_hitcount and app_hitcount/ejb).

An incoming URL request is compared against templates in order, from top to bottom. When a match is found, processing stops. Therefore, place the more restrictive templates at the top of the file.

To activate the definitions in the dynurl.conf file, issue the dynurl update command (use pdadmin server task).

The update occurs immediately and the objects appear in the Web Portal Manager when you refresh the protected object space view.

Avoid uppercase characters in the object name. Use lowercase characters only.

Do not use an object name that already exists in the protected object space.

Before deleting an object in the dynurl.conf file, remove any ACLs attached to the object.

If WebSEAL receives a POST body that contains characters that are not UTF-8 or not from the character set (code page) used by WebSEAL, WebSEAL will reject the request.

Because dynamic URL evaluation operates on all requests and uses character pattern matching, any requests containing binary data in the query string (GET) or request body (POST) is rejected with a 500 Server Error.

Parent topic: Dynamic URLs summary and technical notes

Dynamic URL example: The Travel KingdomDynamic URL example: The Travel Kingdomdynamic URLsexampleThe Travel KingdomThe Travel KingdomTravel KingdomThe following fictitious example illustrates how a corporate intranet can secure URLs generated by an Oracle Web Listener.The dynamic URL Web server used in this example is the Oracle Web Listener. This technology can be applied equally to other dynamic URL Web servers.Dynamic URLsAccess control for dynamic URLsThe applicationThe interfaceThe dynamic URL example provides access to stored procedures in the database.The security policySecure clientsAccess controlThe dynamic URL example results in several access controls.Conclusion

Dynamic URL example: The Travel Kingdom

The following fictitious example illustrates how a corporate intranet can secure URLs generated by an Oracle Web Listener.

The dynamic URL Web server used in this example is the Oracle Web Listener. This technology can be applied equally to other dynamic URL Web servers.

The application

The interface
The dynamic URL example provides access to stored procedures in the database.

The security policy

Secure clients

Access control
The dynamic URL example results in several access controls.

Conclusion

Parent topic: Dynamic URLs

Related concepts:

Access control for dynamic URLs

The applicationThe applicationapplicationoverviewTravel Kingdom is an organization that offers clients a travel booking service over the Internet. The business intends to operate two Oracle database applications on its Web server — accessible across the Internet and from within the corporate firewall. Travel Booking System Authorized customers can make bookings remotely and query their own current bookings. Travel Kingdom staff can also make bookings for telephone customers, process changes, and perform many other transactions. Because external customers pay for services with credit cards, the transmission of that information must be strongly secured.Administration Manager Like most other companies, Travel Kingdom maintains an administration database containing salary, position, and experience information. This data is also accompanied by a photograph of each member of the staff.Dynamic URL example: The Travel Kingdom

The application

Travel Kingdom is an organization that offers clients a travel booking service over the Internet. The business intends to operate two Oracle database applications on its Web server — accessible across the Internet and from within the corporate firewall.

Travel Booking System

Authorized customers can make bookings remotely and query their own current bookings. Travel Kingdom staff can also make bookings for telephone customers, process changes, and perform many other transactions. Because external customers pay for services with credit cards, the transmission of that information must be strongly secured.

Administration Manager

Like most other companies, Travel Kingdom maintains an administration database containing salary, position, and experience information. This data is also accompanied by a photograph of each member of the staff.

Parent topic: Dynamic URL example: The Travel Kingdom

The interfaceThe interfaceThe dynamic URL example provides access to stored procedures in the database.interfacesoverviewAn Oracle Web Server is configured to provide access to the following stored procedures in the database: Stored procedures in the databaseStored procedureDescription/db-apps/owa/tr.browseGives all users the ability to inquire about travel destinations, prices, and so on./db-apps/owa/tr.bookUsed to place a booking (travel agent staff or authenticated customers)./db-apps/owa/tr.changeUsed to review or change current bookings./db-apps/owa/admin.browseUsed by any staff member to view unrestricted staff information, such as extension number, email address, and photograph./db-apps/owa/admin.resumeGives staff members the ability to view or change their own resume information in the Administration database./db-apps/owa/admin.updateUsed by Administration staff to update information on staff.Dynamic URL example: The Travel KingdomWeb space structure

The interface

The dynamic URL example provides access to stored procedures in the database.

An Oracle Web Server is configured to provide access to the following stored procedures in the database:

Table 74. Stored procedures in the database

Stored procedure
Description

/db-apps/owa/tr.browse

Gives all users the ability to inquire about travel destinations, prices, and so on.

/db-apps/owa/tr.book

Used to place a booking (travel agent staff or authenticated customers).

/db-apps/owa/tr.change

Used to review or change current bookings.

/db-apps/owa/admin.browse

Used by any staff member to view unrestricted staff information, such as extension number, email address, and photograph.

/db-apps/owa/admin.resume

Gives staff members the ability to view or change their own resume information in the Administration database.

/db-apps/owa/admin.update

Used by Administration staff to update information on staff.

Web space structure

Parent topic: Dynamic URL example: The Travel Kingdom

Web space structureWeb space structureweb space structureA WebSEAL server is used to provide a secure interface to the unified Web space of Travel Kingdom. A junction (/ows) is made to the Oracle Web Server running both the travel booking application and the administration application.The interfaceThe dynamic URL example provides access to stored procedures in the database.

Web space structure

A WebSEAL server is used to provide a secure interface to the unified Web space of Travel Kingdom.

A junction (/ows) is made to the Oracle Web Server running both the travel booking application and the administration application.

Parent topic: The interface

The security policyThe security policysecuritypoliciespoliciessecurityTo provide suitable security to Web resources, while retaining an easy-to-use system, the business has established the following security goals: Travel agent staff have complete control over all bookings.Authenticated customers can make and change their own bookings, but cannot interfere with the travel data of other authenticated customers.Administration staff have complete access to all of the administration information.Travel Kingdom staff other than the Administration department can change their own resume information and view partial information of other members of staff.Dynamic URL example: The Travel KingdomDynamic URL to object space mappings

The security policy

To provide suitable security to Web resources, while retaining an easy-to-use system, the business has established the following security goals:

Travel agent staff have complete control over all bookings.

Authenticated customers can make and change their own bookings, but cannot interfere with the travel data of other authenticated customers.

Administration staff have complete access to all of the administration information.

Travel Kingdom staff other than the Administration department can change their own resume information and view partial information of other members of staff.

Dynamic URL to object space mappings

Parent topic: Dynamic URL example: The Travel Kingdom

Dynamic URL to object space mappingsDynamic URL to object space mappingsdynamic URLsobject space mappingobject spacedynamic URLsTo achieve the security goals described above, the mappings from dynamic URLs to ACL object entries need to be configured as shown in the following table. Remember that the ordering of these mappings is an important part of achieving the security goals discussed earlier. Object Space EntryURL Pattern/ows/tr/browse/ows/db-apps/owa/tr.browse\?dest=*&date=??/??/????/ows/tr/auth/ows/db-apps/owa/tr.book\?dest=*&depart=??/??/????& return=??/??/????/ows/tr/auth/ows/db-apps/owa/tr.change/ows/admin/forall/ows/db-apps/owa/admin.resume/ows/admin/forall/ows/db-apps/owa/admin.browse\?empid=[th]???/ows/admin/auth/ows/db-apps/owa/admin.update\?empid=????The security policy

Dynamic URL to object space mappings

To achieve the security goals described above, the mappings from dynamic URLs to ACL object entries need to be configured as shown in the following table.

Remember that the ordering of these mappings is an important part of achieving the security goals discussed earlier.

Object Space Entry
URL Pattern

/ows/tr/browse

/ows/db-apps/owa/tr.browse\?dest=*&date=??/??/????

/ows/tr/auth

/ows/db-apps/owa/tr.book\?dest=*&depart=??/??/????& return=??/??/????

/ows/tr/auth

/ows/db-apps/owa/tr.change

/ows/admin/forall

/ows/db-apps/owa/admin.resume

/ows/admin/forall

/ows/db-apps/owa/admin.browse\?empid=[th]???

/ows/admin/auth

/ows/db-apps/owa/admin.update\?empid=????

Parent topic: The security policy

Secure clientsSecure clientsclientssecuresecure clientsClients authenticate to WebSEAL over a secure, encrypted channel. Customers who want to use the Web interface must additionally register with the Travel Kingdom Webmaster to receive an account.Dynamic URL example: The Travel KingdomAccount and group structure

Secure clients

Clients authenticate to WebSEAL over a secure, encrypted channel.

Customers who want to use the Web interface must additionally register with the Travel Kingdom Webmaster to receive an account.

Account and group structure

Parent topic: Dynamic URL example: The Travel Kingdom

Account and group structureAccount and group structurestructureaccountgroupFour groups are created on the system: StaffMembers of the Travel Kingdom organization.TKStaffTravel Kingdom travel agents.AdminStaffMembers of the Travel Kingdom Administration Department. Note that Administration staff members are also in the Staff group.CustomerCustomers of Travel Kingdom who want to make their travel bookings across the Internet.Each user is given an account in the secure domain to be individually identified by the WebSEAL server. The user’s identity is also passed to the Oracle Web Servers to provide a single signon solution to all of the Web resources.Secure clients

Account and group structure

Four groups are created on the system:

Staff

Members of the Travel Kingdom organization.

TKStaff

Travel Kingdom travel agents.

AdminStaff

Members of the Travel Kingdom Administration Department. Note that Administration staff members are also in the Staff group.

Customer

Customers of Travel Kingdom who want to make their travel bookings across the Internet.

Each user is given an account in the secure domain to be individually identified by the WebSEAL server. The user’s identity is also passed to the Oracle Web Servers to provide a single signon solution to all of the Web resources.

Parent topic: Secure clients

Access controlAccess controlThe dynamic URL example results in several access controls.accesscontroloverviewcontrolling accessThe following table lists the access controls resulting from application of the preceding information: Access controls for each object space entryObject space entryAccess/ows/tr/browseunauthenticated Tr any_authenticated Tr/ows/tr/authunauthenticated - any_other - group TKStaff Tr group Customer PTr/ows/admin/forall unauthenticated - any_other - group Staff Tr/ows/admin/authunauthenticated - any_other - group AdminStaff TrCustomers and TKStaff have the same privileges on the booking and travel plan maintenance objects, except that the customers must encrypt information (privacy permission) to give them further security when submitting sensitive data (such as credit card information) across the untrusted Internet.Dynamic URL example: The Travel Kingdom

Access control

The dynamic URL example results in several access controls.

The following table lists the access controls resulting from application of the preceding information:

Table 75. Access controls for each object space entry

Object space entry
Access

/ows/tr/browse

unauthenticated     Tr

any_authenticated     Tr

/ows/tr/auth

unauthenticated     -

any_other     -

group TKStaff     Tr

group Customer     PTr

/ows/admin/forall

unauthenticated     -

any_other     -

group Staff     Tr

/ows/admin/auth

unauthenticated     -

any_other     -

group AdminStaff     Tr

Customers and TKStaff have the same privileges on the booking and travel plan maintenance objects, except that the customers must encrypt information (privacy permission) to give them further security when submitting sensitive data (such as credit card information) across the untrusted Internet.

Parent topic: Dynamic URL example: The Travel Kingdom

Conclusion Conclusion single signonconclusionconclusionThis example illustrates the concepts of deploying a system capable of: Securing sensitive informationAuthenticating usersAuthorizing access to sensitive informationIn addition, the identities of the authenticated users of the system are known to both the WebSEAL and Oracle Web Servers, and are used to provide an auditable, single sign-on solution. Dynamic URL example: The Travel Kingdom

Conclusion

This example illustrates the concepts of deploying a system capable of:

Securing sensitive information

Authenticating users

Authorizing access to sensitive information

In addition, the identities of the authenticated users of the system are known to both the WebSEAL and Oracle Web Servers, and are used to provide an auditable, single sign-on solution.

Parent topic: Dynamic URL example: The Travel Kingdom

Internet Content Adaptation Protocol (ICAP) SupportInternet Content Adaptation Protocol (ICAP) SupportThe Internet Content Adaptation Protocol (ICAP) is designed to offload the processing of Internet-based content to dedicated servers. ICAP helps free up resources and standardize how features are implemented.internet content adaptation protocolICAPsupportWebSEALWebSEALICAPintegrationA proxy server, such as WebSEAL, can be configured to pass client requests and responses through ICAP servers. These ICAP servers can focus on specific, value-added services, and therefore be more efficient. For example, if an ICAP server handles language translation only, it might be more efficient than a web server that performs many additional tasks.ICAP is a "lightweight" HTTP-like protocol. ICAP clients can pass HTTP-based (HTML) messages or content to ICAP servers for adaptation. Adaptation refers to performing the particular value added service, such as content manipulation, for the associated client request or response. WebSEAL supports both TCP connections and SSL connections to the ICAP server. For more information, see Request For Comments (RFC) 3507 - Internet Content Adaptation Protocol (ICAP): http://www.ietf.org/rfc/rfc3507.txt. ExampleAdditional examples of ICAP server functions are: virus scanning, language translation, and content filtering.DeploymentICAP integration with WebSEAL - WorkflowScope of functionalityThe following information captures the scope of integrating ICAP with WebSEAL.Configuration of ICAP support within WebSEALThe configuration of ICAP support within WebSEAL is flexible and allows only those transactions that require the ICAP intervention to be sent to the ICAP servers.

Internet Content Adaptation Protocol (ICAP) Support

The Internet Content Adaptation Protocol (ICAP) is designed to offload the processing of Internet-based content to dedicated servers. ICAP helps free up resources and standardize how features are implemented.

A proxy server, such as WebSEAL, can be configured to pass client requests and responses through ICAP servers. These ICAP servers can focus on specific, value-added services, and therefore be more efficient. For example, if an ICAP server handles language translation only, it might be more efficient than a web server that performs many additional tasks.

ICAP is a "lightweight" HTTP-like protocol. ICAP clients can pass HTTP-based (HTML) messages or content to ICAP servers for adaptation. Adaptation refers to performing the particular value added service, such as content manipulation, for the associated client request or response.

WebSEAL supports both TCP connections and SSL connections to the ICAP server.

For more information, see Request For Comments (RFC) 3507 - Internet Content Adaptation Protocol (ICAP): http://www.ietf.org/rfc/rfc3507.txt.

Example

Additional examples of ICAP server functions are: virus scanning, language translation, and content filtering.

ICAP integration with WebSEAL - Workflow

Scope of functionality
The following information captures the scope of integrating ICAP with WebSEAL.

Configuration of ICAP support within WebSEAL
The configuration of ICAP support within WebSEAL is flexible and allows only those transactions that require the ICAP intervention to be sent to the ICAP servers.

Parent topic: Deployment

ICAP integration with WebSEAL - WorkflowICAP integration with WebSEAL - Workflowinternet content adaptation protocolICAPWebSEALWebSEALICAPintegrationA client request follows the path depicted in the diagram:A client sends a request to WebSEAL.WebSEAL passes the request to the ICAP server.The ICAP server uses the Internet Content Adaptation Protocol (ICAP) to generate a response and sends it back to WebSEAL. The response can be one of the following: A modified version of the request that is forwarded to other ICAP servers in the chain, or to the backend Web server.An HTTP response for this request that must then be sent back to the client.An error, which is processed by WebSEAL.The modified request is then sent to the backend Web server.A response is generated by the backend Web server.WebSEAL passes the response to the ICAP serverA response is generated by the ICAP server and sent back to WebSEAL. The response can be one of the following: A modified version of the response.An error.The response is sent to the client.Steps 2-3 and 6-7 can be repeated multiple times if multiple ICAP servers are configured.Internet Content Adaptation Protocol (ICAP) SupportThe Internet Content Adaptation Protocol (ICAP) is designed to offload the processing of Internet-based content to dedicated servers. ICAP helps free up resources and standardize how features are implemented.Scope of functionalityThe following information captures the scope of integrating ICAP with WebSEAL.Configuration of ICAP support within WebSEALThe configuration of ICAP support within WebSEAL is flexible and allows only those transactions that require the ICAP intervention to be sent to the ICAP servers.

ICAP integration with WebSEAL - Workflow

A client request follows the path depicted in the diagram:

A client sends a request to WebSEAL.

WebSEAL passes the request to the ICAP server.

The ICAP server uses the Internet Content Adaptation Protocol (ICAP) to generate a response and sends it back to WebSEAL. The response can be one of the following:

A modified version of the request that is forwarded to other ICAP servers in the chain, or to the backend Web server.

An HTTP response for this request that must then be sent back to the client.

An error, which is processed by WebSEAL.

The modified request is then sent to the backend Web server.

A response is generated by the backend Web server.

WebSEAL passes the response to the ICAP server

A response is generated by the ICAP server and sent back to WebSEAL. The response can be one of the following:

A modified version of the response.

An error.

The response is sent to the client.

Note: Steps 2-3 and 6-7 can be repeated multiple times if multiple ICAP servers are configured.

Parent topic: Internet Content Adaptation Protocol (ICAP) Support

Related concepts:

Configuration of ICAP support within WebSEAL

Related information

Scope of functionality

Scope of functionalityThe following information captures the scope of integrating ICAP with WebSEAL.functionalityscopescope of functionalityWebSEAL provides support for:Request for modification (REQMOD)Request for response (RESPMOD)WebSEAL does not support the following optional aspects of ICAP RFC 3507:Message preview"204 No Content" Responses outside of previewsOPTIONS methodCachingAuthenticationEncryptionSee the ICAP RFC 3507: http://www.ietf.org/rfc/rfc3507.txt for more information on each of the aspects.Internet Content Adaptation Protocol (ICAP) SupportThe Internet Content Adaptation Protocol (ICAP) is designed to offload the processing of Internet-based content to dedicated servers. ICAP helps free up resources and standardize how features are implemented.ICAP integration with WebSEAL - WorkflowConfiguration of ICAP support within WebSEALThe configuration of ICAP support within WebSEAL is flexible and allows only those transactions that require the ICAP intervention to be sent to the ICAP servers.

Scope of functionality

The following information captures the scope of integrating ICAP with WebSEAL.

WebSEAL provides support for:

Request for modification (REQMOD)

Request for response (RESPMOD)

WebSEAL does not support the following optional aspects of ICAP RFC 3507:

Message preview

"204 No Content" Responses outside of previews

OPTIONS method

Caching

Authentication

Encryption

Note: See the ICAP RFC 3507: http://www.ietf.org/rfc/rfc3507.txt for more information on each of the aspects.

Parent topic: Internet Content Adaptation Protocol (ICAP) Support

Related concepts:

ICAP integration with WebSEAL - Workflow

Configuration of ICAP support within WebSEAL

Configuration of ICAP support within WebSEALConfiguration of ICAP support within WebSEALThe configuration of ICAP support within WebSEAL is flexible and allows only those transactions that require the ICAP intervention to be sent to the ICAP servers. internet content adaptation protocolICAPconfigurationWebSEALWebSEALICAPconfigurationAn Administrator can configure and control the applications that require ICAP processing. Configuration of ICAP support within WebSEAL consists of two parts:Configuration file: Used to define ICAP servers.Protected Object Policy (POP): Used to define the resources that trigger a call to the ICAP servers.Configuration fileA stanza entry called [ICAP: <resource>] is added to the configuration file. The stanza entry is used to define the different ICAP resources. Each resource consists of:A URL for the ICAP server, which defines the ICAP server's address and whether TCP or SSL is used for the connection. When an SSL connection is defined, the system uses the keystore that is configured in the [junction] stanza if it exists. If not, the system uses the keystore that is configured in the [ssl] stanza.A transaction list that defines whether the ICAP server is used in processing the HTTP request or response.A timeout value that defines the maximum length of time (in seconds) that WebSEAL waits for a response from the ICAP server.An optional SSL keyfile label that defines the certificate to be used if client certificate authentication is required.For more information, see [ICAP:<resource>] stanzaUse the [ICAP:<resource>] stanza to define a single ICAP resource. .The <resource> in the stanza name corresponds to the name of the resource in the POP. Multiple resources might be specified in the configuration file.Example[ICAP:resource_a] URL = icap://icap_svr.tivoli.com:1344/ transaction = req timeout = 120 [ICAP:resource_b] URL = icap://icap_svr.tivoli.com:1344/ transaction = rsp timeout = 120 The preceding example establishes a TCP connection to the ICAP server. If you want to use an SSL connection to the ICAP server, use icaps:// instead of icap://. You can also specify an SSL keyfile label that defines the certificate to be used if client certificate authentication is required. [ICAP:resource_a] URL = icaps://icap_svr.tivoli.com:1345/ transaction = req timeout = 120 [ICAP:resource_b] URL = icaps://icap_svr.tivoli.com:1345/ transaction = rsp timeout = 120 ssl-keyfile-label = my_certificateProtected Object Policy (POP)A Protected Object Policy (POP) is used to enable the pre-defined ICAP resource for appropriate parts of the object space. This mechanism provides full control over which resources incur the additional impact of the ICAP processing. The POP must have: An extended attribute created with the name 'ICAP', andA value that matches the name of one of the configured ICAP resources.Multiple attributes of the same name can be created if multiple ICAP servers are required to handle the processing of a particular object or request.The following example shows what the POP might look like:pdadmin sec_master> pop show ICAPPop attribute ICAP ICAP resource_a resource_bresource_a and resource_b correspond to the following configuration stanzas: [ICAP:resource_a] and [ICAP:resource_b].Internet Content Adaptation Protocol (ICAP) SupportThe Internet Content Adaptation Protocol (ICAP) is designed to offload the processing of Internet-based content to dedicated servers. ICAP helps free up resources and standardize how features are implemented.ICAP integration with WebSEAL - WorkflowScope of functionalityThe following information captures the scope of integrating ICAP with WebSEAL.

Configuration of ICAP support within WebSEAL

The configuration of ICAP support within WebSEAL is flexible and allows only those transactions that require the ICAP intervention to be sent to the ICAP servers.

An Administrator can configure and control the applications that require ICAP processing. Configuration of ICAP support within WebSEAL consists of two parts:

Configuration file: Used to define ICAP servers.

Protected Object Policy (POP): Used to define the resources that trigger a call to the ICAP servers.

Configuration file

A stanza entry called [ICAP: <resource>] is added to the configuration file. The stanza entry is used to define the different ICAP resources. Each resource consists of:

A URL for the ICAP server, which defines the ICAP server's address and whether TCP or SSL is used for the connection. When an SSL connection is defined, the system uses the keystore that is configured in the [junction] stanza if it exists. If not, the system uses the keystore that is configured in the [ssl] stanza.

A transaction list that defines whether the ICAP server is used in processing the HTTP request or response.

A timeout value that defines the maximum length of time (in seconds) that WebSEAL waits for a response from the ICAP server.

An optional SSL keyfile label that defines the certificate to be used if client certificate authentication is required.

For more information, see [ICAP:<resource>] stanza.

Note: The <resource> in the stanza name corresponds to the name of the resource in the POP. Multiple resources might be specified in the configuration file.

Example

[ICAP:resource_a]
URL = icap://icap_svr.tivoli.com:1344/
transaction = req
timeout = 120
[ICAP:resource_b]
URL = icap://icap_svr.tivoli.com:1344/
transaction = rsp
timeout = 120

Note: The preceding example establishes a TCP connection to the ICAP server. If you want to use an SSL connection to the ICAP server, use "icaps://" instead of "icap://". You can also specify an SSL keyfile label that defines the certificate to be used if client certificate authentication is required.

[ICAP:resource_a]
URL = icaps://icap_svr.tivoli.com:1345/
transaction = req
timeout = 120
[ICAP:resource_b]
URL = icaps://icap_svr.tivoli.com:1345/
transaction = rsp
timeout = 120
ssl-keyfile-label = my_certificate

Protected Object Policy (POP)

A Protected Object Policy (POP) is used to enable the pre-defined ICAP resource for appropriate parts of the object space. This mechanism provides full control over which resources incur the additional impact of the ICAP processing. The POP must have:

An extended attribute created with the name 'ICAP', and

A value that matches the name of one of the configured ICAP resources.

Multiple attributes of the same name can be created if multiple ICAP servers are required to handle the processing of a particular object or request.

The following example shows what the POP might look like:

pdadmin sec_master> pop show ICAPPop attribute ICAP
    ICAP
        resource_a
        resource_b

Note: resource_a and resource_b correspond to the following configuration stanzas: [ICAP:resource_a] and [ICAP:resource_b].

Parent topic: Internet Content Adaptation Protocol (ICAP) Support

Related concepts:

ICAP integration with WebSEAL - Workflow

Related information

Scope of functionality

Authorization decision information retrievalAuthorization decision information retrievalauthorization decision informationADIinformationretrievalADIretrievaloverviewThe following topics describe how WebSEAL can provide, or acquire, authorization decision information (ADI) required to evaluate authorization rules that protect resources in the Security Access Manager domain.Web Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Overview of ADI retrievalADI retrieval from the WebSEAL client requestADI retrieval from the user credentialSupplying a failure reason across a junctionDynamic ADI retrievalConfiguring WebSEAL to use the attribute retrieval service

Authorization decision information retrieval

The following topics describe how WebSEAL can provide, or acquire, authorization decision information (ADI) required to evaluate authorization rules that protect resources in the Security Access Manager domain.

Overview of ADI retrieval

ADI retrieval from the WebSEAL client request

ADI retrieval from the user credential

Supplying a failure reason across a junction

Dynamic ADI retrieval

Configuring WebSEAL to use the attribute retrieval service

Parent topic: Web Reverse Proxy configuration

Overview of ADI retrievalOverview of ADI retrievalADIretrievaloverviewauthorization rules evaluatorThe Security Access Manager authorization rules evaluator performs authorization decisions based on Boolean logic applied to specific authorization decision information (ADI). You can find detailed information about the construction of authorization rules (using Boolean logic) and ADI in the Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. topics. ADI required for rules evaluation can be retrieved from the following sources:Authorization decision parameters provided to the authorization rule as ADI by the authorization service. Parameters include the target resource (protected object) and the requested action on the resource. See the Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. topics for further information about this topic.The user credential. The user credential is always included with the function call to the authorization rules evaluator, so it is immediately available.The resource manager environment (application context). A resource manager, such as WebSEAL, can be configured to provide ADI from its own environment. For example, WebSEAL can provide ADI contained in parts of the client request. A special prefix is used in the authorization rule to "trigger" this type of ADI source.An external source through the Security Access Manager attribute retrieval service. ADI can be obtained externally through the attribute retrieval service. The entitlement service of the resource manager makes a call to the attribute retrieval service. ADI from the external source is returned in XML format to the authorization rules evaluator.The attribute retrieval service is deprecated. IBM might remove this capability in a subsequent release of the product.Authorization decision information retrievalADI retrieval from the WebSEAL client requestADI retrieval from the user credentialSupplying a failure reason across a junctionDynamic ADI retrievalConfiguring WebSEAL to use the attribute retrieval service

Overview of ADI retrieval

The Security Access Manager authorization rules evaluator performs authorization decisions based on Boolean logic applied to specific authorization decision information (ADI). You can find detailed information about the construction of authorization rules (using Boolean logic) and ADI in the Access Manager Platform and Supporting Components administration topics.

ADI required for rules evaluation can be retrieved from the following sources:

Authorization decision parameters provided to the authorization rule as ADI by the authorization service.

Parameters include the target resource (protected object) and the requested action on the resource. See the Access Manager Platform and Supporting Components administration topics for further information about this topic.

The user credential.

The user credential is always included with the function call to the authorization rules evaluator, so it is immediately available.

The resource manager environment (application context).

A resource manager, such as WebSEAL, can be configured to provide ADI from its own environment. For example, WebSEAL can provide ADI contained in parts of the client request. A special prefix is used in the authorization rule to "trigger" this type of ADI source.

An external source through the Security Access Manager attribute retrieval service.

ADI can be obtained externally through the attribute retrieval service. The entitlement service of the resource manager makes a call to the attribute retrieval service. ADI from the external source is returned in XML format to the authorization rules evaluator.

Note: The attribute retrieval service is deprecated. IBM® might remove this capability in a subsequent release of the product.

Parent topic: Authorization decision information retrieval

Related concepts:

ADI retrieval from the WebSEAL client request

ADI retrieval from the user credential

Dynamic ADI retrieval

Related tasks:

Supplying a failure reason across a junction

Configuring WebSEAL to use the attribute retrieval service

ADI retrieval from the WebSEAL client requestADI retrieval from the WebSEAL client requestADIretrievalWebSEAL clientaznapi-configuration-stanzaresource-manager-provided-adiAMWS_hd_prefixAMWS_qs_prefixAMWS_pb_prefixresource-manager-provided-adi stanza entryaznapi-configuration stanzapermission-info-returned stanza entryIn a WebSEAL environment, authorization rules can be written to require authorization decision information (ADI) contained in the client HTTP/HTTPS request. ADI can be contained in the request header, the request query string, and the request POST body. Authorization decision information is referred to by an XML container name in authorization rules. A special WebSEAL-specific prefix in the container name is used to alert the authorization rules evaluation process that WebSEAL can interpret this parameter correctly and return a value. Prefixes can be specific to any resource manager. Accordingly, the resource manager must be designed to respond appropriately to a request for ADI. The following container names contain prefixes that are appropriate for WebSEAL: AMWS_hd_name Request header container name. The value of the HTTP header called name in the HTTP request is returned to the authorization rules evaluator as ADI.AMWS_qs_name Request query string container name. The value of name in the request query string is returned to the authorization rules evaluator as ADI.AMWS_pb_name Request POST body container name. The value of name in the request POST body is returned to the authorization rules evaluator as ADI.The following process flow helps illustrate how prefixes enable the extraction of ADI from client requests:An authorization rule is written that requires ADI from the client request (for example, a specific HTTP header in the request). In this example, the AMWS_hd_ prefix is used in the container name specified in the rule. The prefix must be specified by the resource-manager-provided-adi stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file. The authorization service incorporates this configuration information during its initialization. This WebSEAL-specific prefix alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI. The authorization rules evaluation process tries to evaluate, for example, the AMWS_hd_host container name in a rule. The AMWS_hd_ prefix alerts the authorization evaluation process that WebSEAL can interpret this container name correctly and return a value.The AMWS_hd_host container name is sent to WebSEAL. WebSEAL is designed to recognize and interpret the AMWS_hd_ prefix.WebSEAL responds to the AMWS_hd_host container name by looking for the "host" header in the client request and extracting the value associated with that header.WebSEAL returns the "host" header value (as an XML container) to the authorization rules evaluation process.The authorization rules evaluation process uses the value as ADI in its evaluation of the rule.The resource-manager-provided-adi stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file specifies—to the authorization rules evaluation process— the prefixes that can be used in container names specified by authorization rules. To specify multiple prefixes, use multiple entries of the resource-manager-provided-adi stanza entry:[aznapi-configuration] resource-manager-provided-adi = AMWS_qs_ resource-manager-provided-adi = AMWS_pb_ resource-manager-provided-adi = AMWS_hd_The permission-info-returned stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file appears by default. This stanza entry specifies the permission information returned to the resource manager (for example, WebSEAL) from the authorization service. The following example is entered as one line, with a single space separating the two permission types:[aznapi-configuration] permission-info-returned = azn_perminfo_rules_adi_request azn_perminfo_reason_rule_failedThe azn_perminfo_rules_adi_request setting allows the authorization service to request ADI from the current WebSEAL client request. The azn_perminfo_reason_rule_failed setting specifies that rule failure reasons be returned to the resource manager (this setting is required for –R junctions—see Supplying a failure reason across a junction).Authorization decision information retrievalOverview of ADI retrievalADI retrieval from the user credentialSupplying a failure reason across a junctionDynamic ADI retrievalConfiguring WebSEAL to use the attribute retrieval serviceExample: Retrieving ADI from the request headerExample: Retrieving ADI from the request query stringExample: Retrieving ADI from the request POST body

ADI retrieval from the WebSEAL client request

In a WebSEAL environment, authorization rules can be written to require authorization decision information (ADI) contained in the client HTTP/HTTPS request. ADI can be contained in the request header, the request query string, and the request POST body.

Authorization decision information is referred to by an XML container name in authorization rules. A special WebSEAL-specific prefix in the container name is used to alert the authorization rules evaluation process that WebSEAL can interpret this parameter correctly and return a value.

Prefixes can be specific to any resource manager. Accordingly, the resource manager must be designed to respond appropriately to a request for ADI.

The following container names contain prefixes that are appropriate for WebSEAL:

AMWS_hd_name

Request header container name. The value of the HTTP header called name in the HTTP request is returned to the authorization rules evaluator as ADI.

AMWS_qs_name

Request query string container name. The value of name in the request query string is returned to the authorization rules evaluator as ADI.

AMWS_pb_name

Request POST body container name. The value of name in the request POST body is returned to the authorization rules evaluator as ADI.

The following process flow helps illustrate how prefixes enable the extraction of ADI from client requests:

An authorization rule is written that requires ADI from the client request (for example, a specific HTTP header in the request).

In this example, the AMWS_hd_ prefix is used in the container name specified in the rule. The prefix must be specified by the resource-manager-provided-adi stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file. The authorization service incorporates this configuration information during its initialization. This WebSEAL-specific prefix alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.

The authorization rules evaluation process tries to evaluate, for example, the AMWS_hd_host container name in a rule. The AMWS_hd_ prefix alerts the authorization evaluation process that WebSEAL can interpret this container name correctly and return a value.

The AMWS_hd_host container name is sent to WebSEAL.

WebSEAL is designed to recognize and interpret the AMWS_hd_ prefix.

WebSEAL responds to the AMWS_hd_host container name by looking for the "host" header in the client request and extracting the value associated with that header.

WebSEAL returns the "host" header value (as an XML container) to the authorization rules evaluation process.

The authorization rules evaluation process uses the value as ADI in its evaluation of the rule.

The resource-manager-provided-adi stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file specifies—to the authorization rules evaluation process— the prefixes that can be used in container names specified by authorization rules. To specify multiple prefixes, use multiple entries of the resource-manager-provided-adi stanza entry:

[aznapi-configuration]
resource-manager-provided-adi = AMWS_qs_
resource-manager-provided-adi = AMWS_pb_
resource-manager-provided-adi = AMWS_hd_

The permission-info-returned stanza entry in the [aznapi-configuration] stanza of the WebSEAL configuration file appears by default. This stanza entry specifies the permission information returned to the resource manager (for example, WebSEAL) from the authorization service. The following example is entered as one line, with a single space separating the two permission types:

[aznapi-configuration]
permission-info-returned = azn_perminfo_rules_adi_request
azn_perminfo_reason_rule_failed

The azn_perminfo_rules_adi_request setting allows the authorization service to request ADI from the current WebSEAL client request. The azn_perminfo_reason_rule_failed setting specifies that rule failure reasons be returned to the resource manager (this setting is required for –R junctions—see Supplying a failure reason across a junction).

Example: Retrieving ADI from the request header

Example: Retrieving ADI from the request query string

Example: Retrieving ADI from the request POST body

Parent topic: Authorization decision information retrieval

Related concepts:

Overview of ADI retrieval

ADI retrieval from the user credential

Dynamic ADI retrieval

Related tasks:

Supplying a failure reason across a junction

Configuring WebSEAL to use the attribute retrieval service

Example: Retrieving ADI from the request headerExample: Retrieving ADI from the request headerADIretrievalrequest headersretrieving ADIrequest headersrequestsheadersThe following example authorization rule requires the name of the Internet host and port number of the resource being requested. (If port number is omitted, the default port for the requested service is used; for example, port 80 is used for an HTTP URL.) The client request is set up to include the host name value in the "host" header of the request. The use of the AMWS_hd_ prefix in the rule alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.<xsl:if test='AMWS_hd_host = "machineA"'>!TRUE!</xsl:if>WebSEAL is designed to know how to handle the extraction of ADI information from the request:[aznapi-configuration] resource-manager-provided-adi = AMWS_hd_WebSEAL looks for this information in the request header name "host." WebSEAL extracts the value contained in the "host" header and returns it to the authorization evaluation process.The example authorization rule is evaluated to be true if the value provided in the request's "host" header is "machineA."In a similar manner, information required to evaluate an authorization rule can come from the request POST body or the query string of the request.ADI retrieval from the WebSEAL client request

Example: Retrieving ADI from the request header

The following example authorization rule requires the name of the Internet host and port number of the resource being requested. (If port number is omitted, the default port for the requested service is used; for example, port 80 is used for an HTTP URL.) The client request is set up to include the host name value in the "host" header of the request. The use of the AMWS_hd_ prefix in the rule alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.

<xsl:if test='AMWS_hd_host = "machineA"'>!TRUE!</xsl:if>

WebSEAL is designed to know how to handle the extraction of ADI information from the request:

[aznapi-configuration]
resource-manager-provided-adi = AMWS_hd_

WebSEAL looks for this information in the request header name "host." WebSEAL extracts the value contained in the "host" header and returns it to the authorization evaluation process.

The example authorization rule is evaluated to be true if the value provided in the request's "host" header is "machineA."

In a similar manner, information required to evaluate an authorization rule can come from the request POST body or the query string of the request.

Parent topic: ADI retrieval from the WebSEAL client request

Example: Retrieving ADI from the request query stringExample: Retrieving ADI from the request query stringADIretrievalrequest query stringrequestsquery stringsretrieving ADIrequest query stringThe following example authorization rule requires the name of the client's ZIP code as passed in the query string of a GET request (as submitted in response to a form). The client request is set up to include the ZIP code value in the "zip" field of the request query string. https://www.service.com/location?zip=99999The use of the AMWS_qs_ prefix in the rule alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.<xsl:if test='AMWS_qs_zip = "99999"'>!TRUE!</xsl:if>WebSEAL is designed to know how to handle the extraction of ADI information form the request:[aznapi-configuration] resource-manager-provided-adi = AMWS_qs_WebSEAL looks for this information in the request query string under the field name "zip". WebSEAL extracts the value contained in the "zip" field and returns it to the authorization evaluation process.The example authorization rule is evaluated to be true if the value provided in the request's query string "zip" field is "99999".In a similar manner, information required to evaluate an authorization rule can come from the request POST body or the request header.ADI retrieval from the WebSEAL client request

Example: Retrieving ADI from the request query string

The following example authorization rule requires the name of the client's ZIP code as passed in the query string of a GET request (as submitted in response to a form). The client request is set up to include the ZIP code value in the "zip" field of the request query string.

https://www.service.com/location?zip=99999

The use of the AMWS_qs_ prefix in the rule alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.

<xsl:if test='AMWS_qs_zip = "99999"'>!TRUE!</xsl:if>

WebSEAL is designed to know how to handle the extraction of ADI information form the request:

[aznapi-configuration]
resource-manager-provided-adi = AMWS_qs_

WebSEAL looks for this information in the request query string under the field name "zip". WebSEAL extracts the value contained in the "zip" field and returns it to the authorization evaluation process.

The example authorization rule is evaluated to be true if the value provided in the request's query string "zip" field is "99999".In a similar manner, information required to evaluate an authorization rule can come from the request POST body or the request header.

Parent topic: ADI retrieval from the WebSEAL client request

Example: Retrieving ADI from the request POST bodyExample: Retrieving ADI from the request POST bodyADIretrievalrequest POST bodyretrieving ADIrequest POST bodyrequestsPOST bodyThe following example authorization rule requires the name of the client's total purchase amount from a Web shopping cart as passed in the body of a POST request (as submitted in response to a form). The client request is set up to include the total purchase value in the "purchase-total" field of the request POST body. The use of the AMWS_pb_ prefix in the rule alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.<xsl:if test='AMWS_pb_purchase-total &lt; "1000.00"'>!TRUE!</xsl:if>WebSEAL is designed to know how to handle the extraction of ADI information from the request:[aznapi-configuration] resource-manager-provided-adi = AMWS_pb_WebSEAL looks for this information in the request POST body under the field name "purchase-total". WebSEAL extracts the value contained in the "purchase-total" field and returns it to the authorization evaluation process.The example authorization rule is evaluated to be true if the value provided in the request's POST body "purchase-total" field is less than "1000.00". In a similar manner, information required to evaluate an authorization rule can come from the request header or the query string of the request.ADI retrieval from the WebSEAL client request

Example: Retrieving ADI from the request POST body

The following example authorization rule requires the name of the client's total purchase amount from a Web shopping cart as passed in the body of a POST request (as submitted in response to a form). The client request is set up to include the total purchase value in the "purchase-total" field of the request POST body.

The use of the AMWS_pb_ prefix in the rule alerts the authorization evaluation process that the required ADI is available in the client request and that WebSEAL knows how to find, extract, and return this ADI.

<xsl:if test='AMWS_pb_purchase-total &lt; "1000.00"'>!TRUE!</xsl:if>

WebSEAL is designed to know how to handle the extraction of ADI information from the request:

[aznapi-configuration]
resource-manager-provided-adi = AMWS_pb_

WebSEAL looks for this information in the request POST body under the field name "purchase-total". WebSEAL extracts the value contained in the "purchase-total" field and returns it to the authorization evaluation process.

The example authorization rule is evaluated to be true if the value provided in the request's POST body "purchase-total" field is less than "1000.00". In a similar manner, information required to evaluate an authorization rule can come from the request header or the query string of the request.

Parent topic: ADI retrieval from the WebSEAL client request

ADI retrieval from the user credentialADI retrieval from the user credentialADIretrievaluser credentialretrieving ADIuser credentialuser credentialAuthorization rules can be written to use ADI that is provided initially to the authorization rules evaluator as part of the credential. The initial call to the authorization service (azn_decision_access_allowed_ext()) actually contains the user's credential information. The authorization rules evaluator always looks through this credential information for any ADI required by the rule being processed. The authorization rule can use the value from any field in the credential, including extended attributes added to the credential during authentication. Authorization decision information retrievalOverview of ADI retrievalADI retrieval from the WebSEAL client requestSupplying a failure reason across a junctionDynamic ADI retrievalConfiguring WebSEAL to use the attribute retrieval service

ADI retrieval from the user credential

Authorization rules can be written to use ADI that is provided initially to the authorization rules evaluator as part of the credential. The initial call to the authorization service (azn_decision_access_allowed_ext()) actually contains the user's credential information. The authorization rules evaluator always looks through this credential information for any ADI required by the rule being processed. The authorization rule can use the value from any field in the credential, including extended attributes added to the credential during authentication.

Parent topic: Authorization decision information retrieval

Related concepts:

Overview of ADI retrieval

ADI retrieval from the WebSEAL client request

Dynamic ADI retrieval

Related tasks:

Supplying a failure reason across a junction

Configuring WebSEAL to use the attribute retrieval service

Supplying a failure reason across a junctionSupplying a failure reason across a junctionADIsupplying failure reasons across junctionsfailure reasonjunctionssupply failure reason (-R)HTTP headersAM_AZN_FAILUREAM_AZN_FAILURE header Authorization rules allow you to set up special, and often complex, conditions governing the ability to access a protected resource. However, the standard result of a failed authorization decision is to stop the progress of the request to the service application that controls the resource, and present the client with a "forbidden" message. If the authorization rule is written to include a failure reason, and is evaluated as FALSE by the Security Access Manager authorization rules evaluator, WebSEAL receives the reason for the rule's failure along with the standard "forbidden" message from the authorization service. The failure reason is usually ignored and the "forbidden" decision is enforced You can optionally configure WebSEAL to reject this standard response and allow denied requests to proceed across a junction to a back-end service application. The request is accompanied by the failure reason provided in the authorization rule. The back-end service application can then have the opportunity to proceed with its own response to the situation. This optional configuration occurs during the creation of the junction to the back-end service application. Authorization rules are typically used in conjunction with service applications that can understand and handle this more sophisticated level of access control. In some cases, it is necessary for the service application to receive a request that is denied by the Security Access Manager authorization service. Such an application is written to understand failure reason information and can provide its own response to a request that has failed a Security Access Manager authorization rule. For example, the order processing component of a shopping cart application can be governed by an authorization rule that denies action on an order if the total purchase price exceeds the user's credit limit. It is important for the shopping cart application to receive the entire request and the reason for failure. Now the shopping cart application can take matters into its own hands and provide a user-friendly response, such as advising the user to eliminate a portion of the order. The interaction with the user is preserved rather than cut off. To allow denied requests and failure reason information to proceed across a junction to the back-end service application, configure the junction with the –R option. When WebSEAL receives an access denied decision on a request for an object located on a –R junction, WebSEAL reverses the denial response, inserts the failure reason into an HTTP header called "AM_AZN_FAILURE", inserts that header into the request, and passes the request on to the back-end application.Always use this option with caution. It is important to coordinate the use of failure reasons in authorization rules with a service application's ability to interpret and respond to this information. You do not want to accidently create a situation where access is granted to a resource controlled by an application that cannot respond accurately to the AM_AZN_FAILURE header.Authorization decision information retrievalOverview of ADI retrievalADI retrieval from the WebSEAL client requestADI retrieval from the user credentialDynamic ADI retrievalConfiguring WebSEAL to use the attribute retrieval service

Supplying a failure reason across a junction

About this task

Authorization rules allow you to set up special, and often complex, conditions governing the ability to access a protected resource. However, the standard result of a failed authorization decision is to stop the progress of the request to the service application that controls the resource, and present the client with a "forbidden" message. If the authorization rule is written to include a failure reason, and is evaluated as FALSE by the Security Access Manager authorization rules evaluator, WebSEAL receives the reason for the rule's failure along with the standard "forbidden" message from the authorization service. The failure reason is usually ignored and the "forbidden" decision is enforced

You can optionally configure WebSEAL to reject this standard response and allow denied requests to proceed across a junction to a back-end service application. The request is accompanied by the failure reason provided in the authorization rule. The back-end service application can then have the opportunity to proceed with its own response to the situation. This optional configuration occurs during the creation of the junction to the back-end service application.

Authorization rules are typically used in conjunction with service applications that can understand and handle this more sophisticated level of access control. In some cases, it is necessary for the service application to receive a request that is denied by the Security Access Manager authorization service. Such an application is written to understand failure reason information and can provide its own response to a request that has failed a Security Access Manager authorization rule.

For example, the order processing component of a shopping cart application can be governed by an authorization rule that denies action on an order if the total purchase price exceeds the user's credit limit. It is important for the shopping cart application to receive the entire request and the reason for failure. Now the shopping cart application can take matters into its own hands and provide a user-friendly response, such as advising the user to eliminate a portion of the order. The interaction with the user is preserved rather than cut off.

Procedure

To allow denied requests and failure reason information to proceed across a junction to the back-end service application, configure the junction with the –R option. When WebSEAL receives an access denied decision on a request for an object located on a –R junction, WebSEAL reverses the denial response, inserts the failure reason into an HTTP header called "AM_AZN_FAILURE", inserts that header into the request, and passes the request on to the back-end application. Always use this option with caution. It is important to coordinate the use of failure reasons in authorization rules with a service application's ability to interpret and respond to this information. You do not want to accidently create a situation where access is granted to a resource controlled by an application that cannot respond accurately to the AM_AZN_FAILURE header.

Parent topic: Authorization decision information retrieval

Related concepts:

Overview of ADI retrieval

ADI retrieval from the WebSEAL client request

ADI retrieval from the user credential

Dynamic ADI retrieval

Related tasks:

Configuring WebSEAL to use the attribute retrieval service

Dynamic ADI retrievalDynamic ADI retrievalADIretrievaldynamicattribute retrieval servicedynamicVeriSign Profiling Servicedynamic ADI retrievalRules can be written requiring ADI that cannot be found in any of the information that the Security Access Manager authorization service has access to. In these cases, it is necessary to retrieve the ADI from an outside source. A dynamic ADI entitlement retrieval service can perform this retrieval in real time. The attribute retrieval service, currently provided with WebSEAL, is one type of entitlement retrieval service.The attribute retrieval service provides communication and format translation services between the WebSEAL entitlement service library and an external provider of authorization decision information. The process flow for the attribute retrieval service is described in the following diagram:Dynamic ADI retrievalDynamic ADI retrievalThe client makes a request for a resource protected by an authorization rule. The authorization rules evaluator, which is part of the authorization service, determines that specific ADI is required to complete the rule evaluation. The ADI requested is not available from the user credential, the authorization service, or WebSEAL. The task of ADI retrieval is sent to the attribute retrieval service through the entitlements service library. This service formats the request for ADI as a SOAP request. The SOAP request is sent over HTTP to the Web Service Description Language (WSDL) interface of the attribute retrieval service.The attribute retrieval service formats the request appropriately for the external provider of ADI.The external provider of ADI returns the appropriate ADI.The ADI is formatted in another SOAP container and returned to the WebSEAL entitlements service. Now the authorization rules evaluator has the necessary information to evaluate the rule and decide whether to accept or deny the original client request.The WebSEAL attribute retrieval service is deprecated. IBM might remove this capability in a subsequent release of the product.Alternatively, you can create and deploy a custom attribute retrieval service. The Security Access Manager Application Development Kit includes a WSDL file to get you started. The file is in the following locations: AIX, Linux, or Solaris/opt/PolicyDirector/example/amwebars/azn_ent_amwebars.wsdlWindowsC:\Program Files\Tivoli\Policy Director\example\amwebars\ azn_ent_amwebars.wsdlFor more information about creating and deploying web services, see the IBM WebSphere Application Server Information Center at http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp.Authorization decision information retrievalOverview of ADI retrievalADI retrieval from the WebSEAL client requestADI retrieval from the user credentialSupplying a failure reason across a junctionConfiguring WebSEAL to use the attribute retrieval service

Dynamic ADI retrieval

Rules can be written requiring ADI that cannot be found in any of the information that the Security Access Manager authorization service has access to. In these cases, it is necessary to retrieve the ADI from an outside source. A dynamic ADI entitlement retrieval service can perform this retrieval in real time. The attribute retrieval service, currently provided with WebSEAL, is one type of entitlement retrieval service.

The attribute retrieval service provides communication and format translation services between the WebSEAL entitlement service library and an external provider of authorization decision information. The process flow for the attribute retrieval service is described in the following diagram:

Figure 58. Dynamic ADI retrieval

The client makes a request for a resource protected by an authorization rule.

The authorization rules evaluator, which is part of the authorization service, determines that specific ADI is required to complete the rule evaluation. The ADI requested is not available from the user credential, the authorization service, or WebSEAL.

The task of ADI retrieval is sent to the attribute retrieval service through the entitlements service library. This service formats the request for ADI as a SOAP request. The SOAP request is sent over HTTP to the Web Service Description Language (WSDL) interface of the attribute retrieval service.

The attribute retrieval service formats the request appropriately for the external provider of ADI.

The external provider of ADI returns the appropriate ADI.

The ADI is formatted in another SOAP container and returned to the WebSEAL entitlements service. Now the authorization rules evaluator has the necessary information to evaluate the rule and decide whether to accept or deny the original client request.

Note: The WebSEAL attribute retrieval service is deprecated. IBM® might remove this capability in a subsequent release of the product.

Alternatively, you can create and deploy a custom attribute retrieval service. The Security Access Manager Application Development Kit includes a WSDL file to get you started. The file is in the following locations:

AIX®, Linux, or Solaris

/opt/PolicyDirector/example/amwebars/azn_ent_amwebars.wsdl

Windows

C:\Program Files\Tivoli\Policy Director\example\amwebars\ azn_ent_amwebars.wsdl

For more information about creating and deploying web services, see the IBM WebSphere® Application Server Information Center at http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp.

Parent topic: Authorization decision information retrieval

Related concepts:

Overview of ADI retrieval

ADI retrieval from the WebSEAL client request

ADI retrieval from the user credential

Related tasks:

Supplying a failure reason across a junction

Configuring WebSEAL to use the attribute retrieval service

Configuring WebSEAL to use the attribute retrieval serviceADIretrievalattributesattribute retrieval serviceWebSEALamwebar stanzaazn_ent_amwebars libraryaznapi-configuration stanzaaznapi-entitlement-services stanzaservice-url stanza entrydynamic-ad-entitlements-services stanza entrydynamic ADI retrievaldeploying the attribute retrieval serviceWebSpheredeploying the attribute retrieval servicePerform the following tasks to configure WebSEAL to use the attribute retrieval service.In the WebSEAL configuration file, specify the identification name (ID) of the attribute retrieval service that is queried when missing ADI is detected during a rules evaluation. In this case, the attribute retrieval service is specified: [aznapi-configuration] dynamic-adi-entitlement-services = AMWebARS_A In the WebSEAL configuration file, use the service ID for the configured attribute retrieval service as a parameter to specify the appropriate built-in library that formats outbound ADI requests and interprets incoming responses:For example:[aznapi-entitlement-services] AMWebARS_A = azn_ent_amwebars In the WebSEAL configuration file, specify the URL to the attribute retrieval service located in the WebSphere environment. For a TCP connection (entered as one line): [amwebars] service-url = http://websphere_hostname:websphere_port /amwebars/amwebars/ServiceToIServicePortAdapter Authorization decision information retrievalOverview of ADI retrievalADI retrieval from the WebSEAL client requestADI retrieval from the user credentialSupplying a failure reason across a junctionDynamic ADI retrieval

Configuring WebSEAL to use the attribute retrieval service

About this task

Perform the following tasks to configure WebSEAL to use the attribute retrieval service.

Procedure

In the WebSEAL configuration file, specify the identification name (ID) of the attribute retrieval service that is queried when missing ADI is detected during a rules evaluation. In this case, the attribute retrieval service is specified:

[aznapi-configuration]
dynamic-adi-entitlement-services = AMWebARS_A

In the WebSEAL configuration file, use the service ID for the configured attribute retrieval service as a parameter to specify the appropriate built-in library that formats outbound ADI requests and interprets incoming responses:

For example:

[aznapi-entitlement-services]
AMWebARS_A = azn_ent_amwebars

In the WebSEAL configuration file, specify the URL to the attribute retrieval service located in the WebSphere® environment.

For a TCP connection (entered as one line):

[amwebars]
service-url = http://websphere_hostname:websphere_port
 /amwebars/amwebars/ServiceToIServicePortAdapter

Parent topic: Authorization decision information retrieval

Related concepts:

Overview of ADI retrieval

ADI retrieval from the WebSEAL client request

ADI retrieval from the user credential

Dynamic ADI retrieval

Related tasks:

Supplying a failure reason across a junction

Guidelines for changing configuration filesGuidelines for changing configuration filesSecurity Access Managerconfiguration guidelinesconfiguration fileschangingguidelineschanging configuration filesThese guidelines are provided to help you make changes to the Security Access Manager configuration files. The guidelines are divided into the following categories: Web Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.General guidelinesDefault valuesStringsDefined stringsFile namesIntegersBoolean values

Guidelines for changing configuration files

These guidelines are provided to help you make changes to the Security Access Manager configuration files. The guidelines are divided into the following categories:

General guidelines

Default values

Strings

Defined strings

File names

Integers

Boolean values

Parent topic: Web Reverse Proxy configuration

General guidelinesGeneral guidelinesconfiguration filesgeneral guidelinesgeneral guidelinesUse the following general guidelines when making changes to the configuration settings:There is no order dependency or location dependency for stanzas in any configuration file.Stanza entries are marked as required or optional. When an entry is required, the entry must contain a valid key and value.Do not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results for the servers.Stanza entries and key names are case-sensitive. For example, usessl and UseSSL are treated as different entries.Spaces are not allowed for names of keys.For the key value pair format of key = value, the spaces surrounding the equal sign (=) are not required, but they are recommended.Non-printable characters (such as tabs, carriage returns, and line feeds) that occur at the end of a stanza entry are ignored. Non-printable characters are ASCII characters with a decimal value less than 32.Guidelines for changing configuration files

General guidelines

Use the following general guidelines when making changes to the configuration settings:

There is no order dependency or location dependency for stanzas in any configuration file.

Stanza entries are marked as required or optional. When an entry is required, the entry must contain a valid key and value.

Do not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results for the servers.

Stanza entries and key names are case-sensitive. For example, usessl and UseSSL are treated as different entries.

Spaces are not allowed for names of keys.

For the key value pair format of key = value, the spaces surrounding the equal sign (=) are not required, but they are recommended.

Non-printable characters (such as tabs, carriage returns, and line feeds) that occur at the end of a stanza entry are ignored. Non-printable characters are ASCII characters with a decimal value less than 32.

Parent topic: Guidelines for changing configuration files

Default valuesDefault valuesconfiguration filesdefault valuesdefault valuesUse the following guidelines when changing default configuration settings: Many values are created or modified only by using configuration programs. Do not manually edit these stanzas or values.Some values are filled in automatically during configuration. These values are needed for the initialization of the server after the configuration.The default values for a stanza entry might be different, depending on the server configuration. Some key value pairs are not applicable to certain servers and are omitted from the default configuration file for this server.Guidelines for changing configuration files

Default values

Use the following guidelines when changing default configuration settings:

Many values are created or modified only by using configuration programs. Do not manually edit these stanzas or values.

Some values are filled in automatically during configuration. These values are needed for the initialization of the server after the configuration.

The default values for a stanza entry might be different, depending on the server configuration. Some key value pairs are not applicable to certain servers and are omitted from the default configuration file for this server.

Parent topic: Guidelines for changing configuration files

StringsStringsconfiguration filesstring valuesstringsvaluesSome values accept a string value. When you manually edit the configuration file, use the following guidelines to change configuration settings that require a string: String values are expected to be characters that are part of the local code set.Additional or different restrictions on the set of allowable string characters might be imposed. For example, many strings are restricted to ASCII characters. Consult each stanza entry description for any restrictions.Double quotation marks are sometimes, but not always, required when you use spaces or more than one word for values. Refer to the descriptions or examples for each stanza entry when in doubt.The minimum and maximum lengths of user registry-related string values, if there are limits, are imposed by the underlying registry. For example, for Active Directory the maximum length is 256 alphanumeric characters.Guidelines for changing configuration files

Strings

Some values accept a string value. When you manually edit the configuration file, use the following guidelines to change configuration settings that require a string:

String values are expected to be characters that are part of the local code set.

Additional or different restrictions on the set of allowable string characters might be imposed. For example, many strings are restricted to ASCII characters. Consult each stanza entry description for any restrictions.

Double quotation marks are sometimes, but not always, required when you use spaces or more than one word for values. Refer to the descriptions or examples for each stanza entry when in doubt.

The minimum and maximum lengths of user registry-related string values, if there are limits, are imposed by the underlying registry. For example, for Active Directory the maximum length is 256 alphanumeric characters.

Parent topic: Guidelines for changing configuration files

Defined stringsDefined stringsconfiguration filesdefined stringsdefined stringsSome values accept a string value, but the value must be one of a set of defined strings. When you manually edit the configuration file, make sure that the string value you type matches one of the valid defined strings values.For example, the [aznapi-configuration] stanza section contains the following entry:auditcfg = {azn|authn|mgmt}The value for auditcfg is expected to be azn, authn, or mgmt. Any other value is invalid and results in an error.Guidelines for changing configuration files

Defined strings

Some values accept a string value, but the value must be one of a set of defined strings. When you manually edit the configuration file, make sure that the string value you type matches one of the valid defined strings values.

For example, the [aznapi-configuration] stanza section contains the following entry:

auditcfg = {azn|authn|mgmt}

The value for auditcfg is expected to be azn, authn, or mgmt. Any other value is invalid and results in an error.

Parent topic: Guidelines for changing configuration files

File namesFile namesconfiguration filesfiles namesfile namesSome values are file names. For each stanza entry that expects a file name as a value, specify the file name exactly as it is displayed in the LMI. Do not include any directory path information.Guidelines for changing configuration files

File names

Some values are file names. For each stanza entry that expects a file name as a value, specify the file name exactly as it is displayed in the LMI. Do not include any directory path information.

Parent topic: Guidelines for changing configuration files

IntegersIntegersconfiguration filesinteger valuesintegersMany stanza entries expect the value for the entry to be expressed as an integer. When defining an entry with an integer, consider the following guidelines: Stanza entries that take an integer value expect integer values within a valid range. The range is described in terms of a minimum value and a maximum value. For example, in the [logging] stanza, the logflush stanza entry has a minimum value of 1 second and a maximum value of 600 seconds. For some entries, the integer value must be positive, and the minimum value is 1. For other entries, a minimum integer value of 0 is allowed. Use caution when setting an integer value to 0. For example, an integer value of 0 might disable the function that is controlled by that stanza entry. For example, in the [ivacld] stanza, the entry tcp-req-port = 0 disables the port number. Or, an integer value of 0 might indicate that the number is unlimited. For example, in the [ldap] stanza, the entry max-search-size = 0 means there is no limit to the maximum search size.For some entries requiring integer values, Security Access Manager does not impose an upper limit for the maximum number allowed. For example, there is typically no maximum for timeout-related values, such as timeout = number in the [ldap] stanza. For this type of entry, the maximum number is limited only by the size of memory allocated for an integer data type. This number can vary, based on the type of operating system. For systems that allocate 4 bytes for an integer, this value is 2147483647. However, as the administrator, use a number that represents the value that is most logical for the value you are trying to set.Guidelines for changing configuration files

Integers

Many stanza entries expect the value for the entry to be expressed as an integer. When defining an entry with an integer, consider the following guidelines:

Stanza entries that take an integer value expect integer values within a valid range. The range is described in terms of a minimum value and a maximum value.

For example, in the [logging] stanza, the logflush stanza entry has a minimum value of 1 second and a maximum value of 600 seconds.

For some entries, the integer value must be positive, and the minimum value is 1. For other entries, a minimum integer value of 0 is allowed.

Use caution when setting an integer value to 0. For example, an integer value of 0 might disable the function that is controlled by that stanza entry. For example, in the [ivacld] stanza, the entry tcp-req-port = 0 disables the port number. Or, an integer value of 0 might indicate that the number is unlimited. For example, in the [ldap] stanza, the entry max-search-size = 0 means there is no limit to the maximum search size.

For some entries requiring integer values, Security Access Manager does not impose an upper limit for the maximum number allowed. For example, there is typically no maximum for timeout-related values, such as timeout = number in the [ldap] stanza.

For this type of entry, the maximum number is limited only by the size of memory allocated for an integer data type. This number can vary, based on the type of operating system. For systems that allocate 4 bytes for an integer, this value is 2147483647.

However, as the administrator, use a number that represents the value that is most logical for the value you are trying to set.

Parent topic: Guidelines for changing configuration files

Boolean valuesBoolean valuesconfiguration filesBoolean valuesBoolean valuesMany stanza entries represent a Boolean value. Security Access Manager recognizes the Boolean values yes and no.Some of the entries in the configuration files are read by other servers and utilities. For example, many entries in the [ldap] stanza are read by the LDAP client. Some of these other programs recognize additional Boolean characters: yes or trueno or falseAnything other than yes|true, including a blank value, is interpreted as no|false.The recognized Boolean entries are listed for each stanza entry. Refer to the individual descriptions to determine when true or false are also recognized.Guidelines for changing configuration files

Boolean values

Many stanza entries represent a Boolean value. Security Access Manager recognizes the Boolean values yes and no.

Some of the entries in the configuration files are read by other servers and utilities. For example, many entries in the [ldap] stanza are read by the LDAP client. Some of these other programs recognize additional Boolean characters:

yes or true

no or false

Anything other than yes|true, including a blank value, is interpreted as no|false.

The recognized Boolean entries are listed for each stanza entry. Refer to the individual descriptions to determine when true or false are also recognized.

Parent topic: Guidelines for changing configuration files

Command referenceCommand referencepdadmin policycommand referencecommand referencepdadminThis appendix contains a subset of the pdadmin commands that are specific to WebSEAL tasks.See the Web command reference topics.Web Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy.Reading syntax statementshelpserver listserver task addThe server task add command adds an additional back-end application server to an existing WebSEAL junction.server task cache flush allThe server task cache flush all command flushes the HTML document cache. server task cluster restartThe server task cluster restart command applies any configuration changes to the entire cluster and restarts the updated servers. server task createThe server task create command creates a WebSEAL junction point.server task deleteThe server task delete command deletes a WebSEAL junction point.server task dynurl updateThe server task dynurl update command reloads the dynamic URL configuration file.server task helpserver task jmtThe server task jmt command clears or loads the junction mapping table data.server task listThe server task list command lists all junction points on a WebSEAL server or instance.server task offlineThe server task offline command places the server that is located at this junction in an offline operational state.server task onlineThe server task online command places the server that is located at this junction in an online operational state. server task refresh all_sessionsThe server task refresh all_sessions command refreshes the credential for all sessions for a specified user.server task reloadThe server task reload command reloads the junction mapping table from the database. server task removeThe server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point.server task server restartThe server task server restart command restarts a WebSEAL server by using the Security Access Manager server task framework. server task showThe server task show command displays detailed information about the specified WebSEAL junction.server task server syncThe server task server sync command synchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework. server task terminate all_sessionsThe server task terminate all_sessions command terminates all user sessions for a specific user. server task terminate sessionThe server task terminate session command terminates a user session using a session ID.server task throttleThe server task throttle command places the server that is located at this junction in a throttled operational state.server task virtualhost addThe server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction. server task virtualhost createThe server task virtualhost create command creates a virtual host junction.server task virtualhost deleteThe server task virtualhost delete command deletes a virtual host junction.server task virtualhost listThe server task virtualhost list command lists all configured virtual host junctions by label name.server task virtualhost offlineThe server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state.server task virtualhost onlineThe server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. server task virtualhost removeThe server task virtualhost remove command removes the specified server from a virtual host junction.server task virtualhost showThe server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed.server task virtualhost throttleThe server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state.

Command reference

This appendix contains a subset of the pdadmin commands that are specific to WebSEAL tasks.

See the Web command reference topics.

Reading syntax statements

help

server list

server task add
The server task add command adds an additional back-end application server to an existing WebSEAL junction.

server task cache flush all
The server task cache flush all command flushes the HTML document cache.

server task cluster restart
The server task cluster restart command applies any configuration changes to the entire cluster and restarts the updated servers.

server task create
The server task create command creates a WebSEAL junction point.

server task delete
The server task delete command deletes a WebSEAL junction point.

server task dynurl update
The server task dynurl update command reloads the dynamic URL configuration file.

server task help

server task jmt
The server task jmt command clears or loads the junction mapping table data.

server task list
The server task list command lists all junction points on a WebSEAL server or instance.

server task offline
The server task offline command places the server that is located at this junction in an offline operational state.

server task online
The server task online command places the server that is located at this junction in an online operational state.

server task refresh all_sessions
The server task refresh all_sessions command refreshes the credential for all sessions for a specified user.

server task reload
The server task reload command reloads the junction mapping table from the database.

server task remove
The server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point.

server task server restart
The server task server restart command restarts a WebSEAL server by using the Security Access Manager server task framework.

server task show
The server task show command displays detailed information about the specified WebSEAL junction.

server task server sync
The server task server sync command synchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework.

server task terminate all_sessions
The server task terminate all_sessions command terminates all user sessions for a specific user.

server task terminate session
The server task terminate session command terminates a user session using a session ID.

server task throttle
The server task throttle command places the server that is located at this junction in a throttled operational state.

server task virtualhost add
The server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction.

server task virtualhost create
The server task virtualhost create command creates a virtual host junction.

server task virtualhost delete
The server task virtualhost delete command deletes a virtual host junction.

server task virtualhost list
The server task virtualhost list command lists all configured virtual host junctions by label name.

server task virtualhost offline
The server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state.

server task virtualhost online
The server task virtualhost online command places the server that is located at this virtual host junction in an online operational state.

server task virtualhost remove
The server task virtualhost remove command removes the specified server from a virtual host junction.

server task virtualhost show
The server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed.

server task virtualhost throttle
The server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state.

Parent topic: Web Reverse Proxy configuration

Reading syntax statementsReading syntax statementssyntax, readingsyntaxreading statementsstatementsreading syntax statementsThe reference documentation uses the following special characters to define syntax: [ ]Identifies optional options. Options not enclosed in brackets are required....Indicates that you can specify multiple values for the previous option.|Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.{ }Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).\Indicates that the command line wraps to the next line. It is a continuation character.The options for each command are listed alphabetically in the Options section. When the order of the options must be used in a specific order, this order is shown in the syntax statement.Command reference

Reading syntax statements

The reference documentation uses the following special characters to define syntax:

[ ]

Identifies optional options. Options not enclosed in brackets are required.

...

Indicates that you can specify multiple values for the previous option.

|

Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.

{ }

Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).

\

Indicates that the command line wraps to the next line. It is a continuation character.

The options for each command are listed alphabetically in the Options section. When the order of the options must be used in a specific order, this order is shown in the syntax statement.

Parent topic: Command reference

helphelppdadminhelphelpObtains system help for pdadmin commands and options. This command does not require a login or authentication to use.Syntax help {topic | command} Options topicSpecifies the help command topic for which help is needed.commandSpecifies the miscellaneous command for which help is needed. Return codes 0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example lists help topics and commands: pdadmin> helpOutput is similar to: Type 'help <topic>' or 'help <command> for more information Topics: acl action admin authzrule config context domain errtext exit group help login logout object objectspace policy pop quit rsrc rsrccred rsrcgroup server user Miscellaneous Commands: exit help quitThe following example lists the options and descriptions that are available whether you specify the topic action or action create: pdadmin> help actionOr: pdadmin> help action createOutput is similar to: action create <action-name> <action-label> <action-type> Creates a new ACL action definition action create <action-name> <action-label> <action-type> <action-group-name> Creates a new ACL action definition in a group ... Command reference

help

Obtains system help for pdadmin commands and options.

This command does not require a login or authentication to use.

Syntax

help {topic | command}

Options

topic

Specifies the help command topic for which help is needed.

command

Specifies the miscellaneous command for which help is needed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists help topics and commands:

pdadmin> help

Output is similar to:

Type 'help <topic>' or 'help <command> for more information

Topics:
acl
action
admin
authzrule
config
context
domain
errtext
exit
group
help
login
logout
object
objectspace
policy
pop
quit
rsrc
rsrccred
rsrcgroup
server
user

Miscellaneous Commands:
exit
help
quit

The following example lists the options and descriptions that are available whether you specify the topic action or action create:

pdadmin> help action

Or:

pdadmin> help action create

Output is similar to:

action create <action-name> <action-label> <action-type>
Creates a new ACL action definition
action create <action-name> <action-label> <action-type> <action-group-name>
Creates a new ACL action definition in a group
...

Parent topic: Command reference

server listserver listserver commandsserver listlist serversLists all registered Security Access Manager servers. Requires authentication (administrator ID and password) to use this command.Syntax server list Description Lists all registered Security Access Manager servers. The name of the server for all server commands, except for the server list command, must be entered in the exact format as it is displayed in the output of this command. Options None. Return codes 0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example lists all registered servers if the Security Access Manager component is the authorization server: pdadmin> server listOutput is similar to: ivacld-topserver ivacld-server2 ivacld-server3 ivacld-server4 Command reference

server list

Lists all registered Security Access Manager servers.

Requires authentication (administrator ID and password) to use this command.

Syntax

server list

Description

Lists all registered Security Access Manager servers. The name of the server for all server commands, except for the server list command, must be entered in the exact format as it is displayed in the output of this command.

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists all registered servers if the Security Access Manager component is the authorization server:

pdadmin> server list

Output is similar to:

ivacld-topserver
ivacld-server2
ivacld-server3
ivacld-server4

Parent topic: Command reference

server task addserver task addWebSEAL server task add commandThe server task add command adds an additional back-end application server to an existing WebSEAL junction.server commandsserver task addserver task commandsaddingjunctionsadding junctioned serverjunctioned serveraddingRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name add -h host_name [options] junction_point Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.optionsSpecifies the options that you can use with the server task add command. These options include: -D "dn"Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US" This option is valid only with junctions that were created with the type of ssl or sslproxy.-H host_nameSpecifies the DNS host name or IP address of the proxy server. Valid values for host_name include any valid IP host name. For example: www.example.com This option is used for junctions that were created with the type of tcpproxy or sslproxy.–iIndicates that the WebSEAL server does not treat URLs as case-sensitive. This option is used for junctions that were created with the type of tcp or ssl.-p portSpecifies the TCP port of the back-end server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.-P portFor proxy junctions that were created with the type of tcpproxy or sslproxy this option specifies the TCP port number for the HTTP proxy server. The default value is 7138. For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater than 1000 that is currently not being used. This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.-q urlRequired option for back-end Windows servers. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file. This option is used for junctions that were created with the type of tcp or ssl.-u uuidSpecifies the UUID of this back-end server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.-v virtual_hostnameSpecifies the virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. Use this option when the back-end junction server expects a host name header, because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host. This option is used for junctions that were created with the type of tcp or ssl.-V virtual_hostname Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. This option is only used for mutual junctions and corresponds to the virtual host which is used for HTTPS requests. You use –V when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host. -wIndicates Microsoft Windows file system support. This option is used for junctions that were created with the type of tcp or ssl.-h host_nameRequired option. Specifies the DNS host name or IP address of the target back-end application server. Valid values for host_name include any valid IP host name. For example: www.example.com Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default. This command is available only when WebSEAL is installed. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors.Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example creates a new junction for the WebSEAL server named WS1 to the back-end server named APP1 and adds another back-end server named APP2 to the same junction point: pdadmin> server task default-webseald-WS1 create -t tcp -h APP1 -s /mnt pdadmin> server task default-webseald-WS1 add -h APP2 /mnt See also server task createThe server task create command creates a WebSEAL junction point. server task deleteThe server task delete command deletes a WebSEAL junction point. server task removeThe server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point. server task showThe server task show command displays detailed information about the specified WebSEAL junction. Command reference

server task add

The server task add command adds an additional back-end application server to an existing WebSEAL junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name add -h host_name [options] junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

options

Specifies the options that you can use with the server task add command. These options include:

-D "dn"

Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

-H host_name

Specifies the DNS host name or IP address of the proxy server. Valid values for host_name include any valid IP host name. For example:

www.example.com

This option is used for junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL server does not treat URLs as case-sensitive. This option is used for junctions that were created with the type of tcp or ssl.

-p port

Specifies the TCP port of the back-end server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.

-P port

For proxy junctions that were created with the type of tcpproxy or sslproxy this option specifies the TCP port number for the HTTP proxy server. The default value is 7138.

For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater than 1000 that is currently not being used.

This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.

-q url

Required option for back-end Windows servers. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file.

This option is used for junctions that were created with the type of tcp or ssl.

-u uuid

Specifies the UUID of this back-end server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.

-v virtual_hostname

Specifies the virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. Use this option when the back-end junction server expects a host name header, because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host. This option is used for junctions that were created with the type of tcp or ssl.

-V virtual_hostname

Virtual host name represented on the back-end server. This option supports a virtual host setup on the back-end server. This option is only used for mutual junctions and corresponds to the virtual host which is used for HTTPS requests.

You use –V when the back-end junction server expects a host name header because you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests destined for a back-end server set up as a virtual host.

-w

Indicates Microsoft Windows file system support.

This option is used for junctions that were created with the type of tcp or ssl.

-h host_name

Required option. Specifies the DNS host name or IP address of the target back-end application server. Valid values for host_name include any valid IP host name. For example:

www.example.com

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Note: This command is available only when WebSEAL is installed.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates a new junction for the WebSEAL server named WS1 to the back-end server named APP1 and adds another back-end server named APP2 to the same junction point:

pdadmin> server task default-webseald-WS1 create -t tcp -h APP1 -s /mnt

pdadmin> server task default-webseald-WS1 add -h APP2 /mnt

See also

server task create

server task delete

server task remove

server task show

Parent topic: Command reference

server task cache flush allserver task cache flush allserver task cache flush allThe server task cache flush all command flushes the HTML document cache. server commandsserver task cache flush allserver task commandscache flush allcacheflushing HTML documentHTMLdocument cachedocument cacheHTML flushingRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name cache flush all Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default. This command is available only when WebSEAL is installed. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example flushes all Web document caches: pdadmin> server task default-webseald-abc.ibm.com cache flush all See also None. Command reference

server task cache flush all

The server task cache flush all command flushes the HTML document cache.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name cache flush all

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default.

Note: This command is available only when WebSEAL is installed.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example flushes all Web document caches:

pdadmin> server task default-webseald-abc.ibm.com cache flush all

See also

None.

Parent topic: Command reference

server task cluster restartserver task cluster restartWebSEAL server task cluster restart commandThe server task cluster restart command applies any configuration changes to the entire cluster and restarts the updated servers. server commandsserver task cluster restartserver task commandscluster restartRequires authentication (administrator ID and password) to use this command. Syntax server task server_name cluster restart [-ripple|-status] DescriptionIf the -status option is used then the command provides a status update on the most recent cluster restart.If the -status option is not used then the command causes each server in the cluster to examine the master for configuration updates. If required, the server updates its configuration data to synchronize with the master configuration information. If updates are applied then the server is restarted. The master server is restarted after all of the slave servers in the cluster have been updated and restarted as required. This command is only available on the configured cluster master server. Options server_nameSpecifies the name of the master authorization server on which the configuration data resides. -rippleIndicates that each WebSEAL server in the cluster must restart in sequence rather than being restarted in parallel.-statusMonitors the progress of a cluster restart. This option returns one of the following messages based on the current status of the cluster:DPWAD0444I The cluster has been restarted. DPWAD0443I The cluster is in the process of being restarted. Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the master /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default. An error is returned if the server is not configured as the master of the cluster. Before executing this command, you must ensure that the cluster is configured correctly using appropriate [cluster] stanza entries. For more information, see [cluster] stanzaUse the [cluster] stanza to configure a clustered WebSEAL server environment..You cannot use the two options -ripple and -status at the same time. The -ripple option is available when initiating a cluster restart, while the -status option monitors the progress of the most recent cluster restart request. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Default valueBy default the cluster is restarted in parallel. ExamplesThe following example restarts the cluster in sequence. This command must be executed on the cluster master server, which in this example is default-webseald-master.ibm.com. server task default-webseald-master.ibm.com cluster restart -rippleIn this example, the following command can be used at any time after the previous request to monitor the progress of the cluster restart:server task default-webseald-master.ibm.com cluster restart -statusCommand reference

server task cluster restart

The server task cluster restart command applies any configuration changes to the entire cluster and restarts the updated servers.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task server_name cluster restart [-ripple|-status]

Description

If the -status option is used then the command provides a status update on the most recent cluster restart.

If the -status option is not used then the command causes each server in the cluster to examine the master for configuration updates. If required, the server updates its configuration data to synchronize with the master configuration information. If updates are applied then the server is restarted. The master server is restarted after all of the slave servers in the cluster have been updated and restarted as required.

Note: This command is only available on the configured cluster master server.

Options

server_name

Specifies the name of the master authorization server on which the configuration data resides.

-ripple

Indicates that each WebSEAL server in the cluster must restart in sequence rather than being restarted in parallel.

-status

Monitors the progress of a cluster restart. This option returns one of the following messages based on the current status of the cluster:

DPWAD0444I   The cluster has been restarted.

DPWAD0443I   The cluster is in the process of being restarted.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the master /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default.

Note:

An error is returned if the server is not configured as the master of the cluster. Before executing this command, you must ensure that the cluster is configured correctly using appropriate [cluster] stanza entries. For more information, see [cluster] stanza.

You cannot use the two options -ripple and -status at the same time. The -ripple option is available when initiating a cluster restart, while the -status option monitors the progress of the most recent cluster restart request.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Default value

By default the cluster is restarted in parallel.

Examples

The following example restarts the cluster in sequence. This command must be executed on the cluster master server, which in this example is default-webseald-master.ibm.com.

server task default-webseald-master.ibm.com cluster restart -ripple

In this example, the following command can be used at any time after the previous request to monitor the progress of the cluster restart:

server task default-webseald-master.ibm.com cluster restart -status

Parent topic: Command reference

server task createserver task createWebSEAL server task create commandThe server task create command creates a WebSEAL junction point.server task commandscreatejunctionscreate junctioned serverjunctioned servercreateserver commandsserver task createRequires authentication (administrator ID and password) to use this command.Syntax For local junctions: server task instance_name-webseald-host_name create -t type [options] junction_point For non-local junctions: server task instance_name-webseald-host_name create -t type -h host_name [options] junction_point Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.optionsSpecifies the options that you can use with the server task create command. The options include: -a addressSpecifies the local IP address for WebSEAL to use when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system. If an address is supplied for a particular junction, WebSEAL is modified to bind to this local address for all communication with the junctioned server.-A Enables or disables lightweight third-party authentication mechanism (LTPA) junctions. This option requires the -F and -Z options. The -A, -F, and -Z options all must be used together. This option is valid for all junctions except for the type of local.-2You can use this option in conjunction with the -A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.-b BA_valueDefines how the WebSEAL server passes the HTTP BA authentication information to the back-end server, which is one of the following values: filter (default)ignoresupplygsoThis option is valid for all junctions except for the type of local.-B Indicates that WebSEAL uses the BA header information to authenticate to the back-end server and to provide mutual authentication over SSL. This option requires the -U and -W options. This option is valid only with junctions that were created with the type of ssl or sslproxy.-c header_typeInserts the Security Access Manager client identity in HTTP headers across the junction. The header_type argument can include any combination of the following Security Access Manager HTTP header types: {iv-user|iv-user-l}iv-groupsiv-credsall The header types must be comma separated, and cannot have spaces between the types. For example: -c iv_user,iv_groups Specifying -c all is the same as specifying -c iv-user,iv-groups,iv-creds. This option is valid for all junctions except for the type of local.-C Indicates single signon from a front-end WebSEAL server to a back-end WebSEAL server. The -C option is not mutual authentication. This option is valid only with junctions that were created with the type of ssl or sslproxy.-D "dn"Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US" This option is valid only with junctions that were created with the type of ssl or sslproxy.-e encoding_typeSpecifies the encoding to use when generating HTTP headers for junctions. This encoding applies to headers that are generated with both the -c junction option and tag-value. The following values for encoding are supported: utf8_binWebSEAL sends the headers in UTF-8.utf8_uriWebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.lcp_binWebSEAL sends the headers in the local code page of the WebSEAL server.lcp_uriWebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them. This option is valid for all junctions except for the type of local.-fForces the replacement of an existing junction. This option is used for junctions that were created with any junction type.-F keyfileSpecifies the name of the keyfile used to encrypt LTPA cookie data. The -F option requires -A and -Z options. The -A, -F, and -Z options all must be used together. This option is valid for all junctions except for the type of local.-H host_nameSpecifies the DNS host name or IP address of the proxy server. The -P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example: proxy.www.example.comThis option is valid only with junctions that were created with the type of tcpproxy or sslproxy.-iIndicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file. Junctions to such a Web server should be created with the -i or -w option. ACLs or POPs that are attached to objects beneath the junction point should use the lowercase object name. An ACL attached to /junction/index.htm will apply to all of the following requests if the -i or -w option is used: /junction/INDEX.HTM/junction/index.htm/junction/InDeX.HtM This option is valid for all junctions except for the type of local. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.-I Ensures a unique Set-Cookie header name attribute when using the -j option to modify server-relative URLs in requests. This option is valid for all junctions except for the type of local.-jSupplies junction identification in a cookie to handle script-generated server-relative URLs. This option is valid for all junctions except for the type of local.-J trailer,inhead,onfocus,xhtml10 Controls the junction cookie JavaScript block. Use –J trailer to append (rather than prepend) the junction cookie JavaScript to HTML page returned from back-end server. Use –J inhead to insert the JavaScript block between <head> </head> tags for HTML 4.01 compliance. Use –J onfocus to use the onfocus event handler in the JavaScript to ensure the correct junction cookie is used in a multiple-junction/multiple-browser-window scenario. Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and XHTML 1.0 compliant. For complete details on this option, see Control on the junction cookie JavaScript block.-kSends WebSEAL session cookies to the junction server. By default, cookies are removed from requests that are sent to the server. This option is valid for all junctions except for the type of local.-K "key_label"Specifies the key label of the client personal certificate that WebSEAL should present to the back-end server. Use of this option allows the junction server to authenticate the WebSEAL server using client certificates. This option is valid only with junctions that were created with the type of ssl and sslproxy.-l percentDefines the soft limit for consumption of worker threads. This option is valid for all junctions except for the type of local.-L percentDefines the hard limit for consumption of worker threads. This option is valid for all junctions except for the type of local.-nIndicates that no modification of the names of non-domain cookies are to be made. Use when client side scripts depend on the names of cookies. By default, if a junction is listed in the JMT or if the -j junction option is used, WebSEAL will modify the names of non-domain cookies that are returned from the junction to prepend AMWEBJCT!junction_point. This option is valid for all junctions except for the type of local.-p portSpecifies the TCP port of the back-end third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is valid for all junctions except for the type of local.-P portFor proxy junctions that were created with the type of tcpproxy or sslproxy this option specifies the TCP port number for the HTTP proxy server. The -P option is required when the -H option is used. This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.-q pathRequired option for back-end Windows servers. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option will indicates to WebSEAL the new URL to the file. This option is valid for all junctions except for the type of local.-rInserts the incoming IP address into the HTTP header across the junction. This option is valid for all junctions except for the type of local.-R Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the -R option is not used and a rule failure occurs, WebSEAL will not allow the request to proceed. This option is valid for all junctions except for the type of local.-sIndicates that the junction support stateful applications. By default, junctions are not stateful. This option is valid for all junctions except for the type of local.-S Specifies the name of the forms single signon configuration file. This option is valid for all junctions except for the type of local.-T {resource | resource_group}Specifies the name of the resource or resource group. This option is required only when the -b gso option is used. This option is valid for all junctions except for the type of local.-u uuidSpecifies the Universally Unique Identifier (UUID) of a back-end server connected to WebSEAL by using a stateful junction (-s option). This option is valid for all junctions except for the type of local.-U "user_name"Specifies the WebSEAL server user name. This option requires the -B and -W options. WebSEAL uses the BA header information to authenticate to the back-end server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.-v virtual_hostname[:HTTP-port]Specifies the virtual host name for the back-end server. This option supports multiple virtual hosts being served from the same Web server. Use -v when the back-end junction server expects a host name header different from the DNS name of the server. This option is valid for all junctions except for the type of local. For mutual junctions this value corresponds to the virtual host which is used for HTTP requests.-V virtual_hostname[:HTTPS-port]Specifies the virtual host name for the back-end server. This option supports multiple virtual hosts being served from the same Web server. Use -V when the back-end junction server expects a host name header different from the DNS name of the server. This option is only used for mutual junctions and corresponds to the virtual host which is used for HTTPS requests.-wIndicates Microsoft Windows file system support. This option provides all of the functionality provided by the –i junction option but disallows requests that contain file names that might be interpreted as Windows file name aliases. This option is valid for all junctions except for the type of local. Local junctions prohibit URLs that contain Windows file name aliases on Windows but allow such URLs on other platforms.-W "password"Specifies the WebSEAL server password. This option requires the -B and -U options. WebSEAL uses the BA header information to authenticate to the back-end server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.-x Creates a transparent path junction. This option is valid for all junctions except for the type of local .-Y Enables Tivoli Federated Identity Manager single-signon (SSO) for the junction. Before using this option, you must first configure the WebSEAL configuration file to support Tivoli Federated Identity Manager single-signon over junctions. -Z keyfile_pwdSpecifies the password of the keyfile used to encrypt LTPA cookie data. This option requires the -A and -F options. The -A, -F, and -Z options all must be used together. This option is valid for all junctions except for the type of local.-h host_nameRequired option for non-local junctions. Specifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example: www.example.com-t typeRequired option. Specifies the type of junction; must be one of the following types: tcptcpproxysslsslproxylocal Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. For more information about gathering statistics, see the Troubleshooting topics in the Knowledge Center.. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and returns an error message.1The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example (entered as one line) creates a basic WebSEAL junction /pubs on the default-webseald-cruz WebSEAL server. The junction type is TCP, and the host name is doc.tivoli.com: pdadmin> server task default-webseald-cruz create -t tcp -h doc.tivoli.com /pubsOutput is similar to: Created junction at /pubsThe following example (entered as one line) limits worker thread consumption on a per junction basis with a soft thread limit of 60 and a hard thread limit of 80 on the /myjunction junction: pdadmin> server task default-webseald-cruz create -t tcp -h cruz.dallas.ibm.com -l 60 -L 80 /myjunction See also server task addThe server task add command adds an additional back-end application server to an existing WebSEAL junction. server task deleteThe server task delete command deletes a WebSEAL junction point. server task removeThe server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point. server task showThe server task show command displays detailed information about the specified WebSEAL junction. Command reference

server task create

The server task create command creates a WebSEAL junction point.

Requires authentication (administrator ID and password) to use this command.

Syntax

For local junctions:

server task instance_name-webseald-host_name create -t type [options] junction_point

For non-local junctions:

server task instance_name-webseald-host_name create -t type -h host_name [options] junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

options

Specifies the options that you can use with the server task create command. The options include:

-a address

Specifies the local IP address for WebSEAL to use when communicating with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system.

If an address is supplied for a particular junction, WebSEAL is modified to bind to this local address for all communication with the junctioned server.

-A

Enables or disables lightweight third-party authentication mechanism (LTPA) junctions. This option requires the -F and -Z options. The -A, -F, and -Z options all must be used together.

This option is valid for all junctions except for the type of local.

-2

You can use this option in conjunction with the -A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

-b BA_value

Defines how the WebSEAL server passes the HTTP BA authentication information to the back-end server, which is one of the following values:

filter (default)

ignore

supply

gso

This option is valid for all junctions except for the type of local.

-B

Indicates that WebSEAL uses the BA header information to authenticate to the back-end server and to provide mutual authentication over SSL. This option requires the -U and -W options.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

-c header_type

Inserts the Security Access Manager client identity in HTTP headers across the junction. The header_type argument can include any combination of the following Security Access Manager HTTP header types:

{iv-user|iv-user-l}

iv-groups

iv-creds

all

The header types must be comma separated, and cannot have spaces between the types. For example: -c iv_user,iv_groups

Specifying -c all is the same as specifying -c iv-user,iv-groups,iv-creds.

This option is valid for all junctions except for the type of local.

-C

Indicates single signon from a front-end WebSEAL server to a back-end WebSEAL server. The -C option is not mutual authentication.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

-D "dn"

Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

-e encoding_type

Specifies the encoding to use when generating HTTP headers for junctions. This encoding applies to headers that are generated with both the -c junction option and tag-value. The following values for encoding are supported:

utf8_bin

WebSEAL sends the headers in UTF-8.

utf8_uri

WebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.

lcp_bin

WebSEAL sends the headers in the local code page of the WebSEAL server.

lcp_uri

WebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them.

This option is valid for all junctions except for the type of local.

-f

Forces the replacement of an existing junction.

This option is used for junctions that were created with any junction type.

-F keyfile

Specifies the name of the keyfile used to encrypt LTPA cookie data.

The -F option requires -A and -Z options. The -A, -F, and -Z options all must be used together.

This option is valid for all junctions except for the type of local.

-H host_name

Specifies the DNS host name or IP address of the proxy server. The -P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example:

proxy.www.example.com

This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.

-i

Indicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file.

Junctions to such a Web server should be created with the -i or -w option. ACLs or POPs that are attached to objects beneath the junction point should use the lowercase object name. An ACL attached to /junction/index.htm will apply to all of the following requests if the -i or -w option is used:

/junction/INDEX.HTM

/junction/index.htm

/junction/InDeX.HtM

This option is valid for all junctions except for the type of local. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.

-I

Ensures a unique Set-Cookie header name attribute when using the -j option to modify server-relative URLs in requests.

This option is valid for all junctions except for the type of local.

-j

Supplies junction identification in a cookie to handle script-generated server-relative URLs.

This option is valid for all junctions except for the type of local.

-J trailer,inhead,onfocus,xhtml10

Controls the junction cookie JavaScript block.

Use –J trailer to append (rather than prepend) the junction cookie JavaScript to HTML page returned from back-end server.

Use –J inhead to insert the JavaScript block between <head> </head> tags for HTML 4.01 compliance.

Use –J onfocus to use the onfocus event handler in the JavaScript to ensure the correct junction cookie is used in a multiple-junction/multiple-browser-window scenario.

Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and XHTML 1.0 compliant.

For complete details on this option, see Control on the junction cookie JavaScript block.

-k

Sends WebSEAL session cookies to the junction server. By default, cookies are removed from requests that are sent to the server.

This option is valid for all junctions except for the type of local.

-K "key_label"

Specifies the key label of the client personal certificate that WebSEAL should present to the back-end server. Use of this option allows the junction server to authenticate the WebSEAL server using client certificates.

This option is valid only with junctions that were created with the type of ssl and sslproxy.

-l percent

Defines the soft limit for consumption of worker threads.

This option is valid for all junctions except for the type of local.

-L percent

Defines the hard limit for consumption of worker threads.

This option is valid for all junctions except for the type of local.

-n

Indicates that no modification of the names of non-domain cookies are to be made. Use when client side scripts depend on the names of cookies.

By default, if a junction is listed in the JMT or if the -j junction option is used, WebSEAL will modify the names of non-domain cookies that are returned from the junction to prepend AMWEBJCT!junction_point.

This option is valid for all junctions except for the type of local.

-p port

Specifies the TCP port of the back-end third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions.

This option is valid for all junctions except for the type of local.

-P port

For proxy junctions that were created with the type of tcpproxy or sslproxy this option specifies the TCP port number for the HTTP proxy server. The -P option is required when the -H option is used.

This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.

-q path

Required option for back-end Windows servers. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option will indicates to WebSEAL the new URL to the file.

This option is valid for all junctions except for the type of local.

-r

Inserts the incoming IP address into the HTTP header across the junction. This option is valid for all junctions except for the type of local.

-R

Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the -R option is not used and a rule failure occurs, WebSEAL will not allow the request to proceed. This option is valid for all junctions except for the type of local.

-s

Indicates that the junction support stateful applications. By default, junctions are not stateful. This option is valid for all junctions except for the type of local.

-S

Specifies the name of the forms single signon configuration file. This option is valid for all junctions except for the type of local.

-T {resource | resource_group}

Specifies the name of the resource or resource group. This option is required only when the -b gso option is used. This option is valid for all junctions except for the type of local.

-u uuid

Specifies the Universally Unique Identifier (UUID) of a back-end server connected to WebSEAL by using a stateful junction (-s option). This option is valid for all junctions except for the type of local.

-U "user_name"

Specifies the WebSEAL server user name. This option requires the -B and -W options. WebSEAL uses the BA header information to authenticate to the back-end server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.

-v virtual_hostname[:HTTP-port]

Specifies the virtual host name for the back-end server. This option supports multiple virtual hosts being served from the same Web server. Use -v when the back-end junction server expects a host name header different from the DNS name of the server. This option is valid for all junctions except for the type of local. For mutual junctions this value corresponds to the virtual host which is used for HTTP requests.

-V virtual_hostname[:HTTPS-port]

Specifies the virtual host name for the back-end server. This option supports multiple virtual hosts being served from the same Web server. Use -V when the back-end junction server expects a host name header different from the DNS name of the server. This option is only used for mutual junctions and corresponds to the virtual host which is used for HTTPS requests.

-w

Indicates Microsoft Windows file system support. This option provides all of the functionality provided by the –i junction option but disallows requests that contain file names that might be interpreted as Windows file name aliases. This option is valid for all junctions except for the type of local. Local junctions prohibit URLs that contain Windows file name aliases on Windows but allow such URLs on other platforms.

-W "password"

Specifies the WebSEAL server password. This option requires the -B and -U options. WebSEAL uses the BA header information to authenticate to the back-end server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.

-x

Creates a transparent path junction.

This option is valid for all junctions except for the type of local .

-Y

Enables Tivoli® Federated Identity Manager single-signon (SSO) for the junction.

Note: Before using this option, you must first configure the WebSEAL configuration file to support Tivoli Federated Identity Manager single-signon over junctions.

-Z keyfile_pwd

Specifies the password of the keyfile used to encrypt LTPA cookie data. This option requires the -A and -F options. The -A, -F, and -Z options all must be used together. This option is valid for all junctions except for the type of local.

-h host_name

Required option for non-local junctions. Specifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example:

www.example.com

-t type

Required option. Specifies the type of junction; must be one of the following types:

tcp

tcpproxy

ssl

sslproxy

local

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Note:

For more information about gathering statistics, see the Troubleshooting topics in the Knowledge Center..

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and returns an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example (entered as one line) creates a basic WebSEAL junction /pubs on the default-webseald-cruz WebSEAL server. The junction type is TCP, and the host name is doc.tivoli.com:

pdadmin> server task default-webseald-cruz create -t tcp
-h doc.tivoli.com /pubs

Output is similar to:

Created junction at /pubs

The following example (entered as one line) limits worker thread consumption on a per junction basis with a soft thread limit of 60 and a hard thread limit of 80 on the /myjunction junction:

pdadmin> server task default-webseald-cruz create -t tcp
-h cruz.dallas.ibm.com -l 60 -L 80 /myjunction

See also

server task add

server task delete

server task remove

server task show

Parent topic: Command reference

server task deleteserver task deleteWebSEAL server task delete commandThe server task delete command deletes a WebSEAL junction point.server task commandsdeletejunctionsdelete junctioned serverjunctioned serversdeleteserver commandsserver task deleteRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name delete junction_point Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example deletes the junction point /pubs from the WebSEAL server default-webseald-abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com delete /pubs See also server task addThe server task add command adds an additional back-end application server to an existing WebSEAL junction. server task createThe server task create command creates a WebSEAL junction point. server task removeThe server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point. server task showThe server task show command displays detailed information about the specified WebSEAL junction. Command reference

server task delete

The server task delete command deletes a WebSEAL junction point.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name delete junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the junction point /pubs from the WebSEAL server default-webseald-abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com delete /pubs

See also

server task add

server task create

server task remove

server task show

Parent topic: Command reference

server task dynurl updateserver task dynurl updateserver task dynurl updateThe server task dynurl update command reloads the dynamic URL configuration file.server commandsserver task dynurl updateserver task commandsdynurl updatedynamic URLsreloadingURLreloading dynamicRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name dynurl update Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example reloads the dynamic URL configuration file: pdadmin> server task default-webseald-abc.ibm.com dynurl update See also None. Command reference

server task dynurl update

The server task dynurl update command reloads the dynamic URL configuration file.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name dynurl update

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example reloads the dynamic URL configuration file:

pdadmin> server task default-webseald-abc.ibm.com dynurl update

See also

None.

Parent topic: Command reference

server task helpserver task helpserver task helpserver commandsserver task helpserver task commandshelpLists detailed help information about a specific server task command. Requires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name help task Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.taskLists detailed help for the specified task, such as the command syntax, the description, and the valid options. Authorization No special authorization required. Return codes 0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example displays output after requesting help for the server task add command at the abc.ibm.com WebSEAL server: pdadmin> server task default-webseald-abc.ibm.com help addOutput is similar to: Command: add <options> <junction point> Description: Adds an additional server to a junction Usage: TCP and SSL Junction Flags -iServer treats URLs as case insensitive. -h <hostname>Target host (required flag). -p <port>TCP port of server. Default is 80 for TCP junctions 443 for SSL junctions. -H <hostname>Proxy hostname. -P <port>Port of proxy server. -D <"DN">The Distinguished Name of the server -q <relative url> URL for query_contents script. -u <UUID>(stateful junctions only). -v <hostname>Virtual hostname for server. -wWin32 file system support. -jScripting support for junction. Common Flags <junction point>Where to create the junctionThe following example displays the output after requesting help for the server task create command at the abc.ibm.com WebSEAL server: pdadmin> server task default-webseald-abc.ibm.com help createOutput is similar to: Command: create -t <type> <options> <junction point> Description: Creates a new junction Usage: create -t <type> <options> <junction point> TCP and SSL Junction Flags ... Common Flags -t <type>Type of junction. One of: tcp, tcpproxy, ssl, sslproxy, local. -fForce the creation: overwrite existing junction. -RWebSEAL will send the Boolean Rule Header to these junctions when a rule failure reason is provided. <junction point>Where to create the junction See also help Command reference

server task help

Lists detailed help information about a specific server task command.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name help task

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

task

Lists detailed help for the specified task, such as the command syntax, the description, and the valid options.

Authorization

No special authorization required.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays output after requesting help for the server task add command at the abc.ibm.com WebSEAL server:

pdadmin> server task default-webseald-abc.ibm.com help add

Output is similar to:

Command:
add <options> <junction point>
Description:
Adds an additional server to a junction
Usage:
TCP and SSL Junction Flags
-iServer treats URLs as case insensitive.
-h <hostname>Target host (required flag).
-p <port>TCP port of server.
Default is 80 for TCP junctions
443 for SSL junctions.
-H <hostname>Proxy hostname.
-P <port>Port of proxy server.
-D <"DN">The Distinguished Name of the server
-q <relative url> URL for query_contents script.
-u <UUID>(stateful junctions only).
-v <hostname>Virtual hostname for server.
-wWin32 file system support.
-jScripting support for junction.
Common Flags
<junction point>Where to create the junction

The following example displays the output after requesting help for the server task create command at the abc.ibm.com WebSEAL server:

pdadmin> server task default-webseald-abc.ibm.com help create

Output is similar to:

Command:
create -t <type> <options> <junction point>
Description:
Creates a new junction
Usage:
create -t <type> <options> <junction point>

TCP and SSL Junction Flags
...
Common Flags
-t <type>Type of junction.
One of: tcp, tcpproxy, ssl, sslproxy, local.
-fForce the creation: overwrite existing junction.
-RWebSEAL will send the Boolean Rule Header to these
junctions when a rule failure reason is provided.
<junction point>Where to create the junction

See also

help

Parent topic: Command reference

server task jmtserver task jmtWebSEAL server task jmt commandThe server task jmt command clears or loads the junction mapping table data.server commandsserver task jmtserver task commandsjmtjunction mapping tableloadclearJMTRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name jmt load server task instance_name-webseald-host_name jmt clear Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.jmt clearClears the junction mapping table data.jmt loadLoads the junction mapping table data, which is located in the jmt.conf file. This file does not exist by default, so you must create the file and add data. Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example loads the junction mapping table data from the jmt.conf file so that WebSEAL has knowledge of the new information: pdadmin> server task default-webseald-abc.ibm.com jmt loadOutput is similar to: JMT table successfully loaded. See also server task reloadThe server task reload command reloads the junction mapping table from the database. Command reference

server task jmt

The server task jmt command clears or loads the junction mapping table data.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name jmt load

server task instance_name-webseald-host_name jmt clear

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

jmt clear

Clears the junction mapping table data.

jmt load

Loads the junction mapping table data, which is located in the jmt.conf file. This file does not exist by default, so you must create the file and add data.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example loads the junction mapping table data from the jmt.conf file so that WebSEAL has knowledge of the new information:

pdadmin> server task default-webseald-abc.ibm.com jmt load

Output is similar to:

JMT table successfully loaded.

See also

server task reload

Parent topic: Command reference

server task listserver task listWebSEAL server task list commandThe server task list command lists all junction points on a WebSEAL server or instance.server commandsserver task listserver task commandslistjunctionslistRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name list Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. Authorization Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/per_junction_point object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example lists all junction points on the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz listOutput is similar to: / /ssljct /tcpjct See also server task addThe server task add command adds an additional back-end application server to an existing WebSEAL junction. server task createThe server task create command creates a WebSEAL junction point. server task deleteThe server task delete command deletes a WebSEAL junction point. server task removeThe server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point. server task showThe server task show command displays detailed information about the specified WebSEAL junction. Command reference

server task list

The server task list command lists all junction points on a WebSEAL server or instance.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name list

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/per_junction_point object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists all junction points on the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz list

Output is similar to:

/
/ssljct
/tcpjct

See also

server task add

server task create

server task delete

server task remove

server task show

Parent topic: Command reference

server task offlineserver task offlineWebSEAL server task offline commandThe server task offline command places the server that is located at this junction in an offline operational state.server commandsserver task offlineserver task commandsofflinejunctionsoffline operational stateserver task offlineRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name offline [–i server_uuid] junction_point Description The server task offline command places the server that is located at this junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are at this junction are placed in an offline operational state. Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidSpecifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are located at this junction are placed in an offline operational state. Use the server task show command to determine the ID of a specific back-end server.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example places the backappl server located at the /pubs junction point in an offline operational state. To determine the UUID of this junctioned server, run the server task show command: pdadmin> server task default-webseald-cruz show /pubsOutput is similar to: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Throttled Throttled at: 2005-03-01-17:07:24 Hostname: backapp1.diamond.example.com ... Current requests: 0 ... Place this server in an offline operational state (entered as one line): pdadmin> server task default-webseald-cruz offline -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See also server task onlineThe server task online command places the server that is located at this junction in an online operational state. server task throttleThe server task throttle command places the server that is located at this junction in a throttled operational state. server task virtualhost offlineThe server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state. server task virtualhost onlineThe server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. server task virtualhost throttleThe server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state. Command reference

server task offline

The server task offline command places the server that is located at this junction in an offline operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name offline [–i server_uuid] junction_point

Description

The server task offline command places the server that is located at this junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are at this junction are placed in an offline operational state.

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

Specifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are located at this junction are placed in an offline operational state. Use the server task show command to determine the ID of a specific back-end server.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example places the backappl server located at the /pubs junction point in an offline operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Place this server in an offline operational state (entered as one line):

pdadmin> server task default-webseald-cruz offline
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task online

server task throttle

server task virtualhost offline

server task virtualhost online

server task virtualhost throttle

Parent topic: Command reference

server task onlineserver task onlineWebSEAL server task online commandThe server task online command places the server that is located at this junction in an online operational state. server commandsserver task onlineserver task commandsonlineserver task onlinejunctionsonline operational stateRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name online [–i server_uuid] junction_point Description The server task online command places the server that is located at this junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are located at this junction are placed in an online operational state. Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidSpecifies the UUID of the server to place in an online operational state. If a server is not specified, all servers that are located at this junction are placed in an online operational state. Use the server task show command to determine the ID of a specific back-end server.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example places the backappl server located at the /pubs junction point in an online operational state. To determine the UUID of this junctioned server, run the server task show command: pdadmin> server task default-webseald-cruz show /pubsOutput is similar to: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Offline Hostname: backapp1.diamond.example.com ... Current requests: 0 ... Place this server in an online operational state (entered as one line): pdadmin> server task default-webseald-cruz online -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See also server task offlineThe server task offline command places the server that is located at this junction in an offline operational state. server task throttleThe server task throttle command places the server that is located at this junction in a throttled operational state. server task virtualhost offlineThe server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state. server task virtualhost onlineThe server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. server task virtualhost throttleThe server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state. Command reference

server task online

The server task online command places the server that is located at this junction in an online operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name online [–i server_uuid] junction_point

Description

The server task online command places the server that is located at this junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are located at this junction are placed in an online operational state.

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

Specifies the UUID of the server to place in an online operational state. If a server is not specified, all servers that are located at this junction are placed in an online operational state. Use the server task show command to determine the ID of a specific back-end server.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example places the backappl server located at the /pubs junction point in an online operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Offline
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Place this server in an online operational state (entered as one line):

pdadmin> server task default-webseald-cruz online
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task offline

server task throttle

server task virtualhost offline

server task virtualhost online

server task virtualhost throttle

Parent topic: Command reference

server task refresh all_sessionsserver task refresh all_sessionsWebSEAL server task refresh all_sessions commandThe server task refresh all_sessions command refreshes the credential for all sessions for a specified user.server commandsserver task refresh all_sessionsserver task commandsrefresh all_sessionscredentialsrefreshingWebSEALRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name refresh all_sessions user_id Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.user_idRefreshes the credential for all sessions that are associated with the specified user. Examples of user names are dlucas, sec_master, and "Mary Jones". Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example refreshes all sessions for the test_user user: pdadmin> server task default-webseald-cruz refresh all_sessions test_user See also server task terminate sessionThe server task terminate session command terminates a user session using a session ID. server task terminate all_sessionsThe server task terminate all_sessions command terminates all user sessions for a specific user. Command reference

server task refresh all_sessions

The server task refresh all_sessions command refreshes the credential for all sessions for a specified user.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name refresh all_sessions user_id

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

user_id

Refreshes the credential for all sessions that are associated with the specified user. Examples of user names are dlucas, sec_master, and "Mary Jones".

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example refreshes all sessions for the test_user user:

pdadmin> server task default-webseald-cruz refresh all_sessions test_user

See also

server task terminate session

server task terminate all_sessions

Parent topic: Command reference

server task reloadserver task reloadWebSEAL server task reload commandThe server task reload command reloads the junction mapping table from the database. server commandsserver task reloadserver task commandsreloadjunction mapping tablereloadRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name reload Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example reloads the junction mapping table from the database: pdadmin> server task default-webseald-abc.ibm.com reload See also server task jmtThe server task jmt command clears or loads the junction mapping table data. Command reference

server task reload

The server task reload command reloads the junction mapping table from the database.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name reload

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example reloads the junction mapping table from the database:

pdadmin> server task default-webseald-abc.ibm.com reload

See also

server task jmt

Parent topic: Command reference

server task removeserver task removeWebSEAL server task remove commandThe server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point.server task commandsremoveserver commandsserver task removejunctionsremove junctioned serverjunctioned serverremoveRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name remove –i server_uuid junction_point Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidSpecifies the UUID of the server to be removed from the junction point. See the server task show command for details about obtaining the UUID.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example removes the backappl junctioned server from the /pubs junction point. To determine the UUID of the server to be removed, run the server task show command: pdadmin> server task default-webseald-cruz show /pubsOutput is similar to: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running ... Hostname: backapp1.cruz.ibm.com ... Remove the server from the junction (entered as one line): pdadmin> server task default-webseald-cruz remove -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See also server task addThe server task add command adds an additional back-end application server to an existing WebSEAL junction. server task createThe server task create command creates a WebSEAL junction point. server task deleteThe server task delete command deletes a WebSEAL junction point. server task showThe server task show command displays detailed information about the specified WebSEAL junction. Command reference

server task remove

The server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name remove –i server_uuid junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

Specifies the UUID of the server to be removed from the junction point. See the server task show command for details about obtaining the UUID.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example removes the backappl junctioned server from the /pubs junction point. To determine the UUID of the server to be removed, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
...
Hostname: backapp1.cruz.ibm.com
...

Remove the server from the junction (entered as one line):

pdadmin> server task default-webseald-cruz remove
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task add

server task create

server task delete

server task show

Parent topic: Command reference

server task server restartserver task server restartWebSEAL server task server restart commandThe server task server restart command restarts a WebSEAL server by using the Security Access Manager server task framework. server task commandsserver restartjunctioned serversrestartserver commandsserver task server restartserver task server restartRequires authentication (administrator ID and password) to use this command.Syntax server task server_name server restart Options server_nameSpecifies the name of the WebSEAL server to be restarted. Authorization Users and groups that require access to this command must be given the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has permission by default. Return codes 0The command that completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. Even if the command is successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example restarts server03: pdadmin> server task server03 server restart Command reference

server task server restart

The server task server restart command restarts a WebSEAL server by using the Security Access Manager server task framework.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task server_name server restart

Options

server_name

Specifies the name of the WebSEAL server to be restarted.

Authorization

Users and groups that require access to this command must be given the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command that completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command is successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example restarts server03:

pdadmin> server task server03 server restart

Parent topic: Command reference

server task showserver task showWebSEAL server task show commandThe server task show command displays detailed information about the specified WebSEAL junction.server task commandsshowjuctionslist detailsjunctioned serversjunctioned serverslist detailsserver commandsserver task showRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name show junction_point Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted. Authorization Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example shows information for the local root junction point / on the WebSEAL server abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com showOutput is similar to: Junction point: / Type: Local Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Root Directory: /opt/pdweb/www-default/docs ... Server 1: ID: 78a1eb8c-074a-11d9-abda-00096bda9439 ... See also server task addThe server task add command adds an additional back-end application server to an existing WebSEAL junction. server task createThe server task create command creates a WebSEAL junction point. server task deleteThe server task delete command deletes a WebSEAL junction point. server task removeThe server task remove command removes the specified installed WebSEAL server or instance from a WebSEAL junction point. Command reference

server task show

The server task show command displays detailed information about the specified WebSEAL junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name show junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example shows information for the local root junction point / on the WebSEAL server abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com show

Output is similar to:

Junction point: /
Type: Local
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Root Directory: /opt/pdweb/www-default/docs
...
Server 1:
ID: 78a1eb8c-074a-11d9-abda-00096bda9439
...

See also

server task add

server task create

server task delete

server task remove

Parent topic: Command reference

server task server syncserver task server syncWebSEAL server task server sync commandThe server task server sync command synchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework. server task commandsserver syncjunctioned serverssynchronizeserver commandsserver task server syncRequires authentication (administrator ID and password) to use this command.The two WebSEAL servers must be of the same type. The WebSEAL server type is either a:WebSEAL running on an appliance.WebSEAL running on a standard operating system.Syntax server task webseal_server server sync server_name Options webseal_serverSpecifies the fully qualified server name of the installed WebSEAL instance. The webseal_server is the target. server_nameSpecifies the name of the WebSEAL server from which data is extracted. Configuration data on the host system is backed up and then synchronized with this data. The server_name is the source. Authorization Users and groups that require access to this command must be given the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. The sec_master administrative user has permission by default. Return codes 0The command that completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. Even if the command is successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example synchronizes configuration data with server master-webseald-abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com server sync master-webseald-abc.ibm.com Command reference

server task server sync

The server task server sync command synchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework.

Requires authentication (administrator ID and password) to use this command.

Note: The two WebSEAL servers must be of the same type. The WebSEAL server type is either a:

WebSEAL running on an appliance.

WebSEAL running on a standard operating system.

Syntax

server task webseal_server server sync server_name

Options

webseal_server

Specifies the fully qualified server name of the installed WebSEAL instance. The webseal_server is the target.

server_name

Specifies the name of the WebSEAL server from which data is extracted. Configuration data on the host system is backed up and then synchronized with this data. The server_name is the source.

Authorization

Users and groups that require access to this command must be given the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. The sec_master administrative user has permission by default.

Return codes

0

The command that completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command is successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example synchronizes configuration data with server master-webseald-abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com server sync
master-webseald-abc.ibm.com

Parent topic: Command reference

server task terminate all_sessionsserver task terminate all_sessionsWebSEAL server task terminate all_sessions commandThe server task terminate all_sessions command terminates all user sessions for a specific user. server commandsserver task terminate all_sessionsserver task terminate all_sessionsserver task commandsterminate all_sessionsuser sessionsterminate allRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name terminate all_sessions user_id Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.user_idSpecifies the name of the user. Examples of user names are dlucas, sec_master, and "Mary Jones". Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example terminates all sessions for the dlucas user on the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz terminate all_sessions dlucas See also server task terminate sessionThe server task terminate session command terminates a user session using a session ID. server task refresh all_sessionsThe server task refresh all_sessions command refreshes the credential for all sessions for a specified user. Command reference

server task terminate all_sessions

The server task terminate all_sessions command terminates all user sessions for a specific user.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name terminate all_sessions user_id

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

user_id

Specifies the name of the user. Examples of user names are dlucas, sec_master, and "Mary Jones".

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example terminates all sessions for the dlucas user on the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz terminate all_sessions dlucas

See also

server task terminate session

server task refresh all_sessions

Parent topic: Command reference

server task terminate sessionserver task terminate sessionWebSEAL server task terminate session commandThe server task terminate session command terminates a user session using a session ID.server commandsserver task terminate sessionserver task terminate sessionserver task commandsterminate sessionuser sessionsterminateRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name terminate session session_id Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.session_idSpecifies the ID of a user session. Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example (entered as one line) terminates a specific session on the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz terminate session 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 See also server task refresh all_sessionsThe server task refresh all_sessions command refreshes the credential for all sessions for a specified user. server task terminate all_sessionsThe server task terminate all_sessions command terminates all user sessions for a specific user. Command reference

server task terminate session

The server task terminate session command terminates a user session using a session ID.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name terminate session session_id

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

session_id

Specifies the ID of a user session.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example (entered as one line) terminates a specific session on the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz terminate
session 6fc3187a-ea1c-11d7-8f4e-09267e38aa77

See also

server task refresh all_sessions

server task terminate all_sessions

Parent topic: Command reference

server task throttleserver task throttleWebSEAL server task throttle commandThe server task throttle command places the server that is located at this junction in a throttled operational state.server commandsserver task throttleserver task throttleserver task commandsthrottlejunctionsthrottle operational stateRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name throttle [–i server_uuid] junction_point Description The server task throttle command places the server that is located at this junction in a throttled operational state. Only requests from users who have created a session with WebSEAL prior to the invocation of this command continue to have their requests processed by the specified server. If a server is not specified, all servers that are located at this junction are placed in a throttled operational state. Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidSpecifies the UUID of the server to throttle. If a server is not specified, all servers that are located at this junction are placed in a throttled operational state. Use the server task show command to determine the ID of a specific back-end server.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example places the backappl server located at the /pubs junction point in a throttled operational state. To determine the UUID of this junctioned server, run the server task show command: pdadmin> server task default-webseald-cruz show /pubsOutput is similar to: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Online Hostname: backapp1.diamond.example.com ... Current requests: 0 ... Place this server in a throttled operational state (entered as one line): pdadmin> server task default-webseald-cruz throttle -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See also server task offlineThe server task offline command places the server that is located at this junction in an offline operational state. server task onlineThe server task online command places the server that is located at this junction in an online operational state. server task virtualhost offlineThe server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state. server task virtualhost onlineThe server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. server task virtualhost throttleThe server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state. Command reference

server task throttle

The server task throttle command places the server that is located at this junction in a throttled operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name throttle [–i server_uuid] junction_point

Description

The server task throttle command places the server that is located at this junction in a throttled operational state. Only requests from users who have created a session with WebSEAL prior to the invocation of this command continue to have their requests processed by the specified server. If a server is not specified, all servers that are located at this junction are placed in a throttled operational state.

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

Specifies the UUID of the server to throttle. If a server is not specified, all servers that are located at this junction are placed in a throttled operational state. Use the server task show command to determine the ID of a specific back-end server.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the back-end server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example places the backappl server located at the /pubs junction point in a throttled operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is similar to:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Online
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Place this server in a throttled operational state (entered as one line):

pdadmin> server task default-webseald-cruz throttle
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task offline

server task online

server task virtualhost offline

server task virtualhost online

server task virtualhost throttle

Parent topic: Command reference

server task virtualhost addserver task virtualhost addWebSEAL server task virtualhost add commandThe server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction. server commandsserver task virtualhost addserver task commandsvirtualhost addjunctionsadding virtual host junctionsjunctioned serveradding virtual host junctionsRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost add –h host_name [options] vhost_label Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.options Specifies the options that you can use with the server task virtualhost add command. These options include: –D "dn"Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US" This option is valid only with junctions that were created with the type of ssl or sslproxy.–H host_nameSpecifies the DNS host name or IP address of the proxy server. Valid values for host_name include any valid IP host name. For example: proxy.www.example.com This option is used for junctions that were created with the type of tcpproxy or sslproxy.–iIndicates that the WebSEAL server does not treat URLs as case-sensitive. This option is used for junctions that were created with the type of tcp or ssl.–p portSpecifies the TCP port of the back-end server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.–P portSpecifies the TCP port of the proxy server. The default value is 7138. For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater then 1000 that is currently not being used. This option is used for junctions that were created with the type of tcpproxy or sslproxy.–q pathRequired option for back-end Windows virtual hosts. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file. This option is valid for all junction types except localtcp and localssl.–u uuidSpecifies the UUID of this back-end server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.–wIndicates Microsoft Windows file system support. This option is used for junctions that were created with the type of tcp or ssl.vhost_labelSpecifies the label name of the virtual host junction.–h host_nameRequired option. Specifies the DNS host name or IP address of the target server. Valid values for host_name include any valid IP host name. For example: www.example.com Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example (entered as one line) adds an additional server with host name xyz.ibm.com to an existing virtual host junction with the label support-vhost-http, located on the WebSEAL server abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com virtualhost add -h xyz.ibm.com support-vhost-http See also server task virtualhost createThe server task virtualhost create command creates a virtual host junction. server task virtualhost deleteThe server task virtualhost delete command deletes a virtual host junction. server task virtualhost listThe server task virtualhost list command lists all configured virtual host junctions by label name. server task virtualhost removeThe server task virtualhost remove command removes the specified server from a virtual host junction. server task virtualhost showThe server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. Command reference

server task virtualhost add

The server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost add –h host_name [options] vhost_label

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

options

Specifies the options that you can use with the server task virtualhost add command. These options include:

–D "dn"

Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–H host_name

Specifies the DNS host name or IP address of the proxy server.

Valid values for host_name include any valid IP host name. For example:

proxy.www.example.com

This option is used for junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL server does not treat URLs as case-sensitive.

This option is used for junctions that were created with the type of tcp or ssl.

–p port

Specifies the TCP port of the back-end server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.

–P port

Specifies the TCP port of the proxy server. The default value is 7138.

For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater then 1000 that is currently not being used.

This option is used for junctions that were created with the type of tcpproxy or sslproxy.

–q path

Required option for back-end Windows virtual hosts. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file.

This option is valid for all junction types except localtcp and localssl.

–u uuid

Specifies the UUID of this back-end server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.

–w

Indicates Microsoft Windows file system support.

This option is used for junctions that were created with the type of tcp or ssl.

vhost_label

Specifies the label name of the virtual host junction.

–h host_name

Required option. Specifies the DNS host name or IP address of the target server. Valid values for host_name include any valid IP host name. For example:

www.example.com

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example (entered as one line) adds an additional server with host name xyz.ibm.com to an existing virtual host junction with the label support-vhost-http, located on the WebSEAL server abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com virtualhost add
-h xyz.ibm.com support-vhost-http

See also

server task virtualhost create

server task virtualhost delete

server task virtualhost list

server task virtualhost remove

server task virtualhost show

Parent topic: Command reference

server task virtualhost createserver task virtualhost createWebSEAL server task virtualhost create commandThe server task virtualhost create command creates a virtual host junction.server task commandsvirtualhost createserver task virtualhost createjunctionscreate virtual host junctionsjunctioned servercreate virtual host junctionsserver commandsserver task virtualhost createRequires authentication (administrator ID and password) to use this command.Syntax For local junctions:server task instance_name-webseald-host_name virtualhost create –t type –v virtual_host_name [options] vhost_labelFor non-local junctions:server task instance_name-webseald-host_name virtualhost create –t type –h host_name [options] vhost_label Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify the full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.optionsSpecifies the options that you can use with the server task virtualhost create command. These options include: –A Enables a virtual host junction to support the lightweight third-party authentication mechanism (LTPA). This option requires the –F and –Z options. The –A, –F, and –Z options all must be used together. This option is valid for all junction types except localtcp and localssl.-2You can use this option in conjunction with the -A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.–b BA_valueDefines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the back-end virtual host, which is one of the following values: filterignoresupplygso This option is valid for all junction types except localtcp and localssl. The default value is filter.–B Indicates that WebSEAL uses the BA header information to authenticate to the back-end virtual host and to provide mutual authentication over SSL. This option requires the –U and –W options. This option is valid only with junctions that were created with the type of ssl or sslproxy.–c header_typeInserts the Security Access Manager client identity in HTTP headers across the virtual host junction. The header_type argument can include any combination of the following Security Access Manager HTTP header types: {iv-user|iv-user-l}iv-groupsiv-credsall The header types must be comma separated, and cannot have a spaces between the types. For example: -c iv_user,iv_groups Specifying –c all is the same as specifying –c iv-user,iv-groups,iv-creds. This option is valid for all junction types except localtcp and localssl.–C Supports mutual authentication by enabling the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server in a Basic Authentication (BA) header. Additionally, the –C option enables single signon functionality provided by the –c option. This option is valid only with junctions that were created with the type of ssl or sslproxy.–D "dn"Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US" This option is valid only with junctions that were created with the type of ssl or sslproxy.–e encoding_typeSpecifies the encoding to use when generating HTTP headers for virtual host junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. Possible values for encoding are as follows: utf8_binWebSEAL sends the headers in UTF-8.utf8_uriWebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.lcp_binWebSEAL sends the headers in the local code page of the WebSEAL server.lcp_uriWebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them. This option is valid for all junction types except localtcp and localssl.–fForces the replacement (overwrite) of an existing virtual host junction. This option is used for junctions that were created with the any junction type.–F "keyfile"Specifies the name of the keyfile used to encrypt LTPA cookie data. The –F option requires –A and –Z options. The –A, –F, and –Z options all must be used together. This option is valid for all junction types except localtcp and localssl.–g vhost_labelThe –g option causes a second additional virtual host junction to share the same protected object space as the initial virtual host junction. This option is appropriate for junction pairs only (two junctions using complementary protocols). The option does not support the association of more than two junctions.–H host_nameSpecifies the DNS host name or IP address of the proxy server. The –P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example: proxy.www.example.comThis option is valid only with junctions that were created with the type of tcpproxy or sslproxy.–iIndicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file. Junctions to such a Web server should be created with the –i or –w option. ACLs or POPs that are attached to objects beneath the junction point should use the lower case object name. An ACL attached to /junction/index.htm will apply to all of the following requests if the –i or –w option is used: /junction/INDEX.HTM/junction/index.htm/junction/InDeX.HtM This option is valid for all junction except for the type of localtcp and localssl. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.–kSends WebSEAL session cookies to the back-end virtual host. By default, cookies are removed from requests that are sent to the server. This option is valid for all junction types except localtcp and localssl.–K "key_label"Specifies the key label of the client-side certificate that WebSEAL should present to the back-end server. Use of this option allows the virtual host to authenticate the WebSEAL server using client certificates. This option is valid only with junctions that were created with the type of ssl and sslproxy.–l percentDefines the soft limit for consumption of worker threads. This option is valid for all junction types except localtcp and localssl.–L percentDefines the hard limit for consumption of worker threads. This option is valid for all junction types except localtcp and localssl.–p portSpecifies the TCP port of the back-end third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is valid for all junction types except localtcp and localssl.–P portSpecifies the TCP port number for the HTTP proxy server. The –P option is required when the –H option is used. This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.–q pathRequired option for back-end Windows virtual hosts. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option will indicate to WebSEAL the new URL to the file. This option is valid for all junction types except localtcp and localssl.–rInserts the incoming IP address into the HTTP header across the junction. This option is valid for all junction types except localtcp and localssl.–R Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the –R option is not used and a rule failure occurs, WebSEAL will not allow the request to proceed. This option is valid for all junction types except localtcp and localssl.–sIndicates that the virtual host junction support stateful applications. By default, virtual host junctions are not stateful. This option is valid for all junction types except localtcp and localssl.–SIndicates the name of the forms single signon configuration file. This option is valid for all junction types except localtcp and localssl.–T {resource | resource_group}Specifies the name of the GSO resource or resource group. This option is required only when the –b gso option is used. This option is valid for all junction types except localtcp and localssl.–u uuidSpecifies the Universally Unique Identifier (UUID) of a back-end server connected to WebSEAL by using a stateful virtual host junction (–s option). This option is valid for all junction types except localtcp and localssl.–U "user_name"Specifies the WebSEAL server user name. This option requires the –B and –W options. WebSEAL uses the BA header information to authenticate to the back-end virtual host and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.–v vhost_name[:port] WebSEAL selects a virtual host junction to process a request if the request's HTTP Host header matches the virtual host name and port number specified by the -v option. The -v option is also used to specify the value of the Host header of the request sent to the back-end server. The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443. If –v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions, the junction is selected from the information contained in the –h host and –p port options. The –v option is required for localtcp and localssl type junctions.–wIndicates Microsoft Windows file system support. This option provides all of the functionality provided by the –i junction option but disallows requests that contain file names that might be interpreted as Windows file name aliases. This option is valid for all junction types except localtcp and localssl. Local junctions prohibit URLs that contain Windows file name aliases on Win64 but allow such URLs on other platforms.–W "password"Specifies the WebSEAL server password. This option requires the –B and –U options. WebSEAL uses the BA header information to authenticate to the back-end virtual host and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.–Y Enables Tivoli Federated Identity Manager single-signon (SSO) for the junction. Before using this option, you must first configure the WebSEAL configuration file to support Tivoli Federated Identity Manager single-signon over junctions.–z replica_setSpecifies the replica set, as follows: For distributed session cache environments:The replica set that sessions on the virtual host junction are managed under and provides the ability to group or separate login sessions among multiple virtual hosts.For environments that do not use the distributed session cache:The replica set that sessions on the virtual host junction are managed under and controls the partitioning of the WebSEAL session cache so the virtual host can be part of the same replica set as any standard junction that is assigned to that same replica set through the standard-junction-replica-set entry of the [session] stanza.–Z keyfile_pwdSpecifies the password of the keyfile used to encrypt LTPA cookie data. This option requires the –A and –F options. The –A, –F, and –Z options all must be used together. This option is valid for all junction types except localtcp and localssl.vhost_labelSpecifies the label name of the virtual host junction.–h host_nameRequired option for non-local junctions. Specifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example: www.example.com–t typeRequired option. Specifies the type of virtual host junction. This option is required and must be one of the following types: tcptcpproxysslsslproxylocaltcplocalssl Authorization Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. For more information about gathering statistics, see the Auditing topics in the IBM Knowledge Center. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example (entered as one line) creates an SSL type virtual host junction with the vhost-xy-https label. This junction serves the virtual host x.y.com located on the junctioned server cruz1.ibm.com. WebSEAL responds to the Host: x.y.com header in SSL (HTTPS) requests by forwarding the requests across this virtual host junction: pdadmin> server task default-webseald-abc.ibm.com virtualhost create -t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-https See also server task virtualhost addThe server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction. server task virtualhost deleteThe server task virtualhost delete command deletes a virtual host junction. server task virtualhost listThe server task virtualhost list command lists all configured virtual host junctions by label name. server task virtualhost removeThe server task virtualhost remove command removes the specified server from a virtual host junction. server task virtualhost showThe server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. Command reference

server task virtualhost create

The server task virtualhost create command creates a virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

For local junctions:

server task instance_name-webseald-host_name virtualhost create –t type –v virtual_host_name [options] vhost_label

For non-local junctions:

server task instance_name-webseald-host_name virtualhost create –t type –h host_name [options] vhost_label

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify the full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

options

Specifies the options that you can use with the server task virtualhost create command. These options include:

–A

Enables a virtual host junction to support the lightweight third-party authentication mechanism (LTPA). This option requires the –F and –Z options. The –A, –F, and –Z options all must be used together.

This option is valid for all junction types except localtcp and localssl.

-2

You can use this option in conjunction with the -A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The -A option without the -2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

–b BA_value

Defines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the back-end virtual host, which is one of the following values:

filter

ignore

supply

gso

This option is valid for all junction types except localtcp and localssl.

The default value is filter.

–B

Indicates that WebSEAL uses the BA header information to authenticate to the back-end virtual host and to provide mutual authentication over SSL. This option requires the –U and –W options.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–c header_type

Inserts the Security Access Manager client identity in HTTP headers across the virtual host junction. The header_type argument can include any combination of the following Security Access Manager HTTP header types:

{iv-user|iv-user-l}

iv-groups

iv-creds

all

The header types must be comma separated, and cannot have a spaces between the types. For example: -c iv_user,iv_groups

Specifying –c all is the same as specifying –c iv-user,iv-groups,iv-creds.

This option is valid for all junction types except localtcp and localssl.

–C

Supports mutual authentication by enabling the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server in a Basic Authentication (BA) header. Additionally, the –C option enables single signon functionality provided by the –c option.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–D "dn"

Specifies the distinguished name of the back-end server certificate. This value, matched with the actual certificate DN enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–e encoding_type

Specifies the encoding to use when generating HTTP headers for virtual host junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. Possible values for encoding are as follows:

utf8_bin

WebSEAL sends the headers in UTF-8.

utf8_uri

WebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.

lcp_bin

WebSEAL sends the headers in the local code page of the WebSEAL server.

lcp_uri

WebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them.

This option is valid for all junction types except localtcp and localssl.

–f

Forces the replacement (overwrite) of an existing virtual host junction.

This option is used for junctions that were created with the any junction type.

–F "keyfile"

Specifies the name of the keyfile used to encrypt LTPA cookie data.

The –F option requires –A and –Z options. The –A, –F, and –Z options all must be used together.

This option is valid for all junction types except localtcp and localssl.

–g vhost_label

The –g option causes a second additional virtual host junction to share the same protected object space as the initial virtual host junction.

This option is appropriate for junction pairs only (two junctions using complementary protocols). The option does not support the association of more than two junctions.

–H host_name

Specifies the DNS host name or IP address of the proxy server. The –P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example:

proxy.www.example.com

This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file.

Junctions to such a Web server should be created with the –i or –w option. ACLs or POPs that are attached to objects beneath the junction point should use the lower case object name. An ACL attached to /junction/index.htm will apply to all of the following requests if the –i or –w option is used:

/junction/INDEX.HTM

/junction/index.htm

/junction/InDeX.HtM

This option is valid for all junction except for the type of localtcp and localssl. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.

–k

Sends WebSEAL session cookies to the back-end virtual host. By default, cookies are removed from requests that are sent to the server.

This option is valid for all junction types except localtcp and localssl.

–K "key_label"

Specifies the key label of the client-side certificate that WebSEAL should present to the back-end server. Use of this option allows the virtual host to authenticate the WebSEAL server using client certificates.

This option is valid only with junctions that were created with the type of ssl and sslproxy.

–l percent

Defines the soft limit for consumption of worker threads.

This option is valid for all junction types except localtcp and localssl.

–L percent

Defines the hard limit for consumption of worker threads.

This option is valid for all junction types except localtcp and localssl.

–p port

Specifies the TCP port of the back-end third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions.

This option is valid for all junction types except localtcp and localssl.

–P port

Specifies the TCP port number for the HTTP proxy server. The –P option is required when the –H option is used.

This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.

–q path

Required option for back-end Windows virtual hosts. Specifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option will indicate to WebSEAL the new URL to the file.

This option is valid for all junction types except localtcp and localssl.

–r

Inserts the incoming IP address into the HTTP header across the junction.

This option is valid for all junction types except localtcp and localssl.

–R

Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the –R option is not used and a rule failure occurs, WebSEAL will not allow the request to proceed.

This option is valid for all junction types except localtcp and localssl.

–s

Indicates that the virtual host junction support stateful applications. By default, virtual host junctions are not stateful.

This option is valid for all junction types except localtcp and localssl.

–S

Indicates the name of the forms single signon configuration file.

This option is valid for all junction types except localtcp and localssl.

–T {resource | resource_group}

Specifies the name of the GSO resource or resource group. This option is required only when the –b gso option is used.

This option is valid for all junction types except localtcp and localssl.

–u uuid

Specifies the Universally Unique Identifier (UUID) of a back-end server connected to WebSEAL by using a stateful virtual host junction (–s option).

This option is valid for all junction types except localtcp and localssl.

–U "user_name"

Specifies the WebSEAL server user name. This option requires the –B and –W options. WebSEAL uses the BA header information to authenticate to the back-end virtual host and to provide mutual authentication over SSL.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–v vhost_name[:port]

WebSEAL selects a virtual host junction to process a request if the request's HTTP Host header matches the virtual host name and port number specified by the -v option.

The -v option is also used to specify the value of the Host header of the request sent to the back-end server.

The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.

If –v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions, the junction is selected from the information contained in the –h host and –p port options.

The –v option is required for localtcp and localssl type junctions.

–w

Indicates Microsoft Windows file system support. This option provides all of the functionality provided by the –i junction option but disallows requests that contain file names that might be interpreted as Windows file name aliases.

This option is valid for all junction types except localtcp and localssl. Local junctions prohibit URLs that contain Windows file name aliases on Win64 but allow such URLs on other platforms.

–W "password"

Specifies the WebSEAL server password. This option requires the –B and –U options. WebSEAL uses the BA header information to authenticate to the back-end virtual host and to provide mutual authentication over SSL.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–Y

Enables Tivoli® Federated Identity Manager single-signon (SSO) for the junction.

Note: Before using this option, you must first configure the WebSEAL configuration file to support Tivoli Federated Identity Manager single-signon over junctions.

–z replica_set

Specifies the replica set, as follows:

For distributed session cache environments:

The replica set that sessions on the virtual host junction are managed under and provides the ability to group or separate login sessions among multiple virtual hosts.

For environments that do not use the distributed session cache:

The replica set that sessions on the virtual host junction are managed under and controls the partitioning of the WebSEAL session cache so the virtual host can be part of the same replica set as any standard junction that is assigned to that same replica set through the standard-junction-replica-set entry of the [session] stanza.

–Z keyfile_pwd

Specifies the password of the keyfile used to encrypt LTPA cookie data. This option requires the –A and –F options. The –A, –F, and –Z options all must be used together.

This option is valid for all junction types except localtcp and localssl.

vhost_label

Specifies the label name of the virtual host junction.

–h host_name

Required option for non-local junctions. Specifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example:

www.example.com

–t type

Required option. Specifies the type of virtual host junction. This option is required and must be one of the following types:

tcp

tcpproxy

ssl

sslproxy

localtcp

localssl

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Note: For more information about gathering statistics, see the Auditing topics in the IBM Knowledge Center.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example (entered as one line) creates an SSL type virtual host junction with the vhost-xy-https label. This junction serves the virtual host x.y.com located on the junctioned server cruz1.ibm.com. WebSEAL responds to the Host: x.y.com header in SSL (HTTPS) requests by forwarding the requests across this virtual host junction:

pdadmin> server task default-webseald-abc.ibm.com virtualhost create
-t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-https

See also

server task virtualhost add

server task virtualhost delete

server task virtualhost list

server task virtualhost remove

server task virtualhost show

Parent topic: Command reference

server task virtualhost deleteserver task virtualhost deleteWebSEAL server task virtualhost delete commandThe server task virtualhost delete command deletes a virtual host junction.server task commandsvirtualhost deletejunctionsdelete virtual host junctionsjunctioned serversdelete virtual host junctionsserver commandsserver task virtualhost delete Requires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost delete vhost_label Description The server list virtualhost delete command deletes a virtual host junction. A virtual host junction cannot be deleted if a second virtual host junction refers to it through the –g option. An error message is returned at such an attempt. Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example (entered as one line) deletes the virtual host junction support-vhost-https from the WebSEAL server abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com virtualhost delete support-vhost-https See also server task virtualhost addThe server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction. server task virtualhost createThe server task virtualhost create command creates a virtual host junction. server task virtualhost listThe server task virtualhost list command lists all configured virtual host junctions by label name. server task virtualhost removeThe server task virtualhost remove command removes the specified server from a virtual host junction. server task virtualhost showThe server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. Command reference

server task virtualhost delete

The server task virtualhost delete command deletes a virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost delete vhost_label

Description

The server list virtualhost delete command deletes a virtual host junction. A virtual host junction cannot be deleted if a second virtual host junction refers to it through the –g option. An error message is returned at such an attempt.

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example (entered as one line) deletes the virtual host junction support-vhost-https from the WebSEAL server abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com virtualhost delete
support-vhost-https

See also

server task virtualhost add

server task virtualhost create

server task virtualhost list

server task virtualhost remove

server task virtualhost show

Parent topic: Command reference

server task virtualhost listserver task virtualhost listWebSEAL server task virtualhost list commandThe server task virtualhost list command lists all configured virtual host junctions by label name.server commandsserver task virtualhost listserver task virtualhost listserver task commandsvirtualhost listjunctionslist virtual host junctionsRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost list Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. Authorization Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@per_vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example lists the label names of all virtual host junctions configured on the abc.ibm.com WebSEAL server: pdadmin> server task default-webseald-abc.ibm.com virtualhost listOutput is similar to: pubs-vhost-http sales-vhost-https support-vhost-http See also server task virtualhost addThe server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction. server task virtualhost createThe server task virtualhost create command creates a virtual host junction. server task virtualhost deleteThe server task virtualhost delete command deletes a virtual host junction. server task virtualhost removeThe server task virtualhost remove command removes the specified server from a virtual host junction. server task virtualhost showThe server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. Command reference

server task virtualhost list

The server task virtualhost list command lists all configured virtual host junctions by label name.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost list

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@per_vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists the label names of all virtual host junctions configured on the abc.ibm.com WebSEAL server:

pdadmin> server task default-webseald-abc.ibm.com virtualhost list

Output is similar to:

pubs-vhost-http
sales-vhost-https
support-vhost-http

See also

server task virtualhost add

server task virtualhost create

server task virtualhost delete

server task virtualhost remove

server task virtualhost show

Parent topic: Command reference

server task virtualhost offlineserver task virtualhost offlineWebSEAL server task virtualhost offline commandThe server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state.server commandsserver task virtualhost offlineserver task commandsvirtualhost offlinejunctionsvirtualhost offlinejunctioned servervirtualhost offlineRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost offline [–i server_uuid] vhost_label Description The server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are located at this virtual host junction are placed in an offline operational state. Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidSpecifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are located at this virtual host junction are placed in an offline operational state. Use the server task virtualhost show command to determine the ID of a specific back-end server.vhost_labelSpecifies the label name of the virtual host junction. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com. There is a requirement to place the int3.ibm.com server in an offline operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command (entered as one line): pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-https Output is similar to: Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Throttled Throttled at: 2005-03-01-17:07:24 Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1 Place this server in an offline operational state using the following command (entered as one line): pdadmin> server task default-webseald-cruz virtualhost offline -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https See also server task offlineThe server task offline command places the server that is located at this junction in an offline operational state. server task onlineThe server task online command places the server that is located at this junction in an online operational state. server task throttleThe server task throttle command places the server that is located at this junction in a throttled operational state. server task virtualhost onlineThe server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. server task virtualhost throttleThe server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state. Command reference

server task virtualhost offline

The server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost offline [–i server_uuid] vhost_label

Description

The server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are located at this virtual host junction are placed in an offline operational state.

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

Specifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are located at this virtual host junction are placed in an offline operational state. Use the server task virtualhost show command to determine the ID of a specific back-end server.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an offline operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command (entered as one line):

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in an offline operational state using the following command (entered as one line):

pdadmin> server task default-webseald-cruz virtualhost offline
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

server task offline

server task online

server task throttle

server task virtualhost online

server task virtualhost throttle

Parent topic: Command reference

server task virtualhost onlineserver task virtualhost onlineWebSEAL server task virtualhost online commandThe server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. server commandsserver task virtualhost onlineserver task virtualhost onlineserver task commandsvirtualhost onlinejunctionsvirtualhost onlinejunctioned servervirtualhost onlineRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost online [–i server_uuid] vhost_label Description The server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are located at this virtual host junction are placed in an online operational state. Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidUUID of the server to place in an online operational state. If a server is not specified, all servers that are located at this virtual host junction are placed in an online operational state. Use the server task virtualhost show command to determine the ID of a specific back-end server.vhost_labelSpecifies the label name of the virtual host junction. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com. There is a requirement to place the int3.ibm.com server in an online operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command (entered as one line): pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-https Output is similar to: Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Offline Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1 Place this server in an online operational state using the following command (entered as one line): pdadmin> server task default-webseald-cruz virtualhost online -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https See also server task offlineThe server task offline command places the server that is located at this junction in an offline operational state. server task onlineThe server task online command places the server that is located at this junction in an online operational state. server task throttleThe server task throttle command places the server that is located at this junction in a throttled operational state. server task virtualhost offlineThe server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state. server task virtualhost throttleThe server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state. Command reference

server task virtualhost online

The server task virtualhost online command places the server that is located at this virtual host junction in an online operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost online [–i server_uuid] vhost_label

Description

The server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are located at this virtual host junction are placed in an online operational state.

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

UUID of the server to place in an online operational state. If a server is not specified, all servers that are located at this virtual host junction are placed in an online operational state. Use the server task virtualhost show command to determine the ID of a specific back-end server.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code will be 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an online operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command (entered as one line):

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Offline
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in an online operational state using the following command (entered as one line):

pdadmin> server task default-webseald-cruz virtualhost online
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

server task offline

server task online

server task throttle

server task virtualhost offline

server task virtualhost throttle

Parent topic: Command reference

server task virtualhost removeserver task virtualhost removeWebSEAL server task virtualhost remove commandThe server task virtualhost remove command removes the specified server from a virtual host junction.server task commandsvirtualhost removeserver commandsserver task virtualhost removejunctionsremove server from virtualhost junctionjunctioned serverremoveRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost remove –i server_uuid vhost_label Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidSpecifies the UUID of the server to be removed from the virtual host junction. For this command, the –i option, normally used to treat URLs as case-sensitive,operates like the –u option. See the server task show command for details about obtaining the UUID.vhost_labelSpecifies the label name of the virtual host junction. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example removes the junctioned server int4.ibm.com from the virtual host junction support-vhost-https. To determine the UUID of the server to be removed, run the server task virtualhost show command (entered as one line): pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-httpsOutput is similar to: Virtual Host label: support-vhost-https Type: SSL Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Basic authentication mode: filter Forms based SSO: disabled Authentication HTTP header: do not insert Remote Address HTTP header: do not insert Stateful junction: no Boolean Rule Header: no Delegation support: no Mutually authenticated: no Insert WebSphere LTPA cookies: no Insert WebSEAL session cookies: no Request Encoding: UTF-8, URI Encoded Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Total requests: 1 Server 2: ID: xycecc77-19ve-81y5-4h0a-90267hj5nn57 Server State: running Hostname: int4.ibm.com Port: 444 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Total requests: 1 Remove the server from the virtual host junction (entered as one line): pdadmin> server task default-webseald-abc.ibm.com virtualhost remove -i xycecc77-19ve-81y5-4h0a-90267hj5nn57 support-vhost-https See also server task virtualhost addThe server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction. server task virtualhost createThe server task virtualhost create command creates a virtual host junction. server task virtualhost deleteThe server task virtualhost delete command deletes a virtual host junction. server task virtualhost listThe server task virtualhost list command lists all configured virtual host junctions by label name. server task virtualhost showThe server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. Command reference

server task virtualhost remove

The server task virtualhost remove command removes the specified server from a virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost remove –i server_uuid vhost_label

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

Specifies the UUID of the server to be removed from the virtual host junction. For this command, the –i option, normally used to treat URLs as case-sensitive,operates like the –u option. See the server task show command for details about obtaining the UUID.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example removes the junctioned server int4.ibm.com from the virtual host junction support-vhost-https. To determine the UUID of the server to be removed, run the server task virtualhost show command (entered as one line):

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Basic authentication mode: filter
Forms based SSO: disabled
Authentication HTTP header: do not insert
Remote Address HTTP header: do not insert
Stateful junction: no
Boolean Rule Header: no
Delegation support: no
Mutually authenticated: no
Insert WebSphere LTPA cookies: no
Insert WebSEAL session cookies: no
Request Encoding: UTF-8, URI Encoded
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1
Server 2:
ID: xycecc77-19ve-81y5-4h0a-90267hj5nn57
Server State: running
Hostname: int4.ibm.com
Port: 444
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1

Remove the server from the virtual host junction (entered as one line):

pdadmin> server task default-webseald-abc.ibm.com
virtualhost remove -i xycecc77-19ve-81y5-4h0a-90267hj5nn57 support-vhost-https

See also

server task virtualhost add

server task virtualhost create

server task virtualhost delete

server task virtualhost list

server task virtualhost show

Parent topic: Command reference

server task virtualhost showserver task virtualhost showWebSEAL server task virtualhost show commandThe server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed.server task commandsvirtualhost showserver task virtualhost showjunctionslist virtualhost junction detailsjunctioned serverslist details of virtualhost junctionsserver commandsserver task virtualhost showRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost show vhost_label Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. Authorization Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example (entered as one line) shows information for the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, that supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com: pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-https Output is similar to: Virtual Host label: support-vhost-https Type: SSL Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Basic authentication mode: filter Forms based SSO: disabled Authentication HTTP header: do not insert Remote Address HTTP header: do not insert Stateful junction: no Boolean Rule Header: no Delegation support: no Mutually authenticated: no Insert WebSphere LTPA cookies: no Insert WebSEAL session cookies: no Request Encoding: UTF-8, URI Encoded Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Total requests: 1 See also server task virtualhost addThe server task virtualhost add command adds an additional installed WebSEAL server or instance to an existing virtual host junction. server task virtualhost createThe server task virtualhost create command creates a virtual host junction. server task virtualhost deleteThe server task virtualhost delete command deletes a virtual host junction. server task virtualhost listThe server task virtualhost list command lists all configured virtual host junctions by label name. server task virtualhost removeThe server task virtualhost remove command removes the specified server from a virtual host junction. Command reference

server task virtualhost show

The server task virtualhost show command displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost show vhost_label

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors.

Note: Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example (entered as one line) shows information for the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, that supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Basic authentication mode: filter
Forms based SSO: disabled
Authentication HTTP header: do not insert
Remote Address HTTP header: do not insert
Stateful junction: no
Boolean Rule Header: no
Delegation support: no
Mutually authenticated: no
Insert WebSphere LTPA cookies: no
Insert WebSEAL session cookies: no
Request Encoding: UTF-8, URI Encoded
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1

See also

server task virtualhost add

server task virtualhost create

server task virtualhost delete

server task virtualhost list

server task virtualhost remove

Parent topic: Command reference

server task virtualhost throttleserver task virtualhost throttleWebSEAL server task virtualhost throttle commandThe server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state.server commandsserver task virtualhost throttleserver task virtualhost throttleserver task commandsvirtualhost throttlejunctionsvirtual host throttlejunctioned servervirtual host throttleRequires authentication (administrator ID and password) to use this command.Syntax server task instance_name-webseald-host_name virtualhost throttle [–i server_uuid] vhost_label Description The server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state. Only requests from users who have created a session with WebSEAL prior to the invocation of this command continue to have their requests processed by the specified server. If a server is not specified, all servers that are located at this virtual host junction are placed in a throttled operational state.. Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed. For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com. If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.–i server_uuidSpecifies the UUID of the server to throttle. If a server is not specified, all servers that are at this virtual host junction are placed in a throttled operational state. Use the server task virtualhost show command to determine the ID of a specific back-end server.vhost_labelSpecifies the label name of the virtual host junction. Authorization Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com. There is a requirement to place the int3.ibm.com server in a throttled operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command (entered as one line): pdadmin> server task default-webseald-abc.ibm.com virtualhost show support-vhost-https Output is similar to: Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Online Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1 Place this server in a throttled operational state using the following command (entered as one line): pdadmin> server task default-webseald-cruz virtualhost throttle -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https See also server task throttleThe server task throttle command places the server that is located at this junction in a throttled operational state. server task offlineThe server task offline command places the server that is located at this junction in an offline operational state. server task onlineThe server task online command places the server that is located at this junction in an online operational state. server task virtualhost offlineThe server task virtualhost offline command places the server that is located at this virtual host junction in an offline operational state. server task virtualhost onlineThe server task virtualhost online command places the server that is located at this virtual host junction in an online operational state. Command reference

server task virtualhost throttle

The server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost throttle [–i server_uuid] vhost_label

Description

The server task virtualhost throttle command places the server that is located at this virtual host junction in a throttled operational state. Only requests from users who have created a session with WebSEAL prior to the invocation of this command continue to have their requests processed by the specified server. If a server is not specified, all servers that are located at this virtual host junction are placed in a throttled operational state..

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL instance is default, and host machine name where the WebSEAL server is installed is abc.ibm.com, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

–i server_uuid

Specifies the UUID of the server to throttle. If a server is not specified, all servers that are at this virtual host junction are placed in a throttled operational state. Use the server task virtualhost show command to determine the ID of a specific back-end server.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user has permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code becomes 0 when the command is sent to the WebSEAL server without errors. Even if the command was successfully sent, the WebSEAL server might not be able to successfully complete the command and can return an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center which provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

In the following example, the virtual host junction with the label support-vhost-https, configured on the WebSEAL server abc.ibm.com, supports the virtual host support.ibm.com, located on the back-end junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in a throttled operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command (entered as one line):

pdadmin> server task default-webseald-abc.ibm.com
virtualhost show support-vhost-https

Output is similar to:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Online
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in a throttled operational state using the following command (entered as one line):

pdadmin> server task default-webseald-cruz virtualhost throttle
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

server task throttle

server task offline

server task online

server task virtualhost offline

server task virtualhost online

Parent topic: Command reference

Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Advanced Access Control configuration This section provides configuration procedures for the Advanced Access Control features, including support for Oauth, one time password, and integration with WebSEAL.ConfiguringConfiguring is an activity in which you modify the default settings of various parts of the product.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks. Getting started with Advanced Access ControlSeveral configuration tasks must be completed in order to start using Advanced Access Control.Managing application interfaces To manage application interfaces with the local management interface, use the Application Interfaces management page.Managing the runtime componentTo manage configuration files with the local management interface, use the Runtime Component management page.Managing user registriesThe appliance runtime profile has a user registry associated. Use the User Registry management page to administer the users and group memberships. The user registry in discussion here is the one used by the runtime applications, not the one used by the management interface.Runtime security services external authorization serviceThe runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.Adding runtime listening interfacesAdd your application interfaces to the list of runtime listening interfaces. This procedure enables communication between an appliance with Advanced Access Control and another Security Access Manager appliance.Support for compliance with NIST SP800-131aAdvanced Access Control supports the requirements that are defined by the National Institute of Standards and Technology (NIST) Special Publications 800-131a. AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.Mobile Multi-Factor AuthenticationThe IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol. Defining a custom domain for policy attachmentsThe administrator can specify a custom domain to separate metadata in a registry. For example, your company might possess metadata that belongs to several companies, and it is a security demand that the data does not overlap.Managing advanced configurationAdjust configuration settings in supported configuration files.Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization.Deploying pending changesSome configuration and administration changes require an extra deployment step.Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. Options for handling session failover eventsAdvanced Access Control offers several solutions to the challenge of providing sharing of session state across multiple servers in a clustered environment. Managing JavaScript mapping rulesCreate or edit JavaScript mapping rules.JavaScript whitelistAdvanced Access Control JavaScript mapping rules call Java code from JavaScript. The set of classes that can be called are restricted.

Advanced Access Control configuration

Use the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Advanced Access Control configuration This section provides configuration procedures for the Advanced Access Control features, including support for Oauth, one time password, and integration with WebSEAL.

Upgrading configuration
After you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Getting started with Advanced Access Control
Several configuration tasks must be completed in order to start using Advanced Access Control.

Managing application interfaces
To manage application interfaces with the local management interface, use the Application Interfaces management page.

Managing the runtime component
To manage configuration files with the local management interface, use the Runtime Component management page.

Managing user registries
The appliance runtime profile has a user registry associated. Use the User Registry management page to administer the users and group memberships. The user registry in discussion here is the one used by the runtime applications, not the one used by the management interface.

Runtime security services external authorization service
The runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.

Using the isamcfg tool
Various features of Advanced Access Control can be configured with the isamcfg tool.

Adding runtime listening interfaces
Add your application interfaces to the list of runtime listening interfaces. This procedure enables communication between an appliance with Advanced Access Control and another Security Access Manager appliance.

Support for compliance with NIST SP800-131a
Advanced Access Control supports the requirements that are defined by the National Institute of Standards and Technology (NIST) Special Publications 800-131a.

Authentication
Security Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

OAuth 2.0 support
Advanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

Mobile Multi-Factor Authentication
The IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol.

Defining a custom domain for policy attachments
The administrator can specify a custom domain to separate metadata in a registry. For example, your company might possess metadata that belongs to several companies, and it is a security demand that the data does not overlap.

Managing advanced configuration
Adjust configuration settings in supported configuration files.

Advanced configuration properties
Modify the advanced configurations to meet the requirements of your organization.

Deploying pending changes
Some configuration and administration changes require an extra deployment step.

Tuning runtime application parameters and tracing specifications
To manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page.

Options for handling session failover events
Advanced Access Control offers several solutions to the challenge of providing sharing of session state across multiple servers in a clustered environment.

Managing JavaScript mapping rules
Create or edit JavaScript mapping rules.

JavaScript whitelist
Advanced Access Control JavaScript mapping rules call Java™ code from JavaScript. The set of classes that can be called are restricted.

Parent topic: Configuring

Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks. database configurationupgradeupgradedatabase configurationReview the following tasks, and perform the ones that are appropriate for your installation. Advanced Access Control configuration upgrade tasksUpgrade taskSeeRun the isamcfg tool to obtain the correct configuration settings for WebSEAL and Security Access Manager.Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.If you use solidDB as an external runtime database, upgrade solidDB.Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0)If SolidDB is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version. or Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)Use the dbupdate tool that is provided by the appliance to upgrade your external runtime databases, such as solidDB, DB2, and Oracle.If you use DB2 as an external runtime database, upgrade DB2.Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0)If DB2 is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version. or Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)Use the dbupdate tool that is provided by the appliance to upgrade your external runtime databases, such as solidDB, DB2, and Oracle.If you use Oracle as an external runtime database, upgrade Oracle.Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0)If Oracle is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version. or Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)Use the dbupdate tool that is provided by the appliance to upgrade your external runtime databases, such as solidDB, DB2, and Oracle.After an upgrade, the setting for one-time password authentication is set to run in backward compatibility mode. Disable this mode.Setting backward compatibility mode for one-time passwordWhen you upgrade your installation, the setting for one-time password authentication is set to run in backward compatibility mode. Complete this task if you need to disable this mode.If you customized any template files, upgrade them.Updating template filesIf you want to update your template files to the latest version, complete this task. Otherwise, the template files from the previous version are ready for use after the upgrade.The new role membership features in later versions of the appliance are granted the permission of None by default. Configure the permissions for these new role membership features, if necessary.Managing roles of users and groupsAssign certain roles to users and groups to control which sections of the local management interface and web services they can access.To limit the number of OAuth tokens per user per definition, update the mapping rule.Updating PreTokenGeneration to limit OAuth tokensUpdate the latest version of the PreTokenGeneration mapping rule to limit the number of OAuth tokens per user per definition.Review and update some existing Web Reverse Proxy instance point of contact settings for the Advanced Access Control runtime.Reviewing existing Web Reverse Proxy instance point of contact settingsAfter you upgrade from appliance v8.n.n.n to v9.n.n.n, it might be necessary to review and update some existing Web Reverse Proxy instance point of contact settings for the Advanced Access Control runtime. After you complete the appropriate configuration tasks, go to Getting started with Advanced Access ControlSeveral configuration tasks must be completed in order to start using Advanced Access Control..Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)Use the dbupdate tool that is provided by the appliance to upgrade your external runtime databases, such as solidDB, DB2, and Oracle.Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0)If SolidDB is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0)If DB2 is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0)If Oracle is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.Setting backward compatibility mode for one-time passwordWhen you upgrade your installation, the setting for one-time password authentication is set to run in backward compatibility mode. Complete this task if you need to disable this mode.Updating template filesIf you want to update your template files to the latest version, complete this task. Otherwise, the template files from the previous version are ready for use after the upgrade.Updating PreTokenGeneration to limit OAuth tokensUpdate the latest version of the PreTokenGeneration mapping rule to limit the number of OAuth tokens per user per definition.Reviewing existing Web Reverse Proxy instance point of contact settingsAfter you upgrade from appliance v8.n.n.n to v9.n.n.n, it might be necessary to review and update some existing Web Reverse Proxy instance point of contact settings for the Advanced Access Control runtime.

Upgrading configuration

After you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Review the following tasks, and perform the ones that are appropriate for your installation.

Table 76. Advanced Access Control configuration upgrade tasks

Upgrade task | See
Run the isamcfg tool to obtain the correct configuration settings for WebSEAL and Security Access Manager. | Using the isamcfg tool
If you use solidDB® as an external runtime database, upgrade solidDB. | Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0) or Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)
If you use DB2® as an external runtime database, upgrade DB2. | Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0) or Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)
If you use Oracle as an external runtime database, upgrade Oracle. | Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0) or Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)
After an upgrade, the setting for one-time password authentication is set to run in backward compatibility mode. Disable this mode. | Setting backward compatibility mode for one-time password
If you customized any template files, upgrade them. | Updating template files
The new role membership features in later versions of the appliance are granted the permission of None by default. Configure the permissions for these new role membership features, if necessary. | Managing roles of users and groups
To limit the number of OAuth tokens per user per definition, update the mapping rule. | Updating PreTokenGeneration to limit OAuth tokens
Review and update some existing Web Reverse Proxy instance point of contact settings for the Advanced Access Control runtime. | Reviewing existing Web Reverse Proxy instance point of contact settings

After you complete the appropriate configuration tasks, go to Getting started with Advanced Access Control.

Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)
Use the dbupdate tool that is provided by the appliance to upgrade your external runtime databases, such as solidDB, DB2, and Oracle.

Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0)
If SolidDB is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.

Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0)
If DB2 is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.

Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0)
If Oracle is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.

Setting backward compatibility mode for one-time password
When you upgrade your installation, the setting for one-time password authentication is set to run in backward compatibility mode. Complete this task if you need to disable this mode.

Updating template files
If you want to update your template files to the latest version, complete this task. Otherwise, the template files from the previous version are ready for use after the upgrade.

Updating PreTokenGeneration to limit OAuth tokens
Update the latest version of the PreTokenGeneration mapping rule to limit the number of OAuth tokens per user per definition.

Reviewing existing Web Reverse Proxy instance point of contact settings
After you upgrade from appliance v8.n.n.n to v9.n.n.n, it might be necessary to review and update some existing Web Reverse Proxy instance point of contact settings for the Advanced Access Control runtime.

Parent topic: Advanced Access Control configuration

Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)Use the dbupdate tool that is provided by the appliance to upgrade your external runtime databases, such as solidDB, DB2, and Oracle.Use this task if your Security Access Manager appliance version is 9.0.0.0 or later. If your appliance version is earlier than 9.0.0.0, you must first update the appliance and the external database to version 9.0.0.0 by using the following methods: Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0)If SolidDB is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0)If DB2 is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0)If Oracle is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version. You must have Java version 8 or later to run the database update tool. In the local management interface, go to Manage System SettingsSecure SettingsFile Downloads.Expand access_controldatabase.Select the dbupdate9.zip file.This file contains the database update tool (dbupdate.jar), the README file, and update files for all databases and SQL types.Click Export.Save the file.Extract the dbupdate9.zip file and run the dbupdate.jar tool for your environment.The usage of the tool is as follows:${JAVA_HOME}/bin/java -jar dbupdate.jar [-t] [-n] <dbType> <sqlType> <connectString> <user> [<password>]-tEnable debug trace output.-nDo not perform any updates, but instead output the update operations that would have been executed. dbTypeThe database type. Valid values are config or runtime.sqlTypeThe database server type. Valid values are db2, oracle, or soliddb.connectStringThe string that is used when establishing a connection to the database server. db2Typically the database name, which is used in "db2 CONNECT TO <connectString> USER <user> USING <password>;".oracleIf the string is not empty, it corresponds to the value used for sqlplus "CONNECT <user>/<password>@<connectString>;". If the string is empty (""), the ORACLE_SID environment variable is used.soliddbTypically "tcp <host> <port>", which is used in the "solsql <options> <connectString> <user> <password>" command.userDatabase user to update the database with.passwordDatabase user's password. If not provided, the value is read from console.For DB2 external databases, the db2 command must be in the path. For Oracle external databases, the sqlplus command must be in the path. For SolidDB external databases, the solsql command must be in the path.Java 8 or later is required for running the tool.The following command shows an example of using the tool to update a DB2 database:/opt/ibm/java-x86_64-80/jre/bin/java -jar dbupdate.jar runtime db2 "HVDB" db2inst1 passw0rdThe following command shows an example of using the tool to update an Oracle database:/opt/ibm/java-x86_64-80/jre/bin/java -jar dbupdate.jar runtime oracle "" SYSTEM passw0rd If the tool is not flexible enough for your environment, you can see which commands the tool runs without executing them and manually run those commands to suit your environment. To see which commands the update tool runs against the database, run the tool with the -n option. This option still must be able to read from the database to get the current update versions in order to determine which updates to apply. However, it will not execute any update operations.See the README file that is included in the dbupdate9.zip file for more details about the update tool.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Upgrading external databases with the dbupdate tool (for appliance at version 9.0.0.0 and later)

Use the dbupdate tool that is provided by the appliance to upgrade your external runtime databases, such as solidDB, DB2, and Oracle.

About this task

Use this task if your Security Access Manager appliance version is 9.0.0.0 or later. If your appliance version is earlier than 9.0.0.0, you must first update the appliance and the external database to version 9.0.0.0 by using the following methods:

Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0)

Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0)

Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0)

You must have Java version 8 or later to run the database update tool.

Procedure

In the local management interface, go to Manage System Settings > Secure Settings > File Downloads.

Expand access_control > database.

Select the dbupdate9.zip file. This file contains the database update tool (dbupdate.jar), the README file, and update files for all databases and SQL types.

Click Export.

Save the file.

Extract the dbupdate9.zip file and run the dbupdate.jar tool for your environment.

The usage of the tool is as follows:

${JAVA_HOME}/bin/java -jar dbupdate.jar [-t] [-n]
<dbType> <sqlType> <connectString> <user> [<password>]

-t

Enable debug trace output.

-n

Do not perform any updates, but instead output the update operations that would have been executed.

dbType

The database type. Valid values are config or runtime.

sqlType

The database server type. Valid values are db2, oracle, or soliddb.

connectString

The string that is used when establishing a connection to the database server.

db2

Typically the database name, which is used in "db2 CONNECT TO <connectString> USER <user> USING <password>;".

oracle

If the string is not empty, it corresponds to the value used for sqlplus "CONNECT <user>/<password>@<connectString>;". If the string is empty (""), the ORACLE_SID environment variable is used.

soliddb

Typically "tcp <host> <port>", which is used in the "solsql <options> <connectString> <user> <password>" command.

user

Database user to update the database with.

password

Database user's password. If not provided, the value is read from console.

Note: For DB2 external databases, the db2 command must be in the path. For Oracle external databases, the sqlplus command must be in the path. For SolidDB external databases, the solsql command must be in the path.

Java 8 or later is required for running the tool.

The following command shows an example of using the tool to update a DB2 database:

/opt/ibm/java-x86_64-80/jre/bin/java -jar dbupdate.jar runtime db2
"HVDB" db2inst1 passw0rd

The following command shows an example of using the tool to update an Oracle database:

/opt/ibm/java-x86_64-80/jre/bin/java -jar dbupdate.jar runtime oracle
"" SYSTEM passw0rd

If the tool is not flexible enough for your environment, you can see which commands the tool runs without executing them and manually run those commands to suit your environment. To see which commands the update tool runs against the database, run the tool with the -n option. This option still must be able to read from the database to get the current update versions in order to determine which updates to apply. However, it will not execute any update operations.

See the README file that is included in the dbupdate9.zip file for more details about the update tool.

Parent topic: Upgrading configuration

Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0)If SolidDB is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.solidDB databaseupgradeupgradesolidDB databaseUse this task only if you have not installed v9000. The updates to the .sql file for each release are not cumulative. Therefore, depending on which version of the isam_access_control_soliddb_update_v*.sql file you installed, make the following updates:v8003.sql is not installed: First upgrade to v8003, then to v8004, then to v8005, and finally to v9000.v8003.sql is installed: First upgrade to v8004, then to v8005, and finally to v9000.v8004.sql is installed: First upgrade to v8005, and then to v9000.v8005.sql is installed: Upgrade to v9000. Use this task to install each version you require, replacing references to isam_access_control_soliddb_update_v9000.sql with the version number you are upgrading to each time, and starting with the earliest version you require.Log in to the local management interface.Click Manage System SettingsFile Downloads.Expand access_controldatabasesoliddbruntime.Select isam_access_control_soliddb_update_v9000.sqlClick Export.Save the file.Log in to the solsql utility./opt/solidDB/soliddb-7.0/bin/solsql network_name username password network_nameThe network name of the solidDB server. usernameThe user name for the database administrator. passwordThe password for the database administrator.Run the following command in the SolidDB SQL Editor:@fully_qualified_path_to_scriptThe following example shows the fully qualified path to the script:@/tmp/isam_access_control_soliddb_update_v9000.sqlValidate that the tables were successfully updated.Ensure that no errors were returned during the update and log in to the database to manually check that the tables exist.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Upgrading a SolidDB external database (for appliance versions earlier than 9.0.0.0)

If SolidDB is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.

About this task

Attention: Use this task only if you have not installed v9000.

The updates to the .sql file for each release are not cumulative. Therefore, depending on which version of the isam_access_control_soliddb_update_v*.sql file you installed, make the following updates:

v8003.sql is not installed: First upgrade to v8003, then to v8004, then to v8005, and finally to v9000.

v8003.sql is installed: First upgrade to v8004, then to v8005, and finally to v9000.

v8004.sql is installed: First upgrade to v8005, and then to v9000.

v8005.sql is installed: Upgrade to v9000.

Use this task to install each version you require, replacing references to isam_access_control_soliddb_update_v9000.sql with the version number you are upgrading to each time, and starting with the earliest version you require.

Procedure

Log in to the local management interface.

Click Manage System Settings > File Downloads.

Expand access_control > database > soliddb > runtime.

Select isam_access_control_soliddb_update_v9000.sql

Click Export.

Save the file.

Log in to the solsql utility.

/opt/solidDB/soliddb-7.0/bin/solsql network_name username password

network_name

The network name of the solidDB server.

username

The user name for the database administrator.

password

The password for the database administrator.

Run the following command in the SolidDB SQL Editor:

@fully_qualified_path_to_script

The following example shows the fully qualified path to the script:

@/tmp/isam_access_control_soliddb_update_v9000.sql

Validate that the tables were successfully updated.

Ensure that no errors were returned during the update and log in to the database to manually check that the tables exist.

Parent topic: Upgrading configuration

Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0)If DB2 is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.DB2 databaseupgradeupgradeDB2 databaseUse this task only if you have not installed v9000. The updates to the .sql file for each release are not cumulative. Therefore, depending on which version of the isam_access_control_db2_update_v*.sql file you installed, make the following updates:v8004.sql not installed: First upgrade to v8004, then to v8005, and finally to v9000.v8004.sql is installed: Upgrade to v8005 and then to v9000.v8005.sql is installed: Upgrade to v9000. Use this task to install each version you require, replacing references to isam_access_control_db2_update_v9000.sql with the version number you are upgrading to each time, and starting with the earliest version you require.Log in to the local management interface.Click Manage System SettingsFile Downloads.Expand access_controldatabasedb2runtime.Select isam_access_control_db2_update_v9000.sqlClick Export.Save the file.Open the isam_access_control_db2_update_v9000.sql file in an editor on the DB2 server.Replace the following macros with the values specific to your environment:&DBINSTANCEThe name of the DB2 instance.&DBUSERThe name of the DB2 administrator.&DBPASSWORDThe password for the DB2 administrator.Save the changes.Log in to the DB2 Command utility (Windows) or DB2 host (UNIX) as the DB2 administrator.Run the following command:db2 -tsvf fully_qualified_path_to_scriptThe following example shows the fully qualified path to the script:db2 -tsvf tmp/isam_access_control_db2_update_v9000.sqlValidate that the tables were successfully updated.Ensure that no errors were returned during the update and log in to the database to manually check that the tables exist.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Upgrading a DB2 external runtime database (for appliance versions earlier than 9.0.0.0)

If DB2 is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.

About this task

Attention: Use this task only if you have not installed v9000.

The updates to the .sql file for each release are not cumulative. Therefore, depending on which version of the isam_access_control_db2_update_v*.sql file you installed, make the following updates:

v8004.sql not installed: First upgrade to v8004, then to v8005, and finally to v9000.

v8004.sql is installed: Upgrade to v8005 and then to v9000.

v8005.sql is installed: Upgrade to v9000.

Use this task to install each version you require, replacing references to isam_access_control_db2_update_v9000.sql with the version number you are upgrading to each time, and starting with the earliest version you require.

Procedure

Log in to the local management interface.

Click Manage System Settings > File Downloads.

Expand access_control > database > db2 > runtime.

Select isam_access_control_db2_update_v9000.sql

Click Export.

Save the file.

Open the isam_access_control_db2_update_v9000.sql file in an editor on the DB2 server.

Replace the following macros with the values specific to your environment:

&DBINSTANCE

The name of the DB2 instance.

&DBUSER

The name of the DB2 administrator.

&DBPASSWORD

The password for the DB2 administrator.

Save the changes.

Log in to the DB2 Command utility (Windows) or DB2 host (UNIX) as the DB2 administrator.

Run the following command:

db2 -tsvf fully_qualified_path_to_script

The following example shows the fully qualified path to the script:

db2 -tsvf tmp/isam_access_control_db2_update_v9000.sql

Validate that the tables were successfully updated.

Ensure that no errors were returned during the update and log in to the database to manually check that the tables exist.

Parent topic: Upgrading configuration

Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0)If Oracle is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.Oracle databaseupgradeupgradeOracle databaseUse this task only if you have not installed v9000. The updates to the .sql file for each release are not cumulative. Therefore, depending on which version of the isam_access_control_oracle_update_v*.sql file you installed, make the following updates:v8011.sql not installed: First upgrade to v8011 and then to v9000.v8011.sql is installed: Upgrade to v9000. Use this task to install each version you require, replacing references to isam_access_control_oracle_update_v9000.sql with the version number you are upgrading to each time, and starting with the earliest version you require.Log in to the local management interface.Click Manage System SettingsFile Downloads.Expand access_controldatabaseoracleruntime.Select isam_access_control_oracle_update_v9000.sqlClick Export.Save the file.Copy the downloaded isam_access_control_oracle_update_v9000.sql file into the Oracle home directory. For example: ORACLE_HOME=/opt/oracle/app/oracle/product/11.2.0/dbhome_1Log in to SQL*Plus.At the SQL prompt, run START isam_access_control_oracle_update_v9000.sql.Validate that the tables were successfully updated.Ensure that no errors were returned during the update and log in to the database to manually check that the tables exist.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Upgrading an Oracle external runtime database (for appliance versions earlier than 9.0.0.0)

If Oracle is the external runtime database, upgrade it after you install the appliance upgrade so that you are using the correct .sql file version.

About this task

Attention: Use this task only if you have not installed v9000.

The updates to the .sql file for each release are not cumulative. Therefore, depending on which version of the isam_access_control_oracle_update_v*.sql file you installed, make the following updates:

v8011.sql not installed: First upgrade to v8011 and then to v9000.

v8011.sql is installed: Upgrade to v9000.

Use this task to install each version you require, replacing references to isam_access_control_oracle_update_v9000.sql with the version number you are upgrading to each time, and starting with the earliest version you require.

Procedure

Log in to the local management interface.

Click Manage System Settings > File Downloads.

Expand access_control > database > oracle > runtime.

Select isam_access_control_oracle_update_v9000.sql

Click Export.

Save the file.

Copy the downloaded isam_access_control_oracle_update_v9000.sql file into the Oracle home directory. For example: ORACLE_HOME=/opt/oracle/app/oracle/product/11.2.0/dbhome_1

Log in to SQL*Plus.

At the SQL prompt, run START isam_access_control_oracle_update_v9000.sql.

Validate that the tables were successfully updated.

Ensure that no errors were returned during the update and log in to the database to manually check that the tables exist.

Parent topic: Upgrading configuration

Setting backward compatibility mode for one-time passwordWhen you upgrade your installation, the setting for one-time password authentication is set to run in backward compatibility mode. Complete this task if you need to disable this mode.backward compatibility modeone-time passwordone-time passwordbackward compatibility modeOTPbackward compatibility modeThe default value for a new installation is false. For an upgrade, the value is set to true.Select Secure Access ControlGlobal SettingsAdvanced Configuration.Click the edit icon for poc.otp.backwardCompatibilityEnabled.Change the value from true, which enables backward compatibility mode, to false.Click OK.Deploy the changes when prompted.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Setting backward compatibility mode for one-time password

When you upgrade your installation, the setting for one-time password authentication is set to run in backward compatibility mode. Complete this task if you need to disable this mode.

About this task

The default value for a new installation is false. For an upgrade, the value is set to true.

Procedure

Select Secure Access Control > Global Settings > Advanced Configuration.

Click the edit icon for poc.otp.backwardCompatibilityEnabled.

Change the value from true, which enables backward compatibility mode, to false.

Click OK.

Deploy the changes when prompted.

Parent topic: Upgrading configuration

Updating template filesIf you want to update your template files to the latest version, complete this task. Otherwise, the template files from the previous version are ready for use after the upgrade.Download the new template file.Log in to the local management interface.Select Manage System SettingsFile Downloads.Expand access_controlpages and select mga_template_files.zip.Click Export.Extract the file.Edit and customize the template files, as necessary.Compress the template files into a .zip file.In the local management interface, select Secure Access ControlGlobal SettingsTemplate Files.Select ManageImport Zip.Click Browse and locate the .zip file you compressed in step 8.Click Open.Click Import.Deploy the changes.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Updating template files

If you want to update your template files to the latest version, complete this task. Otherwise, the template files from the previous version are ready for use after the upgrade.

Procedure

Download the new template file.

Log in to the local management interface.

Select Manage System Settings > File Downloads.

Expand access_control > pages and select mga_template_files.zip.

Click Export.

Extract the file.

Edit and customize the template files, as necessary.

Compress the template files into a .zip file.

In the local management interface, select Secure Access Control > Global Settings > Template Files.

Select Manage > Import Zip.

Click Browse and locate the .zip file you compressed in step 8.

Click Open.

Click Import.

Deploy the changes.

Parent topic: Upgrading configuration

Updating PreTokenGeneration to limit OAuth tokensUpdate the latest version of the PreTokenGeneration mapping rule to limit the number of OAuth tokens per user per definition.PreTokenGeneration mapping rulemapping rulesPreTokenGeneration oauth_20_pre_mapping.js mapping rule fileAPI protection definitionPreTokenGeneration mapping rule updateFollow this procedure so that any API protection definitions you created in a previous version can take advantage of limiting OAuth tokens. If you create new definitions, the latest PreTokenGeneration mapping rule is used.Log in to the local management interface.Download the updated mapping rule:Click Manage System SettingsFile Downloads.Expand access_controlexamples mapping_rules.Select oauth_20_pre_mapping.js.Click Export.Edit and customize the mapping rule if you customized it in the previous version.Replace the PreTokenGeneration mapping rule for the existing API protection definitions.Click Secure Access ControlAPI Protection.Click Advanced.Select the appropriate PreTokenGeneration mapping rule.Click Replace.Browse for the updated mapping rule and click OK.Deploy the changes.Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Updating PreTokenGeneration to limit OAuth tokens

Update the latest version of the PreTokenGeneration mapping rule to limit the number of OAuth tokens per user per definition.

About this task

Follow this procedure so that any API protection definitions you created in a previous version can take advantage of limiting OAuth tokens. If you create new definitions, the latest PreTokenGeneration mapping rule is used.

Procedure

Log in to the local management interface.

Download the updated mapping rule:

Click Manage System Settings > File Downloads.

Expand access_control > examples > mapping_rules.

Select oauth_20_pre_mapping.js.

Click Export.

Optional: Edit and customize the mapping rule if you customized it in the previous version.

Replace the PreTokenGeneration mapping rule for the existing API protection definitions.

Click Secure Access Control > API Protection.

Click Advanced.

Select the appropriate PreTokenGeneration mapping rule.

Click Replace.

Browse for the updated mapping rule and click OK.

Deploy the changes.

Parent topic: Upgrading configuration

Reviewing existing Web Reverse Proxy instance point of contact settingsAfter you upgrade from appliance v8.n.n.n to v9.n.n.n, it might be necessary to review and update some existing Web Reverse Proxy instance point of contact settings for the Advanced Access Control runtime. Reviewing ACL settings for Authentication Services REST endpoint A new REST endpoint for the Authentication Services Framework was introduced in v9.0.0.0. The default URL for this endpoint is “/mga/sps/apiauthsvc”. After an upgrade from a Security Access Manager appliance at v8.n.n.n, if you want to use the “/mga/sps/apiauthsvc” endpoint with an existing web reverse proxy, it might be necessary to create an ACL named “isam_mobile_rest_unauth” and attach it to the “/mga/sps/apiauthsvc” endpoint. You can use the following Security Access Manager policy administration commands to enable this setting. acl create "isam_mobile_rest_unauth" acl modify "isam_mobile_rest_unauth" set user "sec_master" TcmdbsvaBRrxl acl modify "isam_mobile_rest_unauth" set group iv-admin TcmdbsvaBRrxl acl modify "isam_mobile_rest_unauth" set group webseal-servers Tgmdbsrxl acl modify "isam_mobile_rest_unauth" set any-other Tmdrxl acl modify "isam_mobile_rest_unauth" set unauth Tmdrxl acl attach "/WebSEAL/<web reverse proxy>/mga/sps/apiauthsvc" "isam_mobile_rest_unauth"Reviewing EAI point of contact settings Some of the default settings that are related to Advanced Access Control point of contact and EAI headers changed in v9.0.0.0. After an upgrade from v8.n.n.n where an existing Web Reverse Proxy instance has been configured with Advanced Access Control, review the following settings and correct the settings if required. In the Web Reverse Proxy configuration file, check the [eai] stanza settings: # EAI HEADER NAMES # EAI PAC header names eai-pac-header = am-eai-pac eai-pac-svc-header = am-eai-pac-svc # EAI USER ID header names eai-user-id-header = am-eai-user-id eai-auth-level-header = am-eai-auth-level eai-xattrs-header = am-eai-xattrs # EAI external USER ID header names eai-ext-user-id-header = am-eai-ext-user-id eai-ext-user-groups-header = am-eai-ext-user-groups # EAI COMMON header names eai-redir-url-header = am-eai-redir-url The names of the headers must match the point of contact settings for the Advanced Access Control runtime. You can manage these settings with the local management interface by going to Secure Access Control Global SettingsPoint of Contact. Review the parameter value settings for the active point of contact profile. AAC point of contact parameter Reverse Proxy header namefim.user.response.header.nameam-eai-ext-user-id fim.target.response.header.name am-eai-redir-url fim.attributes.response.header.nameam-eai-xattrs fim.groups.response.header.nameam-eai-ext fim.user.request.header.nameiv-user fim.cred.request.header.nameiv-creds fim.groups.request.header.name iv-groups fim.cred.response.header.name am-eai-pac Upgrading configurationAfter you install the upgrade software on a Security Access Manager appliance, you must complete several configuration tasks.

Reviewing existing Web Reverse Proxy instance point of contact settings

After you upgrade from appliance v8.n.n.n to v9.n.n.n, it might be necessary to review and update some existing Web Reverse Proxy instance point of contact settings for the Advanced Access Control runtime.

Reviewing ACL settings for Authentication Services REST endpoint

A new REST endpoint for the Authentication Services Framework was introduced in v9.0.0.0. The default URL for this endpoint is “/mga/sps/apiauthsvc”. After an upgrade from a Security Access Manager appliance at v8.n.n.n, if you want to use the “/mga/sps/apiauthsvc” endpoint with an existing web reverse proxy, it might be necessary to create an ACL named “isam_mobile_rest_unauth” and attach it to the “/mga/sps/apiauthsvc” endpoint. You can use the following Security Access Manager policy administration commands to enable this setting.

acl create "isam_mobile_rest_unauth"
acl modify "isam_mobile_rest_unauth" set user "sec_master" TcmdbsvaBRrxl
acl modify "isam_mobile_rest_unauth" set group iv-admin TcmdbsvaBRrxl
acl modify "isam_mobile_rest_unauth" set group webseal-servers Tgmdbsrxl
acl modify "isam_mobile_rest_unauth" set any-other Tmdrxl
acl modify "isam_mobile_rest_unauth" set unauth Tmdrxl

acl attach "/WebSEAL/<web reverse proxy>/mga/sps/apiauthsvc" "isam_mobile_rest_unauth"

Reviewing EAI point of contact settings

Some of the default settings that are related to Advanced Access Control point of contact and EAI headers changed in v9.0.0.0. After an upgrade from v8.n.n.n where an existing Web Reverse Proxy instance has been configured with Advanced Access Control, review the following settings and correct the settings if required.

In the Web Reverse Proxy configuration file, check the [eai] stanza settings:

# EAI HEADER NAMES

# EAI PAC header names
eai-pac-header = am-eai-pac
eai-pac-svc-header = am-eai-pac-svc

# EAI USER ID header names
eai-user-id-header = am-eai-user-id
eai-auth-level-header = am-eai-auth-level
eai-xattrs-header = am-eai-xattrs

# EAI external USER ID header names
eai-ext-user-id-header = am-eai-ext-user-id
eai-ext-user-groups-header = am-eai-ext-user-groups

# EAI COMMON header names
eai-redir-url-header = am-eai-redir-url

The names of the headers must match the point of contact settings for the Advanced Access Control runtime. You can manage these settings with the local management interface by going to Secure Access Control > Global Settings > Point of Contact. Review the parameter value settings for the active point of contact profile.

AAC point of contact parameter | Reverse Proxy header name
fim.user.response.header.name | am-eai-ext-user-id
fim.target.response.header.name | am-eai-redir-url
fim.attributes.response.header.name | am-eai-xattrs
fim.groups.response.header.name | am-eai-ext
fim.user.request.header.name | iv-user
fim.cred.request.header.name | iv-creds
fim.groups.request.header.name | iv-groups
fim.cred.response.header.name | am-eai-pac

Parent topic: Upgrading configuration

Getting started with Advanced Access ControlGetting StartedSeveral configuration tasks must be completed in order to start using Advanced Access Control.getting startedconfigurestarting configurationstepsAfter setup of IBM Security Access Manager Appliance, complete an initial configuration of Advanced Access Control.If you have not already set up your appliance, see Getting StartedComplete the following tasks that apply to your appliance format..Complete the following tasks:Activate the productActivate the product after installation so you can use all available features. You can optionally import a support license file to receive updates to the appliance.. You must activate both the IBM Security Access Manager Platform offering and the Advanced Access Control Module.Manage application interfaces To manage application interfaces with the local management interface, use the Application Interfaces management page..Configure the runtime environmentTo manage configuration files with the local management interface, use the Runtime Component management page..Manage user registriesThe appliance runtime profile has a user registry associated. Use the User Registry management page to administer the users and group memberships. The user registry in discussion here is the one used by the runtime applications, not the one used by the management interface..Run the isamcfg tool.Various features of Advanced Access Control can be configured with the isamcfg tool.Review optional runtime security services EAS configuration tasks.The runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.You also might need to complete the following task to enable communication between appliances. See Adding runtime listening interfacesAdd your application interfaces to the list of runtime listening interfaces. This procedure enables communication between an appliance with Advanced Access Control and another Security Access Manager appliance..Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Getting started with Advanced Access Control

Several configuration tasks must be completed in order to start using Advanced Access Control.

After setup of IBM Security Access Manager Appliance, complete an initial configuration of Advanced Access Control.

Note: If you have not already set up your appliance, see Getting Started.

Complete the following tasks:

Activate the product. You must activate both the IBM Security Access Manager Platform offering and the Advanced Access Control Module.

Manage application interfaces.

Configure the runtime environment.

Manage user registries.

Run the isamcfg tool.

Review optional runtime security services EAS configuration tasks.

You also might need to complete the following task to enable communication between appliances. See Adding runtime listening interfaces.

Parent topic: Advanced Access Control configuration

Managing application interfacesManaging application interfacesAccess Manager Appliance: Managing application interfaces To manage application interfaces with the local management interface, use the Application Interfaces management page.application interfacemanageFrom the top menu, select Manage System Settings Network SettingsApplication Interfaces.All current application interfaces are displayed in tabs. Each tab contains the current addresses and settings for a particular interface.Select the tab of the interface that you want to work with. You can then add, edit, or delete an address on the corresponding interface tab.Add an addressClick New.In the Add Address page, provide details of the address to add.Select the Enabled check box if you want this address to be enabled after creation.Select IPv4 or IPv6 to indicate the type of address to add.If IPv4 is selected:Under IPv4 Settings, select either Static or Auto to indicate whether the IPv4 address is static or DHCP-assigned.Only one address per interface can be set to auto. If an existing address is already set to auto, then the Auto check box is disabled.Optional: If Static is selected in the previous step, you must enter the IPv4 address and subnet mask. If Auto is selected in the previous step, you can ignore the Address and Subnet Mask field.If IPv6 is selected, enter the IPv6 Address and Prefix.Click Save.Modify an addressMethod 1:Select the address to modify from the table.Click Edit.In the Edit Address page, modify as needed. See the Add an address section for descriptions of the fields.Click Save to save your changes.Method 2:In the table, double-click the field to edit.Make changes inline.Only some fields can be edited inline.Click outside the editing field to save the changes.Delete an addressSelect the address to delete from the table.Click Delete.In the Delete Address page, click Yes to confirm the deletion.Test connection to a serverClick Test.On the Ping Server page, enter the IP address or name of the server to test the connection with.Click Test. A message is then displayed indicating whether the ping operation was successful.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Managing application interfaces

To manage application interfaces with the local management interface, use the Application Interfaces management page.

Procedure

From the top menu, select Manage System Settings > Network Settings > Application Interfaces. All current application interfaces are displayed in tabs. Each tab contains the current addresses and settings for a particular interface.

Select the tab of the interface that you want to work with. You can then add, edit, or delete an address on the corresponding interface tab.

Add an address

Click New.

In the Add Address page, provide details of the address to add.

Select the Enabled check box if you want this address to be enabled after creation.

Select IPv4 or IPv6 to indicate the type of address to add.

If IPv4 is selected:

Under IPv4 Settings, select either Static or Auto to indicate whether the IPv4 address is static or DHCP-assigned.

Note: Only one address per interface can be set to auto. If an existing address is already set to auto, then the Auto check box is disabled.

Optional: If Static is selected in the previous step, you must enter the IPv4 address and subnet mask. If Auto is selected in the previous step, you can ignore the Address and Subnet Mask field.

If IPv6 is selected, enter the IPv6 Address and Prefix.

Click Save.

Modify an address

Method 1:

Select the address to modify from the table.

Click Edit.

In the Edit Address page, modify as needed. See the "Add an address " section for descriptions of the fields.

Click Save to save your changes.

Method 2:

In the table, double-click the field to edit.

Make changes inline.

Note: Only some fields can be edited inline.

Click outside the editing field to save the changes.

Delete an address

Select the address to delete from the table.

Click Delete.

In the Delete Address page, click Yes to confirm the deletion.

Test connection to a server

Click Test.

On the Ping Server page, enter the IP address or name of the server to test the connection with.

Click Test. A message is then displayed indicating whether the ping operation was successful.

Parent topic: Advanced Access Control configuration

Managing the runtime componentManaging runtime componentAccess Manager Appliance: Managing runtime configuration filesTo manage configuration files with the local management interface, use the Runtime Component management page.runtime componentmanageruntime componentconfigureWhen you first install the appliance, you must configure the runtime component. At any time after configuration, you can either edit the configuration settings, or unconfigure the runtime component.From the top menu, select Secure Web SettingsManageRuntime Component.Select one of the following actions.ConfigureOn the Main tab, select the User Registry type of LDAP.The runtime component does not communicate with the user registry, but you must select a registry type. It does not matter what user registry your system uses. Selection of the user registry type has no effect on the runtime component. Select LDAP in order to minimize the configuration steps.On the Policy Server tab, provide settings.Host name: The name of the host that hosts the IBM® Security Access Manager policy server.Port: The port over which communication with the IBM Security Access Manager policy server takes place.Management Domain: The IBM Security Access Manager domain name.Provide settings on the LDAP tab. Enter a Host name and accept the default value for Port. The host name and port values are just placeholders. The runtime component does not use the values, but the configuration wizard requires that values must be set. Click Finish to save the settings.Unconfigure the remote policy serverSelect the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.Click Submit to confirm operation.EditSelect the runtime configuration file of interest.Edit the configuration file and then click Save to save the changes. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert. For the changes to take effect, they must be deployed. Deploy pending changesSome configuration and administration changes require an extra deployment step.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Managing the runtime component

To manage configuration files with the local management interface, use the Runtime Component management page.

About this task

When you first install the appliance, you must configure the runtime component. At any time after configuration, you can either edit the configuration settings, or unconfigure the runtime component.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select one of the following actions.

Configure

On the Main tab, select the User Registry type of LDAP.

Note: The runtime component does not communicate with the user registry, but you must select a registry type. It does not matter what user registry your system uses. Selection of the user registry type has no effect on the runtime component. Select LDAP in order to minimize the configuration steps.

On the Policy Server tab, provide settings.

Host name: The name of the host that hosts the IBM® Security Access Manager policy server.

Port: The port over which communication with the IBM Security Access Manager policy server takes place.

Management Domain: The IBM Security Access Manager domain name.

Provide settings on the LDAP tab. Enter a Host name and accept the default value for Port.

Note: The host name and port values are just placeholders. The runtime component does not use the values, but the configuration wizard requires that values must be set.

Click Finish to save the settings.

Unconfigure the remote policy server

Select the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.

Note: Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.

Click Submit to confirm operation.

Edit

Select the runtime configuration file of interest.

Edit the configuration file and then click Save to save the changes. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert.

Note: For the changes to take effect, they must be deployed.

Parent topic: Advanced Access Control configuration

Related tasks:

Deploy pending changes

Managing user registriesManaging user registriesAccess Manager Appliance: Managing user registriesThe appliance runtime profile has a user registry associated. Use the User Registry management page to administer the users and group memberships. The user registry in discussion here is the one used by the runtime applications, not the one used by the management interface.From the top menu, select Secure Access ControlGlobal SettingsUser Registry.A list of all the current users in the registry is displayed. You can filter and reorder the list of users.Perform one or more of the following actions as needed:Create a user in the registryClick New.In the Create User window, enter the user name, password, and confirmation password for the new user.Click OK.Delete a user from the registrySelect the user to delete.Click Delete.In the window, click Yes to confirm the delete operation.Change the password of a user in the registrySelect the user for which you want to change password.Click Set Password.In the Set Password window, enter the password in the New Password and Confirm Password fields.Click OK.Manage group memberships of a userSelect the user of interest. The group memberships that are associated with this user are displayed under the Group Membership section. You can add the user to a group or delete the user from a group in the registry.Add the user to a groupIn the Group Membership section, click Add.In the Add to Group window, select the group to add this user to.Only a single group can be selected.Click OK.Remove the user from a groupIn the Group Membership section, select the group to remove the user from.Click Delete.In the window, click Yes to confirm the removal.When you make changes to the user registry, the appliance displays a message that there are undeployed changes. If you have finished making changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Managing user registries

The appliance runtime profile has a user registry associated. Use the User Registry management page to administer the users and group memberships. The user registry in discussion here is the one used by the runtime applications, not the one used by the management interface.

Procedure

From the top menu, select Secure Access Control > Global Settings > User Registry. A list of all the current users in the registry is displayed. You can filter and reorder the list of users.

Perform one or more of the following actions as needed:

Create a user in the registry

Click New.

In the Create User window, enter the user name, password, and confirmation password for the new user.

Click OK.

Delete a user from the registry

Select the user to delete.

Click Delete.

In the window, click Yes to confirm the delete operation.

Change the password of a user in the registry

Select the user for which you want to change password.

Click Set Password.

In the Set Password window, enter the password in the New Password and Confirm Password fields.

Click OK.

Manage group memberships of a user

Select the user of interest. The group memberships that are associated with this user are displayed under the Group Membership section.

You can add the user to a group or delete the user from a group in the registry.

Add the user to a group

In the Group Membership section, click Add.

In the Add to Group window, select the group to add this user to.

Note: Only a single group can be selected.

Click OK.

Remove the user from a group

In the Group Membership section, select the group to remove the user from.

Click Delete.

In the window, click Yes to confirm the removal.

When you make changes to the user registry, the appliance displays a message that there are undeployed changes. If you have finished making changes, deploy them.

For more information, see Deploying pending changes.

Parent topic: Advanced Access Control configuration

Runtime security services external authorization serviceThe runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.You can configure the runtime security services EAS to include context-based access decisions as part of the standard authorization on WebSEAL requests. WebSEAL becomes the authorization enforcement point for access to resources that context-based access protects.The runtime security services EAS constructs a request that it sends to the policy decision point (PDP). Based on the policy decision that is received from the PDP, the EAS takes one of the actions listed in the following table.Runtime security services EAS access decisions Runtime security services EAS access decisions ActionDescriptionPermitGrants access to the protected resource.DenyDenies access to the protected resource.Permit with AuthenticationGrants access to the protected resource, after a specific authentication action successfully takes place.Permit with ObligationGrants access to the protected resource, after the user successfully authenticates with a secondary challenge.Deny with ObligationDenies access to the protected resource, after the user unsuccessfully responds to a secondary challenge. The following steps set up the initial integration with Advanced Access Control: Configure runtime security services for client certificate authenticationConfigure runtime security services for client certificate authentication used for authentication between WebSEAL and Advanced Access Control..Run the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool. to automatically update the WebSEAL configuration file and to complete other configuration setup.(Optional) Update the WebSEAL configuration file to:Retain the version 7.0 attribute IDsIf your existing policies contain any of the changed attribute IDs, you can update your WebSEAL configuration file to continue using risk-based access version 7.0 IDs..Define custom attributes for the authorization serviceYou can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS)..Map an obligation to a URLYou can define the mapping between the obligation that the policy decision point (PDP) returns and the URL that attempts to satisfy the obligation..Permit access decisions when runtime security services cannot be contactedUpdate the WebSEAL configuration file if you want to change the behavior when runtime security services servers cannot be contacted by the EAS..For information about WebSEAL, see Web Reverse Proxy configurationUse the topics in this hierarchy to configure the Web Reverse Proxy..Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Configuring runtime security services for client certificate authenticationConfigure runtime security services for client certificate authentication used for authentication between WebSEAL and Advanced Access Control.Permitting access decisions when runtime security services cannot be contactedUpdate the WebSEAL configuration file if you want to change the behavior when runtime security services servers cannot be contacted by the EAS.Retaining the version 7.0 attribute IDs in existing policiesIf your existing policies contain any of the changed attribute IDs, you can update your WebSEAL configuration file to continue using risk-based access version 7.0 IDs.

Runtime security services external authorization service

The runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.

You can configure the runtime security services EAS to include context-based access decisions as part of the standard authorization on WebSEAL requests. WebSEAL becomes the authorization enforcement point for access to resources that context-based access protects.

The runtime security services EAS constructs a request that it sends to the policy decision point (PDP). Based on the policy decision that is received from the PDP, the EAS takes one of the actions listed in the following table.

Table 77. Runtime security services EAS access decisions.

Action | Description
Permit | Grants access to the protected resource.
Deny | Denies access to the protected resource.
Permit with Authentication | Grants access to the protected resource, after a specific authentication action successfully takes place.
Permit with Obligation | Grants access to the protected resource, after the user successfully authenticates with a secondary challenge.
Deny with Obligation | Denies access to the protected resource, after the user unsuccessfully responds to a secondary challenge.

The following steps set up the initial integration with Advanced Access Control:

Configure runtime security services for client certificate authentication.

Run the isamcfg tool to automatically update the WebSEAL configuration file and to complete other configuration setup.

(Optional) Update the WebSEAL configuration file to:

Retain the version 7.0 attribute IDs.

Define custom attributes for the authorization service.

Map an obligation to a URL.

Permit access decisions when runtime security services cannot be contacted.

For information about WebSEAL, see Web Reverse Proxy configuration.

Configuring runtime security services for client certificate authentication
Configure runtime security services for client certificate authentication used for authentication between WebSEAL and Advanced Access Control.

Permitting access decisions when runtime security services cannot be contacted
Update the WebSEAL configuration file if you want to change the behavior when runtime security services servers cannot be contacted by the EAS.

Retaining the version 7.0 attribute IDs in existing policies
If your existing policies contain any of the changed attribute IDs, you can update your WebSEAL configuration file to continue using risk-based access version 7.0 IDs.

Parent topic: Advanced Access Control configuration

Configuring runtime security services for client certificate authenticationConfiguring runtime security services for client certificate authenticationRuntime security services for client authenticationConfigure runtime security services for client certificate authentication used for authentication between WebSEAL and Advanced Access Control.client certificate authenticationcertificate authenticationruntime security servicesconfigure for client certificate authenticationBefore selecting the client certificate authentication option provided in the isamcfg tool, you must perform the following general steps for the client certificate:Generate a certificate that represents the user who will be authenticating from WebSEAL, or the Web Reverse Proxy, to Advanced Access Control. For example, use easuser.Import that certificate into the WebSEAL or Web Reverse Proxy key database as a personal certificate.Import the signer of this certificate as a trusted certificate in the Advanced Access Control keystore.Set Accept Client Certificates to True on the appliance.Create a client certificate for user easusercert.In the local management interface, go to Manage System Settings Secure SettingsSSL Certificates.Select the pdsrv certificate database.Click ManageEdit SSL Certificate Database.Click Personal Certificates.Click New to create a new personal certificate.Provide the following information:Certificate Label: easusercertCertificate Distinguished Name: cn=easuserKey Size: 2048Expiration Time (in days): 365Click Save.Deploy pending changes. See Deploying pending changesSome configuration and administration changes require an extra deployment step.. Restart your reverse proxy instances.Export the client certificate.Select the pdsrv certificate database.Click ManageEdit SSL Certificate Database.Click Personal Certificates.Select the easusercert certificate you created.Click ManageExport.Save the file.Import the exported personal certificate as a signer certificate on the appliance. The signer of the client certificate needs to be trusted. The certificate is self-signed. Importing the easusercert as a signer certificate into the appliances allows that trust.Click Manage System Settings Secure SettingsSSL Certificates.Select the rt_profiles_keys certificate database.Click ManageEdit SSL Certificate Database.Click Signer Certificates. Click ManageImport.Click Browse.Browse to the directory that contains the file to be imported and select the file. Click Open.Click Import. A message that indicates successful import is displayed.Deploy pending changes. See Deploying pending changesSome configuration and administration changes require an extra deployment step.. Configure the appliance for client certificate authentication.In the local management interface, go to Secure Access Control Global SettingsRuntime Parameters. Select Accept Client Certificates.Click Edit and set the value as True.Restart the runtime.Run the isamcfg tool. Ensure that you respond to the following isamcfg prompts appropriately:When answering the question Select the method for authentication between WebSEAL and the Advanced Access Control rumtime listening interface in the isamcfg tool, select Certificate Authentication.When prompted to enter the Advanced Access Control rumtime listening interface SSL keyfile label, enter the label of the certificate that represents the user who will be authenticating from WebSEAL or Web Reverse Proxy to Advanced Access Control.For more information, see isamcfg Security Access Manager appliance configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool..Runtime security services external authorization serviceThe runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.

Configuring runtime security services for client certificate authentication

Configure runtime security services for client certificate authentication used for authentication between WebSEAL and Advanced Access Control.

About this task

Before selecting the client certificate authentication option provided in the isamcfg tool, you must perform the following general steps for the client certificate:

Generate a certificate that represents the user who will be authenticating from WebSEAL, or the Web Reverse Proxy, to Advanced Access Control. For example, use easuser.

Import that certificate into the WebSEAL or Web Reverse Proxy key database as a personal certificate.

Import the signer of this certificate as a trusted certificate in the Advanced Access Control keystore.

Set Accept Client Certificates to True on the appliance.

Procedure

Create a client certificate for user easusercert.

In the local management interface, go to Manage System Settings > Secure Settings > SSL Certificates.

Select the pdsrv certificate database.

Click Manage > Edit SSL Certificate Database.

Click Personal Certificates.

Click New to create a new personal certificate.

Provide the following information:

Certificate Label: easusercert

Certificate Distinguished Name: cn=easuser

Key Size: 2048

Expiration Time (in days): 365

Click Save.

Deploy pending changes. See Deploying pending changes.

Restart your reverse proxy instances.

Export the client certificate.

Select the pdsrv certificate database.

Click Manage > Edit SSL Certificate Database.

Click Personal Certificates.

Select the easusercert certificate you created.

Click Manage > Export.

Save the file.

Import the exported personal certificate as a signer certificate on the appliance. The signer of the client certificate needs to be trusted. The certificate is self-signed. Importing the easusercert as a signer certificate into the appliances allows that trust.

Click Manage System Settings > Secure Settings > SSL Certificates.

Select the rt_profiles_keys certificate database.

Click Manage > Edit SSL Certificate Database.

Click Signer Certificates.

Click Manage > Import.

Click Browse.

Browse to the directory that contains the file to be imported and select the file. Click Open.

Click Import. A message that indicates successful import is displayed.

Deploy pending changes. See Deploying pending changes.

Configure the appliance for client certificate authentication.

In the local management interface, go to Secure Access Control > Global Settings > Runtime Parameters.

Select Accept Client Certificates.

Click Edit and set the value as True.

Restart the runtime.

What to do next

Run the isamcfg tool. Ensure that you respond to the following isamcfg prompts appropriately:

When answering the question Select the method for authentication between WebSEAL and the Advanced Access Control rumtime listening interface in the isamcfg tool, select Certificate Authentication.

When prompted to enter the Advanced Access Control rumtime listening interface SSL keyfile label, enter the label of the certificate that represents the user who will be authenticating from WebSEAL or Web Reverse Proxy to Advanced Access Control.

For more information, see isamcfg Security Access Manager appliance configuration worksheet.

Parent topic: Runtime security services external authorization service

Permitting access decisions when runtime security services cannot be contactedUpdate the WebSEAL configuration file if you want to change the behavior when runtime security services servers cannot be contacted by the EAS.By default, if the EAS cannot contact a runtime security services server, the EAS removes the server from the pool of servers. If all of the servers are removed from the pool, WebSEAL returns an error. To prevent the error, you can permit access decisions even if no servers can be contacted. The following instructions show you how to update the WebSEAL configuration file to make this change. When you perform this task, every single request will be permitted only when none of the runtime security services servers are available. This includes access that might not be permitted if the server was available.Open the WebSEAL configuration file.Add the following entry to the [rtss-eas] stanza: permit-when-no-rtss-available = true The default value for this entry is false. Save the file.Restart the WebSEAL server for the change to take effect.If none of the servers are available, the user is always be permitted to access a resource. The access is granted even when the runtime security services server would normally deny access if it was available.Runtime security services external authorization serviceThe runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.

Permitting access decisions when runtime security services cannot be contacted

Update the WebSEAL configuration file if you want to change the behavior when runtime security services servers cannot be contacted by the EAS.

About this task

By default, if the EAS cannot contact a runtime security services server, the EAS removes the server from the pool of servers. If all of the servers are removed from the pool, WebSEAL returns an error. To prevent the error, you can permit access decisions even if no servers can be contacted. The following instructions show you how to update the WebSEAL configuration file to make this change.

Important: When you perform this task, every single request will be permitted only when none of the runtime security services servers are available. This includes access that might not be permitted if the server was available.

Procedure

Open the WebSEAL configuration file.

Add the following entry to the [rtss-eas] stanza:

permit-when-no-rtss-available = true

The default value for this entry is false.

Save the file.

Restart the WebSEAL server for the change to take effect.

Results

If none of the servers are available, the user is always be permitted to access a resource. The access is granted even when the runtime security services server would normally deny access if it was available.

Parent topic: Runtime security services external authorization service

Retaining the version 7.0 attribute IDs in existing policiesIf your existing policies contain any of the changed attribute IDs, you can update your WebSEAL configuration file to continue using risk-based access version 7.0 IDs.attribute IDsversion 7.0usageversion 7.0attribute ID updatesWebSEALuse 7.0 attribute IDsruntime security servicesattribute ID changesIDD: Need to resolve where/how to specify the pre-reqs for this: ISAM for Web v 7.0 FP 2 or later, and 6.1.1. Clearinghouse or HWSW reqs?This topic, and its two child topics, were removed from Beta 2, per direction from Ann and Ben. Need to find out if these topics belong in 8.0 at all.. Determine whether it is necessary for you to continue using the risk-based access version 7.0 IDs.Use the following procedure to continue to use the version 7.0 attribute IDs.Open the WebSEAL configuration file, and locate the [rtss-eas] stanza.Add the provide_700_attribute_ids flag and set it to true. This flag enables your existing policies to use the version 7.0 attribute IDs. For example: [rtss-eas] provide_700_attribute_ids = true Save the file.Restart the WebSEAL server for the changes to take effect.Runtime security services external authorization serviceThe runtime security services external authorization service (EAS) provides the policy enforcement point function for context-based access.

Retaining the version 7.0 attribute IDs in existing policies

If your existing policies contain any of the changed attribute IDs, you can update your WebSEAL configuration file to continue using risk-based access version 7.0 IDs.

Before you begin

. Determine whether it is necessary for you to continue using the risk-based access version 7.0 IDs.

About this task

Use the following procedure to continue to use the version 7.0 attribute IDs.

Procedure

Open the WebSEAL configuration file, and locate the [rtss-eas] stanza.

Add the provide_700_attribute_ids flag and set it to true. This flag enables your existing policies to use the version 7.0 attribute IDs. For example:

[rtss-eas]
provide_700_attribute_ids = true

Save the file.

Restart the WebSEAL server for the changes to take effect.

Parent topic: Runtime security services external authorization service

Using the isamcfg toolUsing the isamcfg toolUsing the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.isamcfg overviewtool isamcfgThe isamcfg tool helps automate configuration of the following software and appliances: WebSEALSecurity Access Manager applianceSecurity Access Manager for Web applianceSecurity Access Manager for Web software versionSecurity Web Gateway appliance The tools helps with:Creating a junction that points to the Advanced Access Manager runtime endpoint. Creating a Security Access Manager POP used by Advanced Access Control to attach a policy.Configuring the instance of the appliance that supplies the web function, such as WebSEAL, with the instance of the appliance that provides the authorization server for Advanced Access Control.Configuring SSL, sets up key stores, trust stores, and authentication configuration between Advanced Access Control and the web function.Configuring a set of default obligation-to-URL mappings for the authentication service.Modifying the Security Access Manager appliance authentication configuration to support the authentication service.If you are upgrading, see the installation and configuration instructions in the IBM Knowledge Center. If you are upgrading from a previous version of the product, run the isamcfg tool to unconfigure the current version. Then, run the isamcfg tool to configure the new version.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Configuring an appliance reverse proxy instance from the applianceUse the isamcfg tool to configure an appliance reverse proxy instance from a local or remote appliance. Configuring an appliance reverse proxy instance from an external machineUse the isamcfg tool to configure an appliance reverse proxy instance from a remote machine.Configuring a WebSEAL instanceUse the isamcfg tool to configure WebSEAL as a point of contact and policy enforcement point for an appliance that has Advanced Access Control activated.Configuring WebSEAL in a highly available environmentWhen you are working in an environment with multiple Security Access Manager with Advanced Access Control servers, you can configure WebSEAL for failover and high availability. isamcfg referenceUse the isamcfg tool to configure WebSEAL and Security Access Manager appliance servers. You configure a point of contact and policy enforcement point.Using a response fileCreate and use a response file with the isamcfg tool to configure WebSEAL and IBM Security Access Manager for Web 7.0.

Using the isamcfg tool

Various features of Advanced Access Control can be configured with the isamcfg tool.

The isamcfg tool helps automate configuration of the following software and appliances:

WebSEAL

Security Access Manager appliance

Security Access Manager for Web appliance

Security Access Manager for Web software version

Security Web Gateway appliance

The tools helps with:

Creating a junction that points to the Advanced Access Manager runtime endpoint.

Creating a Security Access Manager POP used by Advanced Access Control to attach a policy.

Configuring the instance of the appliance that supplies the web function, such as WebSEAL, with the instance of the appliance that provides the authorization server for Advanced Access Control.

Configuring SSL, sets up key stores, trust stores, and authentication configuration between Advanced Access Control and the web function.

Configuring a set of default obligation-to-URL mappings for the authentication service.

Modifying the Security Access Manager appliance authentication configuration to support the authentication service.

Note: If you are upgrading, see the installation and configuration instructions in the IBM Knowledge Center.

If you are upgrading from a previous version of the product, run the isamcfg tool to unconfigure the current version. Then, run the isamcfg tool to configure the new version.

Configuring an appliance reverse proxy instance from the appliance
Use the isamcfg tool to configure an appliance reverse proxy instance from a local or remote appliance.

Configuring an appliance reverse proxy instance from an external machine
Use the isamcfg tool to configure an appliance reverse proxy instance from a remote machine.

Configuring a WebSEAL instance
Use the isamcfg tool to configure WebSEAL as a point of contact and policy enforcement point for an appliance that has Advanced Access Control activated.

Configuring WebSEAL in a highly available environment
When you are working in an environment with multiple Security Access Manager with Advanced Access Control servers, you can configure WebSEAL for failover and high availability.

isamcfg reference
Use the isamcfg tool to configure WebSEAL and Security Access Manager appliance servers. You configure a point of contact and policy enforcement point.

Using a response file
Create and use a response file with the isamcfg tool to configure WebSEAL and IBM Security Access Manager for Web 7.0.

Parent topic: Advanced Access Control configuration

Configuring an appliance reverse proxy instance from the applianceConfiguring an appliance reverse proxy instance from the applianceConfiguring an appliance reverse proxy instance from the applianceUse the isamcfg tool to configure an appliance reverse proxy instance from a local or remote appliance. isamcfg tool applianceRun the command from the appliance command-line interface. You must use this method to configure a reverse proxy instance on an appliance that is a restricted node in a cluster. Your appliance can be one of the following product versions: Security Access Manager 9.*Security Access Manager for Web 8.*Security Web Gateway 7.*Connect to the appliance with SSH. Enter the administrator user ID and password.Navigate to isamauto_configconfig. The isamcfg tool starts.Use isamcfg to complete the configuration. For configuration details, see isamcfg Security Access Manager appliance configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool..When you complete the configuration, a summary screen displays indicating that the configuration is complete.Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.

Configuring an appliance reverse proxy instance from the appliance

Use the isamcfg tool to configure an appliance reverse proxy instance from a local or remote appliance.

About this task

Run the command from the appliance command-line interface.

You must use this method to configure a reverse proxy instance on an appliance that is a restricted node in a cluster.

Note: Your appliance can be one of the following product versions:

Security Access Manager 9.*

Security Access Manager for Web 8.*

Security Web Gateway 7.*

Procedure

Connect to the appliance with SSH.

Enter the administrator user ID and password.

Navigate to isam > auto_config > config. The isamcfg tool starts.

Use isamcfg to complete the configuration. For configuration details, see isamcfg Security Access Manager appliance configuration worksheet.

Results

When you complete the configuration, a summary screen displays indicating that the configuration is complete.

Parent topic: Using the isamcfg tool

Configuring an appliance reverse proxy instance from an external machineConfiguring an appliance reverse proxy instance from an external machineConfiguring an appliance reverse proxy instance from an external machineUse the isamcfg tool to configure an appliance reverse proxy instance from a remote machine.isamcfg tool reverse proxy instanceisamcfg tool external machineYour appliance server and Advanced Access Control servers must be listening for connections on the appropriate management IP addresses and port numbers. To use the isamcfg tool, you must meet the following conditions: Obtain an IBM® JRE v6.0 Update 10 or later.At least one reverse proxy instance exists on the appliance.Configure the com.ibm.security.cmskeystore.CMSProvider in the java.security file, which is in $JAVA_HOME/lib/security, of the IBM JRE. The isamcfg tool uses the ikeycmd command to manipulate key database files. This requires the JRE to have the CMS provider that is configured in the java.security file. Ensure that the ikeycmd tool in the $JAVA_HOME/bin is on the system path.The reverse proxy instance that you are configuring cannot be on an appliance that is a restricted node in a cluster. See Configuring an appliance reverse proxy instance from the applianceUse the isamcfg tool to configure an appliance reverse proxy instance from a local or remote appliance. .Use this procedure if you want to configure an appliance that is on a machine that is separate from the Advanced Access Control appliance. Once you download the tool from the Advanced Access Control appliance, you can then use the command shell to configure an existing remote appliance.The appliance you configure can be one of the following product versions: Security Access Manager 9.*Security Access Manager for Web 8.*Security Web Gateway 7.*Download the isamcfg.jar from the IBM Security Access Manager appliance with Advanced Access Control activated. From the command line, type: java -jar isamcfg -action config -cfgurl http://isam-appliance-host-url/ The isam-appliance-host-url/ refers to the URL of the activated Security Access Manager appliance base.Use the isamcfg tool to complete the configuration. For configuration details, see isamcfg Security Access Manager appliance configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool..When you complete the configuration, a summary screen displays indicating that the configuration is complete.Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.

Configuring an appliance reverse proxy instance from an external machine

Use the isamcfg tool to configure an appliance reverse proxy instance from a remote machine.

Before you begin

Your appliance server and Advanced Access Control servers must be listening for connections on the appropriate management IP addresses and port numbers.

To use the isamcfg tool, you must meet the following conditions:

Obtain an IBM® JRE v6.0 Update 10 or later.

At least one reverse proxy instance exists on the appliance.

Configure the com.ibm.security.cmskeystore.CMSProvider in the java.security file, which is in $JAVA_HOME/lib/security, of the IBM® JRE. The isamcfg tool uses the ikeycmd command to manipulate key database files. This requires the JRE to have the CMS provider that is configured in the java.security file.

Ensure that the ikeycmd tool in the $JAVA_HOME/bin is on the system path.

The reverse proxy instance that you are configuring cannot be on an appliance that is a restricted node in a cluster. See Configuring an appliance reverse proxy instance from the appliance.

About this task

Use this procedure if you want to configure an appliance that is on a machine that is separate from the Advanced Access Control appliance. Once you download the tool from the Advanced Access Control appliance, you can then use the command shell to configure an existing remote appliance.

The appliance you configure can be one of the following product versions:

Security Access Manager 9.*

Security Access Manager for Web 8.*

Security Web Gateway 7.*

Procedure

Download the isamcfg.jar from the IBM Security Access Manager appliance with Advanced Access Control activated.

From the command line, type:

java -jar isamcfg -action config -cfgurl http://isam-appliance-host-url/

The isam-appliance-host-url/ refers to the URL of the activated Security Access Manager appliance base.

Use the isamcfg tool to complete the configuration. For configuration details, see isamcfg Security Access Manager appliance configuration worksheet.

Results

When you complete the configuration, a summary screen displays indicating that the configuration is complete.

Parent topic: Using the isamcfg tool

Configuring a WebSEAL instanceConfiguring a WebSEAL instanceConfiguring a WebSEAL instanceUse the isamcfg tool to configure WebSEAL as a point of contact and policy enforcement point for an appliance that has Advanced Access Control activated.isamcfg WebSEAL point of contactWebSEAL policy enforcement pointisamcfgreverse proxy instanceisamcfgMake sure that your WebSEAL server is listening for connections on the appropriate IP addresses and port numbers. You can control the IP address and port number by using the WebSEAL configuration file. The IP address is controlled by the [server] network-interface configuration option, and the port numbers are controlled by the [server] https-port and [server] http-port options. To use the isamcfg tool, you must:Obtain an IBM JRE, version 6.0, Update 10 or later that is supported by the version of PDJrte installed.Ensure that the Java Runtime used to start the isamcfg tool is configured into the Security Access Manager domain in full mode that uses the PDJRTE. An error is displayed if this condition is not met. For more information about using the PDJRTE, see http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/60/iKeyman.8.User.Guide.pdf.Ensure that the isamcfg tool is able to access the application interface for Advanced Access Control.Run the command from the appliance that hosts the reverse proxy instance, if the instance is a restricted node in a cluster. Also, you must use the command-line interface to run the command.For IBM Security Access Manager WebSEAL, version 7.0 or later, you must also meet the following conditions:Configure the com.ibm.security.cmskeystore.CMSProvider in the java.security file, which is in $JAVA_HOME/lib/security, of the IBM JRE. The isamcfg tool uses the ikeycmd command to manipulate key database files. This requires the JRE to have the CMS provider that is configured in the java.security file. Ensure that the ikeycmd tool in the $JAVA_HOME/bin is on the system path.For Tivoli Access Manager for e-business WebSEAL versions 6.1.1 or prior, ensure that gsk7ikm tool is on the system path.Run the tool on the same system where WebSEAL is located.This procedure connects the WebSEAL software version 7.* to Security Access Manager. This procedure is not intended for deployments that have a Security Access Manager appliance with the WebSEAL function.Download the isamcfg.jar from the Security Access Manager appliance with Advanced Access Control. On the WebSEAL machine, set up a JAVA_HOME environment variable for the JRE: For example:export JAVA_HOME=/opt/ibm/java-x86_64-60/jre, orexport JAVA_HOME=/opt/IBM/WebSphere/AppServer/java/jreAdd $JAVA_HOME/bin to the path export PATH=$JAVA_HOME/bin:$PATH.From the command line, type: java -jar isamcfg.jar -action config -cfgfile /path/to/webseald.confUse the isamcfg tool to complete the configuration. For configuration details, see isamcfg WebSEAL configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool..When you complete the configuration, a summary screen displays indicating that the configuration is complete.Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.

Configuring a WebSEAL instance

Use the isamcfg tool to configure WebSEAL as a point of contact and policy enforcement point for an appliance that has Advanced Access Control activated.

Before you begin

Make sure that your WebSEAL server is listening for connections on the appropriate IP addresses and port numbers. You can control the IP address and port number by using the WebSEAL configuration file. The IP address is controlled by the [server] network-interface configuration option, and the port numbers are controlled by the [server] https-port and [server] http-port options.

To use the isamcfg tool, you must:

Obtain an IBM® JRE, version 6.0, Update 10 or later that is supported by the version of PDJrte installed.

Ensure that the Java Runtime used to start the isamcfg tool is configured into the Security Access Manager domain in full mode that uses the PDJRTE. An error is displayed if this condition is not met. For more information about using the PDJRTE, see http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/security/60/iKeyman.8.User.Guide.pdf.

Ensure that the isamcfg tool is able to access the application interface for Advanced Access Control.

Run the command from the appliance that hosts the reverse proxy instance, if the instance is a restricted node in a cluster. Also, you must use the command-line interface to run the command.

For IBM Security Access Manager WebSEAL, version 7.0 or later, you must also meet the following conditions:

Configure the com.ibm.security.cmskeystore.CMSProvider in the java.security file, which is in $JAVA_HOME/lib/security, of the IBM JRE. The isamcfg tool uses the ikeycmd command to manipulate key database files. This requires the JRE to have the CMS provider that is configured in the java.security file.

Ensure that the ikeycmd tool in the $JAVA_HOME/bin is on the system path.

For Tivoli Access Manager for e-business WebSEAL versions 6.1.1 or prior, ensure that gsk7ikm tool is on the system path.

Run the tool on the same system where WebSEAL is located.

About this task

This procedure connects the WebSEAL software version 7.* to Security Access Manager.

Note: This procedure is not intended for deployments that have a Security Access Manager appliance with the WebSEAL function.

Procedure

Download the isamcfg.jar from the Security Access Manager appliance with Advanced Access Control.

On the WebSEAL machine, set up a JAVA_HOME environment variable for the JRE: For example:

export JAVA_HOME=/opt/ibm/java-x86_64-60/jre, or

export JAVA_HOME=/opt/IBM/WebSphere/AppServer/java/jre

Add $JAVA_HOME/bin to the path export PATH=$JAVA_HOME/bin:$PATH.

From the command line, type:

java -jar isamcfg.jar -action config -cfgfile /path/to/webseald.conf

Use the isamcfg tool to complete the configuration. For configuration details, see isamcfg WebSEAL configuration worksheet.

Results

When you complete the configuration, a summary screen displays indicating that the configuration is complete.

Parent topic: Using the isamcfg tool

Configuring WebSEAL in a highly available environmentConfiguring WebSEAL in a highly available environmentConfiguring WebSEAL in a highly available environmentWhen you are working in an environment with multiple Security Access Manager with Advanced Access Control servers, you can configure WebSEAL for failover and high availability. clusterconfigurationmaster nodesconfigureregistrationunregistrationclustercluster configuration management pageLMIcluster signature fileexportimportLMIcluster configuration management pageYou can configure the WebSEAL junction and Runtime Security Services External Authorization Service (RTSS EAS) to take advantage of high availability.Figure 1 depicts an environment where WebSEAL is configured to use two Security Access Manager servers, AAC_1 and AAC_2. AAC_1 and AAC_2 are appliances with Advanced Access Control activated. For high availability, you can configure a stateful junction to each available appliance. You can also include each server in the RTSS EAS configuration. WebSEAL client in an environment with multiple IBM Security Access Manager serversWebSEAL client in an environment with multiple IBM Security Access Manager serversAdvanced Access Control provides the isamcfg tool which configures each WebSEAL instance. This tool sets up a single junction server and configures the RTSS EAS to point to a single appliance. If you have more than one appliance with Advanced Access Control activated, you need to manually configure the additional servers. For each Advanced Access Control appliance, include a server entry in the [rtss-cluster:<cluster>] stanza in the WebSEAL configuration file (for example, webseald-default.conf).[rtss-cluster:cluster1] server = 9,https://192.0.2.0:443/rtss/authz/services/AuthzService server = 9,https://192.0.2.5:443/rtss/authz/services/AuthzService The first parameter in each entry is the priority of the server in the cluster. Set the priority of your servers as appropriate to your environment. Using a priority of 9 for all servers evenly distributes the load and switches between the available appliances. The second parameter is a well-formed Uniform Resource Locator (URL) for the runtime security services on the appliance. Use the IP address of the application interface on the Advanced Access Control-activated appliance. Use the pdadmin utility to add extra servers to the junction. pdadmin sec_master> server task default-webseald-test.example.com add -h 192.0.2.0 -p 443 /mga pdadmin sec_master> server task default-webseald-test.example.com add -h 192.0.2.5 -p 443 /mga You must replace all example values in these commands with values that are appropriate to your environment.The first parameter in this server task command is the fully qualified name of the WebSEAL server. For example, default-webseald-test.example.com.The -h option specifies the appliance that you want to add to the junction. Use the IP address of the application interface on the target appliance.The isamcfg tool creates an SSL junction by default. Therefore, when you are adding servers to this junction, use the SSL port number 443.By default, the isamcfg tool creates a junction that is called /mga. This default value is used in the example commands.For secure communication between WebSEAL and the appliance, use trusted certificates. WebSEAL must trust the certificates that are presented by the appliance. To establish this trust, you can use a common certificate authority (CA) that is trusted in your environment or you can configure WebSEAL to trust each individual certificate. Similarly, for client certificate authentication, the Advanced Access Control appliance must trust the certificates that are presented by WebSEAL. To configure failover between junctioned servers, set the use-new-stateful-on-error stanza entry to yes for the stateful junction to the appliance. That is, update the use-new-stateful-on-error entry in the [junction:/mga] stanza in the WebSEAL configuration file. Where /mga is the name of the junction. The isamcfg tool creates a junction that is called /mga by default, but this name is configurable. If a stateful junction becomes unavailable when this value is set to yes, WebSEAL fails over to a different server. For example, if the stateful junction to AAC_1 in Figure 1 becomes unavailable, WebSEAL fails over to AAC_2. Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.

Configuring WebSEAL in a highly available environment

When you are working in an environment with multiple Security Access Manager with Advanced Access Control servers, you can configure WebSEAL for failover and high availability.

About this task

You can configure the WebSEAL junction and Runtime Security Services External Authorization Service (RTSS EAS) to take advantage of high availability.

Figure 59. depicts an environment where WebSEAL is configured to use two Security Access Manager servers, AAC_1 and AAC_2. AAC_1 and AAC_2 are appliances with Advanced Access Control activated. For high availability, you can configure a stateful junction to each available appliance. You can also include each server in the RTSS EAS configuration.

Figure 59. WebSEAL client in an environment with multiple IBM Security Access Manager servers

Advanced Access Control provides the isamcfg tool which configures each WebSEAL instance. This tool sets up a single junction server and configures the RTSS EAS to point to a single appliance.

If you have more than one appliance with Advanced Access Control activated, you need to manually configure the additional servers.

Procedure

For each Advanced Access Control appliance, include a server entry in the [rtss-cluster:<cluster>] stanza in the WebSEAL configuration file (for example, webseald-default.conf).

[rtss-cluster:cluster1]
server = 9,https://192.0.2.0:443/rtss/authz/services/AuthzService
server = 9,https://192.0.2.5:443/rtss/authz/services/AuthzService

Note:

The first parameter in each entry is the priority of the server in the cluster. Set the priority of your servers as appropriate to your environment. Using a priority of 9 for all servers evenly distributes the load and switches between the available appliances.

The second parameter is a well-formed Uniform Resource Locator (URL) for the runtime security services on the appliance. Use the IP address of the application interface on the Advanced Access Control-activated appliance.

Use the pdadmin utility to add extra servers to the junction.

pdadmin sec_master> server task default-webseald-test.example.com add -h
 192.0.2.0 -p 443 /mga
pdadmin sec_master> server task default-webseald-test.example.com add -h
 192.0.2.5 -p 443 /mga

Note:

You must replace all example values in these commands with values that are appropriate to your environment.

The first parameter in this server task command is the fully qualified name of the WebSEAL server. For example, default-webseald-test.example.com.

The -h option specifies the appliance that you want to add to the junction. Use the IP address of the application interface on the target appliance.

The isamcfg tool creates an SSL junction by default. Therefore, when you are adding servers to this junction, use the SSL port number 443.

By default, the isamcfg tool creates a junction that is called /mga. This default value is used in the example commands.

For secure communication between WebSEAL and the appliance, use trusted certificates. WebSEAL must trust the certificates that are presented by the appliance. To establish this trust, you can use a common certificate authority (CA) that is trusted in your environment or you can configure WebSEAL to trust each individual certificate.

Similarly, for client certificate authentication, the Advanced Access Control appliance must trust the certificates that are presented by WebSEAL.

To configure failover between junctioned servers, set the use-new-stateful-on-error stanza entry to yes for the stateful junction to the appliance. That is, update the use-new-stateful-on-error entry in the [junction:/mga] stanza in the WebSEAL configuration file. Where /mga is the name of the junction. The isamcfg tool creates a junction that is called /mga by default, but this name is configurable.

If a stateful junction becomes unavailable when this value is set to yes, WebSEAL fails over to a different server. For example, if the stateful junction to AAC_1 in Figure 59. becomes unavailable, WebSEAL fails over to AAC_2.

Parent topic: Using the isamcfg tool

isamcfg referenceisamcfg referenceisamcfg referenceUse the isamcfg tool to configure WebSEAL and Security Access Manager appliance servers. You configure a point of contact and policy enforcement point.isamcfg referenceThe appliance you configure can be one of the following product versions: Security Access Manager 9.*Security Access Manager for Web 8.*Security Web Gateway 7.*Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.isamcfg command line referenceUse the command line options described in this section to configure and unconfigure WebSEAL and Security Access Manager appliance servers. isamcfg Security Access Manager appliance configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.isamcfg WebSEAL configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.

isamcfg reference

Use the isamcfg tool to configure WebSEAL and Security Access Manager appliance servers. You configure a point of contact and policy enforcement point.

The appliance you configure can be one of the following product versions:

Security Access Manager 9.*

Security Access Manager for Web 8.*

Security Web Gateway 7.*

isamcfg command line reference
Use the command line options described in this section to configure and unconfigure WebSEAL and Security Access Manager appliance servers.

isamcfg Security Access Manager appliance configuration worksheet
Use the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.

isamcfg WebSEAL configuration worksheet
Use the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.

Parent topic: Using the isamcfg tool

isamcfg command line referenceisamcfg command line referenceisamcfg command line referenceUse the command line options described in this section to configure and unconfigure WebSEAL and Security Access Manager appliance servers. isamcfg command line referenceSyntaxjava -jar isamcfg.jar -action mode optionsDescriptionThe configuration tool has two modes of operation:configunconfigEach mode uses different command line options.Options-action config optionsThis command configures a WebSEAL or Secure Access Manager appliance server. This mode uses different command line options:-cfgfile fileSpecifies which WebSEAL configuration file to use. This option is required when configuring a WebSEAL server.-cfgurl URLSpecifies the appliance configuration URL to use. This option is required if configuring a Security Access Manager appliance.-rspfile fileSpecifies the response file for a configuration that is not interactive. Default value: Interactive configuration.-recordGenerates a response file without making changes to WebSEAL or the Security Access Manager appliance configuration.-sslfactorySpecifies the secure socket connection factory to use.When the Security Access Manager environment is enabled for NIST SP800-131a Strict mode, the only supported factory type is TLSv1.2.If the parameter is not specified, the factory default is TLS. -action unconfig optionsThis command unconfigures a WebSEAL or Security Access Manager appliance server. This mode uses different command line options:-cfgfile fileSpecifies which WebSEAL configuration file to use. This option is required when unconfiguring a WebSEAL server.-cfgurl URLSpecifies the Security Access Manager appliance configuration URL to use. This option is required when unconfiguring a Security Access Manager appliance.-rspfile fileSpecifies the response file for a configuration that is not interactive. Default value: Interactive configuration.-recordGenerates response file without making changes to WebSEAL or Security Access Manager appliance configuration.-sslfactorySpecifies the secure socket connection factory to use.When the IBM Security Access Manager environment is enabled for NIST SP800-131a Strict mode, the only supported factory type is TLSv1.2.If the parameter is not specified, the factory default is TLS. Examplejava -jar isamcfg.jar -action -config -cfgfile webseald.confThe log files for the isamcfg tool are written to the system temporary directory. The system temporary file directory is specified by the system property java.io.tmpdir.isamcfg referenceUse the isamcfg tool to configure WebSEAL and Security Access Manager appliance servers. You configure a point of contact and policy enforcement point.

isamcfg command line reference

Use the command line options described in this section to configure and unconfigure WebSEAL and Security Access Manager appliance servers.

Syntax

java -jar isamcfg.jar -action mode options

Description

The configuration tool has two modes of operation:

config

unconfig

Each mode uses different command line options.

Options

-action config options

This command configures a WebSEAL or Secure Access Manager appliance server. This mode uses different command line options:

-cfgfile file

Specifies which WebSEAL configuration file to use. This option is required when configuring a WebSEAL server.

-cfgurl URL

Specifies the appliance configuration URL to use. This option is required if configuring a Security Access Manager appliance.

-rspfile file

Specifies the response file for a configuration that is not interactive.

Default value: Interactive configuration.

-record

Generates a response file without making changes to WebSEAL or the Security Access Manager appliance configuration.

-sslfactory

Specifies the secure socket connection factory to use.

When the Security Access Manager environment is enabled for NIST SP800-131a Strict mode, the only supported factory type is TLSv1.2.

If the parameter is not specified, the factory default is TLS.

-action unconfig options

This command unconfigures a WebSEAL or Security Access Manager appliance server. This mode uses different command line options:

-cfgfile file

Specifies which WebSEAL configuration file to use. This option is required when unconfiguring a WebSEAL server.

-cfgurl URL

Specifies the Security Access Manager appliance configuration URL to use. This option is required when unconfiguring a Security Access Manager appliance.

-rspfile file

Specifies the response file for a configuration that is not interactive.

Default value: Interactive configuration.

-record

Generates response file without making changes to WebSEAL or Security Access Manager appliance configuration.

-sslfactory

Specifies the secure socket connection factory to use.

When the IBM® Security Access Manager environment is enabled for NIST SP800-131a Strict mode, the only supported factory type is TLSv1.2.

If the parameter is not specified, the factory default is TLS.

Example

java -jar isamcfg.jar -action -config -cfgfile webseald.conf

The log files for the isamcfg tool are written to the system temporary directory. The system temporary file directory is specified by the system property java.io.tmpdir.

Parent topic: isamcfg reference

isamcfg Security Access Manager appliance configuration worksheetisamcfg Security Access Manager appliance configuration worksheetisamcfg Security Access Manager appliance configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.isamcfg tool isamcfg worksheet If you are upgrading the Advanced Access Control module, see the installation and configuration instructions.Description of propertiesSelect/deselect the capabilities you would like to configure by typing its number.By default, the tool selects context-based authorization, authentication service, and API protection. You can configure all of them at the same time. If you do not want to configure them all, clear the capability that you do not want to configure by selecting its corresponding number. Context-based AuthorizationConfigure this capability if your environment requires the use of behavioral and contextual data analytics to calculate the risk of a transaction. Authentication serviceConfigure this capability if your environment requires the use of a step-up authentication type of authentication. API ProtectionConfigure this capability if your environment requires the use of an OAuth authentication type to protect your Application Programming Interface (API).Advanced Access Control Local Management Interface hostnameEnter the Local Management Interface hostname or IP address.Advanced Access Control Local Management Interface portSpecify the port number of the Local Management Interface. The tool displays a port number.Example value: 443Press Enter to use the displayed port or enter your preferred port. Advanced Access Control administrator user IDPress Enter to use the displayed user ID or enter your preferred user ID. Advanced Access Control administrator password Enter the corresponding administrator password. SSL certificate data valid (y/n)Press y to validate that the displayed SSL certificate values are valid otherwise, press n. Security Access Manager Appliance Local Management Interface hostnameEnter the Security Access Manager Appliance Local Management Interface hostname or IP address. The tool might display a value. Press Enter to use the displayed value or enter your preferred hostname or IP address.Security Access Manager Appliance Local Management Interface portSpecify the port number of the Local Management Interface port. The tool displays a port number.Example value: 443Press Enter to use the port or enter your preferred port. Security Access Manager Appliance administrator user IDPress Enter to use the user ID or enter your preferred user ID. Security Access Manager Appliance administrator passwordEnter the corresponding administrator password. SSL certificate data valid (y/n)Press y to validated that the displayed SSL certificate values are valid otherwise, press n. Instance to configureThe tool displays the available instances that you can configure in a list. Select the instance that you would like to configure.Security Access Manager administrator user IDPress Enter to use the displayed user ID or enter your preferred user ID. Security Access Manager administrator passwordEnter the corresponding administrator password. Security Access Manager domain name [Default]:Enter the corresponding domain name.Advanced Access Control runtime listening interface hostnameEnter the hostname or IP address of the runtime listening interface for the appliance that has Advanced Access Control activated.Example value: 172.16.229.10Advanced Access Control runtime listening interface portSpecify the port number of the runtime listening interface for the appliance that has Advanced Access Control activated.Example value: 443Select the method for authentication between WebSEAL and the Advanced Access Control runtime listening interfaceCertificate authenticationUse a certificate to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.User ID and password authenticationUse credentials to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.The default username is easuser and the default password is passw0rd.Advanced Access Control runtime listening interface user ID:Press Enter to use the displayed user ID or enter your preferred user ID. Advanced Access Control runtime listening interface password:Enter the corresponding Advanced Access Control runtime listening interface password. SSL certificate data valid (y/n):Press y to validated that the displayed SSL certificate values are valid otherwise, press n. Automatically add CA certificate to the key database (y/n)Press y if you want to automatically add the CA certificate to the key database, otherwise press n. Web Reverse Proxy instance restarts if y is selected.The CA certificate already exists in the key database. Replace the CA certificate? (y/n)Press y if you want to automatically replace the CA certificate to the key database, otherwise press n. The following files are available on the Security Access Manager Appliance.Choose one file for the following pages: The 400 Bad Request response page. The default page is oauth_template_rsp_400_bad_request.html.The 401 Unauthorized response page. The default page is oauth_template_rsp_401_unauthorized.html.The 502 Bad Gateway response page. The default page is oauth_template_rsp_502_bad_gateway.html. If you are not running theisamcfg tool on the appliance, you can choose Cancel to upload a local file. If you are running theisamcfg tool on the appliance, you must upload your custom response file. Upload the file to the Security Access Manager appliance first before you run the isamcfg tool so that the file is displayed as an option. See Uploading OAuth response filesUse the local management interface to upload your own custom OAuth response files..The junction mga contains endpoints that require Authorization HTTP header to be forwarded to the backend server. Do you want to enable this feature? [y|n]?Press y to allow endpoints that require Authorization HTTP header to be forwarded to the backend server. Otherwise, press n.isamcfg referenceUse the isamcfg tool to configure WebSEAL and Security Access Manager appliance servers. You configure a point of contact and policy enforcement point.

isamcfg Security Access Manager appliance configuration worksheet

Use the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.

Description of properties

Note: If you are upgrading the Advanced Access Control module, see the installation and configuration instructions.

Select/deselect the capabilities you would like to configure by typing its number.

By default, the tool selects context-based authorization, authentication service, and API protection. You can configure all of them at the same time. If you do not want to configure them all, clear the capability that you do not want to configure by selecting its corresponding number.

Context-based Authorization

Configure this capability if your environment requires the use of behavioral and contextual data analytics to calculate the risk of a transaction.

Authentication service

Configure this capability if your environment requires the use of a step-up authentication type of authentication.

API Protection

Configure this capability if your environment requires the use of an OAuth authentication type to protect your Application Programming Interface (API).

Advanced Access Control Local Management Interface hostname

Enter the Local Management Interface hostname or IP address.

Advanced Access Control Local Management Interface port

Specify the port number of the Local Management Interface. The tool displays a port number.

Example value: 443

Press Enter to use the displayed port or enter your preferred port.

Advanced Access Control administrator user ID

Press Enter to use the displayed user ID or enter your preferred user ID.

Advanced Access Control administrator password

Enter the corresponding administrator password.

SSL certificate data valid (y/n)

Press y to validate that the displayed SSL certificate values are valid otherwise, press n.

Security Access Manager Appliance Local Management Interface hostname

Enter the Security Access Manager Appliance Local Management Interface hostname or IP address. The tool might display a value. Press Enter to use the displayed value or enter your preferred hostname or IP address.

Security Access Manager Appliance Local Management Interface port

Specify the port number of the Local Management Interface port. The tool displays a port number.

Example value: 443

Press Enter to use the port or enter your preferred port.

Security Access Manager Appliance administrator user ID

Press Enter to use the user ID or enter your preferred user ID.

Security Access Manager Appliance administrator password

Enter the corresponding administrator password.

SSL certificate data valid (y/n)

Press y to validated that the displayed SSL certificate values are valid otherwise, press n.

Instance to configure

The tool displays the available instances that you can configure in a list. Select the instance that you would like to configure.

Security Access Manager administrator user ID

Press Enter to use the displayed user ID or enter your preferred user ID.

Security Access Manager administrator password

Enter the corresponding administrator password.

Security Access Manager domain name [Default]:

Enter the corresponding domain name.

Advanced Access Control runtime listening interface hostname

Enter the hostname or IP address of the runtime listening interface for the appliance that has Advanced Access Control activated.

Example value: 172.16.229.10

Advanced Access Control runtime listening interface port

Specify the port number of the runtime listening interface for the appliance that has Advanced Access Control activated.

Example value: 443

Select the method for authentication between WebSEAL and the Advanced Access Control runtime listening interface

Certificate authentication

Use a certificate to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.

User ID and password authentication

Use credentials to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.

The default username is easuser and the default password is passw0rd.

Advanced Access Control runtime listening interface user ID:

Press Enter to use the displayed user ID or enter your preferred user ID.

Advanced Access Control runtime listening interface password:

Enter the corresponding Advanced Access Control runtime listening interface password.

SSL certificate data valid (y/n):

Press y to validated that the displayed SSL certificate values are valid otherwise, press n.

Automatically add CA certificate to the key database (y/n)

Press y if you want to automatically add the CA certificate to the key database, otherwise press n.

Note: Web Reverse Proxy instance restarts if y is selected.

The CA certificate already exists in the key database. Replace the CA certificate? (y/n)

Press y if you want to automatically replace the CA certificate to the key database, otherwise press n.

The following files are available on the Security Access Manager Appliance.

Choose one file for the following pages:

The 400 Bad Request response page. The default page is oauth_template_rsp_400_bad_request.html.

The 401 Unauthorized response page. The default page is oauth_template_rsp_401_unauthorized.html.

The 502 Bad Gateway response page. The default page is oauth_template_rsp_502_bad_gateway.html.

If you are not running theisamcfg tool on the appliance, you can choose Cancel to upload a local file.

If you are running theisamcfg tool on the appliance, you must upload your custom response file. Upload the file to the Security Access Manager appliance first before you run the isamcfg tool so that the file is displayed as an option. See Uploading OAuth response files.

The junction mga contains endpoints that require Authorization HTTP header to be forwarded to the backend server. Do you want to enable this feature? [y|n]?

Press y to allow endpoints that require Authorization HTTP header to be forwarded to the backend server. Otherwise, press n.

Parent topic: isamcfg reference

isamcfg WebSEAL configuration worksheetisamcfg WebSEAL configuration worksheetisamcfg WebSEAL configuration worksheetUse the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.isamcfg tool WebSEAL configurationisamcfg worksheet WebSEALIf you are upgrading the Advanced Access Control module, see the installation and configuration instructions.Description of propertiesSelect/deselect the capabilities you would like to configure by typing its number.By default, the tool selects context-based authorization, authentication service, and API protection. You can configure all of them at the same time. If you do not want to configure them all, clear the capability that you do not want to configure by selecting its corresponding number. Context-based AuthorizationConfigure this capability if your environment requires the use of behavioral and contextual data analytics to calculate the risk of a transaction. Authentication serviceConfigure this capability if your environment requires the use of a step-up authentication type of authentication. API ProtectionConfigure this capability if your environment requires the use of an OAuth authentication type to protect your Application Programming Interface (API).Advanced Access Control Local Management Interface hostnameEnter the Local Management Interface hostname or IP address.Advanced Access Control Local Management Interface portSpecify the port number of the Local Management Interface. The tool displays a port number.Example value: 443Press Enter to use the displayed port or enter your preferred port. Advanced Access Control Appliance administrator user IDPress Enter to use the displayed user ID or enter your preferred user ID. Advanced Access Control Appliance administrator passwordEnter the corresponding administrator password. Security Access Manager Domain nameEnter the Security Access Manager domain name. Press Enter to use the default domain name or enter your preferred domain name. Security Access Manager administrator user IDEnter a valid Security Access Manager administrator user ID. Press Enter to use the user ID or enter your preferred user ID. Security Access Manager administrator passwordEnter the corresponding Security Access Manager administrator password. Advanced Access Control runtime listening interface hostnameEnter the hostname or IP address of the runtime listening interface for the appliance that has Advanced Access Control activated.Example value: 172.16.229.10Advanced Access Control runtime listening interface portSpecify the port number of the runtime listening interface for the appliance that has Advanced Access Control activated.Example value: 443Advanced Access Control runtime listening interface SSL key fileSpecify the path to the keystore that contains the SSL keys that are required to connect to the Advanced Access Control runtime listening interface. Press Enter to use the default key file.Advanced Access Control runtime listening interface SSL stash fileSpecify the path to the stash file that contains the password to the Advanced Access Control runtime listening interface SSL keyfile. Press Enter to use the default stash file.Select the method for authentication between WebSEAL and the Advanced Access Control runtime listening interfaceCertificate authenticationUse a certificate to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.On Windows operating systems, you must use certificate authentication for WebSEAL from IBM Security Access Manager for Web 7.0.0.2.User ID and password authenticationUse credentials to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.The default username is easuser and the default password is passw0rd.Advanced Access Control runtime listening interface SSL key file labelSpecify the key label of the certificate to present to Advanced Access Control at run time.SSL certificate data valid (y/n)Press y to validated that the displayed SSL certificate values are valid otherwise, press n. Automatically add CA certificate to the key database (y/n)Press y if you want to automatically add the CA certificate to the key database, otherwise press n. Web Reverse Proxy instance restarts if y is selected.The CA certificate already exists in the key database. Replace the CA certificate? (y/n)Press y if you want to automatically replace the CA certificate to the key database, otherwise press n. Runtime security service external authorization service libraryBy default, the tool displays the available library. Press Enter to use the available library or enter your preferred library.The 400 Bad Request response page: Choose one for the 400 Bad Request response page. The default page is oauth_template_rsp_400_bad_request.html.The following files are available on the Secure Access Manager Appliance.Choose one file for the following pages: The 400 Bad Request response page. The default page is oauth_template_rsp_400_bad_request.html.The 401 Unauthorized response page. The default page is oauth_template_rsp_401_unauthorized.html.The 502 Bad Gateway response page. The default page is oauth_template_rsp_502_bad_gateway.html.isamcfg referenceUse the isamcfg tool to configure WebSEAL and Security Access Manager appliance servers. You configure a point of contact and policy enforcement point.

isamcfg WebSEAL configuration worksheet

Use the worksheet for the isamcfg command-line tool to collect the information you need about the configuration properties before you run the tool.

Description of properties

Note: If you are upgrading the Advanced Access Control module, see the installation and configuration instructions.

Select/deselect the capabilities you would like to configure by typing its number.

By default, the tool selects context-based authorization, authentication service, and API protection. You can configure all of them at the same time. If you do not want to configure them all, clear the capability that you do not want to configure by selecting its corresponding number.

Context-based Authorization

Configure this capability if your environment requires the use of behavioral and contextual data analytics to calculate the risk of a transaction.

Authentication service

Configure this capability if your environment requires the use of a step-up authentication type of authentication.

API Protection

Configure this capability if your environment requires the use of an OAuth authentication type to protect your Application Programming Interface (API).

Advanced Access Control Local Management Interface hostname

Enter the Local Management Interface hostname or IP address.

Advanced Access Control Local Management Interface port

Specify the port number of the Local Management Interface. The tool displays a port number.

Example value: 443

Press Enter to use the displayed port or enter your preferred port.

Advanced Access Control Appliance administrator user ID

Press Enter to use the displayed user ID or enter your preferred user ID.

Advanced Access Control Appliance administrator password

Enter the corresponding administrator password.

Security Access Manager Domain name

Enter the Security Access Manager domain name. Press Enter to use the default domain name or enter your preferred domain name.

Security Access Manager administrator user ID

Enter a valid Security Access Manager administrator user ID. Press Enter to use the user ID or enter your preferred user ID.

Security Access Manager administrator password

Enter the corresponding Security Access Manager administrator password.

Advanced Access Control runtime listening interface hostname

Enter the hostname or IP address of the runtime listening interface for the appliance that has Advanced Access Control activated.

Example value: 172.16.229.10

Advanced Access Control runtime listening interface port

Specify the port number of the runtime listening interface for the appliance that has Advanced Access Control activated.

Example value: 443

Advanced Access Control runtime listening interface SSL key file

Specify the path to the keystore that contains the SSL keys that are required to connect to the Advanced Access Control runtime listening interface. Press Enter to use the default key file.

Advanced Access Control runtime listening interface SSL stash file

Specify the path to the stash file that contains the password to the Advanced Access Control runtime listening interface SSL keyfile. Press Enter to use the default stash file.

Select the method for authentication between WebSEAL and the Advanced Access Control runtime listening interface

Certificate authentication

Use a certificate to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.

Note: On Windows operating systems, you must use certificate authentication for WebSEAL from IBM Security Access Manager for Web 7.0.0.2.

User ID and password authentication

Use credentials to authenticate between WebSEAL and the Advanced Access Control runtime listening interface.

The default username is easuser and the default password is passw0rd.

Advanced Access Control runtime listening interface SSL key file label

Specify the key label of the certificate to present to Advanced Access Control at run time.

SSL certificate data valid (y/n)

Press y to validated that the displayed SSL certificate values are valid otherwise, press n.

Automatically add CA certificate to the key database (y/n)

Press y if you want to automatically add the CA certificate to the key database, otherwise press n.

Note: Web Reverse Proxy instance restarts if y is selected.

The CA certificate already exists in the key database. Replace the CA certificate? (y/n)

Press y if you want to automatically replace the CA certificate to the key database, otherwise press n.

Runtime security service external authorization service library

By default, the tool displays the available library. Press Enter to use the available library or enter your preferred library.

The 400 Bad Request response page:

Choose one for the 400 Bad Request response page. The default page is oauth_template_rsp_400_bad_request.html.

The following files are available on the Secure Access Manager Appliance.

Choose one file for the following pages:

The 400 Bad Request response page. The default page is oauth_template_rsp_400_bad_request.html.

The 401 Unauthorized response page. The default page is oauth_template_rsp_401_unauthorized.html.

The 502 Bad Gateway response page. The default page is oauth_template_rsp_502_bad_gateway.html.

Parent topic: isamcfg reference

Using a response fileUsing a response fileUsing a response fileCreate and use a response file with the isamcfg tool to configure WebSEAL and IBM Security Access Manager for Web 7.0.A response file records the actions to be taken by the isamcfg tool. Use the -record command to create a response file without changing the configuration. For example:/usr/lib/jvm/jre-1.7.0-ibm.x86_64/bin/java -jar /opt/IBM/FIM/tools/isamcfg/isamcfg.jar -action config -cfgurl https://1.1.1.1/ -record You can then use the response file to run the isamcfg tool non-interactively. Use the -rspfile command to run the isamcfg tool with a response file. For example:/usr/lib/jvm/jre-1.7.0-ibm.x86_64/bin/java -jar /opt/IBM/FIM/tools/isamcfg/isamcfg.jar -action config -cfgurl https://1.1.1.1/ -rspfile /tmp/isamcfg-access-control.propertiesThe contents of a response varies depending on your configuration, for example: #Fri Sep 06 12:45:28 EST 2013 webseal.addcacert=y tam.admin=sec_master wga.pass= pop.replace=pop.reuse mga.admin.ssl.sha1fingerprint=CD\:1C\:F0\:D9\:A6\:3A\:7A\:11\ :16\:CC\:18\:CB\:56\:02\:08\:E2\:53\:99\:83\:3B mga.runtime.auth.mode=mga.runtime.auth.ba mga.runtime.ssl.md5fingerprint=E4\:65\:16\:A9\:D8\:B2\:97\ :3C\:F6\:13\:19\:77\:25\:8B\:B0\:0A mga.admin.ssl.subjectdn=CN\=amapp800 wga.ssl.md5fingerprint=B2\:9F\:87\:8A\:D1\:49\:D9\:A1\:BA\ :03\:4B\:41\:E9\:DF\:44\:C7 rtss.password= wga.ssl.sha1fingerprint=CD\:1C\:F0\:D9\:A6\:3A\:7A\:11\:16\ :CC\:18\:CB\:56\:02\:08\:E2\:53\:99\:83\:3B wga.instance=mobile mga.admin.user=admin wga.port=443 isam.mode=context_based_authorization, authentication_service, mga.runtime.port=443 mga.admin.pass= jct.replace=reuse wga.host=1.1.1.1 mga.runtime.host=1.1.1.1 mga.admin.ssl.md5fingerprint=B2\:9F\:87\:8A\:D1\:49\:D9\ :A1\:BA\:03\:4B\:41\:E9\:DF\:44\:C7 wga.ssl.subjectdn=CN\=amapp800 mga.runtime.ssl.subjectdn=CN\=isam, O\=ibm, C\=us mga.admin.ssl.issuerdn=CN\=amapp800 rtss.user=admin mga.runtime.ssl.sha1fingerprint=F9\:38\:5A\:53\:0A\:DA\:1A\ :FF\:67\:46\:C9\:58\:3F\:F1\:2B\:00\:B0\:6C\:83\:32 mga.admin.port=443 tam.password= wga.ssl.issuerdn=CN\=amapp800 mga.runtime.ssl.issuerdn=CN\=isam, O\=ibm, C\=us wga.user=admin mga.admin.host=1.1.1.1Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool.

Using a response file

Create and use a response file with the isamcfg tool to configure WebSEAL and IBM Security Access Manager for Web 7.0.

A response file records the actions to be taken by the isamcfg tool.

Use the -record command to create a response file without changing the configuration. For example:

/usr/lib/jvm/jre-1.7.0-ibm.x86_64/bin/java -jar
/opt/IBM/FIM/tools/isamcfg/isamcfg.jar -action config
-cfgurl https://1.1.1.1/ -record

You can then use the response file to run the isamcfg tool non-interactively. Use the -rspfile command to run the isamcfg tool with a response file. For example:

/usr/lib/jvm/jre-1.7.0-ibm.x86_64/bin/java -jar
/opt/IBM/FIM/tools/isamcfg/isamcfg.jar -action config
-cfgurl https://1.1.1.1/ -rspfile /tmp/isamcfg-access-control.properties

The contents of a response varies depending on your configuration, for example:

#Fri Sep 06 12:45:28 EST 2013
webseal.addcacert=y
tam.admin=sec_master
wga.pass=
pop.replace=pop.reuse
mga.admin.ssl.sha1fingerprint=CD\:1C\:F0\:D9\:A6\:3A\:7A\:11\
:16\:CC\:18\:CB\:56\:02\:08\:E2\:53\:99\:83\:3B
mga.runtime.auth.mode=mga.runtime.auth.ba
mga.runtime.ssl.md5fingerprint=E4\:65\:16\:A9\:D8\:B2\:97\
:3C\:F6\:13\:19\:77\:25\:8B\:B0\:0A
mga.admin.ssl.subjectdn=CN\=amapp800
wga.ssl.md5fingerprint=B2\:9F\:87\:8A\:D1\:49\:D9\:A1\:BA\
:03\:4B\:41\:E9\:DF\:44\:C7
rtss.password=
wga.ssl.sha1fingerprint=CD\:1C\:F0\:D9\:A6\:3A\:7A\:11\:16\
:CC\:18\:CB\:56\:02\:08\:E2\:53\:99\:83\:3B
wga.instance=mobile
mga.admin.user=admin
wga.port=443
isam.mode=context_based_authorization,
authentication_service,
mga.runtime.port=443
mga.admin.pass=
jct.replace=reuse
wga.host=1.1.1.1
mga.runtime.host=1.1.1.1
mga.admin.ssl.md5fingerprint=B2\:9F\:87\:8A\:D1\:49\:D9\
:A1\:BA\:03\:4B\:41\:E9\:DF\:44\:C7
wga.ssl.subjectdn=CN\=amapp800
mga.runtime.ssl.subjectdn=CN\=isam, O\=ibm, C\=us
mga.admin.ssl.issuerdn=CN\=amapp800
rtss.user=admin
mga.runtime.ssl.sha1fingerprint=F9\:38\:5A\:53\:0A\:DA\:1A\
:FF\:67\:46\:C9\:58\:3F\:F1\:2B\:00\:B0\:6C\:83\:32
mga.admin.port=443
tam.password=
wga.ssl.issuerdn=CN\=amapp800
mga.runtime.ssl.issuerdn=CN\=isam, O\=ibm, C\=us
wga.user=admin
mga.admin.host=1.1.1.1

Parent topic: Using the isamcfg tool

Adding runtime listening interfacesAdding runtime listening interfacesAdding runtime listening interfacesAdd your application interfaces to the list of runtime listening interfaces. This procedure enables communication between an appliance with Advanced Access Control and another Security Access Manager appliance.listening interfacesruntime listening interfacesWhen you run the isamcfg tool, ensure that you specify the runtime listening interface host name and port when prompted.Define your application interfaces. Use the following procedure only if your deployment has Advanced Access Control running on an appliance that is separate from another Security Access Manager appliance. Log in to the local management interface.Click Secure Access Control.Under Global Settings, click Runtime Parameters.On the Runtime Tuning Parameters page, click Add to add a runtime listening interface on port 443:For Interface, select your appliance interface.For Port, select or type 443.Ensure SSL is checked.Click OK.Click Add to add a runtime listening interface on port 80:For Interface, select your appliance interface.For Port, select or type 80.Clear the SSL checkbox.Click OK.Deploy these changes.Some configuration and administration changes require an extra deployment step. Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Adding runtime listening interfaces

Add your application interfaces to the list of runtime listening interfaces. This procedure enables communication between an appliance with Advanced Access Control and another Security Access Manager appliance.

Before you begin

When you run the isamcfg tool, ensure that you specify the runtime listening interface host name and port when prompted.

Define your application interfaces.

About this task

Use the following procedure only if your deployment has Advanced Access Control running on an appliance that is separate from another Security Access Manager appliance.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Runtime Parameters.

On the Runtime Tuning Parameters page, click Add to add a runtime listening interface on port 443:

For Interface, select your appliance interface.

For Port, select or type 443.

Ensure SSL is checked.

Click OK.

Click Add to add a runtime listening interface on port 80:

For Interface, select your appliance interface.

For Port, select or type 80.

Clear the SSL checkbox.

Click OK.

Deploy these changes.

Parent topic: Advanced Access Control configuration

Support for compliance with NIST SP800-131aNIST complianceNIST SP800-131a complianceAdvanced Access Control supports the requirements that are defined by the National Institute of Standards and Technology (NIST) Special Publications 800-131a. NIST SP800-131a compliancecomplianceNIST SP800-131aSP 800-131a strengthens security by defining stronger cryptographic keys and more robust algorithms. The standard defines a period to allow customers time to make the transition to the new requirements. The transition period closes at the end of 2013. See the NIST publication Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths for the new standards that are defined by Special Publication 800-131, and details about allowed protocols, cipher suites, and key strength. You can run the appliance that provides Advanced Access Control in either of the two modes that are supported by NIST SP800-131a:Transition modeStrict mode When configured in transition mode, server components support the transition mode Transport Layer Security (TLS) protocols, which include TLS 1.0 and TLS 1.1. Client components, such as the HTTPS client that performs one-time password (OTP) delivery and the syslog auditing client, support TLS 1.2 only.When configured in strict mode, both the server components and the client components of Advanced Access Control support TLS 1.2 only. To deploy in transition mode, you need to select only the mode during initial configuration of the appliance. To run in strict mode, you must also set an extra configuration option.If your deployment uses client certificate authentication, and you want to use strict mode, you must complete more configuration steps for the point of contact server. The point of contact server can be either IBM Security Access Manager WebSEAL or IBM Security Web Gateway appliance 7.0.Transition modeWhen you install the appliance, select the option to enable FIPS 140-2 mode. This selection turns on compliance for NIST SP800-131a. When enabled, NIST SP800-131a compliance is run in transition mode. You do not have to complete any further configuration steps in order to run in transition mode.Enable FIPS 140-2 mode only if you must comply with the NIST SP800-131a requirements. There is no advantage to enabling FIPS 140-2 mode if your installation does not require this compliance.The setting of the FIPS 140-2 Mode option is permanent and cannot be turned off after it is enabled. To disable the option, you must reinstall the appliance. If you enable FIPS 140-2 mode, the appliance is automatically restarted before it continues with the rest of the setup.FIPS Limitation: For Advanced Access Control, the FIPS 140-2 mode option in the appliance setup wizard does not turn on compliance for FIPS 140-2. It turns on compliance for NIST SP800-131a only. Strict modeOverview of configuration tasks: Enable FIPS 140-2 mode during appliance configuration. Set a tuning parameter to enable strict mode. (Optional) If your deployment uses client certificate authentication, configure TLS v1.2.Instructions:Install the appliance and choose to enable FIPS 140-2 mode. This selection turns on compliance for NIST SP800-131a.Use the appliance local management interface (LMI) to modify the advanced tuning parameter nist.sp800-131a.strict. This parameter is set by default to false. Complete the following steps:Verify that your browser supports TLS 1.2. Strict mode requires the use of TLS 1.2. Some browsers support TLS 1.2 but have the support disabled by default. If you set the value of the nist.sp800-131a.strict parameter to true, and your browser is not configured to support TLS 1.2, you lose access to the appliance LMI. On the LMI, select Manage System Settings > System Settings > Advanced Tuning Parameters.Select nist.sp800-131a.strict. Select Edit. Change the value to true.Determine whether your deployment uses basic authentication or client certificate authentication, for communication between Advanced Access Control and the point of contact server. If you use basic authentication, the configuration is complete.If you use client certificate authentication, continue with the next section. Client certificate configuration for strict modeIf you use client certificate authentication on the point of contact server, you must configure it to be in compliance with NIST SP800-131a strict mode. To comply with strict mode, configure the point of contact server to use TLS v.1.2 for client certificate authentication.You must create a self-signed certificate, and configure the point of contact server to use TLS v1.2 with the runtime security services external authorization service (EAS). Complete each of the following tasks:Create a self-signed certificate. Review the Before you begin section of Configuring runtime security services for client certificate authenticationConfigure runtime security services for client certificate authentication used for authentication between WebSEAL and Advanced Access Control.. Select one of the following actions, as fits your deployment: If your deployment uses Web Reverse Proxy, follow the instructions in Configuring runtime security services for client certificate authenticationConfigure runtime security services for client certificate authentication used for authentication between WebSEAL and Advanced Access Control.. In Step 1 “Create a client certificate for user easusercert", specify: Signature Algorithm: SHA2withRSA If your deployment uses WebSEAL:Manually create a self-signed certificate. To specify a NIST-compliant algorithm, use an external utility such as gsk7ikm. Open the pd.srv certificate database, and create a self-signed certificate with these credentials: Certificate Label: easusercert Certificate Distinguished Name: cn=easuser Key Size: 2048 Expiration Time (in days): 365 Signature Algorithm: SHA2withRSA The user cn=easuser is the built-in user, but any user with sufficient permissions (as created by the Advanced Access Control administrator) can be used instead. It is not mandatory that WebSEAL has FIPS 140-2 mode configured in order to communicate with the Advanced Access Control server. However, to comply with NIST SP800-131a strict mode, client certificate authentication between WebSEAL and the server must be over TLS v1.2.See the WebSEAL information in the IBM Knowledge Center for complete information on configuring client certificate authentication. Configure the point of contact server to use TLS v1.2 with the Runtime Security Services External Authorization Service (EAS) The point of contact server uses the EAS to process authorization requests. The default EAS setting for communication specifies Secure Sockets Layer (SSL) v2, which is not supported by Advanced Access Control when it operates in NIST SP800-131a strict mode. If you do not adjust the configuration setting for the EAS, the authorization request (and the regular ping call) does not succeed.Select the action that fits your deployment: If you deploy your point of contact server on the same computer as the appliance:In the Advanced Access Control local management interface, select Reverse Proxy Settings > your_instance_name > Manage > Configuration > Edit to open the configuration file. Add the following parameter to the existing stanza: [rtss-cluster:cluster1] gsk-attr-name = enum:438:1 Click Save. Deploy the changes. Restart the instance. If you deploy your point of contact server on a different computer from the appliance:Open the WebSEAL instance configuration file for editing. For example: /opt/pdweb/etc/webseald-appliance-default.conf. Add the following parameter to the existing stanza: [rtss-cluster:cluster1] gsk-attr-name = enum:438:1 . Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Support for compliance with NIST SP800-131a

Advanced Access Control supports the requirements that are defined by the National Institute of Standards and Technology (NIST) Special Publications 800-131a.

SP 800-131a strengthens security by defining stronger cryptographic keys and more robust algorithms. The standard defines a period to allow customers time to make the transition to the new requirements. The transition period closes at the end of 2013. See the NIST publication Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths for the new standards that are defined by Special Publication 800-131, and details about allowed protocols, cipher suites, and key strength.

You can run the appliance that provides Advanced Access Control in either of the two modes that are supported by NIST SP800-131a:

Transition mode

Strict mode

When configured in transition mode, server components support the transition mode Transport Layer Security (TLS) protocols, which include TLS 1.0 and TLS 1.1. Client components, such as the HTTPS client that performs one-time password (OTP) delivery and the syslog auditing client, support TLS 1.2 only.

When configured in strict mode, both the server components and the client components of Advanced Access Control support TLS 1.2 only.

To deploy in transition mode, you need to select only the mode during initial configuration of the appliance. To run in strict mode, you must also set an extra configuration option.

If your deployment uses client certificate authentication, and you want to use strict mode, you must complete more configuration steps for the point of contact server. The point of contact server can be either IBM Security Access Manager WebSEAL or IBM Security Web Gateway appliance 7.0.

Transition mode

When you install the appliance, select the option to enable FIPS 140-2 mode. This selection turns on compliance for NIST SP800-131a.

When enabled, NIST SP800-131a compliance is run in transition mode. You do not have to complete any further configuration steps in order to run in transition mode.

Note:

Enable FIPS 140-2 mode only if you must comply with the NIST SP800-131a requirements. There is no advantage to enabling FIPS 140-2 mode if your installation does not require this compliance.

Important: The setting of the FIPS 140-2 Mode option is permanent and cannot be turned off after it is enabled. To disable the option, you must reinstall the appliance.

If you enable FIPS 140-2 mode, the appliance is automatically restarted before it continues with the rest of the setup.

FIPS Limitation: For Advanced Access Control, the FIPS 140-2 mode option in the appliance setup wizard does not turn on compliance for FIPS 140-2. It turns on compliance for NIST SP800-131a only.

Strict mode

Overview of configuration tasks:

Enable FIPS 140-2 mode during appliance configuration.

Set a tuning parameter to enable strict mode.

(Optional) If your deployment uses client certificate authentication, configure TLS v1.2.

Instructions:

Install the appliance and choose to enable FIPS 140-2 mode. This selection turns on compliance for NIST SP800-131a.

Use the appliance local management interface (LMI) to modify the advanced tuning parameter nist.sp800-131a.strict. This parameter is set by default to false. Complete the following steps:

Verify that your browser supports TLS 1.2.

CAUTION:

Strict mode requires the use of TLS 1.2. Some browsers support TLS 1.2 but have the support disabled by default. If you set the value of the nist.sp800-131a.strict parameter to true, and your browser is not configured to support TLS 1.2, you lose access to the appliance LMI.

On the LMI, select Manage System Settings > System Settings > Advanced Tuning Parameters.

Select nist.sp800-131a.strict. Select Edit. Change the value to true.

Determine whether your deployment uses basic authentication or client certificate authentication, for communication between Advanced Access Control and the point of contact server.

If you use basic authentication, the configuration is complete.

If you use client certificate authentication, continue with the next section.

Client certificate configuration for strict mode

If you use client certificate authentication on the point of contact server, you must configure it to be in compliance with NIST SP800-131a strict mode.

To comply with strict mode, configure the point of contact server to use TLS v.1.2 for client certificate authentication.

You must create a self-signed certificate, and configure the point of contact server to use TLS v1.2 with the runtime security services external authorization service (EAS). Complete each of the following tasks:

Create a self-signed certificate.

Review the "Before you begin" section of Configuring runtime security services for client certificate authentication. Select one of the following actions, as fits your deployment:

If your deployment uses Web Reverse Proxy, follow the instructions in Configuring runtime security services for client certificate authentication. In Step 1 “Create a client certificate for user easusercert", specify:

 Signature Algorithm: SHA2withRSA

If your deployment uses WebSEAL:

Manually create a self-signed certificate. To specify a NIST-compliant algorithm, use an external utility such as gsk7ikm. Open the pd.srv certificate database, and create a self-signed certificate with these credentials:

 Certificate Label: easusercert
 Certificate Distinguished Name: cn=easuser
 Key Size: 2048
 Expiration Time (in days): 365
 Signature Algorithm: SHA2withRSA

Note:

The user cn=easuser is the built-in user, but any user with sufficient permissions (as created by the Advanced Access Control administrator) can be used instead.

It is not mandatory that WebSEAL has FIPS 140-2 mode configured in order to communicate with the Advanced Access Control server. However, to comply with NIST SP800-131a strict mode, client certificate authentication between WebSEAL and the server must be over TLS v1.2.

See the WebSEAL information in the IBM Knowledge Center for complete information on configuring client certificate authentication.

Configure the point of contact server to use TLS v1.2 with the Runtime Security Services External Authorization Service (EAS)

The point of contact server uses the EAS to process authorization requests. The default EAS setting for communication specifies Secure Sockets Layer (SSL) v2, which is not supported by Advanced Access Control when it operates in NIST SP800-131a strict mode. If you do not adjust the configuration setting for the EAS, the authorization request (and the regular ping call) does not succeed.

Select the action that fits your deployment:

If you deploy your point of contact server on the same computer as the appliance:

In the Advanced Access Control local management interface, select Reverse Proxy Settings > your_instance_name > Manage > Configuration > Edit to open the configuration file. Add the following parameter to the existing stanza:

[rtss-cluster:cluster1]
gsk-attr-name = enum:438:1

Click Save. Deploy the changes. Restart the instance.

If you deploy your point of contact server on a different computer from the appliance:

Open the WebSEAL instance configuration file for editing. For example: /opt/pdweb/etc/webseald-appliance-default.conf.

Add the following parameter to the existing stanza:

[rtss-cluster:cluster1]
gsk-attr-name = enum:438:1

.

Parent topic: Advanced Access Control configuration

AuthenticationAuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.The users who want to access your protected resources can be challenged to provide credentials to authenticate with the various authentication technologies that are supported by Security Access Manager. The component responsible for this capability is called the Authentication Service. The Authentication Service consists of a framework you can use to enforce the execution of various supported authentication mechanisms to authenticate users. Authentication mechanisms are modules that authenticate the user with a specific challenge or authentication technology, such as user name and password and one-time password. The order on which the authentication mechanisms are run is controlled by an authentication policy. An authentication policy is an XML document that you create with the authentication policy editor. The authentication policy dictates the order of authentication mechanisms to execute.During an authentication event, the Authentication Service manages the execution of the authentication policy that is required for the event. Each authentication mechanism is included on the authentication policy workflow. This workflow is started by the Authentication Service authentication policy. After the user successfully authenticates to all of the authentication mechanisms that are required by the authentication policy, the Authentication Service generates a user credential. This user credential creates an authenticated session for the user at the point of contact. The administrator can determine what information is included in the credential by configuring the authentication policy. The authentication policy editor provides a credential editor that an administrator can use to specify the attributes to be included in the resulting credential.The generated credential contains: authenticationTypes and authenticationMechanismTypes attributes to indicate the authentication policies.Authentication mechanisms that are completed during the authenticated session. The administrator can use authenticationTypes and authenticationMechanismTypes attributes to author an access control policy to require: The user to authenticate through an authentication policy or mechanism once per policy.The user to authenticate every time they access the protected resource.The Authentication Service supports two flows of execution: Enforcement of an authentication event as a result of an access control evaluation. Request the user to authenticate as a result of either: A point of contact access control list (ACL).A protected object policy (POP) evaluation. Authentication mechanisms Security Access Manager provides the following authentication mechanisms: One-time password authentication mechanisms A one-time password is a password that is generated for an authentication event and is valid for one use. The one-time password authentication capability in Security Access Manager provides the following features: One-time password generation and validation with support for various implementations as provided.One-time password delivery with email and short message service (SMS) implementation.Time-based, counter-based, and RSA one-time password generation and validation that requires no delivery mechanism. The one-time password authentication mechanisms are described in the following table.MechanismDescriptionOne-time password authenticationUsers provide a one-use password that is generated for an authentication event and is typically communicated between the client and the server through a secure channel. The OTP mechanism groups all the supported one-time passwords methods in a single flow and ask the user to select which one-time password method to use to login. The user can select from the supported one-time password authentication methods: HOTPTOTPRSA OTPMAC OTP with SMS deliveryMAC OTP with email deliveryMAC One-time password authenticationUsers provide a one-use password that is generated for an authentication event and is typically communicated between the client and the server through a secure channel. The MAC mechanism generates one-time passwords by randomly drawing one character at a time from the configured character set until the configured number of characters are drawn. The MAC mechanism also stores the generated one-time passwords in the configured one-time password store plug-in. Each one-time password is salted and hashed before it is stored in the configured one-time password store plug-in. The user can select from the supported MAC one-time password authentication methods: MAC OTP with email delivery. The email delivery sends the email address of the user and the one-time password in a message, whose MIME type is text/plain, to the configured SMTP Server. The SMTP Server then sends the one-time password to the user by email. The product does not provide an SMTP Server. You must configure your own SMTP Server.MAC OTP with SMS delivery. The SMS Delivery first sends the phone number of the user and the one-time password in an HTTP POST request, whose content type is application/x-www-form-urlencoded, to the configured SMS Gateway. The SMS Gateway then sends the one-time password to the user through SMS. The product does not provide an SMS Gateway. You must configure your own SMS Gateway.This mechanism also supports the one-time password mapping rules.HOTP One-time password authenticationUsers provide a one-use password that is generated for an authentication event. The one-time password is generated by the HOTP method.TOTP One-time password authenticationUsers provide a one-use password that is generated for an authentication event. The TOTP mechanism generates one-time passwords by using a specified algorithm with a time-based one-time password application. Passwords are not communicated or stored, but are verified as a match between server and client as they are regenerated at regular intervals.RSA One-time password authenticationUsers provide a one-use password that is generated for an authentication event. The RSA mechanism works with an RSA SecurID Authentication Manager and passcode generator. You must own the RSA Authentication Manager product to use RSA as a mechanism. The RSA Authentication Manager and passcode generator generates a passcode every 30 - 60 seconds. The user name and passcode are supplied by the user and passed to the RSA Authentication Manager. The RSA Authentication Manager makes a decision and returns it to Security Access Manager, which relays the decision back to the user. Username and Password mechanismUsers provide a user name and password.HTTP Redirect mechanismUse this mechanism to integrate a custom authentication mechanism into the workflow of an authentication policy. Users provide credentials that are required by the custom authentication mechanism.Consent to device registration mechanismUsers provide consent to allow their device to be registered.Mobile User Approved mechanismUsers provide authentication through the use of registered public-key authentication methods. Through the policy editor, you can group one or more mechanisms into the workflow of an authentication policy. The policy defines which authentication mechanisms your users are required to use to successfully authenticate. Authentication policies By grouping the provided authentication mechanisms into the workflow of an authentication policy, you can achieve several types of authentication: Simple authenticationUsers provide basic identifying information such as a user name and password.Step-up authenticationUsers provide a specific type of credential usually to access sensitive resources. The users might be challenged to authenticate and provide an extra set of credentials to prove that they are allowed to access sensitive resources.Multi-factor authenticationUsers provide more than one type of credential to access a protected resource. Each authentication policy has a unique identifier that you can use with an access policy or to start the authentication service directly without any prior access policy invocation. Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Authentication Service configuration overviewMost of the configuration that is associated with the authentication service and the supported authentication mechanisms is pre-configured on the appliance. In most scenarios, this configuration is adequate. However, some scenarios require customization to meet your requirements.Authentication configuration scenariosUse the configuration scenarios to create a custom configuration for your environment.Configuring an HOTP one-time password mechanismThe HOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring a TOTP one-time password mechanismThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring a MAC one-time password mechanismA one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail. Configuring an RSA one-time password mechanismA one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.Configuring one-time password delivery methodsPasswords can be delivered to the user through Short Message Service (SMS) or email. Configuring username and password authenticationThe user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository. Configuring an HTTP redirect authentication mechanism The HTTP redirect authentication mechanism integrates an external application that you provide to use for authenticating users.Configuring consent to device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.Configuring an End-User License Agreement authentication mechanism The End-User License Agreement authentication mechanism prompts the user to accept an End-User License Agreement (EULA) during an authentication flow.Configuring an Email Message mechanismThe Email Message mechanism provides arbitrary information about a user via either email, webpage, or JSON for consumption by users or applications.Configuring the reCAPTCHA Verification authentication mechanismThe reCAPTCHA Verification authentication mechanism provides anti-robot protection.Configuring an Info Map authentication mechanismUse this mechanism in your policy to return a template form and perform validation on the responding POST data. This mechanism is intended to work in conjunction with the Email Message mechanism. Configuring a Knowledge Questions authentication mechanismThe Knowledge Questions authentication mechanism is an extra step-up authentication measure that uses knowledge questions and answers to authenticate the user.Configuring a Mobile User Approved authentication mechanismThe Mobile User Approved authentication mechanism prompts the user to sign a random challenge string with a private key that is associated with one of the key values that are provided during the authentication flow.Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.One-time password and authentication template filesThe one-time password and authentication methods rely on HTML pages to interact with users, such as displaying errors or prompting users to provide a password or pin or to indicate the method by which they want to receive the password. You can customize these pages using the one-time password and authentication template files.Push notification registrationSecurity Access Manager supports push notifications on both iOS and Android platforms.

Authentication

Security Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

The users who want to access your protected resources can be challenged to provide credentials to authenticate with the various authentication technologies that are supported by Security Access Manager. The component responsible for this capability is called the Authentication Service. The Authentication Service consists of a framework you can use to enforce the execution of various supported authentication mechanisms to authenticate users.

Authentication mechanisms are modules that authenticate the user with a specific challenge or authentication technology, such as user name and password and one-time password. The order on which the authentication mechanisms are run is controlled by an authentication policy. An authentication policy is an XML document that you create with the authentication policy editor. The authentication policy dictates the order of authentication mechanisms to execute.

During an authentication event, the Authentication Service manages the execution of the authentication policy that is required for the event. Each authentication mechanism is included on the authentication policy workflow. This workflow is started by the Authentication Service authentication policy. After the user successfully authenticates to all of the authentication mechanisms that are required by the authentication policy, the Authentication Service generates a user credential. This user credential creates an authenticated session for the user at the point of contact.

The administrator can determine what information is included in the credential by configuring the authentication policy. The authentication policy editor provides a credential editor that an administrator can use to specify the attributes to be included in the resulting credential.

The generated credential contains:

authenticationTypes and authenticationMechanismTypes attributes to indicate the authentication policies.

Authentication mechanisms that are completed during the authenticated session.

The administrator can use authenticationTypes and authenticationMechanismTypes attributes to author an access control policy to require:

The user to authenticate through an authentication policy or mechanism once per policy.

The user to authenticate every time they access the protected resource.

The Authentication Service supports two flows of execution:

Enforcement of an authentication event as a result of an access control evaluation.

Request the user to authenticate as a result of either:

A point of contact access control list (ACL).

A protected object policy (POP) evaluation.

Authentication mechanisms

Security Access Manager provides the following authentication mechanisms:

One-time password authentication mechanisms

A one-time password is a password that is generated for an authentication event and is valid for one use. The one-time password authentication capability in Security Access Manager provides the following features:

One-time password generation and validation with support for various implementations as provided.

One-time password delivery with email and short message service (SMS) implementation.

Time-based, counter-based, and RSA one-time password generation and validation that requires no delivery mechanism.

The one-time password authentication mechanisms are described in the following table.

Mechanism
Description

One-time password authentication
Users provide a one-use password that is generated for an authentication event and is typically communicated between the client and the server through a secure channel. The OTP mechanism groups all the supported one-time passwords methods in a single flow and ask the user to select which one-time password method to use to login. The user can select from the supported one-time password authentication methods:

HOTP

TOTP

RSA OTP

MAC OTP with SMS delivery

MAC OTP with email delivery

MAC One-time password authentication
Users provide a one-use password that is generated for an authentication event and is typically communicated between the client and the server through a secure channel. The MAC mechanism generates one-time passwords by randomly drawing one character at a time from the configured character set until the configured number of characters are drawn. The MAC mechanism also stores the generated one-time passwords in the configured one-time password store plug-in. Each one-time password is salted and hashed before it is stored in the configured one-time password store plug-in. The user can select from the supported MAC one-time password authentication methods:

MAC OTP with email delivery.

The email delivery sends the email address of the user and the one-time password in a message, whose MIME type is text/plain, to the configured SMTP Server. The SMTP Server then sends the one-time password to the user by email. The product does not provide an SMTP Server. You must configure your own SMTP Server.

MAC OTP with SMS delivery.

The SMS Delivery first sends the phone number of the user and the one-time password in an HTTP POST request, whose content type is application/x-www-form-urlencoded, to the configured SMS Gateway. The SMS Gateway then sends the one-time password to the user through SMS. The product does not provide an SMS Gateway. You must configure your own SMS Gateway.

This mechanism also supports the one-time password mapping rules.

HOTP One-time password authentication
Users provide a one-use password that is generated for an authentication event. The one-time password is generated by the HOTP method.

TOTP One-time password authentication
Users provide a one-use password that is generated for an authentication event. The TOTP mechanism generates one-time passwords by using a specified algorithm with a time-based one-time password application. Passwords are not communicated or stored, but are verified as a match between server and client as they are regenerated at regular intervals.

RSA One-time password authentication
Users provide a one-use password that is generated for an authentication event. The RSA mechanism works with an RSA SecurID Authentication Manager and passcode generator. You must own the RSA Authentication Manager product to use RSA as a mechanism. The RSA Authentication Manager and passcode generator generates a passcode every 30 - 60 seconds. The user name and passcode are supplied by the user and passed to the RSA Authentication Manager. The RSA Authentication Manager makes a decision and returns it to Security Access Manager, which relays the decision back to the user.

Username and Password mechanism

Users provide a user name and password.

HTTP Redirect mechanism

Use this mechanism to integrate a custom authentication mechanism into the workflow of an authentication policy. Users provide credentials that are required by the custom authentication mechanism.

Consent to device registration mechanism

Users provide consent to allow their device to be registered.

Mobile User Approved mechanism

Users provide authentication through the use of registered public-key authentication methods.

Through the policy editor, you can group one or more mechanisms into the workflow of an authentication policy. The policy defines which authentication mechanisms your users are required to use to successfully authenticate.

Authentication policies

By grouping the provided authentication mechanisms into the workflow of an authentication policy, you can achieve several types of authentication:

Simple authentication

Users provide basic identifying information such as a user name and password.

Step-up authentication

Users provide a specific type of credential usually to access sensitive resources. The users might be challenged to authenticate and provide an extra set of credentials to prove that they are allowed to access sensitive resources.

Multi-factor authentication

Users provide more than one type of credential to access a protected resource.

Each authentication policy has a unique identifier that you can use with an access policy or to start the authentication service directly without any prior access policy invocation.

Authentication Service configuration overview
Most of the configuration that is associated with the authentication service and the supported authentication mechanisms is pre-configured on the appliance. In most scenarios, this configuration is adequate. However, some scenarios require customization to meet your requirements.

Authentication configuration scenarios
Use the configuration scenarios to create a custom configuration for your environment.

Configuring an HOTP one-time password mechanism
The HOTP one-password mechanism relies on a public algorithm to generate the one-time password.

Configuring a TOTP one-time password mechanism
The TOTP one-password mechanism relies on a public algorithm to generate the one-time password.

Configuring a MAC one-time password mechanism
A one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail.

Configuring an RSA one-time password mechanism
A one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.

Configuring one-time password delivery methods
Passwords can be delivered to the user through Short Message Service (SMS) or email.

Configuring username and password authentication
The user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository.

Configuring an HTTP redirect authentication mechanism
The HTTP redirect authentication mechanism integrates an external application that you provide to use for authenticating users.

Configuring consent to device registration
Consent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.

Configuring an End-User License Agreement authentication mechanism
The End-User License Agreement authentication mechanism prompts the user to accept an End-User License Agreement (EULA) during an authentication flow.

Configuring an Email Message mechanism
The Email Message mechanism provides arbitrary information about a user via either email, webpage, or JSON for consumption by users or applications.

Configuring the reCAPTCHA Verification authentication mechanism
The reCAPTCHA Verification authentication mechanism provides anti-robot protection.

Configuring an Info Map authentication mechanism
Use this mechanism in your policy to return a template form and perform validation on the responding POST data. This mechanism is intended to work in conjunction with the Email Message mechanism.

Configuring a Knowledge Questions authentication mechanism
The Knowledge Questions authentication mechanism is an extra step-up authentication measure that uses knowledge questions and answers to authenticate the user.

Configuring a Mobile User Approved authentication mechanism
The Mobile User Approved authentication mechanism prompts the user to sign a random challenge string with a private key that is associated with one of the key values that are provided during the authentication flow.

Managing mapping rules
The mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

One-time password and authentication template files
The one-time password and authentication methods rely on HTML pages to interact with users, such as displaying errors or prompting users to provide a password or pin or to indicate the method by which they want to receive the password. You can customize these pages using the one-time password and authentication template files.

Push notification registration
Security Access Manager supports push notifications on both iOS and Android platforms.

Parent topic: Advanced Access Control configuration

Authentication Service configuration overviewAuthentication Service configuration overviewAuthentication configuration overviewMost of the configuration that is associated with the authentication service and the supported authentication mechanisms is pre-configured on the appliance. In most scenarios, this configuration is adequate. However, some scenarios require customization to meet your requirements.authentication serviceconfiguration You can configure the following components to customize the authentication support:Configure the point of contact settings.Customize the authentication mechanism settings.Modify the template pages to customize how you interact with your users.Point of contact settingsYou can configure the point of contact in the Advanced Configuration settings of the local management interface. For more information, see the configuration settings that begin with poc. in Managing Advanced ConfigurationAdjust configuration settings in supported configuration files.. This version of the Security Access Manager simplified the configuration that is required for the authentication service. Previous versions relied on a list of preconfigured authentication callbacks to determine the authentication flow. The addition of the new authentication policy format eliminated the need to rely on the authentication level value to determine the order of execution of the authentication mechanisms. The execution of an authentication event now depends on the content of the authentication policy. You can configure the Authentication Service to allow reauthentication. If enabled, the Authentication Service runs all the authentication mechanisms included on the authentication policy regardless of a pre-existing authentication session. Access policy scenario configuration This scenario is almost fully configured when you complete deployment and run activation and isamcfg. To enable this scenario: Create an access policy that references any of the authentication policies that are provided.Attach the access policy to the resource that you want to protect.No further configuration is needed. Web Gateway Appliance step-up authentication scenario This scenario requires a set of manual steps to enable it when you complete deployment and run activation and isamcfg. This scenario relies on an ACL or POP on the point of contact configuration to initiate the policy execution. The user must complete an authentication policy flow when the policy requires that the user step up to a higher authentication. This setup is specific to and dependent on the point of contact technology you are using in your environment. To configure the Web Gateway Appliance to enable this scenario, see Configuring step-up authenticationThe appliance reverse proxy server can be configured to use the authentication service for step-up authentication. The user is required to complete an authentication policy flow when the policy (ACL or POP) dictates that the user steps up to a higher authentication level.. Web Gateway Appliance authentication scenarioThis scenario requires a set of manual steps to enable it when you complete deployment and run activation and isamcfg. This scenario relies on an ACL or POP on the point of contact configuration to initiate the policy execution. The user must complete an authentication policy flow when the policy requires that the user authenticate. This setup is specific to and dependent on the point of contact technology you are using in your environment. To configure the Web Gateway Appliance to enable this scenario, see Configuring authenticationThe appliance reverse proxy server can be configured to use the authentication service for authentication. The user will be required to complete an authentication policy flow when the Security Access Manager policy (ACL or POP) dictates that the user authenticates.. Authentication mechanism settingsYou can modify authentication mechanism settings through the local management interface. See the configuring topics for the authentication mechanisms you want to use:Configuring a TOTP one-time password mechanismThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring an HOTP one-time password mechanismThe HOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring an RSA one-time password mechanismA one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.Configuring a MAC one-time password mechanismA one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail. Configuring consent to device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.Configuring an HTTP redirect authentication mechanism The HTTP redirect authentication mechanism integrates an external application that you provide to use for authenticating users.Configuring username and password authenticationThe user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository. Configuring an End-User License Agreement authentication mechanism The End-User License Agreement authentication mechanism prompts the user to accept an End-User License Agreement (EULA) during an authentication flow.Configuring a Knowledge Questions authentication mechanismThe Knowledge Questions authentication mechanism is an extra step-up authentication measure that uses knowledge questions and answers to authenticate the user. For advanced customization of the authentication service or the one-time password generation, delivery, and verification, you can customize the mapping rules. See Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.. Template configuration Many HTML pages and XML documents are provided to interact with your users. The pages prompt users for authentication information, provide them with one-time passwords, or notify them of errors during authentication. For information about customizing the template pages, see Modifying template filesUse the local management interface to manage files and directories in the template files.. AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Authentication Service configuration overview

Most of the configuration that is associated with the authentication service and the supported authentication mechanisms is pre-configured on the appliance. In most scenarios, this configuration is adequate. However, some scenarios require customization to meet your requirements.

You can configure the following components to customize the authentication support:

Configure the point of contact settings.

Customize the authentication mechanism settings.

Modify the template pages to customize how you interact with your users.

Point of contact settings

You can configure the point of contact in the Advanced Configuration settings of the local management interface. For more information, see the configuration settings that begin with poc. in Managing Advanced Configuration.

This version of the Security Access Manager simplified the configuration that is required for the authentication service. Previous versions relied on a list of preconfigured authentication callbacks to determine the authentication flow. The addition of the new authentication policy format eliminated the need to rely on the authentication level value to determine the order of execution of the authentication mechanisms. The execution of an authentication event now depends on the content of the authentication policy. You can configure the Authentication Service to allow reauthentication. If enabled, the Authentication Service runs all the authentication mechanisms included on the authentication policy regardless of a pre-existing authentication session.

Access policy scenario configuration

This scenario is almost fully configured when you complete deployment and run activation and isamcfg. To enable this scenario:

Create an access policy that references any of the authentication policies that are provided.

Attach the access policy to the resource that you want to protect.

No further configuration is needed.

Web Gateway Appliance step-up authentication scenario

This scenario requires a set of manual steps to enable it when you complete deployment and run activation and isamcfg. This scenario relies on an ACL or POP on the point of contact configuration to initiate the policy execution. The user must complete an authentication policy flow when the policy requires that the user step up to a higher authentication. This setup is specific to and dependent on the point of contact technology you are using in your environment. To configure the Web Gateway Appliance to enable this scenario, see Configuring step-up authentication.

Web Gateway Appliance authentication scenario

This scenario requires a set of manual steps to enable it when you complete deployment and run activation and isamcfg. This scenario relies on an ACL or POP on the point of contact configuration to initiate the policy execution. The user must complete an authentication policy flow when the policy requires that the user authenticate. This setup is specific to and dependent on the point of contact technology you are using in your environment. To configure the Web Gateway Appliance to enable this scenario, see Configuring authentication.

Authentication mechanism settings

You can modify authentication mechanism settings through the local management interface. See the configuring topics for the authentication mechanisms you want to use:

Configuring a TOTP one-time password mechanism

Configuring an HOTP one-time password mechanism

Configuring an RSA one-time password mechanism

Configuring a MAC one-time password mechanism

Configuring consent to device registration

Configuring an HTTP redirect authentication mechanism

Configuring username and password authentication

Configuring an End-User License Agreement authentication mechanism

Configuring a Knowledge Questions authentication mechanism

For advanced customization of the authentication service or the one-time password generation, delivery, and verification, you can customize the mapping rules. See Managing mapping rules.

Template configuration

Many HTML pages and XML documents are provided to interact with your users. The pages prompt users for authentication information, provide them with one-time passwords, or notify them of errors during authentication. For information about customizing the template pages, see Modifying template files.

Parent topic: Authentication

Authentication configuration scenariosUse the configuration scenarios to create a custom configuration for your environment.scenariosauthentication configurationAuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.Configuring step-up authenticationThe appliance reverse proxy server can be configured to use the authentication service for step-up authentication. The user is required to complete an authentication policy flow when the policy (ACL or POP) dictates that the user steps up to a higher authentication level.Configuring authenticationThe appliance reverse proxy server can be configured to use the authentication service for authentication. The user will be required to complete an authentication policy flow when the Security Access Manager policy (ACL or POP) dictates that the user authenticates.

Authentication configuration scenarios

Use the configuration scenarios to create a custom configuration for your environment.

Configuring step-up authentication
The appliance reverse proxy server can be configured to use the authentication service for step-up authentication. The user is required to complete an authentication policy flow when the policy (ACL or POP) dictates that the user steps up to a higher authentication level.

Configuring authentication
The appliance reverse proxy server can be configured to use the authentication service for authentication. The user will be required to complete an authentication policy flow when the Security Access Manager policy (ACL or POP) dictates that the user authenticates.

Parent topic: Authentication

Configuring step-up authenticationThe appliance reverse proxy server can be configured to use the authentication service for step-up authentication. The user is required to complete an authentication policy flow when the policy (ACL or POP) dictates that the user steps up to a higher authentication level.step-up authenticationconfiguringThis task applies to both the Web Gateway appliance and the Security Access Manager appliance.Configure the appliance with the isamcfg tool. See Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool. .Modify the appliance stepuplogin.html file so that it redirects the authentication request to the Security Access Manager Authentication Service.Locate the stepuplogin.html file.For information about working with reverse proxy pages, see HTML server response page modification.Edit the file to insert the following code in the JavaScript section of the file. Optionally, to indicate where to send the user agent after successful authentication, pass the Target query string parameters, which is the default.For example:var authnlevel="%AUTHNLEVEL%"; if (authnlevel == "2"){ window.location = "https://<HOST>:<PORT>/<JUNCTION> /sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED%&PolicyId=<POLICY_ID>"; }Where:HOST The host name for the reverse proxy instance. PORT The port number for the reverse proxy instance. JUNCTIONThe Advanced Access Control junction name. For example: mga.POLICY_IDThe authentication policy identifier to execute when the user is requested to step up.The following example uses one-time password as the step-up mechanism:var authnlevel="%AUTHNLEVEL%"; if (authnlevel == "2"){ window.location = "https://example.com/mga/ sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED%&PolicyId=urn:ibm:security: authentication:asf:otp"; }Restart the appliance.Verify the configuration:Create a test user account. For example: pdadmin> user create john cn=john, dc=iswga John Doe passwordActivate the account. For example: pdadmin> user modify john account-valid yesCreate a test resource that is protected with level 2 authentication and place it in the document root of the appliance reverse proxy server.For example: /junction-root/test.htmlFor information about working with reverse proxy pages, see HTML server response page modificationTry accessing that resource through the appliance reverse proxy server. For example: https://mga.example.com/test.htmlA web form is displayed and prompts you to enter the user name and password.Enter the credential that you created in step 4.a. The contents of the resource is displayed.Create a Protected Object Policy (POP) with a level 2 authentication. For example: pdadmin> pop create level2only pdadmin> pop modify level2only set ipauth anyothernw 2Attach the POP to the protected resource that you created in step 4.c. For example: pdadmin> pop attach /WebSEAL/mga.example.com-default/ test.html level2onlyOpen a new browser session and try accessing the test resource again. A web form is displayed and prompts you to enter the user name and password.Enter the credential for the test user. You are forwarded to the extended authentication endpoint. You are now starting the authentication policy.Enter the required credentials to complete the authentication policy. If you authenticate successfully, you are redirected to back to the test resource and you can access the contents of the resource.Authentication configuration scenariosUse the configuration scenarios to create a custom configuration for your environment.

Configuring step-up authentication

The appliance reverse proxy server can be configured to use the authentication service for step-up authentication. The user is required to complete an authentication policy flow when the policy (ACL or POP) dictates that the user steps up to a higher authentication level.

About this task

This task applies to both the Web Gateway appliance and the Security Access Manager appliance.

Procedure

Configure the appliance with the isamcfg tool. See Using the isamcfg tool .

Modify the appliance stepuplogin.html file so that it redirects the authentication request to the Security Access Manager Authentication Service.

Locate the stepuplogin.html file. For information about working with reverse proxy pages, see HTML server response page modification.

Edit the file to insert the following code in the JavaScript section of the file. Optionally, to indicate where to send the user agent after successful authentication, pass the Target query string parameters, which is the default. For example:

var authnlevel="%AUTHNLEVEL%";
if (authnlevel == "2"){
  window.location = "https://<HOST>:<PORT>/<JUNCTION>
     /sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED%&PolicyId=<POLICY_ID>";
}

Where:

HOST

The host name for the reverse proxy instance.

PORT

The port number for the reverse proxy instance.

JUNCTION

The Advanced Access Control junction name. For example: mga.

POLICY_ID

The authentication policy identifier to execute when the user is requested to step up.

The following example uses one-time password as the step-up mechanism:

var authnlevel="%AUTHNLEVEL%";
if (authnlevel == "2"){
   window.location = "https://example.com/mga/
     sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED%&PolicyId=urn:ibm:security:
     authentication:asf:otp";
}

Restart the appliance.

Verify the configuration:

Create a test user account. For example:

 pdadmin> user create john cn=john, dc=iswga John Doe password

Activate the account. For example:

pdadmin> user modify john account-valid yes

Create a test resource that is protected with level 2 authentication and place it in the document root of the appliance reverse proxy server. For example:

/junction-root/test.html

For information about working with reverse proxy pages, see HTML server response page modification

Try accessing that resource through the appliance reverse proxy server. For example:

https://mga.example.com/test.html

A web form is displayed and prompts you to enter the user name and password.

Enter the credential that you created in step 4.a. The contents of the resource is displayed.

Create a Protected Object Policy (POP) with a level 2 authentication. For example:

pdadmin> pop create level2only
pdadmin> pop modify level2only set ipauth anyothernw 2

Attach the POP to the protected resource that you created in step 4.c. For example:

pdadmin> pop attach /WebSEAL/mga.example.com-default/
   test.html level2only

Open a new browser session and try accessing the test resource again. A web form is displayed and prompts you to enter the user name and password.

Enter the credential for the test user. You are forwarded to the extended authentication endpoint. You are now starting the authentication policy.

Enter the required credentials to complete the authentication policy. If you authenticate successfully, you are redirected to back to the test resource and you can access the contents of the resource.

Parent topic: Authentication configuration scenarios

Configuring authenticationThe appliance reverse proxy server can be configured to use the authentication service for authentication. The user will be required to complete an authentication policy flow when the Security Access Manager policy (ACL or POP) dictates that the user authenticates.authenticationconfiguring This task applies to the Web Gateway, Security Access Manager for Web, and Security Access Manager appliances.Configure the appliance using the isamcfg tool. See Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool. .Modify the appliance login.html so that it redirects the authentication request to the Security Access Manager Authentication Service.Locate the login.html file on the appliance.For information about working with reverse proxy pages, see HTML server response page modification.Open the file in a text editor and insert a meta-tag refresh tag to send the request to the authentication service. Optionally, to indicate where to send the user agent after successful authentication, pass the Target query string parameters, which is the default.For example:<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <HTML> <HEAD> <meta http-equiv="refresh" content="2;url=https://<HOST>:<PORT>/<JUNCTION>/ sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED&PolicyId=<POLICY_ID>"> <TITLE>Access Manager for Web Login</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF" TEXT="#000000"> </BODY> </HTML>Where:HOST The host name for the reverse proxy instance. PORT The port number for the reverse proxy instance. JUNCTIONThe Advanced Access Control junction name. For example: mga.POLICY_IDThe authentication policy identifier to execute when the user is requested to step up. The following example uses user name and password as the login mechanism: <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <HTML> <HEAD> <meta http-equiv="refresh" content="2;url=https://example.com/mga/ sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED%&PolicyId=urn:ibm:security:authentication:asf:password"> <TITLE>Access Manager for Web Login</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF" TEXT="#000000"> </BODY> </HTML> Restart the appliance.Verify the configuration:Create a test user account. For example: pdadmin> user create john cn=john,dc=iswga John Doe passwordActivate the account. For example: pdadmin> user modify john account-valid yesCreate a test resource that is protected with the isam_mobile_anyauth ACL and place it in the document root of WebSEAL.For example: junction-root/test.htmlFor information about working with reverse proxy pages, see HTML server response page modificationAttach the isam_mobile_anyauth ACL to the protected resource. For example: pdadmin> acl attach /WebSEAL/mga.example.com-default/test.html isam_mobile_anyauthOpen a new browser session and try accessing the test resource. You are forwarded to the authentication service endpoint. You are now starting the authentication policy.Enter the required credentials to complete the authentication policy. If you authentication successfully, you are redirected to the test resource and you can access the contents of that resource. Authentication configuration scenariosUse the configuration scenarios to create a custom configuration for your environment.

Configuring authentication

The appliance reverse proxy server can be configured to use the authentication service for authentication. The user will be required to complete an authentication policy flow when the Security Access Manager policy (ACL or POP) dictates that the user authenticates.

About this task

This task applies to the Web Gateway, Security Access Manager for Web, and Security Access Manager appliances.

Procedure

Configure the appliance using the isamcfg tool. See Using the isamcfg tool .

Modify the appliance login.html so that it redirects the authentication request to the Security Access Manager Authentication Service.

Locate the login.html file on the appliance. For information about working with reverse proxy pages, see HTML server response page modification.

Open the file in a text editor and insert a meta-tag refresh tag to send the request to the authentication service. Optionally, to indicate where to send the user agent after successful authentication, pass the Target query string parameters, which is the default. For example:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta http-equiv="refresh" content="2;url=https://<HOST>:<PORT>/<JUNCTION>/
  sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED&PolicyId=<POLICY_ID>">
<TITLE>Access Manager for Web Login</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
</BODY>
</HTML>

Where:

HOST

The host name for the reverse proxy instance.

PORT

The port number for the reverse proxy instance.

JUNCTION

The Advanced Access Control junction name. For example: mga.

POLICY_ID

The authentication policy identifier to execute when the user is requested to step up.

The following example uses user name and password as the login mechanism:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta http-equiv="refresh" content="2;url=https://example.com/mga/
  sps/authsvc?Target=%HTTPS_BASE%%URL_ENCODED%&PolicyId=urn:ibm:security:authentication:asf:password">
<TITLE>Access Manager for Web Login</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
</BODY>
</HTML>

Restart the appliance.

Verify the configuration:

Create a test user account. For example:

 pdadmin> user create john cn=john,dc=iswga John Doe password

Activate the account. For example:

pdadmin> user modify john account-valid yes

Create a test resource that is protected with the isam_mobile_anyauth ACL and place it in the document root of WebSEAL. For example:

junction-root/test.html

For information about working with reverse proxy pages, see HTML server response page modification

Attach the isam_mobile_anyauth ACL to the protected resource. For example:

pdadmin> acl attach /WebSEAL/mga.example.com-default/test.html
          isam_mobile_anyauth

Open a new browser session and try accessing the test resource. You are forwarded to the authentication service endpoint. You are now starting the authentication policy.

Enter the required credentials to complete the authentication policy. If you authentication successfully, you are redirected to the test resource and you can access the contents of that resource.

Parent topic: Authentication configuration scenarios

Configuring an HOTP one-time password mechanismConfiguring an HOTP one-time password mechanismConfiguring an HOTP one-time password mechanismThe HOTP one-password mechanism relies on a public algorithm to generate the one-time password.one-time passwordconfiguring HOTPThe HOTP client solution and Security Access Manager use the same algorithm to generate the one-time password value. No interaction is required between the client software and the Security Access Manager solution. The algorithm uses a shared secret key and a counter to generate the one-time password value. Every time a new one-time password is generated, the counter value increments on both server and client solutions. No delivery of the one-time password is required.This task describes the steps and properties for configuring a HOTP mechanism. For information about configuring other providers, see: Configuring a MAC one-time password mechanismA one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail. Configuring a TOTP one-time password mechanismThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring an RSA one-time password mechanismA one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.When users attempt to log in using HOTP or TOTP and submit an incorrect one-time password, they receive one strike against their account. This strike remains on their account for a configurable duration. By default, the duration is 10 minutes. After that duration, the strike is removed from their account. When users submit multiple incorrect one-time passwords, they can reach a maximum and are then prevented from making another attempt until one of their strikes expires. By default, the maximum is 5. If the users log in successfully, any strikes on their account are cleared. Strikes are shared between TOTP and HOTP. For example, if the users made two incorrect attempts using TOTP, those strikes count against them on HOTP as well. Because user retries affect only TOTP and HOTP logins, users who exceeded password attempt using those logins can still use other OTP provider logins or basic username/password authentication. You can modify the password retry settings through the Advanced Configuration settings in the local management interface. For more information, see Managing advanced configurationAdjust configuration settings in supported configuration files..Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click HOTP One-time Password.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism.HOTPMax Counter LookaheadThe number of times to increment the counter to see whether the one-time password is valid before stopping. Any non-negative number is valid.The default is 25.Password LengthThe length of the generated one-time passwords, which can be 6 - 9 characters or numbers.The default is 6.Generation AlgorithmThe algorithm that is used to generate the one-time password. Valid options include the following algorithms: HmacSHA1HmacSHA256HmacSHA512The default is HmacSHA1.Secret key URL The URL that is used to deliver the secret key. The QR code is also generated using this URL. The URL format might include information specific to your environment, such as your company name. The default URL is:otpauth://hotp/Example:@USER_NAME@?secret=@SECRET_KEY@&issuer= Example&counter=0 The URL uses two macros. Place these macros in the URL wherever their corresponding values belong.@SECRET_KEY@The secret key.@USER_NAME@The user name of the authorized user who logs in. You must change this URL to the appropriate URL for your environment. For example:otpauth://hotp/Example:sec_master?secret=4W7O6TZGEZKN5PUY &issuer=Example&counter=0 Secret key attribute nameThe attribute name that is used for storage of the HOTP secret key in the database.Data type: StringExample: otp.hmac.hotp.secret.keySecret key attribute namespaceThe attribute namespace of the HOTP secret key. The namespace in combination with the attribute name constitutes the unique identifier for the attribute in the database.Data type: StringExample: urn:ibm:security:otp:hmacClick Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring an HOTP one-time password mechanism

The HOTP one-password mechanism relies on a public algorithm to generate the one-time password.

About this task

The HOTP client solution and Security Access Manager use the same algorithm to generate the one-time password value. No interaction is required between the client software and the Security Access Manager solution. The algorithm uses a shared secret key and a counter to generate the one-time password value. Every time a new one-time password is generated, the counter value increments on both server and client solutions. No delivery of the one-time password is required.

This task describes the steps and properties for configuring a HOTP mechanism. For information about configuring other providers, see:

Configuring a MAC one-time password mechanism

Configuring a TOTP one-time password mechanism

Configuring an RSA one-time password mechanism

Note: When users attempt to log in using HOTP or TOTP and submit an incorrect one-time password, they receive one strike against their account. This strike remains on their account for a configurable duration. By default, the duration is 10 minutes. After that duration, the strike is removed from their account. When users submit multiple incorrect one-time passwords, they can reach a maximum and are then prevented from making another attempt until one of their strikes expires. By default, the maximum is 5. If the users log in successfully, any strikes on their account are cleared. Strikes are shared between TOTP and HOTP. For example, if the users made two incorrect attempts using TOTP, those strikes count against them on HOTP as well. Because user retries affect only TOTP and HOTP logins, users who exceeded password attempt using those logins can still use other OTP provider logins or basic username/password authentication. You can modify the password retry settings through the Advanced Configuration settings in the local management interface. For more information, see Managing advanced configuration.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click HOTP One-time Password.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

HOTP

Max Counter Lookahead

The number of times to increment the counter to see whether the one-time password is valid before stopping. Any non-negative number is valid.

The default is 25.

Password Length

The length of the generated one-time passwords, which can be 6 - 9 characters or numbers.

The default is 6.

Generation Algorithm

The algorithm that is used to generate the one-time password. Valid options include the following algorithms:

HmacSHA1

HmacSHA256

HmacSHA512

The default is HmacSHA1.

Secret key URL

The URL that is used to deliver the secret key. The QR code is also generated using this URL. The URL format might include information specific to your environment, such as your company name.

The default URL is:

otpauth://hotp/Example:@USER_NAME@?secret=@SECRET_KEY@&issuer=
Example&counter=0

The URL uses two macros. Place these macros in the URL wherever their corresponding values belong.

@SECRET_KEY@

The secret key.

@USER_NAME@

The user name of the authorized user who logs in.

Attention: You must change this URL to the appropriate URL for your environment. For example:

otpauth://hotp/Example:sec_master?secret=4W7O6TZGEZKN5PUY
&issuer=Example&counter=0

Secret key attribute name

The attribute name that is used for storage of the HOTP secret key in the database.

Data type: String

Example: otp.hmac.hotp.secret.key

Secret key attribute namespace

The attribute namespace of the HOTP secret key. The namespace in combination with the attribute name constitutes the unique identifier for the attribute in the database.

Data type: String

Example: urn:ibm:security:otp:hmac

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changes.

Parent topic: Authentication

Configuring a TOTP one-time password mechanismConfiguring a TOTP one-time password mechanismConfiguring a TOTP one-time password mechanismThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password.one-time password configuring TOTPThe TOTP client solution and the Security Access Manager use the same algorithm to generate the one-time password value. No interaction is required between the client software and the Security Access Manager solution. The algorithm uses a shared secret key and the time to generate the one-time password value. No delivery of the one-time password is required.This task describes the steps and properties for configuring a TOTP mechanism. For information about configuring other one-time password providers, see: Configuring a MAC one-time password mechanismA one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail. Configuring an HOTP one-time password mechanismThe HOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring an RSA one-time password mechanismA one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.When users attempt to log in using HOTP or TOTP and submit an incorrect one-time password, they receive one strike against their account. This strike remains on their account for a configurable duration. By default, the duration is 10 minutes. After that duration, the strike is removed from their account. When users submit multiple incorrect one-time passwords, they can reach a maximum and are then prevented from making another attempt until one of their strikes expires. By default, the maximum is 5. If the users log in successfully, any strikes on their account are cleared. Strikes are shared between TOTP and HOTP. For example, if the users made two incorrect attempts using TOTP, those strikes count against them on HOTP as well. Because user retries affect only TOTP and HOTP logins, users who exceeded password attempt using those logins can still use other OTP provider logins or basic username/password authentication. You can modify the password retry settings through the Advanced Configuration settings in the local management interface. For more information, see Managing advanced configurationAdjust configuration settings in supported configuration files..Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click TOTP One-time Password.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism.TOTPGeneration Interval (seconds)The number of seconds an interval lasts. This number determines how long a one-time password is active before the next one-time password generates.The default is 30.Password LengthThe length of the generated one-time passwords, which can be 6 - 9 characters or numbers.The default is 6.Skew IntervalsThe skew intervals of the algorithm. The skew intervals consider any possible synchronization delay between the server and the client that generates the one-time password. For example, a skew interval of 2 means a one-time password in up to two intervals in the past, or two in the future are valid. For example, if it is interval 563, and intervals are 30 seconds, then one-time passwords for intervals 561-565 are computed and checked against within a range of 2.5 minutes. The default is 1.One Time UseWhether to cache one-time passwords if they are used to successfully log in. If set to true, then the reuse of a one-time password is prevented while it is in cache.The default is true.Generation AlgorithmThe algorithm that is used to generate the one-time password. Valid options include the following algorithms: HmacSHA1HmacSHA256HmacSHA512The default is HmacSHA1.Secret key URL The URL that is used to deliver the secret key. The QR code is also generated using this URL. The URL format might include information specific to your environment, such as your company name. The default URL is:otpauth://totp/Example:@USER_NAME@?secret=@SECRET_KEY@&issuer =Example The URL uses two macros. Place these macros in the URL wherever their corresponding values belong.@SECRET_KEY@The secret key.@USER_NAME@The user name of the authorized user who logs in. You must change this URL to the appropriate URL for your environment. For example:otpauth://totp/Example:sec_master?secret=4W7O6TZGEZKN5PUY &issuer=Example Secret key attribute nameThe attribute name that is used for storage of the TOTP secret key in the database.Data type: StringExample: otp.hmac.totp.secret.keySecret key attribute namespaceThe attribute namespace of the TOTP secret key. The namespace in combination with the attribute name constitutes the unique identifier for the attribute in the database.Data type: StringExample: urn:ibm:security:otp:hmacClick Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring a TOTP one-time password mechanism

The TOTP one-password mechanism relies on a public algorithm to generate the one-time password.

About this task

The TOTP client solution and the Security Access Manager use the same algorithm to generate the one-time password value. No interaction is required between the client software and the Security Access Manager solution. The algorithm uses a shared secret key and the time to generate the one-time password value. No delivery of the one-time password is required.

This task describes the steps and properties for configuring a TOTP mechanism. For information about configuring other one-time password providers, see:

Configuring a MAC one-time password mechanism

Configuring an HOTP one-time password mechanism

Configuring an RSA one-time password mechanism

Note: When users attempt to log in using HOTP or TOTP and submit an incorrect one-time password, they receive one strike against their account. This strike remains on their account for a configurable duration. By default, the duration is 10 minutes. After that duration, the strike is removed from their account. When users submit multiple incorrect one-time passwords, they can reach a maximum and are then prevented from making another attempt until one of their strikes expires. By default, the maximum is 5. If the users log in successfully, any strikes on their account are cleared. Strikes are shared between TOTP and HOTP. For example, if the users made two incorrect attempts using TOTP, those strikes count against them on HOTP as well. Because user retries affect only TOTP and HOTP logins, users who exceeded password attempt using those logins can still use other OTP provider logins or basic username/password authentication. You can modify the password retry settings through the Advanced Configuration settings in the local management interface. For more information, see Managing advanced configuration.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click TOTP One-time Password.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

TOTP

Generation Interval (seconds)

The number of seconds an interval lasts. This number determines how long a one-time password is active before the next one-time password generates.

The default is 30.

Password Length

The length of the generated one-time passwords, which can be 6 - 9 characters or numbers.

The default is 6.

Skew Intervals

The skew intervals of the algorithm. The skew intervals consider any possible synchronization delay between the server and the client that generates the one-time password. For example, a skew interval of 2 means a one-time password in up to two intervals in the past, or two in the future are valid. For example, if it is interval 563, and intervals are 30 seconds, then one-time passwords for intervals 561-565 are computed and checked against within a range of 2.5 minutes.

The default is 1.

One Time Use

Whether to cache one-time passwords if they are used to successfully log in. If set to true, then the reuse of a one-time password is prevented while it is in cache.

The default is true.

Generation Algorithm

The algorithm that is used to generate the one-time password. Valid options include the following algorithms:

HmacSHA1

HmacSHA256

HmacSHA512

The default is HmacSHA1.

Secret key URL

The URL that is used to deliver the secret key. The QR code is also generated using this URL. The URL format might include information specific to your environment, such as your company name.

The default URL is:

otpauth://totp/Example:@USER_NAME@?secret=@SECRET_KEY@&issuer
=Example

The URL uses two macros. Place these macros in the URL wherever their corresponding values belong.

@SECRET_KEY@

The secret key.

@USER_NAME@

The user name of the authorized user who logs in.

Attention: You must change this URL to the appropriate URL for your environment. For example:

otpauth://totp/Example:sec_master?secret=4W7O6TZGEZKN5PUY
&issuer=Example

Secret key attribute name

The attribute name that is used for storage of the TOTP secret key in the database.

Data type: String

Example: otp.hmac.totp.secret.key

Secret key attribute namespace

The attribute namespace of the TOTP secret key. The namespace in combination with the attribute name constitutes the unique identifier for the attribute in the database.

Data type: String

Example: urn:ibm:security:otp:hmac

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changes.

Parent topic: Authentication

Configuring a MAC one-time password mechanismConfiguring a MAC one-time password mechanismConfiguring a MAC one-time password mechanismA one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail. one-time passwordconfiguring MACThis task describes the steps and properties for configuring a MAC mechanism. For information about configuring other providers, see: Configuring an HOTP one-time password mechanismThe HOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring a TOTP one-time password mechanismThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring an RSA one-time password mechanismA one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click MAC One-time Password.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism.MACPassword Character SetThe character set from which the characters in the one-time password are generated.The default is 0123456789.Password LengthThe length of the characters in the one-time password.The default is 6.Store Entry Hash AlgorithmThe hash algorithm that is used for hashing the one-time password before it is stored in the one-time password store plug-in. The supported algorithms are:SHA1SHA-256SHA-512The default is SHA-256.Store Entry Lifetime (seconds)The length of time that the one-time password is stored. The lifetime is in seconds.The default is 300.Click Save.When you configure one-time password providers, a message indicates that changes have not been deployed. If you have finished making changes, deploy them. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Next, consider configuring the delivery methods for the one-time password. Both SMS and Email delivery are enabled but you will want to configure the delivery properties, such as SMTP server or connection URL, for your environment. See Configuring one-time password delivery methodsPasswords can be delivered to the user through Short Message Service (SMS) or email. .AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring a MAC one-time password mechanism

A one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail.

About this task

This task describes the steps and properties for configuring a MAC mechanism. For information about configuring other providers, see:

Configuring an HOTP one-time password mechanism

Configuring a TOTP one-time password mechanism

Configuring an RSA one-time password mechanism

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click MAC One-time Password.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

MAC

Password Character Set

The character set from which the characters in the one-time password are generated.

The default is 0123456789.

Password Length

The length of the characters in the one-time password.

The default is 6.

Store Entry Hash Algorithm

The hash algorithm that is used for hashing the one-time password before it is stored in the one-time password store plug-in. The supported algorithms are:

SHA1

SHA-256

SHA-512

The default is SHA-256.

Store Entry Lifetime (seconds)

The length of time that the one-time password is stored. The lifetime is in seconds.

The default is 300.

Click Save.

What to do next

When you configure one-time password providers, a message indicates that changes have not been deployed. If you have finished making changes, deploy them. For more information, see Deploying pending changes.

Next, consider configuring the delivery methods for the one-time password. Both SMS and Email delivery are enabled but you will want to configure the delivery properties, such as SMTP server or connection URL, for your environment. See Configuring one-time password delivery methods.

Parent topic: Authentication

Configuring an RSA one-time password mechanismConfiguring an RSA one-time password mechanismConfiguring an RSA one-time password mechanismA one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.one-time passwordconfiguring an RSA mechanismComplete the following steps.On your RSA server, generate the following files:sdconf.recThe configuration file for connecting to the RSA Authentication server.sdopts.recThe configuration properties file that contains optional configurations for load balancing.See your RSA Authentication server documentation for details on creating these files and use the following guidelines: On the appliance, you must specify an Agent Network Interface. See Agent Network Interface in step 8. If you connect the RSA server to the appliance by using an application network interface with multiple IP addresses, list all the IP addresses in the Alternate IPs box on the RSA server.For Agent type, choose Standard.Agent Auto-Registration must be enabled when the first RSA one-time password authentication is performed. You can disable it after the first successful authentication is completed.The RSA one-time password mechanism does not support replication of the RSA session information through the cluster environment. The session information is local to each cluster node and the environment must be configured to enforce session affinity between the client and the cluster node.Move or copy the generated files from the RSA server to the appliance.This task describes the steps and properties for configuring an RSA mechanism. For information about configuring other providers, see:Configuring an HOTP one-time password mechanismThe HOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring a MAC one-time password mechanismA one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail. Configuring a TOTP one-time password mechanismThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click RSA One-time Password.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism.Agent Network InterfaceThe name of the network interface that the RSA Agent is using to connect to the RSA server.Required: YesData type: StringValid values: Management network interface valuesM.1M.2Application network interface valuesP.1P.2P.3P.4If you are using the RSA mechanism in a cluster environment and use an application interface with multiple IP addresses defined for that interface, use the RSA console to add all of those IP addresses to the whitelist. See the RSA documentation for information about adding IP addresses to the whitelist.Example: M.1Server Exchange Initial TimeoutThe initial timeout coefficient in milliseconds used to calculate the timeout of the request.Required: NoData type: IntegerExample: 1000Server Exchange Timeout OffsetThe offset timeout coefficient in milliseconds used to calculate the timeout of the request.Required: NoData type: IntegerExample: 200Server Exchange Timeout IncrementThe increment coefficient in milliseconds used to calculate the timeout of the request.Required: NoData type: Integer Example: 100Event Log LevelThe minimum event level to be logged. Events below the level that is specified in this property are not logged.The events in order from lowest level to highest are:OFFDEBUGINFOWARNERRORFATALRequired: Data type: String Example: INFO. If this property is set to INFO, the DEBUG errors are not logged.Enable Debug TracingThe property that enables debug tracing.Required: NoData type: BooleanExample: FALSE. If set to FALSE, debug tracing is not enabled.Trace Function EntriesThe property that enables tracing of function entries.Required: NoData type: BooleanExample: FALSE. If set to FALSE, function entries are not traced.Trace Function ExitsThe property that enables tracing of exits.Required: NoData type: BooleanExample: FALSE. If set to FALSE, exits are not traced.Trace Flow StatementsThe property that enables tracing of flow statements.Required: NoData type: BooleanExample: FALSE. If set to FALSE, flow statements are not traced.Trace Regular StatementsThe property that enables tracing of regular statements.Required: NoData type: BooleanExample: FALSE. If set to FALSE, regular statements are not traced.Trace LocationThe property that enables the class name and line number to be displayed in the trace.Required: NoData type: BooleanExample: FALSE. If set to FALSE, class name and line number are not displayed.Session TimeoutThe length of time, in seconds, that a connection to the RSA Authentication Manager server remains open before it times out when a user attempts to authenticate.Required: NoData type: IntegerExample: 1800Click the Agent Files tab.Select a file in the table the corresponds to the file you generated on the RSA server.Click Upload to upload the file or Clear to remove the contents of the selected file.The status area indicates one of three statuses:Not uploadedUpload is not completed.Last upload dateUpload was completed on date indicated.Auto-generatedThe SecurID was automatically generated instead of uploaded.Repeat this step until all of your files have been uploaded to the appliance.Click Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring an RSA one-time password mechanism

A one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.

Before you begin

Complete the following steps.

On your RSA server, generate the following files:

sdconf.rec

The configuration file for connecting to the RSA Authentication server.

sdopts.rec

The configuration properties file that contains optional configurations for load balancing.

See your RSA Authentication server documentation for details on creating these files and use the following guidelines:

On the appliance, you must specify an Agent Network Interface. See Agent Network Interface in step 8. If you connect the RSA server to the appliance by using an application network interface with multiple IP addresses, list all the IP addresses in the Alternate IPs box on the RSA server.

For Agent type, choose Standard.

Agent Auto-Registration must be enabled when the first RSA one-time password authentication is performed. You can disable it after the first successful authentication is completed.

Note: The RSA one-time password mechanism does not support replication of the RSA session information through the cluster environment. The session information is local to each cluster node and the environment must be configured to enforce session affinity between the client and the cluster node.

Move or copy the generated files from the RSA server to the appliance.

About this task

This task describes the steps and properties for configuring an RSA mechanism. For information about configuring other providers, see:

Configuring an HOTP one-time password mechanism

Configuring a MAC one-time password mechanism

Configuring a TOTP one-time password mechanism

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click RSA One-time Password.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Agent Network Interface

The name of the network interface that the RSA Agent is using to connect to the RSA server.

Required: Yes

Data type: String

Valid values:

Management network interface values

M.1

M.2

Application network interface values

P.1

P.2

P.3

P.4

Note: If you are using the RSA mechanism in a cluster environment and use an application interface with multiple IP addresses defined for that interface, use the RSA console to add all of those IP addresses to the whitelist. See the RSA documentation for information about adding IP addresses to the whitelist.

Example: M.1

Server Exchange Initial Timeout

The initial timeout coefficient in milliseconds used to calculate the timeout of the request.

Required: No

Data type: Integer

Example: 1000

Server Exchange Timeout Offset

The offset timeout coefficient in milliseconds used to calculate the timeout of the request.

Required: No

Data type: Integer

Example: 200

Server Exchange Timeout Increment

The increment coefficient in milliseconds used to calculate the timeout of the request.

Required: No

Data type: Integer

Example: 100

Event Log Level

The minimum event level to be logged. Events below the level that is specified in this property are not logged.

The events in order from lowest level to highest are:

OFF

DEBUG

INFO

WARN

ERROR

FATAL

Required:

Data type: String

Example: INFO. If this property is set to INFO, the DEBUG errors are not logged.

Enable Debug Tracing

The property that enables debug tracing.

Required: No

Data type: Boolean

Example: FALSE. If set to FALSE, debug tracing is not enabled.

Trace Function Entries

The property that enables tracing of function entries.

Required: No

Data type: Boolean

Example: FALSE. If set to FALSE, function entries are not traced.

Trace Function Exits

The property that enables tracing of exits.

Required: No

Data type: Boolean

Example: FALSE. If set to FALSE, exits are not traced.

Trace Flow Statements

The property that enables tracing of flow statements.

Required: No

Data type: Boolean

Example: FALSE. If set to FALSE, flow statements are not traced.

Trace Regular Statements

The property that enables tracing of regular statements.

Required: No

Data type: Boolean

Example: FALSE. If set to FALSE, regular statements are not traced.

Trace Location

The property that enables the class name and line number to be displayed in the trace.

Required: No

Data type: Boolean

Example: FALSE. If set to FALSE, class name and line number are not displayed.

Session Timeout

The length of time, in seconds, that a connection to the RSA Authentication Manager server remains open before it times out when a user attempts to authenticate.

Required: No

Data type: Integer

Example: 1800

Click the Agent Files tab.

Select a file in the table the corresponds to the file you generated on the RSA server.

Click Upload to upload the file or Clear to remove the contents of the selected file. The status area indicates one of three statuses:

Not uploaded

Upload is not completed.

Last upload date

Upload was completed on date indicated.

Auto-generated

The SecurID was automatically generated instead of uploaded.

Repeat this step until all of your files have been uploaded to the appliance.

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changes.

Parent topic: Authentication

Configuring one-time password delivery methodsConfiguring one-time password delivery methodsConfiguring one-time password delivery methodsPasswords can be delivered to the user through Short Message Service (SMS) or email. one-time passwordconfiguring deliveryLog in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click the delivery type.SMS One-time PasswordEmail One-time PasswordClick Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the delivery method.SMSBasic Authentication User NameThe user name that is used in HTTP Basic authentication.SMS Delivery does not perform the HTTP basic authentication if this configuration is not specified. Required: FalseMulti-value: NoExample: usernameBasic Authentication PasswordThe password that is used in HTTP basic authentication.SMS Delivery does not perform HTTP Basic authentication if this configuration is not specified.Required: FalseMulti-value: NoExample: passwordConnection URLThe URL of the SMS Gateway where the phone number of the user and the one-time password is sent.Required: TrueMulti-value: NoExample: https://smsgateway.tfim.example.com/HTTP Request ParametersThe list of name and value pairs that is included in the body of the HTTP POST request to the SMS Gateway. In each pair, the name and the value must be separated by equal sign.Two macros, $DEST_NO$ and $MSG$, are replaced by the phone number of the user and the content of the SMS. These two macros can be used only as value in the name and value pair.Required: TrueMulti-value: YesExample: From=+0123456789To= $DEST_NO$Body= $MSG$Success HTTP Response Body Regex PatternThis parameter defines the Java regular-expression pattern that matches the HTTP response body that is returned by the SMS Gateway. When the match is successful, the SMS delivery is successful.The default value is empty.The default behavior is that the HTTP response body is not going to be matched against any Java regular-expression and the success or failure decision is going to be based on the SuccessHTTPReturnCode value only.If the HTTP response from the SMS Gateway does not contain a body, this matching is not performed.Required: FalseMulti-value: NoExample: When the body of all responses by the SMS Gateway contains either Success or Failure followed by no newline character, the sample SuccessHTTPResponseBodyRegexPattern value is Success When the body of all responses by the SMS Gateway contains the following text: MGDID=TTTTTTTTTTTTT RESPONSECODE=NNN SMS=TTTTTTTTTTTTTTTTTTTTTT DATE=NNNNNNNNwhere each line ends with the \n character without any preceding \r character, and the RESPONSECODE is defined such that a three-digit number from 0 to 199 indicates success, the sample SuccessHTTPResponseBodyRegexPattern value is (?s).* RESPONSECODE=(\d{1,2}|[0-1]{1}\d{2})\n.*Success HTTP Return CodeThe response code from the SMS Gateway that is an acknowledgement from the SMS Gateway that the request is successfully processed.The default SuccessHTTPReturnCode, which is 200, is used when this configuration is not specified.The SuccessHTTPReturnCode match must be successful before this matching is done.Required: FalseMulti-value: NoExample: 200HTTPS Trust StoreThe keystore that validates the SMS Gateway SSL certificate. This configuration must be specified only when SMS Delivery communicates with the SMS Gateway by using HTTPS.Required: FalseMulti-value: NoExample: rt_profile_keysClient Authentication KeyThe certificate that is used as client certificate in SSL Client authentication.SMS Delivery does not perform SSL Client authentication if this configuration is not specified.Required: FalseMulti-value: NoExample: rt_profile_keysEmailSender EmailThe email address that is used as the sender of the email that is sent to the user.Required: TrueMulti-value: NoExample: otp_emailer@example.comSMTP Host NameThe host name of the SMTP Server.Required: TrueMulti-value: NoExample: smtpserver.tfim.example.comSMTP User NameThe user name that is used in SMTP authentication.Required: FalseMulti-value: NoExample: usernameSMTP PasswordThe password that is used in SMTP authentication.Required: FalseMulti-value: NoExample: passwordUse SSLUse SSL for the connection to the SMTP server.Required: TrueMulti-value: NoExample: falseClick Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring one-time password delivery methods

Passwords can be delivered to the user through Short Message Service (SMS) or email.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click the delivery type.

SMS One-time Password

Email One-time Password

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the delivery method.

SMS

Basic Authentication User Name

The user name that is used in HTTP Basic authentication.

SMS Delivery does not perform the HTTP basic authentication if this configuration is not specified.

Required: False

Multi-value: No

Example: username

Basic Authentication Password

The password that is used in HTTP basic authentication.

SMS Delivery does not perform HTTP Basic authentication if this configuration is not specified.

Required: False

Multi-value: No

Example: password

Connection URL

The URL of the SMS Gateway where the phone number of the user and the one-time password is sent.

Required: True

Multi-value: No

Example: https://smsgateway.tfim.example.com/

HTTP Request Parameters

The list of name and value pairs that is included in the body of the HTTP POST request to the SMS Gateway. In each pair, the name and the value must be separated by equal sign.

Two macros, $DEST_NO$ and $MSG$, are replaced by the phone number of the user and the content of the SMS. These two macros can be used only as value in the name and value pair.

Required: True

Multi-value: Yes

Example:

From=+0123456789

To= $DEST_NO$

Body= $MSG$

Success HTTP Response Body Regex Pattern

This parameter defines the Java™ regular-expression pattern that matches the HTTP response body that is returned by the SMS Gateway. When the match is successful, the SMS delivery is successful.

The default value is empty.

The default behavior is that the HTTP response body is not going to be matched against any Java regular-expression and the success or failure decision is going to be based on the SuccessHTTPReturnCode value only.

Note: If the HTTP response from the SMS Gateway does not contain a body, this matching is not performed.

Required: False

Multi-value: No

Example:

When the body of all responses by the SMS Gateway contains either Success or Failure followed by no newline character, the sample SuccessHTTPResponseBodyRegexPattern value is

Success

When the body of all responses by the SMS Gateway contains the following text:

MGDID=TTTTTTTTTTTTT
RESPONSECODE=NNN
SMS=TTTTTTTTTTTTTTTTTTTTTT
DATE=NNNNNNNN

where each line ends with the \n character without any preceding \r character, and the RESPONSECODE is defined such that a three-digit number from 0 to 199 indicates success, the sample SuccessHTTPResponseBodyRegexPattern value is

(?s).*
RESPONSECODE=(\d{1,2}|[0-1]{1}\d{2})\n.*

Success HTTP Return Code

The response code from the SMS Gateway that is an acknowledgement from the SMS Gateway that the request is successfully processed.

The default SuccessHTTPReturnCode, which is 200, is used when this configuration is not specified.

Note: The SuccessHTTPReturnCode match must be successful before this matching is done.

Required: False

Multi-value: No

Example: 200

HTTPS Trust Store

The keystore that validates the SMS Gateway SSL certificate.

This configuration must be specified only when SMS Delivery communicates with the SMS Gateway by using HTTPS.

Required: False

Multi-value: No

Example: rt_profile_keys

Client Authentication Key

The certificate that is used as client certificate in SSL Client authentication.

SMS Delivery does not perform SSL Client authentication if this configuration is not specified.

Required: False

Multi-value: No

Example: rt_profile_keys

Email

Sender Email

The email address that is used as the sender of the email that is sent to the user.

Required: True

Multi-value: No

Example: otp_emailer@example.com

SMTP Host Name

The host name of the SMTP Server.

Required: True

Multi-value: No

Example: smtpserver.tfim.example.com

SMTP User Name

The user name that is used in SMTP authentication.

Required: False

Multi-value: No

Example: username

SMTP Password

The password that is used in SMTP authentication.

Required: False

Multi-value: No

Example: password

Use SSL

Use SSL for the connection to the SMTP server.

Required: True

Multi-value: No

Example: false

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changes.

Parent topic: Authentication

Configuring username and password authenticationUser name and password authenticationThe user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository. authentication mechanismconfiguring username and passwordusername and password authenticationconfiguringThis authentication mechanism uses the user registry that is configured as part of the runtime component settings. Ensure that you configured this registry before you use the mechanism. See Managing the runtime componentTo manage configuration files with the local management interface, use the Runtime Component management page..Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click Username Password.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism. LDAP Bind DN An LDAP account with sufficient rights to update the user registry entries. For example: cn=SecurityMaster,secAuthority=Default One method for creating such an account is using the pdadmin command. For example: user create no-password-policy testapi cn=testapi,secAuthority=Default testapi api passw0rd (SecurityGroup ivacld-servers remote-acl-users)Data type: String LDAP Bind PasswordThe LDAP bind password. Data type: StringLDAP Host Name The host name of the LDAP server.Data type: StringLDAP Port The port number of the LDAP server.Data type: StringDefault: 389 Management DomainThe Security Access Manager Management Domain name. This name is used to determine the location of subdomain in the registry. Subdomains are located relative to the Management Domain LDAP location.Data type: StringDefault: Default. SSL EnabledSet this option to true to enable SSL to the LDAP server.Data type: BooleanDefault: False.SSL Trust Store The keystore that contains the trusted CA signers for the LDAP server certificate. Specify an SSL trust store if you use one of the following LDAP registry scenarios for user name and password authentication:You configure one primary LDAP registry which uses SSL.You configure federated directories, where at least one of the directories uses SSL. In this scenario, the Use Federated Directories Configuration property must be set to true.The trust store you specify must be configured to work with any and all of the LDAP registries that use SSL.Data type: StringUse Federated Directories ConfigurationSet this option to true to use the configured federated directories when authenticating a user name and password.If you specify true:The LDAP Host Name and LDAP Port properties must define a Security Access Manager user registry. This is typically the user registry of the runtime component. The users in any of the additional federated directories you configure must exist in the user registry of the runtime component. Therefore, import these users, if necessary. Data type: BooleanDefault: false.User Search FilterAn LDAP search filter that selects any native user entry.Data type: StringDefault: (|(objectclass=ePerson)(objectclass=Person)).Maximum Server ConnectionsThe maximum number of connections that can exist on the LDAP server. Valid values are 2 though 4096.Data type: IntegerDefault: 16.Login Failures PersistentLogin failures are used with the three-strikes policy. If you set this option to false, each process that uses this API stores the number of login failures in memory. If you use multiple appliances in a cluster, the total number of login failures to trigger a strike-out might vary.If you set this option to true, the strike count is stored in LDAP and shared across all servers. An accurate count can be kept in a multiserver environment.Data type: BooleanDefault: False. Click the Attributes tab.Complete any of the following tasks.Add an attribute. Complete the Registry Attribute, Context Name, Context Namespace fields for the attribute.Modify an attribute. Modify the Registry Attribute, Context Name, Context Namespace fields for the attribute. Delete an attribute. Select an attribute and click delete.By default, this mechanism uses the following attributes. These registry attributes are retrieved from the user account in the user registry and are stored in the Session context with the context name and name space. Registry AttributeContext NameContext NamespacemailemailAddressurn:ibm:security:authentication :asf:mechanism:passwordmobilemobileNumberurn:ibm:security:authentication: asf:mechanism:passwordClick Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring username and password authentication

The user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository.

Before you begin

This authentication mechanism uses the user registry that is configured as part of the runtime component settings. Ensure that you configured this registry before you use the mechanism. See Managing the runtime component.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click Username Password.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

LDAP Bind DN

An LDAP account with sufficient rights to update the user registry entries. For example: cn=SecurityMaster,secAuthority=Default

One method for creating such an account is using the pdadmin command. For example:

user create no-password-policy testapi cn=testapi,secAuthority=Default
  testapi api passw0rd (SecurityGroup ivacld-servers remote-acl-users)

Data type: String

LDAP Bind Password

The LDAP bind password.

Data type: String

LDAP Host Name

The host name of the LDAP server.

Data type: String

LDAP Port

The port number of the LDAP server.

Data type: String

Default: 389

Management Domain

The Security Access Manager Management Domain name. This name is used to determine the location of subdomain in the registry. Subdomains are located relative to the Management Domain LDAP location.

Data type: String

Default: Default.

SSL Enabled

Set this option to true to enable SSL to the LDAP server.

Data type: Boolean

Default: False.

SSL Trust Store

The keystore that contains the trusted CA signers for the LDAP server certificate.

Specify an SSL trust store if you use one of the following LDAP registry scenarios for user name and password authentication:

You configure one primary LDAP registry which uses SSL.

You configure federated directories, where at least one of the directories uses SSL. In this scenario, the Use Federated Directories Configuration property must be set to true.

The trust store you specify must be configured to work with any and all of the LDAP registries that use SSL.

Data type: String

Use Federated Directories Configuration

Set this option to true to use the configured federated directories when authenticating a user name and password.

If you specify true:

The LDAP Host Name and LDAP Port properties must define a Security Access Manager user registry. This is typically the user registry of the runtime component.

The users in any of the additional federated directories you configure must exist in the user registry of the runtime component. Therefore, import these users, if necessary.

Data type: Boolean

Default: false.

User Search Filter

An LDAP search filter that selects any native user entry.

Data type: String

Default: (|(objectclass=ePerson)(objectclass=Person)).

Maximum Server Connections

The maximum number of connections that can exist on the LDAP server. Valid values are 2 though 4096.

Data type: Integer

Default: 16.

Login Failures Persistent

Login failures are used with the three-strikes policy. If you set this option to false, each process that uses this API stores the number of login failures in memory. If you use multiple appliances in a cluster, the total number of login failures to trigger a strike-out might vary.

If you set this option to true, the strike count is stored in LDAP and shared across all servers. An accurate count can be kept in a multiserver environment.

Data type: Boolean

Default: False.

Click the Attributes tab.

Complete any of the following tasks.

Add an attribute. Complete the Registry Attribute, Context Name, Context Namespace fields for the attribute.

Modify an attribute. Modify the Registry Attribute, Context Name, Context Namespace fields for the attribute.

Delete an attribute. Select an attribute and click delete.

By default, this mechanism uses the following attributes. These registry attributes are retrieved from the user account in the user registry and are stored in the Session context with the context name and name space.

Registry Attribute | Context Name | Context Namespace
mail | emailAddress | urn:ibm:security:authentication :asf:mechanism:password
mobile | mobileNumber | urn:ibm:security:authentication: asf:mechanism:password

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changes.

Parent topic: Authentication

Configuring an HTTP redirect authentication mechanismConfiguring an HTTP redirect authentication mechanism The HTTP redirect authentication mechanism integrates an external application that you provide to use for authenticating users.authentication mechanismconfiguring HTTP redirectThe external application that you plan to use must exist before you begin this task. The application must meet the following requirements:To indicate a successful authentication, the application must generate a credential with an attribute that matches the Success Credential Attribute Name and Success Credential Attribute Value properties.When the authentication is complete, the application must return control to Security Access Manager by redirecting the browser to the location provided on the ReturnURL query string parameter when the application was invoked. Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click HTTP Redirect Authentication.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism.Redirect URL The URL to the external authentication application.Data type: StringSuccess Credential Attribute NameThe credential attribute name that verifies successful authentication.Data type: StringDefault: httpRedirectAuthCompleted.Success Credential Attribute ValueThe credential attribute value that verifies successful authentication.Data type: StringDefault: true.Click Save.When you configure the mechanism, a message indicates that changes are not deployed. When you finish the changes, deploy them. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring an HTTP redirect authentication mechanism

The HTTP redirect authentication mechanism integrates an external application that you provide to use for authenticating users.

Before you begin

The external application that you plan to use must exist before you begin this task. The application must meet the following requirements:

To indicate a successful authentication, the application must generate a credential with an attribute that matches the Success Credential Attribute Name and Success Credential Attribute Value properties.

When the authentication is complete, the application must return control to Security Access Manager by redirecting the browser to the location provided on the ReturnURL query string parameter when the application was invoked.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click HTTP Redirect Authentication.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Redirect URL

The URL to the external authentication application.

Data type: String

Success Credential Attribute Name

The credential attribute name that verifies successful authentication.

Data type: String

Default: httpRedirectAuthCompleted.

Success Credential Attribute Value

The credential attribute value that verifies successful authentication.

Data type: String

Default: true.

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. When you finish the changes, deploy them. For more information, see Deploying pending changes.

Parent topic: Authentication

Configuring consent to device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.authentication mechanismconfiguring consent to device registrationThe settings of the consent to device registration mechanism specify:Whether to set the authentication level of the user's credential when the consent to device registration is completed.The value to be used to set the authentication level. The authentication level on the credential is used to represent the strength of the authentication that is used to generate the credential.By default, the authentication level is not set by the consent to device registration operation. Use this task to enable setting the authentication level on the user credential. When the authentication level is set, it can be evaluated as part of an access control policy or by the policy enforcement point to grant access to a resource that requires a specific authentication level .Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click Consent to device registration.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism.Set Authentication Level Credential Attribute Enables the consent to device registration authentication to set the authentication level on the session.Data type: BooleanDefault: False.Authentication Level Credential Attribute ValueThe authentication level value to be used when the consent to device registration is configured to set the authentication level. Data type: Integer.Default: 2.Click Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring consent to device registration

Consent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.

About this task

The settings of the consent to device registration mechanism specify:

Whether to set the authentication level of the user's credential when the consent to device registration is completed.

The value to be used to set the authentication level. The authentication level on the credential is used to represent the strength of the authentication that is used to generate the credential.

By default, the authentication level is not set by the consent to device registration operation. Use this task to enable setting the authentication level on the user credential. When the authentication level is set, it can be evaluated as part of an access control policy or by the policy enforcement point to grant access to a resource that requires a specific authentication level .

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click Consent to device registration.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Set Authentication Level Credential Attribute

Enables the consent to device registration authentication to set the authentication level on the session.

Data type: Boolean

Default: False.

Authentication Level Credential Attribute Value

The authentication level value to be used when the consent to device registration is configured to set the authentication level.

Data type: Integer.

Default: 2.

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy changes when you are finished. For more information, see Deploying pending changes.

Parent topic: Authentication

Configuring an End-User License Agreement authentication mechanismConfiguring an End-User License Agreement authentication mechanismConfiguring an End-User License Agreement authentication mechanism The End-User License Agreement authentication mechanism prompts the user to accept an End-User License Agreement (EULA) during an authentication flow.authentication mechanismconfiguring end user license agreementConfigure the End-User License Agreement and the corresponding properties to determine when the mechanism will show the license agreement.When you accept the license, the date that you last accepted the license file is stored. Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click End-User License Agreement.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism. Accept If Last Accepted Date Before If the date the user last accepted the license is before this date, the mechanism requires the user to accept the license again. Data type: Date There is not a default value. Valid values: A date in the following format: YYYY-MM-DD Always Show License Set this option to true so that the mechanism always prompts the user to accept the license file. Data type: Boolean Default value: false License File Specify the path to the license template file to display for the End-User License Agreement. The path to the license file is relative to the locale in the template tree. For more information about how to update the license and add additional license files, see Template filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors. and Template file macrosMost template pages contain one or more macros. The macros are replaced by values that are specific to the action that is requested on the page. Data type: String Default value: /authsvc/authenticator/eula/license.txt License Renewal Term Specify the number of days until the user must accept the license again. When you specify a value that is less than 1, there is not a renewal term. This property compares the date that the user last accepted the license to the current date. The software then determines the number of days since the user last accepted the license. Data type: String Default value: 0 Click Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy them. See Deploying pending changesSome configuration and administration changes require an extra deployment step..Authentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring an End-User License Agreement authentication mechanism

The End-User License Agreement authentication mechanism prompts the user to accept an End-User License Agreement (EULA) during an authentication flow.

About this task

Configure the End-User License Agreement and the corresponding properties to determine when the mechanism will show the license agreement.

Note: When you accept the license, the date that you last accepted the license file is stored.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click End-User License Agreement.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Accept If Last Accepted Date Before

If the date the user last accepted the license is before this date, the mechanism requires the user to accept the license again.

Data type: Date

There is not a default value.

Valid values: A date in the following format: YYYY-MM-DD

Always Show License

Set this option to true so that the mechanism always prompts the user to accept the license file.

Data type: Boolean

Default value: false

License File

Specify the path to the license template file to display for the End-User License Agreement. The path to the license file is relative to the locale in the template tree. For more information about how to update the license and add additional license files, see Template files and Template file macros

Data type: String

Default value: /authsvc/authenticator/eula/license.txt

License Renewal Term

Specify the number of days until the user must accept the license again. When you specify a value that is less than 1, there is not a renewal term. This property compares the date that the user last accepted the license to the current date. The software then determines the number of days since the user last accepted the license.

Data type: String

Default value: 0

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy them. See Deploying pending changes.

Parent topic: Authentication

Related reference:

Authentication policy parameters and credentials

Configuring an Email Message mechanismThe Email Message mechanism provides arbitrary information about a user via either email, webpage, or JSON for consumption by users or applications.Before using the Email Message mechanism, an SMTP server connection must first be configured. For more information about how to configure the SMTP server connection, see Managing server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data..This mechanism can be used in conjunction with the Info Map mechanism. The Info Map mechanism populates some session info and potentially enriches the session further through user mapping. The Email Message mechanism then provides this information to the user via email. For example, for a forgotten username: The user initiates the forgot username flow.The user is prompted to enter his or her email and date of birth.The user provides the details.The Info Map mechanism performs a lookup based on the information and enriches the session with the user name.The Email Message mechanism sends an email that provides the user name to the user. If this mechanism is not used in conjunction with the Info Map mechanism, only information from the Access Manager credential will be made available. To use values in the Access Manager credential or session information added by the Info Map mechanism, add wrapping @ signs to the attribute identifier in the same way as they are used in macros. For example, to make use of a user's credential that contains the attribute firstName in the template page: ... This is the welcome page for @firstName@ ... The attribute identifier is case sensitive. For example, @firstname@ cannot be used to reference the attribute firstName.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click Email Message.Click the Properties tab.Select a property that you want to configure.Click Modify Property.Enter the value for that property.Click OK.Take note of the properties for the mechanism.Email Attribute IdentifierThe name of the attribute that contains the email address to be used. If this attribute is not set, the system always displays the template HTML page to the user. Default value: emailAddressEmail Sender Value The value to use in the sender field of an email.Email TemplateThe path to the template XML file to be used when sending an email to the user. Default value: /authsvc/authenticator/sessionattributeresponse/email_message.xmlThe default value omits the locale portion of the path, which you can see in the templates page view.Error TemplateThe path to the template HTML file to be used when displaying an error message to the user. Default value: /authsvc/authenticator/sessionattributeresponse/error.htmlServer ConnectionThis field defines the SMTP connection that is used to send the email. You can select the SMTP server from the drop-down list.Click Save.After you have configured the mechanism, a message that indicates the changes are not deployed will be displayed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step.. After deploying the changes, you can create policies that include this mechanism. For more information, see Creating an authentication policyUse the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring an Email Message mechanism

The Email Message mechanism provides arbitrary information about a user via either email, webpage, or JSON for consumption by users or applications.

Before you begin

Before using the Email Message mechanism, an SMTP server connection must first be configured. For more information about how to configure the SMTP server connection, see Managing server connections.

About this task

This mechanism can be used in conjunction with the Info Map mechanism. The Info Map mechanism populates some session info and potentially enriches the session further through user mapping. The Email Message mechanism then provides this information to the user via email.

For example, for a forgotten username:

The user initiates the forgot username flow.

The user is prompted to enter his or her email and date of birth.

The user provides the details.

The Info Map mechanism performs a lookup based on the information and enriches the session with the user name.

The Email Message mechanism sends an email that provides the user name to the user.

If this mechanism is not used in conjunction with the Info Map mechanism, only information from the Access Manager credential will be made available.

To use values in the Access Manager credential or session information added by the Info Map mechanism, add wrapping @ signs to the attribute identifier in the same way as they are used in macros. For example, to make use of a user's credential that contains the attribute "firstName" in the template page:

...
This is the welcome page for @firstName@
...

Note: The attribute identifier is case sensitive. For example, @firstname@ cannot be used to reference the attribute firstName.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click Email Message.

Click the Properties tab.

Select a property that you want to configure.

Click Modify Property.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Email Attribute Identifier

The name of the attribute that contains the email address to be used.

If this attribute is not set, the system always displays the template HTML page to the user.

Default value: emailAddress

Email Sender Value

The value to use in the sender field of an email.

Email Template

The path to the template XML file to be used when sending an email to the user.

Default value: /authsvc/authenticator/sessionattributeresponse/email_message.xml

Note: The default value omits the locale portion of the path, which you can see in the templates page view.

Error Template

The path to the template HTML file to be used when displaying an error message to the user.

Default value: /authsvc/authenticator/sessionattributeresponse/error.html

Server Connection

This field defines the SMTP connection that is used to send the email. You can select the SMTP server from the drop-down list.

Click Save.

What to do next

After you have configured the mechanism, a message that indicates the changes are not deployed will be displayed. Deploy changes when you are finished. For more information, see Deploying pending changes.

After deploying the changes, you can create policies that include this mechanism. For more information, see Creating an authentication policy.

Parent topic: Authentication

Configuring the reCAPTCHA Verification authentication mechanismThe reCAPTCHA Verification authentication mechanism provides anti-robot protection.The appliance uses the Google reCAPTCHA service to provide such verification. For more information, see www.google.com/recaptcha. The appliance supports only Google reCAPTCHA V2. Before configuring a reCAPTCHA Verification mechanism, you must first complete the following steps. Ensure that the appliance can connect to www.google.com. You can test the connection in the CLI, for example: myappliance.example.ibm.com:tools> myappliance.example.ibm.com:tools> connect www.google.com:443 Test: www.google.com (address: 216.58.197.68) on port 443 Status: connection was successfulAdd the issuer of the Google CA certificate to the HTTP client default trust store, which is set by the value of the util.httpClient.defaultTrustStore advanced tuning parameter. The default value of the util.httpClient.defaultTrustStore parameter is rt_profile_keys. From the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the rt_profile_keys key database.Select ManageEdit SSL Certificate Database.Select the Signer Certificates tab.Select ManageLoad.Specify the following fields.Server: www.google.com Port:443 Certificate Label: GoogleClick Load.The reCAPTCHA Verification mechanism can provide protection against spam or abuse caused by robots. With this mechanism, the user is presented with a web page that contains a simple Turing test provided by the Google reCAPTCHA API. These tests can distinguish a human user from a robot. You can add this mechanism to your policy to prevent robots from accessing your applications. The following HTML snippet shows an example of embedding the reCAPTCHA mechanism in the template page: <form method="POST" action="@ACTION@"> <input type="hidden" name="operation" value="verify"></input> <div class="g-recaptcha" data-sitekey="@SITE_KEY@"></div> <br> <div class="controls"> <input class="submitButton" id="Submit" name="Submit" type="submit" value="Submit"></input> </div> </form>Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click reCAPTCHA Verification.Click the Properties tab.Select a property that you want to configure.Click Modify Property.Enter the value for that property.Click OK.Take note of the properties for the mechanism.Site KeyThis property is embedded in the HTML template and used to generate the CAPTCHA in the client browser. Default value: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhISecret KeyThis property is used on the server side by the appliance to verify reCAPTCHA responses with Google. Default value: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe The default Site Key and Secret Key values are designated Google test credentials. When these default values are used, all verification requests will pass.Template PageThe path to the template HTML page to be displayed to the user. Default value: /authsvc/authenticator/recaptcha/standalone.htmlClick Save.After you have configured the mechanism, a message that indicates the changes are not deployed will be displayed. Deploy changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step.. After deploying the changes, you can create policies that include this mechanism. For more information, see Creating an authentication policyUse the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring the reCAPTCHA Verification authentication mechanism

The reCAPTCHA Verification authentication mechanism provides anti-robot protection.

Before you begin

The appliance uses the Google reCAPTCHA service to provide such verification. For more information, see www.google.com/recaptcha.

Note: The appliance supports only Google reCAPTCHA V2.

Before configuring a reCAPTCHA Verification mechanism, you must first complete the following steps.

Ensure that the appliance can connect to www.google.com. You can test the connection in the CLI, for example:

myappliance.example.ibm.com:tools>
myappliance.example.ibm.com:tools> connect www.google.com:443
Test:   www.google.com (address: 216.58.197.68) on port 443
Status: connection was successful

Add the issuer of the Google CA certificate to the HTTP client default trust store, which is set by the value of the util.httpClient.defaultTrustStore advanced tuning parameter. The default value of the util.httpClient.defaultTrustStore parameter is rt_profile_keys.

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the rt_profile_keys key database.

Select Manage > Edit SSL Certificate Database.

Select the Signer Certificates tab.

Select Manage > Load.

Specify the following fields.

Server: www.google.com
Port:443
Certificate Label: Google

Click Load.

About this task

The reCAPTCHA Verification mechanism can provide protection against spam or abuse caused by robots. With this mechanism, the user is presented with a web page that contains a simple Turing test provided by the Google reCAPTCHA API. These tests can distinguish a human user from a robot. You can add this mechanism to your policy to prevent robots from accessing your applications.

The following HTML snippet shows an example of embedding the reCAPTCHA mechanism in the template page:

<form method="POST" action="@ACTION@">
      <input type="hidden" name="operation" value="verify"></input>
      <div class="g-recaptcha" data-sitekey="@SITE_KEY@"></div>
      <br>
      <div class="controls">
      <input class="submitButton" id="Submit" name="Submit"
      type="submit" value="Submit"></input>
      </div>
</form>

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click reCAPTCHA Verification.

Click the Properties tab.

Select a property that you want to configure.

Click Modify Property.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Site Key

This property is embedded in the HTML template and used to generate the CAPTCHA in the client browser.

Default value: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI

Secret Key

This property is used on the server side by the appliance to verify reCAPTCHA responses with Google.

Default value: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

Note: The default Site Key and Secret Key values are designated Google test credentials. When these default values are used, all verification requests will pass.

Template Page

The path to the template HTML page to be displayed to the user.

Default value: /authsvc/authenticator/recaptcha/standalone.html

Click Save.

What to do next

After you have configured the mechanism, a message that indicates the changes are not deployed will be displayed. Deploy changes when you are finished. For more information, see Deploying pending changes.

After deploying the changes, you can create policies that include this mechanism. For more information, see Creating an authentication policy.

Parent topic: Authentication

Configuring an Info Map authentication mechanismUse this mechanism in your policy to return a template form and perform validation on the responding POST data. This mechanism is intended to work in conjunction with the Email Message mechanism. The Info Map mechanism can be used to implement JavaScript authentication mechanisms. When this mechanism is invoked, the configured JavaScript mapping rule will be run. If the rule returns FALSE, then a page will be returned to the user. The JavaScript can also define which page to return or it can use a preconfigured page. The JavaScript can also populate any macros on the page and modify what is displayed to the user.If the rule returns TRUE, then the mechanism will return success and the policy will continue. The following parameters are available in an Info Map mapping rule: ContextThis is an authentication service context. It is identical to what is provided in the Authentication Service Credential mapping rule. For more information about how to use the context, see the context attributes section of Authentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.. Use the context to make changes to the credential and the values that the Email Message mechanism will display.StateA state map that is used for the lifetime of this mechanism invocation. Each instance of this mechanism will have a new state map created per invocation of the policy. If the user invokes the policy again, the state map will be empty because the state map is discarded when the rule returns TRUE.PageThe path to the page to be returned. By default, this parameter is set to the value that is configured in the mechanism properties. It can be modified to return a different page. MacrosA map of macros that will be populated on the returned page. SuccessIndicates whether the rule execution was successful. This parameter is set to TRUE if the rule was successful and the policy will continue. It is set to FALSE if the rule was not successful and a page will be returned to a user.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click Info Map Authentication.In the New Authentication Mechanism window, set the name and identifier of the mechanism on the General tab. If you are modifying an existing Info Map authentication mechanism instead of creating a new instance, values on the General tab cannot be changed.Click the Properties tab.Select a property that you want to configure.Click Modify Property.Enter the value for that property.Template PageThis property defines the HTML template page. Mapping RuleSelect a mapping rule from the list. Only JavaScript mapping rules in the InfoMap category are displayed in the list for selection.Click OK.Repeat the previous steps as needed.Click Save.After you have configured the mechanism, a message that indicates the changes are not deployed will be displayed. Deploy the changes when you are finished. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step.. After deploying the changes, you can create policies that include this mechanism. For more information, see Creating an authentication policyUse the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.Embedding reCAPTCHA verification in an Info Map mechanismYou can embed reCAPTCHA verification in Info Map mechanism instances.

Configuring an Info Map authentication mechanism

Use this mechanism in your policy to return a template form and perform validation on the responding POST data. This mechanism is intended to work in conjunction with the Email Message mechanism.

About this task

The Info Map mechanism can be used to implement JavaScript authentication mechanisms. When this mechanism is invoked, the configured JavaScript mapping rule will be run.

If the rule returns FALSE, then a page will be returned to the user. The JavaScript can also define which page to return or it can use a preconfigured page. The JavaScript can also populate any macros on the page and modify what is displayed to the user.

If the rule returns TRUE, then the mechanism will return success and the policy will continue.

The following parameters are available in an Info Map mapping rule:

Context

This is an authentication service context. It is identical to what is provided in the Authentication Service Credential mapping rule. For more information about how to use the context, see the context attributes section of Authentication policy parameters and credentials.

Use the context to make changes to the credential and the values that the Email Message mechanism will display.

State

A state map that is used for the lifetime of this mechanism invocation.

Note: Each instance of this mechanism will have a new state map created per invocation of the policy. If the user invokes the policy again, the state map will be empty because the state map is discarded when the rule returns TRUE.

Page

The path to the page to be returned. By default, this parameter is set to the value that is configured in the mechanism properties. It can be modified to return a different page.

Macros

A map of macros that will be populated on the returned page.

Success

Indicates whether the rule execution was successful. This parameter is set to TRUE if the rule was successful and the policy will continue. It is set to FALSE if the rule was not successful and a page will be returned to a user.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click Info Map Authentication.

In the New Authentication Mechanism window, set the name and identifier of the mechanism on the General tab. If you are modifying an existing Info Map authentication mechanism instead of creating a new instance, values on the General tab cannot be changed.

Click the Properties tab.

Select a property that you want to configure.

Click Modify Property.

Enter the value for that property.

Template Page

This property defines the HTML template page.

Mapping Rule

Select a mapping rule from the list. Only JavaScript mapping rules in the InfoMap category are displayed in the list for selection.

Click OK.

Repeat the previous steps as needed.

Click Save.

What to do next

After you have configured the mechanism, a message that indicates the changes are not deployed will be displayed. Deploy the changes when you are finished. For more information, see Deploying pending changes.

After deploying the changes, you can create policies that include this mechanism. For more information, see Creating an authentication policy.

Embedding reCAPTCHA verification in an Info Map mechanism
You can embed reCAPTCHA verification in Info Map mechanism instances.

Parent topic: Authentication

Embedding reCAPTCHA verification in an Info Map mechanismYou can embed reCAPTCHA verification in Info Map mechanism instances. The Site Key and Secret Key configured in the reCAPTCHA Verification mechanism are made available to the Info Map mechanism via two default macros: @RECAPTCHASITEKEY@ and @RECAPTCHASECRETKEY@. For more information about configuring reCAPTCHA support, see Configuring the reCAPTCHA Verification authentication mechanismThe reCAPTCHA Verification authentication mechanism provides anti-robot protection..In the HTML template:Include the reCAPTCHA JavaScript in the head of your templateInclude the reCAPTCHA element in your formFor example:... <SCRIPT SRC="https://www.google.com/recaptcha/api.js" ASYNC DEFER></SCRIPT> ... <DIV CLASS="g-recaptcha" DATA-SITEKEY="@RECAPTCHASITEKEY@"></DIV> ...In the JavaScript mapping rule:The reCAPTCHA response is received in a request parameter named g-recaptcha-responseVerification can be performed in the JavaScript mapping ruleFor example:importClass(Packages.com.ibm.security.access.recaptcha.RecaptchaClient); ... // Retrieve the reCAPTCHA response from the request. var captchaResponse = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter", "g-recaptcha-response"); // Verify captchaResponse with Google, using @RECAPTCHASECRETKEY@. The third parameter allows you to overload Google's verify endpoint URL, passing null will use the default. var captchaVerified = (captchaResponse != null) && RecaptchaClient.verify(captchaResponse, macros.get("@RECAPTCHASECRETKEY@"), null);Configuring an Info Map authentication mechanismUse this mechanism in your policy to return a template form and perform validation on the responding POST data. This mechanism is intended to work in conjunction with the Email Message mechanism.

Embedding reCAPTCHA verification in an Info Map mechanism

You can embed reCAPTCHA verification in Info Map mechanism instances.

The Site Key and Secret Key configured in the reCAPTCHA Verification mechanism are made available to the Info Map mechanism via two default macros: @RECAPTCHASITEKEY@ and @RECAPTCHASECRETKEY@.

For more information about configuring reCAPTCHA support, see Configuring the reCAPTCHA Verification authentication mechanism.

In the HTML template:

Include the reCAPTCHA JavaScript in the head of your template

Include the reCAPTCHA element in your form

For example:

...
<SCRIPT SRC="https://www.google.com/recaptcha/api.js" ASYNC DEFER></SCRIPT>
...
<DIV CLASS="g-recaptcha" DATA-SITEKEY="@RECAPTCHASITEKEY@"></DIV>
...

In the JavaScript mapping rule:

The reCAPTCHA response is received in a request parameter named g-recaptcha-response

Verification can be performed in the JavaScript mapping rule

For example:

importClass(Packages.com.ibm.security.access.recaptcha.RecaptchaClient);
...
// Retrieve the reCAPTCHA response from the request.
var captchaResponse = context.get(Scope.REQUEST, "urn:ibm:security:asf:request:parameter",
"g-recaptcha-response");
// Verify captchaResponse with Google, using @RECAPTCHASECRETKEY@. The third parameter
allows you to overload Google's verify endpoint URL, passing null will use the default.
var captchaVerified = (captchaResponse != null) && RecaptchaClient.verify(captchaResponse,
macros.get("@RECAPTCHASECRETKEY@"), null);

Parent topic: Configuring an Info Map authentication mechanism

Configuring a Knowledge Questions authentication mechanism Configuring a Knowledge Questions authentication mechanism Configuring a Knowledge Questions authentication mechanism The Knowledge Questions authentication mechanism is an extra step-up authentication measure that uses knowledge questions and answers to authenticate the user.configuration Knowledge Questions authentication mechanismThe user must register answers to the knowledge questions that the mechanism uses during authentication. The mechanism requires users to provide personal information to successfully authenticate. You can use the Knowledge Questions authentication mechanism: With user ID and password authentication to provide two-factor authentication. As a step-up authentication method when the user accesses a high-value resource or performs a high-value transaction.The administrator can configure the mechanism to provide a predetermined list of knowledge questions, or the user can specify and register their own knowledge questions. Typical knowledge questions about the user might include:Mother's maiden name. Name of first grade teacher. Name of favorite pet. Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click Knowledge Questions.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism. Allow User Provided QuestionsSpecify true to specify custom questions as opposed to pre-configured questions.Default value: trueValid values: BooleanAnswer Hashing AlgorithmSpecify this property to indicate the hashing algorithm that the appliance uses to store the knowledge questions for each user. Default value: SHA-256Valid values include the following string values: SHA-1SHA-256SHA-512Answer Hashing EnabledThe mechanism uses a hashing algorithm to store hash values of the answers to the knowledge questions provided by the user instead of storing the actual answers to the knowledge questions. This prevents the administrator from reading the knowledge question answers for the user. Specify False so that the mechanism does not hash the question answer before it stores it.Default value: trueValid values: BooleanCorrect Answers RequiredSpecify the number of correct answers that is required for the authentication to be successful.Default value: 1Valid values: Any positive integer that does not exceed the number of questions that are stored per user.Retry Count Attribute NameSpecify the number of times that a user can submit invalid answers to the knowledge questions. When the user reaches this number, they are unable to authenticate.Default value: user:knowledge:questions:retry:countValid values: StringGrace Period Authentication Count Attribute Name Specify the name of the attribute that is used to record the number of times the user has authenticated during the grace period. The number of times that the user has authenticated during the grace period is stored in the user information database. The mechanism does not require the user to authenticate during the grace period.Default value: user:knowledge:questions:grace:period:countValid values: StringMaximum Amount of Answers StoredSpecify the maximum number of question and answer combinations that the mechanism can store for each user.Default value: 3Valid values: Any positive integer.Maximum Amount of Grace Period AuthenticationsSpecify the maximum number of user authentications that the mechanism permits during the grace period. The mechanism does not require the user to configure knowledge questions during the grace period.Default value: 0Valid values: Any positive integer.Presentation ModeSpecify Individual so that the mechanism presents one knowledge question at a time. When you specify Group, the mechanism presents all of the knowledge questions in one form.Default value: GroupPresentation OrderSpecify Sequential so that the mechanism presents the questions in the order that they are stored. When you specify Random, the mechanism presents the questions in random order.Default value: RandomQuestions Attribute NameSpecify the name of the attribute that is used to store the user knowledge questions in the user information database.Default value: user:knowledge:questionsValid values: StringRetry Protection EnabledSpecify false to disable retry protection.Default value: true Valid values: BooleanRetry Protection Max Number Of AttemptsSpecify the maximum number of times that a user can supply incorrect answers before the mechanism prohibits the user from logging in.Default value: 5Valid values: IntegerRetry TimeoutSpecify the number of seconds that a user must wait before trying to log in again after the user reaches the maximum number of login attempts.Default value: 600Valid values: IntegerUse Exact Answer MatchingSpecify true so that the mechanism performs an exact match when it validates the submitted answer.Default value: falseValid values: BooleanUser Attributes NamespaceSpecify the namespace to be used to store all of the user attributes that are related to the Knowledge Questions authentication mechanism that are stored in the user information database. Default value: urn:ibm:security:authentication:asf:mechanism:knowledge_questionsValid values: String Click Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy them. See Deploying pending changesSome configuration and administration changes require an extra deployment step..Authentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring a Knowledge Questions authentication mechanism

The Knowledge Questions authentication mechanism is an extra step-up authentication measure that uses knowledge questions and answers to authenticate the user.

Before you begin

The user must register answers to the knowledge questions that the mechanism uses during authentication.

About this task

The mechanism requires users to provide personal information to successfully authenticate. You can use the Knowledge Questions authentication mechanism:

With user ID and password authentication to provide two-factor authentication.

As a step-up authentication method when the user accesses a high-value resource or performs a high-value transaction.

The administrator can configure the mechanism to provide a predetermined list of knowledge questions, or the user can specify and register their own knowledge questions. Typical knowledge questions about the user might include:

Mother's maiden name.

Name of first grade teacher.

Name of favorite pet.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click Knowledge Questions.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Allow User Provided Questions

Specify true to specify custom questions as opposed to pre-configured questions.

Default value: true

Valid values: Boolean

Answer Hashing Algorithm

Specify this property to indicate the hashing algorithm that the appliance uses to store the knowledge questions for each user.

Default value: SHA-256

Valid values include the following string values:

SHA-1

SHA-256

SHA-512

Answer Hashing Enabled

The mechanism uses a hashing algorithm to store hash values of the answers to the knowledge questions provided by the user instead of storing the actual answers to the knowledge questions. This prevents the administrator from reading the knowledge question answers for the user. Specify False so that the mechanism does not hash the question answer before it stores it.

Default value: true

Valid values: Boolean

Correct Answers Required

Specify the number of correct answers that is required for the authentication to be successful.

Default value: 1

Valid values: Any positive integer that does not exceed the number of questions that are stored per user.

Retry Count Attribute Name

Specify the number of times that a user can submit invalid answers to the knowledge questions. When the user reaches this number, they are unable to authenticate.

Default value: user:knowledge:questions:retry:count

Valid values: String

Grace Period Authentication Count Attribute Name

Specify the name of the attribute that is used to record the number of times the user has authenticated during the grace period. The number of times that the user has authenticated during the grace period is stored in the user information database. The mechanism does not require the user to authenticate during the grace period.

Default value: user:knowledge:questions:grace:period:count

Valid values: String

Maximum Amount of Answers Stored

Specify the maximum number of question and answer combinations that the mechanism can store for each user.

Default value: 3

Valid values: Any positive integer.

Maximum Amount of Grace Period Authentications

Specify the maximum number of user authentications that the mechanism permits during the grace period. The mechanism does not require the user to configure knowledge questions during the grace period.

Default value: 0

Valid values: Any positive integer.

Presentation Mode

Specify Individual so that the mechanism presents one knowledge question at a time. When you specify Group, the mechanism presents all of the knowledge questions in one form.

Default value: Group

Presentation Order

Specify Sequential so that the mechanism presents the questions in the order that they are stored. When you specify Random, the mechanism presents the questions in random order.

Default value: Random

Questions Attribute Name

Specify the name of the attribute that is used to store the user knowledge questions in the user information database.

Default value: user:knowledge:questions

Valid values: String

Retry Protection Enabled

Specify false to disable retry protection.

Default value: true

Valid values: Boolean

Retry Protection Max Number Of Attempts

Specify the maximum number of times that a user can supply incorrect answers before the mechanism prohibits the user from logging in.

Default value: 5

Valid values: Integer

Retry Timeout

Specify the number of seconds that a user must wait before trying to log in again after the user reaches the maximum number of login attempts.

Default value: 600

Valid values: Integer

Use Exact Answer Matching

Specify true so that the mechanism performs an exact match when it validates the submitted answer.

Default value: false

Valid values: Boolean

User Attributes Namespace

Specify the namespace to be used to store all of the user attributes that are related to the Knowledge Questions authentication mechanism that are stored in the user information database.

Default value: urn:ibm:security:authentication:asf:mechanism:knowledge_questions

Valid values: String

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy them. See Deploying pending changes.

Parent topic: Authentication

Related reference:

Authentication policy parameters and credentials

Configuring a Mobile User Approved authentication mechanismThe Mobile User Approved authentication mechanism prompts the user to sign a random challenge string with a private key that is associated with one of the key values that are provided during the authentication flow.The user must register a compatible authenticator application and enroll an authentication method type of the attached policy that the mechanism uses during authentication.Configure the Mobile User Approved and the corresponding properties to determine the operation of the mechanism.Log in to the local management interface.Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Click Mobile User Approved.Click Modify.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Take note of the properties for the mechanism.Click Save.When you configure the mechanism, a message indicates that changes are not deployed. Deploy them. See Deploying pending changesSome configuration and administration changes require an extra deployment step..Authentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Configuring a Mobile User Approved authentication mechanism

The Mobile User Approved authentication mechanism prompts the user to sign a random challenge string with a private key that is associated with one of the key values that are provided during the authentication flow.

Before you begin

The user must register a compatible authenticator application and enroll an authentication method type of the attached policy that the mechanism uses during authentication.

About this task

Configure the Mobile User Approved and the corresponding properties to determine the operation of the mechanism.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Click Mobile User Approved.

Click Modify.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Take note of the properties for the mechanism.

Click Save.

What to do next

When you configure the mechanism, a message indicates that changes are not deployed. Deploy them. See Deploying pending changes.

Parent topic: Authentication

Related reference:

Authentication policy parameters and credentials

Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.mapping rulesmanagingone-time passwordmanaging mapping rules Use extreme care when you replace mapping rules. Any change that you make to a mapping rule can affect the entire runtime environment. Always export a copy of the original rule you plan to replace so that you have a backup copy. You can customize several components through JavaScript code. For example, you can customize the Authentication Service to modify the content of user credential by modifying the AuthSvcCredential mapping rule. The JavaScript code is run by the Rhino JavaScript engine. Your JavaScript code must conform to JavaScript 1.7. Your JavaScript code is not run under a browser environment. Therefore, you cannot use objects and functions that are available only in a browser environment. You can, however, use standard JavaScript objects (such as Math) and functions (such as parseInt). In addition, your JavaScript code can use white-listed Java classes, which you might need so that you can use operations that are not supported by standard JavaScript functions. You can find the list of these Java classes at JavaScript whitelistAdvanced Access Control JavaScript mapping rules call Java code from JavaScript. The set of classes that can be called are restricted. . To find out more about using Java classes in JavaScript, see the Rhino documentation https://developer.mozilla.org/en/docs/Rhino.Log in to the local management interface.Click Secure Access Control.Under Policy, click Authentication.Click Advanced.Take one of the following actions:View a mapping rule:Select a mapping rule.Click View. The View Mapping Rule panel opens. The content of the mapping rule is displayed.Click OK to close the panel.Export a mapping rule:Select a mapping rule.Click Export.Choose a location and save the file.Replace a mapping rule:Use an existing mapping rule as the basis for the updated mapping rule. When you replace this file, an error in the JavaScript source might be found immediately after it is replaced or it might not be found until the file is run.Select a mapping rule that you want to replace.Click Import. The Replace Mapping Rule panel opens.Click the field or the Browse button and select a file.The name of the mapping rule cannot be replaced. The name of the uploaded file is ignored.Click OK to upload the mapping rule.When you replace a mapping rule, the appliance displays a message that there are undeployed changes. Deploy the changes when you are done. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.Authentication Service Credential mapping ruleThe Authentication Service Credential mapping rule is JavaScript code that you can use to customize the information that is contained in the user credential.OTPGetMethods mapping ruleOTPGetMethods specifies the methods for delivering the one-time password to the user. OTPGenerate mapping ruleOTPGenerate mapping rule specifies the generation of the one-time password for the user.OTPDeliver mapping ruleThe OTPDeliver mapping rule specifies the delivery method of the one-time password to the user. OTPVerify mapping ruleOTPVerify specifies the verification of the one-time password that is submitted by the user.Customizing one-time password mapping rules to use access control context dataSome authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules.

Managing mapping rules

The mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

Before you begin

Attention: Use extreme care when you replace mapping rules. Any change that you make to a mapping rule can affect the entire runtime environment. Always export a copy of the original rule you plan to replace so that you have a backup copy.

About this task

You can customize several components through JavaScript code. For example, you can customize the Authentication Service to modify the content of user credential by modifying the AuthSvcCredential mapping rule.

The JavaScript code is run by the Rhino JavaScript engine. Your JavaScript code must conform to JavaScript 1.7. Your JavaScript code is not run under a browser environment. Therefore, you cannot use objects and functions that are available only in a browser environment. You can, however, use standard JavaScript objects (such as Math) and functions (such as parseInt). In addition, your JavaScript code can use white-listed Java classes, which you might need so that you can use operations that are not supported by standard JavaScript functions. You can find the list of these Java classes at JavaScript whitelist. To find out more about using Java classes in JavaScript, see the Rhino documentation https://developer.mozilla.org/en/docs/Rhino.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Advanced.

Take one of the following actions:

View a mapping rule:

Select a mapping rule.

Click View. The View Mapping Rule panel opens. The content of the mapping rule is displayed.

Click OK to close the panel.

Export a mapping rule:

Select a mapping rule.

Click Export.

Choose a location and save the file.

Replace a mapping rule:

Use an existing mapping rule as the basis for the updated mapping rule.

Attention: When you replace this file, an error in the JavaScript source might be found immediately after it is replaced or it might not be found until the file is run.

Select a mapping rule that you want to replace.

Click Import. The Replace Mapping Rule panel opens.

Click the field or the Browse button and select a file.

Attention: The name of the mapping rule cannot be replaced. The name of the uploaded file is ignored.

Click OK to upload the mapping rule.

What to do next

When you replace a mapping rule, the appliance displays a message that there are undeployed changes. Deploy the changes when you are done. For more information, see Deploying pending changes.

Authentication Service Credential mapping rule
The Authentication Service Credential mapping rule is JavaScript code that you can use to customize the information that is contained in the user credential.

OTPGetMethods mapping rule
OTPGetMethods specifies the methods for delivering the one-time password to the user.

OTPGenerate mapping rule
OTPGenerate mapping rule specifies the generation of the one-time password for the user.

OTPDeliver mapping rule
The OTPDeliver mapping rule specifies the delivery method of the one-time password to the user.

OTPVerify mapping rule
OTPVerify specifies the verification of the one-time password that is submitted by the user.

Customizing one-time password mapping rules to use access control context data
Some authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules.

Parent topic: Authentication

Authentication Service Credential mapping ruleThe Authentication Service Credential mapping rule is JavaScript code that you can use to customize the information that is contained in the user credential.During authentication, the Authentication Service gathers information about the authenticated user, including attributes associated with the user ID. After successful authentication, the Authentication Service provides this information to the Authentication Service Credential mapping rule. The main task of the mapping rule is to modify or add attributes to the user information before it is used to generate a credential. Customizing the mapping rule is an advanced way to customize the credential. To specify basic credential attributes, use an authentication policy and the Credentials panel in the local management interface instead of creating a custom mapping rule. See Creating an authentication policyUse the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy.. If you write your own mapping rule and use it to replace the existing rule, be aware of the following considerations:Credential attributes are string values. For example, user names and lists of groups are string arrays.Do not use spaces, commas, or colons in credential attribute names. Use alphanumeric characters. The sample mapping rule provides more descriptions about considerations for writing your own mapping rule.A default AuthSvcCredential mapping rule is provided. To review the rule:Log in to the local management interface.Click Secure Access Control.Under Policy, click Authentication.Click Advanced.Select AuthSvcCredential.Click Export.Choose a location and save the file. To review an example of a customized credential mapping rule: Log in to the local management interface.Click Manage System Settings.Click File Downloads.Click access_controlexamplesmapping_rules.Select authsvc_credential.js.Click Export to download the file. If you create your own rule, use it to replace the existing rule. See the replacement instructions in Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification..Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

Authentication Service Credential mapping rule

The Authentication Service Credential mapping rule is JavaScript code that you can use to customize the information that is contained in the user credential.

During authentication, the Authentication Service gathers information about the authenticated user, including attributes associated with the user ID. After successful authentication, the Authentication Service provides this information to the Authentication Service Credential mapping rule. The main task of the mapping rule is to modify or add attributes to the user information before it is used to generate a credential.

Customizing the mapping rule is an advanced way to customize the credential. To specify basic credential attributes, use an authentication policy and the Credentials panel in the local management interface instead of creating a custom mapping rule. See Creating an authentication policy.

If you write your own mapping rule and use it to replace the existing rule, be aware of the following considerations:

Credential attributes are string values. For example, user names and lists of groups are string arrays.

Do not use spaces, commas, or colons in credential attribute names. Use alphanumeric characters.

The sample mapping rule provides more descriptions about considerations for writing your own mapping rule.

A default AuthSvcCredential mapping rule is provided. To review the rule:

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Advanced.

Select AuthSvcCredential.

Click Export.

Choose a location and save the file.

To review an example of a customized credential mapping rule:

Log in to the local management interface.

Click Manage System Settings.

Click File Downloads.

Click access_control > examples > mapping_rules.

Select authsvc_credential.js.

Click Export to download the file.

If you create your own rule, use it to replace the existing rule. See the replacement instructions in Managing mapping rules.

Parent topic: Managing mapping rules

OTPGetMethods mapping ruleOTPGetMethods mapping ruleOTPGetMethods mapping ruleOTPGetMethods specifies the methods for delivering the one-time password to the user. mapping rulesOTPGetMethodsone-time passworddelivery methodOTPGetMethodsusageThis sample mapping rule sets password delivery conditions for the following delivery methods:By emailBy SMSNo deliveryEach delivery method includes the following attributes and their corresponding value:idSpecifies a unique delivery method ID. This value replaces the @OTP_METHOD_ID@ macro in the OTP Method Selection page. Use a unique value across different methods. For example, sms.deliveryTypeSpecifies the delivery plug-in that delivers the one-time password. The value must match one of the types in the DeliveryTypesToOTPDeliveryModuleIds parameter of the OTP response file. For example, sms_delivery.deliveryAttributeSpecifies an attribute that is associated with the delivery type. The value depends on the one-time password provider plug-in for the delivery type. For example: For SMS delivery, the value is the mobile number of the user. For example, mobileNumber.For email delivery, the value is the email address of the user. For example, emailAddress.For no delivery, the value is an empty string.labelSpecifies the unique delivery method to the user. For time-based and counter-based one-time password, use this attribute to specify the secret key of the user. If label is not specified, the time-based and counter-based one-time password code retrieves the key by invoking the user information provider plug-in. This parameter replaces the @OTP_METHOD_LABEL@ macro in the OTP Method Selection page.otpTypeSpecifies the one-time password provider plug-in that generates and verifies the password. The value must match one of the types in the OTPTypesToOTPProviderModuleIds parameter of the OTP response file. For example, mac_otp.userInfoTypeSpecifies which user information provider plug-in to use to retrieve user information that is required to calculate the one-time password. This parameter is only required if user information is used for calculation of the one-time password.To customize one-time password delivery, you can do one of the following actions:Create your own mapping rules that are based on the sample OTPGetMethods mapping rule.Modify the sample OTPGetMethods mapping rule.You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context dataSome authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules..Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

OTPGetMethods mapping rule

OTPGetMethods specifies the methods for delivering the one-time password to the user.

This sample mapping rule sets password delivery conditions for the following delivery methods:

By email

By SMS

No delivery

Each delivery method includes the following attributes and their corresponding value:

id

Specifies a unique delivery method ID. This value replaces the @OTP_METHOD_ID@ macro in the OTP Method Selection page. Use a unique value across different methods. For example, sms.

deliveryType

Specifies the delivery plug-in that delivers the one-time password. The value must match one of the types in the DeliveryTypesToOTPDeliveryModuleIds parameter of the OTP response file. For example, sms_delivery.

deliveryAttribute

Specifies an attribute that is associated with the delivery type. The value depends on the one-time password provider plug-in for the delivery type. For example:

For SMS delivery, the value is the mobile number of the user. For example, mobileNumber.

For email delivery, the value is the email address of the user. For example, emailAddress.

For no delivery, the value is an empty string.

label

Specifies the unique delivery method to the user. For time-based and counter-based one-time password, use this attribute to specify the secret key of the user. If label is not specified, the time-based and counter-based one-time password code retrieves the key by invoking the user information provider plug-in. This parameter replaces the @OTP_METHOD_LABEL@ macro in the OTP Method Selection page.

otpType

Specifies the one-time password provider plug-in that generates and verifies the password. The value must match one of the types in the OTPTypesToOTPProviderModuleIds parameter of the OTP response file. For example, mac_otp.

userInfoType

Specifies which user information provider plug-in to use to retrieve user information that is required to calculate the one-time password. This parameter is only required if user information is used for calculation of the one-time password.

To customize one-time password delivery, you can do one of the following actions:

Create your own mapping rules that are based on the sample OTPGetMethods mapping rule.

Modify the sample OTPGetMethods mapping rule.

You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context data.

Parent topic: Managing mapping rules

OTPGenerate mapping ruleOTPGenerate mapping ruleOTPGenerate mapping ruleOTPGenerate mapping rule specifies the generation of the one-time password for the user.mapping rulesOTPGenerateOTPGenerateusageYou can use the OTPGenerate mapping rule in the following configuration:Modify the one-time password type of the selected method to generate the one-time passwordIndicates the one-time password type to determine the one-time password Provider plug-in that generates the one-time password for the user.See the comments in the mapping rule for more details.You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context dataSome authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules..Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

OTPGenerate mapping rule

OTPGenerate mapping rule specifies the generation of the one-time password for the user.

You can use the OTPGenerate mapping rule in the following configuration:

Modify the one-time password type of the selected method to generate the one-time password

Indicates the one-time password type to determine the one-time password Provider plug-in that generates the one-time password for the user.

Note: See the comments in the mapping rule for more details.

You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context data.

Parent topic: Managing mapping rules

OTPDeliver mapping ruleOTPDeliver mapping ruleOTPDeliver mapping ruleThe OTPDeliver mapping rule specifies the delivery method of the one-time password to the user. mapping rulesOTPDeliverOTPDeliverusageUse the following OTPDeliver mapping rules: Generate the one-time password hintThe one-time password hint is a sequence of characters that is associated with the one-time password. The one-time password hint is displayed in the One-Time Password Login page. It is also sent to the user together with the one-time password.You can customize the way the one-time password hint is generated by modifying the following section in the default OTPDeliver mapping rule:var otpHint = Math.floor(1000 + (Math.random() * 9000));See the comments in the mapping rule for more details. Generate the formatted one-time passwordThe formatted one-time password is the formatted version of the one-time password. The formatted one-time password, instead of the actual one-time password, is sent to the user. For example, for one-time password hint abcd, and one-time password 12345678, you can set the formatted one-time password as abcd-12345678. For one-time password hint efgh, and one-time password87654321, you can set the one-time password as efgh#8765#4321.You can customize the way that the one-time password is generated by modifying the following section in the sample OTPDeliver mapping rule:var otpFormatted = otpHint + "-" + otp;See the comments in the mapping rule for more details.Modify the delivery type of the selected method for delivering the one-time passwordThe delivery type specifies the one-time password Delivery plug-in that delivers the one-time password to the user. Modify the delivery attribute of the selected method to deliverThe delivery attribute is an attribute that is associated with delivery type. The meaning of the delivery attribute depends on the one-time password provider plug-in for the delivery type. For example, for SMS delivery type, the delivery attribute is the mobile number of the user. For email delivery type, the delivery attribute is the email address of the user.See the comments in the mapping rule for more details.You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context dataSome authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules..Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

OTPDeliver mapping rule

The OTPDeliver mapping rule specifies the delivery method of the one-time password to the user.

Use the following OTPDeliver mapping rules:

Generate the one-time password hint

The one-time password hint is a sequence of characters that is associated with the one-time password. The one-time password hint is displayed in the One-Time Password Login page. It is also sent to the user together with the one-time password.

You can customize the way the one-time password hint is generated by modifying the following section in the default OTPDeliver mapping rule:

var otpHint = Math.floor(1000 + (Math.random() * 9000));

Note: See the comments in the mapping rule for more details.

Generate the formatted one-time password

The formatted one-time password is the formatted version of the one-time password. The formatted one-time password, instead of the actual one-time password, is sent to the user. For example, for one-time password hint abcd, and one-time password 12345678, you can set the formatted one-time password as abcd-12345678. For one-time password hint efgh, and one-time password87654321, you can set the one-time password as efgh#8765#4321.

You can customize the way that the one-time password is generated by modifying the following section in the sample OTPDeliver mapping rule:

var otpFormatted = otpHint + "-" + otp;

Note: See the comments in the mapping rule for more details.

Modify the delivery type of the selected method for delivering the one-time password

The delivery type specifies the one-time password Delivery plug-in that delivers the one-time password to the user.

Modify the delivery attribute of the selected method to deliver

The delivery attribute is an attribute that is associated with delivery type. The meaning of the delivery attribute depends on the one-time password provider plug-in for the delivery type. For example, for SMS delivery type, the delivery attribute is the mobile number of the user. For email delivery type, the delivery attribute is the email address of the user.

Note: See the comments in the mapping rule for more details.

You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context data.

Parent topic: Managing mapping rules

OTPVerify mapping ruleOTPVerify mapping ruleOTPVerify mapping ruleOTPVerify specifies the verification of the one-time password that is submitted by the user.mapping rulesOTPVerifyOTPVerifyusageYou can customize the sample OTPVerify mapping rule to modify the following verification rules:Modify the one-time password type of the userIndicates the one-time password type to determine the one-time Provider plug-in that verifies the one-time submitted by the user.Set the authentication level of the userAfter one-time password authentication completes, a credential is issued that contains the authentication level of the user. You can customize the authentication level by modifying the following section in the mapping rule:var authenticationLevel = contextAttributesAttributeContainer.getAttributeValueByNameAndType ("otp.otp-callback.authentication-level", "otp.otp-callback.type"); var attributeAuthenticationLevel = new Attribute("AUTHENTICATION_LEVEL", "urn:ibm:names:ITFIM:5.1:accessmanager", authenticationLevel); attributeContainer.setAttribute(attributeAuthenticationLevel);Enforce the number of times the user can submit the one-time password in the one-time password login pageIf a user exceeds the permitted number of times to submit a one-time password, an error message displays. You can customize the number of times that the user can submit the one-time password in the one-time password login page by modifying the following section in the mapping rule:var retryLimit = 5;By default, this option is set to false. This setting applies only to MAC OTP.Identify the secret key of a userWhen a user registers with a time-based one-time password application, they are assigned a secret key. Store the secret key in this mapping rule for verification of the user by modifying the following code: var secretStr = new java.lang.String(SECRET_KEY_GOES_HERE);By default, this option is set to false. Override the one-time password target URLBy default, a user is redirected to a target URL upon completion of an one-time password flow. That target URL was either the initial cached request at the WebSEAL or reverse proxy instance or was specified as part of the one-time password invocation using the Target query string parameter. You can use the OTPVerify mapping rule to override this target URL by adding an attribute called itfim_override_targeturl_attr. This attribute ensures that at the completion of a successful one-time password flow, the user is redirected to the override target instead of the initial target. Example code:var targetUrl = new java.lang.String("http://www.example.com/url"); var targetUrlAttr = new Attribute("itfim_override_targeturl_attr", "urn:ibm:names:ITFIM:5.1:accessmanager", targetUrl); attributeContainer.setAttribute(targetUrlAttr);To customize one-time password verification, you can do one of the following actions:Create your own verification rules that are based on the sample OTPVerify mapping rule.Modify the sample OTPVerify mapping rule.You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context dataSome authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules..Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

OTPVerify mapping rule

OTPVerify specifies the verification of the one-time password that is submitted by the user.

You can customize the sample OTPVerify mapping rule to modify the following verification rules:

Modify the one-time password type of the user

Indicates the one-time password type to determine the one-time Provider plug-in that verifies the one-time submitted by the user.

Set the authentication level of the user

After one-time password authentication completes, a credential is issued that contains the authentication level of the user. You can customize the authentication level by modifying the following section in the mapping rule:

var authenticationLevel = contextAttributesAttributeContainer.getAttributeValueByNameAndType
       ("otp.otp-callback.authentication-level", "otp.otp-callback.type");
var attributeAuthenticationLevel = new Attribute("AUTHENTICATION_LEVEL",
       "urn:ibm:names:ITFIM:5.1:accessmanager", authenticationLevel);
attributeContainer.setAttribute(attributeAuthenticationLevel);

Enforce the number of times the user can submit the one-time password in the one-time password login page

If a user exceeds the permitted number of times to submit a one-time password, an error message displays. You can customize the number of times that the user can submit the one-time password in the one-time password login page by modifying the following section in the mapping rule:

var retryLimit = 5;

By default, this option is set to false.

Note: This setting applies only to MAC OTP.

Identify the secret key of a user

When a user registers with a time-based one-time password application, they are assigned a secret key. Store the secret key in this mapping rule for verification of the user by modifying the following code:

var secretStr = new java.lang.String(SECRET_KEY_GOES_HERE);

By default, this option is set to false.

Override the one-time password target URL

By default, a user is redirected to a target URL upon completion of an one-time password flow. That target URL was either the initial cached request at the WebSEAL or reverse proxy instance or was specified as part of the one-time password invocation using the Target query string parameter.

You can use the OTPVerify mapping rule to override this target URL by adding an attribute called itfim_override_targeturl_attr. This attribute ensures that at the completion of a successful one-time password flow, the user is redirected to the override target instead of the initial target. Example code:

var targetUrl = new java.lang.String("http://www.example.com/url");
var targetUrlAttr = new Attribute("itfim_override_targeturl_attr",
"urn:ibm:names:ITFIM:5.1:accessmanager", targetUrl);
attributeContainer.setAttribute(targetUrlAttr);

To customize one-time password verification, you can do one of the following actions:

Create your own verification rules that are based on the sample OTPVerify mapping rule.

Modify the sample OTPVerify mapping rule.

You can also customize the mapping rule to use access control context data. For details see, Customizing one-time password mapping rules to use access control context data.

Parent topic: Managing mapping rules

Customizing one-time password mapping rules to use access control context dataCustomizing one-time password mapping rules to use access control context dataCustomizing one-time password mapping rules to use access control context dataSome authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules.mapping rulescustomizing for context dataYou can configure Security Access Manager to perform access control policy evaluation when a resource is accessed. The access control policy evaluation can result on a permit with authentication. The required authentication is determined by the access control policy. Some scenarios require that the context data used to perform the access control decision be available during the authentication. In order to provide access to the access control context data, you can persist the context information for the predefined authentication obligations that perform one-time password authentication. The context data available is limited to the attributes referenced by the access control policy and the request attributes provided by the policy enforcement point. If the policy relies on the risk score to perform access control, the context data available also includes the risk-profile attributes.Log in to the local management interface.Click Secure Access ControlGlobal SettingsAdvanced Configuration.Select attributeCollection.authenticationContextAttributes.Click edit icon for the property.In the text field, enter a list of comma separated attribute names to be collected during the authorization policy evaluation. For example, if your scenario requires the authentication level and host of the request the configuration property, enter authenticationLevel, http:host.The access control context data is provided to the one-time password mapping rules as context attributes values. The following format is used:<stsuuser:Attribute name="AttributeName-AttributeURI" type=""authn.service.context.attribute.type.AttributeDatatype"> <stsuuser:Value>AttributeValue</stsuuser:Value> </stsuuser:Attribute>Where: name is the attribute name and attribute identifier separated by a dash (-).type is the attribute data type prefixed by authn.service.context.attribute.type.For example the authenticationLevel attribute value is added as: <stsuuser:Attribute name="authenticationlevel-urn-ibm: security:subject:authenticationlevel" type="authn.service.context.attribute.type.Integer">     <stsuuser:Value>1</stsuuser:Value> </stsuuser:Attribute>Click OK.When you edit a property, a message indicates that there are undeployed changes. If you have finished making changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Configure the mapping rule to use the information collected by this property as the context attribute.Click Secure Access Control.Under Policy, click Authentication.Click Advanced.Select and export the mapping rule.Use a text editor and modify the rule to access the attributes collected during the access control policy evaluation in the following format:var accessControlAttribute = contextAttributesAttributeContainer.getAttributeValueByNameAndType ("AttributeName-AttributeURI", "authn.service.context.attribute.type.AttributeDatatype");Where: name is the attribute name and attribute identifier separated by a dash (-).type is the attribute data type prefixed by authn.service.context.attribute.type.For example, the authenticationLevel attribute can be obtained using the following information:var accessControlAuthenticationLevel = contextAttributesAttributeContainer.getAttributeValueByNameAndType ("authenticationlevel-urn-ibm:security:subject:authenticationlevel", "authn.service.context.attribute.type.Integer");Save the mapping rule and take note of its location.In the local management interface, click Secure Access Control.Under Policy, click Authentication.Click Advanced.Select the mapping rule you want to replace.Click Replace. The Replace Mapping Rule panel opens.Click the field or the Browse button and select the file for your saved mapping rule. The name of the mapping rule cannot be replaced. The name of the uploaded file is ignored.Click OK to upload the mapping rule.Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.

Customizing one-time password mapping rules to use access control context data

Some authentication scenarios require that context data used in making an access control decision be available during authentication. You can configure Security Access Manager to capture the content data and make it available to the one-time password mapping rules.

About this task

You can configure Security Access Manager to perform access control policy evaluation when a resource is accessed. The access control policy evaluation can result on a permit with authentication. The required authentication is determined by the access control policy. Some scenarios require that the context data used to perform the access control decision be available during the authentication. In order to provide access to the access control context data, you can persist the context information for the predefined authentication obligations that perform one-time password authentication.

Note: The context data available is limited to the attributes referenced by the access control policy and the request attributes provided by the policy enforcement point. If the policy relies on the risk score to perform access control, the context data available also includes the risk-profile attributes.

Procedure

Log in to the local management interface.

Click Secure Access Control > Global Settings > Advanced Configuration.

Select attributeCollection.authenticationContextAttributes.

Click edit icon for the property.

In the text field, enter a list of comma separated attribute names to be collected during the authorization policy evaluation. For example, if your scenario requires the authentication level and host of the request the configuration property, enter authenticationLevel, http:host. The access control context data is provided to the one-time password mapping rules as context attributes values. The following format is used:

<stsuuser:Attribute name="AttributeName-AttributeURI"
  type=""authn.service.context.attribute.type.AttributeDatatype">
<stsuuser:Value>AttributeValue</stsuuser:Value>
</stsuuser:Attribute>

Where:

name is the attribute name and attribute identifier separated by a dash (-).

type is the attribute data type prefixed by authn.service.context.attribute.type.

For example the authenticationLevel attribute value is added as:

<stsuuser:Attribute name="authenticationlevel-urn-ibm:
   security:subject:authenticationlevel"
   type="authn.service.context.attribute.type.Integer">
<stsuuser:Value>1</stsuuser:Value>
</stsuuser:Attribute>

Click OK.

When you edit a property, a message indicates that there are undeployed changes. If you have finished making changes, deploy them.

For more information, see Deploying pending changes.

Configure the mapping rule to use the information collected by this property as the context attribute.

Click Secure Access Control.

Under Policy, click Authentication.

Click Advanced.

Select and export the mapping rule.

Use a text editor and modify the rule to access the attributes collected during the access control policy evaluation in the following format:

var accessControlAttribute =
contextAttributesAttributeContainer.getAttributeValueByNameAndType
("AttributeName-AttributeURI",
"authn.service.context.attribute.type.AttributeDatatype");

Where:

name is the attribute name and attribute identifier separated by a dash (-).

type is the attribute data type prefixed by authn.service.context.attribute.type.

For example, the authenticationLevel attribute can be obtained using the following information:

var accessControlAuthenticationLevel =
contextAttributesAttributeContainer.getAttributeValueByNameAndType
("authenticationlevel-urn-ibm:security:subject:authenticationlevel",
"authn.service.context.attribute.type.Integer");

Save the mapping rule and take note of its location.

In the local management interface, click Secure Access Control.

Under Policy, click Authentication.

Click Advanced.

Select the mapping rule you want to replace.

Click Replace. The Replace Mapping Rule panel opens.

Click the field or the Browse button and select the file for your saved mapping rule.

Attention: The name of the mapping rule cannot be replaced. The name of the uploaded file is ignored.

Click OK to upload the mapping rule.

Parent topic: Managing mapping rules

One-time password and authentication template filesThe one-time password and authentication methods rely on HTML pages to interact with users, such as displaying errors or prompting users to provide a password or pin or to indicate the method by which they want to receive the password. You can customize these pages using the one-time password and authentication template files.For information about one-time password and authentication template files, see Template filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors..AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

One-time password and authentication template files

The one-time password and authentication methods rely on HTML pages to interact with users, such as displaying errors or prompting users to provide a password or pin or to indicate the method by which they want to receive the password. You can customize these pages using the one-time password and authentication template files.

For information about one-time password and authentication template files, see Template files.

Parent topic: Authentication

Push notification registrationSecurity Access Manager supports push notifications on both iOS and Android platforms.To issue a notification to a client device, a specific payload must be generated and sent to the push notification service of the device's platform (Apple Push Notification Service or Firebase Cloud Messaging). This notification request requires a form of authentication and authorization. To establish a trusted connection, Apple Push Notification Service requires a provider certificate and Firebase Cloud Messaging requires a server (API) key. As an administrator, you must register such forms of authentication for your authenticator applications to successfully deliver push notifications to clients on demand. Such registration can be done through either the local management interface or the RESTful API. For details about how to register push notification endpoints through the RESTful API, see the RESTful API documentation. For certificate-based push notification registration, use a specific SSL certificate database for this purpose and import all required certificates to the SSL certificate database before registration.Log in to the local management interface. Click Secure Access Control.Under Manage, click Push Notification Providers.Adding a push notification providerClick Add.Provide values for the displayed fields.Mobile PlatformSpecifies whether the push notification is for iOS or Android platform.Application IDIdentifier of the application.Push Provider HostHost name to be used to connect to the push service provider. The value can include port number, for example, fcm.googleapis.com:443. Push ProviderIf iOS Application is selected in the Mobile Platform field, this option becomes available. You can select either Firebase (Google's push notification provider) or Apple (Apple's push notification service). Server KeyIf Android Application is selected in the Mobile Platform field or Firebase is selected as the Push Provider when iOS Application is selected in the Mobile Platform field, then this text field becomes available to enter the Server API Key to be used for authentication. Certificate StoreIf iOS Application is selected in the Mobile Platform field and Apple is selected as the Push Provider, then this field becomes available to select the certificate store on the appliance that contains the certificate to be used to authenticate to the Apple push notification service.Certificate LabelIf iOS Application is selected in the Mobile Platform field and Apple is selected as the Push Provider, then this field becomes available to select the certificate to be used to authenticate to the Apple push notification service.Click Save.Deploy the changes.Modifying a push notification providerSelect the push notification provider to be modified.Click Edit.Change the settings as needed.Click Save.Deploy the changes.AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.

Push notification registration

Security Access Manager supports push notifications on both iOS and Android platforms.

About this task

To issue a notification to a client device, a specific payload must be generated and sent to the push notification service of the device's platform (Apple Push Notification Service or Firebase Cloud Messaging). This notification request requires a form of authentication and authorization. To establish a trusted connection, Apple Push Notification Service requires a provider certificate and Firebase Cloud Messaging requires a server (API) key.

As an administrator, you must register such forms of authentication for your authenticator applications to successfully deliver push notifications to clients on demand. Such registration can be done through either the local management interface or the RESTful API. For details about how to register push notification endpoints through the RESTful API, see the RESTful API documentation.

Note: For certificate-based push notification registration, use a specific SSL certificate database for this purpose and import all required certificates to the SSL certificate database before registration.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Manage, click Push Notification Providers.

Adding a push notification provider

Click Add.

Provide values for the displayed fields.

Mobile Platform

Specifies whether the push notification is for iOS or Android platform.

Application ID

Identifier of the application.

Push Provider Host

Host name to be used to connect to the push service provider. The value can include port number, for example, fcm.googleapis.com:443.

Push Provider

If iOS Application is selected in the Mobile Platform field, this option becomes available. You can select either Firebase (Google's push notification provider) or Apple (Apple's push notification service).

Server Key

If Android Application is selected in the Mobile Platform field or Firebase is selected as the Push Provider when iOS Application is selected in the Mobile Platform field, then this text field becomes available to enter the Server API Key to be used for authentication.

Certificate Store

If iOS Application is selected in the Mobile Platform field and Apple is selected as the Push Provider, then this field becomes available to select the certificate store on the appliance that contains the certificate to be used to authenticate to the Apple push notification service.

Certificate Label

If iOS Application is selected in the Mobile Platform field and Apple is selected as the Push Provider, then this field becomes available to select the certificate to be used to authenticate to the Apple push notification service.

Click Save.

Deploy the changes.

Modifying a push notification provider

Select the push notification provider to be modified.

Click Edit.

Change the settings as needed.

Click Save.

Deploy the changes.

Parent topic: Authentication

OAuth 2.0 supportOAuth 2.0 supportOverview: OAuth 2.0Advanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.Oauth supportOAuth is an HTTP-based authorization protocol. It gives third-party applications scoped access to a protected resource on behalf of the resource owner. It gives scoped access by creating an approval interaction between the resource owner, client, and the resource server. It gives users the ability to share their private resources between sites without providing user names and passwords. Private resources can be anything, but common examples include photos, videos, and contact lists.For a complete description of the OAuth 2.0 specifications, see the OAuth websitehttp://www.oauth.net.The OAuth 2.0 implementation of Advanced Access Control also integrates with WebSphere DataPower. For more information, see DataPower Integration.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.OAuth 2.0 conceptsThis topic introduces the main concepts of OAuth 2.0.OAuth 2.0 endpointsEndpoints provide OAuth clients the ability to communicate with the OAuth server or authorization server within a definition.OAuth 2.0 workflowThe OAuth 2.0 support in IBM Security Access Manager provides four different ways for an OAuth client to obtain access the protected resource.State management The state_id parameter in the STSUniversalUser module is used as a key to store or retrieve state information for each invocation of the trust chain of an OAuth flow.Trusted clients managementAdvanced Access Control stores trusted client information that is based on the decisions of a resource owner on which clients to trust.Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client. Managing OAuth 2.0 mapping rulesUse the mapping rules to customize the methods for the OAuth 2.0 flow. OAuth 2.0 mapping rule methodsCustomize the PreTokenGeneration and PostTokenGeneration mapping rules using these methods.Customizing OAuth tokens by updating the sample PreTokenGeneration mapping ruleYou can customize the format of the tokens that are issued by your OAuth definition. OAuth 2.0 token limitsYou can define limits on the number of OAuth tokens per user per definition so that the high-volume database does not go beyond capacity.OAuth 2.0 template filesThe OAuth process relies on HTML pages to interact with users, such as displaying errors or prompting users to provide information. You can customize these pages through the OAuth template files.Error responsesAn HTTP response indicates the type of error that has occurred when an action in an authorization process fails. The error responses described here are only applicable to Policy Enforcement Point (PEP) error responses. User self-administration tasks for OAuthAdministrators can configure OAuth to enable users to perform certain self-management tasks.OAuth STS Interface for Authorization Enforcement PointsUse the WS-Trust interface to directly contact an OAuth Security Token Service (STS) trust chain in Security Access Manager to validate a request for an OAuth protected resource. An OAuth enforcement point intercepts requests for OAuth protected resources. The OAuth enforcement point also validates the request with Security Access Manager, and passes the request through, if it is valid. If the request is not valid, the enforcement point denies access to the protected resource.

OAuth 2.0 support

Advanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

OAuth is an HTTP-based authorization protocol. It gives third-party applications scoped access to a protected resource on behalf of the resource owner. It gives scoped access by creating an approval interaction between the resource owner, client, and the resource server. It gives users the ability to share their private resources between sites without providing user names and passwords. Private resources can be anything, but common examples include photos, videos, and contact lists.

For a complete description of the OAuth 2.0 specifications, see the OAuth websitehttp://www.oauth.net.

The OAuth 2.0 implementation of Advanced Access Control also integrates with WebSphere DataPower. For more information, see DataPower Integration.

OAuth 2.0 concepts
This topic introduces the main concepts of OAuth 2.0.

OAuth 2.0 endpoints
Endpoints provide OAuth clients the ability to communicate with the OAuth server or authorization server within a definition.

OAuth 2.0 workflow
The OAuth 2.0 support in IBM Security Access Manager provides four different ways for an OAuth client to obtain access the protected resource.

State management
The state_id parameter in the STSUniversalUser module is used as a key to store or retrieve state information for each invocation of the trust chain of an OAuth flow.

Trusted clients management
Advanced Access Control stores trusted client information that is based on the decisions of a resource owner on which clients to trust.

Configuring API protection
The API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Managing OAuth 2.0 mapping rules
Use the mapping rules to customize the methods for the OAuth 2.0 flow.

OAuth 2.0 mapping rule methods
Customize the PreTokenGeneration and PostTokenGeneration mapping rules using these methods.

Customizing OAuth tokens by updating the sample PreTokenGeneration mapping rule
You can customize the format of the tokens that are issued by your OAuth definition.

OAuth 2.0 token limits
You can define limits on the number of OAuth tokens per user per definition so that the high-volume database does not go beyond capacity.

OAuth 2.0 template files
The OAuth process relies on HTML pages to interact with users, such as displaying errors or prompting users to provide information. You can customize these pages through the OAuth template files.

Error responses
An HTTP response indicates the type of error that has occurred when an action in an authorization process fails. The error responses described here are only applicable to Policy Enforcement Point (PEP) error responses.

User self-administration tasks for OAuth
Administrators can configure OAuth to enable users to perform certain self-management tasks.

OAuth STS Interface for Authorization Enforcement Points
Use the WS-Trust interface to directly contact an OAuth Security Token Service (STS) trust chain in Security Access Manager to validate a request for an OAuth protected resource. An OAuth enforcement point intercepts requests for OAuth protected resources. The OAuth enforcement point also validates the request with Security Access Manager, and passes the request through, if it is valid. If the request is not valid, the enforcement point denies access to the protected resource.

Parent topic: Advanced Access Control configuration

OAuth 2.0 conceptsThis topic introduces the main concepts of OAuth 2.0.OAuth 2.0authorization code specifications OAuthresource owner OAuthclientsOAuthserversOAuthaccess token OAuthprotected resource OAuthresource server OAuthauthorization grant OAuthauthorization code OAuthThe following concepts are generally used in OAuth 2.0.Resource owner An entity capable of authorizing access to a protected resource. When the resource owner is a person, it is called an user.OAuth client A third-party application that wants access to the private resources of the resource owner. The OAuth client can make protected resource requests on behalf of the resource owner after the resource owner grants it authorization. OAuth 2.0 introduces two types of clients: confidential and public. Confidential clients are registered with a client secret, while public clients are not.OAuth serverKnown as the Authorization server in OAuth 2.0. The server that gives OAuth clients scoped access to a protected resource on behalf of the resource owner. The server issues an access token to the OAuth client after it successfully does the following actions: Authenticates the resource owner.Validates a request or an authorization grant.Obtains resource owner authorization. An authorization server can also be the resource server. Access tokenA string that represents authorization granted to the OAuth client by the resource owner. This string represents specific scopes and durations of access. It is granted by the resource owner and enforced by the OAuth server. Protected resourceA restricted resource that can be accessed from the OAuth server using authenticated requests.Resource serverThe server that hosts the protected resources. It can use access tokens to accept and respond to protected resource requests. The resource server might be the same server as the authorization server.Authorization grantA grant that represents the resource owner authorization to access its protected resources. OAuth clients use an authorization grant to obtain an access token. There are four authorization grant types: authorization code, implicit, resource owner password credentials, and client credentials.Authorization codeA code that the Authorization server generates when the resource owner authorizes a request.Refresh token A string that is used to obtain a new access token.A refresh token is optionally issued by the authorization server to the OAuth client together with an access token. The OAuth client can use the refresh token to request another access token that is based on the same authorization, without involving the resource owner again.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

OAuth 2.0 concepts

This topic introduces the main concepts of OAuth 2.0.

The following concepts are generally used in OAuth 2.0.

Resource owner

An entity capable of authorizing access to a protected resource. When the resource owner is a person, it is called an user.

OAuth client

A third-party application that wants access to the private resources of the resource owner. The OAuth client can make protected resource requests on behalf of the resource owner after the resource owner grants it authorization. OAuth 2.0 introduces two types of clients: confidential and public. Confidential clients are registered with a client secret, while public clients are not.

OAuth server

Known as the Authorization server in OAuth 2.0. The server that gives OAuth clients scoped access to a protected resource on behalf of the resource owner. The server issues an access token to the OAuth client after it successfully does the following actions:

Authenticates the resource owner.

Validates a request or an authorization grant.

Obtains resource owner authorization.

An authorization server can also be the resource server.

Access token

A string that represents authorization granted to the OAuth client by the resource owner. This string represents specific scopes and durations of access. It is granted by the resource owner and enforced by the OAuth server.

Protected resource

A restricted resource that can be accessed from the OAuth server using authenticated requests.

Resource server

The server that hosts the protected resources. It can use access tokens to accept and respond to protected resource requests. The resource server might be the same server as the authorization server.

Authorization grant

A grant that represents the resource owner authorization to access its protected resources. OAuth clients use an authorization grant to obtain an access token. There are four authorization grant types: authorization code, implicit, resource owner password credentials, and client credentials.

Authorization code

A code that the Authorization server generates when the resource owner authorizes a request.

Refresh token

A string that is used to obtain a new access token.

A refresh token is optionally issued by the authorization server to the OAuth client together with an access token. The OAuth client can use the refresh token to request another access token that is based on the same authorization, without involving the resource owner again.

Parent topic: OAuth 2.0 support

OAuth 2.0 endpointsOAuth 2.0 endpointsOAuth 2.0 endpointsEndpoints provide OAuth clients the ability to communicate with the OAuth server or authorization server within a definition.endpointsOAuthdefinitionsendpointsOAuthURLsOAuthendpointsfederationOAuth 2.0namingfederationOAuth 2.0endpoint definitionsfederationOAuth 2.0URIsOAuth 2.0endpointdefinitionsOAuth 2.0endpointURLsAll endpoints can be accessed through URLs. The syntax of the URLs is specific to the purpose of the access.If you are responsible for installing and configuring the appliance, you might find it helpful to be familiar with these endpoints and URLs.API protection definitionsThe API protection definitions naming follows the standard Advanced Access Control naming convention. The syntax is: https://<hostname:port>/<junction>/sps/oauth/oauth20 For example: https://server.oauth.com/mga/sps/oauth/oauth20The following table describes the endpoints that are used in an API protection definition. There is only a single set of endpoints.Not all authorization grant types use all three endpoints in a single OAuth 2.0 flow.OAuth 2.0 endpoint definitions and URLsEndpoint nameDescriptionExampleAuthorization endpointAn authorization URL where the resource owner grants authorization to the OAuth client to access the protected resource.https://server.oauth.com/mga/sps/oauth/oauth20/authorizeToken endpointA token request URL where the OAuth client exchanges an authorization grant for an access token and an optional refresh token.https://server.oauth.com/mga/sps/oauth/oauth20/tokenClients manager endpointA URL for resource owners to manage their trusted clients.The resource owner can use the clients manager endpoint to access and modify the list of clients that are authorized to access the protected resource. The trusted clients manager shows the client name and permitted scope of an authorized client.The list does not show clients that are disabled or deleted from the definition.The resource owner can optionally remove trusted client information from the list. In doing so, the resource owner is prompted for consent to authorize the next time the OAuth client attempts to access the protected resource. https://server.oauth.com/mga/sps/oauth/oauth20/clientsSession endpointA URL where an access_token can be exchanged for a web session. The client uses the endpoint to obtain an authenticated web session for the resource owner that is typically used in hybrid mobile application scenarios. The session endpoint is disabled by default and can be enabled by using advanced configuration.The client must send a POST request with the access_token in the body.POST /mga/sps/oauth/oauth20/session HTTP/1.1Host: server.oauth.com Content-Type: application/x-www-form-urlencoded access_token=abc123... https://server.oauth.com/mga/sps/oauth/oauth20/sessionAuthorization grant management endpoint A URL where you can view your authorization grants and the tokens and attributes of each authorization grant.http://server.oauth.com/mga/sps/mga/user/mgmt/html/device/device_selection.htmlLogout endpointA URL where you can end a session by revoking an access_token. The token must be provided in the Authorization header or a session cookie must be used.http://server.oauth.com/mga/sps/oauth/oauth20/logoutOAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

OAuth 2.0 endpoints

Endpoints provide OAuth clients the ability to communicate with the OAuth server or authorization server within a definition.

All endpoints can be accessed through URLs. The syntax of the URLs is specific to the purpose of the access.

If you are responsible for installing and configuring the appliance, you might find it helpful to be familiar with these endpoints and URLs.

API protection definitions

The API protection definitions naming follows the standard Advanced Access Control naming convention. The syntax is:

https://<hostname:port>/<junction>/sps/oauth/oauth20

For example:

https://server.oauth.com/mga/sps/oauth/oauth20

The following table describes the endpoints that are used in an API protection definition.

Notes:

There is only a single set of endpoints.

Not all authorization grant types use all three endpoints in a single OAuth 2.0 flow.

Table 78. OAuth 2.0 endpoint definitions and URLs

Endpoint name
Description
Example

Authorization endpoint
An authorization URL where the resource owner grants authorization to the OAuth client to access the protected resource.
https://server.oauth.com/mga/sps/oauth/oauth20/authorize

Token endpoint
A token request URL where the OAuth client exchanges an authorization grant for an access token and an optional refresh token.
https://server.oauth.com/mga/sps/oauth/oauth20/token

Clients manager endpoint

A URL for resource owners to manage their trusted clients.

The resource owner can use the clients manager endpoint to access and modify the list of clients that are authorized to access the protected resource. The trusted clients manager shows the client name and permitted scope of an authorized client.

Note: The list does not show clients that are disabled or deleted from the definition.

The resource owner can optionally remove trusted client information from the list. In doing so, the resource owner is prompted for consent to authorize the next time the OAuth client attempts to access the protected resource.

https://server.oauth.com/mga/sps/oauth/oauth20/clients

Session endpoint

A URL where an access_token can be exchanged for a web session. The client uses the endpoint to obtain an authenticated web session for the resource owner that is typically used in hybrid mobile application scenarios.

Note: The session endpoint is disabled by default and can be enabled by using advanced configuration.

The client must send a POST request with the access_token in the body.

POST /mga/sps/oauth/oauth20/session HTTP/1.1Host: server.oauth.com
Content-Type: application/x-www-form-urlencoded
access_token=abc123...

https://server.oauth.com/mga/sps/oauth/oauth20/session

Authorization grant management endpoint

A URL where you can view your authorization grants and the tokens and attributes of each authorization grant.

http://server.oauth.com/mga/sps/mga/user/mgmt/html/device/device_selection.html

Logout endpoint
A URL where you can end a session by revoking an access_token. The token must be provided in the Authorization header or a session cookie must be used.
http://server.oauth.com/mga/sps/oauth/oauth20/logout

Parent topic: OAuth 2.0 support

OAuth 2.0 workflowOAuth 2.0 workflowWorkflow: OAuth 2.0The OAuth 2.0 support in IBM Security Access Manager provides four different ways for an OAuth client to obtain access the protected resource.OAuth 2.0overviewOAuth 2.0aboutOAuth 2.0workflowOAuth 2.0conceptOAuth 2.0 workflowAdvanced Access Control supports the following OAuth 2.0 workflows.Authorization code flow The authorization code grant type is suitable for OAuth clients that can keep their client credentials confidential when authenticating with the authorization server. For example, a client implemented on a secure server. As a redirection-based flow, the OAuth client must be able to interact with the user agent of the resource owner. It also must be able to receive incoming requests through redirection from the authorization server.The authorization code workflow diagram involves the following steps:The OAuth client initiates the flow when it directs the user agent of the resource owner to the authorization endpoint. The OAuth client includes its client identifier, requested scope, local state, and a redirection URI. The authorization server sends the user agent back to the redirection URI after access is granted or denied.The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.If the resource owner grants access, the OAuth client uses the redirection URI provided earlier to redirect the user agent back to the OAuth client. The redirection URI includes an authorization code and any local state previously provided by the OAuth client.The OAuth client requests an access token from the authorization server through the token endpoint. The OAuth client authenticates with its client credentials and includes the authorization code received in the previous step. The OAuth client also includes the redirection URI used to obtain the authorization code for verification.The authorization server validates the client credentials and the authorization code. The server also ensures that the redirection URI received matches the URI used to redirect the client in Step 3. If valid, the authorization server responds back with an access token.The authorization server can be the same server as the resource server or a separate entity. A single authorization server can issue access tokens accepted by multiple resource servers.Authorization code flow with refresh tokenThe authorization code workflow with refresh token diagram involves the following steps:The OAuth client requests an access token by authenticating with the authorization server with its client credentials, and presenting an authorization grant.The authorization server validates the client credentials and the authorization grant. If valid, the authorization server issues an access token and a refresh token.The OAuth client makes a protected resource request to the resource server by presenting the access token.The resource server validates the access token. If the access token is valid, the resource owner serves the request.Repeat steps 3 and 4 until the access token expires. If the OAuth client knows that the access token has expired, skip to Step 7. Otherwise, the OAuth client makes another protected resource request.If access token is not valid, the resource server returns an error.The OAuth client requests a new access token by authenticating with the authorization server with its client credentials, and presenting the refresh token.The authorization server validates the client credentials and the refresh token, and if valid, issues a new access token and a new refresh token.Implicit grant flowThe implicit grant type is suitable for clients that are not capable of maintaining their client credentials confidential for authenticating with the authorization server. An example can be in the form of client applications that are in a user agent, typically implemented in a browser using a scripting language such as JavaScript. As a redirection-based flow, the OAuth client must be able to interact with the user agent of the resource owner, typically a web browser. The OAuth client must also be able to receive incoming requests through redirection from the authorization server.The implicit grant workflow diagram involves the following steps:The OAuth client initiates the flow by directing the user agent of the resource owner to the authorization endpoint. The OAuth client includes its client identifier, requested scope, local state, and a redirection URI. The authorization server sends the user agent back to the redirection URI after access is granted or denied.The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.If the resource owner grants access, the authorization server redirects the user agent back to the client using the redirection URI provided earlier. The redirection URI includes the access token in the URI fragment.The user agent follows the redirection instructions by making a request to the web server without the fragment. The user agent retains the fragment information locally.The web server returns a web page, which is typically an HTML document with an embedded script. The web page accesses the full redirection URI including the fragment retained by the user agent. It can also extract the access token and other parameters contained in the fragment.The user agent runs the script provided by the web server locally, which extracts the access token and passes it to the client.Resource owner password credentials flowThe resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client. For example, the resource owner can be a computer operating system of the OAuth client or a highly privileged application. You can only use this grant type when the OAuth client has obtained the credentials of the resource owner. It is also used to migrate existing clients using direct authentication schemes by converting the stored credentials to an access token.The resource owner password credentials workflow diagram involves the following steps:The resource owner provides the client with its user name and password.The OAuth client requests an access token from the authorization server through the token endpoint. The OAuth client authenticates with its client credentials and includes the credentials received from the resource owner.After the authorization server validates the resource owner credentials and the client credentials, it issues an access token and optionally a refresh token.JWT and SAML bearer grant type flowsThe assertion bearer grant types are an extension to the OAuth 2.0 framework. In such flows, a client presents a JWT or SAML assertion to the token endpoint in exchange for tokens. The assertion that is presented must represent the resource owner for whom tokens will be issued to. See RFC 7522 and RFC 7523 for further details. The assertions must be validated in the pre-token mapping rule. A callout to the STS is one way to validate a presented assertion.The following diagram describes the steps in the assertion bearer grant type flows:The client obtains a JWT or SAML assertion from the resource owner. The client presents the assertion to the authorization server.The authorization server validates the presented assertion through signature validation, decryption, or both. The issuer and subject are extracted and validated. If the issuer is trusted, tokens are issued to the subject that is captured in the assertion. Client credentials flowThe client credentials flow is used when the OAuth client requests an access token using only its client credentials. This flow is applicable in one of the following situations: The OAuth client is requesting access to the protected resources under its control.The OAuth client is requesting access to a different protected resource, where authorization has been previously arranged with the authorization server.The client credentials workflow diagram involves the following steps:The OAuth client requests an access token from the token endpoint by authenticating with its client credentials.After the authorization server validates the client credentials, it issues an access token.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.Client authentication considerations at the OAuth 2.0 token endpointThe OAuth 2.0 token endpoint is used for direct communications between an OAuth client and the authorization server. The token endpoint is used to obtain an OAuth token.Configuring an authenticated token endpoint with WebSEAL as the point of contactConfigure an authenticated token endpoint with WebSEAL as the point of contact to delegate authentication of the client to WebSEAL.

OAuth 2.0 workflow

The OAuth 2.0 support in IBM Security Access Manager provides four different ways for an OAuth client to obtain access the protected resource.

OAuth 2.0 workflow

Advanced Access Control supports the following OAuth 2.0 workflows.

Authorization code flow

The authorization code grant type is suitable for OAuth clients that can keep their client credentials confidential when authenticating with the authorization server. For example, a client implemented on a secure server. As a redirection-based flow, the OAuth client must be able to interact with the user agent of the resource owner. It also must be able to receive incoming requests through redirection from the authorization server.

The authorization code workflow diagram involves the following steps:

The OAuth client initiates the flow when it directs the user agent of the resource owner to the authorization endpoint. The OAuth client includes its client identifier, requested scope, local state, and a redirection URI. The authorization server sends the user agent back to the redirection URI after access is granted or denied.

The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.

If the resource owner grants access, the OAuth client uses the redirection URI provided earlier to redirect the user agent back to the OAuth client. The redirection URI includes an authorization code and any local state previously provided by the OAuth client.

The OAuth client requests an access token from the authorization server through the token endpoint. The OAuth client authenticates with its client credentials and includes the authorization code received in the previous step. The OAuth client also includes the redirection URI used to obtain the authorization code for verification.

The authorization server validates the client credentials and the authorization code. The server also ensures that the redirection URI received matches the URI used to redirect the client in Step 3. If valid, the authorization server responds back with an access token.

The authorization server can be the same server as the resource server or a separate entity. A single authorization server can issue access tokens accepted by multiple resource servers.

Authorization code flow with refresh token

The authorization code workflow with refresh token diagram involves the following steps:

The OAuth client requests an access token by authenticating with the authorization server with its client credentials, and presenting an authorization grant.

The authorization server validates the client credentials and the authorization grant. If valid, the authorization server issues an access token and a refresh token.

The OAuth client makes a protected resource request to the resource server by presenting the access token.

The resource server validates the access token. If the access token is valid, the resource owner serves the request.

Repeat steps 3 and 4 until the access token expires. If the OAuth client knows that the access token has expired, skip to Step 7. Otherwise, the OAuth client makes another protected resource request.

If access token is not valid, the resource server returns an error.

The OAuth client requests a new access token by authenticating with the authorization server with its client credentials, and presenting the refresh token.

The authorization server validates the client credentials and the refresh token, and if valid, issues a new access token and a new refresh token.

Implicit grant flow

The implicit grant type is suitable for clients that are not capable of maintaining their client credentials confidential for authenticating with the authorization server. An example can be in the form of client applications that are in a user agent, typically implemented in a browser using a scripting language such as JavaScript.

As a redirection-based flow, the OAuth client must be able to interact with the user agent of the resource owner, typically a web browser. The OAuth client must also be able to receive incoming requests through redirection from the authorization server.

The implicit grant workflow diagram involves the following steps:

The OAuth client initiates the flow by directing the user agent of the resource owner to the authorization endpoint. The OAuth client includes its client identifier, requested scope, local state, and a redirection URI. The authorization server sends the user agent back to the redirection URI after access is granted or denied.

The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.

If the resource owner grants access, the authorization server redirects the user agent back to the client using the redirection URI provided earlier. The redirection URI includes the access token in the URI fragment.

The user agent follows the redirection instructions by making a request to the web server without the fragment. The user agent retains the fragment information locally.

The web server returns a web page, which is typically an HTML document with an embedded script. The web page accesses the full redirection URI including the fragment retained by the user agent. It can also extract the access token and other parameters contained in the fragment.

The user agent runs the script provided by the web server locally, which extracts the access token and passes it to the client.

Resource owner password credentials flow

The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client. For example, the resource owner can be a computer operating system of the OAuth client or a highly privileged application.

You can only use this grant type when the OAuth client has obtained the credentials of the resource owner. It is also used to migrate existing clients using direct authentication schemes by converting the stored credentials to an access token.

The resource owner password credentials workflow diagram involves the following steps:

The resource owner provides the client with its user name and password.

The OAuth client requests an access token from the authorization server through the token endpoint. The OAuth client authenticates with its client credentials and includes the credentials received from the resource owner.

After the authorization server validates the resource owner credentials and the client credentials, it issues an access token and optionally a refresh token.

JWT and SAML bearer grant type flows

The assertion bearer grant types are an extension to the OAuth 2.0 framework. In such flows, a client presents a JWT or SAML assertion to the token endpoint in exchange for tokens. The assertion that is presented must represent the resource owner for whom tokens will be issued to. See RFC 7522 and RFC 7523 for further details.

The assertions must be validated in the pre-token mapping rule. A callout to the STS is one way to validate a presented assertion.

The following diagram describes the steps in the assertion bearer grant type flows:

The client obtains a JWT or SAML assertion from the resource owner.

The client presents the assertion to the authorization server.

The authorization server validates the presented assertion through signature validation, decryption, or both. The issuer and subject are extracted and validated. If the issuer is trusted, tokens are issued to the subject that is captured in the assertion.

Client credentials flow

The client credentials flow is used when the OAuth client requests an access token using only its client credentials. This flow is applicable in one of the following situations:

The OAuth client is requesting access to the protected resources under its control.

The OAuth client is requesting access to a different protected resource, where authorization has been previously arranged with the authorization server.

The client credentials workflow diagram involves the following steps:

The OAuth client requests an access token from the token endpoint by authenticating with its client credentials.

After the authorization server validates the client credentials, it issues an access token.

Client authentication considerations at the OAuth 2.0 token endpoint
The OAuth 2.0 token endpoint is used for direct communications between an OAuth client and the authorization server. The token endpoint is used to obtain an OAuth token.

Configuring an authenticated token endpoint with WebSEAL as the point of contact
Configure an authenticated token endpoint with WebSEAL as the point of contact to delegate authentication of the client to WebSEAL.

Parent topic: OAuth 2.0 support

Client authentication considerations at the OAuth 2.0 token endpointClient authentication considerations at the OAuth 2.0 token endpointClient authentication considerations at the OAuth 2.0 token endpointThe OAuth 2.0 token endpoint is used for direct communications between an OAuth client and the authorization server. The token endpoint is used to obtain an OAuth token.authenticationclientOAuth 2.0token endpoint client authenticationclient authenticationOAuth 2.0 token endpointclient authenticationtypespoint of contacttoken endpointcertificatesclientclient certificatesThe client type, whether public or confidential, determines the authentication requirements of the OAuth 2.0 token endpoint. The Advanced Access Control runtime is responsible for authenticating the client by using the client_id and client_secret in sending the request.OAuth 2.0 workflows for confidential clients that require client authentication at the token endpoint, can be configured in one of the following ways:The Advanced Access Control point of contact requires authentication at the token endpoint:The point of contact is responsible for authenticating the client.The Confidential check box from the client instance panel is not relevant. A client_secret parameter must not be sent in the token endpoint request.If a client_id parameter is sent in the request, it must match the identity of the client that is authenticated by the point of contact. The Advanced Access Control point of contact permits unauthenticated access to the token endpoint: The client_id parameter in the token endpoint request is used to identify the client.The Confidential check box from the client instance panel determines whether a client_secret parameter is required in the token endpoint request. A client secret is required for confidential clients only.When enforcing client authentication at the token endpoint, the point of contact must contain the client ID and client secret within its user registry. The point of contact must be able to map the authenticated user credential to the client_id parameter sent in the OAuth 2.0 token endpoint request.Based on this information, the following configurations are supported:Configurations supportedClient typesConfigurationsWebSEAL point of contact token endpoint URI considerationsCheck box setting for the Confidential parameterConfidential clientsThe point of contact performs client authentication.Authenticated ACL on token endpoint is required. Token endpoint port must match WebSEAL port. N/AConfidential clientsThe client_id and client_secret parameters in the token endpoint request are used to perform client authentication.Unauthenticated ACL on token endpoint is required.Token endpoint port must match WebSEAL port.Must be cleared.Public clientsThe client_id parameter is used to perform client validation.Unauthenticated ACL on token endpoint is required.Token endpoint port must match the WebSEAL port. Must be selected.OAuth 2.0 workflowThe OAuth 2.0 support in IBM Security Access Manager provides four different ways for an OAuth client to obtain access the protected resource.

Client authentication considerations at the OAuth 2.0 token endpoint

The OAuth 2.0 token endpoint is used for direct communications between an OAuth client and the authorization server. The token endpoint is used to obtain an OAuth token.

The client type, whether public or confidential, determines the authentication requirements of the OAuth 2.0 token endpoint. The Advanced Access Control runtime is responsible for authenticating the client by using the client_id and client_secret in sending the request.

OAuth 2.0 workflows for confidential clients that require client authentication at the token endpoint, can be configured in one of the following ways:

The Advanced Access Control point of contact requires authentication at the token endpoint:

The point of contact is responsible for authenticating the client.

The Confidential check box from the client instance panel is not relevant. A client_secret parameter must not be sent in the token endpoint request.

If a client_id parameter is sent in the request, it must match the identity of the client that is authenticated by the point of contact.

The Advanced Access Control point of contact permits unauthenticated access to the token endpoint:

The client_id parameter in the token endpoint request is used to identify the client.

The Confidential check box from the client instance panel determines whether a client_secret parameter is required in the token endpoint request. A client secret is required for confidential clients only.

Note: When enforcing client authentication at the token endpoint, the point of contact must contain the client ID and client secret within its user registry. The point of contact must be able to map the authenticated user credential to the client_id parameter sent in the OAuth 2.0 token endpoint request.

Based on this information, the following configurations are supported:

Table 79. Configurations supported

Client types
Configurations
WebSEAL point of contact token endpoint URI considerations
Check box setting for the Confidential parameter

Confidential clients
The point of contact performs client authentication.

Authenticated ACL on token endpoint is required.

Token endpoint port must match WebSEAL port.

N/A

Confidential clients
The client_id and client_secret parameters in the token endpoint request are used to perform client authentication.

Unauthenticated ACL on token endpoint is required.

Token endpoint port must match WebSEAL port.

Must be cleared.

Public clients
The client_id parameter is used to perform client validation.

Unauthenticated ACL on token endpoint is required.

Token endpoint port must match the WebSEAL port.

Must be selected.

Parent topic: OAuth 2.0 workflow

Configuring an authenticated token endpoint with WebSEAL as the point of contact Configure authenticated token endpoint with WebSEAL as point of contactWebSEAL as point of contact configurationConfigure an authenticated token endpoint with WebSEAL as the point of contact to delegate authentication of the client to WebSEAL.WebSEALconfiguringWebSEALpoint of contactWebSEALtoken endpointWhen you want WebSEAL to do client authentication, you must attach an authenticated ACL on the token endpoint. You can use the isam_mobile_anyauth ACL that the isamcfg creates when you run the isamcfg tool. For more information, see Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool..You must also know how to enable Basic Authentication and Certificate Authentication. For more information, see Basic authentication and Client-side certificate authentication. Use separate WebSEAL instances for the token and authorization endpoints to enforce authentication at WebSEAL for the token endpoint. Clients can authenticate with authentication mechanisms, such as Basic Authentication and Client Certificates. At the same time, users can authenticate by using forms authentication at the authorize and clients manager endpoints. Log in to the pdadmin utility with the sec_master account.Attach the isam_mobile_anyauth ACL to the token endpoint /WebSEAL/<WebSEAL_instance_name>/mga/sps/oauth/oauth20/token. For example, acl attach /WebSEAL/server-default/mga/sps/oauth/oauth20/token isam_mobile_anyauth Enable Basic Authentication, Certificate Authentication, or both. Ensure that the point of contact contains the client ID and client secret within its user registry by running the following command: user list * 0 Verify the configuration:Ensure that the token endpoint is protected. For example, run the following command and verify that you get a login form:curl -kv https://server:445/mga/sps/oauth/oauth20/tokenIf you enabled Basic Authentication or Certificate authentication, ensure that you can authenticate to the point of contact with the Basic Authentication header or Client Certificate. For example, run the following commands and ensure that you can reach the token endpoint:Basic Authenticationcurl -kv https://server:445/mga/sps/oauth/oauth20/token --basic -u jHTzyil9lQAcFsJu9Dw3:CDrQlexadocQ6FwTzEUG Certificate Authenticationcurl -kv https://server:445/mga/sps/oauth/oauth20/token --cert /path/to/cert.pem OAuth 2.0 workflowThe OAuth 2.0 support in IBM Security Access Manager provides four different ways for an OAuth client to obtain access the protected resource.

Configuring an authenticated token endpoint with WebSEAL as the point of contact

Configure an authenticated token endpoint with WebSEAL as the point of contact to delegate authentication of the client to WebSEAL.

Before you begin

When you want WebSEAL to do client authentication, you must attach an authenticated ACL on the token endpoint. You can use the isam_mobile_anyauth ACL that the isamcfg creates when you run the isamcfg tool. For more information, see Using the isamcfg tool.

You must also know how to enable Basic Authentication and Certificate Authentication. For more information, see Basic authentication and Client-side certificate authentication.

About this task

Use separate WebSEAL instances for the token and authorization endpoints to enforce authentication at WebSEAL for the token endpoint. Clients can authenticate with authentication mechanisms, such as Basic Authentication and Client Certificates. At the same time, users can authenticate by using forms authentication at the authorize and clients manager endpoints.

Procedure

Log in to the pdadmin utility with the sec_master account.

Attach the isam_mobile_anyauth ACL to the token endpoint /WebSEAL/<WebSEAL_instance_name>/mga/sps/oauth/oauth20/token. For example,

acl attach /WebSEAL/server-default/mga/sps/oauth/oauth20/token isam_mobile_anyauth

Enable Basic Authentication, Certificate Authentication, or both.

Ensure that the point of contact contains the client ID and client secret within its user registry by running the following command:

user list * 0

Verify the configuration:

Ensure that the token endpoint is protected. For example, run the following command and verify that you get a login form:

curl -kv https://server:445/mga/sps/oauth/oauth20/token

If you enabled Basic Authentication or Certificate authentication, ensure that you can authenticate to the point of contact with the Basic Authentication header or Client Certificate. For example, run the following commands and ensure that you can reach the token endpoint:

Basic Authentication

curl -kv https://server:445/mga/sps/oauth/oauth20/token
--basic -u jHTzyil9lQAcFsJu9Dw3:CDrQlexadocQ6FwTzEUG

Certificate Authentication

curl -kv https://server:445/mga/sps/oauth/oauth20/token
--cert /path/to/cert.pem

Parent topic: OAuth 2.0 workflow

State managementOAuth state managementLearn the concept behind state management for OAuth 2.0. The state_id parameter in the STSUniversalUser module is used as a key to store or retrieve state information for each invocation of the trust chain of an OAuth flow.state management OAuth 2.0OAuth 2.0state managementAdvance Access Control provides sample mapping rules. These sample mapping rules use state management API and are applicable to OAuth 2.0 protocols. You can get the sample mapping rules from the File downloads section.OAuth 2.0OAuth 2.0 tokens, such as grants, access tokens, and refresh tokens, have a state_id parameter that is used in Security Token Service mapping rules. The state_id parameter maintains state between associated Security Token Service calls in an OAuth 2.0 flow.The OAuth 2.0 mapping rule uses the state_id as the key to issue an authorization grant. The key is used to add the token storage time to a cache. The storage time is then retrieved from the cache during a request for a protected resource. Figure 1 shows a section of the sample JavaScript mapping rule for OAuth 2.0.OAuth 2.0 JavaScript sample code with state management ... var request_type = null; var grant_type = null; // The request type - if none available assume 'resource' temp_attr = stsuu.getContextAttributes().getAttributeValuesByNameAndType("request_type", "urn:ibm:names:ITFIM:oauth:request"); if (temp_attr != null && temp_attr.length > 0) { request_type = temp_attr[0]; } else { request_type = "resource"; } // The grant type temp_attr = stsuu.getContextAttributes().getAttributeValuesByNameAndType("grant_type", "urn:ibm:names:ITFIM:oauth:body:param"); if (temp_attr != null && temp_attr.length > 0) { grant_type = temp_attr[0]; } /* The following demonstrates the use of the state management API. * * request_type = 'authorization' ==> Store the UTC time of the request into a cache with state_id as key [authorization_code, implicit] * request_type = 'access_token' && grant_type = 'client_credentials' ==> Store the UTC time of the request into a cache with state_id as key [client_credentials] * request_type = 'access_token' && grant_type = 'password' ==> Store the UTC time of the request into a cache with state_id as key [password] * request_type = 'resource' ==> Retrieve the stored time and put it into an attribute named recovered_state * * It also stores the flow type we are in be used later to detect if this is a client_credentials two-legged flow or not. */ if (request_type == "authorization" || (request_type == "access_token" && ( grant_type == "client_credentials" || grant_type == "password" ))) { var curr_utc_time = "State storage time was: " + IDMappingExtUtils.getCurrentTimeStringUTC(); IDMappingExtUtils.getIDMappingExtCache().put(state_id, curr_utc_time, 1000); } else if (request_type == "resource") { var recovered_state = IDMappingExtUtils.getIDMappingExtCache().get(state_id); if (recovered_state != null) { var state_arr = java.lang.reflect.Array.newInstance(java.lang.String, 1); state_arr[0] = recovered_state; stsuu.addContextAttribute(new Attribute("recovered_state", "urn:ibm:names:ITFIM:oauth:response:attribute", state_arr)); } } ...OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

State management

The state_id parameter in the STSUniversalUser module is used as a key to store or retrieve state information for each invocation of the trust chain of an OAuth flow.

Advance Access Control provides sample mapping rules. These sample mapping rules use state management API and are applicable to OAuth 2.0 protocols. You can get the sample mapping rules from the File downloads section.

OAuth 2.0

OAuth 2.0 tokens, such as grants, access tokens, and refresh tokens, have a state_id parameter that is used in Security Token Service mapping rules. The state_id parameter maintains state between associated Security Token Service calls in an OAuth 2.0 flow.

The OAuth 2.0 mapping rule uses the state_id as the key to issue an authorization grant. The key is used to add the token storage time to a cache. The storage time is then retrieved from the cache during a request for a protected resource.

Figure 60. shows a section of the sample JavaScript mapping rule for OAuth 2.0.

Figure 60. OAuth 2.0 JavaScript sample code with state management

...
var request_type = null;
var grant_type = null;

// The request type - if none available assume 'resource'
temp_attr = stsuu.getContextAttributes().getAttributeValuesByNameAndType("request_type", "urn:ibm:names:ITFIM:oauth:request");
if (temp_attr != null && temp_attr.length > 0) {
        request_type = temp_attr[0];
} else {
        request_type = "resource";
}

// The grant type
temp_attr = stsuu.getContextAttributes().getAttributeValuesByNameAndType("grant_type", "urn:ibm:names:ITFIM:oauth:body:param");
if (temp_attr != null && temp_attr.length > 0) {
        grant_type = temp_attr[0];
}

/* The following demonstrates the use of the state management API.
 *
 *      request_type = 'authorization' ==> Store the UTC time of the request into a cache
                                   with state_id as key [authorization_code, implicit]
 *      request_type = 'access_token' && grant_type = 'client_credentials' ==> Store the UTC time of the request
                                   into a cache with state_id as key [client_credentials]
 *      request_type = 'access_token' && grant_type = 'password' ==> Store the UTC time of the request into a cache
                                   with state_id as key [password]
 *      request_type = 'resource' ==> Retrieve the stored time and put it into an attribute named recovered_state
 *
 *      It also stores the flow type we are in be used later to detect if this is a client_credentials two-legged flow or not.
 */
if (request_type == "authorization" || (request_type == "access_token" &&
                                   ( grant_type == "client_credentials" || grant_type == "password" ))) {
        var curr_utc_time = "State storage time was: " + IDMappingExtUtils.getCurrentTimeStringUTC();
        IDMappingExtUtils.getIDMappingExtCache().put(state_id, curr_utc_time, 1000);
} else if (request_type == "resource") {
        var recovered_state = IDMappingExtUtils.getIDMappingExtCache().get(state_id);

        if (recovered_state != null) {
                var state_arr = java.lang.reflect.Array.newInstance(java.lang.String, 1);
                state_arr[0] = recovered_state;
                stsuu.addContextAttribute(new Attribute("recovered_state",
                                                   "urn:ibm:names:ITFIM:oauth:response:attribute", state_arr));
        }
}
...

Parent topic: OAuth 2.0 support

Trusted clients managementTrusted clients managementTrusted clients managementAdvanced Access Control stores trusted client information that is based on the decisions of a resource owner on which clients to trust.trusted clients managementoverviewOAuth 2.0trusted clients managementIn an OAuth 2.0 flow, the resource owner is asked to provide consent on the scopes that are requested by a client to access the protected resource. The resource owner can either grant permission or deny the client from its access request.The OAuth server or authorization server uses the trusted clients manager to manage information about trusted clients. Administrators can configure the behavior of the trusted clients manager in the API protection page. They can configure whether a resource owner is prompted for consent in the Authorization code flow or the Implicit grant flow.The following configuration options are available:Never prompt a resource owner for consent - Resource owners are never prompted for consent and the authorization decision defaults to allow access to the resource.Always prompt a resource owner for consent - Resource owners are always prompted for consent even if the client was previously allowed to access the resource. Prompt the resource owner once and remember consent - Resource owners are prompted once for consent and later allows access to the resource. For the Prompt once and remember configuration options, the trusted client manager verifies whether the resource owner previously provided consent on the scopes that are requested by a client.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

Trusted clients management

Advanced Access Control stores trusted client information that is based on the decisions of a resource owner on which clients to trust.

In an OAuth 2.0 flow, the resource owner is asked to provide consent on the scopes that are requested by a client to access the protected resource. The resource owner can either grant permission or deny the client from its access request.

The OAuth server or authorization server uses the trusted clients manager to manage information about trusted clients.

Administrators can configure the behavior of the trusted clients manager in the API protection page. They can configure whether a resource owner is prompted for consent in the Authorization code flow or the Implicit grant flow.

The following configuration options are available:

Never prompt a resource owner for consent - Resource owners are never prompted for consent and the authorization decision defaults to allow access to the resource.

Always prompt a resource owner for consent - Resource owners are always prompted for consent even if the client was previously allowed to access the resource.

Prompt the resource owner once and remember consent - Resource owners are prompted once for consent and later allows access to the resource.

Note: For the Prompt once and remember configuration options, the trusted client manager verifies whether the resource owner previously provided consent on the scopes that are requested by a client.

Parent topic: OAuth 2.0 support

Configuring API protectionConfiguring OAuth 2.0 API protectionConfigure OAuth 2.0 API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client. OAuthfederation configurationfederationOAuth configurationYou must then attach the API protection definition to a resource.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.Creating an API protection definitionCreate API protection definitions to configure the settings that dictate the behavior of how resources are accessed. The configuration settings protect the resources from unauthorized access.Managing API protection definitionsAn API protection definition is a set of configurations that define how resources are accessed. PIN policyAdvanced Access Control extends OAuth 2.0 capabilities with a PIN policy.Registering an API protection clientRegister OAuth API protection clients in the Clients panel. Clients are the entities against which OAuth access and refresh tokens are granted at runtime. Managing registered API protection clientsManage registered OAuth API protection clients.Managing policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced.Using oauthScope attributes in an access control policyYou can use the subject and resource oauthScope attributes as part of an access control decision for a resource.Uploading OAuth response filesUse the local management interface to upload your own custom OAuth response files.Actions to be performed in mapping rulesFor certain grant types, you must perform these actions in the pre-token mapping rule.

Configuring API protection

The API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

You must then attach the API protection definition to a resource.

Creating an API protection definition
Create API protection definitions to configure the settings that dictate the behavior of how resources are accessed. The configuration settings protect the resources from unauthorized access.

Managing API protection definitions
An API protection definition is a set of configurations that define how resources are accessed.

PIN policy
Advanced Access Control extends OAuth 2.0 capabilities with a PIN policy.

Registering an API protection client
Register OAuth API protection clients in the Clients panel. Clients are the entities against which OAuth access and refresh tokens are granted at runtime.

Managing registered API protection clients
Manage registered OAuth API protection clients.

Managing policy attachments
Attach policies or API protection definitions to resources so that the policies and definitions can be enforced.

Using oauthScope attributes in an access control policy
You can use the subject and resource oauthScope attributes as part of an access control decision for a resource.

Uploading OAuth response files
Use the local management interface to upload your own custom OAuth response files.

Actions to be performed in mapping rules
For certain grant types, you must perform these actions in the pre-token mapping rule.

Parent topic: OAuth 2.0 support

Creating an API protection definitionCreating an API protection definitionAPI protection definition: creatingCreate API protection definitions to configure the settings that dictate the behavior of how resources are accessed. The configuration settings protect the resources from unauthorized access.definitioncreating API protectionAPI protection definitioncreatingLog in to the local management interface.Click Secure Access Control.Under Policy, click API Protection.Click Definitions.Click Add.In the Name field, type a unique name for the definition.The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.In the Description field, provide a brief description about the definition.Click Grant Types.You must select at least one grant type. Authorization code is enabled by default.Click Token Management.Provide the following information:Access token lifetime (seconds)Specifies the number of seconds an access token is valid. When the access token becomes invalid, the client cannot use it to access the protected resource.Default value: 3600 seconds.Minimum value: 1 second.Access token lengthSpecifies the number of characters in an access token.Default value: 20 characters.Minimum value: one character.Maximum value: 500 characters.Enforce single-use authorization grantIf enabled, all the authorization grant tokens are revoked after an access token is validated. If enabled, resource requests that involve redirects fail because the access token is validated multiple times.Default value: disabledAuthorization code lifetime (seconds)Specifies the number of seconds that an authorization code is valid.This option applies only to an authorization code grant type. The authorization server generates an authorization code and sends it to the client. The client uses the authorization code in exchange for an access token. Default value: 300 seconds.Minimum value: 1 second.Authorization code lengthSpecifies the number of characters in an authorization code.Default value: 30 characters.Minimum value: one character.Maximum value: 500 characters.Issue refresh tokenSpecifies whether a refresh token is sent to the client. A refresh token obtains a new pair of access and refresh tokens. This option is only applicable to the Authorization code and Resource owner password credentials grant types.Maximum authorization grant lifetime (seconds)Specifies the maximum number of seconds that the resource owner authorizes the client to access the protected resource.This option is available only if you enable the Issue refresh token option.The value for this lifetime must be greater than the values specified for the authorization code and access token lifetimes. When this lifetime expires, the resource owner must reauthorize the client to obtain an authorization grant to access the protected resource.Default value: 604800 seconds.Minimum value: 1 second.Refresh token lengthSpecifies the number of characters in a refresh token. This option is available only if you enable the Issue refresh token option.Default value: 40 characters.Minimum value: 1 characters.Maximum value: 500 characters.Enforce single access token per authorization grantIf enabled, all previously granted access tokens are revoked after a new access token is generated presenting the refresh token to the authorization server.This option is available only if you enable the Issue refresh token option.Default value: enabledEnable PIN policyProvides more protection during the exchange of a refresh token fro a new pair of access and refresh tokens. This option is available only if you enable the Issue refresh token option. If enabled, you must configure the PIN length. PIN LengthSpecifies the number of characters in a PIN. This option is available only if you enable the Enable PIN policy option. You can use the runtime.hashAlgorithm runtime parameter to configure the algorithm that is used to hash the PIN before it is stored. For more information, see Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..Default value: 4 characters.Minimum value: 3 characters.Maximum value: 12 characters.Token character setBy default, a set of alphanumeric characters is displayed. You can specify the set of characters used to generate tokens in the following methods:Manually enter charactersSelect from a pre-defined character set from the drop-down listEdit the characters in the field after selecting from a set from the drop-down listThe configured token character set is applicable for all token types. If this parameter is left blank, all available alphanumeric characters are used to generate the token. Maximum number for characters allowed: 200 Click Trusted Clients and Consent and select when you want the user to be prompted to consent to an authorization grant.Click Save.Attach definitions to resources and publish the attachments for definitions to be implemented. See Managing policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced..Register an API protection clientRegister OAuth API protection clients in the Clients panel. Clients are the entities against which OAuth access and refresh tokens are granted at runtime. .Deploy the pending changes. See Deploying pending changesSome configuration and administration changes require an extra deployment step.Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Creating an API protection definition

Create API protection definitions to configure the settings that dictate the behavior of how resources are accessed. The configuration settings protect the resources from unauthorized access.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click API Protection.

Click Definitions.

Click Add.

In the Name field, type a unique name for the definition.

Note: The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.

In the Description field, provide a brief description about the definition.

Click Grant Types.

You must select at least one grant type. Authorization code is enabled by default.

Click Token Management.

Provide the following information:

Access token lifetime (seconds)

Specifies the number of seconds an access token is valid. When the access token becomes invalid, the client cannot use it to access the protected resource.

Default value: 3600 seconds.

Minimum value: 1 second.

Access token length

Specifies the number of characters in an access token.

Default value: 20 characters.

Minimum value: one character.

Maximum value: 500 characters.

Enforce single-use authorization grant

If enabled, all the authorization grant tokens are revoked after an access token is validated. If enabled, resource requests that involve redirects fail because the access token is validated multiple times.

Default value: disabled

Authorization code lifetime (seconds)

Specifies the number of seconds that an authorization code is valid.

This option applies only to an authorization code grant type. The authorization server generates an authorization code and sends it to the client. The client uses the authorization code in exchange for an access token.

Default value: 300 seconds.

Minimum value: 1 second.

Authorization code length

Specifies the number of characters in an authorization code.

Default value: 30 characters.

Minimum value: one character.

Maximum value: 500 characters.

Issue refresh token

Specifies whether a refresh token is sent to the client. A refresh token obtains a new pair of access and refresh tokens. This option is only applicable to the Authorization code and Resource owner password credentials grant types.

Maximum authorization grant lifetime (seconds)

Specifies the maximum number of seconds that the resource owner authorizes the client to access the protected resource.

This option is available only if you enable the Issue refresh token option.

The value for this lifetime must be greater than the values specified for the authorization code and access token lifetimes.

When this lifetime expires, the resource owner must reauthorize the client to obtain an authorization grant to access the protected resource.

Default value: 604800 seconds.

Minimum value: 1 second.

Refresh token length

Specifies the number of characters in a refresh token. This option is available only if you enable the Issue refresh token option.

Default value: 40 characters.

Minimum value: 1 characters.

Maximum value: 500 characters.

Enforce single access token per authorization grant

If enabled, all previously granted access tokens are revoked after a new access token is generated presenting the refresh token to the authorization server.

This option is available only if you enable the Issue refresh token option.

Default value: enabled

Enable PIN policy

Provides more protection during the exchange of a refresh token fro a new pair of access and refresh tokens.

This option is available only if you enable the Issue refresh token option. If enabled, you must configure the PIN length.

PIN Length

Specifies the number of characters in a PIN. This option is available only if you enable the Enable PIN policy option. You can use the runtime.hashAlgorithm runtime parameter to configure the algorithm that is used to hash the PIN before it is stored. For more information, see Advanced configuration properties.

Default value: 4 characters.

Minimum value: 3 characters.

Maximum value: 12 characters.

Token character set

By default, a set of alphanumeric characters is displayed. You can specify the set of characters used to generate tokens in the following methods:

Manually enter characters

Select from a pre-defined character set from the drop-down list

Edit the characters in the field after selecting from a set from the drop-down list

The configured token character set is applicable for all token types. If this parameter is left blank, all available alphanumeric characters are used to generate the token.

Maximum number for characters allowed: 200

Click Trusted Clients and Consent and select when you want the user to be prompted to consent to an authorization grant.

Click Save.

What to do next

Attach definitions to resources and publish the attachments for definitions to be implemented. See Managing policy attachments.

Register an API protection client.

Deploy the pending changes. See Deploying pending changes

Parent topic: Configuring API protection

Managing API protection definitionsManaging API protection definitionsAPI protection definitionAn API protection definition is a set of configurations that define how resources are accessed. definitionmanaging API protectionAPI protection definitionmanagingAPI protection definitionYou can add, modify, and delete definitions.Log in to the local management interface.Click Secure Access Control.Under Policy, click API Protection.Click Definitions.Perform one or more of the following actions:Add definitionsClick Add. See Creating an API protection definition for details.Modify definitionsSelect a definition in the list of definitions.Click Edit.Complete the properties for the definition. You cannot modify the definition name and grant types. See Creating an API protection definition for details. Click Save.Delete definitionsSelect a definition or press Ctrl and select multiple definitions in the definition list.Click Remove. Confirm the deletion. Click OK to continue or click Cancel.A definition cannot be deleted if there are clients associated with it or it is attached to a resource.Click Save. When you add, modify or delete a definition, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Managing API protection definitions

An API protection definition is a set of configurations that define how resources are accessed.

About this task

You can add, modify, and delete definitions.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click API Protection.

Click Definitions.

Perform one or more of the following actions:

Add definitions

Click Add. See Creating an API protection definition for details.

Modify definitions

Select a definition in the list of definitions.

Click Edit.

Complete the properties for the definition.

Note:

You cannot modify the definition name and grant types. See Creating an API protection definition for details.

Click Save.

Delete definitions

Select a definition or press Ctrl and select multiple definitions in the definition list.

Click Remove. Confirm the deletion. Click OK to continue or click Cancel.

Note: A definition cannot be deleted if there are clients associated with it or it is attached to a resource.

Click Save.

When you add, modify or delete a definition, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.

For more information, see Deploying pending changes.

Parent topic: Configuring API protection

PIN policyPIN policyPIN policyAdvanced Access Control extends OAuth 2.0 capabilities with a PIN policy.The PIN policy provides the capability of protecting a refresh token with a PIN provided by the API protection client. An administrator can configure the API protection definition to enable the PIN policy for the grant types that issue a refresh token. The two grant types that issue a refresh token are Authorization code and the Resource owner password credentials.When enabled, the client is required to send a PIN as a parameter in the first access token request. The parameter name is pin. The parameter value consists of digits of the length that is configured in the API protection definition. The client must submit the same PIN on subsequent requests when exchanging a refresh token for a new access token. The PIN policy can be configured to use various hash algorithms to hash and store the PIN. Use the runtime.hashAlgorithm configuration parameter to specify the hash algorithm. For more information about configuring the hash algorithm, see Runtime properties in Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization.Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

PIN policy

Advanced Access Control extends OAuth 2.0 capabilities with a PIN policy.

The PIN policy provides the capability of protecting a refresh token with a PIN provided by the API protection client. An administrator can configure the API protection definition to enable the PIN policy for the grant types that issue a refresh token. The two grant types that issue a refresh token are Authorization code and the Resource owner password credentials.

When enabled, the client is required to send a PIN as a parameter in the first access token request. The parameter name is pin. The parameter value consists of digits of the length that is configured in the API protection definition. The client must submit the same PIN on subsequent requests when exchanging a refresh token for a new access token.

The PIN policy can be configured to use various hash algorithms to hash and store the PIN. Use the runtime.hashAlgorithm configuration parameter to specify the hash algorithm. For more information about configuring the hash algorithm, see Runtime properties in Advanced configuration properties

Parent topic: Configuring API protection

Registering an API protection clientRegister an API protection clientAPI protection client registrationRegister OAuth API protection clients in the Clients panel. Clients are the entities against which OAuth access and refresh tokens are granted at runtime. client registering API protection API protection clientregisteringAPI protectionclientOAuth API protection clientLog in to the local management interface.Click Secure Access Control.Under Policy, click API Protection.Click Clients.Click Add.Specify the following information:Client nameSpecify a meaningful client identifier for each client registration. You can use this value to search for client registrations.API definitionSpecifies the related Definition, which owns and defines the client. A Definition can own many client registrations but a client registration can belong to only one Definition. When you create a client, a list of available Definitions are available. When a client is created, this value cannot be modified.ConfidentialSpecify whether the client type is confidential. A confidential client type requires a client secret. Enable this feature if you want the client to require a client secret.Client secretThis field is enabled only if the client is indicated as confidential. Specify a client secret that is used to authenticate an OAuth client at runtime. It is mandatory for all clients that belong to API protection definitions where the client type is Confidential and the client credentials grant type is enabled. Click Generate to have a client secret that is generated for you or specify your own secret.Redirect URI (Optional)Specify the redirect URI to use for the client.Company nameSpecify the name of the company for this client.Company URL (Optional)Specify the URL of the company website.Contact name (Optional)Specify a name of the contact person for this client. Email address (Optional)Specify the email address of the contact person for this client.Telephone number (Optional)Specify the telephone number of the contact person for this client. Contact type (Optional)Select the contact type from the list:AdministrativeSupportTechnicalBillingOtherOther information (Optional)Specify extra information about the client contact.Click OK.Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Registering an API protection client

Register OAuth API protection clients in the Clients panel. Clients are the entities against which OAuth access and refresh tokens are granted at runtime.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click API Protection.

Click Clients.

Click Add.

Specify the following information:

Client name

Specify a meaningful client identifier for each client registration. You can use this value to search for client registrations.

API definition

Specifies the related Definition, which owns and defines the client. A Definition can own many client registrations but a client registration can belong to only one Definition. When you create a client, a list of available Definitions are available. When a client is created, this value cannot be modified.

Confidential

Specify whether the client type is confidential. A confidential client type requires a client secret. Enable this feature if you want the client to require a client secret.

Client secret

This field is enabled only if the client is indicated as confidential. Specify a client secret that is used to authenticate an OAuth client at runtime. It is mandatory for all clients that belong to API protection definitions where the client type is Confidential and the client credentials grant type is enabled. Click Generate to have a client secret that is generated for you or specify your own secret.

Redirect URI (Optional)

Specify the redirect URI to use for the client.

Company name

Specify the name of the company for this client.

Company URL (Optional)

Specify the URL of the company website.

Contact name (Optional)

Specify a name of the contact person for this client.

Email address (Optional)

Specify the email address of the contact person for this client.

Telephone number (Optional)

Specify the telephone number of the contact person for this client.

Contact type (Optional)

Select the contact type from the list:

Administrative

Support

Technical

Billing

Other

Other information (Optional)

Specify extra information about the client contact.

Click OK.

Parent topic: Configuring API protection

Managing registered API protection clientsManaging registered API protection clientsAPI protection clientsManage registered OAuth API protection clients.clientmanaging API protectionAPI protection client managingAPI protection clientYou can search and delete clients. You can search for API protection clients based on the following values:Client nameClient IDAPI protection definitionLog in to the local management interface.Click Secure Access Control.Under Policy, click API Protection.Click Clients.Perform one or more of the following actions:View and filter clientsYou can filter for client name, client ID, and API protection definition.Take any of the following actions to filter your view: Select the DetailsDetails View to view client name, client ID, and API protection definition. Select the ListList View to view only the name of the client.Type a term, such as an client name, client ID, and API protection definition in the Filter field to list clients that use that term. Any part of the values for client name, client ID, or API protection definition that match is applied by the filter and is displayed in the search results. Click x to clear the Filter field.Sort the client list by column with the up or down arrow on each column. For example, you can view the list of clients that are sorted by the Clients column in ascending order by clicking the up arrow.Modify clientsEnsure that the modification does not affect a current policy or configuration. If you modify a client that is in-use, the policy or configuration that uses the client might stop working.Select the client you want to modify.Click EditComplete the properties for the clients.Click OK.Delete clientsSelect a client or press and hold the Ctrl key and select multiple clients to remove.Click Remove. Confirm the deletion. Click OK to continue or click Cancel.When you delete a client:The client registration is removed from the database.All tokens issued against that client is removed.When you add, modify or delete a client, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Managing registered API protection clients

Manage registered OAuth API protection clients.

About this task

You can search and delete clients. You can search for API protection clients based on the following values:

Client name

Client ID

API protection definition

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click API Protection.

Click Clients.

Perform one or more of the following actions:

View and filter clients

You can filter for client name, client ID, and API protection definition.

Take any of the following actions to filter your view:

Select the DetailsDetails View to view client name, client ID, and API protection definition.

Select the ListList View to view only the name of the client.

Type a term, such as an client name, client ID, and API protection definition in the Filter field to list clients that use that term. Any part of the values for client name, client ID, or API protection definition that match is applied by the filter and is displayed in the search results. Click x to clear the Filter field.

Sort the client list by column with the up or down arrow on each column. For example, you can view the list of clients that are sorted by the Clients column in ascending order by clicking the up arrow.

Modify clients

Attention: Ensure that the modification does not affect a current policy or configuration. If you modify a client that is in-use, the policy or configuration that uses the client might stop working.

Select the client you want to modify.

Click Edit

Complete the properties for the clients.

Click OK.

Delete clients

Select a client or press and hold the Ctrl key and select multiple clients to remove.

Click Remove. Confirm the deletion. Click OK to continue or click Cancel.

When you delete a client:

The client registration is removed from the database.

All tokens issued against that client is removed.

When you add, modify or delete a client, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.

For more information, see Deploying pending changes.

Parent topic: Configuring API protection

Managing policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced.policypublishingpolicyattaching to resourceAPI definitionpublishingAPI definitionattaching to resourceYou must create policies, policy sets, or API protection definitions. When you create policies, policy sets, or API protection definitions you cannot use them until you publish them to resources. Once policies, policy sets, or API protection definitions are published, they are enforced during the evaluation of access requests.Since policies and API protection definitions are attached to resources, you must first configure resources. This means that policy and API protection definition attachment is dependent on prior installation and configuration of a Security Access Manager runtime component and reverse proxy server. These prior configuration tasks include the creation of a Security Access Manager protected object space. In a web environment, this configuration includes creation of a junction and resources (objects) that are protected by that junction. You can:Add a resourceAdd a policy or API protection definition attachment to a resourceRemove a policy or API protection definition attachment from a resourceDelete a resourcePublish a policy or API protection definition attachmentWhen a deployment is fully configured, the Resources panel displays three levels of entries. The top-level entry is the web container that contains the protected object space for a server instance. The second level shows the resources in the protected object space. The third level lists the policies and API protection definitions that are attached to each resource.The user interface provides a quick filter feature for use on the top-level entry. Use the quick filter to search for a specific top-level entry. Enter the first few characters of the web container, and the list displays only the entries that contain the specified characters.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.Click Resources.Perform one or more of the following actions:Add a resourceClick Add.In the Web Container field, click the down arrow icon to display a list of web containers. Select an entry.For example, the list of web containers is the WebSEAL protected object space that is defined directly under /WebSEAL.Specify a resource. You can either enter the name of the resource or browse for it:If you know the name of the resource within the protected object space, you can enter it in the Resource field.For example, /myserver-jct/benefits/medicalIf you select Browse, you can select a resource from the tree hierarchy. Expand the hierarchy to see all available resources.The display of the hierarchy is based on the structure of the WebSEAL protected object space:In some cases, not all resources are displayed because the WebSEAL protected object space is a sparse tree. For example, you might see only the resource /myserver-jct/benefits. You can select this resource and click OK to add it to the Resource. You can then add /myserver-jct/benefits/medical.In some cases, you cannot view the object space for the web server junction. For example, if the administrator did not install the IBM Security Access Manager querycontents script on the application server, you cannot see the junction contents. In these cases, you can enter the resource path manually.Click Save.Next, attach a policy to the resource.Attach a policy or API protection definition to a resourceSelect a resource node and click Attach Attach.In the Attach Policies panel, select Policies or Policy Sets or API Protection.From the displayed list, select one or more policies or policy sets or API protection definitions.You can type the name of the applicable policy or policy set or API protection definition in the quick filter. You can attach both individual policies, policy sets, or API protection definitions.You cannot attach policies or policy sets to a resource where that resource already has API protection definitions attached.You cannot attach API protection definitions to a resource where that resource already has policies and policy sets attached. Click OK to save your changes.The policy or API protection definition remains inactive until you publish it.Remove a policy or API protection definition attachmentTo remove a policy or API protection definition attachment from a resource, select the policy node and click Remove.When prompted, confirm the deletion.You must publish the change.Delete a resourceTo delete a resource and all attached policies or API protection definitions, select the resource node and click Remove.When prompted, confirm the deletion.When you delete a resource:You cannot delete the server node.You do not have to manually publish the change. The deletion is automatically published.Publish a policy or API protection definitionSelect a resource in the resource hierarchy and click Publish Publish. When the publication completes, the status column for the resource indicates the status and time of the publication.Activation of the published policy or API protection definition could take up to a minute to complete.Modify ResourceYou can only use this function if policy or policy sets are attached to the given resource.Select a resource node and click Edit.In the Modify Resource panel, you can modify the Policy Combining Algorithm. Choose the preferred algorithm:Deny access if any attached policy returns denyThis algorithm means that if multiple policies or API protection definitions are attached to a resource, and any one of those policies or API protection definitions returns Deny, then the access request is denied.Permit access if any attached policy returns permitThis algorithm means that if multiple policies or API protection definitions are attached to a resource, and any one of those policies or API protection definitions returns Permit, then the access request is permitted.Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Managing policy attachments

Attach policies or API protection definitions to resources so that the policies and definitions can be enforced.

Before you begin

You must create policies, policy sets, or API protection definitions.

When you create policies, policy sets, or API protection definitions you cannot use them until you publish them to resources. Once policies, policy sets, or API protection definitions are published, they are enforced during the evaluation of access requests.

Since policies and API protection definitions are attached to resources, you must first configure resources. This means that policy and API protection definition attachment is dependent on prior installation and configuration of a Security Access Manager runtime component and reverse proxy server. These prior configuration tasks include the creation of a Security Access Manager protected object space. In a web environment, this configuration includes creation of a junction and resources (objects) that are protected by that junction.

About this task

You can:

Add a resource

Add a policy or API protection definition attachment to a resource

Remove a policy or API protection definition attachment from a resource

Delete a resource

Publish a policy or API protection definition attachment

When a deployment is fully configured, the Resources panel displays three levels of entries. The top-level entry is the web container that contains the protected object space for a server instance. The second level shows the resources in the protected object space. The third level lists the policies and API protection definitions that are attached to each resource.

Tip: The user interface provides a quick filter feature for use on the top-level entry. Use the quick filter to search for a specific top-level entry. Enter the first few characters of the web container, and the list displays only the entries that contain the specified characters.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

Click Resources.

Perform one or more of the following actions:

Add a resource

Click Add.

In the Web Container field, click the down arrow icon to display a list of web containers. Select an entry.

For example, the list of web containers is the WebSEAL protected object space that is defined directly under /WebSEAL.

Specify a resource. You can either enter the name of the resource or browse for it:

If you know the name of the resource within the protected object space, you can enter it in the Resource field.

For example, /myserver-jct/benefits/medical

If you select Browse, you can select a resource from the tree hierarchy. Expand the hierarchy to see all available resources.

The display of the hierarchy is based on the structure of the WebSEAL protected object space:

In some cases, not all resources are displayed because the WebSEAL protected object space is a sparse tree. For example, you might see only the resource /myserver-jct/benefits. You can select this resource and click OK to add it to the Resource. You can then add /myserver-jct/benefits/medical.

In some cases, you cannot view the object space for the web server junction. For example, if the administrator did not install the IBM Security Access Manager querycontents script on the application server, you cannot see the junction contents. In these cases, you can enter the resource path manually.

Click Save.

Next, attach a policy to the resource.

Attach a policy or API protection definition to a resource

Select a resource node and click Attach Attach.

In the Attach Policies panel, select Policies or Policy Sets or API Protection.

From the displayed list, select one or more policies or policy sets or API protection definitions.

Tip: You can type the name of the applicable policy or policy set or API protection definition in the quick filter.

Notes:

You can attach both individual policies, policy sets, or API protection definitions.

You cannot attach policies or policy sets to a resource where that resource already has API protection definitions attached.

You cannot attach API protection definitions to a resource where that resource already has policies and policy sets attached.

Click OK to save your changes.

Note: The policy or API protection definition remains inactive until you publish it.

Remove a policy or API protection definition attachment

To remove a policy or API protection definition attachment from a resource, select the policy node and click Remove.

When prompted, confirm the deletion.

Note: You must publish the change.

Delete a resource

To delete a resource and all attached policies or API protection definitions, select the resource node and click Remove.

When prompted, confirm the deletion.

When you delete a resource:

You cannot delete the server node.

You do not have to manually publish the change. The deletion is automatically published.

Publish a policy or API protection definition

Select a resource in the resource hierarchy and click Publish Publish. When the publication completes, the status column for the resource indicates the status and time of the publication.

Note: Activation of the published policy or API protection definition could take up to a minute to complete.

Modify Resource

Note: You can only use this function if policy or policy sets are attached to the given resource.

Select a resource node and click Edit.

In the Modify Resource panel, you can modify the Policy Combining Algorithm. Choose the preferred algorithm:

Deny access if any attached policy returns deny

This algorithm means that if multiple policies or API protection definitions are attached to a resource, and any one of those policies or API protection definitions returns Deny, then the access request is denied.

Permit access if any attached policy returns permit

This algorithm means that if multiple policies or API protection definitions are attached to a resource, and any one of those policies or API protection definitions returns Permit, then the access request is permitted.

Parent topic: Configuring API protection

Using oauthScope attributes in an access control policyUsing oauthScope attributes in an access control policyUsing oauthScope attributes in an access control policyYou can use the subject and resource oauthScope attributes as part of an access control decision for a resource.scope attributesOAuthoauthScope attributesattributesoauthScope Create a reverse proxy instance.Run the isamcfg tool. You must configure access control policies and API protection capabilities.Determine the access control resources that your policies must be attached to. If the resources do not exist, add them. To use the OAuth attributes in an access control decision, you must attach the access control policy and API protection definition in the proper locations in the protected object space.Create an access control policy. Specify the oauthScopeResource attribute, the oauthScopeSubject attribute, or both, in one or more rules for this policy. See Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy..Attach the access control policy to an object in the protected object space. See Managing policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced..Create an API protection definition. See Creating an API protection definitionCreate API protection definitions to configure the settings that dictate the behavior of how resources are accessed. The configuration settings protect the resources from unauthorized access..Register an API client that uses the API protection definition you created in step 3. See Registering an API protection clientRegister OAuth API protection clients in the Clients panel. Clients are the entities against which OAuth access and refresh tokens are granted at runtime. .Attach the API protection definition to an object in the protected object space. See Managing policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced.. When you attach the definition to a resource, the resource must be at a level lower than where the access control policy is attached in step 2. The term lower means farther away from the root of the protected object space. For example, in the resource tree jct/dir1/dir2/protected_resource, you can attach the access control policy to /jct. Then, attach the API protection definition to /jct/dir1. Deploy the pending changes.The access decision for a resource at or below the API protection definition involves the oauthScope attributes that were defined in the access control policy.Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Using oauthScope attributes in an access control policy

You can use the subject and resource oauthScope attributes as part of an access control decision for a resource.

Before you begin

Create a reverse proxy instance.

Run the isamcfg tool. You must configure access control policies and API protection capabilities.

Determine the access control resources that your policies must be attached to. If the resources do not exist, add them.

About this task

To use the OAuth attributes in an access control decision, you must attach the access control policy and API protection definition in the proper locations in the protected object space.

Procedure

Create an access control policy. Specify the oauthScopeResource attribute, the oauthScopeSubject attribute, or both, in one or more rules for this policy. See Creating an access control policy.

Attach the access control policy to an object in the protected object space. See Managing policy attachments.

Create an API protection definition. See Creating an API protection definition.

Register an API client that uses the API protection definition you created in step 3. See Registering an API protection client.

Attach the API protection definition to an object in the protected object space. See Managing policy attachments.

When you attach the definition to a resource, the resource must be at a level lower than where the access control policy is attached in step 2. The term lower means farther away from the root of the protected object space.

For example, in the resource tree jct/dir1/dir2/protected_resource, you can attach the access control policy to /jct. Then, attach the API protection definition to /jct/dir1.

Deploy the pending changes.

Results

The access decision for a resource at or below the API protection definition involves the oauthScope attributes that were defined in the access control policy.

Parent topic: Configuring API protection

Uploading OAuth response filesUploading OAuth response filesUploading OAuth response filesUse the local management interface to upload your own custom OAuth response files.From the top menu, select Secure Reverse Proxy SettingsManageReverse Proxy.Select a reverse proxy.Select ManageManagement Root.Select the oauth folder.Select ManageImport.Click Browse. Browse to the file you want to import.Click Open.Click Import.Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Uploading OAuth response files

Use the local management interface to upload your own custom OAuth response files.

Procedure

From the top menu, select Secure Reverse Proxy Settings > Manage > Reverse Proxy.

Select a reverse proxy.

Select Manage > Management Root.

Select the oauth folder.

Select Manage > Import.

Click Browse.

Browse to the file you want to import.

Click Open.

Click Import.

Parent topic: Configuring API protection

Actions to be performed in mapping rulesFor certain grant types, you must perform these actions in the pre-token mapping rule.Resource owner password credentials (ROPC) grant type flowFor the ROPC flow, the pre-token mapping rule is responsible for performing validation of the user name and password. This validation can be performed in various ways. The pre-defined rule that is included with the appliance provides the following examples:The java class PluginUtils can be used to validate a user name and password against a configured LDAP. To configure the LDAP to be used, see Configuring username and password authenticationThe user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository. .Validate the user name and password through an HTTP callout. The mapping rule sends the user name and password to a web service. As the format of the messages is not fixed, various services (for example, REST, SOAP, SCIM) can be used for this purpose. Javadoc on the HTTP client and all other exposed Java classes available in mapping rules can be downloaded from the appliance File Downloads page under the path access_controldocISAM-javadoc.zip.JWT and SAML bearer grant type flowFor the JWT or SAML assertion bearer grant type flows, the pre-token mapping rule must perform the following actions: Validate the assertion, including but not limited to:Validate the signature (if signed).Decrypt the assertion (if encrypted).Check the expiry and "not before" value of the assertion.Ensure that the issuer is a trusted party.Extract the subject from the assertion and set the USERNAME field of the STSUU.The USERNAME field of the STSUU can be set via a call, for example:// username is a variable containing the subject of the assertion stsuu.addContextAttribute(new com.tivoli.am.fim.trustserver.sts.uuser.Attribute ("username","urn:ibm:names:ITFIM:oauth:body:param", username));The validation of the assertion can be performed in various ways:HTTP callout to a web service. Use the HTTP client to perform this. WS-Trust request to the Secure Token Service (STS). A chain must be configured to consume the assertion and return the required information.The STSClientHelper will be called to invoke the STS via HTTP. For more information about this class, see the Javadoc that is embedded in the appliance. Any attributes of the assertion can be extracted and associated to the OAuth grant to be used later. For more information about associating attributes, see OAuth 2.0 mapping rule methodsCustomize the PreTokenGeneration and PostTokenGeneration mapping rules using these methods..Configuring API protectionThe API protection uses the OAuth 2.0 protocol. To configure the API protection, you must create a definition and a client.

Actions to be performed in mapping rules

For certain grant types, you must perform these actions in the pre-token mapping rule.

Resource owner password credentials (ROPC) grant type flow

For the ROPC flow, the pre-token mapping rule is responsible for performing validation of the user name and password. This validation can be performed in various ways. The pre-defined rule that is included with the appliance provides the following examples:

The java class PluginUtils can be used to validate a user name and password against a configured LDAP.

To configure the LDAP to be used, see Configuring username and password authentication.

Validate the user name and password through an HTTP callout. The mapping rule sends the user name and password to a web service. As the format of the messages is not fixed, various services (for example, REST, SOAP, SCIM) can be used for this purpose. Javadoc on the HTTP client and all other exposed Java classes available in mapping rules can be downloaded from the appliance File Downloads page under the path access_control > doc > ISAM-javadoc.zip.

JWT and SAML bearer grant type flow

For the JWT or SAML assertion bearer grant type flows, the pre-token mapping rule must perform the following actions:

Validate the assertion, including but not limited to:

Validate the signature (if signed).

Decrypt the assertion (if encrypted).

Check the expiry and "not before" value of the assertion.

Ensure that the issuer is a trusted party.

Extract the subject from the assertion and set the USERNAME field of the STSUU.

The USERNAME field of the STSUU can be set via a call, for example:

// username is a variable containing the subject of the assertion

stsuu.addContextAttribute(new com.tivoli.am.fim.trustserver.sts.uuser.Attribute
("username","urn:ibm:names:ITFIM:oauth:body:param", username));

The validation of the assertion can be performed in various ways:

HTTP callout to a web service. Use the HTTP client to perform this.

WS-Trust request to the Secure Token Service (STS).

A chain must be configured to consume the assertion and return the required information.

The STSClientHelper will be called to invoke the STS via HTTP. For more information about this class, see the Javadoc that is embedded in the appliance.

Any attributes of the assertion can be extracted and associated to the OAuth grant to be used later. For more information about associating attributes, see OAuth 2.0 mapping rule methods.

Parent topic: Configuring API protection

Managing OAuth 2.0 mapping rulesManaging OAuth 2.0 mapping rulesManaging OAuth 2.0 mapping rulesUse the mapping rules to customize the methods for the OAuth 2.0 flow. The OAuth 2.0 mapping rules are JavaScript code that run during the OAuth 2.0 flow. You can view, export, and replace OAuth mapping rules. View the mapping rule if you want to see the content and structure of the mapping rule. Export the mapping rule if you want to save a copy of the mapping rule. You can also edit this copy. Replace a mapping rule if you want to use a new mapping rule.Log in to the local management interface.Click Secure Access Control.Under Policy, click API Protection.Click Advanced.Perform one or more of the following actions:View a mapping ruleSelect a mapping rule.Click View. The View Mapping Rule panel opens. The content of the mapping rule is displayed.Click OK to close the panel.Export a mapping ruleSelect a mapping rule.Click Export.Choose a location and save the file.Replace a mapping rule:Use an existing mapping rule as the basis for the updated mapping rule.Select a mapping rule that you want to replace.Click Import. The Replace Mapping Rule panel opens.Click the field or Browse and select a file.Click OK to upload the mapping rule.When you replace a mapping rule, the appliance displays a message that there are undeployed changes. If you are finished with the changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..OAuth 2.0 mapping rule methodsCustomize the PreTokenGeneration and PostTokenGeneration mapping rules using these methods.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

Managing OAuth 2.0 mapping rules

Use the mapping rules to customize the methods for the OAuth 2.0 flow.

About this task

The OAuth 2.0 mapping rules are JavaScript code that run during the OAuth 2.0 flow. You can view, export, and replace OAuth mapping rules.

View the mapping rule if you want to see the content and structure of the mapping rule. Export the mapping rule if you want to save a copy of the mapping rule. You can also edit this copy. Replace a mapping rule if you want to use a new mapping rule.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click API Protection.

Click Advanced.

Perform one or more of the following actions:

View a mapping rule

Select a mapping rule.

Click View. The View Mapping Rule panel opens. The content of the mapping rule is displayed.

Click OK to close the panel.

Export a mapping rule

Select a mapping rule.

Click Export.

Choose a location and save the file.

Replace a mapping rule:

Note: Use an existing mapping rule as the basis for the updated mapping rule.

Select a mapping rule that you want to replace.

Click Import. The Replace Mapping Rule panel opens.

Click the field or Browse and select a file.

Click OK to upload the mapping rule.

When you replace a mapping rule, the appliance displays a message that there are undeployed changes. If you are finished with the changes, deploy them.

For more information, see Deploying pending changes.

Parent topic: OAuth 2.0 support

Related reference:

OAuth 2.0 mapping rule methods

OAuth 2.0 mapping rule methodsOAuth 2.0 mapping rule methodsOAuth 2.0 mapping rule methodsCustomize the PreTokenGeneration and PostTokenGeneration mapping rules using these methods.mapping rulesPostTokenGenerationone-time passworddelivery methodPostTokenGenerationusageSample mapping rules are in Manage System SettingsSecure SettingsFile Downloadsaccess_controlexamplesmapping rules.The following limitations affect the attribute keys and values that are associated with the state_id by using the OAuthMappingExtUtils class:Keys cannot be null or empty.Values cannot be null but can be empty.Associated key-value pairs are read and write-allowed and not-sensitive.Some keys are reserved for system use and cannot be modified by this utility. For example, the keys and values for the API PIN protection. associatepublic static boolean associate( String stateID, String attrKey, String attrValue )This method associates the attribute key-value pair to the authorization grant state ID. Use the following parameters:stateID - The state ID of the authorization grant. This parameter cannot be null or empty.attrKey - The attribute key. This parameter cannot be null or empty. The maximum length is 256 characters.attrValue - The attribute value. This parameter cannot be null. The maximum length is 256 characters. These responses come from the runtime after association.True if successful.False if not successful.deleteGrantpublic static boolean deleteGrant( String stateId )This method deletes the authorization grant with the given state ID from the token cache. Use the following parameter:stateId - The state ID of the authorization grant. This parameter cannot be null or empty.deleteToken public static Boolean deleteToken ( String tokenID ) This method deletes the token from the token cache. Use the following parameter:tokenID - The token ID of the token to be deleted. This parameter cannot be null or empty. To limit the number of tokens per user per definition, see OAuth 2.0 token limitsYou can define limits on the number of OAuth tokens per user per definition so that the high-volume database does not go beyond capacity..disassociatepublic static String disassociate( String stateID, String attrKey )This method disassociates the attribute key-value pair from the authorization grant state ID. Use the following parameters:stateID - The state ID of the authorization grant. This parameter cannot be null or empty.attrKey - The attribute key to disassociate. This parameter cannot be null or empty. These responses come from the runtime after disassociation.The previous string value that is associated with the state ID and attribute key if successful.Null, if not successful. For example, when association is never made.getAssociation public static String getAssociation( String stateID, String attrKey ) This method gets the attribute value from the authorization grant state ID and attribute key. Use the following parameters:stateID - The state ID of the authorization grant. This parameter cannot be null or empty.attrKey - The attribute key value that you want to be returned. This parameter cannot be null or empty. These responses come from the runtime after it gets the association keys.The string value that is associated with the state ID and attribute key if successful.Null, if not successful. For example, when the association is never made.getAssociationKeyspublic static String[] getAssociationKeys( String stateID )This method gets all the attribute keys that are associated with the authorization grant state ID. Use the following parameter:stateID - The state ID of the authorization grant. This parameter cannot be null or empty.These responses come from the runtime after it gets the association keys.A string array of all attribute keys that are associated with the authorization grant state ID if successful.Null, if state ID is wrong, if there are problems during retrieval from the token cache, or if there are no associated attributes.getGrantspublic static Grant[] getGrants( String username )This method gets the authorization grants associated with the given user name from the token cache. Use the following parameter: username - The user name of the authorization grants. This parameter cannot be null or empty. These responses come from the runtime after it gets the associated grants:A grant array of all authorization grants that are associated with the user name if successful.Null if one of the following conditions exist:User name is wrong or does not exist.There are problems during retrieval from the token cache.There are no associated authorization grants.getTokenspublic static Token[] getTokens( String clientId, String username )This method gets the tokens associated with the given client ID and user name from the token cache. Use the following parameters:clientId - The client ID of the tokens. This parameter cannot be null or empty. username - The user name of the tokens. This parameter cannot be null or empty.These responses come from the runtime after it gets the tokens:A token array of all tokens that are associated with the client ID and user name, if successful.Null, if one of the following conditions exist:Client ID or user name are wrong or do not exist.There are problems during retrieval from the token cache.There are no associated tokens.To limit the number of tokens per user per definition, see OAuth 2.0 token limitsYou can define limits on the number of OAuth tokens per user per definition so that the high-volume database does not go beyond capacity..HTTP GETpublic static HttpResponse httpGet( String url, )This method sends a HTTP GET request. Use the following parameters:url - The URL to send the GET request.This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.HTTP GETpublic static HttpResponse httpGet( String url, Map headers, String httpsTrustStore, String basicAuthUsername, String basicAuthPassword, String clientKeyStore, String clientKeyAlias )This method sends a HTTP GET request. Use the following parameters:url - The URL to send the GET request.headers - A map of the headers.httpsTrustStore - The truststore name. If this parameter is null and SSL connection is required, use the default truststore.basicAuthUsername - The user name for basic authentication. If this parameter is null, the basic authentication is not enabled.basicAuthPassword - The password that is used for basic authentication. If null, basic authentication is not enabled.clientKeyStore - The client keystore name. If this parameter is null, client certificate authentication is not enabled.clientKeyAlias - The client key alias. If this parameter is null, client certificate authentication is not enabled.This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.HTTP POSTpublic static HttpResponse httpPost( String url, Map params )This method sends a HTTP POST request. Use the following parameters:url - The URL to send the POST request.params- A map of the parameters.This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.HTTP POSTpublic static HttpResponse httpPost( String url, Map headers, Map params, String httpsTrustStore, String basicAuthUsername, String basicAuthPassword, String clientKeyStore, String clientKeyAlias )This method sends a HTTP POST request. Use the following parameters:url - The URL to send the GET request.headers - A map of the headers.httpsTrustStore - The truststore name. If this parameter is null and SSL connection is required, use the default truststore.basicAuthUsername - The user name for basic authentication. If this parameter is null, the basic authentication is not enabled.basicAuthPassword - The password that is used for basic authentication. If null, basic authentication is not enabled.clientKeyStore - The client keystore name. If this parameter is null, client certificate authentication is not enabled.clientKeyAlias - The client key alias. If this parameter is null, client certificate authentication is not enabled.This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.HTTPResponsepublic int getCode()This method gets the HTTP response code. This method returns the HttpResponse code. The method returns -1 if the response code is not set.HTTPResponsepublic String getBody()This method gets the HTTP response body.This method returns the HTTP response body. The method returns an empty string if the response body is not set.HTTPResponsepublic String[] getHeaderKeys()This method gets the HTTP response header keys.This method returns a string array of the HTTP response header keys. This method returns an empty array if there are no headers.HTTPResponsepublic String[] getHeaderValues( String key )This method gets the HTTP response header values for the key.This method returns a string array of the HTTP response header values for the key. This method returns an empty array if there is no value for the header key.isValidUsernamePassword public static boolean isValidUsernamePassword( String username, String password ) This method validates that the given user name and password are valid for the underlying user registry. You must configure the user name and password authentication mechanism before using this method. See Configuring username and password authenticationThe user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository. .Use the following parameters:username - The user name to validate. This parameter cannot be null or empty. password - The password of the user name. This parameter cannot be null or empty.These responses come from the runtime after validation.True if the user name and password are valid.False if invalid.logAuditEventpublic static void logAuditEvent( String username, String message, boolean result )This method generates an IBM_SECURITY_CBA_AUDIT_RTE audit event with action-id JAVASCRIPT_EVENT. You must enable auditing to generate this audit event. See Configuring auditingUse the Audit Configuration feature to enable logging of audit events..Use the following parameters: username - The user information to include in the audit record; it might be null. message - The message to include in the audit record. result - A Boolean value to indicate if the operation being audited was successful.throwSTSException public static void throwSTSException( String message ) This method returns an STSException. Use the following parameter:message - The message to be printed with the stack trace in the application log. A generic response is returned to the client. The input message that is passed can only be logged and is not visible to the client.throwSTSUserMessageException public static void throwSTSUserMessageException( String message ) This method returns an STSUserMessageException. Use the following parameter:message - The message to be printed with the stack trace in the application log and returned in the response to the client. The input message is logged and visible to the client.For more information, see the Javadoc in Manage System SettingsSecure SettingsFile Downloadsaccess_controldoc.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

OAuth 2.0 mapping rule methods

Customize the PreTokenGeneration and PostTokenGeneration mapping rules using these methods.

Sample mapping rules are in Manage System Settings > Secure Settings > File Downloads > access_control > examples > mapping rules.

The following limitations affect the attribute keys and values that are associated with the state_id by using the OAuthMappingExtUtils class:

Keys cannot be null or empty.

Values cannot be null but can be empty.

Associated key-value pairs are read and write-allowed and not-sensitive.

Some keys are reserved for system use and cannot be modified by this utility. For example, the keys and values for the API PIN protection.

associate

public static boolean associate(
   String stateID,
   String attrKey,
   String attrValue
)

This method associates the attribute key-value pair to the authorization grant state ID. Use the following parameters:

stateID - The state ID of the authorization grant. This parameter cannot be null or empty.

attrKey - The attribute key. This parameter cannot be null or empty. The maximum length is 256 characters.

attrValue - The attribute value. This parameter cannot be null. The maximum length is 256 characters.

These responses come from the runtime after association.

True if successful.

False if not successful.

deleteGrant

public static boolean deleteGrant(
   String stateId
)

This method deletes the authorization grant with the given state ID from the token cache. Use the following parameter:

stateId - The state ID of the authorization grant. This parameter cannot be null or empty.

deleteToken

public static Boolean deleteToken (

      String tokenID

)

This method deletes the token from the token cache. Use the following parameter:

tokenID - The token ID of the token to be deleted. This parameter cannot be null or empty.

To limit the number of tokens per user per definition, see OAuth 2.0 token limits.

disassociate

public static String disassociate(
   String stateID,
   String attrKey
)

This method disassociates the attribute key-value pair from the authorization grant state ID. Use the following parameters:

stateID - The state ID of the authorization grant. This parameter cannot be null or empty.

attrKey - The attribute key to disassociate. This parameter cannot be null or empty.

These responses come from the runtime after disassociation.

The previous string value that is associated with the state ID and attribute key if successful.

Null, if not successful. For example, when association is never made.

getAssociation

public static String getAssociation(
   String stateID,
   String attrKey
)

This method gets the attribute value from the authorization grant state ID and attribute key. Use the following parameters:

stateID - The state ID of the authorization grant. This parameter cannot be null or empty.

attrKey - The attribute key value that you want to be returned. This parameter cannot be null or empty.

These responses come from the runtime after it gets the association keys.

The string value that is associated with the state ID and attribute key if successful.

Null, if not successful. For example, when the association is never made.

getAssociationKeys

public static String[] getAssociationKeys(
   String stateID
)

This method gets all the attribute keys that are associated with the authorization grant state ID. Use the following parameter:

stateID - The state ID of the authorization grant. This parameter cannot be null or empty.

These responses come from the runtime after it gets the association keys.

A string array of all attribute keys that are associated with the authorization grant state ID if successful.

Null, if state ID is wrong, if there are problems during retrieval from the token cache, or if there are no associated attributes.

getGrants

public static Grant[] getGrants(
   String username
)

This method gets the authorization grants associated with the given user name from the token cache. Use the following parameter:

username - The user name of the authorization grants. This parameter cannot be null or empty.

These responses come from the runtime after it gets the associated grants:

A grant array of all authorization grants that are associated with the user name if successful.

Null if one of the following conditions exist:

User name is wrong or does not exist.

There are problems during retrieval from the token cache.

There are no associated authorization grants.

getTokens

public static Token[] getTokens(
   String clientId,
   String username
)

This method gets the tokens associated with the given client ID and user name from the token cache. Use the following parameters:

clientId - The client ID of the tokens. This parameter cannot be null or empty.

username - The user name of the tokens. This parameter cannot be null or empty.

These responses come from the runtime after it gets the tokens:

A token array of all tokens that are associated with the client ID and user name, if successful.

Null, if one of the following conditions exist:

Client ID or user name are wrong or do not exist.

There are problems during retrieval from the token cache.

There are no associated tokens.

To limit the number of tokens per user per definition, see OAuth 2.0 token limits.

HTTP GET

public static HttpResponse httpGet(
   String url,
)

This method sends a HTTP GET request. Use the following parameters:

url - The URL to send the GET request.

This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.

HTTP GET

public static HttpResponse httpGet(
   String url,
   Map headers,
   String httpsTrustStore,
   String basicAuthUsername,
   String basicAuthPassword,
   String clientKeyStore,
   String clientKeyAlias
)

This method sends a HTTP GET request. Use the following parameters:

url - The URL to send the GET request.

headers - A map of the headers.

httpsTrustStore - The truststore name. If this parameter is null and SSL connection is required, use the default truststore.

basicAuthUsername - The user name for basic authentication. If this parameter is null, the basic authentication is not enabled.

basicAuthPassword - The password that is used for basic authentication. If null, basic authentication is not enabled.

clientKeyStore - The client keystore name. If this parameter is null, client certificate authentication is not enabled.

clientKeyAlias - The client key alias. If this parameter is null, client certificate authentication is not enabled.

This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.

HTTP POST

public static HttpResponse httpPost(
   String url,
   Map params
)

This method sends a HTTP POST request. Use the following parameters:

url - The URL to send the POST request.

params- A map of the parameters.

This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.

HTTP POST

public static HttpResponse httpPost(
   String url,
   Map headers,
   Map params,
   String httpsTrustStore,
   String basicAuthUsername,
   String basicAuthPassword,
   String clientKeyStore,
   String clientKeyAlias
)

This method sends a HTTP POST request. Use the following parameters:

url - The URL to send the GET request.

headers - A map of the headers.

httpsTrustStore - The truststore name. If this parameter is null and SSL connection is required, use the default truststore.

basicAuthUsername - The user name for basic authentication. If this parameter is null, the basic authentication is not enabled.

basicAuthPassword - The password that is used for basic authentication. If null, basic authentication is not enabled.

clientKeyStore - The client keystore name. If this parameter is null, client certificate authentication is not enabled.

clientKeyAlias - The client key alias. If this parameter is null, client certificate authentication is not enabled.

This request returns an HttpResponse. The request becomes null when there is no response or when it contains wrong parameters.

HTTPResponse

public int getCode()

This method gets the HTTP response code.

This method returns the HttpResponse code. The method returns -1 if the response code is not set.

HTTPResponse

public String getBody()

This method gets the HTTP response body.

This method returns the HTTP response body. The method returns an empty string if the response body is not set.

HTTPResponse

public String[] getHeaderKeys()

This method gets the HTTP response header keys.

This method returns a string array of the HTTP response header keys. This method returns an empty array if there are no headers.

HTTPResponse

public String[] getHeaderValues(
   String key
)

This method gets the HTTP response header values for the key.

This method returns a string array of the HTTP response header values for the key. This method returns an empty array if there is no value for the header key.

isValidUsernamePassword

public static boolean isValidUsernamePassword(
   String username,
   String password
)

This method validates that the given user name and password are valid for the underlying user registry. You must configure the user name and password authentication mechanism before using this method. See Configuring username and password authentication.

Use the following parameters:

username - The user name to validate. This parameter cannot be null or empty.

password - The password of the user name. This parameter cannot be null or empty.

These responses come from the runtime after validation.

True if the user name and password are valid.

False if invalid.

logAuditEvent

public static void logAuditEvent(
         String username,
         String message,
         boolean result
)

This method generates an IBM_SECURITY_CBA_AUDIT_RTE audit event with action-id JAVASCRIPT_EVENT.

You must enable auditing to generate this audit event. See Configuring auditing.

Use the following parameters:

username - The user information to include in the audit record; it might be null.

message - The message to include in the audit record.

result - A Boolean value to indicate if the operation being audited was successful.

throwSTSException

public static void throwSTSException(
   String message
)

This method returns an STSException. Use the following parameter:

message - The message to be printed with the stack trace in the application log. A generic response is returned to the client. The input message that is passed can only be logged and is not visible to the client.

throwSTSUserMessageException

public static void throwSTSUserMessageException(
   String message
)

This method returns an STSUserMessageException. Use the following parameter:

message - The message to be printed with the stack trace in the application log and returned in the response to the client. The input message is logged and visible to the client.

For more information, see the Javadoc in Manage System Settings > Secure Settings > File Downloads > access_control > doc.

Parent topic: OAuth 2.0 support

Customizing OAuth tokens by updating the sample PreTokenGeneration mapping ruleYou can customize the format of the tokens that are issued by your OAuth definition. The OAuth tokens can be customized by modifying the sample PreTokenGeneration mapping rule. Enable the PreTokenGeneration mapping rule on the appliance by setting the variable enable_custom_tokens to true. When custom token formats are used, the tokens must remain unique. Otherwise, users might become authenticated with another user's credential. Thus, it is recommended that custom tokens always contain a nonce of reasonable entropy. To customize the authorization code, insert an attribute into the STSUU with the type "urn:ibm:ITFIM:oauth20:custom:token" and the name "urn:ibm:ITFIM:oauth20:custom:token:authorization_code". The provided value will be used as the authorization code if an authorization code would have been issued in this request. To customize the access token, insert an attribute into the STSUU with the type "urn:ibm:ITFIM:oauth20:custom:token" and the name"urn:ibm:ITFIM:oauth20:custom:token:access_token". The provided value will be used as the access token if an access token would have been issued as part of this request. To customize the refresh token, insert an attribute into the STSUU with the type "urn:ibm:ITFIM:oauth20:custom:token" and the name"urn:ibm:ITFIM:oauth20:custom:token:refresh_token". The provided value will be used as the refresh token if a refresh token would have been issued as part of this request. OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

Customizing OAuth tokens by updating the sample PreTokenGeneration mapping rule

You can customize the format of the tokens that are issued by your OAuth definition.

The OAuth tokens can be customized by modifying the sample PreTokenGeneration mapping rule. Enable the PreTokenGeneration mapping rule on the appliance by setting the variable enable_custom_tokens to true.

When custom token formats are used, the tokens must remain unique. Otherwise, users might become authenticated with another user's credential. Thus, it is recommended that custom tokens always contain a nonce of reasonable entropy.

To customize the authorization code, insert an attribute into the STSUU with the type "urn:ibm:ITFIM:oauth20:custom:token" and the name "urn:ibm:ITFIM:oauth20:custom:token:authorization_code". The provided value will be used as the authorization code if an authorization code would have been issued in this request.

To customize the access token, insert an attribute into the STSUU with the type "urn:ibm:ITFIM:oauth20:custom:token" and the name"urn:ibm:ITFIM:oauth20:custom:token:access_token". The provided value will be used as the access token if an access token would have been issued as part of this request.

To customize the refresh token, insert an attribute into the STSUU with the type "urn:ibm:ITFIM:oauth20:custom:token" and the name"urn:ibm:ITFIM:oauth20:custom:token:refresh_token". The provided value will be used as the refresh token if a refresh token would have been issued as part of this request.

Parent topic: OAuth 2.0 support

OAuth 2.0 token limitsYou can define limits on the number of OAuth tokens per user per definition so that the high-volume database does not go beyond capacity.OAuth token limittokenslimit in OAuthOAuth PreTokenGeneration mapping rulemapping rulesOAuth PreTokenGenerationoauth_20_pre_mapping.js mapping ruleOverview Security Access Manager for Mobile has a thread that runs at a specified interval defined by the advanced configuration property, oauth20.tokenCache.cleanupWait. This property defines the amount of time, in seconds, to wait before it performs another cleanup of expired grants and tokens in the OAuth 2.0 token cache. Depending on the interval and use of OAuth grants and tokens, there is a possibility that the capacity of the high-volume database can be reached before the cleanup process runs. If this happens, the appliance can be negatively impacted. To prevent issues such as this, the OAuth PreTokenGeneration mapping rule, by default, limits the number of OAuth tokens per user per client definition. When a user requests an OAuth token, the current number of tokens for that user and the specified client definition will be compared to the maximum allowed. If the maximum is exceeded, an error message is returned to the user. An additional algorithm implements least recently used (LRU) and, if the maximum is exceeded, the least recently used token determined by the date last used for that user and client definition will be removed from the high-volume database.Changing values in the mapping rule file You can set the limit and algorithm to use, which are controlled by variables in the mapping rule file. Two algorithms are implemented in this mapping rule: Strictly enforce the limit.When the limit is reached, remove the least recently used tokens for the user per client. Update the OAuth PreTokenGeneration mapping rule, oauth_20_pre_mapping.js, to define the following variables: OAuth PreTokenGeneration mapping rule variables for token limitsVariableDefault valueDescriptionmax_oauth_tokens_per_user_per_client20Specify an integer for the maximum number of tokens allowed on a per user per client basis.strict_limittrueStrictly enforce the limit. The OAuth flow is stopped and an error message is returned.To disable a strict limit, set the value to false.least_recently_usedfalseRemove the least recently used token once the limit is reached. The OAuth flow continues.limit_oauth_tokens_per_user_per_clienttrueEnforce a limit for the number of tokens on a per user per client basis.To disable limiting the number of tokens allowed, set the value to false. See Managing OAuth 2.0 mapping rulesUse the mapping rules to customize the methods for the OAuth 2.0 flow. for instructions on replacing a mapping rule after you make the updates to the file. See Updating PreTokenGeneration to limit OAuth tokensUpdate the latest version of the PreTokenGeneration mapping rule to limit the number of OAuth tokens per user per definition. so that any API protection definitions you created in versions prior to 8.0.1.2 can take advantage of these limits. OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

OAuth 2.0 token limits

You can define limits on the number of OAuth tokens per user per definition so that the high-volume database does not go beyond capacity.

Overview

Security Access Manager for Mobile has a thread that runs at a specified interval defined by the advanced configuration property, oauth20.tokenCache.cleanupWait. This property defines the amount of time, in seconds, to wait before it performs another cleanup of expired grants and tokens in the OAuth 2.0 token cache.

Depending on the interval and use of OAuth grants and tokens, there is a possibility that the capacity of the high-volume database can be reached before the cleanup process runs. If this happens, the appliance can be negatively impacted.

To prevent issues such as this, the OAuth PreTokenGeneration mapping rule, by default, limits the number of OAuth tokens per user per client definition. When a user requests an OAuth token, the current number of tokens for that user and the specified client definition will be compared to the maximum allowed. If the maximum is exceeded, an error message is returned to the user.

An additional algorithm implements least recently used (LRU) and, if the maximum is exceeded, the least recently used token determined by the date last used for that user and client definition will be removed from the high-volume database.

Changing values in the mapping rule file

You can set the limit and algorithm to use, which are controlled by variables in the mapping rule file. Two algorithms are implemented in this mapping rule:

Strictly enforce the limit.

When the limit is reached, remove the least recently used tokens for the user per client.

Update the OAuth PreTokenGeneration mapping rule, oauth_20_pre_mapping.js, to define the following variables:

Table 80. OAuth PreTokenGeneration mapping rule variables for token limits

Variable
Default value
Description

max_oauth_tokens_per_user_per_client
20
Specify an integer for the maximum number of tokens allowed on a per user per client basis.

strict_limit
true
Strictly enforce the limit. The OAuth flow is stopped and an error message is returned.

To disable a strict limit, set the value to false.

least_recently_used
false
Remove the least recently used token once the limit is reached. The OAuth flow continues.

limit_oauth_tokens_per_user_per_client
true
Enforce a limit for the number of tokens on a per user per client basis.

To disable limiting the number of tokens allowed, set the value to false.

See Managing OAuth 2.0 mapping rules for instructions on replacing a mapping rule after you make the updates to the file.

See Updating PreTokenGeneration to limit OAuth tokens so that any API protection definitions you created in versions prior to 8.0.1.2 can take advantage of these limits.

Parent topic: OAuth 2.0 support

OAuth 2.0 template filesThe OAuth process relies on HTML pages to interact with users, such as displaying errors or prompting users to provide information. You can customize these pages through the OAuth template files.For information aboutOAuth template files, see Template filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors..OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

OAuth 2.0 template files

The OAuth process relies on HTML pages to interact with users, such as displaying errors or prompting users to provide information. You can customize these pages through the OAuth template files.

For information aboutOAuth template files, see Template files.

Parent topic: OAuth 2.0 support

Error responsesError responsesHTTP error responsesAn HTTP response indicates the type of error that has occurred when an action in an authorization process fails. The error responses described here are only applicable to Policy Enforcement Point (PEP) error responses. OAuth HTTP error responseserror messagesOAuth HTTPFor more information about OAuth 2.0 error responses for other endpoints, see the OAuth website: http://www.oauth.net.In some circumstances, the following HTTP error responses must be returned to the client:400 Bad Request 401 Unauthorized 502 Bad GatewayFor the 401 response, an additional WWW-Authenticate header is added to the response in the following format:WWW-Authenticate: OAuth realm = <realm-name>The HTML component of the responses is preinstalled from files that have been specified in the EAS configuration.For details on how to configure the response template files for OAuth EAS, see Configuring WebSEAL to include OAuth decisions.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

Error responses

An HTTP response indicates the type of error that has occurred when an action in an authorization process fails. The error responses described here are only applicable to Policy Enforcement Point (PEP) error responses.

For more information about OAuth 2.0 error responses for other endpoints, see the OAuth website: http://www.oauth.net.

In some circumstances, the following HTTP error responses must be returned to the client:

400 Bad Request

401 Unauthorized

502 Bad Gateway

For the 401 response, an additional WWW-Authenticate header is added to the response in the following format:

WWW-Authenticate: OAuth realm = <realm-name>

The HTML component of the responses is preinstalled from files that have been specified in the EAS configuration.

For details on how to configure the response template files for OAuth EAS, see Configuring WebSEAL to include OAuth decisions.

Parent topic: OAuth 2.0 support

User self-administration tasks for OAuthUser self-administration tasks for OAuthUser self-administration tasks for OAuthAdministrators can configure OAuth to enable users to perform certain self-management tasks.user self-administrationA common user task is to manage authorization grants. For example, users can view the attributes of an authorization grant. A user can also enable an authorization grant.OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.Managing OAuth 2.0 authorization grants You can view your authorization grants and the tokens and attributes of each authorization grant.

User self-administration tasks for OAuth

Administrators can configure OAuth to enable users to perform certain self-management tasks.

A common user task is to manage authorization grants. For example, users can view the attributes of an authorization grant. A user can also enable an authorization grant.

Managing OAuth 2.0 authorization grants
You can view your authorization grants and the tokens and attributes of each authorization grant.

Parent topic: OAuth 2.0 support

Managing OAuth 2.0 authorization grantsManaging OAuth 2.0 authorization grantsManaging OAuth 2.0 authorization grants You can view your authorization grants and the tokens and attributes of each authorization grant.device fingerprints managingYou can complete the following tasks: View a list of your OAuth 2.0 authorization grants.View the OAuth 2.0 tokens and attributes of an authorization grant.Remove an OAuth 2.0 authorization grant.Enable an OAuth 2.0 authorization grant.Disable an OAuth 2.0 authorization grant.Take one of the following actions: View your OAuth 2.0 authorization grants and the tokens and attributes of each authorization grant Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html. Click the ID from the table to view the tokens and attributes of that authorization grant. You can also use the following URL to go directly to the tokens and attributes of a specific authorization grant: http://hostname/mga/sps/mga/user/mgmt/html/device/grant_attributes.html?id=x. The query string, id=x, indicates the authorization grant that you are trying to access. The x represents the ID of the authorization grant.Remove an OAuth 2.0 authorization grant Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html. Click Remove next to the authorization grant that you want to remove. Enable an OAuth 2.0 authorization grant Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html. Select the Enabled box next to the authorization grant that you want to enable. Disable an OAuth 2.0 authorization grant Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html. Clear the Enabled box next to the authorization grant that you want to disable. Authorization grants can be enabled, disabled, or removed in the authorization grant attribute page too.User self-administration tasks for OAuthAdministrators can configure OAuth to enable users to perform certain self-management tasks.

Managing OAuth 2.0 authorization grants

You can view your authorization grants and the tokens and attributes of each authorization grant.

About this task

You can complete the following tasks:

View a list of your OAuth 2.0 authorization grants.

View the OAuth 2.0 tokens and attributes of an authorization grant.

Remove an OAuth 2.0 authorization grant.

Enable an OAuth 2.0 authorization grant.

Disable an OAuth 2.0 authorization grant.

Procedure

Take one of the following actions:

View your OAuth 2.0 authorization grants and the tokens and attributes of each authorization grant

Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html.

Click the ID from the table to view the tokens and attributes of that authorization grant.

Note: You can also use the following URL to go directly to the tokens and attributes of a specific authorization grant: http://hostname/mga/sps/mga/user/mgmt/html/device/grant_attributes.html?id=x.

The query string, id=x, indicates the authorization grant that you are trying to access. The x represents the ID of the authorization grant.

Remove an OAuth 2.0 authorization grant

Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html.

Click Remove next to the authorization grant that you want to remove.

Enable an OAuth 2.0 authorization grant

Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html.

Select the Enabled box next to the authorization grant that you want to enable.

Disable an OAuth 2.0 authorization grant

Log in to http://hostname/mga/sps/mga/user/mgmt/html/device/device_selection.html.

Clear the Enabled box next to the authorization grant that you want to disable.

Note: Authorization grants can be enabled, disabled, or removed in the authorization grant attribute page too.

Parent topic: User self-administration tasks for OAuth

OAuth STS Interface for Authorization Enforcement PointsOAuth STS Interface for Authorization Enforcement PointsOAuth STS Interface for Authorization Enforcement PointsUse the WS-Trust interface to directly contact an OAuth Security Token Service (STS) trust chain in Security Access Manager to validate a request for an OAuth protected resource. An OAuth enforcement point intercepts requests for OAuth protected resources. The OAuth enforcement point also validates the request with Security Access Manager, and passes the request through, if it is valid. If the request is not valid, the enforcement point denies access to the protected resource.OAuth STS interface ID: Sarah Liu| SME: Stephen Viselli, Simon Canning| Apr 2011| Created this new topic for “RTC 23971, IDD for OAuth 2.0: About OAuth 2.0".OAuth STS overviewYou can develop your own customized policy enforcement point to work with the Security Token Service (STS) trust chain through the STS interface. Some examples of existing customized policy enforcement points are WebSphere Servlet Filter, Trust Association Interceptor (TAI), and a reverse proxy such as WebSEAL. As Security Access Manager supports OAuth 2.0 federations, you can develop customized policy enforcement points to work with OAuth 2.0 federations. The following diagram illustrates the relationship between the OAuth STS trust chain and other OAuth components. OAuth STS trust chain workflowOAuth STS trust chain workflowThis section describes the process an OAuth enforcement point undertakes to transform an HTTP request for an OAuth protected resource into a WS-Trust message. The transformation makes it possible for the STS to validate the request. It also describes the possible responses an enforcement point can receive from the STS and how to deal with them. The following information about the policy decision point in Security Access Manager must be made available to the enforcement point:The absolute URL of the Security Access Manager STS trust service endpoint. (For example: https://isam.com/TrustServer/SecurityTokenService)The basic authentication user name and password for the Security Access Manager STS trust service (if required).The ProviderID of the Security Access Manager federation the client belongs to, which is used as the AppliesTo address for WS-Trust requests. Optionally, the enforcement point accepts a provider ID from the OAuth client as a request parameter to serve more than one federation concurrently.Authorization decision requestConfigurationFor OAuth 2.0 requests, the enforcement point must know the Security Access Manager OAuth 2.0 issuer address prefix (urn:ibm:ITFIM:oauth20:token:).HTTP requestWhen an OAuth 2.0 client retrieves a protected resource with its access token, it constructs a request similar to any of the following examples. Each of these three examples is logically the same request. All that differs is the transmission mechanism (HTTP header, query string, post body) for sending the OAuth 2.0 bearer access token:OAuth 2.0 Example 1 (Access token in authorization header)POST /oauth/protectedresource.jsp Host: isam.com Authorization: Bearer YPxa78JggdW7hvcFRJph Content-Type: application/x-www-form-urlencoded username=steveOAuth 2.0 Example 2 (Access token in post body)POST /oauth/protectedresource.jsp Host: isam.com Content-Type: application/x-www-form-urlencoded username=steve&access_token=YPxa78JggdW7hvcFRJph OAuth 2.0 Example 3 (Access token in query string)POST /oauth/protectedresource.jsp?access_token=YPxa78JggdW7hvcFRJph Host: isam.com Content-Type: application/x-www-form-urlencoded username=steveAuthorization decision requestThe OAuth 2.0 enforcement point is responsible for the following actions: Transform HTTP requests into a WS-Trust SOAP message.Send the WS-Trust SOAP message to the Security Access Manager STS for request validation.The HTTP request is transformed into the following WS-Trust SOAP message:OAuth 2.0 Token Validate Request (Request Security Token)<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <wst:RequestSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"> <wst:RequestType xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"> http://schemas.xmlsoap.org/ws/2005/02/trust/Validate </wst:RequestType> <wst:Issuer xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"> <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004 /08/addressing"> urn:ibm:ITFIM:oauth20:token:bearer </wsa:Address> </wst:Issuer> <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004 /09/policy"> <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap .org/ws/2004/08/addressing"> <wsa:Address>https://localhost/sps/oauth/oauth20/2</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:Base xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal/> <stsuuser:AttributeList/> <stsuuser:ContextAttributes> <stsuuser:Attribute name="access_token" type="urn:ibm:names:ITFIM:oauth:param"> <stsuuser:Value>YPxa78JggdW7hvcFRJph</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="username" type="urn:ibm:names:ITFIM:oauth:body:param"> <stsuuser:Value>steve</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="port" type="urn:ibm:names:ITFIM:oauth:request"> <stsuuser:Value>9443</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="method" type="urn:ibm:names:ITFIM:oauth:request"> <stsuuser:Value>POST</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="path" type="urn:ibm:names:ITFIM:oauth:request"> <stsuuser:Value>/oauth/protectedresource.jsp</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="scheme" type="urn:ibm:names:ITFIM:oauth:request"> <stsuuser:Value>https</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="host" type="urn:ibm:names:ITFIM:oauth:request"> <stsuuser:Value>isam.com</stsuuser:Value> </stsuuser:Attribute> </stsuuser:ContextAttributes> </stsuuser:STSUniversalUser> </wst:Base> </wst:RequestSecurityToken> </soapenv:Body> </soapenv:Envelope>The following attributes are defined by the WS-Trust specification. They are used by Security Access Manager to identify the federation that is associated with this request and to identify the type of OAuth 2.0 access token being used.The Issuer address element (highlighted in bold) must be set to the Security Access Manager OAuth 2.0 issuer address prefix (urn:ibm:ITFIM:oauth20:token:). The token type must be appended at the end and separated by a colon. Currently, the only token supported type is bearer, which means the issuer address must be set to urn:ibm:ITFIM:oauth20:token:bearer.The AppliesTo address element (highlighted in italics) must match the Provider ID of the API Protection Definition within Security Access Manager. The general form is https://localhost/sps/oauth/oauth20/{id}. The access_token attribute with type urn:ibm:names:ITFIM:oauth:param is mandatory in the WS-Trust message sent to Security Access Manager. It must be appended to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token. If access_token attribute is missing from the request from the OAuth 2.0 client, the enforcement point does not validate the request with Security Access Manager STS. It can instantly return an HTTP 400 Bad Request status code and optionally can include a description of the error in the body. If the access token is included in the authorization header in the Authorization: Bearer <token> format, the token must still be added to the ContextAttributes section of the STSUU. The same format must be used as if the access token was sent through a query string or post body.The following attributes are not mandatory in the WS-Trust message that is sent to Security Access Manager STS for OAuth 2.0. However, they might be useful to a custom mapping rule that is executed by Security Access Manager. It is recommended to append the following attributes to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token and set the attribute type to urn:ibm:names:ITFIM:oauth:request. method - the HTTP method of the request (GET/POST)scheme - (http/https) host - host header from the request port - the port number on the host (only if it is a non-standard port. For example, not 80 if the method is HTTP or not 443 if the method is HTTPS)path - the requested pathAppend any additional parameters that the OAuth 2.0 enforcement point finds in the request, such as query or post body parameters that are not of OAuth 2.0, to the Context Attribute section of the STSUniversalUser within the WS-Trust Request Security Token. The type value is determined by the following table. In OAuth 2.0 requests, these parameters are not required. However, they might be useful to a custom mapping rule that is executed by Security Access Manager. So it is recommended that you append them.HTTP Parameter LocationAttribute Type ValueURL Query String Parametersurn:ibm:names:ITFIM:oauth:query:paramHTTP Request Body Parametersurn:ibm:names:ITFIM:oauth:body:paramPost body parameters must be included only if the following conditions are met:The entity-body is single-part.The entity-body follows the encoding requirements of the application/x-www-form-urlencodedcontent-type as defined by [W3C.REC-html40-19980424].The HTTP request entity-header includes the Content-Type header field set to application/x-www-form-urlencoded.Authorization decision responseThe SOAP message response from Security Access Manager (regardless of OAuth version) echoes all the context attributes sent in the original request and some extra response context attributes.OAuth Token Validate Response (RSTR)<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <wst:RequestSecurityTokenResponse wsu: Id="uuid56a54e7c-012f-1207-9133-c24cad886d75" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401 -wss-wssecurity-utility-1.0.xsd"> <wsp:AppliesTo xmlns:wsa="http://schemas.xmlsoap.org/ws/2004 /08/addressing" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <wsa:EndpointReference> <wsa:Address>https://localhost/sps/oauth/oauth20/2</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:RequestedSecurityToken> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names :ITFIM:1.0:stsuuser"> <stsuuser:Principal/> <stsuuser:AttributeList/> <stsuuser:ContextAttributes> <stsuuser:Attribute name="authorized" type="urn:ibm:names:ITFIM:oauth:response:decision"> <stsuuser:Value>TRUE</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="expires" type="urn:ibm :names:ITFIM:oauth:response:decision"> <stsuuser:Value>2011-04-22T00:52:18Z</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="scope" type="urn:ibm :names:ITFIM:oauth:response:attribute"> <stsuuser:Value>email</stsuuser:Value> <stsuuser:Value>first</stsuuser:Value> <stsuuser:Value>last</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="username" type="urn:ibm :names:ITFIM:oauth:response:attribute"> <stsuuser:Value>wasadmin</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="username_is_self" type="urn:ibm:names:ITFIM:oauth:response:attribute"> <stsuuser:Value>FALSE</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="oauth_token" type="urn:ibm :names:ITFIM:oauth:response:attribute"> <stsuuser:Value>YPxa78JggdW7hvcFRJph</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="recovered_state" type="urn:ibm :names:ITFIM:oauth:response:attribute"> <stsuuser:Value>State storage time was: 2011-04-15T00:52:18Z</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="state_id" type="urn:ibm :names:ITFIM:oauth:state"> <stsuuser:Value>2cJsZ3QhXV5rDVZHNePp</stsuuser:Value> </stsuuser:Attribute> </stsuuser:ContextAttributes> <stsuuser:AdditionalAttributeStatement id=""/> </stsuuser:STSUniversalUser> </wst:RequestedSecurityToken> <wst:Status> <wst:Code>http://schemas.xmlsoap.org/ws/2005/02/trust/status /valid</wst:Code> </wst:Status> </wst:RequestSecurityTokenResponse> </soapenv:Body> </soapenv:Envelope>The following context attributes returned to the enforcement point by Security Access Manager relate to the authorization decision. It also has the attribute type urn:ibm:names:ITFIM:oauth:response:decision highlighted in italics in the previous RSTR example. It is up to the enforcement point to decide whether to down-stream these attributes to the OAuth protected resource. These attributes are primarily for the use of the enforcement point itself to determine the authorization status.Context attributesDescriptionauthorizedThe value is set to TRUE if the OAuth request is valid and authorized; FALSE if otherwise.expiresThe UTC time when the access token that is used in the request is no longer valid. The following context attributes returned to the enforcement point by Security Access Manager must be down-streamed from the enforcement point to the OAuth protected resource. They might be appended to the original HTTP request in any way deemed suitable by the enforcement point and the protected resource. This way, the protected resource can retrieve them (for example, as additional HTTP headers). These context attributes have the attribute type urn:ibm:names:ITFIM:oauth:response:attribute (highlighted in bold in the previous RSTR example). Custom mapping rules that are executed after the OAuth trust chain might also append attributes with this type. Therefore, any attribute with this type must be down-streamed to the requested protected resource.Context attributesDescriptionaccess_tokenThe OAuth access token that is used in the protected resource request.client_typeThe type of client that this token was issued to, can be either public or confidential. Public clients are clients that do not have client credentials and therefore cannot authenticate to the authorization server.oauth_token_client_idThe unique identifier of the client to which the current access token was issued. scopeA list of strings that represents the resource scope that is authorized by the user at the OAuth resource owner authorization step. The OAuth protected resource can use this attribute to determine which resources to return in the response. This attribute is only present for OAuth flows that include a user authorization step.usernameThe name of the user who authorized the OAuth token to access their protected resources on their behalf. With OAuth flows that do not involve a separate resource owner, this value is the client identifier.Additional attributes with the type urn:ibm:names:ITFIM:oauth:response:attribute are sometimes appended by a custom mapping rule, such is the case with recovered_state and username_is_self in the example.The state_id context attribute returned to the enforcement point by Security Access Manager is used by a custom mapping rule that is executed after the OAuth trust chain. It has the attribute type urn:ibm:names:ITFIM:oauth:state (highlighted with an underline) and can be ignored by the enforcement point.The state_id attribute is a unique identifier for the current OAuth token that is used to store state information.If the state_id attribute is required by the OAuth protected resource, a custom mapping rule can be implemented to make a copy of this attribute. The type can be changed to urn:ibm:names:ITFIM:oauth:response:attribute from the custom mapping rule to ensure that it is down-streamed to the resource.Error responsesYou can customize the amount of OAuth request validation that the enforcement point performs. Any validation it performs is repeated by Security Access Manager. Doing some validation before sending an authorization request to Security Access Manager might improve performance. The following validation must be performed by the enforcement point before sending a request to Security Access Manager.Validate that some OAuth data is present. If not, return an HTTP 401 Unauthorized status code.Validate that none of the required OAuth parameters are missing. If any of them are not present in the request, return an HTTP 400 Bad Request status code.Validate that none of the required OAuth parameters occur more than once in the request. They must also occur only in the one component of the request; for example, the query string or the authorization header. If the validation fails, return an HTTP 400 Bad Request status code. The enforcement point must return an HTTP 401 Unauthorized status code to the OAuth client if the following scenario occurs: The enforcement point receives a SOAP message with an authorized context attribute that has a value of FALSE.The enforcement point must return an HTTP 503 Service Unavailable status code to the OAuth client if the following scenarios occur:Security Access Manager encounters an error.Security Access Manager does not return a constructed SOAP message or the SOAP message does not contain an authorized context attribute.The enforcement point might also optionally return a WWW-Authenticate HTTP header to indicate its support for OAuth.Flow chartThe following chart shows the expected workflow of an OAuth authorization enforcement point.OAuth authorization enforcement point workflowOAuth authorization enforcement point workflowOAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.

OAuth STS Interface for Authorization Enforcement Points

Use the WS-Trust interface to directly contact an OAuth Security Token Service (STS) trust chain in Security Access Manager to validate a request for an OAuth protected resource. An OAuth enforcement point intercepts requests for OAuth protected resources. The OAuth enforcement point also validates the request with Security Access Manager, and passes the request through, if it is valid. If the request is not valid, the enforcement point denies access to the protected resource.

OAuth STS overview

You can develop your own customized policy enforcement point to work with the Security Token Service (STS) trust chain through the STS interface. Some examples of existing customized policy enforcement points are WebSphere® Servlet Filter, Trust Association Interceptor (TAI), and a reverse proxy such as WebSEAL. As Security Access Manager supports OAuth 2.0 federations, you can develop customized policy enforcement points to work with OAuth 2.0 federations. The following diagram illustrates the relationship between the OAuth STS trust chain and other OAuth components.

Figure 61. OAuth STS trust chain workflowOAuth STS trust chain workflow

This section describes the process an OAuth enforcement point undertakes to transform an HTTP request for an OAuth protected resource into a WS-Trust message.

The transformation makes it possible for the STS to validate the request. It also describes the possible responses an enforcement point can receive from the STS and how to deal with them.

The following information about the policy decision point in Security Access Manager must be made available to the enforcement point:

The absolute URL of the Security Access Manager STS trust service endpoint. (For example: https://isam.com/TrustServer/SecurityTokenService)

The basic authentication user name and password for the Security Access Manager STS trust service (if required).

The ProviderID of the Security Access Manager federation the client belongs to, which is used as the AppliesTo address for WS-Trust requests. Optionally, the enforcement point accepts a provider ID from the OAuth client as a request parameter to serve more than one federation concurrently.

Authorization decision request

Configuration

For OAuth 2.0 requests, the enforcement point must know the Security Access Manager OAuth 2.0 issuer address prefix (urn:ibm:ITFIM:oauth20:token:).

HTTP request

When an OAuth 2.0 client retrieves a protected resource with its access token, it constructs a request similar to any of the following examples. Each of these three examples is logically the same request. All that differs is the transmission mechanism (HTTP header, query string, post body) for sending the OAuth 2.0 bearer access token:

OAuth 2.0 Example 1 (Access token in authorization header)

POST /oauth/protectedresource.jsp
  Host: isam.com
  Authorization: Bearer YPxa78JggdW7hvcFRJph
  Content-Type: application/x-www-form-urlencoded

username=steve

OAuth 2.0 Example 2 (Access token in post body)

POST /oauth/protectedresource.jsp
  Host: isam.com
  Content-Type: application/x-www-form-urlencoded

username=steve&access_token=YPxa78JggdW7hvcFRJph

OAuth 2.0 Example 3 (Access token in query string)

POST /oauth/protectedresource.jsp?access_token=YPxa78JggdW7hvcFRJph
  Host: isam.com
  Content-Type: application/x-www-form-urlencoded

username=steve

Authorization decision request

The OAuth 2.0 enforcement point is responsible for the following actions:

Transform HTTP requests into a WS-Trust SOAP message.

Send the WS-Trust SOAP message to the Security Access Manager STS for request validation.

The HTTP request is transformed into the following WS-Trust SOAP message:

OAuth 2.0 Token Validate Request (Request Security Token)

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SOAP-ENV:Body>
        <wst:RequestSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
            <wst:RequestType xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
            </wst:RequestType>
            <wst:Issuer xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004
                /08/addressing">
                    urn:ibm:ITFIM:oauth20:token:bearer
                </wsa:Address>
            </wst:Issuer>
            <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004
            /09/policy">
                <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap
                .org/ws/2004/08/addressing">
                    <wsa:Address>https://localhost/sps/oauth/oauth20/2</wsa:Address>
                </wsa:EndpointReference>
            </wsp:AppliesTo>
            <wst:Base xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust">
                <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
                    <stsuuser:Principal/>
                    <stsuuser:AttributeList/>
                    <stsuuser:ContextAttributes>
                        <stsuuser:Attribute name="access_token"
                          type="urn:ibm:names:ITFIM:oauth:param">
                            <stsuuser:Value>YPxa78JggdW7hvcFRJph</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="username"
                          type="urn:ibm:names:ITFIM:oauth:body:param">
                            <stsuuser:Value>steve</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="port"
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>9443</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="method"
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>POST</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="path"
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>/oauth/protectedresource.jsp</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="scheme"
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>https</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="host"
                          type="urn:ibm:names:ITFIM:oauth:request">
                            <stsuuser:Value>isam.com</stsuuser:Value>
                        </stsuuser:Attribute>
                   </stsuuser:ContextAttributes>
                </stsuuser:STSUniversalUser>
            </wst:Base>
        </wst:RequestSecurityToken>
    </soapenv:Body>
</soapenv:Envelope>

The following attributes are defined by the WS-Trust specification. They are used by Security Access Manager to identify the federation that is associated with this request and to identify the type of OAuth 2.0 access token being used.

The Issuer address element (highlighted in bold) must be set to the Security Access Manager OAuth 2.0 issuer address prefix (urn:ibm:ITFIM:oauth20:token:). The token type must be appended at the end and separated by a colon. Currently, the only token supported type is bearer, which means the issuer address must be set to urn:ibm:ITFIM:oauth20:token:bearer.

The AppliesTo address element (highlighted in italics) must match the Provider ID of the API Protection Definition within Security Access Manager. The general form is https://localhost/sps/oauth/oauth20/{id}.

The access_token attribute with type urn:ibm:names:ITFIM:oauth:param is mandatory in the WS-Trust message sent to Security Access Manager. It must be appended to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token.

If access_token attribute is missing from the request from the OAuth 2.0 client, the enforcement point does not validate the request with Security Access Manager STS. It can instantly return an HTTP 400 Bad Request status code and optionally can include a description of the error in the body.

Note: If the access token is included in the authorization header in the Authorization: Bearer <token> format, the token must still be added to the ContextAttributes section of the STSUU. The same format must be used as if the access token was sent through a query string or post body.

The following attributes are not mandatory in the WS-Trust message that is sent to Security Access Manager STS for OAuth 2.0. However, they might be useful to a custom mapping rule that is executed by Security Access Manager.

It is recommended to append the following attributes to the ContextAttributes section of the STSUniversalUser within the WS-Trust Request Security Token and set the attribute type to urn:ibm:names:ITFIM:oauth:request.

method - the HTTP method of the request (GET/POST)

scheme - (http/https)

host - host header from the request

port - the port number on the host (only if it is a non-standard port. For example, not 80 if the method is HTTP or not 443 if the method is HTTPS)

path - the requested path

Append any additional parameters that the OAuth 2.0 enforcement point finds in the request, such as query or post body parameters that are not of OAuth 2.0, to the Context Attribute section of the STSUniversalUser within the WS-Trust Request Security Token. The type value is determined by the following table.

In OAuth 2.0 requests, these parameters are not required. However, they might be useful to a custom mapping rule that is executed by Security Access Manager. So it is recommended that you append them.

HTTP Parameter Location | Attribute Type Value
URL Query String Parameters | urn:ibm:names:ITFIM:oauth:query:param
HTTP Request Body Parameters | urn:ibm:names:ITFIM:oauth:body:param

Post body parameters must be included only if the following conditions are met:

The entity-body is single-part.

The entity-body follows the encoding requirements of the "application/x-www-form-urlencoded"content-type as defined by [W3C.REC-html40-19980424].

The HTTP request entity-header includes the "Content-Type" header field set to "application/x-www-form-urlencoded".

Authorization decision response

The SOAP message response from Security Access Manager (regardless of OAuth version) echoes all the context attributes sent in the original request and some extra response context attributes.

OAuth Token Validate Response (RSTR)

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SOAP-ENV:Body>
        <wst:RequestSecurityTokenResponse wsu:
        Id="uuid56a54e7c-012f-1207-9133-c24cad886d75"
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401
        -wss-wssecurity-utility-1.0.xsd">
            <wsp:AppliesTo xmlns:wsa="http://schemas.xmlsoap.org/ws/2004
            /08/addressing"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
                <wsa:EndpointReference>
                    <wsa:Address>https://localhost/sps/oauth/oauth20/2</wsa:Address>
                </wsa:EndpointReference>
            </wsp:AppliesTo>
            <wst:RequestedSecurityToken>
                <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names
                :ITFIM:1.0:stsuuser">
                    <stsuuser:Principal/>
                    <stsuuser:AttributeList/>
                    <stsuuser:ContextAttributes>
                        <stsuuser:Attribute name="authorized"
                        type="urn:ibm:names:ITFIM:oauth:response:decision">
                            <stsuuser:Value>TRUE</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="expires" type="urn:ibm
                        :names:ITFIM:oauth:response:decision">
                            <stsuuser:Value>2011-04-22T00:52:18Z</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="scope" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                                <stsuuser:Value>email</stsuuser:Value>
                                <stsuuser:Value>first</stsuuser:Value>
                                <stsuuser:Value>last</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="username" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>wasadmin</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="username_is_self"
                        type="urn:ibm:names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>FALSE</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="oauth_token" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>YPxa78JggdW7hvcFRJph</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="recovered_state" type="urn:ibm
                        :names:ITFIM:oauth:response:attribute">
                            <stsuuser:Value>State storage time was:
                            2011-04-15T00:52:18Z</stsuuser:Value>
                        </stsuuser:Attribute>
                        <stsuuser:Attribute name="state_id" type="urn:ibm
                        :names:ITFIM:oauth:state">
                            <stsuuser:Value>2cJsZ3QhXV5rDVZHNePp</stsuuser:Value>
                        </stsuuser:Attribute>
                    </stsuuser:ContextAttributes>
                    <stsuuser:AdditionalAttributeStatement id=""/>
                </stsuuser:STSUniversalUser>
            </wst:RequestedSecurityToken>
            <wst:Status>
                <wst:Code>http://schemas.xmlsoap.org/ws/2005/02/trust/status
                /valid</wst:Code>
            </wst:Status>
        </wst:RequestSecurityTokenResponse>
    </soapenv:Body>
</soapenv:Envelope>

The following context attributes returned to the enforcement point by Security Access Manager relate to the authorization decision. It also has the attribute type urn:ibm:names:ITFIM:oauth:response:decision highlighted in italics in the previous RSTR example. It is up to the enforcement point to decide whether to down-stream these attributes to the OAuth protected resource.

These attributes are primarily for the use of the enforcement point itself to determine the authorization status.

Context attributes | Description
authorized | The value is set to TRUE if the OAuth request is valid and authorized; FALSE if otherwise.
expires | The UTC time when the access token that is used in the request is no longer valid.

The following context attributes returned to the enforcement point by Security Access Manager must be down-streamed from the enforcement point to the OAuth protected resource. They might be appended to the original HTTP request in any way deemed suitable by the enforcement point and the protected resource. This way, the protected resource can retrieve them (for example, as additional HTTP headers).

These context attributes have the attribute type urn:ibm:names:ITFIM:oauth:response:attribute (highlighted in bold in the previous RSTR example).

Custom mapping rules that are executed after the OAuth trust chain might also append attributes with this type. Therefore, any attribute with this type must be down-streamed to the requested protected resource.

Context attributes
Description

access_token
The OAuth access token that is used in the protected resource request.

client_type
The type of client that this token was issued to, can be either public or confidential. Public clients are clients that do not have client credentials and therefore cannot authenticate to the authorization server.

oauth_token_client_id
The unique identifier of the client to which the current access token was issued.

scope
A list of strings that represents the resource scope that is authorized by the user at the OAuth resource owner authorization step. The OAuth protected resource can use this attribute to determine which resources to return in the response. This attribute is only present for OAuth flows that include a user authorization step.

username
The name of the user who authorized the OAuth token to access their protected resources on their behalf. With OAuth flows that do not involve a separate resource owner, this value is the client identifier.

Additional attributes with the type urn:ibm:names:ITFIM:oauth:response:attribute are sometimes appended by a custom mapping rule, such is the case with recovered_state and username_is_self in the example.

The state_id context attribute returned to the enforcement point by Security Access Manager is used by a custom mapping rule that is executed after the OAuth trust chain. It has the attribute type urn:ibm:names:ITFIM:oauth:state (highlighted with an underline) and can be ignored by the enforcement point.

The state_id attribute is a unique identifier for the current OAuth token that is used to store state information.

If the state_id attribute is required by the OAuth protected resource, a custom mapping rule can be implemented to make a copy of this attribute. The type can be changed to urn:ibm:names:ITFIM:oauth:response:attribute from the custom mapping rule to ensure that it is down-streamed to the resource.

Error responses

You can customize the amount of OAuth request validation that the enforcement point performs. Any validation it performs is repeated by Security Access Manager. Doing some validation before sending an authorization request to Security Access Manager might improve performance. The following validation must be performed by the enforcement point before sending a request to Security Access Manager.

Validate that some OAuth data is present. If not, return an HTTP 401 Unauthorized status code.

Validate that none of the required OAuth parameters are missing. If any of them are not present in the request, return an HTTP 400 Bad Request status code.

Validate that none of the required OAuth parameters occur more than once in the request. They must also occur only in the one component of the request; for example, the query string or the authorization header. If the validation fails, return an HTTP 400 Bad Request status code.

The enforcement point must return an HTTP 401 Unauthorized status code to the OAuth client if the following scenario occurs:

The enforcement point receives a SOAP message with an authorized context attribute that has a value of FALSE.

The enforcement point must return an HTTP 503 Service Unavailable status code to the OAuth client if the following scenarios occur:

Security Access Manager encounters an error.

Security Access Manager does not return a constructed SOAP message or the SOAP message does not contain an authorized context attribute.

The enforcement point might also optionally return a WWW-Authenticate HTTP header to indicate its support for OAuth.

Flow chart

The following chart shows the expected workflow of an OAuth authorization enforcement point.

Figure 62. OAuth authorization enforcement point workflow

Parent topic: OAuth 2.0 support

Mobile Multi-Factor AuthenticationThe IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol. Authenticator applications are mobile-based applications that enable users to authenticate with minimal reliance on passwords. Mobile devices and biometric characteristics are used to support authentication and reduce the threat of unauthorized access to sensitive resources.The IBM Verify application, which is available for download in major mobile application stores, is natively supported by the Advanced Access Control component. The authenticator application is built on the Security Access Manager SDK, which is available for download from the appliance File Downloads area. The Security Access Manager SDK can also be used to create custom applications.The authenticators framework can be integrated with context-based access and authentication policies. Security Access Manager provides several pre-defined authentication policies to enable combinations of mobile and biometric mechanisms.The authenticator application registration is built around an OAuth grant that is issued to the mobile device. The grant is used to identify the authenticator in future requests.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Authenticator registrationThe IBM Verify application uses the OAuth authorization grant flow to perform registration, which is launched by the user in a browser. Authentication method enrollmentAfter an authenticator is registered, the user is prompted to enroll authentication methods. Configuring Mobile Multi-Factor AuthenticationFollow these steps to configure Mobile Muli-Factor Authentication.MMFA mapping rule methodsCustomize the OAuth PreTokenGeneration and PostTokenGeneration mapping rules by using these methods.

Mobile Multi-Factor Authentication

The IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol.

Authenticator applications are mobile-based applications that enable users to authenticate with minimal reliance on passwords. Mobile devices and biometric characteristics are used to support authentication and reduce the threat of unauthorized access to sensitive resources.

The IBM Verify application, which is available for download in major mobile application stores, is natively supported by the Advanced Access Control component. The authenticator application is built on the Security Access Manager SDK, which is available for download from the appliance File Downloads area. The Security Access Manager SDK can also be used to create custom applications.

The authenticators framework can be integrated with context-based access and authentication policies. Security Access Manager provides several pre-defined authentication policies to enable combinations of mobile and biometric mechanisms.

The authenticator application registration is built around an OAuth grant that is issued to the mobile device. The grant is used to identify the authenticator in future requests.

Authenticator registration
The IBM Verify application uses the OAuth authorization grant flow to perform registration, which is launched by the user in a browser.

Authentication method enrollment
After an authenticator is registered, the user is prompted to enroll authentication methods.

Configuring Mobile Multi-Factor Authentication
Follow these steps to configure Mobile Muli-Factor Authentication.

MMFA mapping rule methods
Customize the OAuth PreTokenGeneration and PostTokenGeneration mapping rules by using these methods.

Parent topic: Advanced Access Control configuration

Authenticator registrationThe IBM Verify application uses the OAuth authorization grant flow to perform registration, which is launched by the user in a browser. A button to initiate the registration flow is available in the device_selection.html page, which is an example page that demonstrates how the registration might be initiated. This page is available from the appliance File Downloads area at the path access_control/pages/C/mga/user/mgmt/device/device_selection.html. When the button is clicked, it calls the OAuth authorize endpoint to obtain an authorization code. The user is then presented with a QR code that can be scanned by the IBM Verify application to complete registration. The following steps illustrate a typical authenticator registration flow.The user downloads and installs the IBM Verify application.The user logs in to the Security Access Manager User Self Care (USC) with a desktop browser and clicks a button on the page that is presented by USC to initiate the registration flow.The browser starts the OAuth authorization code flow.Security Access Manager responds with a QR code.The user scans the QR code with the IBM Verify application.The IBM Verify application completes the registration automatically.The Security Access Manager SDK supports registration without the need for browser initiation in custom applications and also supports the OAuth ROPC flow.Authentication registration is completed when an OAuth flow is completed with the scope set to mmfaAuthn. Other attributes that can be included and saved via the OAuth mapping rule are:Push token IDApplication IDDevice NameDevice TypeOS VersionFingerprint support includedFront camera support includedTenant IDMobile Multi-Factor AuthenticationThe IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol.

Authenticator registration

The IBM Verify application uses the OAuth authorization grant flow to perform registration, which is launched by the user in a browser.

A button to initiate the registration flow is available in the device_selection.html page, which is an example page that demonstrates how the registration might be initiated. This page is available from the appliance File Downloads area at the path access_control/pages/C/mga/user/mgmt/device/device_selection.html.

When the button is clicked, it calls the OAuth authorize endpoint to obtain an authorization code. The user is then presented with a QR code that can be scanned by the IBM Verify application to complete registration. The following steps illustrate a typical authenticator registration flow.

The user downloads and installs the IBM Verify application.

The user logs in to the Security Access Manager User Self Care (USC) with a desktop browser and clicks a button on the page that is presented by USC to initiate the registration flow.

The browser starts the OAuth authorization code flow.

Security Access Manager responds with a QR code.

The user scans the QR code with the IBM Verify application.

The IBM Verify application completes the registration automatically.

The Security Access Manager SDK supports registration without the need for browser initiation in custom applications and also supports the OAuth ROPC flow.

Authentication registration is completed when an OAuth flow is completed with the scope set to "mmfaAuthn". Other attributes that can be included and saved via the OAuth mapping rule are:

Push token ID

Application ID

Device Name

Device Type

OS Version

Fingerprint support included

Front camera support included

Tenant ID

Parent topic: Mobile Multi-Factor Authentication

Authentication method enrollmentAfter an authenticator is registered, the user is prompted to enroll authentication methods. Supported authentication methods include fingerprint and simple user presence. Enrollment is performed through the System for Cross-Domain Identity Management (SCIM) API. For more information, see SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. .Mobile Multi-Factor AuthenticationThe IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol.

Authentication method enrollment

After an authenticator is registered, the user is prompted to enroll authentication methods.

Supported authentication methods include fingerprint and simple user presence.

Enrollment is performed through the System for Cross-Domain Identity Management (SCIM) API. For more information, see SCIM configuration.

Parent topic: Mobile Multi-Factor Authentication

Configuring Mobile Multi-Factor AuthenticationFollow these steps to configure Mobile Muli-Factor Authentication.The following pre-requisites must be met:The IBM Security Access Manager Platform and Advanced Access Control Module are activated.The runtime component and a reverse proxy instance are configured.Basic User support is enabled on the local LDAP.Transparent path junction to /scim on localhost is configured.BA with easuser enabledisam_mobile_rest ACL attached to /scim (ACL won't exist until step 2)Username Password Mechanism is configured.Server connection to local LDAP is set up.SCIM is configured with local LDAP server connection dc=iswga suffix.Create an API Protection definition and client with:Authorization code and ROPC enabledRedirect URI: https://<webseal_hostname>:<port>/mga/sps/mmfa/user/mgmt/html/mmfa/qr_code.html?client_id=<client_ID> The redirect URI is essential so that when a user clicks the Register Authenticator button in the USC UI, the user is correctly redirected to the QR Code page.Run the Reverse Proxy MMFA Config API.This step configures the /mga junction and creates the required ACLs. curl -ki -H 'Accept: application/json' -H 'Content-type:application/json' --user 'admin:XXXX' -X POST https:// 192.168.124.130/wga/reverseproxy/default/mmfa_config -d '{"lmi":{"hostname":"192.168.124.130", "port":443, "username":"admin", "password":"XXXX"}, "runtime":{"hostname":"localhost", "port":443, "username":"easuser", "password":"XXXX"}, "reuse_certs":false, "reuse_acls":false, "reuse_pops":false}’Run the AAC MMFA Config API.This step configures the reverse proxy details into a location where the AAC code can access it. curl -ki -H 'Accept: application/json' -H 'Content-type: application/json' --user 'admin:XXXX' -X POST https://192.168.124.130/iam/access/v8/mmfa-config -d '{"client_id":"AuthenticatorClient", "hostname":"192.168.124.140", "port":443, "junction":"/mga"}'Mobile Multi-Factor AuthenticationThe IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol.

Configuring Mobile Multi-Factor Authentication

Follow these steps to configure Mobile Muli-Factor Authentication.

Before you begin

The following pre-requisites must be met:

The IBM Security Access Manager Platform and Advanced Access Control Module are activated.

The runtime component and a reverse proxy instance are configured.

Basic User support is enabled on the local LDAP.

Transparent path junction to /scim on localhost is configured.

BA with easuser enabled

isam_mobile_rest ACL attached to /scim (ACL won't exist until step 2)

Username Password Mechanism is configured.

Server connection to local LDAP is set up.

SCIM is configured with local LDAP server connection dc=iswga suffix.

Procedure

Create an API Protection definition and client with:

Authorization code and ROPC enabled

Redirect URI: https://<webseal_hostname>:<port>/mga/sps/mmfa/user/mgmt/html/mmfa/qr_code.html?client_id=<client_ID>

Note:

The redirect URI is essential so that when a user clicks the Register Authenticator button in the USC UI, the user is correctly redirected to the QR Code page.

Run the Reverse Proxy MMFA Config API.

This step configures the /mga junction and creates the required ACLs.

curl -ki -H 'Accept: application/json' -H
'Content-type:application/json' --user 'admin:XXXX' -X POST https://
192.168.124.130/wga/reverseproxy/default/mmfa_config -d
'{"lmi":{"hostname":"192.168.124.130", "port":443, "username":"admin",
"password":"XXXX"}, "runtime":{"hostname":"localhost", "port":443,
"username":"easuser", "password":"XXXX"}, "reuse_certs":false,
"reuse_acls":false, "reuse_pops":false}’

Run the AAC MMFA Config API.

This step configures the reverse proxy details into a location where the AAC code can access it.

curl -ki -H 'Accept: application/json' -H
'Content-type: application/json' --user 'admin:XXXX' -X POST
https://192.168.124.130/iam/access/v8/mmfa-config -d
'{"client_id":"AuthenticatorClient",
"hostname":"192.168.124.140",
"port":443, "junction":"/mga"}'

Parent topic: Mobile Multi-Factor Authentication

MMFA mapping rule methodsCustomize the OAuth PreTokenGeneration and PostTokenGeneration mapping rules by using these methods.Sample mapping rules are available from Manage System SettingsSecure SettingsFile Downloads under the access_control examplesmapping rules directory.The following limitations affect the attribute keys and values that are associated with the state_id by using the MMFAMappingExtUtils class:Keys cannot be null or empty.Values can only be null or empty when specified.Associated key-value pairs are read-only and not case sensitive.The push token is read-only and case sensitive.registerAuthenticatorpublic static String registerAuthenticator( String stateId ) This method performs the final steps of registering an authenticator. Use the following parameters: stateIdThe state ID of the authorization grant. This parameter cannot be null or empty. These responses come from the runtime after registration. The new authenticator's ID if successful.Null if not successful.savePushTokenpublic static boolean savePushToken( String stateId, String pushToken, String applicationID ) This method saves the push token and application ID with the authorization grant state ID. Use the following parameters: stateId The state ID of the authorization grant. This parameter cannot be null or empty.pushTokenThe push token the authenticator application has received from its push notification service provider. This parameter cannot be null or empty. applicationID The application ID of the authenticator application. This parameter can be null or empty. These responses come from the runtime. True if successful.False if not successful. savePushTokenpublic static boolean savePushToken( String stateId, String pushToken ) This method saves the push token and application ID with the authorization grant state ID. Use the following parameters: stateIdThe state ID of the authorization grant. This parameter cannot be null or empty.pushTokenThe push token the authenticator application has received from its push notification service provider. This parameter cannot be null or empty. These responses come from the runtime. True if successful.False if not successful. saveDeviceAttributespublic static boolean saveDeviceAttributes( String stateId, String deviceName, String deviceType, String osVersion, String fingerprintSupport, String frontCameraSupport, String tenantId ) This method saves various device attributes with the authorization grant state ID. Use the following parameters: stateId The state ID of the authorization grant. This parameter cannot be null or empty.deviceNameThe name of the device the authenticator is installed on. This parameter can be null or empty. If empty, the value is cleared.deviceTypeThe type of the device the authenticator is installed on. This parameter can be null or empty. If empty, the value is cleared.osVersionThe OS version of the device the authenticator is installed on. This parameter can be null or empty. If empty, the value is cleared.fingerprintSupportThe type of fingerprint sensor that is supported by the device. This parameter can be null or empty. If empty, the value is cleared.frontCameraSupportflag that indicates if the device has a front facing camera. This parameter can be null or empty. If empty, the value is cleared.tenantIdThe tenant ID for this registration, if the authenticator application is multi-tenant. This parameter can be null or empty. If empty, the value is cleared. These responses come from the runtime. True if successful.False if not successful.Mobile Multi-Factor AuthenticationThe IBM Security Access Manager Advanced Access Control component supports authenticator applications. Such support is built around the OAuth 2.0 protocol.

MMFA mapping rule methods

Customize the OAuth PreTokenGeneration and PostTokenGeneration mapping rules by using these methods.

Sample mapping rules are available from Manage System Settings > Secure Settings > File Downloads under the access_control > examples > mapping rules directory.

The following limitations affect the attribute keys and values that are associated with the state_id by using the MMFAMappingExtUtils class:

Keys cannot be null or empty.

Values can only be null or empty when specified.

Associated key-value pairs are read-only and not case sensitive.

The push token is read-only and case sensitive.

registerAuthenticator

public static String registerAuthenticator(
      String stateId
      )

This method performs the final steps of registering an authenticator. Use the following parameters:

stateId

The state ID of the authorization grant. This parameter cannot be null or empty.

These responses come from the runtime after registration.

The new authenticator's ID if successful.

Null if not successful.

savePushToken

public static boolean savePushToken(
      String stateId,
      String pushToken,
      String applicationID
      )

This method saves the push token and application ID with the authorization grant state ID. Use the following parameters:

stateId

The state ID of the authorization grant. This parameter cannot be null or empty.

pushToken

The push token the authenticator application has received from its push notification service provider. This parameter cannot be null or empty.

applicationID

The application ID of the authenticator application. This parameter can be null or empty.

These responses come from the runtime.

True if successful.

False if not successful.

savePushToken

public static boolean savePushToken(
      String stateId,
      String pushToken
      )

This method saves the push token and application ID with the authorization grant state ID. Use the following parameters:

stateId

The state ID of the authorization grant. This parameter cannot be null or empty.

pushToken

The push token the authenticator application has received from its push notification service provider. This parameter cannot be null or empty.

These responses come from the runtime.

True if successful.

False if not successful.

saveDeviceAttributes

public static boolean saveDeviceAttributes(
      String stateId,
      String deviceName,
      String deviceType,
      String osVersion,
      String fingerprintSupport,
      String frontCameraSupport,
      String tenantId
      )

This method saves various device attributes with the authorization grant state ID. Use the following parameters:

stateId

The state ID of the authorization grant. This parameter cannot be null or empty.

deviceName

The name of the device the authenticator is installed on. This parameter can be null or empty. If empty, the value is cleared.

deviceType

The type of the device the authenticator is installed on. This parameter can be null or empty. If empty, the value is cleared.

osVersion

The OS version of the device the authenticator is installed on. This parameter can be null or empty. If empty, the value is cleared.

fingerprintSupport

The type of fingerprint sensor that is supported by the device. This parameter can be null or empty. If empty, the value is cleared.

frontCameraSupport

flag that indicates if the device has a front facing camera. This parameter can be null or empty. If empty, the value is cleared.

tenantId

The tenant ID for this registration, if the authenticator application is multi-tenant. This parameter can be null or empty. If empty, the value is cleared.

These responses come from the runtime.

True if successful.

False if not successful.

Parent topic: Mobile Multi-Factor Authentication

Defining a custom domain for policy attachmentsDefining a custom domain for policy attachmentsDefining a custom domain for policy attachmentsThe administrator can specify a custom domain to separate metadata in a registry. For example, your company might possess metadata that belongs to several companies, and it is a security demand that the data does not overlap.custom domain definingpolicy attachmentspolicy attachmentsdefining a custom domain The policy attachment credential automatically selects the default management domain in all supported versions of IBM Tivoli Access Manager when you integrate it with the IBM Security Access Manager local management interface. You must choose one domain to use for policy attachments. Log in to the local management interface. Specify the Tivoli Access Manager administrator credentials when you create a new reverse proxy instance: Select Secure Web Settings > Manage > Reverse Proxy> New. Select the IBM Security Access Manager tab. Specify the following administrator credentials. These credentials must be the same as the ones that you use to attach a policy to a domain other than the default.Administrator NameAdministrator Password Domain You can choose to specify a custom secure domain in the IBM Security Access Manager tab. However, if you choose not to specify a domain, the domain field defers to the default. Select Secure Access Control >Policy> Access Control > Resources. Click . Enter the information that you specified in 2.c at Policy Server Login. You can reset the credentials that you just defined with the setCredential parameter under the following conditions: You upgrade to IBM Security Access Manager, version 8.0.0.4 or later.You want to manage a domain name other than the default. Before you reset the setCredential parameter, remove all current resources and their corresponding policy attachments. For more information about this command, go to the REST API documentation and select Policy Attachments > Resources > Authenticate with Security Access Manager.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Defining a custom domain for policy attachments

The administrator can specify a custom domain to separate metadata in a registry. For example, your company might possess metadata that belongs to several companies, and it is a security demand that the data does not overlap.

About this task

The policy attachment credential automatically selects the default management domain in all supported versions of IBM® Tivoli® Access Manager when you integrate it with the IBM Security Access Manager local management interface. You must choose one domain to use for policy attachments.

Procedure

Log in to the local management interface.

Specify the Tivoli Access Manager administrator credentials when you create a new reverse proxy instance:

Select Secure Web Settings > Manage > Reverse Proxy> Add New.

Select the IBM Security Access Manager tab.

Specify the following administrator credentials. These credentials must be the same as the ones that you use to attach a policy to a domain other than the default.

Administrator Name

Administrator Password

Domain

Note: You can choose to specify a custom secure domain in the IBM Security Access Manager tab. However, if you choose not to specify a domain, the domain field defers to the default.

Select Secure Access Control >Policy> Access Control > Resources.

Click Add attribute.

Enter the information that you specified in 2.c at Policy Server Login.

What to do next

You can reset the credentials that you just defined with the setCredential parameter under the following conditions:

You upgrade to IBM Security Access Manager, version 8.0.0.4 or later.

You want to manage a domain name other than the default.

Before you reset the setCredential parameter, remove all current resources and their corresponding policy attachments. For more information about this command, go to the REST API documentation and select Policy Attachments > Resources > Authenticate with Security Access Manager.

Parent topic: Advanced Access Control configuration

Managing advanced configurationAdjust configuration settings in supported configuration files.configurationadvancedThe advanced configuration panel displays a table of configuration settings. Some can be modified and some are read-only. Each setting is displayed as a row in the table. The name of the setting is listed in the key column. The current value of the key is listed in the value column.You can locate a setting by using one of the following methods:Scroll through the list until you see the setting.By default, all configuration settings are included in the list.Filter the list by entering a string in the Filter field.When you enter a string, the list is modified to show only the settings that contain the specified string.Filter the list by selecting a category from the Filter by Category menu. For descriptions of the categories and properties, see Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..Select Secure Access Control Global SettingsAdvanced ConfigurationTo edit a key, select the edit icon edit icon for the key.You cannot edit keys that are marked with the read-only icon: read only icon.When you choose to edit a key, a new window displays the name of the key and the current value.Edit the value as appropriate for your deployment.Configuration data typesData typeActionIntegersUse the arrow icons to increment or decrement the value. Alternatively, you can type a new value in the text field. StringsEnter a string value in the text field.Text fields must have a value. You cannot specify an empty field. To clear values from a field, enter NULL.BooleansSelect the check box to set the value to true. Clear the check box to set the value to false. Click OK.Deploy the changes.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Managing advanced configuration

Adjust configuration settings in supported configuration files.

About this task

The advanced configuration panel displays a table of configuration settings. Some can be modified and some are read-only. Each setting is displayed as a row in the table. The name of the setting is listed in the key column. The current value of the key is listed in the value column.

You can locate a setting by using one of the following methods:

Scroll through the list until you see the setting.

By default, all configuration settings are included in the list.

Filter the list by entering a string in the Filter field.

When you enter a string, the list is modified to show only the settings that contain the specified string.

Filter the list by selecting a category from the Filter by Category menu. For descriptions of the categories and properties, see Advanced configuration properties.

Procedure

Select Secure Access Control > Global Settings > Advanced Configuration

To edit a key, select the edit icon edit icon for the key.

Note: You cannot edit keys that are marked with the read-only icon: read only icon.

When you choose to edit a key, a new window displays the name of the key and the current value.

Edit the value as appropriate for your deployment.

Table 81. Configuration data types.

Data type
Action

Integers
Use the arrow icons to increment or decrement the value. Alternatively, you can type a new value in the text field.

Strings
Enter a string value in the text field.

Note: Text fields must have a value. You cannot specify an empty field. To clear values from a field, enter NULL.

Booleans
Select the check box to set the value to true. Clear the check box to set the value to false.

Click OK.

Deploy the changes.

Parent topic: Advanced Access Control configuration

Advanced configuration propertiesAdvanced configuration propertiesAdvanced configuration propertiesModify the advanced configurations to meet the requirements of your organization.advanced configurationproperty descriptionsadvanced configurationcategory filterCategory filterThe category filter displays names of grouping of configuration settings. The groupings correspond to functional areas. When you select a category, the user interface displays only the settings for the category.Filter by CategoryCategoryDisplays values for: AllAll keyspoc.signInWebSEAL Sign-In Callbackpoc.websealAuthWebSEAL Authenticate Callbackpoc.otpAuthOne-time password Authenticate Callbackpoc.authPolicyAuthentication-Policy Callbacksps.httpRequestClaimsSPS HTTP request claimsdistributedMapDistributed shared data storageuserBehaviorAttribute matcher propertiesipReputationIP reputation PIP propertiesattributeCollectionAttribute collector propertiesdeviceRegistrationDevice registration propertiesruntimeRuntime propertiessps.pageSPS pagespsSingle sign-on protocol serviceriskEngineRisk engine propertiessps.authServiceAuthentication service propertiessessionSessiondistributedSessionCacheDistributed session cacheotp.retryTOTP and HOTP retry propertiesoauth20OAuth20util.httpClientHTTP clientdemoDemoknowledge.questionsKnowledge questions propertieskessKey encryption and signing service (KESS)jwksJSON Web KeypipPolicy information point (PIP)stsSecurity token service (STS)mmfaMobile Multi-Factor Authentication (MMFA)WebSEAL Sign-In Callbackpoc.signIn.serverResponseHeaderThe name of the header that contains the hostname that authenticates the user.Data type: StringExample: fim.serverWebSEAL Authenticate Callbackpoc.websealAuth.authLevelThe authentication level of the callback.Data type: IntegerExample: 1One-time password Authenticate Callbackpoc.otp.authLevelThe authentication level of the callback.Data type: IntegerExample: 2poc.otp.backwardCompatibilityEnabledIndicates whether the one-time password authentication mechanism should run in backward compatibility mode. The default value is false if it is a new installation. The default value is true if the installation is an upgrade.Data type: BooleanExample: trueAuthentication-Policy Callbackpoc.authPolicy.allowRequestOverrideWhether the authentication level, the authentication mode, and the authentication type of the callback can be overwritten by query string parameters.Data type: BooleanExample: truepoc.authPolicy.authLevelThe authentication level of the callback.Data type: IntegerExample: 1poc.authPolicy.authTypeThe authentication type of the callback.Data type: StringExample: COMPLEMENTARY, HIERARCHICALSPS HTTP request claimssps.httpRequestClaims.enabledWhether HTTP request information is sent to STS as HTTPRequestClaims.Data type: BooleanExample:falsesps.httpRequestClaims.filterSpecThe filter that specifies the HTTP request information that is sent to STS as HTTPRequestClaims.Data type: StringExample: cookies=*:headers=*Distributed shared data storagedistributedMap.cleanupWaitThe amount of time, in milliseconds, to wait before it performs another cleanup against the distributed map.Data type: Integer Example: 10000distributedMap.defaultTTLThe amount of time, in seconds, that the entries in the distributed map must live when no lifetime is specified for an entry.Data type: Integer Example: 3600distributedMap.getRetryDelayThe amount of time, in milliseconds, to wait before it performs another retrieval against the distributed map. The default is 0. Data type: Integer Example: 500distributedMap.getRetryLimitThe number of retrievals that is done against the distributed map before it returns that the retrieved data is not in the distributed map. The default is 0. Data type: Integer Example: 10Attribute matcher propertiesuserBehavior.minimumUsageHistoryRequiredMinimum usage data records required for any usage data analysis; used by LoginTimeMatcher.Data type: IntegerExample: 8userBehavior.ipAddressRequestAttributeThe XACML request attribute to read from the IP address.Data type: StringExample: urn:ibm:security:subject:ipAddress IP reputation PIP properties ip.reputation.ipAddressAdverseReputationThresholdThe value that an IP classification score must be at or above for an IP address to be considered as that classification.Data type: IntegerExample:50ipReputation.dbConnectionTimeout Indicates the number of seconds that the IP reputation policy information point (PIP) waits for a connection to the IP reputation database. The ipReputation.dbConnectionTimeout property defaults to 120.Data type: IntegerExample: 60 Attribute collector propertiesattributeCollection.cookieNameCorrelation ID used by the attribute collector.Data type: StringExample: ac.uuidattributeCollection.requestServerRequest server for attribute collector. A list of the allowable hosts where the ajaxRequest can be sent from.Data type: String ListExample: https://rbademo.example.com,https://rbaemo2.example.comattributeCollection.serviceLocationLocation of the attribute collector.Data type: String ListExample: http://rbademo.example.com/mgaattributeCollection.sessionTimeoutNumber of seconds in which sessions stored in context-based access will automatically expire, unless updated. If any attribute in the session is updated, the session expiry is extended by the specified number of seconds configured in this property. The default is 1800 seconds.Data type: IntegerExample: 1800 secondsattributeCollection.enableGetAttributesEnables the REST GET method to return attributes.Data type: BooleanExample: falseattributeCollection.getAttributesAllowedClientsA comma-separated list of clients that are allowed to access the ACS REST GET method.If this property is not set and attributeCollection.enableGetAttributes is set to true, anyone can access the GET method. If this property is set but attributeCollection.enableGetAttributes is set to false, this property is ignored.Data type: String ListExample: hostname1, hostname2attributeCollection.hashAlgorithmThe algorithm that is used to create the hash.Data type: StringExample: SHA256attributeCollection.attributesHashEnabledA comma-separated list of attribute URI values configured for hashing. Do not hash the following attributes:ipAddressgeoLocationaccessTimeData type: String ListExample:urn:ibm:security:environment:http:userAgent, urn:ibm:security:environment:deviceFonts, urn:ibm:security:environment:browserPlugins attributeCollection.authenticationContextAttributesComma-separated lists of attribute names to be collected during an authentication service obligation. The maximum number of characters for this property is 200.Data type: String ListExample: authenticationLevel, http:host Device registration propertiesdeviceRegistration.allowIncompleteFingerprintsSpecifies to allow the device registration obligation to store fingerprints where all the fingerprint attributes are not available on the session information.Data type: BooleanExample: falsedeviceRegistration.checkForExpiredDevices Determines whether registered devices are inactive or expired. If the deviceRegistration.checkForExpiredDevices property is set to true, the risk engine checks whether a device is inactive or expired. The deviceRegistration.checkForExpiredDevices property defaults to false, which means that users can use any of the devices that are registered.Date type: BooleanExample: truedeviceRegistration.cleanupThread.batchSizeSpecifies if batch delete is enabled for expired devices and how many records are deleted per batch. If the value is defined as 0 or is blank, batch delete is not enabled and all expired devices are deleted using one SLQ delete statement.If the value is defined as an integer greater than 0, batch delete is enabled. The number that you specify determines how many records are deleted in each batch. The batch delete continues until all of the expired devices are deleted. The batch process is useful for deleting a large quantity of expired devices.Data type: IntegerExample: 1000 (Batch delete is enabled, with a batch size of 1000 records.)deviceRegistration.deviceMatchThresholdThe risk score threshold where an existing fingerprint is considered to match the incoming device fingerprint.Data type: IntegerExample: 20deviceRegistration.inactiveExpirationTimeSpecifies the number of days that a device must be inactive for it to expire. The deviceRegistration.inactiveExpirationTime property defaults to 90. Date type: IntegerExample: 100deviceRegistration.maxRegisteredDevicesMaximum device fingerprint count. The default is 10. Valid values are 1 to 100.Data type: IntegerExample: 10deviceRegistration.maxUsageDataPerUserMaximum number of historical usage attribute records stored per user. The default is 200. Valid values are 1 to 5000.Data type: IntegerExample: 1000deviceRegistration.permitOnIncompleteFingerprintsSpecifies to permit access to the resource if the fingerprint collected by the device registration obligation does not include all fingerprint attributes.Data type: BooleanExample: falseRuntime propertiesruntime.dbLoggingEnabledEnables fine-grained logging for database SQL statements.Data type: BooleanExample: falseruntime.hashAlgorithmThe algorithm that is used for hashing. The supported algorithms are:SHA-1SHA-256SHA-512The runtime.hashAlgorithm property defaults to SHA-256.Data type: StringExample: SHA-256Single sign-on protocol service sps.setCookiesAsSecureDetermine whether to flag the cookies set by Security Access Manager as secure.The default value is false.Data type: BooleanExample: falseSPS pagesps.page.htmlEscapedMacrosA comma-separated list of macros that is HTML-escaped when it is rendered in pages that are sent to the browser.Data type: StringExample:@REQ_ADDR@, @DETAIL@, @EXCEPTION_STACK@, @EXCEPTION_MSG@, @OTP_METHOD_ID@, @OTP_METHOD_LABEL@, @OTP_HINT@, @ERROR_MESSAGE@, @MAPPING_RULE_DATA@sps.page.exceptionMacrosA comma-separated list of classname:macro pairs. Classname is the fully qualified name of the exception class. Macro is the name of the macro to which the class maps.Data type: StringExample:com.tivoli.am.fim.otp.deliveries.OTPDeliveryException = @OTP_DELIVERY_EXCEPTION@, com.tivoli.am.fim.otp.providers.OTPProviderException = @OTP_PROVIDER_EXCEPTION@Risk engine propertiesriskEngine.reportsEnabledEnables the generation of risk calculation reports.Data type: BooleanExample: falseriskEngine.reportsMaxStoredSpecifies the maximum number of reports to store.Data type: IntegerExample: 5Authentication service propertiessps.authService.reauthenticationEnabledSpecifies that the authentication service performs authentication even if the user already has an authenticated session at the required authentication level.Data type: BooleanExample: trueSessiondistributedSessionCache.enabledA switch that dictates if the distributed session cache is used for session failover. If this setting is not enabled, the distributed session cache server still runs as a service, but the client does not use it.Data type: BooleanExample: falsedistributedSessionCache.localCacheSizeThe number of sessions to be stored on the client as a local cache. A value of 0 or less means that any number of sessions can be cached by the client. A low number requires more connections to the distributed session cache if there are many active sessions. A high number runs the risk of running out of memory if many sessions are locally cached. All sessions are still stored on the distributed session cache when it is enabled. Data type: IntegerExample: 4096session.dbCleanupIntervalSpecifies the interval, in seconds, that the database cleanup thread runs to remove expired data in the runtime database. The default is 86400. The minimum value for this property is 3600. For more information, see Runtime database tuning parametersTo improve performance, you can configure the database tuning parameters for Advanced Access Control.Data type: IntegerExample: 90000Distributed session cachedistributedSessionCache.enabledA switch that dictates if the distributed session cache is used for session failover. If this setting is not enabled, the distributed session cache server still runs as a service, but the client does not use it.Data type: BooleanExample: falsedistributedSessionCache.localCacheSizeThe number of sessions to be stored on the client as a local cache. A value of 0 or less means that any number of sessions can be cached by the client. A low number requires more connections to the distributed session cache if there are many active sessions. A high number runs the risk of running out of memory if many sessions are locally cached. All sessions are still stored on the distributed session cache when it is enabled. Data type: IntegerExample: 4096TOTP and HOTP retry propertiesotp.retry.enabledWhether the retry protection is enabled.Data type: BooleanExample: trueotp.retry.maxNumberOfAttemptsThe maximum number of strikes the users can have before they are prevented from logging in.Data type: IntegerExample: 5otp.retry.otpRetryTimeoutThe number in seconds a strike lasts.Data type: IntegerExample: 600 OAuth20 oauth20.cleanupThread.batchSizeSpecifies if batch delete is enabled for expired OAuth 2.0 tokens and how many records are deleted per batch. If the value is defined as 0 or is blank, batch delete is not enabled and all expired OAuth tokens are deleted using one SQL delete statement.If the value is defined as an integer greater than 0, batch delete is enabled. The number that you specify determines how many records are deleted in each batch. The batch delete continues until all of the expired OAuth tokens are deleted. The batch process is useful for deleting a large quantity of expired tokens.Data type: IntegerExample: 1000 (Batch delete is enabled, with a batch size of 1000 records.)oauth20.clientDataToIncludeSpecifies the OAuth client information to be returned as JSON data. This property is a comma-separated list of the JSON Keys. Valid values are:contact_type email_address contact_person company_name company_url phone_number other_info You can specify one or more of these keys for this property.The oauth20.clientDataToInclude property defaults to contact_type, email_address, contact_person, company_name, company_url, phone_number, other_info.Data type: StringExample: contact_type, email_address, company_nameoauth20.doNotSendXFrameOptionsHeaderSpecifies whether an X-Frame-Options header with value SAMEORIGIN must be returned from the OAuth 2.0 endpoints. When set to true, no X-Frame-Options header is sent.The oauth20.doNotSendXFrameOptionsHeader property defaults to false.Data type: BooleanExample: falseoauth20.hashedTokenStorageEnabledEnables hashed storage when set to true. The Security Access Manager appliance can persist OAuth 2.0 tokens in the clear text form or in the more secure hashed form. The oauth20.hashedTokenStorageEnabled property defaults to false, and the OAuth 2.0 tokens will be stored as-is.Data type: BooleanExample: falseoauth20.sessionEndpointEnabledEnables the ability to return an authenticated session at the point-of-contact when the oauth20.sessionEndpointEnabled property is set to true. The oauth20.sessionEndpointEnabled property defaults to false.Data type: BooleanExample: falseoauth20.tokenCache.cleanupWaitThe amount of time, in seconds, to wait before it performs another cleanup of expired tokens in the OAuth 2.0 token cache.The oauth20.tokenCache.cleanupWait property defaults to 120.Data type: IntegerExample: 120 HTTP client util.httpClient.defaultTrustStoreStores the default truststore that HTTPS connections in HTTP client uses.The util.httpClient.TrustStore property defaults to rt_profile_keys.Data type: StringExample: rt_profile_keysutil.httpClient.defaultSSLProtocolStores the default SSL protocol configuration that HTTPS connections in HTTP client uses.The util.httpClient.defaultSSLProtocol property defaults to TLS.Data type: StringExample: TLS Demolive.demos.enabledEnables the mobile demonstration application.Data type: BooleanExample: False Knowledge questions properties knowledge.questions.AnswerValidationRegExSpecifies the regular expression used to validate the knowledge question answer value provided during a knowledge question management operation. The assigned value is the list of invalid characters to match against to determine if the supplied value is valid.At a minimum, this property must include the following characters: <>:"Data type: RegExExample: [\[()<>,;:\\/\"\]=]knowledge.questions.QuestionValidationRegExSpecifies the regular expression used to validate the knowledge question text value provided during a knowledge question management operation. The assigned value is the list of invalid characters to match against to determine if the supplied value is valid.At a minimum, this property must include the following characters: <>:"Data type: RegExExample: [\[()<>,;:\\/\"\]=] Key encryption and signing service (KESS) kess.crlEnabledChecks the certificate revocation list. Checking is done by the key encryption and signature service (KESS) for all functions that use an external certificate, except for the audit syslog. If your configuration does not require CRL checking, you can disable it. For example, if you use if an internal certificate authority (CA), you might want to disable CRL checking. The kess.crlEnabled property defaults to true.CRL site unavailability scenarioIf you have kess.crlEnabled set to true and a CRL site becomes unavailable, you cannot determine the revocation status of the certificate. In this situation, the single sign-on flow will fail. Confirm a CRL site unavailability issue by looking for the message FBTKJK056E The CRL site could not be determined. in the runtime trace.log file.As a temporary workaround, set the CRL checking to false to keep the single sign-on flow running. As soon as the CRL site is working again, set kess.crlEnabled to true so that the single sign-on flow contains the CRL check. If you do stop CRL checking as a temporary workaround, be aware that the certificate might have already been revoked by the CA. If this type of certificate is allowed to pass the validation, it creates security issues. Therefore, ensure that you enable CRL checking to avoid potential security issues such as this.Data type: BooleanExample: truekess.crlIntervalThe amount of time, in seconds, between successive CRL checks. Using an interval of time between CRL checks reduces the performance impact of doing the checks every time a certificate needs to be validated.A value less than or equal to zero means that the runtime performs a CRL check every time it wants to use a certificate. The default is 0 seconds.If kess.crlEnabled is set to false, this value is ignored. Data type: IntegerExample: 86400This value means that a CRL check on a certificate is performed once per day.kess.hostnameValidationDisabled Determine whether to disable host name verification when establishing an SSL connection. Host name verification is performed when the host name of the server does not match the CN of the certificate of the server. In a test environment, you might want to disable the validation. In a production environment, you might want to enable validation.The default value is False.Data type: BooleanExample: Falsekess.keySelectionCriteriaSpecify which key or certificate to use for signing, validating, encrypting, or decrypting various messages. If there are multiple keys or certificates with the same Subject DN as the key or certificate with the specified alias, this setting determines which one to use. Use one of the following selection methods:only.aliasSelect the key or certificate with the specified alias. This is the default.longest.lifetimeSelect the key or certificate with the longest lifetime.shortest.lifetimeSelect the key or certificate with the shortest lifetime.Data type: StringExample: only.aliasJSON Web Key jwks.encryption.keystoreDefines the name of the encryption keystore to be used by the jwks endpoint for the runtime. These certificates will have their public keys exposed, with the 'use' value 'enc'. Default value: rt_profile_keysjwks.signing.keystoreDefines the name of the signing keystore to be used by the jwks endpoint for the runtime. These certificates will have their public keys exposed, with the 'use' value 'sig'. Default value: rt_profile_keysPolicy information point (PIP) pip.uncachedAttributesDefines a comma-separated list of attributes that are generated by a policy information point (PIP) that you do not want to be cached.Data type: String listExample: urn:ibm:security:jdbc:city, urn:ibm:security:ldap:priviledgeUserSecurity token service (STS) sts.ldapAttributeCache.TTLSpecifies a time-to-live (TTL) value, in seconds, for the amount of time to keep an LDAP attribute in the cache. Specify 0 to disable. The default value is 60.Data type: IntegerExample: 60Mobile Multi-Factor Authentication (MMFA) mmfa.authenticator.cleanupWaitThe amount of time, in seconds, to wait before another cleanup of expired authenticators is performed. The default value is 3600. Data type: Integer Example: 3600Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Managing advanced configurationAdjust configuration settings in supported configuration files.

Advanced configuration properties

Modify the advanced configurations to meet the requirements of your organization.

Category filter

The category filter displays names of grouping of configuration settings. The groupings correspond to functional areas. When you select a category, the user interface displays only the settings for the category.

Table 82. Table 144. Filter by Category.

Category | Displays values for:
All | All keys
poc.signIn | WebSEAL Sign-In Callback
poc.websealAuth | WebSEAL Authenticate Callback
poc.otpAuth | One-time password Authenticate Callback
poc.authPolicy | Authentication-Policy Callback
sps.httpRequestClaims | SPS HTTP request claims
distributedMap | Distributed shared data storage
userBehavior | Attribute matcher properties
ipReputation | IP reputation PIP properties
attributeCollection | Attribute collector properties
deviceRegistration | Device registration properties
runtime | Runtime properties
sps.page | SPS page
sps | Single sign-on protocol service
riskEngine | Risk engine properties
sps.authService | Authentication service properties
session | Session
distributedSessionCache | Distributed session cache
otp.retry | TOTP and HOTP retry properties
oauth20 | OAuth20
util.httpClient | HTTP client
demo | Demo
knowledge.questions | Knowledge questions properties
kess | Key encryption and signing service (KESS)
jwks | JSON Web Key
pip | Policy information point (PIP)
sts | Security token service (STS)
mmfa | Mobile Multi-Factor Authentication (MMFA)

WebSEAL Sign-In Callback

poc.signIn.serverResponseHeader

The name of the header that contains the hostname that authenticates the user.

Data type: String

Example: fim.server

WebSEAL Authenticate Callback

poc.websealAuth.authLevel

The authentication level of the callback.

Data type: Integer

Example: 1

One-time password Authenticate Callback

poc.otp.authLevel

The authentication level of the callback.

Data type: Integer

Example: 2

poc.otp.backwardCompatibilityEnabled

Indicates whether the one-time password authentication mechanism should run in backward compatibility mode. The default value is false if it is a new installation. The default value is true if the installation is an upgrade.

Data type: Boolean

Example: true

Authentication-Policy Callback

poc.authPolicy.allowRequestOverride

Whether the authentication level, the authentication mode, and the authentication type of the callback can be overwritten by query string parameters.

Data type: Boolean

Example: true

poc.authPolicy.authLevel

The authentication level of the callback.

Data type: Integer

Example: 1

poc.authPolicy.authType

The authentication type of the callback.

Data type: String

Example: COMPLEMENTARY, HIERARCHICAL

SPS HTTP request claims

sps.httpRequestClaims.enabled

Whether HTTP request information is sent to STS as HTTPRequestClaims.

Data type: Boolean

Example:false

sps.httpRequestClaims.filterSpec

The filter that specifies the HTTP request information that is sent to STS as HTTPRequestClaims.

Data type: String

Example: cookies=*:headers=*

Distributed shared data storage

distributedMap.cleanupWait

The amount of time, in milliseconds, to wait before it performs another cleanup against the distributed map.

Data type: Integer

Example: 10000

distributedMap.defaultTTL

The amount of time, in seconds, that the entries in the distributed map must live when no lifetime is specified for an entry.

Data type: Integer

Example: 3600

distributedMap.getRetryDelay

The amount of time, in milliseconds, to wait before it performs another retrieval against the distributed map. The default is 0.

Data type: Integer

Example: 500

distributedMap.getRetryLimit

The number of retrievals that is done against the distributed map before it returns that the retrieved data is not in the distributed map. The default is 0.

Data type: Integer

Example: 10

Attribute matcher properties

userBehavior.minimumUsageHistoryRequired

Minimum usage data records required for any usage data analysis; used by LoginTimeMatcher.

Data type: Integer

Example: 8

userBehavior.ipAddressRequestAttribute

The XACML request attribute to read from the IP address.

Data type: String

Example: urn:ibm:security:subject:ipAddress

IP reputation PIP properties

ip.reputation.ipAddressAdverseReputationThreshold

The value that an IP classification score must be at or above for an IP address to be considered as that classification.

Data type: Integer

Example:50

ipReputation.dbConnectionTimeout

Indicates the number of seconds that the IP reputation policy information point (PIP) waits for a connection to the IP reputation database. The ipReputation.dbConnectionTimeout property defaults to 120.

Data type: Integer

Example: 60

Attribute collector properties

attributeCollection.cookieName

Correlation ID used by the attribute collector.

Data type: String

Example: ac.uuid

attributeCollection.requestServer

Request server for attribute collector. A list of the allowable hosts where the ajaxRequest can be sent from.

Data type: String List

Example: https://rbademo.example.com,https://rbaemo2.example.com

attributeCollection.serviceLocation

Location of the attribute collector.

Data type: String List

Example: http://rbademo.example.com/mga

attributeCollection.sessionTimeout

Number of seconds in which sessions stored in context-based access will automatically expire, unless updated. If any attribute in the session is updated, the session expiry is extended by the specified number of seconds configured in this property. The default is 1800 seconds.

Data type: Integer

Example: 1800 seconds

attributeCollection.enableGetAttributes

Enables the REST GET method to return attributes.

Data type: Boolean

Example: false

attributeCollection.getAttributesAllowedClients

A comma-separated list of clients that are allowed to access the ACS REST GET method.

If this property is not set and attributeCollection.enableGetAttributes is set to true, anyone can access the GET method. If this property is set but attributeCollection.enableGetAttributes is set to false, this property is ignored.

Data type: String List

Example: hostname1, hostname2

attributeCollection.hashAlgorithm

The algorithm that is used to create the hash.

Data type: String

Example: SHA256

attributeCollection.attributesHashEnabled

A comma-separated list of attribute URI values configured for hashing.

Attention: Do not hash the following attributes:

ipAddress

geoLocation

accessTime

Data type: String List

Example:

urn:ibm:security:environment:http:userAgent,
urn:ibm:security:environment:deviceFonts,
urn:ibm:security:environment:browserPlugins

attributeCollection.authenticationContextAttributes

Comma-separated lists of attribute names to be collected during an authentication service obligation. The maximum number of characters for this property is 200.

Data type: String List

Example: authenticationLevel, http:host

Device registration properties

deviceRegistration.allowIncompleteFingerprints

Specifies to allow the device registration obligation to store fingerprints where all the fingerprint attributes are not available on the session information.

Data type: Boolean

Example: false

deviceRegistration.checkForExpiredDevices

Determines whether registered devices are inactive or expired. If the deviceRegistration.checkForExpiredDevices property is set to true, the risk engine checks whether a device is inactive or expired. The deviceRegistration.checkForExpiredDevices property defaults to false, which means that users can use any of the devices that are registered.

Date type: Boolean

Example: true

deviceRegistration.cleanupThread.batchSize

Specifies if batch delete is enabled for expired devices and how many records are deleted per batch.

If the value is defined as 0 or is blank, batch delete is not enabled and all expired devices are deleted using one SLQ delete statement.

If the value is defined as an integer greater than 0, batch delete is enabled. The number that you specify determines how many records are deleted in each batch. The batch delete continues until all of the expired devices are deleted. The batch process is useful for deleting a large quantity of expired devices.

Data type: Integer

Example: 1000 (Batch delete is enabled, with a batch size of 1000 records.)

deviceRegistration.deviceMatchThreshold

The risk score threshold where an existing fingerprint is considered to match the incoming device fingerprint.

Data type: Integer

Example: 20

deviceRegistration.inactiveExpirationTime

Specifies the number of days that a device must be inactive for it to expire. The deviceRegistration.inactiveExpirationTime property defaults to 90.

Date type: Integer

Example: 100

deviceRegistration.maxRegisteredDevices

Maximum device fingerprint count. The default is 10. Valid values are 1 to 100.

Data type: Integer

Example: 10

deviceRegistration.maxUsageDataPerUser

Maximum number of historical usage attribute records stored per user. The default is 200. Valid values are 1 to 5000.

Data type: Integer

Example: 1000

deviceRegistration.permitOnIncompleteFingerprints

Specifies to permit access to the resource if the fingerprint collected by the device registration obligation does not include all fingerprint attributes.

Data type: Boolean

Example: false

Runtime properties

runtime.dbLoggingEnabled

Enables fine-grained logging for database SQL statements.

Data type: Boolean

Example: false

runtime.hashAlgorithm

The algorithm that is used for hashing. The supported algorithms are:

SHA-1

SHA-256

SHA-512

The runtime.hashAlgorithm property defaults to SHA-256.

Data type: String

Example: SHA-256

Single sign-on protocol service

sps.setCookiesAsSecure

Determine whether to flag the cookies set by Security Access Manager as secure.

The default value is false.

Data type: Boolean

Example: false

SPS page

sps.page.htmlEscapedMacros

A comma-separated list of macros that is HTML-escaped when it is rendered in pages that are sent to the browser.

Data type: String

Example:

@REQ_ADDR@,
@DETAIL@,
@EXCEPTION_STACK@,
@EXCEPTION_MSG@,
@OTP_METHOD_ID@,
@OTP_METHOD_LABEL@,
@OTP_HINT@,
@ERROR_MESSAGE@,
@MAPPING_RULE_DATA@

sps.page.exceptionMacros

A comma-separated list of classname:macro pairs. Classname is the fully qualified name of the exception class. Macro is the name of the macro to which the class maps.

Data type: String

Example:

com.tivoli.am.fim.otp.deliveries.OTPDeliveryException =
  @OTP_DELIVERY_EXCEPTION@,
com.tivoli.am.fim.otp.providers.OTPProviderException =
  @OTP_PROVIDER_EXCEPTION@

Risk engine properties

riskEngine.reportsEnabled

Enables the generation of risk calculation reports.

Data type: Boolean

Example: false

riskEngine.reportsMaxStored

Specifies the maximum number of reports to store.

Data type: Integer

Example: 5

Authentication service properties

sps.authService.reauthenticationEnabled

Specifies that the authentication service performs authentication even if the user already has an authenticated session at the required authentication level.

Data type: Boolean

Example: true

Session

distributedSessionCache.enabled

A switch that dictates if the distributed session cache is used for session failover. If this setting is not enabled, the distributed session cache server still runs as a service, but the client does not use it.

Data type: Boolean

Example: false

distributedSessionCache.localCacheSize

The number of sessions to be stored on the client as a local cache. A value of 0 or less means that any number of sessions can be cached by the client. A low number requires more connections to the distributed session cache if there are many active sessions. A high number runs the risk of running out of memory if many sessions are locally cached. All sessions are still stored on the distributed session cache when it is enabled.

Data type: Integer

Example: 4096

session.dbCleanupInterval

Specifies the interval, in seconds, that the database cleanup thread runs to remove expired data in the runtime database. The default is 86400. The minimum value for this property is 3600. For more information, see Runtime database tuning parameters

Data type: Integer

Example: 90000

Distributed session cache

distributedSessionCache.enabled

A switch that dictates if the distributed session cache is used for session failover. If this setting is not enabled, the distributed session cache server still runs as a service, but the client does not use it.

Data type: Boolean

Example: false

distributedSessionCache.localCacheSize

The number of sessions to be stored on the client as a local cache. A value of 0 or less means that any number of sessions can be cached by the client. A low number requires more connections to the distributed session cache if there are many active sessions. A high number runs the risk of running out of memory if many sessions are locally cached. All sessions are still stored on the distributed session cache when it is enabled.

Data type: Integer

Example: 4096

TOTP and HOTP retry properties

otp.retry.enabled

Whether the retry protection is enabled.

Data type: Boolean

Example: true

otp.retry.maxNumberOfAttempts

The maximum number of strikes the users can have before they are prevented from logging in.

Data type: Integer

Example: 5

otp.retry.otpRetryTimeout

The number in seconds a strike lasts.

Data type: Integer

Example: 600

OAuth20

oauth20.cleanupThread.batchSize

Specifies if batch delete is enabled for expired OAuth 2.0 tokens and how many records are deleted per batch.

If the value is defined as 0 or is blank, batch delete is not enabled and all expired OAuth tokens are deleted using one SQL delete statement.

If the value is defined as an integer greater than 0, batch delete is enabled. The number that you specify determines how many records are deleted in each batch. The batch delete continues until all of the expired OAuth tokens are deleted. The batch process is useful for deleting a large quantity of expired tokens.

Data type: Integer

Example: 1000 (Batch delete is enabled, with a batch size of 1000 records.)

oauth20.clientDataToInclude

Specifies the OAuth client information to be returned as JSON data. This property is a comma-separated list of the JSON Keys. Valid values are:

contact_type
email_address
contact_person
company_name
company_url
phone_number
other_info

You can specify one or more of these keys for this property.

Note: The oauth20.clientDataToInclude property defaults to contact_type, email_address, contact_person, company_name, company_url, phone_number, other_info.

Data type: String

Example: contact_type, email_address, company_name

oauth20.doNotSendXFrameOptionsHeader

Specifies whether an X-Frame-Options header with value SAMEORIGIN must be returned from the OAuth 2.0 endpoints. When set to true, no X-Frame-Options header is sent.

Note: The oauth20.doNotSendXFrameOptionsHeader property defaults to false.

Data type: Boolean

Example: false

oauth20.hashedTokenStorageEnabled

Enables hashed storage when set to true. The Security Access Manager appliance can persist OAuth 2.0 tokens in the clear text form or in the more secure hashed form.

Note: The oauth20.hashedTokenStorageEnabled property defaults to false, and the OAuth 2.0 tokens will be stored as-is.

Data type: Boolean

Example: false

oauth20.sessionEndpointEnabled

Enables the ability to return an authenticated session at the point-of-contact when the oauth20.sessionEndpointEnabled property is set to true.

Note: The oauth20.sessionEndpointEnabled property defaults to false.

Data type: Boolean

Example: false

oauth20.tokenCache.cleanupWait

The amount of time, in seconds, to wait before it performs another cleanup of expired tokens in the OAuth 2.0 token cache.

Note: The oauth20.tokenCache.cleanupWait property defaults to 120.

Data type: Integer

Example: 120

HTTP client

util.httpClient.defaultTrustStore

Stores the default truststore that HTTPS connections in HTTP client uses.

Note: The util.httpClient.TrustStore property defaults to rt_profile_keys.

Data type: String

Example: rt_profile_keys

util.httpClient.defaultSSLProtocol

Stores the default SSL protocol configuration that HTTPS connections in HTTP client uses.

Note: The util.httpClient.defaultSSLProtocol property defaults to TLS.

Data type: String

Example: TLS

Demo

live.demos.enabled

Enables the mobile demonstration application.

Data type: Boolean

Example: False

Knowledge questions properties

knowledge.questions.AnswerValidationRegEx

Specifies the regular expression used to validate the knowledge question answer value provided during a knowledge question management operation. The assigned value is the list of invalid characters to match against to determine if the supplied value is valid.

Note: At a minimum, this property must include the following characters: <>:"

Data type: RegEx

Example: [\[()<>,;:\\/\"\]=]

knowledge.questions.QuestionValidationRegEx

Specifies the regular expression used to validate the knowledge question text value provided during a knowledge question management operation. The assigned value is the list of invalid characters to match against to determine if the supplied value is valid.

Note: At a minimum, this property must include the following characters: <>:"

Data type: RegEx

Example: [\[()<>,;:\\/\"\]=]

Key encryption and signing service (KESS)

kess.crlEnabled

Checks the certificate revocation list. Checking is done by the key encryption and signature service (KESS) for all functions that use an external certificate, except for the audit syslog. If your configuration does not require CRL checking, you can disable it. For example, if you use if an internal certificate authority (CA), you might want to disable CRL checking. The kess.crlEnabled property defaults to true.

CRL site unavailability scenario

If you have kess.crlEnabled set to true and a CRL site becomes unavailable, you cannot determine the revocation status of the certificate. In this situation, the single sign-on flow will fail.

Confirm a CRL site unavailability issue by looking for the message "FBTKJK056E The CRL site could not be determined." in the runtime trace.log file.

As a temporary workaround, set the CRL checking to false to keep the single sign-on flow running. As soon as the CRL site is working again, set kess.crlEnabled to true so that the single sign-on flow contains the CRL check.

CAUTION:

If you do stop CRL checking as a temporary workaround, be aware that the certificate might have already been revoked by the CA. If this type of certificate is allowed to pass the validation, it creates security issues. Therefore, ensure that you enable CRL checking to avoid potential security issues such as this.

Data type: Boolean

Example: true

kess.crlInterval

The amount of time, in seconds, between successive CRL checks. Using an interval of time between CRL checks reduces the performance impact of doing the checks every time a certificate needs to be validated.

A value less than or equal to zero means that the runtime performs a CRL check every time it wants to use a certificate. The default is 0 seconds.

If kess.crlEnabled is set to false, this value is ignored.

Data type: Integer

Example: 86400

This value means that a CRL check on a certificate is performed once per day.

kess.hostnameValidationDisabled

Determine whether to disable host name verification when establishing an SSL connection. Host name verification is performed when the host name of the server does not match the CN of the certificate of the server.

In a test environment, you might want to disable the validation. In a production environment, you might want to enable validation.

The default value is False.

Data type: Boolean

Example: False

kess.keySelectionCriteria

Specify which key or certificate to use for signing, validating, encrypting, or decrypting various messages. If there are multiple keys or certificates with the same Subject DN as the key or certificate with the specified alias, this setting determines which one to use. Use one of the following selection methods:

only.alias

Select the key or certificate with the specified alias. This is the default.

longest.lifetime

Select the key or certificate with the longest lifetime.

shortest.lifetime

Select the key or certificate with the shortest lifetime.

Data type: String

Example: only.alias

JSON Web Key

jwks.encryption.keystore

Defines the name of the encryption keystore to be used by the jwks endpoint for the runtime. These certificates will have their public keys exposed, with the 'use' value 'enc'.

Default value: rt_profile_keys

jwks.signing.keystore

Defines the name of the signing keystore to be used by the jwks endpoint for the runtime. These certificates will have their public keys exposed, with the 'use' value 'sig'.

Default value: rt_profile_keys

Policy information point (PIP)

pip.uncachedAttributes

Defines a comma-separated list of attributes that are generated by a policy information point (PIP) that you do not want to be cached.

Data type: String list

Example: urn:ibm:security:jdbc:city, urn:ibm:security:ldap:priviledgeUser

Security token service (STS)

sts.ldapAttributeCache.TTL

Specifies a time-to-live (TTL) value, in seconds, for the amount of time to keep an LDAP attribute in the cache. Specify 0 to disable.

The default value is 60.

Data type: Integer

Example: 60

Mobile Multi-Factor Authentication (MMFA)

mmfa.authenticator.cleanupWait

The amount of time, in seconds, to wait before another cleanup of expired authenticators is performed.

The default value is 3600.

Data type: Integer

Example: 3600

Parent topic: Advanced Access Control configuration

Parent topic: Managing advanced configuration

Deploying pending changesDeploying pending changesDeploying changesSome configuration and administration changes require an extra deployment step.deploying changespending changesWhen you use the graphical user interface on the appliance to specify changes, some configuration and administration tasks take effect immediately. Other tasks require a deployment step to take effect. For these tasks, the appliance gives you a choice of deploying immediately or deploying later. When you must make multiple changes, you can wait until all changes are complete, and then deploy all of them at one time.When a deployment step is required, the user interface presents a message that says that there is an undeployed change. The number of pending changes is displayed in the message, and increments for each change you make.If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.When you finish making configuration changes, select Click here to review the changes or apply them to the system.The Deploy Pending Changes window is displayed.Select one of the following options:CancelDo not deploy the changes now. Retain the undeployed configuration changes. The appliance user interface returns to the previous panel.Roll BackAbandon configuration changes. A message is displayed, stating that the pending changes were reverted. The appliance user interface returns to the previous panel.DeployDeploy all configuration changes.When you select Deploy, a system message is displayed, stating that the changes were deployed.If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Deploying pending changes

Some configuration and administration changes require an extra deployment step.

About this task

When you use the graphical user interface on the appliance to specify changes, some configuration and administration tasks take effect immediately. Other tasks require a deployment step to take effect. For these tasks, the appliance gives you a choice of deploying immediately or deploying later. When you must make multiple changes, you can wait until all changes are complete, and then deploy all of them at one time.

When a deployment step is required, the user interface presents a message that says that there is an undeployed change. The number of pending changes is displayed in the message, and increments for each change you make.

Note: If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.

Procedure

When you finish making configuration changes, select Click here to review the changes or apply them to the system.

The Deploy Pending Changes window is displayed.

Select one of the following options:

Option
Description

Cancel
Do not deploy the changes now.

Retain the undeployed configuration changes. The appliance user interface returns to the previous panel.

Roll Back
Abandon configuration changes.

A message is displayed, stating that the pending changes were reverted. The appliance user interface returns to the previous panel.

Deploy
Deploy all configuration changes.

When you select Deploy, a system message is displayed, stating that the changes were deployed.

If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.

Parent topic: Advanced Access Control configuration

Tuning runtime application parameters and tracing specificationsTuning runtime application parameters and tracing specificationsAccess Manager Appliance: Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. From the top menu, select Secure Access ControlGlobal SettingsRuntime Parameters or Secure FederationGlobal SettingsRuntime Parameters.This page contains three panels: Runtime Status, Runtime Tuning Parameters, and Runtime Tracing. Perform one or more of the following actions to tune your runtime.If automatic restart or reload is not enabled, you must manually restart or reload the runtime for certain changes to take effect.Disable automatic restart or reload of the runtimeBy default, the runtime is automatically reloaded or restarted after certain changes are made. Some configuration changes require that the runtime only needs to be reloaded, while other changes require a restart. The following are examples of configuration changes that require a reload (as opposed to a restart):SAML 2.0 federations and partnersSecurity token service (STS) chains and instancesAuthentication mechanismsAuthentication policiesYou can disable the automatic restart or reload functions if you prefer to do it manually.On the Runtime Tuning Parameters panel, select Auto Restart or Auto Reload.Click Edit.In the Auto Restart or Auto Reload window, define the value as False by clearing the check box.Click OK.View the status of and restart or reload the runtimeSelect the Runtime Status panel. The status of local and clustered runtimes are displayed.Under Local Runtime Status, you can view the runtime operational status, when it was last started and reloaded, and whether a restart or reload is outstanding. If the value of the Restart Required or Reload Required fields are True, it means that the runtime must be restarted or reloaded for some changes to take effect.Under Clustered Runtime Status, all nodes in the cluster are listed.The Primary Master column indicates whether a node is the primary master. Identify a node as a cluster master on the Cluster Configuration panel.The Status column indicates whether a node is running or stopped.The Changes Active column indicates whether changes that are made to the cluster configuration are active on this node. Having a green indicator in this column means that all changes that are made are already active. Having a yellow indicator in this column means that this node must be restarted or reloaded before some changes can take effect.Depending on which runtime you want to restart or reload, click: Restart Local RuntimeReload Local RuntimeRestart All Clustered RuntimesReload All Clustered RuntimesAfter reload, the runtime server immediately uses the new configuration to process new requests. Existing requests are still processed using the old configuration. The old configuration will be cleaned from memory after the runtime server completes processing all existing requests.Certain flows require multiple interactions between the user and runtime server. If you deploy substantial configuration changes in the middle of these interactions, the flow might fail. For example, deleting a federation or a partner while a user is performing single sign-on using this federation or partner might cause the flow to fail. Therefore, it is advisable to perform such configuration changes when the runtime server is not heavily used.Modify the maximum or initial heap sizeThese parameters indicate the maximum and initial heap size in megabytes for the runtime Java virtual machine.On the Runtime Tuning Parameters panel, select Max Heap Size or Initial Heap Size.Click Edit.In the Max Heap Size or Initial Heap Size window, enter the heap size value as needed.Click OK.Modify whether to suppress sensitive traceEnabling this parameter prevents sensitive information from being exposed in log and trace files. Examples of such sensitive information include bytes received over a network connection.On the Runtime Tuning Parameters panel, select Suppress Sensitive Trace.Click Edit.In the Suppress Sensitive Trace window, select or clear the check box as needed.Click OK.Modify console log levelConsole log level controls the granularity of messages that go to the console.log file.On the Runtime Tuning Parameters panel, select Console Log Level. Click Edit.In the Console Log Level window, select the new value from the list.Click OK.Set whether to accept client certificatesThis parameter controls whether the server accepts client certificates as a form of authentication.On the Runtime Tuning Parameters panel, select Accept Client Certificates. Click Edit.In the Accept Client Certificates window, select or clear the check box as needed.Click OK.Set session invalidation timeoutThis parameter defines the amount of time a session can remain unused before it is no longer valid.The default setting is Unset. When this setting is used, the session invalidation timeout is 1800 seconds.On the Runtime Tuning Parameters panel, select Session Invalidation Timeout. Click Edit.In the Session Invalidation Timeout window, define the value in seconds.Click OK.Set session reaper poll intervalThis parameter defines the wake-up interval in seconds for the process that removes invalid sessions. The minimum value is 30 seconds.The default setting is Unset. When this setting is used, or if a value less than the minimum is entered, an appropriate value is automatically determined and used. This value overrides the default installation value, which is 30 - 360 seconds, based on the session invalidation timeout value. Because the default session invalidation timeout is 1800 seconds, the reaper interval is usually 120 - 180 seconds.On the Runtime Tuning Parameters panel, select Session Reaper Poll Interval. Click Edit.In the Session Reaper Poll Interval window, define the value in seconds.Click OK.Set the keystore that is used by the runtime serverThis parameter defines the key database that contains the runtime server's private key.On the Runtime Tuning Parameters panel, select Keystore. Click Edit.In the Keystore window, select the key database from the list.Click OK.Set the truststore that is used by the runtime serverThis parameter defines the key database that contains keys that are trusted by the runtime server.On the Runtime Tuning Parameters panel, select Truststore. Click Edit.In the Truststore window, select the key database from the list.Click OK.Configure the maximum size and maximum number of the log filesThese parameters control settings for the trace.log, messages.log files, and their rollover files. The Maximum Log File Size parameter defines the maximum size in megabytes that the log files can grow to before they are rolled over. The Maximum Log Files parameter defines the maximum number of log files and rollover files that can be kept on the system. On the Runtime Tuning Parameters panel, select Maximum Log File Size or Maximum Log Files. Click Edit.Enter the values as needed.Click OK.Delete the value of a parameterUse this button to delete the existing value of a parameter.Select the parameter to reset the value for.Click Delete. The value of the parameter is then changed to Unset.Manage the application interface on which the runtime listensOn the Runtime Tuning Parameters panel, under Runtime Listening Interfaces, you can add, edit, or delete a listening interface.To add a listening interfaceClick Add.In the Runtime Listening Interfaces window, select the listening interface from the list.Specify the listening port.Select the SSL check box if security is required.Click OK.To modify a listening interfaceSelect the listening interface to edit.Click Edit.In the Runtime Listening Interfaces window, edit the values as needed.Click OK to save the changes.To delete a listening interfaceSelect the listening interface to delete.Select Delete.Confirm the deletion.Manage tracing specificationSelect the Runtime Tracing link from the top of this page. You can also access this panel from the top menu by selecting Monitor Analysis and DiagnosticsLogsRuntime Tracing.Use one of the following ways to edit the trace level of a component.Select the component name from the Component list. Select the ideal trace level for this component from the Trace Level list. Then, click Add. Repeat this process to modify trace levels for other components, if needed. To clear all of the tracing levels, click Clear.To log all events, select ALL as the trace level.This setting increases the amount of data in logs, so use this level when necessary.com.tivoli.am.fim.authsvc.* com.tivoli.am.fim.trustserver.sts.modules.*Valid trace levelsThe following table contains the valid trace levels. LevelSignificanceALLAll events are logged. If you create custom levels, ALL includes those levels and can provide a more detailed trace than FINEST.FINESTDetailed trace information that includes all of the details that are necessary to debug problems.FINERDetailed trace information.FINEGeneral trace information that includes methods entry, exit, and return values.DETAILGeneral information that details sub task progress.CONFIGConfiguration change or status.INFOGeneral information that outlines the overall task progress.AUDITSignificant event that affects the server state or resources.WARNINGPotential error or impending error. This level can also indicate a progressive failure. For example: the potential leaking of resourcesSEVEREThe task cannot continue, but component, application, and server can still function. This level can also indicate an impending unrecoverable error.FATALThe task cannot continue, and component, application, and server cannot function.OFFLogging is turned off.Enter the name and value of the trace component in the Trace Specification field. To modify multiple components, separate two strings with a colon (:). Here is an example.com.x.y.*=WARNING:com.a.b.*=WARNING:com.ibm.isam.*=INFOClick Save.When you make changes, the appliance displays a message that there are undeployed changes. After the changes are complete, deploy them.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Tuning runtime application parameters and tracing specifications

To manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page.

Before you begin

About this task

Procedure

From the top menu, select Secure Access Control > Global Settings > Runtime Parameters or Secure Federation > Global Settings > Runtime Parameters. This page contains three panels: Runtime Status, Runtime Tuning Parameters, and Runtime Tracing.

Perform one or more of the following actions to tune your runtime.

Note: If automatic restart or reload is not enabled, you must manually restart or reload the runtime for certain changes to take effect.

Disable automatic restart or reload of the runtime

By default, the runtime is automatically reloaded or restarted after certain changes are made. Some configuration changes require that the runtime only needs to be reloaded, while other changes require a restart. The following are examples of configuration changes that require a reload (as opposed to a restart):

SAML 2.0 federations and partners

Security token service (STS) chains and instances

Authentication mechanisms

Authentication policies

You can disable the automatic restart or reload functions if you prefer to do it manually.

On the Runtime Tuning Parameters panel, select Auto Restart or Auto Reload.

Click Edit.

In the Auto Restart or Auto Reload window, define the value as False by clearing the check box.

Click OK.

View the status of and restart or reload the runtime

Select the Runtime Status panel. The status of local and clustered runtimes are displayed.

Under Local Runtime Status, you can view the runtime operational status, when it was last started and reloaded, and whether a restart or reload is outstanding. If the value of the Restart Required or Reload Required fields are True, it means that the runtime must be restarted or reloaded for some changes to take effect.

Under Clustered Runtime Status, all nodes in the cluster are listed.

The Primary Master column indicates whether a node is the primary master. Identify a node as a cluster master on the Cluster Configuration panel.

The Status column indicates whether a node is running or stopped.

The Changes Active column indicates whether changes that are made to the cluster configuration are active on this node. Having a green indicator in this column means that all changes that are made are already active. Having a yellow indicator in this column means that this node must be restarted or reloaded before some changes can take effect.

Depending on which runtime you want to restart or reload, click:

Restart Local Runtime

Reload Local Runtime

Restart All Clustered Runtimes

Reload All Clustered Runtimes

Note: After reload, the runtime server immediately uses the new configuration to process new requests. Existing requests are still processed using the old configuration. The old configuration will be cleaned from memory after the runtime server completes processing all existing requests.

Remember: Certain flows require multiple interactions between the user and runtime server. If you deploy substantial configuration changes in the middle of these interactions, the flow might fail. For example, deleting a federation or a partner while a user is performing single sign-on using this federation or partner might cause the flow to fail. Therefore, it is advisable to perform such configuration changes when the runtime server is not heavily used.

Modify the maximum or initial heap size

These parameters indicate the maximum and initial heap size in megabytes for the runtime Java virtual machine.

On the Runtime Tuning Parameters panel, select Max Heap Size or Initial Heap Size.

Click Edit.

In the Max Heap Size or Initial Heap Size window, enter the heap size value as needed.

Click OK.

Modify whether to suppress sensitive trace

Enabling this parameter prevents sensitive information from being exposed in log and trace files. Examples of such sensitive information include bytes received over a network connection.

On the Runtime Tuning Parameters panel, select Suppress Sensitive Trace.

Click Edit.

In the Suppress Sensitive Trace window, select or clear the check box as needed.

Click OK.

Modify console log level

Console log level controls the granularity of messages that go to the console.log file.

On the Runtime Tuning Parameters panel, select Console Log Level.

Click Edit.

In the Console Log Level window, select the new value from the list.

Click OK.

Set whether to accept client certificates

This parameter controls whether the server accepts client certificates as a form of authentication.

On the Runtime Tuning Parameters panel, select Accept Client Certificates.

Click Edit.

In the Accept Client Certificates window, select or clear the check box as needed.

Click OK.

Set session invalidation timeout

This parameter defines the amount of time a session can remain unused before it is no longer valid.

Note: The default setting is Unset. When this setting is used, the session invalidation timeout is 1800 seconds.

On the Runtime Tuning Parameters panel, select Session Invalidation Timeout.

Click Edit.

In the Session Invalidation Timeout window, define the value in seconds.

Click OK.

Set session reaper poll interval

This parameter defines the wake-up interval in seconds for the process that removes invalid sessions. The minimum value is 30 seconds.

The default setting is Unset. When this setting is used, or if a value less than the minimum is entered, an appropriate value is automatically determined and used. This value overrides the default installation value, which is 30 - 360 seconds, based on the session invalidation timeout value. Because the default session invalidation timeout is 1800 seconds, the reaper interval is usually 120 - 180 seconds.

On the Runtime Tuning Parameters panel, select Session Reaper Poll Interval.

Click Edit.

In the Session Reaper Poll Interval window, define the value in seconds.

Click OK.

Set the keystore that is used by the runtime server

This parameter defines the key database that contains the runtime server's private key.

On the Runtime Tuning Parameters panel, select Keystore.

Click Edit.

In the Keystore window, select the key database from the list.

Click OK.

Set the truststore that is used by the runtime server

This parameter defines the key database that contains keys that are trusted by the runtime server.

On the Runtime Tuning Parameters panel, select Truststore.

Click Edit.

In the Truststore window, select the key database from the list.

Click OK.

Configure the maximum size and maximum number of the log files

These parameters control settings for the trace.log, messages.log files, and their rollover files. The Maximum Log File Size parameter defines the maximum size in megabytes that the log files can grow to before they are rolled over. The Maximum Log Files parameter defines the maximum number of log files and rollover files that can be kept on the system.

On the Runtime Tuning Parameters panel, select Maximum Log File Size or Maximum Log Files.

Click Edit.

Enter the values as needed.

Click OK.

Delete the value of a parameter

Use this button to delete the existing value of a parameter.

Select the parameter to reset the value for.

Click Delete. The value of the parameter is then changed to Unset.

Manage the application interface on which the runtime listens

On the Runtime Tuning Parameters panel, under Runtime Listening Interfaces, you can add, edit, or delete a listening interface.

To add a listening interface

Click Add.

In the Runtime Listening Interfaces window, select the listening interface from the list.

Specify the listening port.

Select the SSL check box if security is required.

Click OK.

To modify a listening interface

Select the listening interface to edit.

Click Edit.

In the Runtime Listening Interfaces window, edit the values as needed.

Click OK to save the changes.

To delete a listening interface

Select the listening interface to delete.

Select Delete.

Confirm the deletion.

Manage tracing specification

Select the Runtime Tracing link from the top of this page. You can also access this panel from the top menu by selecting Monitor Analysis and Diagnostics > Logs > Runtime Tracing.

Use one of the following ways to edit the trace level of a component.

Select the component name from the Component list. Select the ideal trace level for this component from the Trace Level list. Then, click Add. Repeat this process to modify trace levels for other components, if needed. To clear all of the tracing levels, click Clear.

To log all events, select ALL as the trace level.

Note: This setting increases the amount of data in logs, so use this level when necessary.

com.tivoli.am.fim.authsvc.*
com.tivoli.am.fim.trustserver.sts.modules.*

Table 83. Valid trace levels. The following table contains the valid trace levels.

Level | Significance
ALL | All events are logged. If you create custom levels, ALL includes those levels and can provide a more detailed trace than FINEST.
FINEST | Detailed trace information that includes all of the details that are necessary to debug problems.
FINER | Detailed trace information.
FINE | General trace information that includes methods entry, exit, and return values.
DETAIL | General information that details sub task progress.
CONFIG | Configuration change or status.
INFO | General information that outlines the overall task progress.
AUDIT | Significant event that affects the server state or resources.
WARNING | Potential error or impending error. This level can also indicate a progressive failure. For example: the potential leaking of resources
SEVERE | The task cannot continue, but component, application, and server can still function. This level can also indicate an impending unrecoverable error.
FATAL | The task cannot continue, and component, application, and server cannot function.
OFF | Logging is turned off.

Enter the name and value of the trace component in the Trace Specification field. To modify multiple components, separate two strings with a colon (:). Here is an example.

com.x.y.*=WARNING:com.a.b.*=WARNING:com.ibm.isam.*=INFO

Click Save.

When you make changes, the appliance displays a message that there are undeployed changes. After the changes are complete, deploy them.

Parent topic: Advanced Access Control configuration

Options for handling session failover eventsOptions for handling session failover eventHandling session failover eventAdvanced Access Control offers several solutions to the challenge of providing sharing of session state across multiple servers in a clustered environment. The following sections describe the options available for handling failover events in clustered environments:No handling of failover eventsThe Distributed Session CacheAdvanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.Option 1: No handling of failover events Failover events are rare when WebSEAL or Web Reverse Proxy instance is configured to maintain session affinity in a stateful junction to Advanced Access Control. Option 2: The distributed session cacheThe distributed session cache (DSC) can be used for session storage by all Security Access Manager appliances in a cluster.

Options for handling session failover events

Advanced Access Control offers several solutions to the challenge of providing sharing of session state across multiple servers in a clustered environment.

The following sections describe the options available for handling failover events in clustered environments:

No handling of failover events

The Distributed Session Cache

Option 1: No handling of failover events
Failover events are rare when WebSEAL or Web Reverse Proxy instance is configured to maintain session affinity in a stateful junction to Advanced Access Control.

Option 2: The distributed session cache
The distributed session cache (DSC) can be used for session storage by all Security Access Manager appliances in a cluster.

Parent topic: Advanced Access Control configuration

Option 1: No handling of failover eventsNo handling of failover eventsHandling of failover events Failover events are rare when WebSEAL or Web Reverse Proxy instance is configured to maintain session affinity in a stateful junction to Advanced Access Control. This scenario is applicable in the case of using the isamcfg tool to configure the junction.When failover events do occur, session state is lost and clients might be required to restart their current transaction.This option is configured by default. However, there is a risk of a poor user experience when: The server containing Advanced Access Control becomes unavailableThe WebSEAL or Web Reverse Proxy cannot maintain session affinityOptions for handling session failover eventsAdvanced Access Control offers several solutions to the challenge of providing sharing of session state across multiple servers in a clustered environment.

Option 1: No handling of failover events

Failover events are rare when WebSEAL or Web Reverse Proxy instance is configured to maintain session affinity in a stateful junction to Advanced Access Control.

This scenario is applicable in the case of using the isamcfg tool to configure the junction.

When failover events do occur, session state is lost and clients might be required to restart their current transaction.

This option is configured by default. However, there is a risk of a poor user experience when:

The server containing Advanced Access Control becomes unavailable

The WebSEAL or Web Reverse Proxy cannot maintain session affinity

Parent topic: Options for handling session failover events

Option 2: The distributed session cacheThe Distributed Session CacheDistributed Session CacheThe distributed session cache (DSC) can be used for session storage by all Security Access Manager appliances in a cluster.distributed session cacheDSCWhen a fail over event occurs, Security Access Manager appliance retrieves the session data of the user from the DSC. It therefore maintains the existing session state.Within Security Access Manager, the DSC is part of the cluster configuration. For more information about turning on or turning off this feature, see the Distributed Session Cache section in Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization. and Managing Distributed Session CacheIn a clustered appliance environment, session information is stored in the Distributed Session Cache. To work with these sessions, use the Distributed Session Cache management page..Options for handling session failover eventsAdvanced Access Control offers several solutions to the challenge of providing sharing of session state across multiple servers in a clustered environment.

Option 2: The distributed session cache

The distributed session cache (DSC) can be used for session storage by all Security Access Manager appliances in a cluster.

When a fail over event occurs, Security Access Manager appliance retrieves the session data of the user from the DSC. It therefore maintains the existing session state.

Within Security Access Manager, the DSC is part of the cluster configuration. For more information about turning on or turning off this feature, see the Distributed Session Cache section in Advanced configuration properties and Managing Distributed Session Cache.

Parent topic: Options for handling session failover events

Managing JavaScript mapping rulesCreate or edit JavaScript mapping rules.When you activate the Advanced Access Control offering, the following mapping rule types are available: AuthSvcAuthorization service mapping rule.OAUTHOAuth mapping rule.OTPOne-time password mapping rule.OIDCOpenID Connect mapping rule.SAML2_0SAML 2.0 mapping rule.Click Secure Access Control.Under Global Settings, click Mapping Rules.All existing mapping rules are displayed.You can create or modify a mapping rule.To create a mapping ruleClick Add.In the Content field, enter the JavaScript mapping rule content.In the Name field, enter a name for the rule.In the Category field, select the type of the mapping rule from the list.Only the mapping rule types that apply to your current activated offering are displayed in the list.Click Save.To modify a mapping ruleSelect the mapping rule to modify.Click Edit.Modify the mapping rule in the Content field as needed.The Name and Category fields are not editable.Click Save.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

Managing JavaScript mapping rules

Create or edit JavaScript mapping rules.

About this task

When you activate the Advanced Access Control offering, the following mapping rule types are available:

AuthSvc

Authorization service mapping rule.

OAUTH

OAuth mapping rule.

OTP

One-time password mapping rule.

OIDC

OpenID Connect mapping rule.

SAML2_0

SAML 2.0 mapping rule.

Procedure

Click Secure Access Control.

Under Global Settings, click Mapping Rules. All existing mapping rules are displayed.

You can create or modify a mapping rule.

To create a mapping rule

Click Add.

In the Content field, enter the JavaScript mapping rule content.

In the Name field, enter a name for the rule.

In the Category field, select the type of the mapping rule from the list.

Note: Only the mapping rule types that apply to your current activated offering are displayed in the list.

Click Save.

To modify a mapping rule

Select the mapping rule to modify.

Click Edit.

Modify the mapping rule in the Content field as needed.

Note: The Name and Category fields are not editable.

Click Save.

Parent topic: Advanced Access Control configuration

JavaScript whitelistJavaScript whitelistJavaScript whitelistAdvanced Access Control JavaScript mapping rules call Java code from JavaScript. The set of classes that can be called are restricted. mapping rulescustomone-time passwordExercise reasonable caution when you call Java code from JavaScript rules to ensure that accidental damage to appliance resources is avoided.The following common classes are allowed in one-time password, OAuth or API protection, dynamic attributes, and JavaScript PIP mapping rules. java.lang.Booleanjava.lang.Characterjava.lang.Integerjava.lang.Objectjava.lang.Stringjava.lang.reflect.Arrayjava.io.ByteArrayInputStreamjava.io.ObjectInputStreamjava.util.ArrayList **java.util.HashSet **java.util.HashMap **java.io.PrintStreamjava.lang.Systemcom.ibm.security.access.httpclient.HttpClientcom.ibm.security.access.httpclient.HttpResponsecom.ibm.security.access.httpclient.Headerscom.ibm.security.access.httpclient.Parameterscom.ibm.security.access.scimclient.ScimClientcom.ibm.security.access.scimcleint.ScimConfigcom.tivoli.am.rba.attributes.AttributeIdentifiercom.tivoli.am.rba.extensions.RBAExtensionscom.tivoli.am.rba.fingerprinting.ValueContainerIdentifierAdaptercom.tivoli.am.rba.extensions.Attribute$Categorycom.tivoli.am.rba.extensions.Attribute$DataTypecom.tivoli.am.rba.extensions.Attributecom.tivoli.am.rba.extensions.PluginUtilsThe following additional classes are allowed in one-time password and OAuth or API protection mapping rules.com.tivoli.am.fim.trustserver.sts.modules.http.stsclient.STSClientHelpercom.tivoli.am.fim.trustserver.sts.oauth20.Clientcom.tivoli.am.fim.trustserver.sts.oauth20.Grantcom.tivoli.am.fim.trustserver.sts.oauth20.Tokencom.tivoli.am.fim.trustserver.sts.STSModuleException com.tivoli.am.fim.trustserver.sts.STSUniversalUser *com.tivoli.am.fim.trustserver.sts.uuser.Attribute *com.tivoli.am.fim.trustserver.sts.uuser.AttributeList *com.tivoli.am.fim.trustserver.sts.uuser.AttributeStatement *com.tivoli.am.fim.trustserver.sts.uuser.ContextAttributes *com.tivoli.am.fim.trustserver.sts.uuser.Group *com.tivoli.am.fim.trustserver.sts.uuser.Principal *com.tivoli.am.fim.trustserver.sts.uuser.Subject *com.tivoli.am.fim.trustserver.sts.uuser.RequestSecurityToken *com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtilscom.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtCacheDMAPImplcom.tivoli.am.fim.trustserver.sts.utilities.InfoCardClaimcom.tivoli.am.fim.trustserver.sts.utilities.QueryServiceAttributecom.tivoli.am.fim.trustserver.sts.utilities.USCContextAttributesHelpercom.tivoli.am.fim.base64.BASE64Utilitycom.tivoli.am.fim.utils.IteratorWrappercom.tivoli.am.fim.trustserver.sts.utilities.OAuthMappingExtUtilscom.tivoli.am.fim.trustserver.sts.utilities.HttpResponsecom.tivoli.am.rba.pip.JavaScriptPIPcom.tivoli.am.rba.pip.JavaScriptPIP$Contextjava.mail.internet.InternetAddressThe following additional classes are allowed in JavaScript PIP mapping rules. com.tivoli.am.fim.base64.BASE64Utilitycom.tivoli.am.rba.rtss.AttributeLocatorImplcom.tivoli.am.rba.pip.JavaScriptPIPcom.tivoli.am.rba.pip.JavaScriptPIP$Context * The white list does not contain any implementation of the interfaces that are defined in the org.w3c.dom package. For example, you cannot use the method org.w3c.dom.Document toXML() in com.tivoli.am.fim.trustserver.sts.STSUniversalUser. ** Inner classes for these classes are not supported. Methods that involve an inner class implementation of an interface are not available. For example, do not use the following method in java.util.HashMap:Collection<V> values()Set<K> keySet()Set<Map.Entry<K,V>> entrySet() For more information about dynamic attributes, see Dynamic attributesYou can capture additional context-based access information in dynamic attributes that you create or customize..For more information about policy information points, see Managing policy information pointsTo use data from sources outside of the appliance in your policies, you must add that source as a policy information point..Managing OAuth 2.0 mapping rulesUse the mapping rules to customize the methods for the OAuth 2.0 flow. Managing mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.Advanced Access Control configurationUse the topics in this hierarchy to configure the Advanced Access Control features, if you activate this module.

JavaScript whitelist

Advanced Access Control JavaScript mapping rules call Java™ code from JavaScript. The set of classes that can be called are restricted.

Exercise reasonable caution when you call Java code from JavaScript rules to ensure that accidental damage to appliance resources is avoided.

The following common classes are allowed in one-time password, OAuth or API protection, dynamic attributes, and JavaScript PIP mapping rules.

java.lang.Boolean

java.lang.Character

java.lang.Integer

java.lang.Object

java.lang.String

java.lang.reflect.Array

java.io.ByteArrayInputStream

java.io.ObjectInputStream

java.util.ArrayList **

java.util.HashSet **

java.util.HashMap **

java.io.PrintStream

java.lang.System

com.ibm.security.access.httpclient.HttpClient

com.ibm.security.access.httpclient.HttpResponse

com.ibm.security.access.httpclient.Headers

com.ibm.security.access.httpclient.Parameters

com.ibm.security.access.scimclient.ScimClient

com.ibm.security.access.scimcleint.ScimConfig

com.tivoli.am.rba.attributes.AttributeIdentifier

com.tivoli.am.rba.extensions.RBAExtensions

com.tivoli.am.rba.fingerprinting.ValueContainerIdentifierAdapter

com.tivoli.am.rba.extensions.Attribute$Category

com.tivoli.am.rba.extensions.Attribute$DataType

com.tivoli.am.rba.extensions.Attribute

com.tivoli.am.rba.extensions.PluginUtils

The following additional classes are allowed in one-time password and OAuth or API protection mapping rules.

com.tivoli.am.fim.trustserver.sts.modules.http.stsclient.STSClientHelper

com.tivoli.am.fim.trustserver.sts.oauth20.Client

com.tivoli.am.fim.trustserver.sts.oauth20.Grant

com.tivoli.am.fim.trustserver.sts.oauth20.Token

com.tivoli.am.fim.trustserver.sts.STSModuleException

com.tivoli.am.fim.trustserver.sts.STSUniversalUser *

com.tivoli.am.fim.trustserver.sts.uuser.Attribute *

com.tivoli.am.fim.trustserver.sts.uuser.AttributeList *

com.tivoli.am.fim.trustserver.sts.uuser.AttributeStatement *

com.tivoli.am.fim.trustserver.sts.uuser.ContextAttributes *

com.tivoli.am.fim.trustserver.sts.uuser.Group *

com.tivoli.am.fim.trustserver.sts.uuser.Principal *

com.tivoli.am.fim.trustserver.sts.uuser.Subject *

com.tivoli.am.fim.trustserver.sts.uuser.RequestSecurityToken *

com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils

com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtCacheDMAPImpl

com.tivoli.am.fim.trustserver.sts.utilities.InfoCardClaim

com.tivoli.am.fim.trustserver.sts.utilities.QueryServiceAttribute

com.tivoli.am.fim.trustserver.sts.utilities.USCContextAttributesHelper

com.tivoli.am.fim.base64.BASE64Utility

com.tivoli.am.fim.utils.IteratorWrapper

com.tivoli.am.fim.trustserver.sts.utilities.OAuthMappingExtUtils

com.tivoli.am.fim.trustserver.sts.utilities.HttpResponse

com.tivoli.am.rba.pip.JavaScriptPIP

com.tivoli.am.rba.pip.JavaScriptPIP$Context

java.mail.internet.InternetAddress

The following additional classes are allowed in JavaScript PIP mapping rules.

com.tivoli.am.fim.base64.BASE64Utility

com.tivoli.am.rba.rtss.AttributeLocatorImpl

com.tivoli.am.rba.pip.JavaScriptPIP

com.tivoli.am.rba.pip.JavaScriptPIP$Context

Notes:

* The white list does not contain any implementation of the interfaces that are defined in the org.w3c.dom package. For example, you cannot use the method org.w3c.dom.Document toXML() in com.tivoli.am.fim.trustserver.sts.STSUniversalUser.

** Inner classes for these classes are not supported. Methods that involve an inner class implementation of an interface are not available. For example, do not use the following method in java.util.HashMap:

Collection<V> values()

Set<K> keySet()

Set<Map.Entry<K,V>> entrySet()

For more information about dynamic attributes, see Dynamic attributes.

For more information about policy information points, see Managing policy information points.

Parent topic: Advanced Access Control configuration

Related tasks:

Managing OAuth 2.0 mapping rules

Managing mapping rules

Federation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.Federation configuration This section provides configuration procedures for the Federation features.ConfiguringConfiguring is an activity in which you modify the default settings of various parts of the product.Federation overviewIBM Security Access Manager provides a Federation Module so that collaborating organizations can gain secure access to each other's applications. With federated access, you have a secure, seamless sign-on experience to external applications, helping to eliminate the need for providing multiple user IDs and passwords. Upgrading configurationAfter upgrading your Security Access Manager appliance, be aware of some changes to your configuration. SAML 2.0 federations The Federation Module supports SAML 2.0 federations.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.Nested single sign-on flowsYou can nest SAML or OpenID Connect single sign-on flows. That is, you can resume an initial SSO flow after the completion of a second SSO flow. Configuring a reverse proxy point of contact serverConfiguring a SAML 2.0 or OpenID Connect federation requires that you set up a reverse proxy instance as the point of contact.Managing advanced configurationAdjust configuration settings in supported configuration files.

Federation configuration

Use the topics in this hierarchy to configure the Federation features, if you have activated this module.

Federation configuration This section provides configuration procedures for the Federation features.

Federation overview
IBM Security Access Manager provides a Federation Module so that collaborating organizations can gain secure access to each other's applications. With federated access, you have a secure, seamless sign-on experience to external applications, helping to eliminate the need for providing multiple user IDs and passwords.

Upgrading configuration
After upgrading your Security Access Manager appliance, be aware of some changes to your configuration.

SAML 2.0 federations
The Federation Module supports SAML 2.0 federations.

OpenID Connect federations
The Federation Module supports OpenID Connect federations.

Nested single sign-on flows
You can nest SAML or OpenID Connect single sign-on flows. That is, you can resume an initial SSO flow after the completion of a second SSO flow.

Configuring a reverse proxy point of contact server
Configuring a SAML 2.0 or OpenID Connect federation requires that you set up a reverse proxy instance as the point of contact.

Managing advanced configuration
Adjust configuration settings in supported configuration files.

Parent topic: Configuring

Federation overviewFederation overviewIBM Security Access Manager provides a Federation Module so that collaborating organizations can gain secure access to each other's applications. With federated access, you have a secure, seamless sign-on experience to external applications, helping to eliminate the need for providing multiple user IDs and passwords. Federation Module overviewBy definition, a federation is a relationship in which the participating entities agree to use the same technical standard, enabling access to data and resources of one another. It consists of one or more service providers (SP) and an identity provider (IdP). An IdP is a partner in a federation that can authenticate the identity of a user. A service provider is a company or program that provides a business function as a service.The Federation Module provides the following functions:Federated single sign-on (SSO) for users across multiple applications.Support for SAML 2.0 and OpenID Connect protocols for federated access.Pre-integrated federation connectors to popular cloud applications.Activate the Security Access Manager Platform and Federation Module to set up federations.Federation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.

Federation overview

IBM Security Access Manager provides a Federation Module so that collaborating organizations can gain secure access to each other's applications. With federated access, you have a secure, seamless sign-on experience to external applications, helping to eliminate the need for providing multiple user IDs and passwords.

By definition, a federation is a relationship in which the participating entities agree to use the same technical standard, enabling access to data and resources of one another. It consists of one or more service providers (SP) and an identity provider (IdP). An IdP is a partner in a federation that can authenticate the identity of a user. A service provider is a company or program that provides a business function as a service.

The Federation Module provides the following functions:

Federated single sign-on (SSO) for users across multiple applications.

Support for SAML 2.0 and OpenID Connect protocols for federated access.

Pre-integrated federation connectors to popular cloud applications.

Activate the Security Access Manager Platform and Federation Module to set up federations.

Parent topic: Federation configuration

Upgrading configurationAfter upgrading your Security Access Manager appliance, be aware of some changes to your configuration. Federation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.Point of contact profile configuration after an upgradeThe point of contact profile configuration process changed compared to how it was handled before release 9.0.1. Point of contact advanced configuration property updatesThe use of several point of contact advanced configuration properties has changed; some properties are deprecated and one is removed after an upgrade.Change in OpenID Connect relying party mapping ruleIf you're upgrading from version 9.0, you must change the location of the attribute values for issuing authority (iss) and subject (sub). If you don't make these changes, the existing OpenID Connect relying party custom mapping rules fail.

Upgrading configuration

After upgrading your Security Access Manager appliance, be aware of some changes to your configuration.

Point of contact profile configuration after an upgrade
The point of contact profile configuration process changed compared to how it was handled before release 9.0.1.

Point of contact advanced configuration property updates
The use of several point of contact advanced configuration properties has changed; some properties are deprecated and one is removed after an upgrade.

Change in OpenID Connect relying party mapping rule
If you're upgrading from version 9.0, you must change the location of the attribute values for issuing authority (iss) and subject (sub). If you don't make these changes, the existing OpenID Connect relying party custom mapping rules fail.

Parent topic: Federation configuration

Point of contact profile configuration after an upgradeThe point of contact profile configuration process changed compared to how it was handled before release 9.0.1. upgradingpoint of contact configurationIn releases before 9.0.1, the point of contact was configured by using poc.* advanced configuration parameters. The upgrade process maps these values to callback parameters in a point of contact profile.Depending on your upgrade scenario, the upgrade makes the following changes:Point of contact profile configuration upgrade scenarios and changesUpgrade scenarioChangesFrom a fresh 9.0.1 installation to 9.0.2None.From a previously upgraded 9.0.1 to 9.0.2Copies the values of the poc.* advanced configuration parameters to the point of contact profile named Advanced configuration. The values of the equivalent callback parameters are shown in Table 1.Deletes the poc.* advanced configuration properties that were moved to the Advanced configuration profile. The only way that you can update these parameters now is by using the callback parameters.Makes the Advanced configuration profile editable. You can now edit the callback parameters for this profile.Does not change the other point of contact profiles.From any release before 9.0.1 (for example, 9.0 or 8.0.*) to 9.0.2Keeps the read-only current profile, which was on the appliance before the upgrade. This current profile is called Advanced configuration.Removes the other obsolete profiles.Copies the values of the poc.* advanced configuration parameters to the point of contact profile named Advanced configuration. The values of the equivalent callback parameters are shown in Table 1.Deletes the poc.* advanced configuration properties that were moved to the Advanced configuration profile. The only way that you can update these parameters now is by using the callback parameters.Makes the Advanced configuration profile editable. You can now edit the callback parameters for this profile.There are also three preconfigured point of contact profiles which support three EAI authentication methods. See Preconfigured point of contact profilesThe appliance provides three preconfigured point of contact profiles you can use to define how your federation runtime communicates with the point of contact server..For more information, see:Creating a point of contact profileCreate a point of contact server profile to capture the information needed for the runtime to communicate with the point of contact server.Callback parameters and valuesSpecify the callback parameters and values when you define a point of contact profile.Point of contact advanced configuration property updatesThe use of several point of contact advanced configuration properties has changed; some properties are deprecated and one is removed after an upgrade.Upgrading configurationAfter upgrading your Security Access Manager appliance, be aware of some changes to your configuration.

Point of contact profile configuration after an upgrade

The point of contact profile configuration process changed compared to how it was handled before release 9.0.1.

In releases before 9.0.1, the point of contact was configured by using poc.* advanced configuration parameters. The upgrade process maps these values to callback parameters in a point of contact profile.

Depending on your upgrade scenario, the upgrade makes the following changes:

Table 84. Point of contact profile configuration upgrade scenarios and changes

Upgrade scenario
Changes

From a fresh 9.0.1 installation to 9.0.2
None.

From a previously upgraded 9.0.1 to 9.0.2

Copies the values of the poc.* advanced configuration parameters to the point of contact profile named Advanced configuration. The values of the equivalent callback parameters are shown in Table 85.

Deletes the poc.* advanced configuration properties that were moved to the Advanced configuration profile. The only way that you can update these parameters now is by using the callback parameters.

Makes the Advanced configuration profile editable. You can now edit the callback parameters for this profile.

Does not change the other point of contact profiles.

From any release before 9.0.1 (for example, 9.0 or 8.0.*) to 9.0.2

Keeps the read-only current profile, which was on the appliance before the upgrade. This current profile is called Advanced configuration.

Removes the other obsolete profiles.

Copies the values of the poc.* advanced configuration parameters to the point of contact profile named Advanced configuration. The values of the equivalent callback parameters are shown in Table 85.

Deletes the poc.* advanced configuration properties that were moved to the Advanced configuration profile. The only way that you can update these parameters now is by using the callback parameters.

Makes the Advanced configuration profile editable. You can now edit the callback parameters for this profile.

There are also three preconfigured point of contact profiles which support three EAI authentication methods. See Preconfigured point of contact profiles.

For more information, see:

Creating a point of contact profile

Callback parameters and values

Point of contact advanced configuration property updates

Parent topic: Upgrading configuration

Point of contact advanced configuration property updates The use of several point of contact advanced configuration properties has changed; some properties are deprecated and one is removed after an upgrade.deprecated advanced configuration propertiespoint of contact profile configurationremoved advanced configuration propertiesdeleted advanced configuration propertiescallback parametersTable 1 shows the status of the point of contact advanced configuration properties: Point of contact advanced configuration properties status and mapping to callback parametersCallback typeAdvanced configuration property namesStatusNew callback parameter namesignInpoc.signIn.userRequestHeaderDeprecatedfim.user.request.header.namesignInpoc.signIn.attributesResponseHeaderDeprecated fim.attributes.response.header.namesignInpoc.signIn.groupsResponseHeaderDeprecated fim.groups.response.header.namesignInpoc.signIn.serverResposeHeaderDeprecated fim.server.response.header.namesignInpoc.signIn.targetResponseHeaderDeprecated fim.target.response.header.namesignInpoc.signIn.userResponseHeaderDeprecated fim.user.response.header.namesignInpoc.signIn.userSessionResponseHeaderDeprecated fim.user.session.id.response.header.namesignInpoc.signIn.credResponseHeaderDeprecated fim.cred.response.header.namesignInpoc.signIn.urlEncodingEnabledDeprecated url.encoding.enabledsignInpoc.signIn.authenticationLevelResponseHeaderRemoved from Advanced Configuration panel after an upgradeNone.signOutpoc.signOut.userSessionRequestHeaderDeprecatedfim.user.session.id.request.header.namesignOutpoc.signOut.userRequestHeaderDeprecatedfim.user.request.header.namelocalIdpoc.localIdentity.attributesRequestHeaderDeprecated fim.attributes.request.header.namelocalIdpoc.localIdentity.credRequestHeaderDeprecated fim.cred.request.header.namelocalIdpoc.localIdentity.groupsRequestHeaderDeprecated fim.groups.request.header.namelocalIdpoc.localIdentity.userRequestHeaderDeprecated fim.user.request.header.nameauthenticatepoc.websealAuth.userRequestHeaderDeprecated fim.user.request.header.nameauthenticatepoc.websealAuth.authenticationMacrosDeprecated authentication.macrosauthenticatepoc.websealAuth.authLevelContinue use in Advanced Configuration panelNone.authenticatepoc.otp.authLevelContinue use in Advanced Configuration panelNone.authenticatepoc.otp.backwardCompatibilityEnabledContinue use in Advanced Configuration panelNone.authnPolicypoc.authPolicy.allowRequestOverrideContinue use in Advanced Configuration panelNone.authnPolicypoc.authPolicy.authLevelContinue use in Advanced Configuration panelNone.authnPolicypoc.authPolicy.authTypeContinue use in Advanced Configuration panelNone.See more details in Point of contact profile configuration after an upgradeThe point of contact profile configuration process changed compared to how it was handled before release 9.0.1. .Upgrading configurationAfter upgrading your Security Access Manager appliance, be aware of some changes to your configuration.

Point of contact advanced configuration property updates

The use of several point of contact advanced configuration properties has changed; some properties are deprecated and one is removed after an upgrade.

Table 85 shows the status of the point of contact advanced configuration properties:

Table 85. Point of contact advanced configuration properties status and mapping to callback parameters

Callback type | Advanced configuration property names | Status | New callback parameter name
signIn | poc.signIn.userRequestHeader | Deprecated | fim.user.request.header.name
signIn | poc.signIn.attributesResponseHeader | Deprecated | fim.attributes.response.header.name
signIn | poc.signIn.groupsResponseHeader | Deprecated | fim.groups.response.header.name
signIn | poc.signIn.serverResposeHeader | Deprecated | fim.server.response.header.name
signIn | poc.signIn.targetResponseHeader | Deprecated | fim.target.response.header.name
signIn | poc.signIn.userResponseHeader | Deprecated | fim.user.response.header.name
signIn | poc.signIn.userSessionResponseHeader | Deprecated | fim.user.session.id.response.header.name
signIn | poc.signIn.credResponseHeader | Deprecated | fim.cred.response.header.name
signIn | poc.signIn.urlEncodingEnabled | Deprecated | url.encoding.enabled
signIn | poc.signIn.authenticationLevelResponseHeader | Removed from Advanced Configuration panel after an upgrade | None.
signOut | poc.signOut.userSessionRequestHeader | Deprecated | fim.user.session.id.request.header.name
signOut | poc.signOut.userRequestHeader | Deprecated | fim.user.request.header.name
localId | poc.localIdentity.attributesRequestHeader | Deprecated | fim.attributes.request.header.name
localId | poc.localIdentity.credRequestHeader | Deprecated | fim.cred.request.header.name
localId | poc.localIdentity.groupsRequestHeader | Deprecated | fim.groups.request.header.name
localId | poc.localIdentity.userRequestHeader | Deprecated | fim.user.request.header.name
authenticate | poc.websealAuth.userRequestHeader | Deprecated | fim.user.request.header.name
authenticate | poc.websealAuth.authenticationMacros | Deprecated | authentication.macros
authenticate | poc.websealAuth.authLevel | Continue use in Advanced Configuration panel | None.
authenticate | poc.otp.authLevel | Continue use in Advanced Configuration panel | None.
authenticate | poc.otp.backwardCompatibilityEnabled | Continue use in Advanced Configuration panel | None.
authnPolicy | poc.authPolicy.allowRequestOverride | Continue use in Advanced Configuration panel | None.
authnPolicy | poc.authPolicy.authLevel | Continue use in Advanced Configuration panel | None.
authnPolicy | poc.authPolicy.authType | Continue use in Advanced Configuration panel | None.

See more details in Point of contact profile configuration after an upgrade.

Parent topic: Upgrading configuration

Change in OpenID Connect relying party mapping ruleIf you're upgrading from version 9.0, you must change the location of the attribute values for issuing authority (iss) and subject (sub). If you don't make these changes, the existing OpenID Connect relying party custom mapping rules fail.The attribute values for issuing authority (iss) and subject (sub) are now in the attribute container of the Secure Token Service Universal User (STSUU). In 9.0, these attribute values were in the context attributes.For example, the following attributes are in the attribute container for versions 9.0.1 or later:stsuu.getAttributeContainer().getAttributeValueByName("iss"); stsuu.getAttributeContainer().getAttributeValueByName("sub");Action: Change your mapping rules to specify the correct location of the attribute values.Upgrading configurationAfter upgrading your Security Access Manager appliance, be aware of some changes to your configuration.

Change in OpenID Connect relying party mapping rule

If you're upgrading from version 9.0, you must change the location of the attribute values for issuing authority (iss) and subject (sub). If you don't make these changes, the existing OpenID Connect relying party custom mapping rules fail.

The attribute values for issuing authority (iss) and subject (sub) are now in the attribute container of the Secure Token Service Universal User (STSUU). In 9.0, these attribute values were in the context attributes.

For example, the following attributes are in the attribute container for versions 9.0.1 or later:

stsuu.getAttributeContainer().getAttributeValueByName("iss");
stsuu.getAttributeContainer().getAttributeValueByName("sub");

Action: Change your mapping rules to specify the correct location of the attribute values.

Parent topic: Upgrading configuration

SAML 2.0 federationsSAML 2.0 federationsSAML 2.0 federations The Federation Module supports SAML 2.0 federations.federationSAML 2.0 federationsprotocolssupport for SAML 2.0SAML 2.0 federationsdescriptionSAML 2.0 is a protocol that you can use to perform federated single sign-on from identity providers to service providers. In federated single sign-on, users authenticate at identity provider. Service providers consume the identity information asserted by identity providers.SAML 2.0 relies on the use of SOAP, among other technologies, to exchange XML messages over computer networks. The XML messages are exchanged through a series of requests and responses. In this process, one of the federation partners sends a request message to the other federation partner. Then, that receiving partner immediately sends a response message to the partner who sent the request.The SAML specifications include descriptors to establish a federation, initialize, and manage single sign-on. The following descriptors specify the structure, content of the messages, and the way the messages are communicated between partners and users.AssertionsXML-formatted tokens that are used to transfer user identity information, such as the authentication, attribute, and entitlement information, in the messages.ProtocolsThe types of request messages and response messages that are used for obtaining authentication data and for managing identities.BindingsThe communication method that is used to transport the messages.ProfilesCombinations of protocols, assertions, and bindings that are used together to create a federation and enable federated single sign-on.You and your partner must use the same SAML specification (2.0) and agree on which protocols, bindings, and profiles to use.Federation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.SAML 2.0 overviewThe Federation Module relies on the SAML 2.0 specification to establish a federation and to initialize and manage single sign-on. SAML 2.0 profilesSAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.SAML 2.0 bindingsSAML requestors and responders communicate by exchanging messages. The mechanism to transport these messages is called a SAML binding. SAML 2.0 name identifier formatsSAML 2.0 name identifier formats control how the users at identity providers are mapped to users at service providers during single sign-on. Customizing SAML 2.0 identity mappingUse mapping rules to map local identities to SAML 2.0 tokens and to map SAML 2.0 tokens to local identities.Creating a SAML 2.0 federationCreate a federation by gathering the necessary configuration information for input into the local management interface on the appliance.Creating a SAML 2.0 partnerCreate a federation partner by gathering the necessary configuration information for input into the local management interface on the appliance.Configuring STS modulesConfigure Security Token Service (STS) modules to validate and exchange security token types.Customizing the SAML 2.0 login formAn identity provider can customize the default authentication login page with more contextual information.Customizing SAML 2.0 pagesAccess Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed. Configuring the user session ID for the federation runtimeCustomize the user session ID header name so that you can track user sessions, end sessions, or sign out a particular user from a web reverse proxy point of contact server.Synchronizing system clocks in the federationBecause security tokens have expiration times, you and your partner's system clocks must be synchronized.

SAML 2.0 federations

The Federation Module supports SAML 2.0 federations.

SAML 2.0 is a protocol that you can use to perform federated single sign-on from identity providers to service providers. In federated single sign-on, users authenticate at identity provider. Service providers consume the identity information asserted by identity providers.

SAML 2.0 relies on the use of SOAP, among other technologies, to exchange XML messages over computer networks. The XML messages are exchanged through a series of requests and responses.

In this process, one of the federation partners sends a request message to the other federation partner. Then, that receiving partner immediately sends a response message to the partner who sent the request.

The SAML specifications include descriptors to establish a federation, initialize, and manage single sign-on. The following descriptors specify the structure, content of the messages, and the way the messages are communicated between partners and users.

Assertions

XML-formatted tokens that are used to transfer user identity information, such as the authentication, attribute, and entitlement information, in the messages.

Protocols

The types of request messages and response messages that are used for obtaining authentication data and for managing identities.

Bindings

The communication method that is used to transport the messages.

Profiles

Combinations of protocols, assertions, and bindings that are used together to create a federation and enable federated single sign-on.

You and your partner must use the same SAML specification (2.0) and agree on which protocols, bindings, and profiles to use.

SAML 2.0 overview
The Federation Module relies on the SAML 2.0 specification to establish a federation and to initialize and manage single sign-on.

SAML 2.0 profiles
SAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.

SAML 2.0 bindings
SAML requestors and responders communicate by exchanging messages. The mechanism to transport these messages is called a SAML binding.

SAML 2.0 name identifier formats
SAML 2.0 name identifier formats control how the users at identity providers are mapped to users at service providers during single sign-on.

Customizing SAML 2.0 identity mapping
Use mapping rules to map local identities to SAML 2.0 tokens and to map SAML 2.0 tokens to local identities.

Creating a SAML 2.0 federation
Create a federation by gathering the necessary configuration information for input into the local management interface on the appliance.

Creating a SAML 2.0 partner
Create a federation partner by gathering the necessary configuration information for input into the local management interface on the appliance.

Configuring STS modules
Configure Security Token Service (STS) modules to validate and exchange security token types.

Customizing the SAML 2.0 login form
An identity provider can customize the default authentication login page with more contextual information.

Customizing SAML 2.0 pages
Access Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed.

Configuring the user session ID for the federation runtime
Customize the user session ID header name so that you can track user sessions, end sessions, or sign out a particular user from a web reverse proxy point of contact server.

Synchronizing system clocks in the federation
Because security tokens have expiration times, you and your partner's system clocks must be synchronized.

Parent topic: Federation configuration

SAML 2.0 overviewThe Federation Module relies on the SAML 2.0 specification to establish a federation and to initialize and manage single sign-on. SAML 2.0overviewAssertions The assertions contain authentication statements. These authentication statements assert that the principal (that is, the entity that requests access) was authenticated. Assertions can also carry attributes about the user that the identity provider wants to make available to the service provider. Assertions are typically passed from the identity provider to the service provider. The content of the assertions that are created is controlled by the SAML 2.0 specification. Select these assertions when you establish a federation. You can also select these assertions by the definitions that are used in the identity mapping method that you configure. The identity mapping method can either be a custom mapping module or an XSL transform file. The identity mapping also specifies how identities are mapped between federation partners. Protocols SAML 2.0 defines several request-response protocols that correspond to the action that is being communicated in the message. The SAML 2.0 protocols that are supported are:Authentication requestSingle logoutArtifact resolutionName identifier managementSAML 2.0 federations The Federation Module supports SAML 2.0 federations.

SAML 2.0 overview

The Federation Module relies on the SAML 2.0 specification to establish a federation and to initialize and manage single sign-on.

Assertions

The assertions contain authentication statements. These authentication statements assert that the principal (that is, the entity that requests access) was authenticated. Assertions can also carry attributes about the user that the identity provider wants to make available to the service provider.

Assertions are typically passed from the identity provider to the service provider.

The content of the assertions that are created is controlled by the SAML 2.0 specification. Select these assertions when you establish a federation. You can also select these assertions by the definitions that are used in the identity mapping method that you configure.

The identity mapping method can either be a custom mapping module or an XSL transform file. The identity mapping also specifies how identities are mapped between federation partners.

Protocols

SAML 2.0 defines several request-response protocols that correspond to the action that is being communicated in the message. The SAML 2.0 protocols that are supported are:

Authentication request

Single logout

Artifact resolution

Name identifier management

Parent topic: SAML 2.0 federations

SAML 2.0 profilesSAML 2.0 profilesSAML 2.0 profilesSAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.SAML 2.0profilesprofilesSAML 2.0The following profiles are supported:Web browser single sign-onThis profile provides options regarding the initiation of the message flow and the transport of the messages: Flow initiationThe message flow can be initiated from the identity provider or the service provider. BindingsThe following bindings can be used in the Web browser SSO profile:HTTP redirect HTTP POSTHTTP artifactThe choice of binding depends on the type of messages being sent. For example, an authentication request message can be sent from a service provider to an identity provider using HTTP redirect, HTTP POST, or HTTP artifact. The response message can be sent from an identity provider to a service provider by using either HTTP POST or HTTP artifact. A pair of partners in a federation does not need to use the same binding. Single Logout The Single Logout profile is used to terminate all the login sessions currently active for a specified user within the federation. A user who achieves single sign-on to a federation establishes sessions with more than one participant in the federation. The sessions are managed by a session authority, which in many cases is an identity provider. When the user wants to end sessions with all session participants, the session authority can use the single logout profile to globally terminate all active sessions.This profile provides options regarding the initiation of the message flow and the transport of the messages:Flow initiationThe message flow can be initiated from the identity provider or the service provider.BindingsThe following bindings can be used in the Single Logout profile:HTTP redirectHTTP POSTHTTP artifactSOAPName Identifier Management The Name Identifier Management profile manages user identities that are exchanged between identity providers and service providers. This profile can be used by identity providers or service providers to inform their partners when there is a change in user aliases.This profile can also be used by identity providers or service providers to terminate user linkages at the partners.To manage the aliases, the Federation module uses a function that is called the alias service. The alias service stores and retrieves aliases that are related to a federated identity. User aliases are stored and retrieved from high-volume database.This profile provides options regarding the initiation of the message flow and the transport of the messages:Flow initiationThe message flow can be initiated from the identity provider or the service provider. BindingsThe following bindings can be used in the Web browser SSO profile:HTTP redirect HTTP POSTHTTP artifactSOAPSAML 2.0 federations The Federation Module supports SAML 2.0 federations.SAML 2.0 endpoints and URLsCommunications within a federation take place through endpoints on the servers of the identity provider and service provider partners.SAML 2.0 profile initial URLsIn a federated environment, specially formed URLs can be used for user-initiated single sign-on actions. You can initiate a single sign-on flow from the service provider or identity provider.

SAML 2.0 profiles

SAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.

The following profiles are supported:

Web browser single sign-on

This profile provides options regarding the initiation of the message flow and the transport of the messages:

Flow initiation

The message flow can be initiated from the identity provider or the service provider.

Bindings

The following bindings can be used in the Web browser SSO profile:

HTTP redirect

HTTP POST

HTTP artifact

The choice of binding depends on the type of messages being sent. For example, an authentication request message can be sent from a service provider to an identity provider using HTTP redirect, HTTP POST, or HTTP artifact. The response message can be sent from an identity provider to a service provider by using either HTTP POST or HTTP artifact. A pair of partners in a federation does not need to use the same binding.

Single Logout

The Single Logout profile is used to terminate all the login sessions currently active for a specified user within the federation. A user who achieves single sign-on to a federation establishes sessions with more than one participant in the federation.

The sessions are managed by a session authority, which in many cases is an identity provider. When the user wants to end sessions with all session participants, the session authority can use the single logout profile to globally terminate all active sessions.

This profile provides options regarding the initiation of the message flow and the transport of the messages:

Flow initiation

The message flow can be initiated from the identity provider or the service provider.

Bindings

The following bindings can be used in the Single Logout profile:

HTTP redirect

HTTP POST

HTTP artifact

SOAP

Name Identifier Management

The Name Identifier Management profile manages user identities that are exchanged between identity providers and service providers.

This profile can be used by identity providers or service providers to inform their partners when there is a change in user aliases.

This profile can also be used by identity providers or service providers to terminate user linkages at the partners.

To manage the aliases, the Federation module uses a function that is called the alias service. The alias service stores and retrieves aliases that are related to a federated identity. User aliases are stored and retrieved from high-volume database.

This profile provides options regarding the initiation of the message flow and the transport of the messages:

Flow initiation

The message flow can be initiated from the identity provider or the service provider.

Bindings

The following bindings can be used in the Web browser SSO profile:

HTTP redirect

HTTP POST

HTTP artifact

SOAP

SAML 2.0 endpoints and URLs
Communications within a federation take place through endpoints on the servers of the identity provider and service provider partners.

SAML 2.0 profile initial URLs
In a federated environment, specially formed URLs can be used for user-initiated single sign-on actions. You can initiate a single sign-on flow from the service provider or identity provider.

Parent topic: SAML 2.0 federations

SAML 2.0 endpoints and URLsSAML 2.0 endpoints and URLsCommunications within a federation take place through endpoints on the servers of the identity provider and service provider partners.endpointsSAMLprofilesinitial URLs descriptionSAML 2.0endpointsURLsprofilesURLspartner communicationIn a Security Access Manager environment, endpoints fall into two categories:Endpoints that are specified by the federation specification (such as SAML 2.0) and are used for partner-to-partner communication.Endpoints that end users can access to initiate a single sign-on activity. All endpoints can be accessed through URLs. The syntax of the URLs is specific to the purpose of the access and whether the access is by a partner or by an end user.URLs for partner communication The URLs that are used for partner-to-partner communication, such as the exchange of requests, in SAML 2.0 federations are referred to collectively as endpoint URLs. They can also be individually referred to by the name of the protocol and binding or service that they are related to. Administrators who are responsible for installing, configuring, and maintaining the Security Access Manager environment and the partner-to-partner communication in that environment will see references to these endpoint URLs and might find it helpful to understand their purpose. See Endpoint URL specificationsYou must define several endpoints on your point of contact server so that communications can be exchanged between you and your partner. .URLs for user access While the SAML specifications define the endpoints for partner-to-partner communication, they provide limited or no guidance about the endpoints or methods that end users must use to initiate single sign-on actions. Security Access Manager supports specific URLs for end-user initiation of single sign-on actions. In a SAML 2.0 federation, single sign-on actions can be initiated at the identity provider site or the service provider site. URLs that can be used by users to initiate a sign-on action are specific to the a single sign-on action, such as initiate a federated sign on, perform a single logout, or end account linkage. They are also specific to whether the action is being initiated at the identity provider or service provider site. In a Security Access Manager environment, the URLs that can be used for initiating sign-on actions are referred to as profile initial URLs. Architects and application developers, who design and implement the interactions of their users with the single sign-on process, need to understand profile initial URLs.SAML 2.0 profilesSAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.Endpoint URL specificationsYou must define several endpoints on your point of contact server so that communications can be exchanged between you and your partner.

SAML 2.0 endpoints and URLs

Communications within a federation take place through endpoints on the servers of the identity provider and service provider partners.

In a Security Access Manager environment, endpoints fall into two categories:

Endpoints that are specified by the federation specification (such as SAML 2.0) and are used for partner-to-partner communication.

Endpoints that end users can access to initiate a single sign-on activity.

All endpoints can be accessed through URLs. The syntax of the URLs is specific to the purpose of the access and whether the access is by a partner or by an end user.

URLs for partner communication

The URLs that are used for partner-to-partner communication, such as the exchange of requests, in SAML 2.0 federations are referred to collectively as endpoint URLs. They can also be individually referred to by the name of the protocol and binding or service that they are related to. Administrators who are responsible for installing, configuring, and maintaining the Security Access Manager environment and the partner-to-partner communication in that environment will see references to these endpoint URLs and might find it helpful to understand their purpose. See Endpoint URL specifications.

URLs for user access

While the SAML specifications define the endpoints for partner-to-partner communication, they provide limited or no guidance about the endpoints or methods that end users must use to initiate single sign-on actions. Security Access Manager supports specific URLs for end-user initiation of single sign-on actions.

In a SAML 2.0 federation, single sign-on actions can be initiated at the identity provider site or the service provider site. URLs that can be used by users to initiate a sign-on action are specific to the a single sign-on action, such as initiate a federated sign on, perform a single logout, or end account linkage. They are also specific to whether the action is being initiated at the identity provider or service provider site. In a Security Access Manager environment, the URLs that can be used for initiating sign-on actions are referred to as profile initial URLs. Architects and application developers, who design and implement the interactions of their users with the single sign-on process, need to understand profile initial URLs.

Endpoint URL specifications
You must define several endpoints on your point of contact server so that communications can be exchanged between you and your partner.

Parent topic: SAML 2.0 profiles

Endpoint URL specificationsEndpoint URL specificationsEndpoint URL specificationsYou must define several endpoints on your point of contact server so that communications can be exchanged between you and your partner. endpoint URLsSAML 2.0 single sign-on serviceendpoint URLsSAML 2.0endpointsURLsURLsSAML 2.0endpoint URLsassertion consumer serviceendpoint URLsartifact resolution serviceendpoint URLsname identifier serviceendpoint URLsThese endpoints are defined when you configure your federation in Security Access Manager. The endpoints are accessible through URLs and are used by the partners in the federation. The following types of endpoint URLs initiate single sign-on: Single sign-on serviceAssertion consumer serviceSingle logout service endpointArtifact resolution service or SOAP Name identifier management service Single sign-on service endpoint URL (IP)The endpoint on the identity provider point of contact server that receives authentication requests. The unauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/loginWhere:isam_hostnameThe host name of the reverse proxy server for the identity provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.Assertion consumer service endpoint (SP)The endpoint on the service provider point of contact server that receives assertions. The unauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/loginWhere:isam_hostnameThe host name of the reverse proxy server for the service provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.Single logout service endpoint (IP or SP)The endpoint on the service provider or identity provider point of contact server that receives logout requests. The unauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/sloWhere:isam_hostnameThe host name of the reverse proxy server for the service provider or identity provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.Artifact resolution service or SOAP endpoint (IP or SP)The endpoint on the service provider or identity provider where artifacts are exchanged for SAML messages. The unauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/soapWhere:isam_hostnameThe host name of the reverse proxy server for the service provider or identity provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.Name identifier management service endpoint (IP or SP)The endpoint on the service provider or identity provider that receives messages related to the name ID management. The unauth ACL must be attached to this endpoint. The syntax of the URL for HTTP redirect, HTTP POST, and HTTP artifact binding is:https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/mnidsThe syntax of the URL for SOAP binding is:https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/soapWhere:isam_hostnameThe host name of the reverse proxy server for the service provider or identity provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.SAML 2.0 endpoints and URLsCommunications within a federation take place through endpoints on the servers of the identity provider and service provider partners.

Endpoint URL specifications

You must define several endpoints on your point of contact server so that communications can be exchanged between you and your partner.

These endpoints are defined when you configure your federation in Security Access Manager. The endpoints are accessible through URLs and are used by the partners in the federation.

The following types of endpoint URLs initiate single sign-on:

Single sign-on service

Assertion consumer service

Single logout service endpoint

Artifact resolution service or SOAP

Name identifier management service

Single sign-on service endpoint URL (IP)

The endpoint on the identity provider point of contact server that receives authentication requests. The unauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/login

Where:

isam_hostname

The host name of the reverse proxy server for the identity provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

Assertion consumer service endpoint (SP)

The endpoint on the service provider point of contact server that receives assertions. The unauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/login

Where:

isam_hostname

The host name of the reverse proxy server for the service provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

Single logout service endpoint (IP or SP)

The endpoint on the service provider or identity provider point of contact server that receives logout requests. The unauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/slo

Where:

isam_hostname

The host name of the reverse proxy server for the service provider or identity provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

Artifact resolution service or SOAP endpoint (IP or SP)

The endpoint on the service provider or identity provider where artifacts are exchanged for SAML messages. The unauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/soap

Where:

isam_hostname

The host name of the reverse proxy server for the service provider or identity provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

Name identifier management service endpoint (IP or SP)

The endpoint on the service provider or identity provider that receives messages related to the name ID management. The unauth ACL must be attached to this endpoint.

The syntax of the URL for HTTP redirect, HTTP POST, and HTTP artifact binding is:

https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/mnids

The syntax of the URL for SOAP binding is:

https://isam_hostname:port_number/junction_name/sps/federation_name/saml20/soap

Where:

isam_hostname

The host name of the reverse proxy server for the service provider or identity provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

Parent topic: SAML 2.0 endpoints and URLs

SAML 2.0 profile initial URLsSAML 2.0 profile initial URLsIn a federated environment, specially formed URLs can be used for user-initiated single sign-on actions. You can initiate a single sign-on flow from the service provider or identity provider. profilesinitial URLs descriptionURLsSAML 2.0 profile initialSAML 2.0profile initial URLsinitial URLsprofiles for SAML 2.0assertion consumer serviceprofile initial URLssingle sign-on serviceprofile initial URLssingle logout serviceprofile initial URLsname identifier serviceprofile initial URLsThe following profile initial URLs are supported in a Security Access Manager environment: Assertion consumer serviceSingle sign-on serviceSingle logout serviceName identifier management service Assertion consumer service initial URL (SP)Initiate the single sign-on flow at the service provider. The unauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps /federation_name/saml20/logininitial ?RequestBinding=RequestBindingType &ResponseBinding=ResponseBindingType &NameIdFormat=NameIDFormatType &IsPassive=IsPassiveValue &IncludeIsPassive=IncludeIsPassiveValue &ForceAuthn=ForceAuthnValue &IncludeForceAuthn=IncludeForceAuthnValue &AllowCreate=AllowCreateValue &IncludeAllowCreate=IncludeAllowCreateValue &AuthnContextClassRef=ClassRefValues &AuthnContextDeclRef=DeclarationRefValues &AuthnContextComparison=AuthnContectComparisonValue &Target=target_application_locationWhere:isam_hostnameThe host name of the reverse proxy server for the service provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.RequestBindingTypeThe binding that is used to send the request. The valid values when initiating single sign-on at the service provider are:HTTPPostHTTPRedirectHTTPArtifactResponseBindingTypeThe binding that is used by the responder to return the response. The valid values when initiating single sign-on at the service provider are:HTTPPostHTTPArtifactNameIdFormatTypeThe name ID format to use for name identifiers. Valid values are:Transient (anonymous)PersistentEmailIsPassiveValueSpecifies if the identity provider must take control of the user agent. A value of true means that the identity provider is not permitted to request the user to provide log in credentials. The default value is false.IncludeIsPassiveValueSpecifies whether to include the IsPassive attribute in the SAML authentication request. The value of the IsPassive attribute is taken from the IsPassive query string parameter. A value of true includes the attribute. The default value is true.ForceAuthnValueSpecifies if the identity provider authenticates the user. A value of true means that the user must be authenticated. The default value is false.IncludeForceAuthnValueSpecifies whether to include the ForceAuthn attribute in the SAML authentication request. The value of the ForceAuthn attribute is taken from the ForceAuthn query string parameter.A value of true includes the attribute. The default value is true.AllowCreateValueSpecifies if new persistent account linkage is performed on the request. The default value is true. To use this parameter, the NameIdFormat must be set to Persistent.IncludeAllowCreateValueSpecifies whether to include the AllowCreate attribute in the SAML authentication request. The value of the AllowCreate attribute is taken from the AllowCreate query string parameter. A value of true includes the attribute. The default value is true.ClassRefValuesSpecifies one or more string values which identify authentication context class URI references.DeclarationRefValuesSpecifies one or more string values which identify authentication context declaration URI references.AuthnContectComparisonValueSpecifies the type of comparison used to determine the requested context classes or declarations. The comparison type must be one of the following variables: exactminimummaximumbetterThe default value is exact.target_application_locationThe URL of the application that a user can log on to using single sign-on.Example: Single sign-on URL when initiated at the service provider:https://sp.example.com:433/samlsp/sps/spfed/saml20/logininitial ?RequestBinding=HTTPPost &ResponseBinding=HTTPPost &NameIdFormat=Email &IsPassive=true &ForceAuthn=false &Target=https://sp.example.com:433/samlsp/bankingSingle sign-on service initial URL (IP)Initiate the single sign-on flow at the identity provider. The unauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps /federation_name/saml20/logininitial ?RequestBinding=RequestBindingType &PartnerId=target_partner_provider_ID &NameIdFormat=NameIDFormatType &AllowCreate=AllowCreateValue &Target=target_application_locationWhere:isam_hostnameThe host name of the reverse proxy server for the identity provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.RequestBindingTypeThe binding that is used to send the request to the service provider. The valid values when initiating single sign-on at the identity provider are:HTTPPostHTTPArtifacttarget_partner_provider_IDThe provider ID of the target partner.NameIdFormatTypeThe name ID format to use for name identifiers. Valid values are:Transient (anonymous)PersistentEmailAllowCreateValueSpecifies if new persistent account linkage is performed on the request. The default value is false. target_application_locationThis element is URL-encoded and set as the value of the RelayState parameter in the unsolicited response delivered by the identity provider to the service provider. A service provider interprets this value as the URL of the application that a user can log on to using single sign-on.Example: Single sign-on URL when initiated at the identity provider:https://idp.example.com:433/samlip/sps/saml20/saml20/logininitial ?RequestBinding=HTTPPost &NameIdFormat=persistent &AllowCreate=true &PartnerId=https://sp.example.com:433/samlsp/sps/saml20/saml20 &Target=https://sp.example.com:9443/bankingSingle logout service initial URL (IP or SP)Initiate the SLO flow at either the identity provider or service provider. The unauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps /federation_name/saml20/sloinitial ?RequestBinding=RequestBindingTypeWhere:isam_hostnameThe host name of the reverse proxy server for the identity provider or service provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.RequestBindingTypeThe binding that is used to send the request. The valid values are: HTTPPostHTTPRedirectHTTPArtifactHTTPSOAPExamples:Single logout URL when initiated at the service provider:https://sp.example.com:433/samlsp/sps/spfed/saml20/sloinitial ?RequestBinding=HTTPRedirectSingle logout URL when initiated at the identity provider:https://idp.example.com:433/samlip/sps/ipfed/saml20/sloinitial ?RequestBinding=HTTPPostName identifier management service initial URL (IP or SP)Used by the partner to contact the name identifier management server. The anyauth ACL must be attached to this URL. The syntax of the URL is:https://isam_hostname:port_number/junction_name/sps /federation_name/saml20/mnidsinitial ?RequestBinding=RequestBindingType &PartnerId=target_partner_provider_ID &NameIdTerminate=name_ID_terminate_valueWhere:isam_hostnameThe host name of the reverse proxy server for the identity provider or service provider.port_numberThe port number of the reverse proxy server.junction_nameThe name of the junction created on the reverse proxy server.federation_nameThe name you assigned to the federation when you created it.RequestBindingTypeThe binding that is used to send the request. The valid values are: HTTPPostHTTPRedirectHTTPArtifactHTTPSOAPtarget_partner_provider_IDThe provider ID of the target partner.name_ID_terminate_valueA value that indicates if the name ID management flow must terminate the name ID mapping. Valid values are:True: Ends the account linkage.False: Indicates that the name ID flow updates the name identifiers (aliases). False is the default, if you do not explicitly specify a value.Examples:Name ID management initiated by the identity provider:https://idp.example.com:443/samlip/sps/ipfed/saml20/mnidsinitial ?RequestBinding=HTTPSOAP &PartnerId=https://sp.example.com:443/samlsp/sps/spfed/saml20 &NameIdTerminate=trueName ID management initiated by the service provider:https://sp.example.com:443/samlsp/sps/spfed/saml20/mnidsinitial ?RequestBinding=HTTPArtifact &PartnerId=https://idp.example.com:443/samlip/sps/ipfed/saml20 &NameIdTerminate=trueSAML 2.0 profilesSAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.

SAML 2.0 profile initial URLs

In a federated environment, specially formed URLs can be used for user-initiated single sign-on actions. You can initiate a single sign-on flow from the service provider or identity provider.

The following profile initial URLs are supported in a Security Access Manager environment:

Assertion consumer service

Single sign-on service

Single logout service

Name identifier management service

Assertion consumer service initial URL (SP)

Initiate the single sign-on flow at the service provider. The unauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps
  /federation_name/saml20/logininitial
  ?RequestBinding=RequestBindingType
  &ResponseBinding=ResponseBindingType
  &NameIdFormat=NameIDFormatType
  &IsPassive=IsPassiveValue
  &IncludeIsPassive=IncludeIsPassiveValue
  &ForceAuthn=ForceAuthnValue
  &IncludeForceAuthn=IncludeForceAuthnValue
  &AllowCreate=AllowCreateValue
  &IncludeAllowCreate=IncludeAllowCreateValue
  &AuthnContextClassRef=ClassRefValues
  &AuthnContextDeclRef=DeclarationRefValues
  &AuthnContextComparison=AuthnContectComparisonValue
  &Target=target_application_location

Where:

isam_hostname

The host name of the reverse proxy server for the service provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

RequestBindingType

The binding that is used to send the request. The valid values when initiating single sign-on at the service provider are:

HTTPPost

HTTPRedirect

HTTPArtifact

ResponseBindingType

The binding that is used by the responder to return the response. The valid values when initiating single sign-on at the service provider are:

HTTPPost

HTTPArtifact

NameIdFormatType

The name ID format to use for name identifiers. Valid values are:

Transient (anonymous)

Persistent

Email

IsPassiveValue

Specifies if the identity provider must take control of the user agent. A value of true means that the identity provider is not permitted to request the user to provide log in credentials. The default value is false.

IncludeIsPassiveValue

Specifies whether to include the IsPassive attribute in the SAML authentication request. The value of the IsPassive attribute is taken from the IsPassive query string parameter. A value of true includes the attribute. The default value is true.

ForceAuthnValue

Specifies if the identity provider authenticates the user. A value of true means that the user must be authenticated. The default value is false.

IncludeForceAuthnValue

Specifies whether to include the ForceAuthn attribute in the SAML authentication request. The value of the ForceAuthn attribute is taken from the ForceAuthn query string parameter.A value of true includes the attribute. The default value is true.

AllowCreateValue

Specifies if new persistent account linkage is performed on the request. The default value is true. To use this parameter, the NameIdFormat must be set to Persistent.

IncludeAllowCreateValue

Specifies whether to include the AllowCreate attribute in the SAML authentication request. The value of the AllowCreate attribute is taken from the AllowCreate query string parameter. A value of true includes the attribute. The default value is true.

ClassRefValues

Specifies one or more string values which identify authentication context class URI references.

DeclarationRefValues

Specifies one or more string values which identify authentication context declaration URI references.

AuthnContectComparisonValue

Specifies the type of comparison used to determine the requested context classes or declarations. The comparison type must be one of the following variables:

exact

minimum

maximum

better

The default value is exact.

target_application_location

The URL of the application that a user can log on to using single sign-on.

Example:

Single sign-on URL when initiated at the service provider:

https://sp.example.com:433/samlsp/sps/spfed/saml20/logininitial
  ?RequestBinding=HTTPPost
  &ResponseBinding=HTTPPost
  &NameIdFormat=Email
  &IsPassive=true
  &ForceAuthn=false
  &Target=https://sp.example.com:433/samlsp/banking

Single sign-on service initial URL (IP)

Initiate the single sign-on flow at the identity provider. The unauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps
  /federation_name/saml20/logininitial
  ?RequestBinding=RequestBindingType
  &PartnerId=target_partner_provider_ID
  &NameIdFormat=NameIDFormatType
  &AllowCreate=AllowCreateValue
  &Target=target_application_location

Where:

isam_hostname

The host name of the reverse proxy server for the identity provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

RequestBindingType

The binding that is used to send the request to the service provider. The valid values when initiating single sign-on at the identity provider are:

HTTPPost

HTTPArtifact

target_partner_provider_ID

The provider ID of the target partner.

NameIdFormatType

The name ID format to use for name identifiers. Valid values are:

Transient (anonymous)

Persistent

Email

AllowCreateValue

Specifies if new persistent account linkage is performed on the request. The default value is false.

target_application_location

This element is URL-encoded and set as the value of the RelayState parameter in the unsolicited response delivered by the identity provider to the service provider. A service provider interprets this value as the URL of the application that a user can log on to using single sign-on.

Example:

Single sign-on URL when initiated at the identity provider:

https://idp.example.com:433/samlip/sps/saml20/saml20/logininitial
  ?RequestBinding=HTTPPost
  &NameIdFormat=persistent
  &AllowCreate=true
  &PartnerId=https://sp.example.com:433/samlsp/sps/saml20/saml20
  &Target=https://sp.example.com:9443/banking

Single logout service initial URL (IP or SP)

Initiate the SLO flow at either the identity provider or service provider. The unauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps
  /federation_name/saml20/sloinitial
  ?RequestBinding=RequestBindingType

Where:

isam_hostname

The host name of the reverse proxy server for the identity provider or service provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

RequestBindingType

The binding that is used to send the request. The valid values are:

HTTPPost

HTTPRedirect

HTTPArtifact

HTTPSOAP

Examples:

Single logout URL when initiated at the service provider:

https://sp.example.com:433/samlsp/sps/spfed/saml20/sloinitial
  ?RequestBinding=HTTPRedirect

Single logout URL when initiated at the identity provider:

https://idp.example.com:433/samlip/sps/ipfed/saml20/sloinitial
  ?RequestBinding=HTTPPost

Name identifier management service initial URL (IP or SP)

Used by the partner to contact the name identifier management server. The anyauth ACL must be attached to this URL. The syntax of the URL is:

https://isam_hostname:port_number/junction_name/sps
  /federation_name/saml20/mnidsinitial
  ?RequestBinding=RequestBindingType
  &PartnerId=target_partner_provider_ID
  &NameIdTerminate=name_ID_terminate_value

Where:

isam_hostname

The host name of the reverse proxy server for the identity provider or service provider.

port_number

The port number of the reverse proxy server.

junction_name

The name of the junction created on the reverse proxy server.

federation_name

The name you assigned to the federation when you created it.

RequestBindingType

The binding that is used to send the request. The valid values are:

HTTPPost

HTTPRedirect

HTTPArtifact

HTTPSOAP

target_partner_provider_ID

The provider ID of the target partner.

name_ID_terminate_value

A value that indicates if the name ID management flow must terminate the name ID mapping. Valid values are:

True: Ends the account linkage.

False: Indicates that the name ID flow updates the name identifiers (aliases). False is the default, if you do not explicitly specify a value.

Examples:

Name ID management initiated by the identity provider:

https://idp.example.com:443/samlip/sps/ipfed/saml20/mnidsinitial
  ?RequestBinding=HTTPSOAP
  &PartnerId=https://sp.example.com:443/samlsp/sps/spfed/saml20
  &NameIdTerminate=true

Name ID management initiated by the service provider:

https://sp.example.com:443/samlsp/sps/spfed/saml20/mnidsinitial
  ?RequestBinding=HTTPArtifact
  &PartnerId=https://idp.example.com:443/samlip/sps/ipfed/saml20
  &NameIdTerminate=true

Parent topic: SAML 2.0 profiles

SAML 2.0 bindingsSAML 2.0 bindingsSAML 2.0 bindingsSAML requestors and responders communicate by exchanging messages. The mechanism to transport these messages is called a SAML binding. SAML 2.0bindingsbindingsSAML 2.0Security Access Manager supports the following bindings:HTTP redirect HTTP redirect enables SAML protocol messages to be transmitted within URL parameters. It enables SAML requestors and responders to communicate by using an HTTP user agent as an intermediary. The intermediary might be necessary if the communicating entities do not have a direct path of communication. The intermediary might also be necessary if the responder requires interaction with a user agent, such as an authentication agent.HTTP redirect is sometimes called browser redirect in single sign-on operations. This profile is selected by default.HTTP POST HTTP POST enables SAML protocol messages to be transmitted within an HTML form by using base64-encoded content. It enables SAML requestors and responders to communicate by using an HTTP user agent as an intermediary. The agent might be necessary if the communicating entities do not have a direct path of communication. The intermediary might also be necessary if the responder requires interaction with a user agent such as an authentication agent.HTTP POST is sometimes called Browser POST, particularly when used in single sign-on operations. It uses a self-posting form during the establishment and use of a trusted session between an identity provider, a service provider, and a client (browser).HTTP artifact HTTP artifact is a binding in which a SAML request or response (or both) is transmitted by reference by using a unique identifier that is called an artifact. A separate binding, such as a SOAP binding, is used to exchange the artifact for the actual protocol message. It enables SAML requestors and responders to communicate by using an HTTP user agent as an intermediary. This setting is used when it is not preferable to expose the message content to the intermediary.HTTP artifact is sometimes called browser artifact, particularly when used in single sign-on operations. The HTTP artifact uses a SOAP back channel. The SOAP back channel is used to exchange an artifact during the establishment and use of a trusted session between an identity provider, a service provider, and a client (browser). SOAPSOAP is a binding that uses Simple Object Access Protocol (SOAP) for communication. To use SOAP binding, SAML requestors must have a direct communication path with SAML responders.The choice of binding you have depends on the profile you choose to use in your federation.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.

SAML 2.0 bindings

SAML requestors and responders communicate by exchanging messages. The mechanism to transport these messages is called a SAML binding.

Security Access Manager supports the following bindings:

HTTP redirect

HTTP redirect enables SAML protocol messages to be transmitted within URL parameters. It enables SAML requestors and responders to communicate by using an HTTP user agent as an intermediary.

The intermediary might be necessary if the communicating entities do not have a direct path of communication. The intermediary might also be necessary if the responder requires interaction with a user agent, such as an authentication agent.

HTTP redirect is sometimes called browser redirect in single sign-on operations. This profile is selected by default.

HTTP POST

HTTP POST enables SAML protocol messages to be transmitted within an HTML form by using base64-encoded content. It enables SAML requestors and responders to communicate by using an HTTP user agent as an intermediary.

The agent might be necessary if the communicating entities do not have a direct path of communication. The intermediary might also be necessary if the responder requires interaction with a user agent such as an authentication agent.

HTTP POST is sometimes called Browser POST, particularly when used in single sign-on operations. It uses a self-posting form during the establishment and use of a trusted session between an identity provider, a service provider, and a client (browser).

HTTP artifact

HTTP artifact is a binding in which a SAML request or response (or both) is transmitted by reference by using a unique identifier that is called an artifact.

A separate binding, such as a SOAP binding, is used to exchange the artifact for the actual protocol message. It enables SAML requestors and responders to communicate by using an HTTP user agent as an intermediary.

This setting is used when it is not preferable to expose the message content to the intermediary.

HTTP artifact is sometimes called browser artifact, particularly when used in single sign-on operations. The HTTP artifact uses a SOAP back channel. The SOAP back channel is used to exchange an artifact during the establishment and use of a trusted session between an identity provider, a service provider, and a client (browser).

SOAP

SOAP is a binding that uses Simple Object Access Protocol (SOAP) for communication.

To use SOAP binding, SAML requestors must have a direct communication path with SAML responders.

The choice of binding you have depends on the profile you choose to use in your federation.

Parent topic: SAML 2.0 federations

SAML 2.0 name identifier formatsSAML 2.0 name identifier formatsSAML 2.0 name identifier formatsSAML 2.0 name identifier formats control how the users at identity providers are mapped to users at service providers during single sign-on. SAML 2.0name identifier managementname identifier managementSAML 2.0Security Access Manager supports the following name identifier formats: Email addressUse the email address name identifier format if you want a user to log in at the service provider as the same user that they use to log in at the identity provider. For example, if a user is logged in at the identity provider as user1, then they will also be logged in as user1 at the service provider after single sign-on.Persistent aliasesUse the persistent name identifier format if you want a user to log in at the identity provider as one user, but log in at the service provider as a different user. Before you can use this name identifier format, you must link the user at the identity provider with the user at the service provider. You can choose to have the user linking done during single sign-on or by using the alias service. For example, suppose user1 in the identity provider is linked with user2 in the service provider. If user1 is logged in at the identity provider, then they will be logged in as user2 in service provider after single sign-on.Transient aliasesUse the transient name identifier format if you want a user to log in as a shared anonymous user, regardless of which user that they use to log in at the identity provider. For example, suppose user1 is a shared anonymous user in the service provider. If the user is logged in as user2 in the identity provider, then they will be logged in as user1 in the service provider after single sign-on. Similarly, if the user is logged in as user3 in the identity provider, then they will be logged in also as user1 in the service provider.See Alias serviceTo manage the aliases, the Federation module uses an alias service. The alias service stores and retrieves aliases that are related to a federated identity. for information about how to manage aliases.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.Alias serviceTo manage the aliases, the Federation module uses an alias service. The alias service stores and retrieves aliases that are related to a federated identity.

SAML 2.0 name identifier formats

SAML 2.0 name identifier formats control how the users at identity providers are mapped to users at service providers during single sign-on.

Security Access Manager supports the following name identifier formats:

Email address

Use the email address name identifier format if you want a user to log in at the service provider as the same user that they use to log in at the identity provider.

For example, if a user is logged in at the identity provider as user1, then they will also be logged in as user1 at the service provider after single sign-on.

Persistent aliases

Use the persistent name identifier format if you want a user to log in at the identity provider as one user, but log in at the service provider as a different user.

Before you can use this name identifier format, you must link the user at the identity provider with the user at the service provider. You can choose to have the user linking done during single sign-on or by using the alias service.

For example, suppose user1 in the identity provider is linked with user2 in the service provider. If user1 is logged in at the identity provider, then they will be logged in as user2 in service provider after single sign-on.

Transient aliases

Use the transient name identifier format if you want a user to log in as a shared anonymous user, regardless of which user that they use to log in at the identity provider.

For example, suppose user1 is a shared anonymous user in the service provider. If the user is logged in as user2 in the identity provider, then they will be logged in as user1 in the service provider after single sign-on. Similarly, if the user is logged in as user3 in the identity provider, then they will be logged in also as user1 in the service provider.

See Alias service for information about how to manage aliases.

Alias service
To manage the aliases, the Federation module uses an alias service. The alias service stores and retrieves aliases that are related to a federated identity.

Parent topic: SAML 2.0 federations

Alias serviceAlias serviceSAML 2.0 alias serviceTo manage the aliases, the Federation module uses an alias service. The alias service stores and retrieves aliases that are related to a federated identity.alias serviceSAML 2.0SAML 2.0alias servicePersistent name identifier format allows you to link a user at the identity provider with a user at the service provider. Security Access Manager stores these account linkages in a high-volume database. You can manage these account linkages using the alias service REST API. See to the REST API documentation for more information.SAML 2.0 name identifier formatsSAML 2.0 name identifier formats control how the users at identity providers are mapped to users at service providers during single sign-on.

Alias service

To manage the aliases, the Federation module uses an alias service. The alias service stores and retrieves aliases that are related to a federated identity.

Persistent name identifier format allows you to link a user at the identity provider with a user at the service provider. Security Access Manager stores these account linkages in a high-volume database. You can manage these account linkages using the alias service REST API. See to the REST API documentation for more information.

Parent topic: SAML 2.0 name identifier formats

Customizing SAML 2.0 identity mappingCustomizing SAML 2.0 identity mappingCustomizing SAML 2.0 identity mappingUse mapping rules to map local identities to SAML 2.0 tokens and to map SAML 2.0 tokens to local identities.You can use an attribute source, such as LDAP, for the identity mapping. See Managing attribute sourcesUse the Attribute Source management page to add, edit, or delete your identity attribute sources..You can use an HTTP external user mapping to map a local identity to a SAML 2.0 token and to map SAML 2.0 token to a local identity. See Managing JavaScript mapping rulesCreate, edit, or delete JavaScript mapping rules. for information about how to create or modify mapping rules.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.Mapping a local identity to a SAML 2.0 tokenYou can map a local identity to a SAML 2.0 token for an identity provider. Mapping a SAML 2.0 token to a local identityYou can map a SAML 2.0 token to a local identity for a service provider.

Customizing SAML 2.0 identity mapping

Use mapping rules to map local identities to SAML 2.0 tokens and to map SAML 2.0 tokens to local identities.

You can use an attribute source, such as LDAP, for the identity mapping. See Managing attribute sources.

You can use an HTTP external user mapping to map a local identity to a SAML 2.0 token and to map SAML 2.0 token to a local identity.

See Managing JavaScript mapping rules for information about how to create or modify mapping rules.

Mapping a local identity to a SAML 2.0 token
You can map a local identity to a SAML 2.0 token for an identity provider.

Mapping a SAML 2.0 token to a local identity
You can map a SAML 2.0 token to a local identity for a service provider.

Parent topic: SAML 2.0 federations

Mapping a local identity to a SAML 2.0 tokenMapping a local identity to a SAML 2.0 tokenMapping a local identity to a SAML 2.0 tokenYou can map a local identity to a SAML 2.0 token for an identity provider. local user identity mappingfromidentity provider mappingSAML 2.0 token, local user SAML 2.0local user mappingmapping rulesSAML 2.0 token to local identityThe Security Access Manager server places the local user identity information into an XML document that conforms to the security token service universal user (STSUUSER) schema. The identity provider issues a SAML 2.0 token to the service provider. It generates the SAML 2.0 token based on the local identity of the user. You can customize how the local identity is converted into a SAML 2.0 token by using a mapping rule. Security Access Manager first converts the local identity to an STS Universal User. It then converts this STS Universal User into another STS Universal User by using a mapping rule that you provide. After that, it converts the latter STS Universal User to a SAML 2.0 token. Your mapping rule does not operate directly on local identity or SAML 2.0 token. Instead, it operates on the STS Universal User. Any modification that you make to an STS Universal User has an impact on the output SAML 2.0 token.The mapping rule is responsible for the following tasks:Mapping Principal Attr Name to a Principal Name entry. When the token module generates the token, this Principal name is not directly used. Instead, the value in the Name field is sent as input to the alias service. The alias service obtains the alias name, name identifier, for the principal, and places the returned alias in the generated token module.The type must be valid for SAML. For example: urn:oasis:names:tc:SAML:2.0:assertionSetting the authentication method to the password mechanism. This action is required by the SAML standard. Setting the audience of the audience restriction condition to the value of the STSUU element AudienceRestriction. If this STSUU element is not present, the audience is set to the Provider ID of the federation partner.Populating the attribute statement of the assertion with the attributes in the AttributeList in the In-STSUU. This information becomes custom information in the token. Custom attributes might exist that are required by applications that use information that is to be transmitted between federation partners. Customizing SAML 2.0 identity mappingUse mapping rules to map local identities to SAML 2.0 tokens and to map SAML 2.0 tokens to local identities.

Mapping a local identity to a SAML 2.0 token

You can map a local identity to a SAML 2.0 token for an identity provider.

The Security Access Manager server places the local user identity information into an XML document that conforms to the security token service universal user (STSUUSER) schema. The identity provider issues a SAML 2.0 token to the service provider. It generates the SAML 2.0 token based on the local identity of the user. You can customize how the local identity is converted into a SAML 2.0 token by using a mapping rule.

Security Access Manager first converts the local identity to an STS Universal User. It then converts this STS Universal User into another STS Universal User by using a mapping rule that you provide. After that, it converts the latter STS Universal User to a SAML 2.0 token.

Your mapping rule does not operate directly on local identity or SAML 2.0 token. Instead, it operates on the STS Universal User. Any modification that you make to an STS Universal User has an impact on the output SAML 2.0 token.

The mapping rule is responsible for the following tasks:

Mapping Principal Attr Name to a Principal Name entry. When the token module generates the token, this Principal name is not directly used. Instead, the value in the Name field is sent as input to the alias service. The alias service obtains the alias name, name identifier, for the principal, and places the returned alias in the generated token module.

The type must be valid for SAML. For example:

urn:oasis:names:tc:SAML:2.0:assertion

Setting the authentication method to the password mechanism. This action is required by the SAML standard.

Setting the audience of the audience restriction condition to the value of the STSUU element AudienceRestriction. If this STSUU element is not present, the audience is set to the Provider ID of the federation partner.

Populating the attribute statement of the assertion with the attributes in the AttributeList in the In-STSUU. This information becomes custom information in the token.

Custom attributes might exist that are required by applications that use information that is to be transmitted between federation partners.

Parent topic: Customizing SAML 2.0 identity mapping

Mapping a SAML 2.0 token to a local identityMapping a SAML 2.0 token to a local identityMapping a SAML 2.0 token to a local identityYou can map a SAML 2.0 token to a local identity for a service provider.local user identity mappingtoidentity mappingSAML 2.0 token, local user SAML 2.0local user mappingservice provider mappingSAML 2.0 token, local user A service provider consumes a SAML 2.0 token that is issued by an identity provider. It generates the local identity of the user based on a SAML 2.0 token. You can customize how a SAML 2.0 token is converted into the local identity of the user by using a mapping rule. Security Access Manager first converts a SAML 2.0 token to an STS Universal User. It then converts this STS Universal User into another STS Universal User by using a mapping rule that you provide. After that, it converts the latter STS Universal User to a local identity of the user. Your mapping rule does not operate directly on the local identity or SAML 2.0 token. Instead, it operates on the STS Universal User. Any modifications that you make on the STS Universal User impacts the output local identity of the user.Customizing SAML 2.0 identity mappingUse mapping rules to map local identities to SAML 2.0 tokens and to map SAML 2.0 tokens to local identities.

Mapping a SAML 2.0 token to a local identity

You can map a SAML 2.0 token to a local identity for a service provider.

A service provider consumes a SAML 2.0 token that is issued by an identity provider. It generates the local identity of the user based on a SAML 2.0 token. You can customize how a SAML 2.0 token is converted into the local identity of the user by using a mapping rule.

Security Access Manager first converts a SAML 2.0 token to an STS Universal User. It then converts this STS Universal User into another STS Universal User by using a mapping rule that you provide. After that, it converts the latter STS Universal User to a local identity of the user.

Your mapping rule does not operate directly on the local identity or SAML 2.0 token. Instead, it operates on the STS Universal User. Any modifications that you make on the STS Universal User impacts the output local identity of the user.

Parent topic: Customizing SAML 2.0 identity mapping

Creating a SAML 2.0 federationCreating a SAML 2.0 federationCreating a SAML 2.0 federationCreate a federation by gathering the necessary configuration information for input into the local management interface on the appliance.To set up a federation, follow these steps:Create and configure a reverse proxy instance to act as the point of contact for the federation. See Configuring a reverse proxy point of contact serverConfiguring a SAML 2.0 or OpenID Connect federation requires that you set up a reverse proxy instance as the point of contact..Gather the required data. See Gathering your federation configuration informationSetting up a federation requires that you first gather the required information according to your role in the federation..Use the local management interface to create your role in the federation. See Creating and modifying federation propertiesUse the Federations management page to view, create, and modify the details about an existing federation or to modify an existing federation..Next, you can set up your federation partner. See Creating a SAML 2.0 partnerCreate a federation partner by gathering the necessary configuration information for input into the local management interface on the appliance..SAML 2.0 federations The Federation Module supports SAML 2.0 federations.Gathering your federation configuration informationSetting up a federation requires that you first gather the required information according to your role in the federation.

Creating a SAML 2.0 federation

Create a federation by gathering the necessary configuration information for input into the local management interface on the appliance.

To set up a federation, follow these steps:

Create and configure a reverse proxy instance to act as the point of contact for the federation. See Configuring a reverse proxy point of contact server.

Gather the required data. See Gathering your federation configuration information.

Use the local management interface to create your role in the federation. See Creating and modifying federation properties.

Next, you can set up your federation partner. See Creating a SAML 2.0 partner.

Gathering your federation configuration information
Setting up a federation requires that you first gather the required information according to your role in the federation.

Parent topic: SAML 2.0 federations

Gathering your federation configuration informationGathering your federation configuration informationGathering federation configuration informationSetting up a federation requires that you first gather the required information according to your role in the federation.federationinformation gatheringIf your role in the federation is a service provider, fill out this worksheet: SAML 2.0 service provider worksheetIf you are the service provider in the federation and use SAML 2.0, use this worksheet to record your configuration information.If your role in the federation is an identity provider, fill out this worksheet: SAML 2.0 identity provider worksheetIf you are the identity provider in the federation and use SAML 2.0, record your configuration information in the following tables.Creating a SAML 2.0 federationCreate a federation by gathering the necessary configuration information for input into the local management interface on the appliance.SAML 2.0 service provider worksheetIf you are the service provider in the federation and use SAML 2.0, use this worksheet to record your configuration information.SAML 2.0 identity provider worksheetIf you are the identity provider in the federation and use SAML 2.0, record your configuration information in the following tables.

Gathering your federation configuration information

Setting up a federation requires that you first gather the required information according to your role in the federation.

Procedure

If your role in the federation is a service provider, fill out this worksheet: SAML 2.0 service provider worksheet

If your role in the federation is an identity provider, fill out this worksheet: SAML 2.0 identity provider worksheet

SAML 2.0 service provider worksheet
If you are the service provider in the federation and use SAML 2.0, use this worksheet to record your configuration information.

SAML 2.0 identity provider worksheet
If you are the identity provider in the federation and use SAML 2.0, record your configuration information in the following tables.

Parent topic: Creating a SAML 2.0 federation

SAML 2.0 service provider worksheetIf you are the service provider in the federation and use SAML 2.0, use this worksheet to record your configuration information.SAML 2.0worksheetsservice providerservice providerSAML 2.0 worksheetworksheetsSAML 2.0SP worksheetworksheetsSAML 2.0service providerFederation protocolFederation protocolDescriptionYour valueFederation nameThe name you want to give this federation. The name must not contain any ASCII control characters or special characters except hyphen and underscore.Select the protocol for this federation:OpenID ConnectSAML 2.0The protocol you want to use in the federation.In these instructions, use SAML 2.0. TemplateTemplateDescriptionYour valueSelect the template:Quick ConnectSAML 2.0Choose Quick Connect to quickly set up an identity provider federation to work with partner templates that can assist with the establishment of federations to well-known partners. Choose SAML 2.0 to use the full set of configuration options. Because this is SAML 2.0 service provider worksheet, select SAML 2.0 as the template.The template cannot be changed after a federation is created.SAML 2.0 General informationGeneral informationDescriptionYour valueCompany nameThe name of the company that is creating this provider.Provider IDA unique identifier that identifies the provider to its partner provider. The default value is point_of_contact _server_URL/federation_name/saml20.RoleYour role is either Identity Provider or Service Provider. An identity provider vouches for the identity of the end user. The Identity Provider authenticates the user and provides an authentication token to the service provider.A service provider provides a service to end users. In most cases, service providers do not authenticate users, but instead request authentication decisions from an identity provider. You cannot change the role after a federation is created.Service provider Point of contact serverPoint of contact serverDescriptionYour valuePoint of contact server URLThe endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format ishttp[s]://hostname[:portnumber]/[junction]/sps Profile selection Profile selectionDescriptionYour valueSAML 2.0 profile options:Web Browser Single Sign-onName Identifier ManagementSingle LogoutThe profile for your federation. The Web Browser Single Sign-on profile must be selected by default. You cannot clear this selection.For more information about profiles, see SAML 2.0 profilesSAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.. Single Sign-on settingsSettingsDescriptionYour valueBindings:You can choose one or more binding options. HTTP ArtifactHTTP POSTHTTP RedirectThe choice of binding depends on the type of messages sent. For example, an authentication request message can be sent from service provider to an identity provider. The response message can be sent from an identity provider to a service provider by using either HTTP POST or HTTP artifact. A pair of partners in a federation does not need to use the same binding.The default NameID formatThe default format determines processing rules for the NameID value if one of the following items is true:The format attribute is not setThe format attribute is set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecifiedChoose one of the following formats:urn:oasis:names:tc:SAML:2.0:nameid-format:persistenturn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressurn:oasis:names:tc:SAML:2.0:nameid-format:transientRequire signature on incoming SAML assertionsSpecifies that you require your partner to sign SAML assertions. You will validate the signature on the incoming SAML assertions. Require outgoing SAML authentication requests to be signedSpecifies that you require your partner to validate the signature on SAML authentication requests. You will sign the outgoing SAML authentication requests. Name Identifier Management settingsSettingsDescriptionYour valueBindings:You can choose one or more binding options. HTTP ArtifactHTTP POSTHTTP RedirectHTTP SOAPThe choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding.Message signatures Select which outgoing SAML messages require a signature:Name identifier management requestsName identifier management responsesSpecifies whether you will sign the outgoing SAML name identifier management requests and responses. Single logout settingsSettingsDescriptionYour valueBindings:You can choose one or more binding options. HTTP ArtifactHTTP POSTHTTP RedirectHTTP SOAPThe choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding. Message signatures Select which outgoing SAML messages require a signature:Single logout requestsSingle logout responsesSpecifies whether you will sign the outgoing SAML logout requests and responses. Signature optionsSignaturesDescriptionYour valueCertificate databaseSelect the database where the signing certificate is storedCertificate labelName of the certificate to use for signing.Include the following KeyInfo elementsDetermine which KeyInfo elements to include in the digital signature for a SAML message or assertion. X509 certificate dataSpecify whether you want the BASE64 encoded certificate data to be included with your signature. The default action is to include the X.509 certificate data. X509 Subject NameSpecify whether you want the subject name to be included with your signature. The default action is to exclude the X.509 subject name.X509 Subject Key IdentifierSpecify whether you want the X.509 subject key identifier to be included with your signature. The default action is to exclude the subject key identifier. X509 Subject Issuer DetailsSpecify whether you want the issuer name and the certificate serial number to be included with your signature. The default action is to exclude the X.509 subject issuer details.Public keySpecify whether you want the public key to be included with your signature. The default action is to exclude the public key. Encryption optionsSignaturesDescriptionYour valueCertificate databaseSelect the database where the encryption certificate is storedCertificate labelName of the certificate to use for encryption. SAML message settingsMessage settingsDescriptionYour valueMessage Lifetime in secondsAn integer value specifying the length of time, in seconds, that a message is valid. The default value is 300. Artifact Lifetime in secondsThe length of time, in seconds, that an artifact is considered valid. This field is only valid when HTTP artifact binding has been enabled. The default value is 120.Session Timeout in secondsThe length of time, in seconds, that the session remains valid. The default value is 7200.Select which outgoing messages require a signature:Artifact requestsArtifact responsesSpecifies whether you will sign the outgoing SAML artifact requests and responses.Message issuer formatFormat attribute of the Issuer of the SAML message.Message issuer name qualifierName qualifier attribute of the Issuer of the SAML message. Identity mapping settingsIdentity mapping DescriptionYour valueIdentity mapping options Use JavaScript transformation for identity mappingUse an external web service for identity mappingIf you configure an identity provider, this mapping specifies how to create an assertion that contains attributes that are mapped from a local user account. If you configure a service provider, this mapping specifies how to match an assertion from the partner to the local user accounts.If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.If you choose an external web service, on a subsequent panel, you are asked to provide the following information:URI format (HTTP or HTTPS)Web service URI Server Certificate database, if the URI format is HTTPS Client authentication type, if the URI format is HTTPS Message format: XMLWS-Trust After you complete the tables, continue with the instructions in Creating and modifying a federationUse the Federations management page to view, create, and modify the details about an existing federation or to modify an existing federation..Gathering your federation configuration informationSetting up a federation requires that you first gather the required information according to your role in the federation.

SAML 2.0 service provider worksheet

If you are the service provider in the federation and use SAML 2.0, use this worksheet to record your configuration information.

Table 86. Federation protocol

Federation protocol
Description
Your value

Federation name
The name you want to give this federation.

The name must not contain any ASCII control characters or special characters except hyphen and underscore.

Select the protocol for this federation:

OpenID Connect

SAML 2.0

The protocol you want to use in the federation.
In these instructions, use SAML 2.0.

Table 87. Template

Template
Description
Your value

Select the template:

Quick Connect

SAML 2.0

Choose Quick Connect to quickly set up an identity provider federation to work with partner templates that can assist with the establishment of federations to well-known partners.

Choose SAML 2.0 to use the full set of configuration options.

Because this is SAML 2.0 service provider worksheet, select SAML 2.0 as the template.

The template cannot be changed after a federation is created.

SAML 2.0

Table 88. General information

General information
Description
Your value

Company name
The name of the company that is creating this provider.

Provider ID
A unique identifier that identifies the provider to its partner provider.

The default value is point_of_contact _server_URL/federation_name/saml20.

Role
Your role is either Identity Provider or Service Provider.

An identity provider vouches for the identity of the end user. The Identity Provider authenticates the user and provides an authentication token to the service provider.

A service provider provides a service to end users. In most cases, service providers do not authenticate users, but instead request authentication decisions from an identity provider. You cannot change the role after a federation is created.

Service provider

Table 89. Point of contact server

Point of contact server
Description
Your value

Point of contact server URL
The endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format is

http[s]://hostname[:portnumber]/[junction]/sps

Table 90. Profile selection

Profile selection
Description
Your value

SAML 2.0 profile options:

Web Browser Single Sign-on

Name Identifier Management

Single Logout

The profile for your federation. The Web Browser Single Sign-on profile must be selected by default. You cannot clear this selection.

For more information about profiles, see SAML 2.0 profiles.

Table 91. Single Sign-on settings

Settings
Description
Your value

Bindings:

You can choose one or more binding options.

HTTP Artifact

HTTP POST

HTTP Redirect

The choice of binding depends on the type of messages sent. For example, an authentication request message can be sent from service provider to an identity provider. The response message can be sent from an identity provider to a service provider by using either HTTP POST or HTTP artifact.

A pair of partners in a federation does not need to use the same binding.

The default NameID format
The default format determines processing rules for the NameID value if one of the following items is true:

The format attribute is not set

The format attribute is set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Choose one of the following formats:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

urn:oasis:names:tc:SAML:2.0:nameid-format:transient

Require signature on incoming SAML assertions
Specifies that you require your partner to sign SAML assertions. You will validate the signature on the incoming SAML assertions.

Require outgoing SAML authentication requests to be signed
Specifies that you require your partner to validate the signature on SAML authentication requests. You will sign the outgoing SAML authentication requests.

Table 92. Name Identifier Management settings

Settings
Description
Your value

Bindings:

You can choose one or more binding options.

HTTP Artifact

HTTP POST

HTTP Redirect

HTTP SOAP

The choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding.

Message signatures Select which outgoing SAML messages require a signature:

Name identifier management requests

Name identifier management responses

Specifies whether you will sign the outgoing SAML name identifier management requests and responses.

Table 93. Single logout settings

Settings
Description
Your value

Bindings:

You can choose one or more binding options.

HTTP Artifact

HTTP POST

HTTP Redirect

HTTP SOAP

The choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding.

Message signatures Select which outgoing SAML messages require a signature:

Single logout requests

Single logout responses

Specifies whether you will sign the outgoing SAML logout requests and responses.

Table 94. Signature options

Signatures
Description
Your value

Certificate database

Select the database where the signing certificate is stored

Certificate label

Name of the certificate to use for signing.

Include the following KeyInfo elements
Determine which KeyInfo elements to include in the digital signature for a SAML message or assertion.

X509 certificate data

Specify whether you want the BASE64 encoded certificate data to be included with your signature. The default action is to include the X.509 certificate data.

X509 Subject Name

Specify whether you want the subject name to be included with your signature. The default action is to exclude the X.509 subject name.

X509 Subject Key Identifier

Specify whether you want the X.509 subject key identifier to be included with your signature. The default action is to exclude the subject key identifier.

X509 Subject Issuer Details

Specify whether you want the issuer name and the certificate serial number to be included with your signature. The default action is to exclude the X.509 subject issuer details.

Public key

Specify whether you want the public key to be included with your signature. The default action is to exclude the public key.

Table 95. Encryption options

Signatures
Description
Your value

Certificate database

Select the database where the encryption certificate is stored

Certificate label

Name of the certificate to use for encryption.

Table 96. SAML message settings

Message settings
Description
Your value

Message Lifetime in seconds
An integer value specifying the length of time, in seconds, that a message is valid. The default value is 300. 

Artifact Lifetime in seconds
The length of time, in seconds, that an artifact is considered valid. This field is only valid when HTTP artifact binding has been enabled. The default value is 120.

Session Timeout in seconds
The length of time, in seconds, that the session remains valid. The default value is 7200.

Select which outgoing messages require a signature:

Artifact requests

Artifact responses

Specifies whether you will sign the outgoing SAML artifact requests and responses.

Message issuer format
Format attribute of the Issuer of the SAML message.

Message issuer name qualifier
Name qualifier attribute of the Issuer of the SAML message.

Table 97.  Identity mapping settings

Identity mapping
Description
Your value

Identity mapping options

Use JavaScript transformation for identity mapping

Use an external web service for identity mapping

If you configure an identity provider, this mapping specifies how to create an assertion that contains attributes that are mapped from a local user account.

If you configure a service provider, this mapping specifies how to match an assertion from the partner to the local user accounts.

If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.

If you choose an external web service, on a subsequent panel, you are asked to provide the following information:

URI format (HTTP or HTTPS)

Web service URI

Server Certificate database, if the URI format is HTTPS

Client authentication type, if the URI format is HTTPS

Message format:

XML

WS-Trust

After you complete the tables, continue with the instructions in Creating and modifying a federation.

Parent topic: Gathering your federation configuration information

SAML 2.0 identity provider worksheetIf you are the identity provider in the federation and use SAML 2.0, record your configuration information in the following tables.SAML 2.0worksheetsidentity provideridentity providerSAML 2.0 worksheetworksheetsSAML 2.0IDPworksheetsSAML 2.0identity provider Federation protocolFederation protocolDescriptionYour valueFederation nameThe name you want to give this federation. The name must not contain any ASCII control characters or special characters except hyphen and underscore.Select the protocol for this federation:OpenID ConnectSAML 2.0The protocol you want to use in the federation.In these instructions, use SAML 2.0.TemplateTemplateDescriptionYour valueSelect the template:Quick ConnectSAML 2.0Choose Quick Connect to quickly set up an identity provider federation to work with partner templates that can assist with the establishment of federations to well-known partners. Choose SAML 2.0 to use the full set of configuration options. The template cannot be changed after a federation is created. General informationGeneral informationDescriptionYour valueCompany nameThe name of the company that is creating this provider.Provider IDA unique identifier that identifies the provider to its partner provider. The default value is point_of_contact _server_URL/federation_name/saml20.RoleYour role is either Identity Provider or Service Provider. An identity provider vouches for the identity of the end user. The Identity Provider authenticates the user and provides an authentication token to the service provider.A service provider provides a service to end users. In most cases, service providers do not authenticate users, but instead request authentication decisions from an identity provider. You cannot change the role after a federation is created.Identity provider Point of contact serverPoint of contact serverDescriptionYour valuePoint of contact server URLThe endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format ishttp[s]://hostname[:portnumber]/[junction]/spsProfile selection Profile selectionDescriptionYour valueSAML 2.0 profile options:Web Browser Single Sign-onName Identifier ManagementSingle LogoutThe profile for your federation. The Web Browser Single Sign-on profile must be selected by default. You cannot clear this selection.For more information about profiles, see SAML 2.0 profilesSAML 2.0 profiles combine protocols, assertions, and bindings to create a federation and enable federated single sign-on.. Single Sign-on settingsSettingsDescriptionYour valueBindings:You can choose one or more binding options. HTTP ArtifactHTTP POSTHTTP RedirectThe choice of binding depends on the type of messages sent. For example, an authentication request message can be sent from a service provider to an identity provider. The response message can be sent from an identity provider to a service provider by using either HTTP POST or HTTP artifact. A pair of partners in a federation does not need to use the same binding.The default NameID formatThe default format determines processing rules for the NameID value if one of the following items is true:The format attribute is not setThe format attribute is set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecifiedChoose one of the following formats:urn:oasis:names:tc:SAML:2.0:nameid-format:persistenturn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressurn:oasis:names:tc:SAML:2.0:nameid-format:transientAmount of time, in seconds, before the issue date that an assertion is considered validSpecifies that you require your partner to sign SAML validations. You will validate the signature on the incoming SAML assertions.Amount of time, in seconds, that the assertion is valid before being issuedSpecifies that you require your partner to validate the signature on SAML authentication requests. You will sign the outgoing SAML authentication requests.Require consent to federateRequires the identity provider to present a page to the user verifying the federation request.Require signature on incoming SAML assertionsSpecifies that you require your partner to sign SAML assertions. You will validate the signature on the incoming SAML assertions. Require outgoing SAML authentication requests to be signedSpecifies that you require your partner to validate the signature on SAML authentication requests. You will sign the outgoing SAML authentication requests. Name Identifier Management settingsSettingsDescriptionYour valueBindings:You can choose one or more binding options. HTTP ArtifactHTTP POSTHTTP RedirectHTTP SOAPThe choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding.Message signatures Select which outgoing SAML messages require a signature:Name identifier management requestsName identifier management responsesSpecifies whether you will sign the outgoing SAML name identifier management requests and responses. Single logout settingsSettingsDescriptionYour valueBindings:You can choose one or more binding options. HTTP ArtifactHTTP POSTHTTP RedirectHTTP SOAPThe choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding. Message signatures Select which outgoing SAML messages require a signature:Single logout requestsSingle logout responsesSpecifies whether you will sign the outgoing SAML logout requests and responses.Signature optionsSignaturesDescriptionYour value Certificate database Select the database where the signing certificate is stored Certificate label Name of the certificate to use for signing. Include the following KeyInfo elementsDetermine which KeyInfo elements to include in the digital signature for a SAML message or assertion. X509 certificate dataSpecify whether you want the BASE64 encoded certificate data to be included with your signature. The default action is to include the X.509 certificate data. X509 Subject NameSpecify whether you want the subject name to be included with your signature. The default action is to exclude the X.509 subject name.X509 Subject Key IdentifierSpecify whether you want the X.509 subject key identifier to be included with your signature. The default action is to exclude the subject key identifier. X509 Subject Issuer DetailsSpecify whether you want the issuer name and the certificate serial number to be included with your signature. The default action is to exclude the X.509 subject issuer details.Public keySpecify whether you want the public key to be included with your signature. The default action is to exclude the public key. Encryption optionsSignaturesDescriptionYour value Certificate database Select the database where the encryption certificate is stored Certificate label Name of the certificate to use for encryption. SAML message settingsMessage settingsDescriptionYour valueMessage Lifetime in secondsAn integer value specifying the length of time, in seconds, that a message is valid. The default value is 300. Artifact Lifetime in secondsThe length of time, in seconds, that an artifact is considered valid. This field is only valid when HTTP artifact binding has been enabled. The default value is 120.Session Timeout in secondsThe length of time, in seconds, that the session remains valid. The default value is 7200. Select which outgoing messages require a signature:Artifact requestsArtifact responses Specifies whether you will sign the outgoing SAML artifact requests and responses.Message issuer formatFormat attribute of the Issuer of the SAML message.Message issuer name qualifierName qualifier attribute of the Issuer of the SAML message. Identity mapping settingsIdentity mapping DescriptionYour value Identity mapping options Use JavaScript transformation for identity mappingUse an external web service for identity mapping If you configure an identity provider, this mapping specifies how to create an assertion that contains attributes that are mapped from a local user account. If you configure a service provider, this mapping specifies how to match an assertion from the partner to the local user accounts.If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.If you choose an external web service, on a subsequent panel, you are asked to provide the following information:URI format (HTTP or HTTPS)Web service URI Server Certificate database, if the URI format is HTTPS Client authentication type, if the URI format is HTTPS Message format: XMLWS-Trust After you complete the tables, continue with the instructions in Creating and modifying a federationUse the Federations management page to view, create, and modify the details about an existing federation or to modify an existing federation..Gathering your federation configuration informationSetting up a federation requires that you first gather the required information according to your role in the federation.

SAML 2.0 identity provider worksheet

If you are the identity provider in the federation and use SAML 2.0, record your configuration information in the following tables.

Table 98. Federation protocol

Federation protocol
Description
Your value

Federation name
The name you want to give this federation.

The name must not contain any ASCII control characters or special characters except hyphen and underscore.

Select the protocol for this federation:

OpenID Connect

SAML 2.0

The protocol you want to use in the federation.
In these instructions, use SAML 2.0.

Table 99. Template

Template
Description
Your value

Select the template:

Quick Connect

SAML 2.0

Choose Quick Connect to quickly set up an identity provider federation to work with partner templates that can assist with the establishment of federations to well-known partners.

Choose SAML 2.0 to use the full set of configuration options.

The template cannot be changed after a federation is created.

Table 100. General information

General information
Description
Your value

Company name
The name of the company that is creating this provider.

Provider ID
A unique identifier that identifies the provider to its partner provider.

The default value is point_of_contact _server_URL/federation_name/saml20.

Role
Your role is either Identity Provider or Service Provider.

An identity provider vouches for the identity of the end user. The Identity Provider authenticates the user and provides an authentication token to the service provider.

A service provider provides a service to end users. In most cases, service providers do not authenticate users, but instead request authentication decisions from an identity provider. You cannot change the role after a federation is created.

Identity provider

Table 101. Point of contact server

Point of contact server
Description
Your value

Point of contact server URL
The endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format is

http[s]://hostname[:portnumber]/[junction]/sps

Table 102. Profile selection

Profile selection
Description
Your value

SAML 2.0 profile options:

Web Browser Single Sign-on

Name Identifier Management

Single Logout

The profile for your federation. The Web Browser Single Sign-on profile must be selected by default. You cannot clear this selection.

For more information about profiles, see SAML 2.0 profiles.

Table 103. Single Sign-on settings

Settings
Description
Your value

Bindings:

You can choose one or more binding options.

HTTP Artifact

HTTP POST

HTTP Redirect

The choice of binding depends on the type of messages sent. For example, an authentication request message can be sent from a service provider to an identity provider. The response message can be sent from an identity provider to a service provider by using either HTTP POST or HTTP artifact.

A pair of partners in a federation does not need to use the same binding.

The default NameID format
The default format determines processing rules for the NameID value if one of the following items is true:

The format attribute is not set

The format attribute is set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Choose one of the following formats:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

urn:oasis:names:tc:SAML:2.0:nameid-format:transient

Amount of time, in seconds, before the issue date that an assertion is considered valid
Specifies that you require your partner to sign SAML validations. You will validate the signature on the incoming SAML assertions.

Amount of time, in seconds, that the assertion is valid before being issued
Specifies that you require your partner to validate the signature on SAML authentication requests. You will sign the outgoing SAML authentication requests.

Require consent to federate
Requires the identity provider to present a page to the user verifying the federation request.

Require signature on incoming SAML assertions
Specifies that you require your partner to sign SAML assertions. You will validate the signature on the incoming SAML assertions.

Require outgoing SAML authentication requests to be signed
Specifies that you require your partner to validate the signature on SAML authentication requests. You will sign the outgoing SAML authentication requests.

Table 104. Name Identifier Management settings

Settings
Description
Your value

Bindings:

You can choose one or more binding options.

HTTP Artifact

HTTP POST

HTTP Redirect

HTTP SOAP

The choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding.

Message signatures Select which outgoing SAML messages require a signature:

Name identifier management requests

Name identifier management responses

Specifies whether you will sign the outgoing SAML name identifier management requests and responses.

Table 105. Single logout settings

Settings
Description
Your value

Bindings:

You can choose one or more binding options.

HTTP Artifact

HTTP POST

HTTP Redirect

HTTP SOAP

The choice of binding depends on the type of messages sent. A pair of partners in a federation does not need to use the same binding.

Message signatures Select which outgoing SAML messages require a signature:

Single logout requests

Single logout responses

Specifies whether you will sign the outgoing SAML logout requests and responses.

Table 106. Signature options

Signatures
Description
Your value

Certificate database

Select the database where the signing certificate is stored

Certificate label

Name of the certificate to use for signing.

Include the following KeyInfo elements
Determine which KeyInfo elements to include in the digital signature for a SAML message or assertion.

X509 certificate data

Specify whether you want the BASE64 encoded certificate data to be included with your signature. The default action is to include the X.509 certificate data.

X509 Subject Name

Specify whether you want the subject name to be included with your signature. The default action is to exclude the X.509 subject name.

X509 Subject Key Identifier

Specify whether you want the X.509 subject key identifier to be included with your signature. The default action is to exclude the subject key identifier.

X509 Subject Issuer Details

Specify whether you want the issuer name and the certificate serial number to be included with your signature. The default action is to exclude the X.509 subject issuer details.

Public key

Specify whether you want the public key to be included with your signature. The default action is to exclude the public key.

Table 107. Encryption options

Signatures
Description
Your value

Certificate database

Select the database where the encryption certificate is stored

Certificate label

Name of the certificate to use for encryption.

Table 108. SAML message settings

Message settings
Description
Your value

Message Lifetime in seconds
An integer value specifying the length of time, in seconds, that a message is valid. The default value is 300. 

Artifact Lifetime in seconds
The length of time, in seconds, that an artifact is considered valid. This field is only valid when HTTP artifact binding has been enabled. The default value is 120.

Session Timeout in seconds
The length of time, in seconds, that the session remains valid. The default value is 7200.

Select which outgoing messages require a signature:

Artifact requests

Artifact responses

Specifies whether you will sign the outgoing SAML artifact requests and responses.

Message issuer format
Format attribute of the Issuer of the SAML message.

Message issuer name qualifier
Name qualifier attribute of the Issuer of the SAML message.

Table 109.  Identity mapping settings

Identity mapping
Description
Your value

Identity mapping options

Use JavaScript transformation for identity mapping

Use an external web service for identity mapping

If you configure an identity provider, this mapping specifies how to create an assertion that contains attributes that are mapped from a local user account.

If you configure a service provider, this mapping specifies how to match an assertion from the partner to the local user accounts.

If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.

If you choose an external web service, on a subsequent panel, you are asked to provide the following information:

URI format (HTTP or HTTPS)

Web service URI

Server Certificate database, if the URI format is HTTPS

Client authentication type, if the URI format is HTTPS

Message format:

XML

WS-Trust

After you complete the tables, continue with the instructions in Creating and modifying a federation.

Parent topic: Gathering your federation configuration information

Creating a SAML 2.0 partnerCreating a SAML 2.0 partnerCreating a SAML 2.0 partnerCreate a federation partner by gathering the necessary configuration information for input into the local management interface on the appliance.To set up a federation, follow these steps:Gather the required data. See Obtaining federation configuration data from your partnerYou must obtain configuration information from your partner before you can add that partner to a federation..Use the local management interface to configure your partner. See Managing federated partnersUse the Federations management page to create, modify, delete, enable, or disable your federation partners.. This process includes exporting a metadata file for the partner.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.Obtaining federation configuration data from your partnerYou must obtain configuration information from your partner before you can add that partner to a federation.

Creating a SAML 2.0 partner

Create a federation partner by gathering the necessary configuration information for input into the local management interface on the appliance.

To set up a federation, follow these steps:

Gather the required data. See Obtaining federation configuration data from your partner.

Use the local management interface to configure your partner. See Managing federated partners. This process includes exporting a metadata file for the partner.

Obtaining federation configuration data from your partner
You must obtain configuration information from your partner before you can add that partner to a federation.

Parent topic: SAML 2.0 federations

Obtaining federation configuration data from your partnerObtaining federation configuration data from your partnerObtaining federation configuration data from your partnerYou must obtain configuration information from your partner before you can add that partner to a federation.partnerobtaining configuration fromfederationpartnerconfiguringobtainingconfigurationpartnerobtaining frommetadatapartnerobtaining fromThe partner can export the federation configuration to a metadata file.To help you gather the appropriate information from your partner, complete the appropriate worksheet for the role that your partner will have in the federation: If you are the identity provider, add a service provider partner. Use the SAML 2.0 service provider partner worksheetIf you use SAML 2.0 in your role as an identity provider, you must add a service provider partner to your federation..If you are the service provider, add an identity provider partner. Use the SAML 2.0 identity provider partner worksheetIf you use SAML 2.0 in your role as a service provider, you must add an identity provider partner to your federation..After gathering the configuration information of your partner, use the local management interface to add the federation partner properties. See Managing federation partnersUse the Federations management page to create, modify, delete, enable, or disable your federation partners..Creating a SAML 2.0 partnerCreate a federation partner by gathering the necessary configuration information for input into the local management interface on the appliance.SAML 2.0 service provider partner worksheetIf you use SAML 2.0 in your role as an identity provider, you must add a service provider partner to your federation.SAML 2.0 identity provider partner worksheetIf you use SAML 2.0 in your role as a service provider, you must add an identity provider partner to your federation.

Obtaining federation configuration data from your partner

You must obtain configuration information from your partner before you can add that partner to a federation.

The partner can export the federation configuration to a metadata file.

To help you gather the appropriate information from your partner, complete the appropriate worksheet for the role that your partner will have in the federation:

If you are the identity provider, add a service provider partner. Use the SAML 2.0 service provider partner worksheet.

If you are the service provider, add an identity provider partner. Use the SAML 2.0 identity provider partner worksheet.

After gathering the configuration information of your partner, use the local management interface to add the federation partner properties. See Managing federation partners.

SAML 2.0 service provider partner worksheet
If you use SAML 2.0 in your role as an identity provider, you must add a service provider partner to your federation.

SAML 2.0 identity provider partner worksheet
If you use SAML 2.0 in your role as a service provider, you must add an identity provider partner to your federation.

Parent topic: Creating a SAML 2.0 partner

SAML 2.0 service provider partner worksheetSAML 2.0 service provider partner worksheetSAML 2.0 service provider partner worksheetIf you use SAML 2.0 in your role as an identity provider, you must add a service provider partner to your federation.SAML 2.0service provider partner worksheetservice provider partnerSAML 2.0 worksheetworksheetsSAML 2.0 service provider partnerUse the following worksheet to gather the necessary information from your partner. Modify this worksheet to reflect the specific information that you need from your partner and ask your partner to complete that modified worksheet. Federation to which you are adding a service provider partner in a SAML 2.0 federationSelect FederationDescriptionYour valueFederation nameThe name of the federation to which you are adding the partner.Metadata file from your service provider partner in a SAML 2.0 federationImport metadataDescriptionYour valueMetadata fileThe name and path of the file you obtained from your partner that contains the configuration information of your partner. Single sign-on settingsSingle sign-on settingsDescriptionYour valueInclude the following attributes in the SAML assertionsSpecify the attributes to include in the assertion. The source attributes must be created first. Include the following attribute types in the SAML assertions (a "*" means include all types)Specify the types of attributes to include in the assertion. The asterisk (*), which is the default setting, indicates that all of the attribute types will be included in the assertion.Amount of time, in seconds, that an idle session for the partner remains validAmount of time, in seconds, that an idle session for the partner remains valid. The default value is 3600 seconds.Include federation ID when performing alias service operations.Indicates whether the key for indexing into the alias service combines the federation ID with the partner Provider ID when performing alias service operations. This feature is useful in scenarios where two or more federations, that use persistent name identifiers, import the same partner metadata. Server certificate validation for your service provider partner in a SAML 2.0 federationProvide the SOAP SSL connection parameters, only if SOAP endpoint ishttps.SSL server validation for SOAP endpointsDescriptionYour valueSelect Server Validation CertificateThe public key for the certificate that shows during SSL communication with your partner.You and your partner must agree which certificate to use. You must have already obtained the certificate and added it to your truststore. Certificate databaseSelect the database where the certificate is stored.Certificate labelName of the certificate to use for server validation. If not provided, all certificates in the specified certificate database will be trusted.Client authentication for your service provider partner in a SAML 2.0 federationSSL Client Authentication for SOAP endpointsDescriptionYour valueClient authentication informationNo authenticationBasic authenticationUsernamePasswordClient certificate authenticationCertificate to present to the server of the identity provider.This certificate is the certificate that you and your identity provider partner agreed to present.If your partner requires mutual authentication, you must know which type to use. Select No authentication if your partner does not require authentication.If it is basic authentication, you need a user name and password. If it is client certificate authentication, you need the certificate that you and your partner have agreed to use.If you need a certificate, be sure that you have agreed with your partner where it comes from. Obtain and import it into the appropriate keystore.One of the following options:No authenticationBasic authentication information:Username:Password:Client certificate authentication information:Certificate database Certificate labelIdentity Mapping options for your service provider partner in a SAML 2.0 federationIdentity Mapping OptionsDescriptionYour value Identity mapping optionsUse the identity mapping that is configured for this partner's federation.Use JavaScript transformation for identity mapping Use an external web service for identity mappingThe type of identity mapping to use with this partner. You can choose to use the identity mapping that is configured for this partner's federation. Or, you can choose to override the identity mapping that is configured for this partner's federation.If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.If you choose an external web service, on a subsequent panel, you are asked to provide the following information: URI format (HTTP or HTTPS)Web service URI Server Certificate database, if the URI format is HTTPS Client authentication type, if the URI format is HTTPS Message format: XMLWS-Trust .After you complete this worksheet, continue with the steps in Managing federation partnersUse the Federations management page to create, modify, delete, enable, or disable your federation partners..Obtaining federation configuration data from your partnerYou must obtain configuration information from your partner before you can add that partner to a federation.

SAML 2.0 service provider partner worksheet

If you use SAML 2.0 in your role as an identity provider, you must add a service provider partner to your federation.

Use the following worksheet to gather the necessary information from your partner. Modify this worksheet to reflect the specific information that you need from your partner and ask your partner to complete that modified worksheet.

Table 110. Federation to which you are adding a service provider partner in a SAML 2.0 federation

Select Federation | Description | Your value
Federation name | The name of the federation to which you are adding the partner. |

Table 111. Metadata file from your service provider partner in a SAML 2.0 federation

Import metadata | Description | Your value
Metadata file | The name and path of the file you obtained from your partner that contains the configuration information of your partner. |

Table 112. Single sign-on settings

Single sign-on settings
Description
Your value

Include the following attributes in the SAML assertions
Specify the attributes to include in the assertion. The source attributes must be created first.

Include the following attribute types in the SAML assertions (a "*" means include all types)
Specify the types of attributes to include in the assertion. The asterisk (*), which is the default setting, indicates that all of the attribute types will be included in the assertion.

Amount of time, in seconds, that an idle session for the partner remains valid
Amount of time, in seconds, that an idle session for the partner remains valid. The default value is 3600 seconds.

Include federation ID when performing alias service operations.
Indicates whether the key for indexing into the alias service combines the federation ID with the partner Provider ID when performing alias service operations.

This feature is useful in scenarios where two or more federations, that use persistent name identifiers, import the same partner metadata.

Table 113. Server certificate validation for your service provider partner in a SAML 2.0 federation.

Note: Provide the SOAP SSL connection parameters, only if SOAP endpoint ishttps.

SSL server validation for SOAP endpoints
Description
Your value

Select Server Validation Certificate
The public key for the certificate that shows during SSL communication with your partner.

You and your partner must agree which certificate to use. You must have already obtained the certificate and added it to your truststore.

Certificate database
Select the database where the certificate is stored.

Certificate label
Name of the certificate to use for server validation. If not provided, all certificates in the specified certificate database will be trusted.

Table 114. Client authentication for your service provider partner in a SAML 2.0 federation

SSL Client Authentication for SOAP endpoints
Description
Your value

Client authentication information

No authentication

Basic authentication

Username

Password

Client certificate authentication

Certificate to present to the server of the identity provider.

This certificate is the certificate that you and your identity provider partner agreed to present.

If your partner requires mutual authentication, you must know which type to use.

Select No authentication if your partner does not require authentication.

If it is basic authentication, you need a user name and password.

If it is client certificate authentication, you need the certificate that you and your partner have agreed to use.

Note: If you need a certificate, be sure that you have agreed with your partner where it comes from. Obtain and import it into the appropriate keystore.

One of the following options:

No authentication

Basic authentication information:

Username:

Password:

Client certificate authentication information:

Certificate database

Certificate label

Table 115. Identity Mapping options for your service provider partner in a SAML 2.0 federation

Identity Mapping Options
Description
Your value

Identity mapping options

Use the identity mapping that is configured for this partner's federation.

Use JavaScript transformation for identity mapping

Use an external web service for identity mapping

The type of identity mapping to use with this partner. You can choose to use the identity mapping that is configured for this partner's federation. Or, you can choose to override the identity mapping that is configured for this partner's federation.
If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.

If you choose an external web service, on a subsequent panel, you are asked to provide the following information:

URI format (HTTP or HTTPS)

Web service URI

Server Certificate database, if the URI format is HTTPS

Client authentication type, if the URI format is HTTPS

Message format:

XML

WS-Trust

.

After you complete this worksheet, continue with the steps in Managing federation partners.

Parent topic: Obtaining federation configuration data from your partner

SAML 2.0 identity provider partner worksheetSAML 2.0 identity provider partner worksheetSAML 2.0 identity provider partner worksheetIf you use SAML 2.0 in your role as a service provider, you must add an identity provider partner to your federation.SAML 2.0worksheetsidentity provider partneridentity provider partnerSAML 2.0 worksheetworksheetsSAML 2.0IDP partnerUse the following worksheet to gather the necessary information from your partner. Modify this worksheet to reflect the specific information that you need from your partner and ask your partner to complete that modified worksheet.Federation to which you are adding an identity provider partner in a SAML 2.0 federationSelect FederationDescriptionYour valueFederation nameThe name of the federation to which you are adding the partner.Metadata file from your identity provider partner in a SAML 2.0 federationImport metadataDescriptionYour valueMetadata fileThe name and path of the file you obtained from your partner that has their configuration information. Single sign-on settingsSingle sign-on settingsDescriptionYour valueInclude the following attributes in the SAML assertionsSpecify the attributes to include in the STSUniversalUser. The source attributes must be created first. Force authentication to achieve account linkageSpecify if a user is forced to authenticate at the service provider to perform account linkage. This event occurs if a SAML response is received with an unknown alias in the service provider.Include federation ID when performing alias service operationsIndicates whether the key for indexing into the alias service combines the federation ID with the partner Provider ID when performing alias service operations.This feature is useful in scenarios where two or more federations, that use persistent name identifiers, import the same partner metadata.Username to be used for anonymous usersUse this name identifier to access a service through an anonymous identity. The user name entered here is one that the service provider recognizes as a one-time name identifier for a legitimate user in the local user registry.This feature gives users access to a resource on the service provider without establishing a federated identity. This feature is useful in scenarios where the service provider does not need to know the identity of the user account but must only know that the identity provider has authenticated (and can vouch for) the user.Map unknown name identifiers to the anonymous username Specifies that the service provider can map an unknown persistent name identifier alias to the anonymous user account.Create multiple attribute statements in the Universal UserSelect this check box to keep multiple attribute statements in the groups they were received in. This option might be necessary if your custom identity mapping rules are written to operate on one or more specific groups of attribute statements. If this check box is not selected, multiple attribute statements are arranged into a single group (AttributeList) in the STSUniversalUser document. Server certificate validationProvide the SOAP SSL connection parameters, only if SOAP endpoint ishttps.SSL server validation for SOAP endpointsDescriptionYour valueSelect Server Validation CertificateThe public key for the certificate that shows during SSL communication with your partner.You and your partner must agree which certificate to use. You must have already obtained the certificate and added it to your truststore. Certificate databaseSelect the database where the certificate is stored.Certificate labelName of the certificate to use for server validation. If not provided, all certificates in the specified certificate database will be trusted. Client authenticationSSL Client Authentication for SOAP endpointsDescriptionYour valueClient authentication information No authenticationBasic authenticationUsernamePasswordClient certificate authenticationCertificate to present to the server of the identity provider.This certificate is the certificate that you and your identity provider partner agreed to present.If your partner requires mutual authentication, you must know which type to use. Select No authentication if your partner does not require authentication. If it is basic authentication, you need a user name and password. If it is client certificate authentication, you need the certificate that you and your partner have agreed to use. If you need a certificate, be sure that you have agreed with your partner where it comes from. Obtain and import it into the appropriate keystore.One of the following options:No authenticationBasic authentication information:Username:Password:Client certificate authentication information:Certificate database Certificate label Identity Mapping Identity Mapping OptionsDescriptionYour value Identity mapping optionsUse the identity mapping that is configured for this partner's federation.Use JavaScript transformation for identity mapping Use an external web service for identity mappingThe type of identity mapping to use with this partner. You can choose to use the identity mapping that is configured for this partner's federation. Or, you can choose to override the identity mapping that is configured for this partner's federation.If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.If you choose an external web service, on a subsequent panel, you are asked to provide the following information: URI format (HTTP or HTTPS)Web service URI Server Certificate database, if the URI format is HTTPS Client authentication type, if the URI format is HTTPS Message format: XMLWS-Trust After you complete this worksheet, continue with the steps in Managing federation partnersUse the Federations management page to create, modify, delete, enable, or disable your federation partners..Obtaining federation configuration data from your partnerYou must obtain configuration information from your partner before you can add that partner to a federation.

SAML 2.0 identity provider partner worksheet

If you use SAML 2.0 in your role as a service provider, you must add an identity provider partner to your federation.

Use the following worksheet to gather the necessary information from your partner. Modify this worksheet to reflect the specific information that you need from your partner and ask your partner to complete that modified worksheet.

Table 116. Federation to which you are adding an identity provider partner in a SAML 2.0 federation

Select Federation | Description | Your value
Federation name | The name of the federation to which you are adding the partner. |

Table 117. Metadata file from your identity provider partner in a SAML 2.0 federation

Import metadata | Description | Your value
Metadata file | The name and path of the file you obtained from your partner that has their configuration information. |

Table 118. Single sign-on settings

Single sign-on settings
Description
Your value

Include the following attributes in the SAML assertions
Specify the attributes to include in the STSUniversalUser. The source attributes must be created first.

Force authentication to achieve account linkage
Specify if a user is forced to authenticate at the service provider to perform account linkage. This event occurs if a SAML response is received with an unknown alias in the service provider.

Include federation ID when performing alias service operations
Indicates whether the key for indexing into the alias service combines the federation ID with the partner Provider ID when performing alias service operations.

This feature is useful in scenarios where two or more federations, that use persistent name identifiers, import the same partner metadata.

Username to be used for anonymous users
Use this name identifier to access a service through an anonymous identity. The user name entered here is one that the service provider recognizes as a one-time name identifier for a legitimate user in the local user registry.

This feature gives users access to a resource on the service provider without establishing a federated identity. This feature is useful in scenarios where the service provider does not need to know the identity of the user account but must only know that the identity provider has authenticated (and can vouch for) the user.

Map unknown name identifiers to the anonymous username
Specifies that the service provider can map an unknown persistent name identifier alias to the anonymous user account.

Create multiple attribute statements in the Universal User
Select this check box to keep multiple attribute statements in the groups they were received in. This option might be necessary if your custom identity mapping rules are written to operate on one or more specific groups of attribute statements. If this check box is not selected, multiple attribute statements are arranged into a single group (AttributeList) in the STSUniversalUser document.

Table 119. Server certificate validation.

Note: Provide the SOAP SSL connection parameters, only if SOAP endpoint ishttps.

SSL server validation for SOAP endpoints
Description
Your value

Select Server Validation Certificate
The public key for the certificate that shows during SSL communication with your partner.

You and your partner must agree which certificate to use. You must have already obtained the certificate and added it to your truststore.

Certificate database
Select the database where the certificate is stored.

Certificate label
Name of the certificate to use for server validation. If not provided, all certificates in the specified certificate database will be trusted.

Table 120. Client authentication

SSL Client Authentication for SOAP endpoints
Description
Your value

Client authentication information

No authentication

Basic authentication

Username

Password

Client certificate authentication

Certificate to present to the server of the identity provider.

This certificate is the certificate that you and your identity provider partner agreed to present.

If your partner requires mutual authentication, you must know which type to use.

Select No authentication if your partner does not require authentication.

If it is basic authentication, you need a user name and password.

If it is client certificate authentication, you need the certificate that you and your partner have agreed to use.

Note: If you need a certificate, be sure that you have agreed with your partner where it comes from. Obtain and import it into the appropriate keystore.

One of the following options:

No authentication

Basic authentication information:

Username:

Password:

Client certificate authentication information:

Certificate database

Certificate label

Table 121. Identity Mapping

Identity Mapping Options
Description
Your value

Identity mapping options

Use the identity mapping that is configured for this partner's federation.

Use JavaScript transformation for identity mapping

Use an external web service for identity mapping

The type of identity mapping to use with this partner. You can choose to use the identity mapping that is configured for this partner's federation. Or, you can choose to override the identity mapping that is configured for this partner's federation.
If you choose JavaScript for mapping, on a subsequent panel, you are asked to select the JavaScript file to use.

If you choose an external web service, on a subsequent panel, you are asked to provide the following information:

URI format (HTTP or HTTPS)

Web service URI

Server Certificate database, if the URI format is HTTPS

Client authentication type, if the URI format is HTTPS

Message format:

XML

WS-Trust

After you complete this worksheet, continue with the steps in Managing federation partners.

Parent topic: Obtaining federation configuration data from your partner

Configuring STS modulesConfiguring STS modulesConfiguring STS modulesConfigure Security Token Service (STS) modules to validate and exchange security token types.STS modulesconfigureThe STS is a component of the federation runtime that accepts WS-Trust requests for the validation and exchange of one security token type for another. You can configure the STS artifacts, which consist of modules, templates, and chains. These configuration elements allow an incoming WS-Trust message to be mapped to a particular template and its configuration. These steps apply to the configuration for all of the Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types..Configure the token module prerequisites. The Attribute Mapping module requires that you set up attribute sources. See Managing attribute sourcesUse the Attribute Source management page to add, edit, or delete your identity attribute sources..The Username Token module requires that you set up server connections. See Managing server connectionsTo access data from outside of your appliance, you must define a server connection.The LTPA module requires that you import the LTPA key file. See Managing LTPA keysYou can create, import, export, and delete LTPA key files that are used by the LTPA token conversion module..The Default Mapping module requires that you import the JavaScript rule file. See Managing JavaScript mapping rulesCreate, edit, or delete JavaScript mapping rules.. View the module instances that are available. See Managing modulesA module is a module class and set of initial parameters.. Create a new template or use an existing one. See Managing templatesA template is an ordered list of modules and their modes.. Create a new module chain. See Managing module chainsA module chain defines a WS-Trust endpoint. It contains a reference to a template and the properties for all modules within that template.. Configure the module properties within the chain. Use the Properties tab inside of the module chain for the module.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.STSRequest and STSResponse access using a JavaScript mapping ruleBy using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects.

Configuring STS modules

Configure Security Token Service (STS) modules to validate and exchange security token types.

About this task

The STS is a component of the federation runtime that accepts WS-Trust requests for the validation and exchange of one security token type for another. You can configure the STS artifacts, which consist of modules, templates, and chains. These configuration elements allow an incoming WS-Trust message to be mapped to a particular template and its configuration.

These steps apply to the configuration for all of the Supported module types.

Procedure

Configure the token module prerequisites.

The Attribute Mapping module requires that you set up attribute sources. See Managing attribute sources.

The Username Token module requires that you set up server connections. See Managing server connections

The LTPA module requires that you import the LTPA key file. See Managing LTPA keys.

The Default Mapping module requires that you import the JavaScript rule file. See Managing JavaScript mapping rules.

View the module instances that are available. See Managing modules.

Create a new template or use an existing one. See Managing templates.

Create a new module chain. See Managing module chains.

Configure the module properties within the chain. Use the Properties tab inside of the module chain for the module.

Supported module types
STS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

Token module properties
Configure token modules so that it contains the appropriate values for your environment.

STSRequest and STSResponse access using a JavaScript mapping rule
By using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects.

Parent topic: SAML 2.0 federations

Supported module typesSupported module typesSupported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.module typesoverviewSTS modulesoverviewConfiguring STS modulesConfigure Security Token Service (STS) modules to validate and exchange security token types.Attribute Mapping module The Attribute Mapping STS module injects attribute values from different sources into an STSUU. This method to add attributes into the STSUU is convenient if you do not know how to write a mapping rule.Default Mapping moduleThe Default Mapping module facilitates mapping by using an identity mapping rule. HTTP Callout moduleThe HTTP callout module invokes a web service and enriches the STSUU with the returned contents.IVCred moduleThe Access Manager credential module creates and consumes Access Manager-specific credentials. These credentials are called IVCreds.LTPA moduleThe LTPA module facilitates the validating and issuing of LTPA version 1 and version 2 tokens. SAML 2.0 moduleThe SAML 2.0 module validates and issues SAML 2.0 tokens. This module is used for single sign-on in SAML 2.0 federations.STS Universal User moduleThe Security Token Service Universal User (STSUU) module acts as a pass-through module to either pass in or out an XML-based STSUniversalUser token.Username token module The Username token STS module validates and issues UsernameToken elements.JSON Web Token (JWT)A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC.

Supported module types

STS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

Attribute Mapping module
The Attribute Mapping STS module injects attribute values from different sources into an STSUU. This method to add attributes into the STSUU is convenient if you do not know how to write a mapping rule.

Default Mapping module
The Default Mapping module facilitates mapping by using an identity mapping rule.

HTTP Callout module
The HTTP callout module invokes a web service and enriches the STSUU with the returned contents.

IVCred module
The Access Manager credential module creates and consumes Access Manager-specific credentials. These credentials are called IVCreds.

LTPA module
The LTPA module facilitates the validating and issuing of LTPA version 1 and version 2 tokens.

SAML 2.0 module
The SAML 2.0 module validates and issues SAML 2.0 tokens. This module is used for single sign-on in SAML 2.0 federations.

STS Universal User module
The Security Token Service Universal User (STSUU) module acts as a pass-through module to either pass in or out an XML-based STSUniversalUser token.

Username token module
The Username token STS module validates and issues UsernameToken elements.

JSON Web Token (JWT)
A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC.

Parent topic: Configuring STS modules

Attribute Mapping moduleAttribute Mapping moduleAttribute Mapping module The Attribute Mapping STS module injects attribute values from different sources into an STSUU. This method to add attributes into the STSUU is convenient if you do not know how to write a mapping rule.Attribute Mapping moduleusingmodule typesAttribute MappingSTS module typesAttribute Mapping The Attribute Mapping module is called AttributeMappingModule. Before using the attribute mapping module, you must configure the attribute sources so that they are available for selection. See Managing attribute sourcesUse the Attribute Source management page to add, edit, or delete your identity attribute sources..ScenariosSingle sign-on federationsCustom trust chainsSupported modesMapConfiguration propertiesAttribute NameThe attribute name that is populated into the STSUniversalUser.Attribute SourceThe name of a configured attribute source object. See Managing attribute sourcesUse the Attribute Source management page to add, edit, or delete your identity attribute sources. for information about configuring attribute sources.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

Attribute Mapping module

The Attribute Mapping STS module injects attribute values from different sources into an STSUU. This method to add attributes into the STSUU is convenient if you do not know how to write a mapping rule.

The Attribute Mapping module is called AttributeMappingModule.

Before using the attribute mapping module, you must configure the attribute sources so that they are available for selection. See Managing attribute sources.

Scenarios

Single sign-on federations

Custom trust chains

Supported modes

Map

Configuration properties

Attribute Name

The attribute name that is populated into the STSUniversalUser.

Attribute Source

The name of a configured attribute source object. See Managing attribute sources for information about configuring attribute sources.

Parent topic: Supported module types

Default Mapping moduleDefault Mapping moduleDefault Mapping moduleThe Default Mapping module facilitates mapping by using an identity mapping rule. Default Mapping moduleusingmodule typesDefault MappingSTS module typesDefault MappingThe Default Mapping module is called XSLTransformationModule. The default mapping configuration consists of a JavaScript file that specifies an identity mapping rule. See Managing JavaScript mapping rulesCreate, edit, or delete JavaScript mapping rules..The module calls a JavaScript engine to read and run the identity mapping rules to generate a Secure Token Service Universal User (STSUU) XML document. The generated STSUU XML document contains the user identity information.ScenariosSingle sign-on federationsCustom trust chainsSupported modesMapConfiguration propertiesJavaScript file containing the identity mapping ruleThe ID of the JavaScript file that contains the identity mapping rule. For example, enter 8.You must complete the mapping rule file and upload it before you can configure it into the chain.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

Default Mapping module

The Default Mapping module facilitates mapping by using an identity mapping rule.

The Default Mapping module is called XSLTransformationModule. The default mapping configuration consists of a JavaScript file that specifies an identity mapping rule. See Managing JavaScript mapping rules.

The module calls a JavaScript engine to read and run the identity mapping rules to generate a Secure Token Service Universal User (STSUU) XML document. The generated STSUU XML document contains the user identity information.

Scenarios

Single sign-on federations

Custom trust chains

Supported modes

Map

Configuration properties

JavaScript file containing the identity mapping rule

The ID of the JavaScript file that contains the identity mapping rule.

For example, enter 8.

You must complete the mapping rule file and upload it before you can configure it into the chain.

Parent topic: Supported module types

HTTP Callout moduleHTTP Callout moduleHTTP Callout moduleThe HTTP callout module invokes a web service and enriches the STSUU with the returned contents.HTTP Callout moduleusingmodule typesHTTP CalloutSTS module typesHTTP CalloutScenariosSingle sign-on federationsCustom trust chainsSupported modesMapConfiguration propertiesIdentify the URI formatThe URI scheme. HTTPUse http for resources that are not protected by SSL.HTTPSUse https for resources that are protected by SSL. Provide the web service URIThe endpoint address of the web service.Server Certificate DatabaseThe trust store containing the certificate of the HTTPS URL to call out to. This option is only required if the URI format is HTTPS.Client authentication typeSpecify the type of authentication to use:No authenticationNo credentials are required.Basic authenticationSupply the basic authentication credentials:UsernameSpecify the user name.PasswordSpecify the password.Client certificate authenticationAuthenticate using a client certificateSelect the message format to useXMLUse XML format for the message.WS-TrustUse WS-Trust format for the message.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

HTTP Callout module

The HTTP callout module invokes a web service and enriches the STSUU with the returned contents.

Scenarios

Single sign-on federations

Custom trust chains

Supported modes

Map

Configuration properties

Identify the URI format

The URI scheme.

HTTP

Use http for resources that are not protected by SSL.

HTTPS

Use https for resources that are protected by SSL.

Provide the web service URI

The endpoint address of the web service.

Server Certificate Database

The trust store containing the certificate of the HTTPS URL to call out to. This option is only required if the URI format is HTTPS.

Client authentication type

Specify the type of authentication to use:

No authentication

No credentials are required.

Basic authentication

Supply the basic authentication credentials:

Username

Specify the user name.

Password

Specify the password.

Client certificate authentication

Authenticate using a client certificate

Select the message format to use

XML

Use XML format for the message.

WS-Trust

Use WS-Trust format for the message.

Parent topic: Supported module types

IVCred moduleIVCred moduleIVCred moduleThe Access Manager credential module creates and consumes Access Manager-specific credentials. These credentials are called IVCreds.Access Manager credential moduleusingmodule typesAccess Manager credentialsSTS module typesIVCredThe IVCred token module is called IVCredModule.The trust service can create and use local tokens in an environment that is protected by Access Manager. The support for Access Manager credentials means that the trust service can also use the credentials for authorization decisions.Supported modesValidateIssueConfiguration propertiesValidate modeEnable signature validationEnables or disables validation of signatures in the token module. Select the check box to enable signature validation.Select validation keySpecifies the validation key that the partner must use.Certificate DatabaseSelect the certificate database to use for validation.Certificate LabelSelect the certificate label for validation.Issue modeList the attribute types to includeSpecifies the attribute type of the attributes to be inserted during token creation. The attributes consist of information about the identity (user). By default, all types are supported, as indicated by the asterisk (*) wildcard character.Enable signaturesSpecifies that signatures must be added to tokens.Select the signing keySpecifies the key to use to sign tokens.Certificate DatabaseSelect the certificate database to use for validation.Certificate LabelSelect the certificate label for validation.Select the KeyInfo elements to includeSpecifies the elements of the signing certificate in the extended attributes of the credential. These attributes are only included if signatures are enabled. The default is for them to be disabled.Public KeySelect to include the public key. If selected, the public key of the signing certificate is included in the Base64 encoded form. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_PUBKEY.Clear the check box to exclude the public key. X509 Subject NameSelect to include this attribute. If selected, the distinguished name of the subject for the signing certificate is included. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_SUBJECT. Clear the check box to exclude the X509 Subject Name. X509 Subject Issuer Details Select to include this attribute. If selected, the issuer details of the signing certificate are included. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_ISSUER. Clear the check box to exclude the X509 Subject Issuer Details.X509 Subject Key Identifier Select to include this attribute. If selected, the subject key identifier of the signing certificate is included. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_SKI. Clear the check box to exclude the X509 Subject Key Identifier.X509 Certificate DataSelect to include this attribute. If selected, the certificate data of the signing certificate is included in the Base64 encoded form. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE. Clear the check box to exclude the X509 Certificate Data.If none of the KeyInfo elements are selected, X509Certificate data is still included in the signature by default.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

IVCred module

The Access Manager credential module creates and consumes Access Manager-specific credentials. These credentials are called IVCreds.

The IVCred token module is called IVCredModule.The trust service can create and use local tokens in an environment that is protected by Access Manager. The support for Access Manager credentials means that the trust service can also use the credentials for authorization decisions.

Supported modes

Validate

Issue

Configuration properties

Validate mode

Enable signature validation

Enables or disables validation of signatures in the token module. Select the check box to enable signature validation.

Select validation key

Specifies the validation key that the partner must use.

Certificate Database

Select the certificate database to use for validation.

Certificate Label

Select the certificate label for validation.

Issue mode

List the attribute types to include

Specifies the attribute type of the attributes to be inserted during token creation. The attributes consist of information about the identity (user).

By default, all types are supported, as indicated by the asterisk (*) wildcard character.

Enable signatures

Specifies that signatures must be added to tokens.

Select the signing key

Specifies the key to use to sign tokens.

Certificate Database

Select the certificate database to use for validation.

Certificate Label

Select the certificate label for validation.

Select the KeyInfo elements to include

Specifies the elements of the signing certificate in the extended attributes of the credential. These attributes are only included if signatures are enabled. The default is for them to be disabled.

Public Key

Select to include the public key. If selected, the public key of the signing certificate is included in the Base64 encoded form. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_PUBKEY.

Clear the check box to exclude the public key.

X509 Subject Name

Select to include this attribute. If selected, the distinguished name of the subject for the signing certificate is included. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_SUBJECT.

Clear the check box to exclude the X509 Subject Name.

X509 Subject Issuer Details

Select to include this attribute. If selected, the issuer details of the signing certificate are included. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_ISSUER.

Clear the check box to exclude the X509 Subject Issuer Details.

X509 Subject Key Identifier

Select to include this attribute. If selected, the subject key identifier of the signing certificate is included. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE_SKI.

Clear the check box to exclude the X509 Subject Key Identifier.

X509 Certificate Data

Select to include this attribute. If selected, the certificate data of the signing certificate is included in the Base64 encoded form. The extended attribute is labeled ITFIM_IVCRED_SIGNER_CERTIFICATE.

Clear the check box to exclude the X509 Certificate Data.

Note: If none of the KeyInfo elements are selected, X509Certificate data is still included in the signature by default.

Parent topic: Supported module types

LTPA moduleLTPA moduleLTPA moduleThe LTPA module facilitates the validating and issuing of LTPA version 1 and version 2 tokens. LTPA moduleusingmodule typesLTPASTS module typesLTPAThe LTPA module is called STSLTPATokenModule. An LTPA token is an encrypted string that contains user information and other metadata. Version 1 tokens contain fairly limited information, such as username and token expiration time. Version 2 tokens are extensible in that they can contain user-defined attributes, where each attribute can contain a list of values.These tokens are represented as BinarySecurityToken elements.This module does not support the initial generation of LTPA keys. You must provide a set of LTPA keys that were generated by another source such as a WebSphere application server. Supported modesValidateIssueConfiguration propertiesValidate modeLTPA fileSelect the LTPA file to use. You must upload the LTPA file into /wga/ltpa_key first for it to display in the list.Password for key protection(Required) The password that was used to protect the keys that are created by the partner. Use the FIPS standardSelect to enable the Federal Information Processing Standards (FIPS). If FIPS was enabled when you created your partner, select this check box. The default is unchecked.Issue modeLTPA fileSelect the LTPA file to use. You must upload the LTPA file into /wga/ltpa_key first for it to display in the list.Password for key protection (Required) The password that was used to protect the keys that are created by the partner. It must be the same password that was used when the keys were created by the partner.Use the FIPS standardSelect to enable the Federal Information Processing Standards (FIPS). If FIPS was enabled when you created your partner, select this check box. The default is unchecked.Number of minutes before the created token expires(Required) Indicates how long, from the time of token creation, the token remains valid. Specify the value in minutes. You can override this value by using the expiration Principle value in the Universal User. The default value is 120 minutes.Realm used to create the user IDThe realm name to append to the user ID during token creation. You can override this value by using the realm Principle value in the Universal User. If you do not specify a name here, then the realm from the imported LTPA file is assumed.Version of LTPA token to issueThe version number of the LTPA token you are issuing. Select 1 or 2 from the list, denoting LTPA Version 1 or Version 2.Attributes to add to a version 2 token Specify the type of attributes to include in the assertion. Use this field only for LTPA Version 2 tokens. An asterisk (*) indicates that all of the attribute types that are specified in the identity mapping file are included in the assertion. To specify one specific type individually, type the attribute type in the text box. For example, if you want to include only attributes of type urn:oasis:names:tc:SAML:2.0:assertion in the assertion, type that string in the text box.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

LTPA module

The LTPA module facilitates the validating and issuing of LTPA version 1 and version 2 tokens.

The LTPA module is called STSLTPATokenModule.

An LTPA token is an encrypted string that contains user information and other metadata. Version 1 tokens contain fairly limited information, such as username and token expiration time. Version 2 tokens are extensible in that they can contain user-defined attributes, where each attribute can contain a list of values.

These tokens are represented as BinarySecurityToken elements.

This module does not support the initial generation of LTPA keys. You must provide a set of LTPA keys that were generated by another source such as a WebSphere® application server.

Supported modes

Validate

Issue

Configuration properties

Validate mode

LTPA file

Select the LTPA file to use.

You must upload the LTPA file into /wga/ltpa_key first for it to display in the list.

Password for key protection

(Required) The password that was used to protect the keys that are created by the partner.

Use the FIPS standard

Select to enable the Federal Information Processing Standards (FIPS). If FIPS was enabled when you created your partner, select this check box. The default is unchecked.

Issue mode

LTPA file

Select the LTPA file to use.

You must upload the LTPA file into /wga/ltpa_key first for it to display in the list.

Password for key protection

(Required) The password that was used to protect the keys that are created by the partner. It must be the same password that was used when the keys were created by the partner.

Use the FIPS standard

Select to enable the Federal Information Processing Standards (FIPS). If FIPS was enabled when you created your partner, select this check box. The default is unchecked.

Number of minutes before the created token expires

(Required) Indicates how long, from the time of token creation, the token remains valid. Specify the value in minutes. You can override this value by using the expiration Principle value in the Universal User. The default value is 120 minutes.

Realm used to create the user ID

The realm name to append to the user ID during token creation. You can override this value by using the realm Principle value in the Universal User. If you do not specify a name here, then the realm from the imported LTPA file is assumed.

Version of LTPA token to issue

The version number of the LTPA token you are issuing. Select 1 or 2 from the list, denoting LTPA Version 1 or Version 2.

Attributes to add to a version 2 token

Specify the type of attributes to include in the assertion. Use this field only for LTPA Version 2 tokens. An asterisk (*) indicates that all of the attribute types that are specified in the identity mapping file are included in the assertion.

To specify one specific type individually, type the attribute type in the text box. For example, if you want to include only attributes of type urn:oasis:names:tc:SAML:2.0:assertion in the assertion, type that string in the text box.

Parent topic: Supported module types

SAML 2.0 moduleSAML 2.0 moduleSAML 2.0 moduleThe SAML 2.0 module validates and issues SAML 2.0 tokens. This module is used for single sign-on in SAML 2.0 federations.SAML 2.0 moduleusingmodule typesSAML 2.0STS module typesSAML 2.0The SAML 2.0 module is called Saml20STSTokenModule. Security Assertion Markup Language 2.0 (SAML 2.0) is a version of the SAML standard for exchanging authentication and authorization data between security domains. SAML 2.0 enables web-based authentication and authorization scenarios including cross-domain single sign-on (SSO), which helps reduce the administrative overhead of distributing multiple authentication tokens to the user.ScenariosSingle sign-on federationsCustom trust chainsSupported modesValidateIssueExchangeConfiguration propertiesValidate modeEnable one-time assertion use enforcementSpecifies whether to use the assertion or token only once.Enable signature validationEnables or disables validation of signatures in the token module. Even if you do not select the check box, you must provide the key for decryption.Select a validation keySpecifies the validation key that the partner must use.Use the KeyInfo of the XML signature to find the X509 certificate for signature validationDetermines the appropriate certificate for signature validation. When you select this option, you must provide the subject distinguished name that matches the certificate.RegExpSpecifies a regular expression to validate the subject distinguished name returned in theKeyInfo.Use the keystore alias to find the public key for signature validationSpecifies a public key for signature validation, which is the default. Select the certificate database and label.Certificate DatabaseSelect the certificate database to use for validation.Certificate LabelSelect the certificate label for validation.Select a decryption keySelect the key to use to decrypt encrypted messages.Certificate DatabaseSelect the certificate database to use for validation.Certificate LabelSelect the certificate label for validation.Create multiple attribute statements in the Universal UserSpecifies whether to keep multiple attribute statements in the groups in which they were received. This option might be necessary if your custom identity mapping rules are written to operate on one or more specific groups of attribute statements.If you do not select this check box, multiple attribute statements are arranged into a single group (AttributeList) in the STSUniversalUser document. The default setting of the check box is not selected. This setting is appropriate for most configurations.Map unknown name identifiers to the anonymous usernameSpecifies that the service provider can map an unknown persistent name identifier alias to the anonymous user account. By default, this option is disabled.Default NameID format for assertion validationSpecifies a parameter for use during validation of a SAML assertion. The parameter is used to determine processing rules for the NameID element when one of the following conditions exists:If there is not an explicit Format attribute that is included in the assertionIf the Format attribute is urn:oasis:names:tc:SAML:2.0:nameid-format:unspecifiedTypically this parameter is needed only for STS chains that process SAML assertions that do not set the Format attribute. A normal example value is urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress.Issue and Exchange modeName of the organization issuing the assertionsShows a string that specifies the name of the organization (for example, a company) that issues the SAML assertions.Amount of time before the issue date that an assertion is considered valid (seconds)Default: 60 secondsThere is no minimum or maximum value enforced.This field must contain a value.Amount of time that the assertion is valid after being issued (seconds)Default: 60 secondsThere is no minimum or maximum value enforced.This field must contain a value. List the attribute types to includeSpecifies the types of attributes to be inserted during token creation. The attributes consist of information about the identity (user). Use && to separate attribute types. By default, all types are supported, as indicated by the asterisk (*) wildcard character.For example, to add user-defined attribute types type1 and type2, enter:type1&&type2Sign SAML assertionsSelect if SAML assertions must be signed. Even if you do not select the check box, you must provide the key for encryption assertions.Select the key for signing assertionsSpecifies the key to use when signing SAML assertions.Certificate DatabaseSelect the certificate database to use for validation.Certificate LabelSelect the certificate label for validation.Select the KeyInfo elements to include Determines what KeyInfo elements to include in the digital signature when signing a SAML message or assertion. Select one or more of the following elements. X509 Subject Key IdentifierSelect to include the X.509 subject key identifier with your signature. If not selected, the subject key identifier is excluded. To change the default for this element, change it in the custom properties. Public KeySelect to include the public key with your signature. If not selected, the public key is excluded. To change the default for this element, change it in the custom properties.X509 Subject Issuer DetailsSelect to include the issuer name and the certificate serial number with your signature. If not selected, the subject issuer details are excluded. To change the default for this element, change it in the custom properties. X509 Subject NameSelect to include the X.509 subject name with your signature. If not selected, the X.509 data is excluded. To change the default for this element, change it in the custom properties.X509 Certificate DataSelect to include the BASE64 encoded certificate data with your signature. If not selected, the X.509 data is excluded. To change the default for this element, change it in the custom properties.If you do not select any of the KeyInfo elements, X.509 certificate data is still included in the signature by default.Signature algorithm for signing SAML assertionsSpecifies the signature algorithm to use to sign the SAML assertion.RSA-SHA1http://www.w3.org/2000/09/xmldsig#rsa-sha1DSA-SHA1http://www.w3.org/2000/09/xmldsig#dsa-sha1RSA-SHA256http://www.w3.org/2001/04/xmldsig-more#rsa-sha256The chosen signature algorithm must match the signing key type that was set in the federation level to prevent a signature failure. For example, select DSA-SHA1 for DSA keys.Select the key for encrypting assertion elements for this partnerSpecifies the key to use to encrypt assertions.Certificate DatabaseSelect the certificate database to use for validation.Certificate LabelSelect the certificate label for validation.Encrypt assertionsSpecifies whether assertions are to be encrypted. If selected, specify an encryption key.Encrypt assertion attribute elementsSpecifies whether Attribute elements within the assertions are to be encrypted. If selected, specify an encryption key.Encrypt NameID elements in assertionsSpecifies whether NameID elements in the assertions are to be encrypted. If selected, specify an encryption key.Block encryption algorithmSpecifies the encryption algorithm to use to encrypt data for this partner.Triple DES Triple Digital Encryption Standard AES-128Advanced Encryption Standard 128-bitAES-192Advanced Encryption Standard 192-bitAES-256Advanced Encryption Standard 256-bitSubject confirmation methodSpecifies the subject confirmation method for the assertion. You can select one or more subject confirmation methods at the same time, or choose not to select any confirmation methods. If you select the holder-of-key type, the default includes the X.509 Certificate Data in the KeyInfo for the SubjectConfirmationMethod. STSUniversalUser can provide the data for the subject confirmation method KeyInfo. The data can also be extracted from the signed request data.Valid values can be:urn:oasis:names:tc:SAML:2.0:bearer urn:oasis:names:tc:SAML:2.0:holder-of-keyurn:oasis:names:tc:SAML:2.0:sender-vouches You can use the identity mapping rules to add subject confirmation information to the STSUniversalUser. See the example of an XSLT mapping rule with multiple subject confirmation methods:<stsuuser:Attribute name="SamlSubjectConfirmationMethod" type="urn:oasis:names:tc:SAML:2.0:assertion"> <stsuuser:Value>urn:oasis:names:tc:SAML:2.0:cm:bearer </stsuuser:Value> <stsuuser:Value>urn:oasis:names:tc:SAML:2.0:cm:holder-of-key </stsuuser:Value> </stsuuser:Attribute>Another way to add subject confirmation information is by using configuration properties. See the topic on SAML 2.0 module propertiesYou can define SAML 2.0 token module self or partner properties. .The values set in the identity mapping rule take precedence over the settings in the configuration. If there are different values for the mapping rule and response file, the assertion contains the values that were set in the mapping rule. For the SubjectConfirmationMethod to be issued correctly, the client must sign the RequestSecurityToken request and include a KeyInfo used for the SCM when sending the RequestSecurityToken. To use the holder-of-key capability, the XSLT mapping rules must be updated. For example: <stsuuser:AttributeList>  <stsuuser:Attribute name="SamlSubjectConfirmationMethod" type="urn:oasis:names:tc:SAML:2.0:assertion">   <stsuuser:Value>urn:oasis:names:tc:SAML:2.0:cm:holder-of-key </stsuuser:Value>  </stsuuser:Attribute> </stsuuser:AttributeList>Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

SAML 2.0 module

The SAML 2.0 module validates and issues SAML 2.0 tokens. This module is used for single sign-on in SAML 2.0 federations.

The SAML 2.0 module is called Saml20STSTokenModule.

Security Assertion Markup Language 2.0 (SAML 2.0) is a version of the SAML standard for exchanging authentication and authorization data between security domains. SAML 2.0 enables web-based authentication and authorization scenarios including cross-domain single sign-on (SSO), which helps reduce the administrative overhead of distributing multiple authentication tokens to the user.

Scenarios

Single sign-on federations

Custom trust chains

Supported modes

Validate

Issue

Exchange

Configuration properties

Validate mode

Enable one-time assertion use enforcement

Specifies whether to use the assertion or token only once.

Enable signature validation

Enables or disables validation of signatures in the token module. Even if you do not select the check box, you must provide the key for decryption.

Select a validation key

Specifies the validation key that the partner must use.

Use the KeyInfo of the XML signature to find the X509 certificate for signature validation

Determines the appropriate certificate for signature validation. When you select this option, you must provide the subject distinguished name that matches the certificate.

RegExp

Specifies a regular expression to validate the subject distinguished name returned in theKeyInfo.

Use the keystore alias to find the public key for signature validation

Specifies a public key for signature validation, which is the default. Select the certificate database and label.

Certificate Database

Select the certificate database to use for validation.

Certificate Label

Select the certificate label for validation.

Select a decryption key

Select the key to use to decrypt encrypted messages.

Certificate Database

Select the certificate database to use for validation.

Certificate Label

Select the certificate label for validation.

Create multiple attribute statements in the Universal User

Specifies whether to keep multiple attribute statements in the groups in which they were received. This option might be necessary if your custom identity mapping rules are written to operate on one or more specific groups of attribute statements.

If you do not select this check box, multiple attribute statements are arranged into a single group (AttributeList) in the STSUniversalUser document. The default setting of the check box is not selected. This setting is appropriate for most configurations.

Map unknown name identifiers to the anonymous username

Specifies that the service provider can map an unknown persistent name identifier alias to the anonymous user account. By default, this option is disabled.

Default NameID format for assertion validation

Specifies a parameter for use during validation of a SAML assertion. The parameter is used to determine processing rules for the NameID element when one of the following conditions exists:

If there is not an explicit Format attribute that is included in the assertion

If the Format attribute is urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified

Typically this parameter is needed only for STS chains that process SAML assertions that do not set the Format attribute. A normal example value is urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress.

Issue and Exchange mode

Name of the organization issuing the assertions

Shows a string that specifies the name of the organization (for example, a company) that issues the SAML assertions.

Amount of time before the issue date that an assertion is considered valid (seconds)

Default: 60 seconds

There is no minimum or maximum value enforced.

This field must contain a value.

Amount of time that the assertion is valid after being issued (seconds)

Default: 60 seconds

There is no minimum or maximum value enforced.

This field must contain a value.

List the attribute types to include

Specifies the types of attributes to be inserted during token creation. The attributes consist of information about the identity (user). Use && to separate attribute types. By default, all types are supported, as indicated by the asterisk (*) wildcard character.

For example, to add user-defined attribute types type1 and type2, enter:

type1&&type2

Sign SAML assertions

Select if SAML assertions must be signed. Even if you do not select the check box, you must provide the key for encryption assertions.

Select the key for signing assertions

Specifies the key to use when signing SAML assertions.

Certificate Database

Select the certificate database to use for validation.

Certificate Label

Select the certificate label for validation.

Select the KeyInfo elements to include

Determines what KeyInfo elements to include in the digital signature when signing a SAML message or assertion. Select one or more of the following elements.

X509 Subject Key Identifier

Select to include the X.509 subject key identifier with your signature. If not selected, the subject key identifier is excluded. To change the default for this element, change it in the custom properties.

Public Key

Select to include the public key with your signature. If not selected, the public key is excluded. To change the default for this element, change it in the custom properties.

X509 Subject Issuer Details

Select to include the issuer name and the certificate serial number with your signature. If not selected, the subject issuer details are excluded. To change the default for this element, change it in the custom properties.

X509 Subject Name

Select to include the X.509 subject name with your signature. If not selected, the X.509 data is excluded. To change the default for this element, change it in the custom properties.

X509 Certificate Data

Select to include the BASE64 encoded certificate data with your signature. If not selected, the X.509 data is excluded. To change the default for this element, change it in the custom properties.

Note: If you do not select any of the KeyInfo elements, X.509 certificate data is still included in the signature by default.

Signature algorithm for signing SAML assertions

Specifies the signature algorithm to use to sign the SAML assertion.

RSA-SHA1

http://www.w3.org/2000/09/xmldsig#rsa-sha1

DSA-SHA1

http://www.w3.org/2000/09/xmldsig#dsa-sha1

RSA-SHA256

http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

Note: The chosen signature algorithm must match the signing key type that was set in the federation level to prevent a signature failure. For example, select DSA-SHA1 for DSA keys.

Select the key for encrypting assertion elements for this partner

Specifies the key to use to encrypt assertions.

Certificate Database

Select the certificate database to use for validation.

Certificate Label

Select the certificate label for validation.

Encrypt assertions

Specifies whether assertions are to be encrypted. If selected, specify an encryption key.

Encrypt assertion attribute elements

Specifies whether Attribute elements within the assertions are to be encrypted. If selected, specify an encryption key.

Encrypt NameID elements in assertions

Specifies whether NameID elements in the assertions are to be encrypted. If selected, specify an encryption key.

Block encryption algorithm

Specifies the encryption algorithm to use to encrypt data for this partner.

Triple DES

Triple Digital Encryption Standard

AES-128

Advanced Encryption Standard 128-bit

AES-192

Advanced Encryption Standard 192-bit

AES-256

Advanced Encryption Standard 256-bit

Subject confirmation method

Specifies the subject confirmation method for the assertion. You can select one or more subject confirmation methods at the same time, or choose not to select any confirmation methods. If you select the holder-of-key type, the default includes the X.509 Certificate Data in the KeyInfo for the SubjectConfirmationMethod. STSUniversalUser can provide the data for the subject confirmation method KeyInfo. The data can also be extracted from the signed request data.

Valid values can be:

urn:oasis:names:tc:SAML:2.0:bearer

urn:oasis:names:tc:SAML:2.0:holder-of-key

urn:oasis:names:tc:SAML:2.0:sender-vouches

You can use the identity mapping rules to add subject confirmation information to the STSUniversalUser. See the example of an XSLT mapping rule with multiple subject confirmation methods:

<stsuuser:Attribute name="SamlSubjectConfirmationMethod"
 type="urn:oasis:names:tc:SAML:2.0:assertion">
  <stsuuser:Value>urn:oasis:names:tc:SAML:2.0:cm:bearer
   </stsuuser:Value>
  <stsuuser:Value>urn:oasis:names:tc:SAML:2.0:cm:holder-of-key
   </stsuuser:Value>
 </stsuuser:Attribute>

Another way to add subject confirmation information is by using configuration properties. See the topic on SAML 2.0 module properties.

Note: The values set in the identity mapping rule take precedence over the settings in the configuration. If there are different values for the mapping rule and response file, the assertion contains the values that were set in the mapping rule.

For the SubjectConfirmationMethod to be issued correctly, the client must sign the RequestSecurityToken request and include a KeyInfo used for the SCM when sending the RequestSecurityToken. To use the holder-of-key capability, the XSLT mapping rules must be updated.

For example:

<stsuuser:AttributeList>
 <stsuuser:Attribute name="SamlSubjectConfirmationMethod"
   type="urn:oasis:names:tc:SAML:2.0:assertion">
  <stsuuser:Value>urn:oasis:names:tc:SAML:2.0:cm:holder-of-key
  </stsuuser:Value>
 </stsuuser:Attribute>
</stsuuser:AttributeList>

Parent topic: Supported module types

STS Universal User moduleSTS Universal User moduleSTS Universal User moduleThe Security Token Service Universal User (STSUU) module acts as a pass-through module to either pass in or out an XML-based STSUniversalUser token.STSUU moduleusingmodule typesSTSUUSTS module typesSTSUUThe STS Universal User module is called STSUUSTSModule. This module is useful for testing other STS modules or for simple custom trust client applications. It provides a simple means to directly call the trust service to issue more complex token types without having to first pass in another token, and then perform a mapping operation. The input STSUniversalUser token can contain the username, any extended attributes, and any attributes required for issuing the SAML assertion, as generated by the caller of the trust service. No mapping step is required.ScenarioCustom trust chainsSupported modesValidateIssueExchangeConfiguration propertiesNone.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

STS Universal User module

The Security Token Service Universal User (STSUU) module acts as a pass-through module to either pass in or out an XML-based STSUniversalUser token.

The STS Universal User module is called STSUUSTSModule.

This module is useful for testing other STS modules or for simple custom trust client applications. It provides a simple means to directly call the trust service to issue more complex token types without having to first pass in another token, and then perform a mapping operation.

The input STSUniversalUser token can contain the username, any extended attributes, and any attributes required for issuing the SAML assertion, as generated by the caller of the trust service.

No mapping step is required.

Scenario

Custom trust chains

Supported modes

Validate

Issue

Exchange

Configuration properties

None.

Parent topic: Supported module types

Username token moduleUsername token moduleUsername token module The Username token STS module validates and issues UsernameToken elements.Username moduleusingmodule typesUsername tokenSTS module typesUsernameThe Username token STS module is called UsernameTokenSTSModule. The STS handles a Username token as both an incoming and outgoing token type.There are three supported username and password validation methods from which to select. ScenarioCustom trust chainsSupported modesValidateIssueConfiguration properties (Validate mode)Skip password validationDo not perform password validation for the Username token. The default value is cleared.User registry optionSelect the type of user registry to use for validation. Access Manager runtimeValidate the username and password according to the Access Manager runtime configuration. Complete the following steps before using this option:Configure the runtime component. See Configure the runtime environmentTo configure the runtime environment with the local management interface, use the Runtime Component management page.. During this process, you must specify an Access Manager user registry as your primary LDAP server.Configure a federated user registry. Client certificate authentication for federated directories is not supported for UsernameTokenSTSModule. See Managing federated directoriesKeep your federated directories up-to-date so that Security Access Manager can access the most recent user information that is stored in external user registries. You can add a new directory, remove an existing one, or modify its settings. . Enable basic users. See Configuring the runtime to authenticate basic usersBasic users are users in the registry that are not imported in to Security Access Manager. Edit the ldap.conf file so that basic users can authenticate in Security Access Manager.. LDAP bind DNThe username used to authenticate to the primary LDAP server. For example, cn=SecurityMaster,secAuthority=Default.LDAP bind PasswordThe password used to authenticate to the primary LDAP server. For example, admin.SSL EnabledSelect to enable SSL.Certificate DatabaseThe name of the certificate database to use for the SSL connection. For example, embedded_ldap_keys.kdb.Access Manager user registryValidate the username and password according to the configured Access Manager user registry. This method requires an LDAP server that you must define by using the local management interface. See Managing server connectionsTo access data from outside of your appliance, you must define a server connection..Server Connection IDThe name of the server connection that holds the required LDAP settings to access the Security Access Manager registry. This property is required if password validation is not skipped.Login Failures PersistentLogin failures are used with the three-strikes policy. If this option is set to false, each process that uses this API stores the number of login failures in memory. If multiple servers are involved, the total number of login failures to trigger a strike-out might vary. If this option is set to true, the strike count is stored in LDAP and shared across all servers. Therefore, an accurate count is kept in a multi-server environment. The default is false.Management DomainThe management domain of Security Access Manager. The default is Default.Maximum Server ConnectionsThe maximum number of connections that are made to the Security Access Manager registry.The default is 16.Generic LDAP user registryValidate the username and password according to the configured LDAP user registry. It does not have to be an Access Manager user registry.Server Connection IDThe name of the server connection that holds the required LDAP settings to access an LDAP user registry. This property is required if password validation is not skipped.Maximum Server ConnectionsThe maximum number of connections that are made to the LDAP user registry.The default is 16.User ID attributeAn LDAP attribute that stores the username. For example, uid.LDAP Base DNAn LDAP base DN to search. For example, o=ibm,c=us.User search filterAn LDAP search filter. For example, ((objectClass=person)(objectClass=ePerson)).Enable the time validity check, based on created time and the amount of time permitted after the issueSpecifies a required created time element on the Username token when checked. This property is enabled by default. The software compares the value of the created time element against the value that specifies the amount of time that the token is valid after it is issued.Amount of time the token is valid after being issuedThe amount of time a token is valid after it is issued. The default value is 300 seconds. A value of -1 means that the token does not expire.Configuration properties (Issue mode)Include nonce in tokenIncludes a nonce (random bits used for obfuscating the element) in the token. When the password option 4 is specified, this value has no effect.Include token creation time in tokenAdds a time stamp to the token, indicating the creation time of the token.Options for including password in the tokenIndicates whether to include the password in the token. When the password is included, you can specify the format.Do not include the passwordSpecifies that you do not want to include the password in the token.Include the digest of the password valueSpecifies that you want to include the password in the token as the digest of the password value.Include the password in clear textSpecifies that you want to include the password in the token as clear text.Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.

Username token module

The Username token STS module validates and issues UsernameToken elements.

The Username token STS module is called UsernameTokenSTSModule. The STS handles a Username token as both an incoming and outgoing token type.

There are three supported username and password validation methods from which to select.

Scenario

Custom trust chains

Supported modes

Validate

Issue

Configuration properties (Validate mode)

Skip password validation

Do not perform password validation for the Username token. The default value is cleared.

User registry option

Select the type of user registry to use for validation.

Access Manager runtime

Validate the username and password according to the Access Manager runtime configuration.

Note: Complete the following steps before using this option:

Configure the runtime component. See Configure the runtime environment. During this process, you must specify an Access Manager user registry as your primary LDAP server.

Configure a federated user registry.

Note: Client certificate authentication for federated directories is not supported for UsernameTokenSTSModule.

See Managing federated directories.

Enable basic users. See Configuring the runtime to authenticate basic users.

LDAP bind DN

The username used to authenticate to the primary LDAP server. For example, cn=SecurityMaster,secAuthority=Default.

LDAP bind Password

The password used to authenticate to the primary LDAP server. For example, admin.

SSL Enabled

Select to enable SSL.

Certificate Database

The name of the certificate database to use for the SSL connection. For example, embedded_ldap_keys.kdb.

Access Manager user registry

Validate the username and password according to the configured Access Manager user registry. This method requires an LDAP server that you must define by using the local management interface. See Managing server connections.

Server Connection ID

The name of the server connection that holds the required LDAP settings to access the Security Access Manager registry. This property is required if password validation is not skipped.

Login Failures Persistent

Login failures are used with the three-strikes policy.

If this option is set to false, each process that uses this API stores the number of login failures in memory. If multiple servers are involved, the total number of login failures to trigger a strike-out might vary.

If this option is set to true, the strike count is stored in LDAP and shared across all servers. Therefore, an accurate count is kept in a multi-server environment.

The default is false.

Management Domain

The management domain of Security Access Manager. The default is Default.

Maximum Server Connections

The maximum number of connections that are made to the Security Access Manager registry.

The default is 16.

Generic LDAP user registry

Validate the username and password according to the configured LDAP user registry. It does not have to be an Access Manager user registry.

Server Connection ID

The name of the server connection that holds the required LDAP settings to access an LDAP user registry. This property is required if password validation is not skipped.

Maximum Server Connections

The maximum number of connections that are made to the LDAP user registry.

The default is 16.

User ID attribute

An LDAP attribute that stores the username. For example, uid.

LDAP Base DN

An LDAP base DN to search. For example, o=ibm,c=us.

User search filter

An LDAP search filter. For example, ((objectClass=person)(objectClass=ePerson)).

Enable the time validity check, based on created time and the amount of time permitted after the issue

Specifies a required created time element on the Username token when checked. This property is enabled by default. The software compares the value of the created time element against the value that specifies the amount of time that the token is valid after it is issued.

Amount of time the token is valid after being issued

The amount of time a token is valid after it is issued. The default value is 300 seconds. A value of -1 means that the token does not expire.

Configuration properties (Issue mode)

Include nonce in token

Includes a nonce (random bits used for obfuscating the element) in the token. When the password option 4 is specified, this value has no effect.

Include token creation time in token

Adds a time stamp to the token, indicating the creation time of the token.

Options for including password in the token

Indicates whether to include the password in the token. When the password is included, you can specify the format.

Do not include the password

Specifies that you do not want to include the password in the token.

Include the digest of the password value

Specifies that you want to include the password in the token as the digest of the password value.

Include the password in clear text

Specifies that you want to include the password in the token as clear text.

Parent topic: Supported module types

JSON Web Token (JWT)A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC.The methods of encrypting and signing and the support for key exchange and algorithms are defined in RFCs 7515, 7516, 7517, and 7518. These RFCs cover signing, encryption, key sets, and algorithms. RFC 7519 covers JWT. A JWT contains three Base64 encoded strings that are separated by dots (“.”).For a signed JWT, these parts are:JWT Header - JSONJWT claims - JSONSignature - Binary dataAll of these parts are Base64 URL encoded. An example JWT is shown in the following example:eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJ5b3UiLCJpc3MiOiJtZSIsInN1YiI6InRvZ GF5IiwiZGF5IjoibW9uZGF5In0.6f14Ub6WuEuMMSa_6hkXfj5kpVAI9tkmP5vcbX1 qH3YThis JWT is signed by using the algorithm HS256 and the shared key of “secret”.You can use http://jwt.io to create and validate simple signed JWTs. Supported module typesSTS modules are assembled as part of an STS chain that issues and validates specific types of tokens. IBM Security Access Manager supports several STS module types.JWT supportIBM Security Access Manager supports JWT by using STS to expose a JWT module. Validate modeIn validate mode, the JWT Module consumes a binary security token, which has the attribute type “urn:com:ibm:JWT”. Issue modeIn issue mode, the JWT Module creates a binary security token, which has the attribute type urn:com:ibm:JWT.

JSON Web Token (JWT)

A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC.

The methods of encrypting and signing and the support for key exchange and algorithms are defined in RFCs 7515, 7516, 7517, and 7518. These RFCs cover signing, encryption, key sets, and algorithms. RFC 7519 covers JWT.

A JWT contains three Base64 encoded strings that are separated by dots (“.”).

For a signed JWT, these parts are:

JWT Header - JSON

JWT claims - JSON

Signature - Binary data

All of these parts are Base64 URL encoded. An example JWT is shown in the following example:

eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJ5b3UiLCJpc3MiOiJtZSIsInN1YiI6InRvZ
GF5IiwiZGF5IjoibW9uZGF5In0.6f14Ub6WuEuMMSa_6hkXfj5kpVAI9tkmP5vcbX1
qH3Y

This JWT is signed by using the algorithm HS256 and the shared key of “secret”.

You can use http://jwt.io to create and validate simple signed JWTs.

JWT support
IBM Security Access Manager supports JWT by using STS to expose a JWT module.

Validate mode
In validate mode, the JWT Module consumes a binary security token, which has the attribute type “urn:com:ibm:JWT”.

Issue mode
In issue mode, the JWT Module creates a binary security token, which has the attribute type urn:com:ibm:JWT.

Parent topic: Supported module types

JWT support IBM Security Access Manager supports JWT by using STS to expose a JWT module. This module can be run in the following two modes: ValidateConsume a JWT.Issue Create a JWT.Both modes support signing, encryption, and some basic validation or population of claims. Security Access Manager supports consuming a nested JWT using the header claim “cty”:”JWT”. However, this support applies only when the JWT is both signed and encrypted, per RFC 7519 section 11.2.The JWT module supports the following JSON Web Algorithms. Signing algorithmsAlgorithmUses symmetric keyUses certificatesRequired key sizeSuggested key sizeHS256YesNo256 bitsRS256NoYesAt least 2048 bitsES256NoYes256 bitsHS384YesNo384 bitsRS384NoYesAt least 2048 bitsES384NoYes384 bitsHS512YesNo512 bitsRS512NoYesAt least 2048 bitsES512NoYes512 bits A required key size indicates that an error occurs if this value is not supplied. A suggested key size indicates the minimum value to achieve a reasonable level of security.Encryption key agreementAlgorithmUses symmetric keyUses certificatesRequired key sizeRSA1_5NoYesAt least 2048 bitsRSA-OAEPNoYesAt least 2048 bitsRSA-OAEP-256NoYesAt least 2048 bitsA128KWYesNo128 bitsA192KWYesNo192 bitsA256KWYesNo256 bitsA128GCMKWYesNo128 bitsA192GCMKWYesNo192 bitsA256GCMKWYesNo256 bitsdirYesNoThe key size that is required by the encryption algorithm (one of 128, 192, or 256 bits)ECDH-ESNoYesECDH-ES+A128KWNoYesECDH-ES+A192KWNoYesECDH-ES+A256KWNoYesA required key size indicates that an error occurs if this value is not supplied. Content encryption algorithmsAlgorithmUses symmetric keyRequired key sizeA128GCMYes128 bitsA192GCMYes192 bitsA256GCMYes256 bitsA128-CBC-HS256Yes256 bitsA192-CBC-HS384Yes384 bitsA256CBC-HS512Yes512 bitsA required key size indicates that an error occurs if this value is not supplied.The Content Encryption Key (CEK) is generated in most cases. When the encryption key algorithm is "dir", you must know the required key size of the CEK. Because the mode "dir" uses the provided key as the CEK. The size of each character in the "symmetricKey" field is 8 bits. For a 128-bit key, you need to provide a 16 character key. The previously listed algorithms are from the JWA RFC(7518) https://tools.ietf.org/html/rfc7518.JSON Web Token (JWT)A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC.

JWT support

IBM Security Access Manager supports JWT by using STS to expose a JWT module.

This module can be run in the following two modes:

Validate

Consume a JWT.

Issue

Create a JWT.

Both modes support signing, encryption, and some basic validation or population of claims.

Security Access Manager supports consuming a nested JWT using the header claim “cty”:”JWT”. However, this support applies only when the JWT is both signed and encrypted, per RFC 7519 section 11.2.

The JWT module supports the following JSON Web Algorithms.

Table 122. Signing algorithms

Algorithm | Uses symmetric key | Uses certificates | Required key size | Suggested key size
HS256 | Yes | No |  | 256 bits
RS256 | No | Yes | At least 2048 bits |
ES256 | No | Yes | 256 bits |
HS384 | Yes | No |  | 384 bits
RS384 | No | Yes | At least 2048 bits |
ES384 | No | Yes | 384 bits |
HS512 | Yes | No |  | 512 bits
RS512 | No | Yes | At least 2048 bits |
ES512 | No | Yes | 512 bits |

Note: A required key size indicates that an error occurs if this value is not supplied. A suggested key size indicates the minimum value to achieve a reasonable level of security.

Table 123. Encryption key agreement

Algorithm | Uses symmetric key | Uses certificates | Required key size
RSA1_5 | No | Yes | At least 2048 bits
RSA-OAEP | No | Yes | At least 2048 bits
RSA-OAEP-256 | No | Yes | At least 2048 bits
A128KW | Yes | No | 128 bits
A192KW | Yes | No | 192 bits
A256KW | Yes | No | 256 bits
A128GCMKW | Yes | No | 128 bits
A192GCMKW | Yes | No | 192 bits
A256GCMKW | Yes | No | 256 bits
dir | Yes | No | The key size that is required by the encryption algorithm (one of 128, 192, or 256 bits)
ECDH-ES | No | Yes |
ECDH-ES+A128KW | No | Yes |
ECDH-ES+A192KW | No | Yes |
ECDH-ES+A256KW | No | Yes |

Note: A required key size indicates that an error occurs if this value is not supplied.

Table 124. Content encryption algorithms

Algorithm | Uses symmetric key | Required key size
A128GCM | Yes | 128 bits
A192GCM | Yes | 192 bits
A256GCM | Yes | 256 bits
A128-CBC-HS256 | Yes | 256 bits
A192-CBC-HS384 | Yes | 384 bits
A256CBC-HS512 | Yes | 512 bits

Note:

A required key size indicates that an error occurs if this value is not supplied.

The Content Encryption Key (CEK) is generated in most cases. When the encryption key algorithm is "dir", you must know the required key size of the CEK. Because the mode "dir" uses the provided key as the CEK.

The size of each character in the "symmetricKey" field is 8 bits. For a 128-bit key, you need to provide a 16 character key.

The previously listed algorithms are from the JWA RFC(7518) https://tools.ietf.org/html/rfc7518.

Parent topic: JSON Web Token (JWT)

Validate modeIn validate mode, the JWT Module consumes a binary security token, which has the attribute type “urn:com:ibm:JWT”. When the module consumes a JWT, the following operations are performed:The keys are resolved.The JWT is decrypted if it was encrypted.The JWT signature is verified if it was signed. If the JWT was encrypted, this step is performed on the payload of the decrypted JWT.The claims are validated.The STSUU is populated.If the JWT is successfully decrypted and validated, then the STSUU attributes will contain the claims and context attributes. The claims will have the attribute type urn:com:ibm:JWT:claim. The context attributes will have one of the following values:urn:com:ibm:JWT:headerurn:com:ibm:JWT:outer_headerurn:com:ibm:JWT:signatureThe following table shows the configuration properties.Configuration properties and usage in validate modeConfiguration propertyDescriptionCan be provided via WS-Trust claimssigning.algThe algorithm with which the JWT is signed.FALSEsigning.symmetricKeyThe symmetric key that is used to perform signature validation.TRUEsigning.dbThe keystore from which the certificate is sourced.TRUEsigning.certThe certificate label from which the public keys are sourced.TRUEsigning.jwksUriThe JWKS URI from which the public key is retrieved.TRUEsigning.kidThe Key ID that is obtained from the retrieved JWKS. TRUEencryption.algThe algorithm that is used by the JWT for key management.FALSEencryption.encThe algorithm that is used by the JWT for content encryption.FALSEencryption.symmetricKeyThe symmetric key that is used for key management.TRUEencryption.dbThe keystore from which the private key is sourced.TRUEencryption.certThe label of the certificate that contains the private key to use for decrypting the encryption key.TRUEissThe Java regular expression that matches the iss (issuer) claim. This value is optional. FALSEaudThe Java regular expression that matches the aud (audience) claim. This value is optional. FALSEsubThe Java regular expression that matches the sub (subject) claim. This value is optional. FALSEvalidateExpWhether the exp claim in the JWT is checked. This check requires that the exp (expiration time) claim be set to a time in the future.FALSEvalidateNbfWhether the nbf (not before) claim in the JWT is checked. This check requires that the nbf claim be set to a time in the past.FALSEvalidateSkewThe skew to offset time checks with. FALSEWhen the module runs in validate mode, it converts the JWT into a populated STSUU. The following examples show some sample input JWT and the corresponding output STSUU.Input example <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:rst="http://docs.oasis-open.org/ws-sx/ws-trust/200512" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <SOAP-ENV:Body> <!-- <rst:RequestSecurityTokenCollection>--> <rst:RequestSecurityToken> <wsp:AppliesTo> <wsa:EndpointReference> <wsa:Address>validate</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:Issuer> <wsa:Address>validate</wsa:Address> </wst:Issuer> <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02 /trust/Validate</wst:RequestType> <wst:Claims><signing.alg>HS256</signing.alg><signing. symmetricKey>superSecret</signing.symmetricKey></wst:Claims> <wst:Base> <wss:BinarySecurityToken xmlns:wss="http://docs.oasis-open.org /wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" wss: EncodingType="http://ibm.com/2004/01/itfim/base64encode" wss: ValueType="urn:com:ibm:JWT">eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoi am9obiIsInRpdGxlIjoiTXIiLCJleHAiOjE0NjA0MzkxNzN9.BNkZM38PygNYb PzGSsd1Za8HmgUkn0aT0ImaJmBmKtU</wss:BinarySecurityToken> </wst:Base> </rst:RequestSecurityToken> <!--</rst:RequestSecurityTokenCollection>--> </SOAP-ENV:Body> </SOAP-ENV:Envelope>Output example <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/> <soap:Body> <wst:RequestSecurityTokenResponseCollection xmlns:wst="http:// docs.oasis-open.org/ws-sx/ws-trust/200512"> <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org /wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="uuid8f53fcc-0154-10f4-bfcd-ebb7b0604011"> <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns: wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <wsa:EndpointReference> <wsa:Address>validate</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:RequestedSecurityToken> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal/> <stsuuser:AttributeList> <stsuuser:Attribute name="title" type="urn:com:ibm:JWT:claim"> <stsuuser:Value>Mr</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="exp" type="urn:com:ibm:JWT:claim"> <stsuuser:Value>1460439173</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="name" type="urn:com:ibm:JWT:claim"> <stsuuser:Value>john</stsuuser:Value> </stsuuser:Attribute> </stsuuser:AttributeList> <stsuuser:RequestSecurityToken/> <stsuuser:ContextAttributes> <stsuuser:Attribute name="header" type="urn:com:ibm:JWT"> <stsuuser:Value>{"alg":"HS256"}</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="signature" type="urn:com:ibm:JWT"> <stsuuser:Value>BNkZM38PygNYbPzGSsd1Za8HmgUkn0aT0ImaJmBmKtU </stsuuser:Value> </stsuuser:Attribute> </stsuuser:ContextAttributes> <stsuuser:AdditionalAttributeStatement/> </stsuuser:STSUniversalUser> </wst:RequestedSecurityToken> <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate </wst:RequestType> <wst:Status> <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status /valid</wst:Code> </wst:Status> </wst:RequestSecurityTokenResponse> </wst:RequestSecurityTokenResponseCollection> </soap:Body> </soap:Envelope>JSON Web Token (JWT)A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC.

Validate mode

In validate mode, the JWT Module consumes a binary security token, which has the attribute type “urn:com:ibm:JWT”.

When the module consumes a JWT, the following operations are performed:

The keys are resolved.

The JWT is decrypted if it was encrypted.

The JWT signature is verified if it was signed. If the JWT was encrypted, this step is performed on the payload of the decrypted JWT.

The claims are validated.

The STSUU is populated.

If the JWT is successfully decrypted and validated, then the STSUU attributes will contain the claims and context attributes. The claims will have the attribute type urn:com:ibm:JWT:claim. The context attributes will have one of the following values:

urn:com:ibm:JWT:header

urn:com:ibm:JWT:outer_header

urn:com:ibm:JWT:signature

The following table shows the configuration properties.

Table 125. Configuration properties and usage in validate mode

Configuration property | Description | Can be provided via WS-Trust claims
signing.alg | The algorithm with which the JWT is signed. | FALSE
signing.symmetricKey | The symmetric key that is used to perform signature validation. | TRUE
signing.db | The keystore from which the certificate is sourced. | TRUE
signing.cert | The certificate label from which the public keys are sourced. | TRUE
signing.jwksUri | The JWKS URI from which the public key is retrieved. | TRUE
signing.kid | The Key ID that is obtained from the retrieved JWKS. | TRUE
encryption.alg | The algorithm that is used by the JWT for key management. | FALSE
encryption.enc | The algorithm that is used by the JWT for content encryption. | FALSE
encryption.symmetricKey | The symmetric key that is used for key management. | TRUE
encryption.db | The keystore from which the private key is sourced. | TRUE
encryption.cert | The label of the certificate that contains the private key to use for decrypting the encryption key. | TRUE
iss | The Java regular expression that matches the "iss" (issuer) claim. This value is optional. | FALSE
aud | The Java regular expression that matches the "aud" (audience) claim. This value is optional. | FALSE
sub | The Java regular expression that matches the "sub" (subject) claim. This value is optional. | FALSE
validateExp | Whether the exp claim in the JWT is checked. This check requires that the "exp" (expiration time) claim be set to a time in the future. | FALSE
validateNbf | Whether the "nbf" (not before) claim in the JWT is checked. This check requires that the nbf claim be set to a time in the past. | FALSE
validateSkew | The skew to offset time checks with. | FALSE

When the module runs in validate mode, it converts the JWT into a populated STSUU. The following examples show some sample input JWT and the corresponding output STSUU.

Input example

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:rst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">

  <SOAP-ENV:Body>
    <!--  <rst:RequestSecurityTokenCollection>-->
      <rst:RequestSecurityToken>
        <wsp:AppliesTo>
          <wsa:EndpointReference>
            <wsa:Address>validate</wsa:Address>
          </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wst:Issuer>
          <wsa:Address>validate</wsa:Address>
        </wst:Issuer>
        <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02
        /trust/Validate</wst:RequestType>
        <wst:Claims><signing.alg>HS256</signing.alg><signing.
        symmetricKey>superSecret</signing.symmetricKey></wst:Claims>
        <wst:Base>
        <wss:BinarySecurityToken xmlns:wss="http://docs.oasis-open.org
        /wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" wss:
        EncodingType="http://ibm.com/2004/01/itfim/base64encode" wss:
        ValueType="urn:com:ibm:JWT">eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoi
        am9obiIsInRpdGxlIjoiTXIiLCJleHAiOjE0NjA0MzkxNzN9.BNkZM38PygNYb
        PzGSsd1Za8HmgUkn0aT0ImaJmBmKtU</wss:BinarySecurityToken>

        </wst:Base>
      </rst:RequestSecurityToken>
      <!--</rst:RequestSecurityTokenCollection>-->
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Output example

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://
    docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org
      /wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
      wsu:Id="uuid8f53fcc-0154-10f4-bfcd-ebb7b0604011">
        <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:
        wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
          <wsa:EndpointReference>
            <wsa:Address>validate</wsa:Address>
          </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wst:RequestedSecurityToken>
          <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
            <stsuuser:Principal/>
            <stsuuser:AttributeList>
              <stsuuser:Attribute name="title" type="urn:com:ibm:JWT:claim">
                <stsuuser:Value>Mr</stsuuser:Value>
              </stsuuser:Attribute>
              <stsuuser:Attribute name="exp" type="urn:com:ibm:JWT:claim">
                <stsuuser:Value>1460439173</stsuuser:Value>
              </stsuuser:Attribute>
              <stsuuser:Attribute name="name" type="urn:com:ibm:JWT:claim">
                <stsuuser:Value>john</stsuuser:Value>
              </stsuuser:Attribute>
            </stsuuser:AttributeList>
            <stsuuser:RequestSecurityToken/>
            <stsuuser:ContextAttributes>
              <stsuuser:Attribute name="header" type="urn:com:ibm:JWT">
                <stsuuser:Value>{"alg":"HS256"}</stsuuser:Value>
              </stsuuser:Attribute>
              <stsuuser:Attribute name="signature" type="urn:com:ibm:JWT">
                <stsuuser:Value>BNkZM38PygNYbPzGSsd1Za8HmgUkn0aT0ImaJmBmKtU
                </stsuuser:Value>
              </stsuuser:Attribute>
            </stsuuser:ContextAttributes>
            <stsuuser:AdditionalAttributeStatement/>
          </stsuuser:STSUniversalUser>
        </wst:RequestedSecurityToken>
        <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
        </wst:RequestType>
        <wst:Status>
          <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status
          /valid</wst:Code>
        </wst:Status>
      </wst:RequestSecurityTokenResponse>
    </wst:RequestSecurityTokenResponseCollection>
  </soap:Body>
</soap:Envelope>

Parent topic: JSON Web Token (JWT)

Issue modeIn issue mode, the JWT Module creates a binary security token, which has the attribute type urn:com:ibm:JWT. When the module creates a JWT, the following operations are performed:The keys are resolved.The claims are populated from the STSUU.The static claims are populated, if they were configured and are not already set from the STSUU.The JWT is signed if signing is set.The JWT is encrypted. If it is signed, the signed JWT will be encrypted and the claim “cty”:”jwt” will be added to the header.The binary security token is issued.The following table shows the configuration properties. Configuration properties and usage in issue modeConfiguration propertyDescriptionCan be provided by STSUU Context Attributessigning.algThe algorithm with which the JWT is signed.TRUEsigning.symmetricKeyThe symmetric key that is used to perform signature validation.TRUEsigning.dbThe keystore from which the certificate is sourced.TRUEsigning.certThe certificate label from which the public keys are sourced.TRUEencryption.jwksUri The JWKS URI that is used for encryption.TRUEencryption.kidThe Key ID that is used for encryption. TRUEencryption.algThe algorithm that is used by the JWT for key management.TRUEencryption.encThe algorithm that is used by the JWT for content encryption.TRUEencryption.symmetricKeyThe symmetric key that is used for key management.TRUEencryption.dbThe keystore from which the private key is sourced.TRUEencryption.certThe label of the certificate that contains the private key to use for decrypting the encryption key.TRUEincludeIatA Boolean value that indicates whether the iat (issued at) claim is generated and included in the JWT. This value does not override an existing iat value if it is already present.FALSEissThe static value with which the iss (issuer) claim is populated.FALSEaudThe static value with which the aud (audience) claim is populated.FALSEsubThe static value with which the sub (subject) claim is populated.FALSEjtiJWT ID, which is a unique identifier for the JWT. A value of 0 disables the claim.FALSEexpOffset for the exp (expiration time) claim. A value of 0 disables the claim.FALSEnbfOffset for the nbf (not before) claim. A value of -1 disables the claim. FALSEWhen the module runs in issue mode, it converts the STSUU into a JWT. The following examples show some sample input STSUU and the corresponding output JWT.Input example <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:rst="http://docs.oasis-open.org/ws-sx/ws-trust/200512" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <SOAP-ENV:Body> <rst:RequestSecurityToken> <wsp:AppliesTo> <wsa:EndpointReference> <wsa:Address>issue</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:Issuer> <wsa:Address>issue</wsa:Address> </wst:Issuer> <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate </wst:RequestType> <wst:Base> <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser"> <stsuuser:Principal/> <stsuuser:AttributeList> <stsuuser:Attribute name="name" type="urn:ibm:jwt:claim"> <stsuuser:Value>john</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="title" type="urn:ibm:jwt:claim"> <stsuuser:Value>Mr</stsuuser:Value> </stsuuser:Attribute> </stsuuser:AttributeList> <stsuuser:ContextAttributes> <!-- specify a HS256 JWT, with the key "superSecret" --> <stsuuser:Attribute name="signing.symmetricKey" type=""> <stsuuser:Value>superSecret</stsuuser:Value> </stsuuser:Attribute> <stsuuser:Attribute name="signing.alg" type=""> <stsuuser:Value>HS256</stsuuser:Value> </stsuuser:Attribute> </stsuuser:ContextAttributes> <stsuuser:AdditionalAttributeStatement id=""/> </stsuuser:STSUniversalUser> </wst:Base> </rst:RequestSecurityToken> </SOAP-ENV:Body> </SOAP-ENV:Envelope>Output example <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/> <soap:Body> <wst:RequestSecurityTokenResponseCollection xmlns:wst="http:// docs.oasis-open.org/ws-sx/ws-trust/200512"> <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org/ wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id= "uuid8f2887f-0154-1671-a234-ebb7b0604011"> <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns: wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <wsa:EndpointReference> <wsa:Address>issue</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:RequestedSecurityToken> <wss:BinarySecurityToken xmlns:wss="http://docs.oasis-open.org/wss /2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" wss:EncodingType= "http://ibm.com/2004/01/itfim/base64encode" wss:ValueType="urn:com:ibm:JWT"> eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiam9obiIsInRpdGxlIjoiTXIiLCJleHAiOjE0NjA0Mz kxNzN9.BNkZM38PygNYbPzGSsd1Za8HmgUkn0aT0ImaJmBmKtU</wss:BinarySecurityToken> </wst:RequestedSecurityToken> <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate </wst:RequestType> <wst:Status> <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid </wst:Code> </wst:Status> </wst:RequestSecurityTokenResponse> </wst:RequestSecurityTokenResponseCollection> </soap:Body> </soap:Envelope>JSON Web Token (JWT)A JWT is a set of JSON claims that are signed, encrypted, or both, and are encoded into a web safe form. This set of claims might or might not include some well-known claims that are defined by the RFC.

Issue mode

In issue mode, the JWT Module creates a binary security token, which has the attribute type urn:com:ibm:JWT.

When the module creates a JWT, the following operations are performed:

The keys are resolved.

The claims are populated from the STSUU.

The static claims are populated, if they were configured and are not already set from the STSUU.

The JWT is signed if signing is set.

The JWT is encrypted. If it is signed, the signed JWT will be encrypted and the claim “cty”:”jwt” will be added to the header.

The binary security token is issued.

The following table shows the configuration properties.

Table 126. Configuration properties and usage in issue mode

Configuration property | Description | Can be provided by STSUU Context Attributes
signing.alg | The algorithm with which the JWT is signed. | TRUE
signing.symmetricKey | The symmetric key that is used to perform signature validation. | TRUE
signing.db | The keystore from which the certificate is sourced. | TRUE
signing.cert | The certificate label from which the public keys are sourced. | TRUE
encryption.jwksUri | The JWKS URI that is used for encryption. | TRUE
encryption.kid | The Key ID that is used for encryption. | TRUE
encryption.alg | The algorithm that is used by the JWT for key management. | TRUE
encryption.enc | The algorithm that is used by the JWT for content encryption. | TRUE
encryption.symmetricKey | The symmetric key that is used for key management. | TRUE
encryption.db | The keystore from which the private key is sourced. | TRUE
encryption.cert | The label of the certificate that contains the private key to use for decrypting the encryption key. | TRUE
includeIat | A Boolean value that indicates whether the "iat" (issued at) claim is generated and included in the JWT. This value does not override an existing "iat" value if it is already present. | FALSE
iss | The static value with which the "iss" (issuer) claim is populated. | FALSE
aud | The static value with which the "aud" (audience) claim is populated. | FALSE
sub | The static value with which the "sub" (subject) claim is populated. | FALSE
jti | JWT ID, which is a unique identifier for the JWT. A value of 0 disables the claim. | FALSE
exp | Offset for the "exp" (expiration time) claim. A value of 0 disables the claim. | FALSE
nbf | Offset for the "nbf" (not before) claim. A value of -1 disables the claim. | FALSE

When the module runs in issue mode, it converts the STSUU into a JWT. The following examples show some sample input STSUU and the corresponding output JWT.

Input example

<?xml version="1.0"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:rst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
  <SOAP-ENV:Body>
      <rst:RequestSecurityToken>
        <wsp:AppliesTo>
          <wsa:EndpointReference>
            <wsa:Address>issue</wsa:Address>
          </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wst:Issuer>
          <wsa:Address>issue</wsa:Address>
        </wst:Issuer>
        <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
        </wst:RequestType>
        <wst:Base>
          <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
            <stsuuser:Principal/>
            <stsuuser:AttributeList>
              <stsuuser:Attribute name="name" type="urn:ibm:jwt:claim">
                <stsuuser:Value>john</stsuuser:Value>
              </stsuuser:Attribute>
              <stsuuser:Attribute name="title" type="urn:ibm:jwt:claim">
                <stsuuser:Value>Mr</stsuuser:Value>
              </stsuuser:Attribute>
            </stsuuser:AttributeList>
            <stsuuser:ContextAttributes>

	    <!-- specify a HS256 JWT, with the key "superSecret" -->
              <stsuuser:Attribute name="signing.symmetricKey" type="">
                <stsuuser:Value>superSecret</stsuuser:Value>
              </stsuuser:Attribute>
              <stsuuser:Attribute name="signing.alg" type="">
                <stsuuser:Value>HS256</stsuuser:Value>
              </stsuuser:Attribute>
            </stsuuser:ContextAttributes>
            <stsuuser:AdditionalAttributeStatement id=""/>
          </stsuuser:STSUniversalUser>
        </wst:Base>

      </rst:RequestSecurityToken>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Output example

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://
    docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org/
      wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id=
      "uuid8f2887f-0154-1671-a234-ebb7b0604011">
        <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:
        wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
          <wsa:EndpointReference>
            <wsa:Address>issue</wsa:Address>
          </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wst:RequestedSecurityToken>
          <wss:BinarySecurityToken xmlns:wss="http://docs.oasis-open.org/wss
          /2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" wss:EncodingType=
          "http://ibm.com/2004/01/itfim/base64encode" wss:ValueType="urn:com:ibm:JWT">
          eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiam9obiIsInRpdGxlIjoiTXIiLCJleHAiOjE0NjA0Mz
          kxNzN9.BNkZM38PygNYbPzGSsd1Za8HmgUkn0aT0ImaJmBmKtU</wss:BinarySecurityToken>
        </wst:RequestedSecurityToken>
        <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
        </wst:RequestType>
        <wst:Status>
          <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid
          </wst:Code>
        </wst:Status>
      </wst:RequestSecurityTokenResponse>
    </wst:RequestSecurityTokenResponseCollection>
  </soap:Body>
</soap:Envelope>

Parent topic: JSON Web Token (JWT)

Token module propertiesToken module propertiesToken module propertiesConfigure token modules so that it contains the appropriate values for your environment.manageItfimStsChainMappingtoken module propertiesConfiguring STS modulesConfigure Security Token Service (STS) modules to validate and exchange security token types.Attribute Mapping module propertiesYou can define Attribute Mapping module self or partner properties. Default Mapping module propertiesYou can define Default Mapping module self or partner properties. HTTP Callout module propertiesYou can define HTTP Callout module self or partner properties. IVCred module propertiesYou can define Security Access Manager IVCred token module self or partner properties. LTPA module propertiesYou can define LTPA token module self or partner properties. SAML 2.0 module propertiesYou can define SAML 2.0 token module self or partner properties. Username module propertiesYou can define Username module self or partner properties.

Token module properties

Configure token modules so that it contains the appropriate values for your environment.

Attribute Mapping module properties
You can define Attribute Mapping module self or partner properties.

Default Mapping module properties
You can define Default Mapping module self or partner properties.

HTTP Callout module properties
You can define HTTP Callout module self or partner properties.

IVCred module properties
You can define Security Access Manager IVCred token module self or partner properties.

LTPA module properties
You can define LTPA token module self or partner properties.

SAML 2.0 module properties
You can define SAML 2.0 token module self or partner properties.

Username module properties
You can define Username module self or partner properties.

Parent topic: Configuring STS modules

Attribute Mapping module propertiesAttribute Mapping module propertiesAttribute Mapping module propertiesYou can define Attribute Mapping module self or partner properties. Attribute Mapping modulepropertiespropertiesAttribute Mapping moduleAttribute Mapping module propertiesAppliance propertySelf or PartnerModeDescriptionattribute.mappingsPARTNER, SELFMapAttribute Mapping in the format: attributeName_attributeSourceID.Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.

Attribute Mapping module properties

You can define Attribute Mapping module self or partner properties.

Table 127. Attribute Mapping module properties

Appliance property | Self or Partner | Mode | Description
attribute.mappings | PARTNER, SELF | Map | Attribute Mapping in the format: attributeName_attributeSourceID.

Parent topic: Token module properties

Default Mapping module propertiesDefault Mapping module propertiesDefault Mapping module propertiesYou can define Default Mapping module self or partner properties. Default Mapping modulepropertiespropertiesDefault Mapping moduleDefault Mapping module propertiesAppliance propertySelf or PartnerModeDescriptionmap.rule.reference.idsPARTNER, SELFMapSpecifies the ID of the JavaScript file containing the identity mapping rule.Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.

Default Mapping module properties

You can define Default Mapping module self or partner properties.

Table 128. Default Mapping module properties

Appliance property | Self or Partner | Mode | Description
map.rule.reference.ids | PARTNER, SELF | Map | Specifies the ID of the JavaScript file containing the identity mapping rule.

Parent topic: Token module properties

HTTP Callout module propertiesHTTP Callout module propertiesHTTP Callout module propertiesYou can define HTTP Callout module self or partner properties. HTTP Callout modulepropertiespropertiesHTTP Callout moduleHTTP Callout module propertiesAppliance propertySelf or PartnerModeDescriptionuriPARTNER, SELFMapSpecifies the endpoint address of the web service.authTypePARTNER, SELFMapSpecifies the client authentication type:NONESpecifies no authentication.CERTIFICATESpecifies client certificate authentication. If selected, set the following client keystore parameters:clientKeyStoreclientKeyAliasBASICSpecifies basic authentication. If selected, set the basic authentication username and password parameters:basicAuthUsernamebasicAuthPasswordsslKeyStorePARTNER, SELFMapSpecifies the server certificate information. If the uri parameter is an HTTPS endpoint, then set this parameter to point to the truststore that contains the HTTPS certificate of the endpoint.clientKeyStorePARTNER, SELFMapDefines the name of the client certificate store. It is required if the authType parameter is set to CERTFICATE. clientKeyAliasPARTNER, SELFMapDefines the alias of the client certificate. It is required if the authType parameter is set to CERTFICATE. basicAuthUsernamePARTNER, SELFMapDefines the basic authentication username. It is required if the authType parameter is set to BASIC. basicAuthPasswordPARTNER, SELFMapDefines the plain text basic authentication password. It is required if the authType parameter is set to BASIC. messageFormatPARTNER, SELFMapDefines the plain text basic authentication password. It is required if the authType parameter is set to BASIC. appliesToPARTNER, SELFMapIf the messageFormat parameter is set to WSTrust, then set this parameter to the WSTrust applies-to address. This value is typically formatted as a URL.issuerUriPARTNER, SELFMapIf the messageFormat parameter is set to WSTrust, then set this parameter to the WSTrust issuer address. This value is typically formatted as a URL.Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.

HTTP Callout module properties

You can define HTTP Callout module self or partner properties.

Table 129. HTTP Callout module properties

Appliance property
Self or Partner
Mode
Description

uri
PARTNER, SELF
Map
Specifies the endpoint address of the web service.

authType
PARTNER, SELF
Map
Specifies the client authentication type:

NONE

Specifies no authentication.

CERTIFICATE

Specifies client certificate authentication. If selected, set the following client keystore parameters:

clientKeyStore

clientKeyAlias

BASIC

Specifies basic authentication. If selected, set the basic authentication username and password parameters:

basicAuthUsername

basicAuthPassword

sslKeyStore
PARTNER, SELF
Map
Specifies the server certificate information. If the uri parameter is an HTTPS endpoint, then set this parameter to point to the truststore that contains the HTTPS certificate of the endpoint.

clientKeyStore
PARTNER, SELF
Map
Defines the name of the client certificate store. It is required if the authType parameter is set to CERTFICATE.

clientKeyAlias
PARTNER, SELF
Map
Defines the alias of the client certificate. It is required if the authType parameter is set to CERTFICATE.

basicAuthUsername
PARTNER, SELF
Map
Defines the basic authentication username. It is required if the authType parameter is set to BASIC.

basicAuthPassword
PARTNER, SELF
Map
Defines the plain text basic authentication password. It is required if the authType parameter is set to BASIC.

messageFormat

PARTNER, SELF
Map
Defines the plain text basic authentication password. It is required if the authType parameter is set to BASIC.

appliesTo
PARTNER, SELF
Map
If the messageFormat parameter is set to WSTrust, then set this parameter to the WSTrust applies-to address. This value is typically formatted as a URL.

issuerUri
PARTNER, SELF
Map
If the messageFormat parameter is set to WSTrust, then set this parameter to the WSTrust issuer address. This value is typically formatted as a URL.

Parent topic: Token module properties

IVCred module propertiesIVCred module propertiesIVCred module propertiesYou can define Security Access Manager IVCred token module self or partner properties. IVCred token modulepropertiespropertiesIVCred moduleIVCred module propertiesAppliance PropertySelf or PartnerModeDescriptionivcred.attribute.typesSELFIssueSpecifies the attribute type to include in the assertion. Enter one attribute type, or use an asterisk (*) for all types.The default is an asterisk (*).This property is required.ivcred.sign.keystore.alias.dbSELFIssueSpecifies the name of the keystore for the signing key. For example, use DefaultKeyStore.This property is required if ivcred.add.signatures=true.ivcred.sign.keystore.alias.certSELFIssueSpecifies the name of the signing key. For example, use testkey.This property is required if ivcred.add.signatures=true.ivcred.add.signaturesSELFIssueSpecifies that signatures must be added to tokens.Set to true to add signatures to tokens.Set to false to exclude signatures in tokens.This property is optional.ivcred.signing. IncludeX509SubjectKeyIdentifierSELFIssueSpecifies whether to include this attribute.Set to true to include the X509 Subject Key Identifier of the signing certificate.Set to false to exclude the X509 Subject Key Identifier. This is the default.Required if ivcred.add.signatures=true.ivcred.signing.IncludePublicKeySELFIssueSpecifies whether to include the KeyInfo element, Public Key. Set to true to include the Public Key.Set to false to exclude the Public Key. This is the default.Required if ivcred.add.signatures=true.ivcred.signing. IncludeX509IssuerDetailsSELFIssueSpecifies whether to include the Key Info element, X509 Issuer Details.Set to true to include the X509 Issuer Details.Set to false to exclude the X509 Issuer Details. This is the default.Required if ivcred.add.signatures=true.ivcred.IncludeX509SubjectNameSELFIssueSpecifies whether to include the Key Info element, X509 Subject Name. Set to true to include the X509 Subject Name.Set to false to exclude the X509 Subject Name. This is the default.Required if ivcred.add.signatures=true.ivcred.IncludeX509CertificateDataSELFIssueSpecifies whether to include the Key Info element, X509 Certificate Data.Set to true to include the X509 Certificate Data.Set to false to exclude the X509 Certificate Data. This is the default.Required if ivcred.add.signatures=true.ivcred.validate.keystore.alias.dbPARTNERValidateSpecifies the name of the keystore for the key identifier. For example, use DefaultKeyStore.Required if ivcred.verify.signatures=true. ivcred.validate.keystore.alias.certPARTNERValidateSpecifies the name of the validation key identifier. For example, use testkey.Required if ivcred.verify.signatures=true. ivcred.verify.signaturesPARTNERValidate Specifies whether the signatures are verified.Set to true to verify signatures.Set to false for no signature verification. The default is false.This property is optional.Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.

IVCred module properties

You can define Security Access Manager IVCred token module self or partner properties.

Table 130. IVCred module properties

Appliance Property
Self or Partner
Mode
Description

ivcred.attribute.types
SELF
Issue
Specifies the attribute type to include in the assertion.

Enter one attribute type, or use an asterisk (*) for all types.

The default is an asterisk (*).

This property is required.

ivcred.sign.keystore.alias.db
SELF
Issue
Specifies the name of the keystore for the signing key. For example, use DefaultKeyStore.

This property is required if ivcred.add.signatures=true.

ivcred.sign.keystore.alias.cert
SELF
Issue
Specifies the name of the signing key. For example, use testkey.

This property is required if ivcred.add.signatures=true.

ivcred.add.signatures
SELF
Issue
Specifies that signatures must be added to tokens.

Set to true to add signatures to tokens.

Set to false to exclude signatures in tokens.

This property is optional.

ivcred.signing.

IncludeX509SubjectKeyIdentifier

SELF
Issue
Specifies whether to include this attribute.

Set to true to include the X509 Subject Key Identifier of the signing certificate.

Set to false to exclude the X509 Subject Key Identifier. This is the default.

Required if ivcred.add.signatures=true.

ivcred.signing.IncludePublicKey
SELF
Issue
Specifies whether to include the KeyInfo element, Public Key.

Set to true to include the Public Key.

Set to false to exclude the Public Key. This is the default.

Required if ivcred.add.signatures=true.

ivcred.signing.

IncludeX509IssuerDetails

SELF
Issue
Specifies whether to include the Key Info element, X509 Issuer Details.

Set to true to include the X509 Issuer Details.

Set to false to exclude the X509 Issuer Details. This is the default.

Required if ivcred.add.signatures=true.

ivcred.IncludeX509SubjectName
SELF
Issue
Specifies whether to include the Key Info element, X509 Subject Name.

Set to true to include the X509 Subject Name.

Set to false to exclude the X509 Subject Name. This is the default.

Required if ivcred.add.signatures=true.

ivcred.IncludeX509CertificateData
SELF
Issue
Specifies whether to include the Key Info element, X509 Certificate Data.

Set to true to include the X509 Certificate Data.

Set to false to exclude the X509 Certificate Data. This is the default.

Required if ivcred.add.signatures=true.

ivcred.validate.keystore.alias.db
PARTNER
Validate
Specifies the name of the keystore for the key identifier. For example, use DefaultKeyStore.

Required if ivcred.verify.signatures=true.

ivcred.validate.keystore.alias.cert
PARTNER
Validate
Specifies the name of the validation key identifier. For example, use testkey.

Required if ivcred.verify.signatures=true.

ivcred.verify.signatures
PARTNER
Validate
Specifies whether the signatures are verified.

Set to true to verify signatures.

Set to false for no signature verification. The default is false.

This property is optional.

Parent topic: Token module properties

LTPA module propertiesLTPA module propertiesLTPA module propertiesYou can define LTPA token module self or partner properties. LTPA modulepropertiespropertiesLTPA moduleLTPA module propertiesAppliance propertySelf or PartnerModeDescriptionltpa.self.filenameSELFIssueSpecifies the LTPA file to use. This property is required.ltpa.self.passwordSELFIssueSpecifies the password that was used to protect the keys. It must be the same password that was used when the keys were created. This property is required.ltpa.self.expirationSELFIssueSpecifies the expiration, in minutes, set on created tokens. The default is 120.ltpa.self.extattrSELFIssueSpecifies the attribute type to add to a version 2 token.Enter one attribute type, or use an asterisk (*) for all types.ltpa.self.realmSELFIssueSpecifies the realm used to create the user name in the token.ltpa.self.usefipsSELFIssueSpecifies whether FIPS mode should be used for incoming tokens. The default is false.ltpa.self.versionSELFIssueSpecifies the version of token to be created. This property is required.ltpa.partner.filenamePARTNERValidateSpecifies the name of the previously imported LTPA file. This property is optional.ltpa.partner.passwordPARTNERValidateSpecifies the password that was used to protect the keys created by the partner. It must be the same password that was used when the keys were created by the partner. This property is optional.ltpa.partner.usefipsPARTNERValidateSpecifies whether FIPS mode should be used for incoming tokens.Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.

LTPA module properties

You can define LTPA token module self or partner properties.

Table 131. LTPA module properties

Appliance property
Self or Partner
Mode
Description

ltpa.self.filename
SELF
Issue
Specifies the LTPA file to use.

This property is required.

ltpa.self.password
SELF
Issue
Specifies the password that was used to protect the keys. It must be the same password that was used when the keys were created.

This property is required.

ltpa.self.expiration
SELF
Issue
Specifies the expiration, in minutes, set on created tokens.

The default is 120.

ltpa.self.extattr
SELF
Issue
Specifies the attribute type to add to a version 2 token.

Enter one attribute type, or use an asterisk (*) for all types.

ltpa.self.realm
SELF
Issue
Specifies the realm used to create the user name in the token.

ltpa.self.usefips
SELF
Issue
Specifies whether FIPS mode should be used for incoming tokens. The default is false.

ltpa.self.version
SELF
Issue
Specifies the version of token to be created. This property is required.

ltpa.partner.filename
PARTNER
Validate
Specifies the name of the previously imported LTPA file.

This property is optional.

ltpa.partner.password
PARTNER
Validate
Specifies the password that was used to protect the keys created by the partner. It must be the same password that was used when the keys were created by the partner.

This property is optional.

ltpa.partner.usefips
PARTNER
Validate
Specifies whether FIPS mode should be used for incoming tokens.

Parent topic: Token module properties

SAML 2.0 module propertiesSAML 2.0 module propertiesSAML 2.0 module propertiesYou can define SAML 2.0 token module self or partner properties. SAML 2.0 modulepropertiespropertiesSAML 2.0 moduleSAML 2.0 module propertiesAppliance propertySelf or PartnerModeDescriptioncom.tivoli.am.fim.sts.saml.2.0. assertion.replay.validationSELFValidateSpecifies whether to enable one-time assertion use enforcement.Set to true to enable one-time use enforcement.Set to false if you do not want to enforce one-time asssertion use.com.tivoli.am.fim.sts.saml.2.0. assertion.verify.signaturesPARTNERValidateSpecifies whether to enable signature validation.Set to true to enable validation.Set to false if you do not want validation enabled.com.tivoli.am.fim.sts.saml.2.0. assertion.signature.use.keyinfoPARTNERValidateSpecifies whether to use the KeyInfo of the XML signature to find the X509 certificate for signature validation.Set to true to use this method. Then, define the com.tivoli.am.fim.sts.saml.2.0.ValidateKeyIdentifier property.Set to false, otherwise.com.tivoli.am.fim.sts.saml.2.0. assertion.keystore.aliasPARTNERValidateSpecifies whether to use the keystore alias to find the public key for signature validation.Set to true to use this method. Then, define the com.tivoli.am.fim.sts.saml.2.0.ValidateKeyIdentifier.db and com.tivoli.am.fim.sts.saml.2.0.ValidateKeyIdentifier.cert properties.Set to false, otherwise.com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifierPARTNERValidateSpecifies a regular expression to validate the subject distinguished name returned in the KeyInfo, if com.tivoli.am.fim.sts.saml.2.0. assertion.signature.use.keyinfo is set to true.You can either specify this property or specify both of the following properties:com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier.dbcom.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier.certIf you specify all of these properties, the keystore alias format overwrites the com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier property.com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier.dbPARTNERValidateSpecifies the name of the certificate database to use for validation, if com.tivoli.am.fim.sts.saml.2.0.assertion. keystore.alias is set to true.com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier.certPARTNERValidateSpecifies the name of the certificate label for validation, if com.tivoli.am.fim.sts.saml.2.0.assertion.keystore.alias is set to true.com.tivoli.am.fim.sts.saml.2.0. DecryptionKeyIdentifier.dbPARTNERValidationSpecifies the name of the keystore for the decryption key. For example, use DefaultKeyStore.com.tivoli.am.fim.sts.saml.2.0. DecryptionKeyIdentifier.certPARTNERValidationSpecifies the name of decryption key. For example, use testkey.com.tivoli.am.fim.sts.saml.2.0. WantMultipleAttributeStatementsPARTNERValidateSpecifies whether to create multiple attribute statements in the Universal User.If you specify false, multiple attribute statements are arranged into a single group (AttributeList) in the STSUniversalUserdocument. This setting is appropriate for most configurations.com.tivoli.am.fim.sts.saml.2.0. map.unknown.aliasPARTNERValidate Specifies whether to map unknown name identifiers to the anonymous username.com.tivoli.am.fim.sts.saml.2.0. assertion.default.nameidformatPARTNERValidateSpecifies the default NameID format for assertion validation. Specify a parameter for use during validation of a SAML assertion. The parameter determines processing rules for the NameID element when one of the following conditions exists:If there is not an explicit Format attribute included in the assertion.If the Format attribute is: urn:oasis:names:tc:SAML:1.1: nameid-format:unspecified.Typically, this parameter is needed only for STS chains that process SAML assertions that do not set the Format attribute. A normal example value is :urn:oasis:names:tc:SAML:1.1: nameid-format:emailAddresscom.tivoli.am.fim.sts.saml.2.0. assertion.issuerSELFIssue, ExchangeSpecifies the name of the organization that issues assertions. This is required.com.tivoli.am.fim.sts.saml.2.0. assertion.pretime.validSELFIssue, ExchangeSpecifies the number of seconds that assertions are valid before its issue date. There is no minimum or maximum value enforced, but a value is required.Default: 60com.tivoli.am.fim.sts.saml.2.0. assertion.posttime.validSELFIssue, ExchangeSpecifies the number of seconds that assertions are valid after its issue date. There is no minimum or maximum value enforced, but a value is required.Default: 60SAML2.IncludeInclusiveNamespacesSELFIssue, ExchangeSpecifies whether to use the InclusiveNamespaces construct. This means using exclusive XML canonicalization for greater standardization. You must set this parameter without a prefix.Set to true or false.If unset, the system behaves as if it was set to true.com.tivoli.am.fim.sts.saml.2.0. assertion.attribute.typesPARTNERIssue, ExchangeSpecifies the types of attributes to include in the assertion.The default, an asterisk (*), includes all the attribute types that are specified in the identity mapping file.To specify one or more attribute types individually, enter each attribute type.Separate multiple type values using &&.com.tivoli.am.fim.sts.saml.2.0. assertion.signPARTNERIssue, ExchangeSpecifies whether SAML assertions must be signed.Set to true to sign assertions.Set to false if signing is not required.com.tivoli.am.fim.sts.saml.2.0. SigningKeyIdentifier.dbPARTNERIssue, ExchangeSpecifies the name of the keystore where the signing key is stored. For example, use DefaultKeyStore.com.tivoli.am.fim.sts.saml.2.0. signingKeyIdentifier.certPARTNERIssue, ExchangeSpecifies the name of the signing key identifier. For example, use testkey.com.tivoli.am.fim.sts.saml.2.0. assertion.signature.include. subject.keyidPARTNERIssue, ExchangeSpecifies whether to include the subject key identifier with your signature. Set to true to include the subject key identifier.Set to false to exclude the subject key identifier. com.tivoli.am.fim.sts.saml.2.0. assertion.signature.include. public.keyPARTNERIssue, ExchangeSpecifies whether to include the public key with your signature. Set to Yes to include the public key.Set to No to exclude the public key. com.tivoli.am.fim.sts.saml.2.0. assertion.signature.include. issuer.detailsPARTNERIssue, ExchangeSpecifies whether to include the issuer details with your signature. Set to Yes to include the issuer details.Set to No to exclude the issuer details.com.tivoli.am.fim.sts.saml.2.0. assertion.signature.include. subject.namePARTNERIssue, ExchangeSpecifies whether to include the subject name with your signature. Set to Yes to include the subject name.Set to No to exclude the subject name. com.tivoli.am.fim.sts.saml.2.0. assertion.signature.include. cert.dataPARTNERIssue, ExchangeSpecifies whether to include the certificate data with your signature. Set to Yes to include the certificate data.Set to No to exclude the certificate data. If none of the assertion.signature.include.* properties are set, the system behaves as if com.tivoli.am.fim.sts.saml.2.0.assertion.signature.include.cert.data is set to true.com.tivoli.am.fim.sts.saml.2.0. SignatureAlgorithmPARTNERIssue, ExchangeSpecifies the signature algorithm to use for signing assertions. Valid values:RSA-SHA1, set to http://w ww.w3.org/2000/09/xmldsig#rsa-sha1DSA-SHA1, set to http://w ww.w3.org/2000/09/xmldsig#dsa-sha1RSA-SHA256, set to http:// www.w3.org/2001/04/xmldsig-more#rsa-sha256com.tivoli.am.fim.sts.saml.2.0. DigestAlgorithmPARTNERIssue, ExchangeSpecifies the digest algorithm used to sign SAML messages. Valid values:SHA1, set to http://www.w3.org/2000/09/xmldsig#sha1SHA256, set to http://www.w3.org/2001/04/xmlenc#sha256SHA512, set to http://www.w3.org/2001/04/xmlenc#sha512com.tivoli.am.fim.sts.saml.2.0. EncryptAssertionsPARTNERIssue, ExchangeSpecifies whether assertions are to be encrypted. Set to true to encrypt.Set to false, if no encryption is required..com.tivoli.am.fim.sts.saml.2.0. EncryptionKeyIdentifier.dbPARTNERIssue, ExchangeSpecifies the name of the keystore where the encryption key is stored. For example, use DefaultKeyStore.com.tivoli.am.fim.sts.saml.2.0. EncryptionKeyIdentifier.certPARTNERIssue, ExchangeSpecifies the name of the encryption key. For example, use testkey.com.tivoli.am.fim.sts.saml.2.0. EncryptAllAttributesPARTNERIssue, Exchange Specifies whether all Attribute elements within the assertions are to be encrypted.Set to true to encrypt.Set to false if no encryption is required.com.tivoli.am.fim.sts.saml.2.0. EncryptNameIdentifiersPARTNERIssue, ExchangeSpecifies whether NameID elements in the assertions are to be encrypted.Set to true to encrypt.Set to false if no encryption is required.com.tivoli.am.fim.sts.saml.2.0. BlockEncryptionAlgorithmPARTNERIssue, ExchangeSpecifies the block encryption algorithm.TRIPLEDES, set to http://www.w3.org/2001/04/xmlenc#tripledes-cbcAES-128, set to http://www.w3.org/2001/04/xmlenc#aes128-cbcAES-192, set to http://www.w3.org/2001/04/xmlenc#aes192-cbcAES-256, set to http://www.w3.org/2001/04/xmlenc#aes256-cbccom.tivoli.am.fim.sts.saml.2.0. EncryptionKeyTransportAlgorithmPARTNERIssue, ExchangeSpecifies the key transport algorithm used to encrypt SAML messages. Valid values are:RSA-v1.5, set to http://www.w3.org/2001/04/xmlenc#rsa-1_5RSA-OAEP, set to http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1pcom.tivoli.am.fim.sts.saml.2.0. assertion.SubjectConfirmationMethodSELFIssue, ExchangeSpecifies the subject confirmation method. Valid values: urn:oasis:names:tc:SAML:2.0:cm:bearer urn:oasis:names:tc:SAML:2.0:cm:holder-of-key urn:oasis:names:tc:SAML:2.0:cm:sender-vouches Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.

SAML 2.0 module properties

You can define SAML 2.0 token module self or partner properties.

Table 132. SAML 2.0 module properties

Appliance property
Self or Partner
Mode
Description

com.tivoli.am.fim.sts.saml.2.0.

assertion.replay.validation

SELF
Validate
Specifies whether to enable one-time assertion use enforcement.

Set to true to enable one-time use enforcement.

Set to false if you do not want to enforce one-time asssertion use.

com.tivoli.am.fim.sts.saml.2.0.

assertion.verify.signatures

PARTNER
Validate
Specifies whether to enable signature validation.

Set to true to enable validation.

Set to false if you do not want validation enabled.

com.tivoli.am.fim.sts.saml.2.0.

assertion.signature.use.keyinfo

PARTNER
Validate
Specifies whether to use the KeyInfo of the XML signature to find the X509 certificate for signature validation.

Set to true to use this method. Then, define the com.tivoli.am.fim.sts.saml.2.0.ValidateKeyIdentifier property.

Set to false, otherwise.

com.tivoli.am.fim.sts.saml.2.0.

assertion.keystore.alias

PARTNER
Validate
Specifies whether to use the keystore alias to find the public key for signature validation.

Set to true to use this method. Then, define the com.tivoli.am.fim.sts.saml.2.0.ValidateKeyIdentifier.db and com.tivoli.am.fim.sts.saml.2.0.ValidateKeyIdentifier.cert properties.

Set to false, otherwise.

com.tivoli.am.fim.sts.saml.2.0.

ValidateKeyIdentifier

PARTNER
Validate
Specifies a regular expression to validate the subject distinguished name returned in the KeyInfo, if com.tivoli.am.fim.sts.saml.2.0. assertion.signature.use.keyinfo is set to true.

You can either specify this property or specify both of the following properties:

com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier.db

com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier.cert

If you specify all of these properties, the keystore alias format overwrites the com.tivoli.am.fim.sts.saml.2.0. ValidateKeyIdentifier property.

com.tivoli.am.fim.sts.saml.2.0.

ValidateKeyIdentifier.db

PARTNER
Validate
Specifies the name of the certificate database to use for validation, if com.tivoli.am.fim.sts.saml.2.0.assertion. keystore.alias is set to true.

com.tivoli.am.fim.sts.saml.2.0.

ValidateKeyIdentifier.cert

PARTNER
Validate
Specifies the name of the certificate label for validation, if com.tivoli.am.fim.sts.saml.2.0.assertion.keystore.alias is set to true.

com.tivoli.am.fim.sts.saml.2.0.

DecryptionKeyIdentifier.db

PARTNER
Validation
Specifies the name of the keystore for the decryption key. For example, use DefaultKeyStore.

com.tivoli.am.fim.sts.saml.2.0.

DecryptionKeyIdentifier.cert

PARTNER
Validation
Specifies the name of decryption key. For example, use testkey.

com.tivoli.am.fim.sts.saml.2.0.

WantMultipleAttributeStatements

PARTNER
Validate
Specifies whether to create multiple attribute statements in the Universal User.

If you specify false, multiple attribute statements are arranged into a single group (AttributeList) in the STSUniversalUserdocument. This setting is appropriate for most configurations.

com.tivoli.am.fim.sts.saml.2.0.

map.unknown.alias

PARTNER
Validate
Specifies whether to map unknown name identifiers to the anonymous username.

com.tivoli.am.fim.sts.saml.2.0.

assertion.default.nameidformat

PARTNER
Validate
Specifies the default NameID format for assertion validation. Specify a parameter for use during validation of a SAML assertion. The parameter determines processing rules for the NameID element when one of the following conditions exists:

If there is not an explicit Format attribute included in the assertion.

If the Format attribute is: urn:oasis:names:tc:SAML:1.1: nameid-format:unspecified.

Typically, this parameter is needed only for STS chains that process SAML assertions that do not set the Format attribute. A normal example value is :urn:oasis:names:tc:SAML:1.1: nameid-format:emailAddress

com.tivoli.am.fim.sts.saml.2.0.

assertion.issuer

SELF
Issue, Exchange
Specifies the name of the organization that issues assertions. This is required.

com.tivoli.am.fim.sts.saml.2.0.

assertion.pretime.valid

SELF
Issue, Exchange
Specifies the number of seconds that assertions are valid before its issue date. There is no minimum or maximum value enforced, but a value is required.

Default: 60

com.tivoli.am.fim.sts.saml.2.0.

assertion.posttime.valid

SELF
Issue, Exchange
Specifies the number of seconds that assertions are valid after its issue date. There is no minimum or maximum value enforced, but a value is required.

Default: 60

SAML2.IncludeInclusiveNamespaces
SELF
Issue, Exchange
Specifies whether to use the InclusiveNamespaces construct. This means using exclusive XML canonicalization for greater standardization. You must set this parameter without a prefix.

Set to true or false.

If unset, the system behaves as if it was set to true.

com.tivoli.am.fim.sts.saml.2.0.

assertion.attribute.types

PARTNER
Issue, Exchange
Specifies the types of attributes to include in the assertion.

The default, an asterisk (*), includes all the attribute types that are specified in the identity mapping file.

To specify one or more attribute types individually, enter each attribute type.

Separate multiple type values using &&.

com.tivoli.am.fim.sts.saml.2.0.

assertion.sign

PARTNER
Issue, Exchange
Specifies whether SAML assertions must be signed.

Set to true to sign assertions.

Set to false if signing is not required.

com.tivoli.am.fim.sts.saml.2.0.

SigningKeyIdentifier.db

PARTNER
Issue, Exchange
Specifies the name of the keystore where the signing key is stored. For example, use DefaultKeyStore.

com.tivoli.am.fim.sts.saml.2.0.

signingKeyIdentifier.cert

PARTNER
Issue, Exchange
Specifies the name of the signing key identifier. For example, use testkey.

com.tivoli.am.fim.sts.saml.2.0.

assertion.signature.include.

subject.keyid

PARTNER
Issue, Exchange
Specifies whether to include the subject key identifier with your signature.

Set to true to include the subject key identifier.

Set to false to exclude the subject key identifier.

com.tivoli.am.fim.sts.saml.2.0.

assertion.signature.include.

public.key

PARTNER
Issue, Exchange
Specifies whether to include the public key with your signature.

Set to Yes to include the public key.

Set to No to exclude the public key.

com.tivoli.am.fim.sts.saml.2.0.

assertion.signature.include.

issuer.details

PARTNER
Issue, Exchange
Specifies whether to include the issuer details with your signature.

Set to Yes to include the issuer details.

Set to No to exclude the issuer details.

com.tivoli.am.fim.sts.saml.2.0.

assertion.signature.include.

subject.name

PARTNER
Issue, Exchange
Specifies whether to include the subject name with your signature.

Set to Yes to include the subject name.

Set to No to exclude the subject name.

com.tivoli.am.fim.sts.saml.2.0.

assertion.signature.include.

cert.data

PARTNER
Issue, Exchange
Specifies whether to include the certificate data with your signature.

Set to Yes to include the certificate data.

Set to No to exclude the certificate data.

If none of the assertion.signature.include.* properties are set, the system behaves as if com.tivoli.am.fim.sts.saml.2.0.assertion.signature.include.cert.data is set to true.

com.tivoli.am.fim.sts.saml.2.0.

SignatureAlgorithm

PARTNER
Issue, Exchange
Specifies the signature algorithm to use for signing assertions. Valid values:

RSA-SHA1, set to http://w ww.w3.org/2000/09/xmldsig#rsa-sha1

DSA-SHA1, set to http://w ww.w3.org/2000/09/xmldsig#dsa-sha1

RSA-SHA256, set to http:// www.w3.org/2001/04/xmldsig-more#rsa-sha256

com.tivoli.am.fim.sts.saml.2.0.

DigestAlgorithm

PARTNER
Issue, Exchange
Specifies the digest algorithm used to sign SAML messages. Valid values:

SHA1, set to http://www.w3.org/2000/09/xmldsig#sha1

SHA256, set to http://www.w3.org/2001/04/xmlenc#sha256

SHA512, set to http://www.w3.org/2001/04/xmlenc#sha512

com.tivoli.am.fim.sts.saml.2.0.

EncryptAssertions

PARTNER
Issue, Exchange
Specifies whether assertions are to be encrypted.

Set to true to encrypt.

Set to false, if no encryption is required.

.

com.tivoli.am.fim.sts.saml.2.0.

EncryptionKeyIdentifier.db

PARTNER
Issue, Exchange
Specifies the name of the keystore where the encryption key is stored. For example, use DefaultKeyStore.

com.tivoli.am.fim.sts.saml.2.0.

EncryptionKeyIdentifier.cert

PARTNER
Issue, Exchange
Specifies the name of the encryption key. For example, use testkey.

com.tivoli.am.fim.sts.saml.2.0.

EncryptAllAttributes

PARTNER
Issue, Exchange
Specifies whether all Attribute elements within the assertions are to be encrypted.

Set to true to encrypt.

Set to false if no encryption is required.

com.tivoli.am.fim.sts.saml.2.0.

EncryptNameIdentifiers

PARTNER
Issue, Exchange
Specifies whether NameID elements in the assertions are to be encrypted.

Set to true to encrypt.

Set to false if no encryption is required.

com.tivoli.am.fim.sts.saml.2.0.

BlockEncryptionAlgorithm

PARTNER
Issue, Exchange
Specifies the block encryption algorithm.

TRIPLEDES, set to http://www.w3.org/2001/04/xmlenc#tripledes-cbc

AES-128, set to http://www.w3.org/2001/04/xmlenc#aes128-cbc

AES-192, set to http://www.w3.org/2001/04/xmlenc#aes192-cbc

AES-256, set to http://www.w3.org/2001/04/xmlenc#aes256-cbc

com.tivoli.am.fim.sts.saml.2.0.

EncryptionKeyTransportAlgorithm

PARTNER
Issue, Exchange
Specifies the key transport algorithm used to encrypt SAML messages. Valid values are:

RSA-v1.5, set to http://www.w3.org/2001/04/xmlenc#rsa-1_5

RSA-OAEP, set to http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

com.tivoli.am.fim.sts.saml.2.0.

assertion.SubjectConfirmationMethod

SELF
Issue, Exchange
Specifies the subject confirmation method. Valid values:

urn:oasis:names:tc:SAML:2.0:cm:bearer

urn:oasis:names:tc:SAML:2.0:cm:holder-of-key

urn:oasis:names:tc:SAML:2.0:cm:sender-vouches

Parent topic: Token module properties

Username module propertiesUsername module propertiesUsername module propertiesYou can define Username module self or partner properties. Username modulepropertiespropertiesUsername module Username module propertiesAppliance propertySelf or PartnerModeDescriptionusername.password.optionsPARTNER, SELFIssueSpecifies the option for including the password in the token:2Include the digest of the password value3Include the password in clear text 4 Do not include the password Default value is 4.username.add.nonceSELFIssueSpecifies whether to include the nonce (random bits used for obfuscating the element) in the token. The default is true.Set to true to include a nonce in the token. Set to false to exclude the nonce.When you specify to issue no password, this value is ineffective.username.add.timestampSELFIssueSpecifies whether to include creation time, or timestamp, in the token. The default is true.Set to true to add the timestamp. Set to false to exclude the timestamp.username.password.validatorSELFValidateSpecifies the user registry option to use. Valid values are:ISAMRTE, for the Access Manager runtime optionTAMRD, for the Access Manager user registry optionLDAP, for the non-Access Manager user registry optionusername.skip.password.validationSELFValidateSpecifies whether to disable password validation. The default is false.Set to true to skip validation.Set to false to enable validation.username.server.connection.idSELFValidateIf TAMRD is specified for username.password.validator, specify the server connection ID. This is the name of the previously configured server connection which holds the settings for the Access Manager LDAP registry.This property is required if password validation is not skipped.username.tamrd.management.domainSELFValidateIf TAMRD is specified for username.password.validator, specify the Access Manager management domain. The default is Default.username.tamrd.login.failures.persistentSELFValidateIf TAMRD is specified for username.password.validator, specify if log in failures are persistent. The default is false.Set to true to persist the failures.Set to false to not persist.username.tamrd.maximum.server.connectionsSELFValidateIf TAMRD is specified for username.password.validator, specify the maximum number of server connections that are allowed. The default is 16.username.rte.bind.dnSELFValidateIf ISAMRTE is specified for username.password.validator, specify the username used to authenticate to the primary LDAP server.For example, cn=SecurityMaster,secAuthority=Default.username.rte.bind.pwdSELFValidateIf ISAMRTE is specified for username.password.validator, specify the password used to authenticate to the primary LDAP server.username.rte.enableSSLSELFValidateSpecifies whether to enable SSL. The default is false. Set to true to enable SSL. Then, define the username.rte.sslTrustStore property. Set to false to disable SSL.username.rte.sslTrustStoreSELFValidateSpecifies the name of the certificate database to use for the SSL connection, if username.rte.enableSSL is set to true.username.ldap.server.connection.idSELFValidateIf LDAP is specified for username.password.validator, specify the name of the server connection that holds the required LDAP settings to access the LDAP user registry. For example, my-isam-user-registry. username.ldap.maximum.server.connectionsSELFValidateIf LDAP is specified for username.password.validator, specify the maximum number of connections to make to the LDAP user registry. For example, 16.username.ldap.base.dn SELFValidateIf LDAP is specified for username.password.validator, specify an LDAP base DN to search. For example, dn o=ibm,c=us.username.ldap.search.filterSELFValidateIf LDAP is specified for username.password.validator, specify an LDAP search filter. For example, ((objectClass=ePerson)(objectClass=Person)).username.ldap.user.id.attributeSELFValidateIf LDAP is specified for username.password.validator, specify an LDAP attribute that stores the username. The LDAP attribute must uniquely identify a user. For example, uid.username.validate.freshnessPARTNERValidateEnables the time validity check, based on created time and the amount of time permitted after the issue. The default is true.Set to true to validate freshness.Set to false for no validation.If this property is not set, then the value of the property username.freshness.limit is checked to see if the time validation check needs to be performed.username.freshness.limitPARTNERValidateSpecifies, in seconds, the amount of time the Username token is valid after being issued.Default: 300 secondsA value of -1 means that the token does not expire. Token module propertiesConfigure token modules so that it contains the appropriate values for your environment.

Username module properties

You can define Username module self or partner properties.

Table 133. Username module properties

Appliance property
Self or Partner
Mode
Description

username.password.options
PARTNER, SELF
Issue
Specifies the option for including the password in the token:

2

Include the digest of the password value

3

Include the password in clear text

4

Do not include the password

Default value is 4.

username.add.nonce
SELF
Issue
Specifies whether to include the nonce (random bits used for obfuscating the element) in the token. The default is true.

Set to true to include a nonce in the token.

Set to false to exclude the nonce.

When you specify to issue no password, this value is ineffective.

username.add.timestamp
SELF
Issue
Specifies whether to include creation time, or timestamp, in the token. The default is true.

Set to true to add the timestamp.

Set to false to exclude the timestamp.

username.password.validator
SELF
Validate
Specifies the user registry option to use. Valid values are:

ISAMRTE, for the Access Manager runtime option

TAMRD, for the Access Manager user registry option

LDAP, for the non-Access Manager user registry option

username.skip.password.validation
SELF
Validate
Specifies whether to disable password validation. The default is false.

Set to true to skip validation.

Set to false to enable validation.

username.server.connection.id
SELF
Validate
If TAMRD is specified for username.password.validator, specify the server connection ID. This is the name of the previously configured server connection which holds the settings for the Access Manager LDAP registry.

This property is required if password validation is not skipped.

username.tamrd.management.domain
SELF
Validate
If TAMRD is specified for username.password.validator, specify the Access Manager management domain. The default is Default.

username.tamrd.login.failures.persistent
SELF
Validate
If TAMRD is specified for username.password.validator, specify if log in failures are persistent. The default is false.

Set to true to persist the failures.

Set to false to not persist.

username.tamrd.maximum.server.connections
SELF
Validate
If TAMRD is specified for username.password.validator, specify the maximum number of server connections that are allowed. The default is 16.

username.rte.bind.dn
SELF
Validate
If ISAMRTE is specified for username.password.validator, specify the username used to authenticate to the primary LDAP server.

For example, cn=SecurityMaster,secAuthority=Default.

username.rte.bind.pwd
SELF
Validate
If ISAMRTE is specified for username.password.validator, specify the password used to authenticate to the primary LDAP server.

username.rte.enableSSL
SELF
Validate
Specifies whether to enable SSL. The default is false. Set to true to enable SSL. Then, define the username.rte.sslTrustStore property. Set to false to disable SSL.

username.rte.sslTrustStore
SELF
Validate
Specifies the name of the certificate database to use for the SSL connection, if username.rte.enableSSL is set to true.

username.ldap.server.connection.id
SELF
Validate
If LDAP is specified for username.password.validator, specify the name of the server connection that holds the required LDAP settings to access the LDAP user registry. For example, my-isam-user-registry.

username.ldap.maximum.server.connections
SELF
Validate
If LDAP is specified for username.password.validator, specify the maximum number of connections to make to the LDAP user registry. For example, 16.

username.ldap.base.dn
SELF
Validate
If LDAP is specified for username.password.validator, specify an LDAP base DN to search. For example, dn o=ibm,c=us.

username.ldap.search.filter
SELF
Validate
If LDAP is specified for username.password.validator, specify an LDAP search filter. For example, ((objectClass=ePerson)(objectClass=Person)).

username.ldap.user.id.attribute
SELF
Validate
If LDAP is specified for username.password.validator, specify an LDAP attribute that stores the username. The LDAP attribute must uniquely identify a user. For example, uid.

username.validate.freshness
PARTNER
Validate
Enables the time validity check, based on created time and the amount of time permitted after the issue. The default is true.

Set to true to validate freshness.

Set to false for no validation.

If this property is not set, then the value of the property username.freshness.limit is checked to see if the time validation check needs to be performed.

username.freshness.limit
PARTNER
Validate
Specifies, in seconds, the amount of time the Username token is valid after being issued.

Default: 300 seconds

A value of -1 means that the token does not expire.

Parent topic: Token module properties

STSRequest and STSResponse access using a JavaScript mapping ruleBy using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects.The following two implicit objects and the classes required by these two objects can be exposed (for example, Java DOM, XML classes, and so on):STSRequest which represents the WS-Trust requestSTSResponse, which represents the WS-Trust responseUse JavaScript code stsrequest.getRequestSecurityToken().getBase() to get the input security token from the WS-Trust request. This returns the input security token as an instance of the Java class org.w3c.dom.Element. Use JavaScript code stsresponse.getRequestSecurityTokenResponse().setRequestedSecurityToken (outputSecurityToken) to set the output security token in the WS-Trust response. The outputSecurityToken is the output security token represented as an instance of Java class org.w3c.dom.Element. By default, WS-Trust response contains only one output security token. To return additional output security tokens, you can use the following JavaScript code: stsresponse.addRequestSecurityTokenResponse().setRequestedSecurityToken(outputSecurityToken)The examples in the following topics show the mapping to and from a JSON web token (JWT). They use the Default Mapping module with a JavaScript mapping rule. The JavaScript mapping rule accesses the STSRequest and STSResponse objects and performs the identity mapping. Configuring STS modulesConfigure Security Token Service (STS) modules to validate and exchange security token types.Mapping a JSON Web Token to a SAML2 token exampleYou can map a JSON Web Token (JWT) to a SAML 2 token by using a JavaScript mapping rule.Mapping a SAML2 token to a JSON Web Token exampleYou can map a SAML 2 token to a JSON Web Token (JWT) by using a JavaScript mapping rule.

STSRequest and STSResponse access using a JavaScript mapping rule

By using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects.

The following two implicit objects and the classes required by these two objects can be exposed (for example, Java DOM, XML classes, and so on):

STSRequest which represents the WS-Trust request

STSResponse, which represents the WS-Trust response

Use JavaScript code stsrequest.getRequestSecurityToken().getBase() to get the input security token from the WS-Trust request. This returns the input security token as an instance of the Java class org.w3c.dom.Element.

Use JavaScript code stsresponse.getRequestSecurityTokenResponse().setRequestedSecurityToken (outputSecurityToken) to set the output security token in the WS-Trust response. The outputSecurityToken is the output security token represented as an instance of Java class org.w3c.dom.Element. By default, WS-Trust response contains only one output security token. To return additional output security tokens, you can use the following JavaScript code:

 stsresponse.addRequestSecurityTokenResponse().setRequestedSecurityToken(outputSecurityToken)

The examples in the following topics show the mapping to and from a JSON web token (JWT). They use the Default Mapping module with a JavaScript mapping rule. The JavaScript mapping rule accesses the STSRequest and STSResponse objects and performs the identity mapping.

Mapping a JSON Web Token to a SAML2 token example
You can map a JSON Web Token (JWT) to a SAML 2 token by using a JavaScript mapping rule.

Mapping a SAML2 token to a JSON Web Token example
You can map a SAML 2 token to a JSON Web Token (JWT) by using a JavaScript mapping rule.

Parent topic: Configuring STS modules

Mapping a JSON Web Token to a SAML2 token exampleYou can map a JSON Web Token (JWT) to a SAML 2 token by using a JavaScript mapping rule.The steps show an end-to-end JWT to SAML2 mapping. STSRequest and STSResponse access using a JavaScript mapping ruleBy using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects. provides a description of this support.Create a JavaScript mapping rule by using the local management interface.Select Secure FederationGlobal SettingsMapping Rules.Click Add.In the Content field, copy and paste the following code: importClass(com.tivoli.am.fim.base64.BASE64Utility); importClass(com.tivoli.am.fim.trustserver.sts.uuser.Attribute); var jwtElement = stsrequest.getRequestSecurityToken().getBase(); var jwtText = jwtElement.getTextContent(); var jwtString = new java.lang.String(BASE64Utility.decode(jwtText), "UTF-8"); var jwt = JSON.parse(jwtString); for (var name in jwt) { if (jwt.hasOwnProperty(name)) { if ("sub".equals(name)) { stsuu.addPrincipalAttribute(new Attribute("name", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", jwt[name])); } else { stsuu.addAttribute(new Attribute(name, "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", jwt[name])); } } }In the Name field, enter jwt_saml.In the Category field, select SAML2_0.Click Save and deploy the changes.Assemble the Security Token Service (STS) template.Select Secure FederationManageSecurity Token Service.Click Templates.Click Add and name the template JWT to SAML2. Click OK.Select the JWT to SAML2 template and add the Default Map Module in Map mode and a Default SAML 2.0 token in Issue mode.Save and deploy the changes.Create an STS chain that references the mapping rule and template you created in the previous steps.Within the Security Token Service panel, select Module Chains.Click Add to create the module chain, with the following values:JWT to SAML2 module chain valuesTab: FieldValueOverview: NameJWT to SAML2Overview: DescriptionJSON Web Token to SAML2 conversion STS chainOverview: TemplateJWT to SAML2Lookup: Request TypeValidateLookup: Applies to AddressjwtappliestoLookup: Issuer AddressjwtissuerProperties: Default Map Module (JavaScript file containing the identity mapping rulejwt_samlProperties: Default SAML 2.0 Token (Name of the organization issuing the assertions)isamProperties: Default SAML 2.0 Token (Amount of time before the issue date that an assertion is considered valid)60Properties: Default SAML 2.0 Token (Amount of time that the assertion is valid after being issued)60Properties: Default SAML 2.0 Token (List of attribute types to include)*Use the defaults for all of the fields that are not specified in the table.Save and deploy the changes.Use curl to test the chain.Send the following WS-Trust 1.2 message:<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <ns1:RequestSecurityToken xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wst:RequestType xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType> <wst:Issuer xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">jwtissuer</wsa:Address> </wst:Issuer> <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"> <wsa:Address>jwtappliesto</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:Base xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <JWT>ewogICJlbWFpbCI6ICJqb2huLmRvZUBleGFtcGxlLmNvbSIsIAogICJmYW1pbHlfbmFtZSI6ICJkb2UiLCAK ICAiZ2l2ZW5fbmFtZSI6ICJqb2huIiwgCiAgImlzcyI6ICJpc2FtIiwgCiAgInN1YiI6ICIwMTIzNDU2Nzg5Igp9</JWT> </wst:Base> </ns1:RequestSecurityToken> </SOAP-ENV:Body> </SOAP-ENV:Envelope> The bold embedded element, <JWT> </JWT>, is the input to the chain. The JWT is a Base64 encoded JSON Web Token that contains the following data: { "email": "john.doe@example.com", "family_name": "doe", "given_name": "john", "iss": "isam", "sub": "0123456789" }Save this file as jwt.xml.Run the following curl command, where jwt.xml is the WS-Trust 1.2 message:curl -k -v -u "easuser:passw0rd" -H "Content-Type: text/xml" --data-binary @jwt.xml https://ip-rte/TrustServer/SecurityTokenService The following results are returned:<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"></SOAP-ENV:Header> <soap:Body> <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="uuidc1288a62-0153-1f8b-bf2a-b4c46f51cd03"> <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <wsa:EndpointReference> <wsa:Address>jwtappliesto</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:Lifetime xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wsu:Created>2016-03-29T06:56:13Z</wsu:Created> <wsu:Expires>2016-03-29T06:57:13Z</wsu:Expires> </wst:Lifetime> <wst:RequestedSecurityToken> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ID="Assertion-uuidc1288ae8-0153-10bd-b7ef-b4c46f51cd03" IssueInstant="2016-03-29T06:56:13Z" Version="2.0"> <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">isam</saml:Issuer> <saml:Subject> <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"> 0123456789</saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData NotOnOrAfter="2016-03-29T06:57:13Z"></saml:SubjectConfirmationData> </saml:SubjectConfirmation> </saml:Subject> <saml:Conditions NotBefore="2016-03-29T06:55:13Z" NotOnOrAfter="2016-03-29T06:57:13Z"> <saml:AudienceRestriction> <saml:Audience>jwtappliesto</saml:Audience> </saml:AudienceRestriction> </saml:Conditions> <saml:AuthnStatement AuthnInstant="2016-03-29T06:56:13Z"> <saml:AuthnContext> <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password </saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement> <saml:Attribute Name="given_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">john</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">john.doe@example.com</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="iss" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">isam</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="family_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">doe</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion> </wst:RequestedSecurityToken> The JWT token is mapped into the SAML assertion, as shown by the previous bold text. The attributes in the SAML2 assertion are mapped from JWT attributes.<wst:RequestedAttachedReference xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wss:SecurityTokenReference xmlns:wss11="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" wss11:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"> <wss:KeyIdentifier xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID"> Assertion-uuidc1288ae8-0153-10bd-b7ef-b4c46f51cd03</wss:KeyIdentifier> </wss:SecurityTokenReference> </wst:RequestedAttachedReference> <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType> <wst:Status> <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid</wst:Code> </wst:Status> </wst:RequestSecurityTokenResponse> </wst:RequestSecurityTokenResponseCollection> </soap:Body> </soap:Envelope>Mapping a SAML2 token to a JSON Web Token exampleYou can map a SAML 2 token to a JSON Web Token (JWT) by using a JavaScript mapping rule.STSRequest and STSResponse access using a JavaScript mapping ruleBy using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects.

Mapping a JSON Web Token to a SAML2 token example

You can map a JSON Web Token (JWT) to a SAML 2 token by using a JavaScript mapping rule.

About this task

The steps show an end-to-end JWT to SAML2 mapping. STSRequest and STSResponse access using a JavaScript mapping rule provides a description of this support.

Procedure

Create a JavaScript mapping rule by using the local management interface.

Select Secure Federation > Global Settings > Mapping Rules.

Click Add.

In the Content field, copy and paste the following code:

    importClass(com.tivoli.am.fim.base64.BASE64Utility);
    importClass(com.tivoli.am.fim.trustserver.sts.uuser.Attribute);

    var jwtElement = stsrequest.getRequestSecurityToken().getBase();
    var jwtText    = jwtElement.getTextContent();
    var jwtString  = new java.lang.String(BASE64Utility.decode(jwtText), "UTF-8");
    var jwt        = JSON.parse(jwtString);

    for (var name in jwt) {
      if (jwt.hasOwnProperty(name)) {
        if ("sub".equals(name)) {
          stsuu.addPrincipalAttribute(new Attribute("name", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", jwt[name]));
        } else {
          stsuu.addAttribute(new Attribute(name, "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", jwt[name]));
        }
      }
    }

In the Name field, enter jwt_saml.

In the Category field, select SAML2_0.

Click Save and deploy the changes.

Assemble the Security Token Service (STS) template.

Select Secure Federation > Manage > Security Token Service.

Click Templates.

Click Add and name the template JWT to SAML2. Click OK.

Select the JWT to SAML2 template and add the Default Map Module in Map mode and a Default SAML 2.0 token in Issue mode.

Save and deploy the changes.

Create an STS chain that references the mapping rule and template you created in the previous steps.

Within the Security Token Service panel, select Module Chains.

Click Add to create the module chain, with the following values:

Table 134. JWT to SAML2 module chain values

Tab: Field | Value
Overview: Name | JWT to SAML2
Overview: Description | JSON Web Token to SAML2 conversion STS chain
Overview: Template | JWT to SAML2
Lookup: Request Type | Validate
Lookup: Applies to Address | jwtappliesto
Lookup: Issuer Address | jwtissuer
Properties: Default Map Module (JavaScript file containing the identity mapping rule | jwt_saml
Properties: Default SAML 2.0 Token (Name of the organization issuing the assertions) | isam
Properties: Default SAML 2.0 Token (Amount of time before the issue date that an assertion is considered valid) | 60
Properties: Default SAML 2.0 Token (Amount of time that the assertion is valid after being issued) | 60
Properties: Default SAML 2.0 Token (List of attribute types to include) | *

Use the defaults for all of the fields that are not specified in the table.

Save and deploy the changes.

Use curl to test the chain.

Send the following WS-Trust 1.2 message:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns1:RequestSecurityToken xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wst:RequestType xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType>
      <wst:Issuer xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
        <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">jwtissuer</wsa:Address>
      </wst:Issuer>
      <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
          <wsa:Address>jwtappliesto</wsa:Address>
        </wsa:EndpointReference>
      </wsp:AppliesTo>
      <wst:Base xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
<JWT>ewogICJlbWFpbCI6ICJqb2huLmRvZUBleGFtcGxlLmNvbSIsIAogICJmYW1pbHlfbmFtZSI6ICJkb2UiLCAK
ICAiZ2l2ZW5fbmFtZSI6ICJqb2huIiwgCiAgImlzcyI6ICJpc2FtIiwgCiAgInN1YiI6ICIwMTIzNDU2Nzg5Igp9</JWT>
      </wst:Base>
    </ns1:RequestSecurityToken>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The bold embedded element, <JWT> </JWT>, is the input to the chain. The JWT is a Base64 encoded JSON Web Token that contains the following data:

{
 "email": "john.doe@example.com",
  "family_name": "doe",
  "given_name": "john",
  "iss": "isam",
  "sub": "0123456789"
}

Save this file as jwt.xml.

Run the following curl command, where jwt.xml is the WS-Trust 1.2 message:

curl -k -v -u "easuser:passw0rd" -H "Content-Type: text/xml" --data-binary
@jwt.xml https://ip-rte/TrustServer/SecurityTokenService

The following results are returned:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"></SOAP-ENV:Header>
    <soap:Body>
        <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
            <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            wsu:Id="uuidc1288a62-0153-1f8b-bf2a-b4c46f51cd03">
                <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
                    <wsa:EndpointReference>
                        <wsa:Address>jwtappliesto</wsa:Address>
                    </wsa:EndpointReference>
                </wsp:AppliesTo>
                <wst:Lifetime xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
                    <wsu:Created>2016-03-29T06:56:13Z</wsu:Created>
                    <wsu:Expires>2016-03-29T06:57:13Z</wsu:Expires>
                </wst:Lifetime>
               <wst:RequestedSecurityToken>
                    <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ID="Assertion-uuidc1288ae8-0153-10bd-b7ef-b4c46f51cd03"
                    IssueInstant="2016-03-29T06:56:13Z" Version="2.0">
                        <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">isam</saml:Issuer>
                        <saml:Subject>
                            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
                            0123456789</saml:NameID>
                            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                                <saml:SubjectConfirmationData NotOnOrAfter="2016-03-29T06:57:13Z"></saml:SubjectConfirmationData>
                            </saml:SubjectConfirmation>
                        </saml:Subject>
                        <saml:Conditions NotBefore="2016-03-29T06:55:13Z" NotOnOrAfter="2016-03-29T06:57:13Z">
                            <saml:AudienceRestriction>
                                <saml:Audience>jwtappliesto</saml:Audience>
                            </saml:AudienceRestriction>
                        </saml:Conditions>
                        <saml:AuthnStatement AuthnInstant="2016-03-29T06:56:13Z">
                            <saml:AuthnContext>
                                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password
                                </saml:AuthnContextClassRef>
                            </saml:AuthnContext>
                        </saml:AuthnStatement>
                        <saml:AttributeStatement>
                            <saml:Attribute Name="given_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                                <saml:AttributeValue xsi:type="xs:string">john</saml:AttributeValue>
                            </saml:Attribute>
                            <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                                <saml:AttributeValue xsi:type="xs:string">john.doe@example.com</saml:AttributeValue>
                            </saml:Attribute>
                            <saml:Attribute Name="iss" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                                <saml:AttributeValue xsi:type="xs:string">isam</saml:AttributeValue>
                            </saml:Attribute>
                            <saml:Attribute Name="family_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                                <saml:AttributeValue xsi:type="xs:string">doe</saml:AttributeValue>
                            </saml:Attribute>
                        </saml:AttributeStatement>
                    </saml:Assertion>
                </wst:RequestedSecurityToken>

The JWT token is mapped into the SAML assertion, as shown by the previous bold text. The attributes in the SAML2 assertion are mapped from JWT attributes.

<wst:RequestedAttachedReference xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
                    <wss:SecurityTokenReference xmlns:wss11="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd"
                    wss11:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0">
                        <wss:KeyIdentifier xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                        xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
                        ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">
                        Assertion-uuidc1288ae8-0153-10bd-b7ef-b4c46f51cd03</wss:KeyIdentifier>
                    </wss:SecurityTokenReference>
                </wst:RequestedAttachedReference>
                <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType>
                <wst:Status>
                    <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid</wst:Code>
                </wst:Status>
            </wst:RequestSecurityTokenResponse>
        </wst:RequestSecurityTokenResponseCollection>
    </soap:Body>
</soap:Envelope>

Parent topic: STSRequest and STSResponse access using a JavaScript mapping rule

Related tasks:

Mapping a SAML2 token to a JSON Web Token example

Mapping a SAML2 token to a JSON Web Token exampleYou can map a SAML 2 token to a JSON Web Token (JWT) by using a JavaScript mapping rule.The steps show an end-to-end SAML to JWT mapping. STSRequest and STSResponse access using a JavaScript mapping ruleBy using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects. provides a description of this support.Create a JavaScript mapping rule using the local management interface.Select Secure FederationGlobal SettingsMapping Rules.Click Add.In the Content field, copy and paste the following code: importClass(com.tivoli.am.fim.base64.BASE64Utility); importClass(com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils) var jwt = {}; var it = stsuu.getPrincipalAttributes(); var jt = stsuu.getAttributes(); while (it.hasNext()) { var attribute = it.next(); var name = new String(attribute.getName()); var value = new String(attribute.getValues()[0]); if ("name".equals(name)) { jwt["sub"] = value; } else { jwt[name] = value; } } while (jt.hasNext()) { var attribute = jt.next(); var name = new String(attribute.getName()); var value = new String(attribute.getValues()[0]); jwt[name] = value; } var document = IDMappingExtUtils.newXMLDocument(); var jwtString = JSON.stringify(jwt); var jwtText = document.createTextNode(BASE64Utility.encode((new java.lang.String(jwtString)).getBytes("UTF-8"))); var jwtElement = document.createElement("JWT"); jwtElement.appendChild(jwtText); stsresponse.getRequestSecurityTokenResponse().setRequestedSecurityToken(jwtElement);In the Name field, enter saml_jwt.In the Category field, select SAML2_0.Click Save and deploy the changes.Assemble the Security Token Service (STS) template.Select Secure FederationManageSecurity Token Service.Click Templates.Click Add and name the template SAML2 to JWT. Click OK.Select the SAML2 to JWT template and add the Default SAML 2.0 Token in Validate mode and a Default Map Module in Map mode.Save and deploy the changes.Create an STS chain that references the mapping rule and template you created in the previous steps.Within the Security Token Service panel, select Module Chains.Click Add to create a module chain, with the following values:SAML2 to JWT module chain valuesTab: FieldValueOverview: NameSAML2 to JWTOverview: DescriptionSAML2 to JSON Web Token conversion STS chainOverview: TemplateSAML2 to JWTLookup: Request TypeValidateLookup: Applies to AddressSAML2_AppliesToLookup: Issuer AddressSAML2_IssuerProperties: Default Map Module (JavaScript file containing the identity mapping rulesaml_jwtUse the defaults for all of the fields not in the table.Save and deploy the changes.Use curl to test the chain.Send the following WS-Trust 1.2 message:<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <ns1:RequestSecurityToken xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wst:RequestType xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType> <wst:Issuer xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">SAML2_Issuer</wsa:Address> </wst:Issuer> <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"> <wsa:Address>SAML2_AppliesTo</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:Base xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ID="Assertion-uuidbcb46a39-0153-1337-8efa-fec506fb7461" IssueInstant="2016-03-28T10:10:53Z" Version="2.0"> <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">isam</saml:Issuer> <saml:Subject> <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">0123456789</saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData NotOnOrAfter="2016-03-28T10:11:53Z"/> </saml:SubjectConfirmation> </saml:Subject> <saml:Conditions NotBefore="2016-03-28T10:09:53Z" NotOnOrAfter="2016-03-29T10:11:53Z"> <saml:AudienceRestriction> <saml:Audience>jwt_saml</saml:Audience> </saml:AudienceRestriction> </saml:Conditions> <saml:AuthnStatement AuthnInstant="2016-03-28T10:10:53Z"> <saml:AuthnContext> <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement> <saml:Attribute Name="given_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">john</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">john.doe@example.com</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="iss" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">isam</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="family_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml:AttributeValue xsi:type="xs:string">doe</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion> </wst:Base> </ns1:RequestSecurityToken> </SOAP-ENV:Body> </SOAP-ENV:Envelope> The bold element in the SAML2 assertion will be mapped to the JWT attributes in the result.Save this file as saml2.xml.Run the following curl command, where saml2.xml is the WS-Trust 1.2 message:curl -k -v -u "easuser:passw0rd" -H "Content-Type: text/xml" --data-binary @saml2.xml https://ip-rte/TrustServer/SecurityTokenService The following results are returned:<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"></SOAP-ENV:Header> <soap:Body> <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"> <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="uuidc1676e30-0153-16a8-86b5-c34fd1aca7a8"> <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"> <wsa:EndpointReference> <wsa:Address>SAML2_AppliesTo</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wst:RequestedSecurityToken> <JWT>eyJzdWIiOiIwMTIzNDU2Nzg5IiwiZ2l2ZW5fbmFtZSI6ImpvaG4iLCJOb3RPbk9yQWZ0ZXIiOiIyMDE2LTAz LTI5VDEwOjExOjUzWiIsIkF1dGhlbnRpY2F0aW9uTWV0aG9kIjoidXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6MS4w OmFtOnBhc3N3b3JkIiwiZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsIkF1ZGllbmNlUmVzdHJpY3Rpb25 Db25kaXRpb24uQXVkaWVuY2UiOiJqd3Rfc2FtbCIsImlzcyI6ImlzYW0iLCJJc3N1ZUluc3RhbnQiOiIyMDE2LT AzLTI4VDEwOjEwOjUzWiIsImZhbWlseV9uYW1lIjoiZG9lIiwiTm90QmVmb3JlIjoiMjAxNi0wMy0yOFQxMDowO To1M1oiLCJBdXRoZW50aWNhdGlvbkluc3RhbnQiOiIyMDE2LTAzLTI4VDEwOjEwOjUzWiIsImlzc3VlciI6Iml zYW0ifQ==</JWT> </wst:RequestedSecurityToken> <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType> <wst:Status> <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid</wst:Code> </wst:Status> </wst:RequestSecurityTokenResponse> </wst:RequestSecurityTokenResponseCollection> </soap:Body> </soap:Envelope>The bold embedded element, <JWT> </JWT>) , is the result in a Base64 encoded JSON Web Token:{ "sub": "0123456789", "given_name": "john", "NotOnOrAfter": "2016-03-29T10:11:53Z", "AuthenticationMethod": "urn:oasis:names:tc:SAML:1.0:am:password", "email": "john.doe@example.com", "AudienceRestrictionCondition.Audience": "jwt_saml", "iss": "isam", "IssueInstant": "2016-03-28T10:10:53Z", "family_name": "doe", "NotBefore": "2016-03-28T10:09:53Z", "AuthenticationInstant": "2016-03-28T10:10:53Z", "issuer": "isam“ }Mapping a JSON Web Token to a SAML2 token exampleYou can map a JSON Web Token (JWT) to a SAML 2 token by using a JavaScript mapping rule.STSRequest and STSResponse access using a JavaScript mapping ruleBy using the Default Mapping STS Module and a JavaScript mapping rule, you can perform identity mapping. The mapping rule can access STSRequest and STSResponse objects.

Mapping a SAML2 token to a JSON Web Token example

You can map a SAML 2 token to a JSON Web Token (JWT) by using a JavaScript mapping rule.

About this task

The steps show an end-to-end SAML to JWT mapping. STSRequest and STSResponse access using a JavaScript mapping rule provides a description of this support.

Procedure

Create a JavaScript mapping rule using the local management interface.

Select Secure Federation > Global Settings > Mapping Rules.

Click Add.

In the Content field, copy and paste the following code:

    importClass(com.tivoli.am.fim.base64.BASE64Utility);
    importClass(com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils)

    var jwt = {};

    var it = stsuu.getPrincipalAttributes();
    var jt = stsuu.getAttributes();

    while (it.hasNext()) {
      var attribute = it.next();
      var name      = new String(attribute.getName());
      var value     = new String(attribute.getValues()[0]);

      if ("name".equals(name)) {
        jwt["sub"] = value;
      } else {
        jwt[name] = value;
      }
    }

    while (jt.hasNext()) {
      var attribute = jt.next();
      var name      = new String(attribute.getName());
      var value     = new String(attribute.getValues()[0]);

      jwt[name] = value;
    }

    var document   = IDMappingExtUtils.newXMLDocument();
    var jwtString  = JSON.stringify(jwt);
    var jwtText    = document.createTextNode(BASE64Utility.encode((new java.lang.String(jwtString)).getBytes("UTF-8")));
    var jwtElement = document.createElement("JWT");

    jwtElement.appendChild(jwtText);

    stsresponse.getRequestSecurityTokenResponse().setRequestedSecurityToken(jwtElement);

In the Name field, enter saml_jwt.

In the Category field, select SAML2_0.

Click Save and deploy the changes.

Assemble the Security Token Service (STS) template.

Select Secure Federation > Manage > Security Token Service.

Click Templates.

Click Add and name the template SAML2 to JWT. Click OK.

Select the SAML2 to JWT template and add the Default SAML 2.0 Token in Validate mode and a Default Map Module in Map mode.

Save and deploy the changes.

Create an STS chain that references the mapping rule and template you created in the previous steps.

Within the Security Token Service panel, select Module Chains.

Click Add to create a module chain, with the following values:

Table 135. SAML2 to JWT module chain values

Tab: Field | Value
Overview: Name | SAML2 to JWT
Overview: Description | SAML2 to JSON Web Token conversion STS chain
Overview: Template | SAML2 to JWT
Lookup: Request Type | Validate
Lookup: Applies to Address | SAML2_AppliesTo
Lookup: Issuer Address | SAML2_Issuer
Properties: Default Map Module (JavaScript file containing the identity mapping rule | saml_jwt

Use the defaults for all of the fields not in the table.

Save and deploy the changes.

Use curl to test the chain.

Send the following WS-Trust 1.2 message:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns1:RequestSecurityToken xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wst:RequestType xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType>
      <wst:Issuer xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
        <wsa:Address xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">SAML2_Issuer</wsa:Address>
      </wst:Issuer>
      <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsa:EndpointReference xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
          <wsa:Address>SAML2_AppliesTo</wsa:Address>
        </wsa:EndpointReference>
      </wsp:AppliesTo>
<wst:Base xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
        <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
        xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        ID="Assertion-uuidbcb46a39-0153-1337-8efa-fec506fb7461" IssueInstant="2016-03-28T10:10:53Z" Version="2.0">
          <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">isam</saml:Issuer>
          <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">0123456789</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
              <saml:SubjectConfirmationData NotOnOrAfter="2016-03-28T10:11:53Z"/>
            </saml:SubjectConfirmation>
          </saml:Subject>
          <saml:Conditions NotBefore="2016-03-28T10:09:53Z" NotOnOrAfter="2016-03-29T10:11:53Z">
            <saml:AudienceRestriction>
              <saml:Audience>jwt_saml</saml:Audience>
            </saml:AudienceRestriction>
          </saml:Conditions>
          <saml:AuthnStatement AuthnInstant="2016-03-28T10:10:53Z">
            <saml:AuthnContext>
              <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
            </saml:AuthnContext>
          </saml:AuthnStatement>
          <saml:AttributeStatement>
            <saml:Attribute Name="given_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
              <saml:AttributeValue xsi:type="xs:string">john</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
              <saml:AttributeValue xsi:type="xs:string">john.doe@example.com</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="iss" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
              <saml:AttributeValue xsi:type="xs:string">isam</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="family_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
              <saml:AttributeValue xsi:type="xs:string">doe</saml:AttributeValue>
            </saml:Attribute>
          </saml:AttributeStatement>
        </saml:Assertion>
      </wst:Base>
    </ns1:RequestSecurityToken>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The bold element in the SAML2 assertion will be mapped to the JWT attributes in the result.

Save this file as saml2.xml.

Run the following curl command, where saml2.xml is the WS-Trust 1.2 message:

curl -k -v -u "easuser:passw0rd" -H "Content-Type: text/xml" --data-binary
@saml2.xml https://ip-rte/TrustServer/SecurityTokenService

The following results are returned:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"></SOAP-ENV:Header>
    <soap:Body>
        <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
            <wst:RequestSecurityTokenResponse
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            wsu:Id="uuidc1676e30-0153-16a8-86b5-c34fd1aca7a8">
                <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing"
                xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
                    <wsa:EndpointReference>
                        <wsa:Address>SAML2_AppliesTo</wsa:Address>
                    </wsa:EndpointReference>
                </wsp:AppliesTo>
                <wst:RequestedSecurityToken>
                <JWT>eyJzdWIiOiIwMTIzNDU2Nzg5IiwiZ2l2ZW5fbmFtZSI6ImpvaG4iLCJOb3RPbk9yQWZ0ZXIiOiIyMDE2LTAz
                LTI5VDEwOjExOjUzWiIsIkF1dGhlbnRpY2F0aW9uTWV0aG9kIjoidXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6MS4w
                OmFtOnBhc3N3b3JkIiwiZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsIkF1ZGllbmNlUmVzdHJpY3Rpb25
                Db25kaXRpb24uQXVkaWVuY2UiOiJqd3Rfc2FtbCIsImlzcyI6ImlzYW0iLCJJc3N1ZUluc3RhbnQiOiIyMDE2LT
                AzLTI4VDEwOjEwOjUzWiIsImZhbWlseV9uYW1lIjoiZG9lIiwiTm90QmVmb3JlIjoiMjAxNi0wMy0yOFQxMDowO
                To1M1oiLCJBdXRoZW50aWNhdGlvbkluc3RhbnQiOiIyMDE2LTAzLTI4VDEwOjEwOjUzWiIsImlzc3VlciI6Iml
                zYW0ifQ==</JWT>
                </wst:RequestedSecurityToken>
                <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate</wst:RequestType>
                <wst:Status>
                    <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid</wst:Code>
                </wst:Status>
            </wst:RequestSecurityTokenResponse>
        </wst:RequestSecurityTokenResponseCollection>
    </soap:Body>
</soap:Envelope>

The bold embedded element, <JWT> </JWT>) , is the result in a Base64 encoded JSON Web Token:

{
  "sub": "0123456789",
  "given_name": "john",
  "NotOnOrAfter": "2016-03-29T10:11:53Z",
  "AuthenticationMethod": "urn:oasis:names:tc:SAML:1.0:am:password",
  "email": "john.doe@example.com",
  "AudienceRestrictionCondition.Audience": "jwt_saml",
  "iss": "isam",
  "IssueInstant": "2016-03-28T10:10:53Z",
  "family_name": "doe",
  "NotBefore": "2016-03-28T10:09:53Z",
  "AuthenticationInstant": "2016-03-28T10:10:53Z",
  "issuer": "isam“
}

Parent topic: STSRequest and STSResponse access using a JavaScript mapping rule

Related tasks:

Mapping a JSON Web Token to a SAML2 token example

Customizing the SAML 2.0 login form Customizing the SAML 2.0 login formCustomizing the SAML 2.0 login formAn identity provider can customize the default authentication login page with more contextual information.SAML 2.0custom login formauthenticationlogin formlogin pagescustomWhen a user requests access to a single sign-on federation, the identity provider initiates single sign-on by authenticating the user. To authenticate the user, the identity provider uses a point of contact server to display a forms-based login page. When an identity provider participates in multiple federations or hosts multiple partners in one federation, an administrator might want to customize the default login form. To specify the contextual information to pass to the web reverse proxy login page, use the local management interface to update the advanced configuration property, poc.websealAuth.authenticationMacros. The value of this advanced configuration property is a list of comma-separated macros. Each macro represents a piece of contextual information.The set of defined values are described in Supported macros for customizing an authentication login formYou can customize an authentication login form with a set macros that are supported by SAML 2.0.. Review this list and identify the ones that you want to use.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.Supported macros for customizing an authentication login formYou can customize an authentication login form with a set macros that are supported by SAML 2.0.

Customizing the SAML 2.0 login form

An identity provider can customize the default authentication login page with more contextual information.

When a user requests access to a single sign-on federation, the identity provider initiates single sign-on by authenticating the user. To authenticate the user, the identity provider uses a point of contact server to display a forms-based login page.

When an identity provider participates in multiple federations or hosts multiple partners in one federation, an administrator might want to customize the default login form.

To specify the contextual information to pass to the web reverse proxy login page, use the local management interface to update the advanced configuration property, poc.websealAuth.authenticationMacros. The value of this advanced configuration property is a list of comma-separated macros. Each macro represents a piece of contextual information.

The set of defined values are described in Supported macros for customizing an authentication login form. Review this list and identify the ones that you want to use.

Supported macros for customizing an authentication login form
You can customize an authentication login form with a set macros that are supported by SAML 2.0.

Parent topic: SAML 2.0 federations

Supported macros for customizing an authentication login formYou can customize an authentication login form with a set macros that are supported by SAML 2.0.authenticationlogin formmacroscustomizationSAMLauthentication login form custom macrosweb reverse proxylogin pageslogin pagesweb reverse proxySecurity Access Manager supplies contextual authentication parameters so that you can customize login forms. The contextual authentication parameters are passed to the web reverse proxy as query string parameters. Table 1 shows the list of macros names and the name of the query string parameter in which the contextual information is passed to the web reverse proxy login page. Specify a list of these comma-separated macros in the poc.websealAuth.authenticationMacros advanced configuration parameter. See Managing advanced configurationAdjust configuration settings in supported configuration files.. Macros for customizing the login formMacroQuery-String Parameter nameDescription%FEDID%FedIdSpecifies the unique identifier of the federation. %FEDNAME%FedNameSpecifies the user-assigned name of the federation.%PARTNERID%PartnerIdSpecifies the provider ID of the partner.%TARGET%Target Specifies the target URL at the partner.%SPRELAYSTATE%SPRelayStateSpecifies the RelayState data that accompanies the SAML authentication request.%ACSURL%AssertionConsumerURLSpecifies the assertion consumer service URL of the partner.%AUTHNCONTEXT%AuthnContextSpecifies the RequestedAuthnContext in the SAML authentication request.%SSOREQUEST%SSORequestSpecifies the base-64 encoded form of SAML authentication request.%FORCEAUTHN%ForceAuthnSpecifies ForceAuthn in SAML authentication request.Customizing the SAML 2.0 login formAn identity provider can customize the default authentication login page with more contextual information.

Supported macros for customizing an authentication login form

You can customize an authentication login form with a set macros that are supported by SAML 2.0.

Security Access Manager supplies contextual authentication parameters so that you can customize login forms. The contextual authentication parameters are passed to the web reverse proxy as query string parameters.

Table 136 shows the list of macros names and the name of the query string parameter in which the contextual information is passed to the web reverse proxy login page.

Specify a list of these comma-separated macros in the poc.websealAuth.authenticationMacros advanced configuration parameter. See Managing advanced configuration.

Table 136. Macros for customizing the login form

Macro | Query-String Parameter name | Description
%FEDID% | FedId | Specifies the unique identifier of the federation.
%FEDNAME% | FedName | Specifies the user-assigned name of the federation.
%PARTNERID% | PartnerId | Specifies the provider ID of the partner.
%TARGET% | Target | Specifies the target URL at the partner.
%SPRELAYSTATE% | SPRelayState | Specifies the RelayState data that accompanies the SAML authentication request.
%ACSURL% | AssertionConsumerURL | Specifies the assertion consumer service URL of the partner.
%AUTHNCONTEXT% | AuthnContext | Specifies the RequestedAuthnContext in the SAML authentication request.
%SSOREQUEST% | SSORequest | Specifies the base-64 encoded form of SAML authentication request.
%FORCEAUTHN% | ForceAuthn | Specifies ForceAuthn in SAML authentication request.

Parent topic: Customizing the SAML 2.0 login form

Customizing SAML 2.0 pagesAccess Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed. event pagescustomization overviewlogin formcustomizing (overview)single sign-onevent pagesYou can customize the event pages by modifying their appearance or content.Before you continue with the customization, you need to have a thorough understanding of how event pages are generated and displayed. SAML 2.0 federations The Federation Module supports SAML 2.0 federations.Generation of event pagesEvent pages are displayed in response to events that occur during single sign-on requests. They usually contain a form (such as a prompt for user name and password information) or text (such as an informational or error message).SAML 2.0 page identifiersThe SAML 2.0 runtime can display HTML pages in response to events that occur during single sign-on requests. You can select which pages to display and also modify the pages.Template page for the WAYF pageThe Where Are You From (WAYF) page is used at the service provider. The WAYF page enables users to select their identity provider if there is more than one configured in the federation. Customizing the Consent to Federate PageA consent to federate page is an HTML form which prompts a user to give consent to joining a federation. You can customize the consent to federate page to specify what information it requests from a user.

Customizing SAML 2.0 pages

Access Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed.

You can customize the event pages by modifying their appearance or content.

Before you continue with the customization, you need to have a thorough understanding of how event pages are generated and displayed.

Generation of event pages
Event pages are displayed in response to events that occur during single sign-on requests. They usually contain a form (such as a prompt for user name and password information) or text (such as an informational or error message).

SAML 2.0 page identifiers
The SAML 2.0 runtime can display HTML pages in response to events that occur during single sign-on requests. You can select which pages to display and also modify the pages.

Template page for the WAYF page
The Where Are You From (WAYF) page is used at the service provider. The WAYF page enables users to select their identity provider if there is more than one configured in the federation.

Customizing the Consent to Federate Page
A consent to federate page is an HTML form which prompts a user to give consent to joining a federation. You can customize the consent to federate page to specify what information it requests from a user.

Parent topic: SAML 2.0 federations

Generation of event pagesEvent pages are displayed in response to events that occur during single sign-on requests. They usually contain a form (such as a prompt for user name and password information) or text (such as an informational or error message).event pagesoverviewSAML 2.0event pagespages, eventSAML 2.0Event pages are dynamic pages that are generated by Security Access Manager using the following information:Template filesXML or HTML files that are provided with the appliance and contain elements, such as fields, text, or graphics, and sometimes macros that are replaced with information that is specific to the request or to provide a response to the request.Page identifiersEvent information that corresponds to one or more template files. Each page identifier corresponds to a specific event condition, such as a specific error or a condition in which a message or a form must be displayed. Message catalogsText that is used to replace macros in the template files.When a request is received, the appropriate response page is generated as follows: Processing of the request occurs and a response to an event is required.Template files and page identifiers are read from the file system.Macros in the template files are replaced with values that are appropriate for the response that is needed.An appropriate event page is generated.The generated event page is displayed.Customizing SAML 2.0 pagesAccess Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed.

Generation of event pages

Event pages are displayed in response to events that occur during single sign-on requests. They usually contain a form (such as a prompt for user name and password information) or text (such as an informational or error message).

Event pages are dynamic pages that are generated by Security Access Manager using the following information:

Template files

XML or HTML files that are provided with the appliance and contain elements, such as fields, text, or graphics, and sometimes macros that are replaced with information that is specific to the request or to provide a response to the request.

Page identifiers

Event information that corresponds to one or more template files. Each page identifier corresponds to a specific event condition, such as a specific error or a condition in which a message or a form must be displayed.

Message catalogs

Text that is used to replace macros in the template files.

When a request is received, the appropriate response page is generated as follows:

Processing of the request occurs and a response to an event is required.

Template files and page identifiers are read from the file system.

Macros in the template files are replaced with values that are appropriate for the response that is needed.

An appropriate event page is generated.

The generated event page is displayed.

Parent topic: Customizing SAML 2.0 pages

SAML 2.0 page identifiersSAML 2.0 page identifiersThe SAML 2.0 runtime can display HTML pages in response to events that occur during single sign-on requests. You can select which pages to display and also modify the pages.SAML 2.0page identifiersHTML pagesSAML 2.0single sign-onHTML pagespage identifiersHTML for SAML 2.0macrosHTML pages for SAML 2.0Use HTML pages for the following purposes: Displaying success and error messages to users Asking users for confirmationSending SAML messages You can customize these HTML pages so that they display what you want. These pages contain macros and are similar to other HTML pages in Security Access Manager. A macro is text in an HTML page that is replaced with context-specific information. For example, the macro @ERROR_MESSSAGE@ is replaced by text that describes the error that occurred. You can find the SAML 2.0 pages in the local management interface using these steps: Click Secure FederationGlobal SettingsTemplate Files.Expand the locale folder to locate a template file. For example, the English version of the SAML consent_to_federate.html template is in C/saml20. All of the available SAML 2.0 HTML pages are listed in the following table. SAML 2.0 HTML page identifiers and macrosPage identifierDescriptionMacros and descriptionssaml20/consent_to_federate.htmlDisplays during the SAML single sign-on flow whenever the service provider wants to federate the account at the identity provider with the account at the service provider.@TOKEN:form_action@ The URL to which the SAML message is sent.@TOKEN:SPProviderID@The ID of the Service Provider.@TOKEN:SPDisplayName@The name of the Service Provider.@TOKEN:IPProviderID@The name of the Identity Provider.saml20/logout_partial_success.htmlDisplays whenever the SAML single log out flow completes with partial success.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@TOKEN:UserName@The user name that performs the operation.saml20/logout_success.htmlDisplays whenever the SAML single log out flow completes successfully.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@TOKEN:UserName@The user name that performs the operation.saml20/nimgmt_terminate_success.htmlDisplays whenever the SAML name identifier management terminate flow completes successfully.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@TOKEN:UserName@The user name that performs the operation.@TOKEN:PartnerID@The ID of the partner.saml20/nimgmt_update_success.htmlDisplays whenever the SAML name identifier management update flow completes successfully.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@TOKEN:UserName@The user name that performs the operation.@TOKEN:PartnerID@The ID of the partner.saml20/saml_post_artifact.htmlSends the SAML artifact to the partner for HTTP POST binding.@TOKEN:form_action@The URL to which the SAML message is sent.@TOKEN:RelayState@The RelayState.@TOKEN:SamlMessage@The SAML message.saml20/saml_post_request.htmlSends the SAML request message to partner for HTTP POST binding.@TOKEN:form_action@The URL to which the SAML message is sent.@TOKEN:RelayState@The RelayState.@TOKEN:SamlMessage@The SAML message.saml20/saml_post_response.htmlSends the SAML response message to the partner for HTTP POST binding.@TOKEN:form_action@The URL to which the SAML message is sent.@TOKEN:RelayState@The RelayState.@TOKEN:SamlMessage@The SAML message.saml20/art_exchange_failed.htmlDisplays whenever there is a failure during the SAML artifact resolution flow.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/authn_failed.htmlDisplays whenever there is a failure during the SAML single sign-on flow.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_building_msg.htmlDisplays whenever an outgoing SAML message is not constructed.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_decrypting_msg.htmlDisplays whenever an incoming SAML message is decrypted.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_missing_config_param.htmlDisplays whenever a SAML flow is run on a SAML federation with invalid configuration.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_parsing_art.htmlDisplays whenever an incoming SAML artifact is parsed.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_parsing_msg.htmlDisplays whenever an incoming SAML message is parsed.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_sending_msg.htmlDisplays whenever an outgoing SAML message is sent.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_validating_art.htmlDisplays whenever an incoming SAML artifact is validated.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_validating_init_msg.htmlDisplays whenever a SAML flow is initiated.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_validating_msg.htmlDisplays whenever an incoming SAML message is validated.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/error_validating_msg_signature.htmlDisplays whenever an incoming SAML message is signature validated.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/invalid_art.htmlDisplays whenever an incoming SAML artifact is validated.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/invalid_init_msg.htmlDisplays whenever a SAML flow is initiated.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/invalid_msg.htmlDisplays whenever an incoming SAML message is validated.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/logout_failed.htmlDisplays whenever there is a failure during SAML single logout flow.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/nimgmt_terminate_failed.htmlDisplays whenever there is a failure during the SAML name identifier terminate management flow.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.saml20/nimgmt_update_failed.htmlDisplays whenever there is a failure during the SAML name identifier update management flow.@REQ_ADDR@The URL of the request.@TIMESTAMP@The time stamp of the request.@ERROR_MESSAGE@The error message.@EXCEPTION_STACK@The stack trace of the error. Do not use this macro in a production environment.Customizing SAML 2.0 pagesAccess Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed.

SAML 2.0 page identifiers

The SAML 2.0 runtime can display HTML pages in response to events that occur during single sign-on requests. You can select which pages to display and also modify the pages.

Use HTML pages for the following purposes:

Displaying success and error messages to users

Asking users for confirmation

Sending SAML messages

You can customize these HTML pages so that they display what you want. These pages contain macros and are similar to other HTML pages in Security Access Manager. A macro is text in an HTML page that is replaced with context-specific information. For example, the macro @ERROR_MESSSAGE@ is replaced by text that describes the error that occurred.

You can find the SAML 2.0 pages in the local management interface using these steps:

Click Secure Federation > Global Settings > Template Files.

Expand the locale folder to locate a template file.

For example, the English version of the SAML consent_to_federate.html template is in C/saml20.

All of the available SAML 2.0 HTML pages are listed in the following table.

Table 137. SAML 2.0 HTML page identifiers and macros

Page identifier
Description
Macros and descriptions

saml20/consent_to_federate.html
Displays during the SAML single sign-on flow whenever the service provider wants to federate the account at the identity provider with the account at the service provider.

@TOKEN:form_action@

The URL to which the SAML message is sent.

@TOKEN:SPProviderID@

The ID of the Service Provider.

@TOKEN:SPDisplayName@

The name of the Service Provider.

@TOKEN:IPProviderID@

The name of the Identity Provider.

saml20/logout_partial_success.html
Displays whenever the SAML single log out flow completes with partial success.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@TOKEN:UserName@

The user name that performs the operation.

saml20/logout_success.html
Displays whenever the SAML single log out flow completes successfully.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@TOKEN:UserName@

The user name that performs the operation.

saml20/nimgmt_terminate_success.html
Displays whenever the SAML name identifier management terminate flow completes successfully.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@TOKEN:UserName@

The user name that performs the operation.

@TOKEN:PartnerID@

The ID of the partner.

saml20/nimgmt_update_success.html
Displays whenever the SAML name identifier management update flow completes successfully.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@TOKEN:UserName@

The user name that performs the operation.

@TOKEN:PartnerID@

The ID of the partner.

saml20/saml_post_artifact.html
Sends the SAML artifact to the partner for HTTP POST binding.

@TOKEN:form_action@

The URL to which the SAML message is sent.

@TOKEN:RelayState@

The RelayState.

@TOKEN:SamlMessage@

The SAML message.

saml20/saml_post_request.html
Sends the SAML request message to partner for HTTP POST binding.

@TOKEN:form_action@

The URL to which the SAML message is sent.

@TOKEN:RelayState@

The RelayState.

@TOKEN:SamlMessage@

The SAML message.

saml20/saml_post_response.html
Sends the SAML response message to the partner for HTTP POST binding.

@TOKEN:form_action@

The URL to which the SAML message is sent.

@TOKEN:RelayState@

The RelayState.

@TOKEN:SamlMessage@

The SAML message.

saml20/art_exchange_failed.html
Displays whenever there is a failure during the SAML artifact resolution flow.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/authn_failed.html
Displays whenever there is a failure during the SAML single sign-on flow.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_building_msg.html
Displays whenever an outgoing SAML message is not constructed.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_decrypting_msg.html
Displays whenever an incoming SAML message is decrypted.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_missing_config_param.html
Displays whenever a SAML flow is run on a SAML federation with invalid configuration.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_parsing_art.html
Displays whenever an incoming SAML artifact is parsed.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_parsing_msg.html
Displays whenever an incoming SAML message is parsed.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_sending_msg.html
Displays whenever an outgoing SAML message is sent.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_validating_art.html
Displays whenever an incoming SAML artifact is validated.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_validating_init_msg.html
Displays whenever a SAML flow is initiated.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_validating_msg.html
Displays whenever an incoming SAML message is validated.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/error_validating_msg_signature.html
Displays whenever an incoming SAML message is signature validated.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/invalid_art.html
Displays whenever an incoming SAML artifact is validated.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/invalid_init_msg.html
Displays whenever a SAML flow is initiated.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/invalid_msg.html
Displays whenever an incoming SAML message is validated.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/logout_failed.html
Displays whenever there is a failure during SAML single logout flow.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/nimgmt_terminate_failed.html
Displays whenever there is a failure during the SAML name identifier terminate management flow.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

saml20/nimgmt_update_failed.html
Displays whenever there is a failure during the SAML name identifier update management flow.

@REQ_ADDR@

The URL of the request.

@TIMESTAMP@

The time stamp of the request.

@ERROR_MESSAGE@

The error message.

@EXCEPTION_STACK@

The stack trace of the error. Do not use this macro in a production environment.

Parent topic: Customizing SAML 2.0 pages

Template page for the WAYF pageTemplate page for the WAYF pageTemplate page for the WAYF pageThe Where Are You From (WAYF) page is used at the service provider. The WAYF page enables users to select their identity provider if there is more than one configured in the federation. Where Are You From (WAYF) page WAYF pageWAYF pagetemplatetemplate pagesWAYF pageWhen a user arrives at a service provider, a WAYF identifier can be delivered through a cookie or query-string parameter with the request. The entity ID of the identity provider is stored as the value of the cookie or query-string parameter. If the WAYF identifier cookie or query-string parameter is not present, the WAYF page opens.An example URL that includes the query string parameter for WAYF:https://sp.host.com/isam/sps/samlfed/saml20/ logininitial?RequestBinding=HTTPRedirect&ResponseBinding =HTTPPost&ITFIM_WAYF_IDP=https://idp.host.com/isam/sps/samlfed/saml20 This example is for a SAML 2.0 single sign-on URL. The query string parameter name is ITFIM_WAYF_IDP. The value of the identity provider ID is https://idp.host.com/isam/sps/samlfed/saml20.The WAYF page requires the user to indicate where they came from. If the user is not logged on to their identity provider, they are asked to log on. Depending on the attributes passed, the service provider can grant or deny access to the service. You can find the template pages for WAYF in the local management interface using these steps:Click Secure FederationGlobal SettingsTemplate Files.Expand the locale folder and navigate to /pages/itfim/wayf.Administrators can use the WAYF page without modifications, but in some cases might want to modify the HTML style to match the specific deployment environment.This template file provides several replacement macros:@WAYF_FORM_ACTION@This macro is replaced with the endpoint of the original request. This macro does not belong within a repeatable section. @WAYF_FORM_METHOD@This macro is replaced with the HTTP method of the original request. This macro does not belong within a repeatable section.@WAYF_FORM_PARAM_ID@This macro is replaced with ID used by the action for the identity provider. This macro is repeated once for each identity provider.@WAYF_IP_ID@This macro is replaced with the unique ID of the identity provider. This macro is repeated once for each identity provider.@WAYF_IP_DISPLAY_NAME@This macro is replaced with the configured display name of the identity provider. This macro is repeated once for each identity provider.@WAYF_HIDDEN_NAME@This macro is replaced with the name of the hidden parameter. This macro is repeated once for each original request parameter and is hidden.@WAYF_HIDDEN_VALUE@This macro is replaced with the value of the hidden parameter. This macro is repeated once for each original request parameter and is hidden.Customizing SAML 2.0 pagesAccess Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed.

Template page for the WAYF page

The Where Are You From (WAYF) page is used at the service provider. The WAYF page enables users to select their identity provider if there is more than one configured in the federation.

When a user arrives at a service provider, a WAYF identifier can be delivered through a cookie or query-string parameter with the request. The entity ID of the identity provider is stored as the value of the cookie or query-string parameter. If the WAYF identifier cookie or query-string parameter is not present, the WAYF page opens.

An example URL that includes the query string parameter for WAYF:

https://sp.host.com/isam/sps/samlfed/saml20/
logininitial?RequestBinding=HTTPRedirect&ResponseBinding
=HTTPPost&ITFIM_WAYF_IDP=https://idp.host.com/isam/sps/samlfed/saml20

This example is for a SAML 2.0 single sign-on URL. The query string parameter name is ITFIM_WAYF_IDP. The value of the identity provider ID is https://idp.host.com/isam/sps/samlfed/saml20.

The WAYF page requires the user to indicate where they came from. If the user is not logged on to their identity provider, they are asked to log on. Depending on the attributes passed, the service provider can grant or deny access to the service.

You can find the template pages for WAYF in the local management interface using these steps:

Click Secure Federation > Global Settings > Template Files.

Expand the locale folder and navigate to /pages/itfim/wayf.

Administrators can use the WAYF page without modifications, but in some cases might want to modify the HTML style to match the specific deployment environment.

This template file provides several replacement macros:

@WAYF_FORM_ACTION@

This macro is replaced with the endpoint of the original request. This macro does not belong within a repeatable section.

@WAYF_FORM_METHOD@

This macro is replaced with the HTTP method of the original request. This macro does not belong within a repeatable section.

@WAYF_FORM_PARAM_ID@

This macro is replaced with ID used by the action for the identity provider. This macro is repeated once for each identity provider.

@WAYF_IP_ID@

This macro is replaced with the unique ID of the identity provider. This macro is repeated once for each identity provider.

@WAYF_IP_DISPLAY_NAME@

This macro is replaced with the configured display name of the identity provider. This macro is repeated once for each identity provider.

@WAYF_HIDDEN_NAME@

This macro is replaced with the name of the hidden parameter. This macro is repeated once for each original request parameter and is hidden.

@WAYF_HIDDEN_VALUE@

This macro is replaced with the value of the hidden parameter. This macro is repeated once for each original request parameter and is hidden.

Parent topic: Customizing SAML 2.0 pages

Customizing the Consent to Federate PageCustomizing the Consent to Federate PageCustomizing the Consent to Federate PageA consent to federate page is an HTML form which prompts a user to give consent to joining a federation. You can customize the consent to federate page to specify what information it requests from a user.Consent to Federate PagedescriptionConsent to Federate PagecustomizationSAML 2.0Consent to Federate Page customizationSAML 2.0responsesDetermine what values you want to use for the consent to federate page.When a user accesses a federation, they agree to join the federation. The HTML form saml20/consent_to_federate.html prompts for this consent. You can customize what the form requests by adding consent values. These values indicate how a user agrees to join a federation and if service providers are notified of the consent. Identity providers receive the consent values in the SAML 2.0 response. The following values determine how a user joins a federation: 1 A user agrees to join a federation without notifying the service provider.0A user refuses to join a federation.A URI valueA URI can indicate whether the user agrees to join a federation and if you want to notify the service provider about the user consent. The following table lists and describes the supported URI values.Supported consent values for SAML 2.0 responseConsent valueURIDescriptionUnspecifiedurn:oasis:names:tc: SAML:2.0:consent: unspecifiedThe consent of the user is not specified.Obtainedurn:oasis:names:tc: SAML:2.0:consent: obtainedSpecifies that user consent is acquired by the issuer of the message.Priorurn:oasis:names:tc: SAML:2.0:consent: priorSpecifies that user consent is acquired by the issuer of the message before the action which initiated the message. Impliciturn:oasis:names:tc: SAML:2.0:consent: current-implicitSpecifies that user consent is implicitly acquired by the issuer of the message when the message was initiated. Expliciturn:oasis:names:tc: SAML:2.0:consent: current-explicitSpecifies that the user consent is explicitly acquired by the issuer of the message at the instance that the message was sent. Unavailableurn:oasis:names:tc: SAML:2.0:consent: unavailableSpecifies that the issuer of the message was not able to get consent from the user. Inapplicableurn:oasis:names:tc: SAML:2.0:consent: inapplicableSpecifies that the issuer of the message does not need to get or report the user consent. Follow the steps in this procedure to customize the consent to federate page.Log in to the local management interface.Click Secure FederationGlobal SettingsTemplate Files.Expand a locale and select saml20/consent_to_federate.html.Click Edit and add the appropriate consent values for your federation.Click Save.Deploy the changes.The following example shows an added URI with a consent value Obtained:<input type="radio" checked name="Consent" value="urn:urn:oasis:names:tc:SAML:2.0:consent:obtained"/> Consent Obtained.<br/>In this example, the user consent is acquired by the issuer of the message.Customizing SAML 2.0 pagesAccess Manager generates files that are displayed in response to events that occur during single sign-on requests. The response that is displayed might be a form, such as when login information is required, or an error or information statement about a condition that occurred while the request was processed.

Customizing the Consent to Federate Page

A consent to federate page is an HTML form which prompts a user to give consent to joining a federation. You can customize the consent to federate page to specify what information it requests from a user.

Before you begin

Determine what values you want to use for the consent to federate page.

About this task

When a user accesses a federation, they agree to join the federation. The HTML form saml20/consent_to_federate.html prompts for this consent. You can customize what the form requests by adding consent values. These values indicate how a user agrees to join a federation and if service providers are notified of the consent. Identity providers receive the consent values in the SAML 2.0 response.

The following values determine how a user joins a federation:

1

A user agrees to join a federation without notifying the service provider.

0

A user refuses to join a federation.

A URI value

A URI can indicate whether the user agrees to join a federation and if you want to notify the service provider about the user consent. The following table lists and describes the supported URI values.

Table 138. Supported consent values for SAML 2.0 response

Consent value | URI | Description
Unspecified | urn:oasis:names:tc: SAML:2.0:consent: unspecified | The consent of the user is not specified.
Obtained | urn:oasis:names:tc: SAML:2.0:consent: obtained | Specifies that user consent is acquired by the issuer of the message.
Prior | urn:oasis:names:tc: SAML:2.0:consent: prior | Specifies that user consent is acquired by the issuer of the message before the action which initiated the message.
Implicit | urn:oasis:names:tc: SAML:2.0:consent: current-implicit | Specifies that user consent is implicitly acquired by the issuer of the message when the message was initiated.
Explicit | urn:oasis:names:tc: SAML:2.0:consent: current-explicit | Specifies that the user consent is explicitly acquired by the issuer of the message at the instance that the message was sent.
Unavailable | urn:oasis:names:tc: SAML:2.0:consent: unavailable | Specifies that the issuer of the message was not able to get consent from the user.
Inapplicable | urn:oasis:names:tc: SAML:2.0:consent: inapplicable | Specifies that the issuer of the message does not need to get or report the user consent.

Follow the steps in this procedure to customize the consent to federate page.

Procedure

Log in to the local management interface.

Click Secure Federation > Global Settings > Template Files.

Expand a locale and select saml20/consent_to_federate.html.

Click Edit and add the appropriate consent values for your federation.

Click Save.

Deploy the changes.

Example

The following example shows an added URI with a consent value Obtained:

<input type="radio" checked name="Consent"
value="urn:urn:oasis:names:tc:SAML:2.0:consent:obtained"/>
Consent Obtained.<br/>

In this example, the user consent is acquired by the issuer of the message.

Parent topic: Customizing SAML 2.0 pages

Configuring the user session ID for the federation runtimeConfiguring the user session ID for the federation runtimeCustomize the user session ID header name so that you can track user sessions, end sessions, or sign out a particular user from a web reverse proxy point of contact server.user session IDfederation runtimeuser session IDsession IDusersingle logoutuser session IDlogoutuser session IDSet your web reverse proxy to enable the creation of unique user session IDs. The following stanza and entry must be set:[session] user-session-ids = yesSee User session management for back-end servers for general information.The federation runtime uses user session ID information to log out the user from the web reverse proxy. The user session ID uniquely identifies a specific session for an authenticated user and is stored as a part of credential information of the user. The federation runtime obtains the user session ID from the web reverse proxy. The web reverse proxy sends the user session ID to the federation runtime in an HTTP header. To accomplish this, configure the web reverse proxy and federation runtime to use the same header name.For the federation runtime, update the advanced configuration property, poc.signOut.userSessionRequestHeader by using the local management interface:Select Secure FederationGlobal SettingsAdvanced Configuration.Locate poc.signOut.userSessionRequestHeader in the list, select it, and click Edit.Enter the header name that you want to use for the user session ID and click Save. For example, specify my_user_session_id.See Managing advanced configurationAdjust configuration settings in supported configuration files..For the web reverse proxy, update the junction to delete an existing user_session_id by using the following command: pdadmin -a sec_master -p password object modify /WebSEAL/fedname-webseal/junction_name delete attribute HTTP-Tag-Value user_session_id=user_session_idWhere: passwordSpecifies the password for sec_master.fednameSpecifies the name of the federation.websealSpecifies the name of the web reverse proxy server.junction_nameSpecifies the name of the junction.user_session_idSpecifies the existing name that was defined for the session ID.For example:pdadmin -a sec_master -p ipadminpw object modify /WebSEAL/saml20-ip-ipwga/isam delete attribute HTTP-Tag-Value user_session_id=user_session_idThis command deletes the existing user_session_id.For the web reverse proxy, update the junction to use the poc.signOut.userSessionRequestHeader property value you defined in step 1. Add this customized attribute value by using the following command:pdadmin -a sec_master -p password object modify /fedname-webseal/junction_name set attribute HTTP-Tag-Value user_session_id=user_session_IDWhere: user_session_idSpecifies the value from step 1. For example, my_user_session_id.For example:pdadmin -a sec_master -p ipadminpw object modify /WebSEAL/saml20-ip-ipwga/isam set attribute HTTP-Tag-Value user_session_id=my_user_session_IDThis command changes the value for the web reverse proxy to my_user_session_ID.The federation runtime and the web reverse proxy have the same header name.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.

Configuring the user session ID for the federation runtime

Customize the user session ID header name so that you can track user sessions, end sessions, or sign out a particular user from a web reverse proxy point of contact server.

Before you begin

Set your web reverse proxy to enable the creation of unique user session IDs. The following stanza and entry must be set:

[session]
user-session-ids = yes

See User session management for back-end servers for general information.

About this task

The federation runtime uses user session ID information to log out the user from the web reverse proxy.

The user session ID uniquely identifies a specific session for an authenticated user and is stored as a part of credential information of the user.

The federation runtime obtains the user session ID from the web reverse proxy. The web reverse proxy sends the user session ID to the federation runtime in an HTTP header. To accomplish this, configure the web reverse proxy and federation runtime to use the same header name.

Procedure

For the federation runtime, update the advanced configuration property, poc.signOut.userSessionRequestHeader by using the local management interface:

Select Secure Federation > Global Settings > Advanced Configuration.

Locate poc.signOut.userSessionRequestHeader in the list, select it, and click Edit.

Enter the header name that you want to use for the user session ID and click Save. For example, specify my_user_session_id.

See Managing advanced configuration.

Optional: For the web reverse proxy, update the junction to delete an existing user_session_id by using the following command:

pdadmin -a sec_master -p password object modify /WebSEAL/fedname-webseal/junction_name
  delete attribute HTTP-Tag-Value user_session_id=user_session_id

Where:

password

Specifies the password for sec_master.

fedname

Specifies the name of the federation.

webseal

Specifies the name of the web reverse proxy server.

junction_name

Specifies the name of the junction.

user_session_id

Specifies the existing name that was defined for the session ID.

For example:

pdadmin -a sec_master -p ipadminpw object modify
  /WebSEAL/saml20-ip-ipwga/isam
  delete attribute HTTP-Tag-Value user_session_id=user_session_id

This command deletes the existing user_session_id.

For the web reverse proxy, update the junction to use the poc.signOut.userSessionRequestHeader property value you defined in step 1. Add this customized attribute value by using the following command:

pdadmin -a sec_master -p password object modify /fedname-webseal/junction_name
  set attribute HTTP-Tag-Value user_session_id=user_session_ID

Where:

user_session_id

Specifies the value from step 1. For example, my_user_session_id.

For example:

pdadmin -a sec_master -p ipadminpw object modify /WebSEAL/saml20-ip-ipwga/isam
  set attribute HTTP-Tag-Value user_session_id=my_user_session_ID

This command changes the value for the web reverse proxy to my_user_session_ID.

Results

The federation runtime and the web reverse proxy have the same header name.

Parent topic: SAML 2.0 federations

Synchronizing system clocks in the federationSynchronizing system clocks in the federationSynchronizing system clocksBecause security tokens have expiration times, you and your partner's system clocks must be synchronized.synchronizing clocksclockssynchronizingsystem clock synchronizationIn your environment, ensure that the clock on the system where you have the runtime and management services component installed is synchronized with your partner. See the information of your operating system documentation for information about your system clock and time synchronization. Consider using the NTP time synchronization protocol.SAML 2.0 federations The Federation Module supports SAML 2.0 federations.

Synchronizing system clocks in the federation

Because security tokens have expiration times, you and your partner's system clocks must be synchronized.

About this task

In your environment, ensure that the clock on the system where you have the runtime and management services component installed is synchronized with your partner.

See the information of your operating system documentation for information about your system clock and time synchronization. Consider using the NTP time synchronization protocol.

Parent topic: SAML 2.0 federations

OpenID Connect federationsThe Federation Module supports OpenID Connect federations.OIDCOpenID Connect is an extension of the OAuth protocol to better support identity and authentication.For a complete description of the OpenID Connect specifications, see the OpenID website: http://openid.net/specs/Federation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.OpenID Connect conceptsThis topic introduces the main concepts of OpenID Connect.OpenID Connect endpointsOpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance. OpenID Connect flowsThe OpenID Connect support in IBM Security Access Manager provides two different ways for a Relying Party to obtain access to a protected resource.Configuring OpenID Connect Providers (OP)An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities. Configuring Relying PartiesWhen configuring a OpenID Connect Relying Party two entities must be created - a federation and a parter. There can be multiple partners per federation, but each partner has only one federation.OpenID Connect mapping rulesMapping rules allow users to customize the information that is propagated from an OpenID Connect Provider or what is consumed by a Relying Party. Accessing identity information from a reverse proxyBy using an OpenID Connect Relying Party for authentication, a Reverse Proxy can be configured to provide identity information to junctioned applications.Authentication macrosThe following authentication macros are available to the user when configuring the login page of an OpenID Connect Provider.Automatic configuration of a reverse proxy for OpenID ConnectTo make use of a configured OpenID Connect Provider or Relying Party, a reverse proxy instance must be configured to act as the point of contact. Customizing the consent pageThe consent page of an OpenID Connect Provider Federation can be changed with the Template Files page in the local management interface. Known limitationsThese limitations apply to OpenID Connect federations.

OpenID Connect federations

The Federation Module supports OpenID Connect federations.

OpenID Connect is an extension of the OAuth protocol to better support identity and authentication.

For a complete description of the OpenID Connect specifications, see the OpenID website: http://openid.net/specs/

OpenID Connect concepts
This topic introduces the main concepts of OpenID Connect.

OpenID Connect endpoints
OpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance.

OpenID Connect flows
The OpenID Connect support in IBM Security Access Manager provides two different ways for a Relying Party to obtain access to a protected resource.

Configuring OpenID Connect Providers (OP)
An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities.

Configuring Relying Parties
When configuring a OpenID Connect Relying Party two entities must be created - a federation and a parter. There can be multiple partners per federation, but each partner has only one federation.

OpenID Connect mapping rules
Mapping rules allow users to customize the information that is propagated from an OpenID Connect Provider or what is consumed by a Relying Party.

Accessing identity information from a reverse proxy
By using an OpenID Connect Relying Party for authentication, a Reverse Proxy can be configured to provide identity information to junctioned applications.

Authentication macros
The following authentication macros are available to the user when configuring the login page of an OpenID Connect Provider.

Automatic configuration of a reverse proxy for OpenID Connect
To make use of a configured OpenID Connect Provider or Relying Party, a reverse proxy instance must be configured to act as the point of contact.

Customizing the consent page
The consent page of an OpenID Connect Provider Federation can be changed with the Template Files page in the local management interface.

Known limitations
These limitations apply to OpenID Connect federations.

Parent topic: Federation configuration

OpenID Connect conceptsThis topic introduces the main concepts of OpenID Connect.OpenID Connect Provider (OP) OAuth 2.0 Authorization Server that is capable of authenticating the end-user and providing claims to a Relying Party about the authentication event and the end-user.Relying Party (RP)OAuth 2.0 Client application that requires end-user authentication and claims from an OpenID Connect Provider.Entity Something that has a separate and distinct existence and that can be identified in a context. An end-user is one example of an entity. ClaimPiece of information asserted about an entity that is included in the ID token. An OpenID Connect Provider should document which claims it includes in its ID tokens. The following claims are required claims about the authentication event: aud (Audience): Must contain the client identifier of the RP registered at the issuer.iss(Issuer): The issuer identifier of the OP.exp (Expiration time): The RP must validate the ID token before this time.iat (Issued at): The time at which the ID token was issued. The following claims are required claims about the user: sub (Subject): A locally unique and permanent (never reassigned) identifier of the end-user at the issuer. Optional claims about the user can include first_name, last_name, picture, gender, etc.ScopeA property requested by the Relying Party, which can be consented to by the end-user, that requests certain claims be included in the ID token. OpenID Connect requires the openid scope. Common scopes include profile and email.Bearer tokenToken issued from the token endpoint. This includes an access token, a ID token, and potentially a refresh token. See http://tools.ietf.org/html/rfc6750 for more information on bearer tokens. ID tokenJSON Web Token (JWT) that contains claims about the authentication event and the user. JWTs are Base64 encoded JSON objects comprising three sections: Header, Claims Set and JSON Web Signature (JWS). These are separated in the JWT by a period ('.'). The Header must at least contain the algorithm used to sign the JWT (the alg claim). The Claims Set includes claims about the authentication event and the user. The JSON Web Signature (JWS) is used to verify the signing of the JWT. For more information on JWS, see RFC7515. For more information about JWTs, see RFC7519.Refresh token A string that is used to obtain a new access token.A refresh token is optionally issued by the OpenID Connect Provider to the OpenID Connect Partner together with an access token. The OpenID Connect Partner can use the refresh token to request another access token that is based on the same authorization, without involving the resource owner again.IssuerEntity that issues a set of claims.Issuer identifierVerifiable identifier for an issuer. An issuer identifier is a case sensitive URL using the HTTPS scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. Authorization endpointThe endpoint used to initiate an OpenID Connect flow. This endpoint is requested in some bespoke manner. Token endpointThe endpoint used to exchange an authorization code for a bearer token. This is also used to exchange a refresh token for a new access token. Access to the token endpoint is secured and requires client credentials to be provided on requests. JWK endpointThe endpoint used to advertise an OpenID Connect provider's public certificate for use in asymmetric signing algorithms.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.

OpenID Connect concepts

This topic introduces the main concepts of OpenID Connect.

OpenID Connect Provider (OP)

OAuth 2.0 Authorization Server that is capable of authenticating the end-user and providing claims to a Relying Party about the authentication event and the end-user.

Relying Party (RP)

OAuth 2.0 Client application that requires end-user authentication and claims from an OpenID Connect Provider.

Entity

Something that has a separate and distinct existence and that can be identified in a context. An end-user is one example of an entity.

Claim

Piece of information asserted about an entity that is included in the ID token. An OpenID Connect Provider should document which claims it includes in its ID tokens.

The following claims are required claims about the authentication event:

aud (Audience): Must contain the client identifier of the RP registered at the issuer.

iss(Issuer): The issuer identifier of the OP.

exp (Expiration time): The RP must validate the ID token before this time.

iat (Issued at): The time at which the ID token was issued.

The following claims are required claims about the user:

sub (Subject): A locally unique and permanent (never reassigned) identifier of the end-user at the issuer.

Optional claims about the user can include first_name, last_name, picture, gender, etc.

Scope

A property requested by the Relying Party, which can be consented to by the end-user, that requests certain claims be included in the ID token. OpenID Connect requires the openid scope. Common scopes include profile and email.

Bearer token

Token issued from the token endpoint. This includes an access token, a ID token, and potentially a refresh token. See http://tools.ietf.org/html/rfc6750 for more information on bearer tokens.

ID token

JSON Web Token (JWT) that contains claims about the authentication event and the user.

JWTs are Base64 encoded JSON objects comprising three sections: Header, Claims Set and JSON Web Signature (JWS). These are separated in the JWT by a period ('.'). The Header must at least contain the algorithm used to sign the JWT (the alg claim).

The Claims Set includes claims about the authentication event and the user.

The JSON Web Signature (JWS) is used to verify the signing of the JWT. For more information on JWS, see RFC7515.

For more information about JWTs, see RFC7519.

Refresh token

A string that is used to obtain a new access token.

A refresh token is optionally issued by the OpenID Connect Provider to the OpenID Connect Partner together with an access token. The OpenID Connect Partner can use the refresh token to request another access token that is based on the same authorization, without involving the resource owner again.

Issuer

Entity that issues a set of claims.

Issuer identifier

Verifiable identifier for an issuer. An issuer identifier is a case sensitive URL using the HTTPS scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

Authorization endpoint

The endpoint used to initiate an OpenID Connect flow. This endpoint is requested in some bespoke manner.

Token endpoint

The endpoint used to exchange an authorization code for a bearer token. This is also used to exchange a refresh token for a new access token. Access to the token endpoint is secured and requires client credentials to be provided on requests.

JWK endpoint

The endpoint used to advertise an OpenID Connect provider's public certificate for use in asymmetric signing algorithms.

Parent topic: OpenID Connect federations

OpenID Connect endpointsOpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance. All URLs use the following base path:https://<ReverseProxy Hostname>:<Port>/<ISAM Runtime Junction>/For example: https://isam.example.com/isam/The base of all URL is: /oidc/endpoint/amapp-runtime-myFederationName/Request URL to /authorize would be: https://isam.example.com/isam/oidc/endpoint/amapp-runtime-myfederation/authorizeThe URLs are as follows:NameDescriptionURLRoleRelying Party initiation EndpointInitiates login to this Reverse Proxy instance using an identity from an external OP. The query string parameter denotes what OP is contacted for the login.https://rp.isam.example.com/isam/sps/oidc/client/FederationName/oidc_client=?FIMDOMAINName-PartnerAppliesToRelying PartyRelying Party Redirect URIThis is the URL a user will be redirected to after logging in at the OP. It requires unauthenticated access.https://rp.isam.example.com/isam/oidcclient/redirect/FIMDOMAINName-PartnerAppliesToRelying PartyAuthorize endpointThe initial endpoint contacted by the Relying Party to begin a flow. https://op.isam.example.com/isam/oidc/endpoint/FIMDOMAINName-FederationName/authorizeOpenID Connect ProviderToken endpointEndpoint used to exchange an authorization code for a tokenhttps://op.isam.example.com/isam/oidc/endpoint/FIMDOMAINName-FederationName/tokenOpenID Connect ProviderIntrospect endpointUsed to inspect access tokens. https://op.isam.example.com/isam/oidc/endpoint/FIMDOMAINName-FederationName/introspectOpenID Connect ProviderOpenID Connect federationsThe Federation Module supports OpenID Connect federations.Relying Party SSO initiation endpointRequests to the SSO initiation endpoint are used to initiate a sign on from another identity provider or OpenID Connect Provider.Redirect URIThe redirect URI is where the user will be directed back to after authenticating and consenting at the OP. This URL requires unauthenticated access through the web reverse proxy. OpenID Connect Provider authorize endpointThe authorize endpoint is the first endpoint used by a Relying Party when making a request for a users identity. Requests to the authorize endpoint include a large number of parameters depending on what sort of flow is being requested by the Relying Party. Token endpointA request to the token endpoint is used to exchange an authorization code for an access token. Introspect endpointRequests to the introspection endpoint can be made by a relying party to check the validity of an access token they have been issued. This endpoint is not used as part of an SSO operation, but is available for use.

OpenID Connect endpoints

OpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance.

All URLs use the following base path:

https://<ReverseProxy  Hostname>:<Port>/<ISAM Runtime Junction>/

For example: https://isam.example.com/isam/

The base of all URL is: /oidc/endpoint/amapp-runtime-myFederationName/

Request URL to /authorize would be: https://isam.example.com/isam/oidc/endpoint/amapp-runtime-myfederation/authorize

The URLs are as follows:

Name | Description | URL | Role
Relying Party initiation Endpoint | Initiates login to this Reverse Proxy instance using an identity from an external OP. The query string parameter denotes what OP is contacted for the login. | https://rp.isam.example.com/isam/sps/oidc/client/FederationName/oidc_client=?FIMDOMAINName-PartnerAppliesTo | Relying Party
Relying Party Redirect URI | This is the URL a user will be redirected to after logging in at the OP. It requires unauthenticated access. | https://rp.isam.example.com/isam/oidcclient/redirect/FIMDOMAINName-PartnerAppliesTo | Relying Party
Authorize endpoint | The initial endpoint contacted by the Relying Party to begin a flow. | https://op.isam.example.com/isam/oidc/endpoint/FIMDOMAINName-FederationName/authorize | OpenID Connect Provider
Token endpoint | Endpoint used to exchange an authorization code for a token | https://op.isam.example.com/isam/oidc/endpoint/FIMDOMAINName-FederationName/token | OpenID Connect Provider
Introspect endpoint | Used to inspect access tokens. | https://op.isam.example.com/isam/oidc/endpoint/FIMDOMAINName-FederationName/introspect | OpenID Connect Provider

Relying Party SSO initiation endpoint
Requests to the SSO initiation endpoint are used to initiate a sign on from another identity provider or OpenID Connect Provider.

Redirect URI
The redirect URI is where the user will be directed back to after authenticating and consenting at the OP. This URL requires unauthenticated access through the web reverse proxy.

OpenID Connect Provider authorize endpoint
The authorize endpoint is the first endpoint used by a Relying Party when making a request for a users identity. Requests to the authorize endpoint include a large number of parameters depending on what sort of flow is being requested by the Relying Party.

Token endpoint
A request to the token endpoint is used to exchange an authorization code for an access token.

Introspect endpoint
Requests to the introspection endpoint can be made by a relying party to check the validity of an access token they have been issued. This endpoint is not used as part of an SSO operation, but is available for use.

Parent topic: OpenID Connect federations

Relying Party SSO initiation endpointRequests to the SSO initiation endpoint are used to initiate a sign on from another identity provider or OpenID Connect Provider.Use the following URL:https://<ReverseProxy hostname:Port/isam junction, usually isam>/sps/oidc/client/<FederationName>Requests to this endpoint should use the HTTP method GET or POST and include the following query string parameters:KeyDescriptionValueRequiredoidc_clientCombination of domain and name of the Relying Party. For example, amapp-runtime-isamRPUser-definedTruetargetURL that to redirect users to after the authentication.User-definedFalseThe value used for the ID in the request will be a combination of $domain-$name, where name is the value provided when creating this Relying Party partner.An example URL is: https://myRpISAM.com/isam/sps/oidc/client/RP?oidc_client=amapp-runtime-googleWhere the federation name is RP, and the client appliesTo value is google.OpenID Connect endpointsOpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance.

Relying Party SSO initiation endpoint

Requests to the SSO initiation endpoint are used to initiate a sign on from another identity provider or OpenID Connect Provider.

Use the following URL:

https://<ReverseProxy hostname:Port/isam junction, usually isam>/sps/oidc/client/<FederationName>

Requests to this endpoint should use the HTTP method GET or POST and include the following query string parameters:

Key | Description | Value | Required
oidc_client | Combination of domain and name of the Relying Party. For example, amapp-runtime-isamRP | User-defined | True
target | URL that to redirect users to after the authentication. | User-defined | False

The value used for the ID in the request will be a combination of $domain-$name, where name is the value provided when creating this Relying Party partner.

An example URL is: https://myRpISAM.com/isam/sps/oidc/client/RP?oidc_client=amapp-runtime-google

Where the federation name is RP, and the client appliesTo value is google.

Parent topic: OpenID Connect endpoints

Redirect URIThe redirect URI is where the user will be directed back to after authenticating and consenting at the OP. This URL requires unauthenticated access through the web reverse proxy. An example URL is: https://<ReverseProxy Hostname:Port>/<isam junction usually isam>/oidcclient/FIMDOMAINName-PartnerAppliesTo.The request will contain query string parameters that are populated by the OP. OpenID Connect endpointsOpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance.

Redirect URI

The redirect URI is where the user will be directed back to after authenticating and consenting at the OP. This URL requires unauthenticated access through the web reverse proxy.

An example URL is: https://<ReverseProxy Hostname:Port>/<isam junction usually isam>/oidcclient/FIMDOMAINName-PartnerAppliesTo.

The request will contain query string parameters that are populated by the OP.

Parent topic: OpenID Connect endpoints

OpenID Connect Provider authorize endpointThe authorize endpoint is the first endpoint used by a Relying Party when making a request for a users identity. Requests to the authorize endpoint include a large number of parameters depending on what sort of flow is being requested by the Relying Party. Requests to the authorize endpoint should use the HTTP method GET or POST and can contain the following parameters.KeyDescriptionValueRequiredresponse_typeThe method which the OpenID Connect Provider should response to the clients authorize request. code, token, id_token tokenTrueredirect_uriThe URI to redirect the users browser to after the authorizationUser-definedFalseclient_idClient ID of the partner. Set when creating the partner to the OP federation. User-defined TruescopeThe scope of the grant to request from the user. Space separated string that must include openidTruestateOpaque string used to maintain state between request and responseCharacter stringFalsenonceUsed to prevent requests from being processed multiple times.Character stringFalseOpenID Connect endpointsOpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance.

OpenID Connect Provider authorize endpoint

The authorize endpoint is the first endpoint used by a Relying Party when making a request for a users identity. Requests to the authorize endpoint include a large number of parameters depending on what sort of flow is being requested by the Relying Party.

Requests to the authorize endpoint should use the HTTP method GET or POST and can contain the following parameters.

Key | Description | Value | Required
response_type | The method which the OpenID Connect Provider should response to the clients authorize request. | code, token, id_token token | True
redirect_uri | The URI to redirect the users browser to after the authorization | User-defined | False
client_id | Client ID of the partner. Set when creating the partner to the OP federation. | User-defined | True
scope | The scope of the grant to request from the user. | Space separated string that must include openid | True
state | Opaque string used to maintain state between request and response | Character string | False
nonce | Used to prevent requests from being processed multiple times. | Character string | False

Parent topic: OpenID Connect endpoints

Token endpointA request to the token endpoint is used to exchange an authorization code for an access token. Requests to the token endpoint are authenticated using client credentials through either basic authentication or by including them as post parameters depending on the clients configuration. All requests to the token endpoint should be an HTTP POST. This URL requires unauthenticated access through the reverse proxy.The following table lists the expected post parameters.KeyDescriptionValueRequiredgrant_typeThe type of grant to be issuedauthorization_code, refresh_tokenTruecodeThe authorization code to be exchanged.Opaque valueTrue – When grant_type is authorization_coderefresh_tokenThe refresh token to be exchangedOpaque valueTrue – When grant_type is refresh_tokenredirect_uriThe redirect URI must be the same as the redirect URI used in the authorization request.Redirect_uri specified in the initial request to /authorizeTrue – When grant_type is authorization_codeclient_idClient ID, set when creating the partner to the OP federation.User-definedFalse - When using BA authenticationclient_secretClient Secret set when creating the partner to the OP federation.User-definedFalse - When using BA authenticationOpenID Connect endpointsOpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance.

Token endpoint

A request to the token endpoint is used to exchange an authorization code for an access token.

Requests to the token endpoint are authenticated using client credentials through either basic authentication or by including them as post parameters depending on the clients configuration. All requests to the token endpoint should be an HTTP POST. This URL requires unauthenticated access through the reverse proxy.

The following table lists the expected post parameters.

Key | Description | Value | Required
grant_type | The type of grant to be issued | authorization_code, refresh_token | True
code | The authorization code to be exchanged. | Opaque value | True – When grant_type is authorization_code
refresh_token | The refresh token to be exchanged | Opaque value | True – When grant_type is refresh_token
redirect_uri | The redirect URI must be the same as the redirect URI used in the authorization request. | Redirect_uri specified in the initial request to /authorize | True – When grant_type is authorization_code
client_id | Client ID, set when creating the partner to the OP federation. | User-defined | False - When using BA authentication
client_secret | Client Secret set when creating the partner to the OP federation. | User-defined | False - When using BA authentication

Parent topic: OpenID Connect endpoints

Introspect endpointRequests to the introspection endpoint can be made by a relying party to check the validity of an access token they have been issued. This endpoint is not used as part of an SSO operation, but is available for use.Requests to the introspection endpoint may be either a HTTP GET or POST. When using GET, the client must authenticate with BA; when using POST the client may authenticate with BA or by including client credentials in the post data. KeyDescriptionValueRequiredtokenThe access token to inspectUser-definedTrueclient_idClient ID, used if post parameters are the authentication methodUser-definedFalseclient_secretClient Secret, used if post parameters are the authentication methodUser-definedFalseOpenID Connect endpointsOpenID Connect endpoints define interfaces through which applications may communicate with an OpenID Connect Provider (OP) or Relying Party (RP) instance running on an appliance.

Introspect endpoint

Requests to the introspection endpoint can be made by a relying party to check the validity of an access token they have been issued. This endpoint is not used as part of an SSO operation, but is available for use.

Requests to the introspection endpoint may be either a HTTP GET or POST. When using GET, the client must authenticate with BA; when using POST the client may authenticate with BA or by including client credentials in the post data.

Key | Description | Value | Required
token | The access token to inspect | User-defined | True
client_id | Client ID, used if post parameters are the authentication method | User-defined | False
client_secret | Client Secret, used if post parameters are the authentication method | User-defined | False

Parent topic: OpenID Connect endpoints

OpenID Connect flowsThe OpenID Connect support in IBM Security Access Manager provides two different ways for a Relying Party to obtain access to a protected resource.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.Authorization code flowThe authorization code flow returns an authorization code to the Relying Party, which can then directly exchange it for an ID token and access token.Implicit grant flowThe implicit flow can be used by Relying Parties with an in-browser scripting language component.

OpenID Connect flows

The OpenID Connect support in IBM Security Access Manager provides two different ways for a Relying Party to obtain access to a protected resource.

Authorization code flow
The authorization code flow returns an authorization code to the Relying Party, which can then directly exchange it for an ID token and access token.

Implicit grant flow
The implicit flow can be used by Relying Parties with an in-browser scripting language component.

Parent topic: OpenID Connect federations

Authorization code flowThe authorization code flow returns an authorization code to the Relying Party, which can then directly exchange it for an ID token and access token. This mechanism provides the benefit of not exposing any tokens to the browser or end-user. The OpenID Connect Provider also authenticates the Relying Party before exchanging the authorization code for an access token. The authorization code flow is suitable for Relying Parties that can securely maintain a client secret between themselves and the OpenID Connect Provider.The authorization code flow involves the following steps:The Relying Party initiates the flow when it directs the user agent of the resource owner to the authorization endpoint. The Relying Party includes its client identifier, requested scope (which must include "openid"), local state, and a redirection URI. The OpenID Connect Provider sends the user agent back to the redirection URI after access is granted or denied. The OpenID Connect Provider authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request. If the resource owner grants access, the Relying Party uses the redirection URI provided earlier to redirect the user agent back to the Relying Party. The redirection URI includes an authorization code and any local state previously provided by the Relying Party. The Relying Party requests an access token and ID token from the OpenID Connect Provider through the token endpoint. The Relying Party authenticates with its client credentials and includes the authorization code received in the previous step. The Relying Party also includes the redirection URI used to obtain the authorization code for verification. The OpenID Connect Provider validates the client credentials and the authorization code. The server also ensures that the redirection URI received matches the URI used to redirect the client in Step 3. If valid, the OpenID Connect Provider responds back with an access token and ID token.OpenID Connect flowsThe OpenID Connect support in IBM Security Access Manager provides two different ways for a Relying Party to obtain access to a protected resource.

Authorization code flow

The authorization code flow returns an authorization code to the Relying Party, which can then directly exchange it for an ID token and access token.

This mechanism provides the benefit of not exposing any tokens to the browser or end-user. The OpenID Connect Provider also authenticates the Relying Party before exchanging the authorization code for an access token. The authorization code flow is suitable for Relying Parties that can securely maintain a client secret between themselves and the OpenID Connect Provider.

The authorization code flow involves the following steps:

The Relying Party initiates the flow when it directs the user agent of the resource owner to the authorization endpoint. The Relying Party includes its client identifier, requested scope (which must include "openid"), local state, and a redirection URI. The OpenID Connect Provider sends the user agent back to the redirection URI after access is granted or denied.

The OpenID Connect Provider authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.

If the resource owner grants access, the Relying Party uses the redirection URI provided earlier to redirect the user agent back to the Relying Party. The redirection URI includes an authorization code and any local state previously provided by the Relying Party.

The Relying Party requests an access token and ID token from the OpenID Connect Provider through the token endpoint. The Relying Party authenticates with its client credentials and includes the authorization code received in the previous step. The Relying Party also includes the redirection URI used to obtain the authorization code for verification.

The OpenID Connect Provider validates the client credentials and the authorization code. The server also ensures that the redirection URI received matches the URI used to redirect the client in Step 3. If valid, the OpenID Connect Provider responds back with an access token and ID token.

Parent topic: OpenID Connect flows

Implicit grant flowThe implicit flow can be used by Relying Parties with an in-browser scripting language component. The access token and ID token are returned directly to the Relying Party, which may expose them to the end-user and applications that have access to the end-user's browser. The token endpoint is not used and the OpenID Connect Provider does not perform authentication on the Relying Party in this flow. The Relying Party does not have to directly communicate with the OpenID Connect Provider as all interactions can be performed through the browser.The implicit grant flow involves the following steps:The Relying Party initiates the flow by directing the user agent of the resource owner to the authorization endpoint. The Relying Party includes its client identifier, requested scope (which must include "openid"), local state, desired response type and response mode, and a redirection URI. The OpenID Connect Provider sends the user agent back to the redirection URI after access is granted or denied.The OpenID Connect Provider authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request. If the resource owner grants access, the OpenID Connect Provider redirects the user agent back to the client using the redirection URI provided earlier. The redirection URI includes the access token and ID token in the URI fragment.The user agent follows the redirection instructions by making a request to the web server without the fragment. The user agent retains the fragment information locally. The web server returns a web page, which is typically an HTML document with an embedded script. The web page accesses the full redirection URI including the fragment retained by the user agent. It can also extract the access token, ID token and other parameters contained in the fragment. The user agent runs the script provided by the web server locally, which extracts the access token and ID token and passes it to the client. OpenID Connect flowsThe OpenID Connect support in IBM Security Access Manager provides two different ways for a Relying Party to obtain access to a protected resource.

Implicit grant flow

The implicit flow can be used by Relying Parties with an in-browser scripting language component.

The access token and ID token are returned directly to the Relying Party, which may expose them to the end-user and applications that have access to the end-user's browser. The token endpoint is not used and the OpenID Connect Provider does not perform authentication on the Relying Party in this flow. The Relying Party does not have to directly communicate with the OpenID Connect Provider as all interactions can be performed through the browser.

The implicit grant flow involves the following steps:

The Relying Party initiates the flow by directing the user agent of the resource owner to the authorization endpoint. The Relying Party includes its client identifier, requested scope (which must include "openid"), local state, desired response type and response mode, and a redirection URI. The OpenID Connect Provider sends the user agent back to the redirection URI after access is granted or denied.

The OpenID Connect Provider authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.

If the resource owner grants access, the OpenID Connect Provider redirects the user agent back to the client using the redirection URI provided earlier. The redirection URI includes the access token and ID token in the URI fragment.

The user agent follows the redirection instructions by making a request to the web server without the fragment. The user agent retains the fragment information locally.

The web server returns a web page, which is typically an HTML document with an embedded script. The web page accesses the full redirection URI including the fragment retained by the user agent. It can also extract the access token, ID token and other parameters contained in the fragment.

The user agent runs the script provided by the web server locally, which extracts the access token and ID token and passes it to the client.

Parent topic: OpenID Connect flows

Configuring OpenID Connect Providers (OP)An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities. A partner to this OP federation represents an OpenID Connect Client which may be configured as a partner to a Relying Party (RP) federation on a different appliance, or used as a standalone OpenID Connect Partner to consume identities from this appliance. OpenID Connect federationsThe Federation Module supports OpenID Connect federations.Configuring an OpenID Connect Provider federationAn OpenID Connect Provider Federation is configured with the Federations page in the local management interface.OpenID Connect Provider federation propertiesDefine these properties when you configure an OpenID Connect Provider federation.Configuring an OpenID Connect Provider (OP) partnerConfiguring a OpenID Connect Provider Partner creates a entity at the provider that represents an OpenID Connect Client. This might be a standalone client, or a partner to a Relying Party federation on an appliance. Use the partners UI in the local management interface to complete this configuration.OpenID Connect Provider partner propertiesDefine these properties when you configure an OpenID Connect Provider partner.

Configuring OpenID Connect Providers (OP)

An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities.

A partner to this OP federation represents an OpenID Connect Client which may be configured as a partner to a Relying Party (RP) federation on a different appliance, or used as a standalone OpenID Connect Partner to consume identities from this appliance.

Configuring an OpenID Connect Provider federation
An OpenID Connect Provider Federation is configured with the Federations page in the local management interface.

OpenID Connect Provider federation properties
Define these properties when you configure an OpenID Connect Provider federation.

Configuring an OpenID Connect Provider (OP) partner
Configuring a OpenID Connect Provider Partner creates a entity at the provider that represents an OpenID Connect Client. This might be a standalone client, or a partner to a Relying Party federation on an appliance. Use the partners UI in the local management interface to complete this configuration.

OpenID Connect Provider partner properties
Define these properties when you configure an OpenID Connect Provider partner.

Parent topic: OpenID Connect federations

Configuring an OpenID Connect Provider federationAn OpenID Connect Provider Federation is configured with the Federations page in the local management interface.This topic focuses on the procedure. For more information about what each field means, see OpenID Connect Provider federation propertiesDefine these properties when you configure an OpenID Connect Provider federation..Log in to the local management console.Select Secure FederationManageFederations.Click Add.Enter a federation name.Select the OpenID Connect as the protocol.Click Next.Select the OpenID Connect Provider option.Select a signature algorithm. If RS256 signing is selected, select a keystore and certificate from the list.Click Next.Select the grants this OP issues. Optionally, adjust any of the timeouts or lengths.Click Next.Select the method for identity mapping.Review the Summary page.Click OK to create the federation.Configuring OpenID Connect Providers (OP)An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities.

Configuring an OpenID Connect Provider federation

An OpenID Connect Provider Federation is configured with the Federations page in the local management interface.

About this task

This topic focuses on the procedure. For more information about what each field means, see OpenID Connect Provider federation properties.

Procedure

Log in to the local management console.

Select Secure Federation > Manage > Federations.

Click Add.

Enter a federation name.

Select the OpenID Connect as the protocol.

Click Next.

Select the OpenID Connect Provider option.

Select a signature algorithm. If RS256 signing is selected, select a keystore and certificate from the list.

Click Next.

Select the grants this OP issues. Optionally, adjust any of the timeouts or lengths.

Click Next.

Select the method for identity mapping.

Review the Summary page.

Click OK to create the federation.

Parent topic: Configuring OpenID Connect Providers (OP)

OpenID Connect Provider federation propertiesDefine these properties when you configure an OpenID Connect Provider federation.Federation NameThis serves as the primary runtime identifier of the federation. This value appears in the authorize, token, and introspect endpoints. This value must be unique. It must not contain characters that require URL encoding. Issuer IdentifierThis value appears in the iss claim of JWTs issued by this OP. This value must be a valid HTTPS URL. It must not contain query string parameters or any fragment information.Signature AlgorithmThis value specifies the method by which the JWTs are signed. Valid values are:HS256HS256 signing requires the partners to have a client secret to perform signing with. The shared secret used to sign a JWT for a partner is the lowercase hexadecimal representation of the client secret configured for that partner.RS256RS256 signing requires a keystore and certificate.NoneNo signing is performed.Signing KeystoreKeystore to look for the provided keystore lable. Only valid when performing RS256 signing.Signing CertificateLabel of the certificate to be used to perform RS256 signing. Only valid when performing RS256 signing. GrantsThis value overwrites any grants requested in a partners configuration. Valid values are:authorization_codeimplicitrefresh_token (Requires that the authorization_code grant is enabled.)Timeouts and LengthsCharacter lengths of created tokens can be configured on this page, as well as the lengths of time for which tokens and grants are valid.Authorization Code Lifetime (Seconds)The time in seconds for which a authorization code is valid and can be exchanged for a token at the token endpoint.Authorization Code LengthCharacter length of an issued authorization code. Value must range from 1 – 254.Refresh Token Length Character length of an issued refresh code. Value must range from 1 – 254.Access Token LengthCharacter length of an issued access code. Value must range from 1 – 254.Access Token Lifetime (Seconds) The time in seconds for which an access token is considered valid by the OP. The validity of an access token can be checked at the introspect endpoint.Authorization Grant Lifetime (Seconds)Time in seconds which the users authorization is valid.ID Token Lifetime (Seconds)The time that the issued JWT is valid for. This is indicated as the difference between the iat (issued at) and exp (expires at) claims of the issued JWT.Configuring OpenID Connect Providers (OP)An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities.

OpenID Connect Provider federation properties

Define these properties when you configure an OpenID Connect Provider federation.

Federation Name

This serves as the primary runtime identifier of the federation. This value appears in the authorize, token, and introspect endpoints. This value must be unique. It must not contain characters that require URL encoding.

Issuer Identifier

This value appears in the iss claim of JWTs issued by this OP. This value must be a valid HTTPS URL. It must not contain query string parameters or any fragment information.

Signature Algorithm

This value specifies the method by which the JWTs are signed. Valid values are:

HS256

HS256 signing requires the partners to have a client secret to perform signing with. The shared secret used to sign a JWT for a partner is the lowercase hexadecimal representation of the client secret configured for that partner.

RS256

RS256 signing requires a keystore and certificate.

None

No signing is performed.

Signing Keystore

Keystore to look for the provided keystore lable. Only valid when performing RS256 signing.

Signing Certificate

Label of the certificate to be used to perform RS256 signing. Only valid when performing RS256 signing.

Grants

This value overwrites any grants requested in a partners configuration. Valid values are:

authorization_code

implicit

refresh_token (Requires that the authorization_code grant is enabled.)

Timeouts and Lengths

Character lengths of created tokens can be configured on this page, as well as the lengths of time for which tokens and grants are valid.

Authorization Code Lifetime (Seconds)

The time in seconds for which a authorization code is valid and can be exchanged for a token at the token endpoint.

Authorization Code Length

Character length of an issued authorization code. Value must range from 1 – 254.

Refresh Token Length

Character length of an issued refresh code. Value must range from 1 – 254.

Access Token Length

Character length of an issued access code. Value must range from 1 – 254.

Access Token Lifetime (Seconds)

The time in seconds for which an access token is considered valid by the OP. The validity of an access token can be checked at the introspect endpoint.

Authorization Grant Lifetime (Seconds)

Time in seconds which the users authorization is valid.

ID Token Lifetime (Seconds)

The time that the issued JWT is valid for. This is indicated as the difference between the iat (issued at) and exp (expires at) claims of the issued JWT.

Parent topic: Configuring OpenID Connect Providers (OP)

Configuring an OpenID Connect Provider (OP) partnerConfiguring a OpenID Connect Provider Partner creates a entity at the provider that represents an OpenID Connect Client. This might be a standalone client, or a partner to a Relying Party federation on an appliance. Use the partners UI in the local management interface to complete this configuration.This topic focuses on the procedure. For more information about what each field means, see OpenID Connect Provider partner propertiesDefine these properties when you configure an OpenID Connect Provider partner..Log in to the local management console.Select Secure FederationManageFederations.All existing federations are displayed in the list.Select the federation you want to add a partner to.Click Partners.Click Add.Enter a name for the partner.Select the Enabled check box.Click Next.Enter a client ID. To automatically generated the client ID, select the Generate check box.Enter a client secret. To automatically generate the client secret, select the Generate check box. You can choose to not provide a client secret.A client secret does not have to be specified. If a client secret is not specifies, a public client is created. Public clients do not have access to all the features of a confidential (client secret set) client.Click Next.Enter a client name.Select the response types.Enter the redirect URIs of this client. More than one redirect URI can be entered by clicking New to add a new row to the display.Enter the scopes this client is allowed to request.Optionally select the check box next to any scope to preauthorize this scope. Any scopes that are preauthorized will not appear in any consent request, and the OP acts as if this scope was consented to by the user.Review the partner summary.Click OK.Configuring OpenID Connect Providers (OP)An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities.

Configuring an OpenID Connect Provider (OP) partner

Configuring a OpenID Connect Provider Partner creates a entity at the provider that represents an OpenID Connect Client. This might be a standalone client, or a partner to a Relying Party federation on an appliance. Use the partners UI in the local management interface to complete this configuration.

About this task

This topic focuses on the procedure. For more information about what each field means, see OpenID Connect Provider partner properties.

Procedure

Log in to the local management console.

Select Secure Federation > Manage > Federations. All existing federations are displayed in the list.

Select the federation you want to add a partner to.

Click Partners.

Click Add.

Enter a name for the partner.

Select the Enabled check box.

Click Next.

Enter a client ID. To automatically generated the client ID, select the Generate check box.

Enter a client secret. To automatically generate the client secret, select the Generate check box. You can choose to not provide a client secret.

Note: A client secret does not have to be specified. If a client secret is not specifies, a public client is created. Public clients do not have access to all the features of a confidential (client secret set) client.

Click Next.

Enter a client name.

Select the response types.

Enter the redirect URIs of this client. More than one redirect URI can be entered by clicking New to add a new row to the display.

Enter the scopes this client is allowed to request. Optionally select the check box next to any scope to preauthorize this scope. Any scopes that are preauthorized will not appear in any consent request, and the OP acts as if this scope was consented to by the user.

Review the partner summary.

Click OK.

Parent topic: Configuring OpenID Connect Providers (OP)

OpenID Connect Provider partner propertiesDefine these properties when you configure an OpenID Connect Provider partner.Client ID This ID can be generated when the partner is created by checking the Generate check box. The value must be unique. It cannot be changed after partner creation.Client SecretThis secret be generated when the partner is created by checking the Generate check box. Leaving the property empty creates a public client. If a public client is created, the following limitations apply:HS256 signing cannot be performed, as this requires the client secret to be used as the key.Authorization code flows cannot be performed.The client is not able to authenticate to either the Token or Introspection endpoints.Client NameDisplay name for this client at runtime. If this value is not specified, the partner name is used.Redirect URIsValid values to be provided as the redirect_uri parameter in an authorize request. At least one must be specified. This value must be a valid URL.Response TypesValues that are allowed in the response_type parameter in an authorize request. Valid values are:codeid_token tokentokenSpecifying only id_token token is not supported. Allow Refresh Token GrantAllows exchange of refresh token for an access token. Requires a client secret.Allow Token Introspection:Allows the client to make requests on the introspection endpoint. Requires a client secret.Token endpoint authentication methodHow it is expected that this client will authenticate to the token endpoint. Valid values are:clientSecretBasic – To expect the Authroization HTTP header.clientSecretPost – To expect the parameters client_id and client_secret in the post body.ScopeThe scopes that can be requested by this client. The value must include openid.Preauthorized ScopeScopes for which consent is automatically granted. If all of the scopes provided in a request to the authorization endpoint are preauthorized, the user is not prompted for consent before being redirected. Configuring OpenID Connect Providers (OP)An OpenID Connect Provider is capable of issuing identities to Relying Parties. The OP federation represents the entity which issues the identities.

OpenID Connect Provider partner properties

Define these properties when you configure an OpenID Connect Provider partner.

Client ID

This ID can be generated when the partner is created by checking the Generate check box. The value must be unique. It cannot be changed after partner creation.

Client Secret

This secret be generated when the partner is created by checking the Generate check box. Leaving the property empty creates a public client. If a public client is created, the following limitations apply:

HS256 signing cannot be performed, as this requires the client secret to be used as the key.

Authorization code flows cannot be performed.

The client is not able to authenticate to either the Token or Introspection endpoints.

Client Name

Display name for this client at runtime. If this value is not specified, the partner name is used.

Redirect URIs

Valid values to be provided as the redirect_uri parameter in an authorize request. At least one must be specified. This value must be a valid URL.

Response Types

Values that are allowed in the response_type parameter in an authorize request. Valid values are:

code

id_token token

token

Note: Specifying only id_token token is not supported.

Allow Refresh Token Grant

Allows exchange of refresh token for an access token. Requires a client secret.

Allow Token Introspection:

Allows the client to make requests on the introspection endpoint. Requires a client secret.

Token endpoint authentication method

How it is expected that this client will authenticate to the token endpoint. Valid values are:

clientSecretBasic – To expect the Authroization HTTP header.

clientSecretPost – To expect the parameters client_id and client_secret in the post body.

Scope

The scopes that can be requested by this client. The value must include openid.

Preauthorized Scope

Scopes for which consent is automatically granted. If all of the scopes provided in a request to the authorization endpoint are preauthorized, the user is not prompted for consent before being redirected.

Parent topic: Configuring OpenID Connect Providers (OP)

Configuring Relying PartiesWhen configuring a OpenID Connect Relying Party two entities must be created - a federation and a parter. There can be multiple partners per federation, but each partner has only one federation.The OpenID Connect Relying Party federation does not do anything on its own - it just serves as a container for the partners. Each OpenID Connect Relying Party Partner is a entity which consumes identities from a given OpenID Connect Provider. For more information on Relying Parties see:http://openid.net/specs/openid-connect-basic-1_0.htmlhttp://openid.net/specs/openid-connect-implicit-1_0.htmlOpenID Connect federationsThe Federation Module supports OpenID Connect federations.Configuring a relying party federationAn OpenID Connect Relying party federation can be configured with the Federations page in the local management interface. Configuring an OpenID Connect Relying Party partnerAn OpenID Connect Relying Party Partner can be configured with the Partners UI in the local management interface. OpenID Connect Relying Party partner propertiesDefine these properties when you configure an OpenID Connect Relying Party partner.

Configuring Relying Parties

When configuring a OpenID Connect Relying Party two entities must be created - a federation and a parter. There can be multiple partners per federation, but each partner has only one federation.

The OpenID Connect Relying Party federation does not do anything on its own - it just serves as a container for the partners. Each OpenID Connect Relying Party Partner is a entity which consumes identities from a given OpenID Connect Provider. For more information on Relying Parties see:

http://openid.net/specs/openid-connect-basic-1_0.html

http://openid.net/specs/openid-connect-implicit-1_0.html

Configuring a relying party federation
An OpenID Connect Relying party federation can be configured with the Federations page in the local management interface.

Configuring an OpenID Connect Relying Party partner
An OpenID Connect Relying Party Partner can be configured with the Partners UI in the local management interface.

OpenID Connect Relying Party partner properties
Define these properties when you configure an OpenID Connect Relying Party partner.

Parent topic: OpenID Connect federations

Configuring a relying party federationAn OpenID Connect Relying party federation can be configured with the Federations page in the local management interface. Log in to the local management console.Select Secure FederationManageFederations.Click Add.Enter a federation name.Select the OpenID Connect as the protocol.Click Next.Select the Relying Party option.Click Next.Select the method of identity mapping.Review the Summary page.Click OK.Deploy the pending changes.The deploy operation triggers a runtime restart.Configuring Relying PartiesWhen configuring a OpenID Connect Relying Party two entities must be created - a federation and a parter. There can be multiple partners per federation, but each partner has only one federation.

Configuring a relying party federation

An OpenID Connect Relying party federation can be configured with the Federations page in the local management interface.

Procedure

Log in to the local management console.

Select Secure Federation > Manage > Federations.

Click Add.

Enter a federation name.

Select the OpenID Connect as the protocol.

Click Next.

Select the Relying Party option.

Click Next.

Select the method of identity mapping.

Review the Summary page.

Click OK.

Deploy the pending changes.

Note: The deploy operation triggers a runtime restart.

Parent topic: Configuring Relying Parties

Configuring an OpenID Connect Relying Party partnerAn OpenID Connect Relying Party Partner can be configured with the Partners UI in the local management interface. This topic focuses on the procedure. For more information about what each field means, see OpenID Connect Relying Party partner propertiesDefine these properties when you configure an OpenID Connect Relying Party partner..Log in to the local management console.Select Secure FederationManageFederations.All existing federations are displayed in the list.Select the federation you want to add a partner to.Click Partners.Click Add.Enter a name for the partner.Select the Enabled check box.Click Next.Enter the client ID of the OpenID Connect client to be used.Enter the client secret of the OpenID Connect client to be used.Click Next.Enter the appliesTo value for this RP. This is the unique ID used in the kickoff URL.Select the grant type this Relying Party (RP) uses.Enter the Authorization endpoint provided by the OpenID Connect Provider (OP) at which this partner was created.Enter the Token endpoint to used for authorization code exchange if the code grant type is selected.Select the signature algorithm to use to verify the ID Token with.If RS256 signing is to be used, select the method used to obtain the public key. Select either a keystore and certificate label, or enter a JWK Endpoint.Click Next.Enter the Issuer identifier provided by the OP at which this partner was created.Enter the RedirectURI Prefix.Click Next.Enter the Scopes this RP will request. Enter one scope per text entry box. To add additional text entry boxes, click New. To delete an unwanted text entry box, select it and click Delete.Enter the Identity Mapping information of this partner.Review the partner summary.Click OK.Configuring Relying PartiesWhen configuring a OpenID Connect Relying Party two entities must be created - a federation and a parter. There can be multiple partners per federation, but each partner has only one federation.

Configuring an OpenID Connect Relying Party partner

An OpenID Connect Relying Party Partner can be configured with the Partners UI in the local management interface.

About this task

This topic focuses on the procedure. For more information about what each field means, see OpenID Connect Relying Party partner properties.

Procedure

Log in to the local management console.

Select Secure Federation > Manage > Federations. All existing federations are displayed in the list.

Select the federation you want to add a partner to.

Click Partners.

Click Add.

Enter a name for the partner.

Select the Enabled check box.

Click Next.

Enter the client ID of the OpenID Connect client to be used.

Enter the client secret of the OpenID Connect client to be used.

Click Next.

Enter the appliesTo value for this RP. This is the unique ID used in the kickoff URL.

Select the grant type this Relying Party (RP) uses.

Enter the Authorization endpoint provided by the OpenID Connect Provider (OP) at which this partner was created.

Enter the Token endpoint to used for authorization code exchange if the code grant type is selected.

Select the signature algorithm to use to verify the ID Token with. If RS256 signing is to be used, select the method used to obtain the public key. Select either a keystore and certificate label, or enter a JWK Endpoint.

Click Next.

Enter the Issuer identifier provided by the OP at which this partner was created.

Enter the RedirectURI Prefix.

Click Next.

Enter the Scopes this RP will request. Enter one scope per text entry box. To add additional text entry boxes, click New. To delete an unwanted text entry box, select it and click Delete.

Enter the Identity Mapping information of this partner.

Review the partner summary.

Click OK.

Parent topic: Configuring Relying Parties

OpenID Connect Relying Party partner propertiesDefine these properties when you configure an OpenID Connect Relying Party partner.Issuer Identifier The expected value of the iss claim in a JWT. If this value does not match the contents of the JWT, then the authentication is rejected.RedirectURI PrefixString containing the protocol, host, port and path of the runtime junction on the Reverse Proxy instance. This is used to automatically generate redirect URIs derived from the applies to value of the partner. An example value for this property is “https://www.reverse.proxy.com:443/isam”, where “www.reverse.proxy.com” is the hostname of the Reverse Proxy instance, “443” is the listening SSL port of the instance, and “/isam” is the local junction to the Federation Runtime. This would, at runtime, provide an endpoint at (example values used) “https://www.reverse.proxy.com:443/isam/oidcclient/redirect/amapp-runtime-examplePartner”.Applies ToThis serves as the primary runtime identifier for a relying party. It must be unique across all federations. It must not contain any characters which require URL encoding. It will be used in the value for the oidc_client query string parameter when initiating a Relying Party flow. Client IDValue used to identify this Relying Party at the OP. This value is required.Client SecretValue used in combination with the Relying Party to authenticate at the OP. Not specifying a Client Secret will indicate that this is a public client. Required to perform the Authorization Code grant. Required to perform HS256 Signing.Authorization endpoint URLEndpoint used to initiate the OpenID Connect flow at the OP.Token endpoint URLEndpoint used to exchange an authorization code for an id token and access token. Required to perform the Authorization Code grant. Requires a client secret to be set.Signature AlgorithmSpecifies the algorithm used to validate the JWT. Valid values are:HS256Performs symmetric signing using a client secret. A client secret is required for HS256 Signing.RS256Performs asymmetric signing using certificates. A JWK endpoint URL or a Signing Key keystore and label is required to perform RS256 signing.NoneA value of none denotes that no signing is performed on the issued JWT.JWK Endpoint URLUsed to fetch the Public Signing Key from the OP at runtime. This field is only valid for RS256 signing. You cannot specify a Signing Key Label when you specify a JWK Endpoint URL. This field is required if you do not specify a Signing Key Label and you specify RS256 signing.Signing KeystoreKeystore to look for the provided keystore lable. Only valid when performing RS256 signing.Signing Key LabelThe signing key to be used in RS256 signing. It specifies a label of a key in the runtime profile key database. The default value for this key database is rt_profile_keys. You cannot specify a JWK Endpoint URL if you specify a Signing Key Label. This field is required if you do not specify a JWK Endpoint URL and you specify RS256 signing.Grant TypeValid grant types are authorization_code and implicit. If the grant type is authorization_code, then requests will use response_type=code. A token URL must be specified. Furthermore, the runtime must be able to successfully connect to the token URL. The partner must have a client secret.If the grant type is implicit, then requests will use response_type=id_token token. Requests will attempt to use response_mode=form_post. If this is not available, then javascript will be sent to retrieve the fragment from the response.ScopeA list of strings showing the scope of authorization delegated to a client. Scope must include openid. Common scopes include profile and email. The email scope usually means the email address of the user will be included in the JWT. The profile scope usually means the first name and last name of the user will be included in the JWT. Configuring Relying PartiesWhen configuring a OpenID Connect Relying Party two entities must be created - a federation and a parter. There can be multiple partners per federation, but each partner has only one federation.

OpenID Connect Relying Party partner properties

Define these properties when you configure an OpenID Connect Relying Party partner.

Issuer Identifier

The expected value of the iss claim in a JWT. If this value does not match the contents of the JWT, then the authentication is rejected.

RedirectURI Prefix

String containing the protocol, host, port and path of the runtime junction on the Reverse Proxy instance. This is used to automatically generate redirect URIs derived from the applies to value of the partner. An example value for this property is “https://www.reverse.proxy.com:443/isam”, where “www.reverse.proxy.com” is the hostname of the Reverse Proxy instance, “443” is the listening SSL port of the instance, and “/isam” is the local junction to the Federation Runtime. This would, at runtime, provide an endpoint at (example values used) “https://www.reverse.proxy.com:443/isam/oidcclient/redirect/amapp-runtime-examplePartner”.

Applies To

This serves as the primary runtime identifier for a relying party. It must be unique across all federations. It must not contain any characters which require URL encoding. It will be used in the value for the oidc_client query string parameter when initiating a Relying Party flow.

Client ID

Value used to identify this Relying Party at the OP. This value is required.

Client Secret

Value used in combination with the Relying Party to authenticate at the OP. Not specifying a Client Secret will indicate that this is a public client. Required to perform the Authorization Code grant. Required to perform HS256 Signing.

Authorization endpoint URL

Endpoint used to initiate the OpenID Connect flow at the OP.

Token endpoint URL

Endpoint used to exchange an authorization code for an id token and access token. Required to perform the Authorization Code grant. Requires a client secret to be set.

Signature Algorithm

Specifies the algorithm used to validate the JWT. Valid values are:

HS256

Performs symmetric signing using a client secret. A client secret is required for HS256 Signing.

RS256

Performs asymmetric signing using certificates. A JWK endpoint URL or a Signing Key keystore and label is required to perform RS256 signing.

None

A value of none denotes that no signing is performed on the issued JWT.

JWK Endpoint URL

Used to fetch the Public Signing Key from the OP at runtime. This field is only valid for RS256 signing. You cannot specify a Signing Key Label when you specify a JWK Endpoint URL. This field is required if you do not specify a Signing Key Label and you specify RS256 signing.

Signing Keystore

Keystore to look for the provided keystore lable. Only valid when performing RS256 signing.

Signing Key Label

The signing key to be used in RS256 signing. It specifies a label of a key in the runtime profile key database. The default value for this key database is rt_profile_keys. You cannot specify a JWK Endpoint URL if you specify a Signing Key Label. This field is required if you do not specify a JWK Endpoint URL and you specify RS256 signing.

Grant Type

Valid grant types are authorization_code and implicit.

If the grant type is authorization_code, then requests will use response_type=code. A token URL must be specified. Furthermore, the runtime must be able to successfully connect to the token URL. The partner must have a client secret.

If the grant type is implicit, then requests will use response_type=id_token token. Requests will attempt to use response_mode=form_post. If this is not available, then javascript will be sent to retrieve the fragment from the response.

Scope

A list of strings showing the scope of authorization delegated to a client. Scope must include openid. Common scopes include profile and email. The email scope usually means the email address of the user will be included in the JWT. The profile scope usually means the first name and last name of the user will be included in the JWT.

Parent topic: Configuring Relying Parties

OpenID Connect mapping rulesMapping rules allow users to customize the information that is propagated from an OpenID Connect Provider or what is consumed by a Relying Party. These mapping rules can either be JavaScript, which is invoked internally via the STS, or the mapping can be performed externally via a HTTP request.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.OpenID Connect Provider mapping rulesWhen you write mapping rules for a provider, the primary goal is to augment the claims that are included in the ID token. OpenID Connect Relying Party mapping rulesWhen you write mapping rules for a Relying Party, the resulting STSUU is turned into a PAC that is used to authenticate the user to a Reverse Proxy via EAI.Attribute sourcesBoth OpenID Connect Providers and Relying Parties can be configured to use an attribute source.

OpenID Connect mapping rules

Mapping rules allow users to customize the information that is propagated from an OpenID Connect Provider or what is consumed by a Relying Party.

These mapping rules can either be JavaScript, which is invoked internally via the STS, or the mapping can be performed externally via a HTTP request.

OpenID Connect Provider mapping rules
When you write mapping rules for a provider, the primary goal is to augment the claims that are included in the ID token.

OpenID Connect Relying Party mapping rules
When you write mapping rules for a Relying Party, the resulting STSUU is turned into a PAC that is used to authenticate the user to a Reverse Proxy via EAI.

Attribute sources
Both OpenID Connect Providers and Relying Parties can be configured to use an attribute source.

Parent topic: OpenID Connect federations

OpenID Connect Provider mapping rulesWhen you write mapping rules for a provider, the primary goal is to augment the claims that are included in the ID token. After mapping rule execution, all attributes in the STSUU will be added to the id_token as a claim, where the attribute key is the key in the id_token, and the value is the value of the attribute. If there are several attributes with the same key, then an array containing each attribute will be added to the claim. Some context information is made available to the user when writing mapping rules; the context attributes of the passed in STSUU will contain attributes with the type “urn:ibm:ITFIM:oidc:provider:context”, which can be used to make decisions on what claims are added, or if any other actions are performed. These context attributes include:The client ID of the client making the request.The federation name of the provider servicing the request.The redirect URI sent in the request.The response type of the request.The state parameter of the request.The user-consented scopes for the request.OpenID Connect mapping rulesMapping rules allow users to customize the information that is propagated from an OpenID Connect Provider or what is consumed by a Relying Party.

OpenID Connect Provider mapping rules

When you write mapping rules for a provider, the primary goal is to augment the claims that are included in the ID token.

After mapping rule execution, all attributes in the STSUU will be added to the id_token as a claim, where the attribute key is the key in the id_token, and the value is the value of the attribute. If there are several attributes with the same key, then an array containing each attribute will be added to the claim. Some context information is made available to the user when writing mapping rules; the context attributes of the passed in STSUU will contain attributes with the type “urn:ibm:ITFIM:oidc:provider:context”, which can be used to make decisions on what claims are added, or if any other actions are performed.

These context attributes include:

The client ID of the client making the request.

The federation name of the provider servicing the request.

The redirect URI sent in the request.

The response type of the request.

The state parameter of the request.

The user-consented scopes for the request.

Parent topic: OpenID Connect mapping rules

OpenID Connect Relying Party mapping rulesWhen you write mapping rules for a Relying Party, the resulting STSUU is turned into a PAC that is used to authenticate the user to a Reverse Proxy via EAI. The attributes that are included in that PAC will be the attributes of the STSUU, and the principal will be the first principal which was in the STSUU. When writing mapping rules for a Relying Party, the values of the id_token, as well as some additional context are made available to the user via the STSUU's context attributes. These attributes will have the types “urn:ibm:ITFIM:oidc:client:idtoken:param” and “urn:ibm:ITFIM:oidc:client:token:param”.These context attributes include:All of the claims inside the id_token.The raw JWT.Any issued access or refresh tokens.All of the properties of the issued bearer token if an authorization code flow is used.All of the parameters issued in the response if an implicit flow is used.OpenID Connect mapping rulesMapping rules allow users to customize the information that is propagated from an OpenID Connect Provider or what is consumed by a Relying Party.

OpenID Connect Relying Party mapping rules

When you write mapping rules for a Relying Party, the resulting STSUU is turned into a PAC that is used to authenticate the user to a Reverse Proxy via EAI.

The attributes that are included in that PAC will be the attributes of the STSUU, and the principal will be the first principal which was in the STSUU. When writing mapping rules for a Relying Party, the values of the id_token, as well as some additional context are made available to the user via the STSUU's context attributes. These attributes will have the types “urn:ibm:ITFIM:oidc:client:idtoken:param” and “urn:ibm:ITFIM:oidc:client:token:param”.

These context attributes include:

All of the claims inside the id_token.

The raw JWT.

Any issued access or refresh tokens.

All of the properties of the issued bearer token if an authorization code flow is used.

All of the parameters issued in the response if an implicit flow is used.

Parent topic: OpenID Connect mapping rules

Attribute sourcesBoth OpenID Connect Providers and Relying Parties can be configured to use an attribute source.For an OpenID Connect Provider, this can be used instead of a mapping rule. However for an OpenID Connect Relying Party a mapping rule must still be present, this mapping rule is required to construct the principal used in the iv-cred.For more information about attribute sources, see Managing attribute sourcesUse the Attribute Source management page to add, edit, or delete your identity attribute sources..OpenID Connect mapping rulesMapping rules allow users to customize the information that is propagated from an OpenID Connect Provider or what is consumed by a Relying Party.

Attribute sources

Both OpenID Connect Providers and Relying Parties can be configured to use an attribute source.

For an OpenID Connect Provider, this can be used instead of a mapping rule. However for an OpenID Connect Relying Party a mapping rule must still be present, this mapping rule is required to construct the principal used in the iv-cred.

For more information about attribute sources, see Managing attribute sources.

Parent topic: OpenID Connect mapping rules

Accessing identity information from a reverse proxyBy using an OpenID Connect Relying Party for authentication, a Reverse Proxy can be configured to provide identity information to junctioned applications.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.Triggering OpenID Connect authenticationAfter a Relying Party has been configured, the Reverse Proxy Instance must be configured to provide a way for users to trigger OpenID Connect authentication. Consuming claims from behind a reverse proxy After a successful OpenID Connect flow, this identity is passed to an Identity Mapping module. This module creates a subject and optionally add any further attributes to the created iv-cred.

Accessing identity information from a reverse proxy

By using an OpenID Connect Relying Party for authentication, a Reverse Proxy can be configured to provide identity information to junctioned applications.

Triggering OpenID Connect authentication
After a Relying Party has been configured, the Reverse Proxy Instance must be configured to provide a way for users to trigger OpenID Connect authentication.

Consuming claims from behind a reverse proxy
After a successful OpenID Connect flow, this identity is passed to an Identity Mapping module. This module creates a subject and optionally add any further attributes to the created iv-cred.

Parent topic: OpenID Connect federations

Triggering OpenID Connect authenticationAfter a Relying Party has been configured, the Reverse Proxy Instance must be configured to provide a way for users to trigger OpenID Connect authentication. To initiate the authentication flow, a user's browser must be redirected tohttps://<Reverse Proxy Hostname>/isam//sps/oidc/client/<Federation name>?oidc_client=<Fim Domain>-<Partner appliesTo>. For example, with the reverse proxy listening on hostname isam.example.com, using a configured federation with the providerId myRpFederation and a partner with the applies to value of google, the authentication trigger URL would be https://isam.example.com/isam/sps/oidc/client/myRpFederation?oidc_client=amapp-runtime-googleThe Reverse Proxy login form can be modified to provide users a method of authenticating using an OpenID Connect Provider.From the Reverse Proxy page in the local management interface, select the desired Reverse Proxy instance and select ManageManagement Root. Browse to managementClogin.html, and choose FileOpen.For example, editing the login form to link to the authentication trigger URL described above would involve adding the following line before the </BODY> tag: <A HREF="/mga/sps/oidc/client/myRpFederation?oidc_client=amapp-runtime-google">Login via Google</A>You must save this file, deploy the pending changes, and restart the Reverse Proxy instance.Accessing identity information from a reverse proxyBy using an OpenID Connect Relying Party for authentication, a Reverse Proxy can be configured to provide identity information to junctioned applications.

Triggering OpenID Connect authentication

After a Relying Party has been configured, the Reverse Proxy Instance must be configured to provide a way for users to trigger OpenID Connect authentication.

To initiate the authentication flow, a user's browser must be redirected tohttps://<Reverse Proxy Hostname>/isam//sps/oidc/client/<Federation name>?oidc_client=<Fim Domain>-<Partner appliesTo>. For example, with the reverse proxy listening on hostname isam.example.com, using a configured federation with the providerId myRpFederation and a partner with the applies to value of google, the authentication trigger URL would be https://isam.example.com/isam/sps/oidc/client/myRpFederation?oidc_client=amapp-runtime-google

The Reverse Proxy login form can be modified to provide users a method of authenticating using an OpenID Connect Provider.

From the Reverse Proxy page in the local management interface, select the desired Reverse Proxy instance and select Manage > Management Root. Browse to management > C > login.html, and choose File > Open.

For example, editing the login form to link to the authentication trigger URL described above would involve adding the following line before the </BODY> tag: <A HREF="/mga/sps/oidc/client/myRpFederation?oidc_client=amapp-runtime-google">Login via Google</A>

You must save this file, deploy the pending changes, and restart the Reverse Proxy instance.

Parent topic: Accessing identity information from a reverse proxy

Consuming claims from behind a reverse proxy After a successful OpenID Connect flow, this identity is passed to an Identity Mapping module. This module creates a subject and optionally add any further attributes to the created iv-cred. There are several ways in which these attributes can be consumed. This topic covers how to use Tag-Value attributes. Another method that uses the Authorization API to extract attributes from a PDPrincipal object is discussed here: https://www.ibm.com/developerworks/tivoli/tutorials/tz-tamauthapi/This section assumes that all of the potential values that could be added to the iv-cred have been added. If using a different mapping rule, only parameters made available by that mapping rule will be available to be configured with a Tag-Value.The Reverse Proxy configuration file must be edited first to allow for Tag-Values to be used without the prefix 'tagvalue_'. Add the following entry to the [server] stanza: force-tag-value-prefix = noModifications to the Reverse Proxy configuration file must be saved and deployed, and the instance must be restarted for changes to take effect.To allow a junctioned application to access a value from an OpenID Connect ID token, an attribute must be set on that object. In pdadmin, for a hostname <HOSTNAME>, Reverse Proxy instance <INSTANCE> and junction <JUNCTION>, the following command will set the iss header to contain the iss claim from the ID token:object modify /WebSEAL/<HOSTNAME>-<INSTANCE/<JUNCTION> set attribute \ HTTP-Tag-Value iss=issThe application at junction <JUNCTION> can now view the iss claim using the iss header.Accessing identity information from a reverse proxyBy using an OpenID Connect Relying Party for authentication, a Reverse Proxy can be configured to provide identity information to junctioned applications.

Consuming claims from behind a reverse proxy

After a successful OpenID Connect flow, this identity is passed to an Identity Mapping module. This module creates a subject and optionally add any further attributes to the created iv-cred.

There are several ways in which these attributes can be consumed. This topic covers how to use Tag-Value attributes. Another method that uses the Authorization API to extract attributes from a PDPrincipal object is discussed here: https://www.ibm.com/developerworks/tivoli/tutorials/tz-tamauthapi/

This section assumes that all of the potential values that could be added to the iv-cred have been added. If using a different mapping rule, only parameters made available by that mapping rule will be available to be configured with a Tag-Value.

The Reverse Proxy configuration file must be edited first to allow for Tag-Values to be used without the prefix 'tagvalue_'. Add the following entry to the [server] stanza:

force-tag-value-prefix = no

Modifications to the Reverse Proxy configuration file must be saved and deployed, and the instance must be restarted for changes to take effect.

To allow a junctioned application to access a value from an OpenID Connect ID token, an attribute must be set on that object. In pdadmin, for a hostname <HOSTNAME>, Reverse Proxy instance <INSTANCE> and junction <JUNCTION>, the following command will set the iss header to contain the iss claim from the ID token:

object modify /WebSEAL/<HOSTNAME>-<INSTANCE/<JUNCTION> set attribute \
HTTP-Tag-Value iss=iss

The application at junction <JUNCTION> can now view the iss claim using the iss header.

Parent topic: Accessing identity information from a reverse proxy

Authentication macrosThe following authentication macros are available to the user when configuring the login page of an OpenID Connect Provider.Protocol independent macros for customizing an authentication login form The following macros are protocol independent and can be used regardless of the federation type used. Supported protocol independent macrosMacroQuery-string parameter nameDescription%FEDID%FedIdSpecifies a unique identifier (UUID) used internally by ISAM to identify the federation.%FEDNAME%FedNameSpecifies the user-assigned name of the federation.OpenID Connect protocol supported macros for customizing an authentication login form The following table indicates how an OpenID Connect federation populates the authentication macros. Supported OpenID Connect protocol macrosMacroQuery-string parameter nameDescription and value%PARTNERID%PartnerIdThe OpenID Connect unique client identifier as it appeared in the “client_id” query string parameter.%TARGET%TargetThe OpenID Connect client redirection URI as it appeared in the “redirect_uri” query string parameter.%SSOREQUEST%SSORequestA base-64 encoded string representing the request made to /authorize.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.

Authentication macros

The following authentication macros are available to the user when configuring the login page of an OpenID Connect Provider.

Protocol independent macros for customizing an authentication login form

The following macros are protocol independent and can be used regardless of the federation type used.

Table 139. Supported protocol independent macros

Macro | Query-string parameter name | Description
%FEDID% | FedId | Specifies a unique identifier (UUID) used internally by ISAM to identify the federation.
%FEDNAME% | FedName | Specifies the user-assigned name of the federation.

OpenID Connect protocol supported macros for customizing an authentication login form

The following table indicates how an OpenID Connect federation populates the authentication macros.

Table 140. Supported OpenID Connect protocol macros

Macro | Query-string parameter name | Description and value
%PARTNERID% | PartnerId | The OpenID Connect unique client identifier as it appeared in the “client_id” query string parameter.
%TARGET% | Target | The OpenID Connect client redirection URI as it appeared in the “redirect_uri” query string parameter.
%SSOREQUEST% | SSORequest | A base-64 encoded string representing the request made to /authorize.

Parent topic: OpenID Connect federations

Automatic configuration of a reverse proxy for OpenID ConnectTo make use of a configured OpenID Connect Provider or Relying Party, a reverse proxy instance must be configured to act as the point of contact. This configuration covers:Changes to the reverse proxy configuration file.Creation of an Unauthenticated access ACL to be attached to some endpoints.Creation of a /isam junction to the federation runtime. This requires the federation runtime SSL certificate to be loaded into the reverse proxies trusted signer certificates keystore.This configuration can be performed automatically on a reverse proxy through the federation configuration web service. For more information about invoking the federation configuration web service, see the REST API documentation that is included in the appliance.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.

Automatic configuration of a reverse proxy for OpenID Connect

To make use of a configured OpenID Connect Provider or Relying Party, a reverse proxy instance must be configured to act as the point of contact.

This configuration covers:

Changes to the reverse proxy configuration file.

Creation of an "Unauthenticated access" ACL to be attached to some endpoints.

Creation of a /isam junction to the federation runtime.

This requires the federation runtime SSL certificate to be loaded into the reverse proxies trusted signer certificates keystore.

This configuration can be performed automatically on a reverse proxy through the federation configuration web service. For more information about invoking the federation configuration web service, see the REST API documentation that is included in the appliance.

Parent topic: OpenID Connect federations

Customizing the consent pageThe consent page of an OpenID Connect Provider Federation can be changed with the Template Files page in the local management interface. All OpenID Connect Provider (OP) federations can have their own unique consent pages. Follow these steps to set a consent page to be used by a specific federation.Log in to the local management console.Select Secure FederationGlobal SettingsTemplate Files.Expand the C locale.Highlight the oidc folder.Click New and select Directory.Enter the Federation Name of the OpenID Connect Provider Federation to use the custom consent page.Click Save.Highlight the new directory.Click New and select File.Enter consent.html as the file name.Populate the file contents.Click Save.Deploy the pending changes.The deploy operation triggers a runtime restart.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.

Customizing the consent page

The consent page of an OpenID Connect Provider Federation can be changed with the Template Files page in the local management interface.

About this task

All OpenID Connect Provider (OP) federations can have their own unique consent pages. Follow these steps to set a consent page to be used by a specific federation.

Procedure

Log in to the local management console.

Select Secure Federation > Global Settings > Template Files.

Expand the C locale.

Highlight the oidc folder.

Click New and select Directory.

Enter the Federation Name of the OpenID Connect Provider Federation to use the custom consent page.

Click Save.

Highlight the new directory.

Click New and select File.

Enter consent.html as the file name.

Populate the file contents.

Click Save.

Deploy the pending changes.

Note: The deploy operation triggers a runtime restart.

Parent topic: OpenID Connect federations

Known limitationsThese limitations apply to OpenID Connect federations.No hybrid flow support for the RP or OPThe currently supported flows are implicit or authorization code flow.No support for response_mode on the OPAn administrator cannot customize the response_mode of responses, for example, setting it to form_post.No encryption of id_tokens, limited signature algorithmsEncrypting id_tokens is not supported. The signature algorithms that are supported for signing them are 256-bit RSA or HMAC.Cannot configure both posting client credentials and providing them in a basic authentication header when contacting the /token endpointOnly one of clientSecretBasic and clientSecretPost can be configured for an OP federation.There is no /userinfo endpointA client cannot use an access token to access a /userinfo endpoint to obtain information about the user the token was issued on behalf of.No discoveryThe ability to discover a user's OP and interact with it as per https://openid.net/specs/openid-connect-discovery-1_0.html is not available.No dynamic client registrationThe ability for clients to self-register against an OP as per https://openid.net/specs/openid-connect-registration-1_0.html is not available.The access_token provided to an OpenID Connect client cannot be used to authenticate to a reverse proxyThe access token is different from one obtained by using an OAuth 2.0 client, and cannot be used to authenticate as a user to the OP.Users cannot manage grants or consent informationThere is no way to revoke access a grant that was issued to a client, or remove any remembered consent decisions.No configuration-time checking is performed on mapping rulesThe mapping rule is not checked for errors before run time. OAuth 2.0 APIs and run time and those of OpenID Connect are not integratedThere is no integration between the two technologies on the appliance. Clients and configurations are separate and do not interact.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.

Known limitations

These limitations apply to OpenID Connect federations.

No hybrid flow support for the RP or OP

The currently supported flows are implicit or authorization code flow.

No support for response_mode on the OP

An administrator cannot customize the response_mode of responses, for example, setting it to form_post.

No encryption of id_tokens, limited signature algorithms

Encrypting id_tokens is not supported. The signature algorithms that are supported for signing them are 256-bit RSA or HMAC.

Cannot configure both posting client credentials and providing them in a basic authentication header when contacting the /token endpoint

Only one of clientSecretBasic and clientSecretPost can be configured for an OP federation.

There is no /userinfo endpoint

A client cannot use an access token to access a /userinfo endpoint to obtain information about the user the token was issued on behalf of.

No discovery

The ability to discover a user's OP and interact with it as per https://openid.net/specs/openid-connect-discovery-1_0.html is not available.

No dynamic client registration

The ability for clients to self-register against an OP as per https://openid.net/specs/openid-connect-registration-1_0.html is not available.

The access_token provided to an OpenID Connect client cannot be used to authenticate to a reverse proxy

The access token is different from one obtained by using an OAuth 2.0 client, and cannot be used to authenticate as a user to the OP.

Users cannot manage grants or consent information

There is no way to revoke access a grant that was issued to a client, or remove any remembered consent decisions.

No configuration-time checking is performed on mapping rules

The mapping rule is not checked for errors before run time.

OAuth 2.0 APIs and run time and those of OpenID Connect are not integrated

There is no integration between the two technologies on the appliance. Clients and configurations are separate and do not interact.

Parent topic: OpenID Connect federations

Nested single sign-on flowsYou can nest SAML or OpenID Connect single sign-on flows. That is, you can resume an initial SSO flow after the completion of a second SSO flow. For SAML, a nested SSO flow means the involvement of an IdP proxy between a real service provider (SP) and a real identity provider (IdP). The IdP proxy delegates the user credentials authentication to the real IdP.For OpenID Connect, a nested SSO flow means the involvement of an OAuth provider (OP) proxy between a real relying party (RP) and a real OP. The OP proxy delegates the user credentials authentication to the real OP.A nested SSO flow involves the following two SP or RP-initiated SSO flows:Between the real SP or RP and an IdP or OP proxy. Between the IdP or OP proxy (acts as an SP or RP) and the real IdP or OP.After the second SSO flow completes the authentication of credentials with the real IdP or OP, the IdP or OP proxy has an implicit mechanism to resume the first SSO flow to sign in to the real SP or RP. When you install an appliance to work as an IdP proxy, create an identity provider and service provider federation and map them to a single reverse proxy instance. See Configuring a reverse proxy point of contact serverConfiguring a SAML 2.0 or OpenID Connect federation requires that you set up a reverse proxy instance as the point of contact..Configure the proper mapping rules in the IdP proxy federations to avoid duplicate attributes in STSUU to attain the successful flow of nested SSO. See the following topics: .Mapping a local identity to a SAML 2.0 tokenYou can map a local identity to a SAML 2.0 token for an identity provider. Mapping a SAML 2.0 token to a local identityYou can map a SAML 2.0 token to a local identity for a service provider.OpenID Connect Provider mapping rulesWhen you write mapping rules for a provider, the primary goal is to augment the claims that are included in the ID token. OpenID Connect Relying Party mapping rulesWhen you write mapping rules for a Relying Party, the resulting STSUU is turned into a PAC that is used to authenticate the user to a Reverse Proxy via EAI.Supported nested SSO combinations First SSO flowSecond SSO flowSAML (HTTPRedirect, HTTPPost, HTTPArtifact) SAML (HTTPRedirect, HTTPPost, HTTPArtifact) SAML (HTTPRedirect, HTTPPost, HTTPArtifact) OpenID ConnectOpenID ConnectOpenID ConnectOpenID ConnectSAML (HTTPRedirect, HTTPPost, HTTPArtifact) The following supported nested flows are for the authentication delegated to the external IdP during an OAuth20 flow: Supported nested OAuth flow combinationsFirst flowSecond flowOAuth20SAML (HTTPRedirect, HTTPPost, HTTPArtifact) OAuth20OpenID ConnectFederation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.

Nested single sign-on flows

You can nest SAML or OpenID Connect single sign-on flows. That is, you can resume an initial SSO flow after the completion of a second SSO flow.

For SAML, a nested SSO flow means the involvement of an IdP proxy between a real service provider (SP) and a real identity provider (IdP). The IdP proxy delegates the user credentials authentication to the real IdP.

For OpenID Connect, a nested SSO flow means the involvement of an OAuth provider (OP) proxy between a real relying party (RP) and a real OP. The OP proxy delegates the user credentials authentication to the real OP.

A nested SSO flow involves the following two SP or RP-initiated SSO flows:

Between the real SP or RP and an IdP or OP proxy.

Between the IdP or OP proxy (acts as an SP or RP) and the real IdP or OP.

After the second SSO flow completes the authentication of credentials with the real IdP or OP, the IdP or OP proxy has an implicit mechanism to resume the first SSO flow to sign in to the real SP or RP.

When you install an appliance to work as an IdP proxy, create an identity provider and service provider federation and map them to a single reverse proxy instance. See Configuring a reverse proxy point of contact server.

Note: Configure the proper mapping rules in the IdP proxy federations to avoid duplicate attributes in STSUU to attain the successful flow of nested SSO. See the following topics: .

Mapping a local identity to a SAML 2.0 token

Mapping a SAML 2.0 token to a local identity

OpenID Connect Provider mapping rules

OpenID Connect Relying Party mapping rules

Table 141. Supported nested SSO combinations

First SSO flow | Second SSO flow
SAML (HTTPRedirect, HTTPPost, HTTPArtifact) | SAML (HTTPRedirect, HTTPPost, HTTPArtifact)
SAML (HTTPRedirect, HTTPPost, HTTPArtifact) | OpenID Connect
OpenID Connect | OpenID Connect
OpenID Connect | SAML (HTTPRedirect, HTTPPost, HTTPArtifact)

The following supported nested flows are for the authentication delegated to the external IdP during an OAuth20 flow:

Table 142. Supported nested OAuth flow combinations

First flow | Second flow
OAuth20 | SAML (HTTPRedirect, HTTPPost, HTTPArtifact)
OAuth20 | OpenID Connect

Parent topic: Federation configuration

Configuring a reverse proxy point of contact serverConfiguring a reverse proxy point of contact serverConfiguring a reverse proxy point of contact serverConfiguring a SAML 2.0 or OpenID Connect federation requires that you set up a reverse proxy instance as the point of contact.point of contact serverreverse proxy configurationreverse proxy instancepoint of contact server configurationserverspoint of contact serverOpenID Connect federationreverse proxy point of contact server configurationSAML federationsreverse proxy point of contact server configurationfederationreverse proxy point of contact server configurationYou can use these instructions to configure a reverse proxy instance, or you can use the Web services REST APIs. The REST API topic is located in Secure: Web SettingsManageReverse ProxyFederation Configuration.If you use the Web services REST APIs to configure a reverse proxy instance, ensure that the junction name is /isam.The reverse proxy instance that you use authenticates users at the identity provider and protects services at the service provider. You must have a reverse proxy instance for both the service provider and the identity provider. See Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed. for more information.Import the federation runtime SSL certificate into the reverse proxy trusted signer certificates keystore. Use the local management interface to import the certificate. See Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates..Using the pdamin command, create the /isam junction to the federated runtime. Substitute the values of your runtime in the following command: server task hostname-webseal-instanceName create -t ssl -c all -s -b ignore -j -e utf8_uri -J inhead -r -q /sps/cgi-bin/query_contents -f -h runtimeHostname -p runtimePort /isamUpdate the reverse proxy configuration file by using the local management interface:Click Secure Web SettingsManageReverse Proxy. Select the reverse proxy instance to update, and click ManageConfigurationEdit Configuration File.Edit the configuration file with the following stanzas and entries, depending on the federation protocol:SAML 2.0[ba]: ba-auth = none [forms]: forms-auth = https [authentication-levels]: level = ext-auth-interface [eai]: eai-auth = https retain-eai-session = yes eai-verify-user-identity = no eai-redir-url-priority = yes [eai-trigger-urls]: trigger = /isam/sps/auth* trigger = /isam/sps/federation_name/saml20/soap* trigger = /isam/sps/federation_name/saml20/slo* trigger = /isam/sps/federation_name/saml20/login* [session]: user-session-ids = yesOpenID Connect[ba]: ba-auth = none [forms]: forms-auth = https [junction:/isam]: reset-cookies-list = *JSESSIONID*,*WAS* (RP ONLY) [authentication-levels]: level = ext-auth-interface (RP ONLY) [eai]: eai-auth = https eai-redir-url-priority = yes (RP ONLY) [eai-trigger-urls]: trigger = /isam/sps/oidc/client/federation_providerID* Using the pdadmin command, define the nobody, anyauth, and unauth ACLs. Note that the WebSEAL user should be used for default-webseald/isam-op.acl create fedname-nobody acl modify fedname-nobody set user default-webseald/hostname TcmdbsvaBRl acl modify fedname-nobody set user sec_master TcmdbsvaBRrxl acl modify fedname-nobody set group iv-admin TcmdbsvaBRrxl acl modify fedname-nobody set group webseal-servers Tgmdbsrxl acl modify fedname-nobody set any-other T acl modify fedname-nobody set unauthenticated T acl create fedname-anyauth acl modify fedname-anyauth set user default-webseald/hostname TcmdbsvaBRl acl modify fedname-anyauth set user sec_master TcmdbsvaBRrxl acl modify fedname-anyauth set group iv-admin TcmdbsvaBRrxl acl modify fedname-anyauth set group webseal-servers Tgmdbsrxl acl modify fedname-anyauth set any-other Tr acl modify fedname-anyauth set unauthenticated T acl create fedname-unauth acl modify fedname-unauth set user default-webseald/hostname TcmdbsvaBRl acl modify fedname-unauth set user sec_master TcmdbsvaBRrxl acl modify fedname-unauth set group iv-admin TcmdbsvaBRrxl acl modify fedname-unauth set group webseal-servers Tgmdbsrxl acl modify fedname-unauth set any-other Tr acl modify fedname-unauth set unauthenticated TrUsing the pdadmin command, create the ACLs on the policy server, and attach them to the relevant endpoints.SAML 2.0fedname-nobody: /WebSEAL/hostname-webseal/isam fedname-unauth: /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/login /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/sloininitial /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/mnids /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/logininitial /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/slo /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/soap fedname-anyauth: /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/mnidsinitial /WebSEAL/hostname-webseal/isam/sps/fedname/saml20/auth /WebSEAL/hostname-webseal/isam/sps/wssoi /WebSEAL/hostname-webseal/isam/sps/authOpenID Connectfedname-nobody: /WebSEAL/hostname-instance/isam fedname-unauth: /WebSEAL/hostname-instance/isam/sps/static /WebSEAL/hostname-instance/isam/sps/fedname/oidc/auth /WebSEAL/hostname-instance/isam/oidc/scripts /WebSEAL/hostname-instance/isam/oidc/endpoint/amapp-runtime-fedname/token /WebSEAL/hostname-instance/isam/oidc/endpoint/amapp-runtime-fedname/introspect /WebSEAL/hostname-instance/isam/oidc/endpoint/amapp-runtime-fedname/authorize (RP Only) /WebSEAL/hostname-instance/isam/sps/oidc/client/fedname (RP Only) /WebSEAL/hostname-instance/isam/oidcclient/redirect fedname-anyauth /WebSEAL/hostname-instance/isam/sps/authUsing the pdamin command, add the HTTP-Tag-Value attribute to the /isam junction object to propagate the user_session_id to the federation runtime: If force-tag-value-prefix = yes:object modify /WebSEAL/hostname-default/isam set attribute HTTP-Tag-Value user_session_id=USER-SESSION-IDIf force-tag-value-prefix = no:object modify /WebSEAL/hostname-default/isam set attribute HTTP-Tag-Value tagvalue_user_session_id=USER-SESSION-IDFederation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.

Configuring a reverse proxy point of contact server

Configuring a SAML 2.0 or OpenID Connect federation requires that you set up a reverse proxy instance as the point of contact.

Before you begin

You can use these instructions to configure a reverse proxy instance, or you can use the Web services REST APIs. The REST API topic is located in Secure: Web Settings > Manage > Reverse Proxy > Federation Configuration.

Note: If you use the Web services REST APIs to configure a reverse proxy instance, ensure that the junction name is /isam.

About this task

The reverse proxy instance that you use authenticates users at the identity provider and protects services at the service provider. You must have a reverse proxy instance for both the service provider and the identity provider.

See Reverse proxy instance management for more information.

Procedure

Import the federation runtime SSL certificate into the reverse proxy trusted signer certificates keystore. Use the local management interface to import the certificate. See Managing SSL certificates.

Using the pdamin command, create the /isam junction to the federated runtime. Substitute the values of your runtime in the following command:

server task hostname-webseal-instanceName create -t ssl -c all -s -b ignore -j
  -e utf8_uri -J inhead -r -q /sps/cgi-bin/query_contents -f
  -h  runtimeHostname -p runtimePort /isam

Update the reverse proxy configuration file by using the local management interface:

Click Secure Web Settings > Manage > Reverse Proxy.

Select the reverse proxy instance to update, and click Manage > Configuration > Edit Configuration File.

Edit the configuration file with the following stanzas and entries, depending on the federation protocol:

SAML 2.0

[ba]:
ba-auth = none
[forms]:
forms-auth = https
[authentication-levels]:
level = ext-auth-interface
[eai]:
eai-auth = https
retain-eai-session = yes
eai-verify-user-identity = no
eai-redir-url-priority = yes
[eai-trigger-urls]:
trigger = /isam/sps/auth*
trigger = /isam/sps/federation_name/saml20/soap*
trigger = /isam/sps/federation_name/saml20/slo*
trigger = /isam/sps/federation_name/saml20/login*
[session]:
user-session-ids = yes

OpenID Connect

[ba]:
ba-auth = none
[forms]:
forms-auth = https
[junction:/isam]:
reset-cookies-list = *JSESSIONID*,*WAS*
(RP ONLY) [authentication-levels]:
level = ext-auth-interface
(RP ONLY) [eai]:
eai-auth = https
eai-redir-url-priority = yes
(RP ONLY) [eai-trigger-urls]:
trigger = /isam/sps/oidc/client/federation_providerID*

Using the pdadmin command, define the nobody, anyauth, and unauth ACLs. Note that the WebSEAL user should be used for default-webseald/isam-op.

acl create fedname-nobody
acl modify fedname-nobody set user default-webseald/hostname TcmdbsvaBRl
acl modify fedname-nobody set user sec_master TcmdbsvaBRrxl
acl modify fedname-nobody set group iv-admin TcmdbsvaBRrxl
acl modify fedname-nobody set group webseal-servers Tgmdbsrxl
acl modify fedname-nobody set any-other T
acl modify fedname-nobody set unauthenticated T

acl create fedname-anyauth
acl modify fedname-anyauth set user default-webseald/hostname TcmdbsvaBRl
acl modify fedname-anyauth set user sec_master TcmdbsvaBRrxl
acl modify fedname-anyauth set group iv-admin TcmdbsvaBRrxl
acl modify fedname-anyauth set group webseal-servers Tgmdbsrxl
acl modify fedname-anyauth set any-other Tr
acl modify fedname-anyauth set unauthenticated T

acl create fedname-unauth
acl modify fedname-unauth set user default-webseald/hostname TcmdbsvaBRl
acl modify fedname-unauth set user sec_master TcmdbsvaBRrxl
acl modify fedname-unauth set group iv-admin TcmdbsvaBRrxl
acl modify fedname-unauth set group webseal-servers Tgmdbsrxl
acl modify fedname-unauth set any-other Tr
acl modify fedname-unauth set unauthenticated Tr

Using the pdadmin command, create the ACLs on the policy server, and attach them to the relevant endpoints.

SAML 2.0

fedname-nobody:
/WebSEAL/hostname-webseal/isam
fedname-unauth:
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/login
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/sloininitial
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/mnids
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/logininitial
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/slo
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/soap
fedname-anyauth:
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/mnidsinitial
/WebSEAL/hostname-webseal/isam/sps/fedname/saml20/auth
/WebSEAL/hostname-webseal/isam/sps/wssoi
/WebSEAL/hostname-webseal/isam/sps/auth

OpenID Connect

fedname-nobody:
/WebSEAL/hostname-instance/isam
fedname-unauth:
/WebSEAL/hostname-instance/isam/sps/static
/WebSEAL/hostname-instance/isam/sps/fedname/oidc/auth
/WebSEAL/hostname-instance/isam/oidc/scripts
/WebSEAL/hostname-instance/isam/oidc/endpoint/amapp-runtime-fedname/token
/WebSEAL/hostname-instance/isam/oidc/endpoint/amapp-runtime-fedname/introspect
/WebSEAL/hostname-instance/isam/oidc/endpoint/amapp-runtime-fedname/authorize
(RP Only) /WebSEAL/hostname-instance/isam/sps/oidc/client/fedname
(RP Only) /WebSEAL/hostname-instance/isam/oidcclient/redirect
fedname-anyauth
/WebSEAL/hostname-instance/isam/sps/auth

Using the pdamin command, add the HTTP-Tag-Value attribute to the /isam junction object to propagate the user_session_id to the federation runtime:

If force-tag-value-prefix = yes:

object modify /WebSEAL/hostname-default/isam set attribute
  HTTP-Tag-Value user_session_id=USER-SESSION-ID

If force-tag-value-prefix = no:

object modify /WebSEAL/hostname-default/isam set attribute
  HTTP-Tag-Value tagvalue_user_session_id=USER-SESSION-ID

Parent topic: Federation configuration

Managing advanced configurationManaging advanced configurationAdjust configuration settings in supported configuration files.configurationfederationadvancedadvanced configrationThe advanced configuration panel displays a table of configuration settings. Some can be modified and some are read-only. Each setting is displayed as a row in the table. The name of the setting is listed in the key column. The current value of the key is listed in the value column.You can locate a setting by using one of the following methods:Scroll through the list until you see the setting.By default, all configuration settings are included in the list.Filter the list by entering a string in the Filter field.When you enter a string, the list is modified to show only the settings that contain the specified string.Filter the list by selecting a category from the Filter by Category menu. For descriptions of the categories and properties, see Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization..Select Secure Federation Global SettingsAdvanced Configuration.To edit a key, select the edit icon Edit icon for the key.You cannot edit keys that are marked with the read-only icon: Read-only icon. When you choose to edit a key, a new window displays the name of the key and the current value.Edit the value for your deployment.Configuration data typesData typeActionIntegersUse the arrow icons to increment or decrement the value. Alternatively, you can type a new value in the field. StringsEnter a string value in the field.This field must have a value. You cannot specify an empty field. To clear values from a field, enter NULL.BooleansSelect the check box to set the value to true. Clear the check box to set the value to false.Click OK.Deploy the changes.Federation configurationUse the topics in this hierarchy to configure the Federation features, if you have activated this module.Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization.

Managing advanced configuration

Adjust configuration settings in supported configuration files.

About this task

The advanced configuration panel displays a table of configuration settings. Some can be modified and some are read-only. Each setting is displayed as a row in the table. The name of the setting is listed in the key column. The current value of the key is listed in the value column.

You can locate a setting by using one of the following methods:

Scroll through the list until you see the setting.

By default, all configuration settings are included in the list.

Filter the list by entering a string in the Filter field.

When you enter a string, the list is modified to show only the settings that contain the specified string.

Filter the list by selecting a category from the Filter by Category menu. For descriptions of the categories and properties, see Advanced configuration properties.

Procedure

Select Secure Federation > Global Settings > Advanced Configuration.

To edit a key, select the edit icon Edit icon for the key.

Note: You cannot edit keys that are marked with the read-only icon: Read-only icon.

When you choose to edit a key, a new window displays the name of the key and the current value.

Edit the value for your deployment.

Table 143. Configuration data types.

Data type
Action

Integers
Use the arrow icons to increment or decrement the value. Alternatively, you can type a new value in the field.

Strings
Enter a string value in the field.

Note: This field must have a value. You cannot specify an empty field. To clear values from a field, enter NULL.

Booleans
Select the check box to set the value to true. Clear the check box to set the value to false.

Click OK.

Deploy the changes.

Advanced configuration properties
Modify the advanced configurations to meet the requirements of your organization.

Parent topic: Federation configuration

Managing advanced configurationManaging advanced configurationManaging advanced configurationManage advanced configuration in supported configuration files.Select the appropriate Module link for information about managing advanced configuration:Advanced Access Control ModuleManaging advanced configurationAdjust configuration settings in supported configuration files.Federation ModuleManaging advanced configurationAdjust configuration settings in supported configuration files.

Managing advanced configuration

Manage advanced configuration in supported configuration files.

Select the appropriate Module link for information about managing advanced configuration:

Advanced Access Control Module

Managing advanced configuration

Federation Module

Managing advanced configuration

AdministeringIBM Security Access Manager provides information about administering supported activation levels.administeringAppliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.

Administering

IBM Security Access Manager provides information about administering supported activation levels.

Appliance administration
The IBM® Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.

Access Manager Platform and Supporting Components administration
The Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy.

Web Reverse Proxy administration
IBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.

Advanced Access Control administration
The Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Federation administration
Use the topics in this hierarchy to administer the Federation features, if you have activated this module.

Appliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.AdministeringIBM Security Access Manager provides information about administering supported activation levels.OverviewThe IBM Security Access Manager Appliance is a network appliance-based security solution that provides both access control and protection from web-based threats. Getting StartedComplete the following tasks that apply to your appliance format.Initial configurationSeveral initial configuration tasks are required for your IBM Security Access Manager environment.Managing the applianceThe appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.Monitoring: Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.Manage: System SettingsInformation about configuring Security, Network, and System settings of your appliance.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Appliance administration

The IBM® Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.

Overview
The IBM Security Access Manager Appliance is a network appliance-based security solution that provides both access control and protection from web-based threats.

Getting Started
Complete the following tasks that apply to your appliance format.

Initial configuration
Several initial configuration tasks are required for your IBM Security Access Manager environment.

Managing the appliance
The appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.

Home: Appliance Dashboard
The appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Monitoring: Analysis and Diagnostics
You can monitor the health and statistics of the appliance.

Manage: System Settings
Information about configuring Security, Network, and System settings of your appliance.

Cluster support
The Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Parent topic: Administering

OverviewOverviewIBM Security Access Manager Appliance overviewThe IBM Security Access Manager Appliance is a network appliance-based security solution that provides both access control and protection from web-based threats. IBM Security Access Manager ApplianceSecurity Access Manager ApplianceoverviewThe main features of the appliance include:A dashboard for viewing system status such as system notifications and disk usage.Analysis and diagnostics tools such as event logs, memory statistics, and CPU utilization.Centralized management of settings such as runtime components configuration files, and SSL certificates.Control of system settings such as updates, licenses, and network settings.Most of the features are configurable by using the local management interface (LMI).The hardware appliance consists of the hardware and preinstalled IBM Security Access Manager Appliance firmware. The preinstalled firmware software can also be obtained separately as a virtual appliance image that you can deploy in a hypervisor environment.For information about specifications for both the hardware appliance and virtual appliance, see System RequirementsYou can view Software Product Compatibility Reports that list the system requirements and appliance specifications for the product..Appliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Activation level overviewEach activation level on the IBM Security Access Manager appliance offers different features. Consider the needs of your environment to determine which activation levels you require. Tips on using the applianceThese tips might be useful during the administration of the appliance.

Overview

The IBM® Security Access Manager Appliance is a network appliance-based security solution that provides both access control and protection from web-based threats.

The main features of the appliance include:

A dashboard for viewing system status such as system notifications and disk usage.

Analysis and diagnostics tools such as event logs, memory statistics, and CPU utilization.

Centralized management of settings such as runtime components configuration files, and SSL certificates.

Control of system settings such as updates, licenses, and network settings.

Most of the features are configurable by using the local management interface (LMI).

The hardware appliance consists of the hardware and preinstalled IBM Security Access Manager Appliance firmware. The preinstalled firmware software can also be obtained separately as a virtual appliance image that you can deploy in a hypervisor environment.

For information about specifications for both the hardware appliance and virtual appliance, see System Requirements.

Activation level overview
Each activation level on the IBM Security Access Manager appliance offers different features. Consider the needs of your environment to determine which activation levels you require.

Tips on using the appliance
These tips might be useful during the administration of the appliance.

Parent topic: Appliance administration

Activation level overviewActivation level overviewActivation level overviewEach activation level on the IBM Security Access Manager appliance offers different features. Consider the needs of your environment to determine which activation levels you require. product activationactivationpoints of contactWebSEALsupporting componentsplatformadvanced access controlSecurity Access Manager Supporting Components: No activation key is required The Supporting Components provide:Appliance management: local management interface and REST APIsPolicy ServerEmbedded LDAP serverAuthorization ServerSecurity Access Manager Platform: Activation key is requiredThe IBM Security Access Manager Platform secures web applications. To use the web security features, you must activate the Security Access Manager Platform. This activation level includes the following key components: Web Reverse ProxyWeb Reverse Proxy is a high performance, multi-threaded Web server that applies fine-grained security policy to the IBM Security Access Manager protected web object space. Web Reverse Proxy can provide single sign-on solutions and incorporate back-end web application server resources into its security policy. For more information, see Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level..Front-end load balancerOptimizes resource use and ensures high availability of services. The front-end load balancer accepts requests from clients and determines which backend server is the most suitable to handle the request. It forwards each request to the appropriate server. The front-end load balancer provides persistence for existing sessions. For more information, see Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm..Web application firewallHelps protect your web servers from malicious traffic and blocks attempts to compromise the system. See Configuring web application firewall To configure web application firewall with the local management interface, use the Reverse Proxy management page..Distributed session cacheMaintains session state in clustered server environments. See Distributed session cache overviewThe following concepts relate to the distributed session cache, which maintains session state in clustered server environments..Advanced Access Control Module: Activation key is requiredThe Advanced Access Control Module secures mobile transactions. This activation level includes features, such as: Context-based access and an authentication service frameworkProvides enhanced authentication assurance, context-based access control, and protection from web-based threats. API protectionUses the OAuth protocol, which provides API protection for native mobile and other API-based applications.Device fingerprinting and registrationStores the device fingerprint of the user in the context-based access database.To activate this module, you must first activate the IBM Security Access Manager Platform offering.Federation Module: Activation key is requiredThe Federation Module provides support for the SAML 2.0 and OpenID Connect protocols.To activate this module, you must first activate the IBM Security Access Manager Platform offering.Figure 1 summarizes the key features and product activation levels. Product activation levels for the IBM Security Access Manager productProduct activation levels for the IBM Security Access Manager productOverviewThe IBM Security Access Manager Appliance is a network appliance-based security solution that provides both access control and protection from web-based threats.

Activation level overview

Each activation level on the IBM® Security Access Manager appliance offers different features. Consider the needs of your environment to determine which activation levels you require.

Security Access Manager Supporting Components: No activation key is required

The Supporting Components provide:

Appliance management: local management interface and REST APIs

Policy Server

Embedded LDAP server

Authorization Server

Security Access Manager Platform: Activation key is required

The IBM Security Access Manager Platform secures web applications. To use the web security features, you must activate the Security Access Manager Platform. This activation level includes the following key components:

Web Reverse Proxy

Web Reverse Proxy is a high performance, multi-threaded Web server that applies fine-grained security policy to the IBM Security Access Manager protected web object space. Web Reverse Proxy can provide single sign-on solutions and incorporate back-end web application server resources into its security policy.

For more information, see Web Reverse Proxy administration.

Front-end load balancer

Optimizes resource use and ensures high availability of services. The front-end load balancer accepts requests from clients and determines which backend server is the most suitable to handle the request. It forwards each request to the appropriate server. The front-end load balancer provides persistence for existing sessions.

For more information, see Front-end load balancer.

Web application firewall

Helps protect your web servers from malicious traffic and blocks attempts to compromise the system. See Configuring web application firewall.

Distributed session cache

Maintains session state in clustered server environments. See Distributed session cache overview.

Advanced Access Control Module: Activation key is required

The Advanced Access Control Module secures mobile transactions. This activation level includes features, such as:

Context-based access and an authentication service framework

Provides enhanced authentication assurance, context-based access control, and protection from web-based threats.

API protection

Uses the OAuth protocol, which provides API protection for native mobile and other API-based applications.

Device fingerprinting and registration

Stores the device fingerprint of the user in the context-based access database.

To activate this module, you must first activate the IBM Security Access Manager Platform offering.

Federation Module: Activation key is required

The Federation Module provides support for the SAML 2.0 and OpenID Connect protocols.

To activate this module, you must first activate the IBM Security Access Manager Platform offering.

Figure 63. summarizes the key features and product activation levels.

Figure 63. Product activation levels for the IBM Security Access Manager product

Parent topic: Overview

Tips on using the applianceTips on using the applianceTips on using the IBM Security Access Manager ApplianceThese tips might be useful during the administration of the appliance.appliancesdisk space usageadministrationbackupBackupIt is important to back up your appliance frequently. To back up the appliance, use the snapshot facility that is provided by the appliance.A snapshot is a copy of the state of the appliance at a certain time. By using snapshot files, you can back up your appliance and restore the appliance later. It is a good practice to take snapshots regularly and download them from the appliance to serve as backups. However, snapshots can consume much disk space and as such it is best to clean up the old snapshots regularly.For details about working with snapshots, see Managing snapshotsUse snapshots to restore prior configuration and policy settings to the appliance. Back up the appliance on a frequent basis by downloading snapshot files..Session timeoutsSave your configuration updates in the local management interface (LMI) regularly to avoid any data loss in the event of a session timeout. LMI sessions expire after the duration of time that is specified by the Session Timeout field on the Administrator Settings page. When a session timeout occurs, any unsaved data on the current page is lost.Disk space usageThe disk space in a hardware appliance is limited by the capacity of the installed hard disk. Certain files can use up a significant amount of disk space over time. Such files typically include:Support filesSupport files are used by IBM support personnel to troubleshoot problems with the appliance. The support files contain all log files, temporary and intermediate files, and command output that is needed to diagnose customer support problems. The size of these files can grow large over time. To reduce the disk space that is occupied by these files, download unused support files to an external drive. Then, delete the support files from the appliance. For detailed instructions, see Managing support filesIBM Customer Support uses support files to help you troubleshoot problems with the appliance. Support files contain all log files, temporary and intermediate files, and command output that is needed to diagnose customer support problems..Snapshot filesSnapshot files record the state that the appliance is in at a certain time. They can be used to restore the appliance to a previous state. The snapshot files are stored on the appliance by default. To reduce the disk space that is used, you can download the snapshot files to an external drive and then delete them from the appliance. For detailed instructions, see Managing snapshotsUse snapshots to restore prior configuration and policy settings to the appliance. Back up the appliance on a frequent basis by downloading snapshot files..The administrator must monitor the remaining free disk space, and take the necessary actions to ensure that there is adequate disk space. The appliance provides a Disk Usage dashboard widget for administrators to monitor the current disk usage. For more information about managing disk space, see Viewing disk usageYou can view the disk space status and remaining disk life information with the Disk Usage dashboard widget..OverviewThe IBM Security Access Manager Appliance is a network appliance-based security solution that provides both access control and protection from web-based threats.

Tips on using the appliance

These tips might be useful during the administration of the appliance.

Backup

It is important to back up your appliance frequently. To back up the appliance, use the snapshot facility that is provided by the appliance.

A snapshot is a copy of the state of the appliance at a certain time. By using snapshot files, you can back up your appliance and restore the appliance later. It is a good practice to take snapshots regularly and download them from the appliance to serve as backups. However, snapshots can consume much disk space and as such it is best to clean up the old snapshots regularly.

For details about working with snapshots, see Managing snapshots.

Session timeouts

Save your configuration updates in the local management interface (LMI) regularly to avoid any data loss in the event of a session timeout.

LMI sessions expire after the duration of time that is specified by the Session Timeout field on the Administrator Settings page. When a session timeout occurs, any unsaved data on the current page is lost.

Disk space usage

The disk space in a hardware appliance is limited by the capacity of the installed hard disk. Certain files can use up a significant amount of disk space over time. Such files typically include:

Support files

Support files are used by IBM® support personnel to troubleshoot problems with the appliance. The support files contain all log files, temporary and intermediate files, and command output that is needed to diagnose customer support problems. The size of these files can grow large over time. To reduce the disk space that is occupied by these files, download unused support files to an external drive. Then, delete the support files from the appliance. For detailed instructions, see Managing support files.

Snapshot files

Snapshot files record the state that the appliance is in at a certain time. They can be used to restore the appliance to a previous state. The snapshot files are stored on the appliance by default. To reduce the disk space that is used, you can download the snapshot files to an external drive and then delete them from the appliance. For detailed instructions, see Managing snapshots.

The administrator must monitor the remaining free disk space, and take the necessary actions to ensure that there is adequate disk space. The appliance provides a Disk Usage dashboard widget for administrators to monitor the current disk usage. For more information about managing disk space, see Viewing disk usage.

Parent topic: Overview

Getting StartedGetting StartedGetting started with the IBM Security Access Manager ApplianceComplete the following tasks that apply to your appliance format.getting startedAppliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Hardware appliance tasksFor the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.Common tasksThese tasks are common for both the hardware appliance and the virtual appliance.

Getting Started

Complete the following tasks that apply to your appliance format.

Hardware appliance tasks
For the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.

Virtual appliance tasks
You must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Common tasks
These tasks are common for both the hardware appliance and the virtual appliance.

Parent topic: Appliance administration

Hardware appliance tasksHardware appliance tasksIBM Security Access Manager hardware appliance tasksFor the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.appliancestaskshardwarehardware appliancesInstall the network cabling.Connect to the local management interface (LMI) or a serial console.Configure the initial appliance settings.Getting StartedComplete the following tasks that apply to your appliance format.Connecting cables and starting the applianceConnect the appliance to your network after you determine where you want to place it on the network. Options to configure the hardware applianceYou can use either a serial console device that is connected to the appliance or the LMI to configure the hardware appliance. Connecting a serial console to the applianceYou must connect a serial console to the hardware appliance before you can proceed with the configuration tasks through the command-line interface (CLI).Determining the system IP addressIf you want to use the LMI to configure the appliance, use one of the following methods to determine the assigned appliance IP address so that you can access the LMI.

Hardware appliance tasks

For the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.

Install the network cabling.

Connect to the local management interface (LMI) or a serial console.

Configure the initial appliance settings.

Connecting cables and starting the appliance
Connect the appliance to your network after you determine where you want to place it on the network.

Options to configure the hardware appliance
You can use either a serial console device that is connected to the appliance or the LMI to configure the hardware appliance.

Connecting a serial console to the appliance
You must connect a serial console to the hardware appliance before you can proceed with the configuration tasks through the command-line interface (CLI).

Determining the system IP address
If you want to use the LMI to configure the appliance, use one of the following methods to determine the assigned appliance IP address so that you can access the LMI.

Parent topic: Getting Started

Connecting cables and starting the applianceConnecting cables and starting the applianceAccess Manager Appliance: Connecting cables and starting the applianceConnect the appliance to your network after you determine where you want to place it on the network. cable connectionsConnect the power cable to the appliance.Connect Management Interface 1 to the network you want to use to manage the appliance.Connect the network cables to the application interfaces.Turn on the appliance.Hardware appliance tasksFor the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.

Connecting cables and starting the appliance

Connect the appliance to your network after you determine where you want to place it on the network.

Procedure

Connect the power cable to the appliance.

Connect Management Interface 1 to the network you want to use to manage the appliance.

Connect the network cables to the application interfaces.

Turn on the appliance.

Parent topic: Hardware appliance tasks

Options to configure the hardware applianceOptions to configure the hardware applianceAccess Manager Appliance: Options to configure the hardware applianceYou can use either a serial console device that is connected to the appliance or the LMI to configure the hardware appliance. configurationhardware applianceshardware appliancesserial consolesLMIconfigure hardware appliancesThe LMI is the preferable option as it offers more advanced configuration options.To use a serial console device, you must connect the console device to the hardware appliance with a serial cable. For instructions, see Connecting a serial console to the applianceYou must connect a serial console to the hardware appliance before you can proceed with the configuration tasks through the command-line interface (CLI)..To use the LMI to configure the appliance, you must browse to the IP address of the appliance. If you do not know the IP address of the appliance, follow instructions in Determining the system IP addressIf you want to use the LMI to configure the appliance, use one of the following methods to determine the assigned appliance IP address so that you can access the LMI..Hardware appliance tasksFor the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.

Options to configure the hardware appliance

You can use either a serial console device that is connected to the appliance or the LMI to configure the hardware appliance.

The LMI is the preferable option as it offers more advanced configuration options.

To use a serial console device, you must connect the console device to the hardware appliance with a serial cable. For instructions, see Connecting a serial console to the appliance.

To use the LMI to configure the appliance, you must browse to the IP address of the appliance. If you do not know the IP address of the appliance, follow instructions in Determining the system IP address.

Parent topic: Hardware appliance tasks

Connecting a serial console to the applianceConnecting a serial console to the applianceAccess Manager Appliance: Connecting a serial console to the applianceYou must connect a serial console to the hardware appliance before you can proceed with the configuration tasks through the command-line interface (CLI).serial consolessetupterminal emulationhardware appliancesConnect the console device to the hardware appliance with a serial cable.Your appliance package might contain a USB serial console cable and a DB-9 serial console cable, or the package might contain only a DB-9 serial console cable. If you use the USB serial console cable and your PC does not recognize the cable, you might need to install the device driver. The device drivers are available for download from http://public.dhe.ibm.com/software/security/products/infrastructure_protection/USBDeviceDrivers or from the driver supplier at http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41.If you use a computer as the console device, connect to the appliance with Microsoft Hyperterminal or another terminal emulation program by using the following settings:Communication PortTypically COM1EmulationVT100Bits per second9600Data bits8ParityNoneStop bits1Flow controlNoneFollow the instructions in Common tasksThese tasks are common for both the hardware appliance and the virtual appliance. to configure initial appliance settings.Hardware appliance tasksFor the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.

Connecting a serial console to the appliance

You must connect a serial console to the hardware appliance before you can proceed with the configuration tasks through the command-line interface (CLI).

Procedure

Connect the console device to the hardware appliance with a serial cable.

Note: Your appliance package might contain a USB serial console cable and a DB-9 serial console cable, or the package might contain only a DB-9 serial console cable. If you use the USB serial console cable and your PC does not recognize the cable, you might need to install the device driver.

The device drivers are available for download from http://public.dhe.ibm.com/software/security/products/infrastructure_protection/USBDeviceDrivers or from the driver supplier at http://www.prolific.com.tw/US/ShowProduct.aspx?p_id=225&pcid=41.

If you use a computer as the console device, connect to the appliance with Microsoft Hyperterminal or another terminal emulation program by using the following settings:

Option | Description
Communication Port | Typically COM1
Emulation | VT100
Bits per second | 9600
Data bits | 8
Parity | None
Stop bits | 1
Flow control | None

Follow the instructions in Common tasks to configure initial appliance settings.

Parent topic: Hardware appliance tasks

Determining the system IP addressDetermining the system IP addressDetermining the system IP address that is assigned to the IBM Security Access Manager ApplianceIf you want to use the LMI to configure the appliance, use one of the following methods to determine the assigned appliance IP address so that you can access the LMI.LMIaccesslocal management interfaceLMIMethod 1: Use the LCD panel to determine the IP address of the appliance. Press OK on the LCD panel to view the main menu.The OK button is labeled with an arrow.Use the arrows to select IP Address. Press OK. The LCD panel displays the IP address of the appliance. Take note of the address.Method 2: Use zero-configuration networking to discover the appliance on your network. Because the appliance uses a set of industry standard IP protocols, it can be discovered automatically when it is physically connected to your network.Hardware appliance tasksFor the hardware appliance, after you determine where to place the appliance in your network, complete the following tasks.

Determining the system IP address

If you want to use the LMI to configure the appliance, use one of the following methods to determine the assigned appliance IP address so that you can access the LMI.

Method 1: Use the LCD panel to determine the IP address of the appliance.

Press OK on the LCD panel to view the main menu.

Note: The OK button is labeled with an arrow.

Use the arrows to select IP Address.

Press OK.

The LCD panel displays the IP address of the appliance. Take note of the address.

Method 2: Use zero-configuration networking to discover the appliance on your network.

Because the appliance uses a set of industry standard IP protocols, it can be discovered automatically when it is physically connected to your network.

Parent topic: Hardware appliance tasks

Virtual appliance tasksVirtual appliance tasksVirtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.virtual appliancestasksGetting StartedComplete the following tasks that apply to your appliance format.Setting up the virtual networkThe administrator who is installing the appliance must be familiar with virtual networking concepts.Installing the virtual appliance by using VMwareUse the provided .iso image to install the virtual appliance.Installing the virtual appliance by using the vSphere APIThe virtual appliance can be installed by using the vSphere API.Installing the virtual appliance by using KVMThe use of Kernel-based virtual machine or KVM is supported. You can use KVM with the provided .iso image so that you can run the virtual appliance.XenServer supportThe Security Access Manager appliance can be installed on a XenServer hypervisor (version 6.2 and later). Amazon EC2 supportYou can deploy Security Access Manager to the Amazon Elastic Compute Cloud (Amazon EC2) environment.Calculating license usageThe IBM Security Access Manager virtual appliance is not detected by IBM License Metric Tool. To calculate license usage, create a Processor Value Unit (PVU) report.Setting up Cloud Orchestrator supportThe virtual appliance has basic support for Cloud Orchestrator as imported KVM virtual images. It is possible to run the appliance within a Cloud Orchestrator environment and use it to perform basic virtual image management tasks.USB support on virtual appliancesAdministrators of virtual appliances can use a physical USB drive for tasks such as uploading a new firmware, uploading or downloading a snapshot file, and downloading a support file.

Virtual appliance tasks

You must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Setting up the virtual network
The administrator who is installing the appliance must be familiar with virtual networking concepts.

Installing the virtual appliance by using VMware
Use the provided .iso image to install the virtual appliance.

Installing the virtual appliance by using the vSphere API
The virtual appliance can be installed by using the vSphere API.

Installing the virtual appliance by using KVM
The use of Kernel-based virtual machine or KVM is supported. You can use KVM with the provided .iso image so that you can run the virtual appliance.

XenServer support
The Security Access Manager appliance can be installed on a XenServer hypervisor (version 6.2 and later).

Amazon EC2 support
You can deploy Security Access Manager to the Amazon Elastic Compute Cloud (Amazon EC2) environment.

Calculating license usage
The IBM® Security Access Manager virtual appliance is not detected by IBM License Metric Tool. To calculate license usage, create a Processor Value Unit (PVU) report.

Setting up Cloud Orchestrator support
The virtual appliance has basic support for Cloud Orchestrator as imported KVM virtual images. It is possible to run the appliance within a Cloud Orchestrator environment and use it to perform basic virtual image management tasks.

USB support on virtual appliances
Administrators of virtual appliances can use a physical USB drive for tasks such as uploading a new firmware, uploading or downloading a snapshot file, and downloading a support file.

Parent topic: Getting Started

Setting up the virtual networkSetting up the virtual networkSetting up the virtual network for the IBM Security Web Gateway virtual applianceThe administrator who is installing the appliance must be familiar with virtual networking concepts.virtualappliancesinstallationThe virtual appliance installation does not support scripts. To install multiple virtual appliances, you can install the first appliance manually and make copies of it.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Setting up the virtual network

The administrator who is installing the appliance must be familiar with virtual networking concepts.

The virtual appliance installation does not support scripts. To install multiple virtual appliances, you can install the first appliance manually and make copies of it.

Parent topic: Virtual appliance tasks

Installing the virtual appliance by using VMwareInstalling the virtual appliance by using VMwareSecurity Access Manager: Installing the virtual appliance by using VMwareUse the provided .iso image to install the virtual appliance.virtual appliancesinstallationVMwareCreate a new virtual machine with your VMware ESX or vSphere. The instructions for creating a virtual machine might differ depending on your VMware ESX or vSphere version. See the VMware documentation that suits your version for specific instructions.Ensure that the virtual machine has enough allocated disk space to store the configuration and log file data for the appliance. Allocate at least 100 GB of disk space for the appliance.Specify Virtual Machine Version 7 or later as your virtual machine version.Specify Linux as the guest operating system and Other 2.6x Linux (64-bit) as the guest operating system version.The memory size has influence over how many WebSEAL instances can be created and how many sessions can be active at a single point in time. The minimum memory size is 4096 MB.A virtual appliance must have a minimum of one and a maximum of eight network adapters.Each network adapter must be of the type E1000 or VMXNET 3. Use VMXNET 3 for better performance.For SCSI controller, select LSI Logic Parallel.For Virtual Device Node, select SCSI (0:0).Diskette, COM ports, and LPT port must be enabled in the BIOS settings of the VM.VMware Tools on the appliance provide the following enhancements:VMware commands for graceful shutdownImproved monitoringTime synchronization with the host operating system unless an NTP server is configuredConfigure the virtual machine to boot from the .iso file and then start the virtual machine.If the hard disk that is attached to the virtual machine already contains a Linux partition, the installer always runs in interactive mode. To run the installer in silent mode, wait 10 seconds or press Enter. After the silent installation completes, the virtual machine is shut down automatically. If you want to continue with setting up the appliance, restart the virtual machine.To run the installer in interactive mode, enter interactive and then press Enter.Select the language for the installation by entering the number that corresponds to the language that you want to use.Enter YES to proceed with the installation. Alternatively if you do not want to proceed with the installation, enter NO to move to the reboot prompt.Examine the installation messages to ensure that the installation was successful. After the installation process is complete, unmount the installation media and then press Enter to reboot the appliance.When the reboot operation is complete, you can start the console-based appliance setup wizard by logging on as the admin user with a password of admin. Alternatively, the Appliance Setup wizard can be accessed through the local management interface.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Installing the virtual appliance by using VMware

Use the provided .iso image to install the virtual appliance.

Procedure

Create a new virtual machine with your VMware ESX or vSphere.

Note:

The instructions for creating a virtual machine might differ depending on your VMware ESX or vSphere version. See the VMware documentation that suits your version for specific instructions.

Ensure that the virtual machine has enough allocated disk space to store the configuration and log file data for the appliance. Allocate at least 100 GB of disk space for the appliance.

Specify Virtual Machine Version 7 or later as your virtual machine version.

Specify Linux as the guest operating system and Other 2.6x Linux (64-bit) as the guest operating system version.

The memory size has influence over how many WebSEAL instances can be created and how many sessions can be active at a single point in time. The minimum memory size is 4096 MB.

A virtual appliance must have a minimum of one and a maximum of eight network adapters.

Each network adapter must be of the type E1000 or VMXNET 3. Use VMXNET 3 for better performance.

For SCSI controller, select LSI Logic Parallel.

For Virtual Device Node, select SCSI (0:0).

Diskette, COM ports, and LPT port must be enabled in the BIOS settings of the VM.

VMware Tools on the appliance provide the following enhancements:

VMware commands for graceful shutdown

Improved monitoring

Time synchronization with the host operating system unless an NTP server is configured

Configure the virtual machine to boot from the .iso file and then start the virtual machine.

Note: If the hard disk that is attached to the virtual machine already contains a Linux partition, the installer always runs in interactive mode.

To run the installer in silent mode, wait 10 seconds or press Enter. After the silent installation completes, the virtual machine is shut down automatically. If you want to continue with setting up the appliance, restart the virtual machine.

To run the installer in interactive mode, enter interactive and then press Enter.

Select the language for the installation by entering the number that corresponds to the language that you want to use.

Enter YES to proceed with the installation. Alternatively if you do not want to proceed with the installation, enter NO to move to the reboot prompt.

Examine the installation messages to ensure that the installation was successful. After the installation process is complete, unmount the installation media and then press Enter to reboot the appliance.

When the reboot operation is complete, you can start the console-based appliance setup wizard by logging on as the admin user with a password of admin. Alternatively, the Appliance Setup wizard can be accessed through the local management interface.

Parent topic: Virtual appliance tasks

Installing the virtual appliance by using the vSphere APIThe virtual appliance can be installed by using the vSphere API.Security Access Manager provides a sample Python script that utilizes the vSphere API to deploy the appliance. This script can be obtained from the appliance File Downloads page. You can examine this script to determine the steps for deploying the appliance. At a high level, the script has two main functions: Create a template on the vSphere server. This step involves uploading an ISO image of the appliance, performing a silent install, and converting this new VM to a template.Deploy a template. This step involves cloning this template into a new VM. This step can make use of a silent configuration ISO to configure the networking. This ISO can also be generated by this script. After the silent configuration ISO image has been generated, the script instructs the user to manually upload the image to a datastore of the vSphere environment. In the local management interface of the appliance, select Manage System SettingsSecure SettingsFile Downloads.Expand CommonSampleDeploy.Select the deploy_isam_to_vsphere.py file.Click Export to save the file to your local drive.Examine the script to determine the steps to deploy and run the virtual appliance. Help on the script can be obtained by running the following command: python deploy_isam_to_vsphere.py --help Supported Python versions are 2.7 and 3.4. In Python versions 2.7.9, 3.4.3, or later, unverified SSL connections are disabled. Ensure that the vSphere server certificate is present in the keystore that Python uses.Supported vSphere versions are 4.1, 5.0, 5.1, and 5.5.The pyVmomi library is required. It can be installed from the pip tool or from https://github.com/vmware/pyvmomi.To run the script, you must have the genisoimage or mkisofs tools in your path.Modify the script as needed.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Installing the virtual appliance by using the vSphere API

The virtual appliance can be installed by using the vSphere API.

About this task

Security Access Manager provides a sample Python script that utilizes the vSphere API to deploy the appliance. This script can be obtained from the appliance File Downloads page. You can examine this script to determine the steps for deploying the appliance.

At a high level, the script has two main functions:

Create a template on the vSphere server. This step involves uploading an ISO image of the appliance, performing a silent install, and converting this new VM to a template.

Deploy a template. This step involves cloning this template into a new VM. This step can make use of a silent configuration ISO to configure the networking. This ISO can also be generated by this script. After the silent configuration ISO image has been generated, the script instructs the user to manually upload the image to a datastore of the vSphere environment.

Procedure

In the local management interface of the appliance, select Manage System Settings > Secure Settings > File Downloads.

Expand Common > Sample > Deploy.

Select the deploy_isam_to_vsphere.py file.

Click Export to save the file to your local drive.

Examine the script to determine the steps to deploy and run the virtual appliance. Help on the script can be obtained by running the following command:

python deploy_isam_to_vsphere.py --help

Note:

Supported Python versions are 2.7 and 3.4.

In Python versions 2.7.9, 3.4.3, or later, unverified SSL connections are disabled. Ensure that the vSphere server certificate is present in the keystore that Python uses.

Supported vSphere versions are 4.1, 5.0, 5.1, and 5.5.

The pyVmomi library is required. It can be installed from the pip tool or from https://github.com/vmware/pyvmomi.

To run the script, you must have the genisoimage or mkisofs tools in your path.

Modify the script as needed.

Parent topic: Virtual appliance tasks

Installing the virtual appliance by using KVMInstalling the virtual appliance by using KVMSecurity Access Manager: Installing the virtual appliance by using KVMThe use of Kernel-based virtual machine or KVM is supported. You can use KVM with the provided .iso image so that you can run the virtual appliance.virtual appliancesinstallationKVMCreate a new virtual machine.The instructions for creating a virtual machine might differ based on the utility that you are using to manage your virtual machines. See the KVM documentation that suits your version for specific instructions.Ensure that the virtual machine has enough disk space that is allocated to store the configuration and log file data for the appliance. Allocate at least 100 GB of disk space for the appliance.The memory size has influence over how many WebSEAL instances can be created and how many sessions can be active at a single point in time. The minimum memory size is 4096 MB.A virtual appliance must have a minimum of one and a maximum of eight network adapters.Each network adapter must be of the type E1000 or Virtio. Use Virtio for better performance.The hard disk drive must be configured as a Virtio disk device.If you use certain versions of the Virtual Machine Manager (virt-manager) software to create your virtual machines, it might by default add some CPU definitions that are incompatible with the appliance and thus cause deployment errors. To fix this issue, you can use one of the following methods:From the Virtual Machine Manager console, open the VM definition. Go to Processor. Expand the Configuration option and then change the value of the Model field to Clear CPU configuration. Click Apply.From the virsh shell, edit the virtual machine definition (for example, edit isam_appliance). Locate and then remove the <cpu>...</cpu> entry. Save the file.Configure the virtual machine to start from the .iso file and then start the virtual machine.To run the installer in silent mode, wait 10 seconds or press Enter. After the silent installation completes, the virtual machine is shut down automatically. If you want to continue with setting up the appliance, restart the virtual machine.To run the installer in interactive mode, enter interactive and then press Enter.If the hard disk that is attached to the virtual machine already contains a Linux partition, the installer always runs in interactive mode.Select the language for the installation by entering the number that corresponds to the language that you want to use.Enter YES to proceed with the installation. Alternatively if you do not want to proceed with the installation, enter NO to move to the reboot prompt.Examine the installation messages to ensure that the installation was successful. After the installation process is complete, unmount the installation media and then press Enter to reboot the appliance.When the restart operation is complete, you can start the console-based appliance setup wizard by logging on as the admin user with a password of admin. Alternatively, the Appliance Setup wizard can be accessed through the local management interface.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Installing the virtual appliance by using KVM

The use of Kernel-based virtual machine or KVM is supported. You can use KVM with the provided .iso image so that you can run the virtual appliance.

Procedure

Create a new virtual machine.

Note:

The instructions for creating a virtual machine might differ based on the utility that you are using to manage your virtual machines. See the KVM documentation that suits your version for specific instructions.

Ensure that the virtual machine has enough disk space that is allocated to store the configuration and log file data for the appliance. Allocate at least 100 GB of disk space for the appliance.

The memory size has influence over how many WebSEAL instances can be created and how many sessions can be active at a single point in time. The minimum memory size is 4096 MB.

A virtual appliance must have a minimum of one and a maximum of eight network adapters.

Each network adapter must be of the type E1000 or Virtio. Use Virtio for better performance.

The hard disk drive must be configured as a Virtio disk device.

If you use certain versions of the Virtual Machine Manager (virt-manager) software to create your virtual machines, it might by default add some CPU definitions that are incompatible with the appliance and thus cause deployment errors. To fix this issue, you can use one of the following methods:

From the Virtual Machine Manager console, open the VM definition. Go to Processor. Expand the Configuration option and then change the value of the Model field to Clear CPU configuration. Click Apply.

From the virsh shell, edit the virtual machine definition (for example, edit isam_appliance). Locate and then remove the <cpu>...</cpu> entry. Save the file.

Configure the virtual machine to start from the .iso file and then start the virtual machine.

To run the installer in silent mode, wait 10 seconds or press Enter. After the silent installation completes, the virtual machine is shut down automatically. If you want to continue with setting up the appliance, restart the virtual machine.

To run the installer in interactive mode, enter interactive and then press Enter.

Note: If the hard disk that is attached to the virtual machine already contains a Linux partition, the installer always runs in interactive mode.

Select the language for the installation by entering the number that corresponds to the language that you want to use.

Enter YES to proceed with the installation. Alternatively if you do not want to proceed with the installation, enter NO to move to the reboot prompt.

Examine the installation messages to ensure that the installation was successful. After the installation process is complete, unmount the installation media and then press Enter to reboot the appliance.

When the restart operation is complete, you can start the console-based appliance setup wizard by logging on as the admin user with a password of admin. Alternatively, the Appliance Setup wizard can be accessed through the local management interface.

Parent topic: Virtual appliance tasks

XenServer supportThe Security Access Manager appliance can be installed on a XenServer hypervisor (version 6.2 and later). When the appliance is installed on XenServer, it runs in paravirtualized (PV) mode rather than hardware assisted virtualization (HVM) mode. The Security Access Manager appliance for XenServer is distributed as a pre-installed disk image of the appliance in Virtual Hard Disk (VHD) format. Standard installation ISO images cannot be used due to some restrictions with XenServer. The disk has a fixed size of 100 GB. It is recommended to enable off-the-box logging and auditing to ensure that the disk is not consumed with log files.To deploy the VHD appliance image to XenServer, you can use either of the following methods:The XenCenter consoleXenAPI or xe command lineVirtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.Installing the virtual appliance by using XenCenterImport the VHD image to XenServer with XenCenter to install the virtual appliance.Installing the virtual appliance by using XenAPI or xe command lineThe virtual appliance can be installed by using the XenAPI or xe command line.

XenServer support

The Security Access Manager appliance can be installed on a XenServer hypervisor (version 6.2 and later).

When the appliance is installed on XenServer, it runs in paravirtualized (PV) mode rather than hardware assisted virtualization (HVM) mode.

The Security Access Manager appliance for XenServer is distributed as a pre-installed disk image of the appliance in Virtual Hard Disk (VHD) format. Standard installation ISO images cannot be used due to some restrictions with XenServer. The disk has a fixed size of 100 GB. It is recommended to enable off-the-box logging and auditing to ensure that the disk is not consumed with log files.

To deploy the VHD appliance image to XenServer, you can use either of the following methods:

The XenCenter console

XenAPI or xe command line

Installing the virtual appliance by using XenCenter
Import the VHD image to XenServer with XenCenter to install the virtual appliance.

Installing the virtual appliance by using XenAPI or xe command line
The virtual appliance can be installed by using the XenAPI or xe command line.

Parent topic: Virtual appliance tasks

Installing the virtual appliance by using XenCenterImport the VHD image to XenServer with XenCenter to install the virtual appliance.Make sure that you have the following prerequisites:A functional XenServer environment, which is used as the hypervisor to host the VHD image.A configured XenCenter installation, which is used to deploy the VHD image.In the XenCenter console, expand the XenCenter icon on the left.Right-click the attached hypervisor and select Import.In the Import Source window:Click Browse.Select the VHD image to be imported and click Open.Click Next.In the VM Definition window:Specify the name, number of CPUs, and memory of the virtual machine.In most scenarios, assign the virtual machine at least one processor and 2 GB of memory. These settings can be adjusted after the virtual machine starts running.Click Next.In the Location window: Select the destination hypervisor from the drop-down list on the right.Click Next.In the Storage window: Select Place imported virtual disks onto specified target SRs.Click Next.In the Networking window:Select the network to be used for the first management interface.Click Next.In the OS Fixup Settings window:Select Don't use Operating System Fixup.Click Next.In the Transfer VM Settings window:Specify the settings to suit your network environment. If DHCP is not available in the network, a valid IP address, subnet, and gateway must be specifiedClick Next.In the Finish window, click Finish to start the import.The import operation might take a considerable amount of time to complete. You can click the Logs tab to check the progress of the import.When the import is complete, run the following commands on the XenServer console to set the image to paravirtualized mode.xe vm-list (to get the uuid for the VM) xe vm-param-set uuid=<vm uuid> HVM-boot-policy="" xe vm-param-set uuid=<vm uuid> PV-bootloader=pygrub xe vm-disk-list (to get the uuid for the disk - VBD entry) xe vbd-param-set uuid=<disk uuid> bootable=true For example:[root@xenserver ~]# xe vm-list name-label="autodeploy" uuid ( RO) : 6288a6a6-8577-5444-6ed5-46d2a097be54 name-label ( RW): autodeploy power-state ( RO): halted [root@xenserver ~]# xe vm-param-set uuid=6288a6a6-8577-5444-6ed5-46d2a097be54 HVM-boot-policy="" [root@xenserver ~]# xe vm-param-set uuid=6288a6a6-8577-5444-6ed5-46d2a097be54 PV-bootloader=pygrub [root@xenserver ~]# xe vm-disk-list vm="autodeploy" Disk 0 VBD: uuid ( RO) : b0d08251-7f08-8b4e-3913-e71052dd7b13 vm-name-label ( RO): autodeploy userdevice ( RW): xvda Disk 0 VDI: uuid ( RO) : 8dfa6027-1ef3-408b-a9ed-efa751d41720 name-label ( RW): amapp-template_vdi sr-name-label ( RO): Local storage virtual-size ( RO): 107376279552 [root@xenserver ~]# xe vbd-param-set uuid=b0d08251-7f08-8b4e-3913-e71052dd7b13 bootable=trueStart the imported virtual machine.At least one network interface must be configured in order for the appliance to start. Sometimes the XenCenter must be restarted before the new virtual appliance can be started correctly.XenServer supportThe Security Access Manager appliance can be installed on a XenServer hypervisor (version 6.2 and later).

Installing the virtual appliance by using XenCenter

Import the VHD image to XenServer with XenCenter to install the virtual appliance.

Before you begin

Make sure that you have the following prerequisites:

A functional XenServer environment, which is used as the hypervisor to host the VHD image.

A configured XenCenter installation, which is used to deploy the VHD image.

Procedure

In the XenCenter console, expand the XenCenter icon on the left.

Right-click the attached hypervisor and select Import.

In the Import Source window:

Click Browse.

Select the VHD image to be imported and click Open.

Click Next.

In the VM Definition window:

Specify the name, number of CPUs, and memory of the virtual machine.

Note: In most scenarios, assign the virtual machine at least one processor and 2 GB of memory. These settings can be adjusted after the virtual machine starts running.

Click Next.

In the Location window:

Select the destination hypervisor from the drop-down list on the right.

Click Next.

In the Storage window:

Select Place imported virtual disks onto specified target SRs.

Click Next.

In the Networking window:

Select the network to be used for the first management interface.

Click Next.

In the OS Fixup Settings window:

Select Don't use Operating System Fixup.

Click Next.

In the Transfer VM Settings window:

Specify the settings to suit your network environment.

Note: If DHCP is not available in the network, a valid IP address, subnet, and gateway must be specified

Click Next.

In the Finish window, click Finish to start the import.

Note: The import operation might take a considerable amount of time to complete. You can click the Logs tab to check the progress of the import.

When the import is complete, run the following commands on the XenServer console to set the image to paravirtualized mode.

xe vm-list (to get the uuid for the VM)
xe vm-param-set uuid=<vm uuid> HVM-boot-policy=""
xe vm-param-set uuid=<vm uuid> PV-bootloader=pygrub
xe vm-disk-list (to get the uuid for the disk - VBD entry)
xe vbd-param-set uuid=<disk uuid> bootable=true

For example:

[root@xenserver ~]# xe vm-list name-label="autodeploy"
uuid ( RO)           : 6288a6a6-8577-5444-6ed5-46d2a097be54
     name-label ( RW): autodeploy
    power-state ( RO): halted
[root@xenserver ~]# xe vm-param-set uuid=6288a6a6-8577-5444-6ed5-46d2a097be54 HVM-boot-policy=""
[root@xenserver ~]# xe vm-param-set uuid=6288a6a6-8577-5444-6ed5-46d2a097be54 PV-bootloader=pygrub
[root@xenserver ~]# xe vm-disk-list vm="autodeploy"
Disk 0 VBD:
uuid ( RO)             : b0d08251-7f08-8b4e-3913-e71052dd7b13
    vm-name-label ( RO): autodeploy
       userdevice ( RW): xvda

Disk 0 VDI:
uuid ( RO)             : 8dfa6027-1ef3-408b-a9ed-efa751d41720
       name-label ( RW): amapp-template_vdi
    sr-name-label ( RO): Local storage
     virtual-size ( RO): 107376279552

[root@xenserver ~]# xe vbd-param-set uuid=b0d08251-7f08-8b4e-3913-e71052dd7b13 bootable=true

Start the imported virtual machine.

Note: At least one network interface must be configured in order for the appliance to start. Sometimes the XenCenter must be restarted before the new virtual appliance can be started correctly.

Parent topic: XenServer support

Installing the virtual appliance by using XenAPI or xe command lineThe virtual appliance can be installed by using the XenAPI or xe command line.Security Access Manager provides a sample python script that utilizes the xe command line utility to deploy the appliance. This script can be obtained from the appliance File Downloads page. You can examine this script to determine the steps for deploying the appliance. At a high level, the script has two main steps: Create a template. This step uploads the VHD to XenServer and creates a VM template from the VHD. The Xen Web Service that is used to upload the image file requires the image to be in RAW or a more efficient proprietary XenServer chunked format. You must convert the VHD image file to a supported image format before uploading it to the XenServer. The script provides an option to perform this conversion.Deploy a template. This step creates an instance of the appliance from the template that was created in the previous step.In the local management interface of the appliance, select Manage System SettingsSecure SettingsFile Downloads.Expand CommonSampleDeploy.Select the deploy_isam_to_xen.py file.Click Export to save the file to your local drive.Examine the script to determine the steps to deploy and run the virtual appliance. Help on the script can be obtained by running the following command: python deploy_isam_to_xen.py --help Supported python versions are 2.79 and 3.4.3. This script has a dependency on the requests and pexpect modules.This script is not supported on the Windows platform.Modify the script as needed.XenServer supportThe Security Access Manager appliance can be installed on a XenServer hypervisor (version 6.2 and later).

Installing the virtual appliance by using XenAPI or xe command line

The virtual appliance can be installed by using the XenAPI or xe command line.

About this task

Security Access Manager provides a sample python script that utilizes the xe command line utility to deploy the appliance. This script can be obtained from the appliance File Downloads page. You can examine this script to determine the steps for deploying the appliance.

At a high level, the script has two main steps:

Create a template. This step uploads the VHD to XenServer and creates a VM template from the VHD. The Xen Web Service that is used to upload the image file requires the image to be in RAW or a more efficient proprietary XenServer chunked format. You must convert the VHD image file to a supported image format before uploading it to the XenServer. The script provides an option to perform this conversion.

Deploy a template. This step creates an instance of the appliance from the template that was created in the previous step.

Procedure

In the local management interface of the appliance, select Manage System Settings > Secure Settings > File Downloads.

Expand Common > Sample > Deploy.

Select the deploy_isam_to_xen.py file.

Click Export to save the file to your local drive.

Examine the script to determine the steps to deploy and run the virtual appliance. Help on the script can be obtained by running the following command:

python deploy_isam_to_xen.py --help

Note:

Supported python versions are 2.79 and 3.4.3.

This script has a dependency on the requests and pexpect modules.

This script is not supported on the Windows platform.

Modify the script as needed.

Parent topic: XenServer support

Amazon EC2 supportYou can deploy Security Access Manager to the Amazon Elastic Compute Cloud (Amazon EC2) environment.Amazon EC2 is a web service that provides:Scalable computing capacity in the Amazon Web Services (AWS) cloudCapability to deploy an Amazon Machine Image (AMI)Deploying Security Access Manager to Amazon EC2 involves the following processes:Create an Amazon Machine Image (AMI) from the appliance VHD image.Launch an instance of the AMI in Amazon EC2.If you want to use the Amazon Elastic Load Balancing, configure the appliance to send statistical data to Amazon CloudWatch.Complete these processes either manually or with an automated script. Obtain the deploy_isam_to_amazon_ec2.py script from the File Downloads page in the commonsamplesdeploy directory on a running appliance. To see script help, run the following command: python deploy_isam_to_amazon_ec2.py --help Supported python versions are 2.79 and 3.4.3. This script has a dependency on the requests module. For details about how to use the Amazon EC2 command line interface to launch an instance, see Launching an Instance Using the Amazon EC2 CLI. Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.Creating an Amazon Machine Image (AMI) from the Virtual Hard Disk (VHD) fileUpload the appliance VHD image to Amazon EC2 and create an AMI so that it can be deployed in Amazon EC2. Launching the appliance AMILaunch an instance of the appliance AMI to run the appliance in Amazon EC2.Post-installation activitiesAfter you install the appliance in Amazon EC2, complete these activities to enable data transmission to Amazon CloudWatch or change the port on which the LMI listens.

Amazon EC2 support

You can deploy Security Access Manager to the Amazon Elastic Compute Cloud (Amazon EC2) environment.

Amazon EC2 is a web service that provides:

Scalable computing capacity in the Amazon Web Services (AWS) cloud

Capability to deploy an Amazon Machine Image (AMI)

Deploying Security Access Manager to Amazon EC2 involves the following processes:

Create an Amazon Machine Image (AMI) from the appliance VHD image.

Launch an instance of the AMI in Amazon EC2.

If you want to use the Amazon Elastic Load Balancing, configure the appliance to send statistical data to Amazon CloudWatch.

Complete these processes either manually or with an automated script. Obtain the deploy_isam_to_amazon_ec2.py script from the File Downloads page in the common > samples > deploy directory on a running appliance. To see script help, run the following command:

python deploy_isam_to_amazon_ec2.py --help

Note:

Supported python versions are 2.79 and 3.4.3.

This script has a dependency on the requests module.

For details about how to use the Amazon EC2 command line interface to launch an instance, see Launching an Instance Using the Amazon EC2 CLI.

Creating an Amazon Machine Image (AMI) from the Virtual Hard Disk (VHD) file
Upload the appliance VHD image to Amazon EC2 and create an AMI so that it can be deployed in Amazon EC2.

Launching the appliance AMI
Launch an instance of the appliance AMI to run the appliance in Amazon EC2.

Post-installation activities
After you install the appliance in Amazon EC2, complete these activities to enable data transmission to Amazon CloudWatch or change the port on which the LMI listens.

Parent topic: Virtual appliance tasks

Creating an Amazon Machine Image (AMI) from the Virtual Hard Disk (VHD) fileUpload the appliance VHD image to Amazon EC2 and create an AMI so that it can be deployed in Amazon EC2. Follow these steps to manually upload an image and create an AMI with the Amazon EC2 console. If you want to automate this process, use the deploy_isam_to_amazon_ec2.py script from the appliance File Downloads page. Download and install the Amazon EC2 API Tools. You can download the tool from the Amazon EC2 API Tools page. Run the following commands in the specified sequence to upload the VHD to Amazon EC2 and create an AMI. SequenceCommandDescription1ec2-import-volumeImports the appliance VHD into Amazon EC2. 2ec2-describe-conversion-tasksMonitors the ec2-import-volume task to show when the task is complete.3ec2-create-snapshotCreates a snapshot of the imported disk image. This snapshot is required during the AMI registration process.4ec2-describe-snapshotsMonitors the status of the snapshot creation to show when the snapshot task is complete.5ec2-registerRegisters a snapshot as a new AMI. You must use the following parameter values when you register the AMI: architecture:x86_64 kernel: This value varies depending on the geographic location of your Amazon EC2 deployment. Use the kernel image identifier that corresponds to the x86_64 PV-GRUB kernel for your geographic region. You can find the full list of kernal image IDs on the PV-GRUB page on the Amazon EC2 documentation website. root device name:/dev/xvda virtualization type:paravirtual6ec2-delete-disk-imageRemoves the uploaded disk image from the storage bucket. The image is no longer required after you finish registering an AMI from the image. Amazon EC2 supportYou can deploy Security Access Manager to the Amazon Elastic Compute Cloud (Amazon EC2) environment.

Creating an Amazon Machine Image (AMI) from the Virtual Hard Disk (VHD) file

Upload the appliance VHD image to Amazon EC2 and create an AMI so that it can be deployed in Amazon EC2.

About this task

Follow these steps to manually upload an image and create an AMI with the Amazon EC2 console. If you want to automate this process, use the deploy_isam_to_amazon_ec2.py script from the appliance File Downloads page.

Procedure

Download and install the Amazon EC2 API Tools. You can download the tool from the Amazon EC2 API Tools page.

Run the following commands in the specified sequence to upload the VHD to Amazon EC2 and create an AMI.

Sequence
Command
Description

1
ec2-import-volume
Imports the appliance VHD into Amazon EC2.

2
ec2-describe-conversion-tasks
Monitors the ec2-import-volume task to show when the task is complete.

3
ec2-create-snapshot
Creates a snapshot of the imported disk image. This snapshot is required during the AMI registration process.

4
ec2-describe-snapshots
Monitors the status of the snapshot creation to show when the snapshot task is complete.

5
ec2-register
Registers a snapshot as a new AMI.

You must use the following parameter values when you register the AMI:

architecture:

x86_64

kernel:

This value varies depending on the geographic location of your Amazon EC2 deployment. Use the kernel image identifier that corresponds to the x86_64 PV-GRUB kernel for your geographic region. You can find the full list of kernal image IDs on the PV-GRUB page on the Amazon EC2 documentation website.

root device name:

/dev/xvda

virtualization type:

paravirtual

6
ec2-delete-disk-image
Removes the uploaded disk image from the storage bucket. The image is no longer required after you finish registering an AMI from the image.

Parent topic: Amazon EC2 support

Launching the appliance AMILaunch an instance of the appliance AMI to run the appliance in Amazon EC2. Follow these steps to manually launch an instance of the appliance AMI with the Amazon EC2 console. If you want to automate this process, use the deploy_isam_to_amazon_ec2.py script that is available from the appliance File Downloads page. Log in to the Amazon EC2 console.Go to IMAGESAMIs.Select the AMI that you want to launch.Click Launch.In the Choose an Instance Type window, select an instance type and click Next: Configure Instance Details.In the Configure Instance Details window, select the options that best fit your environment and click Next: Add Storage.In the Add Storage window, validate the storage and click Next: Tag Instance.In the Tag Instance window, add any desired tags and then click Click Next: Configure Security Group.In the Configure Security Group window, ensure that the selected security group allows inbound SSH and HTTPS access to the appliance. Restrict the access to only those IP addresses from which the appliance is administered. Click Review and Launch.Review the details in the Review Instance window and click Launch. In the Select an existing key pair or Create a new key pair window, you can opt to Proceed without a key pair. Check the acknowledgment check box. Click Launch Instances to proceed. You do not need to associate a key pair with the instance. If you want to log on to the console of the launched instance, log on as the admin user. Go to INSTANCESInstances to check the status of the appliance instance.Amazon EC2 supportYou can deploy Security Access Manager to the Amazon Elastic Compute Cloud (Amazon EC2) environment.

Launching the appliance AMI

Launch an instance of the appliance AMI to run the appliance in Amazon EC2.

About this task

Follow these steps to manually launch an instance of the appliance AMI with the Amazon EC2 console. If you want to automate this process, use the deploy_isam_to_amazon_ec2.py script that is available from the appliance File Downloads page.

Procedure

Log in to the Amazon EC2 console.

Go to IMAGES > AMIs.

Select the AMI that you want to launch.

Click Launch.

In the Choose an Instance Type window, select an instance type and click Next: Configure Instance Details.

In the Configure Instance Details window, select the options that best fit your environment and click Next: Add Storage.

In the Add Storage window, validate the storage and click Next: Tag Instance.

In the Tag Instance window, add any desired tags and then click Click Next: Configure Security Group.

In the Configure Security Group window, ensure that the selected security group allows inbound SSH and HTTPS access to the appliance. Restrict the access to only those IP addresses from which the appliance is administered. Click Review and Launch.

Review the details in the Review Instance window and click Launch.

In the Select an existing key pair or Create a new key pair window, you can opt to Proceed without a key pair. Check the acknowledgment check box. Click Launch Instances to proceed.

Note: You do not need to associate a key pair with the instance. If you want to log on to the console of the launched instance, log on as the admin user.

Go to INSTANCES > Instances to check the status of the appliance instance.

Parent topic: Amazon EC2 support

Post-installation activitiesAfter you install the appliance in Amazon EC2, complete these activities to enable data transmission to Amazon CloudWatch or change the port on which the LMI listens. Amazon EC2 supportYou can deploy Security Access Manager to the Amazon Elastic Compute Cloud (Amazon EC2) environment.Configuring Amazon CloudWatch supportConfigure the appliance to send statistical data to Amazon CloudWatch so that this information can be used by the Amazon Elastic Load Balancer to handle the auto-scaling requirements of the environment.Configuring the local management interface portBy default, Amazon EC2 supports running an instance with a single network interface. To run the appliance with a single network interface, you might want to change the port on which the local management interface listens so that it can be used by other services on the appliance, such as the Web Reverse Proxy.

Post-installation activities

After you install the appliance in Amazon EC2, complete these activities to enable data transmission to Amazon CloudWatch or change the port on which the LMI listens.

Configuring Amazon CloudWatch support
Configure the appliance to send statistical data to Amazon CloudWatch so that this information can be used by the Amazon Elastic Load Balancer to handle the auto-scaling requirements of the environment.

Configuring the local management interface port
By default, Amazon EC2 supports running an instance with a single network interface. To run the appliance with a single network interface, you might want to change the port on which the local management interface listens so that it can be used by other services on the appliance, such as the Web Reverse Proxy.

Parent topic: Amazon EC2 support

Configuring Amazon CloudWatch supportConfigure the appliance to send statistical data to Amazon CloudWatch so that this information can be used by the Amazon Elastic Load Balancer to handle the auto-scaling requirements of the environment. To enable this service, configure the ec2.cloudwatch.frequency advanced tuning parameter to set how often the appliance sends the data to Amazon EC2. To automate this configuration, use the deploy_isam_to_amazon_ec2.py script from the appliance File Downloads page. The appliance can report memory, swap, and disk space usage metrics to Amazon CloudWatch. If you already have an AWS Identity and Access Management role that is associated with your instance, make sure that it has permissions to perform the Amazon CloudWatch PutMetricData operation. Otherwise, you must create a new IAM role with permissions to perform CloudWatch operations and associate that role when you launch a new instance. In the appliance local management interface, go to Manage System SettingsSystem SettingsAdvanced Tuning Parameters. Click New.Enter ec2.cloudwatch.frequency in the Key field.In the Value field, set the frequency in minutes for the appliance to send statistical data to Amazon CloudWatch. A value of 0 disables the service. Monitor the system log for any errors that might occur when the appliance sends the data to CloudWatch. Click Save Configuration.Deploy the changes.Post-installation activitiesAfter you install the appliance in Amazon EC2, complete these activities to enable data transmission to Amazon CloudWatch or change the port on which the LMI listens.

Configuring Amazon CloudWatch support

Configure the appliance to send statistical data to Amazon CloudWatch so that this information can be used by the Amazon Elastic Load Balancer to handle the auto-scaling requirements of the environment.

About this task

To enable this service, configure the ec2.cloudwatch.frequency advanced tuning parameter to set how often the appliance sends the data to Amazon EC2.

To automate this configuration, use the deploy_isam_to_amazon_ec2.py script from the appliance File Downloads page.

The appliance can report memory, swap, and disk space usage metrics to Amazon CloudWatch.

If you already have an AWS Identity and Access Management role that is associated with your instance, make sure that it has permissions to perform the Amazon CloudWatch PutMetricData operation. Otherwise, you must create a new IAM role with permissions to perform CloudWatch operations and associate that role when you launch a new instance.

Procedure

In the appliance local management interface, go to Manage System Settings > System Settings > Advanced Tuning Parameters.

Click New.

Enter ec2.cloudwatch.frequency in the Key field.

In the Value field, set the frequency in minutes for the appliance to send statistical data to Amazon CloudWatch. A value of 0 disables the service.

Note: Monitor the system log for any errors that might occur when the appliance sends the data to CloudWatch.

Click Save Configuration.

Deploy the changes.

Parent topic: Post-installation activities

Configuring the local management interface portBy default, Amazon EC2 supports running an instance with a single network interface. To run the appliance with a single network interface, you might want to change the port on which the local management interface listens so that it can be used by other services on the appliance, such as the Web Reverse Proxy. You can use the Manage System SettingsAdministrator Settings page in the local management interface to configure this setting. If you want to automate this configuration, use the deploy_isam_to_amazon_ec2.py script that is available from the appliance File Downloads page. In the appliance local management interface, go to Manage System SettingsSystem SettingsAdvanced Tuning Parameters. Click New.Enter lmi.https.port in the Key field.In the Value field, enter the appropriate port so that the port on which the local management interface listens can be used by other services on the appliance. Click Save Configuration.Deploy the changes.Post-installation activitiesAfter you install the appliance in Amazon EC2, complete these activities to enable data transmission to Amazon CloudWatch or change the port on which the LMI listens.

Configuring the local management interface port

By default, Amazon EC2 supports running an instance with a single network interface. To run the appliance with a single network interface, you might want to change the port on which the local management interface listens so that it can be used by other services on the appliance, such as the Web Reverse Proxy.

About this task

You can use the Manage System Settings > Administrator Settings page in the local management interface to configure this setting.

If you want to automate this configuration, use the deploy_isam_to_amazon_ec2.py script that is available from the appliance File Downloads page.

Procedure

In the appliance local management interface, go to Manage System Settings > System Settings > Advanced Tuning Parameters.

Click New.

Enter lmi.https.port in the Key field.

In the Value field, enter the appropriate port so that the port on which the local management interface listens can be used by other services on the appliance.

Click Save Configuration.

Deploy the changes.

Parent topic: Post-installation activities

Calculating license usageCalculating license usageCalculating license usageThe IBM Security Access Manager virtual appliance is not detected by IBM License Metric Tool. To calculate license usage, create a Processor Value Unit (PVU) report.licensecalculationmetric toolProcess Value Unit (PVU) reportYou must manually create the Processor Value Unit (PVU) report. You must determine the number and speed of the central processing units (CPUs) on the virtual machine (VM). Select the hypervisor that you are using.VMwareOpen the vSphere Client and connect to the IBM Security Access Manager appliance.Supply the host name and the user name and password.Select the IBM Security Access Manager appliance from the list of VMs. Select the Summary tab to view the number of CPUs assigned. In the General section of the tab there is a line similar to the following entry.CPU: 1 vCPU Select the Resource Allocation tab to view the speed of the processors. The CPU section of the tab displays information similar to the following entry:Host CPU 0 MHz ---> 2800 MHz Consumed: 52.00 MHz Exit the VSphere Client. Retain this information for use in the next steps.KVMFor more information, see the KVM documentation.Consult the following document for specific instructions on how to calculate the PVUs for the target application (the virtual appliance). See page 8 of the document:http://public.dhe.ibm.com/software/passportadvantage/SubCapacity/x86_Scenarios.pdfUse the data that you collect to place entries in the following spreadsheet. See the instructions within the spreadsheet. http://public.dhe.ibm.com/software/passportadvantage/SubCapacity/Manual_Calculation_of_Virtualization_Capacity_Apr_2012.xlsRetain the spreadsheet and data in the event of a license compliance audit.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Calculating license usage

The IBM® Security Access Manager virtual appliance is not detected by IBM License Metric Tool. To calculate license usage, create a Processor Value Unit (PVU) report.

About this task

You must manually create the Processor Value Unit (PVU) report. You must determine the number and speed of the central processing units (CPUs) on the virtual machine (VM).

Procedure

Select the hypervisor that you are using.

VMware

Open the vSphere Client and connect to the IBM Security Access Manager appliance.

Supply the host name and the user name and password.

Select the IBM Security Access Manager appliance from the list of VMs.

Select the Summary tab to view the number of CPUs assigned. In the General section of the tab there is a line similar to the following entry.

CPU: 1 vCPU

Select the Resource Allocation tab to view the speed of the processors. The CPU section of the tab displays information similar to the following entry:

Host CPU 0 MHz ---> 2800 MHz
Consumed: 52.00 MHz

Exit the VSphere Client. Retain this information for use in the next steps.

KVM

For more information, see the KVM documentation.

Consult the following document for specific instructions on how to calculate the PVUs for the target application (the virtual appliance). See page 8 of the document:

http://public.dhe.ibm.com/software/passportadvantage/SubCapacity/x86_Scenarios.pdf

Use the data that you collect to place entries in the following spreadsheet. See the instructions within the spreadsheet.

http://public.dhe.ibm.com/software/passportadvantage/SubCapacity/Manual_Calculation_of_Virtualization_Capacity_Apr_2012.xls

Retain the spreadsheet and data in the event of a license compliance audit.

Parent topic: Virtual appliance tasks

Setting up Cloud Orchestrator supportThe virtual appliance has basic support for Cloud Orchestrator as imported KVM virtual images. It is possible to run the appliance within a Cloud Orchestrator environment and use it to perform basic virtual image management tasks.Consider these limitations before you set up Cloud Orchestrator support: The virtual appliance does not have full support for the orchestration and pattern building capabilities of Cloud Orchestrator.The appliance can be run only in KVM regions.The appliance can be imported and managed in the Virtual Image Library, but cannot be extended with the IBM Image Construction and Composition Tool.The appliance cannot be used in pattern-based deployments.The basic operations that are provided by Cloud Orchestrator for the imported appliance image include the ability to stop, start, or delete the virtual machine.The appliance must be run with a single network interface. To use the virtual appliance as an imported virtual image within a Cloud environment, use the following high-level procedure. For more information, see the IBM Cloud Orchestrator Knowledge Center.Create a KVM virtual machine image and install the appliance firmware. After the installation is complete, remove the installation media and shutdown the machine. Do not go through the first steps wizard before you deploy the image in the cloud.See Installing the virtual appliance by using KVMThe use of Kernel-based virtual machine or KVM is supported. You can use KVM with the provided .iso image so that you can run the virtual appliance. for more detailed instructions.Import the virtual image to the Cloud Orchestrator Virtual Image Library.In the Virtual Image Library, check out the image to an operational repository in the KVM region where you plan to deploy the appliance.Use OpenStack to deploy the virtual image within this KVM region.For example, to deploy the virtual image from the command line, perform these steps on the KVM region server:Set the environment variables for running OpenStack nova.# source ~/openrcVerify that the appliance image is available in the image repository.# nova image-list +--------------------------------------+---------------+--------+--------+ | ID | Name | Status | Server | +--------------------------------------+---------------+--------+--------+ | 9ec1d9ec-2df9-44f6-938c-2533a4d48859 | isam | ACTIVE | | +--------------------------------------+---------------+--------+--------+ Issue the nova boot command to start a new instance of the appliance image.nova boot --image isam --flavor m1.medium isamMonitor the status of the new instance using the nova list command. # nova list +--------------------------------------+--------------------+--------+--------------------+ | ID | Name | Status | Networks | +--------------------------------------+--------------------+--------+--------------------+ | 43f3e09c-a64d-4e11-8827-2d354be3d625 | my-isam-appliance | ACTIVE | public=172.20.96.1 | +--------------------------------------+--------------------+--------+--------------------+The appliance is now started and the local management interface and web services interfaces are listening on the given IP address.After the machine is running in the OpenStack KVM environment, you can import it into Cloud Orchestrator.Log in to the Cloud Orchestrator management web UI.Go to ConfigurationHypervisors.Locate the hypervisor where the appliance is running.Expand the virtual machines section and locate the appliance image.Select ManageImport the Virtual Machine.The appliance virtual machine is now visible in the Cloud Orchestrator UI on the InstancesVirtual Machines page.Installing the virtual appliance by using KVMThe use of Kernel-based virtual machine or KVM is supported. You can use KVM with the provided .iso image so that you can run the virtual appliance.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

Setting up Cloud Orchestrator support

The virtual appliance has basic support for Cloud Orchestrator as imported KVM virtual images. It is possible to run the appliance within a Cloud Orchestrator environment and use it to perform basic virtual image management tasks.

About this task

Consider these limitations before you set up Cloud Orchestrator support:

The virtual appliance does not have full support for the orchestration and pattern building capabilities of Cloud Orchestrator.

The appliance can be run only in KVM regions.

The appliance can be imported and managed in the Virtual Image Library, but cannot be extended with the IBM Image Construction and Composition Tool.

The appliance cannot be used in pattern-based deployments.

The basic operations that are provided by Cloud Orchestrator for the imported appliance image include the ability to stop, start, or delete the virtual machine.

The appliance must be run with a single network interface.

To use the virtual appliance as an imported virtual image within a Cloud environment, use the following high-level procedure. For more information, see the IBM Cloud Orchestrator Knowledge Center.

Procedure

Create a KVM virtual machine image and install the appliance firmware.

Note: After the installation is complete, remove the installation media and shutdown the machine. Do not go through the first steps wizard before you deploy the image in the cloud.

See Installing the virtual appliance by using KVM for more detailed instructions.

Import the virtual image to the Cloud Orchestrator Virtual Image Library.

In the Virtual Image Library, check out the image to an operational repository in the KVM region where you plan to deploy the appliance.

Use OpenStack to deploy the virtual image within this KVM region. For example, to deploy the virtual image from the command line, perform these steps on the KVM region server:

Set the environment variables for running OpenStack nova.

# source ~/openrc

Verify that the appliance image is available in the image repository.

# nova image-list
+--------------------------------------+---------------+--------+--------+
| ID                                   | Name          | Status | Server |
+--------------------------------------+---------------+--------+--------+
| 9ec1d9ec-2df9-44f6-938c-2533a4d48859 | isam          | ACTIVE |        |
+--------------------------------------+---------------+--------+--------+

Issue the nova boot command to start a new instance of the appliance image.

nova boot --image isam --flavor m1.medium isam

Monitor the status of the new instance using the nova list command.

# nova list
+--------------------------------------+--------------------+--------+--------------------+
| ID                                   | Name               | Status | Networks           |
+--------------------------------------+--------------------+--------+--------------------+
| 43f3e09c-a64d-4e11-8827-2d354be3d625 | my-isam-appliance  | ACTIVE | public=172.20.96.1 |
+--------------------------------------+--------------------+--------+--------------------+

The appliance is now started and the local management interface and web services interfaces are listening on the given IP address.

After the machine is running in the OpenStack KVM environment, you can import it into Cloud Orchestrator.

Log in to the Cloud Orchestrator management web UI.

Go to Configuration > Hypervisors.

Locate the hypervisor where the appliance is running.

Expand the virtual machines section and locate the appliance image.

Select Manage > Import the Virtual Machine.

Results

The appliance virtual machine is now visible in the Cloud Orchestrator UI on the Instances > Virtual Machines page.

Parent topic: Virtual appliance tasks

Related tasks:

Installing the virtual appliance by using KVM

USB support on virtual appliancesAdministrators of virtual appliances can use a physical USB drive for tasks such as uploading a new firmware, uploading or downloading a snapshot file, and downloading a support file.To use a USB drive with the virtual appliance, complete these steps:Format the USB drive with the FAT32 file system.Attach the USB drive to the appropriate location.If you use XenServer or KVM as your hypervisor, attach the USB drive to the machine that is running the hypervisor.If you use VMWare vSphere as your hypervisor, attach the USB drive to the machine that is running the vSphere client.Update the virtual machine definition to reference the USB device. The required steps are specific to the hypervisor that you use.Virtual appliance tasksYou must correctly configure the virtual environment before you install the appliance. Connect to the local management interface or the virtual console to configure the initial appliance settings.

USB support on virtual appliances

Administrators of virtual appliances can use a physical USB drive for tasks such as uploading a new firmware, uploading or downloading a snapshot file, and downloading a support file.

To use a USB drive with the virtual appliance, complete these steps:

Format the USB drive with the FAT32 file system.

Attach the USB drive to the appropriate location.

If you use XenServer or KVM as your hypervisor, attach the USB drive to the machine that is running the hypervisor.

If you use VMWare vSphere as your hypervisor, attach the USB drive to the machine that is running the vSphere client.

Update the virtual machine definition to reference the USB device. The required steps are specific to the hypervisor that you use.

Parent topic: Virtual appliance tasks

Common tasksCommon tasksCommon tasks in IBM Security Access Manager ApplianceThese tasks are common for both the hardware appliance and the virtual appliance.hardware appliancescommon tasksvirtual appliancestasksYou can choose either of the following methods to configure initial appliance settings. Command-line interface (CLI)Local management interface (LMI)The LMI method offers more advanced configuration options.Getting StartedComplete the following tasks that apply to your appliance format.Command-line interface initial appliance settings wizardThe initial appliance settings wizard runs the first time that an administrator logs in to the command-line interface (CLI) of an unconfigured appliance.Local management interface Appliance Setup wizardThe Appliance Setup wizard runs the first time that an administrator logs in to the local management interface (LMI) of an unconfigured appliance.Activating the product and buying supportActivate the product after installation so you can use all available features. You can optionally import a support license file to receive updates to the appliance.Silent configurationYou can configure an appliance silently after installation with the web service interfaces by providing a metadata image that contains essential configuration data.

Common tasks

These tasks are common for both the hardware appliance and the virtual appliance.

You can choose either of the following methods to configure initial appliance settings.

Command-line interface (CLI)

Local management interface (LMI)

The LMI method offers more advanced configuration options.

Command-line interface initial appliance settings wizard
The initial appliance settings wizard runs the first time that an administrator logs in to the command-line interface (CLI) of an unconfigured appliance.

Local management interface Appliance Setup wizard
The Appliance Setup wizard runs the first time that an administrator logs in to the local management interface (LMI) of an unconfigured appliance.

Activating the product and buying support
Activate the product after installation so you can use all available features. You can optionally import a support license file to receive updates to the appliance.

Silent configuration
You can configure an appliance silently after installation with the web service interfaces by providing a metadata image that contains essential configuration data.

Parent topic: Getting Started

Command-line interface initial appliance settings wizardCommand-line interface initial appliance settings wizardAccess Manager Appliance: Command-line interface initial appliance settings wizardThe initial appliance settings wizard runs the first time that an administrator logs in to the command-line interface (CLI) of an unconfigured appliance.command-line interfacelicenseagreementsettingsappliancesmanagementportpasswordshostsnamesconfigurationhost namespasswordsNavigationYou can move between screens in the wizard using the following options:p: Previous Screenn: Next ScreenTo cancel the setup process at any time, use the exit command.ModulesYou must configure the following modules to set up your appliance:ModuleDescriptionWelcomeDescribes the appliance settings that you can configure using the wizard.Software License AgreementDescribes the appliance license agreement, IBM terms, and non-IBM terms.FIPS 140-2 Mode ConfigurationEnable this option to turn on compliance for NIST SP800-131a. If you enable this option, the appliance is automatically restarted before it continues on with the rest of the setup.Enable this option only if you must comply with the NIST SP800-131a requirements. There is no advantage to enabling this option if your installation does not require it. To disable NIST SP800-131a compliance, you must reinstall the appliance.Password ConfigurationChanges your password.Host ConfigurationChanges the host name.Management Interface SettingsConfigures the management network interfaces. Displays device settings and the current working-set policy for the primary and secondary interfaces.DNS ConfigurationConfigures the DNS servers that are used by the appliance.Time ConfigurationConfigures the time, date, and time zone on the appliance.Common tasksThese tasks are common for both the hardware appliance and the virtual appliance.

Command-line interface initial appliance settings wizard

The initial appliance settings wizard runs the first time that an administrator logs in to the command-line interface (CLI) of an unconfigured appliance.

Navigation

You can move between screens in the wizard using the following options:

p: Previous Screen

n: Next Screen

To cancel the setup process at any time, use the exit command.

Modules

You must configure the following modules to set up your appliance:

Module
Description

Welcome
Describes the appliance settings that you can configure using the wizard.

Software License Agreement
Describes the appliance license agreement, IBM® terms, and non-IBM terms.

FIPS 140-2 Mode Configuration
Enable this option to turn on compliance for NIST SP800-131a. If you enable this option, the appliance is automatically restarted before it continues on with the rest of the setup.

Note: Enable this option only if you must comply with the NIST SP800-131a requirements. There is no advantage to enabling this option if your installation does not require it. To disable NIST SP800-131a compliance, you must reinstall the appliance.

Password Configuration
Changes your password.

Host Configuration
Changes the host name.

Management Interface Settings
Configures the management network interfaces. Displays device settings and the current working-set policy for the primary and secondary interfaces.

DNS Configuration
Configures the DNS servers that are used by the appliance.

Time Configuration
Configures the time, date, and time zone on the appliance.

Parent topic: Common tasks

Local management interface Appliance Setup wizardIBM Security Access Manager Appliance setup wizard by using the local management interfaceAppliance Setup wizard by using the local management interfaceThe Appliance Setup wizard runs the first time that an administrator logs in to the local management interface (LMI) of an unconfigured appliance.appliancessetup wizardsetupLMIappliance setup wizardAfter you log in to the LMI for the first time, follow the Appliance Setup wizard to complete the initial configuration of the appliance. The tasks that you must complete for the initial configuration include:Read and accept the License Agreement. Download and install the license file. You must install the license to download the firmware for the hardware appliance updates.Depending on your requirements, choose whether to enable the FIPS option to turn on compliance for NIST SP800-131a. If you enable this option, the appliance is automatically restarted before it continues on with the rest of the setup.Enable this option only if you must comply with the NIST SP800-131a requirements. There is no advantage to enabling this option if your installation does not require it. To disable NIST SP800-131a compliance, you must reinstall the appliance.Set the appliance password. Configure the networking, which includes the host name, management interface settings, and DNS configuration.Configure the application interface settings.Configure the date and time settings.When you complete the basic configuration, a summary screen displays. Review the details on the completion page and click Complete Setup.Common tasksThese tasks are common for both the hardware appliance and the virtual appliance.

Local management interface Appliance Setup wizard

The Appliance Setup wizard runs the first time that an administrator logs in to the local management interface (LMI) of an unconfigured appliance.

After you log in to the LMI for the first time, follow the Appliance Setup wizard to complete the initial configuration of the appliance. The tasks that you must complete for the initial configuration include:

Read and accept the License Agreement.

Download and install the license file. You must install the license to download the firmware for the hardware appliance updates.

Depending on your requirements, choose whether to enable the FIPS option to turn on compliance for NIST SP800-131a. If you enable this option, the appliance is automatically restarted before it continues on with the rest of the setup.

Note: Enable this option only if you must comply with the NIST SP800-131a requirements. There is no advantage to enabling this option if your installation does not require it. To disable NIST SP800-131a compliance, you must reinstall the appliance.

Set the appliance password.

Configure the networking, which includes the host name, management interface settings, and DNS configuration.

Configure the application interface settings.

Configure the date and time settings.

When you complete the basic configuration, a summary screen displays. Review the details on the completion page and click Complete Setup.

Parent topic: Common tasks

Activating the product and buying supportActivating the product and buying supportActivating the product and buying supportActivate the product after installation so you can use all available features. You can optionally import a support license file to receive updates to the appliance.activationproduct activationlicensesupportsupportlicenseObtain your activation key and support license:Download your activation key from your account on Passport Advantage at https://www-112.ibm.com/software/howtobuy/softwareandservices.Obtain your support license by following the instructions in the Welcome email that was sent by IBM.If you cannot locate your Welcome email, go to the IBM Security Systems License Key Center at https://ibmss.flexnetoperations.com. Review the FAQs to find out how to obtain support.You can complete the following actions from the Support License and Product Activation panel:Import the activation key, which is required.Import the support license, which is optional. Import the license if you want to install service release updates. The activation key is a permanent activation for the product. Activation keys have no expiration date. Entitlement for X-Force updates for the database is provided automatically with the product. A third-party geolocation database is provided with sample data. You must purchase separately the full set of geolocation data. You can review activation and support license information for your installed product packages, including specific product activations, service agreements, and expiration dates from this panel.Log in to the local management interface.Click Manage System SettingsUpdates and LicensingLicensing and Activation.Perform one or more of the following actions:Import the activation key and deploy the changes:In the Licensing and Activation window, click Import under Activated products.Browse to the activation key file that you downloaded from Passport Advantage.Select the activation file.Click Open.Click Save Configuration.Deploy the changes: You do not need to deploy changes immediately after you install the activation key. However, you must deploy changes before you can take a snapshot of the product.In the undeployed change message, click Click here to review the changes or apply them to the system.Click Deploy.The activated product name and version are displayed in the Products table. To view the software license agreement, click: View Service Agreement.Optional: Import the product support license so that you can update the appliance:In the Licensing and Activation window, under Support license, click Select License.Browse to the support license file that you downloaded from IBM Security Systems License Key Center.Select the license file.Click Save Configuration.The menu in the local management interface refreshes to show the menu for the activated product. If you imported a Support license, you can update the product with service releases. See Installing updatesInstall firmware and intrusion prevention updates to improve the appliance and the network protection that is provided by the appliance..Ensure that the activation is completed before attempting any other activities using the local management interface. Common tasksThese tasks are common for both the hardware appliance and the virtual appliance.

Activating the product and buying support

Activate the product after installation so you can use all available features. You can optionally import a support license file to receive updates to the appliance.

Before you begin

Obtain your activation key and support license:

Download your activation key from your account on Passport Advantage at https://www-112.ibm.com/software/howtobuy/softwareandservices.

Obtain your support license by following the instructions in the Welcome email that was sent by IBM.

Note: If you cannot locate your Welcome email, go to the IBM Security Systems License Key Center at https://ibmss.flexnetoperations.com. Review the FAQs to find out how to obtain support.

About this task

You can complete the following actions from the Support License and Product Activation panel:

Import the activation key, which is required.

Import the support license, which is optional. Import the license if you want to install service release updates.

The activation key is a permanent activation for the product. Activation keys have no expiration date.

Entitlement for X-Force updates for the database is provided automatically with the product. A third-party geolocation database is provided with sample data. You must purchase separately the full set of geolocation data.

You can review activation and support license information for your installed product packages, including specific product activations, service agreements, and expiration dates from this panel.

Procedure

Log in to the local management interface.

Click Manage System Settings > Updates and Licensing > Licensing and Activation.

Perform one or more of the following actions:

Import the activation key and deploy the changes:

In the Licensing and Activation window, click Import under Activated products.

Browse to the activation key file that you downloaded from Passport Advantage.

Select the activation file.

Click Open.

Click Save Configuration.

Deploy the changes:

Note: You do not need to deploy changes immediately after you install the activation key. However, you must deploy changes before you can take a snapshot of the product.

In the undeployed change message, click Click here to review the changes or apply them to the system.

Click Deploy.

The activated product name and version are displayed in the Products table. To view the software license agreement, click: View Service Agreement.

Optional: Import the product support license so that you can update the appliance:

In the Licensing and Activation window, under Support license, click Select License.

Browse to the support license file that you downloaded from IBM Security Systems License Key Center.

Select the license file.

Click Save Configuration.

Results

The menu in the local management interface refreshes to show the menu for the activated product.

If you imported a Support license, you can update the product with service releases. See Installing updates.

Attention: Ensure that the activation is completed before attempting any other activities using the local management interface.

Parent topic: Common tasks

Silent configurationYou can configure an appliance silently after installation with the web service interfaces by providing a metadata image that contains essential configuration data.After the appliance firmware has been installed, shut down the machine. The ISO image that contains the configuration meta-data can then be attached to the appliance in preparation for the initial boot of the installed firmware. Once the appliance has successfully booted, it will mount the ISO image and then use the configuration meta-data to automatically configure the network.The metadata image can be created with the local management interface or manually with a text editor. If you use a manually created metadata image for the initial configuration of an appliance, the appliance boots up with the configured network settings automatically, but the first-steps wizard must be completed manually. You can use the local management interface or the web service interfaces to perform the first-steps configuration. To silently configure the appliance without the need to complete the first-steps wizard manually, you must use a metadata image that contains the system policy. Such metadata images can be created only through the local management interface. See the isam_config_sample.py script available from the File Downloads page of the local management interface as an example for silent configuration with scripts.Common tasksThese tasks are common for both the hardware appliance and the virtual appliance.Creating a metadata image with the local management interfaceYou can create a metadata image that contains essential configuration data for the initial setup of an appliance with the local management interface. This image can later be used for the silent configuration of a new virtual appliance.Creating a metadata image manuallyYou can create a metadata image that contains the initial network configuration for interface 1.1 manually with a text editor.

Silent configuration

You can configure an appliance silently after installation with the web service interfaces by providing a metadata image that contains essential configuration data.

After the appliance firmware has been installed, shut down the machine. The ISO image that contains the configuration meta-data can then be attached to the appliance in preparation for the initial boot of the installed firmware. Once the appliance has successfully booted, it will mount the ISO image and then use the configuration meta-data to automatically configure the network.

The metadata image can be created with the local management interface or manually with a text editor.

If you use a manually created metadata image for the initial configuration of an appliance, the appliance boots up with the configured network settings automatically, but the first-steps wizard must be completed manually. You can use the local management interface or the web service interfaces to perform the first-steps configuration. To silently configure the appliance without the need to complete the first-steps wizard manually, you must use a metadata image that contains the system policy. Such metadata images can be created only through the local management interface.

See the isam_config_sample.py script available from the File Downloads page of the local management interface as an example for silent configuration with scripts.

Creating a metadata image with the local management interface
You can create a metadata image that contains essential configuration data for the initial setup of an appliance with the local management interface. This image can later be used for the silent configuration of a new virtual appliance.

Creating a metadata image manually
You can create a metadata image that contains the initial network configuration for interface 1.1 manually with a text editor.

Parent topic: Common tasks

Creating a metadata image with the local management interfaceYou can create a metadata image that contains essential configuration data for the initial setup of an appliance with the local management interface. This image can later be used for the silent configuration of a new virtual appliance.A metadata image that is created with the local management interface provides more information than a manually created metadata image does. For example, you can choose to include the system policy when you create the image through the local management interface. If the system policy is included in the image, it is possible to accept the license agreement silently and complete the first-steps wizard automatically on first boot.From the top menu, select Manage System SettingsSecure SettingsSilent Configuration.Enter the hostname to be configured on the new appliance.Select the IPv4, IPv6, or both check boxes to specify static IP addresses.If the IPv4 check box is selected, complete the IPv4 section.If the IPv6 check box is selected, complete the IPv6 section.To include the system policy, select the Include system policy check box. The system policy excludes the following configuration:Management interfacesApplication interfacesCluster configurationAdvanced Access Control runtime configurationBesides the previously mentioned policy exclusions, there are also a few non-policy exclusions. The support license, Security Access Manager runtime environment, reverse proxy instances, authorization server instances, local LDAP server, policy databases, custom pages, and other files that are uploaded to the appliance are not included in the system policy.If the system policy is included, when the silent configuration takes place on a new appliance, the license agreement is automatically accepted and the first-steps wizard is automatically completed.At the bottom of the page, click Generate CDROM Image or Generate USB Image to download an image that contains this metadata.To use the USB image, write the IMG file to a partition on a USB device by using the dd tool.To use the CD-ROM image, attach the ISO file to a CD-ROM device on your virtual appliance.Silent configurationYou can configure an appliance silently after installation with the web service interfaces by providing a metadata image that contains essential configuration data.

Creating a metadata image with the local management interface

You can create a metadata image that contains essential configuration data for the initial setup of an appliance with the local management interface. This image can later be used for the silent configuration of a new virtual appliance.

About this task

A metadata image that is created with the local management interface provides more information than a manually created metadata image does. For example, you can choose to include the system policy when you create the image through the local management interface. If the system policy is included in the image, it is possible to accept the license agreement silently and complete the first-steps wizard automatically on first boot.

Procedure

From the top menu, select Manage System Settings > Secure Settings > Silent Configuration.

Enter the hostname to be configured on the new appliance.

Select the IPv4, IPv6, or both check boxes to specify static IP addresses.

If the IPv4 check box is selected, complete the IPv4 section.

If the IPv6 check box is selected, complete the IPv6 section.

To include the system policy, select the Include system policy check box.

Note:

The system policy excludes the following configuration:

Management interfaces

Application interfaces

Cluster configuration

Advanced Access Control runtime configuration

Besides the previously mentioned policy exclusions, there are also a few non-policy exclusions. The support license, Security Access Manager runtime environment, reverse proxy instances, authorization server instances, local LDAP server, policy databases, custom pages, and other files that are uploaded to the appliance are not included in the system policy.

If the system policy is included, when the silent configuration takes place on a new appliance, the license agreement is automatically accepted and the first-steps wizard is automatically completed.

At the bottom of the page, click Generate CDROM Image or Generate USB Image to download an image that contains this metadata.

To use the USB image, write the IMG file to a partition on a USB device by using the dd tool.

To use the CD-ROM image, attach the ISO file to a CD-ROM device on your virtual appliance.

Parent topic: Silent configuration

Creating a metadata image manuallyYou can create a metadata image that contains the initial network configuration for interface 1.1 manually with a text editor.The metadata file is a plain text file that contains a list of key-value pairs. The file must be named app-metadata and at the root of the file system of the ISO image to be mounted.Create a text file with the name app-metadata at the root of the file system of the attached device.Edit the content of the text file as needed.The valid keys are as follows:Valid keysKeyDescriptionnetwork.hostnameThe appliance hostnamenetwork.1.1.ipv4.addressThe initial IPv4 management IP address on interface 1.1 network.1.1.ipv4.netmaskThe netmask for interface 1.1network.1.1.ipv4.gatewayThe gateway for interface 1.1network.1.1.ipv6.addressThe initial IPv6 management IP address on interface 1.1 network.1.1.ipv6.prefixThe prefix length for interface 1.1network.1.1.ipv6.gatewayThe gateway for interface 1.1You can include both ipv4 and ipv6 settings in the same file. If you include ipv4 or ipv6 settings, all associated keys (address, netmask, and gateway) must be present.The following example initially configures an IPv4 address for interface 1.1 and the appliance hostname.network.hostname = isam-appliance.ibm.com network.1.1.ipv4.address = 10.20.0.11 network.1.1.ipv4.netmask = 255.255.0.0 network.1.1.ipv4.gateway = 10.20.0.1Creating a metadata image with the local management interfaceYou can create a metadata image that contains essential configuration data for the initial setup of an appliance with the local management interface. This image can later be used for the silent configuration of a new virtual appliance.Silent configurationYou can configure an appliance silently after installation with the web service interfaces by providing a metadata image that contains essential configuration data.

Creating a metadata image manually

You can create a metadata image that contains the initial network configuration for interface 1.1 manually with a text editor.

About this task

The metadata file is a plain text file that contains a list of key-value pairs. The file must be named app-metadata and at the root of the file system of the ISO image to be mounted.

Procedure

Create a text file with the name app-metadata at the root of the file system of the attached device.

Edit the content of the text file as needed. The valid keys are as follows:

Table 145. Valid keys

Key | Description
network.hostname | The appliance hostname
network.1.1.ipv4.address | The initial IPv4 management IP address on interface 1.1
network.1.1.ipv4.netmask | The netmask for interface 1.1
network.1.1.ipv4.gateway | The gateway for interface 1.1
network.1.1.ipv6.address | The initial IPv6 management IP address on interface 1.1
network.1.1.ipv6.prefix | The prefix length for interface 1.1
network.1.1.ipv6.gateway | The gateway for interface 1.1

You can include both ipv4 and ipv6 settings in the same file. If you include ipv4 or ipv6 settings, all associated keys (address, netmask, and gateway) must be present.

The following example initially configures an IPv4 address for interface 1.1 and the appliance hostname.

network.hostname = isam-appliance.ibm.com
network.1.1.ipv4.address = 10.20.0.11
network.1.1.ipv4.netmask = 255.255.0.0
network.1.1.ipv4.gateway = 10.20.0.1

Parent topic: Silent configuration

Related tasks:

Creating a metadata image with the local management interface

Initial configurationInitial configurationInitial configurationSeveral initial configuration tasks are required for your IBM Security Access Manager environment.configurationinitialAfter you complete the Getting startedComplete the following tasks that apply to your appliance format. tasks, including activating the productActivate the product after installation so you can use all available features. You can optionally import a support license file to receive updates to the appliance., continue with these steps: Manage application interfaces. Create or edit your management and application interfaces.Configure your environment based on your needs:Stand-alone Web Reverse Proxy Configure the runtime environment.To configure the runtime environment with the local management interface, use the Runtime Component management page.Configure Web Reverse Proxy instancesTo configure an instance with the local management interface, use the Reverse Proxy management page.. Member of a cluster of appliances Primary master in a cluster: Manage cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance. and specify an appliance to be the primary master. Configure the runtime environment.To configure the runtime environment with the local management interface, use the Runtime Component management page.Configure Web Reverse Proxy instancesTo configure an instance with the local management interface, use the Reverse Proxy management page.. Member of a cluster: Manage cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance. and join the current appliance to the cluster.Configure Web Reverse Proxy instancesTo configure an instance with the local management interface, use the Reverse Proxy management page.. Front-end load balancer: Configure the front-end load balancer. To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page. Set up communication between appliancesComplete the following task if you have one appliance with Advanced Access Control activated and one without it: Adding runtime listening interfacesAdd your application interfaces to the list of runtime listening interfaces. This procedure enables communication between an appliance with Advanced Access Control and another Security Access Manager appliance..Configure the Administrative User Registry:If you want to enforce password policies for the administrative users, configure an external user registry that implements the desired password policies as the administrative user registry. See Configuring management authentication To configure management authentication with the local management interface, use the Management Authentication management page..Proceed with additional configuration tasks as your environment requires. Do not connect the IBM Security Access Manager appliance to public telecommunications network interfaces. Further certification might be required by law before you make any such connections. Do not use the appliance in Public Services Networks. Contact IBM at IBM Customer Support for more information.Appliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.

Initial configuration

Several initial configuration tasks are required for your IBM Security Access Manager environment.

After you complete the Getting started tasks, including activating the product, continue with these steps:

Manage application interfaces.

Configure your environment based on your needs:

Stand-alone Web Reverse Proxy

Configure the runtime environment.

Configure Web Reverse Proxy instances.

Member of a cluster of appliances

Primary master in a cluster:

Manage cluster configuration and specify an appliance to be the primary master.

Configure the runtime environment.

Configure Web Reverse Proxy instances.

Member of a cluster:

Manage cluster configuration and join the current appliance to the cluster.

Configure Web Reverse Proxy instances.

Front-end load balancer:

Configure the front-end load balancer.

Set up communication between appliances

Complete the following task if you have one appliance with Advanced Access Control activated and one without it: Adding runtime listening interfaces.

Configure the Administrative User Registry:

If you want to enforce password policies for the administrative users, configure an external user registry that implements the desired password policies as the administrative user registry. See Configuring management authentication.

Proceed with additional configuration tasks as your environment requires.

Note: Do not connect the IBM Security Access Manager appliance to public telecommunications network interfaces. Further certification might be required by law before you make any such connections. Do not use the appliance in Public Services Networks. Contact IBM at IBM Customer Support for more information.

Parent topic: Appliance administration

Managing the applianceManaging the applianceManaging the IBM Security Access Manager ApplianceThe appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.appliancesmanagementcommand-line interfaceAppliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Local management interfaceThe appliance offers a browser-based graphical user interface for local, single appliance management. Command-line interfaceAccess the command-line interface (CLI) of the appliance by using either an ssh session or the console.Web serviceThe appliance can also be managed by sending RESTful web service requests to the appliance. Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance.

Managing the appliance

The appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.

Local management interface
The appliance offers a browser-based graphical user interface for local, single appliance management.

Command-line interface
Access the command-line interface (CLI) of the appliance by using either an ssh session or the console.

Web service
The appliance can also be managed by sending RESTful web service requests to the appliance.

Configuration changes commit process
The LMI uses a two-stage commit process when you make changes to the appliance.

Parent topic: Appliance administration

Local management interfaceLocal management interfaceAccess Manager Appliance: local management interfaceThe appliance offers a browser-based graphical user interface for local, single appliance management. local management interfaceLMILMIlogging onsupported browsersappliancesmanagementThe following paragraphs are general notes about the usage of the local management interface (LMI). Examples of specific commands using the LMI are provided through the remainder of this document.To log in to the LMI, type the IP address or host name of your appliance into your web browser. The following web browsers are supported:WindowsGoogle Chrome, version 27 or laterMicrosoft Internet Explorer, version 9, 10, or 11Mozilla Firefox, version 17 or laterLinux/AIX/SolarisMozilla Firefox, version 17 or laterUse the default credentials to log in to the local management interface for the first time:User Name: adminPassword: adminAfter you log in for the first time, use the first-time configuration pages to change your password.To log out of the local management interface, click Logout.Only one user can remain logged in to the appliance at the same time. An error occurs if you try to log in when there is an existing user session. You must displace the existing user session before you can log in with your own user session.When you close the browser window after having accessed the LMI, a session will remain active on the system. You must select the Displace any existing sessions check box when you log in to the LMI next time.Managing the applianceThe appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.

Local management interface

The appliance offers a browser-based graphical user interface for local, single appliance management.

The following paragraphs are general notes about the usage of the local management interface (LMI). Examples of specific commands using the LMI are provided through the remainder of this document.

To log in to the LMI, type the IP address or host name of your appliance into your web browser. The following web browsers are supported:

Windows

Google Chrome, version 27 or later

Microsoft Internet Explorer, version 9, 10, or 11

Mozilla Firefox, version 17 or later

Linux/AIX®/Solaris

Mozilla Firefox, version 17 or later

Use the default credentials to log in to the local management interface for the first time:

User Name: admin

Password: admin

After you log in for the first time, use the first-time configuration pages to change your password.

To log out of the local management interface, click Logout.

Only one user can remain logged in to the appliance at the same time. An error occurs if you try to log in when there is an existing user session. You must displace the existing user session before you can log in with your own user session.

Note: When you close the browser window after having accessed the LMI, a session will remain active on the system. You must select the Displace any existing sessions check box when you log in to the LMI next time.

Parent topic: Managing the appliance

Command-line interfaceCommand-line interfaceIBM Security Access Manager Appliance CLI accessAccess the command-line interface (CLI) of the appliance by using either an ssh session or the console.appliancesCLIcommand-line interfaceThe following example shows the transcript of using an ssh session to access the appliance:usernameA@example.ibm.com>ssh -l admin webapp.vwasp.gc.au.ibm.com admin@webapp.vmasp.gc.au.ibm.com's password: Welcome to the IBM Security Access Manager Appliance Enter "help" for a list of available commands webapp.vwasp.gc.au.ibm.com>isam webapp.vwasp.gc.au.ibm.com:isam> help Current mode commands: admin Start an administration session which can be used to administer the ISAM security policy. auto_config Work with the auto-configuration options. dscadmin Start an administration session which can be used to administer the Distributed Session Cache. logs Work with the ISAM log files. Global commands: back Return to the previous command mode. exit Log off from the appliance. help Display information for using the specified command. reboot Reboot the appliance. shutdown End system operation and turn off the power. top Return to the top level.Use the help command to display usage notes about a specific command.The following example shows the options available under the lmiaccountslocked menu.webapp.vwasp.gc.au.ibm.com:locked> help Current mode commands: list List all of the locked accounts and the amount of time before each of the accounts will be automatically unlocked. unlock_all Unlock all of the locked accounts. unlock <account> Unlock a specific account.The following example shows the options available under the logs menu.webapp.vwasp.gc.au.ibm.com:logs> help Current mode commands: archive Archive the log files to a USB device. delete Delete the log files which have been rolled over by the system. delete_trace Delete the trace files (trace, stats, translog) from the system. monitor Monitor log files on the system.The following example shows the options available under the auto_config menu.webapp.vwasp.gc.au.ibm.com:auto_config> help Current mode commands: config Start a session which can be used to configure a Web Reverse Proxy instance so that it can act as a point of contact for Advanced Access Control. unconfig Start a session which can be used to unconfigure a Web Reverse Proxy instance so that it can no longer act as a point of contact for Advanced Access Control.The following example shows the options available under the tools menu:webapp.vwasp.gc.au.ibm.com:tools> help Current mode commands: connect Test network connection to a certain port on a specified host. connections Display the network connections for the appliance. nslookup Query internet domain name servers. ping Send an ICMP ECHO_REQUEST to network hosts. traceroute Trace a packet from a computer to a remote destination, showing how many hops the packet required to reach the destination and how long each hop took. session Test network sessions with TCP or SSL.The following example shows the options available under the support menu:webapp.vwasp.gc.au.ibm.com:support> help Current mode commands: create Create a support information file. delete Delete a support information file. download Download a support information file to a USB flash drive. get_comment View the comment associated with a support information file. list List the support information files. purge Purge the support files from the hard drive. set_comment Replace the comment associated with a support information file.The purge command deletes all core files, crashmap files, and support files from the /var/support/ directory. The method to access the console differs between the hardware appliance and the virtual appliance: For the hardware appliance, a serial console device must be used. For more information about attaching a serial console device to the hardware, see Connecting a serial console to the applianceYou must connect a serial console to the hardware appliance before you can proceed with the configuration tasks through the command-line interface (CLI)..For the virtual appliance, you can access the console by using the appropriate VMWare software.For example, VMWare vSphere Client.The CLI contains only a subset of the functions available from the local management interface. The following list gives a high-level overview of the functions available from the command-line interface. To see a list of the options for these commands, type the command name followed by -help.firmwareWork with firmware images.fixpacksWork with fix packs.hardwareWork with the baseboard management controller (BMC) module. This command is not available on the virtual appliance.licenseWork with licenses.lmiWork with the local management interface.managementWork with management settings.snapshotsWork with policy snapshot files.supportWork with support information files.toolsWork with network diagnostic tools.updatesWork with firmware and security updates.Managing the applianceThe appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.

Command-line interface

Access the command-line interface (CLI) of the appliance by using either an ssh session or the console.

The following example shows the transcript of using an ssh session to access the appliance:

usernameA@example.ibm.com>ssh -l admin webapp.vwasp.gc.au.ibm.com
admin@webapp.vmasp.gc.au.ibm.com's password:
Welcome to the IBM Security Access Manager Appliance
Enter "help" for a list of available commands
webapp.vwasp.gc.au.ibm.com>isam
webapp.vwasp.gc.au.ibm.com:isam> help
Current mode commands:
admin           Start an administration session which can be used to administer
                the ISAM security policy.
auto_config     Work with the auto-configuration options.
dscadmin        Start an administration session which can be used to administer
                the Distributed Session Cache.
logs            Work with the ISAM log files.

Global commands:
back            Return to the previous command mode.
exit            Log off from the appliance.
help            Display information for using the specified command.
reboot          Reboot the appliance.
shutdown        End system operation and turn off the power.
top             Return to the top level.

Tip: Use the help command to display usage notes about a specific command.

The following example shows the options available under the lmi > accounts > locked menu.

webapp.vwasp.gc.au.ibm.com:locked> help
Current mode commands:
list             List all of the locked accounts and the amount of time before each
                 of the accounts will be automatically unlocked.
unlock_all       Unlock all of the locked accounts.
unlock <account> Unlock a specific account.

The following example shows the options available under the logs menu.

webapp.vwasp.gc.au.ibm.com:logs> help
Current mode commands:
archive         Archive the log files to a USB device.
delete          Delete the log files which have been rolled over by the system.
delete_trace    Delete the trace files (trace, stats, translog) from the system.
monitor         Monitor log files on the system.

The following example shows the options available under the auto_config menu.

webapp.vwasp.gc.au.ibm.com:auto_config> help
Current mode commands:
config          Start a session which can be used to configure a Web Reverse
                Proxy instance so that it can act as a point of contact for
                Advanced Access Control.
unconfig        Start a session which can be used to unconfigure a Web Reverse
                Proxy instance so that it can no longer act as a point of
                contact for Advanced Access Control.

The following example shows the options available under the tools menu:

webapp.vwasp.gc.au.ibm.com:tools> help
Current mode commands:
connect         Test network connection to a certain port on a specified host.
connections     Display the network connections for the appliance.
nslookup        Query internet domain name servers.
ping            Send an ICMP ECHO_REQUEST to network hosts.
traceroute      Trace a packet from a computer to a remote destination, showing
                how many hops the packet required to reach the destination and
                how long each hop took.
session         Test network sessions with TCP or SSL.

The following example shows the options available under the support menu:

webapp.vwasp.gc.au.ibm.com:support> help
Current mode commands:
create          Create a support information file.
delete          Delete a support information file.
download        Download a support information file to a USB flash drive.
get_comment     View the comment associated with a support information file.
list            List the support information files.
purge           Purge the support files from the hard drive.
set_comment     Replace the comment associated with a support information file.

Note: The purge command deletes all core files, crashmap files, and support files from the /var/support/ directory.

The method to access the console differs between the hardware appliance and the virtual appliance:

For the hardware appliance, a serial console device must be used. For more information about attaching a serial console device to the hardware, see Connecting a serial console to the appliance.

For the virtual appliance, you can access the console by using the appropriate VMWare software.

For example, VMWare vSphere Client.

Note: The CLI contains only a subset of the functions available from the local management interface. The following list gives a high-level overview of the functions available from the command-line interface. To see a list of the options for these commands, type the command name followed by -help.

firmware

Work with firmware images.

fixpacks

Work with fix packs.

hardware

Work with the baseboard management controller (BMC) module. This command is not available on the virtual appliance.

license

Work with licenses.

lmi

Work with the local management interface.

management

Work with management settings.

snapshots

Work with policy snapshot files.

support

Work with support information files.

tools

Work with network diagnostic tools.

updates

Work with firmware and security updates.

Parent topic: Managing the appliance

Web serviceWeb serviceIBM Security Access Manager Appliance Web serviceThe appliance can also be managed by sending RESTful web service requests to the appliance. RESTful web servicesappliancesmanagementRESTful web servicesOnly one user can remain logged in to the appliance at the same time. Each web service request automatically displaces any existing sessions.The following paragraphs are general notes about the usage of the web service interface. The content and format of these web service requests are explained through the remainder of this document.Managing the applianceThe appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.Required header for calling a web serviceAll web service requests must include these two headers.Web service responsesThe response to a web service call is composed of two components: HTTP response code and JSON message.

Web service

The appliance can also be managed by sending RESTful web service requests to the appliance.

Only one user can remain logged in to the appliance at the same time. Each web service request automatically displaces any existing sessions.

The following paragraphs are general notes about the usage of the web service interface. The content and format of these web service requests are explained through the remainder of this document.

Required header for calling a web service
All web service requests must include these two headers.

Web service responses
The response to a web service call is composed of two components: HTTP response code and JSON message.

Parent topic: Managing the appliance

Required header for calling a web serviceRequired header for calling a web serviceRequired header for calling a web service in IBM Security Access Manager ApplianceAll web service requests must include these two headers.web servicesrequired headersheadersAccept:application/jsonThe accept header must be present and the value must be set to application/json. If the header is missing, or set as a different value, the web service request fails.BA headerEach request must contain a BA header with a valid user name and password. If this header is missing, the request fails.The following example is the valid request format for retrieving the list of reverse proxy instances by using curl.curl -k -H "Accept:application/json" --user username:password https://{appliance_hostname}/reverseproxyThe previous list contains only two headers that are mandatory for all web service requests. It is not an extensive list of headers that are required for all request actions. The previous example shows a curl GET request on a resource URI. This request requires only the two mandatory headers that are listed. Other HTTP methods, such as POST or PUT, require more headers. The following example is a valid request for starting a reverse proxy instance called inst1 using curl:curl -k -H "Accept:application/json" -H "Content-type:application/json" --user username:password --data-binary '{ 'operation':'start' }' -X PUT https://{appliance_hostname}/reverseproxy/inst1Notice the additional required header Content-type for the PUT operation.Other HTTP clients, such as Java, might require more headers. For required headers for RESTful web services, check the HTTP client documentation.Web serviceThe appliance can also be managed by sending RESTful web service requests to the appliance.

Required header for calling a web service

All web service requests must include these two headers.

Accept:application/json

The accept header must be present and the value must be set to application/json. If the header is missing, or set as a different value, the web service request fails.

BA header

Each request must contain a BA header with a valid user name and password. If this header is missing, the request fails.

The following example is the valid request format for retrieving the list of reverse proxy instances by using curl.

curl -k -H "Accept:application/json" --user username:password
https://{appliance_hostname}/reverseproxy

Note: The previous list contains only two headers that are mandatory for all web service requests. It is not an extensive list of headers that are required for all request actions. The previous example shows a curl GET request on a resource URI. This request requires only the two mandatory headers that are listed. Other HTTP methods, such as POST or PUT, require more headers. The following example is a valid request for starting a reverse proxy instance called inst1 using curl:

curl -k -H "Accept:application/json" -H "Content-type:application/json"
--user username:password --data-binary '{ 'operation':'start' }'
-X PUT https://{appliance_hostname}/reverseproxy/inst1

Notice the additional required header Content-type for the PUT operation.

Other HTTP clients, such as Java, might require more headers. For required headers for RESTful web services, check the HTTP client documentation.

Parent topic: Web service

Web service responsesWeb service error responsesWeb service responsesThe response to a web service call is composed of two components: HTTP response code and JSON message.web serviceserror responsesThe response to a successful web service request includes a 200 status code, and JSON data that contains context-specific information about the request processing. The response to an unsuccessful web service request includes an HTTP error response code, and JSON data that contains the error message. HTTP response codesHTTP error response codesCodeDescription200Success.400There is a problem with the request. The JSON message describes the problem.404The resource that is specified in the request does not exist. The JSON message indicates which resource.500An internal error was encountered while the request is processed. The JSON message indicates the problem.JSON error response format{"message":"The error message"}Web serviceThe appliance can also be managed by sending RESTful web service requests to the appliance.

Web service responses

The response to a web service call is composed of two components: HTTP response code and JSON message.

The response to a successful web service request includes a 200 status code, and JSON data that contains context-specific information about the request processing. The response to an unsuccessful web service request includes an HTTP error response code, and JSON data that contains the error message.

HTTP response codes

Table 146. HTTP error response codes

Code | Description
200 | Success.
400 | There is a problem with the request. The JSON message describes the problem.
404 | The resource that is specified in the request does not exist. The JSON message indicates which resource.
500 | An internal error was encountered while the request is processed. The JSON message indicates the problem.

JSON error response format

{"message":"The error message"}

Parent topic: Web service

Configuration changes commit processConfiguration changes commit processAccess Manager Appliance: Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. commit processconfigurationchangesLMIcommit processlocal management interfaceLMIappliancesupdatingchange commit processchangesconfigurationserviceswebwebservicesStage 1Changes are made by using the LMI and saved to a staging area.Stage 2The user explicitly deploys the changes into production.Multiple changes can exist in a pending state at the same time. They are committed or rolled back together when a user deploys or rolls back these changes.Any changes that affect running reverse proxy instances require a restart of the effected instances before the changes can take effect.Certain appliance updates require either the appliance or the web server to be restarted before the changes can take effect. When one or more of these updates are made alongside other reverse proxy updates, an additional step is required to deploy the reverse proxy updates. You must:Deploy all updates.Restart the appliance or the web server. Deploy all remaining updates.If there are conflicts between the pending changes and the production files, then all pending changes are automatically rolled back and the production files remain unchanged.Web serviceDeploy the pending configuration changesURLhttps://{appliance_hostname}/pending_changes/deployMethodGETParametersN/AResponse HTTP response code and JSON error response where applicable.ExampleRequest:GET https://{appliance_hostname}/pending_changes/deployResponse:200 okRoll back the pending configuration changesURLhttps://{appliance_hostname}/pending_changes/forgetMethodGETParametersN/AResponse HTTP response code and JSON error response where applicable.ExampleRequest:GET https://{appliance_hostname}/pending_changes/forgetResponse:200 okRetrieve the number of outstanding changesURLhttps://{appliance_hostname}/pending_changes/countMethodGETParametersN/AResponse HTTP response code and JSON data that represents the number of pending changes.ExampleRequest:GET https://{appliance_hostname}/pending_changes/countResponse:{"count": 3}Retrieve the list of outstanding changesURLhttps://{appliance_hostname}/pending_changesMethodGETParametersN/AResponse HTTP response code and JSON data that represents the list of pending changes.ExampleRequest:GET https://{appliance_hostname}/pending_changesResponse:200 ok [{ "id": 0, "policy": "SSL Certificates", "user": "admin", "date": "2012-11-05T11:22:20+10:00" }]Local management interfaceWhen there are pending changes, a warning message is displayed at the top of the main pane. To deploy or roll back the pending changes:Click the Click here to review the changes or apply them to the system link within the warning message.In the Deploy Pending Changes page:To view the details of changes that are made to a particular module, click the link to that module.To deploy the changes, click Deploy.To abandon the changes, click Roll Back.To close the pop-up page without any actions against the changes, click Cancel.Managing the applianceThe appliance provides three mechanisms by which it can be managed: the local management interface (LMI), the command-line interface (CLI), and web services interface.Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.

Configuration changes commit process

The LMI uses a two-stage commit process when you make changes to the appliance.

Stage 1

Changes are made by using the LMI and saved to a staging area.

Stage 2

The user explicitly deploys the changes into production.

Multiple changes can exist in a pending state at the same time. They are committed or rolled back together when a user deploys or rolls back these changes.

Any changes that affect running reverse proxy instances require a restart of the effected instances before the changes can take effect.

Certain appliance updates require either the appliance or the web server to be restarted before the changes can take effect. When one or more of these updates are made alongside other reverse proxy updates, an additional step is required to deploy the reverse proxy updates. You must:

Deploy all updates.

Restart the appliance or the web server.

Deploy all remaining updates.

If there are conflicts between the pending changes and the production files, then all pending changes are automatically rolled back and the production files remain unchanged.

Web service

Deploy the pending configuration changes

URL

https://{appliance_hostname}/pending_changes/deploy

Method

GET

Parameters

N/A

Response

HTTP response code and JSON error response where applicable.

Example

Request:

GET https://{appliance_hostname}/pending_changes/deploy

Response:

200 ok

Roll back the pending configuration changes

URL

https://{appliance_hostname}/pending_changes/forget

Method

GET

Parameters

N/A

Response

HTTP response code and JSON error response where applicable.

Example

Request:

GET https://{appliance_hostname}/pending_changes/forget

Response:

200 ok

Retrieve the number of outstanding changes

URL

https://{appliance_hostname}/pending_changes/count

Method

GET

Parameters

N/A

Response

HTTP response code and JSON data that represents the number of pending changes.

Example

Request:

GET https://{appliance_hostname}/pending_changes/count

Response:

{"count": 3}

Retrieve the list of outstanding changes

URL

https://{appliance_hostname}/pending_changes

Method

GET

Parameters

N/A

Response

HTTP response code and JSON data that represents the list of pending changes.

Example

Request:

GET https://{appliance_hostname}/pending_changes

Response:

200 ok

[{
"id": 0,
"policy": "SSL Certificates",
"user": "admin",
"date": "2012-11-05T11:22:20+10:00"
}]

Local management interface

When there are pending changes, a warning message is displayed at the top of the main pane. To deploy or roll back the pending changes:

Click the Click here to review the changes or apply them to the system link within the warning message.

In the Deploy Pending Changes page:

To view the details of changes that are made to a particular module, click the link to that module.

To deploy the changes, click Deploy.

To abandon the changes, click Roll Back.

To close the pop-up page without any actions against the changes, click Cancel.

Parent topic: Managing the appliance

Parent topic: Web Reverse Proxy administration

Home: Appliance DashboardHome: Appliance DashboardAccess Manager Appliance: Home Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.home appliance dashboarddashboardsappliancesdashboardsThese widgets are displayed right after you log in. You can also access them by clicking Home: Appliance Dashboard on the menu bar.Appliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Viewing system notificationsYou can view warning information about potential problems with the Notification dashboard widget.Viewing disk usageYou can view the disk space status and remaining disk life information with the Disk Usage dashboard widget.Viewing IP addressesYou can view a categorized list of IP addresses that the appliance is listening on with the Interfaces dashboard widget.Viewing certificate expiryYou can view certificate details with the Certificate Expiry widget.Viewing partition informationYou can view information about the active and backup partitions with the Partition Information widget.Viewing network trafficYou can view network traffic for the past hour with the Network Traffic widget.Configuring the dashboardYou can add and arrange widgets on the dashboard to monitor traffic, events, and system health in a summary view.

Home: Appliance Dashboard

The appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

These widgets are displayed right after you log in. You can also access them by clicking Home: Appliance Dashboard on the menu bar.

Viewing system notifications
You can view warning information about potential problems with the Notification dashboard widget.

Viewing disk usage
You can view the disk space status and remaining disk life information with the Disk Usage dashboard widget.

Viewing IP addresses
You can view a categorized list of IP addresses that the appliance is listening on with the Interfaces dashboard widget.

Viewing certificate expiry
You can view certificate details with the Certificate Expiry widget.

Viewing partition information
You can view information about the active and backup partitions with the Partition Information widget.

Viewing network traffic
You can view network traffic for the past hour with the Network Traffic widget.

Configuring the dashboard
You can add and arrange widgets on the dashboard to monitor traffic, events, and system health in a summary view.

Parent topic: Appliance administration

Viewing system notificationsViewing system notificationsAccess Manager Appliance: Viewing system notificationsYou can view warning information about potential problems with the Notification dashboard widget.systemsnotificationsnotificationsFrom the dashboard, locate the Notification widget.Warning messages about the following potential problems are displayed:Certificates that are due to expire.Reverse proxy instances that are not currently running.The disk space utilization has exceeded the warning threshold.The database size has reached the warning threshold, which is 80% capacity.The CPU utilization has exceeded the warning threshold.There are pending changes, which have not been deployed.Take appropriate actions as required.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Viewing system notifications

You can view warning information about potential problems with the Notification dashboard widget.

Procedure

From the dashboard, locate the Notification widget. Warning messages about the following potential problems are displayed:

Certificates that are due to expire.

Reverse proxy instances that are not currently running.

The disk space utilization has exceeded the warning threshold.

The database size has reached the warning threshold, which is 80% capacity.

The CPU utilization has exceeded the warning threshold.

There are pending changes, which have not been deployed.

Take appropriate actions as required.

Parent topic: Home: Appliance Dashboard

Viewing disk usageViewing disk usageAccess Manager Appliance: Viewing disk usageYou can view the disk space status and remaining disk life information with the Disk Usage dashboard widget.disk spaceFrom the dashboard, locate the Disk Usage widget.Disk Space Pie ChartInformation about used disk space and free disk space is visualized in the pie chart. Consumed Disk SpaceHow much space (in GB) is already used.Most of the disk space is typically used by log files and trace files. To minimize the disk footprint, set the appliance to store log and trace files on a remote server. It is also a good practice to clear unused log and trace files on a periodic basis.Free Disk SpaceHow much space (in GB) is free.Total Disk SpaceHow much space in total (in GB) is available to the appliance.The disk space in a hardware appliance is limited by the capacity of the hard disk drive it carries. Optional: Click Refresh to refresh the data.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Viewing disk usage

You can view the disk space status and remaining disk life information with the Disk Usage dashboard widget.

Procedure

From the dashboard, locate the Disk Usage widget.

Disk Space Pie Chart

Information about used disk space and free disk space is visualized in the pie chart.

Consumed Disk Space

How much space (in GB) is already used.

Note: Most of the disk space is typically used by log files and trace files. To minimize the disk footprint, set the appliance to store log and trace files on a remote server. It is also a good practice to clear unused log and trace files on a periodic basis.

Free Disk Space

How much space (in GB) is free.

Total Disk Space

How much space in total (in GB) is available to the appliance.

Note: The disk space in a hardware appliance is limited by the capacity of the hard disk drive it carries.

Optional: Click Refresh to refresh the data.

Parent topic: Home: Appliance Dashboard

Viewing IP addressesViewing IP addressesAccess Manager Appliance: Viewing IP addressesYou can view a categorized list of IP addresses that the appliance is listening on with the Interfaces dashboard widget.IP addressesFrom the dashboard, locate the Interfaces widget.The IP addresses of all enabled and configured interfaces are displayed, along with the virtual IP addresses that are managed by the front-end load balancer.Management IPsA list of IP addresses of the management interfaces that are enabled and configured.Application IPsA list of IP addresses of the application interfaces that are enabled and configured.Load Balancer IPsA list of IP addresses of the load balancer services.Optional: Click Refresh to refresh the data.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Viewing IP addresses

You can view a categorized list of IP addresses that the appliance is listening on with the Interfaces dashboard widget.

Procedure

From the dashboard, locate the Interfaces widget. The IP addresses of all enabled and configured interfaces are displayed, along with the virtual IP addresses that are managed by the front-end load balancer.

Management IPs

A list of IP addresses of the management interfaces that are enabled and configured.

Application IPs

A list of IP addresses of the application interfaces that are enabled and configured.

Load Balancer IPs

A list of IP addresses of the load balancer services.

Optional: Click Refresh to refresh the data.

Parent topic: Home: Appliance Dashboard

Viewing certificate expiryViewing certificate expiryAccess Manager Appliance: Viewing certificate expiryYou can view certificate details with the Certificate Expiry widget.certificatesexpiryFrom the dashboard, locate the Certificate Expiry widget.Details about the certificates are displayed.Certificate LabelLabel of the certificate.ExpirationThe date on which the certificate expires.TypeType of the certificate.Key DatabaseName of the key database that the certificate belongs to.Optional: Click Refresh to refresh the data.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Viewing certificate expiry

You can view certificate details with the Certificate Expiry widget.

Procedure

From the dashboard, locate the Certificate Expiry widget. Details about the certificates are displayed.

Certificate Label

Label of the certificate.

Expiration

The date on which the certificate expires.

Type

Type of the certificate.

Key Database

Name of the key database that the certificate belongs to.

Optional: Click Refresh to refresh the data.

Parent topic: Home: Appliance Dashboard

Viewing partition informationViewing partition informationAccess Manager Appliance: Viewing partition informationYou can view information about the active and backup partitions with the Partition Information widget.partitionsFrom the dashboard, locate the Partition Information widget.Details about the active and backup partition are displayed.Firmware VersionVersion information of the appliance firmwareInstallation DateDate on which the appliance firmware was installedInstallation TypeType of the appliance firmware installationLast BootTime when the appliance was last bootedOptional: Click Firmware Settings to go the page to modify settings of the firmware.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Viewing partition information

You can view information about the active and backup partitions with the Partition Information widget.

Procedure

From the dashboard, locate the Partition Information widget. Details about the active and backup partition are displayed.

Firmware Version

Version information of the appliance firmware

Installation Date

Date on which the appliance firmware was installed

Installation Type

Type of the appliance firmware installation

Last Boot

Time when the appliance was last booted

Optional: Click Firmware Settings to go the page to modify settings of the firmware.

Parent topic: Home: Appliance Dashboard

Viewing network trafficViewing network trafficAccess Manager Appliance: Viewing network trafficYou can view network traffic for the past hour with the Network Traffic widget.networktraffictrafficFrom the dashboard, locate the Network Traffic widget.The In and Out traffic details for the past hour are displayed.Optional: Click an interface name to display the details for a specific interface.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Viewing network traffic

You can view network traffic for the past hour with the Network Traffic widget.

Procedure

From the dashboard, locate the Network Traffic widget. The In and Out traffic details for the past hour are displayed.

Optional: Click an interface name to display the details for a specific interface.

Parent topic: Home: Appliance Dashboard

Configuring the dashboardYou can add and arrange widgets on the dashboard to monitor traffic, events, and system health in a summary view.dashboardssummary viewmonitorshome appliance dashboardThe appliance includes a dashboard view for a summary of your network status. You can select and arrange the information displayed on the dashboard to meet your needs.Click HomeAppliance Dashboard.To rearrange the placement of the widgets, click the banner of a widget and drag it to where you want it.Widgets snap to a grid layout on the dashboard and are automatically arranged when you move one widget to the location of another.Home: Appliance DashboardThe appliance provides a series of dashboard widgets in its local management interface. You can use these widgets to view commonly used system information.

Configuring the dashboard

You can add and arrange widgets on the dashboard to monitor traffic, events, and system health in a summary view.

About this task

The appliance includes a dashboard view for a summary of your network status. You can select and arrange the information displayed on the dashboard to meet your needs.

Procedure

Click Home > Appliance Dashboard.

To rearrange the placement of the widgets, click the banner of a widget and drag it to where you want it.

Note: Widgets snap to a grid layout on the dashboard and are automatically arranged when you move one widget to the location of another.

Parent topic: Home: Appliance Dashboard

Monitoring: Analysis and DiagnosticsMonitoring: Analysis and DiagnosticsAccess Manager Appliance: Monitoring Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.analysisdiagnosticshealthstatisticsAppliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Viewing the event logSystem events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.Viewing memory statisticsView the memory graph to see the memory utilization of the appliance.Viewing CPU utilizationView the CPU graph to see the CPU utilization of the appliance.Viewing storage utilizationView the storage graph to see the percentage of disk space that is used by the boot and root partitions of the appliance.Viewing application interface statisticsTo view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.Viewing application log filesUse the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.

Monitoring: Analysis and Diagnostics

You can monitor the health and statistics of the appliance.

Viewing the event log
System events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.

Viewing memory statistics
View the memory graph to see the memory utilization of the appliance.

Viewing CPU utilization
View the CPU graph to see the CPU utilization of the appliance.

Viewing storage utilization
View the storage graph to see the percentage of disk space that is used by the boot and root partitions of the appliance.

Viewing application interface statistics
To view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.

Viewing application log files
Use the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.

Parent topic: Appliance administration

Viewing the event logViewing the event logAccess Manager Appliance: Viewing the event logSystem events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.event logssystemseventsClick Monitor Analysis and DiagnosticsLogsEvent Log.The system events displayed. You can:Click Pause Live Streaming to stop the live updating of the event log.Click Start Live Streaming to resume live updating of the event log.Click Export to download the event log file.In the exported event log file, the time occurred (occurred) field shows the seconds since Epoch (00:00:00 Universal time, 1 January 1970).When you use the table filter on the Priority field, the values that can be filtered are in English only (low, medium, and high). This behavior is expected on all language versions of the appliance.Monitoring: Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.

Viewing the event log

System events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.

Procedure

Click Monitor Analysis and Diagnostics > Logs > Event Log. The system events displayed. You can:

Click Pause Live Streaming to stop the live updating of the event log.

Click Start Live Streaming to resume live updating of the event log.

Click Export to download the event log file.

Notes:

In the exported event log file, the time occurred (occurred) field shows the seconds since Epoch (00:00:00 Universal time, 1 January 1970).

When you use the table filter on the Priority field, the values that can be filtered are in English only (low, medium, and high). This behavior is expected on all language versions of the appliance.

Parent topic: Monitoring: Analysis and Diagnostics

Viewing memory statisticsViewing memory statisticsAccess Manager Appliance: Viewing memory statisticsView the memory graph to see the memory utilization of the appliance.memory graphmemory statisticsClick Monitor Analysis and DiagnosticsSystem GraphsMemory.Select a Date Range:1 DayDisplays data points for every minute during the last 24 hours.3 DaysDisplays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.7 DaysDisplays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.30 DaysDisplays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.In the Legend box, select Memory Used to review total memory utilization.Monitoring: Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.

Viewing memory statistics

View the memory graph to see the memory utilization of the appliance.

Procedure

Click Monitor Analysis and Diagnostics > System Graphs > Memory.

Select a Date Range:

Option | Description
1 Day | Displays data points for every minute during the last 24 hours.
3 Days | Displays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.
7 Days | Displays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.
30 Days | Displays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.

In the Legend box, select Memory Used to review total memory utilization.

Parent topic: Monitoring: Analysis and Diagnostics

Viewing CPU utilizationViewing CPU utilizationAccess Manager Appliance: Viewing CPU utilizationView the CPU graph to see the CPU utilization of the appliance.CPU graphClick Monitor Analysis and DiagnosticsSystem GraphsCPU.Select a Date Range:1 DayDisplays data points for every minute during the last 24 hours.3 DaysDisplays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.7 DaysDisplays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.30 DaysDisplays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.In the Legend box, select the CPU utilization data that you want to review:UserSystemIdleMonitoring: Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.

Viewing CPU utilization

View the CPU graph to see the CPU utilization of the appliance.

Procedure

Click Monitor Analysis and Diagnostics > System Graphs > CPU.

Select a Date Range:

Option | Description
1 Day | Displays data points for every minute during the last 24 hours.
3 Days | Displays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.
7 Days | Displays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.
30 Days | Displays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.

In the Legend box, select the CPU utilization data that you want to review:

User

System

Idle

Parent topic: Monitoring: Analysis and Diagnostics

Viewing storage utilizationViewing storage utilizationAccess Manager Appliance: Viewing storage utilizationView the storage graph to see the percentage of disk space that is used by the boot and root partitions of the appliance.disk spacestoragerootpartitionsClick Monitor Analysis and DiagnosticsSystem GraphsStorage.Select a Date Range:1 DayDisplays data points for every minute during the last 24 hours.3 DaysDisplays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.7 DaysDisplays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.30 DaysDisplays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.In the Legend box, select which partitions you want to review:BootThe boot partition.RootThe base file system, where the system user is root.Monitoring: Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.

Viewing storage utilization

View the storage graph to see the percentage of disk space that is used by the boot and root partitions of the appliance.

Procedure

Click Monitor Analysis and Diagnostics > System Graphs > Storage.

Select a Date Range:

Option | Description
1 Day | Displays data points for every minute during the last 24 hours.
3 Days | Displays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.
7 Days | Displays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.
30 Days | Displays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.

In the Legend box, select which partitions you want to review:

Boot

The boot partition.

Root

The base file system, where the system user is root.

Parent topic: Monitoring: Analysis and Diagnostics

Viewing application interface statisticsViewing application interface statisticsAccess Manager Appliance: Viewing application interface statisticsTo view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.applications interfacestatisticsstatisticsFrom the top menu, select Monitor Analysis and DiagnosticsNetwork GraphsApplication Interface Statistics.In the Date Range field, select the period to display the statistics for.1 DayDisplays data for every 20-minute interval in one day.3 DaysDisplays data for every 20-minute interval during the last three days. 7 DaysDisplays data for every 20-minute interval during the last seven days. 30 DaysDisplays data for every day during the last 30 days. Monitoring: Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.

Viewing application interface statistics

To view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.

Procedure

From the top menu, select Monitor Analysis and Diagnostics > Network Graphs > Application Interface Statistics.

In the Date Range field, select the period to display the statistics for.

Option | Description
1 Day | Displays data for every 20-minute interval in one day.
3 Days | Displays data for every 20-minute interval during the last three days.
7 Days | Displays data for every 20-minute interval during the last seven days.
30 Days | Displays data for every day during the last 30 days.

Parent topic: Monitoring: Analysis and Diagnostics

Viewing application log filesViewing application log filesAccess Manager Appliance: Managing application log filesUse the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.applicationslogsmanagementapplicationslogsFrom the top menu, select Monitor Analysis and DiagnosticsApplication Log Files.The displayed directories contain the application log files that can be viewed and downloaded:access_control: Contains log files specific to the Advanced Access Control offering. It contains subdirectories for different categories of log files, such as auditing, isamcfg, and runtime.cluster: Contains logs files for the cluster manager.management_ui: Contains log files for the management interface. federation: Contains logs files specific to the Federation offering.By default, the log files are displayed in a tree view. Click Details View to manage the log files using a more detailed view. This view shows the path, file size, and last modified time of each log file. You can also order the files by name, path, file size, or last modified time.Click Refresh to get the most up-to-date data.You can then view or download the displayed log files.To view the log fileSelect the file of interest.Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Alternatively, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.Optional: Click Export to download the log file. To download the log fileSelect the file of interest.Click Export to save the file to your local drive.Confirm the save operation in the browser window that pops up.To clear or empty a log fileSelect the file of interest.Click Clear to clear the contents of the file.In the confirmation window, click Yes to confirm the clear operation. To delete a log fileSelect the file of interest.It is the administrator's responsibility to make sure that the log file to be deleted is not in use by the system.Click Delete to remove the log file.In the confirmation window, click Yes to confirm the deletion.Monitoring: Analysis and DiagnosticsYou can monitor the health and statistics of the appliance.

Viewing application log files

Use the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.

Procedure

From the top menu, select Monitor Analysis and Diagnostics > Application Log Files. The displayed directories contain the application log files that can be viewed and downloaded:

access_control: Contains log files specific to the Advanced Access Control offering. It contains subdirectories for different categories of log files, such as auditing, isamcfg, and runtime.

cluster: Contains logs files for the cluster manager.

management_ui: Contains log files for the management interface.

federation: Contains logs files specific to the Federation offering.

By default, the log files are displayed in a tree view.

Optional: Click Details View to manage the log files using a more detailed view. This view shows the path, file size, and last modified time of each log file. You can also order the files by name, path, file size, or last modified time.

Optional: Click Refresh to get the most up-to-date data.

You can then view or download the displayed log files.

To view the log file

Select the file of interest.

Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Alternatively, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.

Note: The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.

Optional: Click Export to download the log file.

To download the log file

Select the file of interest.

Click Export to save the file to your local drive.

Confirm the save operation in the browser window that pops up.

To clear or empty a log file

Select the file of interest.

Click Clear to clear the contents of the file.

In the confirmation window, click Yes to confirm the clear operation.

To delete a log file

Select the file of interest.

Note: It is the administrator's responsibility to make sure that the log file to be deleted is not in use by the system.

Click Delete to remove the log file.

In the confirmation window, click Yes to confirm the deletion.

Parent topic: Monitoring: Analysis and Diagnostics

Manage: System SettingsManage: System SettingsAccess Manager Appliance: Manage System SettingsInformation about configuring Security, Network, and System settings of your appliance.systemssettingsmanagementsettingssystemsAppliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Updates and licensingInformation about managing updates and licensing on your appliance.Network SettingsInformation about configuring network interfaces and information about your appliance.System settingsInformation about managing system settings on your appliance.Secure settingsInformation about managing secure settings on your appliance.

Manage: System Settings

Information about configuring Security, Network, and System settings of your appliance.

Updates and licensing
Information about managing updates and licensing on your appliance.

Network Settings
Information about configuring network interfaces and information about your appliance.

System settings
Information about managing system settings on your appliance.

Secure settings
Information about managing secure settings on your appliance.

Parent topic: Appliance administration

Updates and licensingUpdates and licensingAccess Manager Appliance: Updates and LicensingInformation about managing updates and licensing on your appliance.updateslicensinglicenseupdatesManage: System SettingsInformation about configuring Security, Network, and System settings of your appliance.Viewing the update and licensing overviewThe Overview page displays current information about the appliance firmware, intrusion prevention content, IP reputation database, update servers, and licenses.Installing updatesInstall firmware and intrusion prevention updates to improve the appliance and the network protection that is provided by the appliance.Configuring the update scheduleConfigure the update schedule to receive X-Force content updates daily, weekly, or according to a specified interval of time.Configuring update server settingsConfigure your appliance to download update files from an update server.Viewing update historyView the update history to see which firmware and security content updates are downloaded, installed, and rolled back on the appliance.Installing a fix packInstall a fix pack when IBM Customer Support instructs you to do so.Installing a licenseYou must install a current license file to receive updates to the appliance.Managing firmware settingsThe appliance has two partitions with separate firmware on each partition. Partitions are swapped during firmware updates, so that you can roll back firmware updates.

Updates and licensing

Information about managing updates and licensing on your appliance.

Viewing the update and licensing overview
The Overview page displays current information about the appliance firmware, intrusion prevention content, IP reputation database, update servers, and licenses.

Installing updates
Install firmware and intrusion prevention updates to improve the appliance and the network protection that is provided by the appliance.

Configuring the update schedule
Configure the update schedule to receive X-Force content updates daily, weekly, or according to a specified interval of time.

Configuring update server settings
Configure your appliance to download update files from an update server.

Viewing update history
View the update history to see which firmware and security content updates are downloaded, installed, and rolled back on the appliance.

Installing a fix pack
Install a fix pack when IBM® Customer Support instructs you to do so.

Installing a license
You must install a current license file to receive updates to the appliance.

Managing firmware settings
The appliance has two partitions with separate firmware on each partition. Partitions are swapped during firmware updates, so that you can roll back firmware updates.

Parent topic: Manage: System Settings

Viewing the update and licensing overviewViewing the update and licensing overviewAccess Manager Appliance: Viewing the update and licensing overviewThe Overview page displays current information about the appliance firmware, intrusion prevention content, IP reputation database, update servers, and licenses.overviewupdatesoverviewlicenseoverviewClick Manage System SettingsUpdates and LicensingOverview.View the updates and licensing information. Click the links on the page to make a specific update.Updates and licensingInformation about managing updates and licensing on your appliance.

Viewing the update and licensing overview

The Overview page displays current information about the appliance firmware, intrusion prevention content, IP reputation database, update servers, and licenses.

Procedure

Click Manage System Settings > Updates and Licensing > Overview.

View the updates and licensing information. Click the links on the page to make a specific update.

Parent topic: Updates and licensing

Installing updatesInstalling updatesAccess Manager Appliance: Installing updatesInstall firmware and intrusion prevention updates to improve the appliance and the network protection that is provided by the appliance.updatesfirmwareintrusion preventionAfter you install firmware updates, you must restart the appliance.Firmware updates contain new program files, fixes or patches, enhancements, and online help. Intrusion prevention updates contain the most recent security content that is provided by IBM X-Force research and development team.Click Manage System SettingsUpdates and LicensingAvailable Updates.On the Available Updates page, use one or more of the following commands:UploadTo manually add an update, click Upload. In the New Update window, click Select Update, browse to the update file, click Open, and then click Submit.You can install the update after you manually add it.RefreshTo check for updates, click Refresh.InstallTo install an update, select the update, and then click Install.Updates and licensingInformation about managing updates and licensing on your appliance.

Installing updates

Install firmware and intrusion prevention updates to improve the appliance and the network protection that is provided by the appliance.

About this task

Important: After you install firmware updates, you must restart the appliance.

Firmware updates contain new program files, fixes or patches, enhancements, and online help.

Intrusion prevention updates contain the most recent security content that is provided by IBM X-Force research and development team.

Procedure

Click Manage System Settings > Updates and Licensing > Available Updates.

On the Available Updates page, use one or more of the following commands:

Option
Description

Upload
To manually add an update, click Upload. In the New Update window, click Select Update, browse to the update file, click Open, and then click Submit.

Note: You can install the update after you manually add it.

Refresh
To check for updates, click Refresh.

Install
To install an update, select the update, and then click Install.

Parent topic: Updates and licensing

Configuring the update scheduleConfiguring the update scheduleAccess Manager Appliance: Configuring the update scheduleConfigure the update schedule to receive X-Force content updates daily, weekly, or according to a specified interval of time.settingsupdatesscheduling updatesupdatesschedulesserversX-Force signaturesthreat protectionA 15-minute buffer is applied to update times so that update servers do not become overburdened. Updates are downloaded up to 15 minutes before or after the time you specify.Click Manage System SettingsUpdates and LicensingScheduled Security Updates.In the Update Schedule pane, select Auto Update to receive X-Force content updates.Use one of the following methods to schedule updates:To receive updates on a daily basis, select Daily or Weekly, select Every Day from the first list, and then select a time from the second list.To receive updates on a weekly basis, select Daily or Weekly, select the day of the week you would like to receive updates on, and then select a time from the second list.To receive updates on a schedule that ranges from 1 hour to 24 hours, select Specified Interval, and then select the update interval in minutes.60 - 1440 minutesClick Save.Updates and licensingInformation about managing updates and licensing on your appliance.

Configuring the update schedule

Configure the update schedule to receive X-Force content updates daily, weekly, or according to a specified interval of time.

About this task

A 15-minute buffer is applied to update times so that update servers do not become overburdened. Updates are downloaded up to 15 minutes before or after the time you specify.

Procedure

Click Manage System Settings > Updates and Licensing > Scheduled Security Updates.

In the Update Schedule pane, select Auto Update to receive X-Force content updates.

Use one of the following methods to schedule updates:

To receive updates on a daily basis, select Daily or Weekly, select Every Day from the first list, and then select a time from the second list.

To receive updates on a weekly basis, select Daily or Weekly, select the day of the week you would like to receive updates on, and then select a time from the second list.

To receive updates on a schedule that ranges from 1 hour to 24 hours, select Specified Interval, and then select the update interval in minutes.

Range: 60 - 1440 minutes

Click Save.

Parent topic: Updates and licensing

Configuring update server settingsConfiguring update server settingsAccess Manager Appliance: Configuring update server settingsConfigure your appliance to download update files from an update server.updatesserverssettingsupdatesYou can configure multiple, ordered servers for failover.You cannot delete the IBM ISS Default License and Update Server. You can disable it.Click Manage System SettingsUpdates and LicensingUpdate Servers.In the Update Servers pane, take one of the following actions:To add an update server, click New. The Add Server window is displayed.To edit an update server, select the server, and then click Edit. The Edit Server window is displayed.To delete an update server, select the server, and then click Delete.When you add or edit an update server, configure the following options on the General tab:OrderDefines the order in which update servers are queried for appliance software updates.The appliance uses the next server on the list when a server takes more than 24 hours to respond.EnableEnables the update server so that it can be used by the appliance.NameA name that describes the update server.Server AddressThe IP address or DNS name of the update server.PortThe port number that the appliance uses to communicate with the update server.The port number for the IBM ISS Download Center is 443. The default port for internal update servers is 3994.Trust LevelDefines how the appliance is authenticated with the update server.Explicit (user-defined)The appliance uses the local certificate that is pasted into the Certificate box to authenticate the connection to the update server. The certificate must be Base64 PEM-encoded data.Explicit trust is the most secure trust level. Explicit trust certificates must be Base64 PEM-encoded data.Explicit (xpu.iss.net)The appliance uses the local certificate for the IBM ISS update server to authenticate the connection to the update server. The IBM ISS update server certificate is installed on the appliance by default. The certificate is Base64 PEM-encoded data.Explicit trust is the most secure trust level. Explicit trust certificates must be Base64 PEM-encoded data.First Time TrustIf a certificate is not on the appliance, the appliance downloads a certificate from the server when it connects to the server for the first time. First Time Trust is more secure than Trust All and less secure than Explicit Trust.After the appliance downloads the certificate, it reverts to explicit-trust functionality.Trust AllThe appliance trusts the update server, and does not use SSL certificates for authentication.Trust all trust is the least secure trust level.The Trust All trust level presents a security risk because the internal update server can be spoofed and redirected to a fake server.If you use a proxy server, configure the following settings on the Proxy Settings tab:Use ProxyEnables the appliance to use a proxy server for update servers.Server AddressThe IP address or DNS name of the proxy server.The Server Address field is displayed when you select the Use Proxy check box.PortThe port number that the proxy server uses to communicate with the update server.The Port field is displayed when you select the Use Proxy check box.Use AuthenticationEnables the appliance to authenticate to a proxy server.User Name User name that is required for authenticating to the proxy server.The User Name field is displayed when you select the Use Authentication check box.PasswordPassword that is required for authenticating to the proxy server.The Password field is displayed when you select the Use Authentication check box.Click Submit.Updates and licensingInformation about managing updates and licensing on your appliance.

Configuring update server settings

Configure your appliance to download update files from an update server.

About this task

You can configure multiple, ordered servers for failover.

Note: You cannot delete the IBM® ISS Default License and Update Server. You can disable it.

Procedure

Click Manage System Settings > Updates and Licensing > Update Servers.

In the Update Servers pane, take one of the following actions:

To add an update server, click New. The Add Server window is displayed.

To edit an update server, select the server, and then click Edit. The Edit Server window is displayed.

To delete an update server, select the server, and then click Delete.

When you add or edit an update server, configure the following options on the General tab:

Option
Description

Order
Defines the order in which update servers are queried for appliance software updates.

The appliance uses the next server on the list when a server takes more than 24 hours to respond.

Enable
Enables the update server so that it can be used by the appliance.

Name
A name that describes the update server.

Server Address
The IP address or DNS name of the update server.

Port
The port number that the appliance uses to communicate with the update server.

Tip: The port number for the IBM ISS Download Center is 443. The default port for internal update servers is 3994.

Trust Level
Defines how the appliance is authenticated with the update server.

Explicit (user-defined)

The appliance uses the local certificate that is pasted into the Certificate box to authenticate the connection to the update server. The certificate must be Base64 PEM-encoded data.

Explicit trust is the most secure trust level. Explicit trust certificates must be Base64 PEM-encoded data.

Explicit (xpu.iss.net)

The appliance uses the local certificate for the IBM ISS update server to authenticate the connection to the update server. The IBM ISS update server certificate is installed on the appliance by default. The certificate is Base64 PEM-encoded data.

Explicit trust is the most secure trust level. Explicit trust certificates must be Base64 PEM-encoded data.

First Time Trust

If a certificate is not on the appliance, the appliance downloads a certificate from the server when it connects to the server for the first time.

First Time Trust is more secure than Trust All and less secure than Explicit Trust.

Note: After the appliance downloads the certificate, it reverts to explicit-trust functionality.

Trust All

The appliance trusts the update server, and does not use SSL certificates for authentication.

Trust all trust is the least secure trust level.

Attention: The Trust All trust level presents a security risk because the internal update server can be spoofed and redirected to a fake server.

Optional: If you use a proxy server, configure the following settings on the Proxy Settings tab:

Option
Description

Use Proxy
Enables the appliance to use a proxy server for update servers.

Server Address
The IP address or DNS name of the proxy server.

Note: The Server Address field is displayed when you select the Use Proxy check box.

Port
The port number that the proxy server uses to communicate with the update server.

Note: The Port field is displayed when you select the Use Proxy check box.

Use Authentication
Enables the appliance to authenticate to a proxy server.

User Name
User name that is required for authenticating to the proxy server.

Note: The User Name field is displayed when you select the Use Authentication check box.

Password
Password that is required for authenticating to the proxy server.

Note: The Password field is displayed when you select the Use Authentication check box.

Click Submit.

Parent topic: Updates and licensing

Viewing update historyViewing update historyAccess Manager Appliance: Viewing update historyView the update history to see which firmware and security content updates are downloaded, installed, and rolled back on the appliance.updateshistoryhistoryAfter you install an update, the update package is deleted from the appliance.Click Manage System SettingsUpdates and LicensingUpdate History.To refresh the page, click Refresh.Updates and licensingInformation about managing updates and licensing on your appliance.

Viewing update history

View the update history to see which firmware and security content updates are downloaded, installed, and rolled back on the appliance.

About this task

After you install an update, the update package is deleted from the appliance.

Procedure

Click Manage System Settings > Updates and Licensing > Update History.

To refresh the page, click Refresh.

Parent topic: Updates and licensing

Installing a fix packInstalling a fix packAccess Manager Appliance: Installing a fix packInstall a fix pack when IBM Customer Support instructs you to do so.fix packspatchesinstallationfix packsThe appliance does not automatically create a backup copy of a partition when you apply a fix pack to it. If you want to back up your partition before you apply the fix pack, then you must do it manually.You cannot uninstall fix packs.Fix packs are applied to the current partition. If a fix pack is installed on your appliance, you can view information about who installed it, comments, patch size, and the installation date.In the local management interface, go to Manage System Settings Updates and LicensingFix Packs.In the Fix Packs pane, click New.In the Add Fix Pack window, click Browse for fix pack: to locate the fix pack file, and then click Open.Click Save Configuration to install the fix pack.Updates and licensingInformation about managing updates and licensing on your appliance.

Installing a fix pack

Install a fix pack when IBM® Customer Support instructs you to do so.

Before you begin

The appliance does not automatically create a backup copy of a partition when you apply a fix pack to it. If you want to back up your partition before you apply the fix pack, then you must do it manually.

Restriction: You cannot uninstall fix packs.

About this task

Fix packs are applied to the current partition. If a fix pack is installed on your appliance, you can view information about who installed it, comments, patch size, and the installation date.

Procedure

In the local management interface, go to Manage System Settings > Updates and Licensing > Fix Packs.

In the Fix Packs pane, click New.

In the Add Fix Pack window, click Browse for fix pack: to locate the fix pack file, and then click Open.

Click Save Configuration to install the fix pack.

Parent topic: Updates and licensing

Installing a licenseInstalling a licenseAccess Manager Appliance: Installing a licenseYou must install a current license file to receive updates to the appliance.local management interfaceLMILMIlicense installationinstallationlicenselicenseinstallationContact your IBM representative to get a license registration number. You can download and register your license from the IBM Security Systems License Key Center at https://ibmss.flexnetoperations.com.If you are not configuring your appliance for the first time, click Manage System SettingsUpdates and LicensingLicensing and Activation.On the Licensing and Activation page, click Select License and locate the license file that you want to install.Select the license file that you want to install and then click Open.Click Save Configuration.OCNID stands for Order Confirmation Number and ID.Updates and licensingInformation about managing updates and licensing on your appliance.

Installing a license

You must install a current license file to receive updates to the appliance.

About this task

Contact your IBM® representative to get a license registration number. You can download and register your license from the IBM Security Systems License Key Center at https://ibmss.flexnetoperations.com.

Procedure

Optional: If you are not configuring your appliance for the first time, click Manage System Settings > Updates and Licensing > Licensing and Activation.

On the Licensing and Activation page, click Select License and locate the license file that you want to install.

Select the license file that you want to install and then click Open.

Click Save Configuration.

Note: OCNID stands for Order Confirmation Number and ID.

Parent topic: Updates and licensing

Managing firmware settingsManaging firmware settingsAccess Manager Appliance: Managing firmware settingsThe appliance has two partitions with separate firmware on each partition. Partitions are swapped during firmware updates, so that you can roll back firmware updates. firmwaresettingssettingsfirmwareupdatesfirmwarepartitionsEither partition can be active on the appliance. In the factory-installed state, partition 1 is active and contains the firmware version of the current released product. When you apply a firmware update, the update is installed on partition 2 and your policies and settings are copied from partition 1 to partition 2. The appliance restarts the system using partition 2, which is now the active partition.The appliance comes with identical firmware versions installed on both of the partitions so that you have a backup of the initial firmware configuration.Avoid swapping partitions to restore configuration and policy settings. Use snapshots to back up and restore configuration and policy settings.Click Manage System SettingsUpdates and LicensingFirmware Settings.On the Firmware Settings page, perform one or more of the following actions:EditTo edit the comment that is associated with a partition, select the partition and click Edit.Create BackupCreate a backup of your firmware only when you are installing a fix pack that is provided by IBM Customer Support. Fix packs are installed on the active partition and you might not be able to uninstall the fix pack. The backup process can take several minutes to complete.Set ActiveSet a partition active when you want to use the firmware that is installed on that partition. For example, you might want to set a partition active to use firmware that does not contain a recently applied update or fix pack.Click Yes.If you set a partition active, the appliance restarts the system using the newly activated partition.Updates and licensingInformation about managing updates and licensing on your appliance.

Managing firmware settings

The appliance has two partitions with separate firmware on each partition. Partitions are swapped during firmware updates, so that you can roll back firmware updates.

About this task

Either partition can be active on the appliance. In the factory-installed state, partition 1 is active and contains the firmware version of the current released product. When you apply a firmware update, the update is installed on partition 2 and your policies and settings are copied from partition 1 to partition 2. The appliance restarts the system using partition 2, which is now the active partition.

Note: The appliance comes with identical firmware versions installed on both of the partitions so that you have a backup of the initial firmware configuration.

Tip: Avoid swapping partitions to restore configuration and policy settings. Use snapshots to back up and restore configuration and policy settings.

Procedure

Click Manage System Settings > Updates and Licensing > Firmware Settings.

On the Firmware Settings page, perform one or more of the following actions:

Option
Description

Edit
To edit the comment that is associated with a partition, select the partition and click Edit.

Create Backup

Important: Create a backup of your firmware only when you are installing a fix pack that is provided by IBM® Customer Support.

Fix packs are installed on the active partition and you might not be able to uninstall the fix pack.

Note: The backup process can take several minutes to complete.

Set Active

Set a partition active when you want to use the firmware that is installed on that partition. For example, you might want to set a partition active to use firmware that does not contain a recently applied update or fix pack.

Click Yes. If you set a partition active, the appliance restarts the system using the newly activated partition.

Parent topic: Updates and licensing

Network SettingsNetwork SettingsAccess Manager Appliance: Network SettingsInformation about configuring network interfaces and information about your appliance.network settingssettingsnetworkManage: System SettingsInformation about configuring Security, Network, and System settings of your appliance.Configuring general networking settingsSet the host name of the appliance.Configuring DNSDefine the DNS settings for your interfaces.Configuring interfaces Create or edit your management and application interfaces.Appliance port usageThe following table lists the ports that the appliance listens on and provides a description of what the port is used for and what external entities use the port. Configuring aggregated network interfacesSet up aggregated network interfaces for high availability, increased throughput, or both.Configuring static routesBesides configuring static routes, you can also use this page to set the default gateway.Managing hosts file To manage hosts file with the local management interface, use the Hosts File management page.Managing packet tracing To manage packet tracing with the local management interface, use the Packet Tracing management page.Creating a clusterYou can configure multiple appliances into a cluster that shares configuration information and runtime information. Use the Cluster Configuration management page to administer cluster support for the appliance.Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance.

Network Settings

Information about configuring network interfaces and information about your appliance.

Configuring general networking settings
Set the host name of the appliance.

Configuring DNS
Define the DNS settings for your interfaces.

Configuring interfaces
Create or edit your management and application interfaces.

Appliance port usage
The following table lists the ports that the appliance listens on and provides a description of what the port is used for and what external entities use the port.

Configuring aggregated network interfaces
Set up aggregated network interfaces for high availability, increased throughput, or both.

Configuring static routes
Besides configuring static routes, you can also use this page to set the default gateway.

Managing hosts file
To manage hosts file with the local management interface, use the Hosts File management page.

Managing packet tracing
To manage packet tracing with the local management interface, use the Packet Tracing management page.

Creating a cluster
You can configure multiple appliances into a cluster that shares configuration information and runtime information. Use the Cluster Configuration management page to administer cluster support for the appliance.

Managing cluster configuration
From the Cluster Configuration management page, administer cluster support for the appliance.

Parent topic: Manage: System Settings

Configuring general networking settingsSet the host name of the appliance.From the top menu, select Manage System Settings Network SettingsGeneral.Enter the host name. Changing the appliance host name causes the security device to reset the network connection. You must reconnect after the network connection is reset. This process does not interrupt traffic through the application interfaces.Click Save Configuration.Network SettingsInformation about configuring network interfaces and information about your appliance.

Configuring general networking settings

Set the host name of the appliance.

Procedure

From the top menu, select Manage System Settings > Network Settings > General.

Enter the host name.

Note: Changing the appliance host name causes the security device to reset the network connection. You must reconnect after the network connection is reset. This process does not interrupt traffic through the application interfaces.

Click Save Configuration.

Parent topic: Network Settings

Configuring DNSAccess Manager Appliance: Configuring DNSDefine the DNS settings for your interfaces.From the top menu, select Manage System Settings Network SettingsDNS.To set the DNS via DHCP of an interface:Select Auto.Select the interface from the list.To use manual DNS settings:Select Manual.Define the following settings:Primary DNS (mandatory)Secondary DNSTertiary DNSDNS Search Path Click Save Configuration.Network SettingsInformation about configuring network interfaces and information about your appliance.

Configuring DNS

Define the DNS settings for your interfaces.

Procedure

From the top menu, select Manage System Settings > Network Settings > DNS.

To set the DNS via DHCP of an interface:

Select Auto.

Select the interface from the list.

To use manual DNS settings:

Select Manual.

Define the following settings:

Primary DNS (mandatory)

Secondary DNS

Tertiary DNS

DNS Search Path

Click Save Configuration.

Parent topic: Network Settings

Configuring interfacesAccess Manager Appliance: Configuring interfaces Create or edit your management and application interfaces.applicationsinterfacemanagementinterfaceThe appliance supports the use of virtual local area network (VLAN). A VLAN is a logical association of switch ports that are based on a set of rules or criteria, such as MAC addresses, protocols, network address, or multicast address. This concept permits the LAN to be segmented again without requiring physical rearrangement. The interfaces with names in the format of 1.x are real interfaces, which correspond to the network adapters on your physical appliance or the adapters that are attached to your virtual appliance. The interfaces with names in the format of 1.x:<vlanid> are virtual interfaces. You can add or delete virtual interfaces, but you cannot delete real interfaces. When you add an interface, you are effectively adding a VLAN to a specific interface.From the top menu, select Manage System Settings Network SettingsInterfaces.All current management and application interfaces are displayed. You can add or edit interfaces and addresses that are associated with an interface.To add an interface:Click New.On the General Configuration tab:Select the interface to create from the list.Enter a name for the interface.Select the Enabled checkbox if you want to enable this interface at the same time when it is created.Enter the virtual LAN ID for the interface.Add notes about this interface in the Comment field.Click Save Configuration to confirm the details of this interface.To modify the details of an interface:Select the interface from the table.Click Edit.Modify the details as needed.Click Save Configuration to confirm the modified details.To delete a virtual interface:Select the interface from the table.Click Delete.Click Yes to confirm the operation.To add an IP address to an interface:Select the interface.Click Edit.On the IPv4 Settings tab:If you want to use DHCP to assign addresses, select Auto.To make this interface a management interface, select the Management Interface checkbox. To make this interface an application interface, leave this checkbox unchecked.Select the Provides Default Route if needed.If you want to use static addresses, select Manual.Click New to add an address.Enter the static address in the Address field in the format of <address>/<mask>. Masks are supported in dot-decimal and CIDR notation, for example:10.0.2.38/24 10.0.2.38/255.255.255.0To use this address for management purposes, select the Management Address checkbox. To use this address for application, leave this checkbox unchecked.By default, the appliance performs validation to ensure that overlapping subnets do not span multiple interfaces. Such validation helps prevent networking issues in certain environments. If you want to disable this validation for your environment, select the Override the Overlapping Subnet Validation option.Click Save Configuration to confirm the details.On the IPv6 Settings tab:If you want to use DHCP to assign addresses, select Auto.To make this interface a management interface, select the Management Interface checkbox. To make this interface an application interface, leave this checkbox unchecked.If you want to use static addresses, select Manual.Click New to add an address.Enter the static address in the Address field in the format of <address>/<mask>. Masks must be given in CIDR notation, for example:2001:db8::38/48To use this address for management purposes, select the Management Address checkbox. To use this address for application, leave this checkbox unchecked.Click Save Configuration to confirm the details.To modify an IP address that is associated with an interface:Select the interface.Click Edit.On the IPv4 Settings and IPv6 Settings tabs, select the address to modify and then click Edit.Modify the settings as needed.In the Edit address window, click Save Configuration to close the window.Click Save Configuration to confirm the interface details.To delete an IP address that is associated with an interface:Select the interface.Click Edit.On the IPv4 Settings and IPv6 Settings tabs, select the address to delete and then click Delete.Click Yes to confirm the delete operation.Click Save Configuration to confirm the interface details.Network SettingsInformation about configuring network interfaces and information about your appliance.

Configuring interfaces

Create or edit your management and application interfaces.

About this task

The appliance supports the use of virtual local area network (VLAN). A VLAN is a logical association of switch ports that are based on a set of rules or criteria, such as MAC addresses, protocols, network address, or multicast address. This concept permits the LAN to be segmented again without requiring physical rearrangement.

The interfaces with names in the format of 1.x are real interfaces, which correspond to the network adapters on your physical appliance or the adapters that are attached to your virtual appliance. The interfaces with names in the format of 1.x:<vlanid> are virtual interfaces.

You can add or delete virtual interfaces, but you cannot delete real interfaces. When you add an interface, you are effectively adding a VLAN to a specific interface.

Procedure

From the top menu, select Manage System Settings > Network Settings > Interfaces. All current management and application interfaces are displayed.

You can add or edit interfaces and addresses that are associated with an interface.

To add an interface:

Click New.

On the General Configuration tab:

Select the interface to create from the list.

Enter a name for the interface.

Select the Enabled checkbox if you want to enable this interface at the same time when it is created.

Enter the virtual LAN ID for the interface.

Add notes about this interface in the Comment field.

Click Save Configuration to confirm the details of this interface.

To modify the details of an interface:

Select the interface from the table.

Click Edit.

Modify the details as needed.

Click Save Configuration to confirm the modified details.

To delete a virtual interface:

Select the interface from the table.

Click Delete.

Click Yes to confirm the operation.

To add an IP address to an interface:

Select the interface.

Click Edit.

On the IPv4 Settings tab:

If you want to use DHCP to assign addresses, select Auto.

To make this interface a management interface, select the Management Interface checkbox. To make this interface an application interface, leave this checkbox unchecked.

Select the Provides Default Route if needed.

If you want to use static addresses, select Manual.

Click New to add an address.

Enter the static address in the Address field in the format of <address>/<mask>. Masks are supported in dot-decimal and CIDR notation, for example:

10.0.2.38/24
10.0.2.38/255.255.255.0

To use this address for management purposes, select the Management Address checkbox. To use this address for application, leave this checkbox unchecked.

By default, the appliance performs validation to ensure that overlapping subnets do not span multiple interfaces. Such validation helps prevent networking issues in certain environments. If you want to disable this validation for your environment, select the Override the Overlapping Subnet Validation option.

Click Save Configuration to confirm the details.

On the IPv6 Settings tab:

If you want to use DHCP to assign addresses, select Auto.

To make this interface a management interface, select the Management Interface checkbox. To make this interface an application interface, leave this checkbox unchecked.

If you want to use static addresses, select Manual.

Click New to add an address.

Enter the static address in the Address field in the format of <address>/<mask>. Masks must be given in CIDR notation, for example:

2001:db8::38/48

To use this address for management purposes, select the Management Address checkbox. To use this address for application, leave this checkbox unchecked.

Click Save Configuration to confirm the details.

To modify an IP address that is associated with an interface:

Select the interface.

Click Edit.

On the IPv4 Settings and IPv6 Settings tabs, select the address to modify and then click Edit.

Modify the settings as needed.

In the Edit address window, click Save Configuration to close the window.

Click Save Configuration to confirm the interface details.

To delete an IP address that is associated with an interface:

Select the interface.

Click Edit.

On the IPv4 Settings and IPv6 Settings tabs, select the address to delete and then click Delete.

Click Yes to confirm the delete operation.

Click Save Configuration to confirm the interface details.

Parent topic: Network Settings

Appliance port usageThe following table lists the ports that the appliance listens on and provides a description of what the port is used for and what external entities use the port. This table can be used to decide:The firewall rules that are used to allow or block port access to or from the applianceWhich ports are reserved and must be avoided by administrator configurable portsThe appliance provides two types of interface groupings: administration interface and application interface. Typically ports are assigned to one or more IP addresses from one of these groups of interfaces. In some cases, ports can be assigned to all IP addresses from both groups by providing 0.0.0.0 as the IP address to use.Ports used on the appliance (listen ports)Appliance portAppliance interface typeDescription22AdministrationThis port serves two roles.Provides remote access to the CLI for the admin user.Cluster inter-node communication. Each node in a cluster must have access to all other cluster nodes' SSH ports.80Application (The port can be assigned to both application and administration interfaces by providing 0.0.0.0 as the IP address to use.)This port is the typical default unsecured (non-SSL) port of the first configured Web Reverse Proxy instance. This port can be configured to a different value or disabled.443Application (The port can be assigned to both application and administration interfaces by providing 0.0.0.0 as the IP address to use.)This port is the typical default secured (SSL) port of the first configured Web Reverse Proxy instance. This port can be configured to a different value or disabled.443AdministrationThis port is the Local Management Interface (LMI) secure port.636AdministrationThis port is reserved for remote SSL access to the embedded user registry. The port is only active on the primary master node of the cluster when the Security Access Manager runtime is configured to use the embedded user registry.2020+7AdministrationThis port is used by the appliance DSC servers to replicate session data between cluster master nodes. Each master node must have access to the port of its adjacent node. The primary node is adjacent to the secondary node. The secondary node is adjacent to the tertiary node. The tertiary node is adjacent to the quaternary node.The 2020+7 value assumes that the cluster First Port is set to its default value 2020. If the cluster First Port is configured to a value other than the default, this port value must be adjusted relative to the configured First Port value (configured First Port+7).7135AdministrationThe policy server listens on this port if it is running on the node. Any node that is running Web Reverse Proxy servers, authorization servers, the PD.jar API, pdadmin API, or pdadmin command requires access to this port. This port can be configured to a different value.7136ApplicationThis port is the typical first authorization server port that can be accessed by the Java or C administration or authorization APIs. This port can be configured to a different value.7137AdministrationThis port is the typical first authorization server admin port, which must be accessible by the machine that is running the policy server. This port can be configured to a different value.7234AdministrationThe Web Reverse Proxy server listens on this port if it is running on the node. This port must be accessible from the node that is running the policy server. This value is the typical port that is used for the first Web Reverse Proxy on a node. This port can be configured to a different value.Many services on the appliance can be configured to access external service ports such as LDAP, SQL, DNS, NTP Web Reverse Proxy junctions, OCSP, Kerberos, and syslog server ports. The routing that is configured on the appliance determines which outgoing interface is used to access them based on the external service's IP address.Network SettingsInformation about configuring network interfaces and information about your appliance.

Appliance port usage

The following table lists the ports that the appliance listens on and provides a description of what the port is used for and what external entities use the port.

This table can be used to decide:

The firewall rules that are used to allow or block port access to or from the appliance

Which ports are reserved and must be avoided by administrator configurable ports

The appliance provides two types of interface groupings: administration interface and application interface. Typically ports are assigned to one or more IP addresses from one of these groups of interfaces. In some cases, ports can be assigned to all IP addresses from both groups by providing 0.0.0.0 as the IP address to use.

Table 147. Ports used on the appliance (listen ports)

Appliance port
Appliance interface type
Description

22
Administration
This port serves two roles.

Provides remote access to the CLI for the admin user.

Cluster inter-node communication. Each node in a cluster must have access to all other cluster nodes' SSH ports.

80
Application (The port can be assigned to both application and administration interfaces by providing 0.0.0.0 as the IP address to use.)
This port is the typical default unsecured (non-SSL) port of the first configured Web Reverse Proxy instance. This port can be configured to a different value or disabled.

443
Application (The port can be assigned to both application and administration interfaces by providing 0.0.0.0 as the IP address to use.)
This port is the typical default secured (SSL) port of the first configured Web Reverse Proxy instance. This port can be configured to a different value or disabled.

443
Administration
This port is the Local Management Interface (LMI) secure port.

636
Administration
This port is reserved for remote SSL access to the embedded user registry. The port is only active on the primary master node of the cluster when the Security Access Manager runtime is configured to use the embedded user registry.

2020+7
Administration
This port is used by the appliance DSC servers to replicate session data between cluster master nodes. Each master node must have access to the port of its adjacent node. The primary node is adjacent to the secondary node. The secondary node is adjacent to the tertiary node. The tertiary node is adjacent to the quaternary node.

Note: The 2020+7 value assumes that the cluster First Port is set to its default value 2020. If the cluster First Port is configured to a value other than the default, this port value must be adjusted relative to the configured First Port value (configured First Port+7).

7135
Administration
The policy server listens on this port if it is running on the node. Any node that is running Web Reverse Proxy servers, authorization servers, the PD.jar API, pdadmin API, or pdadmin command requires access to this port. This port can be configured to a different value.

7136
Application
This port is the typical first authorization server port that can be accessed by the Java or C administration or authorization APIs. This port can be configured to a different value.

7137
Administration
This port is the typical first authorization server admin port, which must be accessible by the machine that is running the policy server. This port can be configured to a different value.

7234
Administration
The Web Reverse Proxy server listens on this port if it is running on the node. This port must be accessible from the node that is running the policy server. This value is the typical port that is used for the first Web Reverse Proxy on a node. This port can be configured to a different value.

Note: Many services on the appliance can be configured to access external service ports such as LDAP, SQL, DNS, NTP Web Reverse Proxy junctions, OCSP, Kerberos, and syslog server ports. The routing that is configured on the appliance determines which outgoing interface is used to access them based on the external service's IP address.

Parent topic: Network Settings

Configuring aggregated network interfacesSet up aggregated network interfaces for high availability, increased throughput, or both.This capability is commonly called bonding in Linux environments. Use it to place multiple real network interfaces behind a virtual network interface. This feature is useful for physical appliances only, and not for virtual appliances. For virtual appliances, you can use the hypervisor to set up the NIC bonding and present a single virtual interface to the virtual appliances. The appliance supports the following bonding modes: Bonding modesModeNameDescription0balance-rrRound-robin policy: Transmits packets in sequential order from the first available slave through the last. 1active-backupActive-backup policy: Only 1 slave in the bond is active. A different slave becomes active if, and only if, the active slave fails.2balance-xorXOR policy: Transmits based on the selected transmit hash policy.3broadcastBroadcast policy: Transmits everything on all slave interfaces.4802.3adIEEE 802.3ad Dynamic link aggregation: Creates aggregation groups that share speed and duplex settings. Uses all slaves in the active aggregator according to the 802.3ad specification.5balance-tlbAdaptive transmit load balancing: Channel bonding that does not require any special switch support.6balance-albAdaptive load balancing: Includes balance-tlb plus receive load balancing (rlb) for IPV4 traffic. It does not require any special switch support. The receive load balancing is achieved by ARP negotiation. Configuration options for these bonding modes are available through the appliance advanced tuning parameters. If set, the parameters apply to all bonding interfaces. For more details, see Managing advanced tuning parametersChange the advanced tuning parameter values only under the supervision of IBM software support.. The bonding (enslave) order of the slaves is not configurable. The network device that is configured as the primary bonding device uses its underlying physical device as the first bonded slave. Expect interruption to any existing network traffic on the involved interfaces when the configuration changes are committed.From the top menu, select Manage System Settings Network SettingsInterfaces.Edit the appliance interface to be replaced by the virtual bonding interface behind which the aggregation of interfaces is placed. The physical network interface that is normally represented by this configuration is the first interface aggregated behind the bonding virtual interface.Select the interface and then click Edit.For this interface, set the Bonding Mode to something other than None or Slave. For example, 802.3ad.Some bonding modes, such as 802.3ad, require equivalent support from the network switch to which they are attached.Set the IP addresses of the interface, if not already set. This interface configuration defines the IP address of the aggregation.Save the configuration.Edit each additional interface to be added to the aggregation. For each slave:Set the Bonding Mode to Slave.If you have an existing bonding configuration on an interface, you must set the bonding configuration back to None and deploy the change before you can set the interface to be a slave. That is, the Slave option does not appear when you list the available modes on an interface with an existing bonding configuration. You must first clear the existing bonding configuration by setting the bonding mode to None. After deploying the change, you can see the Slave option in the list. For the Bonded To field, select the initial interface that was configured in previous steps.Save the configuration.Commit the changes.Network SettingsInformation about configuring network interfaces and information about your appliance.

Configuring aggregated network interfaces

Set up aggregated network interfaces for high availability, increased throughput, or both.

About this task

This capability is commonly called bonding in Linux environments. Use it to place multiple real network interfaces behind a virtual network interface. This feature is useful for physical appliances only, and not for virtual appliances. For virtual appliances, you can use the hypervisor to set up the NIC bonding and present a single virtual interface to the virtual appliances.

The appliance supports the following bonding modes:

Table 148. Bonding modes

Mode | Name | Description
0 | balance-rr | Round-robin policy: Transmits packets in sequential order from the first available slave through the last.
1 | active-backup | Active-backup policy: Only 1 slave in the bond is active. A different slave becomes active if, and only if, the active slave fails.
2 | balance-xor | XOR policy: Transmits based on the selected transmit hash policy.
3 | broadcast | Broadcast policy: Transmits everything on all slave interfaces.
4 | 802.3ad | IEEE 802.3ad Dynamic link aggregation: Creates aggregation groups that share speed and duplex settings. Uses all slaves in the active aggregator according to the 802.3ad specification.
5 | balance-tlb | Adaptive transmit load balancing: Channel bonding that does not require any special switch support.
6 | balance-alb | Adaptive load balancing: Includes balance-tlb plus receive load balancing (rlb) for IPV4 traffic. It does not require any special switch support. The receive load balancing is achieved by ARP negotiation.

Configuration options for these bonding modes are available through the appliance advanced tuning parameters. If set, the parameters apply to all bonding interfaces. For more details, see Managing advanced tuning parameters.

The bonding (enslave) order of the slaves is not configurable. The network device that is configured as the primary bonding device uses its underlying physical device as the first bonded slave.

Note: Expect interruption to any existing network traffic on the involved interfaces when the configuration changes are committed.

Procedure

From the top menu, select Manage System Settings > Network Settings > Interfaces.

Edit the appliance interface to be replaced by the virtual bonding interface behind which the aggregation of interfaces is placed. The physical network interface that is normally represented by this configuration is the first interface aggregated behind the bonding virtual interface.

Select the interface and then click Edit.

For this interface, set the Bonding Mode to something other than None or Slave. For example, 802.3ad.

Note: Some bonding modes, such as 802.3ad, require equivalent support from the network switch to which they are attached.

Set the IP addresses of the interface, if not already set. This interface configuration defines the IP address of the aggregation.

Save the configuration.

Edit each additional interface to be added to the aggregation. For each slave:

Set the Bonding Mode to Slave.

Note: If you have an existing bonding configuration on an interface, you must set the bonding configuration back to None and deploy the change before you can set the interface to be a slave. That is, the Slave option does not appear when you list the available modes on an interface with an existing bonding configuration. You must first clear the existing bonding configuration by setting the bonding mode to None. After deploying the change, you can see the Slave option in the list.

For the Bonded To field, select the initial interface that was configured in previous steps.

Save the configuration.

Commit the changes.

Parent topic: Network Settings

Configuring static routesConfiguring static routesAccess Manager Appliance: Configuring static routesBesides configuring static routes, you can also use this page to set the default gateway.static routesconfigurationredirectiondefault gatewaydefault routeThis task is only necessary for networks that contain an additional network segment between the user segment and the appliance.From the top menu, select Manage System SettingsNetwork SettingsStatic Routes.Select the route table to edit from the Route Table For field.You can use these route tables to configure routes that are specific to requests destined for a particular local IP address. Use the Default table if specific local IP address control is not required.Take one of the following actions:Click New to create a route.Select an existing route, and then click Edit to change the settings.Select an existing route, and then click Delete to remove it.Define the following information in each field:EnabledDestinationTo make this route the default gateway, enter Default in the Destination field. GatewayMetricInterfaceClick Save Configuration.Network SettingsInformation about configuring network interfaces and information about your appliance.Multiple routing tablesYou can configure a specific set of routes for each IP that is configured on the appliance. This setting can overcome a single point of failure that occurs from having a single interface and gateway for a particular subnet, or from having a single default gateway.

Configuring static routes

Besides configuring static routes, you can also use this page to set the default gateway.

About this task

This task is only necessary for networks that contain an additional network segment between the user segment and the appliance.

Procedure

From the top menu, select Manage System Settings > Network Settings > Static Routes.

Select the route table to edit from the Route Table For field. You can use these route tables to configure routes that are specific to requests destined for a particular local IP address. Use the Default table if specific local IP address control is not required.

Take one of the following actions:

Click New to create a route.

Select an existing route, and then click Edit to change the settings.

Select an existing route, and then click Delete to remove it.

Define the following information in each field:

Enabled

Destination

Note: To make this route the default gateway, enter Default in the Destination field.

Gateway

Metric

Interface

Click Save Configuration.

Multiple routing tables
You can configure a specific set of routes for each IP that is configured on the appliance. This setting can overcome a single point of failure that occurs from having a single interface and gateway for a particular subnet, or from having a single default gateway.

Parent topic: Network Settings

Multiple routing tables You can configure a specific set of routes for each IP that is configured on the appliance. This setting can overcome a single point of failure that occurs from having a single interface and gateway for a particular subnet, or from having a single default gateway.Interface-specific routes might also be required to solve some firewall conflicts. In an appliance that has multiple interfaces, the return path for a particular request might be different from the request path. In certain firewall configurations, this situation is seen as a spoofing attack and the packet is discarded.For example, if the appliance has an IP of 172.16.197.11/24 configured on Interface 1.2 and a gateway at 172.16.197.2, then select the table for IP 172.16.197.11 and add the following two static routes: 172.16.197.0/24 Interface 1.2 Default via 172.16.197.2 Interface 1.2 If a set of static routes is not provided for a particular IP's table, or the static routes in the IP's table do not result in a route for the IP, then the “Default” static route table is applied.If the ability to define different routes for different destination IP address is not required, then place all required static routes under the “Default” static route table. This is also where migrated static routes from prior releases that do not provide this feature are placed.Configuring static routesBesides configuring static routes, you can also use this page to set the default gateway.

Multiple routing tables

You can configure a specific set of routes for each IP that is configured on the appliance. This setting can overcome a single point of failure that occurs from having a single interface and gateway for a particular subnet, or from having a single default gateway.

Interface-specific routes might also be required to solve some firewall conflicts. In an appliance that has multiple interfaces, the return path for a particular request might be different from the request path. In certain firewall configurations, this situation is seen as a spoofing attack and the packet is discarded.

For example, if the appliance has an IP of 172.16.197.11/24 configured on Interface 1.2 and a gateway at 172.16.197.2, then select the table for IP 172.16.197.11 and add the following two static routes:

172.16.197.0/24 Interface 1.2

Default via 172.16.197.2 Interface 1.2

If a set of static routes is not provided for a particular IP's table, or the static routes in the IP's table do not result in a route for the IP, then the “Default” static route table is applied.

If the ability to define different routes for different destination IP address is not required, then place all required static routes under the “Default” static route table. This is also where migrated static routes from prior releases that do not provide this feature are placed.

Parent topic: Configuring static routes

Managing hosts fileManaging hosts fileAccess Manager Appliance: Managing hosts file To manage hosts file with the local management interface, use the Hosts File management page.hostsfilesmanagementhosts filesFrom the top menu, select Manage System Settings Network SettingsHosts File.All current host records with their IP address and host names are displayed.You can then work with host records and host names.Add a host recordSelect the root level Host Records entry or do not select any entries.Click New.On the Create Host record page, provide IP address and host name of the host record to add.Click Save.Add a host name to a host recordSelect the host record entry to add the host name to.Click New.On the Add Hostname to Host Record page, enter the host name to add.Click Save.Remove a host recordSelect the host record entry to delete.Click Delete.On the confirmation page, click Yes to confirm the deletion.Remove a host name from a host recordSelect host name entry to delete.Click Delete.On the confirmation page, click Yes to confirm the deletion.If the removed host name is the only associated host name for the IP address, then the entire host record (the IP address and host name) is removed.Network SettingsInformation about configuring network interfaces and information about your appliance.

Managing hosts file

To manage hosts file with the local management interface, use the Hosts File management page.

Procedure

From the top menu, select Manage System Settings > Network Settings > Hosts File. All current host records with their IP address and host names are displayed.

You can then work with host records and host names.

Add a host record

Select the root level Host Records entry or do not select any entries.

Click New.

On the Create Host record page, provide IP address and host name of the host record to add.

Click Save.

Add a host name to a host record

Select the host record entry to add the host name to.

Click New.

On the Add Hostname to Host Record page, enter the host name to add.

Click Save.

Remove a host record

Select the host record entry to delete.

Click Delete.

On the confirmation page, click Yes to confirm the deletion.

Remove a host name from a host record

Select host name entry to delete.

Click Delete.

On the confirmation page, click Yes to confirm the deletion.

Note: If the removed host name is the only associated host name for the IP address, then the entire host record (the IP address and host name) is removed.

Parent topic: Network Settings

Managing packet tracingManaging packet tracingAccess Manager Appliance: Managing packet tracing To manage packet tracing with the local management interface, use the Packet Tracing management page.packet tracingmanagementpacket tracingFrom the top menu, select Manage System Settings Network SettingsPacket Tracing.The status of packet tracing is displayed.Manage packet tracing settings.Start packet tracingClick Start.On the Start Packet Tracing page:Select the interface name in the Interface field.If no value is selected for the Interface field, packet tracing is enabled for all interfaces.Click the Filter field.On the Set Filter page, select a pre-defined filter in the Display Filter field, or enter the filter manually in the Filter String field.Click Save.Define the maximum size of the packet tracing file (PCAP file) in the Maximum File Size field. This value is the maximum size that the packet tracing file can grow to before packet tracing is disabled.If no value is selected for the Maximum File Size field, the maximum file size is set to half the remaining disk size. Click Start.Only a single packet tracing operation can be running at the same time. A new packet trace cannot be started until the PCAP file from the previous trace is deleted.Stop packet tracingClick Stop.Click Yes to confirm the action.Export the packet tracing PCAP fileClick Export.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save action in the browser pop-up window.Delete the packet tracing PCAP fileClick Delete.Click Yes to confirm the action. If packet tracing is running, the PCAP file cannot be deleted. You must stop the associated packet tracing before you delete the PCAP file.Network SettingsInformation about configuring network interfaces and information about your appliance.

Managing packet tracing

To manage packet tracing with the local management interface, use the Packet Tracing management page.

Procedure

From the top menu, select Manage System Settings > Network Settings > Packet Tracing. The status of packet tracing is displayed.

Manage packet tracing settings.

Start packet tracing

Click Start.

On the Start Packet Tracing page:

Select the interface name in the Interface field.

Note: If no value is selected for the Interface field, packet tracing is enabled for all interfaces.

Click the Filter field.

On the Set Filter page, select a pre-defined filter in the Display Filter field, or enter the filter manually in the Filter String field.

Click Save.

Define the maximum size of the packet tracing file (PCAP file) in the Maximum File Size field. This value is the maximum size that the packet tracing file can grow to before packet tracing is disabled.

Note: If no value is selected for the Maximum File Size field, the maximum file size is set to half the remaining disk size.

Click Start.

Note: Only a single packet tracing operation can be running at the same time. A new packet trace cannot be started until the PCAP file from the previous trace is deleted.

Stop packet tracing

Click Stop.

Click Yes to confirm the action.

Export the packet tracing PCAP file

Click Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save action in the browser pop-up window.

Delete the packet tracing PCAP file

Click Delete.

Click Yes to confirm the action.

Note: If packet tracing is running, the PCAP file cannot be deleted. You must stop the associated packet tracing before you delete the PCAP file.

Parent topic: Network Settings

Creating a clusterCreating a clusterAccess Manager appliance: creating a clusterYou can configure multiple appliances into a cluster that shares configuration information and runtime information. Use the Cluster Configuration management page to administer cluster support for the appliance.creating clusters In a cluster, you must designate one of the appliances as the primary master. You can designate up to three subordinate masters, which are called the secondary, tertiary, and quaternary masters. The cluster services can fail over between these masters. The remaining appliances serve as nodes. You must activate the primary and secondary masters of the cluster at the highest level of all the nodes in the cluster. For example, if any of the nodes have been activated with the Advanced Access Control module, the primary and secondary masters must also be activated for Advanced Access Control. Activation levels are validated when: A node joins the cluster. Validation ensures that the primary and secondary masters are activated to at least the same level.A new primary or secondary master is set to ensure that the activation level of the new master is at least at the same level of the current primary master. By default, every appliance operates as a stand-alone cluster with only a single node. You can optionally configure a group of appliances into a cluster with multiple nodes. For detailed information about clusters, see Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.. Select an appliance to be the primary master. You can choose any appliance as the primary master if it is not a member of another cluster. If the selected appliance is in another cluster, you must unregister it before you can appoint it as the primary master of a new cluster.Set the value of the Primary Master field on the selected appliance to the IP address of the first management interface. The default value for this field is set to 127.0.0.1 for a stand-alone cluster with a single node. Save and deploy this update. The chosen appliance is configured as the primary master of a cluster that can contain multiple nodes. Export the cluster signature file on the primary master. The cluster signature file contains configuration information so that cluster members can identify and communicate with the primary master. Join appliances to the cluster by importing the cluster signature file on each appliance that you want to become a cluster member. The process of joining an appliance to the cluster is a registration. Update the cluster configuration on the primary master. As part of the cluster configuration, you can define more masters from the pool of registered nodes. For more information, see Failover in a clusterThe distributed session cache, internal runtime database, geolocation database, and configuration database have varying failover capabilities in a clustered environment. . Save and deploy the configuration changes. As a rule, try to limit the number of changes that are made to the cluster configuration in a single policy update. Cluster configuration reference generalUse the Cluster Configuration management page to administer cluster support for the appliance.Session cache referenceUse the Cluster Configuration management page to administer cluster support for the appliance.Runtime databaseYou can view and update the current runtime database settings with the Runtime Database tab on the Cluster Configuration management page.Network SettingsInformation about configuring network interfaces and information about your appliance.

Creating a cluster

You can configure multiple appliances into a cluster that shares configuration information and runtime information. Use the Cluster Configuration management page to administer cluster support for the appliance.

About this task

In a cluster, you must designate one of the appliances as the primary master. You can designate up to three subordinate masters, which are called the secondary, tertiary, and quaternary masters. The cluster services can fail over between these masters. The remaining appliances serve as nodes.

You must activate the primary and secondary masters of the cluster at the highest level of all the nodes in the cluster. For example, if any of the nodes have been activated with the Advanced Access Control module, the primary and secondary masters must also be activated for Advanced Access Control. Activation levels are validated when:

A node joins the cluster. Validation ensures that the primary and secondary masters are activated to at least the same level.

A new primary or secondary master is set to ensure that the activation level of the new master is at least at the same level of the current primary master.

By default, every appliance operates as a stand-alone cluster with only a single node. You can optionally configure a group of appliances into a cluster with multiple nodes.

For detailed information about clusters, see Cluster support.

Procedure

Select an appliance to be the primary master. You can choose any appliance as the primary master if it is not a member of another cluster. If the selected appliance is in another cluster, you must unregister it before you can appoint it as the primary master of a new cluster.

Set the value of the Primary Master field on the selected appliance to the IP address of the first management interface.

Note: The default value for this field is set to 127.0.0.1 for a stand-alone cluster with a single node.

Save and deploy this update. The chosen appliance is configured as the primary master of a cluster that can contain multiple nodes.

Export the cluster signature file on the primary master. The cluster signature file contains configuration information so that cluster members can identify and communicate with the primary master.

Join appliances to the cluster by importing the cluster signature file on each appliance that you want to become a cluster member. The process of joining an appliance to the cluster is a registration.

Update the cluster configuration on the primary master. As part of the cluster configuration, you can define more masters from the pool of registered nodes. For more information, see Failover in a cluster.

Save and deploy the configuration changes.

Note: As a rule, try to limit the number of changes that are made to the cluster configuration in a single policy update.

Parent topic: Network Settings

Related reference:

Cluster configuration reference general

Session cache reference

Runtime database

Managing cluster configuration Managing cluster configurationAccess Manager appliance: managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance.clustersregistrationconfigurationpromotiondemote mastermaster nodesregistrationsignature filesnodespromotion Configure the browser to allow pop-up windows if you want to export files. About the Stand-alone option: It is the default setting on the appliance. You can choose it in the following situations:The appliance is a primary master with no other node in the cluster.The appliance is a node in a cluster, but it is in stand-alone mode for recovery purposes.The corresponding Primary Master default IP address on the appliance is 127.0.0.1.These initial settings indicate that by default the appliance operates as a stand-alone cluster with a single node.If you do not want this appliance to be the primary master, but rather a node in an existing cluster, follow the steps in Join the current appliance to the cluster.When the Stand-alone option is selected, the First Port field is enabled and the fields under Masters for All Services are disabled. About the Multi-node option:To use this appliance as the primary master of a cluster with multiple nodes, you must set the Multi-mode option. When the Multi-node option is selected:If the appliance is the primary master, the First Port field is enabled.If the appliance is not the primary master, the First Port field is disabled. Cluster configuration updates do not take effect until you deploy the changes through the local management interface. From the top menu of the local management interface, select Manage System Settings Cluster Configuration. A list of the nodes in the cluster is under Nodes.Take any of the following actions and click Save. Clicking Save submits all configuration changes from the General, Session Cache, and Database tabs. Add a description to a cluster node Select the node.Click Edit Description.Enter the description for the node. Specify an appliance to be the primary master of a cluster Select the General tab. To make the current node the primary master:If the appliance is in stand-alone mode, select Multi-node.If the appliance is a non-primary node in a cluster, click Make Primary Master. View and update the current cluster general configuration You can perform the update operation only through the primary master local management interface. Select the General tab. Edit the current configuration. View and update the current cluster session cache configuration You can perform the update operation only through the primary master local management interface. The distributed session cache is one of the cluster services. It is used by the IBM Security Access Manager appliance to distribute session data. You must configure the distributed session cache settings for the cluster on the primary master. Select the Session Cache tab. Edit the current settings. View and update the current runtime database configurationThe runtime database stores runtime data. You can perform the update operation only through the primary master local management interface. Select the Database tab.Edit the current settings. If you change the location of the runtime database from Local to the cluster to Remote to the cluster, Database Maintenance displays the following error message: System Error FBTRBA091E The retrieval failed because the resource cannot be found.Complete the following steps to restart the local management interface: Use an ssh session to access the local management interface.Log in as the administrator.Type lmi, and press Enter.Type restart, and press Enter.Type exit, and press Enter.Export the cluster signature file from the cluster master The signature file contains connection and security information. A node uses this file to register with the cluster master server and participate in the cluster. You can generate the cluster signature file only on the primary master. On the General tab, click Export. If the Stand-alone option is selected, the cluster is a stand-alone cluster and the Export function is not available. To export the cluster signature file, select the Multi-node option. Confirm the save operation to export the cluster signature file to your local drive. Join the current appliance to the clusterThis process is referred to as registration. To review the registration rules, see Cluster registrationBefore you register or unregister a node in a cluster, consider these registration rules.. You must perform this operation through the local management interface of the appliance that is joining the cluster.On the Overview tab, click Join Cluster.In Join Cluster , click Browse to select the cluster signature file, which you exported from the primary master. See Export the cluster signature file from the cluster master.To join the cluster as a restricted node, check Join as restricted node. See Managing restricted nodes in a clusterYou can restrict nodes that are in the DMZ so that your network is secure. You can specify which nodes are restricted in the local management interface..Click Join.View the status of all nodesOn the Overview tab, all cluster nodes are displayed under Nodes.Accessible indicates whether the node can be contacted.Synchronized indicates whether the node is running with the current cluster configuration. If this column is empty, it means that the current configuration information cannot be obtained from the primary master.Master indicates whether the node is a cluster master.Remove a node or a secondary master node from the clusterThis process is referred to as unregistration. The cluster configuration prohibits deleting a node that is acting as a master.Perform this operation through the local management interface of the primary master.Take one of the following actions: To remove a node, select the node you want to remove from Nodes on the Overview tab.To remove a secondary master node: Delete the secondary master from Master for All Services on the General tab. Select the node you want to remove from Nodes on the Overview tab.Click Delete.To force the removal of the node even if the node cannot be reached, select the Force.Click Yes. Replicate settings across the clusterYou can enable the replication of the IBM Security Access Manager runtime settings and certificate database settings. After you enable the replication option, you can no longer update runtime and certificate database settings from the non-primary nodes.Perform this operation through the local management interface of the primary master.Select the Replication tab and take one of the following actions: For runtime settings, click Runtime component.For certificate database settings, click Certificate databases.Select Replicate with Cluster.Click Yes. Deploy the changes.Cluster configuration reference generalUse the Cluster Configuration management page to administer cluster support for the appliance.Session cache referenceUse the Cluster Configuration management page to administer cluster support for the appliance.Runtime databaseYou can view and update the current runtime database settings with the Runtime Database tab on the Cluster Configuration management page.Network SettingsInformation about configuring network interfaces and information about your appliance.Cluster configuration reference generalUse the Cluster Configuration management page to administer cluster support for the appliance.Session cache referenceUse the Cluster Configuration management page to administer cluster support for the appliance.Configuration databaseYou can view and update the current configuration database settings with the Configuration Database tab on the Cluster Configuration management page.Runtime databaseYou can view and update the current runtime database settings with the Runtime Database tab on the Cluster Configuration management page.

Managing cluster configuration

From the Cluster Configuration management page, administer cluster support for the appliance.

Before you begin

Configure the browser to allow pop-up windows if you want to export files.

About this task

About the Stand-alone option:

It is the default setting on the appliance.

You can choose it in the following situations:

The appliance is a primary master with no other node in the cluster.

The appliance is a node in a cluster, but it is in stand-alone mode for recovery purposes.

The corresponding Primary Master default IP address on the appliance is 127.0.0.1.

These initial settings indicate that by default the appliance operates as a stand-alone cluster with a single node.

If you do not want this appliance to be the primary master, but rather a node in an existing cluster, follow the steps in Join the current appliance to the cluster.

When the Stand-alone option is selected, the First Port field is enabled and the fields under Masters for All Services are disabled.

About the Multi-node option:

To use this appliance as the primary master of a cluster with multiple nodes, you must set the Multi-mode option.

When the Multi-node option is selected:

If the appliance is the primary master, the First Port field is enabled.

If the appliance is not the primary master, the First Port field is disabled.

Note: Cluster configuration updates do not take effect until you deploy the changes through the local management interface.

Procedure

From the top menu of the local management interface, select Manage System Settings > Cluster Configuration. A list of the nodes in the cluster is under Nodes.

Take any of the following actions and click Save. Clicking Save submits all configuration changes from the General, Session Cache, and Database tabs.

Add a description to a cluster node

Select the node.

Click Edit Description.

Enter the description for the node.

Specify an appliance to be the primary master of a cluster

Select the General tab.

To make the current node the primary master:

If the appliance is in stand-alone mode, select Multi-node.

If the appliance is a non-primary node in a cluster, click Make Primary Master.

View and update the current cluster general configuration

Note: You can perform the update operation only through the primary master local management interface.

Select the General tab.

Edit the current configuration.

View and update the current cluster session cache configuration

Note: You can perform the update operation only through the primary master local management interface.

The distributed session cache is one of the cluster services. It is used by the IBM Security Access Manager appliance to distribute session data. You must configure the distributed session cache settings for the cluster on the primary master.

Select the Session Cache tab.

Edit the current settings.

View and update the current runtime database configuration

The runtime database stores runtime data.

Note: You can perform the update operation only through the primary master local management interface.

Select the Database tab.

Edit the current settings.

If you change the location of the runtime database from Local to the cluster to Remote to the cluster, Database Maintenance displays the following error message:

System Error FBTRBA091E The retrieval failed because
  the resource cannot be found.

Complete the following steps to restart the local management interface:

Use an ssh session to access the local management interface.

Log in as the administrator.

Type lmi, and press Enter.

Type restart, and press Enter.

Type exit, and press Enter.

Export the cluster signature file from the cluster master

The signature file contains connection and security information. A node uses this file to register with the cluster master server and participate in the cluster.

Note: You can generate the cluster signature file only on the primary master.

On the General tab, click Export.

Note: If the Stand-alone option is selected, the cluster is a stand-alone cluster and the Export function is not available. To export the cluster signature file, select the Multi-node option.

Confirm the save operation to export the cluster signature file to your local drive.

Join the current appliance to the cluster

This process is referred to as registration. To review the registration rules, see Cluster registration.

Note: You must perform this operation through the local management interface of the appliance that is joining the cluster.

On the Overview tab, click Join Cluster.

In Join Cluster , click Browse to select the cluster signature file, which you exported from the primary master. See Export the cluster signature file from the cluster master.

To join the cluster as a restricted node, check Join as restricted node. See Managing restricted nodes in a cluster.

Click Join.

View the status of all nodes

On the Overview tab, all cluster nodes are displayed under Nodes.

Accessible indicates whether the node can be contacted.

Synchronized indicates whether the node is running with the current cluster configuration. If this column is empty, it means that the current configuration information cannot be obtained from the primary master.

Master indicates whether the node is a cluster master.

Remove a node or a secondary master node from the cluster

This process is referred to as unregistration. The cluster configuration prohibits deleting a node that is acting as a master.

Note: Perform this operation through the local management interface of the primary master.

Take one of the following actions:

To remove a node, select the node you want to remove from Nodes on the Overview tab.

To remove a secondary master node:

Delete the secondary master from Master for All Services on the General tab.

Select the node you want to remove from Nodes on the Overview tab.

Click Delete.

To force the removal of the node even if the node cannot be reached, select the Force.

Click Yes.

Replicate settings across the cluster

You can enable the replication of the IBM® Security Access Manager runtime settings and certificate database settings. After you enable the replication option, you can no longer update runtime and certificate database settings from the non-primary nodes.

Note: Perform this operation through the local management interface of the primary master.

Select the Replication tab and take one of the following actions:

For runtime settings, click Runtime component.

For certificate database settings, click Certificate databases.

Select Replicate with Cluster.

Click Yes.

Deploy the changes.

Cluster configuration reference general
Use the Cluster Configuration management page to administer cluster support for the appliance.

Session cache reference
Use the Cluster Configuration management page to administer cluster support for the appliance.

Configuration database
You can view and update the current configuration database settings with the Configuration Database tab on the Cluster Configuration management page.

Runtime database
You can view and update the current runtime database settings with the Runtime Database tab on the Cluster Configuration management page.

Parent topic: Network Settings

Related reference:

Cluster configuration reference general

Session cache reference

Runtime database

Cluster configuration reference generalCluster configuration reference generalAccess Manager appliance: cluster configuration reference generalUse the Cluster Configuration management page to administer cluster support for the appliance.references cluster configurationconfiguration You can view and update the current cluster general configuration:First PortThe appliance uses a range of 30 ports, starting with the assigned First Port value.This field is mandatory and cannot be empty. The default value is 2020.Primary MasterThe IP address of the first management interface on the primary master. This field is mandatory and cannot be empty. If you are configuring the appliance as a stand-alone cluster with only a single node, you can use the local IP address (127.0.0.1). However, to configure the appliance as a primary master for a cluster that contains multiple nodes, you must use the IP address of the first management interface. If you change this value to the first management interface, you must save and deploy the changes before you can configure the remaining fields. If you want to configure other masters, you must first join the appliances to the cluster.Add the entries for Primary Master, Secondary Master, Tertiary Master, and Quaternary Master in order. For example, you cannot add a tertiary unless a secondary exists, and you cannot remove a secondary if a tertiary exists.Use the Secondary Master, Tertiary Master, and Quaternary Master fields to manage the supplementary masters. You can update these values at any time to demote existing masters or promote new masters. When you configure the master nodes, you must adhere to the cluster configuration rules. For more information, see Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.. Secondary MasterThe IP address of the secondary master.Master External Reference EntityThe IP address of an external reference device that the primary and secondary masters can use to check the health of the network. This field is required if both the Primary Master and Secondary Master fields are set. Otherwise, it is disabled. Tertiary MasterThe IP address of the tertiary master. You can set this field only if there is a Secondary Master defined. Quaternary MasterThe IP address of the quaternary master. You can set this field only if there is a Tertiary Master defined. Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance.

Cluster configuration reference general

Use the Cluster Configuration management page to administer cluster support for the appliance.

You can view and update the current cluster general configuration:

First Port

The appliance uses a range of 30 ports, starting with the assigned First Port value.

This field is mandatory and cannot be empty. The default value is 2020.

Primary Master

The IP address of the first management interface on the primary master. This field is mandatory and cannot be empty.

If you are configuring the appliance as a stand-alone cluster with only a single node, you can use the local IP address (127.0.0.1). However, to configure the appliance as a primary master for a cluster that contains multiple nodes, you must use the IP address of the first management interface.

If you change this value to the first management interface, you must save and deploy the changes before you can configure the remaining fields.

If you want to configure other masters, you must first join the appliances to the cluster.

Add the entries for Primary Master, Secondary Master, Tertiary Master, and Quaternary Master in order. For example, you cannot add a tertiary unless a secondary exists, and you cannot remove a secondary if a tertiary exists.

Use the Secondary Master, Tertiary Master, and Quaternary Master fields to manage the supplementary masters. You can update these values at any time to demote existing masters or promote new masters.

When you configure the master nodes, you must adhere to the cluster configuration rules. For more information, see Cluster configuration rules.

Secondary Master

The IP address of the secondary master.

Master External Reference Entity

The IP address of an external reference device that the primary and secondary masters can use to check the health of the network.

Note: This field is required if both the Primary Master and Secondary Master fields are set. Otherwise, it is disabled.

Tertiary Master

The IP address of the tertiary master.

Note: You can set this field only if there is a Secondary Master defined.

Quaternary Master

The IP address of the quaternary master.

Note: You can set this field only if there is a Tertiary Master defined.

Parent topic: Managing cluster configuration

Session cache referenceSession cache referenceAccess Manager appliance: session cache referenceUse the Cluster Configuration management page to administer cluster support for the appliance.sessionscache referencereferences session cache You can view and update the current cluster session cache configuration:Worker threadsThe number of worker threads that handle the server requests. At a minimum, use a number that is greater than the maximum number of clients.Maximum session lifetimeThe maximum lifetime in seconds for each session. Use a value greater than the maximum lifetime of all clients. That is, use a value greater than the maximum [session] timeout value that the WebSEAL clients use. For more information about the [session] timeout configuration entry, see the reference topics for the Web Reverse Stanza Proxy in the Knowledge Center.Client grace periodThe grace period in seconds that a client has available to restart and register an interest in the session again before the session is removed from the session cache. This period gives the client a chance to restart without losing the session from the server. Use a similar value to the idle timeout value for the session on the client. That is, use a value similar to the [session] inactive-timeout value that is set in the client Web Reverse Proxy configuration. For more information about the [session] inactive-timeout configuration entry, see the reference topics for the Web Reverse Stanza Proxy in the Knowledge Center.Support internal clients onlyIndicates that only internal clients can use the distributed session cache. The current version supports internal clients only.If this option is selected, the remaining fields are disabled. Clients can be turned off. For more information about failover events, search for the Options for handling session failover events topic in the Administering topics in the Knowledge Center. For more information about configuration properties, see Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization.. Support internal and external clientsIndicates that both internal and external clients can use the distributed session cache.Support for external clients is not available in the current version.Port The port on which external clients can communicate with the session cache. This field is mandatory if you enable support for internal and external clients.Enable SSLIf selected, the distributed session cache uses secure communication with its clients. If you enable SSL, you must also configure the Keyfile.KeyfileLists the existing keyfiles on the appliance. These keyfiles are managed from the SSL certificates page. You can click the SSL Certificates link on the right to go to that page.If you want to share the key files across the cluster, you must go to the SSL Certificates page and select the Replicate with Cluster check box.LabelLists the certificate labels in the selected keyfile. This field is disabled if a keyfile is not selected.Trace level Specifies the trace level for the DSC with an integer (0 - 9). 0 indicates that trace is disabled. 9 indicates the maximum trace level. The trace level setting is not a part of the cluster policy. So this setting is not replicated across the cluster and is not persistent across firmware updates. The trace messages are sent to the log file for the DSC. Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance.

Session cache reference

Use the Cluster Configuration management page to administer cluster support for the appliance.

You can view and update the current cluster session cache configuration:

Worker threads

The number of worker threads that handle the server requests. At a minimum, use a number that is greater than the maximum number of clients.

Maximum session lifetime

The maximum lifetime in seconds for each session. Use a value greater than the maximum lifetime of all clients. That is, use a value greater than the maximum [session] timeout value that the WebSEAL clients use.

For more information about the [session] timeout configuration entry, see the reference topics for the Web Reverse Stanza Proxy in the Knowledge Center.

Client grace period

The grace period in seconds that a client has available to restart and register an interest in the session again before the session is removed from the session cache. This period gives the client a chance to restart without losing the session from the server.

Use a similar value to the idle timeout value for the session on the client. That is, use a value similar to the [session] inactive-timeout value that is set in the client Web Reverse Proxy configuration.

For more information about the [session] inactive-timeout configuration entry, see the reference topics for the Web Reverse Stanza Proxy in the Knowledge Center.

Support internal clients only

Indicates that only internal clients can use the distributed session cache.

Notes:

The current version supports internal clients only.

If this option is selected, the remaining fields are disabled.

Clients can be turned off. For more information about failover events, search for the Options for handling session failover events topic in the Administering topics in the Knowledge Center. For more information about configuration properties, see Advanced configuration properties.

Support internal and external clients

Indicates that both internal and external clients can use the distributed session cache.

Note: Support for external clients is not available in the current version.

Port

The port on which external clients can communicate with the session cache. This field is mandatory if you enable support for internal and external clients.

Enable SSL

If selected, the distributed session cache uses secure communication with its clients.

Note: If you enable SSL, you must also configure the Keyfile.

Keyfile

Lists the existing keyfiles on the appliance. These keyfiles are managed from the SSL certificates page. You can click the SSL Certificates link on the right to go to that page.

Note: If you want to share the key files across the cluster, you must go to the SSL Certificates page and select the Replicate with Cluster check box.

Label

Lists the certificate labels in the selected keyfile. This field is disabled if a keyfile is not selected.

Trace level

Specifies the trace level for the DSC with an integer (0 - 9). 0 indicates that trace is disabled. 9 indicates the maximum trace level.

Note: The trace level setting is not a part of the cluster policy. So this setting is not replicated across the cluster and is not persistent across firmware updates. The trace messages are sent to the log file for the DSC.

Parent topic: Managing cluster configuration

Configuration databaseYou can view and update the current configuration database settings with the Configuration Database tab on the Cluster Configuration management page.The configuration database stores configuration data, including policy information. This data is shared with all appliances in the cluster. Local to the clusterSpecifies the use of the internal configuration database.Database exportExports the current configuration data from the internal database so that it can be imported into an external database of the chosen type. This option is useful if you want to migrate the appliance's internal configuration database to an external database. Supported external database types are DB2 and Oracle. The exported data are compressed into a zip file. A readme file is included in the zip file to provide instructions on how to import the data into the external database.The configuration database schema (table and index definitions), which is available from the File Downloads area of the appliance, must be applied to the database that will house the configuration data before the data can be imported.Remote to the clusterSpecifies the use of an external configuration database. Specify the following information for the external configuration database:Use external database for internal file sharingEnable this option to allow the configurations to be modified on non-primary nodes of the cluster.When you enable this option, the appliance will be rebooted when the change is committed. During the reboot, the files will be migrated between the local file system and the external configuration database.TypeThe database type, which is either DB2 or Oracle.AddressThe IP address or hostname of the external database server.PortThe port on which the external database server is listening.UsernameThe name of the database administrator.PasswordThe password for the database administrator.DB2SecureSelect this check box to create a secure connection with the DB2 or Oracle server. Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the DB2 or Oracle server. Use the SSL Certificates page to import the appropriate certificate.Database nameThe name of the database instance on the external DB2 server.Enable HADR and ACRSelect this checkbox to enable High Availability Disaster Recovery and Automatic Client Reroute.Alternate AddressThe IP address or hostname of the failover database server in the HADR configuration.Alternate PortThe port on which the failover database server in the HADR configuration is listening.Oracle Secure Select this check box to create a secure connection with the Oracle server.Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the Oracle server. Use the SSL Certificates page to import the appropriate certificate. Service name The name of the service instance on the external Oracle server.Driver typeSpecifies the type of Oracle JDBC driver that is used to connect to the Oracle server. Available options are Thin and OCI.Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance.

Configuration database

You can view and update the current configuration database settings with the Configuration Database tab on the Cluster Configuration management page.

The configuration database stores configuration data, including policy information. This data is shared with all appliances in the cluster.

Local to the cluster

Specifies the use of the internal configuration database.

Database export

Exports the current configuration data from the internal database so that it can be imported into an external database of the chosen type. This option is useful if you want to migrate the appliance's internal configuration database to an external database. Supported external database types are DB2 and Oracle. The exported data are compressed into a zip file. A readme file is included in the zip file to provide instructions on how to import the data into the external database.

Note: The configuration database schema (table and index definitions), which is available from the File Downloads area of the appliance, must be applied to the database that will house the configuration data before the data can be imported.

Remote to the cluster

Specifies the use of an external configuration database. Specify the following information for the external configuration database:

Use external database for internal file sharing

Enable this option to allow the configurations to be modified on non-primary nodes of the cluster.

Note: When you enable this option, the appliance will be rebooted when the change is committed. During the reboot, the files will be migrated between the local file system and the external configuration database.

Type

The database type, which is either DB2 or Oracle.

Address

The IP address or hostname of the external database server.

Port

The port on which the external database server is listening.

Username

The name of the database administrator.

Password

The password for the database administrator.

DB2

Secure

Select this check box to create a secure connection with the DB2® or Oracle server.

Note: Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the DB2 or Oracle server. Use the SSL Certificates page to import the appropriate certificate.

Database name

The name of the database instance on the external DB2 server.

Enable HADR and ACR

Select this checkbox to enable High Availability Disaster Recovery and Automatic Client Reroute.

Alternate Address

The IP address or hostname of the failover database server in the HADR configuration.

Alternate Port

The port on which the failover database server in the HADR configuration is listening.

Oracle

Secure

Select this check box to create a secure connection with the Oracle server.

Note: Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the Oracle server. Use the SSL Certificates page to import the appropriate certificate.

Service name

The name of the service instance on the external Oracle server.

Driver type

Specifies the type of Oracle JDBC driver that is used to connect to the Oracle server. Available options are Thin and OCI.

Parent topic: Managing cluster configuration

Runtime databaseRuntime databaseAccess Manager Appliance: Runtime databaseYou can view and update the current runtime database settings with the Runtime Database tab on the Cluster Configuration management page.databasesreferences databases The runtime database contains runtime data that is used by the context-based access component. You can configure this database as an embedded database or an external database. The embedded database is suitable for small environments only. For large-scale production environments, configure an external database. Local to the clusterSpecifies the use of the internal runtime database.Only the Maximum Size field relates to the internal runtime database. If you use the internal runtime database, all other fields are disabled.Maximum Size (% of available disk)The size of the internal runtime database. If you select the Local to the cluster option, this field is mandatory. The maximum size is a percentage of the remaining disk space at the time that the policy is applied. The valid value range is from 10% to 80%. If a change in this value results in a calculated maximum size, which is smaller that the current size of the database, the database must be re-created. In this case, all existing data from the database is lost.To determine the percentage of available disk space to assign to the internal database, consider the following aspects of your environment:The current disk usage on the appliance. You can view the Disk Usage on the Appliance Dashboard in the LMI.Internal disk requirements for other utilities such as logging and snapshots.Remote to the clusterSpecifies the use of an external runtime database. Specify the following information for the external runtime database:TypeThe database type, which is either DB2, solidDB, or Oracle.AddressThe IP address or hostname of the external database server.PortThe port on which the external database server is listening.UsernameThe name of the database administrator.PasswordThe password for the database administrator.DB2 SecureSelect this check box to create a secure connection with the DB2 or Oracle server. Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the DB2 or Oracle server. Use the SSL Certificates page to import the appropriate certificate.Database nameThe name of the database instance on the external DB2 server.Enable High Available Disaster Recovery and Automatic Client RerouteSelect this checkbox to enable HADR and ACR.Alternate AddressThe IP address or hostname of the failover database server in the HADR configuration.Alternate PortThe port on which the failover database server in the HADR configuration is listening. solidDB Enable Transparent ConnectivitySelect this checkbox to enable Transparent Connectivity to additional solidDB HotStandby instances.HotStandby InstancesThe IP address or hostname and listening ports of the solidDB HotStandby instances. Oracle Secure Select this check box to create a secure connection with the Oracle server.Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the Oracle server. Use the SSL Certificates page to import the appropriate certificate. Service name The name of the service instance on the external Oracle server.Driver typeSpecifies the type of Oracle JDBC driver that is used to connect to the Oracle server. Available options are Thin and OCI. Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance.

Runtime database

You can view and update the current runtime database settings with the Runtime Database tab on the Cluster Configuration management page.

The runtime database contains runtime data that is used by the context-based access component. You can configure this database as an embedded database or an external database. The embedded database is suitable for small environments only. For large-scale production environments, configure an external database.

Local to the cluster

Specifies the use of the internal runtime database.

Note: Only the Maximum Size field relates to the internal runtime database. If you use the internal runtime database, all other fields are disabled.

Maximum Size (% of available disk)

The size of the internal runtime database. If you select the Local to the cluster option, this field is mandatory. The maximum size is a percentage of the remaining disk space at the time that the policy is applied.

The valid value range is from 10% to 80%. If a change in this value results in a calculated maximum size, which is smaller that the current size of the database, the database must be re-created. In this case, all existing data from the database is lost.

To determine the percentage of available disk space to assign to the internal database, consider the following aspects of your environment:

The current disk usage on the appliance. You can view the Disk Usage on the Appliance Dashboard in the LMI.

Internal disk requirements for other utilities such as logging and snapshots.

Remote to the cluster

Specifies the use of an external runtime database. Specify the following information for the external runtime database:

Type

The database type, which is either DB2, solidDB, or Oracle.

Address

The IP address or hostname of the external database server.

Port

The port on which the external database server is listening.

Username

The name of the database administrator.

Password

The password for the database administrator.

DB2

Secure

Select this check box to create a secure connection with the DB2® or Oracle server.

Note: Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the DB2 or Oracle server. Use the SSL Certificates page to import the appropriate certificate.

Database name

The name of the database instance on the external DB2 server.

Enable High Available Disaster Recovery and Automatic Client Reroute

Select this checkbox to enable HADR and ACR.

Alternate Address

The IP address or hostname of the failover database server in the HADR configuration.

Alternate Port

The port on which the failover database server in the HADR configuration is listening.

solidDB

Enable Transparent Connectivity

Select this checkbox to enable Transparent Connectivity to additional solidDB HotStandby instances.

HotStandby Instances

The IP address or hostname and listening ports of the solidDB HotStandby instances.

Oracle

Secure

Select this check box to create a secure connection with the Oracle server.

Note: Before a secure connection can be established, you must first import the certificate for the appliance to use for communication with the Oracle server. Use the SSL Certificates page to import the appropriate certificate.

Service name

The name of the service instance on the external Oracle server.

Driver type

Specifies the type of Oracle JDBC driver that is used to connect to the Oracle server. Available options are Thin and OCI.

Parent topic: Managing cluster configuration

System settingsSystem settingsAccess Manager Appliance: System settingsInformation about managing system settings on your appliance.systemssettingssettingssystemsManage: System SettingsInformation about configuring Security, Network, and System settings of your appliance.Configuring date and time settingsUse the Date/Time Configuration page to configure the date, time, time zone, and NTP server information.Configuring administrator settingsUse the Administrator Settings management page to tune the local management interface so that it can run more efficiently.Configuring tracing for the local management interfaceUse the LMI Tracing page to configure the tracing specifications for different components of the local management interface.Configuring management authentication To configure management authentication with the local management interface, use the Management Authentication management page.Managing roles of users and groupsAssign certain roles to users and groups to control which sections of the local management interface and web services they can access.Viewing and updating management SSL certificatesView and update the management SSL certificate details in the Management SSL Certificate page of the local management interface. Managing users and groupsYou can manage administrative users and groups, change user passwords, and configure group membership with Account Management so that you can control their access. Managing advanced tuning parametersChange the advanced tuning parameter values only under the supervision of IBM software support.Managing snapshotsUse snapshots to restore prior configuration and policy settings to the appliance. Back up the appliance on a frequent basis by downloading snapshot files.Managing support filesIBM Customer Support uses support files to help you troubleshoot problems with the appliance. Support files contain all log files, temporary and intermediate files, and command output that is needed to diagnose customer support problems.Configuring system alertsConfigure where you want the system to send notifications about changes to system settings and problems with the system.Restarting or shutting down the applianceUse the Restart or Shut down page to restart or shut down the appliance.Configuring application database settingsConfigure auto updating and feedback for application databases. Application databases store classifications for web applications and websites.Setting the locale of application log filesUse the Application Locale management page to set the locale in which the application log files are written.Configuring SNMP monitoringConfigure SNMP Monitoring so that you can monitor the status of the appliance with a monitoring solution that supports Simple Network Management Protocol. You can monitor the appliance in an IBMTivoli Monitoring environment.

System settings

Information about managing system settings on your appliance.

Configuring date and time settings
Use the Date/Time Configuration page to configure the date, time, time zone, and NTP server information.

Configuring administrator settings
Use the Administrator Settings management page to tune the local management interface so that it can run more efficiently.

Configuring tracing for the local management interface
Use the LMI Tracing page to configure the tracing specifications for different components of the local management interface.

Configuring management authentication
To configure management authentication with the local management interface, use the Management Authentication management page.

Managing roles of users and groups
Assign certain roles to users and groups to control which sections of the local management interface and web services they can access.

Viewing and updating management SSL certificates
View and update the management SSL certificate details in the Management SSL Certificate page of the local management interface.

Managing users and groups
You can manage administrative users and groups, change user passwords, and configure group membership with Account Management so that you can control their access.

Managing advanced tuning parameters
Change the advanced tuning parameter values only under the supervision of IBM® software support.

Managing snapshots
Use snapshots to restore prior configuration and policy settings to the appliance. Back up the appliance on a frequent basis by downloading snapshot files.

Managing support files
IBM Customer Support uses support files to help you troubleshoot problems with the appliance. Support files contain all log files, temporary and intermediate files, and command output that is needed to diagnose customer support problems.

Configuring system alerts
Configure where you want the system to send notifications about changes to system settings and problems with the system.

Restarting or shutting down the appliance
Use the Restart or Shut down page to restart or shut down the appliance.

Configuring application database settings
Configure auto updating and feedback for application databases. Application databases store classifications for web applications and websites.

Setting the locale of application log files
Use the Application Locale management page to set the locale in which the application log files are written.

Configuring SNMP monitoring
Configure SNMP Monitoring so that you can monitor the status of the appliance with a monitoring solution that supports Simple Network Management Protocol. You can monitor the appliance in an IBMTivoli® Monitoring environment.

Parent topic: Manage: System Settings

Configuring date and time settings Configuring date and time settingsAccess Manager Appliance: Configuring date and time settingsUse the Date/Time Configuration page to configure the date, time, time zone, and NTP server information.date and timeNTP serverstime zonesClick Manage System SettingsSystem SettingsDate/Time Configure the following options:Time ZoneSpecifies the time zone for the appliance.Date/TimeSpecifies the day, month, year, and time for the appliance.NTP Server addressLists the NTP (NIST Internet Time Service) servers the appliance uses. You can enter multiple NTP servers, separated by commas. Click Save.System settingsInformation about managing system settings on your appliance.

Configuring date and time settings

Use the Date/Time Configuration page to configure the date, time, time zone, and NTP server information.

Procedure

Click Manage System Settings > System Settings > Date/Time

Configure the following options:

Option | Description
Time Zone | Specifies the time zone for the appliance.
Date/Time | Specifies the day, month, year, and time for the appliance.
NTP Server address | Lists the NTP (NIST Internet Time Service) servers the appliance uses. You can enter multiple NTP servers, separated by commas.

Click Save.

Parent topic: System settings

Configuring administrator settingsConfiguring administrator settingsUse the Administrator Settings management page to tune the local management interface so that it can run more efficiently.LMIadministrator settingspasswordschangepasswordssessionstimeoutClick Manage System SettingsSystem SettingsAdministrator Settings.The available tuning parameters are listed in a table.Modify the parameters.To edit a parameter, select the parameter from the table and click Edit. In the edit window, change the parameter value.To delete the current settings for a parameter and change its value to unset, select the parameter from the table and click Delete.The administrator password cannot be reset. For example, to configure the maximum size or maximum number of the trace.log, messages.log files, and their rollover files, modify the Maximum Log File Size or Maximum Log Files parameters. The Maximum Log File Size parameter defines the maximum size in megabytes that the log files can grow to before they are rolled over. The Maximum Log Files parameter defines the maximum number of log files and rollover files that can be kept on the system. Select Maximum Log File Size or Maximum Log Files. Click Edit.Enter the values as needed.Click OK.Deploy the changes.System settingsInformation about managing system settings on your appliance.

Configuring administrator settings

Use the Administrator Settings management page to tune the local management interface so that it can run more efficiently.

Procedure

Click Manage System Settings > System Settings > Administrator Settings. The available tuning parameters are listed in a table.

Modify the parameters.

To edit a parameter, select the parameter from the table and click Edit. In the edit window, change the parameter value.

To delete the current settings for a parameter and change its value to unset, select the parameter from the table and click Delete.

Note: The administrator password cannot be reset.

For example, to configure the maximum size or maximum number of the trace.log, messages.log files, and their rollover files, modify the Maximum Log File Size or Maximum Log Files parameters. The Maximum Log File Size parameter defines the maximum size in megabytes that the log files can grow to before they are rolled over. The Maximum Log Files parameter defines the maximum number of log files and rollover files that can be kept on the system.

Select Maximum Log File Size or Maximum Log Files.

Click Edit.

Enter the values as needed.

Click OK.

Deploy the changes.

Parent topic: System settings

Configuring tracing for the local management interfaceUse the LMI Tracing page to configure the tracing specifications for different components of the local management interface.You can now set the tracing specifications of the local management interface for debugging purposes. Changing these tracing specifications might have an adverse effect on the performance of the local management interface.Select Manage System SettingsSystem SettingsAdministrator Settings.Click LMI Tracing.The LMI tracing components and trace levels are displayed.LMI tracing componentsComponentDescriptioncom.ibm.isam.*This option enables tracing for the components of all offerings, which include the Security Access Manager Base, Advanced Access Control, and Federation offerings. com.ibm.isam.core.*This option enables tracing for the common components of all offerings. These common components are shared by the various offerings. For example, the Security Access Manager runtime and SSL certificates management. com.ibm.isam.wga.*This option enables tracing for the components of the Security Access Manager Base offering. For example, the management of reverse proxy instances. com.ibm.isam.mga.* This option enables tracing for the components of the Security Access Manager Advanced Access Control and Federation offerings. For example, the risk based analysis (RBA) configuration, the management of federations, partners, and module chains. com.ibm.mesa.*This option enables tracing for the underlying components that compose the LMI framework. These components are used both as a base for all of the offerings and to provide the management of most system settings. For example, updates and network configuration.HTTPThis option enables tracing for the components of the web application server that are involved in HTTP communication.SSLThis option enables tracing for the components of the web application server that are involved in SSL communication.JSPThis option enables tracing for the JavaServer pages components of the web application server.Servlet EngineThis option enables tracing for the servlet engine and web container components of the web application server.Session ManagementThis option enables tracing for the components of the web application server that make up the session and session management functionality.ConfigurationThis option enables tracing for the configuration of the web application server.Native SecurityThis option enables tracing for the native security components of the web application server.LMI trace levelsLevelDescriptionallAll events are logged. If you create custom levels, all includes those levels, and can provide a more detailed trace than finest.finestA more detailed trace that includes all the detail that is needed to debug problems.finerDetailed trace information.fineTrace information that includes general trace, method entry, exit, and return values.detailGeneral information that details the subtask progress.configConfiguration change or status.infoGeneral information that outlines the overall task progress.auditSignificant event that affects the server state or resources.warningPotential error or impending error. This level can also indicate a progressive failure, for example, the potential leaking of resources.severeTask cannot continue. But component, application, and server can still function. This level can also indicate an impending unrecoverable error.fatalTask cannot continue. Component, application, and server cannot function.offLogging is turned off.Define the trace specifications in either of the following methods.Select a component and trace level from the table, and then click the Add. Repeat this procedure until all trace specifications are added.Manually enter the trace specifications in the Trace Specification text area.Click Save.Deploy the changes.The local management interface is automatically restarted so that the changes can take effect.System settingsInformation about managing system settings on your appliance.

Configuring tracing for the local management interface

Use the LMI Tracing page to configure the tracing specifications for different components of the local management interface.

About this task

You can now set the tracing specifications of the local management interface for debugging purposes.

Note: Changing these tracing specifications might have an adverse effect on the performance of the local management interface.

Procedure

Select Manage System Settings > System Settings > Administrator Settings.

Click LMI Tracing. The LMI tracing components and trace levels are displayed.

Table 149. LMI tracing components

Component | Description
com.ibm.isam.* | This option enables tracing for the components of all offerings, which include the Security Access Manager Base, Advanced Access Control, and Federation offerings.
com.ibm.isam.core.* | This option enables tracing for the common components of all offerings. These common components are shared by the various offerings. For example, the Security Access Manager runtime and SSL certificates management.
com.ibm.isam.wga.* | This option enables tracing for the components of the Security Access Manager Base offering. For example, the management of reverse proxy instances.
com.ibm.isam.mga.* | This option enables tracing for the components of the Security Access Manager Advanced Access Control and Federation offerings. For example, the risk based analysis (RBA) configuration, the management of federations, partners, and module chains.
com.ibm.mesa.* | This option enables tracing for the underlying components that compose the LMI framework. These components are used both as a base for all of the offerings and to provide the management of most system settings. For example, updates and network configuration.
HTTP | This option enables tracing for the components of the web application server that are involved in HTTP communication.
SSL | This option enables tracing for the components of the web application server that are involved in SSL communication.
JSP | This option enables tracing for the JavaServer pages components of the web application server.
Servlet Engine | This option enables tracing for the servlet engine and web container components of the web application server.
Session Management | This option enables tracing for the components of the web application server that make up the session and session management functionality.
Configuration | This option enables tracing for the configuration of the web application server.
Native Security | This option enables tracing for the native security components of the web application server.

Table 150. LMI trace levels

Level | Description
all | All events are logged. If you create custom levels, all includes those levels, and can provide a more detailed trace than finest.
finest | A more detailed trace that includes all the detail that is needed to debug problems.
finer | Detailed trace information.
fine | Trace information that includes general trace, method entry, exit, and return values.
detail | General information that details the subtask progress.
config | Configuration change or status.
info | General information that outlines the overall task progress.
audit | Significant event that affects the server state or resources.
warning | Potential error or impending error. This level can also indicate a progressive failure, for example, the potential leaking of resources.
severe | Task cannot continue. But component, application, and server can still function. This level can also indicate an impending unrecoverable error.
fatal | Task cannot continue. Component, application, and server cannot function.
off | Logging is turned off.

Define the trace specifications in either of the following methods.

Select a component and trace level from the table, and then click the Add. Repeat this procedure until all trace specifications are added.

Manually enter the trace specifications in the Trace Specification text area.

Click Save.

Deploy the changes.

Note: The local management interface is automatically restarted so that the changes can take effect.

Parent topic: System settings

Configuring management authenticationConfiguring management authenticationAccess Manager Appliance: Configuring management authentication To configure management authentication with the local management interface, use the Management Authentication management page.authenticationconfigurationauthenticationmanagementauthenticationFrom the top menu, select Manage System Settings System SettingsManagement Authentication.All current management authentication settings are displayed.In the Main tab:Select Local User Database if you want to use the local user database for authentication.Select Remote LDAP User Registry if you want to use the remote LDAP user registry for authentication.If a remote user registry is configured for management authentication, the local administrator user (admin) can continue to be referenced with the admin@local user name. You can use this as a fail safe in the event that the remote user registry is not reachable.In the LDAP tab: Specify the name of the LDAP server in the Host name field.Specify the port over which to communicate with the LDAP server in the Port field.Select the Anonymous Bind check box if the LDAP user registry supports anonymous bind.Specify the DN of the user that is used to bind to the registry in the Bind DN field.Specifies the password that is associated with the bind DN in the Bind Password field.In the LDAP General tab:Specify the name of the LDAP attribute that holds the supplied authentication user name of the user in the User Attribute field. Specify the name of the LDAP attribute that is used to hold the members of a group in the Group Member Attribute field.Specify the base DN that is used to house all administrative users in the Base DN field.Specify the DN of the group to which all administrative users belong in the Administrative Group DN field.All administrative users must have permission to view the specified admin_group_dn group within the user registry.In the LDAP SSL tab:Select the Enable SSL check box to define whether SSL is used when the system communicates with the LDAP server.Select the name of the key database file in the Key File Name field.Select the name of the certificate to be used if client authentication is requested by the LDAP server in the Certificate Label field.Click Save to save your settings.For the changes to take effect, they must be deployed.Optional: Click Test to test the authentication. If there have been changes made to the management authentication configuration that have not yet been deployed, this test will run using the undeployed configuration.In the Test Authentication window, enter the user name in the Username field.Enter the password in the Password field.Click Test.If the authentication is successful, a success message is displayed. If the authentication is not successful, an error message is displayed.System settingsInformation about managing system settings on your appliance.

Configuring management authentication

To configure management authentication with the local management interface, use the Management Authentication management page.

Procedure

From the top menu, select Manage System Settings > System Settings > Management Authentication. All current management authentication settings are displayed.

In the Main tab:

Select Local User Database if you want to use the local user database for authentication.

Select Remote LDAP User Registry if you want to use the remote LDAP user registry for authentication.

Note: If a remote user registry is configured for management authentication, the local administrator user (admin) can continue to be referenced with the "admin@local" user name. You can use this as a fail safe in the event that the remote user registry is not reachable.

In the LDAP tab:

Specify the name of the LDAP server in the Host name field.

Specify the port over which to communicate with the LDAP server in the Port field.

Select the Anonymous Bind check box if the LDAP user registry supports anonymous bind.

Specify the DN of the user that is used to bind to the registry in the Bind DN field.

Specifies the password that is associated with the bind DN in the Bind Password field.

In the LDAP General tab:

Specify the name of the LDAP attribute that holds the supplied authentication user name of the user in the User Attribute field.

Specify the name of the LDAP attribute that is used to hold the members of a group in the Group Member Attribute field.

Specify the base DN that is used to house all administrative users in the Base DN field.

Specify the DN of the group to which all administrative users belong in the Administrative Group DN field.

Note: All administrative users must have permission to view the specified admin_group_dn group within the user registry.

In the LDAP SSL tab:

Select the Enable SSL check box to define whether SSL is used when the system communicates with the LDAP server.

Select the name of the key database file in the Key File Name field.

Select the name of the certificate to be used if client authentication is requested by the LDAP server in the Certificate Label field.

Click Save to save your settings.

Note: For the changes to take effect, they must be deployed.

Optional: Click Test to test the authentication.

Note: If there have been changes made to the management authentication configuration that have not yet been deployed, this test will run using the undeployed configuration.

In the Test Authentication window, enter the user name in the Username field.

Enter the password in the Password field.

Click Test.

If the authentication is successful, a success message is displayed. If the authentication is not successful, an error message is displayed.

Parent topic: System settings

Managing roles of users and groupsManaging roles of users and groupsAssign certain roles to users and groups to control which sections of the local management interface and web services they can access.rolesmanagementrolesBy default, role-based authorization is disabled on the appliance. You must first enable this function from the management interface to make use of it. With Management Authorization, you can perform the following tasks:Add or remove a role.Assign a role to groups or users in local or remote LDAP user registry.You can search for remote LDAP users or groups by entering a search pattern and clicking Search. Then, select the user or group from the search results and click Add.Edit permissions for a role.The roles for a user session are determined when a user first logs in. If the authorization configuration is modified and deployed when a user is logged in, the changes take effect immediately.You can customize the default roles to better suit your environment. You can also remove all default roles and create new ones from scratch.If you plan to use the default roles, you must carefully review these roles to ensure that they are appropriate for your environment.The authorization settings do not affect the main system account admin, which always has read and write permission to all features. The admin account can be used for recovery.Permissions can be set for all features in the appliance except for the Home: Appliance Dashboard. Any user who can authenticate can view Home: Appliance Dashboard, even if they are not assigned to any roles.To ensure complete flexibility with the role configuration, the permissions for each feature are controlled separately. Some pages in the local management interface, such as the Management Authorization page, use multiple features. As a result, users might need permissions for more than one feature to use all of the features on a particular page of the local management interface. For example, to access all of the functions on the Management Authorization page, the user needs permissions for the following features:Account ManagementManagement AuthorizationIf a user clicks a link or attempts to complete an action for which they do not have the appropriate permission, an error message is returned. The error message includes the details about which permission is required for the selected action.When you search for remote LDAP users or groups, consider the following points:Users are assumed to be contained in the Base DN and are identified based on the User Attribute that is set on the Management Authentication page.Groups are also assumed to be contained in the Base DN that is defined on the Management Authentication page.Groups are identified based on cn. Groups must be among the following types: group, groupofUniqueName, or groupOfNames.Authorization enforcement applies to the local management interface, web services, and client certificate authentication.Authorization enforcement in the local management interfaceWhen a user logs in the local management interface, the menu displays only the pages that the user has access to. When users attempt to go to a page to which they do not have access, a page is displayed that explains that the user does not have authorization to view the page. When a user views a page with read-only permission, users cannot modify the configuration or change the state of any services on the page. If a user attempts to do so, a message is displayed stating that the user does not have permission to perform the requested action.Authorization enforcement in web servicesIf a user has read-permission for a feature, they can perform GET requests against the associated Web services. If a user has write-permissions on a feature, they can issue any of the associated GET, POST, PUT, and DELETE web services. When a user attempts to issue a web service request that they are not authorized to perform, they receive a response with the HTTP status code 403 Forbidden and a message that states that they are not authorized to complete the transaction.Authorization enforcement in client certificate authenticationIf you want to use client certificates to authenticate to the local management interface, ensure that the authorization framework can map the DN of the presented client certificate to a user that exists in the registry that is used for authentication. For example, a certificate is presented with DN: cn=testUser,ou=qa,o=ibm,c=au.When you use a remote LDAP user registry for authentication, the authorization decision is made for a user that matches the entire DN in the user registry.For example, a user that matches cn=testUser,ou=qa,o=ibm,c=au is searched for in the remote LDAP user registry, and the policy that is associated with that user is enforced.When you use the local user database, the authorization decision is made for a user that matches the CN of the presented DN. For example, the user that is called testUser is searched for in the local user database, and the policy that is associated with that user is enforced.A user can be assigned multiple roles. In this case, the user receives the highest cumulative permission from these roles for each feature. For example, if they are assigned two roles and one role has read-permission for a feature but the second role has write-permission for the feature, the user is granted write-permission.The appliance caches authentication details to reduce load on the user registry. The authentication details might be used for up to 10 minutes after they are changed. This behavior can be changed by using an advanced tuning parameter. Add the advanced tuning parameter lmi.authCache.baenabled with a value of false to disable this caching. See Managing advanced tuning parametersChange the advanced tuning parameter values only under the supervision of IBM software support..A performance penalty is incurred when you use this parameter. The user registry is queried when:A user logs in the local management interface through the browser.A request to the web services API by using Basic Authentication is received.There is some degradation of performance in environments that make heavy use of the web services API by using Basic Authentication.Select Manage System SettingsSystem SettingsManagement Authorization.Under Roles, select the Enable Authorization Roles check box.Follow the prompts to complete the action you want to take.Use the quick filter to retrieve group names, user names, and features. Adding a roleIn the Roles panel on the left, click New.In the Create New Role window, enter a name for the new role.Click OK.Removing a roleIn the Roles panel on the left, select the role to delete.Click Delete.In the Removing Role window, verify that the role name to delete is correct and then click Yes.Assigning a role to local groups or usersIn the Roles panel on the left, select the role to edit membership for.In the Role Membership panel on the right, select the Local User Database tab if it is not already selected.Click Edit above the group name table or the user name table.In the Edit Local Members window, select or clear the check box on the Groups and Users tabs as needed.Click OK.Assigning a role to LDAP groups or usersIn the Roles panel on the left, select the role to edit membership for.In the Role Membership panel on the right, select the Remote LDAP User Registry tab if it is not already selected.In the Edit Remote LDAP Members window, modify LDAP groups and users on the Groups and Users tabs as needed. To add an LDAP group or user, enter the details in the text field and then click Add. To remove an LDAP group or user, select the entry and then click Delete.Click OK.Editing permissions for a roleIn the Roles panel on the left, select the role to edit permissions for.In the Features panel on the right, select the permission that you want from the drop-down list in each row. If you upgrade from a previous version of the appliance, new role membership features are set to None by default. Configure the permissions, if necessary.The displayed features reflect the features that are available in the activated offerings. If you deactivate a product, the features that are specific to that product are removed from any existing roles. If you reactivate the product in the future, these features and the associated permissions are added to the roles again. Any permissions from a prior activation are reinstantiated. If it is the first time that the product is activated, the product-specific features are added to each role with no assigned permissions. Click Save to save the permission settings.System settingsInformation about managing system settings on your appliance.

Managing roles of users and groups

Assign certain roles to users and groups to control which sections of the local management interface and web services they can access.

About this task

By default, role-based authorization is disabled on the appliance. You must first enable this function from the management interface to make use of it.

With Management Authorization, you can perform the following tasks:

Add or remove a role.

Assign a role to groups or users in local or remote LDAP user registry.

Note: You can search for remote LDAP users or groups by entering a search pattern and clicking Search. Then, select the user or group from the search results and click Add.

Edit permissions for a role.

The roles for a user session are determined when a user first logs in. If the authorization configuration is modified and deployed when a user is logged in, the changes take effect immediately.

You can customize the default roles to better suit your environment. You can also remove all default roles and create new ones from scratch.

Note: If you plan to use the default roles, you must carefully review these roles to ensure that they are appropriate for your environment.

The authorization settings do not affect the main system account admin, which always has read and write permission to all features. The admin account can be used for recovery.

Permissions can be set for all features in the appliance except for the Home: Appliance Dashboard. Any user who can authenticate can view Home: Appliance Dashboard, even if they are not assigned to any roles.

To ensure complete flexibility with the role configuration, the permissions for each feature are controlled separately. Some pages in the local management interface, such as the Management Authorization page, use multiple features. As a result, users might need permissions for more than one feature to use all of the features on a particular page of the local management interface. For example, to access all of the functions on the Management Authorization page, the user needs permissions for the following features:

Account Management

Management Authorization

If a user clicks a link or attempts to complete an action for which they do not have the appropriate permission, an error message is returned. The error message includes the details about which permission is required for the selected action.

When you search for remote LDAP users or groups, consider the following points:

Users are assumed to be contained in the Base DN and are identified based on the User Attribute that is set on the Management Authentication page.

Groups are also assumed to be contained in the Base DN that is defined on the Management Authentication page.

Groups are identified based on cn.

Groups must be among the following types: group, groupofUniqueName, or groupOfNames.

Authorization enforcement applies to the local management interface, web services, and client certificate authentication.

Authorization enforcement in the local management interface

When a user logs in the local management interface, the menu displays only the pages that the user has access to. When users attempt to go to a page to which they do not have access, a page is displayed that explains that the user does not have authorization to view the page. When a user views a page with read-only permission, users cannot modify the configuration or change the state of any services on the page. If a user attempts to do so, a message is displayed stating that the user does not have permission to perform the requested action.

Authorization enforcement in web services

If a user has read-permission for a feature, they can perform GET requests against the associated Web services. If a user has write-permissions on a feature, they can issue any of the associated GET, POST, PUT, and DELETE web services. When a user attempts to issue a web service request that they are not authorized to perform, they receive a response with the HTTP status code 403 Forbidden and a message that states that they are not authorized to complete the transaction.

Authorization enforcement in client certificate authentication

If you want to use client certificates to authenticate to the local management interface, ensure that the authorization framework can map the DN of the presented client certificate to a user that exists in the registry that is used for authentication.

For example, a certificate is presented with DN: cn=testUser,ou=qa,o=ibm,c=au.

When you use a remote LDAP user registry for authentication, the authorization decision is made for a user that matches the entire DN in the user registry.

For example, a user that matches cn=testUser,ou=qa,o=ibm,c=au is searched for in the remote LDAP user registry, and the policy that is associated with that user is enforced.

When you use the local user database, the authorization decision is made for a user that matches the CN of the presented DN. For example, the user that is called testUser is searched for in the local user database, and the policy that is associated with that user is enforced.

A user can be assigned multiple roles. In this case, the user receives the highest cumulative permission from these roles for each feature. For example, if they are assigned two roles and one role has read-permission for a feature but the second role has write-permission for the feature, the user is granted write-permission.

Note: The appliance caches authentication details to reduce load on the user registry. The authentication details might be used for up to 10 minutes after they are changed. This behavior can be changed by using an advanced tuning parameter. Add the advanced tuning parameter lmi.authCache.baenabled with a value of false to disable this caching. See Managing advanced tuning parameters.

A performance penalty is incurred when you use this parameter. The user registry is queried when:

A user logs in the local management interface through the browser.

A request to the web services API by using Basic Authentication is received.

There is some degradation of performance in environments that make heavy use of the web services API by using Basic Authentication.

Procedure

Select Manage System Settings > System Settings > Management Authorization.

Under Roles, select the Enable Authorization Roles check box.

Follow the prompts to complete the action you want to take.

Tip: Use the quick filter to retrieve group names, user names, and features.

Adding a role

In the Roles panel on the left, click New.

In the Create New Role window, enter a name for the new role.

Click OK.

Removing a role

In the Roles panel on the left, select the role to delete.

Click Delete.

In the Removing Role window, verify that the role name to delete is correct and then click Yes.

Assigning a role to local groups or users

In the Roles panel on the left, select the role to edit membership for.

In the Role Membership panel on the right, select the Local User Database tab if it is not already selected.

Click Edit above the group name table or the user name table.

In the Edit Local Members window, select or clear the check box on the Groups and Users tabs as needed.

Click OK.

Assigning a role to LDAP groups or users

In the Roles panel on the left, select the role to edit membership for.

In the Role Membership panel on the right, select the Remote LDAP User Registry tab if it is not already selected.

In the Edit Remote LDAP Members window, modify LDAP groups and users on the Groups and Users tabs as needed.

To add an LDAP group or user, enter the details in the text field and then click Add.

To remove an LDAP group or user, select the entry and then click Delete.

Click OK.

Editing permissions for a role

In the Roles panel on the left, select the role to edit permissions for.

In the Features panel on the right, select the permission that you want from the drop-down list in each row.

If you upgrade from a previous version of the appliance, new role membership features are set to None by default. Configure the permissions, if necessary.

Note: The displayed features reflect the features that are available in the activated offerings. If you deactivate a product, the features that are specific to that product are removed from any existing roles. If you reactivate the product in the future, these features and the associated permissions are added to the roles again. Any permissions from a prior activation are reinstantiated. If it is the first time that the product is activated, the product-specific features are added to each role with no assigned permissions.

Click Save to save the permission settings.

Parent topic: System settings

Viewing and updating management SSL certificatesViewing and updating management SSL certificatesAccess Manager Appliance: Viewing and updating management SSL certificatesView and update the management SSL certificate details in the Management SSL Certificate page of the local management interface. managementcertificatesSSLSSL certificatesmanagementviewing detailsupdating View the details of the current management SSL certificate From the top menu, select Manage System SettingsSystem SettingsManagement SSL Certificate.The details of the current management certificate are displayed. Update the management SSL certificate From the top menu, select Manage System SettingsSystem SettingsManagement SSL Certificate.Select Update. Under Certificate File, click Browse.Browse to the directory that contains the certificate container file and select the file.The certificate container file must be PKCS12 format (.p12 file) and can contain only a single certificate. You can generate this certificate on a server that hosts a certificate utility such as iKeyman. This certificate is used as the management SSL certificate.Click Open.Click Update. A message that indicates successful update is displayed.For the changes to take effect, they must be deployed. System settingsInformation about managing system settings on your appliance.

Viewing and updating management SSL certificates

View and update the management SSL certificate details in the Management SSL Certificate page of the local management interface.

View the details of the current management SSL certificate

From the top menu, select Manage System Settings > System Settings > Management SSL Certificate.

The details of the current management certificate are displayed.

Update the management SSL certificate

From the top menu, select Manage System Settings > System Settings > Management SSL Certificate.

Select Update.

Under Certificate File, click Browse.

Browse to the directory that contains the certificate container file and select the file.

Note: The certificate container file must be PKCS12 format (.p12 file) and can contain only a single certificate. You can generate this certificate on a server that hosts a certificate utility such as iKeyman. This certificate is used as the management SSL certificate.

Click Open.

Click Update. A message that indicates successful update is displayed.

Note: For the changes to take effect, they must be deployed.

Parent topic: System settings

Managing users and groupsYou can manage administrative users and groups, change user passwords, and configure group membership with Account Management so that you can control their access. managementusersgroupsusersgroupsaccount managementWith Account Management, you can perform the following tasks:Add or delete a user.All current users are in the Users table.You cannot change information about admin, the statically configured user.Change a user password.The first and last character of the password cannot be a space character. Any leading or trailing spaces in the password are removed.If the user is logged in, youCan also click Set Password in the top banner.Must enter the existing password before you can change it. If you change the password while logged in as the admin user, the password update is automatically deployed without the need for a manual deployment step.Create or delete a group.Add a user to or remove a user from a group.You can do this step either from the Users or Groups page.The links in the title bars switch between Users and Groups.Add or change role membership. See Managing roles of users and groupsAssign certain roles to users and groups to control which sections of the local management interface and web services they can access..The authentication cache that stores the credentials for configured users refreshes every 10 minutes by default. If you just changed a user password or deleted a user, the change might not be effective immediately. It is possible for the user to continue performing web service calls with their original credentials until the authentication cache is refreshed.From the top menu, select Manage System SettingsSystem SettingsAccount Management.Select the User or Group link. Follow the prompts to complete the action you want to take.System settingsInformation about managing system settings on your appliance.

Managing users and groups

You can manage administrative users and groups, change user passwords, and configure group membership with Account Management so that you can control their access.

About this task

With Account Management, you can perform the following tasks:

Add or delete a user.

All current users are in the Users table.

You cannot change information about admin, the statically configured user.

Change a user password.

The first and last character of the password cannot be a space character. Any leading or trailing spaces in the password are removed.

If the user is logged in, you

Can also click Set Password in the top banner.

Must enter the existing password before you can change it.

If you change the password while logged in as the admin user, the password update is automatically deployed without the need for a manual deployment step.

Create or delete a group.

Add a user to or remove a user from a group.

You can do this step either from the Users or Groups page.

The links in the title bars switch between Users and Groups.

Add or change role membership. See Managing roles of users and groups.

Note: The authentication cache that stores the credentials for configured users refreshes every 10 minutes by default. If you just changed a user password or deleted a user, the change might not be effective immediately. It is possible for the user to continue performing web service calls with their original credentials until the authentication cache is refreshed.

Procedure

From the top menu, select Manage System Settings > System Settings > Account Management.

Select the User or Group link.

Follow the prompts to complete the action you want to take.

Parent topic: System settings

Managing advanced tuning parametersManaging advanced tuning parametersAccess Manager Appliance: Managing advanced tuning parametersChange the advanced tuning parameter values only under the supervision of IBM software support.advanced tuningnist.sp800-131a.strictgw_net.tuning.downdelaygw_net.tuning.miimongw_net.tuning.updelaygw_net.tuning.use_carriergw_net.tuning.xmit_hash_policyIn the local management interface, select Manage System SettingsSystem SettingsAdvanced Tuning Parameters. The following table lists the advanced tuning parameters available.Advanced tuning parametersParameterValueDescriptionnist.sp800-131a.strictThe default value is false.Specifies whether nist.sp800-131a.strict mode is enabled.A value of true causes you to lose access to the appliance local management interface if your browser does not support TLS 1.2.gw_net.tuning.downdelayThe default value is 0.Specifies the time, in milliseconds, to wait before disabling a slave after a link failure is detected. The gw_net.tuning.downdelay value must be a multiple of the gw_net.tuning.miimon value; if not, it is rounded down to the nearest multiple. If your switches take a long time to go into backup mode, it might not be desirable to activate a backup interface immediately after a link goes down. It is possible to delay the moment at which a link is disabled by passing the module parameter downdelay.gw_net.tuning.miimonThe default value is 100.Specifies the MII link monitoring frequency in milliseconds. High availability is achieved by using MII status reporting. The bonding driver can regularly check all its slaves links by checking the MII status registers. This parameter determines how often the link state of each slave is inspected for link failures. A value of 0 disables MII link monitoring. A value of 100 is typically a suitable value. It means that a dead link will be detected 100 milliseconds at most after it goes down. The value must not come to close to 1000/HZ (10 ms on i386) because such setting might reduce the system interactivity.gw_net.tuning.updelayThe default value is 0.Specifies the time, in milliseconds, to wait before enabling a slave after a link recovery is detected. The gw_net.tuning.updelay value must be a multiple of the gw_net.tuning.miimon value; if not, it is rounded down to the nearest multiple. When a switch restarts, it is possible that its ports report "link up" status before they become usable. This behavior might cause a bond device to use some ports that are not ready yet. It is possible to delay the moment at which an active link is reused by passing the module parameter gw_net.tuning.updelay (in milliseconds, must be a multiple of gw_net.tuning.miimon). A similar situation can occur when a host renegotiates a lost link with the switch (in case of cable replacement). A special case is when a bonding interface loses all slave links. Then, the driver immediately reuses the first link that goes up, even if gw_net.tuning.updelay parameter was specified. If there are slave interfaces in the gw_net.tuning.updelay state, the interface that first went into that state is immediately reused. This setting reduces downtime if the value of gw_net.tuning.updelay was overestimated.gw_net.tuning.use_carrier0, 1(default)Specifies whether gw_net.tuning.miimon uses MII / ETHTOOL ioctls, or netif_carrier_ok() to determine the link status. The MII / ETHTOOL ioctls are less efficient and use a deprecated calling sequence within the kernel. The netif_carrier_ok() relies on the device driver to maintain its state with netif_carrier_on/off. Most, but not all, device drivers support this facility. If bonding insists that the link is up when it cannot be, the cause might be that your network device driver does not support netif_carrier_on/off. The default state for netif_carrier is "carrier on". So if a driver does not support netif_carrier, it appears as if the link is always up. In this case, setting gw_net.tuning.use_carrier to 0 causes bonding to revert to the MII / ETHTOOL ioctls method to determine the link state. A value of 1 enables the use of netif_carrier_ok(). A value of 0 specifies to use the deprecated MII / ETHTOOL ioctls. The default value is 1.gw_net.tuning.xmit_hash_policylayer2 (default), layer2+3, layer3+4Selects the transmit hash policy to use for slave selection in balance-xor, 802.3ad, and tlb modes. Here are the possible values: layer2Uses XOR of hardware MAC addresses and packet type ID field to generate the hash. The formula is as follows: hash = source MAC XOR destination MAC XOR packet type ID slave number = hash modulo slave count This algorithm places all traffic to a particular network peer on the same slave. This algorithm is 802.3ad compliant. layer2+3 This policy uses a combination of layer2 and layer3 protocol information to generate the hash. It uses XOR of hardware MAC addresses and IP addresses to generate the hash. The formula is as follows: hash = source MAC XOR destination MAC XOR packet type ID hash = hash XOR source IP XOR destination IP hash = hash XOR (hash RSHIFT 16) hash = hash XOR (hash RSHIFT 8) hash = hash Modulo (bonding_slave_count) If the protocol is IPv6, then the source and destination addresses are first hashed by using ipv6_addr_hash. This algorithm places all traffic to a particular network peer on the same slave. For non-IP traffic, the formula is the same as for the layer2 transmit hash policy. This policy is intended to provide a more balanced distribution of traffic than layer2 alone, especially in environments where a layer3 gateway device is required to reach most destinations. This algorithm is 802.3ad compliant. layer3+4This policy uses upper layer protocol information, when available, to generate the hash. This allows for traffic to a particular network peer to span multiple slaves, although a single connection does not span multiple slaves. The formula for unfragmented TCP and UDP packets is: hash = source port, destination port (as in the header) hash = hash XOR source IP XOR destination IP hash = hash XOR (hash RSHIFT 16) hash = hash XOR (hash RSHIFT 8)hash = hash Modulo (bonding_slave_count) If the protocol is IPv6, then the source and destination addresses are first hashed by using ipv6_addr_hash. For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol traffic, the source and destination port information is omitted. For non-IP traffic, the formula is the same as for the layer2 transmit hash policy. This algorithm is not fully 802.3ad compliant. A single TCP or UDP conversation that contains both fragmented and unfragmented packets causes packets to be striped across two interfaces. This situation might result in out of order delivery. Most traffic types do not meet this criteria, as TCP rarely fragments traffic, and most UDP traffic is not involved in extended conversations. Other implementations of 802.3ad might or might not tolerate this noncompliance. System settingsInformation about managing system settings on your appliance.

Managing advanced tuning parameters

Change the advanced tuning parameter values only under the supervision of IBM® software support.

In the local management interface, select Manage System Settings > System Settings > Advanced Tuning Parameters. The following table lists the advanced tuning parameters available.

Table 151. Advanced tuning parameters

Parameter
Value
Description

nist.sp800-131a.strict
The default value is false.
Specifies whether nist.sp800-131a.strict mode is enabled.

CAUTION:

A value of true causes you to lose access to the appliance local management interface if your browser does not support TLS 1.2.

gw_net.tuning.downdelay
The default value is 0.

Specifies the time, in milliseconds, to wait before disabling a slave after a link failure is detected.

The gw_net.tuning.downdelay value must be a multiple of the gw_net.tuning.miimon value; if not, it is rounded down to the nearest multiple.

If your switches take a long time to go into backup mode, it might not be desirable to activate a backup interface immediately after a link goes down. It is possible to delay the moment at which a link is disabled by passing the module parameter downdelay.

gw_net.tuning.miimon
The default value is 100.

Specifies the MII link monitoring frequency in milliseconds.

High availability is achieved by using MII status reporting. The bonding driver can regularly check all its slaves links by checking the MII status registers. This parameter determines how often the link state of each slave is inspected for link failures.

A value of 0 disables MII link monitoring. A value of 100 is typically a suitable value. It means that a dead link will be detected 100 milliseconds at most after it goes down. The value must not come to close to 1000/HZ (10 ms on i386) because such setting might reduce the system interactivity.

gw_net.tuning.updelay
The default value is 0.

Specifies the time, in milliseconds, to wait before enabling a slave after a link recovery is detected.

The gw_net.tuning.updelay value must be a multiple of the gw_net.tuning.miimon value; if not, it is rounded down to the nearest multiple.

When a switch restarts, it is possible that its ports report "link up" status before they become usable. This behavior might cause a bond device to use some ports that are not ready yet. It is possible to delay the moment at which an active link is reused by passing the module parameter gw_net.tuning.updelay (in milliseconds, must be a multiple of gw_net.tuning.miimon).

A similar situation can occur when a host renegotiates a lost link with the switch (in case of cable replacement).

A special case is when a bonding interface loses all slave links. Then, the driver immediately reuses the first link that goes up, even if gw_net.tuning.updelay parameter was specified. If there are slave interfaces in the gw_net.tuning.updelay state, the interface that first went into that state is immediately reused. This setting reduces downtime if the value of gw_net.tuning.updelay was overestimated.

gw_net.tuning.use_carrier
0, 1(default)

Specifies whether gw_net.tuning.miimon uses MII / ETHTOOL ioctls, or netif_carrier_ok() to determine the link status. The MII / ETHTOOL ioctls are less efficient and use a deprecated calling sequence within the kernel. The netif_carrier_ok() relies on the device driver to maintain its state with netif_carrier_on/off. Most, but not all, device drivers support this facility.

If bonding insists that the link is up when it cannot be, the cause might be that your network device driver does not support netif_carrier_on/off. The default state for netif_carrier is "carrier on". So if a driver does not support netif_carrier, it appears as if the link is always up. In this case, setting gw_net.tuning.use_carrier to 0 causes bonding to revert to the MII / ETHTOOL ioctls method to determine the link state.

A value of 1 enables the use of netif_carrier_ok(). A value of 0 specifies to use the deprecated MII / ETHTOOL ioctls. The default value is 1.

gw_net.tuning.xmit_hash_policy
layer2 (default), layer2+3, layer3+4

Selects the transmit hash policy to use for slave selection in balance-xor, 802.3ad, and tlb modes. Here are the possible values:

layer2

Uses XOR of hardware MAC addresses and packet type ID field to generate the hash. The formula is as follows:

hash = source MAC XOR destination MAC XOR packet type ID

slave number = hash modulo slave count

This algorithm places all traffic to a particular network peer on the same slave.

This algorithm is 802.3ad compliant.

layer2+3

This policy uses a combination of layer2 and layer3 protocol information to generate the hash. It uses XOR of hardware MAC addresses and IP addresses to generate the hash. The formula is as follows:

hash = source MAC XOR destination MAC XOR packet type ID

hash = hash XOR source IP XOR destination IP

hash = hash XOR (hash RSHIFT 16)

hash = hash XOR (hash RSHIFT 8)

hash = hash Modulo (bonding_slave_count)

If the protocol is IPv6, then the source and destination addresses are first hashed by using ipv6_addr_hash.

This algorithm places all traffic to a particular network peer on the same slave. For non-IP traffic, the formula is the same as for the layer2 transmit hash policy.

This policy is intended to provide a more balanced distribution of traffic than layer2 alone, especially in environments where a layer3 gateway device is required to reach most destinations.

This algorithm is 802.3ad compliant.

layer3+4

This policy uses upper layer protocol information, when available, to generate the hash. This allows for traffic to a particular network peer to span multiple slaves, although a single connection does not span multiple slaves.

The formula for unfragmented TCP and UDP packets is:

hash = source port, destination port (as in the header)

hash = hash XOR source IP XOR destination IP

hash = hash XOR (hash RSHIFT 16)

hash = hash XOR (hash RSHIFT 8)

hash = hash Modulo (bonding_slave_count)

If the protocol is IPv6, then the source and destination addresses are first hashed by using ipv6_addr_hash.

For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol traffic, the source and destination port information is omitted. For non-IP traffic, the formula is the same as for the layer2 transmit hash policy.

This algorithm is not fully 802.3ad compliant. A single TCP or UDP conversation that contains both fragmented and unfragmented packets causes packets to be striped across two interfaces. This situation might result in out of order delivery. Most traffic types do not meet this criteria, as TCP rarely fragments traffic, and most UDP traffic is not involved in extended conversations. Other implementations of 802.3ad might or might not tolerate this noncompliance.

Parent topic: System settings

Managing snapshotsManaging snapshotsAccess Manager Appliance: Managing snapshotsUse snapshots to restore prior configuration and policy settings to the appliance. Back up the appliance on a frequent basis by downloading snapshot files.settingspolicyconfigurationsnapshotssnapshotsSnapshots are stored on the appliance. However, you can download snapshots to an external drive in case of system failure. An appliance snapshot can be restored on any appliance that has the same firmware level as the snapshot and the same network infrastructure. If these conditions are met, the appliance type (virtual or hardware) does not matter. Do not restore a snapshot to a system (even the same system) that is running on a different firmware level. The snapshot files do not contain the internal user registry data. Use standard LDAP back-up tools, using port 636 on the appliance, to back-up and restore the data associated with the internal user registry. Click Manage System SettingsSystem SettingsSnapshots.In the Snapshots pane, use one or more of the following commands:NewTo create a snapshot, click New, type a comment that describes the snapshot, and then click Save.EditTo edit the comment for a snapshot, select the snapshot, click Edit, type a new comment, and then click Save.DeleteTo delete snapshots, select one or more snapshots, and then click Delete.ApplyTo apply a snapshot, select the snapshot, and then click Apply.If configuration or policy versions are newer than the firmware version, the settings are rejected. If the configuration and policy versions are older than the firmware version, the settings are migrated to the current firmware version.DownloadTo download a snapshot, select the snapshot, click Download, browse to the drive where you want to save the snapshot, and then click Save.If you download multiple snapshots, the snapshots are compressed into a .zip file.UploadTo upload snapshots, click Upload, browse to the snapshots you want to upload and select the snapshots. Wait for the Comment field of the Upload Snapshot window to be populated automatically. When the Comment field is populated, click Save Configuration.You can upload only one snapshot at a time.RefreshTo refresh the list of snapshots, click Refresh.System settingsInformation about managing system settings on your appliance.

Managing snapshots

Use snapshots to restore prior configuration and policy settings to the appliance. Back up the appliance on a frequent basis by downloading snapshot files.

About this task

Snapshots are stored on the appliance. However, you can download snapshots to an external drive in case of system failure.

An appliance snapshot can be restored on any appliance that has the same firmware level as the snapshot and the same network infrastructure. If these conditions are met, the appliance type (virtual or hardware) does not matter. Do not restore a snapshot to a system (even the same system) that is running on a different firmware level.

Note: The snapshot files do not contain the internal user registry data. Use standard LDAP back-up tools, using port 636 on the appliance, to back-up and restore the data associated with the internal user registry.

Procedure

Click Manage System Settings > System Settings > Snapshots.

In the Snapshots pane, use one or more of the following commands:

Option
Description

New
To create a snapshot, click New, type a comment that describes the snapshot, and then click Save.

Edit
To edit the comment for a snapshot, select the snapshot, click Edit, type a new comment, and then click Save.

Delete
To delete snapshots, select one or more snapshots, and then click Delete.

Apply
To apply a snapshot, select the snapshot, and then click Apply.

Note: If configuration or policy versions are newer than the firmware version, the settings are rejected. If the configuration and policy versions are older than the firmware version, the settings are migrated to the current firmware version.

Download
To download a snapshot, select the snapshot, click Download, browse to the drive where you want to save the snapshot, and then click Save.

Note: If you download multiple snapshots, the snapshots are compressed into a .zip file.

Upload
To upload snapshots, click Upload, browse to the snapshots you want to upload and select the snapshots. Wait for the Comment field of the Upload Snapshot window to be populated automatically. When the Comment field is populated, click Save Configuration.

Note: You can upload only one snapshot at a time.

Refresh
To refresh the list of snapshots, click Refresh.

Parent topic: System settings

Managing support filesManaging support filesAccess Manager Appliance: Managing support filesIBM Customer Support uses support files to help you troubleshoot problems with the appliance. Support files contain all log files, temporary and intermediate files, and command output that is needed to diagnose customer support problems.logsfilestemporary filesintermediate filestroubleshooting support filesdiagnosticssupport filessupportfilesfilesSupport files might contain customer-identifiable information, such as IP addresses, host names, user names, and policy files. Support files might also contain confidential information, such as passwords, certificates, and keys. The support file contents are stored as a .zip file. All files inside the support file can be inspected and censored by the customer.You can create multiple support files to track an issue over time.Click Manage System SettingsSystem SettingsSupport Files.In the Support Files pane, use one or more of the following commands:NewTo create a support file, click New, type a comment that describes the support file, and then click Save. A new support file is created on the appliance.EditTo edit the comment for a support file, select the support file, click Edit, type a new comment, and then click Save.DeleteTo delete a support file, select the support file, and then click Delete.DownloadTo download support files, select the support files, click Download, browse to the drive where you want to save the support files, and then click Save.If you download multiple support files, the files are compressed into a .zip file.System settingsInformation about managing system settings on your appliance.

Managing support files

IBM® Customer Support uses support files to help you troubleshoot problems with the appliance. Support files contain all log files, temporary and intermediate files, and command output that is needed to diagnose customer support problems.

About this task

Support files might contain customer-identifiable information, such as IP addresses, host names, user names, and policy files. Support files might also contain confidential information, such as passwords, certificates, and keys. The support file contents are stored as a .zip file. All files inside the support file can be inspected and censored by the customer.

Tip: You can create multiple support files to track an issue over time.

Procedure

Click Manage System Settings > System Settings > Support Files.

In the Support Files pane, use one or more of the following commands:

Option
Description

New
To create a support file, click New, type a comment that describes the support file, and then click Save. A new support file is created on the appliance.

Edit
To edit the comment for a support file, select the support file, click Edit, type a new comment, and then click Save.

Delete
To delete a support file, select the support file, and then click Delete.

Download
To download support files, select the support files, click Download, browse to the drive where you want to save the support files, and then click Save.

Note: If you download multiple support files, the files are compressed into a .zip file.

Parent topic: System settings

Configuring system alertsConfiguring system alertsAccess Manager Appliance: Configuring system alertsConfigure where you want the system to send notifications about changes to system settings and problems with the system.systemsalertsconfigurationsystem alertsAvailable alerts include system alerts pre-defined in the system and any alert objects that you created.Click Manage System SettingsSystem SettingsSystem Alerts.In the System Alerts pane, complete one or more of the following tasks:To receive notifications for problems with the system, select one or more system alert objects from the Available Objects pane, and add them.To create or edit alert objects, see these related topics to configure one or more of the following alert objects:Configuring email alert objectsYou can create email alert objects to send an email notification to specified users or to administrators when specified events occur on your network. You can also select the event parameters to include in the message so that important information about detected events is provided. Configuring remote syslog alert objectsConfigure remote syslog alert objects to enable the system to record system events in a remote log file.Configuring SNMP alert objectsConfigure SNMP alert objects to enable the system to send system alerts to an SNMP Manager.To delete a system alert, select the alert and then click Delete.System settingsInformation about managing system settings on your appliance.Configuring SNMP alert objectsConfigure SNMP alert objects to enable the system to send system alerts to an SNMP Manager.Configuring email alert objectsYou can create email alert objects to send an email notification to specified users or to administrators when specified events occur on your network. You can also select the event parameters to include in the message so that important information about detected events is provided. Configuring remote syslog alert objectsConfigure remote syslog alert objects to enable the system to record system events in a remote log file.

Configuring system alerts

Configure where you want the system to send notifications about changes to system settings and problems with the system.

About this task

Available alerts include system alerts pre-defined in the system and any alert objects that you created.

Procedure

Click Manage System Settings > System Settings > System Alerts.

In the System Alerts pane, complete one or more of the following tasks:

To receive notifications for problems with the system, select one or more system alert objects from the Available Objects pane, and add them.

To create or edit alert objects, see these related topics to configure one or more of the following alert objects:

Configuring email alert objects

Configuring remote syslog alert objects

Configuring SNMP alert objects

To delete a system alert, select the alert and then click Delete.

Configuring SNMP alert objects
Configure SNMP alert objects to enable the system to send system alerts to an SNMP Manager.

Configuring email alert objects
You can create email alert objects to send an email notification to specified users or to administrators when specified events occur on your network. You can also select the event parameters to include in the message so that important information about detected events is provided.

Configuring remote syslog alert objects
Configure remote syslog alert objects to enable the system to record system events in a remote log file.

Parent topic: System settings

Configuring SNMP alert objectsConfiguring SNMP alert objectsAccess Manager Appliance: Configuring SNMP alert objectsConfigure SNMP alert objects to enable the system to send system alerts to an SNMP Manager.response objectsSNMPsimple network management protocol (SNMP)alertsSNMPnotificationsClick Manage System SettingsSystem SettingsSystem Alerts.In the System Alerts page, take one of the following actions:Click NewSNMP.Select an existing object, and then click Edit.Type a name for the alert object.Select a trap version from the list.In the SNMP Manager box, type the IP address, host name, or fully qualified domain name (FQDN) of the SNMP manager.The SNMP host must be accessible to the appliance to send SNMP traps.Type the port number that the SNMP manager monitors for notifications. The default port number is 162.Type a comment to describe the SNMP alert object.For trap versions V1 or V2c, type the name of the community that is used to authenticate with the SNMP agent.For trap version 3, configure the following options:NameType the user name to be authenticated in the SNMP database.Notification TypeOn the Notification Type tab, select Inform or Trap in the SNMP Trap Version field. AuthenticationOn the Authentication and Privacy tab, select Enabled to enable authentication, type the authentication passphrase, and then select an authentication type.PrivacySelect Enabled to enable privacy, type the privacy passphrase, and then select a privacy type.Click Save.Configuring system alertsConfigure where you want the system to send notifications about changes to system settings and problems with the system.

Configuring SNMP alert objects

Configure SNMP alert objects to enable the system to send system alerts to an SNMP Manager.

Procedure

Click Manage System Settings > System Settings > System Alerts.

In the System Alerts page, take one of the following actions:

Click New > SNMP.

Select an existing object, and then click Edit.

Type a name for the alert object.

Select a trap version from the list.

In the SNMP Manager box, type the IP address, host name, or fully qualified domain name (FQDN) of the SNMP manager.

Note: The SNMP host must be accessible to the appliance to send SNMP traps.

Type the port number that the SNMP manager monitors for notifications.

Note: The default port number is 162.

Type a comment to describe the SNMP alert object.

For trap versions V1 or V2c, type the name of the community that is used to authenticate with the SNMP agent.

For trap version 3, configure the following options:

Option | Description
Name | Type the user name to be authenticated in the SNMP database.
Notification Type | On the Notification Type tab, select Inform or Trap in the SNMP Trap Version field.
Authentication | On the Authentication and Privacy tab, select Enabled to enable authentication, type the authentication passphrase, and then select an authentication type.
Privacy | Select Enabled to enable privacy, type the privacy passphrase, and then select a privacy type.

Click Save.

Parent topic: Configuring system alerts

Configuring email alert objectsConfiguring email alert objectsAccess Manager Appliance: Configuring email alert objectsYou can create email alert objects to send an email notification to specified users or to administrators when specified events occur on your network. You can also select the event parameters to include in the message so that important information about detected events is provided. response objectsemailsemail response objectsalertsemailsnotificationsobjectsemail alertsClick Manage System SettingsSystem SettingsSystem Alerts.In System Alerts page, take one of the following actions:Click NewEmail.Select an existing object, and then click Edit.Configure the following options:NameSpecifies a meaningful name for the response. This name displays when you select responses for events, so give the response a name that allows users to easily identify what they are selecting.FromSpecifies the email address that displays in the From field of the alert email.ToSpecifies the email address or group of addresses to receive the alert.Separate individual email addresses with a comma or semicolon.SMTP ServerSpecifies the fully qualified domain name or IP address of the mail server. The SMTP server must be accessible to the appliance to send email notifications.SMTP PortSpecifies the custom port that is used to connect to the SMTP server. The default is 25. CommentType a comment to identify the email alert object.Click Save.Configuring system alertsConfigure where you want the system to send notifications about changes to system settings and problems with the system.

Configuring email alert objects

You can create email alert objects to send an email notification to specified users or to administrators when specified events occur on your network. You can also select the event parameters to include in the message so that important information about detected events is provided.

Procedure

Click Manage System Settings > System Settings > System Alerts.

In System Alerts page, take one of the following actions:

Click New > Email.

Select an existing object, and then click Edit.

Configure the following options:

Option
Description

Name
Specifies a meaningful name for the response.

Note: This name displays when you select responses for events, so give the response a name that allows users to easily identify what they are selecting.

From
Specifies the email address that displays in the From field of the alert email.

To
Specifies the email address or group of addresses to receive the alert.

Note: Separate individual email addresses with a comma or semicolon.

SMTP Server
Specifies the fully qualified domain name or IP address of the mail server.

Note: The SMTP server must be accessible to the appliance to send email notifications.

SMTP Port
Specifies the custom port that is used to connect to the SMTP server. The default is 25.

Comment
Type a comment to identify the email alert object.

Click Save.

Parent topic: Configuring system alerts

Configuring remote syslog alert objectsConfiguring remote syslog alert objectsAccess Manager Appliance: Configuring remote syslog alert objectsConfigure remote syslog alert objects to enable the system to record system events in a remote log file.response objectslogslogsresponse objectsalertsremote syslogobjectslog alertslogsfilessyslogClick Manage System SettingsSystem SettingsSystem Alerts.In the System Alerts page, do one of the following steps:Click NewRemote Syslog.Select an existing remote syslog alert object, and then click Edit.Configure the following options:NameSpecifies a meaningful name for the response. Remote Syslog CollectorSpecifies the fully qualified domain name or IP address of the host on which you want to save the log. The host must be accessible to the appliance.Remote Syslog Collector PortSpecifies the custom port that is used to connect to the syslog collector. The default is 514. CommentType a comment to identify the remote syslog alert object.Click Save.Configuring system alertsConfigure where you want the system to send notifications about changes to system settings and problems with the system.

Configuring remote syslog alert objects

Configure remote syslog alert objects to enable the system to record system events in a remote log file.

Procedure

Click Manage System Settings > System Settings > System Alerts.

In the System Alerts page, do one of the following steps:

Click New > Remote Syslog.

Select an existing remote syslog alert object, and then click Edit.

Configure the following options:

Option
Description

Name
Specifies a meaningful name for the response.

Remote Syslog Collector
Specifies the fully qualified domain name or IP address of the host on which you want to save the log.

Note: The host must be accessible to the appliance.

Remote Syslog Collector Port
Specifies the custom port that is used to connect to the syslog collector. The default is 514.

Comment
Type a comment to identify the remote syslog alert object.

Click Save.

Parent topic: Configuring system alerts

Restarting or shutting down the applianceRestarting or shutting down the applianceAccess Manager Appliance: Restarting or shutting down the applianceUse the Restart or Shut down page to restart or shut down the appliance.restartingshutting downofflineWhen the appliance is restarting or shutting down, traffic is not passed through the appliance and your network might not be protected.Click Manage System SettingsSystem SettingsRestart or Shut downPerform one of the following tasks:Click Restart to restart the applianceRestarting the appliance takes it offline for several minutes.Click Shut down to turn off the applianceShutting down the appliance takes it offline and makes it inaccessible over the network until you restart it.Click Yes.System settingsInformation about managing system settings on your appliance.

Restarting or shutting down the appliance

Use the Restart or Shut down page to restart or shut down the appliance.

About this task

Important: When the appliance is restarting or shutting down, traffic is not passed through the appliance and your network might not be protected.

Procedure

Click Manage System Settings > System Settings > Restart or Shut down

Perform one of the following tasks:

Option | Description
Click Restart to restart the appliance | Restarting the appliance takes it offline for several minutes.
Click Shut down to turn off the appliance | Shutting down the appliance takes it offline and makes it inaccessible over the network until you restart it.

Click Yes.

Parent topic: System settings

Configuring application database settingsConfiguring application database settingsAccess Manager Appliance: Configuring application database settingsConfigure auto updating and feedback for application databases. Application databases store classifications for web applications and websites.applicationsdatabasesURL categorizationupdatesapplication databasesauto updatingauto updatingTo receive updates to application and IP reputation databases, you must enable auto updating. You cannot manually update application and IP reputation databases.Click Manage System SettingsUpdates and LicensingApplication Database Settings.Enable or disable the following options for updating application databases:Auto UpdateEnable FeedbackThe system classifies a URL as unknown if it is not listed in the application database. Enable the Feedback option to submit unknown URLs and statistics about web application matching to IBM. IBM will classify unknown URLs and include them in a subsequent database update. IBM uses statistics about matched web applications and actions to continuously improve the classification quality and match ratio for web applications. Feedback data does not include any personal or confidential information about your network.Enable or disable the following options for the IP reputation database:Auto UpdateEnable FeedbackEnable the feedback option to submit statistical data to IBM that can make your IP reputation classifications more accurate. This data does not include any personal or confidential information about your network.Include IP reputation infoEnable inclusion of IP reputation information in the security events. When disabled, the appliance does not perform IP reputation lookup for security events.If you use a proxy server, configure the following proxy settings:Use ProxyEnables the appliance to use a proxy server for application databases.Server AddressThe IP address or DNS name of the proxy server.The Server Address field is displayed when you select the Use Proxy check box.PortThe port number that the proxy server uses to communicate with the update server.The Port field is displayed when you select the Use Proxy check box.Use AuthenticationEnables the appliance to authenticate to a proxy server.User Name User name required for authenticating to the proxy server.The User Name field is displayed when you select the Use Authentication check box.PasswordPassword required for authenticating to the proxy server.The Password field is displayed when you select the Use Authentication check box.System settingsInformation about managing system settings on your appliance.

Configuring application database settings

Configure auto updating and feedback for application databases. Application databases store classifications for web applications and websites.

About this task

To receive updates to application and IP reputation databases, you must enable auto updating. You cannot manually update application and IP reputation databases.

Procedure

Click Manage System Settings > Updates and Licensing > Application Database Settings.

Enable or disable the following options for updating application databases:

Auto Update

Enable Feedback

The system classifies a URL as unknown if it is not listed in the application database. Enable the Feedback option to submit unknown URLs and statistics about web application matching to IBM®. IBM will classify unknown URLs and include them in a subsequent database update.

IBM uses statistics about matched web applications and actions to continuously improve the classification quality and match ratio for web applications. Feedback data does not include any personal or confidential information about your network.

Enable or disable the following options for the IP reputation database:

Auto Update

Enable Feedback

Enable the feedback option to submit statistical data to IBM that can make your IP reputation classifications more accurate. This data does not include any personal or confidential information about your network.

Include IP reputation info

Enable inclusion of IP reputation information in the security events. When disabled, the appliance does not perform IP reputation lookup for security events.

Optional: If you use a proxy server, configure the following proxy settings:

Option
Description

Use Proxy
Enables the appliance to use a proxy server for application databases.

Server Address
The IP address or DNS name of the proxy server.

Note: The Server Address field is displayed when you select the Use Proxy check box.

Port
The port number that the proxy server uses to communicate with the update server.

Note: The Port field is displayed when you select the Use Proxy check box.

Use Authentication
Enables the appliance to authenticate to a proxy server.

User Name
User name required for authenticating to the proxy server.

Note: The User Name field is displayed when you select the Use Authentication check box.

Password
Password required for authenticating to the proxy server.

Note: The Password field is displayed when you select the Use Authentication check box.

Parent topic: System settings

Setting the locale of application log filesSetting the locale of application log filesAccess Manager Appliance: Setting the locale of application log filesUse the Application Locale management page to set the locale in which the application log files are written.applicationslocalelogslogsfilesFrom the top menu, select Manage System SettingsSystem SettingsApplication Locale.Select the language that you want the application log files to be written in.Click Save.System settingsInformation about managing system settings on your appliance.

Setting the locale of application log files

Use the Application Locale management page to set the locale in which the application log files are written.

Procedure

From the top menu, select Manage System Settings > System Settings > Application Locale.

Select the language that you want the application log files to be written in.

Click Save.

Parent topic: System settings

Configuring SNMP monitoringConfiguring SNMP monitoringIBM Security Access Manager appliance: Configuring SNMP monitoringConfigure SNMP Monitoring so that you can monitor the status of the appliance with a monitoring solution that supports Simple Network Management Protocol. You can monitor the appliance in an IBMTivoli Monitoring environment.SNMPconfiguringUse the Agentless Monitoring for Linux OS agent to monitor the appliance with IBM Tivoli Monitoring.For more information about configuring the IBM Tivoli Monitoring environment and the Agentless Monitoring for Linux OS agent, see the IBM Tivoli Monitoring Knowledge Center.The following management information bases, or MIBs, are used by the SNMP agent:SNMPv2-MIB TCP-MIB SNMPv2-SMI UDP-MIB SNMP-FRAMEWORK-MIB HOST-RESOURCES-MIB SNMP-MPD-MIB MTA-MIB SNMP-TARGET-MIB DISMAN-EVENT-MIB SNMP-USER-BASED-SM-MIB NOTIFICATION-LOG-MIB SNMP-VIEW-BASED-ACM-MIB UCD-SNMP-MIB IF-MIB UCD-DLMOD-MIB IP-MIB UCD-DISKIO-MIB IPV6-MIB UCD-SNMP-MIB IP-FORWARD-MIB NET-SNMP-AGENT-MIB NET-SNMP-VACM-MIBFrom the top menu, select Manage System SettingsSystem SettingsSNMP Monitoring.Type the port number that the SNMP agent must listen on in the Port field.The default port number is 161.Select the SNMP Protocol that the agent must use. SNMPv1/SNMPv2cType the name of the community that the SNMP uses to authenticate with the SNMP agent.SNMPv3Configure the following options to describe the user who accesses the SNMP agent.Security LevelSelect the security level of the user.User NameType the name of the user who accesses the SNMP agent.Auth ProtocolSelect the authentication protocol to use.Auth PasswordType the password to use for authentication.Confirm Auth PasswordType the password to use for authentication.Priv ProtocolSelect the privacy protocol to use.Priv PasswordType the password to be used as a privacy passphrase.Confirm Priv PasswordType the password to be used as a privacy passphrase.Click Save.System settingsInformation about managing system settings on your appliance.

Configuring SNMP monitoring

Configure SNMP Monitoring so that you can monitor the status of the appliance with a monitoring solution that supports Simple Network Management Protocol. You can monitor the appliance in an IBM®Tivoli® Monitoring environment.

About this task

Use the Agentless Monitoring for Linux OS agent to monitor the appliance with IBM Tivoli Monitoring.

For more information about configuring the IBM Tivoli Monitoring environment and the Agentless Monitoring for Linux OS agent, see the IBM Tivoli Monitoring Knowledge Center.

The following management information bases, or MIBs, are used by the SNMP agent:

SNMPv2-MIB

TCP-MIB

SNMPv2-SMI

UDP-MIB

SNMP-FRAMEWORK-MIB

HOST-RESOURCES-MIB

SNMP-MPD-MIB

MTA-MIB

SNMP-TARGET-MIB

DISMAN-EVENT-MIB

SNMP-USER-BASED-SM-MIB

NOTIFICATION-LOG-MIB

SNMP-VIEW-BASED-ACM-MIB

UCD-SNMP-MIB

IF-MIB

UCD-DLMOD-MIB

IP-MIB

UCD-DISKIO-MIB

IPV6-MIB

UCD-SNMP-MIB

IP-FORWARD-MIB

NET-SNMP-AGENT-MIB

NET-SNMP-VACM-MIB

Procedure

From the top menu, select Manage System Settings > System Settings > SNMP Monitoring.

Type the port number that the SNMP agent must listen on in the Port field.

Note: The default port number is 161.

Select the SNMP Protocol that the agent must use.

SNMPv1/SNMPv2c

Type the name of the community that the SNMP uses to authenticate with the SNMP agent.

SNMPv3

Configure the following options to describe the user who accesses the SNMP agent.

Security Level

Select the security level of the user.

User Name

Type the name of the user who accesses the SNMP agent.

Auth Protocol

Select the authentication protocol to use.

Auth Password

Type the password to use for authentication.

Confirm Auth Password

Type the password to use for authentication.

Priv Protocol

Select the privacy protocol to use.

Priv Password

Type the password to be used as a privacy passphrase.

Confirm Priv Password

Type the password to be used as a privacy passphrase.

Click Save.

Parent topic: System settings

Secure settingsSecure settingsAccess Manager Appliance: Secure settingsInformation about managing secure settings on your appliance.settingssecuremanagementsettingssecureManage: System SettingsInformation about configuring Security, Network, and System settings of your appliance.Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.Managing file downloadsUse the File Downloads management page in the local management interface to access files that are available for download from the appliance.

Secure settings

Information about managing secure settings on your appliance.

Managing SSL certificates
In the local management interface, go to Manage System Settings > Secure Settings > SSL Certificates.

Managing file downloads
Use the File Downloads management page in the local management interface to access files that are available for download from the appliance.

Parent topic: Manage: System Settings

Managing SSL certificatesManaging SSL certificatesAccess Manager Appliance: Managing SSL certificates In the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.SSL certificatesmanagementmanagementcertificatesSSLThe appliance local management interface supports the following authentication mechanisms:Forms authentication (UI only)Basic authentication (Web services only)Client certificate (UI and Web services)The server uses the certificates that are found in the lmi_trust_store certificate database when it authenticates a client certificate. Therefore, to successfully authenticate against the server, the certificate database must contain either the client certificate itself, or the certificate of the CA that signed the client certificate. As a prerequisite for client certificate authentication, you must configure your browser to trust the CA for the appliance server certificate. In addition, the URL in the request must match the domain name of the appliance.Secure settingsInformation about managing secure settings on your appliance.Configuring SSL connectionsConfigure Secure Socket Layer (SSL) connections to enable encrypted communication between the LDAP policy information point (PIP) and the LDAP Server to ensure that LDAP traffic is secure and confidential.Listing current certificate database namesTo list all current certificate database names with the local management interface, use the SSL Certificates management page.Adding description to a certificate databaseTo add a description to a certificate database with the local management interface, use the SSL Certificates management page.Creating a certificate databaseTo create a certificate database with the local management interface, use the SSL Certificates management page.Renaming a certificate databaseTo rename a certificate database with the local management interface, use the SSL Certificates management page.Importing a certificate databaseTo import a certificate database with the local management interface, use the SSL Certificates management page.Exporting a certificate databaseTo export a certificate database with the local management interface, use the SSL Certificates management page.Deleting a certificate databaseTo delete a certificate database with the local management interface, you can use the SSL Certificates management page.Replicating the certificate databases across the clusterIf your appliance is the primary master of a cluster environment, you can replicate the certificate databases across the cluster with the SSL certificate management page.Managing signer certificates in a certificate databaseTo manage signer certificates in a certificate database, you can use the SSL Certificates management page. In particular, you can import, export, or delete signer certificates, and list all signer certificate names.Managing personal certificates in a certificate database To manage personal certificates in a certificate database with the local management interface, use the SSL Certificates management page.Managing certificate requests in a certificate databaseTo manage certificate requests in a certificate database with the local management interface, use the SSL Certificates management page. In particular, you can create, view, export, or delete certificate requests, and list all certificate request names.

Managing SSL certificates

In the local management interface, go to Manage System Settings > Secure Settings > SSL Certificates.

The appliance local management interface supports the following authentication mechanisms:

Forms authentication (UI only)

Basic authentication (Web services only)

Client certificate (UI and Web services)

The server uses the certificates that are found in the lmi_trust_store certificate database when it authenticates a client certificate. Therefore, to successfully authenticate against the server, the certificate database must contain either the client certificate itself, or the certificate of the CA that signed the client certificate.

Note: As a prerequisite for client certificate authentication, you must configure your browser to trust the CA for the appliance server certificate. In addition, the URL in the request must match the domain name of the appliance.

Configuring SSL connections
Configure Secure Socket Layer (SSL) connections to enable encrypted communication between the LDAP policy information point (PIP) and the LDAP Server to ensure that LDAP traffic is secure and confidential.

Listing current certificate database names
To list all current certificate database names with the local management interface, use the SSL Certificates management page.

Adding description to a certificate database
To add a description to a certificate database with the local management interface, use the SSL Certificates management page.

Creating a certificate database
To create a certificate database with the local management interface, use the SSL Certificates management page.

Renaming a certificate database
To rename a certificate database with the local management interface, use the SSL Certificates management page.

Importing a certificate database
To import a certificate database with the local management interface, use the SSL Certificates management page.

Exporting a certificate database
To export a certificate database with the local management interface, use the SSL Certificates management page.

Deleting a certificate database
To delete a certificate database with the local management interface, you can use the SSL Certificates management page.

Replicating the certificate databases across the cluster
If your appliance is the primary master of a cluster environment, you can replicate the certificate databases across the cluster with the SSL certificate management page.

Managing signer certificates in a certificate database
To manage signer certificates in a certificate database, you can use the SSL Certificates management page. In particular, you can import, export, or delete signer certificates, and list all signer certificate names.

Managing personal certificates in a certificate database
To manage personal certificates in a certificate database with the local management interface, use the SSL Certificates management page.

Managing certificate requests in a certificate database
To manage certificate requests in a certificate database with the local management interface, use the SSL Certificates management page. In particular, you can create, view, export, or delete certificate requests, and list all certificate request names.

Parent topic: Secure settings

Configuring SSL connectionsConfiguring SSL connectionsConfiguring SSL connectionsConfigure Secure Socket Layer (SSL) connections to enable encrypted communication between the LDAP policy information point (PIP) and the LDAP Server to ensure that LDAP traffic is secure and confidential.SSL connections configuringSSL connectionsLDAP policy information pointLDAP PIPLDAP server After you import a server certificate, the appliance can authenticate with the LDAP server. For more information, see Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates..Log in to the local management interface. Select Manage System SettingsSecure SettingsSSL Certificates. Import the LDAP server certificate into the trust store of the runtime profile.For example: rt_profile_keys.Configuring username and password authenticationThe user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository. LDAP PIPWhen you add or modify an LDAP policy information point (PIP), you configure a connection to an LDAP server. You also determine what information to use from the LDAP directory.Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Configuring SSL connections

Configure Secure Socket Layer (SSL) connections to enable encrypted communication between the LDAP policy information point (PIP) and the LDAP Server to ensure that LDAP traffic is secure and confidential.

About this task

After you import a server certificate, the appliance can authenticate with the LDAP server. For more information, see Managing SSL certificates.

Procedure

Log in to the local management interface.

Select Manage System Settings > Secure Settings > SSL Certificates.

Import the LDAP server certificate into the trust store of the runtime profile. For example: rt_profile_keys.

Parent topic: Managing SSL certificates

Related tasks:

Configuring username and password authentication

Related reference:

LDAP PIP

Listing current certificate database namesListing current certificate database namesAccess Manager Appliance: Listing current certificate database names To list all current certificate database names with the local management interface, use the SSL Certificates management page.certificatesdatabaseslistingSSL certificatesnamingFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.You can view all current certificate database names and their last modified time information.Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Listing current certificate database names

To list all current certificate database names with the local management interface, use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

You can view all current certificate database names and their last modified time information.

Parent topic: Managing SSL certificates

Adding description to a certificate databaseAdding description to a certificate database Access Manager Appliance: Adding description to a certificate databaseTo add a description to a certificate database with the local management interface, use the SSL Certificates management page.certificatesdatabasesadding descriptionSSL certificatesadding descriptionFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the certificate database that you want to describe.Select ManageDescribe.In the Describe SSL Certificates Database window, enter the description of the certificate database. Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Adding description to a certificate database

To add a description to a certificate database with the local management interface, use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the certificate database that you want to describe.

Select Manage > Describe.

In the Describe SSL Certificates Database window, enter the description of the certificate database.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Managing SSL certificates

Creating a certificate databaseCreating a certificate database Access Manager Appliance: Creating a certificate databaseTo create a certificate database with the local management interface, use the SSL Certificates management page.certificatesdatabasescreatingFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.From the menu bar, click New.On the Create SSL Certificate Database page, enter the name of the certificate database that you want to create. The name of the certificate database name must be unique.Select the type of the certificate database. If you select Local as the type, you can go to Step 5.If you select Network as the type, complete the following fields:On the Main tab, fill in the Token Label and Passcode fields. Select the HSM type.If you select Thales nShield Connect as the HSM type, complete the following fields:On the HSM tab, the HSM IP Address field for the primary HSM device is required. The rest of the fields are optional. You can also provide details of a secondary HSM device. The secondary device can be used for load balancing and failover.On the RFS tab, if you select Automatic, enter the address of the remote file system that stores the key files. The rest of the fields are optional. If you select Manual Upload, click Browse to select the zip file that contains the required key files. The contents of the zip file will be extracted and stored on the local file system. The Manual Upload option requires a zip file to be uploaded. The zip file must contain the encrypted Security World card and key files. The root of the zip file must contain the contents from the %NFAST_KMDATA%/local directory. For example, you can create the zip file by using the following command:cd %NFAST_KMDATA%/local; zip -r /tmp/kmdata.zip * More information can be found in the Thales nShield Connect user documentation.If the files in the remote file system are changed and you selected the Manual Upload option, you must manually upload an updated zip file. The updated zip file overwrites existing file entries but does not delete missing file entries.If you select SafeNet Luna SA as the HSM type, complete the IP Address and Admin Password fields on the SafeNet tab.You can use the appliance to manage the certificates that are contained on the HSM device. However, some operations, such as certificate extract, are not supported. Click Save. For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. . Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Creating a certificate database

To create a certificate database with the local management interface, use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

From the menu bar, click New.

On the Create SSL Certificate Database page, enter the name of the certificate database that you want to create. The name of the certificate database name must be unique.

Select the type of the certificate database.

If you select Local as the type, you can go to Step 5.

If you select Network as the type, complete the following fields:

On the Main tab, fill in the Token Label and Passcode fields.

Select the HSM type.

If you select Thales nShield Connect as the HSM type, complete the following fields:

On the HSM tab, the HSM IP Address field for the primary HSM device is required. The rest of the fields are optional. You can also provide details of a secondary HSM device. The secondary device can be used for load balancing and failover.

On the RFS tab, if you select Automatic, enter the address of the remote file system that stores the key files. The rest of the fields are optional. If you select Manual Upload, click Browse to select the zip file that contains the required key files. The contents of the zip file will be extracted and stored on the local file system.

Note:

The Manual Upload option requires a zip file to be uploaded. The zip file must contain the encrypted Security World card and key files. The root of the zip file must contain the contents from the %NFAST_KMDATA%/local directory. For example, you can create the zip file by using the following command:

cd %NFAST_KMDATA%/local; zip -r /tmp/kmdata.zip *

More information can be found in the Thales nShield Connect user documentation.

If the files in the remote file system are changed and you selected the Manual Upload option, you must manually upload an updated zip file. The updated zip file overwrites existing file entries but does not delete "missing" file entries.

If you select SafeNet Luna SA as the HSM type, complete the IP Address and Admin Password fields on the SafeNet tab.

Note: You can use the appliance to manage the certificates that are contained on the HSM device. However, some operations, such as certificate extract, are not supported.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Managing SSL certificates

Renaming a certificate databaseRenaming a certificate databaseAccess Manager Appliance: Renaming a certificate databaseTo rename a certificate database with the local management interface, use the SSL Certificates management page.certificatesdatabasesnamingSSL certificatesnamingFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the certificate database that you want to rename.Select ManageRenameIn the Rename SSL Certificates Database window, enter the new name of the certificate database. The new name of the certificate database name must be unique.Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Renaming a certificate database

To rename a certificate database with the local management interface, use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the certificate database that you want to rename.

Select Manage > Rename

In the Rename SSL Certificates Database window, enter the new name of the certificate database. The new name of the certificate database name must be unique.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Managing SSL certificates

Importing a certificate database Importing a certificate databaseAccess Manager Appliance: Importing a certificate databaseTo import a certificate database with the local management interface, use the SSL Certificates management page.certificatesdatabasesimportingSSL certificatesimportingFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select ManageImport.Click Browse under Certificate Database File. Browse to the directory that contains the file to be imported and select the file. Click Open.Click Browse under Stash File. Browse to the directory that contains the file to be imported and select the file. Click Open.Click Import.A message that indicates successful import is displayed.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Importing a certificate database

To import a certificate database with the local management interface, use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select Manage > Import.

Click Browse under Certificate Database File.

Browse to the directory that contains the file to be imported and select the file. Click Open.

Click Browse under Stash File.

Browse to the directory that contains the file to be imported and select the file. Click Open.

Click Import. A message that indicates successful import is displayed.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Managing SSL certificates

Exporting a certificate databaseExporting a certificate databaseAccess Manager Appliance: Exporting a certificate databaseTo export a certificate database with the local management interface, use the SSL Certificates management page.certificatesdatabasesexportingSSL certificatesexportingFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the certificate database that you want to export.Select ManageExport.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation when the browser prompts you to save the .zip file.Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Exporting a certificate database

To export a certificate database with the local management interface, use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the certificate database that you want to export.

Select Manage > Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation when the browser prompts you to save the .zip file.

Parent topic: Managing SSL certificates

Deleting a certificate databaseDeleting a certificate databaseAccess Manager Appliance: Deleting a certificate database To delete a certificate database with the local management interface, you can use the SSL Certificates management page.certificatesdatabasesdeletingFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the certificate database that you want to delete.Select DeleteIn the window that pops up, click Yes.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Deleting a certificate database

To delete a certificate database with the local management interface, you can use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the certificate database that you want to delete.

Select Delete

In the window that pops up, click Yes.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Managing SSL certificates

Replicating the certificate databases across the clusterReplicating the certificate databases across the clusterAccess Manager Appliance: Replicating the certificate databases across the clusterIf your appliance is the primary master of a cluster environment, you can replicate the certificate databases across the cluster with the SSL certificate management page.certificatesdatabasesreplicatingprimary mastersSSL certificatesreplicatingreplicating SSL certificatesFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Click Replicate with Cluster to have the certificate databases automatically replicated across the cluster.This option is available only if the current appliance is the primary master of a cluster. If this option is selected, you cannot modify the certificate databases on any appliance other than the primary master.Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Replicating the certificate databases across the cluster

If your appliance is the primary master of a cluster environment, you can replicate the certificate databases across the cluster with the SSL certificate management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Click Replicate with Cluster to have the certificate databases automatically replicated across the cluster.

Note: This option is available only if the current appliance is the primary master of a cluster. If this option is selected, you cannot modify the certificate databases on any appliance other than the primary master.

Parent topic: Managing SSL certificates

Managing signer certificates in a certificate databaseManaging signer certificates in a certificate databaseAccess Manager Appliance: Managing signer certificates in a certificate databaseTo manage signer certificates in a certificate database, you can use the SSL Certificates management page. In particular, you can import, export, or delete signer certificates, and list all signer certificate names.certificatessignermanagementcertificatessignerSSL certificatessigner certificatessigner certificatesFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the certificate database of interest.Select ManageEdit SSL Certificate Database.All signer certificate names are displayed on the Signer Certificates tab.Import a signer certificateClick ManageImport.Click Browse. Then, select the signer certificate to be imported.In the Certificate Label field, enter what you want to label the signer certificate.Click Import.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .View and export a signer certificateSelect the signer certificate that you want to view.Click ManageView. The content of the signer certificate is displayed in the browser.Optional: Click Export. Then, confirm the save operation in the window that pops up. You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Export a signer certificateSelect the signer certificate that you want to export.Click ManageExport.Confirm the save operation in the browser window that pops up.Delete a signer certificateSelect the signer certificate that you want to delete.Click Delete.In the window that pops up, click Yes.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Load a signer certificate from a serverUse the Load function to retrieve a server certificate from the specified server and port, and then install this certificate into the keyfile as a signer certificate with a specific label.Click ManageLoad.In the Load Signer Certificate window, specify the following fields:ServerThe server name from which to load the certificate.PortThe port from which to load the certificate.Certificate LabelThe name to give to the certificate.Click Load.Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Managing signer certificates in a certificate database

To manage signer certificates in a certificate database, you can use the SSL Certificates management page. In particular, you can import, export, or delete signer certificates, and list all signer certificate names.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the certificate database of interest.

Select Manage > Edit SSL Certificate Database.

All signer certificate names are displayed on the Signer Certificates tab.

Import a signer certificate

Click Manage > Import.

Click Browse. Then, select the signer certificate to be imported.

In the Certificate Label field, enter what you want to label the signer certificate.

Click Import.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

View and export a signer certificate

Select the signer certificate that you want to view.

Click Manage > View. The content of the signer certificate is displayed in the browser.

Optional: Click Export. Then, confirm the save operation in the window that pops up.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Export a signer certificate

Select the signer certificate that you want to export.

Click Manage > Export.

Confirm the save operation in the browser window that pops up.

Delete a signer certificate

Select the signer certificate that you want to delete.

Click Delete.

In the window that pops up, click Yes.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Load a signer certificate from a server

Use the Load function to retrieve a server certificate from the specified server and port, and then install this certificate into the keyfile as a signer certificate with a specific label.

Click Manage > Load.

In the Load Signer Certificate window, specify the following fields:

Server

The server name from which to load the certificate.

Port

The port from which to load the certificate.

Certificate Label

The name to give to the certificate.

Click Load.

Parent topic: Managing SSL certificates

Managing personal certificates in a certificate database Managing personal certificates in a certificate databaseAccess Manager Appliance: Managing personal certificates in a certificate database To manage personal certificates in a certificate database with the local management interface, use the SSL Certificates management page.certificatespersonalmanagementcertificatespersonalFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the certificate database of interest.Select ManageEdit SSL Certificate Database.Click the Personal Certificates tab. All personal certificate names are displayed on this tab. If the Issuer or Subject field contains characters in a language other than English, these characters might be displayed in the panel as encoded characters.Import a personal certificateClick ManageImport.Click Browse. Then, select the file that contains the personal certificate to import.Any PKCS 12 file to be imported must have the file extension .p12 for the import operation to be successful.Optional: Specify the password for the file that contains the personal certificate to import.Click Import.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Receive a personal certificateA personal certificate can be received only if a corresponding certificate request exists. Click ManageRecieve.Click Browse. Then, select the personal certificate to be received.Select the Default check box if you want to set the personal certificate as default.Click Receive.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .View a personal certificateSelect the personal certificate you want to view.Click ManageView. The content of the personal certificate is displayed in the browser.Optional: Click Export. Then, confirm the save operation in the window that pops up.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Export a personal certificateSelect the personal certificate that you want to export.Click ManageExport. You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation in the browser window that pops up.Extract a personal certificateThe Extract option is used to export a single certificate and its private key (if one exists) from the current key database to a new pcks12 formatted key database.Select the personal certificate that you want to extract.Click ManageExtract.In the Extract Personal Certificate window, enter a password for the extracted certificate container and confirm the password.Click Extract.You might want to save the certificate with the .p12 file extension for later use. Any PKCS 12 file to be imported must have the file extension .p12 for the import operation to be successful.Delete a personal certificateSelect the personal certificate that you want to delete.Click Delete.In the window that pops up, click Yes.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Create a personal certificate (self-signed)Click New.Enter Certificate Label, Certificate Distinguished Name, Key Size, and Expiration Time. The default value for Expiration Time is 365 days.Optionally, select an entry from the Signature Algorithm list. If this option is not specified, the default signature algorithm is used.Select the Default check box if you want to set this personal certificate as the default certificate.Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Set a personal certificate as defaultSelect the personal certificate that you want to edit.Click Edit.Select the Set as the Default Certificate check box to set the personal certificate as the default certificate.Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Managing personal certificates in a certificate database

To manage personal certificates in a certificate database with the local management interface, use the SSL Certificates management page.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the certificate database of interest.

Select Manage > Edit SSL Certificate Database.

Click the Personal Certificates tab. All personal certificate names are displayed on this tab.

Note: If the Issuer or Subject field contains characters in a language other than English, these characters might be displayed in the panel as encoded characters.

Import a personal certificate

Click Manage > Import.

Click Browse. Then, select the file that contains the personal certificate to import.

Note: Any PKCS 12 file to be imported must have the file extension .p12 for the import operation to be successful.

Optional: Specify the password for the file that contains the personal certificate to import.

Click Import.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Receive a personal certificate

Note: A personal certificate can be received only if a corresponding certificate request exists.

Click Manage > Recieve.

Click Browse. Then, select the personal certificate to be received.

Select the Default check box if you want to set the personal certificate as default.

Click Receive.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

View a personal certificate

Select the personal certificate you want to view.

Click Manage > View. The content of the personal certificate is displayed in the browser.

Optional: Click Export. Then, confirm the save operation in the window that pops up.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Export a personal certificate

Select the personal certificate that you want to export.

Click Manage > Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation in the browser window that pops up.

Extract a personal certificate

Note: The Extract option is used to export a single certificate and its private key (if one exists) from the current key database to a new pcks12 formatted key database.

Select the personal certificate that you want to extract.

Click Manage > Extract.

In the Extract Personal Certificate window, enter a password for the extracted certificate container and confirm the password.

Click Extract.

Note: You might want to save the certificate with the .p12 file extension for later use. Any PKCS 12 file to be imported must have the file extension .p12 for the import operation to be successful.

Delete a personal certificate

Select the personal certificate that you want to delete.

Click Delete.

In the window that pops up, click Yes.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Create a personal certificate (self-signed)

Click New.

Enter Certificate Label, Certificate Distinguished Name, Key Size, and Expiration Time. The default value for Expiration Time is 365 days.

Optionally, select an entry from the Signature Algorithm list. If this option is not specified, the default signature algorithm is used.

Select the Default check box if you want to set this personal certificate as the default certificate.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Set a personal certificate as default

Select the personal certificate that you want to edit.

Click Edit.

Select the Set as the Default Certificate check box to set the personal certificate as the default certificate.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Managing SSL certificates

Managing certificate requests in a certificate databaseManaging certificate requests in a certificate databaseAccess Manager Appliance: Managing certificate requests in a certificate databaseTo manage certificate requests in a certificate database with the local management interface, use the SSL Certificates management page. In particular, you can create, view, export, or delete certificate requests, and list all certificate request names.certificatesrequestsmanagementcertificatesrequestsFrom the top menu, select Manage System SettingsSecure SettingsSSL Certificates.Select the certificate database of interest.Select ManageEdit SSL Certificate Database.Click the Certificate Requests tab. All certificate request names are displayed on this tab.Create a certificate requestClick New.Enter Certificate Request Label, Certificate Request Distinguished Name, and Key Size. Optionally, select an entry from the Signature Algorithm list. If this option is not specified, the default signature algorithm is used.Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .View and export a certificate requestSelect the certificate request that you want to view.Click ManageView. The content of the certificate request is displayed in the browser.Optional: Click Export. Then, confirm the save operation in the window that pops up.Export a certificate requestSelect the certificate request that you want to export.Click ManageExport. The content of the certificate request is displayed in the browser.Confirm the save operation in the window that pops up.Delete a certificate requestSelect the certificate request that you want to delete.Click Delete.In the window that pops up, click Yes.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.

Managing certificate requests in a certificate database

To manage certificate requests in a certificate database with the local management interface, use the SSL Certificates management page. In particular, you can create, view, export, or delete certificate requests, and list all certificate request names.

Procedure

From the top menu, select Manage System Settings > Secure Settings > SSL Certificates.

Select the certificate database of interest.

Select Manage > Edit SSL Certificate Database.

Click the Certificate Requests tab. All certificate request names are displayed on this tab.

Create a certificate request

Click New.

Enter Certificate Request Label, Certificate Request Distinguished Name, and Key Size.

Optionally, select an entry from the Signature Algorithm list. If this option is not specified, the default signature algorithm is used.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

View and export a certificate request

Select the certificate request that you want to view.

Click Manage > View. The content of the certificate request is displayed in the browser.

Optional: Click Export. Then, confirm the save operation in the window that pops up.

Export a certificate request

Select the certificate request that you want to export.

Click Manage > Export. The content of the certificate request is displayed in the browser.

Confirm the save operation in the window that pops up.

Delete a certificate request

Select the certificate request that you want to delete.

Click Delete.

In the window that pops up, click Yes.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Managing SSL certificates

Managing file downloadsManaging file downloadsManaging file downloadsUse the File Downloads management page in the local management interface to access files that are available for download from the appliance.managementfile downloadsfilesFrom the top menu, select Manage System SettingsSecure SettingsFile Downloads.The displayed directories contain the files that can be downloaded. There are three parent directories:access_control contains files specific to the IBM Security Access Manager Advanced Access Control offering. This directory is shown only if Advanced Access Control has been activated.common contains files that are common across Security Access Manager.isam contains files specific to IBM Security Access Manager base offering.. This directory is shown only if the base has been activated.federation contains files specific to the IBM Security Access Manager Federation offering.This directory is shown only if Federation has been activated.These parent directories might contain subdirectories for different categories of files. Click Refresh to get the most up-to-date data.Select the file of interest.Click Export to save the file to your local drive. You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be downloaded. Confirm the save operation in the browser window that pops up.Secure settingsInformation about managing secure settings on your appliance.

Managing file downloads

Use the File Downloads management page in the local management interface to access files that are available for download from the appliance.

Procedure

From the top menu, select Manage System Settings > Secure Settings > File Downloads. The displayed directories contain the files that can be downloaded. There are three parent directories:

access_control contains files specific to the IBM Security Access Manager Advanced Access Control offering.

Note: This directory is shown only if Advanced Access Control has been activated.

common contains files that are common across Security Access Manager.

isam contains files specific to IBM Security Access Manager base offering..

Note: This directory is shown only if the base has been activated.

federation contains files specific to the IBM Security Access Manager Federation offering.

Note: This directory is shown only if Federation has been activated.

These parent directories might contain subdirectories for different categories of files.

Optional: Click Refresh to get the most up-to-date data.

Select the file of interest.

Click Export to save the file to your local drive.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be downloaded.

Confirm the save operation in the browser window that pops up.

Parent topic: Secure settings

Cluster supportCluster supportAccess Manager Appliance: Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.clusterssupportsupportclustersFor information about how to configure and administer a cluster in the LMI, see Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance..Appliance administrationThe IBM Security Access Manager administration interface provides procedures you can use to administer the appliance. The procedures in this hierarchy of topics are used by all activation levels.Cluster support overviewTo share configuration information between appliances and provide failover for services, you can configure your Security Access Manager appliances into clusters.Roles and services in a clusterThe nodes in a cluster share the cluster services, which include the distributed session cache, configuration database, geolocation database, and runtime database.Data replication in a clusterCluster members share data that is relevant to the Security Access Manager configuration. You can update the configuration data on the primary master only. The other nodes in the cluster maintain local read-only replicas of the data from the primary master.High availability of cluster servicesWhen you plan the architecture of your cluster, consider the services that you use in your environment along with your failover requirements for high availability. Include an External Reference Entity (ERE) for the primary and secondary masters in your architecture to assist in the failover process.High availability for the policy serverYou can enable the replication of the Security Access Manager runtime settings and the certificate database settings to achieve high availability for the policy server. Cluster failure managementIf a cluster member fails, you must take different administrative actions, depending on the role of the node in the cluster.Promoting a node to masterIf a master node fails, you might want to promote a different node to master while you resolve the failure. Removing an unreachable master node from the clusterIf a master node is unreachable, you can demote it from master and then remove it from the cluster to resolve the failure. When the node is restored, you can register it with the cluster again as a non-master node.Managing restricted nodes in a clusterYou can restrict nodes that are in the DMZ so that your network is secure. You can specify which nodes are restricted in the local management interface.Cluster maintenanceCluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.Data loss considerationsThe cluster services might lose data under certain circumstances. Deployment patternRead this section to understand the components of a typical cluster environment and how to set up such environments. In this typical deployment scenario, the cluster incorporates both a Security Access Manager base appliance and an appliance with Advanced Access Control activated.

Cluster support

The Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

For information about how to configure and administer a cluster in the LMI, see Managing cluster configuration.

Cluster support overview
To share configuration information between appliances and provide failover for services, you can configure your Security Access Manager appliances into clusters.

Roles and services in a cluster
The nodes in a cluster share the cluster services, which include the distributed session cache, configuration database, geolocation database, and runtime database.

Data replication in a cluster
Cluster members share data that is relevant to the Security Access Manager configuration. You can update the configuration data on the primary master only. The other nodes in the cluster maintain local read-only replicas of the data from the primary master.

High availability of cluster services
When you plan the architecture of your cluster, consider the services that you use in your environment along with your failover requirements for high availability. Include an External Reference Entity (ERE) for the primary and secondary masters in your architecture to assist in the failover process.

High availability for the policy server
You can enable the replication of the Security Access Manager runtime settings and the certificate database settings to achieve high availability for the policy server.

Cluster failure management
If a cluster member fails, you must take different administrative actions, depending on the role of the node in the cluster.

Promoting a node to master
If a master node fails, you might want to promote a different node to master while you resolve the failure.

Removing an unreachable master node from the cluster
If a master node is unreachable, you can demote it from master and then remove it from the cluster to resolve the failure. When the node is restored, you can register it with the cluster again as a non-master node.

Managing restricted nodes in a cluster
You can restrict nodes that are in the DMZ so that your network is secure. You can specify which nodes are restricted in the local management interface.

Cluster maintenance

Cluster configuration rules
When you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.

Data loss considerations
The cluster services might lose data under certain circumstances.

Deployment pattern
Read this section to understand the components of a typical cluster environment and how to set up such environments. In this typical deployment scenario, the cluster incorporates both a Security Access Manager base appliance and an appliance with Advanced Access Control activated.

Parent topic: Appliance administration

Cluster support overviewTo share configuration information between appliances and provide failover for services, you can configure your Security Access Manager appliances into clusters.clustersmastersnodesclustersprimary masterssecondary masterstertiary mastersquaternary mastersmaster nodesstand-alone clustersEvery cluster has a primary master and up to three back-up masters, known as the secondary, tertiary and quaternary masters for high availability of cluster services. By default, an individual appliance is configured as the primary master of a stand-alone cluster. You can configure other appliances to join the cluster as nodes. When an appliance is configured as a node, it can access and share the configuration information of the primary master.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Cluster support overview

To share configuration information between appliances and provide failover for services, you can configure your Security Access Manager appliances into clusters.

Every cluster has a primary master and up to three back-up masters, known as the secondary, tertiary and quaternary masters for high availability of cluster services.

By default, an individual appliance is configured as the primary master of a stand-alone cluster. You can configure other appliances to join the cluster as nodes. When an appliance is configured as a node, it can access and share the configuration information of the primary master.

Parent topic: Cluster support

Roles and services in a clusterRoles and services in a clusterRoles and services in a clusterThe nodes in a cluster share the cluster services, which include the distributed session cache, configuration database, geolocation database, and runtime database.distributed session cachecluster serviceconfigurationdatabasesgeolocation dataruntimedatabasesdatabasesrolesThe IBM Security Access Manager appliance provides services that can be shared across the cluster. You can configure more than one master appliance to provide failover for some of these services as described in Failover in a clusterThe distributed session cache, internal runtime database, geolocation database, and configuration database have varying failover capabilities in a clustered environment. . Services architectureDistributed Session CacheThe distributed session cache is a central cache to hold user session information.Configuration databaseThe configuration database stores configuration data that includes policy information, which is shared between the appliances in the cluster. You can update configuration data on the primary master only.Geolocation databaseThe geolocation database provides geographic location information.Runtime databaseThe context-based access component populates the high-volume database with runtime data. You can configure this database as an embedded database or an external database. The embedded database is suitable for small environments only. For large-scale, production environments, configure an external database. Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Roles and services in a cluster

The nodes in a cluster share the cluster services, which include the distributed session cache, configuration database, geolocation database, and runtime database.

The IBM Security Access Manager appliance provides services that can be shared across the cluster.

You can configure more than one master appliance to provide failover for some of these services as described in Failover in a cluster.

Figure 64. Services architecture

Distributed Session Cache

The distributed session cache is a central cache to hold user session information.

Configuration database

The configuration database stores configuration data that includes policy information, which is shared between the appliances in the cluster.

Note: You can update configuration data on the primary master only.

Geolocation database

The geolocation database provides geographic location information.

Runtime database

The context-based access component populates the high-volume database with runtime data. You can configure this database as an embedded database or an external database.

The embedded database is suitable for small environments only. For large-scale, production environments, configure an external database.

Parent topic: Cluster support

Data replication in a clusterCluster members share data that is relevant to the Security Access Manager configuration. You can update the configuration data on the primary master only. The other nodes in the cluster maintain local read-only replicas of the data from the primary master.clustersdatareplicationstatus columnLMIcluster configurationAny change to the cluster configuration or runtime parameters policy is automatically synchronized and applied to every node in the cluster. The Cluster Configuration management page in the LMI lists the nodes in the cluster. This list includes a Status column to indicate the status of the synchronization of system settings across the cluster.If the changes to the system settings are not synchronized correctly on a particular node, the cluster administrator must investigate the problem. The administrator can examine the various log files on the node to determine why the change did not deploy successfully. When the problem is fixed, the administrator can either reboot the node, or rejoin the node to the cluster so that it applies the changes again.The Status column indicates whether the system settings on each node are up-to-date. This column does not indicate the status of any other synchronizations.The data that is replicated across the cluster includes security settings, geolocation data, and system settings.You can optionally configure the cluster to replicate the Security Access Manager runtime settings and the certificate database settings. Replicating the runtime settings can provide high availability for the Policy Server. For more information, see High availability for the policy serverYou can enable the replication of the Security Access Manager runtime settings and the certificate database settings to achieve high availability for the policy server. .Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.Security SettingsIn an IBM Security Access Manager appliance cluster, the nodes share configuration data and runtime data that is related to the security settings. System settingsIn an IBM Security Access Manager appliance cluster, the nodes share some system settings.

Data replication in a cluster

Cluster members share data that is relevant to the Security Access Manager configuration. You can update the configuration data on the primary master only. The other nodes in the cluster maintain local read-only replicas of the data from the primary master.

Any change to the cluster configuration or runtime parameters policy is automatically synchronized and applied to every node in the cluster. The Cluster Configuration management page in the LMI lists the nodes in the cluster. This list includes a Status column to indicate the status of the synchronization of system settings across the cluster.

If the changes to the system settings are not synchronized correctly on a particular node, the cluster administrator must investigate the problem. The administrator can examine the various log files on the node to determine why the change did not deploy successfully. When the problem is fixed, the administrator can either reboot the node, or rejoin the node to the cluster so that it applies the changes again.

Note: The Status column indicates whether the system settings on each node are up-to-date. This column does not indicate the status of any other synchronizations.

The data that is replicated across the cluster includes security settings, geolocation data, and system settings.

You can optionally configure the cluster to replicate the Security Access Manager runtime settings and the certificate database settings. Replicating the runtime settings can provide high availability for the Policy Server. For more information, see High availability for the policy server.

Security Settings
In an IBM Security Access Manager appliance cluster, the nodes share configuration data and runtime data that is related to the security settings.

System settings
In an IBM Security Access Manager appliance cluster, the nodes share some system settings.

Parent topic: Cluster support

Security SettingsIn an IBM Security Access Manager appliance cluster, the nodes share configuration data and runtime data that is related to the security settings. clustersdatareplicationgeolocation dataruntimedataConfiguration dataOne-time password (OTP) mapping rules.Policy information such as risk profiles, attributes, and obligations.Configuration information such as user registry data.All of the advanced configuration data.Geolocation dataData that maps ranges of IP addresses to geographic locations.Runtime dataSession data.Non-session data that is relevant to the cluster, such as one-time passwords.Template files.Data replication in a clusterCluster members share data that is relevant to the Security Access Manager configuration. You can update the configuration data on the primary master only. The other nodes in the cluster maintain local read-only replicas of the data from the primary master.

Security Settings

In an IBM Security Access Manager appliance cluster, the nodes share configuration data and runtime data that is related to the security settings.

Configuration data

One-time password (OTP) mapping rules.

Policy information such as risk profiles, attributes, and obligations.

Configuration information such as user registry data.

All of the advanced configuration data.

Geolocation data

Data that maps ranges of IP addresses to geographic locations.

Runtime data

Session data.

Non-session data that is relevant to the cluster, such as one-time passwords.

Template files.

Parent topic: Data replication in a cluster

System settingsIn an IBM Security Access Manager appliance cluster, the nodes share some system settings.clustersdatareplicationsystemssettingssettingssystemsSSL certificatesreplicatingreplicating SSL certificatestuning parametersCluster configurationThe cluster configuration information is replicated across the nodes of the cluster.Runtime tuning parametersThe advanced tuning parameters are replicated across the nodes of the cluster.Runtime settingsBy default, the policy server configuration and policy database is not replicated across the cluster. However, you can choose to replicate this data. For more information about this configuration, see the "Replicate settings across the cluster" details in Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance..SSL certificatesBy default, the key file that is used by external clients to communicate with the DSC is not automatically distributed to nodes in the cluster. However, you can choose to replicate this data by selecting the 'Replicate with Cluster' check box on the SSL certificates management page.Data replication in a clusterCluster members share data that is relevant to the Security Access Manager configuration. You can update the configuration data on the primary master only. The other nodes in the cluster maintain local read-only replicas of the data from the primary master.

System settings

In an IBM Security Access Manager appliance cluster, the nodes share some system settings.

Cluster configuration

The cluster configuration information is replicated across the nodes of the cluster.

Runtime tuning parameters

The advanced tuning parameters are replicated across the nodes of the cluster.

Runtime settings

By default, the policy server configuration and policy database is not replicated across the cluster. However, you can choose to replicate this data. For more information about this configuration, see the "Replicate settings across the cluster" details in Managing cluster configuration.

SSL certificates

By default, the key file that is used by external clients to communicate with the DSC is not automatically distributed to nodes in the cluster. However, you can choose to replicate this data by selecting the 'Replicate with Cluster' check box on the SSL certificates management page.

Parent topic: Data replication in a cluster

High availability of cluster servicesWhen you plan the architecture of your cluster, consider the services that you use in your environment along with your failover requirements for high availability. Include an External Reference Entity (ERE) for the primary and secondary masters in your architecture to assist in the failover process.clustersservicesfailureavailabilityCluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.Cluster service considerationsA cluster requires at least one master, called the primary master, which provides the cluster services. For failover purposes in a cluster with multiple nodes, you can configure up to three more masters in the environment. The required number of masters depends on which services you use and your failover requirements.Failover in a clusterThe distributed session cache, internal runtime database, geolocation database, and configuration database have varying failover capabilities in a clustered environment. External Reference EntityTo prepare for failover situations, you must configure an External Reference Entity (ERE) for the primary and secondary master nodes.

High availability of cluster services

When you plan the architecture of your cluster, consider the services that you use in your environment along with your failover requirements for high availability. Include an External Reference Entity (ERE) for the primary and secondary masters in your architecture to assist in the failover process.

Cluster service considerations
A cluster requires at least one master, called the primary master, which provides the cluster services. For failover purposes in a cluster with multiple nodes, you can configure up to three more masters in the environment. The required number of masters depends on which services you use and your failover requirements.

Failover in a cluster
The distributed session cache, internal runtime database, geolocation database, and configuration database have varying failover capabilities in a clustered environment.

External Reference Entity
To prepare for failover situations, you must configure an External Reference Entity (ERE) for the primary and secondary master nodes.

Parent topic: Cluster support

Cluster service considerationsA cluster requires at least one master, called the primary master, which provides the cluster services. For failover purposes in a cluster with multiple nodes, you can configure up to three more masters in the environment. The required number of masters depends on which services you use and your failover requirements.clustersmastersfailureavailabilityexternal reference entity (ERE)configurationdatabasesruntimecluster servicesdistributed session cachecluster serviceThe following table depicts the valid master configurations. Possible architectures for clusters that contain multiple nodesNumber of mastersCombination of mastersConsiderations1Primary master only.No failover for cluster services.2Primary master and secondary master.This configuration includes a secondary master to provide failover for the cluster services, which include the distributed session cache (DSC), configuration database, geolocation database, and runtime database.3Primary master, secondary master, and tertiary master.You can optionally designate a tertiary master to provide extra failover for the distributed session cache. Only the distributed session cache recognizes the tertiary master node. The configuration, geolocation, and runtime databases consider the tertiary node as a non-master node. 4Primary master, secondary master, tertiary master, and quaternary master.You can optionally designate tertiary and quaternary masters to provide extra failover for the distributed session cache. Only the distributed session cache recognizes the tertiary and quaternary master nodes. The configuration, geolocation, and runtime databases consider these nodes as non-master nodes. For high availability in a cross data center environment, you can consider separating the master appliances between the data centers as depicted in Figure 1.Example cluster architectureThis figure shows the data replication and service availability across the master nodes. Distributed session cacheThe primary master maintains the master copy of the distributed session cache and the other master nodes keep slave copies for failover purposes. Runtime databaseIf you are using the internal runtime database, the primary master maintains the master copy of this data, while the secondary master keeps a slave copy for failover purposes.If you are using an external runtime database, the cluster does not provide failover. In this case, the external database server is responsible for ensuring high availability.Configuration and geolocation databasesThe primary master is the only master on which you can update the configuration and geolocation databases. The other nodes in the cluster, including secondary, tertiary, and quaternary masters, maintain a read-only copy of the information from these databases. High availability of cluster servicesWhen you plan the architecture of your cluster, consider the services that you use in your environment along with your failover requirements for high availability. Include an External Reference Entity (ERE) for the primary and secondary masters in your architecture to assist in the failover process.

Cluster service considerations

A cluster requires at least one master, called the primary master, which provides the cluster services. For failover purposes in a cluster with multiple nodes, you can configure up to three more masters in the environment. The required number of masters depends on which services you use and your failover requirements.

The following table depicts the valid master configurations.

Table 152. Possible architectures for clusters that contain multiple nodes.

Number of masters
Combination of masters
Considerations

1
Primary master only.
No failover for cluster services.

2
Primary master and secondary master.
This configuration includes a secondary master to provide failover for the cluster services, which include the distributed session cache (DSC), configuration database, geolocation database, and runtime database.

3
Primary master, secondary master, and tertiary master.
You can optionally designate a tertiary master to provide extra failover for the distributed session cache.

Only the distributed session cache recognizes the tertiary master node. The configuration, geolocation, and runtime databases consider the tertiary node as a non-master node.

4
Primary master, secondary master, tertiary master, and quaternary master.
You can optionally designate tertiary and quaternary masters to provide extra failover for the distributed session cache.

Only the distributed session cache recognizes the tertiary and quaternary master nodes. The configuration, geolocation, and runtime databases consider these nodes as non-master nodes.

For high availability in a cross data center environment, you can consider separating the master appliances between the data centers as depicted in Figure 65..

Figure 65. Example cluster architecture

This figure shows the data replication and service availability across the master nodes.

Distributed session cache

The primary master maintains the master copy of the distributed session cache and the other master nodes keep slave copies for failover purposes.

Runtime database

If you are using the internal runtime database, the primary master maintains the master copy of this data, while the secondary master keeps a slave copy for failover purposes.

If you are using an external runtime database, the cluster does not provide failover. In this case, the external database server is responsible for ensuring high availability.

Configuration and geolocation databases

The primary master is the only master on which you can update the configuration and geolocation databases. The other nodes in the cluster, including secondary, tertiary, and quaternary masters, maintain a read-only copy of the information from these databases.

Parent topic: High availability of cluster services

Failover in a clusterThe distributed session cache, internal runtime database, geolocation database, and configuration database have varying failover capabilities in a clustered environment. clustersfailurefailuredistributed session cachefailoverruntimefailuredatabasesgeolocation dataIf you configure a secondary master and the primary master fails, the distributed session cache and the internal runtime database failover to the secondary master. When the primary master is restored, reconciliation occurs and the primary master resumes control of these services. For the distributed session cache, a full copy of all sessions is restored.You can also configure tertiary and quaternary masters for distributed session cache failover. If the primary and secondary masters are both unavailable, the distributed session cache fails over to the tertiary master. If the tertiary master is also unavailable, the distributed session cache fails over to the quaternary master. The distributed session cache forms a chain of session replication from the primary to the quaternary master. If any node in the chain fails, it can request a full copy of all sessions from either partner in the chain when it recovers. There is no disk caching of sessions, so a full copy is required.There is no failover between the master servers for the configuration and geolocation databases. If the primary master fails, the other nodes have a local read-only copy of the information that they can use in the interim. However, no configuration or geolocation updates are possible until the primary master is back online or a new primary master is designated.For WebSEAL to successfully fail over, set the following parameter in the [junction] stanza of the WebSEAL configuration file:[junction] use-new-stateful-on-error = yes See use-new-stateful-on-error for more information. High availability of cluster servicesWhen you plan the architecture of your cluster, consider the services that you use in your environment along with your failover requirements for high availability. Include an External Reference Entity (ERE) for the primary and secondary masters in your architecture to assist in the failover process.

Failover in a cluster

The distributed session cache, internal runtime database, geolocation database, and configuration database have varying failover capabilities in a clustered environment.

If you configure a secondary master and the primary master fails, the distributed session cache and the internal runtime database failover to the secondary master. When the primary master is restored, reconciliation occurs and the primary master resumes control of these services. For the distributed session cache, a full copy of all sessions is restored.

You can also configure tertiary and quaternary masters for distributed session cache failover. If the primary and secondary masters are both unavailable, the distributed session cache fails over to the tertiary master. If the tertiary master is also unavailable, the distributed session cache fails over to the quaternary master.

The distributed session cache forms a chain of session replication from the primary to the quaternary master. If any node in the chain fails, it can request a full copy of all sessions from either partner in the chain when it recovers. There is no disk caching of sessions, so a full copy is required.

There is no failover between the master servers for the configuration and geolocation databases. If the primary master fails, the other nodes have a local read-only copy of the information that they can use in the interim. However, no configuration or geolocation updates are possible until the primary master is back online or a new primary master is designated.

Note: For WebSEAL to successfully fail over, set the following parameter in the [junction] stanza of the WebSEAL configuration file:

[junction] use-new-stateful-on-error = yes

See use-new-stateful-on-error for more information.

Parent topic: High availability of cluster services

External Reference EntityTo prepare for failover situations, you must configure an External Reference Entity (ERE) for the primary and secondary master nodes.clustersexternal reference entity (ERE)external reference entity (ERE)master EREWhen the communication link between the primary and secondary master nodes fails, both database servers might mistakenly assume that the other one is down. As a result, a dual primary situation can arise and you might lose transactions when databases are later synchronized. To avoid this situation, you can use a network reference device, such as a network router, as an ERE to check the health of the network. If you configure a secondary master, you must also configure an ERE for the primary and secondary masters. If the primary master loses its connection to the secondary master, it can contact the ERE to determine whether there is a network fault or the secondary master is down.In a distributed configuration, you can separate the primary and secondary masters into one data center and the tertiary and quaternary masters into another data center. If the data center link fails, the primary and tertiary masters operate in parallel and service requests in their local networks. When the data center link is restored, the tertiary master becomes inactive and reconciles its updates with the primary master. The above mentioned data reconciliation applies only to the distributed session cache. It does not apply to other databases such as the configuration database and geolocation database.High availability of cluster servicesWhen you plan the architecture of your cluster, consider the services that you use in your environment along with your failover requirements for high availability. Include an External Reference Entity (ERE) for the primary and secondary masters in your architecture to assist in the failover process.

External Reference Entity

To prepare for failover situations, you must configure an External Reference Entity (ERE) for the primary and secondary master nodes.

When the communication link between the primary and secondary master nodes fails, both database servers might mistakenly assume that the other one is down. As a result, a dual primary situation can arise and you might lose transactions when databases are later synchronized. To avoid this situation, you can use a network reference device, such as a network router, as an ERE to check the health of the network.

If you configure a secondary master, you must also configure an ERE for the primary and secondary masters. If the primary master loses its connection to the secondary master, it can contact the ERE to determine whether there is a network fault or the secondary master is down.

In a distributed configuration, you can separate the primary and secondary masters into one data center and the tertiary and quaternary masters into another data center. If the data center link fails, the primary and tertiary masters operate in parallel and service requests in their local networks. When the data center link is restored, the tertiary master becomes inactive and reconciles its updates with the primary master.

Note: The above mentioned data reconciliation applies only to the distributed session cache. It does not apply to other databases such as the configuration database and geolocation database.

Parent topic: High availability of cluster services

High availability for the policy serverYou can enable the replication of the Security Access Manager runtime settings and the certificate database settings to achieve high availability for the policy server. clustersdatareplicationpolicy serversruntimesettingsavailabilityhigh availabilityIn a clustered environment, the Security Access Manager policy server can run on any node in the cluster. However, you must configure the policy server on the primary master if you want high availability.To achieve high availability, you must adhere to the following requirements: The policy server must run on the primary master.You must configure replication for the runtime settings.If you are using SSL communication with an external directory server, you must configure replication for the certificate database settings.You can configure the cluster to replicate the runtime settings and certificate database settings on the Replication tab of the Cluster Configuration page. For more information about these settings, see the "Replicate settings across the cluster" details in Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance..When you enable replication of the runtime settings, the policy server configuration and policy database information is copied from the primary master to every node in the cluster. The keys that are used for SSL communication between the Security Access Manager servers are also distributed across the cluster. If these settings are changed, the primary master sends the updates to the other nodes in the cluster.The following process occurs when you enable replication of the runtime settings from the local management interface of the primary master:Any policy servers on other nodes in the cluster are stopped.The policy server configuration and policy database information is copied from the primary master to all other nodes in the cluster. Any existing policy server configuration on these nodes is overwritten by the configuration from the primary master.SSL keys for communication between the Security Access Manager servers are copied to every node.LDAP servers on other nodes in the cluster are stopped.If the Policy Server is configured to use a local LDAP, the LDAP data is copied to every node in the cluster and LDAP is started on each node. If there are WebSEAL instances or authorization servers, which are configured against a different policy server, you must reconfigure them to use the policy server on the primary master. If you are using an external directory server with SSL enabled, you must configure the cluster to replicate the certificate database settings. If you enable this replication setting, the key files for SSL communication with the external directory server are distributed across the cluster.If the primary master fails, you can promote any other node in the cluster to be the new primary master. The policy server starts automatically on the new primary master. All of the Security Access Manager servers on the other nodes are automatically reconfigured to use the policy server on the new primary master. The Security Access Manager servers can connect to the new policy server without requiring a restart. For more information about promoting a node to primary master, see Promoting a node to primary master when the original primary master is unavailable.When a node is promoted to primary master and replication for the runtime settings is enabled, the following process occurs:The replicated policy server configuration is modified to listen on one of the Management Interfaces. The policy server is started on the promoted node.If the Policy Server is configured to use a local LDAP, the local LDAP is started on the promoted node.Any configured WebSEAL and authorization servers on nodes in the cluster are modified to point to the policy server on the new primary master.When you disable replication of the runtime settings, the policy server configuration and policy database information is removed from the other nodes in the cluster. If you are using the local LDAP on the primary master, the replicated copies of the LDAP files are removed from the other nodes. The WebSEAL instances and authorization servers in the cluster continue to use the policy server on the primary master. After you disable the replication, restart the Security Access Manager server on each node in the cluster.If the policy server is configured with a local LDAP server as the user registry, high availability is provided. Each node of the cluster contains a read-only replica of the LDAP server that is used automatically in failover scenarios.If the LDAP server provided by the primary master becomes unavailable to a node, any authorization servers that run on that node will failover to their local replicas. During this time, only read operations are possible. When the primary master LDAP server becomes available again, the node will automatically revert to normal operation.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

High availability for the policy server

You can enable the replication of the Security Access Manager runtime settings and the certificate database settings to achieve high availability for the policy server.

In a clustered environment, the Security Access Manager policy server can run on any node in the cluster. However, you must configure the policy server on the primary master if you want high availability.

To achieve high availability, you must adhere to the following requirements:

The policy server must run on the primary master.

You must configure replication for the runtime settings.

If you are using SSL communication with an external directory server, you must configure replication for the certificate database settings.

You can configure the cluster to replicate the runtime settings and certificate database settings on the Replication tab of the Cluster Configuration page. For more information about these settings, see the "Replicate settings across the cluster" details in Managing cluster configuration.

When you enable replication of the runtime settings, the policy server configuration and policy database information is copied from the primary master to every node in the cluster. The keys that are used for SSL communication between the Security Access Manager servers are also distributed across the cluster. If these settings are changed, the primary master sends the updates to the other nodes in the cluster.

The following process occurs when you enable replication of the runtime settings from the local management interface of the primary master:

Any policy servers on other nodes in the cluster are stopped.

The policy server configuration and policy database information is copied from the primary master to all other nodes in the cluster. Any existing policy server configuration on these nodes is overwritten by the configuration from the primary master.

SSL keys for communication between the Security Access Manager servers are copied to every node.

LDAP servers on other nodes in the cluster are stopped.

If the Policy Server is configured to use a local LDAP, the LDAP data is copied to every node in the cluster and LDAP is started on each node.

Note: If there are WebSEAL instances or authorization servers, which are configured against a different policy server, you must reconfigure them to use the policy server on the primary master.

If you are using an external directory server with SSL enabled, you must configure the cluster to replicate the certificate database settings. If you enable this replication setting, the key files for SSL communication with the external directory server are distributed across the cluster.

If the primary master fails, you can promote any other node in the cluster to be the new primary master. The policy server starts automatically on the new primary master. All of the Security Access Manager servers on the other nodes are automatically reconfigured to use the policy server on the new primary master. The Security Access Manager servers can connect to the new policy server without requiring a restart. For more information about promoting a node to primary master, see Promoting a node to primary master when the original primary master is unavailable.

When a node is promoted to primary master and replication for the runtime settings is enabled, the following process occurs:

The replicated policy server configuration is modified to listen on one of the Management Interfaces.

The policy server is started on the promoted node.

If the Policy Server is configured to use a local LDAP, the local LDAP is started on the promoted node.

Any configured WebSEAL and authorization servers on nodes in the cluster are modified to point to the policy server on the new primary master.

When you disable replication of the runtime settings, the policy server configuration and policy database information is removed from the other nodes in the cluster. If you are using the local LDAP on the primary master, the replicated copies of the LDAP files are removed from the other nodes. The WebSEAL instances and authorization servers in the cluster continue to use the policy server on the primary master.

Note: After you disable the replication, restart the Security Access Manager server on each node in the cluster.

If the policy server is configured with a local LDAP server as the user registry, high availability is provided. Each node of the cluster contains a read-only replica of the LDAP server that is used automatically in failover scenarios.

If the LDAP server provided by the primary master becomes unavailable to a node, any authorization servers that run on that node will failover to their local replicas. During this time, only read operations are possible. When the primary master LDAP server becomes available again, the node will automatically revert to normal operation.

Parent topic: Cluster support

Cluster failure managementCluster failure managementCluster failure managementIf a cluster member fails, you must take different administrative actions, depending on the role of the node in the cluster.clustersfailurenodesfailurefailureFailure of the primary masterPromote a different node to the primary master. For detailed steps that describe how to promote a different node, see Promoting a node to masterIf a master node fails, you might want to promote a different node to master while you resolve the failure. .You can promote a non-master node to the primary master so that other master nodes in the environment remain for failover purposes. If there is a secondary master in the environment, you can optionally promote it to primary master. The process for this promotion depends on whether there are tertiary and quaternary masters in the environment:If there are tertiary and quaternary masters, you must take either of the following actions at the same time as you promote the secondary master to primary:Promote a non-master node to secondary master, orDemote the tertiary and quaternary nodes to non-master nodes.You cannot have a tertiary and quaternary master without a secondary master.If you do not have tertiary and quaternary masters, you can promote the secondary master to primary master and the cluster can operate with a single master. However, for high availability purposes, you might also want to promote a non-master node to secondary master.Remove the failed node from the cluster. For detailed steps, see Removing an unreachable master node from the clusterIf a master node is unreachable, you can demote it from master and then remove it from the cluster to resolve the failure. When the node is restored, you can register it with the cluster again as a non-master node..Export the signature file from the new master. You must use this signature file when you are adding new nodes to the cluster. Failure of a secondary, tertiary, or quaternary masterDemote the failed node on the primary master. Promote a non-master node to replace the failed master.You might need to complete steps 1 and 2 simultaneously to ensure that you maintain a valid combination of master nodes. For more information about valid architectures, see Cluster architecture rulesThe architecture of a cluster, including the appointment of masters, is governed by numerous rules..Remove the failed node from the cluster.Failure of a nodeUnregister the node on the primary master. Optionally, you can add a node to the cluster to replace the failed node.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Cluster failure management

If a cluster member fails, you must take different administrative actions, depending on the role of the node in the cluster.

Failure of the primary master

Promote a different node to the primary master. For detailed steps that describe how to promote a different node, see Promoting a node to master.

You can promote a non-master node to the primary master so that other master nodes in the environment remain for failover purposes.

If there is a secondary master in the environment, you can optionally promote it to primary master. The process for this promotion depends on whether there are tertiary and quaternary masters in the environment:

If there are tertiary and quaternary masters, you must take either of the following actions at the same time as you promote the secondary master to primary:

Promote a non-master node to secondary master, or

Demote the tertiary and quaternary nodes to non-master nodes.

You cannot have a tertiary and quaternary master without a secondary master.

If you do not have tertiary and quaternary masters, you can promote the secondary master to primary master and the cluster can operate with a single master. However, for high availability purposes, you might also want to promote a non-master node to secondary master.

Remove the failed node from the cluster. For detailed steps, see Removing an unreachable master node from the cluster.

Export the signature file from the new master. You must use this signature file when you are adding new nodes to the cluster.

Failure of a secondary, tertiary, or quaternary master

Demote the failed node on the primary master.

Promote a non-master node to replace the failed master.

Note: You might need to complete steps 1 and 2 simultaneously to ensure that you maintain a valid combination of master nodes. For more information about valid architectures, see Cluster architecture rules.

Remove the failed node from the cluster.

Failure of a node

Unregister the node on the primary master.

Optionally, you can add a node to the cluster to replace the failed node.

Parent topic: Cluster support

Promoting a node to masterPromoting a node to masterAccess Manager Appliance: Promoting a node to master in a clusterIf a master node fails, you might want to promote a different node to master while you resolve the failure. clustersnodesmaster nodeslocal management interfacecluster configurationpromotionnodespromotionWhen you are promoting a node to master, ensure that you adhere to the cluster architecture rules. For example, you must specify the supplementary masters in order. You cannot specify tertiary and quaternary masters if there is no secondary master. For a complete list of the cluster configuration rules, see Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.. Promoting a node to a master falls into two main categories: Promoting a node to a supplementary master - secondary master, tertiary master, or quaternary master. Promoting a node to primary master. Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.Promoting a node to a supplementary masterYou can use the local management interface of the primary master to update the cluster configuration and select the supplementary masters. To promote a node to secondary, tertiary, or quaternary master, complete these steps:Open the Cluster Configuration page from the primary master local management interface.Go to the General tab.Change the values in the master fields. That is, Secondary master, Tertiary master, Quaternary master. Save and deploy the updates.Promoting a node to primary master when the original primary master is unavailableNodes are automatically updated with information for the new primary master. If a node is not reachable by the primary master at the time of promotion, there is a delay of up to 15 minutes from the time that connectivity is restored before the node is notified of the new primary master.If the original primary master is reconnected to the primary master, it is automatically demoted to the role of a normal node. If the network is segregated and two different nodes are promoted to primary master in the different networks, automatic recovery is not possible when the network connectivity is re-established. In this situation, a manual merge of the segregated cluster is required. This step is achieved by removing all nodes from one of the clusters and joining these nodes back into the other cluster. This situation occurs only when both of the following conditions are met:Connectivity in the cluster is lost. The administrator promotes two different nodes to the primary master role while network connectivity is lost.Use the local management interface of the appliance that you are promoting to primary master to update the configuration. You can promote a non-master node or one of the supplementary masters if available. To promote the selected node to primary master, complete these steps:Access the local management interface of the node that you want to promote to primary master.Select Manage System SettingsNetwork SettingsCluster Configuration.Select the General tab.Select Set this appliance as a Primary Master. Use the available menu to set the Primary master IP address. Select the first management interface of the appliance.Save and deploy the changes.Promoting a node to primary master when the original primary master is availableNodes are automatically updated with information for the new primary master. If a node is not reachable by the primary master at the time of promotion, there is a delay of up to 15 minutes from the time that connectivity is restored before the node is notified of the new primary master.You can promote another node to primary master only if it is currently contactable by the current primary master.Use the local management interface of the current primary master to update the configuration. Access the local management interface of the current primary master.Select Manage System SettingsNetwork SettingsCluster Configuration.Select the General tab.Select a new primary master from the list of nodes in the drop-down list.If applicable, update the rest of the configuration to ensure that you do not break any of the clustering rules.Save and deploy the changes.

Promoting a node to master

If a master node fails, you might want to promote a different node to master while you resolve the failure.

About this task

When you are promoting a node to master, ensure that you adhere to the cluster architecture rules. For example, you must specify the supplementary masters in order. You cannot specify tertiary and quaternary masters if there is no secondary master. For a complete list of the cluster configuration rules, see Cluster configuration rules.

Promoting a node to a master falls into two main categories:

Promoting a node to a supplementary master - secondary master, tertiary master, or quaternary master.

Promoting a node to primary master.

Parent topic: Cluster support

Promoting a node to a supplementary master

Procedure

You can use the local management interface of the primary master to update the cluster configuration and select the supplementary masters. To promote a node to secondary, tertiary, or quaternary master, complete these steps:

Open the Cluster Configuration page from the primary master local management interface.

Go to the General tab.

Change the values in the master fields. That is, Secondary master, Tertiary master, Quaternary master.

Save and deploy the updates.

Promoting a node to primary master when the original primary master is unavailable

About this task

Nodes are automatically updated with information for the new primary master. If a node is not reachable by the primary master at the time of promotion, there is a delay of up to 15 minutes from the time that connectivity is restored before the node is notified of the new primary master.

If the original primary master is reconnected to the primary master, it is automatically demoted to the role of a normal node.

If the network is segregated and two different nodes are promoted to primary master in the different networks, automatic recovery is not possible when the network connectivity is re-established. In this situation, a manual merge of the segregated cluster is required. This step is achieved by removing all nodes from one of the clusters and joining these nodes back into the other cluster. This situation occurs only when both of the following conditions are met:

Connectivity in the cluster is lost.

The administrator promotes two different nodes to the primary master role while network connectivity is lost.

Procedure

Use the local management interface of the appliance that you are promoting to primary master to update the configuration. You can promote a non-master node or one of the supplementary masters if available. To promote the selected node to primary master, complete these steps:

Access the local management interface of the node that you want to promote to primary master.

Select Manage System Settings > Network Settings > Cluster Configuration.

Select the General tab.

Select Set this appliance as a Primary Master.

Use the available menu to set the Primary master IP address. Select the first management interface of the appliance.

Save and deploy the changes.

Promoting a node to primary master when the original primary master is available

About this task

Nodes are automatically updated with information for the new primary master. If a node is not reachable by the primary master at the time of promotion, there is a delay of up to 15 minutes from the time that connectivity is restored before the node is notified of the new primary master.

You can promote another node to primary master only if it is currently contactable by the current primary master.

Procedure

Use the local management interface of the current primary master to update the configuration.

Access the local management interface of the current primary master.

Select Manage System Settings > Network Settings > Cluster Configuration.

Select the General tab.

Select a new primary master from the list of nodes in the drop-down list.

If applicable, update the rest of the configuration to ensure that you do not break any of the clustering rules.

Save and deploy the changes.

Removing an unreachable master node from the clusterRemoving an unreachable master node from a clusterAccess Manager Appliance: Removing an unreachable master node from the clusterIf a master node is unreachable, you can demote it from master and then remove it from the cluster to resolve the failure. When the node is restored, you can register it with the cluster again as a non-master node.clustersnodesmaster nodesregistrationconfigurationlocal management interfacesignature fileslocal management interfacecluster configurationTo remove the failed node from the cluster, complete the following steps in the local management interface of the new primary master:Go to the Overview tab on the Cluster Configuration page.Under the Nodes section, select the node to remove.Click Delete.Select the Force check box to force the removal of the node even if the node cannot be reached.Click Yes to confirm the operation. Deploy the changes.After you remove the failed node from the cluster, you might want to restart it and ultimately restore it as a cluster member. In this case, you must complete some additional steps. While the node is disconnected from the network, change it to a stand-alone cluster with only a single node, as described in the following steps.Restore the node and use its local management interface to access the Cluster Configuration page. Go to General tab.From the overview page, remove all other nodes.Change the Primary master IP address to 127.0.0.1.Save and deploy the change.Troubleshoot the original failure and resolve any problems.You can now join the restored appliance back in to the original cluster. This process joins the restored node to the cluster as a non-master node:In the local management interface of the restored appliance, go to the Overview tab on the Cluster Configuration page. Click Import.In the Join Cluster window, click Browse to select the cluster signature file of the new primary master. You can generate the cluster signature file by using the local management interface of the new primary master and selecting the Export option in the Overview tab. Click Join to add the current appliance to the cluster.Deploy the changes.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Removing an unreachable master node from the cluster

If a master node is unreachable, you can demote it from master and then remove it from the cluster to resolve the failure. When the node is restored, you can register it with the cluster again as a non-master node.

Procedure

To remove the failed node from the cluster, complete the following steps in the local management interface of the new primary master:

Go to the Overview tab on the Cluster Configuration page.

Under the Nodes section, select the node to remove.

Click Delete.

Select the Force check box to force the removal of the node even if the node cannot be reached.

Click Yes to confirm the operation.

Deploy the changes.

After you remove the failed node from the cluster, you might want to restart it and ultimately restore it as a cluster member. In this case, you must complete some additional steps. While the node is disconnected from the network, change it to a stand-alone cluster with only a single node, as described in the following steps.

Restore the node and use its local management interface to access the Cluster Configuration page.

Go to General tab.

From the overview page, remove all other nodes.

Change the Primary master IP address to 127.0.0.1.

Save and deploy the change.

Troubleshoot the original failure and resolve any problems.

You can now join the restored appliance back in to the original cluster. This process joins the restored node to the cluster as a non-master node:

In the local management interface of the restored appliance, go to the Overview tab on the Cluster Configuration page.

Click Import.

In the Join Cluster window, click Browse to select the cluster signature file of the new primary master.

Note: You can generate the cluster signature file by using the local management interface of the new primary master and selecting the Export option in the Overview tab.

Click Join to add the current appliance to the cluster.

Deploy the changes.

Parent topic: Cluster support

Managing restricted nodes in a clusterRestricted nodes in a clusterRestricted nodes in a clusterYou can restrict nodes that are in the DMZ so that your network is secure. You can specify which nodes are restricted in the local management interface.nodesrestrictedrestricted nodesconfigurationrestricted nodesLMIrestricted nodesThe following restrictions apply to restricted nodes:Restricted nodes cannot be promoted to any of the master roles.Restricted nodes cannot use the Policy Administration tool to modify the security policy.Restricted nodes do not contain a replica of the data that is stored by the embedded user registry.You can restrict a node when you register a node in a cluster or at any time from the master local management interface. You can also restrict several nodes in a cluster.Select the steps for the task you want to complete:Configuring a restricted node during registrationConfigure a restricted node when you register the node by using the local management interface.Register a node to a cluster.For more information, see Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance..Check Join as restricted node in the Join Cluster window.Click Join to add the appliance to a cluster as a restricted node.Configure a restricted node in a clusterUse the local management interface to specify a restricted node in a cluster.Log on to the master appliance.From the top menu of the local management interface, select Manage System Settings Cluster Configuration.Select the Overview tab.Select the node to be set as restricted in the Nodes grid.Click Restricted Node. Click Submit.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Managing restricted nodes in a cluster

You can restrict nodes that are in the DMZ so that your network is secure. You can specify which nodes are restricted in the local management interface.

About this task

The following restrictions apply to restricted nodes:

Restricted nodes cannot be promoted to any of the master roles.

Restricted nodes cannot use the Policy Administration tool to modify the security policy.

Restricted nodes do not contain a replica of the data that is stored by the embedded user registry.

You can restrict a node when you register a node in a cluster or at any time from the master local management interface. You can also restrict several nodes in a cluster.

Procedure

Select the steps for the task you want to complete:

Configuring a restricted node during registration

Configure a restricted node when you register the node by using the local management interface.

Register a node to a cluster.

For more information, see Managing cluster configuration.

Check Join as restricted node in the Join Cluster window.

Click Join to add the appliance to a cluster as a restricted node.

Configure a restricted node in a cluster

Use the local management interface to specify a restricted node in a cluster.

Log on to the master appliance.

From the top menu of the local management interface, select Manage System Settings > Cluster Configuration.

Select the Overview tab.

Select the node to be set as restricted in the Nodes grid.

Click Restricted Node.

Click Submit.

Parent topic: Cluster support

Cluster maintenancemaintenanceclustersmaintenanceCluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.Firmware updates in a clusterYou must apply firmware updates to the masters in order of priority before you install updates on the remaining nodes.Back up proceduresIn a clustered environment, you cannot use VMWare snapshots to back up your virtual machines. For reliable backups, use appliance snapshots to back up the cluster.

Cluster maintenance

Firmware updates in a cluster
You must apply firmware updates to the masters in order of priority before you install updates on the remaining nodes.

Back up procedures
In a clustered environment, you cannot use VMWare snapshots to back up your virtual machines. For reliable backups, use appliance snapshots to back up the cluster.

Parent topic: Cluster support

Firmware updates in a clusterYou must apply firmware updates to the masters in order of priority before you install updates on the remaining nodes.updatesfirmwarefirmwareupdatesUpgrade the cluster members in the following order as applicable to your environment:Primary masterSecondary masterTertiary masterQuaternary masterOther nodesCluster maintenance

Firmware updates in a cluster

You must apply firmware updates to the masters in order of priority before you install updates on the remaining nodes.

Upgrade the cluster members in the following order as applicable to your environment:

Primary master

Secondary master

Tertiary master

Quaternary master

Other nodes

Parent topic: Cluster maintenance

Back up proceduresIn a clustered environment, you cannot use VMWare snapshots to back up your virtual machines. For reliable backups, use appliance snapshots to back up the cluster.backupappliancessnapshotsYou can complete an appliance snapshot on each cluster member to effectively back up the cluster. An appliance snapshot of the primary master includes all of the cluster configuration and runtime data. When the primary master is restored from an appliance snapshot, it updates every cluster member with the restored configuration.An appliance snapshot of a node other than the primary master excludes the runtime database information. When a cluster member is restored from a snapshot, it contacts the primary master to obtain up-to-date configuration and runtime information. To effectively back up the cluster, complete an appliance snapshot of the primary master after any change to the cluster configuration. For example, take a snapshot after you add or remove a node to ensure that the correct nodes are included in the cluster after a restore.Cluster maintenance

Back up procedures

In a clustered environment, you cannot use VMWare snapshots to back up your virtual machines. For reliable backups, use appliance snapshots to back up the cluster.

You can complete an appliance snapshot on each cluster member to effectively back up the cluster. An appliance snapshot of the primary master includes all of the cluster configuration and runtime data. When the primary master is restored from an appliance snapshot, it updates every cluster member with the restored configuration.

An appliance snapshot of a node other than the primary master excludes the runtime database information. When a cluster member is restored from a snapshot, it contacts the primary master to obtain up-to-date configuration and runtime information.

To effectively back up the cluster, complete an appliance snapshot of the primary master after any change to the cluster configuration. For example, take a snapshot after you add or remove a node to ensure that the correct nodes are included in the cluster after a restore.

Parent topic: Cluster maintenance

Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.clustersrulesupdateschangesTry to limit the number of changes that are made to the cluster configuration in a single policy update. After you save the policy changes, you must deploy the updates for the changes to take effect.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.Cluster architecture rulesThe architecture of a cluster, including the appointment of masters, is governed by numerous rules.Cluster node availabilityIf a node is unavailable when you update the cluster configuration, it contacts the primary master to get the updated configuration information when it comes back online. If the primary master is offline at the same time as the secondary master, the primary master comes back online with read-only databases until the secondary master is available.First management interfaceIn a clustered environment, the IP address of the first management interface is used as the node identifier. For this reason, a static IP address must be assigned to the first management interface of the appliance.Cluster registrationBefore you register or unregister a node in a cluster, consider these registration rules.Cluster portsWhen you configure an appliance cluster, you are required to specify the starting port number for a range of ports to be dedicated to the services that are provided by the cluster.

Cluster configuration rules

When you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.

General notes:

Try to limit the number of changes that are made to the cluster configuration in a single policy update.

After you save the policy changes, you must deploy the updates for the changes to take effect.

Cluster architecture rules
The architecture of a cluster, including the appointment of masters, is governed by numerous rules.

Cluster node availability
If a node is unavailable when you update the cluster configuration, it contacts the primary master to get the updated configuration information when it comes back online. If the primary master is offline at the same time as the secondary master, the primary master comes back online with read-only databases until the secondary master is available.

First management interface
In a clustered environment, the IP address of the first management interface is used as the node identifier. For this reason, a static IP address must be assigned to the first management interface of the appliance.

Cluster registration
Before you register or unregister a node in a cluster, consider these registration rules.

Cluster ports
When you configure an appliance cluster, you are required to specify the starting port number for a range of ports to be dedicated to the services that are provided by the cluster.

Parent topic: Cluster support

Cluster architecture rulesCluster architecture rulesCluster architecture rulesThe architecture of a cluster, including the appointment of masters, is governed by numerous rules.clustersrulesnodesmaster nodesarchitecture rulesrulesA node must be a registered member of the cluster before it can be promoted to a master. The only exception is the primary master when there are no other nodes in the cluster.At a minimum, you must specify a primary master for the cluster.You must activate the product on the primary master of the cluster before any other node. If you use the internal runtime database in an Advanced Access Control-activated cluster, activate the Advanced Access Control-activated appliance on the secondary master before the other nodes.Ensure that the product is activated on the masters before it is activated on any of the individual nodes in the cluster.The primary and secondary masters of the cluster must be activated at the highest level of all the nodes in the cluster. If any node in the cluster is activated with Security Access Manager base, the primary and secondary masters must also be activated with Security Access Manager base. Similarly, if any node in the cluster is activated with Advanced Access Control, the primary and secondary masters must also be activated with Advanced Access Control. Activation levels are validated when:A node joins the cluster. Such validation is to ensure that the primary and secondary masters are activated to at least the same level.A new primary or secondary master is set. Such validation is to ensure that the activation level of the new master is at least at the same level as the current primary master.You cannot specify a master without first specifying each of the prior masters. For example, you must specify the secondary master before you can specify a tertiary master.If you specify a secondary master, you must also specify the master external reference entity (ERE).You can modify the cluster policy on the primary master only, unless you are promoting a local node to primary master in a disaster recovery situation.Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.

Cluster architecture rules

The architecture of a cluster, including the appointment of masters, is governed by numerous rules.

A node must be a registered member of the cluster before it can be promoted to a master. The only exception is the primary master when there are no other nodes in the cluster.

At a minimum, you must specify a primary master for the cluster.

You must activate the product on the primary master of the cluster before any other node. If you use the internal runtime database in an Advanced Access Control-activated cluster, activate the Advanced Access Control-activated appliance on the secondary master before the other nodes.

Ensure that the product is activated on the masters before it is activated on any of the individual nodes in the cluster.

The primary and secondary masters of the cluster must be activated at the highest level of all the nodes in the cluster. If any node in the cluster is activated with Security Access Manager base, the primary and secondary masters must also be activated with Security Access Manager base. Similarly, if any node in the cluster is activated with Advanced Access Control, the primary and secondary masters must also be activated with Advanced Access Control. Activation levels are validated when:

A node joins the cluster. Such validation is to ensure that the primary and secondary masters are activated to at least the same level.

A new primary or secondary master is set. Such validation is to ensure that the activation level of the new master is at least at the same level as the current primary master.

You cannot specify a master without first specifying each of the prior masters. For example, you must specify the secondary master before you can specify a tertiary master.

If you specify a secondary master, you must also specify the master external reference entity (ERE).

You can modify the cluster policy on the primary master only, unless you are promoting a local node to primary master in a disaster recovery situation.

Parent topic: Cluster configuration rules

Cluster node availabilityIf a node is unavailable when you update the cluster configuration, it contacts the primary master to get the updated configuration information when it comes back online. If the primary master is offline at the same time as the secondary master, the primary master comes back online with read-only databases until the secondary master is available.clustersnodesavailabilitymastersavailabilityA node can become unavailable for a number of reasons, including a shutdown request, system failure, or networking failure. If a cluster node is not available during a cluster configuration change, it contacts the primary master for up-to-date information when it restarts. There might be a slight delay where the restored node tries to use the old policy and configuration information before it retrieves the missed updates.The relationship between the primary and secondary nodes can be temporarily affected if both nodes are shut down simultaneously, and only one is powered back up.  Until the other node is up, the databases on the newly powered up node are in read-only mode.  When you power up the other node, the databases on the primary node become writable.You can then shut down the secondary node without affecting the write capability on the primary server.  It is only if both master nodes are offline at the same time that the restored primary master becomes read-only until the secondary master is back online. This situation can be serious if the secondary node fails and the primary node stops for any reason.  In this case, the primary node is not writable when it restarts until a secondary node is either started, or removed from the cluster. If the secondary node is removed, the primary master can operate as a single master in the cluster. You must address a failed primary or secondary master as soon as possible to avoid this situation.The above discussion about cluster node availability applies only to the configuration database and an embedded runtime database.Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.

Cluster node availability

If a node is unavailable when you update the cluster configuration, it contacts the primary master to get the updated configuration information when it comes back online. If the primary master is offline at the same time as the secondary master, the primary master comes back online with read-only databases until the secondary master is available.

A node can become unavailable for a number of reasons, including a shutdown request, system failure, or networking failure. If a cluster node is not available during a cluster configuration change, it contacts the primary master for up-to-date information when it restarts. There might be a slight delay where the restored node tries to use the old policy and configuration information before it retrieves the missed updates.

The relationship between the primary and secondary nodes can be temporarily affected if both nodes are shut down simultaneously, and only one is powered back up.  Until the other node is up, the databases on the newly powered up node are in read-only mode.  When you power up the other node, the databases on the primary node become writable.

You can then shut down the secondary node without affecting the write capability on the primary server.  It is only if both master nodes are offline at the same time that the restored primary master becomes read-only until the secondary master is back online.

This situation can be serious if the secondary node fails and the primary node stops for any reason.  In this case, the primary node is not writable when it restarts until a secondary node is either started, or removed from the cluster. If the secondary node is removed, the primary master can operate as a single master in the cluster. You must address a failed primary or secondary master as soon as possible to avoid this situation.

Note: The above discussion about cluster node availability applies only to the configuration database and an embedded runtime database.

Parent topic: Cluster configuration rules

First management interfaceIn a clustered environment, the IP address of the first management interface is used as the node identifier. For this reason, a static IP address must be assigned to the first management interface of the appliance.clustersnodesidentifiersfirst management interfaceIP addressesWhen you change the first management interface of a non-master node, the cluster is updated automatically. You cannot change the IP address of the first management interface on a master. If you want to change the first management interface on a master node, you must first demote the node from master. You can then promote the node to master again and update any external client references in the distributed session cache.Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.

First management interface

In a clustered environment, the IP address of the first management interface is used as the node identifier. For this reason, a static IP address must be assigned to the first management interface of the appliance.

When you change the first management interface of a non-master node, the cluster is updated automatically.

You cannot change the IP address of the first management interface on a master. If you want to change the first management interface on a master node, you must first demote the node from master. You can then promote the node to master again and update any external client references in the distributed session cache.

Parent topic: Cluster configuration rules

Cluster registrationBefore you register or unregister a node in a cluster, consider these registration rules.clustersregistrationregistrationYou must activate your products on the primary master before you activate the product on any other nodes.If you are using the internal runtime database in a cluster, you must also activate the product on the secondary master before the other nodes.For more information about the activation process, see Activating the product and buying supportActivate the product after installation so you can use all available features. You can optionally import a support license file to receive updates to the appliance.. A node cannot be registered with a cluster if it is already a member of another cluster. In this situation, the node must first be unregistered from its current cluster.Node registration must occur directly through the local management interface of the appliance that you want to join the cluster. The appliance that you are registering must be able to communicate with the primary master.Node unregistration must occur on the primary master.A node cannot be unregistered if it is configured as a master. You must first demote the node from master and promote another node as the master.Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.

Cluster registration

Before you register or unregister a node in a cluster, consider these registration rules.

You must activate your products on the primary master before you activate the product on any other nodes.

If you are using the internal runtime database in a cluster, you must also activate the product on the secondary master before the other nodes.

For more information about the activation process, see Activating the product and buying support.

A node cannot be registered with a cluster if it is already a member of another cluster. In this situation, the node must first be unregistered from its current cluster.

Node registration must occur directly through the local management interface of the appliance that you want to join the cluster. The appliance that you are registering must be able to communicate with the primary master.

Node unregistration must occur on the primary master.

A node cannot be unregistered if it is configured as a master. You must first demote the node from master and promote another node as the master.

Parent topic: Cluster configuration rules

Cluster portsWhen you configure an appliance cluster, you are required to specify the starting port number for a range of ports to be dedicated to the services that are provided by the cluster.It is important to note that these ports are for internal use only and are not used by the cluster for communication between nodes. All of the communication that takes place between nodes in the cluster occurs over port 22. This means that if your nodes are separated by a firewall, you only need to open up traffic on port 22 to allow the cluster services of the various nodes to communicate with each other.The following diagram illustrates the communication requirements of the various roles in the cluster.Communication in a cluster using port 22If you want to manually configure a DSC client on a node within the cluster, use the following addresses and ports:The following examples assume that the first port is 2020.NodePort ExamplePrimaryfirst_port + 15127.0.0.1 15 127.0.0.1:2035Secondary first_port + 16127.0.0.1 16 127.0.0.1:2036Tertiary first_port + 17127.0.0.1 17 127.0.0.1:2037Quarternary first_port + 18127.0.0.1 18 127.0.0.1:2038Some additional settings are required to configure a DSC client on a node within the cluster. Set the priority for each distributed session cache server to 9 within the server stanza entry in the [dsess-cluster] stanza. Also set the load-balance stanza entry in the [dsess-cluster] stanza to no. The DSC does not support load balancing. Setting the load-balance configuration entry to no prevents connection attempts to servers for which the connection attempts will certainly fail.serverUse the server entry in the [dsess-cluster] stanza to specify each distributed session cache server and its priority in the cluster.load-balanceControls the behavior when multiple servers with the same configured priority are available. Cluster configuration rulesWhen you are configuring a cluster of Security Access Manager appliances, consider the following rules that govern cluster configuration.

Cluster ports

When you configure an appliance cluster, you are required to specify the starting port number for a range of ports to be dedicated to the services that are provided by the cluster.

It is important to note that these ports are for internal use only and are not used by the cluster for communication between nodes. All of the communication that takes place between nodes in the cluster occurs over port 22. This means that if your nodes are separated by a firewall, you only need to open up traffic on port 22 to allow the cluster services of the various nodes to communicate with each other.

The following diagram illustrates the communication requirements of the various roles in the cluster.

Figure 66. Communication in a cluster using port 22Communication in a cluster using port 22

If you want to manually configure a DSC client on a node within the cluster, use the following addresses and ports:

Note: The following examples assume that the first port is 2020.

Node | Port | Example
Primary | first_port + 15 | 127.0.0.1 15 127.0.0.1:2035
Secondary | first_port + 16 | 127.0.0.1 16 127.0.0.1:2036
Tertiary | first_port + 17 | 127.0.0.1 17 127.0.0.1:2037
Quarternary | first_port + 18 | 127.0.0.1 18 127.0.0.1:2038

Some additional settings are required to configure a DSC client on a node within the cluster. Set the priority for each distributed session cache server to 9 within the server stanza entry in the [dsess-cluster] stanza. Also set the load-balance stanza entry in the [dsess-cluster] stanza to no. The DSC does not support load balancing. Setting the load-balance configuration entry to no prevents connection attempts to servers for which the connection attempts will certainly fail.

Parent topic: Cluster configuration rules

Related reference:

server

load-balance

Data loss considerationsThe cluster services might lose data under certain circumstances. clustersdatalossdistributed session cachepolicy datadata lossdatabasesruntimedataDistributed session cacheThe policy data, which is used to indicate the first port that is available for use by the cluster, is changed.The policy data that defines the masters is changed.Configuration databaseAn appliance that is operating as a single node cluster fails. In this situation, you must rely on snapshot information to restore the configuration database.Internal runtime databaseAn appliance that is operating as a single node cluster fails. In this situation, there is no recovery possible. The primary master fails, and no secondary master is configured.The maximum size of the internal runtime database is adjusted such that the new maximum size is smaller than the existing database.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Data loss considerations

The cluster services might lose data under certain circumstances.

Distributed session cache

The policy data, which is used to indicate the first port that is available for use by the cluster, is changed.

The policy data that defines the masters is changed.

Configuration database

An appliance that is operating as a single node cluster fails. In this situation, you must rely on snapshot information to restore the configuration database.

Internal runtime database

An appliance that is operating as a single node cluster fails. In this situation, there is no recovery possible.

The primary master fails, and no secondary master is configured.

The maximum size of the internal runtime database is adjusted such that the new maximum size is smaller than the existing database.

Parent topic: Cluster support

Deployment patternRead this section to understand the components of a typical cluster environment and how to set up such environments. In this typical deployment scenario, the cluster incorporates both a Security Access Manager base appliance and an appliance with Advanced Access Control activated.The following diagram illustrates a sample cluster environment.Sample cluster environmentThis environment consists of the following components:An external user registry, which can be a federated registry.Numerous appliances, namely:A policy serverOne or more appliances that provide the Advanced Access Control runtime servicePotentially an internal web reverse proxy to handle corporate trafficOne or more web reverse proxies in the DMZ to handle public trafficIn this scenario, all of the appliances reside in the same appliance cluster, with the policy server running on the primary master. Any of the other appliances that are running in the trusted zone can be enrolled as the secondary master, or you can have a dedicated secondary master appliance. The tertiary and quaternary masters are only required if you are using the distributed session cache across multiple data centers.It is advisable to enroll the appliances that reside in the DMZ as restricted nodes. A restricted node imposes extra security constraints on the appliance, namely you cannot modify the security policy on these appliances or promote any of these appliances to a master.In this environment, it is preferable to enable the replication of the Security Access Manager runtime environment and SSL certificate key files. For instructions on how to enable such settings, see Managing cluster configurationFrom the Cluster Configuration management page, administer cluster support for the appliance.. The replication of the Security Access Manager runtime environment has the following advantages:You no longer need to configure the runtime environment manually on any node in the environment. The configuration information is automatically obtained from the primary master.If the primary master becomes unavailable (for example, due to hardware failure), you can promote one of the other unrestricted nodes to become a primary master and you do not lose the policy database. Nodes within the cluster are also automatically notified of the new policy server.The following steps describe the recommended way in which to set up the environment:Install each of the appliances. You should also:Configure the networking.Activate the required offerings. The primary master must be activated with each offering that you will be using in your environment (for example, in this environment the primary master would be activated with both Security Access Manager base and Advanced Access Control). Change the cluster configuration on the policy server to make it the primary master of a multi-node cluster.On the primary master, configure the Security Access Manager runtime environment, including the policy server.Enable the cluster replication of the runtime environment and certificate database.Join each appliance to the cluster, one at a time. Join any appliances that reside in the DMZ as a restricted node.Change the cluster configuration on the primary master to promote one of the unrestricted nodes to the role of secondary master. The node that is being promoted to secondary master must also be activated with each of the offerings that are used in the environment.Configure the Security Access Manager base and Advanced Access Control security policies.Configure the web reverse proxy instances on each of your Security Access Manager nodes.Cluster supportThe Security Access Manager appliance includes cluster support, which allows multiple appliances to share configuration information and runtime information to work together in a clustered environment.

Deployment pattern

Read this section to understand the components of a typical cluster environment and how to set up such environments. In this typical deployment scenario, the cluster incorporates both a Security Access Manager base appliance and an appliance with Advanced Access Control activated.

The following diagram illustrates a sample cluster environment.

Figure 67. Sample cluster environmentSample cluster environment

This environment consists of the following components:

An external user registry, which can be a federated registry.

Numerous appliances, namely:

A policy server

One or more appliances that provide the Advanced Access Control runtime service

Potentially an internal web reverse proxy to handle corporate traffic

One or more web reverse proxies in the DMZ to handle public traffic

In this scenario, all of the appliances reside in the same appliance cluster, with the policy server running on the primary master. Any of the other appliances that are running in the trusted zone can be enrolled as the secondary master, or you can have a dedicated secondary master appliance. The tertiary and quaternary masters are only required if you are using the distributed session cache across multiple data centers.

It is advisable to enroll the appliances that reside in the DMZ as restricted nodes. A restricted node imposes extra security constraints on the appliance, namely you cannot modify the security policy on these appliances or promote any of these appliances to a master.

In this environment, it is preferable to enable the replication of the Security Access Manager runtime environment and SSL certificate key files. For instructions on how to enable such settings, see Managing cluster configuration. The replication of the Security Access Manager runtime environment has the following advantages:

You no longer need to configure the runtime environment manually on any node in the environment. The configuration information is automatically obtained from the primary master.

If the primary master becomes unavailable (for example, due to hardware failure), you can promote one of the other unrestricted nodes to become a primary master and you do not lose the policy database. Nodes within the cluster are also automatically notified of the new policy server.

The following steps describe the recommended way in which to set up the environment:

Install each of the appliances. You should also:

Configure the networking.

Activate the required offerings.

Note: The primary master must be activated with each offering that you will be using in your environment (for example, in this environment the primary master would be activated with both Security Access Manager base and Advanced Access Control).

Change the cluster configuration on the policy server to make it the primary master of a multi-node cluster.

On the primary master, configure the Security Access Manager runtime environment, including the policy server.

Enable the cluster replication of the runtime environment and certificate database.

Join each appliance to the cluster, one at a time. Join any appliances that reside in the DMZ as a restricted node.

Change the cluster configuration on the primary master to promote one of the unrestricted nodes to the role of secondary master. The node that is being promoted to secondary master must also be activated with each of the offerings that are used in the environment.

Configure the Security Access Manager base and Advanced Access Control security policies.

Configure the web reverse proxy instances on each of your Security Access Manager nodes.

Parent topic: Cluster support

Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. AdministeringIBM Security Access Manager provides information about administering supported activation levels.Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.Web Portal ManagerSecurity Access Manager has both command-line and graphical interface interfaces for managing domains, users, groups, permissions, policies, and other resources in your enterprise.Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.Default security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.Manage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Protected object policy managementThe access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service. Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.Manage users and groupsAn initial domain administrator is created when a new domain is created.Certificate and password managementTo securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.Server managementThis chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.High availability of the policy serverThis chapter provides information about ensuring that Security Access Manager provides high availability for the policy server in case a server failure occurs. Multiple-tenancy policy serverA multiple-tenancy server is a server that supports the hosting of multiple customers on a single server instead of on multiple client systems. Diagnostics and auditingSecurity Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers.Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].User registry differencesEach user registry presents unique concerns when integrated with Security Access Manager. This release of Security Access Manager supports the specified LDAP user registries.pdadmin to Web Portal Manager equivalentsThis appendix shows the mapping of the administration pdadmin commands to Web Portal Manager.Managing user registriesThis appendix contains a subset of user registry tasks that are specific to installing Security Access Manager.

Access Manager Platform and Supporting Components administration

The Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy.

Security Access Manager overview
Security Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.

Web Portal Manager
Security Access Manager has both command-line and graphical interface interfaces for managing domains, users, groups, permissions, policies, and other resources in your enterprise.

Security Access Manager administration
Administering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Default security policy
Security Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.

Domain management
An administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.

Object space management
Security Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.

Manage protected objects
An object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.

Manage access control
A domain administrator can use access control list (ACL) policies to control access to objects.

Protected object policy management
The access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service.

Authorization rules management
These topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.

Manage users and groups
An initial domain administrator is created when a new domain is created.

Certificate and password management
To securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.

Server management
This chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.

High availability of the policy server
This chapter provides information about ensuring that Security Access Manager provides high availability for the policy server in case a server failure occurs.

Multiple-tenancy policy server
A multiple-tenancy server is a server that supports the hosting of multiple customers on a single server instead of on multiple client systems.

Diagnostics and auditing
Security Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers.

Guidelines for changing configuration files
These guidelines are provided to help you change the Security Access Manager configuration files.

Configuration file reference
The way you use configuration files controls the operation of the Security Access Manager servers.

Configuration file stanza reference
Within configuration files, stanza labels occur within brackets, such as [stanza-name].

User registry differences
Each user registry presents unique concerns when integrated with Security Access Manager. This release of Security Access Manager supports the specified LDAP user registries.

pdadmin to Web Portal Manager equivalents
This appendix shows the mapping of the administration pdadmin commands to Web Portal Manager.

Managing user registries
This appendix contains a subset of user registry tasks that are specific to installing Security Access Manager.

Parent topic: Administering

Security Access Manager overviewSecurity Access Manager overviewSecurity Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.overview, Security Access ManagerintroductionSecurity Access Managerframework, descriptionsSecurity Access Manager supports authentication, authorization, data security, and resource management capabilities. You use Security Access Manager in conjunction with standard Internet-based applications to build highly secure and well-managed intranets.Security Access Manager provides the following frameworks: Authentication frameworkThe Security Access Manager authentication service uses a wide range of built-in authenticators and supports external authenticators.Authorization frameworkThe authorization service, accessed through a standard authorization application programming interface (API), provides permit and deny decisions on access requests for native Security Access Manager servers and other applications. The authorization service, together with resource managers, provides a standard authorization mechanism for business network systems.Security Access Manager can be integrated into existing and emerging infrastructures to provide secure, centralized policy management capability.The following resource managers are some of the existing resource managers: IBM Security Access Manager for Web WebSEALManages and protects web-based information and resources. WebSEAL is included with Security Access Manager.IBM Security Access Manager for Web for Operating SystemsProvides a layer of authorization policy enforcement on Linux and UNIX operating systems in addition to that provided by the native operating system.Existing applications can take advantage of the Security Access Manager authorization service and provide a common security policy for the entire enterprise.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Core technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.Security policy overviewThe goal of any security policy is to adequately protect business assets and resources with a minimal amount of administrative effort. High-level steps include determining which resources to protect and the level of access that users get to those resources.Authorization API standardAuthorization services are a critical part of the security architecture of an application. After a user passes the authentication process, authorization services proceed to enforce the business policy by determining what services and information the user can access.Authorization: conceptual modelIn security systems, authorization is distinct from authentication. Authorization determines whether an authenticated client has the required permissions to do a task on a specific resource in a domain. Authentication ensures that the individual is who that individual claims to be.Security Access Manager authorization serviceThe authorization service is responsible for the authorization decision-making process that enforces a network security policy. Implementation of a network security policyControlling user and group participation in the domain and applying rules to resources that require protection determine the security policy for a domain. These rules are defined by access control lists (ACLs), protected object policies (POPs), and authorization rules. Security Access Manager authorization APIThe Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself. External authorization capabilitySecurity Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements.

Security Access Manager overview

Security Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.

Security Access Manager supports authentication, authorization, data security, and resource management capabilities. You use Security Access Manager in conjunction with standard Internet-based applications to build highly secure and well-managed intranets.

Security Access Manager provides the following frameworks:

Authentication framework

The Security Access Manager authentication service uses a wide range of built-in authenticators and supports external authenticators.

Authorization framework

The authorization service, accessed through a standard authorization application programming interface (API), provides permit and deny decisions on access requests for native Security Access Manager servers and other applications.

The authorization service, together with resource managers, provides a standard authorization mechanism for business network systems.

Security Access Manager can be integrated into existing and emerging infrastructures to provide secure, centralized policy management capability.

The following resource managers are some of the existing resource managers:

IBM Security Access Manager for Web WebSEAL

Manages and protects web-based information and resources. WebSEAL is included with Security Access Manager.

IBM Security Access Manager for Web for Operating Systems

Provides a layer of authorization policy enforcement on Linux and UNIX operating systems in addition to that provided by the native operating system.

Existing applications can take advantage of the Security Access Manager authorization service and provide a common security policy for the entire enterprise.

Core technologies
The Security Access Manager network security management solution provides and supports several core technologies and features.

Security policy overview
The goal of any security policy is to adequately protect business assets and resources with a minimal amount of administrative effort. High-level steps include determining which resources to protect and the level of access that users get to those resources.

Authorization API standard
Authorization services are a critical part of the security architecture of an application. After a user passes the authentication process, authorization services proceed to enforce the business policy by determining what services and information the user can access.

Authorization: conceptual model
In security systems, authorization is distinct from authentication. Authorization determines whether an authenticated client has the required permissions to do a task on a specific resource in a domain. Authentication ensures that the individual is who that individual claims to be.

Security Access Manager authorization service
The authorization service is responsible for the authorization decision-making process that enforces a network security policy.

Implementation of a network security policy
Controlling user and group participation in the domain and applying rules to resources that require protection determine the security policy for a domain. These rules are defined by access control lists (ACLs), protected object policies (POPs), and authorization rules.

Security Access Manager authorization API
The Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself.

External authorization capability
Security Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements.

Parent topic: Access Manager Platform and Supporting Components administration

Core technologiesCore technologiesCore technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.core technologiesSee the following topics for information:Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.AuthenticationAuthentication is the first step a user must take when making a request for a resource that is protected by Security Access Manager. During authentication, a user identity is validated. AuthorizationAuthorization enforces the security policy.Quality of ProtectionQuality of Protection (QoP) is the degree to which Security Access Manager protects any information that is transmitted between a client and a server. Security standards configurations (compliance types)You can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government. ScalabilityScalability is the ability to respond to increasing numbers of users who access resources in the domain. Security Access Manager uses several techniques to provide scalability. AccountabilitySecurity Access Manager provides several logging and auditing capabilities to increase accountability for server activity.Centralized managementSecurity Access Manager uses two user interfaces to manage security policies and the Security Access Manager servers.

Core technologies

The Security Access Manager network security management solution provides and supports several core technologies and features.

See the following topics for information:

Authentication
Authentication is the first step a user must take when making a request for a resource that is protected by Security Access Manager. During authentication, a user identity is validated.

Authorization
Authorization enforces the security policy.

Quality of Protection
Quality of Protection (QoP) is the degree to which Security Access Manager protects any information that is transmitted between a client and a server.

Security standards configurations (compliance types)
You can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government.

Scalability
Scalability is the ability to respond to increasing numbers of users who access resources in the domain. Security Access Manager uses several techniques to provide scalability.

Accountability
Security Access Manager provides several logging and auditing capabilities to increase accountability for server activity.

Centralized management
Security Access Manager uses two user interfaces to manage security policies and the Security Access Manager servers.

Parent topic: Security Access Manager overview

AuthenticationAuthenticationAuthenticationAuthentication is the first step a user must take when making a request for a resource that is protected by Security Access Manager. During authentication, a user identity is validated. authenticationintroductionThe authentication process depends on the specific requirements of the service-providing application. Security Access Manager allows a highly flexible approach to authentication through the use of the authorization API.Security Access Manager provides built-in support of user name and password authentication through the authorization API. Applications can build any custom authentication mechanism that uses the authorization API.Core technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.

Authentication

Authentication is the first step a user must take when making a request for a resource that is protected by Security Access Manager. During authentication, a user identity is validated.

The authentication process depends on the specific requirements of the service-providing application. Security Access Manager allows a highly flexible approach to authentication through the use of the authorization API.

Security Access Manager provides built-in support of user name and password authentication through the authorization API. Applications can build any custom authentication mechanism that uses the authorization API.

Parent topic: Core technologies

AuthorizationAuthorizationAuthorizationAuthorization enforces the security policy.authorizationintroductionThe authorization process determines which objects a user can access and which actions a user can take on those objects. The authorization process grants appropriate access to the user.Security Access Manager handles authorization by using the following methods: Security Access Manager authorization service.Access control lists (ACLs), protected object policies (POPs), and authorization rules for fine-grained access control.Standards-based authorization API, which uses the aznAPI for C language applications, and the Java Authentication and Authorization Service (JAAS) for Java language applications.External authorization service capability.Core technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.

Authorization

Authorization enforces the security policy.

The authorization process determines which objects a user can access and which actions a user can take on those objects.

The authorization process grants appropriate access to the user.

Security Access Manager handles authorization by using the following methods:

Security Access Manager authorization service.

Access control lists (ACLs), protected object policies (POPs), and authorization rules for fine-grained access control.

Standards-based authorization API, which uses the aznAPI for C language applications, and the Java™ Authentication and Authorization Service (JAAS) for Java language applications.

External authorization service capability.

Parent topic: Core technologies

Quality of ProtectionQuality of ProtectionQuality of ProtectionQuality of Protection (QoP) is the degree to which Security Access Manager protects any information that is transmitted between a client and a server. Quality of ProtectionintroductionQoPThe quality of data protection is determined by the combined effect of encryption standards and modification-detection algorithms. The resource manager is responsible for ensuring that the quality of data protection is enforced.Security Access Manager supports the following levels of Quality of Protection: Standard Transmission Control Protocol (TCP) communication (no protection)Data integrity protects messages (data stream) from being modified during network communicationData privacy protects messages from being modified or inspected during network communicationCore technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.Supported encryption ciphersSecurity Access Manager uses encryption ciphers from GSKit and Java Secure Socket Extension (JSSE). Secure communicationSecurity Access Manager supports the data integrity and data privacy provided by the Secure Socket Layer (SSL) communication protocol and the Transport Layer Security (TLS) communication protocol.

Quality of Protection

Quality of Protection (QoP) is the degree to which Security Access Manager protects any information that is transmitted between a client and a server.

The quality of data protection is determined by the combined effect of encryption standards and modification-detection algorithms. The resource manager is responsible for ensuring that the quality of data protection is enforced.

Security Access Manager supports the following levels of Quality of Protection:

Standard Transmission Control Protocol (TCP) communication (no protection)

Data integrity protects messages (data stream) from being modified during network communication

Data privacy protects messages from being modified or inspected during network communication

Supported encryption ciphers
Security Access Manager uses encryption ciphers from GSKit and Java™ Secure Socket Extension (JSSE).

Secure communication
Security Access Manager supports the data integrity and data privacy provided by the Secure Socket Layer (SSL) communication protocol and the Transport Layer Security (TLS) communication protocol.

Parent topic: Core technologies

Supported encryption ciphersSupported encryption ciphersSupported encryption ciphersSecurity Access Manager uses encryption ciphers from GSKit and Java Secure Socket Extension (JSSE). encryptionsupported ciphersencryptionGSKitencryptionJSSETo learn about these encryption ciphers, see the GSKit and JSSE documentation.Quality of ProtectionQuality of Protection (QoP) is the degree to which Security Access Manager protects any information that is transmitted between a client and a server.

Supported encryption ciphers

Security Access Manager uses encryption ciphers from GSKit and Java™ Secure Socket Extension (JSSE).

To learn about these encryption ciphers, see the GSKit and JSSE documentation.

Parent topic: Quality of Protection

Secure communicationSecure communicationSecure communicationSecurity Access Manager supports the data integrity and data privacy provided by the Secure Socket Layer (SSL) communication protocol and the Transport Layer Security (TLS) communication protocol.communicationSSLcommunicationTLScommunicationFIPS modeSSLcommunicationSecure Socket LayerTLScommunicationTransport Layer SecurityFIPScommunicationFederal Information Processing StandardsThe SSL handshake protocol provides security and privacy over the Internet. SSL works with public key for authentication and secret key to encrypt data that is transferred over the SSL connection.The TLS protocol meets the Federal Information Processing Standards (FIPS) 140-2 standard. The FIPS standard describes the requirements of the United States federal government for handling sensitive, but unclassified, use of information technology products. When FIPS mode is enabled in Security Access Manager, TLS version 1 (TLSv1) is used instead of SSL version 3 (SSLv3).Security Access Manager generates keys and certificates with FIPS-approved operations. The client- and server-side keys and certificates are always FIPS approved.To switch from SSL to TLS, you must change all server and remote run time configurations. In Security Access Manager, the protocol configuration specifies the FIPS mode. When FIPS mode is enabled, it uses the TLS protocol. When FIPS mode is disabled, it uses the SSL protocol. SSL and TLS protocols cannot be mixed in a Security Access Manager environment. Previous releases of IBM Security Access Manager runtime that did not support TLS cannot communicate with a server that is enabled for FIPS.Quality of ProtectionQuality of Protection (QoP) is the degree to which Security Access Manager protects any information that is transmitted between a client and a server.

Secure communication

Security Access Manager supports the data integrity and data privacy provided by the Secure Socket Layer (SSL) communication protocol and the Transport Layer Security (TLS) communication protocol.

The SSL handshake protocol provides security and privacy over the Internet. SSL works with public key for authentication and secret key to encrypt data that is transferred over the SSL connection.

The TLS protocol meets the Federal Information Processing Standards (FIPS) 140-2 standard. The FIPS standard describes the requirements of the United States federal government for handling sensitive, but unclassified, use of information technology products. When FIPS mode is enabled in Security Access Manager, TLS version 1 (TLSv1) is used instead of SSL version 3 (SSLv3).

Security Access Manager generates keys and certificates with FIPS-approved operations. The client- and server-side keys and certificates are always FIPS approved.

To switch from SSL to TLS, you must change all server and remote run time configurations. In Security Access Manager, the protocol configuration specifies the FIPS mode. When FIPS mode is enabled, it uses the TLS protocol. When FIPS mode is disabled, it uses the SSL protocol.

Note: SSL and TLS protocols cannot be mixed in a Security Access Manager environment. Previous releases of IBM Security Access Manager runtime that did not support TLS cannot communicate with a server that is enabled for FIPS.

Parent topic: Quality of Protection

Security standards configurations (compliance types)Security standards configurations (compliance types)Security standardsYou can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government. securitystandardscompliance typessecuritystandardsconfigurationSecurity Access Manager uses cryptography in the following areas: To create and replace internal, self-signed certificates. These certificates are used by Security Access Manager Runtime and Security Access Manager server to authenticate with each other.Secure communication between the runtime and servers.Secure communication to LDAP.Secure communication to Syslog servers.The Security Access Manager Base components integrate cryptographic modules, which include IBM Global Security Kit (GSKit) 8, Java Secure Socket Extension (JSSE), and Java Cryptography Extension (JCE). Most of the requirements in the standards are handled in GSKit, JSSE, and JCE, which must undergo the certification process to meet government standards. Security Access Manager Base components must be configured to run with GSKit, JSSE, and JCE that are enabled for a particular standard.Core technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.FIPS 140-2The Federal Information Processing Standards (FIPS) specify federal government requirements for cryptographic modules. FIPS 140-2 is a National Institute of Standards and Technology standard.SP 800-131aSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. Suite BSuite B is a security standard that is developed by the National Security Agency (NSA) that establishes a cryptographic interoperability strategy. Suite B is similar to SP 800-131a, but it has tighter restrictions.Java properties that enable the security standardsThe IBM® virtual machine for Java (JVM) runs in a specific security mode based on system properties.

Security standards configurations (compliance types)

You can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government.

Security Access Manager uses cryptography in the following areas:

To create and replace internal, self-signed certificates. These certificates are used by Security Access Manager Runtime and Security Access Manager server to authenticate with each other.

Secure communication between the runtime and servers.

Secure communication to LDAP.

Secure communication to Syslog servers.

The Security Access Manager Base components integrate cryptographic modules, which include IBM Global Security Kit (GSKit) 8, Java™ Secure Socket Extension (JSSE), and Java Cryptography Extension (JCE). Most of the requirements in the standards are handled in GSKit, JSSE, and JCE, which must undergo the certification process to meet government standards. Security Access Manager Base components must be configured to run with GSKit, JSSE, and JCE that are enabled for a particular standard.

FIPS 140-2
The Federal Information Processing Standards (FIPS) specify federal government requirements for cryptographic modules. FIPS 140-2 is a National Institute of Standards and Technology standard.

SP 800-131a
Special Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards.

Suite B
Suite B is a security standard that is developed by the National Security Agency (NSA) that establishes a cryptographic interoperability strategy. Suite B is similar to SP 800-131a, but it has tighter restrictions.

Java properties that enable the security standards
The IBM® virtual machine for Java (JVM) runs in a specific security mode based on system properties.

Parent topic: Core technologies

FIPS 140-2FIPS 140-2FIPS 140-2The Federal Information Processing Standards (FIPS) specify federal government requirements for cryptographic modules. FIPS 140-2 is a National Institute of Standards and Technology standard.securitystandardsFIPS 140-2FIPS140-2The Security Access Manager Base components use certificates generated by the policy server to communicate securely in accordance with FIPS 140-2. The key strength and algorithms that generate FIPS 140-2 certificates are also used when Security Access Manager is not configured for a particular security mode. You can convert between these two modes without completely regenerating all the Security Access Manager certificates. The FIPS 140-2 certificates are compatible with previous releases of Security Access Manager. Previous releases of Security Access Manager can communicate with Security Access Manager 8.0 policy servers.Federal Information Processing Standards (FIPS) that specify requirements on cryptographic modules. For more information, see the National Institute of Standards and Technology website http://csrc.nist.gov/publications/PubsFIPS.html.For more information about FIPS 140-2, see http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf.Security standards configurations (compliance types)You can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government.

FIPS 140-2

The Federal Information Processing Standards (FIPS) specify federal government requirements for cryptographic modules. FIPS 140-2 is a National Institute of Standards and Technology standard.

The Security Access Manager Base components use certificates generated by the policy server to communicate securely in accordance with FIPS 140-2. The key strength and algorithms that generate FIPS 140-2 certificates are also used when Security Access Manager is not configured for a particular security mode. You can convert between these two modes without completely regenerating all the Security Access Manager certificates.

The FIPS 140-2 certificates are compatible with previous releases of Security Access Manager. Previous releases of Security Access Manager can communicate with Security Access Manager 8.0 policy servers.

Federal Information Processing Standards (FIPS) that specify requirements on cryptographic modules. For more information, see the National Institute of Standards and Technology website http://csrc.nist.gov/publications/PubsFIPS.html.

For more information about FIPS 140-2, see http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf.

Parent topic: Security standards configurations (compliance types)

SP 800-131aSP 800-131aSP 800-131aSpecial Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards. securitystandardsSP 800-131aSP 800-131aYou can run SP 800-131a in two modes: transition and strict. Use the transition mode to move gradually towards a strict enforcement of SP 800-131a. The transition mode allows the use of weaker keys and algorithms than strict enforcement allows. The transition mode also allows the use of Transport Layer Security (TLS) v1.0 and v1.1.A strict enforcement of SP 800-131a of the Security Access Manager Base components requires the following configuration: TLS v1.2 protocol for the Secure Sockets Layer (SSL) contextCertificates must have a minimum length of 2048Elliptical Curve (EC) certificates must have a minimum size of 244-bit curvesCertificates must be signed with a signature algorithm of SHA256, SHA384, or SHA512. Valid signature algorithms include:SHA256withRSASHA384withRSASHA512withRSASHA256withECDSASHA384withECDSASHA512withECDSASP 800-131a approved cipher suitesThe Security Access Manager Base component communication uses certificates that are generated by the policy server. The policy server uses the same key strength and algorithms to create certificates for both the transition and strict versions of the SP 800-131a security mode. As a result, you can convert between the transition and strict modes without completely regenerating all Security Access Manager certificates. The SP 800-131a certificates are not compatible with previous releases of Security Access Manager. Previous release Security Access Manager clients cannot communicate with the policy server of previous releases of the Security Access Manager in SP 800-131a mode.For more information about SP 800-131a, see http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf.Security standards configurations (compliance types)You can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government.

SP 800-131a

Special Publication 800-131a (SP 800-131a) is an information security standard of the National Institute of Standards and Technology (NIST). SP 800-131a requires longer key lengths and stronger cryptography than other standards.

You can run SP 800-131a in two modes: transition and strict. Use the transition mode to move gradually towards a strict enforcement of SP 800-131a. The transition mode allows the use of weaker keys and algorithms than strict enforcement allows. The transition mode also allows the use of Transport Layer Security (TLS) v1.0 and v1.1.

A strict enforcement of SP 800-131a of the Security Access Manager Base components requires the following configuration:

TLS v1.2 protocol for the Secure Sockets Layer (SSL) context

Certificates must have a minimum length of 2048

Elliptical Curve (EC) certificates must have a minimum size of 244-bit curves

Certificates must be signed with a signature algorithm of SHA256, SHA384, or SHA512. Valid signature algorithms include:

SHA256withRSA

SHA384withRSA

SHA512withRSA

SHA256withECDSA

SHA384withECDSA

SHA512withECDSA

SP 800-131a approved cipher suites

The Security Access Manager Base component communication uses certificates that are generated by the policy server. The policy server uses the same key strength and algorithms to create certificates for both the transition and strict versions of the SP 800-131a security mode. As a result, you can convert between the transition and strict modes without completely regenerating all Security Access Manager certificates.

The SP 800-131a certificates are not compatible with previous releases of Security Access Manager. Previous release Security Access Manager clients cannot communicate with the policy server of previous releases of the Security Access Manager in SP 800-131a mode.

For more information about SP 800-131a, see http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf.

Parent topic: Security standards configurations (compliance types)

Suite BSuite BSuite BSuite B is a security standard that is developed by the National Security Agency (NSA) that establishes a cryptographic interoperability strategy. Suite B is similar to SP 800-131a, but it has tighter restrictions.securitystandardsSuite BSuite BSuite B can run in two modes: 128-bit and 192-bit. To use the 192-bit mode, you must apply the unrestricted policy file to the JDK in the Security Access Manager Java components. When you apply the unrestricted policy, the JDK uses the stronger cipher that is required for the 192-bit mode.Applying Suite B on the Security Access Manager Base components has the following prerequisites:TLS version 1.2 protocol for the SSL contextSuite B-approved cipher suitesCertificates:128-bit mode certificates must be signed with SHA256withECDSA.192-bit mode certificates must be signed with SHA384withECDSA.Ciphers:SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384The Security Access Manager Base component communication uses certificates that are generated by the policy server. The strength and algorithms to create these certificates differ for each Suite B security mode. You cannot convert from the 128-bit mode to the 192-bit mode (or any other security mode) without completely regenerating all the Security Access Manager certificates. The certificates are not compatible with previous releases of Security Access Manager. Previous release Security Access Manager clients cannot communicate with the Security Access Manager 8.0 policy server in this mode.For more information about the Suite B specifications, see http://www.nsa.gov/ia/programs/suiteb_cryptography/.A requirement from the National Security Agency (NSA) to specify a cryptographic interoperability strategy. This standard is similar to SP800-131 with some tighter restrictions. Suite B can run in two modes: 128-bit or 192-bit. If you are using 192-bit mode with Security Access Manager Java applications, you must apply the unrestricted policy file to the JDK to use the stronger cipher that mode requires. Suite B requirements are:The use of TLSv1.2 protocol.Suite B approved Cipher suitesCertificates:128-bit mode certificates must be signed with SHA256withECDSA192-bit mode certificates must be signed with SHA384withECDSACiphers:SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384Security standards configurations (compliance types)You can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government.

Suite B

Suite B is a security standard that is developed by the National Security Agency (NSA) that establishes a cryptographic interoperability strategy. Suite B is similar to SP 800-131a, but it has tighter restrictions.

Suite B can run in two modes: 128-bit and 192-bit. To use the 192-bit mode, you must apply the unrestricted policy file to the JDK in the Security Access Manager Java™ components. When you apply the unrestricted policy, the JDK uses the stronger cipher that is required for the 192-bit mode.

Applying Suite B on the Security Access Manager Base components has the following prerequisites:

TLS version 1.2 protocol for the SSL context

Suite B-approved cipher suites

Certificates:

128-bit mode certificates must be signed with SHA256withECDSA.

192-bit mode certificates must be signed with SHA384withECDSA.

Ciphers:

SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

The Security Access Manager Base component communication uses certificates that are generated by the policy server. The strength and algorithms to create these certificates differ for each Suite B security mode. You cannot convert from the 128-bit mode to the 192-bit mode (or any other security mode) without completely regenerating all the Security Access Manager certificates. The certificates are not compatible with previous releases of Security Access Manager. Previous release Security Access Manager clients cannot communicate with the Security Access Manager 8.0 policy server in this mode.

For more information about the Suite B specifications, see http://www.nsa.gov/ia/programs/suiteb_cryptography/.

A requirement from the National Security Agency (NSA) to specify a cryptographic interoperability strategy. This standard is similar to SP800-131 with some tighter restrictions. Suite B can run in two modes: 128-bit or 192-bit. If you are using 192-bit mode with Security Access Manager Java applications, you must apply the unrestricted policy file to the JDK to use the stronger cipher that mode requires. Suite B requirements are:

The use of TLSv1.2 protocol.

Suite B approved Cipher suites

Certificates:

128-bit mode certificates must be signed with SHA256withECDSA

192-bit mode certificates must be signed with SHA384withECDSA

Ciphers:

SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Parent topic: Security standards configurations (compliance types)

Java properties that enable the security standardsJava properties that enable the security standardsJava propertiesThe IBM® virtual machine for Java (JVM) runs in a specific security mode based on system properties. securitystandardsJava propertiesWhen Security Access Manager Base components are run in a JVM other than WebSphere, Security Access Manager automatically enables the appropriate system properties for the security configuration settings.JVM system properties enabled by Security Access ManagerSecurity standardSystem property to enableValid valuesFIPS 140-2com.ibm.jsse2.usefipsprovider (for newer JVMs that support it)com.ibm.jsse2.JSSEFIPS (for older JVMs such as Java 5 and pre Java 1.6SR10)true or falseSP 800-131acom.ibm.jsse2.sp800-131transition or strictSuite Bcom.ibm.jsse2.suiteB128 or 192Security standards configurations (compliance types)You can configure Security Access Manager Base components to work with various security standards, including FIPS 140-2, SP 800-131, and Suite B. These security standards meet information security requirements that are required by the government.

Java properties that enable the security standards

The IBM® virtual machine for Java™ (JVM) runs in a specific security mode based on system properties.

When Security Access Manager Base components are run in a JVM other than WebSphere®, Security Access Manager automatically enables the appropriate system properties for the security configuration settings.

Table 153. JVM system properties enabled by Security Access Manager

Security standard
System property to enable
Valid values

FIPS 140-2

com.ibm.jsse2.usefipsprovider (for newer JVMs that support it)

com.ibm.jsse2.JSSEFIPS (for older JVMs such as Java 5 and pre Java 1.6SR10)

true or false

SP 800-131a

com.ibm.jsse2.sp800-131

transition or strict

Suite B

com.ibm.jsse2.suiteB

128 or 192

Parent topic: Security standards configurations (compliance types)

ScalabilityScalabilityScalabilityScalability is the ability to respond to increasing numbers of users who access resources in the domain. Security Access Manager uses several techniques to provide scalability. scalability Security Access Manager provides the following scalability methods:Replication of services Authentication servicesAuthorization servicesSecurity policiesData encryption servicesAuditing servicesFront-end replicated servers Mirrored resources for high availabilityLoad balancing client requestsBack-end replicated servers Back-end servers can be Security Access Manager WebSEAL or other application serversMirrored resources (unified object space) for high availabilityAdditional content and resourcesLoad balancing of incoming requestsOptimized performance by allowing for the offloading of authentication services and authorization services to separate serversScaled deployment of services without increasing management processor usageCore technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.

Scalability

Scalability is the ability to respond to increasing numbers of users who access resources in the domain. Security Access Manager uses several techniques to provide scalability.

Security Access Manager provides the following scalability methods:

Replication of services

Authentication services

Authorization services

Security policies

Data encryption services

Auditing services

Front-end replicated servers

Mirrored resources for high availability

Load balancing client requests

Back-end replicated servers

Back-end servers can be Security Access Manager WebSEAL or other application servers

Mirrored resources (unified object space) for high availability

Additional content and resources

Load balancing of incoming requests

Optimized performance by allowing for the offloading of authentication services and authorization services to separate servers

Scaled deployment of services without increasing management processor usage

Parent topic: Core technologies

AccountabilityAccountabilityAccountabilitySecurity Access Manager provides several logging and auditing capabilities to increase accountability for server activity.accountability Log files capture any error and warning messages generated by Security Access Manager servers. Audit trail files monitor Security Access Manager server activity.Core technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.

Accountability

Security Access Manager provides several logging and auditing capabilities to increase accountability for server activity.

Log files capture any error and warning messages generated by Security Access Manager servers. Audit trail files monitor Security Access Manager server activity.

Parent topic: Core technologies

Centralized managementCentralized managementCentralized managementSecurity Access Manager uses two user interfaces to manage security policies and the Security Access Manager servers.centralized managementmanagementcentralizedpdadmin command-line interfaceWeb Portal Manager graphical user interface (GUI). However, some tasks cannot be done with the Web Portal Manager.Administration APIYou can accomplish most tasks by using any of these methods. Core technologiesThe Security Access Manager network security management solution provides and supports several core technologies and features.pdadmin command-line interfaceThe pdadmin command-line interface administers Security Access Manager. Web Portal ManagerWeb Portal Manager is an optional web-based interface for administering or performing administrative tasks with Security Access Manager. Administration APIYou can use the administration API to write applications to manage users, groups, roles, permissions, policies, domains, and servers. Both C and Java language versions of these functions are available.

Centralized management

Security Access Manager uses two user interfaces to manage security policies and the Security Access Manager servers.

pdadmin command-line interface

Web Portal Manager graphical user interface (GUI). However, some tasks cannot be done with the Web Portal Manager.

Administration API

You can accomplish most tasks by using any of these methods.

pdadmin command-line interface
The pdadmin command-line interface administers Security Access Manager.

Web Portal Manager
Web Portal Manager is an optional web-based interface for administering or performing administrative tasks with Security Access Manager.

Administration API
You can use the administration API to write applications to manage users, groups, roles, permissions, policies, domains, and servers. Both C and Java™ language versions of these functions are available.

Parent topic: Core technologies

pdadmin command-line interfacepdadmin command-line interfacepdadmin command-line interfaceThe pdadmin command-line interface administers Security Access Manager. pdadmincommand interfaceThis interface provides commands for managing users, groups, roles, permissions, policies, domains, and servers, and other tasks. This interface can be used in scripts or batch files to automate processing.This interface is installed as part of the IBM Security Access Manager runtime package.For specific task information, see the task-specific chapters in this guide. For detailed syntax information about the pdadmin command-line interface, see the Reference topics in the IBM Knowledge Center.Centralized managementSecurity Access Manager uses two user interfaces to manage security policies and the Security Access Manager servers.

pdadmin command-line interface

The pdadmin command-line interface administers Security Access Manager.

This interface provides commands for managing users, groups, roles, permissions, policies, domains, and servers, and other tasks. This interface can be used in scripts or batch files to automate processing.

This interface is installed as part of the IBM Security Access Manager runtime package.

For specific task information, see the task-specific chapters in this guide. For detailed syntax information about the pdadmin command-line interface, see the Reference topics in the IBM Knowledge Center.

Parent topic: Centralized management

Web Portal ManagerWeb Portal ManagerWeb Portal ManagerWeb Portal Manager is an optional web-based interface for administering or performing administrative tasks with Security Access Manager. Web Portal ManagerintroductionintroductionWeb Portal ManagerYou can use Web Portal Manager to perform administrative tasks, such as managing users, groups, roles, permissions, policies, domains, and servers. A key advantage to using Web Portal Manager is that you can do these tasks remotely from any supported web browser. You do not need any special network configuration.Centralized managementSecurity Access Manager uses two user interfaces to manage security policies and the Security Access Manager servers.

Web Portal Manager

Web Portal Manager is an optional web-based interface for administering or performing administrative tasks with Security Access Manager.

You can use Web Portal Manager to perform administrative tasks, such as managing users, groups, roles, permissions, policies, domains, and servers. A key advantage to using Web Portal Manager is that you can do these tasks remotely from any supported web browser. You do not need any special network configuration.

Parent topic: Centralized management

Administration APIAdministration APIAdministration APIYou can use the administration API to write applications to manage users, groups, roles, permissions, policies, domains, and servers. Both C and Java language versions of these functions are available.administrationAPISee details about the administration API: Administration C API Developer Reference: http://www.ibm.com/support/docview.wss?uid=swg21665268Administration Java Classes Developer Reference: http://www.ibm.com/support/docview.wss?uid=swg21665270Centralized managementSecurity Access Manager uses two user interfaces to manage security policies and the Security Access Manager servers.

Administration API

You can use the administration API to write applications to manage users, groups, roles, permissions, policies, domains, and servers. Both C and Java™ language versions of these functions are available.

See details about the administration API:

Administration C API Developer Reference: http://www.ibm.com/support/docview.wss?uid=swg21665268

Administration Java Classes Developer Reference: http://www.ibm.com/support/docview.wss?uid=swg21665270

Parent topic: Centralized management

Security policy overviewSecurity policy overviewSecurity policy overviewThe goal of any security policy is to adequately protect business assets and resources with a minimal amount of administrative effort. High-level steps include determining which resources to protect and the level of access that users get to those resources.securitypolicyoverviewDefine what resources need to be protected. Protected resources might be any type of data object, such as files, directories, network servers, messages, databases, or web pages. Determine what users and groups of users can access to these protected resources. Also consider what type of access to these resources is permitted. Apply the appropriate security policy on these resources to ensure that only the right users can access them.The enforcement of the security policy is the job of the resource manager. The resource manager calls the Security Access Manager authorization service with the credentials of the user that makes the request. The call includes the type of access wanted and the object to be accessed. The credential provides detailed information, acquired during authentication, that describes the user, any group associations, and other security-related identity attributes. Credentials can be used to do a multitude of services, such as authorization, auditing, and delegation.The authorization service is also called the authorization engine. The authorization service uses the security policy to determine whether the request is allowed or denied. The request might also be conditionally allowed pending additional verification by the resource manager. The resource manager takes the recommendation of the authorization service. The resource manager does any additional verification actions and ultimately either denies the request or permits the request to be processed.For example, suppose that John wants to access a particular web page that is on a website protected by Security Access Manager WebSEAL. WebSEAL is a resource manager that manages and protects web-based information and resources. It must decide whether "John" can access that page. The resource manager obtains the credentials for John, and then asks the authorization service whether John has read access to the web page. The authorization service checks the security policy and determines that John is permitted access. The service responds to the resource manager that the request is granted. The resource manager then directs the request to the appropriate back-end web server, which provides the web page.The security policy in Security Access Manager is defined through the use of access control lists (ACLs), protected object policies (POPs), and authorization rules.Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.

Security policy overview

The goal of any security policy is to adequately protect business assets and resources with a minimal amount of administrative effort. High-level steps include determining which resources to protect and the level of access that users get to those resources.

Define what resources need to be protected. Protected resources might be any type of data object, such as files, directories, network servers, messages, databases, or web pages.

Determine what users and groups of users can access to these protected resources. Also consider what type of access to these resources is permitted.

Apply the appropriate security policy on these resources to ensure that only the right users can access them.

The enforcement of the security policy is the job of the resource manager. The resource manager calls the Security Access Manager authorization service with the credentials of the user that makes the request. The call includes the type of access wanted and the object to be accessed. The credential provides detailed information, acquired during authentication, that describes the user, any group associations, and other security-related identity attributes. Credentials can be used to do a multitude of services, such as authorization, auditing, and delegation.

The authorization service is also called the authorization engine. The authorization service uses the security policy to determine whether the request is allowed or denied. The request might also be conditionally allowed pending additional verification by the resource manager. The resource manager takes the recommendation of the authorization service. The resource manager does any additional verification actions and ultimately either denies the request or permits the request to be processed.

For example, suppose that John wants to access a particular web page that is on a website protected by Security Access Manager WebSEAL. WebSEAL is a resource manager that manages and protects web-based information and resources. It must decide whether "John" can access that page. The resource manager obtains the credentials for John, and then asks the authorization service whether John has read access to the web page. The authorization service checks the security policy and determines that John is permitted access. The service responds to the resource manager that the request is granted. The resource manager then directs the request to the appropriate back-end web server, which provides the web page.

The security policy in Security Access Manager is defined through the use of access control lists (ACLs), protected object policies (POPs), and authorization rules.

Parent topic: Security Access Manager overview

Authorization API standardAuthorization API standardAuthorization API standardAuthorization services are a critical part of the security architecture of an application. After a user passes the authentication process, authorization services proceed to enforce the business policy by determining what services and information the user can access.authorizationAPIstandardFor example, a user might access a web-based retirement fund. The user can view personal account information after an authorization server verifies the identity, credentials, and privilege attributes of that user.The standards-based authorization API (aznAPI) allows applications to call the centralized authorization service. The authorization API eliminates the necessity for developers to write authorization code for each new application.The authorization API allows businesses to standardize all applications on a trusted authorization framework. With the authorization API, businesses can provide more control over access to resources on their networks.Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.

Authorization API standard

Authorization services are a critical part of the security architecture of an application. After a user passes the authentication process, authorization services proceed to enforce the business policy by determining what services and information the user can access.

For example, a user might access a web-based retirement fund. The user can view personal account information after an authorization server verifies the identity, credentials, and privilege attributes of that user.

The standards-based authorization API (aznAPI) allows applications to call the centralized authorization service. The authorization API eliminates the necessity for developers to write authorization code for each new application.

The authorization API allows businesses to standardize all applications on a trusted authorization framework. With the authorization API, businesses can provide more control over access to resources on their networks.

Parent topic: Security Access Manager overview

Authorization: conceptual modelAuthorization: conceptual modelAuthorization conceptual modelIn security systems, authorization is distinct from authentication. Authorization determines whether an authenticated client has the required permissions to do a task on a specific resource in a domain. Authentication ensures that the individual is who that individual claims to be.authorizationmodel, conceptualmodelauthorizationresourcemanagerpolicyenforcerauthorizationservicedecisionsWhen servers enforce security in a domain, each client must provide proof of its identity. In turn, security policy determines whether that client has the required permission to do a task on a requested resource. Access to every resource in a domain is controlled by a server. The demands on the server for authentication and authorization can provide comprehensive network security.In the Security Access Manager authorization model, authorization policy is implemented independently of the mechanism for user authentication. Users can authenticate their identity with a public/private key, secret key, or customer-defined mechanisms.Part of the authentication process involves the creation of a credential that describes the identity of the client. Authorization decisions made by an authorization service are based on user credentials.The resources in a domain receive a level of protection that is dictated by the security policy for the domain. The security policy defines the legitimate participants of the domain. It also defines the degree of protection that surrounds each resource that requires protection.The authorization process, as shown in Figure 1, includes the following basic components: resource managerImplements the requested operation when authorization is granted. A component of the resource manager is a policy enforcer that directs the request to the authorization service for processing.authorization serviceProcesses the decision-making action on the request. General authorization modelGeneral authorization model.Traditional applications bundle the policy enforcer and resource manager into one process. An example of this structure is Security Access Manager WebSEAL.The independent functions of these authorization components allow flexibility in the design of the security enforcement strategy. For example, such independence allows the security administrator to control: Where the processes are locatedWho writes the code for the processesHow the processes do their tasksSecurity Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.Benefits of a standard authorization serviceA standard authorization service offers several benefits over an assortment of proprietary authorization implementations. Benefits can include reduced development cost and the ability to share information securely.Security Access Manager authorization service overviewYou can integrate Security Access Manager into existing and emerging infrastructures to provide a secure, centralized policy management capability. The authorization service, together with resource managers, provides a standard authorization mechanism for business network systems.

Authorization: conceptual model

In security systems, authorization is distinct from authentication. Authorization determines whether an authenticated client has the required permissions to do a task on a specific resource in a domain. Authentication ensures that the individual is who that individual claims to be.

When servers enforce security in a domain, each client must provide proof of its identity. In turn, security policy determines whether that client has the required permission to do a task on a requested resource. Access to every resource in a domain is controlled by a server. The demands on the server for authentication and authorization can provide comprehensive network security.

In the Security Access Manager authorization model, authorization policy is implemented independently of the mechanism for user authentication. Users can authenticate their identity with a public/private key, secret key, or customer-defined mechanisms.

Part of the authentication process involves the creation of a credential that describes the identity of the client. Authorization decisions made by an authorization service are based on user credentials.

The resources in a domain receive a level of protection that is dictated by the security policy for the domain. The security policy defines the legitimate participants of the domain. It also defines the degree of protection that surrounds each resource that requires protection.

The authorization process, as shown in Figure 68., includes the following basic components:

resource manager

Implements the requested operation when authorization is granted.

A component of the resource manager is a policy enforcer that directs the request to the authorization service for processing.

authorization service

Processes the decision-making action on the request.

Figure 68. General authorization model

Traditional applications bundle the policy enforcer and resource manager into one process. An example of this structure is Security Access Manager WebSEAL.

The independent functions of these authorization components allow flexibility in the design of the security enforcement strategy.

For example, such independence allows the security administrator to control:

Where the processes are located

Who writes the code for the processes

How the processes do their tasks

Benefits of a standard authorization service
A standard authorization service offers several benefits over an assortment of proprietary authorization implementations. Benefits can include reduced development cost and the ability to share information securely.

Security Access Manager authorization service overview
You can integrate Security Access Manager into existing and emerging infrastructures to provide a secure, centralized policy management capability. The authorization service, together with resource managers, provides a standard authorization mechanism for business network systems.

Parent topic: Security Access Manager overview

Benefits of a standard authorization serviceBenefits of a standard authorization serviceBenefits of a standard authorization serviceA standard authorization service offers several benefits over an assortment of proprietary authorization implementations. Benefits can include reduced development cost and the ability to share information securely.authorizationservicebenefitsbenefits, authorization serviceAuthorization in most systems, both existing and new, is tightly coupled to individual applications. Companies typically build applications over time to serve their business needs. Many of these applications require some specific form of authorization.The result is often a wide variety of applications with differing authorization implementations. These proprietary authorization implementations require separate administration, are difficult to integrate, and result in higher costs of ownership.A distributed authorization service can provide these independent applications with a standard authorization decision-making mechanism. Benefits of such a standard authorization service include: Reduced cost of developing and managing access to applicationsReduced total cost of ownership and management of separate authorization systemsUse the existing security infrastructureAllow new businesses to open applications more securelyEnable newer and different kinds of applicationsAllow shorter development cyclesShare information securelyAuthorization: conceptual modelIn security systems, authorization is distinct from authentication. Authorization determines whether an authenticated client has the required permissions to do a task on a specific resource in a domain. Authentication ensures that the individual is who that individual claims to be.

Benefits of a standard authorization service

A standard authorization service offers several benefits over an assortment of proprietary authorization implementations. Benefits can include reduced development cost and the ability to share information securely.

Authorization in most systems, both existing and new, is tightly coupled to individual applications. Companies typically build applications over time to serve their business needs. Many of these applications require some specific form of authorization.

The result is often a wide variety of applications with differing authorization implementations. These proprietary authorization implementations require separate administration, are difficult to integrate, and result in higher costs of ownership.

A distributed authorization service can provide these independent applications with a standard authorization decision-making mechanism. Benefits of such a standard authorization service include:

Reduced cost of developing and managing access to applications

Reduced total cost of ownership and management of separate authorization systems

Use the existing security infrastructure

Allow new businesses to open applications more securely

Enable newer and different kinds of applications

Allow shorter development cycles

Share information securely

Parent topic: Authorization: conceptual model

Security Access Manager authorization service overviewSecurity Access Manager authorization service overviewAccess Manager authorization service overviewYou can integrate Security Access Manager into existing and emerging infrastructures to provide a secure, centralized policy management capability. The authorization service, together with resource managers, provides a standard authorization mechanism for business network systems.authorizationserviceoverviewdatabasemaster authorizationdatabasereplica authorizationThe Security Access Manager authorization service is illustrated in Figure 1.Security Access Manager server componentsArtwork displaying WPM, policy server, user registry, master authorization database, authorization server, and replica authorization database.Existing applications can take advantage of the authorization service. An authorization policy is based on user or group roles. It can be applied to network servers, individual transactions, database requests, specific web-based information, management activities, and user-defined objects.The authorization API allows existing applications to call the authorization service, which bases its decision on the corporate security policy. For more information about the authorization API, see Security Access Manager authorization APIThe Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself. .The Security Access Manager authorization service is also extensible. It can be configured to call on other authorization services for additional processing by using the external authorization service plug-in interface.The authorization service provides the following benefits: The service is application independent.The service uses a standard authorization coding style that is language independent (the authorization API).The service is centrally managed and therefore easy to administer. The addition of a new employee, for example, requires modifying the privilege database in one central location, rather than across multiple systems.The service addresses the application of security services in a heterogeneous cross-platform environment.The service integrates existing non-Security Access Manager authorization systems through an external authorization service capability.The service has a scalable and flexible architecture that can be easily integrated with existing infrastructure.The service enables multi-tiered authorization. A credentials packet can be passed through the multiple layers of an application process or transaction.The service uses a common and effective auditing model.The service is independent of any authentication mechanism.Authorization: conceptual modelIn security systems, authorization is distinct from authentication. Authorization determines whether an authenticated client has the required permissions to do a task on a specific resource in a domain. Authentication ensures that the individual is who that individual claims to be.

Security Access Manager authorization service overview

You can integrate Security Access Manager into existing and emerging infrastructures to provide a secure, centralized policy management capability. The authorization service, together with resource managers, provides a standard authorization mechanism for business network systems.

The Security Access Manager authorization service is illustrated in Figure 69..

Figure 69. Security Access Manager server components

Existing applications can take advantage of the authorization service. An authorization policy is based on user or group roles. It can be applied to network servers, individual transactions, database requests, specific web-based information, management activities, and user-defined objects.

The authorization API allows existing applications to call the authorization service, which bases its decision on the corporate security policy. For more information about the authorization API, see Security Access Manager authorization API.

The Security Access Manager authorization service is also extensible. It can be configured to call on other authorization services for additional processing by using the external authorization service plug-in interface.

The authorization service provides the following benefits:

The service is application independent.

The service uses a standard authorization coding style that is language independent (the authorization API).

The service is centrally managed and therefore easy to administer. The addition of a new employee, for example, requires modifying the privilege database in one central location, rather than across multiple systems.

The service addresses the application of security services in a heterogeneous cross-platform environment.

The service integrates existing non-Security Access Manager authorization systems through an external authorization service capability.

The service has a scalable and flexible architecture that can be easily integrated with existing infrastructure.

The service enables multi-tiered authorization. A credentials packet can be passed through the multiple layers of an application process or transaction.

The service uses a common and effective auditing model.

The service is independent of any authentication mechanism.

Parent topic: Authorization: conceptual model

Security Access Manager authorization serviceSecurity Access Manager authorization serviceThe authorization service is responsible for the authorization decision-making process that enforces a network security policy. authorizationservicedefinitionAuthorization decisions made by the authorization service result in the approval or denial of client requests to do operations on protected resources in a domain.Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.ComponentsThe authorization service is made up of the following basic components: the master authorization policy database, the policy server, and the authorization decision-making evaluator.Authorization service interfacesInteraction in the authorization service occurs in the management interface and the authorization API.Replication for scalability and performanceYou can replicate authorization service components to increase availability in a heavy-demand environment.

Security Access Manager authorization service

The authorization service is responsible for the authorization decision-making process that enforces a network security policy.

Authorization decisions made by the authorization service result in the approval or denial of client requests to do operations on protected resources in a domain.

Components
The authorization service is made up of the following basic components: the master authorization policy database, the policy server, and the authorization decision-making evaluator.

Authorization service interfaces
Interaction in the authorization service occurs in the management interface and the authorization API.

Replication for scalability and performance
You can replicate authorization service components to increase availability in a heavy-demand environment.

Parent topic: Security Access Manager overview

ComponentsComponentsauthorization service componentsThe authorization service is made up of the following basic components: the master authorization policy database, the policy server, and the authorization decision-making evaluator.authorizationservicecomponentsSecurity Access Manager authorization serviceThe authorization service is responsible for the authorization decision-making process that enforces a network security policy. Policy databaseThe policy database contains the security policy information for all resources in a domain. The policy database is also called the master authorization policy database or the master authorization database.Policy serverThe policy server maintains the policy databases and replicates this policy information throughout the domains. The policy server also updates the database replicas whenever a change is made to the master.Authorization evaluatorThe authorization evaluator is the decision-making process that determines the ability of the client to access a protected resource based on the security policy. The evaluator makes its recommendation to the resource manager, which responds.

Components

The authorization service is made up of the following basic components: the master authorization policy database, the policy server, and the authorization decision-making evaluator.

Policy database
The policy database contains the security policy information for all resources in a domain. The policy database is also called the master authorization policy database or the master authorization database.

Policy server
The policy server maintains the policy databases and replicates this policy information throughout the domains. The policy server also updates the database replicas whenever a change is made to the master.

Authorization evaluator
The authorization evaluator is the decision-making process that determines the ability of the client to access a protected resource based on the security policy. The evaluator makes its recommendation to the resource manager, which responds.

Parent topic: Security Access Manager authorization service

Policy databasePolicy databaseAccess Manager policy databaseThe policy database contains the security policy information for all resources in a domain. The policy database is also called the master authorization policy database or the master authorization database.authorizationpolicy database, each domainpolicydatabase for each domainEach domain has its own policy database. The contents of this database are manipulated by using the pdadmin command-line interface, Web Portal Manager, and the administration API.ComponentsThe authorization service is made up of the following basic components: the master authorization policy database, the policy server, and the authorization decision-making evaluator.

Policy database

The policy database contains the security policy information for all resources in a domain. The policy database is also called the master authorization policy database or the master authorization database.

Each domain has its own policy database. The contents of this database are manipulated by using the pdadmin command-line interface, Web Portal Manager, and the administration API.

Parent topic: Components

Policy serverPolicy serverAccess Manager policy serverThe policy server maintains the policy databases and replicates this policy information throughout the domains. The policy server also updates the database replicas whenever a change is made to the master.pdmgrpolicyserveroverviewThe policy server also maintains location information about the other Security Access Manager and non-Security Access Manager resource managers that operate in the domain.ComponentsThe authorization service is made up of the following basic components: the master authorization policy database, the policy server, and the authorization decision-making evaluator.

Policy server

The policy server maintains the policy databases and replicates this policy information throughout the domains. The policy server also updates the database replicas whenever a change is made to the master.

The policy server also maintains location information about the other Security Access Manager and non-Security Access Manager resource managers that operate in the domain.

Parent topic: Components

Authorization evaluatorThe authorization evaluator is the decision-making process that determines the ability of the client to access a protected resource based on the security policy. The evaluator makes its recommendation to the resource manager, which responds.authorizationevaluator, overviewUser registry replication parameters are configurable for each evaluator.Figure 1 illustrates the main components of the authorization service: Authorization service componentsAuthorization service components.ComponentsThe authorization service is made up of the following basic components: the master authorization policy database, the policy server, and the authorization decision-making evaluator.

Authorization evaluator

The authorization evaluator is the decision-making process that determines the ability of the client to access a protected resource based on the security policy. The evaluator makes its recommendation to the resource manager, which responds.

User registry replication parameters are configurable for each evaluator.

Figure 70. illustrates the main components of the authorization service:

Figure 70. Authorization service components

Parent topic: Components

Authorization service interfacesAuthorization service interfacesInteraction in the authorization service occurs in the management interface and the authorization API.authorizationserviceinterfacesmanagementinterfaceauthorizationserviceauthorization APIManagement interfaceThe security administrator manages the security policy with the Web Portal Manager or pdadmin command-line interface to apply policy rules to resources in a domain. The security policy is managed in the policy database by the policy server. This interface is complex and involves detailed knowledge of the object space, policies, and credentials. Authorization APIThe authorization API passes requests for authorization decisions from the resource manager to the authorization evaluator. The authorization evaluator provides feedback on whether to grant or deny the request.Security Access Manager authorization serviceThe authorization service is responsible for the authorization decision-making process that enforces a network security policy.

Authorization service interfaces

Interaction in the authorization service occurs in the management interface and the authorization API.

Management interface

The security administrator manages the security policy with the Web Portal Manager or pdadmin command-line interface to apply policy rules to resources in a domain. The security policy is managed in the policy database by the policy server.

This interface is complex and involves detailed knowledge of the object space, policies, and credentials.

Authorization API

The authorization API passes requests for authorization decisions from the resource manager to the authorization evaluator. The authorization evaluator provides feedback on whether to grant or deny the request.

Parent topic: Security Access Manager authorization service

Replication for scalability and performanceReplication for scalability and performanceYou can replicate authorization service components to increase availability in a heavy-demand environment.replicationscalabilityreplicationperformancescalabilityYou can configure the master authorization policy database, containing policy rules and credential information, to automatically replicate. Resource managers that call the authorization service have two options for referencing this database information: The application, when configured to work seamlessly with the authorization evaluator, uses a local cache of the database. The database is replicated for each resource manager that uses the authorization service in local cache mode.The application uses a shared replica cached by the remote authorization server component. The database is replicated for each instance of the authorization server. Many applications can access a single authorization server.The update notification from the policy server occurs whenever a change is made to the master authorization policy database. The update notification triggers the caching process to update all replicas, as shown in Figure 1: Replicated authorization service componentsReplicated authorization service components.Security Access Manager authorization serviceThe authorization service is responsible for the authorization decision-making process that enforces a network security policy. Performance notesConsider these performance issues:

Replication for scalability and performance

You can replicate authorization service components to increase availability in a heavy-demand environment.

You can configure the master authorization policy database, containing policy rules and credential information, to automatically replicate. Resource managers that call the authorization service have two options for referencing this database information:

The application, when configured to work seamlessly with the authorization evaluator, uses a local cache of the database.

The database is replicated for each resource manager that uses the authorization service in local cache mode.

The application uses a shared replica cached by the remote authorization server component.

The database is replicated for each instance of the authorization server. Many applications can access a single authorization server.

The update notification from the policy server occurs whenever a change is made to the master authorization policy database. The update notification triggers the caching process to update all replicas, as shown in Figure 71.:

Figure 71. Replicated authorization service components

Performance notes
Consider these performance issues:

Parent topic: Security Access Manager authorization service

Performance notesConsider these performance issues:authorizationserviceperformanceYou can update notifications directly from the policy server. You can also configure the resource managers to verify the version of the master authorization policy database every few minutes. This verification ensures that the update notifications are not missed. Such a mechanism is called polling and is not enabled by default. If an update notification fails to reach a server, a log entry is created. In both cases, a retry mechanism also ensures that the update happens in the future.The cached authorization policy information results in high system performance. For example, when WebSEAL does an authorization check, it checks the policy in its own cached version of the database. WebSEAL does not have to access the network to obtain this information from the master database. The result is fast response times (performance) for authorization checks.Individual authorization results are not cached by the calling application server. Replication for scalability and performanceYou can replicate authorization service components to increase availability in a heavy-demand environment.

Performance notes

Consider these performance issues:

You can update notifications directly from the policy server. You can also configure the resource managers to verify the version of the master authorization policy database every few minutes. This verification ensures that the update notifications are not missed. Such a mechanism is called polling and is not enabled by default.

If an update notification fails to reach a server, a log entry is created. In both cases, a retry mechanism also ensures that the update happens in the future.

The cached authorization policy information results in high system performance. For example, when WebSEAL does an authorization check, it checks the policy in its own cached version of the database. WebSEAL does not have to access the network to obtain this information from the master database. The result is fast response times (performance) for authorization checks.

Individual authorization results are not cached by the calling application server.

Parent topic: Replication for scalability and performance

Implementation of a network security policyImplementation of a network security policyControlling user and group participation in the domain and applying rules to resources that require protection determine the security policy for a domain. These rules are defined by access control lists (ACLs), protected object policies (POPs), and authorization rules. securitypolicyimplementationThe authorization service enforces these policies by matching the credentials of a user with the permissions in the policy assigned to the requested resource. The resulting recommendation is passed to the resource manager, which completes the response to the original request.Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.Definition and application of security policyYou can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space. The authorization process: step-by-stepThis example illustrates how the authorization process works.

Implementation of a network security policy

Controlling user and group participation in the domain and applying rules to resources that require protection determine the security policy for a domain. These rules are defined by access control lists (ACLs), protected object policies (POPs), and authorization rules.

The authorization service enforces these policies by matching the credentials of a user with the permissions in the policy assigned to the requested resource. The resulting recommendation is passed to the resource manager, which completes the response to the original request.

Definition and application of security policy
You can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space.

The authorization process: step-by-step
This example illustrates how the authorization process works.

Parent topic: Security Access Manager overview

Definition and application of security policyDefinition and application of security policyYou can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space. securitypolicydefiningsecuritypolicyapplyingYou can apply ACLs, POPs, and authorization rules to the same object. The Web Portal Manager, pdadmin command-line interface and the administration API are used to define this policy.The authorization service makes authorization decisions based on the policies applied to these objects. When a requested operation on a protected object is permitted, the resource manager responsible for the resource implements this operation.One policy can dictate the protection parameters of many objects. Any change to the security policy affects all objects to which the policy is attached. Implementation of a network security policyControlling user and group participation in the domain and applying rules to resources that require protection determine the security policy for a domain. These rules are defined by access control lists (ACLs), protected object policies (POPs), and authorization rules. Explicit and inherited policiesA security policy can be explicitly applied or inherited. The administrator can apply explicit policies only at points in the hierarchy where the rules must change.Access control listsAn access control list (ACL) policy is a set of actions, controls, or permissions. The ACL policy specifies the necessary conditions for a user or group to do operations on a resource. Protected object policiesProtected object policies (POPs) contain additional conditions that must be met before granting access to a user or group. Authorization rulesDefine authorization rules to specify additional conditions that must be met before granting access to a resource.

Definition and application of security policy

You can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space.

You can apply ACLs, POPs, and authorization rules to the same object. The Web Portal Manager, pdadmin command-line interface and the administration API are used to define this policy.

The authorization service makes authorization decisions based on the policies applied to these objects. When a requested operation on a protected object is permitted, the resource manager responsible for the resource implements this operation.

One policy can dictate the protection parameters of many objects. Any change to the security policy affects all objects to which the policy is attached.

Explicit and inherited policies
A security policy can be explicitly applied or inherited. The administrator can apply explicit policies only at points in the hierarchy where the rules must change.

Access control lists
An access control list (ACL) policy is a set of actions, controls, or permissions. The ACL policy specifies the necessary conditions for a user or group to do operations on a resource.

Protected object policies
Protected object policies (POPs) contain additional conditions that must be met before granting access to a user or group.

Authorization rules
Define authorization rules to specify additional conditions that must be met before granting access to a resource.

Parent topic: Implementation of a network security policy

Explicit and inherited policiesExplicit and inherited policiesA security policy can be explicitly applied or inherited. The administrator can apply explicit policies only at points in the hierarchy where the rules must change.explicitpolicyinheritedpolicyThe Security Access Manager protected object space supports inheritance of ACLs, POPs, and authorization rules. This factor is an important consideration for the security administrator who manages the object space. The administrator needs to apply explicit policies only at points in the hierarchy where the rules must change, as shown in Figure 1. Explicit and inherited policiesExplicit and inherited policies.Examples of policy types include: Hardcoded rulesExternal authorization capabilitySpecial secure labelingAccess control lists (ACLs), protected object policies (POPs), and authorization rulesDefinition and application of security policyYou can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space.

Explicit and inherited policies

A security policy can be explicitly applied or inherited. The administrator can apply explicit policies only at points in the hierarchy where the rules must change.

The Security Access Manager protected object space supports inheritance of ACLs, POPs, and authorization rules. This factor is an important consideration for the security administrator who manages the object space. The administrator needs to apply explicit policies only at points in the hierarchy where the rules must change, as shown in Figure 72..

Figure 72. Explicit and inherited policies

Examples of policy types include:

Hardcoded rules

External authorization capability

Special secure labeling

Access control lists (ACLs), protected object policies (POPs), and authorization rules

Parent topic: Definition and application of security policy

Access control listsAccess control listsAn access control list (ACL) policy is a set of actions, controls, or permissions. The ACL policy specifies the necessary conditions for a user or group to do operations on a resource. access control listsACL policy definitions are important components of the security policy established for a domain.An ACL policy specifically determines what operations can be done on a resource, and who can do those operations. An ACL policy is made up of one or more entries that include user and group designations and either their specific permissions or rights.Definition and application of security policyYou can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space.

Access control lists

An access control list (ACL) policy is a set of actions, controls, or permissions. The ACL policy specifies the necessary conditions for a user or group to do operations on a resource.

ACL policy definitions are important components of the security policy established for a domain.

An ACL policy specifically determines what operations can be done on a resource, and who can do those operations. An ACL policy is made up of one or more entries that include user and group designations and either their specific permissions or rights.

Parent topic: Definition and application of security policy

Protected object policiesProtected object policiesProtected object policies (POPs) contain additional conditions that must be met before granting access to a user or group. POPdefinitionUnlike ACLs, which are dependent on what user or group is attempting the action, POPs affect all users and groups. POPs also indicate whether requests must be audited. It is the responsibility of Security Access Manager and the resource manager to enforce the POP conditions.Definition and application of security policyYou can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space.

Protected object policies

Protected object policies (POPs) contain additional conditions that must be met before granting access to a user or group.

Unlike ACLs, which are dependent on what user or group is attempting the action, POPs affect all users and groups. POPs also indicate whether requests must be audited. It is the responsibility of Security Access Manager and the resource manager to enforce the POP conditions.

Parent topic: Definition and application of security policy

Authorization rulesAuthorization rulesDefine authorization rules to specify additional conditions that must be met before granting access to a resource.authorizationrulesdecisionsauthorizationrulesBoolean expressionsYou can use rules to make authorization decisions based on the context and the environment that surround a request. You can also use rules to make authorization decisions based on who is attempting the access and what type of action is being attempted. These conditions are evaluated as a Boolean expression to determine whether the request must be allowed or denied.Definition and application of security policyYou can protect system resources by defining a security policy. You define a security policy with access control lists (ACLs), protected object policies (POPs), and authorization rules. You apply the security policy to the object representations of those resources in the object space.

Authorization rules

Define authorization rules to specify additional conditions that must be met before granting access to a resource.

You can use rules to make authorization decisions based on the context and the environment that surround a request. You can also use rules to make authorization decisions based on who is attempting the access and what type of action is being attempted. These conditions are evaluated as a Boolean expression to determine whether the request must be allowed or denied.

Parent topic: Definition and application of security policy

The authorization process: step-by-stepThe authorization process: step-by-stepThis example illustrates how the authorization process works.authorizationstep-by-step processFigure 1 illustrates the complete authorization process.The Security Access Manager authorization processThe Security Access Manager authorization processAn authenticated client request for a resource is directed to the resource manager server and intercepted by the policy enforcer process. For example, the resource manager can be WebSEAL for Hypertext Transfer Protocol (HTTP), HTTPS access, or another application.The policy enforcer process uses the authorization API to call the authorization service for an authorization decision. For more information about the authorization API, see Security Access Manager authorization APIThe Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself. .The authorization service does an authorization check on the resource. See Authorization AlgorithmAttaching a security policy to objects in the protected object space controls access to objects in a domain. After attaching a security policy to an object, any change to the security policy is reflected immediately throughout the domain. for details on the algorithm used.The decision to accept or deny the request is returned as a recommendation to the resource manager through the policy enforcer.If the request is finally approved, the resource manager passes the request on to the application responsible for the resource.The client receives the results of the requested operation.Implementation of a network security policyControlling user and group participation in the domain and applying rules to resources that require protection determine the security policy for a domain. These rules are defined by access control lists (ACLs), protected object policies (POPs), and authorization rules.

The authorization process: step-by-step

This example illustrates how the authorization process works.

Figure 73. illustrates the complete authorization process.

Figure 73. The Security Access Manager authorization process

An authenticated client request for a resource is directed to the resource manager server and intercepted by the policy enforcer process. For example, the resource manager can be WebSEAL for Hypertext Transfer Protocol (HTTP), HTTPS access, or another application.

The policy enforcer process uses the authorization API to call the authorization service for an authorization decision. For more information about the authorization API, see Security Access Manager authorization API.

The authorization service does an authorization check on the resource. See Authorization Algorithm for details on the algorithm used.

The decision to accept or deny the request is returned as a recommendation to the resource manager through the policy enforcer.

If the request is finally approved, the resource manager passes the request on to the application responsible for the resource.

The client receives the results of the requested operation.

Parent topic: Implementation of a network security policy

Security Access Manager authorization APISecurity Access Manager authorization APIThe Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself. authorizationAPIoverviewmodescachelocalmodescacheremoteThe authorization API allows Security Access Manager applications and other applications to query the authorization service to make authorization decisions. At the same time, the authorization API shields the application from the complexities of the actual decision-making process, including issues of management, storage, caching, replication, credential formats, and authentication methods.The authorization API provides a standard programming model for coding authorization requests and decisions. You can use the authorization API to make standardized calls to the centrally managed authorization service from any existing or newly developed application.The authorization API can be used in one of the following modes: Remote cache moderemote cache modeIn this mode, the API is initialized to call the remote authorization server to do authorization decisions on behalf of the application. The authorization server maintains its own cache of the replica authorization policy database. This mode is best suited for handling authorization requests from application clients. For more information about remote cache mode, see Authorization API: remote cache modeIn remote cache mode, resource managers use the function calls from the authorization API to communicate to the remote authorization server. .Local cache modelocal cache modeIn this mode, the API is initialized to download and maintain a local replica of the authorization database for the application. Local cache mode provides better performance because the application does all authorization decisions locally instead of across a network. However, the processor usage of database replication and the security implications of using this mode make it best suited for use by trusted application servers. For more information about local cache mode, see Authorization API: local cache modeIn local cache mode, the API downloads and maintains a replica of the authorization policy database on the local file system of the resource manager. It makes all authorization decisions in-memory, which results in higher performance and better reliability..The authorization API also works independently from the underlying security infrastructure, the credential format, and the evaluating mechanism. The authorization API makes it possible to request an authorization check and get a simple yes or no recommendation in return. The details of the authorization check mechanism are invisible to the user.Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.Authorization API examplesApplications can use the authorization API to do access control on specific and specialized processes.Authorization API: remote cache modeIn remote cache mode, resource managers use the function calls from the authorization API to communicate to the remote authorization server. Authorization API: local cache modeIn local cache mode, the API downloads and maintains a replica of the authorization policy database on the local file system of the resource manager. It makes all authorization decisions in-memory, which results in higher performance and better reliability.

Security Access Manager authorization API

The Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself.

The authorization API allows Security Access Manager applications and other applications to query the authorization service to make authorization decisions. At the same time, the authorization API shields the application from the complexities of the actual decision-making process, including issues of management, storage, caching, replication, credential formats, and authentication methods.

The authorization API provides a standard programming model for coding authorization requests and decisions. You can use the authorization API to make standardized calls to the centrally managed authorization service from any existing or newly developed application.

The authorization API can be used in one of the following modes:

Remote cache mode

In this mode, the API is initialized to call the remote authorization server to do authorization decisions on behalf of the application. The authorization server maintains its own cache of the replica authorization policy database. This mode is best suited for handling authorization requests from application clients.

For more information about remote cache mode, see Authorization API: remote cache mode.

Local cache mode

In this mode, the API is initialized to download and maintain a local replica of the authorization database for the application. Local cache mode provides better performance because the application does all authorization decisions locally instead of across a network. However, the processor usage of database replication and the security implications of using this mode make it best suited for use by trusted application servers.

For more information about local cache mode, see Authorization API: local cache mode.

The authorization API also works independently from the underlying security infrastructure, the credential format, and the evaluating mechanism. The authorization API makes it possible to request an authorization check and get a simple yes or no recommendation in return. The details of the authorization check mechanism are invisible to the user.

Authorization API examples
Applications can use the authorization API to do access control on specific and specialized processes.

Authorization API: remote cache mode
In remote cache mode, resource managers use the function calls from the authorization API to communicate to the remote authorization server.

Authorization API: local cache mode
In local cache mode, the API downloads and maintains a replica of the authorization policy database on the local file system of the resource manager. It makes all authorization decisions in-memory, which results in higher performance and better reliability.

Parent topic: Security Access Manager overview

Authorization API examplesAuthorization API examplesApplications can use the authorization API to do access control on specific and specialized processes.authorization APIexamples Example 1You can design a graphical interface to dynamically show interface controls as active or inactive, according to the results of the authorization check.Example 2Figure 1 illustrates a request for a Common Gateway Interface (CGI) transaction by a web application. The lowest level of authorization, as illustrated in Figure A of Figure 1, involves an “all-or-nothing” access control on the Uniform Resource Locator (URL). This coarse-grained level of authorization determines only whether the client can run the CGI program. If access is allowed to the CGI application, no further control is available to resources manipulated by the CGI application. As illustrated in Figure B of Figure 1, access controls were set on resources that the CGI program manipulates. The web application is configured to use the authorization API. The CGI program can call the authorization service to make authorization decisions on the resources it manipulates based on the identity of the requesting client. Example use of the authorization APIExample use of the authorization API Security Access Manager authorization APIThe Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself.

Authorization API examples

Applications can use the authorization API to do access control on specific and specialized processes.

Example 1

You can design a graphical interface to dynamically show interface controls as active or inactive, according to the results of the authorization check.

Example 2

Figure 74. illustrates a request for a Common Gateway Interface (CGI) transaction by a web application.

The lowest level of authorization, as illustrated in Figure A of Figure 74., involves an “all-or-nothing” access control on the Uniform Resource Locator (URL). This coarse-grained level of authorization determines only whether the client can run the CGI program. If access is allowed to the CGI application, no further control is available to resources manipulated by the CGI application.

As illustrated in Figure B of Figure 74., access controls were set on resources that the CGI program manipulates. The web application is configured to use the authorization API. The CGI program can call the authorization service to make authorization decisions on the resources it manipulates based on the identity of the requesting client.

Figure 74. Example use of the authorization API

Parent topic: Security Access Manager authorization API

Authorization API: remote cache modeAuthorization API: remote cache modeIn remote cache mode, resource managers use the function calls from the authorization API to communicate to the remote authorization server. remote cache modeauthorizationAPIremote cache modemodesauthorization API remote cacheThe authorization server functions as the authorization decision-making evaluator and maintains its own replica authorization policy database.The authorization server decides and returns a recommendation to the application through the API. The server can also write an audit record that contains the details of the authorization decision request.The remote cache mode requires an authorization server that runs in a domain, as shown in Figure 1. The authorization server can be on the same system as the application or on another system. You also can install the authorization server on more than one system in a domain for high availability. The authorization API transparently performs failover when a particular authorization server fails. Authorization API: remote cache modeAuthorization API: remote cache modeSecurity Access Manager authorization APIThe Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself.

Authorization API: remote cache mode

In remote cache mode, resource managers use the function calls from the authorization API to communicate to the remote authorization server.

The authorization server functions as the authorization decision-making evaluator and maintains its own replica authorization policy database.

The authorization server decides and returns a recommendation to the application through the API. The server can also write an audit record that contains the details of the authorization decision request.

The remote cache mode requires an authorization server that runs in a domain, as shown in Figure 75.. The authorization server can be on the same system as the application or on another system. You also can install the authorization server on more than one system in a domain for high availability. The authorization API transparently performs failover when a particular authorization server fails.

Figure 75. Authorization API: remote cache mode

Parent topic: Security Access Manager authorization API

Authorization API: local cache modeAuthorization API: local cache modeIn local cache mode, the API downloads and maintains a replica of the authorization policy database on the local file system of the resource manager. It makes all authorization decisions in-memory, which results in higher performance and better reliability.local cache modeauthorizationAPIlocal cache modemodesauthorization APIlocal cacheThe local replica is persistent across invocations of the application. When the API starts in replica mode, it checks for updates to the master authorization policy database that were made after the local replica was built. Authorization API: local cache modeAuthorization API: local cache modeSecurity Access Manager authorization APIThe Security Access Manager authorization application programming interface (API) is the interface between the resource manager requesting the authorization check and the authorization service itself.

Authorization API: local cache mode

In local cache mode, the API downloads and maintains a replica of the authorization policy database on the local file system of the resource manager. It makes all authorization decisions in-memory, which results in higher performance and better reliability.

The local replica is persistent across invocations of the application. When the API starts in replica mode, it checks for updates to the master authorization policy database that were made after the local replica was built.

Figure 76. Authorization API: local cache mode

Parent topic: Security Access Manager authorization API

External authorization capabilityExternal authorization capabilitySecurity Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements. external authorization serviceintroductionIn some cases, it might not be possible for the standard Security Access Manager policy implementations to express all conditions required by a security policy. The standard policy implementation uses ACLs, POPs, and authorization rules to manage access to resources.You can use the external authorization service to impose additional authorization controls and conditions that are dictated by a separate, external, authorization service module.Security Access Manager overviewSecurity Access Manager is an authentication and authorization solution for corporate web, client/server, and existing applications. Use Security Access Manager to control user access to protected information and resources. By providing a centralized, flexible, and scalable access control solution, Security Access Manager builds secure and easy-to-manage network-based applications and infrastructure.External authorization serviceExternal authorization capability is automatically built into the Security Access Manager authorization service. Resource managers can use an external authorization service to provide a seamless experience.Application of specific conditions on resource requestsAn external authorization service can impose more specific conditions or system-specific side effects on a successful or unsuccessful access attempt.Authorization evaluation processSecurity Access Manager uses a multi-step process to evaluate authorization requests.The process of implementing an external authorization serviceThis process requires you to write a plug-in module for the external resource manager. You then register the external authorization service with the resource manager.Deployment strategiesYou can deploy an external authorization service in several ways.

External authorization capability

Security Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements.

In some cases, it might not be possible for the standard Security Access Manager policy implementations to express all conditions required by a security policy. The standard policy implementation uses ACLs, POPs, and authorization rules to manage access to resources.

You can use the external authorization service to impose additional authorization controls and conditions that are dictated by a separate, external, authorization service module.

External authorization service
External authorization capability is automatically built into the Security Access Manager authorization service. Resource managers can use an external authorization service to provide a seamless experience.

Application of specific conditions on resource requests
An external authorization service can impose more specific conditions or system-specific side effects on a successful or unsuccessful access attempt.

Authorization evaluation process
Security Access Manager uses a multi-step process to evaluate authorization requests.

The process of implementing an external authorization service
This process requires you to write a plug-in module for the external resource manager. You then register the external authorization service with the resource manager.

Deployment strategies
You can deploy an external authorization service in several ways.

Parent topic: Security Access Manager overview

External authorization serviceExternal authorization serviceExternal authorization capability is automatically built into the Security Access Manager authorization service. Resource managers can use an external authorization service to provide a seamless experience.authorizationserviceextendingauthorizationserviceexternalIf you configure an external authorization service, the Security Access Manager authorization service incorporates the access decision paths into its evaluation process.Resource managers such as WebSEAL benefit from the additional, seamless contribution of an external authorization service. Applications that use the authorization API also benefit. Any addition to the security policy through an external authorization service is not apparent to these applications. The addition requires no change to the applications.The external authorization service architecture provides the full integration of an existing security service. An external authorization service preserves your investment in security infrastructure by incorporating existing servers into the Security Access Manager authorization decision-making process.External authorization capabilitySecurity Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements.

External authorization service

External authorization capability is automatically built into the Security Access Manager authorization service. Resource managers can use an external authorization service to provide a seamless experience.

If you configure an external authorization service, the Security Access Manager authorization service incorporates the access decision paths into its evaluation process.

Resource managers such as WebSEAL benefit from the additional, seamless contribution of an external authorization service. Applications that use the authorization API also benefit. Any addition to the security policy through an external authorization service is not apparent to these applications. The addition requires no change to the applications.

The external authorization service architecture provides the full integration of an existing security service. An external authorization service preserves your investment in security infrastructure by incorporating existing servers into the Security Access Manager authorization decision-making process.

Parent topic: External authorization capability

Application of specific conditions on resource requestsApplication of specific conditions on resource requestsAn external authorization service can impose more specific conditions or system-specific side effects on a successful or unsuccessful access attempt.resource requests, example conditionsExamples of such conditions include: Causing an external auditing mechanism to record the successful or unsuccessful access attemptActively monitoring the access attempt and causing an alert or alarm whenever unacceptable behavior is detectedConducting billing or micro-payment transactionsImposing access quotas on a protected resourceExternal authorization capabilitySecurity Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements.

Application of specific conditions on resource requests

An external authorization service can impose more specific conditions or system-specific side effects on a successful or unsuccessful access attempt.

Examples of such conditions include:

Causing an external auditing mechanism to record the successful or unsuccessful access attempt

Actively monitoring the access attempt and causing an alert or alarm whenever unacceptable behavior is detected

Conducting billing or micro-payment transactions

Imposing access quotas on a protected resource

Parent topic: External authorization capability

Authorization evaluation processAuthorization evaluation processSecurity Access Manager uses a multi-step process to evaluate authorization requests.authorizationevaluation processevaluation process, authorizationAn authorization decision that incorporates an external authorization server takes place in the following manner:If a trigger condition is met during an access decision, the external authorization services that were configured for that condition are each called in turn. The external authorization services evaluate their own external authorization constraints. Invocation of the external authorization service occurs regardless of whether the necessary permission is granted to the user by the Security Access Manager authorization service.Each external authorization service returns a decision of permitted, denied, or indifferent. When indifferent is returned, the external authorization service determined that its functionality is not required for the decision process and that it does not participate.Each external authorization service decision is weighted according to the level of importance that its decision carries in the process. The weighting of individual external authorization services is configured when the service plug-in is loaded.All authorization decision results are summed and combined with the decision made by the Security Access Manager authorization service. The resulting decision is returned to the caller.External authorization capabilitySecurity Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements. Example of an external authorization serviceIn this example, the external authorization service imposes a quota restriction on how often a photo-quality printer resource can be accessed.

Authorization evaluation process

Security Access Manager uses a multi-step process to evaluate authorization requests.

An authorization decision that incorporates an external authorization server takes place in the following manner:

If a trigger condition is met during an access decision, the external authorization services that were configured for that condition are each called in turn. The external authorization services evaluate their own external authorization constraints.

Invocation of the external authorization service occurs regardless of whether the necessary permission is granted to the user by the Security Access Manager authorization service.

Each external authorization service returns a decision of permitted, denied, or indifferent.

When indifferent is returned, the external authorization service determined that its functionality is not required for the decision process and that it does not participate.

Each external authorization service decision is weighted according to the level of importance that its decision carries in the process.

The weighting of individual external authorization services is configured when the service plug-in is loaded.

All authorization decision results are summed and combined with the decision made by the Security Access Manager authorization service. The resulting decision is returned to the caller.

Example of an external authorization service
In this example, the external authorization service imposes a quota restriction on how often a photo-quality printer resource can be accessed.

Parent topic: External authorization capability

Example of an external authorization serviceExampleIn this example, the external authorization service imposes a quota restriction on how often a photo-quality printer resource can be accessed.examplesexternal authorization serviceauthorizationserviceexternal exampleFigure 1 illustrates an authorization decision that involves an application server and an external authorization service. External authorization service with an application serverExternal authorization service with an application serverThe service implementation imposes a limit on the number of job submissions that any one person can make to this printer in one week. A trigger condition is attached to the photo printer resource so that the external authorization service is called whenever the photo printer is accessed.The external authorization service is loaded with the default decision weighting of 101. The default decision weighting overrides any decision made by the Security Access Manager authorization service if required. The resource manager server receives a request from a client for access to an online photo printing resource. The client is a member of the appropriate group GraphicArtists and so is typically permitted to submit jobs to the printer.The application server first consults the Security Access Manager authorization service to determine whether the requesting user has permission to submit jobs to the printer.The authorization service verifies the access permissions on the target requested object and compares the permissions against the capabilities of the requesting user: group GraphicArtists rx In the ACL on the printer resource, the x permission grants any user in the GraphicArtists group access to the resource. Therefore, the authorization service grants the user permission to submit the job.The photo printer resource is being accessed and an external authorization service trigger condition is attached to this object. A request is also made to the external authorization service configured for that trigger condition. The external authorization service receives all the Access Decision Information (ADI) that was passed in with the original access decision check by the resource manager server.The external authorization service consults a record of previous accesses made by this user. If the requesting user is within the quota for the week, it returns an access decision of indifferent. The external authorization service is indifferent to the request. The service does not participate in the access decision because the conditions for denying access are not present. If the user exceeds the quota, then the external authorization service returns a decision of access denied. For this example, the requester exceeds the quota. The external authorization service detects this problem and returns an access denied decision.The Security Access Manager authorization service receives the access denied result from the external authorization service. It then takes this decision and weights it with the default external authorization service weighting value of 101. The results of the external authorization service decision and the decision made by the Security Access Manager authorization service are combined. The result is access denied because the result of the external authorization service (–101) outweighs that of the Security Access Manager authorization service (100).The resource manager server rejects the job submission to the photo printer resource.The resource manager server returns a response to the caller to indicate that the job was rejected.Authorization evaluation processSecurity Access Manager uses a multi-step process to evaluate authorization requests.

Example of an external authorization service

In this example, the external authorization service imposes a quota restriction on how often a photo-quality printer resource can be accessed.

Figure 77. illustrates an authorization decision that involves an application server and an external authorization service.

Figure 77. External authorization service with an application server

The service implementation imposes a limit on the number of job submissions that any one person can make to this printer in one week. A trigger condition is attached to the photo printer resource so that the external authorization service is called whenever the photo printer is accessed.

The external authorization service is loaded with the default decision weighting of 101. The default decision weighting overrides any decision made by the Security Access Manager authorization service if required.

The resource manager server receives a request from a client for access to an online photo printing resource. The client is a member of the appropriate group GraphicArtists and so is typically permitted to submit jobs to the printer.

The application server first consults the Security Access Manager authorization service to determine whether the requesting user has permission to submit jobs to the printer.

The authorization service verifies the access permissions on the target requested object and compares the permissions against the capabilities of the requesting user:

group GraphicArtists rx

In the ACL on the printer resource, the x permission grants any user in the GraphicArtists group access to the resource. Therefore, the authorization service grants the user permission to submit the job.

The photo printer resource is being accessed and an external authorization service trigger condition is attached to this object. A request is also made to the external authorization service configured for that trigger condition.

The external authorization service receives all the Access Decision Information (ADI) that was passed in with the original access decision check by the resource manager server.

The external authorization service consults a record of previous accesses made by this user. If the requesting user is within the quota for the week, it returns an access decision of indifferent.

The external authorization service is indifferent to the request. The service does not participate in the access decision because the conditions for denying access are not present.

If the user exceeds the quota, then the external authorization service returns a decision of access denied.

For this example, the requester exceeds the quota. The external authorization service detects this problem and returns an access denied decision.

The Security Access Manager authorization service receives the access denied result from the external authorization service. It then takes this decision and weights it with the default external authorization service weighting value of 101.

The results of the external authorization service decision and the decision made by the Security Access Manager authorization service are combined. The result is access denied because the result of the external authorization service (–101) outweighs that of the Security Access Manager authorization service (100).

The resource manager server rejects the job submission to the photo printer resource.

The resource manager server returns a response to the caller to indicate that the job was rejected.

Parent topic: Authorization evaluation process

The process of implementing an external authorization serviceThe process of implementing an external authorization serviceThis process requires you to write a plug-in module for the external resource manager. You then register the external authorization service with the resource manager.external authorization serviceimplementingauthorizationserviceimplementation of externalWrite an external resource manager service plug-in module with an authorization interface that can be referenced during authorization decisions.Register the external authorization service with the resource manager so that the resource manager can load the plug-in service at initialization time. Registering the service sets a trigger condition for the invocation of the external authorization service. When the trigger condition is encountered during an authorization check, the external authorization service interface is called to make an additional authorization decision.External authorization capabilitySecurity Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements.

The process of implementing an external authorization service

This process requires you to write a plug-in module for the external resource manager. You then register the external authorization service with the resource manager.

Write an external resource manager service plug-in module with an authorization interface that can be referenced during authorization decisions.

Register the external authorization service with the resource manager so that the resource manager can load the plug-in service at initialization time.

Registering the service sets a trigger condition for the invocation of the external authorization service. When the trigger condition is encountered during an authorization check, the external authorization service interface is called to make an additional authorization decision.

Parent topic: External authorization capability

Deployment strategiesDeployment strategiesYou can deploy an external authorization service in several ways.external authorization servicedeployingauthorizationservicedeploying externalAny number of external authorization services can be registered with resource manager applications. Applications that can load external authorization services include the authorization server, other Security Access Manager resource managers, and any other resource manager applications that you create.Remote-mode authorization API clients make requests to the authorization server for authorization decisions. These clients automatically use any external authorization service that is loaded by the authorization server.More than one external authorization service can be called for any single trigger condition. First, the result of each external authorization service is weighted. Then the results are combined with the result of the Security Access Manager authorization service.Trigger conditions can be placed on objects with the use of a POP trigger. If a trigger condition is placed on an object, then any request to that object instigates a call to the appropriate external authorization services.Trigger conditions can also be placed on the operations requested by a user. For example, an external authorization service can be triggered only when a user requests a Write operation to a protected resource. In this case, the external authorization service is not triggered for any other operation. It is then possible to develop sets of operations for which one or more external authorization services are triggered according to the requested set of operations.The external authorization services are implemented as dynamically loadable library (dynamic link library (DLL) modules. This feature greatly simplifies the task of external authorization service development. There is no requirement to make remote requests to the external authorization service. The load of the call is equivalent to the load of a function call.The combination of the authorization API and an external authorization service provides a highly extensible and flexible solution for implementing a complex security policy.External authorization capabilitySecurity Access Manager provides an optional external authorization capability to accommodate any additional authorization requirements.

Deployment strategies

You can deploy an external authorization service in several ways.

Any number of external authorization services can be registered with resource manager applications. Applications that can load external authorization services include the authorization server, other Security Access Manager resource managers, and any other resource manager applications that you create.

Remote-mode authorization API clients make requests to the authorization server for authorization decisions. These clients automatically use any external authorization service that is loaded by the authorization server.

More than one external authorization service can be called for any single trigger condition. First, the result of each external authorization service is weighted. Then the results are combined with the result of the Security Access Manager authorization service.

Trigger conditions can be placed on objects with the use of a POP trigger. If a trigger condition is placed on an object, then any request to that object instigates a call to the appropriate external authorization services.

Trigger conditions can also be placed on the operations requested by a user. For example, an external authorization service can be triggered only when a user requests a Write operation to a protected resource. In this case, the external authorization service is not triggered for any other operation. It is then possible to develop sets of operations for which one or more external authorization services are triggered according to the requested set of operations.

The external authorization services are implemented as dynamically loadable library (dynamic link library (DLL) modules. This feature greatly simplifies the task of external authorization service development. There is no requirement to make remote requests to the external authorization service. The load of the call is equivalent to the load of a function call.

The combination of the authorization API and an external authorization service provides a highly extensible and flexible solution for implementing a complex security policy.

Parent topic: External authorization capability

Web Portal ManagerWeb Portal ManagerWeb Portal ManagerSecurity Access Manager has both command-line and graphical interface interfaces for managing domains, users, groups, permissions, policies, and other resources in your enterprise.Web Portal Manager introductioncross-site request forgery attacksWeb Portal Managercross-site request forgery attacksWeb Portal Manageraccessing online helpThe command line interface, pdadmindefinitionpdadmin, is installed as part of the runtime package. The graphical user interface is a management console, called Web Portal Manager. Although you can manage your enterprise through either interface, only a subset of the management tasks can be completed through Web Portal Manager. To compare the mapping between the pdadmin utility and Web Portal Manager tasks, see pdadmin to Web Portal Manager equivalentsThis appendix shows the mapping of the administration pdadmin commands to Web Portal Manager..Another difference between these interfaces is that when you use the pdadmin utility, you can specify a file. With Web Portal Manager, you cannot specify a file name. In some cases, however, you can copy and paste the contents of the file.You can automate certain management tasks by writing scripts that use the pdadmin utility.For more information about pdadmin, see the Command Reference topics in the Knowledge Center.Online helpInstructions for completing tasks with Web Portal Manager are documented in the online help system. Use the help system if you have questions when you enter information in fields or select or clear choices.To access the online help:Use Web Portal Manager to log on to the domain. Select a task such as GroupImport Group.In the task title bar, click the question mark icon on the right side of the page. A help window contains the online information for completing the task.Mitigating cross-site request forgery attacksTo help mitigate cross-site request forgery (CSRF) attacks in Web Portal Manager, a token has been added to certain Web Portal Manager requests.This token modifies the URL to the Web Portal Manager web pages. An error is returned if the token is missing from the request or does not match the real session token.A CSRF attack is a type of malicious web site attack that is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. CSRF uses the trust that a site has in the browser of an authenticated user for malicious attacks. CSRF uses links or scripts to send involuntary HTTP requests to a target site where the user is authenticated. Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy.

Web Portal Manager

Security Access Manager has both command-line and graphical interface interfaces for managing domains, users, groups, permissions, policies, and other resources in your enterprise.

The command line interface, pdadmin, is installed as part of the runtime package. The graphical user interface is a management console, called Web Portal Manager.

Although you can manage your enterprise through either interface, only a subset of the management tasks can be completed through Web Portal Manager. To compare the mapping between the pdadmin utility and Web Portal Manager tasks, see pdadmin to Web Portal Manager equivalents.

Another difference between these interfaces is that when you use the pdadmin utility, you can specify a file. With Web Portal Manager, you cannot specify a file name. In some cases, however, you can copy and paste the contents of the file.

You can automate certain management tasks by writing scripts that use the pdadmin utility.

For more information about pdadmin, see the Command Reference topics in the Knowledge Center.

Online help

Instructions for completing tasks with Web Portal Manager are documented in the online help system. Use the help system if you have questions when you enter information in fields or select or clear choices.

To access the online help:

Use Web Portal Manager to log on to the domain.

Select a task such as Group > Import Group.

In the task title bar, click the question mark icon on the right side of the page. A help window contains the online information for completing the task.

Mitigating cross-site request forgery attacks

To help mitigate cross-site request forgery (CSRF) attacks in Web Portal Manager, a token has been added to certain Web Portal Manager requests.

This token modifies the URL to the Web Portal Manager web pages. An error is returned if the token is missing from the request or does not match the real session token.

A CSRF attack is a type of malicious web site attack that is sometimes called a one-click attack or session riding. This type of attack sends unauthorized requests from a user that the website trusts. CSRF uses the trust that a site has in the browser of an authenticated user for malicious attacks. CSRF uses links or scripts to send involuntary HTTP requests to a target site where the user is authenticated.

Parent topic: Access Manager Platform and Supporting Components administration

Security Access Manager administrationSecurity Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.administrationsetting upThe administration of Security Access Manager involves the following high-level tasks.Create domains and subdomains for management purposes, as necessary. See Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains..Install and configure resource managers. During configuration, Security Access Manager resource managers and other components create a protected object space and protected resources, also known as protected objects. Create additional object spaces, as needed, for management purposes. See Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space..Define protected objects in the object space, as needed, to represent the resources that are to be protected. For protected objects, you can define the following characteristics:Who is allowed access.What type of access is allowed.When that access is allowed.What other conditions that must be met before Security Access Manager allows access.Whether the access request is audited. See Manage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object..Define users and groups that require access to the protected resources. See Manage users and groupsAn initial domain administrator is created when a new domain is created..Implement your security policy by attaching the following elements to objects that are in the protected object space:An access control list (ACL)A protected object policy (POP)An authorization ruleAccess Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. DomainsA domain consists of all the resources that require protection and the associated security policy used to protect those resources. Protected object spaceSecurity Access Manager conceptualizes resources in a domain by showing a virtual representation called the protected object space. The protected object space is the logical and hierarchical portrayal of resources that belong to a domain.Users and groupsSecurity Access Manager maintains information about its users and groups in the user registry.Security policyAttaching a security policy to objects in the protected object space controls access to objects in a domain. After attaching a security policy to an object, any change to the security policy is reflected immediately throughout the domain.ACL policies The ACL policy defines who has access to and what operations can be performed on the object.Protected object policiesA protected object policy (POP) specifies a security policy that applies to an object regardless of which user or which operation is done. A POP imposes access conditions on an object based on the time of the access. A POP also indicates whether the access request must be audited. Authorization rulesAn authorization rule policy specifies which security policy applies to an object based on various conditions, such as context and environment. Guidelines for a secure object spaceTo configure a secure object space, use these guidelines.

Security Access Manager administration

Administering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

The administration of Security Access Manager involves the following high-level tasks.

Create domains and subdomains for management purposes, as necessary. See Domain management.

Install and configure resource managers. During configuration, Security Access Manager resource managers and other components create a protected object space and protected resources, also known as protected objects.

Create additional object spaces, as needed, for management purposes. See Object space management.

Define protected objects in the object space, as needed, to represent the resources that are to be protected. For protected objects, you can define the following characteristics:

Who is allowed access.

What type of access is allowed.

When that access is allowed.

What other conditions that must be met before Security Access Manager allows access.

Whether the access request is audited.

See Manage protected objects.

Define users and groups that require access to the protected resources. See Manage users and groups.

Implement your security policy by attaching the following elements to objects that are in the protected object space:

An access control list (ACL)

A protected object policy (POP)

An authorization rule

Domains
A domain consists of all the resources that require protection and the associated security policy used to protect those resources.

Protected object space
Security Access Manager conceptualizes resources in a domain by showing a virtual representation called the protected object space. The protected object space is the logical and hierarchical portrayal of resources that belong to a domain.

Users and groups
Security Access Manager maintains information about its users and groups in the user registry.

Security policy
Attaching a security policy to objects in the protected object space controls access to objects in a domain. After attaching a security policy to an object, any change to the security policy is reflected immediately throughout the domain.

ACL policies
The ACL policy defines who has access to and what operations can be performed on the object.

Protected object policies
A protected object policy (POP) specifies a security policy that applies to an object regardless of which user or which operation is done. A POP imposes access conditions on an object based on the time of the access. A POP also indicates whether the access request must be audited.

Authorization rules
An authorization rule policy specifies which security policy applies to an object based on various conditions, such as context and environment.

Guidelines for a secure object space
To configure a secure object space, use these guidelines.

Parent topic: Access Manager Platform and Supporting Components administration

DomainsDomainsA domain consists of all the resources that require protection and the associated security policy used to protect those resources. managementdomaindomaindefinitionThe resources that you can protect depend on the resource managers that are installed. These resources depend on which resource managers are installed. The resources can be any physical or logical entity, including objects such as files, directories, web pages, printer and network services, and message queues. Any security policy that is implemented in a domain affects only the objects in that domain. Users with authority to do tasks in one domain do not necessarily have the authority to do those tasks in other domains.Security Access Manager creates a domain, called the management domain, as part of its initial configuration. The default name of this management domain is Default. It is in a stand-alone naming context, with a suffix called secAuthority=Default. This domain is used by Security Access Manager to manage the security policy of all domains and is available for managing other protected resources as well. The administrator can rename the management domain and change its location when the policy server is configured.For small and moderately sized enterprises, one domain is typically sufficient. If only one domain is needed, no explicit action needs to be taken. In large enterprises, however, you might want to define two or more domains. Each domain is given a name and is established with a unique set of physical and logical resources. The security administrator can define the resources in a domain based on geographical area, business unit, or major organizational division within the enterprise. The security policy defined in the domain affects only the resources in that domain, which allows data to be partitioned and managed independently.A multiple domain environment can be invaluable when there is a business need to keep a physical separation between different sets of data. The following other benefits are associated with using multiple domains: Increased securitySecurity policy data for each domain is mutually exclusive. You cannot associate users, groups, and resources that are defined in a domain with another domain. For example, suppose that a user named John Doe is identified as JohnDoe in the Sales domain and as JDoe in the Advertising domain. Although the same person, each user ID is unique for each domain. As a result, resources that are available to user JohnDoe can be granted access by the unique ID by which the user is defined in that domain (Sales). In addition, user JohnDoe can be granted access in the Sales domain by the unique ID in the groups of which JohnDoe is a member. Likewise, user JDoe can be granted access only by the unique ID by which the user is defined in the Advertising domain.Simplified administrationYou can assign independent administrators to handle policy management tasks for each domain. For example, assume that you are an IT specialist for a large corporation. You are assigned to deploy Security Access Manager from a single data center. You can create a separate domain with a unique policy database and an administrator for each organization, division, or geographic area in your company. As users, groups, or resources change, the assigned administrator is responsible for updating the security policy for that particular domain. This domain administrator can also delegate administration tasks to others in that domain.An administrator assigned to a specific domain has authority only in that domain. By default, an administrator can view users and groups defined in the user registry that are not necessarily Security Access Manager users or groups. This feature is beneficial if, for example, an administrator wants to import a user or group from a different domain. The administrator of the management domain can limit the registry data that a domain administrator can access. To do so, add the allowed-registry-substrings stanza entry to the [domains] stanza in the ivmgrd.conf configuration file for the policy server.For more information about managing domains, see Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains..Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Domains

A domain consists of all the resources that require protection and the associated security policy used to protect those resources.

The resources that you can protect depend on the resource managers that are installed. These resources depend on which resource managers are installed. The resources can be any physical or logical entity, including objects such as files, directories, web pages, printer and network services, and message queues. Any security policy that is implemented in a domain affects only the objects in that domain. Users with authority to do tasks in one domain do not necessarily have the authority to do those tasks in other domains.

Security Access Manager creates a domain, called the management domain, as part of its initial configuration. The default name of this management domain is Default. It is in a stand-alone naming context, with a suffix called secAuthority=Default. This domain is used by Security Access Manager to manage the security policy of all domains and is available for managing other protected resources as well. The administrator can rename the management domain and change its location when the policy server is configured.

For small and moderately sized enterprises, one domain is typically sufficient. If only one domain is needed, no explicit action needs to be taken.

In large enterprises, however, you might want to define two or more domains. Each domain is given a name and is established with a unique set of physical and logical resources. The security administrator can define the resources in a domain based on geographical area, business unit, or major organizational division within the enterprise. The security policy defined in the domain affects only the resources in that domain, which allows data to be partitioned and managed independently.

A multiple domain environment can be invaluable when there is a business need to keep a physical separation between different sets of data. The following other benefits are associated with using multiple domains:

Increased security

Security policy data for each domain is mutually exclusive. You cannot associate users, groups, and resources that are defined in a domain with another domain. For example, suppose that a user named John Doe is identified as JohnDoe in the Sales domain and as JDoe in the Advertising domain. Although the same person, each user ID is unique for each domain. As a result, resources that are available to user JohnDoe can be granted access by the unique ID by which the user is defined in that domain (Sales). In addition, user JohnDoe can be granted access in the Sales domain by the unique ID in the groups of which JohnDoe is a member. Likewise, user JDoe can be granted access only by the unique ID by which the user is defined in the Advertising domain.

Simplified administration

You can assign independent administrators to handle policy management tasks for each domain. For example, assume that you are an IT specialist for a large corporation. You are assigned to deploy Security Access Manager from a single data center. You can create a separate domain with a unique policy database and an administrator for each organization, division, or geographic area in your company. As users, groups, or resources change, the assigned administrator is responsible for updating the security policy for that particular domain. This domain administrator can also delegate administration tasks to others in that domain.

An administrator assigned to a specific domain has authority only in that domain. By default, an administrator can view users and groups defined in the user registry that are not necessarily Security Access Manager users or groups. This feature is beneficial if, for example, an administrator wants to import a user or group from a different domain. The administrator of the management domain can limit the registry data that a domain administrator can access. To do so, add the allowed-registry-substrings stanza entry to the [domains] stanza in the ivmgrd.conf configuration file for the policy server.

For more information about managing domains, see Domain management.

Parent topic: Security Access Manager administration

Protected object spaceProtected object spacesSecurity Access Manager conceptualizes resources in a domain by showing a virtual representation called the protected object space. The protected object space is the logical and hierarchical portrayal of resources that belong to a domain.protectedobject spaceobject spacedefinitionresourceobjectscontainerobjectshierarchyThe structure of the protected object space consists of the following types of objects: Resource objectsThe logical representation of actual physical resources in a domain, such as files, services, web pages, and message queues.Container objectsStructural components that group resource objects hierarchically into distinct functional regions.Security policy can be applied to both types of objects. Figure 1 shows a logical representation of a protected object space with multiple container and resource objects. This illustration shows container objects as white boxes and resource objects as gray boxes.Security Access Manager protected object spaceFigure showing a logical representation of a protected object space.The structural top of the protected object space is the root container object. Below the root container object are one or more container objects. Each container object represents an object space that consists of a related set of resources. These resources can be resource objects or container objects.The installation of Security Access Manager creates the /Management object space. This object space consists of the objects that are used to manage Security Access Manager itself. Under the /Management object space, the installation creates the following container objects: /Users/Groups/POP/Action/ACL/GSO/Server/Config/ReplicaFigure 2 shows the complete /Management object space that is created during the installation of Security Access Manager.Regions of the Security Access Manager protected object spaceFigure showing the /Management object space within the protected object space.Each resource manager that protects a related set of resources creates its own object space. For example, the installation of the WebSEAL component creates the /WebSEAL object space.Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Protected object space

Security Access Manager conceptualizes resources in a domain by showing a virtual representation called the protected object space. The protected object space is the logical and hierarchical portrayal of resources that belong to a domain.

The structure of the protected object space consists of the following types of objects:

Resource objects

The logical representation of actual physical resources in a domain, such as files, services, web pages, and message queues.

Container objects

Structural components that group resource objects hierarchically into distinct functional regions.

Security policy can be applied to both types of objects. Figure 78. shows a logical representation of a protected object space with multiple container and resource objects. This illustration shows container objects as white boxes and resource objects as gray boxes.

Figure 78. Security Access Manager protected object space

The structural top of the protected object space is the root container object. Below the root container object are one or more container objects. Each container object represents an object space that consists of a related set of resources. These resources can be resource objects or container objects.

The installation of Security Access Manager creates the /Management object space. This object space consists of the objects that are used to manage Security Access Manager itself. Under the /Management object space, the installation creates the following container objects:

/Users

/Groups

/POP

/Action

/ACL

/GSO

/Server

/Config

/Replica

Figure 79. shows the complete /Management object space that is created during the installation of Security Access Manager.

Figure 79. Regions of the Security Access Manager protected object space

Each resource manager that protects a related set of resources creates its own object space. For example, the installation of the WebSEAL component creates the /WebSEAL object space.

Parent topic: Security Access Manager administration

Users and groupsUsers and groupsSecurity Access Manager maintains information about its users and groups in the user registry.dynamicgroupsupportgroupsdynamicusersadministratorgroupsiv-admindomainadministrator (sec_master)sec_masterdomain administratorsec_masteruseruserssec_masteriv-admin group If you have a user registry that maintains users and groups for another application, you can import this user registry information into Security Access Manager. If a required user or group was not in the user registry before it was imported into Security Access Manager or a new user or group needs to be added to the Security Access Manager user registry, you can create it using Security Access Manager.Basic users, or users in the registry that are not imported to the Security Access Manager, are supported. For more information, see Configuring the runtime to authenticate basic usersBasic users are users in the registry that are not imported in to Security Access Manager. Edit the ldap.conf file so that basic users can authenticate in Security Access Manager..Security Access Manager supports two types of group definitions. The most common type of group maintains the group membership as an explicit list of members (users). This type of group is sometimes called a static group, because the membership is listed and maintained.For Active Directory and LDAP registry users, Security Access Manager also supports the use of dynamic groups. Dynamic groups are groups whose members are automatically resolved when the group is accessed. This resolution is based on the results of a defined search filter. For example, you create a dynamic group for members of department XYZ. If you import a new user whose data matches an entry in the search filter, the user is automatically added to the group. If an existing employee switches departments, the user is automatically removed from the group. Manual intervention is not required.The creation and management of a dynamic group can be complex and is specific to the vendor implementation. It requires a search-like filter to be specified and used for group membership resolution. Because of these variables, dynamic groups cannot be created or maintained with Security Access Manager utilities or user interfaces. The vendor-specific tools must be used to create and maintain dynamic groups. Security Access Manager, however, can import and use these dynamic groups after they are created.Security Access Manager supports different types of users. When a domain is created, a special user known as the domain administrator is created. For the management domain, the domain administrator is sec_master. The sec_master user and associated password are created during the configuration of the Security Access Manager policy server. For other domains, the user ID and password of the domain administrator are established when the domain is created. The domain administrator has nearly complete control of the domain. Think of the domain administrator as the Security Access Manager equivalent to the Linux or UNIX root account or the Microsoft Windows Administrator user.The domain administrator is added as a member of the Security Access Manager iv-admin group within the domain. The iv-admin group represents those users with domain administration privileges. When adding users to the iv-admin group, ensure that you do not compromise the security of your domain.Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Users and groups

Security Access Manager maintains information about its users and groups in the user registry.

If you have a user registry that maintains users and groups for another application, you can import this user registry information into Security Access Manager. If a required user or group was not in the user registry before it was imported into Security Access Manager or a new user or group needs to be added to the Security Access Manager user registry, you can create it using Security Access Manager.

Basic users, or users in the registry that are not imported to the Security Access Manager, are supported. For more information, see Configuring the runtime to authenticate basic users.

Security Access Manager supports two types of group definitions. The most common type of group maintains the group membership as an explicit list of members (users). This type of group is sometimes called a static group, because the membership is listed and maintained.

For Active Directory and LDAP registry users, Security Access Manager also supports the use of dynamic groups. Dynamic groups are groups whose members are automatically resolved when the group is accessed. This resolution is based on the results of a defined search filter. For example, you create a dynamic group for members of department XYZ. If you import a new user whose data matches an entry in the search filter, the user is automatically added to the group. If an existing employee switches departments, the user is automatically removed from the group. Manual intervention is not required.

The creation and management of a dynamic group can be complex and is specific to the vendor implementation. It requires a search-like filter to be specified and used for group membership resolution. Because of these variables, dynamic groups cannot be created or maintained with Security Access Manager utilities or user interfaces. The vendor-specific tools must be used to create and maintain dynamic groups. Security Access Manager, however, can import and use these dynamic groups after they are created.

Security Access Manager supports different types of users. When a domain is created, a special user known as the domain administrator is created. For the management domain, the domain administrator is sec_master. The sec_master user and associated password are created during the configuration of the Security Access Manager policy server. For other domains, the user ID and password of the domain administrator are established when the domain is created. The domain administrator has nearly complete control of the domain. Think of the domain administrator as the Security Access Manager equivalent to the Linux or UNIX root account or the Microsoft Windows Administrator user.

The domain administrator is added as a member of the Security Access Manager iv-admin group within the domain. The iv-admin group represents those users with domain administration privileges. When adding users to the iv-admin group, ensure that you do not compromise the security of your domain.

Parent topic: Security Access Manager administration

Security policySecurity policyAttaching a security policy to objects in the protected object space controls access to objects in a domain. After attaching a security policy to an object, any change to the security policy is reflected immediately throughout the domain.security policyprotected object spacesecurity policydomainACLpoliciessecurity policyprotected objectpolicyPOPdefinitionauthorizationrulesdefinitionEach security policy can be defined with a combination of the following controls: Access control list policiesAn access control list (ACL) policy specifies the set of predefined actions that a set of users and groups can do on an object. For example, a specific set of groups or users can be granted read access to an object.Protected object policiesA protected object policy (POP) specifies access conditions that are associated with an object. A POP affects all users and groups. For example, a time-of-day restriction can be placed on an object that excludes all users and groups from accessing that object during the specified time.Authorization rulesAn authorization rule specifies a complex condition that is evaluated to determine whether access is permitted. The data that determines whether access is permitted can be based on the context of the request, the current environment, or other external factors. For example, it can deny a request to modify an object more than five times in an eight-hour period.A security policy can be explicitly applied to an object or can be inherited by an object that is above it in the hierarchy. Apply an explicit security policy in the protected object space only at those points in the hierarchy where the security policy must change.You can implement a security policy by strategically attaching ACL policies, POPs, and authorization rules to objects that require protection. The Security Access Manager authorization service decides whether to allow or deny access to objects based on several criteria. One criterion is the credentials of the user that is making the request. Other criteria include the specific permissions and conditions that are specified in the ACL policies, POPs, and authorization rules.The authorization service uses the following algorithm to process the security policy that is attached to a protected object: Check permissions in the ACL policy to determine whether the user can override the attached POP or authorization rule. See ACL policies The ACL policy defines who has access to and what operations can be performed on the object. for information about the evaluation process. When there is an authorization rule attached and the user cannot override it, gather the Access Decision Information (ADI).When there is a POP attached: Check the Internet Protocol (IP) endpoint authentication method policy.Check the time-of-day policy.Check the audit-level policy and audit the access decision.When an authorization rule is attached and the user cannot override the authorization rule, check the authorization rule policy.When an external authorization service (EAS) operation or a POP trigger applies to this access decision, call the EAS.If any of the ACL policy, POP, or authorization rule evaluations fail, then the access request is denied. The EAS can override this decision on its own if it is configured to do so.Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Security policy

Attaching a security policy to objects in the protected object space controls access to objects in a domain. After attaching a security policy to an object, any change to the security policy is reflected immediately throughout the domain.

Each security policy can be defined with a combination of the following controls:

Access control list policies

An access control list (ACL) policy specifies the set of predefined actions that a set of users and groups can do on an object. For example, a specific set of groups or users can be granted read access to an object.

Protected object policies

A protected object policy (POP) specifies access conditions that are associated with an object. A POP affects all users and groups. For example, a time-of-day restriction can be placed on an object that excludes all users and groups from accessing that object during the specified time.

Authorization rules

An authorization rule specifies a complex condition that is evaluated to determine whether access is permitted. The data that determines whether access is permitted can be based on the context of the request, the current environment, or other external factors. For example, it can deny a request to modify an object more than five times in an eight-hour period.

A security policy can be explicitly applied to an object or can be inherited by an object that is above it in the hierarchy. Apply an explicit security policy in the protected object space only at those points in the hierarchy where the security policy must change.

You can implement a security policy by strategically attaching ACL policies, POPs, and authorization rules to objects that require protection. The Security Access Manager authorization service decides whether to allow or deny access to objects based on several criteria. One criterion is the credentials of the user that is making the request. Other criteria include the specific permissions and conditions that are specified in the ACL policies, POPs, and authorization rules.

The authorization service uses the following algorithm to process the security policy that is attached to a protected object:

Check permissions in the ACL policy to determine whether the user can override the attached POP or authorization rule. See ACL policies for information about the evaluation process.

When there is an authorization rule attached and the user cannot override it, gather the Access Decision Information (ADI).

When there is a POP attached:

Check the Internet Protocol (IP) endpoint authentication method policy.

Check the time-of-day policy.

Check the audit-level policy and audit the access decision.

When an authorization rule is attached and the user cannot override the authorization rule, check the authorization rule policy.

When an external authorization service (EAS) operation or a POP trigger applies to this access decision, call the EAS.

If any of the ACL policy, POP, or authorization rule evaluations fail, then the access request is denied. The EAS can override this decision on its own if it is configured to do so.

Parent topic: Security Access Manager administration

ACL policiesACL policies The ACL policy defines who has access to and what operations can be performed on the object.unauthenticateduserany-otheruserACLpoliciesoperations on an objectACLpoliciesevaluatingauthenticated requests, evaluateany-otherauthenticated requestsrequestsauthenticatedunauthenticatedrequests, evaluateany-otherunauthenticated requestsrequestsunauthenticatedEach ACL policy has a unique name and can be applied to multiple objects within a domain.An ACL policy consists of one or more of the following entry descriptions: The names of users and groups whose access to the object is explicitly controlledThe specific operations that each user, group, or role can doThe specific operations that the special any-other and unauthenticated user categories can doUse of ACL policies with the authorization serviceSecurity Access Manager relies on ACL policies to specify the conditions for a particular user to do an operation on a protected object. When you attach an ACL policy to an object, entries in the ACL specify what operations are allowed on it. The entries in the ACL policies also specify who can do the operations.Web Portal Manager can group ACL policies based on:Use of policies in a particular part of the object space such as WebSEALUse across the entire object space such as Base or GenericSecurity Access Manager uses a default set of actions that cover a wide range of operations. Actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). Each permission is displayed by the pdadmin utility with a label that describes the operation it governs. A resource manager software typically contains one or more operations that are done on protected resources. Security Access Manager requires that resource managers make calls to the authorization service before the requested operation is allowed to progress. This call is made through the authorization application programming interface (authorization API) for both Security Access Manager services and other applications.The authorization service uses the information contained in the ACL entry to make a simple yes or no response to the following question: Does this user or group have the appropriate permission to do the requested operation on the requested object? For example, does the user have the view (r) permission to view an object?The authorization service has no knowledge about the operation that requires the read (r) permission. It merely notes the presence or absence of the r action bit in the ACL entry of the requesting user or group.The authorization service is independent of the requested operations. This independence is why you can extend the benefits of the authorization service to other applications.Evaluation of ACL policiesSecurity Access Manager follows specific steps to evaluate the permissions granted to a particular user by an ACL policy. Understanding how Security Access Manager evaluates ACL policies can help you determine how best to prevent unauthorized users from gaining access to resources.Evaluate authenticated requestsSecurity Access Manager evaluates an authenticated user request by matching attributes of the user that is requesting access with criteria defined in the ACL entries.Security Access Manager evaluates an authenticated user request in the following order: Match the user ID with the user ACL entries. The permissions granted are the permissions in the matching entry. Successful matchEvaluation stops here.Unsuccessful matchContinue to the next step.Determine the groups to which the user belongs and match group ID with the group ACL entries. If more than one group entry is matched, the resulting permissions are a logical or operation (most permissive) of the permissions granted by each matching entry. Successful matchEvaluation stops here.Unsuccessful matchContinue to the next step.Grant the permissions of the any-other entry, if it exists. Successful matchEvaluation stops here.Unsuccessful matchContinue to the next step.An implicit any-other entity exists when there is no any-other ACL entry. This implicit entry grants no permissions. Successful matchNo permissions granted. End of evaluation process.Evaluate unauthenticated requestsSecurity Access Manager evaluates an unauthenticated user by granting the permissions from the unauthenticated ACL entry.The unauthenticated entry is a mask (a bit-wise and operation) against the any-other entry when permissions are determined. A permission for unauthenticated is granted only if the permission also is defined in the any-other entry.Because unauthenticated depends on any-other, it makes little sense for an ACL entry to contain unauthenticated without any-other. If an ACL entry contains unauthenticated without any-other, the default response is to deny permissions to unauthenticated.Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

ACL policies

The ACL policy defines who has access to and what operations can be performed on the object.

Each ACL policy has a unique name and can be applied to multiple objects within a domain.

An ACL policy consists of one or more of the following entry descriptions:

The names of users and groups whose access to the object is explicitly controlled

The specific operations that each user, group, or role can do

The specific operations that the special any-other and unauthenticated user categories can do

Use of ACL policies with the authorization service

Security Access Manager relies on ACL policies to specify the conditions for a particular user to do an operation on a protected object. When you attach an ACL policy to an object, entries in the ACL specify what operations are allowed on it. The entries in the ACL policies also specify who can do the operations.

Web Portal Manager can group ACL policies based on:

Use of policies in a particular part of the object space such as WebSEAL

Use across the entire object space such as Base or Generic

Security Access Manager uses a default set of actions that cover a wide range of operations. Actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). Each permission is displayed by the pdadmin utility with a label that describes the operation it governs.

A resource manager software typically contains one or more operations that are done on protected resources. Security Access Manager requires that resource managers make calls to the authorization service before the requested operation is allowed to progress. This call is made through the authorization application programming interface (authorization API) for both Security Access Manager services and other applications.

The authorization service uses the information contained in the ACL entry to make a simple "yes" or "no" response to the following question:

Does this user or group have the appropriate permission to do the requested operation on the requested object? For example, does the user have the view (r) permission to view an object?

The authorization service has no knowledge about the operation that requires the read (r) permission. It merely notes the presence or absence of the r action bit in the ACL entry of the requesting user or group.

The authorization service is independent of the requested operations. This independence is why you can extend the benefits of the authorization service to other applications.

Evaluation of ACL policies

Security Access Manager follows specific steps to evaluate the permissions granted to a particular user by an ACL policy. Understanding how Security Access Manager evaluates ACL policies can help you determine how best to prevent unauthorized users from gaining access to resources.

Evaluate authenticated requests

Security Access Manager evaluates an authenticated user request by matching attributes of the user that is requesting access with criteria defined in the ACL entries.

Security Access Manager evaluates an authenticated user request in the following order:

Match the user ID with the user ACL entries. The permissions granted are the permissions in the matching entry.

Successful match

Evaluation stops here.

Unsuccessful match

Continue to the next step.

Determine the groups to which the user belongs and match group ID with the group ACL entries. If more than one group entry is matched, the resulting permissions are a logical "or" operation (most permissive) of the permissions granted by each matching entry.

Successful match

Evaluation stops here.

Unsuccessful match

Continue to the next step.

Grant the permissions of the any-other entry, if it exists.

Successful match

Evaluation stops here.

Unsuccessful match

Continue to the next step.

An implicit any-other entity exists when there is no any-other ACL entry. This implicit entry grants no permissions.

Successful match

No permissions granted. End of evaluation process.

Evaluate unauthenticated requests

Security Access Manager evaluates an unauthenticated user by granting the permissions from the unauthenticated ACL entry.

The unauthenticated entry is a mask (a bit-wise "and" operation) against the any-other entry when permissions are determined. A permission for unauthenticated is granted only if the permission also is defined in the any-other entry.

Because unauthenticated depends on any-other, it makes little sense for an ACL entry to contain unauthenticated without any-other. If an ACL entry contains unauthenticated without any-other, the default response is to deny permissions to unauthenticated.

Parent topic: Security Access Manager administration

Protected object policiesProtected object policiesA protected object policy (POP) specifies a security policy that applies to an object regardless of which user or which operation is done. A POP imposes access conditions on an object based on the time of the access. A POP also indicates whether the access request must be audited. POPpoliciespolicyPOPpolicyprotected object policy (POP)Each POP has a unique name and can be applied to multiple objects within a domain.You can apply the following conditions on an object:POP attributes, such as warning mode, audit level, and time-of-day. More details about these attributes are in Configure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.. Authentication strength POP (step-up). More details about this policy are in Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method..Quality of Protection POP. More details about this policy are in Set a Quality of Protection levelThe Quality of Protection POP attribute specifies what level of data protection is required when doing an operation on an object..Network-based authentication POP. More details about this policy are in Network-based authorization policyUse the network-based authorization policy to control access to objects based on the IP address of the user. .Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Protected object policies

A protected object policy (POP) specifies a security policy that applies to an object regardless of which user or which operation is done. A POP imposes access conditions on an object based on the time of the access. A POP also indicates whether the access request must be audited.

Each POP has a unique name and can be applied to multiple objects within a domain.

You can apply the following conditions on an object:

POP attributes, such as warning mode, audit level, and time-of-day.

More details about these attributes are in Configure POP attributes.

Authentication strength POP (step-up).

More details about this policy are in Step-up authentication.

Quality of Protection POP.

More details about this policy are in Set a Quality of Protection level.

Network-based authentication POP.

More details about this policy are in Network-based authorization policy.

Parent topic: Security Access Manager administration

Authorization rulesAuthorization rulesAn authorization rule policy specifies which security policy applies to an object based on various conditions, such as context and environment. authorizationrulespoliciesauthorizationrulesuse ofACLpoliciesauthorization rulesPOPauthorization rulesauthorizationruleswhen to useEach authorization rule policy has a unique name and can be applied to multiple objects within a domain.You define authorization rules in a way similar to definitions of ACL policies and POPs. You specify conditions that must be met before access to a protected object is permitted. You create an authorization rule with a number of conditions. These conditions are based on data supplied to the authorization engine in the user credential from several sources. The conditions can be based on data from the resource manager application and from the encompassing business environment. These conditions are evaluated as a Boolean expression to determine whether access to the object must be granted or denied.You can work with complex, structured data by using the language of an authorization rule. You can examine values in the rule data and make informed access decisions. You can define the data for an access decision statically within the system or during a business process. Authorization rules provide the flexibility of a policy defined by an external authorization service. Unlike an external authorization service, you do not have to build an external authorization service into a shared library plug-in to use the authorization rules.How authorization rules differACL policies use a predefined set of operations to control which users and groups have permission to do operations on a protected object. Rules decide whether to grant access based on the attributes of a user or object and the context and environment. For example, the ability of a user to read data associated with an object is either granted or denied by an ACL policy. POPs apply to all users and groups and control conditions that are specific to a particular protected object. For example, time-of-day access excludes all users and groups from accessing an object outside of the times set in the time-of-day policy.Unlike ACL policies, authorization rules determine whether to allow access based on the attributes of a person or object. The authorization rules also take into account the context and environment that surrounds the access decision. For example, you can use a rule to implement a time-of-day policy that depends on the user or group. You can use an authentication rule to extend the controls provided by the ACL policies to implement a more advanced policy. For example, you can develop a policy based on quotas.An ACL policy can grant a group permission to write to a resource. A rule can extend the policy. For example, a rule can evaluate whether a group exceeds a specified quota before it permits the group to write to a resource.When to use authorization rulesIn the authorization process, the entire security policy (ACL policies, POPs, and authorization rules) must permit access to the protected object before access is granted. Authorization rules provide the flexibility to extend an ACL policy or POP by tailoring the security policy to your needs.Authorization rules can extend a policy implemented by other Security Access Manager policy types. These rules are not merely extensions of the existing policy types. An authorization rule is a policy type that is robust enough to replace the ACL policy and POP. Using ACL policies and POPs generally provides better performance. Use an authorization rule to complement these policies instead of replacing them.Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Authorization rules

An authorization rule policy specifies which security policy applies to an object based on various conditions, such as context and environment.

Each authorization rule policy has a unique name and can be applied to multiple objects within a domain.

You define authorization rules in a way similar to definitions of ACL policies and POPs. You specify conditions that must be met before access to a protected object is permitted. You create an authorization rule with a number of conditions. These conditions are based on data supplied to the authorization engine in the user credential from several sources. The conditions can be based on data from the resource manager application and from the encompassing business environment. These conditions are evaluated as a Boolean expression to determine whether access to the object must be granted or denied.

You can work with complex, structured data by using the language of an authorization rule. You can examine values in the rule data and make informed access decisions. You can define the data for an access decision statically within the system or during a business process. Authorization rules provide the flexibility of a policy defined by an external authorization service. Unlike an external authorization service, you do not have to build an external authorization service into a shared library plug-in to use the authorization rules.

How authorization rules differ

ACL policies use a predefined set of operations to control which users and groups have permission to do operations on a protected object. Rules decide whether to grant access based on the attributes of a user or object and the context and environment.

For example, the ability of a user to read data associated with an object is either granted or denied by an ACL policy. POPs apply to all users and groups and control conditions that are specific to a particular protected object. For example, time-of-day access excludes all users and groups from accessing an object outside of the times set in the time-of-day policy.

Unlike ACL policies, authorization rules determine whether to allow access based on the attributes of a person or object. The authorization rules also take into account the context and environment that surrounds the access decision. For example, you can use a rule to implement a time-of-day policy that depends on the user or group. You can use an authentication rule to extend the controls provided by the ACL policies to implement a more advanced policy. For example, you can develop a policy based on quotas.

An ACL policy can grant a group permission to write to a resource. A rule can extend the policy. For example, a rule can evaluate whether a group exceeds a specified quota before it permits the group to write to a resource.

When to use authorization rules

In the authorization process, the entire security policy (ACL policies, POPs, and authorization rules) must permit access to the protected object before access is granted. Authorization rules provide the flexibility to extend an ACL policy or POP by tailoring the security policy to your needs.

Authorization rules can extend a policy implemented by other Security Access Manager policy types. These rules are not merely extensions of the existing policy types. An authorization rule is a policy type that is robust enough to replace the ACL policy and POP. Using ACL policies and POPs generally provides better performance. Use an authorization rule to complement these policies instead of replacing them.

Parent topic: Security Access Manager administration

Guidelines for a secure object spaceGuidelines for a secure object spaceTo configure a secure object space, use these guidelines.protectedobject space guidelinesguidelinessecure object spaceSet high-level security policy on container objects at the top of the object space. Set exceptions to this policy with explicit ACL policies, POPs, and authorization rules on objects that are lower in the hierarchy.Arrange your protected object space so that most objects are protected by inherited, rather than explicit, ACL policies, POPs, and authorization rules. Reduce the risk of an error that might compromise your network by simplifying the maintenance of your tree. An inherited security policy lowers maintenance because it reduces the number of ACL policies, POPs, and authorization rules that you must maintain.Position new objects in the tree where they inherit the appropriate permissions. Arrange your object tree into a set of subtrees, where each subtree is governed by a specific access policy. You determine the access policy for an entire subtree by setting explicit ACL policies, POPs, and authorization rules at the root of the subtree.Create a core set of ACL policies, POPs, and authorization rules, and reuse these policies wherever necessary. ACL policies, POPs, and authorization rule policies are a single-source definition. Any modification to the policy impacts all objects associated with the ACL policy, POP, or authorization rule.Control user access through the use of groups. It is possible for an ACL policy to consist of only group entries. Individual user entries are not required in the ACL policy when the users can be categorized into groups instead. Authorization rules can also be written to consider any group memberships of an individual rather than the individual specifically. This feature can reduce the complexity of the rule logic considerably. Access to an object by individual users can be efficiently controlled by adding users to or removing users from these groups.Security Access Manager administrationAdministering Security Access Manager includes tasks such as installing and configuring resource managers, defining users and groups, and implementing security policies.

Guidelines for a secure object space

To configure a secure object space, use these guidelines.

Set high-level security policy on container objects at the top of the object space. Set exceptions to this policy with explicit ACL policies, POPs, and authorization rules on objects that are lower in the hierarchy.

Arrange your protected object space so that most objects are protected by inherited, rather than explicit, ACL policies, POPs, and authorization rules.

Reduce the risk of an error that might compromise your network by simplifying the maintenance of your tree. An inherited security policy lowers maintenance because it reduces the number of ACL policies, POPs, and authorization rules that you must maintain.

Position new objects in the tree where they inherit the appropriate permissions.

Arrange your object tree into a set of subtrees, where each subtree is governed by a specific access policy. You determine the access policy for an entire subtree by setting explicit ACL policies, POPs, and authorization rules at the root of the subtree.

Create a core set of ACL policies, POPs, and authorization rules, and reuse these policies wherever necessary.

ACL policies, POPs, and authorization rule policies are a single-source definition. Any modification to the policy impacts all objects associated with the ACL policy, POP, or authorization rule.

Control user access through the use of groups.

It is possible for an ACL policy to consist of only group entries. Individual user entries are not required in the ACL policy when the users can be categorized into groups instead. Authorization rules can also be written to consider any group memberships of an individual rather than the individual specifically. This feature can reduce the complexity of the rule logic considerably.

Access to an object by individual users can be efficiently controlled by adding users to or removing users from these groups.

Parent topic: Security Access Manager administration

Default security policyDefault security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.securitypolicydefaultdefaultsecurity policyAccess Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Default administration users and groupsAt installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.Definition and application of security policySecurity administrators protect system resources by defining a security policy. A security policy consists of the access control list (ACL) policies, protected object policies (POPs), and authorization rules. You can apply these policies and rules to the object representations of the system resources to be protected in the object space. You can apply ACL policies, POPs, and authorization rules to the same object.Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.Default ACL policiesYou can add entries for users, groups, any-other (any-authenticated), and unauthenticated to provide a broader range of control. These entries can better meet the requirements of your protected object space./Management permissionsThe /Management region of the protected object space contains multiple container objects. Changing the mapping of HTTP request methodsYou can change the mapping of HTTP request methods to ACL permission bits by specifying values in the [http-method-perms] stanza of the Web Reverse Proxy configuration file.

Default security policy

Security Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.

Default administration users and groups
At installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.

Definition and application of security policy
Security administrators protect system resources by defining a security policy. A security policy consists of the access control list (ACL) policies, protected object policies (POPs), and authorization rules. You can apply these policies and rules to the object representations of the system resources to be protected in the object space. You can apply ACL policies, POPs, and authorization rules to the same object.

Sparse security policy model
To secure network resources in a protected object space, each object must be protected by security policy.

Default ACL policies
You can add entries for users, groups, any-other (any-authenticated), and unauthenticated to provide a broader range of control. These entries can better meet the requirements of your protected object space.

/Management permissions
The /Management region of the protected object space contains multiple container objects.

Changing the mapping of HTTP request methods
You can change the mapping of HTTP request methods to ACL permission bits by specifying values in the [http-method-perms] stanza of the Web Reverse Proxy configuration file.

Parent topic: Access Manager Platform and Supporting Components administration

Default administration users and groupsDefault administration users and groupsAt installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.delegated administrationusers and groupsadministrationusers and groupsThe following sections detail the specific roles assigned to each of these users and groups at installation time. The sections explain how to create administration users.Default security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.iv-admin groupThis group represents the administrator group. All members of this group are considered administrators of the domain by the default policy.sec_master userThe sec_master user is created when Security Access Manager is initially installed and configured. The default policy makes the sec_master user a member of the iv-admin group, permitting it to do all actions within Security Access Manager. ivmgrd-servers groupThe ivmgrd-servers group contains the policy servers and the policy proxy servers. By default, members of this group are authorized to delegate requests to other Security Access Manager servers on behalf of the requestor.Administration usersYou can create administration accounts with varying degrees of responsibility. Responsibility is delegated to administrators through strategically placed administration ACLs.

Default administration users and groups

At installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.

The following sections detail the specific roles assigned to each of these users and groups at installation time. The sections explain how to create administration users.

iv-admin group
This group represents the administrator group. All members of this group are considered administrators of the domain by the default policy.

sec_master user
The sec_master user is created when Security Access Manager is initially installed and configured. The default policy makes the sec_master user a member of the iv-admin group, permitting it to do all actions within Security Access Manager.

ivmgrd-servers group
The ivmgrd-servers group contains the policy servers and the policy proxy servers. By default, members of this group are authorized to delegate requests to other Security Access Manager servers on behalf of the requestor.

Administration users
You can create administration accounts with varying degrees of responsibility. Responsibility is delegated to administrators through strategically placed administration ACLs.

Parent topic: Default security policy

iv-admin groupiv-admin groupThis group represents the administrator group. All members of this group are considered administrators of the domain by the default policy.groupsiv-admin groupiv-admin grouppermissionsiv-admin groupYou can easily place users into an administration role by adding them to the iv-admin group. There is a danger in this procedure when a user becomes a member of this group with the default ACLs. The user immediately has full rights to do administration operations on any object in the protected object space.When the policy server is configured, the administrator (sec_master) user is created and added to the iv-admin group. It is the combination of group memberships that grants sec_master complete rights for all operations within the management domain but only within the default policy. The sec_master user does not have rights to new groups created outside of the default policy unless it is added as a user or a member of a group.Default administration users and groupsAt installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.

iv-admin group

This group represents the administrator group. All members of this group are considered administrators of the domain by the default policy.

You can easily place users into an administration role by adding them to the iv-admin group. There is a danger in this procedure when a user becomes a member of this group with the default ACLs. The user immediately has full rights to do administration operations on any object in the protected object space.

When the policy server is configured, the administrator (sec_master) user is created and added to the iv-admin group. It is the combination of group memberships that grants sec_master complete rights for all operations within the management domain but only within the default policy. The sec_master user does not have rights to new groups created outside of the default policy unless it is added as a user or a member of a group.

Parent topic: Default administration users and groups

sec_master usersec_master userThe sec_master user is created when Security Access Manager is initially installed and configured. The default policy makes the sec_master user a member of the iv-admin group, permitting it to do all actions within Security Access Manager. sec_masteruserpermissionssec_masteruserssec_masterThink of this account as the equivalent of the Linux or UNIX root account, or a member of the Microsoft Windows Administrator group.Default administration users and groupsAt installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.

sec_master user

The sec_master user is created when Security Access Manager is initially installed and configured. The default policy makes the sec_master user a member of the iv-admin group, permitting it to do all actions within Security Access Manager.

Think of this account as the equivalent of the Linux or UNIX root account, or a member of the Microsoft Windows Administrator group.

Parent topic: Default administration users and groups

ivmgrd-servers groupivmgrd-servers groupThe ivmgrd-servers group contains the policy servers and the policy proxy servers. By default, members of this group are authorized to delegate requests to other Security Access Manager servers on behalf of the requestor.ivmgrd-servers groupgroupsivmgrd-serversDefault administration users and groupsAt installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.

ivmgrd-servers group

The ivmgrd-servers group contains the policy servers and the policy proxy servers. By default, members of this group are authorized to delegate requests to other Security Access Manager servers on behalf of the requestor.

Parent topic: Default administration users and groups

Administration usersAdministration usersYou can create administration accounts with varying degrees of responsibility. Responsibility is delegated to administrators through strategically placed administration ACLs. ACLpoliciesadministratorpermissionsadministration usersadministrationusers, creatingadministratorsecuritypolicysecurity policyadministratoradministratorresource, protectedprotectedresource administratoradministratordeploymentdeployment, administratorThe following list illustrates possible administration roles: Security policy administratorSecurity policy administrators are responsible for defining and organizing security policy in a domain. The administrator needs to be able to create, modify, and delete security policy. To do these tasks, these administrators need the following permissions on the /Management/ACL, /Management/POP, and /Management/Rule resources: Traverse (T)Browse (b)View (v)Modify (m)Delete (d) These administrators need the following permissions to navigate their subtree of protected resources: Traverse (T)Browse (b)View (v) These administrators need the following permission to ability to attach and detach a security policy to the same subtree: Attach (a) These administrators must have the following permissions so as not to be affected by security policies that apply to all users for the same subtree. Bypass POP (B)Bypass rule (R)Protected resource administratorProtected resource administrators are responsible for adding and removing user access to one or more protected resources. These tasks include: Adding users to and removing users from groups that are defined in the security policyAdding permissions to and removing permissions from resources These administrators need the following permissions on the /Management/Groups protected resource or on the individual groups that are defined in the /Management/Groups subtree: Traverse (T)Browse (b)View (v)Add (A)Deployment administratorDeployment administrators are responsible for installation and configuration of the resource managers in the domain. These administrators need the following permissions on the /Management/Server protected resource: Traverse (T)Browse (b)View (v)Modify (m)Delete (d) These permissions give the ability to configure resource managers into and out of the domain and update their configuration. See Permissions attributeEach ACL entry contains a set of permissions (actions) that describes the specific operations that are permitted on the object by the user or group. Permissions are context-sensitive. .Default administration users and groupsAt installation, Security Access Manager provides several important administration groups. By default, these users and groups are given special permissions to control and manage all operations in a domain. The access control lists (ACLs) created during configuration define this default security policy.

Administration users

You can create administration accounts with varying degrees of responsibility. Responsibility is delegated to administrators through strategically placed administration ACLs.

The following list illustrates possible administration roles:

Security policy administrator

Security policy administrators are responsible for defining and organizing security policy in a domain. The administrator needs to be able to create, modify, and delete security policy. To do these tasks, these administrators need the following permissions on the /Management/ACL, /Management/POP, and /Management/Rule resources:

Traverse (T)

Browse (b)

View (v)

Modify (m)

Delete (d)

These administrators need the following permissions to navigate their subtree of protected resources:

Traverse (T)

Browse (b)

View (v)

These administrators need the following permission to ability to attach and detach a security policy to the same subtree:

Attach (a)

These administrators must have the following permissions so as not to be affected by security policies that apply to all users for the same subtree.

Bypass POP (B)

Bypass rule (R)

Protected resource administrator

Protected resource administrators are responsible for adding and removing user access to one or more protected resources. These tasks include:

Adding users to and removing users from groups that are defined in the security policy

Adding permissions to and removing permissions from resources

These administrators need the following permissions on the /Management/Groups protected resource or on the individual groups that are defined in the /Management/Groups subtree:

Traverse (T)

Browse (b)

View (v)

Add (A)

Deployment administrator

Deployment administrators are responsible for installation and configuration of the resource managers in the domain.

These administrators need the following permissions on the /Management/Server protected resource:

Traverse (T)

Browse (b)

View (v)

Modify (m)

Delete (d)

These permissions give the ability to configure resource managers into and out of the domain and update their configuration. See Permissions attribute.

Parent topic: Default administration users and groups

Definition and application of security policyDefinition and application of security policySecurity administrators protect system resources by defining a security policy. A security policy consists of the access control list (ACL) policies, protected object policies (POPs), and authorization rules. You can apply these policies and rules to the object representations of the system resources to be protected in the object space. You can apply ACL policies, POPs, and authorization rules to the same object.securitypolicydefiningThe authorization service makes authorization decisions based on the policies applied to these objects. When a requested operation on a protected object is permitted, the resource manager responsible for the resource implements this operation.One policy can dictate the protection parameters of many objects. Any change to an ACL policy, POP, or authorization rule affects all objects to which the policy is attached.Default security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.ACL policiesAn ACL policy is the set of controls (permissions) that specifies the necessary conditions to do certain operations on that resource. Protected object policiesACL policies provide the authorization service with information that results in a yes or no answer on a request to access a protected object and do some operation on that object.Authorization rulesAn authorization rule specifies the policy that applies to an object and that is based on various conditions, such as context and environment. Each authorization rule has a unique name and can be applied to multiple objects in a domain.

Definition and application of security policy

Security administrators protect system resources by defining a security policy. A security policy consists of the access control list (ACL) policies, protected object policies (POPs), and authorization rules. You can apply these policies and rules to the object representations of the system resources to be protected in the object space. You can apply ACL policies, POPs, and authorization rules to the same object.

The authorization service makes authorization decisions based on the policies applied to these objects. When a requested operation on a protected object is permitted, the resource manager responsible for the resource implements this operation.

One policy can dictate the protection parameters of many objects. Any change to an ACL policy, POP, or authorization rule affects all objects to which the policy is attached.

ACL policies
An ACL policy is the set of controls (permissions) that specifies the necessary conditions to do certain operations on that resource.

Protected object policies
ACL policies provide the authorization service with information that results in a yes or no answer on a request to access a protected object and do some operation on that object.

Authorization rules
An authorization rule specifies the policy that applies to an object and that is based on various conditions, such as context and environment. Each authorization rule has a unique name and can be applied to multiple objects in a domain.

Parent topic: Default security policy

ACL policiesACL policiesAn ACL policy is the set of controls (permissions) that specifies the necessary conditions to do certain operations on that resource. ACLpoliciespermissionsACLpoliciesaccesscontrol listsACL policies are important components of the security policy that is established for the domain. ACL policies, like all policies, are used to stamp the set of security standards for an organization on the resources that are represented in their protected object spaces.An ACL policy provides the following controls: What operations can be done on an object or resourceWho can do an operationAn ACL policy is made up of one or more entries that include user and group designations and their specific permissions.ACL policyACL policyDefinition and application of security policySecurity administrators protect system resources by defining a security policy. A security policy consists of the access control list (ACL) policies, protected object policies (POPs), and authorization rules. You can apply these policies and rules to the object representations of the system resources to be protected in the object space. You can apply ACL policies, POPs, and authorization rules to the same object.

ACL policies

An ACL policy is the set of controls (permissions) that specifies the necessary conditions to do certain operations on that resource.

ACL policies are important components of the security policy that is established for the domain. ACL policies, like all policies, are used to stamp the set of security standards for an organization on the resources that are represented in their protected object spaces.

An ACL policy provides the following controls:

What operations can be done on an object or resource

Who can do an operation

An ACL policy is made up of one or more entries that include user and group designations and their specific permissions.

Figure 80. ACL policy

Parent topic: Definition and application of security policy

Protected object policiesProtected object policiesACL policies provide the authorization service with information that results in a yes or no answer on a request to access a protected object and do some operation on that object.POPattributesprotected objectpolicyattributesprotected objectpolicyenforcementIn contrast to ACL policies, protected object policies (POPs) contain additional conditions on the request. The conditions are passed back to Security Access Manager and the resource manager. These conditions are passed along with the yes ACL policy decision from the authorization server. It is the responsibility of Security Access Manager and the resource manager to enforce the POP conditions.The following table lists the available attributes for a POP that are provided by Security Access Manager. POP attributes that are enforced by Security Access ManagerPOP attributeDescriptionNameName of the policy. This attribute relates to the pop-name variable in the pop command documentation.DescriptionDescriptive text for the policy. This attribute appears in the pop show command.Warning modeProvides administrators a means to test ACLs, POPs, and authorization rules. Warning mode provides a way to test security policy before they are made active.Audit levelSpecifies the type of auditing: all, none, successful access, denied access, or errors. Audit level informs the authorizations service that extra services are required when permitting access to the object.Time-of-day accessDay and time restrictions for successful access to the protected object. Time-of-day places restrictions on the access to the object.IP endpoint authorization method policySpecifies authorization requirements for access from members of external networks. IP endpoint authorization method policy places restrictions on the access to the object.EAS trigger attributes Specifies an External Authorization Service (EAS) plug-in that is started to make an authorization decision with the externalized policy logic of the customer.Quality of ProtectionSpecifies degree of data protection: none, integrity, or privacy. Quality of Protection informs the authorizations service that extra services are required when permitting access to the object.Although Security Access Manager provides these POP attributes, it enforces only the following attributes: NameDescriptionWarning modeAudit levelTime-of-day accessEach resource manager or plug-in can optionally enforce one or more of the following attributes: IP endpoint authorization method policyEAS trigger attributesQuality of ProtectionThe concept of inherited, or sparse ACLs as described in Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy. also applies to POPs.Definition and application of security policySecurity administrators protect system resources by defining a security policy. A security policy consists of the access control list (ACL) policies, protected object policies (POPs), and authorization rules. You can apply these policies and rules to the object representations of the system resources to be protected in the object space. You can apply ACL policies, POPs, and authorization rules to the same object.

Protected object policies

ACL policies provide the authorization service with information that results in a yes or no answer on a request to access a protected object and do some operation on that object.

In contrast to ACL policies, protected object policies (POPs) contain additional conditions on the request. The conditions are passed back to Security Access Manager and the resource manager. These conditions are passed along with the yes ACL policy decision from the authorization server. It is the responsibility of Security Access Manager and the resource manager to enforce the POP conditions.

The following table lists the available attributes for a POP that are provided by Security Access Manager.

Table 154. POP attributes that are enforced by Security Access Manager

POP attribute | Description
Name | Name of the policy. This attribute relates to the pop-name variable in the pop command documentation.
Description | Descriptive text for the policy. This attribute appears in the pop show command.
Warning mode | Provides administrators a means to test ACLs, POPs, and authorization rules. Warning mode provides a way to test security policy before they are made active.
Audit level | Specifies the type of auditing: all, none, successful access, denied access, or errors. Audit level informs the authorizations service that extra services are required when permitting access to the object.
Time-of-day access | Day and time restrictions for successful access to the protected object. Time-of-day places restrictions on the access to the object.
IP endpoint authorization method policy | Specifies authorization requirements for access from members of external networks. IP endpoint authorization method policy places restrictions on the access to the object.
EAS trigger attributes | Specifies an External Authorization Service (EAS) plug-in that is started to make an authorization decision with the externalized policy logic of the customer.
Quality of Protection | Specifies degree of data protection: none, integrity, or privacy. Quality of Protection informs the authorizations service that extra services are required when permitting access to the object.

Although Security Access Manager provides these POP attributes, it enforces only the following attributes:

Name

Description

Warning mode

Audit level

Time-of-day access

Each resource manager or plug-in can optionally enforce one or more of the following attributes:

IP endpoint authorization method policy

EAS trigger attributes

Quality of Protection

The concept of inherited, or sparse ACLs as described in Sparse security policy model also applies to POPs.

Parent topic: Definition and application of security policy

Authorization rulesAuthorization rulesAn authorization rule specifies the policy that applies to an object and that is based on various conditions, such as context and environment. Each authorization rule has a unique name and can be applied to multiple objects in a domain.policyauthorization rulesLike ACL policies and POPs, authorization rules are defined to specify conditions that must be met before access to a protected object is permitted. An authorization rule is created with a number of Boolean conditions. The conditions are based on data that is supplied to the authorization service in the user credential. Data might also be supplied from the resource manager or from the encompassing business environment. The language of an authorization rule allows customers to work with complex, structured data, by examining the values in that data, and making informed access decisions. This information can be defined statically in the system or defined during a business process. Authorization rules can be used to implement extensible attribute-based authorization policy with attributes in the business environment or attributes from trusted external sources.The authorization rule is stored as a text rule in a rule policy object. The rule is attached to a protected object in the same way and with similar constraints as ACL policies and POPs.Definition and application of security policySecurity administrators protect system resources by defining a security policy. A security policy consists of the access control list (ACL) policies, protected object policies (POPs), and authorization rules. You can apply these policies and rules to the object representations of the system resources to be protected in the object space. You can apply ACL policies, POPs, and authorization rules to the same object.

Authorization rules

An authorization rule specifies the policy that applies to an object and that is based on various conditions, such as context and environment. Each authorization rule has a unique name and can be applied to multiple objects in a domain.

Like ACL policies and POPs, authorization rules are defined to specify conditions that must be met before access to a protected object is permitted. An authorization rule is created with a number of Boolean conditions. The conditions are based on data that is supplied to the authorization service in the user credential. Data might also be supplied from the resource manager or from the encompassing business environment. The language of an authorization rule allows customers to work with complex, structured data, by examining the values in that data, and making informed access decisions. This information can be defined statically in the system or defined during a business process. Authorization rules can be used to implement extensible attribute-based authorization policy with attributes in the business environment or attributes from trusted external sources.

The authorization rule is stored as a text rule in a rule policy object. The rule is attached to a protected object in the same way and with similar constraints as ACL policies and POPs.

Parent topic: Definition and application of security policy

Sparse security policy modelSparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.sparse ACL modelexplicitACLYou can assign security policy to an object in one of following ways: Attach an explicit security policy on the object.Allow the object to inherit its security policy from a preceding container object in the hierarchy.Adopting an inherited security scheme can greatly reduce the administration tasks for a domain. This section describes the concepts of inherited, or sparse security policies.Default security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.Security policy inheritanceSecurity policy inheritance simplifies the task of setting and maintaining access controls on a large protected object space.default-root ACL policyDuring the installation and initial configuration of Security Access Manager, the ACL policy for the entire object space is created and explicitly set.Control permissionThe control (c) permission gives you ownership of an ACL policy. As owner, you can modify entries in the ACL policy. Being able to modify entries in the ACL policy means that you can create entries, delete entries, grant permissions, and take away permissions.Traverse permissionThe traverse permission (T) specifies that a user or group that is identified in the ACL entry has permission to pass through this container object to gain access to a protected resource.Resolution of an access requestInheritance begins at the root of the protected object space. Inheritance impacts all objects in the object space until it reaches an object with an explicit ACL policy. At this point, a new chain of inheritance begins.Application of ACL policies to different object typesYou can set permissions for various operations in an ACL policy. Only a subset of these possible operations might be relevant for a specific object to which the ACL policy is attached.ACL policy inheritance exampleThis example illustrates the impact of a mixture of inherited and explicit ACL policies in the fictional ACME corporate object space.

Sparse security policy model

To secure network resources in a protected object space, each object must be protected by security policy.

You can assign security policy to an object in one of following ways:

Attach an explicit security policy on the object.

Allow the object to inherit its security policy from a preceding container object in the hierarchy.

Adopting an inherited security scheme can greatly reduce the administration tasks for a domain. This section describes the concepts of inherited, or sparse security policies.

Security policy inheritance
Security policy inheritance simplifies the task of setting and maintaining access controls on a large protected object space.

default-root ACL policy
During the installation and initial configuration of Security Access Manager, the ACL policy for the entire object space is created and explicitly set.

Control permission
The control (c) permission gives you ownership of an ACL policy. As owner, you can modify entries in the ACL policy. Being able to modify entries in the ACL policy means that you can create entries, delete entries, grant permissions, and take away permissions.

Traverse permission
The traverse permission (T) specifies that a user or group that is identified in the ACL entry has permission to pass through this container object to gain access to a protected resource.

Resolution of an access request
Inheritance begins at the root of the protected object space. Inheritance impacts all objects in the object space until it reaches an object with an explicit ACL policy. At this point, a new chain of inheritance begins.

Application of ACL policies to different object types
You can set permissions for various operations in an ACL policy. Only a subset of these possible operations might be relevant for a specific object to which the ACL policy is attached.

ACL policy inheritance example
This example illustrates the impact of a mixture of inherited and explicit ACL policies in the fictional ACME corporate object space.

Parent topic: Default security policy

Security policy inheritanceSecurity policy inheritanceSecurity policy inheritance simplifies the task of setting and maintaining access controls on a large protected object space.inheritedACLACLexplicit versus inheritedThe power of security policy inheritance is based on the following principle:Any object without an explicitly attached security policy inherits the policy of its nearest container object with an explicitly set security policy. The inheritance chain is broken when an object has an explicitly attached security policy.In a typical object space, you need to attach only a few security policies at key locations to secure the entire object space. Therefore, it is called a sparse security policy model.A typical object space begins with a single explicit security policy attached to the root container object. The root ACL must always exist and can never be removed. Normally, the root ACL is an ACL with little restriction. All objects in the object space inherit this ACL.When a region or subtree in the object space requires different access control restrictions, you attach an explicit security policy at the root of that subtree. This attachment interrupts the flow of inherited security policies from the primary object space root to that subtree. A new chain of inheritance begins from this newly created explicit security policy.Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.

Security policy inheritance

Security policy inheritance simplifies the task of setting and maintaining access controls on a large protected object space.

The power of security policy inheritance is based on the following principle:

Any object without an explicitly attached security policy inherits the policy of its nearest container object with an explicitly set security policy. The inheritance chain is broken when an object has an explicitly attached security policy.

In a typical object space, you need to attach only a few security policies at key locations to secure the entire object space. Therefore, it is called a sparse security policy model.

A typical object space begins with a single explicit security policy attached to the root container object. The root ACL must always exist and can never be removed. Normally, the root ACL is an ACL with little restriction. All objects in the object space inherit this ACL.

When a region or subtree in the object space requires different access control restrictions, you attach an explicit security policy at the root of that subtree. This attachment interrupts the flow of inherited security policies from the primary object space root to that subtree. A new chain of inheritance begins from this newly created explicit security policy.

Parent topic: Sparse security policy model

default-root ACL policydefault-root ACL policyDuring the installation and initial configuration of Security Access Manager, the ACL policy for the entire object space is created and explicitly set.defaultroot ACLroot ACLdefaultrootusers and permissionsrootACLpolicy replacement by administrator This ACL policy is the default-root ACL policy and includes the following users and permissions: group iv-admin TcmdbvaBR any-other T unauthenticated TSecurity Access Manager checks inheritance beginning with the root of the protected object space. If you do not explicitly set an ACL policy on any other object in the tree, the entire tree inherits this root ACL policy.There is always an explicit ACL policy set at the root of the protected object space. An administrator can replace this ACL policy with another ACL policy that contains different entries and permission settings. However, the administrator cannot completely remove the root ACL policy. See Permissions attributeEach ACL entry contains a set of permissions (actions) that describes the specific operations that are permitted on the object by the user or group. Permissions are context-sensitive. .Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.

default-root ACL policy

During the installation and initial configuration of Security Access Manager, the ACL policy for the entire object space is created and explicitly set.

This ACL policy is the default-root ACL policy and includes the following users and permissions:

group iv-admin               TcmdbvaBR
any-other                    T
unauthenticated              T

Security Access Manager checks inheritance beginning with the root of the protected object space. If you do not explicitly set an ACL policy on any other object in the tree, the entire tree inherits this root ACL policy.

There is always an explicit ACL policy set at the root of the protected object space. An administrator can replace this ACL policy with another ACL policy that contains different entries and permission settings. However, the administrator cannot completely remove the root ACL policy. See Permissions attribute.

Parent topic: Sparse security policy model

Control permissionControl permissionThe control (c) permission gives you ownership of an ACL policy. As owner, you can modify entries in the ACL policy. Being able to modify entries in the ACL policy means that you can create entries, delete entries, grant permissions, and take away permissions.control permissionACLcontrol permissionpermissionscontrolThe administrator who wants to delete a permission from an ACL policy must have an entry in that ACL policy. The administrator must also have the control permission set in that entry.With control permission, you can grant administration powers to another user, such as the ability to attach or detach that ACL policy to objects. You must use the control permission with great care because of its powerful ownership properties.Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.

Control permission

The control (c) permission gives you ownership of an ACL policy. As owner, you can modify entries in the ACL policy. Being able to modify entries in the ACL policy means that you can create entries, delete entries, grant permissions, and take away permissions.

The administrator who wants to delete a permission from an ACL policy must have an entry in that ACL policy. The administrator must also have the control permission set in that entry.

With control permission, you can grant administration powers to another user, such as the ability to attach or detach that ACL policy to objects. You must use the control permission with great care because of its powerful ownership properties.

Parent topic: Sparse security policy model

Traverse permissionTraverse permissionThe traverse permission (T) specifies that a user or group that is identified in the ACL entry has permission to pass through this container object to gain access to a protected resource.traverse permissionpermissionstraverse (T)Security Access Manager access control depends on the following conditions: The permission that controls the requested object must contain appropriate access permissions for the requesting user.The requested object must be accessible to the requesting user. Accessibility to protected objects is controlled by the traverse (T) permission.The traverse permission is applied only to container objects in the protected object space. If there are no permissions defined for a user, that user cannot even traverse the root container object. This user cannot gain access at all to the protected object space, regardless of any permissions that might be granted lower in the tree.A protected object is accessible if the requester possesses the traverse permission on each ACL attached to container objects above the requested resource on the path towards root and including root.Figure 1 illustrates how the traverse permission works. Within the fictional ACME Corporation, there is an Engineering container object (directory), which contains a TechPubs directory. Kate (user kate) is a member of the Sales department and requires traversing to the Engineering/TechPubs/ directory tree to review a release note file (release_note). The administrator provides traverse for any-authenticated at the root. The administrator provides traverse permission for group sales on the Engineering directory. The TechPubs directory inherits the ACL from the Engineering directory. Although Kate has no other permissions in these two directories, she can pass (traverse) through these directories to access the required file. Because this file has read permission for Kate, she can view the file. Traverse permissionTraverse permissionYou can easily restrict access to the hierarchy below a specified container object without resetting individual permissions on these objects. Delete the traverse permission from the appropriate ACL policy. Deleting traverse permission on a directory object protects all objects lower in the hierarchy, even if those objects have other less restrictive ACL policies.For example, sales group does not have the traverse permission on the Engineering directory. User kate cannot access the release_note file even though the user has read permission for that file.Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.

Traverse permission

The traverse permission (T) specifies that a user or group that is identified in the ACL entry has permission to pass through this container object to gain access to a protected resource.

Security Access Manager access control depends on the following conditions:

The permission that controls the requested object must contain appropriate access permissions for the requesting user.

The requested object must be accessible to the requesting user. Accessibility to protected objects is controlled by the traverse (T) permission.

The traverse permission is applied only to container objects in the protected object space.

If there are no permissions defined for a user, that user cannot even traverse the root container object. This user cannot gain access at all to the protected object space, regardless of any permissions that might be granted lower in the tree.

A protected object is accessible if the requester possesses the traverse permission on each ACL attached to container objects above the requested resource on the path towards root and including root.

Figure 81. illustrates how the traverse permission works. Within the fictional ACME Corporation, there is an Engineering container object (directory), which contains a TechPubs directory. Kate (user kate) is a member of the Sales department and requires traversing to the Engineering/TechPubs/ directory tree to review a release note file (release_note). The administrator provides traverse for any-authenticated at the root. The administrator provides traverse permission for group sales on the Engineering directory. The TechPubs directory inherits the ACL from the Engineering directory. Although Kate has no other permissions in these two directories, she can pass (traverse) through these directories to access the required file. Because this file has read permission for Kate, she can view the file.

Figure 81. Traverse permission

You can easily restrict access to the hierarchy below a specified container object without resetting individual permissions on these objects. Delete the traverse permission from the appropriate ACL policy. Deleting traverse permission on a directory object protects all objects lower in the hierarchy, even if those objects have other less restrictive ACL policies.

For example, sales group does not have the traverse permission on the Engineering directory. User kate cannot access the release_note file even though the user has read permission for that file.

Parent topic: Sparse security policy model

Resolution of an access requestResolution of an access requestInheritance begins at the root of the protected object space. Inheritance impacts all objects in the object space until it reaches an object with an explicit ACL policy. At this point, a new chain of inheritance begins.ACLrequest, resolvingObjects below an explicitly set ACL policy inherit the new ACL policy. If you delete an explicit ACL policy, permission for all objects reverts to the nearest container object with an explicitly set ACL policy.When a user tries to access a protected object such as a document, Security Access Manager checks whether that user has the permissions to access the object. Security Access Manager checks each object along the object hierarchy for the inherited or explicitly set permissions. A user is denied access to an object if any container object in the hierarchy above the protected object does not include the traverse permission for that user. Access is denied if the target object does not contain sufficient permissions to do the requested operation.To succeed an access check, the requester must have both of the following permissions: Permission to traverse the path to the requested objectAppropriate permissions on the requested objectFor example, to determine whether a user can read the report.html resource in the /acme/engineering/project_Y/current/ object, Security Access Manager does the following checks: Whether traverse permission is set on the root (/).Whether traverse permission is set on the acme, engineering, project_Y, and current directories.Whether read permission is set on the report.html file.If any of these checks fail, the user is denied access.Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.

Resolution of an access request

Inheritance begins at the root of the protected object space. Inheritance impacts all objects in the object space until it reaches an object with an explicit ACL policy. At this point, a new chain of inheritance begins.

Objects below an explicitly set ACL policy inherit the new ACL policy. If you delete an explicit ACL policy, permission for all objects reverts to the nearest container object with an explicitly set ACL policy.

When a user tries to access a protected object such as a document, Security Access Manager checks whether that user has the permissions to access the object. Security Access Manager checks each object along the object hierarchy for the inherited or explicitly set permissions. A user is denied access to an object if any container object in the hierarchy above the protected object does not include the traverse permission for that user. Access is denied if the target object does not contain sufficient permissions to do the requested operation.

To succeed an access check, the requester must have both of the following permissions:

Permission to traverse the path to the requested object

Appropriate permissions on the requested object

For example, to determine whether a user can read the report.html resource in the /acme/engineering/project_Y/current/ object, Security Access Manager does the following checks:

Whether traverse permission is set on the root (/).

Whether traverse permission is set on the acme, engineering, project_Y, and current directories.

Whether read permission is set on the report.html file.

If any of these checks fail, the user is denied access.

Parent topic: Sparse security policy model

Application of ACL policies to different object typesApplication of ACL policies to different object typesYou can set permissions for various operations in an ACL policy. Only a subset of these possible operations might be relevant for a specific object to which the ACL policy is attached.ACLpoliciesobject types, differentACLobject types, policy applicationThe reason for this behavior is related to the following Security Access Manager features that are designed to make administration easier: ACL policiesACL inheritanceUse ACL policies to use the same set of permissions to multiple objects in the protected object space. The ACL policy contains enough permissions to meet the requirements of all objects to which the ACL applies. However, each individual object might be affected by only a few of these permissions.In an ACL inheritance model, any object might not have an explicitly attached ACL policy. The object inherits the policy definitions from the nearest attached ACL policy to an object above it in the hierarchy.In summary, an ACL policy describes the necessary permissions for all object types to which it can apply, and the object to which it is attached.Sparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.

Application of ACL policies to different object types

You can set permissions for various operations in an ACL policy. Only a subset of these possible operations might be relevant for a specific object to which the ACL policy is attached.

The reason for this behavior is related to the following Security Access Manager features that are designed to make administration easier:

ACL policies

ACL inheritance

Use ACL policies to use the same set of permissions to multiple objects in the protected object space. The ACL policy contains enough permissions to meet the requirements of all objects to which the ACL applies. However, each individual object might be affected by only a few of these permissions.

In an ACL inheritance model, any object might not have an explicitly attached ACL policy. The object inherits the policy definitions from the nearest attached ACL policy to an object above it in the hierarchy.

In summary, an ACL policy describes the necessary permissions for all object types to which it can apply, and the object to which it is attached.

Parent topic: Sparse security policy model

ACL policy inheritance exampleACL policy inheritance exampleThis example illustrates the impact of a mixture of inherited and explicit ACL policies in the fictional ACME corporate object space.inheritedACLACLpoliciesinheritance exampleACLpoliciespolicy inheritance exampleA corporate object space has a general security policy set at the root object. Root is followed by the /WebSEAL container object and individually controlled departmental subtrees.In this example, the sales group is given ownership of its departmental subtree. The ACL policy on this subtree no longer acknowledges the unauthenticated or any-other entry types.The ytd.html file has an attached ACL policy that grants read permission to members of the sales-vp group (who are also members of the sales group). This ACL policy scheme does not need to be changed when users are added to or removed from the domain. Users can be added to or removed from the existing groups. ACL inheritance exampleACL inheritance exampleSparse security policy modelTo secure network resources in a protected object space, each object must be protected by security policy.

ACL policy inheritance example

This example illustrates the impact of a mixture of inherited and explicit ACL policies in the fictional ACME corporate object space.

A corporate object space has a general security policy set at the root object. Root is followed by the /WebSEAL container object and individually controlled departmental subtrees.

In this example, the sales group is given ownership of its departmental subtree. The ACL policy on this subtree no longer acknowledges the unauthenticated or any-other entry types.

The ytd.html file has an attached ACL policy that grants read permission to members of the sales-vp group (who are also members of the sales group).

Note: This ACL policy scheme does not need to be changed when users are added to or removed from the domain. Users can be added to or removed from the existing groups.

Figure 82. ACL inheritance example

Parent topic: Sparse security policy model

Default ACL policiesDefault ACL policiesYou can add entries for users, groups, any-other (any-authenticated), and unauthenticated to provide a broader range of control. These entries can better meet the requirements of your protected object space.defaultadministration ACLadministration ACL defaultACLdefault policies, administrationACLpoliciesdefaultdefaultroot ACLrootACLdefaultACLpoliciesdefault-rootdefaultmanagement ACLmanagementACL (default)ACLpoliciesdefault managementdefaultreplica ACLreplicaACL (default)ACLpoliciesdefault replicadefaultconfig ACLconfigACL (default)ACLpoliciesdefault configdefault-config ACL policydefaultGSO ACLGSOACL (default)ACLpoliciesdefault GSOdefaultpolicy ACLpolicy ACLdefaultACLpoliciesdefault policydefaultdomain ACLdomain ACL (default)ACLpoliciesdefault-domainACL policiesdefault-domaindefaultproxy ACLproxyACL (default)ACLpoliciesdefault proxyUsers and groups with the control (c) permission own the ACL and have the power to modify the ACL entries.A detailed description of permissions can be found in Default permissions in the primary action groupSecurity Access Manager defines permissions with action bits. When you install Security Access Manager, the default primary action group is created. This action group contains 17 permissions. .The following default ACL policies are suggested starting points for securing management operations in a domain: default-root ACL policyThe ACL policy for the entire object space is the default-root ACL policy.This ACL policy includes the following users and permissions: group iv-admin TcmdbvaBR any-other T unauthenticated TThe default-root ACL policy is a basic policy that enables everyone to traverse the object space, but they cannot do any other actions. Typically, you would not need to change this setting.Use the default-root ACL policy to quickly deny access to the entire object space for an individual user or group. Consider the following entry in the default-root ACL policy: user john -----------------The user john has no permissions. This user cannot even traverse the root container object. The user cannot access the protected object space regardless of any permissions that are granted lower in the tree.default-management ACL policyThe default ACL policy of the /Management container object is the default-management ACL policy. At installation, this ACL policy is attached to the /Management container object in the object space. This ACL policy includes the following users and permissions: group iv-admin TcmdbsvaBtNWAR group ivmgrd-servers Ts any-other Tvdefault-replica ACL policyThe default ACL policy for the /Management/Replica container object is the default-replica ACL policy.This ACL policy includes the following users and permissions: group iv-admin TcbvaBR group ivmgrd-servers m group secmgrd-servers mdv group ivacld-servers mdvdefault-config ACL policyThe default ACL policy for the /Management/Config container object is the default-config ACL policy.This ACL policy includes the following users and permissions: group iv-admin TcmdbsvaBR any-other Tv unauthenticated Tvdefault-gso ACL policyThe default ACL policy for the /Management/GSO container object is the default-gso ACL policy. This ACL policy includes the following users and permissions: group iv-admin TcmdbvaBNR any-other Tv unauthenticated Tvdefault-policy ACL policyThe default ACL policy for the /Management/Policy container object is the default-policy ACL policy. This ACL policy includes the following users and permissions: group iv-admin TcmdbvaBNR any-other Tv unauthenticated Tvdefault-domain ACL policyThe default ACL policy for the /Management/Domain container object is the default-domain ACL policy. This ACL policy includes the following users and permissions: group iv-admin TcmdbvaBNR group ivmgrd-servers vdefault-proxy ACL policyThe default ACL policy for the /Management/Proxy container object is the default-proxy ACL policy. This ACL policy includes the following users and permissions: group iv-admin Tcbv group ivmgrd-servers TgDefault security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.

Default ACL policies

You can add entries for users, groups, any-other (any-authenticated), and unauthenticated to provide a broader range of control. These entries can better meet the requirements of your protected object space.

Users and groups with the control (c) permission own the ACL and have the power to modify the ACL entries.

A detailed description of permissions can be found in Default permissions in the primary action group.

The following default ACL policies are suggested starting points for securing management operations in a domain:

default-root ACL policy

The ACL policy for the entire object space is the default-root ACL policy.

This ACL policy includes the following users and permissions:

group iv-admin               TcmdbvaBR
any-other                    T
unauthenticated              T

The default-root ACL policy is a basic policy that enables everyone to traverse the object space, but they cannot do any other actions. Typically, you would not need to change this setting.

Use the default-root ACL policy to quickly deny access to the entire object space for an individual user or group. Consider the following entry in the default-root ACL policy:

user john                    -----------------

The user john has no permissions. This user cannot even traverse the root container object. The user cannot access the protected object space regardless of any permissions that are granted lower in the tree.

default-management ACL policy

The default ACL policy of the /Management container object is the default-management ACL policy.

At installation, this ACL policy is attached to the /Management container object in the object space. This ACL policy includes the following users and permissions:

group iv-admin               TcmdbsvaBtNWAR
group ivmgrd-servers         Ts
any-other                    Tv

default-replica ACL policy

The default ACL policy for the /Management/Replica container object is the default-replica ACL policy.

This ACL policy includes the following users and permissions:

group iv-admin               TcbvaBR
group ivmgrd-servers         m
group secmgrd-servers        mdv
group ivacld-servers         mdv

default-config ACL policy

The default ACL policy for the /Management/Config container object is the default-config ACL policy.

This ACL policy includes the following users and permissions:

group iv-admin               TcmdbsvaBR
any-other                    Tv
unauthenticated              Tv

default-gso ACL policy

The default ACL policy for the /Management/GSO container object is the default-gso ACL policy.

This ACL policy includes the following users and permissions:

group iv-admin               TcmdbvaBNR
any-other                    Tv
unauthenticated              Tv

default-policy ACL policy

The default ACL policy for the /Management/Policy container object is the default-policy ACL policy.

This ACL policy includes the following users and permissions:

group iv-admin               TcmdbvaBNR
any-other                    Tv
unauthenticated              Tv

default-domain ACL policy

The default ACL policy for the /Management/Domain container object is the default-domain ACL policy.

This ACL policy includes the following users and permissions:

group iv-admin        TcmdbvaBNR
group ivmgrd-servers  v

default-proxy ACL policy

The default ACL policy for the /Management/Proxy container object is the default-proxy ACL policy.

This ACL policy includes the following users and permissions:

group iv-admin        Tcbv
group ivmgrd-servers  Tg

Parent topic: Default security policy

/Management permissions/Management permissionsThe /Management region of the protected object space contains multiple container objects. ACLmanagementpermissionsmanagementregion permissionsACLpermissions, managingThe following security considerations apply for the /Management region of the protected object space: The /Management object begins the chain of permission inheritance for the entire /Management region of the object space.If you do not apply any other explicit permission, this object defines, through inheritance, the security ACL policy for the entire /Management object space.The traverse (T) permission is required for access to /Management.The /Management region contains the following container objects that each requires a specific set of permissions: Default security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy./Management/ACL permissionsUse this object to do high-level ACL management tasks that can affect the security policy for the domain. /Management/Action permissionsYou might need to use the /Management/Action permissions to manage custom actions and action groups. /Management/POP permissionsUse this object to manage protected object policies. /Management/Server permissionsAdministrators can do server tasks with the /Management/Server container object of the protected object space when the appropriate permissions are set./Management/Config permissionsUse the /Management/Config container object of the protected object space to do configuration tasks when the appropriate permissions are set./Management/Policy permissionsUse the /Management/Policy container object of the protected object space to authorize the policy get and policy set commands when the appropriate permissions are set./Management/Replica permissionsUse the /Management/Replica container object of the protected object space to control the replication of the master policy database./Management/Users permissionsUse this object to manage user accounts. /Management/Groups permissionsUse this object to manage groups and group membership. /Management/GSO permissionsUse the /Management/GSO container object of the protected object space to do Global Sign-On (GSO) tasks when the appropriate permissions are set./Management/Rule permissionsUse this object to manage authorization rule policies./Management/Domain permissionsUse the /Management/Domain container object of the protected object space to do domain tasks when the appropriate permissions are set./Management/Proxy permissionsAdministrators or resource managers can use the /Management/Proxy container object of the protected object space to do delegated management tasks when the appropriate permissions are set.

/Management permissions

The /Management region of the protected object space contains multiple container objects.

The following security considerations apply for the /Management region of the protected object space:

The /Management object begins the chain of permission inheritance for the entire /Management region of the object space.

If you do not apply any other explicit permission, this object defines, through inheritance, the security ACL policy for the entire /Management object space.

The traverse (T) permission is required for access to /Management.

The /Management region contains the following container objects that each requires a specific set of permissions:

/Management/ACL permissions
Use this object to do high-level ACL management tasks that can affect the security policy for the domain.

/Management/Action permissions
You might need to use the /Management/Action permissions to manage custom actions and action groups.

/Management/POP permissions
Use this object to manage protected object policies.

/Management/Server permissions
Administrators can do server tasks with the /Management/Server container object of the protected object space when the appropriate permissions are set.

/Management/Config permissions
Use the /Management/Config container object of the protected object space to do configuration tasks when the appropriate permissions are set.

/Management/Policy permissions
Use the /Management/Policy container object of the protected object space to authorize the policy get and policy set commands when the appropriate permissions are set.

/Management/Replica permissions
Use the /Management/Replica container object of the protected object space to control the replication of the master policy database.

/Management/Users permissions
Use this object to manage user accounts.

/Management/Groups permissions
Use this object to manage groups and group membership.

/Management/GSO permissions
Use the /Management/GSO container object of the protected object space to do Global Sign-On (GSO) tasks when the appropriate permissions are set.

/Management/Rule permissions
Use this object to manage authorization rule policies.

/Management/Domain permissions
Use the /Management/Domain container object of the protected object space to do domain tasks when the appropriate permissions are set.

/Management/Proxy permissions
Administrators or resource managers can use the /Management/Proxy container object of the protected object space to do delegated management tasks when the appropriate permissions are set.

Parent topic: Default security policy

/Management/ACL permissions/Management/ACL permissionsUse this object to do high-level ACL management tasks that can affect the security policy for the domain. Management/ACL permissionspermissions/Management/ACL permissionsACLpermissions, managingACLmanagementACL permissions/Management/ACL permissionsPermissionOperationd (delete)Delete an existing ACL policy. m (modify)Create an ACL policy. v (view)List and find view ACLs; show ACL details. This permission must be in an entry of an ACL attached to the /Management/ACL object. The acl find command shows the list of protected resources where this ACL is attached. You must have the view (v) permission on those protected resources before they can be shown.You must create ACL administrator entries in the effective ACL policy for the /Management/ACL object. The ACL entry of an administrator might contain any of the permissions listed in the table. These permissions give the administrator powers to create, view, and delete ACL policies.An ACL administrator cannot modify an existing ACL unless there is an entry in that ACL for the administrator that contains the control (c) permission. Only the owner of an ACL can modify its entries.The creator of a new ACL policy (m on /Management/ACL) becomes the first entry in that ACL with the TcmdbsvaBIR permissions set by default.For example, if sec_master is an administrator entry in the default-management ACL, with m permission, sec_master can create an ACL policy. User sec_master becomes the first entry in the new ACL, with TcmdbsvaBIR permissions. Ownership of the default-management ACL itself is given to the iv-admin group by default./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/ACL permissions

Use this object to do high-level ACL management tasks that can affect the security policy for the domain.

Table 155. /Management/ACL permissions

Permission | Operation
d (delete) | Delete an existing ACL policy.
m (modify) | Create an ACL policy.
v (view) | List and find view ACLs; show ACL details. This permission must be in an entry of an ACL attached to the /Management/ACL object.

The acl find command shows the list of protected resources where this ACL is attached. You must have the view (v) permission on those protected resources before they can be shown.

You must create ACL administrator entries in the effective ACL policy for the /Management/ACL object. The ACL entry of an administrator might contain any of the permissions listed in the table. These permissions give the administrator powers to create, view, and delete ACL policies.

An ACL administrator cannot modify an existing ACL unless there is an entry in that ACL for the administrator that contains the control (c) permission. Only the owner of an ACL can modify its entries.

The creator of a new ACL policy (m on /Management/ACL) becomes the first entry in that ACL with the TcmdbsvaBIR permissions set by default.

For example, if sec_master is an administrator entry in the default-management ACL, with m permission, sec_master can create an ACL policy. User sec_master becomes the first entry in the new ACL, with TcmdbsvaBIR permissions.

Ownership of the default-management ACL itself is given to the iv-admin group by default.

Parent topic: /Management permissions

/Management/Action permissions/Management/Action permissionsYou might need to use the /Management/Action permissions to manage custom actions and action groups. Management/Action permissionspermissions/Management/Action permissionsactionpermissionsmanagingaction/Management/Action permissionsAction tasks and associated permissions include: /Management/Action permissionsPermissionOperationd (delete)Delete an existing action or action group. m (modify)Create an action or action group. To view an action or action group, no special permissions are required.Resource managers can call the authorization service through the authorization API. To integrate a resource manager with the authorization service:Define the object space for the resource manager.Define the action groups and actions for the resource manager.Apply permissions on resources and objects that need protection.The administrator of a resource manager object space can use the pdadmin utility to define new permissions and actions. Resource managers generally define the actions and action groups that are applicable to the resources that they are protecting.The administrator must have the m and d permissions on the Management/Action object to create and delete these new permissions or actions./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Action permissions

You might need to use the /Management/Action permissions to manage custom actions and action groups.

Action tasks and associated permissions include:

Table 156. /Management/Action permissions

Permission | Operation
d (delete) | Delete an existing action or action group.
m (modify) | Create an action or action group.

To view an action or action group, no special permissions are required.

Resource managers can call the authorization service through the authorization API. To integrate a resource manager with the authorization service:

Define the object space for the resource manager.

Define the action groups and actions for the resource manager.

Apply permissions on resources and objects that need protection.

The administrator of a resource manager object space can use the pdadmin utility to define new permissions and actions. Resource managers generally define the actions and action groups that are applicable to the resources that they are protecting.

The administrator must have the m and d permissions on the Management/Action object to create and delete these new permissions or actions.

Parent topic: /Management permissions

/Management/POP permissions/Management/POP permissionsUse this object to manage protected object policies. Management/POP permissionspermissions/Management/POP permissionsPOPpermissions, managingPOPmanaging permissionsprotected objectpolicypermissionsAll permissions must appear in entries for ACLs on /Management/POP. Action tasks and associated permissions include: /Management/POP permissionsPermissionOperationd (delete)Delete a POP.m (modify)Create POPs and modify POP attributes.v (view)Find and list POPs and show POP details. B (bypass POP)Override the POP on an object.The pop find command shows the list of protected resources where this POP is attached. You must have the view (v) permission on those protected resources before they can be shown./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/POP permissions

Use this object to manage protected object policies.

All permissions must appear in entries for ACLs on /Management/POP. Action tasks and associated permissions include:

Table 157. /Management/POP permissions

Permission | Operation
d (delete) | Delete a POP.
m (modify) | Create POPs and modify POP attributes.
v (view) | Find and list POPs and show POP details.
B (bypass POP) | Override the POP on an object.

The pop find command shows the list of protected resources where this POP is attached. You must have the view (v) permission on those protected resources before they can be shown.

Parent topic: /Management permissions

/Management/Server permissions/Management/Server permissionsAdministrators can do server tasks with the /Management/Server container object of the protected object space when the appropriate permissions are set.serverpermissions, managingManagement/Server permissionspermissions/Management/Server permissionsServer management controls:Determine whether a user has permission to view configured resource managers.Initiate a replication of one or more resource managers.Enable runtime tracing features on behalf of resource managers.Resource managers become available in the list of resource managers after they are configured into the domain. Resource managers are removed when they are unconfigured.The viewable resource manager information allows other Security Access Manager servers, particularly the policy server, to locate and communicate with that resource manager. /Management/Server permissions PermissionOperations (server)Replicate the resource manager or the authorization database.v (view)List registered servers and display server properties.t (trace)Enable dynamic trace or statistics administration./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Server permissions

Administrators can do server tasks with the /Management/Server container object of the protected object space when the appropriate permissions are set.

Server management controls:

Determine whether a user has permission to view configured resource managers.

Initiate® a replication of one or more resource managers.

Enable runtime tracing features on behalf of resource managers.

Resource managers become available in the list of resource managers after they are configured into the domain. Resource managers are removed when they are unconfigured.

The viewable resource manager information allows other Security Access Manager servers, particularly the policy server, to locate and communicate with that resource manager.

Table 158. /Management/Server permissions

Permission | Operation
s (server) | Replicate the resource manager or the authorization database.
v (view) | List registered servers and display server properties.
t (trace) | Enable dynamic trace or statistics administration.

Parent topic: /Management permissions

/Management/Config permissions/Management/Config permissionsUse the /Management/Config container object of the protected object space to do configuration tasks when the appropriate permissions are set.Management/Config permissionspermissions/Management/Config permissionsconfigpermissions, managingconfiguration/Management/Config permissionsConfiguration management controls are used to determine whether a user has permission to configure, unconfigure, or update the configuration of a resource manager.A server definition is created for a particular resource manager or the authorization server as part of the configuration process. The definition for a server is deleted when the server is unconfigured.Server definitions contain information that allows other Security Access Manager servers, particularly the policy server, to locate and communicate with that resource manager. /Management/Config permissions PermissionOperationm (modify)Configure a resource manager into a domain or update the configuration of a resource manager.d (delete)Unconfigure a resource manager from a domain./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Config permissions

Use the /Management/Config container object of the protected object space to do configuration tasks when the appropriate permissions are set.

Configuration management controls are used to determine whether a user has permission to configure, unconfigure, or update the configuration of a resource manager.

A server definition is created for a particular resource manager or the authorization server as part of the configuration process. The definition for a server is deleted when the server is unconfigured.

Server definitions contain information that allows other Security Access Manager servers, particularly the policy server, to locate and communicate with that resource manager.

Table 159. /Management/Config permissions

Permission | Operation
m (modify) | Configure a resource manager into a domain or update the configuration of a resource manager.
d (delete) | Unconfigure a resource manager from a domain.

Parent topic: /Management permissions

/Management/Policy permissions/Management/Policy permissionsUse the /Management/Policy container object of the protected object space to authorize the policy get and policy set commands when the appropriate permissions are set.Management/Policy permissionspermissions/Management/Policy permissionspolicypermissions, managing /Management/Policy permissions PermissionOperationv (view)Required for policy get commands.m (modify)Required for policy set commands./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Policy permissions

Use the /Management/Policy container object of the protected object space to authorize the policy get and policy set commands when the appropriate permissions are set.

Table 160. /Management/Policy permissions

Permission | Operation
v (view) | Required for policy get commands.
m (modify) | Required for policy set commands.

Parent topic: /Management permissions

/Management/Replica permissions/Management/Replica permissionsUse the /Management/Replica container object of the protected object space to control the replication of the master policy database.Management/Replica permissionspermissions/Management/Replica permissionsreplicapermissions, managing High-level controls on this object affect the operation of the policy server and the resource managers in the domain.Replica management controls are used to determine which resource managers are allowed to download the master policy database to their local file system. /Management/Replica permissions PermissionOperationv (view)Read the master policy database.All Security Access Manager servers that maintain a local replica of the policy database must be granted view (v) permission on the /Management/Replica object. This group of servers includes all resource managers and the authorization servers. The replication process requires that these processes be allowed to view and access entries out of the master policy database.The Security Access Manager installation automatically grants read permission to any server that requires access to the master policy database. When a resource manager is configured into the domain, it is automatically added as a member to the ivacld-servers group. This group, by default, is given permission to download the master policy database./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Replica permissions

Use the /Management/Replica container object of the protected object space to control the replication of the master policy database.

High-level controls on this object affect the operation of the policy server and the resource managers in the domain.

Replica management controls are used to determine which resource managers are allowed to download the master policy database to their local file system.

Table 161. /Management/Replica permissions

Permission | Operation
v (view) | Read the master policy database.

All Security Access Manager servers that maintain a local replica of the policy database must be granted view (v) permission on the /Management/Replica object. This group of servers includes all resource managers and the authorization servers. The replication process requires that these processes be allowed to view and access entries out of the master policy database.

The Security Access Manager installation automatically grants read permission to any server that requires access to the master policy database. When a resource manager is configured into the domain, it is automatically added as a member to the ivacld-servers group. This group, by default, is given permission to download the master policy database.

Parent topic: /Management permissions

/Management/Users permissions/Management/Users permissionsUse this object to manage user accounts. Management/Users permissionspermissions/Management/Users permissionsuserspermissionsmanagingusersmanaging users permissionsAction tasks and associated permissions include: /Management/Users permissions PermissionOperationd (delete)Delete a user account.m (modify)Modify the details of a user account.N (create)Create a user and optionally assign that user to one or more groups. Import group data from the user registry. v (view)List user accounts and show details for a user account. W (password)Reset and validate a user password. The password (W) permission allows password resets. This permission is appropriate to give to help desk administrators so that they can assist users who forget their passwords. This permission allows an administrator to reset the password and then to use the user modify password-valid command to set a value of no. This action allows the user to log on and then forces the user to immediately apply a new password. Setting user modify password-valid to no for a user does not indicate whether the password is not valid due to the maximum password age policy, which is a global setting. The policy set max-password-age command sets the maximum time that must elapse before a password expires.The ability for an administrator to manage all user accounts is controlled by permissions on the /Management/Users object. For example, if an administrator has view (v) permission on the /Management/Users object, that administrator can view information about all users.To limit the scope of administrator control to a specific group, remove the administrator permissions from the /Management/Users object. Apply permissions to the /Management/Groups object that is associated with the group to be managed. For example, if an administrator is given view (v) permission on the /Management/Groups/Accounting object, that administrator can view only information about users in the Accounting group.If an administrator has view (v) permission to any group that the user is a member of, the administrator can view the information for that user. Adding the view (v) permission to the /Management/Groups object itself allows an administrator to view information about any user who is a member of any group.Access granted by the /Management/Users object overrides any access restrictions imposed by delegated administration policy ACLs under /Management/Groups/group_name. For information about delegated administration, see [delegated-admin] stanzaThe Security Access Manager configuration can require that the user is authorized to view each group that is returned in the group list. Or, the user can be authorized to return the list without authorizing first../Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Users permissions

Use this object to manage user accounts.

Action tasks and associated permissions include:

Table 162. /Management/Users permissions

Permission | Operation
d (delete) | Delete a user account.
m (modify) | Modify the details of a user account.
N (create) | Create a user and optionally assign that user to one or more groups. Import group data from the user registry.
v (view) | List user accounts and show details for a user account.
W (password) | Reset and validate a user password.

The password (W) permission allows password resets. This permission is appropriate to give to help desk administrators so that they can assist users who forget their passwords. This permission allows an administrator to reset the password and then to use the user modify password-valid command to set a value of no. This action allows the user to log on and then forces the user to immediately apply a new password. Setting user modify password-valid to no for a user does not indicate whether the password is not valid due to the maximum password age policy, which is a global setting. The policy set max-password-age command sets the maximum time that must elapse before a password expires.

The ability for an administrator to manage all user accounts is controlled by permissions on the /Management/Users object. For example, if an administrator has view (v) permission on the /Management/Users object, that administrator can view information about all users.

To limit the scope of administrator control to a specific group, remove the administrator permissions from the /Management/Users object. Apply permissions to the /Management/Groups object that is associated with the group to be managed. For example, if an administrator is given view (v) permission on the /Management/Groups/Accounting object, that administrator can view only information about users in the Accounting group.

If an administrator has view (v) permission to any group that the user is a member of, the administrator can view the information for that user. Adding the view (v) permission to the /Management/Groups object itself allows an administrator to view information about any user who is a member of any group.

Access granted by the /Management/Users object overrides any access restrictions imposed by delegated administration policy ACLs under /Management/Groups/group_name. For information about delegated administration, see [delegated-admin] stanza.

Parent topic: /Management permissions

/Management/Groups permissions/Management/Groups permissionsUse this object to manage groups and group membership. Management/Groups permissionspermissions/Management/Groups permissionsgroupspermissionsmanaginggroupsmanaging groups permissions/Management/Groups permissionsPermission Descriptiond (delete)Delete a group.m (modify)Modify group descriptions. Remove one or more user members of a group.N (create)Create a group. Import group data from the user registry.v (view)List groups and show group details.A (add)Add one or more users to a group.The add (A) permission is required on your entry in the ACL on a group so that you can add existing users to your group. Use the user create command, which requires the N permission, to create new users and optionally place them in one or more existing groups.The capability of adding existing users to your group is powerful because the owner of a group has control over all user members of the group. If you, as the owner of the group, also have the delete (d) permission, you can delete this user from the entire domain.The ability for an administrator to manage all groups is controlled by permissions on the /Management/Groups object. For example, if an administrator has delete (d) permission on the /Management/Groups object, that administrator can delete any group. To limit the scope of administrator control to a specific group, apply permissions to the object that is associated with the group. For example, if an administrator is given delete (d) permission on the /Management/Groups/Travel/Europe object, that administrator can delete any group within that object.Permissions on /Management/Groups objects affect the ability of an administrator to manage users who are part of those groups. Giving an administrator delete (d) permission on a group allows that administrator to delete a user who is a member of the group. If an administrator has view (v) permission on a group, that administrator can view information about the users that are part of those groups./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Groups permissions

Use this object to manage groups and group membership.

Table 163. /Management/Groups permissions

Permission | Description
d (delete) | Delete a group.
m (modify) | Modify group descriptions. Remove one or more user members of a group.
N (create) | Create a group. Import group data from the user registry.
v (view) | List groups and show group details.
A (add) | Add one or more users to a group.

The add (A) permission is required on your entry in the ACL on a group so that you can add existing users to your group. Use the user create command, which requires the N permission, to create new users and optionally place them in one or more existing groups.

The capability of adding existing users to your group is powerful because the owner of a group has control over all user members of the group. If you, as the owner of the group, also have the delete (d) permission, you can delete this user from the entire domain.

The ability for an administrator to manage all groups is controlled by permissions on the /Management/Groups object. For example, if an administrator has delete (d) permission on the /Management/Groups object, that administrator can delete any group.

To limit the scope of administrator control to a specific group, apply permissions to the object that is associated with the group. For example, if an administrator is given delete (d) permission on the /Management/Groups/Travel/Europe object, that administrator can delete any group within that object.

Permissions on /Management/Groups objects affect the ability of an administrator to manage users who are part of those groups. Giving an administrator delete (d) permission on a group allows that administrator to delete a user who is a member of the group. If an administrator has view (v) permission on a group, that administrator can view information about the users that are part of those groups.

Parent topic: /Management permissions

/Management/GSO permissions/Management/GSO permissionsUse the /Management/GSO container object of the protected object space to do Global Sign-On (GSO) tasks when the appropriate permissions are set.Management/GSO permissionspermissions/Management/GSO permissionsGSOpermissionsmanagingGSOmanaging GSO permissionsglobalsign-on/Management/GSO permissionsPermissionOperationN (create)Create a resource, resource group, or resource credential. Creating a resource, resource group, or resource credential also requires the m (modify) permission.d (delete)Delete a resource, resource group, or resource credential. Deleting a resource, resource group, or resource credential also requires the m (modify) permission.m (modify)Modify a resource group or resource credential.v (view)List or show resources, resource groups, and resource credentials./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/GSO permissions

Use the /Management/GSO container object of the protected object space to do Global Sign-On (GSO) tasks when the appropriate permissions are set.

Table 164. /Management/GSO permissions

Permission | Operation
N (create) | Create a resource, resource group, or resource credential. Creating a resource, resource group, or resource credential also requires the m (modify) permission.
d (delete) | Delete a resource, resource group, or resource credential. Deleting a resource, resource group, or resource credential also requires the m (modify) permission.
m (modify) | Modify a resource group or resource credential.
v (view) | List or show resources, resource groups, and resource credentials.

Parent topic: /Management permissions

/Management/Rule permissions/Management/Rule permissionsUse this object to manage authorization rule policies.Management/Rule permissionspermissions/Management/Rule permissionsrulepermissionsmanagingrulepermissionsauthorizationauthorizationrulesmanaging rule permissionsAll permissions must occur in entries for ACLs on /Management/Rule. /Management/Rule permissionsPermissionOperationR (bypass rule)Override the authorization rule policy on an object.d (delete)Delete an authorization rule.m (modify)Create authorization rules and modify authorization rule attributes.v (view)Find and list authorization rules and show authorization rule details.The authzrule find command shows the list of protected resources where this rule is attached. You must have the view (v) permission on those protected resources before they can be shown./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Rule permissions

Use this object to manage authorization rule policies.

All permissions must occur in entries for ACLs on /Management/Rule.

Table 165. /Management/Rule permissions

Permission | Operation
R (bypass rule) | Override the authorization rule policy on an object.
d (delete) | Delete an authorization rule.
m (modify) | Create authorization rules and modify authorization rule attributes.
v (view) | Find and list authorization rules and show authorization rule details.

The authzrule find command shows the list of protected resources where this rule is attached. You must have the view (v) permission on those protected resources before they can be shown.

Parent topic: /Management permissions

/Management/Domain permissions/Management/Domain permissionsUse the /Management/Domain container object of the protected object space to do domain tasks when the appropriate permissions are set.Management/Domain permissionspermissions/Management/Domain permissionsdomainpermissions, managingdomainsmanaging domain permissions /Management/Domain permissionsPermissionOperationm (modify)Modify or create a domain.v (view)List and show domains.d (delete)Delete a domain./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Domain permissions

Use the /Management/Domain container object of the protected object space to do domain tasks when the appropriate permissions are set.

Table 166. /Management/Domain permissions

Permission | Operation
m (modify) | Modify or create a domain.
v (view) | List and show domains.
d (delete) | Delete a domain.

Parent topic: /Management permissions

/Management/Proxy permissions/Management/Proxy permissionsAdministrators or resource managers can use the /Management/Proxy container object of the protected object space to do delegated management tasks when the appropriate permissions are set.Management/Proxy permissionspermissions/Management/Proxy permissionsproxypermissions, managing /Management/Proxy permissionsPermissionOperationg (delegate)Allows administrators and resource managers to act on the behalf of the specified credential./Management permissionsThe /Management region of the protected object space contains multiple container objects.

/Management/Proxy permissions

Administrators or resource managers can use the /Management/Proxy container object of the protected object space to do delegated management tasks when the appropriate permissions are set.

Table 167. /Management/Proxy permissions

Permission | Operation
g (delegate) | Allows administrators and resource managers to act on the behalf of the specified credential.

Parent topic: /Management permissions

Changing the mapping of HTTP request methodsYou can change the mapping of HTTP request methods to ACL permission bits by specifying values in the [http-method-perms] stanza of the Web Reverse Proxy configuration file.For example, to define that an HTTP method POST maps to the permission bits A and x, add the following entry to the [http-method-perms] stanza:POST = AxYou can also create custom permissions in custom action groups, for example, [my-action-group]t. See Custom permissions in custom action groupsThe default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group..Here is an example [http-method-perms] stanza:<default> = r GET = r HEAD = T PUT = m POST = Ax DELETE = d TRACE = [my-action-group]tThe <default> entry is always mandatory when you add any entries to the [http-method-perms] stanza.The [http-method-perms] stanza can be specified on a per-junction basis by creating a stanza in the form of [http-method-perms:junction]. The values in the global [http-method-perms] stanza apply to any junctions that do not have a junction-specific stanza. A junction-specific stanza [http-method-perms:junction] does not inherit values from a global stanza. For more information, see [http-method-perms] stanzaUse this stanza to define the permissions that are required to perform a request with a particular HTTP method..The [http-method-perms] stanza is empty when the Web Reverse Proxy instance is first configured. If the [http-method-perms] stanza is empty, the Web Reverse Proxy defaults to the following ACL bits:PUT => m DELETE => d All else (GET,POST .. ) => rConfiguration validation The configuration that is specified in the [http-method-perms] stanza is validated each time that a junction is created. The configuration is also validated when the Web Reverse Proxy instance is restarted. This mechanism ensures that the specified ACL bits correspond to actions already defined in the policy database. The validation process of the [http-method-perms] configuration might cause authorization audit events to be generated. Such audit events will appear as unauthenticated accesses to the Security Access Manager policy object/Permission-Configuration. If you want to suppress these audit events, attach a protected object policy (POP) with its audit-level attribute set to none to an object with the name /Permission-Configuration. This object is not created in the object space by default. The following pdadmin commands illustrate the creation of policy that will suppress the generation of these audit events: pdadmin> objectspace create /Permission-Configuration "Permission configuration validation" 0 pdadmin> pop create permission-configuration pdadmin> pop modify permission-configuration set audit-level none pdadmin> pop attach /Permission-Configuration permission-configurationDefault security policySecurity Access Manager establishes a default security policy to protect all objects in a domain. A set of administrative users and groups is established and granted a predefined set of permissions. This chapter describes the default security policy.

Changing the mapping of HTTP request methods

You can change the mapping of HTTP request methods to ACL permission bits by specifying values in the [http-method-perms] stanza of the Web Reverse Proxy configuration file.

For example, to define that an HTTP method POST maps to the permission bits A and x, add the following entry to the [http-method-perms] stanza:

POST = Ax

You can also create custom permissions in custom action groups, for example, [my-action-group]t. See Custom permissions in custom action groups.

Here is an example [http-method-perms] stanza:

<default> = r
GET = r
HEAD = T
PUT = m
POST = Ax
DELETE = d
TRACE = [my-action-group]t

Note: The <default> entry is always mandatory when you add any entries to the [http-method-perms] stanza.

The [http-method-perms] stanza can be specified on a per-junction basis by creating a stanza in the form of [http-method-perms:junction]. The values in the global [http-method-perms] stanza apply to any junctions that do not have a junction-specific stanza. A junction-specific stanza [http-method-perms:junction] does not inherit values from a global stanza. For more information, see [http-method-perms] stanza.

The [http-method-perms] stanza is empty when the Web Reverse Proxy instance is first configured. If the [http-method-perms] stanza is empty, the Web Reverse Proxy defaults to the following ACL bits:

PUT => m
DELETE => d
All else (GET,POST .. ) => r

Configuration validation

The configuration that is specified in the [http-method-perms] stanza is validated each time that a junction is created. The configuration is also validated when the Web Reverse Proxy instance is restarted. This mechanism ensures that the specified ACL bits correspond to actions already defined in the policy database.

The validation process of the [http-method-perms] configuration might cause authorization audit events to be generated. Such audit events will appear as unauthenticated accesses to the Security Access Manager policy object/Permission-Configuration.

If you want to suppress these audit events, attach a protected object policy (POP) with its audit-level attribute set to none to an object with the name /Permission-Configuration. This object is not created in the object space by default. The following pdadmin commands illustrate the creation of policy that will suppress the generation of these audit events:

pdadmin> objectspace create /Permission-Configuration
"Permission configuration validation" 0
pdadmin> pop create permission-configuration
pdadmin> pop modify permission-configuration set audit-level none
pdadmin> pop attach /Permission-Configuration permission-configuration

Parent topic: Default security policy

Domain managementManage domainsAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.domainmanaging (overview)In a domain, an administrator can create users, groups, and other objects. Users and groups are specific to their domain and cannot access resources in other domains. If users and groups are created outside of Security Access Manager, these users and groups can be imported into other domains. Resources that are defined and access controls for resources that are protected by Security Access Manager are maintained on a per domain basis. Resources and access controls for resources cannot be shared among domains.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Logging on to domainsYou can log on to a domain with the Web Portal Manager or pdadmin utility.Creating a domainYou can create several domains in addition to the management domains with the Web Portal Manager or pdadmin utility.Modifying the description for a domainYou can modify a domain description by using the Web Portal Manager or pdadmin utility.Listing domainsYou can list all domains, except for the management domain, by using the Web Portal Manager or pdadmin utility.Deleting a domainYou can delete a domain by using the Web Portal Manager or pdadmin utility.

Domain management

An administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.

In a domain, an administrator can create users, groups, and other objects. Users and groups are specific to their domain and cannot access resources in other domains. If users and groups are created outside of Security Access Manager, these users and groups can be imported into other domains. Resources that are defined and access controls for resources that are protected by Security Access Manager are maintained on a per domain basis. Resources and access controls for resources cannot be shared among domains.

Logging on to domains
You can log on to a domain with the Web Portal Manager or pdadmin utility.

Creating a domain
You can create several domains in addition to the management domains with the Web Portal Manager or pdadmin utility.

Modifying the description for a domain
You can modify a domain description by using the Web Portal Manager or pdadmin utility.

Listing domains
You can list all domains, except for the management domain, by using the Web Portal Manager or pdadmin utility.

Deleting a domain
You can delete a domain by using the Web Portal Manager or pdadmin utility.

Parent topic: Access Manager Platform and Supporting Components administration

Logging on to domainsLog on to domainsYou can log on to a domain with the Web Portal Manager or pdadmin utility.domainlogging onDomain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.Logging on to domains with Web Portal ManagerYou can log on to domains with Web Portal Manager.Logging on to domains with pdadminYou can log on to domains with the pdadmin utility.

Logging on to domains

You can log on to a domain with the Web Portal Manager or pdadmin utility.

Logging on to domains with Web Portal Manager
You can log on to domains with Web Portal Manager.

Logging on to domains with pdadmin
You can log on to domains with the pdadmin utility.

Parent topic: Domain management

Logging on to domains with Web Portal ManagerLogging on to domains with Web Portal ManagerYou can log on to domains with Web Portal Manager.domainlogging on with Web Portal ManagerFrom the login screen, type the domain name that you created. The default domain name is Default.Type the user ID that was created for this domain. The default user ID is sec_master.Type the password associated with the user ID.Logging on to domainsYou can log on to a domain with the Web Portal Manager or pdadmin utility.

Logging on to domains with Web Portal Manager

You can log on to domains with Web Portal Manager.

Procedure

From the login screen, type the domain name that you created. The default domain name is Default.

Type the user ID that was created for this domain. The default user ID is sec_master.

Type the password associated with the user ID.

Parent topic: Logging on to domains

Logging on to domains with pdadminLogging on to domains with pdadminYou can log on to domains with the pdadmin utility.commandslogindomainlogging on with pdadminTo log on to a domain, use the login command. Specify an administrator user ID and password, and a value for the domain.For example, the myadmin_id administrator can log on interactively to the Domain-ABC domain by entering the following command:pdadmin login -a myadmin_id -p 12A345 -d Domain-ABCSee the IBM Security Access Manager for Web: Command Reference.Logging on to domainsYou can log on to a domain with the Web Portal Manager or pdadmin utility.

Logging on to domains with pdadmin

You can log on to domains with the pdadmin utility.

Procedure

To log on to a domain, use the login command. Specify an administrator user ID and password, and a value for the domain.

Example

For example, the myadmin_id administrator can log on interactively to the Domain-ABC domain by entering the following command:

pdadmin login -a myadmin_id -p 12A345 -d Domain-ABC

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Logging on to domains

Creating a domainCreate a domainYou can create several domains in addition to the management domains with the Web Portal Manager or pdadmin utility.Only an administrator who is logged on to the management domain is authorized to create additional domains. Only an administrator with the appropriate permissions in that management domain can create a domain.Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.Creating a domain with Web Portal ManagerYou can create a domain with the Web Portal Manager.Creating a domain with pdadminYou can create a domain with the pdadmin utility.

Creating a domain

You can create several domains in addition to the management domains with the Web Portal Manager or pdadmin utility.

Only an administrator who is logged on to the management domain is authorized to create additional domains. Only an administrator with the appropriate permissions in that management domain can create a domain.

Creating a domain with Web Portal Manager
You can create a domain with the Web Portal Manager.

Creating a domain with pdadmin
You can create a domain with the pdadmin utility.

Parent topic: Domain management

Creating a domain with Web Portal ManagerCreating a domain with Web Portal ManagerYou can create a domain with the Web Portal Manager.domaincreatingwith Web Portal ManagerLog on to the Web Portal Manager management domain as a domain administrator.Click Secure Domain → Create Secure Domain.Type the Secure Domain Name that you want to create. For example, type Domain-ABC.The following restrictions apply to the domain name:The maximum length is limited to 64 characters.The name can contain a-z, A–Z, 0–9, hyphen (-), underscore (_), period (.), "at" symbol (@), or ampersand (&) characters.The name can contain any character from a double-byte character set.Optional: Type a Description of the domain, such as: Test Domain.Type a New Domain Administrator ID. For example, type myadmin_id.You must create an administrator ID for the domain.Type a New Administrator Password. For example, type 12A345. Passwords must adhere to the password policies set by the domain administrator.Type the password again in Confirm Password.Click Create.Creating a domainYou can create several domains in addition to the management domains with the Web Portal Manager or pdadmin utility.

Creating a domain with Web Portal Manager

You can create a domain with the Web Portal Manager.

Procedure

Log on to the Web Portal Manager management domain as a domain administrator.

Click Secure Domain → Create Secure Domain.

Type the Secure Domain Name that you want to create. For example, type Domain-ABC.

The following restrictions apply to the domain name:

The maximum length is limited to 64 characters.

The name can contain a-z, A–Z, 0–9, hyphen (-), underscore (_), period (.), "at" symbol (@), or ampersand (&) characters.

The name can contain any character from a double-byte character set.

Optional: Type a Description of the domain, such as: Test Domain.

Type a New Domain Administrator ID. For example, type myadmin_id.

Note: You must create an administrator ID for the domain.

Type a New Administrator Password. For example, type 12A345. Passwords must adhere to the password policies set by the domain administrator.

Type the password again in Confirm Password.

Click Create.

Parent topic: Creating a domain

Creating a domain with pdadminCreating a domain with pdadminYou can create a domain with the pdadmin utility.domaincommandscreate commanddomaincreatingwith pdadmincommandsdomaincreating Log on to the management domain.Use the domain create command.For example, to create a domain named Domain-ABC, enter the following command on a single line: pdadmin sec_master> domain create Domain-ABC myadmin_id 12A345 -desc "Test Domain"See the IBM Security Access Manager for Web: Command Reference.Creating a domainYou can create several domains in addition to the management domains with the Web Portal Manager or pdadmin utility.

Creating a domain with pdadmin

You can create a domain with the pdadmin utility.

Procedure

Log on to the management domain.

Use the domain create command.

Example

For example, to create a domain named Domain-ABC, enter the following command on a single line:

pdadmin sec_master> domain create Domain-ABC myadmin_id 12A345 -desc "Test Domain"

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Creating a domain

Modifying the description for a domainModify the description for a domainYou can modify a domain description by using the Web Portal Manager or pdadmin utility.domainmodifyingdomaindescription, changingOnly an administrator who is logged on to the management domain is authorized to modify a domain description. A domain can be modified only by an administrator with the appropriate permissions within the management domain.Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.Modifying the description of a domain with Web Portal ManagerYou can modify the description of a domain with the Web Portal Manager.Modifying the description of a domain with pdadminYou can modify the description of a domain with the pdadmin utility.

Modifying the description for a domain

You can modify a domain description by using the Web Portal Manager or pdadmin utility.

Only an administrator who is logged on to the management domain is authorized to modify a domain description. A domain can be modified only by an administrator with the appropriate permissions within the management domain.

Modifying the description of a domain with Web Portal Manager
You can modify the description of a domain with the Web Portal Manager.

Modifying the description of a domain with pdadmin
You can modify the description of a domain with the pdadmin utility.

Parent topic: Domain management

Modifying the description of a domain with Web Portal ManagerModifying the description of a domain with Web Portal ManagerYou can modify the description of a domain with the Web Portal Manager.domainmodifyingwith Web Portal ManagerLog on to the Web Portal Manager management domain as a domain administrator.Click Secure Domain → List Secure Domain.From the Manage Secure Domains page, click the name of the domain that you want to change. For example, click Domain-ABC.From the Secure Domain Properties page, edit the Description field to add a description or change the existing description. For example, type new test domain description to change the existing description.Click Apply.Modifying the description for a domainYou can modify a domain description by using the Web Portal Manager or pdadmin utility.

Modifying the description of a domain with Web Portal Manager

You can modify the description of a domain with the Web Portal Manager.

Procedure

Log on to the Web Portal Manager management domain as a domain administrator.

Click Secure Domain → List Secure Domain.

From the Manage Secure Domains page, click the name of the domain that you want to change. For example, click Domain-ABC.

From the Secure Domain Properties page, edit the Description field to add a description or change the existing description. For example, type new test domain description to change the existing description.

Click Apply.

Parent topic: Modifying the description for a domain

Modifying the description of a domain with pdadminModifying the description of a domain with pdadminYou can modify the description of a domain with the pdadmin utility.domaincommandsmodify commanddomainmodifyingwith pdadmincommandsdomainmodifying descriptionLog on to the management domain as a domain administrator.Use the domain modify command.For example, to change the description of the domain named Domain-ABC to new test domain description, enter the following command on a single line: pdadmin sec_master> domain modify Domain-ABC description "new test domain description"See the IBM Security Access Manager for Web: Command Reference.Modifying the description for a domainYou can modify a domain description by using the Web Portal Manager or pdadmin utility.

Modifying the description of a domain with pdadmin

You can modify the description of a domain with the pdadmin utility.

Procedure

Log on to the management domain as a domain administrator.

Use the domain modify command.

Example

For example, to change the description of the domain named Domain-ABC to new test domain description, enter the following command on a single line:

pdadmin sec_master> domain modify Domain-ABC description "new test
domain description"

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Modifying the description for a domain

Listing domainsList domainsYou can list all domains, except for the management domain, by using the Web Portal Manager or pdadmin utility.domainlistingOnly an administrator who is logged on to the management domain is authorized to list domains. The administrator must have the appropriate permissions to list domains within the management domain.The Manage Secure Domains page displays all the domain names, except for the management domain, as links. You can filter the domain names to view only the domain names that meet the criteria you specify.Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.Listing domains with Web Portal ManagerYou can list the domains, except for the management domain, with the Web Portal Manager.Listing domains with pdadminYou can list all domains, except for the management domain, with the pdadmin utility.

Listing domains

You can list all domains, except for the management domain, by using the Web Portal Manager or pdadmin utility.

Only an administrator who is logged on to the management domain is authorized to list domains. The administrator must have the appropriate permissions to list domains within the management domain.

The Manage Secure Domains page displays all the domain names, except for the management domain, as links. You can filter the domain names to view only the domain names that meet the criteria you specify.

Listing domains with Web Portal Manager
You can list the domains, except for the management domain, with the Web Portal Manager.

Listing domains with pdadmin
You can list all domains, except for the management domain, with the pdadmin utility.

Parent topic: Domain management

Listing domains with Web Portal ManagerListing domains with Web Portal ManagerYou can list the domains, except for the management domain, with the Web Portal Manager.domainlistingwith Web Portal ManagerLog on to the Web Portal Manager management domain as a domain administrator.Click Secure Domain → List Secure Domain. Listing domainsYou can list all domains, except for the management domain, by using the Web Portal Manager or pdadmin utility.

Listing domains with Web Portal Manager

You can list the domains, except for the management domain, with the Web Portal Manager.

Procedure

Log on to the Web Portal Manager management domain as a domain administrator.

Click Secure Domain → List Secure Domain.

Parent topic: Listing domains

Listing domains with pdadminListing domains with pdadminYou can list all domains, except for the management domain, with the pdadmin utility.domaincommandslistcommandsdomainlisting domainlistingwith pdadminLog on to the management domain as a domain administrator.Use the domain list command.pdadmin sec_master> domain listSee the IBM Security Access Manager for Web: Command Reference.Listing domainsYou can list all domains, except for the management domain, by using the Web Portal Manager or pdadmin utility.

Listing domains with pdadmin

You can list all domains, except for the management domain, with the pdadmin utility.

Procedure

Log on to the management domain as a domain administrator.

Use the domain list command.

pdadmin sec_master> domain list

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Listing domains

Deleting a domainDelete a domainYou can delete a domain by using the Web Portal Manager or pdadmin utility.Only an administrator who is logged on to the management domain with the appropriate permissions is authorized to delete domains.Deleting a domain deletes the specified Security Access Manager group. Specifying the optional registry entry option deletes all user and group information, including associated ACL entries, from the user registry when the domain is deleted.The delete operation cannot be reversed.Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains.Deleting a domain with Web Portal ManagerYou can delete a domain with the Web Portal Manager.Deleting a domain with pdadminYou can delete a domain with the pdadmin utility.

Deleting a domain

You can delete a domain by using the Web Portal Manager or pdadmin utility.

Only an administrator who is logged on to the management domain with the appropriate permissions is authorized to delete domains.

Deleting a domain deletes the specified Security Access Manager group. Specifying the optional registry entry option deletes all user and group information, including associated ACL entries, from the user registry when the domain is deleted.

Note: The delete operation cannot be reversed.

Deleting a domain with Web Portal Manager
You can delete a domain with the Web Portal Manager.

Deleting a domain with pdadmin
You can delete a domain with the pdadmin utility.

Parent topic: Domain management

Deleting a domain with Web Portal ManagerDeleting a domain with Web Portal ManagerYou can delete a domain with the Web Portal Manager.domaindeletingwith Web Portal ManagerLog on to the Web Portal Manager management domain as a domain administrator.Click Secure Domain → List Secure Domain.From the Domain List page, select the domain you want to delete.From the Domain Properties page, click Delete.To permanently remove domain information from the user registry, click Delete Registry Entry. Otherwise, the user and group information for the domain remains in the user registry and can be used if the domain is created again.Deleting a domainYou can delete a domain by using the Web Portal Manager or pdadmin utility.

Deleting a domain with Web Portal Manager

You can delete a domain with the Web Portal Manager.

Procedure

Log on to the Web Portal Manager management domain as a domain administrator.

Click Secure Domain → List Secure Domain.

From the Domain List page, select the domain you want to delete.

From the Domain Properties page, click Delete.

To permanently remove domain information from the user registry, click Delete Registry Entry. Otherwise, the user and group information for the domain remains in the user registry and can be used if the domain is created again.

Parent topic: Deleting a domain

Deleting a domain with pdadminDeleting a domain with pdadminYou can delete a domain with the pdadmin utility.domaincommandsdomain delete commandcommandsdomaindomain deletedomaindeletingwith pdadminIf you unconfigure the management domain with the pdconfig utility, any additional domain that exists is deleted.Log on to the management domain as a domain administrator.Use the domain delete command.To permanently remove domain information from the user registry, use the –registry option. Otherwise, the user and group information for the domain remains in the user registry and can be used in case the domain is created again.For example, to delete the domain named Domain-ABC and permanently remove the domain information from the user registry, enter the following command: pdadmin sec_master> domain delete Domain-ABC –registrySee the IBM Security Access Manager for Web: Command Reference.Deleting a domainYou can delete a domain by using the Web Portal Manager or pdadmin utility.

Deleting a domain with pdadmin

You can delete a domain with the pdadmin utility.

About this task

Note: If you unconfigure the management domain with the pdconfig utility, any additional domain that exists is deleted.

Procedure

Log on to the management domain as a domain administrator.

Use the domain delete command.

To permanently remove domain information from the user registry, use the –registry option. Otherwise, the user and group information for the domain remains in the user registry and can be used in case the domain is created again.

Example

For example, to delete the domain named Domain-ABC and permanently remove the domain information from the user registry, enter the following command:

pdadmin sec_master> domain delete Domain-ABC –registry

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Deleting a domain

Object space managementManage object spacesSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.object spacemanagement tasksobject spaceresource objectsobject spacecontainer objects An object space consists of resource objects and container objects. Resource objects are logical representations of resources to be protected. Use Container objects to group resource objects and other container objects hierarchically into logical groups or regions. Grouping similar objects makes it easier for you to administer a consistent security policy.Security policy is applied by attaching access control list (ACL) policies, protected object policies (POPs), and authorization rules to the objects in the object space. These objects represent the physical resources you want to protect. The Security Access Manager authorization service evaluates user credentials and the conditions specified in the security policy. Then, Security Access Manager determines whether to permit or deny access to resources.The following object spaces are created during the installation of Security Access Manager products: The /Management object space during the installation of any Security Access Manager product, if it does not existThe /WebSEAL object space during the installation of Security Access ManagerIn the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page. There are no equivalent pdadmin commands for importing, exporting, and copying object spaces.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Creating an object spaceYou can create an object space with the Web Portal Manager or pdadmin utility.Listing object spacesYou can list all object spaces with the Web Portal Manager or pdadmin utility.Copying an object space with Web Portal ManagerYou can copy an object space only with Web Portal Manager.Importing object spaces with Web Portal ManagerYou can import object spaces only with Web Portal Manager.Exporting object spaces with Web Portal ManagerYou can export object spaces only with Web Portal ManagerDeleting an object spaceYou can delete an object space with the Web Portal Manager or pdadmin utility.

Object space management

Security Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.

An object space consists of resource objects and container objects. Resource objects are logical representations of resources to be protected. Use Container objects to group resource objects and other container objects hierarchically into logical groups or regions. Grouping similar objects makes it easier for you to administer a consistent security policy.

Security policy is applied by attaching access control list (ACL) policies, protected object policies (POPs), and authorization rules to the objects in the object space. These objects represent the physical resources you want to protect. The Security Access Manager authorization service evaluates user credentials and the conditions specified in the security policy. Then, Security Access Manager determines whether to permit or deny access to resources.

The following object spaces are created during the installation of Security Access Manager products:

The /Management object space during the installation of any Security Access Manager product, if it does not exist

The /WebSEAL object space during the installation of Security Access Manager

In the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Note: There are no equivalent pdadmin commands for importing, exporting, and copying object spaces.

Creating an object space
You can create an object space with the Web Portal Manager or pdadmin utility.

Listing object spaces
You can list all object spaces with the Web Portal Manager or pdadmin utility.

Copying an object space with Web Portal Manager
You can copy an object space only with Web Portal Manager.

Importing object spaces with Web Portal Manager
You can import object spaces only with Web Portal Manager.

Exporting object spaces with Web Portal Manager
You can export object spaces only with Web Portal Manager

Deleting an object space
You can delete an object space with the Web Portal Manager or pdadmin utility.

Parent topic: Access Manager Platform and Supporting Components administration

Creating an object spaceCreate an object spaceYou can create an object space with the Web Portal Manager or pdadmin utility.objectspacecreatingTo do this task, the administrator must have the following permissions: Create (N)Modify (m)Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.Creating an object space with Web Portal ManagerYou can create an object space with Web Portal Manager.Creating an object space with pdadminYou can create an object space with the pdadmin utility.

Creating an object space

You can create an object space with the Web Portal Manager or pdadmin utility.

To do this task, the administrator must have the following permissions:

Create (N)

Modify (m)

Creating an object space with Web Portal Manager
You can create an object space with Web Portal Manager.

Creating an object space with pdadmin
You can create an object space with the pdadmin utility.

Parent topic: Object space management

Creating an object space with Web Portal ManagerCreating an object space with Web Portal ManagerYou can create an object space with Web Portal Manager.object spacecreatingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Create Object Space.Type an Object Name. This field is required. For example: /Test-SpaceType a Description for the object space. For example: New Object SpaceClick Create. To see the /Test-Space object space in the hierarchical structure, browse the object space. See Listing object spacesYou can list all object spaces with the Web Portal Manager or pdadmin utility.. Because an object space consists of resource objects and container objects, you do not have to specify an object type when using Web Portal Manager.Creating an object spaceYou can create an object space with the Web Portal Manager or pdadmin utility.

Creating an object space with Web Portal Manager

You can create an object space with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Create Object Space.

Type an Object Name. This field is required. For example: /Test-Space

Type a Description for the object space. For example: New Object Space

Click Create. To see the /Test-Space object space in the hierarchical structure, browse the object space. See Listing object spaces.

Results

Because an object space consists of resource objects and container objects, you do not have to specify an object type when using Web Portal Manager.

Parent topic: Creating an object space

Creating an object space with pdadminCreating an object space with pdadminYou can create an object space with the pdadmin utility.object spacecreatingwith pdadmincommandsobject spacecreatingobject spacecommandscreatingobject spacecreate commandLog on to the domain as a domain administrator.Use the objectspace create command. Do not use the objectspace command on object spaces that are created by or developed with Security Access Manager. The following object spaces are created by Security Access Manager: /Management/WebSEAL/OSSEALFor example, to create the /Test-Space object space that is an application container object, which is object type 14, enter the following command: pdadmin sec_master> objectspace create /Test-Space "New Object Space" 14When creating an object space, an object type must be specified. This object space example assigns an object type of 14, which is for an application container object.Protected object spaceSecurity Access Manager conceptualizes resources in a domain by showing a virtual representation called the protected object space. The protected object space is the logical and hierarchical portrayal of resources that belong to a domain. describes the two general types of objects: resource objects and container objects. You can select any of the listed object space types. Alternatively, use any unused category number listed in the following list to designate the object space type and assign a meaning to it.The following object space types are valid for Security Access Manager: 0Unknown1Secure domain2File3Executable program4Directory5Junction6WebSEAL server7Unused8Unused9HTTP server10Nonexistent object11Container object12Leaf object13Port14Application container object15Application leaf object16Management object17UnusedSee the IBM Security Access Manager for Web: Command Reference.Creating an object spaceYou can create an object space with the Web Portal Manager or pdadmin utility.

Creating an object space with pdadmin

You can create an object space with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the objectspace create command.

Results

Note: Do not use the objectspace command on object spaces that are created by or developed with Security Access Manager. The following object spaces are created by Security Access Manager:

/Management

/WebSEAL

/OSSEAL

For example, to create the /Test-Space object space that is an application container object, which is object type 14, enter the following command:

pdadmin sec_master> objectspace create /Test-Space "New Object Space" 14

When creating an object space, an object type must be specified. This object space example assigns an object type of 14, which is for an application container object.

Protected object space describes the two general types of objects: resource objects and container objects. You can select any of the listed object space types. Alternatively, use any unused category number listed in the following list to designate the object space type and assign a meaning to it.

The following object space types are valid for Security Access Manager:

0

Unknown

1

Secure domain

2

File

3

Executable program

4

Directory

5

Junction

6

WebSEAL server

7

Unused

8

Unused

9

HTTP server

10

Nonexistent object

11

Container object

12

Leaf object

13

Port

14

Application container object

15

Application leaf object

16

Management object

17

Unused

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Creating an object space

Listing object spacesListing object spacesYou can list all object spaces with the Web Portal Manager or pdadmin utility.object spacebrowsingTo do this task, the administrator requires the following permissions: Browse (b)View (v)Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.Listing object spaces with Web Portal ManagerYou can list object spaces with Web Portal Manager.Listing object spaces with pdadminYou can list object spaces with the pdadmin utility.

Listing object spaces

You can list all object spaces with the Web Portal Manager or pdadmin utility.

To do this task, the administrator requires the following permissions:

Browse (b)

View (v)

Listing object spaces with Web Portal Manager
You can list object spaces with Web Portal Manager.

Listing object spaces with pdadmin
You can list object spaces with the pdadmin utility.

Parent topic: Object space management

Listing object spaces with Web Portal ManagerListing object spaces with Web Portal ManagerYou can list object spaces with Web Portal Manager.object spacelistingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Browse Object Space to display the Browse Object Space page.The Browse Object Space page displays all the objects in the domain in a hierarchical structure. All object spaces appear at the same structural level as the default /Management object space. Each object space and the corresponding object are displayed as a link. When you select any link, the Protected Object Properties page for that object or object space is displayed.Listing object spacesYou can list all object spaces with the Web Portal Manager or pdadmin utility.

Listing object spaces with Web Portal Manager

You can list object spaces with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Browse Object Space to display the Browse Object Space page.

Results

The Browse Object Space page displays all the objects in the domain in a hierarchical structure. All object spaces appear at the same structural level as the default /Management object space. Each object space and the corresponding object are displayed as a link. When you select any link, the Protected Object Properties page for that object or object space is displayed.

Parent topic: Listing object spaces

Listing object spaces with pdadminListing object spaces with pdadminYou can list object spaces with the pdadmin utility.object spacelistingwith pdadmincommandsobject spacelistingobject spacecommandslistingobjectspace list commandLog on to the domain as a domain administrator.Use the objectspace list command.pdadmin sec_master> objectspace listSee the IBM Security Access Manager for Web: Command Reference.Listing object spacesYou can list all object spaces with the Web Portal Manager or pdadmin utility.

Listing object spaces with pdadmin

You can list object spaces with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the objectspace list command.

pdadmin sec_master> objectspace list

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Listing object spaces

Copying an object space with Web Portal ManagerCopying an object space with Web Portal ManagerYou can copy an object space only with Web Portal Manager.object spacecopyingUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Copy/Paste Object Space to display the Copy/Paste Object Space page.To select which objects to copy, navigate the object space and select the object-specific check boxes in the Copy column.To select where these objects are to be pasted, navigate to the object space and select the object-specific check boxes in the Paste column.Click Copy/Paste to copy the selected object space hierarchies to the designated locations.If successful, the copied object space is shown under the pasted location. To validate, click Refresh.Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.

Copying an object space with Web Portal Manager

You can copy an object space only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Copy/Paste Object Space to display the Copy/Paste Object Space page.

To select which objects to copy, navigate the object space and select the object-specific check boxes in the Copy column.

To select where these objects are to be pasted, navigate to the object space and select the object-specific check boxes in the Paste column.

Click Copy/Paste to copy the selected object space hierarchies to the designated locations.

Results

If successful, the copied object space is shown under the pasted location. To validate, click Refresh.

Parent topic: Object space management

Importing object spaces with Web Portal ManagerImporting object spaces with Web Portal ManagerYou can import object spaces only with Web Portal Manager.object spaceimporting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Import Object.From the Import Protected Object From File page, complete one of the following steps:In the Object File Name field, type the name of the object to import. For example, type objectImport.xml.Click Browse to select a file name.Optional: Select the Create Groups check box to trigger the creation of a group for associated ACLs with entries with the type Group.When the Create Groups box is selected, in the Registry Container text field, type the name of the registry container. For example, type o=ibm,c=us.The file that contains the object space might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.Click Import. If successful, the imported object space is available when you browse the object space.Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.

Importing object spaces with Web Portal Manager

You can import object spaces only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Import Object.

From the Import Protected Object From File page, complete one of the following steps:

In the Object File Name field, type the name of the object to import. For example, type objectImport.xml.

Click Browse to select a file name.

Optional: Select the Create Groups check box to trigger the creation of a group for associated ACLs with entries with the type Group.

When the Create Groups box is selected, in the Registry Container text field, type the name of the registry container. For example, type o=ibm,c=us.

The file that contains the object space might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.

Click Import.

Results

If successful, the imported object space is available when you browse the object space.

Parent topic: Object space management

Exporting object spaces with Web Portal ManagerExporting object spaces with Web Portal ManagerYou can export object spaces only with Web Portal Managerobject spaceexporting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object SpaceBrowse Object Space to display the Browse Object Space page.Navigate the hierarchy and select the object that you want to export.From the Protected Object Properties page, click Export to display the Export Object to File page.Optional: Select the Export Object including Children check box to descend the object hierarchy and export all child objects.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an Encryption String is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported description. The default file name is objectExport.xml.If successful, the exported XML description file is available in the specified location.Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.

Exporting object spaces with Web Portal Manager

You can export object spaces only with Web Portal Manager

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space > Browse Object Space to display the Browse Object Space page.

Navigate the hierarchy and select the object that you want to export.

From the Protected Object Properties page, click Export to display the Export Object to File page.

Optional: Select the Export Object including Children check box to descend the object hierarchy and export all child objects.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an Encryption String is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported description. The default file name is objectExport.xml.

Results

If successful, the exported XML description file is available in the specified location.

Parent topic: Object space management

Deleting an object spaceDelete an object spaceYou can delete an object space with the Web Portal Manager or pdadmin utility.objectspacedeletingTo do this task, the administrator requires the following permissions: Delete (d)Modify (m)Object space managementSecurity Access Manager represents resources to be protected with a virtual representation of the object space that is called the protected object space.Deleting an object space with Web Portal ManagerYou can delete an object space with Web Portal Manager.Deleting an object space with pdadminYou can delete an object space with the pdadmin utility.

Deleting an object space

You can delete an object space with the Web Portal Manager or pdadmin utility.

To do this task, the administrator requires the following permissions:

Delete (d)

Modify (m)

Deleting an object space with Web Portal Manager
You can delete an object space with Web Portal Manager.

Deleting an object space with pdadmin
You can delete an object space with the pdadmin utility.

Parent topic: Object space management

Deleting an object space with Web Portal ManagerDeleting an object space with Web Portal ManagerYou can delete an object space with Web Portal Manager.object spacedeletingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Browse Object Space.From the Browse Object Space page, expand and click the object space that you want to delete.From the Protected Object Properties page, the name of the object space is displayed in the Object Name field. Click Delete.To confirm the deletion, click Delete again.If successful, a message indicates that the object space was deleted.Deleting an object spaceYou can delete an object space with the Web Portal Manager or pdadmin utility.

Deleting an object space with Web Portal Manager

You can delete an object space with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Browse Object Space.

From the Browse Object Space page, expand and click the object space that you want to delete.

From the Protected Object Properties page, the name of the object space is displayed in the Object Name field. Click Delete.

To confirm the deletion, click Delete again.

Results

If successful, a message indicates that the object space was deleted.

Parent topic: Deleting an object space

Deleting an object space with pdadminYou can delete an object space with the pdadmin utility.object spacedeletingwith pdadmincommandsobject spacedeletingobject spacecommandsdeletingobjectspace delete commandLog on to the domain as a domain administrator.Use the objectspace delete command.For example, to delete the object space named /Test-Space, enter the following command: pdadmin sec_master> objectspace delete /Test-Space See the IBM Security Access Manager for Web: Command Reference.Deleting an object spaceYou can delete an object space with the Web Portal Manager or pdadmin utility.

Deleting an object space with pdadmin

You can delete an object space with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the objectspace delete command.

Example

For example, to delete the object space named /Test-Space, enter the following command:

pdadmin sec_master> objectspace delete /Test-Space

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Deleting an object space

Manage protected objectsManage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.protectedobject management tasksobjectmanagement tasksIn the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page. There are no equivalent pdadmin commands for importing, exporting, and copying object spaces.After an object space is created, you can populate it with objects and then manage these objects. For information about creating an object space, see Creating an object spaceYou can create an object space with the Web Portal Manager or pdadmin utility..Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Create an objectYou can create an object with the pdadmin utility.List objectsYou can list objects in the domain with the Web Portal Manager or pdadmin utility. Importing objects with Web Portal ManagerYou can import objects only with Web Portal Manager.Exporting objects with Web Portal ManagerYou can export an object only with Web Portal Manager.Delete an objectYou can delete an object with the Web Portal Manager or pdadmin utility.

Manage protected objects

An object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.

In the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Note: There are no equivalent pdadmin commands for importing, exporting, and copying object spaces.

After an object space is created, you can populate it with objects and then manage these objects. For information about creating an object space, see Creating an object space.

Create an object
You can create an object with the pdadmin utility.

List objects
You can list objects in the domain with the Web Portal Manager or pdadmin utility.

Importing objects with Web Portal Manager
You can import objects only with Web Portal Manager.

Exporting objects with Web Portal Manager
You can export an object only with Web Portal Manager.

Delete an object
You can delete an object with the Web Portal Manager or pdadmin utility.

Parent topic: Access Manager Platform and Supporting Components administration

Create an objectCreate an objectYou can create an object with the pdadmin utility.objectcreatingfrom rootobjectcreatingfrom parent objectWeb Portal Manager provides two ways of creating objects:Specifying the fully qualified path of the new object, starting from rootSpecifying the new object from the provided path of the parent objectTo do this task, the administrator requires the following permissions: Create (N)Modify (m)Manage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.Creating an object with Web Portal Manager, from rootYou can create an object at the root level with Web Portal Manager. The object specifies the path from root.Creating an object with Web Portal Manager, from parent objectYou can create an object that uses the parent object as the base path with Web Portal Manager.Creating an object with pdadminYou can create an object in the domain with the pdadmin utility.

Create an object

You can create an object with the pdadmin utility.

Web Portal Manager provides two ways of creating objects:

Specifying the fully qualified path of the new object, starting from root

Specifying the new object from the provided path of the parent object

To do this task, the administrator requires the following permissions:

Create (N)

Modify (m)

Creating an object with Web Portal Manager, from root
You can create an object at the root level with Web Portal Manager. The object specifies the path from root.

Creating an object with Web Portal Manager, from parent object
You can create an object that uses the parent object as the base path with Web Portal Manager.

Creating an object with pdadmin
You can create an object in the domain with the pdadmin utility.

Parent topic: Manage protected objects

Creating an object with Web Portal Manager, from rootCreating an object with Web Portal Manager, from rootYou can create an object at the root level with Web Portal Manager. The object specifies the path from root.objectroot, creating from Use Web Portal Manager to log on to the domain as a domain administrator.Click Object Space Create Object to display the Create Protected Object page.Type the full path of the object in the Object Name text field. For example, type /Management/Groups/test-object.Optional: In the Description text field, type a description for the object. For example, type Test Object.Click Create.To be able to attach a policy to this protected object, click Object Space → Browse Object Space. The Browse Object Space page provides a hierarchical view of all the objects in the domain as links. Click the link for an object to go to its Protected Object Properties page. From this page, select the Can Policy be attached to this object check box and click Apply.Create an objectYou can create an object with the pdadmin utility.

Creating an object with Web Portal Manager, from root

You can create an object at the root level with Web Portal Manager. The object specifies the path from root.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space > Create Object to display the Create Protected Object page.

Type the full path of the object in the Object Name text field. For example, type /Management/Groups/test-object.

Optional: In the Description text field, type a description for the object. For example, type Test Object.

Click Create.

What to do next

To be able to attach a policy to this protected object, click Object Space → Browse Object Space. The Browse Object Space page provides a hierarchical view of all the objects in the domain as links. Click the link for an object to go to its Protected Object Properties page. From this page, select the Can Policy be attached to this object check box and click Apply.

Parent topic: Create an object

Creating an object with Web Portal Manager, from parent objectCreating an object with Web Portal Manager, from parent objectYou can create an object that uses the parent object as the base path with Web Portal Manager.objectparent object, creating fromUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Browse Object Space to display the Browse Object Space page.Navigate the object hierarchy and select the link of the parent object to display the Protect Object Properties page. For example, select the link that is associated with the /Management/Groups object.Click the Create Child Object link to display the Create Protected Object page where the Object Name and Description fields contain the values of the parent object.In the Object Name field, append a slash and the name of the new object. For example, append /test-object to the provided parent path of /Management/Groups.Optional: In the Description field, modify the description for the object. For example, type Test Object.Click Create.After the object is created, a dialog is displayed with the link to this object. To attach a policy to this protected object, click this link to display its Protected Object Properties page. From this page, select the Can Policy be attached to this object check box and click Apply.Create an objectYou can create an object with the pdadmin utility.

Creating an object with Web Portal Manager, from parent object

You can create an object that uses the parent object as the base path with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Browse Object Space to display the Browse Object Space page.

Navigate the object hierarchy and select the link of the parent object to display the Protect Object Properties page. For example, select the link that is associated with the /Management/Groups object.

Click the Create Child Object link to display the Create Protected Object page where the Object Name and Description fields contain the values of the parent object.

In the Object Name field, append a slash and the name of the new object. For example, append /test-object to the provided parent path of /Management/Groups.

Optional: In the Description field, modify the description for the object. For example, type Test Object.

Click Create.

What to do next

After the object is created, a dialog is displayed with the link to this object. To attach a policy to this protected object, click this link to display its Protected Object Properties page. From this page, select the Can Policy be attached to this object check box and click Apply.

Parent topic: Create an object

Creating an object with pdadminCreating an object with pdadminYou can create an object in the domain with the pdadmin utility.objectcreatingwith pdadmincommandsobjectcreatingobjectcommandscreatingLog on to the domain as the domain administrator.Use the object create command.For example, to create the object named /Management/test-object that is an application container object (14), enter the following command: pdadmin object create /Management/test-object “Test Object” 14 ispolicyattachable yesThe type can be one of the following object type categories: 0Unknown1Secure domain2File3Executable program4Directory5Junction6WebSEAL server7Unused8Unused9HTTP server10Nonexistent object11Container object12Leaf object13Port14Application container object15Application leaf object16Management object17Unused When creating an object, a type must be specified. You can select an appropriate category, or use any number to designate the object type and assign a meaning to it.If the ispolicyattachable option is omitted from the object create command, this command assumes that you intended to use the objectspace create command. An object space is created rather than an object.See the IBM Security Access Manager for Web: Command Reference.Create an objectYou can create an object with the pdadmin utility.

Creating an object with pdadmin

You can create an object in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the object create command.

Results

For example, to create the object named /Management/test-object that is an application container object (14), enter the following command:

pdadmin object create /Management/test-object “Test Object” 14
        ispolicyattachable yes

The type can be one of the following object type categories:

0

Unknown

1

Secure domain

2

File

3

Executable program

4

Directory

5

Junction

6

WebSEAL server

7

Unused

8

Unused

9

HTTP server

10

Nonexistent object

11

Container object

12

Leaf object

13

Port

14

Application container object

15

Application leaf object

16

Management object

17

Unused

When creating an object, a type must be specified. You can select an appropriate category, or use any number to designate the object type and assign a meaning to it.

If the ispolicyattachable option is omitted from the object create command, this command assumes that you intended to use the objectspace create command. An object space is created rather than an object.

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create an object

List objectsList objectsYou can list objects in the domain with the Web Portal Manager or pdadmin utility. To do this task, the administrator requires the following permissions: Browse (b)View (v)Manage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.Listing objects with Web Portal ManagerYou can list objects with Web Portal Manager.Listing objects with pdadminYou can list all objects in the domain with the pdadmin utility.

List objects

You can list objects in the domain with the Web Portal Manager or pdadmin utility.

To do this task, the administrator requires the following permissions:

Browse (b)

View (v)

Listing objects with Web Portal Manager
You can list objects with Web Portal Manager.

Listing objects with pdadmin
You can list all objects in the domain with the pdadmin utility.

Parent topic: Manage protected objects

Listing objects with Web Portal ManagerListing objects with Web Portal ManagerYou can list objects with Web Portal Manager.objectlisting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object SpaceBrowse Object Space.The Browse Object Space page displays all the objects in the domain in a hierarchical structure. All object spaces are listed at the same structural level as the default /Management object space. Each object space and each object are displayed as a link. When you select any link, the Protected Object Properties page for that object or object space is displayed.List objectsYou can list objects in the domain with the Web Portal Manager or pdadmin utility.

Listing objects with Web Portal Manager

You can list objects with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space > Browse Object Space.

Results

The Browse Object Space page displays all the objects in the domain in a hierarchical structure. All object spaces are listed at the same structural level as the default /Management object space. Each object space and each object are displayed as a link. When you select any link, the Protected Object Properties page for that object or object space is displayed.

Parent topic: List objects

Listing objects with pdadminListing objects with pdadminYou can list all objects in the domain with the pdadmin utility.objectlisting with pdadmincommandsobject listingobjectcommandslistingobjectlist commandLog on to the domain as the domain administrator.Use the object list command.For example, to list the objects under the /Management object space, enter the following command: pdadmin sec_master> object list /ManagementSee the IBM Security Access Manager for Web: Command Reference.List objectsYou can list objects in the domain with the Web Portal Manager or pdadmin utility.

Listing objects with pdadmin

You can list all objects in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the object list command.

Example

For example, to list the objects under the /Management object space, enter the following command:

pdadmin sec_master> object list /Management

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: List objects

Importing objects with Web Portal ManagerImporting objects with Web Portal ManagerYou can import objects only with Web Portal Manager.objectimporting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object SpaceImport Object.From the Import Protected Object From File page, complete one of the following steps:In the Object File Name field, type the name of the object to import. For example, type objectImport.xml.Click Browse to select a file name.Optional: Select the Create Groups check box to trigger the creation of a group for associated ACLs with the type Group.When the Create Groups box is selected, in the Registry Container text field, type the name of the registry container. For example, type o=ibm,c=us.The file that contains the object space might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.Click Import. If successful, the imported object is available when you browse the object space.Manage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.

Importing objects with Web Portal Manager

You can import objects only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space > Import Object.

From the Import Protected Object From File page, complete one of the following steps:

In the Object File Name field, type the name of the object to import. For example, type objectImport.xml.

Click Browse to select a file name.

Optional: Select the Create Groups check box to trigger the creation of a group for associated ACLs with the type Group.

When the Create Groups box is selected, in the Registry Container text field, type the name of the registry container. For example, type o=ibm,c=us.

The file that contains the object space might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.

Click Import.

Results

If successful, the imported object is available when you browse the object space.

Parent topic: Manage protected objects

Exporting objects with Web Portal ManagerExporting objects with Web Portal ManagerYou can export an object only with Web Portal Manager.objectexporting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Browse Object Space to display the Browse Object Space page.Navigate the hierarchy and select the object that you want to export.From the Protected Object Properties page, click Export to display the Export Object to File page.Optional: Select the Export Object including Children check box to descend the object hierarchy and export all child objects.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported description. The default file name is objectExport.xml.If successful, the exported XML description file is available in the specified location.Manage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.

Exporting objects with Web Portal Manager

You can export an object only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Browse Object Space to display the Browse Object Space page.

Navigate the hierarchy and select the object that you want to export.

From the Protected Object Properties page, click Export to display the Export Object to File page.

Optional: Select the Export Object including Children check box to descend the object hierarchy and export all child objects.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported description. The default file name is objectExport.xml.

Results

If successful, the exported XML description file is available in the specified location.

Parent topic: Manage protected objects

Delete an objectDelete an objectYou can delete an object with the Web Portal Manager or pdadmin utility.To do this task, the administrator requires the following permissions: Delete (d)Modify (m)Manage protected objectsAn object is a logical representation of a system resource. To protect objects, you must apply security policies. Security policies are the combination of access control list (ACL) policies, protected object policies (POPs), and authorization rules that you can attach to an object.Deleting an object with Web Portal ManagerYou can delete an object with Web Portal Manager. Deleting an object with pdadminYou can delete an object with the pdadmin utility.

Delete an object

You can delete an object with the Web Portal Manager or pdadmin utility.

To do this task, the administrator requires the following permissions:

Delete (d)

Modify (m)

Deleting an object with Web Portal Manager
You can delete an object with Web Portal Manager.

Deleting an object with pdadmin
You can delete an object with the pdadmin utility.

Parent topic: Manage protected objects

Deleting an object with Web Portal ManagerDeleting an object with Web Portal ManagerYou can delete an object with Web Portal Manager. objectdeletingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Browse Object Space.The Browse Object Space page provides a hierarchical display of all objects in the domain as links.Click the link for an object to see its properties. These properties include whether ACL policies, POPs, and authorization rules are attached to the object and whether the object has extended attributes. For example, click the /Management/text-object link to display its properties.From the Protected Object Properties page, ensure the object named is the one you want to delete and click Delete.Delete an objectYou can delete an object with the Web Portal Manager or pdadmin utility.

Deleting an object with Web Portal Manager

You can delete an object with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Browse Object Space.

The Browse Object Space page provides a hierarchical display of all objects in the domain as links.

Click the link for an object to see its properties. These properties include whether ACL policies, POPs, and authorization rules are attached to the object and whether the object has extended attributes. For example, click the /Management/text-object link to display its properties.

From the Protected Object Properties page, ensure the object named is the one you want to delete and click Delete.

Parent topic: Delete an object

Deleting an object with pdadminDeleting an object with pdadminYou can delete an object with the pdadmin utility.objectdeletingwith pdadmincommandsobjectdeletingobjectcommandsdeletingobjectdelete commandLog on to the domain as the domain administrator.Use the object delete command.For example, to delete the object named /Management/test-object, enter the following command: pdadmin object delete /Management/test-objectSee the IBM Security Access Manager for Web: Command Reference.Delete an objectYou can delete an object with the Web Portal Manager or pdadmin utility.

Deleting an object with pdadmin

You can delete an object with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the object delete command.

Example

For example, to delete the object named /Management/test-object, enter the following command:

pdadmin object delete /Management/test-object

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete an object

Manage access controlManage access controlA domain administrator can use access control list (ACL) policies to control access to objects.ACLmanagementpoliciesACLpoliciesaccess control, managingACL policies contain ACL entries that control who can access which domain resources and do which actions. A domain administrator manages the ACL policies by adding, removing, and modifying the ACL entries in the ACL policies. See ACL policiesIn the protected object space, ACL policies can be attached to resource objects and container objects. . For details about the ACL policy tasks that a domain administrator can do, see Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server..An ACL entry defines a user or group and which actions each can do against a protected object. A domain administrator can manage these ACL entries before or after the ACL policy is attached to domain resources. Any change to the ACL entry affects only the access that these users and groups have against a specific domain resource to which the ACL policy is attached. See ACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform. .To define ACL entries, a domain administrator adds or removes permissions (actions) for specific users or groups. A permission is an action that is defined by an action bit in an action group. An action group is a set of permissions. A domain administrator can add or remove action groups from an ACL entry. When Security Access Manager is installed, the primary action group is created, and contains 17 permissions. These permissions are defined with action bits. As additional resource managers are installed, additional action groups might be created. As needed, a domain administrator can create additional action groups and add new actions to previously created action groups. See Action groups and actionsA domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit. . For details about the action group tasks that a domain administrator can do, see Manage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. . For details about the action tasks that a domain administrator can do, see Manage actionsYou can manage actions with the Web Portal Manager or pdadmin utility..A domain administrator can assign administrative authority to another user. To define another administrative user, the domain administrator sets the ACL entries for that user to match the ACL entries of the domain administrator. In this situation, both the new administrative user and the domain administrator have the same authority.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. ACL policiesIn the protected object space, ACL policies can be attached to resource objects and container objects. ACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform. Action groups and actionsA domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit. Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Manage ACL entries in ACL policiesYou can manage ACL entries in ACL policies with the Web Portal Manager or pdadmin utility.Manage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.Manage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. Manage actionsYou can manage actions with the Web Portal Manager or pdadmin utility.

Manage access control

A domain administrator can use access control list (ACL) policies to control access to objects.

ACL policies contain ACL entries that control who can access which domain resources and do which actions. A domain administrator manages the ACL policies by adding, removing, and modifying the ACL entries in the ACL policies. See ACL policies. For details about the ACL policy tasks that a domain administrator can do, see Manage ACL policies.

An ACL entry defines a user or group and which actions each can do against a protected object. A domain administrator can manage these ACL entries before or after the ACL policy is attached to domain resources. Any change to the ACL entry affects only the access that these users and groups have against a specific domain resource to which the ACL policy is attached. See ACL entries.

To define ACL entries, a domain administrator adds or removes permissions (actions) for specific users or groups. A permission is an action that is defined by an action bit in an action group. An action group is a set of permissions. A domain administrator can add or remove action groups from an ACL entry.

When Security Access Manager is installed, the primary action group is created, and contains 17 permissions. These permissions are defined with action bits.

As additional resource managers are installed, additional action groups might be created. As needed, a domain administrator can create additional action groups and add new actions to previously created action groups. See Action groups and actions. For details about the action group tasks that a domain administrator can do, see Manage action groups. For details about the action tasks that a domain administrator can do, see Manage actions.

A domain administrator can assign administrative authority to another user. To define another administrative user, the domain administrator sets the ACL entries for that user to match the ACL entries of the domain administrator. In this situation, both the new administrative user and the domain administrator have the same authority.

ACL policies
In the protected object space, ACL policies can be attached to resource objects and container objects.

ACL entries
Each ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform.

Action groups and actions
A domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit.

Manage ACL policies
You can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.

Manage ACL entries in ACL policies
You can manage ACL entries in ACL policies with the Web Portal Manager or pdadmin utility.

Manage extended attributes in ACL policies
The following sections describe using pdadmin and Web Portal Manager.

Manage action groups
Permissions grant access to do a specific operation on resources that are protected by Security Access Manager.

Manage actions
You can manage actions with the Web Portal Manager or pdadmin utility.

Parent topic: Access Manager Platform and Supporting Components administration

ACL policiesACL policiesIn the protected object space, ACL policies can be attached to resource objects and container objects. ACLpoliciessecurity considerationssecurityconsiderationsACL policiessecurityconsiderationscontainer objectscontainerobjectssecurity considerationsEach ACL policy contains one or more ACL entries that affect only that object. For example, the ACL policy that is attached to the spooler object might allow all requesters the following permissions: ExecuteListReadWriteHowever, the ACL policy that is attached to the docs_repository object might allow all requesters the following permissions: ListReadIn this case, both ACL policies that are attached to these objects for all requesters. However, the permissions that are defined in the ACL entry for all requesters are different.Container objects represent specific regions in the protected object space. After a domain administrator creates an ACL policy and attaches it to a container object, the ACL policy serves the following important security tasks: The root (/) container object begins the chain of ACL inheritance for the entire protected object space.Through inheritance, the root object defines the security policy for the entire object space.Unless an explicit ACL policy is attached to a contained object, the ACL policy for the container object defines the security policy for all resources in that container object.The traverse permission allows a requester to pass through a container object to the requested object. To deny access to all objects in a region, remove the traverse permission (T action bit) from the ACL entry.The traverse permission does not grant any other access controls to the container object.Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.

ACL policies

In the protected object space, ACL policies can be attached to resource objects and container objects.

Each ACL policy contains one or more ACL entries that affect only that object. For example, the ACL policy that is attached to the spooler object might allow all requesters the following permissions:

Execute

List

Read

Write

However, the ACL policy that is attached to the docs_repository object might allow all requesters the following permissions:

List

Read

In this case, both ACL policies that are attached to these objects for all requesters. However, the permissions that are defined in the ACL entry for all requesters are different.

Container objects represent specific regions in the protected object space. After a domain administrator creates an ACL policy and attaches it to a container object, the ACL policy serves the following important security tasks:

The root (/) container object begins the chain of ACL inheritance for the entire protected object space.

Through inheritance, the root object defines the security policy for the entire object space.

Unless an explicit ACL policy is attached to a contained object, the ACL policy for the container object defines the security policy for all resources in that container object.

The traverse permission allows a requester to pass through a container object to the requested object. To deny access to all objects in a region, remove the traverse permission (T action bit) from the ACL entry.

The traverse permission does not grant any other access controls to the container object.

Parent topic: Manage access control

ACL entriesACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform. ACLentriesattributes, requiredThe number of required attributes for an ACL entry depends on the ACL entry type. The general format of an ACL entry contains the following attributes: TypeSpecifies the entity category (user, group, or special) for which the ACL entry was created. See Type attributeThe type attribute of an ACL entry type identifies the user, group, or special entity for a specific ACL entry. .IDThe unique identifier (name) of the user or group that is specified with the type attribute. The any-other and unauthenticated special entry types do not require the ID attribute. See ID attributeEach user ACL entry and each group ACL entry have unique identifiers (name). .PermissionsDefines the set of permissions (actions) that are permitted on the resource by this user or group. Permissions are defined by using action bits. Action bits are defined in action groups. See Permissions attributeEach ACL entry contains a set of permissions (actions) that describes the specific operations that are permitted on the object by the user or group. Permissions are context-sensitive. and Action groups and actionsA domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit. .Figure 1 shows the attributes of an ACL entry. ACL entry attributesAttributes of an ACL entry.Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Type attributeThe type attribute of an ACL entry type identifies the user, group, or special entity for a specific ACL entry. ID attributeEach user ACL entry and each group ACL entry have unique identifiers (name). Permissions attributeEach ACL entry contains a set of permissions (actions) that describes the specific operations that are permitted on the object by the user or group. Permissions are context-sensitive.

ACL entries

Each ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform.

The number of required attributes for an ACL entry depends on the ACL entry type. The general format of an ACL entry contains the following attributes:

Type

Specifies the entity category (user, group, or special) for which the ACL entry was created. See Type attribute.

ID

The unique identifier (name) of the user or group that is specified with the type attribute. The any-other and unauthenticated special entry types do not require the ID attribute. See ID attribute.

Permissions

Defines the set of permissions (actions) that are permitted on the resource by this user or group. Permissions are defined by using action bits. Action bits are defined in action groups. See Permissions attribute and Action groups and actions.

Figure 83. shows the attributes of an ACL entry.

Figure 83. ACL entry attributes

Type attribute
The type attribute of an ACL entry type identifies the user, group, or special entity for a specific ACL entry.

ID attribute
Each user ACL entry and each group ACL entry have unique identifiers (name).

Permissions attribute
Each ACL entry contains a set of permissions (actions) that describes the specific operations that are permitted on the object by the user or group. Permissions are context-sensitive.

Parent topic: Manage access control

Type attributeType attributeThe type attribute of an ACL entry type identifies the user, group, or special entity for a specific ACL entry. ACLentriestype attributeattributesACL typetype attributecategoriesThe following types are supported: useruserstype attributetype attributeuserSets permissions for a specific user in a domain. The user must be a member of the domain with an account in the registry. The user entry type requires a user name (ID). The entry format is user ID permissions as shown in the following example: user anthony -------T-----r-groupgroupstype attributetype attributegroupSets permissions for all members of a specific group in a domain. The group entry type requires a group name (ID). The entry format is group ID permissions as shown in the following example: group engineering -------T-----r-any-otherany-othertype attributetype attributeany-othertype attributeany-authenticatedany-authenticated type attributeSets permissions for all authenticated users. No ID designation is required. The entry format is any-other permissions as shown in the following example: any-other -------T-----r- The any-other entry type is also known as any-authenticated.unauthenticatedunauthenticatedtype attributetype attributeunauthenticatedSets permissions for those users who are not authenticated by the policy server. No ID attribute is required in the ACL entry. The entry format is unauthenticated permissions as shown in the following example: unauthenticated -------T-----r- This ACL entry is a mask (a bit-wise and operation) against the any-other ACL entry to determine the action set. A permission for unauthenticated is granted only if the permission also appears in the any-other entry. For example, when unauthenticated has read and write permissions and any-other has transverse and read permissions, the resulting action set is read only. This example is shown in the following equation: unauthenticated -------------rw + any-other -------T-----r- -------------r-ACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform.

Type attribute

The type attribute of an ACL entry type identifies the user, group, or special entity for a specific ACL entry.

The following types are supported:

user

Sets permissions for a specific user in a domain. The user must be a member of the domain with an account in the registry. The user entry type requires a user name (ID). The entry format is user ID permissions as shown in the following example:

user anthony -------T-----r-

group

Sets permissions for all members of a specific group in a domain. The group entry type requires a group name (ID). The entry format is group ID permissions as shown in the following example:

group engineering -------T-----r-

any-other

Sets permissions for all authenticated users. No ID designation is required. The entry format is any-other permissions as shown in the following example:

any-other   -------T-----r-

The any-other entry type is also known as any-authenticated.

unauthenticated

Sets permissions for those users who are not authenticated by the policy server. No ID attribute is required in the ACL entry. The entry format is unauthenticated permissions as shown in the following example:

unauthenticated -------T-----r-

This ACL entry is a mask (a bit-wise and operation) against the any-other ACL entry to determine the action set. A permission for unauthenticated is granted only if the permission also appears in the any-other entry.

For example, when unauthenticated has read and write permissions and any-other has transverse and read permissions, the resulting action set is read only. This example is shown in the following equation:

   unauthenticated -------------rw
+  any-other       -------T-----r-
                   -------------r-

Parent topic: ACL entries

ID attributeID attributeEach user ACL entry and each group ACL entry have unique identifiers (name). ACLentriesID attributeattributesACL IDID attributeThese names must represent valid users or groups that are created in a domain and have an account in the registry.The any-other and unauthenticated special entry types do not use the ID attribute.ACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform.

ID attribute

Each user ACL entry and each group ACL entry have unique identifiers (name).

These names must represent valid users or groups that are created in a domain and have an account in the registry.

The any-other and unauthenticated special entry types do not use the ID attribute.

Parent topic: ACL entries

Permissions attributePermissions attributeEach ACL entry contains a set of permissions (actions) that describes the specific operations that are permitted on the object by the user or group. Permissions are context-sensitive. ACLentriespermissions attributeattributesACL permissionspermissionsattribute behaviorspermissionsprotected resources, controlThe behavior of certain permissions varies according to where the permissions are applied. For example, the modify permission (m action bit) behaves differently for protected resources in the /WebSEAL object space than for protected resources in the /Management object space.Permissions control protected resources in the following ways: Determine whether a user can do operations on protected objectsDetermine whether an administrator can change security policy on the object and any object that inherits permissionsDetermine whether Security Access Manager itself can delegate credentials for a userACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform.

Permissions attribute

Each ACL entry contains a set of permissions (actions) that describes the specific operations that are permitted on the object by the user or group. Permissions are context-sensitive.

The behavior of certain permissions varies according to where the permissions are applied. For example, the modify permission (m action bit) behaves differently for protected resources in the /WebSEAL object space than for protected resources in the /Management object space.

Permissions control protected resources in the following ways:

Determine whether a user can do operations on protected objects

Determine whether an administrator can change security policy on the object and any object that inherits permissions

Determine whether Security Access Manager itself can delegate credentials for a user

Parent topic: ACL entries

Action groups and actionsAction groups and actionsA domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit. actiongroupsoverviewactiondescriptionA domain administrator modifies the ACL entries in an ACL policy before or after the ACL policy is attached to an object. The actions that can be defined in an ACL entry must be previously defined in an action group.When Security Access Manager is installed, the primary action group is created. The primary action group is an action group that is created during the installation of an application or resource manage. As additional applications and resource managers are installed, additional action groups might be created.Independent of whether additional action groups are created during subsequent installations, a domain administrator can create additional action groups. A domain administrator can create custom permissions in a primary action group or a custom action group by defining new action bits.Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Default permissions in the primary action groupSecurity Access Manager defines permissions with action bits. When you install Security Access Manager, the default primary action group is created. This action group contains 17 permissions. Custom permissions in custom action groupsThe default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group.

Action groups and actions

A domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit.

A domain administrator modifies the ACL entries in an ACL policy before or after the ACL policy is attached to an object. The actions that can be defined in an ACL entry must be previously defined in an action group.

When Security Access Manager is installed, the primary action group is created. The primary action group is an action group that is created during the installation of an application or resource manage. As additional applications and resource managers are installed, additional action groups might be created.

Independent of whether additional action groups are created during subsequent installations, a domain administrator can create additional action groups. A domain administrator can create custom permissions in a primary action group or a custom action group by defining new action bits.

Default permissions in the primary action group
Security Access Manager defines permissions with action bits. When you install Security Access Manager, the default primary action group is created. This action group contains 17 permissions.

Custom permissions in custom action groups
The default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group.

Parent topic: Manage access control

Default permissions in the primary action groupDefault permissions in the primary action groupSecurity Access Manager defines permissions with action bits. When you install Security Access Manager, the default primary action group is created. This action group contains 17 permissions. ACLentriespermissions, defaultpermissionsdefaultsactiongroupspermissions in primary groupprimary group, default permissionsactionbitsWeb Portal Manager divides these permissions into the following categories.BaseGenericApplication Table 1 shows the action bit in the primaryaction group, a brief description of its associated permission, and its category as shown in Web Portal Manager Action bits and permissionsAction bitDescription of permissionWeb Portal Manager categoryaAttachBaseAAddBasebBrowseBaseBBypass protected object policy (POP)BasecControlBasedDeleteGenericgDelegationBaselList directoryApplicationmModifyGenericNCreateBaseRBypass ruleBaserReadApplicationsServer administrationGenerictTraceBaseTTraverseBasevViewGenericWPassword BasexExecuteApplicationSecurity Access Manager provides the capability to define additional permissions for use by resource managers. See Manage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. .Action groups and actionsA domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit.

Default permissions in the primary action group

Security Access Manager defines permissions with action bits. When you install Security Access Manager, the default primary action group is created. This action group contains 17 permissions.

Web Portal Manager divides these permissions into the following categories.

Base

Generic

Application

Table 168 shows the action bit in the primaryaction group, a brief description of its associated permission, and its category as shown in Web Portal Manager

Table 168. Action bits and permissions

Action bit | Description of permission | Web Portal Manager category
a | Attach | Base
A | Add | Base
b | Browse | Base
B | Bypass protected object policy (POP) | Base
c | Control | Base
d | Delete | Generic
g | Delegation | Base
l | List directory | Application
m | Modify | Generic
N | Create | Base
R | Bypass rule | Base
r | Read | Application
s | Server administration | Generic
t | Trace | Base
T | Traverse | Base
v | View | Generic
W | Password | Base
x | Execute | Application

Security Access Manager provides the capability to define additional permissions for use by resource managers. See Manage action groups.

Parent topic: Action groups and actions

Custom permissions in custom action groupsCustom permissions in custom action groupsThe default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group.ACLentriespermissions, custompermissionscustomactiongroupscustom For example, the read permission (action bit r) must be used only by an action that requires read-only access to a protected object.The authorization service does not know or care about the action. A custom action group can reuse an action bit from the primary action group to create an action in a custom action group for an unrelated operation. However, this situation might cause difficulty for a domain administrator who must be able to distinguish between two dissimilar uses of the same action bit.A custom action group might use an action that is not appropriately represented by a default permission. A domain administrator can define a new action bit for a permission that can be used and be recognized by the authorization service. See Manage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. .Action groups and actionsA domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit. When to create custom permissionsThis example demonstrates how a domain administrator can protect a printer from unauthorized use by creating a custom action. Representation of custom actions and action groupsYou must use a special syntax to identify custom action bits that belong to action groups other than the primary action group. The primary action group is the default action group.Scenario with custom actionsThe following scenarios show how to add custom actions to an ACL policy that is attached to a protected object.

Custom permissions in custom action groups

The default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group.

For example, the read permission (action bit r) must be used only by an action that requires read-only access to a protected object.

The authorization service does not know or care about the action. A custom action group can reuse an action bit from the primary action group to create an action in a custom action group for an unrelated operation. However, this situation might cause difficulty for a domain administrator who must be able to distinguish between two dissimilar uses of the same action bit.

A custom action group might use an action that is not appropriately represented by a default permission. A domain administrator can define a new action bit for a permission that can be used and be recognized by the authorization service. See Manage action groups.

When to create custom permissions
This example demonstrates how a domain administrator can protect a printer from unauthorized use by creating a custom action.

Representation of custom actions and action groups
You must use a special syntax to identify custom action bits that belong to action groups other than the primary action group. The primary action group is the default action group.

Scenario with custom actions
The following scenarios show how to add custom actions to an ACL policy that is attached to a protected object.

Parent topic: Action groups and actions

When to create custom permissionsWhen to create custom permissionsThis example demonstrates how a domain administrator can protect a printer from unauthorized use by creating a custom action. actiongroupswhen to createpermissionscustomexamplescustom permissionsFigure 1 shows an example of this requirement. A print spooling service is written with the authorization application programming interface (authorization API). The service can call the authorization service to do ACL checks on requests made to the printer.The default permissions do not include a permission for protecting printers. However, the printer can be protected by a custom action bit (p in this example).An ACL policy is attached to the printer object. If a user requests the use of this protected printer, that user must have an ACL entry that contains the p action bit. The authorization service returns a favorable response if the p action bit is present and the printing operation proceeds. If the authorization service returns an unfavorable response, the printing operation is not allowed to proceed. Permissions for a custom print spoolerPermissions for a custom print spoolerCustom permissions in custom action groupsThe default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group.

When to create custom permissions

This example demonstrates how a domain administrator can protect a printer from unauthorized use by creating a custom action.

Figure 84. shows an example of this requirement. A print spooling service is written with the authorization application programming interface (authorization API). The service can call the authorization service to do ACL checks on requests made to the printer.

The default permissions do not include a permission for protecting printers. However, the printer can be protected by a custom action bit (p in this example).

An ACL policy is attached to the printer object. If a user requests the use of this protected printer, that user must have an ACL entry that contains the p action bit. The authorization service returns a favorable response if the p action bit is present and the printing operation proceeds. If the authorization service returns an unfavorable response, the printing operation is not allowed to proceed.

Figure 84. Permissions for a custom print spooler

Parent topic: Custom permissions in custom action groups

Representation of custom actions and action groupsRepresentation of custom actions and action groupsYou must use a special syntax to identify custom action bits that belong to action groups other than the primary action group. The primary action group is the default action group.permissionsattribute, represented in ACL entriescustomaction groupsrepresentation in ACL entriesACLentriescustom permissionsactiongroupsrepresentation ofAs described in ACL entriesEach ACL policy can contain one or more ACL entries. Each ACL entry contains attributes that identify the user or group and the actions that this user or group can perform. , ACL entries contain an entry type, an ID for user and group types, and the set of permissions (action bits).Permissions that represent the action bits from multiple action groups are presented in the following format: bits[group_1]bits_1...[group_n]bits_nThe following example is an example of the permissions attribute: abgTr[groupA]Pq[groupB]Rsy[groupC]abThe previous permissions attribute has the following interpretation: The primary action group contains the a, b, g, T, and r action bits.The groupA action group contains the P and q action bits.The groupB action group contains the R, s, and y action bits.The groupC action group contains the a and b action bits.Action group groupC contains action bits that use the same letters for action bits as used in the primary action group. The action bits are associated with a specific action group (groupC). The a and b action bits have unique identities and can represent different permissions from those action bits in the primary action group.Custom permissions in custom action groupsThe default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group.

Representation of custom actions and action groups

You must use a special syntax to identify custom action bits that belong to action groups other than the primary action group. The primary action group is the default action group.

As described in ACL entries, ACL entries contain an entry type, an ID for user and group types, and the set of permissions (action bits).

Permissions that represent the action bits from multiple action groups are presented in the following format:

bits[group_1]bits_1...[group_n]bits_n

The following example is an example of the permissions attribute:

abgTr[groupA]Pq[groupB]Rsy[groupC]ab

The previous permissions attribute has the following interpretation:

The primary action group contains the a, b, g, T, and r action bits.

The groupA action group contains the P and q action bits.

The groupB action group contains the R, s, and y action bits.

The groupC action group contains the a and b action bits.

Action group groupC contains action bits that use the same letters for action bits as used in the primary action group. The action bits are associated with a specific action group (groupC). The a and b action bits have unique identities and can represent different permissions from those action bits in the primary action group.

Parent topic: Custom permissions in custom action groups

Scenario with custom actionsScenario with custom actionsThe following scenarios show how to add custom actions to an ACL policy that is attached to a protected object.customaction groupsscenarioactiongroupscustom scenarioTo show action groups, enter the following command: pdadmin sec_master> action group list primary test-groupTo list permissions in the test-group action group, enter the following command: pdadmin sec_master> action list test-group P Test-Action Special S Test-Action2 SpecialTo list ACL policies, enter the following command: pdadmin sec_master> acl list default-webseal default-root default-gso default-policy default-config test-acl default-replica default-managementTo show details about the ACL name test-acl, enter the following command: pdadmin sec_master> acl show test-acl ACL Name: test-acl Description: Entries: User sec_master Tcmdbva Group ivmgrd-servers Tl Any-other rTo add an ACL entry for the user named Kathy that contains permissions from the action groups named primary and test-group, enter the following command: pdadmin sec_master> acl modify test-acl set user kathy brT[test-group]PSTo validate this addition, enter the following command: pdadmin sec_master> acl show test-acl ACL Name: test-acl Description: Entries: User sec_master Tcmdbva Group ivmgrd-servers Tl Any-other r User kathy Tbr[test-group]PSCustom permissions in custom action groupsThe default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group.

Scenario with custom actions

The following scenarios show how to add custom actions to an ACL policy that is attached to a protected object.

To show action groups, enter the following command:

pdadmin sec_master> action group list

      primary
      test-group

To list permissions in the test-group action group, enter the following command:

pdadmin sec_master> action list test-group

      P  Test-Action   Special
      S  Test-Action2  Special

To list ACL policies, enter the following command:

pdadmin sec_master> acl list

      default-webseal
      default-root
      default-gso
      default-policy
      default-config
      test-acl
      default-replica
      default-management

To show details about the ACL name test-acl, enter the following command:

pdadmin sec_master> acl show test-acl

      ACL Name: test-acl
      Description:
      Entries:
          User sec_master Tcmdbva
          Group ivmgrd-servers Tl
          Any-other r

To add an ACL entry for the user named Kathy that contains permissions from the action groups named primary and test-group, enter the following command:

pdadmin sec_master> acl modify test-acl set user kathy brT[test-group]PS

To validate this addition, enter the following command:

pdadmin sec_master> acl show test-acl

      ACL Name: test-acl
      Description:
      Entries:
      User  sec_master  Tcmdbva
      Group  ivmgrd-servers  Tl
      Any-other  r
      User  kathy  Tbr[test-group]PS

Parent topic: Custom permissions in custom action groups

Manage ACL policiesManage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.access control listsACLpoliciesmanagement tasksIn the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page. There are no equivalent pdadmin commands for importing, exporting, or cloning ACL policies.In the following sections, instructions are provided for pdadmin. Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Create an ACL policyYou can create an ACL policy with the Web Portal Manager or pdadmin utility. Modify the description of an ACL policyYou can modify an ACL policy with Web Portal Manager or the pdadmin utility.List ACL policiesYou can list all ACL policies with Web Portal Manager or the pdadmin utility.View an ACL policyYou can view an ACL policy with Web Portal Manager or the pdadmin utility.Cloning an ACL policyYou can clone an ACL policy only with Web Portal Manager.Importing ACL policiesYou can import an ACL policy in the domain only with Web Portal Manager. Exporting all ACL policiesYou can export the definitions of all ACL policies in the domain only with Web Portal Manager. Exporting a single ACL policyYou can export the definition of a single ACL policy in the domain only with Web Portal Manager.Exporting multiple ACL policiesYou can export the definition of ACL policies in a domain from a list only with Web Portal Manager.Attach an ACL policy to an objectYou can attach an ACL to a protected object with Web Portal Manager or the pdadmin utility.Detach an ACL policy from an objectYou can detach an ACL from an object with Web Portal Manager or the pdadmin utility.Locate where an ACL policy is attachedYou can find where an ACL is attached with Web Portal Manager or the pdadmin utility.Delete an ACL policyYou can delete an ACL policy with Web Portal Manager or the pdadmin utility.

Manage ACL policies

You can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.

In the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Note: There are no equivalent pdadmin commands for importing, exporting, or cloning ACL policies.

In the following sections, instructions are provided for pdadmin.

Create an ACL policy
You can create an ACL policy with the Web Portal Manager or pdadmin utility.

Modify the description of an ACL policy
You can modify an ACL policy with Web Portal Manager or the pdadmin utility.

List ACL policies
You can list all ACL policies with Web Portal Manager or the pdadmin utility.

View an ACL policy
You can view an ACL policy with Web Portal Manager or the pdadmin utility.

Cloning an ACL policy
You can clone an ACL policy only with Web Portal Manager.

Importing ACL policies
You can import an ACL policy in the domain only with Web Portal Manager.

Exporting all ACL policies
You can export the definitions of all ACL policies in the domain only with Web Portal Manager.

Exporting a single ACL policy
You can export the definition of a single ACL policy in the domain only with Web Portal Manager.

Exporting multiple ACL policies
You can export the definition of ACL policies in a domain from a list only with Web Portal Manager.

Attach an ACL policy to an object
You can attach an ACL to a protected object with Web Portal Manager or the pdadmin utility.

Detach an ACL policy from an object
You can detach an ACL from an object with Web Portal Manager or the pdadmin utility.

Locate where an ACL policy is attached
You can find where an ACL is attached with Web Portal Manager or the pdadmin utility.

Delete an ACL policy
You can delete an ACL policy with Web Portal Manager or the pdadmin utility.

Parent topic: Manage access control

Create an ACL policyCreate an ACL policyYou can create an ACL policy with the Web Portal Manager or pdadmin utility. ACLpoliciescreatingAn ACL policy contains an entry with all the defined permissions for the logged in user who created the ACL policy. You must modify this ACL policy. Add ACL entries for additional users and groups that need to manage this ACL policy and the objects to which this ACL policy is attached.After adding the appropriate ACL entries, you might need to remove the ACL entry for the user who created the ACL policy.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Creating an ACL policy with Web Portal ManagerYou can create an ACL policy with Web Portal Manager.Creating an ACL policy with pdadminYou can create an ACL policy in the domain with the pdadmin utility.

Create an ACL policy

You can create an ACL policy with the Web Portal Manager or pdadmin utility.

An ACL policy contains an entry with all the defined permissions for the logged in user who created the ACL policy. You must modify this ACL policy. Add ACL entries for additional users and groups that need to manage this ACL policy and the objects to which this ACL policy is attached.

After adding the appropriate ACL entries, you might need to remove the ACL entry for the user who created the ACL policy.

Creating an ACL policy with Web Portal Manager
You can create an ACL policy with Web Portal Manager.

Creating an ACL policy with pdadmin
You can create an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage ACL policies

Creating an ACL policy with Web Portal ManagerCreating an ACL policy with Web Portal ManagerYou can create an ACL policy with Web Portal Manager.ACLpoliciescreating with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → Create ACL.In the ACL Name file, type the name of the ACL policy. For example, type Test-ACL.Optional: In the Description field, type a description of the ACL. For example, type Test of new ACL.Click Create. If successful, a link for this ACL policy is available when you list all ACL policies. You can now add and remove ACL entries from the ACL policy. See Create an ACL entryYou can create an ACL entry for an ACL policy with Web Portal Manager or the pdadmin utility. and Remove ACL entries from an ACL policyYou can remove ACL entries from an ACL policy with the Web Portal Manager or pdadmin utility. .Create an ACL policyYou can create an ACL policy with the Web Portal Manager or pdadmin utility.

Creating an ACL policy with Web Portal Manager

You can create an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → Create ACL.

In the ACL Name file, type the name of the ACL policy. For example, type Test-ACL.

Optional: In the Description field, type a description of the ACL. For example, type Test of new ACL.

Click Create.

Results

If successful, a link for this ACL policy is available when you list all ACL policies. You can now add and remove ACL entries from the ACL policy. See Create an ACL entry and Remove ACL entries from an ACL policy.

Parent topic: Create an ACL policy

Creating an ACL policy with pdadminCreating an ACL policy with pdadminYou can create an ACL policy in the domain with the pdadmin utility.commandsaclcreating policyLog on to the domain as the domain administrator.Use the acl create command.For example, to create an ACL policy named Test-ACL, enter the following command: pdadmin sec_master> acl create Test-ACLFor more information, see the IBM Security Access Manager for Web: Command Reference.Create an ACL policyYou can create an ACL policy with the Web Portal Manager or pdadmin utility.

Creating an ACL policy with pdadmin

You can create an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl create command.

Results

For example, to create an ACL policy named Test-ACL, enter the following command:

pdadmin sec_master> acl create Test-ACL

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create an ACL policy

Modify the description of an ACL policyModify the description of an ACL policyYou can modify an ACL policy with Web Portal Manager or the pdadmin utility.ACLpoliciesdescription, modifyingManage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Modifying the description of an ACL policy with Web Portal ManagerYou can modify the description of an ACL policy with Web Portal Manager.Modifying the description of an ACL policy with pdadminYou can modify the description of an ACL policy in the domain with the pdadmin utility.

Modify the description of an ACL policy

You can modify an ACL policy with Web Portal Manager or the pdadmin utility.

Modifying the description of an ACL policy with Web Portal Manager
You can modify the description of an ACL policy with Web Portal Manager.

Modifying the description of an ACL policy with pdadmin
You can modify the description of an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage ACL policies

Modifying the description of an ACL policy with Web Portal ManagerModifying the description of an ACL policy with Web Portal ManagerYou can modify the description of an ACL policy with Web Portal Manager.ACLpoliciesmodifying with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for the ACL policy that you want to change.From the ACL Properties page, modify the text in the Description field, as appropriate.Click Set.Modify the description of an ACL policyYou can modify an ACL policy with Web Portal Manager or the pdadmin utility.

Modifying the description of an ACL policy with Web Portal Manager

You can modify the description of an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for the ACL policy that you want to change.

From the ACL Properties page, modify the text in the Description field, as appropriate.

Click Set.

Parent topic: Modify the description of an ACL policy

Modifying the description of an ACL policy with pdadminModifying the description of an ACL policy with pdadminYou can modify the description of an ACL policy in the domain with the pdadmin utility.ACLcommandsmodifying ACL policy descriptioncommandsaclmodifying descriptionLog on to the domain as a domain administrator.Use the acl modify command with the description option.For example, to modify the description of the ACL named Test-ACL to be ACL for Test resources, enter the following command: pdadmin sec_master> acl modify Test-ACL description "ACL for Test resources"To show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl show Test-ACL ACL Name: Test-ACL Description: ACL for Test resources Entries: User maryj rSee the IBM Security Access Manager for Web: Command Reference.Modify the description of an ACL policyYou can modify an ACL policy with Web Portal Manager or the pdadmin utility.

Modifying the description of an ACL policy with pdadmin

You can modify the description of an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the acl modify command with the description option.

Example

For example, to modify the description of the ACL named Test-ACL to be ACL for Test resources, enter the following command:

pdadmin sec_master> acl modify Test-ACL description "ACL for Test resources"

To show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl show Test-ACL

          ACL Name:  Test-ACL
          Description: ACL for Test resources
          Entries:   User   maryj r

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Modify the description of an ACL policy

List ACL policiesList ACL policiesYou can list all ACL policies with Web Portal Manager or the pdadmin utility.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Listing ACL policies with Web Portal ManagerYou can list ACL policies in the domain with Web Portal Manager.Listing ACL policies with pdadminYou can list ACL policies in the domain with the pdadmin utility.

List ACL policies

You can list all ACL policies with Web Portal Manager or the pdadmin utility.

Listing ACL policies with Web Portal Manager
You can list ACL policies in the domain with Web Portal Manager.

Listing ACL policies with pdadmin
You can list ACL policies in the domain with the pdadmin utility.

Parent topic: Manage ACL policies

Listing ACL policies with Web Portal ManagerListing ACL policies with Web Portal ManagerYou can list ACL policies in the domain with Web Portal Manager.ACLpolicieslisting in domainpolicyACLlist in domainUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.The Manage ACLs page displays all the ACL policies in the domains.List ACL policiesYou can list all ACL policies with Web Portal Manager or the pdadmin utility.

Listing ACL policies with Web Portal Manager

You can list ACL policies in the domain with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

Results

The Manage ACLs page displays all the ACL policies in the domains.

Parent topic: List ACL policies

Listing ACL policies with pdadminListing ACL policies with pdadminYou can list ACL policies in the domain with the pdadmin utility.ACLcommandslisting ACL policiescommandsacllistLog on to the domain as a domain administrator.Use the acl list command.pdadmin sec_master> acl list See the IBM Security Access Manager for Web: Command Reference.List ACL policiesYou can list all ACL policies with Web Portal Manager or the pdadmin utility.

Listing ACL policies with pdadmin

You can list ACL policies in the domain with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the acl list command.

pdadmin sec_master> acl list

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: List ACL policies

View an ACL policyView an ACL policyYou can view an ACL policy with Web Portal Manager or the pdadmin utility.ACLpoliciesviewing Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Viewing an ACL policy with Web Portal ManagerYou can view an ACL policy with Web Portal Manager.Viewing an ACL policy with pdadminYou can view an ACL policy in the domain with the pdadmin utility.

View an ACL policy

You can view an ACL policy with Web Portal Manager or the pdadmin utility.

Viewing an ACL policy with Web Portal Manager
You can view an ACL policy with Web Portal Manager.

Viewing an ACL policy with pdadmin
You can view an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage ACL policies

Viewing an ACL policy with Web Portal ManagerViewing an ACL policy in the domain with Web Portal Manager.You can view an ACL policy with Web Portal Manager.ACLpoliciesviewing with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for the ACL policy that you want to view.View an ACL policyYou can view an ACL policy with Web Portal Manager or the pdadmin utility.

Viewing an ACL policy with Web Portal Manager

You can view an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for the ACL policy that you want to view.

Parent topic: View an ACL policy

Viewing an ACL policy with pdadminViewing an ACL policy with pdadminYou can view an ACL policy in the domain with the pdadmin utility.ACLcommandsviewing ACL entrycommandsaclviewing policyLog on to the domain as a domain administrator.Use the acl show command.pdadmin sec_master> acl show test-aclSee the IBM Security Access Manager for Web: Command Reference.View an ACL policyYou can view an ACL policy with Web Portal Manager or the pdadmin utility.

Viewing an ACL policy with pdadmin

You can view an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the acl show command.

pdadmin sec_master> acl show test-acl

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: View an ACL policy

Cloning an ACL policyCloning an ACL policyYou can clone an ACL policy only with Web Portal Manager.ACLpoliciescloningUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList ACL.From the Manage ACLs page, select the ACL policy you want to clone.From the ACL Properties page, click Clone.From the Clone ACL page, type an ACL Name. For example, type Test-ACL. The default value is the name of the original ACL with the prefix Clone.Optional: Type a Description of the ACL policy For example, type Clone of new ACL. The default value is the description of the original ACL.Click Clone. If successful, a link for the cloned ACL policy is created and a success message is displayed.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.

Cloning an ACL policy

You can clone an ACL policy only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List ACL.

From the Manage ACLs page, select the ACL policy you want to clone.

From the ACL Properties page, click Clone.

From the Clone ACL page, type an ACL Name. For example, type Test-ACL. The default value is the name of the original ACL with the prefix Clone.

Optional: Type a Description of the ACL policy For example, type Clone of new ACL. The default value is the description of the original ACL.

Click Clone.

Results

If successful, a link for the cloned ACL policy is created and a success message is displayed.

Parent topic: Manage ACL policies

Importing ACL policiesImporting ACL policiesYou can import an ACL policy in the domain only with Web Portal Manager. ACLpoliciesimportingUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLImport ACL.From the Import ACL page, complete one of the following steps:In the ACL File Name field, type the name of the ACL to import. For example, type aclImport.xml.Click Browse to select a file name.Optional: Select the Create Groups check box to create a group for ACL entries with the type Group.If you selected Create Groups, type the name of the registry container for the ACL in the Registry Container field. For example, type o=ibm,c=us.The file that contains the ACL might be encrypted when it was exported. In the Encryption String field, type the string that was used to encrypt the XML file.Click Import. If successful, the imported ACL policy is available when you list all the ACL policies.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.

Importing ACL policies

You can import an ACL policy in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > Import ACL.

From the Import ACL page, complete one of the following steps:

In the ACL File Name field, type the name of the ACL to import. For example, type aclImport.xml.

Click Browse to select a file name.

Optional: Select the Create Groups check box to create a group for ACL entries with the type Group.

If you selected Create Groups, type the name of the registry container for the ACL in the Registry Container field. For example, type o=ibm,c=us.

The file that contains the ACL might be encrypted when it was exported. In the Encryption String field, type the string that was used to encrypt the XML file.

Click Import.

Results

If successful, the imported ACL policy is available when you list all the ACL policies.

Parent topic: Manage ACL policies

Exporting all ACL policiesExporting all ACL policiesYou can export the definitions of all ACL policies in the domain only with Web Portal Manager. ACLpoliciesexportingUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLExport All ACLs to display the Export ACL to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported description. The default file name is aclExport.xml.If successful, the exported XML description file is available in the specified location.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.

Exporting all ACL policies

You can export the definitions of all ACL policies in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > Export All ACLs to display the Export ACL to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported description. The default file name is aclExport.xml.

Results

If successful, the exported XML description file is available in the specified location.

Parent topic: Manage ACL policies

Exporting a single ACL policyExporting a single ACL policyYou can export the definition of a single ACL policy in the domain only with Web Portal Manager.ACLpoliciesexportingUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList ACL.From the Manage ACLs page, select the ACL that you want to export.From the ACL Properties page, click Export to display the Export ACL to File page.Optional: In the Encryption String field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, type the string again in the Confirm Encryption String field.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported description. The default file name is aclExport.xml.If successful, the exported XML description file is available in the specified location.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.

Exporting a single ACL policy

You can export the definition of a single ACL policy in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List ACL.

From the Manage ACLs page, select the ACL that you want to export.

From the ACL Properties page, click Export to display the Export ACL to File page.

Optional: In the Encryption String field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, type the string again in the Confirm Encryption String field.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported description. The default file name is aclExport.xml.

Results

If successful, the exported XML description file is available in the specified location.

Parent topic: Manage ACL policies

Exporting multiple ACL policiesExporting multiple ACL policiesYou can export the definition of ACL policies in a domain from a list only with Web Portal Manager.ACLpoliciesexporting multiple Use Web Portal Manager to log on to the domain as a domain administrator.Click ACLList ACL.From the Manage ACLs page, select the ACLs that you want to export.Click Export to display the Export ACL to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported descriptions. The default file name is aclExport.xml.If successful, the exported XML description file is available in the specified location.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.

Exporting multiple ACL policies

You can export the definition of ACL policies in a domain from a list only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List ACL.

From the Manage ACLs page, select the ACLs that you want to export.

Click Export to display the Export ACL to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported descriptions. The default file name is aclExport.xml.

Results

If successful, the exported XML description file is available in the specified location.

Parent topic: Manage ACL policies

Attach an ACL policy to an objectAttach an ACL policy to an objectYou can attach an ACL to a protected object with Web Portal Manager or the pdadmin utility.ACLpoliciesattachingTo do this task, the administrator requires the attach (a) permission.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Attaching an ACL policy to an object with Web Portal ManagerYou can attach an ACL policy to a protected object with Web Portal Manager.Attaching an ACL policy to an object with pdadminYou can attach an ACL policy to a protected object in a domain with the pdadmin utility.

Attach an ACL policy to an object

You can attach an ACL to a protected object with Web Portal Manager or the pdadmin utility.

To do this task, the administrator requires the attach (a) permission.

Attaching an ACL policy to an object with Web Portal Manager
You can attach an ACL policy to a protected object with Web Portal Manager.

Attaching an ACL policy to an object with pdadmin
You can attach an ACL policy to a protected object in a domain with the pdadmin utility.

Parent topic: Manage ACL policies

Attaching an ACL policy to an object with Web Portal ManagerAttaching an ACL policy to an object with Web Portal ManagerYou can attach an ACL policy to a protected object with Web Portal Manager.Use Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for the name of the ACL that you want to attach to a protected object.From the ACL Properties page, click the Attach tab.Click Attach.From the Attach ACL page, type a Protected Object Path. For example, type /Management/test-object.Click Attach. If successful, the protected object is displayed as a protected object link for the named ACL.Attach an ACL policy to an objectYou can attach an ACL to a protected object with Web Portal Manager or the pdadmin utility.

Attaching an ACL policy to an object with Web Portal Manager

You can attach an ACL policy to a protected object with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for the name of the ACL that you want to attach to a protected object.

From the ACL Properties page, click the Attach tab.

Click Attach.

From the Attach ACL page, type a Protected Object Path. For example, type /Management/test-object.

Click Attach.

Results

If successful, the protected object is displayed as a protected object link for the named ACL.

Parent topic: Attach an ACL policy to an object

Attaching an ACL policy to an object with pdadminAttaching an ACL policy to an object with pdadminYou can attach an ACL policy to a protected object in a domain with the pdadmin utility.ACLcommandsattaching ACL policycommandsaclattaching policyLog on to the domain.Use the acl attach command.For example, to attach an ACL named Test-ACL to a protected object named /Management/test-object, enter the following command: pdadmin sec_master> acl attach /Management/test-object Test-ACLSee the IBM Security Access Manager for Web: Command Reference.Attach an ACL policy to an objectYou can attach an ACL to a protected object with Web Portal Manager or the pdadmin utility.

Attaching an ACL policy to an object with pdadmin

You can attach an ACL policy to a protected object in a domain with the pdadmin utility.

Procedure

Log on to the domain.

Use the acl attach command.

Results

For example, to attach an ACL named Test-ACL to a protected object named /Management/test-object, enter the following command:

pdadmin sec_master> acl attach /Management/test-object Test-ACL

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Attach an ACL policy to an object

Detach an ACL policy from an objectDetach an ACL policy from an objectYou can detach an ACL from an object with Web Portal Manager or the pdadmin utility.ACLpoliciesdetachingTo do this task, the administrator requires the attach (a) permission.Manage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Detaching an ACL policy from an object with Web Portal ManagerYou can detach an ACL policy from a protected object in the domain with Web Portal Manager.Detaching an ACL policy from an object with pdadminYou can detach an ACL policy from a protected object in the domain with the pdadmin utility.

Detach an ACL policy from an object

You can detach an ACL from an object with Web Portal Manager or the pdadmin utility.

To do this task, the administrator requires the attach (a) permission.

Detaching an ACL policy from an object with Web Portal Manager
You can detach an ACL policy from a protected object in the domain with Web Portal Manager.

Detaching an ACL policy from an object with pdadmin
You can detach an ACL policy from a protected object in the domain with the pdadmin utility.

Parent topic: Manage ACL policies

Detaching an ACL policy from an object with Web Portal ManagerDetaching an ACL policy from an object with Web Portal ManagerYou can detach an ACL policy from a protected object in the domain with Web Portal Manager.policydetaching with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for the ACL policy to detach.From the ACL Properties page, click the Attach tab.If the ACL is attached to protected objects, select one or more check boxes for the protected objects from which you want to detach the ACL.Click Detach. You are asked to confirm the detachment.Detach an ACL policy from an objectYou can detach an ACL from an object with Web Portal Manager or the pdadmin utility.

Detaching an ACL policy from an object with Web Portal Manager

You can detach an ACL policy from a protected object in the domain with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for the ACL policy to detach.

From the ACL Properties page, click the Attach tab.

If the ACL is attached to protected objects, select one or more check boxes for the protected objects from which you want to detach the ACL.

Click Detach. You are asked to confirm the detachment.

Parent topic: Detach an ACL policy from an object

Detaching an ACL policy from an object with pdadminDetaching an ACL policy from an object with pdadminYou can detach an ACL policy from a protected object in the domain with the pdadmin utility.ACLcommandsdetaching ACL policycommandsacldetaching policyLog on to the domain.Use the acl detach command.For example, to detach the ACL from the protected object named /Management/test-object, enter the following command: pdadmin sec_master> acl detach /Management/test-objectSee the IBM Security Access Manager for Web: Command Reference.Detach an ACL policy from an objectYou can detach an ACL from an object with Web Portal Manager or the pdadmin utility.

Detaching an ACL policy from an object with pdadmin

You can detach an ACL policy from a protected object in the domain with the pdadmin utility.

Procedure

Log on to the domain.

Use the acl detach command.

Example

For example, to detach the ACL from the protected object named /Management/test-object, enter the following command:

pdadmin sec_master> acl detach /Management/test-object

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Detach an ACL policy from an object

Locate where an ACL policy is attachedLocate where an ACL policy is attachedYou can find where an ACL is attached with Web Portal Manager or the pdadmin utility.ACLpoliciesfinding ACLpolicieslocatingManage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Locating where an ACL policy is attached with Web Portal ManagerYou can locate where an ACL policy is attached with Web Portal Manager.Locating where an ACL policy is attached with pdadminYou can locate where an ACL policy is attached in the domain with the pdadmin utility.

Locate where an ACL policy is attached

You can find where an ACL is attached with Web Portal Manager or the pdadmin utility.

Locating where an ACL policy is attached with Web Portal Manager
You can locate where an ACL policy is attached with Web Portal Manager.

Locating where an ACL policy is attached with pdadmin
You can locate where an ACL policy is attached in the domain with the pdadmin utility.

Parent topic: Manage ACL policies

Locating where an ACL policy is attached with Web Portal ManagerLocating where an ACL policy is attached with Web Portal ManagerYou can locate where an ACL policy is attached with Web Portal Manager.ACLpoliciesattachment location with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList ACL. A list of ACL names is displayed. From the Manage ACLs page, click the link for the name of the ACL.From the ACL Properties page, click the Attach tab.Locate where an ACL policy is attachedYou can find where an ACL is attached with Web Portal Manager or the pdadmin utility.

Locating where an ACL policy is attached with Web Portal Manager

You can locate where an ACL policy is attached with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List ACL. A list of ACL names is displayed.

From the Manage ACLs page, click the link for the name of the ACL.

From the ACL Properties page, click the Attach tab.

Parent topic: Locate where an ACL policy is attached

Locating where an ACL policy is attached with pdadminYou can locate where an ACL policy is attached in the domain with the pdadmin utility.ACLcommandslocating ACL policycommandsacllocating policyLog on to the domain as a domain administrator.Use the acl find command.For example, to find where the ACL named Test-ACL is attached, enter the following command: pdadmin sec_master> acl find Test-ACLSee the IBM Security Access Manager for Web: Command Reference.Locate where an ACL policy is attachedYou can find where an ACL is attached with Web Portal Manager or the pdadmin utility.

Locating where an ACL policy is attached with pdadmin

You can locate where an ACL policy is attached in the domain with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the acl find command.

Example

For example, to find where the ACL named Test-ACL is attached, enter the following command:

pdadmin sec_master> acl find Test-ACL

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Locate where an ACL policy is attached

Delete an ACL policyDelete an ACL policyYou can delete an ACL policy with Web Portal Manager or the pdadmin utility.ACLpoliciesdeletingManage ACL policiesYou can create and configure an ACL policy and attach it to objects in the protected object space. ACL policies are placed in the master policy database on a domain-by-domain basis. The master policy database is controlled by the policy server.Deleting an ACL policy with Web Portal ManagerYou can delete an ACL policy with Web Portal Manager.Deleting an ACL policy with pdadminYou can delete an ACL policy in the domain with the pdadmin utility.

Delete an ACL policy

You can delete an ACL policy with Web Portal Manager or the pdadmin utility.

Deleting an ACL policy with Web Portal Manager
You can delete an ACL policy with Web Portal Manager.

Deleting an ACL policy with pdadmin
You can delete an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage ACL policies

Deleting an ACL policy with Web Portal ManagerDeleting an ACL policy with Web Portal ManagerYou can delete an ACL policy with Web Portal Manager.ACLpoliciesdeleting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, select one or more check boxes of the ACL policies that you want to delete.Click Delete, and then confirm the deletion by clicking Delete again on the Delete confirmation page. If successful, the ACL policy is no longer included in the list of ACL policies in the Manage ACLs page.Delete an ACL policyYou can delete an ACL policy with Web Portal Manager or the pdadmin utility.

Deleting an ACL policy with Web Portal Manager

You can delete an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, select one or more check boxes of the ACL policies that you want to delete.

Click Delete, and then confirm the deletion by clicking Delete again on the Delete confirmation page.

Results

If successful, the ACL policy is no longer included in the list of ACL policies in the Manage ACLs page.

Parent topic: Delete an ACL policy

Deleting an ACL policy with pdadminYou can delete an ACL policy in the domain with the pdadmin utility.ACLcommandsdeleting ACL policycommandsacldeleting policyLog on to the domain as a domain administrator.Use the acl delete command.For example, to delete the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl delete Test-ACL See the IBM Security Access Manager for Web: Command Reference.Delete an ACL policyYou can delete an ACL policy with Web Portal Manager or the pdadmin utility.

Deleting an ACL policy with pdadmin

You can delete an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the acl delete command.

Results

For example, to delete the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl delete Test-ACL

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete an ACL policy

Manage ACL entries in ACL policiesManage ACL entries in ACL policiesYou can manage ACL entries in ACL policies with the Web Portal Manager or pdadmin utility.ACLentriesmanagingIn the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Create an ACL entryYou can create an ACL entry for an ACL policy with Web Portal Manager or the pdadmin utility.Modify permissions for an ACL entryYou can modify permissions for an ACL policy with the Web Portal Manager or pdadmin utility. Remove ACL entries from an ACL policyYou can remove ACL entries from an ACL policy with the Web Portal Manager or pdadmin utility.

Manage ACL entries in ACL policies

You can manage ACL entries in ACL policies with the Web Portal Manager or pdadmin utility.

In the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Create an ACL entry
You can create an ACL entry for an ACL policy with Web Portal Manager or the pdadmin utility.

Modify permissions for an ACL entry
You can modify permissions for an ACL policy with the Web Portal Manager or pdadmin utility.

Remove ACL entries from an ACL policy
You can remove ACL entries from an ACL policy with the Web Portal Manager or pdadmin utility.

Parent topic: Manage access control

Create an ACL entryCreate an ACL entryYou can create an ACL entry for an ACL policy with Web Portal Manager or the pdadmin utility.ACLentriesACL policy, creatingACLpoliciesACL entries, creatingusersACL entry to ACL policy, addinggroupsACL entry to ACL policy, addingany-otherACL entry to ACL policy, addingunauthenticatedACL entry to ACL policy, addingpermissionsACL entry to ACL policy, addingUse this procedure to create the ACL entry for any user, group, or special ACL entry type (any-other and unauthenticated).Manage ACL entries in ACL policiesYou can manage ACL entries in ACL policies with the Web Portal Manager or pdadmin utility.Creating an ACL entry with Web Portal ManagerYou can create an ACL entry with Web Portal Manager.Creating an ACL entry with pdadminYou can create an ACL entry for an ACL policy in the domain with the pdadmin utility.

Create an ACL entry

You can create an ACL entry for an ACL policy with Web Portal Manager or the pdadmin utility.

Use this procedure to create the ACL entry for any user, group, or special ACL entry type (any-other and unauthenticated).

Creating an ACL entry with Web Portal Manager
You can create an ACL entry with Web Portal Manager.

Creating an ACL entry with pdadmin
You can create an ACL entry for an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage ACL entries in ACL policies

Creating an ACL entry with Web Portal ManagerCreating an ACL entry with Web Portal ManagerYou can create an ACL entry with Web Portal Manager.ACLentriescreating with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for the ACL policy you want to change.From the ACL Properties page, click Create.Select the appropriate entry type: user, group, any-other, or unauthenticated.For user or group, specify the name.Select the check box for each permission to enable.Click Apply.Create an ACL entryYou can create an ACL entry for an ACL policy with Web Portal Manager or the pdadmin utility.

Creating an ACL entry with Web Portal Manager

You can create an ACL entry with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for the ACL policy you want to change.

From the ACL Properties page, click Create.

Select the appropriate entry type: user, group, any-other, or unauthenticated.

For user or group, specify the name.

Select the check box for each permission to enable.

Click Apply.

Parent topic: Create an ACL entry

Creating an ACL entry with pdadminCreating an ACL entry with pdadminYou can create an ACL entry for an ACL policy in the domain with the pdadmin utility.ACLcommandsACL entry, creatingcommandsaclcreating entryLog on to the domain as the domain administrator.Use the acl modify command with the set option.For example, to create the permissions for user maryj for the Test-ACL ACL policy to have r (read) action bit, enter the following command: pdadmin sec_master> acl modify Test-ACL set user maryj rTo show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl show Test-ACL ACL Name: Test-ACL Description: Entries: User maryj rSee the IBM Security Access Manager for Web: Command Reference.Create an ACL entryYou can create an ACL entry for an ACL policy with Web Portal Manager or the pdadmin utility.

Creating an ACL entry with pdadmin

You can create an ACL entry for an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl modify command with the set option.

Results

For example, to create the permissions for user maryj for the Test-ACL ACL policy to have r (read) action bit, enter the following command:

pdadmin sec_master> acl modify Test-ACL set user maryj r

To show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl show Test-ACL

          ACL Name:  Test-ACL
          Description:
          Entries:   User   maryj r

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create an ACL entry

Modify permissions for an ACL entryModify permissions for an ACL entryYou can modify permissions for an ACL policy with the Web Portal Manager or pdadmin utility. ACLentriespermissions, modifyingACLpoliciesentry permissions, modifyinguserspermissionsmodifyinggroupspermissionsmodifyingany-otherpermissions, modifyingunauthenticatedpermissions, modifyingpermissionsmodifyingUse this procedure to modify the permissions for any user, group, or special ACL entry type (any-other and unauthenticated).Manage ACL entries in ACL policiesYou can manage ACL entries in ACL policies with the Web Portal Manager or pdadmin utility.Modifying permissions for an ACL entry with Web Portal ManagerYou can modify permissions for an ACL entry using Web Portal Manager.Modifying permissions for an ACL entry with pdadminYou can modify permissions for an ACL entry in the domain with the pdadmin utility.

Modify permissions for an ACL entry

You can modify permissions for an ACL policy with the Web Portal Manager or pdadmin utility.

Use this procedure to modify the permissions for any user, group, or special ACL entry type (any-other and unauthenticated).

Modifying permissions for an ACL entry with Web Portal Manager
You can modify permissions for an ACL entry using Web Portal Manager.

Modifying permissions for an ACL entry with pdadmin
You can modify permissions for an ACL entry in the domain with the pdadmin utility.

Parent topic: Manage ACL entries in ACL policies

Modifying permissions for an ACL entry with Web Portal ManagerModifying permissions for an ACL entry with Web Portal ManagerYou can modify permissions for an ACL entry using Web Portal Manager.ACLentriesmodifying permissions with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList ACL.From the Manage ACLs page, click the link for the ACL policy you want to change.From the ACL Properties page, click the permission link.From the ACL Entry Properties page, select the check box for each permission to enable the permission. Clear the check box for each permission to disable the permission.Click Apply.Modify permissions for an ACL entryYou can modify permissions for an ACL policy with the Web Portal Manager or pdadmin utility.

Modifying permissions for an ACL entry with Web Portal Manager

You can modify permissions for an ACL entry using Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List ACL.

From the Manage ACLs page, click the link for the ACL policy you want to change.

From the ACL Properties page, click the permission link.

From the ACL Entry Properties page, select the check box for each permission to enable the permission. Clear the check box for each permission to disable the permission.

Click Apply.

Parent topic: Modify permissions for an ACL entry

Modifying permissions for an ACL entry with pdadminModifying permissions for an ACL entry with pdadminYou can modify permissions for an ACL entry in the domain with the pdadmin utility.ACLcommandsmodifying permissionscommandsaclmodifying permissionLog on to the domain as the domain administrator.Use the acl modify command with the set option.For example, to modify the permissions for user maryj for the Test-ACL ACL policy to have r (read) and w (write) action bits, enter the following command: pdadmin sec_master> acl modify Test-ACL set user maryj rwTo show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl show Test-ACL ACL Name: Test-ACL Description: Entries: User maryj rwSee the IBM Security Access Manager for Web: Command Reference.Modify permissions for an ACL entryYou can modify permissions for an ACL policy with the Web Portal Manager or pdadmin utility.

Modifying permissions for an ACL entry with pdadmin

You can modify permissions for an ACL entry in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl modify command with the set option.

Example

For example, to modify the permissions for user maryj for the Test-ACL ACL policy to have r (read) and w (write) action bits, enter the following command:

pdadmin sec_master> acl modify Test-ACL set user maryj rw

To show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl show Test-ACL

          ACL Name:  Test-ACL
          Description:
          Entries:   User   maryj rw

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Modify permissions for an ACL entry

Remove ACL entries from an ACL policyRemove ACL entries from an ACL policyYou can remove ACL entries from an ACL policy with the Web Portal Manager or pdadmin utility. ACLentriesremoving from ACL policyACLpoliciesremoving ACL entriesusersremoving ACL entries from ACL policiesgroupsremoving ACL entries from ACL policiesany-otherremoving ACL entries from ACL policiesunauthenticatedremoving ACL entries from ACL policiesUse this procedure to remove the ACL entry for any user, group, or special ACL entry type (any-other and unauthenticated).Manage ACL entries in ACL policiesYou can manage ACL entries in ACL policies with the Web Portal Manager or pdadmin utility.Removing ACL entries from an ACL policy with Web Portal ManagerYou can remove ACL entries from an ACL policy with Web Portal Manager.Removing ACL entries from an ACL policy with pdadminYou can remove ACL entries from an ACL policy in the domain with the pdadmin utility.

Remove ACL entries from an ACL policy

You can remove ACL entries from an ACL policy with the Web Portal Manager or pdadmin utility.

Use this procedure to remove the ACL entry for any user, group, or special ACL entry type (any-other and unauthenticated).

Removing ACL entries from an ACL policy with Web Portal Manager
You can remove ACL entries from an ACL policy with Web Portal Manager.

Removing ACL entries from an ACL policy with pdadmin
You can remove ACL entries from an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage ACL entries in ACL policies

Removing ACL entries from an ACL policy with Web Portal ManagerRemoving ACL entries from an ACL policy with Web Portal ManagerYou can remove ACL entries from an ACL policy with Web Portal Manager.ACLentriesremoving with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList ACL.From the Manage ACLs page, click the link for the ACL policy that you want to remove.From the ACL Properties page, select the user, group, or special ACL entry type to remove.Click Delete.Remove ACL entries from an ACL policyYou can remove ACL entries from an ACL policy with the Web Portal Manager or pdadmin utility.

Removing ACL entries from an ACL policy with Web Portal Manager

You can remove ACL entries from an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List ACL.

From the Manage ACLs page, click the link for the ACL policy that you want to remove.

From the ACL Properties page, select the user, group, or special ACL entry type to remove.

Click Delete.

Parent topic: Remove ACL entries from an ACL policy

Removing ACL entries from an ACL policy with pdadminRemoving ACL entries from an ACL policy with pdadminYou can remove ACL entries from an ACL policy in the domain with the pdadmin utility.ACLcommandsremoving ACL entriescommandsaclremoving entries from policyLog on to the domain as the domain administrator.Use the acl modify command with the remove option.For example, to remove the ACL entry for user maryj from the Test-ACL ACL policy, enter the following command: pdadmin sec_master> acl modify Test-ACL remove user maryjTo show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl show Test-ACL ACL Name: Test-ACL Description: Entries:See the IBM Security Access Manager for Web: Command Reference.Remove ACL entries from an ACL policyYou can remove ACL entries from an ACL policy with the Web Portal Manager or pdadmin utility.

Removing ACL entries from an ACL policy with pdadmin

You can remove ACL entries from an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl modify command with the remove option.

Example

For example, to remove the ACL entry for user maryj from the Test-ACL ACL policy, enter the following command:

pdadmin sec_master> acl modify Test-ACL remove user maryj

To show the modifications to the ACL, use the acl show command. For example, to show the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl show Test-ACL

          ACL Name:  Test-ACL
          Description:
          Entries:

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Remove ACL entries from an ACL policy

Manage extended attributes in ACL policiesManage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.ACLentriesmanaging extended attributes inFor online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Create extended attributes for an ACL policyYou can create an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.Modifying extended attributes from an ACL policy with pdadminYou can modify extended attributes from an ACL policy in the domain only with the pdadmin utility.List extended attributes of an ACL policyYou can list the extended attributes of an ACL policy with the pdadmin utility.View extended attributes of an ACL policyYou can view the extended attributes of an ACL policy with the Web Portal Manager or pdadmin utility.Delete extended attributes from an ACL policyYou can delete an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.Deleting extended attribute values from an ACL policy with pdadminYou can delete extended attribute values from an ACL policy only with the pdadmin utility.

Manage extended attributes in ACL policies

The following sections describe using pdadmin and Web Portal Manager.

For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Create extended attributes for an ACL policy
You can create an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Modifying extended attributes from an ACL policy with pdadmin
You can modify extended attributes from an ACL policy in the domain only with the pdadmin utility.

List extended attributes of an ACL policy
You can list the extended attributes of an ACL policy with the pdadmin utility.

View extended attributes of an ACL policy
You can view the extended attributes of an ACL policy with the Web Portal Manager or pdadmin utility.

Delete extended attributes from an ACL policy
You can delete an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Deleting extended attribute values from an ACL policy with pdadmin
You can delete extended attribute values from an ACL policy only with the pdadmin utility.

Parent topic: Manage access control

Create extended attributes for an ACL policyCreate extended attributes for an ACL policyCreate extended attributes for an ACL policyYou can create an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.ACLpoliciescreating extended attributesextended attributesACL policiescreatingManage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.Creating extended attributes for an ACL policy with Web Portal ManagerYou can create extended attributes for an ACL policy with Web Portal Manager.Creating extended attributes for an ACL policy with pdadminYou can create extended attributes for an ACL policy in the domain with the pdadmin utility.

Create extended attributes for an ACL policy

You can create an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Creating extended attributes for an ACL policy with Web Portal Manager
You can create extended attributes for an ACL policy with Web Portal Manager.

Creating extended attributes for an ACL policy with pdadmin
You can create extended attributes for an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage extended attributes in ACL policies

Creating extended attributes for an ACL policy with Web Portal ManagerCreating extended attributes for an ACL policy with Web Portal ManagerYou can create extended attributes for an ACL policy with Web Portal Manager.ACLcommandscreating extended attributescommandsaclcreating attributesUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList ACL.From the Manage ACLs page, click the link of the ACL policy for which you want to create an extended attribute.From the ACL Properties page, click the Extended Attribute tab.Click Create.From the Create Extended Attribute page, define the extended attribute:In the Attribute Name field, type the name of the attribute. This field is displayed only when the attribute type is Generic Attribute.In the Attribute Type field, select the type of attribute.In the Attribute Value field, select the value for the attribute, unless the selected attribute type is Generic Attribute. When you select the Generic Attribute attribute type, type the value for the attribute.Click Apply.Create extended attributes for an ACL policyYou can create an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Creating extended attributes for an ACL policy with Web Portal Manager

You can create extended attributes for an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List ACL.

From the Manage ACLs page, click the link of the ACL policy for which you want to create an extended attribute.

From the ACL Properties page, click the Extended Attribute tab.

Click Create.

From the Create Extended Attribute page, define the extended attribute:

In the Attribute Name field, type the name of the attribute. This field is displayed only when the attribute type is "Generic Attribute".

In the Attribute Type field, select the type of attribute.

In the Attribute Value field, select the value for the attribute, unless the selected attribute type is "Generic Attribute". When you select the "Generic Attribute" attribute type, type the value for the attribute.

Click Apply.

Parent topic: Create extended attributes for an ACL policy

Creating extended attributes for an ACL policy with pdadminCreating extended attributes for an ACL policy with pdadminYou can create extended attributes for an ACL policy in the domain with the pdadmin utility.ACLcommandscreating extended attributescommandsaclcreating attributesLog on to the domain as the domain administrator.Use the acl modify command with the set attribute option.For example, to create a generic attribute named Dept_No with a value of 445 and associate it with the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl modify Test-ACL set attribute Dept_No 445See the IBM Security Access Manager for Web: Command Reference.Create extended attributes for an ACL policyYou can create an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Creating extended attributes for an ACL policy with pdadmin

You can create extended attributes for an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl modify command with the set attribute option.

Example

For example, to create a generic attribute named Dept_No with a value of 445 and associate it with the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl modify Test-ACL set attribute Dept_No 445

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create extended attributes for an ACL policy

Modifying extended attributes from an ACL policy with pdadminModifying extended attributes from an ACL policy with pdadminYou can modify extended attributes from an ACL policy in the domain only with the pdadmin utility.ACLcommandsmodifying extended attributescommandsaclmodifying attributesWeb Portal Manager does not support modifying attributes. To use Web Portal Manager, an administrator needs to delete the attribute and then create the attribute again.Log on to the domain as the domain administrator.Use the acl modify command with the set attribute option.For example, to modify a generic attribute named Dept_No and add a value of 445 and associate it with the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl modify Test-ACL set attribute Dept_No 445See the IBM Security Access Manager for Web: Command Reference.Manage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.

Modifying extended attributes from an ACL policy with pdadmin

You can modify extended attributes from an ACL policy in the domain only with the pdadmin utility.

About this task

Web Portal Manager does not support modifying attributes. To use Web Portal Manager, an administrator needs to delete the attribute and then create the attribute again.

Procedure

Log on to the domain as the domain administrator.

Use the acl modify command with the set attribute option.

Example

For example, to modify a generic attribute named Dept_No and add a value of 445 and associate it with the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl modify Test-ACL set attribute Dept_No 445

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Manage extended attributes in ACL policies

List extended attributes of an ACL policyList extended attributes of an ACL policyYou can list the extended attributes of an ACL policy with the pdadmin utility.extended attributeslisting ACL policiesACLpolicieslisting extended attributesManage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.Listing extended attributes of an ACL policy with Web Portal ManagerYou can list all of the extended attributes of an ACL policy with Web Portal Manager.Listing extended attributes of an ACL policy with pdadminYou can list extended attributes of an ACL policy with the pdadmin utility.

List extended attributes of an ACL policy

You can list the extended attributes of an ACL policy with the pdadmin utility.

Listing extended attributes of an ACL policy with Web Portal Manager
You can list all of the extended attributes of an ACL policy with Web Portal Manager.

Listing extended attributes of an ACL policy with pdadmin
You can list extended attributes of an ACL policy with the pdadmin utility.

Parent topic: Manage extended attributes in ACL policies

Listing extended attributes of an ACL policy with Web Portal ManagerListing extended attributes of an ACL policy with Web Portal ManagerYou can list all of the extended attributes of an ACL policy with Web Portal Manager.ACLpolicieslist extended attributes with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for name of the ACL policy that you want to view.From the ACL Properties page, click the Extended Attribute tab. The ACL Properties page displays all the extended attributes for the selected ACL policy.List extended attributes of an ACL policyYou can list the extended attributes of an ACL policy with the pdadmin utility.

Listing extended attributes of an ACL policy with Web Portal Manager

You can list all of the extended attributes of an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for name of the ACL policy that you want to view.

From the ACL Properties page, click the Extended Attribute tab.

Results

The ACL Properties page displays all the extended attributes for the selected ACL policy.

Parent topic: List extended attributes of an ACL policy

Listing extended attributes of an ACL policy with pdadminListing extended attributes of an ACL policy with pdadminYou can list extended attributes of an ACL policy with the pdadmin utility.ACLcommandslisting attributecommandsacllist attributeLog on to the domain as the domain administrator.Use the acl list command with the attribute option.For example, to list the extended attributes of the ACL policy named pub_acl_3, enter the following command: pdadmin sec_master> acl list pub_acl_3 attributeSee the IBM Security Access Manager for Web: Command Reference.List extended attributes of an ACL policyYou can list the extended attributes of an ACL policy with the pdadmin utility.

Listing extended attributes of an ACL policy with pdadmin

You can list extended attributes of an ACL policy with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl list command with the attribute option.

Example

For example, to list the extended attributes of the ACL policy named pub_acl_3, enter the following command:

pdadmin sec_master> acl list pub_acl_3 attribute

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: List extended attributes of an ACL policy

View extended attributes of an ACL policyView extended attributes of an ACL policyYou can view the extended attributes of an ACL policy with the Web Portal Manager or pdadmin utility.ACLpoliciesviewing extended attributesextended attributesACL policiesviewingManage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.Viewing extended attributes of an ACL policy with Web Portal ManagerYou can view extended attributes of an ACL policy with Web Portal Manager.Viewing extended attributes of an ACL policy with pdadminYou can view extended attributes of an ACL policy in the domain with the pdadmin utility.

View extended attributes of an ACL policy

You can view the extended attributes of an ACL policy with the Web Portal Manager or pdadmin utility.

Viewing extended attributes of an ACL policy with Web Portal Manager
You can view extended attributes of an ACL policy with Web Portal Manager.

Viewing extended attributes of an ACL policy with pdadmin
You can view extended attributes of an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage extended attributes in ACL policies

Viewing extended attributes of an ACL policy with Web Portal ManagerViewing extended attributes of an ACL policy with Web Portal ManagerYou can view extended attributes of an ACL policy with Web Portal Manager.ACLpoliciesviewing extended attributes with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for the ACL policy that you want to view.Click the Extended Attribute tab.View extended attributes of an ACL policyYou can view the extended attributes of an ACL policy with the Web Portal Manager or pdadmin utility.

Viewing extended attributes of an ACL policy with Web Portal Manager

You can view extended attributes of an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for the ACL policy that you want to view.

Click the Extended Attribute tab.

Parent topic: View extended attributes of an ACL policy

Viewing extended attributes of an ACL policy with pdadminViewing extended attributes of an ACL policy with pdadminYou can view extended attributes of an ACL policy in the domain with the pdadmin utility.ACLcommandsviewing attributescommandsaclviewing attributesLog on to the domain as the domain administrator.Use the acl show command with the attribute option.For example, to show the myAttribute attribute of the test-acl ACL policy, enter the following command: pdadmin sec_master> acl show test-acl attribute myAttributeSee the IBM Security Access Manager for Web: Command Reference.View extended attributes of an ACL policyYou can view the extended attributes of an ACL policy with the Web Portal Manager or pdadmin utility.

Viewing extended attributes of an ACL policy with pdadmin

You can view extended attributes of an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl show command with the attribute option.

Example

For example, to show the myAttribute attribute of the test-acl ACL policy, enter the following command:

pdadmin sec_master> acl show test-acl attribute myAttribute

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: View extended attributes of an ACL policy

Delete extended attributes from an ACL policyDelete extended attributes from an ACL policyYou can delete an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.ACLpoliciesextended attributes, deletingextended attributesACL policiesdeletingManage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.Deleting extended attributes from an ACL policy with Web Portal ManagerYou can delete extended attributes from an ACL policy with Web Portal Manager.Deleting extended attributes from an ACL policy with pdadminYou can delete extended attributes from an ACL policy in the domain with the pdadmin utility.

Delete extended attributes from an ACL policy

You can delete an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Deleting extended attributes from an ACL policy with Web Portal Manager
You can delete extended attributes from an ACL policy with Web Portal Manager.

Deleting extended attributes from an ACL policy with pdadmin
You can delete extended attributes from an ACL policy in the domain with the pdadmin utility.

Parent topic: Manage extended attributes in ACL policies

Deleting extended attributes from an ACL policy with Web Portal ManagerDeleting extended attributes from an ACL policy with Web Portal ManagerYou can delete extended attributes from an ACL policy with Web Portal Manager.ACLpoliciesdeleting extended attributes with Web Portal ManagerpolicyACLdeleting extended attributes with Web Portal Managerextended attributesACL policiesdeleting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List ACL.From the Manage ACLs page, click the link for the ACL policy from which you want to delete extended attributes.From the ACL Properties page, click the Extended Attributes tab.Select the extended attributes.Click Delete.Delete extended attributes from an ACL policyYou can delete an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Deleting extended attributes from an ACL policy with Web Portal Manager

You can delete extended attributes from an ACL policy with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List ACL.

From the Manage ACLs page, click the link for the ACL policy from which you want to delete extended attributes.

From the ACL Properties page, click the Extended Attributes tab.

Select the extended attributes.

Click Delete.

Parent topic: Delete extended attributes from an ACL policy

Deleting extended attributes from an ACL policy with pdadminDeleting extended attributes from an ACL policy with pdadminYou can delete extended attributes from an ACL policy in the domain with the pdadmin utility.ACLcommandsdeleting attributescommandsacldeleting attributesLog on to the domain as the domain administrator.Use the acl modify command with the delete attribute option.For example, to delete the extended attributed named Dept_No from the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl modify Test-ACL delete attribute Dept_NoSee the IBM Security Access Manager for Web: Command Reference.Delete extended attributes from an ACL policyYou can delete an extended attribute for an ACL policy with the Web Portal Manager or pdadmin utility.

Deleting extended attributes from an ACL policy with pdadmin

You can delete extended attributes from an ACL policy in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl modify command with the delete attribute option.

Example

For example, to delete the extended attributed named Dept_No from the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl modify Test-ACL delete attribute Dept_No

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete extended attributes from an ACL policy

Deleting extended attribute values from an ACL policy with pdadminDeleting extended attribute values from an ACL policy with pdadminYou can delete extended attribute values from an ACL policy only with the pdadmin utility.ACLpoliciesdeleting extended attributes with pdadminpolicyACLdeleting extended attributes with pdadminextended attributesACL policiesdeleting with pdadminLog on to the domain as the domain administrator.Use the acl modify command with the delete attribute attribute_name attribute_value options.For example, to delete the value 445 from the extended attributed named Dept_No from the ACL named Test-ACL, enter the following command: pdadmin sec_master> acl modify Test-ACL delete attribute Dept_No 445Only the attribute value is deleted.See the IBM Security Access Manager for Web: Command Reference.Manage extended attributes in ACL policiesThe following sections describe using pdadmin and Web Portal Manager.

Deleting extended attribute values from an ACL policy with pdadmin

You can delete extended attribute values from an ACL policy only with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the acl modify command with the delete attribute attribute_name attribute_value options.

Example

For example, to delete the value 445 from the extended attributed named Dept_No from the ACL named Test-ACL, enter the following command:

pdadmin sec_master> acl modify Test-ACL delete attribute Dept_No 445

Only the attribute value is deleted.

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Manage extended attributes in ACL policies

Manage action groupsManage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. actiongroupsmanagement tasksactiongroupsguidelinesSecurity Access Manager provides 17 predefined permissions for immediate use. These permissions are stored in the predefined action group named primary.Each permission is associated with an action bit. These predefined permissions are described in Default permissions in the primary action groupSecurity Access Manager defines permissions with action bits. When you install Security Access Manager, the default primary action group is created. This action group contains 17 permissions. .Security Access Manager can create resource manager-specific permissions. For example, you can define the Enqueue permission to grant access to put messages in a message queue.Security Access Manager supports a total of 32 action groups, including the primary action group.When you define an action group, the following guidelines and limitations apply: Each action group can hold up to 32 action bits (including the action bits for the 17 predefined permissions).An action bit is made up of a letter: a-z, A-Z.Each action bit character can be used only one time in an action group.You can reuse the same action bit in other action groups.Manage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Create action groupsYou can create an action group with the Web Portal Manager or pdadmin utility.List action groupsYou can list all action groups with the Web Portal Manager or pdadmin utility.Delete an action groupYou can delete an action group with the Web Portal Manager or pdadmin utility.

Manage action groups

Permissions grant access to do a specific operation on resources that are protected by Security Access Manager.

Security Access Manager provides 17 predefined permissions for immediate use. These permissions are stored in the predefined action group named primary.

Each permission is associated with an action bit. These predefined permissions are described in Default permissions in the primary action group.

Security Access Manager can create resource manager-specific permissions. For example, you can define the Enqueue permission to grant access to put messages in a message queue.

Security Access Manager supports a total of 32 action groups, including the primary action group.

When you define an action group, the following guidelines and limitations apply:

Each action group can hold up to 32 action bits (including the action bits for the 17 predefined permissions).

An action bit is made up of a letter: a-z, A-Z.

Each action bit character can be used only one time in an action group.

You can reuse the same action bit in other action groups.

Create action groups
You can create an action group with the Web Portal Manager or pdadmin utility.

List action groups
You can list all action groups with the Web Portal Manager or pdadmin utility.

Delete an action group
You can delete an action group with the Web Portal Manager or pdadmin utility.

Parent topic: Manage access control

Create action groupsCreate action groupsYou can create an action group with the Web Portal Manager or pdadmin utility.actiongroupscreatingManage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. Creating action groups with Web Portal ManagerYou can create action groups with Web Portal Manager.Creating action groups with pdadminYou can create action groups in the domain with the pdadmin utility.

Create action groups

You can create an action group with the Web Portal Manager or pdadmin utility.

Creating action groups with Web Portal Manager
You can create action groups with Web Portal Manager.

Creating action groups with pdadmin
You can create action groups in the domain with the pdadmin utility.

Parent topic: Manage action groups

Creating action groups with Web Portal ManagerCreating action groups with Web Portal ManagerYou can create action groups with Web Portal Manager.actiongroupscreatingUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → Create Action Group.Type the new Action Group Name. For example, type test-group.Click Create. If successful, a message is displayed when the action group is created.Create action groupsYou can create an action group with the Web Portal Manager or pdadmin utility.

Creating action groups with Web Portal Manager

You can create action groups with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → Create Action Group.

Type the new Action Group Name. For example, type test-group.

Click Create.

Results

If successful, a message is displayed when the action group is created.

Parent topic: Create action groups

Creating action groups with pdadminCreating action groups with pdadminYou can create action groups in the domain with the pdadmin utility.commandsaction groups creatingaction groupscreate commandactioncommandsgroup createLog on to the domain as the domain administrator.Use the action group create command.For example, to create an action group named test-group, enter the following command: pdadmin sec_master> action group create test-groupThe primary action group always appears in a group listing and cannot be deleted.You must have an entry in an ACL on the /Management/ACL object with the modify (m) action to create action groups and the delete (d) permission to delete action groups.See the IBM Security Access Manager for Web: Command Reference.Create action groupsYou can create an action group with the Web Portal Manager or pdadmin utility.

Creating action groups with pdadmin

You can create action groups in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the action group create command.

Example

For example, to create an action group named test-group, enter the following command:

pdadmin sec_master> action group create test-group

The primary action group always appears in a group listing and cannot be deleted.

You must have an entry in an ACL on the /Management/ACL object with the modify (m) action to create action groups and the delete (d) permission to delete action groups.

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create action groups

List action groupsList action groupsYou can list all action groups with the Web Portal Manager or pdadmin utility.actiongroupslisting allManage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. Listing action groups with Web Portal ManagerYou can list all action groups with Web Portal Manager.Listing action groups with pdadminYou can list all action groups in the domain with the pdadmin utility.

List action groups

You can list all action groups with the Web Portal Manager or pdadmin utility.

Listing action groups with Web Portal Manager
You can list all action groups with Web Portal Manager.

Listing action groups with pdadmin
You can list all action groups in the domain with the pdadmin utility.

Parent topic: Manage action groups

Listing action groups with Web Portal ManagerListing action groups with Web Portal ManagerYou can list all action groups with Web Portal Manager.action groupslisting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List Action Groups.The Manage Action Groups page displays a list of all action groups in the domain.List action groupsYou can list all action groups with the Web Portal Manager or pdadmin utility.

Listing action groups with Web Portal Manager

You can list all action groups with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List Action Groups.

Results

The Manage Action Groups page displays a list of all action groups in the domain.

Parent topic: List action groups

Listing action groups with pdadminListing action groups with pdadminYou can list all action groups in the domain with the pdadmin utility.commandsaction listing group action groupslist commandactioncommandsgroup listLog on to the domain as the domain administrator.Use the action group list command.For example, to list all action groups, enter the following command: pdadmin sec_master> action group list See the IBM Security Access Manager for Web: Command Reference.List action groupsYou can list all action groups with the Web Portal Manager or pdadmin utility.

Listing action groups with pdadmin

You can list all action groups in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the action group list command.

Example

For example, to list all action groups, enter the following command:

pdadmin sec_master> action group list

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: List action groups

Delete an action groupDelete an action groupYou can delete an action group with the Web Portal Manager or pdadmin utility.actiongroupsdeletingManage action groupsPermissions grant access to do a specific operation on resources that are protected by Security Access Manager. Deleting an action group with Web Portal ManagerYou can delete an action group with Web Portal Manager.Deleting an action group with pdadminYou can delete an action group with the pdadmin utility.

Delete an action group

You can delete an action group with the Web Portal Manager or pdadmin utility.

Deleting an action group with Web Portal Manager
You can delete an action group with Web Portal Manager.

Deleting an action group with pdadmin
You can delete an action group with the pdadmin utility.

Parent topic: Manage action groups

Deleting an action group with Web Portal ManagerDeleting an action group with Web Portal ManagerYou can delete an action group with Web Portal Manager.action groupsdeleting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List Action Groups.From the Manage Action Groups page, select one or more check boxes for the action groups that you want to delete.Click Delete. Confirm the deletion by clicking Delete again on the Delete Action Groups page.Delete an action groupYou can delete an action group with the Web Portal Manager or pdadmin utility.

Deleting an action group with Web Portal Manager

You can delete an action group with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List Action Groups.

From the Manage Action Groups page, select one or more check boxes for the action groups that you want to delete.

Click Delete.

Confirm the deletion by clicking Delete again on the Delete Action Groups page.

Parent topic: Delete an action group

Deleting an action group with pdadminDeleting an action group with pdadminYou can delete an action group with the pdadmin utility.commandsaction groupsdeletingaction groupsdelete commandactioncommandsgroup deleteLog on to the domain as a domain administrator.Use the action group delete command.For example, to delete the action group named test-group, enter the following command: pdadmin sec_master> action group delete test-groupSee the IBM Security Access Manager for Web: Command Reference.Delete an action groupYou can delete an action group with the Web Portal Manager or pdadmin utility.

Deleting an action group with pdadmin

You can delete an action group with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the action group delete command.

Example

For example, to delete the action group named test-group, enter the following command:

pdadmin sec_master> action group delete test-group

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete an action group

Manage actionsManage actionsYou can manage actions with the Web Portal Manager or pdadmin utility.actionmanaging extended attributes inManage access controlA domain administrator can use access control list (ACL) policies to control access to objects.Create actions in an action groupYou can create an action in an action group with the Web Portal Manager or pdadmin utility.List actions in an action groupYou can list all actions in an action group with the Web Portal Manager or pdadmin utility.Delete actions from an action groupYou can delete an action from an action group with the Web Portal Manager or pdadmin utility.

Manage actions

You can manage actions with the Web Portal Manager or pdadmin utility.

Create actions in an action group
You can create an action in an action group with the Web Portal Manager or pdadmin utility.

List actions in an action group
You can list all actions in an action group with the Web Portal Manager or pdadmin utility.

Delete actions from an action group
You can delete an action from an action group with the Web Portal Manager or pdadmin utility.

Parent topic: Manage access control

Create actions in an action groupCreate actions in an action groupYou can create an action in an action group with the Web Portal Manager or pdadmin utility.actiongroupsactions, creatingactiongroupspermissions, creatingpermissionsactions, creatingManage actionsYou can manage actions with the Web Portal Manager or pdadmin utility.Creating actions in an action group with Web Portal ManagerYou can create actions in an action group with Web Portal Manager.Creating actions in an action group with pdadminYou can create actions in an action group with the pdadmin utility.

Create actions in an action group

You can create an action in an action group with the Web Portal Manager or pdadmin utility.

Creating actions in an action group with Web Portal Manager
You can create actions in an action group with Web Portal Manager.

Creating actions in an action group with pdadmin
You can create actions in an action group with the pdadmin utility.

Parent topic: Manage actions

Creating actions in an action group with Web Portal ManagerCreating actions in an action group with Web Portal ManagerYou can create actions in an action group with Web Portal Manager.action groupsactions, creatingactioncreatingUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList Action Groups.From the Manage Action Group page, click the link for the action group name in which to create the permission. For example, select the Test-Group link.From the Action Group Properties page, click Create to display the Create Action page. The Action Group Name is automatically completed.Type a single character Action Name. For example, type x.In the Action Label field, type a short description of the permission. For example, type Execute.In the Action Type field, type a description of the permission, such as the application to which the permission is specific. For example, type WebSEAL.Click Create. If successful, a message is displayed when the permission is created.Create actions in an action groupYou can create an action in an action group with the Web Portal Manager or pdadmin utility.

Creating actions in an action group with Web Portal Manager

You can create actions in an action group with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List Action Groups.

From the Manage Action Group page, click the link for the action group name in which to create the permission. For example, select the Test-Group link.

From the Action Group Properties page, click Create to display the Create Action page. The Action Group Name is automatically completed.

Type a single character Action Name. For example, type x.

In the Action Label field, type a short description of the permission. For example, type Execute.

In the Action Type field, type a description of the permission, such as the application to which the permission is specific. For example, type WebSEAL.

Click Create.

Results

If successful, a message is displayed when the permission is created.

Parent topic: Create actions in an action group

Creating actions in an action group with pdadminCreating actions in an action group with pdadminYou can create actions in an action group with the pdadmin utility.commandsactionsin action group, creatingactioncommandscreateactioncommandsaction createLog on to the domain as the domain administrator.Use the action create command.For example, to create an x action bit in the Test-Group action group, enter the following command: pdadmin sec_master> action create x Execute WebSEAL Test-GroupSee the IBM Security Access Manager for Web: Command Reference.Create actions in an action groupYou can create an action in an action group with the Web Portal Manager or pdadmin utility.

Creating actions in an action group with pdadmin

You can create actions in an action group with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the action create command.

Example

For example, to create an x action bit in the Test-Group action group, enter the following command:

pdadmin sec_master> action create x Execute WebSEAL Test-Group

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create actions in an action group

List actions in an action groupList actions in an action groupYou can list all actions in an action group with the Web Portal Manager or pdadmin utility.actioncommandslistingactiongroupspermissions, listingpermissionslisting for action groupManage actionsYou can manage actions with the Web Portal Manager or pdadmin utility.Listing actions in an action group with Web Portal ManagerYou can list actions in an action group by using Web Portal Manager.Listing actions in an action group with pdadminYou can list the actions in an action group with the pdadmin utility.

List actions in an action group

You can list all actions in an action group with the Web Portal Manager or pdadmin utility.

Listing actions in an action group with Web Portal Manager
You can list actions in an action group by using Web Portal Manager.

Listing actions in an action group with pdadmin
You can list the actions in an action group with the pdadmin utility.

Parent topic: Manage actions

Listing actions in an action group with Web Portal ManagerListing actions in an action group with Web Portal ManagerYou can list actions in an action group by using Web Portal Manager.actionlistingUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List Action Groups.From the Manage Action Group page, click the link for the action group name.List actions in an action groupYou can list all actions in an action group with the Web Portal Manager or pdadmin utility.

Listing actions in an action group with Web Portal Manager

You can list actions in an action group by using Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List Action Groups.

From the Manage Action Group page, click the link for the action group name.

Parent topic: List actions in an action group

Listing actions in an action group with pdadminListing actions in an action group with pdadminYou can list the actions in an action group with the pdadmin utility.commandsaction listingactionlist commandactioncommandslistingLog on to the domain as the domain administrator.Use the action list command.For example, to list the actions in the Test-Group action group, enter the following command: pdadmin sec_master> action list Test-GroupSee the IBM Security Access Manager for Web: Command Reference.List actions in an action groupYou can list all actions in an action group with the Web Portal Manager or pdadmin utility.

Listing actions in an action group with pdadmin

You can list the actions in an action group with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the action list command.

Example

For example, to list the actions in the Test-Group action group, enter the following command:

pdadmin sec_master> action list Test-Group

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: List actions in an action group

Delete actions from an action groupDelete actions from an action groupYou can delete an action from an action group with the Web Portal Manager or pdadmin utility.actioncommandsdeletingaction groupsdeleting permissionspermissionsdeleting from action groupManage actionsYou can manage actions with the Web Portal Manager or pdadmin utility.Deleting actions from an action group with Web Portal ManagerYou can delete actions from an action group with Web Portal Manager.Deleting actions from an action group with pdadminYou can delete actions from an action group with the pdadmin utility.

Delete actions from an action group

You can delete an action from an action group with the Web Portal Manager or pdadmin utility.

Deleting actions from an action group with Web Portal Manager
You can delete actions from an action group with Web Portal Manager.

Deleting actions from an action group with pdadmin
You can delete actions from an action group with the pdadmin utility.

Parent topic: Manage actions

Deleting actions from an action group with Web Portal ManagerDeleting actions from an action group with Web Portal ManagerYou can delete actions from an action group with Web Portal Manager.actiondeleting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACL → List Action Groups.From the Manage Action Group page, click the link for the action group name that contains the permission to be deleted.From the Action Group Properties page, select the permission to delete.Click Delete.Confirm the deletion by clicking Delete on the Delete Action page.Delete actions from an action groupYou can delete an action from an action group with the Web Portal Manager or pdadmin utility.

Deleting actions from an action group with Web Portal Manager

You can delete actions from an action group with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL → List Action Groups.

From the Manage Action Group page, click the link for the action group name that contains the permission to be deleted.

From the Action Group Properties page, select the permission to delete.

Click Delete.

Confirm the deletion by clicking Delete on the Delete Action page.

Parent topic: Delete actions from an action group

Deleting actions from an action group with pdadminDeleting actions from an action group with pdadminYou can delete actions from an action group with the pdadmin utility.commandsaction deleteactioncommandsaction delete actioncommandsdeletingLog on to the domain as the domain administrator.Use the action delete command.For example, to delete the x action bit from the Test-Group action group, enter the following command: pdadmin sec_master> action delete x Test-GroupSee the IBM Security Access Manager for Web: Command Reference.Delete actions from an action groupYou can delete an action from an action group with the Web Portal Manager or pdadmin utility.

Deleting actions from an action group with pdadmin

You can delete actions from an action group with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the action delete command.

Example

For example, to delete the x action bit from the Test-Group action group, enter the following command:

pdadmin sec_master> action delete x Test-Group

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete actions from an action group

Protected object policy managementProtected object policy managementThe access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service. protected objectpolicyPOPPOPintroducingPOPattributesattributesPOPIt is the responsibility of Security Access Manager and the resource manager to enforce the POP conditions.Table 1 lists the available attributes for a POP that are provided by Security Access Manager. POP attributes that Security Access Manager providesPOP attributeDescriptionNameSpecifies the name of the policy. This attribute relates to the pop-name variable in the pop command documentation.DescriptionSpecifies the descriptive text for the policy. This attribute occurs in the pop show command.Warning modeProvides administrators a means to test ACLs, POPs, and authorization rules. Warning mode provides a way to test the security policy before it is made active.Audit levelSpecifies the type of auditing: all, none, successful access, denied access, or errors. Audit level informs the authorizations service that extra services are required when permitting access to the object.Time-of-day AccessDay and time restrictions for successful access to the protected object. Time-of-day places restrictions on the access to the object.IP endpoint authorization method policySpecifies authorization requirements for access from members of external networks. The IP endpoint authentication method policy places restrictions on the access to the object.EAS trigger attributes Specifies an External Authorization Service (EAS) plug-in that is started to make an authorization decision with the externalized policy logic of the customer.Quality of ProtectionSpecifies the degree of data protection: none, integrity, or privacy. Quality of Protection informs the authorizations service that extra services are required when permitting access to the object.Although Security Access Manager provides these POP attributes, it enforces only the following attributes: NameDescriptionWarning modeAudit levelTime-of-day AccessEach resource manager or plug-in can optionally enforce one or more of the following attributes: IP endpoint authorization method policyEAS trigger attributesQuality of ProtectionFor Security Access Manager IP address support: You can grant access to a protected resource based on the IP address that is used by the identity. For example, only users from IP address 9.18.n.n are allowed to access the protected resource.You can define that an additional authentication level is required to access this protected resource based on the IP address that is used by the identity. The step-up level authentication is described in Configure levels for step-up authenticationThe first step in configuring authentication-specific access is to configure the supported authentication methods and determine the order in which these authentication methods must be considered stronger. and the IBM Security Access Manager for Web: WebSEAL Administration Guide.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Network-based authorization algorithmThe authorization server uses an algorithm to process the conditions in a POP. Network-based authorization policyUse the network-based authorization policy to control access to objects based on the IP address of the user. Configure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.

Protected object policy management

The access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service.

It is the responsibility of Security Access Manager and the resource manager to enforce the POP conditions.

Table 169 lists the available attributes for a POP that are provided by Security Access Manager.

Table 169. POP attributes that Security Access Manager provides

POP attribute | Description
Name | Specifies the name of the policy. This attribute relates to the pop-name variable in the pop command documentation.
Description | Specifies the descriptive text for the policy. This attribute occurs in the pop show command.
Warning mode | Provides administrators a means to test ACLs, POPs, and authorization rules. Warning mode provides a way to test the security policy before it is made active.
Audit level | Specifies the type of auditing: all, none, successful access, denied access, or errors. Audit level informs the authorizations service that extra services are required when permitting access to the object.
Time-of-day Access | Day and time restrictions for successful access to the protected object. Time-of-day places restrictions on the access to the object.
IP endpoint authorization method policy | Specifies authorization requirements for access from members of external networks. The IP endpoint authentication method policy places restrictions on the access to the object.
EAS trigger attributes | Specifies an External Authorization Service (EAS) plug-in that is started to make an authorization decision with the externalized policy logic of the customer.
Quality of Protection | Specifies the degree of data protection: none, integrity, or privacy. Quality of Protection informs the authorizations service that extra services are required when permitting access to the object.

Although Security Access Manager provides these POP attributes, it enforces only the following attributes:

Name

Description

Warning mode

Audit level

Time-of-day Access

Each resource manager or plug-in can optionally enforce one or more of the following attributes:

IP endpoint authorization method policy

EAS trigger attributes

Quality of Protection

For Security Access Manager IP address support:

You can grant access to a protected resource based on the IP address that is used by the identity. For example, only users from IP address 9.18.n.n are allowed to access the protected resource.

You can define that an additional authentication level is required to access this protected resource based on the IP address that is used by the identity. The step-up level authentication is described in Configure levels for step-up authentication and the IBM Security Access Manager for Web: WebSEAL Administration Guide.

Manage protected object policies
You create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.

Network-based authorization algorithm
The authorization server uses an algorithm to process the conditions in a POP.

Network-based authorization policy
Use the network-based authorization policy to control access to objects based on the IP address of the user.

Configure POP attributes
POP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.

Step-up authentication
You can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.

Parent topic: Access Manager Platform and Supporting Components administration

Manage protected object policiesManage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.POPmanagement tasksPOPattributesmanagement tasksIn the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page. There are no equivalent pdadmin commands for importing, exporting, or cloning POPs.Protected object policy managementThe access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service. Create a POPYou can create a POP with the Web Portal Manager or pdadmin utility.Modify a POPYou can modify a POP with the Web Portal Manager or pdadmin utility.List POPsYou can list all POPs with the Web Portal Manager or pdadmin utility.View a POPYou can view a POP with the Web Portal Manager or pdadmin utility.Cloning a POPYou can clone a POP only with the Web Portal Manager. Importing POPsYou can import a POP in the domain only with Web Portal Manager. Exporting all POPsYou can export all POPs in the domain only with Web Portal Manager. Exporting a single POPYou can export a single POP in the domain only with Web Portal Manager. Exporting multiple POPsYou can export POPs in the domain from a list only with Web Portal Manager. Attach a POP to an objectYou can attach a POP to an object with the Web Portal Manager or pdadmin utility.Detach a POP from an objectYou can detach a POP from a protected object with the Web Portal Manager or pdadmin utility.Locate where a POP is attachedYou can locate where a POP is attached with the Web Portal Manager orpdadmin utility.Delete a POPYou can delete a POP with the Web Portal Manager or pdadmin utility.

Manage protected object policies

You create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.

In the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Note: There are no equivalent pdadmin commands for importing, exporting, or cloning POPs.

Create a POP
You can create a POP with the Web Portal Manager or pdadmin utility.

Modify a POP
You can modify a POP with the Web Portal Manager or pdadmin utility.

List POPs
You can list all POPs with the Web Portal Manager or pdadmin utility.

View a POP
You can view a POP with the Web Portal Manager or pdadmin utility.

Cloning a POP
You can clone a POP only with the Web Portal Manager.

Importing POPs
You can import a POP in the domain only with Web Portal Manager.

Exporting all POPs
You can export all POPs in the domain only with Web Portal Manager.

Exporting a single POP
You can export a single POP in the domain only with Web Portal Manager.

Exporting multiple POPs
You can export POPs in the domain from a list only with Web Portal Manager.

Attach a POP to an object
You can attach a POP to an object with the Web Portal Manager or pdadmin utility.

Detach a POP from an object
You can detach a POP from a protected object with the Web Portal Manager or pdadmin utility.

Locate where a POP is attached
You can locate where a POP is attached with the Web Portal Manager orpdadmin utility.

Delete a POP
You can delete a POP with the Web Portal Manager or pdadmin utility.

Parent topic: Protected object policy management

Create a POPCreate a POPYou can create a POP with the Web Portal Manager or pdadmin utility. After creating a POP, you can attach it to an object. For information about attaching a POP, see Attach a POP to an objectYou can attach a POP to an object with the Web Portal Manager or pdadmin utility..Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Creating a POP with Web Portal ManagerYou can create a POP with Web Portal Manager.Creating a POP with pdadminYou can create a POP in the domain with the pdadmin utility.

Create a POP

You can create a POP with the Web Portal Manager or pdadmin utility.

After creating a POP, you can attach it to an object. For information about attaching a POP, see Attach a POP to an object.

Creating a POP with Web Portal Manager
You can create a POP with Web Portal Manager.

Creating a POP with pdadmin
You can create a POP in the domain with the pdadmin utility.

Parent topic: Manage protected object policies

Creating a POP with Web Portal ManagerCreating a POP with Web Portal ManagerYou can create a POP with Web Portal Manager.POPcreatingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POPCreate POP to display the Create POP page.In the POP Name field, type the name for the POP. For example, type poptest1.In the Description field, type a description of the POP.Select one or more check boxes for the appropriate audit levels. The audit level is the level of auditing that applies when a resource is accessed to which this POP is attached. You can select more than one audit level. The following choices are available:PermitAudits all of the requests on a protected object that result in successful access.DenyAudits all of the requests on a protected object that result in a denial of access.ErrorAudits all of the internally generated error messages that result from a denial of access to the protected object.AdminAudits not used by Security Access Manager. However, this option can be used by custom applications.See Set an audit levelThe pop modify set audit-level command specifies the granularity level of auditing for a POP. .Select the Warn Only On Policy Violation check box to enable warning mode attributes. A warning mode attribute indicates whether a policy violation that is related to a resource results in denial of access or in an auditable failure. An auditable failure is an access attempt to a resource to which a POP applies, that results in auditing the access, not denying the access.See Set a warning modeThe pop modify set warning command defines the warning mode attribute. A security administrator uses this command to debug or troubleshoot the accuracy of the authorization policy set on the protected object space..Select a type of Quality of Protection. The level of protection applies when a resource is accessed to which this POP is attached. The following choices are available:NoneRequires no Quality of Protection.IntegrityUses some mechanism to ensure that the data is not changed.PrivacyRequires data encryption for Secure Sockets Layer (SSL).See Set a Quality of Protection levelThe Quality of Protection POP attribute specifies what level of data protection is required when doing an operation on an object..Optional: For Time of Day Access, specify the days and times of the day that the resource can be accessed.Select the check boxes for the days of the week that the resource can be accessed.Select either All Day or Between hours of for the access times that the resource can be accessed on the selected days. If you select Between hours of, you must also specify the Start time and End time.If you select Between hours of, you must also specify the Local Time or UTC Time (Coordinated Universal Time).See Set a time-of-day restrictionUse the pop modify set tod-access command defines the time-of-day (TOD) attribute. Use this command to place specific day and time conditions on the access to a protected object. .Click Create or click Create Another if you want to create another POP.If successful, a message confirms that the POP was created.If you clicked Create, click Done. Otherwise, repeat this procedure. Start at step 3 to create another POP.Create a POPYou can create a POP with the Web Portal Manager or pdadmin utility.

Creating a POP with Web Portal Manager

You can create a POP with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > Create POP to display the Create POP page.

In the POP Name field, type the name for the POP. For example, type poptest1.

In the Description field, type a description of the POP.

Select one or more check boxes for the appropriate audit levels. The audit level is the level of auditing that applies when a resource is accessed to which this POP is attached. You can select more than one audit level. The following choices are available:

Permit

Audits all of the requests on a protected object that result in successful access.

Deny

Audits all of the requests on a protected object that result in a denial of access.

Error

Audits all of the internally generated error messages that result from a denial of access to the protected object.

Admin

Audits not used by Security Access Manager. However, this option can be used by custom applications.

See Set an audit level.

Select the Warn Only On Policy Violation check box to enable warning mode attributes. A warning mode attribute indicates whether a policy violation that is related to a resource results in denial of access or in an auditable failure. An auditable failure is an access attempt to a resource to which a POP applies, that results in auditing the access, not denying the access.

See Set a warning mode.

Select a type of Quality of Protection. The level of protection applies when a resource is accessed to which this POP is attached. The following choices are available:

None

Requires no Quality of Protection.

Integrity

Uses some mechanism to ensure that the data is not changed.

Privacy

Requires data encryption for Secure Sockets Layer (SSL).

See Set a Quality of Protection level.

Optional: For Time of Day Access, specify the days and times of the day that the resource can be accessed.

Select the check boxes for the days of the week that the resource can be accessed.

Select either All Day or Between hours of for the access times that the resource can be accessed on the selected days.

If you select Between hours of, you must also specify the Start time and End time.

If you select Between hours of, you must also specify the Local Time or UTC Time (Coordinated Universal Time).

See Set a time-of-day restriction.

Click Create or click Create Another if you want to create another POP.

If successful, a message confirms that the POP was created.

If you clicked Create, click Done. Otherwise, repeat this procedure. Start at step 3 to create another POP.

Parent topic: Create a POP

Creating a POP with pdadminCreating a POP with pdadminYou can create a POP in the domain with the pdadmin utility.commandspopcreatingPOPcreatingwith pdadminLog on to the domain as the domain administrator.Use the pop create command.After creating a POP, you can attach it to an object. See Attach a POP to an objectYou can attach a POP to an object with the Web Portal Manager or pdadmin utility..For example, to create a POP named poptest1, enter the following command: pdadmin sec_master> pop create poptest1The new POP contains the following default settings: pdadmin sec_master> pop show poptest1 Protected object policy: poptest1 Description: Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0See the IBM Security Access Manager for Web: Command Reference.Create a POPYou can create a POP with the Web Portal Manager or pdadmin utility.

Creating a POP with pdadmin

You can create a POP in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop create command.

Results

After creating a POP, you can attach it to an object. See Attach a POP to an object.

Example

For example, to create a POP named poptest1, enter the following command:

pdadmin sec_master> pop create poptest1

The new POP contains the following default settings:

pdadmin sec_master> pop show poptest1
       Protected object policy:  poptest1
       Description:
       Warning:  no
       Audit level:  none
       Quality of protection:  none
       Time of day access: sun, mon, tue, wed, thu, fri, sat:
            anytime:local
       IP Endpoint Authentication Method Policy
           Any Other Network 0

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create a POP

Modify a POPModify a POPYou can modify a POP with the Web Portal Manager or pdadmin utility.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Modifying a POP with Web Portal ManagerYou can modify a POP with Web Portal Manager.Modifying a POP with pdadminYou can modify a POP with the pdadmin utility.

Modify a POP

You can modify a POP with the Web Portal Manager or pdadmin utility.

Modifying a POP with Web Portal Manager
You can modify a POP with Web Portal Manager.

Modifying a POP with pdadmin
You can modify a POP with the pdadmin utility.

Parent topic: Manage protected object policies

Modifying a POP with Web Portal ManagerModifying a POP with Web Portal ManagerYou can modify a POP with Web Portal Manager.POPmodifyingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POPList POP to display the Manage POPs page.Click the link for the POP. For example, select poptest1 to display the POP Properties page.Click the General tab to change the information for the POP, as needed. For example, change the description from Test POP to Test 1 for POP and then click Apply. Click the Attach tab to change the protected object attachments.Click the IP Auth tab to change the IP authentication.Click the Extended Attributes tab to change an extended attribute.Modify a POPYou can modify a POP with the Web Portal Manager or pdadmin utility.

Modifying a POP with Web Portal Manager

You can modify a POP with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > List POP to display the Manage POPs page.

Click the link for the POP. For example, select poptest1 to display the POP Properties page.

Click the General tab to change the information for the POP, as needed. For example, change the description from Test POP to Test 1 for POP and then click Apply.

Click the Attach tab to change the protected object attachments.

Click the IP Auth tab to change the IP authentication.

Click the Extended Attributes tab to change an extended attribute.

Parent topic: Modify a POP

Modifying a POP with pdadminModifying a POP with pdadminYou can modify a POP with the pdadmin utility.commandspopmodifyingPOPmodifyingwith pdadminPOPshow commandLog on to the domain as the domain administrator.Use the pop modify commands.For example to enable the warning mode and set the audit level to permit and deny for the poptest1 POP, enter the following commands: pdadmin sec_master> pop modify poptest1 set warning yes pdadmin sec_master> pop modify poptest1 set audit-level permit,denyTo show these modifications, use the pop show commands. For example, to show the modifications to the poptest1 POP, enter the following command: pdadmin sec_master> pop show poptest1 Protected object policy: poptest1 Description: Test 1 for POP Warning: yes Audit level: permit, deny Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0See the IBM Security Access Manager for Web: Command Reference.Modify a POPYou can modify a POP with the Web Portal Manager or pdadmin utility.

Modifying a POP with pdadmin

You can modify a POP with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop modify commands.

Example

For example to enable the warning mode and set the audit level to permit and deny for the poptest1 POP, enter the following commands:

pdadmin sec_master> pop modify poptest1 set warning yes
pdadmin sec_master> pop modify poptest1 set audit-level permit,deny

To show these modifications, use the pop show commands. For example, to show the modifications to the poptest1 POP, enter the following command:

pdadmin sec_master> pop show poptest1

       Protected object policy:  poptest1
       Description:  Test 1 for POP
       Warning:  yes
       Audit level:  permit, deny
       Quality of protection:  none
       Time of day access: sun, mon, tue, wed, thu, fri, sat:
           anytime:local
       IP Endpoint Authentication Method Policy
           Any Other Network 0

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Modify a POP

List POPsList POPsYou can list all POPs with the Web Portal Manager or pdadmin utility.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Listing POPs with Web Portal ManagerYou can list all POPs with Web Portal Manager.Listing POPs with pdadminYou can list all POPs in the domain with the pdadmin utility.

List POPs

You can list all POPs with the Web Portal Manager or pdadmin utility.

Listing POPs with Web Portal Manager
You can list all POPs with Web Portal Manager.

Listing POPs with pdadmin
You can list all POPs in the domain with the pdadmin utility.

Parent topic: Manage protected object policies

Listing POPs with Web Portal ManagerYou can list all POPs with Web Portal Manager.POPlistingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POP → List POP to display the Manage POPs page. All the POPs for the domain are listed as links.List POPsYou can list all POPs with the Web Portal Manager or pdadmin utility.

Listing POPs with Web Portal Manager

You can list all POPs with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP → List POP to display the Manage POPs page.

Results

All the POPs for the domain are listed as links.

Parent topic: List POPs

Listing POPs with pdadminListing POPs with pdadminYou can list all POPs in the domain with the pdadmin utility.commandspoplistingPOPlistingwith pdadminLog on to the domain as the domain administrator.Use the pop list command.For example, to list all POPs, enter the following command: pdadmin sec_master> pop listSee the IBM Security Access Manager for Web: Command Reference.List POPsYou can list all POPs with the Web Portal Manager or pdadmin utility.

Listing POPs with pdadmin

You can list all POPs in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop list command.

Example

For example, to list all POPs, enter the following command:

pdadmin sec_master> pop list

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: List POPs

View a POPView a POPYou can view a POP with the Web Portal Manager or pdadmin utility.POPshowingManage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Viewing a POP with Web Portal ManagerYou can view a POP with Web Portal Manager.Viewing a POP with pdadminYou can view a POP with the pdadmin utility.

View a POP

You can view a POP with the Web Portal Manager or pdadmin utility.

Viewing a POP with Web Portal Manager
You can view a POP with Web Portal Manager.

Viewing a POP with pdadmin
You can view a POP with the pdadmin utility.

Parent topic: Manage protected object policies

Viewing a POP with Web Portal ManagerYou can view a POP with Web Portal Manager.POPviewingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POPList POP to display the Manage POPs page.Click the link for the POP. For example, select poptest1 to display the POP Properties page.On the General tab, change the information for the POP, as needed. For example, change the description from Test POP to Test 1 for POP, and then click Apply.Click the Attach tab to view the protected object attachments.Click the IP Auth tab to view the IP authentication.Click the Extended Attributes tab to view all extended attributes.View a POPYou can view a POP with the Web Portal Manager or pdadmin utility.

Viewing a POP with Web Portal Manager

You can view a POP with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > List POP to display the Manage POPs page.

Click the link for the POP. For example, select poptest1 to display the POP Properties page.

On the General tab, change the information for the POP, as needed. For example, change the description from Test POP to Test 1 for POP, and then click Apply.

Click the Attach tab to view the protected object attachments.

Click the IP Auth tab to view the IP authentication.

Click the Extended Attributes tab to view all extended attributes.

Parent topic: View a POP

Viewing a POP with pdadminViewing a POP with pdadminYou can view a POP with the pdadmin utility.commandspopviewingPOPviewingwith pdadminPOPshow commandLog on to the domain as the domain administrator.Use the pop show commands.For example, to show the modifications to the POP name poptest1, enter the following command: pdadmin sec_master> pop show poptest1 Protected object policy: poptest1 Description: Test 1 for POP Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0See the IBM Security Access Manager for Web: Command Reference.View a POPYou can view a POP with the Web Portal Manager or pdadmin utility.

Viewing a POP with pdadmin

You can view a POP with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop show commands.

Example

For example, to show the modifications to the POP name poptest1, enter the following command:

pdadmin sec_master> pop show poptest1

       Protected object policy:  poptest1
       Description:  Test 1 for POP
       Warning:  no
       Audit level:  none
       Quality of protection:  none
       Time of day access: sun, mon, tue, wed, thu, fri, sat:
           anytime:local
       IP Endpoint Authentication Method Policy
           Any Other Network 0

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: View a POP

Cloning a POPCloning a POPYou can clone a POP only with the Web Portal Manager. cloning POPsPOPcloningUse Web Portal Manager to log on to the domain as a domain administrator.Click POPList POP.From the Manage POPs page, select the POP you want to clone.From the POP Properties page, click Clone.From the Clone POP page, in the POP Name text field, type the name of the POP. For example, type Test-POP. The default value is the name of the original POP with the prefix Clone. This field is required.Optional: In the Description text field, type the description of the POP. For example, type Clone of new POP. The default value is the description of the original POP.Click Clone. If successful, a link for this cloned POP is created and a success message is displayed.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.

Cloning a POP

You can clone a POP only with the Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > List POP.

From the Manage POPs page, select the POP you want to clone.

From the POP Properties page, click Clone.

From the Clone POP page, in the POP Name text field, type the name of the POP. For example, type Test-POP. The default value is the name of the original POP with the prefix Clone. This field is required.

Optional: In the Description text field, type the description of the POP. For example, type Clone of new POP. The default value is the description of the original POP.

Click Clone.

Results

If successful, a link for this cloned POP is created and a success message is displayed.

Parent topic: Manage protected object policies

Importing POPsImporting POPsYou can import a POP in the domain only with Web Portal Manager. POPimporting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POPImport POP.From the Import POP page, complete one of the following steps:In the POP File Name field, type the name of the POP to import. For example, type popImport.xml.Click Browse to select a file name.The file that contains the POP might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.Click Import. If successful, the imported POP is available when you list all the POPs.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.

Importing POPs

You can import a POP in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > Import POP.

From the Import POP page, complete one of the following steps:

In the POP File Name field, type the name of the POP to import. For example, type popImport.xml.

Click Browse to select a file name.

The file that contains the POP might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.

Click Import.

Results

If successful, the imported POP is available when you list all the POPs.

Parent topic: Manage protected object policies

Exporting all POPsExporting all POPsYou can export all POPs in the domain only with Web Portal Manager. POPexportingallUse Web Portal Manager to log on to the domain as a domain administrator.Click POPExport All POPs to display the Export POP to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported POP description. The default file name is popExport.xml.If successful, the exported POP description is available in the specified location.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.

Exporting all POPs

You can export all POPs in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > Export All POPs to display the Export POP to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported POP description. The default file name is popExport.xml.

Results

If successful, the exported POP description is available in the specified location.

Parent topic: Manage protected object policies

Exporting a single POPExport a single POPYou can export a single POP in the domain only with Web Portal Manager. POPexportingone with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POPList POP.From the Manage POPs page, select the POP that you want to export.From the POP Properties page, click Export to display the Export POP to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported POP description. The default file name is popExport.xml. If successful, the new XML file is available in the specified location.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.

Exporting a single POP

You can export a single POP in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > List POP.

From the Manage POPs page, select the POP that you want to export.

From the POP Properties page, click Export to display the Export POP to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported POP description. The default file name is popExport.xml.

Results

If successful, the new XML file is available in the specified location.

Parent topic: Manage protected object policies

Exporting multiple POPsExporting multiple POPsYou can export POPs in the domain from a list only with Web Portal Manager. POPexportingmultipleUse Web Portal Manager to log on to the domain as a domain administrator.Click POPList POP.From the Manage POPs page, select the POPs that you want to export.Click Export to display the Export POP to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported POP descriptions. The default file name is popExport.xml.If successful, the new XML file is available in the specified location.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.

Exporting multiple POPs

You can export POPs in the domain from a list only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP > List POP.

From the Manage POPs page, select the POPs that you want to export.

Click Export to display the Export POP to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported POP descriptions. The default file name is popExport.xml.

Results

If successful, the new XML file is available in the specified location.

Parent topic: Manage protected object policies

Attach a POP to an objectAttach a POP to an objectYou can attach a POP to an object with the Web Portal Manager or pdadmin utility.POPobjectattachTo do this task, the administrator requires the attach (a) permission.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Attaching a POP to an object with Web Portal ManagerYou can attach a POP to an object with Web Portal Manager.Attaching a POP to an object with pdadminYou can attach a POP to protected object in the domain with the pdadmin utility.

Attach a POP to an object

You can attach a POP to an object with the Web Portal Manager or pdadmin utility.

To do this task, the administrator requires the attach (a) permission.

Attaching a POP to an object with Web Portal Manager
You can attach a POP to an object with Web Portal Manager.

Attaching a POP to an object with pdadmin
You can attach a POP to protected object in the domain with the pdadmin utility.

Parent topic: Manage protected object policies

Attaching a POP to an object with Web Portal ManagerAttaching a POP to an object with Web Portal ManagerYou can attach a POP to an object with Web Portal Manager.POPattachingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POP → List POP to display the Manage POPs page.Click the link for the POP.From the POP Properties page, click the Attach tab.Click Attach to display the Attach POP page.Type the Protected Object Path for the protected object to which to attach the POP. Express the path as the full path name. For example, type /WebSEAL/serverA/index.html.Click Attach.If successful, the protected object is added to the list at the POP Properties–Attach page.Attach a POP to an objectYou can attach a POP to an object with the Web Portal Manager or pdadmin utility.

Attaching a POP to an object with Web Portal Manager

You can attach a POP to an object with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP → List POP to display the Manage POPs page.

Click the link for the POP.

From the POP Properties page, click the Attach tab.

Click Attach to display the Attach POP page.

Type the Protected Object Path for the protected object to which to attach the POP. Express® the path as the full path name. For example, type /WebSEAL/serverA/index.html.

Click Attach.

Results

If successful, the protected object is added to the list at the POP Properties–Attach page.

Parent topic: Attach a POP to an object

Attaching a POP to an object with pdadminAttaching a POP to an object with pdadminYou can attach a POP to protected object in the domain with the pdadmin utility.commandspopattachingPOP attachingwith pdadminPOPattach commandLog on to the domain as the domain administrator.Use the pop attach command.For example, to attach a POP named poptest1 to a protected object named /WebSEAL/serverA/index.html enter the following command: pdadmin sec_master> pop attach /WebSEAL/serverA/index.html poptest1 See the IBM Security Access Manager for Web: Command Reference.Attach a POP to an objectYou can attach a POP to an object with the Web Portal Manager or pdadmin utility.

Attaching a POP to an object with pdadmin

You can attach a POP to protected object in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop attach command.

Example

For example, to attach a POP named poptest1 to a protected object named /WebSEAL/serverA/index.html enter the following command:

pdadmin sec_master> pop attach /WebSEAL/serverA/index.html poptest1

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Attach a POP to an object

Detach a POP from an objectDetach a POP from an objectYou can detach a POP from a protected object with the Web Portal Manager or pdadmin utility.POPobjectdetachingTo do this task, the administrator requires the attach (a) permission.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Detaching a POP from an object with Web Portal ManagerYou can detach a POP from an object with the Web Portal Manager.Detaching a POP from an object with pdadminYou can detach a POP from an object with the pdadmin utility.

Detach a POP from an object

You can detach a POP from a protected object with the Web Portal Manager or pdadmin utility.

To do this task, the administrator requires the attach (a) permission.

Detaching a POP from an object with Web Portal Manager
You can detach a POP from an object with the Web Portal Manager.

Detaching a POP from an object with pdadmin
You can detach a POP from an object with the pdadmin utility.

Parent topic: Manage protected object policies

Detaching a POP from an object with Web Portal ManagerDetaching a POP from an object with Web Portal ManagerYou can detach a POP from an object with the Web Portal Manager.POPdetachingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click Object Space → Browse to display the Browse Object Space page.Click the link for the POP.From the POP Properties page, click the Attach tab.Select one or more check boxes for the protected objects from which you want to detach the POP.Click Detach to display the Detach POP from Object page, where you are prompted to confirm or cancel the detachment.Detach a POP from an objectYou can detach a POP from a protected object with the Web Portal Manager or pdadmin utility.

Detaching a POP from an object with Web Portal Manager

You can detach a POP from an object with the Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click Object Space → Browse to display the Browse Object Space page.

Click the link for the POP.

From the POP Properties page, click the Attach tab.

Select one or more check boxes for the protected objects from which you want to detach the POP.

Click Detach to display the Detach POP from Object page, where you are prompted to confirm or cancel the detachment.

Parent topic: Detach a POP from an object

Detaching a POP from an object with pdadminDetaching a POP from an object with pdadminYou can detach a POP from an object with the pdadmin utility.commandspopdetachingPOPdetachingwith pdadminLog on to the domain as the domain administrator.Use the pop detach commands.For example, to detach the POP from the protected object named /WebSEAL/serverA/index.html, enter the following command: pdadmin sec_master> pop detach /WebSEAL/serverA/index.htmlSee the IBM Security Access Manager for Web: Command Reference.Detach a POP from an objectYou can detach a POP from a protected object with the Web Portal Manager or pdadmin utility.

Detaching a POP from an object with pdadmin

You can detach a POP from an object with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop detach commands.

Example

For example, to detach the POP from the protected object named /WebSEAL/serverA/index.html, enter the following command:

pdadmin sec_master> pop detach /WebSEAL/serverA/index.html

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Detach a POP from an object

Locate where a POP is attachedLocate where a POP is attachedYou can locate where a POP is attached with the Web Portal Manager orpdadmin utility.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Locating where a POP is attached with Web Portal ManagerYou can locate where a POP is attached with Web Portal Manager.Locating where a POP is attached with pdadminYou can locate where a POP is attached in the domain with the pdadmin utility.

Locate where a POP is attached

You can locate where a POP is attached with the Web Portal Manager orpdadmin utility.

Locating where a POP is attached with Web Portal Manager
You can locate where a POP is attached with Web Portal Manager.

Locating where a POP is attached with pdadmin
You can locate where a POP is attached in the domain with the pdadmin utility.

Parent topic: Manage protected object policies

Locating where a POP is attached with Web Portal ManagerYou can locate where a POP is attached with Web Portal Manager.POPlocatingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click ACLList POP. A list of POP names is displayed. Each POP name is a link that you can click to display the POP properties page.Click the Attach tab.Locate where a POP is attachedYou can locate where a POP is attached with the Web Portal Manager orpdadmin utility.

Locating where a POP is attached with Web Portal Manager

You can locate where a POP is attached with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click ACL > List POP. A list of POP names is displayed. Each POP name is a link that you can click to display the POP properties page.

Click the Attach tab.

Parent topic: Locate where a POP is attached

Locating where a POP is attached with pdadminLocating where a POP is attached with pdadminYou can locate where a POP is attached in the domain with the pdadmin utility.commandspoplocatingPOP locatingwith pdadminPOPfind commandLog on to the domain as the domain administrator.Use the pop find command.For example, to find where the POP named poptest1 is attached, enter the following command: pdadmin sec_master> pop find poptest1 /WebSEAL/serverA/index.htmlSee the IBM Security Access Manager for Web: Command Reference.Locate where a POP is attachedYou can locate where a POP is attached with the Web Portal Manager orpdadmin utility.

Locating where a POP is attached with pdadmin

You can locate where a POP is attached in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop find command.

Example

For example, to find where the POP named poptest1 is attached, enter the following command:

pdadmin sec_master> pop find poptest1
      /WebSEAL/serverA/index.html

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Locate where a POP is attached

Delete a POPDelete a POPYou can delete a POP with the Web Portal Manager or pdadmin utility.Manage protected object policiesYou create and configure a protected object policy (POP) and then attach the POP to objects in the protected object space.Deleting a POP with Web Portal ManagerYou can delete a POP with Web Portal Manager.Deleting a POP with pdadminYou can delete a POP with the pdadmin utility.

Delete a POP

You can delete a POP with the Web Portal Manager or pdadmin utility.

Deleting a POP with Web Portal Manager
You can delete a POP with Web Portal Manager.

Deleting a POP with pdadmin
You can delete a POP with the pdadmin utility.

Parent topic: Manage protected object policies

Deleting a POP with Web Portal ManagerDeleting a POP with Web Portal ManagerYou can delete a POP with Web Portal Manager.POPdeletingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click POP → List POP to display the Manage POPs page.Select one or more check boxes for the POPs that you want to delete.Click Delete to display the Delete Pop page.Click Delete to confirm the deletion.Delete a POPYou can delete a POP with the Web Portal Manager or pdadmin utility.

Deleting a POP with Web Portal Manager

You can delete a POP with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click POP → List POP to display the Manage POPs page.

Select one or more check boxes for the POPs that you want to delete.

Click Delete to display the Delete Pop page.

Click Delete to confirm the deletion.

Parent topic: Delete a POP

Deleting a POP with pdadminDeleting a POP with pdadminYou can delete a POP with the pdadmin utility.commandspopdeletePOPdeletingwith pdadminPOPdelete commandLog on to the domain as the domain administrator.Use the pop delete command.For example, to delete the POP named poptest2, enter the following command: pdadmin sec_master> pop delete poptest2See the IBM Security Access Manager for Web: Command Reference.Delete a POPYou can delete a POP with the Web Portal Manager or pdadmin utility.

Deleting a POP with pdadmin

You can delete a POP with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the pop delete command.

Results

For example, to delete the POP named poptest2, enter the following command:

pdadmin sec_master> pop delete poptest2

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete a POP

Network-based authorization algorithmNetwork-based authorization algorithmThe authorization server uses an algorithm to process the conditions in a POP. algorithm, network-based authorizationnetwork-based authorizationalgorithmCheck ACL permissions. The ACL policy bypass (B) permission overrides POP authorization conditions on an object. This permission must be used only by a high-level administrator who needs full access to the protected object space.Verify whether a rule is attached to the object, then verify that all the access decision information (ADI) is present for the coming rule evaluation. If it is not, then find it by querying one of the available sources.Check the IP endpoint authentication method policy on the POP.Check the time-of-day policy on the POP.Check the audit level policy on the POP.Check the authorization rule policy if a rule is attached to the object.If an external authorization service (EAS) operation or POP trigger applies to this access decision, then start the EAS that applies.Protected object policy managementThe access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service.

Network-based authorization algorithm

The authorization server uses an algorithm to process the conditions in a POP.

Check ACL permissions.

Note: The ACL policy bypass (B) permission overrides POP authorization conditions on an object. This permission must be used only by a high-level administrator who needs full access to the protected object space.

Verify whether a rule is attached to the object, then verify that all the access decision information (ADI) is present for the coming rule evaluation. If it is not, then find it by querying one of the available sources.

Check the IP endpoint authentication method policy on the POP.

Check the time-of-day policy on the POP.

Check the audit level policy on the POP.

Check the authorization rule policy if a rule is attached to the object.

If an external authorization service (EAS) operation or POP trigger applies to this access decision, then start the EAS that applies.

Parent topic: Protected object policy management

Network-based authorization policyNetwork-based authorization policyUse the network-based authorization policy to control access to objects based on the IP address of the user. POPnetwork-based authorizationnetwork-based authorizationlimitationsWhen an environment contains both IP version 4 (IPv4) and IP version 6 (IPv6) address formats, be aware of the following restrictions: For administration commands (for example, pop modify set ipauth), IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.For C APIs, IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.For C APIs, IPv6 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.For Java methods, both IPv4 and IPv6 clients must provide addresses in IPv4 format to IPv4 servers.For Java methods, IPv4 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.For an IPv6 address to be accepted (commands, C APIs, and Java methods), the server must be IPv6. You cannot provide an IPv6 address to an IPv4 server.The network-based authorization policy is set in the IP endpoint authentication method attribute of a POP. You can use this functionality to prevent specific IP addresses or IP address ranges from accessing any resources in your domain. When setting an authorization policy, you can apply requisite step-up configuration.When you define a network-based authentication policy, specify these parts of the attribute: Step-up authenticationAllowed networksYou can also apply step-up authentication configuration to this policy and require a specific authentication method for each specified IP address range. See Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method..The IP address used by the resource manager for enforcing the network-based authorization policy must be the IP address of the originator of the connection. In this case, the resource manager cannot definitively identify the true IP address of the client. When setting a network-based authorization policy that depends on specific client IP addresses, ensure that those network clients are connecting directly to the resource manager.Protected object policy managementThe access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service.

Network-based authorization policy

Use the network-based authorization policy to control access to objects based on the IP address of the user.

When an environment contains both IP version 4 (IPv4) and IP version 6 (IPv6) address formats, be aware of the following restrictions:

For administration commands (for example, pop modify set ipauth), IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.

For C APIs, IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.

For C APIs, IPv6 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.

For Java™ methods, both IPv4 and IPv6 clients must provide addresses in IPv4 format to IPv4 servers.

For Java methods, IPv4 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.

For an IPv6 address to be accepted (commands, C APIs, and Java methods), the server must be IPv6. You cannot provide an IPv6 address to an IPv4 server.

The network-based authorization policy is set in the IP endpoint authentication method attribute of a POP. You can use this functionality to prevent specific IP addresses or IP address ranges from accessing any resources in your domain. When setting an authorization policy, you can apply requisite step-up configuration.

When you define a network-based authentication policy, specify these parts of the attribute:

Step-up authentication

Allowed networks

You can also apply step-up authentication configuration to this policy and require a specific authentication method for each specified IP address range. See Step-up authentication.

Note: The IP address used by the resource manager for enforcing the network-based authorization policy must be the IP address of the originator of the connection.

In this case, the resource manager cannot definitively identify the true IP address of the client. When setting a network-based authorization policy that depends on specific client IP addresses, ensure that those network clients are connecting directly to the resource manager.

Parent topic: Protected object policy management

Configure POP attributesConfigure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.POPattributesconfiguringPOPattributessettingProtected object policy managementThe access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service. Set a warning modeThe pop modify set warning command defines the warning mode attribute. A security administrator uses this command to debug or troubleshoot the accuracy of the authorization policy set on the protected object space.Set an audit levelThe pop modify set audit-level command specifies the granularity level of auditing for a POP. Set a time-of-day restrictionUse the pop modify set tod-access command defines the time-of-day (TOD) attribute. Use this command to place specific day and time conditions on the access to a protected object. Specify IP addresses and rangesThe pop modify set ipauth command specifies a network or network range and the required authentication level in the POP. Set a Quality of Protection levelThe Quality of Protection POP attribute specifies what level of data protection is required when doing an operation on an object.

Configure POP attributes

POP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.

Set a warning mode
The pop modify set warning command defines the warning mode attribute. A security administrator uses this command to debug or troubleshoot the accuracy of the authorization policy set on the protected object space.

Set an audit level
The pop modify set audit-level command specifies the granularity level of auditing for a POP.

Set a time-of-day restriction
Use the pop modify set tod-access command defines the time-of-day (TOD) attribute. Use this command to place specific day and time conditions on the access to a protected object.

Specify IP addresses and ranges
The pop modify set ipauth command specifies a network or network range and the required authentication level in the POP.

Set a Quality of Protection level
The Quality of Protection POP attribute specifies what level of data protection is required when doing an operation on an object.

Parent topic: Protected object policy management

Set a warning modeSet a warning modeThe pop modify set warning command defines the warning mode attribute. A security administrator uses this command to debug or troubleshoot the accuracy of the authorization policy set on the protected object space.POPattributeswarning modeWhen you set the warning mode attribute to yes, any action is possible by any user on the object where the POP is attached. Any access to an object is permitted even if the security policy that is attached to the object is set to deny this access.Audit records are generated that capture the results of all security policies with warning mode set throughout the object space. The audit log shows the outcome of an authorization decision as if the warning attribute was set to no. Therefore, the administrator can determine if the policy is set and enforced correctly.For example: pdadmin sec_master> pop modify poptest1 set warning yesSee IBM Security Access Manager for Web: Command Reference.Configure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.

Set a warning mode

The pop modify set warning command defines the warning mode attribute. A security administrator uses this command to debug or troubleshoot the accuracy of the authorization policy set on the protected object space.

When you set the warning mode attribute to yes, any action is possible by any user on the object where the POP is attached. Any access to an object is permitted even if the security policy that is attached to the object is set to deny this access.

Audit records are generated that capture the results of all security policies with warning mode set throughout the object space. The audit log shows the outcome of an authorization decision as if the warning attribute was set to no. Therefore, the administrator can determine if the policy is set and enforced correctly.

For example:

pdadmin sec_master> pop modify poptest1 set warning yes

See IBM Security Access Manager for Web: Command Reference.

Parent topic: Configure POP attributes

Set an audit levelSet an audit levelThe pop modify set audit-level command specifies the granularity level of auditing for a POP. POPattributesaudit levelFor example, auditing might be set to record unsuccessful events. You can use the results to detect an unusual number of failed access attempts on a particular resource.Auditing records are written in a standard Extensible Markup Language (XML) format that allows easy parsing to extract whatever information is required. For example: pdadmin sec_master> pop modify pop_name set audit-level permit,denyAudit levelsValueDescriptionpermitAudit all requests on a protected object that result in successful access.denyAudit all requests on a protected object that result in denial of access.errorAudit all internally generated error messages that result from a denial of access to the protected object.You can apply any combination of these values or specify either all to audit all requests or none to audit no requests. When enabling granular auditing, specify one or more of the following values: permitdenyerrorWhen you specify multiple granular values, use a comma as a separator character between these values.See IBM Security Access Manager for Web: Command Reference.Configure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.

Set an audit level

The pop modify set audit-level command specifies the granularity level of auditing for a POP.

For example, auditing might be set to record unsuccessful events. You can use the results to detect an unusual number of failed access attempts on a particular resource.

Auditing records are written in a standard Extensible Markup Language (XML) format that allows easy parsing to extract whatever information is required. For example:

pdadmin sec_master> pop modify pop_name set audit-level permit,deny

Table 170. Audit levels

Value | Description
permit | Audit all requests on a protected object that result in successful access.
deny | Audit all requests on a protected object that result in denial of access.
error | Audit all internally generated error messages that result from a denial of access to the protected object.

You can apply any combination of these values or specify either all to audit all requests or none to audit no requests. When enabling granular auditing, specify one or more of the following values:

permit

deny

error

When you specify multiple granular values, use a comma as a separator character between these values.

See IBM Security Access Manager for Web: Command Reference.

Parent topic: Configure POP attributes

Set a time-of-day restrictionSet a time-of-day restrictionUse the pop modify set tod-access command defines the time-of-day (TOD) attribute. Use this command to place specific day and time conditions on the access to a protected object. POPattributestime of dayThis type of condition might be useful to limit access to information that regularly requires periods of inactivity for modification and updates. pdadmin sec_master> pop modify pop_name set tod-access time_of_day_stringThe time-of-day-string argument includes a day-range and a time-range and uses the following format: {anyday|weekday|day_list}: {anytime|time_spec-time_spec} [:{utc|local}]The day_list variable can be any combination of the following values: mon, tue, wed, thu, fri, sat, sunThe time_spec range variable must be expressed (in 24 hour time) in the following format: hhmm-hhmmFor example, you can specify the time range with the following string: 0700-1945The optional time zone [:{utc|local}] for the server (not the client) is local by default.For example to change the time-of-day attribute to Monday, Tuesday, and Friday from 1:15 p.m. to 5:30 p.m. local time for the POP named poptest1, enter the following command: pdadmin sec_master> pop modify poptest1 set tod-access mon,tue,fri:1315-1730When modifying a protected object policy, you provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.See IBM Security Access Manager for Web: Command Reference.Configure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.

Set a time-of-day restriction

Use the pop modify set tod-access command defines the time-of-day (TOD) attribute. Use this command to place specific day and time conditions on the access to a protected object.

This type of condition might be useful to limit access to information that regularly requires periods of inactivity for modification and updates.

pdadmin sec_master> pop modify pop_name set tod-access
time_of_day_string

The time-of-day-string argument includes a day-range and a time-range and uses the following format:

{anyday|weekday|day_list}:
{anytime|time_spec-time_spec}
[:{utc|local}]

The day_list variable can be any combination of the following values:

mon, tue, wed, thu, fri, sat, sun

The time_spec range variable must be expressed (in 24 hour time) in the following format:

hhmm-hhmm

For example, you can specify the time range with the following string:

0700-1945

The optional time zone [:{utc|local}] for the server (not the client) is local by default.

For example to change the time-of-day attribute to Monday, Tuesday, and Friday from 1:15 p.m. to 5:30 p.m. local time for the POP named poptest1, enter the following command:

pdadmin sec_master> pop modify poptest1 set tod-access mon,tue,fri:1315-1730

Note: When modifying a protected object policy, you provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.

See IBM Security Access Manager for Web: Command Reference.

Parent topic: Configure POP attributes

Specify IP addresses and rangesSpecify IP addresses and rangesThe pop modify set ipauth command specifies a network or network range and the required authentication level in the POP. network-based authorizationIP addresses and rangesPOPspecifyingIP addressesfor POPsPOPset ipauth commandcommandspopmodifying set ipauthThe network (or network range) can be an IP version 4 (IPv4) or an IP version 6 (IPv6) address. When adding addresses to a POP, IPv4 addresses must be specified in IPv4 format, due to limitations in the operating system functions provided to Security Access Manager.All POPs have an anyothernw (any other network) IP entry whose default authentication level is 0. The anyothernw entry applies to all networks not specified in the POP. Authentication level 0 adds no additional requirement for authentication. The anyothernw authentication level can be modified to a non-zero number or to forbidden.The anyothernw entry appears in a POP as Any Other Network in the output of the pop show command: pdadmin sec_master> pop show poptest1 Protected object policy: poptest1 Description: Test POP Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0You might need more information about setting the IP authentication mechanism with the pop modify command. See the IBM Security Access Manager for Web: Command Reference.Configure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.Adding IP entriesThe pdadmin pop modify set ipauth add command specifies the network (or network range). The command also specifies the required authentication level in the IP endpoint authentication method attribute. You might need to add IP entries to a POP.Deleting IP entriesThe pdadmin pop modify set ipauth remove command disables authorization requirements for IP addresses that were previously added to a POP.

Specify IP addresses and ranges

The pop modify set ipauth command specifies a network or network range and the required authentication level in the POP.

The network (or network range) can be an IP version 4 (IPv4) or an IP version 6 (IPv6) address.

Note: When adding addresses to a POP, IPv4 addresses must be specified in IPv4 format, due to limitations in the operating system functions provided to Security Access Manager.

All POPs have an anyothernw (any other network) IP entry whose default authentication level is 0. The anyothernw entry applies to all networks not specified in the POP. Authentication level 0 adds no additional requirement for authentication. The anyothernw authentication level can be modified to a non-zero number or to forbidden.

The anyothernw entry appears in a POP as Any Other Network in the output of the pop show command:

pdadmin sec_master> pop show poptest1

       Protected object policy: poptest1
       Description: Test POP
       Warning: no
       Audit level: none
       Quality of protection: none
       Time of day access: sun, mon, tue, wed, thu, fri, sat:
            anytime:local
       IP Endpoint Authentication Method Policy
           Any Other Network 0

You might need more information about setting the IP authentication mechanism with the pop modify command. See the IBM Security Access Manager for Web: Command Reference.

Adding IP entries
The pdadmin pop modify set ipauth add command specifies the network (or network range). The command also specifies the required authentication level in the IP endpoint authentication method attribute. You might need to add IP entries to a POP.

Deleting IP entries
The pdadmin pop modify set ipauth remove command disables authorization requirements for IP addresses that were previously added to a POP.

Parent topic: Configure POP attributes

Adding IP entriesAdding IP entriesThe pdadmin pop modify set ipauth add command specifies the network (or network range). The command also specifies the required authentication level in the IP endpoint authentication method attribute. You might need to add IP entries to a POP.network-based authorizationadding for POPsnetwork-based authorizationforbidding or POPsPOPadding authorizationPOPforbidding network-based authorizationPOPmodify set ipauth add commandcommandspopmodifying set ipauth addingIP addressesadding network-based authorization for POPsIP addressesforbidding network-based authorization for POPsSpecify network (or network range) with an authentication level as a number or as forbidden.Specify an authentication level of 0 to allow authentication. A forbidden authentication level indicates that authentication is denied. Specify an authentication greater than 0 to step-up a user to an authentication level. The enforcement of step-up authentication is the responsibility of resource managers. See Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.. When adding addresses to a POP, IPv4 addresses must be specified in IPv4 format, due to limitations in the operating system functions provided to Security Access Manager.The following example adds an IP entry for identities from IPv4 addresses that begin with 9. pdadmin sec_master> pop modify poptest1 set ipauth add 9.0.0.0 255.0.0.0 5The following example adds an entry for an IPv6 network range: pdadmin sec_master> pop modify poptest1 set ipauth add \ fedc:ba98:7654:3210:fedc:ba98:7654:3210 ffff:ffff:ffff:ffff:ffff:ffff:ffff:0 6The following example prevents all users (except users specified in the examples) from accessing the object: pdadmin sec_master> pop modify poptest1 set ipauth anyothernw forbiddenSee the IBM Security Access Manager for Web: Command Reference.Specify IP addresses and rangesThe pop modify set ipauth command specifies a network or network range and the required authentication level in the POP.

Adding IP entries

The pdadmin pop modify set ipauth add command specifies the network (or network range). The command also specifies the required authentication level in the IP endpoint authentication method attribute. You might need to add IP entries to a POP.

Procedure

Specify network (or network range) with an authentication level as a number or as forbidden.

Specify an authentication level of 0 to allow authentication. A forbidden authentication level indicates that authentication is denied. Specify an authentication greater than 0 to step-up a user to an authentication level. The enforcement of step-up authentication is the responsibility of resource managers. See Step-up authentication.

Note: When adding addresses to a POP, IPv4 addresses must be specified in IPv4 format, due to limitations in the operating system functions provided to Security Access Manager.

Example

The following example adds an IP entry for identities from IPv4 addresses that begin with 9.

pdadmin sec_master> pop modify poptest1 set ipauth add 9.0.0.0 255.0.0.0 5

The following example adds an entry for an IPv6 network range:

pdadmin sec_master> pop modify poptest1 set ipauth add \
  fedc:ba98:7654:3210:fedc:ba98:7654:3210 ffff:ffff:ffff:ffff:ffff:ffff:ffff:0 6

The following example prevents all users (except users specified in the examples) from accessing the object:

pdadmin sec_master> pop modify poptest1 set ipauth anyothernw forbidden

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Specify IP addresses and ranges

Deleting IP entriesDeleting IP entriesThe pdadmin pop modify set ipauth remove command disables authorization requirements for IP addresses that were previously added to a POP.network-based authorizationdeleting for POPsPOPdeleting network-based authorizationIP addressesdeleting network-based authorization for POPscommandspopmodifying set ipauth removingPOPmodify set ipauth remove commandUse the pdadmin pop modify set ipauth remove command for an existing POP. The following example deletes an IPv4 entry from the poptest1 POP:pdadmin sec_master> pop modify poptest1 set ipauth remove 9.0.0.0 255.0.0.0Only network entries that were previously added can be removed.Repeat the step for additional entries that you want to remove.See the IBM Security Access Manager for Web: Command Reference.Specify IP addresses and rangesThe pop modify set ipauth command specifies a network or network range and the required authentication level in the POP.

Deleting IP entries

The pdadmin pop modify set ipauth remove command disables authorization requirements for IP addresses that were previously added to a POP.

Procedure

Use the pdadmin pop modify set ipauth remove command for an existing POP. The following example deletes an IPv4 entry from the poptest1 POP:

pdadmin sec_master> pop modify poptest1 set ipauth remove 9.0.0.0 255.0.0.0

Only network entries that were previously added can be removed.

Repeat the step for additional entries that you want to remove.

What to do next

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Specify IP addresses and ranges

Set a Quality of Protection levelSet a Quality of Protection levelThe Quality of Protection POP attribute specifies what level of data protection is required when doing an operation on an object.POPprotectionQuality of ProtectionsettingThe Quality of Protection POP attribute permits a single transaction where the yes response to the ACL decision also includes the required Quality of Protection level. If the resource manager cannot guarantee the required level of protection, the request is denied.Use the following pop modify command syntax to modify the QoP level for an object: pdadmin sec_master> pop modify pop-name set qop {none|integrity|privacy} Quality of Protection levelsQoP levelDescriptionnoneRequires no Quality of Protection.privacyData encryption is required for Secure Sockets Layer (SSL).integrityUse some mechanism to ensure that the data is not changed.For example, to modify the POP named poptest1 to set the Quality of Protection level to use SSL data encryption, enter the following command: pdadmin sec_master> pop modify poptest1 set qop privacyConfigure POP attributesPOP attributes impose access conditions on an object based on the time of the access. They also indicate whether the access request must be audited.

Set a Quality of Protection level

The Quality of Protection POP attribute specifies what level of data protection is required when doing an operation on an object.

The Quality of Protection POP attribute permits a single transaction where the yes response to the ACL decision also includes the required Quality of Protection level. If the resource manager cannot guarantee the required level of protection, the request is denied.

Use the following pop modify command syntax to modify the QoP level for an object:

pdadmin sec_master> pop modify pop-name set qop {none|integrity|privacy}

Table 171. Quality of Protection levels

QoP level | Description
none | Requires no Quality of Protection.
privacy | Data encryption is required for Secure Sockets Layer (SSL).
integrity | Use some mechanism to ensure that the data is not changed.

For example, to modify the POP named poptest1 to set the Quality of Protection level to use SSL data encryption, enter the following command:

pdadmin sec_master> pop modify poptest1 set qop privacy

Parent topic: Configure POP attributes

Step-up authenticationStep-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.authenticationlevelsauthenticationstep-upYou can use this functionality, sometimes known as step-up authentication, to ensure that users who access more sensitive resources use a stronger authentication mechanism. You might want this condition because of the greater threat of improper access to certain resources.For example, you can provide greater security to a junctioned region of the protected object space. Apply a step-up POP policy that requires a stronger level of authentication than the client used when initially entering the domain.The authentication strength policy is set in the IP endpoint authentication method attribute of a POP policy.Protected object policy managementThe access control list (ACL) policies provide the authorization service with information to make a yes or no answer on a request to access a protected object and do some operation on that object. A protected object policy (POP) contains additional conditions on the request. The conditions are passed back to the resource manager along with the yes ACL policy decision from the authorization service. Configure levels for step-up authenticationThe first step in configuring authentication-specific access is to configure the supported authentication methods and determine the order in which these authentication methods must be considered stronger.Apply step-up authentication policyStep-up authentication is implemented through a POP policy placed on the objects requiring authentication-sensitive authorization. You can use the IP endpoint authentication method attribute of a POP policy.Distinguish step-up from multi-factor authenticationSecurity Access Manager step-up authentication and multi-factor authentication are two different mechanisms for controlling access to resources.

Step-up authentication

You can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.

You can use this functionality, sometimes known as step-up authentication, to ensure that users who access more sensitive resources use a stronger authentication mechanism. You might want this condition because of the greater threat of improper access to certain resources.

For example, you can provide greater security to a junctioned region of the protected object space. Apply a step-up POP policy that requires a stronger level of authentication than the client used when initially entering the domain.

The authentication strength policy is set in the IP endpoint authentication method attribute of a POP policy.

Configure levels for step-up authentication
The first step in configuring authentication-specific access is to configure the supported authentication methods and determine the order in which these authentication methods must be considered stronger.

Apply step-up authentication policy
Step-up authentication is implemented through a POP policy placed on the objects requiring authentication-sensitive authorization. You can use the IP endpoint authentication method attribute of a POP policy.

Distinguish step-up from multi-factor authentication
Security Access Manager step-up authentication and multi-factor authentication are two different mechanisms for controlling access to resources.

Parent topic: Protected object policy management

Configure levels for step-up authenticationConfigure levels for step-up authenticationThe first step in configuring authentication-specific access is to configure the supported authentication methods and determine the order in which these authentication methods must be considered stronger.step-up authenticationlevelsconfiguringstep-up authenticationconfiguringauthenticationlevels of step-up, configuringAny client that accesses a resource manager has an authentication level, such as unauthenticated or password. The level indicates the method with which the client was last authenticated by the resource manager.In some situations, it might be necessary to enforce minimum safe levels of authentication required to access certain resources. For example, in one environment, authentication by token pass code might be considered more secure than authentication by user name and password. Another environment might require different standards.The step-up authentication mechanism does not force clients to restart their sessions with the resource manager when they do not meet the required level of authentication. Instead, the step-up authentication mechanism provides clients a second chance to authenticate with the required method of authentication (level).Step-up authentication allows resource managers to control how users access protected resources. If step-up authentication is required because the user has not authenticated with the sufficient method, the authorization engine still permits the access decision. However, the resource manager is presented with a required authentication level as an output of the authorization decision. The resource manager can then decide how to further authenticate the user to gain the required level of authentication to access the protected object.How a particular authentication method is mapped to an authentication level is determined by the resource manager application. For all cases, the absolute minimum acceptable method of authentication must be set as level 0. More secure methods are mapped to integer numbers in ascending order (1..x) from that point forward.Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.

Configure levels for step-up authentication

The first step in configuring authentication-specific access is to configure the supported authentication methods and determine the order in which these authentication methods must be considered stronger.

Any client that accesses a resource manager has an authentication level, such as "unauthenticated" or "password". The level indicates the method with which the client was last authenticated by the resource manager.

In some situations, it might be necessary to enforce minimum safe levels of authentication required to access certain resources. For example, in one environment, authentication by token pass code might be considered more secure than authentication by user name and password. Another environment might require different standards.

The step-up authentication mechanism does not force clients to restart their sessions with the resource manager when they do not meet the required level of authentication. Instead, the step-up authentication mechanism provides clients a second chance to authenticate with the required method of authentication (level).

Step-up authentication allows resource managers to control how users access protected resources. If step-up authentication is required because the user has not authenticated with the sufficient method, the authorization engine still permits the access decision. However, the resource manager is presented with a required authentication level as an output of the authorization decision. The resource manager can then decide how to further authenticate the user to gain the required level of authentication to access the protected object.

How a particular authentication method is mapped to an authentication level is determined by the resource manager application. For all cases, the absolute minimum acceptable method of authentication must be set as level 0. More secure methods are mapped to integer numbers in ascending order (1..x) from that point forward.

Parent topic: Step-up authentication

Apply step-up authentication policyApply step-up authentication policyStep-up authentication is implemented through a POP policy placed on the objects requiring authentication-sensitive authorization. You can use the IP endpoint authentication method attribute of a POP policy.step-upauthenticationapplyingauthenticationstep-up policy, applyingThe pop modify set ipauth command specifies both the allowed networks and the required authentication level in the IP endpoint authentication method attribute. When specifying an IPv4 address, it must be in IPv4 format.The configured authentication levels can be linked to IP address ranges. This method is intended to provide management flexibility. If filtering users by IP address is not important, you can set a single entry for anyothernw (any other network). This setting affects all accessing users, regardless of IP address, and requires the users to authenticate at the specified level. This method is the most common method for implementing step-up authentication.The anyothernw entry is used as a network range that matches any network not otherwise specified in the POP. Use this method to create a default entry that can either deny all unmatched IP addresses or allow anyone access who meets the authentication level requirement.By default, anyothernw occurs in a POP with an authentication level index of 0. The entry occurs as Any Other Network in the output of the pop show command. The following output shows a sample for the poptest1 POP: pdadmin sec_master> pop show poptest1 Protected object policy: poptest1 Description: Test POP Warning: no Audit level: none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime:local IP Endpoint Authentication Method Policy Any Other Network 0See the IBM Security Access Manager for Web: Command Reference.Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.

Apply step-up authentication policy

Step-up authentication is implemented through a POP policy placed on the objects requiring authentication-sensitive authorization. You can use the IP endpoint authentication method attribute of a POP policy.

The pop modify set ipauth command specifies both the allowed networks and the required authentication level in the IP endpoint authentication method attribute.

Note: When specifying an IPv4 address, it must be in IPv4 format.

The configured authentication levels can be linked to IP address ranges. This method is intended to provide management flexibility. If filtering users by IP address is not important, you can set a single entry for anyothernw (any other network). This setting affects all accessing users, regardless of IP address, and requires the users to authenticate at the specified level. This method is the most common method for implementing step-up authentication.

The anyothernw entry is used as a network range that matches any network not otherwise specified in the POP. Use this method to create a default entry that can either deny all unmatched IP addresses or allow anyone access who meets the authentication level requirement.

By default, anyothernw occurs in a POP with an authentication level index of 0. The entry occurs as Any Other Network in the output of the pop show command. The following output shows a sample for the poptest1 POP:

pdadmin sec_master> pop show poptest1

       Protected object policy: poptest1
       Description: Test POP
       Warning: no
       Audit level: none
       Quality of protection: none
       Time of day access: sun, mon, tue, wed, thu, fri, sat:
           anytime:local
       IP Endpoint Authentication Method Policy
           Any Other Network 0

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Step-up authentication

Distinguish step-up from multi-factor authenticationDistinguish step-up from multi-factor authenticationSecurity Access Manager step-up authentication and multi-factor authentication are two different mechanisms for controlling access to resources. multi-factor authenticationstep-up authenticationversus multi-factor authenticationauthenticationmulti-factor authenticationMulti-factor authentication forces a user to authenticate with two or more levels of authentication. For example, the access control on a protected resource can require the user to authenticate with both user name and password (level 1). The access control can also require the user to authenticate with user name and token passcode (level 2).Security Access Manager step-up authentication relies on a pre-configured hierarchy of authentication levels and enforces a specific level of authentication according to the policy set on a resource. Step-up authentication does not force the user to authenticate with multiple levels of authentication to access any specified resource. Instead, step-up authentication requires the user to authenticate at a level at least as high as the level required by the policy that protects the resource.The following example shows the series of commands that are needed to define step-up authentication: pdadmin > pop create test1 pdadmin > pop modify test1 set ipauth anyothernw 1 pdadmin > pop attach /WebSEAL/hostA/junction test1 pdadmin > pop create test2 pdadmin > pop modify test2 set ipauth anyothernw 2 pdadmin > pop attach /WebSEAL/hostA/junction/applicationA test2In the previous example, the /WebSEAL/hostA/junction object is protected by a POP requiring authentication level 1. The /WebSEAL/hostA/junction/applicationA object is protected by a POP requiring authentication level 2.Under step-up authentication, user name/password (level 1) authentication is required to access /WebSEAL/hostA/junction.However, user name/token passcode (level 2) authentication is required to access /WebSEAL/hostA/junction/applicationA. If the user is currently logged in with a user name and password, a prompt appears requesting user name and token passcode information (the step-up). However, if the user initially logged on to WebSEAL with a user name and a token passcode, access to applicationA is immediate, assuming a successful ACL check.Multi-factor authentication requires both level 1 and level 2 authentication for access to applicationA.Step-up authenticationYou can use protected object policies (POPs) to enforce certain access conditions on specific resources. The authentication strength policy makes it possible to control access to objects based on authentication method.

Distinguish step-up from multi-factor authentication

Security Access Manager step-up authentication and multi-factor authentication are two different mechanisms for controlling access to resources.

Multi-factor authentication forces a user to authenticate with two or more levels of authentication. For example, the access control on a protected resource can require the user to authenticate with both user name and password (level 1). The access control can also require the user to authenticate with user name and token passcode (level 2).

Security Access Manager step-up authentication relies on a pre-configured hierarchy of authentication levels and enforces a specific level of authentication according to the policy set on a resource. Step-up authentication does not force the user to authenticate with multiple levels of authentication to access any specified resource. Instead, step-up authentication requires the user to authenticate at a level at least as high as the level required by the policy that protects the resource.

The following example shows the series of commands that are needed to define step-up authentication:

pdadmin > pop create test1
pdadmin > pop modify test1 set ipauth anyothernw 1
pdadmin > pop attach /WebSEAL/hostA/junction test1

pdadmin > pop create test2
pdadmin > pop modify test2 set ipauth anyothernw 2
pdadmin > pop attach /WebSEAL/hostA/junction/applicationA test2

In the previous example, the /WebSEAL/hostA/junction object is protected by a POP requiring authentication level 1. The /WebSEAL/hostA/junction/applicationA object is protected by a POP requiring authentication level 2.

Under step-up authentication, user name/password (level 1) authentication is required to access /WebSEAL/hostA/junction.

However, user name/token passcode (level 2) authentication is required to access /WebSEAL/hostA/junction/applicationA. If the user is currently logged in with a user name and password, a prompt appears requesting user name and token passcode information (the step-up). However, if the user initially logged on to WebSEAL with a user name and a token passcode, access to applicationA is immediate, assuming a successful ACL check.

Multi-factor authentication requires both level 1 and level 2 authentication for access to applicationA.

Parent topic: Step-up authentication

Authorization rules managementAuthorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.authorizationrulesmanagement tasksAccess Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Authorization rules overviewAuthorization rules are defined to specify conditions that must be met before access to a protected object is permitted. Access decision informationThe data and attributes in rule conditions collectively are called access decision information (ADI). Authorization API attributes, which are name and value pairs, form the basis of all ADI that can be referenced in a rule or presented to the authorization engine. Authorization rule languageExtensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is used for the data that forms an input to the rules. The combination of XML and XSL provides a platform independent way to express both the inputs to the rules evaluator and the rules themselves.Authorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.Configuration file and initialization attributesA number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager. Manage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.

Authorization rules management

These topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.

Authorization rules overview
Authorization rules are defined to specify conditions that must be met before access to a protected object is permitted.

Access decision information
The data and attributes in rule conditions collectively are called access decision information (ADI). Authorization API attributes, which are name and value pairs, form the basis of all ADI that can be referenced in a rule or presented to the authorization engine.

Authorization rule language
Extensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is used for the data that forms an input to the rules. The combination of XML and XSL provides a platform independent way to express both the inputs to the rules evaluator and the rules themselves.

Authorization rules evaluator
The authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.

Configuration file and initialization attributes
A number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager.

Manage authorization rules
These topics describe how to use the Web Portal Manager or pdadmin utility.

Parent topic: Access Manager Platform and Supporting Components administration

Authorization rules overviewAuthorization rules overviewAuthorization rules are defined to specify conditions that must be met before access to a protected object is permitted. authorizationrulesoverviewA rule is created with a number of Boolean conditions that are based on data supplied to the authorization engine within the user credential. Data might be supplied from the resource manager application or from the encompassing business environment. The language of an authorization rule allows customers to work with complex, structured data by examining the values in that data and making informed access decisions. This information can be defined statically within the system or can be defined during a business process. Rules can also be used to implement extensible, attribute-based, authorization policy by using attributes within the business environment or attributes from trusted external sources.A Security Access Manager authorization rule is a policy type like an access control list (ACL) or a protected object policy (POP). The rule is stored as a text rule within a rule policy object. The rule is attached to a protected object in the same way and with similar constraints as ACLs and POPs.Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.

Authorization rules overview

Authorization rules are defined to specify conditions that must be met before access to a protected object is permitted.

A rule is created with a number of Boolean conditions that are based on data supplied to the authorization engine within the user credential. Data might be supplied from the resource manager application or from the encompassing business environment. The language of an authorization rule allows customers to work with complex, structured data by examining the values in that data and making informed access decisions. This information can be defined statically within the system or can be defined during a business process. Rules can also be used to implement extensible, attribute-based, authorization policy by using attributes within the business environment or attributes from trusted external sources.

A Security Access Manager authorization rule is a policy type like an access control list (ACL) or a protected object policy (POP). The rule is stored as a text rule within a rule policy object. The rule is attached to a protected object in the same way and with similar constraints as ACLs and POPs.

Parent topic: Authorization rules management

Access decision informationAccess decision informationThe data and attributes in rule conditions collectively are called access decision information (ADI). Authorization API attributes, which are name and value pairs, form the basis of all ADI that can be referenced in a rule or presented to the authorization engine. access decision informationADIdefinitionauthorization APIattributesattributepairs (name/value)Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.Sources for retrieving ADIThe authorization engine can gather ADI from several sources.Volatile versus nonvolatile dataIn general, the source for any particular piece of ADI depends largely on what the data is. The most important question is whether the data is volatile. For example, is it possible for the data to change during the lifetime of the session of the user? Is it important to use the most up-to-date information when it does change? Volatile data must be retrieved with a dynamic ADI retrieval service unless the resource manager application can provide this data.

Access decision information

The data and attributes in rule conditions collectively are called access decision information (ADI). Authorization API attributes, which are name and value pairs, form the basis of all ADI that can be referenced in a rule or presented to the authorization engine.

Sources for retrieving ADI
The authorization engine can gather ADI from several sources.

Volatile versus nonvolatile data
In general, the source for any particular piece of ADI depends largely on what the data is. The most important question is whether the data is volatile. For example, is it possible for the data to change during the lifetime of the session of the user? Is it important to use the most up-to-date information when it does change? Volatile data must be retrieved with a dynamic ADI retrieval service unless the resource manager application can provide this data.

Parent topic: Authorization rules management

Sources for retrieving ADIThe authorization engine can gather ADI from several sources.ADIsourceAccess decision informationThe data and attributes in rule conditions collectively are called access decision information (ADI). Authorization API attributes, which are name and value pairs, form the basis of all ADI that can be referenced in a rule or presented to the authorization engine. User credential entitlementsYou can insert additional entitlements data as attribute name-value pairs into the client credential by a Security Access Manager authorization client. Insertion can occur during the user authentication process or at any time during the process of the transaction.Application context informationAuthorization rules might require application context information to complete an evaluation. Context information includes information that is not an entitlement but is specific to the current transaction or operation. Authorization engine context informationIf required, the authorization engine automatically provides context information before the authorization rule is evaluated. The ADI provided by the authorization engine includes the name of the protected object that is the target of the access decision. The ADI also includes the string of operations that the requesting user wants to do on the protected object.Dynamic ADI retrieval entitlement servicesThe final source for retrieving ADI is the dynamic ADI retrieval entitlements service. This class of authorization entitlement services is designed to retrieve ADI from an external source.

Sources for retrieving ADI

The authorization engine can gather ADI from several sources.

User credential entitlements
You can insert additional entitlements data as attribute name-value pairs into the client credential by a Security Access Manager authorization client. Insertion can occur during the user authentication process or at any time during the process of the transaction.

Application context information
Authorization rules might require application context information to complete an evaluation. Context information includes information that is not an entitlement but is specific to the current transaction or operation.

Authorization engine context information
If required, the authorization engine automatically provides context information before the authorization rule is evaluated. The ADI provided by the authorization engine includes the name of the protected object that is the target of the access decision. The ADI also includes the string of operations that the requesting user wants to do on the protected object.

Dynamic ADI retrieval entitlement services
The final source for retrieving ADI is the dynamic ADI retrieval entitlements service. This class of authorization entitlement services is designed to retrieve ADI from an external source.

Parent topic: Access decision information

User credential entitlementsUser credential entitlementsYou can insert additional entitlements data as attribute name-value pairs into the client credential by a Security Access Manager authorization client. Insertion can occur during the user authentication process or at any time during the process of the transaction.entitlementsuser credentialuserscredential entitlementscredential entitlementsFor example, Security Access Manager can be configured to gather entitlements at the time that a user is authenticated. You can configure entitlement services to run during credential acquisition, collect entitlements data, and then append the data to the credential. Security Access Manager provides a credential attributes entitlement service that retrieves entitlements data from the user registry. Or, you can define your own entitlement services. See Authorization C API Developer Reference.Any attribute added to the user credential can be used as ADI in a rule definition. There are also attributes that are built into the Security Access Manager user credential when it is created by the authorization engine. Just like attributes that can be added to the credential by the resource manager, the built-in credential attributes can be used in authorization rules. The built-in credential attributes include items of information, such as the user name (or the principal UUID). The attributes also include the groups (or the group UUID) of which the user is a member.See the Authorization C API Developer Reference for a table of valid credential attribute names. All credential attribute names begin with azn_cred_ (for example, azn_cred_principal_uuid). This table lists attribute names available in the Security Access Manager authenticated user credential, their value, and a description. Many attributes in this table are also available in an unauthenticated user credential, except attributes related to the identity of a user. For example, attributes such as the user name, principal UUID, group name, and group UUID, and the LDAP DN for LDAP configurations are not available in an unauthenticated credential. When developing rules that use these particular attributes, the authorization engine requires all ADI to be present before a rule can be evaluated. If the ADI is not available, the authorization decision is returned with an error status. Requiring the user to authenticate before accessing the protected object with such a rule attached ensures that the authenticated credential information is available. This requirement can be achieved with an ACL entry on the object that requires authenticated access.Sources for retrieving ADIThe authorization engine can gather ADI from several sources.

User credential entitlements

You can insert additional entitlements data as attribute name-value pairs into the client credential by a Security Access Manager authorization client. Insertion can occur during the user authentication process or at any time during the process of the transaction.

For example, Security Access Manager can be configured to gather entitlements at the time that a user is authenticated. You can configure entitlement services to run during credential acquisition, collect entitlements data, and then append the data to the credential.

Security Access Manager provides a credential attributes entitlement service that retrieves entitlements data from the user registry. Or, you can define your own entitlement services. See Authorization C API Developer Reference.

Any attribute added to the user credential can be used as ADI in a rule definition. There are also attributes that are built into the Security Access Manager user credential when it is created by the authorization engine. Just like attributes that can be added to the credential by the resource manager, the built-in credential attributes can be used in authorization rules. The built-in credential attributes include items of information, such as the user name (or the principal UUID). The attributes also include the groups (or the group UUID) of which the user is a member.

See the Authorization C API Developer Reference for a table of valid credential attribute names. All credential attribute names begin with azn_cred_ (for example, azn_cred_principal_uuid). This table lists attribute names available in the Security Access Manager authenticated user credential, their value, and a description.

Many attributes in this table are also available in an unauthenticated user credential, except attributes related to the identity of a user. For example, attributes such as the user name, principal UUID, group name, and group UUID, and the LDAP DN for LDAP configurations are not available in an unauthenticated credential.

When developing rules that use these particular attributes, the authorization engine requires all ADI to be present before a rule can be evaluated. If the ADI is not available, the authorization decision is returned with an error status. Requiring the user to authenticate before accessing the protected object with such a rule attached ensures that the authenticated credential information is available. This requirement can be achieved with an ACL entry on the object that requires authenticated access.

Parent topic: Sources for retrieving ADI

Application context informationApplication context informationAuthorization rules might require application context information to complete an evaluation. Context information includes information that is not an entitlement but is specific to the current transaction or operation. contextinformationapplicationattributelistsapp_contextapp_context attribute listapplication context informationazn_decision_access_allowed_ext () methodAn example is a transaction amount, such as purchase price or transfer amount. This information is passed to the decision through the app_context attribute list of the azn_decision_access_allowed_ext() call. Security Access Manager WebSEAL also uses this mechanism to pass the values of certain HTML tags and HTML request data (from a get or post request) into the access decision for use in a rule evaluation.Sources for retrieving ADIThe authorization engine can gather ADI from several sources.

Application context information

Authorization rules might require application context information to complete an evaluation. Context information includes information that is not an entitlement but is specific to the current transaction or operation.

An example is a transaction amount, such as purchase price or transfer amount. This information is passed to the decision through the app_context attribute list of the azn_decision_access_allowed_ext() call. Security Access Manager WebSEAL also uses this mechanism to pass the values of certain HTML tags and HTML request data (from a get or post request) into the access decision for use in a rule evaluation.

Parent topic: Sources for retrieving ADI

Authorization engine context informationAuthorization engine context informationIf required, the authorization engine automatically provides context information before the authorization rule is evaluated. The ADI provided by the authorization engine includes the name of the protected object that is the target of the access decision. The ADI also includes the string of operations that the requesting user wants to do on the protected object.contextinformationauthorization engineretrievalentitlements serviceazn_engine_target_resource attributeazn_engine_requested_actions attributeattributesazn_engine_requested_actionsattributesazn_engine_target_resourceThe following attribute names are reserved for these data items: azn_engine_target_resourceazn_engine_requested_actionsSources for retrieving ADIThe authorization engine can gather ADI from several sources.

Authorization engine context information

If required, the authorization engine automatically provides context information before the authorization rule is evaluated. The ADI provided by the authorization engine includes the name of the protected object that is the target of the access decision. The ADI also includes the string of operations that the requesting user wants to do on the protected object.

The following attribute names are reserved for these data items:

azn_engine_target_resource

azn_engine_requested_actions

Parent topic: Sources for retrieving ADI

Dynamic ADI retrieval entitlement servicesDynamic ADI retrieval entitlement servicesThe final source for retrieving ADI is the dynamic ADI retrieval entitlements service. This class of authorization entitlement services is designed to retrieve ADI from an external source. entitlementsretrieval entitlement servicesADIretrieval entitlements servicesretrieval entitlements servicedynamic ADIThese services can be developed to retrieve ADI from an enterprise database that contains employee, customer, partner, or inventory information. The dynamic ADI retrieval service is called to retrieve ADI when the access decision is being made. Calling both at the same time has the benefit of being able to retrieve volatile data, such as quotas, at a time when its value is most current.The Security Access Manager Attribute Retrieval Service (AMWebARS, now deprecated) is an example of a service that can retrieve ADI from external sources. A replacement example uses the Web Service Description Language (WSDL) file in the Security Access Manager Application Development Kit to create and deploy a custom attribute retrieval service. See the IBM Security Access Manager for Web: Installation guide for more information about setting up the IBM Security Access Manager for Web custom attribute retrieval service. Also see the IBM Security Access Manager for Web: WebSEAL Administration Guide for more information about using the WSDL file.Now deprecated, AMWebARS was the official package name for a Security Access Manager J2EE web service that implements a dynamic ADI retrieval service. To facilitate communication between the resource manager, which is starting the rules engine, and AMWebARS, which is done with SOAP over HTTP, the Security Access Manager runtime environment (pdrte package) provides an authorization entitlement service called azn_ent_amwebars. See the Authorization C API Developer Reference for more information about developing with dynamic ADI retrieval entitlement services to fetch ADI when the rule is evaluated. See the Administration C API Developer Reference for an in-depth discussion of attribute lists, their formats, and the authorization APIs that are used to manipulate them. See Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. .Sources for retrieving ADIThe authorization engine can gather ADI from several sources.

Dynamic ADI retrieval entitlement services

The final source for retrieving ADI is the dynamic ADI retrieval entitlements service. This class of authorization entitlement services is designed to retrieve ADI from an external source.

These services can be developed to retrieve ADI from an enterprise database that contains employee, customer, partner, or inventory information. The dynamic ADI retrieval service is called to retrieve ADI when the access decision is being made. Calling both at the same time has the benefit of being able to retrieve volatile data, such as quotas, at a time when its value is most current.

The Security Access Manager Attribute Retrieval Service (AMWebARS, now deprecated) is an example of a service that can retrieve ADI from external sources.

A replacement example uses the Web Service Description Language (WSDL) file in the Security Access Manager Application Development Kit to create and deploy a custom attribute retrieval service. See the IBM Security Access Manager for Web: Installation guide for more information about setting up the IBM Security Access Manager for Web custom attribute retrieval service. Also see the IBM Security Access Manager for Web: WebSEAL Administration Guide for more information about using the WSDL file.

Now deprecated, AMWebARS was the official package name for a Security Access Manager J2EE web service that implements a dynamic ADI retrieval service. To facilitate communication between the resource manager, which is starting the rules engine, and AMWebARS, which is done with SOAP over HTTP, the Security Access Manager runtime environment (pdrte package) provides an authorization entitlement service called azn_ent_amwebars.

See the Authorization C API Developer Reference for more information about developing with dynamic ADI retrieval entitlement services to fetch ADI when the rule is evaluated. See the Administration C API Developer Reference for an in-depth discussion of attribute lists, their formats, and the authorization APIs that are used to manipulate them. See Format and constraints of rules.

Parent topic: Sources for retrieving ADI

Volatile versus nonvolatile dataVolatile versus nonvolatile dataIn general, the source for any particular piece of ADI depends largely on what the data is. The most important question is whether the data is volatile. For example, is it possible for the data to change during the lifetime of the session of the user? Is it important to use the most up-to-date information when it does change? Volatile data must be retrieved with a dynamic ADI retrieval service unless the resource manager application can provide this data.ADIsourcesources for ADIApplication-specific data that is nonvolatile and not user-specific is provided by the resource manager application. Data that is nonvolatile and user-specific is loaded into the user credential when the user is authenticated. The data is kept with the credential for the lifetime of the user session.The set of data provided by the authorization engine, including the target protected object and permissions, is fixed and cannot be changed.Access decision informationThe data and attributes in rule conditions collectively are called access decision information (ADI). Authorization API attributes, which are name and value pairs, form the basis of all ADI that can be referenced in a rule or presented to the authorization engine.

Volatile versus nonvolatile data

In general, the source for any particular piece of ADI depends largely on what the data is. The most important question is whether the data is volatile. For example, is it possible for the data to change during the lifetime of the session of the user? Is it important to use the most up-to-date information when it does change? Volatile data must be retrieved with a dynamic ADI retrieval service unless the resource manager application can provide this data.

Application-specific data that is nonvolatile and not user-specific is provided by the resource manager application. Data that is nonvolatile and user-specific is loaded into the user credential when the user is authenticated. The data is kept with the credential for the lifetime of the user session.

The set of data provided by the authorization engine, including the target protected object and permissions, is fixed and cannot be changed.

Parent topic: Access decision information

Authorization rule languageAuthorization rule languageExtensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is used for the data that forms an input to the rules. The combination of XML and XSL provides a platform independent way to express both the inputs to the rules evaluator and the rules themselves.XMLauthorizationrulesExtensibleStyle LanguageExtensibleMarkup LanguageXSLauthorizationrulesauthorizationruleslanguagesXML also supports expressing complex data types in a structured and standard manner in text format. This text format allows rules for processing the XML data to be written without having to cater to platform and programming language specifics.XSL is a functional style sheet language that can be used to do simple tasks or complex tasks that depend on your needs. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation in e-business models. XSL is built on other XML-based standards such as XPath, which is the expression language at the core of an authorization rule.To implement rules-based authorization policy, it is necessary to impose a number of constraints on the XSL rules. Constraints include the requirements that the output of the rule evaluation is simple text and that the output conforms to one of a known set of result strings. See Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. .It is also necessary to impose constraints on the XML input document that is built as input to the rule evaluation. The ADI XML document model enables the authorization engine to detect when ADI is missing. The ADI might need to be requested from the resource manager or an external entity through the dynamic ADI retrieval service interface. Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.ADI XML document modelThe ADI XML document model (or ADI XML model) is a set of restrictions placed on the XSL/XML model by the authorization rules implementation. The ADI XML model enables the interface to be simple and yet functional for authorization purposes. XML access decision informationBy default, the rule evaluator automatically transforms into XML format any name-value pair attributes passed to it by the calling application. The attributes were identified as target access decision information (ADI) for the current evaluation. XML namespace definitionsXML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules.

Authorization rule language

Extensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is used for the data that forms an input to the rules. The combination of XML and XSL provides a platform independent way to express both the inputs to the rules evaluator and the rules themselves.

XML also supports expressing complex data types in a structured and standard manner in text format. This text format allows rules for processing the XML data to be written without having to cater to platform and programming language specifics.

XSL is a functional style sheet language that can be used to do simple tasks or complex tasks that depend on your needs. XSL possesses an inherent ability to analyze and evaluate XML data, which is becoming the standard for data representation in e-business models. XSL is built on other XML-based standards such as XPath, which is the expression language at the core of an authorization rule.

To implement rules-based authorization policy, it is necessary to impose a number of constraints on the XSL rules. Constraints include the requirements that the output of the rule evaluation is simple text and that the output conforms to one of a known set of result strings. See Format and constraints of rules.

It is also necessary to impose constraints on the XML input document that is built as input to the rule evaluation. The ADI XML document model enables the authorization engine to detect when ADI is missing. The ADI might need to be requested from the resource manager or an external entity through the dynamic ADI retrieval service interface.

ADI XML document model
The ADI XML document model (or ADI XML model) is a set of restrictions placed on the XSL/XML model by the authorization rules implementation. The ADI XML model enables the interface to be simple and yet functional for authorization purposes.

XML access decision information
By default, the rule evaluator automatically transforms into XML format any name-value pair attributes passed to it by the calling application. The attributes were identified as target access decision information (ADI) for the current evaluation.

XML namespace definitions
XML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules.

Parent topic: Authorization rules management

ADI XML document modelADI XML document modelThe ADI XML document model (or ADI XML model) is a set of restrictions placed on the XSL/XML model by the authorization rules implementation. The ADI XML model enables the interface to be simple and yet functional for authorization purposes. ADIXML document modelXMLADIdocument modeldocument, ADI modelmodeldocument, ADIThe model constrains the authorization rules to function within a predetermined XML document format with the same top-level XML document element for all rules. The XML ADI is imported by the rules evaluator from credential attributes, from application context, or from other data sources. The XML ADI must be inserted into this XML document before authorization rules can use the data. Similarly to simplify the process of defining rules, the authorization rules must operate within the confines of the ADI XML model. The ADI XML model requires the XML document to contain the following top-level XML element. All target ADI for a particular rule evaluation is inserted in the top-level XML element. The XMLADI element is created automatically as part of the rule evaluation process by the authorization engine. <XMLADI> <!-- XML formatted ADI are inserted here. --> </XMLADI>As a result of this restriction, the XPath to the data used in an authorization rule must include the prefix /XMLADI to access a particular data element within the model. For example, you might add an ADI item of JohnSmith to the document to access the fields of JohnSmith within the ADI XML document. In this case, specify the XPath /XMLADI/JohnSmith to access the data contained in the XML object JohnSmith.An XPath is the path to a particular child element within the hierarchy of a structured XML data object. Much like a directory path on a hard disk drive is used to access a specific file, an XPath designation starts from the root of the document (in this case /XMLADI). The designation traces a path from this root down through its child elements to the specific element that is being referenced. For example, with the example entitlement JohnSmith in the XML entitlement exampleThe following example is an ADI XML document that might be passed to the XSL processor from the rules evaluator during the evaluation of an authorization rule. as a reference, the JohnSmith XML object has a child element called CreditCard. The child elements of the CreditCard element are attributes which are common to most credit cards. To access Balance under the CreditCard element of JohnSmith, you would use the following XPath: "/XMLADI/JohnSmith/CreditCard/Balance"XPaths like this example are the means by which authorization rules access the ADI data values that are needed to make attribute-based authorization decisions.All data elements are restricted to work within the ADI XML model. The authorization rules must also be restricted to operate on or match XPaths within the model. Therefore, XSL template match statements are also restricted to matching XPaths starting from /XMLADI within the ADI XML document. See Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. .Authorization rule languageExtensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is used for the data that forms an input to the rules. The combination of XML and XSL provides a platform independent way to express both the inputs to the rules evaluator and the rules themselves.Containers and XML ADI container namesWhen data is requested from a resource manager, the granularity of the XML data returned is at the level of a single container of information. Limitations of container namesOne restriction imposed by the ADI XML document model is that each item of ADI consumed by the rules evaluator must have a unique container name. The container name must not be confused with containers provided by other entitlements data providers.

ADI XML document model

The ADI XML document model (or ADI XML model) is a set of restrictions placed on the XSL/XML model by the authorization rules implementation. The ADI XML model enables the interface to be simple and yet functional for authorization purposes.

The model constrains the authorization rules to function within a predetermined XML document format with the same top-level XML document element for all rules. The XML ADI is imported by the rules evaluator from credential attributes, from application context, or from other data sources. The XML ADI must be inserted into this XML document before authorization rules can use the data. Similarly to simplify the process of defining rules, the authorization rules must operate within the confines of the ADI XML model. The ADI XML model requires the XML document to contain the following top-level XML element. All target ADI for a particular rule evaluation is inserted in the top-level XML element. The XMLADI element is created automatically as part of the rule evaluation process by the authorization engine.

<XMLADI>
<!--   XML formatted ADI are inserted here.  -->
</XMLADI>

As a result of this restriction, the XPath to the data used in an authorization rule must include the prefix /XMLADI to access a particular data element within the model. For example, you might add an ADI item of JohnSmith to the document to access the fields of JohnSmith within the ADI XML document. In this case, specify the XPath /XMLADI/JohnSmith to access the data contained in the XML object JohnSmith.

An XPath is the path to a particular child element within the hierarchy of a structured XML data object. Much like a directory path on a hard disk drive is used to access a specific file, an XPath designation starts from the root of the document (in this case /XMLADI). The designation traces a path from this root down through its child elements to the specific element that is being referenced. For example, with the example entitlement JohnSmith in the XML entitlement example as a reference, the JohnSmith XML object has a child element called CreditCard. The child elements of the CreditCard element are attributes which are common to most credit cards. To access Balance under the CreditCard element of JohnSmith, you would use the following XPath:

"/XMLADI/JohnSmith/CreditCard/Balance"

XPaths like this example are the means by which authorization rules access the ADI data values that are needed to make attribute-based authorization decisions.

All data elements are restricted to work within the ADI XML model. The authorization rules must also be restricted to operate on or match XPaths within the model. Therefore, XSL template match statements are also restricted to matching XPaths starting from /XMLADI within the ADI XML document. See Format and constraints of rules.

Containers and XML ADI container names
When data is requested from a resource manager, the granularity of the XML data returned is at the level of a single container of information.

Limitations of container names
One restriction imposed by the ADI XML document model is that each item of ADI consumed by the rules evaluator must have a unique container name. The container name must not be confused with containers provided by other entitlements data providers.

Parent topic: Authorization rule language

Containers and XML ADI container namesContainers and XML ADI container namesWhen data is requested from a resource manager, the granularity of the XML data returned is at the level of a single container of information. ADIcontainers and container namesXMLADIcontainers and container namescontainernamesADI containersThe container is normally also the smallest data element (for example, elements that might be considered for billing purposes). This convention was adopted for the ADI XML model as well. The ADI that is used in authorization rules is also defined and manipulated as containers of XML data. For example, the JohnSmith XML object defined in XML entitlement exampleThe following example is an ADI XML document that might be passed to the XSL processor from the rules evaluator during the evaluation of an authorization rule. is an example of an ADI container.The top-most element in the definition of an item of ADI is termed the container name of that item of ADI. To define an authorization rule, always reference the XPath to the XML definition of data in any ADI container. Specify the name of the container as the first element /XMLADI in the XPath specification for the data element.Returning to the example ADI item JohnSmith, you can assume that there is a container received from the data provider named JohnSmith. To access any element within the JohnSmith container, the XPath specification must be prefixed with JohnSmith. For example, JohnSmith/CreditCard/AcctNumber refers to the AcctNumber value. To access this information from within an authorization rule, this XPath must also be prefixed by the top-level element of the XML target ADI input document. The element is XMLADI (for example, /XMLADI/JohnSmith/CreditCard/AcctNumber). However, both of these XPaths are valid when used in an authorization rule. The validity is due to the default template match statement that is added to all authorization rules that do not explicitly include one. The default template match statement matches the ADI XML document from /XMLADI. JohnSmith can be referred to either with a relative reference or with an absolute reference that is prefixed with /XMLADI. See Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. .ADI XML document modelThe ADI XML document model (or ADI XML model) is a set of restrictions placed on the XSL/XML model by the authorization rules implementation. The ADI XML model enables the interface to be simple and yet functional for authorization purposes.

Containers and XML ADI container names

When data is requested from a resource manager, the granularity of the XML data returned is at the level of a single container of information.

The container is normally also the smallest data element (for example, elements that might be considered for billing purposes). This convention was adopted for the ADI XML model as well. The ADI that is used in authorization rules is also defined and manipulated as containers of XML data. For example, the JohnSmith XML object defined in XML entitlement example is an example of an ADI container.

The top-most element in the definition of an item of ADI is termed the container name of that item of ADI. To define an authorization rule, always reference the XPath to the XML definition of data in any ADI container. Specify the name of the container as the first element /XMLADI in the XPath specification for the data element.

Returning to the example ADI item JohnSmith, you can assume that there is a container received from the data provider named JohnSmith. To access any element within the JohnSmith container, the XPath specification must be prefixed with JohnSmith. For example, JohnSmith/CreditCard/AcctNumber refers to the AcctNumber value. To access this information from within an authorization rule, this XPath must also be prefixed by the top-level element of the XML target ADI input document. The element is XMLADI (for example, /XMLADI/JohnSmith/CreditCard/AcctNumber). However, both of these XPaths are valid when used in an authorization rule. The validity is due to the default template match statement that is added to all authorization rules that do not explicitly include one. The default template match statement matches the ADI XML document from /XMLADI. JohnSmith can be referred to either with a relative reference or with an absolute reference that is prefixed with /XMLADI. See Format and constraints of rules.

Parent topic: ADI XML document model

Limitations of container namesLimitations of container namesOne restriction imposed by the ADI XML document model is that each item of ADI consumed by the rules evaluator must have a unique container name. The container name must not be confused with containers provided by other entitlements data providers. ADIlimitationsXMLADIdocument model restrictionrestriction, ADI XML document modelcontainernameslimitationsFor example, two different data providers might provide a data item called TxInfo. The rules evaluator does know to which provider it must make a request to get this item of data. To help differentiate items of ADI with the same name, XML provides defining namespaces for data. The namespace ID of the namespace can then be used to differentiate one ADI element from another. For TxInfo, you might define a namespace companyA and reference this instance of ADI with companyA:TxInfo. See XML namespace definitionsXML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules. .This restriction on naming containers among data providers is not enforced by the authorization engine. If the engine encounters multiple instances of the same item of ADI (for example, TxInfo), it adds them all to the ADI XML document for use in the evaluation. In the ADI XML document, there can be two items of ADI data with the same container name within the ADI XML input document. The assumption is then made that they are structured in the exact same way. For example, a particular application request might involve a number of individual transactions, each with its own transaction amount. An authorization rule can be formulated to add all these items together. The rule compares the sum of the items to a predefined total transactions limit or to a per-transaction limit with an XSL node select statement. Example: ADI from dynamic ADI retrieval servicesThis example evaluates an application-defined XML input document that is provided by a dynamic entitlement service that was written with the dynamic ADI retrieval service. in the Examples of authorization rulesThese examples demonstrate how rules can be implemented. section shows an example rule. The rule sums multiple transaction elements in this way and even counts the number of instances of a particular ADI element.ADI XML document modelThe ADI XML document model (or ADI XML model) is a set of restrictions placed on the XSL/XML model by the authorization rules implementation. The ADI XML model enables the interface to be simple and yet functional for authorization purposes.

Limitations of container names

One restriction imposed by the ADI XML document model is that each item of ADI consumed by the rules evaluator must have a unique container name. The container name must not be confused with containers provided by other entitlements data providers.

For example, two different data providers might provide a data item called TxInfo. The rules evaluator does know to which provider it must make a request to get this item of data. To help differentiate items of ADI with the same name, XML provides defining namespaces for data. The namespace ID of the namespace can then be used to differentiate one ADI element from another. For TxInfo, you might define a namespace companyA and reference this instance of ADI with companyA:TxInfo. See XML namespace definitions.

This restriction on naming containers among data providers is not enforced by the authorization engine. If the engine encounters multiple instances of the same item of ADI (for example, TxInfo), it adds them all to the ADI XML document for use in the evaluation. In the ADI XML document, there can be two items of ADI data with the same container name within the ADI XML input document. The assumption is then made that they are structured in the exact same way. For example, a particular application request might involve a number of individual transactions, each with its own transaction amount. An authorization rule can be formulated to add all these items together. The rule compares the sum of the items to a predefined total transactions limit or to a per-transaction limit with an XSL node select statement. Example: ADI from dynamic ADI retrieval services in the Examples of authorization rules section shows an example rule. The rule sums multiple transaction elements in this way and even counts the number of instances of a particular ADI element.

Parent topic: ADI XML document model

XML access decision informationXML access decision informationBy default, the rule evaluator automatically transforms into XML format any name-value pair attributes passed to it by the calling application. The attributes were identified as target access decision information (ADI) for the current evaluation. ADIname/value pair attributesXMLADIname/value pair attributesattributename, XMLWhen transforming the attribute to XML, the attribute name is used as the container name of the XML data item. The attribute value is converted into an XML value. The container name of an item of ADI equates to the XML element name in the XML definition. For example, the following XML data is generated for attribute name VPS_CREDIT_CARD with a string attribute value of 5517 3394 8324 0965: <VPS_CREDIT_CARD>5517 3394 8324 0965</VPS_CREDIT_CARD>The container name and XML element name in this case is VPS_CREDIT_CARD. The graphical user interface, the command-line interface, and the Security Access Manager authorization API attribute list interfaces do not permit the administrator to define rules that contain invalid XML container names.The application might pass entitlements or application context that are already formatted as XML for an access decision. In this case, the authorization rules evaluator expects the data to be of type azn_string_t and expects the format of the string to be XML. The attribute name must match the container name of the XML data item. If the names do not match, the evaluator does not evaluate the rule correctly.The evaluator identifies XML format data by locating the less than (<) character at the beginning of the attribute value. If the attribute value does not begin with a less than character, the data is not considered to be an XML data item. The evaluator attempts to convert the data item to XML format automatically. This means of identification is used only on attributes or application context identified as target ADI for the access decision. Non-XML attribute values that start with a less than character cannot be used by the application. An error status is returned from the authorization decision. If the data is not correct XML, the XSL processor fails and returns an error to denote the failure.Data items that must be defined in XML must be entirely defined in XML. Definition must not rely on the translation mechanism for non-XML items to generate the appropriate XML element name automatically. For example, to define an attribute to contain the XML definition of MY_CREDIT_CARD_NUM, you must add an attribute with the attribute name MY_CREDIT_CARD_NUM. The attribute value for MY_CREDIT_CARD_NUM is:<MY_CREDIT_CARD_NUM>5517 3394 8324 0965</MY_CREDIT_CARD_NUM>By defining the XML element as opposed to defining only its value, XML attributes can be added to the element definition. The addition does not affect the name by which the ADI is referred to when talking with data providers.In the following definition of the XML item MY_CREDIT_CARD_NUM, the CardType XML attribute has the value of "visa". XML attributes are defined in the element start tag of the element to which they apply. XML attributes are equivalent to any other first-level child element of the XML object. To reference the attribute CardType, the required XPath is: /XMLADI/MY_CREDIT_CARD_NUM/CardTypeXML attributes must not be confused with the authorization API attributes and attribute lists that are used to carry data into and out of the authorization process. <MY_CREDIT_CARD_NUM CardType="visa"> 5517 3394 8324 0965 </MY_CREDIT_CARD_NUM>The ability to add XML attributes to an element definition is useful when it comes to defining a namespace for the data item. See XML namespace definitionsXML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules. .If the ADI attribute contains multiple attribute values (string, XML, or any combination), the evaluator converts each attribute value as a separate instance of ADI. For example, the TxData attribute has values of 100 and 500. The evaluator inserts the following XML item declarations into the ADI XML document: <TxData>100</TxData> <TxData>500</TxData>The policy administrator can then design an authorization rule that uses XSL language node selection statements to work with these two values independently. Alternatively, the authorization rule can add the values and compare the total with some predefined limit. If TxData is compared to a value, it is treated as a node set comparison where each TxData value is compared to the data. Success is indicated when any of the TxData values equal the target data. Node set comparisons have slightly different behavior than expected when using the != operator. In most cases, use the not() function instead. For information about when to use != and not() when comparing a node set, see Example: ADI from dynamic ADI retrieval servicesThis example evaluates an application-defined XML input document that is provided by a dynamic entitlement service that was written with the dynamic ADI retrieval service..Authorization rule languageExtensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is used for the data that forms an input to the rules. The combination of XML and XSL provides a platform independent way to express both the inputs to the rules evaluator and the rules themselves.XML entitlement exampleThe following example is an ADI XML document that might be passed to the XSL processor from the rules evaluator during the evaluation of an authorization rule.

XML access decision information

By default, the rule evaluator automatically transforms into XML format any name-value pair attributes passed to it by the calling application. The attributes were identified as target access decision information (ADI) for the current evaluation.

When transforming the attribute to XML, the attribute name is used as the container name of the XML data item. The attribute value is converted into an XML value. The container name of an item of ADI equates to the XML element name in the XML definition. For example, the following XML data is generated for attribute name VPS_CREDIT_CARD with a string attribute value of 5517 3394 8324 0965:

<VPS_CREDIT_CARD>5517 3394 8324 0965</VPS_CREDIT_CARD>

The container name and XML element name in this case is VPS_CREDIT_CARD. The graphical user interface, the command-line interface, and the Security Access Manager authorization API attribute list interfaces do not permit the administrator to define rules that contain invalid XML container names.

The application might pass entitlements or application context that are already formatted as XML for an access decision. In this case, the authorization rules evaluator expects the data to be of type azn_string_t and expects the format of the string to be XML. The attribute name must match the container name of the XML data item. If the names do not match, the evaluator does not evaluate the rule correctly.

The evaluator identifies XML format data by locating the less than (<) character at the beginning of the attribute value. If the attribute value does not begin with a less than character, the data is not considered to be an XML data item. The evaluator attempts to convert the data item to XML format automatically. This means of identification is used only on attributes or application context identified as target ADI for the access decision. Non-XML attribute values that start with a less than character cannot be used by the application. An error status is returned from the authorization decision. If the data is not correct XML, the XSL processor fails and returns an error to denote the failure.

Data items that must be defined in XML must be entirely defined in XML. Definition must not rely on the translation mechanism for non-XML items to generate the appropriate XML element name automatically. For example, to define an attribute to contain the XML definition of MY_CREDIT_CARD_NUM, you must add an attribute with the attribute name MY_CREDIT_CARD_NUM. The attribute value for MY_CREDIT_CARD_NUM is:

<MY_CREDIT_CARD_NUM>5517 3394 8324 0965</MY_CREDIT_CARD_NUM>

By defining the XML element as opposed to defining only its value, XML attributes can be added to the element definition. The addition does not affect the name by which the ADI is referred to when talking with data providers.

In the following definition of the XML item MY_CREDIT_CARD_NUM, the CardType XML attribute has the value of "visa". XML attributes are defined in the element start tag of the element to which they apply. XML attributes are equivalent to any other first-level child element of the XML object. To reference the attribute CardType, the required XPath is:

/XMLADI/MY_CREDIT_CARD_NUM/CardType

XML attributes must not be confused with the authorization API attributes and attribute lists that are used to carry data into and out of the authorization process.

<MY_CREDIT_CARD_NUM CardType="visa">
   5517 3394 8324 0965
</MY_CREDIT_CARD_NUM>

The ability to add XML attributes to an element definition is useful when it comes to defining a namespace for the data item. See XML namespace definitions.

If the ADI attribute contains multiple attribute values (string, XML, or any combination), the evaluator converts each attribute value as a separate instance of ADI. For example, the TxData attribute has values of 100 and 500. The evaluator inserts the following XML item declarations into the ADI XML document:

<TxData>100</TxData>
<TxData>500</TxData>

The policy administrator can then design an authorization rule that uses XSL language node selection statements to work with these two values independently. Alternatively, the authorization rule can add the values and compare the total with some predefined limit. If TxData is compared to a value, it is treated as a node set comparison where each TxData value is compared to the data. Success is indicated when any of the TxData values equal the target data. Node set comparisons have slightly different behavior than expected when using the != operator. In most cases, use the not() function instead. For information about when to use != and not() when comparing a node set, see Example: ADI from dynamic ADI retrieval services.

XML entitlement example
The following example is an ADI XML document that might be passed to the XSL processor from the rules evaluator during the evaluation of an authorization rule.

Parent topic: Authorization rule language

XML entitlement exampleXML entitlement exampleThe following example is an ADI XML document that might be passed to the XSL processor from the rules evaluator during the evaluation of an authorization rule. XMLentitlement document exampleentitlementsexample, XMLThe document contains two containers: JohnSmith and AmountReqd. The attribute value of the container JohnSmith is defined in XML. The AmountReqd container is translated to XML from an incoming string application context attribute. The container JohnSmith is an entitlement and the container AmountReqd is an item of transaction context.The authorization rules evaluator automatically encompasses all the data under the XML top-level node declaration XMLADI when the ADI XML document is created. This top-level element was added for clarity.The XML document that is passed to the evaluation routines by the authorization rules evaluator is as follows: <XMLADI> <JohnSmith> <CreditCard> <AcctNumber>0123456776543210</AcctNumber> <Limit>10000.00</Limit> <Balance>2000.00</Balance> </CreditCard> <MileagePlus> <MemberStatus>100k</MemberStatus> <CardNumber>12345678</CardNumber> <MileagePlus> <JohnSmith> <AmountReqd>500.00</AmountReqd> </XMLADI>When referencing a particular ADI item in the XMLADI document available to a rule, the XPath path specifier can begin from the container name of the XML element. For example, the name might be JohnSmith. The default template rule matches the /XMLADI element automatically. If the callers want to specify their own template match statement explicitly, they can do so.In this example, the ADI container names are JohnSmith and AmountReqd. See Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. .XML access decision informationBy default, the rule evaluator automatically transforms into XML format any name-value pair attributes passed to it by the calling application. The attributes were identified as target access decision information (ADI) for the current evaluation.

XML entitlement example

The following example is an ADI XML document that might be passed to the XSL processor from the rules evaluator during the evaluation of an authorization rule.

The document contains two containers: JohnSmith and AmountReqd. The attribute value of the container JohnSmith is defined in XML. The AmountReqd container is translated to XML from an incoming string application context attribute. The container JohnSmith is an entitlement and the container AmountReqd is an item of transaction context.

The authorization rules evaluator automatically encompasses all the data under the XML top-level node declaration XMLADI when the ADI XML document is created. This top-level element was added for clarity.

The XML document that is passed to the evaluation routines by the authorization rules evaluator is as follows:

<XMLADI>
  <JohnSmith>
    <CreditCard>
      <AcctNumber>0123456776543210</AcctNumber>
      <Limit>10000.00</Limit>
      <Balance>2000.00</Balance>
    </CreditCard>
    <MileagePlus>
      <MemberStatus>100k</MemberStatus>
      <CardNumber>12345678</CardNumber>
    <MileagePlus>
  <JohnSmith>
  <AmountReqd>500.00</AmountReqd>
</XMLADI>

When referencing a particular ADI item in the XMLADI document available to a rule, the XPath path specifier can begin from the container name of the XML element. For example, the name might be JohnSmith. The default template rule matches the /XMLADI element automatically. If the callers want to specify their own template match statement explicitly, they can do so.

In this example, the ADI container names are JohnSmith and AmountReqd. See Format and constraints of rules.

Parent topic: XML access decision information

XML namespace definitionsXML namespace definitionsXML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules. XMLnamespace definitionsFor example, a customer database and a product inventory database might both define ADI called name that might be used in authorization rules. By defining an XML namespace with the namespace ID item, you can differentiate between the two instances of name by calling the ADI from the product database item:name. This example provides a namespace definition for the item namespace: xmlns:item="http://mycompany/namespaces/itemswhere xmlns is a standard XML attribute name and item is the namespace ID chosen for the namespace. The URI following the = is used to distinguish one namespace ID from another.This namespace declaration associates the namespace ID item with the URI string: http://mycompany/namespaces/itemsThe value of the URI string is of no consequence to the XML and XSL processors but it must be unique. Unlike the XML and XSL processors, the Security Access Manager authorization engine does not permit two namespace IDs to be assigned the same URI value. The Security Access Manager authorization engine uses the URI to uniquely identify the namespaces. Defining two namespaces with the same URI results in an initialization error. The authorization application cannot start, and an error is logged to the error log of the application. The source from which the item name is to be obtained must be aware of this relationship. The source must be able to make the connection between the item:name requested by the authorization engine and the name data stored in the product database. The source must also be able to provide this data to the authorization engine in an attribute called item:name when it is needed. For example, a dynamic ADI retrieval service must understand that, when it is asked for item:name, it must fetch the required value by looking for name in the product database. The service needs to return the data to the authorization engine in an attribute called item:name. When an application uses namespaces to differentiate or aggregate ADI items, it is required to define the namespace for both the XML and XSL processors.To define a namespace for the XSL processor, add the namespace definition to the xsl-stylesheet-prolog configuration file entry described in input-adi-xml-prolog and xsl-stylesheet-prologYou can use the input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries to change the XML and XSL prolog statements. These statements are appended to the ADI XML document and authorization rule style sheet before they are passed to the rules evaluator for processing. . This example shows how to add a namespace definition for the item namespace to the xsl-stylesheet-prolog entry: xsl-stylesheet-prolog = <?xml version='1.0' encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:item="http://mycompany/namespaces/items" version='1.0'> <xsl:output method = 'text' omit-xml-declaration='yes' encoding='UTF-8' indent='no'/> <xsl:template match='text()'> </xsl:template>There are two ways to define a namespace prefix to the XML processor: Define the namespace globally for the entire XMLADI document.Define it individually in those ADI items that use the prefix. In both cases, the namespace declaration must be included in the start tag for the XML element.The first and simplest method of defining a namespace for the XML processor is to add the namespace definition to the XMLADI document element start tag. Adding the definition to the XMLADI document element start tag is easiest to do because it automatically defines the namespace for the entire document. Any ADI items in the document whose names are prefixed with this namespace ID do not have to have the namespace definition added to their own element start tag. This method does not suffer any of the drawbacks of defining the namespace by using the second method. The [xmladi-attribute-definitions] stanza was added to the configuration file to allow customers to define namespaces globally for use in the XMLADI document. For information about how to add a namespace definition to the [xmladi-attribute-definitions] stanza, see [xmladi-attribute-definitions]The [xmladi-attribute-definitions] stanza enables customers to add XML attribute definitions, such as XML namespace definitions, to the XMLADI document start tag. .The second method of specifying an XML namespace definition to the XML processor is to add the definition to the XML value of the ADI element. For example, to add the XML namespace definition to the item:name XML item with a string value of Widget A, you would define item:name in XML as follows: <item:name xmlns:item="http://mycompany/namespaces/items"> Widget A </item:name>The ADI item:name must be added to an attribute list with the item:name attribute name. Its value is the entire XML element definition in the example entered as a single contiguous text string. There are some drawbacks to defining the XML namespace in the XML definition of each ADI item rather than defining it globally for the entire XML ADI document. For instance, the value of any ADI items that use a namespace ID prefix must be in XML. The namespace definition can be added only to the XML definition of the value of the item, as demonstrated for item:name in the example. As a result, items of ADI with namespace prefixes cannot have the value 100. The value of the item must be an XML fragment, such as the string <prefix:adi_name>100</prefix:adi_name>. Any ADI source that can provide values for namespace prefixed ADI items must ensure that the appropriate namespace definitions for the item are added to each XML formatted value that it returns. When the service does not normally return XML formatted data and is not aware of namespace prefixes, you must changed it. The change causes an increased processing load for dynamic ADI retrieval services. By defining the namespace globally, you can avoid all of these complications. If a namespace is not defined for either the XML or XSL processors, an error is logged to the application error logs. The error indicates that the namespace ID does not have an associated URI mapping. This problem might occur during the creation of the rule if the XSL processor is not notified of the new namespace. The problem might occur during rule evaluation if the XML processor is not notified.Authorization rule languageExtensible Style Language (XSL) is the language that specifies rules. Extensible Markup Language (XML) is used for the data that forms an input to the rules. The combination of XML and XSL provides a platform independent way to express both the inputs to the rules evaluator and the rules themselves.

XML namespace definitions

XML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules.

For example, a customer database and a product inventory database might both define ADI called name that might be used in authorization rules. By defining an XML namespace with the namespace ID item, you can differentiate between the two instances of name by calling the ADI from the product database item:name. This example provides a namespace definition for the item namespace:

xmlns:item="http://mycompany/namespaces/items

where xmlns is a standard XML attribute name and item is the namespace ID chosen for the namespace. The URI following the = is used to distinguish one namespace ID from another.

This namespace declaration associates the namespace ID item with the URI string:

http://mycompany/namespaces/items

The value of the URI string is of no consequence to the XML and XSL processors but it must be unique. Unlike the XML and XSL processors, the Security Access Manager authorization engine does not permit two namespace IDs to be assigned the same URI value. The Security Access Manager authorization engine uses the URI to uniquely identify the namespaces. Defining two namespaces with the same URI results in an initialization error. The authorization application cannot start, and an error is logged to the error log of the application.

The source from which the item name is to be obtained must be aware of this relationship. The source must be able to make the connection between the item:name requested by the authorization engine and the name data stored in the product database. The source must also be able to provide this data to the authorization engine in an attribute called item:name when it is needed. For example, a dynamic ADI retrieval service must understand that, when it is asked for item:name, it must fetch the required value by looking for name in the product database. The service needs to return the data to the authorization engine in an attribute called item:name. When an application uses namespaces to differentiate or aggregate ADI items, it is required to define the namespace for both the XML and XSL processors.

To define a namespace for the XSL processor, add the namespace definition to the xsl-stylesheet-prolog configuration file entry described in input-adi-xml-prolog and xsl-stylesheet-prolog. This example shows how to add a namespace definition for the item namespace to the xsl-stylesheet-prolog entry:

xsl-stylesheet-prolog = <?xml version='1.0' encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
     xmlns:item="http://mycompany/namespaces/items" version='1.0'>
<xsl:output method = 'text' omit-xml-declaration='yes'
     encoding='UTF-8' indent='no'/>
<xsl:template match='text()'>
</xsl:template>

There are two ways to define a namespace prefix to the XML processor:

Define the namespace globally for the entire XMLADI document.

Define it individually in those ADI items that use the prefix.

In both cases, the namespace declaration must be included in the start tag for the XML element.

The first and simplest method of defining a namespace for the XML processor is to add the namespace definition to the XMLADI document element start tag. Adding the definition to the XMLADI document element start tag is easiest to do because it automatically defines the namespace for the entire document. Any ADI items in the document whose names are prefixed with this namespace ID do not have to have the namespace definition added to their own element start tag.

This method does not suffer any of the drawbacks of defining the namespace by using the second method. The [xmladi-attribute-definitions] stanza was added to the configuration file to allow customers to define namespaces globally for use in the XMLADI document. For information about how to add a namespace definition to the [xmladi-attribute-definitions] stanza, see [xmladi-attribute-definitions].

The second method of specifying an XML namespace definition to the XML processor is to add the definition to the XML value of the ADI element. For example, to add the XML namespace definition to the item:name XML item with a string value of Widget A, you would define item:name in XML as follows:

<item:name xmlns:item="http://mycompany/namespaces/items">
  Widget A
</item:name>

The ADI item:name must be added to an attribute list with the item:name attribute name. Its value is the entire XML element definition in the example entered as a single contiguous text string.

There are some drawbacks to defining the XML namespace in the XML definition of each ADI item rather than defining it globally for the entire XML ADI document. For instance, the value of any ADI items that use a namespace ID prefix must be in XML. The namespace definition can be added only to the XML definition of the value of the item, as demonstrated for item:name in the example. As a result, items of ADI with namespace prefixes cannot have the value 100. The value of the item must be an XML fragment, such as the string <prefix:adi_name>100</prefix:adi_name>.

Any ADI source that can provide values for namespace prefixed ADI items must ensure that the appropriate namespace definitions for the item are added to each XML formatted value that it returns. When the service does not normally return XML formatted data and is not aware of namespace prefixes, you must changed it. The change causes an increased processing load for dynamic ADI retrieval services.

By defining the namespace globally, you can avoid all of these complications. If a namespace is not defined for either the XML or XSL processors, an error is logged to the application error logs. The error indicates that the namespace ID does not have an associated URI mapping. This problem might occur during the creation of the rule if the XSL processor is not notified of the new namespace. The problem might occur during rule evaluation if the XML processor is not notified.

Parent topic: Authorization rule language

Authorization rules evaluatorAuthorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.authorizationrulesevaluatorevaluator, authorization rulesauthorizationrulesdelimitersdelimiters, authorization rules evaluatorThe authorization rules evaluator takes the rule policy that is attached to the target protected object and evaluates the rule by calling the XSL processor. The input XML document for the transformation contains a definition for how the authorization engine can retrieve one of the following sources for the ADI: User credential entitlements that request the authorizationApplication context information that is passed in by the access decision call (passed in by the resource manager)Security Access Manager authorization engine contextDynamic ADI retrieval entitlement servicesThe authorization engine expects the rules evaluation to result in the return of one of the string identifiers as shown in Table 1. These identifiers ensure uniqueness when an XSL rule is written incorrectly and the evaluation returns incorrect information. Delimiting the identifiers with an exclamation point (!) enables the evaluator to identify errant cases. String identifiers returned by rules evaluationDelimiterMeaning!TRUE!Access is permitted.!FALSE!Access is denied.!INDIFFERENT!The rules engine has no opinion.The identifiers must be the only text in the output document, although they can be surrounded by white space. A value other than the defined valid values or an empty document might be returned. In this case, the access decision fails and an error code is returned to the resource manager to indicate that the rule is not compliant. The format of an authorization rule is outlined in Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. .In addition, the maximum length of any result text that is returned by a rule evaluation is limited to 1023 characters. Rules returning more text than this limit cause the access decision to fail at run time with a minor error code of ivacl_s_rule_result_string_too_large.Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.Format and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. Examples of authorization rulesThese examples demonstrate how rules can be implemented. Methods of providing ADI to the rules evaluatorA resource manager application can provide ADI from the resource manager to the rules evaluator in one of two ways. One method is to add the attributes to the application context parameter. The other method is to configure the rules evaluator to supply the missing ADI to the authorization engine only when it is explicitly requested.Reason codes for rule failuresThis feature allows the target application to fail or permit the access request based on the rule failure reason code it is given by the resource manager.

Authorization rules evaluator

The authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.

The authorization rules evaluator takes the rule policy that is attached to the target protected object and evaluates the rule by calling the XSL processor. The input XML document for the transformation contains a definition for how the authorization engine can retrieve one of the following sources for the ADI:

User credential entitlements that request the authorization

Application context information that is passed in by the access decision call (passed in by the resource manager)

Security Access Manager authorization engine context

Dynamic ADI retrieval entitlement services

The authorization engine expects the rules evaluation to result in the return of one of the string identifiers as shown in Table 172. These identifiers ensure uniqueness when an XSL rule is written incorrectly and the evaluation returns incorrect information. Delimiting the identifiers with an exclamation point (!) enables the evaluator to identify errant cases.

Table 172. String identifiers returned by rules evaluation

Delimiter | Meaning
!TRUE! | Access is permitted.
!FALSE! | Access is denied.
!INDIFFERENT! | The rules engine has no opinion.

The identifiers must be the only text in the output document, although they can be surrounded by white space. A value other than the defined valid values or an empty document might be returned. In this case, the access decision fails and an error code is returned to the resource manager to indicate that the rule is not compliant. The format of an authorization rule is outlined in Format and constraints of rules.

In addition, the maximum length of any result text that is returned by a rule evaluation is limited to 1023 characters. Rules returning more text than this limit cause the access decision to fail at run time with a minor error code of ivacl_s_rule_result_string_too_large.

Format and constraints of rules
An authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file.

Examples of authorization rules
These examples demonstrate how rules can be implemented.

Methods of providing ADI to the rules evaluator
A resource manager application can provide ADI from the resource manager to the rules evaluator in one of two ways. One method is to add the attributes to the application context parameter. The other method is to configure the rules evaluator to supply the missing ADI to the authorization engine only when it is explicitly requested.

Reason codes for rule failures
This feature allows the target application to fail or permit the access request based on the rule failure reason code it is given by the resource manager.

Parent topic: Authorization rules management

Format and constraints of rulesFormat and constraints of rulesAn authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file. authorizationrulesformat and constraintsformat, authorization rulesconstraints, authorization rulesstring identifiersazn_entitlement_get_entitlements() methodXSLxsl:template statementThe rule must be written in a valid XSL template rule format and must return a text document that contains one of the following string identifiers: !TRUE!!FALSE!!INDIFFERENT!The identifiers must be the only text in the output document but they can be surrounded by white space. The identifiers are not case-sensitive. A value other than one of the identifiers listed or an empty document might be returned. The access decision fails and an error code is returned to the resource manager to indicate that the rule is not compliant. See Authorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine..For authorization decisions, the rule must return the expected decision data to the rules evaluator. The data that is returned from the rules-driven entitlements interface must be able to be expressed as a text name-value attribute pair in the entitlements output parameter of the azn_entitlement_get_entitlements() method. Many data providers return entitlements data in XML format. No additional transformation is required to pass these entitlements into the rules evaluator as ADI.All ADI that is passed to the rules evaluator must be specified in XML. Non-XML ADI that is passed to the access decision or retrieved from the credential is formatted into XML by the evaluator before an authorization rule can be evaluated.The result of the XSL transformation done by an XSL authorization rule must be a text output document that contains only one of the supported string identifiers.The following example references the XML data item that is defined in JohnSmith. The condition that the following example rule evaluates is expressed, as follows: if ((AmountReqd + Credit Card Balance) < Credit Card Limit && MileagePlus Status is "100k")The corresponding authorization rule is: <xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance) &lt; JohnSmith/CreditCard/Limit and JohnSmith/MileagePlus/MemberStatus = '100k'"> !TRUE! </xsl:if>This example rule is the simplest form for specifying an authorization rule. It does not include its own template match statement and it accepts the default template match statement, which is set to /XMLADI. Template match statements are an XSL language construct that is used to select the point in the hierarchy of an XML document at which the XSL rules, which are contained within the template match statement, are applied. The default template match statement of the ADI XML model matches from the top of the XMLADI document by specifying the XPath /XMLADI.To add your own template match statement to a rule definition, only two additional lines are needed. For example, you might rewrite the example to include your own explicit template match statement that matches from the root of the XMLADI document. Modify the rule as follows: <xsl:template match="/XMLADI"> <xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance) &lt; JohnSmith/CreditCard/Limit and JohnSmith/MileagePlus/MemberStatus = '100k') !TRUE! </xsl:if> </xsl:template>To reference any data item in the document, the XPath to each node must include the XMLADI node. For example, to access the credit card balance, the full path would be /XMLADI/JohnSmith/CreditCard/Balance. When a rule is built, the rule writer must understand what the correct XPath is from the current point in the tree. The XPath accesses the XML data nodes and subnodes. The current point in the tree is selected with the template match statement. The template match statement allows an XSL programmer to shorten the XPath to each data element by specifying that the XPath processing occur further down the XML document tree.The <xsl:template match="/XMLADI"> statement tells the XSL processor that all relative XPaths within the bounds of the template statement must be assumed to be relative to the node XMLADI. To shorten the XPaths even further, the template match statement can be set at /XMLADI/JohnSmith. In this case, the credit card balance might be termed CreditCard/Balance.Policy administrators must also make the following assumptions about the XSL style sheet document that is created by the rules evaluator to contain the rule that they devise: If a style sheet prolog is specified in the azn client configuration file, that prolog is imported into the empty style sheet. If no prolog is specified, the following default prolog is used instead: <!-- Required for XSLT language --> <?xml version="1.0" encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <!-- Required to constrain output of rule evaluation --> <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/> <!-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template>Among other things, this prolog sets the XSL style sheet syntax to version 1.0, which is supported by the embedded XSL processor. The prolog sets the namespace for XSL documents to xsl, which requires that all XSL language-specific identities be prefixed by xsl:. This prefix is the standard mode of operation for XSL style sheets. Most attributes in this prolog must be in the style sheet. If not, the results that are returned from the rules evaluator do not conform to the expected results.All authorization rules must be enclosed in an xsl:template match statement. If the rule is defined with its own xsl:template match statement, the rule is accepted as is. This acceptance allows the rule creator to specify the level within the ADI XML document at which the rule matches data items. In this case, the match statement must be the first statement encountered by the evaluator when validating the rule. Otherwise, it is assumed that there is no template match statement. If there is a match statement but the match statement does not begin with the /XMLADI absolute path, the rule is returned as not valid. Relative match statements are not accepted at this level.If no match statement is specified in the rule, the rule is automatically enclosed in the following match statement: <xsl:template match="/XMLADI"> ... <xsl:template>Therefore, all rules devised without an explicit template match statement must use XPath expressions that assume the XML context node is /XMLADI. The XPath expression for any ADI item must begin with the container name of the item and must be fully qualified.Authorization rules are processed internally with a recursive algorithm. Avoid creating very long logical expressions that can exhaust the system stack. Long expressions are problematic on systems that have a small stack by default. For example, this rule might exhaust the system stack:<xsl:choose><xsl:when test="(((azn_cred_principal_name='9410431')) \ or ((azn_cred_principal_name='user1')) \ or ((azn_cred_principal_name='user2')) \ ... or ((azn_cred_principal_name='user500'))\ )">!TRUE!</xsl:when><xsl:otherwise>!FALSE!</xsl:otherwise></xsl:choose>A better option is to add the users to a group and write a rule to check group membership.As a preventive measure two new options are added: xsl-max-logical-expressionsxsl-eval-expressions-checkThe xsl-max-logical-expressions option limits the number of logical 'or' and 'and' operators in a logical expression when a rule is created. The xsl-eval-expressions-check option uses the value from the xsl-max-logical-expressions option to limit the same logical operators when a rule is evaluated.See the [aznapi-configuration] stanza in IBM Security Access Manager for Web: Plug-in for Web Servers Administration Guide.Authorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.

Format and constraints of rules

An authorization rule must be defined as an XSL template in an XSL style sheet with the style sheet prolog that is specified in the configuration file.

The rule must be written in a valid XSL template rule format and must return a text document that contains one of the following string identifiers:

!TRUE!

!FALSE!

!INDIFFERENT!

The identifiers must be the only text in the output document but they can be surrounded by white space. The identifiers are not case-sensitive. A value other than one of the identifiers listed or an empty document might be returned. The access decision fails and an error code is returned to the resource manager to indicate that the rule is not compliant. See Authorization rules evaluator.

For authorization decisions, the rule must return the expected decision data to the rules evaluator. The data that is returned from the rules-driven entitlements interface must be able to be expressed as a text name-value attribute pair in the entitlements output parameter of the azn_entitlement_get_entitlements() method. Many data providers return entitlements data in XML format. No additional transformation is required to pass these entitlements into the rules evaluator as ADI.

All ADI that is passed to the rules evaluator must be specified in XML. Non-XML ADI that is passed to the access decision or retrieved from the credential is formatted into XML by the evaluator before an authorization rule can be evaluated.

The result of the XSL transformation done by an XSL authorization rule must be a text output document that contains only one of the supported string identifiers.

The following example references the XML data item that is defined in JohnSmith. The condition that the following example rule evaluates is expressed, as follows:

if ((AmountReqd + Credit Card Balance) < Credit Card Limit
     && MileagePlus Status is "100k")

The corresponding authorization rule is:

<xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance)
  &lt; JohnSmith/CreditCard/Limit
    and JohnSmith/MileagePlus/MemberStatus = '100k'">
  !TRUE!
</xsl:if>

This example rule is the simplest form for specifying an authorization rule. It does not include its own template match statement and it accepts the default template match statement, which is set to /XMLADI. Template match statements are an XSL language construct that is used to select the point in the hierarchy of an XML document at which the XSL rules, which are contained within the template match statement, are applied. The default template match statement of the ADI XML model matches from the top of the XMLADI document by specifying the XPath /XMLADI.

To add your own template match statement to a rule definition, only two additional lines are needed. For example, you might rewrite the example to include your own explicit template match statement that matches from the root of the XMLADI document. Modify the rule as follows:

<xsl:template match="/XMLADI">
<xsl:if test="(AmountReqd + JohnSmith/CreditCard/Balance)
  &lt; JohnSmith/CreditCard/Limit
    and JohnSmith/MileagePlus/MemberStatus = '100k')
  !TRUE!
</xsl:if>
</xsl:template>

To reference any data item in the document, the XPath to each node must include the XMLADI node. For example, to access the credit card balance, the full path would be /XMLADI/JohnSmith/CreditCard/Balance. When a rule is built, the rule writer must understand what the correct XPath is from the current point in the tree. The XPath accesses the XML data nodes and subnodes. The current point in the tree is selected with the template match statement. The template match statement allows an XSL programmer to shorten the XPath to each data element by specifying that the XPath processing occur further down the XML document tree.

The <xsl:template match="/XMLADI"> statement tells the XSL processor that all relative XPaths within the bounds of the template statement must be assumed to be relative to the node XMLADI. To shorten the XPaths even further, the template match statement can be set at /XMLADI/JohnSmith. In this case, the credit card balance might be termed CreditCard/Balance.

Policy administrators must also make the following assumptions about the XSL style sheet document that is created by the rules evaluator to contain the rule that they devise:

If a style sheet prolog is specified in the azn client configuration file, that prolog is imported into the empty style sheet. If no prolog is specified, the following default prolog is used instead:

<!-- Required for XSLT language -->
<?xml version="1.0" encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          version="1.0">

<!-- Required to constrain output of rule evaluation -->
<xsl:output method="text" omit-xml-declaration="yes"
          encoding='UTF=8' indent="no"/>

<!-- Need this to ensure default text node printing is off -->
<xsl:template match="text()"></xsl:template>

Among other things, this prolog sets the XSL style sheet syntax to version 1.0, which is supported by the embedded XSL processor. The prolog sets the namespace for XSL documents to xsl, which requires that all XSL language-specific identities be prefixed by xsl:. This prefix is the standard mode of operation for XSL style sheets. Most attributes in this prolog must be in the style sheet. If not, the results that are returned from the rules evaluator do not conform to the expected results.

All authorization rules must be enclosed in an xsl:template match statement. If the rule is defined with its own xsl:template match statement, the rule is accepted as is. This acceptance allows the rule creator to specify the level within the ADI XML document at which the rule matches data items. In this case, the match statement must be the first statement encountered by the evaluator when validating the rule. Otherwise, it is assumed that there is no template match statement. If there is a match statement but the match statement does not begin with the /XMLADI absolute path, the rule is returned as not valid. Relative match statements are not accepted at this level.

If no match statement is specified in the rule, the rule is automatically enclosed in the following match statement:

<xsl:template match="/XMLADI">
			...
<xsl:template>

Therefore, all rules devised without an explicit template match statement must use XPath expressions that assume the XML context node is /XMLADI. The XPath expression for any ADI item must begin with the container name of the item and must be fully qualified.

Note: Authorization rules are processed internally with a recursive algorithm. Avoid creating very long logical expressions that can exhaust the system stack. Long expressions are problematic on systems that have a small stack by default.

For example, this rule might exhaust the system stack:

<xsl:choose><xsl:when test="(((azn_cred_principal_name='9410431')) \
 or ((azn_cred_principal_name='user1')) \
 or ((azn_cred_principal_name='user2')) \
 ...
 or ((azn_cred_principal_name='user500'))\
 )">!TRUE!</xsl:when><xsl:otherwise>!FALSE!</xsl:otherwise></xsl:choose>

A better option is to add the users to a group and write a rule to check group membership.

As a preventive measure two new options are added:

xsl-max-logical-expressions

xsl-eval-expressions-check

The xsl-max-logical-expressions option limits the number of logical 'or' and 'and' operators in a logical expression when a rule is created. The xsl-eval-expressions-check option uses the value from the xsl-max-logical-expressions option to limit the same logical operators when a rule is evaluated.

See the [aznapi-configuration] stanza in IBM® Security Access Manager for Web: Plug-in for Web Servers Administration Guide.

Parent topic: Authorization rules evaluator

Examples of authorization rulesExamples of authorization rulesThese examples demonstrate how rules can be implemented. authorizationrulesexamplesAuthorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.Example: ADI from resource managerThis example relies mostly on ADI that is passed in to the access decision call. The example also requires an ADI container called printQuota to be stored in the requesting user credential or passed in as application context. Example: ADI from entitlement dataThis example shows how a rule works on data that is in the authorization credential.Example: ADI from dynamic ADI retrieval servicesThis example evaluates an application-defined XML input document that is provided by a dynamic entitlement service that was written with the dynamic ADI retrieval service.

Examples of authorization rules

These examples demonstrate how rules can be implemented.

Example: ADI from resource manager
This example relies mostly on ADI that is passed in to the access decision call. The example also requires an ADI container called printQuota to be stored in the requesting user credential or passed in as application context.

Example: ADI from entitlement data
This example shows how a rule works on data that is in the authorization credential.

Example: ADI from dynamic ADI retrieval services
This example evaluates an application-defined XML input document that is provided by a dynamic entitlement service that was written with the dynamic ADI retrieval service.

Parent topic: Authorization rules evaluator

Example: ADI from resource managerExample: ADI from resource managerThis example relies mostly on ADI that is passed in to the access decision call. The example also requires an ADI container called printQuota to be stored in the requesting user credential or passed in as application context. authorizationrulesADI from resource manager examplesThe access decision logic defined by this rule is to permit access only when one of the following conditions is true: The user is in the printUsers group.The user requests a print operation (p).The user requests to queue a print job for printing later (q) and the print quota is less than 20. <xsl:if test='azn_cred_groups = "cn=printUsers,o=ibm,c=us" and (contains(azn_engine_requested_actions,"p") or contains(azn_engine_requested_actions,"q")) and printQuota &lt;20'> !TRUE! </xsl:if>The test condition for the group name returns an appropriate result regardless of the number of groups that the requesting user is in. The condition is an XSL node test that compares each value within the XML element azn_cred_groups with the DN string. To determine the opposite case (for example, that the requesting user is not in the printUsers group), the syntax requires a slightly different expression. See Example: ADI from entitlement dataThis example shows how a rule works on data that is in the authorization credential. for an example of how to test for whether a set of values like the azn_cred_group_names attribute does not contain a certain member.Examples of authorization rulesThese examples demonstrate how rules can be implemented.

Example: ADI from resource manager

This example relies mostly on ADI that is passed in to the access decision call. The example also requires an ADI container called printQuota to be stored in the requesting user credential or passed in as application context.

The access decision logic defined by this rule is to permit access only when one of the following conditions is true:

The user is in the printUsers group.

The user requests a print operation (p).

The user requests to queue a print job for printing later (q) and the print quota is less than 20.

<xsl:if test='azn_cred_groups = "cn=printUsers,o=ibm,c=us"
    and (contains(azn_engine_requested_actions,"p")
      or contains(azn_engine_requested_actions,"q"))
    and printQuota &lt;20'>
  !TRUE!
</xsl:if>

The test condition for the group name returns an appropriate result regardless of the number of groups that the requesting user is in. The condition is an XSL node test that compares each value within the XML element azn_cred_groups with the DN string. To determine the opposite case (for example, that the requesting user is not in the printUsers group), the syntax requires a slightly different expression. See Example: ADI from entitlement data for an example of how to test for whether a set of values like the azn_cred_group_names attribute does not contain a certain member.

Parent topic: Examples of authorization rules

Example: ADI from entitlement dataExample: ADI from entitlement dataThis example shows how a rule works on data that is in the authorization credential.attributesazn_cred_principal_nameattributesazn_cred_groupsattributesazn_cred_registry_idazn_cred_principal_name attributeazn_cred_groups attributeazn_cred_registry_id attributexsl:when statementXSLxsl:when statementauthorizationrulesADI from entitlement data exampleIt evaluates the following attributes: azn_cred_principal_nameazn_cred_groupsazn_cred_registry_idEach of the xsl:when statements are evaluated. The first statement with conditions that are all true returns a result. Each condition tested has a comment that explains its action. <!-- Example choose rule --> <xsl:choose> <!-- Explicitly allow if the requesting user is myuser0 --> <xsl:when test="azn_cred_principal_name = 'myuser0'"> !TRUE! </xsl:when> <!-- Explicitly deny if the requesting user is myuser1 --> <xsl:when test="azn_cred_principal_name = 'myuser1'"> !FALSE! </xsl:when> <!-- Explicitly allow if the requesting user's LDAP DN --> <!-- is the same as that specified --> <xsl:when test="azn_cred_registry_id = 'cn=myuser3,secAuthority=Default'"> !TRUE! </xsl:when> <!-- This rule permits access to any user who is a member of mygroup1 --> <!-- but is not a member of mygroup2 --> <xsl:when test="azn_cred_groups = 'mygroup1' and not (azn_cred_groups = 'mygroup2')"> !TRUE! </xsl:when> <xsl:otherwise> !FALSE! <xsl:otherwise> </xsl:choose>The fourth xsl:when statement uses the not() function to negate the Boolean result of the following test: azn_cred_groups = 'mygroup2'The not() function is used instead of the valid authorization rule operator != operator because, in this case, the azn_cred_groups attribute is a multi-valued attribute. Multi-valued attributes like azn_cred_groups return a set of values, referred to as a node-set in XSL, to be tested by the condition. Each node value in the set is tested against the condition individually and !TRUE! is returned if any of the conditions evaluate to true. In any case, where the user is in more than one group, other than mygroup2, the result of the node test is always !TRUE!. To test the nonexistence of something in a node-set, use the not() function instead of the != operator. For example, you can test that the condition group is mygroup2 is not true.Examples of authorization rulesThese examples demonstrate how rules can be implemented.

Example: ADI from entitlement data

This example shows how a rule works on data that is in the authorization credential.

It evaluates the following attributes:

azn_cred_principal_name

azn_cred_groups

azn_cred_registry_id

Each of the xsl:when statements are evaluated. The first statement with conditions that are all true returns a result. Each condition tested has a comment that explains its action.

<!-- Example choose rule -->

<xsl:choose>
  <!-- Explicitly allow if the requesting user is myuser0 -->
  <xsl:when test="azn_cred_principal_name = 'myuser0'">
    !TRUE!
  </xsl:when>

  <!-- Explicitly deny if the requesting user is myuser1 -->
  <xsl:when test="azn_cred_principal_name = 'myuser1'">
    !FALSE!
  </xsl:when>

  <!-- Explicitly allow if the requesting user's LDAP DN  -->
  <!-- is the same as that specified   -->

  <xsl:when test="azn_cred_registry_id = 'cn=myuser3,secAuthority=Default'">
    !TRUE!
  </xsl:when>

  <!-- This rule permits access to any user who is a member of mygroup1 -->
  <!-- but is not a member of mygroup2     -->

  <xsl:when test="azn_cred_groups = 'mygroup1'
    and not (azn_cred_groups = 'mygroup2')">
    !TRUE!
  </xsl:when>

  <xsl:otherwise>
    !FALSE!
  <xsl:otherwise>
</xsl:choose>

The fourth xsl:when statement uses the not() function to negate the Boolean result of the following test:

azn_cred_groups = 'mygroup2'

The not() function is used instead of the valid authorization rule operator != operator because, in this case, the azn_cred_groups attribute is a multi-valued attribute. Multi-valued attributes like azn_cred_groups return a set of values, referred to as a node-set in XSL, to be tested by the condition. Each node value in the set is tested against the condition individually and !TRUE! is returned if any of the conditions evaluate to true. In any case, where the user is in more than one group, other than mygroup2, the result of the node test is always !TRUE!. To test the nonexistence of something in a node-set, use the not() function instead of the != operator. For example, you can test that the condition group is mygroup2 is not true.

Parent topic: Examples of authorization rules

Example: ADI from dynamic ADI retrieval servicesExample: ADI from dynamic ADI retrieval servicesThis example evaluates an application-defined XML input document that is provided by a dynamic entitlement service that was written with the dynamic ADI retrieval service.authorizationrulesdynamic ADI retrieval services exampleThe code that must be written might create a batch object that contains a list of operations that are to be done together. The batch object consists of a number of transaction elements. Each transaction consists of an item and the amount of those items to order.With these assumptions, the following XML object might be used as input for making the authorization decision: <!-- batched transaction --> <batch> <max_tx_count>5</max_tx_count> <max_tx_amount>150</max_tx_amount> <account>customerA</account> <transaction> <item>widgetA</item> <amount>10</amount> </transaction> <transaction> <item>widgetB</item> <amount>20</amount> </transaction> <transaction> <item>widgetC</item> <amount>30</amount> </transaction> <transaction> <item>widgetD</item> <amount>40</amount> </transaction> <transaction> <item>widgetE</item> <amount>50</amount> </transaction> </batch>With this expected XML object, you might create the following authorization rule: <!--Compare group to batch customer and num tranactions and total tx amounts to limits.--> <xsl:if test="azn_cred_groups = batch/account and count (batch/transaction) &lt;= batch/max_tx_count and sum (batch/transaction/amount) &lt;= batch/max_tx_amount"> !TRUE! </xsl:if> The authorization rule checks that the requesting user is a member of a group whose name matches the name of the account in the transaction. In this example, it is customerA. If the requesting user is not a member of this group, the user is not authorized to submit batch requests on behalf of customerA. Then, the rule checks that the total number of transactions within the batch is less than or equal to the max_tx_count element of the batch object. The rule also checks that the total number of items ordered in the entire request is less than the max_tx_amount element of the batch object. The rule calls the count() and sum() functions. The count() function counts the number of instances of a transaction element within the batch. The sum() function totals the value of all the amount elements within all transaction elements in the batch.For additional information of creating authorization rules, see the Authorization C API Developer Reference.Examples of authorization rulesThese examples demonstrate how rules can be implemented.

Example: ADI from dynamic ADI retrieval services

This example evaluates an application-defined XML input document that is provided by a dynamic entitlement service that was written with the dynamic ADI retrieval service.

The code that must be written might create a batch object that contains a list of operations that are to be done together. The batch object consists of a number of transaction elements. Each transaction consists of an item and the amount of those items to order.

With these assumptions, the following XML object might be used as input for making the authorization decision:

<!-- batched transaction -->
<batch>
  <max_tx_count>5</max_tx_count>
  <max_tx_amount>150</max_tx_amount>
  <account>customerA</account>
  <transaction>
    <item>widgetA</item>
    <amount>10</amount>
  </transaction>
  <transaction>
    <item>widgetB</item>
    <amount>20</amount>
  </transaction>
  <transaction>
    <item>widgetC</item>
    <amount>30</amount>
  </transaction>
  <transaction>
    <item>widgetD</item>
    <amount>40</amount>
  </transaction>
  <transaction>
    <item>widgetE</item>
    <amount>50</amount>
  </transaction>
</batch>

With this expected XML object, you might create the following authorization rule:

<!--Compare group to batch customer and num tranactions
    and total tx amounts to limits.-->
<xsl:if test="azn_cred_groups = batch/account
      and count (batch/transaction) &lt;= batch/max_tx_count
      and sum (batch/transaction/amount) &lt;= batch/max_tx_amount">
    !TRUE!
</xsl:if>

The authorization rule checks that the requesting user is a member of a group whose name matches the name of the account in the transaction. In this example, it is customerA. If the requesting user is not a member of this group, the user is not authorized to submit batch requests on behalf of customerA. Then, the rule checks that the total number of transactions within the batch is less than or equal to the max_tx_count element of the batch object. The rule also checks that the total number of items ordered in the entire request is less than the max_tx_amount element of the batch object. The rule calls the count() and sum() functions. The count() function counts the number of instances of a transaction element within the batch. The sum() function totals the value of all the amount elements within all transaction elements in the batch.

For additional information of creating authorization rules, see the Authorization C API Developer Reference.

Parent topic: Examples of authorization rules

Methods of providing ADI to the rules evaluatorMethods of providing ADI to the rules evaluatorA resource manager application can provide ADI from the resource manager to the rules evaluator in one of two ways. One method is to add the attributes to the application context parameter. The other method is to configure the rules evaluator to supply the missing ADI to the authorization engine only when it is explicitly requested.ADIrequest from the resource managerresourcemanagerrequesting ADIazn_decision_access_allowed() methodazn_perminfo_rules_adi_request attributeazn_init_set_perminfo_attrs attributeattributesazn_perminfo_rules_adi_requestattributesazn_init_set_perminfo_attrsThe first method is to provide the ADI by adding the attributes to the application context parameter passed to the azn_decision_access_allowed_ext() method. The problem with this method is that the resource manager must know which ADI is going to be needed by a particular access decision. Alternatively, you can provide all the ADI for all known rules to the authorization engine for every access decision call regardless of whether a rule is involved in the decision.The first method might be acceptable and even desirable for a smaller set of ADI. However, for a larger and more varied set of possible ADI, a second method is needed. You can configure the resource manager to supply the missing ADI to the authorization engine only when it is explicitly requested. With this method, the authorization engine can be configured with a set of ADI prefixes that can be provided by the resource manager upon request. The authorization engine fails the access decision and notifies the resource manager of the ADI it needs in a permission information attribute returned by the azn_decision_access_allowed_ext() method. The attribute contains a list of the ADI that is needed to successfully evaluate the rule. The ADI was not found in the application context that was passed in. The ADI also did not have a prefix that matches those prefixes that the resource manager identified as its own.The permission information attribute is named azn_perminfo_rules_adi_request and contains a text attribute value for each item of ADI required. The resource manager looks for this attribute when the access decision fails. When it is present, the resource manager scans the list of ADI names in the attribute and gathers the requested data to try the access decision with this additional data again. If the requested data cannot be provided, the resource manager must deny access and log the problem as a failure due to insufficient rules data. The requested list contains only the ADI items that are identified as being provided by the resource manager. The unique prefix added to the attribute name is used to identify the ADI. All resource managers that provide data to the evaluation process in this manner must define a unique prefix by which their ADI data set can be identified.Permission information is returned to a resource manager application only when the authorization client was configured that way. To activate the return of the azn_perminfo_rules_adi_request permission information attribute, the name of this attribute must either be added to the azn_init_set_perminfo_attrs initialization attribute or the equivalent permission-info-returned entry in the [aznapi-configuration] stanza.The ADI prefixes that are recognized by the resource manager can be configured using the resource-manager-provided-adi entry or the azn_init_resource_mgr_provided_adi initialization attribute. See resource-manager-provided-adiThe resource-manager-provided-adi configuration stanza entry defines the prefixes that the authorization engine uses to determine the set of missing ADI from the resource manager. and for the initialization attribute, see Authorization C API Developer Reference.The authorization engine attempts to anticipate the need to request information from the resource manager by obtaining the rule policy object on the protected object early in the access decision process. The authorization engine then compares the required ADI in the rule with the ADI names in the application context parameter that is passed by the resource manager. The ADI names, which are missing from the application context and which are specific to the resource manager, are added to the returned permission information object.ADI prefixes must be unique to identify them as resource manager ADI and to avoid conflict with ADI provided in the credential from the authorization engine or from an external data provider.Authorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.

Methods of providing ADI to the rules evaluator

A resource manager application can provide ADI from the resource manager to the rules evaluator in one of two ways. One method is to add the attributes to the application context parameter. The other method is to configure the rules evaluator to supply the missing ADI to the authorization engine only when it is explicitly requested.

The first method is to provide the ADI by adding the attributes to the application context parameter passed to the azn_decision_access_allowed_ext() method. The problem with this method is that the resource manager must know which ADI is going to be needed by a particular access decision. Alternatively, you can provide all the ADI for all known rules to the authorization engine for every access decision call regardless of whether a rule is involved in the decision.

The first method might be acceptable and even desirable for a smaller set of ADI. However, for a larger and more varied set of possible ADI, a second method is needed. You can configure the resource manager to supply the missing ADI to the authorization engine only when it is explicitly requested. With this method, the authorization engine can be configured with a set of ADI prefixes that can be provided by the resource manager upon request. The authorization engine fails the access decision and notifies the resource manager of the ADI it needs in a permission information attribute returned by the azn_decision_access_allowed_ext() method. The attribute contains a list of the ADI that is needed to successfully evaluate the rule. The ADI was not found in the application context that was passed in. The ADI also did not have a prefix that matches those prefixes that the resource manager identified as its own.

The permission information attribute is named azn_perminfo_rules_adi_request and contains a text attribute value for each item of ADI required. The resource manager looks for this attribute when the access decision fails. When it is present, the resource manager scans the list of ADI names in the attribute and gathers the requested data to try the access decision with this additional data again. If the requested data cannot be provided, the resource manager must deny access and log the problem as a failure due to insufficient rules data. The requested list contains only the ADI items that are identified as being provided by the resource manager. The unique prefix added to the attribute name is used to identify the ADI. All resource managers that provide data to the evaluation process in this manner must define a unique prefix by which their ADI data set can be identified.

Permission information is returned to a resource manager application only when the authorization client was configured that way. To activate the return of the azn_perminfo_rules_adi_request permission information attribute, the name of this attribute must either be added to the azn_init_set_perminfo_attrs initialization attribute or the equivalent permission-info-returned entry in the [aznapi-configuration] stanza.

The ADI prefixes that are recognized by the resource manager can be configured using the resource-manager-provided-adi entry or the azn_init_resource_mgr_provided_adi initialization attribute. See resource-manager-provided-adi and for the initialization attribute, see Authorization C API Developer Reference.

The authorization engine attempts to anticipate the need to request information from the resource manager by obtaining the rule policy object on the protected object early in the access decision process. The authorization engine then compares the required ADI in the rule with the ADI names in the application context parameter that is passed by the resource manager. The ADI names, which are missing from the application context and which are specific to the resource manager, are added to the returned permission information object.

ADI prefixes must be unique to identify them as resource manager ADI and to avoid conflict with ADI provided in the credential from the authorization engine or from an external data provider.

Parent topic: Authorization rules evaluator

Reason codes for rule failuresReason codes for rule failuresThis feature allows the target application to fail or permit the access request based on the rule failure reason code it is given by the resource manager. ADIrequest from the resource managerreason codesrule failurereason codesaccess decisionreason codesforwarding to protected web applicationreason codesconditions for returnrulefailure reason codepermission_info attribute listattributelistspermission_info-returnedattributesazn_perminfo_reason_rule_failedazn_perminfo_reason_rule_failed attributeazn_init_set_perminfo_attrs initialization parameterazn_decision_access_allowed_ext() methodThe authorization engine processes all policies for the access decision as normal. If the rule evaluation fails, the engine returns access denied with a reason code in the azn_perminfo_reason_rule_failed permission information attribute list. When access is denied, the application must check the permission_info attribute list returned from the access decision call. The application determines whether a rule failure reason code was returned from the access decision. The resource manager does not need to check for the attribute on a successful access decision call. The Security Access Manager application is an example of an aznAPI resource manager that can use the rule failure reason code. When configured, Security Access Manager forwards the reason code to the protected web application. The protected web application must be mounted through a secure junction to have access to the reason code defined for the authorization rule. The use of rule failure reason codes in Security Access Manager is limited to the protected object space of junctioned web applications.The attribute value (the reason code) of the azn_perminfo_reason_rule_failed attribute is a single string. The value is determined and defined by the policy administrator and is set in the rule policy object when it is first created. The only constraint on the value of the reason code is that the value must be a string.The following conditions must be met before a rule failure reason code is returned to the caller: The reason code is returned only when the access request is denied and the rule policy evaluation denies access. However, the reason code is not returned for every case in which access is denied. The reason code is not returned when the rule evaluation succeeds. The rule failure reason code is not returned if the rule failed due to a rule syntax error. The code is not returned if there was insufficient ADI to do the rule evaluation. In the latter cases, the authorization decision is failed with an error status.There must be a reason code set in the attached rule policy object. This value is set in the rule policy with the admin API or the pdadmin utility.The aznAPI application must be enabled to return the rule failure reason as permission information. To do this action, either the azn_init_set_perminfo_attrs initialization parameter or the equivalent configuration file entry in the [aznapi-configuration] stanza (stanza entry permission-info-returned) must include the attribute name azn_perminfo_reason_rule_failed. This feature enables the attribute to be returned by the authorization engine in the permission information output parameter (perminfo) of azn_decision_access_allowed_ext(). See the Authorization C API Developer Reference.Authorization rules evaluatorThe authorization rules evaluator evaluates authorization rules within the constraints that are required by the authorization engine.

Reason codes for rule failures

This feature allows the target application to fail or permit the access request based on the rule failure reason code it is given by the resource manager.

The authorization engine processes all policies for the access decision as normal. If the rule evaluation fails, the engine returns access denied with a reason code in the azn_perminfo_reason_rule_failed permission information attribute list.

When access is denied, the application must check the permission_info attribute list returned from the access decision call. The application determines whether a rule failure reason code was returned from the access decision. The resource manager does not need to check for the attribute on a successful access decision call. The Security Access Manager application is an example of an aznAPI resource manager that can use the rule failure reason code. When configured, Security Access Manager forwards the reason code to the protected web application. The protected web application must be mounted through a secure junction to have access to the reason code defined for the authorization rule. The use of rule failure reason codes in Security Access Manager is limited to the protected object space of junctioned web applications.

The attribute value (the reason code) of the azn_perminfo_reason_rule_failed attribute is a single string. The value is determined and defined by the policy administrator and is set in the rule policy object when it is first created. The only constraint on the value of the reason code is that the value must be a string.

The following conditions must be met before a rule failure reason code is returned to the caller:

The reason code is returned only when the access request is denied and the rule policy evaluation denies access. However, the reason code is not returned for every case in which access is denied. The reason code is not returned when the rule evaluation succeeds. The rule failure reason code is not returned if the rule failed due to a rule syntax error. The code is not returned if there was insufficient ADI to do the rule evaluation. In the latter cases, the authorization decision is failed with an error status.

There must be a reason code set in the attached rule policy object. This value is set in the rule policy with the admin API or the pdadmin utility.

The aznAPI application must be enabled to return the rule failure reason as permission information. To do this action, either the azn_init_set_perminfo_attrs initialization parameter or the equivalent configuration file entry in the [aznapi-configuration] stanza (stanza entry permission-info-returned) must include the attribute name azn_perminfo_reason_rule_failed. This feature enables the attribute to be returned by the authorization engine in the permission information output parameter (perminfo) of azn_decision_access_allowed_ext(). See the Authorization C API Developer Reference.

Parent topic: Authorization rules evaluator

Configuration file and initialization attributesConfiguration file and initialization attributesA number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager. initialization attributesconfiguringAn example of this aznAPI.conf configuration file is provided in the example/authzn_demo/cpp directory of the Security Access Manager Application Developer Kit (ADK) package. Configuration files are also used by Security Access Manager resource management applications. These configuration entries can be added to the configuration file of these applications. See the application configuration file documentation for the specific Security Access Manager application.Initialization attributes are the programmatic equivalent of configuration attributes and are intended to be used to develop a custom resource manager application. The authorization-rule-specific initialization attributes and the process of developing a custom resource manager aznAPI application are described in the Authorization C API Developer Reference.Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.resource-manager-provided-adiThe resource-manager-provided-adi configuration stanza entry defines the prefixes that the authorization engine uses to determine the set of missing ADI from the resource manager. dynamic-adi-entitlement-servicesThe dynamic-adi-entitlement-services configuration entry lists the service IDs of the dynamic ADI retrieval entitlement services. These services must be called by the authorization engine if ADI is missing from the requesting user credential or from the application context and cannot be gathered from the resource manager. input-adi-xml-prolog and xsl-stylesheet-prologYou can use the input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries to change the XML and XSL prolog statements. These statements are appended to the ADI XML document and authorization rule style sheet before they are passed to the rules evaluator for processing. [xmladi-attribute-definitions]The [xmladi-attribute-definitions] stanza enables customers to add XML attribute definitions, such as XML namespace definitions, to the XMLADI document start tag.

Configuration file and initialization attributes

A number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager.

An example of this aznAPI.conf configuration file is provided in the example/authzn_demo/cpp directory of the Security Access Manager Application Developer Kit (ADK) package. Configuration files are also used by Security Access Manager resource management applications. These configuration entries can be added to the configuration file of these applications. See the application configuration file documentation for the specific Security Access Manager application.

Initialization attributes are the programmatic equivalent of configuration attributes and are intended to be used to develop a custom resource manager application. The authorization-rule-specific initialization attributes and the process of developing a custom resource manager aznAPI application are described in the Authorization C API Developer Reference.

resource-manager-provided-adi
The resource-manager-provided-adi configuration stanza entry defines the prefixes that the authorization engine uses to determine the set of missing ADI from the resource manager.

dynamic-adi-entitlement-services
The dynamic-adi-entitlement-services configuration entry lists the service IDs of the dynamic ADI retrieval entitlement services. These services must be called by the authorization engine if ADI is missing from the requesting user credential or from the application context and cannot be gathered from the resource manager.

input-adi-xml-prolog and xsl-stylesheet-prolog
You can use the input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries to change the XML and XSL prolog statements. These statements are appended to the ADI XML document and authorization rule style sheet before they are passed to the rules evaluator for processing.

[xmladi-attribute-definitions]
The [xmladi-attribute-definitions] stanza enables customers to add XML attribute definitions, such as XML namespace definitions, to the XMLADI document start tag.

Parent topic: Authorization rules management

resource-manager-provided-adiresource-manager-provided-adiThe resource-manager-provided-adi configuration stanza entry defines the prefixes that the authorization engine uses to determine the set of missing ADI from the resource manager. initialization attributesresource-manager-provided-adiconfigurationentriesresource-manager-provided-adiresource-manager-provided-adi configuration entryADIresource-manager-provided-adiThis entry uses a string prefix as its value. To specify more than one prefix, you must add multiple stanza entries as in the following examples: resource-manager-provided-adi = sales_customer_ resource-manager-provided-adi = sales_item_These examples notify the authorization engine that any ADI it requires that begins with sales_customer_ or sales_item_ is provided by the resource manager application. ADI items named sales_customer_name, sales_customer_address, sales_item_count, and sales_item_price are examples of ADI that the authorization engine would request from the resource manager.Configuration file and initialization attributesA number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager.

resource-manager-provided-adi

The resource-manager-provided-adi configuration stanza entry defines the prefixes that the authorization engine uses to determine the set of missing ADI from the resource manager.

This entry uses a string prefix as its value. To specify more than one prefix, you must add multiple stanza entries as in the following examples:

resource-manager-provided-adi = sales_customer_

resource-manager-provided-adi = sales_item_

These examples notify the authorization engine that any ADI it requires that begins with sales_customer_ or sales_item_ is provided by the resource manager application. ADI items named sales_customer_name, sales_customer_address, sales_item_count, and sales_item_price are examples of ADI that the authorization engine would request from the resource manager.

Parent topic: Configuration file and initialization attributes

dynamic-adi-entitlement-servicesdynamic-adi-entitlement-servicesThe dynamic-adi-entitlement-services configuration entry lists the service IDs of the dynamic ADI retrieval entitlement services. These services must be called by the authorization engine if ADI is missing from the requesting user credential or from the application context and cannot be gathered from the resource manager. initializationattributesdynamic-adi-entitlement-servicesconfigurationentriesdynamic-adi-entitlement-servicesdynamic-adi-entitlement-services configuration entrydynamic ADIretrieval entitlement servicesretrieval entitlement servicesADIdynamic retrieval entitlement servicesazn_entitlement_get_entitlements() callattributesazn_perminfo_rules_adi_requestazn_perminfo_rules_adi_request attributeAny entitlement service configured under this entry is called by the authorization engine with the azn_entitlement_get_entitlements() interface and is passed the azn_perminfo_rules_adi_request attribute. The string values of this attribute are the container names of the ADI that are still required. If the dynamic ADI retrieval service can fulfill the request, it returns the requested data to the authorization engine in the entitlements parameter. Security Access Manager provides demonstrations of how an entitlement service can perform the functions of a dynamic ADI retrieval service and a credential attribute retrieval service. See the Authorization C API Developer Reference.To specify that the authorization engine must call multiple dynamic ADI retrieval services, you must specify multiple entries. The following examples demonstrate how to specify the service IDs of two different entitlement services for use as dynamic ADI entitlement services. The service IDs must correspond to valid entitlement service definitions in the [aznapi-entitlement-service] stanza. dynamic-adi-entitlement-services = ent_cred_attrs_id dynamic-adi-entitlement-services = ent_svc_demo_idConfiguration file and initialization attributesA number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager.

dynamic-adi-entitlement-services

The dynamic-adi-entitlement-services configuration entry lists the service IDs of the dynamic ADI retrieval entitlement services. These services must be called by the authorization engine if ADI is missing from the requesting user credential or from the application context and cannot be gathered from the resource manager.

Any entitlement service configured under this entry is called by the authorization engine with the azn_entitlement_get_entitlements() interface and is passed the azn_perminfo_rules_adi_request attribute. The string values of this attribute are the container names of the ADI that are still required. If the dynamic ADI retrieval service can fulfill the request, it returns the requested data to the authorization engine in the entitlements parameter. Security Access Manager provides demonstrations of how an entitlement service can perform the functions of a dynamic ADI retrieval service and a credential attribute retrieval service. See the Authorization C API Developer Reference.

To specify that the authorization engine must call multiple dynamic ADI retrieval services, you must specify multiple entries. The following examples demonstrate how to specify the service IDs of two different entitlement services for use as dynamic ADI entitlement services. The service IDs must correspond to valid entitlement service definitions in the [aznapi-entitlement-service] stanza.

dynamic-adi-entitlement-services = ent_cred_attrs_id
dynamic-adi-entitlement-services = ent_svc_demo_id

Parent topic: Configuration file and initialization attributes

input-adi-xml-prolog and xsl-stylesheet-prologinput-adi-xml-prolog and xsl-stylesheet-prologYou can use the input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries to change the XML and XSL prolog statements. These statements are appended to the ADI XML document and authorization rule style sheet before they are passed to the rules evaluator for processing. initialization attributesinput-adi-xml-prologinitialization attributesxsl-stylesheet-prologconfigurationentriesinput-adi-xml-prologconfigurationentriesxsl-stylesheet-prologinput-adi-xml-prolog configuration entryxsl-stylesheet-prolog entryprolog statementsXMLprolog statementsXSLprolog statementsThe format and defaults for each of these entries are: input-adi-xml-prolog=<?xml version="1.0" encoding="UTF-8"?>and xsl-stylesheet-prolog=<?xml version="1.0" encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> <xsl:output method = 'text'omit-xml-declaration='yes' encoding='UTF-8'indent='no'/> <xsl:template match='text()'> </xsl:template>Due to the constraints imposed by the authorization rule model, there are a number of prolog attributes that are required by the authorization engine. All of the attributes are specified in the default prolog entries. If any of these attributes are changed or omitted from the entry, the authorization client fails to start and returns an error.Ensure that you are familiar with the Xalan XSL processor and the Xerces XML processor. Be familiar with the use of prolog statements before you change these entries from the default values.Configuration file and initialization attributesA number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager.

input-adi-xml-prolog and xsl-stylesheet-prolog

You can use the input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries to change the XML and XSL prolog statements. These statements are appended to the ADI XML document and authorization rule style sheet before they are passed to the rules evaluator for processing.

The format and defaults for each of these entries are:

input-adi-xml-prolog=<?xml version="1.0" encoding="UTF-8"?>

and

xsl-stylesheet-prolog=<?xml version="1.0" encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
<xsl:output method = 'text'omit-xml-declaration='yes' encoding='UTF-8'indent='no'/>
<xsl:template match='text()'>
</xsl:template>

Due to the constraints imposed by the authorization rule model, there are a number of prolog attributes that are required by the authorization engine. All of the attributes are specified in the default prolog entries. If any of these attributes are changed or omitted from the entry, the authorization client fails to start and returns an error.

Note: Ensure that you are familiar with the Xalan XSL processor and the Xerces XML processor. Be familiar with the use of prolog statements before you change these entries from the default values.

Parent topic: Configuration file and initialization attributes

[xmladi-attribute-definitions][xmladi-attribute-definitions]The [xmladi-attribute-definitions] stanza enables customers to add XML attribute definitions, such as XML namespace definitions, to the XMLADI document start tag. initialization attributesxmladi-attribute-definitionsFor example, an application might want to use namespaces to differentiate or aggregate ADI items, as described in XML namespace definitionsXML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules. . The XML processor must be notified of the namespace with an XML namespace definition. The namespace definition can be added to this stanza, and it is automatically added to the XMLADI document element start tag. The benefit of adding definitions to the XMLADI document start tag is that the attribute definitions are available for all ADI items that are defined in the XMLADI document. The attribute definitions are available whether their values were retrieved from the credential, generated by the authorization engine, or retrieved by a dynamic ADI entitlement service. For example: [xmladi-attribute-definitions] xmlns:myNS = "http://myURI.mycompany.com" appID = '"Jupiter" - Account Management Web Portal Server #1.' The XMLADI element start tag that results from these definitions is: <XMLADI xmlns:myNS="http://myURI.mycompany.com" appID='"Jupiter" - Account Management Web Portal Server #1.'>Both the namespace ID myNS and the attribute appID are defined globally in the XMLADI document.Configuration file and initialization attributesA number of configuration file entries and initialization attributes are available to control aspects of the initialization of the rules evaluator within the authorization engine. The configuration entries are in the configuration file of the resource manager.

[xmladi-attribute-definitions]

The [xmladi-attribute-definitions] stanza enables customers to add XML attribute definitions, such as XML namespace definitions, to the XMLADI document start tag.

For example, an application might want to use namespaces to differentiate or aggregate ADI items, as described in XML namespace definitions. The XML processor must be notified of the namespace with an XML namespace definition. The namespace definition can be added to this stanza, and it is automatically added to the XMLADI document element start tag. The benefit of adding definitions to the XMLADI document start tag is that the attribute definitions are available for all ADI items that are defined in the XMLADI document. The attribute definitions are available whether their values were retrieved from the credential, generated by the authorization engine, or retrieved by a dynamic ADI entitlement service. For example:

[xmladi-attribute-definitions]
  xmlns:myNS = "http://myURI.mycompany.com"
  appID = '"Jupiter" - Account Management Web Portal Server #1.'

The XMLADI element start tag that results from these definitions is:

<XMLADI xmlns:myNS="http://myURI.mycompany.com"
  appID='"Jupiter" - Account Management Web Portal Server #1.'>

Both the namespace ID myNS and the attribute appID are defined globally in the XMLADI document.

Parent topic: Configuration file and initialization attributes

Manage authorization rulesManage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.authorizationrulesmanagement tasksmanagementauthorization rulesFor online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page. There are no equivalent pdadmin commands for importing, exporting, or cloning authorization rules.When providing rule text with the pdadmin utility, enclose the rule text in double quotation marks ("). Double quotation marks embedded within the rule text must be escaped with a backward slash (\) so that they are ignored by the pdadmin utility. The XSL processor treats single and double quotation marks equally for defining text strings. They can be used interchangeably, but they must always be paired appropriately. For example: pdadmin sec_master> authzrule create testrule1 "<xsl:if test='some_piece_of_ADI =\"any string\"'>!TRUE!</xsl:if>" Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.Create an authorization ruleYou can create an authorization rule with the Web Portal Manager or pdadmin utility.Modify an authorization ruleYou can modify an authorization rule with the Web Portal Manager or pdadmin utility.List authorization rulesYou can list the authorization rules that the Web Portal Manager or pdadmin utility created.Cloning an authorization rule with Web Portal ManagerYou can clone an authorization rule in the domain only with Web Portal Manager.Importing authorization rules with Web Portal ManagerYou can import authorization rules in the domain only with Web Portal Manager.Exporting all authorization rules with Web Portal ManagerYou can export all authorization rules in the domain only with Web Portal Manager.Exporting a single authorization rule with Web Portal ManagerYou can export a single authorization rule in the domain only with Web Portal Manager.Exporting multiple authorization rules with Web Portal ManagerYou can export multiple authorization rules in the domain only with Web Portal Manager.Attach an authorization rule to a protected objectYou can attach an authorization rule to a protected object with the Web Portal Manager or pdadmin utility.Detach an authorization ruleYou can detach an authorization rule from a protected object with the Web Portal Manager or pdadmin utility.Locate where an authorization rule is attachedYou can find the protected objects that have an authorization rule attached with the Web Portal Manager or pdadmin utility.Delete an authorization ruleYou can delete an authorization rule with the Web Portal Manager or pdadmin utility.

Manage authorization rules

These topics describe how to use the Web Portal Manager or pdadmin utility.

For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Note: There are no equivalent pdadmin commands for importing, exporting, or cloning authorization rules.

Note:

When providing rule text with the pdadmin utility, enclose the rule text in double quotation marks ("). Double quotation marks embedded within the rule text must be escaped with a backward slash (\) so that they are ignored by the pdadmin utility. The XSL processor treats single and double quotation marks equally for defining text strings. They can be used interchangeably, but they must always be paired appropriately. For example:

pdadmin sec_master> authzrule create testrule1
  "<xsl:if test='some_piece_of_ADI =\"any string\"'>!TRUE!</xsl:if>"

Create an authorization rule
You can create an authorization rule with the Web Portal Manager or pdadmin utility.

Modify an authorization rule
You can modify an authorization rule with the Web Portal Manager or pdadmin utility.

List authorization rules
You can list the authorization rules that the Web Portal Manager or pdadmin utility created.

Cloning an authorization rule with Web Portal Manager
You can clone an authorization rule in the domain only with Web Portal Manager.

Importing authorization rules with Web Portal Manager
You can import authorization rules in the domain only with Web Portal Manager.

Exporting all authorization rules with Web Portal Manager
You can export all authorization rules in the domain only with Web Portal Manager.

Exporting a single authorization rule with Web Portal Manager
You can export a single authorization rule in the domain only with Web Portal Manager.

Exporting multiple authorization rules with Web Portal Manager
You can export multiple authorization rules in the domain only with Web Portal Manager.

Attach an authorization rule to a protected object
You can attach an authorization rule to a protected object with the Web Portal Manager or pdadmin utility.

Detach an authorization rule
You can detach an authorization rule from a protected object with the Web Portal Manager or pdadmin utility.

Locate where an authorization rule is attached
You can find the protected objects that have an authorization rule attached with the Web Portal Manager or pdadmin utility.

Delete an authorization rule
You can delete an authorization rule with the Web Portal Manager or pdadmin utility.

Parent topic: Authorization rules management

Create an authorization ruleCreate an authorization ruleYou can create an authorization rule with the Web Portal Manager or pdadmin utility.authorizationrulescreating (overview)Manage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.Creating an authorization rule with Web Portal ManagerYou can create an authorization rule with Web Portal Manager.Creating an authorization rule with pdadminYou can create an authorization rule with the pdadmin utility.

Create an authorization rule

You can create an authorization rule with the Web Portal Manager or pdadmin utility.

Creating an authorization rule with Web Portal Manager
You can create an authorization rule with Web Portal Manager.

Creating an authorization rule with pdadmin
You can create an authorization rule with the pdadmin utility.

Parent topic: Manage authorization rules

Creating an authorization rule with Web Portal ManagerCreating an authorization rule with Web Portal ManagerYou can create an authorization rule with Web Portal Manager.authorizationrulescreating with Web Portal Manager To create an authorization rule, complete the following steps.Use Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRuleCreate AuthzRule to display the Create AuthzRule page.Type the AuthzRule Name for the authorization rule that you want to create (for example, r2).Do not use the following characters in the name of a rule: ! " # & ( ) * + , ; : < > = @ \ |In the Description field, type a description of the authorization rule. For example, type the following text:time-of-day rule for engineering object spaceIn the AuthzRule Text field, type the text of the rule policy. For example, type the following information:<xsl:template match="/XMLADI"> <xsl:if test="(AmountReqd +JohnSmith/CreditCard/Balance) <JohnSmith/CreditCard/Limit and JohnSmith?mileagePlus/MemberStatus='100k'> !TRUE! </xsl:if> </xsl:template>In the Fail Reason field, type the text that you want to be returned to the resource manager if the rule denies access to a protected object. For example, type error.Click Create. If successful, the new rule is displayed as a link on the Manage AuthzRules page. If you select the authorization rule link, the properties of that rule are displayed.Create an authorization ruleYou can create an authorization rule with the Web Portal Manager or pdadmin utility.

Creating an authorization rule with Web Portal Manager

You can create an authorization rule with Web Portal Manager.

About this task

To create an authorization rule, complete the following steps.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule > Create AuthzRule to display the Create AuthzRule page.

Type the AuthzRule Name for the authorization rule that you want to create (for example, r2).

Note: Do not use the following characters in the name of a rule:

! " # & ( ) * + , ; : < > = @ \ |

In the Description field, type a description of the authorization rule. For example, type the following text:

time-of-day rule for engineering object space

In the AuthzRule Text field, type the text of the rule policy. For example, type the following information:

<xsl:template match="/XMLADI">
  <xsl:if test="(AmountReqd +JohnSmith/CreditCard/Balance)
    <JohnSmith/CreditCard/Limit
      and JohnSmith?mileagePlus/MemberStatus='100k'>
    !TRUE!
  </xsl:if>
</xsl:template>

In the Fail Reason field, type the text that you want to be returned to the resource manager if the rule denies access to a protected object. For example, type error.

Click Create. If successful, the new rule is displayed as a link on the Manage AuthzRules page. If you select the authorization rule link, the properties of that rule are displayed.

Parent topic: Create an authorization rule

Creating an authorization rule with pdadminCreating an authorization rule with pdadminYou can create an authorization rule with the pdadmin utility.authorizationrulescreating with pdadmincommandsauthzrule creatingauthzrulecommandscreatingauthzrulecreate commandTo create an authorization rule with the pdadmin utility, complete the following steps. Log on to the domain as the domain administrator.Use the authzrule create command.When providing rule text with the pdadmin utility, enclose the rule text in double quotation marks ("). Double quotation marks embedded within the rule text must be escaped with a backward slash (\) so that they are ignored by the pdadmin utility. The XSL processor treats single and double quotation marks equally for defining text strings. They can be used interchangeably, but they must always be paired appropriately. For example: pdadmin sec_master> authzrule create testrule1 "<xsl:if test='some_piece_of_ADI =\"any string\"'>!TRUE!</xsl:if>"See the IBM Security Access Manager for Web: Command Reference.Create an authorization ruleYou can create an authorization rule with the Web Portal Manager or pdadmin utility.

Creating an authorization rule with pdadmin

You can create an authorization rule with the pdadmin utility.

About this task

To create an authorization rule with the pdadmin utility, complete the following steps.

Procedure

Log on to the domain as the domain administrator.

Use the authzrule create command.

Example

When providing rule text with the pdadmin utility, enclose the rule text in double quotation marks ("). Double quotation marks embedded within the rule text must be escaped with a backward slash (\) so that they are ignored by the pdadmin utility. The XSL processor treats single and double quotation marks equally for defining text strings. They can be used interchangeably, but they must always be paired appropriately. For example:

pdadmin sec_master> authzrule create testrule1
"<xsl:if test='some_piece_of_ADI =\"any string\"'>!TRUE!</xsl:if>"

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create an authorization rule

Modify an authorization ruleModify an authorization ruleYou can modify an authorization rule with the Web Portal Manager or pdadmin utility.authorizationruleschangingauthorizationrulesmodifyingManage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.Modifying an authorization rule with Web Portal ManagerYou can modify an authorization rule with Web Portal Manager.Modifying an authorization rule with pdadminYou can modify an authorization rule in the domain with the pdadmin utility.

Modify an authorization rule

You can modify an authorization rule with the Web Portal Manager or pdadmin utility.

Modifying an authorization rule with Web Portal Manager
You can modify an authorization rule with Web Portal Manager.

Modifying an authorization rule with pdadmin
You can modify an authorization rule in the domain with the pdadmin utility.

Parent topic: Manage authorization rules

Modifying an authorization rule with Web Portal ManagerModifying an authorization rule with Web Portal ManagerYou can modify an authorization rule with Web Portal Manager.authorizationrulesmodifying with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRuleList AuthzRule to display the Manage AuthzRules page.A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.Click the authorization rule link for the rule that you want to change. The AuthzRule Properties page is displayed.As needed, change the following information:The descriptionThe authorization rule textThe fail reasonFor example, if no description currently exists, add a description. If a description currently exists, change the authorization rule description by typing the new description in the Description field (for example, adding the words updated June 23 2003): updated June 23 2003 time-of-day rule for engineering object spaceClick Apply for the changes to take effect.Modify an authorization ruleYou can modify an authorization rule with the Web Portal Manager or pdadmin utility.

Modifying an authorization rule with Web Portal Manager

You can modify an authorization rule with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule > List AuthzRule to display the Manage AuthzRules page.

A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.

Click the authorization rule link for the rule that you want to change. The AuthzRule Properties page is displayed.

As needed, change the following information:

The description

The authorization rule text

The fail reason

For example, if no description currently exists, add a description. If a description currently exists, change the authorization rule description by typing the new description in the Description field (for example, adding the words updated June 23 2003):

updated June 23 2003 time-of-day rule for engineering object space

Click Apply for the changes to take effect.

Parent topic: Modify an authorization rule

Modifying an authorization rule with pdadminModifying an authorization rule with pdadminYou can modify an authorization rule in the domain with the pdadmin utility.authorizationrulesmodifying with pdadmincommandsauthzrule modifyingauthzrulecommandsmodifyauthzrulecommandsmodifyingLog on to the domain as the domain administrator.Use the authzrule modify command.For example, to change the rule named r2 to return a fail reason code of warning, enter the following command: pdadmin sec_master> authzrule modify r2 failreason warningSee the IBM Security Access Manager for Web: Command Reference.Modify an authorization ruleYou can modify an authorization rule with the Web Portal Manager or pdadmin utility.

Modifying an authorization rule with pdadmin

You can modify an authorization rule in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the authzrule modify command.

Example

For example, to change the rule named r2 to return a fail reason code of warning, enter the following command:

pdadmin sec_master> authzrule modify r2 failreason warning

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Modify an authorization rule

List authorization rulesList authorization rulesYou can list the authorization rules that the Web Portal Manager or pdadmin utility created.authorizationruleslistingManage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.Listing authorization rules with Web Portal ManagerYou can list all authorization rules with Web Portal Manager.Listing authorization rules with pdadminYou can list authorization rules in the domain with the pdadmin utility.

List authorization rules

You can list the authorization rules that the Web Portal Manager or pdadmin utility created.

Listing authorization rules with Web Portal Manager
You can list all authorization rules with Web Portal Manager.

Listing authorization rules with pdadmin
You can list authorization rules in the domain with the pdadmin utility.

Parent topic: Manage authorization rules

Listing authorization rules with Web Portal ManagerListing authorization rules with Web Portal ManagerYou can list all authorization rules with Web Portal Manager.authorizationruleslisting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.A list of names for authorization rules that were created in Security Access Manager are displayed as links. If you select an authorization rule link, the properties of that rule are displayed.List authorization rulesYou can list the authorization rules that the Web Portal Manager or pdadmin utility created.

Listing authorization rules with Web Portal Manager

You can list all authorization rules with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.

Results

A list of names for authorization rules that were created in Security Access Manager are displayed as links. If you select an authorization rule link, the properties of that rule are displayed.

Parent topic: List authorization rules

Listing authorization rules with pdadminListing authorization rules with pdadminYou can list authorization rules in the domain with the pdadmin utility.authorizationruleslisting with pdadmincommandsauthzrule listingauthzrulecommandslistingLog on to the domain as the domain administrator.Use the authzrule list command.pdadmin sec_master> authzrule listSee the IBM Security Access Manager for Web: Command Reference.List authorization rulesYou can list the authorization rules that the Web Portal Manager or pdadmin utility created.

Listing authorization rules with pdadmin

You can list authorization rules in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the authzrule list command.

pdadmin sec_master> authzrule list

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: List authorization rules

Cloning an authorization rule with Web Portal ManagerCloning an authorization rule with Web Portal ManagerYou can clone an authorization rule in the domain only with Web Portal Manager.authorizationrulescloningUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → List AuthzRule.From the Manage AuthzRules page, select the authorization rule you want to clone.From the AuthzRule Properties page, click Clone.From the Clone AuthzRule page, type an AuthzRule Name For example, type Test-AuthzRule. The default value is the name of the original authorization rule with the prefix Clone. This field is required.Optional: Type a Description of the authorization rule. For example, type Clone of new authorization rule. The default value is the description of the original authorization rule.Click Clone. If successful, a link for this cloned authorization rule is created and a success message is displayed.Manage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.

Cloning an authorization rule with Web Portal Manager

You can clone an authorization rule in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → List AuthzRule.

From the Manage AuthzRules page, select the authorization rule you want to clone.

From the AuthzRule Properties page, click Clone.

From the Clone AuthzRule page, type an AuthzRule Name For example, type Test-AuthzRule. The default value is the name of the original authorization rule with the prefix Clone. This field is required.

Optional: Type a Description of the authorization rule. For example, type Clone of new authorization rule. The default value is the description of the original authorization rule.

Click Clone. If successful, a link for this cloned authorization rule is created and a success message is displayed.

Parent topic: Manage authorization rules

Importing authorization rules with Web Portal ManagerImporting authorization rules with Web Portal ManagerYou can import authorization rules in the domain only with Web Portal Manager.authorizationrulesimporting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → Import AuthzRule.From the Import AuthzRule page, complete one of the following steps:In the AuthzRule File Name field, type the name of the authorization rule to import. For example, type ruleImport.xml.Click Browse to select a file name.The file that contains the authorization rule might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.Click Import.If successful, the imported rule is available when you list all the rules.Manage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.

Importing authorization rules with Web Portal Manager

You can import authorization rules in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → Import AuthzRule.

From the Import AuthzRule page, complete one of the following steps:

In the AuthzRule File Name field, type the name of the authorization rule to import. For example, type ruleImport.xml.

Click Browse to select a file name.

The file that contains the authorization rule might be encrypted when it was exported. In the Encryption String text field, type the string that was used to encrypt the XML file.

Click Import.

Results

If successful, the imported rule is available when you list all the rules.

Parent topic: Manage authorization rules

Exporting all authorization rules with Web Portal ManagerExporting all authorization rules with Web Portal ManagerYou can export all authorization rules in the domain only with Web Portal Manager.authorizationrulesexporting allUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → Export All AuthzRules to display the Export AuthzRule to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported rule descriptions. The default file name is ruleExport.xml.If successful, the exported rule descriptions are available in the specified location.Manage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.

Exporting all authorization rules with Web Portal Manager

You can export all authorization rules in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → Export All AuthzRules to display the Export AuthzRule to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported rule descriptions. The default file name is ruleExport.xml.

Results

If successful, the exported rule descriptions are available in the specified location.

Parent topic: Manage authorization rules

Exporting a single authorization rule with Web Portal ManagerExporting a single authorization rule only with Web Portal ManagerYou can export a single authorization rule in the domain only with Web Portal Manager.authorizationrulesexporting one with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → List AuthzRule.From the Manage AuthzRules page, select the authorization rule that you want to export.From the AuthzRule Properties page, click Export to display the Export AuthzRule to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported authorization rule description. The default file name is ruleExport.xml. If successful, the exported rule description is available in the specified location.Manage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.

Exporting a single authorization rule with Web Portal Manager

You can export a single authorization rule in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → List AuthzRule.

From the Manage AuthzRules page, select the authorization rule that you want to export.

From the AuthzRule Properties page, click Export to display the Export AuthzRule to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported authorization rule description. The default file name is ruleExport.xml.

Results

If successful, the exported rule description is available in the specified location.

Parent topic: Manage authorization rules

Exporting multiple authorization rules with Web Portal ManagerExporting multiple authorization rules with Web Portal ManagerYou can export multiple authorization rules in the domain only with Web Portal Manager.authorizationrulesexporting multipleUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → List AuthzRule.From the Manage AuthzRules page, select the authorization rule that you want to export.Click Export to display the Export AuthzRule to File page.Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.When an encryption string is provided, in the Confirm Encryption String text field, type the string again.Click Export to display the File Download window.Click Save to display the Save As window.Click Save to create the file that contains the exported authorization rule descriptions. The default file name is ruleExport.xml.If successful, the new XML file is available in the specified location.Manage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.

Exporting multiple authorization rules with Web Portal Manager

You can export multiple authorization rules in the domain only with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → List AuthzRule.

From the Manage AuthzRules page, select the authorization rule that you want to export.

Click Export to display the Export AuthzRule to File page.

Optional: In the Encryption String text field, type the string to use to encrypt the XML file. If not specified, the exported file is in plain text.

When an encryption string is provided, in the Confirm Encryption String text field, type the string again.

Click Export to display the File Download window.

Click Save to display the Save As window.

Click Save to create the file that contains the exported authorization rule descriptions. The default file name is ruleExport.xml.

Results

If successful, the new XML file is available in the specified location.

Parent topic: Manage authorization rules

Attach an authorization rule to a protected objectAttach an authorization rule to a protected objectYou can attach an authorization rule to a protected object with the Web Portal Manager or pdadmin utility.authorizationrulesattaching to an objectManage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.Attaching an authorization rule to a protected object with Web Portal ManagerYou can attach an authorization rule to a protected object with Web Portal Manager.Attaching an authorization rule to a protected object with pdadminYou can attach an authorization rule to a protected object with the pdadmin utility.

Attach an authorization rule to a protected object

You can attach an authorization rule to a protected object with the Web Portal Manager or pdadmin utility.

Attaching an authorization rule to a protected object with Web Portal Manager
You can attach an authorization rule to a protected object with Web Portal Manager.

Attaching an authorization rule to a protected object with pdadmin
You can attach an authorization rule to a protected object with the pdadmin utility.

Parent topic: Manage authorization rules

Attaching an authorization rule to a protected object with Web Portal ManagerAttaching an authorization rule to a protected object with Web Portal ManagerYou can attach an authorization rule to a protected object with Web Portal Manager.authorizationrulesattaching with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.Click the link for the authorization rule that you want to attach to an object. For example, the r2 authorization rule. The AuthzRule Properties page is displayed.Click the Attach tab to view a list of protected objects to which the authorization rule is already attached, if any.Click Attach to display the Attach AuthzRule page.Type the Protected Object Path of the protected object to which you want to attach the authorization rule. This field is required. Be sure to type the full path name. For example, type the following path:/WebSEAL/tivoli.com/w3junction/index.htmlClick Attach. If successful, the new protected object is added as a link to the list of objects to which the authorization rule is attached on the AuthzRule Properties–Attach page.Attach an authorization rule to a protected objectYou can attach an authorization rule to a protected object with the Web Portal Manager or pdadmin utility.

Attaching an authorization rule to a protected object with Web Portal Manager

You can attach an authorization rule to a protected object with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.

A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.

Click the link for the authorization rule that you want to attach to an object. For example, the r2 authorization rule. The AuthzRule Properties page is displayed.

Click the Attach tab to view a list of protected objects to which the authorization rule is already attached, if any.

Click Attach to display the Attach AuthzRule page.

Type the Protected Object Path of the protected object to which you want to attach the authorization rule. This field is required. Be sure to type the full path name. For example, type the following path:

/WebSEAL/tivoli.com/w3junction/index.html

Click Attach. If successful, the new protected object is added as a link to the list of objects to which the authorization rule is attached on the AuthzRule Properties–Attach page.

Parent topic: Attach an authorization rule to a protected object

Attaching an authorization rule to a protected object with pdadminAttaching an authorization rule to a protected object with pdadminYou can attach an authorization rule to a protected object with the pdadmin utility.authorizationrulesattaching with pdadmincommandsauthzrule attachingauthzrulecommandsattachLog on to the domain as the domain administrator.Use the authzrule attach command.For example, to attach a rule named r2 to a protected object named /WebSEAL/tivoli.com/w3junction/index.html, enter the following command: pdadmin sec_master> authzrule attach /WebSEAL/tivoli.com/w3junction/index.html r2See the IBM Security Access Manager for Web: Command Reference.Attach an authorization rule to a protected objectYou can attach an authorization rule to a protected object with the Web Portal Manager or pdadmin utility.

Attaching an authorization rule to a protected object with pdadmin

You can attach an authorization rule to a protected object with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the authzrule attach command.

Example

For example, to attach a rule named r2 to a protected object named /WebSEAL/tivoli.com/w3junction/index.html, enter the following command:

pdadmin sec_master> authzrule attach /WebSEAL/tivoli.com/w3junction/index.html r2

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Attach an authorization rule to a protected object

Detach an authorization ruleDetach an authorization ruleYou can detach an authorization rule from a protected object with the Web Portal Manager or pdadmin utility.authorizationrulesdetachingManage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.Detaching an authorization rule with Web Portal ManagerYou can detach an authorization rule from a protected object with Web Portal Manager.Detaching an authorization rule with pdadminYou can detach an authorization rule from a protected object in the domain with the pdadmin utility.

Detach an authorization rule

You can detach an authorization rule from a protected object with the Web Portal Manager or pdadmin utility.

Detaching an authorization rule with Web Portal Manager
You can detach an authorization rule from a protected object with Web Portal Manager.

Detaching an authorization rule with pdadmin
You can detach an authorization rule from a protected object in the domain with the pdadmin utility.

Parent topic: Manage authorization rules

Detaching an authorization rule with Web Portal ManagerDetaching an authorization rule with Web Portal ManagerYou can detach an authorization rule from a protected object with Web Portal Manager.authorizationrulesdetaching with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.Click the link for the authorization rule that you want to detach from an object. The AuthzRule Properties page is displayed.Click the Attach tab to view a list of protected objects to which the authorization rule is already attached, if any.Select one or more check boxes for the protected objects from which you want to detach the authorization rule.Click Detach to display the Detach AuthzRule from Object page where you are prompted to confirm or cancel the request.Detach an authorization ruleYou can detach an authorization rule from a protected object with the Web Portal Manager or pdadmin utility.

Detaching an authorization rule with Web Portal Manager

You can detach an authorization rule from a protected object with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule → List AuthzRule to display the Manage AuthzRules page.

A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.

Click the link for the authorization rule that you want to detach from an object. The AuthzRule Properties page is displayed.

Click the Attach tab to view a list of protected objects to which the authorization rule is already attached, if any.

Select one or more check boxes for the protected objects from which you want to detach the authorization rule.

Click Detach to display the Detach AuthzRule from Object page where you are prompted to confirm or cancel the request.

Parent topic: Detach an authorization rule

Detaching an authorization rule with pdadminDetaching an authorization rule with pdadminYou can detach an authorization rule from a protected object in the domain with the pdadmin utility.authorizationrulesdetaching with pdadmincommandsauthzrule detachingauthzrulecommandsdetachingLog on to the domain as the domain administrator.Use the authzrule detach command.For example, to detach a rule from a protected object named /WebSEAL/tivoli.com/w3junction/index.html, enter the following command: pdadmin sec_master> authzrule detach /WebSEAL/tivoli.com/w3junction/index.htmlFor more information, see the IBM Security Access Manager for Web: Command Reference.Detach an authorization ruleYou can detach an authorization rule from a protected object with the Web Portal Manager or pdadmin utility.

Detaching an authorization rule with pdadmin

You can detach an authorization rule from a protected object in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the authzrule detach command.

Example

For example, to detach a rule from a protected object named /WebSEAL/tivoli.com/w3junction/index.html, enter the following command:

pdadmin sec_master> authzrule detach /WebSEAL/tivoli.com/w3junction/index.html

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Detach an authorization rule

Locate where an authorization rule is attachedLocate where an authorization rule is attachedYou can find the protected objects that have an authorization rule attached with the Web Portal Manager or pdadmin utility.authorizationrulesfindingManage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.Locating where an authorization rule is attached with Web Portal ManagerYou can locate all the protected objects that are attached to an authorization rule with Web Portal Manager.Locating where an authorization rule is attached with pdadminYou can locate all the protected objects to which an authorization rule is attached in the domain with the pdadmin utility.

Locate where an authorization rule is attached

You can find the protected objects that have an authorization rule attached with the Web Portal Manager or pdadmin utility.

Locating where an authorization rule is attached with Web Portal Manager
You can locate all the protected objects that are attached to an authorization rule with Web Portal Manager.

Locating where an authorization rule is attached with pdadmin
You can locate all the protected objects to which an authorization rule is attached in the domain with the pdadmin utility.

Parent topic: Manage authorization rules

Locating where an authorization rule is attached with Web Portal ManagerLocating where an authorization rule is attached with Web Portal ManagerYou can locate all the protected objects that are attached to an authorization rule with Web Portal Manager.authorizationruleslocating with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRuleList AuthzRule. A list of authorization names is displayed. Each authorization rule name is a link that you can click to display the AuthzRule Properties page.Click the Attach tab.Locate where an authorization rule is attachedYou can find the protected objects that have an authorization rule attached with the Web Portal Manager or pdadmin utility.

Locating where an authorization rule is attached with Web Portal Manager

You can locate all the protected objects that are attached to an authorization rule with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule > List AuthzRule. A list of authorization names is displayed. Each authorization rule name is a link that you can click to display the AuthzRule Properties page.

Click the Attach tab.

Parent topic: Locate where an authorization rule is attached

Locating where an authorization rule is attached with pdadminLocating where an authorization rule is attached with pdadminYou can locate all the protected objects to which an authorization rule is attached in the domain with the pdadmin utility.authorizationruleslocating with pdadmincommandsauthzrule locatingauthzrulecommandsfindauthzrulecommandslocatingLog on to the domain as the domain administrator.Use the authzrule find command.For example, to find the protected objects attached to a rule named r2, enter the following command: pdadmin sec_master> authzrule find r2See the IBM Security Access Manager for Web: Command Reference.Locate where an authorization rule is attachedYou can find the protected objects that have an authorization rule attached with the Web Portal Manager or pdadmin utility.

Locating where an authorization rule is attached with pdadmin

You can locate all the protected objects to which an authorization rule is attached in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the authzrule find command.

Example

For example, to find the protected objects attached to a rule named r2, enter the following command:

pdadmin sec_master> authzrule find r2

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Locate where an authorization rule is attached

Delete an authorization ruleDelete an authorization ruleYou can delete an authorization rule with the Web Portal Manager or pdadmin utility.authorizationrulesdeletingManage authorization rulesThese topics describe how to use the Web Portal Manager or pdadmin utility.Deleting an authorization rule with Web Portal ManagerYou can delete an authorization rule with Web Portal Manager.Deleting an authorization rule with pdadminYou can delete an authorization rule in the domain with the pdadmin utility.

Delete an authorization rule

You can delete an authorization rule with the Web Portal Manager or pdadmin utility.

Deleting an authorization rule with Web Portal Manager
You can delete an authorization rule with Web Portal Manager.

Deleting an authorization rule with pdadmin
You can delete an authorization rule in the domain with the pdadmin utility.

Parent topic: Manage authorization rules

Deleting an authorization rule with Web Portal ManagerDeleting an authorization rule with Web Portal ManagerYou can delete an authorization rule with Web Portal Manager.authorizationrulesdeleting with Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click AuthzRule List AuthzRule to display the Manage AuthzRules page.A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.Select one or more check boxes for the links that you want to delete. For example, you might select the check box for the authorization rule named r2.Click Delete to display the Delete AuthzRules page where you are prompted to confirm or cancel the deletion.Delete an authorization ruleYou can delete an authorization rule with the Web Portal Manager or pdadmin utility.

Deleting an authorization rule with Web Portal Manager

You can delete an authorization rule with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click AuthzRule > List AuthzRule to display the Manage AuthzRules page.

A list of authorization rules that were created in Security Access Manager are displayed. Each rule is a link that displays properties for that rule when selected.

Select one or more check boxes for the links that you want to delete. For example, you might select the check box for the authorization rule named r2.

Click Delete to display the Delete AuthzRules page where you are prompted to confirm or cancel the deletion.

Parent topic: Delete an authorization rule

Deleting an authorization rule with pdadminDeleting an authorization rule with pdadminYou can delete an authorization rule in the domain with the pdadmin utility.authorizationrulesdeleting with pdadmincommandsauthzrule deletingauthzrulecommandsdeleteauthzrulecommandsdeletingLog on to the domain as the domain administrator.Use the authzrule delete command.For example, to delete a rule named r2, enter the following command: pdadmin sec_master> authzrule delete r2See the IBM Security Access Manager for Web: Command Reference.Delete an authorization ruleYou can delete an authorization rule with the Web Portal Manager or pdadmin utility.

Deleting an authorization rule with pdadmin

You can delete an authorization rule in the domain with the pdadmin utility.

Procedure

Log on to the domain as the domain administrator.

Use the authzrule delete command.

Example

For example, to delete a rule named r2, enter the following command:

pdadmin sec_master> authzrule delete r2

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete an authorization rule

Manage users and groupsAn initial domain administrator is created when a new domain is created.domainadministratorusersdefinitionusersaccountsusersmanagement tasksgroupsdefinitiongroupsmanaging accountsgroupsmanagement tasksuseraccountsgroupaccountsaccounts, user and groupThe domain administrator has the necessary privileges to manage the domain. The domain administrator can create and configure users, groups, resources, and applications, and can delegate administration tasks within the domain as required.A user represents any authenticated Security Access Manager identity. Typically, these authenticated identities represent network users or resource managers.A group is a collection of one or more users. An administrator can use group ACL entries to assign the same permissions to multiple users. New users to the domain gain access to objects by becoming members of groups. Group membership eliminates the need to create new ACL entries for each new user. Groups can represent organizational divisions or departments within a domain. Groups are also useful in defining roles or functional associations.An account refers to users and groups collectively.A registry unique identifier (UID) specifies the location in the user registry where the new user is created. Similarly, a registry group unique identifier (GID) specifies the location in the user registry where the new group is created. For registry UIDs and GIDs, you must type the full path name for the new user or group. The path format depends on the type of registry that the product is using. The following list shows sample formats for different user registries: LDAPcn=IBM-Support,o=ibm,c=usActive Directorycn=IBM-Support,dc=Austin,dc=USThe registry UID or registry GID provides extra security in the case where a user or group is deleted from the domain and then recreated with the same name. For example, even though a new user has the same name as the deleted user, Security Access Manager allocates a new registry UID to this user. Because the registry UID is new, any existing ACL entries that refer to the old user name do not grant any rights to the new user. Stale UIDs from deleted users and groups are silently removed by the policy server.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Manage usersYou can do the following user tasks: Manage groupsYou can do the following group tasks:Enabling dynamic group supportYou can enable dynamic group support on the policy server and all servers where dynamic groups are supported. Use the pdadmin utility. The command that you run depends on the type of user registry.

Manage users and groups

An initial domain administrator is created when a new domain is created.

The domain administrator has the necessary privileges to manage the domain. The domain administrator can create and configure users, groups, resources, and applications, and can delegate administration tasks within the domain as required.

A user represents any authenticated Security Access Manager identity. Typically, these authenticated identities represent network users or resource managers.

A group is a collection of one or more users. An administrator can use group ACL entries to assign the same permissions to multiple users. New users to the domain gain access to objects by becoming members of groups. Group membership eliminates the need to create new ACL entries for each new user. Groups can represent organizational divisions or departments within a domain. Groups are also useful in defining roles or functional associations.

An account refers to users and groups collectively.

A registry unique identifier (UID) specifies the location in the user registry where the new user is created. Similarly, a registry group unique identifier (GID) specifies the location in the user registry where the new group is created. For registry UIDs and GIDs, you must type the full path name for the new user or group. The path format depends on the type of registry that the product is using. The following list shows sample formats for different user registries:

LDAP

cn=IBM-Support,o=ibm,c=us

Active Directory

cn=IBM-Support,dc=Austin,dc=US

The registry UID or registry GID provides extra security in the case where a user or group is deleted from the domain and then recreated with the same name. For example, even though a new user has the same name as the deleted user, Security Access Manager allocates a new registry UID to this user. Because the registry UID is new, any existing ACL entries that refer to the old user name do not grant any rights to the new user. Stale UIDs from deleted users and groups are silently removed by the policy server.

Manage users
You can do the following user tasks:

Manage groups
You can do the following group tasks:

Enabling dynamic group support
You can enable dynamic group support on the policy server and all servers where dynamic groups are supported. Use the pdadmin utility. The command that you run depends on the type of user registry.

Parent topic: Access Manager Platform and Supporting Components administration

Manage usersYou can do the following user tasks: usersmanagement tasksIn the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.Manage users and groupsAn initial domain administrator is created when a new domain is created.Create a userYou can create a user with the Web Portal Manager or pdadmin utility.List usersYou can search for users with the Web Portal Manager or pdadmin utility.Change a passwordYou can change a user password with the Web Portal Manager or pdadmin utility.Setting user policyYou can change the user policy settings for specific users, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.Setting global user policyYou can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.Import usersYou can import a user that exists in a user registry and make that user a Security Access Manager user with the Web Portal Manager or pdadmin utility.Delete a userYou can delete a user with the Web Portal Manager or pdadmin utility.

Manage users

You can do the following user tasks:

In the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Create a user
You can create a user with the Web Portal Manager or pdadmin utility.

List users
You can search for users with the Web Portal Manager or pdadmin utility.

Change a password
You can change a user password with the Web Portal Manager or pdadmin utility.

Setting user policy
You can change the user policy settings for specific users, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Setting global user policy
You can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Import users
You can import a user that exists in a user registry and make that user a Security Access Manager user with the Web Portal Manager or pdadmin utility.

Delete a user
You can delete a user with the Web Portal Manager or pdadmin utility.

Parent topic: Manage users and groups

Create a userCreate a userCreate a userYou can create a user with the Web Portal Manager or pdadmin utility.userscreatingWhen a user is created, the domain administrator assigns a user name, which is sometimes called a principal name. The user name must be unique within the domain, because it is used by Security Access Manager to identify this user. A registry user identifier, known as a distinguished name (DN), is also assigned to uniquely identify the user definition in the user registry. The format of the DN depends on the registry type that is being used. Also assigned are the common name (CN) and surname (SN) of the user that is being defined.When Active Directory Lightweight Directory Service (AD LDS) is used as the user registry, users must be created within the same AD LDS partition in which Security Access Manager was configured.Manage usersYou can do the following user tasks: Creating a user with Web Portal ManagerYou can create a user in a domain with Web Portal Manager.Creating a user with pdadminYou can create a user with the pdadmin utility.

Create a user

You can create a user with the Web Portal Manager or pdadmin utility.

When a user is created, the domain administrator assigns a user name, which is sometimes called a principal name. The user name must be unique within the domain, because it is used by Security Access Manager to identify this user. A registry user identifier, known as a distinguished name (DN), is also assigned to uniquely identify the user definition in the user registry. The format of the DN depends on the registry type that is being used. Also assigned are the common name (CN) and surname (SN) of the user that is being defined.

Note: When Active Directory Lightweight Directory Service (AD LDS) is used as the user registry, users must be created within the same AD LDS partition in which Security Access Manager was configured.

Creating a user with Web Portal Manager
You can create a user in a domain with Web Portal Manager.

Creating a user with pdadmin
You can create a user with the pdadmin utility.

Parent topic: Manage users

Creating a user with Web Portal ManagerYou can create a user in a domain with Web Portal Manager.userscreatingwith Web Portal ManagerUse Web Portal Manager to log on to the domain as a domain administrator.Click User → Create User.In the User Id text field, type the user name (for example maryj).Click Group Membership to search for groups in which the user can be a member.In the First Name text field, type the name of the user (for example Mary).In the Last Name text field, type the family or surname of the user (for example Jones).In the Password text field, type the password. Passwords must adhere to the password policies that are set by the domain administrator. In the Confirm Password text field, type the password again.In the Description text field, type the description for the user (for example, Member of Marketing Group.In the Registry UID text field, type the registry UID. The registry UID specifies the location in the user registry where the new user is created. For example: cn=maryj,o=ibm,c=us,dc=mkt. Lotus Notes users require the full path name for the user that is being created. For example: Mary Jones/IBM/USSelect the Account Valid check box to indicate that the new user can participate in the domain. If this option is not selected, the new user account is not valid and the user cannot log on.Select the GSO User check box to indicate the use of global sign-on (single sign-on) for Security Access Manager.Select the Password Valid check box to force a password change the next time the user logs in to the domain. If this option is not selected, the user is informed that the password expired.Click No Password Policy to indicate that you do not want the initial password to conform to the password policies that are set by the domain administrator.Click Create. A message is shown if the user ID is created.Create a userYou can create a user with the Web Portal Manager or pdadmin utility.

Creating a user with Web Portal Manager

You can create a user in a domain with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the domain as a domain administrator.

Click User → Create User.

In the User Id text field, type the user name (for example maryj).

Click Group Membership to search for groups in which the user can be a member.

In the First Name text field, type the name of the user (for example Mary).

In the Last Name text field, type the family or surname of the user (for example Jones).

In the Password text field, type the password. Passwords must adhere to the password policies that are set by the domain administrator.

In the Confirm Password text field, type the password again.

In the Description text field, type the description for the user (for example, Member of Marketing Group.

In the Registry UID text field, type the registry UID. The registry UID specifies the location in the user registry where the new user is created. For example: cn=maryj,o=ibm,c=us,dc=mkt. Lotus® Notes® users require the full path name for the user that is being created. For example: Mary Jones/IBM/US

Select the Account Valid check box to indicate that the new user can participate in the domain. If this option is not selected, the new user account is not valid and the user cannot log on.

Select the GSO User check box to indicate the use of global sign-on (single sign-on) for Security Access Manager.

Select the Password Valid check box to force a password change the next time the user logs in to the domain. If this option is not selected, the user is informed that the password expired.

Click No Password Policy to indicate that you do not want the initial password to conform to the password policies that are set by the domain administrator.

Click Create.

Results

A message is shown if the user ID is created.

Parent topic: Create a user

Creating a user with pdadminYou can create a user with the pdadmin utility.userscreatingwith pdadmincommandsusercreatinguserscommandscreateLog on to the appropriate domain as a domain administrator.Use the user create command to create the user.For example, to create the user named maryj with global sign-on capability, enter the following command: pdadmin sec_master> user create –gsouser maryj "cn=Mary Jones,o=IBM,c=us,dc=mkt" \ "Mary Jones" Jones pwd2pwd2The format of the distinguished name depends on the type of user registry. For more information, see the IBM Security Access Manager for Web: Command Reference.Create a userYou can create a user with the Web Portal Manager or pdadmin utility.

Creating a user with pdadmin

You can create a user with the pdadmin utility.

Procedure

Log on to the appropriate domain as a domain administrator.

Use the user create command to create the user.

Example

For example, to create the user named maryj with global sign-on capability, enter the following command:

pdadmin sec_master> user create –gsouser maryj "cn=Mary Jones,o=IBM,c=us,dc=mkt" \
"Mary Jones" Jones pwd2pwd2

The format of the distinguished name depends on the type of user registry. For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create a user

List usersList usersList usersYou can search for users with the Web Portal Manager or pdadmin utility.userssearchinguserslistingwildcards, limiting useHowever, when the user registry contains many user definitions, use wildcard characters with discretion. When a pattern includes one or more wildcard characters, the command attempts to find all user definitions that match the specified pattern. However, the command displays only the specified number of matching definitions in the user registry. If the user registry contains 10,000 definitions, specifying a single wildcard (*), with a limit of 100, finds all 10,000 definitions. However, the command displays only the first 100 matching definitions. If many users are defined in the user registry (for example, more than 100,000), avoid specifying the global wildcard (*). Instead, use a search filter that is as specific as possible, or qualify the search pattern to limit the search results. For example, you might use the pdadmin tool and list users whose names start with John. Limit the search results by specifying the number of records to return, as in the following command: pdadmin user list john* 100 For the specific syntax of the user list command, see the IBM Security Access Manager for Web: Command Reference.For more specific information about tuning the directory server to achieve best results, see the IBM Security Access Manager for Web: Performance Tuning Guide.Manage usersYou can do the following user tasks: Listing users with Web Portal ManagerYou can search for and list up to a maximum of 100 users with Web Portal Manager. Listing users with pdadminYou can search for a list of users with the pdadmin utility.

List users

You can search for users with the Web Portal Manager or pdadmin utility.

However, when the user registry contains many user definitions, use wildcard characters with discretion. When a pattern includes one or more wildcard characters, the command attempts to find all user definitions that match the specified pattern. However, the command displays only the specified number of matching definitions in the user registry. If the user registry contains 10,000 definitions, specifying a single wildcard ("*"), with a limit of 100, finds all 10,000 definitions. However, the command displays only the first 100 matching definitions.

Note: If many users are defined in the user registry (for example, more than 100,000), avoid specifying the global wildcard (*). Instead, use a search filter that is as specific as possible, or qualify the search pattern to limit the search results.

For example, you might use the pdadmin tool and list users whose names start with John. Limit the search results by specifying the number of records to return, as in the following command: pdadmin user list john* 100

For the specific syntax of the user list command, see the IBM Security Access Manager for Web: Command Reference.

For more specific information about tuning the directory server to achieve best results, see the IBM Security Access Manager for Web: Performance Tuning Guide.

Listing users with Web Portal Manager
You can search for and list up to a maximum of 100 users with Web Portal Manager.

Listing users with pdadmin
You can search for a list of users with the pdadmin utility.

Parent topic: Manage users

Listing users with Web Portal ManagerYou can search for and list up to a maximum of 100 users with Web Portal Manager. userslistingwith Web Portal ManagerUse Web Portal Manager to log on to the appropriate domain as a domain administrator.Click UserSearch Users to display the User Search page.At the User Search page, specify the pattern to filter user ID names. Use wildcard characters with discretion.Use the default value of 100 or type another value in the Maximum Results field. This number limits the number of user IDs that are displayed.Click Search to display a table of user IDs. Each user ID is displayed as a link.From the User Search page, you can do these tasks: create a user, delete one or more existing users, and click the link to view user properties.Use the default value of 15 user IDs per page, or click Options to type the number of user IDs to view per page. Toggle back by clicking Hide Options.Use the default value of None, meaning that no text is used for filtering. Alternatively, click Filters to find user IDs that contain, start with, or end with the text that you specify. Toggle back by clicking Hide Filters.List usersYou can search for users with the Web Portal Manager or pdadmin utility.

Listing users with Web Portal Manager

You can search for and list up to a maximum of 100 users with Web Portal Manager.

Procedure

Use Web Portal Manager to log on to the appropriate domain as a domain administrator.

Click User > Search Users to display the User Search page.

At the User Search page, specify the pattern to filter user ID names. Use wildcard characters with discretion.

Use the default value of 100 or type another value in the Maximum Results field. This number limits the number of user IDs that are displayed.

Click Search to display a table of user IDs. Each user ID is displayed as a link.

From the User Search page, you can do these tasks: create a user, delete one or more existing users, and click the link to view user properties.

Use the default value of 15 user IDs per page, or click Options to type the number of user IDs to view per page. Toggle back by clicking Hide Options.

Use the default value of None, meaning that no text is used for filtering. Alternatively, click Filters to find user IDs that contain, start with, or end with the text that you specify. Toggle back by clicking Hide Filters.

Parent topic: List users

Listing users with pdadminYou can search for a list of users with the pdadmin utility.userslistingwith pdadmincommandsuserlistinguserscommandslistLog on to the domain as a domain administrator.Use the user list command to list users.For example, to search for and list up to a maximum of 100 users, enter the following command: pdadmin sec_master> user list * 100For more information, see the IBM Security Access Manager for Web: Command Reference.List usersYou can search for users with the Web Portal Manager or pdadmin utility.

Listing users with pdadmin

You can search for a list of users with the pdadmin utility.

Procedure

Log on to the domain as a domain administrator.

Use the user list command to list users.

Example

For example, to search for and list up to a maximum of 100 users, enter the following command:

pdadmin sec_master> user list * 100

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: List users

Change a passwordChange a passwordChange a passwordYou can change a user password with the Web Portal Manager or pdadmin utility.passwordchanginguserpasswords, changingThe new password must comply with the password policies that are currently in effect. You might use Active Directory as your user registry with the Active Directory server on Windows 2008 SP1 or later. In this case, old passwords might still be able to be used after a password change. See the following web page:http://support.microsoft.com/?id=906305When setting or changing a password, the password must comply with the following policies: The defined Security Access Manager password policyThe password policy for the underlying operating systemThe password policy for the underlying user registryWhen enforcing the password policy, Security Access Manager validates compliance in the following sequence: Against the Security Access Manager password policy currently in effectAgainst the underlying user registryAlthough a password complies to the defined Security Access Manager password policy, validation might fail against the password policy of the underlying operating system or user registry.For additional information about setting the password policy for Security Access Manager users, see Setting global user policyYou can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility..Manage usersYou can do the following user tasks: Changing a password with Web Portal ManagerYou can change the password for the specified user ID with Web Portal Manager.Changing a password with pdadminYou can change the password for the user with the pdadmin utility.

Change a password

You can change a user password with the Web Portal Manager or pdadmin utility.

The new password must comply with the password policies that are currently in effect.

Note: You might use Active Directory as your user registry with the Active Directory server on Windows 2008 SP1 or later. In this case, old passwords might still be able to be used after a password change.

See the following web page:

http://support.microsoft.com/?id=906305

When setting or changing a password, the password must comply with the following policies:

The defined Security Access Manager password policy

The password policy for the underlying operating system

The password policy for the underlying user registry

When enforcing the password policy, Security Access Manager validates compliance in the following sequence:

Against the Security Access Manager password policy currently in effect

Against the underlying user registry

Although a password complies to the defined Security Access Manager password policy, validation might fail against the password policy of the underlying operating system or user registry.

For additional information about setting the password policy for Security Access Manager users, see Setting global user policy.

Changing a password with Web Portal Manager
You can change the password for the specified user ID with Web Portal Manager.

Changing a password with pdadmin
You can change the password for the user with the pdadmin utility.

Parent topic: Manage users

Changing a password with Web Portal ManagerYou can change the password for the specified user ID with Web Portal Manager.userspassword with Web Portal Manager, changingUse Web Portal Manager to log in to the domain as a domain administrator.Click User → Change My Password.Verify that the User ID identifies the login identifier for the user whose password you want to change.In the Current Password text field, type the existing password for the specified user ID.In the New Password text field, type the new password for the specified user ID.In the Confirm New Password text field, type the password again.Click Apply.Change a passwordYou can change a user password with the Web Portal Manager or pdadmin utility.

Changing a password with Web Portal Manager

You can change the password for the specified user ID with Web Portal Manager.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click User → Change My Password.

Verify that the User ID identifies the login identifier for the user whose password you want to change.

In the Current Password text field, type the existing password for the specified user ID.

In the New Password text field, type the new password for the specified user ID.

In the Confirm New Password text field, type the password again.

Click Apply.

Parent topic: Change a password

Changing a password with pdadminYou can change the password for the user with the pdadmin utility.userschanging with pdadmincommandsusermodifying passworduserscommandsmodify passwordLog in to the domain as a domain administrator.Use the user modify command with the password option.For example, to change the password for the user dlucas to newpasswd, enter the following command: pdadmin sec_master> user modify dlucas password newpasswdFor more information, see the IBM Security Access Manager for Web: Command Reference.Change a passwordYou can change a user password with the Web Portal Manager or pdadmin utility.

Changing a password with pdadmin

You can change the password for the user with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the user modify command with the password option.

Example

For example, to change the password for the user dlucas to newpasswd, enter the following command:

pdadmin sec_master> user modify dlucas password newpasswd

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Change a password

Setting user policySetting user policySetting user policyYou can change the user policy settings for specific users, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.userssetting user policyuserspoliciescompliance with operating systems, user registriesThe valid range for numbers can be any number. However, use a reasonable number for the task that you want to do. For example, a minimum password length must be long enough to protect your system. The minimum length must not be so short as to make it easy for someone to determine your password by trying different combinations.When defining the password policy, ensure that this definition complies with the password policy of the underlying operating systems and user registries.When using Security Directory Server as your user registry, you can take advantage of its password history policy. For additional information about setting the password history policy when using Security Directory Server as your user registry, see Setting the password history policyIf Security Directory Server is your user registry, you can use its password history policy..When modifying a password policy, you provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.Manage usersYou can do the following user tasks: Setting user policy with Web Portal ManagerYou can change policy settings for a specific user with Web Portal Manager.Setting user policy with pdadminYou can set or change user policy settings with the pdadmin utility.

Setting user policy

You can change the user policy settings for specific users, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Note:

The valid range for numbers can be any number. However, use a reasonable number for the task that you want to do. For example, a minimum password length must be long enough to protect your system. The minimum length must not be so short as to make it easy for someone to determine your password by trying different combinations.

When defining the password policy, ensure that this definition complies with the password policy of the underlying operating systems and user registries.

When using Security Directory Server as your user registry, you can take advantage of its password history policy. For additional information about setting the password history policy when using Security Directory Server as your user registry, see Setting the password history policy.

When modifying a password policy, you provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.

Setting user policy with Web Portal Manager
You can change policy settings for a specific user with Web Portal Manager.

Setting user policy with pdadmin
You can set or change user policy settings with the pdadmin utility.

Parent topic: Manage users

Setting user policy with Web Portal ManagerYou can change policy settings for a specific user with Web Portal Manager.userspoliciessetting with Web Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click UserSearch Users to display the User Search page.From the list of matching users, select the user whose policy is to be changed. The User Properties page for that user is displayed.Click the Policy tab.Modify the following policies as needed:For Max Login Failures, select Unset or Set to set or unset the maximum number of login failures before the account is no longer allowed to participate in the secure domain. If you select Set, either accept the default value of 10 or change the value to a number equal to or greater than zero.For Disable Time Interval, select Unset, Disable, or Set to set the time, in seconds, or to disable each user account when the maximum number of login failures is exceeded. If you select Set, either accept the default value of 180 seconds or change the value to a number equal to or greater than zero.For Minimum Password Length, select Unset or Set to set the minimum number of characters required for the password. If you select Set, either accept the default value of eight alphanumeric characters or change the value to a number greater than zero.For Maximum Password Age, select Unset or Set to set the maximum time that a password can be used before it expires. The maximum password age is relative to the last time the password was changed. If you select Set, either accept the default value of 91 days (91-00:00:00) or change the value to a number equal to or greater than zero. A value of 0 (000-00:00:00) indicates that the password never expires.For Minimum Password Alphas, select Unset or Set to set the minimum number of alphabetical characters required in a password. If you select Set, either accept the default value of four alphabetical characters or change the value to a number greater than zero.For Minimum Password Non-Alphas, select Unset or Set to set the minimum number of non-alphabetic characters required in a password. If you select Set, either accept the default value of one non-alphabetic character or change the value to a number greater than one.For Max Password Repeated Characters, select Unset or Set to set the maximum number of repeated characters allowed in a password. If you select Set, either accept the default value of two repeated characters or change the value to a number greater than two.For Password Spaces Allowed, select Unset, Yes, or No to determine whether spaces are allowed in passwords. You can accept the default setting of Unset. You can change the value to Yes to allow spaces in passwords or to No to not allow spaces in passwords.For Max Concurrent Web Sessions, select Displace, Unset, Unlimited, or Set to set the maximum number of concurrent web sessions allowed. If you select Set, type a number equal to or greater than one. This policy applies only to certain components. A web session is a user session that is maintained by the web security solutions, such as WebSEAL and plug-ins for web servers. Refer to the component administration guides to see whether this setting is applicable and whether specific configuration options are required to enforce this policy.For Account Expiration Date, select Unset, Unlimited, or Set to set the account expiration date. You can accept the default setting of Unset. You can change it to Unlimited or Set. If you select Set, type the four-digit year in the Year field. Either accept the default value of Jan 01-00:00:00 or change the value to the date and time, specified as Month DD:hh:mm:ss. The hours must be entered using a 24-hour clock (for example, 09 for 9:00 a.m. or 14 for 2:00 p.m.). For Time of Day Access, select Unset or Set to set the time of day access policy. If you select Set, either accept the default settings or change them. You can change these values: Select the days of the week from the choices provided.Select All Day or Between hours of. If you select Between hours of, also select the Start Time. The start time format is specified as hours and minutes. The start time is expressed by using a 24-hour clock. If you select Between hours of, also select the End Time. The end time format is specified as hours and minutes. The end time is expressed by using a 24-hour clock. If you select Between hours of, also select Local Time or UTC Time. The time zone is local by default; UTC is Coordinated Universal Time.Click Apply.Setting user policyYou can change the user policy settings for specific users, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Setting user policy with Web Portal Manager

You can change policy settings for a specific user with Web Portal Manager.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click User > Search Users to display the User Search page.

From the list of matching users, select the user whose policy is to be changed. The User Properties page for that user is displayed.

Click the Policy tab.

Modify the following policies as needed:

For Max Login Failures, select Unset or Set to set or unset the maximum number of login failures before the account is no longer allowed to participate in the secure domain. If you select Set, either accept the default value of 10 or change the value to a number equal to or greater than zero.

For Disable Time Interval, select Unset, Disable, or Set to set the time, in seconds, or to disable each user account when the maximum number of login failures is exceeded. If you select Set, either accept the default value of 180 seconds or change the value to a number equal to or greater than zero.

For Minimum Password Length, select Unset or Set to set the minimum number of characters required for the password. If you select Set, either accept the default value of eight alphanumeric characters or change the value to a number greater than zero.

For Maximum Password Age, select Unset or Set to set the maximum time that a password can be used before it expires. The maximum password age is relative to the last time the password was changed. If you select Set, either accept the default value of 91 days (91-00:00:00) or change the value to a number equal to or greater than zero. A value of 0 (000-00:00:00) indicates that the password never expires.

For Minimum Password Alphas, select Unset or Set to set the minimum number of alphabetical characters required in a password. If you select Set, either accept the default value of four alphabetical characters or change the value to a number greater than zero.

For Minimum Password Non-Alphas, select Unset or Set to set the minimum number of non-alphabetic characters required in a password. If you select Set, either accept the default value of one non-alphabetic character or change the value to a number greater than one.

For Max Password Repeated Characters, select Unset or Set to set the maximum number of repeated characters allowed in a password. If you select Set, either accept the default value of two repeated characters or change the value to a number greater than two.

For Password Spaces Allowed, select Unset, Yes, or No to determine whether spaces are allowed in passwords. You can accept the default setting of Unset. You can change the value to Yes to allow spaces in passwords or to No to not allow spaces in passwords.

For Max Concurrent Web Sessions, select Displace, Unset, Unlimited, or Set to set the maximum number of concurrent web sessions allowed. If you select Set, type a number equal to or greater than one.

Note: This policy applies only to certain components. A web session is a user session that is maintained by the web security solutions, such as WebSEAL and plug-ins for web servers. Refer to the component administration guides to see whether this setting is applicable and whether specific configuration options are required to enforce this policy.

For Account Expiration Date, select Unset, Unlimited, or Set to set the account expiration date. You can accept the default setting of Unset. You can change it to Unlimited or Set.

If you select Set, type the four-digit year in the Year field.

Either accept the default value of Jan 01-00:00:00 or change the value to the date and time, specified as Month DD:hh:mm:ss. The hours must be entered using a 24-hour clock (for example, 09 for 9:00 a.m. or 14 for 2:00 p.m.).

For Time of Day Access, select Unset or Set to set the time of day access policy. If you select Set, either accept the default settings or change them.

You can change these values:

Select the days of the week from the choices provided.

Select All Day or Between hours of.

If you select Between hours of, also select the Start Time. The start time format is specified as hours and minutes. The start time is expressed by using a 24-hour clock.

If you select Between hours of, also select the End Time. The end time format is specified as hours and minutes. The end time is expressed by using a 24-hour clock.

If you select Between hours of, also select Local Time or UTC Time. The time zone is local by default; UTC is Coordinated Universal Time.

Click Apply.

Parent topic: Setting user policy

Setting user policy with pdadminYou can set or change user policy settings with the pdadmin utility.userspoliciessetting with pdadmincommandssetting single userpolicycommandsset single userLog in to the domain as a domain administrator.Use the policy set command.For example, to set the maximum password age of 31 days 8 hours and 30 minutes for user bsmith, enter the following command: pdadmin sec_master> policy set max-password-age 031-08:30:00 -user bsmithFor more information, see the IBM Security Access Manager for Web: Command Reference.Setting user policyYou can change the user policy settings for specific users, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Setting user policy with pdadmin

You can set or change user policy settings with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the policy set command.

Example

For example, to set the maximum password age of 31 days 8 hours and 30 minutes for user bsmith, enter the following command:

pdadmin sec_master> policy set max-password-age 031-08:30:00 -user bsmith

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Setting user policy

Setting global user policyYou can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.globaluser policy, settinguserpolicies, global setting The valid range for numbers can be any number. However, use a reasonable number for the task that you want to do. For example, a minimum password length must be long enough to protect your system. The minimum length must not be so short as to make it easy for someone to determine passwords by trying different combinations.When you define the password policy, ensure that this definition complies with the password policy of the underlying operating systems and user registries.When you use Security Directory Server as your user registry, you can take advantage of its password history policy. For more information about setting the password history policy when you use Security Directory Server as your user registry, see Setting the password history policyIf Security Directory Server is your user registry, you can use its password history policy..When you modify a password policy, provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.Certain global user policies can be applied to basic users. See the following table for which policies are available to basic users.Global user policies for basic usersPolicyAvailable to basic usersaccount-expiry-dateYesdisable-time-intervalNomax-concurrent-web-sessionsYesmax-login-failuresNomax-password-ageNomax-password-repeated-charsYesmin-password-alphasYesmin-password-lengthYesmin-password-non-alphasYespassword-spacesYestod-accessYesManage usersYou can do the following user tasks: Setting global user policy with Web Portal ManagerYou can change global user settings with Web Portal Manager.Setting global user policy with pdadminYou can set or change global user settings with the pdadmin utility.

Setting global user policy

You can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Notes:

The valid range for numbers can be any number. However, use a reasonable number for the task that you want to do. For example, a minimum password length must be long enough to protect your system. The minimum length must not be so short as to make it easy for someone to determine passwords by trying different combinations.

When you define the password policy, ensure that this definition complies with the password policy of the underlying operating systems and user registries.

When you use Security Directory Server as your user registry, you can take advantage of its password history policy. For more information about setting the password history policy when you use Security Directory Server as your user registry, see Setting the password history policy.

When you modify a password policy, provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.

Certain global user policies can be applied to basic users. See the following table for which policies are available to basic users.

Table 173. Global user policies for basic users

Policy | Available to basic users
account-expiry-date | Yes
disable-time-interval | No
max-concurrent-web-sessions | Yes
max-login-failures | No
max-password-age | No
max-password-repeated-chars | Yes
min-password-alphas | Yes
min-password-length | Yes
min-password-non-alphas | Yes
password-spaces | Yes
tod-access | Yes

Setting global user policy with Web Portal Manager
You can change global user settings with Web Portal Manager.

Setting global user policy with pdadmin
You can set or change global user settings with the pdadmin utility.

Parent topic: Manage users

Setting global user policy with Web Portal ManagerYou can change global user settings with Web Portal Manager.usersglobal policy, setting with Web Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click User → Show Global User Policy.For Max Login Failures, select Unset or Set to set or clear the maximum number of login failures before the account is no longer allowed to participate in the secure domain. If you select Set, either accept the default value of 10 or change the value to a number equal to or greater than zero.For Disable Time Interval, select Unset, Disable, or Set to set the time, in seconds, or to disable each user account when the maximum number of login failures is exceeded. If you select Set, either accept the default value of 180 seconds or change the value to a number equal to or greater than zero.For Minimum Password Length, select Unset or Set to set the minimum number of characters required for the password. If you select Set, either accept the default value of eight alphanumeric characters or change the value to a number greater than zero.For Maximum Password Age, select Unset or Set to set the maximum time that a password can be used before it expires. The maximum password age is relative to the last time the password was changed. If you select Set, either accept the default value of 91 days (91-00:00:00) or change the value to a number greater than zero.For Minimum Password Alphas, select Unset or Set to set the minimum number of alphabetical characters required in a password. If you select Set, either accept the default value of four alphabetical characters or change the value to a number greater than zero.For Minimum Password Non-Alphas, select Unset or Set to set the minimum number of non-alphabetic characters required in a password. If you select Set, either accept the default value of one non-alphabetic character or change the value to a number greater than one.For Max Password Repeated Characters, select Unset or Set to set the maximum number of repeated characters allowed in a password. If you select Set, either accept the default value of two repeated characters or change the value to a number greater than two.For Password Spaces Allowed, select Unset, Yes, or No to determine whether spaces are allowed in passwords. You can accept the default setting of Unset. You can change the value to Yes to allow spaces in passwords or to No to not allow spaces in passwords.For Max Concurrent Web Sessions, select Displace, Unset, Unlimited, or Set to set the maximum number of concurrent web sessions to allow. If you select Set, type a number equal to or greater than one. This policy applies only to certain components. A web session is a user session that is maintained by the web security solutions, such as WebSEAL and plug-ins for web servers. Refer to the component administration guides to see whether this setting is applicable and whether specific configuration options are required to enforce this policy.For Account Expiration Date, select Unset, Unlimited, or Set to set the account expiration date. You can accept the default setting of Unset. You can change it to Unlimited or Set. If you select Set, type the four-digit year in the Year field. Either accept the default value of Jan 01-00:00:00 or change the value to the date and time, specified as Month DD:hh:mm:ss. The hours must be entered using a 24-hour clock (for example, 09 for 9:00 a.m. or 14 for 2:00 p.m.).For Time of Day Access, select Unset or Set to set the time of day access policy. If you select Set, either accept the default settings or change them.You can change these values: Select the days of the week from the choices provided.Select All Day or Between hours of. If you select Between hours of, also select the Start Time. The start time format is specified as hours and minutes. The start time is expressed by using a 24-hour clock. If you select Between hours of, also select the End Time. The end time format is specified as hours and minutes. The end time is expressed by using a 24-hour clock. If you select Between hours of, also select Local Time or UTC Time. The time zone is local by default; UTC is Coordinated Universal Time.Click Apply.Setting global user policyYou can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Setting global user policy with Web Portal Manager

You can change global user settings with Web Portal Manager.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click User → Show Global User Policy.

For Max Login Failures, select Unset or Set to set or clear the maximum number of login failures before the account is no longer allowed to participate in the secure domain. If you select Set, either accept the default value of 10 or change the value to a number equal to or greater than zero.

For Disable Time Interval, select Unset, Disable, or Set to set the time, in seconds, or to disable each user account when the maximum number of login failures is exceeded. If you select Set, either accept the default value of 180 seconds or change the value to a number equal to or greater than zero.

For Minimum Password Length, select Unset or Set to set the minimum number of characters required for the password. If you select Set, either accept the default value of eight alphanumeric characters or change the value to a number greater than zero.

For Maximum Password Age, select Unset or Set to set the maximum time that a password can be used before it expires. The maximum password age is relative to the last time the password was changed. If you select Set, either accept the default value of 91 days (91-00:00:00) or change the value to a number greater than zero.

For Minimum Password Alphas, select Unset or Set to set the minimum number of alphabetical characters required in a password. If you select Set, either accept the default value of four alphabetical characters or change the value to a number greater than zero.

For Minimum Password Non-Alphas, select Unset or Set to set the minimum number of non-alphabetic characters required in a password. If you select Set, either accept the default value of one non-alphabetic character or change the value to a number greater than one.

For Max Password Repeated Characters, select Unset or Set to set the maximum number of repeated characters allowed in a password. If you select Set, either accept the default value of two repeated characters or change the value to a number greater than two.

For Password Spaces Allowed, select Unset, Yes, or No to determine whether spaces are allowed in passwords. You can accept the default setting of Unset. You can change the value to Yes to allow spaces in passwords or to No to not allow spaces in passwords.

For Max Concurrent Web Sessions, select Displace, Unset, Unlimited, or Set to set the maximum number of concurrent web sessions to allow. If you select Set, type a number equal to or greater than one.

Note: This policy applies only to certain components. A web session is a user session that is maintained by the web security solutions, such as WebSEAL and plug-ins for web servers. Refer to the component administration guides to see whether this setting is applicable and whether specific configuration options are required to enforce this policy.

For Account Expiration Date, select Unset, Unlimited, or Set to set the account expiration date. You can accept the default setting of Unset. You can change it to Unlimited or Set.

If you select Set, type the four-digit year in the Year field.

Either accept the default value of Jan 01-00:00:00 or change the value to the date and time, specified as Month DD:hh:mm:ss. The hours must be entered using a 24-hour clock (for example, 09 for 9:00 a.m. or 14 for 2:00 p.m.).

For Time of Day Access, select Unset or Set to set the time of day access policy. If you select Set, either accept the default settings or change them.

You can change these values:

Select the days of the week from the choices provided.

Select All Day or Between hours of.

If you select Between hours of, also select the Start Time. The start time format is specified as hours and minutes. The start time is expressed by using a 24-hour clock.

If you select Between hours of, also select the End Time. The end time format is specified as hours and minutes. The end time is expressed by using a 24-hour clock.

If you select Between hours of, also select Local Time or UTC Time. The time zone is local by default; UTC is Coordinated Universal Time.

Click Apply.

Parent topic: Setting global user policy

Setting global user policy with pdadminYou can set or change global user settings with the pdadmin utility.usersglobal policysetting with pdadmincommandsglobal user, settingpolicycommandsset all usersLog in to the domain as a domain administrator.Use the policy set command.For example, to set a global user policy to a maximum password age of 31 days 8 hours and 30 minutes, enter the following command: pdadmin sec_master> policy set max-password-age 031-08:30:00For more information, see the IBM Security Access Manager for Web: Command Reference.Setting global user policyYou can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies with the Web Portal Manager or pdadmin utility.

Setting global user policy with pdadmin

You can set or change global user settings with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the policy set command.

Example

For example, to set a global user policy to a maximum password age of 31 days 8 hours and 30 minutes, enter the following command:

pdadmin sec_master> policy set max-password-age 031-08:30:00

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Setting global user policy

Import usersImport usersImport usersYou can import a user that exists in a user registry and make that user a Security Access Manager user with the Web Portal Manager or pdadmin utility.usersimportingWhen a user is imported, the domain administrator assigns a user name, which is sometimes called a principal name. The user name must be unique within the domain because it is used by Security Access Manager to identify this user.When AD LDS is used as the user registry, you can import only existing users defined within the same AD LDS partition in which Security Access Manager was configured.Manage usersYou can do the following user tasks: Importing users with Web Portal ManagerYou can import a user that exists in a user registry and make that user a Security Access Manager user.Importing groups with pdadminYou can import a user that exists in a user registry and make that user a Security Access Manager user with the pdadmin utility.

Import users

You can import a user that exists in a user registry and make that user a Security Access Manager user with the Web Portal Manager or pdadmin utility.

When a user is imported, the domain administrator assigns a user name, which is sometimes called a principal name. The user name must be unique within the domain because it is used by Security Access Manager to identify this user.

Note: When AD LDS is used as the user registry, you can import only existing users defined within the same AD LDS partition in which Security Access Manager was configured.

Importing users with Web Portal Manager
You can import a user that exists in a user registry and make that user a Security Access Manager user.

Importing groups with pdadmin
You can import a user that exists in a user registry and make that user a Security Access Manager user with the pdadmin utility.

Parent topic: Manage users

Importing users with Web Portal ManagerYou can import a user that exists in a user registry and make that user a Security Access Manager user.usersimportingwithWeb Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click User → Import User.Type a User Id (for example maryj).Click Group Membership to search for groups in which the user can be a member.Type a Registry UID. The registry UID specifies the location in the user registry to be imported. For example: cn=maryj,o=ibm,c=us,dc=mkt. Lotus Notes users require the full path name for the user that is being imported. For example: Mary Jones/IBM/USSelect the Account Valid check box to indicate that the new user can participate in the domain. If this option is not selected, the new user account is not valid and the user cannot log in.Select the GSO User check box to indicate that the user can use the global sign-on (single sign-on) for Security Access Manager.Select the Password Valid check box to force a password change the next time the user logs in to the domain. If this option is not selected, the user is informed that the password expired.Click Create.A message occurs if the user ID is created.Import usersYou can import a user that exists in a user registry and make that user a Security Access Manager user with the Web Portal Manager or pdadmin utility.

Importing users with Web Portal Manager

You can import a user that exists in a user registry and make that user a Security Access Manager user.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click User → Import User.

Type a User Id (for example maryj).

Click Group Membership to search for groups in which the user can be a member.

Type a Registry UID. The registry UID specifies the location in the user registry to be imported. For example: cn=maryj,o=ibm,c=us,dc=mkt. Lotus® Notes® users require the full path name for the user that is being imported. For example: Mary Jones/IBM/US

Select the Account Valid check box to indicate that the new user can participate in the domain. If this option is not selected, the new user account is not valid and the user cannot log in.

Select the GSO User check box to indicate that the user can use the global sign-on (single sign-on) for Security Access Manager.

Select the Password Valid check box to force a password change the next time the user logs in to the domain. If this option is not selected, the user is informed that the password expired.

Click Create.

Results

A message occurs if the user ID is created.

Parent topic: Import users

Importing groups with pdadminYou can import a user that exists in a user registry and make that user a Security Access Manager user with the pdadmin utility.usersimportingwith pdadmincommandsuserimportinguserscommandsimportLog in to the domain as a domain administrator.Use the user import command to import an existing user.For example, to import the user information for the user named maryj from the existing user registry definition, enter the following command:pdadmin sec_master> user import –gsouser maryj "cn=Mary Jones,o=IBM,c=us,dc=mkt"When using an LDAP user registry and if necessary, the user information that is imported to the domain can be imported again to another domain.For more information, see the IBM Security Access Manager for Web: Command Reference.Import usersYou can import a user that exists in a user registry and make that user a Security Access Manager user with the Web Portal Manager or pdadmin utility.

Importing groups with pdadmin

You can import a user that exists in a user registry and make that user a Security Access Manager user with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the user import command to import an existing user.

Example

For example, to import the user information for the user named maryj from the existing user registry definition, enter the following command:

pdadmin sec_master> user import –gsouser maryj "cn=Mary Jones,o=IBM,c=us,dc=mkt"

Note: When using an LDAP user registry and if necessary, the user information that is imported to the domain can be imported again to another domain.

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Import users

Delete a userDelete a userDelete a userYou can delete a user with the Web Portal Manager or pdadmin utility.When you delete a user, this user is removed from all objects with which it is associated. If this user is the only ACL entry that is associated with an ACL policy, no other user or group can manage this ACL policy. Before deleting a user, you must validate that there are other users or groups that can manage this ACL policy.Manage usersYou can do the following user tasks: Deleting a user with Web Portal ManagerYou can delete a user from a domain with the Web Portal Manager.Deleting a user with pdadminYou can delete a user from the domain with the pdadmin utility.

Delete a user

You can delete a user with the Web Portal Manager or pdadmin utility.

When you delete a user, this user is removed from all objects with which it is associated. If this user is the only ACL entry that is associated with an ACL policy, no other user or group can manage this ACL policy. Before deleting a user, you must validate that there are other users or groups that can manage this ACL policy.

Deleting a user with Web Portal Manager
You can delete a user from a domain with the Web Portal Manager.

Deleting a user with pdadmin
You can delete a user from the domain with the pdadmin utility.

Parent topic: Manage users

Deleting a user with Web Portal ManagerYou can delete a user from a domain with the Web Portal Manager.usersdeletingwith Web Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click User → Search Users.Search for one or more user names to delete and click Search.Select the check boxes next to the user names to delete and then click Delete.From the Delete Selected Users page, click Delete Users to confirm the deletion or click Delete Users and Registry Entries to also remove the registry entries associated with the selected users.Delete a userYou can delete a user with the Web Portal Manager or pdadmin utility.

Deleting a user with Web Portal Manager

You can delete a user from a domain with the Web Portal Manager.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click User → Search Users.

Search for one or more user names to delete and click Search.

Select the check boxes next to the user names to delete and then click Delete.

From the Delete Selected Users page, click Delete Users to confirm the deletion or click Delete Users and Registry Entries to also remove the registry entries associated with the selected users.

Parent topic: Delete a user

Deleting a user with pdadminYou can delete a user from the domain with the pdadmin utility.usersdeletingwith pdadmincommandsuserdeleteuserscommandsuser deleteLog in to the domain as a domain administrator.Use the user delete command to delete a user.Any resource credentials associated with a user account are automatically removed when the user account is deleted. If the user does not exist in the user registry, an error is displayed.For example, to delete the user named jdoe and the associated information from the user registry, enter the following command: pdadmin sec_master> user delete –registry jdoeFor more information, see the IBM Security Access Manager for Web: Command Reference.Delete a userYou can delete a user with the Web Portal Manager or pdadmin utility.

Deleting a user with pdadmin

You can delete a user from the domain with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the user delete command to delete a user. Any resource credentials associated with a user account are automatically removed when the user account is deleted. If the user does not exist in the user registry, an error is displayed.

Example

For example, to delete the user named jdoe and the associated information from the user registry, enter the following command:

pdadmin sec_master> user delete –registry jdoe

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete a user

Manage groupsManage groupsManage groupsYou can do the following group tasks:groupsmanagement tasksIn the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.Manage users and groupsAn initial domain administrator is created when a new domain is created.Create a groupYou can create a group with the Web Portal Manager or pdadmin utility.List groupsYou can search for group names with the Web Portal Manager or pdadmin utility.Import groupsYou can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the Web Portal Manager or pdadmin utility.Delete a groupYou can delete a group with the Web Portal Manager or pdadmin utility.

Manage groups

You can do the following group tasks:

In the following sections, instructions are provided for using either Web Portal Manager or pdadmin, or both. For online help while usingWeb Portal Manager, click the question mark to open a separate help window for the current page.

Create a group
You can create a group with the Web Portal Manager or pdadmin utility.

List groups
You can search for group names with the Web Portal Manager or pdadmin utility.

Import groups
You can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the Web Portal Manager or pdadmin utility.

Delete a group
You can delete a group with the Web Portal Manager or pdadmin utility.

Parent topic: Manage users and groups

Create a groupCreate a groupCreate a groupYou can create a group with the Web Portal Manager or pdadmin utility.When a group is created, the domain administrator assigns a group name. The group name must be unique within the domain because it is used by Security Access Manager to identify this group.When Active Directory Lightweight Directory Service (AD LDS) is used as the user registry, groups must be created within the same AD LDS partition in which Security Access Manager was configured.Manage groupsYou can do the following group tasks:Creating a group with Web Portal ManagerYou can create a group in the domain with Web Portal Manager.Creating a group with pdadminYou can create a group in the domain with the pdadmin utility.

Create a group

You can create a group with the Web Portal Manager or pdadmin utility.

When a group is created, the domain administrator assigns a group name. The group name must be unique within the domain because it is used by Security Access Manager to identify this group.

Note: When Active Directory Lightweight Directory Service (AD LDS) is used as the user registry, groups must be created within the same AD LDS partition in which Security Access Manager was configured.

Creating a group with Web Portal Manager
You can create a group in the domain with Web Portal Manager.

Creating a group with pdadmin
You can create a group in the domain with the pdadmin utility.

Parent topic: Manage groups

Creating a group with Web Portal ManagerYou can create a group in the domain with Web Portal Manager.groupscreatingwith Web Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click Group → Create Group.Type a Group Name for the group (for example, sales).Optional: Type a Description for the group (for example, Sales).Type a Registry GID. The registry GID specifies the location in the user registry where the new group is created. For example: cn=Sales,o=ibm,c=us,dc=mkt. Lotus Notes users require the full path name for the group that is being created. For example: Sales/IBM/US.Optional: Type the path in the Object Container field to the Security Access Manager object space where the group is to be created.Click Create. The new group is displayed as a link. Select the link and the properties for the new group are displayed.Create a groupYou can create a group with the Web Portal Manager or pdadmin utility.

Creating a group with Web Portal Manager

You can create a group in the domain with Web Portal Manager.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click Group → Create Group.

Type a Group Name for the group (for example, sales).

Optional: Type a Description for the group (for example, Sales).

Type a Registry GID. The registry GID specifies the location in the user registry where the new group is created. For example: cn=Sales,o=ibm,c=us,dc=mkt. Lotus® Notes® users require the full path name for the group that is being created. For example: Sales/IBM/US.

Optional: Type the path in the Object Container field to the Security Access Manager object space where the group is to be created.

Click Create.

Results

The new group is displayed as a link. Select the link and the properties for the new group are displayed.

Parent topic: Create a group

Creating a group with pdadminYou can create a group in the domain with the pdadmin utility.groupscreatingwith pdadmincommandsgroupcreatinggroupcommandscreating groupLog in to the domain as a domain administrator.Use the group create command to create a group and optionally place this group in a group container object. If the container object does not currently exist, it is automatically created.For example, to create the group named sales, enter the following command: pdadmin sec_master> group create sales "cn=sales,o=IBM,c=us,dc=mkt" SalesFor more information, see the IBM Security Access Manager for Web: Command Reference.Create a groupYou can create a group with the Web Portal Manager or pdadmin utility.

Creating a group with pdadmin

You can create a group in the domain with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the group create command to create a group and optionally place this group in a group container object. If the container object does not currently exist, it is automatically created.

Results

For example, to create the group named sales, enter the following command:

pdadmin sec_master> group create sales "cn=sales,o=IBM,c=us,dc=mkt" Sales

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Create a group

List groupsList groupsList groupsYou can search for group names with the Web Portal Manager or pdadmin utility.groupssearchingManage groupsYou can do the following group tasks:Listing groups with Web Portal ManagerYou can search for and list up to a maximum of 100 groups with Web Portal Manager.Listing groups with pdadminYou can search for a list of groups with the pdadmin utility.

List groups

You can search for group names with the Web Portal Manager or pdadmin utility.

Listing groups with Web Portal Manager
You can search for and list up to a maximum of 100 groups with Web Portal Manager.

Listing groups with pdadmin
You can search for a list of groups with the pdadmin utility.

Parent topic: Manage groups

Listing groups with Web Portal ManagerYou can search for and list up to a maximum of 100 groups with Web Portal Manager.groupslistingwith Web Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click Search Groups.At the Group Search page, use the special character (*) to filter group names.Use the default value of 100 or type a Maximum Results number to limit the number of group names that you want to view.Click Search to display a table of group names. Each group name is displayed as a link.From the Group Search page, you can do these tasks: create a group, delete one or more existing groups, and click the link to view group properties.Use the default value of 15 group names per page or click Options to enter the number of group names you want to view per page. Toggle back by clicking Hide Options.Use the default value of None, meaning that no text is used for filtering. Alternatively, click Filters to find group names that contain, start with, or end with the text that you specify. Toggle back by clicking Hide Filters.List groupsYou can search for group names with the Web Portal Manager or pdadmin utility.

Listing groups with Web Portal Manager

You can search for and list up to a maximum of 100 groups with Web Portal Manager.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click Search Groups.

At the Group Search page, use the special character (*) to filter group names.

Use the default value of 100 or type a Maximum Results number to limit the number of group names that you want to view.

Click Search to display a table of group names. Each group name is displayed as a link.

From the Group Search page, you can do these tasks: create a group, delete one or more existing groups, and click the link to view group properties.

Use the default value of 15 group names per page or click Options to enter the number of group names you want to view per page. Toggle back by clicking Hide Options.

Use the default value of None, meaning that no text is used for filtering. Alternatively, click Filters to find group names that contain, start with, or end with the text that you specify. Toggle back by clicking Hide Filters.

Parent topic: List groups

Listing groups with pdadminYou can search for a list of groups with the pdadmin utility.groupslistingwith pdadmincommandsgroup listinggroupscommandslistingLog in to the domain as a domain administrator.Use the group list command to list groups.For example, to search for and list up to a maximum of 100 groups, enter the following command:pdadmin sec_master> group list * 100For more information, see the IBM Security Access Manager for Web: Command Reference.List groupsYou can search for group names with the Web Portal Manager or pdadmin utility.

Listing groups with pdadmin

You can search for a list of groups with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the group list command to list groups.

Example

For example, to search for and list up to a maximum of 100 groups, enter the following command:

pdadmin sec_master> group list * 100

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: List groups

Import groupsImport groupsImport groupsYou can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the Web Portal Manager or pdadmin utility.dynamicgroupsupportgroupdynamicgroupimportingcommandspdadmin group importgroupcommandsimportingWhen a group is imported, the domain administrator assigns a group name. The group name must be unique within the domain because it is used by Security Access Manager to identify this group.When AD LDS is used as the user registry, you can import only existing groups defined within the same AD LDS partition in which Security Access Manager was configured.If you import a dynamic group, ensure that the policy server is enabled for dynamic group support. For blade systems to benefit from dynamic group support, also enable this stanza entry on each blade system. For details about enabling the policy server for dynamic groups, see Enabling dynamic group supportYou can enable dynamic group support on the policy server and all servers where dynamic groups are supported. Use the pdadmin utility. The command that you run depends on the type of user registry..Manage groupsYou can do the following group tasks:Importing groups with Web Portal ManagerTo import an existing group from a user registry into the domain and make that group a Security Access Manager group, complete the following steps:Importing groups with pdadminYou can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the pdadmin utility.

Import groups

You can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the Web Portal Manager or pdadmin utility.

When a group is imported, the domain administrator assigns a group name. The group name must be unique within the domain because it is used by Security Access Manager to identify this group.

Note: When AD LDS is used as the user registry, you can import only existing groups defined within the same AD LDS partition in which Security Access Manager was configured.

Attention: If you import a dynamic group, ensure that the policy server is enabled for dynamic group support. For blade systems to benefit from dynamic group support, also enable this stanza entry on each blade system. For details about enabling the policy server for dynamic groups, see Enabling dynamic group support.

Importing groups with Web Portal Manager
To import an existing group from a user registry into the domain and make that group a Security Access Manager group, complete the following steps:

Importing groups with pdadmin
You can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the pdadmin utility.

Parent topic: Manage groups

Importing groups with Web Portal ManagerTo import an existing group from a user registry into the domain and make that group a Security Access Manager group, complete the following steps:groupsimportingwith Web Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click GroupImport Group.Type a Group Name for the group. For example, type sales.Type a Registry GID. The registry GID specifies the location in the user registry of the group to be imported. For example, type cn=sales,o=ibm,c=us,dc=mkt. Lotus Notes users require the full path name for the group that is being imported. For example: sales/IBM/US.Optional: Type the path in the Object Container field to the Security Access Manager object space where the group is to be imported.Click Import.The new group is displayed as a link. Select the link to display the properties for the new group.Import groupsYou can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the Web Portal Manager or pdadmin utility.

Importing groups with Web Portal Manager

To import an existing group from a user registry into the domain and make that group a Security Access Manager group, complete the following steps:

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click Group > Import Group.

Type a Group Name for the group. For example, type sales.

Type a Registry GID. The registry GID specifies the location in the user registry of the group to be imported. For example, type cn=sales,o=ibm,c=us,dc=mkt. Lotus® Notes® users require the full path name for the group that is being imported. For example: sales/IBM/US.

Optional: Type the path in the Object Container field to the Security Access Manager object space where the group is to be imported.

Click Import.

Results

The new group is displayed as a link. Select the link to display the properties for the new group.

Parent topic: Import groups

Importing groups with pdadminYou can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the pdadmin utility.groupsimportingwith pdadmincommandsgroup importinggroupscommandsimporting using pdadminLog in to the domain as a domain administrator.Use the group import command to import an existing group.Place this group in a group container object.If the container object does not currently exist, it is automatically created.For example, to import the existing group named "cn=sales,o=IBM,c=us,dc=mkt" from the user registry, enter the following command: pdadmin sec_master> group import sales "cn=sales,o=IBM,c=us,dc=mkt"The group information that is imported to the domain can be imported again to another domain, if necessary.See the IBM Security Access Manager for Web: Command Reference.Import groupsYou can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the Web Portal Manager or pdadmin utility.

Importing groups with pdadmin

You can import an existing group from a user registry into the domain and make that group a Security Access Manager group with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the group import command to import an existing group.

Optional: Place this group in a group container object. If the container object does not currently exist, it is automatically created.

Example

For example, to import the existing group named "cn=sales,o=IBM,c=us,dc=mkt" from the user registry, enter the following command:

pdadmin sec_master> group import sales "cn=sales,o=IBM,c=us,dc=mkt"

Note: The group information that is imported to the domain can be imported again to another domain, if necessary.

See the IBM Security Access Manager for Web: Command Reference.

Parent topic: Import groups

Delete a groupDelete a groupDelete a groupYou can delete a group with the Web Portal Manager or pdadmin utility.When you delete a group, this group is removed from all objects with which it is associated. If this group is the only ACL entry that is associated with an ACL policy, no other user or group can manage this ACL policy. Before deleting a group in this case, you must validate that there are other users or groups that can manage this ACL policy.Manage groupsYou can do the following group tasks:Deleting a group with Web Portal ManagerYou can delete a group from the domain with the Web Portal Manager.Deleting a group with pdadminYou can delete a group from the domain with the pdadmin utility.

Delete a group

You can delete a group with the Web Portal Manager or pdadmin utility.

When you delete a group, this group is removed from all objects with which it is associated. If this group is the only ACL entry that is associated with an ACL policy, no other user or group can manage this ACL policy. Before deleting a group in this case, you must validate that there are other users or groups that can manage this ACL policy.

Deleting a group with Web Portal Manager
You can delete a group from the domain with the Web Portal Manager.

Deleting a group with pdadmin
You can delete a group from the domain with the pdadmin utility.

Parent topic: Manage groups

Deleting a group with Web Portal ManagerYou can delete a group from the domain with the Web Portal Manager.groupsdeletingwith Web Portal ManagerUse Web Portal Manager to log in to the domain as a domain administrator.Click GroupSearch Groups.Search for one or more group names to delete and click Search.Select check boxes next to the group names to delete, and click Delete.From the Delete Selected Groups page, click Delete Groups to confirm the deletion or click Delete Groups and Registry Entries to also remove the registry entries associated with the selected groups.Delete a groupYou can delete a group with the Web Portal Manager or pdadmin utility.

Deleting a group with Web Portal Manager

You can delete a group from the domain with the Web Portal Manager.

Procedure

Use Web Portal Manager to log in to the domain as a domain administrator.

Click Group > Search Groups.

Search for one or more group names to delete and click Search.

Select check boxes next to the group names to delete, and click Delete.

From the Delete Selected Groups page, click Delete Groups to confirm the deletion or click Delete Groups and Registry Entries to also remove the registry entries associated with the selected groups.

Parent topic: Delete a group

Deleting a group with pdadminYou can delete a group from the domain with the pdadmin utility.groupsdeletingwith pdadmincommandsgroup deletegroupcommandsdeletingLog in to the domain as a domain administrator.Use the group delete command to delete a group.For example, to delete the group named sales and the associated information from the user registry, enter the following command: pdadmin sec_master> group delete –registry salesFor more information, see the IBM Security Access Manager for Web: Command Reference.Delete a groupYou can delete a group with the Web Portal Manager or pdadmin utility.

Deleting a group with pdadmin

You can delete a group from the domain with the pdadmin utility.

Procedure

Log in to the domain as a domain administrator.

Use the group delete command to delete a group.

Example

For example, to delete the group named sales and the associated information from the user registry, enter the following command:

pdadmin sec_master> group delete –registry sales

For more information, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Delete a group

Enabling dynamic group supportYou can enable dynamic group support on the policy server and all servers where dynamic groups are supported. Use the pdadmin utility. The command that you run depends on the type of user registry.commandsgroup support, enablingdynamicgroupenablinggroupsdynamicManage users and groupsAn initial domain administrator is created when a new domain is created.LDAP registryFor LDAP registry users, modify the dynamic-groups-enabled entry in the [ldap] stanza of the ldap.conf file.

Enabling dynamic group support

You can enable dynamic group support on the policy server and all servers where dynamic groups are supported. Use the pdadmin utility. The command that you run depends on the type of user registry.

LDAP registry
For LDAP registry users, modify the dynamic-groups-enabled entry in the [ldap] stanza of the ldap.conf file.

Parent topic: Manage users and groups

LDAP registryFor LDAP registry users, modify the dynamic-groups-enabled entry in the [ldap] stanza of the ldap.conf file.dynamicgroupLDAP registryLDAPregistry, enabling dynamic groupsTo do so, edit the configuration files with the local management interface as follows: dynamic-groups-enabled = yesFor configuration changes to take effect, you must restart the updated server. Dynamic groups are not supported for the AD LDS registry.Managing runtime configuration filesTo manage configuration files with the local management interface, use the Runtime Component management page.Enabling dynamic group supportYou can enable dynamic group support on the policy server and all servers where dynamic groups are supported. Use the pdadmin utility. The command that you run depends on the type of user registry.

LDAP registry

For LDAP registry users, modify the dynamic-groups-enabled entry in the [ldap] stanza of the ldap.conf file.

To do so, edit the configuration files with the local management interface as follows:

dynamic-groups-enabled = yes

For configuration changes to take effect, you must restart the updated server.

Note: Dynamic groups are not supported for the AD LDS registry.

Parent topic: Enabling dynamic group support

Related tasks:

Managing runtime configuration files

Certificate and password managementCertificate and password managementTo securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.certificateauthoritydefinitioncertificateauthority(CA)certificatemanagement taskspasswordmanagement tasksstash filesdefinitionkey filesdefinitionkeystores, definitionThis information describes certificate and password management from the perspective of the administration C API run time. However, Security Access Manager also provides a Java run time to complete the same tasks. For more information about the administration Java runtime and classes, see the Administration Java Classes Developer Reference and the Authorization Java Classes Developer Reference.Security Access Manager can use Secure Sockets Layer (SSL) for encryption, system authentication, and application-level authentication. When installed and configured, SSL uses certificates for operation that help to ensure a secure environment. Security Access Manager can also use Transport Layer Security (TLS) version 1 and SSL. TSL can be enabled to work when compliance modes are enabled and when compliance modes are disabled.In the secure environment, the policy server acts as the certificate authority (CA) and is responsible for creating and renewing certificates. The IBM Security Access Manager runtime package (pdrte) relies on only SSL server-side authentication and does not require a client-side certificate. All of the Security Access Manager servers, including the policy server, authorization server, policy proxy server, and resource manager server, rely on client-side certificates to operate.The Security Access Manager servers use certificates to authenticate themselves. For example, when the authorization server wants to communicate with the policy server, it presents its client-side certificate. In this example, the policy server is considered the server, and the authorization server is the client. The policy server verifies that the certificate is valid and is signed by a trusted signer. In this case, the trusted signer is the policy server itself, using the Security Access Manager certificate authority (PDCA) certificate. The authorization server does the same for the certificate presented by the policy server. During the Security Access Manager application-level authentication, the policy server:Determines whether the authorization server certificate is good.Tries to map the certificate to a Security Access Manager user. If the authentication succeeds, then the servers can communicate.The certificates used by Security Access Manager are in key files. Key files have a .kdb extension (or .ks extension for Java keystores). Key files must be secured and protected by the strictest operating system controls available, because they contain the private keys for the certificates. For example, the key file for the policy server is ivmgrd.kdb and, by default, it can be read and written to by only the ivmgr user.The certificate files in a directory need to be accessible to the user ivmgr (or all users). Ensure that the ivmgrd.kdb file and the directory or folder that contains the ivmgrd.kdb file is accessible by the user ivmgr or all users. Ensure that these users have the appropriate permissions for this file.Furthermore, to facilitate unattended server operation, there are files that contain an obfuscated (not encrypted) version of the password to the key files. These versions are stash files, which are denoted by a .sth file extension. Java key files that are generated by Security Access Manager do not have corresponding stash files. These stash files must be secured by using the local standard operating system measures. For the policy server, the stash file is ivmgrd.sth and its permissions are the same as the ivmgrd.kdb key file.For security reasons, both the certificates and the key file passwords can be set to expire after a configurable amount of time. The default lifetime for a certificate is four years. The default lifetime for a key file password is 183 days. The fixed lifetime for the PDCA certificate is 20 years. By default, the Security Access Manager servers refresh the certificates and passwords automatically while they are running. The refresh process reissues a new certificate with a new lifetime and generates a new password with the configured lifetime.The Security Access Manager calculates the life span of the certificate when you open the security context. When opening the security context, the Security Access Manager verifies the need to refresh the context. If there is a need to refresh the certificate, then Security Access Manager creates an SSL context with the new certificate and processes the request.If the servers are not running in a specified time frame, then their certificates or passwords can expire. In this case, a manual refresh is necessary. Also, if a certificate or a password or the entire key file is damaged, then you must manually refresh it. Refreshing the expired or damaged certificate, password, or key file is necessary to maintain the security of the Security Access Manager domain. For information about manually refreshing the certificates, passwords, and key files, see Key file and stash file renewal informationServers have associated key files and stash files..Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Initial configurationYou create certificates used by the Security Access Manager servers during the initial configuration of the servers. The Security Access Manager servers use these certificates to securely communicate with other servers.Key file and stash file renewal informationServers have associated key files and stash files.Regenerating certificatesIf a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.Server certificate revocationIf a certificate on a resource manager is compromised, you can revoke the certificate and then replace it with a new certificate.Additional key file and stash file considerationsThere are additional considerations for key file and stash file renewal.

Certificate and password management

To securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.

This information describes certificate and password management from the perspective of the administration C API run time. However, Security Access Manager also provides a Java™ run time to complete the same tasks. For more information about the administration Java runtime and classes, see the Administration Java Classes Developer Reference and the Authorization Java Classes Developer Reference.

Security Access Manager can use Secure Sockets Layer (SSL) for encryption, system authentication, and application-level authentication. When installed and configured, SSL uses certificates for operation that help to ensure a secure environment. Security Access Manager can also use Transport Layer Security (TLS) version 1 and SSL. TSL can be enabled to work when compliance modes are enabled and when compliance modes are disabled.

In the secure environment, the policy server acts as the certificate authority (CA) and is responsible for creating and renewing certificates. The IBM Security Access Manager runtime package (pdrte) relies on only SSL server-side authentication and does not require a client-side certificate. All of the Security Access Manager servers, including the policy server, authorization server, policy proxy server, and resource manager server, rely on client-side certificates to operate.

The Security Access Manager servers use certificates to authenticate themselves. For example, when the authorization server wants to communicate with the policy server, it presents its client-side certificate. In this example, the policy server is considered the server, and the authorization server is the client. The policy server verifies that the certificate is valid and is signed by a trusted signer. In this case, the trusted signer is the policy server itself, using the Security Access Manager certificate authority (PDCA) certificate. The authorization server does the same for the certificate presented by the policy server. During the Security Access Manager application-level authentication, the policy server:

Determines whether the authorization server certificate is good.

Tries to map the certificate to a Security Access Manager user.

If the authentication succeeds, then the servers can communicate.

The certificates used by Security Access Manager are in key files. Key files have a .kdb extension (or .ks extension for Java keystores). Key files must be secured and protected by the strictest operating system controls available, because they contain the private keys for the certificates. For example, the key file for the policy server is ivmgrd.kdb and, by default, it can be read and written to by only the ivmgr user.

The certificate files in a directory need to be accessible to the user ivmgr (or all users). Ensure that the ivmgrd.kdb file and the directory or folder that contains the ivmgrd.kdb file is accessible by the user ivmgr or all users. Ensure that these users have the appropriate permissions for this file.

Furthermore, to facilitate unattended server operation, there are files that contain an obfuscated (not encrypted) version of the password to the key files. These versions are stash files, which are denoted by a .sth file extension. Java key files that are generated by Security Access Manager do not have corresponding stash files. These stash files must be secured by using the local standard operating system measures. For the policy server, the stash file is ivmgrd.sth and its permissions are the same as the ivmgrd.kdb key file.

For security reasons, both the certificates and the key file passwords can be set to expire after a configurable amount of time. The default lifetime for a certificate is four years. The default lifetime for a key file password is 183 days. The fixed lifetime for the PDCA certificate is 20 years. By default, the Security Access Manager servers refresh the certificates and passwords automatically while they are running. The refresh process reissues a new certificate with a new lifetime and generates a new password with the configured lifetime.

The Security Access Manager calculates the life span of the certificate when you open the security context. When opening the security context, the Security Access Manager verifies the need to refresh the context. If there is a need to refresh the certificate, then Security Access Manager creates an SSL context with the new certificate and processes the request.

If the servers are not running in a specified time frame, then their certificates or passwords can expire. In this case, a manual refresh is necessary. Also, if a certificate or a password or the entire key file is damaged, then you must manually refresh it. Refreshing the expired or damaged certificate, password, or key file is necessary to maintain the security of the Security Access Manager domain. For information about manually refreshing the certificates, passwords, and key files, see Key file and stash file renewal information.

Initial configuration
You create certificates used by the Security Access Manager servers during the initial configuration of the servers. The Security Access Manager servers use these certificates to securely communicate with other servers.

Key file and stash file renewal information
Servers have associated key files and stash files.

Regenerating certificates
If a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.

Server certificate revocation
If a certificate on a resource manager is compromised, you can revoke the certificate and then replace it with a new certificate.

Additional key file and stash file considerations
There are additional considerations for key file and stash file renewal.

Parent topic: Access Manager Platform and Supporting Components administration

Initial configurationInitial configurationYou create certificates used by the Security Access Manager servers during the initial configuration of the servers. The Security Access Manager servers use these certificates to securely communicate with other servers.certificatesinitial configurationPDCAcertificateIn a new Security Access Manager installation, the policy server is the first server that is configured. During the configuration, two certificates are created: the PDCA certificate and a personal certificate that is used by the policy server and signed by the PDCA certificate. Both of these certificates are in the ivmgrd.kdb key file. During the policy server configuration, the IBM Security Access Manager runtime key file pd.kdb is created. The PDCA certificate is inserted into it as a trusted certificate.When new systems are added to the Security Access Manager domain, the IBM Security Access Manager runtime package is configured first. As part of this configuration, the system pd.kdb and pd.sth files are created. The PDCA certificate is included in the key files as a trusted certificate.When new resource managers, such as WebSEAL, are configured, the svrsslcfg utility or an equivalent application programming interface (API) is run. This utility creates a key file (such as pdacld.kdb) and places a personal certificate for the server in it. The utility also inserts the PDCA certificate as a trusted certificate in the key file. These two certificates are obtained from the policy server. The certificates are transported to the client system over SSL with the IBM Security Access Manager runtime key file.For more information about the configuration files and certificate-related stanza entries, such as the configured key file and the configured stash files, see Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers..Certificate and password managementTo securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.

Initial configuration

You create certificates used by the Security Access Manager servers during the initial configuration of the servers. The Security Access Manager servers use these certificates to securely communicate with other servers.

In a new Security Access Manager installation, the policy server is the first server that is configured. During the configuration, two certificates are created: the PDCA certificate and a personal certificate that is used by the policy server and signed by the PDCA certificate. Both of these certificates are in the ivmgrd.kdb key file. During the policy server configuration, the IBM Security Access Manager runtime key file pd.kdb is created. The PDCA certificate is inserted into it as a trusted certificate.

When new systems are added to the Security Access Manager domain, the IBM Security Access Manager runtime package is configured first. As part of this configuration, the system pd.kdb and pd.sth files are created. The PDCA certificate is included in the key files as a trusted certificate.

When new resource managers, such as WebSEAL, are configured, the svrsslcfg utility or an equivalent application programming interface (API) is run. This utility creates a key file (such as pdacld.kdb) and places a personal certificate for the server in it. The utility also inserts the PDCA certificate as a trusted certificate in the key file. These two certificates are obtained from the policy server. The certificates are transported to the client system over SSL with the IBM Security Access Manager runtime key file.

For more information about the configuration files and certificate-related stanza entries, such as the configured key file and the configured stash files, see Configuration file reference.

Parent topic: Certificate and password management

Key file and stash file renewal informationKey file and stash file renewal informationServers have associated key files and stash files.automatic certificate and password refreshcertificate and passwords, refreshcertificatesautomatic refreshpasswordautomatic refreshauthorizationserverkey and stash filesrenewalskey filesrenewalsstash fileskey filesrenewingstash filesrenewingfilesrenewingfilesrenewingutilitiesmanual certificate updatescertificatesupdate utilitiesThe following table describes the server key and stash files, including how they are created and refreshed. Server key and stash filesServerKey and stash filesHow createdHow automatically updatedHow manually updatedstash filespd.sthkey filespd.kdbIBM Security Access Manager runtime packagepd.sth stash filepd.kdb key fileIBM Security Access Manager runtime packagepd.kdb and pd.sth (does not contain a client-side certificate)During runtime configurationRunning the pdadmin1 utilityRunning the bassslcfg utility with the –chgpwd optionstash filesivmgrd.sthkey filesivmgrd.kdbpolicy serverkey and stash filesivmgrd.sth stash fileivmgrd.kdb key filePolicy serverivmgrd.kdb and ivmgrd.sthDuring server configurationRunning the pdmgrd1,2 commandRunning the mgrsslcfg utility with the -chgpwd3 and -chgcert3 optionsstash filespdmgrproxyd.sthkey filespdmgrproxyd.kdbpolicy proxy serverkey and stash filespdmgrproxyd.sth stash filepdmgrproxyd.kdb key fileProxy serverpdmgrproxyd.kdb and pdmgrproxyd.sth During server configuration Running the pdmgrproxyd1 commandRunning the svrsslcfg utility with the –chgpwd9 and the –chgcert5 optionsstash filesivacld.sthkey filesivacld.kdbivacld.sth stash fileivacld.kdb key fileAuthorization server[instance-]ivacld.kdb [instance-]ivacld.sth[instance-] is the instance of an authorization server on a computer. Having more than one authorization server on a computer generates multiple sets of .kdb and .sth filenames.During server configurationRunning the pdacld1 commandRunning the svrsslcfg utility with the -chgpwd4 and -chgcert5 optionsResource managerThe key files and stash file names are resource manager-dependent, and the file name is configurable.6Running the svrsslcfg utility with the –config optionRunning an instance of the resource manager1Running the svrsslcfg utility with the –chgpwd7 and –chgcert8 optionsTable notes: 1You can turn off automatic certificate and password refresh by setting the ssl-auto-refresh stanza entry to no in the [ssl] stanza in the respective configuration file.2Because the policy server also acts as the certificate authority (CA) for the secure domain, it must be recycled after a refresh. It continues to operate normally until it is recycled, but it cannot issue or renew certificates for other servers until it is recycled. The policy server log file contains a message that states when to restart the server.3Before running this command, stop the policy server.4Before running this command, stop the authorization server.5Before running this command, the policy server must be running. Stop the authorization server.6Java resource managers have an equivalent to key files, known as Java keystores, where the application personal certificate and the PDCA certificate are stored. Java resource managers do not have a stash file equivalent. The names of keystores are created by running the Java SvrSslCfg class with the –action config option.7Before running this command, the resource manager must be stopped.8Before running this command, the policy server must be running, and the resource manager must be stopped.9Before running this command, the proxy server must be stopped.Certificate and password managementTo securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.

Key file and stash file renewal information

Servers have associated key files and stash files.

The following table describes the server key and stash files, including how they are created and refreshed.

Table 174. Server key and stash files

Server
Key and stash files
How created
How automatically updated
How manually updated

IBM Security Access Manager runtime package
pd.kdb and pd.sth (does not contain a client-side certificate)
During runtime configuration
Running the pdadmin¹ utility
Running the bassslcfg utility with the –chgpwd option

Policy server
ivmgrd.kdb and ivmgrd.sth
During server configuration
Running the pdmgrd1,2 command
Running the mgrsslcfg utility with the -chgpwd³ and -chgcert³ options

Proxy server
pdmgrproxyd.kdb and pdmgrproxyd.sth
During server configuration
Running the pdmgrproxyd¹ command

Running the svrsslcfg utility with the –chgpwd⁹ and the –chgcert⁵ options

Authorization server
[instance-]ivacld.kdb [instance-]ivacld.sth

Note: [instance-] is the instance of an authorization server on a computer. Having more than one authorization server on a computer generates multiple sets of .kdb and .sth filenames.

During server configuration
Running the pdacld¹ command
Running the svrsslcfg utility with the -chgpwd⁴ and -chgcert⁵ options

Resource manager
The key files and stash file names are resource manager-dependent, and the file name is configurable.⁶
Running the svrsslcfg utility with the –config option
Running an instance of the resource manager¹
Running the svrsslcfg utility with the –chgpwd⁷ and –chgcert⁸ options

Table notes:

¹

You can turn off automatic certificate and password refresh by setting the ssl-auto-refresh stanza entry to no in the [ssl] stanza in the respective configuration file.

²

Because the policy server also acts as the certificate authority (CA) for the secure domain, it must be recycled after a refresh. It continues to operate normally until it is recycled, but it cannot issue or renew certificates for other servers until it is recycled. The policy server log file contains a message that states when to restart the server.

³

Before running this command, stop the policy server.

⁴

Before running this command, stop the authorization server.

⁵

Before running this command, the policy server must be running. Stop the authorization server.

⁶

Java™ resource managers have an equivalent to key files, known as Java keystores, where the application personal certificate and the PDCA certificate are stored. Java resource managers do not have a stash file equivalent. The names of keystores are created by running the Java SvrSslCfg class with the –action config option.

⁷

Before running this command, the resource manager must be stopped.

⁸

Before running this command, the policy server must be running, and the resource manager must be stopped.

⁹

Before running this command, the proxy server must be stopped.

Parent topic: Certificate and password management

Regenerating certificatesRegenerating certificatesIf a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.certificateauthoritydetermining trusttrust determination, certificates Each key file contains a list of trusted certificate authorities (CAs). Each key file except ivmgrd.kdb has the Security Access Manager certificate authority (PDCA) certificate as a trusted certificate authority. This certificate authority signs all the other Security Access Manager certificates. This certificate authority is created during policy server configuration and is placed in the ivmgrd.kdb file.It is important to protect the ivmgrd.kdb file to keep the private key in the PDCA certificate from being compromised. If the private key is compromised, the private key, each key file, and each certificate in the domain must be regenerated.From the Java perspective, the IBM Security Access Manager Runtime for Java also stores the PDCA certificate. If the PDCA certificate is compromised and must be regenerated, you must reconfigure all servers that use the IBM Security Access Manager Runtime for Java. You must also regenerate the key file for all resource managers that were previously configured with the SvrSslCfg class. Reconfigure these resource managers.Stop the policy server. Regenerate the PDCA certificate and policy server certificate by generating a new ivmgrd.kdb file with the mgrsslcfg –config utility. Regenerate the IBM Security Access Manager runtime certificates on the policy server by running the bassslcfg –config utility. After obtaining the certificate authority certificate, you can choose to automatically download the certificate authority certificate or manually copy the file.If auto-download is set to on (enabled) and the policy server is running, the certificate authority certificate is automatically obtained. By default, auto-download is enabled.If auto-download is set to off (disabled), the base-64 DER encoded version of the PDCA certificate must be copied to the system. This file is stored as pdcacert.b64 on the policy server.On each runtime system, run the bassslcfg –config utility.On each authorization server in the domain, regenerate its key files by running the svrsslcfg –config utility. The policy server must be running. This command updates both the server certificate for the authorization server and its trusted certificate (the new PDCA certificate).On each resource manager in the domain, regenerate its key files by running the svrsslcfg –config utility. The policy server must be running. This command updates both the server certificate for the authorization server and its trusted certificate, the new PDCA certificate.On each Security Access Manager Java runtime system, run the pdjrtecfg -unconfig utility, the pdjrtecfg -config utility, and the java com.tivoli.pd.jcfg.SvrSslCfg -action replcert command.Certificate and password managementTo securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.Reconfiguring the PDCA on the policy serverIf the certificate is compromised or expires, you must reconfigure the PDCA on the policy server.Reconfiguring the certifications of Security Access Manager Java applicationsTo use the new policy server certificate authority, you must reconfigure the PDCA in the configured Java run time. You must also reconfigure the certificates of any Security Access Manager Java application that uses the IBM Security Access Manager Runtime for Java. First, update the IBM Security Access Manager Runtime for Java configuration. Then, update the certificate of each Security Access Manager Java application that uses the run time.Reconfiguring the PDCA on the runtime systemsAfter you reconfigure the policy server and transfer the newly generated PDCA certificate to each runtime system, you must reconfigure the PDCA on the runtime systems.Transferring the PDCA certificate to other systemsAfter regenerating the PDCA certificate, you can transfer the PDCA certificate to each system in the domain. In this case, your business security policy requires trusted transport of the PDCA signer certificate to the target machine. The network between the policy server and the target system contains untrusted segments.

Regenerating certificates

If a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.

About this task

Each key file contains a list of trusted certificate authorities (CAs). Each key file except ivmgrd.kdb has the Security Access Manager certificate authority (PDCA) certificate as a trusted certificate authority. This certificate authority signs all the other Security Access Manager certificates. This certificate authority is created during policy server configuration and is placed in the ivmgrd.kdb file.

It is important to protect the ivmgrd.kdb file to keep the private key in the PDCA certificate from being compromised. If the private key is compromised, the private key, each key file, and each certificate in the domain must be regenerated.

From the Java™ perspective, the IBM Security Access Manager Runtime for Java also stores the PDCA certificate. If the PDCA certificate is compromised and must be regenerated, you must reconfigure all servers that use the IBM Security Access Manager Runtime for Java.

You must also regenerate the key file for all resource managers that were previously configured with the SvrSslCfg class. Reconfigure these resource managers.

Procedure

Stop the policy server.

Regenerate the PDCA certificate and policy server certificate by generating a new ivmgrd.kdb file with the mgrsslcfg –config utility.

Regenerate the IBM Security Access Manager runtime certificates on the policy server by running the bassslcfg –config utility.

After obtaining the certificate authority certificate, you can choose to automatically download the certificate authority certificate or manually copy the file.

If auto-download is set to on (enabled) and the policy server is running, the certificate authority certificate is automatically obtained. By default, auto-download is enabled.

If auto-download is set to off (disabled), the base-64 DER encoded version of the PDCA certificate must be copied to the system. This file is stored as pdcacert.b64 on the policy server.

On each runtime system, run the bassslcfg –config utility.

On each authorization server in the domain, regenerate its key files by running the svrsslcfg –config utility. The policy server must be running. This command updates both the server certificate for the authorization server and its trusted certificate (the new PDCA certificate).

On each resource manager in the domain, regenerate its key files by running the svrsslcfg –config utility. The policy server must be running. This command updates both the server certificate for the authorization server and its trusted certificate, the new PDCA certificate.

On each Security Access Manager Java runtime system, run the pdjrtecfg -unconfig utility, the pdjrtecfg -config utility, and the java com.tivoli.pd.jcfg.SvrSslCfg -action replcert command.

Reconfiguring the PDCA on the policy server
If the certificate is compromised or expires, you must reconfigure the PDCA on the policy server.

Reconfiguring the certifications of Security Access Manager Java applications
To use the new policy server certificate authority, you must reconfigure the PDCA in the configured Java run time. You must also reconfigure the certificates of any Security Access Manager Java application that uses the IBM Security Access Manager Runtime for Java. First, update the IBM Security Access Manager Runtime for Java configuration. Then, update the certificate of each Security Access Manager Java application that uses the run time.

Reconfiguring the PDCA on the runtime systems
After you reconfigure the policy server and transfer the newly generated PDCA certificate to each runtime system, you must reconfigure the PDCA on the runtime systems.

Transferring the PDCA certificate to other systems
After regenerating the PDCA certificate, you can transfer the PDCA certificate to each system in the domain. In this case, your business security policy requires trusted transport of the PDCA signer certificate to the target machine. The network between the policy server and the target system contains untrusted segments.

Parent topic: Certificate and password management

Reconfiguring the PDCA on the policy serverReconfiguring the PDCA on the policy serverIf the certificate is compromised or expires, you must reconfigure the PDCA on the policy server.policy serverPDCA, reconfiguringPDCApolicy server, reconfiguringStop all Security Access Manager services that are running on the system by entering the following command:AIX, Linux, and Solaris operating systems:pd_start stopWindows operating systems:drive:\net stop servernameStop each Security Access Manager service. For example, to stop the policy server, type:C:\net stop IVMgrChange to the directory where the key files are located. Assuming the default directory on a AIX, Linux, or Solaris operating system, enter the following command:cd /var/PolicyDirector/keytabRename the ivmgrd.kdb key file, ivmgrd.sth stash file, and pdcacert.b64 PDCA file by entering the following commands: mv ivmgrd.kdb ivmgrd.kdb.old mv ivmgrd.sth ivmgrd.sth.old mv pdcacert.b64 pdcacert.b64.oldConfigure the policy manager server to create a new key file and stash file.For example, enter the command but replace the value for the compliance option./opt/PolicyDirector/sbin/mgrsslcfg -config -D yes -C complianceChange the ownership of the newly created key file, stash file, and certificate to ivmgr:ivmgr by entering the following commands:chown ivmgr:ivmgr /var/PolicyDirector/keytab/ivmgrd.kdb chown ivmgr:ivmgr /var/PolicyDirector/keytab/ivmgrd.sth chown ivmgr:ivmgr /var/PolicyDirector/keytab/pdcacert.b64Configure the IBM Security Access Manager runtime with the bassslcfg –config utility.For example, enter the command but replace the values for the –c, –h, and –C options. bassslcfg -config -C {compliance} -h myhostname -c /var/PolicyDirector/keytab/pdcacert.b64Change the ownership of the new key file and stash file to ivmgr:ivmgr by entering the following commands:chown ivmgr:ivmgr /var/PolicyDirector/keytab/pd.kdb chown ivmgr:ivmgr /var/PolicyDirector/keytab/pd.sthStart the Security Access Manager services on the computer by entering the following command:/opt/PolicyDirector/bin/pdmgrdUpdate the certificates of the authorization, proxy, and resource servers and other C API applications that use svrsslcfg -config by entering the following command:svrsslcfg -chgcertThis example shows the command (on one line) to update the certificate on the authorization server:svrsslcfg -chgcert -f /opt/PolicyDirector/etc/[instance-]ivacld.conf -P *** -A sec_masterStart the updated Security Access Manager servers by entering the following command:pd_start restartReconfigure the certificates of any other Security Access Manager Java applications on the policy server. See Reconfiguring the certifications of Security Access Manager Java applicationsTo use the new policy server certificate authority, you must reconfigure the PDCA in the configured Java run time. You must also reconfigure the certificates of any Security Access Manager Java application that uses the IBM Security Access Manager Runtime for Java. First, update the IBM Security Access Manager Runtime for Java configuration. Then, update the certificate of each Security Access Manager Java application that uses the run time..After updating the PDCA on the policy server, you must update the certificates on all other systems that run Security Access Manager servers and applications. The management environment must be running.After regenerating the PDCA certificate on the policy server, you might need to copy the PDCA certificate to each runtime computer in the domain. If auto-download is enabled, you do not need to copy the file.Regenerating certificatesIf a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.

Reconfiguring the PDCA on the policy server

If the certificate is compromised or expires, you must reconfigure the PDCA on the policy server.

Procedure

Stop all Security Access Manager services that are running on the system by entering the following command:

AIX®, Linux, and Solaris operating systems:

pd_start stop

Windows operating systems:

drive:\net stop servername

Stop each Security Access Manager service. For example, to stop the policy server, type:

C:\net stop IVMgr

Change to the directory where the key files are located. Assuming the default directory on a AIX, Linux, or Solaris operating system, enter the following command:

cd /var/PolicyDirector/keytab

Rename the ivmgrd.kdb key file, ivmgrd.sth stash file, and pdcacert.b64 PDCA file by entering the following commands:

mv ivmgrd.kdb ivmgrd.kdb.old
mv ivmgrd.sth ivmgrd.sth.old
mv pdcacert.b64 pdcacert.b64.old

Configure the policy manager server to create a new key file and stash file. For example, enter the command but replace the value for the compliance option.

/opt/PolicyDirector/sbin/mgrsslcfg -config -D yes -C compliance

Change the ownership of the newly created key file, stash file, and certificate to ivmgr:ivmgr by entering the following commands:

chown ivmgr:ivmgr /var/PolicyDirector/keytab/ivmgrd.kdb
chown ivmgr:ivmgr /var/PolicyDirector/keytab/ivmgrd.sth
chown ivmgr:ivmgr /var/PolicyDirector/keytab/pdcacert.b64

Configure the IBM Security Access Manager runtime with the bassslcfg –config utility. For example, enter the command but replace the values for the –c, –h, and –C options.

bassslcfg -config -C {compliance} -h myhostname
-c /var/PolicyDirector/keytab/pdcacert.b64

Change the ownership of the new key file and stash file to ivmgr:ivmgr by entering the following commands:

chown ivmgr:ivmgr /var/PolicyDirector/keytab/pd.kdb
chown ivmgr:ivmgr /var/PolicyDirector/keytab/pd.sth

Start the Security Access Manager services on the computer by entering the following command:

/opt/PolicyDirector/bin/pdmgrd

Update the certificates of the authorization, proxy, and resource servers and other C API applications that use svrsslcfg -config by entering the following command:

svrsslcfg -chgcert

This example shows the command (on one line) to update the certificate on the authorization server:

svrsslcfg -chgcert -f /opt/PolicyDirector/etc/[instance-]ivacld.conf
-P *** -A sec_master

Start the updated Security Access Manager servers by entering the following command:

pd_start restart

Reconfigure the certificates of any other Security Access Manager Java™ applications on the policy server. See Reconfiguring the certifications of Security Access Manager Java applications.

What to do next

After updating the PDCA on the policy server, you must update the certificates on all other systems that run Security Access Manager servers and applications.

The management environment must be running.

After regenerating the PDCA certificate on the policy server, you might need to copy the PDCA certificate to each runtime computer in the domain. If auto-download is enabled, you do not need to copy the file.

Parent topic: Regenerating certificates

Reconfiguring the certifications of Security Access Manager Java applicationsReconfiguring the certifications of Security Access Manager Java applicationsTo use the new policy server certificate authority, you must reconfigure the PDCA in the configured Java run time. You must also reconfigure the certificates of any Security Access Manager Java application that uses the IBM Security Access Manager Runtime for Java. First, update the IBM Security Access Manager Runtime for Java configuration. Then, update the certificate of each Security Access Manager Java application that uses the run time.Java runtime applications certificationreconfigurationJava runtime applications certificationupdatingJava runtime applications files backup Back up all the files in [JRE]/PolicyDirector. For WebSphere Application Server version 8.0 and later, the directory is [WAS_HOME]/tivoli/tam/PolicyDirector. This procedure updates the IBM Security Access Manager Runtime for Java files. Then it updates the individual Security Access Manager Java components with the IBM Security Access Manager Runtime for Java.The IBM Security Access Manager Runtime for Java files that must be updated are the PDCA.ks file and the ssl-compliance property in the PD.properties file.There are several ways that you can reconfigure the certification of a Security Access Manager Java application: Unconfigure and then reconfigure the IBM Security Access Manager Runtime for Java.Obtain a PDCA.ks file from another IBM Security Access Manager Runtime for Java that was already updated. Then, copy the file into the target IBM Security Access Manager Runtime for Java. If you configured the Java application with the Security Access Manager, version 7.0, configuration program, you specified a location for the PDCA.ks file. Replace the PDCA.ks file at that location instead of the location in the JRE.To locate the PDCA.ks file, open the properties configuration file of your application for IBM Security Access Manager Runtime for Java. For example, the file might be named pdwpm.properties. In the file, find the pdca-url entry. The entry specifies the PDCA.ks file path.pdca-url=file\:/user_supplied_path/PDCA.ksWrite the PDCA.ks file from an updated IBM Security Access Manager Runtime for Java into the location that the pdca-url entry specifies.Also update the ssl-compliance entry, if it exists. For example:ssl-compliance=noneChange the value to the appropriate compliance level for Java application that you configured with Security Access Manager, version 7.0. For example:ssl-compliance=suite-b-192Update the PDCA.ks and PD.properties files by unconfiguring the Java runtime and then reconfiguring it.This step removes all files in the [JRE]/PolicyDirector directory and then re-creates the files. For WebSphere Application Server version 8.0 and later, the directory is [WAS_HOME]/tivoli/tam/PolicyDirector.If any file under this directory was customized, then you must reapply the customization to the new file.At this step, do not unconfigure the Security Access Manager Java applications that are configured to use the JRE.You might need more information about configuring or unconfiguring Security Access Manager run time for Java. See the pdjrtecfg command utility in the IBM Security Access Manager for Web Command Reference.Update the WebSphere profile if:The Security Access Manager compliance type changed andThe Security Access Manager Java applications run in a WebSphere profile. The FIPS security mode must match the Security Access Manager compliance level.Stop any processes that are using the JRE.For example, stop any WebSphere profiles that are using the JRE.Update the ssl.client.props file of the WebSphere profile to allow WebSphere client applications to communicate with the profile if:You are using a WebSphere Java run time and You changed the FIPS security mode of the run time.oRegenerate the certificates of each SvrSslCfg Security Access Manager Java application. This example illustrates how to reconfigure the Security Access Manager WebSphere Portal Manager certificates: java com.tivoli.pd.jcfg.SvrSslCfg -action replcert -admin_id sec_master -admin_pwd -cfg_file /opt/PolicyDirector/java/export/pdwpm/pdwpm.propertiesStart the JRE and ensure that it operates properly in the updated Java run time.For WebSphere, start the WebSphere profile to start the JRE.Repeat this procedure for any other Security Access Manager Java run times that are on the system.Regenerating certificatesIf a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.

Reconfiguring the certifications of Security Access Manager Java applications

To use the new policy server certificate authority, you must reconfigure the PDCA in the configured Java™ run time. You must also reconfigure the certificates of any Security Access Manager Java application that uses the IBM Security Access Manager Runtime for Java. First, update the IBM Security Access Manager Runtime for Java configuration. Then, update the certificate of each Security Access Manager Java application that uses the run time.

Before you begin

Back up all the files in [JRE]/PolicyDirector. For WebSphere Application Server version 8.0 and later, the directory is [WAS_HOME]/tivoli/tam/PolicyDirector.

About this task

This procedure updates the IBM Security Access Manager Runtime for Java files. Then it updates the individual Security Access Manager Java components with the IBM Security Access Manager Runtime for Java.

The IBM Security Access Manager Runtime for Java files that must be updated are the PDCA.ks file and the ssl-compliance property in the PD.properties file.

There are several ways that you can reconfigure the certification of a Security Access Manager Java application:

Unconfigure and then reconfigure the IBM Security Access Manager Runtime for Java.

Obtain a PDCA.ks file from another IBM Security Access Manager Runtime for Java that was already updated. Then, copy the file into the target IBM Security Access Manager Runtime for Java.

If you configured the Java application with the Security Access Manager, version 7.0, configuration program, you specified a location for the PDCA.ks file. Replace the PDCA.ks file at that location instead of the location in the JRE.

To locate the PDCA.ks file, open the properties configuration file of your application for IBM Security Access Manager Runtime for Java. For example, the file might be named pdwpm.properties.

In the file, find the pdca-url entry. The entry specifies the PDCA.ks file path.

pdca-url=file\:/user_supplied_path/PDCA.ks

Write the PDCA.ks file from an updated IBM Security Access Manager Runtime for Java into the location that the pdca-url entry specifies.

Also update the ssl-compliance entry, if it exists. For example:

ssl-compliance=none

Change the value to the appropriate compliance level for Java application that you configured with Security Access Manager, version 7.0.

For example:

ssl-compliance=suite-b-192

Procedure

Update the PDCA.ks and PD.properties files by unconfiguring the Java runtime and then reconfiguring it.

Note:

This step removes all files in the [JRE]/PolicyDirector directory and then re-creates the files. For WebSphere Application Server version 8.0 and later, the directory is [WAS_HOME]/tivoli/tam/PolicyDirector.

If any file under this directory was customized, then you must reapply the customization to the new file.

At this step, do not unconfigure the Security Access Manager Java applications that are configured to use the JRE.

You might need more information about configuring or unconfiguring Security Access Manager run time for Java. See the pdjrtecfg command utility in the IBM Security Access Manager for Web Command Reference.

Update the WebSphere® profile if:

The Security Access Manager compliance type changed and

The Security Access Manager Java applications run in a WebSphere profile.

The FIPS security mode must match the Security Access Manager compliance level.

Stop any processes that are using the JRE. For example, stop any WebSphere profiles that are using the JRE.

Update the ssl.client.props file of the WebSphere profile to allow WebSphere client applications to communicate with the profile if:

You are using a WebSphere Java run time and

You changed the FIPS security mode of the run time.

o

Regenerate the certificates of each SvrSslCfg Security Access Manager Java application. This example illustrates how to reconfigure the Security Access Manager WebSphere Portal Manager certificates:

java com.tivoli.pd.jcfg.SvrSslCfg -action replcert -admin_id sec_master
 -admin_pwd -cfg_file /opt/PolicyDirector/java/export/pdwpm/pdwpm.properties

Start the JRE and ensure that it operates properly in the updated Java run time. For WebSphere, start the WebSphere profile to start the JRE.

What to do next

Repeat this procedure for any other Security Access Manager Java run times that are on the system.

Parent topic: Regenerating certificates

Reconfiguring the PDCA on the runtime systemsReconfiguring the PDCA on the runtime systemsAfter you reconfigure the policy server and transfer the newly generated PDCA certificate to each runtime system, you must reconfigure the PDCA on the runtime systems.SSLreconfiguring runtimeTLSreconfiguring runtimeruntimereconfiguring secure communicationsecure communication, reconfiguring runtimeStop all Security Access Manager services that are running on the system by entering the following command:AIX, Linux, and Solaris operating systems:pd_start stopWindows operating systems:drive:\net stop servernameStop each Security Access Manager service. For example, to stop the policy server, type:C:\net stop IVMgrConfigure the IBM Security Access Manager runtime with the bassslcfg –config utility.For example, enter the command but replace the values for the –c and –h options./opt/PolicyDirector/sbin/bassslcfg -config -h policysvrhostname -c /var/PolicyDirector/keytab/pdcacert.b64Run the svrsslcfg -chgcert command for the authorization, proxy, and resource servers and for any other C API applications that use svrsslcfg -config.This example is for the authorization server: svrsslcfg -chgcert -f /opt/PolicyDirector/etc/[instance-]ivacld.conf -P *** -A sec_masterStart the Security Access Manager services on the computer by entering the following command:pd_start startReconfigure the certificates of any other Security Access Manager Java applications on the policy server. See Reconfiguring the certifications of Security Access Manager Java applicationsTo use the new policy server certificate authority, you must reconfigure the PDCA in the configured Java run time. You must also reconfigure the certificates of any Security Access Manager Java application that uses the IBM Security Access Manager Runtime for Java. First, update the IBM Security Access Manager Runtime for Java configuration. Then, update the certificate of each Security Access Manager Java application that uses the run time..Reconfigure the certificates of any Security Access Manager Java applications. See Server certificate revocationIf a certificate on a resource manager is compromised, you can revoke the certificate and then replace it with a new certificate..Regenerating certificatesIf a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.

Reconfiguring the PDCA on the runtime systems

After you reconfigure the policy server and transfer the newly generated PDCA certificate to each runtime system, you must reconfigure the PDCA on the runtime systems.

Procedure

Stop all Security Access Manager services that are running on the system by entering the following command:

AIX®, Linux, and Solaris operating systems:

pd_start stop

Windows operating systems:

drive:\net stop servername

Stop each Security Access Manager service. For example, to stop the policy server, type:

C:\net stop IVMgr

Configure the IBM Security Access Manager runtime with the bassslcfg –config utility. For example, enter the command but replace the values for the –c and –h options.

/opt/PolicyDirector/sbin/bassslcfg -config -h
policysvrhostname -c /var/PolicyDirector/keytab/pdcacert.b64

Run the svrsslcfg -chgcert command for the authorization, proxy, and resource servers and for any other C API applications that use svrsslcfg -config. This example is for the authorization server:

svrsslcfg -chgcert -f /opt/PolicyDirector/etc/[instance-]ivacld.conf -P *** -A sec_master

Start the Security Access Manager services on the computer by entering the following command:

pd_start start

Reconfigure the certificates of any other Security Access Manager Java™ applications on the policy server. See Reconfiguring the certifications of Security Access Manager Java applications.

What to do next

Reconfigure the certificates of any Security Access Manager Java applications. See Server certificate revocation.

Parent topic: Regenerating certificates

Transferring the PDCA certificate to other systemsTransferring the PDCA certificate to other systemsAfter regenerating the PDCA certificate, you can transfer the PDCA certificate to each system in the domain. In this case, your business security policy requires trusted transport of the PDCA signer certificate to the target machine. The network between the policy server and the target system contains untrusted segments.FTPcertificatesFTPIf auto-download is disabled, then you must manually copy the file to each system. If the File Transfer Protocol (FTP) is supported in your environment, use one of the following FTP options:Use the put command from the policy server to transfer the certificate to the other system.Use the get command from the other system to retrieve the certificate from the policy server.The following steps assume that the pdcacert.b64 certificate is retrieved from the policy server:Change to the local directory on the policy server that contains the pdcacert.b64 file:cd /var/PolicyDirector/keytabConnect to the runtime system by opening an FTP session. To illustrate, pdruntime1 is the name of the runtime system.ftp pdruntime1Log on to the remote system with the appropriate user ID and password.Change to the directory where you want to store the certificate. Assuming the default directory is on a AIX, Linux, or Solaris operating system, enter the following FTP command:cd /var/PolicyDirector/keytabIndicate that the file to be transferred is a text (ASCII) file by entering the following command:asciiTo view the transfer process visually, enter the following command:hashStart the transfer by entering the following command:put pdcacert.b64After the transfer completes, end the FTP session by entering the following command:quitRegenerating certificatesIf a private key in the PDCA certificate is compromised, then you must regenerate the key file. You might change Security Access Manager to a different compliance type that requires certificates with different bit strengths or signature algorithms. In this case, you must regenerate the key file.

Transferring the PDCA certificate to other systems

After regenerating the PDCA certificate, you can transfer the PDCA certificate to each system in the domain. In this case, your business security policy requires trusted transport of the PDCA signer certificate to the target machine. The network between the policy server and the target system contains untrusted segments.

About this task

If auto-download is disabled, then you must manually copy the file to each system. If the File Transfer Protocol (FTP) is supported in your environment, use one of the following FTP options:

Use the put command from the policy server to transfer the certificate to the other system.

Use the get command from the other system to retrieve the certificate from the policy server.

The following steps assume that the pdcacert.b64 certificate is retrieved from the policy server:

Procedure

Change to the local directory on the policy server that contains the pdcacert.b64 file:

cd /var/PolicyDirector/keytab

Connect to the runtime system by opening an FTP session. To illustrate, pdruntime1 is the name of the runtime system.

ftp pdruntime1

Log on to the remote system with the appropriate user ID and password.

Change to the directory where you want to store the certificate. Assuming the default directory is on a AIX, Linux, or Solaris operating system, enter the following FTP command:

cd /var/PolicyDirector/keytab

Indicate that the file to be transferred is a text (ASCII) file by entering the following command:

ascii

To view the transfer process visually, enter the following command:

hash

Start the transfer by entering the following command:

put pdcacert.b64

After the transfer completes, end the FTP session by entering the following command:

quit

Parent topic: Regenerating certificates

Server certificate revocationServer certificate revocationIf a certificate on a resource manager is compromised, you can revoke the certificate and then replace it with a new certificate.certificatesrevocationchgcert option of svrsslcfg commandcommandssvrsslcfg -unconfigsvrsslcfg -unconfig commandIf the certificate on a C-based resource manager is compromised, you can run the svrsslcfg –chgcert utility to replace the existing server certificate and update the PDCA certificate. For resource managers that are based on Java, use the PDAppSvrConfig.replaceAppSvrCert() method.You also can reconfigure a C-based server by running the svrsslcfg –unconfig and svrsslcfg –config utilities. The policy server must be running when you reconfigure it. These commands update both the server certificate for the authorization server and its trusted certificate (the new PDCA certificate). Similarly, a resource manager based on Java can be unconfigured and reconfigured with the Java SvrSslCfg class.Certificate and password managementTo securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.

Server certificate revocation

If a certificate on a resource manager is compromised, you can revoke the certificate and then replace it with a new certificate.

If the certificate on a C-based resource manager is compromised, you can run the svrsslcfg –chgcert utility to replace the existing server certificate and update the PDCA certificate.

For resource managers that are based on Java™, use the PDAppSvrConfig.replaceAppSvrCert() method.

You also can reconfigure a C-based server by running the svrsslcfg –unconfig and svrsslcfg –config utilities. The policy server must be running when you reconfigure it. These commands update both the server certificate for the authorization server and its trusted certificate (the new PDCA certificate). Similarly, a resource manager based on Java can be unconfigured and reconfigured with the Java SvrSslCfg class.

Parent topic: Certificate and password management

Additional key file and stash file considerationsAdditional key file and stash file considerationsThere are additional considerations for key file and stash file renewal.configoption, bassslcfgcommandsbassslcfgbassslcfg utilityguidelineskey file renewalguidelinesstash file renewalkey filesrenewal guidelinesstash filesrenewal guidelinesfilesstash renewal guidelinesfilesrenewal guidelinesWhen a certificate and the password to the key file that contains that certificate are both expired, the password must be refreshed. For example, for the authorization server, run the svrsslcfg –chgpwd utility and then the svrsslcfg –chgcert utility. You must run these utilities because a valid password is needed to open the key file to obtain the certificate.The lifetime of a certificate is determined by the value of the ssl-cert-life entry in the [ssl] stanza of the ivmgrd.conf file when the policy server is started. Any certificates that are issued or renewed use this value. To increase or decrease this value, change the value and restart the policy server. The new value is in effect only for certificates that are issued or renewed from that point onward. The actual time is whichever value is less: the value specified in the ivmgrd.conf configuration file or the number of days before the policy server certificate authority certificate expires.For automatic password renewal, the lifetime of a password is controlled by the value of the ssl-pwd-life entry in the [ssl] stanza in effect when the server is started. For manual password renewal, the value is dictated by the value supplied to the svrsslcfg –chgpwd utility. This value is also written into the appropriate configuration file.The key file password refresh occurs after half the lifetime of the password expiration date. If the blade server is not running during the second half of the password life, the ACL update cannot refresh the password. The update uses the connection from the management server to the blade server, which uses the SSL connection protected by the certificate. The certificate, in turn, is protected by the password.Security Access Manager servers can also communicate with Lightweight Directory Access Protocol (LDAP) with SSL. In the standard configuration, this communication uses server-side authentication only. Therefore, the Security Access Manager server needs only the CA certificate that signed the LDAP server certificate or the LDAP server certificate itself. The expiration and management of these certificates are not handled by Security Access Manager. However, it is possible to include the LDAP certificate in the key file for a resource manager by running the svrsslcfg –config utility with the -C option. Refresh certificates that are not managed by Security Access Manager with the same mechanism that created the initial certificate. The new certificate can be replaced in the key file by running the svrsslcfg –modify –C new_cert_filename utility.After running the bassslcfg –config utility, you might need to change the permissions on the pd.kdb and pd.sth files.The configuration files mentioned are found in the install_dir/etc directory. For example, on an AIX system, the policy server, authorization server, and runtime configuration files are /opt/PolicyDirector/etc/ivmgrd.conf, /opt/PolicyDirector/etc/[instance-]ivacld.conf, and /opt/PolicyDirector/etc/pd.conf. Similarly, the key files and stash files can be found in the install_dir/keytabs directory.Security Access Manager does not distinguish between export and domestic encryption. For encryption based on Java, the strength is regulated by the jurisdiction files that are present in the Java runtime environment. There is no set length for keys generated by the IBM Security Access Manager runtime.Both the public keys that are included in certificates and the private keys that might be stored in key files have key lengths. The maximum key length is 2048 bits. Public keys with 2048-bit key lengths can be generated by using the configuration utilities bassslcfg, mgrsslcfg, or svrsslcfg.Certificate and password managementTo securely transfer information between servers and clients, you can configure Security Access Manager to use various server-side and client-side certificates, key files, and stash files for authentication. During the initial configuration, you can configure the settings for the default lifetime of the certificates and the key file passwords.

Additional key file and stash file considerations

There are additional considerations for key file and stash file renewal.

When a certificate and the password to the key file that contains that certificate are both expired, the password must be refreshed. For example, for the authorization server, run the svrsslcfg –chgpwd utility and then the svrsslcfg –chgcert utility. You must run these utilities because a valid password is needed to open the key file to obtain the certificate.

The lifetime of a certificate is determined by the value of the ssl-cert-life entry in the [ssl] stanza of the ivmgrd.conf file when the policy server is started. Any certificates that are issued or renewed use this value. To increase or decrease this value, change the value and restart the policy server. The new value is in effect only for certificates that are issued or renewed from that point onward. The actual time is whichever value is less: the value specified in the ivmgrd.conf configuration file or the number of days before the policy server certificate authority certificate expires.

For automatic password renewal, the lifetime of a password is controlled by the value of the ssl-pwd-life entry in the [ssl] stanza in effect when the server is started. For manual password renewal, the value is dictated by the value supplied to the svrsslcfg –chgpwd utility. This value is also written into the appropriate configuration file.

The key file password refresh occurs after half the lifetime of the password expiration date. If the blade server is not running during the second half of the password life, the ACL update cannot refresh the password. The update uses the connection from the management server to the blade server, which uses the SSL connection protected by the certificate. The certificate, in turn, is protected by the password.

Security Access Manager servers can also communicate with Lightweight Directory Access Protocol (LDAP) with SSL. In the standard configuration, this communication uses server-side authentication only. Therefore, the Security Access Manager server needs only the CA certificate that signed the LDAP server certificate or the LDAP server certificate itself. The expiration and management of these certificates are not handled by Security Access Manager. However, it is possible to include the LDAP certificate in the key file for a resource manager by running the svrsslcfg –config utility with the -C option.

Refresh certificates that are not managed by Security Access Manager with the same mechanism that created the initial certificate. The new certificate can be replaced in the key file by running the svrsslcfg –modify –C new_cert_filename utility.

After running the bassslcfg –config utility, you might need to change the permissions on the pd.kdb and pd.sth files.

The configuration files mentioned are found in the install_dir/etc directory. For example, on an AIX® system, the policy server, authorization server, and runtime configuration files are /opt/PolicyDirector/etc/ivmgrd.conf, /opt/PolicyDirector/etc/[instance-]ivacld.conf, and /opt/PolicyDirector/etc/pd.conf. Similarly, the key files and stash files can be found in the install_dir/keytabs directory.

Security Access Manager does not distinguish between export and domestic encryption. For encryption based on Java™, the strength is regulated by the jurisdiction files that are present in the Java runtime environment. There is no set length for keys generated by the IBM Security Access Manager runtime.

Both the public keys that are included in certificates and the private keys that might be stored in key files have key lengths. The maximum key length is 2048 bits. Public keys with 2048-bit key lengths can be generated by using the configuration utilities bassslcfg, mgrsslcfg, or svrsslcfg.

Parent topic: Certificate and password management

Server managementThis chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.servermanagement Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Security Access Manager serversSecurity Access Manager consists of server processes, or daemons.Security Access Manager utilitiesThe Security Access Manager utilities are described in detail in the IBM Security Access Manager for Web: Command Reference.Server configuration file tasksYou can use the server configuration files to customize the operation of Security Access Manager and its servers. Policy server administration tasksThe policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.

Server management

This chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.

Security Access Manager servers
Security Access Manager consists of server processes, or daemons.

Security Access Manager utilities
The Security Access Manager utilities are described in detail in the IBM Security Access Manager for Web: Command Reference.

Server configuration file tasks
You can use the server configuration files to customize the operation of Security Access Manager and its servers.

Policy server administration tasks
The policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.

Parent topic: Access Manager Platform and Supporting Components administration

Security Access Manager serversSecurity Access Manager consists of server processes, or daemons.types ofSecurity Access Manager serversauthorizationserverpdacld server processpdacld server processauthorization serverpolicyserverpdmgrd server processpdmgrd server processpolicy serverThe server processes (daemons) include:pdmgrdThe server process for the policy server.pdacldThe server process for the authorization server.Security Access Manager server componentsGraphic demonstrating one possible server installation configurationThe authorization server allows other applications to make authorization calls to Security Access Manager with the authorization application programming interface (API). The authorization server also acts as a logging and auditing collection server to store records of server activity.Server managementThis chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.Server dependenciesTo ensure optimal performance, you must consider several dependencies when you configure your server.

Security Access Manager servers

Security Access Manager consists of server processes, or daemons.

The server processes (daemons) include:

pdmgrd

The server process for the policy server.

pdacld

The server process for the authorization server.

Figure 85. Security Access Manager server components

The authorization server allows other applications to make authorization calls to Security Access Manager with the authorization application programming interface (API). The authorization server also acts as a logging and auditing collection server to store records of server activity.

Server dependencies
To ensure optimal performance, you must consider several dependencies when you configure your server.

Parent topic: Server management

Server dependenciesTo ensure optimal performance, you must consider several dependencies when you configure your server.dependencies, serverserverdependencies Dependencies include:There must be at least one instance of the policy server.There must be at least one policy server defined. You can have a single policy server and create as many domains as you want. When a domain is created, a separate policy database is also created for each domain. The single policy server can access any of the distinct policy databases.The policy server manages the policy database.There must be only one policy database (master authorization database) in a domain. The policy database must be on a highly available policy server with a robust file system.Each policy database is subject to a regular backup procedure. The administrator can specify the location for the backup files.The policy servers provide authorization database replication services to all other Security Access Manager servers in the domain that run in local cache mode.Each resource manager, such as Security Access Manager WebSEAL, applies security policy based on information from either the policy database or from a replicated authorization database.Security Access Manager serversSecurity Access Manager consists of server processes, or daemons.

Server dependencies

To ensure optimal performance, you must consider several dependencies when you configure your server.

Dependencies include:

There must be at least one instance of the policy server.

There must be at least one policy server defined. You can have a single policy server and create as many domains as you want. When a domain is created, a separate policy database is also created for each domain. The single policy server can access any of the distinct policy databases.

The policy server manages the policy database.

There must be only one policy database (master authorization database) in a domain.

The policy database must be on a highly available policy server with a robust file system.

Each policy database is subject to a regular backup procedure. The administrator can specify the location for the backup files.

The policy servers provide authorization database replication services to all other Security Access Manager servers in the domain that run in local cache mode.

Each resource manager, such as Security Access Manager WebSEAL, applies security policy based on information from either the policy database or from a replicated authorization database.

Parent topic: Security Access Manager servers

Security Access Manager utilitiesThe Security Access Manager utilities are described in detail in the IBM Security Access Manager for Web: Command Reference.types ofSecurity Access Manager utilitiesutilitiesThe table at the beginning of the utilities section lists available utilities and their purposes.The pdadmin utility, which is also described in IBM Security Access Manager for Web: Command Reference, provides commands that assist in troubleshooting problems. For example, the pdadmin utility includes the server task stats and server task trace commands that enable statistics gathering and capture information about error conditions. In addition, the IBM Security Access Manager for Web Troubleshooting Guide provides further diagnostic information for using the Security Access Manager pdadmin utility and other utilities.Server managementThis chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.

Security Access Manager utilities

The Security Access Manager utilities are described in detail in the IBM Security Access Manager for Web: Command Reference.

The table at the beginning of the utilities section lists available utilities and their purposes.

The pdadmin utility, which is also described in IBM Security Access Manager for Web: Command Reference, provides commands that assist in troubleshooting problems. For example, the pdadmin utility includes the server task stats and server task trace commands that enable statistics gathering and capture information about error conditions. In addition, the IBM Security Access Manager for Web Troubleshooting Guide provides further diagnostic information for using the Security Access Manager pdadmin utility and other utilities.

Parent topic: Server management

Server configuration file tasksYou can use the server configuration files to customize the operation of Security Access Manager and its servers. configurationfilesserverserverconfiguration filesVarious server configurations are discussed in Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers..Server managementThis chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.Changing configuration settingsYou can change a configuration setting. For example, you might change Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.Automatic server startup at boot timeStanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.

Server configuration file tasks

You can use the server configuration files to customize the operation of Security Access Manager and its servers.

Various server configurations are discussed in Configuration file reference.

Changing configuration settings
You can change a configuration setting. For example, you might change Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

Automatic server startup at boot time
Stanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.

Parent topic: Server management

Changing configuration settingsYou can change a configuration setting. For example, you might change Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.configurationsettings, changingThe configuration files, stanzas, and stanza entries are described in Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.. Make a backup copy of the configuration file that you plan to modify. If you encounter an error, use the backup copy to return the configuration file to a known working state.Stop the Security Access Manager servers that are affected.Use one of the following mechanisms to modify the configuration file:Use the pdadmin config commands to modify the configuration file.Use the appropriate configuration tool for your server to change the configuration settings: For the ivmgrd.conf file, use the mgrsslcfg utility.For the pd.conf file, use the bassslcfg utility.For all other configuration files, use the svrsslcfg utility.Many stanzas or values are created or modified only by using Security Access Manager configuration utilities. Some values are completed automatically after the configuration is completed. Do not modify these values.Start the Security Access Manager servers that are affected.For example, if you want to change the ivmgrd.conf file, you must stop the policy servers. Complete the change and restart all the policy servers to put the change into effect.Server configuration file tasksYou can use the server configuration files to customize the operation of Security Access Manager and its servers.

Changing configuration settings

You can change a configuration setting. For example, you might change Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

About this task

The configuration files, stanzas, and stanza entries are described in Configuration file reference.

Procedure

Make a backup copy of the configuration file that you plan to modify. If you encounter an error, use the backup copy to return the configuration file to a known working state.

Stop the Security Access Manager servers that are affected.

Use one of the following mechanisms to modify the configuration file:

Use the pdadmin config commands to modify the configuration file.

Use the appropriate configuration tool for your server to change the configuration settings:

For the ivmgrd.conf file, use the mgrsslcfg utility.

For the pd.conf file, use the bassslcfg utility.

For all other configuration files, use the svrsslcfg utility.

Note: Many stanzas or values are created or modified only by using Security Access Manager configuration utilities. Some values are completed automatically after the configuration is completed. Do not modify these values.

Start the Security Access Manager servers that are affected.

Example

For example, if you want to change the ivmgrd.conf file, you must stop the policy servers. Complete the change and restart all the policy servers to put the change into effect.

Parent topic: Server configuration file tasks

Automatic server startup at boot timeStanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.serverautomatic startupBy default, the pd.conf file is installed at the following location for AIX, Linux, and Solaris operating systems: /opt/PolicyDirector/etc/pd.confBy default, the pd.conf file is installed at the following location for Windows operating systems: c:\Program files\tivoli\Policy Director\etc\pd.confServer configuration file tasksYou can use the server configuration files to customize the operation of Security Access Manager and its servers. Policy serverWhen the PDMgr package is installed, the policy server automatically starts after each system reboot.Authorization serverWhen the PDAcld package is installed, the authorization server automatically starts after each system reboot.

Automatic server startup at boot time

Stanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.

By default, the pd.conf file is installed at the following location for AIX, Linux, and Solaris operating systems:

/opt/PolicyDirector/etc/pd.conf

By default, the pd.conf file is installed at the following location for Windows operating systems:

c:\Program files\tivoli\Policy Director\etc\pd.conf

Policy server
When the PDMgr package is installed, the policy server automatically starts after each system reboot.

Authorization server
When the PDAcld package is installed, the authorization server automatically starts after each system reboot.

Parent topic: Server configuration file tasks

Policy serverWhen the PDMgr package is installed, the policy server automatically starts after each system reboot.startuppolicy serverautomatic startup, preventingboot-start-ivmgrd commandpolicyserverautomatic startup, preventing[pdrte] boot-start-ivmgrd = yesTo prevent the policy server from automatic startup, set: boot-start-ivmgrd = noAutomatic server startup at boot timeStanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.

Policy server

When the PDMgr package is installed, the policy server automatically starts after each system reboot.

[pdrte]
boot-start-ivmgrd = yes

To prevent the policy server from automatic startup, set:

boot-start-ivmgrd = no

Parent topic: Automatic server startup at boot time

Authorization serverWhen the PDAcld package is installed, the authorization server automatically starts after each system reboot.startupauthorization serverautomatic startup, preventingboot-start-ivacld commandauthorizationserverautomatic startup, preventing[pdrte] boot-start-[instance-]ivacld = yesTo prevent the authorization server from automatic startup, set: boot-start-[instance-]ivacld = noAutomatic server startup at boot timeStanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.

Authorization server

When the PDAcld package is installed, the authorization server automatically starts after each system reboot.

[pdrte]
boot-start-[instance-]ivacld = yes

To prevent the authorization server from automatic startup, set:

boot-start-[instance-]ivacld = no

Parent topic: Automatic server startup at boot time

Policy server administration tasksThe policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.The policy server typically requires little administration or configuration. This section describes configuration tasks available to the administrator.Server managementThis chapter provides detailed information about general administration and configuration tasks on the Security Access Manager servers.Replicate the authorization databaseA Security Access Manager domain administrator can make security policy changes to a domain at any time.Use the server replicate commandWhen you configure update notification to be manual, the manual application of the server replicate command controls this event. Set the number of update-notifier threadsThe policy server is responsible for synchronizing all database replicas in the domain.Set the notification delay timeWhen the policy server is instructed to change the master authorization database, it waits for a default period before sending out notifications to database replicas.

Policy server administration tasks

The policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.

The policy server typically requires little administration or configuration. This section describes configuration tasks available to the administrator.

Replicate the authorization database
A Security Access Manager domain administrator can make security policy changes to a domain at any time.

Use the server replicate command
When you configure update notification to be manual, the manual application of the server replicate command controls this event.

Set the number of update-notifier threads
The policy server is responsible for synchronizing all database replicas in the domain.

Set the notification delay time
When the policy server is instructed to change the master authorization database, it waits for a default period before sending out notifications to database replicas.

Parent topic: Server management

Replicate the authorization databaseA Security Access Manager domain administrator can make security policy changes to a domain at any time.authorizationdatabase, replicatingreplicationauthorization databaseauto-database-update-notify entryA primary responsibility of the policy server is to make the necessary adjustments to the domain master authorization database to reflect these changes.When the policy server modifies the master authorization database, it can send out notification of this change to all resource manager servers with replica databases. The authorization servers must then request a database update from the policy server.Additionally, resource manager servers can check for database updates by polling the policy server at regular intervals. Polling configuration for a WebSEAL client, for example, is explained in the IBM Security Access Manager for Web: WebSEAL Administration Guide.Update notifications from the policy server can be configured as an automatic process or a manually controlled task. Notification is determined by the auto-database-update-notify stanza entry in the [ivmgrd] stanza of the ivmgrd.conf configuration file. By default, the stanza entry value is set to yes (update notification is automatically done by the policy server): [ivmgrd] auto-database-update-notify = yesThis automatic setting is appropriate for environments where database changes are few and infrequent. When you configure update notification to be automatic, you must also correctly configure the max-notifier-threads and notifier-wait-time stanza entries. For more information about these entries, see Set the number of update-notifier threadsThe policy server is responsible for synchronizing all database replicas in the domain. and Set the notification delay timeWhen the policy server is instructed to change the master authorization database, it waits for a default period before sending out notifications to database replicas..When you configure update notification to be manual, manual application of the server replicate command controls this event. [ivmgrd] auto-database-update-notify = noThis manual setting is appropriate for environments where database modifications occur frequently and involve substantial changes. In some cases, several database modifications can generate many update notifications that soon become obsolete because of the continuing changes to the master database. These obsolete notifications cause unnecessary network traffic and impair the performance of resource managers because of continued requesting and processing of policy updates.Use the manual control of update notification to complete the process of modifying the master authorization database before update notifications are sent out to authorization servers with database replicas.In manual mode, update notification uses the notifier thread pool as it does in automatic mode. Therefore, the manual mode setting is affected by the max-notifier-threads stanza entry value. For more information about this stanza entry, see Set the number of update-notifier threadsThe policy server is responsible for synchronizing all database replicas in the domain..Policy server administration tasksThe policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.

Replicate the authorization database

A Security Access Manager domain administrator can make security policy changes to a domain at any time.

A primary responsibility of the policy server is to make the necessary adjustments to the domain master authorization database to reflect these changes.

When the policy server modifies the master authorization database, it can send out notification of this change to all resource manager servers with replica databases. The authorization servers must then request a database update from the policy server.

Note: Additionally, resource manager servers can check for database updates by polling the policy server at regular intervals. Polling configuration for a WebSEAL client, for example, is explained in the IBM Security Access Manager for Web: WebSEAL Administration Guide.

Update notifications from the policy server can be configured as an automatic process or a manually controlled task. Notification is determined by the auto-database-update-notify stanza entry in the [ivmgrd] stanza of the ivmgrd.conf configuration file. By default, the stanza entry value is set to yes (update notification is automatically done by the policy server):

[ivmgrd]
auto-database-update-notify = yes

This automatic setting is appropriate for environments where database changes are few and infrequent. When you configure update notification to be automatic, you must also correctly configure the max-notifier-threads and notifier-wait-time stanza entries. For more information about these entries, see Set the number of update-notifier threads and Set the notification delay time.

When you configure update notification to be manual, manual application of the server replicate command controls this event.

[ivmgrd]
auto-database-update-notify = no

This manual setting is appropriate for environments where database modifications occur frequently and involve substantial changes. In some cases, several database modifications can generate many update notifications that soon become obsolete because of the continuing changes to the master database. These obsolete notifications cause unnecessary network traffic and impair the performance of resource managers because of continued requesting and processing of policy updates.

Use the manual control of update notification to complete the process of modifying the master authorization database before update notifications are sent out to authorization servers with database replicas.

In manual mode, update notification uses the notifier thread pool as it does in automatic mode. Therefore, the manual mode setting is affected by the max-notifier-threads stanza entry value. For more information about this stanza entry, see Set the number of update-notifier threads.

Parent topic: Policy server administration tasks

Use the server replicate commandWhen you configure update notification to be manual, the manual application of the server replicate command controls this event. serverreplicatingserverserver replicate commandcommandsserver replicatepdadmin sec_master> server replicate -server test_serverWhen the -server option (test_server in the previous example) is specified, only that server is notified of changes to the master authorization database. A response indicates the success or failure of the notification and the replication.When the -server option is not specified, all configured resource manager servers receive update notifications. A successful response indicates only that the policy server began sending out update notifications. The response does not indicate success or failure of the actual notification and replication processes.The authorization required to run this command is the s action bit on the /Management/Server object.For more information about the server replicate command, see the IBM Security Access Manager for Web: Command Reference.Policy server administration tasksThe policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.

Use the server replicate command

When you configure update notification to be manual, the manual application of the server replicate command controls this event.

pdadmin sec_master> server replicate -server test_server

When the -server option (test_server in the previous example) is specified, only that server is notified of changes to the master authorization database. A response indicates the success or failure of the notification and the replication.

When the -server option is not specified, all configured resource manager servers receive update notifications. A successful response indicates only that the policy server began sending out update notifications. The response does not indicate success or failure of the actual notification and replication processes.

The authorization required to run this command is the s action bit on the /Management/Server object.

For more information about the server replicate command, see the IBM Security Access Manager for Web: Command Reference.

Parent topic: Policy server administration tasks

Set the number of update-notifier threadsThe policy server is responsible for synchronizing all database replicas in the domain.update-notifier threadsmax-notifier-threads entryreplicadatabases, synchronizingWhen a change is made to the master database, notification threads announce this change to all replicas configured to receive update notifications. Each replica must then download the new information or the changes from the master.The policy server configuration file, ivmgrd.conf, contains a stanza entry for setting the maximum number of update-notifier threads. This pool of threads allows simultaneous (parallel) notification.For example, to concurrently notify 30 replicas of a database change, the thread pool must be set to at least 30. If there are more than 30 replicas, another round of notifications occurs (in this example, 30 at a time). All replicas are guaranteed to be notified, regardless of the value of this stanza entry.The performance goal of the update-notifier threads value is to announce a database change as quickly as possible. Generally the value must be set to equal the number of existing replicas. This results in the performance advantage of a single pool of threads quickly accomplishing the notification task to all replicas at once.The default event notifier thread pool is set as: [ivmgrd] max-notifier-threads = 10When the auto-database-update-notify stanza entry is set to yes, you must correctly configure this stanza entry and also the notifier-wait-time stanza entry. See also Set the notification delay timeWhen the policy server is instructed to change the master authorization database, it waits for a default period before sending out notifications to database replicas..Policy server administration tasksThe policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.

Set the number of update-notifier threads

The policy server is responsible for synchronizing all database replicas in the domain.

When a change is made to the master database, notification threads announce this change to all replicas configured to receive update notifications. Each replica must then download the new information or the changes from the master.

The policy server configuration file, ivmgrd.conf, contains a stanza entry for setting the maximum number of update-notifier threads. This pool of threads allows simultaneous (parallel) notification.

For example, to concurrently notify 30 replicas of a database change, the thread pool must be set to at least 30. If there are more than 30 replicas, another round of notifications occurs (in this example, 30 at a time). All replicas are guaranteed to be notified, regardless of the value of this stanza entry.

The performance goal of the update-notifier threads value is to announce a database change as quickly as possible. Generally the value must be set to equal the number of existing replicas. This results in the performance advantage of a single pool of threads quickly accomplishing the notification task to all replicas at once.

The default event notifier thread pool is set as:

[ivmgrd]
max-notifier-threads = 10

When the auto-database-update-notify stanza entry is set to yes, you must correctly configure this stanza entry and also the notifier-wait-time stanza entry. See also Set the notification delay time.

Parent topic: Policy server administration tasks

Set the notification delay timeWhen the policy server is instructed to change the master authorization database, it waits for a default period before sending out notifications to database replicas.notification delay timenotifier-wait-time entryThe default time delay is set at 15 seconds. This time delay is reset with each subsequent change to the database.The purpose of the time delay is to prevent the policy server from sending individual replica notifications for each change in a series of database changes. The time delay helps to ensure optimal performance of the Security Access Manager system.This performance feature is important for environments where batch changes are made to the authorization database. It is not efficient for policy changes to be sent to database replicas until all changes are made.You can override this default notification time delay by changing the notifier-wait-time entry value in the [ivmgrd] stanza of the ivmgrd.conf configuration file. For example: [ivmgrd] notifier-wait-time = 20By default, the value is set to 15 seconds.When the auto-database-update-notify entry is set to yes, you must configure this entry and the max-notifier-threads entry. See also Set the number of update-notifier threadsThe policy server is responsible for synchronizing all database replicas in the domain..Policy server administration tasksThe policy server manages the policy database or databases and maintains location information about other Security Access Manager servers in each domain.

Set the notification delay time

When the policy server is instructed to change the master authorization database, it waits for a default period before sending out notifications to database replicas.

The default time delay is set at 15 seconds. This time delay is reset with each subsequent change to the database.

The purpose of the time delay is to prevent the policy server from sending individual replica notifications for each change in a series of database changes. The time delay helps to ensure optimal performance of the Security Access Manager system.

This performance feature is important for environments where batch changes are made to the authorization database. It is not efficient for policy changes to be sent to database replicas until all changes are made.

You can override this default notification time delay by changing the notifier-wait-time entry value in the [ivmgrd] stanza of the ivmgrd.conf configuration file. For example:

[ivmgrd]
notifier-wait-time = 20

By default, the value is set to 15 seconds.

When the auto-database-update-notify entry is set to yes, you must configure this entry and the max-notifier-threads entry. See also Set the number of update-notifier threads.

Parent topic: Policy server administration tasks

High availability of the policy serverThis chapter provides information about ensuring that Security Access Manager provides high availability for the policy server in case a server failure occurs. policy serverhigh availability ofhigh availabilitypolicy serverThis chapter describes how Security Access Manager supports the replication capability of the LDAP directory server to ensure that its data is always available.For more concepts about high availability in an appliance environment, see High availability for the policy serverYou can enable the replication of the Security Access Manager runtime settings and the certificate database settings to achieve high availability for the policy server. .Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Primary and replica LDAP serversSecurity Access Manager allows primary and replica LDAP servers. The replica LDAP server, on a different node, can assume LDAP server operations if the primary LDAP server fails.

High availability of the policy server

This chapter provides information about ensuring that Security Access Manager provides high availability for the policy server in case a server failure occurs.

This chapter describes how Security Access Manager supports the replication capability of the LDAP directory server to ensure that its data is always available.

For more concepts about high availability in an appliance environment, see High availability for the policy server.

Primary and replica LDAP servers
Security Access Manager allows primary and replica LDAP servers. The replica LDAP server, on a different node, can assume LDAP server operations if the primary LDAP server fails.

Parent topic: Access Manager Platform and Supporting Components administration

Primary and replica LDAP serversSecurity Access Manager allows primary and replica LDAP servers. The replica LDAP server, on a different node, can assume LDAP server operations if the primary LDAP server fails.serverLDAP LDAPserverfailoverDuring failover, no write operations can occur. Only read-only LDAP server operations are permitted during failover.See the LDAP server documentation for complete information about high availability of LDAP servers.High availability of the policy serverThis chapter provides information about ensuring that Security Access Manager provides high availability for the policy server in case a server failure occurs.

Primary and replica LDAP servers

Security Access Manager allows primary and replica LDAP servers. The replica LDAP server, on a different node, can assume LDAP server operations if the primary LDAP server fails.

During failover, no write operations can occur. Only read-only LDAP server operations are permitted during failover.

See the LDAP server documentation for complete information about high availability of LDAP servers.

Parent topic: High availability of the policy server

Multiple-tenancy policy serverMultiple-tenancy policy serverA multiple-tenancy server is a server that supports the hosting of multiple customers on a single server instead of on multiple client systems. multiple-tenancy policy serverdatabasepath for user registryFor example, your company might be sharing applications or data on your company server with your customer (for example, Smith-Davis Enterprises). Before adding data and information that belongs to another customer (for example, Systems, Inc.), you must ensure that these two customers cannot get access to the data or applications that belong to the other company.Using a multiple-tenancy (multi-domain) server, you can run the applications or data for each company in an isolated server environment. Running in an isolated or partitioned server environment replaces the need to use multiple physical servers for each customer and their applications. Depending on the demands of your customers and their applications, you can host multiple clients on a single server. Replacing multiple servers with one server reduces the costs to your company for the services you provide to your customers. For example, fewer servers reduce hardware costs and reduce IT personnel burden. It is easier to manage a single server than it is to manage multiple servers.A multiple-tenancy server is not necessarily less secure than the traditional one-server, one-client approach. Using technologies such as SSL and restricted access, you can protect two customers (users) on the same server from one another. Extra layers of security for multiple-user applications are designed into Security Access Manager. Security Access Manager compartmentalizes each domain to seal off users from one another rather than using the multiple-user security provisions that are provided by the operating system.Multiple-tenancy is supported by Security Access Manager through the use of different Security Access Manager domains. These domains can be managed through the Security Access Manager administration interface. For more information about managing domains, see Domain managementAn administrator in the management domain can create additional domains. You must specify a unique name and an administrator when you create the domain. Domain administrators can do administrative tasks only within their own domains and do not have the authority to do tasks in other domains..Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy.

Multiple-tenancy policy server

A multiple-tenancy server is a server that supports the hosting of multiple customers on a single server instead of on multiple client systems.

For example, your company might be sharing applications or data on your company server with your customer (for example, Smith-Davis Enterprises). Before adding data and information that belongs to another customer (for example, Systems, Inc.), you must ensure that these two customers cannot get access to the data or applications that belong to the other company.

Using a multiple-tenancy (multi-domain) server, you can run the applications or data for each company in an isolated server environment. Running in an isolated or partitioned server environment replaces the need to use multiple physical servers for each customer and their applications. Depending on the demands of your customers and their applications, you can host multiple clients on a single server. Replacing multiple servers with one server reduces the costs to your company for the services you provide to your customers. For example, fewer servers reduce hardware costs and reduce IT personnel burden. It is easier to manage a single server than it is to manage multiple servers.

A multiple-tenancy server is not necessarily less secure than the traditional one-server, one-client approach. Using technologies such as SSL and restricted access, you can protect two customers (users) on the same server from one another. Extra layers of security for multiple-user applications are designed into Security Access Manager. Security Access Manager compartmentalizes each domain to seal off users from one another rather than using the multiple-user security provisions that are provided by the operating system.

Multiple-tenancy is supported by Security Access Manager through the use of different Security Access Manager domains. These domains can be managed through the Security Access Manager administration interface. For more information about managing domains, see Domain management.

Parent topic: Access Manager Platform and Supporting Components administration

Diagnostics and auditingSecurity Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers.diagnostic events, overviewauditingoverviewEvents for diagnostics and auditing pertain to the operations of the Security Access Manager servers. These events do not pertain to the installation of these servers.To enable diagnostics and auditing, you define which types of events to capture. When events are captured, they can be written to log files. Events can also be written to the standard output (STDOUT) device, to the standard error (STDERR) device, or to a combination of these destinations. Beyond these destinations, when events are captured, they can be redirected to a remote server or redirected for processing to an application that uses log agents.During the installation of the Security Access Manager servers, the installation logs capture all messages for that specific installation. When using a native installation, the installation uses the operating system logs. For information about installation logs, see the IBM Security Access Manager for Web: Troubleshooting Guide.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Diagnostic eventsFor diagnostic purposes, define which message events and which trace events to capture. These events can help you troubleshoot problems.Auditing eventsFor auditing purposes, define which audit, statistic, or other type of events to capture. Use these events to create snapshots of various server activities.

Diagnostics and auditing

Security Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers.

Events for diagnostics and auditing pertain to the operations of the Security Access Manager servers. These events do not pertain to the installation of these servers.

To enable diagnostics and auditing, you define which types of events to capture. When events are captured, they can be written to log files. Events can also be written to the standard output (STDOUT) device, to the standard error (STDERR) device, or to a combination of these destinations. Beyond these destinations, when events are captured, they can be redirected to a remote server or redirected for processing to an application that uses log agents.

During the installation of the Security Access Manager servers, the installation logs capture all messages for that specific installation. When using a native installation, the installation uses the operating system logs. For information about installation logs, see the IBM® Security Access Manager for Web: Troubleshooting Guide.

Diagnostic events
For diagnostic purposes, define which message events and which trace events to capture. These events can help you troubleshoot problems.

Auditing events
For auditing purposes, define which audit, statistic, or other type of events to capture. Use these events to create snapshots of various server activities.

Parent topic: Access Manager Platform and Supporting Components administration

Diagnostic eventsFor diagnostic purposes, define which message events and which trace events to capture. These events can help you troubleshoot problems.messagestrace dataeventsdiagnosticeventsmessageseventstraceTo configure diagnostic events, define statements in the server-specific routing files. Each server has an associated routing file. The statements in these routing files are for both message events and trace events. You define the statements for message events by severity level. You define the statements for trace events by trace level and optionally by component.See the IBM Security Access Manager for Web: Troubleshooting Guide.Diagnostics and auditingSecurity Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers.

Diagnostic events

For diagnostic purposes, define which message events and which trace events to capture. These events can help you troubleshoot problems.

To configure diagnostic events, define statements in the server-specific routing files. Each server has an associated routing file. The statements in these routing files are for both message events and trace events. You define the statements for message events by severity level. You define the statements for trace events by trace level and optionally by component.

See the IBM® Security Access Manager for Web: Troubleshooting Guide.

Parent topic: Diagnostics and auditing

Auditing eventsFor auditing purposes, define which audit, statistic, or other type of events to capture. Use these events to create snapshots of various server activities.auditingeventsstatisticseventsauditingeventsstatisticsYou can log audit events with Security Access Manager.To configure auditing events, define stanza entries in the configuration files. Depending on your approach, define different stanza entries in different configuration files. For native Security Access Manager auditing, you define logcfg entries in the appropriate stanza of the server-specific configuration files. For additional information about audit events, see the IBM Security Access Manager for Web: Auditing Guide.Diagnostics and auditingSecurity Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers.

Auditing events

For auditing purposes, define which audit, statistic, or other type of events to capture. Use these events to create snapshots of various server activities.

You can log audit events with Security Access Manager.

To configure auditing events, define stanza entries in the configuration files. Depending on your approach, define different stanza entries in different configuration files. For native Security Access Manager auditing, you define logcfg entries in the appropriate stanza of the server-specific configuration files.

For additional information about audit events, see the IBM Security Access Manager for Web: Auditing Guide.

Parent topic: Diagnostics and auditing

Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.configurationfileschangingconfigurationfilesguidelinesAccess Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. General guidelinesUse the following general guidelines when you change the configuration settings:Default valuesUse the following guidelines when changing default configuration settings:StringsSome values accept a string value.Defined stringsSome values accept a string value, but the value must be a string from a set of defined strings.File namesSome values are file names.IntegersMany stanza entries expect the value for the entry to be expressed as an integer.Boolean valuesMany stanza entries represent a Boolean value.

Guidelines for changing configuration files

These guidelines are provided to help you change the Security Access Manager configuration files.

General guidelines
Use the following general guidelines when you change the configuration settings:

Default values
Use the following guidelines when changing default configuration settings:

Strings
Some values accept a string value.

Defined strings
Some values accept a string value, but the value must be a string from a set of defined strings.

File names
Some values are file names.

Integers
Many stanza entries expect the value for the entry to be expressed as an integer.

Boolean values
Many stanza entries represent a Boolean value.

Parent topic: Access Manager Platform and Supporting Components administration

General guidelinesUse the following general guidelines when you change the configuration settings:configurationfilesgeneral guidelinesUse the config modify command in the pdadmin command-line interface to update configuration files for Security Access Manager. See "config modify" in the IBM Security Access Manager for Web: Command Reference for more information and instructions for using these commands. There is no order dependency or location dependency for stanzas in any configuration file.Stanza entries are marked as required or optional. When an entry is required, the entry must contain a valid key and value.Do not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results for the servers.Stanza entries and key names are case-sensitive. For example, usessl and UseSSL are treated as different entries.Spaces are not allowed for names of keys.For the key value pair format of key = value, the spaces that surround the equal sign (=) are not required. However, a good practice is to use spaces.Non-printable characters (such as tabs, carriage returns, and line feeds) that occur at the end of a stanza entry are ignored. Non-printable characters are ASCII characters with a decimal value less than 32.Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.

General guidelines

Use the following general guidelines when you change the configuration settings:

Use the config modify command in the pdadmin command-line interface to update configuration files for Security Access Manager. See "config modify" in the IBM Security Access Manager for Web: Command Reference for more information and instructions for using these commands.

There is no order dependency or location dependency for stanzas in any configuration file.

Stanza entries are marked as required or optional. When an entry is required, the entry must contain a valid key and value.

Do not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results for the servers.

Stanza entries and key names are case-sensitive. For example, usessl and UseSSL are treated as different entries.

Spaces are not allowed for names of keys.

For the key value pair format of key = value, the spaces that surround the equal sign (=) are not required. However, a good practice is to use spaces.

Non-printable characters (such as tabs, carriage returns, and line feeds) that occur at the end of a stanza entry are ignored. Non-printable characters are ASCII characters with a decimal value less than 32.

Parent topic: Guidelines for changing configuration files

Default valuesUse the following guidelines when changing default configuration settings:configurationfilesdefault valuesMany values are created or modified only with configuration programs. Do not manually edit these stanzas or values.Some values are filled in automatically during configuration. These values are needed for the initialization of the server after the configuration.The default values for a stanza entry might be different, depending on the server configuration. Some key value pairs are not applicable to certain servers and are omitted from the default configuration file for this server.Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.

Default values

Use the following guidelines when changing default configuration settings:

Many values are created or modified only with configuration programs. Do not manually edit these stanzas or values.

Some values are filled in automatically during configuration. These values are needed for the initialization of the server after the configuration.

The default values for a stanza entry might be different, depending on the server configuration. Some key value pairs are not applicable to certain servers and are omitted from the default configuration file for this server.

Parent topic: Guidelines for changing configuration files

StringsSome values accept a string value.configurationfilesstring valuesWhen you manually edit the configuration file, use the following guidelines to change configuration settings that require a string: String values are expected to be characters that are part of the local code set.Additional or different restrictions on the set of allowable string characters might be imposed. For example, many strings are restricted to ASCII characters. Consult each stanza entry description for any restrictions.Double quotation marks are sometimes, but not always, required when you use spaces or more than one word for values. Refer to the descriptions or examples for each stanza entry.The minimum and maximum lengths of user registry-related string values, if there are limits, are imposed by the underlying registry. For example, for Active Directory the maximum length is 256 alphanumeric characters.Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.

Strings

Some values accept a string value.

When you manually edit the configuration file, use the following guidelines to change configuration settings that require a string:

String values are expected to be characters that are part of the local code set.

Additional or different restrictions on the set of allowable string characters might be imposed. For example, many strings are restricted to ASCII characters. Consult each stanza entry description for any restrictions.

Double quotation marks are sometimes, but not always, required when you use spaces or more than one word for values. Refer to the descriptions or examples for each stanza entry.

The minimum and maximum lengths of user registry-related string values, if there are limits, are imposed by the underlying registry. For example, for Active Directory the maximum length is 256 alphanumeric characters.

Parent topic: Guidelines for changing configuration files

Defined stringsSome values accept a string value, but the value must be a string from a set of defined strings.configurationfilesdefined stringsWhen you manually edit the configuration file, make sure that the string value that you type matches a valid value of one of the defined strings.For example, the [aznapi-configuration] stanza section contains the following entry: mode = {local|remote}The value for mode is expected to be local or remote. Any other value is not valid and results in an error.Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.

Defined strings

Some values accept a string value, but the value must be a string from a set of defined strings.

When you manually edit the configuration file, make sure that the string value that you type matches a valid value of one of the defined strings.

For example, the [aznapi-configuration] stanza section contains the following entry:

mode = {local|remote}

The value for mode is expected to be local or remote. Any other value is not valid and results in an error.

Parent topic: Guidelines for changing configuration files

File namesSome values are file names.configurationfilesfile namesFor each stanza entry that expects a file name as a value, the description of the stanza entry specifies which of the following constructs are valid: FilenameNo directory path included.Relative filenameA directory path is allowed but not mandatory. These files typically are expected to be located relative to the location of a standard Security Access Manager directory. The stanza entry for each relative path name lists the root directory to which the file name is relative.Fully qualified absolute pathAn absolute directory path is required.Some stanza entries allow more than one of these choices.The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks (").Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.

File names

Some values are file names.

For each stanza entry that expects a file name as a value, the description of the stanza entry specifies which of the following constructs are valid:

Filename

No directory path included.

Relative filename

A directory path is allowed but not mandatory.

These files typically are expected to be located relative to the location of a standard Security Access Manager directory. The stanza entry for each relative path name lists the root directory to which the file name is relative.

Fully qualified absolute path

An absolute directory path is required.

Some stanza entries allow more than one of these choices.

The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks (").

Parent topic: Guidelines for changing configuration files

IntegersMany stanza entries expect the value for the entry to be expressed as an integer.configurationfilesinteger valuesWhen defining an entry with an integer, consider the following guidelines: Some stanza entries that take an integer value expect integer values within a valid range. The range is described in terms of a minimum value and a maximum value. For example, in the [ivmgrd] stanza, the max-notifier-thread stanza entry has a minimum value of 1 thread and a maximum value of 128 threads. For some entries, the integer value must be positive and the minimum value is 1. For other entries, a minimum integer value of 0 is allowed. Use caution when setting an integer value to 0, which might disable the function that is controlled by that stanza entry. For example, in the [ivacld] stanza, the entry tcp-req-port = 0 disables the port number. Or, an integer value of 0 might indicate that the number is unlimited. For example, in the [ldap] stanza, the entry max-search-size = 0 means that there is no limit to the maximum search size.For some entries that require integer values, Security Access Manager does not impose an upper limit for the maximum number allowed. For example, there is typically no maximum for timeout-related values, such as timeout = number in the [ldap] stanza. For this type of entry, the maximum number is limited only by the size of memory allocated for an integer data type. This number can vary, based on the type of operating system. For systems that allocate 4 bytes for an integer, this value is 2147483647. However, as the administrator, use a number that represents the value that is most logical for the value you are trying to set.Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.

Integers

Many stanza entries expect the value for the entry to be expressed as an integer.

When defining an entry with an integer, consider the following guidelines:

Some stanza entries that take an integer value expect integer values within a valid range. The range is described in terms of a minimum value and a maximum value.

For example, in the [ivmgrd] stanza, the max-notifier-thread stanza entry has a minimum value of 1 thread and a maximum value of 128 threads.

For some entries, the integer value must be positive and the minimum value is 1. For other entries, a minimum integer value of 0 is allowed.

Use caution when setting an integer value to 0, which might disable the function that is controlled by that stanza entry. For example, in the [ivacld] stanza, the entry tcp-req-port = 0 disables the port number. Or, an integer value of 0 might indicate that the number is unlimited. For example, in the [ldap] stanza, the entry max-search-size = 0 means that there is no limit to the maximum search size.

For some entries that require integer values, Security Access Manager does not impose an upper limit for the maximum number allowed. For example, there is typically no maximum for timeout-related values, such as timeout = number in the [ldap] stanza.

For this type of entry, the maximum number is limited only by the size of memory allocated for an integer data type. This number can vary, based on the type of operating system. For systems that allocate 4 bytes for an integer, this value is 2147483647.

However, as the administrator, use a number that represents the value that is most logical for the value you are trying to set.

Parent topic: Guidelines for changing configuration files

Boolean valuesMany stanza entries represent a Boolean value.configurationfilesBoolean valuesBooleanvaluesBooleanconfiguration file entriesBooleanstanza entriesSecurity Access Manager recognizes the Boolean values yes and no.Some of the entries in the configuration files are read by other servers and utilities. For example, many entries in the [ldap] stanza are read by the LDAP client. Some of these other programs recognize additional Boolean characters: yes or trueno or falseAnything other than yes|true, including a blank value, is interpreted as no|false.The recognized Boolean entries are listed for each stanza entry. Refer to the individual descriptions to determine when true or false are also recognized.Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files.

Boolean values

Many stanza entries represent a Boolean value.

Security Access Manager recognizes the Boolean values yes and no.

Some of the entries in the configuration files are read by other servers and utilities. For example, many entries in the [ldap] stanza are read by the LDAP client. Some of these other programs recognize additional Boolean characters:

yes or true

no or false

Anything other than yes|true, including a blank value, is interpreted as no|false.

The recognized Boolean entries are listed for each stanza entry. Refer to the individual descriptions to determine when true or false are also recognized.

Parent topic: Guidelines for changing configuration files

Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.configurationfilespd.confconfigurationfilesivacld.confconfigurationfilesivmgrd.confconfigurationfilesldap.confconfigurationfilesactivedir_ldap.confconfigurationfilesconfigurationfilespdaudit.server.confconfigurationfilespdaudit.pdmgr.confconfigurationfilespdaudit.pdacld.confconfigurationfilespdaudit.instance-webseald-host.confconfigurationfilespdaudit.webpi.confconfigurationfilespdaudit.appsvr.confconfigurationfilesaznAPI.confEach configuration file contains sections that are called stanzas.Server configuration files are ASCII text-based and contain stanza entries. Configuration files are processed only when the servers start. The following configuration files are currently used by Security Access Manager: pd.confThe configuration file that is used by the authentication server to configure the IBM Security Access Manager runtime. For details about the stanzas contained in this configuration file, see IBM Security Access Manager runtime configuration fileFor Security Access Manager servers, you must have the pd.conf configuration file..[instance-]ivacld.confThe configuration file that is used to configure an Security Access Manager authorization server instance. [instance-] represents the name of the specified authorization server instance. If an authorization server instance name contains an empty string, the configuration file is called ivacld.conf. For details about the stanzas contained in this configuration file, see Authorization server configuration fileWhen you use the Security Access Manager authorization server, you must have the [instance-]ivacld.conf server configuration file..ivmgrd.confThe configuration file that is used to configure the Security Access Manager policy server. For details about the stanzas contained in this configuration file, see Policy server configuration fileWhen you use the Security Access Manager policy server, you must have the ivmgrd.conf server configuration file..ldap.confThe configuration file that is used by the LDAP-based server to configure the LDAP-based user registry. For details about the stanzas that are contained in this configuration file, see LDAP server configuration fileWhen you use LDAP as the user registry for Security Access Manager, use the ldap.conf configuration file to customize the LDAP-based stanza entries..aznAPI.confA template configuration file that is used to configure any Security Access Manager resource manager. For details about the stanzas that are contained in this template file, see Resource manager configuration filesSecurity Access Manager provides a sample file that includes the more common configuration stanzas needed by resource managers..Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. Location of configuration filesIf you did not change the installation directories during Security Access Manager installation, the configuration files are in one of the following platform-specific directories:IBM Security Access Manager runtime configuration fileFor Security Access Manager servers, you must have the pd.conf configuration file.Authorization server configuration fileWhen you use the Security Access Manager authorization server, you must have the [instance-]ivacld.conf server configuration file.Policy server configuration fileWhen you use the Security Access Manager policy server, you must have the ivmgrd.conf server configuration file.LDAP server configuration fileWhen you use LDAP as the user registry for Security Access Manager, use the ldap.conf configuration file to customize the LDAP-based stanza entries.LDAP client with Active Directory server configuration fileWhen you use an LDAP client to retrieve data for the Active Directory user registry to which the Security Access Manager policy server is configured, you must have the activedir_ldap.conf configuration file.Resource manager configuration filesSecurity Access Manager provides a sample file that includes the more common configuration stanzas needed by resource managers.

Configuration file reference

The way you use configuration files controls the operation of the Security Access Manager servers.

Each configuration file contains sections that are called stanzas.

Server configuration files are ASCII text-based and contain stanza entries. Configuration files are processed only when the servers start. The following configuration files are currently used by Security Access Manager:

pd.conf

The configuration file that is used by the authentication server to configure the IBM Security Access Manager runtime. For details about the stanzas contained in this configuration file, see IBM Security Access Manager runtime configuration file.

[instance-]ivacld.conf

The configuration file that is used to configure an Security Access Manager authorization server instance. [instance-] represents the name of the specified authorization server instance. If an authorization server instance name contains an empty string, the configuration file is called ivacld.conf. For details about the stanzas contained in this configuration file, see Authorization server configuration file.

ivmgrd.conf

The configuration file that is used to configure the Security Access Manager policy server. For details about the stanzas contained in this configuration file, see Policy server configuration file.

ldap.conf

The configuration file that is used by the LDAP-based server to configure the LDAP-based user registry. For details about the stanzas that are contained in this configuration file, see LDAP server configuration file.

aznAPI.conf

A template configuration file that is used to configure any Security Access Manager resource manager. For details about the stanzas that are contained in this template file, see Resource manager configuration files.

Location of configuration files
If you did not change the installation directories during Security Access Manager installation, the configuration files are in one of the following platform-specific directories:

IBM Security Access Manager runtime configuration file
For Security Access Manager servers, you must have the pd.conf configuration file.

Authorization server configuration file
When you use the Security Access Manager authorization server, you must have the [instance-]ivacld.conf server configuration file.

Policy server configuration file
When you use the Security Access Manager policy server, you must have the ivmgrd.conf server configuration file.

LDAP server configuration file
When you use LDAP as the user registry for Security Access Manager, use the ldap.conf configuration file to customize the LDAP-based stanza entries.

LDAP client with Active Directory server configuration file
When you use an LDAP client to retrieve data for the Active Directory user registry to which the Security Access Manager policy server is configured, you must have the activedir_ldap.conf configuration file.

Resource manager configuration files
Security Access Manager provides a sample file that includes the more common configuration stanzas needed by resource managers.

Parent topic: Access Manager Platform and Supporting Components administration

Location of configuration filesIf you did not change the installation directories during Security Access Manager installation, the configuration files are in one of the following platform-specific directories:configurationfilesdefault locationfilesdefault locationAIX, Linux, and Solaris operating systems/opt/PolicyDirector/etcWindows operating systemsc:\program files\tivoli\policy director\etcIf you did not change the installation directories while installing the common audit service, the templates for the configuration files are located in one of the following platform-specific directories: AIX, Linux, and Solaris operating systems/opt/PolicyDirector/etc/auditWindows operating systemsc:\program files\tivoli\policy director\etc\auditConfiguration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.

Location of configuration files

If you did not change the installation directories during Security Access Manager installation, the configuration files are in one of the following platform-specific directories:

AIX, Linux, and Solaris operating systems

/opt/PolicyDirector/etc

Windows operating systems

c:\program files\tivoli\policy director\etc

If you did not change the installation directories while installing the common audit service, the templates for the configuration files are located in one of the following platform-specific directories:

AIX, Linux, and Solaris operating systems

/opt/PolicyDirector/etc/audit

Windows operating systems

c:\program files\tivoli\policy director\etc\audit

Parent topic: Configuration file reference

IBM Security Access Manager runtime configuration fileFor Security Access Manager servers, you must have the pd.conf configuration file.runtimepd.confruntimeconfiguration fileconfigurationfilesruntimeconfigurationfilespd.conffilesconfigurationfilesruntimepd.conf configuration fileUse this configuration file to automate server startup, to indicate whether the IBM Security Access Manager runtime is configured, and specify information about the user registry.Stanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.This configuration file can include the following stanzas: [meta-info][pdrte][ssl][manager]The unconfiguration of the server with the pd.conf configuration file also queries information from this configuration file.Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.

IBM Security Access Manager runtime configuration file

For Security Access Manager servers, you must have the pd.conf configuration file.

Use this configuration file to automate server startup, to indicate whether the IBM Security Access Manager runtime is configured, and specify information about the user registry.

Stanza entries for automating server startup are in the [pdrte] stanza of the pd.conf configuration file.

This configuration file can include the following stanzas:

[meta-info]

[pdrte]

[ssl]

[manager]

The unconfiguration of the server with the pd.conf configuration file also queries information from this configuration file.

Parent topic: Configuration file reference

Authorization server configuration fileWhen you use the Security Access Manager authorization server, you must have the [instance-]ivacld.conf server configuration file.authorizationserverivacld.confauthorizationserverconfiguration fileconfigurationfilesauthorization serverconfigurationfilesivacld.confivacld.conf configuration filefilesauthorization serverfilesivacld.confUse this configuration file to customize the operation of each authorization server.This configuration file can include the following stanzas: [meta-info][ivacld][ldap][ssl][manager][aznapi-configuration][xmladi-attribute-definitions][aznapi-entitlement-services][aznapi-external-authzn-services][aznapi-pac-services][aznapi-cred-modification-services][aznapi-admin-services][configuration-database]The unconfiguration of the server with the [instance-]ivacld.conf configuration file also queries information from this configuration file.[instance-] represents the name of the specified authorization server instance. If an authorization server instance name contains an empty string, the configuration file is called ivacld.conf.Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.

Authorization server configuration file

When you use the Security Access Manager authorization server, you must have the [instance-]ivacld.conf server configuration file.

Use this configuration file to customize the operation of each authorization server.

This configuration file can include the following stanzas:

[meta-info]

[ivacld]

[ldap]

[ssl]

[manager]

[aznapi-configuration]

[xmladi-attribute-definitions]

[aznapi-entitlement-services]

[aznapi-external-authzn-services]

[aznapi-pac-services]

[aznapi-cred-modification-services]

[aznapi-admin-services]

[configuration-database]

The unconfiguration of the server with the [instance-]ivacld.conf configuration file also queries information from this configuration file.

Note: [instance-] represents the name of the specified authorization server instance. If an authorization server instance name contains an empty string, the configuration file is called ivacld.conf.

Parent topic: Configuration file reference

Policy server configuration filePolicy server configuration fileWhen you use the Security Access Manager policy server, you must have the ivmgrd.conf server configuration file.policy serverivmgrd.confpolicy serverconfiguration fileconfigurationfilespolicy serverconfigurationfilesivmgrd.confivmgrd.conf configuration filefilespolicy serverfilesivmgrd.confUse this configuration file to customize the operation of each policy server.This configuration file can include the following stanzas: [meta-info][ivmgrd][ldap][ssl][aznapi-configuration][xmladi-attribute-definitions][aznapi-entitlement-services][aznapi-pac-services][aznapi-cred-modification-services][aznapi-external-authzn-services][delegated-admin][configuration-database][domains][domain=domain_name]The unconfiguration of the server with the ivmgrd.conf configuration file also queries information from this configuration file.Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.

Policy server configuration file

When you use the Security Access Manager policy server, you must have the ivmgrd.conf server configuration file.

Use this configuration file to customize the operation of each policy server.

This configuration file can include the following stanzas:

[meta-info]

[ivmgrd]

[ldap]

[ssl]

[aznapi-configuration]

[xmladi-attribute-definitions]

[aznapi-entitlement-services]

[aznapi-pac-services]

[aznapi-cred-modification-services]

[aznapi-external-authzn-services]

[delegated-admin]

[configuration-database]

[domains]

[domain=domain_name]

The unconfiguration of the server with the ivmgrd.conf configuration file also queries information from this configuration file.

Parent topic: Configuration file reference

LDAP server configuration fileWhen you use LDAP as the user registry for Security Access Manager, use the ldap.conf configuration file to customize the LDAP-based stanza entries.LDAPserverldap.confuserregistriesLDAP serverconfigurationfilesLDAP serverconfigurationfilesldap.conffilesLDAP serverfilesldap.confldap.conf configuration fileThis configuration file includes the following stanzas: [ldap][meta-info]stanzasldap-generic-general (internal use)stanzasldap-generic-pwd-change-error-map (internal use)stanzasldap-generic-acls (internal use)ldap-generic-general (internal use)ldap-generic-pwd-change-error-map (internal use)ldap-generic-acls (internal use)The ldap.conf configuration file contains the following stanzas that contain entries that are for internal use only: [ldap-generic-general][ldap-generic-pwd-change-error-map][ldap-generic-acls]Do not modify any of the values that are defined in these stanzas.Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.

LDAP server configuration file

When you use LDAP as the user registry for Security Access Manager, use the ldap.conf configuration file to customize the LDAP-based stanza entries.

This configuration file includes the following stanzas:

[ldap]

[meta-info]

Note: The ldap.conf configuration file contains the following stanzas that contain entries that are for internal use only:

[ldap-generic-general]

[ldap-generic-pwd-change-error-map]

[ldap-generic-acls]

Do not modify any of the values that are defined in these stanzas.

Parent topic: Configuration file reference

LDAP client with Active Directory server configuration fileWhen you use an LDAP client to retrieve data for the Active Directory user registry to which the Security Access Manager policy server is configured, you must have the activedir_ldap.conf configuration file.Active Directory serverconfiguration file with LDAP clientLDAPclientactivedir_ldap.confuserregistriesActive Directory with LDAP clientconfigurationfilesLDAP client with Active Directory serverLDAPclientwith Active Directory serverconfigurationfilesactivedir_ldap.conffilesLDAP client with Active Directory serverfilesactivedir_ldap.confactivedir_ldap.conf configuration fileUse this configuration file to customize the operation of each Active Directory user registry.For example, you might have multiple platforms where the policy server is configured to use the Active Directory user registry. Other blades, such as WebSEAL on one platform, and the authorization server are configured to use the LDAP client to retrieve data from that Active Directory user registry on another platform.This configuration file can include the following stanzas:[meta-info]Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.

LDAP client with Active Directory server configuration file

When you use an LDAP client to retrieve data for the Active Directory user registry to which the Security Access Manager policy server is configured, you must have the activedir_ldap.conf configuration file.

Use this configuration file to customize the operation of each Active Directory user registry.

For example, you might have multiple platforms where the policy server is configured to use the Active Directory user registry. Other blades, such as WebSEAL on one platform, and the authorization server are configured to use the LDAP client to retrieve data from that Active Directory user registry on another platform.

This configuration file can include the following stanzas:

[meta-info]

Parent topic: Configuration file reference

Resource manager configuration filesSecurity Access Manager provides a sample file that includes the more common configuration stanzas needed by resource managers.resourcemanageraznAPI.confresourcemanagerconfiguration fileconfigurationfilesresource managersconfigurationfilesaznAPI.conffilesresource managersfilesaznAPI.confaznAPI.conf configuration fileYour documentation sources, when implementing your own plug-in or security-enhanced application, include the Authorization Java Classes Developer Reference.When creating your own security resource manager or extending the functions provided by Security Access Manager, you can use the aznAPI.conf configuration file. This configuration file can include the following stanzas: [aznapi-configuration][xmladi-attribute-definitions][ssl][ldap][aznapi-entitlement-services][aznapi-pac-services][aznapi-cred-modification-services][aznapi-external-authzn-services][aznapi-admin-services][manager]Configuration file referenceThe way you use configuration files controls the operation of the Security Access Manager servers.

Resource manager configuration files

Security Access Manager provides a sample file that includes the more common configuration stanzas needed by resource managers.

Your documentation sources, when implementing your own plug-in or security-enhanced application, include the Authorization Java Classes Developer Reference.

When creating your own security resource manager or extending the functions provided by Security Access Manager, you can use the aznAPI.conf configuration file.

This configuration file can include the following stanzas:

[aznapi-configuration]

[xmladi-attribute-definitions]

[ssl]

[ldap]

[aznapi-entitlement-services]

[aznapi-pac-services]

[aznapi-cred-modification-services]

[aznapi-external-authzn-services]

[aznapi-admin-services]

[manager]

Parent topic: Configuration file reference

Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].configurationstanzasstanzasgeneral formatstanzaslabelsstanzaskey-value pairFor example, the [ssl] stanza in the ivmgrd.conf configuration file defines the Secure Sockets Layer (SSL) configuration settings for the policy server. The [ldap] stanza defines the configuration settings that are required by the policy server to communicate with an LDAP-based user registry.Each stanza in a Security Access Manager configuration file contains one or more key value pairs. The pairs contain information that is expressed as a paired set of parameters. Each stanza entry is a key-value pair in the following format: key = valueDo not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results in the servers. Spaces surrounding the equal sign (=) are typically used, but are not required.The initial installation of Security Access Manager establishes many of the default values. Some values are static and never change; other values can be modified to customize server functionality and performance.The following stanza descriptions provide a list of the valid stanza entries. Each stanza entry consists of key value pairs. Each stanza entry includes a description of its default behavior, when applicable.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. [aznapi-admin-services] stanzaAn administration service plug-in enables applications to do application-specific administration tasks.[aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.[aznapi-cred-modification-services] stanzaA credential modification service plug-in enables authorization API applications to do modifications on a Security Access Manager credential.[aznapi-entitlement-services] stanzaAn entitlement services plug-in enables authorization API applications to retrieve the entitlements for a user from an entitlements repository.[aznapi-external-authzn-services] stanzaAn external authorization service plug-in is an optional extension of the Security Access Manager authorization service that you can use to impose additional authorization controls and conditions.[aznapi-pac-services] stanzaA PAC services plug-in gives authorization API applications the ability to move Security Access Manager credentials back and forth between the native Security Access Manager credentials format and an alternate format called privilege attribute certificate (PAC).[configuration-database] stanzaThe stanza entry defines the name and location of the Security Access Manager obfuscated password configuration file.[delegated-admin] stanzaThe Security Access Manager configuration can require that the user is authorized to view each group that is returned in the group list. Or, the user can be authorized to return the list without authorizing first.[domains] and [domain=domain_name] stanzasThe [domains] stanza contains a list of domains.[ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file: [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:[ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.[ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.[manager] stanzaThe stanza entries for configuring the master server settings are in the [manager] stanza of each of the following configuration files:[meta-info] stanzaThe stanza entry for configuring Security Access Manager version information is in the [meta-info] stanza of each of the following configuration files:[pdconfig] stanzaThis stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.[pdaudit-filter] stanzaThe stanza entry for Security Access Manager auditing support is in the [pdaudit-filter] stanza of the pdaudit.conf configuration file.[pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.[ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.[xmladi-attribute-definitions] stanzaThe stanza entries for configuring the Access Decision Information Extensible Markup Language (ADI XML) document attribute definitions are in the [xmladi-attribute-definitions] stanza.

Configuration file stanza reference

Within configuration files, stanza labels occur within brackets, such as [stanza-name].

For example, the [ssl] stanza in the ivmgrd.conf configuration file defines the Secure Sockets Layer (SSL) configuration settings for the policy server. The [ldap] stanza defines the configuration settings that are required by the policy server to communicate with an LDAP-based user registry.

Each stanza in a Security Access Manager configuration file contains one or more key value pairs. The pairs contain information that is expressed as a paired set of parameters. Each stanza entry is a key-value pair in the following format:

key = value

Do not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results in the servers. Spaces surrounding the equal sign (=) are typically used, but are not required.

The initial installation of Security Access Manager establishes many of the default values. Some values are static and never change; other values can be modified to customize server functionality and performance.

The following stanza descriptions provide a list of the valid stanza entries. Each stanza entry consists of key value pairs. Each stanza entry includes a description of its default behavior, when applicable.

[aznapi-admin-services] stanza
An administration service plug-in enables applications to do application-specific administration tasks.

[aznapi-configuration] stanza
Security Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

[aznapi-cred-modification-services] stanza
A credential modification service plug-in enables authorization API applications to do modifications on a Security Access Manager credential.

[aznapi-entitlement-services] stanza
An entitlement services plug-in enables authorization API applications to retrieve the entitlements for a user from an entitlements repository.

[aznapi-external-authzn-services] stanza
An external authorization service plug-in is an optional extension of the Security Access Manager authorization service that you can use to impose additional authorization controls and conditions.

[aznapi-pac-services] stanza
A PAC services plug-in gives authorization API applications the ability to move Security Access Manager credentials back and forth between the native Security Access Manager credentials format and an alternate format called privilege attribute certificate (PAC).

[configuration-database] stanza
The stanza entry defines the name and location of the Security Access Manager obfuscated password configuration file.

[delegated-admin] stanza
The Security Access Manager configuration can require that the user is authorized to view each group that is returned in the group list. Or, the user can be authorized to return the list without authorizing first.

[domains] and [domain=domain_name] stanzas
The [domains] stanza contains a list of domains.

[ivacld] stanza
The stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

[ivmgrd] stanza
The stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

[ldap] stanza
This stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

[ldap] stanza for ldap.conf
This stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

[manager] stanza
The stanza entries for configuring the master server settings are in the [manager] stanza of each of the following configuration files:

[meta-info] stanza
The stanza entry for configuring Security Access Manager version information is in the [meta-info] stanza of each of the following configuration files:

[pdconfig] stanza
This stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

[pdaudit-filter] stanza
The stanza entry for Security Access Manager auditing support is in the [pdaudit-filter] stanza of the pdaudit.conf configuration file.

[pdrte] stanza
When the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

[ssl] stanza
The [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

[xmladi-attribute-definitions] stanza
The stanza entries for configuring the Access Decision Information Extensible Markup Language (ADI XML) document attribute definitions are in the [xmladi-attribute-definitions] stanza.

Parent topic: Access Manager Platform and Supporting Components administration

[aznapi-admin-services] stanzaAn administration service plug-in enables applications to do application-specific administration tasks.aznapi-admin-services stanzadescriptionstanzasaznapi-admin-servicesThe administration service plug-in is accessed by a calling application with one of the Security Access Manager administration interfaces.The calling application can be an administrative utility such as the Web Portal Manager or pdadmin utility. The calling application can be a custom-built application that uses the Security Access Manager administration APIs.The administration service maps the administration API calls to the corresponding administration service API calls and carries out the requested action. Each administration service plug-in is a stand-alone module that is dynamically loaded into the authorization service.The parameters for configuring Security Access Manager administration service plug-ins are declared in the [aznapi-admin-services] stanza of these configuration files provided by Security Access Manager: The ivmgrd.conf configuration file for the policy serverThe [instance-]ivacld.conf configuration file for the authorization serverThe configuration files for the configured administration service plug-ins for your resource managers The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].service-idThis stanza entry defines the authorization API service for functions that enable a plug-in to obtain the contents of a defined portion of the protected object hierarchy. Service functions can also enable a plug-in to define application-specific administration tasks that also return commands that do those tasks.

[aznapi-admin-services] stanza

An administration service plug-in enables applications to do application-specific administration tasks.

The administration service plug-in is accessed by a calling application with one of the Security Access Manager administration interfaces.

The calling application can be an administrative utility such as the Web Portal Manager or pdadmin utility. The calling application can be a custom-built application that uses the Security Access Manager administration APIs.

The administration service maps the administration API calls to the corresponding administration service API calls and carries out the requested action. Each administration service plug-in is a stand-alone module that is dynamically loaded into the authorization service.

The parameters for configuring Security Access Manager administration service plug-ins are declared in the [aznapi-admin-services] stanza of these configuration files provided by Security Access Manager:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

The configuration files for the configured administration service plug-ins for your resource managers

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

service-id
This stanza entry defines the authorization API service for functions that enable a plug-in to obtain the contents of a defined portion of the protected object hierarchy. Service functions can also enable a plug-in to define application-specific administration tasks that also return commands that do those tasks.

Parent topic: Configuration file stanza reference

service-idThis stanza entry defines the authorization API service for functions that enable a plug-in to obtain the contents of a defined portion of the protected object hierarchy. Service functions can also enable a plug-in to define application-specific administration tasks that also return commands that do those tasks.service-id entryaznapi-admin-services stanzaentriesservice-idaznapi-admin-services stanzaservice-id entrySyntax service-id = {short_name|path_to_dll} [-pobj protected_object_hierarchy_name ] [& params] Description Defines the authorization API service for functions that enable a plug-in to obtain the contents of a defined portion of the protected object hierarchy. Service functions can also enable a plug-in to define application-specific administration tasks that also return commands that do those tasks. Each stanza entry defines different types of aznAPI service. Options Each entry has the following format. service-idDeveloper-specified ID of the administration service. An authorization API application can register more than one administration service plug-in, but each must have a unique service ID.short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executable code for the service. If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is added as a prefix and appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short name of azn_ent_user, the following names are automatically searched for on each platform: AIX libazn_ent_user.so libazn_ent_user.a Linuxlibazn_ent_user.soSolarislibazn_ent_user.soWindowsazn_ent_user.dllprotected_object_hierarchy_nameOptional: The name of the protected object hierarchy. This option refers either to the name of a protected object space (hierarchy) or to a protected object. Protected object hierarchy names must be unique for each administration service plug-in within the scope of an authorization API application. To support failover, multiple authorization API application instances can be registered to service the same protected object hierarchy names. Failover support allows for the administration of an object space if a particular authorization API application server fails.paramsOptional: The additional initialization arguments that can be passed to the external authorization service. The arguments must be preceded by the ampersand (&); for example, & -server fred. The authorization service does not process the characters after the ampersand. It passes these characters directly to the administration service plug-in. The service definition is described in more detail in the Authorization C API Developer Reference. Usage Optional Default value There is no default value. Example AZN_ADMIN_SVC_TRACE = pdtraceadmin [aznapi-admin-services] stanzaAn administration service plug-in enables applications to do application-specific administration tasks.

service-id

This stanza entry defines the authorization API service for functions that enable a plug-in to obtain the contents of a defined portion of the protected object hierarchy. Service functions can also enable a plug-in to define application-specific administration tasks that also return commands that do those tasks.

Syntax

service-id = {short_name|path_to_dll}
     [-pobj protected_object_hierarchy_name ] [& params]

Description

Defines the authorization API service for functions that enable a plug-in to obtain the contents of a defined portion of the protected object hierarchy. Service functions can also enable a plug-in to define application-specific administration tasks that also return commands that do those tasks.

Each stanza entry defines different types of aznAPI service.

Options

Each entry has the following format.

service-id

Developer-specified ID of the administration service. An authorization API application can register more than one administration service plug-in, but each must have a unique service ID.

short_name|path_to_dll

The path to the dynamic link library (DLL) that contains the executable code for the service.

If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is added as a prefix and appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short name of azn_ent_user, the following names are automatically searched for on each platform:

AIX®

libazn_ent_user.so

libazn_ent_user.a

Linux

libazn_ent_user.so

Solaris

libazn_ent_user.so

Windows

azn_ent_user.dll

protected_object_hierarchy_name

Optional: The name of the protected object hierarchy. This option refers either to the name of a protected object space (hierarchy) or to a protected object. Protected object hierarchy names must be unique for each administration service plug-in within the scope of an authorization API application. To support failover, multiple authorization API application instances can be registered to service the same protected object hierarchy names. Failover support allows for the administration of an object space if a particular authorization API application server fails.

params

Optional: The additional initialization arguments that can be passed to the external authorization service. The arguments must be preceded by the ampersand (&); for example, & -server fred. The authorization service does not process the characters after the ampersand. It passes these characters directly to the administration service plug-in. The service definition is described in more detail in the Authorization C API Developer Reference.

Usage

Optional

Default value

There is no default value.

Example

AZN_ADMIN_SVC_TRACE = pdtraceadmin

Parent topic: [aznapi-admin-services] stanza

[aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.stanzasaznapi-configurationaznapi-configuration stanzadescriptionThe standards-based authorization API allows applications to make calls to the centralized authorization service. Security Access Manager provides built-in support of user name and password authentication as well through the authorization API.The configuration key value pairs that are used for configuring audit files for Security Access Manager servers are in the [aznapi-configuration] stanza of each of the following configuration files: The ivmgrd.conf configuration file for the policy serverThe [instance-]ivacld.conf configuration file for the authorization serverThe pdmgrproxyd.conf configuration file for the policy proxy serverThe configuration files for your resource managers Other stanza entries that apply to the configuration files of your resource managers are described in the Authorization C API Developer Reference. Read and thoroughly understand these concepts so that they can provide the required standard functions. A sample aznAPI.conf configuration file is provided with Security Access Manager to use as a guide for creating your own resource manager configuration file.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].audit-attributeThis stanza entry specifies the name of the access decision information (ADI) attribute to audit.azn-app-hostThis stanza entry specifies the host name that the policy server uses when communicating with the resource manager.azn-server-nameThis stanza entry specifies the unique name of the Security Access Manager resource manager, authorization server, or policy server, that is configured into the domain.cache-refresh-intervalThis stanza entry specifies the poll interval (in seconds) between checks for updates to the master policy database.cred-attributes-entitlement-servicesThis stanza entry specifies the service that you can use to add external information to the user credential. The addition is in the form of credential attributes and allows applications to use that information in making access decisions.db-fileThis stanza entry specifies the name and location of the resource manager policy database cache file. dynamic-adi-entitlement-servicesThis stanza entry specifies the dynamic access decision information (ADI) retrieval entitlement service.input-adi-xml-prologThis stanza entry specifies the prolog to be added to the top of the XML document. This document is created with the Access Decision Information (ADI) needed to evaluate a Boolean authorization rule.listen-flagsThis stanza entry specifies whether the reception of policy cache update notifications is on or off.logcfgThis stanza entry enables logging and auditing for the application. modeThis stanza entry specifies the operating mode for the resource manager.pd-user-nameThis stanza entry specifies the Security Access Manager user account for the resource manager server.pd-user-pwdThis stanza entry specifies the Security Access Manager user account password for the resource manager.permission-info-returnedThis stanza entry specifies the set of attributes that the caller wants to receive from the azn_decision_access_allowed_ext() function in the permission information attribute list.policy-cache-sizeThis stanza entry specifies the maximum size of the in-memory policy cache.resource-manager-provided-adiThis stanza entry specifies the prefix that the authorization engine uses to determine the set of missing access decision information (ADI) provided by the resource manager.xsl-stylesheet-prologThis stanza entry specifies the prolog to be added to the top of the XSL style sheet with the XSL text that defines a Boolean authorization rule.

[aznapi-configuration] stanza

Security Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

The standards-based authorization API allows applications to make calls to the centralized authorization service. Security Access Manager provides built-in support of user name and password authentication as well through the authorization API.

The configuration key value pairs that are used for configuring audit files for Security Access Manager servers are in the [aznapi-configuration] stanza of each of the following configuration files:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

The pdmgrproxyd.conf configuration file for the policy proxy server

The configuration files for your resource managers

Other stanza entries that apply to the configuration files of your resource managers are described in the Authorization C API Developer Reference. Read and thoroughly understand these concepts so that they can provide the required standard functions. A sample aznAPI.conf configuration file is provided with Security Access Manager to use as a guide for creating your own resource manager configuration file.

audit-attribute
This stanza entry specifies the name of the access decision information (ADI) attribute to audit.

azn-app-host
This stanza entry specifies the host name that the policy server uses when communicating with the resource manager.

azn-server-name
This stanza entry specifies the unique name of the Security Access Manager resource manager, authorization server, or policy server, that is configured into the domain.

cache-refresh-interval
This stanza entry specifies the poll interval (in seconds) between checks for updates to the master policy database.

cred-attributes-entitlement-services
This stanza entry specifies the service that you can use to add external information to the user credential. The addition is in the form of credential attributes and allows applications to use that information in making access decisions.

db-file
This stanza entry specifies the name and location of the resource manager policy database cache file.

dynamic-adi-entitlement-services
This stanza entry specifies the dynamic access decision information (ADI) retrieval entitlement service.

input-adi-xml-prolog
This stanza entry specifies the prolog to be added to the top of the XML document. This document is created with the Access Decision Information (ADI) needed to evaluate a Boolean authorization rule.

listen-flags
This stanza entry specifies whether the reception of policy cache update notifications is on or off.

logcfg
This stanza entry enables logging and auditing for the application.

mode
This stanza entry specifies the operating mode for the resource manager.

pd-user-name
This stanza entry specifies the Security Access Manager user account for the resource manager server.

pd-user-pwd
This stanza entry specifies the Security Access Manager user account password for the resource manager.

permission-info-returned
This stanza entry specifies the set of attributes that the caller wants to receive from the azn_decision_access_allowed_ext() function in the permission information attribute list.

policy-cache-size
This stanza entry specifies the maximum size of the in-memory policy cache.

resource-manager-provided-adi
This stanza entry specifies the prefix that the authorization engine uses to determine the set of missing access decision information (ADI) provided by the resource manager.

xsl-stylesheet-prolog
This stanza entry specifies the prolog to be added to the top of the XSL style sheet with the XSL text that defines a Boolean authorization rule.

Parent topic: Configuration file stanza reference

audit-attributeThis stanza entry specifies the name of the access decision information (ADI) attribute to audit.audit-attribute entryentriesaudit-attributeaznapi-configuration stanzaaudit-attribute entrySyntax audit-attribute = azn-attr Description Name of the access decision information (ADI) attribute to audit. An attribute can establish accountability by providing information to help identify potentially inappropriate access of assets. You can grant or deny access based on the rules that are applied to attributes. For example, the WebSEAL switch-user authentication feature provides a mechanism to allow certain users to impersonate another user. When switch-user is used, an authorization request is evaluated against an assumed identity rather than the actual identity of the user. It is desirable to allow administrators to capture the user's actual identity. You can audit the names or descriptions of the Security Access Manager policies (ACL, POP, and authorization rule) that are applied to the object that is accessed. Options azn_attrThe authorization API attribute represents an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Usage Optional Default value There is no default value. Example The following example shows the configuration for WebSEAL: audit-attribute = tagvalue_su-admin [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

audit-attribute

This stanza entry specifies the name of the access decision information (ADI) attribute to audit.

Syntax

audit-attribute = azn-attr

Description

Name of the access decision information (ADI) attribute to audit. An attribute can establish accountability by providing information to help identify potentially inappropriate access of assets. You can grant or deny access based on the rules that are applied to attributes.

For example, the WebSEAL switch-user authentication feature provides a mechanism to allow certain users to impersonate another user. When switch-user is used, an authorization request is evaluated against an assumed identity rather than the actual identity of the user. It is desirable to allow administrators to capture the user's actual identity.

You can audit the names or descriptions of the Security Access Manager policies (ACL, POP, and authorization rule) that are applied to the object that is accessed.

Options

azn_attr

The authorization API attribute represents an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.

Usage

Optional

Default value

There is no default value.

Example

The following example shows the configuration for WebSEAL:

audit-attribute = tagvalue_su-admin

Parent topic: [aznapi-configuration] stanza

azn-app-hostThis stanza entry specifies the host name that the policy server uses when communicating with the resource manager.azn-app-host entryentriesazn-app-hostaznapi-configuration stanzaazn-app-host entrySyntax azn-app-host = other_hostname Description Attribute that is used to specify the host name that the policy server uses when communicating with the resource manager. Options For other_hostname, you can provide any valid internet host name. If this attribute is not specified, the default host name is used. Examples of valid host names: mycomputer.city.company.com mycomputer By default, this attribute is disabled. When disabled, the stanza entry is commented out by using a pound sign (#) at the beginning of the stanza entry. The following example shows a commented out entry: #azn-app-host = libra To enable this value, uncomment the entry by removing the pound sign. Be sure to include a host name value. Usage Optional Default value There is no default value. Example azn-app-host = libra.dallas.ibm.com [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

azn-app-host

This stanza entry specifies the host name that the policy server uses when communicating with the resource manager.

Syntax

azn-app-host = other_hostname

Description

Attribute that is used to specify the host name that the policy server uses when communicating with the resource manager.

Options

For other_hostname, you can provide any valid internet host name. If this attribute is not specified, the default host name is used. Examples of valid host names:

mycomputer.city.company.com

mycomputer

By default, this attribute is disabled. When disabled, the stanza entry is commented out by using a pound sign (#) at the beginning of the stanza entry. The following example shows a commented out entry:

#azn-app-host = libra

To enable this value, uncomment the entry by removing the pound sign. Be sure to include a host name value.

Usage

Optional

Default value

There is no default value.

Example

azn-app-host = libra.dallas.ibm.com

Parent topic: [aznapi-configuration] stanza

azn-server-nameThis stanza entry specifies the unique name of the Security Access Manager resource manager, authorization server, or policy server, that is configured into the domain.azn-server-name entryentriesazn-server-nameaznapi-configuration stanzaazn-server-name entrySyntax azn-server-name = server–hostname Description Unique name of the Security Access Manager resource manager, authorization server, or policy server, that is configured into the domain. The hyphen (-) character is required. The host name is generated and set during configuration. Do not edit this stanza entry. [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

azn-server-name

This stanza entry specifies the unique name of the Security Access Manager resource manager, authorization server, or policy server, that is configured into the domain.

Syntax

azn-server-name = server–hostname

Description

Unique name of the Security Access Manager resource manager, authorization server, or policy server, that is configured into the domain. The hyphen (-) character is required.

Note: The host name is generated and set during configuration. Do not edit this stanza entry.

Parent topic: [aznapi-configuration] stanza

cache-refresh-intervalThis stanza entry specifies the poll interval (in seconds) between checks for updates to the master policy database.cache-refresh-interval entryentriescache-refresh-intervalaznapi-configuration stanzacache-refresh-interval entrySyntax cache-refresh-interval = {disable|default|number_seconds} Description Poll interval (in seconds) between checks for updates to the master policy database. The local cache is rebuilt only if an update is detected. This stanza entry is not used in the ivmgrd.conf file. Options disableThe interval value in seconds is not set.defaultThe default value of 600 seconds is used.number_secondsThe exact time interval in number of seconds. This value is between 0 and the size of an unsigned integer. The unsigned integer is approximately 136 years. Usage Optional Default value default Example cache-refresh-interval = 500 [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

cache-refresh-interval

This stanza entry specifies the poll interval (in seconds) between checks for updates to the master policy database.

Syntax

cache-refresh-interval = {disable|default|number_seconds}

Description

Poll interval (in seconds) between checks for updates to the master policy database.

Note: The local cache is rebuilt only if an update is detected.

This stanza entry is not used in the ivmgrd.conf file.

Options

disable

The interval value in seconds is not set.

default

The default value of 600 seconds is used.

number_seconds

The exact time interval in number of seconds. This value is between 0 and the size of an unsigned integer. The unsigned integer is approximately 136 years.

Usage

Optional

Default value

default

Example

cache-refresh-interval = 500

Parent topic: [aznapi-configuration] stanza

cred-attributes-entitlement-servicesThis stanza entry specifies the service that you can use to add external information to the user credential. The addition is in the form of credential attributes and allows applications to use that information in making access decisions.cred-attributes-entitlement-services entryentriescred-attributes-entitlement-servicesaznapi-configuration stanzacred-attributes-entitlement-services entrySyntax cred-attributes-entitlement-services = {short_name_entitlement_service|path_to_dll} Description Service that you can use to add external information to the user credential in the form of credential attributes. The addition allows applications to use that information in making access decisions. These extended attributes are stored in the user registry. This service can also work with attributes with an API call. A list of authorization API entitlement service IDs are queried by the azn_id_get_creds() interface. The query compiles a list of attributes to be added to the user credential while the credential is being built. A list of service identifiers, which can be found within the [aznapi-entitlement-services] stanza, is queried to compile a list of attributes. The attributes are added to the user credential while the credential is being built. Each service ID is queried in the order it is declared in the list. The attribute returned is inserted into the credential attribute list of each credential that is built. The following example shows two entries from the credential attribute list: cred-attribute-entitlement-services = myEntSvcID cred-attribute-entitlement-services = myOtherEntSvcID You cannot use this stanza entry to override read-only attributes in the credential attribute list that include the principal name, principal UUID, and others. The exception to this rule is for the azn_cred_groups attribute. The Authorization C API Developer Reference lists the read-only attributes and contains more information about this service. The document explains why administrators who do not want this capability must ensure that the azn_mod_rad service is not loaded by the application. Usage Optional Default value There is no default value. Example cred-attribute-entitlement-services = myEntSvcID [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

cred-attributes-entitlement-services

This stanza entry specifies the service that you can use to add external information to the user credential. The addition is in the form of credential attributes and allows applications to use that information in making access decisions.

Syntax

cred-attributes-entitlement-services =
     {short_name_entitlement_service|path_to_dll}

Description

Service that you can use to add external information to the user credential in the form of credential attributes. The addition allows applications to use that information in making access decisions. These extended attributes are stored in the user registry.

This service can also work with attributes with an API call. A list of authorization API entitlement service IDs are queried by the azn_id_get_creds() interface. The query compiles a list of attributes to be added to the user credential while the credential is being built.

A list of service identifiers, which can be found within the [aznapi-entitlement-services] stanza, is queried to compile a list of attributes. The attributes are added to the user credential while the credential is being built. Each service ID is queried in the order it is declared in the list. The attribute returned is inserted into the credential attribute list of each credential that is built. The following example shows two entries from the credential attribute list:

cred-attribute-entitlement-services = myEntSvcID
cred-attribute-entitlement-services = myOtherEntSvcID

Note: You cannot use this stanza entry to override read-only attributes in the credential attribute list that include the principal name, principal UUID, and others. The exception to this rule is for the azn_cred_groups attribute.

The Authorization C API Developer Reference lists the read-only attributes and contains more information about this service. The document explains why administrators who do not want this capability must ensure that the azn_mod_rad service is not loaded by the application.

Usage

Optional

Default value

There is no default value.

Example

cred-attribute-entitlement-services = myEntSvcID

Parent topic: [aznapi-configuration] stanza

db-fileThis stanza entry specifies the name and location of the resource manager policy database cache file. db-file entryentriesdb-fileaznapi-configuration stanzadb-file entrySyntax db-file = fully_qualified_path Description Name and location of the resource manager policy database cache file. This value must be specified, and each server provides its own value.This stanza entry is not used in the ivmgrd.conf file. The policy server has its own stanza entries for specifying the path to the master policy database. Options fully_qualified_pathRepresents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Required for each specified server. Default value There is no default value. Example The following example sets the policy database with an absolute path on a Windows operating system: db-file = C:\pd\db\ivacld.db The following example sets the policy database with a relative path on a AIX, Linux, or Solaris operating system: db-file = ./authzn_demo.db [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

db-file

This stanza entry specifies the name and location of the resource manager policy database cache file.

Syntax

db-file = fully_qualified_path

Description

Name and location of the resource manager policy database cache file. This value must be specified, and each server provides its own value.

This stanza entry is not used in the ivmgrd.conf file. The policy server has its own stanza entries for specifying the path to the master policy database.

Options

fully_qualified_path

Represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).

For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Required for each specified server.

Default value

There is no default value.

Example

The following example sets the policy database with an absolute path on a Windows operating system:

db-file = C:\pd\db\ivacld.db

The following example sets the policy database with a relative path on a AIX, Linux, or Solaris operating system:

db-file = ./authzn_demo.db

Parent topic: [aznapi-configuration] stanza

dynamic-adi-entitlement-servicesThis stanza entry specifies the dynamic access decision information (ADI) retrieval entitlement service.dynamic-adi-entitlement-services entryentriesdynamic-adi-entitlement-servicesaznapi-configuration stanzadynamic-adi-entitlement-services entrySyntax dynamic-adi-entitlement-services = entitlement_service Description Dynamic access decision information (ADI) retrieval entitlement service. Options entitlement_serviceA string value for the container names of the required ADI. A list of configured authorization API entitlements service identifiers (IDs) is queried by the authorization rules engine when missing ADI is detected during an authorization rule evaluation. When ADI is found to be missing during a rule evaluation, each service in this list is queried in the order defined in this entry. These stanza entries must refer to existing entitlements services. The service ID (for example, bank_A_ADI) is loaded by using service entries in the entitlement service configuration [aznapi-entitlement-services] stanza or in an initialization attribute. See dynamic-adi-entitlement-servicesThe dynamic-adi-entitlement-services configuration entry lists the service IDs of the dynamic ADI retrieval entitlement services. These services must be called by the authorization engine if ADI is missing from the requesting user credential or from the application context and cannot be gathered from the resource manager. and the Authorization C API Developer Reference for more information about rules processing and this service. Usage Optional Default value There is no default value. Example [aznapi-entitlement-services] dynamic-adi-entitlement-services = bank_A_ADI dynamic-adi-entitlement-services = bank_B_ADI [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

dynamic-adi-entitlement-services

This stanza entry specifies the dynamic access decision information (ADI) retrieval entitlement service.

Syntax

dynamic-adi-entitlement-services = entitlement_service

Description

Dynamic access decision information (ADI) retrieval entitlement service.

Options

entitlement_service

A string value for the container names of the required ADI. A list of configured authorization API entitlements service identifiers (IDs) is queried by the authorization rules engine when missing ADI is detected during an authorization rule evaluation.

When ADI is found to be missing during a rule evaluation, each service in this list is queried in the order defined in this entry. These stanza entries must refer to existing entitlements services.

The service ID (for example, bank_A_ADI) is loaded by using service entries in the entitlement service configuration [aznapi-entitlement-services] stanza or in an initialization attribute.

See dynamic-adi-entitlement-services and the Authorization C API Developer Reference for more information about rules processing and this service.

Usage

Optional

Default value

There is no default value.

Example

[aznapi-entitlement-services]
dynamic-adi-entitlement-services = bank_A_ADI
dynamic-adi-entitlement-services = bank_B_ADI

Parent topic: [aznapi-configuration] stanza

input-adi-xml-prologThis stanza entry specifies the prolog to be added to the top of the XML document. This document is created with the Access Decision Information (ADI) needed to evaluate a Boolean authorization rule.input-adi-xml-prolog entryentriesinput-adi-xml-prologaznapi-configuration stanzainput-adi-xml-prolog entrySyntax input-adi-xml-prolog = prolog_attrs Description Prolog to be added to the top of the XML document. This document is created with the Access Decision Information (ADI) needed to evaluate a Boolean authorization rule. If a style sheet prolog is specified, that prolog is imported into the empty style sheet. If no prolog is specified, a default prolog value is used instead. All of the required prolog attributes are specified in the default prolog entries. If any of these attributes are changed or omitted from the entry, the authorization client fails to start and returns an error. Options prolog_attrsProlog attributes that are required by the authorization engine and include the following attributes: <?xml version="1.0" encoding="UTF-8"?> See input-adi-xml-prolog and xsl-stylesheet-prologYou can use the input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries to change the XML and XSL prolog statements. These statements are appended to the ADI XML document and authorization rule style sheet before they are passed to the rules evaluator for processing. . Usage Optional Example input-adi-xml-prolog = <?xml version="1.0" encoding="UTF-8"?> [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

input-adi-xml-prolog

This stanza entry specifies the prolog to be added to the top of the XML document. This document is created with the Access Decision Information (ADI) needed to evaluate a Boolean authorization rule.

Syntax

input-adi-xml-prolog = prolog_attrs

Description

Prolog to be added to the top of the XML document. This document is created with the Access Decision Information (ADI) needed to evaluate a Boolean authorization rule.

If a style sheet prolog is specified, that prolog is imported into the empty style sheet. If no prolog is specified, a default prolog value is used instead. All of the required prolog attributes are specified in the default prolog entries.

Note: If any of these attributes are changed or omitted from the entry, the authorization client fails to start and returns an error.

Options

prolog_attrs

Prolog attributes that are required by the authorization engine and include the following attributes:

<?xml version="1.0" encoding="UTF-8"?>

See input-adi-xml-prolog and xsl-stylesheet-prolog.

Usage

Optional

Example

input-adi-xml-prolog = <?xml version="1.0" encoding="UTF-8"?>

Parent topic: [aznapi-configuration] stanza

listen-flagsThis stanza entry specifies whether the reception of policy cache update notifications is on or off.listen-flags entryentrieslisten-flagsaznapi-configuration stanzalisten-flags entrySyntax listen-flags = {enable|disable} Description Specification of whether to turn on or off the reception of policy cache update notifications. Options enableActivates the notification listener.disableDeactivates the notification listener. Usage Optional Default value disable Example listen-flags = enable [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

listen-flags

This stanza entry specifies whether the reception of policy cache update notifications is on or off.

Syntax

listen-flags = {enable|disable}

Description

Specification of whether to turn on or off the reception of policy cache update notifications.

Options

enable

Activates the notification listener.

disable

Deactivates the notification listener.

Usage

Optional

Default value

disable

Example

listen-flags = enable

Parent topic: [aznapi-configuration] stanza

logcfgThis stanza entry enables logging and auditing for the application. logcfg entryaznapi-configuration stanzaentrieslogcfgaznapi-configuration stanzalogcfg entrySyntax logcfg = audit.azn:[log-agent][[param[=value]] ...] Description Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events. Each server provides its own setting for event logging in its corresponding configuration file. Options audit.azn:log-agentCategory of auditing event. Also specifies that the destination where log-agent is one of the following agents: stdoutstderrfilepiperemoteparam=valueAllowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing you want to do. See IBM Security Access Manager for Web: Troubleshooting Guide for information about the log agents and the configuration parameters. Usage Optional Default value Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application. Example logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

logcfg

This stanza entry enables logging and auditing for the application.

Syntax

logcfg = audit.azn:[log-agent][[param[=value]] ...]

Description

Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events.

Each server provides its own setting for event logging in its corresponding configuration file.

Options

audit.azn:log-agent

Category of auditing event. Also specifies that the destination where log-agent is one of the following agents:

stdout

stderr

file

pipe

remote

param=value

Allowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing you want to do.

See IBM Security Access Manager for Web: Troubleshooting Guide for information about the log agents and the configuration parameters.

Usage

Optional

Default value

Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application.

Example

logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log

Parent topic: [aznapi-configuration] stanza

modeThis stanza entry specifies the operating mode for the resource manager.mode entryentriesmodeaznapi-configuration stanzamode entrySyntax mode = {local|remote} Description Operating mode for the resource manager. This value cannot be changed after resource manager configuration. This stanza entry is set during configuration. Do not change it. Options localThe resource manager uses a local policy cache. remoteThe resource manager uses a remote policy cache that is maintained by the authorization server. Some configuration attributes apply only to resource managers that are configured to use local mode. Usage Required Default value local Example mode = remote [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

mode

This stanza entry specifies the operating mode for the resource manager.

Syntax

mode = {local|remote}

Description

Operating mode for the resource manager. This value cannot be changed after resource manager configuration.

Note: This stanza entry is set during configuration. Do not change it.

Options

local

The resource manager uses a local policy cache.

remote

The resource manager uses a remote policy cache that is maintained by the authorization server.

Some configuration attributes apply only to resource managers that are configured to use local mode.

Usage

Required

Default value

local

Example

mode = remote

Parent topic: [aznapi-configuration] stanza

pd-user-nameThis stanza entry specifies the Security Access Manager user account for the resource manager server.pd-user-name entryentriespd-user-nameaznapi-configuration stanzapd-user-name entrySyntax pd-user-name = server_name/hostname Description Security Access Manager user account for the resource manager server, either the policy proxy server, authorization server, or policy server, that is configured into the domain. The forward slash (/) character is required. The server name or host name is generated and set during configuration. Do not edit this stanza entry. [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

pd-user-name

This stanza entry specifies the Security Access Manager user account for the resource manager server.

Syntax

pd-user-name = server_name/hostname

Description

Security Access Manager user account for the resource manager server, either the policy proxy server, authorization server, or policy server, that is configured into the domain. The forward slash (/) character is required.

Note: The server name or host name is generated and set during configuration. Do not edit this stanza entry.

Parent topic: [aznapi-configuration] stanza

pd-user-pwdThis stanza entry specifies the Security Access Manager user account password for the resource manager.pd-user-pwd entryentriespd-user-pwdaznapi-configuration stanzapd-user-pwd entrySyntax pd-user-pwd = server_password Description Security Access Manager user account password for the resource manager, which can be the authorization server or policy server that is configured into the domain. The server password is generated and set during configuration. Do not edit this stanza entry. [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

pd-user-pwd

This stanza entry specifies the Security Access Manager user account password for the resource manager.

Syntax

pd-user-pwd = server_password

Description

Security Access Manager user account password for the resource manager, which can be the authorization server or policy server that is configured into the domain.

Note: The server password is generated and set during configuration. Do not edit this stanza entry.

Parent topic: [aznapi-configuration] stanza

permission-info-returnedThis stanza entry specifies the set of attributes that the caller wants to receive from the azn_decision_access_allowed_ext() function in the permission information attribute list.permission-info-returned entryentriespermission-info-returnedaznapi-configuration stanzapermission-info-returned entrySyntax permission-info-returned = {attribute1 attribute2 ...} Description Set of attributes that the caller wants to receive from the azn_decision_access_allowed_ext() function in the permission information attribute list. Before you use this stanza entry and value, read and thoroughly understand the concept in the Authorization C API Developer Reference. You can also define your own attributes. For example, you can set an attribute on an ACL with the acl modify command with the set attribute option. When you add an attribute name to the list, the attribute can be returned only as permission information if it is applicable to the current decision call. Options For a list of the strings recognized by the authorization engine, see Authorization C API Developer Reference. Usage Optional Default value No information is returned. Example The following example returns permission information for all attributes in the list: permission-info-returned = azn_perminfo_all_attrs [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

permission-info-returned

This stanza entry specifies the set of attributes that the caller wants to receive from the azn_decision_access_allowed_ext() function in the permission information attribute list.

Syntax

permission-info-returned = {attribute1 attribute2 ...}

Description

Set of attributes that the caller wants to receive from the azn_decision_access_allowed_ext() function in the permission information attribute list. Before you use this stanza entry and value, read and thoroughly understand the concept in the Authorization C API Developer Reference.

You can also define your own attributes. For example, you can set an attribute on an ACL with the acl modify command with the set attribute option.

When you add an attribute name to the list, the attribute can be returned only as permission information if it is applicable to the current decision call.

Options

For a list of the strings recognized by the authorization engine, see Authorization C API Developer Reference.

Usage

Optional

Default value

No information is returned.

Example

The following example returns permission information for all attributes in the list:

permission-info-returned = azn_perminfo_all_attrs

Parent topic: [aznapi-configuration] stanza

policy-cache-sizeThis stanza entry specifies the maximum size of the in-memory policy cache.policy-cache-size entryentriespolicy-cache-sizeaznapi-configuration stanzapolicy-cache-size entrySyntax policy-cache-size = size Description Maximum size of the in-memory policy cache. This size is configurable. The cache consists of policy and the relationships between policy and resources. The knowledge that a resource has no directly associated policy is also cached. Specify the maximum cache size relative to the number of policy objects defined, the number of resources protected, and the available memory. As a starting point, use the following algorithm:3 * (number of policy objects + number of protected resources) This value controls how much information is cached. A larger cache potentially improves the application performance, but uses additional memory as well. Options sizeSize is specified as the number of entries. Usage Optional Default value 32768 Example policy-cache-size = 32768 [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

policy-cache-size

This stanza entry specifies the maximum size of the in-memory policy cache.

Syntax

policy-cache-size = size

Description

Maximum size of the in-memory policy cache. This size is configurable. The cache consists of policy and the relationships between policy and resources. The knowledge that a resource has no directly associated policy is also cached.

Specify the maximum cache size relative to the number of policy objects defined, the number of resources protected, and the available memory.

As a starting point, use the following algorithm:

3 * (number of policy objects + number of protected resources)

This value controls how much information is cached. A larger cache potentially improves the application performance, but uses additional memory as well.

Options

size

Size is specified as the number of entries.

Usage

Optional

Default value

32768

Example

policy-cache-size = 32768

Parent topic: [aznapi-configuration] stanza

resource-manager-provided-adiThis stanza entry specifies the prefix that the authorization engine uses to determine the set of missing access decision information (ADI) provided by the resource manager.resource-manager-provided-adi entryentriesresource-manager-provided-adiaznapi-configuration stanzaresource-manager-provided-adi entrySyntax resource-manager-provided-adi = prefix Description Prefix that the authorization engine uses to determine the set of missing access decision information (ADI) provided by the resource manager. To specify more than one prefix, add multiple stanza entries. These entries must refer to existing entitlements services that were loaded with service entries in the [aznapi-entitlement-services] configuration stanza or that were loaded with an initialization attribute. If an ADI is found to be missing during a rule evaluation, each service in this list is queried in the order defined. Options prefixA string prefix for its value. For example, you might want to notify the authorization engine that any ADI beginning with sales_customer_ is provided by the resource manager application. The stanza entry is:resource-manager-provided-adi = sales_customer_ See resource-manager-provided-adiThe resource-manager-provided-adi configuration stanza entry defines the prefixes that the authorization engine uses to determine the set of missing ADI from the resource manager. . Usage Optional Default value There is no default value. Example The following example shows multiple stanza entries: resource-manager-provided-adi = sales_item_ resource-manager-provided-adi = sales_customer_ [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

resource-manager-provided-adi

This stanza entry specifies the prefix that the authorization engine uses to determine the set of missing access decision information (ADI) provided by the resource manager.

Syntax

resource-manager-provided-adi = prefix

Description

Prefix that the authorization engine uses to determine the set of missing access decision information (ADI) provided by the resource manager. To specify more than one prefix, add multiple stanza entries.

These entries must refer to existing entitlements services that were loaded with service entries in the [aznapi-entitlement-services] configuration stanza or that were loaded with an initialization attribute. If an ADI is found to be missing during a rule evaluation, each service in this list is queried in the order defined.

Options

prefix

A string prefix for its value. For example, you might want to notify the authorization engine that any ADI beginning with sales_customer_ is provided by the resource manager application. The stanza entry is:

resource-manager-provided-adi = sales_customer_

See resource-manager-provided-adi.

Usage

Optional

Default value

There is no default value.

Example

The following example shows multiple stanza entries:

resource-manager-provided-adi = sales_item_
resource-manager-provided-adi = sales_customer_

Parent topic: [aznapi-configuration] stanza

xsl-stylesheet-prologThis stanza entry specifies the prolog to be added to the top of the XSL style sheet with the XSL text that defines a Boolean authorization rule.xsl-stylesheet-prolog entryentriesxsl-stylesheet-prologaznapi-configuration stanzaxsl-stylesheet-prolog entrySyntax xsl-stylesheet-prolog = prolog_attrs Description The prolog to be added to the top of the XSL style sheet that is created with the XSL text that defines a Boolean authorization rule. If a style sheet prolog is specified, that prolog is imported into the empty style sheet. If no prolog is specified, a default prolog value is used instead. All of the required prolog attributes are specified in the default prolog entries. When not specified, the default XSL style sheet prolog is: !<-- Required for XSLT language --> <?xml version="1.0" encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl= "http://www.w3.org/1999/XSL/Transform" version="1.0"> !<-- Required to constrain output of rule evaluation --> <xsl:output method="text" omit-xml-declaration="yes" encoding='UTF-8' indent="no" /> !<-- Need this to ensure default text node printing is off --> <xsl:template match="text()"></xsl:template> If any of the required prolog attributes are changed or omitted from the entry, then the authorization client fails to start and returns an error. Use caution when changing this setting. See input-adi-xml-prolog and xsl-stylesheet-prologYou can use the input-adi-xml-prolog and xsl-stylesheet-prolog configuration entries to change the XML and XSL prolog statements. These statements are appended to the ADI XML document and authorization rule style sheet before they are passed to the rules evaluator for processing. . Options prolog_attrsProlog attributes that are required by the authorization server. Usage Optional Example See XML namespace definitionsXML namespaces differentiate between XML items with the same name. XML namespaces also group XML data of the same type or function. The same principles can be used with ADI that is defined for use with authorization rules. for a complete explanation of the name space example. [aznapi-configuration] stanzaSecurity Access Manager allows a highly flexible approach to authorization through the use of the authorization API.

xsl-stylesheet-prolog

This stanza entry specifies the prolog to be added to the top of the XSL style sheet with the XSL text that defines a Boolean authorization rule.

Syntax

xsl-stylesheet-prolog = prolog_attrs

Description

The prolog to be added to the top of the XSL style sheet that is created with the XSL text that defines a Boolean authorization rule.

If a style sheet prolog is specified, that prolog is imported into the empty style sheet. If no prolog is specified, a default prolog value is used instead. All of the required prolog attributes are specified in the default prolog entries.

When not specified, the default XSL style sheet prolog is:

!<-- Required for XSLT language -->
<?xml version="1.0" encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl=
   "http://www.w3.org/1999/XSL/Transform" version="1.0">

!<-- Required to constrain output of rule evaluation -->
<xsl:output method="text" omit-xml-declaration="yes"
    encoding='UTF-8' indent="no" />

!<-- Need this to ensure default text node printing is
      off -->
<xsl:template match="text()"></xsl:template>

Note: If any of the required prolog attributes are changed or omitted from the entry, then the authorization client fails to start and returns an error.

Use caution when changing this setting. See input-adi-xml-prolog and xsl-stylesheet-prolog.

Options

prolog_attrs

Prolog attributes that are required by the authorization server.

Usage

Optional

Example

See XML namespace definitions for a complete explanation of the name space example.

Parent topic: [aznapi-configuration] stanza

[aznapi-cred-modification-services] stanzaA credential modification service plug-in enables authorization API applications to do modifications on a Security Access Manager credential.stanzasaznapi-cred-modification-servicesaznapi-cred-modification-services stanzadescriptionThe credentials modification service can then return this modified credential for use by the calling application. Applications can use this service to add additional information to a user's credential. For example, this additional information can include the credit card number and credit limit of the user. Each credential modification service plug-in is a stand-alone module that is dynamically loaded into the authorization service.The parameters for configuring Security Access Manager credential modification service plug-ins are declared in the [aznapi-cred-modification-services] stanza of each of the configuration files provided with Security Access Manager: The ivmgrd.conf configuration file for the policy serverThe [instance-]ivacld.conf configuration file for the authorization serverThe configuration file for configured credentials modification service plug-ins for your resource managers The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].service-idThis stanza entry defines the authorization API service for the credentials attribute list modification service.

[aznapi-cred-modification-services] stanza

A credential modification service plug-in enables authorization API applications to do modifications on a Security Access Manager credential.

The credentials modification service can then return this modified credential for use by the calling application. Applications can use this service to add additional information to a user's credential. For example, this additional information can include the credit card number and credit limit of the user. Each credential modification service plug-in is a stand-alone module that is dynamically loaded into the authorization service.

The parameters for configuring Security Access Manager credential modification service plug-ins are declared in the [aznapi-cred-modification-services] stanza of each of the configuration files provided with Security Access Manager:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

The configuration file for configured credentials modification service plug-ins for your resource managers

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

service-id
This stanza entry defines the authorization API service for the credentials attribute list modification service.

Parent topic: Configuration file stanza reference

service-idThis stanza entry defines the authorization API service for the credentials attribute list modification service.service-id entryaznapi-cred-modification-services stanzaaznapi-cred-modification-services stanzaservice-id entrySyntax service-id = short_name|path_to_dll [ & params …] Description Defines the authorization API service for the credentials attribute list modification service. Each stanza entry defines different types of aznAPI service. Options Each entry has the following format: service-idDeveloper-specified ID of the credential modification service. The service ID string must be unique.short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executable code for the service. If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short name of azn_ent_user, the following table shows the names that are automatically searched for on each platform: AIX libazn_ent_user.so libazn_ent_user.aLinuxlibazn_ent_user.soSolarislibazn_ent_user.soWindowsazn_ent_user.dllparamsOptional: The parameters to pass to the service when it is initialized by the aznAPI service. Parameters are considered to be all data that follow the ampersand (&). The service definition is described in more detail in the Authorization C API Developer Reference. Usage Optional Default value There is no default value. Example AZN_MOD_SVC_RAD_2AB = azn_mod_rad [aznapi-cred-modification-services] stanzaA credential modification service plug-in enables authorization API applications to do modifications on a Security Access Manager credential.

service-id

This stanza entry defines the authorization API service for the credentials attribute list modification service.

Syntax

service-id = short_name|path_to_dll [ & params …]

Description

Defines the authorization API service for the credentials attribute list modification service. Each stanza entry defines different types of aznAPI service.

Options

Each entry has the following format:

service-id

Developer-specified ID of the credential modification service. The service ID string must be unique.

short_name|path_to_dll

The path to the dynamic link library (DLL) that contains the executable code for the service.

If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short name of azn_ent_user, the following table shows the names that are automatically searched for on each platform:

AIX®

libazn_ent_user.so

libazn_ent_user.a

Linux

libazn_ent_user.so

Solaris

libazn_ent_user.so

Windows

azn_ent_user.dll

params

Optional: The parameters to pass to the service when it is initialized by the aznAPI service. Parameters are considered to be all data that follow the ampersand (&). The service definition is described in more detail in the Authorization C API Developer Reference.

Usage

Optional

Default value

There is no default value.

Example

AZN_MOD_SVC_RAD_2AB = azn_mod_rad

Parent topic: [aznapi-cred-modification-services] stanza

[aznapi-entitlement-services] stanzaAn entitlement services plug-in enables authorization API applications to retrieve the entitlements for a user from an entitlements repository.stanzasaznapi-entitlement-servicesaznapi-entitlement-services stanzadescriptionEach entitlement services plug-in is a stand-alone module that is dynamically loaded into the authorization service.The stanza entries for configuring Security Access Manager entitlement services plug-ins are declared in the [aznapi-entitlement-services] stanza of each of these configuration files provided by Security Access Manager:The ivmgrd.conf configuration file for the policy serverThe [instance-]ivacld.conf configuration file for the authorization serverThe configuration file for configured entitlement services plug-ins for your resource managers The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].service-idThis stanza entry defines the authorization API service for the entitlement services of the protected objects.

[aznapi-entitlement-services] stanza

An entitlement services plug-in enables authorization API applications to retrieve the entitlements for a user from an entitlements repository.

Each entitlement services plug-in is a stand-alone module that is dynamically loaded into the authorization service.

The stanza entries for configuring Security Access Manager entitlement services plug-ins are declared in the [aznapi-entitlement-services] stanza of each of these configuration files provided by Security Access Manager:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

The configuration file for configured entitlement services plug-ins for your resource managers

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

service-id
This stanza entry defines the authorization API service for the entitlement services of the protected objects.

Parent topic: Configuration file stanza reference

service-idThis stanza entry defines the authorization API service for the entitlement services of the protected objects.service-id entryaznapi-entitlement-services stanzaaznapi-entitlement-services stanzaservice-id entrySyntax service-id = {short_name|path_to_dll} [ & params ...] Description Defines the authorization API service for the entitlement services of the protected objects. Each stanza entry defines different types of aznAPI service. Options Each entry has the following format: service-idDeveloper-specified ID by which the service can be identified by the aznAPI client. The service ID string must be unique.short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executable code for the service. If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported Security Access Manager platform, provide a short form library name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short form library name of azn_ent_user, the following names that are automatically searched for on each platform: AIX libazn_ent_user.so libazn_ent_user.aLinuxlibazn_ent_user.soSolarislibazn_ent_user.soWindowsazn_ent_user.dllparamsOptional: One or more parameters to pass to the service when it is initialized by the aznAPI service. Parameters are considered to be all data that follow the ampersand (&). The service definition is described in more detail in the IBM Security Access Manager for Web: Authorization C API Developer Reference. Usage Optional Default value There is no default value. Example credattrs_ent_svc = azn_ent_cred_attrs [aznapi-entitlement-services] stanzaAn entitlement services plug-in enables authorization API applications to retrieve the entitlements for a user from an entitlements repository.

service-id

This stanza entry defines the authorization API service for the entitlement services of the protected objects.

Syntax

service-id = {short_name|path_to_dll} [ & params ...]

Description

Defines the authorization API service for the entitlement services of the protected objects. Each stanza entry defines different types of aznAPI service.

Options

Each entry has the following format:

service-id

Developer-specified ID by which the service can be identified by the aznAPI client. The service ID string must be unique.

short_name|path_to_dll

The path to the dynamic link library (DLL) that contains the executable code for the service.

If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported Security Access Manager platform, provide a short form library name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short form library name of azn_ent_user, the following names that are automatically searched for on each platform:

AIX®

libazn_ent_user.so

libazn_ent_user.a

Linux

libazn_ent_user.so

Solaris

libazn_ent_user.so

Windows

azn_ent_user.dll

params

Optional: One or more parameters to pass to the service when it is initialized by the aznAPI service. Parameters are considered to be all data that follow the ampersand (&). The service definition is described in more detail in the IBM Security Access Manager for Web: Authorization C API Developer Reference.

Usage

Optional

Default value

There is no default value.

Example

credattrs_ent_svc = azn_ent_cred_attrs

Parent topic: [aznapi-entitlement-services] stanza

[aznapi-external-authzn-services] stanzaAn external authorization service plug-in is an optional extension of the Security Access Manager authorization service that you can use to impose additional authorization controls and conditions.stanzasaznapi-external-authzn-servicesaznapi-external-authzn-services stanzadescriptionYou can use an external authorization service plug-in to force authorization decisions to be made based on application-specific criteria that are not known to the Security Access Manager authorization service. Each external authorization service plug-in is a stand-alone module that is dynamically loaded into the authorization service. The parameters for configuring Security Access Manager external authorization service plug-ins are declared in the [aznapi-external-authzn-services] stanza of this configuration file provided by Security Access Manager: The ivmgrd.conf configuration file for the policy server The [instance-]ivacld.conf configuration file for the authorization serverThe configuration file for configured external authorization service plug-ins for your resource managers The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].policy-triggerThis stanza entry defines the authorization API service for external authorization service definitions that force authorization decisions to made based on application-specific criteria.

[aznapi-external-authzn-services] stanza

An external authorization service plug-in is an optional extension of the Security Access Manager authorization service that you can use to impose additional authorization controls and conditions.

You can use an external authorization service plug-in to force authorization decisions to be made based on application-specific criteria that are not known to the Security Access Manager authorization service. Each external authorization service plug-in is a stand-alone module that is dynamically loaded into the authorization service.

The parameters for configuring Security Access Manager external authorization service plug-ins are declared in the [aznapi-external-authzn-services] stanza of this configuration file provided by Security Access Manager:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

The configuration file for configured external authorization service plug-ins for your resource managers

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

policy-trigger
This stanza entry defines the authorization API service for external authorization service definitions that force authorization decisions to made based on application-specific criteria.

Parent topic: Configuration file stanza reference

policy-triggerThis stanza entry defines the authorization API service for external authorization service definitions that force authorization decisions to made based on application-specific criteria.policy-trigger entryentriespolicy-triggeraznapi-external-authzn-services stanzapolicy-trigger entrySyntax policy-trigger = {short_name|path_to_dll} [-weight number] [ & params ...] Description Defines the authorization API service for external authorization service definitions that force authorization decisions to made based on application-specific criteria. Each stanza entry defines different types of aznAPI service, and each entry is the same format. Options policy-triggerThe policy trigger is the way that an external authorization service is started. It is either a service ID or an access control list (ACL) action string. For example, it can be my_service_1 or Trx. If the service is defined an ID, the service ID is used as an extended attribute on a POP that triggers the external authorization service when an object has this POP attached to it. If the service is defined with an ACL action string, the service is started when this ACL action mask is requested as part of an authorization decision. The policy trigger can be any string that is recognized as a valid key name. The policy-trigger is case-sensitive, because the actions themselves are case-sensitive. However, the policy trigger is not case-sensitive if the trigger is a POP attribute.short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executable code for the service. If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL. Specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short name of azn_ent_user, the following names that are automatically searched for on each platform: AIX libazn_ent_user.so libazn_ent_user.aLinuxlibazn_ent_user.soSolarislibazn_ent_user.soWindowsazn_ent_user.dll[-weight number]Optional: Specifies the weight assigned in the access decision process of the external authorization service. This option is an unsigned size_t value. This value signifies the weight. In the entire decision process, the weight is specified in any decision that is returned by the external authorization service. The default value is 101.paramsOptional: Additional initialization information to pass to the external authorization service in the form of arguments. The arguments must be preceded by the ampersand (&); for example, & -server fred. The service definition is described in more detail in the Authorization C API Developer Reference. Usage Optional Default value There is no default value. [aznapi-external-authzn-services] stanzaAn external authorization service plug-in is an optional extension of the Security Access Manager authorization service that you can use to impose additional authorization controls and conditions.

policy-trigger

This stanza entry defines the authorization API service for external authorization service definitions that force authorization decisions to made based on application-specific criteria.

Syntax

policy-trigger = {short_name|path_to_dll} [-weight number]
     [ & params ...]

Description

Defines the authorization API service for external authorization service definitions that force authorization decisions to made based on application-specific criteria. Each stanza entry defines different types of aznAPI service, and each entry is the same format.

Options

policy-trigger

The policy trigger is the way that an external authorization service is started. It is either a service ID or an access control list (ACL) action string. For example, it can be my_service_1 or Trx. If the service is defined an ID, the service ID is used as an extended attribute on a POP that triggers the external authorization service when an object has this POP attached to it. If the service is defined with an ACL action string, the service is started when this ACL action mask is requested as part of an authorization decision.

The policy trigger can be any string that is recognized as a valid key name. The policy-trigger is case-sensitive, because the actions themselves are case-sensitive. However, the policy trigger is not case-sensitive if the trigger is a POP attribute.

short_name|path_to_dll

The path to the dynamic link library (DLL) that contains the executable code for the service.

If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL. Specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short name of azn_ent_user, the following names that are automatically searched for on each platform:

AIX®

libazn_ent_user.so

libazn_ent_user.a

Linux

libazn_ent_user.so

Solaris

libazn_ent_user.so

Windows

azn_ent_user.dll

[-weight number]

Optional: Specifies the weight assigned in the access decision process of the external authorization service. This option is an unsigned size_t value. This value signifies the weight. In the entire decision process, the weight is specified in any decision that is returned by the external authorization service. The default value is 101.

params

Optional: Additional initialization information to pass to the external authorization service in the form of arguments. The arguments must be preceded by the ampersand (&); for example, & -server fred. The service definition is described in more detail in the Authorization C API Developer Reference.

Usage

Optional

Default value

There is no default value.

Parent topic: [aznapi-external-authzn-services] stanza

[aznapi-pac-services] stanzaA PAC services plug-in gives authorization API applications the ability to move Security Access Manager credentials back and forth between the native Security Access Manager credentials format and an alternate format called privilege attribute certificate (PAC).stanzasaznapi-pac-servicesaznapi-pac-services stanzadescriptionEach PAC services plug-in is a stand-alone module that is dynamically loaded into the authorization service. Identity information can be obtained from a PAC. Applications can convert user credentials to PACs for use within other authorization domains. Applications can then pass the PACs to a server in another authorization domain and do an operation.The stanza entries for configuring Security Access Manager PAC services plug-ins are declared in the [aznapi-pac-services] stanza of each of these configuration files provided by Security Access Manager: The configuration file for configured PAC services plug-ins for your resource managersThe aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].service-idThis stanza entry defines the authorization API service for the Security Access Manager privilege attribute certificate (PAC) encoding service.

[aznapi-pac-services] stanza

A PAC services plug-in gives authorization API applications the ability to move Security Access Manager credentials back and forth between the native Security Access Manager credentials format and an alternate format called privilege attribute certificate (PAC).

Each PAC services plug-in is a stand-alone module that is dynamically loaded into the authorization service.

Identity information can be obtained from a PAC. Applications can convert user credentials to PACs for use within other authorization domains. Applications can then pass the PACs to a server in another authorization domain and do an operation.

The stanza entries for configuring Security Access Manager PAC services plug-ins are declared in the [aznapi-pac-services] stanza of each of these configuration files provided by Security Access Manager:

The configuration file for configured PAC services plug-ins for your resource managers

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

service-id
This stanza entry defines the authorization API service for the Security Access Manager privilege attribute certificate (PAC) encoding service.

Parent topic: Configuration file stanza reference

service-idThis stanza entry defines the authorization API service for the Security Access Manager privilege attribute certificate (PAC) encoding service.service-id entryaznapi-pac-services stanzaaznapi-pac-services stanzaservice-id entrySyntax service-id = {short_name|path_to_dll} [ & params ... ] Description Defines the authorization API service for the Security Access Manager privilege attribute certificate (PAC) encoding service. Each stanza entry defines different types of aznAPI authorization service. Options Each entry has the following format: service-idDeveloper-specified ID of the PAC service that produces the PAC. The service ID string must be unique.short_name|path_to_dllThe path to the dynamic link library (DLL) that contains the executable code for the service executable. If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short form library name of azn_ent_user, the following names that are automatically searched for on each platform: AIX libazn_ent_user.so libazn_ent_user.aLinuxlibazn_ent_user.soSolarislibazn_ent_user.soWindowsazn_ent_user.dllparamsOptional: Parameters to pass to the service when it is initialized by the aznAPI service. Parameters are considered to be all data that follow the ampersand (&). The service definition is described in more detail in the IBM Security Access Manager for Web: Authorization C API Developer Reference. Usage Optional Default value There is no default value. [aznapi-pac-services] stanzaA PAC services plug-in gives authorization API applications the ability to move Security Access Manager credentials back and forth between the native Security Access Manager credentials format and an alternate format called privilege attribute certificate (PAC).

service-id

This stanza entry defines the authorization API service for the Security Access Manager privilege attribute certificate (PAC) encoding service.

Syntax

service-id = {short_name|path_to_dll}
      [ & params ... ]

Description

Defines the authorization API service for the Security Access Manager privilege attribute certificate (PAC) encoding service. Each stanza entry defines different types of aznAPI authorization service.

Options

Each entry has the following format:

service-id

Developer-specified ID of the PAC service that produces the PAC. The service ID string must be unique.

short_name|path_to_dll

The path to the dynamic link library (DLL) that contains the executable code for the service executable.

If the DLL is in a directory that is normally searched by the system (for example, /usr/lib on AIX, Linux, and Solaris operating systems or the value of the PATH environment variable on Windows operating systems), do not specify the full path to the DLL, specify only the DLL name. If you want a platform-independent DLL name, so it can be loaded on any supported platform, provide a short name. The short name is appended with known library prefixes and suffixes for each platform, and each possibility is searched in turn. For example, with a short form library name of azn_ent_user, the following names that are automatically searched for on each platform:

AIX®

libazn_ent_user.so

libazn_ent_user.a

Linux

libazn_ent_user.so

Solaris

libazn_ent_user.so

Windows

azn_ent_user.dll

params

Optional: Parameters to pass to the service when it is initialized by the aznAPI service. Parameters are considered to be all data that follow the ampersand (&). The service definition is described in more detail in the IBM Security Access Manager for Web: Authorization C API Developer Reference.

Usage

Optional

Default value

There is no default value.

Parent topic: [aznapi-pac-services] stanza

[configuration-database] stanzaThe stanza entry defines the name and location of the Security Access Manager obfuscated password configuration file.stanzasconfiguration-databaseconfiguration-database stanzadescriptionSecurity Access Manager creates a configuration file that contains all the obfuscated entries. For example, All bind (log in) passwords are obfuscated and placed in the configuration file. Both the existing configuration file and the obfuscated configuration file have the same file name, except that .obf is appended to the file name (for example, ivmgrd.conf.obf).In addition, Security Access Manager creates the [configuration-database] stanza, as needed, whenever an obfuscated entry is automatically added to the obfuscated configuration file. This stanza has a stanza entry that points to the name and location of the obfuscated configuration file. The [configuration-database] stanza can be in every configuration file, including the pd.conf configuration file, if an obfuscated value is added to the file.Never edit the entry in the [configuration-database] stanza. The one exception might be if the file is to be moved permanently to a different location. This scenario is the only circumstance in which you modify the file name and location. Remember that whenever the configuration file is moved to a different location, you must move the obfuscated file also.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].fileThis stanza entry specifies the file name and location of the obfuscated configuration file information.

[configuration-database] stanza

The stanza entry defines the name and location of the Security Access Manager obfuscated password configuration file.

Security Access Manager creates a configuration file that contains all the obfuscated entries. For example, All bind (log in) passwords are obfuscated and placed in the configuration file. Both the existing configuration file and the obfuscated configuration file have the same file name, except that .obf is appended to the file name (for example, ivmgrd.conf.obf).

In addition, Security Access Manager creates the [configuration-database] stanza, as needed, whenever an obfuscated entry is automatically added to the obfuscated configuration file. This stanza has a stanza entry that points to the name and location of the obfuscated configuration file. The [configuration-database] stanza can be in every configuration file, including the pd.conf configuration file, if an obfuscated value is added to the file.

Never edit the entry in the [configuration-database] stanza. The one exception might be if the file is to be moved permanently to a different location. This scenario is the only circumstance in which you modify the file name and location. Remember that whenever the configuration file is moved to a different location, you must move the obfuscated file also.

file
This stanza entry specifies the file name and location of the obfuscated configuration file information.

Parent topic: Configuration file stanza reference

fileThis stanza entry specifies the file name and location of the obfuscated configuration file information.file, stanza entryentriesfileconfiguration-database stanzafile entrySyntax file = fully_qualified_path Description File name and location of the obfuscated configuration file information. The obfuscated password is generated and set by the configuration utility. Do not edit this stanza entry. The name of the obfuscated configuration file is the same name as the related configuration file name. The file extension can be anything, but the extension is usually .conf.obf. For example, the obfuscated configuration file for ldap.conf is ldap.conf.obf. Options fully_qualified_pathRepresents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of characters permitted in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Conditional. This stanza entry is required only if, during configuration, passwords were obfuscated. Default value The following table shows the default installation location by platform. PlatformFile nameLinux or UNIX/opt/PolicyDirector/etc/server_name.conf.obfWindowsc:\program files\tivoli\policy director\etc\server_name.conf.obf Example The following example of setting the location of the obfuscated configuration file when using Microsoft Active Directory as the user registry on a Windows operating system: c:\program files\tivoli\policy director\etc\ldap.conf.obf [configuration-database] stanzaThe stanza entry defines the name and location of the Security Access Manager obfuscated password configuration file.

file

This stanza entry specifies the file name and location of the obfuscated configuration file information.

Syntax

file = fully_qualified_path

Description

File name and location of the obfuscated configuration file information.

Note: The obfuscated password is generated and set by the configuration utility. Do not edit this stanza entry.

The name of the obfuscated configuration file is the same name as the related configuration file name. The file extension can be anything, but the extension is usually .conf.obf. For example, the obfuscated configuration file for ldap.conf is ldap.conf.obf.

Options

fully_qualified_path

Represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of characters permitted in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Conditional. This stanza entry is required only if, during configuration, passwords were obfuscated.

Default value

The following table shows the default installation location by platform.

Platform | File name
Linux or UNIX | /opt/PolicyDirector/etc/server_name.conf.obf
Windows | c:\program files\tivoli\policy director\etc\server_name.conf.obf

Example

The following example of setting the location of the obfuscated configuration file when using Microsoft Active Directory as the user registry on a Windows operating system:

c:\program files\tivoli\policy director\etc\ldap.conf.obf

Parent topic: [configuration-database] stanza

[delegated-admin] stanzaThe Security Access Manager configuration can require that the user is authorized to view each group that is returned in the group list. Or, the user can be authorized to return the list without authorizing first.stanzasdelegated-admindelegated-admin stanzadescriptionFor delegated administration, use one type of interface throughout the entire process for optimal results. Use the Web Portal Manager or pdadmin utility. This stanza relates only to the pdadmin utility.The stanza entries for turning on or off the setting for authorization checks for the delegated management of groups and users are in the [delegated-admin] stanza of the following configuration file: The ivmgrd.conf configuration file for the policy server Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].authorize-group-listThis stanza entry specifies whether authorization checks on the group list and group list-dn commands are made.

[delegated-admin] stanza

The Security Access Manager configuration can require that the user is authorized to view each group that is returned in the group list. Or, the user can be authorized to return the list without authorizing first.

For delegated administration, use one type of interface throughout the entire process for optimal results. Use the Web Portal Manager or pdadmin utility. This stanza relates only to the pdadmin utility.

The stanza entries for turning on or off the setting for authorization checks for the delegated management of groups and users are in the [delegated-admin] stanza of the following configuration file:

The ivmgrd.conf configuration file for the policy server

authorize-group-list
This stanza entry specifies whether authorization checks on the group list and group list-dn commands are made.

Parent topic: Configuration file stanza reference

authorize-group-listThis stanza entry specifies whether authorization checks on the group list and group list-dn commands are made.authorize-group-list entryentriesauthorize-group-listdelegated-admin stanzaauthorize-group-list entrySyntax authorize-group-list = {yes|no} Description Specification of whether authorization checks on the group list and group list-dn commands are made. This keyword is provided as a performance feature. Options yesEnables authorization checks.noDisables authorization checks. Usage Optional Default value no Example authorize-group-list = yes [delegated-admin] stanzaThe Security Access Manager configuration can require that the user is authorized to view each group that is returned in the group list. Or, the user can be authorized to return the list without authorizing first.

authorize-group-list

This stanza entry specifies whether authorization checks on the group list and group list-dn commands are made.

Syntax

authorize-group-list = {yes|no}

Description

Specification of whether authorization checks on the group list and group list-dn commands are made.

This keyword is provided as a performance feature.

Options

yes

Enables authorization checks.

no

Disables authorization checks.

Usage

Optional

Default value

no

Example

authorize-group-list = yes

Parent topic: [delegated-admin] stanza

[domains] and [domain=domain_name] stanzasThe [domains] stanza contains a list of domains.stanzasdomainsstanzasdomain=domain_namedomainsstanzadescriptionEach domain specified under this stanza must have its own [domain=domain_name] stanza. The following example shows domains named d and mydomain: [domains] domain = d domain = mydomain [domain=d] [domain=mydomain]The stanza entries for configuring multiple domains are in the [domains] and the [domain=domain_name] stanzas of the following configuration file: The ivmgrd.conf configuration file for the policy server Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].allowed-registry-substringsThis stanza entry specifies the Distinguished Name (DN) substring that restricts which registry locations that users can be created in or be imported from.database-pathThis stanza entry specifies the file name and location of the policy database for the specified domain.domainThis stanza entry specifies the name of the domain.

[domains] and [domain=domain_name] stanzas

The [domains] stanza contains a list of domains.

Each domain specified under this stanza must have its own [domain=domain_name] stanza. The following example shows domains named d and mydomain:

[domains]
domain = d
domain = mydomain

[domain=d]

[domain=mydomain]

The stanza entries for configuring multiple domains are in the [domains] and the [domain=domain_name] stanzas of the following configuration file:

The ivmgrd.conf configuration file for the policy server

allowed-registry-substrings
This stanza entry specifies the Distinguished Name (DN) substring that restricts which registry locations that users can be created in or be imported from.

database-path
This stanza entry specifies the file name and location of the policy database for the specified domain.

domain
This stanza entry specifies the name of the domain.

Parent topic: Configuration file stanza reference

allowed-registry-substringsThis stanza entry specifies the Distinguished Name (DN) substring that restricts which registry locations that users can be created in or be imported from.allowed-registry-substrings entryentriesallowed-registry-substringsdomainsstanzaallowed-registry-substrings entrydomain=domain_name stanzaallowed-registry-substrings entrySyntax allowed-registry-substrings = dn Description Distinguished name (DN) substring that restricts which registry locations that users can be created in or be imported from. The DN of the user that is created or imported must contain the substring value specified. The DN substring value restrictions are registry-dependent. Most user registries allow an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. You can specify one or more relative DNs to use when creating users. By specifying one or more substrings, you can restrict creating and importing users and groups to the relative DNs that are identified by the substrings. For example, you can specify the DN substring dc=mkt to restrict users who are created or imported into a domain named Marketing: As a management domain administrator, complete the following tasks: Manually add the dn value for each domain created, except the Management (policy server) domain.Notify the domain administrator, after this key value pair is added, to add this string to the DN option when creating and importing users or groups. Options dnThe distinguished name substring Usage Optional Default value There is no default value. Example allowed-registry-substrings = dc=mkt [domains] and [domain=domain_name] stanzasThe [domains] stanza contains a list of domains.

allowed-registry-substrings

This stanza entry specifies the Distinguished Name (DN) substring that restricts which registry locations that users can be created in or be imported from.

Syntax

allowed-registry-substrings = dn

Description

Distinguished name (DN) substring that restricts which registry locations that users can be created in or be imported from.

The DN of the user that is created or imported must contain the substring value specified. The DN substring value restrictions are registry-dependent. Most user registries allow an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.

You can specify one or more relative DNs to use when creating users. By specifying one or more substrings, you can restrict creating and importing users and groups to the relative DNs that are identified by the substrings. For example, you can specify the DN substring dc=mkt to restrict users who are created or imported into a domain named Marketing:

As a management domain administrator, complete the following tasks:

Manually add the dn value for each domain created, except the Management (policy server) domain.

Notify the domain administrator, after this key value pair is added, to add this string to the DN option when creating and importing users or groups.

Options

dn

The distinguished name substring

Usage

Optional

Default value

There is no default value.

Example

allowed-registry-substrings = dc=mkt

Parent topic: [domains] and [domain=domain_name] stanzas

database-pathThis stanza entry specifies the file name and location of the policy database for the specified domain.database-path entrydomains stanzadatabase-path entrydomain=domain_name stanzaentriesdatabase-pathdomainsstanzadatabase-path entrydomain=domain_name stanzadatabase-path entrySyntax database-path = fully_qualified_path Description File name and location of the policy database for the specified domain. The name of the database is the same as the domain name. The file extension can be anything, but the extension is usually .db. Do not edit this entry. Options The fully_qualified_path value represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Conditional. This stanza entry is required when the user creates at least one domain. Default value The following table shows the default value by platform. database-path default value by platformPlatformFile nameLinux or UNIX/var/PolicyDirector/db/domain_name.dbWindowsc:\program files\tivoli\policy director\db\domain_name.db Example The following example shows the setting of the database path on a Windows operating system: d:\programs\ibm\am\db\dname1.db [domains] and [domain=domain_name] stanzasThe [domains] stanza contains a list of domains.

database-path

This stanza entry specifies the file name and location of the policy database for the specified domain.

Syntax

database-path = fully_qualified_path

Description

File name and location of the policy database for the specified domain. The name of the database is the same as the domain name. The file extension can be anything, but the extension is usually .db.

Note: Do not edit this entry.

Options

The fully_qualified_path value represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).

For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Conditional. This stanza entry is required when the user creates at least one domain.

Default value

The following table shows the default value by platform.

Table 175. database-path default value by platform

Platform | File name
Linux or UNIX | /var/PolicyDirector/db/domain_name.db
Windows | c:\program files\tivoli\policy director\db\domain_name.db

Example

The following example shows the setting of the database path on a Windows operating system:

d:\programs\ibm\am\db\dname1.db

Parent topic: [domains] and [domain=domain_name] stanzas

domainThis stanza entry specifies the name of the domain.domainentrydomains stanzadomainentrydomain=domain_name stanzaentriesdomaindomainsstanzadomain entrydomain=domain_name stanzadomain entrySyntax domain = domain_name Description Name of the domain that was created. Options The domain_name value is an alphanumeric, case-sensitive string. String values are expected to be characters that are part of the local code set. Usage Conditional. This stanza entry is required when the user creates at least one domain. Default value There is no default value. Example domain = mydomain1 [domains] and [domain=domain_name] stanzasThe [domains] stanza contains a list of domains.

domain

This stanza entry specifies the name of the domain.

Syntax

domain = domain_name

Description

Name of the domain that was created.

Options

The domain_name value is an alphanumeric, case-sensitive string. String values are expected to be characters that are part of the local code set.

Usage

Conditional. This stanza entry is required when the user creates at least one domain.

Default value

There is no default value.

Example

domain = mydomain1

Parent topic: [domains] and [domain=domain_name] stanzas

[ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file: stanzasivacldivacld stanzadescriptionThe [instance-]ivacld.conf configuration file for the authorization server Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].log-fileThis stanza entry specifies the location and name of the log file.logcfgThis stanza entry enables logging and auditing for the authorization component.permit-unauth-remote-callerThis stanza entry specifies whether authorization API clients must be authorized by the authorization server before their requests are processed.pid-fileThis stanza entry specifies the location and name of the PID file.tcp-req-portThis stanza entry specifies the Transmission Control Protocol (TCP) port on which the server is listening for requests.unix-userThis stanza entry specifies the Linux or UNIX user account for this server. unix-groupThis stanza entry specifies the Linux or UNIX group account for this server.

[ivacld] stanza

The stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

The [instance-]ivacld.conf configuration file for the authorization server

log-file
This stanza entry specifies the location and name of the log file.

logcfg
This stanza entry enables logging and auditing for the authorization component.

permit-unauth-remote-caller
This stanza entry specifies whether authorization API clients must be authorized by the authorization server before their requests are processed.

pid-file
This stanza entry specifies the location and name of the PID file.

tcp-req-port
This stanza entry specifies the Transmission Control Protocol (TCP) port on which the server is listening for requests.

unix-user
This stanza entry specifies the Linux or UNIX user account for this server.

unix-group
This stanza entry specifies the Linux or UNIX group account for this server.

Parent topic: Configuration file stanza reference

log-fileThis stanza entry specifies the location and name of the log file.log-file entryivacld stanzaentrieslog-fileivacld stanzalog-file entrySyntax log-file = fully_qualified_path Description Location and name of the log file. Messages are redirected from STDOUT and STDERR and sent to the server log file as defined in the authorization server routing file (pdacld_routing). The authorization server relies on the routing file to determine the log file names and path. At startup of the authorization server, a check is made to see whether the routing file exists. If it exists, the routing file is used and this stanza entry is ignored; otherwise, this stanza entry is used. Options The fully_qualified_path value represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. During installation of Security Access Manager, if you enabled Tivoli Common Directory to specify one common directory location for all your base component log files, the default installation directory is different. For example: log-file = TCD/HPD/logs /msg__pdacld_utf8.logThe three-character identifier used in the example is HPD, which specifies that the log files are for the Security Access Manager common components. Usage Required Default value The following table shows the default value by platform. log-file default value by platformPlatformFile nameLinux or UNIX/var/PolicyDirector/log/msg__pdacld_utf8.logWindowsc:\program files\tivoli\policy director\log\msg__pdacld_utf8.log Example The following example sets the log file as Tivoli Common Directory on a Windows operating system: log-file = C:\pd\log\msg__pdacld_utf8.log The following example sets the log file as Tivoli Common Directory on a AIX, Linux, or Solaris operating system: /PolicyDirector/TAMBase/HPD/logs/msg__pdacld_utf8.log [ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

log-file

This stanza entry specifies the location and name of the log file.

Syntax

log-file = fully_qualified_path

Description

Location and name of the log file. Messages are redirected from STDOUT and STDERR and sent to the server log file as defined in the authorization server routing file (pdacld_routing). The authorization server relies on the routing file to determine the log file names and path.

At startup of the authorization server, a check is made to see whether the routing file exists. If it exists, the routing file is used and this stanza entry is ignored; otherwise, this stanza entry is used.

Options

The fully_qualified_path value represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

During installation of Security Access Manager, if you enabled Tivoli Common Directory to specify one common directory location for all your base component log files, the default installation directory is different. For example:

log-file = TCD/HPD/logs
/msg__pdacld_utf8.log

The three-character identifier used in the example is HPD, which specifies that the log files are for the Security Access Manager common components.

Usage

Required

Default value

The following table shows the default value by platform.

Table 176. log-file default value by platform

Platform | File name
Linux or UNIX | /var/PolicyDirector/log/msg__pdacld_utf8.log
Windows | c:\program files\tivoli\policy director\log\msg__pdacld_utf8.log

Example

The following example sets the log file as Tivoli Common Directory on a Windows operating system:

log-file = C:\pd\log\msg__pdacld_utf8.log

The following example sets the log file as Tivoli Common Directory on a AIX, Linux, or Solaris operating system:

/PolicyDirector/TAMBase/HPD/logs/msg__pdacld_utf8.log

Parent topic: [ivacld] stanza

logcfgThis stanza entry enables logging and auditing for the authorization component.logcfg entryivacld stanzaivacld stanzalogcfg entrySyntax logcfg = audit.azn:{log-agent} path=path flush_interval=interval log_id Description Enables logging and auditing for the authorization component. Each server provides its own event logging setting in its corresponding configuration file. Options audit.aznCategory that specifies auditing of the authorization component.log-agentSpecifies that the destination where log-agent is one of the following values: stdoutstderrfilepiperemotepath = pathSpecifies the name and location of the log file that is used for the log-agent.flush_interval = intervalSpecifies the frequency for flushing log file buffers.log_id Specifies the identifier for directing events from additional categories to the same log-agent. Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application. Usage Optional Default value There is no default value. Example The following example shows the configuration for authentication and authorization auditing: logcfg = audit.azn:file path=/var/PolicyDirector/audit/ ivacld.log,flush_interval=20,log_id=PDAclAudit logcfg = audit.authn:file log_id=PDAclAudit [ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

logcfg

This stanza entry enables logging and auditing for the authorization component.

Syntax

logcfg = audit.azn:{log-agent} path=path
     flush_interval=interval log_id

Description

Enables logging and auditing for the authorization component.

Each server provides its own event logging setting in its corresponding configuration file.

Options

audit.azn

Category that specifies auditing of the authorization component.

log-agent

Specifies that the destination where log-agent is one of the following values:

stdout

stderr

file

pipe

remote

path = path

Specifies the name and location of the log file that is used for the log-agent.

flush_interval = interval

Specifies the frequency for flushing log file buffers.

log_id

Specifies the identifier for directing events from additional categories to the same log-agent.

Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application.

Usage

Optional

Default value

There is no default value.

Example

The following example shows the configuration for authentication and authorization auditing:

logcfg = audit.azn:file path=/var/PolicyDirector/audit/
      ivacld.log,flush_interval=20,log_id=PDAclAudit
logcfg = audit.authn:file log_id=PDAclAudit

Parent topic: [ivacld] stanza

permit-unauth-remote-callerThis stanza entry specifies whether authorization API clients must be authorized by the authorization server before their requests are processed.permit-unauth-remote-caller entryentriespermit-unauth-remote-callerivacld stanzapermit-unauth-remote-caller entrySyntax permit-unauth-remote-caller= {true|false} Description Specification of whether authorization API clients must be authorized by the authorization server before their requests are processed. Options trueAuthorization API clients are not authorized. Specifying true exposes the policy database in the domain for all clients to read, not just those clients that were properly authorized with membership in the remote-acl-users group. Depending on the policy within the domain security, system planners must consider the ability for any client to read system-defined policy to be a security problem.falseAuthorization API clients are authorized. Usage Optional Default value false Example permit-unauth-remote-caller= false [ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

permit-unauth-remote-caller

This stanza entry specifies whether authorization API clients must be authorized by the authorization server before their requests are processed.

Syntax

permit-unauth-remote-caller= {true|false}

Description

Specification of whether authorization API clients must be authorized by the authorization server before their requests are processed.

Options

true

Authorization API clients are not authorized.

Attention: Specifying true exposes the policy database in the domain for all clients to read, not just those clients that were properly authorized with membership in the remote-acl-users group. Depending on the policy within the domain security, system planners must consider the ability for any client to read system-defined policy to be a security problem.

false

Authorization API clients are authorized.

Usage

Optional

Default value

false

Example

permit-unauth-remote-caller= false

Parent topic: [ivacld] stanza

pid-fileThis stanza entry specifies the location and name of the PID file.pid-file entryivacld stanzaentriespid-fileivacld stanzapid-file entrySyntax pid-file = fully_qualified_path Description Location and name of the PID file. Options fully_qualified_pathRepresents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Required Default value The following table shows the default value by platform. pid-file default value by platformPlatformFile nameLinux or UNIX/var/PolicyDirector/log/ivacld.pidWindowsc:\progra files\tivoli\policy director\log\ivacld.pid Example Example for a Windows operating system: pid-file = C:\pd\log\ivacld.pid [ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

pid-file

This stanza entry specifies the location and name of the PID file.

Syntax

pid-file = fully_qualified_path

Description

Location and name of the PID file.

Options

fully_qualified_path

Represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Required

Default value

The following table shows the default value by platform.

Table 177. pid-file default value by platform

Platform | File name
Linux or UNIX | /var/PolicyDirector/log/ivacld.pid
Windows | c:\progra files\tivoli\policy director\log\ivacld.pid

Example

Example for a Windows operating system:

pid-file = C:\pd\log\ivacld.pid

Parent topic: [ivacld] stanza

tcp-req-portThis stanza entry specifies the Transmission Control Protocol (TCP) port on which the server is listening for requests.tcp-req-port entryivacld stanzaentriestcp-req-portivacld stanzatcp-req-port entrySyntax tcp-req-port = {0|port} Description Transmission Control Protocol (TCP) port on which the server is listening for requests. Options 0Disable the port number.portEnable the port number. Use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default value, or use a port over 1000 that is not currently being used. Usage Required Default value 7136 Example tcp-req-port = 7136 [ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

tcp-req-port

This stanza entry specifies the Transmission Control Protocol (TCP) port on which the server is listening for requests.

Syntax

tcp-req-port = {0|port}

Description

Transmission Control Protocol (TCP) port on which the server is listening for requests.

Options

0

Disable the port number.

port

Enable the port number. Use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default value, or use a port over 1000 that is not currently being used.

Usage

Required

Default value

7136

Example

tcp-req-port = 7136

Parent topic: [ivacld] stanza

unix-userThis stanza entry specifies the Linux or UNIX user account for this server. unix-user entryivacld stanzaentriesunix-userivacld stanzaunix-user entrySyntax unix-user = user_name Description The Linux or UNIX user account for this server. The server will run as this user account. Options The user_name value represents an alphabetic string for the name associated with the user account. Usage Required Default value ivmgr Example unix-user = ivmgr [ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

unix-user

This stanza entry specifies the Linux or UNIX user account for this server.

Syntax

unix-user = user_name

Description

The Linux or UNIX user account for this server. The server will run as this user account.

Options

The user_name value represents an alphabetic string for the name associated with the user account.

Usage

Required

Default value

ivmgr

Example

unix-user = ivmgr

Parent topic: [ivacld] stanza

unix-groupThis stanza entry specifies the Linux or UNIX group account for this server.unix-group entryivacld stanzaentriesunix-groupivacld stanzaunix-group entrySyntax unix-group = group_name Description The Linux or UNIX group account for this server. The server runs as this account. Options The group_name value represents an alphabetic string for the group associated with the user account. Usage Required Default value ivmgr Example unix-group = ivmgr [ivacld] stanzaThe stanza entries for configuring authorization server-related information are in the [ivacld] stanza in the following configuration file:

unix-group

This stanza entry specifies the Linux or UNIX group account for this server.

Syntax

unix-group = group_name

Description

The Linux or UNIX group account for this server. The server runs as this account.

Options

The group_name value represents an alphabetic string for the group associated with the user account.

Usage

Required

Default value

ivmgr

Example

unix-group = ivmgr

Parent topic: [ivacld] stanza

[ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:ivmgrd stanzadescriptionstanzasivmgrdThe ivmgrd.conf configuration file for the policy serverConfiguration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].provide-last-loginThis stanza entry specifies whether to report information about the last login instance of a user.provide-last-pwd-changeThis stanza entry specifies whether to report information about the last password change instance of a user.auto-database-update-notifyThis stanza entry specifies automatic or manual update notification for policy database replicas.ca-cert-download-enabledThis stanza entry specifies whether the CA certificate can be downloaded.database-pathThis stanza entry specifies the location and name of the master policy database.log-fileThis stanza entry specifies the location and name of the log file.logcfgThis stanza entry enables logging and auditing for the application.max-notifier-threadsThis stanza entry specifies the maximum number of event notifier threads.notifier-wait-timeThis stanza entry specifies the time in seconds that the authorization policy database is idle before notification is sent to replicas.pid-fileThis stanza entry specifies the location and name of the PID file.standbyThis stanza entry specifies the number of standby policy servers.tcp-req-portThis stanza entry specifies the TCP port on which the server is listening for requests.unix-userThis stanza entry specifies the Linux or UNIX user account for this server.unix-groupThis stanza entry specifies the Linux or UNIX group account for this server. am610compatThis stanza entry maintains compatibility with applications developed for previous Security Access Manager versions.

[ivmgrd] stanza

The stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

The ivmgrd.conf configuration file for the policy server

provide-last-login
This stanza entry specifies whether to report information about the last login instance of a user.

provide-last-pwd-change
This stanza entry specifies whether to report information about the last password change instance of a user.

auto-database-update-notify
This stanza entry specifies automatic or manual update notification for policy database replicas.

ca-cert-download-enabled
This stanza entry specifies whether the CA certificate can be downloaded.

database-path
This stanza entry specifies the location and name of the master policy database.

log-file
This stanza entry specifies the location and name of the log file.

logcfg
This stanza entry enables logging and auditing for the application.

max-notifier-threads
This stanza entry specifies the maximum number of event notifier threads.

notifier-wait-time
This stanza entry specifies the time in seconds that the authorization policy database is idle before notification is sent to replicas.

pid-file
This stanza entry specifies the location and name of the PID file.

standby
This stanza entry specifies the number of standby policy servers.

tcp-req-port
This stanza entry specifies the TCP port on which the server is listening for requests.

unix-user
This stanza entry specifies the Linux or UNIX user account for this server.

unix-group
This stanza entry specifies the Linux or UNIX group account for this server.

am610compat
This stanza entry maintains compatibility with applications developed for previous Security Access Manager versions.

Parent topic: Configuration file stanza reference

provide-last-loginThis stanza entry specifies whether to report information about the last login instance of a user.provide-last-login entryentriesprovide-last-loginivmgrd stanzaprovide-last-login entrySyntax provide-last-login = {yes|true|no|false} Description Use the provide-last-login option for reporting information about the last login instance of a user. To record the last login information for LDAP-based registries, set [ldap] enable-last-login to yes. For Microsoft Active Directory registry, Security Access Manager uses the Active Directory user attribute lastLogonTimestamp to report the last login time of the user. This attribute is a system attribute and is updated automatically by Active Directory. Security Access Manager has no control over this attribute except reporting the value when required. This attribute is not updated every time a user logs in successfully. When a user logs in successfully, this attribute is only updated if its current value is older than the current time minus the value of the msDS-LogonTimeSyncInterval attribute. The value that Security Access Manager reports for the last login of a user might not be the exact time that a user last logged in. The reported time might be the actual last login time minus the configurable value of msDS-LogonTimeSyncInterval. You can configure the default value of msDS-LogonTimeSyncInterval to suit the user domain policy. To use the lastLogonTimestamp attribute, the Active Directory domains must be at or greater than Microsoft Windows 2003 domain functional level. For more information about lastLogonTimestamp and msDS-LogonTimeSyncInterval, visit the Microsoft support website. Options yes|trueSet the provide-last-login option to yes, to specify that the policy server reports the time of last login of a user.no|falseSet the provide-last-login option to no, to disable reporting of the last login information about a user. [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

provide-last-login

This stanza entry specifies whether to report information about the last login instance of a user.

Syntax

provide-last-login = {yes|true|no|false}

Description

Use the provide-last-login option for reporting information about the last login instance of a user.

To record the last login information for LDAP-based registries, set [ldap] enable-last-login to yes.

For Microsoft Active Directory registry, Security Access Manager uses the Active Directory user attribute lastLogonTimestamp to report the last login time of the user. This attribute is a system attribute and is updated automatically by Active Directory. Security Access Manager has no control over this attribute except reporting the value when required. This attribute is not updated every time a user logs in successfully. When a user logs in successfully, this attribute is only updated if its current value is older than the current time minus the value of the msDS-LogonTimeSyncInterval attribute.

The value that Security Access Manager reports for the last login of a user might not be the exact time that a user last logged in. The reported time might be the actual last login time minus the configurable value of msDS-LogonTimeSyncInterval. You can configure the default value of msDS-LogonTimeSyncInterval to suit the user domain policy.

To use the lastLogonTimestamp attribute, the Active Directory domains must be at or greater than Microsoft Windows 2003 domain functional level. For more information about lastLogonTimestamp and msDS-LogonTimeSyncInterval, visit the Microsoft support website.

Options

yes|true

Set the provide-last-login option to yes, to specify that the policy server reports the time of last login of a user.

no|false

Set the provide-last-login option to no, to disable reporting of the last login information about a user.

Parent topic: [ivmgrd] stanza

provide-last-pwd-changeThis stanza entry specifies whether to report information about the last password change instance of a user.provide-last-pwd-change entryentriesprovide-last-pwd-changeivmgrd stanzaprovide-last-pwd-change entrySyntax provide-last-pwd-change = {yes|true|no|false} Description Use the provide-last-pwd-change option to permit reporting of information about the last password change instance of a user. Options yes|trueSet the provide-last-pwd-change option to yes, to specify that the policy server reports the last password change instance of a user.no|falseSet the provide-last-pwd-change option to no, to disable reporting of the last password change instance of a user. [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

provide-last-pwd-change

This stanza entry specifies whether to report information about the last password change instance of a user.

Syntax

provide-last-pwd-change = {yes|true|no|false}

Description

Use the provide-last-pwd-change option to permit reporting of information about the last password change instance of a user.

Options

yes|true

Set the provide-last-pwd-change option to yes, to specify that the policy server reports the last password change instance of a user.

no|false

Set the provide-last-pwd-change option to no, to disable reporting of the last password change instance of a user.

Parent topic: [ivmgrd] stanza

auto-database-update-notifyThis stanza entry specifies automatic or manual update notification for policy database replicas.auto-database-update-notify entryentriesauto-database-update-notifyivmgrd stanzaauto-database-update-notify entrySyntax auto-database-update-notify = {yes|true|no|false} Description Specification of automatic or manual update notification for policy database replicas. Options yes|trueEnable automatic update notification. This automatic setting is appropriate for environments where database changes are few and infrequent. When you configure update notification to be automatic, you must also correctly configure the max-notifier-threads= and notifier-wait-time= stanza entries.no|falseEnable manual update notification. Usage Required Default value yes Example auto-database-update-notify = yes [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

auto-database-update-notify

This stanza entry specifies automatic or manual update notification for policy database replicas.

Syntax

auto-database-update-notify = {yes|true|no|false}

Description

Specification of automatic or manual update notification for policy database replicas.

Options

yes|true

Enable automatic update notification. This automatic setting is appropriate for environments where database changes are few and infrequent. When you configure update notification to be automatic, you must also correctly configure the max-notifier-threads= and notifier-wait-time= stanza entries.

no|false

Enable manual update notification.

Usage

Required

Default value

yes

Example

auto-database-update-notify = yes

Parent topic: [ivmgrd] stanza

ca-cert-download-enabledThis stanza entry specifies whether the CA certificate can be downloaded.ca-cert-download-enabled entryentriesca-cert-download-enabledivmgrd stanzaca-cert-download-enabled entrySyntax ca-cert-download-enabled = {yes|no} Description The policy server always allows the download of the CA certificate. It is up to the client application to allow whether the CA certificate can be downloaded. Independent of the defined value, the policy server ignores this configuration setting. Usage Ignored [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

ca-cert-download-enabled

This stanza entry specifies whether the CA certificate can be downloaded.

Syntax

ca-cert-download-enabled = {yes|no}

Description

The policy server always allows the download of the CA certificate. It is up to the client application to allow whether the CA certificate can be downloaded. Independent of the defined value, the policy server ignores this configuration setting.

Usage

Ignored

Parent topic: [ivmgrd] stanza

database-pathThis stanza entry specifies the location and name of the master policy database.database-path entryivmgrd stanzaivmgrd stanzadatabase-pathSyntax database-path = fully_qualified_path Description Location and name of the master policy database. The file extension can be anything, but the extension is usually .db. Do not edit this stanza entry. Options fully_qualified_pathRepresents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Required Default value The following table shows the default value by platform. PlatformFile nameLinux or UNIX/var/PolicyDirector/db/master_authzn.dbWindowsc:\program files\tivoli\policy director\db\master_authzn.db Example The following example set the path to the master policy database on a Windows operating system: database-path = C:\pd\db\master_authzn.db [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

database-path

This stanza entry specifies the location and name of the master policy database.

Syntax

database-path = fully_qualified_path

Description

Location and name of the master policy database. The file extension can be anything, but the extension is usually .db.

Note: Do not edit this stanza entry.

Options

fully_qualified_path

Represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Required

Default value

The following table shows the default value by platform.

Platform | File name
Linux or UNIX | /var/PolicyDirector/db/master_authzn.db
Windows | c:\program files\tivoli\policy director\db\master_authzn.db

Example

The following example set the path to the master policy database on a Windows operating system:

database-path = C:\pd\db\master_authzn.db

Parent topic: [ivmgrd] stanza

log-fileThis stanza entry specifies the location and name of the log file.log-file entryivmgrd stanzaivmgrd stanzalog-file entrySyntax log-file = fully_qualified_path Description Location and name of the log file. Messages are redirected from STDOUT and STDERR and sent to the server log file as defined in the policy server routing file ([instance-]pdmgrd_routing). The policy server relies on the routing file to determine the log file names and path. At startup of the policy server, a check is made to see whether the routing file exists. If it exists, the routing file is used and this stanza entry is ignored; otherwise, this stanza entry is used. Options The fully_qualified_path value represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Required Default value The following table shows the default value by platform. [ivmgrd] stanza log-file default value by platformPlatformFile nameLinux or UNIX/var/PolicyDirector/log/msg__pdmgrd_utf8.logWindowsc:\program files\tivoli\policy director\log\msg__pdmgrd_utf8.log During an installation of Security Access Manager, if you enabled Tivoli Common Directory to specify one common directory location for all your log files, the default installation directory is different. Example The following example sets the log file on a Windows operating system without Tivoli Common Directory: log-file = C:\pd\log\msg__pdmgrd_utf8.log The following example sets the log file on a AIX, Linux, or Solaris operating system with Tivoli Common Directory: log-file = TCD_directory/HPD/logs/msg__pdmgrd_utf8.logThe three-character identifier used in the example is HPD, which specifies that the log files are for Security Access Manager. [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

log-file

This stanza entry specifies the location and name of the log file.

Syntax

log-file = fully_qualified_path

Description

Location and name of the log file. Messages are redirected from STDOUT and STDERR and sent to the server log file as defined in the policy server routing file ([instance-]pdmgrd_routing). The policy server relies on the routing file to determine the log file names and path.

At startup of the policy server, a check is made to see whether the routing file exists. If it exists, the routing file is used and this stanza entry is ignored; otherwise, this stanza entry is used.

Options

The fully_qualified_path value represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).

For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Required

Default value

The following table shows the default value by platform.

Table 178. [ivmgrd] stanza log-file default value by platform

Platform | File name
Linux or UNIX | /var/PolicyDirector/log/msg__pdmgrd_utf8.log
Windows | c:\program files\tivoli\policy director\log\msg__pdmgrd_utf8.log

During an installation of Security Access Manager, if you enabled Tivoli Common Directory to specify one common directory location for all your log files, the default installation directory is different.

Example

The following example sets the log file on a Windows operating system without Tivoli Common Directory:

log-file = C:\pd\log\msg__pdmgrd_utf8.log

The following example sets the log file on a AIX, Linux, or Solaris operating system with Tivoli Common Directory:

log-file = TCD_directory/HPD/logs/msg__pdmgrd_utf8.log

The three-character identifier used in the example is HPD, which specifies that the log files are for Security Access Manager.

Parent topic: [ivmgrd] stanza

logcfgThis stanza entry enables logging and auditing for the application.logcfg entryivmgrd stanzaivmgrd stanzalogcfg entrySyntax logcfg = audit.azn:{log-agent} path=path flush_interval=interval log_id Description Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events. Each server provides its own event logging setting in its corresponding configuration file. Options audit.aznCategory that specifies auditing of the authorization component.log-agentSpecifies that the destination where log-agent is one of the following values: stdoutstderrfilepiperemotepath = pathSpecifies the name and location of the log file that is used for the log-agent.flush_interval = intervalSpecifies the frequency for flushing log file buffers.log_id Specifies the identifier for directing events from additional categories to the same log-agent. Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application. Usage Optional Default value There is no default value. Example The following example sets the configuration for authentication and authorization auditing only: logcfg = audit.azn:file path=/var/PolicyDirector/audit/ pdmgrd.log,flush_interval=20,log_id=PDMgrAudit logcfg = audit.authn:file log_id=PDMgrAudit #logcfg = audit.mgmt:file log_id=PDMgrAudit [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

logcfg

This stanza entry enables logging and auditing for the application.

Syntax

logcfg = audit.azn:{log-agent} path=path
     flush_interval=interval log_id

Description

Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events.

Each server provides its own event logging setting in its corresponding configuration file.

Options

audit.azn

Category that specifies auditing of the authorization component.

log-agent

Specifies that the destination where log-agent is one of the following values:

stdout

stderr

file

pipe

remote

path = path

Specifies the name and location of the log file that is used for the log-agent.

flush_interval = interval

Specifies the frequency for flushing log file buffers.

log_id

Specifies the identifier for directing events from additional categories to the same log-agent.

Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application.

Usage

Optional

Default value

There is no default value.

Example

The following example sets the configuration for authentication and authorization auditing only:

logcfg = audit.azn:file path=/var/PolicyDirector/audit/
     pdmgrd.log,flush_interval=20,log_id=PDMgrAudit
logcfg = audit.authn:file log_id=PDMgrAudit
#logcfg = audit.mgmt:file log_id=PDMgrAudit

Parent topic: [ivmgrd] stanza

max-notifier-threadsThis stanza entry specifies the maximum number of event notifier threads.max-notifier-threads entryentriesmax-notifier-threadsivmgrd stanzamax-notifier-threads entrySyntax max-notifier-threads = number_threads Description Maximum number of event notifier threads. The policy server is responsible for synchronizing all database replicas in the secure domain. When a change is made to the master database, notification threads do the work of announcing this change to all replicas. Each replica then has the responsibility to download the new information from the master. When the update notification stanza entry is set to yes, you must correctly configure this stanza entry and also the notifier-wait-time= stanza entry. Options number_threadsSet this value to equal the number of existing replicas. Specify a valid, positive whole number. Valid range for the number of threads is 1 - 128. Usage Conditional. This stanza entry is required when auto-database-update-notify = yes. Default value 10 Example max-notifier-threads = 20 [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

max-notifier-threads

This stanza entry specifies the maximum number of event notifier threads.

Syntax

max-notifier-threads = number_threads

Description

Maximum number of event notifier threads. The policy server is responsible for synchronizing all database replicas in the secure domain. When a change is made to the master database, notification threads do the work of announcing this change to all replicas. Each replica then has the responsibility to download the new information from the master.

When the update notification stanza entry is set to yes, you must correctly configure this stanza entry and also the notifier-wait-time= stanza entry.

Options

number_threads

Set this value to equal the number of existing replicas. Specify a valid, positive whole number. Valid range for the number of threads is 1 - 128.

Usage

Conditional. This stanza entry is required when auto-database-update-notify = yes.

Default value

10

Example

max-notifier-threads = 20

Parent topic: [ivmgrd] stanza

notifier-wait-timeThis stanza entry specifies the time in seconds that the authorization policy database is idle before notification is sent to replicas.notifier-wait-time entryentriesnotifier-wait-timeivmgrd stanzanotifier-wait-time entrySyntax notifier-wait-time = time_seconds Description Time in seconds that the authorization policy database is idle before notification is sent to replicas. When the policy server is instructed to change the master policy database, it waits for a default period before sending out notifications to database replicas. This time delay is reset with each subsequent change to the database. When the update notification stanza entry is set to yes, you must correctly configure this stanza entry and also the max-notifier-threads= stanza entry. Options time_secondsThe number of seconds the authorization policy database is idle before notification is sent to replicas. Usage Conditional. This stanza entry is required when the auto-database-update-notify = yes. Default value 15 Example notifier-wait-time = 30 [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

notifier-wait-time

This stanza entry specifies the time in seconds that the authorization policy database is idle before notification is sent to replicas.

Syntax

notifier-wait-time = time_seconds

Description

Time in seconds that the authorization policy database is idle before notification is sent to replicas. When the policy server is instructed to change the master policy database, it waits for a default period before sending out notifications to database replicas. This time delay is reset with each subsequent change to the database.

When the update notification stanza entry is set to yes, you must correctly configure this stanza entry and also the max-notifier-threads= stanza entry.

Options

time_seconds

The number of seconds the authorization policy database is idle before notification is sent to replicas.

Usage

Conditional. This stanza entry is required when the auto-database-update-notify = yes.

Default value

15

Example

notifier-wait-time = 30

Parent topic: [ivmgrd] stanza

pid-fileThis stanza entry specifies the location and name of the PID file.pid-file entryivmgrd stanzaivmgrd stanzapid-file entrySyntax pid-file = fully_qualified_path Description Location and name of the PID file. Options fully_qualified_pathRepresents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Required Default value The following table shows the default value by platform. [ivmgrd] stanza pid-file default value by platformPlatformFile nameLinux or UNIX/var/PolicyDirector/log/ivmgrd.pidWindowsc:\program files\tivoli\policy director\log\ivmgrd.pid Example Example for a AIX, Linux, or Solaris operating system: pid-file = /var/PolicyDirector/log/ivmgrd.pid [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

pid-file

This stanza entry specifies the location and name of the PID file.

Syntax

pid-file = fully_qualified_path

Description

Location and name of the PID file.

Options

fully_qualified_path

Represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).

For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Required

Default value

The following table shows the default value by platform.

Table 179. [ivmgrd] stanza pid-file default value by platform

Platform | File name
Linux or UNIX | /var/PolicyDirector/log/ivmgrd.pid
Windows | c:\program files\tivoli\policy director\log\ivmgrd.pid

Example

Example for a AIX, Linux, or Solaris operating system:

pid-file = /var/PolicyDirector/log/ivmgrd.pid

Parent topic: [ivmgrd] stanza

standbyThis stanza entry specifies the number of standby policy servers.standby entryentriesstandbyivmgrd stanzastandby entrySyntax standby = {0|number} Description Specifies the number of standby policy servers. The number of standby servers is generated and set by the configuration utility. Do not edit this stanza entry. Options 0Zero specifies that no policy servers are standby servers.numberThe number of standby policy servers. Use a number that is a positive whole number. Currently, this number is only 1. Usage Required Default value 0 Example standby = 1 [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

standby

This stanza entry specifies the number of standby policy servers.

Syntax

standby = {0|number}

Description

Specifies the number of standby policy servers.

Note: The number of standby servers is generated and set by the configuration utility. Do not edit this stanza entry.

Options

0

Zero specifies that no policy servers are standby servers.

number

The number of standby policy servers. Use a number that is a positive whole number. Currently, this number is only 1.

Usage

Required

Default value

0

Example

standby = 1

Parent topic: [ivmgrd] stanza

tcp-req-portThis stanza entry specifies the TCP port on which the server is listening for requests.tcp-req-port entryivmgrd stanzaivmgrd stanzatcp-req-port entrySyntax tcp-req-port = {0|port} Description TCP port on which the server is listening for requests. Options 0Disables the port number.portEnables the port number. Specify any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number, or use a port number over 1024 that is currently not being used. Usage Required Default value 8135 Example tcp-req-port = 8135 [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

tcp-req-port

This stanza entry specifies the TCP port on which the server is listening for requests.

Syntax

tcp-req-port = {0|port}

Description

TCP port on which the server is listening for requests.

Options

0

Disables the port number.

port

Enables the port number. Specify any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number, or use a port number over 1024 that is currently not being used.

Usage

Required

Default value

8135

Example

tcp-req-port = 8135

Parent topic: [ivmgrd] stanza

unix-userThis stanza entry specifies the Linux or UNIX user account for this server.unix-user entryivmgrd stanzaentriesunix-userivmgrd stanzaunix-user entrySyntax unix-user = user_name Description The Linux or UNIX user account for this server. The server runs as this account. Options user_nameRepresents an alphabetic string for the name associated with the user account. Usage Required Default value ivmgr Example unix-user = ivmgr [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

unix-user

This stanza entry specifies the Linux or UNIX user account for this server.

Syntax

unix-user = user_name

Description

The Linux or UNIX user account for this server. The server runs as this account.

Options

user_name

Represents an alphabetic string for the name associated with the user account.

Usage

Required

Default value

ivmgr

Example

unix-user = ivmgr

Parent topic: [ivmgrd] stanza

unix-groupThis stanza entry specifies the Linux or UNIX group account for this server. unix-group entryivmgrd stanzaivmgrd stanzaunix-group entrySyntax unix-group = group_name Description The Linux or UNIX group account for this server. The server runs as this account. Options group_nameRepresents an alphabetic string for the group associated with the user account. Usage Required Default value ivmgr Example unix-group = ivmgr [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

unix-group

This stanza entry specifies the Linux or UNIX group account for this server.

Syntax

unix-group = group_name

Description

The Linux or UNIX group account for this server. The server runs as this account.

Options

group_name

Represents an alphabetic string for the group associated with the user account.

Usage

Required

Default value

ivmgr

Example

unix-group = ivmgr

Parent topic: [ivmgrd] stanza

am610compatam610compat optionThis stanza entry maintains compatibility with applications developed for previous Security Access Manager versions. am610compat entryentriesam610compativmgrd stanzaam610compat entrySyntax am610compat = yes Description Maintains compatibility with applications developed for previous Security Access Manager versions. The policy server causes the system to follow the previous behavior of applications that assume no errors are thrown. Options yesIf set to yes, the command does not return an error if the specified user does not exist. The system returns the value none instead.noIf set to no, the command returns an error if the user does not exist. Usage The am610compat configuration item is for the ivmgrd.conf policy server configuration file.Th configuration item affects the pdadmin commands where the -user <user-name> is supplied.See the pdadmin commands policy get section of the IBM Security Access Manager Command Reference Guide for details.If the user specified by the command does not exist, it returns the value none. Default value yes for migrated systemsno for new installationsExample am610compat = yes [ivmgrd] stanzaThe stanza entries for configuring the policy server and policy database are in the [ivmgrd] stanza in this configuration file:

am610compat

This stanza entry maintains compatibility with applications developed for previous Security Access Manager versions.

Syntax

am610compat = yes

Description

Maintains compatibility with applications developed for previous Security Access Manager versions. The policy server causes the system to follow the previous behavior of applications that assume no errors are thrown.

Options

yes

If set to yes, the command does not return an error if the specified user does not exist. The system returns the value none instead.

no

If set to no, the command returns an error if the user does not exist.

Usage

The am610compat configuration item is for the ivmgrd.conf policy server configuration file.

Th configuration item affects the pdadmin commands where the -user <user-name> is supplied.

See the pdadmin commands policy get section of the IBM® Security Access Manager Command Reference Guide for details.

If the user specified by the command does not exist, it returns the value none.

Default value

yes for migrated systems

no for new installations

Example

am610compat = yes

Parent topic: [ivmgrd] stanza

[ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.ldap stanzauser registrystanzasldapldap stanzaivmgrd.confldap stanzaivacld.confThe value for the user registry stanza entry (ldap-server-config) is determined by the pd.conf file. The pd.conf file is created when the IBM Security Access Manager runtime component is configured.The key value pairs that are used only for the LDAP registry server are in the ldap.conf configuration file in the [ldap] stanza. The LDAP server stanza entries are described separately in [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza..The key value pairs that are for the server configuration files are in the [ldap] stanza of each of the following configuration files: The ivmgrd.conf configuration file for the policy serverThe [instance-]ivacld.conf configuration file for the authorization serverYour resource managers' configuration file for configured LDAP entries The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].enhanced-pwd-policyThis stanza entry specifies whether the LDAP registries that Security Access Manager uses provide password policy enforcement for LDAP accounts.max-auth-connectionsThis stanza entry specifies how many simultaneous connections to your LDAP server are permitted for user authentication.enable-last-loginThis stanza entry specifies whether to store the last login information of a user in LDAP.auth-using-compareThis stanza entry specifies whether ldap_compare() is used instead of the ldap_bind() call to verify the password and authenticate the user.authn-timeoutThis stanza entry specifies the amount of time (in seconds) for authentication operations before the LDAP server is considered down. bind-dnThis stanza entry specifies the LDAP user distinguished name (DN) that is used when binding (signing on) to the LDAP server.cache-enabledThis stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries.cache-group-expire-timeThis stanza entry specifies the amount of time (in seconds) until a group entry in the cache is considered stale and is discarded.cache-group-membershipThis stanza entry specifies whether group membership information is cached.cache-group-sizeThis stanza entry specifies the number of entries in the LDAP group cache.cache-policy-expire-timeThis stanza entry specifies the amount of time in seconds until a policy entry in the cache is considered stale and is discarded.cache-policy-sizeThis stanza entry specifies the number of entries in the LDAP policy cache.cache-return-registry-idThis stanza entry specifies whether the LDAP cache returns the Security Access Manager user identity as it is stored in the registry or the value entered by the user.cache-use-user-cacheThis stanza entry specifies whether to use the user cache information.cache-user-expire-timeThis stanza entry specifies the amount of time in seconds until a user entry in the cache is considered stale and is discarded.cache-user-sizeThis stanza entry specifies the number of entries in the LDAP user cache.default-policy-override-supportThis stanza entry specifies whether user-level policy support can be used.ldap-server-configThis stanza entry specifies the location of the ldap.conf configuration file. login-failures-persistentThis stanza entry specifies whether the tracking of login failures is persistent (maintained in the registry) or done in the local process cache.max-search-sizeThis stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.portThis stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.prefer-readwrite-serverThis stanza entry specifies whether the client can question the read/write LDAP server before querying any replica read-only servers that are configured in the domain. search-timeoutThis stanza entry specifies the amount of time in seconds that is allowed for search operations before the LDAP server is considered to be down.ssl-enabledThis stanza entry specifies whether the Security Access Manager server uses SSL to communicate with the LDAP server.ssl-keyfileThis stanza entry specifies the SSL key file name and location.ssl-keyfile-dnThis stanza entry specifies the key label of the client certificate within the SSL key file.ssl-keyfile-pwdThis stanza entry is deprecated. The ssl-keyfile-pwd entry is deprecated in the [ldap] stanza. Although this entry might exist in a configuration file, it is ignored.user-and-group-in-same-suffixThis stanza entry specifies whether the groups in which a user is a member are defined in the same LDAP suffix as the user definition.

[ldap] stanza

This stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

The value for the user registry stanza entry (ldap-server-config) is determined by the pd.conf file. The pd.conf file is created when the IBM Security Access Manager runtime component is configured.

The key value pairs that are used only for the LDAP registry server are in the ldap.conf configuration file in the [ldap] stanza. The LDAP server stanza entries are described separately in [ldap] stanza for ldap.conf.

The key value pairs that are for the server configuration files are in the [ldap] stanza of each of the following configuration files:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

Your resource managers' configuration file for configured LDAP entries

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

enhanced-pwd-policy
This stanza entry specifies whether the LDAP registries that Security Access Manager uses provide password policy enforcement for LDAP accounts.

max-auth-connections
This stanza entry specifies how many simultaneous connections to your LDAP server are permitted for user authentication.

enable-last-login
This stanza entry specifies whether to store the last login information of a user in LDAP.

auth-using-compare
This stanza entry specifies whether ldap_compare() is used instead of the ldap_bind() call to verify the password and authenticate the user.

authn-timeout
This stanza entry specifies the amount of time (in seconds) for authentication operations before the LDAP server is considered down.

bind-dn
This stanza entry specifies the LDAP user distinguished name (DN) that is used when binding (signing on) to the LDAP server.

cache-enabled
This stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries.

cache-group-expire-time
This stanza entry specifies the amount of time (in seconds) until a group entry in the cache is considered stale and is discarded.

cache-group-membership
This stanza entry specifies whether group membership information is cached.

cache-group-size
This stanza entry specifies the number of entries in the LDAP group cache.

cache-policy-expire-time
This stanza entry specifies the amount of time in seconds until a policy entry in the cache is considered stale and is discarded.

cache-policy-size
This stanza entry specifies the number of entries in the LDAP policy cache.

cache-return-registry-id
This stanza entry specifies whether the LDAP cache returns the Security Access Manager user identity as it is stored in the registry or the value entered by the user.

cache-use-user-cache
This stanza entry specifies whether to use the user cache information.

cache-user-expire-time
This stanza entry specifies the amount of time in seconds until a user entry in the cache is considered stale and is discarded.

cache-user-size
This stanza entry specifies the number of entries in the LDAP user cache.

default-policy-override-support
This stanza entry specifies whether user-level policy support can be used.

ldap-server-config
This stanza entry specifies the location of the ldap.conf configuration file.

login-failures-persistent
This stanza entry specifies whether the tracking of login failures is persistent (maintained in the registry) or done in the local process cache.

max-search-size
This stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.

port
This stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.

prefer-readwrite-server
This stanza entry specifies whether the client can question the read/write LDAP server before querying any replica read-only servers that are configured in the domain.

search-timeout
This stanza entry specifies the amount of time in seconds that is allowed for search operations before the LDAP server is considered to be down.

ssl-enabled
This stanza entry specifies whether the Security Access Manager server uses SSL to communicate with the LDAP server.

ssl-keyfile
This stanza entry specifies the SSL key file name and location.

ssl-keyfile-dn
This stanza entry specifies the key label of the client certificate within the SSL key file.

ssl-keyfile-pwd
This stanza entry is deprecated. The ssl-keyfile-pwd entry is deprecated in the [ldap] stanza. Although this entry might exist in a configuration file, it is ignored.

user-and-group-in-same-suffix
This stanza entry specifies whether the groups in which a user is a member are defined in the same LDAP suffix as the user definition.

Parent topic: Configuration file stanza reference

enhanced-pwd-policyThis stanza entry specifies whether the LDAP registries that Security Access Manager uses provide password policy enforcement for LDAP accounts.enhanced-pwd-policyentryentriesenhanced-pwd-policyldap stanzaenhanced-pwd-policy entrySyntax enhanced-pwd-policy = {yes|true|no|false} Description The appliance embedded LDAP server does not support this configuration option. Security Access Manager uses LDAP account passwords for authentication. This means that Security Access Manager is subject to LDAP registry password policies. When the enhanced-pwd-policy option is enabled, Security Access Manager efficiently identifies the underlying LDAP registry password policy and reacts appropriately. The Security Access Manager password policy is enforced concurrently and is not affected by the enhanced-pwd-policy option.This option is supported for Sun Directory Server 6.3.1 and Security Directory Server. For Security Directory Server with the enhanced-pwd-policy option disabled, Security Access Manager provides only limited support for handling LDAP registry password policies. The enhanced-pwd-policy option enhances such support.When you set the auth-using-compare option to no, a user password is authenticated by creating a connection to the LDAP registry and binding the connection with the user password. Success or failure of the binding is noted and the connection is closed. If you set the enhanced-pwd-policy option is set to yes when auth-using-compare is set to no, the user password changes occur on the connection that is used to authenticate the user. Such behavior increases the duration of the connection and might cause the number of simultaneous instances to increase. If the increase in simultaneous connections is not acceptable, use the max-auth-connections option to limit the number of simultaneous connections. For detailed information about the max-auth-connections option, see the max-auth-connections section. Only Security Directory Server supports enabling of the auth-using-compare option. For other LDAP servers, Security Access Manager considers this option disabled. Security Access Manager WebSEAL takes advantage of enhanced-pwd-policy. The password policies and account states supported by Security Access Manager are: Password resetLocked accountsExpired accountsGrace login for expired accountsAccounts whose passwords are going to expire Options yes|trueWhen the enhanced-pwd-policy option is set to true, Security Access Manager efficiently identifies the underlying LDAP registry password policy and reacts appropriately.no|falseWhen the enhanced-pwd-policy option is set to false, the behavior of Security Access Manager towards LDAP registry password policy enforcement remains unchanged. Default value The default value of enhanced-pwd-policy is no|false Example An example of this feature is: LDAP reports that an account is expired and allows grace login. The user is informed that the account is expired, and is provided a grace login page and an option to change the password. [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.Using enhanced-pwd-policy with Security Directory ServerIf you enable enhanced-pwd-policy for the Security Directory Server when using Security Directory Server for the registry, you must take several steps.

enhanced-pwd-policy

This stanza entry specifies whether the LDAP registries that Security Access Manager uses provide password policy enforcement for LDAP accounts.

Syntax

enhanced-pwd-policy = {yes|true|no|false}

Description

Note: The appliance embedded LDAP server does not support this configuration option.

Security Access Manager uses LDAP account passwords for authentication. This means that Security Access Manager is subject to LDAP registry password policies. When the enhanced-pwd-policy option is enabled, Security Access Manager efficiently identifies the underlying LDAP registry password policy and reacts appropriately. The Security Access Manager password policy is enforced concurrently and is not affected by the enhanced-pwd-policy option.

This option is supported for Sun Directory Server 6.3.1 and Security Directory Server. For Security Directory Server with the enhanced-pwd-policy option disabled, Security Access Manager provides only limited support for handling LDAP registry password policies. The enhanced-pwd-policy option enhances such support.

When you set the auth-using-compare option to no, a user password is authenticated by creating a connection to the LDAP registry and binding the connection with the user password. Success or failure of the binding is noted and the connection is closed. If you set the enhanced-pwd-policy option is set to yes when auth-using-compare is set to no, the user password changes occur on the connection that is used to authenticate the user.

Such behavior increases the duration of the connection and might cause the number of simultaneous instances to increase. If the increase in simultaneous connections is not acceptable, use the max-auth-connections option to limit the number of simultaneous connections. For detailed information about the max-auth-connections option, see the max-auth-connections section.

Note: Only Security Directory Server supports enabling of the auth-using-compare option. For other LDAP servers, Security Access Manager considers this option disabled.

Security Access Manager WebSEAL takes advantage of enhanced-pwd-policy.

The password policies and account states supported by Security Access Manager are:

Password reset

Locked accounts

Expired accounts

Grace login for expired accounts

Accounts whose passwords are going to expire

Options

yes|true

When the enhanced-pwd-policy option is set to true, Security Access Manager efficiently identifies the underlying LDAP registry password policy and reacts appropriately.

no|false

When the enhanced-pwd-policy option is set to false, the behavior of Security Access Manager towards LDAP registry password policy enforcement remains unchanged.

Default value

The default value of enhanced-pwd-policy is no|false

Example

An example of this feature is: LDAP reports that an account is expired and allows grace login. The user is informed that the account is expired, and is provided a grace login page and an option to change the password.

Using enhanced-pwd-policy with Security Directory Server
If you enable enhanced-pwd-policy for the Security Directory Server when using Security Directory Server for the registry, you must take several steps.

Parent topic: [ldap] stanza

Using enhanced-pwd-policy with Security Directory ServerIf you enable enhanced-pwd-policy for the Security Directory Server when using Security Directory Server for the registry, you must take several steps.enhanced-pwd-policySecurity Directory ServerManually update the access control lists (ACL) of the server so that users can change their passwords.Set auth-using-compare to no in each configuration file where you set enhanced-pwd-policy to yes.To ensure that users can change their passwords, suffixes that contain or will contain Security Access Manager user accounts must have an LDAP ACL that permits users to change their passwords. An example of the suffix that you create is o=ibm,c=us. An example of a suffix that Security Access Manager creates is secAuthority=Default. Each of these suffixes requires an LDAP ACL to let the users change their passwords.Complete the following steps to update LDAP access control lists: For the suffix that you created, create a file, for example, addacl1.ldif, that contains the following statements:dn:o=ibm,c=us changetype:modify add:aclEntry aclEntry:access-id:cn=this:at.userPassword:rwscRun the command:idsldapmodify -D "cn=root" -w "password" -h your.ldap.host.name -f "addacl1.ldif"enhanced-pwd-policyThis stanza entry specifies whether the LDAP registries that Security Access Manager uses provide password policy enforcement for LDAP accounts.Behavior of Security Access Manager policy server LDAP accounts and policiesThe pwdMustChange option in the LDAP policy prevents the policy server from starting during configuration.

Using enhanced-pwd-policy with Security Directory Server

If you enable enhanced-pwd-policy for the Security Directory Server when using Security Directory Server for the registry, you must take several steps.

About this task

Manually update the access control lists (ACL) of the server so that users can change their passwords.

Set auth-using-compare to no in each configuration file where you set enhanced-pwd-policy to yes.

To ensure that users can change their passwords, suffixes that contain or will contain Security Access Manager user accounts must have an LDAP ACL that permits users to change their passwords. An example of the suffix that you create is o=ibm,c=us. An example of a suffix that Security Access Manager creates is secAuthority=Default. Each of these suffixes requires an LDAP ACL to let the users change their passwords.

Complete the following steps to update LDAP access control lists:

Procedure

For the suffix that you created, create a file, for example, addacl1.ldif, that contains the following statements:

dn:o=ibm,c=us
changetype:modify
add:aclEntry
aclEntry:access-id:cn=this:at.userPassword:rwsc

Run the command:

idsldapmodify -D "cn=root" -w "password"
 -h your.ldap.host.name -f "addacl1.ldif"

Behavior of Security Access Manager policy server LDAP accounts and policies
The pwdMustChange option in the LDAP policy prevents the policy server from starting during configuration.

Parent topic: enhanced-pwd-policy

Behavior of Security Access Manager policy server LDAP accounts and policiesThe pwdMustChange option in the LDAP policy prevents the policy server from starting during configuration.LDAPserveraccountspolicyserverpwdMustChange optionpolicyserverglobal policiespolicyglobal, disablingpwdMustChange option, policy serverThe account used for configuration does not exist before the configuration starts. You cannot set a policy to override the global policy. To create Security Access Manager LDAP server accounts, you might temporarily disable the global policies before configuration.After you configure the Security Access Manager server LDAP accounts and the policy server, set a policy for each Security Access Manager server LDAP account to override any global policy that affects the use of the LDAP account.Using enhanced-pwd-policy with Security Directory ServerIf you enable enhanced-pwd-policy for the Security Directory Server when using Security Directory Server for the registry, you must take several steps.

Behavior of Security Access Manager policy server LDAP accounts and policies

The pwdMustChange option in the LDAP policy prevents the policy server from starting during configuration.

The account used for configuration does not exist before the configuration starts. You cannot set a policy to override the global policy. To create Security Access Manager LDAP server accounts, you might temporarily disable the global policies before configuration.

After you configure the Security Access Manager server LDAP accounts and the policy server, set a policy for each Security Access Manager server LDAP account to override any global policy that affects the use of the LDAP account.

Parent topic: Using enhanced-pwd-policy with Security Directory Server

max-auth-connectionsThis stanza entry specifies how many simultaneous connections to your LDAP server are permitted for user authentication.Syntax max-auth-connections = {0|unlimited number of simultaneous connections used for user authentication|any number higher than 0|actual number of simultaneous connections used for user authentication} Description Use the max-auth-connections option to determine how many simultaneous connections to your LDAP server are permitted for user authentication. This option has no effect if auth-using-compare is enabled. The benefit of the max-auth-connections option is greater if enhanced-pwd-policy is enabled. See enhanced-pwd-policy for details. Options 0|unlimited number of simultaneous connections used for user authenticationWhen you set max-auth-connections to 0 (zero), you can use unlimited LDAP server connections simultaneously to authenticate users.any number higher than 0|actual number of simultaneous connections used for user authenticationIf you set max-auth-connections to a value greater than 0 (zero), the number of simultaneous connections used for user authentication is limited to the number you specify. Default value By default, max-auth-connections is set to 0 (zero). [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

max-auth-connections

This stanza entry specifies how many simultaneous connections to your LDAP server are permitted for user authentication.

Syntax

max-auth-connections = {0|unlimited number of simultaneous connections used for user
authentication|any number higher than 0|actual number of simultaneous
connections used for user authentication}

Description

Use the max-auth-connections option to determine how many simultaneous connections to your LDAP server are permitted for user authentication. This option has no effect if auth-using-compare is enabled. The benefit of the max-auth-connections option is greater if enhanced-pwd-policy is enabled. See enhanced-pwd-policy for details.

Options

0|unlimited number of simultaneous connections used for user authentication

When you set max-auth-connections to 0 (zero), you can use unlimited LDAP server connections simultaneously to authenticate users.

any number higher than 0|actual number of simultaneous connections used for user authentication

If you set max-auth-connections to a value greater than 0 (zero), the number of simultaneous connections used for user authentication is limited to the number you specify.

Default value

By default, max-auth-connections is set to 0 (zero).

Parent topic: [ldap] stanza

enable-last-loginThis stanza entry specifies whether to store the last login information of a user in LDAP.enable-last-login entryentriesenable-last-loginldap stanzaenable-last-login entrySyntax enable-last-login = {yes|true|no|false} Description For LDAP-based registries, each Security Access Manager server that provides a login service requires you to set the enable-last-login option to store the last login date of a user in LDAP. Examples of such servers are: WebSEAL.Policy Server.Authorization Server.Local-mode authorization and Java Authorization applications that allow user authentication directly to the registry. Options yes|trueSet the value of the enable-last-login option to yes if you want the last login information of users to be recorded and displayed to users.no|falseSet the value of the enable-last-login option to no if you do not want the last login information of users to be recorded and displayed to users. [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

enable-last-login

This stanza entry specifies whether to store the last login information of a user in LDAP.

Syntax

enable-last-login = {yes|true|no|false}

Description

For LDAP-based registries, each Security Access Manager server that provides a login service requires you to set the enable-last-login option to store the last login date of a user in LDAP. Examples of such servers are:

WebSEAL.

Policy Server.

Authorization Server.

Local-mode authorization and Java™ Authorization applications that allow user authentication directly to the registry.

Options

yes|true

Set the value of the enable-last-login option to yes if you want the last login information of users to be recorded and displayed to users.

no|false

Set the value of the enable-last-login option to no if you do not want the last login information of users to be recorded and displayed to users.

Parent topic: [ldap] stanza

auth-using-compareThis stanza entry specifies whether ldap_compare() is used instead of the ldap_bind() call to verify the password and authenticate the user.auth-using-compare entryentriesauth-using-compareldap stanzaauth-using-compare entrySyntax auth-using-compare = {yes|true|no|false} Description Choice of whether ldap_compare() is used instead of the ldap_bind() call to verify the password and authenticate the user. For those LDAP servers that allow it, a compare operation might run faster than a bind operation. The value for each server can be different, depending on how that server is configured. This option changes the method used by the following authorization API calls: azn_util_client_authenticate()azn_util_password_authenticate() Options yes|trueA compare operation is used to authenticate LDAP users. no|falseA bind operation is used to authenticate LDAP users. Any value other than yes|true, including a blank value, is interpreted as no|false. To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide. Usage Optional Default value The default values are server-dependent. Example auth-using-compare = yes [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

auth-using-compare

This stanza entry specifies whether ldap_compare() is used instead of the ldap_bind() call to verify the password and authenticate the user.

Syntax

auth-using-compare = {yes|true|no|false}

Description

Choice of whether ldap_compare() is used instead of the ldap_bind() call to verify the password and authenticate the user. For those LDAP servers that allow it, a compare operation might run faster than a bind operation. The value for each server can be different, depending on how that server is configured.

This option changes the method used by the following authorization API calls:

azn_util_client_authenticate()

azn_util_password_authenticate()

Options

yes|true

A compare operation is used to authenticate LDAP users.

no|false

A bind operation is used to authenticate LDAP users.

Any value other than yes|true, including a blank value, is interpreted as no|false.

To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide.

Usage

Optional

Default value

The default values are server-dependent.

Example

auth-using-compare = yes

Parent topic: [ldap] stanza

authn-timeoutThis stanza entry specifies the amount of time (in seconds) for authentication operations before the LDAP server is considered down. authn-timeout entryentriesauthn-timeoutldap stanzaauthn-timeout entrySyntax authn-timeout = {0|number_seconds} Description Amount of time (in seconds) that is allowed for authentication operations before the LDAP server is considered to be down. If specified, this value overrides any value set for the timeout entry for authentication operations. Do not specify this stanza entry in the ldap.conf server configuration file. Options 0No timeout (synchronous).number_secondsThe number of seconds allowed for authentication operations. Specify a positive whole number. There is no range limitation for timeout values. Usage Optional Default value 0 Example authn-timeout = 0 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

authn-timeout

This stanza entry specifies the amount of time (in seconds) for authentication operations before the LDAP server is considered down.

Syntax

authn-timeout = {0|number_seconds}

Description

Amount of time (in seconds) that is allowed for authentication operations before the LDAP server is considered to be down. If specified, this value overrides any value set for the timeout entry for authentication operations.

Note: Do not specify this stanza entry in the ldap.conf server configuration file.

Options

0

No timeout (synchronous).

number_seconds

The number of seconds allowed for authentication operations. Specify a positive whole number. There is no range limitation for timeout values.

Usage

Optional

Default value

0

Example

authn-timeout = 0

Parent topic: [ldap] stanza

bind-dnThis stanza entry specifies the LDAP user distinguished name (DN) that is used when binding (signing on) to the LDAP server.bind-dn entryentriesbind-dnldap stanzabind-dn entrySyntax bind-dn = LDAP_dn Description LDAP user distinguished name (DN) that is used when binding (signing on) to the LDAP server. The LDAP_dn value is created, based on the server name that was specified with the –n server_name option and the local host of the computer. Use the svrsslcfg utility to set the LDAP_dn value. To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide. Options LDAP_dnDistinguished name that is used to bind to the LDAP server Usage Conditional. This stanza entry is required when using an LDAP user registry. Default value The default value is server-dependent. Example The following example sets the distinguished name for the policy server: bind-dn = cn=ivmgrd/master,cn=SecurityDaemons,secAuthority=Default [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

bind-dn

This stanza entry specifies the LDAP user distinguished name (DN) that is used when binding (signing on) to the LDAP server.

Syntax

bind-dn = LDAP_dn

Description

LDAP user distinguished name (DN) that is used when binding (signing on) to the LDAP server. The LDAP_dn value is created, based on the server name that was specified with the –n server_name option and the local host of the computer.

Use the svrsslcfg utility to set the LDAP_dn value.

To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide.

Options

LDAP_dn

Distinguished name that is used to bind to the LDAP server

Usage

Conditional. This stanza entry is required when using an LDAP user registry.

Default value

The default value is server-dependent.

Example

The following example sets the distinguished name for the policy server:

bind-dn = cn=ivmgrd/master,cn=SecurityDaemons,secAuthority=Default

Parent topic: [ldap] stanza

cache-enabledThis stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries.cache-enabled entryldap stanza, ivmgrd.confcache-enabled entryldap stanza, pdmgrproxyd.confcache-enabled entryldap stanza, ivacld.confentriescache-enabledldap stanzacache-enabled entrySyntax cache-enabled = {yes|true|no|false} Description Specification of whether LDAP client-side caching is used to improve performance for similar LDAP queries. Options yes|trueEnables LDAP client-side caching.no|falseDisables LDAP client-side caching. This value is the default value. Anything other than yes|true, including a blank value, is interpreted as no|false. To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide. Usage Optional Default value no Example cache-enabled = no [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-enabled

This stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries.

Syntax

cache-enabled = {yes|true|no|false}

Description

Specification of whether LDAP client-side caching is used to improve performance for similar LDAP queries.

Options

yes|true

Enables LDAP client-side caching.

no|false

Disables LDAP client-side caching. This value is the default value. Anything other than yes|true, including a blank value, is interpreted as no|false.

To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide.

Usage

Optional

Default value

no

Example

cache-enabled = no

Parent topic: [ldap] stanza

cache-group-expire-timeThis stanza entry specifies the amount of time (in seconds) until a group entry in the cache is considered stale and is discarded.cache-group-expire-time entryentriescache-group-expire-timeldap stanzacache-group-expire-time entrySyntax cache-group-expire-time = number_seconds Description Amount of time (in seconds) until a group entry in the cache is considered stale and is discarded. This stanza entry is ignored if the cache is not enabled. Options number_secondsThe amount of time specified in seconds. Specify a positive whole number. Usage Optional Default value 300 (5 minutes) Example cache-group-expire-time = 600 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-group-expire-time

This stanza entry specifies the amount of time (in seconds) until a group entry in the cache is considered stale and is discarded.

Syntax

cache-group-expire-time = number_seconds

Description

Amount of time (in seconds) until a group entry in the cache is considered stale and is discarded. This stanza entry is ignored if the cache is not enabled.

Options

number_seconds

The amount of time specified in seconds. Specify a positive whole number.

Usage

Optional

Default value

300 (5 minutes)

Example

cache-group-expire-time = 600

Parent topic: [ldap] stanza

cache-group-membershipThis stanza entry specifies whether group membership information is cached.cache-group-membership entryentriescache-group-membershipldap stanzacache-group-membership entrySyntax cache-group-membership = {yes|true|no|false} Description Specification of whether group membership information is cached. This stanza entry is ignored if the cache is not enabled. Options yes|trueGroup membership is cached.no|falseGroup membership is not cached. Anything other than yes|true, including a blank value, is interpreted as no|false. Usage Optional Default value yes|true Example cache-group-membership = no [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-group-membership

This stanza entry specifies whether group membership information is cached.

Syntax

cache-group-membership = {yes|true|no|false}

Description

Specification of whether group membership information is cached. This stanza entry is ignored if the cache is not enabled.

Options

yes|true

Group membership is cached.

no|false

Group membership is not cached. Anything other than yes|true, including a blank value, is interpreted as no|false.

Usage

Optional

Default value

yes|true

Example

cache-group-membership = no

Parent topic: [ldap] stanza

cache-group-sizeThis stanza entry specifies the number of entries in the LDAP group cache.cache-group-size entryentriescache-group-sizeldap stanzacache-group-size entrySyntax cache-group-size = group_entries Description Number of entries in the LDAP group cache. This stanza entry is ignored if the cache is not enabled. Options group_entriesA positive whole number that represents the number of entries is the LDAP group cache. Usage Optional Default value 64 Example cache-group-size = 100 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-group-size

This stanza entry specifies the number of entries in the LDAP group cache.

Syntax

cache-group-size = group_entries

Description

Number of entries in the LDAP group cache. This stanza entry is ignored if the cache is not enabled.

Options

group_entries

A positive whole number that represents the number of entries is the LDAP group cache.

Usage

Optional

Default value

64

Example

cache-group-size = 100

Parent topic: [ldap] stanza

cache-policy-expire-timeThis stanza entry specifies the amount of time in seconds until a policy entry in the cache is considered stale and is discarded.cache-policy-expire-time entryentriescache-policy-expire-timeldap stanzacache-policy-expire-time entrySyntax cache-policy-expire-time = number_seconds Description Amount of time in seconds until a policy entry in the cache is considered stale and is discarded. This stanza entry is ignored if the cache is not enabled. Options number_secondsThe amount of time specified in number of seconds. Specify a positive whole number. Usage Optional Default value 30 Example cache-policy-expire-time = 60 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-policy-expire-time

This stanza entry specifies the amount of time in seconds until a policy entry in the cache is considered stale and is discarded.

Syntax

cache-policy-expire-time = number_seconds

Description

Amount of time in seconds until a policy entry in the cache is considered stale and is discarded. This stanza entry is ignored if the cache is not enabled.

Options

number_seconds

The amount of time specified in number of seconds. Specify a positive whole number.

Usage

Optional

Default value

30

Example

cache-policy-expire-time = 60

Parent topic: [ldap] stanza

cache-policy-sizeThis stanza entry specifies the number of entries in the LDAP policy cache.cache-policy-size entryentriescache-policy-sizeldap stanzacache-policy-size entrySyntax cache-policy-size = policy_entries Description Number of entries in the LDAP policy cache. This stanza entry is ignored if the cache is not enabled. Options policy_entriesA positive whole number that represents the number of entries is the LDAP policy cache. Usage Optional Default value 20 Example cache-policy-size = 50 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-policy-size

This stanza entry specifies the number of entries in the LDAP policy cache.

Syntax

cache-policy-size = policy_entries

Description

Number of entries in the LDAP policy cache. This stanza entry is ignored if the cache is not enabled.

Options

policy_entries

A positive whole number that represents the number of entries is the LDAP policy cache.

Usage

Optional

Default value

20

Example

cache-policy-size = 50

Parent topic: [ldap] stanza

cache-return-registry-idThis stanza entry specifies whether the LDAP cache returns the Security Access Manager user identity as it is stored in the registry or the value entered by the user.cache-return-registry-id entryentriescache-return-registry-idldap stanzacache-return-registry-id entrySyntax cache-return-registry-id = {yes|no} Description Specifies whether the LDAP cache returns the Security Access Manager user identity as it is stored in the registry or the value entered by the user. Refer to Guidelines for changing configuration filesThese guidelines are provided to help you change the Security Access Manager configuration files. for guidelines on changing configuration file properties. Options yesReturn the Security Access Manager user identity as it is stored in the registry. This option returns the user identity exactly as it was created and preserved in the registry.noReturn the Security Access Manager user identity as the value is entered by the user. Usage Optional Default value no Example cache-return-registry-id = no [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-return-registry-id

This stanza entry specifies whether the LDAP cache returns the Security Access Manager user identity as it is stored in the registry or the value entered by the user.

Syntax

cache-return-registry-id = {yes|no}

Description

Specifies whether the LDAP cache returns the Security Access Manager user identity as it is stored in the registry or the value entered by the user.

Note: Refer to Guidelines for changing configuration files for guidelines on changing configuration file properties.

Options

yes

Return the Security Access Manager user identity as it is stored in the registry. This option returns the user identity exactly as it was created and preserved in the registry.

no

Return the Security Access Manager user identity as the value is entered by the user.

Usage

Optional

Default value

no

Example

cache-return-registry-id = no

Parent topic: [ldap] stanza

cache-use-user-cacheThis stanza entry specifies whether to use the user cache information.cache-use-user-cache entryentriescache-use-user-cacheldap stanzacache-use-user-cache entrySyntax cache-use-user-cache = {yes|true|no|false} Description Specification of whether to use the user cache information. This stanza entry is ignored if the cache is not enabled. Options yes|trueUse user information from the cache.no|falseDo not use user information from the cache. Anything other than yes|true, including a blank value, is interpreted as no|false. Usage Optional Default value yes|true Example cache-use-user-cache = no [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-use-user-cache

This stanza entry specifies whether to use the user cache information.

Syntax

cache-use-user-cache = {yes|true|no|false}

Description

Specification of whether to use the user cache information. This stanza entry is ignored if the cache is not enabled.

Options

yes|true

Use user information from the cache.

no|false

Do not use user information from the cache. Anything other than yes|true, including a blank value, is interpreted as no|false.

Usage

Optional

Default value

yes|true

Example

cache-use-user-cache = no

Parent topic: [ldap] stanza

cache-user-expire-timeThis stanza entry specifies the amount of time in seconds until a user entry in the cache is considered stale and is discarded.cache-user-expire-time entryentriescache-user-expire-timeldap stanzacache-user-expire-time entrySyntax cache-user-expire-time = number_seconds Description Amount of time in seconds until a user entry in the cache is considered stale and is discarded. This stanza entry is ignored if the cache is not enabled. Options number_secondsThe amount of time specified in number of seconds. Use a number that is a positive whole number. Usage Optional Default value 30 Example cache-user-expire-time = 120 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-user-expire-time

This stanza entry specifies the amount of time in seconds until a user entry in the cache is considered stale and is discarded.

Syntax

cache-user-expire-time = number_seconds

Description

Amount of time in seconds until a user entry in the cache is considered stale and is discarded. This stanza entry is ignored if the cache is not enabled.

Options

number_seconds

The amount of time specified in number of seconds. Use a number that is a positive whole number.

Usage

Optional

Default value

30

Example

cache-user-expire-time = 120

Parent topic: [ldap] stanza

cache-user-sizeThis stanza entry specifies the number of entries in the LDAP user cache.cache-user-size entryentriescache-user-sizeldap stanzacache-user-size entrySyntax cache-user-size = user_entries Description Number of entries in the LDAP user cache. This stanza entry is Ignored if the cache is not enabled. Options user_entriesA positive whole number that represents the number of entries is the LDAP user cache. Usage Optional Default value 256 Example cache-user-size = 1000 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

cache-user-size

This stanza entry specifies the number of entries in the LDAP user cache.

Syntax

cache-user-size = user_entries

Description

Number of entries in the LDAP user cache. This stanza entry is Ignored if the cache is not enabled.

Options

user_entries

A positive whole number that represents the number of entries is the LDAP user cache.

Usage

Optional

Default value

256

Example

cache-user-size = 1000

Parent topic: [ldap] stanza

default-policy-override-supportThis stanza entry specifies whether user-level policy support can be used.default-policy-override-support entryentriesdefault-policy-override-supportldap stanzadefault-policy-override-support entrySyntax default-policy-override-support = {yes|true|no|false} Description Specification of whether user-level policy support can be used. Options yes|trueUser policy support is disabled, and only the global (default) policy is checked. This option allows the user policy to not be checked, even if it is specified. no|falseUser policy support is enabled. When a user policy is specified by the administrator, it overrides the global policy. If no value is specified, default-policy-override-support = no becomes the value. To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide. Usage Optional Default value no Example default-policy-override-support = yes [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

default-policy-override-support

This stanza entry specifies whether user-level policy support can be used.

Syntax

default-policy-override-support = {yes|true|no|false}

Description

Specification of whether user-level policy support can be used.

Options

yes|true

User policy support is disabled, and only the global (default) policy is checked. This option allows the user policy to not be checked, even if it is specified.

no|false

User policy support is enabled. When a user policy is specified by the administrator, it overrides the global policy. If no value is specified, default-policy-override-support = no becomes the value.

To use this key value pair for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide.

Usage

Optional

Default value

no

Example

default-policy-override-support = yes

Parent topic: [ldap] stanza

ldap-server-configThis stanza entry specifies the location of the ldap.conf configuration file. ldap-server-config entryentriesldap-server-configldap stanzaldap-server-config entrySyntax ldap-server-config = fully_qualified_path Description Location of the ldap.conf configuration file. When the ldap-server-config entry is specified in the configuration file, the values for enabled, host, port, max-search-size, and replica are obtained from the ldap.conf file. If any of these entries exist in the configuration file, their values are overridden by the values from the ldap.conf file. Options fully_qualified_pathRepresents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage This stanza entry is required for ivmgrd.conf. Default value The following table shows the default value by platform. PlatformFile nameLinux or UNIX/opt/PolicyDirector/etc/ldap.confWindowsc:\Program Files\tivoli\Policy Director\etc\ldap.conf Example The following example set the location of the LDAP server for a AIX, Linux, or Solaris operating system: ldap-server-config = /opt/PolicyDirector/etc/ldap.conf [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

ldap-server-config

This stanza entry specifies the location of the ldap.conf configuration file.

Syntax

ldap-server-config = fully_qualified_path

Description

Location of the ldap.conf configuration file.

Note: When the ldap-server-config entry is specified in the configuration file, the values for enabled, host, port, max-search-size, and replica are obtained from the ldap.conf file. If any of these entries exist in the configuration file, their values are overridden by the values from the ldap.conf file.

Options

fully_qualified_path

Represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).

For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

This stanza entry is required for ivmgrd.conf.

Default value

The following table shows the default value by platform.

Platform | File name
Linux or UNIX | /opt/PolicyDirector/etc/ldap.conf
Windows | c:\Program Files\tivoli\Policy Director\etc\ldap.conf

Example

The following example set the location of the LDAP server for a AIX, Linux, or Solaris operating system:

ldap-server-config = /opt/PolicyDirector/etc/ldap.conf

Parent topic: [ldap] stanza

login-failures-persistentThis stanza entry specifies whether the tracking of login failures is persistent (maintained in the registry) or done in the local process cache.login-failures-persistent entryentrieslogin-failures-persistentldap stanzalogin-failures-persistent entrySyntax login-failures-persistent = {yes|no} Description Specifies whether the tracking of login failures is persistent (maintained in the registry) or done in the local process cache. Options yesTracking of failures is maintained in the registry.noTracking of failures is done in the local process cache. Usage Optional Default value no Example login-failures-presistent = yes [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

login-failures-persistent

This stanza entry specifies whether the tracking of login failures is persistent (maintained in the registry) or done in the local process cache.

Syntax

login-failures-persistent = {yes|no}

Description

Specifies whether the tracking of login failures is persistent (maintained in the registry) or done in the local process cache.

Options

yes

Tracking of failures is maintained in the registry.

no

Tracking of failures is done in the local process cache.

Usage

Optional

Default value

no

Example

login-failures-presistent = yes

Parent topic: [ldap] stanza

max-search-sizeThis stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.max-search-size entryldap stanza, ivmgrd.confmax-search-size entryldap stanza, pdmgrproxyd.confmax-search-size entryldap stanza, ivacld.confentriesmax-search-sizeldap stanzamax-search-size entrySyntax max-search-size = [0|number_entries] Description Limit for the maximum search size, specified as the number of entries, that can be returned from the LDAP server. The value for each server can be different, depending on how the server was configured. Options 0The number is unlimited. There is no limit to the maximum search size.number_entriesThe maximum number of entries for search, specified as an integer whole number. This value can also be limited by the LDAP server itself. Usage Optional Default value The default value is server-dependent, but defaults to 2048 if not configured. Example max-search-size = 2048 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

max-search-size

This stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.

Syntax

max-search-size = [0|number_entries]

Description

Limit for the maximum search size, specified as the number of entries, that can be returned from the LDAP server. The value for each server can be different, depending on how the server was configured.

Options

0

The number is unlimited. There is no limit to the maximum search size.

number_entries

The maximum number of entries for search, specified as an integer whole number. This value can also be limited by the LDAP server itself.

Usage

Optional

Default value

The default value is server-dependent, but defaults to 2048 if not configured.

Example

max-search-size = 2048

Parent topic: [ldap] stanza

portThis stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.port entryldap stanza, ivmgrd.confport entryldap stanza, ivacld.confentriesportldap stanzaport entrySyntax port = port Description Non-SSL IP port number that is used for communicating with the LDAP server. Options portThe port number configured for the LDAP server. Usage Required for the authorization server; not required for the policy server. Default value 389 Example port = 389 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

port

This stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.

Syntax

port = port

Description

Non-SSL IP port number that is used for communicating with the LDAP server.

Options

port

The port number configured for the LDAP server.

Usage

Required for the authorization server; not required for the policy server.

Default value

389

Example

port = 389

Parent topic: [ldap] stanza

prefer-readwrite-serverThis stanza entry specifies whether the client can question the read/write LDAP server before querying any replica read-only servers that are configured in the domain. prefer-readwrite-server entryentriesprefer-readwrite-serverldap stanzaprefer-readwrite-server entrySyntax prefer-readwrite-server = {yes|true|no|false} Description Specification of whether the client can question the read/write LDAP server before querying any replica Read-only servers that are configured in the domain. The default value can be different. For example, the default value for ivmgrd.conf is yes while the default value for ivacld.conf is no. Options yes|trueEnables the client to be able to question the read/write LDAP server.no|falseDisables the client. Anything other than yes|true, including a blank value, is interpreted as no|false. Usage Optional Default value There is no default value. The default value is server-dependent. Example prefer-readwrite-server = no [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

prefer-readwrite-server

This stanza entry specifies whether the client can question the read/write LDAP server before querying any replica read-only servers that are configured in the domain.

Syntax

prefer-readwrite-server = {yes|true|no|false}

Description

Specification of whether the client can question the read/write LDAP server before querying any replica Read-only servers that are configured in the domain.

The default value can be different. For example, the default value for ivmgrd.conf is yes while the default value for ivacld.conf is no.

Options

yes|true

Enables the client to be able to question the read/write LDAP server.

no|false

Disables the client. Anything other than yes|true, including a blank value, is interpreted as no|false.

Usage

Optional

Default value

There is no default value. The default value is server-dependent.

Example

prefer-readwrite-server = no

Parent topic: [ldap] stanza

search-timeoutThis stanza entry specifies the amount of time in seconds that is allowed for search operations before the LDAP server is considered to be down.search-timeout entryentriessearch-timeoutldap stanzasearch-timeout entrySyntax search-timeout = {0|number_seconds} Description Amount of time in seconds that is allowed for search operations before the LDAP server is considered to be down. If specified, this value overrides any value that is set for the timeout entry for search operations. Do not specify this stanza entry in the ldap.conf server configuration file. Options 0No timeout (synchronous).number_secondsThe number of seconds allowed for search operations. Specify a positive whole number. There is no range limitation for timeout values. Usage Optional Default value 0 Example search-timeout = 0 [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

search-timeout

This stanza entry specifies the amount of time in seconds that is allowed for search operations before the LDAP server is considered to be down.

Syntax

search-timeout = {0|number_seconds}

Description

Amount of time in seconds that is allowed for search operations before the LDAP server is considered to be down. If specified, this value overrides any value that is set for the timeout entry for search operations.

Note: Do not specify this stanza entry in the ldap.conf server configuration file.

Options

0

No timeout (synchronous).

number_seconds

The number of seconds allowed for search operations. Specify a positive whole number. There is no range limitation for timeout values.

Usage

Optional

Default value

0

Example

search-timeout = 0

Parent topic: [ldap] stanza

ssl-enabledThis stanza entry specifies whether the Security Access Manager server uses SSL to communicate with the LDAP server.ssl-enabled entryentriesssl-enabledldap stanzassl-enabled entrySyntax ssl-enabled = {yes|true|no|false} Description Specification of whether the Security Access Manager server uses SSL to communicate with the LDAP server. The value for each Security Access Manager server can be different, depending on how that server was configured. If this value is set to yes and Federal Information Processing Standards (FIPS) mode is enabled (ssl-compliance=yes), LDAP uses whatever secure communication protocol it chooses for FIPS enablement. If you specify that the authorization API (aznAPI) should use SSL to communicate with the LDAP server, you must enable SSL using this stanza entry. If you enable SSL communication, you must specify an SSL key file name and, if there are multiple keys in the file, the key file DN. Options yes|trueEnables SSL communication.no|falseDisables SSL communication. Anything other than yes or true, including a blank value, is interpreted as no or false. Usage Required to enable SSL communication. When ssl-enabled = yes, the LdapSSL entry in the ldap.conf file must be set to useSSL. Default value There is no default value. The default values are server-dependent. Example ssl-enabled = yes [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

ssl-enabled

This stanza entry specifies whether the Security Access Manager server uses SSL to communicate with the LDAP server.

Syntax

ssl-enabled = {yes|true|no|false}

Description

Specification of whether the Security Access Manager server uses SSL to communicate with the LDAP server. The value for each Security Access Manager server can be different, depending on how that server was configured. If this value is set to yes and Federal Information Processing Standards (FIPS) mode is enabled (ssl-compliance=yes), LDAP uses whatever secure communication protocol it chooses for FIPS enablement.

If you specify that the authorization API (aznAPI) should use SSL to communicate with the LDAP server, you must enable SSL using this stanza entry.

If you enable SSL communication, you must specify an SSL key file name and, if there are multiple keys in the file, the key file DN.

Options

yes|true

Enables SSL communication.

no|false

Disables SSL communication. Anything other than yes or true, including a blank value, is interpreted as no or false.

Usage

Required to enable SSL communication. When ssl-enabled = yes, the LdapSSL entry in the ldap.conf file must be set to useSSL.

Default value

There is no default value. The default values are server-dependent.

Example

ssl-enabled = yes

Parent topic: [ldap] stanza

ssl-keyfileThis stanza entry specifies the SSL key file name and location.ssl-keyfile entryldap stanzaentriesssl-keyfileldap stanzassl-keyfile entrySyntax ssl-keyfile = ldap-ssl-key-filename Description SSL key file name and location. Use the SSL key file to handle certificates that are used in LDAP communication. The file extension can be anything, but the extension is usually .kdb. The certificate files in a directory need to be accessible to the server user (or all users). Make sure that server user (for example, ivmgr) or all users have permission to access the .kdb file and the folder that contains the .kdb file. Options ldap-ssl-key-filenameA valid file name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks. Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Conditional. This stanza entry is required only when the LDAP server is configured to do client authentication (ssl-enabled = yes). Default value The following table shows the default value by platform. [ldap] stanza ssl-keyfile default value by platformPlatformFile nameLinux or UNIX/opt/PolicyDirector/keytab/server_name.kdbWindowsc:\program files\tivoli\policy director\keytab\server_name.kdb Example The following example sets the SSL key file for a UNIX policy server: ssl-keyfile = /ldap52kdb/a17jsun.kdb [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

ssl-keyfile

This stanza entry specifies the SSL key file name and location.

Syntax

ssl-keyfile = ldap-ssl-key-filename

Description

SSL key file name and location. Use the SSL key file to handle certificates that are used in LDAP communication. The file extension can be anything, but the extension is usually .kdb.

The certificate files in a directory need to be accessible to the server user (or all users). Make sure that server user (for example, ivmgr) or all users have permission to access the .kdb file and the folder that contains the .kdb file.

Options

ldap-ssl-key-filename

A valid file name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks. Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Conditional. This stanza entry is required only when the LDAP server is configured to do client authentication (ssl-enabled = yes).

Default value

The following table shows the default value by platform.

Table 180. [ldap] stanza ssl-keyfile default value by platform

Platform | File name
Linux or UNIX | /opt/PolicyDirector/keytab/server_name.kdb
Windows | c:\program files\tivoli\policy director\keytab\server_name.kdb

Example

The following example sets the SSL key file for a UNIX policy server:

ssl-keyfile = /ldap52kdb/a17jsun.kdb

Parent topic: [ldap] stanza

ssl-keyfile-dnThis stanza entry specifies the key label of the client certificate within the SSL key file.ssl-keyfile-dn entryentriesssl-keyfile-dnldap stanzassl-keyfile-dn entrySyntax ssl-keyfile-dn = ldap-ssl-keyfile-label Description Key label of the client certificate within the SSL key file. Options ldap-ssl-keyfile-labelIdentifies the client certificate that is presented to the LDAP server. Usage Conditional. This stanza entry is required only when the LDAP server is configured to do client authentication. Default value If the default policy server key database is being used, the default client certificate value is PDLDAP. Example ssl-keyfile-dn = "PDLDAP" [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

ssl-keyfile-dn

This stanza entry specifies the key label of the client certificate within the SSL key file.

Syntax

ssl-keyfile-dn = ldap-ssl-keyfile-label

Description

Key label of the client certificate within the SSL key file.

Options

ldap-ssl-keyfile-label

Identifies the client certificate that is presented to the LDAP server.

Usage

Conditional. This stanza entry is required only when the LDAP server is configured to do client authentication.

Default value

If the default policy server key database is being used, the default client certificate value is PDLDAP.

Example

ssl-keyfile-dn = "PDLDAP"

Parent topic: [ldap] stanza

ssl-keyfile-pwdThis stanza entry is deprecated. The ssl-keyfile-pwd entry is deprecated in the [ldap] stanza. Although this entry might exist in a configuration file, it is ignored.ssl-keyfile-pwd entryldap stanzassl-keyfile-pwd entrySyntax ssl-keyfile-pwd = ldap-ssl-keyfile-password Description Deprecated: The ssl-keyfile-pwd entry is deprecated in the [ldap] stanza. Although this entry might exist in a configuration file, it is ignored. [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

ssl-keyfile-pwd

This stanza entry is deprecated. The ssl-keyfile-pwd entry is deprecated in the [ldap] stanza. Although this entry might exist in a configuration file, it is ignored.

Syntax

ssl-keyfile-pwd = ldap-ssl-keyfile-password

Description

Deprecated: The ssl-keyfile-pwd entry is deprecated in the [ldap] stanza. Although this entry might exist in a configuration file, it is ignored.

Parent topic: [ldap] stanza

user-and-group-in-same-suffixThis stanza entry specifies whether the groups in which a user is a member are defined in the same LDAP suffix as the user definition.user-and-group-in-same-suffix entryentriesuser-and-group-in-same-suffixldap stanzauser-and-group-in-same-suffix entrySyntax user-and-group-in-same-suffix = {yes|true|no|false} Description Specification of whether the groups in which a user is a member are defined in the same LDAP suffix as the user definition. When a user is authenticated, the groups in which the user is a member must be determined to build a credential. Normally, all LDAP suffixes are searched to locate the groups of which the user is a member. Options yes|trueThe groups that are assumed to be defined in the same LDAP suffix as the user definition. Only that suffix is searched for group membership. This behavior can improve the performance of group lookup, because only a single suffix is searched. Use this option only if group definitions are restricted to the same suffix as user definitions.no|falseThe groups might be defined in any LDAP suffix. Anything other than yes|true, including a blank value, is interpreted as no|false. To use this key value pair for performance tuning purposes, see the IBM Security Access Manager for Web: Performance Tuning Guide. Usage Optional Default value no Example user-and-group-in-same-suffix = yes [ldap] stanzaThis stanza defines configuration key value pairs that are required for the Security Access Manager servers to communicate with the server that is associated with an LDAP user registry.

user-and-group-in-same-suffix

This stanza entry specifies whether the groups in which a user is a member are defined in the same LDAP suffix as the user definition.

Syntax

user-and-group-in-same-suffix = {yes|true|no|false}

Description

Specification of whether the groups in which a user is a member are defined in the same LDAP suffix as the user definition.

When a user is authenticated, the groups in which the user is a member must be determined to build a credential. Normally, all LDAP suffixes are searched to locate the groups of which the user is a member.

Options

yes|true

The groups that are assumed to be defined in the same LDAP suffix as the user definition. Only that suffix is searched for group membership. This behavior can improve the performance of group lookup, because only a single suffix is searched. Use this option only if group definitions are restricted to the same suffix as user definitions.

no|false

The groups might be defined in any LDAP suffix. Anything other than yes|true, including a blank value, is interpreted as no|false.

To use this key value pair for performance tuning purposes, see the IBM Security Access Manager for Web: Performance Tuning Guide.

Usage

Optional

Default value

no

Example

user-and-group-in-same-suffix = yes

Parent topic: [ldap] stanza

[ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.LDAPldap.confldap stanzaldap.confThe user registry type value is determined by the pd.conf file. The pd.conf file is created when the IBM Security Access Manager runtime is configured.To use the key value pairs in this stanza for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].cache-enabledThis stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries. cache-account-policyThe cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled.connection-inactivityThis stanza entry specifies the number of seconds of inactivity allowed on an LDAP connection before the connection is taken down.dynamic-groups-enabledThis stanza entry specifies whether dynamic groups are supported. enabledThis stanza entry specifies whether LDAP is the user registry.hostThis stanza entry specifies the host name of the LDAP server.ignore-suffixThis stanza entry specifies the LDAP server suffix that is to be ignored when searching for user and group information.max-search-sizeThis stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.max-server-connectionsThis stanza entry specifies the maximum number of connections for the LDAP server.novell-suffix-search-enabledThis stanza entry specifies whether Security Access Manager searches the entire directory namespace when the Novell eDirectory LDAP server is used as the user registry. portThis stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.replicaThis stanza entry specifies the LDAP user registry replicas in the domain.secauthority-suffixThis stanza entry provides a suffix under which the secAuthorityInfo object is located. This parameter serves as a starting search location for the secAuthorityInfo object when Security Access Manager is started. ssl-portThis stanza entry specifies the SSL IP port that is used to connect to the LDAP server.cache-account-policyThe cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled or not.user-search-filterThe user-search-filter is a configuration file parameter in the [ldap] stanza for ldap.conf that specifies the LDAP search filter used by Security Access Manager.

[ldap] stanza for ldap.conf

This stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

The user registry type value is determined by the pd.conf file. The pd.conf file is created when the IBM Security Access Manager runtime is configured.

To use the key value pairs in this stanza for performance tuning, see the IBM Security Access Manager for Web: Performance Tuning Guide.

cache-enabled
This stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries.

cache-account-policy
The cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled.

connection-inactivity
This stanza entry specifies the number of seconds of inactivity allowed on an LDAP connection before the connection is taken down.

dynamic-groups-enabled
This stanza entry specifies whether dynamic groups are supported.

enabled
This stanza entry specifies whether LDAP is the user registry.

host
This stanza entry specifies the host name of the LDAP server.

ignore-suffix
This stanza entry specifies the LDAP server suffix that is to be ignored when searching for user and group information.

max-search-size
This stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.

max-server-connections
This stanza entry specifies the maximum number of connections for the LDAP server.

novell-suffix-search-enabled
This stanza entry specifies whether Security Access Manager searches the entire directory namespace when the Novell eDirectory LDAP server is used as the user registry.

port
This stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.

replica
This stanza entry specifies the LDAP user registry replicas in the domain.

secauthority-suffix
This stanza entry provides a suffix under which the secAuthorityInfo object is located. This parameter serves as a starting search location for the secAuthorityInfo object when Security Access Manager is started.

ssl-port
This stanza entry specifies the SSL IP port that is used to connect to the LDAP server.

cache-account-policy
The cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled or not.

user-search-filter
The user-search-filter is a configuration file parameter in the [ldap] stanza for ldap.conf that specifies the LDAP search filter used by Security Access Manager.

Parent topic: Configuration file stanza reference

cache-enabledThis stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries. cache-enabled entryldap stanza, ldap.confSyntax cache-enabled = {yes|true|no|false} Description Specification of whether LDAP client-side caching is used to improve performance for similar LDAP queries. Options yes|trueEnables LDAP client-side caching.no|falseDisables LDAP client-side caching. This value is the default value. Anything other than yes|true, including a blank value, is interpreted as no|false. To use this key value pair for performance tuning purposes, see the IBM Security Access Manager for Web: Performance Tuning Guide. Usage Optional Default value no Example cache-enabled = no [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

cache-enabled

This stanza entry specifies whether LDAP client-side caching is used to improve performance for similar LDAP queries.

Syntax

cache-enabled = {yes|true|no|false}

Description

Specification of whether LDAP client-side caching is used to improve performance for similar LDAP queries.

Options

yes|true

Enables LDAP client-side caching.

no|false

Disables LDAP client-side caching. This value is the default value. Anything other than yes|true, including a blank value, is interpreted as no|false.

To use this key value pair for performance tuning purposes, see the IBM Security Access Manager for Web: Performance Tuning Guide.

Usage

Optional

Default value

no

Example

cache-enabled = no

Parent topic: [ldap] stanza for ldap.conf

cache-account-policyThe cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled.cache-account-policy entryldap stanza, ldap.confentriescache-account-policyldap stanza, ldap.confldap stanzacache-account-policy entryldap.confSyntax cache-account-policy = {yes|true|no|false} Default value yes Option descriptions yes|trueEnables LDAP client-side caching of expired account or expired password. Anything other than no|false, including a blank value, is interpreted as yes|true.no|falseDisables LDAP client-side caching of expired account or password. Usage Optional. Enable this configuration file parameter if you want Security Access Manager to cache an expired account or password. Otherwise, set this parameter to no. ExampleThis example enables the LDAP caching of expired account or password.cache-account-policy = yes [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

cache-account-policy

The cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled.

Syntax

cache-account-policy = {yes|true|no|false}

Default value

yes

Option descriptions

yes|true

Enables LDAP client-side caching of expired account or expired password. Anything other than no|false, including a blank value, is interpreted as yes|true.

no|false

Disables LDAP client-side caching of expired account or password.

Usage

Optional. Enable this configuration file parameter if you want Security Access Manager to cache an expired account or password. Otherwise, set this parameter to no.

Example

This example enables the LDAP caching of expired account or password.

cache-account-policy = yes

Parent topic: [ldap] stanza for ldap.conf

connection-inactivityThis stanza entry specifies the number of seconds of inactivity allowed on an LDAP connection before the connection is taken down.connection-inactivity entryldap stanza, ldap.confentriesconnection-inactivityldap stanzaconnection-inactivity entrySyntax connection-inactivity = number_seconds Description Specifies the number of seconds of inactivity allowed on an LDAP connection before the connection is taken down. This parameter is not available with the pdconfig utility. The parameter must be modified manually with the pdadmin command line (local login). For more information, see "pdadmin commands" in the IBM Security Access Manager for Web: Command Reference. Options number_secondsThe number of seconds of inactivity allowed on an LDAP connection. The valid range for this parameter is 0 to 31536000. A connection-inactivity value of 0 specifies that connection inactivity is not tracked and the connections, after they are established, are left connected permanently. Usage Optional Default value If this parameter is not specified, the default value is 0. Example connection-inactivity = 0 [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

connection-inactivity

This stanza entry specifies the number of seconds of inactivity allowed on an LDAP connection before the connection is taken down.

Syntax

connection-inactivity = number_seconds

Description

Specifies the number of seconds of inactivity allowed on an LDAP connection before the connection is taken down.

This parameter is not available with the pdconfig utility. The parameter must be modified manually with the pdadmin command line (local login). For more information, see "pdadmin commands" in the IBM Security Access Manager for Web: Command Reference.

Options

number_seconds

The number of seconds of inactivity allowed on an LDAP connection. The valid range for this parameter is 0 to 31536000. A connection-inactivity value of 0 specifies that connection inactivity is not tracked and the connections, after they are established, are left connected permanently.

Usage

Optional

Default value

If this parameter is not specified, the default value is 0.

Example

connection-inactivity = 0

Parent topic: [ldap] stanza for ldap.conf

dynamic-groups-enabledThis stanza entry specifies whether dynamic groups are supported. dynamic-groups-enabled entryldap stanzaldap.confentriesdynamic-groups-enabledldap stanzadynamic-groups-enabled entrySyntax dynamic-groups-enabled = {yes|true|no|false} Description Specification of whether dynamic groups are supported. This key value pair applies to supported LDAP registries. Security Access Manager supports dynamic groups with Security Directory Server regardless of this setting. This stanza entry can be used only in the ldap.conf configuration file. Options yes|trueSecurity Access Manager attempts to resolve dynamic group membership.no|falseSecurity Access Manager does not attempt to resolve dynamic group membership. Anything other than yes|true, including a blank value, is interpreted as no|false. Usage Optional Default value no Example dynamic-groups-enabled = no [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

dynamic-groups-enabled

This stanza entry specifies whether dynamic groups are supported.

Syntax

dynamic-groups-enabled = {yes|true|no|false}

Description

Specification of whether dynamic groups are supported. This key value pair applies to supported LDAP registries. Security Access Manager supports dynamic groups with Security Directory Server regardless of this setting.

Note: This stanza entry can be used only in the ldap.conf configuration file.

Options

yes|true

Security Access Manager attempts to resolve dynamic group membership.

no|false

Security Access Manager does not attempt to resolve dynamic group membership. Anything other than yes|true, including a blank value, is interpreted as no|false.

Usage

Optional

Default value

no

Example

dynamic-groups-enabled = no

Parent topic: [ldap] stanza for ldap.conf

enabledThis stanza entry specifies whether LDAP is the user registry.enabled entryldap stanza, ldap.confentriesenabledldap stanzaenabled entrySyntax enabled = {yes|true|no|false} Description Specification of whether LDAP is being used as the user registry. Only one user registry can be specified at a time. If enabled, other required stanza entries are an LDAP server host name, and port with which to bind to the server, a bind user DN, and bind user password (obfuscated). Options yes|trueEnables LDAP user registry support.no|falseDisables LDAP user registry support and specifies that LDAP is not the user registry that is used. Anything other than yes or true, including a blank value, is interpreted as no or false. Usage Conditional. This stanza entry is required when LDAP is the user registry. Default value The default value can be different, depending on how the server is configured. Example enabled = yes [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

enabled

This stanza entry specifies whether LDAP is the user registry.

Syntax

enabled = {yes|true|no|false}

Description

Specification of whether LDAP is being used as the user registry. Only one user registry can be specified at a time.

If enabled, other required stanza entries are an LDAP server host name, and port with which to bind to the server, a bind user DN, and bind user password (obfuscated).

Options

yes|true

Enables LDAP user registry support.

no|false

Disables LDAP user registry support and specifies that LDAP is not the user registry that is used. Anything other than yes or true, including a blank value, is interpreted as no or false.

Usage

Conditional. This stanza entry is required when LDAP is the user registry.

Default value

The default value can be different, depending on how the server is configured.

Example

enabled = yes

Parent topic: [ldap] stanza for ldap.conf

hostThis stanza entry specifies the host name of the LDAP server.host entryentrieshostldap stanzahost entrySyntax host = host_name Description Host name of the LDAP server. Valid values for host_name include any valid Internet Protocol (IP) host name. The host that is specified by this entry is assumed to be a readwrite type of server with a preference of 5. For a general description of server types and preferences, see replicaThis stanza entry specifies the LDAP user registry replicas in the domain.. Options host_nameThe value is taken from the pd.conf file. The pd.conf file is created when the IBM Security Access Manager runtime is configured. Usage Required Default value There is no default value. The value is taken from the pd.conf file. Example host = libra host = libra.dallas.ibm.com [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

host

This stanza entry specifies the host name of the LDAP server.

Syntax

host = host_name

Description

Host name of the LDAP server. Valid values for host_name include any valid Internet Protocol (IP) host name.

The host that is specified by this entry is assumed to be a readwrite type of server with a preference of 5. For a general description of server types and preferences, see replica.

Options

host_name

The value is taken from the pd.conf file. The pd.conf file is created when the IBM Security Access Manager runtime is configured.

Usage

Required

Default value

There is no default value. The value is taken from the pd.conf file.

Example

host = libra
host = libra.dallas.ibm.com

Parent topic: [ldap] stanza for ldap.conf

ignore-suffixThis stanza entry specifies the LDAP server suffix that is to be ignored when searching for user and group information.ignore-suffix entryentriesignore-suffixldap stanzaignore-suffix entrySyntax ignore-suffix = suffix_dn Description LDAP server suffix that is to be ignored when searching for user and group information. By default, all defined suffixes in the LDAP server are searched when acquiring User and group information. This stanza entry can be used only in the ldap.conf configuration file. Options suffix_dnSpecifies the suffix distinguished name (DN) that you want to be ignored. Repeat this stanza entry for each suffix you want to be ignored. For example, if you specify ignore-suffix = o=tivoli,c=us, any user, or group that includes o=tivoli,c=us as part of the DN is ignored. Usage Optional Default value All defined suffixes are searched. Example ignore-suffix = o=tivoli,c=us [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

ignore-suffix

This stanza entry specifies the LDAP server suffix that is to be ignored when searching for user and group information.

Syntax

ignore-suffix = suffix_dn

Description

LDAP server suffix that is to be ignored when searching for user and group information. By default, all defined suffixes in the LDAP server are searched when acquiring User and group information.

Note: This stanza entry can be used only in the ldap.conf configuration file.

Options

suffix_dn

Specifies the suffix distinguished name (DN) that you want to be ignored. Repeat this stanza entry for each suffix you want to be ignored. For example, if you specify ignore-suffix = o=tivoli,c=us, any user, or group that includes o=tivoli,c=us as part of the DN is ignored.

Usage

Optional

Default value

All defined suffixes are searched.

Example

ignore-suffix = o=tivoli,c=us

Parent topic: [ldap] stanza for ldap.conf

max-search-sizeThis stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.max-search-size entryldap stanza, ldap.confSyntax max-search-size = [0|number_entries] Description Limit for the maximum search size, specified as the number of entries, that can be returned from the LDAP server. The value for each server can be different, depending on how the server was configured. Options 0The number is unlimited. There is no limit to the maximum search size.number_entriesThe maximum number of entries for search, specified as an integer whole number. This value can be limited by the LDAP server itself. Usage Optional Default value The default value is server-dependent, but it defaults to 2048 if it is not configured. Example max-search-size = 2048 [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

max-search-size

This stanza entry specifies the maximum search size, as the number of entries, that can be returned from the LDAP server.

Syntax

max-search-size = [0|number_entries]

Description

Limit for the maximum search size, specified as the number of entries, that can be returned from the LDAP server. The value for each server can be different, depending on how the server was configured.

Options

0

The number is unlimited. There is no limit to the maximum search size.

number_entries

The maximum number of entries for search, specified as an integer whole number. This value can be limited by the LDAP server itself.

Usage

Optional

Default value

The default value is server-dependent, but it defaults to 2048 if it is not configured.

Example

max-search-size = 2048

Parent topic: [ldap] stanza for ldap.conf

max-server-connectionsThis stanza entry specifies the maximum number of connections for the LDAP server.max-server-connections entryldap stanza, ldap.confentriesmax-server-connectionsldap stanzamax-server-connections entrySyntax max-server-connections = number_connections Description Specifies the maximum number of connections that are allowed with the LDAP server. The Security Access Manager run time maintains a pool of connections for each LDAP server. From this pool, an available connection is chosen to do requests to the LDAP server. If all connections are busy, a new connection is established with the LDAP server, up to the maximum server connection pool size. Options number_connectionsThe maximum number of connections allowed with the LDAP server. The valid range for this parameter is 2-16. Values greater than 16 are set to 16. Usage Optional Default value If this parameter is not specified, the default pool size is 16. Example max-server-connections = 16 [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

max-server-connections

This stanza entry specifies the maximum number of connections for the LDAP server.

Syntax

max-server-connections = number_connections

Description

Specifies the maximum number of connections that are allowed with the LDAP server. The Security Access Manager run time maintains a pool of connections for each LDAP server. From this pool, an available connection is chosen to do requests to the LDAP server. If all connections are busy, a new connection is established with the LDAP server, up to the maximum server connection pool size.

Options

number_connections

The maximum number of connections allowed with the LDAP server. The valid range for this parameter is 2-16. Values greater than 16 are set to 16.

Usage

Optional

Default value

If this parameter is not specified, the default pool size is 16.

Example

max-server-connections = 16

Parent topic: [ldap] stanza for ldap.conf

novell-suffix-search-enabledThis stanza entry specifies whether Security Access Manager searches the entire directory namespace when the Novell eDirectory LDAP server is used as the user registry. novell-suffix-search-enabled entryldap stanza, ldap.confentriesnovell-suffix-search-enabledldap stanzanovell-suffix-search-enabled entrySyntax novell-suffix-search-enabled = {yes|true|no|false} Description When the Novell eDirectory LDAP server is used as the user registry, Security Access Manager uses this option to determine whether to search the entire directory namespace. The search is for user, group, and policy information which uses a global root search. Otherwise, the search is to automatically determine the set of naming contexts hosted by the LDAP server. The search examines each defined naming context individually for user, group, and policy information. Options yes|trueSecurity Access Manager does naming context (suffix/partition) discovery and searches each naming context for user, group, and policy information. The optional ignore-suffix parameters are honored.no|falseSecurity Access Manager does a baseless (global root) search of the entire namespace for user, group, and policy information. The optional ignore-suffix parameters are ignored. Usage Optional; this stanza entry can be used only in the ldap.conf configuration file. Default value no Example novell-suffix-search-enabled = no [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

novell-suffix-search-enabled

This stanza entry specifies whether Security Access Manager searches the entire directory namespace when the Novell eDirectory LDAP server is used as the user registry.

Syntax

novell-suffix-search-enabled = {yes|true|no|false}

Description

When the Novell eDirectory LDAP server is used as the user registry, Security Access Manager uses this option to determine whether to search the entire directory namespace. The search is for user, group, and policy information which uses a global root search. Otherwise, the search is to automatically determine the set of naming contexts hosted by the LDAP server. The search examines each defined naming context individually for user, group, and policy information.

Options

yes|true

Security Access Manager does naming context (suffix/partition) discovery and searches each naming context for user, group, and policy information. The optional ignore-suffix parameters are honored.

no|false

Security Access Manager does a baseless (global root) search of the entire namespace for user, group, and policy information. The optional ignore-suffix parameters are ignored.

Usage

Optional; this stanza entry can be used only in the ldap.conf configuration file.

Default value

no

Example

novell-suffix-search-enabled = no

Parent topic: [ldap] stanza for ldap.conf

portThis stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.port entryldap stanza, ldap.confSyntax port = port Description Non-SSL IP port number that is used for communicating with the LDAP server. Options portThe value configured for the LDAP server. Usage Required Default value 389 Example port = 389 [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

port

This stanza entry specifies the non-SSL IP port number that is used for communicating with the LDAP server.

Syntax

port = port

Description

Non-SSL IP port number that is used for communicating with the LDAP server.

Options

port

The value configured for the LDAP server.

Usage

Required

Default value

389

Example

port = 389

Parent topic: [ldap] stanza for ldap.conf

replicaThis stanza entry specifies the LDAP user registry replicas in the domain.replicaentryentriesreplicaldap stanzareplica entrySyntax replica = ldap-server, port, type, pref Description Definition of the LDAP user registry replicas in the domain. Options ldap-serverThe network name of the server.portThe port number for the LDAP server. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.typeEither readonly or readwrite.prefA number between 1 and 10, where 10 is the highest preference. The server with the highest preference is chosen for LDAP operations. If multiple servers have the same preference value, then load balancing occurs among the least busy of the servers. Usage Optional Default value No replicas are specified. Example The following example shows one replica that is specified and two replicas that are commented out: replica = freddy,390,readonly,1 #replica = barney,391,readwrite,2 #replica = benny,392,readwrite,3 [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

replica

This stanza entry specifies the LDAP user registry replicas in the domain.

Syntax

replica = ldap-server, port, type, pref

Description

Definition of the LDAP user registry replicas in the domain.

Options

ldap-server

The network name of the server.

port

The port number for the LDAP server. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.

type

Either readonly or readwrite.

pref

A number between 1 and 10, where 10 is the highest preference. The server with the highest preference is chosen for LDAP operations. If multiple servers have the same preference value, then load balancing occurs among the least busy of the servers.

Usage

Optional

Default value

No replicas are specified.

Example

The following example shows one replica that is specified and two replicas that are commented out:

replica = freddy,390,readonly,1
#replica = barney,391,readwrite,2
#replica = benny,392,readwrite,3

Parent topic: [ldap] stanza for ldap.conf

secauthority-suffixThis stanza entry provides a suffix under which the secAuthorityInfo object is located. This parameter serves as a starting search location for the secAuthorityInfo object when Security Access Manager is started. secauthority-suffix entryentriessecauthority-suffixldap stanzasecauthority-suffix entrySyntax secauthority-suffix = suffix Description Provides a suffix under which the secAuthorityInfo object is located. This parameter serves as a starting search location for the secAuthorityInfo object when Security Access Manager is started. If this parameter is set, the specified suffix is searched first to locate the secAuthorityInfo object for the domain. If this parameter is not set, or if the secAuthorityInfo object is not located within the suffix specified by the parameter, then the entire set of suffixes is searched. Options suffix Suffix under which the secAuthorityInfo object is located. Usage Optional. Default value No suffixes are specified. Example secauthority-suffix = c=US [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

secauthority-suffix

This stanza entry provides a suffix under which the secAuthorityInfo object is located. This parameter serves as a starting search location for the secAuthorityInfo object when Security Access Manager is started.

Syntax

secauthority-suffix = suffix

Description

Provides a suffix under which the secAuthorityInfo object is located. This parameter serves as a starting search location for the secAuthorityInfo object when Security Access Manager is started. If this parameter is set, the specified suffix is searched first to locate the secAuthorityInfo object for the domain. If this parameter is not set, or if the secAuthorityInfo object is not located within the suffix specified by the parameter, then the entire set of suffixes is searched.

Options

suffix

Suffix under which the secAuthorityInfo object is located.

Usage

Optional.

Default value

No suffixes are specified.

Example

secauthority-suffix = c=US

Parent topic: [ldap] stanza for ldap.conf

ssl-portThis stanza entry specifies the SSL IP port that is used to connect to the LDAP server.ssl-port entryentriesssl-portldap stanzassl-port entrySyntax ssl-port = port Description SSL IP port that is used to connect to the LDAP server. Options portAny valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Usage Conditional. This stanza entry is required when Security Access Manager is configured to use SSL or TLS to communicate with the LDAP server (ssl-enabled = yes). Default value 636 Example ssl-port = 636 [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

ssl-port

This stanza entry specifies the SSL IP port that is used to connect to the LDAP server.

Syntax

ssl-port = port

Description

SSL IP port that is used to connect to the LDAP server.

Options

port

Any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.

Usage

Conditional. This stanza entry is required when Security Access Manager is configured to use SSL or TLS to communicate with the LDAP server (ssl-enabled = yes).

Default value

636

Example

ssl-port = 636

Parent topic: [ldap] stanza for ldap.conf

cache-account-policyThe cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled or not.cache-account-policy entryldap stanza, ldap.confentriescache-account-policyldap stanza, ldap.confldap stanzacache-account-policy entryldap.confSyntax cache-account-policy = {yes|true|no|false} Default value yes Option descriptions yes|trueEnables LDAP client-side caching of expired account or expired password. Anything other than no|false, including a blank value, is interpreted as yes|true.no|falseDisables LDAP client-side caching of expired account or password. Usage Notes Optional. Enable this configuration file parameter if you want Security Access Manager to cache an expired account or password. Otherwise, set this parameter to no. Return Values None. ExampleThis example enables the LDAP caching of expired account or password.cache-account-policy = yes [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

cache-account-policy

The cache-account-policy is a configuration file parameter in the [ldap] stanza for ldap.conf. The policy determines whether the LDAP client-side caching is enabled or not.

Syntax

cache-account-policy = {yes|true|no|false}

Default value

yes

Option descriptions

yes|true

Enables LDAP client-side caching of expired account or expired password. Anything other than no|false, including a blank value, is interpreted as yes|true.

no|false

Disables LDAP client-side caching of expired account or password.

Usage Notes®

Optional. Enable this configuration file parameter if you want Security Access Manager to cache an expired account or password. Otherwise, set this parameter to no.

Return Values

None.

Example

This example enables the LDAP caching of expired account or password.

cache-account-policy = yes

Parent topic: [ldap] stanza for ldap.conf

user-search-filterThe user-search-filter is a configuration file parameter in the [ldap] stanza for ldap.conf that specifies the LDAP search filter used by Security Access Manager.user-search-filter entryldap stanza, ldap.confldap stanzauser-search-filter entrySyntax user-search-filter = <ldap search filter> Default value For AD LDS and Sun Directory Servers:user-search-filter = (|(objectclass=ePerson)(objectclass=Person)(objectclass=User))For all other LDAP Directory Servers:user-search-filter = (|(objectclass=ePerson)(objectclass=Person)) Option descriptions Specifies the LDAP search filter used by Security Access Manager to locate users in the LDAP directory server. This filter must be a valid LDAP string search filter as described by the Request for Comments (RFC) 2254 document. Use the user-search-filter option with user-objectclass so that the Security Access Manager can locate LDAP users created with the LDAP object classes. Do not update the unsupported option with the same name under the [ldap-generic-general] stanza. Usage Optional: Use this configuration file parameter to specify how to locate Security Access Manager users in LDAP. ExampleThis example specifies a search for a User or Person under objectclass. [ldap] user-search-filter = (|(objectclass=User)(objectclass=Person)) [ldap] stanza for ldap.confThis stanza defines the configuration key value pairs that are required for the LDAP server. For example, you can find the configuration keys and values for LDAP failover, including the use of master server and replica servers, in this stanza.

user-search-filter

The user-search-filter is a configuration file parameter in the [ldap] stanza for ldap.conf that specifies the LDAP search filter used by Security Access Manager.

Syntax

user-search-filter = <ldap search filter>

Default value

For AD LDS and Sun Directory Servers:

user-search-filter = (|(objectclass=ePerson)(objectclass=Person)(objectclass=User))

For all other LDAP Directory Servers:

user-search-filter = (|(objectclass=ePerson)(objectclass=Person))

Option descriptions

Specifies the LDAP search filter used by Security Access Manager to locate users in the LDAP directory server. This filter must be a valid LDAP string search filter as described by the Request for Comments (RFC) 2254 document.

Use the user-search-filter option with user-objectclass so that the Security Access Manager can locate LDAP users created with the LDAP object classes.

Note: Do not update the unsupported option with the same name under the [ldap-generic-general] stanza.

Usage

Optional: Use this configuration file parameter to specify how to locate Security Access Manager users in LDAP.

Example

This example specifies a search for a User or Person under objectclass.

[ldap]
user-search-filter = (|(objectclass=User)(objectclass=Person))

Parent topic: [ldap] stanza for ldap.conf

[manager] stanzaThe stanza entries for configuring the master server settings are in the [manager] stanza of each of the following configuration files:stanzasmanagermanager stanzadescriptionThe [instance-]ivacld.conf configuration file for the authorization serverThe pd.conf configuration file when you use the authorization serverConfiguration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].management-domainThis stanza entry specifies the name of the management domain.master-hostThis stanza entry specifies the host name of the Security Access Manager server.master-portThis stanza entry specifies the TCP port on which the server listens for requests.

[manager] stanza

The stanza entries for configuring the master server settings are in the [manager] stanza of each of the following configuration files:

The [instance-]ivacld.conf configuration file for the authorization server

The pd.conf configuration file when you use the authorization server

management-domain
This stanza entry specifies the name of the management domain.

master-host
This stanza entry specifies the host name of the Security Access Manager server.

master-port
This stanza entry specifies the TCP port on which the server listens for requests.

Parent topic: Configuration file stanza reference

management-domainThis stanza entry specifies the name of the management domain.management-domain entryentriesmanagement-domainmanager stanzamanagement-domain entrySyntax management-domain = {default|domain_name} Description Name of the management domain. This value is created and set by one of the following utilities: For the pd.conf file, the value is set with the bassslcfg utility. For other configuration files, the value is set with the svrsslcfg utility.If the value is not specified, then the value of Default is used. Options DefaultSpecifies the Management domain. This value is the default value for all servers.domain_nameSpecifies the user-specified domain. Use this value when you configure your own name for the domain. The domain_name value is an alphanumeric, case-sensitive string. String values are expected to be characters that are part of the local code set. Valid characters for domain names for US English are the letters a-Z, the numbers 0-9, a period (.), an underscore (_), a plus sign (+), a hyphen (-), an "at" symbol (@), an ampersand (&), and an asterisk (*). You cannot use a space in the domain name. Usage Required Default value Default Example management-domain = mymgmtdomain [manager] stanzaThe stanza entries for configuring the master server settings are in the [manager] stanza of each of the following configuration files:

management-domain

This stanza entry specifies the name of the management domain.

Syntax

management-domain = {default|domain_name}

Description

Name of the management domain. This value is created and set by one of the following utilities:

For the pd.conf file, the value is set with the bassslcfg utility.

For other configuration files, the value is set with the svrsslcfg utility.

Note: If the value is not specified, then the value of Default is used.

Options

Default

Specifies the Management domain. This value is the default value for all servers.

domain_name

Specifies the user-specified domain. Use this value when you configure your own name for the domain.

The domain_name value is an alphanumeric, case-sensitive string. String values are expected to be characters that are part of the local code set.

Valid characters for domain names for US English are the letters a-Z, the numbers 0-9, a period (.), an underscore (_), a plus sign (+), a hyphen (-), an "at" symbol (@), an ampersand (&), and an asterisk (*). You cannot use a space in the domain name.

Usage

Required

Default value

Default

Example

management-domain = mymgmtdomain

Parent topic: [manager] stanza

master-hostThis stanza entry specifies the host name of the Security Access Manager server.master-host entryentriesmaster-hostmanager stanzamaster-host entrySyntax master-host = server_hostname Description Host name of the Security Access Manager server. The following host names are valid: mycomputer.city.company.commycomputer Options server_hostnameRepresents the valid name for the host. Usage Required Default value There is no default value. Example master-host = ammaster [manager] stanzaThe stanza entries for configuring the master server settings are in the [manager] stanza of each of the following configuration files:

master-host

This stanza entry specifies the host name of the Security Access Manager server.

Syntax

master-host = server_hostname

Description

Host name of the Security Access Manager server. The following host names are valid:

mycomputer.city.company.com

mycomputer

Options

server_hostname

Represents the valid name for the host.

Usage

Required

Default value

There is no default value.

Example

master-host = ammaster

Parent topic: [manager] stanza

master-portThis stanza entry specifies the TCP port on which the server listens for requests.master-port entryentriesmaster-portmanager stanzamaster-host port entrySyntax master-port = port Description TCP port on which the server listens for requests. This value is created and set by one of the following utilities: For the pd.conf file, the value is set with the bassslcfg utility.For all other configuration files, the value is set with the svrsslcfg utility. Options portAny valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port over 1000 that is currently not being used. Usage Required Default value The default value is server-dependent. Example master-port = 7135 [manager] stanzaThe stanza entries for configuring the master server settings are in the [manager] stanza of each of the following configuration files:

master-port

This stanza entry specifies the TCP port on which the server listens for requests.

Syntax

master-port = port

Description

TCP port on which the server listens for requests. This value is created and set by one of the following utilities:

For the pd.conf file, the value is set with the bassslcfg utility.

For all other configuration files, the value is set with the svrsslcfg utility.

Options

port

Any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port over 1000 that is currently not being used.

Usage

Required

Default value

The default value is server-dependent.

Example

master-port = 7135

Parent topic: [manager] stanza

[meta-info] stanzaThe stanza entry for configuring Security Access Manager version information is in the [meta-info] stanza of each of the following configuration files:stanzasmeta-infometa-info stanzadescriptionThe ivmgrd.conf configuration file for the policy serverThe [instance-]ivacld.conf configuration file for the authorization serverThe pd.conf configuration file when you use the authorization serverConfiguration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].versionThis stanza entry specifies the version of Security Access Manager in decimal format.

[meta-info] stanza

The stanza entry for configuring Security Access Manager version information is in the [meta-info] stanza of each of the following configuration files:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

The pd.conf configuration file when you use the authorization server

version
This stanza entry specifies the version of Security Access Manager in decimal format.

Parent topic: Configuration file stanza reference

versionThis stanza entry specifies the version of Security Access Manager in decimal format.version entryentriesversionmeta-info stanzaversion entrySyntax version = number Description Version of Security Access Manager in decimal format. This value is generated. Do not change it. [meta-info] stanzaThe stanza entry for configuring Security Access Manager version information is in the [meta-info] stanza of each of the following configuration files:

version

This stanza entry specifies the version of Security Access Manager in decimal format.

Syntax

version = number

Description

Version of Security Access Manager in decimal format.

Note: This value is generated. Do not change it.

Parent topic: [meta-info] stanza

[pdconfig] stanzaThis stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.stanzaspdconfigpdconfig stanzadescriptionConfiguration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].LdapSSLThis stanza entry specifies whether to enable SSL communication on the LDAP server.LdapSSLKeyFileThis stanza entry specifies the SSL key file name and location. LdapSSLKeyFileDnThis stanza entry specifies the key label of the client certificate within the SSL key file.LdapSSLKeyFilePwdThis stanza entry specifies the password to access the SSL key file.

[pdconfig] stanza

This stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

LdapSSL
This stanza entry specifies whether to enable SSL communication on the LDAP server.

LdapSSLKeyFile
This stanza entry specifies the SSL key file name and location.

LdapSSLKeyFileDn
This stanza entry specifies the key label of the client certificate within the SSL key file.

LdapSSLKeyFilePwd
This stanza entry specifies the password to access the SSL key file.

Parent topic: Configuration file stanza reference

LdapSSLThis stanza entry specifies whether to enable SSL communication on the LDAP server.LdapSSL entryentriesLdapSSLpdconfig stanzaLdapSSL entrySyntax LdapSSL = {ssl|nossl} Description Specification of whether to enable SSL communication on the LDAP server. If the LDAP server is not SSL enabled, any Security Access Manager server that is SSL enabled cannot communicate with the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility. Options sslEnables SSL communication. SSL is automatically configured.nosslDisables SSL communication. Anything other than ssl, including a blank value, is interpreted as nossl. Usage Optional Default value The default value is server-dependent. Example LdapSSL = nossl [pdconfig] stanzaThis stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

LdapSSL

This stanza entry specifies whether to enable SSL communication on the LDAP server.

Syntax

LdapSSL = {ssl|nossl}

Description

Specification of whether to enable SSL communication on the LDAP server. If the LDAP server is not SSL enabled, any Security Access Manager server that is SSL enabled cannot communicate with the LDAP server.

Note: The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

Options

ssl

Enables SSL communication. SSL is automatically configured.

nossl

Disables SSL communication. Anything other than ssl, including a blank value, is interpreted as nossl.

Usage

Optional

Default value

The default value is server-dependent.

Example

LdapSSL = nossl

Parent topic: [pdconfig] stanza

LdapSSLKeyFileThis stanza entry specifies the SSL key file name and location. LdapSSLKeyFile entryentriesLdapSSLKeyFilepdconfig stanzaLdapSSLKeyFile entrySyntax LdapSSLKeyFile = ldap-ssl-key-filename Description SSL key file name and location. Use the SSL key file to handle certificates that are used in LDAP communication. The file extension can be anything, but the extension is usually .kdb. The certificate files in a directory need to be accessible to the server user (or all users). Make sure that the server user (for example, ivmgr) or all users have permission to access the .kdb file and the folder that contains the .kdb file. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility. Options ldap-ssl-key-filenameThe file name and location that represents an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Conditional. This stanza entry is required when LdapSSL = ssl. Default value The following table shows the default value by platform. [pdconfig] stanza LdapSSLKeyFile default value by platformPlatformFile nameLinux or UNIX/opt/PolicyDirector/keytab/ivmgrd.kdbWindowsc:\program files\tivoli\policy director\keytab\ivmgrd.kdb Example LdapSSL = ssl LdapSSLKeyFile = /opt/PolicyDirector/keytab/ivmgrd.kdb [pdconfig] stanzaThis stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

LdapSSLKeyFile

This stanza entry specifies the SSL key file name and location.

Syntax

LdapSSLKeyFile = ldap-ssl-key-filename

Description

SSL key file name and location. Use the SSL key file to handle certificates that are used in LDAP communication. The file extension can be anything, but the extension is usually .kdb.

The certificate files in a directory need to be accessible to the server user (or all users). Make sure that the server user (for example, ivmgr) or all users have permission to access the .kdb file and the folder that contains the .kdb file.

Note: The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

Options

ldap-ssl-key-filename

The file name and location that represents an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Conditional. This stanza entry is required when LdapSSL = ssl.

Default value

The following table shows the default value by platform.

Table 181. [pdconfig] stanza LdapSSLKeyFile default value by platform

Platform | File name
Linux or UNIX | /opt/PolicyDirector/keytab/ivmgrd.kdb
Windows | c:\program files\tivoli\policy director\keytab\ivmgrd.kdb

Example

LdapSSL = ssl
LdapSSLKeyFile = /opt/PolicyDirector/keytab/ivmgrd.kdb

Parent topic: [pdconfig] stanza

LdapSSLKeyFileDnThis stanza entry specifies the key label of the client certificate within the SSL key file.LdapSSLKeyFileDn entryentriesLdapSSLKeyFileDnpdconfig stanzaLdapSSLKeyFileDn entrySyntax LdapSSLKeyFileDn = keyLabel Description Key label of the client certificate within the SSL key file. This stanza entry is used when the LDAP server is configured to do client authentication. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility. Options keyLabel Identifies the client certificate that is presented to the LDAP server. Usage Conditional. This stanza entry is required when LdapSSL = ssl. Default value There is no default value. Example LdapSSL = ssl LdapSSLKeyFileDn = "PD_LDAP" [pdconfig] stanzaThis stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

LdapSSLKeyFileDn

This stanza entry specifies the key label of the client certificate within the SSL key file.

Syntax

LdapSSLKeyFileDn = keyLabel

Description

Key label of the client certificate within the SSL key file. This stanza entry is used when the LDAP server is configured to do client authentication.

Note: The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

Options

keyLabel

Identifies the client certificate that is presented to the LDAP server.

Usage

Conditional. This stanza entry is required when LdapSSL = ssl.

Default value

There is no default value.

Example

LdapSSL = ssl
LdapSSLKeyFileDn = "PD_LDAP"

Parent topic: [pdconfig] stanza

LdapSSLKeyFilePwdThis stanza entry specifies the password to access the SSL key file.LdapSSLKeyFilePwd entryentriesLdapSSLKeyFilePwdpdconfig stanzaLdapSSLKeyFilePwd entrySyntax LdapSSLKeyFilePwd = ldap-ssl-keyfile-password Description Password to access the SSL key file. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility. Options ldap-ssl-keyfile-passwordThe password that is associated with the SSL key file. The default SSL key file is key4ssl. Usage Conditional. This stanza entry is required when LdapSSL = ssl. Default value There is no default value. Example LdapSSL = ssl LdapSSLKeyFilePwd = mysslpwd [pdconfig] stanzaThis stanza defines the configuration key value pairs that are required for the LDAP server. The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

LdapSSLKeyFilePwd

This stanza entry specifies the password to access the SSL key file.

Syntax

LdapSSLKeyFilePwd = ldap-ssl-keyfile-password

Description

Password to access the SSL key file.

Note: The entries in this stanza are for internal use only. Do not modify the values in this file. To properly configure these entries, use the pdconfig utility.

Options

ldap-ssl-keyfile-password

The password that is associated with the SSL key file. The default SSL key file is key4ssl.

Usage

Conditional. This stanza entry is required when LdapSSL = ssl.

Default value

There is no default value.

Example

LdapSSL = ssl
LdapSSLKeyFilePwd = mysslpwd

Parent topic: [pdconfig] stanza

[pdaudit-filter] stanzaThe stanza entry for Security Access Manager auditing support is in the [pdaudit-filter] stanza of the pdaudit.conf configuration file.stanzaspdaudit-filterpdaudit-filter stanzadescriptionConfiguration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].logcfgThis stanza entry enables logging and auditing for the application.

[pdaudit-filter] stanza

The stanza entry for Security Access Manager auditing support is in the [pdaudit-filter] stanza of the pdaudit.conf configuration file.

logcfg
This stanza entry enables logging and auditing for the application.

Parent topic: Configuration file stanza reference

logcfgThis stanza entry enables logging and auditing for the application.logcfg entrypdaudit-filter stanzapdaudit-filter stanzalogcfg entrySyntax logcfg = audit.azn:[log-agent][[param[=value]] ...] Description Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events. Each server provides its own setting for event logging in its corresponding configuration file. Options audit.azn:log-agentCategory of auditing event. Also specifies that the destination where log-agent is one of the following agents: stdoutstderrfilepiperemoteparam=valueAllowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing you want to do. See IBM Security Access Manager for Web: Troubleshooting Guide for information about the log agents and the configuration parameters. Usage Optional Default value Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application. Example logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log [pdaudit-filter] stanzaThe stanza entry for Security Access Manager auditing support is in the [pdaudit-filter] stanza of the pdaudit.conf configuration file.

logcfg

This stanza entry enables logging and auditing for the application.

Syntax

logcfg = audit.azn:[log-agent][[param[=value]] ...]

Description

Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events.

Each server provides its own setting for event logging in its corresponding configuration file.

Options

audit.azn:log-agent

Category of auditing event. Also specifies that the destination where log-agent is one of the following agents:

stdout

stderr

file

pipe

remote

param=value

Allowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing you want to do.

See IBM Security Access Manager for Web: Troubleshooting Guide for information about the log agents and the configuration parameters.

Usage

Optional

Default value

Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application.

Example

logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log

Parent topic: [pdaudit-filter] stanza

[pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.stanzaspdrtepdrte stanzadescriptionThe stanza entries for automating server startup when using any of the user registries are in the [pdrte] stanza of the following configuration file: The pd.conf configuration file when you use the authorization serverWhen you use the Security Access Manager authorization server, you must have the pd.conf configuration file.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].boot-start-[instance-]ivacldThis stanza entry specifies whether to start the authorization server instance at system startup. boot-start-ivmgrdThis stanza entry specifies whether to start the policy server at system boot.configuredThis stanza entry specifies whether the IBM Security Access Manager runtime package was configured.ivacld-instancesThis stanza entry specifies a list of configured authorization server instance names.tivoli_common_dirThis stanza entry specifies the file name and location for message files and trace log files. user-reg-hostThis stanza entry specifies the user registry host name.user-reg-hostportThis stanza entry specifies the non-SSL IP port number that is used for communicating with the user registry server.user-reg-serverThis stanza entry specifies the user registry server name. user-reg-typeThis stanza entry specifies the user registry type.

[pdrte] stanza

When the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

The stanza entries for automating server startup when using any of the user registries are in the [pdrte] stanza of the following configuration file:

The pd.conf configuration file when you use the authorization server

When you use the Security Access Manager authorization server, you must have the pd.conf configuration file.

boot-start-[instance-]ivacld
This stanza entry specifies whether to start the authorization server instance at system startup.

boot-start-ivmgrd
This stanza entry specifies whether to start the policy server at system boot.

configured
This stanza entry specifies whether the IBM Security Access Manager runtime package was configured.

ivacld-instances
This stanza entry specifies a list of configured authorization server instance names.

tivoli_common_dir
This stanza entry specifies the file name and location for message files and trace log files.

user-reg-host
This stanza entry specifies the user registry host name.

user-reg-hostport
This stanza entry specifies the non-SSL IP port number that is used for communicating with the user registry server.

user-reg-server
This stanza entry specifies the user registry server name.

user-reg-type
This stanza entry specifies the user registry type.

Parent topic: Configuration file stanza reference

boot-start-[instance-]ivacldThis stanza entry specifies whether to start the authorization server instance at system startup. boot-start-[instance-]ivacld entryentriesboot-start-[instance-]ivacldpdrte stanzaboot-start-[instance-]ivacld entrySyntax boot-start-[instance-]ivacld = {yes|no} Description Specifies whether to start the authorization server instance at system startup. The syntax contains:The boot-start-ivacld default instance stanzaOther entries corresponding to configured authorization server instancesWhen you configure any authorization server with a specified (non-empty string) instance name, the configuration file adds a boot-start-[instance-]ivacld entry for that server. The configuration file always contains an entry for the empty string instance name authorization server, boot-start-ivacld. Options instance-The instance name created during configuration of an authorization server.yesStart the authorization server at system startup.noDo not start the authorization server at system startup. Usage Conditional. This stanza entry is required for AIX, Linux, and Solaris operating systems only. Default value no Example boot-start-ivacld = yes boot-start-otherinst-ivacld = yes [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

boot-start-[instance-]ivacld

This stanza entry specifies whether to start the authorization server instance at system startup.

Syntax

boot-start-[instance-]ivacld = {yes|no}

Description

Specifies whether to start the authorization server instance at system startup. The syntax contains:

The boot-start-ivacld default instance stanza

Other entries corresponding to configured authorization server instances

When you configure any authorization server with a specified (non-empty string) instance name, the configuration file adds a boot-start-[instance-]ivacld entry for that server.

The configuration file always contains an entry for the empty string instance name authorization server, boot-start-ivacld.

Options

instance-

The instance name created during configuration of an authorization server.

yes

Start the authorization server at system startup.

no

Do not start the authorization server at system startup.

Usage

Conditional. This stanza entry is required for AIX, Linux, and Solaris operating systems only.

Default value

no

Example

boot-start-ivacld = yes
boot-start-otherinst-ivacld = yes

Parent topic: [pdrte] stanza

boot-start-ivmgrdThis stanza entry specifies whether to start the policy server at system boot.boot-start-ivmgrd entryentriesboot-start-ivmgrdpdrte stanzaboot-start-ivmgrd entrySyntax boot-start-ivmgrd = {yes|no} Description Specification of whether to start the policy server at system boot. Options yesStart the policy server at system boot. noDo not start the policy server at system boot. Usage Conditional. This stanza entry is required for AIX, Linux, and Solaris operating systems only. Default value no Example boot-start-ivmgrd = yes [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

boot-start-ivmgrd

This stanza entry specifies whether to start the policy server at system boot.

Syntax

boot-start-ivmgrd = {yes|no}

Description

Specification of whether to start the policy server at system boot.

Options

yes

Start the policy server at system boot.

no

Do not start the policy server at system boot.

Usage

Conditional. This stanza entry is required for AIX, Linux, and Solaris operating systems only.

Default value

no

Example

boot-start-ivmgrd = yes

Parent topic: [pdrte] stanza

configuredThis stanza entry specifies whether the IBM Security Access Manager runtime package was configured.configured entryentriesconfiguredpdrte stanzaconfigured Syntax configured = {yes|no} Description Specification of whether the IBM Security Access Manager runtime package was configured. This value is generated. Do not change it. [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

configured

This stanza entry specifies whether the IBM Security Access Manager runtime package was configured.

Syntax

configured = {yes|no}

Description

Specification of whether the IBM Security Access Manager runtime package was configured.

Note: This value is generated. Do not change it.

Parent topic: [pdrte] stanza

ivacld-instancesThis stanza entry specifies a list of configured authorization server instance names.ivacld instancesivacld-instancesSyntax ivacld-instances = [ 'instance1' [ 'instance2' [ ...] ] ] Description A list of configured authorization server instance names. OptionsEach authorization server instance name must be set in single quotation marks and separated by space characters. An empty string instance name is set as the default authorization server instance. This default name must not be present in the list of ivacld-instances. Usage Conditional. This stanza entry is required for Linux and UNIX operating systems only.Do not modify this value directly. The authorization server configuration tools maintain this value.Default value no Example ivacld-instances = 'otherinst' 'otherinst2' [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

ivacld-instances

This stanza entry specifies a list of configured authorization server instance names.

Syntax

ivacld-instances = [ 'instance1' [ 'instance2' [ ...] ] ]

Description

A list of configured authorization server instance names.

Options

Each authorization server instance name must be set in single quotation marks and separated by space characters. An empty string instance name is set as the default authorization server instance. This default name must not be present in the list of ivacld-instances.

Usage

Conditional. This stanza entry is required for Linux and UNIX operating systems only.

Do not modify this value directly. The authorization server configuration tools maintain this value.

Default value

no

Example

ivacld-instances = 'otherinst' 'otherinst2'

Parent topic: [pdrte] stanza

tivoli_common_dirThis stanza entry specifies the file name and location for message files and trace log files. tivoli_common_dir entryentriestivoli_common_dirpdrte stanzativoli_common_dir entrySyntax tivoli_common_dir = fully_qualified_path Description File name and location for message files and trace log files. Specifies whether Tivoli Common Directory is used. Options fully_qualified_pathRepresents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:). For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive. Usage Conditional. This stanza entry is required when you configure the IBM Security Access Manager Runtime for Java environment for Tivoli Common Directory (TCD) logging. Default value See IBM Security Access Manager for Web: Troubleshooting Guide. [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

tivoli_common_dir

This stanza entry specifies the file name and location for message files and trace log files.

Syntax

tivoli_common_dir = fully_qualified_path

Description

File name and location for message files and trace log files. Specifies whether Tivoli Common Directory is used.

Options

fully_qualified_path

Represents an alphanumeric string. String values are expected to be characters that are part of the local code set. The set of valid characters in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks ("). Windows operating systems path names, however, can have a backward slash (\) or a colon (:).

For AIX, Linux, and Solaris operating systems, path names and file names are case-sensitive.

Usage

Conditional. This stanza entry is required when you configure the IBM Security Access Manager Runtime for Java environment for Tivoli Common Directory (TCD) logging.

Default value

See IBM Security Access Manager for Web: Troubleshooting Guide.

Parent topic: [pdrte] stanza

user-reg-hostThis stanza entry specifies the user registry host name.user-reg-host entryentriesuser-reg-hostpdrte stanzauser-reg-host entrySyntax user-reg-host = hostname Description User registry host name. This value is generated during configuration. Do not change it. [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

user-reg-host

This stanza entry specifies the user registry host name.

Syntax

user-reg-host = hostname

Description

User registry host name.

Note: This value is generated during configuration. Do not change it.

Parent topic: [pdrte] stanza

user-reg-hostportThis stanza entry specifies the non-SSL IP port number that is used for communicating with the user registry server.user-reg-hostport entryentriesuser-reg-hostportpdrte stanzauser-reg-hostport entrySyntax user-reg-hostport = port Description Non-SSL IP port number that is used for communicating with the user registry server. This value is generated during configuration. Do not change it. [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

user-reg-hostport

This stanza entry specifies the non-SSL IP port number that is used for communicating with the user registry server.

Syntax

user-reg-hostport = port

Description

Non-SSL IP port number that is used for communicating with the user registry server.

Note: This value is generated during configuration. Do not change it.

Parent topic: [pdrte] stanza

user-reg-serverThis stanza entry specifies the user registry server name. user-reg-server entryentriesuser-reg-serverpdrte stanzauser-reg-server entrySyntax user-reg-server = server_name Description User registry server name. This value is generated during configuration. Do not change it. [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

user-reg-server

This stanza entry specifies the user registry server name.

Syntax

user-reg-server = server_name

Description

User registry server name.

Note: This value is generated during configuration. Do not change it.

Parent topic: [pdrte] stanza

user-reg-typeThis stanza entry specifies the user registry type.user-reg-type entryentriesuser-reg-typepdrte stanzauser-reg-type entrySyntaxuser-reg-type = {ldap|active_directory} Description User registry type. This value is generated during configuration. Do not change it. [pdrte] stanzaWhen the policy server is installed, the policy server automatically starts after each system reboot. When the authorization server is installed, the authorization server daemon automatically starts after each system reboot.

user-reg-type

This stanza entry specifies the user registry type.

Syntax

user-reg-type = {ldap|active_directory}

Description

User registry type.

Note: This value is generated during configuration. Do not change it.

Parent topic: [pdrte] stanza

[ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.ssl stanzaivmgrd.confssl stanzaivacld.confssl stanzapd.confThe stanza entries for configuring Security Access Manager SSL settings are in the [ssl] stanza of each of the following configuration files: The ivmgrd.conf configuration file for the policy serverThe [instance-]ivacld.conf configuration file for the authorization serverThe pd.conf configuration file when you use the authorization serverYour configuration file of the resource manager for configured SSL entries The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins must provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].ssl-authn-typeThis stanza entry specifies the type of authentication.ssl-auto-refreshThis stanza entry specifies whether automatic refresh of the SSL certificate and the key database file password occur.ssl-cert-lifeThis stanza entry specifies the number of days in the lifetime of a certificate.disallow-trailing-spaced-usernamesThe disallow-trailing-spaced-usernames is a configuration file parameter in the [ssl] stanza for pd.conf that determines whether trailing spaces in usernames are accepted.ssl-compliancessl-enable-fips (deprecated)This stanza entry determines whether Federal Information Process Standards (FIPS) mode is enabled. This entry is deprecated and replaced by the ssl-compliance entry.ssl-enhanced-securityssl-io-inactivity-timeoutThis stanza entry specifies the time in seconds that an SSL connection waits for a response before timing out.ssl-keyfileThis stanza entry specifies the file name and location on the local system of the SSL key file.ssl-keyfile-labelThis stanza entry specifies the label of the key, other than the default key that you can use.ssl-keyfile-stashThis stanza entry specifies the file name and location of the SSL password stash file that protects private keys in the key file.ssl-listening-portThis stanza entry specifies the TCP port to listen on for incoming requests.ssl-local-domainThis stanza entry specifies the name of the local domain.ssl-maximum-worker-threadsThis stanza entry specifies the number of threads that the server can create to handle incoming requests.ssl-pwd-lifeThis stanza entry specifies the password lifetime in days for the key database file.ssl-v3-timeoutThis stanza entry specifies the session timeout in seconds for SSL Version 3 connections between clients and servers.ssl-v2-enableThis stanza entry specifies the Secure Sockets Layer (SSL), Version 2, settings for Security Access Manager server communication.ssl-session-cache-sizeThis stanza entry specifies the number of concurrent sessions supported by a Security Access Manager server or service.ssl-v3-cipher-specsThis stanza entry defines the Secure Sockets Layer (SSL), Version 3, ciphers.tls-v10-cipher-specsThis stanza entry specifies the Transport Layer Security (TLS), Version 1.0, ciphers to use.tls-v11-cipher-specsDefines the Transport Layer Security (TLS), Version 1.1, ciphers.tls-v12-cipher-specsThis stanza entry specifies the Transport Layer Security (TLS), Version 1.2, ciphers.

[ssl] stanza

The [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

The stanza entries for configuring Security Access Manager SSL settings are in the [ssl] stanza of each of the following configuration files:

The ivmgrd.conf configuration file for the policy server

The [instance-]ivacld.conf configuration file for the authorization server

The pd.conf configuration file when you use the authorization server

Your configuration file of the resource manager for configured SSL entries

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins must provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

ssl-authn-type
This stanza entry specifies the type of authentication.

ssl-auto-refresh
This stanza entry specifies whether automatic refresh of the SSL certificate and the key database file password occur.

ssl-cert-life
This stanza entry specifies the number of days in the lifetime of a certificate.

disallow-trailing-spaced-usernames
The disallow-trailing-spaced-usernames is a configuration file parameter in the [ssl] stanza for pd.conf that determines whether trailing spaces in usernames are accepted.

ssl-compliance

ssl-enable-fips (deprecated)
This stanza entry determines whether Federal Information Process Standards (FIPS) mode is enabled. This entry is deprecated and replaced by the ssl-compliance entry.

ssl-enhanced-security

ssl-io-inactivity-timeout
This stanza entry specifies the time in seconds that an SSL connection waits for a response before timing out.

ssl-keyfile
This stanza entry specifies the file name and location on the local system of the SSL key file.

ssl-keyfile-label
This stanza entry specifies the label of the key, other than the default key that you can use.

ssl-keyfile-stash
This stanza entry specifies the file name and location of the SSL password stash file that protects private keys in the key file.

ssl-listening-port
This stanza entry specifies the TCP port to listen on for incoming requests.

ssl-local-domain
This stanza entry specifies the name of the local domain.

ssl-maximum-worker-threads
This stanza entry specifies the number of threads that the server can create to handle incoming requests.

ssl-pwd-life
This stanza entry specifies the password lifetime in days for the key database file.

ssl-v3-timeout
This stanza entry specifies the session timeout in seconds for SSL Version 3 connections between clients and servers.

ssl-v2-enable
This stanza entry specifies the Secure Sockets Layer (SSL), Version 2, settings for Security Access Manager server communication.

ssl-session-cache-size
This stanza entry specifies the number of concurrent sessions supported by a Security Access Manager server or service.

ssl-v3-cipher-specs
This stanza entry defines the Secure Sockets Layer (SSL), Version 3, ciphers.

tls-v10-cipher-specs
This stanza entry specifies the Transport Layer Security (TLS), Version 1.0, ciphers to use.

tls-v11-cipher-specs
Defines the Transport Layer Security (TLS), Version 1.1, ciphers.

tls-v12-cipher-specs
This stanza entry specifies the Transport Layer Security (TLS), Version 1.2, ciphers.

Parent topic: Configuration file stanza reference

ssl-authn-typeThis stanza entry specifies the type of authentication.ssl-authn-type entryentriesssl-authn-typessl stanzassl-authn-type entrySyntax ssl-authn-type = certificate Description Type of authentication. This value is created and its value set during configuration for the authentication server and the policy proxy server. This stanza entry is not used for the policy server. Do not edit this stanza entry. Default value certificate [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-authn-type

This stanza entry specifies the type of authentication.

Syntax

ssl-authn-type = certificate

Description

Type of authentication.

Note: This value is created and its value set during configuration for the authentication server and the policy proxy server. This stanza entry is not used for the policy server.

Do not edit this stanza entry.

Default value

certificate

Parent topic: [ssl] stanza

ssl-auto-refreshThis stanza entry specifies whether automatic refresh of the SSL certificate and the key database file password occur.ssl-auto-refresh entryentriesssl-auto-refreshssl stanzassl-auto-refresh entrySyntax ssl-auto-refresh = {yes|no} Description Specification of whether automatic refresh of the SSL certificate and the key database file password occur. This value is created and its value set with one of the following utilities: For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.For the pd.conf configuration file, it is set with the bassslcfg utility.For all other configuration files, it is set with the svrsslcfg utility. This value is set with a configuration utility. Do not edit this stanza entry. Options yesEnables automatic certificate and password refresh.noDisables automatic certificate and password refresh. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-auto-refresh

This stanza entry specifies whether automatic refresh of the SSL certificate and the key database file password occur.

Syntax

ssl-auto-refresh = {yes|no}

Description

Specification of whether automatic refresh of the SSL certificate and the key database file password occur.

This value is created and its value set with one of the following utilities:

For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.

For the pd.conf configuration file, it is set with the bassslcfg utility.

For all other configuration files, it is set with the svrsslcfg utility.

Note: This value is set with a configuration utility. Do not edit this stanza entry.

Options

yes

Enables automatic certificate and password refresh.

no

Disables automatic certificate and password refresh.

Parent topic: [ssl] stanza

ssl-cert-lifeThis stanza entry specifies the number of days in the lifetime of a certificate.ssl-cert-life entryentriesssl-cert-lifessl stanzassl-cert-life entrySyntax ssl-cert-life = number_days Description Value for number of days in the lifetime of a certificate. Any issued or renewed certificates must use this value. For the ivmgrd.conf configuration file, set this value with the mgrsslcfg utility to a value 1 - 7299. (The default is 1460, or four years.) The name and path are fixed for this configuration file. Use this utility to modify this value after initial configuration. To increase or decrease the value, change the value and restart the policy server. The new value is in effect only for certificates that are issued or that are renewed from that point on. If both the certificate and the password to the key database file that contains the certificate expire, the password must be refreshed first. Only the policy server uses this value.The password value is set with the mgrsslcfg utility.Do not edit this stanza entry. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-cert-life

This stanza entry specifies the number of days in the lifetime of a certificate.

Syntax

ssl-cert-life = number_days

Description

Value for number of days in the lifetime of a certificate. Any issued or renewed certificates must use this value.

For the ivmgrd.conf configuration file, set this value with the mgrsslcfg utility to a value 1 - 7299. (The default is 1460, or four years.) The name and path are fixed for this configuration file. Use this utility to modify this value after initial configuration.

To increase or decrease the value, change the value and restart the policy server. The new value is in effect only for certificates that are issued or that are renewed from that point on. If both the certificate and the password to the key database file that contains the certificate expire, the password must be refreshed first.

Note:

Only the policy server uses this value.

The password value is set with the mgrsslcfg utility.

Do not edit this stanza entry.

Parent topic: [ssl] stanza

disallow-trailing-spaced-usernamesThe disallow-trailing-spaced-usernames is a configuration file parameter in the [ssl] stanza for pd.conf that determines whether trailing spaces in usernames are accepted.disallow-trailing-spaced-usernames entryentriesdisallow-trailing-spaced-usernamesssl stanzadisallow-trailing-spaced-usernames entrySyntax disallow-trailing-spaced-usernames = {yes|no} Default value no Option descriptions yesIndicates that trailing spaces in usernames are not accepted.noIndicates that trailing spaces in usernames are accepted. Usage notes Enable this configuration file parameter if trailing spaces in usernames are not accepted. This configuration file parameter is optional. Example This example indicates that trailing spaces in usernames are not accepted.disallow-trailing-spaced-usernames = yes [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

disallow-trailing-spaced-usernames

The disallow-trailing-spaced-usernames is a configuration file parameter in the [ssl] stanza for pd.conf that determines whether trailing spaces in usernames are accepted.

Syntax

disallow-trailing-spaced-usernames = {yes|no}

Default value

no

Option descriptions

yes

Indicates that trailing spaces in usernames are not accepted.

no

Indicates that trailing spaces in usernames are accepted.

Usage notes

Enable this configuration file parameter if trailing spaces in usernames are not accepted. This configuration file parameter is optional.

Example

This example indicates that trailing spaces in usernames are not accepted.

disallow-trailing-spaced-usernames = yes

Parent topic: [ssl] stanza

ssl-compliancessl-compliancessl-compliance entryentriesssl-compliancessl stanzassl-compliance entrySyntax ssl-compliance = { none | fips | sp800-131-transition | sp800-131-strict | suite-b-128 | suite-b-192 } Description Determines which compliance mode is enabled. Options noneIndicates that no special compliance modes are applied to the TLS communication protocol. This setting is equivalent to [ssl] ssl-enable-fips = no, which is a deprecated option.fipsEnables FIPS 140-2 compliance. This setting is equivalent to [ssl] ssl-enable-fips = yes, which is a deprecated option.sp800-131-transitionEnables NIST SP 800-131a support at the transition level. The transition level has fewer restrictions than the strict level.sp800-131-strictEnables NIST SP 800-131a support at the strict level. This enforcement is required by some federal agencies and enterprises that work with the federal government starting in 2014.suite-b-128Enables NSA Suite B at the 128-bit support level. suite-b-192Enables NSA Suite B at the 192-bit support level. Usage Required.This setting is used for secure communication between Security Access Manager processes, secure communication from Security Access Manager to the LDAP registry servers, and secure communication from Security Access Manager to syslog servers. When a Security Access Manager Java component is running in WebSphere Application Server, then WebSphere Application Server must be running with the same compliance standard as Security Access Manager. For details on configuring WebSphere Application Server for various compliance modes, see http://publib.boulder.ibm.com/infocenter/ieduasst/v1r1m0/index.jsp?topic=/com.ibm.iea.was_v8/was/8.0.0.3/Security/WASV8003_SecurityCryptoSignatureAlgorithm/player.html.To configure Security Access Manager with a specific compliance, set the ssl-compliance value in pd.conf immediately before you configure the Security Access Manager policy server. The ssl-compliance option takes precedence over the deprecated ssl-enable-fips option if both are present. Default value none Example ssl-compliance = suite-b-128 [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-compliance

Syntax

ssl-compliance = { none | fips | sp800-131-transition | sp800-131-strict
                 | suite-b-128 | suite-b-192 }

Description

Determines which compliance mode is enabled.

Options

none

Indicates that no special compliance modes are applied to the TLS communication protocol. This setting is equivalent to [ssl] ssl-enable-fips = no, which is a deprecated option.

fips

Enables FIPS 140-2 compliance. This setting is equivalent to [ssl] ssl-enable-fips = yes, which is a deprecated option.

sp800-131-transition

Enables NIST SP 800-131a support at the transition level. The transition level has fewer restrictions than the strict level.

sp800-131-strict

Enables NIST SP 800-131a support at the strict level. This enforcement is required by some federal agencies and enterprises that work with the federal government starting in 2014.

suite-b-128

Enables NSA Suite B at the 128-bit support level.

suite-b-192

Enables NSA Suite B at the 192-bit support level.

Usage

Required.

This setting is used for secure communication between Security Access Manager processes, secure communication from Security Access Manager to the LDAP registry servers, and secure communication from Security Access Manager to syslog servers.

When a Security Access Manager Java™ component is running in WebSphere Application Server, then WebSphere Application Server must be running with the same compliance standard as Security Access Manager. For details on configuring WebSphere Application Server for various compliance modes, see http://publib.boulder.ibm.com/infocenter/ieduasst/v1r1m0/index.jsp?topic=/com.ibm.iea.was_v8/was/8.0.0.3/Security/WASV8003_SecurityCryptoSignatureAlgorithm/player.html.

To configure Security Access Manager with a specific compliance, set the ssl-compliance value in pd.conf immediately before you configure the Security Access Manager policy server. The ssl-compliance option takes precedence over the deprecated ssl-enable-fips option if both are present.

Default value

none

Example

ssl-compliance = suite-b-128

Parent topic: [ssl] stanza

ssl-enable-fips (deprecated)This stanza entry determines whether Federal Information Process Standards (FIPS) mode is enabled. This entry is deprecated and replaced by the ssl-compliance entry.ssl-enable-fips entryentriesssl-enable-fipsssl stanzassl-enable-fips entrySyntax ssl-enable-fips = {yes|no} Description Determines whether Federal Information Process Standards (FIPS) mode is enabled. If enable, set to yes, Transport Layer Security (TLS) version 1 (TLSv1) is the secure communication protocol used. If not enabled, set to no, SSL version 3 (SSLv3) is the secure communication protocol used. Options yesSpecifies that TLSv1 is the secure communication protocol.noSpecifies that SSLv3 is the secure communication protocol. Usage Required Default value There is no default value. This value is set by the configuration utility that is associated with each server. Example ssl-enable-fips = no [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-enable-fips (deprecated)

This stanza entry determines whether Federal Information Process Standards (FIPS) mode is enabled. This entry is deprecated and replaced by the ssl-compliance entry.

Syntax

ssl-enable-fips = {yes|no}

Description

Determines whether Federal Information Process Standards (FIPS) mode is enabled. If enable, set to yes, Transport Layer Security (TLS) version 1 (TLSv1) is the secure communication protocol used. If not enabled, set to no, SSL version 3 (SSLv3) is the secure communication protocol used.

Options

yes

Specifies that TLSv1 is the secure communication protocol.

no

Specifies that SSLv3 is the secure communication protocol.

Usage

Required

Default value

There is no default value. This value is set by the configuration utility that is associated with each server.

Example

ssl-enable-fips = no

Parent topic: [ssl] stanza

ssl-enhanced-securityssl-enhanced-security entryentriesssl-enhanced-securityldap stanzassl-enhanced-securitySyntax ssl-enhanced-security = {yes|true|no|false} DescriptionControls the enhanced security added to the proprietary Inter-Process Communication (IPC) in Access Manager. It affects the following functions:All pdadmin server task commands that are sent from the Policy Server to Tivoli Access Manager applications, such as WebSEAL (webseald), at the Tivoli Access Manager application side of the communication.Remote logging at the Authorization Server (pdacld) side of the communication.The policy database change notification sent to Tivoli Access Manager local mode applications at the application side. Options yes|trueEnables enhanced security.no|falseDisables enhanced security. Anything other than yes or true, including a blank value, is interpreted as no or false. Default value This option is enabled by default. Example ssl-enhanced-security = yes [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-enhanced-security

Syntax

ssl-enhanced-security = {yes|true|no|false}

Description

Controls the enhanced security added to the proprietary Inter-Process Communication (IPC) in Access Manager. It affects the following functions:

All pdadmin server task commands that are sent from the Policy Server to Tivoli® Access Manager applications, such as WebSEAL (webseald), at the Tivoli Access Manager application side of the communication.

Remote logging at the Authorization Server (pdacld) side of the communication.

The policy database change notification sent to Tivoli Access Manager local mode applications at the application side.

Options

yes|true

Enables enhanced security.

no|false

Disables enhanced security. Anything other than yes or true, including a blank value, is interpreted as no or false.

Default value

This option is enabled by default.

Example

ssl-enhanced-security = yes

Parent topic: [ssl] stanza

ssl-io-inactivity-timeoutThis stanza entry specifies the time in seconds that an SSL connection waits for a response before timing out.ssl-io-inactivity-timeout entryentriesssl-io-inactivity-timeoutssl stanzassl-io-inactivity-timeout entrySyntax ssl-io-inactivity-timeout = {0|number_seconds} Description Duration in seconds that an SSL connection waits for a response before timing out. For certain administration requests, you might receive the HPDBA0219E error message when the timeout value is too small. For example, a request might be to look up members in a large user registry group over an SSL connection. To resolve this problem, increase this timeout value in the pd.conf configuration file. This timeout value is created, and the value is set with one of the following utilities: For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.For the pd.conf configuration file, it is set with the bassslcfg utility.For all other configuration files, it is set with the svrsslcfg. The timeout value is set with the configuration utility. Do not edit this stanza entry. Options 0No timeout is allowed.number_secondsSpecifies the number of seconds that an SSL connection waits for a response before timing out. There is no range limitation for this timeout value. Usage Required Default value There is no default value. This value is set by the configuration utility that is associated with each server. Example ssl-io-inactivity-timeout = 300 [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-io-inactivity-timeout

This stanza entry specifies the time in seconds that an SSL connection waits for a response before timing out.

Syntax

ssl-io-inactivity-timeout = {0|number_seconds}

Description

Duration in seconds that an SSL connection waits for a response before timing out. For certain administration requests, you might receive the HPDBA0219E error message when the timeout value is too small. For example, a request might be to look up members in a large user registry group over an SSL connection. To resolve this problem, increase this timeout value in the pd.conf configuration file.

This timeout value is created, and the value is set with one of the following utilities:

For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.

For the pd.conf configuration file, it is set with the bassslcfg utility.

For all other configuration files, it is set with the svrsslcfg.

Note: The timeout value is set with the configuration utility. Do not edit this stanza entry.

Options

0

No timeout is allowed.

number_seconds

Specifies the number of seconds that an SSL connection waits for a response before timing out. There is no range limitation for this timeout value.

Usage

Required

Default value

There is no default value. This value is set by the configuration utility that is associated with each server.

Example

ssl-io-inactivity-timeout = 300

Parent topic: [ssl] stanza

ssl-keyfileThis stanza entry specifies the file name and location on the local system of the SSL key file.ssl-keyfile entryssl stanzassl stanzassl-keyfile entrySyntax ssl-keyfile = key-path Description File name and location on the local system of the SSL key file. If the key-value pair does not exist in the configuration file, the application fails. The file extension can be anything, but it is usually .kdb. By default, the key file is in one of the following operating system-specific directories: AIX, Linux, and Solaris operating systems/var/PolicyDirector/keytabWindows operating systemsc:\program files\tivoli\policy director\keytab The certificate files in a directory need to be accessible to the server user (or all users). Make sure that server user (for example, ivmgr) or all users have permission to access the .kdb file and the folder that contains the .kdb file. This file is created, and the value is set with one of the following utilities: For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.For the pd.conf configuration file, it is set with the bassslcfg utility.For all other configuration files, it is set with the svrsslcfg utility. The file name, including extension, is generated and set by the configuration utility. Do not edit this stanza entry. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-keyfile

This stanza entry specifies the file name and location on the local system of the SSL key file.

Syntax

ssl-keyfile = key-path

Description

File name and location on the local system of the SSL key file. If the key-value pair does not exist in the configuration file, the application fails. The file extension can be anything, but it is usually .kdb. By default, the key file is in one of the following operating system-specific directories:

AIX, Linux, and Solaris operating systems

/var/PolicyDirector/keytab

Windows operating systems

c:\program files\tivoli\policy director\keytab

The certificate files in a directory need to be accessible to the server user (or all users). Make sure that server user (for example, ivmgr) or all users have permission to access the .kdb file and the folder that contains the .kdb file.

This file is created, and the value is set with one of the following utilities:

For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.

For the pd.conf configuration file, it is set with the bassslcfg utility.

For all other configuration files, it is set with the svrsslcfg utility.

Note: The file name, including extension, is generated and set by the configuration utility. Do not edit this stanza entry.

Parent topic: [ssl] stanza

ssl-keyfile-labelThis stanza entry specifies the label of the key, other than the default key that you can use.ssl-keyfile-label entryssl stanzaentriesssl-keyfile-labelssl stanzassl-keyfile-label entrySyntax ssl-keyfile-label = label Description Label of the key to use other than the default. Quotation marks that surround the label value are not permitted. This label is created, and the value is set with one of the following utilities: For the ivmgrd.conf configuration file, it is set with mgrsslcfg utilityFor the pd.conf configuration file, this entry does not apply.For all other configuration files, it is set with the svrsslcfg utility. The label is set by the configuration utility. Do not edit this stanza entry. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-keyfile-label

This stanza entry specifies the label of the key, other than the default key that you can use.

Syntax

ssl-keyfile-label = label

Description

Label of the key to use other than the default. Quotation marks that surround the label value are not permitted.

This label is created, and the value is set with one of the following utilities:

For the ivmgrd.conf configuration file, it is set with mgrsslcfg utility

For the pd.conf configuration file, this entry does not apply.

For all other configuration files, it is set with the svrsslcfg utility.

Note: The label is set by the configuration utility. Do not edit this stanza entry.

Parent topic: [ssl] stanza

ssl-keyfile-stashThis stanza entry specifies the file name and location of the SSL password stash file that protects private keys in the key file.ssl-keyfile-stash entryentriesssl-keyfile-stashssl stanzassl-keyfile-stash entrySyntax ssl-keyfile-stash = stash-path Description File name and location of the SSL password stash file that is used to protect private keys in the key file. The password might be stored encrypted in the stash file. The file extension can be anything, but it is usually .sth. By default, the key file is in one of the following operating system-specific directories: AIX, Linux, and Solaris operating systems/var/PolicyDirector/keytabWindows operating systemsc:\program files\tivoli\policy director\keytab This file is created, and the value is set with one of the following utilities: For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.For the pd.conf configuration file, it is set with the bassslcfg utility.For all other configuration files, it is set with the svrsslcfg utility. The path is defined by the –d option, and the name is defined by the –n option. The file name, including extension, is generated and set by the configuration utility. Do not edit this stanza entry. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-keyfile-stash

This stanza entry specifies the file name and location of the SSL password stash file that protects private keys in the key file.

Syntax

ssl-keyfile-stash = stash-path

Description

File name and location of the SSL password stash file that is used to protect private keys in the key file. The password might be stored encrypted in the stash file.

The file extension can be anything, but it is usually .sth. By default, the key file is in one of the following operating system-specific directories:

AIX, Linux, and Solaris operating systems

/var/PolicyDirector/keytab

Windows operating systems

c:\program files\tivoli\policy director\keytab

This file is created, and the value is set with one of the following utilities:

For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.

For the pd.conf configuration file, it is set with the bassslcfg utility.

For all other configuration files, it is set with the svrsslcfg utility. The path is defined by the –d option, and the name is defined by the –n option.

Note: The file name, including extension, is generated and set by the configuration utility. Do not edit this stanza entry.

Parent topic: [ssl] stanza

ssl-listening-portThis stanza entry specifies the TCP port to listen on for incoming requests.ssl-listening-port entryentriesssl-listening-portssl stanzassl-listening-port entrySyntax ssl-listening-port = {0|port} Description TCP port to listen on for incoming requests. The policy server does not use this stanza entry. Options 0Disables listening. The value is specified during configuration by with the svrsslcfg utility. Do not change this parameter directly; modify the parameter only by issuing the scrsslcfg -chgport command so that the policy server knows that the listening port is changed. Otherwise, the resource manager cannot receive policy update notifications or pdadmin server task commands.portEnables listening at the specified port number. The valid range for port is any positive number that is allowed by TCP/IP and is not currently being used by another application. There is no one default value, because the configuration programs for each daemon specify its own default value. Usage Required, except for the policy server. Default value If not specified during configuration, the default value is 0. Otherwise, the value is server-dependent. Example ssl-listening-port = 8139 [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-listening-port

This stanza entry specifies the TCP port to listen on for incoming requests.

Syntax

ssl-listening-port = {0|port}

Description

TCP port to listen on for incoming requests.

Note: The policy server does not use this stanza entry.

Options

0

Disables listening. The value is specified during configuration by with the svrsslcfg utility.

Note: Do not change this parameter directly; modify the parameter only by issuing the scrsslcfg -chgport command so that the policy server knows that the listening port is changed. Otherwise, the resource manager cannot receive policy update notifications or pdadmin server task commands.

port

Enables listening at the specified port number. The valid range for port is any positive number that is allowed by TCP/IP and is not currently being used by another application.

There is no one default value, because the configuration programs for each daemon specify its own default value.

Usage

Required, except for the policy server.

Default value

If not specified during configuration, the default value is 0. Otherwise, the value is server-dependent.

Example

ssl-listening-port = 8139

Parent topic: [ssl] stanza

ssl-local-domainThis stanza entry specifies the name of the local domain.ssl-local-domain entryssl stanza, ivmgrd.confssl-local-domain entryssl stanza, ivacld.confssl-local-domain entryssl stanza, pd.confssl-local-domain entryssl stanza, pdmgrproxyd.confentriesssl-local-domainSyntax ssl-local-domain = {Default|domain_name} Description The name of the local domain. The server runs on this domain. If this value is not in the configuration file, then operations that rely on its presence fail. The domain name value is created during configuration, but you can change it using one of the following utilities: For the ivmgrd.conf configuration file, change it with the mgrsslcfg utility.For the pd.conf configuration file, change it with the bassslcfg utility.For all other configuration files, change it with the svrsslcfg utility. This value is set during configuration or set with the configuration utility. Do not edit this stanza entry. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-local-domain

This stanza entry specifies the name of the local domain.

Syntax

ssl-local-domain = {Default|domain_name}

Description

The name of the local domain. The server runs on this domain. If this value is not in the configuration file, then operations that rely on its presence fail.

The domain name value is created during configuration, but you can change it using one of the following utilities:

For the ivmgrd.conf configuration file, change it with the mgrsslcfg utility.

For the pd.conf configuration file, change it with the bassslcfg utility.

For all other configuration files, change it with the svrsslcfg utility.

Note: This value is set during configuration or set with the configuration utility. Do not edit this stanza entry.

Parent topic: [ssl] stanza

ssl-maximum-worker-threadsThis stanza entry specifies the number of threads that the server can create to handle incoming requests.ssl-maximum-worker-threads entryentriesssl-maximum-worker-threadsssl stanzassl-maximum-worker-threads entrySyntax ssl-maximum-worker-threads = number_threads Description Number of threads that can be created by the server to handle incoming requests. Options number_threadsNumber of threads that can be specified. The valid range must be equal to or greater than 1. The maximum number varies, because it is dependent on available system resources. Usage Required Default value The default value is server-dependent. Example ssl-maximum-worker-threads = 50 [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-maximum-worker-threads

This stanza entry specifies the number of threads that the server can create to handle incoming requests.

Syntax

ssl-maximum-worker-threads = number_threads

Description

Number of threads that can be created by the server to handle incoming requests.

Options

number_threads

Number of threads that can be specified. The valid range must be equal to or greater than 1. The maximum number varies, because it is dependent on available system resources.

Usage

Required

Default value

The default value is server-dependent.

Example

ssl-maximum-worker-threads = 50

Parent topic: [ssl] stanza

ssl-pwd-lifeThis stanza entry specifies the password lifetime in days for the key database file.ssl-pwd-life entryentriesssl-pwd-lifessl stanzassl-pwd-life entrySyntax ssl-pwd-life = number_days Description Password lifetime for the key database file, specified in the number of days. For automatic password renewal, the value for the lifetime of a password is controlled by the number_days value when the server is started. The number of days 1 - 7299 is created, and the value is set with one of the following utilities: For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.For the pd.conf configuration file, it is set with the bassslcfg utility.For all other configuration files, it is set with the svrsslcfg utility. For manual password renewal, the value is dictated by the value supplied to the svrsslcfg –chgpwd utility. This value is also written into the appropriate configuration file. If a certificate and the password to the key database file that contains that certificate are both expired, the password must be refreshed first.The password value is set with the configuration utility. Do not edit this stanza entry. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-pwd-life

This stanza entry specifies the password lifetime in days for the key database file.

Syntax

ssl-pwd-life = number_days

Description

Password lifetime for the key database file, specified in the number of days. For automatic password renewal, the value for the lifetime of a password is controlled by the number_days value when the server is started.

The number of days 1 - 7299 is created, and the value is set with one of the following utilities:

For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.

For the pd.conf configuration file, it is set with the bassslcfg utility.

For all other configuration files, it is set with the svrsslcfg utility.

For manual password renewal, the value is dictated by the value supplied to the svrsslcfg –chgpwd utility. This value is also written into the appropriate configuration file.

Note:

If a certificate and the password to the key database file that contains that certificate are both expired, the password must be refreshed first.

The password value is set with the configuration utility. Do not edit this stanza entry.

Parent topic: [ssl] stanza

ssl-v3-timeoutThis stanza entry specifies the session timeout in seconds for SSL Version 3 connections between clients and servers.ssl-v3-timeout entryentriesssl-v3-timeoutssl stanzassl-v3-timeout entrySyntax ssl-v3-timeout = number_seconds Description Session timeout in seconds for SSL Version 3 connections between clients and servers. This timeout value controls how often a full SSL handshake is completed between Security Access Manager clients and servers. This timeout value is created, and the value is set with one of the following utilities: For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.For the pd.conf configuration file, it is set with the bassslcfg utility.For all other configuration files, it is set with the svrsslcfg. The path is defined by the –d option, and the name is defined by the –n option. Security Access Manager components might not function with small timeout values in some network environments.The timeout value is set with the configuration utility. Do not edit this stanza entry. [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-v3-timeout

This stanza entry specifies the session timeout in seconds for SSL Version 3 connections between clients and servers.

Syntax

ssl-v3-timeout = number_seconds

Description

Session timeout in seconds for SSL Version 3 connections between clients and servers. This timeout value controls how often a full SSL handshake is completed between Security Access Manager clients and servers.

This timeout value is created, and the value is set with one of the following utilities:

For the ivmgrd.conf configuration file, it is set with the mgrsslcfg utility.

For the pd.conf configuration file, it is set with the bassslcfg utility.

For all other configuration files, it is set with the svrsslcfg. The path is defined by the –d option, and the name is defined by the –n option.

Note:

Security Access Manager components might not function with small timeout values in some network environments.

The timeout value is set with the configuration utility. Do not edit this stanza entry.

Parent topic: [ssl] stanza

ssl-v2-enableThis stanza entry specifies the Secure Sockets Layer (SSL), Version 2, settings for Security Access Manager server communication.ssl-v2-enableentriesssl-v2-enablessl stanzassl-v2-enable entrySyntax ssl-v2-enable = {yes|true|no|false} Description The ssl-v2-enable option has an effect only when ssl-compliance = none. The setting is for compatibility with version 6.1.1 of Security Access Manager. Enabling SSL Version 2 is not required. By default, the SSL Version 2 protocol is disabled, which increases communication security. Options yes|trueEnables the SSL v2 protocol. The protocols SSL v3 and TLS are also choices for Security Access Manager communication and are chosen by Security Access Manager in preference to SSL Version 2, even if this setting is enabled.no|falseDisables the SSL Version 2 protocol. Anything other than yes or true, including a blank value, is interpreted as no or false. Usage Optional. If used, must be set to the same value in all Security Access Manager server and application configuration files. Default value The default value is no. Example The following example disabled the SSL Version 2 protocol.ssl-v2-enable = no [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-v2-enable

This stanza entry specifies the Secure Sockets Layer (SSL), Version 2, settings for Security Access Manager server communication.

Syntax

ssl-v2-enable = {yes|true|no|false}

Description

The ssl-v2-enable option has an effect only when ssl-compliance = none. The setting is for compatibility with version 6.1.1 of Security Access Manager.

Enabling SSL Version 2 is not required. By default, the SSL Version 2 protocol is disabled, which increases communication security.

Options

yes|true

Enables the SSL v2 protocol. The protocols SSL v3 and TLS are also choices for Security Access Manager communication and are chosen by Security Access Manager in preference to SSL Version 2, even if this setting is enabled.

no|false

Disables the SSL Version 2 protocol. Anything other than yes or true, including a blank value, is interpreted as no or false.

Usage

Optional. If used, must be set to the same value in all Security Access Manager server and application configuration files.

Default value

The default value is no.

Example

The following example disabled the SSL Version 2 protocol.

ssl-v2-enable = no

Parent topic: [ssl] stanza

ssl-session-cache-sizeThis stanza entry specifies the number of concurrent sessions supported by a Security Access Manager server or service.ssl-session-cache-sizeentriesssl-session-cache-sizessl stanzassl-session-cache-size entrySyntax ssl-session-cache-size = numeric value Description A larger cache size can improve the Secure Sockets Layer (SSL) security performance of the server if you add additional memory.The cache size can be 1-524,288 number of concurrent sessions.You might need to double the SSL session cache size for a target maximum cache size. For example: if you want a cache size of 8,192, set the ssl-session-cache-size parameter value to 16,384.Options numeric valueThe cache size can be 1-524,288 number of concurrent sessions. Usage Optional. Default valueThe default value is 1024. Example The following example sets the cache size at 1024.ssl-session-cache-size = 1024 [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-session-cache-size

This stanza entry specifies the number of concurrent sessions supported by a Security Access Manager server or service.

Syntax

ssl-session-cache-size = numeric value

Description

A larger cache size can improve the Secure Sockets Layer (SSL) security performance of the server if you add additional memory.

The cache size can be 1-524,288 number of concurrent sessions.

Note: You might need to double the SSL session cache size for a target maximum cache size. For example: if you want a cache size of 8,192, set the ssl-session-cache-size parameter value to 16,384.

Options

numeric value

The cache size can be 1-524,288 number of concurrent sessions.

Usage

Optional.

Default value

The default value is 1024.

Example

The following example sets the cache size at 1024.

ssl-session-cache-size = 1024

Parent topic: [ssl] stanza

ssl-v3-cipher-specsThis stanza entry defines the Secure Sockets Layer (SSL), Version 3, ciphers.ssl-v3-cipher-specsentriesssl-v3-cipher-specsssl stanzassl-v3-cipher-specs entrySyntax ssl-v3-cipher-specs = configuration string Description To specify the ciphers for SSL Version 3, modify the ssl-v3-cipher-specs parameter value in the appropriate configuration file. You can specify one or more ciphers. Enter multiple ciphers in a comma-separated list.Any SSL Version 3 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the ssl-v3-cipher-specs parameter. Options configuration stringAllowed SSLV30 CipherSpecs: TLS_RSA_WITH_NULL_NULL, TLS_RSA_WITH_NULL_MD5, TLS_RSA_WITH_NULL_SHA, TLS_RSA_EXPORT_WITH_RC4_40_MD5, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA (Deprecated), TLS_RSA_EXPORT1024_WITH_RC4_56_SHA (Deprecated), SSL_RSA_FIPS_WITH_DES_CBC_SHA (Deprecated), SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA (Deprecated), TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHAFIPS and NIST SP800-131a allowed SSLV30 CipherSpecs:None Usage Optional. Default value Default SSLV30 CipherSpecs:TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_EXPORT_WITH_RC4_40_MD5, TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA, TLS_RSA_EXPORT1024_WITH_RC4_56_SHA, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_NULL_MD5 Example ssl-v3-cipher-specs = TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

ssl-v3-cipher-specs

This stanza entry defines the Secure Sockets Layer (SSL), Version 3, ciphers.

Syntax

ssl-v3-cipher-specs = configuration string

Description

To specify the ciphers for SSL Version 3, modify the ssl-v3-cipher-specs parameter value in the appropriate configuration file. You can specify one or more ciphers. Enter multiple ciphers in a comma-separated list.

Any SSL Version 3 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the ssl-v3-cipher-specs parameter.

Options

configuration string

Allowed SSLV30 CipherSpecs:

TLS_RSA_WITH_NULL_NULL, TLS_RSA_WITH_NULL_MD5, TLS_RSA_WITH_NULL_SHA, TLS_RSA_EXPORT_WITH_RC4_40_MD5, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA (Deprecated), TLS_RSA_EXPORT1024_WITH_RC4_56_SHA (Deprecated), SSL_RSA_FIPS_WITH_DES_CBC_SHA (Deprecated), SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA (Deprecated), TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA

FIPS and NIST SP800-131a allowed SSLV30 CipherSpecs:

None

Usage

Optional.

Default value

Default SSLV30 CipherSpecs:

TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_EXPORT_WITH_RC4_40_MD5, TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA, TLS_RSA_EXPORT1024_WITH_RC4_56_SHA, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_NULL_MD5

Example

ssl-v3-cipher-specs = TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA

Parent topic: [ssl] stanza

tls-v10-cipher-specsThis stanza entry specifies the Transport Layer Security (TLS), Version 1.0, ciphers to use.tls-v10-cipher-specsentriestls-v10-cipher-specsssl stanzatls-v10-cipher-specs entrySyntax tls-v10-cipher-specs = configuration string Description To specify the ciphers for TLS Version 1.0, modify the tls-v10-cipher-specs parameter value in the appropriate configuration file. Enter multiple ciphers in a comma-separated list.Any TLS Version 1.0 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the tls-v10-cipher-specs parameter. Options configuration stringAllowed TLSV10 CipherSpecs: TLS_RSA_WITH_NULL_NULL, TLS_RSA_WITH_NULL_MD5, TLS_RSA_WITH_NULL_SHA, TLS_RSA_EXPORT_WITH_RC4_40_MD5, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA (Deprecated), TLS_RSA_EXPORT1024_WITH_RC4_56_SHA (Deprecated), TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHAFIPS and NIST SP800-131a allowed TLSV10 CipherSpecs: TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA Usage Optional. Default value Default TLSV10 CipherSpecs:TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_RC4_128_MD5 TLS_RSA_WITH_DES_CBC_SHA TLS_RSA_EXPORT_WITH_RC4_40_MD5 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA, TLS_RSA_EXPORT1024_WITH_RC4_56_SHA, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_NULL_MD5 Example tls-v10-cipher-specs = TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

tls-v10-cipher-specs

This stanza entry specifies the Transport Layer Security (TLS), Version 1.0, ciphers to use.

Syntax

tls-v10-cipher-specs = configuration string

Description

To specify the ciphers for TLS Version 1.0, modify the tls-v10-cipher-specs parameter value in the appropriate configuration file. Enter multiple ciphers in a comma-separated list.

Any TLS Version 1.0 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the tls-v10-cipher-specs parameter.

Options

configuration string

Allowed TLSV10 CipherSpecs:

TLS_RSA_WITH_NULL_NULL, TLS_RSA_WITH_NULL_MD5, TLS_RSA_WITH_NULL_SHA, TLS_RSA_EXPORT_WITH_RC4_40_MD5, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA (Deprecated), TLS_RSA_EXPORT1024_WITH_RC4_56_SHA (Deprecated), TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA

FIPS and NIST SP800-131a allowed TLSV10 CipherSpecs:

TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA

Usage

Optional.

Default value

Default TLSV10 CipherSpecs:

TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_RC4_128_MD5 TLS_RSA_WITH_DES_CBC_SHA TLS_RSA_EXPORT_WITH_RC4_40_MD5 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5, TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA, TLS_RSA_EXPORT1024_WITH_RC4_56_SHA, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_NULL_MD5

Example

tls-v10-cipher-specs = TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA

Parent topic: [ssl] stanza

tls-v11-cipher-specsDefines the Transport Layer Security (TLS), Version 1.1, ciphers.tls-v11-cipher-specsentriestls-v11-cipher-specsssl stanzatls-v11-cipher-specs entrySyntax tls-v11-cipher-specs = configuration string DescriptionTo specify the ciphers for TLS Version 1.1, modify the tls-v11-cipher-specs parameter value in the appropriate configuration file. You can specify one or more ciphers. Enter multiple ciphers in a comma-separated list.Any TLS Version 1.1 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the tls-v11-cipher-specs parameter. Options configuration stringAllowed TLSV11 CipherSpecs: TLS_RSA_WITH_NULL_NULL, TLS_RSA_WITH_NULL_MD5, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHAFIPS and NIST SP800-131a allowed TLSV11 CipherSpecs: TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA Usage Optional. Default value Default TLSV11 CipherSpecs:TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_NULL_MD5 Example tls-v11-cipher-specs = TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

tls-v11-cipher-specs

Defines the Transport Layer Security (TLS), Version 1.1, ciphers.

Syntax

tls-v11-cipher-specs = configuration string

Description

To specify the ciphers for TLS Version 1.1, modify the tls-v11-cipher-specs parameter value in the appropriate configuration file. You can specify one or more ciphers. Enter multiple ciphers in a comma-separated list.

Any TLS Version 1.1 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the tls-v11-cipher-specs parameter.

Options

configuration string

Allowed TLSV11 CipherSpecs:

TLS_RSA_WITH_NULL_NULL, TLS_RSA_WITH_NULL_MD5, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA

FIPS and NIST SP800-131a allowed TLSV11 CipherSpecs:

TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA

Usage

Optional.

Default value

Default TLSV11 CipherSpecs:

TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_RC4_128_MD5, TLS_RSA_WITH_DES_CBC_SHA, TLS_RSA_WITH_NULL_SHA, TLS_RSA_WITH_NULL_MD5

Example

tls-v11-cipher-specs = TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA

Parent topic: [ssl] stanza

tls-v12-cipher-specsThis stanza entry specifies the Transport Layer Security (TLS), Version 1.2, ciphers.tls-v12-cipher-specsentriestls-v12-cipher-specsssl stanzatls-v12-cipher-specs entrySyntax tls-v12-cipher-specs = configuration string Description To specify the ciphers for TLS Version 1.2, modify the tls-v12-cipher-specs parameter value in the appropriate configuration file. You can specify one or more ciphers. Enter multiple ciphers in a comma-separated list.Any TLS Version 1.2 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the tls-v12-cipher-specs parameter. Options configuration stringAllowed TLSV12 CipherSpecs: The allowed CipherSpecs are the same as the Default TLSV12 CipherSpecs with the addition of: TLS_RSA_WITH_NULL_NULL TLS_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA FIPS and NIST SP800-131a allowed TLSV12 CipherSpecs: TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 Suite B Allowed TLSV12 CipherSpecs:TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 Usage Optional. Default value Default TLSV12 CipherSpecs:TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_NULL_SHA256 TLS_RSA_WITH_NULL_SHA TLS_ECDHE_RSA_WITH_NULL_SHA TLS_ECDHE_ECDSA_WITH_NULL_SHATLS Version 1.2 CipherSpecs that do not explicitly indicate a SHA256 or SHA384 hash implicitly use a SHA256 or SHA384 hash. However, the use of CipherSpecs that do not explicitly indicate a SHA256 or SHA384 hash with TLS Version 1.2 might result in interoperability problems with SSL and TLS stacks. CipherSpecs with explicit SHA256 or SHA384 hashes must be used. Example tls-v12-cipher-specs = TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_CBC_SHA256 [ssl] stanzaThe [ssl] stanza in the configuration file defines the Secure Sockets Layer (SSL) configuration settings for the Security Access Manager servers.

tls-v12-cipher-specs

This stanza entry specifies the Transport Layer Security (TLS), Version 1.2, ciphers.

Syntax

tls-v12-cipher-specs = configuration string

Description

To specify the ciphers for TLS Version 1.2, modify the tls-v12-cipher-specs parameter value in the appropriate configuration file. You can specify one or more ciphers. Enter multiple ciphers in a comma-separated list.

Any TLS Version 1.2 connection to a Security Access Manager server or service is limited to the set of ciphers defined in the tls-v12-cipher-specs parameter.

Options

configuration string

Allowed TLSV12 CipherSpecs: The allowed CipherSpecs are the same as the Default TLSV12 CipherSpecs with the addition of:

TLS_RSA_WITH_NULL_NULL TLS_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA

FIPS and NIST SP800-131a allowed TLSV12 CipherSpecs:

TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Suite B Allowed TLSV12 CipherSpecs:

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Usage

Optional.

Default value

Default TLSV12 CipherSpecs:

TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_RSA_WITH_NULL_SHA256 TLS_RSA_WITH_NULL_SHA TLS_ECDHE_RSA_WITH_NULL_SHA TLS_ECDHE_ECDSA_WITH_NULL_SHA

Note: TLS Version 1.2 CipherSpecs that do not explicitly indicate a SHA256 or SHA384 hash implicitly use a SHA256 or SHA384 hash. However, the use of CipherSpecs that do not explicitly indicate a SHA256 or SHA384 hash with TLS Version 1.2 might result in interoperability problems with SSL and TLS stacks. CipherSpecs with explicit SHA256 or SHA384 hashes must be used.

Example

tls-v12-cipher-specs = TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_CBC_SHA256

Parent topic: [ssl] stanza

[xmladi-attribute-definitions] stanzaThe stanza entries for configuring the Access Decision Information Extensible Markup Language (ADI XML) document attribute definitions are in the [xmladi-attribute-definitions] stanza.stanzasxmladi-attribute-definitionxmladi-attribute-definition stanzadefinitionThis stanza can be found or placed into any of the Security Access Manager configuration files, except for the pd.conf configuration file.The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.Configuration file stanza referenceWithin configuration files, stanza labels occur within brackets, such as [stanza-name].AttributeNameThis stanza entry defines ADI XML document attributes that are inserted into the XML ADI element start tag.

[xmladi-attribute-definitions] stanza

The stanza entries for configuring the Access Decision Information Extensible Markup Language (ADI XML) document attribute definitions are in the [xmladi-attribute-definitions] stanza.

This stanza can be found or placed into any of the Security Access Manager configuration files, except for the pd.conf configuration file.

The aznAPI.conf configuration file is provided with Security Access Manager as a sample file for creating your own resource manager configuration file. Developers of service plug-ins typically provide the standard functions. Before you implement service plug-ins, read and thoroughly understand the concepts in the Authorization C API Developer Reference.

AttributeName
This stanza entry defines ADI XML document attributes that are inserted into the XML ADI element start tag.

Parent topic: Configuration file stanza reference

AttributeNameThis stanza entry defines ADI XML document attributes that are inserted into the XML ADI element start tag.AttributeName entryentriesAttributeNamexmladi-attribute-definition stanzaAttributeName entrySyntax AttributeName = "AttributeValue" Description Definition of ADI XML document attributes that are inserted into the XML ADI element start tag. The entry enables attributes to be defined for the entire XML ADI document and for all ADI defined in the XML ADI document.The ADI XML model requires that the XML document contains the following top-level XML element into which all target ADI for a particular rule evaluation is inserted. The XMLADI element is created automatically as part of the rule evaluation process: <XMLADI> <!-- XML formatted ADI are inserted here. --> </XMLADI> Usage Required Example xmlns:myNS = "http://myURI.mycompany.com" appID = '"Jupiter" - Account Management Web Portal Server #1.' The attribute value must be enclosed in either double or single quotation marks. The following XMLADI element start tag defines these attributes: <XMLADI xmlns:myNS="http://myURI.mycompany.com" appID='"Jupiter" - Account Management Web Portal Server #1.'> See Authorization rules managementThese topics provide information about Security Access Manager authorization rules. Authorization rules are conditions contained in an authorization policy that are used to make access decisions based on attributes such as user, application, and environment context.. [xmladi-attribute-definitions] stanzaThe stanza entries for configuring the Access Decision Information Extensible Markup Language (ADI XML) document attribute definitions are in the [xmladi-attribute-definitions] stanza.

AttributeName

This stanza entry defines ADI XML document attributes that are inserted into the XML ADI element start tag.

Syntax

AttributeName = "AttributeValue"

Description

Definition of ADI XML document attributes that are inserted into the XML ADI element start tag. The entry enables attributes to be defined for the entire XML ADI document and for all ADI defined in the XML ADI document.

The ADI XML model requires that the XML document contains the following top-level XML element into which all target ADI for a particular rule evaluation is inserted. The XMLADI element is created automatically as part of the rule evaluation process:

<XMLADI>
<!--  XML formatted ADI are inserted here.  -->
</XMLADI>

Usage

Required

Example

xmlns:myNS = "http://myURI.mycompany.com"
appID = '"Jupiter" - Account Management Web Portal Server #1.'

The attribute value must be enclosed in either double or single quotation marks.

The following XMLADI element start tag defines these attributes:

<XMLADI xmlns:myNS="http://myURI.mycompany.com"
appID='"Jupiter" - Account Management Web Portal Server #1.'>

See Authorization rules management.

Parent topic: [xmladi-attribute-definitions] stanza

User registry differencesEach user registry presents unique concerns when integrated with Security Access Manager. This release of Security Access Manager supports the specified LDAP user registries.userregistriesdifferencesSecurity Access Manager supports the following LDAP user registries: Active Directory Lightweight Directory Service (AD LDS)IBM z/OS Security Server LDAP ServerNovell eDirectory ServerSun Java System Directory ServerSecurity Directory ServerAccess Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. General concernsThere are several concerns specific to all supported user registries.LDAP concernsThere are several concerns specific to all supported LDAP user registries.Length of namesThe maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry that is being used.

User registry differences

Each user registry presents unique concerns when integrated with Security Access Manager. This release of Security Access Manager supports the specified LDAP user registries.

Security Access Manager supports the following LDAP user registries:

Active Directory Lightweight Directory Service (AD LDS)

IBM® z/OS® Security Server LDAP Server

Novell eDirectory Server

Sun Java™ System Directory Server

Security Directory Server

General concerns
There are several concerns specific to all supported user registries.

LDAP concerns
There are several concerns specific to all supported LDAP user registries.

Length of names
The maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry that is being used.

Parent topic: Access Manager Platform and Supporting Components administration

General concernsThere are several concerns specific to all supported user registries.userregistriesconsiderations for user namesDo not use the forward slash (/) character when defining the names for users and groups when distinguished names strings are used to define the name. Each user registry treats this character differently.Do not use leading and trailing blanks in user and group names. Each user registry treats blanks differently.User registry differencesEach user registry presents unique concerns when integrated with Security Access Manager. This release of Security Access Manager supports the specified LDAP user registries.

General concerns

There are several concerns specific to all supported user registries.

Do not use the forward slash (/) character when defining the names for users and groups when distinguished names strings are used to define the name. Each user registry treats this character differently.

Do not use leading and trailing blanks in user and group names. Each user registry treats blanks differently.

Parent topic: User registry differences

LDAP concernsThere are several concerns specific to all supported LDAP user registries.LDAPconcernspasswordpolicy, LDAPThere are no configuration steps needed to make Security Access Manager support the password policy of the LDAP. Security Access Manager does not assume that the LDAP has its own password policy. Security Access Manager first enforces its own Password Policy. Security Access Manager attempts to update the password in LDAP only if the provided password meets the requirements of the Security Access Manager password policy. Next, Security Access Manager implements the password policy of the LDAP by using the return code that it gets from LDAP during a password-related update. If Security Access Manager can map the return code without ambiguity with the corresponding error code, then it maps the code and returns an error message.To take advantage of the multi-domain support in Security Access Manager, you must use an LDAP user registry. When using an LDAP user registry, the capability to own global sign-on credentials must be explicitly granted to a user. After this capability is granted, it can then be removed. Leading and trailing blanks in user names and group names are ignored when using an LDAP user registry in a Security Access Manager secure domain. To ensure consistent processing regardless of the user registry, define user names and group names without leading or trailing blanks.Attempting to add a single duplicate user to a group does not produce an error when using an LDAP user registry.The Security Access Manager authorization API provides a credential attribute entitlements service. This service is used to retrieve user attributes from a user registry. When this service is used with an LDAP user registry, the retrieved attributes can be string data or binary data.User registry differencesEach user registry presents unique concerns when integrated with Security Access Manager. This release of Security Access Manager supports the specified LDAP user registries.Modifying Sun Java System Directory Server look-through limitWhen the directory server is installed, the default value is 5000. You can modify this value.Microsoft Active Directory Lightweight Directory Service (AD LDS) concernsThe following concerns are specific to Microsoft Active Directory Lightweight Directory Service (AD LDS).Federated registry supportConsider the following points when you configure federated registry support.

LDAP concerns

There are several concerns specific to all supported LDAP user registries.

There are no configuration steps needed to make Security Access Manager support the password policy of the LDAP. Security Access Manager does not assume that the LDAP has its own password policy. Security Access Manager first enforces its own Password Policy. Security Access Manager attempts to update the password in LDAP only if the provided password meets the requirements of the Security Access Manager password policy.

Next, Security Access Manager implements the password policy of the LDAP by using the return code that it gets from LDAP during a password-related update.

If Security Access Manager can map the return code without ambiguity with the corresponding error code, then it maps the code and returns an error message.

To take advantage of the multi-domain support in Security Access Manager, you must use an LDAP user registry.

When using an LDAP user registry, the capability to own global sign-on credentials must be explicitly granted to a user. After this capability is granted, it can then be removed.

Leading and trailing blanks in user names and group names are ignored when using an LDAP user registry in a Security Access Manager secure domain. To ensure consistent processing regardless of the user registry, define user names and group names without leading or trailing blanks.

Attempting to add a single duplicate user to a group does not produce an error when using an LDAP user registry.

The Security Access Manager authorization API provides a credential attribute entitlements service. This service is used to retrieve user attributes from a user registry. When this service is used with an LDAP user registry, the retrieved attributes can be string data or binary data.

Modifying Sun Java System Directory Server look-through limit
When the directory server is installed, the default value is 5000. You can modify this value.

Microsoft Active Directory Lightweight Directory Service (AD LDS) concerns
The following concerns are specific to Microsoft Active Directory Lightweight Directory Service (AD LDS).

Federated registry support
Consider the following points when you configure federated registry support.

Parent topic: User registry differences

Modifying Sun Java System Directory Server look-through limitWhen the directory server is installed, the default value is 5000. You can modify this value.LDAP_ADMINLIMIT_EXCEEDEDlook-through limitSun Java System Directory ServerLDAP_ADMINLIMIT_ EXCEEDEDSun Java System Directory Serverlook-through limitIf the user registry contains more entries than the defined look-through limit, then the directory server returns the following status: LDAP_ADMINLIMIT_EXCEEDEDSecurity Access Manager treats this status as an error.On the Sun Java System Directory Server Console, select the Configuration tab.Expand the Data entry.Select Database Settings.Select the LDBM Plug-in Settings tab.In the Look-through Limit field, type the maximum number of entries that you want the server to check in response to the search. Alternatively, type -1 to define no maximum limit.If you bind the directory as the Directory Manager, the look-through limit is unlimited and overrides any settings specified in this field.LDAP concernsThere are several concerns specific to all supported LDAP user registries.

Modifying Sun Java System Directory Server look-through limit

When the directory server is installed, the default value is 5000. You can modify this value.

About this task

If the user registry contains more entries than the defined look-through limit, then the directory server returns the following status:

LDAP_ADMINLIMIT_EXCEEDED

Security Access Manager treats this status as an error.

Procedure

On the Sun Java™ System Directory Server Console, select the Configuration tab.

Expand the Data entry.

Select Database Settings.

Select the LDBM Plug-in Settings tab.

In the Look-through Limit field, type the maximum number of entries that you want the server to check in response to the search. Alternatively, type -1 to define no maximum limit.

Note: If you bind the directory as the Directory Manager, the look-through limit is unlimited and overrides any settings specified in this field.

Parent topic: LDAP concerns

Microsoft Active Directory Lightweight Directory Service (AD LDS) concernsThe following concerns are specific to Microsoft Active Directory Lightweight Directory Service (AD LDS).Active DirectoryLightweight Directory Service considerationsAD LDSActive Directory Lightweight Directory ServiceIn the Policy Server configuration, you can select either a standard data model or a minimal data model for the user registry. If you use AD LDS, you must select the minimal data model, because AD LDS allows only a single naming attribute when creating LDAP objects. When AD LDS is selected as the user registry, Security Access Manager always uses the minimal data model even if the standard data model is selected during the Policy Server configuration. The common name (cn) attribute is a single-value attribute and can store only one value. The AD LDS registry requires the value of cn to be the same as the cn naming attribute in the distinguished name (dn) attribute. When creating a user or group in Security Access Manager, specify the same value for cn as the cn naming attribute in the dn. Security Access Manager ignores the value of the cn attribute if it is different from the value of the cn naming attribute in the dn. For example, you cannot use the following command to create a user because the value of the cn attribute, fred, is different from the cn naming attribute in the dn, user1: pdadmin user create user1 cn=user1,o=ibm,c=us fred smith password1LDAP concernsThere are several concerns specific to all supported LDAP user registries.

Microsoft Active Directory Lightweight Directory Service (AD LDS) concerns

The following concerns are specific to Microsoft Active Directory Lightweight Directory Service (AD LDS).

In the Policy Server configuration, you can select either a standard data model or a minimal data model for the user registry. If you use AD LDS, you must select the minimal data model, because AD LDS allows only a single naming attribute when creating LDAP objects. When AD LDS is selected as the user registry, Security Access Manager always uses the minimal data model even if the standard data model is selected during the Policy Server configuration.

The common name (cn) attribute is a single-value attribute and can store only one value. The AD LDS registry requires the value of cn to be the same as the cn naming attribute in the distinguished name (dn) attribute. When creating a user or group in Security Access Manager, specify the same value for cn as the cn naming attribute in the dn. Security Access Manager ignores the value of the cn attribute if it is different from the value of the cn naming attribute in the dn. For example, you cannot use the following command to create a user because the value of the cn attribute, fred, is different from the cn naming attribute in the dn, user1:

pdadmin user create user1 cn=user1,o=ibm,c=us fred smith password1

Parent topic: LDAP concerns

Federated registry supportConsider the following points when you configure federated registry support.The federated registry support feature provides the following benefits:It provides the ability to use Security Access Manager with a user registry without requiring the addition of Security Access Manager schema changes, accounts, and access controls in the user registry. These are instead stored in an separate registry leaving the user registry untouched.Multiple user registries can be federated into one common Security Access Manager registry.It introduces a method to support Active Directory for policy servers running on the appliance.The following limitations apply to supported federated registries:IBM Security Directory Server nested groups are not supported for foreign user DN members.Dynamic groups are only supported for user DNs in the same registry in which the group exists. Each domain in Active Directory Forest is considered a different registry. IBM Security Directory Server supports foreign member DNs. This means that Active Directory native users could be added to Security Access Manager registry groups such as su-admins. However the nested group limitation applies.Active Directory: Active Directory groups do not support adding foreign user DN members. For example, users in the Security Access Manager registry such as sec_master can not be made members of Active Directory groups.When a native Active Directory user is removed by a process outside of Security Access Manager, and that user was also a Security Access Manager enabled user, Security Access Manager does not automatically detect and remove the Security Access Manager component of this user.Active Directory Forest: The Global Catalog is not an option for locating user credentials, only the Security Access Manager principalName is used.The connection to the registry must be over SSL/TLS for password operations to be permitted by Active Directory.Security Access Manager must be provided with an account (bind-dn) with sufficient privileges for the operations required on the suffixes of registry being federated to it. In some cases the actual users being federated need certain privileges.The bind-dn account is shared by all Security Access Manager processes on the same appliance. Thus it requires the permissions that will satisfy all these processes. For example, if both WebSEAL and the policy server are on the same appliance, then the bind-dn account needs all the permissions required by both.For all registry types and use cases: The bind-dn account needs permission to read attributes from the root DSE entry ("").Password Change: If options bind-auth-and-pwdchg = yes or enhanced-pwd-policy = yes are set, then Security Access Manager managed federated users need permission to modify their own password. For example, the IBM Security Directory Server LDAP server requires an ACL to be attached, such as:aclEntry: access-id:cn=this:at.userPassword:grant:wIf bind-auth-and-pwdchg = no, enhanced-pwd-policy = no, auth-using-compare = yes, and auth-using-compare is supported for the LDAP server, then the bind-dn account needs permission to be able to do an LDAP compare operation on the user's userPassword attribute.If neither of the previous two configurations are in force, then the bind-dn account needs password reset permissions discussed as follows.The configuration property bind-auth-and-pwdchg is configurable per federated registry stanza and for the Security Access Manager registry itself. It defaults to FALSE for all federated registries except Active Directory.The configuration property enhanced-pwd-policy is a single global setting common to all federated registries and the Security Access Manager registry itself. The Active Directory federated registry implementation does not provide all the features of enhanced-pwd-policy.Password Reset: If you reset the password with the pdadmin> user modify <user> password <password> command, then the bind-dn account needs permission to be able to set or reset a user's userPassword attribute (or unicodePwd for Active Directory).Credential Construction:Active Directory: The bind-dn account needs permission to be able to read the memberOf attribute of a user.If dynamic-groups-enabled = yes, then bind-dn account needs permission to read the authorization store containing the groups with attribute groupType=34 and read the group attribute msDS-AzLDAPQuery, which contains a search filter. The bind-dn account then needs permission to search for user entries under the specified suffixes using this search filter.IBM Security Directory Server: The bind-dn account needs permission to be able to read the ibm-allGroups attribute of a user.Oracle Sun Directory Server: If dynamic-groups-enabled = yes, then bind-dn account needs permission to search under the specified suffix for group entries with an objectClass=groupOfURLs. It also needs permission to read the group attribute memberURL, which contains a search suffix, scope, and filter. The bind-dn account then needs permission to search for user entries under the specified suffix using this search filter and scope.For other supported registries, the bind-dn account needs permission to search for group entries under the specified suffixes and read their member entries.The configuration property dynamic-groups-enabled is configurable per federated registry stanza and for the Security Access Manager registry itself. It defaults to FALSE except for IBM Security Directory Server, which automatically provides dynamic group memberships using the ibm-allGroups attribute.Read access to additional user entry attributes might be required if Security Access Manager is configured to fetch and add their values to the credential.Import User or Group: The bind-dn account needs permission to read the user or group objectclass attribute.If you do not plan to view, add, remove, or modify the federated registry native user and group accounts, then no additional permissions are required.Federated registry native user and group administration via pdadmin: The bind-dn account must have permission to view, add, remove, and modify users and groups and modify group memberships under the specified federated registry suffix.LDAP concernsThere are several concerns specific to all supported LDAP user registries.AD registry support configurationFollow these steps to set up the Security Access Manager to support federated registries.

Federated registry support

Consider the following points when you configure federated registry support.

The federated registry support feature provides the following benefits:

It provides the ability to use Security Access Manager with a user registry without requiring the addition of Security Access Manager schema changes, accounts, and access controls in the user registry. These are instead stored in an separate registry leaving the user registry untouched.

Multiple user registries can be federated into one common Security Access Manager registry.

It introduces a method to support Active Directory for policy servers running on the appliance.

The following limitations apply to supported federated registries:

IBM Security Directory Server nested groups are not supported for foreign user DN members.

Dynamic groups are only supported for user DNs in the same registry in which the group exists.

Note: Each domain in Active Directory Forest is considered a different registry.

IBM Security Directory Server supports foreign member DNs. This means that Active Directory native users could be added to Security Access Manager registry groups such as su-admins. However the nested group limitation applies.

Active Directory:

Active Directory groups do not support adding foreign user DN members. For example, users in the Security Access Manager registry such as sec_master can not be made members of Active Directory groups.

When a native Active Directory user is removed by a process outside of Security Access Manager, and that user was also a Security Access Manager enabled user, Security Access Manager does not automatically detect and remove the Security Access Manager component of this user.

Active Directory Forest: The Global Catalog is not an option for locating user credentials, only the Security Access Manager principalName is used.

The connection to the registry must be over SSL/TLS for password operations to be permitted by Active Directory.

Security Access Manager must be provided with an account (bind-dn) with sufficient privileges for the operations required on the suffixes of registry being federated to it. In some cases the actual users being federated need certain privileges.

The bind-dn account is shared by all Security Access Manager processes on the same appliance. Thus it requires the permissions that will satisfy all these processes. For example, if both WebSEAL and the policy server are on the same appliance, then the bind-dn account needs all the permissions required by both.

For all registry types and use cases: The bind-dn account needs permission to read attributes from the root DSE entry ("").

Password Change:

If options bind-auth-and-pwdchg = yes or enhanced-pwd-policy = yes are set, then Security Access Manager managed federated users need permission to modify their own password. For example, the IBM Security Directory Server LDAP server requires an ACL to be attached, such as:

aclEntry: access-id:cn=this:at.userPassword:grant:w

If bind-auth-and-pwdchg = no, enhanced-pwd-policy = no, auth-using-compare = yes, and auth-using-compare is supported for the LDAP server, then the bind-dn account needs permission to be able to do an LDAP compare operation on the user's userPassword attribute.

If neither of the previous two configurations are in force, then the bind-dn account needs password reset permissions discussed as follows.

The configuration property bind-auth-and-pwdchg is configurable per federated registry stanza and for the Security Access Manager registry itself. It defaults to FALSE for all federated registries except Active Directory.

The configuration property enhanced-pwd-policy is a single global setting common to all federated registries and the Security Access Manager registry itself. The Active Directory federated registry implementation does not provide all the features of enhanced-pwd-policy.

Password Reset:

If you reset the password with the pdadmin> user modify <user> password <password> command, then the bind-dn account needs permission to be able to set or reset a user's userPassword attribute (or unicodePwd for Active Directory).

Credential Construction:

Active Directory:

The bind-dn account needs permission to be able to read the memberOf attribute of a user.

If dynamic-groups-enabled = yes, then bind-dn account needs permission to read the authorization store containing the groups with attribute groupType=34 and read the group attribute msDS-AzLDAPQuery, which contains a search filter. The bind-dn account then needs permission to search for user entries under the specified suffixes using this search filter.

IBM Security Directory Server: The bind-dn account needs permission to be able to read the ibm-allGroups attribute of a user.

Oracle Sun Directory Server: If dynamic-groups-enabled = yes, then bind-dn account needs permission to search under the specified suffix for group entries with an objectClass=groupOfURLs. It also needs permission to read the group attribute memberURL, which contains a search suffix, scope, and filter. The bind-dn account then needs permission to search for user entries under the specified suffix using this search filter and scope.

For other supported registries, the bind-dn account needs permission to search for group entries under the specified suffixes and read their member entries.

Notes:

The configuration property dynamic-groups-enabled is configurable per federated registry stanza and for the Security Access Manager registry itself. It defaults to FALSE except for IBM Security Directory Server, which automatically provides dynamic group memberships using the ibm-allGroups attribute.

Read access to additional user entry attributes might be required if Security Access Manager is configured to fetch and add their values to the credential.

Import User or Group: The bind-dn account needs permission to read the user or group objectclass attribute.

If you do not plan to view, add, remove, or modify the federated registry native user and group accounts, then no additional permissions are required.

Federated registry native user and group administration via pdadmin: The bind-dn account must have permission to view, add, remove, and modify users and groups and modify group memberships under the specified federated registry suffix.

AD registry support configuration
Follow these steps to set up the Security Access Manager to support federated registries.

Parent topic: LDAP concerns

AD registry support configurationFollow these steps to set up the Security Access Manager to support federated registries.Set up a Security Access Manager policy server using either the appliance internal LDAP server or an external TDS LDAP server.You cannot set up the policy server directly in AD.Federate the AD registry suffixes into the Security Access Manager registry. The AD registry must be accessed using its LDAP SSL interface. You can use either of the following methods:Using the Federated Directories management page in the appliance LMIFrom the top menu, select Secure Web SettingsManageRuntime Component.Select ManageFederated Directories.Click New.Enter the information for the AD registry suffix to add.Click Save.Modifying the ldap.conf configuration file manually. For example:[server:myadserver] bind-dn = CN=Administrator,CN=Users,DC=home,DC=com bind-pwd = P@ssw0rd host = myad.ibm.com port = 636 ssl-enabled = yes suffix = DC=home,DC=com #dynamic-groups-enabled = no bind-auth-and-pwdchg = yesYou can federate multiple servers. So for an AD forest, you would need multiple [server:<inst>] stanzas for each AD server that contains users or groups you want to access. Some of the options such as dynamic-groups-enabled and bind-auth-and-pwdchg can only be set by manually modifying the ldap.conf configuration file. You cannot use the LMI method to set these options.If you are not using SSL to your Security Access Manager registry (internal or TDS), then you also need to set up a keyfile for the SSL access to AD. You can use either of the following methods:Using the Federated Directories management page in the appliance LMIFrom the top menu, select Secure Web SettingsManageRuntime Component.Select ManageFederated Directories.Click SSL Settings.Provide values for the displayed fields.Click Save.Modifying the ldap.conf configuration file manually. For example:[ldap] ssl-keyfile = /opt/PolicyDirector/etc/ldapssl.kdb ssl-keyfile-pwd = passw0rdThe bind-pwd and ssl-keyfile-pwd should be placed in the ldap.conf obfuscation file. The ssl-keyfile settings in ivmgrd.conf, ivacld*.conf or webseald*.conf take precedence for their respective processes over the values in ldap.conf.After you have federated AD suffixes into your Security Access Manager registry, you can manipulate the AD users and groups in those suffixes as normal Security Access Manager users. For example, you can import an AD user into Security Access Manager:pdadmin sec_master> user import testuser CN=testuser,CN=Users,DC=home,DC=comThere are some restrictions as to foreign group memberships (cross-federated registry). For example, AD groups do not allow adding Security Access Manager registry (non-AD) user members, but appliance internal or TDS registry groups do allow AD user members. You can add the AD user Administrator to su-admins (cn=su-admins,cn=SecurityGroups,secAuthority=Default), but you cannot add the Security Access Manager user sec_master to the AD group Administrators (CN=Administrators,CN=Builtin,DC=home,DC=com).Federated registry supportConsider the following points when you configure federated registry support.

AD registry support configuration

Follow these steps to set up the Security Access Manager to support federated registries.

Set up a Security Access Manager policy server using either the appliance internal LDAP server or an external TDS LDAP server.

Note: You cannot set up the policy server directly in AD.

Federate the AD registry suffixes into the Security Access Manager registry. The AD registry must be accessed using its LDAP SSL interface. You can use either of the following methods:

Using the Federated Directories management page in the appliance LMI

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select Manage > Federated Directories.

Click New.

Enter the information for the AD registry suffix to add.

Click Save.

Modifying the ldap.conf configuration file manually. For example:

[server:myadserver]
bind-dn = CN=Administrator,CN=Users,DC=home,DC=com
bind-pwd = P@ssw0rd
host = myad.ibm.com
port = 636
ssl-enabled = yes
suffix = DC=home,DC=com
#dynamic-groups-enabled = no
bind-auth-and-pwdchg = yes

Note: You can federate multiple servers. So for an AD forest, you would need multiple [server:<inst>] stanzas for each AD server that contains users or groups you want to access. Some of the options such as dynamic-groups-enabled and bind-auth-and-pwdchg can only be set by manually modifying the ldap.conf configuration file. You cannot use the LMI method to set these options.

If you are not using SSL to your Security Access Manager registry (internal or TDS), then you also need to set up a keyfile for the SSL access to AD. You can use either of the following methods:

Using the Federated Directories management page in the appliance LMI

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select Manage > Federated Directories.

Click SSL Settings.

Provide values for the displayed fields.

Click Save.

Modifying the ldap.conf configuration file manually. For example:

[ldap]
ssl-keyfile = /opt/PolicyDirector/etc/ldapssl.kdb
ssl-keyfile-pwd = passw0rd

Note: The bind-pwd and ssl-keyfile-pwd should be placed in the ldap.conf obfuscation file. The ssl-keyfile settings in ivmgrd.conf, ivacld*.conf or webseald*.conf take precedence for their respective processes over the values in ldap.conf.

After you have federated AD suffixes into your Security Access Manager registry, you can manipulate the AD users and groups in those suffixes as normal Security Access Manager users. For example, you can import an AD user into Security Access Manager:

pdadmin sec_master> user import testuser CN=testuser,CN=Users,DC=home,DC=com

There are some restrictions as to foreign group memberships (cross-federated registry). For example, AD groups do not allow adding Security Access Manager registry (non-AD) user members, but appliance internal or TDS registry groups do allow AD user members. You can add the AD user Administrator to su-admins (cn=su-admins,cn=SecurityGroups,secAuthority=Default), but you cannot add the Security Access Manager user sec_master to the AD group Administrators (CN=Administrators,CN=Builtin,DC=home,DC=com).

Parent topic: Federated registry support

Length of namesThe maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry that is being used.name lengthuserregistrieslength of names inSee Table 1 for a comparison of the maximum lengths that are allowed and the recommended maximum length to use to ensure compatibility with all the user registries that are supported by Security Access Manager. Maximum lengths for names by user registry and the optimum length across user registriesuserregistriesmaximum valuesNameIBM Security Directory ServerIBM z/OS Security ServerNovell eDirectory ServerSun Java System Directory ServerMicrosoft Active Directory ServerActive Directory Lightweight Directory Service (AD LDS)Optimum lengthGiven name (LDAP CN)256256 64256646464Middle name128128128128646464Family name128128128128646464Registry UID (LDAP DN)102410241024102420481024255Security Access Manager user identity256256256256646464User passwordunlimitedunlimitedunlimitedunlimited256128256User description1024102410241024102410241024Group name256256256256646464Group description1024102410241024102410241024Single sign-on resource name2402402402406024060Single sign-on resource description1024102410241024102410241024Single sign-on user ID2402402402406024060Single sign-on passwordunlimitedunlimitedunlimitedunlimited256unlimited256Single sign-on group name2402402402406024060Single sign-on group description1024102410241024102410241024Action name1111111Action description, action typeunlimitedunlimitedunlimitedunlimitedunlimitedunlimited unlimitedObject name, object descriptionunlimitedunlimitedunlimitedunlimitedunlimitedunlimited unlimitedObject space name, object space descriptionunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedACL name, ACL descriptionsunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedunlimitedPOP name, POP descriptionunlimitedunlimitedunlimitedunlimitedunlimited unlimitedAlthough the maximum length of an Active Directory distinguished name (registry UID) is 2048, the maximum length of each relative distinguished name (RDN) is 64.If you configure Security Access Manager to use multiple Active Directory domains, the maximum length of the user identity and group name does not include the domain suffix. When using multiple domains, the format of a user identity is user_id@domain_suffix. The maximum length of 64 characters applies only to the user_id portion. When using an email address or other format for the Security Access Manager user identity in the Active Directory, then the maximum name length remains the same but it includes the suffix.Although the lengths of some names can be unlimited, the excessive lengths can result in a policy that is difficult to manage and might result in poor system performance. Choose maximum values that are logical for your environment.User registry differencesEach user registry presents unique concerns when integrated with Security Access Manager. This release of Security Access Manager supports the specified LDAP user registries.

Length of names

The maximum lengths of various names that are associated with Security Access Manager vary depending on the user registry that is being used.

See Table 182 for a comparison of the maximum lengths that are allowed and the recommended maximum length to use to ensure compatibility with all the user registries that are supported by Security Access Manager.

Table 182. Maximum lengths for names by user registry and the optimum length across user registries

Name
IBM Security Directory Server
IBM® z/OS® Security Server
Novell eDirectory Server
Sun Java™ System Directory Server
Microsoft Active Directory Server

Active Directory Lightweight Directory Service (AD LDS)

Optimum length

Given name (LDAP CN)
256
256
64
256
64
64
64

Middle name
128
128
128
128
64
64
64

Family name
128
128
128
128
64
64
64

Registry UID (LDAP DN)
1024
1024
1024
1024
2048
1024
255

Security Access Manager user identity
256
256
256
256
64
64
64

User password
unlimited
unlimited
unlimited
unlimited
256
128
256

User description
1024
1024
1024
1024
1024
1024
1024

Group name
256
256
256
256
64
64
64

Group description
1024
1024
1024
1024
1024
1024
1024

Single sign-on resource name
240
240
240
240
60
240
60

Single sign-on resource description
1024
1024
1024
1024
1024
1024
1024

Single sign-on user ID
240
240
240
240
60
240
60

Single sign-on password
unlimited
unlimited
unlimited
unlimited
256
unlimited
256

Single sign-on group name
240
240
240
240
60
240
60

Single sign-on group description
1024
1024
1024
1024
1024
1024
1024

Action name
1
1
1
1
1
1
1

Action description, action type
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited

Object name, object description
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited

Object space name, object space description
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited

ACL name, ACL descriptions
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited
unlimited

POP name, POP description

unlimited
unlimited
unlimited
unlimited
unlimited
unlimited

Although the maximum length of an Active Directory distinguished name (registry UID) is 2048, the maximum length of each relative distinguished name (RDN) is 64.

If you configure Security Access Manager to use multiple Active Directory domains, the maximum length of the user identity and group name does not include the domain suffix. When using multiple domains, the format of a user identity is user_id@domain_suffix. The maximum length of 64 characters applies only to the user_id portion. When using an email address or other format for the Security Access Manager user identity in the Active Directory, then the maximum name length remains the same but it includes the suffix.

Although the lengths of some names can be unlimited, the excessive lengths can result in a policy that is difficult to manage and might result in poor system performance. Choose maximum values that are logical for your environment.

Parent topic: User registry differences

pdadmin to Web Portal Manager equivalentsThis appendix shows the mapping of the administration pdadmin commands to Web Portal Manager.pdadmin CLI, mapping to Web Portal ManagerInformation about the pdadmin utility can be found in the IBM Security Access Manager for Web: Command Reference.Mapping between the pddamin utility and Web Portal Managerpdadmin utilityWeb Portal Manageracl attach object_name acl_nameACL → List ACL → click ACL name → Attach tab → Attach → type protected object path → Attachacl create acl_nameACL → Create ACL → complete the form → Createacl delete acl_nameACL → List ACL → select ACL names → Deleteacl detach object_nameACL → List ACL → click ACL name → Attach tab → select protected object → Detachacl find acl_nameACL → List ACL → click ACL name → Attach tabacl listACL → List ACLacl list acl_name attributeACL → List ACL → click ACL name → Extended Attribute tabacl modify acl_name delete attribute attribute_nameACL → List ACL → select ACL name → Extended Attribute tab → select attributes → Deleteacl modify acl_name delete attribute attribute_name attribute_valueNot supportedacl modify acl_name description descriptionACL → List ACL → click ACL name → modify description → Setacl modify acl_name remove any-otherACL → List ACL → click ACL name → select Any-other → Deleteacl modify acl_name remove group group_nameACL → List ACL → click ACL name → select group name → Deleteacl modify acl_name remove unauthenticatedACL → List ACL → click ACL name → select Unauthenticated → Deleteacl modify acl_name remove user user_nameACL → List ACL → click ACL name → select user name → Deleteacl modify acl_name set any-other permissionsACL → List ACL → click ACL name → select Any-other → Create → select permissions → Applyacl modify acl_name set attribute attribute_name attribute_valueACL → List ACL → click ACL name → Extended Attribute tab → Create → complete the form → Applyacl modify acl_name set group group_name permissionsACL → List ACL → click ACL name → Create → select Group → specify group name → select permissions → Applyacl modify acl_name set unauthenticated permissionsACL → List ACL → click ACL name → Create → select Unauthenticated → select permissions → Applyacl modify acl_name set user user_name permissionsACL → List ACL → click ACL name → Create → select User → specify user name → select permissions → Applyacl show acl_name ACL → List ACL → click ACL nameacl show acl_name attribute attribute_nameACL → List ACL → click ACL name → Extended Attribute tabaction create name description action_typeACL → List Action Groups → click primary action group → Create → complete the form → Createaction create name description action_type action_group_nameACL → List Action Groups → click action group → Create → complete the form → Create action delete nameACL → List Action Groups → click primary action group → select actions → Deleteaction delete name action_group_nameACL → List Action Groups → click action group → select actions → Deleteaction group create action_group_nameACL → Create Action Group → type group name → Createaction group delete action_group_nameACL → List Action Groups → select action groups → Deleteaction group listACL → List Action Groupsaction list ACL → List Action Groups → click primary action groupaction list action_group_nameACL → List Action Groups → click action groupadmin show configurationNot supportedauthzrule attach object_name ruleidAuthzRule → List AuthzRule → click authorization rule name → Attach tab → Attach → type protected object path → Attachauthzrule create ruleid { ruletext} [–desc description] [–failreason failreason]AuthzRule → Create AuthzRule → complete the form → Createauthzrule delete ruleidAuthzRule → List AuthzRule → select authorization rule name → Delete authzrule detach object_nameAuthzRule → List AuthzRule → click authorization rule name → Attach tab → select object names → Detachauthzrule find ruleidAuthzRule → List AuthzRule → click authorization rule name → Attach tabauthzrule listAuthzRule → List AuthzRuleauthzrule modify ruleid { ruletext rule_text | description description | failreason failreasonAuthzRule → List AuthzRule → click authorization rule name → modify fields → Applyauthzrule show ruleidAuthzRule → List AuthzRule → click authorization rule nameconfig modify svrpassword config_file passwordNot supportedconfig modify keyvalue set [–obfuscate] config_file stanza key valueNot supportedconfig modify keyvalue append [–obfuscate] config_file stanza key valueNot supportedconfig modify keyvalue remove config_file stanza key valueNot supportedconfig modify keyvalue remove config_file stanza keyNot supportedconfig show config_file stanza keyNot supportedcontext showNot supporteddomain create domain domain_admin_id domain_admin_password [–desc description]Secure Domain → Create Secure Domain → complete the form → Createdomain delete domain [–registry]Secure Domain → List Secure Domain → select secure domain names → Deletedomain listSecure Domain → List Secure Domain domain modify domain description descriptionSecure Domain → List Secure Domain → click secure domain name → modify description → Applydomain show domainSecure Domain → List Secure Domain → click secure domain nameerrtext error_numberNot supportedexitNot supportedgroup create group_name dn cn [group_container]Group → Create Group → complete the form → Creategroup delete [–registry] group_nameGroup → Search Groups → type pattern and maximum results → Search → select group names → Deletegroup import group_name dn [group_container]Group → Import Group → complete the form → Importgroup list pattern max_returnGroup → Search Groups → type pattern and maximum results → Search group list-dn pattern max_returnNot supported group modify group_name add user group modify group_name add (user_1 user_2 [... user_n])Group → Search Groups → type pattern and maximum results → Search → click group name → Members tab → select users → Addgroup modify group_name description descriptionGroup → Search Groups → type pattern and maximum results → Search → click group name → type description → Apply group modify group_name remove user group modify group_name remove (user_1 user_2 [... user_n])Group → Search Groups → type pattern and maximum results → Search → click group name → Members tab → select user names → Removegroup show group_nameGroup → Search Groups → type pattern and maximum results → Search → click group namegroup show-dn dnNot supportedgroup show-members group_nameGroup → Search Groups → type pattern and maximum results → Search → click group name → Members tabhelp {topic | command}Not supportedlogin –a admin_id –p password [–d domain | –m]Not supportedlogin –lNot supportedlogoutNot supportedobject access object_name permissionsNot supportedobject create object_name description type ispolicyattachable {yes | no}Object Space → Create Object → complete the form → Create The type field is not supported. You can select the Can Policy be attached to this object check box on the Protected Object Properties page.object delete object_nameObject Space → Browse Object Space → expand and click object name → Deleteobject exists object_nameNot supportedobject list Object Space → Browse Object Space → expandobject list object_nameObject Space → Browse Object Space → expand and click object nameobject list object_name attributeObject Space → Browse Object Space → expand and click object name → Extended Attributes tabobject listandshow object_nameNot supportedobject modify object_name delete attribute_nameObject Space → Browse Object Space → expand and click object name → Extended Attributes tab → select attribute → Deleteobject modify object_name delete attribute_name attribute_valueNot supportedobject modify object_name set attribute attribute_name attribute_valueObject Space → Browse Object Space → expand and click object name → Extended Attributes tab → Create → complete the form → Applyobject modify object_name set description descriptionObject Space → Browse Object Space → expand and click object name → modify description → Applyobject modify object_name isPolicyAttachable {yes | no}Object Space → Browse Object Space → expand and click object name → select or clear check box→ Applyobject modify object_name type typeNot supportedobject show object_nameObject Space → Browse Object Space → expand and click object nameobject show object_name attribute attribute_nameObject Space → Browse Object Space → expand and click object name → Extended Attributes tabobjectspace create objectspace_nameObject Space → Create Object Space → complete the form → Createobjectspace delete objectspace_nameObject Space → Browse Object Space → click object space name → Deleteobjectspace listObject Space → Browse Object Spacepolicy get policy_nameUser → Show Global User Policypolicy get policy_name –user user_nameUser → Search Users → type pattern and maximum results → Search → click user name → Policy tabpolicy set policy_name policy_valueUser → Show Global User Policy → modify value → Applypolicy set policy_name policy_value –user user_nameUser → Search Users → type pattern and maximum results → Search → click user name → Policy tab → modify value → Applypop attach object_name pop_namePOP → List POP → click POP name → Attach tab → Attach → type protected object path → Attachpop create pop_namePOP → Create POP → complete the form → Createpop delete pop_name POP → List POP → select POP names → Deletepop detach object_namePOP → List POP → click POP name → Attach tab → select object → Detachpop find pop_namePOP → List POP → click POP name → Attach tabpop listPOP → List POPpop list pop_namePOP → List POP → click POP namepop list pop_name attributePOP → List POP → click POP name → Extended Attributes tabpop modify pop_name delete attribute attribute_namePOP → List POP → click POP name → Extended Attributes tab → select attributes → Deletepop modify pop_name delete attribute attribute_name attribute_valueNot supportedpop modify pop_name set attribute attribute_name attribute_valuePOP → List POP → click POP name → Extended Attributes tab → Create → complete the form → Applypop modify pop_name set audit-level {all | none | audit_level_list}POP → List POP → click POP name → select or clear appropriate check boxes → Applypop modify pop_name set description descriptionPOP → List POP → click POP name → modify description → Applypop modify pop_name set ipauth add network netmask authentication_levelPOP → List POP → click POP name → IP Auth tab → Create → type the network, net mask, and authentication level → Applypop modify pop_name set ipauth add network netmask forbiddenPOP → List POP → click POP name → IP Auth tab → Create → type network and net mask and select Forbidden check box → Applypop modify pop_name set ipauth anyothernw authentication_levelPOP → List POP → click POP name → IP Auth tab → Create → select Any Other Network check box and type authentication level → Createpop modify pop_name set ipauth anyothernw forbiddenPOP → List POP → click POP name → IP Auth tab → Create → select Any Other Network and Forbidden check boxes → Createpop modify pop_name set ipauth remove network netmaskPOP → List POP → click POP name → IP Auth tab → select IP authorization entries → Deletepop modify pop_name set qop {none | integrity | privacy}POP → List POP → click POP name → select appropriate quality of protection → Applypop modify pop_name set tod-access {anyday | weekday | day_list}:{anytime | time_spec-time_spec}[:utc | local]POP → List POP → click POP name → define time of day access → Applypop modify pop_name set warning {yes | no}POP → List POP → click POP name → select or clear Warn Only On Policy Violation check box → Applypop show pop_namePOP → List POP → click POP namepop show pop_name attributePOP → List POP → click POP name → Extended Attributes tabquitNot supportedrsrc create resource_name [–desc description]GSO Resource → Create GSO → complete the form → Creatersrc delete resource_nameGSO Resource → List GSO → select resources → Deletersrc listGSO Resource → List GSOrsrc show resource_nameGSO Resource → List GSO → click resourcersrccred create resource_name rsrcuser resource_userid rsrcpwd resource_pwd rsrctype {web | group} user user_nameUser → Search Users → Search → click user name → GSO Credentials tab → Create → complete the form → Creatersrccred create resource_group_name rsrcuser resource_userid rsrcpwd resource_pwd rsrctype {web | group} user user_nameUser → Search Groups → Search → click user name → GSO Credentials tab → Create → complete the form → Creatersrccred delete resource_name rsrctype {web | group} user user_nameUser → Search Users → Search → click user name → GSO Credentials tab → select credentials → Deletersrccred delete resource_group_name rsrctype {web | group} user user_nameUser → Search Groups → Search → click user name → GSO Credentials tab → select credentials → Deletersrccred list user user_nameUser → Search Users → Search → click user name → GSO Credentials tabrsrccred modify resource_name rsrctype {web | group} [–rsrcuser resource_userid] [–rsrcpwd resource_pwd] user user_nameUser → Search Users → Search → click user name → GSO Credentials tab → Create → modify form → Creatersrccred modify resource_group_name rsrctype {web | group} [–rsrcuser resource_userid] [–rsrcpwd resource_pwd] user user_nameUser → Search Groups → Search → click user name → GSO Credentials tab → Create → modify form → Creatersrccred show resource_name rsrctype {web | group} user user_nameUser → Search Users → Search → click user name → GSO Credentials tabrsrccred show resource_group_name rsrctype {web | group} user user_nameUser → Search Groups → Search → click user name → GSO Credentials tabrsrcgroup create resource_group_name [–desc description]GSO Resource → Create GSO Group → complete the form → Creatersrcgroup delete resource_group_nameGSO Resource → List GSO Groups → select resource groups → Deletersrcgroup listGSO Resource → List GSO Groupsrsrcgroup modify resource_group_name add rsrcname resource_nameGSO Resource → List GSO Groups → select resource group → select members → Addrsrcgroup modify resource_group_name remove rsrcname resource_nameGSO Resource → List GSO Groups → select resource group → select members → Removersrcgroup show resource_group_nameGSO Resource → List GSO Groups → select resource groupserver listNot supportedserver listtasks server_nameNot supportedserver replicate server_nameNot supportedserver show server_name Not supportedserver task server_name {help | stats | trace}Not supportedserver task server_name server_taskNot supported For more information about the WebSEAL server tasks and junction points, see the IBM Security Access Manager for Web: WebSEAL Administration Guide.user create [–gsouser] [–no-password-policy] user_name dn cn sn password [group1 [group2 ...]]User → Create User → complete the form → Createuser delete [–registry] user_nameUser → Search Users → type pattern and maximum results → Search → select user names → Deleteuser import [–gsouser] user_name dn [group_name]User → Import User → complete the form → Importuser list pattern max_returnUser → Search Users → type pattern and maximum results → Searchuser list-dn pattern max_returnNot supporteduser modify user_name account-valid {yes | no}User → Search Users → type pattern and maximum results → Search → click user name → select or clear check box → Applyuser modify user_name password passwordUser → Search Users → type pattern and maximum results → Search → click user name → modify password→ Applyuser modify user_name password-valid {yes | no}User → Search Users → type pattern and maximum results → Search → click user name → select or clear check box → Applyuser show user_nameUser → Search Users → type pattern and maximum results → Search → click user nameuser show-dn dnNot supporteduser show-groups user_nameUser → Search Users → type pattern and maximum results → Search → click user name → Groups tabAccess Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy.

pdadmin to Web Portal Manager equivalents

This appendix shows the mapping of the administration pdadmin commands to Web Portal Manager.

Information about the pdadmin utility can be found in the IBM Security Access Manager for Web: Command Reference.

Table 183. Mapping between the pddamin utility and Web Portal Manager

pdadmin utility
Web Portal Manager

acl attach object_name acl_name
ACL → List ACL → click ACL name → Attach tab → Attach → type protected object path → Attach

acl create acl_name
ACL → Create ACL → complete the form → Create

acl delete acl_name
ACL → List ACL → select ACL names → Delete

acl detach object_name
ACL → List ACL → click ACL name → Attach tab → select protected object → Detach

acl find acl_name
ACL → List ACL → click ACL name → Attach tab

acl list
ACL → List ACL

acl list acl_name attribute
ACL → List ACL → click ACL name → Extended Attribute tab

acl modify acl_name delete attribute attribute_name
ACL → List ACL → select ACL name → Extended Attribute tab → select attributes → Delete

acl modify acl_name delete attribute attribute_name attribute_value
Not supported

acl modify acl_name description description
ACL → List ACL → click ACL name → modify description → Set

acl modify acl_name remove any-other
ACL → List ACL → click ACL name → select Any-other → Delete

acl modify acl_name remove group group_name
ACL → List ACL → click ACL name → select group name → Delete

acl modify acl_name remove unauthenticated
ACL → List ACL → click ACL name → select Unauthenticated → Delete

acl modify acl_name remove user user_name
ACL → List ACL → click ACL name → select user name → Delete

acl modify acl_name set any-other permissions
ACL → List ACL → click ACL name → select Any-other → Create → select permissions → Apply

acl modify acl_name set attribute attribute_name attribute_value
ACL → List ACL → click ACL name → Extended Attribute tab → Create → complete the form → Apply

acl modify acl_name set group group_name permissions
ACL → List ACL → click ACL name → Create → select Group → specify group name → select permissions → Apply

acl modify acl_name set unauthenticated permissions
ACL → List ACL → click ACL name → Create → select Unauthenticated → select permissions → Apply

acl modify acl_name set user user_name permissions
ACL → List ACL → click ACL name → Create → select User → specify user name → select permissions → Apply

acl show acl_name
ACL → List ACL → click ACL name

acl show acl_name attribute attribute_name
ACL → List ACL → click ACL name → Extended Attribute tab

action create name description action_type
ACL → List Action Groups → click primary action group → Create → complete the form → Create

action create name description action_type action_group_name
ACL → List Action Groups → click action group → Create → complete the form → Create

action delete name
ACL → List Action Groups → click primary action group → select actions → Delete

action delete name action_group_name
ACL → List Action Groups → click action group → select actions → Delete

action group create action_group_name
ACL → Create Action Group → type group name → Create

action group delete action_group_name
ACL → List Action Groups → select action groups → Delete

action group list
ACL → List Action Groups

action list
ACL → List Action Groups → click primary action group

action list action_group_name
ACL → List Action Groups → click action group

admin show configuration
Not supported

authzrule attach object_name ruleid
AuthzRule → List AuthzRule → click authorization rule name → Attach tab → Attach → type protected object path → Attach

authzrule create ruleid { ruletext} [–desc description] [–failreason failreason]
AuthzRule → Create AuthzRule → complete the form → Create

authzrule delete ruleid
AuthzRule → List AuthzRule → select authorization rule name → Delete

authzrule detach object_name
AuthzRule → List AuthzRule → click authorization rule name → Attach tab → select object names → Detach

authzrule find ruleid
AuthzRule → List AuthzRule → click authorization rule name → Attach tab

authzrule list
AuthzRule → List AuthzRule

authzrule modify ruleid { ruletext rule_text | description description | failreason failreason
AuthzRule → List AuthzRule → click authorization rule name → modify fields → Apply

authzrule show ruleid
AuthzRule → List AuthzRule → click authorization rule name

config modify svrpassword config_file password
Not supported

config modify keyvalue set [–obfuscate] config_file stanza key value
Not supported

config modify keyvalue append [–obfuscate] config_file stanza key value
Not supported

config modify keyvalue remove config_file stanza key value
Not supported

config modify keyvalue remove config_file stanza key
Not supported

config show config_file stanza key
Not supported

context show
Not supported

domain create domain domain_admin_id domain_admin_password [–desc description]
Secure Domain → Create Secure Domain → complete the form → Create

domain delete domain [–registry]
Secure Domain → List Secure Domain → select secure domain names → Delete

domain list
Secure Domain → List Secure Domain

domain modify domain description description
Secure Domain → List Secure Domain → click secure domain name → modify description → Apply

domain show domain
Secure Domain → List Secure Domain → click secure domain name

errtext error_number
Not supported

exit
Not supported

group create group_name dn cn [group_container]
Group → Create Group → complete the form → Create

group delete [–registry] group_name
Group → Search Groups → type pattern and maximum results → Search → select group names → Delete

group import group_name dn [group_container]
Group → Import Group → complete the form → Import

group list pattern max_return
Group → Search Groups → type pattern and maximum results → Search

group list-dn pattern max_return
Not supported

group modify group_name add user

group modify group_name add (user_1 user_2 [... user_n])

Group → Search Groups → type pattern and maximum results → Search → click group name → Members tab → select users → Add

group modify group_name description description
Group → Search Groups → type pattern and maximum results → Search → click group name → type description → Apply

group modify group_name remove user

group modify group_name remove (user_1 user_2 [... user_n])

Group → Search Groups → type pattern and maximum results → Search → click group name → Members tab → select user names → Remove

group show group_name
Group → Search Groups → type pattern and maximum results → Search → click group name

group show-dn dn
Not supported

group show-members group_name
Group → Search Groups → type pattern and maximum results → Search → click group name → Members tab

help {topic | command}
Not supported

login –a admin_id –p password [–d domain | –m]
Not supported

login –l
Not supported

logout
Not supported

object access object_name permissions
Not supported

object create object_name description type ispolicyattachable {yes | no}
Object Space → Create Object → complete the form → Create

The type field is not supported.

You can select the Can Policy be attached to this object check box on the Protected Object Properties page.

object delete object_name
Object Space → Browse Object Space → expand and click object name → Delete

object exists object_name
Not supported

object list
Object Space → Browse Object Space → expand

object list object_name
Object Space → Browse Object Space → expand and click object name

object list object_name attribute
Object Space → Browse Object Space → expand and click object name → Extended Attributes tab

object listandshow object_name
Not supported

object modify object_name delete attribute_name
Object Space → Browse Object Space → expand and click object name → Extended Attributes tab → select attribute → Delete

object modify object_name delete attribute_name attribute_value
Not supported

object modify object_name set attribute attribute_name attribute_value
Object Space → Browse Object Space → expand and click object name → Extended Attributes tab → Create → complete the form → Apply

object modify object_name set description description
Object Space → Browse Object Space → expand and click object name → modify description → Apply

object modify object_name isPolicyAttachable {yes | no}
Object Space → Browse Object Space → expand and click object name → select or clear check box→ Apply

object modify object_name type type
Not supported

object show object_name
Object Space → Browse Object Space → expand and click object name

object show object_name attribute attribute_name
Object Space → Browse Object Space → expand and click object name → Extended Attributes tab

objectspace create objectspace_name
Object Space → Create Object Space → complete the form → Create

objectspace delete objectspace_name
Object Space → Browse Object Space → click object space name → Delete

objectspace list
Object Space → Browse Object Space

policy get policy_name
User → Show Global User Policy

policy get policy_name –user user_name
User → Search Users → type pattern and maximum results → Search → click user name → Policy tab

policy set policy_name policy_value
User → Show Global User Policy → modify value → Apply

policy set policy_name policy_value –user user_name
User → Search Users → type pattern and maximum results → Search → click user name → Policy tab → modify value → Apply

pop attach object_name pop_name
POP → List POP → click POP name → Attach tab → Attach → type protected object path → Attach

pop create pop_name
POP → Create POP → complete the form → Create

pop delete pop_name

POP → List POP → select POP names → Delete

pop detach object_name
POP → List POP → click POP name → Attach tab → select object → Detach

pop find pop_name
POP → List POP → click POP name → Attach tab

pop list
POP → List POP

pop list pop_name
POP → List POP → click POP name

pop list pop_name attribute
POP → List POP → click POP name → Extended Attributes tab

pop modify pop_name delete attribute attribute_name
POP → List POP → click POP name → Extended Attributes tab → select attributes → Delete

pop modify pop_name delete attribute attribute_name attribute_value
Not supported

pop modify pop_name set attribute attribute_name attribute_value
POP → List POP → click POP name → Extended Attributes tab → Create → complete the form → Apply

pop modify pop_name set audit-level {all | none | audit_level_list}
POP → List POP → click POP name → select or clear appropriate check boxes → Apply

pop modify pop_name set description description
POP → List POP → click POP name → modify description → Apply

pop modify pop_name set ipauth add network netmask authentication_level
POP → List POP → click POP name → IP Auth tab → Create → type the network, net mask, and authentication level → Apply

pop modify pop_name set ipauth add network netmask forbidden
POP → List POP → click POP name → IP Auth tab → Create → type network and net mask and select Forbidden check box → Apply

pop modify pop_name set ipauth anyothernw authentication_level
POP → List POP → click POP name → IP Auth tab → Create → select Any Other Network check box and type authentication level → Create

pop modify pop_name set ipauth anyothernw forbidden
POP → List POP → click POP name → IP Auth tab → Create → select Any Other Network and Forbidden check boxes → Create

pop modify pop_name set ipauth remove network netmask
POP → List POP → click POP name → IP Auth tab → select IP authorization entries → Delete

pop modify pop_name set qop {none | integrity | privacy}
POP → List POP → click POP name → select appropriate quality of protection → Apply

pop modify pop_name set tod-access {anyday | weekday | day_list}:{anytime | time_spec-time_spec}[:utc | local]
POP → List POP → click POP name → define time of day access → Apply

pop modify pop_name set warning {yes | no}
POP → List POP → click POP name → select or clear Warn Only On Policy Violation check box → Apply

pop show pop_name
POP → List POP → click POP name

pop show pop_name attribute
POP → List POP → click POP name → Extended Attributes tab

quit
Not supported

rsrc create resource_name [–desc description]
GSO Resource → Create GSO → complete the form → Create

rsrc delete resource_name
GSO Resource → List GSO → select resources → Delete

rsrc list
GSO Resource → List GSO

rsrc show resource_name
GSO Resource → List GSO → click resource

rsrccred create resource_name rsrcuser resource_userid rsrcpwd resource_pwd rsrctype {web | group} user user_name
User → Search Users → Search → click user name → GSO Credentials tab → Create → complete the form → Create

rsrccred create resource_group_name rsrcuser resource_userid rsrcpwd resource_pwd rsrctype {web | group} user user_name
User → Search Groups → Search → click user name → GSO Credentials tab → Create → complete the form → Create

rsrccred delete resource_name rsrctype {web | group} user user_name
User → Search Users → Search → click user name → GSO Credentials tab → select credentials → Delete

rsrccred delete resource_group_name rsrctype {web | group} user user_name
User → Search Groups → Search → click user name → GSO Credentials tab → select credentials → Delete

rsrccred list user user_name
User → Search Users → Search → click user name → GSO Credentials tab

rsrccred modify resource_name rsrctype {web | group} [–rsrcuser resource_userid] [–rsrcpwd resource_pwd] user user_name
User → Search Users → Search → click user name → GSO Credentials tab → Create → modify form → Create

rsrccred modify resource_group_name rsrctype {web | group} [–rsrcuser resource_userid] [–rsrcpwd resource_pwd] user user_name
User → Search Groups → Search → click user name → GSO Credentials tab → Create → modify form → Create

rsrccred show resource_name rsrctype {web | group} user user_name
User → Search Users → Search → click user name → GSO Credentials tab

rsrccred show resource_group_name rsrctype {web | group} user user_name
User → Search Groups → Search → click user name → GSO Credentials tab

rsrcgroup create resource_group_name [–desc description]
GSO Resource → Create GSO Group → complete the form → Create

rsrcgroup delete resource_group_name
GSO Resource → List GSO Groups → select resource groups → Delete

rsrcgroup list
GSO Resource → List GSO Groups

rsrcgroup modify resource_group_name add rsrcname resource_name
GSO Resource → List GSO Groups → select resource group → select members → Add

rsrcgroup modify resource_group_name remove rsrcname resource_name
GSO Resource → List GSO Groups → select resource group → select members → Remove

rsrcgroup show resource_group_name
GSO Resource → List GSO Groups → select resource group

server list
Not supported

server listtasks server_name
Not supported

server replicate server_name
Not supported

server show server_name
Not supported

server task server_name {help | stats | trace}
Not supported

server task server_name server_task
Not supported

For more information about the WebSEAL server tasks and junction points, see the IBM Security Access Manager for Web: WebSEAL Administration Guide.

user create [–gsouser] [–no-password-policy] user_name dn cn sn password [group1 [group2 ...]]
User → Create User → complete the form → Create

user delete [–registry] user_name
User → Search Users → type pattern and maximum results → Search → select user names → Delete

user import [–gsouser] user_name dn [group_name]
User → Import User → complete the form → Import

user list pattern max_return
User → Search Users → type pattern and maximum results → Search

user list-dn pattern max_return
Not supported

user modify user_name account-valid {yes | no}
User → Search Users → type pattern and maximum results → Search → click user name → select or clear check box → Apply

user modify user_name password password
User → Search Users → type pattern and maximum results → Search → click user name → modify password→ Apply

user modify user_name password-valid {yes | no}
User → Search Users → type pattern and maximum results → Search → click user name → select or clear check box → Apply

user show user_name
User → Search Users → type pattern and maximum results → Search → click user name

user show-dn dn
Not supported

user show-groups user_name
User → Search Users → type pattern and maximum results → Search → click user name → Groups tab

Parent topic: Access Manager Platform and Supporting Components administration

Managing user registriesThis appendix contains a subset of user registry tasks that are specific to installing Security Access Manager.userregistriesmanagingYou might need more information about common administrative tasks for your particular registry (tasks that are not specific to Security Access Manager). See the documentation that came with your user registry product.Access Manager Platform and Supporting Components administrationThe Security Access Manager Platform and Supporting Components are available with the Security Access Manager Platform activation level. The topics in this hierarchy describe how to manage the Security Access Manager servers and resources that support WebSEAL and the Web Reverse Proxy. LDAP-specific tasksLDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.Novell-specific tasksThe Novell eDirectory can be configured as a Security Access Manager user registry.

Managing user registries

This appendix contains a subset of user registry tasks that are specific to installing Security Access Manager.

You might need more information about common administrative tasks for your particular registry (tasks that are not specific to Security Access Manager). See the documentation that came with your user registry product.

LDAP-specific tasks
LDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.

Novell-specific tasks
The Novell eDirectory can be configured as a Security Access Manager user registry.

Parent topic: Access Manager Platform and Supporting Components administration

LDAP-specific tasksLDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.userregistriesmanaging LDAPA directory that is accessible through LDAP is commonly termed an LDAP directory. An example of an LDAP server product is the Security Directory Server, which is included with Security Access Manager.This section contains the following topics: Managing user registriesThis appendix contains a subset of user registry tasks that are specific to installing Security Access Manager.LDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.Valid characters for LDAP user and group namesYou might use LDAP as the user registry. The set of valid characters allowed within a user or group name is determined by several Internet Engineering Task Force (IETF) Request for Comments (RFC).Applying Security Access Manager ACLs to new LDAP suffixesThe LDAP naming model is maintained in a hierarchical namespace known as the Directory Information Tree (DIT).Setting the password history policyIf Security Directory Server is your user registry, you can use its password history policy.

LDAP-specific tasks

LDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.

A directory that is accessible through LDAP is commonly termed an LDAP directory. An example of an LDAP server product is the Security Directory Server, which is included with Security Access Manager.

This section contains the following topics:

LDAP failover configuration
LDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

Valid characters for LDAP user and group names
You might use LDAP as the user registry. The set of valid characters allowed within a user or group name is determined by several Internet Engineering Task Force (IETF) Request for Comments (RFC).

Applying Security Access Manager ACLs to new LDAP suffixes
The LDAP naming model is maintained in a hierarchical namespace known as the Directory Information Tree (DIT).

Setting the password history policy
If Security Directory Server is your user registry, you can use its password history policy.

Parent topic: Managing user registries

LDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.iPlanetfailoverconfigurationreplicationLDAPfailoverconfigurationDirectories are accessed with the client/server model of communication. Any server that implements LDAP is an LDAP server. The LDAP distributed architecture supports scalable directory services with server replication capabilities. Server replication improves the availability of a directory service.Security Directory Server replication is based on a master-subordinate model. Sun Java System Directory Server replication is based on a supplier/consumer model, which Security Access Manager still treats as a master-subordinate or peer-to-peer relationship.Active Directory Lightweight Directory Service (AD LDS) replication is based on membership in a configuration set, which is a group of AD LDS instances that share and replicate a common configuration partition and schema partition. AD LDS uses a multi-master form of replication, which means that any instance in the configuration set is writable and propagates the changes to all other instances in the configuration set. AD LDS instances cannot replicate with Active Directory. They replicate on a schedule that is independent of the Active Directory replication schedule, even when AD LDS is running in an Active Directory domain.Security Access Manager treats each AD LDS instance in a configuration set as a replica. The Access Manager directory partition that contains the secAuthorityInfo subtree must be replicated to each of the AD LDS instances in the configuration set. The default replication schedule for AD LDS is one time per hour. This schedule can be changed, but the most frequent rate at which AD LDS replicates is four times an hour. Updates to one instance in a configuration set are not propagated for at least 15 minutes. Therefore, when Security Access Manager is used with AD LDS, configure one instance in the configuration set to have a higher read/write preference than all other instances. This way, updates are directed to the AD LDS instance with the highest preference. No other instances are used as failover unless the preferred instance is down. For information about setting the AD LDS replication schedule, see the IBM Security Access Manager for Web: Installation Guide. To set preference values, see Preference values for replica LDAP serversEach replica LDAP server must have a preference value (1 to 10) that determines its priority.. For SSL, ensure that the same certificate authority issues the AD LDS certificate for each instance in the configuration set. This way, Security Access Manager can validate the AD LDS certificate from each instance. If the AD LDS instances in the configuration set are on the same system, the instances can share the certificate.For a generic LDAP server, the failover configuration depends on the specific LDAP server. The LDAP server recognizes the concept of master-subordinate, and Security Access Manager can use this replication support. For information about whether your LDAP server supports replication in this manner, see the documentation for your LDAP server.The combination of a master server and multiple replicated servers helps to ensure that directory data is always available when needed. If any server fails, the directory service continues to be available from another replicated server. Security Access Manager supports this replication capability.LDAP-specific tasksLDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.The master-subordinate replication modelReplication involves two types of directories: master/peer and replica.Security Access Manager failover capability for LDAP serversWhen it starts, Security Access Manager connects to the LDAP master server indicated by the host key in the ldap.conf configuration file.Master server configurationSecurity Directory Server supports a single read/write master LDAP server or multiple peer-to-peer read/write servers.Replica server configurationSecurity Directory Server supports one or more read-only replica LDAP servers.Preference values for replica LDAP serversEach replica LDAP server must have a preference value (1 to 10) that determines its priority.Server pollingIf an LDAP server does fail, Security Access Manager continuously polls the server to check for its return to active duty. The poll time is 10 seconds.

LDAP failover configuration

LDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

Directories are accessed with the client/server model of communication. Any server that implements LDAP is an LDAP server. The LDAP distributed architecture supports scalable directory services with server replication capabilities. Server replication improves the availability of a directory service.

Security Directory Server replication is based on a master-subordinate model. Sun Java™ System Directory Server replication is based on a supplier/consumer model, which Security Access Manager still treats as a master-subordinate or peer-to-peer relationship.

Active Directory Lightweight Directory Service (AD LDS) replication is based on membership in a configuration set, which is a group of AD LDS instances that share and replicate a common configuration partition and schema partition. AD LDS uses a multi-master form of replication, which means that any instance in the configuration set is writable and propagates the changes to all other instances in the configuration set.

Note: AD LDS instances cannot replicate with Active Directory. They replicate on a schedule that is independent of the Active Directory replication schedule, even when AD LDS is running in an Active Directory domain.

Security Access Manager treats each AD LDS instance in a configuration set as a replica. The Access Manager directory partition that contains the secAuthorityInfo subtree must be replicated to each of the AD LDS instances in the configuration set. The default replication schedule for AD LDS is one time per hour. This schedule can be changed, but the most frequent rate at which AD LDS replicates is four times an hour. Updates to one instance in a configuration set are not propagated for at least 15 minutes. Therefore, when Security Access Manager is used with AD LDS, configure one instance in the configuration set to have a higher read/write preference than all other instances. This way, updates are directed to the AD LDS instance with the highest preference. No other instances are used as failover unless the preferred instance is down.

For information about setting the AD LDS replication schedule, see the IBM Security Access Manager for Web: Installation Guide. To set preference values, see Preference values for replica LDAP servers.

Note: For SSL, ensure that the same certificate authority issues the AD LDS certificate for each instance in the configuration set. This way, Security Access Manager can validate the AD LDS certificate from each instance. If the AD LDS instances in the configuration set are on the same system, the instances can share the certificate.

For a generic LDAP server, the failover configuration depends on the specific LDAP server. The LDAP server recognizes the concept of master-subordinate, and Security Access Manager can use this replication support. For information about whether your LDAP server supports replication in this manner, see the documentation for your LDAP server.

The combination of a master server and multiple replicated servers helps to ensure that directory data is always available when needed. If any server fails, the directory service continues to be available from another replicated server. Security Access Manager supports this replication capability.

The master-subordinate replication model
Replication involves two types of directories: master/peer and replica.

Security Access Manager failover capability for LDAP servers
When it starts, Security Access Manager connects to the LDAP master server indicated by the host key in the ldap.conf configuration file.

Master server configuration
Security Directory Server supports a single read/write master LDAP server or multiple peer-to-peer read/write servers.

Replica server configuration
Security Directory Server supports one or more read-only replica LDAP servers.

Preference values for replica LDAP servers
Each replica LDAP server must have a preference value (1 to 10) that determines its priority.

Server polling
If an LDAP server does fail, Security Access Manager continuously polls the server to check for its return to active duty. The poll time is 10 seconds.

Parent topic: LDAP-specific tasks

The master-subordinate replication modelReplication involves two types of directories: master/peer and replica.LDAPreplication modelLDAP refers to the master as the master server and to the replica as the replica server. Even when peer-to-peer replication is being used, the peer servers can be considered masters for the Security Access Manager perspective. All updates are made on the master server and these updates are later propagated to the replica servers. Each replica server directory contains a copy of the data in the master server directory.Changes to the directory can be made only to a master server, which is always used for write operations to the directory. For Security Access Manager, these types of servers are configured as readwrite servers. Either the master or the replicas can be used for read operations. When the original master server is out of service for an extended period, a replica server can be promoted as a master server. The change enables write operations to the directory.LDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

The master-subordinate replication model

Replication involves two types of directories: master/peer and replica.

LDAP refers to the master as the master server and to the replica as the replica server. Even when peer-to-peer replication is being used, the peer servers can be considered "masters" for the Security Access Manager perspective. All updates are made on the master server and these updates are later propagated to the replica servers. Each replica server directory contains a copy of the data in the master server directory.

Changes to the directory can be made only to a master server, which is always used for write operations to the directory. For Security Access Manager, these types of servers are configured as readwrite servers. Either the master or the replicas can be used for read operations. When the original master server is out of service for an extended period, a replica server can be promoted as a master server. The change enables write operations to the directory.

Parent topic: LDAP failover configuration

Security Access Manager failover capability for LDAP serversSecurity Access Manager failover capability for LDAP serversWhen it starts, Security Access Manager connects to the LDAP master server indicated by the host key in the ldap.conf configuration file.failover configurationcapabilityLDAPfailovercapabilityIf the LDAP master server is down for any reason, the Security Access Manager server must be able to connect to an available LDAP replica server for any read operations. For Security Access Manager, these types of servers are configured as readonly servers.Many operations, especially those from regular users, are read operations. These include operations such as user authentication and sign-on to back-end junctioned web servers. After configuration, Security Access Manager fails over to a replica server when it cannot connect to the master server.You can find the configuration parameters for LDAP failover in the [ldap] stanza of the ldap.conf configuration file. This configuration file is in one of the following operating system-specific locations: On AIX, Linux, and Solaris operating systems/opt/PolicyDirector/etc/ldap.confOn Windows operating systemsinstall_path\etc\ldap.confLDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

Security Access Manager failover capability for LDAP servers

When it starts, Security Access Manager connects to the LDAP master server indicated by the host key in the ldap.conf configuration file.

If the LDAP master server is down for any reason, the Security Access Manager server must be able to connect to an available LDAP replica server for any read operations. For Security Access Manager, these types of servers are configured as readonly servers.

Many operations, especially those from regular users, are read operations. These include operations such as user authentication and sign-on to back-end junctioned web servers. After configuration, Security Access Manager fails over to a replica server when it cannot connect to the master server.

You can find the configuration parameters for LDAP failover in the [ldap] stanza of the ldap.conf configuration file. This configuration file is in one of the following operating system-specific locations:

On AIX, Linux, and Solaris operating systems

/opt/PolicyDirector/etc/ldap.conf

On Windows operating systems

install_path\etc\ldap.conf

Parent topic: LDAP failover configuration

Master server configurationSecurity Directory Server supports a single read/write master LDAP server or multiple peer-to-peer read/write servers.ldap.conf configuration fileLDAPmaster serverSun Java System Directory Server supports multiple read/write LDAP servers. Security Access Manager treats the Sun Java System supplier server as the master server for configuration purposes.The active configuration lines in the ldap.conf file represent the parameters and values for this master LDAP server. You determine these values during Security Access Manager configuration. For example: [ldap] enabled = yes host = outback port = 389 ssl-port = 636 max-search-size = 2048Master server configuration entities and valuesEntityDescriptionenabledSecurity Access Manager uses an LDAP user registry. Values are yes and no.hostThe network name of the computer where the LDAP master server is located. This server is assumed to be a readwrite server with a preference of 5.portThe TCP listening port of the LDAP master server.ssl-portThe SSL listening port of the LDAP master server.max-search-sizeThe Security Access Manager limit for an LDAP client search of database items. For example, a request for the Web Portal Manager to list users from the LDAP database might reach this limit.You might change the LDAP database. For example, when you add a user account through the Web Portal Manager, Security Access Manager uses the read/write (master) LDAP server.LDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

Master server configuration

Security Directory Server supports a single read/write master LDAP server or multiple peer-to-peer read/write servers.

Sun Java™ System Directory Server supports multiple read/write LDAP servers. Security Access Manager treats the Sun Java System supplier server as the master server for configuration purposes.

The active configuration lines in the ldap.conf file represent the parameters and values for this master LDAP server. You determine these values during Security Access Manager configuration. For example:

[ldap]
enabled = yes
host = outback
port = 389
ssl-port = 636
max-search-size = 2048

Table 184. Master server configuration entities and values

Entity
Description

enabled
Security Access Manager uses an LDAP user registry. Values are yes and no.

host
The network name of the computer where the LDAP master server is located. This server is assumed to be a readwrite server with a preference of 5.

port
The TCP listening port of the LDAP master server.

ssl-port
The SSL listening port of the LDAP master server.

max-search-size
The Security Access Manager limit for an LDAP client search of database items.

For example, a request for the Web Portal Manager to list users from the LDAP database might reach this limit.

You might change the LDAP database. For example, when you add a user account through the Web Portal Manager, Security Access Manager uses the read/write (master) LDAP server.

Parent topic: LDAP failover configuration

Replica server configurationSecurity Directory Server supports one or more read-only replica LDAP servers.LDAPreplica serverSun Java System Directory Server supports the existence of one or more read-only replica LDAP servers that are termed consumers. replicaYou must add lines to the [ldap] stanza that identifies any replica servers available to Security Access Manager. Use the following syntax for each replica: replica = ldap_server,port,type,preferenceReplica server configuration entities and valuesEntityDescriptionldap-serverThe network name of the LDAP replica server.portThe port this server listens on. Generally, use 389 or 636.typeThe functionality of the replica server, which is either readonly or readwrite. Normally, use read-only. A read/write type would represent a master server.preferenceA number from 1 to 10. The server with the highest preference value is chosen for LDAP connections. See Preference values for replica LDAP serversEach replica LDAP server must have a preference value (1 to 10) that determines its priority..Example: replica = replica1.ldap.tivoli.com,389,readonly,4 replica = replica2.ldap.tivoli.com,389,readonly,4Changes to the ldap.conf file do not take effect until you restart Security Access Manager.LDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

Replica server configuration

Security Directory Server supports one or more read-only replica LDAP servers.

Sun Java™ System Directory Server supports the existence of one or more read-only replica LDAP servers that are termed consumers.

You must add lines to the [ldap] stanza that identifies any replica servers available to Security Access Manager. Use the following syntax for each replica:

replica = ldap_server,port,type,preference

Table 185. Replica server configuration entities and values

Entity | Description
ldap-server | The network name of the LDAP replica server.
port | The port this server listens on. Generally, use 389 or 636.
type | The functionality of the replica server, which is either readonly or readwrite. Normally, use read-only. A read/write type would represent a master server.
preference | A number from 1 to 10. The server with the highest preference value is chosen for LDAP connections. See Preference values for replica LDAP servers.

Example:

replica = replica1.ldap.tivoli.com,389,readonly,4
replica = replica2.ldap.tivoli.com,389,readonly,4

Changes to the ldap.conf file do not take effect until you restart Security Access Manager.

Parent topic: LDAP failover configuration

Preference values for replica LDAP serversEach replica LDAP server must have a preference value (1 to 10) that determines its priority.preference values (LDAP failover)LDAPfailoverpreference valuesPriority is based on one of the following selections:The primary read-only access serverA backup read-only server during a failoverThe higher the number, the higher the priority. If the primary read-only server fails for any reason, the server with the next highest preference value is used. If two or more servers have the same preference value, a least-busy load balancing algorithm determines which one is selected.Remember that the master LDAP server can function as both a read-only and a read/write server. For read-only access, the master server has a hardcoded default preference setting of 5. Use this preference setting to set replica servers at values higher or lower than the master to obtain the required performance. For example, with appropriate preference settings, you can prevent the master server from handling everyday read operations.You can set hierarchical preference values to allow access to a single LDAP server with failover to the other servers. You can also set equal preferences for all servers and allow load balancing to dictate server selection.Table 1 illustrates some possible preference scenarios. M is a reference to the master (read-only/read-write) LDAP server; R1, R2 and R3 are references to the replica (read-only) LDAP servers. Potential preference scenariosMR1R2R3Failover preference5555All servers have the same preference values. Load balancing determines which server is selected for each access operation.5666The 3 replica servers have the same preference value. This value is higher than the master server value. Load balancing determines server selection among the 3 replicas. The master is used only if all 3 replica servers become unavailable.5678Server 3 (with the highest preference value) becomes the primary server. If server 3 fails, server 2 becomes the primary server because it has the next highest preference value.Preference values affect only read-only access to the LDAP database. Security Access Manager always uses the master (read/write) server when you need to change the LDAP database.Some Security Access Manager daemons such as the policy server override the preference settings in their configuration files to indicate that the read/write server is preferred. This override occurs because those daemons usually make update operations that go to the master LDAP server.LDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

Preference values for replica LDAP servers

Each replica LDAP server must have a preference value (1 to 10) that determines its priority.

Priority is based on one of the following selections:

The primary read-only access server

A backup read-only server during a failover

The higher the number, the higher the priority. If the primary read-only server fails for any reason, the server with the next highest preference value is used. If two or more servers have the same preference value, a least-busy load balancing algorithm determines which one is selected.

Remember that the master LDAP server can function as both a read-only and a read/write server. For read-only access, the master server has a hardcoded default preference setting of 5. Use this preference setting to set replica servers at values higher or lower than the master to obtain the required performance. For example, with appropriate preference settings, you can prevent the master server from handling everyday read operations.

You can set hierarchical preference values to allow access to a single LDAP server with failover to the other servers. You can also set equal preferences for all servers and allow load balancing to dictate server selection.

Table 186 illustrates some possible preference scenarios. "M" is a reference to the master (read-only/read-write) LDAP server; "R1", "R2" and "R3" are references to the replica (read-only) LDAP servers.

Table 186. Potential preference scenarios

M | R1 | R2 | R3 | Failover preference
5 | 5 | 5 | 5 | All servers have the same preference values. Load balancing determines which server is selected for each access operation.
5 | 6 | 6 | 6 | The 3 replica servers have the same preference value. This value is higher than the master server value. Load balancing determines server selection among the 3 replicas. The master is used only if all 3 replica servers become unavailable.
5 | 6 | 7 | 8 | Server 3 (with the highest preference value) becomes the primary server. If server 3 fails, server 2 becomes the primary server because it has the next highest preference value.

Preference values affect only read-only access to the LDAP database. Security Access Manager always uses the master (read/write) server when you need to change the LDAP database.

Some Security Access Manager daemons such as the policy server override the preference settings in their configuration files to indicate that the read/write server is preferred. This override occurs because those daemons usually make update operations that go to the master LDAP server.

Parent topic: LDAP failover configuration

Server pollingIf an LDAP server does fail, Security Access Manager continuously polls the server to check for its return to active duty. The poll time is 10 seconds.LDAPpollingLDAP failover configurationLDAP failover configuration makes use of the Lightweight Directory Access Protocol (LDAP) standard method for accessing and updating information in a directory.

Server polling

If an LDAP server does fail, Security Access Manager continuously polls the server to check for its return to active duty. The poll time is 10 seconds.

Parent topic: LDAP failover configuration

Valid characters for LDAP user and group namesYou might use LDAP as the user registry. The set of valid characters allowed within a user or group name is determined by several Internet Engineering Task Force (IETF) Request for Comments (RFC).LDAPvalid characters for namesLDAPas user registryRelevant RFCs include:2253 Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names2254 The String Representation of LDAP Search FiltersThe specific LDAP server can also dictate the validity of these characters.In general, you can use special characters within a distinguished name. However, certain special characters require an additional escape character. The following special characters must be escaped when used in a distinguished name: Plus sign (+)Semicolon (;)Comma (,)Backward slash (\)Double quote (")Less than (<)Greater than (>)Pound sign (#)For example, to create a user that contains a semicolon with the pdadmin utility: pdadmin> user create "user;one" "cn=user\;one,o=tivoli,c=us" "user;one" "user;one" password1Avoid the backward slash character (\) as part of a user or group name. For more information, see "Characters disallowed for user and group name" in appendix A of the IBM Security Access Manager for Web: Command Reference.If you use special characters with the pdadmin utility, enclose each argument of the user or group command with double quotation marks. The double quotation marks allow the argument to be entered without being subject to interpretation by the operating system shell command processor.Due to the variability of special character handling in general, avoid the use of special characters.LDAP-specific tasksLDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.

Valid characters for LDAP user and group names

You might use LDAP as the user registry. The set of valid characters allowed within a user or group name is determined by several Internet Engineering Task Force (IETF) Request for Comments (RFC).

Relevant RFCs include:

2253 Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names

2254 The String Representation of LDAP Search Filters

The specific LDAP server can also dictate the validity of these characters.

In general, you can use special characters within a distinguished name. However, certain special characters require an additional escape character. The following special characters must be escaped when used in a distinguished name:

Plus sign (+)

Semicolon (;)

Comma (,)

Backward slash (\)

Double quote (")

Less than (<)

Greater than (>)

Pound sign (#)

For example, to create a user that contains a semicolon with the pdadmin utility:

pdadmin> user create "user;one" "cn=user\;one,o=tivoli,c=us"
"user;one" "user;one" password1

Note: Avoid the backward slash character (\) as part of a user or group name. For more information, see "Characters disallowed for user and group name" in appendix A of the IBM Security Access Manager for Web: Command Reference.

If you use special characters with the pdadmin utility, enclose each argument of the user or group command with double quotation marks. The double quotation marks allow the argument to be entered without being subject to interpretation by the operating system shell command processor.

Due to the variability of special character handling in general, avoid the use of special characters.

Parent topic: LDAP-specific tasks

Applying Security Access Manager ACLs to new LDAP suffixesThe LDAP naming model is maintained in a hierarchical namespace known as the Directory Information Tree (DIT).LDAPACLsapplyingACLLDAP suffixesMany LDAP server products, such as Security Directory Server, which is included with Security Access Manager, and the Sun Java System Directory Server and Novell eDirectory, maintain the data of the DIT in a hierarchical namespace that is often represented as a tree structure. The top of the tree is termed a naming context. Sometimes, this naming context is called a suffix because it represents the ending portion of a distinguished name (DN). For example, the c=us suffix might be created to represent country-specific data within an organization. An entry within this suffix might have a DN similar to cn=Joe Williams,ou=austin,o=ibm,c=us. The set of suffixes that is maintained by the LDAP server can be configured with the vendor-specific LDAP administration tools.When the Security Access Manager policy server is configured, it attempts to apply appropriate access controls in the form of Access Control Lists (ACLs) to each LDAP suffix that is in the LDAP server. This access control gives appropriate permissions to allow Security Access Manager to create and manage user and group information in these suffixes. The Security Access Manager policy server does not attempt to apply ACLs to each LDAP suffix when AD LDS is used as the user registry. Access to AD LDS registry entries is controlled by administration groups within AD LDS.For LDAP server types other than AD LDS, an LDAP administrator might add an LDAP suffix after Security Access Manager is configured. To have Security Access Manager to manage users and groups in this new suffix, the administrator must apply the appropriate ACLs to the new suffix.To apply the appropriate access controls to a newly created LDAP suffix, use the ivrgy_tool utility with the add-acls parameter. For more information, see "ivrgy_tool" in the IBM Security Access Manager for Web: Command Reference. Alternately, you can manually apply the following ACLs to each new suffix: cn=SecurityGroup,secAuthority=Default Full accesscn=ivacld-servers,cn=SecurityGroups,secAuthority=Default readsearchcomparewrite for the following attributes: secAcctValidsecPwdFailCountTimesecPwdFailuressecPwdLastChangedsecPwdLastFailedsecPwdLastUsedsecPwdUnlockTimesecPwdValidcn=remote-acl-users,cn=SecurityGroups,secAuthority=Default readsearchcomparewrite for the following attributes: secAcctValidsecPwdFailCountTimesecPwdFailuressecPwdLastChangedsecPwdLastFailedsecPwdLastUsedsecPwdUnlockTimesecPwdValidWhen using a generic LDAP server, give the same access controls to the specified groups. For information about how to set access control for a generic LDAP server, see the documentation that is associated with the generic LDAP server.If a Security Access Manager administrator created a domain other than the initial \Management domain, which is created during the configuration of the policy server, apply the following additional ACLs to the new suffix for each domain: cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains, secAuthority=Default Full accesscn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains, secAuthority=Default readsearchcomparewrite for the following attributes: secAcctValidsecPwdFailCountTimesecPwdFailuressecPwdLastChangedsecPwdLastFailedsecPwdLastUsedsecPwdUnlockTimesecPwdValidcn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name, cn=Subdomains,secAuthority=Default readsearchcomparewrite for the following attributes: secAcctValidsecPwdFailCountTimesecPwdFailuressecPwdLastChangedsecPwdLastFailedsecPwdLastUsedsecPwdUnlockTimesecPwdValidWhere domain_name is the name of the additional administrative domain. For a list of domains, use the domain list command.LDAP-specific tasksLDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.Example proceduresYou can use these example procedures for either Security Directory Server or Sun Java System Directory Server, depending on the LDAP server type that is used.

Applying Security Access Manager ACLs to new LDAP suffixes

The LDAP naming model is maintained in a hierarchical namespace known as the Directory Information Tree (DIT).

Many LDAP server products, such as Security Directory Server, which is included with Security Access Manager, and the Sun Java™ System Directory Server and Novell eDirectory, maintain the data of the DIT in a hierarchical namespace that is often represented as a tree structure. The top of the tree is termed a naming context. Sometimes, this naming context is called a suffix because it represents the ending portion of a distinguished name (DN). For example, the c=us suffix might be created to represent country-specific data within an organization. An entry within this suffix might have a DN similar to cn=Joe Williams,ou=austin,o=ibm,c=us. The set of suffixes that is maintained by the LDAP server can be configured with the vendor-specific LDAP administration tools.

When the Security Access Manager policy server is configured, it attempts to apply appropriate access controls in the form of Access Control Lists (ACLs) to each LDAP suffix that is in the LDAP server. This access control gives appropriate permissions to allow Security Access Manager to create and manage user and group information in these suffixes.

Note: The Security Access Manager policy server does not attempt to apply ACLs to each LDAP suffix when AD LDS is used as the user registry. Access to AD LDS registry entries is controlled by administration groups within AD LDS.

For LDAP server types other than AD LDS, an LDAP administrator might add an LDAP suffix after Security Access Manager is configured. To have Security Access Manager to manage users and groups in this new suffix, the administrator must apply the appropriate ACLs to the new suffix.

To apply the appropriate access controls to a newly created LDAP suffix, use the ivrgy_tool utility with the add-acls parameter. For more information, see "ivrgy_tool" in the IBM Security Access Manager for Web: Command Reference. Alternately, you can manually apply the following ACLs to each new suffix:

cn=SecurityGroup,secAuthority=Default

Full access

cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default

read

search

compare

write for the following attributes:

secAcctValid

secPwdFailCountTime

secPwdFailures

secPwdLastChanged

secPwdLastFailed

secPwdLastUsed

secPwdUnlockTime

secPwdValid

cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default

read

search

compare

write for the following attributes:

secAcctValid

secPwdFailCountTime

secPwdFailures

secPwdLastChanged

secPwdLastFailed

secPwdLastUsed

secPwdUnlockTime

secPwdValid

When using a generic LDAP server, give the same access controls to the specified groups. For information about how to set access control for a generic LDAP server, see the documentation that is associated with the generic LDAP server.

If a Security Access Manager administrator created a domain other than the initial \Management domain, which is created during the configuration of the policy server, apply the following additional ACLs to the new suffix for each domain:

cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains, secAuthority=Default

Full access

cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains, secAuthority=Default

read

search

compare

write for the following attributes:

secAcctValid

secPwdFailCountTime

secPwdFailures

secPwdLastChanged

secPwdLastFailed

secPwdLastUsed

secPwdUnlockTime

secPwdValid

cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name, cn=Subdomains,secAuthority=Default

read

search

compare

write for the following attributes:

secAcctValid

secPwdFailCountTime

secPwdFailures

secPwdLastChanged

secPwdLastFailed

secPwdLastUsed

secPwdUnlockTime

secPwdValid

Where domain_name is the name of the additional administrative domain. For a list of domains, use the domain list command.

Example procedures
You can use these example procedures for either Security Directory Server or Sun Java System Directory Server, depending on the LDAP server type that is used.

Parent topic: LDAP-specific tasks

Example proceduresYou can use these example procedures for either Security Directory Server or Sun Java System Directory Server, depending on the LDAP server type that is used. LDAPexamples, adding ACLsACLexamples, adding to suffixesThe example procedures assume that there is a newly created c=fr suffix. Substitute your newly created suffix for this value in the procedures.Applying Security Access Manager ACLs to new LDAP suffixesThe LDAP naming model is maintained in a hierarchical namespace known as the Directory Information Tree (DIT).Security Directory ServerThis procedure describes how to apply the appropriate Security Access Manager access controls in Security Directory Server for a newly created suffix.Sun Java System Directory ServerThis procedure applies the appropriate Security Access Manager access controls to the newly created suffix for Sun Java System Directory Server. IBM z/OS Security ServerThis procedure applies the appropriate Security Access Manager access controls to the newly created suffix for IBM z/OS Security Server. Do this procedure after the Security Access Manager policy server is configured.

Example procedures

You can use these example procedures for either Security Directory Server or Sun Java™ System Directory Server, depending on the LDAP server type that is used.

About this task

The example procedures assume that there is a newly created c=fr suffix. Substitute your newly created suffix for this value in the procedures.

Security Directory Server
This procedure describes how to apply the appropriate Security Access Manager access controls in Security Directory Server for a newly created suffix.

Sun Java System Directory Server
This procedure applies the appropriate Security Access Manager access controls to the newly created suffix for Sun Java System Directory Server.

IBM z/OS Security Server
This procedure applies the appropriate Security Access Manager access controls to the newly created suffix for IBM® z/OS® Security Server. Do this procedure after the Security Access Manager policy server is configured.

Parent topic: Applying Security Access Manager ACLs to new LDAP suffixes

Security Directory ServerThis procedure describes how to apply the appropriate Security Access Manager access controls in Security Directory Server for a newly created suffix.LDAPACLsapplying to Directory ServerACLDirectory Server, applying to This procedure uses the Security Directory Server Web Administration Tool and assumes that this tool is installed and configured into the WebSphere Application Server.Access the login page with a supported web browser. The default login page is the following URL:http://server_name:12100/IDSWebApp/IDSjsp/Login.jspWhere server_name is the host name of the application server where the Web Administration Tool is installed.If the list of console server contains the LDAP server to be administered, select its host name and go to step 4. If this list does not contain the server, add it as a console server.Add an LDAP server to the list of console servers:Log on as the Console Admin. The default Console Admin identity is superadmin and the default password is secret.In the navigation area on the left, click Console administration and Manage console servers. This action presents a list of LDAP servers that are currently configured for administration. Click Add and type the host name and port number for the LDAP server to be administered.Click OK to add the server.Click Close to complete the action.From the navigation area, click Logout.Access the login page with the URL in step 1 and select from the list the LDAP server that you added.In the Login window, type the LDAP server administrator in the Username field (for example, cn=root) and password in the password field, and click Login.In the navigation area on the left, click Directory management and Manage entries.If you see the newly added suffix in the Manage entries window on the right, go to step 7. If you do not see the newly added suffix, add an entry for a newly created suffix.Add a suffix:Click Add to display the Add an entry window.Select the appropriate structural object class for the newly added suffix. For the c=fr suffix, the appropriate object class is country.Click Next to display the Select auxiliary object classes window where you can add additional object classes appropriate for the entry type.Because this example does not use other object classes, click Next to define the selected structural object class.In the Relative DN field, type c=fr and leave the Parent DN field blank. The only required attribute is c for country. Enter the value fr, and click Finish to return to the Manage entries window. You now see the newly added suffix in the list of top-level entries.In the Manage entries window:From the Select column, select the suffix.From the Select Action list, select Edit ACL.Click Go to display the Edit ACL window that shows the current ACLs on the suffix.In the Edit ACL window:Click Non-filtered ACLs.Ensure that the Propagate ACLs option is selected.Click Add to display the Add access rights window.In the Add access rights window:In the Subject DN (distinguished name) field, type cn=SecurityGroup,secAuthority=Default.Set the Add child right to grant.Set the Delete entry right to grant.Set the normal, sensitive, critical, system and restricted security classes to grant for the read, write, search and compare actions.Click OK to return to the Edit ACL window.In the Edit ACL window, click Add to display the Add access rights window.In the Add access rights window:In the Subject DN (distinguished name) field, type cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default.Set the Subject Type to group.Set the normal security classes to grant for the read, search and compare actions.From the Attributes list, select secAcctValid and click Define. Repeat this step for each of the following attributes: secPwdFailCountTimesecPwdFailuressecPwdLastChangedsecPwdLastFailedsecPwdLastUsedsecPwdUnlockTimesecPwdValidAfter defining these attributes, set each of these attributes to grant for the read, write, search and compare actions.Click OK to return to the Edit ACL window.If you have other domains that need domain ACLs, continue to step 12. If you have no further domains, this step completes the access control. Go to step 17. This sample procedure has additional domains the require domain ACLs.In the Edit ACL window, click Add to display the Add access rights window.In the Add access rights window: In the Subject DN (distinguished name) field, type cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains, secAuthority=Default, where domain_name is the domain name that is protected.Set the Add child right to grant.Set the Delete entry right to grant.Set the normal, sensitive, critical, system and restricted security classes to grant for the read, write, search, and compare actions.Click OK to return to the Edit ACL window.In the Edit ACL window, click Add to display the Add access rights window.In the Add access rights window:In the Subject DN (distinguished name) field, type cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains, secAuthority=Default, where domain_name is the domain name that is protected.Set the Subject Type to group.Set the normal security classes to grant for the read, search and compare actions.From the Attributes list, select secAcctValid and click Define. Repeat this step for each of the following attributes:secPwdFailCountTimesecPwdFailuressecPwdLastChangedsecPwdLastFailedsecPwdLastUsedsecPwdUnlockTimesecPwdValidAfter defining these attributes, set each of these attributes to grant for the read, write, search and compare actions.Click OK to return to the Edit ACL window.In the Edit ACL window, click Add to display the Add access rights window.In the Add access rights window:In the Subject DN (distinguished name) field, type cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains, secAuthority=Default, where domain_name is the domain name that is protected.Set the Subject Type to group.Set the normal security classes to grant for the read, search and compare actions.From the Attributes list, select secAcctValid and click Define. Repeat this step for each of the following attributes: secPwdFailCountTimesecPwdFailuressecPwdLastChangedsecPwdLastFailedsecPwdLastUsedsecPwdUnlockTimesecPwdValidAfter defining these attributes, set each of these attributes to grant for the read, write, search and compare actions.Click OK to return to the Edit ACL window.This completes the addition of the access control for the suffix.Click Close. You do not need to restart the LDAP server for the changes to take effect.If you no longer need to use the Web Administration Tool, click Logout.Example proceduresYou can use these example procedures for either Security Directory Server or Sun Java System Directory Server, depending on the LDAP server type that is used.

Security Directory Server

This procedure describes how to apply the appropriate Security Access Manager access controls in Security Directory Server for a newly created suffix.

About this task

This procedure uses the Security Directory Server Web Administration Tool and assumes that this tool is installed and configured into the WebSphere Application Server.

Procedure

Access the login page with a supported web browser. The default login page is the following URL:

http://

server_name

:12100/IDSWebApp/IDSjsp/Login.jsp

Where server_name is the host name of the application server where the Web Administration Tool is installed.

If the list of console server contains the LDAP server to be administered, select its host name and go to step 4. If this list does not contain the server, add it as a console server.

Add an LDAP server to the list of console servers:

Log on as the Console Admin. The default Console Admin identity is superadmin and the default password is secret.

In the navigation area on the left, click Console administration and Manage console servers. This action presents a list of LDAP servers that are currently configured for administration.

Click Add and type the host name and port number for the LDAP server to be administered.

Click OK to add the server.

Click Close to complete the action.

From the navigation area, click Logout.

Access the login page with the URL in step 1 and select from the list the LDAP server that you added.

In the Login window, type the LDAP server administrator in the Username field (for example, cn=root) and password in the password field, and click Login.

In the navigation area on the left, click Directory management and Manage entries. If you see the newly added suffix in the Manage entries window on the right, go to step 7. If you do not see the newly added suffix, add an entry for a newly created suffix.

Add a suffix:

Click Add to display the Add an entry window.

Select the appropriate structural object class for the newly added suffix. For the c=fr suffix, the appropriate object class is country.

Click Next to display the Select auxiliary object classes window where you can add additional object classes appropriate for the entry type.

Because this example does not use other object classes, click Next to define the selected structural object class.

In the Relative DN field, type c=fr and leave the Parent DN field blank. The only required attribute is c for country. Enter the value fr, and click Finish to return to the Manage entries window. You now see the newly added suffix in the list of top-level entries.

In the Manage entries window:

From the Select column, select the suffix.

From the Select Action list, select Edit ACL.

Click Go to display the Edit ACL window that shows the current ACLs on the suffix.

In the Edit ACL window:

Click Non-filtered ACLs.

Ensure that the Propagate ACLs option is selected.

Click Add to display the Add access rights window.

In the Add access rights window:

In the Subject DN (distinguished name) field, type cn=SecurityGroup,secAuthority=Default.

Set the Add child right to grant.

Set the Delete entry right to grant.

Set the normal, sensitive, critical, system and restricted security classes to grant for the read, write, search and compare actions.

Click OK to return to the Edit ACL window.

In the Edit ACL window, click Add to display the Add access rights window.

In the Add access rights window:

In the Subject DN (distinguished name) field, type cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default.

Set the Subject Type to group.

Set the normal security classes to grant for the read, search and compare actions.

From the Attributes list, select secAcctValid and click Define. Repeat this step for each of the following attributes:

secPwdFailCountTime

secPwdFailures

secPwdLastChanged

secPwdLastFailed

secPwdLastUsed

secPwdUnlockTime

secPwdValid

After defining these attributes, set each of these attributes to grant for the read, write, search and compare actions.

Click OK to return to the Edit ACL window.

If you have other domains that need domain ACLs, continue to step 12. If you have no further domains, this step completes the access control. Go to step 17. This sample procedure has additional domains the require domain ACLs.

In the Edit ACL window, click Add to display the Add access rights window.

In the Add access rights window:

In the Subject DN (distinguished name) field, type cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains, secAuthority=Default, where domain_name is the domain name that is protected.

Set the Add child right to grant.

Set the Delete entry right to grant.

Set the normal, sensitive, critical, system and restricted security classes to grant for the read, write, search, and compare actions.

Click OK to return to the Edit ACL window.

In the Edit ACL window, click Add to display the Add access rights window.

In the Add access rights window:

In the Subject DN (distinguished name) field, type cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains, secAuthority=Default, where domain_name is the domain name that is protected.

Set the Subject Type to group.

Set the normal security classes to grant for the read, search and compare actions.

From the Attributes list, select secAcctValid and click Define. Repeat this step for each of the following attributes:

secPwdFailCountTime

secPwdFailures

secPwdLastChanged

secPwdLastFailed

secPwdLastUsed

secPwdUnlockTime

secPwdValid

After defining these attributes, set each of these attributes to grant for the read, write, search and compare actions.

Click OK to return to the Edit ACL window.

In the Edit ACL window, click Add to display the Add access rights window.

In the Add access rights window:

In the Subject DN (distinguished name) field, type cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,cn=Subdomains, secAuthority=Default, where domain_name is the domain name that is protected.

Set the Subject Type to group.

Set the normal security classes to grant for the read, search and compare actions.

From the Attributes list, select secAcctValid and click Define. Repeat this step for each of the following attributes:

secPwdFailCountTime

secPwdFailures

secPwdLastChanged

secPwdLastFailed

secPwdLastUsed

secPwdUnlockTime

secPwdValid

After defining these attributes, set each of these attributes to grant for the read, write, search and compare actions.

Click OK to return to the Edit ACL window.

This completes the addition of the access control for the suffix.

Click Close. You do not need to restart the LDAP server for the changes to take effect.

If you no longer need to use the Web Administration Tool, click Logout.

Parent topic: Example procedures

Sun Java System Directory ServerThis procedure applies the appropriate Security Access Manager access controls to the newly created suffix for Sun Java System Directory Server. LDAPACLsapplying to Sun Java SystemACLSun Java System, applying toThis procedure uses the Sun Java System Server Console. Start the Sun Java System Server Console with one of the following commands: On AIX, Linux, and Solaris operating systems, enter the following command from the Sun Java System Directory Server installation directory: # ./startconsoleOn systems that run the Solaris operating environment, when not using the Solaris packaged version: Change to the server root directory.Enter the following command: startconsole argumentsType –h to display a usage message that explains command-line arguments. On Windows operating systems, select StartProgramsSun Java System Server ProductsSun Java System Server Console Version version_number.Log on to the Sun Java System Server Console: Type the LDAP administrator ID, which is usually cn=Directory ManagerType the password for this administrator.Click OK.Select the Sun Java System Domain to be used by Security Access Manager.Expand the server name and Server Group.Select Directory Server to display the configuration information about the Sun Java System Directory server.Click Open to access the Sun Java System Directory server.Click the Directory tab. If the newly created suffix is displayed on the left pane, go to step 8. If the newly created suffix is not displayed, create an entry for the new suffix before applying access controls to the suffix. These instructions assume an example suffix. Create the entry type and name that corresponds to your actual suffix. To create the entry: Right-click the name of the server at the top of the directory tree, and select ObjectNew Root Object to display a list of root suffixes.Select c=fr from the list of root suffixes. The New Object selection window is displayed. In the New Object selection window, scroll down and select Country as the new object entry type.Click OK to display the Property Editor window.In the Country field type fr, and click OK.Select ViewRefresh to display the new suffix.Right-click c=fr in the left pane, and select Object → Set Access Permissions to display the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type SECURITY GROUP – ALLOW ALL.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="*") (version 3.0; acl "SECURITY GROUP – ALLOW ALL"; allow (all) groupdn = "ldap:///cn=SecurityGroup,secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type PD Servers GROUP – ALLOW READ.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="*") (version 3.0; acl "PD Servers GROUP – ALLOW READ"; allow (read, search, compare) groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups, secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type SECURITY GROUP– ALLOW WRITE.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="secAcctValid || secPwdFailCountTime || secPwdFailures || secPwdLastChanged || secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime || secPwdValid") (version 3.0; acl "SECURITY GROUP– ALLOW WRITE"; allow (read, search, compare) groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups, secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type PD Remote ACL Users GROUP – ALLOW READ.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="*") (version 3.0; acl "PD Remote ACL Users GROUP – ALLOW READ"; allow (read, search, compare) groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups, secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type SECURITY GROUP– ALLOW WRITE.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="secAcctValid || secPwdFailCountTime || secPwdFailures || secPwdLastChanged || secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime || secPwdValid") (version 3.0; acl "SECURITY GROUP– ALLOW WRITE"; allow (read, search, compare) groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups, secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type PD Deny-Others.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (targetfilter="(secAuthority=Default)") (version 3.0; acl "PD Deny-Others"; deny(all) groupdn != "ldap:///cn=SecurityGroup,secAuthority=Default|| ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default|| ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.If you have no further domains, this action completes the access control. You can skip to step 34. If you have additional domains that require domain ACLs, continue with step 21.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type SECURITY GROUP – ALLOW ALL.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="*") (version 3.0; acl "SECURITY GROUP - ALLOW ALL; allow (all) groupdn = "ldap:///cn=SecurityGroup,secAuthority=domain_name, cn=Subdomains,secAuthority=Default";)where domain_name is the name of the domain that is protected.Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type PD Servers GROUP – ALLOW READ.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="*") (version 3.0; acl "PD Servers GROUP - ALLOW READ"; allow (read, search, compare) groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups, secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)where domain_name is the name of the domain that is protected.Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type SECURITY GROUP– ALLOW WRITE.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="secAcctValid || secPwdFailCountTime || secPwdFailures || secPwdLastChanged || secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime || secPwdValid") (version 3.0; acl "SECURITY GROUP– ALLOW WRITE"; allow (read, search, compare) groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups, secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type PD Remote ACL Users GROUP – ALLOW READ.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="*") (version 3.0; acl "PD Remote ACL Users GROUP - ALLOW READ"; allow (read, search, compare) groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups, secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)where domain_name is the name of the domain that is protected.Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type SECURITY GROUP– ALLOW WRITE.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (target="ldap:///c=fr")(targetattr="secAcctValid || secPwdFailCountTime || secPwdFailures || secPwdLastChanged || secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime || secPwdValid") (version 3.0; acl "SECURITY GROUP– ALLOW WRITE"; allow (read, search, compare) groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups, secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.Click New to display the Edit ACI for c=fr window.In the Edit ACI for c=fr window: In the ACI name field, type PD Deny-Others.Highlight All Users, and click Remove.Click Edit Manually.Replace the default ACI text with the following text: (targetfilter="(secAuthority=domain_name)") (version 3.0; acl "PD Deny-Others"; deny(all) groupdn != "ldap:///cn=SecurityGroup,secAuthority=Default|| ldap:///cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains, secAuthority=Default|| ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name, cn=Subdomains,secAuthority=Default|| ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name, cn=Subdomains,secAuthority=Default";)where domain_name is the name of the domain that is protected.Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.Click OK to return to the Manage Access Control for c=fr window.If there are further domains, repeat steps 21 to 32 for each domain. When complete, continue with step 34.Click OK to close the Manage Access Control for c=fr window. Click ConsoleExit to exit the console.Example proceduresYou can use these example procedures for either Security Directory Server or Sun Java System Directory Server, depending on the LDAP server type that is used.

Sun Java System Directory Server

This procedure applies the appropriate Security Access Manager access controls to the newly created suffix for Sun Java™ System Directory Server.

About this task

This procedure uses the Sun Java System Server Console.

Procedure

Start the Sun Java System Server Console with one of the following commands:

On AIX, Linux, and Solaris operating systems, enter the following command from the Sun Java System Directory Server installation directory:

# ./startconsole

On systems that run the Solaris operating environment, when not using the Solaris packaged version:

Change to the server root directory.

Enter the following command:

startconsole arguments

Type –h to display a usage message that explains command-line arguments.

On Windows operating systems, select Start > Programs > Sun Java System Server Products > Sun Java System Server Console Version version_number.

Log on to the Sun Java System Server Console:

Type the LDAP administrator ID, which is usually cn=Directory Manager

Type the password for this administrator.

Click OK.

Select the Sun Java System Domain to be used by Security Access Manager.

Expand the server name and Server Group.

Select Directory Server to display the configuration information about the Sun Java System Directory server.

Click Open to access the Sun Java System Directory server.

Click the Directory tab. If the newly created suffix is displayed on the left pane, go to step 8. If the newly created suffix is not displayed, create an entry for the new suffix before applying access controls to the suffix.

Note: These instructions assume an example suffix. Create the entry type and name that corresponds to your actual suffix.

To create the entry:

Right-click the name of the server at the top of the directory tree, and select Object > New Root Object to display a list of root suffixes.

Select c=fr from the list of root suffixes. The New Object selection window is displayed.

In the New Object selection window, scroll down and select Country as the new object entry type.

Click OK to display the Property Editor window.

In the Country field type fr, and click OK.

Select View > Refresh to display the new suffix.

Right-click c=fr in the left pane, and select Object → Set Access Permissions to display the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type SECURITY GROUP – ALLOW ALL.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")
(version 3.0; acl "SECURITY GROUP – ALLOW ALL";
allow (all)
groupdn = "ldap:///cn=SecurityGroup,secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type PD Servers GROUP – ALLOW READ.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")
(version 3.0; acl "PD Servers GROUP – ALLOW READ";
allow (read, search, compare)
groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,
secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type SECURITY GROUP– ALLOW WRITE.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="secAcctValid ||
secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||
secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||
secPwdValid")
(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";
allow (read, search, compare)
groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,
secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type PD Remote ACL Users GROUP – ALLOW READ.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")
(version 3.0; acl "PD Remote ACL Users GROUP – ALLOW READ";
allow (read, search, compare)
groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,
secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type SECURITY GROUP– ALLOW WRITE.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="secAcctValid ||
secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||
secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||
secPwdValid")
(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";
allow (read, search, compare)
groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,
secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type PD Deny-Others.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(targetfilter="(secAuthority=Default)")
(version 3.0; acl "PD Deny-Others";
deny(all)
groupdn != "ldap:///cn=SecurityGroup,secAuthority=Default||
ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=Default||
ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

If you have no further domains, this action completes the access control. You can skip to step 34. If you have additional domains that require domain ACLs, continue with step 21.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type SECURITY GROUP – ALLOW ALL.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")
(version 3.0; acl "SECURITY GROUP - ALLOW ALL;
allow (all)
groupdn = "ldap:///cn=SecurityGroup,secAuthority=domain_name,
cn=Subdomains,secAuthority=Default";)

where domain_name is the name of the domain that is protected.

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type PD Servers GROUP – ALLOW READ.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")
(version 3.0; acl "PD Servers GROUP - ALLOW READ";
allow (read, search, compare)
groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,
secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)

where domain_name is the name of the domain that is protected.

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type SECURITY GROUP– ALLOW WRITE.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="secAcctValid ||
secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||
secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||
secPwdValid")
(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";
allow (read, search, compare)
groupdn = "ldap:///cn=ivacld-servers,cn=SecurityGroups,
secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type PD Remote ACL Users GROUP – ALLOW READ.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="*")
(version 3.0; acl "PD Remote ACL Users GROUP - ALLOW READ";
allow (read, search, compare)
groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,
secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)

where domain_name is the name of the domain that is protected.

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type SECURITY GROUP– ALLOW WRITE.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(target="ldap:///c=fr")(targetattr="secAcctValid ||
secPwdFailCountTime || secPwdFailures || secPwdLastChanged ||
secPwdLastFailed || secPWDLastUsed || secPwdUnlockTime ||
secPwdValid")
(version 3.0; acl "SECURITY GROUP– ALLOW WRITE";
allow (read, search, compare)
groupdn = "ldap:///cn=remote-acl-users,cn=SecurityGroups,
secAuthority=domain_name,cn=Subdomains,secAuthority=Default";)

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

Click New to display the Edit ACI for c=fr window.

In the Edit ACI for c=fr window:

In the ACI name field, type PD Deny-Others.

Highlight All Users, and click Remove.

Click Edit Manually.

Replace the default ACI text with the following text:

(targetfilter="(secAuthority=domain_name)")
(version 3.0; acl "PD Deny-Others";
deny(all)
groupdn != "ldap:///cn=SecurityGroup,secAuthority=Default||
ldap:///cn=SecurityGroup,secAuthority=domain_name,cn=Subdomains,
secAuthority=Default||
ldap:///cn=remote-acl-users,cn=SecurityGroups,secAuthority=domain_name,
cn=Subdomains,secAuthority=Default||
ldap:///cn=ivacld-servers,cn=SecurityGroups,secAuthority=domain_name,
cn=Subdomains,secAuthority=Default";)

where domain_name is the name of the domain that is protected.

Click Check Syntax to ensure validate the text. Correct errors until the syntax validates.

Click OK to return to the Manage Access Control for c=fr window.

If there are further domains, repeat steps 21 to 32 for each domain. When complete, continue with step 34.

Click OK to close the Manage Access Control for c=fr window.

Click Console > Exit to exit the console.

Parent topic: Example procedures

IBM z/OS Security ServerThis procedure applies the appropriate Security Access Manager access controls to the newly created suffix for IBM z/OS Security Server. Do this procedure after the Security Access Manager policy server is configured. LDAPapplying ACLs to z/OSACLapplying to z/OSInstead of using the manual process described below, you can use the ivrgy_tool utility to update the ACLs on suffixes added after the initial policy server configuration. See "ivrgy_tool" in the IBM Security Access Manager for Web: Installation Guide.These steps are specifically for the IBM Security Directory Server for z/OS Version 1.8. This LDAP server is the IBM z/OS LDAP Server. Add the new suffix to the LDAP server configuration file. See z/OS LDAP Server Administration and Use for your version of z/OS LDAP for details on how to update the server configuration file.Restart the IBM z/OS LDAP Server.To add an entry to the newly created suffix, do the following steps: Create an LDIF file. This example assumes that the new suffix is o=neworg,c=us: dn: o=neworg,c=us objectClass: organization objectClass: top o: neworgUse the appropriate LDIF file as input to the ldapadd command: ldapadd -h ldap_host -p ldap_port -D ldap_admin_dn -w ldap_admin_pwd -v -f ldif_filenameTo apply the appropriate Security Access Manager access controls to the newly created suffix (suffix), do either of the following tasks: If no additional Security Access Manager domains were created other than the initial management domain, complete the following steps: Create the following LDIF file: dn: suffix aclpropagate: TRUE aclentry: group:cn=SecurityGroup,secAuthority=Default:object:ad:normal:\ rwsc:sensitive:rwsc:critical:rwsc:restricted:rwsc aclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=Defaul\ t:normal:rsc:at.userPassword:wc:at.secAcctValid:rwsc: at.secPwdFailCountTime:rwsc:at.secPwd\ Failures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.sec\ PwdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc aclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=Defau\ lt:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.secPwd\ Failures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.secP\ wdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc entryowner: LDAP_admin_dn entryowner: group:cn=SecurityGroup,secAuthority=Default ownerpropagate: TRUEThe backward slash (\) at the end of a line indicates that this line combines with the next line, without any spaces.Apply the updates in the LDIF file by using it as input to the ldapmodify command: ldapmodify -h ldap_host -p ldap_port -D ldap_admin_dn -w ldap_admin_pwd -v -f ldif_fileIf a domain was created in addition to the initial management domain, and if a new suffix is created, apply ACLs for each added domain. Complete the following steps: Add ACLs to the default domain and added domain (added_domain) by creating an LDIF file similar to the following one: dn: suffix aclentry: group:cn=SecurityGroup,secAuthority=Default:object:ad:normal\ :rwsc:sensitive:rwsc:critical:rwsc:restricted:rwsc aclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=Defau\ lt:normal:rsc:at.userPassword:wc:at.secAcctValid: rwsc:at.secPwdFailCountTime:rwsc:at.secP\wdFailures:rwsc: at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.\secPwdLastUsed: rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc aclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=Def\ ault:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.se\ cPwdFailures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:a\ t.secPwdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc aclentry: group:cn=SecurityGroup,secAuthority=added_domain,cn=Subdomai\ ns,secAuthority=Default:object:ad:normal:rwsc:sensitive:rwsc:critical:\ rwsc:restricted:rwsc aclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=added\ _domain,cn=Subdomains,secAuthority= Default:normal:rsc:at.userPassword:wc:at.secAcctValid:\ rwsc:at.secPwdFailCountTime:rwsc:at.secPwdFailures:rwsc:at.secPwdLastC\ hanged:rwsc:at.secPwdLastFailed:rwsc:at.secPwdLastUsed:rwsc:at.secPwdU\ nlockTime:rwsc:at.secPwdValid:rwsc aclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=add\ ed_domain,cn=Subdomains,secAuthority= Default:normal:rsc:at.userPassword:wc:at.secAcctVali\ d:rwsc:at.secPwdFailCountTime:rwsc:at.secPwdFailures:rwsc:at.secPwdLas\ tChanged:rwsc:at.secPwdLastFailed:rwsc:at.secPwdLastUsed:rwsc:at.secPw\ dUnlockTime:rwsc:at.secPwdValid:rwsc aclpropagate: TRUE entryowner: LDAP_admin_dn entryowner: group:cn=SecurityGroup,secAuthority=Default ownerpropagate: TRUEApply the updates in the LDIF file by using it as input to the ldapmodify command: ldapmodify -h ldap_host -p ldap_port -D ldap_admin_dn -w ldap_admin_pwd -v -f ldif_fileThe ldapmodify command returns an error if the following attributes and values are set by default for the newly added suffix: aclpropagate: TRUE entryowner: LDAP_admin_dn ownerpropagate: TRUEIf the ldapmodify command returns the following error, remove these three attribute and value pairs from the LDIF file and run the ldapmodify command again: ldapmodify: additional info: R004086 Entry 'suffix' already contains attribute 'attribute' with value 'value'Example proceduresYou can use these example procedures for either Security Directory Server or Sun Java System Directory Server, depending on the LDAP server type that is used.

IBM z/OS Security Server

This procedure applies the appropriate Security Access Manager access controls to the newly created suffix for IBM® z/OS® Security Server. Do this procedure after the Security Access Manager policy server is configured.

About this task

Instead of using the manual process described below, you can use the ivrgy_tool utility to update the ACLs on suffixes added after the initial policy server configuration. See "ivrgy_tool" in the IBM Security Access Manager for Web: Installation Guide.

These steps are specifically for the IBM Security Directory Server for z/OS Version 1.8. This LDAP server is the IBM z/OS LDAP Server.

Procedure

Add the new suffix to the LDAP server configuration file. See z/OS LDAP Server Administration and Use for your version of z/OS LDAP for details on how to update the server configuration file.

Restart the IBM z/OS LDAP Server.

To add an entry to the newly created suffix, do the following steps:

Create an LDIF file. This example assumes that the new suffix is o=neworg,c=us:

dn: o=neworg,c=us
objectClass: organization
objectClass: top
o: neworg

Use the appropriate LDIF file as input to the ldapadd command:

ldapadd -h ldap_host -p ldap_port -D ldap_admin_dn -w ldap_admin_pwd
  -v -f ldif_filename

To apply the appropriate Security Access Manager access controls to the newly created suffix (suffix), do either of the following tasks:

If no additional Security Access Manager domains were created other than the initial management domain, complete the following steps:

Create the following LDIF file:

dn: suffix
aclpropagate: TRUE
aclentry: group:cn=SecurityGroup,secAuthority=Default:object:ad:normal:\
rwsc:sensitive:rwsc:critical:rwsc:restricted:rwsc
aclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=Defaul\
t:normal:rsc:at.userPassword:wc:at.secAcctValid:rwsc:
at.secPwdFailCountTime:rwsc:at.secPwd\
Failures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.sec\
PwdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc
aclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=Defau\
lt:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.secPwd\
Failures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.secP\
wdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc
entryowner: LDAP_admin_dn
entryowner: group:cn=SecurityGroup,secAuthority=Default
ownerpropagate: TRUE

The backward slash (\) at the end of a line indicates that this line combines with the next line, without any spaces.

Apply the updates in the LDIF file by using it as input to the ldapmodify command:

ldapmodify -h ldap_host -p ldap_port -D ldap_admin_dn
-w ldap_admin_pwd -v -f ldif_file

If a domain was created in addition to the initial management domain, and if a new suffix is created, apply ACLs for each added domain. Complete the following steps:

Add ACLs to the default domain and added domain (added_domain) by creating an LDIF file similar to the following one:

dn: suffix
aclentry: group:cn=SecurityGroup,secAuthority=Default:object:ad:normal\
:rwsc:sensitive:rwsc:critical:rwsc:restricted:rwsc
aclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=Defau\
lt:normal:rsc:at.userPassword:wc:at.secAcctValid:
rwsc:at.secPwdFailCountTime:rwsc:at.secP\wdFailures:rwsc:
at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:at.\secPwdLastUsed:
rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc
aclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=Def\
ault:normal:rsc:at.secAcctValid:rwsc:at.secPwdFailCountTime:rwsc:at.se\
cPwdFailures:rwsc:at.secPwdLastChanged:rwsc:at.secPwdLastFailed:rwsc:a\
t.secPwdLastUsed:rwsc:at.secPwdUnlockTime:rwsc:at.secPwdValid:rwsc
aclentry: group:cn=SecurityGroup,secAuthority=added_domain,cn=Subdomai\
ns,secAuthority=Default:object:ad:normal:rwsc:sensitive:rwsc:critical:\
rwsc:restricted:rwsc
aclentry: group:cn=ivacld-servers,cn=SecurityGroups,secAuthority=added\
_domain,cn=Subdomains,secAuthority=
Default:normal:rsc:at.userPassword:wc:at.secAcctValid:\
rwsc:at.secPwdFailCountTime:rwsc:at.secPwdFailures:rwsc:at.secPwdLastC\
hanged:rwsc:at.secPwdLastFailed:rwsc:at.secPwdLastUsed:rwsc:at.secPwdU\
nlockTime:rwsc:at.secPwdValid:rwsc
aclentry: group:cn=remote-acl-users,cn=SecurityGroups,secAuthority=add\
ed_domain,cn=Subdomains,secAuthority=
Default:normal:rsc:at.userPassword:wc:at.secAcctVali\
d:rwsc:at.secPwdFailCountTime:rwsc:at.secPwdFailures:rwsc:at.secPwdLas\
tChanged:rwsc:at.secPwdLastFailed:rwsc:at.secPwdLastUsed:rwsc:at.secPw\
dUnlockTime:rwsc:at.secPwdValid:rwsc
aclpropagate: TRUE
entryowner: LDAP_admin_dn
entryowner: group:cn=SecurityGroup,secAuthority=Default
ownerpropagate: TRUE

Apply the updates in the LDIF file by using it as input to the ldapmodify command:

ldapmodify -h ldap_host -p ldap_port -D ldap_admin_dn -w ldap_admin_pwd
-v -f ldif_file

Note: The ldapmodify command returns an error if the following attributes and values are set by default for the newly added suffix:

aclpropagate: TRUE
entryowner: LDAP_admin_dn
ownerpropagate: TRUE

If the ldapmodify command returns the following error, remove these three attribute and value pairs from the LDIF file and run the ldapmodify command again:

ldapmodify: additional info: R004086 Entry 'suffix' already contains
  attribute 'attribute' with value 'value'

Parent topic: Example procedures

Setting the password history policyIf Security Directory Server is your user registry, you can use its password history policy.LDAPpassword history policypasswordhistory policyFor more information about setting the password policy that is used with Security Directory Server, see the IBM Security Directory Server: Administration Guide.Access the login page with a supported web browser. The default login page is the following URL: http://server_name:12100/IDSWebApp/IDSjsp/Login.jsp Where server_name is the host name of the application server where the Web Administration Tool is installed.Select the LDAP host name to be managed and log on as an LDAP administrator (for example, cn=root). The Web Administration Tool starts.In the navigation area, select Server administrationManage security properties.In the main window, select Password validation.Set the minimum number of passwords that must be used before a password can be reused. Enter a number from 0 to 30. If you enter zero, a password can be reused without restriction.Click Apply.In the main window, click Password policy.If not already enabled, set the Password policy enabled check box to enable password policy.Click OK.LDAP-specific tasksLDAP is a protocol that runs over TCP/IP. The LDAP protocol standard includes low-level network protocol definitions plus data representation and handling.

Setting the password history policy

If Security Directory Server is your user registry, you can use its password history policy.

About this task

For more information about setting the password policy that is used with Security Directory Server, see the IBM Security Directory Server: Administration Guide.

Procedure

Access the login page with a supported web browser. The default login page is the following URL:

http://

server_name

:12100/IDSWebApp/IDSjsp/Login.jsp

Where server_name is the host name of the application server where the Web Administration Tool is installed.

Select the LDAP host name to be managed and log on as an LDAP administrator (for example, cn=root). The Web Administration Tool starts.

In the navigation area, select Server administration > Manage security properties.

In the main window, select Password validation.

Set the minimum number of passwords that must be used before a password can be reused. Enter a number from 0 to 30. If you enter zero, a password can be reused without restriction.

Click Apply.

In the main window, click Password policy.

If not already enabled, set the Password policy enabled check box to enable password policy.

Click OK.

Parent topic: LDAP-specific tasks

Novell-specific tasksThe Novell eDirectory can be configured as a Security Access Manager user registry.userregistriesmanaging NovellNovell servermanagingThis section describes a few steps that are unique to this configuration.Managing user registriesThis appendix contains a subset of user registry tasks that are specific to installing Security Access Manager.Updating the eDirectory schema with ConsoleOneIf you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured.Updating the eDirectory schema with Novell iManagerIf you install a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured. Novell eDirectory maintenance activities that can damage schema modifications applied by Security Access ManagerNovell eDirectory defines the object classes User and Group as part of its base schema.

Novell-specific tasks

The Novell eDirectory can be configured as a Security Access Manager user registry.

This section describes a few steps that are unique to this configuration.

Updating the eDirectory schema with ConsoleOne
If you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured.

Updating the eDirectory schema with Novell iManager
If you install a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured.

Novell eDirectory maintenance activities that can damage schema modifications applied by Security Access Manager
Novell eDirectory defines the object classes User and Group as part of its base schema.

Parent topic: Managing user registries

Updating the eDirectory schema with ConsoleOneIf you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured.Novell serverupdating eDirectory schema (iManager)Before you configure the policy server, modify Novell eDirectory with Novell’s ConsoleOne directory management utility or iManager web-based administration console. The default Novell eDirectory schema assumes that the directory does not use the X.500 object classes of inetOrgPerson or groupOfNames. By default, these classes are mapped into the eDirectory classes of User and Group. Because Security Access Manager uses the inetOrgPerson and groupOfNames object classes for creating its own users and groups, modifications to the default eDirectory schema are required.To update the eDirectory schema with the Novell iManager web-based administration console, see Updating the eDirectory schema with Novell iManagerIf you install a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured. .Start the Novell ConsoleOne directory management utility.Select the organization object within your Novell eDirectory tree. A list of objects is displayed on the right side of the ConsoleOne window.Right click the LDAP group object (not LDAP server), and click Properties from the menu.Click the Class Map tab and the table of LDAP class names. The Novell eDirectory class names are displayed.Delete the entries with LDAP classes of inetOrgPerson and groupOfNames.Click Apply and then click Close.Click the Attribute Map tab and the table of LDAP attribute names. The Novell eDirectory attribute names are displayed.Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, then no change is needed. If the attribute is showing the default value of uniqueMember, you need to modify it as follows. Click Modify. The Attribute Mapping window is displayed.Change the Primary LDAP Attribute field from uniqueMember to member.Change the Secondary LDAP attribute field from member to uniqueMember.In the Attribute window, click OK to accept the changes.If you are using Solaris, proceed to the next step. If you are using Windows NT, you might have to add another mapping for the LDAP attribute ndsHomeDirectory as follows: On the right hand side of the Attribute Mappings window, click Add. The Attribute Mapping window repaints and is displayed again.From the Novell eDirectory NSD Attribute field menu, click Home Directory.In the Primary LDAP Attribute field, click ndsHomeDirectory.In the Attribute Mapping window, click OK to accept the changes.In the Properties window, click OK.Novell-specific tasksThe Novell eDirectory can be configured as a Security Access Manager user registry.

Updating the eDirectory schema with ConsoleOne

If you are installing a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured.

About this task

Before you configure the policy server, modify Novell eDirectory with Novell’s ConsoleOne directory management utility or iManager web-based administration console.

Note: The default Novell eDirectory schema assumes that the directory does not use the X.500 object classes of inetOrgPerson or groupOfNames. By default, these classes are mapped into the eDirectory classes of User and Group. Because Security Access Manager uses the inetOrgPerson and groupOfNames object classes for creating its own users and groups, modifications to the default eDirectory schema are required.

To update the eDirectory schema with the Novell iManager web-based administration console, see Updating the eDirectory schema with Novell iManager.

Procedure

Start the Novell ConsoleOne directory management utility.

Select the organization object within your Novell eDirectory tree. A list of objects is displayed on the right side of the ConsoleOne window.

Right click the LDAP group object (not LDAP server), and click Properties from the menu.

Click the Class Map tab and the table of LDAP class names. The Novell eDirectory class names are displayed.

Delete the entries with LDAP classes of inetOrgPerson and groupOfNames.

Click Apply and then click Close.

Click the Attribute Map tab and the table of LDAP attribute names. The Novell eDirectory attribute names are displayed.

Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, then no change is needed. If the attribute is showing the default value of uniqueMember, you need to modify it as follows.

Click Modify. The Attribute Mapping window is displayed.

Change the Primary LDAP Attribute field from uniqueMember to member.

Change the Secondary LDAP attribute field from member to uniqueMember.

In the Attribute window, click OK to accept the changes.

If you are using Solaris, proceed to the next step. If you are using Windows NT, you might have to add another mapping for the LDAP attribute ndsHomeDirectory as follows:

On the right hand side of the Attribute Mappings window, click Add. The Attribute Mapping window repaints and is displayed again.

From the Novell eDirectory NSD Attribute field menu, click Home Directory.

In the Primary LDAP Attribute field, click ndsHomeDirectory.

In the Attribute Mapping window, click OK to accept the changes.

In the Properties window, click OK.

Parent topic: Novell-specific tasks

Updating the eDirectory schema with Novell iManagerIf you install a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured. Novell serverupdating eDirectory schema (iManager)Before you configure the policy server, modify Novell eDirectory with Novell’s ConsoleOne directory management utility or iManager web-based administration console. The default Novell eDirectory schema assumes that the directory does not use the X.500 object classes of inetOrgPerson or groupOfNames. By default, these classes are mapped into the eDirectory classes of User and Group. Because Security Access Manager uses the inetOrgPerson and groupOfNames object classes for creating its own users and groups, modifications to the default eDirectory schema are required.Launch the iManager web page and log on as the administrator for the Novell eDirectory tree to be updated. Click the Roles and Tasks icon at the top of the iManager window to open the Roles and Tasks view.In the Roles and Tasks navigation frame, expand the LDAP category. In the expanded list, click the LDAP Options task.On the LDAP Options page, click the LDAP Group listed. Click Class Map to display the Novell eDirectory class to LDAP class mappings.Remove mappings to inetOrgPerson and groupOfNames. Scroll through the list and look for mappings of eDirectory classes to the LDAP class inetOrgPerson.If a mapping exists, select the row and click the Remove Mapping icon to remove the mapping.Click OK in the pop-up window to confirm the removal of the mapping.Click Apply to apply the changes.Repeat this step to remove a mapping for the LDAP class groupOfNames.Click OK to accept the changes.Repeat steps 3-5 to return to the LDAP Group page.Click Attribute Map to access the Novell eDirectory attribute to LDAP attribute mappings. Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, no change is needed. If the attribute is the default value of uniqueMember, modify it as follows: Select the row and click the View/Edit Mapping icon.Change the Primary LDAP Attribute field from uniqueMember to member.Change the Secondary LDAP attribute field from member to uniqueMember.Click OK in the pop-up window to confirm the change.Click Apply to apply the changes.If you are using Solaris, proceed to the next step. If you are using Windows NT, you might need to add another mapping for the LDAP attribute ndsHomeDirectory. To add another mapping for the LDAP attribute ndsHomeDirectory: Click the Add Mapping icon in the right side of the window. A pop-up window to define the mapping is displayed.In the eDirectory Attribute field, select Home Directory.In the Primary LDAP Attribute field, type ndsHomeDirectory.Click OK to confirm the mapping and close the pop-up window.Click OK in the Attribute Map window to accept the changes.Novell-specific tasksThe Novell eDirectory can be configured as a Security Access Manager user registry.

Updating the eDirectory schema with Novell iManager

If you install a new Security Access Manager secure domain, the Security Access Manager schema is installed automatically on the Novell eDirectory Server (NDS) when the Security Access Manager policy server is configured.

About this task

Before you configure the policy server, modify Novell eDirectory with Novell’s ConsoleOne directory management utility or iManager web-based administration console.

Note: The default Novell eDirectory schema assumes that the directory does not use the X.500 object classes of inetOrgPerson or groupOfNames. By default, these classes are mapped into the eDirectory classes of User and Group. Because Security Access Manager uses the inetOrgPerson and groupOfNames object classes for creating its own users and groups, modifications to the default eDirectory schema are required.

Procedure

Launch the iManager web page and log on as the administrator for the Novell eDirectory tree to be updated.

Click the Roles and Tasks icon at the top of the iManager window to open the Roles and Tasks view.

In the Roles and Tasks navigation frame, expand the LDAP category.

In the expanded list, click the LDAP Options task.

On the LDAP Options page, click the LDAP Group listed.

Click Class Map to display the Novell eDirectory class to LDAP class mappings.

Remove mappings to inetOrgPerson and groupOfNames.

Scroll through the list and look for mappings of eDirectory classes to the LDAP class inetOrgPerson.

If a mapping exists, select the row and click the Remove Mapping icon to remove the mapping.

Click OK in the pop-up window to confirm the removal of the mapping.

Click Apply to apply the changes.

Repeat this step to remove a mapping for the LDAP class groupOfNames.

Click OK to accept the changes.

Repeat steps 3-5 to return to the LDAP Group page.

Click Attribute Map to access the Novell eDirectory attribute to LDAP attribute mappings.

Scroll through the table and find the Novell eDirectory attribute member. Check the value of the corresponding LDAP attribute. If the LDAP attribute value is member, no change is needed. If the attribute is the default value of uniqueMember, modify it as follows:

Select the row and click the View/Edit Mapping icon.

Change the Primary LDAP Attribute field from uniqueMember to member.

Change the Secondary LDAP attribute field from member to uniqueMember.

Click OK in the pop-up window to confirm the change.

Click Apply to apply the changes.

If you are using Solaris, proceed to the next step. If you are using Windows NT, you might need to add another mapping for the LDAP attribute ndsHomeDirectory. To add another mapping for the LDAP attribute ndsHomeDirectory:

Click the Add Mapping icon in the right side of the window. A pop-up window to define the mapping is displayed.

In the eDirectory Attribute field, select Home Directory.

In the Primary LDAP Attribute field, type ndsHomeDirectory.

Click OK to confirm the mapping and close the pop-up window.

Click OK in the Attribute Map window to accept the changes.

Parent topic: Novell-specific tasks

Novell eDirectory maintenance activities that can damage schema modifications applied by Security Access ManagerNovell eDirectory defines the object classes User and Group as part of its base schema.Novell servermaintenance activitiesInstances of these object classes are created by an eDirectory administrator when defining a user or a group. Both of these object classes are defined by eDirectory as leaf nodes. eDirectory adds an attribute X-NDS_NOT_CONTAINER '1' to each of these object class definitions that specifies they are not container objects. Not being a container object means that the objects cannot be defined beneath instances of these object classes.Security Access Manager requires the ability to append its own objects beneath pre-existing eDirectory users and groups to import them and make them usable by Security Access Manager. When Security Access Manager adds its own object class definitions to the eDirectory schema, it also redefines the eDirectory User and Group object classes. Redefinition allows instances of these classes to be container objects. Novell eDirectory allows this change to its schema definition.The following Novell eDirectory administrator actions cause Security Access Manager modification to the User object class to be undone. The Group object class is not affected. Running the eDirectory database repair tool ndsrepair with the rebuild schema option.Running Basic Repair from the iManager console and running local database repair with the rebuild operational schema option.Applying a patch update to Novell eDirectory.Upgrading Novell eDirectory to a more recent version.To do any of these operations after Security Access Manager was configured into the eDirectory server, run the following command immediately. This action ensures that the definition of the User object class is restored.ivrgy_tool(.exe) -h edir_server_name -p port -D edir_admin_dn -w edir_admin_password schemaThe ivrgy_tool utility can be found in one of the following Security Access Manager directories: AIX, Linux, and Solaris operating systems/opt/PolicyDirector/sbin Windows operating systemsc:\program files\tivoli\policy director\sbinSecurity Access Manager does not add the /sbin directory to the system PATH. You must run the ivrgy_tool utility from the /sbin directory.Novell-specific tasksThe Novell eDirectory can be configured as a Security Access Manager user registry.

Novell eDirectory maintenance activities that can damage schema modifications applied by Security Access Manager

Novell eDirectory defines the object classes User and Group as part of its base schema.

Instances of these object classes are created by an eDirectory administrator when defining a user or a group. Both of these object classes are defined by eDirectory as leaf nodes. eDirectory adds an attribute X-NDS_NOT_CONTAINER '1' to each of these object class definitions that specifies they are not container objects. Not being a container object means that the objects cannot be defined beneath instances of these object classes.

Security Access Manager requires the ability to append its own objects beneath pre-existing eDirectory users and groups to import them and make them usable by Security Access Manager. When Security Access Manager adds its own object class definitions to the eDirectory schema, it also redefines the eDirectory User and Group object classes. Redefinition allows instances of these classes to be container objects. Novell eDirectory allows this change to its schema definition.

The following Novell eDirectory administrator actions cause Security Access Manager modification to the User object class to be undone. The Group object class is not affected.

Running the eDirectory database repair tool ndsrepair with the rebuild schema option.

Running Basic Repair from the iManager console and running local database repair with the rebuild operational schema option.

Applying a patch update to Novell eDirectory.

Upgrading Novell eDirectory to a more recent version.

To do any of these operations after Security Access Manager was configured into the eDirectory server, run the following command immediately. This action ensures that the definition of the User object class is restored.

ivrgy_tool(.exe) -h edir_server_name -p port -D edir_admin_dn
-w edir_admin_password schema

The ivrgy_tool utility can be found in one of the following Security Access Manager directories:

AIX, Linux, and Solaris operating systems

/opt/PolicyDirector/sbin

Windows operating systems

c:\program files\tivoli\policy director\sbin

Security Access Manager does not add the /sbin directory to the system PATH. You must run the ivrgy_tool utility from the /sbin directory.

Parent topic: Novell-specific tasks

Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.AdministeringIBM Security Access Manager provides information about administering supported activation levels.Supported Web Reverse Proxy functionalityThe IBM Security Access Manager appliance Web Reverse Proxy functionality is based on the technology included with the IBM Security Access Manager WebSEAL product. The appliance supports the majority of features that are offered by WebSEAL, with the exception of the items contained in the following table:MigrationConfiguration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. Runtime environmentIn the local management interface, go to Secure Web SettingsManageRuntime Component.Users and user registriesReverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics. JunctionsFederation managementUse the local management interface to configure your federations with a reverse proxy server. Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.ClustersPolicy management with Web Portal ManagerWeb Portal Manager is a graphical management console for managing domains, users, groups, permissions, policies, and other resources in your enterprise. The appliance provides an embedded version of Web Portal Manager.Global settingsGlobal keysTrace dataYou can use the local management interface (LMI) to control tracing.LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files. Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.dscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

Web Reverse Proxy administration

IBM® Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.

Supported Web Reverse Proxy functionality
The IBM Security Access Manager appliance Web Reverse Proxy functionality is based on the technology included with the IBM Security Access Manager WebSEAL product. The appliance supports the majority of features that are offered by WebSEAL, with the exception of the items contained in the following table:

Migration

Configuration changes commit process
The LMI uses a two-stage commit process when you make changes to the appliance.

Runtime environment
In the local management interface, go to Secure Web Settings > Manage > Runtime Component.

Users and user registries

Reverse proxy instance management
In the local management interface, go to Secure Web Settings > Manage > Reverse Proxy. A list of all instances and their current states is displayed.

Reverse proxy status
You can use the local management interface (LMI) to manage status and view statistics.

Junctions

Federation management
Use the local management interface to configure your federations with a reverse proxy server.

Authorization servers
To manage IBM Security Access Manager authorization server instances, go to Secure Web Settings > Manage > Authorization Server.

Clusters

Policy management with Web Portal Manager
Web Portal Manager is a graphical management console for managing domains, users, groups, permissions, policies, and other resources in your enterprise. The appliance provides an embedded version of Web Portal Manager.

Global settings

Global keys

Trace data
You can use the local management interface (LMI) to control tracing.

Logging
You can use the local management interface (LMI) to manage the reverse proxy log files.

Front-end load balancer
The appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

dscadmin command
Use the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

Parent topic: Administering

Supported Web Reverse Proxy functionalityWebSEAL functionality on the applianceWebSEAL functionality on the IBM Security Access Manager applianceThe IBM Security Access Manager appliance Web Reverse Proxy functionality is based on the technology included with the IBM Security Access Manager WebSEAL product. The appliance supports the majority of features that are offered by WebSEAL, with the exception of the items contained in the following table:WebSEALfunctionalityWeb Reverse Proxysupported featuresfunctionalityfunctionalityIBM Security Access ManagerappliancesSecurity Access ManagerappliancesCDAScustom librariesWebSEAL features that the appliance does not supportFeatureDescriptionCustom libraries, including CDAS and EASThe appliance does not support custom CDAS modules. As a result, the appliance does not support the following authentication mechanisms:IP addressHTTP headerPost password changeWebSEAL does not provide CDAS modules for these mechanisms.The appliance does support the IBM Security Identity Manager Password Synchronization Plug-in. For more information, see the [itim] stanza in the Stanza Reference topics in the Knowledge Center.Local junctionsThe following limitations apply to local junction support on the appliance: The appliance can support a single fixed file system path for the local junction of a WebSEAL instance. Local junctions on the appliance cannot execute any CGI scripts.Hardware Based CryptographyThe appliance supports the following network Hardware Security Module (HSM) devices: Thales nShield ConnectSafeNet Luna SA v5.xApplication Response Measurement (ARM)WebSEAL software includes support for ARM to monitor transactions throughout the request and response processing stream. The appliance does not include ARM support. Tivoli Common Directory Logging The Tivoli Common Directory Logging feature stores all log files for IBM Security software applications in a common file system directory. The appliance does not support this common logging. Logging for the appliance is managed through the LMI. Auditing to a pipe or CARSThe appliance cannot send audit records directly to a pipe or a CARS server. It can however, use an intermediate ISAM authorization server to indirectly send audit records to the destinations.ARS (web service)The IBM Security Access Manager for Web ARS web service can send request information to an external ARS server for authorization. ARS is not available on the appliance.Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.

Supported Web Reverse Proxy functionality

The IBM Security Access Manager appliance Web Reverse Proxy functionality is based on the technology included with the IBM Security Access Manager WebSEAL product. The appliance supports the majority of features that are offered by WebSEAL, with the exception of the items contained in the following table:

Table 187. WebSEAL features that the appliance does not support.

Feature
Description

Custom libraries, including CDAS and EAS
The appliance does not support custom CDAS modules. As a result, the appliance does not support the following authentication mechanisms:

IP address

HTTP header

Post password change

WebSEAL does not provide CDAS modules for these mechanisms.

Note: The appliance does support the IBM Security Identity Manager Password Synchronization Plug-in. For more information, see the [itim] stanza in the Stanza Reference topics in the Knowledge Center.

Local junctions
The following limitations apply to local junction support on the appliance:

The appliance can support a single fixed file system path for the local junction of a WebSEAL instance.

Local junctions on the appliance cannot execute any CGI scripts.

Hardware Based Cryptography
The appliance supports the following network Hardware Security Module (HSM) devices:

Thales nShield Connect

SafeNet Luna SA v5.x

Application Response Measurement (ARM)

WebSEAL software includes support for ARM to monitor transactions throughout the request and response processing stream. The appliance does not include ARM support.

Tivoli® Common Directory Logging
The Tivoli Common Directory Logging feature stores all log files for IBM® Security software applications in a common file system directory. The appliance does not support this common logging. Logging for the appliance is managed through the LMI.

Auditing to a pipe or CARS
The appliance cannot send audit records directly to a pipe or a CARS server. It can however, use an intermediate ISAM authorization server to indirectly send audit records to the destinations.

ARS (web service)
The IBM Security Access Manager for Web ARS web service can send request information to an external ARS server for authorization. ARS is not available on the appliance.

Parent topic: Web Reverse Proxy administration

MigrationWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Migrating an existing WebSEAL instance to the applianceYou can migrate an existing WebSEAL instance to the appliance. Migrating an existing Security Access Manager environment to the applianceYou can migrate an existing Security Access Manager environment to the appliance with the provided mechanism.

Migration

Migrating an existing WebSEAL instance to the appliance
You can migrate an existing WebSEAL instance to the appliance.

Migrating an existing Security Access Manager environment to the appliance
You can migrate an existing Security Access Manager environment to the appliance with the provided mechanism.

Parent topic: Web Reverse Proxy administration

Migrating an existing WebSEAL instance to the applianceYou can migrate an existing WebSEAL instance to the appliance. Custom CDAS or EAS libraries are not supported. Make sure that there is no dependency on custom CDAS or EAS libraries before you start to migrate the system. For example, any custom CDAS processing must be converted to an EAI. Local junctions are supported, but a fixed location is used as the document root. A local junction is also not permitted to run any CGI scripts. It can serve only static page content. Any CGI scripts must be migrated to a remote server. The appliance supports only a single local junction. The content for all other local junctions (if any) must also be migrated to a remote server.As part of the migration process, you must collect the files that are necessary for the migration. You can use either of the following methods to collect the necessary files: Run the provided Perl script (wga_migrate.pl) to automatically collect the necessary files. A Perl utility is provided to help facilitate the collection of files that are required by the WebSEAL instance. This utility can process the configuration for the specified WebSEAL instance. It can also copy the necessary files into the directory structure that is required by the import facility of the appliance. To set up and run this utility, follow these steps: In the appliance top menu, go to Manage System SettingsFile Downloads.Under commonmigrate, select the wga_migrate.pl file to download it.Copy the script to the WebSEAL server.Ensure that Perl is installed and available on the WebSEAL server.Locate the name of the configuration file for the WebSEAL instance that is to be migrated.Run the wga_migrate.pl script, specifying the name of the WebSEAL configuration file and the destination directory. Use the following format for the script:perl wga_migrate.pl [-c config-file] [-d dst-dir] {-v}-c config-fileThe name of the WebSEAL configuration file.d dst-dirThe name of the destination directory. This directory must not exist on the file system.-vDisplay more status messages during the execution of the script.For example, use the following script: perl wga_migrate.pl -c /var/pdweb/etc/webseald-default.conf -d /tmp/migrate_outReview the files that are contained within the destination directory to ensure that all of the necessary files are located. Manually create the directory structure and copy the files to those directories.On the source WebSEAL server, create the directory structure of configuration files, as defined in the following table. Only those directories for which files are to be migrated must be created. Create these directories as subdirectories under a single source directory.Directory structureDirectoryDescriptiondynurlDynamic URL configuration files. fssoForms-Based Single Sign-on configuration files.jmtJunction Mapping Table configuration files.keytabThe key database (kdb/sth) files that are used by the WebSEAL instance. The files do not include the keyfile that is used to communicate with the policy server.ltpa-keysLTPA key files.tam-keysKey files that are generated with the cdsso-key-gen utility. They are used for things such as encrypting the failover cookie.xslt/user-map-cdasXSLT configuration file that is used by the client certificate user mapping CDAS.xslt/http-transformationXSLT configuration file that is used by the HTTP transformation rules function.doc-root/docsThe files that are served by the WebSEAL local junction. These files are typically located under the /opt/pdweb/www-<instance>/lib/docs directory.doc-root/errorsThe error pages that are served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/errors directory.doc-root/htmlThe management HTML pages (for example, login.html) which are served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/html directory.doc-root/oauthThe OAuth response files, as defined within the [oauth-eas] stanza of the WebSEAL configuration file.junctionsThe XML files that contain the junction definitions for the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/jct directory.etcThe configuration files that are used by the WebSEAL instance. In particular, the routing file, the webseald-<instance>.conf, and the webseald-<instance>.conf.obf files.When you create the directory structure, additional subdirectories are not supported for any directory other than the doc-root ones (doc-root/docs, doc-root/errors, doc-root/html, doc-root/oauth). For example, you can create a directory structure such as /doc-root/error/<folder>/<file>, but a structure such as xslt/http-transformation/<folder>/<file> is not valid. For directories other than the doc-root ones, files can be placed only in the default root directories that are listed in Table 1. For example, xslt/http-transformation/<file>.All files to be copied must have unique file names. If two files have the same name, the migration tool copies only the first file that matches the name. For example, you might have the following structure:[http-transformation] request_pop1 = <path1>/pop1.xsl response_pop1 = <path2>/pop1.xslOnly <path1>/pop1.xsl are created in the directory structure. All references to <path1>/pop1.xsl and <path2>/pop1.xsl in the configuration file are reduced to pop1.xsl, which now points to the same file.The WebSEAL configuration file must be included in the set of configuration files to be migrated. The obfuscated configuration file, as defined by the [configuration-database] stanza and file configuration entry, must also be included. Modify the copied WebSEAL configuration file so that any configuration entries that are not applicable to the new WebSEAL instance are removed. Examples of entries that you might potentially not want to migrate would include network settings. The following configuration entries are ignored when the configuration file is imported into the appliance: token-card configuration entry from the [authentication-levels] stanzaserver-name configuration entry from the [server] stanzanetwork-interface configuration entry from the [server] stanza[interfaces] configuration stanzaCreate a compressed file, with the contents relative to the location that contains the copied files. For example, on a UNIX system, if the directory structure was created in /tmp/migrate, the command would be: cd /tmp/migrate; zip -r /tmp/migrate.zip * Migration is supported for the following versions: IBM Tivoli Access Manager Version 6.1 and laterIBM Security Access Manager Version 7.0 and later Create a WebSEAL instance on the appliance with the local management interface.Import the migration compressed file. If you are warned that files might be overwritten as a part of the import operation, you must validate the overwrite operation before you can continue. Make sure that the overwrite operation does not affect any other WebSEAL instances that might be running on the appliance. For detailed steps when you import with the local management interface, see Import the contents of a compressed file into the administration pages root. If the appliance is a non-primary node in a clustered environment, and you enabled replication of SSL certificates in the cluster, first manually import the required SSL key files into the primary node and wait for these certificates to be replicated to the non-primary node. After the replication is complete, you can then import the WebSEAL configuration bundle into the non-primary node. If you do not follow this procedure in this type of environment and instead import the WebSEAL configuration directly on the non-primary node, the certificates from the WebSEAL configuration compressed file might be replaced during the next replication event by the certificates from the primary master and this will cause deployment issues. Deploy the changes.Restart the WebSEAL instance.Examine the WebSEAL log file for any potential migration issues.Migration

Migrating an existing WebSEAL instance to the appliance

You can migrate an existing WebSEAL instance to the appliance.

Before you begin

Custom CDAS or EAS libraries are not supported. Make sure that there is no dependency on custom CDAS or EAS libraries before you start to migrate the system. For example, any custom CDAS processing must be converted to an EAI.

Local junctions are supported, but a fixed location is used as the document root. A local junction is also not permitted to run any CGI scripts. It can serve only static page content. Any CGI scripts must be migrated to a remote server. The appliance supports only a single local junction. The content for all other local junctions (if any) must also be migrated to a remote server.

As part of the migration process, you must collect the files that are necessary for the migration. You can use either of the following methods to collect the necessary files:

Run the provided Perl script (wga_migrate.pl) to automatically collect the necessary files.

A Perl utility is provided to help facilitate the collection of files that are required by the WebSEAL instance. This utility can process the configuration for the specified WebSEAL instance. It can also copy the necessary files into the directory structure that is required by the import facility of the appliance.

To set up and run this utility, follow these steps:

In the appliance top menu, go to Manage System Settings > File Downloads.

Under common > migrate, select the wga_migrate.pl file to download it.

Copy the script to the WebSEAL server.

Ensure that Perl is installed and available on the WebSEAL server.

Locate the name of the configuration file for the WebSEAL instance that is to be migrated.

Run the wga_migrate.pl script, specifying the name of the WebSEAL configuration file and the destination directory. Use the following format for the script:

perl wga_migrate.pl [-c config-file] [-d dst-dir] {-v}

-c config-file

The name of the WebSEAL configuration file.

d dst-dir

The name of the destination directory. This directory must not exist on the file system.

-v

Display more status messages during the execution of the script.

For example, use the following script:

perl wga_migrate.pl -c /var/pdweb/etc/webseald-default.conf
-d /tmp/migrate_out

Review the files that are contained within the destination directory to ensure that all of the necessary files are located.

Manually create the directory structure and copy the files to those directories.

On the source WebSEAL server, create the directory structure of configuration files, as defined in the following table. Only those directories for which files are to be migrated must be created. Create these directories as subdirectories under a single source directory.

Table 188. Directory structure

Directory
Description

dynurl
Dynamic URL configuration files.

fsso
Forms-Based Single Sign-on configuration files.

jmt
Junction Mapping Table configuration files.

keytab
The key database (kdb/sth) files that are used by the WebSEAL instance. The files do not include the keyfile that is used to communicate with the policy server.

ltpa-keys
LTPA key files.

tam-keys
Key files that are generated with the cdsso-key-gen utility. They are used for things such as encrypting the failover cookie.

xslt/user-map-cdas
XSLT configuration file that is used by the client certificate user mapping CDAS.

xslt/http-transformation
XSLT configuration file that is used by the HTTP transformation rules function.

doc-root/docs

The files that are served by the WebSEAL local junction. These files are typically located under the /opt/pdweb/www-<instance>/lib/docs directory.

doc-root/errors
The error pages that are served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/errors directory.

doc-root/html
The management HTML pages (for example, login.html) which are served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/html directory.

doc-root/oauth
The OAuth response files, as defined within the [oauth-eas] stanza of the WebSEAL configuration file.

junctions
The XML files that contain the junction definitions for the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/jct directory.

etc
The configuration files that are used by the WebSEAL instance. In particular, the routing file, the webseald-<instance>.conf, and the webseald-<instance>.conf.obf files.

Note: When you create the directory structure, additional subdirectories are not supported for any directory other than the doc-root ones (doc-root/docs, doc-root/errors, doc-root/html, doc-root/oauth). For example, you can create a directory structure such as /doc-root/error/<folder>/<file>, but a structure such as xslt/http-transformation/<folder>/<file> is not valid. For directories other than the doc-root ones, files can be placed only in the default root directories that are listed in Table 188. For example, xslt/http-transformation/<file>.

Note: All files to be copied must have unique file names. If two files have the same name, the migration tool copies only the first file that matches the name. For example, you might have the following structure:

[http-transformation]
request_pop1 = <path1>/pop1.xsl
response_pop1 = <path2>/pop1.xsl

Only <path1>/pop1.xsl are created in the directory structure. All references to <path1>/pop1.xsl and <path2>/pop1.xsl in the configuration file are reduced to pop1.xsl, which now points to the same file.

The WebSEAL configuration file must be included in the set of configuration files to be migrated. The obfuscated configuration file, as defined by the [configuration-database] stanza and file configuration entry, must also be included.

Modify the copied WebSEAL configuration file so that any configuration entries that are not applicable to the new WebSEAL instance are removed. Examples of entries that you might potentially not want to migrate would include network settings. The following configuration entries are ignored when the configuration file is imported into the appliance:

token-card configuration entry from the [authentication-levels] stanza

server-name configuration entry from the [server] stanza

network-interface configuration entry from the [server] stanza

[interfaces] configuration stanza

Create a compressed file, with the contents relative to the location that contains the copied files. For example, on a UNIX system, if the directory structure was created in /tmp/migrate, the command would be:

cd /tmp/migrate; zip -r /tmp/migrate.zip *

About this task

Migration is supported for the following versions:

IBM Tivoli Access Manager Version 6.1 and later

IBM Security Access Manager Version 7.0 and later

Procedure

Create a WebSEAL instance on the appliance with the local management interface.

Import the migration compressed file.

Note:

If you are warned that files might be overwritten as a part of the import operation, you must validate the overwrite operation before you can continue. Make sure that the overwrite operation does not affect any other WebSEAL instances that might be running on the appliance. For detailed steps when you import with the local management interface, see Import the contents of a compressed file into the administration pages root.

If the appliance is a non-primary node in a clustered environment, and you enabled replication of SSL certificates in the cluster, first manually import the required SSL key files into the primary node and wait for these certificates to be replicated to the non-primary node. After the replication is complete, you can then import the WebSEAL configuration bundle into the non-primary node. If you do not follow this procedure in this type of environment and instead import the WebSEAL configuration directly on the non-primary node, the certificates from the WebSEAL configuration compressed file might be replaced during the next replication event by the certificates from the primary master and this will cause deployment issues.

Deploy the changes.

Restart the WebSEAL instance.

Examine the WebSEAL log file for any potential migration issues.

Parent topic: Migration

Migrating an existing Security Access Manager environment to the applianceYou can migrate an existing Security Access Manager environment to the appliance with the provided mechanism. migrationSecurity Access Managerisam_migrate.plSecurity Access Managermigrationappliancesmigrationchangesmigrationcomponentscommand-line toolsdatabasesauthorizationmetadatastorageuser registriesActive DirectoryTo achieve the migration, ensure that Perl is installed and available on the policy server to be migrated. To migrate from an environment that is using Active Directory as the user registry, ensure that:IBM Directory Server client is installed on the policy server.The AD DS Snap-Ins and Command-Line Tools component is available on the policy server.The appliance provides a Perl script to help with the collection of files that are necessary for the migration. These files include the IBM Security Access Manager configuration files, key files, and the authorization database.Such migration is supported for the following versions:IBM Tivoli Access Manager Version 6.1 and laterIBM Security Access Manager Version 7.0 and laterIn the appliance top menu, go to Manage System SettingsFile Downloads.Under commonmigrate, select the isam_migrate.pl file to download it. This file is a Perl utility to help facilitate the collection of files that are required by the migration.Copy the isam_migrate.pl file to the existing Security Access Manager environment.Run the isam_migrate.pl script, specifying the location of the runtime environment and policy server configuration path.perl isam_migrate.pl [-c <config-path>] [-d <working-dir>] [-o <zip-file>] {-v}-c <config-path>The path of the IBM Security Access Manager configuration files.-d <working-dir>The name of the working directory. This directory must not exist on the file system.-o <zip-file>The name of the configuration bundle .zip file to produce. This file must not exist on the file system.-vDisplay more status messages during the execution of the script.The following script is an example:perl isam_migrate.pl -c /opt/PolicyDirector/etc/ -d /tmp/isam -o /tmp/isam.zip -vIn most situations, the existing user registry is used by the migrated policy server. An exception to this situation is the environment where Active Directory is used as the user registry. In this situation, the Security Access Manager metadata must be migrated from the existing user registry to a new user registry. The isam_migrate.pl utility also provides this capability.To migrate from a Windows computer that runs the Security Access Manager policy server, that uses Active Directory as the user registry, you can use the following commands:-U Unconfigure the old Active Directory policy server. This parameter is used to clean up the Security Access Manager user data from the Active Directory server after the data is migrated. -i The user registry that is embedded in the appliance is used by the policy server. If this parameter is not present, then the LDAP server is external to the destination appliance. -h <ldap-host>The host name of the user registry against which the policy server is configured. This option is not required if the -i option is used. -p <ldap-port>The port of the user registry against which the policy server is configured. This option is not required if the -i option is used. -sIf this parameter is present, then SSL is used by the policy server when it is communicating with the external user registry. This option is not required if the -i option is used. -D <ldap-admin-dn>The distinguished name of the administrator of the external user registry that is used. This option is not required if the -i option is used. -a <authority-suffix>The LDAP suffix that is used to hold the Security Access Manager secAuthority data. This option is not required if the -i option is used. -w <ldap-pwd>The password for the administrator of the external or internal user registry. -b Migrate the users as Security Access Manager basic users. -k <keyfile>A GSKit CMS keyfile that contains the Active Directory CA certificate. If the option -i was not supplied and -s was supplied, then it must also contain the external LDAP server SSL CA certificate. -W <keyfile-pwd>The password for the specified keyfile. -f <usergroup-ldif-file>The file that stores all non-system user and group metadata in LDIF format. This file must be added after the policy server is migrated.This file is not used for the migration on the appliance. Do not include this file in the <zip-file>.Generate a migration .zip file that can be used to configure a policy server on the appliance with the embedded LDAP server.perl isam_migrate.pl -i -c <config-path> [-v] -d <working-dir> -o <zip-file> -w <ldap-pwd> [-b ] -f <usergroup-ldif-file> -k <keyfile> -W <keyfile-pwd>As an example, use the following set of assumptions:The user is logged in to the Active Directory machine that is running the policy server and has administrative access to Active Directory.Perl is installed into the directory C:\perl.The isam_migrate.pl file is in C:\.The current working directory is C:\.A temporary directory is created: C:\tmp.The appliance has the default LDAP administrator password of passw0rd.The Active Directory signer certificate is placed in the GSKit CMS file C:\adkeyfile.kdb with the password passw0rd.The destination uses full Security Access Manager users, not basic users. The -b option is not provided.The following command is based on the list of assumptions:C:\perl\bin\perl.exe isam_migrate.pl -i -c "C:\Program Files\Tivoli \Policy Director\etc" -d "C:\tmp\mig" -o "C:\tmp\migrate.zip" -w passw0rd -k "C:\adkeyfile.kdb" -W passw0rd -f "C:\tmp\usergroup.ldif"Generate a migration .zip file that can be used to configure a policy server on the appliance with an external LDAP server.perl isam_migrate.pl -c <config-path> [-v] -d <working-dir> -o <zip-file> -w <ldap-pwd> [-b ] -f <usergroup-ldif-file> -k <keyfile> -W <keyfile-pwd> -h <ldap-host> -p <ldap-port> [-s] -D <ldap-admin-dn> [-a <authority-suffix>]As an example, use the following set of assumptions:The user is logged in to the Active Directory machine that is running the policy server and has administrative access to Active Directory.Perl is installed into the directory C:\perl.The isam_migrate.pl file is in C:\.The current working directory is C:\.A temporary directory is created: C:\tmp.The external LDAP server administrator is cn=root with password of passw0rd.The Active Directory signer certificate is placed in the GSKit CMS file C:\adextkeyfile.kdb with the password passw0rd.The external LDAP server, host name of extldap.ibm.com, requires SSL access on port 636 and its signer certificate is placed in C:\adextkeyfile.kdb.The external LDAP server has a suffix secAuthority=Default at which the Security Access Manager metadata is placed.The destination uses full Security Access Manager users, not basic users. The -b option is not provided.The following command is based on the list of assumptions:C:\perl\bin\perl.exe isam_migrate.pl -c "C:\Program Files\Tivoli \Policy Director\etc" -d "C:\tmp\mig" -o "C:\tmp\migrate.zip" -D "cn=root" -w passw0rd -h extldap.ibm.com -p 636 -s -k "C:\adextkeyfile.kdb" -W passw0rd -f "C:\tmp\usergroup.ldif"Unconfigure the Active Directory server. This command is used to clean up the Security Access Manager user data from the Active Directory server after the data is migrated.perl isam_migrate.pl -U -c <config-path> [-v]Use this unconfigure command only after you finish generating the migration .zip file.As an example, use the following set of assumptions:The user is logged in to the Active Directory machine that is running the policy server and has administrative access to Active Directory and the local machine.Perl is installed into the directory C:\perl.The isam_migrate.pl file is in C:\.The current working directory is C:\.The following command is based on the list of assumptions:C:\perl\bin\perl.exe isam_migrate.pl -U -c "C:\Program Files\Tivoli\Policy Director\etc"If a compressed file is not automatically created on your platform, create a compressed file where the contents are relative to the location that contains the copied files. For example, on a UNIX system, if the directory structure was created in /tmp/isam, the command would be: cd /tmp/isam; zip -r /tmp/isam.zip *In the destination appliance's local management console, import the compressed file created in the previous step. Go to Secure Web SettingsManage Runtime Component.Click Configure.Click Import.In the pop-up window, click Browse.Select the compressed file that contains the necessary migration files.Click Import.Deploy the changes.If you are migrating from an environment that uses a local LDAP server, you might need to manually change the host values (localhost) in the pd.conf and ldap.conf files to IP addresses that suit your new environment.The behavior of "[ssl] ssl-v3-enable" in pd.conf changed after version 6.1.1. It now provides the default for all other Security Access Manager servers on the same machine, unless their .conf file explicitly sets its value. Previously this option only affected the pdadmin command. So if "[ssl] ssl-v3-enable = yes" is set in the migrated pd.conf, and is not explicitly set in the migrated ivmgrd.conf file, then the policy server starts with SSLv3 enabled. To obtain the behavior before migration, add "[ssl] ssl-v3-enable = no" into the ivmgrd.conf file. It would be better to not use SSLv3 at all and set "[ssl] ssl-v3-enable = no" in the migrated pd.conf file.If you want to add the <usergroup-ldif-file> after migration, you must apply this file to the LDAP server that is used by the new policy server by using an LDIF tool. For example, use the following ldapadd command:/opt/ibm/ldap/V6.3/bin/ldapadd -h <ldap-host> -p <ldap-port> -D <ldap-admin-dn>        -w <ldap-pwd> -K <keyfile> -P <keyfile-pwd> -Z -i <usergroup-ldif-file>Migration

Migrating an existing Security Access Manager environment to the appliance

You can migrate an existing Security Access Manager environment to the appliance with the provided mechanism.

Before you begin

To achieve the migration, ensure that Perl is installed and available on the policy server to be migrated.

To migrate from an environment that is using Active Directory as the user registry, ensure that:

IBM® Directory Server client is installed on the policy server.

The AD DS Snap-Ins and Command-Line Tools component is available on the policy server.

The appliance provides a Perl script to help with the collection of files that are necessary for the migration. These files include the IBM Security Access Manager configuration files, key files, and the authorization database.

Note: Such migration is supported for the following versions:

IBM Tivoli® Access Manager Version 6.1 and later

IBM Security Access Manager Version 7.0 and later

Procedure

In the appliance top menu, go to Manage System Settings > File Downloads.

Under common > migrate, select the isam_migrate.pl file to download it. This file is a Perl utility to help facilitate the collection of files that are required by the migration.

Copy the isam_migrate.pl file to the existing Security Access Manager environment.

Run the isam_migrate.pl script, specifying the location of the runtime environment and policy server configuration path.

perl isam_migrate.pl [-c <config-path>] [-d <working-dir>] [-o <zip-file>] {-v}

-c <config-path>

The path of the IBM Security Access Manager configuration files.

-d <working-dir>

The name of the working directory. This directory must not exist on the file system.

-o <zip-file>

The name of the configuration bundle .zip file to produce. This file must not exist on the file system.

-v

Display more status messages during the execution of the script.

The following script is an example:

perl isam_migrate.pl -c /opt/PolicyDirector/etc/ -d /tmp/isam -o /tmp/isam.zip -v

Note: In most situations, the existing user registry is used by the migrated policy server. An exception to this situation is the environment where Active Directory is used as the user registry. In this situation, the Security Access Manager metadata must be migrated from the existing user registry to a new user registry. The isam_migrate.pl utility also provides this capability.

To migrate from a Windows computer that runs the Security Access Manager policy server, that uses Active Directory as the user registry, you can use the following commands:

-U

Unconfigure the old Active Directory policy server. This parameter is used to clean up the Security Access Manager user data from the Active Directory server after the data is migrated.

-i

The user registry that is embedded in the appliance is used by the policy server. If this parameter is not present, then the LDAP server is external to the destination appliance.

-h <ldap-host>

The host name of the user registry against which the policy server is configured. This option is not required if the "-i" option is used.

-p <ldap-port>

The port of the user registry against which the policy server is configured. This option is not required if the "-i" option is used.

-s

If this parameter is present, then SSL is used by the policy server when it is communicating with the external user registry. This option is not required if the "-i" option is used.

-D <ldap-admin-dn>

The distinguished name of the administrator of the external user registry that is used. This option is not required if the "-i" option is used.

-a <authority-suffix>

The LDAP suffix that is used to hold the Security Access Manager secAuthority data. This option is not required if the "-i" option is used.

-w <ldap-pwd>

The password for the administrator of the external or internal user registry.

-b

Migrate the users as Security Access Manager basic users.

-k <keyfile>

A GSKit CMS keyfile that contains the Active Directory CA certificate. If the option "-i" was not supplied and "-s" was supplied, then it must also contain the external LDAP server SSL CA certificate.

-W <keyfile-pwd>

The password for the specified keyfile.

-f <usergroup-ldif-file>

The file that stores all non-system user and group metadata in LDIF format. This file must be added after the policy server is migrated.

Note: This file is not used for the migration on the appliance. Do not include this file in the <zip-file>.

Generate a migration .zip file that can be used to configure a policy server on the appliance with the embedded LDAP server.

perl isam_migrate.pl -i -c <config-path> [-v] -d <working-dir>
-o <zip-file> -w <ldap-pwd> [-b ] -f <usergroup-ldif-file> -k <keyfile> -W <keyfile-pwd>

As an example, use the following set of assumptions:

The user is logged in to the Active Directory machine that is running the policy server and has administrative access to Active Directory.

Perl is installed into the directory C:\perl.

The isam_migrate.pl file is in C:\.

The current working directory is C:\.

A temporary directory is created: C:\tmp.

The appliance has the default LDAP administrator password of "passw0rd".

The Active Directory signer certificate is placed in the GSKit CMS file C:\adkeyfile.kdb with the password "passw0rd".

The destination uses full Security Access Manager users, not basic users. The -b option is not provided.

The following command is based on the list of assumptions:

C:\perl\bin\perl.exe isam_migrate.pl -i -c "C:\Program Files\Tivoli
\Policy Director\etc" -d "C:\tmp\mig" -o "C:\tmp\migrate.zip"
-w passw0rd -k "C:\adkeyfile.kdb" -W passw0rd -f "C:\tmp\usergroup.ldif"

Generate a migration .zip file that can be used to configure a policy server on the appliance with an external LDAP server.

perl isam_migrate.pl -c <config-path> [-v] -d <working-dir>
-o <zip-file> -w <ldap-pwd> [-b ] -f <usergroup-ldif-file> -k <keyfile> -W <keyfile-pwd>
-h <ldap-host> -p <ldap-port> [-s] -D <ldap-admin-dn> [-a <authority-suffix>]

As an example, use the following set of assumptions:

The user is logged in to the Active Directory machine that is running the policy server and has administrative access to Active Directory.

Perl is installed into the directory C:\perl.

The isam_migrate.pl file is in C:\.

The current working directory is C:\.

A temporary directory is created: C:\tmp.

The external LDAP server administrator is "cn=root" with password of "passw0rd".

The Active Directory signer certificate is placed in the GSKit CMS file C:\adextkeyfile.kdb with the password "passw0rd".

The external LDAP server, host name of extldap.ibm.com, requires SSL access on port 636 and its signer certificate is placed in C:\adextkeyfile.kdb.

The external LDAP server has a suffix "secAuthority=Default" at which the Security Access Manager metadata is placed.

The destination uses full Security Access Manager users, not basic users. The -b option is not provided.

The following command is based on the list of assumptions:

C:\perl\bin\perl.exe isam_migrate.pl -c "C:\Program Files\Tivoli
\Policy Director\etc" -d "C:\tmp\mig" -o "C:\tmp\migrate.zip"
-D "cn=root" -w passw0rd -h extldap.ibm.com -p 636 -s
-k "C:\adextkeyfile.kdb" -W passw0rd -f "C:\tmp\usergroup.ldif"

Unconfigure the Active Directory server. This command is used to clean up the Security Access Manager user data from the Active Directory server after the data is migrated.

perl isam_migrate.pl -U -c <config-path> [-v]

Note: Use this unconfigure command only after you finish generating the migration .zip file.

As an example, use the following set of assumptions:

The user is logged in to the Active Directory machine that is running the policy server and has administrative access to Active Directory and the local machine.

Perl is installed into the directory C:\perl.

The isam_migrate.pl file is in C:\.

The current working directory is C:\.

The following command is based on the list of assumptions:

C:\perl\bin\perl.exe isam_migrate.pl -U -c
"C:\Program Files\Tivoli\Policy Director\etc"

If a compressed file is not automatically created on your platform, create a compressed file where the contents are relative to the location that contains the copied files. For example, on a UNIX system, if the directory structure was created in /tmp/isam, the command would be:

cd /tmp/isam; zip -r /tmp/isam.zip *

In the destination appliance's local management console, import the compressed file created in the previous step.

Go to Secure Web Settings > Manage > Runtime Component.

Click Configure.

Click Import.

In the pop-up window, click Browse.

Select the compressed file that contains the necessary migration files.

Click Import.

Deploy the changes.

Note:

If you are migrating from an environment that uses a local LDAP server, you might need to manually change the host values (localhost) in the pd.conf and ldap.conf files to IP addresses that suit your new environment.

The behavior of "[ssl] ssl-v3-enable" in pd.conf changed after version 6.1.1. It now provides the default for all other Security Access Manager servers on the same machine, unless their .conf file explicitly sets its value. Previously this option only affected the pdadmin command. So if "[ssl] ssl-v3-enable = yes" is set in the migrated pd.conf, and is not explicitly set in the migrated ivmgrd.conf file, then the policy server starts with SSLv3 enabled. To obtain the behavior before migration, add "[ssl] ssl-v3-enable = no" into the ivmgrd.conf file. It would be better to not use SSLv3 at all and set "[ssl] ssl-v3-enable = no" in the migrated pd.conf file.

What to do next

If you want to add the <usergroup-ldif-file> after migration, you must apply this file to the LDAP server that is used by the new policy server by using an LDIF tool.

For example, use the following ldapadd command:

/opt/ibm/ldap/V6.3/bin/ldapadd -h <ldap-host> -p <ldap-port> -D <ldap-admin-dn>
-w <ldap-pwd> -K <keyfile> -P <keyfile-pwd> -Z -i <usergroup-ldif-file>

Parent topic: Migration

Runtime environmentIn the local management interface, go to Secure Web SettingsManageRuntime Component.runtimecomponentscomponentsruntimeWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Stopping, starting, or restarting the runtime environmentAfter you change the runtime configuration, you must restart the runtime environment to apply the changes.Configuring the runtime environmentTo configure the runtime environment with the local management interface, use the Runtime Component management page.Unconfiguring the runtime environmentTo unconfigure the runtime environment component of the appliance with the local management interface, use the Runtime Component management page.Managing runtime configuration filesTo manage configuration files with the local management interface, use the Runtime Component management page.Configuring JVM debugging for the runtime profileEnable JVM debugging for the runtime profile so that you can debug new Java extension points.

Runtime environment

In the local management interface, go to Secure Web Settings > Manage > Runtime Component.

Stopping, starting, or restarting the runtime environment
After you change the runtime configuration, you must restart the runtime environment to apply the changes.

Configuring the runtime environment
To configure the runtime environment with the local management interface, use the Runtime Component management page.

Unconfiguring the runtime environment
To unconfigure the runtime environment component of the appliance with the local management interface, use the Runtime Component management page.

Managing runtime configuration files
To manage configuration files with the local management interface, use the Runtime Component management page.

Configuring JVM debugging for the runtime profile
Enable JVM debugging for the runtime profile so that you can debug new Java™ extension points.

Parent topic: Web Reverse Proxy administration

Stopping, starting, or restarting the runtime environmentStopping, starting, or restarting the runtime environmentAccess Manager Appliance: Stopping, starting, or restarting the runtime environmentAfter you change the runtime configuration, you must restart the runtime environment to apply the changes.runtimestartingstoppingrestartingapplying changeschangesruntime configurationpolicy serversmanagementuser registrieslog filesFrom the top menu, select Secure Web SettingsManageRuntime Component.Information about the status and the mode of the runtime environment is displayed.If the runtime environment is configured as either local stand-alone or remote stand-alone mode, you can stop, start, or restart it with this management page. Otherwise, the Stop, Start, and Restart buttons are disabled.Depending on your needs, choose to stop, start, or restart the runtime environment.To stop the runtime environment, click Stop.To start the runtime environment, click Start.To restart the runtime environment, click Restart.The records of these operations are logged to the policy server log files and user registry log files.To manage the policy server and user registry log files, click the Go to Application Log Files to view the Policy Server and User Registry log files link. You can also access these log files by selecting Monitor Analysis and DiagnosticsApplication Log Files from the top menu.Relevant entries can be found under isam_runtime/policy_server and isam_runtime/user_registry.Runtime environmentIn the local management interface, go to Secure Web SettingsManageRuntime Component.

Stopping, starting, or restarting the runtime environment

After you change the runtime configuration, you must restart the runtime environment to apply the changes.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component. Information about the status and the mode of the runtime environment is displayed.

Note: If the runtime environment is configured as either local stand-alone or remote stand-alone mode, you can stop, start, or restart it with this management page. Otherwise, the Stop, Start, and Restart buttons are disabled.

Depending on your needs, choose to stop, start, or restart the runtime environment.

To stop the runtime environment, click Stop.

To start the runtime environment, click Start.

To restart the runtime environment, click Restart.

The records of these operations are logged to the policy server log files and user registry log files.

Optional: To manage the policy server and user registry log files, click the Go to Application Log Files to view the Policy Server and User Registry log files link. You can also access these log files by selecting Monitor Analysis and Diagnostics > Application Log Files from the top menu. Relevant entries can be found under isam_runtime/policy_server and isam_runtime/user_registry.

Parent topic: Runtime environment

Configuring the runtime environmentConfiguring the runtime environmentAccess Manager Appliance: Configuring the runtime environmentTo configure the runtime environment with the local management interface, use the Runtime Component management page.runtimeconfigurationpolicy serverslocalremoteconfigurationserverspoliciesSSLLDAPdomainsmanagementconfigurationdatabasescertificatesDNLDAPdistringuised nameDNLDAPuser registriesremotelocalserversuser registriesentrieslocalFrom the top menu, select Secure Web SettingsManage Runtime Component.Click Configure.You can configure your policy server to be local or remote.Local policy server with a remote LDAP user registryUnder Policy Server, select Local.Under User Registry, select LDAP Remote.Click Next.On the Policy Server tab, provide settings for the fields displayed. Fields with an asterisk are required and must be completed.Management Suffix: The LDAP suffix that is used to hold the IBM Security Access Manager secAuthority data. To create the domain at the secAuthority=Default tree, you must leave this field blank.Management Domain: The IBM Security Access Manager domain name.Make sure that the domain name you specify is unique among all domains on the LDAP server. The existence of a domain with the same name in a different suffix also causes an error. As this field is the name of the management domain, do not specify an LDAP DN.Here are some example settings and the corresponding result data:SettingResultManagement Suffix: <blank> Management Domain: DefaultsecAuthority=DefaultManagement Suffix: OU=TAMDATA Management Domain: DefaultsecAuthority=Default,OU=TAMDATAAdministrator Password: The security administrator's password.Confirm Administrator Password: The security administrator's password.SSL Server Certificate Lifetime (days): The lifetime in days for the SSL server certificate.SSL Compliance: Specifies any additional SSL compliance.If FIPS is enabled on the appliance, the SSL Compliance field cannot be set to No additional compliance.Click Next.On the LDAP tab, provide settings for the fields displayed. Host name: The name of the LDAP server.Port: The port to be used the system communicates with the LDAP server.DN: The distinguished name that is used when the system contacts the user registry.Password: The password for the DN.Enable SSL: Whether SSL is enabled.Certificate Database: The KDB file that contains the certificate that is used to communicate with the user registry. This field is required if Enable SSL is selected.Certificate Label: The label of the SSL certificate that is presented to the user registry upon request. This field is optional and is only required if SSL is enabled, and the user registry is configured to require a client certificate.Click Finish to save the settings.Local policy server with a local user registryUsers and groups within the local user registry are managed through the Security Access Manager administration framework; for example, pdadmin. All these users and groups are housed under the suffix dc=iswga.Under Policy Server, select Local.Under User Registry, select LDAP Local.Click Next.On the Policy Server tab, provide settings for the fields displayed. Fields with an asterisk are required and must be completed.Administrator Password: The security administrator's password.Confirm Administrator Password: The security administrator's password.SSL Server Certificate Lifetime (days): The lifetime in days for the SSL server certificate.SSL Compliance: Specifies any additional SSL compliance.Click Next.On the LDAP tab, provide settings for the fields displayed. Fields with an asterisk are required and must be completed.PasswordThe administrator password of the embedded LDAP server.Clean existing dataSelect this check box to delete any existing data in the embedded LDAP server before the configuration.Click Finish to save the settings.Remote policy server Under Policy Server, select Remote.Under User Registry, select whether to use LDAP.Click Next.On the Policy Server tab, provide settings for the fields displayed. Host name: The name of the host that hosts the IBM Security Access Manager policy server.Port: The port over which communication with the IBM Security Access Manager policy server takes place.Management Domain: The IBM Security Access Manager domain name.Click Next and complete settings on the LDAP tab.Host name: The name of the LDAP server.Port: The port to be used when the system communicates with the LDAP server.Click Finish to save the settings.Runtime environmentIn the local management interface, go to Secure Web SettingsManageRuntime Component.

Configuring the runtime environment

To configure the runtime environment with the local management interface, use the Runtime Component management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Click Configure. You can configure your policy server to be local or remote.

Local policy server with a remote LDAP user registry

Under Policy Server, select Local.

Under User Registry, select LDAP Remote.

Click Next.

On the Policy Server tab, provide settings for the fields displayed. Fields with an asterisk are required and must be completed.

Management Suffix: The LDAP suffix that is used to hold the IBM® Security Access Manager secAuthority data.

Note: To create the domain at the secAuthority=Default tree, you must leave this field blank.

Management Domain: The IBM Security Access Manager domain name.

Note: Make sure that the domain name you specify is unique among all domains on the LDAP server. The existence of a domain with the same name in a different suffix also causes an error. As this field is the name of the management domain, do not specify an LDAP DN.

Here are some example settings and the corresponding result data:

Setting
Result

Management Suffix: <blank>
Management Domain: Default

secAuthority=Default

Management Suffix: OU=TAMDATA
Management Domain: Default

secAuthority=Default,OU=TAMDATA

Administrator Password: The security administrator's password.

Confirm Administrator Password: The security administrator's password.

SSL Server Certificate Lifetime (days): The lifetime in days for the SSL server certificate.

SSL Compliance: Specifies any additional SSL compliance.

Note: If FIPS is enabled on the appliance, the SSL Compliance field cannot be set to No additional compliance.

Click Next.

On the LDAP tab, provide settings for the fields displayed.

Host name: The name of the LDAP server.

Port: The port to be used the system communicates with the LDAP server.

DN: The distinguished name that is used when the system contacts the user registry.

Password: The password for the DN.

Enable SSL: Whether SSL is enabled.

Certificate Database: The KDB file that contains the certificate that is used to communicate with the user registry. This field is required if "Enable SSL" is selected.

Certificate Label: The label of the SSL certificate that is presented to the user registry upon request. This field is optional and is only required if SSL is enabled, and the user registry is configured to require a client certificate.

Click Finish to save the settings.

Local policy server with a local user registry

Note: Users and groups within the local user registry are managed through the Security Access Manager administration framework; for example, pdadmin. All these users and groups are housed under the suffix "dc=iswga".

Under Policy Server, select Local.

Under User Registry, select LDAP Local.

Click Next.

On the Policy Server tab, provide settings for the fields displayed. Fields with an asterisk are required and must be completed.

Administrator Password: The security administrator's password.

Confirm Administrator Password: The security administrator's password.

SSL Server Certificate Lifetime (days): The lifetime in days for the SSL server certificate.

SSL Compliance: Specifies any additional SSL compliance.

Click Next.

On the LDAP tab, provide settings for the fields displayed. Fields with an asterisk are required and must be completed.

Password

The administrator password of the embedded LDAP server.

Clean existing data

Select this check box to delete any existing data in the embedded LDAP server before the configuration.

Click Finish to save the settings.

Remote policy server

Under Policy Server, select Remote.

Under User Registry, select whether to use LDAP.

Click Next.

On the Policy Server tab, provide settings for the fields displayed.

Host name: The name of the host that hosts the IBM Security Access Manager policy server.

Port: The port over which communication with the IBM Security Access Manager policy server takes place.

Management Domain: The IBM Security Access Manager domain name.

Click Next and complete settings on the LDAP tab.

Host name: The name of the LDAP server.

Port: The port to be used when the system communicates with the LDAP server.

Click Finish to save the settings.

Parent topic: Runtime environment

Unconfiguring the runtime environmentUnconfiguring the runtime environmentAccess Manager Appliance: Unconfiguring the runtime environmentTo unconfigure the runtime environment component of the appliance with the local management interface, use the Runtime Component management page.runtimeunconfiguringpolicy serverslocalremoteunconfiguringserverspoliciesappliancesruntime environment componentdataconfigurationDNLDAPdomainsSecurity Access ManagerLDAPremote user registrieslocal user registriesuser registriesremotelocalFrom the top menu, select Secure Web SettingsManage Runtime Component.Click Unconfigure.Take one of the following sets of actions.Unconfigure a local policy server with a remote LDAP user registryEnter the LDAP DN and LDAP password.Select the Clear user registry entries check box if you want the unconfigure operation to remove all Security Access Manager domain, user, and group information. By default, this check box is not selected.Click the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.Click Submit to confirm the operation.Unconfigure a local policy server with a local user registryEnter the LDAP password.Select the Clear user registry entries check box if you want the unconfigure operation to remove all Security Access Manager domain, user, and group information. By default, this check box is not selected. Select the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.Click Submit to confirm the operation.Unconfigure a remote policy serverSelect the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.Click Submit to confirm operation.Runtime environmentIn the local management interface, go to Secure Web SettingsManageRuntime Component.

Unconfiguring the runtime environment

To unconfigure the runtime environment component of the appliance with the local management interface, use the Runtime Component management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Click Unconfigure.

Take one of the following sets of actions.

Unconfigure a local policy server with a remote LDAP user registry

Enter the LDAP DN and LDAP password.

Select the Clear user registry entries check box if you want the unconfigure operation to remove all Security Access Manager domain, user, and group information. By default, this check box is not selected.

Click the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.

Note: Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.

Click Submit to confirm the operation.

Unconfigure a local policy server with a local user registry

Enter the LDAP password.

Select the Clear user registry entries check box if you want the unconfigure operation to remove all Security Access Manager domain, user, and group information. By default, this check box is not selected.

Select the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.

Note: Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.

Click Submit to confirm the operation.

Unconfigure a remote policy server

Select the Force check box if you want the unconfigure operation to forcefully remove all of the configuration data. By default, this check box is not selected.

Note: Select the Force check box only if the unconfiguration fails repeatedly. Use this option only as a last resort.

Click Submit to confirm operation.

Parent topic: Runtime environment

Managing runtime configuration filesManaging runtime configuration filesAccess Manager Appliance: Managing runtime configuration filesTo manage configuration files with the local management interface, use the Runtime Component management page.runtimeconfigurationappliancesruntime environment componentFrom the top menu, select Secure Web SettingsManageRuntime Component.Click ManageConfiguration Files.Select one of the following runtime configuration files.pd.conf ivmgrd.conf ldap.conf activedir_ldap.conf Routing FileThe ivmgrd.conf and Routing File options are only available when a policy server is configured on the appliance.Edit the configuration file and then click Save to save the changes. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert. For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Runtime environmentIn the local management interface, go to Secure Web SettingsManageRuntime Component.

Managing runtime configuration files

To manage configuration files with the local management interface, use the Runtime Component management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Click Manage > Configuration Files.

Select one of the following runtime configuration files.

pd.conf
ivmgrd.conf
ldap.conf
activedir_ldap.conf
Routing File

Note: The ivmgrd.conf and Routing File options are only available when a policy server is configured on the appliance.

Edit the configuration file and then click Save to save the changes. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Runtime environment

Configuring JVM debugging for the runtime profileConfiguring JVM debugging for the runtime profileConfiguring JVM debugging for the runtime profileEnable JVM debugging for the runtime profile so that you can debug new Java extension points.runtimeprofilesJVM debuggingJVM debuggingdebuggingJVMJava extension pointsJavaextension pointsadvanced tuning parametersFrom the top menu, select Manage System SettingsSystem SettingsAdvanced Tuning Parameters.Click New.In the Key field, enter runtime_profile.jvm_option.In the Value field, enter the JVM debug options that suits your environment. For example, -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044.Click Save Configuration.Deploy your changes.Runtime environmentIn the local management interface, go to Secure Web SettingsManageRuntime Component.

Configuring JVM debugging for the runtime profile

Enable JVM debugging for the runtime profile so that you can debug new Java™ extension points.

Procedure

From the top menu, select Manage System Settings > System Settings > Advanced Tuning Parameters.

Click New.

In the Key field, enter runtime_profile.jvm_option.

In the Value field, enter the JVM debug options that suits your environment. For example, -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044.

Click Save Configuration.

Deploy your changes.

Parent topic: Runtime environment

Users and user registriesWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Configuring the runtime to authenticate basic usersBasic users are users in the registry that are not imported in to Security Access Manager. Edit the ldap.conf file so that basic users can authenticate in Security Access Manager.Embedded LDAP server managementWhen you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry. Managing federated directoriesKeep your federated directories up-to-date so that Security Access Manager can access the most recent user information that is stored in external user registries. You can add a new directory, remove an existing one, or modify its settings.

Users and user registries

Configuring the runtime to authenticate basic users
Basic users are users in the registry that are not imported in to Security Access Manager. Edit the ldap.conf file so that basic users can authenticate in Security Access Manager.

Embedded LDAP server management
When you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry.

Managing federated directories
Keep your federated directories up-to-date so that Security Access Manager can access the most recent user information that is stored in external user registries. You can add a new directory, remove an existing one, or modify its settings.

Parent topic: Web Reverse Proxy administration

Configuring the runtime to authenticate basic usersConfiguring the runtime to authenticate basic usersAccess Manager Appliance: Configuring the run time to authenticate basic usersBasic users are users in the registry that are not imported in to Security Access Manager. Edit the ldap.conf file so that basic users can authenticate in Security Access Manager.basic usersauthenticationauthenticationbasic usersruntimeconfigurationchangesruntime configurationcontrolbasic usersaccess listsmetadataSecurity Access Manager usersJavaAPILDAPconfigurationusersbasicThe following limitations apply to basic users:Basic users work in minimal registry mode only.Basic users cannot use global sign-on.You cannot set access control lists for individual basic users. However, basic users can be members of a Security Access Manager group with access control lists.Registry direct Java API does not support basic users.Account and password valid settings are set to yes. You cannot modify them for basic users. Basic users are not subject to any Security Access Manager account and password policies. They always have their account-valid and password-valid values set to yes. Basic users do not record the last login or last password change even if [ldap] enable-last-login is set. You must use the underlying registry equivalents for these capabilities.Configure the run time so that basic users can authenticate to Security Access Manager. Basic users have limitations. When basic-user-support is enabled, basic and full users are located by using the basic-user-principal-attribute suffix in the LDAP native user entry. If the located native user entry has full Security Access Manager user metadata then it is treated as a full user. The value of the basic-user-principal-attribute is used for the user ID even if the Security Access Manager full user metadata has a different principalName.Basic users are managed in the corporate user registry by using LDAP management tools. These users are not managed through Security Access Manager, except when you change and reset passwords for basic users.When searching for basic or full users, Security Access Manager: Uses the configured basic-user-principal-attribute and the user-search-filter values to locate users in the registry.Searches all suffixes that are defined by basic-user-search-suffix entries and in the order that they are defined, unless basic-user-suffix-optimizer is enabled. If no basic-user-search-suffix entries are specified, all suffixes are searched in an unspecified order.If basic-user-suffix-optimizer is enabled, a hit count is kept for each suffix that is used to search for users. The suffix search order is based on a dynamic most-used suffix order. This dynamic search order is not used if basic-user-no-duplicates is enabled since in that situation, all suffixes must be searched to ensure that there are no duplicates, thus the order is irrelevant.Log in the local management interface.From the top menu, select Secure Web SettingsManageRuntime Component.Click ManageConfiguration Files.Select ldap.conf.Add the following lines under the [ldap] stanza.basic-user-support = yesSet this option to yes to support basic users.basic-user-principal-attribute = <uid>This attribute is the principalName of the basic and full users.basic-user-search-suffix = <DN>Set this option for each suffix to search for full and basic users. This must include suffixes to search on the primary LDAP server and all federated registries. If basic-user-support is enabled and one or more basic-user-search-suffix values are configured, the ignore-suffix entries are disregarded. The basic-user-search-suffix configuration entries determine the suffixes that are searched. When there are no basic-user-search-suffix entries, the system searches all available suffixes, except for those specified by the ignore-suffix entries. If you do not specify any basic-user-search-suffix values, you can use ignore-suffix entries to specify one or more suffixes to exclude from the search. If basic-user-search-suffix is not set, then all suffixes are chosen in an unspecified order.If you choose to specify one or more basic-user-search-suffix entries, ensure that you include an entry for every suffix that must be searched. Ensure that you include the primary suffix for Security Access Manager accounts. For example, secAuthority=Default. If you specify one or more basic-user-search-suffix entries, but you do not include this suffix, the search does not return the full Security Access Manager accounts. In this case, you are not able to authenticate to pdadmin with the sec_master account or any other Security Access Manager accounts.basic-user-no-duplicates = {yes | no}If set to yes, the search for basic users covers all suffixes to ensure that no users with the same name are found. If set to no, the search for basic users stops immediately and ignores possible duplicates.Avoid configuring your environment to include suffixes that contain duplicates. Ensure that the basic-user-principal-attribute is unique for all accounts across the specified suffixes. If there are no duplicates in the environment, you can set basic-user-no-duplicates to no to improve search efficiency. However, if duplicates exist in your environment, set basic-user-no-duplicates to yes so that the system can return an error if it encounters more than one account with the same principal attribute value. basic-user-suffix-optimizer = {yes | no}If set to yes and basic-user-no-duplicates is set to no, the search order of suffixes is sorted, with the most hit of the basic user suffix at the head of the search suffix list. If set to no, the search order is provided by the basic-user-search-suffix order.If basic-user-no-duplicates is set to yes, the basic-user-suffix-optimizer entry is disregarded. In this case, all suffixes are searched to check for duplicates. Add the following line under the [server:<fedreg>] stanza.basic-user-principal-attribute = <uid>Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Users and user registries

Configuring the runtime to authenticate basic users

Basic users are users in the registry that are not imported in to Security Access Manager. Edit the ldap.conf file so that basic users can authenticate in Security Access Manager.

Before you begin

The following limitations apply to basic users:

Basic users work in minimal registry mode only.

Basic users cannot use global sign-on.

You cannot set access control lists for individual basic users. However, basic users can be members of a Security Access Manager group with access control lists.

Registry direct Java API does not support basic users.

Account and password valid settings are set to yes. You cannot modify them for basic users.

Warning: Basic users are not subject to any Security Access Manager account and password policies. They always have their account-valid and password-valid values set to yes. Basic users do not record the last login or last password change even if [ldap] enable-last-login is set. You must use the underlying registry equivalents for these capabilities.

About this task

Configure the run time so that basic users can authenticate to Security Access Manager. Basic users have limitations.

When basic-user-support is enabled, basic and full users are located by using the basic-user-principal-attribute suffix in the LDAP native user entry. If the located native user entry has full Security Access Manager user metadata then it is treated as a full user. The value of the basic-user-principal-attribute is used for the user ID even if the Security Access Manager full user metadata has a different principalName.

Basic users are managed in the corporate user registry by using LDAP management tools. These users are not managed through Security Access Manager, except when you change and reset passwords for basic users.

When searching for basic or full users, Security Access Manager:

Uses the configured basic-user-principal-attribute and the user-search-filter values to locate users in the registry.

Searches all suffixes that are defined by basic-user-search-suffix entries and in the order that they are defined, unless basic-user-suffix-optimizer is enabled. If no basic-user-search-suffix entries are specified, all suffixes are searched in an unspecified order.

If basic-user-suffix-optimizer is enabled, a hit count is kept for each suffix that is used to search for users. The suffix search order is based on a dynamic most-used suffix order. This dynamic search order is not used if basic-user-no-duplicates is enabled since in that situation, all suffixes must be searched to ensure that there are no duplicates, thus the order is irrelevant.

Procedure

Log in the local management interface.

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Click Manage > Configuration Files.

Select ldap.conf.

Add the following lines under the [ldap] stanza.

basic-user-support = yes

Set this option to yes to support basic users.

basic-user-principal-attribute = <uid>

This attribute is the principalName of the basic and full users.

basic-user-search-suffix = <DN>

Set this option for each suffix to search for full and basic users. This must include suffixes to search on the primary LDAP server and all federated registries.

If basic-user-support is enabled and one or more basic-user-search-suffix values are configured, the ignore-suffix entries are disregarded. The basic-user-search-suffix configuration entries determine the suffixes that are searched.

Note: When there are no basic-user-search-suffix entries, the system searches all available suffixes, except for those specified by the ignore-suffix entries. If you do not specify any basic-user-search-suffix values, you can use ignore-suffix entries to specify one or more suffixes to exclude from the search.

If basic-user-search-suffix is not set, then all suffixes are chosen in an unspecified order.

If you choose to specify one or more basic-user-search-suffix entries, ensure that you include an entry for every suffix that must be searched. Ensure that you include the primary suffix for Security Access Manager accounts. For example, secAuthority=Default. If you specify one or more basic-user-search-suffix entries, but you do not include this suffix, the search does not return the full Security Access Manager accounts. In this case, you are not able to authenticate to pdadmin with the sec_master account or any other Security Access Manager accounts.

basic-user-no-duplicates = {yes | no}

If set to yes, the search for basic users covers all suffixes to ensure that no users with the same name are found. If set to no, the search for basic users stops immediately and ignores possible duplicates.

Avoid configuring your environment to include suffixes that contain duplicates. Ensure that the basic-user-principal-attribute is unique for all accounts across the specified suffixes. If there are no duplicates in the environment, you can set basic-user-no-duplicates to no to improve search efficiency. However, if duplicates exist in your environment, set basic-user-no-duplicates to yes so that the system can return an error if it encounters more than one account with the same principal attribute value.

basic-user-suffix-optimizer = {yes | no}

If set to yes and basic-user-no-duplicates is set to no, the search order of suffixes is sorted, with the most hit of the basic user suffix at the head of the search suffix list. If set to no, the search order is provided by the basic-user-search-suffix order.

Note: If basic-user-no-duplicates is set to yes, the basic-user-suffix-optimizer entry is disregarded. In this case, all suffixes are searched to check for duplicates.

Add the following line under the [server:<fedreg>] stanza.

basic-user-principal-attribute = <uid>

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Users and user registries

Embedded LDAP server managementWhen you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry. embedded LDAP serversmanagementexternal user registriesmetadatauser registriesserversLDAPdatausersLDAPmanagementserversuser registriesembeddedThis same registry can optionally be used to also store the associated user data for the users. For more information, see Managing federated directoriesKeep your federated directories up-to-date so that Security Access Manager can access the most recent user information that is stored in external user registries. You can add a new directory, remove an existing one, or modify its settings. .The embedded LDAP server does not support TLS v1.1 or TLS v1.2.Users and user registriesSSL supportThe embedded LDAP server provides an SSL interface for management of the data contained in the user registry. Managing passwordsAdministration of the data contained in the embedded LDAP server can be performed as the cn=root,secAuthority=Default user. Managing suffixesA suffix (also known as a naming context) is a DN that identifies the top entry in a locally held directory hierarchy. Because of the relative naming scheme used in LDAP, this DN is also the suffix of every other entry in that directory hierarchy. The embedded LDAP server can have multiple suffixes, each identifying a locally held directory hierarchy, for example, o=ibm,c=us.Setting debug log levelCustomize the log levels of the embedded LDAP server to suit your debugging needs.

Embedded LDAP server management

When you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry.

This same registry can optionally be used to also store the associated user data for the users. For more information, see Managing federated directories.

Note: The embedded LDAP server does not support TLS v1.1 or TLS v1.2.

SSL support
The embedded LDAP server provides an SSL interface for management of the data contained in the user registry.

Managing passwords
Administration of the data contained in the embedded LDAP server can be performed as the cn=root,secAuthority=Default user.

Managing suffixes
A suffix (also known as a naming context) is a DN that identifies the top entry in a locally held directory hierarchy. Because of the relative naming scheme used in LDAP, this DN is also the suffix of every other entry in that directory hierarchy. The embedded LDAP server can have multiple suffixes, each identifying a locally held directory hierarchy, for example, o=ibm,c=us.

Setting debug log level
Customize the log levels of the embedded LDAP server to suit your debugging needs.

Parent topic: Users and user registries

SSL supportThe embedded LDAP server provides an SSL interface for management of the data contained in the user registry. SSLsupportembedded LDAP serversSSL interfaceLDAPSSLsupportadvanced tuning parametersauthenticationmutualappliancesmanagement interfacecontrolFIPS settingdatamanagementdatabasesLDAP keysdefaultportsuser registriesmanagementThe embedded LDAP server listens on port 636 of the management interface of the appliance by default. The administrator can choose a port other than the default by modifying the advanced tuning parameter wga.rte.embedded.ldap.ssl.port. The advanced tuning parameters are accessed through Manage System SettingsAdvanced Tuning Parameters. After you modify this advanced tuning parameter, you must restart the Security Access Manager runtime environment for the change to take effect.The SSL certificates that are used by the LDAP server can be managed through the SSL Certificates panels of the LMI. For further details, see Managing SSL certificatesIn the local management interface, go to Manage System SettingsSecure SettingsSSL Certificates.. The certificates are contained in the embedded_ldap_keys database file.Two certificates are used by the LDAP server:The certificate with the server label is used as the server certificate by the LDAP server. By default, the server certificate is a self-signed certificate. But this should be replaced in a production environment.The certificate with the ca label is used as the CA certificate by the LDAP server. If no ca certificate is found in the key database, the server then uses the server certificate as the CA certificate. That is, it expects the server certificate to be a self-signed certificate.In addition to this, the LDAP server can support mutual authentication by client certificates, providing that:The client certificate has been signed by the CA that is known to the LDAP server. That is, the CA certificate is stored in the keyfile with a label of ca.The distinguished name (DN) contained in the client certificate precisely matches a known LDAP user.The FIPS setting of the appliance controls the ciphers that are supported by the OpenLDAP server.Embedded LDAP server managementWhen you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry.

SSL support

The embedded LDAP server provides an SSL interface for management of the data contained in the user registry.

The embedded LDAP server listens on port 636 of the management interface of the appliance by default. The administrator can choose a port other than the default by modifying the advanced tuning parameter wga.rte.embedded.ldap.ssl.port. The advanced tuning parameters are accessed through Manage System Settings > Advanced Tuning Parameters. After you modify this advanced tuning parameter, you must restart the Security Access Manager runtime environment for the change to take effect.

The SSL certificates that are used by the LDAP server can be managed through the SSL Certificates panels of the LMI. For further details, see Managing SSL certificates. The certificates are contained in the embedded_ldap_keys database file.

Two certificates are used by the LDAP server:

The certificate with the server label is used as the server certificate by the LDAP server. By default, the server certificate is a self-signed certificate. But this should be replaced in a production environment.

The certificate with the ca label is used as the CA certificate by the LDAP server. If no ca certificate is found in the key database, the server then uses the server certificate as the CA certificate. That is, it expects the server certificate to be a self-signed certificate.

In addition to this, the LDAP server can support mutual authentication by client certificates, providing that:

The client certificate has been signed by the CA that is known to the LDAP server. That is, the CA certificate is stored in the keyfile with a label of ca.

The distinguished name (DN) contained in the client certificate precisely matches a known LDAP user.

The FIPS setting of the appliance controls the ciphers that are supported by the OpenLDAP server.

Parent topic: Embedded LDAP server management

Managing passwordsAdministration of the data contained in the embedded LDAP server can be performed as the cn=root,secAuthority=Default user. password managementembedded LDAP serversadministrationdataadministrationchangespasswordscomponentsruntimedefaultpasswordsLDAPadministrationThe default password for this user is passw0rd. The password should be modified in a production environment.From the top menu, select Secure Web SettingsManageRuntime Component.Select ManageEmbedded LDAPPassword.Enter the new password in the Password field.Enter the new password again in the Confirm Password field.Click OK to change the password.Embedded LDAP server managementWhen you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry.

Managing passwords

Administration of the data contained in the embedded LDAP server can be performed as the cn=root,secAuthority=Default user.

About this task

The default password for this user is passw0rd. The password should be modified in a production environment.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select Manage > Embedded LDAP > Password.

Enter the new password in the Password field.

Enter the new password again in the Confirm Password field.

Click OK to change the password.

Parent topic: Embedded LDAP server management

Managing suffixesA suffix (also known as a naming context) is a DN that identifies the top entry in a locally held directory hierarchy. Because of the relative naming scheme used in LDAP, this DN is also the suffix of every other entry in that directory hierarchy. The embedded LDAP server can have multiple suffixes, each identifying a locally held directory hierarchy, for example, o=ibm,c=us.suffix managementembedded LDAP serverssuffixesDNlocal hierarchiesdefaultsuffixesdomainsTCP/IPLDAPsuffixesThe embedded LDAP server is pre-configured with a default suffix, dc=iswga, to make it easier to get started with the server. There is no requirement that you use this suffix. You can add your own suffixes and delete the pre-configured suffix.There are two commonly used naming conventions for suffixes. One is based on the TCP/IP domain for your organization. The other is based on the organization's name and location. For example:Given a TCP/IP domain of mycompany.com, you might choose a suffix like dc=mycompany,dc=com, where the dc attribute refers to the domain component. If your company name is My Company and it is located in the United States, you might chose a suffix like one of the following examples:o=My Company o=My Company,c=US ou=Widget Division,o=My Company,c=USWhere ou is the name for the organizationalUnit object class, o is the organization name for the organization object class, and c is a standard two letter country abbreviation used to name the country object class. The following table lists the supported suffix elements and the corresponding object classes that are used when creating the top level entry for the suffix:Supported suffix elementsSupported suffix elementsElementObject classdcdomainccountryoorganizationouorganizationalUnitllocalityFrom the top menu, select Secure Web SettingsManageRuntime Component.Select ManageEmbedded LDAPSuffixes.All current suffixes are listed. You can then add or delete suffixes as needed.Follow the prompts to complete the action you want to take.Embedded LDAP server managementWhen you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry.

Managing suffixes

A suffix (also known as a naming context) is a DN that identifies the top entry in a locally held directory hierarchy. Because of the relative naming scheme used in LDAP, this DN is also the suffix of every other entry in that directory hierarchy. The embedded LDAP server can have multiple suffixes, each identifying a locally held directory hierarchy, for example, o=ibm,c=us.

About this task

The embedded LDAP server is pre-configured with a default suffix, dc=iswga, to make it easier to get started with the server. There is no requirement that you use this suffix. You can add your own suffixes and delete the pre-configured suffix.

There are two commonly used naming conventions for suffixes. One is based on the TCP/IP domain for your organization. The other is based on the organization's name and location. For example:

Given a TCP/IP domain of mycompany.com, you might choose a suffix like dc=mycompany,dc=com, where the dc attribute refers to the domain component.

If your company name is My Company and it is located in the United States, you might chose a suffix like one of the following examples:

o=My Company
o=My Company,c=US
ou=Widget Division,o=My Company,c=US

Where ou is the name for the organizationalUnit object class, o is the organization name for the organization object class, and c is a standard two letter country abbreviation used to name the country object class.

The following table lists the supported suffix elements and the corresponding object classes that are used when creating the top level entry for the suffix:

Table 189. Supported suffix elements. Supported suffix elements

Element | Object class
dc | domain
c | country
o | organization
ou | organizationalUnit
l | locality

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select Manage > Embedded LDAP > Suffixes. All current suffixes are listed. You can then add or delete suffixes as needed.

Follow the prompts to complete the action you want to take.

Parent topic: Embedded LDAP server management

Setting debug log levelCustomize the log levels of the embedded LDAP server to suit your debugging needs.debugginglog levelslog levelscustomizingLDAP serverschangesdebug levelscontrolaccess listsembedded LDAP serverslog levelsLDAPlog levelsreplicationsyncingsettingsdebug levelstracefunction callsSelect Secure Web SettingsManage Runtime Component.On the Runtime Component page, select ManageEmbedded LDAPChange Debug Level.Select or clear the check boxes to indicate the wanted debug level. You can select zero to multiple debug level options.Use the check box at the top to select or clear all debug level options.Debug level optionDebug level optionKeywordDescriptiontracetraceTrace function callsconnectionconnsConnection managementsearch.filterfilterSearch filter processingconfig.fileconfigConfiguration processingacl.processingACLAccess control list processingstatisticsstatsStatistics log connections, operations, or resultsstatistics.entriesstats2Statistics log entries sentshell.backendshellPrint communication with shell backendsentry.parsingparsePrint entry parsing debuggingsync.replicationsyncSync replication consumer processinguncategorizednoneLog messages that are not categorized including critical messagesClick Submit.Embedded LDAP server managementWhen you configure the Security Access Manager runtime environment, you can choose to use an external user registry for storing the Security Access Manager metadata, or use the embedded user registry.

Setting debug log level

Customize the log levels of the embedded LDAP server to suit your debugging needs.

Procedure

Select Secure Web Settings > Manage > Runtime Component.

On the Runtime Component page, select Manage > Embedded LDAP > Change Debug Level.

Select or clear the check boxes to indicate the wanted debug level. You can select zero to multiple debug level options.

Tip: Use the check box at the top to select or clear all debug level options.

Table 190. . Debug level option

Debug level option | Keyword | Description
trace | trace | Trace function calls
connection | conns | Connection management
search.filter | filter | Search filter processing
config.file | config | Configuration processing
acl.processing | ACL | Access control list processing
statistics | stats | Statistics log connections, operations, or results
statistics.entries | stats2 | Statistics log entries sent
shell.backend | shell | Print communication with shell backends
entry.parsing | parse | Print entry parsing debugging
sync.replication | sync | Sync replication consumer processing
uncategorized | none | Log messages that are not categorized including critical messages

Click Submit.

Parent topic: Embedded LDAP server management

Managing federated directoriesKeep your federated directories up-to-date so that Security Access Manager can access the most recent user information that is stored in external user registries. You can add a new directory, remove an existing one, or modify its settings. federated directoriesexternal user registriesSecurity Access Managerexternal user registrieschangesfederated directory configurationdefaultsuffixescertificatesLDAPSSLsettingsuser registriesexternalFederated directories store the data that is associated with different users in different user registries. With federated directories, the appliance can access user information that is stored in a user registry external to Security Access Manager.The DN of the user controls the user registry that is used when you search for user information. The Security Access Manager data that is associated with each user record is still stored in the Security Access Manager user registry. The Security Access Manageruser registry is defined when you configure the runtime environment.The Federated Directories menu item is enabled only if the runtime component is already configured.If the federated directories configuration is changed on the appliance that is running the policy server, the policy server is automatically restarted.From the top menu, select Secure Web SettingsManageRuntime Component.Select ManageFederated Directories.All configured directories are displayed. By default, only the number of configured suffixes is shown. To view the suffixes in a particular directory, expand the relevant row.Follow the prompts to complete the action you want to take.After you make any of the following changes, you must restart the Security Access Manager runtime environment for the changes to take effect.Add a directoryClick New and provide values for the displayed fields.Multiple suffixes can be added on separate lines in the Suffix field.If the Enable SSL option is selected, an extra field Client Certificate is displayed. Use the Client Certificate field to define the client personal certificate to present to the federated user directory server. This field is not required when one of the certificates in the keyfile was identified as the default certificate. The decision of whether to identify a certificate as the default depends on the configuration of the target user directory server. You can click Save only if all of the fields are valid.Modify the settings for a configured directorySelect the directory to update and click Edit.Remove a directory or suffixIf you select a directory row and click Delete, the selected directory is removed. If you select a suffix row and click Delete, the selected suffix is removed.Before you delete a federated directory, delete all federated users in this directory from Security Access Manager first.The confirmation message indicates whether a directory or a suffix is being removed.You cannot delete a suffix if it is the only suffix left in a directory, as such operation would leave the configuration in an invalid state. A directory must have at least one suffix to be valid.Update the LDAP SSL settingsClick SSL Settings.This function updates the values in the ldap.conf configuration file. These values are only used if SSL settings do not exist in the configuration file of the hosting server. For example, if the settings exist in the WebSEAL configuration file, they take precedence over the settings that are contained in the ldap.conf configuration file.Users and user registries

Managing federated directories

Keep your federated directories up-to-date so that Security Access Manager can access the most recent user information that is stored in external user registries. You can add a new directory, remove an existing one, or modify its settings.

About this task

Federated directories store the data that is associated with different users in different user registries. With federated directories, the appliance can access user information that is stored in a user registry external to Security Access Manager.

The DN of the user controls the user registry that is used when you search for user information. The Security Access Manager data that is associated with each user record is still stored in the Security Access Manager user registry. The Security Access Manageruser registry is defined when you configure the runtime environment.

The Federated Directories menu item is enabled only if the runtime component is already configured.

Note: If the federated directories configuration is changed on the appliance that is running the policy server, the policy server is automatically restarted.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select Manage > Federated Directories.

Note: All configured directories are displayed. By default, only the number of configured suffixes is shown. To view the suffixes in a particular directory, expand the relevant row.

Follow the prompts to complete the action you want to take.

Note: After you make any of the following changes, you must restart the Security Access Manager runtime environment for the changes to take effect.

Add a directory

Click New and provide values for the displayed fields.

Multiple suffixes can be added on separate lines in the Suffix field.

If the Enable SSL option is selected, an extra field Client Certificate is displayed. Use the Client Certificate field to define the client personal certificate to present to the federated user directory server. This field is not required when one of the certificates in the keyfile was identified as the default certificate. The decision of whether to identify a certificate as the default depends on the configuration of the target user directory server.

You can click Save only if all of the fields are valid.

Modify the settings for a configured directory

Select the directory to update and click Edit.

Remove a directory or suffix

If you select a directory row and click Delete, the selected directory is removed. If you select a suffix row and click Delete, the selected suffix is removed.

Note: Before you delete a federated directory, delete all federated users in this directory from Security Access Manager first.

The confirmation message indicates whether a directory or a suffix is being removed.

You cannot delete a suffix if it is the only suffix left in a directory, as such operation would leave the configuration in an invalid state. A directory must have at least one suffix to be valid.

Update the LDAP SSL settings

Click SSL Settings.

This function updates the values in the ldap.conf configuration file. These values are only used if SSL settings do not exist in the configuration file of the hosting server. For example, if the settings exist in the WebSEAL configuration file, they take precedence over the settings that are contained in the ldap.conf configuration file.

Parent topic: Users and user registries

Reverse proxy instance managementAccess Manager Appliance: Managing reverse proxyIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.reverse proxymanagementLMIreverse proxy managementWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Stopping, starting, or restarting an instanceTo stop, start or restart an instance with the local management interface, use the Reverse Proxy management page.Configuring an instanceTo configure an instance with the local management interface, use the Reverse Proxy management page.Unconfiguring an instanceTo unconfigure an instance with the local management interface, use the Reverse Proxy management page.Managing web reverse proxy configuration entriesTo manage the web reverse proxy basic configuration, use the Reverse Proxy management page.Managing web reverse proxy configuration filesTo manage reverse proxy configurations with the local management interface, use the Reverse Proxy management page.Exporting WebSEAL configurationExport the configuration bundle of WebSEAL from the appliance so that you can migrate the WebSEAL instances between different appliances.Configuring web application firewall To configure web application firewall with the local management interface, use the Reverse Proxy management page.Managing administration pagesTo manage files and directories in the administration pages root with the local management interface, use the Reverse Proxy management page.Renewing web reverse proxy management certificatesRenew the management certificate of a web reverse proxy instance.

Reverse proxy instance management

In the local management interface, go to Secure Web Settings > Manage > Reverse Proxy. A list of all instances and their current states is displayed.

Stopping, starting, or restarting an instance
To stop, start or restart an instance with the local management interface, use the Reverse Proxy management page.

Configuring an instance
To configure an instance with the local management interface, use the Reverse Proxy management page.

Unconfiguring an instance
To unconfigure an instance with the local management interface, use the Reverse Proxy management page.

Managing web reverse proxy configuration entries
To manage the web reverse proxy basic configuration, use the Reverse Proxy management page.

Managing web reverse proxy configuration files
To manage reverse proxy configurations with the local management interface, use the Reverse Proxy management page.

Exporting WebSEAL configuration
Export the configuration bundle of WebSEAL from the appliance so that you can migrate the WebSEAL instances between different appliances.

Configuring web application firewall
To configure web application firewall with the local management interface, use the Reverse Proxy management page.

Managing administration pages
To manage files and directories in the administration pages root with the local management interface, use the Reverse Proxy management page.

Renewing web reverse proxy management certificates
Renew the management certificate of a web reverse proxy instance.

Parent topic: Web Reverse Proxy administration

Stopping, starting, or restarting an instanceAccess Manager Appliance: Stopping, starting, or restarting an instanceTo stop, start or restart an instance with the local management interface, use the Reverse Proxy management page.reverse proxyinstancesstoppingstartingrestartinginstancesstoppingstartingrestartingFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Stop an instanceClick Stop.A message is displayed indicating that the instance has been stopped successfully.Start an instanceClick Start.A message is displayed indicating that the instance has been started successfully.Restart an instanceClick Restart.A message is displayed indicating that the instance has been restarted successfully.Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Stopping, starting, or restarting an instance

To stop, start or restart an instance with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Stop an instance

Click Stop.

A message is displayed indicating that the instance has been stopped successfully.

Start an instance

Click Start.

A message is displayed indicating that the instance has been started successfully.

Restart an instance

Click Restart.

A message is displayed indicating that the instance has been restarted successfully.

Parent topic: Reverse proxy instance management

Configuring an instanceAccess Manager Appliance: Configuring an instanceTo configure an instance with the local management interface, use the Reverse Proxy management page.reverse proxyinstancesconfigurationinstancesconfigurationdomainsSecurity Access ManagerIBM Security Access ManageradministrationSecurity Access ManageradministrationLDAPSSLenablingusersrequestsFrom the top menu, select Secure Web SettingsManageReverse Proxy.Click New.Provide settings for the fields that are displayed on the Instance, IBM Security Access Manager, Transport, and User Registry tabs. On the Instance tab:FieldDescriptionInstance NameThis is the new instance name, which is a unique name that identifies the instance. Multiple instances can be installed on the same computer system. Each instance must have a unique name.Host NameThe host name that is used by the IBM Security Access Manager policy server to contact the appliance. The address that corresponds to this host name must match a management interface address of the appliance. The addresses that are associated with the application interface of the appliance cannot be used for communication with the IBM Security Access Manager policy server. Valid values include any valid host name or IP address. For example: libra.dallas.ibm.comListening PortThis is the listening port through which the instance communicates with the Security Access Manager policy server.IP Address for the Primary InterfaceThe IP address for the logical interface. On the IBM Security Access Manager tab:FieldDescriptionAdministrator NameThe Security Access Manager administrator name.Administrator PasswordThe Security Access Manager administrator password.DomainThe Security Access Manager domain.On the Transport tab:FieldDescriptionEnable HTTPSpecifies whether to accept user requests across the HTTP protocol. HTTP PortThe port to listen for HTTP requests. This field is only valid if the Enable HTTP check box is selected.Enable HTTPSSpecifies whether to accept user requests across the HTTPS protocol. HTTPS PortThe port to listen for HTTPS requests. This field is only valid if the Enable HTTPS check box is selected.On the User Registry tab:FieldDescriptionEnable SSLSpecifies whether to enable SSL communication between the instance and the LDAP server. Key File NameThe file that contains the LDAP SSL certificate. This field is only valid if the Enable SSL check box is selected.Certificate LabelThe LDAP client certificate label. This field is only valid if the Enable SSL check box is selected.PortThe port number through which to communicate with the LDAP server. This field is only valid if the Enable SSL check box is selected.Click Finish.A message is displayed indicating that the instance has been configured successfully.Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Configuring an instance

To configure an instance with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Click New.

Provide settings for the fields that are displayed on the Instance, IBM Security Access Manager, Transport, and User Registry tabs.

On the Instance tab:

Field
Description

Instance Name
This is the new instance name, which is a unique name that identifies the instance. Multiple instances can be installed on the same computer system. Each instance must have a unique name.

Host Name

The host name that is used by the IBM® Security Access Manager policy server to contact the appliance. The address that corresponds to this host name must match a management interface address of the appliance. The addresses that are associated with the application interface of the appliance cannot be used for communication with the IBM Security Access Manager policy server.

Valid values include any valid host name or IP address. For example: libra.dallas.ibm.com

Listening Port
This is the listening port through which the instance communicates with the Security Access Manager policy server.

IP Address for the Primary Interface
The IP address for the logical interface.

On the IBM Security Access Manager tab:

Field | Description
Administrator Name | The Security Access Manager administrator name.
Administrator Password | The Security Access Manager administrator password.
Domain | The Security Access Manager domain.

On the Transport tab:

Field | Description
Enable HTTP | Specifies whether to accept user requests across the HTTP protocol.
HTTP Port | The port to listen for HTTP requests. This field is only valid if the Enable HTTP check box is selected.
Enable HTTPS | Specifies whether to accept user requests across the HTTPS protocol.
HTTPS Port | The port to listen for HTTPS requests. This field is only valid if the Enable HTTPS check box is selected.

On the User Registry tab:

Field | Description
Enable SSL | Specifies whether to enable SSL communication between the instance and the LDAP server.
Key File Name | The file that contains the LDAP SSL certificate. This field is only valid if the Enable SSL check box is selected.
Certificate Label | The LDAP client certificate label. This field is only valid if the Enable SSL check box is selected.
Port | The port number through which to communicate with the LDAP server. This field is only valid if the Enable SSL check box is selected.

Click Finish. A message is displayed indicating that the instance has been configured successfully.

Parent topic: Reverse proxy instance management

Unconfiguring an instanceAccess Manager Appliance: Unconfiguring an instanceTo unconfigure an instance with the local management interface, use the Reverse Proxy management page.reverse proxyinstancesunconfiguringinstancesunconfiguringFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance to unconfigure.Click Delete.Enter the administrator name and password. Click DeleteSelect the Force check box if unconfiguration fails multiple times. Use this option only as a last resort.Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Unconfiguring an instance

To unconfigure an instance with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance to unconfigure.

Click Delete.

Enter the administrator name and password.

Click Delete

Note: Select the Force check box if unconfiguration fails multiple times. Use this option only as a last resort.

Parent topic: Reverse proxy instance management

Managing web reverse proxy configuration entriesAccess Manager Appliance: Managing web reverse proxy configuration entriesTo manage the web reverse proxy basic configuration, use the Reverse Proxy management page.Web Reverse Proxyconfigurationentriesconfigurationweb reverse proxyentriesappliancesclustersauthenticationsettingschangescluster configurationclustersmastersappliancesconfigurationdatabasesSSLdatacertificatesDistributed Session Cache (DSC)enablingdomainsCDSSOECSSOjunctionsconfigurationLTPA keysfilesreverse proxyconfigurationsessionssettingsservicesnamescommandsTCPjunctionssession cookie namesWebSEALinterfaceswebserverspingFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select Edit.Make your changes to the settings on the Server, SSL, Junction, Authentication, SSO, Session, Response, Logging, and Interfaces tabs. ServerThe Server tab contains entries that are related to the general server configuration.FieldDescriptionHTTPSSelect this check box to enable the HTTPS port within Reverse Proxy.HTTPS PortThe port over which Reverse Proxy listens for HTTPS requests.HTTPSelect this check box to enable the HTTP port within Reverse Proxy.HTTP PortThe port over which Reverse Proxy listens for HTTP requests.Interface AddressThe network interface on which the Reverse Proxy server listens for requests.Persistent Connection TimeoutThe maximum number of seconds that a persistent connection with a client can remain inactive before it is closed by the server.Worker ThreadsThe number of threads that are allocated to service requests.Cluster is MasterIf the Reverse Proxy clustering function is used, this check box controls whether this Reverse Proxy server acts as the cluster master.Master Instance NameThe server name for the Reverse Proxy instance which is acting as the master within the cluster. This option is only enabled if the Cluster is Master check box is not selected.Message LocaleThe locale in which the Reverse Proxy runs.SSLThe SSL tab contains entries that are related to the general SSL configuration of the server.FieldDescriptionSSL Certificate Key FileThe key database that is used to store the certificates which are presented by Reverse Proxy to the client.Network HSM Key FileThe key database that stores the certificates to be used by the network Hardware Security Module (HSM) device.SSL Server CertificateThe name of the SSL certificate, within the key database, which is presented to the client. The drop-down list includes certificates from both the local and network key files. The certificates from the network key file are prefixed with the token label for the network HSM device.JCT Certificate Key FileThe key database that is used to store the certificates which are presented by Reverse Proxy to the junctioned Web servers.JunctionThe Junction tab contains entries that are related to the general junction configuration.FieldDescriptionHTTP TimeoutTimeout in seconds for sending to and reading from a TCP junction.HTTPS TimeoutTimeout in seconds for sending to and reading from an SSL junction.Ping IntervalThe interval in seconds between requests which are sent by Reverse Proxy to junctioned Web servers to determine the state of the junctioned Web server.Ping MethodThe HTTP method that Reverse Proxy uses when it sends health check requests to the junctioned Web server.Ping URIThe URI that Reverse Proxy uses when it sends health check requests to the junctioned Web server.Maximum Cached Persistent ConnectionsThe maximum number of connections between Reverse Proxy and a junctioned Web server that will be cached for future use.Persistent Connection TimeoutThe maximum length of time, in seconds, that a cached connection with a junctioned Web server can remain idle before it is closed by Reverse Proxy.Managed Cookie ListA pattern-matched and comma-separated list of cookie names for those cookies which are stored in the Reverse Proxy cookie jar. Other cookies are passed by Reverse Proxy back to the client.AuthenticationThe Authentication tab contains entries that are related to the configuration of the authentication mechanisms which are used by the server.Basic AuthenticationFieldDescriptionTransportThe transport over which basic authentication is supported.Realm NameRealm name for basic authentication.Forms AuthenticationFieldDescriptionForms AuthenticationThe transport over which forms authentication is supported.Client Certificate AuthenticationFieldDescriptionAccept Client CertificatesDefines the condition under which client certificates are required by Reverse Proxy.Certificate EAI URIThe resource identifier of the application that is invoked to perform external client certificate authentication.Certificate DataThe client certificate data that are passed to the EAI application.Kerberos AuthenticationFieldDescriptionTransportThe transport over which Kerberos authentication is supported.Keytab FileName of the Kerberos keytab file. The keytab file must contain each of the service principal names used for SPNEGO authentication.Use Domain Qualified NameKerberos authentication provides a principal name in the form of shortname@domain.com. By default, only the shortname is used as the Security Access Manager user ID. If this checkbox is selected, then the domain is also included as part of the Security Access Manager user ID.Kerberos Service NamesThe list of Kerberos service principal names used for the server.The first service name in the list is the default service name. To make a service name the default, select the service name and then click Default.EAI AuthenticationFieldDescriptionTransportThe transport over which EAI authentication is supported.Trigger URLA URL pattern that is used by Reverse Proxy to determine whether a response is examined for EAI authentication headers.Authentication LevelsThe designated authentication level for each of the configuration authentication mechanisms. Token AuthenticationFieldDescriptionTransportThe transport over which RSA authentication is supported.You can also click Go to RSA Configuration to access the RSA Configuration page.SessionThe Session tab contains entries that are related to the general session configuration.FieldDescriptionRe-authentication for InactiveWhether to prompt users to re-authenticate if their entry in the server credential cache has timed out because of inactivity.Max Cache EntriesThe maximum number of concurrent entries in the session cache.Lifetime TimeoutMaximum lifetime in seconds for an entry in the session cache.Inactivity TimeoutThe maximum time, in seconds, that a session can remain idle before it is removed from the session cache.TCP Session Cookie NameThe name of the cookie to be used to hold the HTTP session identifier.SSL Session Cookie NameThe name of the cookie to be used to hold HTTPS session identifier.Use Same SessionSelect the check box to use the same session for both HTTP and HTTPS requests.Enable Distributed Session CacheSelect the check box to enable distributed session cache on this reverse proxy instance.The appliance must be a part of an appliance cluster to enable the distributed session cache. Also, if the cluster configuration changes and a new master is specified, this option must be disabled and then re-enabled. The instance can then pick up the details of the new cluster configuration.ResponseThe Response tab contains entries that are related to response generation.FieldDescriptionEnable HTML RedirectSelect the check box to enable the HTML redirect function.Enable Local Response RedirectSelect the check box to enable the local response redirect function.Local Response Redirect URIWhen local response redirect is enabled, this field contains the URI to which the client is redirected for Reverse Proxy responses.Local Response Redirect MacrosThe macro information which is included in the local response redirect.SSOThe SSO tab contains entries that are related to the configuration of the different single-sign-on mechanisms that are used by the server.FailoverFieldDescriptionTransportThe transport over which failover authentication is supported.Cookies LifetimeMaximum lifetime in seconds for failover cookies.Cookies Key FileThe key file which is used to encrypt the failover cookie.LTPAFieldDescriptionTransportThe transport over which LTPA authentication is supported.Cookie NameThe name of the cookie which is used to transport the LTPA token.Key FileThe key file that is used when accessing LTPA cookies.Key File PasswordThe password that is used to access the LTPA key file.CDSSOFieldDescriptionTransportThe transport over which CDSSO authentication is supported.Transport (generation)The transport over which the creation of CDSSO tokens is supported.PeersThe name of the other Reverse Proxy servers that are participating in the CDSSO domain. Along with the name of the keyfile that are used by the Reverse Proxy servers.ECSSOFieldDescriptionTransportThe transport over which e-community SSO authentication is supported.NameName of the e-community.Is Master Authentication ServerSelect the check box if this Reverse Proxy server is the master for the e-community.Master Authentication ServerThe name of the Reverse Proxy server that acts as the master of the e-community. This field is not required if this Reverse Proxy server is designated as the master.Domain KeysThe name of the other Reverse Proxy servers which are participating in the e-community. Along with the name of the keyfile that is used by the various Reverse Proxy servers.LoggingThe Logging tab contains entries that are related to the logging and auditing configuration.FieldDescriptionEnable Agent LoggingSelect the check box to enable the agent log.Enable Referer LoggingSelect the check box to enable the referrer log.Enable Request LoggingSelect the check box to enable the request log.Request Log FormatThe format of the entries that are contained within the request log.Maximum Log SizeThe maximum size of the log file before it is rolled over.Flush TimeThe period, in seconds, that Reverse Proxy caches the log entries before the system writes the entries to the log file.Enable Audit LogSelect the check box to enable the generation of audit events.Audit Log TypeSelect the events to be audited.Audit Log SizeThe maximum size of the audit log file before it is rolled over.Audit Log FlushThe period, in seconds, that Reverse Proxy caches the audit log entries before the system writes the entries to the log file.InterfacesThe Interfaces tab contains settings that are related to WebSEAL secondary interfaces.To add a new secondary interface, click New. Then, define your settings in the pop-up window that contains the following fields:FieldDescriptionApplication Interface IP AddressThe IP address on which the WebSEAL instance listens for requests.HTTP PortThis field contains the port on which the WebSEAL instance listens for HTTP requests.HTTPS PortThis field contains the port on which the WebSEAL instance listens for HTTPS requests.Web HTTP PortThis is the port that the client perceives WebSEAL to be using.Web HTTP ProtocolThis is the protocol that the client perceives WebSEAL to be using.Certificate LabelThe label of the SSL server certificate that is presented to the client by the WebSEAL instance.Accept Client CertificatesDefines the condition under which client certificates are required by WebSEAL.Worker ThreadsThe number of threads that is allocated to service requests.Click Save to save the settings.To delete a secondary interface, select the interface and then click Delete.To edit a secondary interface, select the interface and click Edit. Then, update your settings in the pop-up window that contains the fields that described previously.Click Save to apply the changes.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Managing web reverse proxy configuration entries

To manage the web reverse proxy basic configuration, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Edit.

Make your changes to the settings on the Server, SSL, Junction, Authentication, SSO, Session, Response, Logging, and Interfaces tabs.

Server

The Server tab contains entries that are related to the general server configuration.

Field | Description
HTTPS | Select this check box to enable the HTTPS port within Reverse Proxy.
HTTPS Port | The port over which Reverse Proxy listens for HTTPS requests.
HTTP | Select this check box to enable the HTTP port within Reverse Proxy.
HTTP Port | The port over which Reverse Proxy listens for HTTP requests.
Interface Address | The network interface on which the Reverse Proxy server listens for requests.
Persistent Connection Timeout | The maximum number of seconds that a persistent connection with a client can remain inactive before it is closed by the server.
Worker Threads | The number of threads that are allocated to service requests.
Cluster is Master | If the Reverse Proxy clustering function is used, this check box controls whether this Reverse Proxy server acts as the cluster master.
Master Instance Name | The server name for the Reverse Proxy instance which is acting as the master within the cluster. This option is only enabled if the Cluster is Master check box is not selected.
Message Locale | The locale in which the Reverse Proxy runs.

SSL

The SSL tab contains entries that are related to the general SSL configuration of the server.

Field | Description
SSL Certificate Key File | The key database that is used to store the certificates which are presented by Reverse Proxy to the client.
Network HSM Key File | The key database that stores the certificates to be used by the network Hardware Security Module (HSM) device.
SSL Server Certificate | The name of the SSL certificate, within the key database, which is presented to the client. The drop-down list includes certificates from both the local and network key files. The certificates from the network key file are prefixed with the token label for the network HSM device.
JCT Certificate Key File | The key database that is used to store the certificates which are presented by Reverse Proxy to the junctioned Web servers.

Junction

The Junction tab contains entries that are related to the general junction configuration.

Field | Description
HTTP Timeout | Timeout in seconds for sending to and reading from a TCP junction.
HTTPS Timeout | Timeout in seconds for sending to and reading from an SSL junction.
Ping Interval | The interval in seconds between requests which are sent by Reverse Proxy to junctioned Web servers to determine the state of the junctioned Web server.
Ping Method | The HTTP method that Reverse Proxy uses when it sends health check requests to the junctioned Web server.
Ping URI | The URI that Reverse Proxy uses when it sends health check requests to the junctioned Web server.
Maximum Cached Persistent Connections | The maximum number of connections between Reverse Proxy and a junctioned Web server that will be cached for future use.
Persistent Connection Timeout | The maximum length of time, in seconds, that a cached connection with a junctioned Web server can remain idle before it is closed by Reverse Proxy.
Managed Cookie List | A pattern-matched and comma-separated list of cookie names for those cookies which are stored in the Reverse Proxy cookie jar. Other cookies are passed by Reverse Proxy back to the client.

Authentication

The Authentication tab contains entries that are related to the configuration of the authentication mechanisms which are used by the server.

Basic Authentication

Field | Description
Transport | The transport over which basic authentication is supported.
Realm Name | Realm name for basic authentication.

Forms Authentication

Field | Description
Forms Authentication | The transport over which forms authentication is supported.

Client Certificate Authentication

Field | Description
Accept Client Certificates | Defines the condition under which client certificates are required by Reverse Proxy.
Certificate EAI URI | The resource identifier of the application that is invoked to perform external client certificate authentication.
Certificate Data | The client certificate data that are passed to the EAI application.

Kerberos Authentication

Field
Description

Transport
The transport over which Kerberos authentication is supported.

Keytab File
Name of the Kerberos keytab file. The keytab file must contain each of the service principal names used for SPNEGO authentication.

Use Domain Qualified Name
Kerberos authentication provides a principal name in the form of "shortname@domain.com". By default, only the shortname is used as the Security Access Manager user ID. If this checkbox is selected, then the domain is also included as part of the Security Access Manager user ID.

Kerberos Service Names

The list of Kerberos service principal names used for the server.

The first service name in the list is the default service name. To make a service name the default, select the service name and then click Default.

EAI Authentication

Field | Description
Transport | The transport over which EAI authentication is supported.
Trigger URL | A URL pattern that is used by Reverse Proxy to determine whether a response is examined for EAI authentication headers.
Authentication Levels | The designated authentication level for each of the configuration authentication mechanisms.

Token Authentication

Field | Description
Transport | The transport over which RSA authentication is supported.

You can also click Go to RSA Configuration to access the RSA Configuration page.

Session

The Session tab contains entries that are related to the general session configuration.

Field
Description

Re-authentication for Inactive
Whether to prompt users to re-authenticate if their entry in the server credential cache has timed out because of inactivity.

Max Cache Entries
The maximum number of concurrent entries in the session cache.

Lifetime Timeout
Maximum lifetime in seconds for an entry in the session cache.

Inactivity Timeout
The maximum time, in seconds, that a session can remain idle before it is removed from the session cache.

TCP Session Cookie Name
The name of the cookie to be used to hold the HTTP session identifier.

SSL Session Cookie Name
The name of the cookie to be used to hold HTTPS session identifier.

Use Same Session
Select the check box to use the same session for both HTTP and HTTPS requests.

Enable Distributed Session Cache
Select the check box to enable distributed session cache on this reverse proxy instance.

Note: The appliance must be a part of an appliance cluster to enable the distributed session cache. Also, if the cluster configuration changes and a new master is specified, this option must be disabled and then re-enabled. The instance can then pick up the details of the new cluster configuration.

Response

The Response tab contains entries that are related to response generation.

Field | Description
Enable HTML Redirect | Select the check box to enable the HTML redirect function.
Enable Local Response Redirect | Select the check box to enable the local response redirect function.
Local Response Redirect URI | When local response redirect is enabled, this field contains the URI to which the client is redirected for Reverse Proxy responses.
Local Response Redirect Macros | The macro information which is included in the local response redirect.

SSO

The SSO tab contains entries that are related to the configuration of the different single-sign-on mechanisms that are used by the server.

Failover

Field | Description
Transport | The transport over which failover authentication is supported.
Cookies Lifetime | Maximum lifetime in seconds for failover cookies.
Cookies Key File | The key file which is used to encrypt the failover cookie.

LTPA

Field | Description
Transport | The transport over which LTPA authentication is supported.
Cookie Name | The name of the cookie which is used to transport the LTPA token.
Key File | The key file that is used when accessing LTPA cookies.
Key File Password | The password that is used to access the LTPA key file.

CDSSO

Field | Description
Transport | The transport over which CDSSO authentication is supported.
Transport (generation) | The transport over which the creation of CDSSO tokens is supported.
Peers | The name of the other Reverse Proxy servers that are participating in the CDSSO domain. Along with the name of the keyfile that are used by the Reverse Proxy servers.

ECSSO

Field | Description
Transport | The transport over which e-community SSO authentication is supported.
Name | Name of the e-community.
Is Master Authentication Server | Select the check box if this Reverse Proxy server is the master for the e-community.
Master Authentication Server | The name of the Reverse Proxy server that acts as the master of the e-community. This field is not required if this Reverse Proxy server is designated as the master.
Domain Keys | The name of the other Reverse Proxy servers which are participating in the e-community. Along with the name of the keyfile that is used by the various Reverse Proxy servers.

Logging

The Logging tab contains entries that are related to the logging and auditing configuration.

Field | Description
Enable Agent Logging | Select the check box to enable the agent log.
Enable Referer Logging | Select the check box to enable the referrer log.
Enable Request Logging | Select the check box to enable the request log.
Request Log Format | The format of the entries that are contained within the request log.
Maximum Log Size | The maximum size of the log file before it is rolled over.
Flush Time | The period, in seconds, that Reverse Proxy caches the log entries before the system writes the entries to the log file.
Enable Audit Log | Select the check box to enable the generation of audit events.
Audit Log Type | Select the events to be audited.
Audit Log Size | The maximum size of the audit log file before it is rolled over.
Audit Log Flush | The period, in seconds, that Reverse Proxy caches the audit log entries before the system writes the entries to the log file.

Interfaces

The Interfaces tab contains settings that are related to WebSEAL secondary interfaces.

To add a new secondary interface, click New. Then, define your settings in the pop-up window that contains the following fields:

Field | Description
Application Interface IP Address | The IP address on which the WebSEAL instance listens for requests.
HTTP Port | This field contains the port on which the WebSEAL instance listens for HTTP requests.
HTTPS Port | This field contains the port on which the WebSEAL instance listens for HTTPS requests.
Web HTTP Port | This is the port that the client perceives WebSEAL to be using.
Web HTTP Protocol | This is the protocol that the client perceives WebSEAL to be using.
Certificate Label | The label of the SSL server certificate that is presented to the client by the WebSEAL instance.
Accept Client Certificates | Defines the condition under which client certificates are required by WebSEAL.
Worker Threads | The number of threads that is allocated to service requests.

Click Save to save the settings.

To delete a secondary interface, select the interface and then click Delete.

To edit a secondary interface, select the interface and click Edit. Then, update your settings in the pop-up window that contains the fields that described previously.

Click Save to apply the changes.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Reverse proxy instance management

Managing web reverse proxy configuration filesAccess Manager Appliance: Managing web reverse proxy configuration filesTo manage reverse proxy configurations with the local management interface, use the Reverse Proxy management page.Web Reverse Proxyconfigurationfilesreverse proxyconfigurationchangesconfigurationFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select ManageConfigurationEdit Configuration File.Edit the configuration file that is displayed and then click Save to save the changes. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert. Tip: When you are editing the configuration file, you can use the search function of the browser to locate a string. For example, press Ctrl+F. For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. . Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Managing web reverse proxy configuration files

To manage reverse proxy configurations with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Manage > Configuration > Edit Configuration File.

Edit the configuration file that is displayed and then click Save to save the changes. If you do not want to save the changes, click Cancel. If you want to revert to the previous version of the configuration file, click Revert.

Tip: When you are editing the configuration file, you can use the search function of the browser to locate a string. For example, press Ctrl+F.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Reverse proxy instance management

Exporting WebSEAL configurationExporting WebSEAL configurationExporting WebSEAL configurationExport the configuration bundle of WebSEAL from the appliance so that you can migrate the WebSEAL instances between different appliances.web reverse proxy exportingFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select ManageConfigurationExport Configuration.Confirm the save operation when your browser displays a confirmation window.Migrating an existing WebSEAL instance to the applianceYou can migrate an existing WebSEAL instance to the appliance. Migrating an existing Security Access Manager environment to the applianceYou can migrate an existing Security Access Manager environment to the appliance with the provided mechanism. Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Exporting WebSEAL configuration

Export the configuration bundle of WebSEAL from the appliance so that you can migrate the WebSEAL instances between different appliances.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Manage > Configuration > Export Configuration.

Confirm the save operation when your browser displays a confirmation window.

Parent topic: Reverse proxy instance management

Related tasks:

Migrating an existing WebSEAL instance to the appliance

Migrating an existing Security Access Manager environment to the appliance

Configuring web application firewall Access Manager Appliance: Configuring web application firewall To configure web application firewall with the local management interface, use the Reverse Proxy management page.webapplication firewallcontent protectionauthenticationmutualdefaultactionsserversremoteauthorizationSyslogtrafficclientsnetworksFrom the top menu, select Secure Web Settings ManageReverse Proxy.Select the Reverse Proxy instance to configure web application firewall for.Click ManageConfigurationWeb Content Protection.On the Operating Configuration tab, you can configure general Web Content Protection settings.Select the Enable Web Content Protection check box to turn on the web application firewall.To run the firewall in a simulation mode without actually affecting the client traffic, select the Enable Simulation Mode check box. When the simulation mode is enabled, any detected issues are audited and then ignored. You can preview the issues that are detected and adjust the settings if necessary before any real actions are taken against the offending requests.Select the Use Proxy HTTP Header check box as needed.This is used to control whether the audit log contains the IP address of the client as obtained from the network connection, or the IP address that is obtained from the x-forwarded-for HTTP header. This setting is useful when a network terminating firewall sits between the reverse proxy and the client.Provide a value in bytes for the Maximum Memory Size field. This defines the maximum memory that can be used by the PAM engine. PAM has a pre-defined minimum memory size. If the configured value is set to less than the minimum, the allocated memory is automatically increased to this minimum size.Under Resource Actions:Use this table to customize the actions that are taken when issues are encountered for a particular resource. This is a pattern-matched list that is searched in order. The resource name can contain the * and ? pattern-matching characters. If no matching resource is found, the default actions, as recommended by the x-force team, are taken.To add a resource:Click New.On the Add Custom Resource page, provide the resource name. All issues available to the resource are pre-populated.Resource names can contain the * and ? pattern-matching characters. For example, *.html.Select an issue that you want to modify and then click Edit.On the Edit Custom Resource Issue page, select the action to take against this issue in the Response field.Optional: If Quarantine is selected as the event response in the previous step, specify the quarantine time in the Quarantine Period field.Click Save on the Edit Custom Resource Issue page.Click Save on the Add Custom Resource page.To edit a resource:Select the resource name to edit.Click Edit.On the Edit Custom Resource page, select the issue that you want to modify and then click Edit.On the Edit Custom Resource Issue page, modify the event response and quarantine time as needed.Click Save on the Edit Custom Resource Issue page.Click Save on the Edit Custom Resource page.To delete a resource:Select the resource name to delete.Click Delete.There is no confirmation window for this delete operation. Make sure that the selected resource is the one you want to delete before you click Delete.Under Registered Resources:The registered resources are used to designate the requests that are passed to the inspection engine. When a request is received by the Web reverse proxy, the entries in the list is sequentially searched until a match is found. The action that is assigned to the matching resource controls whether the inspection is enabled or disabled. The resources can contain wildcard characters for pattern matching.To add a registered resource:Click New.On the Add Protected Resources page that pops up, provide the Resource Name. For example, index.html, *.html or *.gif.Select Enabled or Disabled as needed. Click Save.To edit a registered resource:Select the resource to edit from the list.Click Edit.On the Edit Protected Resources page that pops up, modify the resource name and whether it is enabled as needed.Click Save.To delete a registered resourceSelect the resource to delete from the list.Click Delete.There is no confirmation window for this delete operation. Make sure that the selected resource is the one you want to delete before you click Delete.Under Injection Tuning Parameters, modify the listed parameters by double-clicking a value in the Units column and editing inline as needed. To see a description of each parameter, hover your mouse cursor on that parameter and a pop-up message that contains the description is displayed.On the Issues tab, you can enable or disable certain issues.The list of issues control the events that are monitored by the inspection engine. If an issue is disabled, the inspection engine no longer checks for this issue. Approach 1:Select the event to edit.Click Edit.On the Edit Issue page, select Enabled or Disabled as needed.Click Save.Approach 2:Select or clear the Enabled check box to enable or disable a particular issue.Approach 3:Click Trust X-Force to automatically disable all issues for which there is not a default response.On the Audit tab, you can configure logging and auditing settings.Under Log detailed audit events, select the check box if you want to enable logging for detailed audit events.Under Log Audit Events, select one of the options to indicate where the audit events are sent.Under Log Audit Config, define the following parameters based on the selections made in the previous step.If Log to File is selected:ParameterDescriptionFile NameThe entry specifies the name of the log file.Rollover SizeThe maximum size to which a log file can grow before it is rolled over. The default value is 2000000 bytes.Buffer SizeThe maximum size of the message that is used when smaller events are combined.Queue SizeThere is a delay between events being placed on the queue and the file log agent removing them. This parameter specifies the maximum size to which the queue is allowed to grow. High Water MarkProcessing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size reaching a high water mark on the event queue. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible.Flush IntervalThis entry controls the frequency with which the server asynchronously forces a flush of the file stream to disk. The value defined for this parameter is 0, < 0, or the flush interval in seconds.If Log to Remote Authorization Server is selected:ParameterDescriptionCompressTo reduce network traffic, use this parameter to compress buffers before transmission and expand on reception. The default value is no.Buffer SizeTo reduce network traffic, events are buffered into blocks of the nominated size before they are relayed to the remote server. This parameter specifies the maximum message size that the local program attempts to construct by combining smaller events into a large buffer. The default value is 1024 bytes.Flush IntervalThis parameter limits the time that a process waits to fill a consolidation buffer. The default value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.Queue SizeThere is a delay between events being placed on the queue and the file log agent removing them. This parameter specifies the maximum size to which the queue is allowed to grow. High Water MarkProcessing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size reaching a high water mark on the event queue. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible.Error Retry TimeoutIf a send operation to a remote service fails, the system tries again. Before the system tries again, it waits for the error retry timeout in seconds. The default value is 2 seconds.Logging PortConfigure the port parameter to specify the port that the remote authorization server listens on for remote logging requests. The default value is port 7136.Rebind RetryIf the remote authorization server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds. The default rebind retry timeout value is 300 seconds.HostnameThe remote logging services are offered by the authorization service. The server parameter nominates the hosts to which the authorization server process is bound for event recording. DNTo establish mutual authentication of the remote server, a distinguished name (DN) must be configured. A distinguished name must be specified as a string that is enclosed by double quotation marks.If Log to Remote Syslog Server is selected:ParameterDescriptionRemote Syslog ServerThe host to which the syslog server process is bound for event recording.PortThe port on which the remote syslog server listens for remote logging requests.Application IDThe name of the application, as it appears in the messages that are sent to the remote syslog server. Error Retry TimeoutIf a send operation to a remote service fails, the system tries again. Before the system tries again, it waits for the error retry timeout in seconds. The default value is 2 seconds.Flush IntervalThis parameter limits the time that a process waits to fill a consolidation buffer. The default value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.High Water MarkProcessing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size reaching a high water mark on the event queue. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible.Queue SizeThere is a delay between events being placed on the queue and the file log agent removing them. This parameter specifies the maximum size to which the queue is allowed to grow. Rebind RetryIf the remote system log server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds. The default rebind retry timeout value is 300 seconds.Maximum Event LengthThe maximum length of an event to be transmitted to the remote syslog server. If the event text is longer than the configured length, it is truncated to the maximum event length. If the maximum event length is zero, the event text is never truncated. If transmitting the event to the remote syslog server in clear text, set the maximum event length to less than the maximum transmission unit (MTU) for the network path to the server. This avoids fragmentation of the event.Enable SSL CommunicationWhether SSL is be used for communication. SSL KeyfileThe name of the GSKit key database file that contains the CA certificate. It is used when the system establishes a secure connection with the remote syslog server over TLS. If the Enable SSL Communication check box is selected, this field is required.SSL Certificate LabelThe name of the certificate to be presented to the remote syslog server, upon request, when the system establishes a secure connection. If no value is set for this field, the default certificate from the key database is used.On the Advanced Configuration tab, you can configure coalescer, inspection engine, issues, and custom actions.Under Coalescer Configuration:The coalescer is used to correlate audit events. The administrator can use these configuration settings to fine-tune the processing of the coalescer and thus reduce the number of messages that are sent to the audit log.To add a coalescer parameter:Click New.On the Add Coalescer Parameter page that pops up, provide the parameter name and value.Click Save.To edit a coalescer parameter:Select the parameter to edit from the list.Click Edit.On the Edit Coalescer Parameter page that pops up, modify the parameter name and value as needed.Click Save.To delete a coalescer parameter:Select the parameter to delete from the list.Click Delete.There is no confirmation window for this delete operation. Make sure that the selected parameter is the one you want to delete before you click Delete.Under Inspection Engine Configuration:To add a inspection engine configuration parameter:Click New.On the Add Inspection Parameter page that pops up, provide the parameter name and value.Click Save.To edit a inspection engine configuration parameter:Select the parameter to edit from the list.Click Edit.On the Edit Inspection Parameter page that pops up, modify the parameter name and value as needed.Click Save.To delete a inspection engine configuration parameter:Select the parameter to delete from the list.Click Delete.There is no confirmation window for this delete operation. Make sure that the selected resource is the one you want to delete before you click Delete.Click Save.Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Configuring web application firewall

To configure web application firewall with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the Reverse Proxy instance to configure web application firewall for.

Click Manage > Configuration > Web Content Protection.

On the Operating Configuration tab, you can configure general Web Content Protection settings.

Select the Enable Web Content Protection check box to turn on the web application firewall.

To run the firewall in a simulation mode without actually affecting the client traffic, select the Enable Simulation Mode check box. When the simulation mode is enabled, any detected issues are audited and then ignored. You can preview the issues that are detected and adjust the settings if necessary before any real actions are taken against the offending requests.

Select the Use Proxy HTTP Header check box as needed. This is used to control whether the audit log contains the IP address of the client as obtained from the network connection, or the IP address that is obtained from the x-forwarded-for HTTP header. This setting is useful when a network terminating firewall sits between the reverse proxy and the client.

Provide a value in bytes for the Maximum Memory Size field. This defines the maximum memory that can be used by the PAM engine.

Note: PAM has a pre-defined minimum memory size. If the configured value is set to less than the minimum, the allocated memory is automatically increased to this minimum size.

Under Resource Actions:

Note: Use this table to customize the actions that are taken when issues are encountered for a particular resource. This is a pattern-matched list that is searched in order. The resource name can contain the "*" and "?" pattern-matching characters. If no matching resource is found, the default actions, as recommended by the x-force team, are taken.

To add a resource:

Click New.

On the Add Custom Resource page, provide the resource name. All issues available to the resource are pre-populated.

Note: Resource names can contain the "*" and "?" pattern-matching characters. For example, *.html.

Select an issue that you want to modify and then click Edit.

On the Edit Custom Resource Issue page, select the action to take against this issue in the Response field.

Optional: If Quarantine is selected as the event response in the previous step, specify the quarantine time in the Quarantine Period field.

Click Save on the Edit Custom Resource Issue page.

Click Save on the Add Custom Resource page.

To edit a resource:

Select the resource name to edit.

Click Edit.

On the Edit Custom Resource page, select the issue that you want to modify and then click Edit.

On the Edit Custom Resource Issue page, modify the event response and quarantine time as needed.

Click Save on the Edit Custom Resource Issue page.

Click Save on the Edit Custom Resource page.

To delete a resource:

Select the resource name to delete.

Click Delete.

Note: There is no confirmation window for this delete operation. Make sure that the selected resource is the one you want to delete before you click Delete.

Under Registered Resources:

Note: The registered resources are used to designate the requests that are passed to the inspection engine. When a request is received by the Web reverse proxy, the entries in the list is sequentially searched until a match is found. The action that is assigned to the matching resource controls whether the inspection is enabled or disabled. The resources can contain wildcard characters for pattern matching.

To add a registered resource:

Click New.

On the Add Protected Resources page that pops up, provide the Resource Name. For example, index.html, *.html or *.gif.

Select Enabled or Disabled as needed.

Click Save.

To edit a registered resource:

Select the resource to edit from the list.

Click Edit.

On the Edit Protected Resources page that pops up, modify the resource name and whether it is enabled as needed.

Click Save.

To delete a registered resource

Select the resource to delete from the list.

Click Delete.

Note: There is no confirmation window for this delete operation. Make sure that the selected resource is the one you want to delete before you click Delete.

Under Injection Tuning Parameters, modify the listed parameters by double-clicking a value in the Units column and editing inline as needed. To see a description of each parameter, hover your mouse cursor on that parameter and a pop-up message that contains the description is displayed.

On the Issues tab, you can enable or disable certain issues.

Note: The list of issues control the events that are monitored by the inspection engine. If an issue is disabled, the inspection engine no longer checks for this issue.

Approach 1:

Select the event to edit.

Click Edit.

On the Edit Issue page, select Enabled or Disabled as needed.

Click Save.

Approach 2:

Select or clear the Enabled check box to enable or disable a particular issue.

Approach 3:

Click Trust X-Force to automatically disable all issues for which there is not a default response.

On the Audit tab, you can configure logging and auditing settings.

Under Log detailed audit events, select the check box if you want to enable logging for detailed audit events.

Under Log Audit Events, select one of the options to indicate where the audit events are sent.

Under Log Audit Config, define the following parameters based on the selections made in the previous step.

If Log to File is selected:

Parameter
Description

File Name
The entry specifies the name of the log file.

Rollover Size
The maximum size to which a log file can grow before it is rolled over. The default value is 2000000 bytes.

Buffer Size
The maximum size of the message that is used when smaller events are combined.

Queue Size
There is a delay between events being placed on the queue and the file log agent removing them. This parameter specifies the maximum size to which the queue is allowed to grow.

High Water Mark
Processing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size reaching a high water mark on the event queue. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible.

Flush Interval
This entry controls the frequency with which the server asynchronously forces a flush of the file stream to disk. The value defined for this parameter is 0, < 0, or the flush interval in seconds.

If Log to Remote Authorization Server is selected:

Parameter
Description

Compress
To reduce network traffic, use this parameter to compress buffers before transmission and expand on reception. The default value is no.

Buffer Size
To reduce network traffic, events are buffered into blocks of the nominated size before they are relayed to the remote server. This parameter specifies the maximum message size that the local program attempts to construct by combining smaller events into a large buffer. The default value is 1024 bytes.

Flush Interval
This parameter limits the time that a process waits to fill a consolidation buffer. The default value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.

Queue Size
There is a delay between events being placed on the queue and the file log agent removing them. This parameter specifies the maximum size to which the queue is allowed to grow.

High Water Mark
Processing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size reaching a high water mark on the event queue. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible.

Error Retry Timeout
If a send operation to a remote service fails, the system tries again. Before the system tries again, it waits for the error retry timeout in seconds. The default value is 2 seconds.

Logging Port
Configure the port parameter to specify the port that the remote authorization server listens on for remote logging requests. The default value is port 7136.

Rebind Retry
If the remote authorization server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds. The default rebind retry timeout value is 300 seconds.

Hostname
The remote logging services are offered by the authorization service. The server parameter nominates the hosts to which the authorization server process is bound for event recording.

DN
To establish mutual authentication of the remote server, a distinguished name (DN) must be configured. A distinguished name must be specified as a string that is enclosed by double quotation marks.

If Log to Remote Syslog Server is selected:

Parameter
Description

Remote Syslog Server
The host to which the syslog server process is bound for event recording.

Port
The port on which the remote syslog server listens for remote logging requests.

Application ID
The name of the application, as it appears in the messages that are sent to the remote syslog server.

Error Retry Timeout
If a send operation to a remote service fails, the system tries again. Before the system tries again, it waits for the error retry timeout in seconds. The default value is 2 seconds.

Flush Interval
This parameter limits the time that a process waits to fill a consolidation buffer. The default value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.

High Water Mark
Processing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size reaching a high water mark on the event queue. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible.

Queue Size
There is a delay between events being placed on the queue and the file log agent removing them. This parameter specifies the maximum size to which the queue is allowed to grow.

Rebind Retry
If the remote system log server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds. The default rebind retry timeout value is 300 seconds.

Maximum Event Length

The maximum length of an event to be transmitted to the remote syslog server. If the event text is longer than the configured length, it is truncated to the maximum event length. If the maximum event length is zero, the event text is never truncated. If transmitting the event to the remote syslog server in clear text, set the maximum event length to less than the maximum transmission unit (MTU) for the network path to the server. This avoids fragmentation of the event.

Enable SSL Communication
Whether SSL is be used for communication.

SSL Keyfile
The name of the GSKit key database file that contains the CA certificate. It is used when the system establishes a secure connection with the remote syslog server over TLS. If the Enable SSL Communication check box is selected, this field is required.

SSL Certificate Label
The name of the certificate to be presented to the remote syslog server, upon request, when the system establishes a secure connection. If no value is set for this field, the default certificate from the key database is used.

On the Advanced Configuration tab, you can configure coalescer, inspection engine, issues, and custom actions.

Under Coalescer Configuration:

Note: The coalescer is used to correlate audit events. The administrator can use these configuration settings to fine-tune the processing of the coalescer and thus reduce the number of messages that are sent to the audit log.

To add a coalescer parameter:

Click New.

On the Add Coalescer Parameter page that pops up, provide the parameter name and value.

Click Save.

To edit a coalescer parameter:

Select the parameter to edit from the list.

Click Edit.

On the Edit Coalescer Parameter page that pops up, modify the parameter name and value as needed.

Click Save.

To delete a coalescer parameter:

Select the parameter to delete from the list.

Click Delete.

Note: There is no confirmation window for this delete operation. Make sure that the selected parameter is the one you want to delete before you click Delete.

Under Inspection Engine Configuration:

To add a inspection engine configuration parameter:

Click New.

On the Add Inspection Parameter page that pops up, provide the parameter name and value.

Click Save.

To edit a inspection engine configuration parameter:

Select the parameter to edit from the list.

Click Edit.

On the Edit Inspection Parameter page that pops up, modify the parameter name and value as needed.

Click Save.

To delete a inspection engine configuration parameter:

Select the parameter to delete from the list.

Click Delete.

Note: There is no confirmation window for this delete operation. Make sure that the selected resource is the one you want to delete before you click Delete.

Click Save.

Parent topic: Reverse proxy instance management

Managing administration pagesAccess Manager Appliance: Work with the administration pages rootTo manage files and directories in the administration pages root with the local management interface, use the Reverse Proxy management page.administration pages rootfilesdirectoriesdefaultdirectoriesWeb Reverse ProxymanagementFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select ManageManagement Root.All current management files and directories are displayed. The default directories include:managementThe Web Reverse proxy management pages. For example, login.htmlerrorsThe error pages that can be returned by the Web Reverse proxy.oauth The HTML files that can be returned by the oauth module.junction-rootThe static HTML files that are served by the local junction of the Web Reverse proxy.A fixed location is used as the document root. A local junction cannot run any CGI scripts. It can serve only static page content.Work with all the management files and directories.Create a new file in the administration pages rootSelect the directory in which you want to create the file.Select FileNewFile.Enter the file name.Optionally, you can add file contents in the New File Contents field.Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Create a new directory in the administration pages rootSelect the directory in which to create the directory.Select FileNewDirectory.Enter the directory name.Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .View or update the contents of a file in the administration pages rootSelect the file of interest.Select FileOpen. You can then view the contents of the file.Optionally, edit the contents of the file. Then, click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Export a file from the administration pages rootSelect the file of interest.Select ManageExport. You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation when your browser displays a confirmation window.Rename a file or directory in the administration pages rootSelect the file or directory of interest.Select ManageRename. Enter the new name of the file or directory in the New Resource Name field.Click Save.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Delete a file or directory in the administration pages rootSelect the file or directory of interest.Select ManageDelete. Click Yes to confirm the delete operation.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Import a file to administration pages rootSelect the directory that you want to import the file into.Select ManageImport. Click Browse. Browse to the file you want to import and then click Open.Click Import.Import the contents of a .zip file into the administration pages rootSelect ManageImport Zip.Click Browse. Browse to the .zip file you want to import and then click Open.Click Import.Export the contents of the administration pages root as a .zip fileSelect ManageExport Zip. You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation when your browser displays a confirmation window.Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Managing administration pages

To manage files and directories in the administration pages root with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Manage > Management Root. All current management files and directories are displayed. The default directories include:

management

The Web Reverse proxy management pages. For example, login.html

errors

The error pages that can be returned by the Web Reverse proxy.

oauth

The HTML files that can be returned by the oauth module.

junction-root

The static HTML files that are served by the local junction of the Web Reverse proxy.

Note: A fixed location is used as the document root. A local junction cannot run any CGI scripts. It can serve only static page content.

Work with all the management files and directories.

Create a new file in the administration pages root

Select the directory in which you want to create the file.

Select File > New > File.

Enter the file name.

Optionally, you can add file contents in the New File Contents field.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Create a new directory in the administration pages root

Select the directory in which to create the directory.

Select File > New > Directory.

Enter the directory name.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

View or update the contents of a file in the administration pages root

Select the file of interest.

Select File > Open. You can then view the contents of the file.

Optionally, edit the contents of the file. Then, click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Export a file from the administration pages root

Select the file of interest.

Select Manage > Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation when your browser displays a confirmation window.

Rename a file or directory in the administration pages root

Select the file or directory of interest.

Select Manage > Rename.

Enter the new name of the file or directory in the New Resource Name field.

Click Save.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Delete a file or directory in the administration pages root

Select the file or directory of interest.

Select Manage > Delete.

Click Yes to confirm the delete operation.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Import a file to administration pages root

Select the directory that you want to import the file into.

Select Manage > Import.

Click Browse.

Browse to the file you want to import and then click Open.

Click Import.

Import the contents of a .zip file into the administration pages root

Select Manage > Import Zip.

Click Browse.

Browse to the .zip file you want to import and then click Open.

Click Import.

Export the contents of the administration pages root as a .zip file

Select Manage > Export Zip.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation when your browser displays a confirmation window.

Parent topic: Reverse proxy instance management

Renewing web reverse proxy management certificatesRenew the management certificate of a web reverse proxy instance.An SSL certificate is used to authenticate the web reverse proxy instance to the policy server. Use this option to automatically generate a new certificate that can be used in this communication.From the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance to update the management certificate for.Select ManageRenew Management Certificate.Enter your administrator name and password.Click Renew.Reverse proxy instance managementIn the local management interface, go to Secure Web SettingsManageReverse Proxy. A list of all instances and their current states is displayed.

Renewing web reverse proxy management certificates

Renew the management certificate of a web reverse proxy instance.

About this task

An SSL certificate is used to authenticate the web reverse proxy instance to the policy server. Use this option to automatically generate a new certificate that can be used in this communication.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance to update the management certificate for.

Select Manage > Renew Management Certificate.

Enter your administrator name and password.

Click Renew.

Parent topic: Reverse proxy instance management

Reverse proxy statusAccess Manager Appliance: Statistics controlYou can use the local management interface (LMI) to manage status and view statistics. statisticscontrolcontrolstatisticsWeb Security Gateway Appliancestatisticsdetailsstatistics componentsWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Showing the current state of all instancesTo show the current state of all instances with the local management interface, use the Reverse Proxy management page.Modifying the statistics settings for a componentTo modify the statistics settings for a particular component with the local management interface, use the Reverse Proxy management page.Managing statistics log filesTo manage statistics log files with the local management interface, use the Reverse Proxy management page.Archiving and deleting reverse proxy log files with the command-line interfaceUse the logs option in the command-line interface to archive Web Reverse Proxy log files to a USB device and then delete old log files to free up disk space.Viewing reverse proxy trafficTo view flow data at an instance-specific level with the local management interface, use the Reverse Proxy Traffic management page.Viewing reverse proxy throughputTo view flow data at an appliance-wide level with the local management interface, use the Reverse Proxy Throughput management page or the Reverse Proxy Throughput widget on the dashboard.Viewing reverse proxy health statusThe health status of a reverse proxy is determined by the state of instances, junctions, and junctioned servers. You can view the health status information with the Reverse Proxy Health dashboard widget.Viewing front-end load balancer health statusThe health status of a front-end load balancer is determined by the state of the load balanced servers. You can view the health status information with the Load Balancer Health dashboard widget.Viewing average response time statisticsThe Web Reverse Proxy can be configured to record transaction logs. One of the attributes that is recorded is the average request response time. This information is recorded at a per-junction level. To view a summary of the average response time that has been recorded, use the Average Response Time widget.Viewing security action statisticsThe Web Reverse Proxy can be configured to perform inspections on web content, searching for potential malicious requests (known as issues). It can then take certain defensive actions against any discovered issues. A summary of the defensive actions that have been taken can be viewed by using the Security Actions widget.

Reverse proxy status

You can use the local management interface (LMI) to manage status and view statistics.

Showing the current state of all instances
To show the current state of all instances with the local management interface, use the Reverse Proxy management page.

Modifying the statistics settings for a component
To modify the statistics settings for a particular component with the local management interface, use the Reverse Proxy management page.

Managing statistics log files
To manage statistics log files with the local management interface, use the Reverse Proxy management page.

Archiving and deleting reverse proxy log files with the command-line interface
Use the logs option in the command-line interface to archive Web Reverse Proxy log files to a USB device and then delete old log files to free up disk space.

Viewing reverse proxy traffic
To view flow data at an instance-specific level with the local management interface, use the Reverse Proxy Traffic management page.

Viewing reverse proxy throughput
To view flow data at an appliance-wide level with the local management interface, use the Reverse Proxy Throughput management page or the Reverse Proxy Throughput widget on the dashboard.

Viewing reverse proxy health status
The health status of a reverse proxy is determined by the state of instances, junctions, and junctioned servers. You can view the health status information with the Reverse Proxy Health dashboard widget.

Viewing front-end load balancer health status
The health status of a front-end load balancer is determined by the state of the load balanced servers. You can view the health status information with the Load Balancer Health dashboard widget.

Viewing average response time statistics
The Web Reverse Proxy can be configured to record transaction logs. One of the attributes that is recorded is the average request response time. This information is recorded at a per-junction level. To view a summary of the average response time that has been recorded, use the Average Response Time widget.

Viewing security action statistics
The Web Reverse Proxy can be configured to perform inspections on web content, searching for potential malicious requests (known as issues). It can then take certain defensive actions against any discovered issues. A summary of the defensive actions that have been taken can be viewed by using the Security Actions widget.

Parent topic: Web Reverse Proxy administration

Showing the current state of all instancesAccess Manager Appliance: Showing the current state of all instancesTo show the current state of all instances with the local management interface, use the Reverse Proxy management page.instancesshowing current statereverse proxyinstancesshowing current stateFrom the top menu, select Secure Web SettingsManageReverse Proxy.You can view the current state and version information of all instances.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Showing the current state of all instances

To show the current state of all instances with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

You can view the current state and version information of all instances.

Parent topic: Reverse proxy status

Modifying the statistics settings for a componentAccess Manager Appliance: Modifying the statistics settings for a componentTo modify the statistics settings for a particular component with the local management interface, use the Reverse Proxy management page.statisticssettingscomponentsmodifying statistics settingssettingsstatisticsFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select ManageTroubleshootingStatistics.Select the statistics component that you want to modify.Click Edit.Select the check box beside Enabled if it is not already checked.Modify the Interval, Count, Flush Interval, Rollover Size, Maximum Rollover Files, and Compress fields as needed.By default, the Compress option is set to No. To save disk space, set the Compress option to Yes so that all rollover files are automatically compressed.Click Save to save your changes.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Modifying the statistics settings for a component

To modify the statistics settings for a particular component with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Manage > Troubleshooting > Statistics.

Select the statistics component that you want to modify.

Click Edit.

Select the check box beside Enabled if it is not already checked.

Modify the Interval, Count, Flush Interval, Rollover Size, Maximum Rollover Files, and Compress fields as needed. By default, the Compress option is set to No. To save disk space, set the Compress option to Yes so that all rollover files are automatically compressed.

Click Save to save your changes.

Parent topic: Reverse proxy status

Managing statistics log filesAccess Manager Appliance: Managing statistics log filesTo manage statistics log files with the local management interface, use the Reverse Proxy management page.statisticslog fileslog filesstatisticsFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select ManageTroubleshootingStatistics.Select the statistics component of interest.Click Files. The file name, file size, and last modified time information of all statistics log files is displayed.View a statistics log file or a snippet of a statistics log fileSelect the statistics log file that you want to view and then click View. The contents of the statistics log file are displayed.You can enter a value into the Number of lines to view field and then click Reload to get a customized snippet view of the log file. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.Export a statistics log fileSelect the statistics log file that you want to export.Click ManageExport.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation in the browser window displayed.Delete a statistics log fileSelect the statistics log file that you want to delete and then click Delete. Only log files that are not in use can be deleted. To disable a log file, you can select the log file, click Edit, clear the Enabled check box, and then click Save.Click Yes to confirm the operation.Delete all unused statistics log filesClick ManageDelete All.Click Yes to confirm the operation.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Managing statistics log files

To manage statistics log files with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Manage > Troubleshooting > Statistics.

Select the statistics component of interest.

Click Files. The file name, file size, and last modified time information of all statistics log files is displayed.

View a statistics log file or a snippet of a statistics log file

Select the statistics log file that you want to view and then click View. The contents of the statistics log file are displayed.

You can enter a value into the Number of lines to view field and then click Reload to get a customized snippet view of the log file. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.

Note: The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.

Export a statistics log file

Select the statistics log file that you want to export.

Click Manage > Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation in the browser window displayed.

Delete a statistics log file

Select the statistics log file that you want to delete and then click Delete.

Note: Only log files that are not in use can be deleted. To disable a log file, you can select the log file, click Edit, clear the Enabled check box, and then click Save.

Click Yes to confirm the operation.

Delete all unused statistics log files

Click Manage > Delete All.

Click Yes to confirm the operation.

Parent topic: Reverse proxy status

Archiving and deleting reverse proxy log files with the command-line interfaceAccess Manager Appliance: Archiving and deleting Web Reverse Proxy log files with the command-line interfaceUse the logs option in the command-line interface to archive Web Reverse Proxy log files to a USB device and then delete old log files to free up disk space.log filesarchivingdeletingarchivingCLIWeb Reverse Proxy log filesWeb Reverse Proxylog filesarchivingdeletingUSB devicesdisk spacereverse proxyarchivingdeletingIn the command-line interface, go to isamlogs.Optional: Enter help to display all available commands.Current mode commands: archive Archive the log files to a USB device. delete Delete the log files which have been rolled over by the system. Global commands: back Return to the previous command mode. exit Log off from the appliance. help Display information for using the specified command. reboot Reboot the appliance. shutdown End system operation and turn off the power. top Return to the top level.Archive or delete the log files.Archive the log files to a USB deviceEnter archive to save the log files to a USB device.Insert a USB device into the USB port of the appliance.Enter YES to start the archive operation. A list of archived files are displayed, along with a message that indicates when the archive operation has completed. Example output is shown as follows:updating: var/PolicyDirector/log/ (stored 0%) updating: var/PolicyDirector/log/msg__pdmgrd_utf8.log (deflated 85%) updating: var/PolicyDirector/log/PDMgr_config_start.log (deflated 37%) updating: var/PolicyDirector/log/ivmgrd.pid (stored 0%) updating: var/pdweb/default/log/ (stored 0%) updating: var/pdweb/default/log/iss-pam1.so (deflated 59%) updating: var/pdweb/default/log/webseald-default.pid (stored 0%) updating: var/pdweb/default/log/config_data__default -webseald-felbb.wga.gc.au.ibm.com.log (deflated 92%) updating: var/pdweb/default/log/referer.log (stored 0%) updating: var/pdweb/default/log/msg__webseald-default.log (deflated 89%) updating: var/pdweb/default/log/pam.log (deflated 98%) updating: var/pdweb/default/log/agent.log (stored 0%) updating: var/pdweb/default/log/request.log (stored 0%) The log files have been successfully archived to the USB drive: iswga_logs.zip. It is now safe to remove the USB drive.Remove the USB device from the USB port.Delete the log filesEnter delete to purge all log files that are rolled over.Enter YES to confirm the delete operation.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Archiving and deleting reverse proxy log files with the command-line interface

Use the logs option in the command-line interface to archive Web Reverse Proxy log files to a USB device and then delete old log files to free up disk space.

Procedure

In the command-line interface, go to isam > logs.

Optional: Enter help to display all available commands.

Current mode commands:
archive         Archive the log files to a USB device.
delete          Delete the log files which have been rolled over by the system.
Global commands:
back            Return to the previous command mode.
exit            Log off from the appliance.
help            Display information for using the specified command.
reboot          Reboot the appliance.
shutdown        End system operation and turn off the power.
top             Return to the top level.

Archive or delete the log files.

Archive the log files to a USB device

Enter archive to save the log files to a USB device.

Insert a USB device into the USB port of the appliance.

Enter YES to start the archive operation. A list of archived files are displayed, along with a message that indicates when the archive operation has completed. Example output is shown as follows:

updating: var/PolicyDirector/log/ (stored 0%)
updating: var/PolicyDirector/log/msg__pdmgrd_utf8.log (deflated 85%)
updating: var/PolicyDirector/log/PDMgr_config_start.log (deflated 37%)
updating: var/PolicyDirector/log/ivmgrd.pid (stored 0%)
updating: var/pdweb/default/log/ (stored 0%)
updating: var/pdweb/default/log/iss-pam1.so (deflated 59%)
updating: var/pdweb/default/log/webseald-default.pid (stored 0%)
updating: var/pdweb/default/log/config_data__default
-webseald-felbb.wga.gc.au.ibm.com.log (deflated 92%)
updating: var/pdweb/default/log/referer.log (stored 0%)
updating: var/pdweb/default/log/msg__webseald-default.log (deflated 89%)
updating: var/pdweb/default/log/pam.log (deflated 98%)
updating: var/pdweb/default/log/agent.log (stored 0%)
updating: var/pdweb/default/log/request.log (stored 0%)
The log files have been successfully archived to the USB drive:
iswga_logs.zip. It is now safe to remove the USB drive.

Remove the USB device from the USB port.

Delete the log files

Enter delete to purge all log files that are rolled over.

Enter YES to confirm the delete operation.

Parent topic: Reverse proxy status

Viewing reverse proxy trafficViewing reverse proxy trafficAccess Manager Appliance: Viewing reverse proxy trafficTo view flow data at an instance-specific level with the local management interface, use the Reverse Proxy Traffic management page.reverse proxytrafficgraphstrafficreverse proxydataflowinstance-specificinstancesrangeflow datainstance-specificFrom the top menu, select Monitor Analysis and DiagnosticsReverse Proxy GraphsReverse Proxy Traffic.On the Reverse Proxy Traffic page, specify the settings for the chart displayed.InstanceThe instance which the data displayed are specific to.Aspect TypeThe type of chart to display the data with. Select one from Column and Lines, Column, and Lines.Start DateThe starting date.Start TimeThe starting time of the day.Date RangeThe duration over which data is collected and displayed. Select from 1 Hour to 30 Days.For example, if the date and time that is chosen is 04.12.2012 10.00 and the duration is 12 Hours, the data that are collected between 10:00 a.m. and 10:00 p.m. on 12th April 2012 are displayed.By default, data of the first instance in the instance list for the last 24 hours are displayed, grouped by junction.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Viewing reverse proxy traffic

To view flow data at an instance-specific level with the local management interface, use the Reverse Proxy Traffic management page.

Procedure

From the top menu, select Monitor Analysis and Diagnostics > Reverse Proxy Graphs > Reverse Proxy Traffic.

On the Reverse Proxy Traffic page, specify the settings for the chart displayed.

Instance

The instance which the data displayed are specific to.

Aspect Type

The type of chart to display the data with. Select one from Column and Lines, Column, and Lines.

Start Date

The starting date.

Start Time

The starting time of the day.

Date Range

The duration over which data is collected and displayed. Select from 1 Hour to 30 Days.

For example, if the date and time that is chosen is 04.12.2012 10.00 and the duration is 12 Hours, the data that are collected between 10:00 a.m. and 10:00 p.m. on 12th April 2012 are displayed.

By default, data of the first instance in the instance list for the last 24 hours are displayed, grouped by junction.

Parent topic: Reverse proxy status

Viewing reverse proxy throughputViewing reverse proxy throughputAccess Manager Appliance: Viewing reverse proxy throughputTo view flow data at an appliance-wide level with the local management interface, use the Reverse Proxy Throughput management page or the Reverse Proxy Throughput widget on the dashboard.reverse proxythroughputgraphsdataflowappliance-widerangedefaultdisplayflow dataappliance-wideWebSEALinstancesdisplayTo view the Reverse Proxy Throughput: From the dashboard, locate the Reverse Proxy Throughput widget.From the top menu, select Monitor Analysis and DiagnosticsReverse Proxy GraphsReverse Proxy Throughput. Specify the settings for the chart displayed.On the dashboard, select the duration over which data is collected and displayed with the Data Range list.On the Reverse Proxy Throughput page, use the following settings:Chart TypeThe type of chart to display the data with. Select one from Column and Lines, Column, and Lines.Date RangeThe duration over which data is collected and displayed. Select from 1 Hour to 30 Days.Start DateThe starting date.Start TimeThe starting time of the day. For example, if the date and time that is chosen is 04.12.2012 10.00 and the duration is 12 Hours, the data that are collected between 10:00 a.m. and 10:00 p.m. on 12 April 2012 are displayed.By default, data of all configured WebSEAL instances on this appliance from the last 24 hours are displayed.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Viewing reverse proxy throughput

To view flow data at an appliance-wide level with the local management interface, use the Reverse Proxy Throughput management page or the Reverse Proxy Throughput widget on the dashboard.

Procedure

To view the Reverse Proxy Throughput:

From the dashboard, locate the Reverse Proxy Throughput widget.

From the top menu, select Monitor Analysis and Diagnostics > Reverse Proxy Graphs > Reverse Proxy Throughput.

Specify the settings for the chart displayed.

On the dashboard, select the duration over which data is collected and displayed with the Data Range list.

On the Reverse Proxy Throughput page, use the following settings:

Chart Type

The type of chart to display the data with. Select one from Column and Lines, Column, and Lines.

Date Range

The duration over which data is collected and displayed. Select from 1 Hour to 30 Days.

Start Date

The starting date.

Start Time

The starting time of the day.

For example, if the date and time that is chosen is 04.12.2012 10.00 and the duration is 12 Hours, the data that are collected between 10:00 a.m. and 10:00 p.m. on 12 April 2012 are displayed.

By default, data of all configured WebSEAL instances on this appliance from the last 24 hours are displayed.

Parent topic: Reverse proxy status

Viewing reverse proxy health statusViewing reverse proxy health statusAccess Manager Appliance: Viewing reverse proxy health statusThe health status of a reverse proxy is determined by the state of instances, junctions, and junctioned servers. You can view the health status information with the Reverse Proxy Health dashboard widget.reverse proxyhealth statusjunctionshealth statushealth statusFrom the dashboard, locate the Reverse Proxy Health widget.The health status of each instance, its junctions, and the junctioned servers are displayed in a hierarchical structure. Health status is determined by the health of all elements lower than the current element in the hierarchy. An instance is unhealthy if it is stopped or pdadmin cannot contact it.A junction is unhealthy if it is disabled or pdadmin cannot return information for it.A junctioned server is unhealthy if it is disabled or offline.Each element can be in one of the three health states:IconStateDescriptionHealthyAll child elements are healthy.WarningThe element contains at least one unhealthy child element and at least one healthy child element.UnhealthyAll child elements are unhealthy.Optional: Click Refresh to refresh the health data.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Viewing reverse proxy health status

The health status of a reverse proxy is determined by the state of instances, junctions, and junctioned servers. You can view the health status information with the Reverse Proxy Health dashboard widget.

Procedure

From the dashboard, locate the Reverse Proxy Health widget.

The health status of each instance, its junctions, and the junctioned servers are displayed in a hierarchical structure. Health status is determined by the health of all elements lower than the current element in the hierarchy.

An instance is unhealthy if it is stopped or pdadmin cannot contact it.

A junction is unhealthy if it is disabled or pdadmin cannot return information for it.

A junctioned server is unhealthy if it is disabled or offline.

Each element can be in one of the three health states:

Icon
State
Description

Healthy
All child elements are healthy.

Warning
The element contains at least one unhealthy child element and at least one healthy child element.

Unhealthy
All child elements are unhealthy.

Optional: Click Refresh to refresh the health data.

Parent topic: Reverse proxy status

Viewing front-end load balancer health statusViewing front-end load balancer health statusAccess Manager Appliance: Viewing front-end load balancer health statusThe health status of a front-end load balancer is determined by the state of the load balanced servers. You can view the health status information with the Load Balancer Health dashboard widget.load balancershealth statusfront-end load balancershealth statusserversload-balancedhigh availabilityserviceshealth statushealth statusFrom the dashboard, locate the Load Balancer Health widget.Under High Availability (if high availability is configured):The first row displays the health status of the self front-end load balancer and whether it is active or passive.The second row displays the health status of the peer front-end load balancer and whether it is active or passive.Under Services (if at least one service is configured):The health status of the configured services and the load balanced servers are displayed in a hierarchical structure. You can expand a service to view the health status of the servers that are attached to this service.Each element can be in one of the following health states:IconStateDescriptionHealthyAll child elements are healthy.WarningThe element contains at least one unhealthy child element and at least one healthy child element.UnhealthyAll child elements are unhealthy.Optional: Click Refresh to refresh the health data.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Viewing front-end load balancer health status

The health status of a front-end load balancer is determined by the state of the load balanced servers. You can view the health status information with the Load Balancer Health dashboard widget.

Procedure

From the dashboard, locate the Load Balancer Health widget.

Under High Availability (if high availability is configured):

The first row displays the health status of the self front-end load balancer and whether it is active or passive.

The second row displays the health status of the peer front-end load balancer and whether it is active or passive.

Under Services (if at least one service is configured):

The health status of the configured services and the load balanced servers are displayed in a hierarchical structure. You can expand a service to view the health status of the servers that are attached to this service.

Each element can be in one of the following health states:

Icon
State
Description

Healthy
All child elements are healthy.

Warning
The element contains at least one unhealthy child element and at least one healthy child element.

Unhealthy
All child elements are unhealthy.

Optional: Click Refresh to refresh the health data.

Parent topic: Reverse proxy status

Viewing average response time statisticsViewing average response time statisticsAccess Manager Appliance: Viewing average response time statisticsThe Web Reverse Proxy can be configured to record transaction logs. One of the attributes that is recorded is the average request response time. This information is recorded at a per-junction level. To view a summary of the average response time that has been recorded, use the Average Response Time widget.average response time statisticsstatisticsaverage response timesjunctionsgraphsWeb Reverse Proxytransaction logstransaction logging componentsFrom the dashboard, locate the Average Response Time widget. The average response time for requests is displayed on a graph.The widget is only displayed if one or more Reverse Proxy instances have the Flow Data function enabled.Under Reverse Proxy Instances, select the instance to view the average response time statistics for.Under Junctions, select the junctions to display on the graph. Each junction is represented by a separate line on the graph.Under Date Range, select the duration over which the response times are recorded.Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Viewing average response time statistics

The Web Reverse Proxy can be configured to record transaction logs. One of the attributes that is recorded is the average request response time. This information is recorded at a per-junction level. To view a summary of the average response time that has been recorded, use the Average Response Time widget.

Procedure

From the dashboard, locate the Average Response Time widget. The average response time for requests is displayed on a graph.

Note: The widget is only displayed if one or more Reverse Proxy instances have the Flow Data function enabled.

Under Reverse Proxy Instances, select the instance to view the average response time statistics for.

Under Junctions, select the junctions to display on the graph. Each junction is represented by a separate line on the graph.

Under Date Range, select the duration over which the response times are recorded.

Parent topic: Reverse proxy status

Viewing security action statisticsViewing security action statisticsAccess Manager Appliance: Viewing security action statisticsThe Web Reverse Proxy can be configured to perform inspections on web content, searching for potential malicious requests (known as issues). It can then take certain defensive actions against any discovered issues. A summary of the defensive actions that have been taken can be viewed by using the Security Actions widget.security actionsstatisticssecurity actionsWeb Reverse Proxyinspectionsmalicious requestswebcontentFrom the dashboard, locate the Security Actions widget. The number of times each defensive action has been taken is displayed in a graph.The widget is only displayed if one or more instances have the security statistics function enabled.Under Reverse Proxy Instances, select the instances to view action statistics for. Only instances that have security statistics function enabled are listed for selection.Under Actions, select the actions to be included in the statistics. The number of actions that are displayed is the total of all selected actions.Under Date Range, select the duration over which the actions are taken. Reverse proxy statusYou can use the local management interface (LMI) to manage status and view statistics.

Viewing security action statistics

The Web Reverse Proxy can be configured to perform inspections on web content, searching for potential malicious requests (known as issues). It can then take certain defensive actions against any discovered issues. A summary of the defensive actions that have been taken can be viewed by using the Security Actions widget.

Procedure

From the dashboard, locate the Security Actions widget. The number of times each defensive action has been taken is displayed in a graph.

Note: The widget is only displayed if one or more instances have the security statistics function enabled.

Under Reverse Proxy Instances, select the instances to view action statistics for.

Note: Only instances that have security statistics function enabled are listed for selection.

Under Actions, select the actions to be included in the statistics. The number of actions that are displayed is the total of all selected actions.

Under Date Range, select the duration over which the actions are taken.

Parent topic: Reverse proxy status

JunctionsWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Creating virtual junctionsUse the Junction Management page to create one or more virtual junctions in your environment.Creating standard junctionsUse the Junction Management page to create one or more standard junctions in your environment.Managing standard and virtual junctionsTo manage standard and virtual junctions with the local management interface, use the Junction Management page.

Junctions

Creating virtual junctions
Use the Junction Management page to create one or more virtual junctions in your environment.

Creating standard junctions
Use the Junction Management page to create one or more standard junctions in your environment.

Managing standard and virtual junctions
To manage standard and virtual junctions with the local management interface, use the Junction Management page.

Parent topic: Web Reverse Proxy administration

Creating virtual junctionsUse the Junction Management page to create one or more virtual junctions in your environment.From the top menu, select Secure Web SettingsManageReverse Proxy.Select the reverse proxy to manage junctions for.Select ManageJunction Management.Click NewVirtual Junction.On the Junction tab page:Enter the junction label in the Junction Label field.Select the Stateful Junction check box if you want the junction to be stateful.Select a junction type from the listed options on the right.On the Servers tab page:Click New to add a target back-end server.At lease one target back-end server must be added to create a junction.Complete the fields displayed.Click Save.On the Basic Authentication tab page:Select the Enable Basic Authentication check box if BA header information is to be used for authentication with the back-end server.Enter the WebSEAL user name in the Username field.Enter the WebSEAL password in the Password field.Select the Enable mutual authentication to junctioned WebSEAL servers check box if mutual authentication is to be used between a frontend WebSEAL server and a back-end WebSEAL server.Select the key file from the list to use for mutual authentication.Select the key label from the list to use for mutual authentication.On the Identity tab page:Define how WebSEAL server passes client identity information in BA headers to the back-end server by selecting appropriate actions from the list under HTTP Basic Authentication Header.If GSO is selected in the previous step, enter the GSO resource or resource group name in the GSO Resource or Group field. If a value other than GSO is selected in the previous step, skip this step.Select what HTTP header identity information is passed to the back-end server in the HTTP Header Identity Information field.Select encoding from the list under HTTP Header Encoding.Select the check box on the right as necessary.On the SSO and LTPA tab page:Select the Enable LTPA cookie Support check box if the junctions are to support LTPA cookies.If LTPA version 2 cookies (LtpaToken2) are used, select the Use Version 2 Cookies check box.Select the LTPA keyfile from the list under LTPA Keyfile.Enter the keyfile password in the LTPA Keyfile Password field.On the General tab page:Specify the name of the form based single sign-on configuration file in the FSSO Configuration File field.Define the hard limit for consumption of worker threads in the Percentage Value for Hard Limit of Worker Threads field.Define the soft limit for consumption of worker threads in the Percentage Value for Soft Limit of Worker Threads field.If you want denied requests and failure reason information from authorization rules to be sent in the Boolean Rule header, select the Include authorization rules decision information check box.Click Save.Junctions

Creating virtual junctions

Use the Junction Management page to create one or more virtual junctions in your environment.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the reverse proxy to manage junctions for.

Select Manage > Junction Management.

Click New > Virtual Junction.

On the Junction tab page:

Enter the junction label in the Junction Label field.

Select the Stateful Junction check box if you want the junction to be stateful.

Select a junction type from the listed options on the right.

On the Servers tab page:

Click New to add a target back-end server.At lease one target back-end server must be added to create a junction.

Complete the fields displayed.

Click Save.

On the Basic Authentication tab page:

Select the Enable Basic Authentication check box if BA header information is to be used for authentication with the back-end server.

Enter the WebSEAL user name in the Username field.

Enter the WebSEAL password in the Password field.

Select the Enable mutual authentication to junctioned WebSEAL servers check box if mutual authentication is to be used between a frontend WebSEAL server and a back-end WebSEAL server.

Select the key file from the list to use for mutual authentication.

Select the key label from the list to use for mutual authentication.

On the Identity tab page:

Define how WebSEAL server passes client identity information in BA headers to the back-end server by selecting appropriate actions from the list under HTTP Basic Authentication Header.

If GSO is selected in the previous step, enter the GSO resource or resource group name in the GSO Resource or Group field. If a value other than GSO is selected in the previous step, skip this step.

Select what HTTP header identity information is passed to the back-end server in the HTTP Header Identity Information field.

Select encoding from the list under HTTP Header Encoding.

Select the check box on the right as necessary.

On the SSO and LTPA tab page:

Select the Enable LTPA cookie Support check box if the junctions are to support LTPA cookies.

If LTPA version 2 cookies (LtpaToken2) are used, select the Use Version 2 Cookies check box.

Select the LTPA keyfile from the list under LTPA Keyfile.

Enter the keyfile password in the LTPA Keyfile Password field.

On the General tab page:

Specify the name of the form based single sign-on configuration file in the FSSO Configuration File field.

Define the hard limit for consumption of worker threads in the Percentage Value for Hard Limit of Worker Threads field.

Define the soft limit for consumption of worker threads in the Percentage Value for Soft Limit of Worker Threads field.

If you want denied requests and failure reason information from authorization rules to be sent in the Boolean Rule header, select the Include authorization rules decision information check box.

Click Save.

Parent topic: Junctions

Creating standard junctionsUse the Junction Management page to create one or more standard junctions in your environment.From the top menu, select Secure Web SettingsManageReverse Proxy.Select the reverse proxy to manage junctions for.Select ManageJunction Management.Click NewStandard Junction.On the Junction tab page:Enter the junction point name. Names for standard junctions must start with a forward slash (/) character.Select the Create Transparant Path Junction check box if the junction name must match the name of a subdirectory under the root of the back-end server document space.Select the Stateful Junction check box if you want the junction to be stateful.Select a junction type from the listed options.On the Servers tab page:Click New to add a target back-end server. At least one target back-end server must be added to create a junction. The options available when you add a server vary depending on the junction type selected.Complete the fields displayed.Click Save.On the Basic Authentication tab page:The properties on this tab are specific to SSL junctions. They are available only if you create an SSL junction.Select the Enable Basic Authentication check box if BA header information is to be used for authentication with the back-end server.Enter the WebSEAL user name in the Username field.Enter the WebSEAL password in the Password field.Select the Enable mutual authentication to junctioned WebSEAL servers check box if mutual authentication is to be used between a frontend WebSEAL server and a back-end WebSEAL server.Select the key file from the list to use for mutual authentication.The options in the list include certificates from both the local and network key files. The certificates from the network key file are prefixed with the token label for the network HSM device.On the Identity tab page:Define how WebSEAL server passes client identity information in BA headers to the back-end server by selecting appropriate actions from the list under HTTP Basic Authentication Header.If GSO is selected in the previous step, enter the GSO resource or resource group name in the GSO Resource or Group field. If a value other than GSO is selected in the previous step, skip this step.Select what HTTP header identity information is passed to the back-end server in the HTTP Header Identity Information field.Select encoding from the list under HTTP Header Encoding.Select an option from the list under Junction Cookie Javascript Block.Select the check box on the right as necessary.On the SSO and LTPA tab page:Select the Enable LTPA cookie Support check box if the junctions are to support LTPA cookies.If LTPA version 2 cookies (LtpaToken2) are used, select the Use Version 2 Cookies check box.Select the LTPA keyfile from the list under LTPA Keyfile.Enter the keyfile password in the LTPA Keyfile Password field.On the General tab page:Specify the name of the form based single sign-on configuration file in the FSSO Configuration File field.Define the hard limit for consumption of worker threads in the Percentage Value for Hard Limit of Worker Threads field.Define the soft limit for consumption of worker threads in the Percentage Value for Soft Limit of Worker Threads field.If you want denied requests and failure reason information from authorization rules to be sent in the Boolean Rule header, select the Include authorization rules decision information check box.Click Save.Junctions

Creating standard junctions

Use the Junction Management page to create one or more standard junctions in your environment.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the reverse proxy to manage junctions for.

Select Manage > Junction Management.

Click New > Standard Junction.

On the Junction tab page:

Enter the junction point name. Names for standard junctions must start with a forward slash (/) character.

Select the Create Transparant Path Junction check box if the junction name must match the name of a subdirectory under the root of the back-end server document space.

Select the Stateful Junction check box if you want the junction to be stateful.

Select a junction type from the listed options.

On the Servers tab page:

Click New to add a target back-end server. At least one target back-end server must be added to create a junction. The options available when you add a server vary depending on the junction type selected.

Complete the fields displayed.

Click Save.

On the Basic Authentication tab page:

Note: The properties on this tab are specific to SSL junctions. They are available only if you create an SSL junction.

Select the Enable Basic Authentication check box if BA header information is to be used for authentication with the back-end server.

Enter the WebSEAL user name in the Username field.

Enter the WebSEAL password in the Password field.

Select the Enable mutual authentication to junctioned WebSEAL servers check box if mutual authentication is to be used between a frontend WebSEAL server and a back-end WebSEAL server.

Select the key file from the list to use for mutual authentication.

Note: The options in the list include certificates from both the local and network key files. The certificates from the network key file are prefixed with the token label for the network HSM device.

On the Identity tab page:

Define how WebSEAL server passes client identity information in BA headers to the back-end server by selecting appropriate actions from the list under HTTP Basic Authentication Header.

If GSO is selected in the previous step, enter the GSO resource or resource group name in the GSO Resource or Group field. If a value other than GSO is selected in the previous step, skip this step.

Select what HTTP header identity information is passed to the back-end server in the HTTP Header Identity Information field.

Select encoding from the list under HTTP Header Encoding.

Select an option from the list under Junction Cookie Javascript Block.

Select the check box on the right as necessary.

On the SSO and LTPA tab page:

Select the Enable LTPA cookie Support check box if the junctions are to support LTPA cookies.

If LTPA version 2 cookies (LtpaToken2) are used, select the Use Version 2 Cookies check box.

Select the LTPA keyfile from the list under LTPA Keyfile.

Enter the keyfile password in the LTPA Keyfile Password field.

On the General tab page:

Specify the name of the form based single sign-on configuration file in the FSSO Configuration File field.

Define the hard limit for consumption of worker threads in the Percentage Value for Hard Limit of Worker Threads field.

Define the soft limit for consumption of worker threads in the Percentage Value for Soft Limit of Worker Threads field.

If you want denied requests and failure reason information from authorization rules to be sent in the Boolean Rule header, select the Include authorization rules decision information check box.

Click Save.

Parent topic: Junctions

Managing standard and virtual junctions Access Manager Appliance: Managing standard and virtual junctions To manage standard and virtual junctions with the local management interface, use the Junction Management page.junctionsstandardvirtualstandard junctionsvirtualjunctionsLTPA keysfilesauthenticationenablingFSSOconfigurationHTTP headersidentitiesserversWebSEALusersnamesWebSEALserversFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the reverse proxy to manage junctions for.Select ManageJunction Management.Perform junction-related tasks as needed.Create standard junctions See Creating standard junctionsUse the Junction Management page to create one or more standard junctions in your environment..Create virtual junctions See Creating virtual junctionsUse the Junction Management page to create one or more virtual junctions in your environment..Edit a standard or virtual junctionSelect the junction to edit from the list.Click Edit.Modify the settings as needed.Click Save.Delete a standard or virtual junctionSelect the junction to delete from the list.Click Delete.In the confirmation window that pops up, click Yes.Some junction management tasks can be performed only with the web service, but not the local management interface. For example, functions achieved by using the following web service commands cannot be achieved by using the local management interface:jmt loadjmt clearoffline online throttleJunctions

Managing standard and virtual junctions

To manage standard and virtual junctions with the local management interface, use the Junction Management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the reverse proxy to manage junctions for.

Select Manage > Junction Management.

Perform junction-related tasks as needed.

Create standard junctions

See Creating standard junctions.

Create virtual junctions

See Creating virtual junctions.

Edit a standard or virtual junction

Select the junction to edit from the list.

Click Edit.

Modify the settings as needed.

Click Save.

Delete a standard or virtual junction

Select the junction to delete from the list.

Click Delete.

In the confirmation window that pops up, click Yes.

Note: Some junction management tasks can be performed only with the web service, but not the local management interface. For example, functions achieved by using the following web service commands cannot be achieved by using the local management interface:

jmt load

jmt clear

offline

online

throttle

Parent topic: Junctions

Federation managementUse the local management interface to configure your federations with a reverse proxy server. federationsmanagementWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Adding a federation for a reverse proxy serverConfigure a federation on a reverse proxy server to set up access between the federation and reverse proxy appliances.Removing a federation from a reverse proxy serverYou can remove a federation that was configured for a reverse proxy server.

Federation management

Use the local management interface to configure your federations with a reverse proxy server.

Adding a federation for a reverse proxy server
Configure a federation on a reverse proxy server to set up access between the federation and reverse proxy appliances.

Removing a federation from a reverse proxy server
You can remove a federation that was configured for a reverse proxy server.

Parent topic: Web Reverse Proxy administration

Adding a federation for a reverse proxy serverAdding a federationConfigure a federation on a reverse proxy server to set up access between the federation and reverse proxy appliances.federationsreverse proxy configurationreverse proxyfederation configurationThe reverse proxy server that you want to use for your federations must already be configured. See Configuring an instanceTo configure an instance with the local management interface, use the Reverse Proxy management page..From the local management interface, select Secure Web SettingsManageReverse Proxy.A list of reverse proxy instances displays.Select the reverse proxy instance name from the list.Select ManageFederation Management. A list of federations configured for this reverse proxy instance displays.Click Add. A window opens where you can add the configuration information.Enter the configuration details for the federation.The Runtime tab provides authentication information for the federation runtime: Host nameThe host name or IP address of the runtime server. This field is required.PortThe SSL port number of the runtime server. This field is required.User nameThe user name that is used to authenticate with the runtime server. This field is required.PasswordThe password that is used to authenticate with the runtime server. This field is required. The Federation tab specifies the federation name: Federation NameThe name that identifies the federation that you are configuring on this reverse proxy instance. Select the correct name from the list. If the federation name is not in the list, ensure that you set up the runtime configuration properly for that federation. The ACLs and Certificates tab indicates reuse of existing access control lists (ACLs) and certificates: Reuse ACLsSelect to reuse any existing ACLs with the same name. If this check box is not selected, the ACLs are replaced. Reuse CertificatesSelect to reuse the SSL certificate if it was already saved. If this check box is not selected, the certificate is overwritten.Click Submit.Federation managementUse the local management interface to configure your federations with a reverse proxy server.

Adding a federation for a reverse proxy server

Configure a federation on a reverse proxy server to set up access between the federation and reverse proxy appliances.

Before you begin

The reverse proxy server that you want to use for your federations must already be configured. See Configuring an instance.

Procedure

From the local management interface, select Secure Web Settings > Manage > Reverse Proxy. A list of reverse proxy instances displays.

Select the reverse proxy instance name from the list.

Select Manage > Federation Management. A list of federations configured for this reverse proxy instance displays.

Click Add. A window opens where you can add the configuration information.

Enter the configuration details for the federation.

The Runtime tab provides authentication information for the federation runtime:

Host name

The host name or IP address of the runtime server. This field is required.

Port

The SSL port number of the runtime server. This field is required.

User name

The user name that is used to authenticate with the runtime server. This field is required.

Password

The password that is used to authenticate with the runtime server. This field is required.

The Federation tab specifies the federation name:

Federation Name

The name that identifies the federation that you are configuring on this reverse proxy instance. Select the correct name from the list. If the federation name is not in the list, ensure that you set up the runtime configuration properly for that federation.

The ACLs and Certificates tab indicates reuse of existing access control lists (ACLs) and certificates:

Reuse ACLs

Select to reuse any existing ACLs with the same name. If this check box is not selected, the ACLs are replaced.

Reuse Certificates

Select to reuse the SSL certificate if it was already saved. If this check box is not selected, the certificate is overwritten.

Click Submit.

Parent topic: Federation management

Removing a federation from a reverse proxy serverRemoving a federationYou can remove a federation that was configured for a reverse proxy server.federationsreverse proxy configurationreverse proxyfederation configurationFrom the local management interface, select Secure Web SettingsManageReverse Proxy.A list of reverse proxy instances displays.Select the reverse proxy instance name from the list.Select ManageFederation Management. A list of federations configured for this reverse proxy instance displays.Select the federation name from the list.Click Remove. A pop-up window is displayed for confirmation.Click Yes.Federation managementUse the local management interface to configure your federations with a reverse proxy server.

Removing a federation from a reverse proxy server

You can remove a federation that was configured for a reverse proxy server.

Procedure

From the local management interface, select Secure Web Settings > Manage > Reverse Proxy. A list of reverse proxy instances displays.

Select the reverse proxy instance name from the list.

Select Manage > Federation Management. A list of federations configured for this reverse proxy instance displays.

Select the federation name from the list.

Click Remove. A pop-up window is displayed for confirmation.

Click Yes.

Parent topic: Federation management

Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.authorization serversmanagementserversauthorizationmanagementIBM Security Access Managerauthorization server instancesSecurity Access Managerauthorization serversWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Cleaning up authorization serversAfter you import a migration bundle, some authorization server instances might no longer be relevant to your current environment. In such situation, you can use the cleanup function on the Runtime Component management page to remove these instances.Creating an authorization server instanceTo create an authorization server instance, use the Authorization Server management page.Deleting an authorization server instanceTo delete an authorization server instance, use the Authorization Server management page.Stopping, starting, or restarting an authorization server instanceTo stop, start, or restart an authorization server instance, use the Authorization Server management page.Editing an authorization server instance advanced configuration fileTo edit an authorization server instance advanced configuration file, use the Authorization Server management page.Editing an authorization server instance tracing configuration fileTo edit an authorization server instance tracing configuration file, use the Authorization Server management page.Renewing authorization server management certificatesRenew the management certificate of an authorization server instance.

Authorization servers

To manage IBM Security Access Manager authorization server instances, go to Secure Web Settings > Manage > Authorization Server.

Cleaning up authorization servers
After you import a migration bundle, some authorization server instances might no longer be relevant to your current environment. In such situation, you can use the cleanup function on the Runtime Component management page to remove these instances.

Creating an authorization server instance
To create an authorization server instance, use the Authorization Server management page.

Deleting an authorization server instance
To delete an authorization server instance, use the Authorization Server management page.

Stopping, starting, or restarting an authorization server instance
To stop, start, or restart an authorization server instance, use the Authorization Server management page.

Editing an authorization server instance advanced configuration file
To edit an authorization server instance advanced configuration file, use the Authorization Server management page.

Editing an authorization server instance tracing configuration file
To edit an authorization server instance tracing configuration file, use the Authorization Server management page.

Renewing authorization server management certificates
Renew the management certificate of an authorization server instance.

Parent topic: Web Reverse Proxy administration

Cleaning up authorization serversCleaning up authorization serversAccess Manager Appliance: Cleaning up authorization serversAfter you import a migration bundle, some authorization server instances might no longer be relevant to your current environment. In such situation, you can use the cleanup function on the Runtime Component management page to remove these instances.cleaning upauthorization serverscleaning upmigrationimporting a bundlecleanup functionserversauthorizationcleaning upFrom the top menu, select Secure Web SettingsManageRuntime Component.Click ManageCleanup Servers.In the pop-up window, enter you IBM Security Access Manager administrator user name and password.These are the same user name and password you would use with the pdadmin utility.Click Login.From the list of authorization servers, select the one to be removed.A red icon indicates that the server is uncontactable. Stopping a server also renders it uncontactable. Make sure that you select only the instance that is no longer relevant in your current environment and thus should be removed. Click Delete.The Delete button is only clickable when an uncontactable server with a red icon is selected. After you delete an instance, all knowledge of this instance is removed from the policy server including LDAP.In the confirmation window, click Yes to confirm the operation.Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.

Cleaning up authorization servers

After you import a migration bundle, some authorization server instances might no longer be relevant to your current environment. In such situation, you can use the cleanup function on the Runtime Component management page to remove these instances.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Click Manage > Cleanup Servers.

In the pop-up window, enter you IBM Security Access Manager administrator user name and password. These are the same user name and password you would use with the pdadmin utility.

Click Login.

From the list of authorization servers, select the one to be removed.

Note: A red icon indicates that the server is uncontactable. Stopping a server also renders it uncontactable. Make sure that you select only the instance that is no longer relevant in your current environment and thus should be removed.

Click Delete.

Note: The Delete button is only clickable when an uncontactable server with a red icon is selected. After you delete an instance, all knowledge of this instance is removed from the policy server including LDAP.

In the confirmation window, click Yes to confirm the operation.

Parent topic: Authorization servers

Creating an authorization server instanceCreating an authorization server instanceAccess Manager Appliance: Creating an authorization server instanceTo create an authorization server instance, use the Authorization Server management page.authorization serverscreatingserversauthorizationcreatinginstancescreatingappliancesexternal LDAP serversdefaultvaluesLDAPuser registriesexternalSSLenablingcertificatesFrom the top menu, select Secure Web SettingsManageAuthorization Server.The status of all authorization server instances is displayed.Click New.In the New Authorization Server Instance window, provide values for the displayed fields.On the Instance tab, define the following fields.FieldDescriptionInstance NameName of the authorization server instance.Host NameName of the local host. The name is used during the construction of the authorization server instance name. The default value is the host name of the local system.Authorization PortThe port over which authorization requests are received. The default value is the next available port from 7136.Administration PortThe port over which Security Access Manager administration requests are received. The default value is the next available port after the authorization port value.IP AddressesThe IP addresses on which the authorization server listens for requests. To add an IP address to the selected box, select the address from the list immediately under IP Addresses and then click Add. To remove an IP address from the selected list, select the address from the box and then click Remove.On the IBM Security Access Manager tab, define the following fields.FieldDescriptionAdministrator NameThe administrator user name of IBM Security Access Manager.Administrator PasswordThe administrator user password of IBM Security Access Manager.DomainThe domain name of IBM Security Access Manager.If you use an LDAP server that is external to the appliance, a User Registry tab is also displayed. On the User Registry tab, define the following fields. FieldDescriptionEnable SSLSpecifies whether to enable SSL communication between the instance and the LDAP server. Key File NameThe file that contains the LDAP SSL certificate. This field is only valid if the Enable SSL check box is selected.Certificate LabelThe LDAP client certificate label. This field is only valid if the Enable SSL check box is selected.PortThe port number through which to communicate with the LDAP server. This field is only valid if the Enable SSL check box is selected.Click Finish.Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.

Creating an authorization server instance

To create an authorization server instance, use the Authorization Server management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Authorization Server. The status of all authorization server instances is displayed.

Click New.

In the New Authorization Server Instance window, provide values for the displayed fields.

On the Instance tab, define the following fields.

Field
Description

Instance Name
Name of the authorization server instance.

Host Name
Name of the local host. The name is used during the construction of the authorization server instance name. The default value is the host name of the local system.

Authorization Port
The port over which authorization requests are received. The default value is the next available port from 7136.

Administration Port
The port over which Security Access Manager administration requests are received. The default value is the next available port after the authorization port value.

IP Addresses
The IP addresses on which the authorization server listens for requests. To add an IP address to the selected box, select the address from the list immediately under IP Addresses and then click Add. To remove an IP address from the selected list, select the address from the box and then click Remove.

On the IBM Security Access Manager tab, define the following fields.

Field | Description
Administrator Name | The administrator user name of IBM Security Access Manager.
Administrator Password | The administrator user password of IBM Security Access Manager.
Domain | The domain name of IBM Security Access Manager.

If you use an LDAP server that is external to the appliance, a User Registry tab is also displayed. On the User Registry tab, define the following fields.

Field | Description
Enable SSL | Specifies whether to enable SSL communication between the instance and the LDAP server.
Key File Name | The file that contains the LDAP SSL certificate. This field is only valid if the Enable SSL check box is selected.
Certificate Label | The LDAP client certificate label. This field is only valid if the Enable SSL check box is selected.
Port | The port number through which to communicate with the LDAP server. This field is only valid if the Enable SSL check box is selected.

Click Finish.

Parent topic: Authorization servers

Deleting an authorization server instanceDeleting an authorization server instanceAccess Manager Appliance: Deleting an authorization server instanceTo delete an authorization server instance, use the Authorization Server management page.authorization serversdeletinginstancesdeletingserversauthorizationdeletingFrom the top menu, select Secure Web SettingsManageAuthorization Server.The status of all authorization server instances is displayed.Select the instance to delete.Click Delete.In the Delete Authorization Server Instance window, enter the administrator name and password.If you want to unconfigure the instance even if the policy server is unreachable, select the Force check box.Click Delete to confirm the operation.Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.

Deleting an authorization server instance

To delete an authorization server instance, use the Authorization Server management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Authorization Server. The status of all authorization server instances is displayed.

Select the instance to delete.

Click Delete.

In the Delete Authorization Server Instance window, enter the administrator name and password.

Optional: If you want to unconfigure the instance even if the policy server is unreachable, select the Force check box.

Click Delete to confirm the operation.

Parent topic: Authorization servers

Stopping, starting, or restarting an authorization server instanceStopping, starting, or restarting an authorization server instanceAccess Manager Appliance: Stopping, starting, or restarting an authorization server instanceTo stop, start, or restart an authorization server instance, use the Authorization Server management page.authorization serversrestartingstoppingstartinginstancesrestartingstoppingstartingserversauthorizationstartingstoppingrestartingFrom the top menu, select Secure Web SettingsManageAuthorization Server.Select the instance of interest.Stop an instanceClick Stop.A message is displayed indicating that the instance is stopped successfully.Start an instanceClick Start.A message is displayed indicating that the instance is started successfully.Restart an instanceClick Restart.A message is displayed indicating that the instance is restarted successfully.Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.

Stopping, starting, or restarting an authorization server instance

To stop, start, or restart an authorization server instance, use the Authorization Server management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Authorization Server.

Select the instance of interest.

Stop an instance

Click Stop.

A message is displayed indicating that the instance is stopped successfully.

Start an instance

Click Start.

A message is displayed indicating that the instance is started successfully.

Restart an instance

Click Restart.

A message is displayed indicating that the instance is restarted successfully.

Parent topic: Authorization servers

Editing an authorization server instance advanced configuration fileEditing an authorization server instance advanced configuration fileAccess Manager Appliance: Editing an authorization server instance advanced configuration fileTo edit an authorization server instance advanced configuration file, use the Authorization Server management page.authorization serverseditingconfiguration filesinstanceseditingserversauthorizationeditingadvanced configuration filesFrom the top menu, select Secure Web SettingsManageAuthorization Server.Select the instance of interest.Select ManageConfigurationEdit Configuration File.The configuration file contents are displayed.In the Advanced Configuration File Editor window, modify the configuration file.Click Save to save the changes. If you want to revert to the last successfully saved version of this file, click Revert. Or click Cancel if you do not want to save the changes.For the changes to take effect, the changes must be deployed and the running instance must be restarted.Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.

Editing an authorization server instance advanced configuration file

To edit an authorization server instance advanced configuration file, use the Authorization Server management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Authorization Server.

Select the instance of interest.

Select Manage > Configuration > Edit Configuration File. The configuration file contents are displayed.

In the Advanced Configuration File Editor window, modify the configuration file.

Click Save to save the changes. If you want to revert to the last successfully saved version of this file, click Revert. Or click Cancel if you do not want to save the changes.

Note: For the changes to take effect, the changes must be deployed and the running instance must be restarted.

Parent topic: Authorization servers

Editing an authorization server instance tracing configuration fileEditing an authorization server instance tracing configuration fileSecurity Access Manager: Editing an authorization server instance tracing configuration fileTo edit an authorization server instance tracing configuration file, use the Authorization Server management page.authorization serverseditingserversauthorizationeditingtraceconfiguration fileseditinginstanceseditingSecurity Access Managerauthorization serversFrom the top menu, select Secure Web SettingsManageAuthorization Server.Select the instance of interest.Select ManageConfigurationEdit Tracing Configuration File.The tracing configuration file contents are displayed.In the Tracing Configuration File Editor window, modify the file.Click Save to save the changes. Or click Cancel if you do not want to save the changes.For the changes to take effect, the changes must be deployed and the running instance must be restarted.Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.

Editing an authorization server instance tracing configuration file

To edit an authorization server instance tracing configuration file, use the Authorization Server management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Authorization Server.

Select the instance of interest.

Select Manage > Configuration > Edit Tracing Configuration File. The tracing configuration file contents are displayed.

In the Tracing Configuration File Editor window, modify the file.

Click Save to save the changes. Or click Cancel if you do not want to save the changes.

Note: For the changes to take effect, the changes must be deployed and the running instance must be restarted.

Parent topic: Authorization servers

Renewing authorization server management certificatesRenew the management certificate of an authorization server instance.An SSL certificate is used to authenticate the authorization server instance to the policy server. Use this option to automatically generate a new certificate that can be used in this communication.From the top menu, select Secure Web SettingsManageAuthorization Server.Select the instance to update the management certificate for.Select ManageRenew Management Certificate.Enter your administrator name and password.Click Renew.Authorization serversTo manage IBM Security Access Manager authorization server instances, go to Secure Web SettingsManageAuthorization Server.

Renewing authorization server management certificates

Renew the management certificate of an authorization server instance.

About this task

An SSL certificate is used to authenticate the authorization server instance to the policy server. Use this option to automatically generate a new certificate that can be used in this communication.

Procedure

From the top menu, select Secure Web Settings > Manage > Authorization Server.

Select the instance to update the management certificate for.

Select Manage > Renew Management Certificate.

Enter your administrator name and password.

Click Renew.

Parent topic: Authorization servers

ClustersWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Replicating runtime settings across the clusterIn a cluster environment, enable this option on the primary master to replicate the IBM Security Access Manager runtime settings to the non-primary nodes. Managing Distributed Session CacheIn a clustered appliance environment, session information is stored in the Distributed Session Cache. To work with these sessions, use the Distributed Session Cache management page.

Clusters

Replicating runtime settings across the cluster
In a cluster environment, enable this option on the primary master to replicate the IBM Security Access Manager runtime settings to the non-primary nodes.

Managing Distributed Session Cache
In a clustered appliance environment, session information is stored in the Distributed Session Cache. To work with these sessions, use the Distributed Session Cache management page.

Parent topic: Web Reverse Proxy administration

Replicating runtime settings across the clusterIn a cluster environment, enable this option on the primary master to replicate the IBM Security Access Manager runtime settings to the non-primary nodes. runtimereplicationsettingsclustersruntime settings replicationprimary mastersnon-primary nodesreplicationruntime settingsIBM Security Access ManagerreplicationSecurity Access ManagerreplicationsettingsruntimeFrom the top menu, select Secure Web SettingsManageRuntime Component.Select the Replicate with Cluster check box.This option is selectable on the primary master of the cluster only. In the confirmation window, click Yes to confirm the operation.The current IBM Security Access Manager runtime settings of the primary master and any future updates are automatically replicated to the non-primary nodes.After you enable this replication option, you can no longer update the IBM Security Access Manager runtime settings on the non-primary nodes of the cluster.Clusters

Replicating runtime settings across the cluster

In a cluster environment, enable this option on the primary master to replicate the IBM Security Access Manager runtime settings to the non-primary nodes.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select the Replicate with Cluster check box.

Note: This option is selectable on the primary master of the cluster only.

In the confirmation window, click Yes to confirm the operation. The current IBM Security Access Manager runtime settings of the primary master and any future updates are automatically replicated to the non-primary nodes.

Note: After you enable this replication option, you can no longer update the IBM Security Access Manager runtime settings on the non-primary nodes of the cluster.

Parent topic: Clusters

Managing Distributed Session CacheManaging Distributed Session CacheAccess Manager Appliance: Managing Distributed Session CacheIn a clustered appliance environment, session information is stored in the Distributed Session Cache. To work with these sessions, use the Distributed Session Cache management page.Distributed Session Cache (DSC)managingclustersDistributed Session Cacheappliancesclustersreplica setsmanagementsessionsinformationThe Distributed Session Cache feature replaces the Session Management Server. The Session Management Server (SMS) is not supported on IBM Security Access Manager for Web Version 8 and later.From the top menu, select Secure Web SettingsManageDistributed Session Cache.All replica set names and the number of sessions in each replica set are displayed.You can then view the replica set server list and manage sessions in a particular replica set.To view a list of the servers that are registered with a replica set, select the replica set and then click Servers.To manage the sessions in a replica set, select the replica set and then click Sessions.Typically, the list of sessions contains many entries. You can locate a session or a user faster by using the filter in the upper left corner.Delete a specific sessionSelect the session to delete.Click Delete.In the confirmation window, click Delete Session.Delete all sessions for a userSelect any session for that user.Click Delete.In the confirmation window, click Delete User.Clusters

Managing Distributed Session Cache

In a clustered appliance environment, session information is stored in the Distributed Session Cache. To work with these sessions, use the Distributed Session Cache management page.

About this task

The Distributed Session Cache feature replaces the Session Management Server. The Session Management Server (SMS) is not supported on IBM Security Access Manager for Web Version 8 and later.

Procedure

From the top menu, select Secure Web Settings > Manage > Distributed Session Cache. All replica set names and the number of sessions in each replica set are displayed.

You can then view the replica set server list and manage sessions in a particular replica set.

To view a list of the servers that are registered with a replica set, select the replica set and then click Servers.

To manage the sessions in a replica set, select the replica set and then click Sessions.

Tip: Typically, the list of sessions contains many entries. You can locate a session or a user faster by using the filter in the upper left corner.

Delete a specific session

Select the session to delete.

Click Delete.

In the confirmation window, click Delete Session.

Delete all sessions for a user

Select any session for that user.

Click Delete.

In the confirmation window, click Delete User.

Parent topic: Clusters

Policy management with Web Portal ManagerAccess Manager ApplianceWeb Portal Manager is a graphical management console for managing domains, users, groups, permissions, policies, and other resources in your enterprise. The appliance provides an embedded version of Web Portal Manager.Web Portal ManagerdomainsmanagementTo access Web Portal Manager from the appliance, go to Secure Web SettingsManagePolicy Administration.The Web Portal Manager panels might carry a different appearance than the other appliance panels. This behavior is expected. It does not affect the performance of the embedded Web Portal Manager.For more information about how to use Web Portal Manager, see Web Portal ManagerSecurity Access Manager has both command-line and graphical interface interfaces for managing domains, users, groups, permissions, policies, and other resources in your enterprise.. Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.

Policy management with Web Portal Manager

Web Portal Manager is a graphical management console for managing domains, users, groups, permissions, policies, and other resources in your enterprise. The appliance provides an embedded version of Web Portal Manager.

To access Web Portal Manager from the appliance, go to Secure Web Settings > Manage > Policy Administration.

Note: The Web Portal Manager panels might carry a different appearance than the other appliance panels. This behavior is expected. It does not affect the performance of the embedded Web Portal Manager.

For more information about how to use Web Portal Manager, see Web Portal Manager.

Parent topic: Web Reverse Proxy administration

Global settingsWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Managing dynamic URL configuration filesIn the local management interface, go to Secure Web SettingsGlobal SettingsURL Mapping. A list of all dynamic URL (DynURL) configuration files is displayed. You can view individual file details, and create, import, export, update, rename, and delete DynURL files.Managing junction mapping JMT configuration filesIn the local management interface, go to Secure Web SettingsGlobal SettingsJunction Mapping. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.Managing client certificate CDAS filesIn the local management interface, go to Secure Web SettingsGlobal SettingsClient Certificate Mapping. A list of all client certificate CDAS files is displayed. You can view individual file details, and create, import, export, update, rename, and delete CDAS files.Managing user mapping CDAS filesYou can use a user mapping CDAS file to map an authenticated user name to a different Security Access Manager user identity.Managing password strength rule filesYou can use a password strength rule file to define the criteria for new passwords to be validated against.Managing forms based single sign-on filesIn the local management interface, go to Secure Web SettingsGlobal SettingsForms Based Single Sign-On. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.Managing HTTP transformation filesIn the local management interface, go to Secure Web SettingsGlobal SettingsHTTP Transformation. A list of all files is displayed. You can create, import, export, update, rename, and delete files.Managing RSA SecurID configurationIn the local management interface, go to Secure Web SettingsGlobal SettingsRSA SecurID Configuration. The status of the RSA server and node is displayed, as well as the option to upload or clear a RSA configuration, clear a node secret, and test a configuration.

Global settings

Managing dynamic URL configuration files
In the local management interface, go to Secure Web Settings > Global Settings > URL Mapping. A list of all dynamic URL (DynURL) configuration files is displayed. You can view individual file details, and create, import, export, update, rename, and delete DynURL files.

Managing junction mapping JMT configuration files
In the local management interface, go to Secure Web Settings > Global Settings > Junction Mapping. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.

Managing client certificate CDAS files
In the local management interface, go to Secure Web Settings > Global Settings > Client Certificate Mapping. A list of all client certificate CDAS files is displayed. You can view individual file details, and create, import, export, update, rename, and delete CDAS files.

Managing user mapping CDAS files
You can use a user mapping CDAS file to map an authenticated user name to a different Security Access Manager user identity.

Managing password strength rule files
You can use a password strength rule file to define the criteria for new passwords to be validated against.

Managing forms based single sign-on files
In the local management interface, go to Secure Web Settings > Global Settings > Forms Based Single Sign-On. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.

Managing HTTP transformation files
In the local management interface, go to Secure Web Settings > Global Settings > HTTP Transformation. A list of all files is displayed. You can create, import, export, update, rename, and delete files.

Managing RSA SecurID configuration
In the local management interface, go to Secure Web Settings > Global Settings > RSA SecurID Configuration. The status of the RSA server and node is displayed, as well as the option to upload or clear a RSA configuration, clear a node secret, and test a configuration.

Parent topic: Web Reverse Proxy administration

Managing dynamic URL configuration filesIn the local management interface, go to Secure Web SettingsGlobal SettingsURL Mapping. A list of all dynamic URL (DynURL) configuration files is displayed. You can view individual file details, and create, import, export, update, rename, and delete DynURL files.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click URL Mapping.Perform any of the following actions:Viewing details of a DynURL configuration file:Select the file to view.Click Edit. The file content is displayed.Creating a DynURL configuration file:Click New.Modify the content of the file.Enter the name for the file.Click Save.Importing a DynURL configuration file:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting a DynURL configuration file:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Modifying a DynURL configuration file:Select the file that you want to modify.Click Edit.Modify the content of the file.Enter the name for the file.Click Save.Renaming a DynURL configuration file:Select the file that you want to rename.Click ManageRename.In the New Resource Name field, enter the new name for the file.Click Save.Deleting a DynURL configuration file:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing dynamic URL configuration files

In the local management interface, go to Secure Web Settings > Global Settings > URL Mapping. A list of all dynamic URL (DynURL) configuration files is displayed. You can view individual file details, and create, import, export, update, rename, and delete DynURL files.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click URL Mapping.

Perform any of the following actions:

Viewing details of a DynURL configuration file:

Select the file to view.

Click Edit. The file content is displayed.

Creating a DynURL configuration file:

Click New.

Modify the content of the file.

Enter the name for the file.

Click Save.

Importing a DynURL configuration file:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting a DynURL configuration file:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Modifying a DynURL configuration file:

Select the file that you want to modify.

Click Edit.

Modify the content of the file.

Enter the name for the file.

Click Save.

Renaming a DynURL configuration file:

Select the file that you want to rename.

Click Manage > Rename.

In the New Resource Name field, enter the new name for the file.

Click Save.

Deleting a DynURL configuration file:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Managing junction mapping JMT configuration filesIn the local management interface, go to Secure Web SettingsGlobal SettingsJunction Mapping. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click Junction Mapping.Perform any of the following actions:Viewing details of a JMT configuration file:Select the file to view.Click Edit. The file content is displayed.Creating a JMT configuration file:Click New.Modify the content of the file.Enter the name for the file.Click Save.Importing a JMT configuration file:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting a JMT configuration file:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Modifying a JMT configuration file:Select the file that you want to modify.Click Edit.Modify the content of the file.Click Save.Renaming a JMT configuration file:Select the file that you want to rename.Click ManageRename.In the New Resource Name field, enter the new name for the file.Click Save.Deleting a JMT configuration file:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing junction mapping JMT configuration files

In the local management interface, go to Secure Web Settings > Global Settings > Junction Mapping. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click Junction Mapping.

Perform any of the following actions:

Viewing details of a JMT configuration file:

Select the file to view.

Click Edit. The file content is displayed.

Creating a JMT configuration file:

Click New.

Modify the content of the file.

Enter the name for the file.

Click Save.

Importing a JMT configuration file:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting a JMT configuration file:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Modifying a JMT configuration file:

Select the file that you want to modify.

Click Edit.

Modify the content of the file.

Click Save.

Renaming a JMT configuration file:

Select the file that you want to rename.

Click Manage > Rename.

In the New Resource Name field, enter the new name for the file.

Click Save.

Deleting a JMT configuration file:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Managing client certificate CDAS filesIn the local management interface, go to Secure Web SettingsGlobal SettingsClient Certificate Mapping. A list of all client certificate CDAS files is displayed. You can view individual file details, and create, import, export, update, rename, and delete CDAS files.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click Client Certificate Mapping.Perform any of the following actions:Viewing details of a client certificate CDAS file:Select the file to view.Click Edit. The file content is displayed.Creating a client certificate CDAS file:Click New.Modify the content of the file.Enter the name for the file.Click Save.Importing a client certificate CDAS file:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting a client certificate CDAS file:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Modifying a client certificate CDAS file:Select the file that you want to modify.Click Edit.Modify the content of the file.Click Save.Renaming a client certificate CDAS file:Select the file that you want to rename.Click ManageRename.In the New Resource Name field, enter the new name for the file.Click Save.Deleting a client certificate CDAS file:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing client certificate CDAS files

In the local management interface, go to Secure Web Settings > Global Settings > Client Certificate Mapping. A list of all client certificate CDAS files is displayed. You can view individual file details, and create, import, export, update, rename, and delete CDAS files.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click Client Certificate Mapping.

Perform any of the following actions:

Viewing details of a client certificate CDAS file:

Select the file to view.

Click Edit. The file content is displayed.

Creating a client certificate CDAS file:

Click New.

Modify the content of the file.

Enter the name for the file.

Click Save.

Importing a client certificate CDAS file:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting a client certificate CDAS file:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Modifying a client certificate CDAS file:

Select the file that you want to modify.

Click Edit.

Modify the content of the file.

Click Save.

Renaming a client certificate CDAS file:

Select the file that you want to rename.

Click Manage > Rename.

In the New Resource Name field, enter the new name for the file.

Click Save.

Deleting a client certificate CDAS file:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Managing user mapping CDAS filesYou can use a user mapping CDAS file to map an authenticated user name to a different Security Access Manager user identity.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click User Name Mapping.Perform any of the following actions:Viewing details of a user mapping CDAS file:Select the file to view.Click Edit. The file content is displayed.Creating a user mapping CDAS file:Click New.Enter the name for the file.Click Save.Importing a user mapping CDAS file:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting a user mapping CDAS file:Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Modifying a user mapping CDAS file:Select the file that you want to modify.Click Edit.Modify the content of the file.Click Save.Renaming a user mapping CDAS file:Select the file that you want to rename.Click ManageRename.In the New Resource Name field, enter the new name for the file.Click Save.Deleting a user mapping CDAS file:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing user mapping CDAS files

You can use a user mapping CDAS file to map an authenticated user name to a different Security Access Manager user identity.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click User Name Mapping.

Perform any of the following actions:

Viewing details of a user mapping CDAS file:

Select the file to view.

Click Edit. The file content is displayed.

Creating a user mapping CDAS file:

Click New.

Enter the name for the file.

Click Save.

Importing a user mapping CDAS file:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting a user mapping CDAS file:

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Modifying a user mapping CDAS file:

Select the file that you want to modify.

Click Edit.

Modify the content of the file.

Click Save.

Renaming a user mapping CDAS file:

Select the file that you want to rename.

Click Manage > Rename.

In the New Resource Name field, enter the new name for the file.

Click Save.

Deleting a user mapping CDAS file:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Managing password strength rule filesYou can use a password strength rule file to define the criteria for new passwords to be validated against.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click Password Strength.Perform any of the following actions:Viewing details of a password strength rule file:Select the file to view.Click Edit. The file content is displayed.Creating a password strength rule file:Click New.Enter the name for the file.Click Save.Importing a password strength rule file:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting a password strength rule file:Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Modifying a password strength rule file:Select the file that you want to modify.Click Edit.Modify the content of the file.Click Save.Renaming a password strength rule file:Select the file that you want to rename.Click ManageRename.In the New Resource Name field, enter the new name for the file.Click Save.Deleting a password strength rule file:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing password strength rule files

You can use a password strength rule file to define the criteria for new passwords to be validated against.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click Password Strength.

Perform any of the following actions:

Viewing details of a password strength rule file:

Select the file to view.

Click Edit. The file content is displayed.

Creating a password strength rule file:

Click New.

Enter the name for the file.

Click Save.

Importing a password strength rule file:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting a password strength rule file:

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Modifying a password strength rule file:

Select the file that you want to modify.

Click Edit.

Modify the content of the file.

Click Save.

Renaming a password strength rule file:

Select the file that you want to rename.

Click Manage > Rename.

In the New Resource Name field, enter the new name for the file.

Click Save.

Deleting a password strength rule file:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Managing forms based single sign-on filesIn the local management interface, go to Secure Web SettingsGlobal SettingsForms Based Single Sign-On. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click Forms Based Single Sign-On.Perform any of the following actions:Viewing details of a forms based single sign-on file:Select the file to view.Click Edit. The file content is displayed.Creating a forms based single sign-on file:Click New.Modify the content of the file.Enter the name for the file.Click Save.Importing a forms based single sign-on file:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting a forms based single sign-on file:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Modifying a forms based single sign-on file:Select the file that you want to modify.Click Edit.Modify the content of the file.Click Save.Renaming a forms based single sign-on file:Select the file that you want to rename.Click ManageRename.In the New Resource Name field, enter the new name for the file.Click Save.Deleting a forms based single sign-on file:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing forms based single sign-on files

In the local management interface, go to Secure Web Settings > Global Settings > Forms Based Single Sign-On. A list of all files is displayed. You can view individual file details, and create, import, export, update, rename, and delete files.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click Forms Based Single Sign-On.

Perform any of the following actions:

Viewing details of a forms based single sign-on file:

Select the file to view.

Click Edit. The file content is displayed.

Creating a forms based single sign-on file:

Click New.

Modify the content of the file.

Enter the name for the file.

Click Save.

Importing a forms based single sign-on file:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting a forms based single sign-on file:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Modifying a forms based single sign-on file:

Select the file that you want to modify.

Click Edit.

Modify the content of the file.

Click Save.

Renaming a forms based single sign-on file:

Select the file that you want to rename.

Click Manage > Rename.

In the New Resource Name field, enter the new name for the file.

Click Save.

Deleting a forms based single sign-on file:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Managing HTTP transformation filesIn the local management interface, go to Secure Web SettingsGlobal SettingsHTTP Transformation. A list of all files is displayed. You can create, import, export, update, rename, and delete files.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click HTTP Transformation.Perform any of the following actions:Creating an HTTP transformation rule file:Click New.Modify the content of the file.Enter the name for the file.Click Save.Importing an HTTP transformation rule file:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting an HTTP transformation rule file:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Modifying an HTTP transformation rule file:Select the file that you want to modify.Click Edit.Modify the content of the file.Click Save.Renaming an HTTP transformation rule file:Select the file that you want to rename.Click ManageRename.In the New Resource Name field, enter the new name for the file.Click Save.Deleting an HTTP transformation rule file:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing HTTP transformation files

In the local management interface, go to Secure Web Settings > Global Settings > HTTP Transformation. A list of all files is displayed. You can create, import, export, update, rename, and delete files.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click HTTP Transformation.

Perform any of the following actions:

Creating an HTTP transformation rule file:

Click New.

Modify the content of the file.

Enter the name for the file.

Click Save.

Importing an HTTP transformation rule file:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting an HTTP transformation rule file:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Modifying an HTTP transformation rule file:

Select the file that you want to modify.

Click Edit.

Modify the content of the file.

Click Save.

Renaming an HTTP transformation rule file:

Select the file that you want to rename.

Click Manage > Rename.

In the New Resource Name field, enter the new name for the file.

Click Save.

Deleting an HTTP transformation rule file:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Managing RSA SecurID configurationIn the local management interface, go to Secure Web SettingsGlobal SettingsRSA SecurID Configuration. The status of the RSA server and node is displayed, as well as the option to upload or clear a RSA configuration, clear a node secret, and test a configuration. Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click RSA SecurID Configuration.Perform any of the following actions:Uploading a new RSA server configuration fileClick Upload.Select the file to be uploaded.The RSA configuration file to be uploaded to the appliance must be generated by the RSA server. Click Submit.Removing an RSA server configuration file:Click Clear under the Server Configuration File section.Confirm that you want to clear the configuration.Testing a configurationAfter uploading a server configuration file, click Test. Enter a valid user.Enter a valid passcode.You might need to disable two-step authentication on the RSA server to successfully test the configuration, as the test function does not support two-step authentication.Clearing a node secretClick Clear under the Node Secret File section.Confirm that you want to clear the secret.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global settings

Managing RSA SecurID configuration

In the local management interface, go to Secure Web Settings > Global Settings > RSA SecurID Configuration. The status of the RSA server and node is displayed, as well as the option to upload or clear a RSA configuration, clear a node secret, and test a configuration.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click RSA SecurID Configuration.

Perform any of the following actions:

Uploading a new RSA server configuration file

Click Upload.

Select the file to be uploaded.

Note: The RSA configuration file to be uploaded to the appliance must be generated by the RSA server.

Click Submit.

Removing an RSA server configuration file:

Click Clear under the Server Configuration File section.

Confirm that you want to clear the configuration.

Testing a configuration

After uploading a server configuration file, click Test.

Enter a valid user.

Enter a valid passcode.

Note: You might need to disable two-step authentication on the RSA server to successfully test the configuration, as the test function does not support two-step authentication.

Clearing a node secret

Click Clear under the Node Secret File section.

Confirm that you want to clear the secret.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global settings

Global keysWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Managing SSO keysIn the local management interface, go to Secure Web SettingsGlobal SettingsSSO Keys. A list of all keys is displayed. You can create, import, export, and delete keys.Managing LTPA keysIn the local management interface, go to Secure Web SettingsGlobal SettingsLTPA Keys. A list of all keys is displayed. You can create, import, export, and delete keys.Kerberos configurationYou can create, edit, delete, and test the following Kerberos settings from the local management interface.

Global keys

Managing SSO keys
In the local management interface, go to Secure Web Settings > Global Settings > SSO Keys. A list of all keys is displayed. You can create, import, export, and delete keys.

Managing LTPA keys
In the local management interface, go to Secure Web Settings > Global Settings > LTPA Keys. A list of all keys is displayed. You can create, import, export, and delete keys.

Kerberos configuration
You can create, edit, delete, and test the following Kerberos settings from the local management interface.

Parent topic: Web Reverse Proxy administration

Managing SSO keysIn the local management interface, go to Secure Web SettingsGlobal SettingsSSO Keys. A list of all keys is displayed. You can create, import, export, and delete keys.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click SSO Keys.Perform any of the following actions:Creating an SSO key:Click New.Modify the content of the file.Enter the name for the file.Click Save.Importing an SSO key:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting an SSO key:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Deleting an SSO key:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global keys

Managing SSO keys

In the local management interface, go to Secure Web Settings > Global Settings > SSO Keys. A list of all keys is displayed. You can create, import, export, and delete keys.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click SSO Keys.

Perform any of the following actions:

Creating an SSO key:

Click New.

Modify the content of the file.

Enter the name for the file.

Click Save.

Importing an SSO key:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting an SSO key:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Deleting an SSO key:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global keys

Managing LTPA keysIn the local management interface, go to Secure Web SettingsGlobal SettingsLTPA Keys. A list of all keys is displayed. You can create, import, export, and delete keys.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Web Settings.Under Global Settings, click LTPA Keys.Perform any of the following actions:Creating an LTPA key:Click New.Modify the content of the file.Enter the name for the file.Click Save.Importing an LTPA key:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting an LTPA key:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Deleting an LTPA key:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Global keys

Managing LTPA keys

In the local management interface, go to Secure Web Settings > Global Settings > LTPA Keys. A list of all keys is displayed. You can create, import, export, and delete keys.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Web Settings.

Under Global Settings, click LTPA Keys.

Perform any of the following actions:

Creating an LTPA key:

Click New.

Modify the content of the file.

Enter the name for the file.

Click Save.

Importing an LTPA key:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting an LTPA key:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Deleting an LTPA key:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Global keys

Kerberos configurationYou can create, edit, delete, and test the following Kerberos settings from the local management interface. Kerberossettingskeytab filesauthenticationpathstestingCA pathsdefaultvaluesdomainsrealmskeytab filesLMIKerberos configurationsettingsKerberosrealmsdomainsauthenticationnamesserverswebserversprincipalsManage Kerberos configuration settingsSettingDescriptionlibdefaultContains default values that are used by the Kerberos library. realmsContains subsections that are keyed by Kerberos realm names. Each subsection describes realm-specific information, which includes where to find the Kerberos servers for that realm. domain realmsContains relations that map domain names and subdomains to Kerberos realm names. These relations are used by programs to determine what realm a host is in, given its fully qualified domain name. CA paths Contains the authentication paths that are used with direct (non-hierarchical) cross-realm authentication. Entries in this section are used by the client to determine the intermediate realms that can be used in cross-realm authentication. It is also used by the end-service when it checks the transited field for trusted intermediate realms. keytab filesContains the keytab files that are used for Kerberos authentication. The files contain pairs of Kerberos principals and encrypted keys.Global keysManaging the default values used by KerberosUse the Defaults tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings are used as default values by the Kerberos library. Managing realmsUse the Realms tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe realm-specific information. Managing domain realm propertiesUse the Domains tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe relations that map domain names and subdomains to Kerberos realm names.Managing CA pathsUse the CA Paths tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings contain the authentication paths that are used with direct (non-hierarchical) cross-realm authentication.Managing keytab filesUse the Keyfiles tab on the Kerberos Configuration management page in the LMI to manage these settings.

Kerberos configuration

You can create, edit, delete, and test the following Kerberos settings from the local management interface.

Table 191. Manage Kerberos configuration settings.

Setting
Description

libdefault
Contains default values that are used by the Kerberos library.

realms
Contains subsections that are keyed by Kerberos realm names. Each subsection describes realm-specific information, which includes where to find the Kerberos servers for that realm.

domain realms
Contains relations that map domain names and subdomains to Kerberos realm names. These relations are used by programs to determine what realm a host is in, given its fully qualified domain name.

CA paths
Contains the authentication paths that are used with direct (non-hierarchical) cross-realm authentication. Entries in this section are used by the client to determine the intermediate realms that can be used in cross-realm authentication. It is also used by the end-service when it checks the transited field for trusted intermediate realms.

keytab files
Contains the keytab files that are used for Kerberos authentication. The files contain pairs of Kerberos principals and encrypted keys.

Managing the default values used by Kerberos
Use the Defaults tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings are used as default values by the Kerberos library.

Managing realms
Use the Realms tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe realm-specific information.

Managing domain realm properties
Use the Domains tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe relations that map domain names and subdomains to Kerberos realm names.

Managing CA paths
Use the CA Paths tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings contain the authentication paths that are used with direct (non-hierarchical) cross-realm authentication.

Managing keytab files
Use the Keyfiles tab on the Kerberos Configuration management page in the LMI to manage these settings.

Parent topic: Global keys

Managing the default values used by KerberosManaging the default values used by KerberosAccess Manager Appliance: Managing the default values used by KerberosUse the Defaults tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings are used as default values by the Kerberos library. Kerberosdefault valuesdefaultvaluesThe Defaults tab contains settings for the libdefault section of the corresponding Kerberos configuration file. You can create, edit, and delete properties in this section. You can also test authentication with your web server principal name and password.From the top menu, select Secure Web SettingsGlobal SettingsKerberos Configuration.The current Kerberos configuration is displayed.On the Defaults tab, take actions as needed.Create a propertyClick New.In the Create New Property window, select a name from the Pre-Defined Names list or enter a name in the Name field as the name of the new property.Provide the value of the new property in the Value field.Click Save.Edit a propertySelect the property to edit from the table.Click Edit.In the Edit Property window, modify the value of the property as needed.Click Save.Delete a propertySelect the property to delete from the table.Click Delete.In the Confirm Action window, click Yes.Test authentication with principal and passwordClick Test.In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.Enter the password in the Password field.Click Test.Kerberos configurationYou can create, edit, delete, and test the following Kerberos settings from the local management interface.

Managing the default values used by Kerberos

Use the Defaults tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings are used as default values by the Kerberos library.

About this task

The Defaults tab contains settings for the libdefault section of the corresponding Kerberos configuration file. You can create, edit, and delete properties in this section. You can also test authentication with your web server principal name and password.

Procedure

From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration. The current Kerberos configuration is displayed.

On the Defaults tab, take actions as needed.

Create a property

Click New.

In the Create New Property window, select a name from the Pre-Defined Names list or enter a name in the Name field as the name of the new property.

Provide the value of the new property in the Value field.

Click Save.

Edit a property

Select the property to edit from the table.

Click Edit.

In the Edit Property window, modify the value of the property as needed.

Click Save.

Delete a property

Select the property to delete from the table.

Click Delete.

In the Confirm Action window, click Yes.

Test authentication with principal and password

Click Test.

In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.

Enter the password in the Password field.

Click Test.

Parent topic: Kerberos configuration

Managing realmsManaging realmsAccess Manager Appliance: Managing realmsUse the Realms tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe realm-specific information. KerberosrealmsrealmsmanagementThe Realms tab contains settings for the realms section of the corresponding Kerberos configuration file. You can create, edit, and delete realms, configuration subsections, and properties in this section. You can also test authentication with your web server principal name and password.From the top menu, select Secure Web SettingsGlobal SettingsKerberos Configuration.The current Kerberos configuration is displayed.On the Realms tab, take actions as needed.Create a realmClick NewRealm.In the Create New Realm window, enter the name of the new realm in the Realm field.Click Save.Create a configuration subsectionSelect the realm in which to create the subsection.Click NewSubsection.In the Create New Subsection window, select a name from the Pre-Defined Names list or enter a name in the Subsection field.Click Save.Create a propertySelect the realm or subsection in which to create the property.Click NewProperty.In the Create New Property window, select a name from the Pre-Defined Names list or enter a name in the Name field.Enter the value of the property in the Value field.Click Save.Edit a propertySelect the property to edit.Click Edit.In the Edit Property window, modify the value as needed.Click Save.Delete a realmSelect the realm to delete from the table.Click Delete.In the Confirm Action window, click Yes.Test authentication with principal and passwordClick Test.In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.Enter the password in the Password field.Click Test.Kerberos configurationYou can create, edit, delete, and test the following Kerberos settings from the local management interface.

Managing realms

Use the Realms tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe realm-specific information.

About this task

The Realms tab contains settings for the realms section of the corresponding Kerberos configuration file. You can create, edit, and delete realms, configuration subsections, and properties in this section. You can also test authentication with your web server principal name and password.

Procedure

From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration. The current Kerberos configuration is displayed.

On the Realms tab, take actions as needed.

Create a realm

Click New > Realm.

In the Create New Realm window, enter the name of the new realm in the Realm field.

Click Save.

Create a configuration subsection

Select the realm in which to create the subsection.

Click New > Subsection.

In the Create New Subsection window, select a name from the Pre-Defined Names list or enter a name in the Subsection field.

Click Save.

Create a property

Select the realm or subsection in which to create the property.

Click New > Property.

In the Create New Property window, select a name from the Pre-Defined Names list or enter a name in the Name field.

Enter the value of the property in the Value field.

Click Save.

Edit a property

Select the property to edit.

Click Edit.

In the Edit Property window, modify the value as needed.

Click Save.

Delete a realm

Select the realm to delete from the table.

Click Delete.

In the Confirm Action window, click Yes.

Test authentication with principal and password

Click Test.

In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.

Enter the password in the Password field.

Click Test.

Parent topic: Kerberos configuration

Managing domain realm propertiesManaging domain realm propertiesAccess Manager Appliance: Managing domain realm propertiesUse the Domains tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe relations that map domain names and subdomains to Kerberos realm names.KerberosdomainsdomainsrealmsrealmsdomainspropertiesThe Domains tab contains settings for the domain_realm section of the corresponding Kerberos configuration file. You can create, edit, and delete properties in this section. You can also test authentication with your web server principal name and password.From the top menu, select Secure Web SettingsGlobal SettingsKerberos Configuration.The current Kerberos configuration is displayed.On the Domains tab, take actions as needed.Create a domain realm propertyClick New.In the Create New Translation window, enter the local DNS address in the Local DNS Value field.Select a realm from the Realm list.Click Save.Edit a domain realm propertySelect the domain realm property to edit from the table.Click Edit.In the Edit Property window, modify the realm as needed.Click Save.Delete a domain realm propertySelect the domain realm property to delete from the table.Click Delete.In the Confirm Action window, click Yes.Test authentication with principal and passwordClick Test.In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.Enter the password in the Password field.Click Test.Kerberos configurationYou can create, edit, delete, and test the following Kerberos settings from the local management interface.

Managing domain realm properties

Use the Domains tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings describe relations that map domain names and subdomains to Kerberos realm names.

About this task

The Domains tab contains settings for the domain_realm section of the corresponding Kerberos configuration file. You can create, edit, and delete properties in this section. You can also test authentication with your web server principal name and password.

Procedure

From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration. The current Kerberos configuration is displayed.

On the Domains tab, take actions as needed.

Create a domain realm property

Click New.

In the Create New Translation window, enter the local DNS address in the Local DNS Value field.

Select a realm from the Realm list.

Click Save.

Edit a domain realm property

Select the domain realm property to edit from the table.

Click Edit.

In the Edit Property window, modify the realm as needed.

Click Save.

Delete a domain realm property

Select the domain realm property to delete from the table.

Click Delete.

In the Confirm Action window, click Yes.

Test authentication with principal and password

Click Test.

In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.

Enter the password in the Password field.

Click Test.

Parent topic: Kerberos configuration

Managing CA pathsManaging CA pathsAccess Manager Appliance: Managing CA pathsUse the CA Paths tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings contain the authentication paths that are used with direct (non-hierarchical) cross-realm authentication.KerberosCA pathsCA pathsauthenticationpathsrealmsauthenticationThe CA Paths tab contains settings for the capaths section of the corresponding Kerberos configuration file. You can create, edit, and delete properties and CA paths in this section. You can also test authentication with your web server principal name and password.From the top menu, select Secure Web SettingsGlobal SettingsKerberos Configuration.The current Kerberos configuration is displayed.On the CA Paths tab, take actions as needed.Create a CA pathClick NewClient Realm.In the Create Client Realm window, enter the realm name in the Client Realm field.Click Save.Create a propertySelect the client realm in which to create the property.Click NewProperty.In the Create New Property window, provide a value for the Server Realm and Intermediate Realm.Click Save.Edit a propertySelect the property to edit from the table.Click Edit.In the Edit Property window, modify the value as needed.Click Save.Delete a CA pathSelect the CA path to delete from the table.Click Delete.In the Confirm Action window, click Yes.Delete a propertySelect the property to delete from the table.Click Delete.In the Confirm Action window, click Yes.Test authentication with principal and passwordClick Test.In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.Enter the password in the Password field.Click Test.Kerberos configurationYou can create, edit, delete, and test the following Kerberos settings from the local management interface.

Managing CA paths

Use the CA Paths tab on the Kerberos Configuration management page in the LMI to manage these settings. These settings contain the authentication paths that are used with direct (non-hierarchical) cross-realm authentication.

About this task

The CA Paths tab contains settings for the capaths section of the corresponding Kerberos configuration file. You can create, edit, and delete properties and CA paths in this section. You can also test authentication with your web server principal name and password.

Procedure

From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration. The current Kerberos configuration is displayed.

On the CA Paths tab, take actions as needed.

Create a CA path

Click New > Client Realm.

In the Create Client Realm window, enter the realm name in the Client Realm field.

Click Save.

Create a property

Select the client realm in which to create the property.

Click New > Property.

In the Create New Property window, provide a value for the Server Realm and Intermediate Realm.

Click Save.

Edit a property

Select the property to edit from the table.

Click Edit.

In the Edit Property window, modify the value as needed.

Click Save.

Delete a CA path

Select the CA path to delete from the table.

Click Delete.

In the Confirm Action window, click Yes.

Delete a property

Select the property to delete from the table.

Click Delete.

In the Confirm Action window, click Yes.

Test authentication with principal and password

Click Test.

In the Test Kerberos Authentication window, enter the name of the user that is created as the web server principal in the Username field.

Enter the password in the Password field.

Click Test.

Parent topic: Kerberos configuration

Managing keytab filesManaging keytab filesAccess Manager Appliance: Managing keytab files Use the Keyfiles tab on the Kerberos Configuration management page in the LMI to manage these settings.Kerberoskeytab fileskeytab filesauthenticationsettingsThe Keyfiles tab contains settings for the keytab files that are used for Kerberos authentication. You can import, combine, and delete keytab files. You can also test authentication with a Kerberos principal name and keytab file.From the top menu, select Secure Web SettingsGlobal SettingsKerberos Configuration.The current Kerberos configuration is displayed.On the Keyfiles tab, take actions as needed.Import a keytab fileClick Import.In the Import Keytab File window, click Browse.Select the keytab file to be imported and then click Open.Click Import.Delete a keytab fileSelect the file to delete from the table.Click Delete.In the Confirm Action window, click Yes.Combine keytab filesSelect the keytab files to be combined from the table.Click Combine.In the Combine Keytab Files window, enter the name for the combined file in the New Resource Name field.Click Save.Verify authentication with a keytab fileSelect the keytab file to test from the table.Click Test.In the Test Keytab Authentication window, provide the value of the Kerberos principal in the Username field.Click Test.Kerberos configurationYou can create, edit, delete, and test the following Kerberos settings from the local management interface.

Managing keytab files

Use the Keyfiles tab on the Kerberos Configuration management page in the LMI to manage these settings.

About this task

The Keyfiles tab contains settings for the keytab files that are used for Kerberos authentication. You can import, combine, and delete keytab files. You can also test authentication with a Kerberos principal name and keytab file.

Procedure

From the top menu, select Secure Web Settings > Global Settings > Kerberos Configuration. The current Kerberos configuration is displayed.

On the Keyfiles tab, take actions as needed.

Import a keytab file

Click Import.

In the Import Keytab File window, click Browse.

Select the keytab file to be imported and then click Open.

Click Import.

Delete a keytab file

Select the file to delete from the table.

Click Delete.

In the Confirm Action window, click Yes.

Combine keytab files

Select the keytab files to be combined from the table.

Click Combine.

In the Combine Keytab Files window, enter the name for the combined file in the New Resource Name field.

Click Save.

Verify authentication with a keytab file

Select the keytab file to test from the table.

Click Test.

In the Test Keytab Authentication window, provide the value of the Kerberos principal in the Username field.

Click Test.

Parent topic: Kerberos configuration

Trace dataAccess Manager Appliance: Tracing controlYou can use the local management interface (LMI) to control tracing.tracecontroldatacontroltracingWeb Security Gateway AppliancetracingdatatracingIBM Security Access ManagerenvironmentSecurity Access ManagerenvironmentssoftwaresupportTrace data is intended primarily for use by IBM Software Support. Trace data might be requested as part of diagnosing a reported problem. However, experienced product administrators can use trace data to diagnose and correct problems in an IBM Security Access Manager environment. For more information about trace event logging, see TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager..Use trace with caution. It is intended as a tool to use under the direction of IBM Software Support. Messages from tracing are sometimes cryptic, are not translated, and can severely degrade system performance.Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Modifying the tracing settings for a componentTo modify the trace level, flush interval, rollover size, maximum rollover files, and whether rollover files are automatically compressed for a component, use the Reverse Proxy management page or the Authorization Server management page.Managing the trace files for a componentTo manage the trace files and rollover files for a component, use the Reverse Proxy management page or the Authorization Server management page.Editing the tracing configuration file for the runtime environmentTo edit the tracing configuration file for the runtime environment, use the Runtime Component management page. Updating a tracing configuration fileTo update a tracing configuration file with the local management interface, use the Reverse Proxy Instances management page.

Trace data

You can use the local management interface (LMI) to control tracing.

Trace data is intended primarily for use by IBM® Software Support. Trace data might be requested as part of diagnosing a reported problem. However, experienced product administrators can use trace data to diagnose and correct problems in an IBM Security Access Manager environment. For more information about trace event logging, see Troubleshooting.

Note: Use trace with caution. It is intended as a tool to use under the direction of IBM Software Support. Messages from tracing are sometimes cryptic, are not translated, and can severely degrade system performance.

Modifying the tracing settings for a component
To modify the trace level, flush interval, rollover size, maximum rollover files, and whether rollover files are automatically compressed for a component, use the Reverse Proxy management page or the Authorization Server management page.

Managing the trace files for a component
To manage the trace files and rollover files for a component, use the Reverse Proxy management page or the Authorization Server management page.

Editing the tracing configuration file for the runtime environment
To edit the tracing configuration file for the runtime environment, use the Runtime Component management page.

Updating a tracing configuration file
To update a tracing configuration file with the local management interface, use the Reverse Proxy Instances management page.

Parent topic: Web Reverse Proxy administration

Modifying the tracing settings for a componentTo modify the trace level, flush interval, rollover size, maximum rollover files, and whether rollover files are automatically compressed for a component, use the Reverse Proxy management page or the Authorization Server management page.tracelevelscomponentsrolloversizesflush intervalscomponentstrace levelsflush intervalsrollover sizecompressFrom the top menu, select Secure Web SettingsManageReverse Proxy if you want to manage tracing for a reverse proxy instance. Or select Secure Web SettingsManageAuthorization Server if you want to manage tracing for an authorization server instance.Select the instance of interest. For reverse proxy, select ManageTroubleshootingTracing. For authorization server, select ManageTracing.Select the component to be modified and then click Edit.Modify the trace level, flush interval, rollover size, maximum rollover files, and whether rollover files are automatically compressed.By default, the Compress option is set to No. To save disk space, set the Compress option to Yes so that all rollover files are automatically compressed.Click Save.Trace dataYou can use the local management interface (LMI) to control tracing.

Modifying the tracing settings for a component

To modify the trace level, flush interval, rollover size, maximum rollover files, and whether rollover files are automatically compressed for a component, use the Reverse Proxy management page or the Authorization Server management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy if you want to manage tracing for a reverse proxy instance. Or select Secure Web Settings > Manage > Authorization Server if you want to manage tracing for an authorization server instance.

Select the instance of interest.

For reverse proxy, select Manage > Troubleshooting > Tracing. For authorization server, select Manage > Tracing.

Select the component to be modified and then click Edit.

Modify the trace level, flush interval, rollover size, maximum rollover files, and whether rollover files are automatically compressed. By default, the Compress option is set to No. To save disk space, set the Compress option to Yes so that all rollover files are automatically compressed.

Click Save.

Parent topic: Trace data

Managing the trace files for a componentManaging the trace files for a componentAccess Manager Appliance: Managing the trace files for a componentTo manage the trace files and rollover files for a component, use the Reverse Proxy management page or the Authorization Server management page.tracefilesauthorization serversmanagementrolloverfilesserversauthorizationtrace filesFrom the top menu, select Secure Web SettingsManageReverse Proxy if you want to manage tracing for a reverse proxy instance. Or select Secure Web SettingsManageAuthorization Server if you want to manage tracing for an authorization server instance.Select the instance of interest. For reverse proxy, select ManageTroubleshootingTracing. For authorization server, select ManageTracing.Select a component and then click Files to view a list of all its trace and rollover files.The file name, file size, and last modified time of each file is displayed.View or export a trace file or rollover fileSelect the file of interest.Click View. The content of the trace files is then displayed. To view a particular number of lines of trace, provide a value in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.Click Export if you want to export the file.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation when the browser prompts you to save the file.Delete a trace file or rollover fileSelect the file of interest.Only a file that is not in use can be deleted.Click Delete.Click Yes to confirm the operation.Export a trace file or rollover fileSelect the file of interest.Click ManageExport.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation when the browser prompts you to save the file.Delete all trace files and rollover files that are not in useClick ManageDelete All. Click Yes to confirm the operation.Trace dataYou can use the local management interface (LMI) to control tracing.

Managing the trace files for a component

To manage the trace files and rollover files for a component, use the Reverse Proxy management page or the Authorization Server management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy if you want to manage tracing for a reverse proxy instance. Or select Secure Web Settings > Manage > Authorization Server if you want to manage tracing for an authorization server instance.

Select the instance of interest.

For reverse proxy, select Manage > Troubleshooting > Tracing. For authorization server, select Manage > Tracing.

Select a component and then click Files to view a list of all its trace and rollover files. The file name, file size, and last modified time of each file is displayed.

View or export a trace file or rollover file

Select the file of interest.

Click View. The content of the trace files is then displayed. To view a particular number of lines of trace, provide a value in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.

Note: The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.

Click Export if you want to export the file.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation when the browser prompts you to save the file.

Delete a trace file or rollover file

Select the file of interest.

Note: Only a file that is not in use can be deleted.

Click Delete.

Click Yes to confirm the operation.

Export a trace file or rollover file

Select the file of interest.

Click Manage > Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation when the browser prompts you to save the file.

Delete all trace files and rollover files that are not in use

Click Manage > Delete All.

Click Yes to confirm the operation.

Parent topic: Trace data

Editing the tracing configuration file for the runtime environmentEditing the tracing configuration file for the runtime environmentSecurity Access Manager: Editing the tracing configuration file for the runtime environmentTo edit the tracing configuration file for the runtime environment, use the Runtime Component management page. runtimeconfigurationtraceconfiguration fileseditingSecurity Access Managerediting tracing configuration filepolicy serverseditingFrom the top menu, select Secure Web SettingsManageRuntime Component.Select ManageConfiguration Files Tracing Configuration Files.The tracing configuration file contents are displayed.The Tracing Configuration File menu item is available only when a local policy server is configured. When a remote policy server is configured, this menu item is disabled. In that case, you must directly edit the file on the machine where the policy server is installed.In the Tracing Configuration File Editor window, modify the file.Click Save to save the changes. Or click Cancel if you do not want to save the changes.For the changes to take effect, the changes must be deployed and the runtime environment must be restarted.Trace dataYou can use the local management interface (LMI) to control tracing.

Editing the tracing configuration file for the runtime environment

To edit the tracing configuration file for the runtime environment, use the Runtime Component management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Runtime Component.

Select Manage > Configuration Files > Tracing Configuration Files. The tracing configuration file contents are displayed.

Note: The Tracing Configuration File menu item is available only when a local policy server is configured. When a remote policy server is configured, this menu item is disabled. In that case, you must directly edit the file on the machine where the policy server is installed.

In the Tracing Configuration File Editor window, modify the file.

Click Save to save the changes. Or click Cancel if you do not want to save the changes.

Note: For the changes to take effect, the changes must be deployed and the runtime environment must be restarted.

Parent topic: Trace data

Updating a tracing configuration fileUpdating a tracing configuration file Security Access Manager: Updating a tracing configuration fileTo update a tracing configuration file with the local management interface, use the Reverse Proxy Instances management page.traceconfiguration filesupdatingconfiguration filesupdatingFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select ManageConfigurationEdit Tracing Configuration File.The tracing configuration file contents are displayed.Modify the file.Click Save to save the changes. Or click Close if you do not want to save the changes.For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Trace dataYou can use the local management interface (LMI) to control tracing.

Updating a tracing configuration file

To update a tracing configuration file with the local management interface, use the Reverse Proxy Instances management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Manage > Configuration > Edit Tracing Configuration File. The tracing configuration file contents are displayed.

Modify the file.

Click Save to save the changes. Or click Close if you do not want to save the changes.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Trace data

LoggingLoggingAccess Manager Appliance: LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files. log filesmanagementWeb Reverse Proxylog filesmanagementWeb Security Gateway Appliancereverse proxy log filesCLIloggingloggingdetailsloggingdisk spaceUSB devicesThe web reverse proxy log files record the events and activities of the web reverse proxies during the daily operation of the appliance. There are two ways to reduce the disk space that is used by these files. Configure the web reverse proxy to send the log information to a remote server. For more information about the remote logging options, see Configuring web application firewall To configure web application firewall with the local management interface, use the Reverse Proxy management page..Clear the unused log files regularly. For details, see Managing reverse proxy log filesUse the Manage Reverse Proxy Log Files management page to work with reverse proxy log files.. Alternatively, use the command-line interface to back up the log files to a USB device, and to purge all log files that were rolled over. For details, see Archiving and deleting reverse proxy log files with the command-line interfaceUse the logs option in the command-line interface to archive Web Reverse Proxy log files to a USB device and then delete old log files to free up disk space..Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.Listing the names of all log files and file sizesTo list the names of all log files and file size with the local management interface, use the Reverse Proxy management page.Viewing a snippet of or export a log file To view a snippet of a log file or export a log file with the local management interface, use the Reverse Proxy management page.Clearing a log fileTo clear a log file and turn its size to 0 with the local management interface, use the Reverse Proxy management page.Managing transaction logging components and data filesTo manage transaction logging components and data files with the local management interface, use the Reverse Proxy management page.Managing reverse proxy log filesUse the Manage Reverse Proxy Log Files management page to work with reverse proxy log files.Managing authorization server log filesTo work with authorization server log files, use the Manage Authorization Server Log Files management page.

Logging

You can use the local management interface (LMI) to manage the reverse proxy log files.

Note: The web reverse proxy log files record the events and activities of the web reverse proxies during the daily operation of the appliance. There are two ways to reduce the disk space that is used by these files.

Configure the web reverse proxy to send the log information to a remote server. For more information about the remote logging options, see Configuring web application firewall.

Clear the unused log files regularly. For details, see Managing reverse proxy log files. Alternatively, use the command-line interface to back up the log files to a USB device, and to purge all log files that were rolled over. For details, see Archiving and deleting reverse proxy log files with the command-line interface.

Listing the names of all log files and file sizes
To list the names of all log files and file size with the local management interface, use the Reverse Proxy management page.

Viewing a snippet of or export a log file
To view a snippet of a log file or export a log file with the local management interface, use the Reverse Proxy management page.

Clearing a log file
To clear a log file and turn its size to 0 with the local management interface, use the Reverse Proxy management page.

Managing transaction logging components and data files
To manage transaction logging components and data files with the local management interface, use the Reverse Proxy management page.

Managing reverse proxy log files
Use the Manage Reverse Proxy Log Files management page to work with reverse proxy log files.

Managing authorization server log files
To work with authorization server log files, use the Manage Authorization Server Log Files management page.

Parent topic: Web Reverse Proxy administration

Listing the names of all log files and file sizesListing the names of all log files and file sizesAccess Manager Appliance: Listing the names of all log files and file sizesTo list the names of all log files and file size with the local management interface, use the Reverse Proxy management page.log filesnameslistingnames of log filesfile sizesfile sizesdetailsloggingFrom the top menu, select Secure Web SettingsManageReverse Proxy.Optional: If instance-specific log files are of interest, select the instance.Select ManageLogging. If an instance is selected, details of all common log files and instance-specific log files are displayed. If no instance is selected, only details of the common log files are displayed.You can use the filter bar under Name to filter entries that meet specific conditions. Click Clear filter to return to the full list.LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files.

Listing the names of all log files and file sizes

To list the names of all log files and file size with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Optional: If instance-specific log files are of interest, select the instance.

Select Manage > Logging. If an instance is selected, details of all common log files and instance-specific log files are displayed. If no instance is selected, only details of the common log files are displayed.

You can use the filter bar under Name to filter entries that meet specific conditions. Click Clear filter to return to the full list.

Parent topic: Logging

Viewing a snippet of or export a log fileViewing a snippet of or export a log fileAccess Manager Appliance: Viewing a snippet of or export a log file To view a snippet of a log file or export a log file with the local management interface, use the Reverse Proxy management page.log filesviewing snippetsexportingFrom the top menu, select Secure Web SettingsManageReverse Proxy.Optional: If instance-specific log files are of interest, select the instance.Select ManageLogging.Select the log file that you want to view.Click View. The content of the log file is displayed. By default, the last 100 lines of a log file is displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.Click Export to download the log file.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.You can also export a file by selecting it and then clicking ManageExport.LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files.

Viewing a snippet of or export a log file

To view a snippet of a log file or export a log file with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Optional: If instance-specific log files are of interest, select the instance.

Select Manage > Logging.

Select the log file that you want to view.

Click View. The content of the log file is displayed. By default, the last 100 lines of a log file is displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.

Note: The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.

Click Export to download the log file.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

You can also export a file by selecting it and then clicking Manage > Export.

Parent topic: Logging

Clearing a log fileClearing a log fileAccess Manager Appliance: Clearing a log fileTo clear a log file and turn its size to 0 with the local management interface, use the Reverse Proxy management page.log filesclearingFrom the top menu, select Secure Web SettingsManageReverse Proxy.Optional: If instance-specific log files are of interest, select the instance.Select ManageLogging.Select the log file that you want to clear.Click Clear.On the Confirm Action confirmation page, click Yes.LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files.

Clearing a log file

To clear a log file and turn its size to 0 with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Optional: If instance-specific log files are of interest, select the instance.

Select Manage > Logging.

Select the log file that you want to clear.

Click Clear.

On the Confirm Action confirmation page, click Yes.

Parent topic: Logging

Managing transaction logging components and data files Managing transaction logging components and data files Access Manager Appliance: Managing transaction logging components and data files To manage transaction logging components and data files with the local management interface, use the Reverse Proxy management page.transaction logging componentsdatafilesdefaultrollover sizeloggingrolloversizescompressFrom the top menu, select Secure Web SettingsManageReverse Proxy.Select the instance of interest.Select ManageTroubleshootingTransaction Logging.All transaction logging components and their status, total file size, and rollover size are displayed.Enable or disable a transaction logging componentSelect the transaction logging component of interest.Click Edit.Select or clear the Enabled check box to enable or disable the transaction logging component.Optionally, define the rollover size by providing a value in the Rollover Size field. If no value is provided, the default rollover size is used.Optionally, define the maximum number of rollover files by providing a value in the Maximum Rollover Files field. If no value is provided, no rollover files will be deleted.Optionally, set the Compress option to Yes so that all rollover files are automatically compressed to save disk space. By default, the Compress option is set to No. Click Save to save your changes.Rollover the data file of a transaction logging componentSelect the transaction logging component of interest.Click ManageRollover.Click Yes to confirm the operation.Manage transaction logging data filesSelect the transaction logging component of interest.Click Files.Export a transaction logging data fileSelect the transaction logging data file of interest.Click ManageExport.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm whether to open or save the exported file in the browser window.Delete a transaction logging data fileOnly transaction logging data files that are not in use can be deleted.Select the transaction logging data file of interest.Click Delete.Click Yes to confirm the operation.Delete all unused transaction logging data filesClick ManageDelete All.Click Yes to confirm the operation.LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files.

Managing transaction logging components and data files

To manage transaction logging components and data files with the local management interface, use the Reverse Proxy management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select the instance of interest.

Select Manage > Troubleshooting > Transaction Logging. All transaction logging components and their status, total file size, and rollover size are displayed.

Enable or disable a transaction logging component

Select the transaction logging component of interest.

Click Edit.

Select or clear the Enabled check box to enable or disable the transaction logging component.

Optionally, define the rollover size by providing a value in the Rollover Size field. If no value is provided, the default rollover size is used.

Optionally, define the maximum number of rollover files by providing a value in the Maximum Rollover Files field. If no value is provided, no rollover files will be deleted.

Optionally, set the Compress option to Yes so that all rollover files are automatically compressed to save disk space. By default, the Compress option is set to No.

Click Save to save your changes.

Rollover the data file of a transaction logging component

Select the transaction logging component of interest.

Click Manage > Rollover.

Click Yes to confirm the operation.

Manage transaction logging data files

Select the transaction logging component of interest.

Click Files.

Export a transaction logging data file

Select the transaction logging data file of interest.

Click Manage > Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm whether to open or save the exported file in the browser window.

Delete a transaction logging data file

Note: Only transaction logging data files that are not in use can be deleted.

Select the transaction logging data file of interest.

Click Delete.

Click Yes to confirm the operation.

Delete all unused transaction logging data files

Click Manage > Delete All.

Click Yes to confirm the operation.

Parent topic: Logging

Managing reverse proxy log filesManaging reverse proxy log filesAccess Manager Appliance: Managing reverse proxy log filesUse the Manage Reverse Proxy Log Files management page to work with reverse proxy log files.reverse proxylog fileslog filesreverse proxydetailscommon log filesFrom the top menu, select Monitor Analysis and DiagnosticsLogsManage Reverse Proxy Log Files.Details of all common log files are displayed under Log Files for Selected Instance.You can use the filter bar under Name to filter entries that meet specific conditions. Click Clear filter to return to the full list.Optional: If instance-specific log files are of interest, select the instance from the list under Reverse Proxy Instances.Details of all common log files and instance-specific log files are displayed under Log Files for Selected Instance.Work with the reverse proxy log files.View the content of a reverse proxy log fileSelect the log file that you want to view.Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.Optional: Click Export to download the log file. You must configure the software to block pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Export a reverse proxy log fileSelect the log file that you want to export.Click ManageExport.You must configure the software to block pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation in the browser window to export the file to a local location.Clear a reverse proxy log fileSelect the log file that you want to clear.Click Clear.On the Confirm Action confirmation page, click Yes.LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files.

Managing reverse proxy log files

Use the Manage Reverse Proxy Log Files management page to work with reverse proxy log files.

Procedure

From the top menu, select Monitor Analysis and Diagnostics > Logs > Manage Reverse Proxy Log Files. Details of all common log files are displayed under Log Files for Selected Instance.

You can use the filter bar under Name to filter entries that meet specific conditions. Click Clear filter to return to the full list.

Optional: If instance-specific log files are of interest, select the instance from the list under Reverse Proxy Instances. Details of all common log files and instance-specific log files are displayed under Log Files for Selected Instance.

Work with the reverse proxy log files.

View the content of a reverse proxy log file

Select the log file that you want to view.

Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.

Note: The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.

Optional: Click Export to download the log file.

Note: You must configure the software to block pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Export a reverse proxy log file

Select the log file that you want to export.

Click Manage > Export.

Note: You must configure the software to block pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation in the browser window to export the file to a local location.

Clear a reverse proxy log file

Select the log file that you want to clear.

Click Clear.

On the Confirm Action confirmation page, click Yes.

Parent topic: Logging

Managing authorization server log filesManaging authorization server log filesAccess Manager Appliance: Managing authorization server log filesTo work with authorization server log files, use the Manage Authorization Server Log Files management page.authorization serverslog fileslog filesauthorizationserversauthorizationlog filesFrom the top menu, select Secure Web SettingsManageAuthorization Server.Select the instance of interest.Select ManageLogging.Work with the authorization server log files as needed.View the content of an authorization server log fileSelect the log file that you want to view.Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define which line in the log file to start viewing from. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.Optional: Click Export to download the log file. You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Clear an authorization server log fileSelect the log file that you want to clear.Click Clear.On the Confirm Action confirmation page, click Yes. A system notification is displayed to indicate that the log file is successfully cleared. The original log file with empty content remains in the log list. Any rollover log files (for example, xxx.log.1 and xxx.log.2) are deleted.Export an authorization server log fileSelect the log file that you want to export.Click ManageExport.You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.Confirm the save operation in the browser window to export the file to a local location.LoggingYou can use the local management interface (LMI) to manage the reverse proxy log files.

Managing authorization server log files

To work with authorization server log files, use the Manage Authorization Server Log Files management page.

Procedure

From the top menu, select Secure Web Settings > Manage > Authorization Server.

Select the instance of interest.

Select Manage > Logging.

Work with the authorization server log files as needed.

View the content of an authorization server log file

Select the log file that you want to view.

Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Optionally, you can provide a value in the Starting from line field to define which line in the log file to start viewing from. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.

Note: The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.

Optional: Click Export to download the log file.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Clear an authorization server log file

Select the log file that you want to clear.

Click Clear.

On the Confirm Action confirmation page, click Yes. A system notification is displayed to indicate that the log file is successfully cleared. The original log file with empty content remains in the log list. Any rollover log files (for example, xxx.log.1 and xxx.log.2) are deleted.

Export an authorization server log file

Select the log file that you want to export.

Click Manage > Export.

Note: You must configure the software that blocks pop-up windows in your browser to allow pop-up windows for the appliance before files can be exported.

Confirm the save operation in the browser window to export the file to a local location.

Parent topic: Logging

Front-end load balancerFront-end load balancerAccess Manager Appliance: Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.load balancersfront-endfront-end load balancersfunctionsserversservicesIP addressesportsrequestsload balancingappliancesfront-end load balancerschangesfront-end load balancersfunctionalityhigh availabilityIBM Security Access ManagerenvironmentsSecurity Access ManagerenvironmentspersistencestickinessvirtualIP addressesserversdefinitionWeb Reverse ProxyconfigurationenvironmentsserversIn an IBM Security Access Manager environment, you can have many services. Each service has a virtual IP address and a port. Every service is available on one or more real servers. Each server is defined by IP address and a port. The front-end load balancer maps incoming service requests to real servers. A front-end load balancer is a server that uses a virtual IP address to accept requests from a client. It determines which reverse proxy server is most suitable to handle the request and forwards it to the appropriate reverse proxy server. Incoming requests from the same client are forwarded to the same server. That is, the front-end load balancer provides stickiness or persistence for existing sessions. The load balancer uses a scheduling algorithm to forward requests from clients that are not already assigned to a back-end server.In a typical setup, there are two front-end load balancer servers and multiple reverse proxy servers. Configuring two front end load balancers in the environment provides high availability for the front-end load balancing service. A heartbeat is transmitted between the two front-end load balancers so that the state of each front-end load balancer is known. The load balancer that is actively receiving and processing requests is known as the active load balancer. The other load balancer is known as the passive load balancer. When available, the primary front-end load balancer acts as the active load balancer. It is assigned the virtual IP address for the load balancing service and awaits incoming client requests. If the primary front-end load balancer becomes unavailable, the backup load balancer can no longer detect heartbeats. In this situation, the backup load balancer assumes the virtual IP address and starts accepting requests from clients. That is, the backup load balancer becomes the active load balancer until the primary load balancer is restored.Front-end load balancerFront-end load balancerYou can have only two front-end load balancers in your environment.It is possible to configure the reverse proxy functionality on an appliance that is also acting as a front-end load balancer. However, this configuration might have a negative impact on the performance of the front-end load balancer. If you decide to use such setting, you must take the resources that are used by the reverse proxy into consideration.You must make sure that the front-end load balancer still has enough resources to perform routing effectively.Example high availability environmentThe Web Reverse Proxy and the front-end load balancer functioning on the same applianceYou can configure a highly available web reverse proxy environment with as few as two appliances, as shown in Figure 2. The active load balancer is on the primary appliance. This load balancer assumes the virtual IP address for the load balancing service. Client requests are received from the Internet-facing network, 10.254.140.0. The load balancer distributes these requests between the web reverse proxy servers, which are on the 10.254.140.0 network.Web Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.SchedulingThe front-end load balancing function of the appliance supports several types of scheduling.Load balancing layerSecurity Access Manager supports load balancing at layer 4 or layer 7 of the Open Systems Interconnection (OSI) network model.PersistenceSession persistence, also known as stickiness, is a mechanism that ensures a client is connected to the same reverse proxy server during a session. Network terminationThe front-end load balancer that is provided in Security Access Manager, version 7.0, is a network terminating load balancer. Benefits of layer 7 load balancingThe main benefit of layer 7 load balancing is the ability to use and manipulate the HTTP headers in requests and responses.Configuring front-end load balancer To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page.Front-end load balancer advanced tuning parametersUse these parameters to tune the frond-end load balancer configuration.

Front-end load balancer

The appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

In an IBM Security Access Manager environment, you can have many services. Each service has a virtual IP address and a port. Every service is available on one or more real servers. Each server is defined by IP address and a port. The front-end load balancer maps incoming service requests to real servers.

A front-end load balancer is a server that uses a virtual IP address to accept requests from a client. It determines which reverse proxy server is most suitable to handle the request and forwards it to the appropriate reverse proxy server.

Incoming requests from the same client are forwarded to the same server. That is, the front-end load balancer provides stickiness or persistence for existing sessions. The load balancer uses a scheduling algorithm to forward requests from clients that are not already assigned to a back-end server.

In a typical setup, there are two front-end load balancer servers and multiple reverse proxy servers. Configuring two front end load balancers in the environment provides high availability for the front-end load balancing service.

A heartbeat is transmitted between the two front-end load balancers so that the state of each front-end load balancer is known. The load balancer that is actively receiving and processing requests is known as the active load balancer. The other load balancer is known as the passive load balancer.

When available, the primary front-end load balancer acts as the active load balancer. It is assigned the virtual IP address for the load balancing service and awaits incoming client requests.

If the primary front-end load balancer becomes unavailable, the backup load balancer can no longer detect heartbeats. In this situation, the backup load balancer assumes the virtual IP address and starts accepting requests from clients. That is, the backup load balancer becomes the active load balancer until the primary load balancer is restored.

Figure 86. Front-end load balancer

Note: You can have only two front-end load balancers in your environment.

It is possible to configure the reverse proxy functionality on an appliance that is also acting as a front-end load balancer. However, this configuration might have a negative impact on the performance of the front-end load balancer. If you decide to use such setting, you must take the resources that are used by the reverse proxy into consideration.

You must make sure that the front-end load balancer still has enough resources to perform routing effectively.

Figure 87. Example high availability environment

You can configure a highly available web reverse proxy environment with as few as two appliances, as shown in Figure 87.. The active load balancer is on the primary appliance. This load balancer assumes the virtual IP address for the load balancing service. Client requests are received from the Internet-facing network, 10.254.140.0. The load balancer distributes these requests between the web reverse proxy servers, which are on the 10.254.140.0 network.

Scheduling
The front-end load balancing function of the appliance supports several types of scheduling.

Load balancing layer
Security Access Manager supports load balancing at layer 4 or layer 7 of the Open Systems Interconnection (OSI) network model.

Persistence
Session persistence, also known as stickiness, is a mechanism that ensures a client is connected to the same reverse proxy server during a session.

Network termination
The front-end load balancer that is provided in Security Access Manager, version 7.0, is a network terminating load balancer.

Benefits of layer 7 load balancing
The main benefit of layer 7 load balancing is the ability to use and manipulate the HTTP headers in requests and responses.

Configuring front-end load balancer
To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page.

Front-end load balancer advanced tuning parameters
Use these parameters to tune the frond-end load balancer configuration.

Parent topic: Web Reverse Proxy administration

SchedulingSchedulingAccess Manager Appliance: SchedulingThe front-end load balancing function of the appliance supports several types of scheduling.schedulingfront-end load balancersschedulingappliancesfront-end load balancersload balancersconfigurationIn your environment, you might have some servers that are more powerful than others. You can configure the front-end load balancer to respect the relative performance of each server by setting a weight value for each server. You can assign weights between 1 and 256, with 256 indicating the most powerful server. For more information about how to configure the weight of each server and select the scheduling algorithm, see Configuring front-end load balancer To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page..The following scheduling types are supported:lcLeast connection. The server with the lowest number of connections receives the request. This algorithm is dynamic so you can update the weight ratios in real time. rrRound robin. Requests are rotated between the servers. This algorithm is dynamic and uses the weight parameter that is assigned to each server.srrStatic round robin. Each server is used in turn according to the defined weight for the server. This algorithm is static so you cannot dynamically change the weight ratio for a server.shSource hashing. A hash of the source IP is divided by the total weight of the running servers to determine which server receives the request. This algorithm inherently sends requests from the same IP address to the same server provided that the available servers remains unchanged.Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

Scheduling

The front-end load balancing function of the appliance supports several types of scheduling.

In your environment, you might have some servers that are more powerful than others. You can configure the front-end load balancer to respect the relative performance of each server by setting a weight value for each server. You can assign weights between 1 and 256, with 256 indicating the most powerful server.

For more information about how to configure the weight of each server and select the scheduling algorithm, see Configuring front-end load balancer.

The following scheduling types are supported:

lc

Least connection. The server with the lowest number of connections receives the request. This algorithm is dynamic so you can update the weight ratios in real time.

rr

Round robin. Requests are rotated between the servers. This algorithm is dynamic and uses the weight parameter that is assigned to each server.

srr

Static round robin. Each server is used in turn according to the defined weight for the server. This algorithm is static so you cannot dynamically change the weight ratio for a server.

sh

Source hashing. A hash of the source IP is divided by the total weight of the running servers to determine which server receives the request. This algorithm inherently sends requests from the same IP address to the same server provided that the available servers remains unchanged.

Parent topic: Front-end load balancer

Load balancing layerLoad balancing layerAccess Manager Appliance: Load balancing layerSecurity Access Manager supports load balancing at layer 4 or layer 7 of the Open Systems Interconnection (OSI) network model.load balancerslayersfront-end load balancerslayersapplication layerlayer 7load balancingTCPlayersheader informationOSI network modelFor each service, you can configure either of the following load balancing layers: TCP Layer (Layer 4) At this layer, the load balancer can use the TCP header information to determine how to process the request. Application Layer (Layer 7) At this layer, the load balancer can recognize application requests (for example, HTTP requests) and process these requests accordingly. Layer 7 offers the following extra features when compared to layer 4 load balancing: Ability to use an HTTP cookie to provide stickiness. For more information, see PersistenceSession persistence, also known as stickiness, is a mechanism that ensures a client is connected to the same reverse proxy server during a session. .Ability to use and manipulate the headers in HTTP requests and responses. For more information, see Benefits of layer 7 load balancingThe main benefit of layer 7 load balancing is the ability to use and manipulate the HTTP headers in requests and responses..If you do not require these features, use layer 4 load balancing. Layer 4 load balancing is the most efficient type of load balancing. Layer 7 load balancers incur extra processing costs as they need to complete the following extra tasks: SSL termination.HTTP packet inspection.HTTP header manipulation (as required).For more information about configuring the load balancing layer, see Configuring front-end load balancer To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page..Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

Load balancing layer

Security Access Manager supports load balancing at layer 4 or layer 7 of the Open Systems Interconnection (OSI) network model.

For each service, you can configure either of the following load balancing layers:

TCP Layer (Layer 4)

At this layer, the load balancer can use the TCP header information to determine how to process the request.

Application Layer (Layer 7)

At this layer, the load balancer can recognize application requests (for example, HTTP requests) and process these requests accordingly.

Layer 7 offers the following extra features when compared to layer 4 load balancing:

Ability to use an HTTP cookie to provide stickiness. For more information, see Persistence.

Ability to use and manipulate the headers in HTTP requests and responses. For more information, see Benefits of layer 7 load balancing.

If you do not require these features, use layer 4 load balancing. Layer 4 load balancing is the most efficient type of load balancing. Layer 7 load balancers incur extra processing costs as they need to complete the following extra tasks:

SSL termination.

HTTP packet inspection.

HTTP header manipulation (as required).

For more information about configuring the load balancing layer, see Configuring front-end load balancer.

Parent topic: Front-end load balancer

PersistencePersistenceAccess Manager Appliance: PersistenceSession persistence, also known as stickiness, is a mechanism that ensures a client is connected to the same reverse proxy server during a session. persistencefront-end load balancerspersistencestickinesslayer 7HTTP cookiesstickinessload balancerslayerssessionspersistenceTCPheader informationWebSEALsessionsLayer 4 load balancers can extract the client IP address from the TCP header to maintain persistence. Layer 7 load balancers can use an HTTP cookie to provide stickiness. Subsequent requests from a particular client are routed through the same processing path and use the same WebSEAL session. Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

Persistence

Session persistence, also known as stickiness, is a mechanism that ensures a client is connected to the same reverse proxy server during a session.

Layer 4 load balancers can extract the client IP address from the TCP header to maintain persistence. Layer 7 load balancers can use an HTTP cookie to provide stickiness. Subsequent requests from a particular client are routed through the same processing path and use the same WebSEAL session.

Parent topic: Front-end load balancer

Network terminationNetwork terminationAccess Manager Appliance: Network terminationThe front-end load balancer that is provided in Security Access Manager, version 7.0, is a network terminating load balancer. networkterminationterminationnetworkslayer 7SSL terminationfront-end load balancersnetwork terminationSSLterminationload balancersnetwork terminationWeb Reverse ProxyserversClients send requests directly to the virtual IP address of the front-end load balancer. The front-end load balancer processes each request. The load balancer terminates the network connection of the request from the client. It then creates a new network connection to forward the load-balanced request to the appropriate backend server. The Web Reverse Proxy server receives the request from the front-end load balancer and processes it. The Web Reverse Proxy server sends its response back to the front-end load balancer. The load balancer acts as a proxy and sends the information back to the original client. Network terminationNetwork terminationThe point of SSL termination depends on the load balancing layer. In a layer 4 configuration, WebSEAL is responsible for the SSL termination. In a layer 7 configuration, SSL is terminated by the load balancer. When SSL is terminated by the front-end load balancer, the load balancer forwards the request to the backend server by using HTTP instead of HTTPS.Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

Network termination

The front-end load balancer that is provided in Security Access Manager, version 7.0, is a network terminating load balancer.

Clients send requests directly to the virtual IP address of the front-end load balancer. The front-end load balancer processes each request.

The load balancer terminates the network connection of the request from the client. It then creates a new network connection to forward the load-balanced request to the appropriate backend server.

The Web Reverse Proxy server receives the request from the front-end load balancer and processes it. The Web Reverse Proxy server sends its response back to the front-end load balancer. The load balancer acts as a proxy and sends the information back to the original client.

Figure 88. Network termination

The point of SSL termination depends on the load balancing layer. In a layer 4 configuration, WebSEAL is responsible for the SSL termination. In a layer 7 configuration, SSL is terminated by the load balancer. When SSL is terminated by the front-end load balancer, the load balancer forwards the request to the backend server by using HTTP instead of HTTPS.

Parent topic: Front-end load balancer

Benefits of layer 7 load balancingBenefits of layer 7 load balancingAccess Manager Appliance: Layer 7 load balancing benefitsThe main benefit of layer 7 load balancing is the ability to use and manipulate the HTTP headers in requests and responses.layer 7benefitsload balancerslayer 7front-end load balancerslayersHTTP headersrequestsresponsesdomainsnamesWhen a layer 7 load balancer processes a request from a particular client for the first time, it adds a load balancer cookie to the HTTP request. The front-end load balancer checks for this load balancer cookie in each subsequent request to provide persistence, or stickiness. When you configure Security Access Manager version 7.0 to use layer 7 load balancing, you must specify the name of this cookie for each service.If you use a layer 7 load balancer, you have access to extra attributes that you can use to manipulate the HTTP requests and responses. For example, you can use the replace attributes, such as reqrep, to rewrite URLs or domain names in "Host" headers.The available attributes for header manipulation are as follows:reqaddAdds a header to the end of the HTTP request.reqdelHeaders that match a specified regular expression are deleted from the request.reqrep(Case-sensitive) Search the HTTP request line for a specified regular expression and replace any instances with a specified string.reqirep(Case-insensitive) Search the HTTP request line for a specified regular expression and replace any instances with a specified string.rspaddAdds a header to the end of the HTTP response.rspdelHeaders that match a specified regular expression are deleted from the response.rsprep(Case-sensitive) Search the HTTP response line for a specified regular expression and replace any instances with a specified string.rspirep(Case-insensitive) Search the HTTP response line for a specified regular expression and replace any instances with a specified string.The available attributes to assist with HTTP header based balancing are as follows:balancehdr(<name>) Overrides the standard scheduler to enable balancing on the specified HTTP request header.There are also generic attributes to configure connection properties for the front-end load balancer. For example, you can set values for the connection timeout, number of retries, and number of concurrent connections. For a complete list of the available attributes, see Configuring front-end load balancer To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page..Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

Benefits of layer 7 load balancing

The main benefit of layer 7 load balancing is the ability to use and manipulate the HTTP headers in requests and responses.

When a layer 7 load balancer processes a request from a particular client for the first time, it adds a load balancer cookie to the HTTP request. The front-end load balancer checks for this load balancer cookie in each subsequent request to provide persistence, or stickiness. When you configure Security Access Manager version 7.0 to use layer 7 load balancing, you must specify the name of this cookie for each service.

If you use a layer 7 load balancer, you have access to extra attributes that you can use to manipulate the HTTP requests and responses. For example, you can use the replace attributes, such as reqrep, to rewrite URLs or domain names in "Host" headers.

The available attributes for header manipulation are as follows:

reqadd

Adds a header to the end of the HTTP request.

reqdel

Headers that match a specified regular expression are deleted from the request.

reqrep

(Case-sensitive) Search the HTTP request line for a specified regular expression and replace any instances with a specified string.

reqirep

(Case-insensitive) Search the HTTP request line for a specified regular expression and replace any instances with a specified string.

rspadd

Adds a header to the end of the HTTP response.

rspdel

Headers that match a specified regular expression are deleted from the response.

rsprep

(Case-sensitive) Search the HTTP response line for a specified regular expression and replace any instances with a specified string.

rspirep

(Case-insensitive) Search the HTTP response line for a specified regular expression and replace any instances with a specified string.

The available attributes to assist with HTTP header based balancing are as follows:

balance

hdr(<name>) Overrides the standard scheduler to enable balancing on the specified HTTP request header.

There are also generic attributes to configure connection properties for the front-end load balancer. For example, you can set values for the connection timeout, number of retries, and number of concurrent connections. For a complete list of the available attributes, see Configuring front-end load balancer.

Parent topic: Front-end load balancer

Configuring front-end load balancerConfiguring front-end load balancerAccess Manager Appliance: Configuring front-end load balancer To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page.load balancersfront-endconfigurationlayer 7SSL proxyfront-end load balancersconfigurationdebuggingmessagessecurity lognetworksettingsvirtualserversschedulingserviceslayer 7serversvirtualrealTCPlevelsFrom the top menu, select Manage System Settings Network SettingsFront End Load Balancer.On the General tab page:Select Enabled if you want to enable this front-end load balancer.Select Debug if you want more debug messages to be sent to the security log.Select Enable SSL if you plan to enable SSL communication for any Layer-7 services.In the SSL Key File list, select the key file that contains the certificates to be used in the Layer-7 SSL communication.The SSL Key File list can only be selected if Enable SSL is enabled.On the Advanced Tuning tab page, modify global level parameters to fine tune the configuration.Click Add.In the Add New Parameter window, select the desired parameter from the Name list.Enter a value for the selected parameter in the Value field.Click Save.On the Servers tab page, you can work with virtual servers and real servers. Each virtual server corresponds to an interface (virtual IP address and port) that is load balanced. Each real server corresponds to a load balanced server.Add a virtual serverClick New.On the Add Virtual Server page, define settings of the virtual server to be added. On the General tab page:FieldDescriptionEnabledSpecifies whether the new virtual server is active.NameName of the virtual server, which is used to uniquely identify this server.The syntax for the virtual server name must be treated as if it were a server host name. It must not contain any space characters.Virtual AddressSpecifies the IP address that connects this virtual server to the public network.PortSpecifies the port on which this virtual server listens.MaskSpecifies the network mask to be applied to the IP address for the virtual server.InterfaceSpecifies the appliance interface on which the new virtual server connects to the public network.Layer 4 or Layer 7The load balancing layer for the server. Layer 4 indicates TCP level load balancing. Layer 7 indicates application level load balancing.Cookie used in Layer 7The name of the cookie to be used in Layer 7 load balancing.This field is available only when Layer 7 load balancing has been selected.Layer 7 SSL EnabledWhether SSL is used to terminate the connection.This field is available only when Layer 7 load balancing has been selected.Layer 7 SSL Certificate LabelThe label of the certificate to be used when terminating the connection.This field is available only when Layer 7 load balancing has been selected.On the Scheduler tab page:FieldDescriptionSchedulerSpecifies the scheduling algorithm for distributing jobs to the real servers. Available choices are:lcLeast connection. The server with the lowest number of connections receives the request. This algorithm is dynamic so you can update the weight ratios in real time. rrRound robin. Requests are rotated between the servers. This algorithm is dynamic and uses the weight parameter that is assigned to each server.srrStatic round robin. Each server is used in turn according to the defined weight for the server. This algorithm is static so you cannot dynamically change the weight ratio for a server.shSource hashing. A hash of the source IP is divided by the total weight of the running servers to determine which server receives the request. This algorithm inherently sends requests from the same IP address to the same server provided that the available servers remains unchanged. For Layer 4 operations, only a scheduler setting of sh (source hash) specifies to use all CPUs available on the appliance. If other scheduler settings are used for Layer 4 operation, then the load balancer process operates that particular virtual server by using one CPU. This behavior might impact performance of the front end load balancer for the virtual server, particularly if the back-end servers are using SSL.For Layer 7 operations, all CPUs available are always used regardless of the scheduler setting.Health Check IntervalNumber of seconds between health check messages that are sent to the real servers.RiseThe number of successful health checks before a server is considered active.FallThe number of unsuccessful health checks before a server is considered inactive.Optional: On the Advanced Tuning tab page, add, edit, or delete any service level advanced configuration parameters as needed. See Front-end load balancer advanced tuning parametersUse these parameters to tune the frond-end load balancer configuration. for the available parameters. See Benefits of layer 7 load balancingThe main benefit of layer 7 load balancing is the ability to use and manipulate the HTTP headers in requests and responses. for descriptions of the advanced tuning attributes available.Click Save.Delete a virtual serverSelect the virtual server to delete from the list.Click Delete.On the confirmation page, click Yes.Edit a virtual serverSelect the virtual server to edit from the list.Click Edit.On the Edit Virtual Server page, modify the settings as needed.Click Save.Manage real serversFrom the list of virtual servers, select the virtual server to associate the real servers with.Click Real Servers. The Real Servers page is displayed.To add a real server: Click New.On the Add Real Server page that pops up, define settings for the server o be added.FieldDescriptionEnabledSpecifies whether the new real server is active.AddressSpecifies the IP address for the real server.WeightSpecifies an integer that represents this processing capacity of the server relative to that of other real servers. For example, a server assigned 2000 has twice the capacity of a sever assigned 1000. The weighted scheduling algorithms adjust this number dynamically based on workload.SSL EnabledSpecifies whether to use an SSL connection between the load balancer and the back-end server.SSL Certificate LabelSpecifies the SSL certificate label.Click Save.To delete a real server:Select the real server to delete from the list.Click Delete.On the confirmation page, click Yes.To edit a real server:Select the real server to edit from the list.Click Edit.On the Edit Real Server page, modify the settings as needed.Click Save.Click Close to return to the Front End Load Balancer main page.On the High Availability tab page, you can define the settings that enable high availability of the front-end load balancer function. For example, configure a second front-end load balancer as either a primary or a back-up load balancer for the environment.Select the Enable High Availability check box to enable this feature.Select Primary or Backup to designate this system as the primary or backup front-end load balancer.For the Local Interface - Primary field, select the local IP address of the front-end load balancer.For the Remote Address - Backup field, specify the IP address that is used by this system to communicate with the other front-end load balancer. This field is required if a backup load balancer is in use.For the Remote Port field, specify the port to be used for high availability communication.In the Health Check Interval field, specify in seconds the interval of the heartbeat messages that are sent between the primary and backup front-end load balancers.In the Health Check Timeout field, specify in seconds the time to wait before the system declares a non-responsive router unavailable and initiating failover.On the Logging tab page, configure the local or remote logging options.If you select Log to local, no additional configuration is required on this page.If you select Log to remote, you must provide values for Syslog facility, Remote syslog server address, and Remote syslog server port.On the Error Pages tab page, customize the error pages (200, 400, 403, 408, 500, 502, 503, and 504) that are returned by the software. These error pages are returned when the layer-7 load balancing function encounters a problem.To edit an existing error page:Select the error page to customize.Click Edit.In the Edit File window, modify the error page as needed.Click Save.To import a new page to replace an existing error page:Select the error page to be replaced.Click Import.In the Import Error Page window, click Browse.Select the new page.Click Save.To export an error page:Select the error page to export.Click Export.Specify the destination location to export the file to.Click Export to confirm the operation.Click Save to save all changes that are made on the Front End Load Balancer management page. For the changes to take effect, they must be deployed as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

Configuring front-end load balancer

To configure the front end load balancer with the local management interface, use the Front End Load Balancer management page.

Procedure

From the top menu, select Manage System Settings > Network Settings > Front End Load Balancer.

On the General tab page:

Select Enabled if you want to enable this front-end load balancer.

Select Debug if you want more debug messages to be sent to the security log.

Select Enable SSL if you plan to enable SSL communication for any Layer-7 services.

In the SSL Key File list, select the key file that contains the certificates to be used in the Layer-7 SSL communication.

Note: The SSL Key File list can only be selected if Enable SSL is enabled.

Optional: On the Advanced Tuning tab page, modify global level parameters to fine tune the configuration.

Click Add.

In the Add New Parameter window, select the desired parameter from the Name list.

Enter a value for the selected parameter in the Value field.

Click Save.

On the Servers tab page, you can work with virtual servers and real servers. Each virtual server corresponds to an interface (virtual IP address and port) that is load balanced. Each real server corresponds to a load balanced server.

Add a virtual server

Click New.

On the Add Virtual Server page, define settings of the virtual server to be added.

On the General tab page:

Field
Description

Enabled
Specifies whether the new virtual server is active.

Name
Name of the virtual server, which is used to uniquely identify this server.

Note: The syntax for the virtual server name must be treated as if it were a server host name. It must not contain any space characters.

Virtual Address
Specifies the IP address that connects this virtual server to the public network.

Port
Specifies the port on which this virtual server listens.

Mask
Specifies the network mask to be applied to the IP address for the virtual server.

Interface
Specifies the appliance interface on which the new virtual server connects to the public network.

Layer 4 or Layer 7
The load balancing layer for the server. Layer 4 indicates TCP level load balancing. Layer 7 indicates application level load balancing.

Cookie used in Layer 7
The name of the cookie to be used in Layer 7 load balancing.

Note: This field is available only when Layer 7 load balancing has been selected.

Layer 7 SSL Enabled
Whether SSL is used to terminate the connection.

Note: This field is available only when Layer 7 load balancing has been selected.

Layer 7 SSL Certificate Label
The label of the certificate to be used when terminating the connection.

Note: This field is available only when Layer 7 load balancing has been selected.

On the Scheduler tab page:

Field
Description

Scheduler
Specifies the scheduling algorithm for distributing jobs to the real servers. Available choices are:

lc

Least connection. The server with the lowest number of connections receives the request. This algorithm is dynamic so you can update the weight ratios in real time.

rr

Round robin. Requests are rotated between the servers. This algorithm is dynamic and uses the weight parameter that is assigned to each server.

srr

Static round robin. Each server is used in turn according to the defined weight for the server. This algorithm is static so you cannot dynamically change the weight ratio for a server.

sh

Source hashing. A hash of the source IP is divided by the total weight of the running servers to determine which server receives the request. This algorithm inherently sends requests from the same IP address to the same server provided that the available servers remains unchanged.

For Layer 4 operations, only a scheduler setting of sh (source hash) specifies to use all CPUs available on the appliance. If other scheduler settings are used for Layer 4 operation, then the load balancer process operates that particular virtual server by using one CPU. This behavior might impact performance of the front end load balancer for the virtual server, particularly if the back-end servers are using SSL.

For Layer 7 operations, all CPUs available are always used regardless of the scheduler setting.

Health Check Interval
Number of seconds between health check messages that are sent to the real servers.

Rise
The number of successful health checks before a server is considered active.

Fall
The number of unsuccessful health checks before a server is considered inactive.

Optional: On the Advanced Tuning tab page, add, edit, or delete any service level advanced configuration parameters as needed. See Front-end load balancer advanced tuning parameters for the available parameters. See Benefits of layer 7 load balancing for descriptions of the advanced tuning attributes available.

Click Save.

Delete a virtual server

Select the virtual server to delete from the list.

Click Delete.

On the confirmation page, click Yes.

Edit a virtual server

Select the virtual server to edit from the list.

Click Edit.

On the Edit Virtual Server page, modify the settings as needed.

Click Save.

Manage real servers

From the list of virtual servers, select the virtual server to associate the real servers with.

Click Real Servers. The Real Servers page is displayed.

To add a real server:

Click New.

On the Add Real Server page that pops up, define settings for the server o be added.

Field | Description
Enabled | Specifies whether the new real server is active.
Address | Specifies the IP address for the real server.
Weight | Specifies an integer that represents this processing capacity of the server relative to that of other real servers. For example, a server assigned 2000 has twice the capacity of a sever assigned 1000. The weighted scheduling algorithms adjust this number dynamically based on workload.
SSL Enabled | Specifies whether to use an SSL connection between the load balancer and the back-end server.
SSL Certificate Label | Specifies the SSL certificate label.

Click Save.

To delete a real server:

Select the real server to delete from the list.

Click Delete.

On the confirmation page, click Yes.

To edit a real server:

Select the real server to edit from the list.

Click Edit.

On the Edit Real Server page, modify the settings as needed.

Click Save.

Click Close to return to the Front End Load Balancer main page.

On the High Availability tab page, you can define the settings that enable high availability of the front-end load balancer function. For example, configure a second front-end load balancer as either a primary or a back-up load balancer for the environment.

Select the Enable High Availability check box to enable this feature.

Select Primary or Backup to designate this system as the primary or backup front-end load balancer.

For the Local Interface - Primary field, select the local IP address of the front-end load balancer.

For the Remote Address - Backup field, specify the IP address that is used by this system to communicate with the other front-end load balancer. This field is required if a backup load balancer is in use.

For the Remote Port field, specify the port to be used for high availability communication.

In the Health Check Interval field, specify in seconds the interval of the heartbeat messages that are sent between the primary and backup front-end load balancers.

In the Health Check Timeout field, specify in seconds the time to wait before the system declares a non-responsive router unavailable and initiating failover.

On the Logging tab page, configure the local or remote logging options.

If you select Log to local, no additional configuration is required on this page.

If you select Log to remote, you must provide values for Syslog facility, Remote syslog server address, and Remote syslog server port.

On the Error Pages tab page, customize the error pages (200, 400, 403, 408, 500, 502, 503, and 504) that are returned by the software. These error pages are returned when the layer-7 load balancing function encounters a problem.

To edit an existing error page:

Select the error page to customize.

Click Edit.

In the Edit File window, modify the error page as needed.

Click Save.

To import a new page to replace an existing error page:

Select the error page to be replaced.

Click Import.

In the Import Error Page window, click Browse.

Select the new page.

Click Save.

To export an error page:

Select the error page to export.

Click Export.

Specify the destination location to export the file to.

Click Export to confirm the operation.

Click Save to save all changes that are made on the Front End Load Balancer management page.

Note: For the changes to take effect, they must be deployed as described in Configuration changes commit process.

Parent topic: Front-end load balancer

Front-end load balancer advanced tuning parametersUse these parameters to tune the frond-end load balancer configuration.The following parameters are supported at the global level.Frone-end load balancer advanced tuning parameters at global levelParameterValueDescriptionlog-send-hostname[ <string> ]Sets the hostname field in the syslog header. If optional "string" parameter is set, the header is set to the string contents. Otherwise, the hostname of the system is used. Generally used if one is not relaying logs through an intermediate syslog server or for simply customizing the hostname printed in the logs.log-tag<string>Sets the tag field in the syslog header to this string. It defaults to the program name as launched from the command line, which usually is "haproxy". Sometimes it can be useful to differentiate between multiple processes running on the same host.node<name>Only letters, digits, hyphen, and underscore are allowed, like in DNS names. This statement is useful in HA configurations where two or more processes or servers share the same IP address. By setting a different node-name on all nodes, it becomes easy to immediately spot what server is handling the traffic.maxconn<number>Sets the maximum per-process number of concurrent connections to <number>. It is equivalent to the command-line argument "-n". Proxies will stop accepting connections when this limit is reached. The "select" poller cannot reliably use more than 1024 file descriptors on some platforms. If your platform only supports select and reports "select FAILED" on startup, you need to reduce maxconn until it works (slightly below 500 in general).The following parameters are supported for each virtual server.Front-end load balancer advanced tuning parameters at virtual server levelParameterValueDescriptionfullconn<conns>Specify at what backend load the servers will reach their maxconn. <conns> is the number of connections on the backend which will make the servers use the maximal number of connections.http-check_disable-on-404Enable a maintenance mode upon HTTP/404 response to health-checks. When this option is set, a server which returns an HTTP code 404 will be excluded from further load-balancing, but will still receive persistent connections.http-send-name-header[ <header> ]Add the server name to a request. Use the header string given by <header>.maxconn<number>Sets the maximum per-process number of concurrent connections to <number>. It is equivalent to the command-line argument "-n". Proxies will stop accepting connections when this limit is reached. The "select" poller cannot reliably use more than 1024 file descriptors on some platforms. If your platform only supports select and reports "select FAILED" on startup, you need to reduce maxconn until it works (slightly below 500 in general).option_abortoncloseEnable or disable early dropping of aborted requests pending in queues.option_accept-invalid-http-requestEnable or disable relaxing of HTTP request parsing.option_accept-invalid-http-responseEnable or disable relaxing of HTTP response parsing.option_clitcpkaEnable or disable the sending of TCP keepalive packets on the client side.option_dontlog-normalEnable or disable logging of normal, successful connections.option_dontlog-nullEnable or disable logging of null connections.option_forcecloseEnable or disable active connection closing after response is transferred.option_forwardfor[ except <network> ] [ header <name> ] [ if-none ]Enable insertion of the X-Forwarded-For header to requests sent to servers.<network> is an optional argument used to disable this option for sources matching <network>. <name> is an optional argument to specify a different "X-Forwarded-For" header name.option_http-server-closeEnable or disable HTTP connection closing on the server side.option_httpcloseEnable or disable passive HTTP connection closing.option_log-health-checksEnable or disable logging of health checks status updates.option_nolingerEnable or disable immediate session resource cleaning after close.option_srvtcpkaEnable or disable the sending of TCP keepalive packets on the server side.rate-limit_sessions<rate>Set a limit on the number of new sessions accepted per second on a front end.reqadd<string> [{if | unless} <cond> ]Add a header at the end of the HTTP request. <string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\'). <cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.reqdel<search> [{if | unless} <cond> ]Delete all headers matching a regular expression in an HTTP request. <search> is the regular expression applied to HTTP headers and to the request line. This is an extended regular expression. Parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time. <cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.reqrep / reqirep<search> <string> [{if | unless} <cond> ]Replace a regular expression with a string in an HTTP request line. <search> is the regular expression applied to HTTP headers and to the request line. This is an extended regular expression. Parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time. The reqrep keyword strictly matches case while reqirep ignores case. <string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\'). References to matched pattern groups are possible using the common \N form, with N being a single digit between 0 and 9. <cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.retries<value>Set the number of retries to perform on a server after a connection failure. <value> is the number of times a connection attempt should be retried on a server when a connection either is refused or times out. The default value is 3.rspadd<string> [{if | unless} <cond> ]Add a header at the end of the HTTP response. <string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\'). <cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.rspdel<search> [{if | unless} <cond>]Delete all headers matching a regular expression in an HTTP response. <search> is the regular expression applied to HTTP headers and to the response line. This is an extended regular expression, so parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time. <cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.rsprep / rspirep<search> <string> [{if | unless} <cond>]Replace a regular expression with a string in an HTTP response line. <search> is the regular expression applied to HTTP headers and to the response line. This is an extended regular expression, so parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time. The rsprep keyword strictly matches case while rspirep ignores case. <string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\'). References to matched pattern groups are possible using the common \N form, with N being a single digit between 0 and 9. <cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.source<addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ], <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ], <addr>[:<port>] [interface <name>]Set the source address for outgoing connections. <addr> is the IPv4 address HAProxy will bind to before connecting to a server. This address is also used as a source for health checks. <port> is an optional port. It is normally not needed but may be useful in some very specific contexts. The default value of zero means the system will select a free port. Note that port ranges are not supported in the backend. <addr2> is the IP address to present to the server when connections are forwarded in full transparent proxy mode. This is currently only supported on some patched Linux kernels. When this address is specified, clients connecting to the server will be presented with this address, while health checks will still use the address <addr>. <port2> is the optional port to present to the server when connections are forwarded in full transparent proxy mode (see <addr2> above). The default value of zero means the system will select a free port. <hdr> is the name of a HTTP header in which to fetch the IP to bind to. This is the name of a comma-separated header list which can contain multiple IP addresses. By default, the last occurrence is used. <occ> is the occurrence number of a value to be used in a multi-value header. This is to be used in conjunction with "hdr_ip(<hdr>)", in order to specify which occurrence to use for the source IP address. Positive values indicate a position from the first occurrence, 1 being the first one. Negative values indicate positions relative to the last one, -1 being the last one. This is helpful for situations where an X-Forwarded-For header is set at the entry point of an infrastructure and must be used several proxy layers away. When this value is not specified, -1 is assumed. Passing a zero here disables the feature. <name> is an optional interface name to which to bind to for outgoing traffic. On systems supporting this features (currently, only Linux), this allows one to bind all traffic to the server to this interface even if it is not the one the system would select based on routing tables. This should be used with extreme care. Note that using this option requires root privileges.tcp-request_inspect-delay<timeout>Set the maximum allowed time to wait for data during content inspection. <timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.timeout_client<timeout>Set the maximum inactivity time on the client side. <timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.timeout_connect<timeout>Set the maximum time to wait for a connection attempt to a server to succeed. <timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.timeout_http-keep-alive<timeout>Set the maximum allowed time to wait for a new HTTP request to appear. <timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.timeout_http-request<timeout>Set the maximum allowed time to wait for a complete HTTP request. <timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.timeout_queue<timeout>Set the maximum time to wait in the queue for a connection slot to be free. <timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.timeout server<timeout>Set the maximum inactivity time on the server side. <timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.Front-end load balancerThe appliance provides front-end load balancing function to automatically assign client requests to the appropriate reverse proxy server based on the scheduling specified algorithm.

Front-end load balancer advanced tuning parameters

Use these parameters to tune the frond-end load balancer configuration.

The following parameters are supported at the global level.

Table 192. Frone-end load balancer advanced tuning parameters at global level

Parameter
Value
Description

log-send-hostname
[ <string> ]

Sets the hostname field in the syslog header. If optional "string" parameter is set, the header is set to the string contents. Otherwise, the hostname of the system is used. Generally used if one is not relaying logs through an intermediate syslog server or for simply customizing the hostname printed in the logs.

log-tag
<string>

Sets the tag field in the syslog header to this string. It defaults to the program name as launched from the command line, which usually is "haproxy". Sometimes it can be useful to differentiate between multiple processes running on the same host.

node
<name>

Only letters, digits, hyphen, and underscore are allowed, like in DNS names.

This statement is useful in HA configurations where two or more processes or servers share the same IP address. By setting a different node-name on all nodes, it becomes easy to immediately spot what server is handling the traffic.

maxconn
<number>

Sets the maximum per-process number of concurrent connections to <number>. It is equivalent to the command-line argument "-n". Proxies will stop accepting connections when this limit is reached.

Note: The "select" poller cannot reliably use more than 1024 file descriptors on some platforms. If your platform only supports select and reports "select FAILED" on startup, you need to reduce maxconn until it works (slightly below 500 in general).

The following parameters are supported for each virtual server.

Table 193. Front-end load balancer advanced tuning parameters at virtual server level

Parameter
Value
Description

fullconn
<conns>

Specify at what backend load the servers will reach their maxconn. <conns> is the number of connections on the backend which will make the servers use the maximal number of connections.

http-check_disable-on-404

Enable a maintenance mode upon HTTP/404 response to health-checks. When this option is set, a server which returns an HTTP code 404 will be excluded from further load-balancing, but will still receive persistent connections.

http-send-name-header
[ <header> ]
Add the server name to a request. Use the header string given by <header>.

maxconn
<number>

Sets the maximum per-process number of concurrent connections to <number>. It is equivalent to the command-line argument "-n". Proxies will stop accepting connections when this limit is reached.

Note: The "select" poller cannot reliably use more than 1024 file descriptors on some platforms. If your platform only supports select and reports "select FAILED" on startup, you need to reduce maxconn until it works (slightly below 500 in general).

option_abortonclose

Enable or disable early dropping of aborted requests pending in queues.

option_accept-invalid-http-request

Enable or disable relaxing of HTTP request parsing.

option_accept-invalid-http-response

Enable or disable relaxing of HTTP response parsing.

option_clitcpka

Enable or disable the sending of TCP keepalive packets on the client side.

option_dontlog-normal

Enable or disable logging of normal, successful connections.

option_dontlog-null

Enable or disable logging of null connections.

option_forceclose

Enable or disable active connection closing after response is transferred.

option_forwardfor
[ except <network> ] [ header <name> ] [ if-none ]
Enable insertion of the X-Forwarded-For header to requests sent to servers.

<network> is an optional argument used to disable this option for sources matching <network>. <name> is an optional argument to specify a different "X-Forwarded-For" header name.

option_http-server-close

Enable or disable HTTP connection closing on the server side.

option_httpclose

Enable or disable passive HTTP connection closing.

option_log-health-checks

Enable or disable logging of health checks status updates.

option_nolinger

Enable or disable immediate session resource cleaning after close.

option_srvtcpka

Enable or disable the sending of TCP keepalive packets on the server side.

rate-limit_sessions
<rate>
Set a limit on the number of new sessions accepted per second on a front end.

reqadd
<string> [{if | unless} <cond> ]

Add a header at the end of the HTTP request.

<string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\').

<cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.

reqdel
<search> [{if | unless} <cond> ]

Delete all headers matching a regular expression in an HTTP request.

<search> is the regular expression applied to HTTP headers and to the request line. This is an extended regular expression. Parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time.

<cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.

reqrep / reqirep
<search> <string> [{if | unless} <cond> ]

Replace a regular expression with a string in an HTTP request line.

<search> is the regular expression applied to HTTP headers and to the request line. This is an extended regular expression. Parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time. The reqrep keyword strictly matches case while reqirep ignores case.

<string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\'). References to matched pattern groups are possible using the common \N form, with N being a single digit between 0 and 9.

<cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.

retries
<value>

Set the number of retries to perform on a server after a connection failure.

<value> is the number of times a connection attempt should be retried on a server when a connection either is refused or times out. The default value is 3.

rspadd
<string> [{if | unless} <cond> ]

Add a header at the end of the HTTP response.

<string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\').

<cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.

rspdel
<search> [{if | unless} <cond>]

Delete all headers matching a regular expression in an HTTP response.

<search> is the regular expression applied to HTTP headers and to the response line. This is an extended regular expression, so parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time.

<cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.

rsprep / rspirep
<search> <string> [{if | unless} <cond>]

Replace a regular expression with a string in an HTTP response line.

<search> is the regular expression applied to HTTP headers and to the response line. This is an extended regular expression, so parenthesis grouping is supported and no preliminary backslash is required. Any space or known delimiter must be escaped using a backslash ('\'). The pattern applies to a full line at a time. The rsprep keyword strictly matches case while rspirep ignores case.

<string> is the complete line to be added. Any space or known delimiter must be escaped using a backslash ('\'). References to matched pattern groups are possible using the common \N form, with N being a single digit between 0 and 9.

<cond> is an optional matching condition built from ACLs. It makes it possible to ignore this rule when other conditions are not met.

source
<addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ], <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ], <addr>[:<port>] [interface <name>]

Set the source address for outgoing connections.

<addr> is the IPv4 address HAProxy will bind to before connecting to a server. This address is also used as a source for health checks.

<port> is an optional port. It is normally not needed but may be useful in some very specific contexts. The default value of zero means the system will select a free port. Note that port ranges are not supported in the backend.

<addr2> is the IP address to present to the server when connections are forwarded in full transparent proxy mode. This is currently only supported on some patched Linux kernels. When this address is specified, clients connecting to the server will be presented with this address, while health checks will still use the address <addr>.

<port2> is the optional port to present to the server when connections are forwarded in full transparent proxy mode (see <addr2> above). The default value of zero means the system will select a free port.

<hdr> is the name of a HTTP header in which to fetch the IP to bind to. This is the name of a comma-separated header list which can contain multiple IP addresses. By default, the last occurrence is used.

<occ> is the occurrence number of a value to be used in a multi-value header. This is to be used in conjunction with "hdr_ip(<hdr>)", in order to specify which occurrence to use for the source IP address. Positive values indicate a position from the first occurrence, 1 being the first one. Negative values indicate positions relative to the last one, -1 being the last one. This is helpful for situations where an X-Forwarded-For header is set at the entry point of an infrastructure and must be used several proxy layers away. When this value is not specified, -1 is assumed. Passing a zero here disables the feature.

<name> is an optional interface name to which to bind to for outgoing traffic. On systems supporting this features (currently, only Linux), this allows one to bind all traffic to the server to this interface even if it is not the one the system would select based on routing tables. This should be used with extreme care. Note that using this option requires root privileges.

tcp-request_inspect-delay
<timeout>

Set the maximum allowed time to wait for data during content inspection.

<timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.

timeout_client
<timeout>

Set the maximum inactivity time on the client side.

<timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.

timeout_connect
<timeout>

Set the maximum time to wait for a connection attempt to a server to succeed.

<timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.

timeout_http-keep-alive
<timeout>

Set the maximum allowed time to wait for a new HTTP request to appear.

<timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.

timeout_http-request
<timeout>

Set the maximum allowed time to wait for a complete HTTP request.

<timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.

timeout_queue
<timeout>

Set the maximum time to wait in the queue for a connection slot to be free.

<timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.

timeout server
<timeout>

Set the maximum inactivity time on the server side.

<timeout> is the timeout value specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit.

Parent topic: Front-end load balancer

dscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.dscadmin commandCLIdscadmin commandcommand-line interfaceCLIDistributed Session Cache (DSC)administeringreplica setsnameslistingTo access this command, log onto the command-line interface (either by logging onto the appliance console, or performing an ssh into the machine), and then enter the isam menu, followed by the dscadmin sub-menu.The dscadmin command supports the following operations:replica set show replica_set_namereplica set list session terminate all_sessions user_id replica_set_namesession terminate session session-id replica-set-namesession list pattern maximum_return replica_set_nameexit quitWeb Reverse Proxy administrationIBM Security Access Manager Appliance provides procedures and reference information for managing the resources of your secure Web domain, including the Web Reverse Proxy or WebSEAL. The appliance administration interface provides these procedures when you activate the Access Manager Platform activation level.replica set showLists all session management replicas in the specified replica set. A replica is a client that has registered with the distributed session cache.replica set listLists all session management replica sets in the domain.session terminate all_sessionsTerminates all user sessions for a specific user within the specified replica set. session terminate sessionTerminates a user session using a session ID within the specified replica set.session listLists all session management sessions within the specified replica set.exit or quitUse either the exit command or the quit command to exit from the dscadmin utility interactive command-line mode.

dscadmin command

Use the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

To access this command, log onto the command-line interface (either by logging onto the appliance console, or performing an ssh into the machine), and then enter the isam menu, followed by the dscadmin sub-menu.

The dscadmin command supports the following operations:

replica set show replica_set_name

replica set list

session terminate all_sessions user_id replica_set_name

session terminate session session-id replica-set-name

session list pattern maximum_return replica_set_name

exit

quit

replica set show
Lists all session management replicas in the specified replica set. A replica is a client that has registered with the distributed session cache.

replica set list
Lists all session management replica sets in the domain.

session terminate all_sessions
Terminates all user sessions for a specific user within the specified replica set.

session terminate session
Terminates a user session using a session ID within the specified replica set.

session list
Lists all session management sessions within the specified replica set.

exit or quit
Use either the exit command or the quit command to exit from the dscadmin utility interactive command-line mode.

Parent topic: Web Reverse Proxy administration

replica set showreplica set showAccess Manager Appliance: replica set showLists all session management replicas in the specified replica set. A replica is a client that has registered with the distributed session cache.replica setsshowingsetsDistributed Session Cache (DSC)registered clientsdetailsreplica setsessionsmanagement replicasSyntaxreplica set show replica_set_nameOptionsreplica_set_nameSpecifies the name of the replica set.ExamplesThe following example returns details about the ibm.com replica set: dscadmin> replica set show ibm.comdscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

replica set show

Lists all session management replicas in the specified replica set. A replica is a client that has registered with the distributed session cache.

Syntax

replica set show replica_set_name

Options

replica_set_name

Specifies the name of the replica set.

Examples

The following example returns details about the ibm.com replica set:

dscadmin> replica set show ibm.com

Parent topic: dscadmin command

replica set listreplica set listAccess Manager Appliance: replica set listLists all session management replica sets in the domain.replica setslistingsetsdomainsreplica setslistingsession management sessionssessionsmanagement replicasSyntaxreplica set listOptionsN/AExamplesThe following example lists all the replica sets: dscadmin> replica set listdscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

replica set list

Lists all session management replica sets in the domain.

Syntax

replica set list

Options

N/A

Examples

The following example lists all the replica sets:

dscadmin> replica set list

Parent topic: dscadmin command

session terminate all_sessionssession terminate all_sessionsAccess Manager Appliance: session terminate all_sessionsTerminates all user sessions for a specific user within the specified replica set. sessionsterminationterminationsessionsreplica setssession terminationuserssessionsSyntaxsession terminate all_sessions user_id replica-set-nameOptionsuser_idSpecifies the name of the user. An example of user name is sec_master. Pattern matching can be used when specifying the user name.replica_set_nameSpecifies the name of the replica set.ExamplesThe following example terminates all sessions for the sec_master user in the ibm.com replica set:dscadmin> session terminate all_sessions sec_master ibm.comThe following example terminates all sessions whose user names start with sec_m in the ibm.com replica set:dscadmin> session terminate all_sessions sec_m* ibm.comdscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

session terminate all_sessions

Terminates all user sessions for a specific user within the specified replica set.

Syntax

session terminate all_sessions user_id replica-set-name

Options

user_id

Specifies the name of the user. An example of user name is sec_master. Pattern matching can be used when specifying the user name.

replica_set_name

Specifies the name of the replica set.

Examples

The following example terminates all sessions for the sec_master user in the ibm.com replica set:

dscadmin> session terminate all_sessions sec_master ibm.com

The following example terminates all sessions whose user names start with sec_m in the ibm.com replica set:

dscadmin> session terminate all_sessions sec_m* ibm.com

Parent topic: dscadmin command

session terminate sessionsession terminate sessionAccess Manager Appliance: session terminate sessionTerminates a user session using a session ID within the specified replica set.sessionsterminationterminationsessionsreplica setssession terminationuserssessionsSyntaxsession terminate session session-id replica-set-nameOptionssession-idSpecifies the ID of a user session.replica_set_nameSpecifies the name of the replica set.ExamplesThe following example terminates session 678 in the ibm.com replica set: dscadmin> session terminate session 678 ibm.comdscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

session terminate session

Terminates a user session using a session ID within the specified replica set.

Syntax

session terminate session session-id replica-set-name

Options

session-id

Specifies the ID of a user session.

replica_set_name

Specifies the name of the replica set.

Examples

The following example terminates session 678 in the ibm.com replica set:

dscadmin> session terminate session 678 ibm.com

Parent topic: dscadmin command

session listsession listAccess Manager Appliance: session listLists all session management sessions within the specified replica set.sessionslistingmanagementreplica setslistinglistingsession management sessionsuserssessionsSyntaxsession list pattern maximum_return replica_set_nameOptionspatternSpecifies the pattern for returning user names. The pattern can include a combination of wild card and string constant characters. The pattern is not case-sensitive. For example, you can specify *luca* or *LUCA* as the pattern to find all users that contain the substring luca in the user name. Only the asterisk (*) character can be used as wild card.maximum_returnSpecifies the maximum number of sessions to return. When there are more matches than designated by this option, the output contains the number of matches.replica_set_nameSpecifies the name of the replica set.ExamplesThe following example (entered as one line) lists the user sessions in the ibm.com replica set for users that contains the string ons and limits the number of matches to 100:dscadmin> session list *ons* 100 ibm.com dscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

session list

Lists all session management sessions within the specified replica set.

Syntax

session list pattern maximum_return replica_set_name

Options

pattern

Specifies the pattern for returning user names. The pattern can include a combination of wild card and string constant characters. The pattern is not case-sensitive. For example, you can specify *luca* or *LUCA* as the pattern to find all users that contain the substring luca in the user name.

Note: Only the asterisk (*) character can be used as wild card.

maximum_return

Specifies the maximum number of sessions to return. When there are more matches than designated by this option, the output contains the number of matches.

replica_set_name

Specifies the name of the replica set.

Examples

The following example (entered as one line) lists the user sessions in the ibm.com replica set for users that contains the string ons and limits the number of matches to 100:

dscadmin> session list *ons* 100 ibm.com

Parent topic: dscadmin command

exit or quitexit or quitAccess Manager Appliance: exit or quitUse either the exit command or the quit command to exit from the dscadmin utility interactive command-line mode.exitingquittingdscadmin commandSyntaxexit quitOptionsN/AExamplesThe following example displays how to exit the dscadmin utility:dscadmin> exit The following example displays how to quit the dscadmin utility:dscadmin> quitdscadmin commandUse the dscadmin command option from the command-line interface (CLI) to administer the distributed session cache.

exit or quit

Use either the exit command or the quit command to exit from the dscadmin utility interactive command-line mode.

Syntax

exit

quit

Options

N/A

Examples

The following example displays how to exit the dscadmin utility:

dscadmin> exit

The following example displays how to quit the dscadmin utility:

dscadmin> quit

Parent topic: dscadmin command

Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.AdministeringIBM Security Access Manager provides information about administering supported activation levels.Overview of context-based accessContext-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.Risk management overviewContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.Attribute collection serviceThe attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score.Attribute matchersAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.ObligationsObligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.Authentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute.Risk profilesThe risk engine uses the active risk profile to calculate risk scores for incoming requests. The administrator can create risk profiles or use predefined risk profiles that are provided with Advanced Access Control. Access control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.Device fingerprintsDevice registration is the process that stores the device fingerprint of the user in the context-based access database. Runtime databaseThe runtime database stores user data such as session attributes and device fingerprints.Policy information pointsPolicy information points gather information from the request or other sources, such as databases.ExtensionsUse extensions so that you can implement your own obligation handler and authentication mechanism.Deploying pending changesSome configuration and administration changes require an extra deployment step.Template filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors.SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. User self-administration tasksAdministrators can configure context-based access to enable users to perform certain self-management tasks.Access ControlAccess Control links include Policies, Resources, Attributes, and Obligations.AttributesAttributes links include Risk Profile, Attributes, and Matchers.AuthenticationAuthentication links include Policies, Mechanisms, and Advanced.ObligationsObligations links include Policies, Resources, Attributes and Obligations.Risk ProfileRisk Profile links include Attributes and Matchers.Managing server connectionsTo use data outside of the appliance, you can define server connections.Managing federations and partnersUse the local management interface to manage federation and partner properties.

Advanced Access Control administration

The Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Overview of context-based access
Context-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.

Risk management overview
Context-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.

Attributes
Attributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.

Attribute collection service
The attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score.

Attribute matchers
An attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.

Obligations
Obligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.

Authentication policies
Authentication policies are workflows that dictate the authentication mechanisms to execute.

Risk profiles
The risk engine uses the active risk profile to calculate risk scores for incoming requests. The administrator can create risk profiles or use predefined risk profiles that are provided with Advanced Access Control.

Access control policies
An access control policy is a set of conditions that, after they have been evaluated, determine access decisions.

Device fingerprints
Device registration is the process that stores the device fingerprint of the user in the context-based access database.

Runtime database
The runtime database stores user data such as session attributes and device fingerprints.

Policy information points
Policy information points gather information from the request or other sources, such as databases.

Extensions
Use extensions so that you can implement your own obligation handler and authentication mechanism.

Deploying pending changes
Some configuration and administration changes require an extra deployment step.

Template files
Template files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors.

SCIM configuration
Security Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol.

User self-administration tasks
Administrators can configure context-based access to enable users to perform certain self-management tasks.

Access Control
Access Control links include Policies, Resources, Attributes, and Obligations.

Attributes
Attributes links include Risk Profile, Attributes, and Matchers.

Authentication
Authentication links include Policies, Mechanisms, and Advanced.

Obligations
Obligations links include Policies, Resources, Attributes and Obligations.

Risk Profile
Risk Profile links include Attributes and Matchers.

Managing server connections
To use data outside of the appliance, you can define server connections.

Managing federations and partners
Use the local management interface to manage federation and partner properties.

Parent topic: Administering

Overview of context-based accessOverview of context-based accessContext-based access overviewContext-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.context-based accessoverviewcontext-based accessdefinitionContext-based access:Improves security during authentication and authorization of business transactions.Assesses risk based on static, contextual, and analytically calculated attributes.Calculates a risk score based on multiple weighted attributes.Provides policy rules that determine whether an access request must be permitted, denied, or challenged.You can configure context-based access to:Silently register or require users to register devices that they commonly use.Associate the registered devices with user credentials.Present a challenge or request additional authentication, if the user attempts to authenticate with the same credentials from another unregistered device.Enforce specific authentication mechanisms to access a particular protected resource.Use the behavioral patterns of the user as a factor in risk score calculation. For example, a user might attempt to access a protected resource at a time outside of normal business hours. You can configure the context-based access policy to deny access or force the user access to authenticate with a secondary challenge.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Business scenariosBusiness transactions that have an increased security risk factor can benefit by implementing context-based access.FeaturesContext-based access provides several capabilities to identify potential risk and limit the ability for an attacker to use stolen credentials.Functional overviewContext-based access includes an external authorization service (EAS), runtime authorization service, and attribute collection service.Transaction flowIn a typical context-based transaction, the user requests access to a protected resource. Context-based access calculates the risk score and determines whether access is permitted, denied, or permitted with an obligation.

Overview of context-based access

Context-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.

Context-based access:

Improves security during authentication and authorization of business transactions.

Assesses risk based on static, contextual, and analytically calculated attributes.

Calculates a risk score based on multiple weighted attributes.

Provides policy rules that determine whether an access request must be permitted, denied, or challenged.

You can configure context-based access to:

Silently register or require users to register devices that they commonly use.

Associate the registered devices with user credentials.

Present a challenge or request additional authentication, if the user attempts to authenticate with the same credentials from another unregistered device.

Enforce specific authentication mechanisms to access a particular protected resource.

Use the behavioral patterns of the user as a factor in risk score calculation. For example, a user might attempt to access a protected resource at a time outside of normal business hours. You can configure the context-based access policy to deny access or force the user access to authenticate with a secondary challenge.

Business scenarios
Business transactions that have an increased security risk factor can benefit by implementing context-based access.

Features
Context-based access provides several capabilities to identify potential risk and limit the ability for an attacker to use stolen credentials.

Functional overview
Context-based access includes an external authorization service (EAS), runtime authorization service, and attribute collection service.

Transaction flow
In a typical context-based transaction, the user requests access to a protected resource. Context-based access calculates the risk score and determines whether access is permitted, denied, or permitted with an obligation.

Parent topic: Advanced Access Control administration

Business scenariosBusiness scenariosContext-based access scenariosBusiness transactions that have an increased security risk factor can benefit by implementing context-based access.context-based accessbusiness scenariosThe following examples are some scenarios where you can use context-based access to provide a higher level of confidence for the transaction:A user tries to access sensitive information where a simple user ID and password authentication is not sufficient. However, the data is not sensitive enough to use a more complex authentication mechanism, such as token IDs.Users require access from remote locations that are not trusted and they use devices such as mobile devices and notebooks. To ensure that mobile users are authenticated sufficiently, the business requires a second factor authentication.Users need to access an application that provides sensitive business information. They might access the information outside of their regular work patterns.A user accesses a resource from a device that the user previously used and maintains typical usage patterns. Context-based access improves the user experience by limiting secondary authentication mechanisms.Overview of context-based accessContext-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.

Business scenarios

Business transactions that have an increased security risk factor can benefit by implementing context-based access.

The following examples are some scenarios where you can use context-based access to provide a higher level of confidence for the transaction:

A user tries to access sensitive information where a simple user ID and password authentication is not sufficient. However, the data is not sensitive enough to use a more complex authentication mechanism, such as token IDs.

Users require access from remote locations that are not trusted and they use devices such as mobile devices and notebooks. To ensure that mobile users are authenticated sufficiently, the business requires a second factor authentication.

Users need to access an application that provides sensitive business information. They might access the information outside of their regular work patterns.

A user accesses a resource from a device that the user previously used and maintains typical usage patterns. Context-based access improves the user experience by limiting secondary authentication mechanisms.

Parent topic: Overview of context-based access

FeaturesFeaturesContext-based access featuresContext-based access provides several capabilities to identify potential risk and limit the ability for an attacker to use stolen credentials.context-based accessfeaturesSilent device registration where the system does not require any user interaction.Ready-to-use, predefined policy attributes that are specific to context-based access.Scenario-based, predefined risk profiles.A risk-scoring engine that calculates a risk score for the current transaction based on the active risk profile. The risk score is based on configurable weights that are assigned to context attributes and behavior attributes. If the risk score is high, further challenges are presented to the user or access is denied. If the risk score is low, the user is permitted access.Overview of context-based accessContext-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.

Features

Context-based access provides several capabilities to identify potential risk and limit the ability for an attacker to use stolen credentials.

Silent device registration where the system does not require any user interaction.

Ready-to-use, predefined policy attributes that are specific to context-based access.

Scenario-based, predefined risk profiles.

A risk-scoring engine that calculates a risk score for the current transaction based on the active risk profile. The risk score is based on configurable weights that are assigned to context attributes and behavior attributes. If the risk score is high, further challenges are presented to the user or access is denied. If the risk score is low, the user is permitted access.

Parent topic: Overview of context-based access

Functional overviewFunctional overviewContext-based servicesContext-based access includes an external authorization service (EAS), runtime authorization service, and attribute collection service.context-based accessarchitecturecontext-based accesscomponentscontext-based accessoverviewfunctionalattribute collection servicedefinitionrisk-scoring enginedefinitionPolicy enforcement point (PEP)definitionPolicy decision point (PDP)definitionExternal authorization service (EAS)definitionPolicy information points (PIPs)definitionPolicy administration point (PAP)definitionThe following diagram illustrates the architecture of context-based access. The diagram also shows how the various components plug into WebSEAL. WebSEAL is a component available in the following IBM products:IBM Web Gateway ApplianceIBM Security Access ManagerTivoli Access Manager for e-business Context-based access architectureContext-based access architectureContext-based access runtime servicesContext-based access provides the following runtime services:Authorization serviceThe context-based access authorization service is a component of the runtime environment. The runtime authorization service stores the policy, calculates the risk score, and makes the access decision. The authorization service exposes an XACML over SOAP web service that third-party enforcement points can call to get authorization decisions.Attribute collection serviceThe attribute collection service is a Representational State Transfer (REST) service that collects web browser and location attributes from the user. The attribute collection service is a push service. You can configure the context-based access runtime service to use the collected attributes as the policy attributes for calculating risk. You can also use the Java ADK to plug in your custom implementation for a pull service that retrieves attributes from the user.Risk-scoring engineThe risk-scoring engine calculates the risk or confidence level. It provides a single integer that represents the risk score for the current transaction in the form of a percentage. The risk score is calculated based on the weights that are assigned to one or more of the following policy attributes that are part of the active risk profile:Device identification or fingerprint, such as details of hardware, IP address, location information, IP address reputation, operating system, web browser type, web browser version, web browser plug-ins, and screen resolution.Behavioral patterns, such as frequency of login, time of access, frequency of access, and type of transactions.Custom attributes that you can configure and manage through a pluggable interface. The context-based access authorization service is extensible and can also include external sources for attributes.The risk engine returns the final risk score as a policy attribute, which is the basis of the final authorization decision.Policy enforcement point (PEP)WebSEAL is the policy enforcement point for context-based access. Context-based access integrates with the existing WebSEAL authentication mechanisms, such as cross domain authentication service (CDAS) and external authentication interface (EAI). External authorization serviceThe runtime security services EAS plug-in for WebSEAL enforces the policy decision. The EAS takes the request data and sends an authorization decision request to the context-based access authorization service. The authorization service maps the authorization decision response to the appropriate WebSEAL action, such as permit, deny, or step-up authentication. You can manage the EAS with entries in the webseald.conf file with the WebSEAL stanza syntax. The isamcfg tool automates the configuration of the EAS for the predefined scenarios provided with the product.Policy information points (PIPs)Policy information points are components of the context-based access authorization service. They provide all the policy attributes that are not provided in the initial access request. The risk score and attributes that are pushed to the attribute collection service are provided to the authorization service through PIPs.Context-based access includes ready-to-use PIP implementations that provide the policy attributes that are required. You can also provide custom policy attributes to the authorization service through a custom PIP.Policy decision point (PDP)The runtime authorization service is the policy decision point for context-based access. This service is configured to use the PEP context-based access plug-in. The authorization decision is based on an authorization policy that uses policy attributes and PIPs that are specific to context-based access. The PIPs provide information, such as risk score, user location, and device type.The policy administration point (PAP)The IBM Security Access Manager appliance is the policy administration point for context-based access. Context-based access provides an administrative console for configuring and managing the policies, risk profiles, attributes, and weights, which are required for calculating risk.Overview of context-based accessContext-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.

Functional overview

Context-based access includes an external authorization service (EAS), runtime authorization service, and attribute collection service.

The following diagram illustrates the architecture of context-based access. The diagram also shows how the various components plug into WebSEAL. WebSEAL is a component available in the following IBM products:

IBM Web Gateway Appliance

IBM Security Access Manager

Tivoli Access Manager for e-business

Figure 89. Context-based access architecture

Context-based access runtime services

Context-based access provides the following runtime services:

Authorization service

The context-based access authorization service is a component of the runtime environment. The runtime authorization service stores the policy, calculates the risk score, and makes the access decision. The authorization service exposes an XACML over SOAP web service that third-party enforcement points can call to get authorization decisions.

Attribute collection service

The attribute collection service is a Representational State Transfer (REST) service that collects web browser and location attributes from the user. The attribute collection service is a push service. You can configure the context-based access runtime service to use the collected attributes as the policy attributes for calculating risk. You can also use the Java™ ADK to plug in your custom implementation for a pull service that retrieves attributes from the user.

Risk-scoring engine

The risk-scoring engine calculates the risk or confidence level. It provides a single integer that represents the risk score for the current transaction in the form of a percentage. The risk score is calculated based on the weights that are assigned to one or more of the following policy attributes that are part of the active risk profile:

Device identification or fingerprint, such as details of hardware, IP address, location information, IP address reputation, operating system, web browser type, web browser version, web browser plug-ins, and screen resolution.

Behavioral patterns, such as frequency of login, time of access, frequency of access, and type of transactions.

Custom attributes that you can configure and manage through a pluggable interface. The context-based access authorization service is extensible and can also include external sources for attributes.

The risk engine returns the final risk score as a policy attribute, which is the basis of the final authorization decision.

Policy enforcement point (PEP)

WebSEAL is the policy enforcement point for context-based access. Context-based access integrates with the existing WebSEAL authentication mechanisms, such as cross domain authentication service (CDAS) and external authentication interface (EAI).

External authorization service

The runtime security services EAS plug-in for WebSEAL enforces the policy decision. The EAS takes the request data and sends an authorization decision request to the context-based access authorization service. The authorization service maps the authorization decision response to the appropriate WebSEAL action, such as permit, deny, or step-up authentication. You can manage the EAS with entries in the webseald.conf file with the WebSEAL stanza syntax. The isamcfg tool automates the configuration of the EAS for the predefined scenarios provided with the product.

Policy information points (PIPs)

Policy information points are components of the context-based access authorization service. They provide all the policy attributes that are not provided in the initial access request. The risk score and attributes that are pushed to the attribute collection service are provided to the authorization service through PIPs.

Context-based access includes ready-to-use PIP implementations that provide the policy attributes that are required. You can also provide custom policy attributes to the authorization service through a custom PIP.

Policy decision point (PDP)

The runtime authorization service is the policy decision point for context-based access. This service is configured to use the PEP context-based access plug-in. The authorization decision is based on an authorization policy that uses policy attributes and PIPs that are specific to context-based access. The PIPs provide information, such as risk score, user location, and device type.

The policy administration point (PAP)

The IBM Security Access Manager appliance is the policy administration point for context-based access. Context-based access provides an administrative console for configuring and managing the policies, risk profiles, attributes, and weights, which are required for calculating risk.

Parent topic: Overview of context-based access

Transaction flowTransaction flowContext-based access transactionsIn a typical context-based transaction, the user requests access to a protected resource. Context-based access calculates the risk score and determines whether access is permitted, denied, or permitted with an obligation.context-based accesstransaction flowcontext-based accessoverviewprocessIn the following example of a context-based access transaction, the risk score indicates that the user must be presented with a challenge. The user successfully completes the challenge and receives permission to access the protected resource.Context-based access transaction flow exampleContext-based access transaction flow exampleThe following process explains the flow of the transaction in the example scenario:The user interacts through a web browser to submit authentication information and requests access to a protected resource. The protected resource is a junctioned web application that WebSEAL protects.WebSEAL inspects the request. WebSEAL is the reverse proxy server that interacts with all transactions. For the protected resource that the user requests, the WebSEAL policy (POP) is configured to call the runtime security services EAS plug-in to authorize the request. The EAS is a shared library plug-in, which is internal to the WebSEAL process, so there is no on-the-wire callout between WebSEAL and the EAS.The EAS first checks the local access manager policy. If the access manager denies access, then the EAS returns the response and does not continue with a forbidden response. If the access manager permits access, the EAS collects the context information about the user and the request. The WebSEAL azn-decision-info stanza has the specifications to create an XACML over SOAP authorization decision request. The EAS sends the request to the context-based access runtime authorization service for the authorization decision.The runtime authorization service (PDP) runs the configured policy and calls the appropriate PIPs based on the current policy. If a risk score policy attribute is requested, then the risk engine is called.The risk engine takes the context details, requests additional policy attributes, if required, and then calculates a risk score.The authorization service applies the risk score policy attribute against the authorization policy and returns an appropriate decision response to the runtime security services EAS.The EAS supports three decision types: permit, deny, and permit with obligation. In this example, a decision to permit with obligation is returned.If the policy decision is a simple permit or deny, the decision is mapped to the WebSEAL permit and not_permit decisions. The WebSEAL decisions are returned from the azn_svc_decision_access_allowed_ext call.If the response is to permit access, WebSEAL permits the request to continue to the requested resource.If the response is to deny access, WebSEAL displays an error page, which indicates that access is forbidden.The runtime security services EAS parses the response and returns one of the following EAS responses to WebSEAL: PermitDenyStep-up authentication levelsBrowser redirect to a location configured on the WebSEAL configuration fileIn this example, the response is a redirect to a location on the appliance runtime, so that WebSEAL can enforce the appropriate authentication challenge. The context-based access EAS also provides a configuration to map the returned obligation to a specific WebSEAL external authentication interface (EAI) mechanism. The EAI can be either a WebSEAL EAI or CDAS external authentication mechanism, which the customer or IBM Business Partner can implement.WebSEAL specifies the appropriate authentication mechanism to the user.The user is redirected to the authentication mechanism, which builds a challenge response.The challenge response is presented to the user.The user responds to the challenge.If the response of the user to the challenge request is successful, the challenge is processed. The EAI application returns the credentials of the user and a successful step-up level in the HTTP response to WebSEAL.WebSEAL updates the session of the user with the new credential details that the EAI application provides and redirects the user to the protected resource.The request from the user to access the protected resource is sent via 302 redirect. The request does not require any user interaction.WebSEAL inspects the request and directs the request to the runtime security services EAS for authorization.The EAS collects all context information about the user and the request and creates an XACML over SOAP decision request. The EAS sends the request to the runtime authorization service.The context-based access runtime service takes the context and other policy attributes and calculates a risk score. The runtime service applies the risk score against the configured authorization policy and returns a policy decision response to permit access.The runtime security services EAS interprets the response and returns the permit decision to WebSEAL.WebSEAL permits the original request to continue without going back to the web browser of the user. The user is not aware of the transaction process.Overview of context-based accessContext-based access provides access decision and enforcement that is based on a dynamic risk assessment or confidence level of a transaction. Context-based access uses behavioral and contextual data analytics to calculate risk.

Transaction flow

In a typical context-based transaction, the user requests access to a protected resource. Context-based access calculates the risk score and determines whether access is permitted, denied, or permitted with an obligation.

In the following example of a context-based access transaction, the risk score indicates that the user must be presented with a challenge. The user successfully completes the challenge and receives permission to access the protected resource.

Figure 90. Context-based access transaction flow example

The following process explains the flow of the transaction in the example scenario:

The user interacts through a web browser to submit authentication information and requests access to a protected resource. The protected resource is a junctioned web application that WebSEAL protects.

WebSEAL inspects the request.

WebSEAL is the reverse proxy server that interacts with all transactions. For the protected resource that the user requests, the WebSEAL policy (POP) is configured to call the runtime security services EAS plug-in to authorize the request. The EAS is a shared library plug-in, which is internal to the WebSEAL process, so there is no on-the-wire callout between WebSEAL and the EAS.

The EAS first checks the local access manager policy.

If the access manager denies access, then the EAS returns the response and does not continue with a forbidden response.

If the access manager permits access, the EAS collects the context information about the user and the request. The WebSEAL azn-decision-info stanza has the specifications to create an XACML over SOAP authorization decision request.

The EAS sends the request to the context-based access runtime authorization service for the authorization decision.

The runtime authorization service (PDP) runs the configured policy and calls the appropriate PIPs based on the current policy.

If a risk score policy attribute is requested, then the risk engine is called.

The risk engine takes the context details, requests additional policy attributes, if required, and then calculates a risk score.

The authorization service applies the risk score policy attribute against the authorization policy and returns an appropriate decision response to the runtime security services EAS.

The EAS supports three decision types: permit, deny, and permit with obligation. In this example, a decision to permit with obligation is returned.

If the policy decision is a simple permit or deny, the decision is mapped to the WebSEAL permit and not_permit decisions. The WebSEAL decisions are returned from the azn_svc_decision_access_allowed_ext call.

If the response is to permit access, WebSEAL permits the request to continue to the requested resource.

If the response is to deny access, WebSEAL displays an error page, which indicates that access is forbidden.

The runtime security services EAS parses the response and returns one of the following EAS responses to WebSEAL:

Permit

Deny

Step-up authentication levels

Browser redirect to a location configured on the WebSEAL configuration file

In this example, the response is a redirect to a location on the appliance runtime, so that WebSEAL can enforce the appropriate authentication challenge.

The context-based access EAS also provides a configuration to map the returned obligation to a specific WebSEAL external authentication interface (EAI) mechanism. The EAI can be either a WebSEAL EAI or CDAS external authentication mechanism, which the customer or IBM® Business Partner can implement.

WebSEAL specifies the appropriate authentication mechanism to the user.

The user is redirected to the authentication mechanism, which builds a challenge response.

The challenge response is presented to the user.

The user responds to the challenge.

If the response of the user to the challenge request is successful, the challenge is processed. The EAI application returns the credentials of the user and a successful step-up level in the HTTP response to WebSEAL.

WebSEAL updates the session of the user with the new credential details that the EAI application provides and redirects the user to the protected resource.

The request from the user to access the protected resource is sent via 302 redirect. The request does not require any user interaction.

WebSEAL inspects the request and directs the request to the runtime security services EAS for authorization.

The EAS collects all context information about the user and the request and creates an XACML over SOAP decision request. The EAS sends the request to the runtime authorization service.

The context-based access runtime service takes the context and other policy attributes and calculates a risk score. The runtime service applies the risk score against the configured authorization policy and returns a policy decision response to permit access.

The runtime security services EAS interprets the response and returns the permit decision to WebSEAL.

WebSEAL permits the original request to continue without going back to the web browser of the user. The user is not aware of the transaction process.

Parent topic: Overview of context-based access

Risk management overviewRisk management overviewRisk managementContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.risk profileconfigurationconfigurationrisk profileconfigurationweights of attributesconfigurationsession attributesconfigurationattribute matchersattributes device registrationThe system allows for multiple risk profiles to be defined, but only one is active at run time. Each attribute included on a risk profile has an assigned weight to be used while calculating the risk score of a given request. The active risk profile attributes are evaluated to determine whether a user should be granted access to a protected resource. A policy author can rely on the risk score to enforce stronger authentication mechanisms or to perform device registration.To get started setting up context-based access control for your installation, work with:AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.: The product provides a predefined set of attributes that are ready to use without any customization. Optionally, you can add attributes that can come from:Standard HTTP headersHTTP FORM parametersClient-side JavaScript files that are collected into the attribute collection serviceCustom attributes you define by writing custom JavaScript filesObligationsObligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.: The product provides a predefined set of obligations that are ready to use without any customization. Optionally, you can update or define your own obligations.Risk profilesThe risk engine uses the active risk profile to calculate risk scores for incoming requests. The administrator can create risk profiles or use predefined risk profiles that are provided with Advanced Access Control. : The product provides a predefined set of risk profiles that are ready to use without any customization. Optionally, you can update or define your own risk profiles to calculate the risk score.A default risk profile is set as active when you configure the appliance. This risk profile is not intended to be used in a production environment. Set a different risk profile before using risk profiles in your production environment.PoliciesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.: Create policies that evaluate requests that are based on attributes and obligations that you defined and the risk decisions that you want to make. Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Risk score calculationRisk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.Risk reportsRisk reports illustrate the comparison between the incoming device fingerprint and the registered device fingerprint for each risk score calculation. Configuring risk reportsThe risk engine generates risk reports to analyze risk score calculation scenarios. The administrator can configure the riskEngine.reportsEnabled property and the riskEngine.reportsMaxStored property to enable the risk engine to store a specified number of these reports.Accessing risk reportsThe administrator can access the risk reports that are generated during risk score calculation scenarios.

Risk management overview

Context-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.

The system allows for multiple risk profiles to be defined, but only one is active at run time.

Each attribute included on a risk profile has an assigned weight to be used while calculating the risk score of a given request. The active risk profile attributes are evaluated to determine whether a user should be granted access to a protected resource. A policy author can rely on the risk score to enforce stronger authentication mechanisms or to perform device registration.

To get started setting up context-based access control for your installation, work with:

Attributes: The product provides a predefined set of attributes that are ready to use without any customization. Optionally, you can add attributes that can come from:

Standard HTTP headers

HTTP FORM parameters

Client-side JavaScript files that are collected into the attribute collection service

Custom attributes you define by writing custom JavaScript files

Obligations: The product provides a predefined set of obligations that are ready to use without any customization. Optionally, you can update or define your own obligations.

Risk profiles: The product provides a predefined set of risk profiles that are ready to use without any customization. Optionally, you can update or define your own risk profiles to calculate the risk score.

Note: A default risk profile is set as active when you configure the appliance. This risk profile is not intended to be used in a production environment. Set a different risk profile before using risk profiles in your production environment.

Policies: Create policies that evaluate requests that are based on attributes and obligations that you defined and the risk decisions that you want to make.

Risk score calculation
Risk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.

Risk reports
Risk reports illustrate the comparison between the incoming device fingerprint and the registered device fingerprint for each risk score calculation.

Configuring risk reports
The risk engine generates risk reports to analyze risk score calculation scenarios. The administrator can configure the riskEngine.reportsEnabled property and the riskEngine.reportsMaxStored property to enable the risk engine to store a specified number of these reports.

Accessing risk reports
The administrator can access the risk reports that are generated during risk score calculation scenarios.

Parent topic: Advanced Access Control administration

Risk score calculationRisk score calculationRisk score calculationRisk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.risk score calculationrisk score calculationdevice fingerprintrisk enginerisk scorethreshold scoredevice fingerprintrisk score calculationrisk enginerisk score calculationrisk scorerisk score calculationthreshold scorerisk score calculationOverviewThe risk engine determines a risk score by comparing sets of attributes that identify devices. These sets of attributes are called device fingerprints. Device fingerprint attributes include items such as IP address, location, and screen size. Each registered device has one device fingerprint. Because the user accesses the resource in different locations and on different devices, the user can have many registered devices.The following process describes how risk assessment works: The incoming device requests access to the resource.The risk engine collects as many device fingerprint attributes as it can from the request device.After the attributes are collected, the risk engine:Determines the device fingerprint.Calculates the risk score. The risk scoreIs a number. Represents the amount of risk that is associated with the incoming request.Indicates the likelihood that the incoming request represents the user.The risk engine: Compares the incoming fingerprint with each registered device fingerprint.Uses the attributes that are contained in the larger fingerprint for each comparison.Calculates a risk score for each comparison.To determine the final risk score, the risk engine: Chooses the lowest risk score of the comparisons between the incoming fingerprint and the registered fingerprint.Measures the final risk score against a threshold score or range that the administrator sets in a policy.Depending on the way the administrator writes the policy, one of the following outcomes occurs: PermitThe risk score for the incoming request is well below the threshold score. The user is granted access to the resource. For example, the risk score is 30, and the threshold score that is set by the administrator is 40.Permit with obligation or authenticationThe user is asked to complete an extra security measure, such as step up authentication. For example, the risk score is 40, and the policy that the administrator wrote requires users that operate devices with scores 30 - 90 to step up.DenyThe risk score for the incoming request is above the threshold score or range. The user is denied access to the resource. For example, the risk score is 50, and the threshold score that is set by the administrator is 40.The risk score is calculated through the following formula:Risk Score = (total weight of mismatched attributes / total weight of all attributes) × 100When the values that belong to the incoming device fingerprint and the registered device fingerprint are the same, the values are matched. When the values that belong to the incoming device fingerprint and the registered device fingerprint are not the same, the values are mismatched.Sometimes, the fingerprints contain attributes that are not matched or mismatched. These attributes are called indeterminate attributes. When there are indeterminate attributes present, the following formula is used to calculate the risk score:Risk Score = (total weight of mismatched attributes / (total weight of all attributes−total weight of indeterminate attributes)) × 100ScenariosThe following example scenarios demonstrate risk score calculation. All three of the scenarios assume that the administratorWrote a policy that specifies that any risk score at or below 40 is permitted, and any risk score above 40 is denied.Gave equal weight values to all of the attributes in the tables.The attributes in the tables have the same weight value of 10.Scenario 1: Authentication permittedThe total weight of the unequal device fingerprint values that belongs to one attribute is not significant enough to prohibit authentication.The example information in the table is used to calculate the risk score.Attribute names Weight valuesIncoming device fingerprint valuesRegistered device fingerprint valuescolorDepth103232deviceLanguage10en-USen-USdevicePlatform10Win32Win32http:userAgent10Mozilla/5.0 (Windows NT 6.1; WOW64; rv:15.0) Gecko/20120427 Firefox/15.0a1Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1468.0 Safari/537.36ipAddress1042.29.144.542.29.144.5screenHeight1010801080screenWidth1019201920All of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for http:userAgent.Because http:userAgent is the only attribute that has any mismatched values, the total weight of the mismatched attributes is 10.The total weight of all of the attributes is 70 because each attribute has a weight value of 10.According to the risk score calculation formula: (10/70)×100=14. Therefore, the risk score is 14.Because the risk score is below 40, authentication is permitted.Scenario 2: Authentication denied with multiple significant attributesThe total weight of the unequal device fingerprint values that belongs to 6 out of 7 of the attributes is significant enough to prohibit authentication.The example information in the table is used to calculate the risk score.Attribute names Weight valuesIncoming device fingerprint valuesRegistered device fingerprint valuescolorDepth102432deviceLanguage10en-USen-USdevicePlatform10LinuxWin32http:userAgent10Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.93 Safari/537.36Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1468.0 Safari/537.36ipAddress109.53.18.16442.29.144.5screenHeight1010501080screenWidth1016801920None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for deviceLanguage.Because all of the attributes except for deviceLanguage have mismatched values, the collective weight of the mismatched attributes is 60.The total weight of all of the attributes is 70 because each attribute has a weight value of 10.According to the risk score calculation formula: (60/70)×100=86. Therefore, the risk score is 86.Because the risk score is above 40, authentication is denied.Scenario 3: Authentication denied with one significant attribute The total weight of the unequal device fingerprint values that belongs to one attribute is significant enough to prohibit authentication.The example information in the table is used to calculate the risk score.Attribute names Weight valuesIncoming device fingerprint valuesRegistered device fingerprint valuesdevicePlatform5AndroidAndroidgeoLocation8551.499444, -0.1275, 1030.283611, -97.7325, 10screenHeight5800800screenWidth5480480In addition to the previous assumptions, this scenario prohibits any distance greater than 40 kilometers.All of the device fingerprint values match except for the incoming device fingerprint value and the existing device fingerprint value for the geoLocation attribute. The geoLocation attribute contains the values that the risk engine uses to calculate the distance between the incoming device fingerprint and the registered device fingerprint. In this instance, the distance between the two device fingerprints is 7909 kilometers.Because the geoLocation attribute is the only attribute with mismatched values, the weight of the mismatched attributes is 85.The total weight of all of the attributes is 100 because the geoLocation attribute has a weight value of 85. devicePlatform, screenHeight, and screenWidth each have weight values of 5.According to the risk score calculation formula: (85/100)×100=85. Therefore, the risk score is 85.Because the risk score is above 40, authentication is denied. Authentication can be denied if the incoming fingerprint value and registered device fingerprint value for just one attribute indicate a large enough discrepancy. In this scenario, the distance between the incoming device fingerprint value and the registered device fingerprint value is too large for authentication to be permitted.Risk management overviewContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.

Risk score calculation

Risk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.

Overview

The risk engine determines a risk score by comparing sets of attributes that identify devices. These sets of attributes are called device fingerprints. Device fingerprint attributes include items such as IP address, location, and screen size. Each registered device has one device fingerprint. Because the user accesses the resource in different locations and on different devices, the user can have many registered devices.

The following process describes how risk assessment works:

The incoming device requests access to the resource.

The risk engine collects as many device fingerprint attributes as it can from the request device.

After the attributes are collected, the risk engine:

Determines the device fingerprint.

Calculates the risk score. The risk score

Is a number.

Represents the amount of risk that is associated with the incoming request.

Indicates the likelihood that the incoming request represents the user.

The risk engine:

Compares the incoming fingerprint with each registered device fingerprint.

Uses the attributes that are contained in the larger fingerprint for each comparison.

Calculates a risk score for each comparison.

To determine the final risk score, the risk engine:

Chooses the lowest risk score of the comparisons between the incoming fingerprint and the registered fingerprint.

Measures the final risk score against a threshold score or range that the administrator sets in a policy.

Depending on the way the administrator writes the policy, one of the following outcomes occurs:

Permit

The risk score for the incoming request is well below the threshold score. The user is granted access to the resource. For example, the risk score is 30, and the threshold score that is set by the administrator is 40.

Permit with obligation or authentication

The user is asked to complete an extra security measure, such as step up authentication. For example, the risk score is 40, and the policy that the administrator wrote requires users that operate devices with scores 30 - 90 to step up.

Deny

The risk score for the incoming request is above the threshold score or range. The user is denied access to the resource. For example, the risk score is 50, and the threshold score that is set by the administrator is 40.

The risk score is calculated through the following formula:

Risk Score = (total weight of mismatched attributes /
total weight of all attributes) × 100

When the values that belong to the incoming device fingerprint and the registered device fingerprint are the same, the values are matched. When the values that belong to the incoming device fingerprint and the registered device fingerprint are not the same, the values are mismatched.

Sometimes, the fingerprints contain attributes that are not matched or mismatched. These attributes are called indeterminate attributes. When there are indeterminate attributes present, the following formula is used to calculate the risk score:

Risk Score = (total weight of mismatched attributes /
(total weight of all attributes−total weight of indeterminate attributes)) × 100

Scenarios

The following example scenarios demonstrate risk score calculation.

All three of the scenarios assume that the administrator

Wrote a policy that specifies that any risk score at or below 40 is permitted, and any risk score above 40 is denied.

Gave equal weight values to all of the attributes in the tables.

The attributes in the tables have the same weight value of 10.

Scenario 1: Authentication permitted

The total weight of the unequal device fingerprint values that belongs to one attribute is not significant enough to prohibit authentication.

The example information in the table is used to calculate the risk score.

Attribute names | Weight values | Incoming device fingerprint values | Registered device fingerprint values
colorDepth | 10 | 32 | 32
deviceLanguage | 10 | en-US | en-US
devicePlatform | 10 | Win32 | Win32
http:userAgent | 10 | Mozilla/5.0 (Windows NT 6.1; WOW64; rv:15.0) Gecko/20120427 Firefox/15.0a1 | Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1468.0 Safari/537.36
ipAddress | 10 | 42.29.144.5 | 42.29.144.5
screenHeight | 10 | 1080 | 1080
screenWidth | 10 | 1920 | 1920

All of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for http:userAgent.

Because http:userAgent is the only attribute that has any mismatched values, the total weight of the mismatched attributes is 10.

The total weight of all of the attributes is 70 because each attribute has a weight value of 10.

According to the risk score calculation formula: (10/70)×100=14. Therefore, the risk score is 14.

Because the risk score is below 40, authentication is permitted.

Scenario 2: Authentication denied with multiple significant attributes

The total weight of the unequal device fingerprint values that belongs to 6 out of 7 of the attributes is significant enough to prohibit authentication.

The example information in the table is used to calculate the risk score.

Attribute names | Weight values | Incoming device fingerprint values | Registered device fingerprint values
colorDepth | 10 | 24 | 32
deviceLanguage | 10 | en-US | en-US
devicePlatform | 10 | Linux | Win32
http:userAgent | 10 | Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.93 Safari/537.36 | Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1468.0 Safari/537.36
ipAddress | 10 | 9.53.18.164 | 42.29.144.5
screenHeight | 10 | 1050 | 1080
screenWidth | 10 | 1680 | 1920

None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for deviceLanguage.

Because all of the attributes except for deviceLanguage have mismatched values, the collective weight of the mismatched attributes is 60.

The total weight of all of the attributes is 70 because each attribute has a weight value of 10.

According to the risk score calculation formula: (60/70)×100=86. Therefore, the risk score is 86.

Because the risk score is above 40, authentication is denied.

Scenario 3: Authentication denied with one significant attribute

The total weight of the unequal device fingerprint values that belongs to one attribute is significant enough to prohibit authentication.

The example information in the table is used to calculate the risk score.

Attribute names | Weight values | Incoming device fingerprint values | Registered device fingerprint values
devicePlatform | 5 | Android | Android
geoLocation | 85 | 51.499444, -0.1275, 10 | 30.283611, -97.7325, 10
screenHeight | 5 | 800 | 800
screenWidth | 5 | 480 | 480

In addition to the previous assumptions, this scenario prohibits any distance greater than 40 kilometers.

All of the device fingerprint values match except for the incoming device fingerprint value and the existing device fingerprint value for the geoLocation attribute. The geoLocation attribute contains the values that the risk engine uses to calculate the distance between the incoming device fingerprint and the registered device fingerprint. In this instance, the distance between the two device fingerprints is 7909 kilometers.

Because the geoLocation attribute is the only attribute with mismatched values, the weight of the mismatched attributes is 85.

The total weight of all of the attributes is 100 because the geoLocation attribute has a weight value of 85. devicePlatform, screenHeight, and screenWidth each have weight values of 5.

According to the risk score calculation formula: (85/100)×100=85. Therefore, the risk score is 85.

Because the risk score is above 40, authentication is denied.

Note: Authentication can be denied if the incoming fingerprint value and registered device fingerprint value for just one attribute indicate a large enough discrepancy. In this scenario, the distance between the incoming device fingerprint value and the registered device fingerprint value is too large for authentication to be permitted.

Parent topic: Risk management overview

Risk reportsRisk reportsRisk reportsRisk reports illustrate the comparison between the incoming device fingerprint and the registered device fingerprint for each risk score calculation. risk reportsEach risk report contains the incoming device fingerprint that attempts to access a protected resource as compared to the registered device fingerprint. Analysis of each risk report provides the following information about the corresponding risk score calculation:Outcome of the risk score calculation. Matcher that the risk engine used for the comparison between the device fingerprints.Attributes that were compared between the incoming fingerprint and the registered fingerprint.Other calculations that were made during the risk score determination. The administrator can use risk reports to complete the following objectives: Write more effective risk profiles.Monitor system activity.Risk score calculationRisk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.Accessing risk reportsThe administrator can access the risk reports that are generated during risk score calculation scenarios.Risk management overviewContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.

Risk reports

Risk reports illustrate the comparison between the incoming device fingerprint and the registered device fingerprint for each risk score calculation.

Each risk report contains the incoming device fingerprint that attempts to access a protected resource as compared to the registered device fingerprint. Analysis of each risk report provides the following information about the corresponding risk score calculation:

Outcome of the risk score calculation.

Matcher that the risk engine used for the comparison between the device fingerprints.

Attributes that were compared between the incoming fingerprint and the registered fingerprint.

Other calculations that were made during the risk score determination.

The administrator can use risk reports to complete the following objectives:

Write more effective risk profiles.

Monitor system activity.

Parent topic: Risk management overview

Related concepts:

Risk score calculation

Related tasks:

Accessing risk reports

Configuring risk reportsConfiguring risk reportsConfiguring risk reportsThe risk engine generates risk reports to analyze risk score calculation scenarios. The administrator can configure the riskEngine.reportsEnabled property and the riskEngine.reportsMaxStored property to enable the risk engine to store a specified number of these reports.risk reportsconfiguringThe following properties are necessary for the generation of risk reports: riskEngine.reportsEnabledEnables the risk engine to produce risk reports after the risk engine generates the risk score for each incoming request.The riskEngine.reportsEnabled property defaults to disabled, so the administrator must configure riskEngine.reportsEnabled to enable risk reporting. riskEngine.reportsMaxStoredEnables the risk engine to store a maximum number of risk reports as specified by the administrator. The administrator can set the riskEngine.reportsMaxStored property. However, the property defaults to five reports. The risk engine deletes the oldest report when it produces a report that exceeds the maximum number of reports that it is specified to store.To configure the riskEngine.reportsEnabled property, complete the following steps. Log in to the local management interface.Click Secure Access ControlGlobal SettingsAdvanced Configuration.Configure the riskEngine.reportsEnabled propertyUnder Key, find riskEngine.reportsEnabled.Click the edit button.Complete one of the following actions: Enable risk reporting Select the Enabled box.Click Save. Enabling risk reporting sets the riskEngine.reportsEnabled property to true.Disable risk reportingClear the Enabled box.Click Save. Disabling risk reporting sets the riskEngine.reportsEnabled property to false.Configure the riskEngine.reportsMaxStored property Under Key, find riskEngine.reportsMaxStored. Click the edit button.Specify the number of reports for the risk engine to store.Click Save.Accessing risk reportsThe administrator can access the risk reports that are generated during risk score calculation scenarios.Risk management overviewContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.

Configuring risk reports

The risk engine generates risk reports to analyze risk score calculation scenarios. The administrator can configure the riskEngine.reportsEnabled property and the riskEngine.reportsMaxStored property to enable the risk engine to store a specified number of these reports.

About this task

The following properties are necessary for the generation of risk reports:

riskEngine.reportsEnabled

Enables the risk engine to produce risk reports after the risk engine generates the risk score for each incoming request.

The riskEngine.reportsEnabled property defaults to disabled, so the administrator must configure riskEngine.reportsEnabled to enable risk reporting.

riskEngine.reportsMaxStored

Enables the risk engine to store a maximum number of risk reports as specified by the administrator.

The administrator can set the riskEngine.reportsMaxStored property. However, the property defaults to five reports. The risk engine deletes the oldest report when it produces a report that exceeds the maximum number of reports that it is specified to store.

To configure the riskEngine.reportsEnabled property, complete the following steps.

Procedure

Log in to the local management interface.

Click Secure Access Control > Global Settings > Advanced Configuration.

Configure the riskEngine.reportsEnabled property

Under Key, find riskEngine.reportsEnabled.

Click the edit button.

Complete one of the following actions:

Enable risk reporting

Select the Enabled box.

Click Save.

Note: Enabling risk reporting sets the riskEngine.reportsEnabled property to true.

Disable risk reporting

Clear the Enabled box.

Click Save.

Note: Disabling risk reporting sets the riskEngine.reportsEnabled property to false.

Configure the riskEngine.reportsMaxStored property

Under Key, find riskEngine.reportsMaxStored.

Click the edit button.

Specify the number of reports for the risk engine to store.

Click Save.

Parent topic: Risk management overview

Related tasks:

Accessing risk reports

Accessing risk reportsAccessing risk reportsAccessing risk reportsThe administrator can access the risk reports that are generated during risk score calculation scenarios.risk reportsaccessing The administrator can access the risk reports specific to your business by completing the following steps: Log in to the local management interface.Click Monitor Analysis and Diagnostics.Click Application Log Files.Click the + next to the access_control folder.Click the + next to the risk_reports folder. The administrator can access the risk reports after the risk engine generates the first report and the risk_reports folder is created.Find the necessary report, and click View.Risk reportsRisk reports illustrate the comparison between the incoming device fingerprint and the registered device fingerprint for each risk score calculation. Configuring risk reportsThe risk engine generates risk reports to analyze risk score calculation scenarios. The administrator can configure the riskEngine.reportsEnabled property and the riskEngine.reportsMaxStored property to enable the risk engine to store a specified number of these reports.Risk management overviewContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user.

Accessing risk reports

The administrator can access the risk reports that are generated during risk score calculation scenarios.

About this task

The administrator can access the risk reports specific to your business by completing the following steps:

Procedure

Log in to the local management interface.

Click Monitor Analysis and Diagnostics.

Click Application Log Files.

Click the + next to the access_control folder.

Click the + next to the risk_reports folder. The administrator can access the risk reports after the risk engine generates the first report and the risk_reports folder is created.

Find the necessary report, and click View.

Parent topic: Risk management overview

Related concepts:

Risk reports

Related tasks:

Configuring risk reports

AttributesAttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.attributescategoryRequests contain one or more of the following categories of attributes:ActionIndicates the user action.EnvironmentIndicates when and how the user is trying to access the resource.ResourceGives information about what the user is trying to access.SubjectIndicates who is trying to access the resource.When you author policies or risk profiles, you select attributes that you want to be evaluated. Commonly used attributes are predefined. You can also create your own to meet the needs of your environment.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.Updating location attributesTo define policy that is based on geolocation, you must update the geolocation database with appropriate location and IP data.Attribute propertiesWhen you add or modify an attribute, you specify properties that make that attribute unique.Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.Configuring the hash algorithm for attribute storageHashing encodes a character string as a fixed-length bit string for comparison. Context-based access hashes certain attributes by default. You can change the hash algorithm and specify additional attributes that you want to hash.Dynamic attributesYou can capture additional context-based access information in dynamic attributes that you create or customize.Custom attributes for the authorization serviceYou can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS).

Attributes

Attributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.

Requests contain one or more of the following categories of attributes:

Action

Indicates the user action.

Environment

Indicates when and how the user is trying to access the resource.

Resource

Gives information about what the user is trying to access.

Subject

Indicates who is trying to access the resource.

When you author policies or risk profiles, you select attributes that you want to be evaluated. Commonly used attributes are predefined. You can also create your own to meet the needs of your environment.

Managing attributes
Attributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.

Updating location attributes
To define policy that is based on geolocation, you must update the geolocation database with appropriate location and IP data.

Attribute properties
When you add or modify an attribute, you specify properties that make that attribute unique.

Predefined attributes
An appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

Configuring the hash algorithm for attribute storage
Hashing encodes a character string as a fixed-length bit string for comparison. Context-based access hashes certain attributes by default. You can change the hash algorithm and specify additional attributes that you want to hash.

Dynamic attributes
You can capture additional context-based access information in dynamic attributes that you create or customize.

Custom attributes for the authorization service
You can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS).

Parent topic: Advanced Access Control administration

Managing attributesManaging attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.attributesmanagingLog in to the local management interface.Click Secure Access Control.Under Policy, click Attributes.Perform one or more of the following actions:View and filter attributesTake any of the following actions to filter your view: Select the DetailsDetails View to view attribute name, category, and data type. Select the ListList View to view only the name of the attribute.Type a term, such as an attribute name, category, or data type in the Filter field to list attributes that use that term. The filter searches all attribute properties fields, including descriptions, for the alphanumeric characters you type in the Filter field. For example, if you type header in the Filter field, all attributes that contain header in their properties are shown in the attributes list.Click x to clear the Filter field.Sort the attribute list by column with the up or down arrow on each column. For example, you can view the list of attributes that are sorted by the Data type column in ascending order by clicking the up arrow.Add an attributeClick Add attribute.Complete the properties for the attribute.The attribute name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ;  " ' < > ? , [  ] { } / anywhere in the name.Click Save.Modify an attributeEnsure that the modification does not affect a current policy or configuration. If you modify an attribute that is in-use, the policy or configuration that uses the attribute might stop working.Click Modify attribute.Complete the properties for the attribute. The attribute name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ;  " ' < > ? , [  ] { } / anywhere in the name.Click Save.Delete an attributeSelect an attribute or press and hold the Ctrl key and select multiple attributes to remove.Click Delete attribute. Confirm the deletion. Click OK to continue or click Cancel. The attribute is removed.When you add, modify or delete an attribute, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.

Managing attributes

Attributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Attributes.

Perform one or more of the following actions:

View and filter attributes

Take any of the following actions to filter your view:

Select the DetailsDetails View to view attribute name, category, and data type.

Select the ListList View to view only the name of the attribute.

Type a term, such as an attribute name, category, or data type in the Filter field to list attributes that use that term.

Note: The filter searches all attribute properties fields, including descriptions, for the alphanumeric characters you type in the Filter field. For example, if you type header in the Filter field, all attributes that contain header in their properties are shown in the attributes list.

Click x to clear the Filter field.

Sort the attribute list by column with the up or down arrow on each column. For example, you can view the list of attributes that are sorted by the Data type column in ascending order by clicking the up arrow.

Add an attribute

Click Add attribute.

Complete the properties for the attribute.

Note: The attribute name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ;  " ' < > ? , [  ] { } / anywhere in the name.

Click Save.

Modify an attribute

Attention: Ensure that the modification does not affect a current policy or configuration. If you modify an attribute that is in-use, the policy or configuration that uses the attribute might stop working.

Click Modify attribute.

Complete the properties for the attribute.

Note: The attribute name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ;  " ' < > ? , [  ] { } / anywhere in the name.

Click Save.

Delete an attribute

Select an attribute or press and hold the Ctrl key and select multiple attributes to remove.

Click Delete attribute. Confirm the deletion. Click OK to continue or click Cancel.

The attribute is removed.

When you add, modify or delete an attribute, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.

For more information, see Deploying pending changes.

Parent topic: Attributes

Related reference:

Predefined attributes

Updating location attributesUpdating location attributesTo define policy that is based on geolocation, you must update the geolocation database with appropriate location and IP data.geolocation dataupdatingattributesupdating geolocation When a request is received, a GeoLocator policy information point (PIP) determines the location of the device that made the request. The device IP address as determined by the point of contact server is the input to the PIP. The PIP reads the geolocation database to determine the device location. All location attributes stored in the database are shown as environment attributes that you can use to author policies.Location attributes include:CountryState or regionCitySample data is included in the geolocation database. However, this sample data cannot be used in a production environment. Use the sample files for IPv4, IPv6, or both to create your own file. To locate the files, log in to the local management interface and click Manage System SettingsSecure SettingsFile Downloads. Then expand access_controlcbageolocation.Obtain or create an appropriate geolocation data file in ZIP format.The file or files you must use depend on whether you want support for IPv4 addresses, IPv6 addresses, or both.For IPv4: The file must contain two CSV files. One file contains all of the possible locations and the other contains the IP blocks and their corresponding locations.Locations fileEach line in the locations file corresponds to one location and is in the following format:location id,country,region,city,,,,,Note the 5 commas after city. You must include these commas in your locations file.location idA unique integer value that identifies the location.countryA two-letter country code. For assistance with locating a country code, see geoCountryCode in Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes..regionA two-character region code. For assistance with locating a region code, see geoRegionCode in Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes..cityThe name of a city.The locations file must have Location in its file name. The sample provided is named: GeoLiteCity-Location.csvIP blocks fileEach line in the IP blocks file corresponds to one IP block and is in the following format:startip,endip,location idstartipThe first IP address in the block that is represented as an integer.endipThe last IP address in the block that is represented as an integer.location idThe integer that is defined in the locations file that corresponds with the IP block.The IP blocks file must have Blocks in its name. The sample provided is named: GeoLiteCity-Blocks.csvEnsure that the CSV files contain all of the data that you want to load in the database. When you import the file, the existing data is removed and replaced with the data in the file.For IPv6: The file must contain one CSV file that contains all of the location and IP block information. Each line in the file corresponds to one location and IP block combination:startip string, endip string, startip int, endip int, country, region, city,,,,,Note the 5 commas after city. You must include these commas in your locations file.startip string The first IP address in the block that is represented as a hexadecimal string. For example, a IPv6 string might be 2001:200:ffff:ffff:ffff:ffff:ffff:ffffendip stringThe last IP address in the block that is represented as a hexadecimal string.startip integerThe first IP address in the block that is represented as an integer. For example, the IPv6 integer that corresponds to startip 2001:200:ffff:ffff:ffff:ffff:ffff:ffff might be 42540528806023212578155541913346768895.endip integerThe last IP address in the block that is represented as an integer.countryA two-letter country code. For assistance with locating a country code, see geoCountryCode in Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes..regionA two-character region code. For assistance with locating a region code, see geoRegionCode in Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes..cityThe name of a city.The file must have v6 in its file name. The sample provided is named: GeoLiteCityv6.csvCreate a file in ZIP format that contains the files you want to upload.For example, if you want to use both IPv4 and IPv6, include all the CSV files that you created in one ZIP formatted file.Log in to the local management interface.Click Manage System Settings.Under Updates and Licensing, click Geolocation Database.Click Import.Select the geolocation file in ZIP format.Click Import.Importing the data can take more than 20 minutes to complete.Click Refresh Status to check the import process.When the process is complete, the status says Loaded.AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.

Updating location attributes

To define policy that is based on geolocation, you must update the geolocation database with appropriate location and IP data.

About this task

When a request is received, a GeoLocator policy information point (PIP) determines the location of the device that made the request. The device IP address as determined by the point of contact server is the input to the PIP. The PIP reads the geolocation database to determine the device location.

All location attributes stored in the database are shown as environment attributes that you can use to author policies.

Location attributes include:

Country

State or region

City

Attention: Sample data is included in the geolocation database. However, this sample data cannot be used in a production environment. Use the sample files for IPv4, IPv6, or both to create your own file. To locate the files, log in to the local management interface and click Manage System Settings > Secure Settings > File Downloads. Then expand access_control > cba > geolocation.

Procedure

Obtain or create an appropriate geolocation data file in ZIP format. The file or files you must use depend on whether you want support for IPv4 addresses, IPv6 addresses, or both.

For IPv4: The file must contain two CSV files. One file contains all of the possible locations and the other contains the IP blocks and their corresponding locations.

Locations file

Each line in the locations file corresponds to one location and is in the following format:

location id,country,region,city,,,,,

Attention: Note the 5 commas after city. You must include these commas in your locations file.

location id

A unique integer value that identifies the location.

country

A two-letter country code. For assistance with locating a country code, see geoCountryCode in Predefined attributes.

region

A two-character region code. For assistance with locating a region code, see geoRegionCode in Predefined attributes.

city

The name of a city.

The locations file must have Location in its file name. The sample provided is named: GeoLiteCity-Location.csv

IP blocks file

Each line in the IP blocks file corresponds to one IP block and is in the following format:

startip,endip,location id

startip

The first IP address in the block that is represented as an integer.

endip

The last IP address in the block that is represented as an integer.

location id

The integer that is defined in the locations file that corresponds with the IP block.

The IP blocks file must have Blocks in its name. The sample provided is named: GeoLiteCity-Blocks.csv

Attention: Ensure that the CSV files contain all of the data that you want to load in the database. When you import the file, the existing data is removed and replaced with the data in the file.

For IPv6: The file must contain one CSV file that contains all of the location and IP block information.

Each line in the file corresponds to one location and IP block combination:

startip string, endip string, startip int, endip int, country,
  region, city,,,,,

Attention: Note the 5 commas after city. You must include these commas in your locations file.

startip string

The first IP address in the block that is represented as a hexadecimal string. For example, a IPv6 string might be 2001:200:ffff:ffff:ffff:ffff:ffff:ffff

endip string

The last IP address in the block that is represented as a hexadecimal string.

startip integer

The first IP address in the block that is represented as an integer. For example, the IPv6 integer that corresponds to startip 2001:200:ffff:ffff:ffff:ffff:ffff:ffff might be 42540528806023212578155541913346768895.

endip integer

The last IP address in the block that is represented as an integer.

country

A two-letter country code. For assistance with locating a country code, see geoCountryCode in Predefined attributes.

region

A two-character region code. For assistance with locating a region code, see geoRegionCode in Predefined attributes.

city

The name of a city.

The file must have v6 in its file name. The sample provided is named: GeoLiteCityv6.csv

Create a file in ZIP format that contains the files you want to upload. For example, if you want to use both IPv4 and IPv6, include all the CSV files that you created in one ZIP formatted file.

Log in to the local management interface.

Click Manage System Settings.

Under Updates and Licensing, click Geolocation Database.

Click Import.

Select the geolocation file in ZIP format.

Click Import.

Note: Importing the data can take more than 20 minutes to complete.

Click Refresh Status to check the import process. When the process is complete, the status says Loaded.

Parent topic: Attributes

Attribute propertiesAttribute propertiesWhen you add or modify an attribute, you specify properties that make that attribute unique.Adding attributesSpecify the following properties when you add an attribute:NameA unique name for the attribute.DescriptionA description of the attribute.IdentifierThe internal name of the attribute that is used in the generated XACML policy.IssuerThe identifier of the policy information point from which the value of the attribute is retrieved. If an attribute can be returned from multiple policy information points, the issuer property specifies which policy information point to use. Use this field only if you are using a policy information point. Otherwise, leave this field blank.TypeIndicates whether the attribute is used for policies or risk profiles or both. If neither check box is selected, the attribute is not available for policies or risk profiles.CategoryThe part of the XACML request that the attribute value comes from.Data typeThe type of values that the attribute can handle. In a policy rule with an attribute, the data type indicates how the attribute can be compared to a value. In a risk profile, the risk matchers compare attribute values that have the same data type.MatcherAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user.Storage DomainThe storage domain indicates whether the attribute is stored as a device, session, or behavior attribute. Device fingerprint dataConsists of attributes that are stored when a device is registered. The incoming device fingerprint is compared against this stored repository of trusted device fingerprints.Session dataConsists of the session attributes of the user that are stored temporarily until the session times out. However, if the device is registered, the session attributes are also stored as part of the device fingerprint. If session is selected, the attribute is collected in the user’s session.Behavior dataIs historic data that is stored in the database and used for behavior-based attribute matching. For example, the login timestamps of the user over the previous three months. If an attribute is included in a risk profile configuration and the storage domain is not specified, the default storage domain is device.Modifying attributesAll the properties for an attribute are displayed. However, you can modify only some of attribute properties. Also, if an attribute is included in a policy, you cannot make further updates to the attribute.You can modify the following properties:Editable properties of predefined attributesStorage DomainThe storage domain indicates whether the attribute is stored as a device, session, or behavior attribute. If session is selected, the attribute is collected in the user’s session. If an attribute is included in a risk profile configuration and the storage domain is not specified, the default storage domain is device.Editable properties of custom attributesNameA unique name for the attribute.DescriptionA description of the attribute.IdentifierThe internal name of the attribute that is used in the generated XACML policy.IssuerThe identifier of the policy information point from which the value of the attribute is retrieved. If an attribute can be returned from multiple policy information points, the issuer property specifies which policy information point to use. Use this field only if you are using a policy information point. Otherwise, leave this field blank.TypeIndicates whether the attribute is used for policies or risk profiles or both. If neither check box is selected, the attribute is not available for policies or risk profiles.CategoryThe part of the XACML request that the attribute value comes from.Data typeThe type of values that the attribute can handle. In a policy rule with an attribute, the data type indicates how the attribute can be compared to a value. In a risk profile, the risk matchers compare attribute values that have the same data type.MatcherAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user.Storage DomainThe storage domain indicates whether the attribute is stored as a device, session, or behavior attribute. If session is selected, the attribute is collected in the user’s session. If an attribute is included in a risk profile configuration and the storage domain is not specified, the default storage domain is device.Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.

Attribute properties

When you add or modify an attribute, you specify properties that make that attribute unique.

Adding attributes

Specify the following properties when you add an attribute:

Name

A unique name for the attribute.

Description

A description of the attribute.

Identifier

The internal name of the attribute that is used in the generated XACML policy.

Issuer

The identifier of the policy information point from which the value of the attribute is retrieved. If an attribute can be returned from multiple policy information points, the issuer property specifies which policy information point to use.

Note: Use this field only if you are using a policy information point. Otherwise, leave this field blank.

Type

Indicates whether the attribute is used for policies or risk profiles or both. If neither check box is selected, the attribute is not available for policies or risk profiles.

Category

The part of the XACML request that the attribute value comes from.

Data type

The type of values that the attribute can handle. In a policy rule with an attribute, the data type indicates how the attribute can be compared to a value. In a risk profile, the risk matchers compare attribute values that have the same data type.

Matcher

An attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user.

Storage Domain

The storage domain indicates whether the attribute is stored as a device, session, or behavior attribute.

Device fingerprint data

Consists of attributes that are stored when a device is registered. The incoming device fingerprint is compared against this stored repository of trusted device fingerprints.

Session data

Consists of the session attributes of the user that are stored temporarily until the session times out. However, if the device is registered, the session attributes are also stored as part of the device fingerprint. If session is selected, the attribute is collected in the user’s session.

Behavior data

Is historic data that is stored in the database and used for behavior-based attribute matching. For example, the login timestamps of the user over the previous three months. If an attribute is included in a risk profile configuration and the storage domain is not specified, the default storage domain is device.

Modifying attributes

All the properties for an attribute are displayed. However, you can modify only some of attribute properties. Also, if an attribute is included in a policy, you cannot make further updates to the attribute.

You can modify the following properties:

Editable properties of predefined attributes

Storage Domain

The storage domain indicates whether the attribute is stored as a device, session, or behavior attribute. If session is selected, the attribute is collected in the user’s session. If an attribute is included in a risk profile configuration and the storage domain is not specified, the default storage domain is device.

Editable properties of custom attributes

Name

A unique name for the attribute.

Description

A description of the attribute.

Identifier

The internal name of the attribute that is used in the generated XACML policy.

Issuer

The identifier of the policy information point from which the value of the attribute is retrieved. If an attribute can be returned from multiple policy information points, the issuer property specifies which policy information point to use.

Note: Use this field only if you are using a policy information point. Otherwise, leave this field blank.

Type

Indicates whether the attribute is used for policies or risk profiles or both. If neither check box is selected, the attribute is not available for policies or risk profiles.

Category

The part of the XACML request that the attribute value comes from.

Data type

The type of values that the attribute can handle. In a policy rule with an attribute, the data type indicates how the attribute can be compared to a value. In a risk profile, the risk matchers compare attribute values that have the same data type.

Matcher

An attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user.

Storage Domain

The storage domain indicates whether the attribute is stored as a device, session, or behavior attribute. If session is selected, the attribute is collected in the user’s session. If an attribute is included in a risk profile configuration and the storage domain is not specified, the default storage domain is device.

Parent topic: Attributes

Related tasks:

Managing attributes

Predefined attributesPredefined attributesPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.predefined attributes referencepredefined attributes referencepoliciesrisk profilesrisk-based accesspredefined attributes referencerisk profilespoliciespredefined attributes referencerisk profilespredefined attributes reference Five values describe each predefined attribute: CategoryCategories indicate the type of information that each attribute conveys. Type Data typeEach predefined attribute has a data type. Data types are classifications that identify the possible values for each type of attribute. Source typeSource types indicate the source of each attribute. SourceSources indicate where the attributes originate from. Predefined attribute categoriesCategories indicate the type of information that each attribute conveys.CategoryCategory descriptionActionIndicates the user action.EnvironmentIndicates when and how the user is trying to access the resource.ResourceGives information about what the user is trying to access.SubjectIndicates who is trying to access the resource. Predefined attribute typesTypeType descriptionAccess policyThe administrator uses policy attributes to create policies.Risk profileThe administrator uses risk attributes to create risk profiles. Predefined attribute data typesEach predefined attribute has a data type. Data types are classifications that identify the possible values for each type of attribute.Data typeData type descriptionBooleanCondition that refers to two possible values: TrueFalseDateDate of the request.IntegerNumber that can be written without a fractional or decimal component.StringSequence of characters.TimeTime of the request.X500NameValues with distinguished names. Predefined attribute source typesSource types indicate the source of each attribute. Source typeSource type descriptionActiveCollected by the attribute collection service. The administrator must add JavaScript to the application so that active attributes can be collected. For example: system fonts. DerivedGenerated by a policy information point (PIP). For example: risk score.PassiveCollected from the browser by the external authorization service (EAS) and placed into an XACML request. Attributes with this source type are collected by the policy enforcement point (PEP) without installing more software or challenging the client to provide more details. For example: user-agent HTTP header and client IP address. Predefined attribute sourcesSources indicate where the attributes originate from. SourceSource descriptionAttribute collection serviceCollects information about the user device such as browser information, the operating system of the device, and the language of the device.Consent external authentication interfaceAsks the user for a device registration decision.Device fingerprint count PIPCounts the number of devices that are associated with the user.Fiberlink MaaS360 PIPRetrieves device attributes from the registered MaaS360 device inventory.Geolocation PIPLooks up the location of the user that is based on the IP address.HTTP headersProvides information about the request.IP reputation PIPGenerates the IP reputation. See IP reputationThe IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control. for more information about IP reputation. POST dataCollects information about the user and sends it to the external authorization service (EAS) as POST data. The EAS inserts this POST data into the decision request.Risk engineGenerates the risk score. See Risk score calculationRisk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison. for more information about risk score calculation.System timeKeeps the time of the system.Security Access Manager credentialCollects information about the user from Security Access Manager.Worklight JavaScript PIPParses the POST data from a Worklight adapter invocation and returns custom attributes that are created from the data that is contained within the POST from the parameters element. AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.accessTimeThe accessTime attribute contains the record of the past login times that belongs to the user.actionThe action attribute indicates the action that is performed on the resourceauthenticationLevelThe authenticationLevel attribute is a numeric value that specifies the authentication level of a user. authenticationMechanismThe authenticationMechanism attribute indicates the location of the user registry that belongs to the requesting user. authenticationMechanismTypesThe authenticationMechanismTypes attribute indicates the types of authentication mechanisms that the user completes during the current authenticated session. authenticationMethodThe authenticationMethod attribute indicates the method of authentication that is used, such as password.authenticationTypesThe authenticationTypes attribute indicates the types of authentication policies that the user completes during the current authenticated session. browserPluginsThe browserPlugins attribute indicates all of the installed plug-ins in the browser in a comma-separated list. colorDepthThe colorDepth attribute indicates the bit depth of the color palette of the device. currentDateThe currentDate attribute indicates the date of the request. currentTimeThe currentTime attribute indicates the time of the request.deviceFontsThe deviceFonts attribute indicates all of the installed fonts on the device in a comma-separated list.deviceLanguageThe deviceLanguage attribute indicates the language of the device. deviceNameThe deviceName attribute indicates the name of the device.devicePlatformThe devicePlatform attribute indicates the operating system of the device. fiberlink.maas360.device.compliance.stateThe fiberlink.maas360.device.compliance.state attribute indicates the Fiberlink MaaS360 ownership of the registered device.fiberlink.maas360.device.idsThe fiberlink.maas360.device.ids attribute indicates the Fiberlink MaaS360 registered device IDs.fiberlink.maas360.device.ownershipThe fiberlink.maas360.device.ownership attribute indicates a Fiberlink MaaS360 ownership of the registered device.fiberlink.maas360.device.jailbrokenThe fiberlink.maas360.device.jailbroken attribute indicates the Fiberlink MaaS360 jailbroken state of the registered device.fiberlink.maas360.device.last.reportedThe fiberlink.maas360.device.last.reported attribute indicates the Fiberlink MaaS360 last reported date and time of the device to the server.fiberlink.maas360.device.managed.statusThe fiberlink.maas360.device.managed.status attribute indicates the Fiberlink MaaS360 managed status of the registered device.fiberlink.maas360.device.match.foundThe fiberlink.maas360.device.match.found attribute indicates a Fiberlink MaaS360 match against the attribute collection service to a registered device.geoCityThe geoCity attribute indicates the city in which the device is located. geoCountryCodeThe geoCountryCode attribute indicates the country in which the device is located. geoLocationThe geoLocation attribute indicates the latitude, longitude, and accuracy of the requesting device that is obtained with the W3C geolocation standard. geoRegionCodeThe geoRegionCode attribute indicates the state or province in which the device is located.groupsThe groups attribute lists the groups of which the user is a member.groupsDNThe groupsDN attribute lists the groups of which the user is a member.http:acceptThe http:accept attribute indicates the acceptable content types.http:acceptEncodingThe http:acceptEncoding attribute indicates the acceptable encoding types. http:acceptLanguageThe http:acceptLanguage attribute indicates the acceptable human languages for response. http:hostThe http:host attribute indicates the host that is requested. http:uriThe http:uri attribute indicates the requested resource and the query string.http:userAgentThe http:userAgent attribute indicates the user agent. ipAddressThe ipAddress attribute indicates the string representation of the IP address.ipReputationThe ipReputation attribute lists any combination of certain classifications whose IP reputation score is at or above the threshold.oauthScopeResourceThe oauthScopeResource attribute indicates authorization of an API call for OAuth. This value originates when the OAuth grant is created.oauthScopeSubjectThe oauthScopeSubject attribute indicates the identity for the session for OAuth. This value originates when the OAuth grant is created.qopThe qop attribute indicates the quality of protection information.registeredDeviceCountThe registeredDeviceCount attribute indicates the number of devices that the user registers.resourceThe resource attribute indicates the Worklight adapter parameters URL encoded JSON array POST data.riskScoreThe riskScore attribute indicates the calculated risk score, which is a number 0 - 100. schemeThe scheme attribute indicates the protocol that is used to access the resource. screenAvailableHeightThe screenAvailableHeight attribute indicates the height of the screen of the requesting device without the toolbar.screenAvailableWidthThe screenAvailableWidth attribute indicates the width of the screen of the requesting device without the toolbar.screenHeightThe screenHeight attribute indicates the height of the screen of the requesting device. screenWidthThe screenWidth attribute indicates the width of the screen of the requesting device. userConsentThe userConsent attribute indicates the registration decision of the user. userDNThe userDN attribute indicates the distinguished name for the user in a registry. usernameThe username attribute identifies the user.worklight.adapter.adapterThe worklight.adapter.adapter attribute indicates the Worklight adapter adapter POST data.worklight.adapter.balance.accountThe worklight.adapter.balance.account attribute indicates the Worklight adapter BankingApprovals getBalance account.worklight.adapter.parametersThe worklight.adapter.parameters attribute indicates the Worklight adapter parameters URL encoded JSON array POST data.worklight.adapter.procedureThe worklight.adapter.procedure attribute indicates the Worklight adapter procedure POST data.worklight.adapter.transfer.account.fromThe worklight.adapter.transfer.account.from attribute indicates the Worklight adapter BankingApprovals doTransfer from account. worklight.adapter.transfer.account.toThe worklight.adapter.transfer.account.to attribute indicates the Worklight adapter BankingApprovals doTransfer to account.worklight.adapter.transfer.amountThe worklight.adapter.transfer.amount attribute indicates the Worklight adapter BankingApprovals doTransfer amount.worklight.device.idThe worklight.device.id attribute indicates the unique ID of the device that is assigned by Worklight.worklight.version.appThe worklight.version.app attribute indicates the version of the Worklight application.worklight.version.nativeThe worklight.version.native attribute indicates the version of the Worklight application.worklight.version.platformThe worklight.version.platform attribute indicates the version of the Worklight Software Development Kit for the Advanced Access Control.

Predefined attributes

An appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

Five values describe each predefined attribute:

Category

Type

Data type

Source type

Source

Table 194. Predefined attribute categories. Categories indicate the type of information that each attribute conveys.

Category | Category description
Action | Indicates the user action.
Environment | Indicates when and how the user is trying to access the resource.
Resource | Gives information about what the user is trying to access.
Subject | Indicates who is trying to access the resource.

Table 195. Predefined attribute types

Type | Type description
Access policy | The administrator uses policy attributes to create policies.
Risk profile | The administrator uses risk attributes to create risk profiles.

Table 196. Predefined attribute data types. Each predefined attribute has a data type. Data types are classifications that identify the possible values for each type of attribute.

Data type
Data type description

Boolean
Condition that refers to two possible values:

True

False

Date
Date of the request.

Integer
Number that can be written without a fractional or decimal component.

String
Sequence of characters.

Time
Time of the request.

X500Name
Values with distinguished names.

Table 197. Predefined attribute source types. Source types indicate the source of each attribute.

Source type
Source type description

Active
Collected by the attribute collection service. The administrator must add JavaScript to the application so that active attributes can be collected. For example: system fonts.

Derived
Generated by a policy information point (PIP). For example: risk score.

Passive
Collected from the browser by the external authorization service (EAS) and placed into an XACML request. Attributes with this source type are collected by the policy enforcement point (PEP) without installing more software or challenging the client to provide more details. For example: user-agent HTTP header and client IP address.

Table 198. Predefined attribute sources. Sources indicate where the attributes originate from.

Source | Source description
Attribute collection service | Collects information about the user device such as browser information, the operating system of the device, and the language of the device.
Consent external authentication interface | Asks the user for a device registration decision.
Device fingerprint count PIP | Counts the number of devices that are associated with the user.
Fiberlink MaaS360 PIP | Retrieves device attributes from the registered MaaS360 device inventory.
Geolocation PIP | Looks up the location of the user that is based on the IP address.
HTTP headers | Provides information about the request.
IP reputation PIP | Generates the IP reputation. See IP reputation for more information about IP reputation.
POST data | Collects information about the user and sends it to the external authorization service (EAS) as POST data. The EAS inserts this POST data into the decision request.
Risk engine | Generates the risk score. See Risk score calculation for more information about risk score calculation.
System time | Keeps the time of the system.
Security Access Manager credential | Collects information about the user from Security Access Manager.
Worklight® JavaScript PIP | Parses the POST data from a Worklight adapter invocation and returns custom attributes that are created from the data that is contained within the POST from the parameters element.

accessTime
The accessTime attribute contains the record of the past login times that belongs to the user.

action
The action attribute indicates the action that is performed on the resource

authenticationLevel
The authenticationLevel attribute is a numeric value that specifies the authentication level of a user.

authenticationMechanism
The authenticationMechanism attribute indicates the location of the user registry that belongs to the requesting user.

authenticationMechanismTypes
The authenticationMechanismTypes attribute indicates the types of authentication mechanisms that the user completes during the current authenticated session.

authenticationMethod
The authenticationMethod attribute indicates the method of authentication that is used, such as password.

authenticationTypes
The authenticationTypes attribute indicates the types of authentication policies that the user completes during the current authenticated session.

browserPlugins
The browserPlugins attribute indicates all of the installed plug-ins in the browser in a comma-separated list.

colorDepth
The colorDepth attribute indicates the bit depth of the color palette of the device.

currentDate
The currentDate attribute indicates the date of the request.

currentTime
The currentTime attribute indicates the time of the request.

deviceFonts
The deviceFonts attribute indicates all of the installed fonts on the device in a comma-separated list.

deviceLanguage
The deviceLanguage attribute indicates the language of the device.

deviceName
The deviceName attribute indicates the name of the device.

devicePlatform
The devicePlatform attribute indicates the operating system of the device.

fiberlink.maas360.device.compliance.state
The fiberlink.maas360.device.compliance.state attribute indicates the Fiberlink MaaS360 ownership of the registered device.

fiberlink.maas360.device.ids
The fiberlink.maas360.device.ids attribute indicates the Fiberlink MaaS360 registered device IDs.

fiberlink.maas360.device.ownership
The fiberlink.maas360.device.ownership attribute indicates a Fiberlink MaaS360 ownership of the registered device.

fiberlink.maas360.device.jailbroken
The fiberlink.maas360.device.jailbroken attribute indicates the Fiberlink MaaS360 jailbroken state of the registered device.

fiberlink.maas360.device.last.reported
The fiberlink.maas360.device.last.reported attribute indicates the Fiberlink MaaS360 last reported date and time of the device to the server.

fiberlink.maas360.device.managed.status
The fiberlink.maas360.device.managed.status attribute indicates the Fiberlink MaaS360 managed status of the registered device.

fiberlink.maas360.device.match.found
The fiberlink.maas360.device.match.found attribute indicates a Fiberlink MaaS360 match against the attribute collection service to a registered device.

geoCity
The geoCity attribute indicates the city in which the device is located.

geoCountryCode
The geoCountryCode attribute indicates the country in which the device is located.

geoLocation
The geoLocation attribute indicates the latitude, longitude, and accuracy of the requesting device that is obtained with the W3C geolocation standard.

geoRegionCode
The geoRegionCode attribute indicates the state or province in which the device is located.

groups
The groups attribute lists the groups of which the user is a member.

groupsDN
The groupsDN attribute lists the groups of which the user is a member.

http:accept
The http:accept attribute indicates the acceptable content types.

http:acceptEncoding
The http:acceptEncoding attribute indicates the acceptable encoding types.

http:acceptLanguage
The http:acceptLanguage attribute indicates the acceptable human languages for response.

http:host
The http:host attribute indicates the host that is requested.

http:uri
The http:uri attribute indicates the requested resource and the query string.

http:userAgent
The http:userAgent attribute indicates the user agent.

ipAddress
The ipAddress attribute indicates the string representation of the IP address.

ipReputation
The ipReputation attribute lists any combination of certain classifications whose IP reputation score is at or above the threshold.

oauthScopeResource
The oauthScopeResource attribute indicates authorization of an API call for OAuth. This value originates when the OAuth grant is created.

oauthScopeSubject
The oauthScopeSubject attribute indicates the identity for the session for OAuth. This value originates when the OAuth grant is created.

qop
The qop attribute indicates the quality of protection information.

registeredDeviceCount
The registeredDeviceCount attribute indicates the number of devices that the user registers.

resource
The resource attribute indicates the Worklight adapter parameters URL encoded JSON array POST data.

riskScore
The riskScore attribute indicates the calculated risk score, which is a number 0 - 100.

scheme
The scheme attribute indicates the protocol that is used to access the resource.

screenAvailableHeight
The screenAvailableHeight attribute indicates the height of the screen of the requesting device without the toolbar.

screenAvailableWidth
The screenAvailableWidth attribute indicates the width of the screen of the requesting device without the toolbar.

screenHeight
The screenHeight attribute indicates the height of the screen of the requesting device.

screenWidth
The screenWidth attribute indicates the width of the screen of the requesting device.

userConsent
The userConsent attribute indicates the registration decision of the user.

userDN
The userDN attribute indicates the distinguished name for the user in a registry.

username
The username attribute identifies the user.

worklight.adapter.adapter
The worklight.adapter.adapter attribute indicates the Worklight adapter adapter POST data.

worklight.adapter.balance.account
The worklight.adapter.balance.account attribute indicates the Worklight adapter BankingApprovals getBalance account.

worklight.adapter.parameters
The worklight.adapter.parameters attribute indicates the Worklight adapter parameters URL encoded JSON array POST data.

worklight.adapter.procedure
The worklight.adapter.procedure attribute indicates the Worklight adapter procedure POST data.

worklight.adapter.transfer.account.from
The worklight.adapter.transfer.account.from attribute indicates the Worklight adapter BankingApprovals doTransfer from account.

worklight.adapter.transfer.account.to
The worklight.adapter.transfer.account.to attribute indicates the Worklight adapter BankingApprovals doTransfer to account.

worklight.adapter.transfer.amount
The worklight.adapter.transfer.amount attribute indicates the Worklight adapter BankingApprovals doTransfer amount.

worklight.device.id
The worklight.device.id attribute indicates the unique ID of the device that is assigned by Worklight.

worklight.version.app
The worklight.version.app attribute indicates the version of the Worklight application.

worklight.version.native
The worklight.version.native attribute indicates the version of the Worklight application.

worklight.version.platform
The worklight.version.platform attribute indicates the version of the Worklight Software Development Kit for the Advanced Access Control.

Parent topic: Attributes

accessTimeaccessTimeaccessTimeThe accessTime attribute contains the record of the past login times that belongs to the user.Predefined attributes accessTimeThe accessTime attribute uses the ISO 8601 standard: YYYY-MM-DD'T'hh:mm:ss'Z'. For example: 2013-06-07T04:02:33ZCategoryTypeData typeSource typeSourceEnvironmentRisk profile TimePassiveSystem time Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

accessTime

The accessTime attribute contains the record of the past login times that belongs to the user.

The accessTime attribute uses the ISO 8601 standard: YYYY-MM-DD'T'hh:mm:ss'Z'. For example: 2013-06-07T04:02:33Z

Category | Type | Data type | Source type | Source
Environment | Risk profile | Time | Passive | System time

Parent topic: Predefined attributes

actionactionactionThe action attribute indicates the action that is performed on the resourcePredefined attributes actionThe action attribute includes one of the following values: CONNECTDELETEGETHEADOPTIONSPATCHPOSTPUTTRACECategoryTypeData typeSource typeSourceActionAccess policy, Risk profileStringPassiveHTTP headersPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

action

The action attribute indicates the action that is performed on the resource

The action attribute includes one of the following values:

CONNECT

DELETE

GET

HEAD

OPTIONS

PATCH

POST

PUT

TRACE

Category | Type | Data type | Source type | Source
Action | Access policy, Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

authenticationLevelauthenticationLevelauthenticationLevelThe authenticationLevel attribute is a numeric value that specifies the authentication level of a user. Predefined attributes authenticationLevelIt increases as the levels of authentication that belong to the user increase. For example: A possible authentication level is 2. CategoryTypeData typeSource typeSourceSubjectAccess policyIntegerPassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

authenticationLevel

The authenticationLevel attribute is a numeric value that specifies the authentication level of a user.

It increases as the levels of authentication that belong to the user increase. For example: A possible authentication level is 2.

Category | Type | Data type | Source type | Source
Subject | Access policy | Integer | Passive | Security Access Manager credential

Parent topic: Predefined attributes

authenticationMechanismauthenticationMechanismauthenticationMechanismThe authenticationMechanism attribute indicates the location of the user registry that belongs to the requesting user. Predefined attributes authenticationMechanismFor example: LDAP RegistryCategoryTypeData typeSource typeSourceSubjectAccess policy, Risk profileStringPassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

authenticationMechanism

The authenticationMechanism attribute indicates the location of the user registry that belongs to the requesting user.

For example: LDAP Registry

Category | Type | Data type | Source type | Source
Subject | Access policy, Risk profile | String | Passive | Security Access Manager credential

Parent topic: Predefined attributes

authenticationMechanismTypesauthenticationMechanismTypesauthenticationMechanismTypesThe authenticationMechanismTypes attribute indicates the types of authentication mechanisms that the user completes during the current authenticated session. Predefined attributes authenticationMechanismTypesThe authenticationMechanismTypes attribute values consist of the unique identifiers for the completed authentication mechanisms. The following values are predefined: urn:ibm:security:authentication:asf:mechanism:hotpurn:ibm:security:authentication:asf:mechanism:macotpurn:ibm:security:authentication:asf:mechanism:rsaurn:ibm:security:authentication:asf:mechanism:totpurn:ibm:security:authentication:asf:mechanism:consent_register_device urn:ibm:security:authentication:asf:mechanism:otpurn:ibm:security:authentication:asf:mechanism:http_redirect urn:ibm:security:authentication:asf:mechanism:password CategoryTypeData typeSource typeSourceSubjectAccess policyStringPassiveSecurity AccessManager credential Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

authenticationMechanismTypes

The authenticationMechanismTypes attribute indicates the types of authentication mechanisms that the user completes during the current authenticated session.

The authenticationMechanismTypes attribute values consist of the unique identifiers for the completed authentication mechanisms. The following values are predefined:

urn:ibm:security:authentication:asf:mechanism:hotp

urn:ibm:security:authentication:asf:mechanism:macotp

urn:ibm:security:authentication:asf:mechanism:rsa

urn:ibm:security:authentication:asf:mechanism:totp

urn:ibm:security:authentication:asf:mechanism:consent_register_device

urn:ibm:security:authentication:asf:mechanism:otp

urn:ibm:security:authentication:asf:mechanism:http_redirect

urn:ibm:security:authentication:asf:mechanism:password

Category | Type | Data type | Source type | Source
Subject | Access policy | String | Passive | Security AccessManager credential 

Parent topic: Predefined attributes

authenticationMethodauthenticationMethodauthenticationMethodThe authenticationMethod attribute indicates the method of authentication that is used, such as password.Predefined attributes authenticationMethodThe authenticationMethod attribute includes the following values: ext-auth-interfacepasswordssltoken-cardunauthenticatedCategoryTypeData typeSource type SourceSubjectAccess policy, Risk profileStringPassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

authenticationMethod

The authenticationMethod attribute indicates the method of authentication that is used, such as password.

The authenticationMethod attribute includes the following values:

ext-auth-interface

password

ssl

token-card

unauthenticated

Category | Type | Data type | Source type | Source
Subject | Access policy, Risk profile | String | Passive | Security Access Manager credential

Parent topic: Predefined attributes

authenticationTypesauthenticationTypesauthenticationTypesThe authenticationTypes attribute indicates the types of authentication policies that the user completes during the current authenticated session. Predefined attributes authenticationTypesThe authenticationTypes attribute values consist of the unique identifiers for the completed authentication policies. The values can include the identifiers for predefined authentication policies or custom values that are created by the administrator.  The following values are predefined: urn:ibm:security:obligation:register_deviceurn:ibm:security:authentication:asf:otpurn:ibm:security:authentication:asf:hotpurn:ibm:security:authentication:asf:totpurn:ibm:security:authentication:asf:rsaurn:ibm:security:authentication:asf:emailurn:ibm:security:authentication:asf:smsurn:ibm:security:authentication:asf:consent_register_device urn:ibm:security:authentication:asf:password urn:ibm:security:authentication:asf:macotpurn:ibm:security:authentication:asf:hotpurn:ibm:security:authentication:asf:otpurn:ibm:security:authentication:asf:totpurn:ibm:security:authentication:asf:smsurn:ibm:security:authentication:asf:emailurn:ibm:security:authentication:asf:rsaurn:ibm:security:authentication:asf:consent_register_deviceurn:ibm:security:authentication:asf:http_redirecturn:ibm:security:authentication:asf:password_smsotpurn:ibm:security:authentication:asf:password_hotpurn:ibm:security:authentication:asf:password_macotpurn:ibm:security:authentication:asf:password_rsaurn:ibm:security:authentication:asf:password_emailotpurn:ibm:security:authentication:asf:password_totpurn:ibm:security:authentication:asf:password_otpCategoryTypeData typeSource typeSourceSubjectAccess policyStringPassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

authenticationTypes

The authenticationTypes attribute indicates the types of authentication policies that the user completes during the current authenticated session.

The authenticationTypes attribute values consist of the unique identifiers for the completed authentication policies. The values can include the identifiers for predefined authentication policies or custom values that are created by the administrator.  The following values are predefined:

urn:ibm:security:obligation:register_device

urn:ibm:security:authentication:asf:otp

urn:ibm:security:authentication:asf:hotp

urn:ibm:security:authentication:asf:totp

urn:ibm:security:authentication:asf:rsa

urn:ibm:security:authentication:asf:email

urn:ibm:security:authentication:asf:sms

urn:ibm:security:authentication:asf:consent_register_device

urn:ibm:security:authentication:asf:password

urn:ibm:security:authentication:asf:macotp

urn:ibm:security:authentication:asf:hotp

urn:ibm:security:authentication:asf:otp

urn:ibm:security:authentication:asf:totp

urn:ibm:security:authentication:asf:sms

urn:ibm:security:authentication:asf:email

urn:ibm:security:authentication:asf:rsa

urn:ibm:security:authentication:asf:consent_register_device

urn:ibm:security:authentication:asf:http_redirect

urn:ibm:security:authentication:asf:password_smsotp

urn:ibm:security:authentication:asf:password_hotp

urn:ibm:security:authentication:asf:password_macotp

urn:ibm:security:authentication:asf:password_rsa

urn:ibm:security:authentication:asf:password_emailotp

urn:ibm:security:authentication:asf:password_totp

urn:ibm:security:authentication:asf:password_otp

Category | Type | Data type | Source type | Source
Subject | Access policy | String | Passive | Security Access Manager credential

Parent topic: Predefined attributes

browserPluginsbrowserPluginsbrowserPluginsThe browserPlugins attribute indicates all of the installed plug-ins in the browser in a comma-separated list. Predefined attributes browserPlugins For example: Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for LinuxCategoryTypeData typeSource typeSourceEnvironmentRisk profileStringActiveAttribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

browserPlugins

The browserPlugins attribute indicates all of the installed plug-ins in the browser in a comma-separated list.

For example: Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for Linux

Category | Type | Data type | Source type | Source
Environment | Risk profile | String | Active | Attribute collection service

Parent topic: Predefined attributes

colorDepthcolorDepthcolorDepthThe colorDepth attribute indicates the bit depth of the color palette of the device. Predefined attributes colorDepthFor example: 32CategoryTypeData typeSource typeSourceEnvironmentRisk profileIntegerActive Attribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

colorDepth

The colorDepth attribute indicates the bit depth of the color palette of the device.

For example: 32

Category | Type | Data type | Source type | Source
Environment | Risk profile | Integer | Active | Attribute collection service

Parent topic: Predefined attributes

currentDatecurrentDatecurrentDateThe currentDate attribute indicates the date of the request. Predefined attributes currentDateThe currentDate attribute uses the format: YYYY-MM-DDzzzzzz. For example: 2013-05-20−06:00CategoryTypeData typeSource typeSourceEnvironmentAccess policyDatePassive System timePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

currentDate

The currentDate attribute indicates the date of the request.

The currentDate attribute uses the format: YYYY-MM-DDzzzzzz. For example: 2013-05-20−06:00

Category | Type | Data type | Source type | Source
Environment | Access policy | Date | Passive | System time

Parent topic: Predefined attributes

currentTimecurrentTimecurrentTimeThe currentTime attribute indicates the time of the request.Predefined attributes currentTimeIt uses the format: hh:mm:sszzzzzz. For example: 12:15:26+01:00 CategoryTypeData typeSource typeSourceEnvironmentAccess policyTimePassiveSystem timePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

currentTime

The currentTime attribute indicates the time of the request.

It uses the format: hh:mm:sszzzzzz. For example: 12:15:26+01:00

Category | Type | Data type | Source type | Source
Environment | Access policy | Time | Passive | System time

Parent topic: Predefined attributes

deviceFontsdeviceFontsdeviceFontsThe deviceFonts attribute indicates all of the installed fonts on the device in a comma-separated list.Predefined attributes deviceFontsFor example: Arial, Dingbats, Georgia, Tahoma, Times New Roman, Verdana CategoryTypeData typeSource typeSourceEnvironmentRisk profileStringActive Attribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

deviceFonts

The deviceFonts attribute indicates all of the installed fonts on the device in a comma-separated list.

For example: Arial, Dingbats, Georgia, Tahoma, Times New Roman, Verdana

Category | Type | Data type | Source type | Source
Environment | Risk profile | String | Active | Attribute collection service

Parent topic: Predefined attributes

deviceLanguagedeviceLanguagedeviceLanguageThe deviceLanguage attribute indicates the language of the device. Predefined attributes deviceLanguageIt uses the Internet Engineering Task Force (IETF) language tag standard. For example: en-US CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringActiveAttribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

deviceLanguage

The deviceLanguage attribute indicates the language of the device.

It uses the Internet Engineering Task Force (IETF) language tag standard. For example: en-US

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Active | Attribute collection service

Parent topic: Predefined attributes

deviceNamedeviceNamedeviceNameThe deviceName attribute indicates the name of the device.Predefined attributes deviceNameFor example: My laptop CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringActiveConsent external authentication interfacePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

deviceName

The deviceName attribute indicates the name of the device.

For example: My laptop

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Active | Consent external authentication interface

Parent topic: Predefined attributes

devicePlatformdevicePlatformdevicePlatformThe devicePlatform attribute indicates the operating system of the device. Predefined attributes devicePlatformFor example: Linux x86_64 CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringActiveAttribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

devicePlatform

The devicePlatform attribute indicates the operating system of the device.

For example: Linux x86_64

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Active | Attribute collection service

Parent topic: Predefined attributes

fiberlink.maas360.device.compliance.statefiberlink.maas360.device.compliance.statefiberlink.maas360.device.compliance.stateThe fiberlink.maas360.device.compliance.state attribute indicates the Fiberlink MaaS360 ownership of the registered device.Predefined attributes fiberlink.maas360.device.compliance.stateValid values are: In CcomplianceOut of Compliance CategoryTypeData typeSource typeSourceSubjectPolicy, RiskStringDerived Fiberlink MaaS360 PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

fiberlink.maas360.device.compliance.state

The fiberlink.maas360.device.compliance.state attribute indicates the Fiberlink MaaS360 ownership of the registered device.

Valid values are:

In Ccompliance

Out of Compliance

Category | Type | Data type | Source type | Source
Subject | Policy, Risk | String | Derived | Fiberlink MaaS360 PIP

Parent topic: Predefined attributes

fiberlink.maas360.device.idsfiberlink.maas360.device.idsfiberlink.maas360.device.idsThe fiberlink.maas360.device.ids attribute indicates the Fiberlink MaaS360 registered device IDs.Predefined attributes fiberlink.maas360.device.ids CategoryTypeData typeSource typeSourceEnvironmentNoneStringDerived Fiberlink MaaS360 PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

fiberlink.maas360.device.ids

The fiberlink.maas360.device.ids attribute indicates the Fiberlink MaaS360 registered device IDs.

Category | Type | Data type | Source type | Source
Environment | None | String | Derived | Fiberlink MaaS360 PIP

Parent topic: Predefined attributes

fiberlink.maas360.device.ownershipfiberlink.maas360.device.ownershipfiberlink.maas360.device.ownershipThe fiberlink.maas360.device.ownership attribute indicates a Fiberlink MaaS360 ownership of the registered device.Predefined attributes fiberlink.maas360.device.ownershipValid values are: Corporate OwnedCorporate SharedCorporate Third PartyEmployee OwnedNot Defined CategoryTypeData typeSource typeSourceSubjectPolicy, RiskStringDerived Fiberlink MaaS360 PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

fiberlink.maas360.device.ownership

The fiberlink.maas360.device.ownership attribute indicates a Fiberlink MaaS360 ownership of the registered device.

Valid values are:

Corporate Owned

Corporate Shared

Corporate Third Party

Employee Owned

Not Defined

Category | Type | Data type | Source type | Source
Subject | Policy, Risk | String | Derived | Fiberlink MaaS360 PIP

Parent topic: Predefined attributes

fiberlink.maas360.device.jailbrokenfiberlink.maas360.device.jailbrokenfiberlink.maas360.device.jailbrokenThe fiberlink.maas360.device.jailbroken attribute indicates the Fiberlink MaaS360 jailbroken state of the registered device.Predefined attributes fiberlink.maas360.device.jailbrokenValid values are: YesNo CategoryTypeData typeSource typeSourceSubjectPolicy, RiskStringDerived Fiberlink MaaS360 PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

fiberlink.maas360.device.jailbroken

The fiberlink.maas360.device.jailbroken attribute indicates the Fiberlink MaaS360 jailbroken state of the registered device.

Valid values are:

Yes

No

Category | Type | Data type | Source type | Source
Subject | Policy, Risk | String | Derived | Fiberlink MaaS360 PIP

Parent topic: Predefined attributes

fiberlink.maas360.device.last.reportedfiberlink.maas360.device.last.reportedfiberlink.maas360.device.last.reportedThe fiberlink.maas360.device.last.reported attribute indicates the Fiberlink MaaS360 last reported date and time of the device to the server.Predefined attributes fiberlink.maas360.device.last.reportedThe date and time uses the ISO 8601 standard: YYYY-MM-DD'T'hh:mm:ss. For example: 2014-06-07T04:02:33 CategoryTypeData typeSource typeSourceEnvironmentPolicy, RiskStringDerived Fiberlink MaaS360 PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

fiberlink.maas360.device.last.reported

The fiberlink.maas360.device.last.reported attribute indicates the Fiberlink MaaS360 last reported date and time of the device to the server.

The date and time uses the ISO 8601 standard: YYYY-MM-DD'T'hh:mm:ss. For example: 2014-06-07T04:02:33

Category | Type | Data type | Source type | Source
Environment | Policy, Risk | String | Derived | Fiberlink MaaS360 PIP

Parent topic: Predefined attributes

fiberlink.maas360.device.managed.statusfiberlink.maas360.device.managed.statusfiberlink.maas360.device.managed.statusThe fiberlink.maas360.device.managed.status attribute indicates the Fiberlink MaaS360 managed status of the registered device.Predefined attributes fiberlink.maas360.device.managed.statusValid values are: EnrolledNot EnrolledUser Removed ControlControl RemovedPending Control Removal CategoryTypeData typeSource typeSourceSubjectPolicy, RiskStringDerived Fiberlink MaaS360 PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

fiberlink.maas360.device.managed.status

The fiberlink.maas360.device.managed.status attribute indicates the Fiberlink MaaS360 managed status of the registered device.

Valid values are:

Enrolled

Not Enrolled

User Removed Control

Control Removed

Pending Control Removal

Category | Type | Data type | Source type | Source
Subject | Policy, Risk | String | Derived | Fiberlink MaaS360 PIP

Parent topic: Predefined attributes

fiberlink.maas360.device.match.foundfiberlink.maas360.device.match.foundfiberlink.maas360.device.match.foundThe fiberlink.maas360.device.match.found attribute indicates a Fiberlink MaaS360 match against the attribute collection service to a registered device.Predefined attributes fiberlink.maas360.device.match.foundValid values are: TrueFalse CategoryTypeData typeSource typeSourceEnvironmentPolicyBooleanDerived Fiberlink MaaS360 PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

fiberlink.maas360.device.match.found

The fiberlink.maas360.device.match.found attribute indicates a Fiberlink MaaS360 match against the attribute collection service to a registered device.

Valid values are:

True

False

Category | Type | Data type | Source type | Source
Environment | Policy | Boolean | Derived | Fiberlink MaaS360 PIP

Parent topic: Predefined attributes

geoCitygeoCitygeoCityThe geoCity attribute indicates the city in which the device is located. Predefined attributes geoCityFor example: Austin CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringDerived Geolocation PIPPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

geoCity

The geoCity attribute indicates the city in which the device is located.

For example: Austin

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Derived | Geolocation PIP

Parent topic: Predefined attributes

geoCountryCodegeoCountryCodegeoCountryCodeThe geoCountryCode attribute indicates the country in which the device is located. Predefined attributes geoCountryCodeIt uses the two letter country code according to the ISO-3166-1 standard. For example: The country code for the United States is US.For a list of country codes, see the International Organization for Standardization homepage. To find your two letter country code: On the right side of the page, click ISO 3166.In the HTML, Text and XML versions section, choose a format for the list of country codes.CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringDerived Geolocation PIPPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

geoCountryCode

The geoCountryCode attribute indicates the country in which the device is located.

It uses the two letter country code according to the ISO-3166-1 standard. For example: The country code for the United States is US.For a list of country codes, see the International Organization for Standardization homepage. To find your two letter country code:

On the right side of the page, click ISO 3166.

In the HTML, Text and XML versions section, choose a format for the list of country codes.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Derived | Geolocation PIP

Parent topic: Predefined attributes

geoLocationgeoLocationgeoLocationThe geoLocation attribute indicates the latitude, longitude, and accuracy of the requesting device that is obtained with the W3C geolocation standard. Predefined attributes geoLocationIt uses the format: latitude, longitude, accuracy For example: 60.170833, 24.9375, 98CategoryTypeData typeSource typeSourceEnvironmentRisk profileStringActive Attribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

geoLocation

The geoLocation attribute indicates the latitude, longitude, and accuracy of the requesting device that is obtained with the W3C geolocation standard.

It uses the format: latitude, longitude, accuracy For example: 60.170833, 24.9375, 98

Category | Type | Data type | Source type | Source
Environment | Risk profile | String | Active | Attribute collection service

Parent topic: Predefined attributes

geoRegionCodegeoRegionCodegeoRegionCodeThe geoRegionCode attribute indicates the state or province in which the device is located.Predefined attributes geoRegionCodeIt uses the two letter code for the region. For the United States and Canada, the region codes are according to the ISO-3166-2 standard. For example: The region code for the province of Nova Scotia in Canada is NS. For all other countries, the region codes are according to the FIPS 10-4 standard. Your region code is the last pair of characters in the four-character code that is assigned to your region. For a list of region codes, see the National Geospatial Intelligence Agency homepage. To find your two-letter region code: On the left side of the page, click Country codes.In the Geopolitical Entities and Codes (Formerly FIPS PUB 10-4) section, find the most recent update and choose a format for a list of countries and region codes.For example: The region code for Queensland in Australia is 04.CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringDerived Geolocation PIPPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

geoRegionCode

The geoRegionCode attribute indicates the state or province in which the device is located.

It uses the two letter code for the region. For the United States and Canada, the region codes are according to the ISO-3166-2 standard. For example: The region code for the province of Nova Scotia in Canada is NS.

For all other countries, the region codes are according to the FIPS 10-4 standard. Your region code is the last pair of characters in the four-character code that is assigned to your region. For a list of region codes, see the National Geospatial Intelligence Agency homepage. To find your two-letter region code:

On the left side of the page, click Country codes.

In the Geopolitical Entities and Codes (Formerly FIPS PUB 10-4) section, find the most recent update and choose a format for a list of countries and region codes.

For example: The region code for Queensland in Australia is 04.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Derived | Geolocation PIP

Parent topic: Predefined attributes

groupsgroupsgroupsThe groups attribute lists the groups of which the user is a member.Predefined attributes groupsThe groups attribute is a multivalue attribute. See Attribute propertiesWhen you add or modify an attribute, you specify properties that make that attribute unique.. For example: engineeringCategoryTypeData typeSource typeSourceSubjectAccess policyStringPassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

groups

The groups attribute lists the groups of which the user is a member.

The groups attribute is a multivalue attribute. See Attribute properties. For example: engineering

Category | Type | Data type | Source type | Source
Subject | Access policy | String | Passive | Security Access Manager credential

Parent topic: Predefined attributes

groupsDNgroupsDNgroupsDNThe groupsDN attribute lists the groups of which the user is a member.Predefined attributes groupsDNThe groupsDN attribute has a distinguished name format and is a multivalue attribute. For example: CN=engineering, O=ibm, C=us CategoryTypeData typeSource typeSourceSubjectAccess policyX500Name PassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

groupsDN

The groupsDN attribute lists the groups of which the user is a member.

The groupsDN attribute has a distinguished name format and is a multivalue attribute. For example: CN=engineering, O=ibm, C=us

Category | Type | Data type | Source type | Source
Subject | Access policy | X500Name | Passive | Security Access Manager credential

Parent topic: Predefined attributes

http:accepthttp:accepthttp:acceptThe http:accept attribute indicates the acceptable content types.Predefined attributes http:acceptFor example: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8CategoryTypeData typeSource typeSourceEnvironmentRisk profileStringPassiveHTTP headersPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

http:accept

The http:accept attribute indicates the acceptable content types.

For example: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Category | Type | Data type | Source type | Source
Environment | Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

http:acceptEncodinghttp:acceptEncodinghttp:acceptEncodingThe http:acceptEncoding attribute indicates the acceptable encoding types. Predefined attributes http:acceptEncodingFor example: gzip, deflateCategoryTypeData typeSource typeSourceEnvironmentRisk profileStringPassiveHTTP headersPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

http:acceptEncoding

The http:acceptEncoding attribute indicates the acceptable encoding types.

For example: gzip, deflate

Category | Type | Data type | Source type | Source
Environment | Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

http:acceptLanguagehttp:acceptLanguagehttp:acceptLanguageThe http:acceptLanguage attribute indicates the acceptable human languages for response. Predefined attributes http:acceptLanguageFor example: en-US,en;q=0.8CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassiveHTTP headersPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

http:acceptLanguage

The http:acceptLanguage attribute indicates the acceptable human languages for response.

For example: en-US,en;q=0.8

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

http:hosthttp:hosthttp:hostThe http:host attribute indicates the host that is requested. Predefined attributes http:host CategoryTypeData typeSource type SourceEnvironmentAccess policyStringPassive HTTP headers Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

http:host

The http:host attribute indicates the host that is requested.

Category | Type | Data type | Source type | Source
Environment | Access policy | String | Passive | HTTP headers

Parent topic: Predefined attributes

http:urihttp:urihttp:uriThe http:uri attribute indicates the requested resource and the query string.Predefined attributes http:uriFor example: /mga/sps/ac/rest CategoryTypeData typeSource typeSourceEnvironmentAccess policyStringPassiveHTTP headersPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

http:uri

The http:uri attribute indicates the requested resource and the query string.

For example: /mga/sps/ac/rest

Category | Type | Data type | Source type | Source
Environment | Access policy | String | Passive | HTTP headers

Parent topic: Predefined attributes

http:userAgenthttp:userAgenthttp:userAgentThe http:userAgent attribute indicates the user agent. Predefined attributes http:userAgentFor example: Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.57 Safari/537.17CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive HTTP headersPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

http:userAgent

The http:userAgent attribute indicates the user agent.

For example: Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.57 Safari/537.17

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

ipAddressipAddressipAddressThe ipAddress attribute indicates the string representation of the IP address.Predefined attributes ipAddressSpecify one of the following IP address formats depending on the network type: IPv4 format192.9.200.1IPv6 formatFEDC:BA98:7654:3210:FEDC:BA98:7654:3210 CategoryTypeData typeSource typeSourceSubjectAccess policy, Risk profileStringPassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

ipAddress

The ipAddress attribute indicates the string representation of the IP address.

Specify one of the following IP address formats depending on the network type:

IPv4 format

192.9.200.1

IPv6 format

FEDC:BA98:7654:3210:FEDC:BA98:7654:3210

Category | Type | Data type | Source type | Source
Subject | Access policy, Risk profile | String | Passive | Security Access Manager credential

Parent topic: Predefined attributes

ipReputationipReputationipReputationThe ipReputation attribute lists any combination of certain classifications whose IP reputation score is at or above the threshold.Predefined attributes ipReputationThe ipReputation attribute lists any combination of the following classifications: Anonymous ProxiesBotnet Command and Control ServerDynamic IPsMalwareScanning IPsSpamThe user can either configure the threshold or use the default threshold of 50. CategoryTypeData typeSource typeSourceSubjectAccess policyString Derived IP reputation PIPPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

ipReputation

The ipReputation attribute lists any combination of certain classifications whose IP reputation score is at or above the threshold.

The ipReputation attribute lists any combination of the following classifications:

Anonymous Proxies

Botnet Command and Control Server

Dynamic IPs

Malware

Scanning IPs

Spam

The user can either configure the threshold or use the default threshold of 50.

Category | Type | Data type | Source type | Source
Subject | Access policy | String | Derived | IP reputation PIP

Parent topic: Predefined attributes

oauthScopeResourceoauthScopeResourceoauthScopeResourceThe oauthScopeResource attribute indicates authorization of an API call for OAuth. This value originates when the OAuth grant is created.Predefined attributes oauthScopeResource CategoryTypeData typeSource type SourceResourceAccess policyStringPassive OAuth External Authorization Service (EAS) Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

oauthScopeResource

The oauthScopeResource attribute indicates authorization of an API call for OAuth. This value originates when the OAuth grant is created.

Category | Type | Data type | Source type | Source
Resource | Access policy | String | Passive | OAuth External Authorization Service (EAS)

Parent topic: Predefined attributes

oauthScopeSubjectoauthScopeSubjectoauthScopeSubjectThe oauthScopeSubject attribute indicates the identity for the session for OAuth. This value originates when the OAuth grant is created.Predefined attributes oauthScopeSubject This value is only present for access control policies when a user authenticates by using the OAuth mechanism. If a user authenticates another way, this value is not present for an access control decision. CategoryTypeData typeSource type SourceSubjectAccess policy, Risk profileStringPassive OAuth authentication mechanism of the reverse proxy server Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

oauthScopeSubject

The oauthScopeSubject attribute indicates the identity for the session for OAuth. This value originates when the OAuth grant is created.

This value is only present for access control policies when a user authenticates by using the OAuth mechanism. If a user authenticates another way, this value is not present for an access control decision.

Category | Type | Data type | Source type | Source
Subject | Access policy, Risk profile | String | Passive | OAuth authentication mechanism of the reverse proxy server

Parent topic: Predefined attributes

qopqopqopThe qop attribute indicates the quality of protection information.Predefined attributes qopThe qop attribute includes the following valid values: NoneIntegrityPrivacyCategoryTypeData typeSource typeSourceSubjectAccess policy, Risk profileStringPassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

qop

The qop attribute indicates the quality of protection information.

The qop attribute includes the following valid values:

None

Integrity

Privacy

Category | Type | Data type | Source type | Source
Subject | Access policy, Risk profile | String | Passive | Security Access Manager credential

Parent topic: Predefined attributes

registeredDeviceCountregisteredDeviceCountregisteredDeviceCountThe registeredDeviceCount attribute indicates the number of devices that the user registers.Predefined attributes registeredDeviceCount CategoryTypeData typeSource type SourceSubjectAccess policy IntegerDerived Device fingerprint count PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

registeredDeviceCount

The registeredDeviceCount attribute indicates the number of devices that the user registers.

Category | Type | Data type | Source type | Source
Subject | Access policy | Integer | Derived | Device fingerprint count PIP

Parent topic: Predefined attributes

resourceresourceresourceThe resource attribute indicates the Worklight adapter parameters URL encoded JSON array POST data.Predefined attributes resourceIt does not include the query string and is usually the same as the http:uri attribute. For example: /mga/sps/ac/restCategoryTypeData typeSource typeSourceResourceAccess policyStringPassiveHTTP headersPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

resource

The resource attribute indicates the Worklight® adapter parameters URL encoded JSON array POST data.

It does not include the query string and is usually the same as the http:uri attribute.

For example: /mga/sps/ac/rest

Category | Type | Data type | Source type | Source
Resource | Access policy | String | Passive | HTTP headers

Parent topic: Predefined attributes

riskScoreriskScoreriskScoreThe riskScore attribute indicates the calculated risk score, which is a number 0 - 100. Predefined attributes riskScoreThe risk score indicates the level of risk that is associated with authenticating a request device. See Risk score calculationRisk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.. CategoryTypeData typeSource typeSourceSubjectAccess policyIntegerDerived Risk enginePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

riskScore

The riskScore attribute indicates the calculated risk score, which is a number 0 - 100.

The risk score indicates the level of risk that is associated with authenticating a request device. See Risk score calculation.

Category | Type | Data type | Source type | Source
Subject | Access policy | Integer | Derived | Risk engine

Parent topic: Predefined attributes

schemeschemeschemeThe scheme attribute indicates the protocol that is used to access the resource. Predefined attributes schemeFor example: http, https, or ftp. CategoryTypeData typeSource type SourceEnvironmentAccess policyStringPassive HTTP headers Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

scheme

The scheme attribute indicates the protocol that is used to access the resource.

For example: http, https, or ftp.

Category | Type | Data type | Source type | Source
Environment | Access policy | String | Passive | HTTP headers

Parent topic: Predefined attributes

screenAvailableHeightscreenAvailableHeightscreenAvailableHeightThe screenAvailableHeight attribute indicates the height of the screen of the requesting device without the toolbar.Predefined attributes screenAvailableHeightFor example: 1025CategoryTypeData typeSource typeSourceEnvironmentRisk profileIntegerActiveAttribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

screenAvailableHeight

The screenAvailableHeight attribute indicates the height of the screen of the requesting device without the toolbar.

For example: 1025

Category | Type | Data type | Source type | Source
Environment | Risk profile | Integer | Active | Attribute collection service

Parent topic: Predefined attributes

screenAvailableWidthscreenAvailableWidthscreenAvailableWidthThe screenAvailableWidth attribute indicates the width of the screen of the requesting device without the toolbar.Predefined attributes screenAvailableWidthFor example: 1920CategoryTypeData typeSource typeSourceEnvironmentRisk profileIntegerActiveAttribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

screenAvailableWidth

The screenAvailableWidth attribute indicates the width of the screen of the requesting device without the toolbar.

For example: 1920

Category | Type | Data type | Source type | Source
Environment | Risk profile | Integer | Active | Attribute collection service

Parent topic: Predefined attributes

screenHeightscreenHeightscreenHeightThe screenHeight attribute indicates the height of the screen of the requesting device. Predefined attributes screenHeightFor example: 1080CategoryTypeData typeSource typeSourceEnvironmentRisk profileIntegerActiveAttribute collection servicePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

screenHeight

The screenHeight attribute indicates the height of the screen of the requesting device.

For example: 1080

Category | Type | Data type | Source type | Source
Environment | Risk profile | Integer | Active | Attribute collection service

Parent topic: Predefined attributes

screenWidthscreenWidthscreenWidthThe screenWidth attribute indicates the width of the screen of the requesting device. Predefined attributes screenWidthFor example: 1920CategoryTypeData typeSource typeSourceEnvironmentRisk profileIntegerActiveAttribute collection service Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

screenWidth

The screenWidth attribute indicates the width of the screen of the requesting device.

For example: 1920

Category | Type | Data type | Source type | Source
Environment | Risk profile | Integer | Active | Attribute collection service

Parent topic: Predefined attributes

userConsentuserConsentuserConsentThe userConsent attribute indicates the registration decision of the user. Predefined attributes userConsentA registered device is true. An unregistered device is false. CategoryTypeData typeSource typeSourceEnvironmentAccess policyBoolean Active Consent external authentication interfacePredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

userConsent

The userConsent attribute indicates the registration decision of the user.

A registered device is true. An unregistered device is false.

Category | Type | Data type | Source type | Source
Environment | Access policy | Boolean | Active | Consent external authentication interface

Parent topic: Predefined attributes

userDNuserDNuserDNThe userDN attribute indicates the distinguished name for the user in a registry. Predefined attributes userDNFor example: CN=Mark Smith,o=IBM, L=Austin, S=Texas, C=US CategoryTypeData typeSource typeSourceSubjectAccess policy, Risk profileX500NamePassiveSecurity Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

userDN

The userDN attribute indicates the distinguished name for the user in a registry.

For example: CN=Mark Smith,o=IBM, L=Austin, S=Texas, C=US

Category | Type | Data type | Source type | Source
Subject | Access policy, Risk profile | X500Name | Passive | Security Access Manager credential

Parent topic: Predefined attributes

usernameusernameusernameThe username attribute identifies the user.Predefined attributes usernameFor example: sec_masterCategoryTypeData typeSource typeSourceSubjectAccess policy, Risk profileStringPassive Security Access Manager credentialPredefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

username

The username attribute identifies the user.

For example: sec_master

Category | Type | Data type | Source type | Source
Subject | Access policy, Risk profile | String | Passive | Security Access Manager credential

Parent topic: Predefined attributes

worklight.adapter.adapterworklight.adapter.adapterworklight.adapter.adapterThe worklight.adapter.adapter attribute indicates the Worklight adapter adapter POST data.Predefined attributes worklight.adapter.adapter CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive POST data Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.adapter.adapter

The worklight.adapter.adapter attribute indicates the Worklight® adapter adapter POST data.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | POST data

Parent topic: Predefined attributes

worklight.adapter.balance.accountworklight.adapter.balance.accountworklight.adapter.balance.accountThe worklight.adapter.balance.account attribute indicates the Worklight adapter BankingApprovals getBalance account.Predefined attributes worklight.adapter.balance.account CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringDerivedWorklight JavaScript PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.adapter.balance.account

The worklight.adapter.balance.account attribute indicates the Worklight® adapter BankingApprovals getBalance account.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Derived | Worklight JavaScript PIP

Parent topic: Predefined attributes

worklight.adapter.parametersworklight.adapter.parametersworklight.adapter.parametersThe worklight.adapter.parameters attribute indicates the Worklight adapter parameters URL encoded JSON array POST data.Predefined attributes worklight.adapter.parameters CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive POST data Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.adapter.parameters

The worklight.adapter.parameters attribute indicates the Worklight® adapter parameters URL encoded JSON array POST data.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | POST data

Parent topic: Predefined attributes

worklight.adapter.procedureworklight.adapter.procedureworklight.adapter.procedureThe worklight.adapter.procedure attribute indicates the Worklight adapter procedure POST data.Predefined attributes worklight.adapter.procedure CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive POST data Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.adapter.procedure

The worklight.adapter.procedure attribute indicates the Worklight® adapter procedure POST data.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | POST data

Parent topic: Predefined attributes

worklight.adapter.transfer.account.fromworklight.adapter.transfer.account.fromworklight.adapter.transfer.account.fromThe worklight.adapter.transfer.account.from attribute indicates the Worklight adapter BankingApprovals doTransfer from account. Predefined attributes worklight.adapter.transfer.account.from CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringDerivedWorklight JavaScript PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.adapter.transfer.account.from

The worklight.adapter.transfer.account.from attribute indicates the Worklight® adapter BankingApprovals doTransfer from account.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Derived | Worklight JavaScript PIP

Parent topic: Predefined attributes

worklight.adapter.transfer.account.toworklight.adapter.transfer.account.toworklight.adapter.transfer.account.toThe worklight.adapter.transfer.account.to attribute indicates the Worklight adapter BankingApprovals doTransfer to account.Predefined attributes worklight.adapter.transfer.account.to CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringDerivedWorklight JavaScript PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.adapter.transfer.account.to

The worklight.adapter.transfer.account.to attribute indicates the Worklight® adapter BankingApprovals doTransfer to account.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Derived | Worklight JavaScript PIP

Parent topic: Predefined attributes

worklight.adapter.transfer.amountworklight.adapter.transfer.amountworklight.adapter.transfer.amountThe worklight.adapter.transfer.amount attribute indicates the Worklight adapter BankingApprovals doTransfer amount.Predefined attributes worklight.adapter.transfer.amount CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileIntegerDerivedWorklight JavaScript PIP Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.adapter.transfer.amount

The worklight.adapter.transfer.amount attribute indicates the Worklight® adapter BankingApprovals doTransfer amount.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | Integer | Derived | Worklight JavaScript PIP

Parent topic: Predefined attributes

worklight.device.id worklight.device.id worklight.device.id The worklight.device.id attribute indicates the unique ID of the device that is assigned by Worklight.Predefined attributes worklight.device.id CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive HTTP headers Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.device.id

The worklight.device.id attribute indicates the unique ID of the device that is assigned by Worklight®.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

worklight.version.appworklight.version.appworklight.version.appThe worklight.version.app attribute indicates the version of the Worklight application.Predefined attributes worklight.version.app CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive HTTP headers Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.version.app

The worklight.version.app attribute indicates the version of the Worklight® application.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

worklight.version.nativeworklight.version.nativeworklight.version.nativeThe worklight.version.native attribute indicates the version of the Worklight application.Predefined attributes worklight.version.native CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive HTTP headers Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.version.native

The worklight.version.native attribute indicates the version of the Worklight® application.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

worklight.version.platformworklight.version.platformworklight.version.platformThe worklight.version.platform attribute indicates the version of the Worklight Software Development Kit for the Advanced Access Control.Predefined attributes worklight.version.platform CategoryTypeData typeSource typeSourceEnvironmentAccess policy, Risk profileStringPassive HTTP headers Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.

worklight.version.platform

The worklight.version.platform attribute indicates the version of the Worklight® Software Development Kit for the Advanced Access Control.

Category | Type | Data type | Source type | Source
Environment | Access policy, Risk profile | String | Passive | HTTP headers

Parent topic: Predefined attributes

Configuring the hash algorithm for attribute storageHashing encodes a character string as a fixed-length bit string for comparison. Context-based access hashes certain attributes by default. You can change the hash algorithm and specify additional attributes that you want to hash.hash algorithmconfigurationconfigurationhash algorithmBy default, when attributes are stored in the context-based access database, the attributes that exceed the maximum length according to the schema are hashed. You can also specify any other attribute that you require to be hashed. For example, you might want to hash values that are considered confidential or private. The default hash algorithm that context-based access uses for storing these attributes is SHA256. Context-based access also uses the default when the hash algorithm is not configured properly. You can specify any other hash algorithm that Java Security supports.Log in to the local management interface.Click Secure Access Control.Under Global Settings, click Advanced Configuration.Under Key, find the name of the property that you must work with.Take one of the following actions:Configure the attributeCollection.attributesHashEnabled property.Click the edit icon . Enter the Identifier names of the attributes that you want the attributeCollection.attributesHashEnabled property to hash. For example: urn:ibm:security:environment:http:userAgent, urn:ibm:security:environment:deviceFonts, urn:ibm:security:environment:browserPlugins To find the list of attributes that context-based access can hash, complete the following steps: Log in to your local management interfaceClick Secure Access Control.Under Policy, click Attributes.Select the name of an attribute, and click Modify attributes .Under Modify Attribute, find the Identifier of the attribute.Use the Identifier of the attribute in your list of attributes that you want context-based access to hash. Click Cancel to exit. Configure the attributeCollection.hashAlgorithm property.Click the edit icon .Set the value for the attributeCollection.hashAlgorithm property to one of the following values: SHA1SHA512SHA256Click Save.When you make changes to the properties, the appliance displays a message that there are undeployed changes. If you are finished making changes, deploy them.AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.

Configuring the hash algorithm for attribute storage

Hashing encodes a character string as a fixed-length bit string for comparison. Context-based access hashes certain attributes by default. You can change the hash algorithm and specify additional attributes that you want to hash.

About this task

By default, when attributes are stored in the context-based access database, the attributes that exceed the maximum length according to the schema are hashed. You can also specify any other attribute that you require to be hashed. For example, you might want to hash values that are considered confidential or private.

The default hash algorithm that context-based access uses for storing these attributes is SHA256. Context-based access also uses the default when the hash algorithm is not configured properly. You can specify any other hash algorithm that Java™ Security supports.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Advanced Configuration.

Under Key, find the name of the property that you must work with.

Take one of the following actions:

Configure the attributeCollection.attributesHashEnabled property.

Click the edit icon Edit.

Enter the Identifier names of the attributes that you want the attributeCollection.attributesHashEnabled property to hash. For example: urn:ibm:security:environment:http:userAgent, urn:ibm:security:environment:deviceFonts, urn:ibm:security:environment:browserPlugins

To find the list of attributes that context-based access can hash, complete the following steps:

Log in to your local management interface

Click Secure Access Control.

Under Policy, click Attributes.

Select the name of an attribute, and click Modify attributes Modify attributes.

Under Modify Attribute, find the Identifier of the attribute.

Use the Identifier of the attribute in your list of attributes that you want context-based access to hash.

Click Cancel to exit.

Configure the attributeCollection.hashAlgorithm property.

Click the edit icon Edit.

Set the value for the attributeCollection.hashAlgorithm property to one of the following values:

SHA1

SHA512

SHA256

Click Save.

When you make changes to the properties, the appliance displays a message that there are undeployed changes. If you are finished making changes, deploy them.

Parent topic: Attributes

Dynamic attributesDynamic attributesDynamic attributesYou can capture additional context-based access information in dynamic attributes that you create or customize.dynamic attributesoverviewattributesdynamicAttributes used to calculate risk score come from various sources. Context-based access can capture and use many default attributes. However, you might require more information to be captured. This data can come from:Data that is gathered when a session is established that is sent to the Attribute Collector Service. This data persists during the session and is stored in the session table in context-based access.  This type of information is gathered by the info.js file.  Data that is derived from a particular request for which authorization is being performed. This data can be stored in either the session or behavior tables. Data that is provided by a PIP during the authorization decision. This data can be stored in either the session or behavior tables. This type of data can be captured in dynamic attributes.Scenarios for adding and manipulating attributesYou can dynamically add attributes or manipulate the values of attributes for various purposes.AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.Scenarios for adding and manipulating attributesYou can dynamically add attributes or manipulate the values of attributes for various purposes.Coding the dynamic.attributes.js fileAdd JavaScript code to the dynamic.attributes.js file to dynamically add attributes or modify the values of attributes. Updating and deploying the dynamic.attributes.js fileTo implement the dynamic.attributes.js file on your appliance, update the file and then deploy the change.

Dynamic attributes

You can capture additional context-based access information in dynamic attributes that you create or customize.

Attributes used to calculate risk score come from various sources. Context-based access can capture and use many default attributes. However, you might require more information to be captured. This data can come from:

Data that is gathered when a session is established that is sent to the Attribute Collector Service. This data persists during the session and is stored in the session table in context-based access.  This type of information is gathered by the info.js file.  

Data that is derived from a particular request for which authorization is being performed. This data can be stored in either the session or behavior tables.

Data that is provided by a PIP during the authorization decision. This data can be stored in either the session or behavior tables.

This type of data can be captured in dynamic attributes.

Scenarios for adding and manipulating attributes
You can dynamically add attributes or manipulate the values of attributes for various purposes.

Coding the dynamic.attributes.js file
Add JavaScript code to the dynamic.attributes.js file to dynamically add attributes or modify the values of attributes.

Updating and deploying the dynamic.attributes.js file
To implement the dynamic.attributes.js file on your appliance, update the file and then deploy the change.

Parent topic: Attributes

Related concepts:

Scenarios for adding and manipulating attributes

Scenarios for adding and manipulating attributesScenarios for adding and manipulating attributesScenarios for adding and manipulating attributesYou can dynamically add attributes or manipulate the values of attributes for various purposes.scenariosdynamic attributesattributesscenarios for dynamic attributesdynamic attributesscenariosThe following topics provide specific instructions to create or update the JavaScript file for dynamic attributes:Coding the dynamic.attributes.js fileAdd JavaScript code to the dynamic.attributes.js file to dynamically add attributes or modify the values of attributes. Updating and deploying the dynamic.attributes.js fileTo implement the dynamic.attributes.js file on your appliance, update the file and then deploy the change.The following scenarios show examples of the data you can dynamically capture:Creating a device.name attribute In this scenario, you can create a device name attribute that a user can easily identify. While configuring a system that only has hybrid applications, you can gather a few more attributes while using the info.js active collection library. For example, if you combine three separate device attributes that the client sends, you can uniquely identify the device. The attributes are: Device ModelDevice Model VersionDevice UUID (unique ID) Combining these attributes into a single attribute with a zero device weight results in a meaningful attribute name that you can use to display the device. You can accomplish this by providing a server-side JavaScript rule that runs when an attribute collection service request arrives. Adding the last risk score as a session attribute to be used by a third party The risk score is a derived attribute using a combination of other attributes. It can be useful for third party authentication services. In this scenario, you can implement a JavaScript rule that captures the current risk score and stores it as a session attribute. Later, when a third-party application is determining possible further action based on the current context, it can make a remote call to the attribute collection service using the REST API call to retrieve the sessions attributes, such as risk score.Dynamic attributesYou can capture additional context-based access information in dynamic attributes that you create or customize.

Scenarios for adding and manipulating attributes

You can dynamically add attributes or manipulate the values of attributes for various purposes.

The following topics provide specific instructions to create or update the JavaScript file for dynamic attributes:

Coding the dynamic.attributes.js file

Updating and deploying the dynamic.attributes.js file

The following scenarios show examples of the data you can dynamically capture:

Creating a device.name attribute

In this scenario, you can create a device name attribute that a user can easily identify. While configuring a system that only has hybrid applications, you can gather a few more attributes while using the info.js active collection library. For example, if you combine three separate device attributes that the client sends, you can uniquely identify the device. The attributes are:

Device Model

Device Model Version

Device UUID (unique ID)

Combining these attributes into a single attribute with a zero device weight results in a meaningful attribute name that you can use to display the device. You can accomplish this by providing a server-side JavaScript rule that runs when an attribute collection service request arrives.

Adding the last risk score as a session attribute to be used by a third party

The risk score is a derived attribute using a combination of other attributes. It can be useful for third party authentication services.

In this scenario, you can implement a JavaScript rule that captures the current risk score and stores it as a session attribute. Later, when a third-party application is determining possible further action based on the current context, it can make a remote call to the attribute collection service using the REST API call to retrieve the sessions attributes, such as risk score.

Parent topic: Dynamic attributes

Coding the dynamic.attributes.js fileCoding the dynamic.attributes.js fileCoding the dynamic.attributes.js fileAdd JavaScript code to the dynamic.attributes.js file to dynamically add attributes or modify the values of attributes. dynamic.attributes.js filecode to updatecontext-based accessdynamic.attributes.js fileupdate attributesattributesupdate using dynamic.attributes.js fileJavaScript filedynamic.attributes.jsReview the Scenarios for adding and manipulating attributesYou can dynamically add attributes or manipulate the values of attributes for various purposes.. Determine which attributes you want to modify and how to store them. Create a function for each one, which you will add to the dynamic.attributes.js file in the steps below.Deploy context-based access.The modifySessionAttributes and modifyBehaviorAttributes functions are the only functions called by the context-based access processing. Therefore, any function you add must be called within one of these functions in order to be executed. Create a JavaScript file or edit the sample dynamic.attributes.js file.Define the necessary import packages for the APIs you use. For example:importPackage(com.tivoli.am.rba.extensions); importClass(Packages.com.tivoli.am.rba.attributes.AttributeIdentifier);Use the modifySessionAttributes function to add or manipulate the session attributes.function modifySessionAttributes(attributes, username, session) Add code to work with session attributes.Create an attribute identifier. For example, to use the risk score value, the following line is required:var riskScoreIdentifier = new AttributeIdentifier("riskScore", "urn:ibm:security:subject:riskScore","Integer", "urn:ibm:security:issuer:RiskCalculator");Use the attribute identifier to get the value of this attribute. For example, to use the risk score, the following line is required:var riskScoreValue = session.getValue(riskScoreIdentifier);Call the function you created to process the attributes. Define the function either at the beginning or at the end of the dynamic.attributes.js file.Store your attribute to session storage. For example, to store the risk score, the following line is required:attributes.put(riskScoreIdentifier, riskScoreValue);Use the modifyBehaviorAttributes function to add or manipulate behavior attributes.function modifyBehaviorAttributes(attributes, username, session) Add code to work with behavior attributes. Create an attribute identifier. Use the attribute identifier to get the value of this attribute. Call the function you created to process the attributes. Define the function either at the beginning or at the end of the dynamic.attributes.js file.Store your attribute to behavioral storage. Save the file. The following dynamic.attributes.js file is a sample that is available with Advanced Access Control. The code in this example JavaScript file captures the risk score. This is the only way you can save the risk score value./** * This script is executed after each request is processed by risk engine. * The intent is to allow users to capture attributes that don't get captured * automatically by the system. The attributes captured here will be stored * in either the session storage or the behavior storage (i.e., usage data, historical) * area of RBA, or both. The risk profile configuration dictates where the * attributes will be stored by the system. * * For any RBA specific API, necessary packages need to be imported as shown in this example. */ /** * Import RBA packages necessary for the script to execute. */ importPackage(com.tivoli.am.rba.extensions); importClass(Packages.com.tivoli.am.rba.attributes.AttributeIdentifier); /** * @param username - current user's name * @param attributes - java.util.Map where the 'dynamic' values need to be captured by * this javascript file. * @param session - object containing current values visible to incoming request context */ function modifySessionAttributes(attributes, username, session) { // creates an identifier with the attribute's name, URI, datatype, and the issuer var riskScoreIdentifier = new AttributeIdentifier("riskScore", "urn:ibm:security:subject:riskScore", "Integer", "urn:ibm:security:issuer:RiskCalculator"); // retrieve the risk score var riskScoreValue = session.getValue(riskScoreIdentifier); // set the risk score to be stored as a session attribute attributes.put(riskScoreIdentifier, riskScoreValue); } /** * @param username - current user's name * @param attributes - java.util.Map where the 'dynamic' values need to be captured * by this javascript file. * @param session - RBA's com.tivoli.am.rba.fingerprinting.IValueContainer object * containing current values visible to incoming request context */ function modifyBehaviorAttributes(attributes, username, session) { // store any behavior attributes here } Update and deploy the dynamic.attributes.js file.To implement the dynamic.attributes.js file on your appliance, update the file and then deploy the change.Dynamic attributesYou can capture additional context-based access information in dynamic attributes that you create or customize.

Coding the dynamic.attributes.js file

Add JavaScript code to the dynamic.attributes.js file to dynamically add attributes or modify the values of attributes.

Before you begin

Review the Scenarios for adding and manipulating attributes.

Determine which attributes you want to modify and how to store them. Create a function for each one, which you will add to the dynamic.attributes.js file in the steps below.

Deploy context-based access.

About this task

The modifySessionAttributes and modifyBehaviorAttributes functions are the only functions called by the context-based access processing. Therefore, any function you add must be called within one of these functions in order to be executed. 

Procedure

Create a JavaScript file or edit the sample dynamic.attributes.js file.

Define the necessary import packages for the APIs you use. For example:

importPackage(com.tivoli.am.rba.extensions);
importClass(Packages.com.tivoli.am.rba.attributes.AttributeIdentifier);

Use the modifySessionAttributes function to add or manipulate the session attributes.

function modifySessionAttributes(attributes, username, session)

Add code to work with session attributes.

Create an attribute identifier. For example, to use the risk score value, the following line is required:

var riskScoreIdentifier = new AttributeIdentifier("riskScore",
  "urn:ibm:security:subject:riskScore","Integer",
  "urn:ibm:security:issuer:RiskCalculator");

Use the attribute identifier to get the value of this attribute. For example, to use the risk score, the following line is required:

var riskScoreValue = session.getValue(riskScoreIdentifier);

Call the function you created to process the attributes. Define the function either at the beginning or at the end of the dynamic.attributes.js file.

Store your attribute to session storage. For example, to store the risk score, the following line is required:

attributes.put(riskScoreIdentifier, riskScoreValue);

Use the modifyBehaviorAttributes function to add or manipulate behavior attributes.

function modifyBehaviorAttributes(attributes, username, session)

Add code to work with behavior attributes.

Create an attribute identifier.

Use the attribute identifier to get the value of this attribute.

Call the function you created to process the attributes. Define the function either at the beginning or at the end of the dynamic.attributes.js file.

Store your attribute to behavioral storage.

Save the file.

Example

The following dynamic.attributes.js file is a sample that is available with Advanced Access Control. The code in this example JavaScript file captures the risk score. This is the only way you can save the risk score value.

/**
 * This script is executed after each request is processed by risk engine.
 * The intent is to allow users to capture attributes that don't get captured
 * automatically by the system. The attributes captured here will be stored
 * in either the session storage or the behavior storage (i.e., usage data, historical)
 * area of RBA, or both. The risk profile configuration dictates where the
 * attributes will be stored by the system.
 *
 * For any RBA specific API, necessary packages need to be imported as shown in this example.
 */

/**
 * Import RBA packages necessary for the script to execute.
 */
importPackage(com.tivoli.am.rba.extensions);
importClass(Packages.com.tivoli.am.rba.attributes.AttributeIdentifier);

/**
 * @param username - current user's name
 * @param attributes - java.util.Map where the 'dynamic' values need to be captured by
 *                     this javascript file.
 * @param session - object containing current values visible to incoming request context
 */
function modifySessionAttributes(attributes, username, session) {

	// creates an identifier with the attribute's name, URI, datatype, and the issuer
	var riskScoreIdentifier = new AttributeIdentifier("riskScore", "urn:ibm:security:subject:riskScore",
	"Integer", "urn:ibm:security:issuer:RiskCalculator");

	// retrieve the risk score
	var riskScoreValue = session.getValue(riskScoreIdentifier);

	// set the risk score to be stored as a session attribute
	attributes.put(riskScoreIdentifier, riskScoreValue);
}

/**
 * @param username - current user's name
 * @param attributes - java.util.Map where the 'dynamic' values need to be captured
 *                     by this javascript file.
 * @param session - RBA's com.tivoli.am.rba.fingerprinting.IValueContainer object
 *                  containing current values visible to incoming request context
 */
function modifyBehaviorAttributes(attributes, username, session) {

	// store any behavior attributes here
}

What to do next

Update and deploy the dynamic.attributes.js file.

Parent topic: Dynamic attributes

Updating and deploying the dynamic.attributes.js fileUpdating and deploying the dynamic.attributes.js fileUpdating and deploying the dynamic.attributes.js fileTo implement the dynamic.attributes.js file on your appliance, update the file and then deploy the change.dynamic.attributes.js fileupdate on appliancedeployCode the dynamic.attributes.js fileAdd JavaScript code to the dynamic.attributes.js file to dynamically add attributes or modify the values of attributes. to create the customizations you require. To use a custom attribute in a policy, create the attribute. See Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes..You must set the following properties in the local management interface for the custom attribute:Specify a name for the attribute.Issuer: urn:ibm:security:issuer:AttributeSession Category: Environment Type: PolicyStorage Domain: SessionThen, you must use the attribute you created in the rule section of a policy. See Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy..Log in to the local management interface.Click Secure Access Control.Under Global Settings, click Template Files.Locate the existing dynamic.attributes.js file in the C/ac/javascript_rules directory.Select the dynamic.attributes.js file to edit or import:Click ManageEdit to update the existing file in an editing window by using copy and paste from the file you created. Click Save.Click ManageImport to import the script file you created and replace the existing file. Click Browse to select the location of the file, and click Import to replace the existing dynamic.attributes.js file.Deploy the changes.Dynamic attributesYou can capture additional context-based access information in dynamic attributes that you create or customize.

Updating and deploying the dynamic.attributes.js file

To implement the dynamic.attributes.js file on your appliance, update the file and then deploy the change.

Before you begin

Code the dynamic.attributes.js file to create the customizations you require.

To use a custom attribute in a policy, create the attribute. See Managing attributes.

You must set the following properties in the local management interface for the custom attribute:

Specify a name for the attribute.

Issuer: urn:ibm:security:issuer:AttributeSession

Category: Environment

Type: Policy

Storage Domain: Session

Then, you must use the attribute you created in the rule section of a policy. See Creating an access control policy.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Template Files.

Locate the existing dynamic.attributes.js file in the C/ac/javascript_rules directory.

Select the dynamic.attributes.js file to edit or import:

Click Manage > Edit to update the existing file in an editing window by using copy and paste from the file you created. Click Save.

Click Manage > Import to import the script file you created and replace the existing file. Click Browse to select the location of the file, and click Import to replace the existing dynamic.attributes.js file.

Deploy the changes.

Parent topic: Dynamic attributes

Custom attributes for the authorization serviceYou can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS).You can define your own attributes, called custom attributes, to specify in policies and for decision making. Update the WebSEAL configuration file with the attribute information so that the EAS can use these attributes. The WebSEAL EAS uses this attribute information to create the runtime security services request.To update the WebSEAL configuration file for custom attributes:Update the [azn-decision-info] stanza with the custom attribute information. Define the type of data and category that the attribute represents using the [user-attribute-definitions] stanza.AttributesAttributes specify the context of a request that you want to be evaluated as part of an access decision. For example, an attribute might be information in a request, such as a user name, or information in an external source, such as a user's age in a user registry or an information type in a database.[azn-decision-info] stanzaAdd extra information from the HTTP request to the authorization decision information.[user-attribute-definitions] stanzaUse the [user-attribute-definitions] stanza to modify the data type, the category, or both of a custom attribute. Setting the data type or category of a custom attributeSet the data type or category of a custom attribute that is being passed to the runtime security services. Setting the data type or category ensures that the runtime security services use the data accurately when evaluating the policy.

Custom attributes for the authorization service

You can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS).

You can define your own attributes, called custom attributes, to specify in policies and for decision making. Update the WebSEAL configuration file with the attribute information so that the EAS can use these attributes. The WebSEAL EAS uses this attribute information to create the runtime security services request.

To update the WebSEAL configuration file for custom attributes:

Update the [azn-decision-info] stanza with the custom attribute information.

Define the type of data and category that the attribute represents using the [user-attribute-definitions] stanza.

[azn-decision-info] stanza
Add extra information from the HTTP request to the authorization decision information.

[user-attribute-definitions] stanza
Use the [user-attribute-definitions] stanza to modify the data type, the category, or both of a custom attribute.

Setting the data type or category of a custom attribute
Set the data type or category of a custom attribute that is being passed to the runtime security services. Setting the data type or category ensures that the runtime security services use the data accurately when evaluating the policy.

Parent topic: Attributes

[azn-decision-info] stanza[azn-decision-info] stanzaWebSEAL azn-decision-info stanza entryAdd extra information from the HTTP request to the authorization decision information.azn-decision-info stanza entryazn-decision-info stanzaentriesazn-decision-infoazn-decision-info stanzaazn-decision-info stanza Syntax<attr_ID> = <http_info> Description This stanza defines any extra information that is available to the authorization framework when it makes authorization decisions. This extra information can be obtained from various elements of the HTTP request, namely: HTTP methodHTTP schemeHTTP cookiesRequest URIHTTP headersPOST dataClient IP address If the requested element is not in the HTTP request, no corresponding attribute is added to the authorization decision information. Options attr_IDThe identifier of the attribute that contains the HTTP information.http_infoThe source of the information. It can be one of the following values: methodschemeuriclient_ipheader:<header-name>where: <header-name>The name of the header that contains information for WebSEAL to add to the authorization decision information. For example, Host.cookie:<cookie-name>where: <cookie-name>The name of the cookie that contains information for WebSEAL to add to the authorization decision information.post-data:<values>,where the content and format of the <values> depends on the type of POST data.See WebSEAL support for POST data. WebSEAL support for POST dataWebSEAL supports two types of POST data:Normal FORM data, which is the application/x-www-form-urlencoded content-type. To add normal FORM data to the HTTP request, use the following format for this entry:post-data:<post-data-name>where the <post-data-name> is the name of the selected form data field in the request. WebSEAL adds the corresponding value for this field to the authorization decision information.JavaScript Object Notation (JSON) data, which is the application/json content-type. For more information about the JSON syntax, see http://www.json.org.To search for a key in the JSON data and add its value to the HTTP request, use the following format:post-data:/"<JSON-node-id>"[[/"<JSON-node-id>"][<JSON-array-indx>]]...where:"<JSON-node-id>"The name of a node in the JSON data. JSON data is essentially a hierarchy of name-value pairs. The forward slash character (/) that precedes each "<JSON-node-id>" identifies a level of the JSON hierarchy. You can repeatedly add [/<JSON-node-id>] elements to move through the JSON data hierarchy and identify the node that contains the value that you want WebSEAL to add to the authorization decision information.Each <JSON-node-id> must be:Enclosed in double quotation marks.Preceded by a forward slash character (/).A case-sensitive match with a node in the JSON data hierarchy.If WebSEAL does not find a matching node name in the POST data, no corresponding attribute is added to the authorization decision information. <JSON-array-indx> The contents of a node in the JSON data might be a JSON array. If you configure WebSEAL to search for a JSON node that contains an array, specify the array index of the value that you want WebSEAL to use. Use a base of 0. In other words, the first entry in the array has an index of 0. The <JSON-array-indx> is not enclosed in double quotation marks. The square brackets ([]) in this syntax indicate an optional element. Do not include square brackets in your configuration entry. Similarly, the ellipsis (...) indicates that you can repeat the optional elements that precede it. Do not include the ellipsis in your configuration entry.WebSEAL returns only node values of the following JSON types:StringNumbertrue or falsenullIf the value of the selected node is not one of the types in this list, WebSEAL does not return it as authorization decision information. Object and Array types cannot be added to the authorization decision information. Usage This stanza entry is optional. Default value None. Example 1: Standard HTTP elements HTTP_REQUEST_METHOD = method HTTP_HOST_HEADER= header:Host If these example configuration entries are set in the [azn-decision-info] stanza, WebSEAL adds the following attributes to the authorization decision information:HTTP_REQUEST_METHODContains the HTTP method.HTTP_HOST_HEADERContains the data from the Host header. Example 2: JSON POST data For this example, consider the following JSON form data:{ "userid": "jdoe", "transactionValue": "146.67", "accountBalances": { "chequing": "4345.45", "savings": "12432.23", "creditLine": "19999.12" } } The following configuration entries in the [azn-decision-info] stanza extract information from this JSON form data. USERID = post-data:/"userid" SAVINGS = post-data:/"accountBalances"/"savings" The first entry prompts WebSEAL to search for the JSON node called "userid". In this example, the value that is associated with the "userid" node is jdoe. WebSEAL adds this value to the HTTP request in an attribute called USERID. When WebSEAL processes the second entry, it searches for a top-level JSON node called "accountBalances". Under the "accountBalances" hierarchy, WebSEAL locates the "savings" JSON node. In the example data, the value that is associated with this node is 12432.23. WebSEAL adds this value to the HTTP request in an attribute called SAVINGS. WebSEAL adds the following attributes to the authorization decision information:USERIDContains the value jdoe.SAVINGSContains the value 12432.23. Example 3: JSON POST data with a JSON array value For this example, consider the following JSON form data:{ "userid": "jdoe", "transactionValue": "146.67", "accounts": [ {"name": "chequing":, "balance": "4350.45"}, {"name": "savings":, "balance": "4350.46"} ] } The following configuration entry is included in the [azn-decision-info] stanza:SAVINGSBAL = post-data:/"accounts"/1/"balance" WebSEAL processes this entry as follows: Searches for a top-level node in the JSON data called "accounts". Locates the element in position 1 of the JSON array (base 0). Searches for the "balance" name-value pair in this array element.Adds the associated value to the authorization decision information. In this example, WebSEAL adds the following attribute to the authorization decision information:SAVINGSBALContains the value 4350.46. Custom attributes for the authorization serviceYou can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS).

[azn-decision-info] stanza

Add extra information from the HTTP request to the authorization decision information.

Syntax

<attr_ID> = <http_info>

Description

This stanza defines any extra information that is available to the authorization framework when it makes authorization decisions. This extra information can be obtained from various elements of the HTTP request, namely:

HTTP method

HTTP scheme

HTTP cookies

Request URI

HTTP headers

POST data

Client IP address

If the requested element is not in the HTTP request, no corresponding attribute is added to the authorization decision information.

Options

attr_ID

The identifier of the attribute that contains the HTTP information.

http_info

The source of the information. It can be one of the following values:

method

scheme

uri

client_ip

header:<header-name>

where:

<header-name>

The name of the header that contains information for WebSEAL to add to the authorization decision information. For example, Host.

cookie:<cookie-name>

where:

<cookie-name>

The name of the cookie that contains information for WebSEAL to add to the authorization decision information.

post-data:<values>,

where the content and format of the <values> depends on the type of POST data.

See WebSEAL support for POST data.

WebSEAL support for POST data

WebSEAL supports two types of POST data:

Normal FORM data, which is the application/x-www-form-urlencoded content-type.

To add normal FORM data to the HTTP request, use the following format for this entry:

post-data:<post-data-name>

where the <post-data-name> is the name of the selected form data field in the request. WebSEAL adds the corresponding value for this field to the authorization decision information.

JavaScript Object Notation (JSON) data, which is the application/json content-type. For more information about the JSON syntax, see http://www.json.org.

To search for a key in the JSON data and add its value to the HTTP request, use the following format:

post-data:/"<JSON-node-id>"[[/"<JSON-node-id>"][<JSON-array-indx>]]...

where:

"<JSON-node-id>"

The name of a node in the JSON data.

JSON data is essentially a hierarchy of name-value pairs. The forward slash character (/) that precedes each "<JSON-node-id>" identifies a level of the JSON hierarchy. You can repeatedly add [/<JSON-node-id>] elements to move through the JSON data hierarchy and identify the node that contains the value that you want WebSEAL to add to the authorization decision information.

Each <JSON-node-id> must be:

Enclosed in double quotation marks.

Preceded by a forward slash character (/).

A case-sensitive match with a node in the JSON data hierarchy.

If WebSEAL does not find a matching node name in the POST data, no corresponding attribute is added to the authorization decision information.

<JSON-array-indx>

The contents of a node in the JSON data might be a JSON array. If you configure WebSEAL to search for a JSON node that contains an array, specify the array index of the value that you want WebSEAL to use. Use a base of 0. In other words, the first entry in the array has an index of 0.

Note: The <JSON-array-indx> is not enclosed in double quotation marks.

Usage notes:

The square brackets ([]) in this syntax indicate an optional element. Do not include square brackets in your configuration entry. Similarly, the ellipsis (...) indicates that you can repeat the optional elements that precede it. Do not include the ellipsis in your configuration entry.

WebSEAL returns only node values of the following JSON types:

String

Number

true or false

null

If the value of the selected node is not one of the types in this list, WebSEAL does not return it as authorization decision information.

Object and Array types cannot be added to the authorization decision information.

Usage

This stanza entry is optional.

Default value

None.

Example 1: Standard HTTP elements

HTTP_REQUEST_METHOD = method
HTTP_HOST_HEADER= header:Host

If these example configuration entries are set in the [azn-decision-info] stanza, WebSEAL adds the following attributes to the authorization decision information:

HTTP_REQUEST_METHOD

Contains the HTTP method.

HTTP_HOST_HEADER

Contains the data from the Host header.

Example 2: JSON POST data

For this example, consider the following JSON form data:

{ "userid": "jdoe",
  "transactionValue": "146.67",
  "accountBalances": {
        "chequing": "4345.45",
        "savings": "12432.23",
        "creditLine": "19999.12"
    }
}

The following configuration entries in the [azn-decision-info] stanza extract information from this JSON form data.

USERID = post-data:/"userid"
SAVINGS = post-data:/"accountBalances"/"savings"

The first entry prompts WebSEAL to search for the JSON node called "userid". In this example, the value that is associated with the "userid" node is jdoe. WebSEAL adds this value to the HTTP request in an attribute called USERID.

When WebSEAL processes the second entry, it searches for a top-level JSON node called "accountBalances". Under the "accountBalances" hierarchy, WebSEAL locates the "savings" JSON node. In the example data, the value that is associated with this node is 12432.23. WebSEAL adds this value to the HTTP request in an attribute called SAVINGS.

WebSEAL adds the following attributes to the authorization decision information:

USERID

Contains the value jdoe.

SAVINGS

Contains the value 12432.23.

Example 3: JSON POST data with a JSON array value

For this example, consider the following JSON form data:

{
    "userid": "jdoe",
    "transactionValue": "146.67",
    "accounts": [
        {"name": "chequing":, "balance": "4350.45"},
        {"name": "savings":, "balance": "4350.46"}
    ]
}

The following configuration entry is included in the [azn-decision-info] stanza:

SAVINGSBAL = post-data:/"accounts"/1/"balance"

WebSEAL processes this entry as follows:

Searches for a top-level node in the JSON data called "accounts".

Locates the element in position 1 of the JSON array (base 0).

Searches for the "balance" name-value pair in this array element.

Adds the associated value to the authorization decision information.

In this example, WebSEAL adds the following attribute to the authorization decision information:

SAVINGSBAL

Contains the value 4350.46.

Parent topic: Custom attributes for the authorization service

[user-attribute-definitions] stanza[user-attribute-definitions] stanzaWebSEAL user-attribute-definitions stanzaUse the [user-attribute-definitions] stanza to modify the data type, the category, or both of a custom attribute. user-attribute-definitions stanzadata typecategorydata typeuser-attribute-definitions stanzacategoryuser-attribute-definitions stanzaattributesdata typecategorycustom attributesmodify categorymodify data type Syntax attr_ID.datatype = data_type attr_ID.category = category_name Description Use the appropriate stanza entry syntax depending on if you want to set the data type or category of a custom attribute from the default values. Options attr_IDSpecify the attribute identifier for which you want to set the data type or category. The attribute ID must match the name that exists in the [azn-decision-info] stanza entry.datatype data_typeSet the data type of an attribute from the default of string to a specified data_type. Your choices are: stringbooleanintegerdoubletimedatex500namecategory category_nameSet the category of an attribute from the default of Environment to a specified category_name. Your choices are:EnvironmentSubjectActionResource Usage This stanza entry is not required. Default value The default value for data type is string. The default value for category is Environment. Example: Updating the data type for JSON data If you defined a custom attribute in the [azn-decision-info] stanza as: urn:example:company:txn:value = post-data:/"accountBalances"/"savings" Then, you can set the data type of urn:example:company:txn:value to double by using the following stanza and entry: [user-attribute-definitions] urn:example:company:txn:value.datatype = double Example: Updating the category for form data If you defined a custom attribute in the [azn-decision-info] stanza as: urn:example:company:txn:userid = post-data:userid Then, you can set the category of urn:example:company:txn:userid to Subject by using the following stanza and entry: [user-attribute-definitions] urn:example:company:txn:userid.category = Subject Custom attributes for the authorization serviceYou can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS).

[user-attribute-definitions] stanza

Use the [user-attribute-definitions] stanza to modify the data type, the category, or both of a custom attribute.

Syntax

attr_ID.datatype = data_type
attr_ID.category = category_name

Description

Use the appropriate stanza entry syntax depending on if you want to set the data type or category of a custom attribute from the default values.

Options

attr_ID

Specify the attribute identifier for which you want to set the data type or category. The attribute ID must match the name that exists in the [azn-decision-info] stanza entry.

datatype data_type

Set the data type of an attribute from the default of string to a specified data_type. Your choices are:

string

boolean

integer

double

time

date

x500name

category category_name

Set the category of an attribute from the default of Environment to a specified category_name. Your choices are:

Environment

Subject

Action

Resource

Usage

This stanza entry is not required.

Default value

The default value for data type is string.

The default value for category is Environment.

Example: Updating the data type for JSON data

If you defined a custom attribute in the [azn-decision-info] stanza as:

urn:example:company:txn:value = post-data:/"accountBalances"/"savings"

Then, you can set the data type of urn:example:company:txn:value to double by using the following stanza and entry:

[user-attribute-definitions]
urn:example:company:txn:value.datatype = double

Example: Updating the category for form data

If you defined a custom attribute in the [azn-decision-info] stanza as:

urn:example:company:txn:userid = post-data:userid

Then, you can set the category of urn:example:company:txn:userid to Subject by using the following stanza and entry:

[user-attribute-definitions]
urn:example:company:txn:userid.category = Subject

Parent topic: Custom attributes for the authorization service

Setting the data type or category of a custom attributeSetting the data type or category of a custom attributeSetting the data type or category of a custom attributeSet the data type or category of a custom attribute that is being passed to the runtime security services. Setting the data type or category ensures that the runtime security services use the data accurately when evaluating the policy.attribute IDsWebSEAL configurationWebSEAL configuration fileset data typeset categoryEASset data typeset categorycategoryset for attributedata typeset for attributeuser-attribute-definitionsset typeset category The default data type of an attribute is string. The default category of an attribute is Environment. Use the following procedure to change the type and the category. Open the WebSEAL configuration file. Create one or more entries in the [azn-decision-info] stanza for custom attributes, if they do not already exist.Set the data type or category of a custom attribute by using the [user-attribute-definitions] stanza and entry. Add the stanza if it does not already exist. data typeDefine the data type by using the following syntax:[user-attribute-definitions] attr_ID.datatype = data_typecategoryDefine the category by using the following syntax:[user-attribute-definitions] attr_ID.category = category_name The value you use for attr_ID must match the attribute identifier you defined in the [azn-decision-info] stanza. See [user-attribute-definitions] stanzaUse the [user-attribute-definitions] stanza to modify the data type, the category, or both of a custom attribute. for the list of values you can use for data type and category. Save the file.Restart the WebSEAL server for the changes to take effect.[user-attribute-definitions] stanzaUse the [user-attribute-definitions] stanza to modify the data type, the category, or both of a custom attribute. [azn-decision-info] stanzaAdd extra information from the HTTP request to the authorization decision information.Custom attributes for the authorization serviceYou can modify the [azn-decision-info] stanza of the WebSEAL configuration file to make other data available to the external authorization service (EAS).

Setting the data type or category of a custom attribute

Set the data type or category of a custom attribute that is being passed to the runtime security services. Setting the data type or category ensures that the runtime security services use the data accurately when evaluating the policy.

About this task

The default data type of an attribute is string. The default category of an attribute is Environment. Use the following procedure to change the type and the category.

Procedure

Open the WebSEAL configuration file.

Optional: Create one or more entries in the [azn-decision-info] stanza for custom attributes, if they do not already exist.

Set the data type or category of a custom attribute by using the [user-attribute-definitions] stanza and entry. Add the stanza if it does not already exist.

data type

Define the data type by using the following syntax:

[user-attribute-definitions]
attr_ID.datatype = data_type

category

Define the category by using the following syntax:

[user-attribute-definitions]
attr_ID.category = category_name

The value you use for attr_ID must match the attribute identifier you defined in the [azn-decision-info] stanza.

See [user-attribute-definitions] stanza for the list of values you can use for data type and category.

Save the file.

Restart the WebSEAL server for the changes to take effect.

Parent topic: Custom attributes for the authorization service

Related reference:

[user-attribute-definitions] stanza

[azn-decision-info] stanza

Attribute collection serviceAttribute collection serviceAttribute collection serviceThe attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score.attribute collection servicerequest typesPOSTattribute collection servicerequest typesDELETEattribute collection servicerequest typesGETattribute collection serviceJavaScript functionssendSession()attribute collection serviceJavaScript functionsdeleteSession()attribute collection serviceJavaScript functionsgetLocation()attribute collection servicedefinitionattribute collection servicesession attributessession attributesattribute collection servicesession attributesweb browser attributessession attributeslocation attributesRepresentational State Transfer (REST) serviceattribute collection serviceweb browser attributesattribute collection servicelocation attributesattribute collection serviceProcess overviewThe following process describes the attribute collection service and how to use it:Make REST calls to store and delete attributes in the database. The initial request to the service receives a correlation ID. The correlation ID is used to make further REST calls.Use JavaScript to collect the web browser attributes. You can place the HTML page that calls the JavaScript functions on any server.Ajax collects information in the background. It does not slow down page loading.You can make standard Ajax requests only to the same domain. With Cross Origin Resource Sharing (CORS), you can make Ajax requests across domains.The CORS response header contains the settings for the following specifications: The server from which requests are accepted.The types of requests that are accepted.Attributes that are configured as session attributes are collected automatically by the info.js file for risk score calculation.Request typesGET and POST requests create a correlation ID to identify the session in the database. A correlation ID is a UUID that is stored in a cookie. The attribute collection service process uses the following request types:GETRetrieves information about an attribute session from the database. GET requests are disabled by default. Requests use a URL with a REST path, such as: https://webseal/mga/sps/ac/rest/UUID.POSTCreates an attribute session in the database. POST requests use a URL such as https://webseal/mga/sps/ac/UUID. The session attributes are sent as a JSON string with the request. In a response, the server sets a cookie that contains the correlation ID. For example, the POST /sps/ac/9d37e806-24cf-4398-a3b9-d7f13fb2231f request creates a session in the database with a UUID of 9d37e806-24cf-4398-a3b9-d7f13fb2231f.You can also configure the risk-based access properties to use an existing cookieDELETEDeletes an attribute session from the database.Risk-based access runtime propertiesUse the local management interface to configure the risk-based access properties that are required for attribute collection service.The following properties specify information about the attribute collection service: attributeCollection.cookieNameCorrelation ID used by the attribute collector.Data type: StringExample:ac.uuidattributeCollection.requestServerRequest server for attribute collector. A list of the allowable hosts where the ajaxRequest can be sent from.Data type: String ListExample:https://rbademo.example.com,https://rbaemo2.example.comattributeCollection.serviceLocationLocation of the attribute collector.Data type: String ListExample:http://rbademo.example.com/mgaattributeCollection.sessionTimeoutNumber of seconds in which sessions stored in context-based access will automatically expire, unless updated. If any attribute in the session is updated, the session expiry is extended by the specified number of seconds configured in this property. The default is 3600 seconds.Data type: IntegerExample:3600 secondsattributeCollection.enableGetAttributesEnables the REST GET method to return attributes.Data type: BooleanExample:FalseattributeCollection.getAttributesAllowedClientsA comma-separated list of clients that are allowed to access the ACS REST GET method.If this property is not set and attributeCollection.enableGetAttributes is set to true, anyone can access the GET method. If this property is set but attributeCollection.enableGetAttributes is set to false, this property is ignored.Data type: String ListExample:hostname1, hostname2attributeCollection.hashAlgorithmThe algorithm that is used to create the hash.Data type: StringExample:SHA256attributeCollection.attributesHashEnabledA comma-separated list of attribute URI values that have been configured for hashing.Data type: String ListExample:urn:ibm:security:environment:http:userAgent, urn:ibm:security:environment:deviceFonts, urn:ibm:security:environment:browserPlugins attributeCollection.authenticationContextAttributesComma-separated lists of attribute names to be collected when performing an authentication service obligation.Data type: String ListExample:authenticationLevel, http:host JavaScript functionsUse the JavaScript functions in the C/ac/info.js file to make requests to the server. Include the info.js JavaScript file in the HTML landing page of your application. When info.js is loaded, it calls the following functions:sendSession()Makes a POST request to the delegate service.The sendSession() function collects the web browser attributes and sends them to the server. They are stored in the database. Call this function when a user logs in.deleteSession()Makes a DELETE request for a specified correlation ID. The POST request from the sendSession() returns a correlation ID. Based on the correlation ID, the deleteSession() function deletes the attributes from the database. Call this function when the user logs out or when the current session times out.getLocation()Detects the location of the device from which the requests are made. If the location information is sent to the server, call the getLocation() function before the sendSession() function. The following web browsers support the detection of location: Mozilla Firefox, Google Chrome, Opera, Apple Safari, and Microsoft Internet Explorer 9 and 10.For the JavaScript functions to work in Microsoft Internet Explorer, include the following statement in the HTML page from which you call the function. The following statement forces Microsoft Internet Explorer to use the standards mode:<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"  "http://www.w3.org/TR/html4/loose.dtd">For configuration steps and examples, see Configuring the attribute collection serviceBefore you can collect risk calculation information, you must specify the server and location of the collection service. You also must specify a JavaScript file to collect the session attributes..Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Configuring the attribute collection serviceBefore you can collect risk calculation information, you must specify the server and location of the collection service. You also must specify a JavaScript file to collect the session attributes.Configuring the REST service to GET session and behavior attributesThe client can use REST services in the attribute collection service to GET session and behavior attributes.Viewing the JSON for behavior and session attributesThe administrator can view the JSON for behavior and session attributes for diagnostic purposes.

Attribute collection service

The attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score.

Process overview

The following process describes the attribute collection service and how to use it:

Make REST calls to store and delete attributes in the database. The initial request to the service receives a correlation ID. The correlation ID is used to make further REST calls.

Use JavaScript to collect the web browser attributes. You can place the HTML page that calls the JavaScript functions on any server.

Ajax collects information in the background. It does not slow down page loading.

You can make standard Ajax requests only to the same domain. With Cross Origin Resource Sharing (CORS), you can make Ajax requests across domains.

The CORS response header contains the settings for the following specifications:

The server from which requests are accepted.

The types of requests that are accepted.

Attributes that are configured as session attributes are collected automatically by the info.js file for risk score calculation.

Request types

GET and POST requests create a correlation ID to identify the session in the database. A correlation ID is a UUID that is stored in a cookie. The attribute collection service process uses the following request types:

GET

Retrieves information about an attribute session from the database. GET requests are disabled by default. Requests use a URL with a REST path, such as: https://webseal/mga/sps/ac/rest/UUID.

POST

Creates an attribute session in the database. POST requests use a URL such as https://webseal/mga/sps/ac/UUID.

The session attributes are sent as a JSON string with the request. In a response, the server sets a cookie that contains the correlation ID. For example, the POST /sps/ac/9d37e806-24cf-4398-a3b9-d7f13fb2231f request creates a session in the database with a UUID of 9d37e806-24cf-4398-a3b9-d7f13fb2231f.

You can also configure the risk-based access properties to use an existing cookie

DELETE

Deletes an attribute session from the database.

Risk-based access runtime properties

Use the local management interface to configure the risk-based access properties that are required for attribute collection service.

The following properties specify information about the attribute collection service:

attributeCollection.cookieName

Correlation ID used by the attribute collector.

Data type: String

Example:

ac.uuid

attributeCollection.requestServer

Request server for attribute collector. A list of the allowable hosts where the ajaxRequest can be sent from.

Data type: String List

Example:

https://rbademo.example.com,https://rbaemo2.example.com

attributeCollection.serviceLocation

Location of the attribute collector.

Data type: String List

Example:

http://rbademo.example.com/mga

attributeCollection.sessionTimeout

Number of seconds in which sessions stored in context-based access will automatically expire, unless updated. If any attribute in the session is updated, the session expiry is extended by the specified number of seconds configured in this property. The default is 3600 seconds.

Data type: Integer

Example:

3600 seconds

attributeCollection.enableGetAttributes

Enables the REST GET method to return attributes.

Data type: Boolean

Example:

False

attributeCollection.getAttributesAllowedClients

A comma-separated list of clients that are allowed to access the ACS REST GET method.

If this property is not set and attributeCollection.enableGetAttributes is set to true, anyone can access the GET method. If this property is set but attributeCollection.enableGetAttributes is set to false, this property is ignored.

Data type: String List

Example:

hostname1, hostname2

attributeCollection.hashAlgorithm

The algorithm that is used to create the hash.

Data type: String

Example:

SHA256

attributeCollection.attributesHashEnabled

A comma-separated list of attribute URI values that have been configured for hashing.

Data type: String List

Example:

urn:ibm:security:environment:http:userAgent,
urn:ibm:security:environment:deviceFonts,
urn:ibm:security:environment:browserPlugins

attributeCollection.authenticationContextAttributes

Comma-separated lists of attribute names to be collected when performing an authentication service obligation.

Data type: String List

Example:

authenticationLevel, http:host

JavaScript functions

Use the JavaScript functions in the C/ac/info.js file to make requests to the server. Include the info.js JavaScript file in the HTML landing page of your application. When info.js is loaded, it calls the following functions:

sendSession()

Makes a POST request to the delegate service.

The sendSession() function collects the web browser attributes and sends them to the server. They are stored in the database. Call this function when a user logs in.

deleteSession()

Makes a DELETE request for a specified correlation ID.

The POST request from the sendSession() returns a correlation ID. Based on the correlation ID, the deleteSession() function deletes the attributes from the database. Call this function when the user logs out or when the current session times out.

getLocation()

Detects the location of the device from which the requests are made. If the location information is sent to the server, call the getLocation() function before the sendSession() function. The following web browsers support the detection of location: Mozilla Firefox, Google Chrome, Opera, Apple Safari, and Microsoft Internet Explorer 9 and 10.

Note: For the JavaScript functions to work in Microsoft Internet Explorer, include the following statement in the HTML page from which you call the function. The following statement forces Microsoft Internet Explorer to use the standards mode:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
     "http://www.w3.org/TR/html4/loose.dtd">

For configuration steps and examples, see Configuring the attribute collection service.

Configuring the attribute collection service
Before you can collect risk calculation information, you must specify the server and location of the collection service. You also must specify a JavaScript file to collect the session attributes.

Configuring the REST service to GET session and behavior attributes
The client can use REST services in the attribute collection service to GET session and behavior attributes.

Viewing the JSON for behavior and session attributes
The administrator can view the JSON for behavior and session attributes for diagnostic purposes.

Parent topic: Advanced Access Control administration

Configuring the attribute collection serviceConfiguring the attribute collection serviceConfiguring the attribute collection serviceBefore you can collect risk calculation information, you must specify the server and location of the collection service. You also must specify a JavaScript file to collect the session attributes.attribute collection serviceconfigurationapplication login pageattribute collection serviceconfigurationJavaScript functionsattribute collection serviceconfigurationsession attributesconfigurationattribute collection serviceconfigurationapplication login pagesession attributesattribute collection serviceRun the isamcfg tool to configure the runtime security services EAS. See Using the isamcfg toolVarious features of Advanced Access Control can be configured with the isamcfg tool..Review Attribute collection serviceThe attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score..Configure the context-based access properties that you require for the attribute collection service. These properties are set by the isamcfg tool, but if you need to change them, use the following instructions:Configure attributeCollection.requestServer to specify the server from which requests are received using the local management interface:Select Secure Access ControlGlobal SettingsAdvanced ConfigurationFind the attributeCollection.requestServer key in the list and click the edit icon. A new window displays the name and the current value.Edit the value of the request servers. The value is a space-separated list of WebSEAL host names from which requests are permitted. Host names musts begin with http:// or https://. For example, type http://mywebsealhost.company.com.Configure attributeCollection.serviceLocation to specify the location using the local management interface:Select Secure Access ControlGlobal SettingsAdvanced ConfigurationFind the attributeCollection.serviceLocation key in the list and click the edit icon. A new window displays the name and the current value.Edit the value of the location. Specify the location as: https://host_name/webseal-junction-nameFor example, type https://mywebsealhost.company.com/mga.You can configure any other attribute collection service attributes in a similar fashion, as necessary. Add the URL of info.js to the <head> block in the HTML landing page of your application. The info.js file calls functions that are required to collect session attributes. Follow this format:<script src="https://host_name/webseal-junction-name/sps/ac/js/info.js"></script> When the info.js file is included on an HTML page, attribute collection by Ajax calls can take time to complete. To avoid issues, attribute collection must end before moving away from the page. For example, if the attribute collection is still running, and a link is clicked, the policy fails to resolve session attributes. To prevent this issue, modify the JavaScript file to prevent the user from continuing until after the Ajax call completes. The basic configuration of the attribute collection service for context-based access is complete. Attribute collection serviceThe attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score.

Configuring the attribute collection service

Before you can collect risk calculation information, you must specify the server and location of the collection service. You also must specify a JavaScript file to collect the session attributes.

Before you begin

Run the isamcfg tool to configure the runtime security services EAS. See Using the isamcfg tool.

Review Attribute collection service.

Procedure

Optional: Configure the context-based access properties that you require for the attribute collection service. These properties are set by the isamcfg tool, but if you need to change them, use the following instructions:

Configure attributeCollection.requestServer to specify the server from which requests are received using the local management interface:

Select Secure Access Control > Global Settings > Advanced Configuration

Find the attributeCollection.requestServer key in the list and click the edit icon. A new window displays the name and the current value.

Edit the value of the request servers. The value is a space-separated list of WebSEAL host names from which requests are permitted. Host names musts begin with http:// or https://. For example, type http://mywebsealhost.company.com.

Configure attributeCollection.serviceLocation to specify the location using the local management interface:

Select Secure Access Control > Global Settings > Advanced Configuration

Find the attributeCollection.serviceLocation key in the list and click the edit icon. A new window displays the name and the current value.

Edit the value of the location. Specify the location as:

https://host_name/webseal-junction-name

For example, type https://mywebsealhost.company.com/mga.

You can configure any other attribute collection service attributes in a similar fashion, as necessary.

Add the URL of info.js to the <head> block in the HTML landing page of your application. The info.js file calls functions that are required to collect session attributes. Follow this format:

<script src="https://host_name/webseal-junction-name/sps/ac/js/info.js"></script>

Note: When the info.js file is included on an HTML page, attribute collection by Ajax calls can take time to complete. To avoid issues, attribute collection must end before moving away from the page. For example, if the attribute collection is still running, and a link is clicked, the policy fails to resolve session attributes. To prevent this issue, modify the JavaScript file to prevent the user from continuing until after the Ajax call completes.

Results

The basic configuration of the attribute collection service for context-based access is complete.

Parent topic: Attribute collection service

Configuring the REST service to GET session and behavior attributes Configuring the REST service to GET session and behavior attributes Configuring the REST service to GET session and behavior attributes The client can use REST services in the attribute collection service to GET session and behavior attributes.REST service configure session attributesbehavior attributessession attributesconfigure the REST service behavior attributesconfigure the REST service An administrator must enable the attributeCollection.enableGetAttributes property before using the REST services capability. If you do not enable this property, the following error message is returned when the attribute collection service or the client attempts to GET behavior or session attributes:FBTRBA079E The attribute collection service GET method is not enabled. The GET method is not enabled by default. To enable specific clients to GET attributes from the attribute collection service, you must add their corresponding host names to the attributeCollection.getAttributesAllowedClients property. If the administrator does not set this property, any client can GET attributes from the attribute collection service.Log in to the local management interface.Click Secure Access Control. Under Global Settings, click Advanced Configuration.Enable the attributeCollection.enableGetAttributes property. Attribute collection serviceThe attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score.

Configuring the REST service to GET session and behavior attributes

The client can use REST services in the attribute collection service to GET session and behavior attributes.

About this task

An administrator must enable the attributeCollection.enableGetAttributes property before using the REST services capability. If you do not enable this property, the following error message is returned when the attribute collection service or the client attempts to GET behavior or session attributes:

FBTRBA079E The attribute collection service GET method is not enabled.

The GET method is not enabled by default. To enable specific clients to GET attributes from the attribute collection service, you must add their corresponding host names to the attributeCollection.getAttributesAllowedClients property. If the administrator does not set this property, any client can GET attributes from the attribute collection service.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Advanced Configuration.

Enable the attributeCollection.enableGetAttributes property.

Parent topic: Attribute collection service

Viewing the JSON for behavior and session attributesViewing the JSON for behavior and session attributesViewing the JSON for behavior and session attributesThe administrator can view the JSON for behavior and session attributes for diagnostic purposes.JSON for attributes viewingYou can view the JSON for registered behavior or session attributes.Open a browser.View the information for your registered attributes by entering one of the following URLs: Attribute typeURLExample informationBehaviorhttps://hostname/mga/sps/ac/rest/behavior [ { "time":1399431163540, "attributes":[ {"urn:ibm:security:environment:geoLocation":"30.402806599999998,-97.714635,45"}, {"urn:ibm:security:environment:accessTime":"2014-05-07T02:52:43Z"} ] }, { "time":1399431202147, "attributes":[ {"urn:ibm:security:environment:geoLocation":"30.4028181,-97.7146326,44"}, {"urn:ibm:security:environment:accessTime":"2014-05-07T02:53:22Z"} ] } ] Sessionhttps://hostname/mga/sps/ac/rest/session { "urn:ibm:security:subject:riskScore":"0", "urn:ibm:security:environment:devicePlatform":"Linuxx86_64", "urn:ibm:security:environment:screenAvailableWidth":"1920", "urn:ibm:security:environment:browserPlugins":"Shockwave Flash", "urn:ibm:security:environment:geoRegionCode":"", "urn:ibm:security:environment:screenHeight":"1080", "urn:ibm:security:environment:deviceLanguage":"en-US", "urn:ibm:security:environment:colorDepth":"24", "urn:ibm:security:environment:screenWidth":"1920", "urn:ibm:security:environment:geoLocation":"30.4029283,-97.7147197,49", "urn:ibm:security:environment:screenAvailableHeight":"1025" } Attribute collection serviceThe attribute collection service is a Representational State Transfer (REST) service. It can collect web browser and location information from the user for calculating the risk score.

Viewing the JSON for behavior and session attributes

The administrator can view the JSON for behavior and session attributes for diagnostic purposes.

About this task

You can view the JSON for registered behavior or session attributes.

Procedure

Open a browser.

View the information for your registered attributes by entering one of the following URLs:

Attribute type
URL
Example information

Behavior
https://hostname/mga/sps/ac/rest/behavior

[
  {
    "time":1399431163540,
    "attributes":[
      {"urn:ibm:security:environment:geoLocation":"30.402806599999998,-97.714635,45"},
      {"urn:ibm:security:environment:accessTime":"2014-05-07T02:52:43Z"}
     ]
  },
  {
    "time":1399431202147,
    "attributes":[
      {"urn:ibm:security:environment:geoLocation":"30.4028181,-97.7146326,44"},
      {"urn:ibm:security:environment:accessTime":"2014-05-07T02:53:22Z"}
    ]
  }
]

Session
https://hostname/mga/sps/ac/rest/session

{
  "urn:ibm:security:subject:riskScore":"0",
  "urn:ibm:security:environment:devicePlatform":"Linuxx86_64",
   "urn:ibm:security:environment:screenAvailableWidth":"1920",
  "urn:ibm:security:environment:browserPlugins":"Shockwave Flash",
   "urn:ibm:security:environment:geoRegionCode":"",
  "urn:ibm:security:environment:screenHeight":"1080",
  "urn:ibm:security:environment:deviceLanguage":"en-US",
  "urn:ibm:security:environment:colorDepth":"24",
  "urn:ibm:security:environment:screenWidth":"1920",
  "urn:ibm:security:environment:geoLocation":"30.4029283,-97.7147197,49",
  "urn:ibm:security:environment:screenAvailableHeight":"1025"
}

Parent topic: Attribute collection service

Attribute matchersAttribute matchersAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.attribute matchersdefinitionattribute matchersexact matcherattribute comparisonIn some scenarios, multiple attributes or a set of composite attributes must be matched. For example, longitude, latitude, and accuracy are three attributes that are related to location. In a given scenario, two device fingerprints are considered a match if the distance between two location points is not greater than a specified threshold value. In this scenario, the comparison of only the longitude attribute does not provide accurate results. The matcher must do a more complex comparison or composite matching, where it matches multiple attributes from both fingerprints.The matcher returns one of the following results after it compares the attributes values in the registered device fingerprint and the incoming device fingerprint:MatchedThe decision that the matcher returns if the attribute value in the registered device fingerprint and the incoming device fingerprint value are the same or considered equivalent.MismatchedThe decision that the matcher returns if the attribute value in the registered device fingerprint and the incoming device fingerprint value are not the same or considered equivalent.IndeterminateThe decision that the matcher returns if it cannot gather enough attribute information to determine a result. When the matcher returns Indeterminate as the result, the risk engine does not use the attribute in risk score calculations.A mismatch increases the risk score that is based on the assigned weight of the attributes.The matcher might not be used in the risk calculation in the following situations:The incoming device fingerprint does not contain the required attributes.The historical data is not available for a matcher to make a match or mismatch decision.Risk-based access provides ready-to-use attribute matchers that compare composite attributes or analyze a range of attribute values. You can configure one or more of the attribute matchers that are described in the following sections.Exact match matcherThe exact_match matcher checks whether the values of an attribute in a registered device and an incoming request exactly equal each other. Use this matcher if the more specialized matchers are not appropriate for the attribute.IP address matcherThe IP address matcher (ipaddr_matcher) compares the IP address of a request with:A trusted list (inclusion list) of IP addressesAn untrusted list (exclusion list) of IP addressesThe historical IP addresses of the deviceThe IP reputation of the deviceThe IP address matcher has the following properties: Trusted addresses IPV4 addressesIP and Netmask: Specifies the IP address and its netmask to include. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered.IPV6 addressesIP and Prefix: Specifies the IP address and its prefix to include. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered. Untrusted addresses IPV4 addressesIP and Netmask: Specifies the IP address and its netmask to exclude. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered. IPV6 addressesIP and Prefix: Specifies the IP address and its prefix to exclude. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered. The IP address matcher returns one of the following decisions after it compares the incoming IP address with the IP address that belongs to the registered device:MISMATCHEDThe decision that the matcher returns if either of the following conditions are true: The incoming IP address is in the list of untrusted IP addresses.The incoming IP address is not in the list of trusted IP addresses, and the IP address has a reputation other than Dynamic IPs. MATCHEDThe decision that the matcher returns if the matcher finds the incoming IP address in the list of trusted IP addresses.INDETERMINATEThe decision that the matcher returns if the following conditions are true: The IP address is not in the list of untrusted IP addresses.The IP address is not in the list of trusted IP addresses.The IP address qualifies for one of the following conditions: Does not have a reputation.Has a Dynamic IPs reputation.PIP matcherThe policy information point (PIP) matcher (pip_matcher) uses the value of a single-valued attribute to determine one of the following results: MatchedThe value of the attribute is MATCHED.MismatchedThe value of the attribute is MISMATCHED.IndeterminateThe value of the attribute is INDETERMINATE.The PIP matcher supports only single-valued attributes with String data types. Write and configure a JavaScript PIP with the following capabilities if you prefer to use the PIP matcher: The PIP determines attribute values.The PIP compares attribute values.The PIP returns match decisions that are based on the values of attributes that it compares.Location matcherThe location matcher (location_matcher) checks whether the location of a device is within a specific distance from the previous known locations of the device. Configure the location matcher properties to specify the accuracy range and how to compare the location information.The retrieval of location attributes depends on the web browser and the settings that the user specifies in the web browser. The web browser must support the Geolocation API. An error might occur in some web browsers if a user tries to access a protected resource from a device with a wired internet connection.The location-based analysis processes all three location attributes (longitude, latitude, and accuracy) collectively when it determines the match for the location. Though weights are assigned to all three attributes, the weight for only the longitude attribute is considered. The weights that are assigned to the supporting latitude and accuracy attributes are ignored.The location matcher has two properties:ComparisonIndicates how you want the attribute matcher to calculate the accuracy range of the location coordinates. The following figure illustrates the closest points, midpoints, and farthest points of the accuracy ranges of two locations. In this figure, the circle represents the accuracy range and the center of the circle represents the location.The closest points, midpoints, and farthest points on the accuracy ranges of two locationsThe closest points, midpoints, and farthest points on the accuracy ranges of two locations.Set the Comparison property to one of the following values:Specify the value as closest to calculate the distance between the closest points on the accuracy range of two locations. This calculation is the most restrictive calculation.Specify the value as midpoint to calculate the distance between the midpoints of the circles without considering accuracy.Specify the value as farthest to calculate the distance between the farthest points on the accuracy ranges of the two locations. This calculation is the least restrictive calculation.DistanceThe maximum distance between the new location and the historic locations. The unit of the numeric value is in kilometers. The default value is 40.Login time matcherThe login time matcher (login_time_matcher) compares and analyzes the historical login time data of the user with the current login time of the user. You must configure the attributes and properties that are required for login time analysis. The login time matcher primarily detects the logins per session. The first of the several access times that are captured within the session is considered the login time of the user. The result of the analysis determines the probability of a fraudulent user.The login time matcher has one property: ThresholdIndicates the probability that a user might log in at a particular time. Valid values are 0 to 1. The default value is .3. This default value indicates the probability that the user logs in approximately within an hour of the previous login times. If you set a lower value, the odds of the matcher returning true are higher and the risk score is lower. If you set a higher value, the odds of the matcher returning true are lower and risk score is higher. For example, if you set a value of 0.5, the matcher almost always returns false. The login time analysis collects data for eight login times before it provides input for risk score calculation. IP reputationThe IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.Modifying attribute matchersAttribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.IP reputationThe IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.Modifying attribute matchersAttribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.

Attribute matchers

An attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.

In some scenarios, multiple attributes or a set of composite attributes must be matched. For example, longitude, latitude, and accuracy are three attributes that are related to location. In a given scenario, two device fingerprints are considered a match if the distance between two location points is not greater than a specified threshold value. In this scenario, the comparison of only the longitude attribute does not provide accurate results. The matcher must do a more complex comparison or composite matching, where it matches multiple attributes from both fingerprints.

The matcher returns one of the following results after it compares the attributes values in the registered device fingerprint and the incoming device fingerprint:

Matched

The decision that the matcher returns if the attribute value in the registered device fingerprint and the incoming device fingerprint value are the same or considered equivalent.

Mismatched

The decision that the matcher returns if the attribute value in the registered device fingerprint and the incoming device fingerprint value are not the same or considered equivalent.

Indeterminate

The decision that the matcher returns if it cannot gather enough attribute information to determine a result.

Note: When the matcher returns Indeterminate as the result, the risk engine does not use the attribute in risk score calculations.

A mismatch increases the risk score that is based on the assigned weight of the attributes.

The matcher might not be used in the risk calculation in the following situations:

The incoming device fingerprint does not contain the required attributes.

The historical data is not available for a matcher to make a match or mismatch decision.

Risk-based access provides ready-to-use attribute matchers that compare composite attributes or analyze a range of attribute values. You can configure one or more of the attribute matchers that are described in the following sections.

Exact match matcher

The exact_match matcher checks whether the values of an attribute in a registered device and an incoming request exactly equal each other. Use this matcher if the more specialized matchers are not appropriate for the attribute.

IP address matcher

The IP address matcher (ipaddr_matcher) compares the IP address of a request with:

A trusted list (inclusion list) of IP addresses

An untrusted list (exclusion list) of IP addresses

The historical IP addresses of the device

The IP reputation of the device

The IP address matcher has the following properties:

Trusted addresses

IPV4 addresses

IP and Netmask: Specifies the IP address and its netmask to include. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered.

IPV6 addresses

IP and Prefix: Specifies the IP address and its prefix to include. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered.

Untrusted addresses

IPV4 addresses

IP and Netmask: Specifies the IP address and its netmask to exclude. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered.

IPV6 addresses

IP and Prefix: Specifies the IP address and its prefix to exclude. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered.

The IP address matcher returns one of the following decisions after it compares the incoming IP address with the IP address that belongs to the registered device:

MISMATCHED

The decision that the matcher returns if either of the following conditions are true:

The incoming IP address is in the list of untrusted IP addresses.

The incoming IP address is not in the list of trusted IP addresses, and the IP address has a reputation other than Dynamic IPs.

MATCHED

The decision that the matcher returns if the matcher finds the incoming IP address in the list of trusted IP addresses.

INDETERMINATE

The decision that the matcher returns if the following conditions are true:

The IP address is not in the list of untrusted IP addresses.

The IP address is not in the list of trusted IP addresses.

The IP address qualifies for one of the following conditions:

Does not have a reputation.

Has a Dynamic IPs reputation.

PIP matcher

The policy information point (PIP) matcher (pip_matcher) uses the value of a single-valued attribute to determine one of the following results:

Matched

The value of the attribute is MATCHED.

Mismatched

The value of the attribute is MISMATCHED.

Indeterminate

The value of the attribute is INDETERMINATE.

Note: The PIP matcher supports only single-valued attributes with String data types.

Write and configure a JavaScript PIP with the following capabilities if you prefer to use the PIP matcher:

The PIP determines attribute values.

The PIP compares attribute values.

The PIP returns match decisions that are based on the values of attributes that it compares.

Location matcher

The location matcher (location_matcher) checks whether the location of a device is within a specific distance from the previous known locations of the device. Configure the location matcher properties to specify the accuracy range and how to compare the location information.

Limitation: The retrieval of location attributes depends on the web browser and the settings that the user specifies in the web browser. The web browser must support the Geolocation API. An error might occur in some web browsers if a user tries to access a protected resource from a device with a wired internet connection.

The location-based analysis processes all three location attributes (longitude, latitude, and accuracy) collectively when it determines the match for the location. Though weights are assigned to all three attributes, the weight for only the longitude attribute is considered. The weights that are assigned to the supporting latitude and accuracy attributes are ignored.

The location matcher has two properties:

Comparison

Indicates how you want the attribute matcher to calculate the accuracy range of the location coordinates.

The following figure illustrates the closest points, midpoints, and farthest points of the accuracy ranges of two locations. In this figure, the circle represents the accuracy range and the center of the circle represents the location.

Figure 91. The closest points, midpoints, and farthest points on the accuracy ranges of two locations

Set the Comparison property to one of the following values:

Specify the value as closest to calculate the distance between the closest points on the accuracy range of two locations. This calculation is the most restrictive calculation.

Specify the value as midpoint to calculate the distance between the midpoints of the circles without considering accuracy.

Specify the value as farthest to calculate the distance between the farthest points on the accuracy ranges of the two locations. This calculation is the least restrictive calculation.

Distance

The maximum distance between the new location and the historic locations. The unit of the numeric value is in kilometers. The default value is 40.

Login time matcher

The login time matcher (login_time_matcher) compares and analyzes the historical login time data of the user with the current login time of the user. You must configure the attributes and properties that are required for login time analysis. The login time matcher primarily detects the logins per session. The first of the several access times that are captured within the session is considered the login time of the user. The result of the analysis determines the probability of a fraudulent user.

The login time matcher has one property:

Threshold

Indicates the probability that a user might log in at a particular time. Valid values are 0 to 1. The default value is .3. This default value indicates the probability that the user logs in approximately within an hour of the previous login times. If you set a lower value, the odds of the matcher returning true are higher and the risk score is lower. If you set a higher value, the odds of the matcher returning true are lower and risk score is higher. For example, if you set a value of 0.5, the matcher almost always returns false. The login time analysis collects data for eight login times before it provides input for risk score calculation.

IP reputation
The IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.

Modifying attribute matchers
Attribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.

Parent topic: Advanced Access Control administration

Related concepts:

IP reputation

Related tasks:

Modifying attribute matchers

IP reputationIP reputationIP reputationThe IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.IP reputation databasepolicy information pointdatabaseIP reputationpolicy information pointIP reputationPossible IP reputations include the following classifications:Anonymous proxiesBotnet Command and Control ServerDynamic IPsMalwareScanning IPsSpamIP addresses that have reputations engage in certain activities that qualify them for reputations. The IP reputation database contains classification information about IP addresses. When the IP reputation PIP requests information, the database returns a score for each classification that the IP address might have. The score ranges from 0 - 100. As the value increases, the likelihood that the IP address has a reputation corresponding with that score increases. The score for each classification is compared to a threshold score that you can configure. You can also use the default score of 50. The IP address has a reputation if the score that belongs to any number of classifications is greater than or equal to the threshold score. For example, if an IP address is suspected to be a spammer, the database may return a value of 95 for the spam classification. If this value is greater than or equal to the threshold score you choose to use, the IP reputation PIP returns a Spam classification for the requesting IP address.You can write a policy to either grant access to or prohibit access from IP addresses with specified classifications. To use the IP reputation PIP, use the ipReputation attribute in a policy.IP reputation can also be used to influence an access decision when the IP matcher is used.Attribute matchersAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.Modifying attribute matchersAttribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.Attribute matchersAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.Managing the IP reputation databaseSet the appliance so that you can update its IP reputation database automatically. To complete this task, use the Manage Application Databases management page.License server configurationThe appliance with Advanced Access Control must be able to contact the license server so that the IP reputation database can perform updates.

IP reputation

The IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.

Possible IP reputations include the following classifications:

Anonymous proxies

Botnet Command and Control Server

Dynamic IPs

Malware

Scanning IPs

Spam

IP addresses that have reputations engage in certain activities that qualify them for reputations. The IP reputation database contains classification information about IP addresses. When the IP reputation PIP requests information, the database returns a score for each classification that the IP address might have. The score ranges from 0 - 100. As the value increases, the likelihood that the IP address has a reputation corresponding with that score increases.

The score for each classification is compared to a threshold score that you can configure. You can also use the default score of 50. The IP address has a reputation if the score that belongs to any number of classifications is greater than or equal to the threshold score. For example, if an IP address is suspected to be a spammer, the database may return a value of 95 for the spam classification. If this value is greater than or equal to the threshold score you choose to use, the IP reputation PIP returns a Spam classification for the requesting IP address.

You can write a policy to either grant access to or prohibit access from IP addresses with specified classifications. To use the IP reputation PIP, use the ipReputation attribute in a policy.

IP reputation can also be used to influence an access decision when the IP matcher is used.

Managing the IP reputation database
Set the appliance so that you can update its IP reputation database automatically. To complete this task, use the Manage Application Databases management page.

License server configuration
The appliance with Advanced Access Control must be able to contact the license server so that the IP reputation database can perform updates.

Parent topic: Attribute matchers

Related tasks:

Modifying attribute matchers

Attribute matchers

Managing the IP reputation databaseManaging the IP reputation databaseAccess Manager Appliance: Managing IP reputation databaseSet the appliance so that you can update its IP reputation database automatically. To complete this task, use the Manage Application Databases management page.IP reputation database managementThe IBM X-Force team frequently publishes the most recent IP reputation data. The appliance provides the function to automatically download such updates to its local IP reputation database.When Auto Update is enabled, the server polls the update server every minute for updates. The actual frequency cannot be changed. If an update is found, the server automatically downloads the update and applies it to the appliance. These updates are automatically detected and no restart is required.From the top menu, select Manage System SettingsUpdates and LicensingApplication Database Settings.Under IP Reputation Database, select the Auto Update check box.Use a proxy to access the update server.Under Proxy Settings, select the Use Proxy check box.Enter the address of the proxy server.Enter the port number of the proxy server.If the proxy server requires authentication, select the Use Authentication check box, and enter the user name and password for authentication. Click Save.Check the status of the IP reputation update. From the top menu, select Manage System SettingsUpdates and LicensingOverview.IP reputationThe IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.

Managing the IP reputation database

Set the appliance so that you can update its IP reputation database automatically. To complete this task, use the Manage Application Databases management page.

About this task

The IBM X-Force team frequently publishes the most recent IP reputation data. The appliance provides the function to automatically download such updates to its local IP reputation database.

When Auto Update is enabled, the server polls the update server every minute for updates. The actual frequency cannot be changed. If an update is found, the server automatically downloads the update and applies it to the appliance. These updates are automatically detected and no restart is required.

Procedure

From the top menu, select Manage System Settings > Updates and Licensing > Application Database Settings.

Under IP Reputation Database, select the Auto Update check box.

Optional: Use a proxy to access the update server.

Under Proxy Settings, select the Use Proxy check box.

Enter the address of the proxy server.

Enter the port number of the proxy server.

If the proxy server requires authentication, select the Use Authentication check box, and enter the user name and password for authentication.

Click Save.

What to do next

Check the status of the IP reputation update. From the top menu, select Manage System Settings > Updates and Licensing > Overview.

Parent topic: IP reputation

License server configurationLicense server configurationLicense server configurationThe appliance with Advanced Access Control must be able to contact the license server so that the IP reputation database can perform updates. license server configurationWhen the appliance cannot resolve the domain name for the license server, the IP reputation database cannot update. When the IP reputation database cannot update, it either contains inaccurate IP reputation data or no IP reputation data.You know that the IP reputation database cannot contact the license server when all IP addresses are granted access despite their IP reputations. If the following conditions are true, the IP reputation policy information point (PIP) might return an incorrect reputation: An administrator writes a policy that denies access based on IP reputation.The database cannot contact the license server. The IP reputation database must contact the license server so that the appliance can access the license server. The administrator must complete one of the following tasks so that the IP reputation database can contact the license server directly or indirectly: Tasks for contacting the license serverType of access to the license serverTaskFor more informationDirect accessComplete one of the following tasks:Add the license server to the hosts fileConfigure the domain name system (DNS)See "Configuring direct access to the license server"Indirect accessUse a proxy serverSee "Configuring indirect access to the license server"Configuring direct access to the license serverAdd the license server to the hosts file or configure the domain name system so that the appliance has direct access to the license server. Direct access to the license server enables the appliance to perform updates and resolve domain names. Configuring indirect access to the license serverConfigure a proxy so that the appliance has indirect access to the license server to perform updates and resolve domain names. IP reputationThe IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.Configuring direct access to the license serverAdd the license server to the hosts file or configure the domain name system so that the appliance has direct access to the license server. Direct access to the license server enables the appliance to perform updates and resolve domain names. Configuring indirect access to the license serverConfigure a proxy so that the appliance has indirect access to the license server to perform updates and resolve domain names.

License server configuration

The appliance with Advanced Access Control must be able to contact the license server so that the IP reputation database can perform updates.

When the appliance cannot resolve the domain name for the license server, the IP reputation database cannot update. When the IP reputation database cannot update, it either contains inaccurate IP reputation data or no IP reputation data.

You know that the IP reputation database cannot contact the license server when all IP addresses are granted access despite their IP reputations. If the following conditions are true, the IP reputation policy information point (PIP) might return an incorrect reputation:

An administrator writes a policy that denies access based on IP reputation.

The database cannot contact the license server.

The IP reputation database must contact the license server so that the appliance can access the license server. The administrator must complete one of the following tasks so that the IP reputation database can contact the license server directly or indirectly:

Table 199. Tasks for contacting the license server

Type of access to the license server
Task
For more information

Direct access
Complete one of the following tasks:

Add the license server to the hosts file

Configure the domain name system (DNS)

See "Configuring direct access to the license server"

Indirect access
Use a proxy server
See "Configuring indirect access to the license server"

Configuring direct access to the license server
Add the license server to the hosts file or configure the domain name system so that the appliance has direct access to the license server. Direct access to the license server enables the appliance to perform updates and resolve domain names.

Configuring indirect access to the license server
Configure a proxy so that the appliance has indirect access to the license server to perform updates and resolve domain names.

Parent topic: IP reputation

Related tasks:

Configuring direct access to the license server

Configuring indirect access to the license server

Configuring direct access to the license serverConfiguring direct access to the license serverConfiguring direct access to the license serverAdd the license server to the hosts file or configure the domain name system so that the appliance has direct access to the license server. Direct access to the license server enables the appliance to perform updates and resolve domain names. license server direct access configuration license serverdirect accessChoose one of the following options if your appliance has access to an external internet connection. Choose one of the following options to enable an appliance with Advanced Access Control to contact the license server directly. Add the license server to the hosts file to enable the appliance to resolve only the domain names that are configured in the hosts file. Configure the domain name system (DNS) to enable the appliance to resolve any domain name. Complete one of the following tasks: Adding the license server to the hosts fileLog in to the local management interface.Under Manage System Settings, click Hosts File.Click New.Enter 194.153.113.16 for Address. Enter license.cobion.com for the Hostname.Click Save.Configuring the DNSLog in to the local management interface. Under Manage System Settings, click Management Interfaces.Click DNS.Specify the DNS fields so that they are specific to your environment. Verify that the IP reputation policy works in accordance to the updates that you made.License server configurationThe appliance with Advanced Access Control must be able to contact the license server so that the IP reputation database can perform updates.

Configuring direct access to the license server

Add the license server to the hosts file or configure the domain name system so that the appliance has direct access to the license server. Direct access to the license server enables the appliance to perform updates and resolve domain names.

Before you begin

Choose one of the following options if your appliance has access to an external internet connection.

About this task

Choose one of the following options to enable an appliance with Advanced Access Control to contact the license server directly. Add the license server to the hosts file to enable the appliance to resolve only the domain names that are configured in the hosts file. Configure the domain name system (DNS) to enable the appliance to resolve any domain name.

Procedure

Complete one of the following tasks:

Adding the license server to the hosts file

Log in to the local management interface.

Under Manage System Settings, click Hosts File.

Click New.

Enter 194.153.113.16 for Address. Enter license.cobion.com for the Hostname.

Click Save.

Configuring the DNS

Log in to the local management interface.

Under Manage System Settings, click Management Interfaces.

Click DNS.

Specify the DNS fields so that they are specific to your environment.

What to do next

Verify that the IP reputation policy works in accordance to the updates that you made.

Parent topic: License server configuration

Configuring indirect access to the license serverConfiguring indirect access to the license server Configuring indirect access to the license serverConfigure a proxy so that the appliance has indirect access to the license server to perform updates and resolve domain names. license server indirect access configurationlicense serverindirect accessChoose this option if your appliance does not have access to an external internet connection. The server that you use as a proxy must have access to the following connections:An external internet connection.An internal intranet connection. Choose this option to enable an appliance with Advanced Access Control to contact the license server indirectly. Log in to the local management interface. Under Manage System Settings, click Application Database Settings.Under Proxy Settings, complete the following steps: Select the Use Proxy check box if you want to use a proxy to access the update server. For Server Address, enter the address of the proxy server. For Port, enter the port number on which to access the proxy server. If the proxy server requires authentication, select the Use Authentication check box, and also enter the user name and password for authentication. Verify that the IP reputation policy works in accordance to the updates that you made.License server configurationThe appliance with Advanced Access Control must be able to contact the license server so that the IP reputation database can perform updates.

Configuring indirect access to the license server

Configure a proxy so that the appliance has indirect access to the license server to perform updates and resolve domain names.

Before you begin

Choose this option if your appliance does not have access to an external internet connection.

Note: The server that you use as a proxy must have access to the following connections:

An external internet connection.

An internal intranet connection.

About this task

Choose this option to enable an appliance with Advanced Access Control to contact the license server indirectly.

Procedure

Log in to the local management interface.

Under Manage System Settings, click Application Database Settings.

Under Proxy Settings, complete the following steps:

Select the Use Proxy check box if you want to use a proxy to access the update server.

For Server Address, enter the address of the proxy server.

For Port, enter the port number on which to access the proxy server.

If the proxy server requires authentication, select the Use Authentication check box, and also enter the user name and password for authentication.

What to do next

Verify that the IP reputation policy works in accordance to the updates that you made.

Parent topic: License server configuration

Modifying attribute matchersModifying attribute matchersAttribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.attribute matchersmodifyingEach predefined matcher uses specific properties.exact_matchThe exact_match matcher checks whether the values of an attribute in a registered device and an incoming request exactly equal each other. Use this matcher if the more specialized matchers are not appropriate for the attribute. This matcher cannot be modified.location_matcherThe location matcher checks whether the location of a device is within a specific distance from the previous known locations of a device.ComparisonIndicates how you want the attribute matcher to calculate the accuracy range of the location coordinates. DistanceSpecifies the maximum distance between the new location and the historic locations. The value is in kilometers. The default value is 40.login_time_matcherThe login matcher compares and analyzes the historical login time data for the user with the current login time of the user.ThresholdIndicates the probability that a user might log in at a particular time. Valid values are 0 to 1. The default value is 0.3. This default value indicates the probability that the user logs in approximately within an hour of the previous login times. If you set a lower value, the odds of a return value of true are higher and the risk score is lower. If you set a higher value, the odds of a return value of true are lower and risk score is higher. For example, if you set a value of 0.5, the matcher almost always returns false. The login time analysis collects data for eight login times before it provides input for risk score calculation. ipaddr_matcherThe IP address matcher compares an inclusion list (trusted) or exclusion list (not trusted) of IP addresses with the historical IP addresses of the device. Trusted addresses IPV4 addressesIP and Netmask: Specifies the IP address and its netmask to include. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered.IPV6 addressesIP and Prefix: Specifies the IP address and its prefix to include. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered. Untrusted addresses IPV4 addressesIP and Netmask: Specifies the IP address and its netmask to exclude. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered. IPV6 addressesIP and Prefix: Specifies the IP address and its prefix to exclude. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered. Use the IP reputation database for classification of IP addressesSelect this box to check the requesting IP address against the addresses in the IP Reputation database. Addresses in the database are associated with one or more classifications. If the requesting address matches an address in the database, the database returns a score for each classification that is associated with the address.The IP reputation threshold for classificationsThe score that is compared to the classification score of an IP address. Select a score between 0 and 100 below the Untrusted tab in IP Address Matcher Properties. The default value is 50.Log in to the local management interface.Click Secure Access Control.Under Policy, click Attributes.Click Matchers.Click the Edit icon for the matcher.Change the properties.Click Save.When you modify an attribute matcher, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..The modified attribute matcher is saved.IP reputationThe IP reputation policy information point (PIP) uses the IP reputation database to determine the reputation of the IP address of a request. Based on the IP address reputation, you can write a policy to grant or prohibit access to the requesting IP address. The IP reputation PIP is pre-configured with Advanced Access Control.Attribute matchersAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.Attribute matchersAn attribute matcher compares the values of a specified attribute in the incoming device fingerprint with the existing device fingerprint of the user. Context-based access uses the information that is returned by the attribute matchers to calculate the risk score.

Modifying attribute matchers

Attribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.

About this task

Each predefined matcher uses specific properties.

exact_match

The exact_match matcher checks whether the values of an attribute in a registered device and an incoming request exactly equal each other. Use this matcher if the more specialized matchers are not appropriate for the attribute. This matcher cannot be modified.

location_matcher

The location matcher checks whether the location of a device is within a specific distance from the previous known locations of a device.

Comparison

Indicates how you want the attribute matcher to calculate the accuracy range of the location coordinates.

Distance

Specifies the maximum distance between the new location and the historic locations. The value is in kilometers. The default value is 40.

login_time_matcher

The login matcher compares and analyzes the historical login time data for the user with the current login time of the user.

Threshold

Indicates the probability that a user might log in at a particular time. Valid values are 0 to 1. The default value is 0.3. This default value indicates the probability that the user logs in approximately within an hour of the previous login times. If you set a lower value, the odds of a return value of true are higher and the risk score is lower. If you set a higher value, the odds of a return value of true are lower and risk score is higher. For example, if you set a value of 0.5, the matcher almost always returns false. The login time analysis collects data for eight login times before it provides input for risk score calculation.

ipaddr_matcher

The IP address matcher compares an inclusion list (trusted) or exclusion list (not trusted) of IP addresses with the historical IP addresses of the device.

Trusted addresses

IPV4 addresses

IP and Netmask: Specifies the IP address and its netmask to include. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered.

IPV6 addresses

IP and Prefix: Specifies the IP address and its prefix to include. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered.

Untrusted addresses

IPV4 addresses

IP and Netmask: Specifies the IP address and its netmask to exclude. Include X.X.X.X as a value to compare the incoming IP address with the IP address with which the device is registered.

IPV6 addresses

IP and Prefix: Specifies the IP address and its prefix to exclude. Include X:X:X:X:X:X:X:X as a value to compare the incoming IP address with the IP address with which the device is registered.

Use the IP reputation database for classification of IP addresses

Select this box to check the requesting IP address against the addresses in the IP Reputation database. Addresses in the database are associated with one or more classifications. If the requesting address matches an address in the database, the database returns a score for each classification that is associated with the address.

The IP reputation threshold for classifications

The score that is compared to the classification score of an IP address. Select a score between 0 and 100 below the Untrusted tab in IP Address Matcher Properties. The default value is 50.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Attributes.

Click Matchers.

Click the Edit icon for the matcher.

Change the properties.

Click Save.

When you modify an attribute matcher, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.

For more information, see Deploying pending changes.

Results

The modified attribute matcher is saved.

Parent topic: Attribute matchers

Related concepts:

Attribute matchers

IP reputation

Obligations Obligation managementObligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.obligationsoverviewObligations are either of the following types:Actions that require the user to perform an operation. Actions that occur on the server without user involvement.Predefined obligations are available by default. See Predefined obligationsPredefined obligations are provided for your use in policy authoring.. You can create, modify, or delete obligations.When you create a policy, you can add an obligation. If the obligation has parameters, define the parameter details when you create the policy. You can use the same obligation for different policies. Parameters customize the obligation for each policy. Parameter details are defined in the policy, not the obligation.Obligations are saved in the local configuration database.You can also map an obligation to a URL by defining it in the WebSEAL configuration file.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.Obligation propertiesWhen you add or modify an obligation, you specify properties that make that attribute unique.Predefined obligationsPredefined obligations are provided for your use in policy authoring.Mapping obligations to a URLYou can define the mapping between the obligation that the policy decision point (PDP) returns and the URL that attempts to satisfy the obligation.

Obligations

Obligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.

Obligations are either of the following types:

Actions that require the user to perform an operation.

Actions that occur on the server without user involvement.

Predefined obligations are available by default. See Predefined obligations.

You can create, modify, or delete obligations.

When you create a policy, you can add an obligation. If the obligation has parameters, define the parameter details when you create the policy.

You can use the same obligation for different policies. Parameters customize the obligation for each policy. Parameter details are defined in the policy, not the obligation.

Obligations are saved in the local configuration database.

You can also map an obligation to a URL by defining it in the WebSEAL configuration file.

Managing obligations
Obligations are used for authoring policies. You can view, add, modify, and delete obligations.

Obligation properties
When you add or modify an obligation, you specify properties that make that attribute unique.

Predefined obligations
Predefined obligations are provided for your use in policy authoring.

Mapping obligations to a URL
You can define the mapping between the obligation that the policy decision point (PDP) returns and the URL that attempts to satisfy the obligation.

Parent topic: Advanced Access Control administration

Managing obligationsManaging obligationsManaging obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.obligationsmanagingThe obligation name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.Log in to the local management interface.Click Secure Access Control.Under Policy, click Obligations.Click Obligations.Perform any of the following actions: Add an obligation Determine whether you want to use an imported obligation extension or not.If you want to use an imported obligation extension, click Add and select its associated obligation type.If you do not want to use an imported obligation extension, click Add and select Enforcement Point.Complete the fields in the General tab.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Click Save. Modify a custom obligation You cannot modify the identifier for obligations that are in use by a policy. You cannot change the extension that is used in the custom obligation. Only extension properties can be changed. Select the obligation that you want to modify.Click Modify.To add a parameter, click Add, specify the settings. Click OK.To delete a parameter, highlight it, and click Delete.Modify the obligation properties.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.You must enter the value for all required properties.Click Save. Delete a custom obligation You cannot delete predefined obligations or obligations that are in use by a policy. Select an obligation from the list. To select multiple obligations, press and hold the Ctrl key and select several obligationsClick Delete. A message prompts you to confirm the deletion.Click Delete. When you add, modify or delete an obligation, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..You can use any obligation in your policy. See Access control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions. for instructions on how to specify an obligation for use in your policy.Predefined obligationsPredefined obligations are provided for your use in policy authoring.Obligation propertiesWhen you add or modify an obligation, you specify properties that make that attribute unique.ObligationsObligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.

Managing obligations

Obligations are used for authoring policies. You can view, add, modify, and delete obligations.

About this task

The obligation name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Obligations.

Click Obligations.

Perform any of the following actions:

Add an obligation

Determine whether you want to use an imported obligation extension or not.

If you want to use an imported obligation extension, click Add and select its associated obligation type.

If you do not want to use an imported obligation extension, click Add and select Enforcement Point.

Complete the fields in the General tab.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Click Save.

Modify a custom obligation

Note:

You cannot modify the identifier for obligations that are in use by a policy.

You cannot change the extension that is used in the custom obligation. Only extension properties can be changed.

Select the obligation that you want to modify.

Click Modify.

To add a parameter, click Add, specify the settings. Click OK.

To delete a parameter, highlight it, and click Delete.

Modify the obligation properties.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Note: You must enter the value for all required properties.

Click Save.

Delete a custom obligation

Note: You cannot delete predefined obligations or obligations that are in use by a policy.

Select an obligation from the list. To select multiple obligations, press and hold the Ctrl key and select several obligations

Click Delete. A message prompts you to confirm the deletion.

Click Delete.

When you add, modify or delete an obligation, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.

For more information, see Deploying pending changes.

What to do next

You can use any obligation in your policy. See Access control policies for instructions on how to specify an obligation for use in your policy.

Parent topic: Obligations

Related reference:

Predefined obligations

Obligation properties

Obligation propertiesWhen you add or modify an obligation, you specify properties that make that attribute unique.Specify the following properties when you add or modify an obligation:NameSpecify a unique name for the obligation.DescriptionEnter a description of the obligation. (Optional)IdentifierSpecify an obligation ID that is used within the XACML policy file to identify the obligation at run time. The identifier must be a known identifier that can be handled by the target enforcement point. This value is required. For example, urn:ibm:security:obligation:myCustomObligation.TypeThis field is read only. The type is Obligation.ParametersDataTypeSelect a data type for the parameter. Valid options include the following options: BooleanRepresents the XML Boolean data type, http://www.w3.org/2001/XMLSchema#boolean.DateRepresents the XML date data type, http://www.w3.org/2001/XMLSchema#date.DoubleRepresents the XML double data type, http://www.w3.org/2001/XMLSchema#double.IntegerRepresents the XML integer data type, http://www.w3.org/2001/XMLSchema#integer.StringSpecifies the XML string data type, http://www.w3.org/2001/XMLSchema#string.TimeRepresents the XML time data type, http://www.w3.org/2001/XMLSchema#time.X500NameRepresents the XACML X500 name data type, urn:oasis:names:tc:xacml:1.0:data-type:x500Name.Managing obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.ObligationsObligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.

Obligation properties

When you add or modify an obligation, you specify properties that make that attribute unique.

Specify the following properties when you add or modify an obligation:

Name

Specify a unique name for the obligation.

Description

Enter a description of the obligation. (Optional)

Identifier

Specify an obligation ID that is used within the XACML policy file to identify the obligation at run time. The identifier must be a known identifier that can be handled by the target enforcement point. This value is required. For example, urn:ibm:security:obligation:myCustomObligation.

Type

This field is read only. The type is Obligation.

Parameters

DataType

Select a data type for the parameter. Valid options include the following options:

Boolean

Represents the XML Boolean data type, http://www.w3.org/2001/XMLSchema#boolean.

Date

Represents the XML date data type, http://www.w3.org/2001/XMLSchema#date.

Double

Represents the XML double data type, http://www.w3.org/2001/XMLSchema#double.

Integer

Represents the XML integer data type, http://www.w3.org/2001/XMLSchema#integer.

String

Specifies the XML string data type, http://www.w3.org/2001/XMLSchema#string.

Time

Represents the XML time data type, http://www.w3.org/2001/XMLSchema#time.

X500Name

Represents the XACML X500 name data type, urn:oasis:names:tc:xacml:1.0:data-type:x500Name.

Parent topic: Obligations

Related tasks:

Managing obligations

Predefined obligationsPredefined obligationsPredefined obligationsPredefined obligations are provided for your use in policy authoring.predefined obligationsobligationspredefinedAn obligation consists of an action that must occur to allow or deny access to a resource.Register DeviceThe system registers the device that is used by the user to access the resource. No user interaction is required for this obligation.The administrator can configure the following properties to affect device fingerprint registration: deviceRegistration.allowIncompleteFingerprintsSpecifies whether the risk engine registers devices with incomplete device fingerprints.An incomplete device fingerprint is a device fingerprint that does not include all of the attributes that the administrator specifies in the risk profile.deviceRegistration.permitOnIncompleteFingerprintSpecifies whether the risk engine grants access to request devices with incomplete device fingerprints.If the administrator does not set the configuration properties, then the properties default to false. When the properties are set to false: The risk engine cannot register devices that have incomplete device fingerprints.The risk engine denies request devices with incomplete device fingerprints.ObligationsObligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.

Predefined obligations

Predefined obligations are provided for your use in policy authoring.

An obligation consists of an action that must occur to allow or deny access to a resource.

Register Device

The system registers the device that is used by the user to access the resource. No user interaction is required for this obligation.

The administrator can configure the following properties to affect device fingerprint registration:

deviceRegistration.allowIncompleteFingerprints

Specifies whether the risk engine registers devices with incomplete device fingerprints.

An incomplete device fingerprint is a device fingerprint that does not include all of the attributes that the administrator specifies in the risk profile.

deviceRegistration.permitOnIncompleteFingerprint

Specifies whether the risk engine grants access to request devices with incomplete device fingerprints.

If the administrator does not set the configuration properties, then the properties default to false. When the properties are set to false:

The risk engine cannot register devices that have incomplete device fingerprints.

The risk engine denies request devices with incomplete device fingerprints.

Parent topic: Obligations

Mapping obligations to a URLMapping obligations to a URLMapping obligations to a URLYou can define the mapping between the obligation that the policy decision point (PDP) returns and the URL that attempts to satisfy the obligation.obligationsURLURLobligationOpen the WebSEAL configuration file.Add entries to the [obligations-urls-mapping] stanza. These entries define the mapping between an obligation and the URL that attempts to satisfy that obligation. The following example contains a complete stanza and entry: [obligations-urls-mapping] obligation = URL Where: obligationDefines the obligation string that is returned by runtime security services. This string, or key, is case-sensitive.You can also use wildcard obligations in this entry. Add an asterisk at the end of an obligation to indicate that all obligations found that match this entry, up to but not including the asterisk, are redirected to the URL value. Exact matches are searched for first. If no match is found, wildcard matches are used.URLDefines the URL to which the user is redirected for authentication. The URL must point to an external authentication interface (EAI) application. See the WebSEAL documentation for information about the requirements for the EAI application. Save the file.Restart the WebSEAL server for the changes to take effect.When the runtime security services returns an obligation, the key is searched for in the configuration file in the following order: [obligations-urls-mapping] entries[obligations-levels-mappings] entries The entries in the [obligations-urls-mapping] stanza must have unique keys as compared to the keys in the [obligations-levels-mappings] entries. The following entry specifies that an obligation named auth1. The value of auth1 is a URL that is used to satisfy the obligation. [obligations-urls-mapping] auth1 = https://example.com To redirect all obligations that start with urn:example to http://www.example.com, add the following entry: urn:example:* = http://example.com Suppose that you have the following entries in the [obligations-urls-mapping] stanza: urn:example:sports = http://example.sports urn:example:* = http://example If runtime security services returns an obligation of urn:example:sports, the first entry is used to redirect the user to http://example.sports. In this case, both stanza entries apply to the obligation returned, but because there is an exact match, that obligation is used. ObligationsObligations are used in policies to inform the enforcement point that more actions are required before access is granted or denied to a protected resource.

Mapping obligations to a URL

You can define the mapping between the obligation that the policy decision point (PDP) returns and the URL that attempts to satisfy the obligation.

Procedure

Open the WebSEAL configuration file.

Add entries to the [obligations-urls-mapping] stanza. These entries define the mapping between an obligation and the URL that attempts to satisfy that obligation. The following example contains a complete stanza and entry:

[obligations-urls-mapping]
obligation = URL

Where:

obligation

Defines the obligation string that is returned by runtime security services. This string, or key, is case-sensitive.

You can also use wildcard obligations in this entry. Add an asterisk at the end of an obligation to indicate that all obligations found that match this entry, up to but not including the asterisk, are redirected to the URL value. Exact matches are searched for first. If no match is found, wildcard matches are used.

URL

Defines the URL to which the user is redirected for authentication. The URL must point to an external authentication interface (EAI) application. See the WebSEAL documentation for information about the requirements for the EAI application.

Save the file.

Restart the WebSEAL server for the changes to take effect.

Results

When the runtime security services returns an obligation, the key is searched for in the configuration file in the following order:

[obligations-urls-mapping] entries

[obligations-levels-mappings] entries

The entries in the [obligations-urls-mapping] stanza must have unique keys as compared to the keys in the [obligations-levels-mappings] entries.

Example

The following entry specifies that an obligation named auth1. The value of auth1 is a URL that is used to satisfy the obligation.

[obligations-urls-mapping]
auth1 = https://example.com

To redirect all obligations that start with urn:example to http://www.example.com, add the following entry:

urn:example:* = http://example.com

Suppose that you have the following entries in the [obligations-urls-mapping] stanza:

urn:example:sports = http://example.sports
urn:example:* = http://example

If runtime security services returns an obligation of urn:example:sports, the first entry is used to redirect the user to http://example.sports. In this case, both stanza entries apply to the obligation returned, but because there is an exact match, that obligation is used.

Parent topic: Obligations

Authentication policiesAuthentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute.authentication policiesoverviewThe access control policy that is attached to the resource can be used to determine the authentication policy with which the user must comply to access the resource. For example, the authentication policy can require the user to provide a one-time password value or authenticate with a user name and password whether or not an authenticated session exists. Predefined authentication policies are available by default. See Predefined authentication policiesAuthentication policies are workflows. They specify the authentication mechanisms that are required so the user can access a resource. . You can create, modify, or delete authentication policies.You cannot modify or delete predefined authentication policies.Use an authentication policy as a permit condition of an access control policy.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing authentication policiesAuthentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.Creating an authentication policyUse the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy.Authentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.Predefined authentication policiesAuthentication policies are workflows. They specify the authentication mechanisms that are required so the user can access a resource. Managing authentication mechanismsAuthentication mechanisms determine conditions that successfully authenticate a user. You can view, add, modify, and delete authentication mechanisms.

Authentication policies

Authentication policies are workflows that dictate the authentication mechanisms to execute.

The access control policy that is attached to the resource can be used to determine the authentication policy with which the user must comply to access the resource. For example, the authentication policy can require the user to provide a one-time password value or authenticate with a user name and password whether or not an authenticated session exists.

Predefined authentication policies are available by default. See Predefined authentication policies.

You can create, modify, or delete authentication policies.

Attention: You cannot modify or delete predefined authentication policies.

Use an authentication policy as a permit condition of an access control policy.

Managing authentication policies
Authentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.

Creating an authentication policy
Use the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy.

Authentication policy parameters and credentials
When you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.

Predefined authentication policies
Authentication policies are workflows. They specify the authentication mechanisms that are required so the user can access a resource.

Managing authentication mechanisms
Authentication mechanisms determine conditions that successfully authenticate a user. You can view, add, modify, and delete authentication mechanisms.

Parent topic: Advanced Access Control administration

Managing authentication policiesManaging authentication policiesAuthentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.authentication policiesmanagingKeep the following considerations in mind when you work with authentication policies:The authentication policy name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.You cannot modify or delete predefined policies.Log in to the local management interface.Click Secure Access Control.Under Policy, click Authentication.Perform any of the following actions: Add an authentication policy:Click Add. The Authentication Policy Editor opens. See Creating an authentication policyUse the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy..Modify a custom authentication policy: Select the authentication policy that you want to modify.Click Modify. The Authentication Policy Editor opens. Modify any of the authentication policy properties.Click Save. Delete a custom authentication policy: Select an authentication policy from the list. To select multiple authentication policies, press and hold the Ctrl key and select several authentication policiesClick Delete. A message prompts you to confirm the deletion.Click Delete. You can use any authentication policy in your access control policy. See Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy.. Authentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute.

Managing authentication policies

Authentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.

About this task

Keep the following considerations in mind when you work with authentication policies:

The authentication policy name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.

You cannot modify or delete predefined policies.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Perform any of the following actions:

Add an authentication policy:

Click Add. The Authentication Policy Editor opens. See Creating an authentication policy.

Modify a custom authentication policy:

Select the authentication policy that you want to modify.

Click Modify. The Authentication Policy Editor opens.

Modify any of the authentication policy properties.

Click Save.

Delete a custom authentication policy:

Select an authentication policy from the list. To select multiple authentication policies, press and hold the Ctrl key and select several authentication policies

Click Delete. A message prompts you to confirm the deletion.

Click Delete.

What to do next

You can use any authentication policy in your access control policy. See Creating an access control policy.

Parent topic: Authentication policies

Creating an authentication policyCreating an authentication policyUse the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy.authentication policycreatingEach policy consists of one or more authentication mechanisms. The mechanisms are modules that authenticate the user with a specific challenge or authentication technology, such as user name and password and one-time password. In the policy, the authentication mechanisms are grouped into a workflow. The workflow specifies the mechanism to use and the order in which each mechanism runs. The Authentication Policy Editor has several sections.Name, Identifier, and DescriptionSpecify a name and unique identifier for the policy, and optionally include a description of the policy. Prefix the unique identifier with the following text: urn:ibm:security:authentication:asf:*. Replace the * with the identifier you want to use for the policy. For example, urn:ibm:security:authentication:asf:bankingWorkflow StepsAdd one or more authentication mechanisms to use and the order in which they are to be used.Click Add.The Authentication Policy Editor opens.Complete the Name and Identifier fields. Provide a description in the Description field.Click Add Add Step to add an authentication mechanism as a step in the policy workflow.Select an authentication mechanism.See AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios. for descriptions of the mechanisms.Click to review and select parameters that are supported by the mechanism.Not all authentication mechanisms support parameters. However, some configuration settings for authentication mechanisms can be customized with parameters on a per policy basis. If an authentication mechanism supports parameters, use the parameters settings to assign values to the parameters. See Authentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision..Click OK.Continue with one of the following steps: Add another authentication mechanism to the workflow. Repeat the preceding steps.After you add all authentication mechanisms, click if you want to customize the information that is included in the user credential. See Authentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.. Click OK.Use this authentication policy as the Permit with authentication action in an access control policy. See Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy..Authentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute.

Creating an authentication policy

Use the Authentication Policy Editor on the appliance local management interface to create and configure an authentication policy.

About this task

Each policy consists of one or more authentication mechanisms. The mechanisms are modules that authenticate the user with a specific challenge or authentication technology, such as user name and password and one-time password. In the policy, the authentication mechanisms are grouped into a workflow. The workflow specifies the mechanism to use and the order in which each mechanism runs.

The Authentication Policy Editor has several sections.

Name, Identifier, and Description

Specify a name and unique identifier for the policy, and optionally include a description of the policy. Prefix the unique identifier with the following text: urn:ibm:security:authentication:asf:*. Replace the * with the identifier you want to use for the policy. For example, urn:ibm:security:authentication:asf:banking

Workflow Steps

Add one or more authentication mechanisms to use and the order in which they are to be used.

Procedure

Click Add. The Authentication Policy Editor opens.

Complete the Name and Identifier fields.

Optional: Provide a description in the Description field.

Click Add Add Step to add an authentication mechanism as a step in the policy workflow.

Select an authentication mechanism. See Authentication for descriptions of the mechanisms.

Click List view to review and select parameters that are supported by the mechanism. Not all authentication mechanisms support parameters. However, some configuration settings for authentication mechanisms can be customized with parameters on a per policy basis. If an authentication mechanism supports parameters, use the parameters settings to assign values to the parameters. See Authentication policy parameters and credentials.

Click OK.

Continue with one of the following steps:

Add another authentication mechanism to the workflow. Repeat the preceding steps.

After you add all authentication mechanisms, click Modify attribute if you want to customize the information that is included in the user credential. See Authentication policy parameters and credentials.

Click OK.

What to do next

Use this authentication policy as the Permit with authentication action in an access control policy. See Creating an access control policy.

Parent topic: Authentication policies

Authentication policy parameters and credentialsAuthentication policy parameters and credentialsAuthentication policy parameters and credentialsWhen you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.authentication policyparameterscredentialsparametersauthentication policycredentialsauthentication policy You cannot modify predefined authentication policies. Parameters Parameters pass policy configuration to the authentication mechanism. Parameters can be set for each workflow step. Parameter values can be a literal string that you provide in the parameter settings or they can be a context attribute reference. A context attribute consists of an attribute source, attribute namespace, and attribute ID. See Table 2 for a list of context attributes that you can use. Authentication mechanism runtime parametersAuthentication mechanismParameter nameDefault valueDescriptionUsername PasswordreauthenticatetrueAn authentication value that indicates whether the user must authenticate even if the user previously authenticated.One-Time PasswordreauthenticatetrueAn authentication value that indicates whether the user must authenticate even if the user previously authenticated.One-Time PasswordusernameNo default valueThe user name for OTP authentication. If the Pass check box is not checked, the OTP authentication mechanism retrieves the user name from the current authentication service credential.HOTP One-Time PasswordreauthenticatetrueAn authentication value that indicates whether the user must authenticate even if the user previously authenticated.HOTP One-Time PasswordusernameNo default valueThe user name in HOTP authentication. If the Pass check box is not checked, the HOTP authentication mechanism retrieves the user name from the current authentication service credential.HOTP One-Time PasswordsecretKeyNo default valueThe secret key in HOTP authentication. If the Pass check box is not checked, the HOTP authentication mechanism retrieves the secret key of the user from its internal database. Users can configure their own secret key on the OTP Secret Keys management page. See Managing OTP secret keysTo help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability.TOTP One-Time PasswordreauthenticatetrueAn authentication value that indicates whether the user must authenticate even if the user previously authenticated.TOTP One-Time PasswordusernameNo default valueThe user name in TOTP authentication. If the Pass check box is not checked, TOTP authentication mechanism retrieves the user name from the current authentication service credential.TOTP One-Time PasswordsecretKeyNo default valueThe secret key in TOTP authentication. If the Pass check box is not checked, the TOTP authentication mechanism retrieves the secret key of the user from its internal database. Users can configure their own secret key on the OTP Secret Keys management page. See Managing OTP secret keysTo help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability.MAC Email One-time PasswordMAC One-time PasswordMAC SMS One-time passwordmobileNumberNo default valueThe phone number that delivers the one-time password value.MAC Email One-time PasswordMAC One-time PasswordMAC SMS One-time passwordemailAddressNo default valueThe email address that delivers the one-time password value.MAC Email One-time PasswordMAC One-time PasswordMAC SMS One-time passwordreauthenticatetrueAn authentication value that indicates whether the user must authenticate even if the user previously authenticated. If you create a policy that uses both the SMS and Email delivery types with reauthenticate set to false, only the first delivery type is executed.MAC Email One-time PasswordMAC One-time PasswordMAC SMS One-time passwordusernameNo default valueThe user name in MAC OTP authentication. If the Pass check box is not checked, MAC OTP authentication mechanism retrieves the user name from the current authentication service credential.MAC Email One-time PasswordMAC One-time PasswordMAC SMS One-time passworddeliveryTypeEmailSMSThe type of delivery mechanisms to use for delivering the one-time password value. When specified, the MAC One-Time password bypasses the OTPMethods mapping rule. If you create a policy and have both the SMS and Email delivery types defined and reauthenticate is set to false, only the first delivery type is executed.RSA One-Time PasswordreauthenticatetrueThe authentication value that indicates whether the user must authenticate even if the user previously authenticated.RSA One-Time PasswordusernameNo default valueThe user name in RSA authentication. If the Pass check box is not checked, RSA authentication mechanism retrieves the user name from the current authentication service credential.HTTP Redirect AuthenticationredirectURLNo default valueThe URL that contacts the custom authentication implementation. The HTTP Redirect authentication mechanism redirects the user's browser to the specified URL.HTTP Redirect AuthenticationreauthenticatetrueAn authentication value that indicates whether the user must authenticate even if the user previously authenticated.HTTP Redirect AuthenticationreturnCredAttrNameNo default valueThe credential attribute name that determines whether the HTTP Redirect authentication is successful.HTTP Redirect AuthenticationreturnCredAttrValueNo default valueThe credential attribute value that is compared against to determine whether the HTTP Redirect authentication is successful.End-User License Agreement alwaysShowLicenseFalseThe prompt for the license file. Set this option to true to always prompt the user to accept the license file. End-User License Agreement licenseRenewalTerm0The number of days until the user must accept the license again. When you specify a value that is less than 1, there is not a renewal term.This parameter compares the date that the user last accepted the license to the current date to determine the number of days since the user last accepted the license.End-User License Agreement licenseFileNo default value The path to the license template file to display for the End-User License Agreement. For more information about how to update the license and add more license files, see Template filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors. and Template file macrosMost template pages contain one or more macros. The macros are replaced by values that are specific to the action that is requested on the page.. The path to the license file is relative to the locale in the template tree. End-User License Agreement acceptIfLastAccepted Before No default valueThe date that the license was last accepted. If the date the user last accepted the license is before this date, this parameter requires the user to accept the license again. Use the date format of YYYY-MM-DD.End-User License Agreement usernameNo default valueThe user name of the user who is prompted to accept the license. If the Pass check box is not checked, the End-User License Agreement authentication mechanism retrieves the user name from the current authentication service credential. End-User License Agreement reauthenticateTrue An authentication value that indicates whether the user must authenticate even if the user previously authenticated. The mechanism displays the license once per authenticated session under the following conditions:alwaysShowLicense=true reauthenticate=false Knowledge QuestionsquestionPresentationModeGroupUse one of the following values: IndividualPresents each question one at a time.GroupPresents all questions to the user in the same form.Knowledge QuestionsquestionPresentationOrderRandomUse one of the following values: RandomPresents the questions in random order.SequentialPresents the questions in the order in which they are stored.Knowledge QuestionsamountOfCorrectAnswersRequired1The number of correct answers that is required for successful authentication.Specify any positive integer value that is not higher than the number of questions that is stored for each user.Knowledge QuestionsusernameNo default valueThe user name of the user who is prompted to answer the knowledge questions. If you do not specify the user name, the user must log in before the Knowledge Questions authentication mechanism starts. The value must be a string.Knowledge QuestionsreauthenticateTrueAn authentication value that indicates whether the user must authenticate with the Knowledge Questions authentication mechanism even if the user previously authenticated.The value is Boolean.Knowledge QuestionsmaxGracePeriodAuthenticationCount0The maximum number of user authentications during the grace period. The mechanism does not require the user to configure knowledge questions during the grace period.The value is any positive integer.Mobile User ApprovedauthenticationMethodTypeTouch IDThe type of registered authentication method to use.Mobile User ApprovedusernameNo default valueThe user name for Mobile User Approved authentication. If the Pass check box is not checked, the Mobile User Approved authentication mechanism retrieves the user name from the current authentication service credential.Mobile User ApprovedauthenticationMethodTypeUser PresenceThe type of registered authentication method to use. Pass A check in the Pass check box passes the parameter to the authenticator. The value for a passed parameter is either specified in the Value field or with the session or request information. If the Pass check box is not checked, the mechanism takes one of the following actions: Uses the default value.Uses the default method to get the default value.Reports an error, depending on the mechanism and the parameter. Credentials When the user completes the authentication process, the Authentication Service creates a credential for that user. It uses the credential to log in the user. The user credential contains information such as the name of the user, the groups that the user belongs to, and attributes that further describe the user. You might want to modify the information that is included in the credential depending on the information required in your policies. The Authentication Service automatically includes the following attributes:usernameThe name of the user who is making the access request.authenticationTypesA list of URIs of all authentication policies that the user completed.authenticationMechanismTypesA list of URIs of all the authentication mechanisms that the user completed.authenticationTransactionIdAn identifier of the latest authentication transaction that the user completed. Use Credentials to restrict the attributes in the credential by explicitly including each attribute. These attributes can be: A literal string that you provide in the credential settings.A context attribute reference A context attribute consists of an attribute source, attribute namespace, and attribute ID. See Table 2 for a list of context attributes that you can use. Credential attributeThe name of an attribute to use as an authentication credential. ASCII letters ASCII digits Period (.) Underscore (_) Hyphen (-) Do not use any other special characters or non-ASCII Unicode characters.SourceThe source specifies the provider of the value for the credential:ValueThe value for the credential. Use any characters.SessionA context attribute with a lifetime throughout the authentication process.RequestA context attribute with a lifetime of the HTTP Request. ValueThe value of the credential attribute. The value that you specify depends on the source you select in the previous field.If you select Value as a source, type a literal value in this field.If you select Session or Request, type an attribute ID and namespace. Context attributesThe following table lists of types of values you can retrieve from a session or a request.Context attributesTypeDescriptionAttribute SourceAttribute NamespaceAttribute IDPolicy IDThe ID of the authentication policy in the current authentication process.Sessionurn:ibm:security:asf:policypolicyIDTransaction IDThe ID that triggers the current authentication process. Sessionurn:ibm:security:asf:transactiontransactionIDHTTP request parametersThe HTTP request parameters of the current HTTP request.Request Each attribute can contain multiple values. urn:ibm:security:asf:request:parameterRetrieves the first value.urn:ibm:security:asf:request:parametersRetrieves all the values. The name of the parameter.HTTP request headersThe HTTP request headers of the current HTTP request.Request Each attribute can contain multiple values. You can retrieve the first value or all of the values:urn:ibm:security:asf:request:headerRetrieves the first value.urn:ibm:security:asf:request:headersRetrieves all the values. The name of the header.Request credentialThe credential of the user in the current request. Request Each attribute can contain multiple values. You can retrieve the first value or all of the values:urn:ibm:security:asf:request:token:attributeRetrieves the first value.urn:ibm:security:asf:request:token:attributesRetrieves all the values. The name of the Request credential attribute. Use username to retrieve the name of the user. Use group to retrieve the groups of the user.Authentication Service credentialThe credential of the user that the Authentication Service began constructing at the beginning of the authentication process.Session Each attribute can contain multiple values. You can retrieve the first value or all of the values:urn:ibm:security:asf:response:token:attributeRetrieves the first value.urn:ibm:security:asf:response:token:attributesRetrieves all the values. The name of the Authentication Service credential attribute. Use username to retrieve the name of the user. User group to retrieve the groups of the user.Context-based access attributesThe attributes that specify the context of the request that is evaluated as part of an access control decision.Session Before you can use context attributes, you must add the attributes to theattributeCollection.authenticationContextAttributes property in the Advanced Configuration settings. See Managing advanced configurationAdjust configuration settings in supported configuration files.. Each attribute can contain multiple values. You can retrieve the first value or all of the values: urn:ibm:security:asf:cba:attributeRetrieves the first value.urn:ibm:security:asf:cba:attributesRetrieves all the values. The name of the attribute.Authentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute.

Authentication policy parameters and credentials

When you add or modify an authentication policy, you specify parameters for the authentication mechanism and the attributes that you want in the credential. The credentials are evaluated as part of the access control decision.

Note: You cannot modify predefined authentication policies.

Parameters

Parameters pass policy configuration to the authentication mechanism. Parameters can be set for each workflow step. Parameter values can be a literal string that you provide in the parameter settings or they can be a context attribute reference. A context attribute consists of an attribute source, attribute namespace, and attribute ID. See Table 201 for a list of context attributes that you can use.

Table 200. Authentication mechanism runtime parameters

Authentication mechanism
Parameter name
Default value
Description

Username Password
reauthenticate
true
An authentication value that indicates whether the user must authenticate even if the user previously authenticated.

One-Time Password
reauthenticate
true
An authentication value that indicates whether the user must authenticate even if the user previously authenticated.

One-Time Password
username
No default value
The user name for OTP authentication. If the Pass check box is not checked, the OTP authentication mechanism retrieves the user name from the current authentication service credential.

HOTP One-Time Password
reauthenticate
true
An authentication value that indicates whether the user must authenticate even if the user previously authenticated.

HOTP One-Time Password
username
No default value
The user name in HOTP authentication. If the Pass check box is not checked, the HOTP authentication mechanism retrieves the user name from the current authentication service credential.

HOTP One-Time Password
secretKey
No default value
The secret key in HOTP authentication. If the Pass check box is not checked, the HOTP authentication mechanism retrieves the secret key of the user from its internal database. Users can configure their own secret key on the OTP Secret Keys management page. See Managing OTP secret keys

TOTP One-Time Password
reauthenticate
true
An authentication value that indicates whether the user must authenticate even if the user previously authenticated.

TOTP One-Time Password
username
No default value
The user name in TOTP authentication. If the Pass check box is not checked, TOTP authentication mechanism retrieves the user name from the current authentication service credential.

TOTP One-Time Password
secretKey
No default value
The secret key in TOTP authentication. If the Pass check box is not checked, the TOTP authentication mechanism retrieves the secret key of the user from its internal database. Users can configure their own secret key on the OTP Secret Keys management page. See Managing OTP secret keys

MAC Email One-time Password

MAC One-time Password

MAC SMS One-time password

mobileNumber
No default value
The phone number that delivers the one-time password value.

MAC Email One-time Password

MAC One-time Password

MAC SMS One-time password

emailAddress
No default value
The email address that delivers the one-time password value.

MAC Email One-time Password

MAC One-time Password

MAC SMS One-time password

reauthenticate
true
An authentication value that indicates whether the user must authenticate even if the user previously authenticated.

Note: If you create a policy that uses both the SMS and Email delivery types with reauthenticate set to false, only the first delivery type is executed.

MAC Email One-time Password

MAC One-time Password

MAC SMS One-time password

username
No default value
The user name in MAC OTP authentication. If the Pass check box is not checked, MAC OTP authentication mechanism retrieves the user name from the current authentication service credential.

MAC Email One-time Password

MAC One-time Password

MAC SMS One-time password

deliveryType

Email

SMS

The type of delivery mechanisms to use for delivering the one-time password value. When specified, the MAC One-Time password bypasses the OTPMethods mapping rule.

Note: If you create a policy and have both the SMS and Email delivery types defined and reauthenticate is set to false, only the first delivery type is executed.

RSA One-Time Password
reauthenticate
true
The authentication value that indicates whether the user must authenticate even if the user previously authenticated.

RSA One-Time Password
username
No default value
The user name in RSA authentication. If the Pass check box is not checked, RSA authentication mechanism retrieves the user name from the current authentication service credential.

HTTP Redirect Authentication
redirectURL
No default value
The URL that contacts the custom authentication implementation. The HTTP Redirect authentication mechanism redirects the user's browser to the specified URL.

HTTP Redirect Authentication
reauthenticate
true
An authentication value that indicates whether the user must authenticate even if the user previously authenticated.

HTTP Redirect Authentication
returnCredAttrName
No default value
The credential attribute name that determines whether the HTTP Redirect authentication is successful.

HTTP Redirect Authentication
returnCredAttrValue
No default value
The credential attribute value that is compared against to determine whether the HTTP Redirect authentication is successful.

End-User License Agreement
alwaysShowLicense
False
The prompt for the license file. Set this option to true to always prompt the user to accept the license file.

End-User License Agreement
licenseRenewalTerm
0
The number of days until the user must accept the license again. When you specify a value that is less than 1, there is not a renewal term.

Note: This parameter compares the date that the user last accepted the license to the current date to determine the number of days since the user last accepted the license.

End-User License Agreement
licenseFile
No default value

The path to the license template file to display for the End-User License Agreement. For more information about how to update the license and add more license files, see Template files and Template file macros.

Note: The path to the license file is relative to the locale in the template tree.

End-User License Agreement

acceptIfLastAccepted

Before

No default value

The date that the license was last accepted. If the date the user last accepted the license is before this date, this parameter requires the user to accept the license again.

Use the date format of YYYY-MM-DD.

End-User License Agreement
username
No default value
The user name of the user who is prompted to accept the license. If the Pass check box is not checked, the End-User License Agreement authentication mechanism retrieves the user name from the current authentication service credential.

End-User License Agreement
reauthenticate
True

An authentication value that indicates whether the user must authenticate even if the user previously authenticated.

Note: The mechanism displays the license once per authenticated session under the following conditions:

alwaysShowLicense=true

reauthenticate=false

Knowledge Questions
questionPresentationMode
Group
Use one of the following values:

Individual

Presents each question one at a time.

Group

Presents all questions to the user in the same form.

Knowledge Questions
questionPresentationOrder
Random
Use one of the following values:

Random

Presents the questions in random order.

Sequential

Presents the questions in the order in which they are stored.

Knowledge Questions
amountOfCorrectAnswersRequired
1

The number of correct answers that is required for successful authentication.

Specify any positive integer value that is not higher than the number of questions that is stored for each user.

Knowledge Questions
username
No default value

The user name of the user who is prompted to answer the knowledge questions. If you do not specify the user name, the user must log in before the Knowledge Questions authentication mechanism starts.

The value must be a string.

Knowledge Questions
reauthenticate
True

An authentication value that indicates whether the user must authenticate with the Knowledge Questions authentication mechanism even if the user previously authenticated.

The value is Boolean.

Knowledge Questions
maxGracePeriodAuthenticationCount
0

The maximum number of user authentications during the grace period. The mechanism does not require the user to configure knowledge questions during the grace period.

The value is any positive integer.

Mobile User Approved
authenticationMethodType
Touch ID

The type of registered authentication method to use.

Mobile User Approved
username
No default value

The user name for Mobile User Approved authentication. If the Pass check box is not checked, the Mobile User Approved authentication mechanism retrieves the user name from the current authentication service credential.

Mobile User Approved
authenticationMethodType
User Presence

The type of registered authentication method to use.

Pass

A check in the Pass check box passes the parameter to the authenticator. The value for a passed parameter is either specified in the Value field or with the session or request information. If the Pass check box is not checked, the mechanism takes one of the following actions:

Uses the default value.

Uses the default method to get the default value.

Reports an error, depending on the mechanism and the parameter.

Credentials

When the user completes the authentication process, the Authentication Service creates a credential for that user. It uses the credential to log in the user. The user credential contains information such as the name of the user, the groups that the user belongs to, and attributes that further describe the user. You might want to modify the information that is included in the credential depending on the information required in your policies.

The Authentication Service automatically includes the following attributes:

username

The name of the user who is making the access request.

authenticationTypes

A list of URIs of all authentication policies that the user completed.

authenticationMechanismTypes

A list of URIs of all the authentication mechanisms that the user completed.

authenticationTransactionId

An identifier of the latest authentication transaction that the user completed.

Use Credentials to restrict the attributes in the credential by explicitly including each attribute. These attributes can be:

A literal string that you provide in the credential settings.

A context attribute reference

A context attribute consists of an attribute source, attribute namespace, and attribute ID. See Table 201 for a list of context attributes that you can use.

Credential attribute

The name of an attribute to use as an authentication credential.

ASCII letters

ASCII digits

Period (.)

Underscore (_)

Hyphen (-)

Note: Do not use any other special characters or non-ASCII Unicode characters.

Source

The source specifies the provider of the value for the credential:

Value

The value for the credential. Use any characters.

Session

A context attribute with a lifetime throughout the authentication process.

Request

A context attribute with a lifetime of the HTTP Request.

Value

The value of the credential attribute. The value that you specify depends on the source you select in the previous field.

If you select Value as a source, type a literal value in this field.

If you select Session or Request, type an attribute ID and namespace.

Context attributes

The following table lists of types of values you can retrieve from a session or a request.

Table 201. Context attributes

Type
Description
Attribute Source
Attribute Namespace
Attribute ID

Policy ID
The ID of the authentication policy in the current authentication process.
Session
urn:ibm:security:asf:policy
policyID

Transaction ID
The ID that triggers the current authentication process.
Session
urn:ibm:security:asf:transaction
transactionID

HTTP request parameters
The HTTP request parameters of the current HTTP request.
Request

Each attribute can contain multiple values.

urn:ibm:security:asf:request:parameter

Retrieves the first value.

urn:ibm:security:asf:request:parameters

Retrieves all the values.

The name of the parameter.

HTTP request headers
The HTTP request headers of the current HTTP request.
Request

Each attribute can contain multiple values. You can retrieve the first value or all of the values:

urn:ibm:security:asf:request:header

Retrieves the first value.

urn:ibm:security:asf:request:headers

Retrieves all the values.

The name of the header.

Request credential
The credential of the user in the current request.
Request

Each attribute can contain multiple values. You can retrieve the first value or all of the values:

urn:ibm:security:asf:request:token:attribute

Retrieves the first value.

urn:ibm:security:asf:request:token:attributes

Retrieves all the values.

The name of the Request credential attribute. Use username to retrieve the name of the user. Use group to retrieve the groups of the user.

Authentication Service credential
The credential of the user that the Authentication Service began constructing at the beginning of the authentication process.
Session

Each attribute can contain multiple values. You can retrieve the first value or all of the values:

urn:ibm:security:asf:response:token:attribute

Retrieves the first value.

urn:ibm:security:asf:response:token:attributes

Retrieves all the values.

The name of the Authentication Service credential attribute. Use username to retrieve the name of the user. User group to retrieve the groups of the user.

Context-based access attributes
The attributes that specify the context of the request that is evaluated as part of an access control decision.
Session

Attention: Before you can use context attributes, you must add the attributes to the

attributeCollection.authenticationContextAttributes

property in the Advanced Configuration settings. See Managing advanced configuration.

Each attribute can contain multiple values. You can retrieve the first value or all of the values:

urn:ibm:security:asf:cba:attribute

Retrieves the first value.

urn:ibm:security:asf:cba:attributes

Retrieves all the values.

The name of the attribute.

Parent topic: Authentication policies

Predefined authentication policiesPredefined authentication policiesPredefined authentication policiesAuthentication policies are workflows. They specify the authentication mechanisms that are required so the user can access a resource. authentication policiespredefinedEach step in the workflow consists of an authentication mechanism. Each mechanism has requirements with which the user must comply to successfully authenticate. Most authentication policies require that the user present some credentials, but some requirements can be completed without any user action. The following table describes the predefined authentication policies: PolicyThe user authenticatesConsent Register DeviceWhen prompted for consent to register a device. Optionally, the user can assign a name to the device to be registered.Email One-Time PasswordWith a one-time password that is delivered by email. The one-time password value is generated and verified with the MAC one-time password.HOTP One-Time PasswordWith a counter-based, one-time password. No one-time password delivery is required. The one-time password value is verified with the HOTP one-time password provider.One-Time PasswordWith a one-time password. The user is prompted for the type of one-time password to use.RSA One-Time PasswordWith an RSA one-time password. No one-time password delivery is required. The one-time password value is verified with the RSA one-time password provider. The RSA one-time password provider uses the RSA Authentication Manager.MAC One-Time PasswordWith a MAC one-time password. The user is prompted for a password delivery method.SMS One-Time PasswordWith a one-time password that is delivered by SMS. The one-time password value is generated and verified with the MAC one-time password provider.TOTP One-Time PasswordWith a time-based one-time password. No one-time password delivery is required. The one-time password value is verified with the TOTP one-time password provider.Username PasswordWith a user name and password.Two-factor - Username Password and HOTP With a user name and password and an HOTP one-time password. Two-factor - Username Password and MACWith a user name and password and a MAC one-time password.Two-factor - Username Password and RSAWith a user name and password and an RSA one-time password.Two-factor - Username Password and TOTP With a user name and password and a TOTP one-time password.Two-factor - Username Password and OTPWith a user name and password and a MAC one-time password. The user is prompted to select the type of one-time password to use.Two-factor - Username Password and EmailWith a user name and password and a MAC one-time password. The one-time password is delivered through email.Two-factor - Username Password and SMSWith a user name and password and a MAC one-time password. The one-time password is delivered through SMS.End-User License Agreement With the End-User License Agreement.Two factor - Username Password and End-User License Agreement With a user name and password and the End-User License Agreement.Knowledge QuestionsWith knowledge questions.Two-factor - Username Password and Knowledge QuestionsWith both of the following: User name and passwordKnowledge questionsFingerprintWith a registered authenticator application via an enrolled fingerprint authentication method.User PresenceWith a registered authenticator application via an enrolled User Presence authentication method.Authentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute.

Predefined authentication policies

Authentication policies are workflows. They specify the authentication mechanisms that are required so the user can access a resource.

Each step in the workflow consists of an authentication mechanism. Each mechanism has requirements with which the user must comply to successfully authenticate. Most authentication policies require that the user present some credentials, but some requirements can be completed without any user action. The following table describes the predefined authentication policies:

Policy
The user authenticates

Consent Register Device
When prompted for consent to register a device. Optionally, the user can assign a name to the device to be registered.

Email One-Time Password
With a one-time password that is delivered by email. The one-time password value is generated and verified with the MAC one-time password.

HOTP One-Time Password
With a counter-based, one-time password. No one-time password delivery is required. The one-time password value is verified with the HOTP one-time password provider.

One-Time Password
With a one-time password. The user is prompted for the type of one-time password to use.

RSA One-Time Password
With an RSA one-time password. No one-time password delivery is required. The one-time password value is verified with the RSA one-time password provider. The RSA one-time password provider uses the RSA Authentication Manager.

MAC One-Time Password
With a MAC one-time password. The user is prompted for a password delivery method.

SMS One-Time Password
With a one-time password that is delivered by SMS. The one-time password value is generated and verified with the MAC one-time password provider.

TOTP One-Time Password
With a time-based one-time password. No one-time password delivery is required. The one-time password value is verified with the TOTP one-time password provider.

Username Password
With a user name and password.

Two-factor - Username Password and HOTP
With a user name and password and an HOTP one-time password.

Two-factor - Username Password and MAC
With a user name and password and a MAC one-time password.

Two-factor - Username Password and RSA
With a user name and password and an RSA one-time password.

Two-factor - Username Password and TOTP
With a user name and password and a TOTP one-time password.

Two-factor - Username Password and OTP
With a user name and password and a MAC one-time password. The user is prompted to select the type of one-time password to use.

Two-factor - Username Password and Email
With a user name and password and a MAC one-time password. The one-time password is delivered through email.

Two-factor - Username Password and SMS
With a user name and password and a MAC one-time password. The one-time password is delivered through SMS.

End-User License Agreement
With the End-User License Agreement.

Two factor - Username Password and End-User License Agreement
With a user name and password and the End-User License Agreement.

Knowledge Questions
With knowledge questions.

Two-factor - Username Password and Knowledge Questions
With both of the following:

User name and password

Knowledge questions

Fingerprint
With a registered authenticator application via an enrolled fingerprint authentication method.

User Presence
With a registered authenticator application via an enrolled User Presence authentication method.

Parent topic: Authentication policies

Managing authentication mechanismsManaging authentication mechanismsAuthentication mechanisms determine conditions that successfully authenticate a user. You can view, add, modify, and delete authentication mechanisms.authentication mechanismsmanagingLog in to the local management interface.Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Perform any of the following actions: Add an authentication mechanism:The Add button is not enabled if no custom authentication mechanism is imported in the appliance.Click the Add drop-down button.Select your authentication mechanism type.Complete the fields in the General tab.Click the Properties tab.Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Save and deploy the changes.Modify an authentication mechanism: Select the authentication mechanism that you want to modify.Click Modify.Modify the authentication mechanism properties. Select a property that you want to configure.Click Modify.Enter the value for that property.Click OK.Save and deploy the changes. Delete a custom authentication mechanism: The Delete button is not enabled when you select a predefined authentication mechanism. You cannot delete predefined authentication mechanisms. Select an authentication mechanism from the list. To select multiple authentication mechanisms, press and hold the Ctrl key and select several authentication mechanisms.Click Delete. A message prompts you to confirm the deletion.Click Delete.Save and deploy the changes. You can use your authentication mechanism in your authentication policy. See Managing authentication policiesAuthentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.. Authentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute.

Managing authentication mechanisms

Authentication mechanisms determine conditions that successfully authenticate a user. You can view, add, modify, and delete authentication mechanisms.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Perform any of the following actions:

Add an authentication mechanism:

Note: The Add button is not enabled if no custom authentication mechanism is imported in the appliance.

Click the Add drop-down button.

Select your authentication mechanism type.

Complete the fields in the General tab.

Click the Properties tab.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Save and deploy the changes.

Modify an authentication mechanism:

Select the authentication mechanism that you want to modify.

Click Modify.

Modify the authentication mechanism properties.

Select a property that you want to configure.

Click Modify.

Enter the value for that property.

Click OK.

Save and deploy the changes.

Delete a custom authentication mechanism:

Note: The Delete button is not enabled when you select a predefined authentication mechanism. You cannot delete predefined authentication mechanisms.

Select an authentication mechanism from the list. To select multiple authentication mechanisms, press and hold the Ctrl key and select several authentication mechanisms.

Click Delete. A message prompts you to confirm the deletion.

Click Delete.

Save and deploy the changes.

What to do next

You can use your authentication mechanism in your authentication policy. See Managing authentication policies.

Parent topic: Authentication policies

Risk profilesRisk profilesRisk profilesThe risk engine uses the active risk profile to calculate risk scores for incoming requests. The administrator can create risk profiles or use predefined risk profiles that are provided with Advanced Access Control. risk profilesrisk profilespredefined risk profilespredefined risk profilesrisk profilesThere are two types of risk profiles: Predefined risk profilesDefault risk profiles that are pre-configured on an appliance that has Advanced Access Control. Each predefined risk profile is tailored to a specific scenario.Risk profilesCustom risk profiles that the administrator creates.Risk profiles include:Attributes that the administrator specifies. The risk engine collects all of the attributes that the administrator specifies in the risk profile from each incoming request device.Weight values for each attribute that the administrator specifies in the risk profile. The weight that an administrator gives to each attribute in the risk profile depends on the importance of each attribute. As the attributes increase in importance, their weight values also increase. There is not a limit on the number of attributes that the administrator can include in a risk profile. However, the risk engine uses one risk profile at a time. Predefined risk profiles Predefined risk profiles are pre-configured on an appliance with Advanced Access Control. The risk engine uses the active risk profile to calculate risk scores for incoming requests. Risk score calculationRisk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing risk profilesA risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time.Predefined risk profiles Predefined risk profiles are pre-configured on an appliance with Advanced Access Control. The risk engine uses the active risk profile to calculate risk scores for incoming requests.

Risk profiles

The risk engine uses the active risk profile to calculate risk scores for incoming requests. The administrator can create risk profiles or use predefined risk profiles that are provided with Advanced Access Control.

There are two types of risk profiles:

Predefined risk profiles

Default risk profiles that are pre-configured on an appliance that has Advanced Access Control.

Each predefined risk profile is tailored to a specific scenario.

Risk profiles

Custom risk profiles that the administrator creates.

Risk profiles include:

Attributes that the administrator specifies. The risk engine collects all of the attributes that the administrator specifies in the risk profile from each incoming request device.

Weight values for each attribute that the administrator specifies in the risk profile. The weight that an administrator gives to each attribute in the risk profile depends on the importance of each attribute. As the attributes increase in importance, their weight values also increase.

Note: There is not a limit on the number of attributes that the administrator can include in a risk profile. However, the risk engine uses one risk profile at a time.

Managing risk profiles
A risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time.

Predefined risk profiles
Predefined risk profiles are pre-configured on an appliance with Advanced Access Control. The risk engine uses the active risk profile to calculate risk scores for incoming requests.

Parent topic: Advanced Access Control administration

Related concepts:

Risk score calculation

Related reference:

Predefined risk profiles

Managing risk profilesManaging risk profilesA risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time.risk profilemanaging Several risk profiles are predefined based on risk assessment for a collection of attributes. Predefined risk profiles are read only and you cannot modify their weights or add attributes to them. You can add custom risk profiles by creating your own or by cloning an existing profile. By default, a risk profile named Default is set to active. The Default profile includes all the risk profile attributes with weights set to 0. With this profile active, if a user logs in with no devices registered, the risk score of that user is 100. If a user logs in with a device registered, the risk score of that user is 0. The Default profile is a sample profile. It is not intended to be used in a production environment. Before you use Security Access Manager, choose another risk profile or create your own.Use single-value attributes when you create a risk profile. Multivalue attributes are not supported in risk profiles. There are two sections on the Risk Profile page:Risk ProfilesThe Risk Profiles section lists all the available risk profiles. An icon indicates which profile is active. Click a profile to select it.Selected Profile ContentsThe Selected Profile Contents section displays the Attribute and Weight for a selected risk profile. If you select a custom risk profile, you can modify the weight by typing a number or selecting a number. Log in to the local management interface.Click Secure Access Control.Under Policy, click Risk Profiles.Perform one or more of the following actions: Rename a risk profile Right-click the profile name in the table and click Rename to change the name. The risk profile name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.Press Enter to apply the change. Modify a custom profile You can modify only custom profiles. Select a custom profile.Modify the attributes and associated weights in the Selected Profile Contents section. Create a custom profile Click Add.Type a name for the profile. Click Save.In the Profile Contents section, click Add attribute to add one or more attributes.In the Add Profile Attributes window, select an attribute to use. Click the Attribute column to sort the list in ascending or descending order. To filter the list of available attributes, type one or more characters in the Filter field. For example, if you type current in the Filter field, all attributes that start with current are shown in the attributes list. The attributes that match those characters are displayed.Select one or more attributes to add.Click Add.Click Close when you are done with the Add Profile Attributes window.Change the weights by typing or selecting a number.Click Save to apply the changes.If you want to make this new profile active, click Set active Set Active. Create a copy of a profile and use it to make a custom profile Select the profile that you want to clone and give the profile a unique name.Click Duplicate.Type a new name for the cloned profile.Click Save.Select the clone.In the Profile Contents section, select an attribute and take one of the following actions:Type a new value in the Weight field.Click Remove attribute to remove both the attribute and weight.Click Add attribute to add one or more attributes. In the Add Profile Attribute window, select the attributes to use. To filter the list of available attributes, type one or more characters in the Filter field. The attributes that match those characters are displayed. For example, if you type header in the Filter field, all attributes that start with header are shown in the attributes list. Select the attribute that you want to use in the list and click Add. Click Close when you are done with the Add Profile Attributes window. Click Save after each change to apply the change.If you want to make this new profile active, click Set active Set Active. Delete a risk profileSelect a risk profile. You cannot remove predefined risk profiles.Click Delete.Respond to the confirmation prompt.The risk profile is removed and cannot be used.Make a profile active Select a profile.Click Set active Set Active. Only one profile can be active at a time. When you add, modify or delete a risk profile, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Risk profilesThe risk engine uses the active risk profile to calculate risk scores for incoming requests. The administrator can create risk profiles or use predefined risk profiles that are provided with Advanced Access Control.

Managing risk profiles

A risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time.

About this task

Several risk profiles are predefined based on risk assessment for a collection of attributes. Predefined risk profiles are read only and you cannot modify their weights or add attributes to them. You can add custom risk profiles by creating your own or by cloning an existing profile.

By default, a risk profile named Default is set to active. The Default profile includes all the risk profile attributes with weights set to 0. With this profile active, if a user logs in with no devices registered, the risk score of that user is 100. If a user logs in with a device registered, the risk score of that user is 0. The Default profile is a sample profile. It is not intended to be used in a production environment. Before you use Security Access Manager, choose another risk profile or create your own.

Note: Use single-value attributes when you create a risk profile. Multivalue attributes are not supported in risk profiles.

There are two sections on the Risk Profile page:

Risk Profiles

The Risk Profiles section lists all the available risk profiles. An icon indicates which profile is active. Click a profile to select it.

Selected Profile Contents

The Selected Profile Contents section displays the Attribute and Weight for a selected risk profile. If you select a custom risk profile, you can modify the weight by typing a number or selecting a number.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Risk Profiles.

Perform one or more of the following actions:

Rename a risk profile

Right-click the profile name in the table and click Rename to change the name.

Note: The risk profile name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.

Press Enter to apply the change.

Modify a custom profile

Note: You can modify only custom profiles.

Select a custom profile.

Modify the attributes and associated weights in the Selected Profile Contents section.

Create a custom profile

Click Add.

Type a name for the profile. Click Save.

In the Profile Contents section, click Add attribute to add one or more attributes.

In the Add Profile Attributes window, select an attribute to use. Click the Attribute column to sort the list in ascending or descending order. To filter the list of available attributes, type one or more characters in the Filter field. For example, if you type current in the Filter field, all attributes that start with current are shown in the attributes list. The attributes that match those characters are displayed.

Select one or more attributes to add.

Click Add.

Click Close when you are done with the Add Profile Attributes window.

Change the weights by typing or selecting a number.

Click Save to apply the changes.

If you want to make this new profile active, click Set active Set Active.

Create a copy of a profile and use it to make a custom profile

Select the profile that you want to clone and give the profile a unique name.

Click Duplicate.

Type a new name for the cloned profile.

Click Save.

Select the clone.

In the Profile Contents section, select an attribute and take one of the following actions:

Type a new value in the Weight field.

Click Remove attribute to remove both the attribute and weight.

Click Add attribute to add one or more attributes. In the Add Profile Attribute window, select the attributes to use. To filter the list of available attributes, type one or more characters in the Filter field. The attributes that match those characters are displayed. For example, if you type header in the Filter field, all attributes that start with header are shown in the attributes list. Select the attribute that you want to use in the list and click Add. Click Close when you are done with the Add Profile Attributes window.

Click Save after each change to apply the change.

If you want to make this new profile active, click Set active Set Active.

Delete a risk profile

Select a risk profile.

Note: You cannot remove predefined risk profiles.

Click Delete.

Respond to the confirmation prompt.

The risk profile is removed and cannot be used.

Make a profile active

Select a profile.

Click Set active Set Active.

Note: Only one profile can be active at a time.

When you add, modify or delete a risk profile, a message indicates that there are changes to deploy. If you are finished with the changes, deploy them.

For more information, see Deploying pending changes.

Parent topic: Risk profiles

Predefined risk profilesPredefined risk profilesPredefined risk profiles Predefined risk profiles are pre-configured on an appliance with Advanced Access Control. The risk engine uses the active risk profile to calculate risk scores for incoming requests. predefined risk profilesrisk profilespredefinedrisk score calculations Predefined risk profiles:Are tailored for specific scenarios.Can be cloned.Cannot be modified.To choose the most appropriate risk profile, you must determine your security priority. You can also create your own risk profile. Depending on your environment, choose one of the following scenarios: Upgrading to an IBM Security Access Manager appliance with Advanced Access ControlBy default, a risk profile that is named Default is set to active. The Default profile includes all the risk profile attributes with weights set to 0. The risk score for this profile is always 0. The Default profile is a sample profile. It is not intended for a production environment. Before you use Security Access Manager, choose another risk profile or create your own.Performing a new installation of an IBM Security Access Manager appliance with Advanced Access ControlBy default, the Browser risk profile is set as the default risk profile. If the Browser risk profile does not suit the needs of your environment, you must choose another risk profile or create your own. Predefined risk profile types You can choose one of the following predefined risk profiles for the risk engine to use as a filter when it calculates the risk score:BehaviorDetermines a risk score by comparing the time of the current request with the time that the user usually tries to access the resource. The following table contains the attributes and corresponding weight values that are included in the Behavior risk profile.Attribute WeightaccessTime50browserPlugins 10deviceFonts 10http:userAgent 10 BrowserDetermines a risk score by comparing the attributes from the requesting browser with the browsers that the user is known to use. The following table contains the attributes and corresponding weight values that are included in the Browser risk profile.Attribute WeightbrowserPlugins 50deviceFonts 50http:accept 30http:acceptEncoding50http:acceptLanguage 50http:userAgent 50 DeviceDetermines a risk score by comparing the attributes from the requesting device with the devices that are associated with the user. The following table contains the attributes and corresponding weight values that are included in the Device risk profile.Attribute WeightbrowserPlugins 30colorDepth 50deviceFonts 50deviceLanguage50devicePlatform50screenAvailableHeight 50screenAvailableWidth 50screenHeight 50screenWidth 50 LocationDetermines a risk score by comparing the location of the incoming request with the locations that the user is known to log in from. The following table contains the attributes and corresponding weight values that are included in the Location risk profile. Attribute Weight geoLocation 50geoCity 10geoCountryCode10geoRegionCode 10 Usage scenariosThe following example usage scenarios demonstrate risk score calculation in predefined risk profiles.Each scenario assumes that the administrator wrote a policy, which specifies that:Any risk score at or below 40 is permitted.Any risk score above 40 is denied. Scenario 1: Behavior risk profileThe risk engine uses risk profile information in the following table to calculate the risk score.AttributesWeight values Incoming device fingerprint valuesRegistered device fingerprint valuesaccessTime502013-05-07T03:25:13Z2013-05-06T04:00:39Z, 2013-05-13T03:05:20Z,2013-05-20T03:15:22,2013-05-27T03:26:05Z, 2013-06-03T03:42:45ZbrowserPlugins 10Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for LinuxShockwave Flash,Chrome Remote Desktop Viewer,Native Client, Chrome PDF Viewer, Conference Plugin, AmazonMP3DownloaderPlugin, Google UpdatedeviceFonts10Andale Mono,Arial Black,Arial,Bitstream Charter,Century Schoolbook L,Comic Sans MS,Courier 10 Pitch,Courier New,DejaVu Sans Mono,DejaVu Sans,DejaVu Serif,Dingbats,Georgia, Impact,Khmer OS System,Khmer OS,Liberation Mono,Liberation Sans,Liberation Serif,Lohit Bengali,Lohit Gujarati,Lohit Punjabi,Lohit Tamil,Luxi Mono,Luxi Sans,Luxi Serif,Meera,Nimbus Mono L,Nimbus Roman No9 L,Nimbus Sans L,Standard Symbols L,Tahoma,Times New Roman,Trebuchet MS,URW Bookman L,URW Chancery L,URW Gothic L,URW Palladio L,UnBatang,UnDotum,Verdana, Waree,WebdingsAharoni,Andalus,Angsana New, AngsanaUPC,Aparajita,Arabic Typesetting,Arial Black,Arial, Batang,BatangChe,Browallia New,BrowalliaUPC,Calibri, Cambria Math,Cambria,Candara, Comic Sans MS,Consolas, Constantia,Corbel,Cordia New,CordiaUPC,Courier 10 Pitch,Courier New,David, DilleniaUPC,DokChampa, Dotum,DotumChe,Ebrima, Estrangelo Edessa,EucrosiaUPC, Euphemia,FangSong,FrankRuehl, Franklin Gothic Medium,LilyUPC, Lucida Bright,Lucida Console, Lucida Sans Typewriter,Tahoma, Times New Roman,Traditional Arabic,Wingdingshttp:userAgent 10Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.2 Safari/537.36Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.110 Safari/537.36Results:None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for accessTime.Because all of the attributes except for accessTime have mismatched values, the collective weight of the mismatched attributes is 30.The total weight of all of the attributes is 80. The accessTime attribute has a weight value of 50. The http:userAgent attribute, browserPlugins attribute, and deviceFonts attribute each have weight values of 10.According to the risk score calculation formula: (30/80)×100=38. Therefore, the risk score is 38.Authentication is permitted because the risk score is below 40. Scenario 2: Browser risk profileThe risk engine uses risk profile information in the following table to calculate the risk score.AttributesWeight values Incoming device fingerprint valuesRegistered device fingerprint valuesbrowserPlugins 50Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for LinuxShockwave Flash,Chrome Remote Desktop Viewer,Native Client, Chrome PDF Viewer, Conference Plugin, AmazonMP3DownloaderPlugin, Google UpdatedeviceFonts 50Andale Mono,Arial Black,Arial,Bitstream Charter,Century Schoolbook L,Comic Sans MS,Courier 10 Pitch,Courier New,DejaVu Sans Mono,DejaVu Sans,DejaVu Serif,Dingbats,Georgia, Impact,Khmer OS System,Khmer OS,Liberation Mono,Liberation Sans,Liberation Serif,Lohit Bengali,Lohit Gujarati,Lohit Punjabi,Lohit Tamil,Luxi Mono,Luxi Sans,Luxi Serif,Meera,Nimbus Mono L,Nimbus Roman No9 L,Nimbus Sans L,Standard Symbols L,Tahoma,Times New Roman,Trebuchet MS,URW Bookman L,URW Chancery L,URW Gothic L,URW Palladio L,UnBatang,UnDotum,Verdana, Waree,WebdingsAharoni,Andalus,Angsana New, AngsanaUPC,Aparajita,Arabic Typesetting,Arial Black,Arial, Batang,BatangChe,Browallia New,BrowalliaUPC,Calibri, Cambria Math,Cambria,Candara, Comic Sans MS,Consolas, Constantia,Corbel,Cordia New,CordiaUPC,Courier 10 Pitch,Courier New,David, DilleniaUPC,DokChampa, Dotum,DotumChe,Ebrima, Estrangelo Edessa,EucrosiaUPC, Euphemia,FangSong,FrankRuehl, Franklin Gothic Medium,LilyUPC, Lucida Bright,Lucida Console, Lucida Sans Typewriter,Tahoma, Times New Roman,Traditional Arabic,Wingdings http:accept 30text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8http:acceptEncoding 50gzip,deflate,sdchgzip,deflate,sdchhttp:acceptLanguage 50en-US,en;q=0.8en-US,en;q=0.8,es;q=0.6http:userAgent 50Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.116 Safari/537.36Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.110 Safari/537.36Results:None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for http:accept and http:acceptEncoding.Because all of the attributes except for http:accept and http:acceptEncoding have mismatched values, the collective weight of the mismatched attributes is 200.The total weight of all of the attributes is 280. The http:accept attribute has a weight value of 30. The browserPlugins attribute, deviceFonts attribute, http:acceptEncoding attribute, http:acceptLanguage attribute, and http:userAgent attribute each have weight values of 50.According to the risk score calculation formula: (200/280)×100=71. Therefore, the risk score is 71.Authentication is denied because the risk score is above 40. Scenario 3: Device risk profileThe risk engine uses risk profile information in the following table to calculate the risk score.Attribute names Weight valuesIncoming device fingerprint valuesRegistered device fingerprint valuesbrowserPlugins30Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for LinuxShockwave Flash,Chrome Remote Desktop Viewer,Native Client, Chrome PDF Viewer, Conference Plugin, AmazonMP3DownloaderPlugin, Google UpdatecolorDepth 502432deviceFonts 50Andale Mono,Arial Black,Arial,Bitstream Charter,Century Schoolbook L,Comic Sans MS,Courier 10 Pitch,Courier New,DejaVu Sans Mono,DejaVu Sans,DejaVu Serif,Dingbats,Georgia, Impact,Khmer OS System,Khmer OS,Liberation Mono,Liberation Sans,Liberation Serif,Lohit Bengali,Lohit Gujarati,Lohit Punjabi,Lohit Tamil,Luxi Mono,Luxi Sans,Luxi Serif,Meera,Nimbus Mono L,Nimbus Roman No9 L,Nimbus Sans L,Standard Symbols L,Tahoma,Times New Roman,Trebuchet MS,URW Bookman L,URW Chancery L,URW Gothic L,URW Palladio L,UnBatang,UnDotum,Verdana, Waree,WebdingsAharoni,Andalus,Angsana New, AngsanaUPC,Aparajita,Arabic Typesetting,Arial Black,Arial, Batang,BatangChe,Browallia New,BrowalliaUPC,Calibri, Cambria Math,Cambria,Candara, Comic Sans MS,Consolas, Constantia,Corbel,Cordia New,CordiaUPC,Courier 10 Pitch,Courier New,David, DilleniaUPC,DokChampa, Dotum,DotumChe,Ebrima, Estrangelo Edessa,EucrosiaUPC, Euphemia,FangSong,FrankRuehl, Franklin Gothic Medium,LilyUPC, Lucida Bright,Lucida Console, Lucida Sans Typewriter,Tahoma, Times New Roman,Traditional Arabic,WingdingsdeviceLanguage50en-USen-USdevicePlatform 50Linux x86_64Win-32screenAvailable Height 501025870screenAvailable Width5019201600screenHeight501080900screenWidth 5019201600Results: None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for deviceLanguage.Because all of the attributes except for deviceLanguage have mismatched values, the collective weight of the mismatched attributes is 380.The total weight of all of the attributes is 430. The browserPlugins attribute has a weight value of 30. The following attributes have weight values of 50: colorDepthdeviceFontsdeviceLanguagedevicePlatformscreenAvailableHeightscreenAvailableWidthscreenHeightscreenWidthAccording to the risk score calculation formula: (380/430)×100=88. Therefore, the risk score is 88.Authentication is denied because the risk score is above 40. Scenario 4: Location risk profileThe risk engine uses risk profile information in the following table to calculate the risk score.AttributesWeight values Incoming device fingerprint valuesRegistered device fingerprint valuesgeoCity10AustinAustingeoCountryCode10 USUSgeoLocation5030.2861, -97.739321, 1030.274722, -97.740556, 13geoRegionCode10TXTXResults:All of the device fingerprint values match. The geoLocation attribute contains the values that the risk engine uses to calculate the distance between the incoming device fingerprint and the registered device fingerprint. In this instance, the distance between the two device fingerprints is 1.27 km.Because all of the device fingerprint values match, the total weight of the mismatched attributes is 0.The total weight of all of the attributes is 80. The geoLocation attribute has a weight value of 50. The geoCity attribute, geoCountryCode attribute, and geoRegionCode attribute each have weight values of 10.According to the risk score calculation formula: (0/80)×100=0. Therefore, the risk score is 0.Authentication is permitted because the risk score is below 40. Risk score calculationRisk score calculation is the process by which the risk engine determines a risk score. The risk score demonstrates the level of risk that is associated with permitting a request to access the resource. This risk score is compared to a threshold score that is set in a policy. A decision is made based on the result of this comparison.Risk profilesThe risk engine uses the active risk profile to calculate risk scores for incoming requests. The administrator can create risk profiles or use predefined risk profiles that are provided with Advanced Access Control.

Predefined risk profiles

Predefined risk profiles are pre-configured on an appliance with Advanced Access Control. The risk engine uses the active risk profile to calculate risk scores for incoming requests.

Predefined risk profile types

Predefined risk profiles:

Are tailored for specific scenarios.

Can be cloned.

Cannot be modified.

To choose the most appropriate risk profile, you must determine your security priority. You can also create your own risk profile.

Depending on your environment, choose one of the following scenarios:

Upgrading to an IBM Security Access Manager appliance with Advanced Access Control

By default, a risk profile that is named Default is set to active. The Default profile includes all the risk profile attributes with weights set to 0. The risk score for this profile is always 0. The Default profile is a sample profile. It is not intended for a production environment. Before you use Security Access Manager, choose another risk profile or create your own.

Performing a new installation of an IBM Security Access Manager appliance with Advanced Access Control

By default, the Browser risk profile is set as the default risk profile. If the Browser risk profile does not suit the needs of your environment, you must choose another risk profile or create your own.

You can choose one of the following predefined risk profiles for the risk engine to use as a filter when it calculates the risk score:

Behavior

Determines a risk score by comparing the time of the current request with the time that the user usually tries to access the resource.

The following table contains the attributes and corresponding weight values that are included in the Behavior risk profile.

Attribute | Weight
accessTime | 50
browserPlugins | 10
deviceFonts | 10
http:userAgent | 10

Browser

Determines a risk score by comparing the attributes from the requesting browser with the browsers that the user is known to use.

The following table contains the attributes and corresponding weight values that are included in the Browser risk profile.

Attribute | Weight
browserPlugins | 50
deviceFonts | 50
http:accept | 30
http:acceptEncoding | 50
http:acceptLanguage | 50
http:userAgent | 50

Device

Determines a risk score by comparing the attributes from the requesting device with the devices that are associated with the user.

The following table contains the attributes and corresponding weight values that are included in the Device risk profile.

Attribute | Weight
browserPlugins | 30
colorDepth | 50
deviceFonts | 50
deviceLanguage | 50
devicePlatform | 50
screenAvailableHeight | 50
screenAvailableWidth | 50
screenHeight | 50
screenWidth | 50

Location

Determines a risk score by comparing the location of the incoming request with the locations that the user is known to log in from.

The following table contains the attributes and corresponding weight values that are included in the Location risk profile.

Attribute | Weight
geoLocation | 50
geoCity | 10
geoCountryCode | 10
geoRegionCode | 10

Usage scenarios

The following example usage scenarios demonstrate risk score calculation in predefined risk profiles.

Each scenario assumes that the administrator wrote a policy, which specifies that:

Any risk score at or below 40 is permitted.

Any risk score above 40 is denied.

Scenario 1: Behavior risk profile

The risk engine uses risk profile information in the following table to calculate the risk score.

Attributes
Weight values
Incoming device fingerprint values
Registered device fingerprint values

accessTime
50
2013-05-07T03:25:13Z
2013-05-06T04:00:39Z, 2013-05-13T03:05:20Z,2013-05-20T03:15:22,2013-05-27T03:26:05Z, 2013-06-03T03:42:45Z

browserPlugins
10
Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for Linux
Shockwave Flash,Chrome Remote Desktop Viewer,Native Client, Chrome PDF Viewer, Conference Plugin, AmazonMP3DownloaderPlugin, Google Update

deviceFonts
10
Andale Mono,Arial Black,Arial,Bitstream Charter,Century Schoolbook L,Comic Sans MS,Courier 10 Pitch,Courier New,DejaVu Sans Mono,DejaVu Sans,DejaVu Serif,Dingbats,Georgia, Impact,Khmer OS System,Khmer OS,Liberation Mono,Liberation Sans,Liberation Serif,Lohit Bengali,Lohit Gujarati,Lohit Punjabi,Lohit Tamil,Luxi Mono,Luxi Sans,Luxi Serif,Meera,Nimbus Mono L,Nimbus Roman No9 L,Nimbus Sans L,Standard Symbols L,Tahoma,Times New Roman,Trebuchet MS,URW Bookman L,URW Chancery L,URW Gothic L,URW Palladio L,UnBatang,UnDotum,Verdana, Waree,Webdings
Aharoni,Andalus,Angsana New, AngsanaUPC,Aparajita,Arabic Typesetting,Arial Black,Arial, Batang,BatangChe,Browallia New,BrowalliaUPC,Calibri, Cambria Math,Cambria,Candara, Comic Sans MS,Consolas, Constantia,Corbel,Cordia New,CordiaUPC,Courier 10 Pitch,Courier New,David, DilleniaUPC,DokChampa, Dotum,DotumChe,Ebrima, Estrangelo Edessa,EucrosiaUPC, Euphemia,FangSong,FrankRuehl, Franklin Gothic Medium,LilyUPC, Lucida Bright,Lucida Console, Lucida Sans Typewriter,Tahoma, Times New Roman,Traditional Arabic,Wingdings

http:userAgent
10
Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.2 Safari/537.36
Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.110 Safari/537.36

Results:

None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for accessTime.

Because all of the attributes except for accessTime have mismatched values, the collective weight of the mismatched attributes is 30.

The total weight of all of the attributes is 80. The accessTime attribute has a weight value of 50. The http:userAgent attribute, browserPlugins attribute, and deviceFonts attribute each have weight values of 10.

According to the risk score calculation formula: (30/80)×100=38. Therefore, the risk score is 38.

Authentication is permitted because the risk score is below 40.

Scenario 2: Browser risk profile

The risk engine uses risk profile information in the following table to calculate the risk score.

Attributes
Weight values
Incoming device fingerprint values
Registered device fingerprint values

browserPlugins
50
Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for Linux
Shockwave Flash,Chrome Remote Desktop Viewer,Native Client, Chrome PDF Viewer, Conference Plugin, AmazonMP3DownloaderPlugin, Google Update

deviceFonts
50
Andale Mono,Arial Black,Arial,Bitstream Charter,Century Schoolbook L,Comic Sans MS,Courier 10 Pitch,Courier New,DejaVu Sans Mono,DejaVu Sans,DejaVu Serif,Dingbats,Georgia, Impact,Khmer OS System,Khmer OS,Liberation Mono,Liberation Sans,Liberation Serif,Lohit Bengali,Lohit Gujarati,Lohit Punjabi,Lohit Tamil,Luxi Mono,Luxi Sans,Luxi Serif,Meera,Nimbus Mono L,Nimbus Roman No9 L,Nimbus Sans L,Standard Symbols L,Tahoma,Times New Roman,Trebuchet MS,URW Bookman L,URW Chancery L,URW Gothic L,URW Palladio L,UnBatang,UnDotum,Verdana, Waree,Webdings
Aharoni,Andalus,Angsana New, AngsanaUPC,Aparajita,Arabic Typesetting,Arial Black,Arial, Batang,BatangChe,Browallia New,BrowalliaUPC,Calibri, Cambria Math,Cambria,Candara, Comic Sans MS,Consolas, Constantia,Corbel,Cordia New,CordiaUPC,Courier 10 Pitch,Courier New,David, DilleniaUPC,DokChampa, Dotum,DotumChe,Ebrima, Estrangelo Edessa,EucrosiaUPC, Euphemia,FangSong,FrankRuehl, Franklin Gothic Medium,LilyUPC, Lucida Bright,Lucida Console, Lucida Sans Typewriter,Tahoma, Times New Roman,Traditional Arabic,Wingdings

http:accept
30
text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

http:acceptEncoding
50
gzip,deflate,sdch
gzip,deflate,sdch

http:acceptLanguage
50
en-US,en;q=0.8
en-US,en;q=0.8,es;q=0.6

http:userAgent
50
Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.116 Safari/537.36
Mozilla/5.0 (X11; Linux i686 (x86_64)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.110 Safari/537.36

Results:

None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for http:accept and http:acceptEncoding.

Because all of the attributes except for http:accept and http:acceptEncoding have mismatched values, the collective weight of the mismatched attributes is 200.

The total weight of all of the attributes is 280. The http:accept attribute has a weight value of 30. The browserPlugins attribute, deviceFonts attribute, http:acceptEncoding attribute, http:acceptLanguage attribute, and http:userAgent attribute each have weight values of 50.

According to the risk score calculation formula: (200/280)×100=71. Therefore, the risk score is 71.

Authentication is denied because the risk score is above 40.

Scenario 3: Device risk profile

The risk engine uses risk profile information in the following table to calculate the risk score.

Attribute names
Weight values
Incoming device fingerprint values
Registered device fingerprint values

browserPlugins
30
Shockwave Flash,Chrome Remote Desktop Viewer,Widevine Content Decryption Module,Native Client,Chrome PDF Viewer,Java(TM) Plug-in 1.7.0,Citrix Receiver for Linux
Shockwave Flash,Chrome Remote Desktop Viewer,Native Client, Chrome PDF Viewer, Conference Plugin, AmazonMP3DownloaderPlugin, Google Update

colorDepth
50
24
32

deviceFonts
50
Andale Mono,Arial Black,Arial,Bitstream Charter,Century Schoolbook L,Comic Sans MS,Courier 10 Pitch,Courier New,DejaVu Sans Mono,DejaVu Sans,DejaVu Serif,Dingbats,Georgia, Impact,Khmer OS System,Khmer OS,Liberation Mono,Liberation Sans,Liberation Serif,Lohit Bengali,Lohit Gujarati,Lohit Punjabi,Lohit Tamil,Luxi Mono,Luxi Sans,Luxi Serif,Meera,Nimbus Mono L,Nimbus Roman No9 L,Nimbus Sans L,Standard Symbols L,Tahoma,Times New Roman,Trebuchet MS,URW Bookman L,URW Chancery L,URW Gothic L,URW Palladio L,UnBatang,UnDotum,Verdana, Waree,Webdings
Aharoni,Andalus,Angsana New, AngsanaUPC,Aparajita,Arabic Typesetting,Arial Black,Arial, Batang,BatangChe,Browallia New,BrowalliaUPC,Calibri, Cambria Math,Cambria,Candara, Comic Sans MS,Consolas, Constantia,Corbel,Cordia New,CordiaUPC,Courier 10 Pitch,Courier New,David, DilleniaUPC,DokChampa, Dotum,DotumChe,Ebrima, Estrangelo Edessa,EucrosiaUPC, Euphemia,FangSong,FrankRuehl, Franklin Gothic Medium,LilyUPC, Lucida Bright,Lucida Console, Lucida Sans Typewriter,Tahoma, Times New Roman,Traditional Arabic,Wingdings

deviceLanguage
50
en-US
en-US

devicePlatform
50
Linux x86_64
Win-32

screenAvailable Height
50
1025
870

screenAvailable Width
50
1920
1600

screenHeight
50
1080
900

screenWidth
50
1920
1600

Results:

None of the device fingerprint values match except for the incoming device fingerprint value and existing device fingerprint value for deviceLanguage.

Because all of the attributes except for deviceLanguage have mismatched values, the collective weight of the mismatched attributes is 380.

The total weight of all of the attributes is 430. The browserPlugins attribute has a weight value of 30. The following attributes have weight values of 50:

colorDepth

deviceFonts

deviceLanguage

devicePlatform

screenAvailableHeight

screenAvailableWidth

screenHeight

screenWidth

According to the risk score calculation formula: (380/430)×100=88. Therefore, the risk score is 88.

Authentication is denied because the risk score is above 40.

Scenario 4: Location risk profile

The risk engine uses risk profile information in the following table to calculate the risk score.

Attributes | Weight values | Incoming device fingerprint values | Registered device fingerprint values
geoCity | 10 | Austin | Austin
geoCountryCode | 10 | US | US
geoLocation | 50 | 30.2861, -97.739321, 10 | 30.274722, -97.740556, 13
geoRegionCode | 10 | TX | TX

Results:

All of the device fingerprint values match. The geoLocation attribute contains the values that the risk engine uses to calculate the distance between the incoming device fingerprint and the registered device fingerprint. In this instance, the distance between the two device fingerprints is 1.27 km.

Because all of the device fingerprint values match, the total weight of the mismatched attributes is 0.

The total weight of all of the attributes is 80. The geoLocation attribute has a weight value of 50. The geoCity attribute, geoCountryCode attribute, and geoRegionCode attribute each have weight values of 10.

According to the risk score calculation formula: (0/80)×100=0. Therefore, the risk score is 0.

Authentication is permitted because the risk score is below 40.

Parent topic: Risk profiles

Risk score calculation

Access control policiesAccess control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.The conditions are a combination of attributes, obligations, authentication policies, and a risk profile.Before you author a policy, review the available attributes, obligations, authentication policies, and risk profiles in the local management interface to determine if they meet the needs of your policy. Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.Managing obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.Managing authentication policiesAuthentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.Managing risk profilesA risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time.For more information, see Risk management overviewContext-based access policy decisions can be based on the risk score. The risk score is calculated based on the active risk profile attributes that are retrieved from the user..When all of the attributes, obligations, and authentication policies are available and the risk profile you want to use is set active, use the policy editor to select the conditions for your policy.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing access control policiesAn access control policy is a set of conditions that define whether a user is permitted or denied access to a protected resource.Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy.Managing access control policy setsA policy set is a group of policies that are used together to protect a resource.Managing access control policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced.Policy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Access control policies

An access control policy is a set of conditions that, after they have been evaluated, determine access decisions.

The conditions are a combination of attributes, obligations, authentication policies, and a risk profile.

Before you author a policy, review the available attributes, obligations, authentication policies, and risk profiles in the local management interface to determine if they meet the needs of your policy.

Managing attributes

Managing obligations

Managing authentication policies

Managing risk profiles

For more information, see Risk management overview.

When all of the attributes, obligations, and authentication policies are available and the risk profile you want to use is set active, use the policy editor to select the conditions for your policy.

Managing access control policies
An access control policy is a set of conditions that define whether a user is permitted or denied access to a protected resource.

Creating an access control policy
Use the Policy Editor on the appliance local management interface to create and configure an access control policy.

Managing access control policy sets
A policy set is a group of policies that are used together to protect a resource.

Managing access control policy attachments
Attach policies or API protection definitions to resources so that the policies and definitions can be enforced.

Policy scenarios
Several commonly used policy scenarios are provided as examples to help you author policies.

Parent topic: Advanced Access Control administration

Managing access control policiesAn access control policy is a set of conditions that define whether a user is permitted or denied access to a protected resource.policiesmanagingYou can view, create, edit, or delete an access control policy.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.Click All Policies.Perform one or more of the following actions:Search for and view policiesType one or more characters in the Filter field. The list displays the policies that start with those characters. Click either view icon:Details viewThe details view lists the name and description of the policy.List viewThe list view lists only the name of the policy.Create a policyClick Add. The Policy Editor opens. See Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy. for details.Edit a policySelect a policy in the policy list.Click Edit. The Policy Editor opens.Change the policy. See Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy. for details.Click Save.Delete one or more policiesSelect a policy or press Ctrl and select multiple policies in the policy list.Click Delete. A message prompts you to confirm the deletion.Click OK. The policy or policies are deleted.Add one or more polices to a policy setA policy set is a group of policies that are used together to protect a resource. To add policies to a policy set, see Managing access control policy setsA policy set is a group of policies that are used together to protect a resource..Import policyYou can import a policy from another appliance with Advanced Access Control. To import a policy, you must author it in the local management interface and export it using the Export function.Select All Policies in the left navigation.Click Import Policy Export Policy and select Import Policy.In the Import Policy dialog box, click Browse to locate the file. The policy file you import must have a .json extension. All custom attributes, obligations, and authentication policies referenced by the policy must exist for import to succeed. Click Import. The policy displays in the list of policies.Export policyYou can export a policy from the current appliance to use on another appliance. Select All Policies in the left navigation.From the list of policies, select a policy or press Ctrl and select multiple policies to export. Click Import Policy Export Policy and select Export Policy. Select the proper location and click Save.Access control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.

Managing access control policies

An access control policy is a set of conditions that define whether a user is permitted or denied access to a protected resource.

About this task

You can view, create, edit, or delete an access control policy.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

Click All Policies.

Perform one or more of the following actions:

Search for and view policies

Type one or more characters in the Filter field. The list displays the policies that start with those characters. Click either view icon:

The details view lists the name and description of the policy.

The list view lists only the name of the policy.

Create a policy

Click Add. The Policy Editor opens. See Creating an access control policy for details.

Edit a policy

Select a policy in the policy list.

Click Edit. The Policy Editor opens.

Change the policy. See Creating an access control policy for details.

Click Save.

Delete one or more policies

Select a policy or press Ctrl and select multiple policies in the policy list.

Click Delete. A message prompts you to confirm the deletion.

Click OK. The policy or policies are deleted.

Add one or more polices to a policy set

A policy set is a group of policies that are used together to protect a resource. To add policies to a policy set, see Managing access control policy sets.

Import policy

You can import a policy from another appliance with Advanced Access Control. To import a policy, you must author it in the local management interface and export it using the Export function.

Select All Policies in the left navigation.

Click Import Policy Export Policy and select Import Policy.

In the Import Policy dialog box, click Browse to locate the file.

The policy file you import must have a .json extension. All custom attributes, obligations, and authentication policies referenced by the policy must exist for import to succeed.

Click Import. The policy displays in the list of policies.

Export policy

You can export a policy from the current appliance to use on another appliance.

Select All Policies in the left navigation.

From the list of policies, select a policy or press Ctrl and select multiple policies to export.

Click Import Policy Export Policy and select Export Policy.

Select the proper location and click Save.

Parent topic: Access control policies

Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy.policycreatingEach policy is a combination of attributes, obligations or authentications, and a risk profile.Before you create an access control policy:Ensure that the attributes and obligations you want to use in the policy are defined and available in the local management interface:Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.Managing obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.Managing authentication policiesAuthentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.Ensure that the risk profile you want to use is set as active. See Managing risk profilesA risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time..The Policy Editor page has several sections:Name and descriptionSpecify a unique name for the policy and optionally include a description of the policy.SubjectsOptionally specify one or more subjects to which the policy applies. Subjects can be anything in the Subject part of an access request. For example, use this field to specify that the policy applies to subjects who are members of the SystemAdministrators group. Click Add subject Add Subject to add subjects to the policy. Click Remove subject to remove a subject from the policy. By specifying subjects, you can ensure that the policy rules are evaluated only if they match at least one of the specified subjects.RulesThe Rules section has several settings: PrecedenceSpecify an access action to take on the policy. DenyIf any rule in the policy returns deny, the policy returns deny.PermitIf any rule in the policy returns permit, the policy returns permit.FirstAccess is permitted or denied based on the outcome of first rule in the policy that can be evaluated against the access request. The rules in the policy are evaluated in the same order they are listed. The policy returns Not Applicable if none of the rules evaluates to true. To ensure that either a Permit or Deny decision is returned, include in the policy a Permit or Deny rule that does not contain a condition.AttributesWhen a policy is evaluated, the runtime will attempt to retrieve the values for all attributes that are specified in the policy. Attributes that are not found in the incoming request are considered missing. The Attributes setting controls how missing attributes are handled. OptionalIf Attributes is set to Optional, then all attributes specified in the Rule section of the policy are considered optional. With this setting, missing attributes are treated as empty sets and evaluated against the expression. In most cases, a missing attribute will cause the rule expression to return false.RequiredIf Attributes is set to Required, then all attributes specified in the Rule section of the policy are considered required. With this setting, missing attributes are considered an error and will return a decision of Indeterminate when the rule is evaluated. Indeterminate results often cause the access request to be denied.Add RuleClick the Add Rule drop-down arrow and select either: Conditional rule: This type of rule contains one or more conditions and an action. Rules are boolean expressions that are applied to a set of context attributes that are passed in the context object of the decision request. Each rule has an If statement and a Then statement. The If statement specifies the conditions that are checked when an access request is received. The Then statement specifies the action to take when the rule conditions are true.Unconditional rule: This type of rule contains only an action and no conditions.The rule actions are:PermitThe request must be permitted to pass.Permit with ObligationA specific action must take place before the request is permitted to pass. Specify the action in the adjacent field. Permit with AuthenticationA specific authentication action must take place before the request is permitted to pass. Specify the authentication policy in the adjacent field. For more information about authentication policies, see Authentication policiesAuthentication policies are workflows that dictate the authentication mechanisms to execute..DenyThe request must be denied and not permitted to pass.Deny with ObligationThe request is denied and an obligation is processed.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.In the center panel, click Add policy.In the Name field, type a unique name for the policy.The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.In the Description field, type a description for the policy. Specify subjects to which the policy applies.Click Add Subject.In the first box, select a subject attribute.Begin typing the name of the subject to filter the list.In the second box, select an operator.In the third box, type a value.For example, if you want the rule to be evaluated only if the access requestor belongs to the SecurityAdministrator group, specify the following selections:ParametergroupsOperator=ValueSecurityAdministratorIf your LDAP root DN is secauthority=default, you can only use the = (equal) operator in policies that use X.500 names userDN and groupsDN.To specify more subjects, click Add Subject.In the Rule section, add one or more rules.For Precedence, select the access action to take for the policy:For Attributes, select the attribute usage of the policy.To add a rule to the policy, click the Add Rule drop-down arrow and choose one of the following:Conditional rule: This type of rule contains one or more conditions and an action.Unconditional rule: This type of rule contains no conditions.If you create an unconditional rule, continue with step 8.h.If you are creating a Conditional rule, select whether the rules apply if All conditions are true or if Any of the conditions are true.Create a rule by typing or selecting a parameter, operator, and value.To specify a value in the value field, click the drop-down menu on the right and select either Enter Value or Select Attribute.Take one of the following actions: Click ! to add a NOT operator to the expression. If the expression already has a NOT operator, clicking ! removes the operator.Click + to add another expression. The new expression is added below the preceding expression.Click - to remove an expression.Click () to create a parenthetical expression. Select the appropriate attributes, operators, and values for the expression. Or, add more expressions to the group. The new expression is added below the preceding expression.Specify the action to take when the rule evaluation is completed.Click OK when the rule is complete.To add another rule to the policy, repeat step 8.c.If your policy has more than one rule, you can change the sequence of the rules by selecting a rule and clicking Move up or Move down.The sequence of the rules is important if you have selected First as the action for the policy.Click Save when the policy is complete.Attach the policy to a resource. See Managing access control policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced..Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes.Access control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.

Creating an access control policy

Use the Policy Editor on the appliance local management interface to create and configure an access control policy.

Before you begin

Each policy is a combination of attributes, obligations or authentications, and a risk profile.

Before you create an access control policy:

Ensure that the attributes and obligations you want to use in the policy are defined and available in the local management interface:

Managing attributes

Managing obligations

Managing authentication policies

Ensure that the risk profile you want to use is set as active. See Managing risk profiles.

About this task

The Policy Editor page has several sections:

Name and description

Specify a unique name for the policy and optionally include a description of the policy.

Subjects

Optionally specify one or more subjects to which the policy applies. Subjects can be anything in the Subject part of an access request. For example, use this field to specify that the policy applies to subjects who are members of the SystemAdministrators group. Click Add subject Add Subject to add subjects to the policy. Click Remove subject to remove a subject from the policy. By specifying subjects, you can ensure that the policy rules are evaluated only if they match at least one of the specified subjects.

Rules

The Rules section has several settings:

Precedence

Specify an access action to take on the policy.

Deny

If any rule in the policy returns deny, the policy returns deny.

Permit

If any rule in the policy returns permit, the policy returns permit.

First

Access is permitted or denied based on the outcome of first rule in the policy that can be evaluated against the access request. The rules in the policy are evaluated in the same order they are listed. The policy returns Not Applicable if none of the rules evaluates to true. To ensure that either a Permit or Deny decision is returned, include in the policy a Permit or Deny rule that does not contain a condition.

Attributes

When a policy is evaluated, the runtime will attempt to retrieve the values for all attributes that are specified in the policy. Attributes that are not found in the incoming request are considered missing. The Attributes setting controls how missing attributes are handled.

Optional

If Attributes is set to Optional, then all attributes specified in the Rule section of the policy are considered optional. With this setting, missing attributes are treated as empty sets and evaluated against the expression. In most cases, a missing attribute will cause the rule expression to return false.

Required

If Attributes is set to Required, then all attributes specified in the Rule section of the policy are considered required. With this setting, missing attributes are considered an error and will return a decision of Indeterminate when the rule is evaluated. Indeterminate results often cause the access request to be denied.

Add Rule

Click the Add Rule drop-down arrow and select either:

Conditional rule: This type of rule contains one or more conditions and an action. Rules are boolean expressions that are applied to a set of context attributes that are passed in the context object of the decision request. Each rule has an If statement and a Then statement. The If statement specifies the conditions that are checked when an access request is received. The Then statement specifies the action to take when the rule conditions are true.

Unconditional rule: This type of rule contains only an action and no conditions.

The rule actions are:

Permit

The request must be permitted to pass.

Permit with Obligation

A specific action must take place before the request is permitted to pass. Specify the action in the adjacent field.

Permit with Authentication

A specific authentication action must take place before the request is permitted to pass. Specify the authentication policy in the adjacent field. For more information about authentication policies, see Authentication policies.

Deny

The request must be denied and not permitted to pass.

Deny with Obligation

The request is denied and an obligation is processed.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

In the center panel, click Add policy.

In the Name field, type a unique name for the policy.

Note: The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.

Optional: In the Description field, type a description for the policy.

Optional: Specify subjects to which the policy applies.

Click Add Subject.

In the first box, select a subject attribute. Begin typing the name of the subject to filter the list.

In the second box, select an operator.

In the third box, type a value.

For example, if you want the rule to be evaluated only if the access requestor belongs to the SecurityAdministrator group, specify the following selections:

Parameter

groups

Operator

=

Value

SecurityAdministrator

Note: If your LDAP root DN is secauthority=default, you can only use the = (equal) operator in policies that use X.500 names userDN and groupsDN.

To specify more subjects, click Add Subject.

In the Rule section, add one or more rules.

For Precedence, select the access action to take for the policy:

For Attributes, select the attribute usage of the policy.

To add a rule to the policy, click the Add Rule drop-down arrow and choose one of the following:

Conditional rule: This type of rule contains one or more conditions and an action.

Unconditional rule: This type of rule contains no conditions.

If you create an unconditional rule, continue with step 8.h.

If you are creating a Conditional rule, select whether the rules apply if All conditions are true or if Any of the conditions are true.

Create a rule by typing or selecting a parameter, operator, and value. To specify a value in the value field, click the drop-down menu on the right and select either Enter Value or Select Attribute.

Take one of the following actions:

Click ! to add a NOT operator to the expression. If the expression already has a NOT operator, clicking ! removes the operator.

Click + to add another expression. The new expression is added below the preceding expression.

Click - to remove an expression.

Click () to create a parenthetical expression. Select the appropriate attributes, operators, and values for the expression. Or, add more expressions to the group. The new expression is added below the preceding expression.

Specify the action to take when the rule evaluation is completed.

Click OK when the rule is complete.

To add another rule to the policy, repeat step 8.c.

If your policy has more than one rule, you can change the sequence of the rules by selecting a rule and clicking Move up or Move down.

Note: The sequence of the rules is important if you have selected First as the action for the policy.

Click Save when the policy is complete.

What to do next

Attach the policy to a resource. See Managing access control policy attachments.

Parent topic: Access control policies

Related reference:

Predefined attributes

Managing access control policy setsA policy set is a group of policies that are used together to protect a resource.policy setsmanagingYou must create access control policies. See Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy..You can view, create, modify, or delete a policy set.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.Perform one or more of the following actions:Create a policy setClick Create policy set.Type a name for the policy set in the Name field. The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.Optionally, type a description in the Description field.In the Policy Combining Algorithm dialog, set the combined action for the policy set by choosing one of the following options:Deny access if any policy in the set returns denyChoose this option if you want the policy set to deny access if any policy in the set returns a response of deny.Permit access if any policy in the set returns permitChoose this option if you want the policy set to permit access if any policy in the set returns a response of permit.Return the decision of the first policy in the set that returns either permit or denyThe policies are evaluated in the order they are listed in the set. Choose this option if you want to use the first policy that returns a response of permit or deny as the result of the policy set.Click Save.Click OK.Next, add one or more policies to the policy set.Add one or more policies to a policy setClick All Policies.Select a policy or press Ctrl and select multiple policies to add to the policy set.Click Add To Add To.Select a policy set.Click OK.Change the order of the policies in a setIf you selected Return the decision of the first policy in the set that returns either permit or deny, set the order in which you want the policies to run:Select a policy set.Select a policy.Click Move up or Move down to change the position of the policy in the set.Modify a policy setSelect a policy set in the list of policy sets.Click Modify policy set.Change to the name, description, or policy combining algorithm. The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.Click Save.Remove one or more policies from a policy setSelect a policy set in the list of policy sets.Select a policy or press Ctrl and select multiple policies to remove from the policy set.Click Remove Remove. Confirm the removal. When you remove a policy from a set, the policy is not deleted from the policy list. To delete a policy from the list, see Managing access control policiesAn access control policy is a set of conditions that define whether a user is permitted or denied access to a protected resource..Click OK. The policy is removed.Delete a policy setSelect a policy set in the list of policy sets.Click Delete. Confirm the deletion.Click OK. The policy set is deleted.Access control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.

Managing access control policy sets

A policy set is a group of policies that are used together to protect a resource.

Before you begin

You must create access control policies. See Creating an access control policy.

About this task

You can view, create, modify, or delete a policy set.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

Perform one or more of the following actions:

Create a policy set

Click Create policy set.

Type a name for the policy set in the Name field.

Note: The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.

Optionally, type a description in the Description field.

In the Policy Combining Algorithm dialog, set the combined action for the policy set by choosing one of the following options:

Deny access if any policy in the set returns deny

Choose this option if you want the policy set to deny access if any policy in the set returns a response of deny.

Permit access if any policy in the set returns permit

Choose this option if you want the policy set to permit access if any policy in the set returns a response of permit.

Return the decision of the first policy in the set that returns either permit or deny

The policies are evaluated in the order they are listed in the set. Choose this option if you want to use the first policy that returns a response of permit or deny as the result of the policy set.

Click Save.

Click OK.

Next, add one or more policies to the policy set.

Add one or more policies to a policy set

Click All Policies.

Select a policy or press Ctrl and select multiple policies to add to the policy set.

Click Add To Add To.

Select a policy set.

Click OK.

Change the order of the policies in a set

If you selected Return the decision of the first policy in the set that returns either permit or deny, set the order in which you want the policies to run:

Select a policy set.

Select a policy.

Click Move up or Move down to change the position of the policy in the set.

Modify a policy set

Select a policy set in the list of policy sets.

Click Modify policy set.

Change to the name, description, or policy combining algorithm.

Note: The name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( )  + | ` = \ ; :  " ' < > ? , [  ] { } / anywhere in the name.

Click Save.

Remove one or more policies from a policy set

Select a policy set in the list of policy sets.

Select a policy or press Ctrl and select multiple policies to remove from the policy set.

Click Remove Remove. Confirm the removal.

Note: When you remove a policy from a set, the policy is not deleted from the policy list. To delete a policy from the list, see Managing access control policies.

Click OK. The policy is removed.

Delete a policy set

Select a policy set in the list of policy sets.

Click Delete. Confirm the deletion.

Click OK. The policy set is deleted.

Parent topic: Access control policies

Managing access control policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced.policypublishingpolicyattaching to resourceAPI definitionpublishingAPI definitionattaching to resourceYou must create policies, policy sets, or API protection definitions. You cannot use them until you publish them to resources. After publication, they are enforced during the evaluation of access requests.Since policies and API protection definitions are attached to resources, you must first configure resources. This means that policy and API protection definition attachment requires an installed and configured IBM Security Access Manager runtime component and reverse proxy server. The configuration tasks must include creating a Security Access Manager protected object space. In a Security Access Manager environment, this configuration includes creation of a junction and resources (objects) that are protected by that junction. You can perform the following tasks:Add a resourceAdd a policy or API protection definition attachment to a resourceRemove a policy or API protection definition attachment from a resourceDelete a resourcePublish a policy or API protection definition attachmentWhen a deployment is fully configured, the Resources panel displays three levels of entries. The top-level entry is the web container for the protected object space for a server instance. The second level shows the resources in the protected object space. The third level lists the policies and API protection definitions that are attached to each resource.The user interface provides a quick filter feature for the top-level entry. Use the quick filter to search for a specific top-level entry. Enter the first few characters of the web container, and the list displays only the entries that contain the specified characters.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.Click Resources.Perform one or more of the following actions:Add a resource If you need to add a resource from a custom domain, see Defining a custom domain for policy attachmentsThe administrator can specify a custom domain to separate metadata in a registry. For example, your company might possess metadata that belongs to several companies, and it is a security demand that the data does not overlap..Click Add.When you add a resource for the first time, the system prompts you to enter the user name, password, and domain for the Security Access Manager policy server. The entered information is cached and used by default when you add a resource again. If you want to change this domain, click Change Domain and then enter the new user name, password, and domain information. This new information replaces the old cached values.In the Web Container field, click the down arrow icon to display a list of web containers. Select an entry.For example, the list of web containers is the WebSEAL protected object space that is defined directly under /WebSEAL.Specify a resource by entering its name or browsing for it. When you browse, you can expand the list of resources. The list hierarchy is based on the structure of the WebSEAL protected object space.In some cases, not all resources are displayed because the WebSEAL protected object space is a sparse tree. For example, you might see only the resource /myserver-jct/benefits. You can select this resource and click OK to add it to the Resource. You can then add /myserver-jct/benefits/medical.In some cases, you cannot view the object space for the web server junction. For example, if the administrator did not install the IBM Security Access Manager querycontents script on the application server, you cannot see the junction contents. In these cases, you can enter the resource path manually.Click Save.Attach a policy to the resource.Attach a policy or API protection definition to a resourceSelect a resource node and click Attach Attach.In the Attach Policies panel, select Policies or Policy Sets or API Protection.From the list, select one or more items.You can type the name in the quick filter. You can attach both individual policies, policy sets, or API protection definitions.You cannot attach policies or policy sets to a resource where that resource already has API protection definitions attached.You cannot attach API protection definitions to a resource where that resource already has policies and policy sets attached. Click OK to save your changes.The policy or API protection definition remains inactive until you publish it.Remove a policy or API protection definition attachmentTo remove a policy or API protection definition attachment from a resource, select the policy node and click Remove.When prompted, confirm the deletion.You must publish the change.Delete a resource When you delete a resource:Be aware of the status of the reverse proxy server that the resource is attached to before deleting it:If the reverse proxy server is defined but not available for use, restart the server first. Then, follow the instructions below to delete the resource from the local management interface.If the reverse proxy server has been deleted, force the delete of the resource to remove it from the local management interface.You cannot delete the server node.To delete a resource and all attached policies or API protection definitions, select the resource node and click Remove.When prompted, confirm the deletion. You do not have to manually publish the change. The deletion is automatically published.Publish policies or API protection definitions Publish a specific policy or API protection definition, or publish all of them at once: Publish: Select a resource in the resource hierarchy and click Publish Publish. When the publication completes, the status column for the resource indicates the status and time of the publication.Publish All: Click Publish All Publish All and then respond to the confirmation. This action publishes only those policies or API protection definitions that have a status of Publish required. When the publication completes, the status column for the resources indicates the status and time of the publication. Activation of a single published policy or API protection definition might take up to a minute to complete.Modify ResourceYou can use this function only if policy or policy sets are attached to the resource.Select a resource node and click Edit.In the Modify Resource panel, you can modify the Policy Combining Algorithm. Choose the preferred algorithm:Deny access if any attached policy returns denyIf both of the following statements are true, then the access request is denied.Multiple policies or API protection definitions are attached to a resource.Any one of the policies or API protection definitions returns Deny.Permit access if any attached policy returns permitIf any one of the following statements is true, then the access request is permitted.Multiple policies or API protection definitions are attached to a resource.Any one of the policies or API protection definitions returns Permit.Access control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.

Managing access control policy attachments

Attach policies or API protection definitions to resources so that the policies and definitions can be enforced.

Before you begin

You must create policies, policy sets, or API protection definitions. You cannot use them until you publish them to resources. After publication, they are enforced during the evaluation of access requests.

Since policies and API protection definitions are attached to resources, you must first configure resources. This means that policy and API protection definition attachment requires an installed and configured IBM Security Access Manager runtime component and reverse proxy server. The configuration tasks must include creating a Security Access Manager protected object space. In a Security Access Manager environment, this configuration includes creation of a junction and resources (objects) that are protected by that junction.

About this task

You can perform the following tasks:

Add a resource

Add a policy or API protection definition attachment to a resource

Remove a policy or API protection definition attachment from a resource

Delete a resource

Publish a policy or API protection definition attachment

When a deployment is fully configured, the Resources panel displays three levels of entries. The top-level entry is the web container for the protected object space for a server instance. The second level shows the resources in the protected object space. The third level lists the policies and API protection definitions that are attached to each resource.

Tip: The user interface provides a quick filter feature for the top-level entry. Use the quick filter to search for a specific top-level entry. Enter the first few characters of the web container, and the list displays only the entries that contain the specified characters.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

Click Resources.

Perform one or more of the following actions:

Add a resource

If you need to add a resource from a custom domain, see Defining a custom domain for policy attachments.

Click Add.

Note: When you add a resource for the first time, the system prompts you to enter the user name, password, and domain for the Security Access Manager policy server. The entered information is cached and used by default when you add a resource again. If you want to change this domain, click Change Domain and then enter the new user name, password, and domain information. This new information replaces the old cached values.

In the Web Container field, click the down arrow icon to display a list of web containers. Select an entry.

For example, the list of web containers is the WebSEAL protected object space that is defined directly under /WebSEAL.

Specify a resource by entering its name or browsing for it. When you browse, you can expand the list of resources. The list hierarchy is based on the structure of the WebSEAL protected object space.

In some cases, not all resources are displayed because the WebSEAL protected object space is a sparse tree. For example, you might see only the resource /myserver-jct/benefits. You can select this resource and click OK to add it to the Resource. You can then add /myserver-jct/benefits/medical.

In some cases, you cannot view the object space for the web server junction. For example, if the administrator did not install the IBM Security Access Manager querycontents script on the application server, you cannot see the junction contents. In these cases, you can enter the resource path manually.

Click Save.

Attach a policy to the resource.

Attach a policy or API protection definition to a resource

Select a resource node and click Attach Attach.

In the Attach Policies panel, select Policies or Policy Sets or API Protection.

From the list, select one or more items.

Tip: You can type the name in the quick filter.

Notes:

You can attach both individual policies, policy sets, or API protection definitions.

You cannot attach policies or policy sets to a resource where that resource already has API protection definitions attached.

You cannot attach API protection definitions to a resource where that resource already has policies and policy sets attached.

Click OK to save your changes.

Note: The policy or API protection definition remains inactive until you publish it.

Remove a policy or API protection definition attachment

To remove a policy or API protection definition attachment from a resource, select the policy node and click Remove.

When prompted, confirm the deletion.

Note: You must publish the change.

Delete a resource

Note: When you delete a resource:

Be aware of the status of the reverse proxy server that the resource is attached to before deleting it:

If the reverse proxy server is defined but not available for use, restart the server first. Then, follow the instructions below to delete the resource from the local management interface.

If the reverse proxy server has been deleted, force the delete of the resource to remove it from the local management interface.

You cannot delete the server node.

To delete a resource and all attached policies or API protection definitions, select the resource node and click Remove.

When prompted, confirm the deletion.

You do not have to manually publish the change. The deletion is automatically published.

Publish policies or API protection definitions

Publish a specific policy or API protection definition, or publish all of them at once:

Publish: Select a resource in the resource hierarchy and click Publish Publish. When the publication completes, the status column for the resource indicates the status and time of the publication.

Publish All: Click Publish All Publish All and then respond to the confirmation. This action publishes only those policies or API protection definitions that have a status of "Publish required".

When the publication completes, the status column for the resources indicates the status and time of the publication.

Note: Activation of a single published policy or API protection definition might take up to a minute to complete.

Modify Resource

Note: You can use this function only if policy or policy sets are attached to the resource.

Select a resource node and click Edit.

In the Modify Resource panel, you can modify the Policy Combining Algorithm. Choose the preferred algorithm:

Deny access if any attached policy returns deny

If both of the following statements are true, then the access request is denied.

Multiple policies or API protection definitions are attached to a resource.

Any one of the policies or API protection definitions returns Deny.

Permit access if any attached policy returns permit

If any one of the following statements is true, then the access request is permitted.

Multiple policies or API protection definitions are attached to a resource.

Any one of the policies or API protection definitions returns Permit.

Parent topic: Access control policies

Policy scenariosPolicy scenariosPolicy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.policiesscenariosexamplesAccess control policiesAn access control policy is a set of conditions that, after they have been evaluated, determine access decisions.Denying access based on a set of conditionsA common policy scenario is to deny access based on a set of conditions.Denying access based on a set of conditions with an OR clauseA common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is denied if either of the policy conditions that are joined by Or are true.Permitting access based on a set of conditions with an AND clauseA common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is permitted if both of the policy conditions that are joined by And are true.Permitting access after one-time password authenticationSecurity Access Manager can prompt users for one-time passwords when they request access to protected resources. You can use a policy to permit access to users who authenticated with a one-time password. Or, you can prompt them for the password and then permit access when they provide it.Enforcing an authentication policy for every access per sessionYou can enforce an authentication policy once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationTypes credential attribute to determine which authentication policies the user successfully completed during the authentication session.Enforcing an authentication mechanism once per sessionYou can enforce an authentication mechanism once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationMechanismTypes credential attributes to determine which authentication mechanisms the user successfully completed during the authentication session.Registering a device after user consentDevice registration is the process that stores the device fingerprint of the user in the risk-based access database. The rules that you specify in a policy determine whether a device is registered silently or only after the user consents to the registration.

Policy scenarios

Several commonly used policy scenarios are provided as examples to help you author policies.

Denying access based on a set of conditions
A common policy scenario is to deny access based on a set of conditions.

Denying access based on a set of conditions with an OR clause
A common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is denied if either of the policy conditions that are joined by Or are true.

Permitting access based on a set of conditions with an AND clause
A common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is permitted if both of the policy conditions that are joined by And are true.

Permitting access after one-time password authentication
Security Access Manager can prompt users for one-time passwords when they request access to protected resources. You can use a policy to permit access to users who authenticated with a one-time password. Or, you can prompt them for the password and then permit access when they provide it.

Enforcing an authentication policy for every access per session
You can enforce an authentication policy once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationTypes credential attribute to determine which authentication policies the user successfully completed during the authentication session.

Enforcing an authentication mechanism once per session
You can enforce an authentication mechanism once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationMechanismTypes credential attributes to determine which authentication mechanisms the user successfully completed during the authentication session.

Registering a device after user consent
Device registration is the process that stores the device fingerprint of the user in the risk-based access database. The rules that you specify in a policy determine whether a device is registered silently or only after the user consents to the registration.

Parent topic: Access control policies

Denying access based on a set of conditionsDenying access based on a set of conditionsDeny access based on a set of conditionsA common policy scenario is to deny access based on a set of conditions.policy scenariodeny access using conditionsUse the steps in this scenario task to create a policy that denies access if any of the following conditions are true.The calculated risk score is higher than a value of 40.The reputation of the ipAddress in the request is considered malware.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.In the center panel, click Add policy.Enter a name for the policy.In the Rules section, set the Precedence property to Deny.As a result, access is denied if any rule returns deny.Click Add Rule.Select riskScore from the attribute list.Select > as the operator.Type 40 as the value.In the Decision list, select Deny.Click OK to complete the rule.Click Add Rule to add another rule.Select ipReputation from the attribute list.Select has member as the operator.Type Malware as the value.In the Decision list, select Deny.Click OK to complete the rule.Click the arrow next to Add Rule.Click Unconditional rule.In the Decision list, select Permit.The unconditional Permit rule causes the policy to permit access if none of the deny access rules evaluate to true.Click OK.This scenario uses the following settings in the policy editor.Precedence: DenyAttributes: OptionalRule 1: If riskScore >40 Then DenyRule 2: If ipReputation has member Malware Then DenyRule 3: PermitPolicy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Denying access based on a set of conditions

A common policy scenario is to deny access based on a set of conditions.

About this task

Use the steps in this scenario task to create a policy that denies access if any of the following conditions are true.

The calculated risk score is higher than a value of 40.

The reputation of the ipAddress in the request is considered malware.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

In the center panel, click Add policy.

Enter a name for the policy.

In the Rules section, set the Precedence property to Deny. As a result, access is denied if any rule returns deny.

Click Add Rule.

Select riskScore from the attribute list.

Select > as the operator.

Type 40 as the value.

In the Decision list, select Deny.

Click OK to complete the rule.

Click Add Rule to add another rule.

Select ipReputation from the attribute list.

Select has member as the operator.

Type Malware as the value.

In the Decision list, select Deny.

Click OK to complete the rule.

Click the arrow next to Add Rule.

Click Unconditional rule.

In the Decision list, select Permit. The unconditional Permit rule causes the policy to permit access if none of the deny access rules evaluate to true.

Click OK.

Results

This scenario uses the following settings in the policy editor.

Precedence: Deny

Attributes: Optional

Rule 1: If riskScore >40 Then Deny

Rule 2: If ipReputation has member Malware Then Deny

Rule 3: Permit

Parent topic: Policy scenarios

Denying access based on a set of conditions with an OR clauseDenying access based on a set of conditions with an OR clauseDeny access based on a set of conditions with an OR clauseA common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is denied if either of the policy conditions that are joined by Or are true.policy scenariodeny access with OR clauseUse the steps in this scenario task to create a policy that denies access if either of the following conditions are true:The calculated risk score is higher than a value of 40.The reputation of the ipAddress in the request is considered malware.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.In the center panel, click Add policy.Enter a name for the policy.In the Rules section, set the Precedence property to Deny.As a result, access is denied if any rule returns deny.Click Add Rule.Click If Any are true.The rule evaluates to true if any of the conditions in the rule are true.Select riskScore from the attribute list.Select > as the operator.Type 40 as the value.Click Add condition to add another condition to the rule.Select ipReputation from the attribute list.Select has member as the operator.Type Malware as the value.In the Decision list, select Deny.Click OK to complete the rule.Click the arrow next to Add Rule.Click Unconditional rule.In the Decision list, select Permit.The unconditional Permit rule causes the policy to permit access if none of the deny access rules evaluate to true.Click OK.This scenario uses the following settings in the policy editor.Precedence: DenyAttributes: OptionalRule 1: If riskScore >40 or ipReputation has member Malware Then DenyRule 2: PermitPolicy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Denying access based on a set of conditions with an OR clause

A common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is denied if either of the policy conditions that are joined by Or are true.

About this task

Use the steps in this scenario task to create a policy that denies access if either of the following conditions are true:

The calculated risk score is higher than a value of 40.

The reputation of the ipAddress in the request is considered malware.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

In the center panel, click Add policy.

Enter a name for the policy.

In the Rules section, set the Precedence property to Deny. As a result, access is denied if any rule returns deny.

Click Add Rule.

Click If Any are true. The rule evaluates to true if any of the conditions in the rule are true.

Select riskScore from the attribute list.

Select > as the operator.

Type 40 as the value.

Click Add condition to add another condition to the rule.

Select ipReputation from the attribute list.

Select has member as the operator.

Type Malware as the value.

In the Decision list, select Deny.

Click OK to complete the rule.

Click the arrow next to Add Rule.

Click Unconditional rule.

In the Decision list, select Permit. The unconditional Permit rule causes the policy to permit access if none of the deny access rules evaluate to true.

Click OK.

Results

This scenario uses the following settings in the policy editor.

Precedence: Deny

Attributes: Optional

Rule 1: If riskScore >40 or ipReputation has member Malware Then Deny

Rule 2: Permit

Parent topic: Policy scenarios

Permitting access based on a set of conditions with an AND clausePermitting access based on a set of conditions with an AND clausePermit access based on a set of conditions with an AND clauseA common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is permitted if both of the policy conditions that are joined by And are true.policy scenariopermit access using AND clauseUse the steps in this scenario task to create a policy that permits access if both of the following conditions are true:The calculated risk score is less than or equal to a value of 40.The reputation of the ipAddress in the request is not considered malware.Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.In the center panel, click Add policy.Enter a name for the policy.In the Rules section, set the Precedence property to Permit.As a result, access is permitted if any rule returns permit.Click Add Rule.Click If all are true.The rule evaluates to true if all of the conditions in the rule are true.Select riskScore from the attribute list.Select <= as the operator.Type 40 as the value.Click Add condition to add another condition to the rule.Select ipReputation from the attribute list.Select has member as the operator.Type Malware as the value.Click Not operator to convert the condition to a Not condition.In the Decision list, select Permit.Click OK to complete the rule.Click the arrow next to Add Rule.Click Unconditional rule.In the Decision list, select Deny.The unconditional Deny rule causes the policy to deny access if none of the permit access rules evaluate to true.Click OK.This scenario uses the following settings in the policy editor.Precedence: PermitAttributes: OptionalRule 1: If riskScore <=40 and not (ipReputation has member Malware) Then PermitRule 2: DenyPolicy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Permitting access based on a set of conditions with an AND clause

A common policy scenario is to use multiple conditions in a single rule and to join those conditions with And or Or. In this scenario, access is permitted if both of the policy conditions that are joined by And are true.

About this task

Use the steps in this scenario task to create a policy that permits access if both of the following conditions are true:

The calculated risk score is less than or equal to a value of 40.

The reputation of the ipAddress in the request is not considered malware.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

In the center panel, click Add policy.

Enter a name for the policy.

In the Rules section, set the Precedence property to Permit. As a result, access is permitted if any rule returns permit.

Click Add Rule.

Click If all are true. The rule evaluates to true if all of the conditions in the rule are true.

Select riskScore from the attribute list.

Select <= as the operator.

Type 40 as the value.

Click Add condition to add another condition to the rule.

Select ipReputation from the attribute list.

Select has member as the operator.

Type Malware as the value.

Click Not operator to convert the condition to a Not condition.

In the Decision list, select Permit.

Click OK to complete the rule.

Click the arrow next to Add Rule.

Click Unconditional rule.

In the Decision list, select Deny. The unconditional Deny rule causes the policy to deny access if none of the permit access rules evaluate to true.

Click OK.

Results

This scenario uses the following settings in the policy editor.

Precedence: Permit

Attributes: Optional

Rule 1: If riskScore <=40 and not (ipReputation has member Malware) Then Permit

Rule 2: Deny

Parent topic: Policy scenarios

Permitting access after one-time password authenticationPermitting access after one-time password authenticationPermit access after one-time password authenticationSecurity Access Manager can prompt users for one-time passwords when they request access to protected resources. You can use a policy to permit access to users who authenticated with a one-time password. Or, you can prompt them for the password and then permit access when they provide it.policy scenariopermit access using one-time passwordone-time passwordscenario exampleConfigure the TOTP one-time password mechanism. See Configuring a TOTP one-time password mechanismThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password..Use the steps in this scenario task to create a policy that permits access after the user authenticates with a one-time password. Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.In the center panel, click Add policy.Enter a name for the policy.In the Rules section, set the Precedence property to First.As a result, the policy returns a decision for the first rule in the policy that evaluates to true.Click Add Rule.Select authenticationTypes from the attribute list.Select has member as the operator.Type urn:ibm:security:authentication:asf:totp as the value.If this value is present, the request was already authenticated with a one-time password.In the Decision list, select Permit.Click OK to complete the rule.Click the arrow next to Add Rule.Click Unconditional rule.In the Decision list, select Permit with authentication.In the Authentication list, select TOTP One-time Password.This selection results in a request for a one-time password from the user.Click OK.This scenario uses the following settings in the policy editor.Precedence: FirstAttributes: OptionalRule 1: If authenticationTypes has member "urn:ibm:security:authentication:asf:totp" Then PermitRule 2: Permit with Authentication TOTP One-time PasswordPolicy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Permitting access after one-time password authentication

Security Access Manager can prompt users for one-time passwords when they request access to protected resources. You can use a policy to permit access to users who authenticated with a one-time password. Or, you can prompt them for the password and then permit access when they provide it.

Before you begin

Configure the TOTP one-time password mechanism. See Configuring a TOTP one-time password mechanism.

About this task

Use the steps in this scenario task to create a policy that permits access after the user authenticates with a one-time password.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

In the center panel, click Add policy.

Enter a name for the policy.

In the Rules section, set the Precedence property to First. As a result, the policy returns a decision for the first rule in the policy that evaluates to true.

Click Add Rule.

Select authenticationTypes from the attribute list.

Select has member as the operator.

Type urn:ibm:security:authentication:asf:totp as the value. If this value is present, the request was already authenticated with a one-time password.

In the Decision list, select Permit.

Click OK to complete the rule.

Click the arrow next to Add Rule.

Click Unconditional rule.

In the Decision list, select Permit with authentication.

In the Authentication list, select TOTP One-time Password. This selection results in a request for a one-time password from the user.

Click OK.

Results

This scenario uses the following settings in the policy editor.

Precedence: First

Attributes: Optional

Rule 1: If authenticationTypes has member "urn:ibm:security:authentication:asf:totp" Then Permit

Rule 2: Permit with Authentication TOTP One-time Password

Parent topic: Policy scenarios

Enforcing an authentication policy for every access per sessionReauthentication scenarioYou can enforce an authentication policy once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationTypes credential attribute to determine which authentication policies the user successfully completed during the authentication session.reauthenticationscenarioUse this task to enforce a particular authentication policy every time the user accesses a protected resource during a session. Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.In the center panel, click Add policy.Enter a name for the policy.In the Rules section, set the Precedence property to First.As a result, the policy returns a decision for the first rule in the policy that evaluates to true.Click Add Rule.Click authenticationTypes from the attribute list.Select has member as the operator.Enter the unique identifier for the policy. For example, to enforce only the user name and password policy add the value: urn:ibm:security:authentication:asf:password.In the Decision list, select Permit.Click OK to complete the rule.Click the arrow next to Add Rule.Click Unconditional rule.In the Decision list, select Permit with authentication.In the Authentication list, select Username Password.This selection results in request for a user name password from the user.Click OK.This scenario uses the following settings in the policy editor: Precedence: FirstAttributes: OptionalRule 1: If authenicationTypes has member urn:ibm:security:authentication:asf:password Then PermitRule 2: If Permit with Authentication Username Password Policy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Enforcing an authentication policy for every access per session

You can enforce an authentication policy once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationTypes credential attribute to determine which authentication policies the user successfully completed during the authentication session.

About this task

Use this task to enforce a particular authentication policy every time the user accesses a protected resource during a session.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

In the center panel, click Add policy.

Enter a name for the policy.

In the Rules section, set the Precedence property to First. As a result, the policy returns a decision for the first rule in the policy that evaluates to true.

Click Add Rule.

Click authenticationTypes from the attribute list.

Select has member as the operator.

Enter the unique identifier for the policy. For example, to enforce only the user name and password policy add the value: urn:ibm:security:authentication:asf:password.

In the Decision list, select Permit.

Click OK to complete the rule.

Click the arrow next to Add Rule.

Click Unconditional rule.

In the Decision list, select Permit with authentication.

In the Authentication list, select Username Password. This selection results in request for a user name password from the user.

Click OK.

Results

This scenario uses the following settings in the policy editor:

Precedence: First

Attributes: Optional

Rule 1: If authenicationTypes has member urn:ibm:security:authentication:asf:password Then Permit

Rule 2: If Permit with Authentication Username Password

Parent topic: Policy scenarios

Enforcing an authentication mechanism once per sessionYou can enforce an authentication mechanism once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationMechanismTypes credential attributes to determine which authentication mechanisms the user successfully completed during the authentication session.reauthenticationscenarioUse this task to enforce a particular authentication mechanism only once during the user's authenticated session. This scenario uses the Username Password and MAC One-time Password mechanisms. However, you can use any authentication mechanisms.Log in to the local management interface.Click Secure Access Control.Under Policy, click Authentication.In the center panel, click Add policy.Enter the name of the custom authentication policy.Enter the Identifier.In the Workflow Steps section, click Add step Add Step. Select Username Password and click OK.Click Parameter .Select the Pass check box for the reauthenticate parameter.Select Value in the Source field.Select False in the Value field.Click OK.In the Workflow Steps section, click Add stepAdd Step.Select MAC One-time Password.Click OK.Click Save.Under Policy, click Access Control.In the center panel, click Add policy.Enter a name for the policy. In the Rules section, set the Precedence property to First. As a result, the policy returns a decision for the first rule in the policy that evaluates to true.Click Add Unconditional Rule.In the Decision list, select Permit with authentication.In the Authentication list, select the name of the custom authentication policy that is created in step 5.Click OK.Click Save.This scenario uses the following settings in the policy editor: Precedence: FirstAttributes: OptionalRule 1: An Unconditional Rule that enforces a Permit with Authentication with a custom Two-Factor authentication policy. If the Username Password mechanism was completed by the user during the authenticated session, the user is required to provide only the MAC one-time password as indicated by the second workflow step.Policy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Enforcing an authentication mechanism once per session

You can enforce an authentication mechanism once per session or every time a user accesses a protected resource. In this scenario, the authentication service relies on the authenticationMechanismTypes credential attributes to determine which authentication mechanisms the user successfully completed during the authentication session.

About this task

Use this task to enforce a particular authentication mechanism only once during the user's authenticated session. This scenario uses the Username Password and MAC One-time Password mechanisms. However, you can use any authentication mechanisms.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

In the center panel, click Add policy.

Enter the name of the custom authentication policy.

Enter the Identifier.

In the Workflow Steps section, click Add step Add Step.

Select Username Password and click OK.

Click Parameter List view.

Select the Pass check box for the reauthenticate parameter.

Select Value in the Source field.

Select False in the Value field.

Click OK.

In the Workflow Steps section, click Add stepAdd Step.

Select MAC One-time Password.

Click OK.

Click Save.

Under Policy, click Access Control.

In the center panel, click Add policy.

Enter a name for the policy.

In the Rules section, set the Precedence property to First. As a result, the policy returns a decision for the first rule in the policy that evaluates to true.

Click Add Unconditional Rule.

In the Decision list, select Permit with authentication.

In the Authentication list, select the name of the custom authentication policy that is created in step 5.

Click OK.

Click Save.

Results

This scenario uses the following settings in the policy editor:

Precedence: First

Attributes: Optional

Rule 1: An Unconditional Rule that enforces a Permit with Authentication with a custom Two-Factor authentication policy.

Note: If the Username Password mechanism was completed by the user during the authenticated session, the user is required to provide only the MAC one-time password as indicated by the second workflow step.

Parent topic: Policy scenarios

Registering a device after user consentRegistering a device after user consentRegister a device after user consentDevice registration is the process that stores the device fingerprint of the user in the risk-based access database. The rules that you specify in a policy determine whether a device is registered silently or only after the user consents to the registration.policy scenarioregister devicedevice registrationscenario exampleThis scenario uses risk assessment. Ensure that a risk profile other than Default is set to active. See Managing risk profilesA risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time..Use the steps in this scenario task to create a policy that registers a device after the user gives consent. This scenario contains the following rules:If the calculated risk score is lower than a specified value, then Permit access.If the user consents to device registration, then register the device. This action causes the riskScore for the request to be lowered when the policy is reevaluated.If the user was not yet prompted to register the device, then display the consent registration form to the user.Deny access if none of the above rules evaluates to true.When you use a Consent Register Device authentication or a Register Device obligation in your access policy, consider the following actions:If you include a consent to register rule in your access policy, the user is prompted to give consent. If the user responds to the prompt, by either giving consent or not, the authentication flow continues. If the user does not give consent, the authentication flow does not end. In the following scenario, the "userConsent=true" rule controls whether to display the consent registration form to the user.Even if the user gives consent to register the device, the device is not registered unless you include a Device Registration obligation in your policy. In the following scenario, the "Permit with Obligation Register Device" rule controls the registration of the device. Log in to the local management interface.Click Secure Access Control.Under Policy, click Access Control.In the center panel, click Add policy.Enter a name for the policy.In the Rules section, set the Precedence property to First.As a result, the policy returns a decision for the first rule in the policy that evaluates to true.Click Add Rule.Click If all are true.The rule evaluates to true if all of the conditions in the rule are true.Select riskScore from the attribute list.Select < as the operator.Type 40 as the value.In the Decision list, select Permit.As a result, the policy permits access if the risk score is below the specified value.Click OK to complete the rule.Add a second rule that checks whether the userConsent attribute is present and that the value of userConsent is true.The userConsent attribute is present only if the user was previously prompted with the device registration consent form. If the userConsent attribute is true, the user granted consent to register the device.Click Add Rule.Select userConsent from the attribute list.Select is present as the operator.Click Add condition to add another condition to the rule.Select userConsent from the attribute list.Select = as the operator.Type true as the value.In the Decision list, select Permit with Obligation.In the Obligation list, select Register Device.Click OK.Add a third rule that checks whether the userConsent attribute is missing.If the userConsent attribute is missing, the user was not yet prompted with the device registration consent form.Click Add Rule.Select userConsent from the attribute list.Select is missing as the operator.In the Decision list, select Permit with Authentication.In the Authentication list, select Consent Register Device.Click OK.Click the arrow next to Add Rule.Click Unconditional rule.In the Decision list, select Deny.This rule is evaluated only if none of the previous rules evaluates to true. This situation can occur if:The risk score is higher than the specified value in the first rule (40 in this example). The user decided not to give consent to register the device.Click OK.Click Save.This scenario uses the following settings in the policy editor.Precedence: FirstAttributes: OptionalRule 1: If riskScore <40 Then PermitRule 2: If userConsent is present and userConsent=true Then Permit with Obligation Register DeviceRule 3: If userConsent is missing Then Permit with Authentication Consent Register DeviceRule 4: DenyPolicy scenariosSeveral commonly used policy scenarios are provided as examples to help you author policies.

Registering a device after user consent

Device registration is the process that stores the device fingerprint of the user in the risk-based access database. The rules that you specify in a policy determine whether a device is registered silently or only after the user consents to the registration.

Before you begin

This scenario uses risk assessment. Ensure that a risk profile other than Default is set to active. See Managing risk profiles.

About this task

Use the steps in this scenario task to create a policy that registers a device after the user gives consent. This scenario contains the following rules:

If the calculated risk score is lower than a specified value, then Permit access.

If the user consents to device registration, then register the device. This action causes the riskScore for the request to be lowered when the policy is reevaluated.

If the user was not yet prompted to register the device, then display the consent registration form to the user.

Deny access if none of the above rules evaluates to true.

When you use a Consent Register Device authentication or a Register Device obligation in your access policy, consider the following actions:

If you include a consent to register rule in your access policy, the user is prompted to give consent. If the user responds to the prompt, by either giving consent or not, the authentication flow continues. If the user does not give consent, the authentication flow does not end. In the following scenario, the "userConsent=true" rule controls whether to display the consent registration form to the user.

Even if the user gives consent to register the device, the device is not registered unless you include a Device Registration obligation in your policy. In the following scenario, the "Permit with Obligation Register Device" rule controls the registration of the device.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Access Control.

In the center panel, click Add policy.

Enter a name for the policy.

In the Rules section, set the Precedence property to First. As a result, the policy returns a decision for the first rule in the policy that evaluates to true.

Click Add Rule.

Click If all are true. The rule evaluates to true if all of the conditions in the rule are true.

Select riskScore from the attribute list.

Select < as the operator.

Type 40 as the value.

In the Decision list, select Permit. As a result, the policy permits access if the risk score is below the specified value.

Click OK to complete the rule.

Add a second rule that checks whether the userConsent attribute is present and that the value of userConsent is true. The userConsent attribute is present only if the user was previously prompted with the device registration consent form. If the userConsent attribute is true, the user granted consent to register the device.

Click Add Rule.

Select userConsent from the attribute list.

Select is present as the operator.

Click Add condition to add another condition to the rule.

Select userConsent from the attribute list.

Select = as the operator.

Type true as the value.

In the Decision list, select Permit with Obligation.

In the Obligation list, select Register Device.

Click OK.

Add a third rule that checks whether the userConsent attribute is missing. If the userConsent attribute is missing, the user was not yet prompted with the device registration consent form.

Click Add Rule.

Select userConsent from the attribute list.

Select is missing as the operator.

In the Decision list, select Permit with Authentication.

In the Authentication list, select Consent Register Device.

Click OK.

Click the arrow next to Add Rule.

Click Unconditional rule.

In the Decision list, select Deny. This rule is evaluated only if none of the previous rules evaluates to true. This situation can occur if:

The risk score is higher than the specified value in the first rule (40 in this example).

The user decided not to give consent to register the device.

Click OK.

Click Save.

Results

This scenario uses the following settings in the policy editor.

Precedence: First

Attributes: Optional

Rule 1: If riskScore <40 Then Permit

Rule 2: If userConsent is present and userConsent=true Then Permit with Obligation Register Device

Rule 3: If userConsent is missing Then Permit with Authentication Consent Register Device

Rule 4: Deny

Parent topic: Policy scenarios

Device fingerprintsDevice registration is the process that stores the device fingerprint of the user in the context-based access database. deviceregistrationdevicefingerprintdevicesilent registrationdeviceconsent-based registrationsilent device registrationconsent-based device registrationThe rules that you specify in the context-based access policy determine whether a device is registered silently or only after the user consents to the registration. Device fingerprints can be managed by the administrator and also by the user. The administrator can list the device fingerprints that are registered to a user, and can deregister device fingerprints. The administrator can also set the authentication level for consent-based registration, and modify template pages for use with consent-based registration. For information on user self-administration of registered devices, see Managing your registered devices You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios. Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing device fingerprintsThe device fingerprint contains information that is required for risk score calculation. You can list fingerprints or deregister fingerprints.Silent device registrationSilent device registration is the process of registering the device after the user responds successfully to a secondary challenge.Consent-based device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.Configuring device fingerprint expirationThe administrator can specify the number of days that a device fingerprint can remain valid based on the number of days since the device was last used.

Device fingerprints

Device registration is the process that stores the device fingerprint of the user in the context-based access database.

The rules that you specify in the context-based access policy determine whether a device is registered silently or only after the user consents to the registration.

Device fingerprints can be managed by the administrator and also by the user. The administrator can list the device fingerprints that are registered to a user, and can deregister device fingerprints. The administrator can also set the authentication level for consent-based registration, and modify template pages for use with consent-based registration.

For information on user self-administration of registered devices, see Managing your registered devices

Managing device fingerprints
The device fingerprint contains information that is required for risk score calculation. You can list fingerprints or deregister fingerprints.

Silent device registration
Silent device registration is the process of registering the device after the user responds successfully to a secondary challenge.

Consent-based device registration
Consent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.

Configuring device fingerprint expiration
The administrator can specify the number of days that a device fingerprint can remain valid based on the number of days since the device was last used.

Parent topic: Advanced Access Control administration

Managing device fingerprints The device fingerprint contains information that is required for risk score calculation. You can list fingerprints or deregister fingerprints.device fingerprintsmanagingTo list registered devices, you can search on a user ID or use an asterisk as a wildcard to search on partial matches. User names are not stored with the fingerprints and you cannot search on user names. You can also deregister a selected device fingerprint or deregister all of the device fingerprints that belong to a specific user. When you deregister a device fingerprint, it is removed from the database. Log in to the local management interface.Click Secure Access Control.Under Manage, click Devices.Take one of the following actions:List device fingerprints:In the Search for the user ID field, type:One or more characters and an asterisk * in the first or last position to search on partial matches. For example, enter g* to search for all user IDs that begin with g. The search is case-sensitive. Specifying an uppercase letter returns only uppercase results and specifying a lowercase letter returns only lowercase results.A specific user ID.In the Maximum results field, the default value is 100. Use this value or change it to another value. The minimum value is 1. The maximum value is 1000.Click Search. A list of user IDs is displayed.Click a user ID in the User Results list. The Registered Device Fingerprints table is displayed. Deregister a registered device fingerprint:List the device fingerprints for a specific user.Click Deregister All to remove all of the device fingerprints for the user, or select a device fingerprint and click Deregister.Confirm that you want to deregister the selected device fingerprints.If you want to configure device fingerprint expiration, see Configuring device fingerprint expirationThe administrator can specify the number of days that a device fingerprint can remain valid based on the number of days since the device was last used.. Device fingerprintsDevice registration is the process that stores the device fingerprint of the user in the context-based access database.

Managing device fingerprints

The device fingerprint contains information that is required for risk score calculation. You can list fingerprints or deregister fingerprints.

About this task

To list registered devices, you can search on a user ID or use an asterisk as a wildcard to search on partial matches.

Note: User names are not stored with the fingerprints and you cannot search on user names.

You can also deregister a selected device fingerprint or deregister all of the device fingerprints that belong to a specific user. When you deregister a device fingerprint, it is removed from the database.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Manage, click Devices.

Take one of the following actions:

List device fingerprints:

In the Search for the user ID field, type:

One or more characters and an asterisk * in the first or last position to search on partial matches. For example, enter g* to search for all user IDs that begin with g. The search is case-sensitive. Specifying an uppercase letter returns only uppercase results and specifying a lowercase letter returns only lowercase results.

A specific user ID.

In the Maximum results field, the default value is 100. Use this value or change it to another value. The minimum value is 1. The maximum value is 1000.

Click Search. A list of user IDs is displayed.

Click a user ID in the User Results list. The Registered Device Fingerprints table is displayed.

Deregister a registered device fingerprint:

List the device fingerprints for a specific user.

Click Deregister All to remove all of the device fingerprints for the user, or select a device fingerprint and click Deregister.

Confirm that you want to deregister the selected device fingerprints.

What to do next

If you want to configure device fingerprint expiration, see Configuring device fingerprint expiration.

Parent topic: Device fingerprints

Silent device registrationSilent device registration is the process of registering the device after the user responds successfully to a secondary challenge.deviceregistrationdevicefingerprintdevicesilent registrationsilent device registrationsample policysamplesilent registration Silent registration does not require any further interaction or consent from the user. The context-based access policy that you configure determines whether a device must be registered silently.You can optionally configure your system to allow incomplete device fingerprints to be registered. Use the Advanced Configuration menu to specify the necessary properties. For more information, see Managing advanced configurationAdjust configuration settings in supported configuration files..Device fingerprintsDevice registration is the process that stores the device fingerprint of the user in the context-based access database.

Silent device registration

Silent device registration is the process of registering the device after the user responds successfully to a secondary challenge.

Silent registration does not require any further interaction or consent from the user. The context-based access policy that you configure determines whether a device must be registered silently.

You can optionally configure your system to allow incomplete device fingerprints to be registered. Use the Advanced Configuration menu to specify the necessary properties. For more information, see Managing advanced configuration.

Parent topic: Device fingerprints

Consent-based device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.deviceregistrationdevicefingerprintdeviceconsent-based registrationA typical scenario that requires consent-based device registration is when a user attempts to access a protected resource from a public access environment. For example, a user might log in from an internet café or airport kiosk. After the user logs in and successfully responds to the secondary challenge, a consent form is presented. The consent form can be an HTML page where users can specify that they consent to the device registration.If the user consents to the registration of the device, the device is registered and access is permitted. The next time that the user logs in from the same device, the consent form is not presented because the device is already registered.If the user does not consent to the registration of the device, the device is not registered and the access is permitted. If the user logs in from the same device again, the secondary challenge and the consent form are presented again. The process is repeated because the risk score is high when a user logs in from a device that is not registered.When a user consents to registration of the device, two attributes are automatically set. You can use these attributes when creating policy:userConsentSets the boolean value to true. Specifies that the user has consented to device registrationauthenticationLevelNumeric value that specifies the authentication level of a user. It increases as the levels of authentication that belong to the user increase. For example: A possible authentication level is 2When a user is granted access, the authentication level is set by the policy enforcement point. This is the default behavior. Optionally, you can control the authentication level for the user, by setting advanced configuration properties.Advanced Access Control provides a template page that you can use for the HTML page to display in order to obtain user consent.Device fingerprintsDevice registration is the process that stores the device fingerprint of the user in the context-based access database. Context-based access policy sample settings to support consent-based device registrationConsent-based device registration is typically enabled and supported by combining the “Consent Register Device” authentication policy and the “Register Device” obligation within a CBA policy. Setting the authentication level for consent-based device registrationYou can specify the authentication level to grant to a user who consents to device registration.Modifying consent template pagesUse the local management interface to manage files and directories in the template files.

Consent-based device registration

Consent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.

A typical scenario that requires consent-based device registration is when a user attempts to access a protected resource from a public access environment. For example, a user might log in from an internet café or airport kiosk. After the user logs in and successfully responds to the secondary challenge, a consent form is presented. The consent form can be an HTML page where users can specify that they consent to the device registration.

If the user consents to the registration of the device, the device is registered and access is permitted. The next time that the user logs in from the same device, the consent form is not presented because the device is already registered.

If the user does not consent to the registration of the device, the device is not registered and the access is permitted. If the user logs in from the same device again, the secondary challenge and the consent form are presented again. The process is repeated because the risk score is high when a user logs in from a device that is not registered.

When a user consents to registration of the device, two attributes are automatically set. You can use these attributes when creating policy:

userConsent

Sets the boolean value to true. Specifies that the user has consented to device registration

authenticationLevel

Numeric value that specifies the authentication level of a user. It increases as the levels of authentication that belong to the user increase. For example: A possible authentication level is 2

When a user is granted access, the authentication level is set by the policy enforcement point. This is the default behavior. Optionally, you can control the authentication level for the user, by setting advanced configuration properties.

Advanced Access Control provides a template page that you can use for the HTML page to display in order to obtain user consent.

Context-based access policy sample settings to support consent-based device registration
Consent-based device registration is typically enabled and supported by combining the “Consent Register Device” authentication policy and the “Register Device” obligation within a CBA policy.

Setting the authentication level for consent-based device registration
You can specify the authentication level to grant to a user who consents to device registration.

Modifying consent template pages
Use the local management interface to manage files and directories in the template files.

Parent topic: Device fingerprints

Context-based access policy sample settings to support consent-based device registration Consent-based device registration is typically enabled and supported by combining the “Consent Register Device” authentication policy and the “Register Device” obligation within a CBA policy. The CBA policy typically also references the “riskScore” session attribute as a policy rule condition to prevent duplicate registrations. For consent-based device registration, the CBA policy might include rules similar to the following examples: If riskScore <= 40 Then Permit If userConsent = “true” Then Permit with Obligation Register Device If riskScore > 40 and userConsent != “true” Then Permit with Authentication Consent Register Device Consent-based device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.

Context-based access policy sample settings to support consent-based device registration

Consent-based device registration is typically enabled and supported by combining the “Consent Register Device” authentication policy and the “Register Device” obligation within a CBA policy.

The CBA policy typically also references the “riskScore” session attribute as a policy rule condition to prevent duplicate registrations. For consent-based device registration, the CBA policy might include rules similar to the following examples:

If riskScore <= 40
Then Permit

If userConsent = “true”
Then Permit with Obligation Register Device

If riskScore > 40 and
   userConsent != “true”
Then Permit with Authentication Consent Register Device

Parent topic: Consent-based device registration

Setting the authentication level for consent-based device registrationYou can specify the authentication level to grant to a user who consents to device registration.authentication levelconsent-based device registrationBy default, a user who consents to device registration is granted access without a specified authentication level. Optionally, you can set properties to specify the authentication level. You might want to do this action if the user needs access to resources that are restricted to users with a higher access level.Select Secure Access ControlGlobal SettingsAdvanced Configuration.Under Filter by Category, select deviceRegistration.The advanced configuration properties window lists the properties for device registration.Click Edit for the property consentDeviceRegisration.authLevelHeaderEnabled.Select the Enabled check box, and click Save.Click Edit for the property consentDeviceRegisration.authLevelHeaderValue.Specify a value for the authentication level to be granted to the user. Click Save.When you change configuration settings, the appliance alerts you that there are undeployed changes. If your changes are complete, deploy them. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Consent-based device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.

Setting the authentication level for consent-based device registration

You can specify the authentication level to grant to a user who consents to device registration.

About this task

By default, a user who consents to device registration is granted access without a specified authentication level. Optionally, you can set properties to specify the authentication level. You might want to do this action if the user needs access to resources that are restricted to users with a higher access level.

Procedure

Select Secure Access Control > Global Settings > Advanced Configuration.

Under Filter by Category, select deviceRegistration. The advanced configuration properties window lists the properties for device registration.

Click Edit for the property consentDeviceRegisration.authLevelHeaderEnabled.

Select the Enabled check box, and click Save.

Click Edit for the property consentDeviceRegisration.authLevelHeaderValue.

Specify a value for the authentication level to be granted to the user. Click Save.

When you change configuration settings, the appliance alerts you that there are undeployed changes. If your changes are complete, deploy them.

For more information, see Deploying pending changes.

Parent topic: Consent-based device registration

Modifying consent template pagesModifying consent template pagesModifying consent template pagesUse the local management interface to manage files and directories in the template files.template files rootmanagemodifyingconsent template pagesThe template page for consent-form.html displays the form where the user can indicate consent to device registration and optionally provide a name to the device that is being registeredYou can run the following tasks on the template files:Edit- Use this option if you want to view or modify the template file.Import- Use this option if you to import a file to the template files root.Export- Use this option if you want to export a file from the template files root.Import Zip- Use this option if you want to import the template files from a compressed file.Export Zip- Use this option if you want to export the template files as a compressed file.From the top menu, select Secure Access ControlGlobal SettingsTemplate Files.Work with all the management files and directories.View or update the contents of a file in the template files rootSelect the file of interest.Select Edit. You can then view the contents of the file.Edit the contents of the file.Click Save.Export a file from the template files rootSelect the file of interest.Select ManageExport. Confirm the save operation when your browser displays a confirmation window.Import a file to the template files rootSelect the file of interest.Select ManageImport. Click Browse. Browse to the file you want to import.Click Open.Click Import.Export the template file as a compressed fileSelect ManageExport Zip. Confirm the save operation when your browser displays a confirmation window.Import the template files as a compressed fileMake sure that the .zip file contains files that exist in the document root. Select ManageImport Zip. Click Browse. Browse to the file you want to import.Click Open.Click Import.When you edit or import template files, the appliance displays a message that there are undeployed changes. If you have finished making changes, deploy them.For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..Consent-based device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.Device fingerprint template page for consent-based registrationThis consent-form.html template page displays the form where the user can indicate consent to device registration. The user also has the option of providing a name to the device that is being registered.

Modifying consent template pages

Use the local management interface to manage files and directories in the template files.

About this task

The template page for consent-form.html displays the form where the user can indicate consent to device registration and optionally provide a name to the device that is being registered

You can run the following tasks on the template files:

Edit- Use this option if you want to view or modify the template file.

Import- Use this option if you to import a file to the template files root.

Export- Use this option if you want to export a file from the template files root.

Import Zip- Use this option if you want to import the template files from a compressed file.

Export Zip- Use this option if you want to export the template files as a compressed file.

Procedure

From the top menu, select Secure Access Control > Global Settings > Template Files.

Work with all the management files and directories.

View or update the contents of a file in the template files root

Select the file of interest.

Select Edit. You can then view the contents of the file.

Edit the contents of the file.

Click Save.

Export a file from the template files root

Select the file of interest.

Select Manage > Export.

Confirm the save operation when your browser displays a confirmation window.

Import a file to the template files root

Select the file of interest.

Select Manage > Import.

Click Browse.

Browse to the file you want to import.

Click Open.

Click Import.

Export the template file as a compressed file

Select Manage > Export Zip.

Confirm the save operation when your browser displays a confirmation window.

Import the template files as a compressed file

Make sure that the .zip file contains files that exist in the document root.

Select Manage > Import Zip.

Click Browse.

Browse to the file you want to import.

Click Open.

Click Import.

When you edit or import template files, the appliance displays a message that there are undeployed changes. If you have finished making changes, deploy them.

For more information, see Deploying pending changes.

Device fingerprint template page for consent-based registration
This consent-form.html template page displays the form where the user can indicate consent to device registration. The user also has the option of providing a name to the device that is being registered.

Parent topic: Consent-based device registration

Device fingerprint template page for consent-based registrationDevice fingerprint template page for consent-based registrationDevice fingerprint template page for consent-based registrationThis consent-form.html template page displays the form where the user can indicate consent to device registration. The user also has the option of providing a name to the device that is being registered. device fingerprint template page for consent-based registrationdevice fingerprint template pageconsent-based registrationThe consent-form.html template page has the following replacement macro: @ERROR_MESSAGE@ This macro is replaced with a message that indicates that there was an error in obtaining consent for device registration. For example, the device name is not valid. The device name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters: ~ ! @ # $ % ^ & * ( ) + | ` = \ ; " ' < > ? , [ ] { } / anywhere in the name.Modifying consent template pagesUse the local management interface to manage files and directories in the template files.

Device fingerprint template page for consent-based registration

This consent-form.html template page displays the form where the user can indicate consent to device registration. The user also has the option of providing a name to the device that is being registered.

The consent-form.html template page has the following replacement macro: @ERROR_MESSAGE@

This macro is replaced with a message that indicates that there was an error in obtaining consent for device registration. For example, the device name is not valid.

Note: The device name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters: ~ ! @ # $ % ^ & * ( ) + | ` = \ ; " ' < > ? , [ ] { } / anywhere in the name.

Parent topic: Modifying consent template pages

Configuring device fingerprint expirationConfiguring device fingerprint expirationConfiguring device fingerprint expirationThe administrator can specify the number of days that a device fingerprint can remain valid based on the number of days since the device was last used.device fingerprint expirationdevice fingerprint expirationconfiguringconfiguring device fingerprint expirationThe user must re-register a device when the device fingerprint expires. For example, the user must re-register a device under the following circumstances: The device has a registered fingerprint that was not used in 120 days.The administrator specified that devices must be used at least one time per 90 days.The risk engine does not consider expired device fingerprints when it calculates risk scores. To use an expired device fingerprint, re-register the device.Log in to the local management interface.Click Secure Access Control.Under Global Settings, click Advanced Configuration.Configure the following properties:deviceRegistration.checkForExpiredDevicesClick Edit . Select Enabled. This property enables the risk engine to check whether devices are inactive or expired.Click Save.deviceRegistration.inactiveExpirationTime Click Edit . Specify the number of days that device fingerprints remain valid if they are not used. The default is 90 days. Click Save.Managing device fingerprintsThe device fingerprint contains information that is required for risk score calculation. You can list fingerprints or deregister fingerprints.Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization.Device fingerprintsDevice registration is the process that stores the device fingerprint of the user in the context-based access database.

Configuring device fingerprint expiration

The administrator can specify the number of days that a device fingerprint can remain valid based on the number of days since the device was last used.

About this task

The user must re-register a device when the device fingerprint expires. For example, the user must re-register a device under the following circumstances:

The device has a registered fingerprint that was not used in 120 days.

The administrator specified that devices must be used at least one time per 90 days.

Note: The risk engine does not consider expired device fingerprints when it calculates risk scores. To use an expired device fingerprint, re-register the device.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Advanced Configuration.

Configure the following properties:

deviceRegistration.checkForExpiredDevices

Click Edit Edit.

Select Enabled. This property enables the risk engine to check whether devices are inactive or expired.

Click Save.

deviceRegistration.inactiveExpirationTime

Click Edit Edit.

Specify the number of days that device fingerprints remain valid if they are not used. The default is 90 days.

Click Save.

Parent topic: Device fingerprints

Related tasks:

Managing device fingerprints

Related reference:

Advanced configuration properties

Runtime databaseThe runtime database stores user data such as session attributes and device fingerprints.runtime databaseoverviewTo manage the disk space usage of this database, you can clear some or all of its stored data.To optimize performance or increase capacity, you can optionally deploy an external runtime database for the appliance. Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing the runtime databaseTo manage the disk space usage of this database, you can clear some or all of its stored data.Deploying an external runtime databaseTo optimize performance or increase storage capacity for the appliance, you can deploy an external runtime database. You can configure the appliance to connect to SolidDB, DB2, or Oracle database on an external server.Database usage requirementsAdvanced Access Control uses the runtime database to store user data such as the attributes with which users are associated.Runtime database tuning parametersTo improve performance, you can configure the database tuning parameters for Advanced Access Control.

Runtime database

The runtime database stores user data such as session attributes and device fingerprints.

To manage the disk space usage of this database, you can clear some or all of its stored data.

To optimize performance or increase capacity, you can optionally deploy an external runtime database for the appliance.

Managing the runtime database
To manage the disk space usage of this database, you can clear some or all of its stored data.

Deploying an external runtime database
To optimize performance or increase storage capacity for the appliance, you can deploy an external runtime database. You can configure the appliance to connect to SolidDB, DB2®, or Oracle database on an external server.

Database usage requirements
Advanced Access Control uses the runtime database to store user data such as the attributes with which users are associated.

Runtime database tuning parameters
To improve performance, you can configure the database tuning parameters for Advanced Access Control.

Parent topic: Advanced Access Control administration

Managing the runtime databaseTo manage the disk space usage of this database, you can clear some or all of its stored data.runtime databasemanagingWhen you remove data, the Security Access Manager runtime is stopped.Log in to the local management interface.Select Secure Access Control ManageDatabase MaintenanceTake one of the following actions:Remove device fingerprints:Select Remove device fingerprints.Select a time period in days, months, or years. For example, you might select 1 Year. When you click Remove, device fingerprints that have not been used in more than 1 year are removed from the database. The default is 1 year.Click Remove.Remove user session data:Select Remove user session data.Select a time period in hours or days. For example, you might select 12 Hours. When you click Remove, data older than 12 hours is removed from the database. The default is 1 day.Click Remove.Remove all data from the runtime database:Use this selection only if you want to remove all data from the runtime database.Select Remove all data from the runtime database.Click Remove.Respond to the confirmation message. Click Yes to remove all data or No to cancel the removal.If the runtime was not stopped before you selected an action, a message is displayed that asks if the runtime can be stopped. The runtime must be stopped before any removal actions can occur.After the selected action is completed, click Refresh Status to see the time that processing was completed and the number of records removed.If the status indicates that an error occurred, correct the error and try the action again.When the database record has been removed, restart the runtime by clicking Go to Runtime Tuning Parameters to restart the runtime.Runtime databaseThe runtime database stores user data such as session attributes and device fingerprints.

Managing the runtime database

To manage the disk space usage of this database, you can clear some or all of its stored data.

About this task

When you remove data, the Security Access Manager runtime is stopped.

Procedure

Log in to the local management interface.

Select Secure Access Control > Manage > Database Maintenance

Take one of the following actions:

Remove device fingerprints:

Select Remove device fingerprints.

Select a time period in days, months, or years. For example, you might select 1 Year. When you click Remove, device fingerprints that have not been used in more than 1 year are removed from the database. The default is 1 year.

Click Remove.

Remove user session data:

Select Remove user session data.

Select a time period in hours or days. For example, you might select 12 Hours. When you click Remove, data older than 12 hours is removed from the database. The default is 1 day.

Click Remove.

Remove all data from the runtime database:

Attention: Use this selection only if you want to remove all data from the runtime database.

Select Remove all data from the runtime database.

Click Remove.

Respond to the confirmation message. Click Yes to remove all data or No to cancel the removal.

Note: If the runtime was not stopped before you selected an action, a message is displayed that asks if the runtime can be stopped. The runtime must be stopped before any removal actions can occur.

After the selected action is completed, click Refresh Status to see the time that processing was completed and the number of records removed. If the status indicates that an error occurred, correct the error and try the action again.

When the database record has been removed, restart the runtime by clicking Go to Runtime Tuning Parameters to restart the runtime.

Parent topic: Runtime database

Deploying an external runtime databaseDeploying an external runtime databaseDeploying an external runtime databaseTo optimize performance or increase storage capacity for the appliance, you can deploy an external runtime database. You can configure the appliance to connect to SolidDB, DB2, or Oracle database on an external server.external runtime database DB2 deploymentSolidDB deploymentDB2external runtime databaseSolidDBexternal runtime databaseperformance, optimizingstorage capacity, increasingA Security Access Manager appliance with Advanced Access Control includes an internal SolidDB database to store user data such as session attributes and device fingerprints. This embedded database is suitable for small environments. In a production environment, use an external runtime database that can handle the required volume of data.The appliance provides scripts to deploy the runtime database on an external SolidDB, DB2, or Oracle server. You can then configure the appliance to use the external database. Use the File Downloads management page in the local management interface to access the runtime database deployment files for your environment. Runtime database deployment scriptsDatabase typeDeployment scriptsSolidDB/access_control/database/isam_access_control_soliddb.sqlDB2/access_control/database/isam_access_control_db2.sqlOracle/access_control/database/isam_access_control_oracle.sql Save the deployment script on the database server.Run the SolidDB, DB2, or Oracle script to create the external database. SolidDB script Log in to the solsql utility./opt/solidDB/soliddb-7.0/bin/solsql <network_name> <username> <password>Where<network_name>The network name of the solidDB server.<username>The user name for the database administrator.<password>The password for the database administrator.Run the following command in the SolidDB SQL Editor: @<fully_qualified_path_to_script>The following command shows the fully qualified path to the script:@/tmp/isam_access_control_soliddb.sql Oracle script Copy the downloaded isam_access_control_oracle.sql file into the Oracle home directory. For example, ORACLE_HOME=/opt/oracle/app/oracle/product/11.2.0/dbhome_1 Log in to SQL*Plus.At the SQL prompt, run START isam_access_control_oracle.sql. DB2 script Create a DB2 instance to contain the runtime database. For information about creating the DB2 instance, see the DB2 documentation.Open the isam_access_control_db2.sql file in an editor on the DB2 server.Replace the following macros with the values specific to your environment:&DBINSTANCEThe name of the DB2 instance.&DBUSERThe name of the DB2 administrator.&DBPASSWORDThe password for the DB2 administrator.Save the changes.Log in to the DB2 Command utility (Windows) or DB2 host (UNIX) as the DB2 administrator.Run the following command: db2 -tsvf <fully_qualified_path_to_script>The following example shows the fully qualified path to the script:db2 -tsvf /tmp/isam_access_control_db2.sql Validate that the tables were successfully created. Ensure that no errors were returned during the creation and log in to the database to manually check that the tables exist.From the top menu of the local management interface, select Manage System Settings > Cluster Configuration to open the Cluster Configuration management page. Select the Database tab.You must enter the following JDBC connection information:TypeThe database type, which is either DB2, Solid DB, or Oracle.AddressThe IP address of the external database server.PortThe port on which the external database server is listening.UsernameThe name of the database administrator.PasswordThe password for the database administrator.DB2 also requires the following information: SecureSelect this check box to create a secure connection with the server. Before a secure connection can be established, you must first import the certificate that the appliance uses to communication with the server. Use the SSL Certificates page to import the appropriate certificate.Database nameThe name of the database instance on the external DB2 server.Complete the following steps to identify and specify the DB2 database name when your DB2 database is remote to the cluster that you are configuring. Open the isam_access_control_db2.sql file that was used to create the database and tables.In the CREATE DATABASE entry, get the name that is specified. In the following entry, HVDB is the string that identifies the default database name: CREATE DATABASE HVDB ALIAS HVDB using codeset UTF-8 territory us COLLATE USING UCA400_NO PAGESIZE 8192 WITH "HVDB Tables"; Oracle also requires the following information: SecureSelect this check box to create a secure connection with the server. Before a secure connection can be established, you must first import the certificate that the appliance uses to communication with the server. Use the SSL Certificates page to import the appropriate certificate.Service nameSpecify the name of the Oracle instance on the external server. Contact your Oracle database administrator for this information. Driver typeChoose the Oracle JDBC driver type that is used in your Oracle installation:Thin (default value)OCIClick Save. Deploy the changes. The following error message is displayed in the Database Maintenance panel after the location of the runtime database is changed from Local to the cluster to Remote to the cluster in the Cluster Configuration panel:System Error FBTRBA091E The retrieval failed because the resource cannot be found.Restart the local management interface and resolve the error.Use an ssh session to access the local management interface. Log in as the administrator.Log in as the administrator. Type lmi and press Enter.Type restart and press Enter.Type exit, and press Enter.The appliance is configured to use the runtime database that is deployed on the external system. Tune the external database by setting the configuration parameters. See Runtime database tuning parametersTo improve performance, you can configure the database tuning parameters for Advanced Access Control..For a SolidDB external runtime database, change the DurabilityLevel to 3 from the default value of 1 to prevent loss of data. Edit the solid.ini file for the runtime database to change the DurabilityLevel.DurabilityLevel = 3After you modify and save the solid.ini file, shut down and restart the runtime database.Runtime databaseThe runtime database stores user data such as session attributes and device fingerprints.

Deploying an external runtime database

To optimize performance or increase storage capacity for the appliance, you can deploy an external runtime database. You can configure the appliance to connect to SolidDB, DB2®, or Oracle database on an external server.

About this task

A Security Access Manager appliance with Advanced Access Control includes an internal SolidDB database to store user data such as session attributes and device fingerprints. This embedded database is suitable for small environments. In a production environment, use an external runtime database that can handle the required volume of data.

The appliance provides scripts to deploy the runtime database on an external SolidDB, DB2, or Oracle server. You can then configure the appliance to use the external database.

Procedure

Use the File Downloads management page in the local management interface to access the runtime database deployment files for your environment.

Table 202. Runtime database deployment scripts.

Database type | Deployment scripts
SolidDB | /access_control/database/isam_access_control_soliddb.sql
DB2 | /access_control/database/isam_access_control_db2.sql
Oracle | /access_control/database/isam_access_control_oracle.sql

Save the deployment script on the database server.

Run the SolidDB, DB2, or Oracle script to create the external database.

SolidDB script

Log in to the solsql utility.

/opt/solidDB/soliddb-7.0/bin/solsql <network_name> <username>
<password>

Where

<network_name>

The network name of the solidDB® server.

<username>

The user name for the database administrator.

<password>

The password for the database administrator.

Run the following command in the SolidDB SQL Editor:

@<fully_qualified_path_to_script>

The following command shows the fully qualified path to the script:

@/tmp/isam_access_control_soliddb.sql

Oracle script

Copy the downloaded isam_access_control_oracle.sql file into the Oracle home directory. For example, ORACLE_HOME=/opt/oracle/app/oracle/product/11.2.0/dbhome_1 

Log in to SQL*Plus.

At the SQL prompt, run START isam_access_control_oracle.sql.

DB2 script

Create a DB2 instance to contain the runtime database. For information about creating the DB2 instance, see the DB2 documentation.

Open the isam_access_control_db2.sql file in an editor on the DB2 server.

Replace the following macros with the values specific to your environment:

&DBINSTANCE

The name of the DB2 instance.

&DBUSER

The name of the DB2 administrator.

&DBPASSWORD

The password for the DB2 administrator.

Save the changes.

Log in to the DB2 Command utility (Windows) or DB2 host (UNIX) as the DB2 administrator.

Run the following command:

db2 -tsvf <fully_qualified_path_to_script>

The following example shows the fully qualified path to the script:

db2 -tsvf /tmp/isam_access_control_db2.sql

Validate that the tables were successfully created.

Ensure that no errors were returned during the creation and log in to the database to manually check that the tables exist.

From the top menu of the local management interface, select Manage System Settings > Cluster Configuration to open the Cluster Configuration management page.

Select the Database tab.

You must enter the following JDBC connection information:

Type

The database type, which is either DB2, Solid DB, or Oracle.

Address

The IP address of the external database server.

Port

The port on which the external database server is listening.

Username

The name of the database administrator.

Password

The password for the database administrator.

DB2 also requires the following information:

Secure

Select this check box to create a secure connection with the server.

Note: Before a secure connection can be established, you must first import the certificate that the appliance uses to communication with the server. Use the SSL Certificates page to import the appropriate certificate.

Database name

The name of the database instance on the external DB2 server.

Complete the following steps to identify and specify the DB2 database name when your DB2 database is remote to the cluster that you are configuring.

Open the isam_access_control_db2.sql file that was used to create the database and tables.

In the CREATE DATABASE entry, get the name that is specified. In the following entry, HVDB is the string that identifies the default database name:

 CREATE DATABASE HVDB ALIAS HVDB using codeset UTF-8 territory us
     COLLATE USING UCA400_NO PAGESIZE 8192 WITH "HVDB Tables";

Oracle also requires the following information:

Secure

Select this check box to create a secure connection with the server.

Note: Before a secure connection can be established, you must first import the certificate that the appliance uses to communication with the server. Use the SSL Certificates page to import the appropriate certificate.

Service name

Specify the name of the Oracle instance on the external server. Contact your Oracle database administrator for this information.

Driver type

Choose the Oracle JDBC driver type that is used in your Oracle installation:

Thin (default value)

OCI

Click Save.

Deploy the changes.

Note:

The following error message is displayed in the Database Maintenance panel after the location of the runtime database is changed from Local to the cluster to Remote to the cluster in the Cluster Configuration panel:

System Error FBTRBA091E The retrieval failed because the resource
cannot be found.

Restart the local management interface and resolve the error.

Use an ssh session to access the local management interface. Log in as the administrator.

Log in as the administrator.

Type lmi and press Enter.

Type restart and press Enter.

Type exit, and press Enter.

Results

The appliance is configured to use the runtime database that is deployed on the external system.

What to do next

Tune the external database by setting the configuration parameters. See Runtime database tuning parameters.

For a SolidDB external runtime database, change the DurabilityLevel to 3 from the default value of 1 to prevent loss of data. Edit the solid.ini file for the runtime database to change the DurabilityLevel.

DurabilityLevel = 3

After you modify and save the solid.ini file, shut down and restart the runtime database.

Parent topic: Runtime database

Database usage requirementsDatabase usage requirementsDatabase usage requirementsAdvanced Access Control uses the runtime database to store user data such as the attributes with which users are associated.runtime databasestore user datadatabase usage requirementscontext-based accessruntime databasecontext-based accessdatabase usage requirementsruntime databaseA range of storage space is available in the runtime database.The average size per user and the maximum size per user are based on the default settings:There are 10 devices per user, and each device has 30 attributes.Each user has one session at a time.There are 1,000 records of behavior data per user.The administrator can configure custom database settings or use the default settings.Space requirements for average-length attributes 100 KB is the average amount of space per user in the runtime database.Your database can use more than 100 KB of space per user and still run effectively.100 KB is the suggested amount of space for your database to use per user because databases that use 100 KB per user:Allow context-based access to run effectively and efficiently.Prevent wasted space in the database.Do not use less than 100 KB of space per user. Databases that use less than 100 KB of space per user might run out of space. Databases that run out of space experience errors when context-based access runs.Space requirements for maximum-length attributes3 MB is the maximum amount of space that is possible per user in the runtime database if every attribute uses 2,000 bytes. 2,000 bytes is the maximum amount of space that each attribute can use.Runtime databaseThe runtime database stores user data such as session attributes and device fingerprints.

Database usage requirements

Advanced Access Control uses the runtime database to store user data such as the attributes with which users are associated.

A range of storage space is available in the runtime database.

The average size per user and the maximum size per user are based on the default settings:

There are 10 devices per user, and each device has 30 attributes.

Each user has one session at a time.

There are 1,000 records of behavior data per user.

Note: The administrator can configure custom database settings or use the default settings.

Space requirements for average-length attributes

100 KB is the average amount of space per user in the runtime database.

Your database can use more than 100 KB of space per user and still run effectively.

100 KB is the suggested amount of space for your database to use per user because databases that use 100 KB per user:

Allow context-based access to run effectively and efficiently.

Prevent wasted space in the database.

Do not use less than 100 KB of space per user. Databases that use less than 100 KB of space per user might run out of space. Databases that run out of space experience errors when context-based access runs.

Space requirements for maximum-length attributes

3 MB is the maximum amount of space that is possible per user in the runtime database if every attribute uses 2,000 bytes. 2,000 bytes is the maximum amount of space that each attribute can use.

Parent topic: Runtime database

Runtime database tuning parametersRuntime database tuning parametersTo improve performance, you can configure the database tuning parameters for Advanced Access Control.database tuningtuningruntime databasedeviceRegistration .maxRegisteredDevicesdeviceRegistration .maxUsageDataPerUserattributeCollection.sessionTimeoutdistributedMap.getRetryLimitdistributedMap.getRetryDelaysession.dbCleanupIntervalruntime databasetuningadvanced configurationdatabase tuning parametersFrom the top menu, select Secure Access Control > Global Settings > Advanced Configuration to access these configuration parameters. Table 1 contains the key parameters that you can use to tune the runtime database. For a full list of the available parameters, see Managing advanced configurationAdjust configuration settings in supported configuration files..Runtime database tuning parametersParameterDescriptionattributeCollection.sessionTimeoutThe appliance keeps the collected session data for context-based access in the runtime database tables. In an environment with a high volume of transactions, the tables build quickly. Consider the rate of transactions in your runtime environment to determine an appropriate timeout value.The default value of the attributeCollection.sessionTimeout parameter is 1800 seconds. deviceRegistration.maxRegisteredDevicesThe device registration process creates entries across numerous tables in the runtime database. This value limits the maximum number of devices that each user can register. A user can continue to register new devices until this maximum is reached.In a dynamic environment where every user has multiple devices, set this value to a number that represents a reasonable number of devices per user. To limit the volume of data in the database, do not use an excessive number.The default value of the deviceRegistration.maxRegisteredDevices parameter is 10.deviceRegistration.maxUsageDataPerUserThe number of records each user can have in the runtime database table that holds usage data. If a new usage transaction is received after a user reaches this limit, the oldest record for the user is removed to accommodate the new data. That is, the system retains the most recent usage records for each user.In a large deployment, set this value to a number that retains the necessary usage records without overloading the table with unnecessary data.The default value of the deviceRegistration.maxUsageDataPerUser parameter is 200. distributedMap.getRetryDelayThe amount of time, in milliseconds, to wait before the appliance does another retrieval against the distributed map. In a cluster environment with failover support, you can use this value to cater for failover time. For example, distributedMap.getRetryDelay = 500.Increasing this value might result in longer response times. The default value of the distributedMap.getRetryDelay parameter is 0. distributedMap.getRetryLimitThe number of retrievals that are done against the distributed map before the appliance returns that the retrieved data is not in the distributed map. The default value is zero, which means that the retry is disabled.You can use this value with the distributedMap.getRetryDelay value to control the behavior of the appliance when it tries to retrieve data from the distributed map. In a cluster environment with failover support, you might want to permit multiple retrievals by setting a value such as 5. If there is network latency in the environment between cluster members, you can increase this number of retries along with the retry delay.Increasing this value might result in longer response times. The default value of the distributedMap.getRetryLimit parameter is 0. session.dbCleanupIntervalSpecifies the interval, in seconds, that the database cleanup thread runs to remove expired data in the runtime database. The database cleanup thread removes the following types of expired data: Session dataDevice informationObligation transaction dataThe default value of the session.dbCleanupInterval parameter is 86400. The minimum value for this property is 3600. Runtime databaseThe runtime database stores user data such as session attributes and device fingerprints.

Runtime database tuning parameters

To improve performance, you can configure the database tuning parameters for Advanced Access Control.

From the top menu, select Secure Access Control > Global Settings > Advanced Configuration to access these configuration parameters. Table 203 contains the key parameters that you can use to tune the runtime database.

For a full list of the available parameters, see Managing advanced configuration.

Table 203. Runtime database tuning parameters

Parameter
Description

attributeCollection.sessionTimeout
The appliance keeps the collected session data for context-based access in the runtime database tables. In an environment with a high volume of transactions, the tables build quickly.

Consider the rate of transactions in your runtime environment to determine an appropriate timeout value.

The default value of the attributeCollection.sessionTimeout parameter is 1800 seconds.

deviceRegistration.maxRegisteredDevices
The device registration process creates entries across numerous tables in the runtime database. This value limits the maximum number of devices that each user can register. A user can continue to register new devices until this maximum is reached.

In a dynamic environment where every user has multiple devices, set this value to a number that represents a reasonable number of devices per user. To limit the volume of data in the database, do not use an excessive number.

The default value of the deviceRegistration.maxRegisteredDevices parameter is 10.

deviceRegistration.maxUsageDataPerUser
The number of records each user can have in the runtime database table that holds usage data. If a new usage transaction is received after a user reaches this limit, the oldest record for the user is removed to accommodate the new data. That is, the system retains the most recent usage records for each user.

In a large deployment, set this value to a number that retains the necessary usage records without overloading the table with unnecessary data.

The default value of the deviceRegistration.maxUsageDataPerUser parameter is 200.

distributedMap.getRetryDelay

The amount of time, in milliseconds, to wait before the appliance does another retrieval against the distributed map.

In a cluster environment with failover support, you can use this value to cater for failover time. For example, distributedMap.getRetryDelay = 500.

Note: Increasing this value might result in longer response times.

The default value of the distributedMap.getRetryDelay parameter is 0.

distributedMap.getRetryLimit

The number of retrievals that are done against the distributed map before the appliance returns that the retrieved data is not in the distributed map. The default value is zero, which means that the retry is disabled.

You can use this value with the distributedMap.getRetryDelay value to control the behavior of the appliance when it tries to retrieve data from the distributed map.

In a cluster environment with failover support, you might want to permit multiple retrievals by setting a value such as 5.

If there is network latency in the environment between cluster members, you can increase this number of retries along with the retry delay.

Note: Increasing this value might result in longer response times.

The default value of the distributedMap.getRetryLimit parameter is 0.

session.dbCleanupInterval
Specifies the interval, in seconds, that the database cleanup thread runs to remove expired data in the runtime database.

The database cleanup thread removes the following types of expired data:

Session data

Device information

Obligation transaction data

The default value of the session.dbCleanupInterval parameter is 86400. The minimum value for this property is 3600.

Parent topic: Runtime database

Policy information pointsPolicy information pointsPolicy information pointsPolicy information points gather information from the request or other sources, such as databases.policy information pointsdescriptionPIPsdescriptioninformation pointsdescriptionRestful Web servicepolicy information pointJavaScriptpolicy information pointLDAPpolicy information pointdatabasepolicy information pointFiberlink MaaS360policy information pointrule fileFiberlink MaaS360JavaScript PIPThe appliance provides several policy information points that are configured to use data from the request. You can use the predefined attributes from these policy information points in your policy evaluations. For more information about predefined attributes, see Predefined attributesAn appliance with Advanced Access Control uses attributes to provide information about users and devices that try to access a protected resource. The appliance also includes a set of commonly used attributes called predefined attributes..You cannot delete or modify these preconfigured PIPs through the local management interface. However, you can modify a few settings for some of them with the advanced configuration properties. See Advanced configuration propertiesModify the advanced configurations to meet the requirements of your organization. for details.Session attribute PIPReturns attributes that are related to session information, such as browser information and device characteristics.GeoLocation attribute PIPReturns geographic location attributes, such as the city and country code where the device is located.Risk Calculator PIPReturns the RiskScore attribute.IP Reputation PIPReturns the IP address reputation score.User Fingerprint Count PIPReturns the number of fingerprints that are registered for a user.The appliance also supports a PIP that uses data from outside of the appliance. You must configure this PIP before you can use it and the attributes it returns. See Managing policy information pointsTo use data from sources outside of the appliance in your policies, you must add that source as a policy information point..RESTful Web Service PIPReturns attributes from data that is obtained from a RESTful web service that is hosted outside of the appliance. You can configure multiple instances of this PIP to access different web services. JavaScript PIPReturns attributes from data that is obtained from: WebSEAL or Web Reverse Proxy data such as HTTP headers or POST data in the requestOther PIPs The JavaScript PIP processes this unstructured data and parses it so that the administrator can use it to write authorization policies and risk policies. Database PIPReturns attributes from data that is hosted outside of the appliance by using SQL SELECT query statements. You can define information points for the following types of databases:solidDBDB2OracleYou can configure more than one database policy information point instance so that different data sources can be accessed. Within the configuration, you define a query that can allow multiple attributes to be populated. You can then define a policy that relies on the custom attributes that you created.LDAP PIPObtains attributes from a registry hosted outside of the appliance by using LDAP searches. For example, you might want to determine dynamically the credit limit for a user that triggers higher authentication requirements. To make such a determination, a customer directory or database is consulted. An LDAP PIP provides the following function:Multiple instances of a configuration are allowed so that different registries can be accessed. Multiple attributes can be populated from a single search.Support for Active Directory, IBM Security Director Server, Oracle Directory Server, and any LDAP v3 compliant server.For SSL connections to the LDAP server, only server authentication is supported.Fiberlink MaaS360 PIPEnables the use of device attributes from registered devices in MaaS360 in access policies. Separate PIPs are available for browser-based web applications and MaaS360 SDK-based applications or wrapped apps. You can use either PIP to populate the MaaS360 attributes in access policy. For complete instructions on how to set up your appliance to integrate with Fiberlink MaaS360, see http://www.ibm.com/support/docview.wss?uid=swg24038325. The .zip file contains an integration guide PDF file.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing policy information pointsTo use data from sources outside of the appliance in your policies, you must add that source as a policy information point.Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.Managing server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data.RESTful web service PIPWhen you add or modify a RESTful web service policy information point (PIP), you must specify its properties.JavaScript PIPWhen you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.Database PIPWhen you add or modify a database policy information point (PIP), you configure a connection to a data source. You also determine what information to use from the data source.LDAP PIPWhen you add or modify an LDAP policy information point (PIP), you configure a connection to an LDAP server. You also determine what information to use from the LDAP directory.Fiberlink MaaS360 PIPWhen you add or modify a Fiberlink MaaS360 policy information point (PIP), you configure a connection to the Fiberlink MaaS360 web service API.

Policy information points

Policy information points gather information from the request or other sources, such as databases.

The appliance provides several policy information points that are configured to use data from the request. You can use the predefined attributes from these policy information points in your policy evaluations. For more information about predefined attributes, see Predefined attributes.

Note: You cannot delete or modify these preconfigured PIPs through the local management interface. However, you can modify a few settings for some of them with the advanced configuration properties. See Advanced configuration properties for details.

Session attribute PIP

Returns attributes that are related to session information, such as browser information and device characteristics.

GeoLocation attribute PIP

Returns geographic location attributes, such as the city and country code where the device is located.

Risk Calculator PIP

Returns the RiskScore attribute.

IP Reputation PIP

Returns the IP address reputation score.

User Fingerprint Count PIP

Returns the number of fingerprints that are registered for a user.

The appliance also supports a PIP that uses data from outside of the appliance. You must configure this PIP before you can use it and the attributes it returns. See Managing policy information points.

RESTful Web Service PIP

Returns attributes from data that is obtained from a RESTful web service that is hosted outside of the appliance. You can configure multiple instances of this PIP to access different web services.

JavaScript PIP

Returns attributes from data that is obtained from:

WebSEAL or Web Reverse Proxy data such as HTTP headers or POST data in the request

Other PIPs

The JavaScript PIP processes this unstructured data and parses it so that the administrator can use it to write authorization policies and risk policies.

Database PIP

Returns attributes from data that is hosted outside of the appliance by using SQL SELECT query statements. You can define information points for the following types of databases:

solidDB®

DB2®

Oracle

You can configure more than one database policy information point instance so that different data sources can be accessed. Within the configuration, you define a query that can allow multiple attributes to be populated. You can then define a policy that relies on the custom attributes that you created.

LDAP PIP

Obtains attributes from a registry hosted outside of the appliance by using LDAP searches. For example, you might want to determine dynamically the credit limit for a user that triggers higher authentication requirements. To make such a determination, a customer directory or database is consulted. An LDAP PIP provides the following function:

Multiple instances of a configuration are allowed so that different registries can be accessed.

Multiple attributes can be populated from a single search.

Support for Active Directory, IBM® Security Director Server, Oracle Directory Server, and any LDAP v3 compliant server.

For SSL connections to the LDAP server, only server authentication is supported.

Fiberlink MaaS360 PIP

Enables the use of device attributes from registered devices in MaaS360 in access policies. Separate PIPs are available for browser-based web applications and MaaS360 SDK-based applications or wrapped apps. You can use either PIP to populate the MaaS360 attributes in access policy. For complete instructions on how to set up your appliance to integrate with Fiberlink MaaS360, see http://www.ibm.com/support/docview.wss?uid=swg24038325. The .zip file contains an integration guide PDF file.

Managing policy information points
To use data from sources outside of the appliance in your policies, you must add that source as a policy information point.

Server connection properties
To access a data source outside of the appliance, define the properties of the server.

Managing server connections
To use data from outside your appliance in your policies, you must define the server connection to access the data.

RESTful web service PIP
When you add or modify a RESTful web service policy information point (PIP), you must specify its properties.

JavaScript PIP
When you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.

Database PIP
When you add or modify a database policy information point (PIP), you configure a connection to a data source. You also determine what information to use from the data source.

LDAP PIP
When you add or modify an LDAP policy information point (PIP), you configure a connection to an LDAP server. You also determine what information to use from the LDAP directory.

Fiberlink MaaS360 PIP
When you add or modify a Fiberlink MaaS360 policy information point (PIP), you configure a connection to the Fiberlink MaaS360 web service API.

Parent topic: Advanced Access Control administration

Managing policy information pointsManaging policy information pointsPolicy information point managementTo use data from sources outside of the appliance in your policies, you must add that source as a policy information point.policy information pointsmanagingTo use attributes from an external data source, you must add the attributes to the appliance before you add the policy information point. Use the steps for adding an attribute in Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes..To create a server connection policy information point, define the database server connection first. See Managing server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data..Log in to the local management interface.Click Secure Access Control.Under Policy, click Information Points.Take one of the following actions:Filter policy information points:Complete these steps to filter policy information points:In the Quick Filter field, type one or more characters. For example, enter g to search for all policy information points names that contain g or G. Press Enter.Add a policy information point:Complete these steps to configure a policy information point:Click the Add drop-down button.Select the type:RESTful Web ServiceJavaScriptDatabaseLDAPFiberLink MaaS360Complete the properties for the information point. See: RESTful web service PIPWhen you add or modify a RESTful web service policy information point (PIP), you must specify its properties.JavaScript PIPWhen you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.Database PIPWhen you add or modify a database policy information point (PIP), you configure a connection to a data source. You also determine what information to use from the data source.LDAP PIPWhen you add or modify an LDAP policy information point (PIP), you configure a connection to an LDAP server. You also determine what information to use from the LDAP directory.Fiberlink MaaS360 PIPWhen you add or modify a Fiberlink MaaS360 policy information point (PIP), you configure a connection to the Fiberlink MaaS360 web service API.Modify a policy information point:Complete these steps to modify a policy information point that you previously configured:Select a policy information point.Click Edit.Complete the properties for the policy information point. See:RESTful web service PIPWhen you add or modify a RESTful web service policy information point (PIP), you must specify its properties.JavaScript PIPWhen you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.Database PIPWhen you add or modify a database policy information point (PIP), you configure a connection to a data source. You also determine what information to use from the data source.LDAP PIPWhen you add or modify an LDAP policy information point (PIP), you configure a connection to an LDAP server. You also determine what information to use from the LDAP directory.Fiberlink MaaS360 PIPWhen you add or modify a Fiberlink MaaS360 policy information point (PIP), you configure a connection to the Fiberlink MaaS360 web service API.Delete a policy information point:Complete these steps to remove a policy information point that you previously configured:Do not delete a policy information point if it returns attributes that are used in a policy or risk score.Select a policy information point.Click Delete. View, import, or export a JavaScript file: These instructions apply only to JavaScript policy information points. You must select a JavaScript policy information point type to see the JavaScript drop-down button. Advanced Access Control provides the following JavaScript policy information points: Worklight Policy Information Point for AdaptersFiberlink MaaS360 Policy Information Point View a JavaScript file that you previously configured as a policy information point: Select a policy information point that is a JavaScript type.Click the JavaScript drop-down button.Select View. A read-only version of the script displays in a pop-up window.Click Close when finished. Import a JavaScript file to replace an existing file for your policy information point: Select a policy information point that is a JavaScript type.Click the JavaScript drop-down button.Select Import. A pop-up window displays to import a script.Click Browse to locate the JavaScript file.Click OK. The syntax of the file is checked. If there are errors, you must fix them before you can import the file. Export an existing JavaScript file: Select a policy information point that is a JavaScript type.Click the JavaScript drop-down button.Select Export.Click Save File. Policy information pointsPolicy information points gather information from the request or other sources, such as databases.

Managing policy information points

To use data from sources outside of the appliance in your policies, you must add that source as a policy information point.

Before you begin

To use attributes from an external data source, you must add the attributes to the appliance before you add the policy information point. Use the steps for adding an attribute in Managing attributes.

To create a server connection policy information point, define the database server connection first. See Managing server connections.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Information Points.

Take one of the following actions:

Filter policy information points:

Complete these steps to filter policy information points:

In the Quick Filter field, type one or more characters. For example, enter g to search for all policy information points names that contain g or G.

Press Enter.

Add a policy information point:

Complete these steps to configure a policy information point:

Click the Add drop-down button.

Select the type:

RESTful Web Service

JavaScript

Database

LDAP

FiberLink MaaS360

Complete the properties for the information point. See:

RESTful web service PIP

JavaScript PIP

Database PIP

LDAP PIP

Fiberlink MaaS360 PIP

Modify a policy information point:

Complete these steps to modify a policy information point that you previously configured:

Select a policy information point.

Click Edit.

Complete the properties for the policy information point. See:

RESTful web service PIP

JavaScript PIP

Database PIP

LDAP PIP

Fiberlink MaaS360 PIP

Delete a policy information point:

Complete these steps to remove a policy information point that you previously configured:

Attention: Do not delete a policy information point if it returns attributes that are used in a policy or risk score.

Select a policy information point.

Click Delete.

View, import, or export a JavaScript file:

Note: These instructions apply only to JavaScript policy information points. You must select a JavaScript policy information point type to see the JavaScript drop-down button.

Advanced Access Control provides the following JavaScript policy information points:

Worklight® Policy Information Point for Adapters

Fiberlink MaaS360 Policy Information Point

View a JavaScript file that you previously configured as a policy information point:

Select a policy information point that is a JavaScript type.

Click the JavaScript drop-down button.

Select View. A read-only version of the script displays in a pop-up window.

Click Close when finished.

Import a JavaScript file to replace an existing file for your policy information point:

Select a policy information point that is a JavaScript type.

Click the JavaScript drop-down button.

Select Import. A pop-up window displays to import a script.

Click Browse to locate the JavaScript file.

Click OK. The syntax of the file is checked. If there are errors, you must fix them before you can import the file.

Export an existing JavaScript file:

Select a policy information point that is a JavaScript type.

Click the JavaScript drop-down button.

Select Export.

Click Save File.

Parent topic: Policy information points

Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.server connectionpropertiestuning propertiesDB2server connection propertiesOracleserver connection propertiessolidDBserver connection propertiesLDAPserver connection propertiesPostgreSQLserver connection propertiesSMTPserver connection propertiesTable 1 describes the properties on the Server Connections panel for the Advanced Access Control and Federation module activation levels. Advanced Access Control: Configure LDAP or database server connections so that you can set up policy information points. You can configure any of the server connection types.Federation: Configure an LDAP server as an attribute source for attribute mapping. Federation does not configure any of the other database server connection types. Server Connection propertiesPropertyDescriptionNameSpecifies the name for the server connection. Ensure that the name is unique. Select this name when you define the policy information point.The server connection name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( ) + | ` = \ ; " ' < > ? , [ ] { } / anywhere in the name.DescriptionDescribes the server connection. This property is optional.TypeShows the server connection type. (Read only)JNDI ID (Oracle, DB2, solidDB, PostgreSQL only)Specifies the JNDI ID that the server uses. Ensure that the ID is unique. Use only alphanumeric characters: a-b, A-B, 0-9Server name (Oracle, DB2, solidDB, PostgreSQL, SMTP only)Specifies the name or IP address for the server.PortSpecifies the port number where the connection to the server can be made. User name (Oracle, DB2, solidDB, PostgreSQL, SMTP only)Specifies the user name that has the correct permissions to access the resources. Password (Oracle, DB2, solidDB, PostgreSQL, SMTP only)Specifies the password to access the server. SSLSpecifies whether SSL is used for connecting to the server. Select True or False. The default value is True. See Configuring SSL connectionsConfigure Secure Socket Layer (SSL) connections to enable encrypted communication between the LDAP policy information point (PIP) and the LDAP Server to ensure that LDAP traffic is secure and confidential..Driver type (Oracle only) Specifies the driver type. Select Thin or OCI. The default value is Thin. Service name (Oracle only) Specifies the name of the service. Database name (DB2, PostgreSQL only) Specifies the name of the database. Host name (LDAP only) Specifies the host name or IP address of the LDAP server.Bind DN (LDAP only) Specifies the LDAP distinguished name (DN) that is used when binding, or signing on, to the LDAP server. If this value is set to "anonymous", the appliance uses an anonymous bind to the LDAP directory server. Typically the bind-dn has significant privileges so that it can be used to modify LDAP registry entries, such as creating users and resetting passwords via pdadmin or the Registry Direct Java API. Using an anonymous connection to LDAP typically comes with very limited access, perhaps at most search and view of entries, at the least no access at all. If anonymous access has sufficient privileges, then it might be usable for the WebSEAL level of access on users and groups. This access includes the permission for a user to change password if "bind-auth-and-pwdchg = yes" is set ("ldap.bind-auth-and-pwdchg = true" for Registry Direct Java API).Bind Password (LDAP only) Specifies the password for the LDAP bind DN. If bind DN (bind-dn) is set to anonymous, you can use any non-empty string as the value of bind password (bind-pwd). Servers properties (LDAP only)PropertyDescriptionHost name Specifies the host name or IP address of the LDAP server.PortSpecifies the port number of the LDAP server.Bind DNSpecifies the LDAP distinguished name (DN) that is used when binding, or signing on, to the LDAP server. Bind Password Specifies the password for the LDAP bind DN. SSLSpecifies whether SSL is used for connecting to the server. Select True or False. The default value is True. See Configuring SSL connectionsConfigure Secure Socket Layer (SSL) connections to enable encrypted communication between the LDAP policy information point (PIP) and the LDAP Server to ensure that LDAP traffic is secure and confidential..SSL TruststoreSpecifies the truststore that verifies the credentials.SSL Mutual Authentication KeyLabel of client certificate to be presented when connecting to the LDAP. This property is sourced from SSL Truststore. This field is required only if mutual SSL authentication is required by the server. The properties in the following table are connection manager properties. The defaults that are listed are the current known defaults. All tuning properties are optional. Tuning propertiesPropertyDescriptionAged timeout (seconds) (Oracle, DB2, solidDB, PostgreSQL only)Specifies the amount of time, in seconds, before a physical connection is discarded by pool maintenance. Specify -1 to disable this timeout. The default is -1.Connection timeout (seconds)Specifies the amount of time, in seconds, after which a connection times out. For Oracle, DB2, solidDB, PostgreSQL, and SMTP, specify -1 to disable this timeout. The default is 30 seconds.For LDAP, specify only integers, 1 or greater. The default is 120 seconds.Max idle time (seconds) (Oracle, DB2, solidDB, PostgreSQL only)Specifies the maximum amount of time, in seconds, after which an unused or idle connection is discarded during pool maintenance. Specify -1 to disable this timeout. The default is 1800 seconds.Reap time (seconds) (Oracle, DB2, solidDB, PostgreSQL only)Specifies the amount of time, in seconds, between runs of the pool maintenance thread. Specify -1 to disable pool maintenance. The default is 180 seconds.Max pool size (Oracle, DB2, solidDB, PostgreSQL only)Specifies the maximum number of physical connections for a pool. Specify 0 for unlimited. The default is 50.Min pool size (Oracle, DB2, solidDB, PostgreSQL only)Specifies the minimum number of physical connections to maintain in a pool. The aged timeout can override the minimum. Purge policy (Oracle, DB2, solidDB, PostgreSQL only)Specifies which connections to delete when a stale connection is detected in the pool. Select from the following options:Entire pool When a stale connection is detected, all connections in the pool are marked stale, and when no longer in use, are closed. This is the default option. Failing connection only When a stale connection is detected, only the connection that was found to be bad is closed. Validate all connections When a stale connection is detected, connections are tested and the ones that are found to be bad are closed. Max connections per thread (Oracle, DB2, solidDB, PostgreSQL only)Specifies the limit of open connections on each thread.Cache connections per thread (Oracle, DB2, solidDB, PostgreSQL only)Specifies the number of cache connections for each thread. Policy information pointsPolicy information points gather information from the request or other sources, such as databases.Managing server connectionsTo access data from outside of your appliance, you must define a server connection.

Server connection properties

To access a data source outside of the appliance, define the properties of the server.

describes the properties on the Server Connections panel for the Advanced Access Control and Federation module activation levels.

Advanced Access Control: Configure LDAP or database server connections so that you can set up policy information points. You can configure any of the server connection types.

Federation: Configure an LDAP server as an attribute source for attribute mapping. Federation does not configure any of the other database server connection types.

Table 204. Table 225. Server Connection properties

Property
Description

Name
Specifies the name for the server connection. Ensure that the name is unique. Select this name when you define the policy information point.

Note: The server connection name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters ~ ! @ # $ % ^ & * ( ) + | ` = \ ; " ' < > ? , [ ] { } / anywhere in the name.

Description
Describes the server connection. This property is optional.

Type
Shows the server connection type. (Read only)

JNDI ID (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the JNDI ID that the server uses. Ensure that the ID is unique. Use only alphanumeric characters: a-b, A-B, 0-9

Server name (Oracle, DB2, solidDB, PostgreSQL, SMTP only)
Specifies the name or IP address for the server.

Port
Specifies the port number where the connection to the server can be made.

User name (Oracle, DB2, solidDB, PostgreSQL, SMTP only)
Specifies the user name that has the correct permissions to access the resources.

Password (Oracle, DB2, solidDB, PostgreSQL, SMTP only)
Specifies the password to access the server.

SSL
Specifies whether SSL is used for connecting to the server. Select True or False. The default value is True. See Configuring SSL connections.

Driver type (Oracle only)
Specifies the driver type. Select Thin or OCI. The default value is Thin.

Service name (Oracle only)
Specifies the name of the service.

Database name (DB2, PostgreSQL only)
Specifies the name of the database.

Host name (LDAP only)
Specifies the host name or IP address of the LDAP server.

Bind DN (LDAP only)
Specifies the LDAP distinguished name (DN) that is used when binding, or signing on, to the LDAP server.

Note: If this value is set to "anonymous", the appliance uses an anonymous bind to the LDAP directory server. Typically the bind-dn has significant privileges so that it can be used to modify LDAP registry entries, such as creating users and resetting passwords via pdadmin or the Registry Direct Java API. Using an anonymous connection to LDAP typically comes with very limited access, perhaps at most search and view of entries, at the least no access at all. If anonymous access has sufficient privileges, then it might be usable for the WebSEAL level of access on users and groups. This access includes the permission for a user to change password if "bind-auth-and-pwdchg = yes" is set ("ldap.bind-auth-and-pwdchg = true" for Registry Direct Java API).

Bind Password (LDAP only)
Specifies the password for the LDAP bind DN.

Note: If bind DN (bind-dn) is set to anonymous, you can use any non-empty string as the value of bind password (bind-pwd).

Table 205. Table 226. Servers properties (LDAP only)

Property
Description

Host name
Specifies the host name or IP address of the LDAP server.

Port
Specifies the port number of the LDAP server.

Bind DN
Specifies the LDAP distinguished name (DN) that is used when binding, or signing on, to the LDAP server.

Bind Password
Specifies the password for the LDAP bind DN.

SSL
Specifies whether SSL is used for connecting to the server. Select True or False. The default value is True. See Configuring SSL connections.

SSL Truststore
Specifies the truststore that verifies the credentials.

SSL Mutual Authentication Key
Label of client certificate to be presented when connecting to the LDAP. This property is sourced from SSL Truststore.

Note: This field is required only if mutual SSL authentication is required by the server.

The properties in the following table are connection manager properties. The defaults that are listed are the current known defaults. All tuning properties are optional.

Table 206. Table 227. Tuning properties

Property
Description

Aged timeout (seconds) (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the amount of time, in seconds, before a physical connection is discarded by pool maintenance. Specify -1 to disable this timeout. The default is -1.

Connection timeout (seconds)
Specifies the amount of time, in seconds, after which a connection times out.

For Oracle, DB2, solidDB, PostgreSQL, and SMTP, specify -1 to disable this timeout. The default is 30 seconds.

For LDAP, specify only integers, 1 or greater. The default is 120 seconds.

Max idle time (seconds) (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the maximum amount of time, in seconds, after which an unused or idle connection is discarded during pool maintenance. Specify -1 to disable this timeout. The default is 1800 seconds.

Reap time (seconds) (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the amount of time, in seconds, between runs of the pool maintenance thread. Specify -1 to disable pool maintenance. The default is 180 seconds.

Max pool size (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the maximum number of physical connections for a pool. Specify 0 for unlimited. The default is 50.

Min pool size (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the minimum number of physical connections to maintain in a pool. The aged timeout can override the minimum.

Purge policy (Oracle, DB2, solidDB, PostgreSQL only)
Specifies which connections to delete when a stale connection is detected in the pool. Select from the following options:

Entire pool

When a stale connection is detected, all connections in the pool are marked stale, and when no longer in use, are closed. This is the default option.

Failing connection only

When a stale connection is detected, only the connection that was found to be bad is closed.

Validate all connections

When a stale connection is detected, connections are tested and the ones that are found to be bad are closed.

Max connections per thread (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the limit of open connections on each thread.

Cache connections per thread (Oracle, DB2, solidDB, PostgreSQL only)
Specifies the number of cache connections for each thread.

Parent topic: Policy information points

Parent topic: Managing server connections

Managing server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data.server connectionsOracleDB2LDAPsolidDBPostgreSQLSMTPOracleserver connectionDB2server connectionsolidDBserver connectionLDAPserver connectionPostgreSQLserver connectionSMTPserver connectionObtain the connection information for the existing database server you want to define for your policy information point.You can create server connections to data sources, such as Oracle, DB2, solidDB, PostgreSQL, LDAP, and SMTP. You can have multiple servers for an LDAP connection.Log in to the local management interface.Click Secure Access Control.Under Global Settings, click Server Connections.Take one of the following actions: Filter server connections: In the Quick Filter field, type one or more characters. For example, enter g to search for all server connection names that contain g or G. Press Enter. Add a server connection: Click the Add drop-down button.Select Oracle, DB2, SolidDB, PostgreSQL, LDAP, or SMTP.Complete the properties for the new server connection. See Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.. Modify an existing server connection: Select a server connection.Click Edit.Complete the properties for the server connection. See Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.. Delete a server connection: Do not delete a server connection if it returns attributes that are used in a policy or risk score. Select a server connection.Click Delete. For LDAP connections, take one of the following actions in the Servers tab. Add a server connection: Click the Add drop-down button.Complete the properties for the new server connection. See Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.. Modify an existing server connection: Click Edit.Complete the properties for the server connection. See Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.. Delete a server connection: Select a server connection.Click Delete. Move a server connection: Select a server connection.Click up or down. After you define a server connection to a data source, you can create a policy information point to access this data and use it in policies. See Managing policy information pointsTo use data from sources outside of the appliance in your policies, you must add that source as a policy information point..Policy information pointsPolicy information points gather information from the request or other sources, such as databases.

Managing server connections

To use data from outside your appliance in your policies, you must define the server connection to access the data.

Before you begin

Obtain the connection information for the existing database server you want to define for your policy information point.

About this task

You can create server connections to data sources, such as Oracle, DB2®, solidDB®, PostgreSQL, LDAP, and SMTP. You can have multiple servers for an LDAP connection.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Server Connections.

Take one of the following actions:

Filter server connections:

In the Quick Filter field, type one or more characters. For example, enter g to search for all server connection names that contain g or G.

Press Enter.

Add a server connection:

Click the Add drop-down button.

Select Oracle, DB2, SolidDB, PostgreSQL, LDAP, or SMTP.

Complete the properties for the new server connection. See Server connection properties.

Modify an existing server connection:

Select a server connection.

Click Edit.

Complete the properties for the server connection. See Server connection properties.

Delete a server connection:

Note: Do not delete a server connection if it returns attributes that are used in a policy or risk score.

Select a server connection.

Click Delete.

Optional: For LDAP connections, take one of the following actions in the Servers tab.

Add a server connection:

Click the Add drop-down button.

Complete the properties for the new server connection. See Server connection properties.

Modify an existing server connection:

Click Edit.

Complete the properties for the server connection. See Server connection properties.

Delete a server connection:

Select a server connection.

Click Delete.

Move a server connection:

Select a server connection.

Click up or down.

What to do next

After you define a server connection to a data source, you can create a policy information point to access this data and use it in policies. See Managing policy information points.

Parent topic: Policy information points

RESTful web service PIPRESTful web service PIPRESTful web service PIPWhen you add or modify a RESTful web service policy information point (PIP), you must specify its properties.policy information pointsRESTful web serviceRESTful web service PIPpropertiesConnection propertiesNameA unique name for the policy information point. Use this name as the Issuer for the attributes that are returned by this policy information point.DescriptionA description of the policy information point. (Optional)TypeThe type is RESTful Web Service. This field is read only. URLThe URL for the RESTful web service that starts with http (plain-text) or https (secure HTTP). For example: https://example.ibm.com/jaxrs/getApprovedAmount/You can also dynamically create the URL by using the attribute values in a request at run time. The attribute that you use must match the name field of that attribute. Do not use confuse the attribute name in the name field with the attribute identifier in the identifier field. Use the name that matches the name in the name field.In the following example, the user name for the request is substituted in the URL at run time. The name of the attribute is username: https://example.ibm.com/jaxrs/getApprovedAmount/{username}In the following example, the user name and IP address for the request are substituted in the URL at run time. The attribute names are username and ipAddress. https://example.ibm.com/jaxrs/getApprovedAmount/{username}/{ipAddress} The server name in the URL value must match the cn= value in the SSL server certificate for the policy information point server. For the example, if the URL is https://example.ibm.com/jaxrs/getApprovedAmount/, then the SSL server certificate value must be cn=example.ibm.com.Also, the cn= value in the server certificate must be the host name for the server, not the IP address.Response FormatThe format of the response as requested by the service through the URL. Select XML, JSON, or Text.Media TypeThe Accept header in the request. The default values correspond with the response formats:application/jsonapplication/xmltext/plainHowever, you can use any MIME type that you want to use.Certificate DatabaseIf https is used on the RESTful web service URL, specify the key database for the server SSL certificate. For example, rt_profile_keysClient AuthenticationIf you require client authentication, select the type of authentication and its appropriate properties.Basic AuthenticationAn authentication method that uses a user name and a password.This property is valid only if the RESTful web service uses HTTPS. Client CertificateAn authentication method that requires the client to present an SSL certificate. Specify the database that stores the certificate and the certificate label.This property is valid only if the RESTful web service uses HTTPS. Attributes propertiesAttributeThe attributes that are retrieved from a response and that can be used in a policy or risk score. The values are mapped to the associated attributes. You can use one or more attributes, and you can add, modify, or delete attributes. You must add the attributes to the appliance before you can use the attributes in this property.See the steps for adding an attribute in Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes..Do not delete an attribute that is used in a policy or risk score.SelectorXMLXPath 1.0 expressions are supported for XML selectors. Any valid XPath expression is supported.Plain TextThe plain text selector is a delimiter. The response from the web service can be a single value or list of values for an attribute. The selector specifies the character that separates the values. For example: The selector is a comma (,)The response from the web service is "LabA,LabB,LabC"The returned attribute has three values: LabA, LabB, and LabC If you specify None for the delimiter, the RESTful web service policy information point returns the entire response as the attribute's value. If you do not specify a delimiter, the appliance defaults to None. JSONThe JSON selector string. All attribute selectors must return either a primitive type or an array of primitive types. If the selector references complex types, a policy evaluation error occurs, and access to the system is denied. JSON Selector formatDescription$.xReturns the value for the property that is named x in the JSON object. Example: {"name": "Bill", "loan": {"amount":100, "rate":0.15, "duration":60}, "accounts":[10000, 2000, 500]}$.name returns 'Bill'.$.x....zReturns the value for the property within a nested JSON object. Example: {"name": "Bill", "loan": {"amount":100, "rate":0.15, "duration":60}, "accounts":[10000, 2000, 500]}$.loan.amount returns 100.$.x[*]Returns the array found at the specified property. Example: {"name": "Bill", "loan": {"amount":100, "rate":0.15, "duration":60}, "accounts":[10000, 2000, 500]}$.accounts[*] returns [10000, 2000, 500]. The attribute is multivalued with each object in the array as a value. $.[*]Returns an array that is contained in the JSON response. The attribute is multivalued with each object in the array as a value. Example:If the data is ["joe", "bob", "ted"] , $.[*] returns ["joe", "bob", "ted"]$.[x]Returns a value from a JSON array index, where $.[x] represents the index on the array of the value you want to return. Example:If the data is ["joe", "bob", "ted"] , $.[1] returns ["bob"]$.[*].xReturns values from a property within an array of JSON objects.Example: If the data is[ {"name":"joe", "phone":"555-1212"}, {"name":"bill", "phone":"555-1213"}, {"name":"ted", "phone":"555-1214"} ]$.[*].name returns ["joe", "bill", "ted"]Policy information pointsPolicy information points gather information from the request or other sources, such as databases.

RESTful web service PIP

When you add or modify a RESTful web service policy information point (PIP), you must specify its properties.

Connection properties

Name

A unique name for the policy information point. Use this name as the Issuer for the attributes that are returned by this policy information point.

Description

A description of the policy information point. (Optional)

Type

The type is RESTful Web Service. This field is read only.

URL

The URL for the RESTful web service that starts with http (plain-text) or https (secure HTTP). For example:

 https://example.ibm.com/jaxrs/getApprovedAmount/

You can also dynamically create the URL by using the attribute values in a request at run time. The attribute that you use must match the name field of that attribute.

Attention: Do not use confuse the attribute name in the name field with the attribute identifier in the identifier field. Use the name that matches the name in the name field.

In the following example, the user name for the request is substituted in the URL at run time. The name of the attribute is username:

 https://example.ibm.com/jaxrs/getApprovedAmount/{username}

In the following example, the user name and IP address for the request are substituted in the URL at run time. The attribute names are username and ipAddress.

 https://example.ibm.com/jaxrs/getApprovedAmount/{username}/{ipAddress}

Attention: The server name in the URL value must match the cn= value in the SSL server certificate for the policy information point server. For the example, if the URL is https://example.ibm.com/jaxrs/getApprovedAmount/, then the SSL server certificate value must be cn=example.ibm.com.

Also, the cn= value in the server certificate must be the host name for the server, not the IP address.

Response Format

The format of the response as requested by the service through the URL. Select XML, JSON, or Text.

Media Type

The Accept header in the request. The default values correspond with the response formats:

application/json

application/xml

text/plain

However, you can use any MIME type that you want to use.

Certificate Database

If https is used on the RESTful web service URL, specify the key database for the server SSL certificate. For example, rt_profile_keys

Client Authentication

If you require client authentication, select the type of authentication and its appropriate properties.

Basic Authentication

An authentication method that uses a user name and a password.

Attention: This property is valid only if the RESTful web service uses HTTPS.

Client Certificate

An authentication method that requires the client to present an SSL certificate. Specify the database that stores the certificate and the certificate label.

Attention: This property is valid only if the RESTful web service uses HTTPS.

Attributes properties

Attribute

The attributes that are retrieved from a response and that can be used in a policy or risk score. The values are mapped to the associated attributes. You can use one or more attributes, and you can add, modify, or delete attributes.

Attention:

You must add the attributes to the appliance before you can use the attributes in this property.See the steps for adding an attribute in Managing attributes.

Do not delete an attribute that is used in a policy or risk score.

Selector

XML

XPath 1.0 expressions are supported for XML selectors. Any valid XPath expression is supported.

Plain Text

The plain text selector is a delimiter. The response from the web service can be a single value or list of values for an attribute. The selector specifies the character that separates the values. For example:

The selector is a comma (,)

The response from the web service is "LabA,LabB,LabC"

The returned attribute has three values: LabA, LabB, and LabC

Note: If you specify None for the delimiter, the RESTful web service policy information point returns the entire response as the attribute's value. If you do not specify a delimiter, the appliance defaults to None.

JSON

The JSON selector string. All attribute selectors must return either a primitive type or an array of primitive types. If the selector references complex types, a policy evaluation error occurs, and access to the system is denied.

JSON Selector format
Description

$.x
Returns the value for the property that is named x in the JSON object. Example:

{"name": "Bill", "loan":
  {"amount":100, "rate":0.15, "duration":60},
   "accounts":[10000, 2000, 500]}

$.name returns 'Bill'.

$.x....z
Returns the value for the property within a nested JSON object. Example:

{"name": "Bill", "loan":
  {"amount":100, "rate":0.15, "duration":60},
   "accounts":[10000, 2000, 500]}

$.loan.amount returns 100.

$.x[*]
Returns the array found at the specified property. Example:

{"name": "Bill", "loan":
  {"amount":100, "rate":0.15, "duration":60},
   "accounts":[10000, 2000, 500]}

$.accounts[*] returns [10000, 2000, 500]. The attribute is multivalued with each object in the array as a value.

$.[*]
Returns an array that is contained in the JSON response. The attribute is multivalued with each object in the array as a value.

Example:

If the data is ["joe", "bob", "ted"] , $.[*] returns ["joe", "bob", "ted"]

$.[x]
Returns a value from a JSON array index, where $.[x] represents the index on the array of the value you want to return.

Example:

If the data is ["joe", "bob", "ted"] , $.[1] returns ["bob"]

$.[*].x
Returns values from a property within an array of JSON objects.

Example:

If the data is

[
      {"name":"joe", "phone":"555-1212"},
      {"name":"bill", "phone":"555-1213"},
      {"name":"ted", "phone":"555-1214"}
]

$.[*].name returns ["joe", "bill", "ted"]

Parent topic: Policy information points

JavaScript PIP JavaScript PIPJavaScript PIPWhen you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.policy information pointsJavaScript propertiesJavaScript PIPproperties General NameA unique name for the policy information point. Use this name as the Issuer for the attributes that are returned by this policy information point.DescriptionA description of the policy information point. (Optional)TypeThe type is JavaScript. This field is read only. ScriptA file that contains the JavaScript rule. Type the file name or click Browse to select the file from your workstation. JavaScript policy information point instance properties The Name and Value properties are optional. They are passed into the JavaScript code so that the administrator can use them to configure how the code runs. Policy information pointsPolicy information points gather information from the request or other sources, such as databases.Fiberlink MaaS360 JavaScript PIPYou can configure a JavaScript PIP to call the Fiberlink MaaS360 rule file. This type of PIP is for MaaS360 SDK-based applications or wrapped applications, and it retrieves attributes from the MaaS360 device inventory for use in access policies. Worklight JavaScript PIPAn appliance with Advanced Access Control can provide a JavaScript policy information point (PIP) for the Worklight product.

JavaScript PIP

When you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.

General

Name

A unique name for the policy information point. Use this name as the Issuer for the attributes that are returned by this policy information point.

Description

A description of the policy information point. (Optional)

Type

The type is JavaScript. This field is read only.

Script

A file that contains the JavaScript rule. Type the file name or click Browse to select the file from your workstation.

JavaScript policy information point instance properties

The Name and Value properties are optional. They are passed into the JavaScript code so that the administrator can use them to configure how the code runs.

Fiberlink MaaS360 JavaScript PIP
You can configure a JavaScript PIP to call the Fiberlink MaaS360 rule file. This type of PIP is for MaaS360 SDK-based applications or wrapped applications, and it retrieves attributes from the MaaS360 device inventory for use in access policies.

Worklight JavaScript PIP
An appliance with Advanced Access Control can provide a JavaScript policy information point (PIP) for the Worklight® product.

Parent topic: Policy information points

Fiberlink MaaS360 JavaScript PIPFiberlink MaaS360 JavaScript PIPFiberlink MaaS360 JavaScript PIPYou can configure a JavaScript PIP to call the Fiberlink MaaS360 rule file. This type of PIP is for MaaS360 SDK-based applications or wrapped applications, and it retrieves attributes from the MaaS360 device inventory for use in access policies. JavaScript PIPFiberlink MaaS360policy information points JavaScriptFiberlink MaaS360Fiberlink MaaS360JavaScript PIPFollow these general steps to set up the PIP:Update the Fiberlink MaaS360 SDK application code to retrieve the device ID. Then, populate an HTTP request header with the value. For example://Inside application HTTP connection methods ... String maas360DeviceCsn = MaaS360SDK.getContext().getDeviceCsn(); DefaultHttpClient client = new DefaultHttpClient(); HttpHost host = new HttpHost("isam.ibm.com", 443, "https"); HttpGet httpget = new HttpGet("<path>"); httpget.setHeader("x-fl-device-id", maas360DeviceCsn); ... MaaS360SDK.getEnterpriseGatewayService().proxy(client); ... //Handle response ...Configure the web reverse proxy to populate the following attribute used by the PIP to retrieve the device attributes from MaaS360:[azn-decision-info] urn:ibm:security:fiberlink:maas360:device:ids = header:x-fl-device-idConfigure the appliance with Advanced Access Conrol to call the Fiberlink MaaS360 JavaScript PIP rule file, maas360_pip_rule.js. This rule file is provided with the integration download package.For complete instructions on how to set up your appliance to integrate with Fiberlink MaaS360, see http://www.ibm.com/support/docview.wss?uid=swg24038325. The .zip file contains an integration guide PDF file and the rule file for this PIP.JavaScript PIPWhen you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.

Fiberlink MaaS360 JavaScript PIP

You can configure a JavaScript PIP to call the Fiberlink MaaS360 rule file. This type of PIP is for MaaS360 SDK-based applications or wrapped applications, and it retrieves attributes from the MaaS360 device inventory for use in access policies.

Follow these general steps to set up the PIP:

Update the Fiberlink MaaS360 SDK application code to retrieve the device ID. Then, populate an HTTP request header with the value. For example:

//Inside application HTTP connection methods
...
String maas360DeviceCsn = MaaS360SDK.getContext().getDeviceCsn();
DefaultHttpClient client = new DefaultHttpClient();
HttpHost host = new HttpHost("isam.ibm.com", 443, "https");
HttpGet httpget = new HttpGet("<path>");
httpget.setHeader("x-fl-device-id", maas360DeviceCsn);
...
MaaS360SDK.getEnterpriseGatewayService().proxy(client);
...
//Handle response
...

Configure the web reverse proxy to populate the following attribute used by the PIP to retrieve the device attributes from MaaS360:

[azn-decision-info]
urn:ibm:security:fiberlink:maas360:device:ids = header:x-fl-device-id

Configure the appliance with Advanced Access Conrol to call the Fiberlink MaaS360 JavaScript PIP rule file, maas360_pip_rule.js. This rule file is provided with the integration download package.

For complete instructions on how to set up your appliance to integrate with Fiberlink MaaS360, see http://www.ibm.com/support/docview.wss?uid=swg24038325. The .zip file contains an integration guide PDF file and the rule file for this PIP.

Parent topic: JavaScript PIP

Worklight JavaScript PIPWorklight JavaScript PIPWorklight JavaScript PIPAn appliance with Advanced Access Control can provide a JavaScript policy information point (PIP) for the Worklight product.JavaScript policy information point Worklightpolicy information points JavaScriptWorklightThe Worklight JavaScript PIP is a prepopulated PIP that completes the following tasks: Decodes and parses the POST data that exists in a Worklight adapter request. Returns custom attributes that are created from the data that is contained within the POST data from the parameters element.To support context-based authorization for Worklight adapters, you must create a custom PIP to URL-decode and tokenize form POST data. Worklight uses the following HTTP POST format: x-www-form-urlencoded For example: adapter=BankingApprovals&procedure=doTransfer&parameters=%5B%22200%22%2C%22sav%22%2C%22chq%22%5D represents the following JSON data: ["200","sav","chq"]["200","sav","chq"] starts when $200.00 is transferred from a savings account to a checking account. In this example: The JavaScript PIP maps the POST data into the following corresponding Worklight attribute names: worklight.adapter.adapter, worklight.adapter.procedure, and worklight.adapter.parameters.The Worklight client calls the Worklight Adapter, which starts a procedure where the parameters are passed. In the example, the name of the Worklight adapter is BankingApprovals. The Worklight PIP then determines the attribute context of the worklight.adapter.parameters. This context is based on the worklight.adapter.adapter attribute and the worklight.adapter.procedure attribute. The JavaScript PIP maps the following values into their corresponding Worklight attributes:parametersworklight.adapter.parameters is the Worklight attribute for parameters. 200worklight.adapter.transfer.amount is the Worklight attribute for 200. savworklight.adapter.transfer.account.from is the Worklight attribute for sav. chqworklight.adapter.transfer.account.to is the Worklight attribute for chq.You can complete the following tasks for these PIPs by using the local management interface: Add, modify, and delete PIPs. View, import, and export JavaScript PIPs. The sample Worklight JavaScript PIP and associated attributes on the appliance provide built-in support for the IBM Security Access Manager for Worklight integration sample application. See IBM Security Access Manager for IBM Worklight for more informationSee Managing policy information pointsTo use data from sources outside of the appliance in your policies, you must add that source as a policy information point. and JavaScript propertiesWhen you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment..JavaScript PIPWhen you add or modify a JavaScript policy information point (PIP), you must define the properties to customize the PIP according to the needs of your environment.

Worklight JavaScript PIP

An appliance with Advanced Access Control can provide a JavaScript policy information point (PIP) for the Worklight® product.

The Worklight JavaScript PIP is a prepopulated PIP that completes the following tasks:

Decodes and parses the POST data that exists in a Worklight adapter request.

Returns custom attributes that are created from the data that is contained within the POST data from the parameters element.

To support context-based authorization for Worklight adapters, you must create a custom PIP to URL-decode and tokenize form POST data.

Worklight uses the following HTTP POST format: x-www-form-urlencoded

For example: adapter=BankingApprovals&procedure=doTransfer&parameters=%5B%22200%22%2C%22sav%22%2C%22chq%22%5D represents the following JSON data: ["200","sav","chq"]

["200","sav","chq"] starts when $200.00 is transferred from a savings account to a checking account. In this example:

The JavaScript PIP maps the POST data into the following corresponding Worklight attribute names: worklight.adapter.adapter, worklight.adapter.procedure, and worklight.adapter.parameters.

The Worklight client calls the Worklight Adapter, which starts a procedure where the parameters are passed. In the example, the name of the Worklight adapter is BankingApprovals.

The Worklight PIP then determines the attribute context of the worklight.adapter.parameters. This context is based on the worklight.adapter.adapter attribute and the worklight.adapter.procedure attribute.

The JavaScript PIP maps the following values into their corresponding Worklight attributes:

parameters

worklight.adapter.parameters is the Worklight attribute for parameters.

200

worklight.adapter.transfer.amount is the Worklight attribute for 200.

sav

worklight.adapter.transfer.account.from is the Worklight attribute for sav.

chq

worklight.adapter.transfer.account.to is the Worklight attribute for chq.

You can complete the following tasks for these PIPs by using the local management interface:

Add, modify, and delete PIPs.

View, import, and export JavaScript PIPs.

The sample Worklight JavaScript PIP and associated attributes on the appliance provide built-in support for the IBM® Security Access Manager for Worklight integration sample application. See IBM Security Access Manager for IBM Worklight for more information

See Managing policy information points and JavaScript properties.

Parent topic: JavaScript PIP

Database PIPDatabase PIPDatabase PIPWhen you add or modify a database policy information point (PIP), you configure a connection to a data source. You also determine what information to use from the data source.policy information pointsdatabase propertiesdatabase PIPproperties Connection properties NameIdentifies the policy information point instance. This name must be unique to the instance. Do not use a predefined Advanced Access Control policy information point issuer name.The name that you create is the issuer for any attributes that the policy information point instance returns.DescriptionDescribes the policy information point. (Optional)TypeSpecifies the policy information point type, which is Database. (Read only)Server ConnectionSpecifies the database from which to retrieve the attributes. Select one of the defined databases from the list. If the database you require is not available to select in the list, you must define it. See Managing server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data.. Attribute properties SQL QuerySpecifies the SQL SELECT statement that queries the database for information. You can use any valid SQL SELECT statement. You cannot add an attribute unless you enter a query statement in this field.The format of the SELECT statement:SELECT COLNAME1, COLNAME2, ..., COLNAMEn FROM TABLE WHERE ... You can also dynamically create the query by using attribute values in a query at run time. The attribute that you use must match the name field of that attribute. In the following example, the user name for the request is substituted in the query at run time. The name of the attribute is username:SELECT COLNAME1, COLNAME2, ..., COLNAMEn FROM TABLE WHERE ACCOUNT_HOLDER = {username}You can specify only a single select statement when you configure the database policy information point. If you specify multiple SQL statements, an error message is returned. Do not end the statement with a semicolon.AttributeSpecifies the attributes that are retrieved from a response and that can be used in a policy or risk score. The database column is mapped to the associated attribute. You can use one or more attributes. You also can add, modify, or delete attributes. Database ColumnSpecifies the database column that maps to the attribute. Select it from the list of column names or type the name. The column names from the SQL SELECT query are used as the attribute selectors. For example, if you specify the following query: SELECT ACCOUNT_BALANCE, ACCOUNT_NUMBER FROM ACCOUNTS WHERE ACCOUNT_HOLDER_NAME = 'Joe Smith'ACCOUNT_BALANCE and ACCOUNT_NUMBER are the column names to select from.If your SELECT statement specifies a wildcard character, type the column name in this field. Policy information pointsPolicy information points gather information from the request or other sources, such as databases.

Database PIP

When you add or modify a database policy information point (PIP), you configure a connection to a data source. You also determine what information to use from the data source.

Connection properties

Name

Identifies the policy information point instance. This name must be unique to the instance. Do not use a predefined Advanced Access Control policy information point issuer name.

The name that you create is the issuer for any attributes that the policy information point instance returns.

Description

Describes the policy information point. (Optional)

Type

Specifies the policy information point type, which is Database. (Read only)

Server Connection

Specifies the database from which to retrieve the attributes. Select one of the defined databases from the list. If the database you require is not available to select in the list, you must define it. See Managing server connections.

Attribute properties

SQL Query

Specifies the SQL SELECT statement that queries the database for information. You can use any valid SQL SELECT statement. You cannot add an attribute unless you enter a query statement in this field.

The format of the SELECT statement:

SELECT COLNAME1, COLNAME2, ..., COLNAMEn FROM TABLE WHERE ...

You can also dynamically create the query by using attribute values in a query at run time. The attribute that you use must match the name field of that attribute. In the following example, the user name for the request is substituted in the query at run time. The name of the attribute is username:

SELECT COLNAME1, COLNAME2, ..., COLNAMEn FROM TABLE WHERE ACCOUNT_HOLDER = {username}

Note: You can specify only a single select statement when you configure the database policy information point. If you specify multiple SQL statements, an error message is returned. Do not end the statement with a semicolon.

Attribute

Specifies the attributes that are retrieved from a response and that can be used in a policy or risk score. The database column is mapped to the associated attribute. You can use one or more attributes. You also can add, modify, or delete attributes.

Database Column

Specifies the database column that maps to the attribute. Select it from the list of column names or type the name. The column names from the SQL SELECT query are used as the attribute selectors. For example, if you specify the following query:

SELECT ACCOUNT_BALANCE, ACCOUNT_NUMBER FROM ACCOUNTS WHERE ACCOUNT_HOLDER_NAME = 'Joe Smith'

ACCOUNT_BALANCE and ACCOUNT_NUMBER are the column names to select from.

If your SELECT statement specifies a wildcard character, type the column name in this field.

Parent topic: Policy information points

LDAP PIPLDAP PIPLDAP PIPWhen you add or modify an LDAP policy information point (PIP), you configure a connection to an LDAP server. You also determine what information to use from the LDAP directory.policy information pointsLDAPLDAP PIPproperties Connection properties NameIdentifies the policy information point instance. This name must be unique to the instance. Do not use a predefined Advanced Access Control policy information point issuer name.The name that you create is the issuer for any attributes that the policy information point instance returns.DescriptionDescribes the policy information point. (Optional)TypeSpecifies the policy information point type, which is LDAP. (Read only)Server ConnectionSpecifies the LDAP server from which to retrieve the attributes. Select one of the defined LDAP servers from the list. If the server you require is not available to select in the list, you must define it. See Managing server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data.. Attribute properties Base DNSpecifies the base DN of the directory server that determines where to search for attribute values. For example, you can specify o=Example_Organization,c=us.Search filterSpecifies the search filter for the attribute values you require. Any LDAP search filter is supported. For example, specify (|(objectclass=ePerson)(objectclass=Person)). You can also dynamically create the search by using attribute values in a search at runtime. The attribute that you use must match the name field of that attribute. For example, (&(cn={username})(|(objectclass=ePerson)(objectclass=Person))).Search timeout (seconds) Specifies the amount of time in seconds that is allowed for search operation before the LDAP server is considered to be down. The default is 120 seconds.AttributeSpecifies the attributes that are retrieved from a response and that can be used in a policy or risk score. Each attribute is mapped to an associated LDAP registry attribute. You can use one or more attributes, and you can add, modify, or delete attributes. The attributes that you add here must already be defined in the appliance local management interface. See Managing attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes. for information on adding an attribute. Do not delete an attribute that is used in a policy or risk score.SelectorSpecifies the name of an LDAP registry attribute. Policy information pointsPolicy information points gather information from the request or other sources, such as databases.

LDAP PIP

When you add or modify an LDAP policy information point (PIP), you configure a connection to an LDAP server. You also determine what information to use from the LDAP directory.

Connection properties

Name

Identifies the policy information point instance. This name must be unique to the instance. Do not use a predefined Advanced Access Control policy information point issuer name.

The name that you create is the issuer for any attributes that the policy information point instance returns.

Description

Describes the policy information point. (Optional)

Type

Specifies the policy information point type, which is LDAP. (Read only)

Server Connection

Specifies the LDAP server from which to retrieve the attributes. Select one of the defined LDAP servers from the list. If the server you require is not available to select in the list, you must define it. See Managing server connections.

Attribute properties

Base DN

Specifies the base DN of the directory server that determines where to search for attribute values. For example, you can specify o=Example_Organization,c=us.

Search filter

Specifies the search filter for the attribute values you require. Any LDAP search filter is supported. For example, specify (|(objectclass=ePerson)(objectclass=Person)). You can also dynamically create the search by using attribute values in a search at runtime. The attribute that you use must match the name field of that attribute. For example, (&(cn={username})(|(objectclass=ePerson)(objectclass=Person))).

Search timeout (seconds)

Specifies the amount of time in seconds that is allowed for search operation before the LDAP server is considered to be down. The default is 120 seconds.

Attribute

Specifies the attributes that are retrieved from a response and that can be used in a policy or risk score. Each attribute is mapped to an associated LDAP registry attribute. You can use one or more attributes, and you can add, modify, or delete attributes.

The attributes that you add here must already be defined in the appliance local management interface. See Managing attributes for information on adding an attribute.

Do not delete an attribute that is used in a policy or risk score.

Selector

Specifies the name of an LDAP registry attribute.

Parent topic: Policy information points

Fiberlink MaaS360 PIPFiberlink MaaS360 PIPFiberlink MaaS360 PIPWhen you add or modify a Fiberlink MaaS360 policy information point (PIP), you configure a connection to the Fiberlink MaaS360 web service API.policy information pointsFiberlink MaaS360Fiberlink MaaS360 PIPproperties See the following link for complete integration information for this type of PIP: http://www.ibm.com/support/docview.wss?uid=swg24038325 Connection properties NameIdentifies the policy information point instance. You must use urn:ibm:security:fiberlink:maas360 to ensure that the MaaS360 attributes used in the access policy cause the PIP to be called.DescriptionDescribes the policy information point. (Optional)TypeSpecifies the policy information point type, which is FiberLink MaaS360. (Read only)URLSpecifies the URL of the Maas360 host. For example: https://services.fiberlink.comUsernameSpecifies the MaaS360 user name.PasswordSpecifies the MaaS360 password.App Access KeySpecifies the MaaS360 app access key. For example: abcdef1234App VersionSpecifies the MaaS360 app version. For example: 1App IDSpecifies the MaaS360 app ID. For example: com.123456789.maas360Billing IDSpecifies the MaaS360 billing ID.Platform IDSpecifies the MaaS360 platform ID. Certificate DatabaseIf https is used on the URL, specify the key database for the server SSL certificate. For example, specify maas360_keys. Policy information pointsPolicy information points gather information from the request or other sources, such as databases.

Fiberlink MaaS360 PIP

When you add or modify a Fiberlink MaaS360 policy information point (PIP), you configure a connection to the Fiberlink MaaS360 web service API.

See the following link for complete integration information for this type of PIP: http://www.ibm.com/support/docview.wss?uid=swg24038325

Connection properties

Name

Identifies the policy information point instance. You must use urn:ibm:security:fiberlink:maas360 to ensure that the MaaS360 attributes used in the access policy cause the PIP to be called.

Description

Describes the policy information point. (Optional)

Type

Specifies the policy information point type, which is FiberLink MaaS360. (Read only)

URL

Specifies the URL of the Maas360 host. For example: https://services.fiberlink.com

Username

Specifies the MaaS360 user name.

Password

Specifies the MaaS360 password.

App Access Key

Specifies the MaaS360 app access key. For example: abcdef1234

App Version

Specifies the MaaS360 app version. For example: 1

App ID

Specifies the MaaS360 app ID. For example: com.123456789.maas360

Billing ID

Specifies the MaaS360 billing ID.

Platform ID

Specifies the MaaS360 platform ID.

Certificate Database

If https is used on the URL, specify the key database for the server SSL certificate. For example, specify maas360_keys.

Parent topic: Policy information points

ExtensionsExtensionsExtensionsUse extensions so that you can implement your own obligation handler and authentication mechanism.Extensionsserver-side obligation handlerauthentication mechanismObligation handlerThe obligation handler extension point allows an application developer to handle obligations at the policy decision point before it returns the result to the policy enforcement point application.For more information about managing obligations in the local management interface, see Managing obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.. Authentication mechanismThe authentication mechanism determines the conditions that successfully authenticate a user. For more information about managing authentication mechanisms in the local management interface, see Managing authentication mechanismsAuthentication mechanisms determine conditions that successfully authenticate a user. You can view, add, modify, and delete authentication mechanisms..For more information about the Software Development Kit, see Software Development KitUse the Software Development Kit so that you can create customized components such as your own obligation handler or authentication mechanism..Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing extensionsDeploy your extensions to the appliance so that you can create an instance of it and use the instance in your policies. Extensions are contained in bundles. You can import, replace, export, and delete bundles that contain extensions.

Extensions

Use extensions so that you can implement your own obligation handler and authentication mechanism.

Obligation handler

The obligation handler extension point allows an application developer to handle obligations at the policy decision point before it returns the result to the policy enforcement point application.

For more information about managing obligations in the local management interface, see Managing obligations.

Authentication mechanism

The authentication mechanism determines the conditions that successfully authenticate a user.

For more information about managing authentication mechanisms in the local management interface, see Managing authentication mechanisms.

For more information about the Software Development Kit, see Software Development Kit.

Managing extensions
Deploy your extensions to the appliance so that you can create an instance of it and use the instance in your policies. Extensions are contained in bundles. You can import, replace, export, and delete bundles that contain extensions.

Parent topic: Advanced Access Control administration

Managing extensionsManaging extensionsManaging extensionsDeploy your extensions to the appliance so that you can create an instance of it and use the instance in your policies. Extensions are contained in bundles. You can import, replace, export, and delete bundles that contain extensions.extensionsmanagingConsider the following restrictions:You cannot delete a bundle that has extensions that are used by a policy. If you are replacing a bundle that contains extensions that are used by a policy, make sure that the new bundle:Has the same file name as the old bundleContains the same exact extensions that are used by a policyContains the same exact properties as the original extensionsIf you are replacing a bundle that contains extensions that are not used by a policy, make sure that the new bundle has the same file name as the old bundle.Log in to the local management interface.Click Secure Access Control.Under Policy, click Extensions.Take one of the following actions: Search for and view a bundleTake any of the following actions to filter your view: Type one or more characters in the Filter field. The list displays the bundles that start with those characters. Sort the list by column with the up or down arrow on each column. For example, you can view the list of extension IDs in ascending order by clicking the up arrow.Import a bundle Click Import.Click Browse to locate the bundle.Click Import. The syntax of the file is checked. If there are errors, you must fix them before you can import the file. Replace a bundle Click Import. Click Browse to locate the bundle.Click OK when you are prompted that the bundle exists. Export a bundle Select the bundle that you want to export.Click Export.Save the file. Delete a bundleSelect the bundle that you want to delete.Click Delete. A message prompts you to confirm the deletion.Click Delete. Save and deploy your changes. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step..If you imported a custom authentication mechanism, see Managing authentication mechanismsAuthentication mechanisms determine conditions that successfully authenticate a user. You can view, add, modify, and delete authentication mechanisms..If you imported a custom obligation, see Managing obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations..ExtensionsUse extensions so that you can implement your own obligation handler and authentication mechanism.

Managing extensions

Deploy your extensions to the appliance so that you can create an instance of it and use the instance in your policies. Extensions are contained in bundles. You can import, replace, export, and delete bundles that contain extensions.

Before you begin

Consider the following restrictions:

You cannot delete a bundle that has extensions that are used by a policy.

If you are replacing a bundle that contains extensions that are used by a policy, make sure that the new bundle:

Has the same file name as the old bundle

Contains the same exact extensions that are used by a policy

Contains the same exact properties as the original extensions

If you are replacing a bundle that contains extensions that are not used by a policy, make sure that the new bundle has the same file name as the old bundle.

Procedure

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Extensions.

Take one of the following actions:

Search for and view a bundle

Take any of the following actions to filter your view:

Type one or more characters in the Filter field. The list displays the bundles that start with those characters.

Sort the list by column with the up or down arrow on each column. For example, you can view the list of extension IDs in ascending order by clicking the up arrow.

Import a bundle

Click Import.

Click Browse to locate the bundle.

Click Import. The syntax of the file is checked. If there are errors, you must fix them before you can import the file.

Replace a bundle

Click Import.

Click Browse to locate the bundle.

Click OK when you are prompted that the bundle exists.

Export a bundle

Select the bundle that you want to export.

Click Export.

Save the file.

Delete a bundle

Select the bundle that you want to delete.

Click Delete. A message prompts you to confirm the deletion.

Click Delete.

Save and deploy your changes. For more information, see Deploying pending changes.

What to do next

If you imported a custom authentication mechanism, see Managing authentication mechanisms.

If you imported a custom obligation, see Managing obligations.

Parent topic: Extensions

Deploying pending changesDeploying pending changesDeploying changesSome configuration and administration changes require an extra deployment step.deploying changespending changesWhen you use the graphical user interface on the appliance to specify changes, some configuration and administration tasks take effect immediately. Other tasks require a deployment step to take effect. For these tasks, the appliance gives you a choice of deploying immediately or deploying later. When you must make multiple changes, you can wait until all changes are complete, and then deploy all of them at one time.When a deployment step is required, the user interface presents a message that says that there is an undeployed change. The number of pending changes is displayed in the message, and increments for each change you make.If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.When you finish making configuration changes, select Click here to review the changes or apply them to the system.The Deploy Pending Changes window is displayed.Select one of the following options:CancelDo not deploy the changes now. Retain the undeployed configuration changes. The appliance user interface returns to the previous panel.Roll BackAbandon configuration changes. A message is displayed, stating that the pending changes were reverted. The appliance user interface returns to the previous panel.DeployDeploy all configuration changes.When you select Deploy, a system message is displayed, stating that the changes were deployed.If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Deploying pending changes

Some configuration and administration changes require an extra deployment step.

About this task

When you use the graphical user interface on the appliance to specify changes, some configuration and administration tasks take effect immediately. Other tasks require a deployment step to take effect. For these tasks, the appliance gives you a choice of deploying immediately or deploying later. When you must make multiple changes, you can wait until all changes are complete, and then deploy all of them at one time.

When a deployment step is required, the user interface presents a message that says that there is an undeployed change. The number of pending changes is displayed in the message, and increments for each change you make.

Note: If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.

Procedure

When you finish making configuration changes, select Click here to review the changes or apply them to the system.

The Deploy Pending Changes window is displayed.

Select one of the following options:

Option
Description

Cancel
Do not deploy the changes now.

Retain the undeployed configuration changes. The appliance user interface returns to the previous panel.

Roll Back
Abandon configuration changes.

A message is displayed, stating that the pending changes were reverted. The appliance user interface returns to the previous panel.

Deploy
Deploy all configuration changes.

When you select Deploy, a system message is displayed, stating that the changes were deployed.

If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.

Parent topic: Advanced Access Control administration

Template filesTemplate filesTemplate filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors.template filesYou can customize any of the HTML pages by exporting, modifying, and importing its corresponding template file. Each template file uses one or more specific macros. See Template file macrosMost template pages contain one or more macros. The macros are replaced by values that are specific to the action that is requested on the page. for descriptions of the macros. Consent to register device template files These files support consent to registering a device. Default template files in the ac/ directoryPage nameFile name and macrosDescriptionAttribute Collection JavaScriptac/info.jsDetects the location of the device from which the requests are made. Collects the web browser attributes and sends them to the server for storing in the database. When the user logs out or when the current session times out, the script deletes the attributes from the database.Dynamics Attributes JavaScriptac/javascript_rules/dynamic_attributes.jsRuns after each request is processed by risk engine. Use it to capture attributes that do not get captured automatically. Captured attributes are stored either in the session storage or the behavior storage area of the risk-based component, or both. The risk profile configuration dictates where the attributes are stored. User self-care template files These files support user self-care tasks. Default template files in the access_control/ directoryPage nameFile name and macrosDescriptionCommon User Profile Management JavaScriptaccess_control/user/mgmt/common.jsUsed by one-time password pages and by device management pages. Contains functions and properties that are used for making calls to the user self-care REST services.Device Attributesaccess_control/user/mgmt/device/device_attributes.htmlEnables or disable devices. Renames or removes device. Displays all of the attributes for a device. For more information, see Managing your registered devices You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios. .Device Attributes JavaScriptaccess_control/user/mgmt/device/device_attributes.jsProcesses values that are entered in the device_attributes.html templateDevice Selectionaccess_control/user/mgmt/device/device_selection.htmlDisplays device name, status (enabled or disabled), and time of last activity. For more information, see Managing your registered devices You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios. .Device Selection JavaScriptaccess_control/user/mgmt/device/device_selection.jsProcesses data to display in the device_selections.html templateAuthorization Grantaccess_control/user/mgmt/device/grant_attributes.htmlEnables or disables an OAuth 2.0 authorization grant. Removes an OAuth 2.0 authorization grant. Displays the OAuth 2.0 tokens and attributes of an authorization grant. For more information, see Managing OAuth 2.0 authorization grants You can view your authorization grants and the tokens and attributes of each authorization grant..Authorization Grants JavaScriptaccess_control/user/mgmt/device/grant-attributes.jsProcesses data to display in the grant_attributes.html template.HMAC OTP Shared Keyaccess_control/user/mgmt/otp/otp.htmlResets TOTP and HOTP Secret Key. For more information, see Managing OTP secret keysTo help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability..HMAC OTP Shared Key JavaScriptaccess_control/user/mgmt/otp/otp.jsResets TOTP and HOTP Secret Key.Knowledge Questions managementaccess_control/user/mgmt/questions/user_questions.htmlMacros: @USERNAME @@MAX_STORED_QUESTIONS@Displayed for the user to manage their knowledge questions. The user can select pre-configured questions or write their own questions.Knowledge Questions JavaScript functions access_control/user/mgmt/questions/user_questions.js Consists of the JavaScript functions that: Display the knowledge questions.Allow the user to manage their knowledge questions. Authentication process template files These files support the authentication process. For more information, see AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.. Default template files in the authsvc/ directoryPage nameFile name and macrosDescriptionServer Errorauthsvc/server_error.htmlMacros:@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays general server errors. User Errorauthsvc/user_error.htmlMacros:@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during authentication policy execution that are caused by user input. Authentication mechanisms These files support the authentication mechanisms. For more information, see AuthenticationSecurity Access Manager provides user authentication functions that allow for simple and complex authentication scenarios.. Default template files in the otp/ directoryPage nameFile name and macrosDescription and link to file contentsChange PIN requiredotp/change_pin.htmlMacros:@ERROR_MESSAGE@@MAPPING_RULE_DATA@@DISPLAY_RESELECT_BUTTON@Enables the user to enter a new PIN.OTP Email Delivery Messageotp/delivery/email_message.xmlUsed by EmailOTPDelivery as the content of the email that it sends to the user.The template file must be a compliant XML file. The content can be plain text or HTML. Following is an example using HTML in the email template:<?xml version="1.0" encoding="UTF-8"?> <root> <Subject> <Value>One-time Password</Value> </Subject> <Message> <Value><![CDATA[<html> <body> <img src="https://www.example.com/images/logo.gif" /> <br />This is your HTML email one-time password @OTP_STRING@.<br /> <p>Thank you,<br /> The Example Co.</p> </body> </html>]]> </Value> </Message> </root>OTP SMS Delivery Messageotp/delivery/sms_message.xmlUsed by SMSOTPDelivery as the content of the SMS that it sends to the user.The template file must be a compliant XML file.One-Time Password Delivery Selectionotp/delivery_selection.htmlMacros:@OTP_METHOD_CHECKED@@OTP_METHOD_LABEL@Displays the list of methods for generating, delivering, and verifying the one-time password. OTP General Errorotp/errors/allerror.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_STACK@Displays general errors that happen during the one-time password flow.OTP Validation Errorotp/errors/error_could_not_validate_otp.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_STACK@Displays errors during the validation of the one-time password that the user submits.OTP Generation Errorotp/errors/error_generating_otp.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_STACK@Displays errors during the generation of a one-time password.OTP Methods Retrieval Errorotp/errors/error_get_delivery_options.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_STACK@Displays errors during the retrieval of the list of methods for delivering one-time password to the user. OTP Delivery Errorotp/errors/error_otp_delivery.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_STACK@Displays errors during the delivery of a one-time password to the user.OTP STS Invocation Errorotp/errors/error_sts_invoke_failed.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_STACK@Displays errors during the invocation of the Security Token Service.One-Time Password Loginotp/login.htmlMacros:@ERROR_MESSAGE@@MAPPING_RULE_DATA@@DISPLAY_RESELECT_BUTTON@Displays the form where the user can enter the one-time password.Enter Next OTP Formotp/next_otp.htmlMacros:@ERROR_MESSAGE@@MAPPING_RULE_DATA@@DISPLAY_RESELECT_BUTTON@Enables the user to enter the next one time password. Default template files in the authsvc/authenticator/password/ directoryPage nameFile name and macrosDescriptionChange Passwordauthsvc/authenticator/password/change_password.htmlMacros:@USERNAME@@ERROR_MESSAGE@Enables the users to change their registry password.Username and Password Errorauthsvc/authenticator/password/error.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during the user name and password authentication or when the users modify their password.Username and Password Loginauthsvc/authenticator/password/login.htmlDisplays the form where the users can enter their user name and password to log in. Default template files in the authsvc/authenticator/http_redirect/ directoryPage nameFile name and macrosDescriptionHTTP Redirect Authentication Errorauthsvc/authenticator/http_redirect/allerror.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays general errors during for HTTP redirect authentication mechanism.HTTP Redirect Authentication Failedauthsvc/authenticator/http_redirect/error_authenticate.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during the HTTP redirect authentication flow. Default template files in the authsvc/authenticator/macotp/ directoryPage nameFile name and macrosDescriptionMAC One-Time Password Delivery Selectionauthsvc/authenticator/macotp/delivery_selection.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays the list of methods for generating, delivering, and verifying the one-time password.MAC OTP One-Time Password Errorauthsvc/authenticator/macotp/error.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during the MAC one-time password authentication.MAC One-Time Password Loginauthsvc/authenticator/macotp/login.htmlMacros:@OTP_HINT@@OTP_LOGIN_DISABLED@Displays the form where the user can enter the MAC one-time password Default template files in the authsvc/authenticator/rsa/ directoryPage nameFile name and macrosDescriptionRSA One-Time Password Errorauthsvc/authenticator/rsa/error.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during the RSA one-time password authentication.RSA One-Time Password Loginauthsvc/authenticator/rsa/code.htmlMacro:@ERROR_MESSAGE@Displays the form where the users can enter the RSA one-time password to log in.RSA One-Time Password Login (New PIN)authsvc/authenticator/rsa/new_pin.htmlMacro:@ERROR_MESSAGE@Enables users to enter a new RSA pin.RSA One-Time Password Login (Next OTP)authsvc/authenticator/rsa/next_code.htmlMacro:@ERROR_MESSAGE@Enables users to enter the next RSA one-time password. Default template files in the authsvc/authenticator/totp/ directoryPage nameFile name and macrosDescriptionTOTP One-Time Password Errorauthsvc/authenticator/totp/error.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during the TOTP one-time password authentication.TOTP One-Time Password Loginauthsvc/authenticator/totp/login.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays the form where the users can enter the TOTP password to log in. Default template files in the authsvc/authenticator/hotp/ directoryPage nameFile name and macrosDescriptionHOTP One-Time Password Errorauthsvc/authenticator/hotp/error.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during the HOTP one-time password authentication.HOTP One-Time Password Loginauthsvc/authenticator/hotp/login.htmlMacros:@ERROR_MESSAGE@Displays the form where the users can enter the HOTP password to log in. Default template files in the authsvc/authenticator/consent_register_device/ directoryPage nameFile name and macrosDescriptionConsent to Device Registration Errorauthsvc/authenticator/consent_register_device/error.htmlMacros:@ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during the consent to device registration flow.Consent pageauthsvc/authenticator/consent_register_device/consent-form.htmlMacro:@ERROR_MESSAGE@Prompts the user to provide consent for registering a device. Default template files in the authsvc/authenticator/eula/ directoryPage nameFile name and macrosDescriptionEnd-User License Agreement license file displayauthsvc/authenticator/eula/license.txtContains the license agreement to display to the user.The template does not use replacement macros.You can add more license files to the template tree.Specify the metadata in the End-User License Agreement for the following purposes:AuditingForensic The End-User License Agreement authentication mechanism removes the metadata before it displays the license agreement to the user. The metadata must be on the first line of the license agreement. For example: Metadata: Version: 1.0 Identifier: 135223434343 When the user accepts the license agreement or declines the license agreement, the mechanism audits: The user action.The license file name.The corresponding metadata.End-User License Agreement license agreement displayauthsvc/authenticator/eula/eula.htmlMacros:@USERNAME@ @LICENSE@ Displays the page where the user views the license and accepts the license agreement. End-User License Agreement license agreement declineauthsvc/authenticator/eula/error_license_declined.htmlMacros:@USERNAME@ @ERROR_MESSAGE@@REQ_ADDR@@TIMESTAMP@@ERROR_MESSAGE@@EXCEPTION_MSG@@EXCEPTION_STACK@@LICENSE_FILE@@LICENSE_METADATA@ Displays the page where the user declines the license agreement. Default template files in the authsvc/authenticator/knowledge_questions/ directoryPage nameFile name and macrosDescriptionKnowledge Questions authentication mechanism knowledge question formauthsvc/authenticator/knowledge_questions/login.htmlMacros:@ QUESTION_TEXT @@ QUESTION_INDEX @@QUESTION_UNIQUE_ID@@QUESTION_COUNT@@ERROR_MESSAGE@@NUM_REQUIRED_ANSWERS@Displays the form where the user enters the answers to the required knowledge questions.Knowledge Questions authentication mechanism knowledge question authentication errorsauthsvc/authenticator/knowledge_questions/error.htmlMacros:@REQ_ADDR@@TIMESTAMP@@ERROR_MESSAGE@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors during knowledge-question authentication.Knowledge Questions authentication mechanism missing knowledge questions with grace periodauthsvc/authenticator/knowledge_questions/ not_enough_questions_found_continue.html Macros:@USERNAME@@NUM_REQUIRED_ANSWERS@ @NUM_REGISTERED_QUESTIONS@ @ GRACE_PERIOD_AUTH_COUNT@@MAX_ GRACE_PERIOD_AUTH_COUNT@ Displayed when the user did not register the required number of knowledge questions and answers that are required for successful authentication. The following conditions must also be true:The administrator configured the environment to allow grace-period authentication.The user did not reach the limit of grace-period logins.Knowledge Questions authentication mechanism missing knowledge questions without grace periodauthsvc/authenticator/knowledge_questions/ not_enough_questions_found_error.html Macros:@USERNAME@@NUM_REQUIRED_ANSWERS@ @NUM_REGISTERED_QUESTIONS@@REQ_ADDR@@TIMESTAMP@Displayed when the user did not register the required number of knowledge questions and answers that are required for successful authentication. One of the following conditions must also be true:The administrator did not configure the environment to allow grace-period authentication.The user reached the limit of grace-period logins. Authentication error template files These files display errors that occur during authentication. Default files in the proper/ directoryPage nameFile name and macrosDescriptionAccess Deniedproper/errors/access_denied.htmlMacros:@REQ_ADDR@@TIMESTAMP@Displays a message that the user cannot access the requested resource.General Errorproper/errors/allerror.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_STACK@Displays general errors that are not displayed in other template files. Missing Component Errorproper/errors/missingcomponent.htmlMacros:@REQ_ADDR@@TIMESTAMP@@DETAIL@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays an error that the component required to process the request was not correctly configured or was not initialized. Authentication Requiredproper/errors/need_authentication.htmlMacros:@REQ_ADDR@@TIMESTAMP@Displays an error that authentication is required to access the requested resource.Protocol Determination Errorproper/errors/noprotdet.htmlMacros:@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays an error that the access request is to an unknown address. The error might occur because no configured endpoint or protocol exists that is mapped to this endpoint.Protocol Runtime Errorproper/errors/protocol_error.htmlMacros:@REQ_ADDR@@TIMESTAMP@@EXCEPTION_MSG@@EXCEPTION_STACK@Displays errors that an error occurred fulfilling a request to a specified address, and the error was caused by an unexpected error on the protocol module. OAuth template files These files support OAuth. For more information, see OAuth 2.0 supportAdvanced Access Control supports the OAuth 2.0 protocol. The implementation of OAuth 2.0 in Advanced Access Control strictly follows the OAuth 2.0 standards.. Default files in the oauth20/ directoryPage nameFile name and macrosDescriptionOAuth 2.0 Trusted Clients Manageroauth20/clients_manager.htmlMacros:@USERNAME@@OAUTH_CLIENT_COMPANY_NAME@@PERMITTED_SCOPES@@OAUTH_CUSTOM_MACRO@Used by resource owners to show and manage trusted clients information. OAuth 2.0 - Consent to Authorizeoauth20/user_consent.htmlMacros:@USERNAME@@OAUTH_CLIENT_COMPANY_NAME@@PERMITTED_SCOPES@@OAUTH_CUSTOM_MACRO@Used by the authorization server to determine and store user consent information about which OAuth clients are authorized to access the protected resource. The page also lists of scopes that the OAuth client requests. These lists are shown in the consent page and can be of indeterminate length. The template supports multiple copies of stanzas that are repeated once for each scope in the lists.OAuth 2.0 - Erroroauth20/user_error.htmlMacros:@OAUTH_CLIENT_COMPANY_NAME@@CLIENT_TYPE@@CLIENT_ID@@REDIRECT_URI@@STATE@@RESPONSE_TYPE@@USERNAME@@OAUTH_TOKEN_SCOPE_REPEAT@@OAUTH_OTHER_PARAM_REPEAT@@OAUTH_OTHER_PARAM_VALUE_REPEAT@Shows detailed text information when an error occurs in an OAuth 2.0 flow.OAuth - Responseoauth20/user_response.htmlMacros:@OAUTH_CODE@Displays the authorization code of an OAuth client that did not specify a client redirection URI upon registration. When the OAuth client does not specify a client redirection URI or cannot receive redirects, the authorization server does not know where to send the resource owner after authorization. As a result, the OAuth client does not receive the authorization code that is required to exchange for an access token or refresh token.The page includes several codes: The authorization code that the resource owner can provide to the trusted OAuth client.The authorization code as machine-readable Quick Response (QR) code. The encoder that creates the QR code follows the ISO/IEC 18004:2006 specification. Scanners that support this specification can read the generated QR code. Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Modifying template filesUse the local management interface to manage files and directories in the template files.Template file macrosMost template pages contain one or more macros. The macros are replaced by values that are specific to the action that is requested on the page.

Template files

Template files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors.

You can customize any of the HTML pages by exporting, modifying, and importing its corresponding template file. Each template file uses one or more specific macros. See Template file macros for descriptions of the macros.

Consent to register device template files

These files support consent to registering a device.

Table 207. Default template files in the ac/ directory

Page name
File name and macros
Description

Attribute Collection JavaScript
ac/info.js
Detects the location of the device from which the requests are made. Collects the web browser attributes and sends them to the server for storing in the database. When the user logs out or when the current session times out, the script deletes the attributes from the database.

Dynamics Attributes JavaScript
ac/javascript_rules/dynamic_attributes.js
Runs after each request is processed by risk engine. Use it to capture attributes that do not get captured automatically. Captured attributes are stored either in the session storage or the behavior storage area of the risk-based component, or both. The risk profile configuration dictates where the attributes are stored.

User self-care template files

These files support user self-care tasks.

Table 208. Default template files in the access_control/ directory.

Page name
File name and macros
Description

Common User Profile Management JavaScript
access_control/user/mgmt/common.js
Used by one-time password pages and by device management pages. Contains functions and properties that are used for making calls to the user self-care REST services.

Device Attributes
access_control/user/mgmt/device/device_attributes.html
Enables or disable devices. Renames or removes device. Displays all of the attributes for a device.

For more information, see Managing your registered devices.

Device Attributes JavaScript
access_control/user/mgmt/device/device_attributes.js
Processes values that are entered in the device_attributes.html template

Device Selection
access_control/user/mgmt/device/device_selection.html
Displays device name, status (enabled or disabled), and time of last activity.

For more information, see Managing your registered devices.

Device Selection JavaScript
access_control/user/mgmt/device/device_selection.js
Processes data to display in the device_selections.html template

Authorization Grant
access_control/user/mgmt/device/grant_attributes.html
Enables or disables an OAuth 2.0 authorization grant. Removes an OAuth 2.0 authorization grant. Displays the OAuth 2.0 tokens and attributes of an authorization grant. For more information, see Managing OAuth 2.0 authorization grants.

Authorization Grants JavaScript
access_control/user/mgmt/device/grant-attributes.js
Processes data to display in the grant_attributes.html template.

HMAC OTP Shared Key
access_control/user/mgmt/otp/otp.html
Resets TOTP and HOTP Secret Key.

For more information, see Managing OTP secret keys.

HMAC OTP Shared Key JavaScript
access_control/user/mgmt/otp/otp.js
Resets TOTP and HOTP Secret Key.

Knowledge Questions management
access_control/user/mgmt/questions/user_questions.html

Macros:

@USERNAME @

@MAX_STORED_QUESTIONS@

Displayed for the user to manage their knowledge questions. The user can select pre-configured questions or write their own questions.

Knowledge Questions JavaScript functions
access_control/user/mgmt/questions/user_questions.js
Consists of the JavaScript functions that:

Display the knowledge questions.

Allow the user to manage their knowledge questions.

Authentication process template files

These files support the authentication process. For more information, see Authentication.

Table 209. Default template files in the authsvc/ directory.

Page name
File name and macros
Description

Server Error
authsvc/server_error.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays general server errors.

User Error
authsvc/user_error.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during authentication policy execution that are caused by user input.

Authentication mechanisms

These files support the authentication mechanisms. For more information, see Authentication.

Table 210. Default template files in the otp/ directory.

Page name
File name and macros
Description and link to file contents

Change PIN required
otp/change_pin.html

Macros:

@ERROR_MESSAGE@

@MAPPING_RULE_DATA@

@DISPLAY_RESELECT_BUTTON@

Enables the user to enter a new PIN.

OTP Email Delivery Message
otp/delivery/email_message.xml
Used by EmailOTPDelivery as the content of the email that it sends to the user.

The template file must be a compliant XML file.

The content can be plain text or HTML. Following is an example using HTML in the email template:

<?xml version="1.0" encoding="UTF-8"?>
<root>
<Subject>
  <Value>One-time Password</Value>
</Subject>
<Message>
  <Value><![CDATA[<html>
<body>
<img src="https://www.example.com/images/logo.gif" />
<br />This is your HTML email one-time password @OTP_STRING@.<br />
    <p>Thank you,<br />
    The Example Co.</p>
</body>
    </html>]]>
  </Value>
</Message>
</root>

OTP SMS Delivery Message
otp/delivery/sms_message.xml
Used by SMSOTPDelivery as the content of the SMS that it sends to the user.

The template file must be a compliant XML file.

One-Time Password Delivery Selection
otp/delivery_selection.html

Macros:

@OTP_METHOD_CHECKED@

@OTP_METHOD_LABEL@

Displays the list of methods for generating, delivering, and verifying the one-time password.

OTP General Error
otp/errors/allerror.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_STACK@

Displays general errors that happen during the one-time password flow.

OTP Validation Error
otp/errors/error_could_not_validate_otp.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_STACK@

Displays errors during the validation of the one-time password that the user submits.

OTP Generation Error
otp/errors/error_generating_otp.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_STACK@

Displays errors during the generation of a one-time password.

OTP Methods Retrieval Error
otp/errors/error_get_delivery_options.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_STACK@

Displays errors during the retrieval of the list of methods for delivering one-time password to the user.

OTP Delivery Error
otp/errors/error_otp_delivery.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_STACK@

Displays errors during the delivery of a one-time password to the user.

OTP STS Invocation Error
otp/errors/error_sts_invoke_failed.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_STACK@

Displays errors during the invocation of the Security Token Service.

One-Time Password Login
otp/login.html

Macros:

@ERROR_MESSAGE@

@MAPPING_RULE_DATA@

@DISPLAY_RESELECT_BUTTON@

Displays the form where the user can enter the one-time password.

Enter Next OTP Form
otp/next_otp.html

Macros:

@ERROR_MESSAGE@

@MAPPING_RULE_DATA@

@DISPLAY_RESELECT_BUTTON@

Enables the user to enter the next one time password.

Table 211. Default template files in the authsvc/authenticator/password/ directory.

Page name
File name and macros
Description

Change Password
authsvc/authenticator/password/change_password.html

Macros:

@USERNAME@

@ERROR_MESSAGE@

Enables the users to change their registry password.

Username and Password Error
authsvc/authenticator/password/error.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during the user name and password authentication or when the users modify their password.

Username and Password Login
authsvc/authenticator/password/login.html
Displays the form where the users can enter their user name and password to log in.

Table 212. Default template files in the authsvc/authenticator/http_redirect/ directory.

Page name
File name and macros
Description

HTTP Redirect Authentication Error
authsvc/authenticator/http_redirect/allerror.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays general errors during for HTTP redirect authentication mechanism.

HTTP Redirect Authentication Failed
authsvc/authenticator/http_redirect/error_authenticate.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during the HTTP redirect authentication flow.

Table 213. Default template files in the authsvc/authenticator/macotp/ directory.

Page name
File name and macros
Description

MAC One-Time Password Delivery Selection
authsvc/authenticator/macotp/delivery_selection.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays the list of methods for generating, delivering, and verifying the one-time password.

MAC OTP One-Time Password Error
authsvc/authenticator/macotp/error.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during the MAC one-time password authentication.

MAC One-Time Password Login
authsvc/authenticator/macotp/login.html

Macros:

@OTP_HINT@

@OTP_LOGIN_DISABLED@

Displays the form where the user can enter the MAC one-time password

Table 214. Default template files in the authsvc/authenticator/rsa/ directory.

Page name
File name and macros
Description

RSA One-Time Password Error
authsvc/authenticator/rsa/error.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during the RSA one-time password authentication.

RSA One-Time Password Login
authsvc/authenticator/rsa/code.html

Macro:

@ERROR_MESSAGE@

Displays the form where the users can enter the RSA one-time password to log in.

RSA One-Time Password Login (New PIN)
authsvc/authenticator/rsa/new_pin.html

Macro:

@ERROR_MESSAGE@

Enables users to enter a new RSA pin.

RSA One-Time Password Login (Next OTP)
authsvc/authenticator/rsa/next_code.html

Macro:

@ERROR_MESSAGE@

Enables users to enter the next RSA one-time password.

Table 215. Default template files in the authsvc/authenticator/totp/ directory.

Page name
File name and macros
Description

TOTP One-Time Password Error
authsvc/authenticator/totp/error.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during the TOTP one-time password authentication.

TOTP One-Time Password Login
authsvc/authenticator/totp/login.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays the form where the users can enter the TOTP password to log in.

Table 216. Default template files in the authsvc/authenticator/hotp/ directory.

Page name
File name and macros
Description

HOTP One-Time Password Error
authsvc/authenticator/hotp/error.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during the HOTP one-time password authentication.

HOTP One-Time Password Login
authsvc/authenticator/hotp/login.html

Macros:

@ERROR_MESSAGE@

Displays the form where the users can enter the HOTP password to log in.

Table 217. Default template files in the authsvc/authenticator/consent_register_device/ directory.

Page name
File name and macros
Description

Consent to Device Registration Error
authsvc/authenticator/consent_register_device/error.html

Macros:

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during the consent to device registration flow.

Consent page
authsvc/authenticator/consent_register_device/consent-form.html

Macro:

@ERROR_MESSAGE@

Prompts the user to provide consent for registering a device.

Table 218. Default template files in the authsvc/authenticator/eula/ directory.

Page name
File name and macros
Description

End-User License Agreement license file display
authsvc/authenticator/eula/license.txt
Contains the license agreement to display to the user.

The template does not use replacement macros.

Note: You can add more license files to the template tree.

Specify the metadata in the End-User License Agreement for the following purposes:

Auditing

Forensic

The End-User License Agreement authentication mechanism removes the metadata before it displays the license agreement to the user. The metadata must be on the first line of the license agreement. For example:

Metadata:   Version: 1.0          Identifier:  135223434343

When the user accepts the license agreement or declines the license agreement, the mechanism audits:

The user action.

The license file name.

The corresponding metadata.

End-User License Agreement license agreement display
authsvc/authenticator/eula/eula.html

Macros:

@USERNAME@

@LICENSE@

Displays the page where the user views the license and accepts the license agreement.

End-User License Agreement license agreement decline
authsvc/authenticator/eula/error_license_declined.html

Macros:

@USERNAME@

@ERROR_MESSAGE@

@REQ_ADDR@

@TIMESTAMP@

@ERROR_MESSAGE@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

@LICENSE_FILE@

@LICENSE_METADATA@

Displays the page where the user declines the license agreement.

Table 219. Default template files in the authsvc/authenticator/knowledge_questions/ directory.

Page name
File name and macros
Description

Knowledge Questions authentication mechanism knowledge question form
authsvc/authenticator/knowledge_questions/login.html

Macros:

@ QUESTION_TEXT @

@ QUESTION_INDEX @

@QUESTION_UNIQUE_ID@

@QUESTION_COUNT@

@ERROR_MESSAGE@

@NUM_REQUIRED_ANSWERS@

Displays the form where the user enters the answers to the required knowledge questions.

Knowledge Questions authentication mechanism knowledge question authentication errors
authsvc/authenticator/knowledge_questions/error.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@ERROR_MESSAGE@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors during knowledge-question authentication.

Knowledge Questions authentication mechanism missing knowledge questions with grace period
authsvc/authenticator/knowledge_questions/ not_enough_questions_found_continue.html

Macros:

@USERNAME@

@NUM_REQUIRED_ANSWERS@

@NUM_REGISTERED_QUESTIONS@

@ GRACE_PERIOD_AUTH_COUNT@

@MAX_ GRACE_PERIOD_AUTH_COUNT@

Displayed when the user did not register the required number of knowledge questions and answers that are required for successful authentication. The following conditions must also be true:

The administrator configured the environment to allow grace-period authentication.

The user did not reach the limit of grace-period logins.

Knowledge Questions authentication mechanism missing knowledge questions without grace period
authsvc/authenticator/knowledge_questions/ not_enough_questions_found_error.html

Macros:

@USERNAME@

@NUM_REQUIRED_ANSWERS@

@NUM_REGISTERED_QUESTIONS@

@REQ_ADDR@

@TIMESTAMP@

Displayed when the user did not register the required number of knowledge questions and answers that are required for successful authentication. One of the following conditions must also be true:

The administrator did not configure the environment to allow grace-period authentication.

The user reached the limit of grace-period logins.

Authentication error template files

These files display errors that occur during authentication.

Table 220. Default files in the proper/ directory.

Page name
File name and macros
Description

Access Denied
proper/errors/access_denied.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

Displays a message that the user cannot access the requested resource.

General Error
proper/errors/allerror.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_STACK@

Displays general errors that are not displayed in other template files.

Missing Component Error
proper/errors/missingcomponent.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@DETAIL@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays an error that the component required to process the request was not correctly configured or was not initialized.

Authentication Required
proper/errors/need_authentication.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

Displays an error that authentication is required to access the requested resource.

Protocol Determination Error
proper/errors/noprotdet.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays an error that the access request is to an unknown address. The error might occur because no configured endpoint or protocol exists that is mapped to this endpoint.

Protocol Runtime Error
proper/errors/protocol_error.html

Macros:

@REQ_ADDR@

@TIMESTAMP@

@EXCEPTION_MSG@

@EXCEPTION_STACK@

Displays errors that an error occurred fulfilling a request to a specified address, and the error was caused by an unexpected error on the protocol module.

OAuth template files

These files support OAuth. For more information, see OAuth 2.0 support.

Table 221. Default files in the oauth20/ directory.

Page name
File name and macros
Description

OAuth 2.0 Trusted Clients Manager
oauth20/clients_manager.html

Macros:

@USERNAME@

@OAUTH_CLIENT_COMPANY_NAME@

@PERMITTED_SCOPES@

@OAUTH_CUSTOM_MACRO@

Used by resource owners to show and manage trusted clients information.

OAuth 2.0 - Consent to Authorize
oauth20/user_consent.html

Macros:

@USERNAME@

@OAUTH_CLIENT_COMPANY_NAME@

@PERMITTED_SCOPES@

@OAUTH_CUSTOM_MACRO@

Used by the authorization server to determine and store user consent information about which OAuth clients are authorized to access the protected resource.

The page also lists of scopes that the OAuth client requests. These lists are shown in the consent page and can be of indeterminate length. The template supports multiple copies of stanzas that are repeated once for each scope in the lists.

OAuth 2.0 - Error
oauth20/user_error.html

Macros:

@OAUTH_CLIENT_COMPANY_NAME@

@CLIENT_TYPE@

@CLIENT_ID@

@REDIRECT_URI@

@STATE@

@RESPONSE_TYPE@

@USERNAME@

@OAUTH_TOKEN_SCOPE_REPEAT@

@OAUTH_OTHER_PARAM_REPEAT@

@OAUTH_OTHER_PARAM_VALUE_REPEAT@

Shows detailed text information when an error occurs in an OAuth 2.0 flow.

OAuth - Response
oauth20/user_response.html

Macros:

@OAUTH_CODE@

Displays the authorization code of an OAuth client that did not specify a client redirection URI upon registration.

When the OAuth client does not specify a client redirection URI or cannot receive redirects, the authorization server does not know where to send the resource owner after authorization. As a result, the OAuth client does not receive the authorization code that is required to exchange for an access token or refresh token.

The page includes several codes:

The authorization code that the resource owner can provide to the trusted OAuth client.

The authorization code as machine-readable Quick Response (QR) code.

Note: The encoder that creates the QR code follows the ISO/IEC 18004:2006 specification. Scanners that support this specification can read the generated QR code.

Modifying template files
Use the local management interface to manage files and directories in the template files.

Template file macros
Most template pages contain one or more macros. The macros are replaced by values that are specific to the action that is requested on the page.

Parent topic: Advanced Access Control administration

Modifying template filesModifying template filesModifying template filesUse the local management interface to manage files and directories in the template files.template files rootmanageYou can run the following tasks on the template files:New- Use this option if you want to create a new file or directory.Edit- Use this option if you want to view or modify the template file.Import- Use this option if you to import a file to the template files root.Export- Use this option if you want to export a file from the template files root.Rename- Use this option if you want to rename a file or directory from the template files root.Delete- Use this option if you want to delete a file or directory from the template files root.Import Zip- Use this option if you want to import the template files from a compressed file.Export Zip- Use this option if you want to export the template files as a compressed file. When you use this option to export template files as a compressed file, you cannot export an individual folder. The root directory, including all the subdirectories, is exported. To access the contents of a specific directory, export the entire template directory, and then view the directory from the extracted compressed file on your local workstation.Select Secure Access Control Global SettingsTemplate FilesWork with all the management files and directories.Create a file or directory in the template files rootSelect the directory of interest.Select New. Select File or Directory.Enter the name of the file or directory.Click Save.View or update the contents of a file in the template files rootSelect the file of interest.Select Edit. You can then view the contents of the file.Edit the contents of the file.Click Save.Export a file from the template files rootSelect the file of interest.Select ManageExport. Confirm the save operation when your browser displays a confirmation window.Rename file from the template files rootSelect the file or directory of interest.Select ManageRename. Enter the new resource name.Click Save.Delete file from the template files rootSelect the file or directory of interest.Select ManageDelete. Click Yes.Import a file to the template files rootSelect a file.Select ManageImport. Click Browse. Browse to the file that you want to import the contents from.Click Open.Click Import.Select a folder.Select ManageImport. Click Browse. Browse to the file that you want to import to the selected folder.Click Open.Click Import.Export the template file as a compressed fileSelect ManageExport Zip. Confirm the save operation when your browser displays a confirmation window.Import the template files as a compressed fileMake sure that the files in the compressed file are in the same directory structure as the files in the root directory or appliance. For example, if a file in the compressed file is in the /C directory of the appliance, the compressed file must contain the C folder and the file that you want to import. When you import a compressed file that contains: A file that exists in the appliance The file is replaced in the appliance.A file or directory that does not exist in the appliance The file or directory is created in the appliance. You can put these new files and directories in an existing non-root directory or add a new directory in the root. You cannot delete a top level directory after you create it.Select ManageImport Zip. Click Browse. Browse to the file you want to import.Click Open.Click Import.When you edit or import template files, the appliance displays a message that there are undeployed changes. If you finish the changes, deploy them. For more information, see Deploying pending changesSome configuration and administration changes require an extra deployment step.. Template filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors.

Modifying template files

Use the local management interface to manage files and directories in the template files.

About this task

You can run the following tasks on the template files:

New- Use this option if you want to create a new file or directory.

Edit- Use this option if you want to view or modify the template file.

Import- Use this option if you to import a file to the template files root.

Export- Use this option if you want to export a file from the template files root.

Rename- Use this option if you want to rename a file or directory from the template files root.

Delete- Use this option if you want to delete a file or directory from the template files root.

Import Zip- Use this option if you want to import the template files from a compressed file.

Export Zip- Use this option if you want to export the template files as a compressed file.

Note: When you use this option to export template files as a compressed file, you cannot export an individual folder. The root directory, including all the subdirectories, is exported. To access the contents of a specific directory, export the entire template directory, and then view the directory from the extracted compressed file on your local workstation.

Procedure

Select Secure Access Control > Global Settings > Template Files

Work with all the management files and directories.

Create a file or directory in the template files root

Select the directory of interest.

Select New.

Select File or Directory.

Enter the name of the file or directory.

Click Save.

View or update the contents of a file in the template files root

Select the file of interest.

Select Edit. You can then view the contents of the file.

Edit the contents of the file.

Click Save.

Export a file from the template files root

Select the file of interest.

Select Manage > Export.

Confirm the save operation when your browser displays a confirmation window.

Rename file from the template files root

Select the file or directory of interest.

Select Manage > Rename.

Enter the new resource name.

Click Save.

Delete file from the template files root

Select the file or directory of interest.

Select Manage > Delete.

Click Yes.

Import a file to the template files root

Select a file.

Select Manage > Import.

Click Browse.

Browse to the file that you want to import the contents from.

Click Open.

Click Import.

Select a folder.

Select Manage > Import.

Click Browse.

Browse to the file that you want to import to the selected folder.

Click Open.

Click Import.

Export the template file as a compressed file

Select Manage > Export Zip.

Confirm the save operation when your browser displays a confirmation window.

Import the template files as a compressed file

Make sure that the files in the compressed file are in the same directory structure as the files in the root directory or appliance.

For example, if a file in the compressed file is in the /C directory of the appliance, the compressed file must contain the C folder and the file that you want to import. When you import a compressed file that contains:

A file that exists in the appliance

The file is replaced in the appliance.

A file or directory that does not exist in the appliance

The file or directory is created in the appliance. You can put these new files and directories in an existing non-root directory or add a new directory in the root.

Note: You cannot delete a top level directory after you create it.

Select Manage > Import Zip.

Click Browse.

Browse to the file you want to import.

Click Open.

Click Import.

When you edit or import template files, the appliance displays a message that there are undeployed changes. If you finish the changes, deploy them.

For more information, see Deploying pending changes.

Parent topic: Template files

Template file macrosTemplate file macrosTemplate file macrosMost template pages contain one or more macros. The macros are replaced by values that are specific to the action that is requested on the page.template filesmacros MacroValue that replaces the macro@CLIENT_ID@The client_id parameter that is specified in the authorization request.@CONSENT_FORM_VERIFIER@A unique identifier for the consent_form_verifier parameter value. The value is automatically generated by the authorization server. Do not modify the parameter name or value.@DETAIL@The error message.@ERROR_CODE@Characters that uniquely identify the error.@ERROR_DESCRIPTION@The native language support (NLS) text of the error message that is associated with the error.@ERROR_MESSAGE@An error message that is specific to the action in the page. For example, on the One-time password template page for login, the error message indicates that the password submitted contains errors, such as the password is not valid or has expired.@EXCEPTION_MSG@The exception message.@EXCEPTION_STACK@The stack trace of the error.@GRACE_PERIOD_AUTH_COUNT@ The amount of grace-period authentication.@LICENSE@The contents of the license file.@LICENSE_FILE@The name of the license file.@LICENSE_METADATA@The metadata that is either:Defined in the license file.Not Available if it is not defined.@MAPPING_RULE_DATA@If the submitted one-time password contains an error, this value is the STS Universal User context attribute with the name @MAPPING_RULE_DATA@ and is type otp.sts.macro.type. This context attribute can be set in the OTPVerify mapping ruleOTPVerify specifies the verification of the one-time password that is submitted by the user..@MAX_GRACE_PERIOD_AUTH_COUNT@The maximum count of grace-period authentication that is allotted to a policy.@MAX_STORED_QUESTIONS@The maximum number of answers that can be stored per user.@NUM_REQUIRED_ANSWERS@ The number of valid answers that is required for successful authentication.@NUM_REGISTERED_QUESTIONS@ The number of questions that the user registered.@OAUTH_AUTHORIZE_URI@The URI for the authorization endpoint.@OAUTH_CLIENT_COMPANY_NAME@A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with the name of the company that requests access to the protected resource.@OAUTH_CLIENTMANAGERURL@A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with the endpoint of the trusted clients manager.@OAUTH_CODE@The oauth_code parameter that is specified in the authorization response.@OAUTH_CUSTOM_MACRO@A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with trusted client information that contains additional information about an authorized OAuth client.@OAUTH_OTHER_PARAM_REPEAT@A multi-valued macro that belongs inside an [RPT oauthOtherParamsRepeatable] repeatable replacement list. The values show the list of extra parameter names.@OAUTH_OTHER_PARAM_VALUE_REPEAT@A multi-valued macro that belongs inside an [RPT oauthOtherParamsRepeatable] repeatable replacement list. The values show the list of extra parameter values.@OAUTH_TOKEN_SCOPE_REPEAT@A multi-valued macro that belongs inside an [RPT oauthTokenScopePreapprovedRepeatable] or [RPT oauthTokenScopeNewApprovalRepeatable]repeatable replacement lists. The values inside the [RPT oauthTokenScopePreapprovedRepeatable] show the list of token scopes that have been previously approved by the resource owner. Alternatively, the values inside the [RPT oauthTokenScopeNewApprovalRepeatable] show the list of token scopes that have not yet been approved by the resource owner. @OTP_HINT@The one-time password hint. The hint is a sequence of characters that is associated with the one-time password.@OTP_METHOD_CHECKED@For the first method, this macro is replaced with an HTML radio button attribute that causes that radio button to be selected. For the remaining methods that generate, deliver, and verify one-time passwords, this macro is replaced with an empty string.I'm not really sure what the sentence about the button means!@OTP_METHOD_ID@The ID of the method for generating, delivering, and verifying the one-time password. This ID is generated by the OTPGetMethods mapping rule. @OTP_METHOD_LABEL@The label of the method for generating, delivering, and verifying the one-time password. This label is generated by the OTPGetMethods mapping rule.@OTP_METHOD_TYPE@The type of the currently selected method for generating, delivering, and verifying the one-time password. This type is generated by the OTPGetMethods mapping rule and was selected by the user.@OTP_STRING@The one-time password that is generated by the one-time password provider.@PERMITTED_SCOPES@A multi-valued macro that belongs inside an [RPT trustedClients] repeatable list. The values are replaced with the token scopes to which the OAuth client has access.@QUESTION_COUNT@The number of questions that are presented on the login page.@QUESTION_TEXT@The question text. This macro is only populated when the question is a user-provided question.@QUESTION_INDEX@The question index. This index corresponds to the array of questions that are presented on the page when questions are presented as a group.@QUESTION_UNIQUE_ID@The question unique identifier. @REDIRECT_URI@The redirect URI that the authorization server uses to send the authorization code to. The value depends on the following items:Redirect URI that is entered during partner registration.oauth_redirect parameter that is specified in the authorization request@REGENERATE_ACTION@The URl where the Generate button posts the form to regenerate and deliver the new one-time password value.@RESPONSE_TYPE@The response_type parameter specified in the authorization request.@REQ_ADDR@The URL into which the request from the user is sent.@RESELECT_ACTION@The URl where the Reselect button posts the form to reselect the method for generating, delivering, and verifying the one-time password value.@STATE@The state parameter that is specified in the authorization request.@TIMESTAMP@The time stamp when the error occurred.@UNIQUE_ID@A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with a unique identifier that identifies the trusted client information for each entry in the list.@USERNAME@The Security Access Manager user name. Template filesTemplate files are HTML pages that are presented to your users during the authentication process. The pages prompt users for authentication information, such as user names and passwords, or present information to users, such as one-time passwords, status, or errors.

Template file macros

Most template pages contain one or more macros. The macros are replaced by values that are specific to the action that is requested on the page.

Macro
Value that replaces the macro

@CLIENT_ID@
The client_id parameter that is specified in the authorization request.

@CONSENT_FORM_VERIFIER@
A unique identifier for the consent_form_verifier parameter value. The value is automatically generated by the authorization server. Do not modify the parameter name or value.

@DETAIL@
The error message.

@ERROR_CODE@
Characters that uniquely identify the error.

@ERROR_DESCRIPTION@
The native language support (NLS) text of the error message that is associated with the error.

@ERROR_MESSAGE@
An error message that is specific to the action in the page. For example, on the One-time password template page for login, the error message indicates that the password submitted contains errors, such as the password is not valid or has expired.

@EXCEPTION_MSG@
The exception message.

@EXCEPTION_STACK@
The stack trace of the error.

@GRACE_PERIOD_AUTH_COUNT@
The amount of grace-period authentication.

@LICENSE@
The contents of the license file.

@LICENSE_FILE@
The name of the license file.

@LICENSE_METADATA@
The metadata that is either:

Defined in the license file.

Not Available if it is not defined.

@MAPPING_RULE_DATA@
If the submitted one-time password contains an error, this value is the STS Universal User context attribute with the name @MAPPING_RULE_DATA@ and is type otp.sts.macro.type. This context attribute can be set in the OTPVerify mapping rule.

@MAX_GRACE_PERIOD_AUTH_COUNT@
The maximum count of grace-period authentication that is allotted to a policy.

@MAX_STORED_QUESTIONS@
The maximum number of answers that can be stored per user.

@NUM_REQUIRED_ANSWERS@
The number of valid answers that is required for successful authentication.

@NUM_REGISTERED_QUESTIONS@
The number of questions that the user registered.

@OAUTH_AUTHORIZE_URI@
The URI for the authorization endpoint.

@OAUTH_CLIENT_COMPANY_NAME@
A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with the name of the company that requests access to the protected resource.

@OAUTH_CLIENTMANAGERURL@
A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with the endpoint of the trusted clients manager.

@OAUTH_CODE@
The oauth_code parameter that is specified in the authorization response.

@OAUTH_CUSTOM_MACRO@
A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with trusted client information that contains additional information about an authorized OAuth client.

@OAUTH_OTHER_PARAM_REPEAT@
A multi-valued macro that belongs inside an [RPT oauthOtherParamsRepeatable] repeatable replacement list. The values show the list of extra parameter names.

@OAUTH_OTHER_PARAM_VALUE_REPEAT@
A multi-valued macro that belongs inside an [RPT oauthOtherParamsRepeatable] repeatable replacement list. The values show the list of extra parameter values.

@OAUTH_TOKEN_SCOPE_REPEAT@
A multi-valued macro that belongs inside an [RPT oauthTokenScopePreapprovedRepeatable] or [RPT oauthTokenScopeNewApprovalRepeatable]repeatable replacement lists. The values inside the [RPT oauthTokenScopePreapprovedRepeatable] show the list of token scopes that have been previously approved by the resource owner. Alternatively, the values inside the [RPT oauthTokenScopeNewApprovalRepeatable] show the list of token scopes that have not yet been approved by the resource owner.

@OTP_HINT@
The one-time password hint. The hint is a sequence of characters that is associated with the one-time password.

@OTP_METHOD_CHECKED@
For the first method, this macro is replaced with an HTML radio button attribute that causes that radio button to be selected. For the remaining methods that generate, deliver, and verify one-time passwords, this macro is replaced with an empty string.

@OTP_METHOD_ID@
The ID of the method for generating, delivering, and verifying the one-time password. This ID is generated by the OTPGetMethods mapping rule.

@OTP_METHOD_LABEL@
The label of the method for generating, delivering, and verifying the one-time password. This label is generated by the OTPGetMethods mapping rule.

@OTP_METHOD_TYPE@
The type of the currently selected method for generating, delivering, and verifying the one-time password. This type is generated by the OTPGetMethods mapping rule and was selected by the user.

@OTP_STRING@
The one-time password that is generated by the one-time password provider.

@PERMITTED_SCOPES@
A multi-valued macro that belongs inside an [RPT trustedClients] repeatable list. The values are replaced with the token scopes to which the OAuth client has access.

@QUESTION_COUNT@
The number of questions that are presented on the login page.

@QUESTION_TEXT@
The question text. This macro is only populated when the question is a user-provided question.

@QUESTION_INDEX@
The question index. This index corresponds to the array of questions that are presented on the page when questions are presented as a group.

@QUESTION_UNIQUE_ID@
The question unique identifier.

@REDIRECT_URI@
The redirect URI that the authorization server uses to send the authorization code to. The value depends on the following items:

Redirect URI that is entered during partner registration.

oauth_redirect parameter that is specified in the authorization request

@REGENERATE_ACTION@
The URl where the Generate button posts the form to regenerate and deliver the new one-time password value.

@RESPONSE_TYPE@
The response_type parameter specified in the authorization request.

@REQ_ADDR@
The URL into which the request from the user is sent.

@RESELECT_ACTION@
The URl where the Reselect button posts the form to reselect the method for generating, delivering, and verifying the one-time password value.

@STATE@
The state parameter that is specified in the authorization request.

@TIMESTAMP@
The time stamp when the error occurred.

@UNIQUE_ID@
A multi-valued macro that belongs inside an [RPT trustedClients] repeatable replacement list. The values are replaced with a unique identifier that identifies the trusted client information for each entry in the list.

@USERNAME@
The Security Access Manager user name.

Parent topic: Template files

SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. SCIM is an HTTP-based protocol that makes managing identities in multi-domain scenarios easier to support through a standardized service. Security Access Manager provides SCIM-based web services to facilitate user self care capabilities such as social login association, account enablement, and password reset. You can use the SCIM Configuration page in the local management interface to configure the SCIM capabilities. If a reverse proxy is used in front of the SCIM components, the IV credential headers (also known as iv-users/iv-groups/iv-creds), if provided, will be used to obtain the authenticated user identity for the request.A demo application is provided for authenticated users to view and modify their own data. This application can be accessed at the following URL:https://<runtime_server>/scim/demo.htmlBy default, the demo application is disabled on the appliance. To enable it, go to Manage System SettingsAdvanced Tuning Parameters, add an advanced tuning parameter named scim_demo_enabled, and set its value to true.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.General SCIM settingsThe general SCIM settings include common configuration for the SCIM Web Service.User profileThe user profile configuration contains the settings that are required to manage the user data that is stored in the user registry.External authentication servicesThe external authentication services configuration contains the settings that are required by an external authentication service.ISAM userThe ISAM user configurations enable the SCIM web service to manage the Security Access Manager security entities.

SCIM configuration

Security Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol.

SCIM is an HTTP-based protocol that makes managing identities in multi-domain scenarios easier to support through a standardized service. Security Access Manager provides SCIM-based web services to facilitate user self care capabilities such as social login association, account enablement, and password reset. You can use the SCIM Configuration page in the local management interface to configure the SCIM capabilities.

Note: If a reverse proxy is used in front of the SCIM components, the IV credential headers (also known as iv-users/iv-groups/iv-creds), if provided, will be used to obtain the authenticated user identity for the request.

A demo application is provided for authenticated users to view and modify their own data. This application can be accessed at the following URL:

https://<runtime_server>/scim/demo.html

By default, the demo application is disabled on the appliance. To enable it, go to Manage System Settings > Advanced Tuning Parameters, add an advanced tuning parameter named scim_demo_enabled, and set its value to true.

General SCIM settings
The general SCIM settings include common configuration for the SCIM Web Service.

User profile
The user profile configuration contains the settings that are required to manage the user data that is stored in the user registry.

External authentication services
The external authentication services configuration contains the settings that are required by an external authentication service.

ISAM user
The ISAM user configurations enable the SCIM web service to manage the Security Access Manager security entities.

Parent topic: Advanced Access Control administration

General SCIM settingsThe general SCIM settings include common configuration for the SCIM Web Service.From the top menu, go to Secure Access ControlManageSCIM Configuration.On the General page, modify the following options as needed.Enable ISAM Header AuthenticationControls whether ISAM Header Authentication is enabled. ISAM Header Authentication is used to add the Security Access Manager credential attributes to the session so they can be used by SCIM.Enable Authorization FilterThe authorization filter is responsible for authorizing the request. It has some pre-defined rules for each of the supported SCIM end-points. These rules are:For the user profile functionalityOnly authenticated users with administrator authority are allowed to do a search of users (GET /Users).Unauthenticated access is allowed for creating a new user (POST /Users).Only authenticated users with administrator authority or authenticated users who are accessing their own data are allowed to perform create, retrieve, update, and delete operations on a specific user's data (GET/PUT/DELETE/PATCH /Me or /Users/<id>).For other functionalitiesAny authenticated user is allowed to retrieve information about the SCIM service (GET /ServiceProviderConfig, /ResourceTypes, or /Schemas).If more advanced or different authorization is required, disable this filter and use a Web Reverse Proxy or the Advanced Access Control component in front of the SCIM application to handle the authorization.Administration GroupThis group is used by the authorization filter for authorization checks where the user must be a member of the administration group.Max User ResponsesSets the maximum number of users that can be returned from a web service query to list users.Attribute ModeEach SCIM attribute has an associated mutability mode. The value can be ReadOnly, ReadWrite, AdminWrite, UserWrite, WriteOnly, or Immutable. The value of the default column shows if the mode is default (true) or user defined (false). A mode can be reset to default by setting this mode to an empty string.You can expand an attribute to see its subattributes.Click Save to save the changes.Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol.

General SCIM settings

The general SCIM settings include common configuration for the SCIM Web Service.

Procedure

From the top menu, go to Secure Access Control > Manage > SCIM Configuration.

On the General page, modify the following options as needed.

Enable ISAM Header Authentication

Controls whether ISAM Header Authentication is enabled. ISAM Header Authentication is used to add the Security Access Manager credential attributes to the session so they can be used by SCIM.

Enable Authorization Filter

The authorization filter is responsible for authorizing the request. It has some pre-defined rules for each of the supported SCIM end-points. These rules are:

For the user profile functionality

Only authenticated users with administrator authority are allowed to do a search of users (GET /Users).

Unauthenticated access is allowed for creating a new user (POST /Users).

Only authenticated users with administrator authority or authenticated users who are accessing their own data are allowed to perform create, retrieve, update, and delete operations on a specific user's data (GET/PUT/DELETE/PATCH /Me or /Users/<id>).

For other functionalities

Any authenticated user is allowed to retrieve information about the SCIM service (GET /ServiceProviderConfig, /ResourceTypes, or /Schemas).

If more advanced or different authorization is required, disable this filter and use a Web Reverse Proxy or the Advanced Access Control component in front of the SCIM application to handle the authorization.

Administration Group

This group is used by the authorization filter for authorization checks where the user must be a member of the administration group.

Max User Responses

Sets the maximum number of users that can be returned from a web service query to list users.

Attribute Mode

Each SCIM attribute has an associated mutability mode. The value can be ReadOnly, ReadWrite, AdminWrite, UserWrite, WriteOnly, or Immutable.

The value of the default column shows if the mode is default (true) or user defined (false). A mode can be reset to default by setting this mode to an empty string.

You can expand an attribute to see its subattributes.

Click Save to save the changes.

Note: Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.

Parent topic: SCIM configuration

User profileThe user profile configuration contains the settings that are required to manage the user data that is stored in the user registry.From the top menu, go to Secure Access ControlManageSCIM Configuration.Click User Profile.Modify the following settings as needed.LDAP ServerThis server connection is a pointer to an LDAP server connection that has been defined in the Advanced Access Control server connections page. This field is required.LDAP User Related Object ClassesThe LDAP object classes that are used to reference a user object. These values are the object classes that will be looked for when parsing the response to an LDAP subschema query. This is how the list of LDAP user attributes are determined and made available to the administrator for mapping SCIM attributes to LDAP attributes.This field is optional. If this field is not set, then no LDAP attributes will be available.Attribute MappingsThe list of SCIM attributes and the mapped source for the attribute, either an LDAP or session attribute. You can expand an attribute to see its subattributes.The LDAP server connection and object classes settings must be set in the respective fields before any LDAP attributes are made available.Search SuffixThis field contains the user suffix from which LDAP search operations will commence.User SuffixThis field contains the suffix that will house any users that are created through the SCIM interface.Click Save to save the changes.Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol.

User profile

The user profile configuration contains the settings that are required to manage the user data that is stored in the user registry.

Procedure

From the top menu, go to Secure Access Control > Manage > SCIM Configuration.

Click User Profile.

Modify the following settings as needed.

LDAP Server

This server connection is a pointer to an LDAP server connection that has been defined in the Advanced Access Control server connections page.

This field is required.

LDAP User Related Object Classes

The LDAP object classes that are used to reference a user object. These values are the object classes that will be looked for when parsing the response to an LDAP subschema query. This is how the list of LDAP user attributes are determined and made available to the administrator for mapping SCIM attributes to LDAP attributes.

This field is optional. If this field is not set, then no LDAP attributes will be available.

Attribute Mappings

The list of SCIM attributes and the mapped source for the attribute, either an LDAP or session attribute. You can expand an attribute to see its subattributes.

Note: The LDAP server connection and object classes settings must be set in the respective fields before any LDAP attributes are made available.

Search Suffix

This field contains the user suffix from which LDAP search operations will commence.

User Suffix

This field contains the suffix that will house any users that are created through the SCIM interface.

Click Save to save the changes.

Note: Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.

Parent topic: SCIM configuration

External authentication servicesThe external authentication services configuration contains the settings that are required by an external authentication service.From the top menu, go to Secure Access ControlManageSCIM Configuration.Click External Authentication Services.You can add or edit external authentication services. Each external authentication service definition has the following fields.Server ConnectionThis server connection is a pointer to a Web service server connection that has been defined in the Advanced Access Control server connections page. This field is required.Supported SchemasThe names of the SCIM schemas managed by this service.Click Save to save the changes.Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol.

External authentication services

The external authentication services configuration contains the settings that are required by an external authentication service.

Procedure

From the top menu, go to Secure Access Control > Manage > SCIM Configuration.

Click External Authentication Services.

You can add or edit external authentication services. Each external authentication service definition has the following fields.

Server Connection

This server connection is a pointer to a Web service server connection that has been defined in the Advanced Access Control server connections page.

This field is required.

Supported Schemas

The names of the SCIM schemas managed by this service.

Click Save to save the changes.

Note: Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.

Parent topic: SCIM configuration

ISAM userThe ISAM user configurations enable the SCIM web service to manage the Security Access Manager security entities.When ISAM integration is enabled, the SCIM web service can perform the following operations to manage Security Access Manager identity: Import a user to the secAuthority=<Domain> suffixDelete a user from the secAuthority=<Domain> suffixEnable or disable a user accountChange a users passwordMark a user password as invalid This function is implemented through the urn:ietf:params:scim:schemas:extension:isam:1.0:User schema. The data that is available as a part of this schema can be obtained from the SCIM schema web service. The ISAM user configuration only works in conjunction with the user profile configuration if the LDAP registry and suffix used by the user profile configuration is known to Security Access Manager (either as the Security Access Manager user registry or a federated user registry).From the top menu, go to Secure Access ControlManageSCIM Configuration.Click ISAM User.Modify the following settings as needed.Enable ISAM IntegrationSelect this check box to enable the integration with Security Access Manager and the management of Security Access Manager users.LDAP ConnectionThe name of an LDAP server connection. This LDAP server connection should reference the Security Access Manager user registry.Management DomainThe Security Access Manager Management domain name. The default value for this field is Default.Update Native UsersThis option defines whether the uid attribute of the native user entry is updated with the Security Access Manager user identity when a Security Access Manager user is created. Enabling this option allows Security Access Manager to authenticate users with their Security Access Manager user identity.Click Save to save the changes.Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.SCIM configurationSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol.

ISAM user

The ISAM user configurations enable the SCIM web service to manage the Security Access Manager security entities.

About this task

When ISAM integration is enabled, the SCIM web service can perform the following operations to manage Security Access Manager identity:

Import a user to the secAuthority=<Domain> suffix

Delete a user from the secAuthority=<Domain> suffix

Enable or disable a user account

Change a users password

Mark a user password as invalid

This function is implemented through the urn:ietf:params:scim:schemas:extension:isam:1.0:User schema. The data that is available as a part of this schema can be obtained from the SCIM schema web service.

The ISAM user configuration only works in conjunction with the user profile configuration if the LDAP registry and suffix used by the user profile configuration is known to Security Access Manager (either as the Security Access Manager user registry or a federated user registry).

Procedure

From the top menu, go to Secure Access Control > Manage > SCIM Configuration.

Click ISAM User.

Modify the following settings as needed.

Enable ISAM Integration

Select this check box to enable the integration with Security Access Manager and the management of Security Access Manager users.

LDAP Connection

The name of an LDAP server connection. This LDAP server connection should reference the Security Access Manager user registry.

Management Domain

The Security Access Manager Management domain name. The default value for this field is Default.

Update Native Users

This option defines whether the uid attribute of the native user entry is updated with the Security Access Manager user identity when a Security Access Manager user is created. Enabling this option allows Security Access Manager to authenticate users with their Security Access Manager user identity.

Click Save to save the changes.

Note: Due to the caching of configuration data within the runtime, it might take up to 30 seconds before any deployed configuration changes become active.

Parent topic: SCIM configuration

User self-administration tasksUser self-administration tasksUser self-administration tasksAdministrators can configure context-based access to enable users to perform certain self-management tasks.user self-administrationA common user task is to manage registered devices. For example, users can view the attributes for a device. Also, a user can rename a device.Users can also view, specify and configure secret keys for use with one-time password.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.Managing your registered devices You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios. Managing OTP secret keysTo help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability.Configuring knowledge questionsUse the Knowledge Questions management page to manage the knowledge questions that the Knowledge Questions authentication mechanism will present as a step-up authentication measure.SCIM account managementSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. The SCIM interface can be used as a consolidated API for accessing user data from various data sources.

User self-administration tasks

Administrators can configure context-based access to enable users to perform certain self-management tasks.

A common user task is to manage registered devices. For example, users can view the attributes for a device. Also, a user can rename a device.

Users can also view, specify and configure secret keys for use with one-time password.

Managing your registered devices
You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios.

Managing OTP secret keys
To help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability.

Configuring knowledge questions
Use the Knowledge Questions management page to manage the knowledge questions that the Knowledge Questions authentication mechanism will present as a step-up authentication measure.

SCIM account management
Security Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. The SCIM interface can be used as a consolidated API for accessing user data from various data sources.

Parent topic: Advanced Access Control administration

Managing your registered devicesManaging your registered devicesManaging your registered devices You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios. device fingerprints managingYou can complete the following tasks: View a list of your registered devices and the list of attributes that each device has.Rename your registered devices.Remove your registered devices.Disable your registered devices. When you disable a registered device, the device is still registered. However, when a login request comes from the disabled device, the risk engine gives that session the highest level of risk possible, which is 100. Enable your registered devices.Take one of the following actions: View your registered devices and the attributes that each device has Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html. Click the name of a device from the table to view the attributes of that device. You can also use the following URL to go directly to the attributes page of a specific device: https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_attributes.html?id=x. The query string, ?id=x indicates the device that you are trying to access. The x represents the ID of the device. Rename your registered devices Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html. If you select a specific device name, https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_attributes.html loads with an attributes page specific to that device.Click the device that you want to rename.Type the name into the device name field, and click Rename Device. The device name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters: ~ ! @ # $ % ^ & * ( ) + | ` = \ ; " ' < > ? , [ ] { } / anywhere in the name. Remove a registered device Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html. If you select a specific device name, https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_attributes.html loads with an attributes page specific to that device. Click Remove next to the device that you want to remove. You can also click the device that you want to remove and view the attributes that belong to the device before you remove the device. Click Remove Device underneath the attributes when you are ready to remove the device. Disable a registered device Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html. Clear the Enabled box next to the device that you want to disable. Enable a registered device Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html. Select the Enabled box next to the device that you want to enable. REST services for device fingerprint registrationYou can use the REST services capability to manage your mobile data such as your registered devices.User self-administration tasksAdministrators can configure context-based access to enable users to perform certain self-management tasks.

Managing your registered devices

You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios.

About this task

You can complete the following tasks:

View a list of your registered devices and the list of attributes that each device has.

Rename your registered devices.

Remove your registered devices.

Disable your registered devices. When you disable a registered device, the device is still registered. However, when a login request comes from the disabled device, the risk engine gives that session the highest level of risk possible, which is 100.

Enable your registered devices.

Procedure

Take one of the following actions:

View your registered devices and the attributes that each device has

Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html.

Click the name of a device from the table to view the attributes of that device.

Note: You can also use the following URL to go directly to the attributes page of a specific device: https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_attributes.html?id=x.

The query string, ?id=x indicates the device that you are trying to access. The x represents the ID of the device.

Rename your registered devices

Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html.

Note: If you select a specific device name, https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_attributes.html loads with an attributes page specific to that device.

Click the device that you want to rename.

Type the name into the device name field, and click Rename Device.

Note: The device name must begin with an alphabetic character. Do not use control characters, leading and trailing blanks, and the following special characters: ~ ! @ # $ % ^ & * ( ) + | ` = \ ; " ' < > ? , [ ] { } / anywhere in the name.

Remove a registered device

Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html.

Note: If you select a specific device name, https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_attributes.html loads with an attributes page specific to that device.

Click Remove next to the device that you want to remove.

Note: You can also click the device that you want to remove and view the attributes that belong to the device before you remove the device. Click Remove Device underneath the attributes when you are ready to remove the device.

Disable a registered device

Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html.

Clear the Enabled box next to the device that you want to disable.

Enable a registered device

Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/device/device_selection.html.

Select the Enabled box next to the device that you want to enable.

Parent topic: User self-administration tasks

REST services for device fingerprint registration

Managing OTP secret keysManaging OTP secret keysManaging OTP secret keysTo help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability.secret keysmanagementOTP secret keysHOTP secret keysTOTP secret keysYou can use this capability to complete the following tasks: View your OTP secret keys. Configure your OTP secret keys.Reset your OTP secret keys.Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/otp/otp.html. Perform one or more of the following actions: View your current OTP secret key. When you log in, you see one or both of the following in clear text and as quick response (QR) code: HOTP secret keyTOTP secret keyConfigure your secret key in your OTP generator: Use the clear text to manually enter either the HOTP secret key or the TOTP secret key into your OTP provider.Scan the QR code. When you scan the QR code, the OTP generator: Analyzes the QR code.Acquires the following information from the QR code: Secret key.Account with which the secret key is associated.Type of OTP with which the secret key is associated.Enter a secret key into your OTP generator.Reset your OTP secret key by clicking reset.User self-administration tasksAdministrators can configure context-based access to enable users to perform certain self-management tasks.

Managing OTP secret keys

To help manage your mobile data, such as your HOTP secret keys and TOTP secret keys, you can use the REST services capability.

About this task

You can use this capability to complete the following tasks:

View your OTP secret keys.

Configure your OTP secret keys.

Reset your OTP secret keys.

Procedure

Log in to https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/otp/otp.html.

Perform one or more of the following actions:

View your current OTP secret key. When you log in, you see one or both of the following in clear text and as quick response (QR) code:

HOTP secret key

TOTP secret key

Configure your secret key in your OTP generator:

Use the clear text to manually enter either the HOTP secret key or the TOTP secret key into your OTP provider.

Scan the QR code. When you scan the QR code, the OTP generator:

Analyzes the QR code.

Acquires the following information from the QR code:

Secret key.

Account with which the secret key is associated.

Type of OTP with which the secret key is associated.

Enter a secret key into your OTP generator.

Reset your OTP secret key by clicking reset.

Parent topic: User self-administration tasks

Configuring knowledge questionsConfiguring knowledge questionsConfiguring knowledge questionsUse the Knowledge Questions management page to manage the knowledge questions that the Knowledge Questions authentication mechanism will present as a step-up authentication measure.knowledge questions configuringknowledge questionsrest servicesknowledge question configuration The user can complete the following self-care management operations that are related to their knowledge questions: CreateUpdateDelete Specify and log in to the following URL: https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/questions/user_questions.htmlPerform one of the following tasks:Create knowledge questionsSelect a pre-configured knowledge question, or write your own question.Specify the answer to each question. Click Set User Questions.Update knowledge questionsChoose the necessary questions to update and specify the answers to the updated questions. Click Set User Questions.Delete knowledge questions Click Remove All Questions to delete you current knowledge questions.User self-administration tasksAdministrators can configure context-based access to enable users to perform certain self-management tasks.

Configuring knowledge questions

Use the Knowledge Questions management page to manage the knowledge questions that the Knowledge Questions authentication mechanism will present as a step-up authentication measure.

About this task

The user can complete the following self-care management operations that are related to their knowledge questions:

Create

Update

Delete

Procedure

Specify and log in to the following URL: https://<WebSEAL host>:<port>/<junction name>/sps/mga/user/mgmt/html/questions/user_questions.html

Perform one of the following tasks:

Create knowledge questions

Select a pre-configured knowledge question, or write your own question.

Specify the answer to each question.

Click Set User Questions.

Update knowledge questions

Choose the necessary questions to update and specify the answers to the updated questions.

Click Set User Questions.

Delete knowledge questions

Click Remove All Questions to delete you current knowledge questions.

Parent topic: User self-administration tasks

SCIM account managementSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. The SCIM interface can be used as a consolidated API for accessing user data from various data sources.User self-administration tasksAdministrators can configure context-based access to enable users to perform certain self-management tasks.User Self-Care with the SCIM APISecurity Access Manager SCIM support provides an API that can consolidate the management of user data from various sources. User Self-Care operationsSecurity Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval.

SCIM account management

Security Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. The SCIM interface can be used as a consolidated API for accessing user data from various data sources.

User Self-Care with the SCIM API
Security Access Manager SCIM support provides an API that can consolidate the management of user data from various sources.

User Self-Care operations
Security Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval.

Parent topic: User self-administration tasks

User Self-Care with the SCIM APISecurity Access Manager SCIM support provides an API that can consolidate the management of user data from various sources. Supported data sources include:User registrySecurity Access Manager user profileMobile Multi Factor Authentication (MMFA) dataUser knowledge questionsSCIM support provided by the Security Access Manager is based on the SCIM 2.0 standard. The SCIM 2.0 standard comprises of the SCIM Core Schema defined in RFC 7643 and the SCIM Protocol defined in RFC 7644.The SCIM application is provided on all Advanced Access Control interfaces under the path /scim. For example:https://<runtime_listening_address>:<port>/scim https://<runtime_listening_address>:<port>/scim/Schemas https://<runtime_listening_address>:<port>/scim/UsersSCIM account managementSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. The SCIM interface can be used as a consolidated API for accessing user data from various data sources.SetupThe SCIM application can be accessed internally via the Advanced Access Control endpoints or securely exposed externally using the Web Reverse Proxy with some additional setup.EndpointsSecurity Access Manager supports these SCIM endpoints.User profile schema LDAP attribute mappingSecurity Access Manager provides pre-defined mapping of SCIM attributes to commonly available LDAP attributes.Resource schemasSecurity Access Manager supports the following resource schemas from RFC 7643.LimitationsThe Security Access Manager SCIM application has some limitations.

User Self-Care with the SCIM API

Security Access Manager SCIM support provides an API that can consolidate the management of user data from various sources.

Supported data sources include:

User registry

Security Access Manager user profile

Mobile Multi Factor Authentication (MMFA) data

User knowledge questions

SCIM support provided by the Security Access Manager is based on the SCIM 2.0 standard. The SCIM 2.0 standard comprises of the SCIM Core Schema defined in RFC 7643 and the SCIM Protocol defined in RFC 7644.

The SCIM application is provided on all Advanced Access Control interfaces under the path /scim. For example:

https://<runtime_listening_address>:<port>/scim
https://<runtime_listening_address>:<port>/scim/Schemas
https://<runtime_listening_address>:<port>/scim/Users

Setup
The SCIM application can be accessed internally via the Advanced Access Control endpoints or securely exposed externally using the Web Reverse Proxy with some additional setup.

Endpoints
Security Access Manager supports these SCIM endpoints.

User profile schema LDAP attribute mapping
Security Access Manager provides pre-defined mapping of SCIM attributes to commonly available LDAP attributes.

Resource schemas
Security Access Manager supports the following resource schemas from RFC 7643.

Limitations
The Security Access Manager SCIM application has some limitations.

Parent topic: SCIM account management

SetupThe SCIM application can be accessed internally via the Advanced Access Control endpoints or securely exposed externally using the Web Reverse Proxy with some additional setup.Access to the SCIM application is controlled by the Advanced Access Control user registry. Administration tasks can be performed by users in the Administration Group that is specified on the SCIM Configuration page. By default, the account easuser is present in the default Administration Group. Only use the administration accounts internally or as service accounts for other points of contact (such as the Web Reverse Proxy) to authenticate to the SCIM application.Authenticating as a Security Access Manager user to the SCIM Application The SCIM application supports authentication as Security Access Manager users via the Web Reverse Proxy. To set up the Web Reverse Proxy as a point of contact for the SCIM application, create a junction to the Advanced Access Control listening interface with the following settings: Identity parametersHTTP header identity information:IV-USERIV-GROUPSIV-CREDSAuthenticationThe junction authenticates by using the credentials for a service account that is part of the Administration Group. Depending on the configuration of the Advanced Access Control Runtime, this can be basic authentication or mutual SSL authentication. The SCIM application can interpret the IV-USER/IV-GROUPS/IV-CREDS headers and determine which Security Access Manager user is authenticated. Specifically, the SCIM application determines the user based on the AZN_CRED_PRINCIPAL_NAME attribute. Using this information, the SCIM application resolves the /Users/Me endpoint to the current user and grants the following access: Read/write access to only the user’s own profileNo access to other user profiles or listing of all users As the user is determined by the SCIM application based on the value of AZN_CRED_PRINCIPAL_NAME, this value must be a normalized and globally unique value for any entity that can authenticate in your Security Access Manager environment. This includes users in local or federated user registries, users from federated single sign-on, and users from EAI applications.Authenticating as SCIM users to the Web Reverse Proxy It is possible to use the SCIM users as basic users to authenticate to the Web Reverse Proxy. This is useful in scenarios where you do not want to create all of your SCIM users within the Security Access Manager registry. SCIM users can authenticate if the Security Access Manager Runtime is configured with basic user support. For further information, see Configuring the runtime to authenticate basic usersBasic users are users in the registry that are not imported in to Security Access Manager. Edit the ldap.conf file so that basic users can authenticate in Security Access Manager.. Ensure that the LDAP server and suffix containing the SCIM users is configured and the principal attribute (basic-user-principal-attribute) is set to the LDAP attribute that the SCIM userName attribute is mapped to. By default, the SCIM userName attribute is mapped to the LDAP attribute uid.URL Filtering Resource responses include URLs that will not be filtered or rewritten by the Web Reverse Proxy by default. To rewrite URLs within SCIM JSON responses, make the following changes to the Web Reverse Proxy configuration file: [filter-content-types] type = application/scim+json [script-filtering] script-filter = yes rewrite-absolute-with-absolute = yesUser Self-Care with the SCIM APISecurity Access Manager SCIM support provides an API that can consolidate the management of user data from various sources.

Setup

The SCIM application can be accessed internally via the Advanced Access Control endpoints or securely exposed externally using the Web Reverse Proxy with some additional setup.

Access to the SCIM application is controlled by the Advanced Access Control user registry. Administration tasks can be performed by users in the Administration Group that is specified on the SCIM Configuration page. By default, the account easuser is present in the default Administration Group.

Only use the administration accounts internally or as service accounts for other points of contact (such as the Web Reverse Proxy) to authenticate to the SCIM application.

Authenticating as a Security Access Manager user to the SCIM Application

The SCIM application supports authentication as Security Access Manager users via the Web Reverse Proxy. To set up the Web Reverse Proxy as a point of contact for the SCIM application, create a junction to the Advanced Access Control listening interface with the following settings:

Identity parameters

HTTP header identity information:

IV-USER

IV-GROUPS

IV-CREDS

Authentication

The junction authenticates by using the credentials for a service account that is part of the Administration Group.

Depending on the configuration of the Advanced Access Control Runtime, this can be basic authentication or mutual SSL authentication.

The SCIM application can interpret the IV-USER/IV-GROUPS/IV-CREDS headers and determine which Security Access Manager user is authenticated. Specifically, the SCIM application determines the user based on the AZN_CRED_PRINCIPAL_NAME attribute. Using this information, the SCIM application resolves the /Users/Me endpoint to the current user and grants the following access:

Read/write access to only the user’s own profile

No access to other user profiles or listing of all users

Note: As the user is determined by the SCIM application based on the value of AZN_CRED_PRINCIPAL_NAME, this value must be a normalized and globally unique value for any entity that can authenticate in your Security Access Manager environment. This includes users in local or federated user registries, users from federated single sign-on, and users from EAI applications.

Authenticating as SCIM users to the Web Reverse Proxy

It is possible to use the SCIM users as basic users to authenticate to the Web Reverse Proxy. This is useful in scenarios where you do not want to create all of your SCIM users within the Security Access Manager registry.

SCIM users can authenticate if the Security Access Manager Runtime is configured with basic user support. For further information, see Configuring the runtime to authenticate basic users.

Ensure that the LDAP server and suffix containing the SCIM users is configured and the principal attribute (basic-user-principal-attribute) is set to the LDAP attribute that the SCIM userName attribute is mapped to. By default, the SCIM userName attribute is mapped to the LDAP attribute uid.

URL Filtering

Resource responses include URLs that will not be filtered or rewritten by the Web Reverse Proxy by default. To rewrite URLs within SCIM JSON responses, make the following changes to the Web Reverse Proxy configuration file:

[filter-content-types]
type = application/scim+json
[script-filtering]
script-filter = yes
rewrite-absolute-with-absolute = yes

Parent topic: User Self-Care with the SCIM API

EndpointsSecurity Access Manager supports these SCIM endpoints.Supported SCIM endpointsURLMethodDescription/SchemasGETReturns a list of all schemas./Schemas/{id}GETReturns a particular schema./ServiceProviderConfigGETReturns the SCIM service provider configuration./ResourceTypesGETReturns a list of resource types that are serviceable by this SCIM service provider./ResourceTypes/{id}GETReturns a particular resource type./UsersGETReturns a list of all users./UsersPOSTCreates a new user./Users/{id} or /MeGETReturns a particular user./Users/{id} or /MePUTUpdates an existing user./Users/{id} or /MePATCHPatches an existing user./Users/{id} or /MeDELETEDeletes an existing user.The URL /Me is an alias for /Users/{id} where {id} is the ID of the currently authenticated user.For a list of standard SCIM endpoints that are not supported by the application, see Unsupported endpoints.Detailed web services API documentation can be downloaded from the File Downloads page of the appliance LMI. The Security Access Manager SCIM documentation can be found in the following path:/access_control/doc/ISAM-Access-Control-scim-rest-api.zipUser Self-Care with the SCIM APISecurity Access Manager SCIM support provides an API that can consolidate the management of user data from various sources.

Endpoints

Security Access Manager supports these SCIM endpoints.

Table 222. Supported SCIM endpoints

URL | Method | Description
/Schemas | GET | Returns a list of all schemas.
/Schemas/{id} | GET | Returns a particular schema.
/ServiceProviderConfig | GET | Returns the SCIM service provider configuration.
/ResourceTypes | GET | Returns a list of resource types that are serviceable by this SCIM service provider.
/ResourceTypes/{id} | GET | Returns a particular resource type.
/Users | GET | Returns a list of all users.
/Users | POST | Creates a new user.
/Users/{id} or /Me | GET | Returns a particular user.
/Users/{id} or /Me | PUT | Updates an existing user.
/Users/{id} or /Me | PATCH | Patches an existing user.
/Users/{id} or /Me | DELETE | Deletes an existing user.

Note: The URL /Me is an alias for /Users/{id} where {id} is the ID of the currently authenticated user.

For a list of standard SCIM endpoints that are not supported by the application, see Unsupported endpoints.

Detailed web services API documentation can be downloaded from the File Downloads page of the appliance LMI. The Security Access Manager SCIM documentation can be found in the following path:

/access_control/doc/ISAM-Access-Control-scim-rest-api.zip

Parent topic: User Self-Care with the SCIM API

User profile schema LDAP attribute mappingSecurity Access Manager provides pre-defined mapping of SCIM attributes to commonly available LDAP attributes.This default mapping can be customized on the User Profile tab of the SCIM Configuration page. See User profileThe user profile configuration contains the settings that are required to manage the user data that is stored in the user registry..SCIM attributes that are not mapped to an LDAP attribute are not shown when the user profile schema is queried.The following table shows the default user schema attribute mapping.User schema attribute mappingSCIM attributeLDAP attributeaddresses[0].type == homeaddresses[0].formattedhomePostalAddressaddresses[1].type == workaddresses[1].formattedpostalAddressaddresses[1].streetAddressstreetaddresses[1].postalCodepostalCodeaddresses[1].localityladdresses[1].regionstdisplayNamedisplayNameemails[0].type == workemails[0].primary == trueemails[0].valuemailidBase64URLEncoded version of uidname.familyNamesnname.givenNamegivenNamepassworduserPasswordphoneNumbers[0].type == workphoneNumbers[0].primary == truephoneNumbers[0].valuetelephoneNumberphoneNumbers[1].type == homephoneNumbers[1].valuehomePhonephoneNumbers[2].type == mobilephoneNumbers[2].valuemobilephoneNumbers[3].type == pagerphoneNumbers[3].valuepagerpreferredLanguagepreferredLanguagetitletitleuserNamecn, uidThe multi-valued SCIM attributes (addresses, emails, and phone numbers) are not order-dependent and are shown here with array indices for illustrative purposes only.id is generated by the server based on the userName attribute when an account is created. If you are connecting the SCIM application to a user registry that is already populated with users, the id field is a Base64URLEncoded version of the uid field.The following table shows the enterprise extension attribute mapping.Enterprise extension attribute mappingSCIM attributeLDAP attributedepartmentdepartmentNumberemployeeNumberemployeeNumbermanager.valuemanagerorganizationoThe following attributes are not mapped by default:User schemaactive entitlements externalId groups ims[] locale name.formatted name.middleName name.honorificPrefix name.honorificSuffix nickName photos profileUrl roles timezone userType x509CertificatesEnterprise user schemacostCenter divisionHandling of multi-valued LDAP attributes If an attribute in the SCIM schema is mapped to a multi-valued LDAP attribute, only the first of the multiple values that are provided by the LDAP server is returned.Handling of multi-valued SCIM attributes Some SCIM attributes, such as addresses, emails, and phone numbers contain multiple complex values. For these attributes, the returned value is an array where each array element is a sub attribute with a different type string. The type strings are mapped to fixed strings and as such the entire sub attribute is always returned, regardless of whether other attributes such as value or primary are present. Consider the following LDAP entry and corresponding SCIM JSON representation of an example user. LDAP representationdn: cn=bjensen,dc=scim-users o: Universal Studios givenName: Barbara sn: Jensen street: 100 Universal City Plaza userPassword:: cGFzc3dvcmQ= departmentNumber: Tour Operations displayName: Bab Jensen mail: bjensen@example.com uid: bjensen objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson postalAddress:: MTAwIFVuaXZlcnNhbCBDaXR5IFBsYXphDQpIb2xseXdvb2QsIENBIDkxNjA4IF VTQQ== postalCode: 91608 title: Tour Guide cn: bjensen employeeNumber: 701984 l: Hollywood st: CA homePostalAddress:: NDU2IEhvbGx5d29vZCBCbHZkCkhvbGx5d29vZCwgQ0EgOTE2MDggVVNB telephoneNumber: 555-555-5555 mobile: 555-555-4444 homePhone: 555-555-3333 pager: 555-555-2222 preferredLanguage: en-US manager: cn=jsmithSCIM JSON representation{ "addresses": [ { "formatted": "100 Universal City Plaza\r\nHollywood, CA 91608 USA", "locality": "Hollywood", "postalCode": "91608", "region": "CA", "streetAddress": "100 Universal City Plaza", "type": "work" }, { "formatted": "456 Hollywood Blvd\nHollywood, CA 91608 USA", "type": "home" } ], "displayName": "Bab Jensen", "emails": [ { "primary": true, "type": "work", "value": "bjensen@example.com" } ], "id": "YmplbnNlbg", "meta": { "location": "https://isam-demo.ibm.com/scim/Users/YmplbnNlbg", "resourceType": "User" }, "name": { "familyName": "Jensen", "givenName": "Barbara" }, "phoneNumbers": [ { "primary": true, "type": "work", "value": "555-555-5555" }, { "primary": false, "type": "home", "value": "555-555-3333" }, { "primary": false, "type": "mobile", "value": "555-555-4444" }, { "primary": false, "type": "pager", "value": "555-555-2222" } ], "preferredLanguage": "en-US", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "title": "Tour Guide", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": "Tour Operations", "employeeNumber": "701984", "manager": { "value": "cn=jsmith" }, "organization": "Universal Studios" }, "userName": "bjensen" }User Self-Care with the SCIM APISecurity Access Manager SCIM support provides an API that can consolidate the management of user data from various sources.

User profile schema LDAP attribute mapping

Security Access Manager provides pre-defined mapping of SCIM attributes to commonly available LDAP attributes.

This default mapping can be customized on the User Profile tab of the SCIM Configuration page. See User profile.

SCIM attributes that are not mapped to an LDAP attribute are not shown when the user profile schema is queried.

The following table shows the default user schema attribute mapping.

Table 223. User schema attribute mapping

SCIM attribute | LDAP attribute
addresses[0].type == home |
addresses[0].formatted | homePostalAddress
addresses[1].type == work |
addresses[1].formatted | postalAddress
addresses[1].streetAddress | street
addresses[1].postalCode | postalCode
addresses[1].locality | l
addresses[1].region | st
displayName | displayName
emails[0].type == work |
emails[0].primary == true |
emails[0].value | mail
id | Base64URLEncoded version of uid
name.familyName | sn
name.givenName | givenName
password | userPassword
phoneNumbers[0].type == work |
phoneNumbers[0].primary == true |
phoneNumbers[0].value | telephoneNumber
phoneNumbers[1].type == home |
phoneNumbers[1].value | homePhone
phoneNumbers[2].type == mobile |
phoneNumbers[2].value | mobile
phoneNumbers[3].type == pager |
phoneNumbers[3].value | pager
preferredLanguage | preferredLanguage
title | title
userName | cn, uid

Note:

The multi-valued SCIM attributes (addresses, emails, and phone numbers) are not order-dependent and are shown here with array indices for illustrative purposes only.

id is generated by the server based on the userName attribute when an account is created. If you are connecting the SCIM application to a user registry that is already populated with users, the id field is a Base64URLEncoded version of the uid field.

The following table shows the enterprise extension attribute mapping.

Table 224. Enterprise extension attribute mapping

SCIM attribute | LDAP attribute
department | departmentNumber
employeeNumber | employeeNumber
manager.value | manager
organization | o

The following attributes are not mapped by default:

User schema

active
entitlements
externalId
groups
ims[]
locale
name.formatted
name.middleName
name.honorificPrefix
name.honorificSuffix
nickName
photos
profileUrl
roles
timezone
userType
x509Certificates

Enterprise user schema

costCenter
division

Handling of multi-valued LDAP attributes

If an attribute in the SCIM schema is mapped to a multi-valued LDAP attribute, only the first of the multiple values that are provided by the LDAP server is returned.

Handling of multi-valued SCIM attributes

Some SCIM attributes, such as addresses, emails, and phone numbers contain multiple complex values. For these attributes, the returned value is an array where each array element is a sub attribute with a different type string. The type strings are mapped to fixed strings and as such the entire sub attribute is always returned, regardless of whether other attributes such as value or primary are present.

Consider the following LDAP entry and corresponding SCIM JSON representation of an example user.

LDAP representation

dn: cn=bjensen,dc=scim-users
o: Universal Studios
givenName: Barbara
sn: Jensen
street: 100 Universal City Plaza
userPassword:: cGFzc3dvcmQ=
departmentNumber: Tour Operations
displayName: Bab Jensen
mail: bjensen@example.com
uid: bjensen
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
postalAddress:: MTAwIFVuaXZlcnNhbCBDaXR5IFBsYXphDQpIb2xseXdvb2QsIENBIDkxNjA4IF
 VTQQ==
postalCode: 91608
title: Tour Guide
cn: bjensen
employeeNumber: 701984
l: Hollywood
st: CA
homePostalAddress:: NDU2IEhvbGx5d29vZCBCbHZkCkhvbGx5d29vZCwgQ0EgOTE2MDggVVNB
telephoneNumber: 555-555-5555
mobile: 555-555-4444
homePhone: 555-555-3333
pager: 555-555-2222
preferredLanguage: en-US
manager: cn=jsmith

SCIM JSON representation

{
  "addresses": [
    {
      "formatted": "100 Universal City Plaza\r\nHollywood, CA 91608 USA",
      "locality": "Hollywood",
      "postalCode": "91608",
      "region": "CA",
      "streetAddress": "100 Universal City Plaza",
      "type": "work"
    },
    {
 "formatted": "456 Hollywood Blvd\nHollywood, CA 91608 USA",
      "type": "home"
    }
  ],
  "displayName": "Bab Jensen",
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "bjensen@example.com"
    }
  ],
  "id": "YmplbnNlbg",
  "meta": {
    "location": "https://isam-demo.ibm.com/scim/Users/YmplbnNlbg",
    "resourceType": "User"
  },
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "phoneNumbers": [
    {
      "primary": true,
      "type": "work",
      "value": "555-555-5555"
    },
    {
      "primary": false,
      "type": "home",
      "value": "555-555-3333"
    },
    {
      "primary": false,
      "type": "mobile",
      "value": "555-555-4444"
    },
    {
      "primary": false,
      "type": "pager",
      "value": "555-555-2222"
    }
  ],
  "preferredLanguage": "en-US",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "title": "Tour Guide",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Tour Operations",
    "employeeNumber": "701984",
    "manager": {
      "value": "cn=jsmith"
    },
    "organization": "Universal Studios"
  },
  "userName": "bjensen"
}

Parent topic: User Self-Care with the SCIM API

Resource schemasSecurity Access Manager supports the following resource schemas from RFC 7643.“User” Resource Schema urn:ietf:params:scim:schemas:core:2.0:User Enterprise User Schema Extension urn:ietf:params:scim:schemas:extension:enterprise:2.0:UserSecurity Access Manager also provides the following extensions to the “User” Resource Schema:MMFA Authenticators urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Authenticator MMFA Transactions urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Transaction MMFA EAS urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:EAS User Knowledge Questions urn:ietf:params:scim:schemas:extension:isam:1.0:UserKnowledgeQuestions ISAM User urn:ietf:params:scim:schemas:extension:isam:1.0:User Data in the Security Access Manager schemas can be managed for users that do not necessarily exist in the LDAP user registry. For instance, scenarios where a user logged in with their identity from another provider.Consider a user logging in with an identity from social.ibm.com. Their AZN_CRED_PRINCIPAL_NAME is https://social.ibm.com/myTestUser. The SCIM interface can be used to manage data on the Security Access Manager extension schemas if the correct SCIM user ID is provided.The SCIM user ID expected by the SCIM application is the Base64 and URL encoded version of the username, which in this case is “aHR0cHM6Ly9zb2NpYWwuaWJtLmNvbS9teVRlc3RVc2Vy”. Even though the user does not exist in the LDAP user registry and has no attributes in the defined User Resource Schema, it is still possible to manage their data in the Security Access Manager specific schemas.In the following example, a user is not in the user registry but still has MMFA Authenticators data.GET https://scim.ibm.com/scim/Users/aHR0cHM6Ly9zb2NpYWwuaWJtLmNvbS9teVRlc3RVc2Vy { "meta": { "location": "https://scim.ibm.com/scim/Users/aHR0cHM6Ly9zb2NpYWwuaWJtLmNvbS9teVRlc3RVc2Vy ", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Authenticator" ], "id": "dGVzdHVzZXI1NTU", "urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Authenticator": { "userPresenceMethods": [], "authenticators": [ { "osVersion": "2.b", "id": "uuid1c689142-be74-4262-9e33-8813b532599b", "oauthGrant": "uuid9d06ddc1-0157-16e7-87b9-e593c7ab6dfc", "deviceName": "IBM Phone", "enabled": true } ], "fingerprintMethods": [ { "id": "uuid4e6e91fe-0956-41be-a933-c01ed4466c05", "keyHandle": " SVNBTSBTQ0lNIEVhc3RlciBFZ2cu", "authenticator": "uuid1c689142-be74-4262-9e33-8813b532599b", "enabled": true, "algorithm": "SHA512withRSA" } ] } }User Self-Care with the SCIM APISecurity Access Manager SCIM support provides an API that can consolidate the management of user data from various sources.

Resource schemas

Security Access Manager supports the following resource schemas from RFC 7643.

“User” Resource Schema
urn:ietf:params:scim:schemas:core:2.0:User

Enterprise User Schema Extension
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Security Access Manager also provides the following extensions to the “User” Resource Schema:

MMFA Authenticators
urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Authenticator

MMFA Transactions
urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Transaction

MMFA EAS
urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:EAS

User Knowledge Questions
urn:ietf:params:scim:schemas:extension:isam:1.0:UserKnowledgeQuestions

ISAM User
urn:ietf:params:scim:schemas:extension:isam:1.0:User

Data in the Security Access Manager schemas can be managed for users that do not necessarily exist in the LDAP user registry. For instance, scenarios where a user logged in with their identity from another provider.

Consider a user logging in with an identity from social.ibm.com. Their AZN_CRED_PRINCIPAL_NAME is https://social.ibm.com/myTestUser. The SCIM interface can be used to manage data on the Security Access Manager extension schemas if the correct SCIM user ID is provided.

The SCIM user ID expected by the SCIM application is the Base64 and URL encoded version of the username, which in this case is “aHR0cHM6Ly9zb2NpYWwuaWJtLmNvbS9teVRlc3RVc2Vy”. Even though the user does not exist in the LDAP user registry and has no attributes in the defined User Resource Schema, it is still possible to manage their data in the Security Access Manager specific schemas.

In the following example, a user is not in the user registry but still has MMFA Authenticators data.

GET https://scim.ibm.com/scim/Users/aHR0cHM6Ly9zb2NpYWwuaWJtLmNvbS9teVRlc3RVc2Vy

{
  "meta": {
    "location": "https://scim.ibm.com/scim/Users/aHR0cHM6Ly9zb2NpYWwuaWJtLmNvbS9teVRlc3RVc2Vy ",
    "resourceType": "User"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Authenticator"
  ],
  "id": "dGVzdHVzZXI1NTU",
  "urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Authenticator": {
    "userPresenceMethods": [],
    "authenticators": [
      {
        "osVersion": "2.b",
        "id": "uuid1c689142-be74-4262-9e33-8813b532599b",
        "oauthGrant": "uuid9d06ddc1-0157-16e7-87b9-e593c7ab6dfc",
        "deviceName": "IBM Phone",
        "enabled": true
      }
    ],
    "fingerprintMethods": [
      {
        "id": "uuid4e6e91fe-0956-41be-a933-c01ed4466c05",
        "keyHandle": " SVNBTSBTQ0lNIEVhc3RlciBFZ2cu",
        "authenticator": "uuid1c689142-be74-4262-9e33-8813b532599b",
        "enabled": true,
        "algorithm": "SHA512withRSA"
      }
    ]
  }
}

Parent topic: User Self-Care with the SCIM API

LimitationsThe Security Access Manager SCIM application has some limitations.General HTTP ETags supportSecurity Access Manager does not provide support for HTTP ETags. Resource responses will not contain the ETag HTTP header, and response bodies will not contain the meta attributes: created, lastModified, and version.Attribute case sensitivityAttribute names are always handled with case sensitivity. This rule also applies to attributes that are named in JSON bodies and in URL query string parameters.Resource filtering and sortingSecurity Access Manager supports basic filtering operations using attribute operators. Filtering with logical operators or grouping operators is not supported. Sorting operations are not supported.Unsupported endpoints Security Access Manager does not provide the following endpoints defined is RFC 7643 and RFC 7644. Group resource schema and /Groups endpointSecurity Access Manager does not provide the “Group” resource schema from RFC 7643. It is not possible to use the /Groups endpoint to manage group resources. The User resource schema still includes the complete groups attribute.Bulk operations and the /Bulk endpointSecurity Access Manager does not support the bulk resource update endpoint.Search operations using the ./search endpointSecurity Access Manager does not support query resources using HTTP POST functionality. This includes the endpoint /.search and any endpoint of the format <prefix>/.search.User Self-Care with the SCIM APISecurity Access Manager SCIM support provides an API that can consolidate the management of user data from various sources.

Limitations

The Security Access Manager SCIM application has some limitations.

General

HTTP ETags support

Security Access Manager does not provide support for HTTP ETags. Resource responses will not contain the ETag HTTP header, and response bodies will not contain the meta attributes: created, lastModified, and version.

Attribute case sensitivity

Attribute names are always handled with case sensitivity. This rule also applies to attributes that are named in JSON bodies and in URL query string parameters.

Resource filtering and sorting

Security Access Manager supports basic filtering operations using attribute operators. Filtering with logical operators or grouping operators is not supported. Sorting operations are not supported.

Unsupported endpoints

Security Access Manager does not provide the following endpoints defined is RFC 7643 and RFC 7644.

"Group" resource schema and /Groups endpoint

Security Access Manager does not provide the “Group” resource schema from RFC 7643. It is not possible to use the /Groups endpoint to manage group resources.

Note: The "User" resource schema still includes the complete groups attribute.

Bulk operations and the /Bulk endpoint

Security Access Manager does not support the bulk resource update endpoint.

Search operations using the ./search endpoint

Security Access Manager does not support query resources using HTTP POST functionality. This includes the endpoint /.search and any endpoint of the format <prefix>/.search.

Parent topic: User Self-Care with the SCIM API

User Self-Care operationsSecurity Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval.You can modify and customize these pre-defined authentication policies to suit your particular needs, for example:The OTP mechanism can be removed from the Create User flow so that an OTP is no longer required when a user creates an account.The secondary attribute that is used in the Password Reset and Lost ID flows can be changed from surname to another attribute.The required attributes that are collected when an account is created during the Create User flow can be modified.You can also use these pre-defined authentication policies as building blocks to compose new User Self-Care scenarios. The logic and server-side processing is almost entirely performed in JavaScript mapping rules. These existing rules can be extended or transformed. New rules can also be written to implement different features.The pre-defined authentication policies all use HTML templates, which can be customized to match your application. Each policy includes a list of the HTML templates that are used.Form pre-population and handling of responses is performed by JavaScript mapping rules. Each policy includes a list of the JavaScript mapping rules that are used.Prerequisites Before you use any of the authentication policies to achieve SCIM account management, you must complete the following prerequisite setup: Create a server connection to the SCIM application endpoint.Log in to the local management interface. Click Secure Access Control.Under Global Settings, click Server Connections.Click New and select Web Service.Specify the details of your SCIM application endpoint.If you are using the SCIM application included with Security Access Manager, the URL is <runtime_endpoint>/scim. The user name and password can be that of any user who is part of the Administration Group that is defined in the SCIM Configuration.Save and deploy the changes.Configure the authentication policies to make use of the SCIM application endpoint.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanisms.Select the SCIM Endpoint Configuration mechanism and click Edit.On the Properties tab in the Modify Authentication Mechanism window, select the Server Connection entry and click Edit.In the Modify Property window, select from the list the server connection that was created in the previous step and click OK.Save and deploy the changes.SCIM account managementSecurity Access Manager provides support for selected parts of the Cross-domain Identity Management (SCIM) protocol. The SCIM interface can be used as a consolidated API for accessing user data from various data sources.Account Create policyThe Account Create policy enables users to create new accounts for themselves. This policy uses the ReCAPTCHA mechanism to verify that the requests originate from a human and an Email OTP to ensure that a valid email address is being used.Password Reset policyThe Password Reset authentication policy enables users to reset their passwords. This policy uses the ReCAPTCHA mechanism to verify that the request originates from a human. It also uses the Email OTP mechanism and a secondary attribute to ensure that only the account owner can reset the password.Lost ID policyThe Lost ID authentication policy enables users to retrieve their lost or forgotten user IDs. This policy uses the reCAPTCHA mechanism to verify that the request originates from a human and a secondary attribute to ensure that only the account owner can start the process. The lost ID is emailed to the user. None of the user's account information is displayed in the browser.

User Self-Care operations

Security Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval.

You can modify and customize these pre-defined authentication policies to suit your particular needs, for example:

The OTP mechanism can be removed from the Create User flow so that an OTP is no longer required when a user creates an account.

The secondary attribute that is used in the Password Reset and Lost ID flows can be changed from surname to another attribute.

The required attributes that are collected when an account is created during the Create User flow can be modified.

You can also use these pre-defined authentication policies as building blocks to compose new User Self-Care scenarios. The logic and server-side processing is almost entirely performed in JavaScript mapping rules. These existing rules can be extended or transformed. New rules can also be written to implement different features.

The pre-defined authentication policies all use HTML templates, which can be customized to match your application. Each policy includes a list of the HTML templates that are used.

Form pre-population and handling of responses is performed by JavaScript mapping rules. Each policy includes a list of the JavaScript mapping rules that are used.

Prerequisites

Before you use any of the authentication policies to achieve SCIM account management, you must complete the following prerequisite setup:

Create a server connection to the SCIM application endpoint.

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Server Connections.

Click New and select Web Service.

Specify the details of your SCIM application endpoint.

If you are using the SCIM application included with Security Access Manager, the URL is <runtime_endpoint>/scim. The user name and password can be that of any user who is part of the Administration Group that is defined in the SCIM Configuration.

Save and deploy the changes.

Configure the authentication policies to make use of the SCIM application endpoint.

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanisms.

Select the SCIM Endpoint Configuration mechanism and click Edit.

On the Properties tab in the Modify Authentication Mechanism window, select the Server Connection entry and click Edit.

In the Modify Property window, select from the list the server connection that was created in the previous step and click OK.

Save and deploy the changes.

Account Create policy
The Account Create policy enables users to create new accounts for themselves. This policy uses the ReCAPTCHA mechanism to verify that the requests originate from a human and an Email OTP to ensure that a valid email address is being used.

Password Reset policy
The Password Reset authentication policy enables users to reset their passwords. This policy uses the ReCAPTCHA mechanism to verify that the request originates from a human. It also uses the Email OTP mechanism and a secondary attribute to ensure that only the account owner can reset the password.

Lost ID policy
The Lost ID authentication policy enables users to retrieve their lost or forgotten user IDs. This policy uses the reCAPTCHA mechanism to verify that the request originates from a human and a secondary attribute to ensure that only the account owner can start the process. The lost ID is emailed to the user. None of the user's account information is displayed in the browser.

Parent topic: SCIM account management

Account Create policyThe Account Create policy enables users to create new accounts for themselves. This policy uses the ReCAPTCHA mechanism to verify that the requests originate from a human and an Email OTP to ensure that a valid email address is being used.Account Create setup Ensure that the Prerequisites steps are completed.Configure the reCAPTCHA Verification mechanism. See Configuring the reCAPTCHA Verification authentication mechanismThe reCAPTCHA Verification authentication mechanism provides anti-robot protection..Configure the Email OTP delivery mechanism to be used in the Account Create authentication policy.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanism.Click Email One-time Password.Click Edit.Select the Properties tab and configure the connection to the SMTP server.HTML templates authsvc/usc/account-create/collectEmail.htmlauthsvc/authentictor/macotp/login.htmlauthsvc/usc/account-create/collectProfile.htmlauthsvc/usc/account-create/success.htmlJavaScript Mapping Rules USC_CreateAccount_CollectEmailUSC_CreateAccount_CollectProfileUSC_CreateAccount_SuccessCreating a new account workflow The Account Create authentication policy enables users to create new accounts with the following workflow. The new accounts that are created under this workflow are of the type basic users. The user accesses https://<WebSEAL host>:<port>/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:uscAccountCreateOn this screen, the user is prompted to enter an email address and CAPTCHA.The template page that is presented is authsvc/usc/account-create/collectEmail.htmlThe JavaScript that pre-populates the form and validates responses is USC_CreateAccount_CollectEmailOn the next screen, the user is prompted to enter an OTP.The OTP is delivered via Email.The template page that is presented is authsvc/authentictor/macotp/login.htmlOn the next screen, the user is presented with the enrollment form.The template page that is presented is authsvc/usc/account-create/collectProfile.htmlThe JavaScript that pre-populates the form and validates responses is USC_AccountCreate_CollectProfileThe JavaScript that pre-populates the template and ends the policy is USC_CreateAccount_SuccessOn the next screen, the account success page is presented.The template page that is presented is authsvc/usc/account-create/success.htmlUser Self-Care operationsSecurity Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval.

Account Create policy

The Account Create policy enables users to create new accounts for themselves. This policy uses the ReCAPTCHA mechanism to verify that the requests originate from a human and an Email OTP to ensure that a valid email address is being used.

Account Create setup

Ensure that the Prerequisites steps are completed.

Configure the reCAPTCHA Verification mechanism. See Configuring the reCAPTCHA Verification authentication mechanism.

Configure the Email OTP delivery mechanism to be used in the Account Create authentication policy.

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanism.

Click Email One-time Password.

Click Edit.

Select the Properties tab and configure the connection to the SMTP server.

HTML templates

authsvc/usc/account-create/collectEmail.html

authsvc/authentictor/macotp/login.html

authsvc/usc/account-create/collectProfile.html

authsvc/usc/account-create/success.html

JavaScript Mapping Rules

USC_CreateAccount_CollectEmail

USC_CreateAccount_CollectProfile

USC_CreateAccount_Success

Creating a new account workflow

The Account Create authentication policy enables users to create new accounts with the following workflow.

Note: The new accounts that are created under this workflow are of the type "basic users".

The user accesses https://<WebSEAL host>:<port>/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:uscAccountCreate

On this screen, the user is prompted to enter an email address and CAPTCHA.

The template page that is presented is authsvc/usc/account-create/collectEmail.html

The JavaScript that pre-populates the form and validates responses is USC_CreateAccount_CollectEmail

On the next screen, the user is prompted to enter an OTP.

The OTP is delivered via Email.

The template page that is presented is authsvc/authentictor/macotp/login.html

On the next screen, the user is presented with the enrollment form.

The template page that is presented is authsvc/usc/account-create/collectProfile.html

The JavaScript that pre-populates the form and validates responses is USC_AccountCreate_CollectProfile

The JavaScript that pre-populates the template and ends the policy is USC_CreateAccount_Success

On the next screen, the account success page is presented.

The template page that is presented is authsvc/usc/account-create/success.html

Parent topic: User Self-Care operations

Password Reset policyThe Password Reset authentication policy enables users to reset their passwords. This policy uses the ReCAPTCHA mechanism to verify that the request originates from a human. It also uses the Email OTP mechanism and a secondary attribute to ensure that only the account owner can reset the password.Password Reset Setup Ensure that the Prerequisites steps are completed.Configure the reCAPTCHA Verification mechanism. See Configuring the reCAPTCHA Verification authentication mechanismThe reCAPTCHA Verification authentication mechanism provides anti-robot protection..Configure the Email OTP delivery mechanism to be used in the Password Reset authentication policy.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanism.Click Email One-time Password.Click Edit.Select the Properties tab and configure the connection to the SMTP server.HTML templates authsvc/usc/password-reset/collectEmail.htmlauthsvc/authentictor/macotp/login.htmlauthsvc/usc/password-reset/collectPassword.htmlauthsvc/usc/password-reset/success.htmlJavaScript Mapping Rules USC_PasswordReset_CollectEmailUSC_PasswordReset_CollectPasswordUSC_PasswordReset_SuccessPassword reset workflow The Password Reset authentication policy enables users to reset their lost or forgotten passwords with the following workflow. The user accesses https://<WebSEAL host>:<port>/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:uscPasswordResetOn this screen, the user is prompted to enter an email address, surname, and CAPTCHA.The template page that is presented is authsvc/usc/password-reset/collectEmail.htmlThe JavaScript that pre-populates the form and validates responses is USC_PasswordReset_CollectEmailIf the email address and surname do not match any existing profile, a generic error is returned.On the next screen, the user is prompted to enter an OTP.The OTP is delivered through an email.The template page that is presented is authsvc/authentictor/macotp/login.htmlOn the next screen, the user is presented with the password reset form.The template page that is presented is authsvc/usc/password-reset/collectPassword.htmlThe JavaScript that pre-populates the form and validates responses is USC_PasswordReset_CollectPasswordOn the next screen, the account success page is presented.The template page that is presented is authsvc/usc/password-reset/success.htmlThe JavaScript that pre-populates the page is USC_PasswordReset_SuccessUser Self-Care operationsSecurity Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval.

Password Reset policy

The Password Reset authentication policy enables users to reset their passwords. This policy uses the ReCAPTCHA mechanism to verify that the request originates from a human. It also uses the Email OTP mechanism and a secondary attribute to ensure that only the account owner can reset the password.

Password Reset Setup

Ensure that the Prerequisites steps are completed.

Configure the reCAPTCHA Verification mechanism. See Configuring the reCAPTCHA Verification authentication mechanism.

Configure the Email OTP delivery mechanism to be used in the Password Reset authentication policy.

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanism.

Click Email One-time Password.

Click Edit.

Select the Properties tab and configure the connection to the SMTP server.

HTML templates

authsvc/usc/password-reset/collectEmail.html

authsvc/authentictor/macotp/login.html

authsvc/usc/password-reset/collectPassword.html

authsvc/usc/password-reset/success.html

JavaScript Mapping Rules

USC_PasswordReset_CollectEmail

USC_PasswordReset_CollectPassword

USC_PasswordReset_Success

Password reset workflow

The Password Reset authentication policy enables users to reset their lost or forgotten passwords with the following workflow.

The user accesses https://<WebSEAL host>:<port>/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:uscPasswordReset

On this screen, the user is prompted to enter an email address, surname, and CAPTCHA.

The template page that is presented is authsvc/usc/password-reset/collectEmail.html

The JavaScript that pre-populates the form and validates responses is USC_PasswordReset_CollectEmail

If the email address and surname do not match any existing profile, a generic error is returned.

On the next screen, the user is prompted to enter an OTP.

The OTP is delivered through an email.

The template page that is presented is authsvc/authentictor/macotp/login.html

On the next screen, the user is presented with the password reset form.

The template page that is presented is authsvc/usc/password-reset/collectPassword.html

The JavaScript that pre-populates the form and validates responses is USC_PasswordReset_CollectPassword

On the next screen, the account success page is presented.

The template page that is presented is authsvc/usc/password-reset/success.html

The JavaScript that pre-populates the page is USC_PasswordReset_Success

Parent topic: User Self-Care operations

Lost ID policyThe Lost ID authentication policy enables users to retrieve their lost or forgotten user IDs. This policy uses the reCAPTCHA mechanism to verify that the request originates from a human and a secondary attribute to ensure that only the account owner can start the process. The lost ID is emailed to the user. None of the user's account information is displayed in the browser.Lost ID Setup Ensure that the Prerequisites steps are completed.Configure the reCAPTCHA Verification mechanism. See Configuring the reCAPTCHA Verification authentication mechanismThe reCAPTCHA Verification authentication mechanism provides anti-robot protection..Create an SMTP Server ConnectionLog in to the local management interface. Click Secure Access Control.Under Global Settings, click Server Connections.Click the New Server Connection icon.Select SMTP.Complete the connection details of your SMTP server.Click Save.Deploy these changes before you continue to the next step.Configure the Session Attribute Response mechanism to be used in the Lost ID authentication policy.Log in to the local management interface. Click Secure Access Control.Under Policy, click Authentication.Click Mechanism.Select USC Lost ID - Send ID.Click Edit.In the dialog window, select the Properties tab.Select the Server Connection property and click Edit.In the dialog window, select the SMTP server connection that is created in the previous step.Click Save.Deploy the changes.HTML templates authsvc/usc/lost-id/collectEmail.htmlauthsvc/authenticator/email_message/error.htmlauthsvc/usc/lost-id/success.htmlEmail templates authsvc/usc/lost-id/email.xmlJavaScript Mapping Rules USC_LostId_CollectEmailUSC_LostId_SuccessLost ID workflow Upon completion of this flow, the user receives an email message that contains the lost or forgotten user ID. The user accesses https://<WebSEAL host>:<port>/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:uscLostIdOn this screen, the user is prompted to enter an email address, surname, and complete the CAPTCHA.The template page that is presented is authsvc/usc/lost-id/collectEmail.htmlThe JavaScript that pre-populates the form and validates responses is USC_LostId_CollectEmailIf the email address and surname do not match any existing profile, a generic error is returned.An email that contains the lost or forgotten user ID is sent to the user.On the next screen, the operation success page is presented.The template page that is presented is authsvc/usc/lost-id/success.htmlThe JavaScript that pre-populates the page is USC_LostId_SuccessUser Self-Care operationsSecurity Access Manager provides some pre-defined authentication policies that can be used to enable certain User Self-Care operations, such as account creation, password reset, and lost ID retrieval.

Lost ID policy

The Lost ID authentication policy enables users to retrieve their lost or forgotten user IDs. This policy uses the reCAPTCHA mechanism to verify that the request originates from a human and a secondary attribute to ensure that only the account owner can start the process. The lost ID is emailed to the user. None of the user's account information is displayed in the browser.

Lost ID Setup

Ensure that the Prerequisites steps are completed.

Configure the reCAPTCHA Verification mechanism. See Configuring the reCAPTCHA Verification authentication mechanism.

Create an SMTP Server Connection

Log in to the local management interface.

Click Secure Access Control.

Under Global Settings, click Server Connections.

Click the New Server Connection icon.

Select SMTP.

Complete the connection details of your SMTP server.

Click Save.

Deploy these changes before you continue to the next step.

Configure the Session Attribute Response mechanism to be used in the Lost ID authentication policy.

Log in to the local management interface.

Click Secure Access Control.

Under Policy, click Authentication.

Click Mechanism.

Select USC Lost ID - Send ID.

Click Edit.

In the dialog window, select the Properties tab.

Select the Server Connection property and click Edit.

In the dialog window, select the SMTP server connection that is created in the previous step.

Click Save.

Deploy the changes.

HTML templates

authsvc/usc/lost-id/collectEmail.html

authsvc/authenticator/email_message/error.html

authsvc/usc/lost-id/success.html

Email templates

authsvc/usc/lost-id/email.xml

JavaScript Mapping Rules

USC_LostId_CollectEmail

USC_LostId_Success

Lost ID workflow

Upon completion of this flow, the user receives an email message that contains the lost or forgotten user ID.

The user accesses https://<WebSEAL host>:<port>/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:uscLostId

On this screen, the user is prompted to enter an email address, surname, and complete the CAPTCHA.

The template page that is presented is authsvc/usc/lost-id/collectEmail.html

The JavaScript that pre-populates the form and validates responses is USC_LostId_CollectEmail

If the email address and surname do not match any existing profile, a generic error is returned.

An email that contains the lost or forgotten user ID is sent to the user.

On the next screen, the operation success page is presented.

The template page that is presented is authsvc/usc/lost-id/success.html

The JavaScript that pre-populates the page is USC_LostId_Success

Parent topic: User Self-Care operations

Access ControlAccess ControlAccess ControlAccess Control links include Policies, Resources, Attributes, and Obligations.Use the Access Control links to complete the following tasks:PoliciesManaging access control policiesAn access control policy is a set of conditions that define whether a user is permitted or denied access to a protected resource.Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy.Managing access control policy setsA policy set is a group of policies that are used together to protect a resource.ResourcesManaging access control policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced.AttributesManaging attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.ObligationsManaging obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Access Control

Access Control links include Policies, Resources, Attributes, and Obligations.

Use the Access Control links to complete the following tasks:

Policies

Managing access control policies

Creating an access control policy

Managing access control policy sets

Resources

Managing access control policy attachments

Attributes

Managing attributes

Obligations

Managing obligations

Parent topic: Advanced Access Control administration

Attributes AttributesAttributesAttributes links include Risk Profile, Attributes, and Matchers.Use the Attributes links to complete the following tasks:Risk ProfileManaging risk profilesA risk profile is a collection of attributes with assigned weights. You can view a list of profiles or to add, delete, or clone profiles or set a profile to active. Only one risk profile can be active at a time.AttributesManaging attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.MatchersModifying attribute matchersAttribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Attributes

Attributes links include Risk Profile, Attributes, and Matchers.

Use the Attributes links to complete the following tasks:

Risk Profile

Managing risk profiles

Attributes

Managing attributes

Matchers

Modifying attribute matchers

Parent topic: Advanced Access Control administration

AuthenticationAuthenticationAuthenticationAuthentication links include Policies, Mechanisms, and Advanced.Use the Authentication links to complete the following tasks:PoliciesManaging authentication policiesAuthentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user. You can view, add, modify, and delete authentication policies.MechanismsConfiguring a MAC one-time password providerA one-time password is valid for one session or login. The MAC password is generated by Security Access Manager and can be delivered to the user through Short Message Service (SMS) or e-mail. Configuring an HOTP one-time password providerThe TOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring a TOTP one-time password providerThe HOTP one-password mechanism relies on a public algorithm to generate the one-time password.Configuring an RSA one-time password providerA one-time password is valid for one session or login. To use RSA as a mechanism, you must own RSA Authentication Manager. The server and the client generate the passwords with the same algorithm.Configuring a one-time password delivery methodPasswords can be delivered to the user through Short Message Service (SMS) or email. Configuring username and password authenticationThe user name and password authentication mechanism authenticates users with their user name and password credentials that are stored in the Access Manager user repository. Configuring an HTTP redirect authentication mechanism The HTTP redirect authentication mechanism integrates an external application that you provide to use for authenticating users.Configuring consent to device registrationConsent-based device registration is the process of registering the device fingerprint only after the user consents to the device registration.Configuring an End-User License Agreement authentication mechanism The End-User License Agreement authentication mechanism prompts the user to accept an End-User License Agreement (EULA) during an authentication flow.Configuring a Knowledge Questions authentication mechanismThe Knowledge Questions authentication mechanism is an extra step-up authentication measure that uses knowledge questions and answers to authenticate the user.AdvancedManaging mapping rulesThe mapping rules are JavaScript code that run during the authentication flow. Use the rules to customize the authentication service and the one-time password generation, delivery, and verification.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Authentication

Authentication links include Policies, Mechanisms, and Advanced.

Use the Authentication links to complete the following tasks:

Policies

Managing authentication policies

Mechanisms

Configuring a MAC one-time password provider

Configuring an HOTP one-time password provider

Configuring a TOTP one-time password provider

Configuring an RSA one-time password provider

Configuring a one-time password delivery method

Configuring username and password authentication

Configuring an HTTP redirect authentication mechanism

Configuring consent to device registration

Configuring an End-User License Agreement authentication mechanism

Configuring a Knowledge Questions authentication mechanism

Advanced

Managing mapping rules

Parent topic: Advanced Access Control administration

Obligations ObligationsObligationsObligations links include Policies, Resources, Attributes and Obligations.Use the Obligations links to complete the following tasks:PoliciesManaging access control policiesAn access control policy is a set of conditions that define whether a user is permitted or denied access to a protected resource.Creating an access control policyUse the Policy Editor on the appliance local management interface to create and configure an access control policy.Managing access control policy setsA policy set is a group of policies that are used together to protect a resource.ResourcesManaging access control policy attachmentsAttach policies or API protection definitions to resources so that the policies and definitions can be enforced.AttributesManaging attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.ObligationsManaging obligationsObligations are used for authoring policies. You can view, add, modify, and delete obligations.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Obligations

Obligations links include Policies, Resources, Attributes and Obligations.

Use the Obligations links to complete the following tasks:

Policies

Managing access control policies

Creating an access control policy

Managing access control policy sets

Resources

Managing access control policy attachments

Attributes

Managing attributes

Obligations

Managing obligations

Parent topic: Advanced Access Control administration

Risk Profile Risk Profile Risk Profile Risk Profile links include Attributes and Matchers.Use the Risk Profile links to complete the following tasks:AttributesManaging attributesAttributes represent unique information about a request. You use attributes in policy rules and risk profiles to match the attributes in a request. You can view, add, modify, and delete attributes.MatchersModifying attribute matchersAttribute matchers match incoming attributes to attributes in a device fingerprint. The predefined matchers are set to default values. You can modify those values to customize the risk calculations for your policies.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Risk Profile

Risk Profile links include Attributes and Matchers.

Use the Risk Profile links to complete the following tasks:

Attributes

Managing attributes

Matchers

Modifying attribute matchers

Parent topic: Advanced Access Control administration

Managing server connectionsManaging server connectionsManaging server connectionsTo use data outside of the appliance, you can define server connections.Select the appropriate Module link for information about managing server connections:Advanced Access Control ModuleManaging server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data.Federation ModuleManaging server connectionsTo access data from outside of your appliance, you must define a server connection.Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Managing server connections

To use data outside of the appliance, you can define server connections.

Select the appropriate Module link for information about managing server connections:

Advanced Access Control Module

Managing server connections

Federation Module

Managing server connections

Parent topic: Advanced Access Control administration

Managing federations and partnersManaging federations and partnersManaging federations and partnersUse the local management interface to manage federation and partner properties.Use the appropriate link for instructions:Managing federationsUse the local management interface to manage federations. Managing federation partnersYou can use the console to manage partners. Advanced Access Control administrationThe Advanced Access Control topics explain how to administer context-based access. These topics are specific to the Advanced Access Control activation level.

Managing federations and partners

Use the local management interface to manage federation and partner properties.

Use the appropriate link for instructions:

Managing federations

Managing federation partners

Parent topic: Advanced Access Control administration

Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.This section provides the administration procedures for the Federation features.AdministeringIBM Security Access Manager provides information about administering supported activation levels.Managing federationsUse the local management interface to manage federations. Managing federation partner templatesUse the Federation Partner Templates management page to see the current version of the templates on the appliance and update the templates to a new version.Managing attribute sourcesUse the Attribute Source management page to add, edit, or delete your identity attribute sources.Managing trust chainsUse the Security Token Service page to achieve token conversions through the WS-Trust interface.Managing point of contact profilesUse the local management interface to work with your point of contact profiles.Managing server connectionsTo access data from outside of your appliance, you must define a server connection.Managing LTPA keysYou can create, import, export, and delete LTPA key files that are used by the LTPA token conversion module.Managing JavaScript mapping rulesCreate, edit, or delete JavaScript mapping rules.

Federation administration

Use the topics in this hierarchy to administer the Federation features, if you have activated this module.

This section provides the administration procedures for the Federation features.

Managing federations
Use the local management interface to manage federations.

Managing federation partner templates
Use the Federation Partner Templates management page to see the current version of the templates on the appliance and update the templates to a new version.

Managing attribute sources
Use the Attribute Source management page to add, edit, or delete your identity attribute sources.

Managing trust chains
Use the Security Token Service page to achieve token conversions through the WS-Trust interface.

Managing point of contact profiles
Use the local management interface to work with your point of contact profiles.

Managing server connections
To access data from outside of your appliance, you must define a server connection.

Managing LTPA keys
You can create, import, export, and delete LTPA key files that are used by the LTPA token conversion module.

Managing JavaScript mapping rules
Create, edit, or delete JavaScript mapping rules.

Parent topic: Administering

Managing federationsManaging federationsManaging federationsUse the local management interface to manage federations. federationsmanagingEnsure that you activate the Federation Module to use the federation features.For information about establishing a federation, including creating a federation and adding a partner to an existing federation, see SAML 2.0 federations The Federation Module supports SAML 2.0 federations. and OpenID Connect federationsThe Federation Module supports OpenID Connect federations. in the Federation configuration topic collection.Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.Creating and modifying a federationUse the Federations management page to view, create, and modify the details about an existing federation or to modify an existing federation.Exporting a federationWhen you want to join a federation hosted by another business partner, you must supply your federation configuration properties. You can export your SAML 2.0 federation properties to a file to share them with your partner.Deleting a federationUse the Federations management page to delete the federation that you no longer need. Managing federation partnersUse the Federations management page to create, modify, delete, enable, or disable your federation partners.

Managing federations

Use the local management interface to manage federations.

Ensure that you activate the Federation Module to use the federation features.

For information about establishing a federation, including creating a federation and adding a partner to an existing federation, see SAML 2.0 federations and OpenID Connect federations in the Federation configuration topic collection.

Creating and modifying a federation
Use the Federations management page to view, create, and modify the details about an existing federation or to modify an existing federation.

Exporting a federation
When you want to join a federation hosted by another business partner, you must supply your federation configuration properties. You can export your SAML 2.0 federation properties to a file to share them with your partner.

Deleting a federation
Use the Federations management page to delete the federation that you no longer need.

Managing federation partners
Use the Federations management page to create, modify, delete, enable, or disable your federation partners.

Parent topic: Federation administration

Creating and modifying a federation Creating and modifying a federation Creating and modifying a federation Use the Federations management page to view, create, and modify the details about an existing federation or to modify an existing federation.federationspropertiesfederationsmodifyingpropertiesfederationDepending on the protocol you want to use, review the following topics:SAML 2.0 federations The Federation Module supports SAML 2.0 federations.OpenID Connect federationsThe Federation Module supports OpenID Connect federations.Log in to the local management interface.Select Secure FederationManageFederations.All configured federations are displayed.You can create a federation or modify any existing federations.To create a federation, click Add and then follow the wizard. The wizard pages differ depending on the federation protocol you select.If you encounter a session timeout while creating a federation and then log back in, you might not be able to see the federation you created. You must click Refresh to get the latest data from the appliance.To modify a federation, select the federation and then click Edit. Follow the wizard and modify the settings on each page as needed.Managing federationsUse the local management interface to manage federations.

Creating and modifying a federation

Use the Federations management page to view, create, and modify the details about an existing federation or to modify an existing federation.

Before you begin

Depending on the protocol you want to use, review the following topics:

SAML 2.0 federations

OpenID Connect federations

Procedure

Log in to the local management interface.

Select Secure Federation > Manage > Federations. All configured federations are displayed.

You can create a federation or modify any existing federations.

To create a federation, click Add and then follow the wizard. The wizard pages differ depending on the federation protocol you select.

Note: If you encounter a session timeout while creating a federation and then log back in, you might not be able to see the federation you created. You must click Refresh to get the latest data from the appliance.

To modify a federation, select the federation and then click Edit. Follow the wizard and modify the settings on each page as needed.

Parent topic: Managing federations

Exporting a federation Exporting a federation Exporting a federation When you want to join a federation hosted by another business partner, you must supply your federation configuration properties. You can export your SAML 2.0 federation properties to a file to share them with your partner.federationsexporting propertiespropertiesexporting federationLog in to the local management interface.Click Secure FederationManageFederations.Select a federation from the table.Click Export. The browser shows a message window that prompts you to save the file containing the exported data. Exporting a federation is applicable to SAML 2.0 federation only.Click OK.The browser download window prompts for a location to save the file. Select a directory and metadata file.Metadata file names have the following syntax: federationname_metadata.xmlFor example, for a federation named federation1, and a company named ABC, the metadata file would be named: federation1_ABC_metadata.xmlPlace the metadata file in an easily accessible location. You must provide the file to your partner, when your partner wants to import configuration information for the federation.Click Save.Managing federationsUse the local management interface to manage federations.

Exporting a federation

When you want to join a federation hosted by another business partner, you must supply your federation configuration properties. You can export your SAML 2.0 federation properties to a file to share them with your partner.

Procedure

Log in to the local management interface.

Click Secure Federation > Manage > Federations.

Select a federation from the table.

Click Export. The browser shows a message window that prompts you to save the file containing the exported data.

Note: Exporting a federation is applicable to SAML 2.0 federation only.

Click OK. The browser download window prompts for a location to save the file.

Select a directory and metadata file. Metadata file names have the following syntax:

federationname_metadata.xml

For example, for a federation named federation1, and a company named ABC, the metadata file would be named:

federation1_ABC_metadata.xml

Note: Place the metadata file in an easily accessible location. You must provide the file to your partner, when your partner wants to import configuration information for the federation.

Click Save.

Parent topic: Managing federations

Deleting a federationDeleting a federationDeleting a federationUse the Federations management page to delete the federation that you no longer need. federationsdeletingWhen you delete a federation, all of its partners are also deleted.Log in to the local management interface. Click Secure FederationManageFederations.The Federation Management panel shows a list of configured federations.Select a federation.Click Delete to delete the federation.A message box prompts you to confirm the deletion of the federation.Click YES on the message box. The federation is deleted.Managing federationsUse the local management interface to manage federations.

Deleting a federation

Use the Federations management page to delete the federation that you no longer need.

About this task

Attention: When you delete a federation, all of its partners are also deleted.

Procedure

Log in to the local management interface.

Click Secure Federation > Manage > Federations. The Federation Management panel shows a list of configured federations.

Select a federation.

Click Delete to delete the federation. A message box prompts you to confirm the deletion of the federation.

Click YES on the message box. The federation is deleted.

Parent topic: Managing federations

Managing federation partnersUse the Federations management page to create, modify, delete, enable, or disable your federation partners.federation partnerLog in to the local management interface.Select Secure FederationManageFederations.All existing federations are displayed in the list.Select the federation to manage partners for.Click Partners.All existing partners for this federation are displayed.You can create, modify, delete, enable, or disable your federation partners.To create a partner, click Add and follow the wizard. The wizard pages differ depending on the federation protocols. When there are multiple partner templates to choose from, they are displayed in a table. You can use the filter to locate a particular partner template and then select it from the table.For a SAML 2.0 federation, the partner create wizard is a two-stage process. The first stage is to upload the metadata file for the partner. After this stage is complete, a new partner that matches the details in the metadata file is created. The second stage is to complete the wizard to update some properties in the new partner. Even if the wizard is canceled after the metadata upload, the new partner is still created. The upload operation creates the partner. For information about adding a partner to an existing federation, see Creating a SAML 2.0 partnerCreate a federation partner by gathering the necessary configuration information for input into the local management interface on the appliance..If you encounter a session timeout while creating a partner and then log back in, you might not be able to see the partner you created. You must click Refresh to get the latest data from the appliance.To modify a partner, select the partner and click Edit. Follow the wizard and modify the settings on each page as needed.To delete a partner, select the partner and click Delete. Confirm the deletion by clicking Yes.To enable or disable a partner, select the partner and click Enable or Disable.To refresh the partners page, click Refresh.Managing federationsUse the local management interface to manage federations.

Managing federation partners

Use the Federations management page to create, modify, delete, enable, or disable your federation partners.

Procedure

Log in to the local management interface.

Select Secure Federation > Manage > Federations. All existing federations are displayed in the list.

Select the federation to manage partners for.

Click Partners. All existing partners for this federation are displayed.

You can create, modify, delete, enable, or disable your federation partners.

To create a partner, click Add and follow the wizard. The wizard pages differ depending on the federation protocols. When there are multiple partner templates to choose from, they are displayed in a table. You can use the filter to locate a particular partner template and then select it from the table.

Remember: For a SAML 2.0 federation, the partner create wizard is a two-stage process. The first stage is to upload the metadata file for the partner. After this stage is complete, a new partner that matches the details in the metadata file is created. The second stage is to complete the wizard to update some properties in the new partner. Even if the wizard is canceled after the metadata upload, the new partner is still created. The upload operation creates the partner. For information about adding a partner to an existing federation, see Creating a SAML 2.0 partner.

Note: If you encounter a session timeout while creating a partner and then log back in, you might not be able to see the partner you created. You must click Refresh to get the latest data from the appliance.

To modify a partner, select the partner and click Edit. Follow the wizard and modify the settings on each page as needed.

To delete a partner, select the partner and click Delete. Confirm the deletion by clicking Yes.

To enable or disable a partner, select the partner and click Enable or Disable.

To refresh the partners page, click Refresh.

Parent topic: Managing federations

Managing federation partner templatesUse the Federation Partner Templates management page to see the current version of the templates on the appliance and update the templates to a new version.Federation partner templates are designed to simplify the configuration of federations within the appliance. These templates contain partner definitions that can assist with the establishment of federations to well-known partners. When you activate the Federation Module, the federation partner templates package that was included in the firmware is automatically applied. You can also update the existing templates to a new version by importing a new templates package into your appliance. In a cluster environment, after you import a new templates package into the primary node appliance, the update is automatically applied to non-primary nodes. Templates package update is possible from the primary node only.Log in to the local management interface.Select Secure FederationGlobal SettingsPartner Templates.The version number of the current federation partner templates and the installation date are displayed.To update the templates, click Import.Click Browse and then select the new templates package file.Click Import to upload the selected templates package file to the appliance.Deploy the changes.Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.

Managing federation partner templates

Use the Federation Partner Templates management page to see the current version of the templates on the appliance and update the templates to a new version.

About this task

Federation partner templates are designed to simplify the configuration of federations within the appliance. These templates contain partner definitions that can assist with the establishment of federations to well-known partners.

When you activate the Federation Module, the federation partner templates package that was included in the firmware is automatically applied. You can also update the existing templates to a new version by importing a new templates package into your appliance.

In a cluster environment, after you import a new templates package into the primary node appliance, the update is automatically applied to non-primary nodes.

Note: Templates package update is possible from the primary node only.

Procedure

Log in to the local management interface.

Select Secure Federation > Global Settings > Partner Templates. The version number of the current federation partner templates and the installation date are displayed.

To update the templates, click Import.

Click Browse and then select the new templates package file.

Click Import to upload the selected templates package file to the appliance.

Deploy the changes.

Parent topic: Federation administration

Managing attribute sourcesUse the Attribute Source management page to add, edit, or delete your identity attribute sources.attribute sourceYou can manage the following types of attribute sources with this UI: FixedThis type contains the Attribute Name and Value fields. Both fields are in free text format. You can specify any text in these fields to suit your needs.CredentialThis type contains the Attribute Name and Credential Attribute fields. For the Credential Attribute field, you can select from a list of commonly used credential attribute values or add a value that is not already in the list.The Credential attribute source does not work for the Relying Party in an OpenID Connect federation. Because at the time of mapping, the user does not have credential to retrieve attribute from.LDAPThis type contains the attribute name and the details of the LDAP server to look up the attribute in. The following fields are available:Attribute NameName of the attribute on the appliance. This field is required.LDAP AttributeName of the attribute on the LDAP server. This field is required.Server ConnectionThe ID of the existing LDAP server connection that contains information about the location and the credential that is required to connect to the LDAP server. This field is required.To add an LDAP attribute source, there must be at least one LDAP server connection present. For details about how to create an LDAP server connection, see Managing server connectionsTo access data from outside of your appliance, you must define a server connection..ScopeThe scope of the search. Valid values are Subtree, One level, and Base. This field is optional.SelectorA comma-separated list of the attributes to be retrieved from the search result. When multiple attributes are required from the same search result, you can use the selector to include all the required attributes. For example, "cn,sn,mobile,email". This field is optional.Search FilterThe search filter to use for the search. You can use a variable macro that will be replaced during the run time before the search. The macro will be replaced with a value from the STSUU attributes. If the value is not found, it will not be replaced. The macro is indicated by curly brackets. For example, "(cn={AZN_CRED_PRINCIPAL_NAME})". This field is required.BaseDNThe base DN to run the search on. You can use a variable macro that will be replaced during the run time before the search. The macro will be replaced with a value from the STSUU attributes. If the value is not found, it will not be replaced. The macro is indicated by curly brackets. For example, "dc=iswga" or"dc={myBaseVariable}". This field is required.Log in to the local management interface.Click Secure FederationManageAttribute Source.You can create, modify, or delete attribute sources.Creating an attribute resourceClick Add and select the type of attribute source to create.Provide details for the attribute source.Click Add.Deploy the changes.Modifying an attribute sourceSelect the attribute source to modify.Click Edit.Edit the details of the attribute source as needed.Click Modify.Deploy the changes.Deleting an attribute sourceSelect the attribute source to delete.Click Delete.Click Delete to confirm the deletion.Deploy the changes.Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.

Managing attribute sources

Use the Attribute Source management page to add, edit, or delete your identity attribute sources.

About this task

You can manage the following types of attribute sources with this UI:

Fixed

This type contains the Attribute Name and Value fields. Both fields are in free text format. You can specify any text in these fields to suit your needs.

Credential

This type contains the Attribute Name and Credential Attribute fields. For the Credential Attribute field, you can select from a list of commonly used credential attribute values or add a value that is not already in the list.

Note: The Credential attribute source does not work for the Relying Party in an OpenID Connect federation. Because at the time of mapping, the user does not have credential to retrieve attribute from.

LDAP

This type contains the attribute name and the details of the LDAP server to look up the attribute in. The following fields are available:

Attribute Name

Name of the attribute on the appliance. This field is required.

LDAP Attribute

Name of the attribute on the LDAP server. This field is required.

Server Connection

The ID of the existing LDAP server connection that contains information about the location and the credential that is required to connect to the LDAP server. This field is required.

Note: To add an LDAP attribute source, there must be at least one LDAP server connection present. For details about how to create an LDAP server connection, see Managing server connections.

Scope

The scope of the search. Valid values are Subtree, One level, and Base. This field is optional.

Selector

A comma-separated list of the attributes to be retrieved from the search result. When multiple attributes are required from the same search result, you can use the selector to include all the required attributes. For example, "cn,sn,mobile,email". This field is optional.

Search Filter

The search filter to use for the search. You can use a variable macro that will be replaced during the run time before the search. The macro will be replaced with a value from the STSUU attributes. If the value is not found, it will not be replaced. The macro is indicated by curly brackets. For example, "(cn={AZN_CRED_PRINCIPAL_NAME})". This field is required.

BaseDN

The base DN to run the search on. You can use a variable macro that will be replaced during the run time before the search. The macro will be replaced with a value from the STSUU attributes. If the value is not found, it will not be replaced. The macro is indicated by curly brackets. For example, "dc=iswga" or"dc={myBaseVariable}". This field is required.

Procedure

Log in to the local management interface.

Click Secure Federation > Manage > Attribute Source.

You can create, modify, or delete attribute sources.

Creating an attribute resource

Click Add and select the type of attribute source to create.

Provide details for the attribute source.

Click Add.

Deploy the changes.

Modifying an attribute source

Select the attribute source to modify.

Click Edit.

Edit the details of the attribute source as needed.

Click Modify.

Deploy the changes.

Deleting an attribute source

Select the attribute source to delete.

Click Delete.

Click Delete to confirm the deletion.

Deploy the changes.

Parent topic: Federation administration

Managing trust chainsUse the Security Token Service page to achieve token conversions through the WS-Trust interface.module chaintrust chainFederation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.Managing module chainsA module chain defines a WS-Trust endpoint. It contains a reference to a template and the properties for all modules within that template.Managing templatesA template is an ordered list of modules and their modes.Managing modulesA module is a module class and set of initial parameters.

Managing trust chains

Use the Security Token Service page to achieve token conversions through the WS-Trust interface.

Managing module chains
A module chain defines a WS-Trust endpoint. It contains a reference to a template and the properties for all modules within that template.

Managing templates
A template is an ordered list of modules and their modes.

Managing modules
A module is a module class and set of initial parameters.

Parent topic: Federation administration

Managing module chainsA module chain defines a WS-Trust endpoint. It contains a reference to a template and the properties for all modules within that template.module chainchain mappingYou can define the following fields for a module chain: The following fields are available on the Overview tab: NameName of the module chain. This field is required.DescriptionDescription of the module chain. This field is required.TemplateThe template that is referenced by this module chain. The following fields are available on the Lookup tab: Request TypeThe type of request to associate with this chain. The request is one of the types that are supported by the WS-Trust specification.IssueIssue a new token, based on information that is obtained from the request.RenewRenew an expired token. ValidateValidate the specified security token and return the requested result.CancelCancels a previously issued token so that it is no longer used.Key ExchangeTransfer of a new key for use by the receiver of the request.OtherA custom request type.URIA Uniform Resource Indicator for each request type. This field is read-only except when you select Other as the request type. For the Other type, enter the URI for your custom request type.Lookup TypeXPathSelect this option to enable a text field that can be used to define a custom lookup rule. Use XML Path Language to define the rule.Traditional WS-Trust ElementsSpecifies that the trust service uses the values in the request for Applies To, Issuer, and Token Type as input to determine which trust service module chain to call.Select this option to show the data entry fields for Applies To, Issuer, and Token Type.You must provide a value for at least one of the following fields for the Traditional WS-Trust Elements:Issuer address Applies To address Token Type selected, where value is not NoneOr, if you do not specify one of the above options, then you must select the XPath option, plus a specified XPath.If you supply values for all of the parameters, including the XPath, then the Issuer, Applies To, and Token Type values take priority over XPath in the runtime.Applies ToDefines the scope of the token. AddressThe address of the service that is being requested. For example: http://sp.example.com:9080/TrustServer/SecurityTokenService You can use the asterisk (*) wildcard character at the end of a string. For example, token* matches all strings that start with token.You can also use regular expressions in the format of REGEXP:(regular_expression_here). For example, REGEXP:(.*/application.*) matches any string that contains /application. When you specify the scope for single sign-on protocols, this URI is sufficient information for identifying the issuer.Service NameA qualified name (QName) that includes a namespace URI and a local part for the Web service. A QName is a term that is defined in XML specifications. A QName consists of a namespace URI plus a local part. For example: http://sp.example.com:SecurityTokenService The Service Name field provides a colon (:) to separate the namespace URI from the local part. This field is typically not used for single sign-on protocols, but can be used for Web services security management.Port TypeWeb services operations are grouped by port type. Use this field when there are more than one Web services port types to specify. For example, a stock market data service might provide both a stock quoting service and a stock price history service. Use this field to specify the needed Web service. http://sp.example.com:RequestSecurityTokenPort The port type is also a QName. The Port Type field provides a colon (:) to separate the namespace URI from the local part. This field is typically not used for single sign-on protocols, but can be used for Web services security management.IssuerAddressThe URL for the company or enterprise that issued the token. For example: example.com You can use the asterisk (*) wildcard character at the end of a string. For example, token* matches all strings that start with token.You can also use regular expressions in the format of REGEXP:(regular_expression_here). For example, REGEXP:(.*/application.*) matches any string that contains /application. When you specify the scope for single sign-on protocols, this provider ID is sufficient information for identifying the issuer.Service NameA qualified name (QName) that includes a namespace URI and a local part for the Web service. A QName is a term that is defined in XML specifications. A QName consists of a namespace URI plus a local part. For example: http://idp.example.com:myWebService The Service Name field provides a colon (:) to separate the namespace URI from the local part. This field is typically not used for single sign-on protocols, but can be used for Web services security management.Port TypeWeb services operations are grouped by port type. Use this field when there is more than one Web service port type to specify. For example, a stock market data service might provide both a stock quoting service and a stock price history service. Use this field to specify the needed Web service. http://idp.example.com:getQuotePortType The port type is also a QName.The Port Type field provides a colon (:) to separate the namespace URI from the local part.This field is typically not used for single sign-on protocols, but can be used for Web services security management. Token TypeDefines the STS module type. Select a type to map a request message to an STS chain. Select a type other than None for it to be part of the runtime flow. URIA Uniform Resource Indicator for each token type. This field is read-only except when you select Other as the token type. For the Other type, enter the URI for your custom token type. The following fields are available on the Security tab. Validate RequestsSelect to require a signature on the SOAP Body element that contains the RequestSecurityToken messages. When you select this option, your Trust Service client must use their private key to sign the body of the SOAP messages in accordance with the Web Services Security SOAP Message Security 1.1 specification. Select the public key that was provided by the client to validate the signature on the message.Certificate DatabaseSpecify the database where the certificate is stored.Certificate LabelSpecify the name of the certificate to use for validation.Send Validation ConfirmationSend signature validation confirmation. When you select this option, the Trust Server includes a SignatureValidationConfirmation element in the Security header in accordance with the Web Services Security SOAP Message Security 1.1 specification.Sign ResponsesSelect to sign the Trust Server SOAP response messages. When you select this option, the Trust server uses the private key you select to sign the body of the SOAP response messages in accordance with the Web Services Security SOAP Message Security 1.1 specification. Provide the corresponding public key to your client so that they can validate the signature on the message.Certificate DatabaseSpecify the database where the certificate is stored.Certificate LabelSpecify the name of the certificate to use for validation.IncludeDetermine which elements to include in the digital signature for a Trust Server SOAP response message.Public KeySpecify whether to include the public key with your signature.Subject Key IdentifierSpecify whether to include the X.509 subject key identifier with your signature. Subject NameSpecify whether to include the subject name with your signature. Certificate DataSpecify whether to include the BASE64 encoded certificate data with your signature. Issuer DetailsSpecify whether to include the issuer name and the certificate serial number with your signature. The Properties tab contains the properties for all modules within the template. Properties for each module can be viewed and updated by selecting the module on the Template Contents list.Log in to the local management interface.Click Secure FederationManageSecurity Token Service.By default, the Security Token Service Module Chains tab is open. All existing module chains are listed.You can create, modify, or delete module chains.Creating a module chainClick Add.Provide details for the module chain on all tabs.Click Save.Deploy the changes.Modifying a module chainSelect the module chain to modify.Click Edit.Edit the details on various tabs as needed.Click Save.Deploy the changes.Deleting a module chainSelect the module chain to delete.Click Delete.Click Delete to confirm the deletion.Deploy the changes.Managing trust chainsUse the Security Token Service page to achieve token conversions through the WS-Trust interface.

Managing module chains

A module chain defines a WS-Trust endpoint. It contains a reference to a template and the properties for all modules within that template.

About this task

You can define the following fields for a module chain:

The following fields are available on the Overview tab:

Name

Name of the module chain. This field is required.

Description

Description of the module chain. This field is required.

Template

The template that is referenced by this module chain.

The following fields are available on the Lookup tab:

Request Type

The type of request to associate with this chain. The request is one of the types that are supported by the WS-Trust specification.

Issue

Issue a new token, based on information that is obtained from the request.

Renew

Renew an expired token.

Validate

Validate the specified security token and return the requested result.

Cancel

Cancels a previously issued token so that it is no longer used.

Key Exchange

Transfer of a new key for use by the receiver of the request.

Other

A custom request type.

URI

A Uniform Resource Indicator for each request type. This field is read-only except when you select Other as the request type. For the Other type, enter the URI for your custom request type.

Lookup Type

XPath

Select this option to enable a text field that can be used to define a custom lookup rule. Use XML Path Language to define the rule.

Traditional WS-Trust Elements

Specifies that the trust service uses the values in the request for Applies To, Issuer, and Token Type as input to determine which trust service module chain to call.

Select this option to show the data entry fields for Applies To, Issuer, and Token Type.

You must provide a value for at least one of the following fields for the Traditional WS-Trust Elements:

Issuer address

Applies To address

Token Type selected, where value is not None

Or, if you do not specify one of the above options, then you must select the XPath option, plus a specified XPath.

Note: If you supply values for all of the parameters, including the XPath, then the Issuer, Applies To, and Token Type values take priority over XPath in the runtime.

Applies To

Defines the scope of the token.

Address

The address of the service that is being requested. For example:

http://sp.example.com:9080/TrustServer/SecurityTokenService

You can use the asterisk (*) wildcard character at the end of a string. For example, token* matches all strings that start with token.

You can also use regular expressions in the format of REGEXP:(regular_expression_here). For example, REGEXP:(.*/application.*) matches any string that contains /application.

When you specify the scope for single sign-on protocols, this URI is sufficient information for identifying the issuer.

Service Name

A qualified name (QName) that includes a namespace URI and a local part for the Web service.

Note: A QName is a term that is defined in XML specifications. A QName consists of a namespace URI plus a local part.

For example:

http://sp.example.com:SecurityTokenService

Note: The Service Name field provides a colon (:) to separate the namespace URI from the local part.

This field is typically not used for single sign-on protocols, but can be used for Web services security management.

Port Type

Web services operations are grouped by port type. Use this field when there are more than one Web services port types to specify.

For example, a stock market data service might provide both a stock quoting service and a stock price history service. Use this field to specify the needed Web service.

http://sp.example.com:RequestSecurityTokenPort

The port type is also a QName.

Note: The Port Type field provides a colon (:) to separate the namespace URI from the local part.

This field is typically not used for single sign-on protocols, but can be used for Web services security management.

Issuer

Address

The URL for the company or enterprise that issued the token. For example:

example.com

You can use the asterisk (*) wildcard character at the end of a string. For example, token* matches all strings that start with token.

You can also use regular expressions in the format of REGEXP:(regular_expression_here). For example, REGEXP:(.*/application.*) matches any string that contains /application.

When you specify the scope for single sign-on protocols, this provider ID is sufficient information for identifying the issuer.

Service Name

A qualified name (QName) that includes a namespace URI and a local part for the Web service.

Note: A QName is a term that is defined in XML specifications. A QName consists of a namespace URI plus a local part.

For example:

http://idp.example.com:myWebService

Note: The Service Name field provides a colon (:) to separate the namespace URI from the local part.

This field is typically not used for single sign-on protocols, but can be used for Web services security management.

Port Type

Web services operations are grouped by port type. Use this field when there is more than one Web service port type to specify.

For example, a stock market data service might provide both a stock quoting service and a stock price history service. Use this field to specify the needed Web service.

http://idp.example.com:getQuotePortType

The port type is also a QName.

Note: The Port Type field provides a colon (:) to separate the namespace URI from the local part.

This field is typically not used for single sign-on protocols, but can be used for Web services security management.

Token Type

Defines the STS module type. Select a type to map a request message to an STS chain. Select a type other than None for it to be part of the runtime flow.

URI

A Uniform Resource Indicator for each token type. This field is read-only except when you select Other as the token type. For the Other type, enter the URI for your custom token type.

The following fields are available on the Security tab.

Validate Requests

Select to require a signature on the SOAP Body element that contains the RequestSecurityToken messages. When you select this option, your Trust Service client must use their private key to sign the body of the SOAP messages in accordance with the Web Services Security SOAP Message Security 1.1 specification.

Select the public key that was provided by the client to validate the signature on the message.

Certificate Database

Specify the database where the certificate is stored.

Certificate Label

Specify the name of the certificate to use for validation.

Send Validation Confirmation

Send signature validation confirmation. When you select this option, the Trust Server includes a SignatureValidationConfirmation element in the Security header in accordance with the Web Services Security SOAP Message Security 1.1 specification.

Sign Responses

Select to sign the Trust Server SOAP response messages. When you select this option, the Trust server uses the private key you select to sign the body of the SOAP response messages in accordance with the Web Services Security SOAP Message Security 1.1 specification.

Provide the corresponding public key to your client so that they can validate the signature on the message.

Certificate Database

Specify the database where the certificate is stored.

Certificate Label

Specify the name of the certificate to use for validation.

Include

Determine which elements to include in the digital signature for a Trust Server SOAP response message.

Public Key

Specify whether to include the public key with your signature.

Subject Key Identifier

Specify whether to include the X.509 subject key identifier with your signature.

Subject Name

Specify whether to include the subject name with your signature.

Certificate Data

Specify whether to include the BASE64 encoded certificate data with your signature.

Issuer Details

Specify whether to include the issuer name and the certificate serial number with your signature.

The Properties tab contains the properties for all modules within the template. Properties for each module can be viewed and updated by selecting the module on the Template Contents list.

Procedure

Log in to the local management interface.

Click Secure Federation > Manage > Security Token Service. By default, the Security Token Service Module Chains tab is open. All existing module chains are listed.

You can create, modify, or delete module chains.

Creating a module chain

Click Add.

Provide details for the module chain on all tabs.

Click Save.

Deploy the changes.

Modifying a module chain

Select the module chain to modify.

Click Edit.

Edit the details on various tabs as needed.

Click Save.

Deploy the changes.

Deleting a module chain

Select the module chain to delete.

Click Delete.

Click Delete to confirm the deletion.

Deploy the changes.

Parent topic: Managing trust chains

Managing templatesA template is an ordered list of modules and their modes.trust chainmodule chaintemplateLog in to the local management interface.Click Secure FederationManageSecurity Token Service.Click Templates.All existing templates are listed on the left pane.You can add, modify, or delete templates.Adding a templateClick Add on the left pane.Enter a name and description for the new template.Click OK. The new template is added to the template list on the left pane.Select the new template from the left pane.Click Add on the right pane.Select the module instance and mode to add to the template. Click OK.Repeat the previous three steps for each module instance to add to the template.Click Move Up or Move Down to adjust the order of the module instances if needed.Deploy the changes.Modifying a templateSelect the template to modify from the left pane.Use the controls in the right pane to make changes.Deploy the changes.Deleting a templateSelect the template to delete from the left pane.Click Delete on the left pane.Click Delete in the dialog box to confirm the operation.Deploy the changes.Managing trust chainsUse the Security Token Service page to achieve token conversions through the WS-Trust interface.

Managing templates

A template is an ordered list of modules and their modes.

Procedure

Log in to the local management interface.

Click Secure Federation > Manage > Security Token Service.

Click Templates. All existing templates are listed on the left pane.

You can add, modify, or delete templates.

Adding a template

Click Add on the left pane.

Enter a name and description for the new template.

Click OK. The new template is added to the template list on the left pane.

Select the new template from the left pane.

Click Add on the right pane.

Select the module instance and mode to add to the template.

Click OK.

Repeat the previous three steps for each module instance to add to the template.

Click Move Up or Move Down to adjust the order of the module instances if needed.

Deploy the changes.

Modifying a template

Select the template to modify from the left pane.

Use the controls in the right pane to make changes.

Deploy the changes.

Deleting a template

Select the template to delete from the left pane.

Click Delete on the left pane.

Click Delete in the dialog box to confirm the operation.

Deploy the changes.

Parent topic: Managing trust chains

Managing modulesA module is a module class and set of initial parameters.module instanceLog in to the local management interface.Click Secure FederationManageSecurity Token Service.Click Modules.All existing modules are displayed.You can view the modules.Select the module to view.Click View.Observe the module properties.Click Close. Managing trust chainsUse the Security Token Service page to achieve token conversions through the WS-Trust interface.

Managing modules

A module is a module class and set of initial parameters.

Procedure

Log in to the local management interface.

Click Secure Federation > Manage > Security Token Service.

Click Modules. All existing modules are displayed.

You can view the modules.

Select the module to view.

Click View.

Observe the module properties.

Click Close.

Parent topic: Managing trust chains

Managing point of contact profilesUse the local management interface to work with your point of contact profiles.You can perform the following point of contact profile tasks:Creating a point of contact profileCreate a point of contact server profile to capture the information needed for the runtime to communicate with the point of contact server.Updating or viewing a point of contact profileUpdate or view a point of contact server profile.Deleting a point of contact profileUse the local management interface to remove a point of contact profile.Setting a current point of contact profileSet a point of contact profile as the current one so that the federation runtime communicates with the point of contact server using the correct set of specifications.Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.Creating a point of contact profileCreate a point of contact server profile to capture the information needed for the runtime to communicate with the point of contact server.Updating or viewing a point of contact profileUpdate or view a point of contact server profile.Deleting a point of contact profileUse the local management interface to remove a point of contact profile.Setting a current point of contact profileSet a point of contact profile as the current one so that the federation runtime communicates with the point of contact server using the correct set of specifications.

Managing point of contact profiles

Use the local management interface to work with your point of contact profiles.

You can perform the following point of contact profile tasks:

Creating a point of contact profile

Updating or viewing a point of contact profile

Deleting a point of contact profile

Setting a current point of contact profile

Creating a point of contact profile
Create a point of contact server profile to capture the information needed for the runtime to communicate with the point of contact server.

Updating or viewing a point of contact profile
Update or view a point of contact server profile.

Deleting a point of contact profile
Use the local management interface to remove a point of contact profile.

Setting a current point of contact profile
Set a point of contact profile as the current one so that the federation runtime communicates with the point of contact server using the correct set of specifications.

Parent topic: Federation administration

Creating a point of contact profileCreate a point of contact server profile to capture the information needed for the runtime to communicate with the point of contact server.point of contact profilecreatingfederationpoint of contact profileAdvanced Access Controlpoint of contact profileYou can create point of contact profiles with the Federation module or the Advanced Access Control module. Three point of contact profiles provided by Security Access Manager are ready for use. See Preconfigured point of contact profilesThe appliance provides three preconfigured point of contact profiles you can use to define how your federation runtime communicates with the point of contact server. for specifications of these profiles. When you want to create your own profile that is similar to an existing one, use Create Like to save time. If you do not want to reuse any of the existing specifications, create a brand new one with Create. The details are in the following procedure.From the local management interface, select Secure Federation or Secure Access Control. Then, Global SettingsPoint of Contact.A list of point of contact server profiles displays. The list includes three preconfigured profiles and any other custom profiles that you created.Take one of the following actions: Click Create to create a custom point of contact profile.Select a profile from the list and click Create Like to start with values similar to an existing profile. On the Profile Name page, enter the name of the profile. The first character of the profile name must be alphanumeric. The maximum number of characters is 200.Enter a description.Specify the parameter information:Enter the information on each tabbed page, and click Next.In the Callback Parameters section on each page, click Create to open a window to add a set of parameter name and value pairs. Click Save when complete.See Callback parameters and valuesSpecify the callback parameters and values when you define a point of contact profile. for descriptions.Add as many parameters as you need. The Value field might be empty for some parameters.To delete a parameter name from the list, select the parameter and click Delete.At the Summary page, if everything is correct, click Finish.Deploy the pending changes.You might want to change the current point of contact profile. See Setting a current point of contact profileSet a point of contact profile as the current one so that the federation runtime communicates with the point of contact server using the correct set of specifications..Managing point of contact profilesUse the local management interface to work with your point of contact profiles.Callback parameters and valuesSpecify the callback parameters and values when you define a point of contact profile.

Creating a point of contact profile

Create a point of contact server profile to capture the information needed for the runtime to communicate with the point of contact server.

About this task

You can create point of contact profiles with the Federation module or the Advanced Access Control module.

Three point of contact profiles provided by Security Access Manager are ready for use. See Preconfigured point of contact profiles for specifications of these profiles.

When you want to create your own profile that is similar to an existing one, use Create Like to save time. If you do not want to reuse any of the existing specifications, create a brand new one with Create. The details are in the following procedure.

Procedure

From the local management interface, select Secure Federation or Secure Access Control. Then, Global Settings > Point of Contact. A list of point of contact server profiles displays. The list includes three preconfigured profiles and any other custom profiles that you created.

Take one of the following actions:

Click Create to create a custom point of contact profile.

Select a profile from the list and click Create Like to start with values similar to an existing profile.

On the Profile Name page, enter the name of the profile. The first character of the profile name must be alphanumeric. The maximum number of characters is 200.

Optional: Enter a description.

Specify the parameter information:

Enter the information on each tabbed page, and click Next.

In the Callback Parameters section on each page, click Create to open a window to add a set of parameter name and value pairs. Click Save when complete.

See Callback parameters and values for descriptions.

Add as many parameters as you need. The Value field might be empty for some parameters.

To delete a parameter name from the list, select the parameter and click Delete.

At the Summary page, if everything is correct, click Finish.

Deploy the pending changes.

What to do next

You might want to change the current point of contact profile. See Setting a current point of contact profile.

Callback parameters and values
Specify the callback parameters and values when you define a point of contact profile.

Parent topic: Managing point of contact profiles

Callback parameters and valuesSpecify the callback parameters and values when you define a point of contact profile.callback parameterspoint of contact profilepoint of contact profilecallback parametersSign In callbacks fim.user.request.header.nameThe name of the header that contains the user name of the user.Data type: StringExample: iv-userfim.attributes.response.header.nameThe name of the header that contains the attributes of the user. Data type: StringExample: am-fim-eai-xattrsfim.groups.response.header.nameThe name of the header that contains the groups of the user. Data type: StringExample: fim.groupsfim.server.response.header.nameThe name of the header that contains the hostname that authenticates the user. Data type: StringExample: fim.serverfim.target.response.header.nameThe name of the header that contains the redirect URL.Data type: StringExample: am-fim-eai-redir-urlfim.user.response.header.nameThe name of the header that contains the user name of the user.Data type: StringExample: am-fim-eai-user-idfim.user.session.id.response.header.nameThe name of the header that contains the reverse proxy session ID of the user.Data type: StringExample: user_session_idfim.cred.response.header.nameThe name of the header that contains the IVCred of the user.Data type: StringExample: am-fim-eai-pacurl.encoding.enabledIndicates whether the EAI header names and values are URL encoded. The default setting for this property is false. The EAI header names and values are not URL encoded.Data type: BooleanExample: falseSign Out callbacks fim.user.session.id.request.header.nameThe name of the header that contains the reverse proxy session ID of the user.Data type: StringExample: user_session_idfim.user.request.header.nameThe name of the header that contains the user name.Data type: StringExample: iv-userLocal ID fim.attributes.request.header.nameThe name of the header that contains the attributes of the user.Data type: StringExample: fim.attributesfim.cred.request.header.nameThe header that contains the IVCred of the user.Data type: StringExample: iv-credsfim.groups.request.header.nameThe name of the header that contains the groups of the user.Data type: StringExample: iv-groupsfim.user.request.header.nameThe name of the header that contains the user name.Data type: StringExample: iv-userAuthenticate fim.user.request.header.nameThe name of the header that contains the user name.Data type: StringExample: iv-userauthentication.macrosA list of macros that defines contextual information to pass to the web reverse proxy login page. The macros you specify can customize an authentication login page for a specific service provider. For more information, see Customizing the SAML 2.0 login formAn identity provider can customize the default authentication login page with more contextual information..Data type: StringExample: If an identity provider wants to display the provider ID and target URL of a partner, specify the following macros: %PARTNERID%,%TARGET%Creating a point of contact profileCreate a point of contact server profile to capture the information needed for the runtime to communicate with the point of contact server.

Callback parameters and values

Specify the callback parameters and values when you define a point of contact profile.

Sign In callbacks

fim.user.request.header.name

The name of the header that contains the user name of the user.

Data type: String

Example: iv-user

fim.attributes.response.header.name

The name of the header that contains the attributes of the user.

Data type: String

Example: am-fim-eai-xattrs

fim.groups.response.header.name

The name of the header that contains the groups of the user.

Data type: String

Example: fim.groups

fim.server.response.header.name

The name of the header that contains the hostname that authenticates the user.

Data type: String

Example: fim.server

fim.target.response.header.name

The name of the header that contains the redirect URL.

Data type: String

Example: am-fim-eai-redir-url

fim.user.response.header.name

The name of the header that contains the user name of the user.

Data type: String

Example: am-fim-eai-user-id

fim.user.session.id.response.header.name

The name of the header that contains the reverse proxy session ID of the user.

Data type: String

Example: user_session_id

fim.cred.response.header.name

The name of the header that contains the IVCred of the user.

Data type: String

Example: am-fim-eai-pac

url.encoding.enabled

Indicates whether the EAI header names and values are URL encoded. The default setting for this property is false. The EAI header names and values are not URL encoded.

Data type: Boolean

Example: false

Sign Out callbacks

fim.user.session.id.request.header.name

The name of the header that contains the reverse proxy session ID of the user.

Data type: String

Example: user_session_id

fim.user.request.header.name

The name of the header that contains the user name.

Data type: String

Example: iv-user

Local ID

fim.attributes.request.header.name

The name of the header that contains the attributes of the user.

Data type: String

Example: fim.attributes

fim.cred.request.header.name

The header that contains the IVCred of the user.

Data type: String

Example: iv-creds

fim.groups.request.header.name

The name of the header that contains the groups of the user.

Data type: String

Example: iv-groups

fim.user.request.header.name

The name of the header that contains the user name.

Data type: String

Example: iv-user

Authenticate

fim.user.request.header.name

The name of the header that contains the user name.

Data type: String

Example: iv-user

authentication.macros

A list of macros that defines contextual information to pass to the web reverse proxy login page. The macros you specify can customize an authentication login page for a specific service provider. For more information, see Customizing the SAML 2.0 login form.

Data type: String

Example: If an identity provider wants to display the provider ID and target URL of a partner, specify the following macros:

%PARTNERID%,%TARGET%

Parent topic: Creating a point of contact profile

Updating or viewing a point of contact profileUpdate or view a point of contact server profile.point of contact profileupdatingYou cannot update the preconfigured point of contact profiles.From the local management interface, select Secure FederationGlobal SettingsPoint of Contact.A list of point of contact server profiles displays.Perform one of the following actions:UpdateSelect a profile from the list that is not a preconfigured profile and click Update to change the configuration details.Click Next to see each page and make updates if necessary. See Callback parameters and valuesSpecify the callback parameters and values when you define a point of contact profile. for more information about the properties.On the Summary page, click Finish to save your changes.Deploy the changes.ViewSelect a profile from the list and click Properties to look at the configuration details without making updates.Click on each tab to see the information.Click OK when finished.Managing point of contact profilesUse the local management interface to work with your point of contact profiles.

Updating or viewing a point of contact profile

Update or view a point of contact server profile.

About this task

You cannot update the preconfigured point of contact profiles.

Procedure

From the local management interface, select Secure Federation > Global Settings > Point of Contact. A list of point of contact server profiles displays.

Perform one of the following actions:

Update

Select a profile from the list that is not a preconfigured profile and click Update to change the configuration details.

Click Next to see each page and make updates if necessary. See Callback parameters and values for more information about the properties.

On the Summary page, click Finish to save your changes.

Deploy the changes.

View

Select a profile from the list and click Properties to look at the configuration details without making updates.

Click on each tab to see the information.

Click OK when finished.

Parent topic: Managing point of contact profiles

Deleting a point of contact profileUse the local management interface to remove a point of contact profile.point of contact profiledeletingYou cannot delete the following profiles: A preconfigured point of contact profile. See Preconfigured point of contact profilesThe appliance provides three preconfigured point of contact profiles you can use to define how your federation runtime communicates with the point of contact server..A profile that is set as the current profile. Select another profile as the current one, if necessary. See Setting a current point of contact profileSet a point of contact profile as the current one so that the federation runtime communicates with the point of contact server using the correct set of specifications..From the local management interface, select Secure FederationGlobal SettingsPoint of Contact.A list of point of contact server profiles displays.Select a profile from the list, that is not a preconfigured profile, and click Delete. The details of the selected profile display.Review the profile to ensure that it is the one you want to delete.Click Finish.Click OK to confirm.Deploy the change.Managing point of contact profilesUse the local management interface to work with your point of contact profiles.

Deleting a point of contact profile

Use the local management interface to remove a point of contact profile.

About this task

You cannot delete the following profiles:

A preconfigured point of contact profile. See Preconfigured point of contact profiles.

A profile that is set as the current profile. Select another profile as the current one, if necessary. See Setting a current point of contact profile.

Procedure

From the local management interface, select Secure Federation > Global Settings > Point of Contact. A list of point of contact server profiles displays.

Select a profile from the list, that is not a preconfigured profile, and click Delete. The details of the selected profile display.

Review the profile to ensure that it is the one you want to delete.

Click Finish.

Click OK to confirm.

Deploy the change.

Parent topic: Managing point of contact profiles

Setting a current point of contact profileSet a point of contact profile as the current one so that the federation runtime communicates with the point of contact server using the correct set of specifications.point of contact profilecurrentFrom the local management interface, select Secure FederationGlobal SettingsPoint of Contact.A list of point of contact server profiles displays. The list includes three preconfigured profiles and any other custom profiles that you created. The green dot indicates the current profile.To change the current profile, select the profile you want to use as the current one and click Set As Current.The current profile indicator displays next to the profile you selected.Deploy the changes.Managing point of contact profilesUse the local management interface to work with your point of contact profiles.

Setting a current point of contact profile

Set a point of contact profile as the current one so that the federation runtime communicates with the point of contact server using the correct set of specifications.

Procedure

From the local management interface, select Secure Federation > Global Settings > Point of Contact. A list of point of contact server profiles displays. The list includes three preconfigured profiles and any other custom profiles that you created. The green dot indicates the current profile.

To change the current profile, select the profile you want to use as the current one and click Set As Current. The current profile indicator displays next to the profile you selected.

Deploy the changes.

Parent topic: Managing point of contact profiles

Managing server connectionsTo access data from outside of your appliance, you must define a server connection.server connectionsLDAPLDAPserver connectionfederationsLDAP data sourceObtain the connection information for an existing LDAP database server.With a Federation module activated, you can create server connections to an LDAP data source. You can have multiple servers for an LDAP connection.Even though other server connection types are available to select in the local management interface, such as DB2, only the LDAP server connection is used by Federation module. If you also have the Advanced Access Control module activated, you can create any of the server connection types. See Managing server connectionsTo use data from outside your appliance in your policies, you must define the server connection to access the data..Log in to the local management interface.Click Secure Federation.Under Global Settings, click Server Connections.Take one of the following actions:Filter server connections:In the Quick Filter field, type one or more characters. For example, enter g to search for all server connection names that contain g or G. Press Enter.Add a server connection:Click the Add drop-down button.Select LDAP.Complete the properties for the new server connection. See Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.. Look specifically for the LDAP properties.Modify an existing server connection:Select a server connection.Click the edit iconEdit.Complete the properties for the server connection. See Server connection propertiesTo access a data source outside of the appliance, define the properties of the server..Delete a server connection:Be careful about removing a server connection that is in use. Select a server connection.Click the delete iconDelete. Click Delete to confirm the deletion.After you define a server connection to an LDAP data source, you can create an attribute source that looks up information from the LDAP server.Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.Server connection propertiesTo access a data source outside of the appliance, define the properties of the server.

Managing server connections

To access data from outside of your appliance, you must define a server connection.

Before you begin

Obtain the connection information for an existing LDAP database server.

About this task

With a Federation module activated, you can create server connections to an LDAP data source. You can have multiple servers for an LDAP connection.

Note: Even though other server connection types are available to select in the local management interface, such as DB2, only the LDAP server connection is used by Federation module.

If you also have the Advanced Access Control module activated, you can create any of the server connection types. See Managing server connections.

Procedure

Log in to the local management interface.

Click Secure Federation.

Under Global Settings, click Server Connections.

Take one of the following actions:

Filter server connections:

In the Quick Filter field, type one or more characters. For example, enter g to search for all server connection names that contain g or G.

Press Enter.

Add a server connection:

Click the Add drop-down button.

Select LDAP.

Complete the properties for the new server connection. See Server connection properties. Look specifically for the LDAP properties.

Modify an existing server connection:

Select a server connection.

Click the edit iconEdit.

Complete the properties for the server connection. See Server connection properties.

Delete a server connection:

Note: Be careful about removing a server connection that is in use.

Select a server connection.

Click the delete iconDelete.

Click Delete to confirm the deletion.

What to do next

After you define a server connection to an LDAP data source, you can create an attribute source that looks up information from the LDAP server.

Server connection properties
To access a data source outside of the appliance, define the properties of the server.

Parent topic: Federation administration

Managing LTPA keysYou can create, import, export, and delete LTPA key files that are used by the LTPA token conversion module.Ensure that your browser allows pop-up windows to be displayed.Log in to the local management interface.Click Secure Federation.Under Global Keys, click LTPA Keys.Perform any of the following actions:Importing an LTPA key:Click ManageImport.Click Browse.Select the file that you want to import.Click Import.Exporting an LTPA key:Click Browse.Select the file that you want to export.Click ManageExport.Confirm that you want to save the file to your local workstation.Deleting an LTPA key:Select the file that you want to delete.Click Delete.Click Yes when you are prompted to confirm the deletion.Deploy the changes as described in Configuration changes commit processThe LMI uses a two-stage commit process when you make changes to the appliance. .Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.

Managing LTPA keys

You can create, import, export, and delete LTPA key files that are used by the LTPA token conversion module.

Before you begin

Ensure that your browser allows pop-up windows to be displayed.

Procedure

Log in to the local management interface.

Click Secure Federation.

Under Global Keys, click LTPA Keys.

Perform any of the following actions:

Importing an LTPA key:

Click Manage > Import.

Click Browse.

Select the file that you want to import.

Click Import.

Exporting an LTPA key:

Click Browse.

Select the file that you want to export.

Click Manage > Export.

Confirm that you want to save the file to your local workstation.

Deleting an LTPA key:

Select the file that you want to delete.

Click Delete.

Click Yes when you are prompted to confirm the deletion.

Deploy the changes as described in Configuration changes commit process.

Parent topic: Federation administration

Managing JavaScript mapping rulesCreate, edit, or delete JavaScript mapping rules.When you activate the Federation offering, the following mapping rule types are available: OIDCOpenID Connect mapping rule.SAML2_0SAML 2.0 mapping rule.Click Secure Federation.Under Global Settings, click Mapping Rules.All existing mapping rules are displayed.You can create, edit, or delete a mapping rule.To create a mapping ruleClick Add.In the Content field, enter the JavaScript mapping rule content.In the Name field, enter a name for the rule.In the Category field, select the type of the mapping rule from the list, or type a name to create your own mapping rule type.Only the mapping rule types that apply to your current activated offering are displayed in the list.Click Save.To modify a mapping ruleSelect the mapping rule to modify.Click Edit.Modify the mapping rule in the Content field as needed.The Name and Category fields are not editable.Click Save.To delete a mapping ruleDo not delete a mapping rule that is currently used by a SAML 2.0 or OpenID Connect federation.Select the mapping rule to delete.Click Delete.Confirm the delete operation.Federation administrationUse the topics in this hierarchy to administer the Federation features, if you have activated this module.

Managing JavaScript mapping rules

Create, edit, or delete JavaScript mapping rules.

About this task

When you activate the Federation offering, the following mapping rule types are available:

OIDC

OpenID Connect mapping rule.

SAML2_0

SAML 2.0 mapping rule.

Procedure

Click Secure Federation.

Under Global Settings, click Mapping Rules. All existing mapping rules are displayed.

You can create, edit, or delete a mapping rule.

To create a mapping rule

Click Add.

In the Content field, enter the JavaScript mapping rule content.

In the Name field, enter a name for the rule.

In the Category field, select the type of the mapping rule from the list, or type a name to create your own mapping rule type.

Note: Only the mapping rule types that apply to your current activated offering are displayed in the list.

Click Save.

To modify a mapping rule

Select the mapping rule to modify.

Click Edit.

Modify the mapping rule in the Content field as needed.

Note: The Name and Category fields are not editable.

Click Save.

To delete a mapping rule

Note: Do not delete a mapping rule that is currently used by a SAML 2.0 or OpenID Connect federation.

Select the mapping rule to delete.

Click Delete.

Confirm the delete operation.

Parent topic: Federation administration

AuditingThe IBM Security Access Manager provides information about configuring and managing audit events.auditingAuditing overviewAuditing is the process of maintaining detailed and secure logs of critical activities in a business environment. Configuring auditing on the applianceUse the Audit Configuration feature to enable logging of audit events.Native Security Access Manager auditingAudit eventsRouting filesConfiguration stanzasCommands and utilitiesAuditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

Auditing

The IBM Security Access Manager provides information about configuring and managing audit events.

Auditing overview
Auditing is the process of maintaining detailed and secure logs of critical activities in a business environment.

Configuring auditing on the appliance
Use the Audit Configuration feature to enable logging of audit events.

Native Security Access Manager auditing

Audit events

Routing files

Configuration stanzas

Commands and utilities

Auditing Advanced Access Control
These topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

Auditing Federation
These topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

Auditing overviewAuditing overviewAuditing overviewAuditing is the process of maintaining detailed and secure logs of critical activities in a business environment. These activities can be related to security, content management, business transactions, or other such activities.For example, the following activities can be audited:Login failuresUnauthorized access to protected resourcesModification to security policyUse the method that is provided in Native Security Access Manager auditing to manage audit events with the native Security Access Manager approach.For information about managing statistical events, see Working with statistics. For information about WebSEAL HTTP events, see WebSEAL HTTP logging.Auditing versus diagnosticsSecurity Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers. Events for diagnostics and auditing pertain to the operations of the servers.To enable diagnostics and auditing, define which types of events to capture. You can write recorded events to one or a combination of the following files or devices:Log file.Standard output (STDOUT) device.Standard error (STDERR) device.Beyond these destinations, when events are captured, they can be redirected to a remote authorization server or redirected to an application for processing. Audit eventsFor auditing purposes, define which audit, statistic, or other type of events to capture. You can use events to create snapshots of various server activities. You can record audit events by using the native Security Access Manager support.To configure auditing events, define stanza entries in the configuration files. Depending on your approach, you define different stanza entries in different configuration files.Use the following guidelines for defining the auditing configuration:For audit events, define logcfg entries in the [aznapi-configuration] stanza of the server configuration file.For HTTP request events, define entries in the [aznapi-configuration] and [logging] stanzas of the WebSEAL configuration files for HTTP events that you want to record.Diagnostic eventsFor diagnostic information, define which message events and which trace events to capture. These events can help you troubleshoot problems.To configure diagnostic events, you must define statements in the server-specific routing files. Each server has an associated routing file. The statements in these routing files are for both message events and trace events. You define the statements for message events by severity level. You can define the statements for trace events by trace level and optionally by component.For more information about message and trace events, see the Troubleshooting topics in the IBM Knowledge Center.Audit trailsIT organizations can use information that is contained in audit trails to help them show compliance with government regulations such as the following regulations:Sarbanes-Oxley (SOX) Act.The Health Insurance Portability and Accountability Act (HIPAA).The Basel II international banking accord.For these reasons, such audit trails must be sometimes maintained for years. Audit trails are useful to check enforcement and effectiveness of IT controls, for accountability and vulnerability, and for risk analysis. IT organizations can also use auditing of security-related critical activities to aid in forensic investigations of security incidents. When a security incident occurs, audit trails enable analysis of the history of activities that occurred before the security incident. This analysis might answer questions such as who did what, when, where, and how. Based on this analysis, appropriate corrective actions can be taken. For these reasons, audit trails must be archived and accessible for years.Audit trails can be established in relational databases that are easily queried to generate reports. When audit trails are written to relational databases, reporting tools can be used to display reports. Reports can fall into the following categories:Trend reports provide summarized audit data that you can use to assess whether there is any long-term rise or fall in questionable activity. Trend reports can help provide a security pulse for an organization.Operational reports allow a detailed review of audit data to help determine the cause of a security incident.Audit records for HTTP accessThe generation of audit records for HTTP access to WebSEAL can use large quantities of disk space quickly. You can reduce the volume of audit events that are generated by using the following strategies:Generate events for unsuccessful HTTP accesses only.Selectively disable the generation of events by using attached protected object policies (POPs).For details about reducing records by generating events for unsuccessful accesses only, see Native auditing if you are using native Security Access Manager auditing.For details about using POPs to selectively disable the generation of audit events, see Disabling resource access eventsYou can use protected object policies (POPs) to selectively disable auditing of access to particular resources..AuditingThe IBM Security Access Manager provides information about configuring and managing audit events.

Auditing overview

Auditing is the process of maintaining detailed and secure logs of critical activities in a business environment.

These activities can be related to security, content management, business transactions, or other such activities.

For example, the following activities can be audited:

Login failures

Unauthorized access to protected resources

Modification to security policy

Use the method that is provided in Native Security Access Manager auditing to manage audit events with the native Security Access Manager approach.

For information about managing statistical events, see Working with statistics. For information about WebSEAL HTTP events, see WebSEAL HTTP logging.

Auditing versus diagnostics

Security Access Manager provides ways to collect events that you can use for diagnostic and auditing purposes of the servers. Events for diagnostics and auditing pertain to the operations of the servers.

To enable diagnostics and auditing, define which types of events to capture. You can write recorded events to one or a combination of the following files or devices:

Log file.

Standard output (STDOUT) device.

Standard error (STDERR) device.

Beyond these destinations, when events are captured, they can be redirected to a remote authorization server or redirected to an application for processing.

Audit events

For auditing purposes, define which audit, statistic, or other type of events to capture.

You can use events to create snapshots of various server activities. You can record audit events by using the native Security Access Manager support.

To configure auditing events, define stanza entries in the configuration files. Depending on your approach, you define different stanza entries in different configuration files.

Use the following guidelines for defining the auditing configuration:

For audit events, define logcfg entries in the [aznapi-configuration] stanza of the server configuration file.

For HTTP request events, define entries in the [aznapi-configuration] and [logging] stanzas of the WebSEAL configuration files for HTTP events that you want to record.

Diagnostic events

For diagnostic information, define which message events and which trace events to capture. These events can help you troubleshoot problems.

To configure diagnostic events, you must define statements in the server-specific routing files. Each server has an associated routing file. The statements in these routing files are for both message events and trace events. You define the statements for message events by severity level. You can define the statements for trace events by trace level and optionally by component.

For more information about message and trace events, see the Troubleshooting topics in the IBM Knowledge Center.

Audit trails

IT organizations can use information that is contained in audit trails to help them show compliance with government regulations such as the following regulations:

Sarbanes-Oxley (SOX) Act.

The Health Insurance Portability and Accountability Act (HIPAA).

The Basel II international banking accord.

For these reasons, such audit trails must be sometimes maintained for years.

Audit trails are useful to check enforcement and effectiveness of IT controls, for accountability and vulnerability, and for risk analysis. IT organizations can also use auditing of security-related critical activities to aid in forensic investigations of security incidents.

When a security incident occurs, audit trails enable analysis of the history of activities that occurred before the security incident. This analysis might answer questions such as who did what, when, where, and how. Based on this analysis, appropriate corrective actions can be taken. For these reasons, audit trails must be archived and accessible for years.

Audit trails can be established in relational databases that are easily queried to generate reports. When audit trails are written to relational databases, reporting tools can be used to display reports. Reports can fall into the following categories:

Trend reports provide summarized audit data that you can use to assess whether there is any long-term rise or fall in questionable activity. Trend reports can help provide a "security pulse" for an organization.

Operational reports allow a detailed review of audit data to help determine the cause of a security incident.

Audit records for HTTP access

The generation of audit records for HTTP access to WebSEAL can use large quantities of disk space quickly. You can reduce the volume of audit events that are generated by using the following strategies:

Generate events for unsuccessful HTTP accesses only.

Selectively disable the generation of events by using attached protected object policies (POPs).

For details about reducing records by generating events for unsuccessful accesses only, see Native auditing if you are using native Security Access Manager auditing.

For details about using POPs to selectively disable the generation of audit events, see Disabling resource access events.

Parent topic: Auditing

Overview of Security Access Manager event loggingOverview of Security Access Manager event loggingOverview of Security Access Manager event loggingFor auditing and other serviceability purposes, Security Access Manager uses a structured hierarchy of events. This hierarchy is built dynamically and allows runtime-associations to be made between event categories and the log agents that record those events. loggingoverviewFigure 1 shows the hierarchy of Security Access Manager events in the event pool.Event pool hierarchyEvent pool hierarchyNatively, Security Access Manager generates and can record the following primary categories of events:Audit eventsFor information about audit events, see Audit event loggingTo enable logging, define entries in the configuration file. .HTTP request eventsFor information about HTTP request events, see WebSEAL HTTP logging.Statistical eventsFor information about statistical events, see Working with statistics.Trace eventsFor information about trace events, see the Troubleshooting topics in the Knowledge Center.

Overview of Security Access Manager event logging

For auditing and other serviceability purposes, Security Access Manager uses a structured hierarchy of events. This hierarchy is built dynamically and allows runtime-associations to be made between event categories and the log agents that record those events.

Figure 92. shows the hierarchy of Security Access Manager events in the event pool.

Figure 92. Event pool hierarchy

Natively, Security Access Manager generates and can record the following primary categories of events:

Audit events

For information about audit events, see Audit event logging.

HTTP request events

For information about HTTP request events, see WebSEAL HTTP logging.

Statistical events

For information about statistical events, see Working with statistics.

Trace events

For information about trace events, see the Troubleshooting topics in the Knowledge Center.

Native auditingNative auditingNative auditingauditoverviewAuditing is defined as the logging of audit records. It includes the collection of data about system activities that affect the secure operation of the Security Access Manager server processes. Each Security Access Manager server can capture audit events whenever any security-related auditable activity occurs.Auditing uses the concepts of a record, an audit event, and an audit trail. Each audited activity is called an audit event. The output of a specific server event is called a record. An audit trail is a collection of multiple records that document the server activity.When configuring for auditing, think about the source of the events that you want to capture. Audit trail files can capture authorization, authentication, and management events that are generated by the Security Access Manager servers. There are multiple sources for auditing events that you want to gather. You can collect either a combination or all the different types of auditing events at the same time. Table 1 shows some of the event types that can be used for native auditing.Categories and description of native audit eventsEvent categoryDescriptionaudit.authzAuthorization events for WebSEAL serversaudit.aznAuthorization events for base serversaudit.authnAuthentication, credential acquisition authentication, password change, and logout eventsaudit.authn.successfulSuccessful authentication credential acquisition authentication, password change, and logout eventsaudit.authn.unsuccessfulFailed authentication credential acquisition authentication, password change, and logout eventsaudit.httpHTTP access eventsaudit.http.successfulSuccessful HTTP access eventsaudit.http.unsuccessfulFailed HTTP access eventsaudit.mgmtManagement eventshttpHTTP logging informationhttp.clfHTTP request information defined by the request-log-format configuration entry in the [logging] stanza. clf stands for common log format.http.refHTTP Referrer header informationhttp.agentHTTP User Agent head information

Native auditing

Auditing is defined as the logging of audit records. It includes the collection of data about system activities that affect the secure operation of the Security Access Manager server processes. Each Security Access Manager server can capture audit events whenever any security-related auditable activity occurs.

Auditing uses the concepts of a record, an audit event, and an audit trail. Each audited activity is called an audit event. The output of a specific server event is called a record. An audit trail is a collection of multiple records that document the server activity.

When configuring for auditing, think about the source of the events that you want to capture. Audit trail files can capture authorization, authentication, and management events that are generated by the Security Access Manager servers. There are multiple sources for auditing events that you want to gather. You can collect either a combination or all the different types of auditing events at the same time. Table 228 shows some of the event types that can be used for native auditing.

Table 228. Categories and description of native audit events

Event category | Description
audit.authz | Authorization events for WebSEAL servers
audit.azn | Authorization events for base servers
audit.authn | Authentication, credential acquisition authentication, password change, and logout events
audit.authn.successful | Successful authentication credential acquisition authentication, password change, and logout events
audit.authn.unsuccessful | Failed authentication credential acquisition authentication, password change, and logout events
audit.http | HTTP access events
audit.http.successful | Successful HTTP access events
audit.http.unsuccessful | Failed HTTP access events
audit.mgmt | Management events
http | HTTP logging information
http.clf | HTTP request information defined by the request-log-format configuration entry in the [logging] stanza. clf stands for common log format.
http.ref | HTTP Referrer header information
http.agent | HTTP User Agent head information

Statistics gatheringstatisticsgatherSecurity Access Manager servers provide a series of modules that can monitor and collect information about specific server activity. After enabling a module, you can display the statistical information that it gathered since it was enabled. In addition to displaying this information, you can direct these statistics to a log file.You can work with statistics with the server task stats command or with stanza entries in the configuration file for the specific server.When you display statistics, you see a snapshot of the statistics. These statistics provide a view of the recorded activity. If you capture statistics at regular intervals, you can determine trend analyses against the server activities.For information about enabling and working with the statistics gathering modules, see Working with statistics.

Statistics gathering

Security Access Manager servers provide a series of modules that can monitor and collect information about specific server activity. After enabling a module, you can display the statistical information that it gathered since it was enabled. In addition to displaying this information, you can direct these statistics to a log file.

You can work with statistics with the server task stats command or with stanza entries in the configuration file for the specific server.

When you display statistics, you see a snapshot of the statistics. These statistics provide a view of the recorded activity. If you capture statistics at regular intervals, you can determine trend analyses against the server activities.

For information about enabling and working with the statistics gathering modules, see Working with statistics.

Logging processloggingprocessFigure 1 depicts the relationships among the steps in the logging process. The top part of the figure represents the code of a Security Access Manager server. The code contains probe points where events of specific types can be generated. Generated events are submitted to the server event pool for possible recording through a point of capture (event sink). The event pool defines the events category.At run time, you can subscribe a log agent at any point in the event pool hierarchy. You can selectively record events that are generated at the probe points for the program. The middle part of the figure depicts subscription.For example, you can subscribe to a remote client for capturing events. This client forwards the selected events to a remote authorization server.The lower part of the figure depicts this remote server. Relayed events are placed in the event pool at the remote probe points for the authorization server.Application-specific probe pointsDiagram showing relationships in the logging process

Logging process

Figure 93. depicts the relationships among the steps in the logging process. The top part of the figure represents the code of a Security Access Manager server. The code contains probe points where events of specific types can be generated. Generated events are submitted to the server event pool for possible recording through a point of capture (event sink). The event pool defines the events category.

At run time, you can subscribe a log agent at any point in the event pool hierarchy. You can selectively record events that are generated at the probe points for the program. The middle part of the figure depicts subscription.

For example, you can subscribe to a remote client for capturing events. This client forwards the selected events to a remote authorization server.

The lower part of the figure depicts this remote server. Relayed events are placed in the event pool at the remote probe points for the authorization server.

Figure 93. Application-specific probe points

Audit data in UTF-8 formataudit dataUTF-8UTF-8audit dataSecurity Access Manager produces audit data that uses UTF-8 encoding. When the operating system uses a non-UTF-8 code page, Security Access Manager converts the data to a format that matches the non-UTF-8 code page. In some cases, the conversion can result in data loss. For this reason, run Security Access Manager in an environment that uses UTF-8 encoded code pages.When the operating system does not use a UTF-8 code page, the conversion to UTF-8 can result in data loss. When data loss occurs, the log file contains a series of question mark (?) characters at the location where the data conversion was problematic.When running in a non-UTF-8 locale, use the UTF8FILE type in the routing file. For more information about the UTF8FILE type, see Routing files.

Audit data in UTF-8 format

Security Access Manager produces audit data that uses UTF-8 encoding. When the operating system uses a non-UTF-8 code page, Security Access Manager converts the data to a format that matches the non-UTF-8 code page. In some cases, the conversion can result in data loss. For this reason, run Security Access Manager in an environment that uses UTF-8 encoded code pages.

When the operating system does not use a UTF-8 code page, the conversion to UTF-8 can result in data loss. When data loss occurs, the log file contains a series of question mark (?) characters at the location where the data conversion was problematic.

When running in a non-UTF-8 locale, use the UTF8FILE type in the routing file. For more information about the UTF8FILE type, see Routing files.

Configuring auditing on the applianceConfiguring auditing on the applianceConfiguring auditing on the applianceUse the Audit Configuration feature to enable logging of audit events.auditlogconfigurationauditDepending on the required audit configuration, you might need the following information to complete the auditing configuration: If you plan to use a syslog server on a remote machine, ensure that you have the information of the location of the syslog server.If you plan to use a TLS type protocol, ensure that the server certificate was imported into the chosen certificate database. If you plan to use client certificate to authenticate to the syslog server, ensure that the certificate is trusted by the syslog server. The certificate must be imported into the chosen certificate database.IBM Security Access Manager provides the capability of collecting and processing system log (syslog) messages. Enable the feature by completing the steps in the audit configuration page to use a common auditing configuration that is used by all runtime components.From the top menu, select Monitor Analysis and DiagnosticsLogsAudit Configuration.Select Enable audit log.Specify the location of the syslog server. On this applianceAudit events are sent to a syslog server on this appliance. If you select the local syslog server, no additional mandatory configuration is needed. If you want to tune the default configuration settings, proceed to step 5.If you configure auditing to use a local syslog server, see Viewing application log filesUse the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager., to view the audit logs. On a remote machineAudit events are sent to a syslog server on a remote machine. If you select a syslog server on a remote machine, you might need to specify some or all of the following information:Syslog server remote machine configuration values. Syslog server remote machine configuration values. Field Default ValuesDescriptionHostNoneSpecifies the host name of the syslog server.Port514Specifies the port of the syslog server.ProtocolUDP Though UDP is the default value, use TLS. TLS is the preferred protocol for production environments.Specifies the type of transport protocol to use to transmit syslog messages.Certificate database (truststore)NoneSpecifies the truststore to use to validate the certificate of the syslog server. This field is enabled only when the transport layer protocol type selected is TLS. Enable client certificate authenticationDisabledIf enabled, the client is able to do client certificate authentication during the SSL handshake upon server request.Certificate database (keystore)NoneSpecifies the keystore to use for client certificate authentication. This field is enabled only when the enable client certificate authentication is selected.Certificate labelNoneSpecifies the personal certificate to use for client certificate authentication. This field is enabled only when the enable client certificate authentication is selected.Enable disk failoverDisabledIf enabled, audit events are logged to a local disk file when an error occurs during the SSL connection to the remote syslog server.If you enable disk failover the audit events are logged to local disk files that follow the naming pattern ISAMAudit0.log.nn, where nn is a number that uniquely identifies a local disk file. The local disk file can be viewed at the same location as the local syslog server audit logs. If you choose to use default values for tuning, you can complete the configuration by clicking Save. Otherwise, proceed with the subsequent steps. If you want to discard the changes you made, click Refresh.Click Tuning. Provide the following information: Audit tuning values Audit tuning values FieldDefault ValueDescriptionEvent Queue Size1000Specifies the maximum number of audit events that the event queue can hold. Syslog messages are queued in the memory before they are sent to the syslog server.Queue Full Timeout (seconds)-1Specifies the number of seconds to wait before an incoming event is discarded when the queue is full. A value of 0 indicates that new events are discarded immediately if the queue is full. A value of -1 indicates that new events wait perpetually for the queue to have a vacancy.Sender Threads1Specifies the number of sender threads, which drain the audit events from the queue to send to the syslog server.Error Retry Count2Specifies the number of times the syslog client tries to establish a connection with the server again if it fails in the first attempt. Click Save. Otherwise, click Refresh to discard the changes you made.AuditingThe IBM Security Access Manager provides information about configuring and managing audit events.

Configuring auditing on the appliance

Use the Audit Configuration feature to enable logging of audit events.

Before you begin

Depending on the required audit configuration, you might need the following information to complete the auditing configuration:

If you plan to use a syslog server on a remote machine, ensure that you have the information of the location of the syslog server.

If you plan to use a TLS type protocol, ensure that the server certificate was imported into the chosen certificate database.

If you plan to use client certificate to authenticate to the syslog server, ensure that the certificate is trusted by the syslog server. The certificate must be imported into the chosen certificate database.

About this task

IBM® Security Access Manager provides the capability of collecting and processing system log (syslog) messages. Enable the feature by completing the steps in the audit configuration page to use a common auditing configuration that is used by all runtime components.

Procedure

From the top menu, select Monitor Analysis and Diagnostics > Logs > Audit Configuration.

Select Enable audit log.

Specify the location of the syslog server.

On this appliance

Audit events are sent to a syslog server on this appliance. If you select the local syslog server, no additional mandatory configuration is needed. If you want to tune the default configuration settings, proceed to step 5.

Note: If you configure auditing to use a local syslog server, see Viewing application log files, to view the audit logs.

On a remote machine

Audit events are sent to a syslog server on a remote machine. If you select a syslog server on a remote machine, you might need to specify some or all of the following information:

Table 229. Syslog server remote machine configuration values..

Field
Default Values
Description

Host
None
Specifies the host name of the syslog server.

Port
514
Specifies the port of the syslog server.

Protocol
UDP

Note: Though UDP is the default value, use TLS. TLS is the preferred protocol for production environments.

Specifies the type of transport protocol to use to transmit syslog messages.

Certificate database (truststore)
None
Specifies the truststore to use to validate the certificate of the syslog server. This field is enabled only when the transport layer protocol type selected is TLS.

Enable client certificate authentication
Disabled
If enabled, the client is able to do client certificate authentication during the SSL handshake upon server request.

Certificate database (keystore)
None
Specifies the keystore to use for client certificate authentication. This field is enabled only when the enable client certificate authentication is selected.

Certificate label
None
Specifies the personal certificate to use for client certificate authentication. This field is enabled only when the enable client certificate authentication is selected.

Enable disk failover
Disabled
If enabled, audit events are logged to a local disk file when an error occurs during the SSL connection to the remote syslog server.

Note: If you enable disk failover the audit events are logged to local disk files that follow the naming pattern ISAMAudit0.log.nn, where nn is a number that uniquely identifies a local disk file. The local disk file can be viewed at the same location as the local syslog server audit logs.

If you choose to use default values for tuning, you can complete the configuration by clicking Save. Otherwise, proceed with the subsequent steps. If you want to discard the changes you made, click Refresh.

Optional: Click Tuning. Provide the following information:

Table 230. Audit tuning values.

Field | Default Value | Description
Event Queue Size | 1000 | Specifies the maximum number of audit events that the event queue can hold. Syslog messages are queued in the memory before they are sent to the syslog server.
Queue Full Timeout (seconds) | -1 | Specifies the number of seconds to wait before an incoming event is discarded when the queue is full. A value of 0 indicates that new events are discarded immediately if the queue is full. A value of -1 indicates that new events wait perpetually for the queue to have a vacancy.
Sender Threads | 1 | Specifies the number of sender threads, which drain the audit events from the queue to send to the syslog server.
Error Retry Count | 2 | Specifies the number of times the syslog client tries to establish a connection with the server again if it fails in the first attempt.

Click Save. Otherwise, click Refresh to discard the changes you made.

Parent topic: Auditing

Native Security Access Manager auditingAuditingThe IBM Security Access Manager provides information about configuring and managing audit events.Audit event loggingTo enable logging, define entries in the configuration file. WebSEAL HTTP loggingWorking with statistics

Native Security Access Manager auditing

Audit event logging
To enable logging, define entries in the configuration file.

WebSEAL HTTP logging

Working with statistics

Parent topic: Auditing

Audit event loggingTo enable logging, define entries in the configuration file. audit eventslogsSpecify the type of audit event.Specify the location of the audit log.Note: On Windows operating systems, newly created files are given Full Control permissions or inherit permissions from the parent directory. To protect audit files from possible tampering, manually modify the permission settings to Read & Execute on newly created files and on any parent directory.Specify the maximum file size.Specify the file flush interval.Native Security Access Manager auditingLog agentsConfiguring audit eventsIndependent of the logging agent, configure which audit events to capture by using the logcfg entry.Defining logcfg entriesDisabling resource access eventsYou can use protected object policies (POPs) to selectively disable auditing of access to particular resources.Process flow for logcfg loggingThe following example process flow assumes the [aznapi-configuration] stanza of a WebSEAL configuration file. Auditing using logaudit

Audit event logging

To enable logging, define entries in the configuration file.

Procedure

Specify the type of audit event.

Specify the location of the audit log.
Note: On Windows operating systems, newly created files are given "Full Control" permissions or inherit permissions from the parent directory. To protect audit files from possible tampering, manually modify the permission settings to "Read & Execute" on newly created files and on any parent directory.

Specify the maximum file size.

Specify the file flush interval.

Log agents

Configuring audit events
Independent of the logging agent, configure which audit events to capture by using the logcfg entry.

Defining logcfg entries

Disabling resource access events
You can use protected object policies (POPs) to selectively disable auditing of access to particular resources.

Process flow for logcfg logging
The following example process flow assumes the [aznapi-configuration] stanza of a WebSEAL configuration file.

Auditing using logaudit

Parent topic: Native Security Access Manager auditing

Log agentsaudit eventslog agentslog agentsagentslogWith event logging, the concept of a log agent includes capturing events that are redirected to destinations other than the local file system. Event logging uses the following types of log agents, each agent represents an audit trail: Sending events to the consoleConfiguring file log agentsConfiguring remote log agentsAudit event loggingTo enable logging, define entries in the configuration file.

Log agents

With event logging, the concept of a log agent includes capturing events that are redirected to destinations other than the local file system. Event logging uses the following types of log agents, each agent represents an audit trail:

Sending events to the console

Configuring file log agents

Configuring remote log agents

Parent topic: Audit event logging

Configuring audit eventsIndependent of the logging agent, configure which audit events to capture by using the logcfg entry.audit eventsoverviewWhen using the Security Access Manager approach, define the logcfg entry in any or all the following locations: The [aznapi-configuration] stanza of the policy server ivmgrd.conf configuration fileThe [ivacld] stanza of the authorization server ivacld.conf configuration fileThe [aznapi-configuration] stanza of a WebSEAL server webseald.instance.conf configuration fileThe [aznapi-configuration] stanza of the Plug-in for Web Servers pdwebpi.conf configuration fileThe [aznapi-configuration] stanza of the resource manager aznAPI.conf configuration fileAudit event loggingTo enable logging, define entries in the configuration file.

Configuring audit events

Independent of the logging agent, configure which audit events to capture by using the logcfg entry.

When using the Security Access Manager approach, define the logcfg entry in any or all the following locations:

The [aznapi-configuration] stanza of the policy server ivmgrd.conf configuration file

The [ivacld] stanza of the authorization server ivacld.conf configuration file

The [aznapi-configuration] stanza of a WebSEAL server webseald.instance.conf configuration file

The [aznapi-configuration] stanza of the Plug-in for Web Servers pdwebpi.conf configuration file

The [aznapi-configuration] stanza of the resource manager aznAPI.conf configuration file

Parent topic: Audit event logging

Defining logcfg entrieslogcfg entrydefinitionWhen you define the logcfg entry in a configuration file, use the following general format (on a single line) to specify audit event logging: logcfg = category:{stdout|stderr|file|remote} [[parameter[=value]], [parameter[=value]]], ..., [parameter[=value]]]To enable the recording of audit events, associate an event category with a log agent (file or remote) or associate an event category with a console destination (stdout or stderr).When you define the parameters for any logcfg entry, be aware of the following conditions: Parameters can be specified in any sequenceParameter names are not case-sensitiveParameter names can be shortened to any unambiguous nameParameters differ by log agentParameters are optionalEvents for a category are inclusive of all subcomponents in the hierarchy. That is, a foo.bar.fred event is captured when the foo.bar category is defined.You can attach multiple log agents to the same category. For example, the following configuration: Captures authorization audit events (category audit.azn) and uses a file agent to copy these events to the audit.azn file.Uses a pipe agent to relay these same events to the analyse.exe program. [ivacld] logcfg = audit.azn:file path=audit.aznAudit event loggingTo enable logging, define entries in the configuration file. Parameters for the logcfg entryThe available parameters for the logcfg stanza entry differ by log agent.Configuring the event poolSending events to the consoleConfiguring file log agentsConfiguring remote log agentsConfiguring remote syslog agentsUse the logcfg entry to configure the remote syslog agent to send events to a remote syslog server for recording.

Defining logcfg entries

When you define the logcfg entry in a configuration file, use the following general format (on a single line) to specify audit event logging:

logcfg = category:{stdout|stderr|file|remote}
[[parameter[=value]],
[parameter[=value]]],
...,
[parameter[=value]]]

To enable the recording of audit events, associate an event category with a log agent (file or remote) or associate an event category with a console destination (stdout or stderr).

When you define the parameters for any logcfg entry, be aware of the following conditions:

Parameters can be specified in any sequence

Parameter names are not case-sensitive

Parameter names can be shortened to any unambiguous name

Parameters differ by log agent

Parameters are optional

Events for a category are inclusive of all subcomponents in the hierarchy. That is, a foo.bar.fred event is captured when the foo.bar category is defined.

You can attach multiple log agents to the same category. For example, the following configuration:

Captures authorization audit events (category audit.azn) and uses a file agent to copy these events to the audit.azn file.

Uses a pipe agent to relay these same events to the analyse.exe program.

[ivacld]
logcfg = audit.azn:file path=audit.azn

Parameters for the logcfg entry
The available parameters for the logcfg stanza entry differ by log agent.

Configuring the event pool

Sending events to the console

Configuring file log agents

Configuring remote log agents

Configuring remote syslog agents
Use the logcfg entry to configure the remote syslog agent to send events to a remote syslog server for recording.

Parent topic: Audit event logging

Parameters for the logcfg entryThe available parameters for the logcfg stanza entry differ by log agent.logcfg entryavailable parametersTable 1 shows which parameters are available for the EventPool category and the following log agents: File log agentPipe log agentRemote agentRemote syslog agentTable 1 does not show the console log agent. The console log agent does not support parameters. For more information, see Sending events to the console. Available parameters for the logcfg stanza entryParameterEventPool categoryFile log agentPipe log agentRemote log agentRemote syslog agentbuffer_sizeYesYescompressYesdnYeserror_retryYesYesflush_intervalYesYesYesYesYeshi_waterYesYesYesYesYeslog_idYesYesmax_event_lenYesmodeYespathYesYesYesYesportYesYesqueue_sizeYesYesYesYesYesrebind_retryYesYesrollover_sizeYesserverYesYesssl_keyfileYesssl_labelYesssl_stashfileYesDefining logcfg entries

Parameters for the logcfg entry

The available parameters for the logcfg stanza entry differ by log agent.

Table 231 shows which parameters are available for the EventPool category and the following log agents:

File log agent

Pipe log agent

Remote agent

Remote syslog agent

Table 231 does not show the console log agent. The console log agent does not support parameters. For more information, see Sending events to the console.

Table 231. Available parameters for the logcfg stanza entry

Parameter | EventPool category | File log agent | Pipe log agent | Remote log agent | Remote syslog agent
buffer_size |  | Yes |  | Yes |
compress |  |  |  | Yes |
dn |  |  |  | Yes |
error_retry |  |  |  | Yes | Yes
flush_interval | Yes | Yes | Yes | Yes | Yes
hi_water | Yes | Yes | Yes | Yes | Yes
log_id |  | Yes |  |  | Yes
max_event_len |  |  |  |  | Yes
mode |  | Yes |  |  |
path |  | Yes | Yes | Yes | Yes
port |  |  |  | Yes | Yes
queue_size | Yes | Yes | Yes | Yes | Yes
rebind_retry |  |  |  | Yes | Yes
rollover_size |  | Yes |  |  |
server |  |  |  | Yes | Yes
ssl_keyfile |  |  |  |  | Yes
ssl_label |  |  |  |  | Yes
ssl_stashfile |  |  |  |  | Yes

Parent topic: Defining logcfg entries

Configuring the event poolaudit eventsEventPool configurationpropagation queueconfigurationeventspropagation queueflush_interval parameterEventPoolflush_interval parameterpropagation queuelogcfg parametersflush_intervalEventPoollogcfg parametersflush_intervalevent propagation queuepropagation queueflushingEventPoolflush propagation queuehi_water parameterEventPoolhi_water parameterevent propagation queuelogcfg parametershi_waterEventPoollogcfg parametershi_waterevent propagation queueeventshigh water markEventPoolset high water markqueue_size parameterEventPoolqueue_size parameterpropagation queuelogcfg parametersqueue_sizeEventPoollogcfg parametersqueue_sizeevent propagation queuepropagation queueset memory limitEvents are passed to subscribed log agents asynchronously from the application-level requests that construct the events. All events enter the common propagation queue before they are forwarded to the subscribed log agents.The propagation queue is configurable. To configure the propagation queue, define the logcfg stanza entry with EventPool as the category name and specifies the configuration parameters without specifying a log agent.Manage the propagation queue to support the configuration of log agents. For example, limit the amount of memory that is used to queue events for a remote log agent. To limit the amount of memory that is used, constrain the propagation queue with the queue_size parameter: [aznapi-configuration] logcfg = EventPool queue_size=number,hi_water=number, flush_interval=number_seconds logcfg = category:remote buffer_size=number,path=pathname, server=hostname,queue_size=numberYou can define the following parameters for pipe log agents: flush_interval Configure the flush_interval parameter to limit the amount of time that events can remain in the propagation queue. Specify the time in seconds. Assume that the size of the queue does not reach the high water mark within the specified interval. In this case, events in the queue are forwarded to the log agents. The default value is 10 seconds. Specifying a value of 0 is equivalent to setting the value to 600 seconds.hi_water Configure the hi_water parameter to indicate the threshold where events in the propagation queue are forwarded to the log agents. Assume that the size of the queue does not reach this high water mark within the defined flush interval. In this case, events in the queue are forwarded to the log agents. The default value is calculated as two-thirds of the configured queue size. If the queue size is 0 (unlimited), the high water mark is set to 100 events. If the high water mark is 1 event, each event in the queue is forwarded immediately to the log agents. Setting a low value for the high water mark can have an adverse effect on performance.queue_size Because each event in the propagation queue consumes memory, configure the queue_size parameter to define the maximum number of events that the propagation queue can hold. If the maximum size is reached, the event-producing thread is blocked until space is available in the queue. Blocking corresponds to throttling back the performance of the event-producing thread to a rate that can be consumed by the logging threads. The default value is 0. Specifying a value of 0 indicates that no size limit is enforced on the propagation queue. The propagation queue can grow to an unmanageable size when: You use the default value, andThe logging threads cannot process events as they enter the propagation queue.Defining logcfg entries

Configuring the event pool

Events are passed to subscribed log agents asynchronously from the application-level requests that construct the events. All events enter the common propagation queue before they are forwarded to the subscribed log agents.

The propagation queue is configurable. To configure the propagation queue, define the logcfg stanza entry with EventPool as the category name and specifies the configuration parameters without specifying a log agent.

Manage the propagation queue to support the configuration of log agents. For example, limit the amount of memory that is used to queue events for a remote log agent. To limit the amount of memory that is used, constrain the propagation queue with the queue_size parameter:

[aznapi-configuration]
logcfg = EventPool queue_size=number,hi_water=number,
     flush_interval=number_seconds
logcfg = category:remote buffer_size=number,path=pathname,
     server=hostname,queue_size=number

You can define the following parameters for pipe log agents:

flush_interval

Configure the flush_interval parameter to limit the amount of time that events can remain in the propagation queue. Specify the time in seconds. Assume that the size of the queue does not reach the high water mark within the specified interval. In this case, events in the queue are forwarded to the log agents.

The default value is 10 seconds. Specifying a value of 0 is equivalent to setting the value to 600 seconds.

hi_water

Configure the hi_water parameter to indicate the threshold where events in the propagation queue are forwarded to the log agents. Assume that the size of the queue does not reach this high water mark within the defined flush interval. In this case, events in the queue are forwarded to the log agents.

The default value is calculated as two-thirds of the configured queue size. If the queue size is 0 (unlimited), the high water mark is set to 100 events. If the high water mark is 1 event, each event in the queue is forwarded immediately to the log agents.

Setting a low value for the high water mark can have an adverse effect on performance.

queue_size

Because each event in the propagation queue consumes memory, configure the queue_size parameter to define the maximum number of events that the propagation queue can hold. If the maximum size is reached, the event-producing thread is blocked until space is available in the queue. Blocking corresponds to throttling back the performance of the event-producing thread to a rate that can be consumed by the logging threads.

The default value is 0. Specifying a value of 0 indicates that no size limit is enforced on the propagation queue. The propagation queue can grow to an unmanageable size when:

You use the default value, and

The logging threads cannot process events as they enter the propagation queue.

Parent topic: Defining logcfg entries

Sending events to the consoleaudit eventsconsole log agent configurationconfigurationconsole log agentconsole logging parameterslog agentloggingconsole, toLogging to the console is the easiest event logging option to configure. Associate an output destination of standard out or standard error with the category of events in the event pool to capture: [ivmgrd] logcfg = category:{stdout|stderr}Logging to the console does not use any queuing. The events are written to the console as they are received from the propagation queue. Depending on the queue settings, events might be delayed in the propagation queue.If you are using console output and running a server in the foreground for debugging purposes, you might want to set the propagation queue settings accordingly. For example, set the hi_water parameter to a low value.Defining logcfg entriesSending events to standard errorYou might configure event logging to standard error.Sending events to standard outputYou might capture event logging to standard output.

Sending events to the console

Logging to the console is the easiest event logging option to configure. Associate an output destination of standard out or standard error with the category of events in the event pool to capture:

[ivmgrd]
logcfg = category:{stdout|stderr}

Logging to the console does not use any queuing. The events are written to the console as they are received from the propagation queue. Depending on the queue settings, events might be delayed in the propagation queue.

If you are using console output and running a server in the foreground for debugging purposes, you might want to set the propagation queue settings accordingly. For example, set the hi_water parameter to a low value.

Sending events to standard error
You might configure event logging to standard error.

Sending events to standard output
You might capture event logging to standard output.

Parent topic: Defining logcfg entries

Sending events to standard errorYou might configure event logging to standard error.eventsconsole logstderrstandard error (stderr) for loggingconsole logging parametersstderrEdit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.Locate the stanza that contains the logcfg entries.Define the logcfg entry and specify the event category to log and the destination of standard error. logcfg = category:stderrSave and exit the configuration file.For example, to capture all audit events to standard error, define the following entry in the configuration file: [ivmgrd] logcfg = audit:stderrSending events to the console

Sending events to standard error

You might configure event logging to standard error.

Procedure

Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.

Locate the stanza that contains the logcfg entries.

Define the logcfg entry and specify the event category to log and the destination of standard error.

logcfg = category:stderr

Save and exit the configuration file.

Example

For example, to capture all audit events to standard error, define the following entry in the configuration file:

[ivmgrd]
logcfg = audit:stderr

Parent topic: Sending events to the console

Sending events to standard outputYou might capture event logging to standard output.eventsconsole logstdoutstandard out (stdout) for loggingconsole logging parametersstdoutEdit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.Locate the stanza that contains the logcfg entries.Define the logcfg entry and specify the event category to log and the destination of standard output.logcfg = category:stdoutSave and exit the configuration file.To capture all audit events to standard output, define the following entry in the configuration file: [ivmgrd] logcfg = audit:stdoutSending events to the console

Sending events to standard output

You might capture event logging to standard output.

Procedure

Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.

Locate the stanza that contains the logcfg entries.

Define the logcfg entry and specify the event category to log and the destination of standard output.

logcfg = category:stdout

Save and exit the configuration file.

Results

To capture all audit events to standard output, define the following entry in the configuration file:

[ivmgrd]
logcfg = audit:stdout

Parent topic: Sending events to the console

Configuring file log agentsaudit eventsfile log agent configurationconfigurationconsole log agentfile log agentparametersfilesconfigurationloggingconfigurationfile log agentsTo record events in a file, specify a log file configuration as follows: [ivacld] logcfg = category:file path=file_pathname, flush_interval=num_seconds, rollover_size=number,max_rollover_files=number,log_id=logid, queue_size=number,hi_water=number,buffer_size=number,mode={text|binary}Parameter names can be shortened to any unambiguous name. For example, the hi_water parameter can be shortened to hi.A file is opened only one time. The file opens according to the options in the first configuration entry that is processed when: Multiple configuration entries exist.You want to selectively capture events to the same file.You want to capture events at different points of the event pool hierarchy.After a file was opened, further file configurations can use the following shorthand notation to record events to the same file:[ivacld] logcfg = category:file log_id=logidWriting to a file can be a slow operation relative to the tasks that are generating events. Therefore, events are posted to a file log agent through a second level of queuing. This second level of event queuing is configured like the central event propagation queue, but has different default values.Defining logcfg entriesParameters for file log agentsYou can define the following parameters for file log agents: Sending events to a log fileYou might configure Security Access Manager to send event records to a log file.

Configuring file log agents

To record events in a file, specify a log file configuration as follows:

[ivacld]
logcfg = category:file path=file_pathname, flush_interval=num_seconds,
rollover_size=number,max_rollover_files=number,log_id=logid,
queue_size=number,hi_water=number,buffer_size=number,mode={text|binary}

Parameter names can be shortened to any unambiguous name. For example, the hi_water parameter can be shortened to hi.

A file is opened only one time. The file opens according to the options in the first configuration entry that is processed when:

Multiple configuration entries exist.

You want to selectively capture events to the same file.

You want to capture events at different points of the event pool hierarchy.

After a file was opened, further file configurations can use the following shorthand notation to record events to the same file:

[ivacld]
logcfg = category:file log_id=logid

Writing to a file can be a slow operation relative to the tasks that are generating events. Therefore, events are posted to a file log agent through a second level of queuing. This second level of event queuing is configured like the central event propagation queue, but has different default values.

Parameters for file log agents
You can define the following parameters for file log agents:

Sending events to a log file
You might configure Security Access Manager to send event records to a log file.

Parent topic: Defining logcfg entries

Parameters for file log agentsYou can define the following parameters for file log agents: file log agentparametersbuffer_size parameterfile log agentfile log agentbuffer_sizelogcfg parametersbuffer_sizefile log agentflush_interval parameterfile log agentfile log agentflush_intervallogcfg parametersflush_intervalfile log agenthi_water parameterfile log agentfile log agenthi_waterlogcfg parametershi_waterfile log agentlog_id parameterfile log agentlog_id parameterlogcfg parameterslog_idparametermode parameterfile log agentmode parameterlogcfg parametersmodequeue_size parameterfile log agentfile log agentqueue_sizelogcfg parametersqueue_sizefile log agentpath parameterfile log agentfile log agentpathlogcfg parameterspathfile log agentrollover_size parameterfile log agentrollover_size parameterlogcfg parametersrollover_sizebuffer_size Reduce memory fragmentation and improve the performance of writing to a file by: Not queuing many small events individually to the file log agent.Buffering events into blocks of a nominated size before queuing for writing. The buffer_size parameter specifies the maximum size message that the program attempts to construct by combining smaller events into a large buffer. Buffers consist of only an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is recorded in a buffer of its own, exceeding the configured value. The default buffer size for logging to a file is 0 bytes. This value prevents buffering and each event is handled individually. If a value is specified for the buffer_size parameter, events are packed into buffers of that size before queuing to the file log agent. For example, around 10 events are packed into each buffer that is written to the file when: The value for the buffer_size parameter is set to 2 KB.Events are assumed to be about 256 bytes.This process reduces the number of disk input/outputs (I/Os) that are made while logging to 10 percent of the equivalent non-buffering case. A default queue size of 200 also consumes around 10 times the memory of a default configuration that did no buffering if: The buffer size was 2 KB.The event size was around 200 bytes.This size is because the maximum queue size value has not been changed. However, the size of events being queued has increased tenfold.flush_interval The flush_interval parameter is a multiuse parameter. Ensure that stream buffers are flushed to disk regularly. Configure the frequency with which the server asynchronously forces a flush of the file stream to disk. To configure this frequency, use the flush_interval parameter. The value that is defined for this parameter is 0, < 0, or the flush interval in seconds. Specifying a value of 0 results in the flushing of the buffer every 600 seconds. Specifying a value of < 0 results in the absolute value that is used as the asynchronous flush frequency. However, a stream flush is also forced synchronously after each record is written. Events are consolidated into large buffers that is based on the value of the buffer_size parameter. However, the flush_interval parameter also might affect the size of buffer written. When a flush is scheduled, an in-memory, partially filled buffer is also queued for writing before it completes the buffer fill. The event queue is triggered for processing at the flush interval rate. The trigger enables processing of events that were waiting for longer than the scheduled flush time. Such processing applies to a scenario when the queue does not reach the high water mark between scheduled flushes.hi_water Processing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size that reaches a high water mark on the event queue. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that is consumed by enabling event logging to file. If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible. This setting is not optimal. Use it if you want to ensure that events get to disk as fast as possible. Doing so adversely impacts overall performance.log_id An open log file is associated with a short name identifier to facilitate the recording of events from different categories to the same file. Use the log_id parameter to set the log file identifier (ID) explicitly; otherwise, it is given a default value. If the path parameter is specified, the default value is the configured path name. If the path parameter is not specified, the log ID defaults to the domain component of the event category being captured. For example: logcfg = audit.azn:file implies log_id=audit To capture events to a common file, set the log file ID to a suitable value in a fully optioned file configuration. Then, use the shorthand configuration variant to capture events from additional categories as shown: [aznapi-configuration] logcfg = audit.azn:file path=audit.log, rollover_size=-1,flush_interval=20,log_id=audit, ... logcfg = audit.authn:file log_id=audit Because of the default rules, this configuration is also equivalent to the following specification: [aznapi-configuration] logcfg = audit.azn:file path=audit.log, rollover_size=-1, ... logcfg = audit.authn:file If you construct a configuration where the log ID value does not match any open log file, no events are captured. For example, the following configuration does not record any events because the configuration line that initializes the log file was commented out: [ivacld] #logcfg = audit.azn:file path=azn.log,log_id=azn,... logcfg = audit.authn:file log_id=aznmode Configure the mode parameter to open a file in either text or binary mode. For example: [aznapi-configuration] logcfg = audit.azn:file ... mode={text|binary}, ... Text mode is deprecated on AIX, Linux, and Solaris operating systems. Binary mode on a Windows operating system writes the log file in an AIX, Linux, or Solaris-compatible format.path The path specifies the name and location of a log file. There is no default value, because the value of the log_id parameter takes precedence. An example for the WebSEAL audit trail file on AIX, Linux, and Solaris operating systems is as follows: [aznapi-configuration] logcfg = category:file path=audit.log The directory portion of this path must exist. The log file is created if it does not exist.queue_sizeThere is a delay between events being placed on the queue and the file log agent removing them. The queue_size parameter specifies the maximum size to which the queue is allowed to grow. Consider that a new event is ready to be placed on the queue. Then, if the queue reaches the maximum size, the requesting thread is blocked until space is available in the queue. This process causes the performance of the event propagation thread to slow down to that of the file logging thread. Limiting the queue size for the log agent must be configured with setting the queue size for the central event propagation queue. Unless the event propagation defined by the queue_size parameter is constrained appropriately, memory usage can still grow without bounds. [aznapi-configuration] logcfg = audit.azn:file ... queue_size=number_events, ... The default value is 0. Specifying a value of 0 indicates that no limit is enforced on the growth of the unprocessed event queue. Correspondingly, the event propagation thread is not constrained by the speed of the logging thread. The unrecorded event queue can grow to an unmanageable size if: You are using the default.Events are being generated faster than they can be recorded to file.rollover_size Configure the rollover_size parameter to specify the maximum size to which a log file can grow. The default value is 2000000 bytes. When the size of a log file reaches the specified rollover threshold, the existing file is backed up. The back-up happens to a file of the same name with the current date and time stamp appended. A new log file is then started. The possible rollover size values are interpreted as follows: If the rollover_size value is less than zero, a new log file is created: With each invocation of the process, and Every 24 hours since that instance.If the rollover_size value is equal to zero, the log file grows until it reaches 2 GB and then rolls over. If a log file exists at startup, new data is appended to it.If the rollover_size value is greater than zero, the log file grows until it reaches the lesser of the following values and then rolls over: The specified value2 GBIf a log file exists at startup, new data is appended to it.max_rollover_filesConfigure the max_rollover_files parameter to specify the maximum number of rollover files to be kept on disk. When the number of rollover log files reaches the specified threshold, the oldest log file is deleted. The value of this configuration parameter is interpreted as follows: If the max_rollover_files value is blank or not specified, then no rollover files are deleted.If the max_rollover_files value is equal to zero, then only the current log file is kept, and all rollover log files are deleted.If the max_rollover_files value is greater than zero, then only that number of rollover log files are kept. When the number of rollover log files exceeds max_rollover_files, the oldest log file is deleted.Configuring file log agents

Parameters for file log agents

You can define the following parameters for file log agents:

buffer_size

Reduce memory fragmentation and improve the performance of writing to a file by:

Not queuing many small events individually to the file log agent.

Buffering events into blocks of a nominated size before queuing for writing.

The buffer_size parameter specifies the maximum size message that the program attempts to construct by combining smaller events into a large buffer.

Buffers consist of only an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is recorded in a buffer of its own, exceeding the configured value. The default buffer size for logging to a file is 0 bytes. This value prevents buffering and each event is handled individually.

If a value is specified for the buffer_size parameter, events are packed into buffers of that size before queuing to the file log agent.

For example, around 10 events are packed into each buffer that is written to the file when:

The value for the buffer_size parameter is set to 2 KB.

Events are assumed to be about 256 bytes.

This process reduces the number of disk input/outputs (I/Os) that are made while logging to 10 percent of the equivalent non-buffering case.

A default queue size of 200 also consumes around 10 times the memory of a default configuration that did no buffering if:

The buffer size was 2 KB.

The event size was around 200 bytes.

This size is because the maximum queue size value has not been changed. However, the size of events being queued has increased tenfold.

flush_interval

The flush_interval parameter is a multiuse parameter.

Ensure that stream buffers are flushed to disk regularly. Configure the frequency with which the server asynchronously forces a flush of the file stream to disk. To configure this frequency, use the flush_interval parameter. The value that is defined for this parameter is 0, < 0, or the flush interval in seconds.

Specifying a value of 0 results in the flushing of the buffer every 600 seconds.

Specifying a value of < 0 results in the absolute value that is used as the asynchronous flush frequency. However, a stream flush is also forced synchronously after each record is written.

Events are consolidated into large buffers that is based on the value of the buffer_size parameter. However, the flush_interval parameter also might affect the size of buffer written. When a flush is scheduled, an in-memory, partially filled buffer is also queued for writing before it completes the buffer fill.

The event queue is triggered for processing at the flush interval rate. The trigger enables processing of events that were waiting for longer than the scheduled flush time. Such processing applies to a scenario when the queue does not reach the high water mark between scheduled flushes.

hi_water

Processing of the event queue is scheduled regularly at the configured flush interval. It also is triggered asynchronously by the queue size that reaches a high water mark on the event queue.

The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100.

The transaction rates and the values of these options determine the maximum amount of memory that is consumed by enabling event logging to file.

If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible. This setting is not optimal. Use it if you want to ensure that events get to disk as fast as possible. Doing so adversely impacts overall performance.

log_id

An open log file is associated with a short name identifier to facilitate the recording of events from different categories to the same file.

Use the log_id parameter to set the log file identifier (ID) explicitly; otherwise, it is given a default value. If the path parameter is specified, the default value is the configured path name. If the path parameter is not specified, the log ID defaults to the domain component of the event category being captured. For example:

logcfg = audit.azn:file

implies

log_id=audit

To capture events to a common file, set the log file ID to a suitable value in a fully optioned file configuration. Then, use the shorthand configuration variant to capture events from additional categories as shown:

[aznapi-configuration]
logcfg = audit.azn:file path=audit.log,
     rollover_size=-1,flush_interval=20,log_id=audit,
     ...
logcfg = audit.authn:file log_id=audit

Because of the default rules, this configuration is also equivalent to the following specification:

[aznapi-configuration]
logcfg = audit.azn:file path=audit.log,
     rollover_size=-1,
     ...
logcfg = audit.authn:file

If you construct a configuration where the log ID value does not match any open log file, no events are captured. For example, the following configuration does not record any events because the configuration line that initializes the log file was commented out:

[ivacld]
#logcfg = audit.azn:file path=azn.log,log_id=azn,...
logcfg = audit.authn:file log_id=azn

mode

Configure the mode parameter to open a file in either text or binary mode. For example:

[aznapi-configuration]
logcfg = audit.azn:file
...
mode={text|binary},
...

Text mode is deprecated on AIX, Linux, and Solaris operating systems. Binary mode on a Windows operating system writes the log file in an AIX®, Linux, or Solaris-compatible format.

path

The path specifies the name and location of a log file. There is no default value, because the value of the log_id parameter takes precedence. An example for the WebSEAL audit trail file on AIX, Linux, and Solaris operating systems is as follows:

[aznapi-configuration]
logcfg = category:file path=audit.log

The directory portion of this path must exist. The log file is created if it does not exist.

queue_size

There is a delay between events being placed on the queue and the file log agent removing them. The queue_size parameter specifies the maximum size to which the queue is allowed to grow.

Consider that a new event is ready to be placed on the queue. Then, if the queue reaches the maximum size, the requesting thread is blocked until space is available in the queue. This process causes the performance of the event propagation thread to slow down to that of the file logging thread.

Limiting the queue size for the log agent must be configured with setting the queue size for the central event propagation queue. Unless the event propagation defined by the queue_size parameter is constrained appropriately, memory usage can still grow without bounds.

[aznapi-configuration]
logcfg = audit.azn:file
...
queue_size=number_events,
...

The default value is 0. Specifying a value of 0 indicates that no limit is enforced on the growth of the unprocessed event queue. Correspondingly, the event propagation thread is not constrained by the speed of the logging thread. The unrecorded event queue can grow to an unmanageable size if:

You are using the default.

Events are being generated faster than they can be recorded to file.

rollover_size

Configure the rollover_size parameter to specify the maximum size to which a log file can grow. The default value is 2000000 bytes.

When the size of a log file reaches the specified rollover threshold, the existing file is backed up. The back-up happens to a file of the same name with the current date and time stamp appended. A new log file is then started.

The possible rollover size values are interpreted as follows:

If the rollover_size value is less than zero, a new log file is created:

With each invocation of the process, and

Every 24 hours since that instance.

If the rollover_size value is equal to zero, the log file grows until it reaches 2 GB and then rolls over. If a log file exists at startup, new data is appended to it.

If the rollover_size value is greater than zero, the log file grows until it reaches the lesser of the following values and then rolls over:

The specified value

2 GB

If a log file exists at startup, new data is appended to it.

max_rollover_files

Configure the max_rollover_files parameter to specify the maximum number of rollover files to be kept on disk.

When the number of rollover log files reaches the specified threshold, the oldest log file is deleted.

The value of this configuration parameter is interpreted as follows:

If the max_rollover_files value is blank or not specified, then no rollover files are deleted.

If the max_rollover_files value is equal to zero, then only the current log file is kept, and all rollover log files are deleted.

If the max_rollover_files value is greater than zero, then only that number of rollover log files are kept. When the number of rollover log files exceeds max_rollover_files, the oldest log file is deleted.

Parent topic: Configuring file log agents

Sending events to a log fileYou might configure Security Access Manager to send event records to a log file.file log agentsending event recordsBefore you begin this task, review the information in Configuring file log agents.Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.Locate the stanza that contains the logcfg entries.Specify that the category is to send event records to a log file by using the following format: category:file For example, a category might be to audit authorization events (audit.azn): logcfg=audit.azn:file Specify the path to the log file: path=fully_qualified_path The default directories are: AIX, Linux, and Solaris operating systems/opt/PolicyDirector/logWindows operating systemsC:\Program Files\Tivoli\Policy Director\log\ The default file name depends on the type of logging being completed, such as audit.logSpecify the identifier for the log file: log_id=logid Use the log_id parameter to set the log file identifier (ID) explicitly; otherwise, it is given a default value. If the path parameter is specified, the default value is the configured path name. If the path parameter is not specified, the log ID defaults to the domain component of the event category that is being captured. For example, logcfg=audit.azn:file implies log_id=audit.Specify the maximum size of the log file: rollover_size= value By default is rollover_size=2000000. The rollover size values are interpreted as: If less than zero, a new log file is created with each invocation of the process and every 24 hours from that instance.If equal to zero, no rollover is completed, and the log file grows indefinitely. If a log file exists, new data is appended to it.If greater than zero, a rollover is completed when a log file reaches the configured threshold value. If a log file exists at startup, new data is appended to it.Specify the maximum number of rollover log files: max_rollover_files= value The rollover size values are interpreted as: If the value is blank or not specified, no rollover files are deleted.If equal to zero, only the current log file is kept, and all rollover log files are deleted.If greater than zero, only that number of rollover log files are kept. When the number of rollover log files exceeds max_rollover_files, the oldest log file is deleted.Specify the maximum size of the buffer: buffer_size={0|number_kb} By default, the buffer size for logging to a file is 0 bytes, This buffer size prevents buffering so that each event is handled individually. If a value other than 0 is specified, events are packed into buffers of that size before queuing to the file log agent. Buffers consist of only an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is recorded in a buffer of its own, exceeding the configured value.Specify the maximum number of events to queue in memory: queue_size={0|number_events} By default, the queue size is 0. A zero queue size means that no limit is enforced on the growth of the unprocessed event queue. The requesting thread is blocked until space is available in the queue when: The queue_size is defined as any valid value except 0.The number of events in the queue reaches the defined queue size.A new event is ready to be placed on the queue.Specify the event queue high water mark: hi_water={0|1|number} By default, the event queue high water mark value is two-thirds of the maximum configured queue size.If the maximum queue size is 0, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that is consumed by enabling event logging to file.If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible. This setting is not optimal.Specify the frequency for flushing log file buffers: flush_interval={0|number_seconds}Specify the file mode: mode={text|binary} Binary mode on a Windows operating system writes the log file in an AIX, Linux, or Solaris-compatible format.Text mode is deprecated on AIX, Linux, and Solaris operating systems.Save and exit the configuration file.For example, to configure a file log agent to capture authorization events, the following sample shows the logcfg entry: [aznapi-configuration] logcfg=audit.azn:file path=audit.log, flush_interval=20,rollover_size=2000000,log_id=audit,queue_size=200, hi_water=100,buffer_size=2,mode=textTuning the buffer size with the queue size and the event queue high water mark can improve performance.Configuring file log agents

Sending events to a log file

You might configure Security Access Manager to send event records to a log file.

Before you begin

Before you begin this task, review the information in Configuring file log agents.

Procedure

Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.

Locate the stanza that contains the logcfg entries.

Specify that the category is to send event records to a log file by using the following format:

category:file

For example, a category might be to audit authorization events (audit.azn):

logcfg=audit.azn:file

Specify the path to the log file:

path=fully_qualified_path

The default directories are:

AIX, Linux, and Solaris operating systems

/opt/PolicyDirector/log

Windows operating systems

C:\Program Files\Tivoli\Policy Director\log\

The default file name depends on the type of logging being completed, such as audit.log

Specify the identifier for the log file:

log_id=logid

Use the log_id parameter to set the log file identifier (ID) explicitly; otherwise, it is given a default value. If the path parameter is specified, the default value is the configured path name. If the path parameter is not specified, the log ID defaults to the domain component of the event category that is being captured. For example, logcfg=audit.azn:file implies log_id=audit.

Specify the maximum size of the log file:

rollover_size= value

By default is rollover_size=2000000.

The rollover size values are interpreted as:

If less than zero, a new log file is created with each invocation of the process and every 24 hours from that instance.

If equal to zero, no rollover is completed, and the log file grows indefinitely. If a log file exists, new data is appended to it.

If greater than zero, a rollover is completed when a log file reaches the configured threshold value. If a log file exists at startup, new data is appended to it.

Specify the maximum number of rollover log files:

max_rollover_files= value

The rollover size values are interpreted as:

If the value is blank or not specified, no rollover files are deleted.

If equal to zero, only the current log file is kept, and all rollover log files are deleted.

If greater than zero, only that number of rollover log files are kept. When the number of rollover log files exceeds max_rollover_files, the oldest log file is deleted.

Specify the maximum size of the buffer:

buffer_size={0|number_kb}

By default, the buffer size for logging to a file is 0 bytes, This buffer size prevents buffering so that each event is handled individually. If a value other than 0 is specified, events are packed into buffers of that size before queuing to the file log agent.

Buffers consist of only an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is recorded in a buffer of its own, exceeding the configured value.

Specify the maximum number of events to queue in memory:

queue_size={0|number_events}

By default, the queue size is 0. A zero queue size means that no limit is enforced on the growth of the unprocessed event queue. The requesting thread is blocked until space is available in the queue when:

The queue_size is defined as any valid value except 0.

The number of events in the queue reaches the defined queue size.

A new event is ready to be placed on the queue.

Specify the event queue high water mark:

hi_water={0|1|number}

By default, the event queue high water mark value is two-thirds of the maximum configured queue size.

If the maximum queue size is 0, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that is consumed by enabling event logging to file.

If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible. This setting is not optimal.

Specify the frequency for flushing log file buffers:

flush_interval={0|number_seconds}

Specify the file mode:

mode={text|binary}

Binary mode on a Windows operating system writes the log file in an AIX®, Linux, or Solaris-compatible format.

Text mode is deprecated on AIX, Linux, and Solaris operating systems.

Save and exit the configuration file.

Example

For example, to configure a file log agent to capture authorization events, the following sample shows the logcfg entry:

[aznapi-configuration]
logcfg=audit.azn:file path=audit.log,
flush_interval=20,rollover_size=2000000,log_id=audit,queue_size=200,
hi_water=100,buffer_size=2,mode=text

Tuning the buffer size with the queue size and the event queue high water mark can improve performance.

Parent topic: Configuring file log agents

Configuring remote log agentsaudit eventsremote log agent configurationconfigurationremote log agentremote log agentparametersloggingconfigurationremote log agentsremote logging parametersremote server, send events toremote logging parametersConfigure the remote log agent to send events to a remote authorization server for recording. For example: [aznapi-configuration] logcfg = category:remote buffer_size=size, compress={yes|no},error_retry=timeout,path=name, flush_interval=number_seconds,rebind_retry=timeout, server=hostname,port=number,dn=identity, queue_size=number,hi_water=numberParameter names can be shortened to any unambiguous name. For example, the hi_water parameter can be shortened to hi.Requests to log an event remotely are accepted on a best effort basis only. If the remote authorization server is not available, captured events are cached locally and relayed at a later date, if and when the server becomes available.Only one remote logging connection is established to a remote authorization server. Consider the case where multiple configuration entries are made to: Selectively capture events,Capture events at different points of the event pool hierarchy, andTo the same remote server.Then, the remote connection is established according to the options of the first remote configuration entry processed. Multiple remote connections can be configured to log to different remote authorization servers.Events received at the remote authorization server are placed in the event pool of that server. The events are placed in a different location from where they were originally captured on the client system. All events entering a host through the remote logging service are placed in a category constructed in the following manner: remote.client-category-domain.hostname.program The short name version of the host name is shown in some of the examples, however, the fully qualified host name is often required. To obtain system configuration information, you can use the gethostbyname command. To relay events remotely on host amazon, you might use this example: [aznapi-configuration] logcfg = audit:remote buffer=2000,compress=y, error=2,path=remote.cache,rebind=600,server=timelord,port=7136Defining logcfg entriesParameters for remote log agentsYou can define the following parameters for remote log agents: Sending events to a remote authorization serverYou might configure Security Access Manager to send event records to a remote authorization server.

Configuring remote log agents

Configure the remote log agent to send events to a remote authorization server for recording. For example:

[aznapi-configuration]
logcfg = category:remote buffer_size=size,
     compress={yes|no},error_retry=timeout,path=name,
     flush_interval=number_seconds,rebind_retry=timeout,
     server=hostname,port=number,dn=identity,
     queue_size=number,hi_water=number

Parameter names can be shortened to any unambiguous name. For example, the hi_water parameter can be shortened to hi.

Requests to log an event remotely are accepted on a best effort basis only. If the remote authorization server is not available, captured events are cached locally and relayed at a later date, if and when the server becomes available.

Only one remote logging connection is established to a remote authorization server. Consider the case where multiple configuration entries are made to:

Selectively capture events,

Capture events at different points of the event pool hierarchy, and

To the same remote server.

Then, the remote connection is established according to the options of the first remote configuration entry processed. Multiple remote connections can be configured to log to different remote authorization servers.

Events received at the remote authorization server are placed in the event pool of that server. The events are placed in a different location from where they were originally captured on the client system. All events entering a host through the remote logging service are placed in a category constructed in the following manner:

remote.client-category-domain.hostname.program

Note: The short name version of the host name is shown in some of the examples, however, the fully qualified host name is often required. To obtain system configuration information, you can use the gethostbyname command.

To relay events remotely on host amazon, you might use this example:

[aznapi-configuration] logcfg = audit:remote buffer=2000,compress=y,
error=2,path=remote.cache,rebind=600,server=timelord,port=7136

Parameters for remote log agents
You can define the following parameters for remote log agents:

Sending events to a remote authorization server
You might configure Security Access Manager to send event records to a remote authorization server.

Parent topic: Defining logcfg entries

Parameters for remote log agentsYou can define the following parameters for remote log agents: remote log agentparametersbuffer_size parameterremote log agentremote log agentbuffer_sizelogcfg parametersbuffer_sizeremote log agentcompress parameterremote log agentcompress parameterlogcfg parameterscompressdn parameterremote log agentdn parameterlogcfg parametersdnerror parameterremote log agenterror parameterlogcfg parameterserrorflush_interval parameterremote log agentremote log agentflush_intervallogcfg parametersflush_intervalremote log agenthi_water parameterremote log agentremote log agenthi_waterlogcfg parametershi_waterremote log agentserver parameterremote log agentsremote log agentserver parameterlogcfg parametersserverpath parameterremote log agentremote log agentpathlogcfg parameterspathremote log agentport parameterremote log agentport parameterlogcfg parametersportqueue_size parameterremote log agentremote log agentqueue_sizelogcfg parametersqueue_sizeremote log agentrebind_retry parameterremote log agentrebind_retry parameterlogcfg parametersrebind_retrybuffer_size To reduce network traffic, events are buffered into blocks of the nominated size before relaying to the remote server. The buffer_size parameter specifies the maximum size message that the local program attempts to construct by combining smaller events into a large buffer. Buffers consist only of an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is sent in a buffer of its own, exceeding the configured value.The default value is 1024 bytes.compress Security Access Manager events are principally text messages. To reduce network traffic, use the compress parameter to compress buffers before transmission and expand on reception.The default value is no.dn To establish mutual authentication of the remote server, a distinguished name (DN) must be configured. The DN can be checked against the name that is returned in the remote server’s certificate.The default value is a null string. Explicitly specifying an empty string or using the default value enables the logging client to request a remote server connection with any server that is listening.Specifying a value for the dn parameter limits successful connection to a specific server, such as: dn="cn=ivacld/timelord.testnet.tivoli.com,o=policy director,c=us"A distinguished name must be specified as a string that is enclosed by double quotation marks.error If a send to a remote service fails, the system tries again. Before the system tries again, the system waits for the error retry timeout in seconds. If the attempt to try again fails: The link is recorded.The given event and future events are saved.Events are saved in the local event cache file until the remote service is available again. The default value is 2 seconds.flush_interval Events can sit in memory for a long time if: Events are being consolidated into large buffers.There is less logging activity.Further, events can sit in memory before being: Forwarded to the remote server.Written to the cache file.The flush_interval parameter limits the time that a process waits to fill a consolidation buffer. The default value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.hi_water The hi_water parameter for a remote logging connection is like the one specified for logging to a file.path Configure the path parameter to specify the location of a cache file on the local host. The cache file name defaults to ./server.cache, where server is the name of the remote server that is being logged to.If the running process cannot establish communication with the remote server, or the link fails during operation, event recording switches to storing events in the specified file. The switch lasts until the server becomes available again. When the server is available, events are drained from the disk cache and relayed to the remote server.For example, suppose that the path value is as follows:path=pdmgrd_remote.cacheThe log file is created if it does not exist. The size of this file is not bound, and it does not have any rollover capability. If a remote server is not accessible for sufficient time, you might run out of disk space.port Configure the port parameter to specify the port that the remote authorization server listens on for remote logging requests. The default value is port 7136.queue_size The queue_size parameter for a remote logging connection is like the one specified for logging to a file.rebind_retry If the remote authorization server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds. rebind_retry=number_seconds The default rebind retry timeout value is 300 seconds.server The remote logging services are offered by the authorization service. The server parameter nominates the hosts to which the authorization server process is bound for event recording. server=hostnameConfiguring remote log agents

Parameters for remote log agents

You can define the following parameters for remote log agents:

buffer_size

To reduce network traffic, events are buffered into blocks of the nominated size before relaying to the remote server. The buffer_size parameter specifies the maximum size message that the local program attempts to construct by combining smaller events into a large buffer. Buffers consist only of an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is sent in a buffer of its own, exceeding the configured value.

The default value is 1024 bytes.

compress

Security Access Manager events are principally text messages. To reduce network traffic, use the compress parameter to compress buffers before transmission and expand on reception.

The default value is no.

dn

To establish mutual authentication of the remote server, a distinguished name (DN) must be configured. The DN can be checked against the name that is returned in the remote server’s certificate.

The default value is a null string. Explicitly specifying an empty string or using the default value enables the logging client to request a remote server connection with any server that is listening.

Specifying a value for the dn parameter limits successful connection to a specific server, such as:

dn="cn=ivacld/timelord.testnet.tivoli.com,o=policy director,c=us"

A distinguished name must be specified as a string that is enclosed by double quotation marks.

error

If a send to a remote service fails, the system tries again. Before the system tries again, the system waits for the error retry timeout in seconds. If the attempt to try again fails:

The link is recorded.

The given event and future events are saved.

Events are saved in the local event cache file until the remote service is available again.

The default value is 2 seconds.

flush_interval

Events can sit in memory for a long time if:

Events are being consolidated into large buffers.

There is less logging activity.

Further, events can sit in memory before being:

Forwarded to the remote server.

Written to the cache file.

The flush_interval parameter limits the time that a process waits to fill a consolidation buffer.

The default value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.

hi_water

The hi_water parameter for a remote logging connection is like the one specified for logging to a file.

path

Configure the path parameter to specify the location of a cache file on the local host. The cache file name defaults to ./server.cache, where server is the name of the remote server that is being logged to.

If the running process cannot establish communication with the remote server, or the link fails during operation, event recording switches to storing events in the specified file. The switch lasts until the server becomes available again. When the server is available, events are drained from the disk cache and relayed to the remote server.

For example, suppose that the path value is as follows:

path=pdmgrd_remote.cache

The log file is created if it does not exist. The size of this file is not bound, and it does not have any rollover capability. If a remote server is not accessible for sufficient time, you might run out of disk space.

port

Configure the port parameter to specify the port that the remote authorization server listens on for remote logging requests.

The default value is port 7136.

queue_size

The queue_size parameter for a remote logging connection is like the one specified for logging to a file.

rebind_retry

If the remote authorization server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds.

rebind_retry=number_seconds

The default rebind retry timeout value is 300 seconds.

server

The remote logging services are offered by the authorization service. The server parameter nominates the hosts to which the authorization server process is bound for event recording.

server=hostname

Parent topic: Configuring remote log agents

Sending events to a remote authorization serverYou might configure Security Access Manager to send event records to a remote authorization server.remote log agentsending event recordsBefore you begin this task, review the information in Configuring remote log agents.Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.Locate the stanza that contains the logcfg entries.Specify that the category is to send event records to a remote server using the format category:remote. For example, a category might be to audit authorization events ( audit ) :logcfg=audit:remote Specify the maximum buffer size. This buffer size is the maximum size message that the local program attempts to construct by combining smaller events into a large buffer: buffer_size={0|number_bytes}If a number_bytes value is specified, events are packed into buffers of that size before being relayed to the remote server. By default, the buffer size before relaying to the remote server is 1024 bytes.Buffers consist of only an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is recorded in a buffer of its own, exceeding the configured value.Specify the frequency for flushing log file buffers: flush_interval={0|number_seconds}The flush_interval parameter limits the time that a process waits to fill a consolidation buffer.By default, the flush interval value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.Specify the maximum number of events to queue: queue_size={0|number_events} By default, the queue size is 0. A zero queue size means that no limit is enforced on the growth of the unprocessed event queue. The requesting thread is blocked until space is available in the queue if: The maximum value for number_events is specified.The maximum value for number_events is reached.A new event is ready to be placed on the queue.Specify the event queue high water mark: hi_water={0|1|number}By default, the event queue high water mark value is a number that represents two-thirds of the maximum configured queue size.If the maximum queue size is 0, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that is consumed by enabling event logging to file.If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible. This setting is not optimal.Specify whether you want to compress buffers before transmission and expand on reception: compress={yes|no} By default, the compress value is no to disable.Specify the time to wait whenever a send to a remote service fails and an error occurs: error=secondsBy default, the error retry timeout is 2 seconds.Specify the cache file location: path=fully_qualified_pathThe file name is server_name_remote.cache. For example: pdmgrd_remote.cacheThe default file name depends on the type of logging being performed, such as audit.logSpecify the time between attempts to rebind (sign on): rebind_retry=number_secondsBy default, the rebind retry timeout value is 300 seconds.Specify the host name of the remote authorization server: server=hostnameSpecify the remote server port number: port=authorization server port By default, the port number value is 7136.Specify the remote server distinguished name to establish mutual authentication of the remote server: dn="distinguished_name"The default value for the dn parameter is a null string. Explicitly specifying an empty string or using the default value enables the logging client to request a remote server connection with any server listening.The dn parameter value limits a successful connection to a specific server, for example: dn="cn=ivacld/timelord.tivoli.com,o=policy director,c=us" A distinguished name must be specified as a string enclosed by double quotation marks.Save and exit the configuration file.This example sends event records to the remote timelord server: [aznapi-configuration] logcfg = audit:remote buffer=2000,compress=y,error=2 path=remote.cache,rebind=600,server=timelord,port=7136 dn="cn=ivacld/timelord.tivoli.com,o=policy director,c=us"Configuring remote log agents

Sending events to a remote authorization server

You might configure Security Access Manager to send event records to a remote authorization server.

Before you begin

Before you begin this task, review the information in Configuring remote log agents.

Procedure

Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.

Locate the stanza that contains the logcfg entries.

Specify that the category is to send event records to a remote server using the format category:remote.

For example, a category might be to audit authorization events ( audit ) :

logcfg=audit:remote

Specify the maximum buffer size. This buffer size is the maximum size message that the local program attempts to construct by combining smaller events into a large buffer:

buffer_size={0|number_bytes}

If a number_bytes value is specified, events are packed into buffers of that size before being relayed to the remote server. By default, the buffer size before relaying to the remote server is 1024 bytes.

Buffers consist of only an integral number of events; events are not split across buffers. If any individual event exceeds that maximum configured size, the large event is recorded in a buffer of its own, exceeding the configured value.

Specify the frequency for flushing log file buffers:

flush_interval={0|number_seconds}

The flush_interval parameter limits the time that a process waits to fill a consolidation buffer.

By default, the flush interval value is 20 seconds. A flush interval of 0 is not allowed. Specifying a value of 0 results in the buffer being flushed every 600 seconds.

Specify the maximum number of events to queue:

queue_size={0|number_events}

By default, the queue size is 0. A zero queue size means that no limit is enforced on the growth of the unprocessed event queue. The requesting thread is blocked until space is available in the queue if:

The maximum value for number_events is specified.

The maximum value for number_events is reached.

A new event is ready to be placed on the queue.

Specify the event queue high water mark:

hi_water={0|1|number}

By default, the event queue high water mark value is a number that represents two-thirds of the maximum configured queue size.

If the maximum queue size is 0, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that is consumed by enabling event logging to file.

If the event queue high water mark is set to 1, every event queued is relayed to the log agent as soon as possible. This setting is not optimal.

Specify whether you want to compress buffers before transmission and expand on reception:

compress={yes|no}

By default, the compress value is no to disable.

Specify the time to wait whenever a send to a remote service fails and an error occurs:

error=seconds

By default, the error retry timeout is 2 seconds.

Specify the cache file location:

path=fully_qualified_path

The file name is server_name_remote.cache. For example: pdmgrd_remote.cache

The default file name depends on the type of logging being performed, such as audit.log

Specify the time between attempts to rebind (sign on):

rebind_retry=number_seconds

By default, the rebind retry timeout value is 300 seconds.

Specify the host name of the remote authorization server:

server=hostname

Specify the remote server port number:

port=authorization server port

By default, the port number value is 7136.

Specify the remote server distinguished name to establish mutual authentication of the remote server:

dn="distinguished_name"

The default value for the dn parameter is a null string. Explicitly specifying an empty string or using the default value enables the logging client to request a remote server connection with any server listening.

The dn parameter value limits a successful connection to a specific server, for example:

dn="cn=ivacld/timelord.tivoli.com,o=policy director,c=us"

A distinguished name must be specified as a string enclosed by double quotation marks.

Save and exit the configuration file.

Example

This example sends event records to the remote timelord server:

[aznapi-configuration] logcfg = audit:remote buffer=2000,compress=y,error=2
path=remote.cache,rebind=600,server=timelord,port=7136
dn="cn=ivacld/timelord.tivoli.com,o=policy director,c=us"

Parent topic: Configuring remote log agents

Configuring remote syslog agentsUse the logcfg entry to configure the remote syslog agent to send events to a remote syslog server for recording. audit eventsremote syslog agent configurationconfigurationremote syslog agentremote syslog agentparametersloggingconfigurationremote syslog agentsremote syslog parametersremote syslog serversend events toremote syslog parametersFor example: [aznapi-configuration] logcfg = category:rsyslog,error_retry=timeout,log_id=id, path=name,flush_interval=number_seconds,max_event_len=length, rebind_retry=timeout,server=hostname,port=number, ssl_keyfile=key_file,ssl_label=label,ssl_stashfile=stash_file, queue_size=number,hi_water=numberThe agent accepts requests to log an event remotely on a best effort basis only. If the remote syslog server is not available, the agent buffers events in a local cache file. When the server becomes available again, the agent sends the events to the server.Caching does not occur if you configure the agent to use clear text communication with the syslog server. Clear text communication occurs over the User Datagram Protocol (UDP), which does not guarantee message delivery. In this configuration, the network layer does not notify the agent if the server does not receive the event. This means that events can be lost if the remote syslog server becomes unavailable.If you do not want to use clear text communication, you can configure SSL. For SSL communication, the agent uses the TLS Cipher Suite to encrypt the data.Defining logcfg entriesParameters for remote syslog agentsYou can define the following parameters for remote syslog agents: Sending events to a remote syslog serverYou can configure Security Access Manager to send event records to a remote syslog server.

Configuring remote syslog agents

Use the logcfg entry to configure the remote syslog agent to send events to a remote syslog server for recording.

For example:

[aznapi-configuration]
logcfg = category:rsyslog,error_retry=timeout,log_id=id,
					path=name,flush_interval=number_seconds,max_event_len=length,
					rebind_retry=timeout,server=hostname,port=number,
					ssl_keyfile=key_file,ssl_label=label,ssl_stashfile=stash_file,
					queue_size=number,hi_water=number

The agent accepts requests to log an event remotely on a best effort basis only. If the remote syslog server is not available, the agent buffers events in a local cache file. When the server becomes available again, the agent sends the events to the server.

Caching does not occur if you configure the agent to use clear text communication with the syslog server. Clear text communication occurs over the User Datagram Protocol (UDP), which does not guarantee message delivery. In this configuration, the network layer does not notify the agent if the server does not receive the event. This means that events can be lost if the remote syslog server becomes unavailable.

Note: If you do not want to use clear text communication, you can configure SSL. For SSL communication, the agent uses the TLS Cipher Suite to encrypt the data.

Parameters for remote syslog agents
You can define the following parameters for remote syslog agents:

Sending events to a remote syslog server
You can configure Security Access Manager to send event records to a remote syslog server.

Parent topic: Defining logcfg entries

Parameters for remote syslog agentsYou can define the following parameters for remote syslog agents: remote syslog agentparameterserror_retry parameterremote syslog agenterror parameterlogcfg parameterserrorflush_interval parameterremote syslog agentremote syslog agentflush_intervallogcfg parametersflush_intervalremote syslog agenthi_water parameterremote syslog agentremote syslog agenthi_waterlogcfg parametershi_waterremote syslog agentlog_id remote syslog agentremote syslog agentlog_idlogcfg parameterslog_idremote syslog agentmax_event_len parameterremote syslog agentmax_event_lenlogcfg parametersmax_event_lenpath parameterremote syslog agentremote syslog agentpathlogcfg parameterspathremote syslog agentport parameterremote syslog agentport parameterlogcfg parametersportqueue_size parameterremote syslog agentremote syslog agentqueue_sizelogcfg parametersqueue_sizeremote syslog agentrebind_retry parameterremote syslog agentrebind_retry parameterlogcfg parametersrebind_retryserver parameterremote syslog agentsremote syslog agentserver parameterlogcfg parametersserverssl_keyfile parameterremote syslog agentssl_keyfile parameterlogcfg parametersssl_keyfilessl_label parameterremote syslog agentssl_label parameterlogcfg parametersssl_labelssl_stashfile parameterremote syslog agentssl_stashfile parameterlogcfg parametersssl_stashfileerror_retry If a message sent to a remote syslog service fails, the system tries again. Before trying again, the system waits for the error_retry timeout in seconds. If the next attempt fails, the agent saves the current event and future events in the local cache file until the remote service is available again. The default value is 2 seconds.flush_interval Events can sit in memory for a long time if there is only a small amount of logging activity.The flush_interval parameter limits the time a process waits to fill a consolidation buffer. The default value is 20 seconds. You cannot use a flush interval of 0 seconds. If you specify a value of 0, the agent flushes the buffer every 600 seconds.hi_water Processing of the event queue is scheduled regularly at the configured flush interval. It is also triggered asynchronously when the queue size reaches a high water mark on the event queue. Use the hi_water parameter to define this high water mark. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that the agent uses for logging events to file. If the event queue high water mark is set to 1, WebSEAL relays every queued event to the log agent as soon as possible. This setting is not optimal. A setting of 1 ensures that events get to disk as fast as possible, but this configuration adversely impacts overall performance.log_id The log_id parameter defines the name of the application that the syslog agent includes in the messages sent to the remote syslog server. This field is mandatory. max_event_len The max_event_len parameter specifies the maximum length of an event that the syslog agent transmits to the remote syslog server. If the event text is longer than the configured length, the agent truncates the message to the maximum event length. If the maximum event length is zero, the agent does not truncate the event text. If you are using clear text communication to transmit the event, set the max_event_len parameter to a value less than the maximum transmission unit (MTU). That is, use a value less than the MTU for the network path to the server to avoid fragmentation of the event.path Configure the path parameter to specify the location of a cache file on the local host. The cache file name defaults to ./log_id.cache, where log_id is the value of the log_id parameter.Event recording switches to storing events in the specified file if any of the following scenarios occur: The running process cannot establish communication with the remote server.The link fails during operation.The switch lasts until the server becomes available again. When the server is available, the agent removes the events from the disk cache and relays them to the remote server.For example, suppose that the path value for pdmgrd on AIX, Linux, and Solaris operating systems is as follows:path=pdmgrd_rsyslog.cacheThe directory portion of this path must exist. If the log file does not exist, the agent creates the file. The size of this file is not bound, and it does not have any rollover capability. If a syslog server is not accessible for a sufficient time, you might run out of disk space.port Configure the port parameter to specify the port that the remote syslog server listens on for remote logging requests. The default port value is 514 for clear text communication and 6514 for SSL communication.queue_sizeThere is a delay between placing events on the queue and their removal by the file log agent. The queue_size parameter specifies the maximum size of the queue. Consider that a new event is ready to be placed on the queue. If the queue reaches the maximum size, the requesting thread is blocked until space is available in the queue.This process causes the performance of the event propagation thread to slow down to the speed of the file logging thread.You must use the queue_size parameter to limit the central event propagation queue size. If not, memory usage by the log agent can grow without bounds. [aznapi-configuration] logcfg = audit.azn:rsyslog ... queue_size=number_events, ...The default value is 0. Specifying a value of 0 indicates that there is no limit to the growth of the unprocessed event queue. In this case, the speed of the logging thread does not constrain the event propagation thread. The unrecorded event queue can grow to an unmanageable size if:You are using the default value.Events are being generated faster than they can be recorded to file. rebind_retry If the remote syslog server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds. rebind_retry=number_seconds The default rebind_retry timeout value is 300 seconds.server The remote logging services are offered by the remote syslog server. The server parameter nominates the host to which the agent is bound for event recording. server=hostnamessl_keyfile The name of the GSKit key database file that contains the CA certificate. The logging agent uses the CA certificate to establish a secure connection with the remote syslog server over SSL. If you do not configure this value, the logging agent uses clear text that is not encrypted to communicate with the remote syslog server.ssl_label The name of the certificate that the logging agent presents to the remote syslog server to establish a secure connection. If you do not configure this field, the agent uses the default certificate from the key database.ssl_stashfile The name of the GSKit stash file that contains the password for the ssl-keyfile database. This field is mandatory if you specify a value for the ssl-keyfile field.Configuring remote syslog agentsUse the logcfg entry to configure the remote syslog agent to send events to a remote syslog server for recording.

Parameters for remote syslog agents

You can define the following parameters for remote syslog agents:

error_retry

If a message sent to a remote syslog service fails, the system tries again. Before trying again, the system waits for the error_retry timeout in seconds. If the next attempt fails, the agent saves the current event and future events in the local cache file until the remote service is available again.

The default value is 2 seconds.

flush_interval

Events can sit in memory for a long time if there is only a small amount of logging activity.

The flush_interval parameter limits the time a process waits to fill a consolidation buffer.

The default value is 20 seconds. You cannot use a flush interval of 0 seconds. If you specify a value of 0, the agent flushes the buffer every 600 seconds.

hi_water

Processing of the event queue is scheduled regularly at the configured flush interval. It is also triggered asynchronously when the queue size reaches a high water mark on the event queue.

Use the hi_water parameter to define this high water mark. The default value is two-thirds of the maximum configured queue size. If the maximum queue size is zero, the high water mark is set to a default of 100.

The transaction rates and the values of these options determine the maximum amount of memory that the agent uses for logging events to file.

If the event queue high water mark is set to 1, WebSEAL relays every queued event to the log agent as soon as possible. This setting is not optimal. A setting of 1 ensures that events get to disk as fast as possible, but this configuration adversely impacts overall performance.

log_id

The log_id parameter defines the name of the application that the syslog agent includes in the messages sent to the remote syslog server. This field is mandatory.

max_event_len

The max_event_len parameter specifies the maximum length of an event that the syslog agent transmits to the remote syslog server.

If the event text is longer than the configured length, the agent truncates the message to the maximum event length. If the maximum event length is zero, the agent does not truncate the event text.

If you are using clear text communication to transmit the event, set the max_event_len parameter to a value less than the maximum transmission unit (MTU). That is, use a value less than the MTU for the network path to the server to avoid fragmentation of the event.

path

Configure the path parameter to specify the location of a cache file on the local host. The cache file name defaults to ./log_id.cache, where log_id is the value of the log_id parameter.

Event recording switches to storing events in the specified file if any of the following scenarios occur:

The running process cannot establish communication with the remote server.

The link fails during operation.

The switch lasts until the server becomes available again. When the server is available, the agent removes the events from the disk cache and relays them to the remote server.

For example, suppose that the path value for pdmgrd on AIX, Linux, and Solaris operating systems is as follows:

path=pdmgrd_rsyslog.cache

The directory portion of this path must exist. If the log file does not exist, the agent creates the file. The size of this file is not bound, and it does not have any rollover capability. If a syslog server is not accessible for a sufficient time, you might run out of disk space.

port

Configure the port parameter to specify the port that the remote syslog server listens on for remote logging requests.

The default port value is 514 for clear text communication and 6514 for SSL communication.

queue_size

There is a delay between placing events on the queue and their removal by the file log agent. The queue_size parameter specifies the maximum size of the queue. Consider that a new event is ready to be placed on the queue. If the queue reaches the maximum size, the requesting thread is blocked until space is available in the queue.

This process causes the performance of the event propagation thread to slow down to the speed of the file logging thread.

You must use the queue_size parameter to limit the central event propagation queue size. If not, memory usage by the log agent can grow without bounds.

[aznapi-configuration]
logcfg = audit.azn:rsyslog
...
queue_size=number_events,
...

The default value is 0. Specifying a value of 0 indicates that there is no limit to the growth of the unprocessed event queue. In this case, the speed of the logging thread does not constrain the event propagation thread. The unrecorded event queue can grow to an unmanageable size if:

You are using the default value.

Events are being generated faster than they can be recorded to file.

rebind_retry

If the remote syslog server is unavailable, the log agent attempts to rebind to this server at this frequency in number of seconds.

rebind_retry=number_seconds

The default rebind_retry timeout value is 300 seconds.

server

The remote logging services are offered by the remote syslog server. The server parameter nominates the host to which the agent is bound for event recording.

server=hostname

ssl_keyfile

The name of the GSKit key database file that contains the CA certificate. The logging agent uses the CA certificate to establish a secure connection with the remote syslog server over SSL.

If you do not configure this value, the logging agent uses clear text that is not encrypted to communicate with the remote syslog server.

ssl_label

The name of the certificate that the logging agent presents to the remote syslog server to establish a secure connection.

If you do not configure this field, the agent uses the default certificate from the key database.

ssl_stashfile

The name of the GSKit stash file that contains the password for the ssl-keyfile database. This field is mandatory if you specify a value for the ssl-keyfile field.

Parent topic: Configuring remote syslog agents

Sending events to a remote syslog serverYou can configure Security Access Manager to send event records to a remote syslog server.remote log agentsending event recordsBefore you begin this task, review the information in Configuring remote syslog agentsUse the logcfg entry to configure the remote syslog agent to send events to a remote syslog server for recording. .Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.Locate the stanza that contains the logcfg entries.Specify that the category is to send event records to a remote server by using the format category:rsyslog. For example, a category that audits authorization events (audit):logcfg=audit:rsyslog Specify the frequency for flushing log file buffers: flush_interval={0|number_seconds}The flush_interval parameter limits the time a process waits to fill a consolidation buffer.By default, the flush interval value is 20 seconds. You cannot use a flush interval of 0 seconds. If you specify a value of 0, the agent flushes the buffer every 600 seconds.Specify the maximum number of events to queue: queue_size={0|number_events} By default, the queue size is 0. A zero queue size means that the agent does not limit the growth of the unprocessed event queue. The requesting thread is blocked until space is available in the queue if: The maximum value for number_events is specified.The maximum value for number_events is reached.A new event is ready to be placed on the queue.Specify the event queue high water mark: hi_water={0|1|number}By default, the event queue high water mark value is a number that represents two-thirds of the maximum configured queue size.If the maximum queue size is 0, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that the agent uses for logging events to file.If the event queue high water mark is set to 1, WebSEAL relays every queued event to the log agent as soon as possible. This setting is not optimal.Specify the time to wait whenever a send to a remote service fails and an error occurs: error_retry=secondsBy default, the error_retry timeout is 2 seconds.Specify the cache file location: path=fully_qualified_pathThe default cache file name is ./log_id.cache. For example: rsyslog.cacheThe directory portion of this path must exist. If the log file does not exist, the agent creates the file. Specify the time between attempts to rebind (sign on): rebind_retry=number_secondsBy default, the rebind_retry timeout value is 300 seconds.Specify the host name of the remote syslog server: server=hostnameSpecify the remote server port number: port=rsyslog_port The default port number is 514 for clear text communication and 6514 for SSL communication.Specify the application name that the syslog agent includes in the messages sent to the remote server: log_id=nameSpecify the maximum length of an event that the agent transmits to the remote syslog server. If the event text is longer than this configured value, the agent truncates the message to the maximum event length. If the maximum event length is 0, the agent does not truncate the event text. max_event_len=lengthIf you are using clear text communication to transmit the event, set the max_event_len parameter to a value less than the maximum transmission unit (MTU). Use a value less than the MTU for the network path to the server to avoid fragmentation of the event.If you require SSL communication with the remote server, you must specify the SSL keyfile: ssl_keyfile=key_file If you are using SSL communication, you can use ssl_label to specify the certificate name: If you do not configure a value for this field, the agent uses the default certificate from the key database.ssl_label=my_label If you require SSL communication with the remote server, you must specify the SSL stash file: ssl_stashfile=stash_file This example sends event records to the remote timelord server: [aznapi-configuration] logcfg = audit:rsyslog error_retry=2,path=rsyslog.cache, rebind_retry=600,server=timelord,port=514,log_id=webseal-instanceConfiguring remote syslog agentsUse the logcfg entry to configure the remote syslog agent to send events to a remote syslog server for recording.

Sending events to a remote syslog server

You can configure Security Access Manager to send event records to a remote syslog server.

Before you begin

Before you begin this task, review the information in Configuring remote syslog agents.

Procedure

Edit the appropriate server configuration file. Each server provides its own stanza entry values in its configuration file.

Locate the stanza that contains the logcfg entries.

Specify that the category is to send event records to a remote server by using the format category:rsyslog.

For example, a category that audits authorization events (audit):

logcfg=audit:rsyslog

Specify the frequency for flushing log file buffers:

flush_interval={0|number_seconds}

The flush_interval parameter limits the time a process waits to fill a consolidation buffer.

By default, the flush interval value is 20 seconds. You cannot use a flush interval of 0 seconds. If you specify a value of 0, the agent flushes the buffer every 600 seconds.

Specify the maximum number of events to queue:

queue_size={0|number_events}

By default, the queue size is 0. A zero queue size means that the agent does not limit the growth of the unprocessed event queue. The requesting thread is blocked until space is available in the queue if:

The maximum value for number_events is specified.

The maximum value for number_events is reached.

A new event is ready to be placed on the queue.

Specify the event queue high water mark:

hi_water={0|1|number}

By default, the event queue high water mark value is a number that represents two-thirds of the maximum configured queue size.

If the maximum queue size is 0, the high water mark is set to a default of 100. The transaction rates and the values of these options determine the maximum amount of memory that the agent uses for logging events to file.

If the event queue high water mark is set to 1, WebSEAL relays every queued event to the log agent as soon as possible. This setting is not optimal.

Specify the time to wait whenever a send to a remote service fails and an error occurs:

error_retry=seconds

By default, the error_retry timeout is 2 seconds.

Specify the cache file location:

path=fully_qualified_path

The default cache file name is ./log_id.cache. For example: rsyslog.cache

Note: The directory portion of this path must exist. If the log file does not exist, the agent creates the file.

Specify the time between attempts to rebind (sign on):

rebind_retry=number_seconds

By default, the rebind_retry timeout value is 300 seconds.

Specify the host name of the remote syslog server:

server=hostname

Specify the remote server port number:

port=rsyslog_port

The default port number is 514 for clear text communication and 6514 for SSL communication.

Specify the application name that the syslog agent includes in the messages sent to the remote server:

log_id=name

Specify the maximum length of an event that the agent transmits to the remote syslog server. If the event text is longer than this configured value, the agent truncates the message to the maximum event length. If the maximum event length is 0, the agent does not truncate the event text.

max_event_len=length

Note: If you are using clear text communication to transmit the event, set the max_event_len parameter to a value less than the maximum transmission unit (MTU). Use a value less than the MTU for the network path to the server to avoid fragmentation of the event.

Optional: If you require SSL communication with the remote server, you must specify the SSL keyfile:

ssl_keyfile=key_file

Optional: If you are using SSL communication, you can use ssl_label to specify the certificate name:

Note: If you do not configure a value for this field, the agent uses the default certificate from the key database.

ssl_label=my_label

Optional: If you require SSL communication with the remote server, you must specify the SSL stash file:

ssl_stashfile=stash_file

Example

This example sends event records to the remote timelord server:

[aznapi-configuration]
logcfg = audit:rsyslog error_retry=2,path=rsyslog.cache,
rebind_retry=600,server=timelord,port=514,log_id=webseal-instance

Parent topic: Configuring remote syslog agents

Disabling resource access eventsYou can use protected object policies (POPs) to selectively disable auditing of access to particular resources.resource access eventsdisablingDisable generating audit records.If a POP with the audithttp extended attribute set to no is attached to a resource, access to that resource does not generate an HTTP access audit record. For example, if access to the /images subdirectory is not of sufficient interest to merit an audit record, you can disable audit records by using the following commands: pdadmin sec_master> pop create nohttpaudit pdadmin sec_master> pop modify nohttpaudit set attribute audithttp no pdadmin sec_master> pop attached /WebSEAL/server/images nohttpauditAfter you attach the nohttpaudit POP to the /images subdirectory, access to files under this directory no longer generates an audit event. Enable generating audit records.If you have a specific resource that must be audited, you can enable auditing of that resource. To enable auditing, attach a second POP without the audithttp attribute. For example, the special.jpg file in the /images subdirectory must be audited. You can enable audit records for the file with the following commands: pdadmin sec_master> pop create restorehttpaudit pdadmin sec_master> pop attached /WebSEAL/server/images/special.jpg \ restorehttpauditAudit event loggingTo enable logging, define entries in the configuration file.

Disabling resource access events

You can use protected object policies (POPs) to selectively disable auditing of access to particular resources.

Procedure

Disable generating audit records.

If a POP with the audithttp extended attribute set to no is attached to a resource, access to that resource does not generate an HTTP access audit record. For example, if access to the /images subdirectory is not of sufficient interest to merit an audit record, you can disable audit records by using the following commands:

pdadmin sec_master> pop create nohttpaudit
pdadmin sec_master> pop modify nohttpaudit set attribute audithttp no
pdadmin sec_master> pop attached /WebSEAL/server/images nohttpaudit

After you attach the nohttpaudit POP to the /images subdirectory, access to files under this directory no longer generates an audit event.

Enable generating audit records.

If you have a specific resource that must be audited, you can enable auditing of that resource. To enable auditing, attach a second POP without the audithttp attribute. For example, the special.jpg file in the /images subdirectory must be audited. You can enable audit records for the file with the following commands:

pdadmin sec_master> pop create restorehttpaudit
pdadmin sec_master> pop attached /WebSEAL/server/images/special.jpg \
  restorehttpaudit

Parent topic: Audit event logging

Process flow for logcfg loggingThe following example process flow assumes the [aznapi-configuration] stanza of a WebSEAL configuration file. Use the syntax of the logcfg entry to specify a log file. The log file is opened at WebSEAL initialization. If no log file is opened during initialization, regardless of other configuration settings, no events are logged. Unless a log file is specified, all event data is lost.[aznapi-configuration] logcfg = http.agent:file path=abc.log,log_id=agentYou can use the log_id identifier to facilitate the recording of events from different categories to the same file. You can construct more log agents. The log agents can gather different event data. These agents use log_id to direct the data to the log file that was opened by the initial log agent. The first logcfg entry must be used to define the log agent. If the log agent is defined after the first log_id, no events for that category are logged.In the following example, events from the http.agent category are directed to the abc.log file. The log agent has the log_id=httplogs identifier. Events from http.ref and http.clf audit categories are also logged to this file because the logcfg entry uses the same identifier log_id=httplogs:[aznapi-configuration] logcfg = http.agent:file path=abc.log,log_id=httplogs logcfg = http.ref:file log_id=httplogs logcfg = http.clf:file log_id=httplogsAudit event loggingTo enable logging, define entries in the configuration file.

Process flow for logcfg logging

The following example process flow assumes the [aznapi-configuration] stanza of a WebSEAL configuration file.

Use the syntax of the logcfg entry to specify a log file. The log file is opened at WebSEAL initialization. If no log file is opened during initialization, regardless of other configuration settings, no events are logged. Unless a log file is specified, all event data is lost.

[aznapi-configuration]
logcfg = http.agent:file path=abc.log,log_id=agent

You can use the log_id identifier to facilitate the recording of events from different categories to the same file. You can construct more log agents. The log agents can gather different event data. These agents use log_id to direct the data to the log file that was opened by the initial log agent. The first logcfg entry must be used to define the log agent. If the log agent is defined after the first log_id, no events for that category are logged.

In the following example, events from the http.agent category are directed to the abc.log file. The log agent has the log_id=httplogs identifier. Events from http.ref and http.clf audit categories are also logged to this file because the logcfg entry uses the same identifier log_id=httplogs:

[aznapi-configuration]
logcfg = http.agent:file path=abc.log,log_id=httplogs
logcfg = http.ref:file log_id=httplogs
logcfg = http.clf:file log_id=httplogs

Parent topic: Audit event logging

Auditing using logauditlogaudit stanza entryauditcfg stanza entryauditlog stanza entrylogsize stanza entrylogflush stanza entryWebSEAL and Plug-in for Web Servers continue to support audit logging that uses the logaudit entries and its related entries in the [aznapi-configuration] stanza. This approach uses the following stanza entries:[aznapi-configuration] logaudit auditlog auditcfg logsize logflushThis approach is comparable to the logcfg entry with a file agent.For example, to capture authentication events, you can set the configuration file entries as follows:[aznapi-configuration] logaudit = yes auditcfg = authn auditlog = /var/pdweb/log/audit.log logsize = 2000000 logflush = 20If you are still using the logaudit approach, consider using the logcfg approach. The logcfg approach provides more configuration options, such as buffer size and event queues, and the ability to use the console, pipe, and remote log agents.Audit event loggingTo enable logging, define entries in the configuration file.

Auditing using logaudit

WebSEAL and Plug-in for Web Servers continue to support audit logging that uses the logaudit entries and its related entries in the [aznapi-configuration] stanza. This approach uses the following stanza entries:

[aznapi-configuration]
logaudit
auditlog
auditcfg
logsize
logflush

This approach is comparable to the logcfg entry with a file agent.

For example, to capture authentication events, you can set the configuration file entries as follows:

[aznapi-configuration]
logaudit = yes
auditcfg = authn
auditlog = /var/pdweb/log/audit.log
logsize = 2000000
logflush = 20

If you are still using the logaudit approach, consider using the logcfg approach. The logcfg approach provides more configuration options, such as buffer size and event queues, and the ability to use the console, pipe, and remote log agents.

Parent topic: Audit event logging

WebSEAL HTTP loggingHTTP logsWebSEALloggingHTTP eventsThis chapter describes WebSEAL HTTP logging.Native Security Access Manager auditingHTTP log filesEnabling HTTP loggingCustomizing the HTTP request logProcess flow for [logging] and logcfg loggingYou can configure WebSEAL auditing you use both the [logging] stanza and the [aznapi-configuration] stanza. Sample request.log fileSample agent.log fileThe agent.log file records the contents of the User_Agent: header in the HTTP request. Sample referer.log

WebSEAL HTTP logging

This chapter describes WebSEAL HTTP logging.

HTTP log files

Enabling HTTP logging

Customizing the HTTP request log

Process flow for [logging] and logcfg logging
You can configure WebSEAL auditing you use both the [logging] stanza and the [aznapi-configuration] stanza.

Sample request.log file

Sample agent.log file
The agent.log file records the contents of the User_Agent: header in the HTTP request.

Sample referer.log

Parent topic: Native Security Access Manager auditing

HTTP log filesrequests-file stanza entryreferers-file stanza entryenable logsWebSEAL maintains the following HTTP log files that record HTTP activity: request.logagent.logreferer.logStanza entries for configuring traditional HTTP logging are in the [logging] stanza of the WebSEAL configuration file.Table 1 illustrates the relationship among the HTTP logs and the configuration file entries: Relationship between HTTP logs and the stanza entriesFile nameLog file entryEnablement entryrequest.logrequests-filerequests referer.logreferers-filereferers agent.logagents-fileagents WebSEAL HTTP logging

HTTP log files

WebSEAL maintains the following HTTP log files that record HTTP activity:

request.log

agent.log

referer.log

Stanza entries for configuring traditional HTTP logging are in the [logging] stanza of the WebSEAL configuration file.

Table 232 illustrates the relationship among the HTTP logs and the configuration file entries:

Table 232. Relationship between HTTP logs and the stanza entries

File name | Log file entry | Enablement entry
request.log | requests-file | requests
referer.log | referers-file | referers
agent.log | agents-file | agents

Parent topic: WebSEAL HTTP logging

Enabling HTTP logging HTTPlogsenable and disablerequests stanza entryreferers stanza entryenable logsagentsstanza entryrequest.logevent logging formatreferer.logevent logging formatagent.logevent logging formatBy default, HTTP logging is enabled in the WebSEAL configuration file. For example: [logging] requests = yes referers = yes agents = yesYou can enable or disable each log independently from the others. If any stanza entry is set to no, logging is disabled for that file.Configuring HTTP logging in the [logging] stanza implements the standard event logging mechanism that is described in Audit event loggingTo enable logging, define entries in the configuration file. .The following configurations are created when the WebSEAL HTTP logging stanza entries are enabled. These configurations accept the values of the requests-file, referers-file, agents-file, flush-time, and max-size stanza entries from the WebSEAL configuration file [logging] stanza:request.log logcfg = http.clf:file path=requests-file,flush=flush-time, rollover=max-size,max_rollover_files=max-files, log=clf,buffer_size=8192,queue_size=48referer.log logcfg = http.ref:file path=referers-file,flush=flush-time, rollover=max-size,max_rollover_files=max-files, log=ref,buffer_size=8192,queue_size=48agent.log (common log format) logcfg = http.agent:file path=agents-file,flush=flush-time, rollover=max-size,max_rollover_files=max-files, log=agent,buffer_size=8192,queue_size=48See Process flow for logcfg loggingThe following example process flow assumes the [aznapi-configuration] stanza of a WebSEAL configuration file. for special considerations and conditions when you use both traditional HTTP logging ([logging] stanza) and the event logging mechanism ([aznapi-configuration] stanza).WebSEAL HTTP loggingSpecifying the timestampSpecifying rollover thresholdsSpecifying the frequency for flushing buffersDistinguishing virtual hosts

Enabling HTTP logging

By default, HTTP logging is enabled in the WebSEAL configuration file. For example:

[logging]
requests = yes
referers = yes
agents = yes

You can enable or disable each log independently from the others. If any stanza entry is set to no, logging is disabled for that file.

Configuring HTTP logging in the [logging] stanza implements the standard event logging mechanism that is described in Audit event logging.

The following configurations are created when the WebSEAL HTTP logging stanza entries are enabled. These configurations accept the values of the requests-file, referers-file, agents-file, flush-time, and max-size stanza entries from the WebSEAL configuration file [logging] stanza:

request.log

logcfg = http.clf:file path=requests-file,flush=flush-time,
rollover=max-size,max_rollover_files=max-files,
log=clf,buffer_size=8192,queue_size=48

referer.log

logcfg = http.ref:file path=referers-file,flush=flush-time,
rollover=max-size,max_rollover_files=max-files,
log=ref,buffer_size=8192,queue_size=48

agent.log (common log format)

logcfg = http.agent:file path=agents-file,flush=flush-time,
rollover=max-size,max_rollover_files=max-files,
log=agent,buffer_size=8192,queue_size=48

See Process flow for logcfg logging for special considerations and conditions when you use both traditional HTTP logging ([logging] stanza) and the event logging mechanism ([aznapi-configuration] stanza).

Specifying the timestamp

Specifying rollover thresholds

Specifying the frequency for flushing buffers

Distinguishing virtual hosts

Parent topic: WebSEAL HTTP logging

Specifying the timestampHTTP logstimestampgmt-time stanza entryYou can choose to have timestamps in each HTTP log file that is recorded in Greenwich Mean Time (GMT). This GMT choice overrides the local time zone. By default, the local time zone is used.To use GMT timestamps, set the value of the gmt-time entry to yes as shown in the following entry: gmt-time = yesEnabling HTTP logging

Specifying the timestamp

You can choose to have timestamps in each HTTP log file that is recorded in Greenwich Mean Time (GMT). This GMT choice overrides the local time zone. By default, the local time zone is used.

To use GMT timestamps, set the value of the gmt-time entry to yes as shown in the following entry:

gmt-time = yes

Parent topic: Enabling HTTP logging

Specifying rollover thresholds HTTP logsrollover thresholdmax-size stanza entryThe max-size stanza entry specifies the maximum size to which each of the HTTP log files can grow and has the following default value in bytes: [logging] max-size = 2000000When a log file reaches its rollover threshold: The existing file is backed up to a file of the same name. The file name is appended with the current date and timestamp.A new log file is started. The various possible max-size values are interpreted as follows: If the max-size value is less than zero (< 0), a new log file is created: With each invocation of the logging process.Every 24 hours from that instance.If the max-size value is equal to zero (= 0), no rollover is completed and the log file grows indefinitely. If a log file exists, new data is appended to it.If the max-size value is greater than zero (> 0), a rollover is completed when a log file reaches the configured threshold value. If a log file exists at startup, new data is appended to it.Enabling HTTP logging

Specifying rollover thresholds

The max-size stanza entry specifies the maximum size to which each of the HTTP log files can grow and has the following default value in bytes:

[logging]
max-size = 2000000

When a log file reaches its rollover threshold:

The existing file is backed up to a file of the same name. The file name is appended with the current date and timestamp.

A new log file is started.

The various possible max-size values are interpreted as follows:

If the max-size value is less than zero (< 0), a new log file is created:

With each invocation of the logging process.

Every 24 hours from that instance.

If the max-size value is equal to zero (= 0), no rollover is completed and the log file grows indefinitely. If a log file exists, new data is appended to it.

If the max-size value is greater than zero (> 0), a rollover is completed when a log file reaches the configured threshold value. If a log file exists at startup, new data is appended to it.

Parent topic: Enabling HTTP logging

Specifying the frequency for flushing buffersHTTP logsbuffer flush frequencyflush-time stanza entryflushing buffer frequencyLog files are written to buffered data streams. If you are monitoring the log files in real time, alter the frequency with which the server flushes the log file buffers.By default, log files are flushed every 20 seconds as shown in the following example: [logging] flush-time = 20If you specify a negative value, a flush is forced after each record is written.Enabling HTTP logging

Specifying the frequency for flushing buffers

Log files are written to buffered data streams. If you are monitoring the log files in real time, alter the frequency with which the server flushes the log file buffers.

By default, log files are flushed every 20 seconds as shown in the following example:

[logging]
flush-time = 20

If you specify a negative value, a flush is forced after each record is written.

Parent topic: Enabling HTTP logging

Distinguishing virtual hostsvirtual hostoverviewWhen you use virtual hosts, you can use the request-log-format entry in the [logging] stanza to distinguish between requests to different virtual hosts.Use the %v directive at the start of the request-log-format configuration item to include the header at the front of each line in the request log.When you use the %R directive entry in the request-log-format configuration item, the log contains the absolute URI. Enabling HTTP logging

Distinguishing virtual hosts

When you use virtual hosts, you can use the request-log-format entry in the [logging] stanza to distinguish between requests to different virtual hosts.

Use the %v directive at the start of the request-log-format configuration item to include the header at the front of each line in the request log.

When you use the %R directive entry in the request-log-format configuration item, the log contains the absolute URI.

Parent topic: Enabling HTTP logging

Customizing the HTTP request logHTTP logscommon log formatHTTPcommon log formatcommon log format (request.log)You can customize the content of the request.log file by adding a configuration entry in the [logging] stanza. The syntax is as follows:request-log-format=directivesThe following directives can be used to customize the log format:Directives for customizing the format of the request.log fileDirectiveDescription%aRemote IP address%ALocal IP address%bBytes in the response excluding HTTP headers in CLF format: '-' instead of 0 when no bytes are returned%BBytes in the response excluding HTTP headers%{Attribute}CAttribute from the Security Access Manager credential named 'Attribute'%dTransaction identifier, or session sequence number%FTime that it takes to serve the request in microseconds%hRemote host%HRequest protocol%{header-name}iContents of the Header 'header-name' in the request%jThe name of the junction that services the request%lRemote logname%mRequest method (that is, GET, POST, HEAD)%{header-name}oContents of the Header 'header-name' in the response%pPort over which the request was received%qThe query string (prefixed with '?' or empty)%QRaw query strings that must be decoded manually.%rFirst line of the request%RFirst line of the request including HTTP://HOSTNAME%sResponse status%tTime and date in CLF format%{format}tThe time and date in the specified format%TTime that it takes to serve the request in seconds%uRemote user%UThe URL requested%vCanonical ServerName of the server that serves the request%{cookie-name}eContents of the cookie 'cookie-name' in the request%{cookie-name}EContents of the cookie 'cookie-name' in the responseThe following configuration entry shows an example of customizing the request.log file: request-log-format = %h %l %u %t "%r" %s %bCustomized HTTP logs also support the new line (\n), carriage return (\r), and tab (\t) special characters. Any character that is either not part of a directive or not a special character is written out in the log entry. You can direct the system to ignore the % and \ characters by prefixing them with the backslash (\) character. For example: request-log-format = \%{header}i\t->\t%{header}i renders the following output: %{header}i -> headerWebSEAL HTTP logging

Customizing the HTTP request log

You can customize the content of the request.log file by adding a configuration entry in the [logging] stanza. The syntax is as follows:

request-log-format=directives

The following directives can be used to customize the log format:

Table 233. Directives for customizing the format of the request.log file

Directive | Description
%a | Remote IP address
%A | Local IP address
%b | Bytes in the response excluding HTTP headers in CLF format: '-' instead of 0 when no bytes are returned
%B | Bytes in the response excluding HTTP headers
%{Attribute}C | Attribute from the Security Access Manager credential named 'Attribute'
%d | Transaction identifier, or session sequence number
%F | Time that it takes to serve the request in microseconds
%h | Remote host
%H | Request protocol
%{header-name}i | Contents of the Header 'header-name' in the request
%j | The name of the junction that services the request
%l | Remote logname
%m | Request method (that is, GET, POST, HEAD)
%{header-name}o | Contents of the Header 'header-name' in the response
%p | Port over which the request was received
%q | The query string (prefixed with '?' or empty)
%Q | Raw query strings that must be decoded manually.
%r | First line of the request
%R | First line of the request including HTTP://HOSTNAME
%s | Response status
%t | Time and date in CLF format
%{format}t | The time and date in the specified format
%T | Time that it takes to serve the request in seconds
%u | Remote user
%U | The URL requested
%v | Canonical ServerName of the server that serves the request
%{cookie-name}e | Contents of the cookie 'cookie-name' in the request
%{cookie-name}E | Contents of the cookie 'cookie-name' in the response

The following configuration entry shows an example of customizing the request.log file:

request-log-format = %h %l %u %t "%r" %s %b

Customized HTTP logs also support the new line (\n), carriage return (\r), and tab (\t) special characters. Any character that is either not part of a directive or not a special character is written out in the log entry. You can direct the system to ignore the % and \ characters by prefixing them with the backslash (\) character. For example:

request-log-format = \%{header}i\t->\t%{header}i

renders the following output:

%{header}i	->	header

Parent topic: WebSEAL HTTP logging

Process flow for [logging] and logcfg loggingYou can configure WebSEAL auditing you use both the [logging] stanza and the [aznapi-configuration] stanza. loggingprocess flow[logging]process flowlogcfgprocess flowWhen you use both configuration settings, WebSEAL processes the [aznapi-configuration] stanza before the [logging] stanza.For example, assuming the following entries in the WebSEAL configuration file:[logging] requests = yes requests-file =request.log [aznapi-configuration] logcfg = stats.pdweb.authn:file path=stats.log,log_id=stats logcfg = http.agent:file path=abc.log,log_id=httplogs logcfg = http.ref:file log_id=httplogsWebSEAL processes these entries in the following manner:The [aznapi-configuration] stanza is read.The stats.log file with log_id=stats is opened. All stats.pdweb.authn events are logged to this file.The abc.log file with log_id=httplogs is opened. All http.agent events are logged to this file.Because the next log agent uses log_id=httplogs, all http.ref events are logged to the previously opened abc.log file.The [logging] stanza is read.HTTP request logging is enabled. All http.clf events are logged to the request.log file that uses the default log_id=clf. See the following example for an explanation of this default identifier.HTTP logging using the [logging] stanza operates by generating its own default log agent entries. Each HTTP log file has a default value for the log_id parameter.Log filelog_idrequest.loglog_id=clfreferer.loglog_id=refagent.loglog_id=agentIf a logcfg entry in the [aznapi-configuration] stanza contains the same log_id as one used in the [logging] stanza, the HTTP log file is not created. Audit events with the same log_id are directed to 1 log file only. That 1 log file is always the first one opened.In the following example, the abc.log file with log_id=clf is opened first. Because the HTTP requests logging defined in the [logging] stanza uses a default log_id=clf, the requests.log file is never created and all http.clf (requests) events are directed to abc.log file.[logging] requests = yes requests-file = request.log [aznapi-configuration] logcfg = http.agent:file path=abc.log,log_id=clf logcfg = http.ref:file log_id=clfHTTP logging can be configured in the [logging] and [aznapi-configuration] stanzas. Therefore, it is possible to have duplicate entries for HTTP events in a log file when both mechanisms are enabled.In the following example, http.clf audit events are recorded twice in the abc.log file: From the event logging configuration.From the enabled request logging, which uses log_id=clf by default. The requests.log is not created because the abc.log file with log_id=clf is opened first.[logging] requests = yes requests-file =request.log [aznapi-configuration] logcfg = http.agent:file path=abc.log,log_id=clf logcfg = http.ref:file log_id=clf logcfg = http.clf:file log_id=clfWebSEAL HTTP logging

Process flow for [logging] and logcfg logging

You can configure WebSEAL auditing you use both the [logging] stanza and the [aznapi-configuration] stanza.

When you use both configuration settings, WebSEAL processes the [aznapi-configuration] stanza before the [logging] stanza.

For example, assuming the following entries in the WebSEAL configuration file:

[logging]
requests = yes
requests-file =request.log

[aznapi-configuration]
logcfg = stats.pdweb.authn:file path=stats.log,log_id=stats
logcfg = http.agent:file path=abc.log,log_id=httplogs
logcfg = http.ref:file log_id=httplogs

WebSEAL processes these entries in the following manner:

The [aznapi-configuration] stanza is read.

The stats.log file with log_id=stats is opened. All stats.pdweb.authn events are logged to this file.

The abc.log file with log_id=httplogs is opened. All http.agent events are logged to this file.

Because the next log agent uses log_id=httplogs, all http.ref events are logged to the previously opened abc.log file.

The [logging] stanza is read.

HTTP request logging is enabled. All http.clf events are logged to the request.log file that uses the default log_id=clf. See the following example for an explanation of this default identifier.

HTTP logging using the [logging] stanza operates by generating its own default log agent entries. Each HTTP log file has a default value for the log_id parameter.

Log file | log_id
request.log | log_id=clf
referer.log | log_id=ref
agent.log | log_id=agent

If a logcfg entry in the [aznapi-configuration] stanza contains the same log_id as one used in the [logging] stanza, the HTTP log file is not created. Audit events with the same log_id are directed to 1 log file only. That 1 log file is always the first one opened.

In the following example, the abc.log file with log_id=clf is opened first. Because the HTTP requests logging defined in the [logging] stanza uses a default log_id=clf, the requests.log file is never created and all http.clf (requests) events are directed to abc.log file.

[logging]
requests = yes
requests-file = request.log

[aznapi-configuration]
logcfg = http.agent:file path=abc.log,log_id=clf
logcfg = http.ref:file log_id=clf

HTTP logging can be configured in the [logging] and [aznapi-configuration] stanzas. Therefore, it is possible to have duplicate entries for HTTP events in a log file when both mechanisms are enabled.

In the following example, http.clf audit events are recorded twice in the abc.log file:

From the event logging configuration.

From the enabled request logging, which uses log_id=clf by default. The requests.log is not created because the abc.log file with log_id=clf is opened first.

[logging]
requests = yes
requests-file =request.log

[aznapi-configuration]
logcfg = http.agent:file path=abc.log,log_id=clf
logcfg = http.ref:file log_id=clf
logcfg = http.clf:file log_id=clf

Parent topic: WebSEAL HTTP logging

Sample request.log file HTTP logsrequest.log examplerequest.logexampleThe content of the request.log file is set by the request-log-format configuration item. The following table shows all the possible initial request-log-format combinations that are based on the existing absolute-uri-in-request-log and host-header-in-request-log configuration items: Example output of the request.log fileabsolute-uri-in-request-loghost-header-in-request-logrequest-log-formatExample outputNoNo%h %l %u %t "%r" %s %b 10.251.173.1 - sec_master [04/Jan/2009:11:13:07 +1000] "GET /pics/iv30.gif HTTP/1.1" 200 46498NoYes%v %h %l %u %t "%r" %s %b tamtestbed 10.251.173.1 - sec_master [04/Jan/2009:11:10:04 +1000] "GET /pics/iv30.gif HTTP/1.1" 200 46498YesNo%h %l %u %t "%R" %s %b 10.251.173.1 - sec_master [04/Jan/2009:11:14:51 +1000] "GET HTTP://tamtestbed/pics/iv30.gif HTTP/1.1" 200 46498YesYes%v %h %l %u %t "%R" %s %b tamtestbed 10.251.173.1 - sec_master [04/Jan/2009:11:16:40 +1000] "GET HTTP://tamtestbed/pics/iv30.gif HTTP/1.1" 200 46498WebSEAL HTTP logging

Sample request.log file

The content of the request.log file is set by the request-log-format configuration item. The following table shows all the possible initial request-log-format combinations that are based on the existing absolute-uri-in-request-log and host-header-in-request-log configuration items:

Table 234.  Example output of the request.log file

absolute-uri-in-request-log | host-header-in-request-log | request-log-format | Example output
No | No | %h %l %u %t "%r" %s %b | 10.251.173.1 - sec_master [04/Jan/2009:11:13:07 +1000] "GET /pics/iv30.gif HTTP/1.1" 200 46498
No | Yes | %v %h %l %u %t "%r" %s %b | tamtestbed 10.251.173.1 - sec_master [04/Jan/2009:11:10:04 +1000] "GET /pics/iv30.gif HTTP/1.1" 200 46498
Yes | No | %h %l %u %t "%R" %s %b | 10.251.173.1 - sec_master [04/Jan/2009:11:14:51 +1000] "GET HTTP://tamtestbed/pics/iv30.gif HTTP/1.1" 200 46498
Yes | Yes | %v %h %l %u %t "%R" %s %b | tamtestbed 10.251.173.1 - sec_master [04/Jan/2009:11:16:40 +1000] "GET HTTP://tamtestbed/pics/iv30.gif HTTP/1.1" 200 46498

Parent topic: WebSEAL HTTP logging

Sample agent.log fileThe agent.log file records the contents of the User_Agent: header in the HTTP request. HTTP logsagent.log exampleagent.logexampleThis log reveals information about the client browser, such as architecture or version number, for each request. The following example shows a sample version of the agent.log file:Mozilla/4.01 [en] (WinNT; U) Mozilla/4.01 [en] (WinNT; U) Mozilla/4.01 [en] (WinNT; U) Mozilla/4.01 [en] (WinNT; U)WebSEAL HTTP logging

Sample agent.log file

The agent.log file records the contents of the User_Agent: header in the HTTP request.

This log reveals information about the client browser, such as architecture or version number, for each request. The following example shows a sample version of the agent.log file:

Mozilla/4.01 [en] (WinNT; U)
Mozilla/4.01 [en] (WinNT; U)
Mozilla/4.01 [en] (WinNT; U)
Mozilla/4.01 [en] (WinNT; U)

Parent topic: WebSEAL HTTP logging

Sample referer.log HTTP logsreferer.log examplereferer.logexampleThe referer.log records the Referer: header of the HTTP request. For each request, the log records the document that contained the link to the requested document.The log uses the following format: referer -> objectThis information is useful for tracking external links to documents in your web space. The log reveals that the source indicated by referer contains a link to a page (object). With this log, you can track stale links and to find out who is creating links to your documents.The following example shows a sample version of a referer log file: http://manuel/maybam/index.html -> /pics/tivoli_logo.gif http://manuel/maybam/pddl/index.html -> /pics/tivoli_logo.gif http://manuel/maybam/ -> /pddl/index.html http://manuel/maybam/ -> /pddl/index.html http://manuel/maybam/pddl/index.html -> /pics/tivoli_logo.gif http://manuel/maybam/ -> /pddl/index.htmlWebSEAL HTTP logging

Sample referer.log

The referer.log records the Referer: header of the HTTP request. For each request, the log records the document that contained the link to the requested document.

The log uses the following format:

referer -> object

This information is useful for tracking external links to documents in your web space. The log reveals that the source indicated by referer contains a link to a page (object). With this log, you can track stale links and to find out who is creating links to your documents.

The following example shows a sample version of a referer log file:

http://manuel/maybam/index.html -> /pics/tivoli_logo.gif
http://manuel/maybam/pddl/index.html -> /pics/tivoli_logo.gif
http://manuel/maybam/ -> /pddl/index.html
http://manuel/maybam/ -> /pddl/index.html
http://manuel/maybam/pddl/index.html -> /pics/tivoli_logo.gif
http://manuel/maybam/ -> /pddl/index.html

Parent topic: WebSEAL HTTP logging

Working with statisticsstatisticsworking withThis chapter provides information about working with the Security Access Manager modules that can monitor and collect statistical information.Native Security Access Manager auditingUsing stats commands for statisticsUsing stanza entries for statisticsSecurity Access Manager components and activity typesWebSEAL components and activity types

Working with statistics

This chapter provides information about working with the Security Access Manager modules that can monitor and collect statistical information.

Using stats commands for statistics

Using stanza entries for statistics

Security Access Manager components and activity types

WebSEAL components and activity types

Parent topic: Native Security Access Manager auditing

Using stats commands for statisticsstatisticsstats commandsUse the server tasks stats command that is provided as by the pdadmin utility to manage statistics components. You can use the stats command to complete the following operations: stats onEnable statistics for a specific component.stats offDisable statistics for a specific component or for all components.stats showList enabled components.stats getDisplay current statistics values for a specific component or for all components.stats resetReset statistics values for a specific component or for all components.stats listList all statistics components.See server task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. for more information about the command.Working with statisticsEnabling statisticsYou can enable statistics reporting with the stats on command or with stanza entries in the configuration file for the specific server. Disabling statisticsListing enabled componentsDisplaying statisticsResetting statisticsListing components

Using stats commands for statistics

Use the server tasks stats command that is provided as by the pdadmin utility to manage statistics components. You can use the stats command to complete the following operations:

stats on

Enable statistics for a specific component.

stats off

Disable statistics for a specific component or for all components.

stats show

List enabled components.

stats get

Display current statistics values for a specific component or for all components.

stats reset

Reset statistics values for a specific component or for all components.

stats list

List all statistics components.

See server task stats for more information about the command.

Enabling statistics
You can enable statistics reporting with the stats on command or with stanza entries in the configuration file for the specific server.

Disabling statistics

Listing enabled components

Displaying statistics

Resetting statistics

Listing components

Parent topic: Working with statistics

Enabling statisticsYou can enable statistics reporting with the stats on command or with stanza entries in the configuration file for the specific server. statisticsenable with stats commandoverviewstatisticsstats on commandFor details about using stanza entries to enable statistics, see Using stanza entries for statistics.To enable the gathering of statistics with the stats on command, set the statistics report frequency, event count, and destination for the component. For more information about the stats on command, see server task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. .By default, the WebSEAL pdweb.threads, pdweb.doccache, and pdweb.jmt components are always enabled and cannot be disabled.Using stats on and changing the runtime Policy server trace settings affects only the current run of the Policy server. If the Policy server is stopped and then started later, the default trace settings take effect. To persist trace settings across multiple runs of the Policy server, modify the /etc/pdmgrd_routing file.When you enable statistics, you can specify one log file for the statistics report. If you specify two equivalent commands that differ only on the destination, the second invocation deactivates the first log file and activates the second log file. The following example illustrates this limitation: #pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 \ file path=A.log #pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 \ file path=B.logThe first command enables the pdweb.http component and sends statistics reports to the A.log file. The second command attempts to activate a second log file, B.log. However, this action actually deactivates the A.log file while it also activates the B.log file.Using stats commands for statisticsEnabling basic statisticsEnabling statistics with frequency and countEnabling statistics with frequency and destination

Enabling statistics

You can enable statistics reporting with the stats on command or with stanza entries in the configuration file for the specific server.

For details about using stanza entries to enable statistics, see Using stanza entries for statistics.

To enable the gathering of statistics with the stats on command, set the statistics report frequency, event count, and destination for the component. For more information about the stats on command, see server task stats.

Note:

By default, the WebSEAL pdweb.threads, pdweb.doccache, and pdweb.jmt components are always enabled and cannot be disabled.

Using stats on and changing the runtime Policy server trace settings affects only the current run of the Policy server. If the Policy server is stopped and then started later, the default trace settings take effect. To persist trace settings across multiple runs of the Policy server, modify the /etc/pdmgrd_routing file.

When you enable statistics, you can specify one log file for the statistics report. If you specify two equivalent commands that differ only on the destination, the second invocation deactivates the first log file and activates the second log file. The following example illustrates this limitation:

#pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 \
  file path=A.log

#pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 \
  file path=B.log

The first command enables the pdweb.http component and sends statistics reports to the A.log file. The second command attempts to activate a second log file, B.log. However, this action actually deactivates the A.log file while it also activates the B.log file.

Enabling basic statistics

Enabling statistics with frequency and count

Enabling statistics with frequency and destination

Parent topic: Using stats commands for statistics

Enabling basic statisticsstatisticsenable with stats commandbasicTo enable basic statistics gathering, use the stats on command and specify only the component option. Because the interval option is not specified, you can obtain statistics information only for this component with the stats get command. Because the destination option is not specified, the information is sent to the standard log file for that component.The following example enables the gathering of statistics for the pdweb.http component of a WebSEAL instance: #pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.httpEnabling statisticsYou can enable statistics reporting with the stats on command or with stanza entries in the configuration file for the specific server.

Enabling basic statistics

To enable basic statistics gathering, use the stats on command and specify only the component option. Because the interval option is not specified, you can obtain statistics information only for this component with the stats get command. Because the destination option is not specified, the information is sent to the standard log file for that component.

The following example enables the gathering of statistics for the pdweb.http component of a WebSEAL instance:

#pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http

Parent topic: Enabling statistics

Enabling statistics with frequency and countstatisticsenable with stats commandfrequency and countTo enable the gathering of statistics at a designated frequency and event count, use the stats on command and specify the following options: componentintervalcountThe interval and count options: Cause the buffer to accumulate a specific number of entries that represent a statistics report.Flush the buffer after a specific number of seconds elapse. Because the destination option is not specified, the information is sent to the standard log file for that component.The following example enables the gathering of statistics for the pdweb.http component of a WebSEAL instance. In this example, the buffer accumulates 100 entries and sends statistics reports every 20 seconds: #pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 100Enabling statisticsYou can enable statistics reporting with the stats on command or with stanza entries in the configuration file for the specific server.

Enabling statistics with frequency and count

To enable the gathering of statistics at a designated frequency and event count, use the stats on command and specify the following options:

component

interval

count

The interval and count options:

Cause the buffer to accumulate a specific number of entries that represent a statistics report.

Flush the buffer after a specific number of seconds elapse.

Because the destination option is not specified, the information is sent to the standard log file for that component.

The following example enables the gathering of statistics for the pdweb.http component of a WebSEAL instance. In this example, the buffer accumulates 100 entries and sends statistics reports every 20 seconds:

#pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 100

Parent topic: Enabling statistics

Enabling statistics with frequency and destinationstatisticsenable with stats commandfrequency and destinationstatisticsenable with stats commandspecifying configuration optionsTo enable gathering of statistics at a designated frequency and write the statistics to a specific file, use the stats on command and specify the following options: componentintervaldestinationThe interval option, without a count option, indefinitely sends statistics reports after a specific number of seconds elapses. The destination option specifies the exact file where the statistics are written. When you specify a file that is different for the file log agent for the component, you can specify more configuration options.The following example enables the gathering of statistics for the pdweb.http component of a WebSEAL instance where: A statistics report is sent to the jmt-stats.log file every 20 seconds.A new file is created each time that the buffer is flushed. #pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 \ file path=jmt-stats.log,rollover_size=-1The growth of the log file is controlled by the rollover_size configuration option. For complete details about configuring event logging, see the Troubleshooting topics in the Knowledge Center.Enabling statisticsYou can enable statistics reporting with the stats on command or with stanza entries in the configuration file for the specific server.

Enabling statistics with frequency and destination

To enable gathering of statistics at a designated frequency and write the statistics to a specific file, use the stats on command and specify the following options:

component

interval

destination

The interval option, without a count option, indefinitely sends statistics reports after a specific number of seconds elapses. The destination option specifies the exact file where the statistics are written. When you specify a file that is different for the file log agent for the component, you can specify more configuration options.

The following example enables the gathering of statistics for the pdweb.http component of a WebSEAL instance where:

A statistics report is sent to the jmt-stats.log file every 20 seconds.

A new file is created each time that the buffer is flushed.

#pdadmin> server task default-webseald-abc.ibm.com stats on pdweb.http 20 \
  file path=jmt-stats.log,rollover_size=-1

The growth of the log file is controlled by the rollover_size configuration option. For complete details about configuring event logging, see the Troubleshooting topics in the Knowledge Center.

Parent topic: Enabling statistics

Disabling statisticsstatisticsdisableoverviewstatisticsstats off commandYou can disable statistics reporting with the stats off command for a specific component or for all components. By default, the pdweb.threads, pdweb.doccache, and pdweb.jmt components are always enabled and cannot be disabled.Using stats commands for statisticsDisabling statistics for all componentsDisabling statistics for a single component

Disabling statistics

You can disable statistics reporting with the stats off command for a specific component or for all components. By default, the pdweb.threads, pdweb.doccache, and pdweb.jmt components are always enabled and cannot be disabled.

Disabling statistics for all components

Disabling statistics for a single component

Parent topic: Using stats commands for statistics

Disabling statistics for all componentsstatisticsdisableall componentsTo disable the gathering of statistics for all components, use the stats off command without options.The following example disables statistics for all components of a WebSEAL instance: #pdadmin> server task default-webseald-abc.ibm.com stats offDisabling statistics

Disabling statistics for all components

To disable the gathering of statistics for all components, use the stats off command without options.

The following example disables statistics for all components of a WebSEAL instance:

#pdadmin> server task default-webseald-abc.ibm.com stats off

Parent topic: Disabling statistics

Disabling statistics for a single componentstatisticsdisablesingle componentTo disable the gathering of statistics for a single component, use the stats off command with the component option.The following example disables statistics for the pdweb.sescache component of a WebSEAL instance: #pdadmin> server task default-webseald-abc.ibm.com stats off pdweb.sescacheDisabling statistics

Disabling statistics for a single component

To disable the gathering of statistics for a single component, use the stats off command with the component option.

The following example disables statistics for the pdweb.sescache component of a WebSEAL instance:

#pdadmin> server task default-webseald-abc.ibm.com stats off pdweb.sescache

Parent topic: Disabling statistics

Listing enabled componentsstatisticslist enabled componentsoverviewstatisticsstats show commandYou can use the stats show command to: List all enabled statistics components.Determine whether a specific component is enabled.Using stats commands for statisticsListing all enabled componentsDetermining whether a component is enabledTo determine whether a component is enabled, use the stats show command with the component option.

Listing enabled components

You can use the stats show command to:

List all enabled statistics components.

Determine whether a specific component is enabled.

Listing all enabled components

Determining whether a component is enabled
To determine whether a component is enabled, use the stats show command with the component option.

Parent topic: Using stats commands for statistics

Listing all enabled componentsstatisticslist enabled componentsall componentsTo display a list of all components, use the stats show command without options.The following example displays a list of the enabled component of a WebSEAL instance: #pdadmin> server task default-webseald-abc.ibm.com stats show pdweb.authn pdweb.doccache pdweb.jmt pdweb.sescache pdweb.threadsBecause the pdweb.threads, pdweb.doccache, and pdweb.jmt components are always enabled, the output for a WebSEAL instance always contains these entries.Listing enabled components

Listing all enabled components

To display a list of all components, use the stats show command without options.

The following example displays a list of the enabled component of a WebSEAL instance:

#pdadmin> server task default-webseald-abc.ibm.com stats show

pdweb.authn
pdweb.doccache
pdweb.jmt
pdweb.sescache
pdweb.threads

Because the pdweb.threads, pdweb.doccache, and pdweb.jmt components are always enabled, the output for a WebSEAL instance always contains these entries.

Parent topic: Listing enabled components

Determining whether a component is enabledTo determine whether a component is enabled, use the stats show command with the component option. statisticslist enabled componentssingle componentIf the component is enabled, the output lists that component. If the component is not enabled, no output is displayed.Listing enabled components

Determining whether a component is enabled

To determine whether a component is enabled, use the stats show command with the component option.

If the component is enabled, the output lists that component. If the component is not enabled, no output is displayed.

Parent topic: Listing enabled components

Displaying statisticsstatisticsdisplayoverviewstatisticsstats get commandYou can display the current statistics for all enabled components or for a single component with the stats get command.Using stats commands for statisticsDisplaying statistics for all componentsDisplaying statistics for a single component

Displaying statistics

You can display the current statistics for all enabled components or for a single component with the stats get command.

Displaying statistics for all components

Displaying statistics for a single component

Parent topic: Using stats commands for statistics

Displaying statistics for all componentsstatisticsdisplayall componentsTo display statistics for all components, use the stats get command without options. For each enabled component, the name of the component is displayed followed by its statistics. For details about the specifics of the statistics for each component, see the information for that specific component in one of the following sections: Security Access Manager components and activity typesWebSEAL components and activity typesThe following example displays the current statistics for all enabled components of a WebSEAL instance: #pdadmin> server task default-webseald-abc.ibm.com stats get pd.ras.stats.monitor ... pd.log.EventPool.queue ... pd.log.file.clf ... pd.log.file.ref ... pd.log.file.agent ... pdweb.authn ... pdweb.authz ... pdweb.http ... pdweb.https ... pdweb.threads ... pdweb.sescache ... pdweb.doccache ... pdweb.jct.1 ... pdweb.jct.2 ...Displaying statistics

Displaying statistics for all components

To display statistics for all components, use the stats get command without options. For each enabled component, the name of the component is displayed followed by its statistics. For details about the specifics of the statistics for each component, see the information for that specific component in one of the following sections:

Security Access Manager components and activity types

WebSEAL components and activity types

The following example displays the current statistics for all enabled components of a WebSEAL instance:

#pdadmin> server task default-webseald-abc.ibm.com stats get

pd.ras.stats.monitor
  ...
pd.log.EventPool.queue
  ...
pd.log.file.clf
  ...
pd.log.file.ref
  ...
pd.log.file.agent
  ...
pdweb.authn
  ...
pdweb.authz
  ...
pdweb.http
  ...
pdweb.https
  ...
pdweb.threads
  ...
pdweb.sescache
  ...
pdweb.doccache
  ...
pdweb.jct.1
  ...
pdweb.jct.2
...

Parent topic: Displaying statistics

Displaying statistics for a single componentstatisticsdisplaysingle componentTo display statistics for a single component, use the stats get command with the component option.The following example displays the current statistics for the pdweb.threads component of a WebSEAL instance: #pdadmin> server task default-webseald-abc.ibm.com stats get pdweb.threads active : 4 total : 50 'default' active : 4 'default' total : 50Displaying statistics

Displaying statistics for a single component

To display statistics for a single component, use the stats get command with the component option.

The following example displays the current statistics for the pdweb.threads component of a WebSEAL instance:

#pdadmin> server task default-webseald-abc.ibm.com stats get pdweb.threads

active : 4
total : 50
'default' active : 4
'default' total : 50

Parent topic: Displaying statistics

Resetting statisticsstatisticsresetstatisticsstats reset commandYou can reset the current statistics for all enabled components or for a single component with the stats reset command.To reset statistics for all components, use the stats reset command without options.To reset statistics for a single component, use the stats reset command with the component option.Using stats commands for statistics

Resetting statistics

You can reset the current statistics for all enabled components or for a single component with the stats reset command.

To reset statistics for all components, use the stats reset command without options.

To reset statistics for a single component, use the stats reset command with the component option.

Parent topic: Using stats commands for statistics

Listing componentsstatisticslist componentsstatisticsstats list commandYou can list all components that are available to gather and report statistics with the stats list command.To determine which queues are implemented on a server, use the stats list command. The following example lists all available components of a WebSEAL instance: #pdadmin> server task default-webseald-abc.ibm.com stats list pd.ras.stats.monitor pd.log.EventPool.queue pd.log.file.clf pd.log.file.ref pd.log.file.agent pdweb.authn pdweb.authz pdweb.http pdweb.https pdweb.threads pdweb.jmt pdweb.sescache pdweb.doccache pdweb.jct.1Using stats commands for statistics

Listing components

You can list all components that are available to gather and report statistics with the stats list command.

To determine which queues are implemented on a server, use the stats list command. The following example lists all available components of a WebSEAL instance:

#pdadmin> server task default-webseald-abc.ibm.com stats list

pd.ras.stats.monitor
pd.log.EventPool.queue
pd.log.file.clf
pd.log.file.ref
pd.log.file.agent
pdweb.authn
pdweb.authz
pdweb.http
pdweb.https
pdweb.threads
pdweb.jmt
pdweb.sescache
pdweb.doccache
pdweb.jct.1

Parent topic: Using stats commands for statistics

Using stanza entries for statisticsstatisticsenable with stanza entriesoverviewstanzasaznapi-configurationstanza entriesstatsstanza entrieslogcfgstats entry, using for statisticslogcfg entryuse for statisticsThe configuration file for each server contains the following stanza entries that can be set to: Enable the statistics interface.Specify the destination for statistics reports. statslogcfgThe following segment of a configuration file shows the structure of the stats and logcfg stanza entries: [aznapi-configuration] stats = component [interval [count]] logcfg = stats.component:destinationFor information about the interval and count options, see server task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. . For complete details about configuring event logging, see the Troubleshooting topics in the Knowledge Center.Working with statisticsEnabling statistics for a single componentEnabling statistics for multiple components

Using stanza entries for statistics

The configuration file for each server contains the following stanza entries that can be set to:

Enable the statistics interface.

Specify the destination for statistics reports.

stats

logcfg

The following segment of a configuration file shows the structure of the stats and logcfg stanza entries:

[aznapi-configuration]
stats = component [interval [count]]
logcfg = stats.component:destination

For information about the interval and count options, see server task stats. For complete details about configuring event logging, see the Troubleshooting topics in the Knowledge Center.

Enabling statistics for a single component

Enabling statistics for multiple components

Parent topic: Working with statistics

Enabling statistics for a single componentstatisticsenable with stanza entriessingle componentIn a server configuration file, you can enable gathering of statistics by using the stats and logcfg entries. These entries are in the [aznapi-configuration] stanza.In the following example: The stats stanza entry enables gathering of statistics for the pdweb.jmt component. The frequency is 20 seconds.The logcfg stanza entry specifies the destination for the statistics report as the jmt.log file. The entry contains more configuration information for the rollover_size and flush configuration settings: [aznapi-configuration] stats = pdweb.jmt 20 logcfg = stats.pdweb.jmt:file path=jmt.log,rollover_size=-1,flush=20For detailed information about configuration files, see the Administering topics in the Knowledge Center.Using stanza entries for statistics

Enabling statistics for a single component

In a server configuration file, you can enable gathering of statistics by using the stats and logcfg entries. These entries are in the [aznapi-configuration] stanza.

In the following example:

The stats stanza entry enables gathering of statistics for the pdweb.jmt component. The frequency is 20 seconds.

The logcfg stanza entry specifies the destination for the statistics report as the jmt.log file. The entry contains more configuration information for the rollover_size and flush configuration settings:

[aznapi-configuration]
stats = pdweb.jmt 20
logcfg = stats.pdweb.jmt:file path=jmt.log,rollover_size=-1,flush=20

For detailed information about configuration files, see the Administering topics in the Knowledge Center.

Parent topic: Using stanza entries for statistics

Enabling statistics for multiple componentsstatisticsenable with stanza entriesmultiple componentsUnlike the stats on command, you enable gathering of statistics for multiple components by using multiple stats and logcfg entries in the [aznapi-configuration] stanza. The stanza is in the server configuration file.In the following example, statistics gathering is enabled for the following WebSEAL components: pdweb.authnFor the pdweb.authn component: The frequency is set to 40 seconds.The destination for the statistics report is the an.log file.The component has more configuration information for the rollover_size and flush configuration settings.pdweb.jct.1For the pdweb.jct.1 component: The frequency is set to 50 seconds,The destination for the statistics report is the jct.log file.The component has more configuration information for the rollover_size and flush configuration settings.pdweb.jmtFor the pdweb.jmt component: The frequency is set to 20 seconds.The destination for the statistics report is the jmtA.log and the jmtB.log files.The component has more configuration information for the rollover_size and flush configuration settings. [aznapi-configuration] stats = pdweb.jmt 20 stats = pdweb.authn 40 stats = pdweb.jct.1 50 logcfg = stats.pdweb.jmt:file path=jmtA.log,rollover_size=-1,flush=20 logcfg = stats.pdweb.jmt:file path=jmtB.log,rollover_size=-1,flush=20 logcfg = stats.pdweb.authn:file path=an.log,rollover_size=-1,flush=20 logcfg = stats.pdweb.jct.1:file path=jct.log,rollover_size=-1,flush=20For detailed information about configuration files, see the Administering topics in the Knowledge Center.Using stanza entries for statistics

Enabling statistics for multiple components

Unlike the stats on command, you enable gathering of statistics for multiple components by using multiple stats and logcfg entries in the [aznapi-configuration] stanza. The stanza is in the server configuration file.

In the following example, statistics gathering is enabled for the following WebSEAL components:

pdweb.authn

For the pdweb.authn component:

The frequency is set to 40 seconds.

The destination for the statistics report is the an.log file.

The component has more configuration information for the rollover_size and flush configuration settings.

pdweb.jct.1

For the pdweb.jct.1 component:

The frequency is set to 50 seconds,

The destination for the statistics report is the jct.log file.

The component has more configuration information for the rollover_size and flush configuration settings.

pdweb.jmt

For the pdweb.jmt component:

The frequency is set to 20 seconds.

The destination for the statistics report is the jmtA.log and the jmtB.log files.

The component has more configuration information for the rollover_size and flush configuration settings.

[aznapi-configuration]
stats = pdweb.jmt 20
stats = pdweb.authn 40
stats = pdweb.jct.1 50
logcfg = stats.pdweb.jmt:file path=jmtA.log,rollover_size=-1,flush=20
logcfg = stats.pdweb.jmt:file path=jmtB.log,rollover_size=-1,flush=20
logcfg = stats.pdweb.authn:file path=an.log,rollover_size=-1,flush=20
logcfg = stats.pdweb.jct.1:file path=jct.log,rollover_size=-1,flush=20

For detailed information about configuration files, see the Administering topics in the Knowledge Center.

Parent topic: Using stanza entries for statistics

Security Access Manager components and activity typesserverstatistics componentslistThe following statistics components are available to Security Access Manager servers: Working with statisticspd.log.EventPool.queue componentpd.log.file.agent componentpd.log.file.clf componentpd.log.file.ref componentpd.ras.stats.monitor component

Security Access Manager components and activity types

The following statistics components are available to Security Access Manager servers:

pd.log.EventPool.queue component

pd.log.file.agent component

pd.log.file.clf component

pd.log.file.ref component

pd.ras.stats.monitor component

Parent topic: Working with statistics

pd.log.EventPool.queue componentproxy policy serverauthorization serverpd.log.EventPool.queueserverstatistics componentspd.log.EventPool.queuestatisticsserverspd.log.EventPool.queuepd.log.EventPool.queue componentThe pd.log.EventPool.queue component is the main event propagation queue. Use the statistics interface to monitor: The queuing profiles that are configured for the main propagation queue.Each file agent.Remote agent.Pipe log agent.Each queue that is created as an instance of the EventQueue object registers itself with the statistics subsystem with its category name. The category name is constructed from the logging agent type and the pd.log string.The following example shows the output from a stats get command for the pd.log.EventPool.queue component: #pdadmin> server task ivacld-instance stats get \ pd.log.EventPool.queue dispatcher wakes on timeout (20) : 3617 dispatcher wakes by notify : 0 notifies above highwater (100) : 0 notifies below highwater : 0 spurious notifies : 0 total events processed : 24 average number of events handled per activation : 1 greatest number of events handled per activation : 7 blocks in queue requests : 0In the previous output: The flush frequency for the queue is 20, the value that is denoted in the parentheses after timeout.The high water setting for the queue is 100, the value that is denoted in the parentheses after highwater.The settings that are defined for the various queue configuration options must attempt to balance: The maximum amount of memory that is consumed between queue activations, andThe rate at which a particular log agent can consume events.Set the queue high water mark such that the number of events that are processed during a queue activation fills a processing time slice. This setting avoids unnecessary thread context-switching. However, setting these options to large values is not productive. The reason is that event log processing must be done at some point and cannot be deferred indefinitely. Consuming large amounts of memory has its own drawbacks.Security Access Manager components and activity types

pd.log.EventPool.queue component

The pd.log.EventPool.queue component is the main event propagation queue. Use the statistics interface to monitor:

The queuing profiles that are configured for the main propagation queue.

Each file agent.

Remote agent.

Pipe log agent.

Each queue that is created as an instance of the EventQueue object registers itself with the statistics subsystem with its category name. The category name is constructed from the logging agent type and the pd.log string.

The following example shows the output from a stats get command for the pd.log.EventPool.queue component:

#pdadmin> server task ivacld-instance stats get \
  pd.log.EventPool.queue

dispatcher wakes on timeout (20) : 3617
dispatcher wakes by notify : 0
   notifies above highwater (100) : 0
   notifies below highwater : 0
   spurious notifies : 0
total events processed : 24
average number of events handled per activation : 1
greatest number of events handled per activation : 7
blocks in queue requests : 0

In the previous output:

The flush frequency for the queue is 20, the value that is denoted in the parentheses after timeout.

The high water setting for the queue is 100, the value that is denoted in the parentheses after highwater.

The settings that are defined for the various queue configuration options must attempt to balance:

The maximum amount of memory that is consumed between queue activations, and

The rate at which a particular log agent can consume events.

Set the queue high water mark such that the number of events that are processed during a queue activation fills a processing time slice. This setting avoids unnecessary thread context-switching. However, setting these options to large values is not productive. The reason is that event log processing must be done at some point and cannot be deferred indefinitely. Consuming large amounts of memory has its own drawbacks.

Parent topic: Security Access Manager components and activity types

pd.log.file.agent componentserverstatistics componentspd.log.file.agentstatisticsserverspd.log.file.agentpd.log.file.agent componentdispatcher wakes on timeout (20) : 299 dispatcher wakes by notify : 0 notifies above highwater (33) : 0 notifies below highwater : 0 spurious notifies : 0 total events processed : 146 average number of events handled per activation : 0 greatest number of events handled per activation : 1 blocks in queue requests : 0Security Access Manager components and activity types

pd.log.file.agent component

dispatcher wakes on timeout (20) : 299
dispatcher wakes by notify : 0
    notifies above highwater (33) : 0
    notifies below highwater : 0
    spurious notifies : 0
total events processed : 146
average number of events handled per activation : 0
greatest number of events handled per activation : 1
blocks in queue requests : 0

Parent topic: Security Access Manager components and activity types

pd.log.file.clf componentserverstatistics componentspd.log.file.clfstatisticsserverspd.log.file.clfpd.log.file.clf componentdispatcher wakes on timeout (20) : 299 dispatcher wakes by notify : 0 notifies above highwater (33) : 0 notifies below highwater : 0 spurious notifies : 0 total events processed : 147 average number of events handled per activation : 0 greatest number of events handled per activation : 1 blocks in queue requests : 0Security Access Manager components and activity types

pd.log.file.clf component

dispatcher wakes on timeout (20) : 299
dispatcher wakes by notify : 0
    notifies above highwater (33) : 0
    notifies below highwater : 0
    spurious notifies : 0
total events processed : 147
average number of events handled per activation : 0
greatest number of events handled per activation : 1
blocks in queue requests : 0

Parent topic: Security Access Manager components and activity types

pd.log.file.ref componentserverstatistics componentspd.log.file.refstatisticsserverspd.log.file.refpd.log.file.ref componentdispatcher wakes on timeout (20) : 300 dispatcher wakes by notify : 0 notifies above highwater (33) : 0 notifies below highwater : 0 spurious notifies : 0 total events processed : 148 average number of events handled per activation : 0 greatest number of events handled per activation : 1 blocks in queue requests : 0Security Access Manager components and activity types

pd.log.file.ref component

dispatcher wakes on timeout (20) : 300
dispatcher wakes by notify : 0
    notifies above highwater (33) : 0
    notifies below highwater : 0
    spurious notifies : 0
total events processed : 148
average number of events handled per activation : 0
greatest number of events handled per activation : 1
blocks in queue requests : 0

Parent topic: Security Access Manager components and activity types

pd.ras.stats.monitor componentserverstatistics componentspd.ras.stats.monitorstatisticsserverspd.ras.stats.monitorpd.ras.stats.monitor component5 components reporting statistics 5 reports generatedSecurity Access Manager components and activity types

pd.ras.stats.monitor component

5 components reporting statistics
5 reports generated

Parent topic: Security Access Manager components and activity types

WebSEAL components and activity typesWebSEALstatistics componentslistThe following statistics components are available to WebSEAL instances: Working with statisticspdweb.authn componentpdweb.authz componentpdweb.doccache componentpdweb.http componentpdweb.https componentpdweb.jct.# componentpdweb.jmt componentpdweb.sescache componentpdweb.threads component

WebSEAL components and activity types

The following statistics components are available to WebSEAL instances:

pdweb.authn component

pdweb.authz component

pdweb.doccache component

pdweb.http component

pdweb.https component

pdweb.jct.# component

pdweb.jmt component

pdweb.sescache component

pdweb.threads component

Parent topic: Working with statistics

pdweb.authn componentWebSEALstatistics componentspdweb.authnstatisticsWebSEAL componentspdweb.authnpdweb.authn componentThe pdweb.authn statistics component gathers information about WebSEAL authentication. The following list describes the types of available information: passThe total number of successful authentications.failThe total number of failed authentications.pwd expThe total number of authentication attempts that were made with an expired password.maxThe maximum time for a single authentication process.avgThe average time for a single authentication process.totalThe total time for all authentication processing.The following example shows the output from a stats get command for the pdweb.authn component: #pdadmin> server task default-webseald-instance stats get pdweb.authn pass : 2 fail : 1 pwd exp : 0 max : 0.178 avg : 0.029 total : 0.382WebSEAL components and activity types

pdweb.authn component

The pdweb.authn statistics component gathers information about WebSEAL authentication. The following list describes the types of available information:

pass

The total number of successful authentications.

fail

The total number of failed authentications.

pwd exp

The total number of authentication attempts that were made with an expired password.

max

The maximum time for a single authentication process.

avg

The average time for a single authentication process.

total

The total time for all authentication processing.

The following example shows the output from a stats get command for the pdweb.authn component:

#pdadmin> server task default-webseald-instance stats get pdweb.authn

pass     : 2
fail     : 1
pwd exp  : 0
max      : 0.178
avg      : 0.029
total    : 0.382

Parent topic: WebSEAL components and activity types

pdweb.authz componentWebSEALstatistics componentspdweb.authzstatisticsWebSEAL componentspdweb.authzpdweb.authz componentThe pdweb.authz statistics component gathers information about WebSEAL authorization. The following list describes the types of available information: passThe total number of successful authorization requests. That is, the total number of resources that were successfully accessed.failThe total number of failed authorization requests.The following example shows the output from a stats get command for the pdweb.authz component: #pdadmin> server task default-webseald-instance stats get pdweb.authz pass : 2 fail : 1WebSEAL components and activity types

pdweb.authz component

The pdweb.authz statistics component gathers information about WebSEAL authorization. The following list describes the types of available information:

pass

The total number of successful authorization requests. That is, the total number of resources that were successfully accessed.

fail

The total number of failed authorization requests.

The following example shows the output from a stats get command for the pdweb.authz component:

#pdadmin> server task default-webseald-instance stats get pdweb.authz

pass     : 2
fail     : 1

Parent topic: WebSEAL components and activity types

pdweb.doccache componentWebSEALstatistics componentspdweb.doccachestatisticsWebSEAL componentspdweb.doccachepdweb.doccache componentThe pdweb.doccache statistics component gathers information about WebSEAL document-caching activity. This component reports statistics for all MIME types that aer enabled in the [content-cache] stanza of the WebSEAL configuration file. This component is always enabled by default and cannot be disabled.The following list describes the types of global information available for all MIME types: General ErrorsThe number of errors reported by the pdweb.doccache component when there are memory allocation failures, initialization failures, or invalid MIME type header values.UncachableThe number of instances when there is no cache that is defined for the MIME type of the document to be cached.Pending DeletesThe number of entries that are marked for deletion, but these entries are still in use.Pending SizeThe number of bytes that are used by entries that are marked for deletion, but these entries are still in use.MissesThe number of times a URL is looked up in the document cache and is not found. A found cached document eliminates the need to access the real document again.Cache MIME typeThe MIME type of documents that is stored in this cache. The following list describes the cache MIME types: Max sizeThe maximum combined byte size of all documents in the cache.Max entry sizeThe maximum byte size for any single cached document. If the document size exceeds this internally calculated value, it is not cached.SizeThe total byte count for all documents currently located in the cache.CountThe current number of entries in the cache.HitsThe number of successful lookups. (Documents that are successfully found in the cache.)Stale hitsThe number of successful lookups that found an entry that was too old and was purged instead.Create waitsThe number of times subsequent requests for a document are blocked (made to wait) while the document content is initially being cached.Cache no roomThe number of times a document that is valid for caching cannot fit into the cache. The reason is that there are too many entries that are being created at the same time.AdditionsThe number of successful new entries in the cache.AbortsThe number of times the creation of a new cache entry is canceled. The reason might be a header that indicates the entry must not be cached.DeletesThe number of cache entries that were deleted because the entry is stale (expired) or because the creation was canceled.UpdatesThe number of entries that had expiry times updated.Too big errorThe number of attempts to cache documents that exceed the maximum entry size (and therefore are not cached).MT errorsThe number of times more than one thread tries to create the same entry in the cache. (MT=Multi-Threading)The following example shows the output from a stats get command for the pdweb.doccache component: #pdadmin> server task default-webseald-instance stats get pdweb.doccache General Errors : 0 Uncachable : 0 Pending Deletes: 0 Pending Size : 0 Misses : 0 Cache MIME type : text/html Max size : 2048000 Max entry size : 128000 Size : 0 Count : 0 Hits : 0 Stale hits : 0 Create waits : 0 Cache no room : 0 Additions : 0 Aborts : 0 Deletes : 0 Updates : 0 Too big errors : 0 MT errors : 0WebSEAL components and activity types

pdweb.doccache component

The pdweb.doccache statistics component gathers information about WebSEAL document-caching activity. This component reports statistics for all MIME types that aer enabled in the [content-cache] stanza of the WebSEAL configuration file. This component is always enabled by default and cannot be disabled.

The following list describes the types of global information available for all MIME types:

General Errors

The number of errors reported by the pdweb.doccache component when there are memory allocation failures, initialization failures, or invalid MIME type header values.

Uncachable

The number of instances when there is no cache that is defined for the MIME type of the document to be cached.

Pending Deletes

The number of entries that are marked for deletion, but these entries are still in use.

Pending Size

The number of bytes that are used by entries that are marked for deletion, but these entries are still in use.

Misses

The number of times a URL is looked up in the document cache and is not found. A found cached document eliminates the need to access the real document again.

Cache MIME type

The MIME type of documents that is stored in this cache. The following list describes the cache MIME types:

Max size

The maximum combined byte size of all documents in the cache.

Max entry size

The maximum byte size for any single cached document. If the document size exceeds this internally calculated value, it is not cached.

Size

The total byte count for all documents currently located in the cache.

Count

The current number of entries in the cache.

Hits

The number of successful lookups. (Documents that are successfully found in the cache.)

Stale hits

The number of successful lookups that found an entry that was too old and was purged instead.

Create waits

The number of times subsequent requests for a document are blocked (made to wait) while the document content is initially being cached.

Cache no room

The number of times a document that is valid for caching cannot fit into the cache. The reason is that there are too many entries that are being created at the same time.

Additions

The number of successful new entries in the cache.

Aborts

The number of times the creation of a new cache entry is canceled. The reason might be a header that indicates the entry must not be cached.

Deletes

The number of cache entries that were deleted because the entry is stale (expired) or because the creation was canceled.

Updates

The number of entries that had expiry times updated.

Too big error

The number of attempts to cache documents that exceed the maximum entry size (and therefore are not cached).

MT errors

The number of times more than one thread tries to create the same entry in the cache. (MT=Multi-Threading)

The following example shows the output from a stats get command for the pdweb.doccache component:

#pdadmin> server task default-webseald-instance stats get pdweb.doccache

General Errors : 0
Uncachable     : 0
Pending Deletes: 0
Pending Size   : 0
Misses         : 0
Cache MIME type  : text/html
  Max size       : 2048000
  Max entry size : 128000
  Size           : 0
  Count          : 0
  Hits           : 0
  Stale hits     : 0
  Create waits   : 0
  Cache no room  : 0
  Additions      : 0
  Aborts         : 0
  Deletes        : 0
  Updates        : 0
  Too big errors : 0
  MT errors      : 0

Parent topic: WebSEAL components and activity types

pdweb.http componentWebSEALstatistics componentspdweb.httpstatisticsWebSEAL componentspdweb.httppdweb.http componentThe pdweb.http statistics component gathers information about WebSEAL HTTP communication. The following list describes the types of available information: reqsThe total number of HTTP requests received.max-workerThe maximum time that is used by a single worker thread to process an HTTP request.total-workerThe total time that is used by all worker threads that process HTTP requests.max-websealThe maximum time that is used to process a single HTTP request - measured inside the worker thread, after the request headers are read, and eliminating connection setup overhead.total-websealThe total time that is used to process all HTTP requests - measured inside the worker threads, after the request headers are read, and eliminating connection setup overhead.The following example shows the output from a stats get command for the pdweb.http component: #pdadmin> server task default-webseald-instance stats get pdweb.http reqs : 0 max-worker : 0.000 total-worker : 0.000 max-webseal : 0.000 total-webseal : 0.000WebSEAL components and activity types

pdweb.http component

The pdweb.http statistics component gathers information about WebSEAL HTTP communication. The following list describes the types of available information:

reqs

The total number of HTTP requests received.

max-worker

The maximum time that is used by a single worker thread to process an HTTP request.

total-worker

The total time that is used by all worker threads that process HTTP requests.

max-webseal

The maximum time that is used to process a single HTTP request - measured inside the worker thread, after the request headers are read, and eliminating connection setup overhead.

total-webseal

The total time that is used to process all HTTP requests - measured inside the worker threads, after the request headers are read, and eliminating connection setup overhead.

The following example shows the output from a stats get command for the pdweb.http component:

#pdadmin> server task default-webseald-instance stats get pdweb.http
reqs             : 0
max-worker       : 0.000
total-worker     : 0.000
max-webseal      : 0.000
total-webseal    : 0.000

Parent topic: WebSEAL components and activity types

pdweb.https componentWebSEALstatistics componentspdweb.httpsstatisticsWebSEAL componentspdweb.httpspdweb.https componentThe pdweb.https statistics component gathers information about WebSEAL HTTPS communication. The following list describes the types of available information: reqsThe total number of HTTPS requests received.max-workerThe maximum time that is used by a single worker thread to process an HTTPS request.total-workerThe total time that is used by all worker threads that process HTTPS requests.max-websealThe maximum time that is used to process a single HTTPS request - measured inside the worker thread, after the request headers are read, and eliminating connection setup overhead.total-websealThe total time that is used to process all HTTPS requests - measured inside the worker threads, after the request headers are read, and eliminating connection setup overhead.The following example shows the output from a stats get command for the pdweb.https component: #pdadmin> server task default-webseald-instance stats get pdweb.https reqs : 0 max-worker : 0.000 total-worker : 0.000 max-webseal : 0.000 total-webseal : 0.000WebSEAL components and activity types

pdweb.https component

The pdweb.https statistics component gathers information about WebSEAL HTTPS communication. The following list describes the types of available information:

reqs

The total number of HTTPS requests received.

max-worker

The maximum time that is used by a single worker thread to process an HTTPS request.

total-worker

The total time that is used by all worker threads that process HTTPS requests.

max-webseal

The maximum time that is used to process a single HTTPS request - measured inside the worker thread, after the request headers are read, and eliminating connection setup overhead.

total-webseal

The total time that is used to process all HTTPS requests - measured inside the worker threads, after the request headers are read, and eliminating connection setup overhead.

The following example shows the output from a stats get command for the pdweb.https component:

#pdadmin> server task default-webseald-instance stats get pdweb.https

reqs             : 0
max-worker       : 0.000
total-worker     : 0.000
max-webseal      : 0.000
total-webseal    : 0.000

Parent topic: WebSEAL components and activity types

pdweb.jct.# componentWebSEALstatistics componentspdweb.jct.#statisticsWebSEAL componentspdweb.jct.#pdweb.jct.# componentThe pdweb.jct.# statistics component gathers information about configured junctions. The following list describes the types of available information: [/]The actual junction name (listed as the number in the command)reqsThe total number of requests that are routed across this junctionmaxThe maximum time that is consumed by a single request across this junctiontotalThe total time that is consumed by requests across this junctionThe following example shows the output from a stats get command for the pdweb.jct.1 component: #pdadmin> server task default-webseald-instance stats get pdweb.jct.1 [/] reqs : 0 max : 0.000 total : 0.000WebSEAL components and activity types

pdweb.jct.# component

The pdweb.jct.# statistics component gathers information about configured junctions. The following list describes the types of available information:

[/]

The actual junction name (listed as the number in the command)

reqs

The total number of requests that are routed across this junction

max

The maximum time that is consumed by a single request across this junction

total

The total time that is consumed by requests across this junction

The following example shows the output from a stats get command for the pdweb.jct.1 component:

#pdadmin> server task default-webseald-instance stats get pdweb.jct.1

[/]
reqs    : 0
max     : 0.000
total   : 0.000

Parent topic: WebSEAL components and activity types

pdweb.jmt componentWebSEALstatistics componentspdweb.jmtstatisticsWebSEAL componentspdweb.jmtpdweb.jmt componentThe pdweb.jmt statistics component gathers information about the WebSEAL junction mapping table. This component is always enabled by default and cannot be disabled. The following list describes the types of available information: hitsThe total number of requests that required URL mapping with the junction mapping table.The following example shows the output from a stats get command for the pdweb.jmt component: #pdadmin> server task default-webseald-instance stats get pdweb.jmt hits : 5WebSEAL components and activity types

pdweb.jmt component

The pdweb.jmt statistics component gathers information about the WebSEAL junction mapping table. This component is always enabled by default and cannot be disabled. The following list describes the types of available information:

hits

The total number of requests that required URL mapping with the junction mapping table.

The following example shows the output from a stats get command for the pdweb.jmt component:

#pdadmin> server task default-webseald-instance stats get pdweb.jmt

hits  : 5

Parent topic: WebSEAL components and activity types

pdweb.sescache componentWebSEALstatistics componentspdweb.sescacheWebSEALstatistics componentspdweb.certcallbackcacheWebSEALstatistics componentspdweb.usersessidcachestatisticsWebSEAL componentspdweb.sescachestatisticsWebSEAL componentspdweb.certcallbackcachestatisticsWebSEAL componentspdweb.usersessidcachepdweb.sescache componentpdweb.certcallbackcache componentpdweb.usersessidcache componentThe pdweb.sescache component gathers statistics about the WebSEAL session cache. This component gathers the following activity information: hitThe number of requests where a cache entry for a user was referenced successfully. That is, the number of requests that resulted in a session cache hit.missThe number of requests that missed a session cache hit.addThe number of cache entries that was added to the session cache.delThe number of cache entries that was deleted from the session cache.inactiveThe number of times where a cache entry hit the inactivity timeout.lifetimeThe number of times where a cache entry hit the lifetime timeout.LRU expiredThe number of times that a least recently used cache entry was deleted from the session cache to make room for a new cache entry.The following example shows the output from a stats get command for the pdweb.sescache component: pdadmin sec_master> server task default-webseald-instance stats get pdweb.sescache hit : 225 miss : 75 add : 375 del : 150 inactive : 60 lifetime : 15 LRU expired : 75In the previous release, the pdweb.sescache component contained activity that was associated with callback certificates and user session mappings. These statistics are now managed by the following components: pdweb.certcallbackcacheThis cache stores the SSL IDs of sessions that require certificate validation when a user is stepping up. The reported information has the same categories as pdweb.sescache. These activities are internal.pdweb.usersessidcacheThis cache stores a mapping of users to their sessions. The reported information has the same categories as pdweb.sescache. These activities are internal.Therefore, the first time that you gather statistics for the pdweb.sescache component and compare it to your last report, the figures might appear to be wrong. To set a new baseline, add the statistics from the following components and then compare them to your previous baseline (last pdweb.sescache report): pdweb.sescachepdweb.certcallbackcachepdweb.usersessidcacheThe output against the pdweb.sescache component must be your new baseline.WebSEAL components and activity types

pdweb.sescache component

The pdweb.sescache component gathers statistics about the WebSEAL session cache. This component gathers the following activity information:

hit

The number of requests where a cache entry for a user was referenced successfully. That is, the number of requests that resulted in a session cache hit.

miss

The number of requests that missed a session cache hit.

add

The number of cache entries that was added to the session cache.

del

The number of cache entries that was deleted from the session cache.

inactive

The number of times where a cache entry hit the inactivity timeout.

lifetime

The number of times where a cache entry hit the lifetime timeout.

LRU expired

The number of times that a "least recently used" cache entry was deleted from the session cache to make room for a new cache entry.

The following example shows the output from a stats get command for the pdweb.sescache component:

pdadmin sec_master>  server task default-webseald-instance stats get pdweb.sescache
hit      : 225
miss     : 75
add      : 375
del      : 150
inactive : 60
lifetime : 15
LRU expired : 75

In the previous release, the pdweb.sescache component contained activity that was associated with callback certificates and user session mappings. These statistics are now managed by the following components:

pdweb.certcallbackcache

This cache stores the SSL IDs of sessions that require certificate validation when a user is stepping up. The reported information has the same categories as pdweb.sescache. These activities are internal.

pdweb.usersessidcache

This cache stores a mapping of users to their sessions. The reported information has the same categories as pdweb.sescache. These activities are internal.

Therefore, the first time that you gather statistics for the pdweb.sescache component and compare it to your last report, the figures might appear to be wrong. To set a new baseline, add the statistics from the following components and then compare them to your previous baseline (last pdweb.sescache report):

pdweb.sescache

pdweb.certcallbackcache

pdweb.usersessidcache

The output against the pdweb.sescache component must be your new baseline.

Parent topic: WebSEAL components and activity types

pdweb.threads componentWebSEALstatistics componentspdweb.threadsstatisticsWebSEAL componentspdweb.threadspdweb.threads componentThe pdweb.threads statistics component gathers information about WebSEAL worker thread activity. Its report is the overall thread usage statistics that include not just request traffic, but all the worker threads for the WebSEAL process.WebSEAL, version 6.0, and later can be configured to use multiple interfaces. Each separately configured interface can use a separate worker thread pool. The thread pool has the same name as the specified interface. Alternatively, all configured interfaces can share worker thread pool. The default WebSEAL interface configuration uses the default name to differentiate between that interface and the corresponding thread pool, from other separately configured interfaces. The default WebSEAL interface configuration is defined under the [server] stanza. A separately configured WebSEAL interface (defined under the [interfaces] stanza) uses the specified name.The pdweb.threads component is always enabled by default and cannot be disabled. The following list describes the types of available information: activeThe total number of active worker threads of all WebSEAL interfaces that are handling requests.totalThe total number of worker threads that are configured for all WebSEAL interfaces.'default' activeThe total number of active worker threads in the default interface thread pool that are handling requests. If you do not configure one or more more WebSEAL interfaces, the value of default active matches the value of active.'default' totalThe total number of configured worker threads for the default interface thread pool. If you do not configure one or more more WebSEAL interfaces, the value of default total matches the value of total.'other_interface' activeThe total number of active worker threads in the thread pool that is handling requests for an additional configured interface. other_interface is the name that is assigned to the interface.'other_interface' totalThe total number of worker threads in the thread pool that is used by an additional interface named other_interface.The following example shows the output from a stats get command for the pdweb.threads component. The example assumes that no additional WebSEAL interface is configured: #pdadmin> server task default-webseald-instance stats get pdweb.threads active : 0 total : 50 'default' active : 0 'default' total : 50WebSEAL components and activity types

pdweb.threads component

The pdweb.threads statistics component gathers information about WebSEAL worker thread activity. Its report is the overall thread usage statistics that include not just request traffic, but all the worker threads for the WebSEAL process.

WebSEAL, version 6.0, and later can be configured to use multiple interfaces. Each separately configured interface can use a separate worker thread pool. The thread pool has the same name as the specified interface.

Alternatively, all configured interfaces can share worker thread pool. The default WebSEAL interface configuration uses the default name to differentiate between that interface and the corresponding thread pool, from other separately configured interfaces. The default WebSEAL interface configuration is defined under the [server] stanza. A separately configured WebSEAL interface (defined under the [interfaces] stanza) uses the specified name.

The pdweb.threads component is always enabled by default and cannot be disabled. The following list describes the types of available information:

active

The total number of active worker threads of all WebSEAL interfaces that are handling requests.

total

The total number of worker threads that are configured for all WebSEAL interfaces.

'default' active

The total number of active worker threads in the default interface thread pool that are handling requests. If you do not configure one or more more WebSEAL interfaces, the value of default active matches the value of active.

'default' total

The total number of configured worker threads for the default interface thread pool. If you do not configure one or more more WebSEAL interfaces, the value of default total matches the value of total.

'other_interface' active

The total number of active worker threads in the thread pool that is handling requests for an additional configured interface. other_interface is the name that is assigned to the interface.

'other_interface' total

The total number of worker threads in the thread pool that is used by an additional interface named other_interface.

The following example shows the output from a stats get command for the pdweb.threads component. The example assumes that no additional WebSEAL interface is configured:

#pdadmin> server task default-webseald-instance stats get pdweb.threads
active   : 0
total    : 50
'default' active : 0
'default' total : 50

Parent topic: WebSEAL components and activity types

Audit eventsAuditingThe IBM Security Access Manager provides information about configuring and managing audit events.XML output of native audit eventsElements by event typesThis section lists the elements that are available for each common audit event type.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

Audit events

XML output of native audit events

Elements by event types
This section lists the elements that are available for each common audit event type.

Reference information about elements and element types
This section defines the various elements and element types that are available for the common audit event types.

Parent topic: Auditing

XML output of native audit eventsaudit eventsXML outputWhen you use native Security Access Manager auditing, audit events are captured in the audit trail in a standard format with the Extensible Markup Language (XML) elements. XML is only an intermediary step to delivering a presentation view of the data. The XML file is in ASCII format and can be read directly or passed to other external parsing engines for further analysis.Audit eventsDTD intermediate formatData blocks and output elementsXML output elementsAction codes for management commandsAuthentication failures

XML output of native audit events

When you use native Security Access Manager auditing, audit events are captured in the audit trail in a standard format with the Extensible Markup Language (XML) elements. XML is only an intermediary step to delivering a presentation view of the data. The XML file is in ASCII format and can be read directly or passed to other external parsing engines for further analysis.

DTD intermediate format

Data blocks and output elements

XML output elements

Action codes for management commands

Authentication failures

Parent topic: Audit events

DTD intermediate formatDTD audit events formatDocument Type Definitionformataudit eventsaudit trail file formatAs an audit administrator, you are expected to select and extract events according to your own criteria. This activity might include reformatting each event by applying an appropriate Document Type Definition (DTD) or schema for the analysis tool that you are using. The DTD is an intermediate format that provides a description of the data that can be captured.XML output of native audit events

DTD intermediate format

As an audit administrator, you are expected to select and extract events according to your own criteria. This activity might include reformatting each event by applying an appropriate Document Type Definition (DTD) or schema for the analysis tool that you are using. The DTD is an intermediate format that provides a description of the data that can be captured.

Parent topic: XML output of native audit events

Data blocks and output elementsXMLaudit trail output elementsoutput elementselements, XML outputAn entire audit trail does not represent a single XML document. Each audit event within the file is written as an isolated XML data block. Each data block conforms to the rules of standard XML syntax.XML output of native audit eventsSample authorization eventSample resource access eventSample successful authentication eventsSample failed authentication eventsSample authentication terminate event

Data blocks and output elements

An entire audit trail does not represent a single XML document. Each audit event within the file is written as an isolated XML data block. Each data block conforms to the rules of standard XML syntax.

Sample authorization event

Sample resource access event

Sample successful authentication events

Sample failed authentication events

Sample authentication terminate event

Parent topic: XML output of native audit events

Sample authorization eventaudit eventsXML outputFor example, the following data block is an audit record for getting user authorization credentials: <event rev="1.2"> <date>2005-11-14-16:25:08.341+00:00I-----</date> <outcome status="0">0</outcome> <originator blade="pdmgrd"> <component rev="1.2">azn</component> <action>0</action> <location>phaedrus</location> </originator> <accessor name=""> <principal auth="IV_LDAP_V3.0">sec_master</principal> </accessor> <target resource="3"> <object>IV_LDAP_V3.0:sec_master</object> </target> <data>azn_id_get_creds</data> </event>Data blocks and output elements

Sample authorization event

For example, the following data block is an audit record for getting user authorization credentials:

<event rev="1.2">
  <date>2005-11-14-16:25:08.341+00:00I-----</date>
  <outcome status="0">0</outcome>
  <originator blade="pdmgrd">
    <component rev="1.2">azn</component>
    <action>0</action>
    <location>phaedrus</location>
  </originator>
  <accessor name="">
    <principal auth="IV_LDAP_V3.0">sec_master</principal>
  </accessor>
  <target resource="3">
    <object>IV_LDAP_V3.0:sec_master</object>
  </target>
  <data>azn_id_get_creds</data>
</event>

Parent topic: Data blocks and output elements

Sample resource access eventresource access eventssampleFor example, the following data block is an audit record for an HTTP request: <event rev="1.2"> <date>2005-10-02-22:01:36.187-04:00I-----</date> <outcome status="953091111" reason="unauthorized">1</outcome> <originator blade="webseald" instance="default"> <component rev="1.2">http</component> <event_id>109</event_id> <action>1</action> <location>cmd.wma.ibm.com</location> </originator> <accessor name="unauthenticated"> <principal auth="IV_UNAUTH_V3.0" domain="Default">Unauthenticated</principal> <user_location>9.54.83.206</user_location> <user_location_type>IPV4</user_location_type> </accessor> <target resource="5"> <object>/</object> <object_nameinapp>HTTP://cmd.wma.ibm.com:80/</object_nameinapp> </target> <resource_access> <action>httpRequest</action> <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl> <httpmethod>GET</httpmethod> <httpresponse>200</httpresponse> </resource_access> <data> GET HTTP://cmd.wma.ibm.com:80/ HTTP/1.0 1970 Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1) </data> </event>Data blocks and output elements

Sample resource access event

For example, the following data block is an audit record for an HTTP request:

<event rev="1.2">
  <date>2005-10-02-22:01:36.187-04:00I-----</date>
  <outcome status="953091111" reason="unauthorized">1</outcome>
  <originator blade="webseald" instance="default">
    <component rev="1.2">http</component>
    <event_id>109</event_id>
    <action>1</action>
    <location>cmd.wma.ibm.com</location>
  </originator>
  <accessor name="unauthenticated">
    <principal auth="IV_UNAUTH_V3.0" domain="Default">Unauthenticated</principal>
    <user_location>9.54.83.206</user_location>
    <user_location_type>IPV4</user_location_type>
  </accessor>
  <target resource="5">
    <object>/</object>
    <object_nameinapp>HTTP://cmd.wma.ibm.com:80/</object_nameinapp>
  </target>
  <resource_access>
    <action>httpRequest</action>
    <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl>
    <httpmethod>GET</httpmethod>
    <httpresponse>200</httpresponse>
  </resource_access>
  <data>
    GET HTTP://cmd.wma.ibm.com:80/ HTTP/1.0
    1970
    Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)
  </data>
</event>

Parent topic: Data blocks and output elements

Sample successful authentication eventsauthenticationeventsuccessful, sample ofFor example, the following data block is an audit record for a successful authentication: <event rev="1.2"> <date>2005-10-02-21:59:31.980-04:00I-----</date> <outcome status="0">0</outcome> <originator blade="webseald" instance="default"> <component rev="1.4">authn</component> <event_id>101</event_id> <action>0</action> <location>cmd.wma.ibm.com</location> </originator> <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default">testuser268</principal> <name_in_rgy>cn=testuser268,dc=ibm,dc=com</name_in_rgy> <session_id>56a701a4-33b1-11da-a8d3-00096bc369d2</session_id> <user_location>9.54.83.206</user_location> <user_location_type>IPV4</user_location_type> </accessor> <target resource="7"> <object></object> </target> <authntype>formsPassword</authntype> <data></data> </event>Data blocks and output elements

Sample successful authentication events

For example, the following data block is an audit record for a successful authentication:

<event rev="1.2">
  <date>2005-10-02-21:59:31.980-04:00I-----</date>
  <outcome status="0">0</outcome>
  <originator blade="webseald" instance="default">
    <component rev="1.4">authn</component>
    <event_id>101</event_id>
    <action>0</action>
    <location>cmd.wma.ibm.com</location>
  </originator>
  <accessor name="">
    <principal auth="IV_LDAP_V3.0" domain="Default">testuser268</principal>
    <name_in_rgy>cn=testuser268,dc=ibm,dc=com</name_in_rgy>
    <session_id>56a701a4-33b1-11da-a8d3-00096bc369d2</session_id>
    <user_location>9.54.83.206</user_location>
    <user_location_type>IPV4</user_location_type>
  </accessor>
  <target resource="7">
    <object></object>
  </target>
  <authntype>formsPassword</authntype>
  <data></data>
</event>

Parent topic: Data blocks and output elements

Sample failed authentication eventsauthenticationeventfailed, sample ofFor example, the following data block is an audit record for a failed authentication: <event rev="1.2"> <date>2005-10-02-21:59:31.977-04:00I-----</date> <outcome status="320938184" reason="authenticationFailure">1</outcome> <originator blade="webseald" instance="default"> <component rev="1.4">authn</component> <event_id>101</event_id> <action>0</action> <location>cmd.wma.ibm.com</location> </originator> <accessor name=""> <principal auth="" domain="">testuser335</principal> <user_location>9.54.83.206</user_location> <user_location_type>IPV4</user_location_type> </accessor> <target resource="7"> <object></object> </target> <authntype>formsPassword</authntype> <data> Password Failure: testuser335 </data> </event>Data blocks and output elements

Sample failed authentication events

For example, the following data block is an audit record for a failed authentication:

<event rev="1.2">
  <date>2005-10-02-21:59:31.977-04:00I-----</date>
  <outcome status="320938184" reason="authenticationFailure">1</outcome>
  <originator blade="webseald" instance="default">
    <component rev="1.4">authn</component>
    <event_id>101</event_id>
    <action>0</action>
    <location>cmd.wma.ibm.com</location>
  </originator>
  <accessor name="">
    <principal auth="" domain="">testuser335</principal>
    <user_location>9.54.83.206</user_location>
    <user_location_type>IPV4</user_location_type>
  </accessor>
  <target resource="7">
    <object></object>
  </target>
  <authntype>formsPassword</authntype>
  <data>
    Password Failure: testuser335
  </data>
</event>

Parent topic: Data blocks and output elements

Sample authentication terminate eventauthenticationeventterminate, sample ofFor example, the following data block is an audit record for the termination of an authentication: <event rev="1.2"> <date>2005-10-04-11:45:27.487-04:00I-----</date> <outcome status="0">0</outcome> <originator blade="webseald" instance="default"> <component rev="1.4">authn</component> <event_id>103</event_id> <action>103</action> <location>cmd.wma.ibm.com</location> </originator> <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default">testuser1</principal> <name_in_rgy>cn=testuser1,dc=ibm,dc=com</name_in_rgy> <session_id>e005b3ae-34ed-11da-a016-00096bc369d2</session_id> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> <target resource="7"> <object></object> </target> <authntype>formsPassword</authntype> <terminateinfo> <terminatereason>userLoggedOut</terminatereason> </terminateinfo> <data></data> </event>Data blocks and output elements

Sample authentication terminate event

For example, the following data block is an audit record for the termination of an authentication:

<event rev="1.2">
  <date>2005-10-04-11:45:27.487-04:00I-----</date>
  <outcome status="0">0</outcome>
  <originator blade="webseald" instance="default">
    <component rev="1.4">authn</component>
    <event_id>103</event_id>
    <action>103</action>
    <location>cmd.wma.ibm.com</location>
  </originator>
  <accessor name="">
    <principal auth="IV_LDAP_V3.0" domain="Default">testuser1</principal>
    <name_in_rgy>cn=testuser1,dc=ibm,dc=com</name_in_rgy>
    <session_id>e005b3ae-34ed-11da-a016-00096bc369d2</session_id>
    <user_location>9.65.85.162</user_location>
    <user_location_type>IPV4</user_location_type>
  </accessor>
  <target resource="7">
    <object></object>
  </target>
  <authntype>formsPassword</authntype>
  <terminateinfo>
    <terminatereason>userLoggedOut</terminatereason>
  </terminateinfo>
  <data></data>
</event>

Parent topic: Data blocks and output elements

XML output elementsXML output elementseventsoutput elementoutcome output elementoriginator output elementaction output elementoriginatorcomponent output elementevent_id output elementsource output elementperm output elementaction codeseventsauthorizationaction codeseventsauthenticationaction codeseventschange passwordaction codeseventsWebSEALazn output elementaudit output elementdataoutput elementterminatereason output elementterminateinfo output elementauthntype output elementhttpresponse output elementhttpmethod output elementaction codeseventsmanagementlocation output elementhttpurl output elementaccessorsoutput elementprincipal output elementname_in_rgy output elementaction output elementresource_accessresource_access output elementvalue output elementtype output elementsession_id output elementuser_location output elementname output elementuser_location_type output elementattributesoutput elementtarget output elementdescr output elementresult output elementpolicy output elementprocess output elementobject output elementqualifier output elementname output elementTable 1 describes the XML output elements that are possible by using the default Security Access Manager DTD elements. If you create your own DTD, each element must represent the events that you selected and extracted according to your own criteria.Names and descriptions for XML output elementsOutput element nameDescription <event> ... </event> Auditing event. Each auditing event captures the result of an action. A principal attempts an action on a target object. The event element can include the following elements: dateoutcomeoriginatoraccessortargetresource_access (for resource access events)authntype (for authentication events)terminationinfo (for authentication terminate events)data Because Security Access Manager auditing uses a standard record format, not all elements are relevant to each event that is recorded. Fields that are not relevant for a particular event might contain a default value. The event element can include the following attribute: rev Example: <event rev="1.2"> <date>2003-11-14-16:25:08.341+00:00I-----</date> <outcome status="0">0</outcome> ... </event> <date> ... </date> Current date and timestamp. The date element has the following format: yyyy-mm-dd-hh:mm:ss.xxx-xx:xxI----- Where: yyyy-mm-ddRelates to the year (yyyy), the month (mm), and the day (dd).hh:mm:ssRelates to hours (hh), minutes (mm), and seconds (ss).xxx-xx:xxIRefers to the time zone. Example: <event rev="1.2"> <date>2005-11-14-16:25:08.341+00-----</date> ... </event> <outcome> ... </outcome> Outcome of the event. The outcome element can be one of the following values: 0Success1Failure2Pending3Unknown The following information is captured in a common format header of the audit record: The outcome.The action.The credentials for the principal.The target object. This element can include the following attributes: statusreason Example of a failed event: <outcome status="320938184" reason="authenticationFailure"> 1 </outcome> For information about the contents of the status attribute, use the errtext command. The command provides the error message that is associated with the status code (320938184) of a failed event. If the error is not identified by the errtext command, the error did not originate in Security Access Manager. See your third-party documentation for more status code definitions. For information about the contents of the reason attribute, see Outcome output for failures. Example of a successful event: <event rev="1.2"> ... <outcome status="0">0</outcome> ... </event> <originator> ... </originator> Server that originated the event being logged. The originator element can include the following elements: componentevent_idactionlocation The originator element can include the following attributes: bladeinstanceThe blade attributes represents the server that originated the event. For example, pdmgrd is the Security Access Manager policy server, webseald is the Security Access Manager WebSEAL server. The instance attribute applies to WebSEAL and represents the name of the instance. Example: <event rev="1.2"> ... <originator blade="webseald"> <component rev="1.4">authn</component> <event_id>101</event_id> <action>0</action> <location>cmd.wma.ibm.com</location> </originator> ... </event> <component> ... </component> Audit events, categorized by the server functionality that generates them. Some functionality is common across Security Access Manager servers while other functionality is server-specific. The component element can be one of the following values: authz or aznCaptures authorization events.authnCaptures authentication events.mgmtCaptures management events.httpCaptures WebSEAL HTTP events. See the Configuring topics in the Knowledge Center for more information about this value. The component element can contain the rev attribute. Example: <originator blade="webseald"> <component rev="1.4">authn</component> <event_id>101</event_id> <action>0</action> <location>cmd.wma.ibm.com</location> </originator> <event_id> ... </event_id> The category of the event ID. The event_id element can be one of the following values: 101Login102Password change103Logout104Authenticate105Step-up106Re-authentication107Credentials refresh108Authorization check109Resource access110Get credentials111Modify credentials/combine credentials112Get credentials from pac113Get pac114Get entitlements115Runtime start116Runtime stop117Runtime audit start118Runtime audit stop119Runtime audit level change120Runtime statistic121Runtime heartbeat up122Runtime heartbeat down123Runtime lost contact124Runtime contact restored125Runtime monitor126Switch-user login127Switch-user logout Example: <originator blade="webseald"> <component rev="1.4">authn</component> <event_id>101</event_id> <action>0</action> <location>cmd.wma.ibm.com</location> </originator> <action> ... </action> Audit record action code, which can be for one of the following groups of events: Authentication or authorization eventsAudit records for authentication or authorization events contain one of the following event action codes: 0Authentication or authorization events1Change password events2WebSEAL eventsManagement eventsAudit records for management events contain an action code that identifies the pdadmin utility. For example, the <action>13702</action> action code relates to the POP_MODIFY action for the pop modify command. See Action codes for management commands, which relates the action code reference number for each command. A common format header of the audit record captures information about: The action.The credentials of the principal.The target object.The outcome. Example: <originator blade="webseald"> <component rev="1.4">authn</component> <event_id>101</event_id> <action>0</action> <location>cmd.wma.ibm.com</location> </originator> <location> ... </location> The host name (location) of the machine. If there is no host name specified, a notation of location not specified is substituted in the location element. Example: <originator blade="webseald"> <component rev="1.4">authn</component> <event_id>101</event_id> <action>0</action> <location>cmd.wma.ibm.com</location> </originator> <accessor> ... </accessor> The name of the user that caused the event. If there is no user name specified, a notation of name="user not specified" or name="" is substituted in the accessor element. The accessor element can include the following elements: principalname_in_rgy (for authenticated users)session_id (for authenticated users)principaluser_locationuser_location_type The accessor element includes the name attribute. The following example shown the accessor element for an unauthenticated user: <event rev="1.2> ... <accessor name="unauthenticated"> <principal auth="IV_UNAUTH_V3.0" domain="Default"> testuser2 </principal> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> ... </event> The following example shown the accessor element for an authenticated user: <event rev="1.2> ... <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default"> testuser2 </principal> <name_in_rgy> cn=testuser1,dc=ibm,dc=com </name_in_rgy> <session_id> e005ba3-34ed-11da-a016-00096bc369d </session_id> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> ... </event> <principal> ... </principal> User authorization credentials. Generally each event captures the result of an action that a user (principal) attempts on a target object. If there is no user name specified, a notation of auth="invalid" is substituted in the principal element. The principal element can contain the following attributes: authdomainTo determine the actual authentication method, use the data in the authntype element. A common format header of the audit record captures information about: The credentials of the principal.The action.The target object.The outcome. Example: <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default"> testuser2 </principal> <name_in_rgy> cn=testuser1,dc=ibm,dc=com </name_in_rgy> <session_id> e005ba3-34ed-11da-a016-00096bc369d </session_id> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> <name_in_rgy> ... </name_in_rgy> The name in the registry for the user. Example: <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default"> testuser2 </principal> <name_in_rgy> cn=testuser1,dc=ibm,dc=com </name_in_rgy> <session_id> e005ba3-34ed-11da-a016-00096bc369d </session_id> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> <session_id> ... </session_id> The session ID that is associated with this session. This ID can be used to trace a series of events back to the authentication data that was initially provided by the user. For example, the data in the session_id element could be used to determine when a user logged in and when a user logged out. Example: <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default"> testuser2 </principal> <name_in_rgy> cn=testuser1,dc=ibm,dc=com </name_in_rgy> <session_id> e005ba3-34ed-11da-a016-00096bc369d </session_id> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> <user_location> ... </user_location> The IP address in IPv4 or IPv6 format. Example: <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default"> testuser2 </principal> <name_in_rgy> cn=testuser1,dc=ibm,dc=com </name_in_rgy> <session_id> e005ba3-34ed-11da-a016-00096bc369d </session_id> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> <user_location_type> ... </user_location_type> The format of the data in the user_location element. Values are: IPV4IPV6 Example: <accessor name=""> <principal auth="IV_LDAP_V3.0" domain="Default"> testuser2 </principal> <name_in_rgy> cn=testuser1,dc=ibm,dc=com </name_in_rgy> <session_id> e005ba3-34ed-11da-a016-00096bc369d </session_id> <user_location>9.65.85.162</user_location> <user_location_type>IPV4</user_location_type> </accessor> <target> ... </target> Target information. The target element can include the following elements: objectobject_nameinappprocessazn The target element includes the resource attribute, which represents a broad categorization of the target object: The resource attribute can be one of the following values: 0AUTHORIZATION1PROCESS2TCB3CREDENTIAL5GENERAL6APPLICATION7AUTHENTICATION Examples: <target resource="7"> <object></object> </target> <target resource="3"> <object>IV_LDAP_V3.0:sec_master</object> </target> <object> ... </object> Target object. Authorization audit records can be captured when a target object in the policy database (protected object space) has a POP attached to it. The POP must enable audit functionality. For example: <object>/Management</object> A common format header of the audit record captures information about: The target object.The action.The user credentials.The outcome. Example: <target resource="3"> <object>IV_LDAP_V3.0:sec_master</object> </target> <azn> ... </azn> Authorization service information. The authorization service: Checks the access permissions on the target requested object.Compares these access permissions with the capabilities of the requesting user. The azn element can include the following elements: permresultqualifier <target resource="3"> ... <azn> <perm>64</perm> <result>0</result> <qualifier>0</qualifier> </azn> ... </target> <perm> ... </perm> Set of controls (permissions) that specifies the conditions necessary to complete certain operations on that resource. The permission can be specified in this element by using either the binary number such as <perm>64</perm> or the letters for the specified action permissions such as <perm>Tr</perm>. Example: <target resource="3"> ... <azn> <perm>64</perm> <result>0</result> <qualifier>0</qualifier> </azn> ... </target> <result> ... </result> Results of the authorization service check. Example: <target resource="3"> ... <azn> <perm>64</perm> <result>0</result> <qualifier>0</qualifier> </azn> ... </target> <qualifier> ... </qualifier> Qualifier information. Example: <target resource="3"> ... <azn> <perm>64</perm> <result>0</result> <qualifier>0</qualifier> </azn> ... </target> <process> ... </process> Type of process. The process element can include the following elements: pid (process ID)uid (user ID)eid (effective user ID)gid (group ID)egid (effective group ID) The process element includes the architecture attribute, which is one of the following values: 0For AIX, Linux, and Solaris operating systems.1For Windows operating systems. Example: <process architecture="0"> ... <pid></pid> </process> <pid></pid> <eid></eid> <uid></uid> <gid></gid> <egid></egid> The identifier of the process, which is contained in one of the following elements: pidProcess IDeidEffective user IDuidUser IDgidGroup IDegidEffective group ID Example: <process architecture="0"> ... <pid>3899</pid> </process> <policy> ... </policy> The security policy information. The policy element can include the following elements: nametypedescr Example of name element for policy element: <policy> <name>real-traders-only</name> <type>rule</type> </policy> <name> ... </name> Name of the policy attribute that you want to audit. The name matches the name that you specified in a list of attributes in the [aznapi-configuration] stanza of the appropriate configuration file. For example: [aznapi-configuration] audit-attribute = real-traders-only Example: <policy> <name>real-traders-only</name> <type>rule</type> </policy> <type> ... </type> Type of security policy being audited. The type element can contain the following values: ACLPOPrule Example: <policy> <name>traders-pop</name> <type>POP</type> </policy> <descr> ... </descr> Description of the security policy. This element is empty if no description was created for the policy. Example: <policy><name>traders-acl</name> <type>ACL</type> <descr>traders that have ACL security policies</descr> </policy> <attribute> ... </attribute> The container for the characteristics of the access decision information (ADI) attribute to audit. An attribute can establish accountability by providing information to help identify potentially inappropriate access of assets. You can grant or deny access based on rules applied to attributes. The attribute element can include the following elements: namesourcetypevalue Example: <attribute> <name>tagvalue_su-admin</name> <source>cred</source> <type>string</type> <value>test_customer_service_rep_1</value> </attribute> <name> ... </name> Name of the ADI to audit. This ADI can be for auditing either a user credential if for the authn component or an app_context if for an azn component. The name of the authorization attribute matches the name that you specified in a list of attributes in the [aznapi-configuration] stanza of the appropriate configuration file. For example: [aznapi-configuration] audit-attribute = AZN_CRED_AUTH_METHOD Example of name element for the attribute element: <attribute> <name>AZN_CRED_AUTH_METHOD</name> <source>credADI</source> <type>string</type> <value>su-forms</value> </attribute> <source> ... </source> The source event. The source element can contain one of the following values: credApplies to any Security Access Manager component. appApplies only to an authorization (azn) component.credADIApplies only to the authorization (azn) component when evaluating a Boolean rule.appADIApplies only to the authorization (azn) component when evaluating a Boolean rule.engineADIApplies only to the authorization (azn) component when evaluating a Boolean rule. dynADIApplies only to the authorization (azn) component when evaluating a Boolean rule. If the ADI attribute is multi-valued, a separate attribute element is written for each value. Example: <attribute> <name>AZN_CRED_AUTH_METHOD</name> <source>credADI</source> <type>string</type> <value>su-forms</value> </attribute> <type> ... </type> Type of security policy that is being audited. The type element can contain one of the following values: stringulongpobj If <type>pobj</type>, the value is the name of the protected object. Example: <attribute> <name>AZN_CRED_AUTH_METHOD</name> <source>credADI</source> <type>string</type> <value>su-forms</value> </attribute> <value> ... </value> Value for the aznAPI attribute. If the ADI attribute is multi-valued, then a separate attribute element is written for each value. Example: <attribute> <name>AZN_CRED_AUTH_METHOD</name> <source>credADI</source> <type>string</type> <value>su-forms</value> </attribute> <resource_access> ... </resource_access> Example: <event rev="1.2"> ... <resource_access> <action>httpRequest</action> <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl> <httpmethod>GET</httpmethod> <httpresponse>200</httpresponse> </resource_access> ... </event> <action> ... </action> Example: <event rev="1.2"> ... <resource_access> <action>httpRequest</action> <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl> <httpmethod>GET</httpmethod> <httpresponse>200</httpresponse> </resource_access> ... </event> <httpurl> ... </httpurl> Example: <event rev="1.2"> ... <resource_access> <action>httpRequest</action> <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl> <httpmethod>GET</httpmethod> <httpresponse>200</httpresponse> </resource_access> ... </event> <httpmethod> ... </httpmethod> Example: <event rev="1.2"> ... <resource_access> <action>httpRequest</action> <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl> <httpmethod>GET</httpmethod> <httpresponse>200</httpresponse> </resource_access> ... </event> <httpresponse> ... </httpresponse> Example: <event rev="1.2"> ... <resource_access> <action>httpRequest</action> <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl> <httpmethod>GET</httpmethod> <httpresponse>200</httpresponse> </resource_access> ... </event> <authntype> ... </authntype> The type of authentication that the user completed. The following strings are authentication types that are associated with WebSEAL and Plug-in for Web Servers: itamFailoverCookieFailover cookieitamCDSSOWebSEAL or Plug-in for Web Servers authentication using cross domain single-sign on (CDSSO)itamECSSOWebSEAL or Plug-in for Web Servers authentication using e-Community single-sign on (ECSSO)certificateSSL certificate authenticationtwoFactorWebSEAL or Plug-in for Web Servers using token authenticationformsPasswordPassword authentication using an HTML formbasicAuthRFC2617Password authentication using HTTP Basic Authentication (BA)passwordOtherPassword authentication using an undetermined mechanismitamHTTPHeaderWebSEAL or Plug-in for Web Servers using HTTP header authenticationitamIPAddressWebSEAL or Plug-in for Web Servers using IP address-based authenticationkerberosWebSEAL or Plug-in for Web Servers using SPNEGO authenticationitamEAIWebSEAL or Plug-in for Web Servers using external authentication interface (EAI) authenticationitamIVCredsPlug-in for Web Servers authentication using the IV_CREDS headeritamIVUserPlug-in for Web Servers authentication using the IV_USER headertokenLTPAPlug-in for Web Servers authentication using a lightweight third-party authentication (LTPA) tokenntlmPlug-in for Web Servers using NTLM authenticationitamWebServerAuthenticationPlug-in for Web Servers authentication that is provided by the hosting Web server Example: <event rev="1.2"> ... <authntype>formsPassword</authntype> ... </event> <terminateinfo> ... </terminateinfo> Contains information about why a session ended. The terminateinfo element contains the terminatereason element. Example: <event rev="1.2"> ... <terminateinfo> <terminatereason>userLoggedOut</terminatereason> </terminateinfo> ... </event> <terminatereason> ... </terminatereason> The reason why the session ended. The following values are possible: idleTimeoutThe session timed out because the user was inactive.sessionExpiredThe session timed out because the user was logged in for too long.sessionDisplacedThe session ended because another user with the same user ID logged in.sessionTerminatedByAdminThe session ended because an administrator logged out the user.userLoggedOutThe session ended because the user logged out.reathLockOutThe session ended because the user did not authenticate again. Example: <terminateinfo> <terminatereason>userLoggedOut</terminatereason> </terminateinfo> <data> ... </data> Event-specific data. The data element can contain the audit element. Additional event-specific information is recorded in a free format data area at the end of the event record. For failed authentication attempts, Data output for errors provides details about the data information that is returned. Decoding the meaning of certain data values in the record might require an advanced knowledge of the Security Access Manager code and architecture. Command arguments are listed in the data element of the event record in their internal format. For example: <data>azn_id_get_creds</data> Commands that do not result in an effective state change (list and show) are never captured. Examples: <event> ... <data> POST /pkmspasswd.form HTTP/1.1 0 Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0) https://c03comcrit2.somecompany.com/pkmspasswd </data> </event> <data> "2019" "1002" "pop1" "0" "" </data> <audit/> Beginning and ending of an audit event. The audit element can include the event attribute, which can be one of the following values: StartStop Example: <event rev="1.2"> ... <data> <audit event="Start"/> </data> </event> ... <event rev="1.2"> ... <data> <audit event="Stop"/> </data> </event>XML output of native audit events

XML output elements

Table 235 describes the XML output elements that are possible by using the default Security Access Manager DTD elements. If you create your own DTD, each element must represent the events that you selected and extracted according to your own criteria.

Table 235. Names and descriptions for XML output elements

Output element name
Description

<event>
...
</event>

Auditing event. Each auditing event captures the result of an action. A principal attempts an action on a target object.

The event element can include the following elements:

date

outcome

originator

accessor

target

resource_access (for resource access events)

authntype (for authentication events)

terminationinfo (for authentication terminate events)

data

Because Security Access Manager auditing uses a standard record format, not all elements are relevant to each event that is recorded. Fields that are not relevant for a particular event might contain a default value.

The event element can include the following attribute:

rev

Example:

<event rev="1.2">
  <date>2003-11-14-16:25:08.341+00:00I-----</date>
  <outcome status="0">0</outcome>
  ...
</event>

<date>
...
</date>

Current date and timestamp. The date element has the following format:

yyyy-mm-dd-hh:mm:ss.xxx-xx:xxI-----

Where:

yyyy-mm-dd

Relates to the year (yyyy), the month (mm), and the day (dd).

hh:mm:ss

Relates to hours (hh), minutes (mm), and seconds (ss).

xxx-xx:xxI

Refers to the time zone.

Example:

<event rev="1.2">
<date>2005-11-14-16:25:08.341+00-----</date>
...
</event>

<outcome>
...
</outcome>

Outcome of the event. The outcome element can be one of the following values:

0

Success

1

Failure

2

Pending

3

Unknown

The following information is captured in a common format header of the audit record:

The outcome.

The action.

The credentials for the principal.

The target object.

This element can include the following attributes:

status

reason

Example of a failed event:

<outcome status="320938184" reason="authenticationFailure">
  1
</outcome>

For information about the contents of the status attribute, use the errtext command. The command provides the error message that is associated with the status code (320938184) of a failed event. If the error is not identified by the errtext command, the error did not originate in Security Access Manager. See your third-party documentation for more status code definitions.

For information about the contents of the reason attribute, see Outcome output for failures.

Example of a successful event:

<event rev="1.2">
...
<outcome status="0">0</outcome>
...
</event>

<originator>
...
</originator>

Server that originated the event being logged. The originator element can include the following elements:

component

event_id

action

location

The originator element can include the following attributes:

blade

instance

The blade attributes represents the server that originated the event. For example, pdmgrd is the Security Access Manager policy server, webseald is the Security Access Manager WebSEAL server. The instance attribute applies to WebSEAL and represents the name of the instance.

Example:

<event rev="1.2">
...
<originator blade="webseald">
   <component rev="1.4">authn</component>
   <event_id>101</event_id>
   <action>0</action>
   <location>cmd.wma.ibm.com</location>
</originator>
...
</event>

<component>
...
</component>

Audit events, categorized by the server functionality that generates them. Some functionality is common across Security Access Manager servers while other functionality is server-specific.

The component element can be one of the following values:

authz or azn

Captures authorization events.

authn

Captures authentication events.

mgmt

Captures management events.

http

Captures WebSEAL HTTP events. See the Configuring topics in the Knowledge Center for more information about this value.

The component element can contain the rev attribute.

Example:

<originator blade="webseald">
   <component rev="1.4">authn</component>
   <event_id>101</event_id>
   <action>0</action>
   <location>cmd.wma.ibm.com</location>
</originator>

<event_id>
...
</event_id>

The category of the event ID. The event_id element can be one of the following values:

101

Login

102

Password change

103

Logout

104

Authenticate

105

Step-up

106

Re-authentication

107

Credentials refresh

108

Authorization check

109

Resource access

110

Get credentials

111

Modify credentials/combine credentials

112

Get credentials from pac

113

Get pac

114

Get entitlements

115

Runtime start

116

Runtime stop

117

Runtime audit start

118

Runtime audit stop

119

Runtime audit level change

120

Runtime statistic

121

Runtime heartbeat up

122

Runtime heartbeat down

123

Runtime lost contact

124

Runtime contact restored

125

Runtime monitor

126

Switch-user login

127

Switch-user logout

Example:

<originator blade="webseald">
   <component rev="1.4">authn</component>
   <event_id>101</event_id>
   <action>0</action>
   <location>cmd.wma.ibm.com</location>
</originator>

<action>
...
</action>

Audit record action code, which can be for one of the following groups of events:

Authentication or authorization events

Audit records for authentication or authorization events contain one of the following event action codes:

0

Authentication or authorization events

1

Change password events

2

WebSEAL events

Management events

Audit records for management events contain an action code that identifies the pdadmin utility. For example, the <action>13702</action> action code relates to the POP_MODIFY action for the pop modify command. See Action codes for management commands, which relates the action code reference number for each command.

A common format header of the audit record captures information about:

The action.

The credentials of the principal.

The target object.

The outcome.

Example:

<originator blade="webseald">
   <component rev="1.4">authn</component>
   <event_id>101</event_id>
   <action>0</action>
   <location>cmd.wma.ibm.com</location>
</originator>

<location>
...
</location>

The host name (location) of the machine. If there is no host name specified, a notation of "location not specified" is substituted in the location element.

Example:

<originator blade="webseald">
   <component rev="1.4">authn</component>
   <event_id>101</event_id>
   <action>0</action>
   <location>cmd.wma.ibm.com</location>
</originator>

<accessor>
...
</accessor>

The name of the user that caused the event. If there is no user name specified, a notation of "name="user not specified"" or "name=""" is substituted in the accessor element.

The accessor element can include the following elements:

principal

name_in_rgy (for authenticated users)

session_id (for authenticated users)

principal

user_location

user_location_type

The accessor element includes the name attribute.

The following example shown the accessor element for an unauthenticated user:

<event rev="1.2>
  ...
  <accessor name="unauthenticated">
    <principal auth="IV_UNAUTH_V3.0" domain="Default">
      testuser2
    </principal>
    <user_location>9.65.85.162</user_location>
    <user_location_type>IPV4</user_location_type>
  </accessor>
  ...
</event>

The following example shown the accessor element for an authenticated user:

<event rev="1.2>
  ...
  <accessor name="">
    <principal auth="IV_LDAP_V3.0" domain="Default">
      testuser2
    </principal>
    <name_in_rgy>
      cn=testuser1,dc=ibm,dc=com
    </name_in_rgy>
    <session_id>
      e005ba3-34ed-11da-a016-00096bc369d
    </session_id>
    <user_location>9.65.85.162</user_location>
    <user_location_type>IPV4</user_location_type>
  </accessor>
  ...
</event>

<principal>
...
</principal>

User authorization credentials. Generally each event captures the result of an action that a user (principal) attempts on a target object. If there is no user name specified, a notation of "auth="invalid"" is substituted in the principal element.

The principal element can contain the following attributes:

auth

domain

To determine the actual authentication method, use the data in the authntype element.

A common format header of the audit record captures information about:

The credentials of the principal.

The action.

The target object.

The outcome.

Example:

<accessor name="">
  <principal auth="IV_LDAP_V3.0" domain="Default">
    testuser2
  </principal>
  <name_in_rgy>
    cn=testuser1,dc=ibm,dc=com
  </name_in_rgy>
  <session_id>
    e005ba3-34ed-11da-a016-00096bc369d
  </session_id>
  <user_location>9.65.85.162</user_location>
  <user_location_type>IPV4</user_location_type>
  </accessor>

<name_in_rgy>
...
</name_in_rgy>

The name in the registry for the user.

Example:

<accessor name="">
  <principal auth="IV_LDAP_V3.0" domain="Default">
    testuser2
  </principal>
  <name_in_rgy>
    cn=testuser1,dc=ibm,dc=com
  </name_in_rgy>
  <session_id>
    e005ba3-34ed-11da-a016-00096bc369d
  </session_id>
  <user_location>9.65.85.162</user_location>
  <user_location_type>IPV4</user_location_type>
</accessor>

<session_id>
...
</session_id>

The session ID that is associated with this session. This ID can be used to trace a series of events back to the authentication data that was initially provided by the user. For example, the data in the session_id element could be used to determine when a user logged in and when a user logged out.

Example:

<accessor name="">
  <principal auth="IV_LDAP_V3.0" domain="Default">
    testuser2
  </principal>
  <name_in_rgy>
    cn=testuser1,dc=ibm,dc=com
  </name_in_rgy>
  <session_id>
    e005ba3-34ed-11da-a016-00096bc369d
  </session_id>
  <user_location>9.65.85.162</user_location>
  <user_location_type>IPV4</user_location_type>
</accessor>

<user_location>
...
</user_location>

The IP address in IPv4 or IPv6 format.

Example:

<accessor name="">
  <principal auth="IV_LDAP_V3.0" domain="Default">
    testuser2
  </principal>
  <name_in_rgy>
    cn=testuser1,dc=ibm,dc=com
  </name_in_rgy>
  <session_id>
    e005ba3-34ed-11da-a016-00096bc369d
  </session_id>
  <user_location>9.65.85.162</user_location>
  <user_location_type>IPV4</user_location_type>
</accessor>

<user_location_type>
...
</user_location_type>

The format of the data in the user_location element. Values are:

IPV4

IPV6

Example:

<accessor name="">
  <principal auth="IV_LDAP_V3.0" domain="Default">
    testuser2
  </principal>
  <name_in_rgy>
    cn=testuser1,dc=ibm,dc=com
  </name_in_rgy>
  <session_id>
    e005ba3-34ed-11da-a016-00096bc369d
  </session_id>
  <user_location>9.65.85.162</user_location>
  <user_location_type>IPV4</user_location_type>
</accessor>

<target>
...
</target>

Target information. The target element can include the following elements:

object

object_nameinapp

process

azn

The target element includes the resource attribute, which represents a broad categorization of the target object: The resource attribute can be one of the following values:

0

AUTHORIZATION

1

PROCESS

2

TCB

3

CREDENTIAL

5

GENERAL

6

APPLICATION

7

AUTHENTICATION

Examples:

<target resource="7">
  <object></object>
</target>

<target resource="3">
  <object>IV_LDAP_V3.0:sec_master</object>
</target>

<object>
...
</object>

Target object. Authorization audit records can be captured when a target object in the policy database (protected object space) has a POP attached to it. The POP must enable audit functionality. For example:

<object>/Management</object>

A common format header of the audit record captures information about:

The target object.

The action.

The user credentials.

The outcome.

Example:

<target resource="3">
  <object>IV_LDAP_V3.0:sec_master</object>
</target>

<azn>
...
</azn>

Authorization service information. The authorization service:

Checks the access permissions on the target requested object.

Compares these access permissions with the capabilities of the requesting user.

The azn element can include the following elements:

perm

result

qualifier

<target resource="3">
  ...
  <azn>
    <perm>64</perm>
    <result>0</result>
    <qualifier>0</qualifier>
  </azn>
  ...
</target>

<perm>
...
</perm>

Set of controls (permissions) that specifies the conditions necessary to complete certain operations on that resource. The permission can be specified in this element by using either the binary number such as <perm>64</perm> or the letters for the specified action permissions such as <perm>Tr</perm>.

Example:

<target resource="3">
  ...
  <azn>
    <perm>64</perm>
    <result>0</result>
    <qualifier>0</qualifier>
  </azn>
  ...
</target>

<result>
...
</result>

Results of the authorization service check.

Example:

<target resource="3">
  ...
  <azn>
    <perm>64</perm>
    <result>0</result>
    <qualifier>0</qualifier>
  </azn>
  ...
</target>

<qualifier>
...
</qualifier>

Qualifier information.

Example:

<target resource="3">
  ...
  <azn>
    <perm>64</perm>
    <result>0</result>
    <qualifier>0</qualifier>
  </azn>
  ...
</target>

<process>
...
</process>

Type of process. The process element can include the following elements:

pid (process ID)

uid (user ID)

eid (effective user ID)

gid (group ID)

egid (effective group ID)

The process element includes the architecture attribute, which is one of the following values:

0

For AIX, Linux, and Solaris operating systems.

1

For Windows operating systems.

Example:

<process architecture="0">
  ...
  <pid></pid>
</process>

<pid></pid>
<eid></eid>
<uid></uid>
<gid></gid>
<egid></egid>

The identifier of the process, which is contained in one of the following elements:

pid

Process ID

eid

Effective user ID

uid

User ID

gid

Group ID

egid

Effective group ID

Example:

<process architecture="0">
  ...
  <pid>3899</pid>
</process>

<policy>
...
</policy>

The security policy information. The policy element can include the following elements:

name

type

descr

Example of name element for policy element:

<policy>
  <name>real-traders-only</name>
  <type>rule</type>
</policy>

<name>
...
</name>

Name of the policy attribute that you want to audit. The name matches the name that you specified in a list of attributes in the [aznapi-configuration] stanza of the appropriate configuration file. For example:

[aznapi-configuration]
audit-attribute = real-traders-only

Example:

<policy>
  <name>real-traders-only</name>
  <type>rule</type>
</policy>

<type>
...
</type>

Type of security policy being audited. The type element can contain the following values:

ACL

POP

rule

Example:

<policy>
  <name>traders-pop</name>
  <type>POP</type>
</policy>

<descr>
...
</descr>

Description of the security policy. This element is empty if no description was created for the policy.

Example:

<policy><name>traders-acl</name>
  <type>ACL</type>
  <descr>traders that have ACL security policies</descr>
</policy>

<attribute>
...
</attribute>

The container for the characteristics of the access decision information (ADI) attribute to audit. An attribute can establish accountability by providing information to help identify potentially inappropriate access of assets. You can grant or deny access based on rules applied to attributes.

The attribute element can include the following elements:

name

source

type

value

Example:

<attribute>
  <name>tagvalue_su-admin</name>
  <source>cred</source>
  <type>string</type>
  <value>test_customer_service_rep_1</value>
</attribute>

<name>
...
</name>

Name of the ADI to audit. This ADI can be for auditing either a user credential if for the authn component or an app_context if for an azn component.

The name of the authorization attribute matches the name that you specified in a list of attributes in the [aznapi-configuration] stanza of the appropriate configuration file. For example:

[aznapi-configuration]
audit-attribute = AZN_CRED_AUTH_METHOD

Example of name element for the attribute element:

<attribute>
  <name>AZN_CRED_AUTH_METHOD</name>
  <source>credADI</source>
  <type>string</type>
  <value>su-forms</value>
</attribute>

<source>
...
</source>

The source event. The source element can contain one of the following values:

cred

Applies to any Security Access Manager component.

app

Applies only to an authorization (azn) component.

credADI

Applies only to the authorization (azn) component when evaluating a Boolean rule.

appADI

Applies only to the authorization (azn) component when evaluating a Boolean rule.

engineADI

Applies only to the authorization (azn) component when evaluating a Boolean rule.

dynADI

Applies only to the authorization (azn) component when evaluating a Boolean rule.

If the ADI attribute is multi-valued, a separate attribute element is written for each value.

Example:

<attribute>
  <name>AZN_CRED_AUTH_METHOD</name>
  <source>credADI</source>
  <type>string</type>
  <value>su-forms</value>
</attribute>

<type>
...
</type>

Type of security policy that is being audited. The type element can contain one of the following values:

string

ulong

pobj

If <type>pobj</type>, the value is the name of the protected object.

Example:

<attribute>
  <name>AZN_CRED_AUTH_METHOD</name>
  <source>credADI</source>
  <type>string</type>
  <value>su-forms</value>
</attribute>

<value>
...
</value>

Value for the aznAPI attribute. If the ADI attribute is multi-valued, then a separate attribute element is written for each value.

Example:

<attribute>
  <name>AZN_CRED_AUTH_METHOD</name>
  <source>credADI</source>
  <type>string</type>
  <value>su-forms</value>
</attribute>

<resource_access>
...
</resource_access>

Example:

<event rev="1.2">
  ...
  <resource_access>
    <action>httpRequest</action>
    <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl>
    <httpmethod>GET</httpmethod>
    <httpresponse>200</httpresponse>
  </resource_access>
  ...
</event>

<action>
...
</action>

Example:

<event rev="1.2">
  ...
  <resource_access>
    <action>httpRequest</action>
    <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl>
    <httpmethod>GET</httpmethod>
    <httpresponse>200</httpresponse>
  </resource_access>  ...
</event>

<httpurl>
...
</httpurl>

Example:

<event rev="1.2">
  ...
  <resource_access>
    <action>httpRequest</action>
    <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl>
    <httpmethod>GET</httpmethod>
    <httpresponse>200</httpresponse>
  </resource_access>  ...
</event>

<httpmethod>
...
</httpmethod>

Example:

<event rev="1.2">
  ...
  <resource_access>
    <action>httpRequest</action>
    <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl>
    <httpmethod>GET</httpmethod>
    <httpresponse>200</httpresponse>
  </resource_access>  ...
</event>

<httpresponse>
...
</httpresponse>

Example:

<event rev="1.2">
  ...
  <resource_access>
    <action>httpRequest</action>
    <httpurl>HTTP://cmd.wma.ibm.com:80/</httpurl>
    <httpmethod>GET</httpmethod>
    <httpresponse>200</httpresponse>
  </resource_access>  ...
</event>

<authntype>
...
</authntype>

The type of authentication that the user completed. The following strings are authentication types that are associated with WebSEAL and Plug-in for Web Servers:

itamFailoverCookie

Failover cookie

itamCDSSO

WebSEAL or Plug-in for Web Servers authentication using cross domain single-sign on (CDSSO)

itamECSSO

WebSEAL or Plug-in for Web Servers authentication using e-Community single-sign on (ECSSO)

certificate

SSL certificate authentication

twoFactor

WebSEAL or Plug-in for Web Servers using token authentication

formsPassword

Password authentication using an HTML form

basicAuthRFC2617

Password authentication using HTTP Basic Authentication (BA)

passwordOther

Password authentication using an undetermined mechanism

itamHTTPHeader

WebSEAL or Plug-in for Web Servers using HTTP header authentication

itamIPAddress

WebSEAL or Plug-in for Web Servers using IP address-based authentication

kerberos

WebSEAL or Plug-in for Web Servers using SPNEGO authentication

itamEAI

WebSEAL or Plug-in for Web Servers using external authentication interface (EAI) authentication

itamIVCreds

Plug-in for Web Servers authentication using the IV_CREDS header

itamIVUser

Plug-in for Web Servers authentication using the IV_USER header

tokenLTPA

Plug-in for Web Servers authentication using a lightweight third-party authentication (LTPA) token

ntlm

Plug-in for Web Servers using NTLM authentication

itamWebServerAuthentication

Plug-in for Web Servers authentication that is provided by the hosting Web server

Example:

<event rev="1.2">
  ...
  <authntype>formsPassword</authntype>
  ...
</event>

<terminateinfo>
...
</terminateinfo>

Contains information about why a session ended. The terminateinfo element contains the terminatereason element.

Example:

<event rev="1.2">
  ...
  <terminateinfo>
    <terminatereason>userLoggedOut</terminatereason>
  </terminateinfo>
  ...
</event>

<terminatereason>
...
</terminatereason>

The reason why the session ended. The following values are possible:

idleTimeout

The session timed out because the user was inactive.

sessionExpired

The session timed out because the user was logged in for too long.

sessionDisplaced

The session ended because another user with the same user ID logged in.

sessionTerminatedByAdmin

The session ended because an administrator logged out the user.

userLoggedOut

The session ended because the user logged out.

reathLockOut

The session ended because the user did not authenticate again.

Example:

<terminateinfo>
  <terminatereason>userLoggedOut</terminatereason>
</terminateinfo>

<data>
...
</data>

Event-specific data. The data element can contain the audit element.

Additional event-specific information is recorded in a free format data area at the end of the event record. For failed authentication attempts, Data output for errors provides details about the data information that is returned.

Note: Decoding the meaning of certain data values in the record might require an advanced knowledge of the Security Access Manager code and architecture.

Command arguments are listed in the data element of the event record in their internal format. For example:

<data>azn_id_get_creds</data>

Commands that do not result in an effective state change (list and show) are never captured.

Examples:

<event>
  ...
  <data>
  POST /pkmspasswd.form HTTP/1.1 0 Mozilla/4.0
  (compatible; MSIE 6.0; Windows NT 5.0)
  https://c03comcrit2.somecompany.com/pkmspasswd
  </data>
</event>

<data>
  "2019"
  "1002"
  "pop1"
  "0"
  ""
</data>

<audit/>

Beginning and ending of an audit event. The audit element can include the event attribute, which can be one of the following values:

Start

Stop

Example:

<event rev="1.2">
  ...
  <data>
    <audit event="Start"/>
  </data>
</event>
...
<event rev="1.2">
  ...
  <data>
    <audit event="Stop"/>
  </data>
</event>

Parent topic: XML output of native audit events

Action codes for management commandsmanagement commandsaction codesmanagement commands The action code identifies one of the pdadmin management commands. The tables in this section relate the action code reference number for each management command. For example, the action code 13702 relates to the POP_MODIFY action command. In other words, the pdadmin pop modify command. Command arguments are listed in the data section of the event record in their internal format. Commands that do not result in an effective change of state of the database (such as the list and show commands) are never captured. Table 1 maps the action codes to the management commands. Mapping of action codes to management commandsAction codeManagement command13000ACL_LIST13001ACL_GET13002ACL_SET_LEGACY13003ACL_DELETE13005ACL_FIND13006ACTION_LIST13007ACTION_SET13008ACTION_DELETE13009ACTION_GROUPLIST13010ACTION_GROUPCREATE13011ACTION_GROUPDELETE13012ACTION_LISTGROUP13013ACTION_CREATEGROUP13014ACTION_DELETEGROUP13020ACL_CREATE13021ACL_SET13100OBJ_GET13101OBJ_ACL_SET (deprecated)13102OBJ_GET_OBJ13103OBJSPC_CREATE13104OBJSPC_DELETE13105OBJSPC_LIST13106OBJ_CREATE13107OBJ_DELETE13110OBJ_MOD_SET_NAME13111OBJ_MOD_SET_DESC13112OBJ_MOD_SET_TYPE13113OBJ_MOD_SET_ISLF13114OBJ_MOD_SET_ISPOL13115OBJ_MOD_SET_ATTR13116OBJ_MOD_DEL_ATTR13117OBJ_MOD_DEL_ATTRVAL13118OBJ_SHOW_ATTR13119OBJ_LIST_ATTR13120ACL_ATTACH13121ACL_DETACH13123ACL_MOD_SET_ATTR13124ACL_MOD_DEL_ATTR13125ACL_MOD_DEL_ATTRVAL13126ACL_SHOW_ATTR13127ACL_LIST_ATTR13128POP_MOD_SET_ATTR13129POP_MOD_DEL_ATTR13130POP_MOD_DEL_ATTRVAL13131POP_SHOW_ATTR13132POP_LIST_ATTR13133OBJ_SHOW_ATTRS13134ACL_SHOW_ATTRS13135POP_SHOW_ATTRS13136OBJ_SHOW_V41713137OBJ_LIST13138OBJ_LISTANDSHOW_V41713139OBJ_EXISTS (deprecated)13140OBJ_ACCESS_CHECK13141OBJ_SHOW13142OBJ_LISTANDSHOW13150ACL_CREATE_ATTR (deprecated, see 13134)13200SERVER_GET13201SERVER_RESTORE13202SERVER_DELETE (deprecated)13203SERVER_LIST13204SERVER_PERFORMTASK13205SERVER_GETTASKLIST13206SERVER_REPLICATE13207SERVER_ACTION13208SERVER_STATUS_GET13209SERVER_ENABLE (deprecated)13210SERVER_DISABLE (deprecated)13400ADMIN_SHOWCONF13401USER_CREATE13402USER_IMPORT13403USER_MODDESC13404USER_MODPWD13405USER_MODAUTHMECH13406USER_MODACCVALID13407USER_MODPWDVALID13408USER_DELETE13409USER_SHOWGROUPS13410USER_SHOW13411USER_SHOWDN13412USER_LIST13413USER_LISTDN13414GROUP_CREATE13415GROUP_IMPORT13416GROUP_MODDESC13417GROUP_MODADD13418GROUP_MODREMOVE13419GROUP_DELETE13420GROUP_SHOW13421GROUP_SHOWDN13422GROUP_LIST13423GROUP_LISTDN13424GROUP_SHOWMEMB13425USER_MODGSOUSER13426USER_SET (deprecated)13427GROUP_SET (deprecated)13428GROUP_MODADD213500GSO_RESOURCE_CREATE13501GSO_RESOURCE_DELETE13502GSO_RESOURCE_LIST13503GSO_RESOURCE_SHOW13504GSO_RESOURCE_CRED_CREATE13505GSO_RESOURCE_CRED_DELETE13506GSO_RESOURCE_CRED_MODIFY13507GSO_RESOURCE_CRED_LIST13508GSO_RESOURCE_CRED_SHOW13509GSO_RESOURCE_GROUP_CREATE13510GSO_RESOURCE_GROUP_DELETE13511GSO_RESOURCE_GROUP_ADD13512GSO_RESOURCE_GROUP_REMOVE13513GSO_RESOURCE_GROUP_LIST13514GSO_RESOURCE_GROUP_SHOW13600POLICY_SET_MAX_LOGIN_FAILURES13601POLICY_GET_MAX_LOGIN_FAILURES13602POLICY_SET_DISABLE_TIME_INTERVAL13603POLICY_GET_DISABLE_TIME_INTERVAL13604POLICY_SET_MAX_ACCOUNT_AGE13605POLICY_GET_MAX_ACCOUNT_AGE13606POLICY_SET_ACCOUNT_EXPIRY_DATE13607POLICY_GET_ACCOUNT_EXPIRY_DATE13608POLICY_SET_MAX_INACTIVITY_TIME13609POLICY_GET_MAX_INACTIVITY_TIME13610POLICY_GET_ACCOUNT_CREATION_DATE13611POLICY_GET_LAST_LOGIN_ATTEMPT_DATE13612POLICY_SET_MAX_PASSWORD_AGE13613POLICY_GET_MAX_PASSWORD_AGE13614POLICY_SET_MIN_PASSWORD_AGE13615POLICY_GET_MIN_PASSWORD_AGE13616POLICY_SET_MAX_PASSWORD_REPEATED_CHARS13617POLICY_GET_MAX_PASSWORD_REPEATED_CHARS13618POLICY_SET_MIN_PASSWORD_ALPHAS13619POLICY_GET_MIN_PASSWORD_ALPHAS13620POLICY_SET_MIN_PASSWORD_NON_ALPHAS13621POLICY_GET_MIN_PASSWORD_NON_ALPHAS13622POLICY_SET_MIN_PASSWORD_DIFFERENT_CHARS13623POLICY_GET_MIN_PASSWORD_DIFFERENT_CHARS13624POLICY_SET_PASSWORD_SPACES13625POLICY_GET_PASSWORD_SPACES13626POLICY_SET_MIN_PASSWORD_LENGTH13627POLICY_GET_MIN_PASSWORD_LENGTH13628POLICY_SET_MIN_PASSWORD_REUSE_TIME13629POLICY_GET_MIN_PASSWORD_REUSE_TIME13630POLICY_GET_PASSWORD_FAILURES13631POLICY_GET_LAST_PASSWORD_CHANGE_DATE13632POLICY_SET_NUMBER_WARN_DAYS13633POLICY_GET_NUMBER_WARN_DAYS13634POLICY_SET_PASSWORD_REUSE_NUM13635POLICY_GET_PASSWORD_REUSE_NUM13636POLICY_SET_TOD_ACCESS13637POLICY_GET_TOD_ACCESS13638POLICY_GET_ALL_POLICY13639POLICY_SET_MAX_CONCURRENT_WEB_SESSIONS13640POLICY_GET_MAX_CONCURRENT_WEB_SESSIONS13700POP_CREATE13701POP_DELETE13702POP_MODIFY13703POP_SHOW13704POP_LIST13705POP_ATTACH13706POP_DETACH13707POP_FIND13800CFG_CONFIG13801CFG_UNCONFIG13802CFG_RENEWCERT13803CFG_SETPORT13804CFG_SETLISTENING13805CFG_SETKEYRINGPWD13806CFG_SETSSLTIMEOUT13807CFG_SETAPPLCERT13808CFG_ADDREPLICA13809CFG_CHGREPLICA13810CFG_RMVREPLICA13811CFG_GETVALUE13812CFG_SETVALUE13813CFG_RMVVALUE13814CFG_SETSVRPWD13900DOMAIN_CREATE13901DOMAIN_DELETE13902DOMAIN_MODIFY_DESC13903DOMAIN_SHOW13904DOMAIN_LIST13950AUTHZRULE_CREATE13951AUTHZRULE_DELETE13952AUTHZRULE_MODIFYTEXT13953AUTHZRULE_MODIFYREASON13954AUTHZRULE_MODIFYDESC13955AUTHZRULE_SHOW13956AUTHZRULE_LIST13957AUTHZRULE_ATTACH13958AUTHZRULE_DETACH13959AUTHZRULE_FIND13960AUTHZRULE_MOD_SET_ATTR13961AUTHZRULE_MOD_DEL_ATTR13962AUTHZRULE_MOD_DEL_ATTRVAL13963AUTHZRULE_SHOW_ATTRS13964AUTHZRULE_SHOW_ATTR13965AUTHZRULE_LIST_ATTR XML output of native audit events

Action codes for management commands

The action code identifies one of the pdadmin management commands. The tables in this section relate the action code reference number for each management command. For example, the action code 13702 relates to the POP_MODIFY action command. In other words, the pdadmin pop modify command.

Command arguments are listed in the data section of the event record in their internal format. Commands that do not result in an effective change of state of the database (such as the list and show commands) are never captured.

Table 236 maps the action codes to the management commands.

Table 236. Mapping of action codes to management commands

Action code | Management command
13000 | ACL_LIST
13001 | ACL_GET
13002 | ACL_SET_LEGACY
13003 | ACL_DELETE
13005 | ACL_FIND
13006 | ACTION_LIST
13007 | ACTION_SET
13008 | ACTION_DELETE
13009 | ACTION_GROUPLIST
13010 | ACTION_GROUPCREATE
13011 | ACTION_GROUPDELETE
13012 | ACTION_LISTGROUP
13013 | ACTION_CREATEGROUP
13014 | ACTION_DELETEGROUP
13020 | ACL_CREATE
13021 | ACL_SET
13100 | OBJ_GET
13101 | OBJ_ACL_SET (deprecated)
13102 | OBJ_GET_OBJ
13103 | OBJSPC_CREATE
13104 | OBJSPC_DELETE
13105 | OBJSPC_LIST
13106 | OBJ_CREATE
13107 | OBJ_DELETE
13110 | OBJ_MOD_SET_NAME
13111 | OBJ_MOD_SET_DESC
13112 | OBJ_MOD_SET_TYPE
13113 | OBJ_MOD_SET_ISLF
13114 | OBJ_MOD_SET_ISPOL
13115 | OBJ_MOD_SET_ATTR
13116 | OBJ_MOD_DEL_ATTR
13117 | OBJ_MOD_DEL_ATTRVAL
13118 | OBJ_SHOW_ATTR
13119 | OBJ_LIST_ATTR
13120 | ACL_ATTACH
13121 | ACL_DETACH
13123 | ACL_MOD_SET_ATTR
13124 | ACL_MOD_DEL_ATTR
13125 | ACL_MOD_DEL_ATTRVAL
13126 | ACL_SHOW_ATTR
13127 | ACL_LIST_ATTR
13128 | POP_MOD_SET_ATTR
13129 | POP_MOD_DEL_ATTR
13130 | POP_MOD_DEL_ATTRVAL
13131 | POP_SHOW_ATTR
13132 | POP_LIST_ATTR
13133 | OBJ_SHOW_ATTRS
13134 | ACL_SHOW_ATTRS
13135 | POP_SHOW_ATTRS
13136 | OBJ_SHOW_V417
13137 | OBJ_LIST
13138 | OBJ_LISTANDSHOW_V417
13139 | OBJ_EXISTS (deprecated)
13140 | OBJ_ACCESS_CHECK
13141 | OBJ_SHOW
13142 | OBJ_LISTANDSHOW
13150 | ACL_CREATE_ATTR (deprecated, see 13134)
13200 | SERVER_GET
13201 | SERVER_RESTORE
13202 | SERVER_DELETE (deprecated)
13203 | SERVER_LIST
13204 | SERVER_PERFORMTASK
13205 | SERVER_GETTASKLIST
13206 | SERVER_REPLICATE
13207 | SERVER_ACTION
13208 | SERVER_STATUS_GET
13209 | SERVER_ENABLE (deprecated)
13210 | SERVER_DISABLE (deprecated)
13400 | ADMIN_SHOWCONF
13401 | USER_CREATE
13402 | USER_IMPORT
13403 | USER_MODDESC
13404 | USER_MODPWD
13405 | USER_MODAUTHMECH
13406 | USER_MODACCVALID
13407 | USER_MODPWDVALID
13408 | USER_DELETE
13409 | USER_SHOWGROUPS
13410 | USER_SHOW
13411 | USER_SHOWDN
13412 | USER_LIST
13413 | USER_LISTDN
13414 | GROUP_CREATE
13415 | GROUP_IMPORT
13416 | GROUP_MODDESC
13417 | GROUP_MODADD
13418 | GROUP_MODREMOVE
13419 | GROUP_DELETE
13420 | GROUP_SHOW
13421 | GROUP_SHOWDN
13422 | GROUP_LIST
13423 | GROUP_LISTDN
13424 | GROUP_SHOWMEMB
13425 | USER_MODGSOUSER
13426 | USER_SET (deprecated)
13427 | GROUP_SET (deprecated)
13428 | GROUP_MODADD2
13500 | GSO_RESOURCE_CREATE
13501 | GSO_RESOURCE_DELETE
13502 | GSO_RESOURCE_LIST
13503 | GSO_RESOURCE_SHOW
13504 | GSO_RESOURCE_CRED_CREATE
13505 | GSO_RESOURCE_CRED_DELETE
13506 | GSO_RESOURCE_CRED_MODIFY
13507 | GSO_RESOURCE_CRED_LIST
13508 | GSO_RESOURCE_CRED_SHOW
13509 | GSO_RESOURCE_GROUP_CREATE
13510 | GSO_RESOURCE_GROUP_DELETE
13511 | GSO_RESOURCE_GROUP_ADD
13512 | GSO_RESOURCE_GROUP_REMOVE
13513 | GSO_RESOURCE_GROUP_LIST
13514 | GSO_RESOURCE_GROUP_SHOW
13600 | POLICY_SET_MAX_LOGIN_FAILURES
13601 | POLICY_GET_MAX_LOGIN_FAILURES
13602 | POLICY_SET_DISABLE_TIME_INTERVAL
13603 | POLICY_GET_DISABLE_TIME_INTERVAL
13604 | POLICY_SET_MAX_ACCOUNT_AGE
13605 | POLICY_GET_MAX_ACCOUNT_AGE
13606 | POLICY_SET_ACCOUNT_EXPIRY_DATE
13607 | POLICY_GET_ACCOUNT_EXPIRY_DATE
13608 | POLICY_SET_MAX_INACTIVITY_TIME
13609 | POLICY_GET_MAX_INACTIVITY_TIME
13610 | POLICY_GET_ACCOUNT_CREATION_DATE
13611 | POLICY_GET_LAST_LOGIN_ATTEMPT_DATE
13612 | POLICY_SET_MAX_PASSWORD_AGE
13613 | POLICY_GET_MAX_PASSWORD_AGE
13614 | POLICY_SET_MIN_PASSWORD_AGE
13615 | POLICY_GET_MIN_PASSWORD_AGE
13616 | POLICY_SET_MAX_PASSWORD_REPEATED_CHARS
13617 | POLICY_GET_MAX_PASSWORD_REPEATED_CHARS
13618 | POLICY_SET_MIN_PASSWORD_ALPHAS
13619 | POLICY_GET_MIN_PASSWORD_ALPHAS
13620 | POLICY_SET_MIN_PASSWORD_NON_ALPHAS
13621 | POLICY_GET_MIN_PASSWORD_NON_ALPHAS
13622 | POLICY_SET_MIN_PASSWORD_DIFFERENT_CHARS
13623 | POLICY_GET_MIN_PASSWORD_DIFFERENT_CHARS
13624 | POLICY_SET_PASSWORD_SPACES
13625 | POLICY_GET_PASSWORD_SPACES
13626 | POLICY_SET_MIN_PASSWORD_LENGTH
13627 | POLICY_GET_MIN_PASSWORD_LENGTH
13628 | POLICY_SET_MIN_PASSWORD_REUSE_TIME
13629 | POLICY_GET_MIN_PASSWORD_REUSE_TIME
13630 | POLICY_GET_PASSWORD_FAILURES
13631 | POLICY_GET_LAST_PASSWORD_CHANGE_DATE
13632 | POLICY_SET_NUMBER_WARN_DAYS
13633 | POLICY_GET_NUMBER_WARN_DAYS
13634 | POLICY_SET_PASSWORD_REUSE_NUM
13635 | POLICY_GET_PASSWORD_REUSE_NUM
13636 | POLICY_SET_TOD_ACCESS
13637 | POLICY_GET_TOD_ACCESS
13638 | POLICY_GET_ALL_POLICY
13639 | POLICY_SET_MAX_CONCURRENT_WEB_SESSIONS
13640 | POLICY_GET_MAX_CONCURRENT_WEB_SESSIONS
13700 | POP_CREATE
13701 | POP_DELETE
13702 | POP_MODIFY
13703 | POP_SHOW
13704 | POP_LIST
13705 | POP_ATTACH
13706 | POP_DETACH
13707 | POP_FIND
13800 | CFG_CONFIG
13801 | CFG_UNCONFIG
13802 | CFG_RENEWCERT
13803 | CFG_SETPORT
13804 | CFG_SETLISTENING
13805 | CFG_SETKEYRINGPWD
13806 | CFG_SETSSLTIMEOUT
13807 | CFG_SETAPPLCERT
13808 | CFG_ADDREPLICA
13809 | CFG_CHGREPLICA
13810 | CFG_RMVREPLICA
13811 | CFG_GETVALUE
13812 | CFG_SETVALUE
13813 | CFG_RMVVALUE
13814 | CFG_SETSVRPWD
13900 | DOMAIN_CREATE
13901 | DOMAIN_DELETE
13902 | DOMAIN_MODIFY_DESC
13903 | DOMAIN_SHOW
13904 | DOMAIN_LIST
13950 | AUTHZRULE_CREATE
13951 | AUTHZRULE_DELETE
13952 | AUTHZRULE_MODIFYTEXT
13953 | AUTHZRULE_MODIFYREASON
13954 | AUTHZRULE_MODIFYDESC
13955 | AUTHZRULE_SHOW
13956 | AUTHZRULE_LIST
13957 | AUTHZRULE_ATTACH
13958 | AUTHZRULE_DETACH
13959 | AUTHZRULE_FIND
13960 | AUTHZRULE_MOD_SET_ATTR
13961 | AUTHZRULE_MOD_DEL_ATTR
13962 | AUTHZRULE_MOD_DEL_ATTRVAL
13963 | AUTHZRULE_SHOW_ATTRS
13964 | AUTHZRULE_SHOW_ATTR
13965 | AUTHZRULE_LIST_ATTR

Parent topic: XML output of native audit events

Authentication failuresauthenticationfailureThe reason for authentication failure is included in two different locations in the authentication audit event: The data elementThe outcome elementPrimarily, the data element is for compatibility with the earlier version of audit events. Later versions of audit events use the outcome element.XML output of native audit eventsData output for errorsOutcome output for failures

Authentication failures

The reason for authentication failure is included in two different locations in the authentication audit event:

The data element

The outcome element

Primarily, the data element is for compatibility with the earlier version of audit events. Later versions of audit events use the outcome element.

Data output for errors

Outcome output for failures

Parent topic: XML output of native audit events

Data output for errorsdataoutput errorTable 1 lists the authentication error codes and the data output element structures that are returned when an authentication attempt fails.Authentication errorsError typeError code (in hex)Error code (in decimal)Generated XMLPassword failure132120c8320938184 <data> Password failure: user </data>Account lock-out13212132320938290 <data> Account lock-out: user </data>General failureAll othersAll others <data> <username>user</username> </data>Authentication failures

Data output for errors

Table 237 lists the authentication error codes and the data output element structures that are returned when an authentication attempt fails.

Table 237. Authentication errors

Error type
Error code (in hex)
Error code (in decimal)
Generated XML

Password failure
132120c8
320938184

<data>
Password failure: user
</data>

Account lock-out
13212132
320938290

<data>
Account lock-out: user
</data>

General failure
All others
All others

<data>
<username>user</username>
</data>

Parent topic: Authentication failures

Outcome output for failuresauthenticationoutcome outputThe outcome element provides more detailed information about the authentication failure. The following snippet of an audit event shows the outcome element: <outcome status="320938184" reason="authenticationFailure">The following list explains the meaning for the reason attribute of the outcome element: accountDisabledThe account is disabled.accountDisabledRetryViolationThe account was disabled because of a violation of the max-login-failures policy. The account was permanently disabled.accountExpiredThe account is expired or disabled.accountLockedOutMaxLoginFailThe login failed because the account is temporarily disabled due to the max-login-failures policy.authenticationFailureGeneral authentication failure, including incorrect password.certificateFailureIncorrect SSL certificate.invalidUserNameIncorrect user name.nextTokenToken authentication requires next token.passwordExpiredThe password expired and must be changed.pinRequiredToken authentication requires a new PIN (personal identification number).policyViolationMaxLotginsReachedViolation of the max-concurrent-web-session policy.policyViolationTODViolation of the time-of-day policy.userNameMismatchAttempt at authentication or step-up authenticate failed because the user name that was provided did not match the previous user name.Authentication failures

Outcome output for failures

The outcome element provides more detailed information about the authentication failure. The following snippet of an audit event shows the outcome element:

<outcome status="320938184" reason="authenticationFailure">

The following list explains the meaning for the reason attribute of the outcome element:

accountDisabled

The account is disabled.

accountDisabledRetryViolation

The account was disabled because of a violation of the max-login-failures policy. The account was permanently disabled.

accountExpired

The account is expired or disabled.

accountLockedOutMaxLoginFail

The login failed because the account is temporarily disabled due to the max-login-failures policy.

authenticationFailure

General authentication failure, including incorrect password.

certificateFailure

Incorrect SSL certificate.

invalidUserName

Incorrect user name.

nextToken

Token authentication requires next token.

passwordExpired

The password expired and must be changed.

pinRequired

Token authentication requires a new PIN (personal identification number).

policyViolationMaxLotginsReached

Violation of the max-concurrent-web-session policy.

policyViolationTOD

Violation of the time-of-day policy.

userNameMismatch

Attempt at authentication or step-up authenticate failed because the user name that was provided did not match the previous user name.

Parent topic: Authentication failures

Elements by event typesThis section lists the elements that are available for each common audit event type.For each event type, this documentation provides a description of the event and a listing of the available element. For each available element, the table provides the element name, whether it is always in the event output, and its abbreviated XPath statement.The abbreviated XPath statement is represented in one of the following ways:elementelement_type.elementWhen the representation is element, the full XPath statement would be:CommonBaseEvent/extendedDataElements[@name='element']/values When the representation is element_type.element, the full XPath statement would be:CommonBaseEvent/extendedDataElements[@name='element_type']/children [@name='element']/valuesFor detailed information about these elements and element types, see Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types..Audit eventsElements for AUDIT_AUTHN eventsThis event type identifies authentication events.Elements for AUDIT_AUTHN_CREDS_MODIFY eventsThis event type modifies credentials for a given user identity.Elements for AUDIT_AUTHN_MAPPING eventsThis event type records the mapping of principal and credentials where there are two user identities involved.Elements for AUDIT_AUTHN_TERMINATE eventsThis event type identifies authentication termination events.Elements for AUDIT_AUTHZ eventsThis event type identifies authorization events.Elements for AUDIT_COMPLIANCE eventsThis event type records whether a specified security policy was being complied with.Elements for AUDIT_DATA_SYNC eventsThe event type provides information on data synchronization events.Elements for AUDIT_MGMT_CONFIG eventsThis event type identifies configuration and other management events for a server.Elements for AUDIT_MGMT_POLICY eventsThis event type identifies the security policy management events, such as creation of access control lists.Elements for AUDIT_MGMT_PROVISIONING eventsThis event type identifies provisioning events, such as creating an account for a user on a specific machine.Elements for AUDIT_MGMT_REGISTRY eventsThis event type identifies registry management events, such as creating users and groups, changing passwords by the administrator, and changing the properties for users and groups.Elements for AUDIT_MGMT_RESOURCE eventsThis event type identifies resource management events.Elements for AUDIT_PASSWORD_CHANGE eventsThis event type identifies password changes initiated by the user.Elements for AUDIT_RESOURCE_ACCESS eventsThis event type identifies all accesses to a resource, such as a file or HTTP request or response events outside of the AUDIT_AUTHZ events.Elements for AUDIT_RUNTIME eventsThis event type identifies runtime events, such as starting, stopping, and capacity planning-related events for security servers. This event type is not meant for administrative operations performed by a system administrator. Such operations need to use the AUDIT_MGMT_* event types.Elements for AUDIT_RUNTIME_KEY eventsThis event type identifies certificate expiration and expiration check events that occur during runtime.Elements for AUDIT_WORKFLOW eventsThis event type identifies workflow events.

Elements by event types

This section lists the elements that are available for each common audit event type.

For each event type, this documentation provides a description of the event and a listing of the available element. For each available element, the table provides the element name, whether it is always in the event output, and its abbreviated XPath statement.

The abbreviated XPath statement is represented in one of the following ways:

element

element_type.element

When the representation is element, the full XPath statement would be:

CommonBaseEvent/extendedDataElements[@name='element']/values

When the representation is element_type.element, the full XPath statement would be:

CommonBaseEvent/extendedDataElements[@name='element_type']/children
[@name='element']/values

For detailed information about these elements and element types, see Reference information about elements and element types.

Elements for AUDIT_AUTHN events
This event type identifies authentication events.

Elements for AUDIT_AUTHN_CREDS_MODIFY events
This event type modifies credentials for a given user identity.

Elements for AUDIT_AUTHN_MAPPING events
This event type records the mapping of principal and credentials where there are two user identities involved.

Elements for AUDIT_AUTHN_TERMINATE events
This event type identifies authentication termination events.

Elements for AUDIT_AUTHZ events
This event type identifies authorization events.

Elements for AUDIT_COMPLIANCE events
This event type records whether a specified security policy was being complied with.

Elements for AUDIT_DATA_SYNC events
The event type provides information on data synchronization events.

Elements for AUDIT_MGMT_CONFIG events
This event type identifies configuration and other management events for a server.

Elements for AUDIT_MGMT_POLICY events
This event type identifies the security policy management events, such as creation of access control lists.

Elements for AUDIT_MGMT_PROVISIONING events
This event type identifies provisioning events, such as creating an account for a user on a specific machine.

Elements for AUDIT_MGMT_REGISTRY events
This event type identifies registry management events, such as creating users and groups, changing passwords by the administrator, and changing the properties for users and groups.

Elements for AUDIT_MGMT_RESOURCE events
This event type identifies resource management events.

Elements for AUDIT_PASSWORD_CHANGE events
This event type identifies password changes initiated by the user.

Elements for AUDIT_RESOURCE_ACCESS events
This event type identifies all accesses to a resource, such as a file or HTTP request or response events outside of the AUDIT_AUTHZ events.

Elements for AUDIT_RUNTIME events
This event type identifies runtime events, such as starting, stopping, and capacity planning-related events for security servers. This event type is not meant for administrative operations performed by a system administrator. Such operations need to use the AUDIT_MGMT_* event types.

Elements for AUDIT_RUNTIME_KEY events
This event type identifies certificate expiration and expiration check events that occur during runtime.

Elements for AUDIT_WORKFLOW events
This event type identifies workflow events.

Parent topic: Audit events

Elements for AUDIT_AUTHN eventsThis event type identifies authentication events.The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN event and their abbreviated XPath statements.Elements used in AUDIT_AUTHN eventsElementAlways in outputAbbreviated XPathactionNoactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdauthenProviderNoauthenProviderauthnTypeYesauthnTypeauthnTypeVersionNoauthnTypeVersionendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_AUTHN'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultpartnerNopartnerprogNameNoprogNameregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNamesessionIdNouserInfo.sessionIduniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_AUTHN events

This event type identifies authentication events.

The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN event and their abbreviated XPath statements.

Table 238. Elements used in AUDIT_AUTHN events

Element | Always in output | Abbreviated XPath
action | No | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
authenProvider | No | authenProvider
authnType | Yes | authnType
authnTypeVersion | No | authnTypeVersion
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_AUTHN'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
partner | No | partner
progName | No | progName
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
sessionId | No | userInfo.sessionId
uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_AUTHN_CREDS_MODIFY eventsThis event type modifies credentials for a given user identity.The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN_CREDS_MODIFY event and their abbreviated XPath statements. Elements used in AUDIT_AUTHN_CREDS_MODIFY eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_AUTHN'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNamesessionIdNouserInfo.sessionIduniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_AUTHN_CREDS_MODIFY events

This event type modifies credentials for a given user identity.

The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN_CREDS_MODIFY event and their abbreviated XPath statements.

Table 239. Elements used in AUDIT_AUTHN_CREDS_MODIFY events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_AUTHN'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
sessionId | No | userInfo.sessionId
uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_AUTHN_MAPPING eventsThis event type records the mapping of principal and credentials where there are two user identities involved.The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN_MAPPING event and their abbreviated XPath statements. Elements used in AUDIT_AUTHN_MAPPING eventsElementAlways in outputAbbreviated XPathauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_AUTHN'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.mappedRealmNomappedRealmmappedSecurityDomainYesmappedSecurityDomainmappedUserNameYesmappedUserNameoriginalRealmNooriginalRealmoriginalSecurityDomainYesoriginalSecurityDomainoriginalUserNameYesoriginalUserNameoutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultreporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_AUTHN_MAPPING events

This event type records the mapping of principal and credentials where there are two user identities involved.

The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN_MAPPING event and their abbreviated XPath statements.

Table 240. Elements used in AUDIT_AUTHN_MAPPING events

Element | Always in output | Abbreviated XPath
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_AUTHN'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
mappedRealm | No | mappedRealm
mappedSecurityDomain | Yes | mappedSecurityDomain
mappedUserName | Yes | mappedUserName
originalRealm | No | originalRealm
originalSecurityDomain | Yes | originalSecurityDomain
originalUserName | Yes | originalUserName
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime

Parent topic: Elements by event types

Elements for AUDIT_AUTHN_TERMINATE eventsThis event type identifies authentication termination events.The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN_TERMINATE event and their abbreviated XPath statements. Elements used in AUDIT_AUTHN_TERMINATE eventsElementAlways in outputAbbreviated XPathactionNoactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdauthnTypeYesauthnTypeauthnTypeVersionNoauthnTypeVersionendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_AUTHN'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.loginTimeYesloginTimeoutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultprogNameNoprogNameregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']terminateReasonWhen action is logoutterminateReasontimestampYesCommonBaseEvent/@creationTimeuserInfoWhen action is logoutThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNamesessionIdNouserInfo.sessionIduniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_AUTHN_TERMINATE events

This event type identifies authentication termination events.

The following table lists the elements that can be displayed in the output of an AUDIT_AUTHN_TERMINATE event and their abbreviated XPath statements.

Table 241. Elements used in AUDIT_AUTHN_TERMINATE events

Element | Always in output | Abbreviated XPath
action | No | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
authnType | Yes | authnType
authnTypeVersion | No | authnTypeVersion
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_AUTHN'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
loginTime | Yes | loginTime
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
progName | No | progName
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
terminateReason | When action is logout | terminateReason
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | When action is logout | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
sessionId | No | userInfo.sessionId
uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_AUTHZ eventsThis event type identifies authorization events.The following table lists the elements that can be displayed in the output of an AUDIT_AUTHZ event and their abbreviated XPath statements.Elements used in AUDIT_AUTHZ eventsElementAlways in outputAbbreviated XPathaccessDecisionWhen outcome.result is SUCCESSFULaccessDecisionaccessDecisionReasonWhen accessDecision is DeniedaccessDecisionReasonactionNoactionappNameNoappNameattributePermissionInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributePermissionInfoType element type.attributePermissionInfo attributeNamesYesattributePermissionInfo.attributeNamesattributePermissionInfo checkedYesattributePermissionInfo.checkedattributePermissionInfo deniedNoattributePermissionInfo.deniedattributePermissionInfo grantedNoattributePermissionInfo.grantedattributesNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributeType element type.attributes nameYesattributes.nameattributes sourceNoattributes.sourceattributes valueYesattributes.valueauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_AUTHZ'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultpermissionInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the permissionInfoType element type.permissionInfo checkedYespermissionInfo.checkedpermissionInfo deniedNopermissionInfo.deniedpermissionInfo grantedNopermissionInfo.grantedpermissionInfo J2EERolesCheckedNopermissionInfo.J2EERolesCheckedpermissionInfo J2EERolesGrantedNopermissionInfo.J2EERolesGrantedpolicyInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the policyInfoType element type.policyInfo attributesNopolicyInfo.attributespolicyInfo branchNopolicyInfo.branchpolicyInfo descriptionYespolicyInfo.descriptionpolicyInfo nameYespolicyInfo.namepolicyInfo typeYespolicyInfo.typeregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.resourceInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.resourceInfo attributesNoresourceInfo.attributesresourceInfo nameInAppYesresourceInfo.nameInAppresourceInfo nameInPolicyYesresourceInfo.nameInPolicyresourceInfo typeYesresourceInfo.typesequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_AUTHZ events

This event type identifies authorization events.

The following table lists the elements that can be displayed in the output of an AUDIT_AUTHZ event and their abbreviated XPath statements.

Table 242. Elements used in AUDIT_AUTHZ events

Element | Always in output | Abbreviated XPath
accessDecision | When outcome.result is SUCCESSFUL | accessDecision
accessDecisionReason | When accessDecision is Denied | accessDecisionReason
action | No | action
appName | No | appName
attributePermissionInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributePermissionInfoType element type.
attributePermissionInfo attributeNames | Yes | attributePermissionInfo.attributeNames
attributePermissionInfo checked | Yes | attributePermissionInfo.checked
attributePermissionInfo denied | No | attributePermissionInfo.denied
attributePermissionInfo granted | No | attributePermissionInfo.granted
attributes | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributeType element type.
attributes name | Yes | attributes.name
attributes source | No | attributes.source
attributes value | Yes | attributes.value
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_AUTHZ'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
permissionInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the permissionInfoType element type.
permissionInfo checked | Yes | permissionInfo.checked
permissionInfo denied | No | permissionInfo.denied
permissionInfo granted | No | permissionInfo.granted
permissionInfo J2EERolesChecked | No | permissionInfo.J2EERolesChecked
permissionInfo J2EERolesGranted | No | permissionInfo.J2EERolesGranted
policyInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the policyInfoType element type.
policyInfo attributes | No | policyInfo.attributes
policyInfo branch | No | policyInfo.branch
policyInfo description | Yes | policyInfo.description
policyInfo name | Yes | policyInfo.name
policyInfo type | Yes | policyInfo.type
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
resourceInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.
resourceInfo attributes | No | resourceInfo.attributes
resourceInfo nameInApp | Yes | resourceInfo.nameInApp
resourceInfo nameInPolicy | Yes | resourceInfo.nameInPolicy
resourceInfo type | Yes | resourceInfo.type
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_COMPLIANCE eventsThis event type records whether a specified security policy was being complied with.The following table lists the elements that can be displayed in the output of an AUDIT_COMPLIANCE event and their abbreviated XPath statements.Elements used in AUDIT_COMPLIANCE eventsElementAlways in outputAbbreviated XPathauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdcomplianceStatusYescomplianceStatusendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_COMPLIANCE'"fixDescriptionNofixDescriptionfixIdNofixIdglobalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.messageNomessageoutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultpolicyDescriptionNopolicyDescriptionpolicyNameNopolicyNamerecommendationNorecommendationreporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.severityNoseveritysourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdsuppressedNosuppressedstartTimeNostartTime [type='dateTime']targetAccountNotargetAccounttargetResourceNotargetResourcetargetUserNotargetUsertimestampYesCommonBaseEvent/@creationTimeviolationClassificationNoviolationClassificationviolationDescriptionNoviolationDescriptionviolationNameWhen complianceStatus is nonCompliantviolationNameElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_COMPLIANCE events

This event type records whether a specified security policy was being complied with.

The following table lists the elements that can be displayed in the output of an AUDIT_COMPLIANCE event and their abbreviated XPath statements.

Table 243. Elements used in AUDIT_COMPLIANCE events

Element | Always in output | Abbreviated XPath
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
complianceStatus | Yes | complianceStatus
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_COMPLIANCE'"
fixDescription | No | fixDescription
fixId | No | fixId
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
message | No | message
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
policyDescription | No | policyDescription
policyName | No | policyName
recommendation | No | recommendation
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
severity | No | severity
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
suppressed | No | suppressed
startTime | No | startTime [type='dateTime']
targetAccount | No | targetAccount
targetResource | No | targetResource
targetUser | No | targetUser
timestamp | Yes | CommonBaseEvent/@creationTime
violationClassification | No | violationClassification
violationDescription | No | violationDescription
violationName | When complianceStatus is nonCompliant | violationName

Parent topic: Elements by event types

Elements for AUDIT_DATA_SYNC eventsThe event type provides information on data synchronization events.The following table lists the elements that can be displayed in the output of an AUDIT_DATA_SYNC event and their abbreviated XPath statements.Elements used in AUDIT_DATA_SYNC eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdextensionNameNoendTime [type='dateTime']eventTypeYes”'AUDIT_DATA_SYNC'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultoutcome registryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.outcome serverLocationYesregistryInfo.serverLocationoutcome serverLocationTypeYesregistryInfo.serverLocationTypeoutcome serverPortYesregistryInfo.serverPortoutcome typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.resourceInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.resourceInfo attributesNoresourceInfo.attributesresourceInfo nameInAppYesresourceInfo.nameInAppresourceInfo nameInPolicyYesresourceInfo.nameInPolicyresourceInfo typeYesresourceInfo.typesequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_DATA_SYNC events

The event type provides information on data synchronization events.

The following table lists the elements that can be displayed in the output of an AUDIT_DATA_SYNC event and their abbreviated XPath statements.

Table 244. Elements used in AUDIT_DATA_SYNC events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
extensionName | No | endTime [type='dateTime']
eventType | Yes | ”'AUDIT_DATA_SYNC'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
outcome registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
outcome serverLocation | Yes | registryInfo.serverLocation
outcome serverLocationType | Yes | registryInfo.serverLocationType
outcome serverPort | Yes | registryInfo.serverPort
outcome type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
resourceInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.
resourceInfo attributes | No | resourceInfo.attributes
resourceInfo nameInApp | Yes | resourceInfo.nameInApp
resourceInfo nameInPolicy | Yes | resourceInfo.nameInPolicy
resourceInfo type | Yes | resourceInfo.type
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_MGMT_CONFIG eventsThis event type identifies configuration and other management events for a server.The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_CONFIG event and their abbreviated XPath statements.Elements used in AUDIT_MGMT_CONFIG eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_MGMT_CONFIG'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.mgmtInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.mgmtInfo commandNomgmtInfo.commandmgmtInfo targetInfoNomgmtInfo.targetInfooutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimetypeYestypeuserInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_MGMT_CONFIG events

This event type identifies configuration and other management events for a server.

The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_CONFIG event and their abbreviated XPath statements.

Table 245. Elements used in AUDIT_MGMT_CONFIG events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_MGMT_CONFIG'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
mgmtInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.
mgmtInfo command | No | mgmtInfo.command
mgmtInfo targetInfo | No | mgmtInfo.targetInfo
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
type | Yes | type
userInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_MGMT_POLICY eventsThis event type identifies the security policy management events, such as creation of access control lists.The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_POLICY event and their abbreviated XPath statements.Elements used in AUDIT_MGMT_POLICY eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_MGMT_POLICY'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.membershipsNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the membershipInfoType element type.memberships idNomemberships.idmemberships nameNomemberships.namememberships typeYesmemberships.typemgmtInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.mgmtInfo commandNomgmtInfo.commandmgmtInfo targetInfoNomgmtInfo.targetInfooutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultpolicyInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the policyInfoType element type.policyInfo attributesNopolicyInfo.attributespolicyInfo branchNopolicyInfo.branchpolicyInfo descriptionYespolicyInfo.descriptionpolicyInfo nameYespolicyInfo.namepolicyInfo typeYespolicyInfo.typeregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.resourceInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.resourceInfo attributesNoresourceInfo.attributesresourceInfo nameInAppYesresourceInfo.nameInAppresourceInfo nameInPolicyYesresourceInfo.nameInPolicyresourceInfo typeYesresourceInfo.typesequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_MGMT_POLICY events

This event type identifies the security policy management events, such as creation of access control lists.

The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_POLICY event and their abbreviated XPath statements.

Table 246. Elements used in AUDIT_MGMT_POLICY events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_MGMT_POLICY'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
memberships | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the membershipInfoType element type.
memberships id | No | memberships.id
memberships name | No | memberships.name
memberships type | Yes | memberships.type
mgmtInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.
mgmtInfo command | No | mgmtInfo.command
mgmtInfo targetInfo | No | mgmtInfo.targetInfo
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
policyInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the policyInfoType element type.
policyInfo attributes | No | policyInfo.attributes
policyInfo branch | No | policyInfo.branch
policyInfo description | Yes | policyInfo.description
policyInfo name | Yes | policyInfo.name
policyInfo type | Yes | policyInfo.type
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
resourceInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.
resourceInfo attributes | No | resourceInfo.attributes
resourceInfo nameInApp | Yes | resourceInfo.nameInApp
resourceInfo nameInPolicy | Yes | resourceInfo.nameInPolicy
resourceInfo type | Yes | resourceInfo.type
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_MGMT_PROVISIONING eventsThis event type identifies provisioning events, such as creating an account for a user on a specific machine.The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_PROVISIONING event and their abbreviated XPath statements.Elements used in AUDIT_MGMT_PROVISIONING eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_MGMT_PROVISIONING'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultprovisioningInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the provisioningInfoType element type.provisioningInfo accountIdNoprovisioningInfo.accountIdprovisioningInfo resourceIdYesprovisioningInfo.resourceIdprovisioningInfo resourceTypeYesprovisioningInfo.resourceTyperegistryInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']targetUserInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryObjectInfoType element type.targetUserInfo attributesNoregistryObjectInfo.attributestargetUserInfo descriptionNoregistryObjectInfo.descriptiontargetUserInfo nameYesregistryObjectInfo.nametargetUserInfo registryNameNoregistryObjectInfo.registryNametargetUserInfo typeYesregistryObjectInfo.typetargetUserRegistryInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the targetUserRegistryInfoType element type.targetUserRegistryInfo serverLocationYesregistryInfo.serverLocationtargetUserRegistryInfo serverLocationTypeYesregistryInfo.serverLocationTypetargetUserRegistryInfo serverPortYesregistryInfo.serverPorttargetUserRegistryInfo typeYesregistryInfo.typetimestampYesCommonBaseEvent/@creationTimeuserInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_MGMT_PROVISIONING events

This event type identifies provisioning events, such as creating an account for a user on a specific machine.

The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_PROVISIONING event and their abbreviated XPath statements.

Table 247. Elements used in AUDIT_MGMT_PROVISIONING events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_MGMT_PROVISIONING'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
provisioningInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the provisioningInfoType element type.
provisioningInfo accountId | No | provisioningInfo.accountId
provisioningInfo resourceId | Yes | provisioningInfo.resourceId
provisioningInfo resourceType | Yes | provisioningInfo.resourceType
registryInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
targetUserInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryObjectInfoType element type.
targetUserInfo attributes | No | registryObjectInfo.attributes
targetUserInfo description | No | registryObjectInfo.description
targetUserInfo name | Yes | registryObjectInfo.name
targetUserInfo registryName | No | registryObjectInfo.registryName
targetUserInfo type | Yes | registryObjectInfo.type
targetUserRegistryInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the targetUserRegistryInfoType element type.
targetUserRegistryInfo serverLocation | Yes | registryInfo.serverLocation
targetUserRegistryInfo serverLocationType | Yes | registryInfo.serverLocationType
targetUserRegistryInfo serverPort | Yes | registryInfo.serverPort
targetUserRegistryInfo type | Yes | registryInfo.type
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_MGMT_REGISTRY eventsThis event type identifies registry management events, such as creating users and groups, changing passwords by the administrator, and changing the properties for users and groups.The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_REGISTRY event and their abbreviated XPath statements.Elements used in AUDIT_MGMT_REGISTRY eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_MGMT_REGISTRY'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.mgmtInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.mgmtInfo commandNomgmtInfo.commandmgmtInfo targetInfoNomgmtInfo.targetInfooutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typeregistryObjectInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryObjectInfoType element type.registryObjectInfo attributesNoregistryObjectInfo.attributesregistryObjectInfo descriptionNoregistryObjectInfo.descriptionregistryObjectInfo nameYesregistryObjectInfo.nameregistryObjectInfo registryNameNoregistryObjectInfo.registryNameregistryObjectInfo typeYesregistryObjectInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_MGMT_REGISTRY events

This event type identifies registry management events, such as creating users and groups, changing passwords by the administrator, and changing the properties for users and groups.

The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_REGISTRY event and their abbreviated XPath statements.

Table 248. Elements used in AUDIT_MGMT_REGISTRY events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_MGMT_REGISTRY'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
mgmtInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.
mgmtInfo command | No | mgmtInfo.command
mgmtInfo targetInfo | No | mgmtInfo.targetInfo
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
registryObjectInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryObjectInfoType element type.
registryObjectInfo attributes | No | registryObjectInfo.attributes
registryObjectInfo description | No | registryObjectInfo.description
registryObjectInfo name | Yes | registryObjectInfo.name
registryObjectInfo registryName | No | registryObjectInfo.registryName
registryObjectInfo type | Yes | registryObjectInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_MGMT_RESOURCE eventsThis event type identifies resource management events.The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_RESOURCE event and their abbreviated XPath statements.Elements used in AUDIT_MGMT_RESOURCE eventsElementAlways in outputAbbreviated XPathActionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_MGMT_RESOURCE'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.mgmtInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.mgmtInfo commandNomgmtInfo.commandmgmtInfo targetInfoNomgmtInfo.targetInfooutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.registryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryObjectInfoType element type.registryInfo attributesNoregistryObjectInfo.attributesregistryInfo descriptionNoregistryObjectInfo.descriptionregistryInfo nameYesregistryObjectInfo.nameregistryInfo registryNameNoregistryObjectInfo.registryNameregistryInfo typeYesregistryObjectInfo.typeresourceInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.resourceInfo attributesNoresourceInfo.attributesresourceInfo nameInAppYesresourceInfo.nameInAppresourceInfo nameInPolicyYesresourceInfo.nameInPolicyresourceInfo typeYesresourceInfo.typesequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_MGMT_RESOURCE events

This event type identifies resource management events.

The following table lists the elements that can be displayed in the output of an AUDIT_MGMT_RESOURCE event and their abbreviated XPath statements.

Table 249. Elements used in AUDIT_MGMT_RESOURCE events

Element | Always in output | Abbreviated XPath
Action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_MGMT_RESOURCE'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
mgmtInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the mgmtInfoType element type.
mgmtInfo command | No | mgmtInfo.command
mgmtInfo targetInfo | No | mgmtInfo.targetInfo
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryObjectInfoType element type.
registryInfo attributes | No | registryObjectInfo.attributes
registryInfo description | No | registryObjectInfo.description
registryInfo name | Yes | registryObjectInfo.name
registryInfo registryName | No | registryObjectInfo.registryName
registryInfo type | Yes | registryObjectInfo.type
resourceInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.
resourceInfo attributes | No | resourceInfo.attributes
resourceInfo nameInApp | Yes | resourceInfo.nameInApp
resourceInfo nameInPolicy | Yes | resourceInfo.nameInPolicy
resourceInfo type | Yes | resourceInfo.type
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_PASSWORD_CHANGE eventsThis event type identifies password changes initiated by the user.The following table lists the elements that can be displayed in the output of an AUDIT_PASSWORD_CHANGE event and their abbreviated XPath statements.Elements used in AUDIT_PASSWORD_CHANGE eventsElementAlways in outputAbbreviated XPathauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_PASSWORD_CHANGE'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultprovisioningInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the provisioningInfoType element type.provisioningInfo accountIdNoprovisioningInfo.accountIdprovisioningInfo resourceIdYesprovisioningInfo.resourceIdprovisioningInfo resourceTypeYesprovisioningInfo.resourceTyperegistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_PASSWORD_CHANGE events

This event type identifies password changes initiated by the user.

The following table lists the elements that can be displayed in the output of an AUDIT_PASSWORD_CHANGE event and their abbreviated XPath statements.

Table 250. Elements used in AUDIT_PASSWORD_CHANGE events

Element | Always in output | Abbreviated XPath
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_PASSWORD_CHANGE'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
provisioningInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the provisioningInfoType element type.
provisioningInfo accountId | No | provisioningInfo.accountId
provisioningInfo resourceId | Yes | provisioningInfo.resourceId
provisioningInfo resourceType | Yes | provisioningInfo.resourceType
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_RESOURCE_ACCESS eventsThis event type identifies all accesses to a resource, such as a file or HTTP request or response events outside of the AUDIT_AUTHZ events.The following table lists the elements that can be displayed in the output of an AUDIT_RESOURCE_ACCESS event and their abbreviated XPath statements.Elements used in AUDIT_RESOURCE_ACCESS eventsElementAlways in outputAbbreviated XPathaccessDecisionNoaccessDecisionaccessDecisionReasonWhen accessDecision is DeniedaccessDecisionReasonactionYesactionappNameNoappNameattributePermissionInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributePermissionInfoType element type.attributePermissionInfo attributeNamesYesattributePermissionInfo.attributeNamesattributePermissionInfo checkedYesattributePermissionInfo.checkedattributePermissionInfo deniedNoattributePermissionInfo.deniedattributePermissionInfo grantedNoattributePermissionInfo.grantedauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_RESOURCE_ACCESS'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.httpURLInfoWhen action is HTTPRequestThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the HTTPURLInfoType element type.httpURLInfo methodNoHTTPURLInfo.methodhttpURLInfo requestHeadersHTTPURLInfo.requestHeadershttpURLInfo responseCodeHTTPURLInfo.responseCodehttpURLInfo responseHeadersHTTPURLInfo.responseHeadershttpURLInfo urlHTTPURLInfo.urloutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultpermissionInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the permissionInfoType element type.permissionInfo checkedYespermissionInfo.checkedpermissionInfo deniedNopermissionInfo.deniedpermissionInfo grantedNopermissionInfo.grantedpermissionInfo J2EERolesCheckedNopermissionInfo.J2EERolesCheckedpermissionInfo J2EERolesGrantedNopermissionInfo.J2EERolesGrantedregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from the sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.resourceInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.resourceInfo attributesNoresourceInfo.attributesresourceInfo nameInAppYesresourceInfo.nameInAppresourceInfo nameInPolicyYesresourceInfo.nameInPolicyresourceInfo typeYesresourceInfo.typesequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_RESOURCE_ACCESS events

This event type identifies all accesses to a resource, such as a file or HTTP request or response events outside of the AUDIT_AUTHZ events.

The following table lists the elements that can be displayed in the output of an AUDIT_RESOURCE_ACCESS event and their abbreviated XPath statements.

Table 251. Elements used in AUDIT_RESOURCE_ACCESS events

Element | Always in output | Abbreviated XPath
accessDecision | No | accessDecision
accessDecisionReason | When accessDecision is Denied | accessDecisionReason
action | Yes | action
appName | No | appName
attributePermissionInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributePermissionInfoType element type.
attributePermissionInfo attributeNames | Yes | attributePermissionInfo.attributeNames
attributePermissionInfo checked | Yes | attributePermissionInfo.checked
attributePermissionInfo denied | No | attributePermissionInfo.denied
attributePermissionInfo granted | No | attributePermissionInfo.granted
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_RESOURCE_ACCESS'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
httpURLInfo | When action is HTTPRequest | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the HTTPURLInfoType element type.
httpURLInfo method | No | HTTPURLInfo.method
httpURLInfo requestHeaders |  | HTTPURLInfo.requestHeaders
httpURLInfo responseCode |  | HTTPURLInfo.responseCode
httpURLInfo responseHeaders |  | HTTPURLInfo.responseHeaders
httpURLInfo url |  | HTTPURLInfo.url
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
permissionInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the permissionInfoType element type.
permissionInfo checked | Yes | permissionInfo.checked
permissionInfo denied | No | permissionInfo.denied
permissionInfo granted | No | permissionInfo.granted
permissionInfo J2EERolesChecked | No | permissionInfo.J2EERolesChecked
permissionInfo J2EERolesGranted | No | permissionInfo.J2EERolesGranted
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from the sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
resourceInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.
resourceInfo attributes | No | resourceInfo.attributes
resourceInfo nameInApp | Yes | resourceInfo.nameInApp
resourceInfo nameInPolicy | Yes | resourceInfo.nameInPolicy
resourceInfo type | Yes | resourceInfo.type
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_RUNTIME eventsThis event type identifies runtime events, such as starting, stopping, and capacity planning-related events for security servers. This event type is not meant for administrative operations performed by a system administrator. Such operations need to use the AUDIT_MGMT_* event types.The following table lists the elements that can be displayed in the output of an AUDIT_RUNTIME event and their abbreviated XPath statements.Elements used in AUDIT_RUNTIME eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_RUNTIME'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultperfInfoWhen action is statisticThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the perfInfoType element type.perfInfo aggregateYesperfInfo.aggregateperfInfo descriptionYesperfInfo.descriptionperfInfo nameYesperfInfo.nameperfInfo maxValueNoperfInfo.maxValueperfInfo minValueNoperfInfo.minValueperfInfo numDataPointsYesperfInfo.numDataPointsperfInfo unitYesperfInfo.unitperfInfo valueYesperfInfo.valueregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from the sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.resourceInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.resourceInfo attributesNoresourceInfo.attributesresourceInfo nameInAppYesresourceInfo.nameInAppresourceInfo nameInPolicyYesresourceInfo.nameInPolicyresourceInfo typeYesresourceInfo.typesequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_RUNTIME events

This event type identifies runtime events, such as starting, stopping, and capacity planning-related events for security servers. This event type is not meant for administrative operations performed by a system administrator. Such operations need to use the AUDIT_MGMT_* event types.

The following table lists the elements that can be displayed in the output of an AUDIT_RUNTIME event and their abbreviated XPath statements.

Table 252. Elements used in AUDIT_RUNTIME events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_RUNTIME'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
perfInfo | When action is statistic | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the perfInfoType element type.
perfInfo aggregate | Yes | perfInfo.aggregate
perfInfo description | Yes | perfInfo.description
perfInfo name | Yes | perfInfo.name
perfInfo maxValue | No | perfInfo.maxValue
perfInfo minValue | No | perfInfo.minValue
perfInfo numDataPoints | Yes | perfInfo.numDataPoints
perfInfo unit | Yes | perfInfo.unit
perfInfo value | Yes | perfInfo.value
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from the sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
resourceInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the resourceInfoType element type.
resourceInfo attributes | No | resourceInfo.attributes
resourceInfo nameInApp | Yes | resourceInfo.nameInApp
resourceInfo nameInPolicy | Yes | resourceInfo.nameInPolicy
resourceInfo type | Yes | resourceInfo.type
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_RUNTIME_KEY eventsThis event type identifies certificate expiration and expiration check events that occur during runtime.The following table lists the elements that can be displayed in the output of an AUDIT_RUNTIME_KEY event and their abbreviated XPath statements.Elements used in AUDIT_RUNTIME_KEY eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_RUNTIME_KEY'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.keyLabelYeskeyLabellifetimeNolifetimelocationYeslocationlocationTypeYeslocationTypeoutcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from the sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']timestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIdElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_RUNTIME_KEY events

This event type identifies certificate expiration and expiration check events that occur during runtime.

The following table lists the elements that can be displayed in the output of an AUDIT_RUNTIME_KEY event and their abbreviated XPath statements.

Table 253. Elements used in AUDIT_RUNTIME_KEY events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_RUNTIME_KEY'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
keyLabel | Yes | keyLabel
lifetime | No | lifetime
location | Yes | location
locationType | Yes | locationType
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from the sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId

Parent topic: Elements by event types

Elements for AUDIT_WORKFLOW eventsThis event type identifies workflow events.The following table lists the elements that can be displayed in the output of an AUDIT_WORKFLOW event and their abbreviated XPath statements.Elements used in AUDIT_WORKFLOW eventsElementAlways in outputAbbreviated XPathactionYesactionauditMsgNoauditMsgauditMsgElementNoNeither this element, nor its children, should be defined in the shredder configuration file.auditTrailIdNoauditTrailIdendTimeNoendTime [type='dateTime']extensionNameYes”'AUDIT_WORKFLOW'"globalInstanceIdYesNot applicable. This value is an internal number that is not related to #GLOBAL_ID.outcomeYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.outcome failureReasonNooutcome.failureReasonoutcome majorStatusNooutcome.majorStatusoutcome minorStatusNooutcome.minorStatusoutcome resultYesoutcome.resultregistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.registryInfo serverLocationYesregistryInfo.serverLocationregistryInfo serverLocationTypeYesregistryInfo.serverLocationTyperegistryInfo serverPortYesregistryInfo.serverPortregistryInfo typeYesregistryInfo.typereporterComponentIdWhen different from sourceComponentIdNeither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.sequenceNumberYesNot applicable. This value is an internal number that is not related to #RECORD_ID.sourceComponentIdYesThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.sourceComponentId applicationYesCommonBaseEvent/SourceComponentId/ @applicationsourceComponentId componentYesCommonBaseEvent/SourceComponentId/ @componentsourceComponentId componentIdTypeYesCommonBaseEvent/SourceComponentId/ @componentIdTypesourceComponentId componentTypeYesCommonBaseEvent/SourceComponentId/ @componentTypesourceComponentId executionEnvironmentNoCommonBaseEvent/SourceComponentId/ @executionEnvironmentsourceComponentId instanceIdNoCommonBaseEvent/SourceComponentId/ @instanceIdsourceComponentId locationYesCommonBaseEvent/SourceComponentId/@locationsourceComponentId locationTypeYesCommonBaseEvent/SourceComponentId/ @locationTypesourceComponentId processedNoCommonBaseEvent/SourceComponentId/ @processedsourceComponentId subComponentYesCommonBaseEvent/SourceComponentId/ @subComponentsourceComponentId threadIdNoCommonBaseEvent/SourceComponentId/@threadIdstartTimeNostartTime [type='dateTime']targetUserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.targetUserInfo appUserNameYesuserInfo.appUserNametargetUserInfo attributesNouserInfo.attributestargetUserInfo callerListNouserInfo.callerListtargetUserInfo domainNouserInfo.domaintargetUserInfo locationNouserInfo.locationtargetUserInfo locationTypeNouserInfo.locationTypetargetUserInfo realmNouserInfo.realmtargetUserInfo registryUserNameYesuserInfo.registryUserNametargetUserInfo sessionIdNouserInfo.sessionIdtargetUserInfo uniqueIdNouserInfo.uniqueIdtargetUserRegistryInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.targetUserRegistryInfo serverLocationYesregistryInfo.serverLocationtargetUserRegistryInfo serverLocationTypeYesregistryInfo.serverLocationTypetargetUserRegistryInfo serverPortYesregistryInfo.serverPorttargetUserRegistryInfo typeYesregistryInfo.typetimestampYesCommonBaseEvent/@creationTimeuserInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.userInfo appUserNameYesuserInfo.appUserNameuserInfo attributesNouserInfo.attributesuserInfo callerListNouserInfo.callerListuserInfo domainNouserInfo.domainuserInfo locationNouserInfo.locationuserInfo locationTypeNouserInfo.locationTypeuserInfo realmNouserInfo.realmuserInfo registryUserNameYesuserInfo.registryUserNameuserInfo sessionIdNouserInfo.sessionIduserInfo uniqueIdNouserInfo.uniqueIduserInputsNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributeType element type.userInputs nameYesattributeType.nameuserInputs sourceNoattributeType.sourceuserInputs valueYesattributeType.valueworkItemInfoNoThis element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the workItemInfoType element type.workItemInfo idYesworkItemInfoType.idworkItemInfo typeYesworkItemInfoType.typeElements by event typesThis section lists the elements that are available for each common audit event type.

Elements for AUDIT_WORKFLOW events

This event type identifies workflow events.

The following table lists the elements that can be displayed in the output of an AUDIT_WORKFLOW event and their abbreviated XPath statements.

Table 254. Elements used in AUDIT_WORKFLOW events

Element | Always in output | Abbreviated XPath
action | Yes | action
auditMsg | No | auditMsg
auditMsgElement | No | Neither this element, nor its children, should be defined in the shredder configuration file.
auditTrailId | No | auditTrailId
endTime | No | endTime [type='dateTime']
extensionName | Yes | ”'AUDIT_WORKFLOW'"
globalInstanceId | Yes | Not applicable. This value is an internal number that is not related to #GLOBAL_ID.
outcome | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditOutcomeType element type.
outcome failureReason | No | outcome.failureReason
outcome majorStatus | No | outcome.majorStatus
outcome minorStatus | No | outcome.minorStatus
outcome result | Yes | outcome.result
registryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
registryInfo serverLocation | Yes | registryInfo.serverLocation
registryInfo serverLocationType | Yes | registryInfo.serverLocationType
registryInfo serverPort | Yes | registryInfo.serverPort
registryInfo type | Yes | registryInfo.type
reporterComponentId | When different from sourceComponentId | Neither this element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code. This container element uses the children of the auditComponentIdType element type.
sequenceNumber | Yes | Not applicable. This value is an internal number that is not related to #RECORD_ID.
sourceComponentId | Yes | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the auditComponentIdType element type.
sourceComponentId application | Yes | CommonBaseEvent/SourceComponentId/ @application
sourceComponentId component | Yes | CommonBaseEvent/SourceComponentId/ @component
sourceComponentId componentIdType | Yes | CommonBaseEvent/SourceComponentId/ @componentIdType
sourceComponentId componentType | Yes | CommonBaseEvent/SourceComponentId/ @componentType
sourceComponentId executionEnvironment | No | CommonBaseEvent/SourceComponentId/ @executionEnvironment
sourceComponentId instanceId | No | CommonBaseEvent/SourceComponentId/ @instanceId
sourceComponentId location | Yes | CommonBaseEvent/SourceComponentId/@location
sourceComponentId locationType | Yes | CommonBaseEvent/SourceComponentId/ @locationType
sourceComponentId processed | No | CommonBaseEvent/SourceComponentId/ @processed
sourceComponentId subComponent | Yes | CommonBaseEvent/SourceComponentId/ @subComponent
sourceComponentId threadId | No | CommonBaseEvent/SourceComponentId/@threadId
startTime | No | startTime [type='dateTime']
targetUserInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
targetUserInfo appUserName | Yes | userInfo.appUserName
targetUserInfo attributes | No | userInfo.attributes
targetUserInfo callerList | No | userInfo.callerList
targetUserInfo domain | No | userInfo.domain
targetUserInfo location | No | userInfo.location
targetUserInfo locationType | No | userInfo.locationType
targetUserInfo realm | No | userInfo.realm
targetUserInfo registryUserName | Yes | userInfo.registryUserName
targetUserInfo sessionId | No | userInfo.sessionId
targetUserInfo uniqueId | No | userInfo.uniqueId
targetUserRegistryInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the registryInfoType element type.
targetUserRegistryInfo serverLocation | Yes | registryInfo.serverLocation
targetUserRegistryInfo serverLocationType | Yes | registryInfo.serverLocationType
targetUserRegistryInfo serverPort | Yes | registryInfo.serverPort
targetUserRegistryInfo type | Yes | registryInfo.type
timestamp | Yes | CommonBaseEvent/@creationTime
userInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the userInfoType element type.
userInfo appUserName | Yes | userInfo.appUserName
userInfo attributes | No | userInfo.attributes
userInfo callerList | No | userInfo.callerList
userInfo domain | No | userInfo.domain
userInfo location | No | userInfo.location
userInfo locationType | No | userInfo.locationType
userInfo realm | No | userInfo.realm
userInfo registryUserName | Yes | userInfo.registryUserName
userInfo sessionId | No | userInfo.sessionId
userInfo uniqueId | No | userInfo.uniqueId
userInputs | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the attributeType element type.
userInputs name | Yes | attributeType.name
userInputs source | No | attributeType.source
userInputs value | Yes | attributeType.value
workItemInfo | No | This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the workItemInfoType element type.
workItemInfo id | Yes | workItemInfoType.id
workItemInfo type | Yes | workItemInfoType.type

Parent topic: Elements by event types

Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.For each element and element type that can be used in an audit event, this documentation provides a description, the values that can be displayed in the output, and the XPath statement that can be used when modifying the shredder configuration file.For information on the elements and element types described in this section, refer to the Common Base Event specification at the following Web site: http://www.eclipse.org/tptp/platform/documents/index.phpAudit eventsaccessDecision elementReference information about the accessDecision element.accessDecisionReason elementReference information about the accessDecisionReason element.action elementReference information about the action element.appName elementReference information about the appName element.attributePermissionInfo elementReference information about the attributePermissionInfo element.attributePermissionInfo.attributeNames elementReference information about the attributePermissionInfo.attributeNames element.attributePermissionInfo.checked elementReference information about the attributePermissionInfo.checked element.attributePermissionInfo elementReference information about the attributePermissionInfo.denied element.attributePermissionInfo.granted elementReference information about the attributePermissionInfo.granted element.attributes elementReference information about the attributes element.attributes.name elementReference information about the attributes.name element.attributes.sourceReference information about the attributes.source element.attributes.valueReference information about the attributes.value element.auditMsgReference information about the auditMsg element.auditMsgElementReference information about the auditMsgElement element.auditTrailIdReference information about the auditTrailId element.authenProviderReference information about the authenProvider element.authnTypeReference information about the authnType element.authnTypeVersionReference information about the authnTypeVersion element.complianceStatusReference information about the complianceStatus element.endTimeReference information about the endTime element.extensionNameReference information about the extensionName element.fixDescriptionReference information about the fixDescription element.fixIdReference information about the fixId element.globalInstanceIdReference information about the globalInstanceId element.httpURLInfo elementReference information about the httpURLInfo element.HTTPURLInfo.methodReference information about the HTTPURLInfo.method element.HTTPURLInfo.requestHeadersReference information about the HTTPURLInfo.requestHeaders element.HTTPURLInfo.responseCodeReference information about the HTTPURLInfo.responseCode element.HTTPURLInfo.responseHeadersReference information about the HTTPURLInfo.responseHeaders element.HTTPURLInfo.url elementReference information about the HTTPURLInfo.url element.keyLabelReference information about the keyLabel element.lifetimeReference information about the lifetime element.locationReference information about the location element.locationTypeReference information about the locationType element.loginTimeReference information about the loginTime element.mappedRealmReference information about the mappedRealm element.mappedSecurityDomainReference information about the mappedSecurityDomain element.mappedUserNameReference information about the mappedUserName element.membershipInfoReference information about the membershipInfo element.memberships.id elementReference information about the memberships.id element.memberships.name elementReference information about the memberships.name element.memberships.type elementReference information about the memberships.type element.messageReference information about the message element.mgmtInfoReference information about the mgmtInfo element.mgmtInfo.commandReference information about the mgmtInfo.command element.mgmtInfo.targetInfoReference information about the mgmtInfo.targetInfo element.originalRealmReference information about the originalRealm element.originalSecurityRealmReference information about the originalSecurityRealm element.originalUserNameReference information about the originalUserName element.outcomeReference information about the outcome element.outcome.failureReasonReference information about the outcome.failureReason element.outcome.majorStatusReference information about the outcome.majorStatus element.outcome.minorStatusReference information about the outcome.minorStatus element.outcome.resultReference information about the outcome.result element.partnerReference information about the partner element.perfInfoReference information about the perfInfo element.perfInfo.aggregateReference information about the perfInfo.aggregate element.perfInfo.descriptionReference information about the perfInfo.description element.perfInfo.name elementReference information about the perfInfo.name element.perfInfo.maxValueReference information about the perfInfo.maxValue element.perfInfo.minValueReference information about the perfInfo.minValue element.perfInfo.numDataPointsReference information about the perfInfo.numDataPoints element.perfInfo.unit elementReference information about the perfInfo.unit element.perfInfo.valueReference information about the perfInfo.value element.permissionInfoReference information about the permissionInfo element.permissionInfo.checkedReference information about the permissionInfo.checked element.permissionInfo.deniedReference information about the permissionInfo.denied element.permissionInfo.grantedReference information about the permissionInfo.granted element.permissionInfo.J2EERolesCheckedReference information about the permissionInfo.J2EERolesChecked element.permissionInfo.J2EERolesGrantedReference information about the permissionInfo.J2EERolesGranted element.policyDescriptionReference information about the policyDescription element.policyInfoReference information about the policyInfo element.policyInfo.attributesReference information about the policyInfo.attributes element.policyInfo.branchReference information about the policyInfo.branch element.policyInfo.descriptionReference information about the policyInfo.description element.policyInfo.name elementReference information about the policyInfo.name element.policyInfo.type elementReference information about the policyInfo.type element.policyNameReference information about the policyName element.progNameReference information about the progName element.provisioningInfoReference information about the provisioningInfo element.provisioningInfo.accountIdReference information about the provisioningInfo.accountId element.provisioningInfo.resourceIdReference information about the provisioningInfo.resourceId element.provisioningInfo.resourceTypeReference information about the provisioningInfo.resourceType element.provisioningTargetInfoReference information about the provisioningTargetInfo element.recommendationReference information about the recommendation element.registryInfoReference information about the registryInfo element.registryInfo.serverLocationReference information about the registryInfo.serverLocation element.registryInfo.serverLocationTypeReference information about the registryInfo.serverLocationType element.registryInfo.serverPortReference information about the registryInfo.serverPort element.registryInfo.type elementReference information about the registryInfo.type element.registryObjectInfoReference information about the registryObjectInfo element.registryObjectInfo.attributesReference information about the registryObjectInfo.attributes element.registryObjectInfo.descriptionReference information about the registryObjectInfo.description element.registryObjectInfo.name elementReference information about the registryObjectInfo.name element.registryObjectInfo.registryNameReference information about the registryObjectInfo.registryName element.registryObjectInfo.type elementReference information about the registryObjectInfo.type element.reporterComponentIdReference information about the reporterComponentId element.resourceInfoReference information about the resourceInfo element.resourceInfo.attributesReference information about the resourceInfo.attributes element.resourceInfo.nameInAppReference information about the resourceInfo.nameInApp element.resourceInfo.nameInPolicyReference information about the resourceInfo.nameInPolicy element.resourceInfo.type elementReference information about the resourceInfo.type element.sequenceNumberReference information about the sequenceNumber element.severityReference information about the severity element.sourceComponentIdReference information about the sourceComponentId element.sourceComponentId/@applicationReference information about the sourceComponentId/@application element.sourceComponentId/@componentReference information about the sourceComponentId/@component element.sourceComponentId/@componentIdTypeReference information about the sourceComponentId/@componentIdType element.sourceComponentId/@componentTypeReference information about the sourceComponentId/@componentType element.sourceComponentId/@executionEnvironmentReference information about the sourceComponentId/@executionEnvironment element.sourceComponentId/@instanceIdReference information about the sourceComponentId/@instanceId element.sourceComponentId/@locationReference information about the sourceComponentId/@location element.sourceComponentId/@locationTypeReference information about the sourceComponentId/@locationType element.sourceComponentId/@processIdReference information about the sourceComponentId/@processId element.sourceComponentId/@subComponentReference information about the sourceComponentId/@subComponent element.sourceComponentId/@threadIdReference information about the sourceComponentId/@threadId element.startTimeReference information about the startTime element.suppressedReference information about the suppressed element.targetAccountReference information about the targetAccount element.targetInfoTypeReference information about the targetInfoType element.targetInfo.attributesReference information about the targetInfo.attributes element.targetInfo.targetNamesReference information about the targetInfo.targetNames element.targetResourceReference information about the targetResource element.targetUserReference information about the targetUser element.targetUserInfo (1)Reference information about the targetUserInfo element when used with the AUDIT_WORKFLOW event type.targetUserInfo (2)Reference information about the targetUserInfo element when used with the AUDIT_MGMT_PROVISIONING event type.targetUserRegistryInfoReference information about the targetUserRegistryInfo element.terminateReasonReference information about the terminateReason element.timestampReference information about the timestamp element.typeReference information about the type element.userInfoReference information about the userInfo element.userInfo.appUserNameReference information about the userInfo.appUserName element.userInfo.attributesReference information about the userInfo.attributes element.userInfo.callerListReference information about the userInfo.callerList element.userInfo.domainReference information about the userInfo.domain element.userInfo.locationReference information about the userInfo.location element.userInfo.locationTypeReference information about the userInfo.locationType element.userInfo.realmReference information about the userInfo.realm element.userInfo.registryUserNameReference information about the userInfo.registryUserName element.userInfo.sessionIdReference information about the userInfo.sessionId element.userInfo.uniqueIdReference information about the userInfo.uniqueId element.userInputsReference information about the userInputs element.violationClassificationReference information about the violationClassification element.violationDescriptionReference information about the violationDescription element.violationNameReference information about the violationName element.workItemInfoReference information about the workItemInfo element.workItemInfoType.id elementReference information about the workItemInfoType.id element.workItemInfoType.type elementReference information about the workItemInfoType.type element.

Reference information about elements and element types

This section defines the various elements and element types that are available for the common audit event types.

For each element and element type that can be used in an audit event, this documentation provides a description, the values that can be displayed in the output, and the XPath statement that can be used when modifying the shredder configuration file.

For information on the elements and element types described in this section, refer to the Common Base Event specification at the following Web site: http://www.eclipse.org/tptp/platform/documents/index.php

accessDecision element
Reference information about the accessDecision element.

accessDecisionReason element
Reference information about the accessDecisionReason element.

action element
Reference information about the action element.

appName element
Reference information about the appName element.

attributePermissionInfo element
Reference information about the attributePermissionInfo element.

attributePermissionInfo.attributeNames element
Reference information about the attributePermissionInfo.attributeNames element.

attributePermissionInfo.checked element
Reference information about the attributePermissionInfo.checked element.

attributePermissionInfo element
Reference information about the attributePermissionInfo.denied element.

attributePermissionInfo.granted element
Reference information about the attributePermissionInfo.granted element.

attributes element
Reference information about the attributes element.

attributes.name element
Reference information about the attributes.name element.

attributes.source
Reference information about the attributes.source element.

attributes.value
Reference information about the attributes.value element.

auditMsg
Reference information about the auditMsg element.

auditMsgElement
Reference information about the auditMsgElement element.

auditTrailId
Reference information about the auditTrailId element.

authenProvider
Reference information about the authenProvider element.

authnType
Reference information about the authnType element.

authnTypeVersion
Reference information about the authnTypeVersion element.

complianceStatus
Reference information about the complianceStatus element.

endTime
Reference information about the endTime element.

extensionName
Reference information about the extensionName element.

fixDescription
Reference information about the fixDescription element.

fixId
Reference information about the fixId element.

globalInstanceId
Reference information about the globalInstanceId element.

httpURLInfo element
Reference information about the httpURLInfo element.

HTTPURLInfo.method
Reference information about the HTTPURLInfo.method element.

HTTPURLInfo.requestHeaders
Reference information about the HTTPURLInfo.requestHeaders element.

HTTPURLInfo.responseCode
Reference information about the HTTPURLInfo.responseCode element.

HTTPURLInfo.responseHeaders
Reference information about the HTTPURLInfo.responseHeaders element.

HTTPURLInfo.url element
Reference information about the HTTPURLInfo.url element.

keyLabel
Reference information about the keyLabel element.

lifetime
Reference information about the lifetime element.

location
Reference information about the location element.

locationType
Reference information about the locationType element.

loginTime
Reference information about the loginTime element.

mappedRealm
Reference information about the mappedRealm element.

mappedSecurityDomain
Reference information about the mappedSecurityDomain element.

mappedUserName
Reference information about the mappedUserName element.

membershipInfo
Reference information about the membershipInfo element.

memberships.id element
Reference information about the memberships.id element.

memberships.name element
Reference information about the memberships.name element.

memberships.type element
Reference information about the memberships.type element.

message
Reference information about the message element.

mgmtInfo
Reference information about the mgmtInfo element.

mgmtInfo.command
Reference information about the mgmtInfo.command element.

mgmtInfo.targetInfo
Reference information about the mgmtInfo.targetInfo element.

originalRealm
Reference information about the originalRealm element.

originalSecurityRealm
Reference information about the originalSecurityRealm element.

originalUserName
Reference information about the originalUserName element.

outcome
Reference information about the outcome element.

outcome.failureReason
Reference information about the outcome.failureReason element.

outcome.majorStatus
Reference information about the outcome.majorStatus element.

outcome.minorStatus
Reference information about the outcome.minorStatus element.

outcome.result
Reference information about the outcome.result element.

partner
Reference information about the partner element.

perfInfo
Reference information about the perfInfo element.

perfInfo.aggregate
Reference information about the perfInfo.aggregate element.

perfInfo.description
Reference information about the perfInfo.description element.

perfInfo.name element
Reference information about the perfInfo.name element.

perfInfo.maxValue
Reference information about the perfInfo.maxValue element.

perfInfo.minValue
Reference information about the perfInfo.minValue element.

perfInfo.numDataPoints
Reference information about the perfInfo.numDataPoints element.

perfInfo.unit element
Reference information about the perfInfo.unit element.

perfInfo.value
Reference information about the perfInfo.value element.

permissionInfo
Reference information about the permissionInfo element.

permissionInfo.checked
Reference information about the permissionInfo.checked element.

permissionInfo.denied
Reference information about the permissionInfo.denied element.

permissionInfo.granted
Reference information about the permissionInfo.granted element.

permissionInfo.J2EERolesChecked
Reference information about the permissionInfo.J2EERolesChecked element.

permissionInfo.J2EERolesGranted
Reference information about the permissionInfo.J2EERolesGranted element.

policyDescription
Reference information about the policyDescription element.

policyInfo
Reference information about the policyInfo element.

policyInfo.attributes
Reference information about the policyInfo.attributes element.

policyInfo.branch
Reference information about the policyInfo.branch element.

policyInfo.description
Reference information about the policyInfo.description element.

policyInfo.name element
Reference information about the policyInfo.name element.

policyInfo.type element
Reference information about the policyInfo.type element.

policyName
Reference information about the policyName element.

progName
Reference information about the progName element.

provisioningInfo
Reference information about the provisioningInfo element.

provisioningInfo.accountId
Reference information about the provisioningInfo.accountId element.

provisioningInfo.resourceId
Reference information about the provisioningInfo.resourceId element.

provisioningInfo.resourceType
Reference information about the provisioningInfo.resourceType element.

provisioningTargetInfo
Reference information about the provisioningTargetInfo element.

recommendation
Reference information about the recommendation element.

registryInfo
Reference information about the registryInfo element.

registryInfo.serverLocation
Reference information about the registryInfo.serverLocation element.

registryInfo.serverLocationType
Reference information about the registryInfo.serverLocationType element.

registryInfo.serverPort
Reference information about the registryInfo.serverPort element.

registryInfo.type element
Reference information about the registryInfo.type element.

registryObjectInfo
Reference information about the registryObjectInfo element.

registryObjectInfo.attributes
Reference information about the registryObjectInfo.attributes element.

registryObjectInfo.description
Reference information about the registryObjectInfo.description element.

registryObjectInfo.name element
Reference information about the registryObjectInfo.name element.

registryObjectInfo.registryName
Reference information about the registryObjectInfo.registryName element.

registryObjectInfo.type element
Reference information about the registryObjectInfo.type element.

reporterComponentId
Reference information about the reporterComponentId element.

resourceInfo
Reference information about the resourceInfo element.

resourceInfo.attributes
Reference information about the resourceInfo.attributes element.

resourceInfo.nameInApp
Reference information about the resourceInfo.nameInApp element.

resourceInfo.nameInPolicy
Reference information about the resourceInfo.nameInPolicy element.

resourceInfo.type element
Reference information about the resourceInfo.type element.

sequenceNumber
Reference information about the sequenceNumber element.

severity
Reference information about the severity element.

sourceComponentId
Reference information about the sourceComponentId element.

sourceComponentId/@application
Reference information about the sourceComponentId/@application element.

sourceComponentId/@component
Reference information about the sourceComponentId/@component element.

sourceComponentId/@componentIdType
Reference information about the sourceComponentId/@componentIdType element.

sourceComponentId/@componentType
Reference information about the sourceComponentId/@componentType element.

sourceComponentId/@executionEnvironment
Reference information about the sourceComponentId/@executionEnvironment element.

sourceComponentId/@instanceId
Reference information about the sourceComponentId/@instanceId element.

sourceComponentId/@location
Reference information about the sourceComponentId/@location element.

sourceComponentId/@locationType
Reference information about the sourceComponentId/@locationType element.

sourceComponentId/@processId
Reference information about the sourceComponentId/@processId element.

sourceComponentId/@subComponent
Reference information about the sourceComponentId/@subComponent element.

sourceComponentId/@threadId
Reference information about the sourceComponentId/@threadId element.

startTime
Reference information about the startTime element.

suppressed
Reference information about the suppressed element.

targetAccount
Reference information about the targetAccount element.

targetInfoType
Reference information about the targetInfoType element.

targetInfo.attributes
Reference information about the targetInfo.attributes element.

targetInfo.targetNames
Reference information about the targetInfo.targetNames element.

targetResource
Reference information about the targetResource element.

targetUser
Reference information about the targetUser element.

targetUserInfo (1)
Reference information about the targetUserInfo element when used with the AUDIT_WORKFLOW event type.

targetUserInfo (2)
Reference information about the targetUserInfo element when used with the AUDIT_MGMT_PROVISIONING event type.

targetUserRegistryInfo
Reference information about the targetUserRegistryInfo element.

terminateReason
Reference information about the terminateReason element.

timestamp
Reference information about the timestamp element.

type
Reference information about the type element.

userInfo
Reference information about the userInfo element.

userInfo.appUserName
Reference information about the userInfo.appUserName element.

userInfo.attributes
Reference information about the userInfo.attributes element.

userInfo.callerList
Reference information about the userInfo.callerList element.

userInfo.domain
Reference information about the userInfo.domain element.

userInfo.location
Reference information about the userInfo.location element.

userInfo.locationType
Reference information about the userInfo.locationType element.

userInfo.realm
Reference information about the userInfo.realm element.

userInfo.registryUserName
Reference information about the userInfo.registryUserName element.

userInfo.sessionId
Reference information about the userInfo.sessionId element.

userInfo.uniqueId
Reference information about the userInfo.uniqueId element.

userInputs
Reference information about the userInputs element.

violationClassification
Reference information about the violationClassification element.

violationDescription
Reference information about the violationDescription element.

violationName
Reference information about the violationName element.

workItemInfo
Reference information about the workItemInfo element.

workItemInfoType.id element
Reference information about the workItemInfoType.id element.

workItemInfoType.type element
Reference information about the workItemInfoType.type element.

Parent topic: Audit events

accessDecision elementaccessDecision elementReference information about the accessDecision element.DescriptionDecision of the authorization call.ValuesStringThe following strings are suggested values:deniedAccess was denied.permittedAccess was permitted.permittedWarningAccess was permitted in warning mode.unknownCannot determine whether access is denied or not. Might be due to a non-access error (configuration problem or internal problem) or because more access decision information is needed.XPathCommonBaseEvent/extendedDataElements[@name='accessDecision']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

accessDecision element

Reference information about the accessDecision element.

Description

Decision of the authorization call.

Values

String

The following strings are suggested values:

denied

Access was denied.

permitted

Access was permitted.

permittedWarning

Access was permitted in warning mode.

unknown

Cannot determine whether access is denied or not. Might be due to a non-access error (configuration problem or internal problem) or because more access decision information is needed.

XPath

CommonBaseEvent/extendedDataElements[@name='accessDecision']/values

Parent topic: Reference information about elements and element types

accessDecisionReason elementaccessDecisionReason elementReference information about the accessDecisionReason element.DescriptionAdditional information about the access decision.For example, when accessDecision='denied', provides the reason for the denial.ValuesStringThe following strings are suggested values:authnLevelUnauthorizedThe user is not authenticated at a sufficiently high level to access the resource.authzRuleUnauthorizedThe authorization rule policy denied access.delegateUnauthorized Delegate principal is unauthorized to perform delegation.qopUnauthorizedThe communication channel that is used to access the resource has an insufficient level of quality of protection.reauthnUnauthorizedAccess is denied until the user interactively reauthenticates.timeOfDayUnauthorizedAccess denied due to time of day policy.unauthorizedOperation is not authorized. Use this value only if you cannot provide a more specific reason.XPathCommonBaseEvent/extendedDataElements[@name='accessDecisionReason']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

accessDecisionReason element

Reference information about the accessDecisionReason element.

Description

Additional information about the access decision.

For example, when accessDecision='denied', provides the reason for the denial.

Values

String

The following strings are suggested values:

authnLevelUnauthorized

The user is not authenticated at a sufficiently high level to access the resource.

authzRuleUnauthorized

The authorization rule policy denied access.

delegateUnauthorized

Delegate principal is unauthorized to perform delegation.

qopUnauthorized

The communication channel that is used to access the resource has an insufficient level of quality of protection.

reauthnUnauthorized

Access is denied until the user interactively reauthenticates.

timeOfDayUnauthorized

Access denied due to time of day policy.

unauthorized

Operation is not authorized. Use this value only if you cannot provide a more specific reason.

XPath

CommonBaseEvent/extendedDataElements[@name='accessDecisionReason']/values

Parent topic: Reference information about elements and element types

action elementaction elementReference information about the action element.DescriptionThe action that is performed.ValuesStringFor the AUDIT_AUTHN event type, the following strings are suggested values:authenticationAn authentication operation. Multiple authentications can occur as part of a single login.credsRefreshRefresh of a credential. For example, in the case of Kerberos.loginA login operation.reauthenticationReauthentication operation.stepUpStep-up authentication.tokenIssueUsed when the Trust Service issues a token on behalf of an identity.tokenReceiptUsed when an incoming security token is validated by the Trust Service.switchUserA switch user operation.For the AUDIT_AUTHN_CREDS_MODIFY event type, the following strings are suggested values:credsCombineCaller is adding a user to a credential chain.credsModifyCaller is creating a modified copy of existing user credentials.getCredsCaller is getting credentials based on user information.getCredsFromPACResolve credentials from transferable object (privilege attribute certificate [PAC]).getEntitlementsAdd to credentials by using an entitlements service.getPACConvert credentials to a transferable object (privilege attribute certificate [PAC]).For the AUDIT_AUTHN_TERMINATE event type, the following strings are suggested values:logoutA logout operation.switchUserTerminateUsed when the switch user session is ended.For the AUDIT_DATA_SYNC event type, the following strings are suggested values:reconcileReconcile accounts. For example, the Identity Manager server might send a request to the remote provisioning resource to synchronize account data into the Identity Manager repository.unsolicitedNotificationNotify of operations. For example, the remote provisioning resource might send a notification to the Identity Manager server to notify changes on the account data.For the AUDIT_MGMT_CONFIG, AUDIT_MGMT_POLICY, AUDIT_MGMT_REGISTRY, and AUDIT_MGMT_RESOURCE event types, the following strings are suggested values:associateAssociate entities. For example, the user who is associated with groups, group associated with users, and policy associated with objects.challengeResponseChange the challenge and response configurations.changePolicyEnforcementActionChange the policy enforcement action of the management object. The following list shows the allowable actions:CorrectSuspendMarkNon-CompliantcheckAccessAn authorization decision was made.createCreate a management object.delegateDelegate authorities the user has to another user for a specified amount of time.deleteDelete a management object. For example, delete a file from the Trusted Computing Base.disableDisable an account for login activity.disassociateDisassociate entities. For example, disassociate a user from groups, disassociate a group from users, and disassociate a policy from objects.enableEnable an account for login activity.markTrustedMark as trusted. For example, mark a file as trusted in the Trusted Computing Base.markUntrustedMark as untrusted. For example, mark a file as untrusted in the Trusted Computing Base.modifyModify a management object.passthruIndicates that request is passed to another server.passwordChangeIndicates a password change operation initiated by the administrator.passwordPickupPick up password for account.registerTo register. For example, register a daemon with the kernel.restoreTo restore. For example, to restore a suspended user or account.retireTo retire. For example, a federation is retired when it is no longer used. This information is archived for future reference.retrieveA credential was retrieved.showShow a management object.suspendTo suspend. For example, suspend a partner in a federation.transferTransfer a user between different organization containers.validateTo validate. For example, verify a security token that represents a user.For the AUDIT_MGMT_PROVISIONING event type, the following strings are suggested values:addProvision a new account on the target resource identified by provisioningTargetInfo.adoptAdopt an orphan account identified by provisioningTargetInfo.changePasswordChange password for an account identified by provisioningTargetInfo.deleteDelete an account identified by provisioningTargetInfo.modifyModify an existing account identified by provisioningTargetInfo.passwordPickupPick up password for an account identified by provisioningTargetInfo.restoreRestore a suspended account identified by provisioningTargetInfo.suspendSuspend an existing account identified by provisioningTargetInfo.For the AUDIT_RESOURCE_ACCESS event type, the following strings are suggested values:fileExecA program execution occurred.fileTraceA file access occurred.httpRequestA request was made to access a resource by using HTTP.For the AUDIT_RUNTIME event type, the following strings are suggested values:auditLevelChangeAn audit or warning level change request is sent to the server.auditStartAuditing started for a server component.auditStopAuditing stopped for a server component.contactRestoredRestored contact. For example, the server regained contact with the Security Access Manager user registry.heartbeatDownHeartbeat information that a server or API is down.heartbeatUpHeartbeat information that a server or API is up.lostContactLost contact. For example, the server currently has no contact with the Security Access Manager user registry.monitorA process was adopted in to the set of monitored processes.startA server successfully started.statisticStatistical information for a server for capacity planning purposes.stopA server successfully stopped.For the AUDIT_RUNTIME_KEY event type, the following strings are suggested values:keyRetireThe key is retired.keyCRLInvalidatedThe CRL in the key is not valid.keyCertExpiredThe certificate in the key expired.keySetInvalidThe key is set as not valid.keyCertExpirationCheckThe expiration of the certificate is checked.For the AUDIT_WORKFLOW event type, the following strings are suggested values:assignA work item is assigned and routed to a user.completeA work item is completed by the user.deferMore time is given for the completion of the work item.delegateA work item is being delegated to another user.escalateA work item is being escalated as a result of timeout.lockA work item is being locked by a user. After a work item is locked, no other potential work item owner can perform the operation on the work item.unlockA work item is unlocked by a user.XPathCommonBaseEvent/extendedDataElements[@name='action']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

action element

Reference information about the action element.

Description

The action that is performed.

Values

String

For the AUDIT_AUTHN event type, the following strings are suggested values:

authentication

An authentication operation. Multiple authentications can occur as part of a single login.

credsRefresh

Refresh of a credential. For example, in the case of Kerberos.

login

A login operation.

reauthentication

Reauthentication operation.

stepUp

Step-up authentication.

tokenIssue

Used when the Trust Service issues a token on behalf of an identity.

tokenReceipt

Used when an incoming security token is validated by the Trust Service.

switchUser

A switch user operation.

For the AUDIT_AUTHN_CREDS_MODIFY event type, the following strings are suggested values:

credsCombine

Caller is adding a user to a credential chain.

credsModify

Caller is creating a modified copy of existing user credentials.

getCreds

Caller is getting credentials based on user information.

getCredsFromPAC

Resolve credentials from transferable object (privilege attribute certificate [PAC]).

getEntitlements

Add to credentials by using an entitlements service.

getPAC

Convert credentials to a transferable object (privilege attribute certificate [PAC]).

For the AUDIT_AUTHN_TERMINATE event type, the following strings are suggested values:

logout

A logout operation.

switchUserTerminate

Used when the switch user session is ended.

For the AUDIT_DATA_SYNC event type, the following strings are suggested values:

reconcile

Reconcile accounts. For example, the Identity Manager server might send a request to the remote provisioning resource to synchronize account data into the Identity Manager repository.

unsolicitedNotification

Notify of operations. For example, the remote provisioning resource might send a notification to the Identity Manager server to notify changes on the account data.

For the AUDIT_MGMT_CONFIG, AUDIT_MGMT_POLICY, AUDIT_MGMT_REGISTRY, and AUDIT_MGMT_RESOURCE event types, the following strings are suggested values:

associate

Associate entities. For example, the user who is associated with groups, group associated with users, and policy associated with objects.

challengeResponse

Change the challenge and response configurations.

changePolicyEnforcementAction

Change the policy enforcement action of the management object. The following list shows the allowable actions:

Correct

Suspend

Mark

Non-Compliant

checkAccess

An authorization decision was made.

create

Create a management object.

delegate

Delegate authorities the user has to another user for a specified amount of time.

delete

Delete a management object. For example, delete a file from the Trusted Computing Base.

disable

Disable an account for login activity.

disassociate

Disassociate entities. For example, disassociate a user from groups, disassociate a group from users, and disassociate a policy from objects.

enable

Enable an account for login activity.

markTrusted

Mark as trusted. For example, mark a file as trusted in the Trusted Computing Base.

markUntrusted

Mark as untrusted. For example, mark a file as untrusted in the Trusted Computing Base.

modify

Modify a management object.

passthru

Indicates that request is passed to another server.

passwordChange

Indicates a password change operation initiated by the administrator.

passwordPickup

Pick up password for account.

register

To register. For example, register a daemon with the kernel.

restore

To restore. For example, to restore a suspended user or account.

retire

To retire. For example, a federation is retired when it is no longer used. This information is archived for future reference.

retrieve

A credential was retrieved.

show

Show a management object.

suspend

To suspend. For example, suspend a partner in a federation.

transfer

Transfer a user between different organization containers.

validate

To validate. For example, verify a security token that represents a user.

For the AUDIT_MGMT_PROVISIONING event type, the following strings are suggested values:

add

Provision a new account on the target resource identified by provisioningTargetInfo.

adopt

Adopt an orphan account identified by provisioningTargetInfo.

changePassword

Change password for an account identified by provisioningTargetInfo.

delete

Delete an account identified by provisioningTargetInfo.

modify

Modify an existing account identified by provisioningTargetInfo.

passwordPickup

Pick up password for an account identified by provisioningTargetInfo.

restore

Restore a suspended account identified by provisioningTargetInfo.

suspend

Suspend an existing account identified by provisioningTargetInfo.

For the AUDIT_RESOURCE_ACCESS event type, the following strings are suggested values:

fileExec

A program execution occurred.

fileTrace

A file access occurred.

httpRequest

A request was made to access a resource by using HTTP.

For the AUDIT_RUNTIME event type, the following strings are suggested values:

auditLevelChange

An audit or warning level change request is sent to the server.

auditStart

Auditing started for a server component.

auditStop

Auditing stopped for a server component.

contactRestored

Restored contact. For example, the server regained contact with the Security Access Manager user registry.

heartbeatDown

Heartbeat information that a server or API is down.

heartbeatUp

Heartbeat information that a server or API is up.

lostContact

Lost contact. For example, the server currently has no contact with the Security Access Manager user registry.

monitor

A process was adopted in to the set of monitored processes.

start

A server successfully started.

statistic

Statistical information for a server for capacity planning purposes.

stop

A server successfully stopped.

For the AUDIT_RUNTIME_KEY event type, the following strings are suggested values:

keyRetire

The key is retired.

keyCRLInvalidated

The CRL in the key is not valid.

keyCertExpired

The certificate in the key expired.

keySetInvalid

The key is set as not valid.

keyCertExpirationCheck

The expiration of the certificate is checked.

For the AUDIT_WORKFLOW event type, the following strings are suggested values:

assign

A work item is assigned and routed to a user.

complete

A work item is completed by the user.

defer

More time is given for the completion of the work item.

delegate

A work item is being delegated to another user.

escalate

A work item is being escalated as a result of timeout.

lock

A work item is being locked by a user. After a work item is locked, no other potential work item owner can perform the operation on the work item.

unlock

A work item is unlocked by a user.

XPath

CommonBaseEvent/extendedDataElements[@name='action']/values

Parent topic: Reference information about elements and element types

appName elementappName elementReference information about the appName element.DescriptionName of the application that is accessing the resource.ValuesStringFor example, an Emacs program can be accessing a file resource.XPathCommonBaseEvent/extendedDataElements[@name='appName']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

appName element

Reference information about the appName element.

Description

Name of the application that is accessing the resource.

Values

String

For example, an Emacs program can be accessing a file resource.

XPath

CommonBaseEvent/extendedDataElements[@name='appName']/values

Parent topic: Reference information about elements and element types

attributePermissionInfo elementattributePermissionInfo elementReference information about the attributePermissionInfo element.DescriptionA container for the information about access permissions on the attributes of the target.This container uses the children of attributePermissionInfoType:attributePermissionInfoType.attributeNamesattributePermissionInfoType.checkedattributePermissionInfoType.deniedattributePermissionInfoType.grantedXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributePermissionInfo element

Reference information about the attributePermissionInfo element.

Description

A container for the information about access permissions on the attributes of the target.

This container uses the children of attributePermissionInfoType:

attributePermissionInfoType.attributeNames

attributePermissionInfoType.checked

attributePermissionInfoType.denied

attributePermissionInfoType.granted

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

attributePermissionInfo.attributeNames elementattributePermissionInfo.attributeNames elementReference information about the attributePermissionInfo.attributeNames element.DescriptionList of attributes in which permissions are being checked.ValuesString[]XPathThe XPath accesses the first attributeNames element from an array of attributeNames elements.CommonBaseEvent/extendedDataElements [@name='attributePermissionInfo']/children[1]/children [@name='attributeNames']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributePermissionInfo.attributeNames element

Reference information about the attributePermissionInfo.attributeNames element.

Description

List of attributes in which permissions are being checked.

Values

String[]

XPath

The XPath accesses the first attributeNames element from an array of attributeNames elements.

CommonBaseEvent/extendedDataElements
[@name='attributePermissionInfo']/children[1]/children
[@name='attributeNames']/values[1]

Parent topic: Reference information about elements and element types

attributePermissionInfo.checked elementattributePermissionInfo.checked elementReference information about the attributePermissionInfo.checked element.DescriptionPermission that are being checked during the authorization call.ValuesString[]XPathThe XPath accesses the first checked element from an array of checked elements.CommonBaseEvent/extendedDataElements [@name='attributePermissionInfo']/children[1]/children [@name='checked']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributePermissionInfo.checked element

Reference information about the attributePermissionInfo.checked element.

Description

Permission that are being checked during the authorization call.

Values

String[]

XPath

The XPath accesses the first checked element from an array of checked elements.

CommonBaseEvent/extendedDataElements
[@name='attributePermissionInfo']/children[1]/children
[@name='checked']/values[1]

Parent topic: Reference information about elements and element types

attributePermissionInfo elementattributePermissionInfo.denied elementReference information about the attributePermissionInfo.denied element.DescriptionPermission that are denied.ValuesString[]XPathThe XPath accesses the first denied element from an array of denied elements.CommonBaseEvent/extendedDataElements [@name='attributePermissionInfo']/children[1]/children [@name='denied']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributePermissionInfo element

Reference information about the attributePermissionInfo.denied element.

Description

Permission that are denied.

Values

String[]

XPath

The XPath accesses the first denied element from an array of denied elements.

CommonBaseEvent/extendedDataElements
[@name='attributePermissionInfo']/children[1]/children
[@name='denied']/values[1]

Parent topic: Reference information about elements and element types

attributePermissionInfo.granted elementattributePermissionInfo.granted elementReference information about the attributePermissionInfo.granted element.DescriptionPermission that are granted.ValuesString[]XPathThe XPath accesses the first granted element from an array of granted elements.CommonBaseEvent/extendedDataElements [@name='attributePermissionInfo']/children[1]/children [@name='granted']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributePermissionInfo.granted element

Reference information about the attributePermissionInfo.granted element.

Description

Permission that are granted.

Values

String[]

XPath

The XPath accesses the first granted element from an array of granted elements.

CommonBaseEvent/extendedDataElements
[@name='attributePermissionInfo']/children[1]/children
[@name='granted']/values[1]

Parent topic: Reference information about elements and element types

attributes elementattributes elementReference information about the attributes element.DescriptionA container for the array of application-specific attributes for this event.This element type represents an attribute that is associated with an entity, such as a user, application, or authorization rule.This element uses the children of the attributeType element:attributes.nameattributes.sourceattributes.valueXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributes element

Reference information about the attributes element.

Description

A container for the array of application-specific attributes for this event.

This element type represents an attribute that is associated with an entity, such as a user, application, or authorization rule.

This element uses the children of the attributeType element:

attributes.name

attributes.source

attributes.value

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

attributes.name elementattributes.name elementReference information about the attributes.name element.DescriptionName of the attribute.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='attributes']/children[1]/children [@name='name']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributes.name element

Reference information about the attributes.name element.

Description

Name of the attribute.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='attributes']/children[1]/children
[@name='name']/values[1]

Parent topic: Reference information about elements and element types

attributes.sourceattributes.source elementReference information about the attributes.source element.DescriptionSource of the attribute.ValuesStringThe following strings are suggested values:applicationProvided by the application.authzRuleADIProvided as an input for authorization rules.userProvided by the user.XPathCommonBaseEvent/extendedDataElements[@name='attributes']/children[1]/children [@name='source']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributes.source

Reference information about the attributes.source element.

Description

Source of the attribute.

Values

String

The following strings are suggested values:

application

Provided by the application.

authzRuleADI

Provided as an input for authorization rules.

user

Provided by the user.

XPath

CommonBaseEvent/extendedDataElements[@name='attributes']/children[1]/children
[@name='source']/values[1]

Parent topic: Reference information about elements and element types

attributes.valueattributes.value elementReference information about the attributes.value element.DescriptionValue of the attribute.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='attributes']/children[1]/children [@name='value']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

attributes.value

Reference information about the attributes.value element.

Description

Value of the attribute.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='attributes']/children[1]/children
[@name='value']/values[1]

Parent topic: Reference information about elements and element types

auditMsgauditMsg elementReference information about the auditMsg element.DescriptionMessage for this audit event.Valuesxsd:stringAny arbitrary stringRefer to the msg field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='auditMsg']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

auditMsg

Reference information about the auditMsg element.

Description

Message for this audit event.

Values

xsd:string

Any arbitrary string

Refer to the msg field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='auditMsg']/values

Parent topic: Reference information about elements and element types

auditMsgElementauditMsgElement elementReference information about the auditMsgElement element.DescriptionInformation associated with message.This container uses the field of msgDataElement and its children. For additional details, refer to the Common Base Event specification.Valuescbe:msgDataElementXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

auditMsgElement

Reference information about the auditMsgElement element.

Description

Information associated with message.

This container uses the field of msgDataElement and its children. For additional details, refer to the Common Base Event specification.

Values

cbe:msgDataElement

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

auditTrailIdauditTrailId elementReference information about the auditTrailId element.DescriptionID that allows audit events that belong to a given transaction to be correlated. For example, this could be populated using the propagationToken in WebSphere Application Server.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='auditTrailId']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

auditTrailId

Reference information about the auditTrailId element.

Description

ID that allows audit events that belong to a given transaction to be correlated.

For example, this could be populated using the propagationToken in WebSphere® Application Server.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='auditTrailId']/values

Parent topic: Reference information about elements and element types

authenProviderauthenProvider elementReference information about the authenProvider element.DescriptionProvider of the authentication service.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='authenProvider']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

authenProvider

Reference information about the authenProvider element.

Description

Provider of the authentication service.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='authenProvider']/values

Parent topic: Reference information about elements and element types

authnTypeauthnType elementReference information about the authnType element.DescriptionProvider of the authentication service.ValuesAny arbitrary stringThe following strings are suggested values:basicAuthBrowser authentication based on user ID and password.challengeResponseChallenge and response authentication.digestDigest-based authentication.formForm-based authentication.identityAssertionAuthentication based on identity assertion.kerberosAuthentication based on Kerberos credentials.ldap_v3.0Authentication using the LDAP protocol.ltpaLightweight third-party authentication.sslAuthnSSL-based authentication.tokenAccessManagerCredAuthentication based on Security Access Manager credentials.tokenLibertyAuthentication based on a Liberty token.tokenSAMLAuthentication based on a SAML token.tokenUserNameAuthentication based on user name based token.trustAssociationAuthentication based on trust association.XPathCommonBaseEvent/extendedDataElements[@name='authnType']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

authnType

Reference information about the authnType element.

Description

Provider of the authentication service.

Values

Any arbitrary string

The following strings are suggested values:

basicAuth

Browser authentication based on user ID and password.

challengeResponse

Challenge and response authentication.

digest

Digest-based authentication.

form

Form-based authentication.

identityAssertion

Authentication based on identity assertion.

kerberos

Authentication based on Kerberos credentials.

ldap_v3.0

Authentication using the LDAP protocol.

ltpa

Lightweight third-party authentication.

sslAuthn

SSL-based authentication.

tokenAccessManagerCred

Authentication based on Security Access Manager credentials.

tokenLiberty

Authentication based on a Liberty token.

tokenSAML

Authentication based on a SAML token.

tokenUserName

Authentication based on user name based token.

trustAssociation

Authentication based on trust association.

XPath

CommonBaseEvent/extendedDataElements[@name='authnType']/values

Parent topic: Reference information about elements and element types

authnTypeVersionauthnTypeVersion elementReference information about the authnTypeVersion element.DescriptionVersion of the authentication type.ValuesString form of the version numberXPathCommonBaseEvent/extendedDataElements[@name='authnTypeVersion']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

authnTypeVersion

Reference information about the authnTypeVersion element.

Description

Version of the authentication type.

Values

String form of the version number

XPath

CommonBaseEvent/extendedDataElements[@name='authnTypeVersion']/values

Parent topic: Reference information about elements and element types

complianceStatuscomplianceStatus elementReference information about the complianceStatus element.DescriptionStatus of compliance.ValuesStringThe following strings are suggested values:compliantThe reconciled account on the provisioning resource complies with the specified security policy.disallowedThe reconciled account is not allowed by a provisioning policy.nonCompliantThe reconciled account on the provisioning resource does not comply with the specified security policy.orphanNo owner can be found for the reconciled account.XPathCommonBaseEvent/extendedDataElements[@name='complianceStatus']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

complianceStatus

Reference information about the complianceStatus element.

Description

Status of compliance.

Values

String

The following strings are suggested values:

compliant

The reconciled account on the provisioning resource complies with the specified security policy.

disallowed

The reconciled account is not allowed by a provisioning policy.

nonCompliant

The reconciled account on the provisioning resource does not comply with the specified security policy.

orphan

No owner can be found for the reconciled account.

XPath

CommonBaseEvent/extendedDataElements[@name='complianceStatus']/values

Parent topic: Reference information about elements and element types

endTimeendTime elementReference information about the endTime element.DescriptionEnd time of the operation.Valuesxsd:DateTimeRefer to the creationTime field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='endTime'][@type='dateTime']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

endTime

Reference information about the endTime element.

Description

End time of the operation.

Values

xsd:DateTime

Refer to the creationTime field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='endTime'][@type='dateTime']/values

Parent topic: Reference information about elements and element types

extensionNameextensionName elementReference information about the extensionName element.DescriptionThe event type.This information relates to the following line in the CARSShredder.conf file:cars_t_event, eventType, "'event_type'"ValuesStringThe actual name of the event type, which is one of the following literal values:AUDIT_AUTHN_CREDS_MODIFYAUDIT_AUTHN_MAPPINGAUDIT_AUTHN_TERMINATEAUDIT_AUTHNAUDIT_AUTHZAUDIT_COMPLIANCEAUDIT_DATA_SYNCAUDIT_MGMT_CONFIGAUDIT_MGMT_POLICYAUDIT_MGMT_PROVISIONINGAUDIT_MGMT_REGISTRYAUDIT_MGMT_RESOURCEAUDIT_PASSWORD_CHANGEAUDIT_RESOURCE_ACCESSAUDIT_RUNTIMEAUDIT_RUNTIME_KEYAUDIT_WORKFLOWXPathevent_typeFor example, to specify the AUDIT_AUTHN event type, specify:"'AUDIT_AUTHN'"Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

extensionName

Reference information about the extensionName element.

Description

The event type.

This information relates to the following line in the CARSShredder.conf file:

cars_t_event, eventType, "'event_type'"

Values

String

The actual name of the event type, which is one of the following literal values:

AUDIT_AUTHN_CREDS_MODIFY

AUDIT_AUTHN_MAPPING

AUDIT_AUTHN_TERMINATE

AUDIT_AUTHN

AUDIT_AUTHZ

AUDIT_COMPLIANCE

AUDIT_DATA_SYNC

AUDIT_MGMT_CONFIG

AUDIT_MGMT_POLICY

AUDIT_MGMT_PROVISIONING

AUDIT_MGMT_REGISTRY

AUDIT_MGMT_RESOURCE

AUDIT_PASSWORD_CHANGE

AUDIT_RESOURCE_ACCESS

AUDIT_RUNTIME

AUDIT_RUNTIME_KEY

AUDIT_WORKFLOW

XPath

event_type

For example, to specify the AUDIT_AUTHN event type, specify:

"'AUDIT_AUTHN'"

Parent topic: Reference information about elements and element types

fixDescriptionfixDescription elementReference information about the fixDescription element.DescriptionDescription of specific fix. For example, Apply patch xyz.ValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='fixDescription']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

fixDescription

Reference information about the fixDescription element.

Description

Description of specific fix. For example, "Apply patch xyz".

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='fixDescription']/values

Parent topic: Reference information about elements and element types

fixIdfixId elementReference information about the fixId element.DescriptionIdentifier of specific fix.ValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='fixId']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

fixId

Reference information about the fixId element.

Description

Identifier of specific fix.

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='fixId']/values

Parent topic: Reference information about elements and element types

globalInstanceIdglobalInstanceId elementReference information about the globalInstanceId element.DescriptionAn internal identifier for an audit event as shown in the XML output.This information is not related to the following line in the CARSShredder.conf file:cars_t_event, event_id, #GLOBAL_IDReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

globalInstanceId

Reference information about the globalInstanceId element.

Description

An internal identifier for an audit event as shown in the XML output.

This information is not related to the following line in the CARSShredder.conf file:

cars_t_event, event_id, #GLOBAL_ID

Parent topic: Reference information about elements and element types

httpURLInfo elementhttpURLInfo elementReference information about the httpURLInfo element.DescriptionThe container for information about the HTTP request.This container uses the children of HTTPURLInfoType:HTTPURLInfoType.methodHTTPURLInfoType.requestHeadersHTTPURLInfoType.responseCodeHTTPURLInfoType.responseHeadersHTTPURLInfoType.urlXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

httpURLInfo element

Reference information about the httpURLInfo element.

Description

The container for information about the HTTP request.

This container uses the children of HTTPURLInfoType:

HTTPURLInfoType.method

HTTPURLInfoType.requestHeaders

HTTPURLInfoType.responseCode

HTTPURLInfoType.responseHeaders

HTTPURLInfoType.url

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

HTTPURLInfo.methodHTTPURLInfo.method elementReference information about the HTTPURLInfo.method element.DescriptionMethod used.ValuesStringMethods allowed by the HTTP protocol (for example, POST or GET). The following strings are suggested values:GETPassed in information using the HTTP GET method.POSTPassed in information using the HTTP POST method.XPathCommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children [@name='method']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

HTTPURLInfo.method

Reference information about the HTTPURLInfo.method element.

Description

Method used.

Values

String

Methods allowed by the HTTP protocol (for example, POST or GET). The following strings are suggested values:

GET

Passed in information using the HTTP GET method.

POST

Passed in information using the HTTP POST method.

XPath

CommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children
[@name='method']/values

Parent topic: Reference information about elements and element types

HTTPURLInfo.requestHeadersHTTPURLInfo.requestHeaders elementReference information about the HTTPURLInfo.requestHeaders element.DescriptionHTTP request headers given by the client.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children [@name='requestHeaders']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

HTTPURLInfo.requestHeaders

Reference information about the HTTPURLInfo.requestHeaders element.

Description

HTTP request headers given by the client.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children
[@name='requestHeaders']/values

Parent topic: Reference information about elements and element types

HTTPURLInfo.responseCodeHTTPURLInfo.responseCode elementReference information about the HTTPURLInfo.responseCode element.DescriptionResponse code returned by the server.ValuesIntegerXPathCommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children [@name='responseCode']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

HTTPURLInfo.responseCode

Reference information about the HTTPURLInfo.responseCode element.

Description

Response code returned by the server.

Values

Integer

XPath

CommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children
[@name='responseCode']/values

Parent topic: Reference information about elements and element types

HTTPURLInfo.responseHeadersHTTPURLInfo.responseHeaders elementReference information about the HTTPURLInfo.responseHeaders element.DescriptionHTTP response headers returned by the server.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children [@name='responseHeaders']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

HTTPURLInfo.responseHeaders

Reference information about the HTTPURLInfo.responseHeaders element.

Description

HTTP response headers returned by the server.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children
[@name='responseHeaders']/values

Parent topic: Reference information about elements and element types

HTTPURLInfo.url elementHTTPURLInfo.url elementReference information about the HTTPURLInfo.url element.DescriptionURL of the HTTP request.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children [@name='url']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

HTTPURLInfo.url element

Reference information about the HTTPURLInfo.url element.

Description

URL of the HTTP request.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='HTTPURLInfo']/children
[@name='url']/values

Parent topic: Reference information about elements and element types

keyLabelkeyLabel elementReference information about the keyLabel element.DescriptionIndicates the key or certificate label.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='keyLabel']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

keyLabel

Reference information about the keyLabel element.

Description

Indicates the key or certificate label.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='keyLabel']/values

Parent topic: Reference information about elements and element types

lifetimelifetime elementReference information about the lifetime element.DescriptionIndicates when a certificate will expire.Valuesxsd:DateTimeRefer to the creationTime field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='lifetime']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

lifetime

Reference information about the lifetime element.

Description

Indicates when a certificate will expire.

Values

xsd:DateTime

Refer to the creationTime field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='lifetime']/values

Parent topic: Reference information about elements and element types

locationlocation elementReference information about the location element.DescriptionPhysical location of the key database.Valuesxsd:stringRefer to the location field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='location']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

location

Reference information about the location element.

Description

Physical location of the key database.

Values

xsd:string

Refer to the location field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='location']/values

Parent topic: Reference information about elements and element types

locationTypelocationType elementReference information about the locationType element.DescriptionType of location.Valuesxsd:NameRefer to the locationType field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='locationType']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

locationType

Reference information about the locationType element.

Description

Type of location.

Values

xsd:Name

Refer to the locationType field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='locationType']/values

Parent topic: Reference information about elements and element types

loginTimeloginTime elementReference information about the loginTime element.DescriptionThe time that the login occurred.Valuesxsd:DateTimeRefer to the creationTime field in the Common Base Event specification.XPathCommonBaseEvent/@creationTimeReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

loginTime

Reference information about the loginTime element.

Description

The time that the login occurred.

Values

xsd:DateTime

Refer to the creationTime field in the Common Base Event specification.

XPath

CommonBaseEvent/@creationTime

Parent topic: Reference information about elements and element types

mappedRealmmappedRealm elementReference information about the mappedRealm element.DescriptionIndicate the realm after mapping.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='mappedRealm']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

mappedRealm

Reference information about the mappedRealm element.

Description

Indicate the realm after mapping.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='mappedRealm']/values

Parent topic: Reference information about elements and element types

mappedSecurityDomainmappedSecurityDomain elementReference information about the mappedSecurityDomain element.DescriptionIndicate the security domain after mapping.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='mappedSecurityDomain']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

mappedSecurityDomain

Reference information about the mappedSecurityDomain element.

Description

Indicate the security domain after mapping.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='mappedSecurityDomain']/values

Parent topic: Reference information about elements and element types

mappedUserNamemappedUserName elementReference information about the mappedUserName element.DescriptionIndicate the user name after mapping.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='mappedUserName']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

mappedUserName

Reference information about the mappedUserName element.

Description

Indicate the user name after mapping.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='mappedUserName']/values

Parent topic: Reference information about elements and element types

membershipInfomembershipInfo elementReference information about the membershipInfo element.DescriptionThe container for list of memberships to which the policy applies.The element uses the children of the membershipInfo element:membershipInfoType.idmembershipInfoType.namemembershipInfoType.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

membershipInfo

Reference information about the membershipInfo element.

Description

The container for list of memberships to which the policy applies.

The element uses the children of the membershipInfo element:

membershipInfoType.id

membershipInfoType.name

membershipInfoType.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

memberships.id elementmemberships.id elementReference information about the memberships.id element.DescriptionUnique identifier of the member.ValuesStringFor example, distinguished name of a role.XPathThe XPath statement assumes the first membership element from an array of membership elements.CommonBaseEvent/extendedDataElements [@name='memberships']/children[1]/children [@name='id']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

memberships.id element

Reference information about the memberships.id element.

Description

Unique identifier of the member.

Values

String

For example, distinguished name of a role.

XPath

The XPath statement assumes the first membership element from an array of membership elements.

CommonBaseEvent/extendedDataElements
[@name='memberships']/children[1]/children
[@name='id']/values

Parent topic: Reference information about elements and element types

memberships.name elementmemberships.name elementReference information about the memberships.name element.DescriptionName of the member.ValuesStringXPathThe XPath statement assumes the first membership element from an array of membership elements.CommonBaseEvent/extendedDataElements [@name='memberships']/children[1]/children [@name='name']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

memberships.name element

Reference information about the memberships.name element.

Description

Name of the member.

Values

String

XPath

The XPath statement assumes the first membership element from an array of membership elements.

CommonBaseEvent/extendedDataElements
[@name='memberships']/children[1]/children
[@name='name']/values

Parent topic: Reference information about elements and element types

memberships.type elementmemberships.type elementReference information about the memberships.type element.DescriptionMembership type.ValuesStringThe following strings are suggested values:allApplies to all users.orgContainerApplies to users that belong in a given organization container.otherIs not one of the other types.roleApplies to users that belong in a given role.XPathThe XPath statement assumes the first membership element from an array of membership elements.CommonBaseEvent/extendedDataElements [@name='memberships']/children[1]/children [@name='type']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

memberships.type element

Reference information about the memberships.type element.

Description

Membership type.

Values

String

The following strings are suggested values:

all

Applies to all users.

orgContainer

Applies to users that belong in a given organization container.

other

Is not one of the other types.

role

Applies to users that belong in a given role.

XPath

The XPath statement assumes the first membership element from an array of membership elements.

CommonBaseEvent/extendedDataElements
[@name='memberships']/children[1]/children
[@name='type']/values

Parent topic: Reference information about elements and element types

messagemessage elementReference information about the message element.DescriptionGenerated message that describes specifics about the violation. Can include dynamically inserted information. Example:Invalid ACL for c:\winnt\repair: Account: BUILTIN\usersValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='message']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

message

Reference information about the message element.

Description

Generated message that describes specifics about the violation. Can include dynamically inserted information. Example:

Invalid ACL for

c:\winnt\repair:

Account: BUILTIN\users

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='message']/values

Parent topic: Reference information about elements and element types

mgmtInfomgmtInfo elementReference information about the mgmtInfo element.DescriptionThe container for information about this management operation.This element type represents information that is common for events that are related to management operations, such as managing policies, resources, registry objects, and so forth.This element uses the children of mgmtInfoType:mgmtInfoType.commandmgmtInfoType.targetInfoXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

mgmtInfo

Reference information about the mgmtInfo element.

Description

The container for information about this management operation.

This element type represents information that is common for events that are related to management operations, such as managing policies, resources, registry objects, and so forth.

This element uses the children of mgmtInfoType:

mgmtInfoType.command

mgmtInfoType.targetInfo

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

mgmtInfo.commandmgmtInfo.command elementReference information about the mgmtInfo.command element.DescriptionThe application-specific command being performed. The command is particularly useful for modify actions to pinpoint what is being modified.ValuesStringAn application-specific string that represents the command. Examples:Key user modify:modifyPassword modifyAccountValid modifyPasswordValidKey Policy modify:modifyPolicyMaxLoginFailures modifyPolicyMaxAccountAge modifyPolicyMaxPasswordAge modifyPolicyTimeOfDayAccessACL modify:modifyACLSetAttribute modifyACLDelAttributePOP modify:modifyPOPSetAttribute modifyPOPDelAttributeprotectedObject modify:modifyObjectDelAttribute modifyObjectSetAttributeXPathCommonBaseEvent/extendedDataElements[@name='mgmtInfo']/children [@name='command']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

mgmtInfo.command

Reference information about the mgmtInfo.command element.

Description

The application-specific command being performed. The command is particularly useful for modify actions to pinpoint what is being modified.

Values

String

An application-specific string that represents the command. Examples:

Key user modify:

modifyPassword

modifyAccountValid

modifyPasswordValidKey

Policy modify:

modifyPolicyMaxLoginFailures

modifyPolicyMaxAccountAge

modifyPolicyMaxPasswordAge

modifyPolicyTimeOfDayAccess

ACL modify:

modifyACLSetAttribute

modifyACLDelAttribute

POP modify:

modifyPOPSetAttribute

modifyPOPDelAttribute

protectedObject modify:

modifyObjectDelAttribute

modifyObjectSetAttribute

XPath

CommonBaseEvent/extendedDataElements[@name='mgmtInfo']/children
[@name='command']/values

Parent topic: Reference information about elements and element types

mgmtInfo.targetInfomgmtInfo.targetInfo elementReference information about the mgmtInfo.targetInfo element.DescriptionInformation about the target resource of this operation.ValuestargetInfoTypeXPathRefer to targetInfoTypeReference information about the targetInfoType element. for details.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

mgmtInfo.targetInfo

Reference information about the mgmtInfo.targetInfo element.

Description

Information about the target resource of this operation.

Values

targetInfoType

XPath

Refer to targetInfoType for details.

Parent topic: Reference information about elements and element types

originalRealmoriginalRealm elementReference information about the originalRealm element.DescriptionIndicate the realm before mapping.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='originalRealm']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

originalRealm

Reference information about the originalRealm element.

Description

Indicate the realm before mapping.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='originalRealm']/values

Parent topic: Reference information about elements and element types

originalSecurityRealmoriginalSecurityRealm elementReference information about the originalSecurityRealm element.DescriptionIndicate the security domain before mapping.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='originalSecurityRealm']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

originalSecurityRealm

Reference information about the originalSecurityRealm element.

Description

Indicate the security domain before mapping.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='originalSecurityRealm']/values

Parent topic: Reference information about elements and element types

originalUserNameoriginalUserName elementReference information about the originalUserName element.DescriptionIndicate the user name before mapping.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='originalUserName']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

originalUserName

Reference information about the originalUserName element.

Description

Indicate the user name before mapping.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='originalUserName']/values

Parent topic: Reference information about elements and element types

outcomeoutcome elementReference information about the outcome element.DescriptionA container for the outcome of the action for which the audit record is generated.This element type identifies a component that is the source of the event or reports an event, and defines the outcome of the event being audited.This element uses the children of auditOutcomeType:outcome.failureReasonoutcome.majorStatusoutcome.minorStatusoutcome.resultXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

outcome

Reference information about the outcome element.

Description

A container for the outcome of the action for which the audit record is generated.

This element type identifies a component that is the source of the event or reports an event, and defines the outcome of the event being audited.

This element uses the children of auditOutcomeType:

outcome.failureReason

outcome.majorStatus

outcome.minorStatus

outcome.result

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

outcome.failureReasonoutcome.failureReason elementReference information about the outcome.failureReason element.DescriptionAdditional information about the outcome.ValuesAny arbitrary string.The outcome element contains the failureReason element. The values for the failureReason elements are event-specific. The following strings are some of the suggested values:accountDisabledUser's account has been disabled.accountDisabledRetryViolationRetry maximum has been violated for authentications that are not valid. The account has been disabled in the registry.accountExpiredUser account has expired.accountLockedOutMaxLoginFailUser account has been temporarily locked out due to too many failed login attempts. Lock time interval has not elapsed.accountLockedOutRetryViolationInvalid authentication retry maximum has been violated. The account has been temporarily locked out.accountMaxInactiveElapsedMaximum inactive days has elapsed for the account.accountUnlockedUser account was unlocked because lock time interval has elapsed.authenticationFailureAuthentication failed. Use this value when you do not have a more specific value for this audit element.certificateFailureA client certificate could not be authenticated.invalidUserNameThe supplied user name does not exist in the registry.invalidUserPasswordThe password associated with the given user name is incorrect.mappingFailureThe login data entered could not be mapped to an application-specific user.nextTokenNext token required for authentication.passwordChangeMaxIntervalElapsedMaximum time interval since last password change has elapsed.passwordChangeMinIntervalUnexpiredMinimum time interval required between password changes has not elapsed.passwordContainOldPassword contains the old password or is contained in the old password.passwordExpiredThe user's password has expired and no further grace logins remain.passwordFirstLastNumericPassword contains a numeric first or last character.passwordMaxCharOldPassword exceeds the allowed number of consecutive characters that are common with the previous password.passwordMaxRepeatedPassword exceeds the maximum allowed number of repeated characters.passwordMinAlphabeticPassword does not contain the required minimum number of alphabetic characters.passwordMinAlphabeticLowerPassword does not contain the required minimum number of lowercase characters.passwordMinAlphabeticUpperPassword does not contain the required minimum number of uppercase characters.passwordMinAlphanumericPassword does not contain the required minimum number of alphanumeric characterspasswordMinNumericPassword does not contain the required minimum number of numeric characters.passwordMinSpecialPassword does not contain the required minimum number of special characters.passwordNumCharViolationPassword does not contain the required number of characters.passwordOldReusedPassword is a recently used old password.passwordUserNamePassword contains the user name or is contained in the user name.pinRequiredA PIN must be assigned to enable account.policyAllowedAccessAll login policy checks permitted access.policyViolationLogin rejected due to policy violation.policyViolationMaxLoginsReachedLogin rejected because maximum number of concurrent logins reached.policyViolationTODAuthentication denied at this time of the day.tokenExpiredThe lifetime for the token has expired.tokenNotSupportedThe given token is not a supported type.tokenNotInValidFormatThe given token was not in the expected format or was corrupted.tokenNotValidYetThe token is not valid yet.tokenSignatureValidationFailedThe signature for the token was not valid.usernameMismatchIn the case of reauthentication or stepUp authentication, the given user name does not match the current user name.When a suggested value is not available, use the string Unknown Failure Reason.XPathCommonBaseEvent/extendedDataElements[@name='outcome']/children [@name='failureReason']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

outcome.failureReason

Reference information about the outcome.failureReason element.

Description

Additional information about the outcome.

Values

Any arbitrary string.

The outcome element contains the failureReason element. The values for the failureReason elements are event-specific. The following strings are some of the suggested values:

accountDisabled

User's account has been disabled.

accountDisabledRetryViolation

Retry maximum has been violated for authentications that are not valid. The account has been disabled in the registry.

accountExpired

User account has expired.

accountLockedOutMaxLoginFail

User account has been temporarily locked out due to too many failed login attempts. Lock time interval has not elapsed.

accountLockedOutRetryViolation

Invalid authentication retry maximum has been violated. The account has been temporarily locked out.

accountMaxInactiveElapsed

Maximum inactive days has elapsed for the account.

accountUnlocked

User account was unlocked because lock time interval has elapsed.

authenticationFailure

Authentication failed. Use this value when you do not have a more specific value for this audit element.

certificateFailure

A client certificate could not be authenticated.

invalidUserName

The supplied user name does not exist in the registry.

invalidUserPassword

The password associated with the given user name is incorrect.

mappingFailure

The login data entered could not be mapped to an application-specific user.

nextToken

Next token required for authentication.

passwordChangeMaxIntervalElapsed

Maximum time interval since last password change has elapsed.

passwordChangeMinIntervalUnexpired

Minimum time interval required between password changes has not elapsed.

passwordContainOld

Password contains the old password or is contained in the old password.

passwordExpired

The user's password has expired and no further grace logins remain.

passwordFirstLastNumeric

Password contains a numeric first or last character.

passwordMaxCharOld

Password exceeds the allowed number of consecutive characters that are common with the previous password.

passwordMaxRepeated

Password exceeds the maximum allowed number of repeated characters.

passwordMinAlphabetic

Password does not contain the required minimum number of alphabetic characters.

passwordMinAlphabeticLower

Password does not contain the required minimum number of lowercase characters.

passwordMinAlphabeticUpper

Password does not contain the required minimum number of uppercase characters.

passwordMinAlphanumeric

Password does not contain the required minimum number of alphanumeric characters

passwordMinNumeric

Password does not contain the required minimum number of numeric characters.

passwordMinSpecial

Password does not contain the required minimum number of special characters.

passwordNumCharViolation

Password does not contain the required number of characters.

passwordOldReused

Password is a recently used old password.

passwordUserName

Password contains the user name or is contained in the user name.

pinRequired

A PIN must be assigned to enable account.

policyAllowedAccess

All login policy checks permitted access.

policyViolation

Login rejected due to policy violation.

policyViolationMaxLoginsReached

Login rejected because maximum number of concurrent logins reached.

policyViolationTOD

Authentication denied at this time of the day.

tokenExpired

The lifetime for the token has expired.

tokenNotSupported

The given token is not a supported type.

tokenNotInValidFormat

The given token was not in the expected format or was corrupted.

tokenNotValidYet

The token is not valid yet.

tokenSignatureValidationFailed

The signature for the token was not valid.

usernameMismatch

In the case of reauthentication or stepUp authentication, the given user name does not match the current user name.

When a suggested value is not available, use the string "Unknown Failure Reason".

XPath

CommonBaseEvent/extendedDataElements[@name='outcome']/children
[@name='failureReason']/values

Parent topic: Reference information about elements and element types

outcome.majorStatusoutcome.majorStatus elementReference information about the outcome.majorStatus element.DescriptionMajor status code. Typically, majorStatus will be zero when result is SUCCESSFUL, and some nonzero value when it is not.ValuesAny integerXPathCommonBaseEvent/extendedDataElements[@name='outcome']/children [@name='majorStatus']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

outcome.majorStatus

Reference information about the outcome.majorStatus element.

Description

Major status code. Typically, majorStatus will be zero when result is SUCCESSFUL, and some nonzero value when it is not.

Values

Any integer

XPath

CommonBaseEvent/extendedDataElements[@name='outcome']/children
[@name='majorStatus']/values

Parent topic: Reference information about elements and element types

outcome.minorStatusoutcome.minorStatus elementReference information about the outcome.minorStatus element.DescriptionMinor status code. Typically, minorStatus will be zero when result is SUCCESSFUL, and some non-zero value when it is not.ValuesAny integerXPathCommonBaseEvent/extendedDataElements[@name='outcome']/children [@name='minorStatus']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

outcome.minorStatus

Reference information about the outcome.minorStatus element.

Description

Minor status code. Typically, minorStatus will be zero when result is SUCCESSFUL, and some non-zero value when it is not.

Values

Any integer

XPath

CommonBaseEvent/extendedDataElements[@name='outcome']/children
[@name='minorStatus']/values

Parent topic: Reference information about elements and element types

outcome.resultoutcome.result elementReference information about the outcome.result element.DescriptionOverall status of the event commonly used for filtering. Use UNSUCCESSFUL when an error condition arose which prevented normal processing, and SUCCESSFUL for normal processing.ValuesSame as the successDisposition field in the Situation types in the Common Base Event specification.SUCCESSFULUNSUCCESSFULXPathCommonBaseEvent/extendedDataElements[@name='outcome']/children [@name='result']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

outcome.result

Reference information about the outcome.result element.

Description

Overall status of the event commonly used for filtering. Use UNSUCCESSFUL when an error condition arose which prevented normal processing, and SUCCESSFUL for normal processing.

Values

Same as the successDisposition field in the Situation types in the Common Base Event specification.

SUCCESSFUL

UNSUCCESSFUL

XPath

CommonBaseEvent/extendedDataElements[@name='outcome']/children
[@name='result']/values

Parent topic: Reference information about elements and element types

partnerpartner elementReference information about the partner element.DescriptionEnd time of the operation.Valuesxsd:DateTimeXPathCommonBaseEvent/extendedDataElements[@name='partner']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

partner

Reference information about the partner element.

Description

End time of the operation.

Values

xsd:DateTime

XPath

CommonBaseEvent/extendedDataElements[@name='partner']/values

Parent topic: Reference information about elements and element types

perfInfoperfInfo elementReference information about the perfInfo element.DescriptionA container that represents performance and statistical data This information that can be helpful during capacity planning activities.This element uses the children of perfInfoType:perfInfo.aggregateperfInfo.descriptionperfInfo.nameperfInfo.maxValueperfInfo.minValueperfInfo.numDataPointsperfInfo.unitperfInfo.valueXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo

Reference information about the perfInfo element.

Description

A container that represents performance and statistical data This information that can be helpful during capacity planning activities.

This element uses the children of perfInfoType:

perfInfo.aggregate

perfInfo.description

perfInfo.name

perfInfo.maxValue

perfInfo.minValue

perfInfo.numDataPoints

perfInfo.unit

perfInfo.value

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

perfInfo.aggregateperfInfo.aggregate elementReference information about the perfInfo.aggregate element.DescriptionOperation for combining with other statistic events.ValuesStringThe following strings are suggested values:additionWhen combining with another statistic that measures the same data, then the values of the data should be added together.averageWhen combining with another statistic that measures the same data, then the values of the data should be averaged.XPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='aggregate']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.aggregate

Reference information about the perfInfo.aggregate element.

Description

Operation for combining with other statistic events.

Values

String

The following strings are suggested values:

addition

When combining with another statistic that measures the same data, then the values of the data should be added together.

average

When combining with another statistic that measures the same data, then the values of the data should be averaged.

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='aggregate']/values

Parent topic: Reference information about elements and element types

perfInfo.descriptionperfInfo.description elementReference information about the perfInfo.description element.DescriptionDescription of the statistic.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='description']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.description

Reference information about the perfInfo.description element.

Description

Description of the statistic.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='description']/values

Parent topic: Reference information about elements and element types

perfInfo.name elementperfInfo.name elementReference information about the perfInfo.name element.DescriptionName of the statistic.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='name']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.name element

Reference information about the perfInfo.name element.

Description

Name of the statistic.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='name']/values

Parent topic: Reference information about elements and element types

perfInfo.maxValueperfInfo.maxValue elementReference information about the perfInfo.maxValue element.DescriptionMaximum value among all data points.ValuesLongXPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='maxValue']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.maxValue

Reference information about the perfInfo.maxValue element.

Description

Maximum value among all data points.

Values

Long

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='maxValue']/values

Parent topic: Reference information about elements and element types

perfInfo.minValueperfInfo.minValue elementReference information about the perfInfo.minValue element.DescriptionMinimum value among all data points.ValuesLongXPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='minValue']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.minValue

Reference information about the perfInfo.minValue element.

Description

Minimum value among all data points.

Values

Long

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='minValue']/values

Parent topic: Reference information about elements and element types

perfInfo.numDataPointsperfInfo.numDataPoints elementReference information about the perfInfo.numDataPoints element.DescriptionNumber of data points gathered.ValuesIntegerXPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='numDataPoints']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.numDataPoints

Reference information about the perfInfo.numDataPoints element.

Description

Number of data points gathered.

Values

Integer

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='numDataPoints']/values

Parent topic: Reference information about elements and element types

perfInfo.unit elementperfInfo.unit elementReference information about the perfInfo.unit element.DescriptionUnit of measurement for the value.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='unit']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.unit element

Reference information about the perfInfo.unit element.

Description

Unit of measurement for the value.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='unit']/values

Parent topic: Reference information about elements and element types

perfInfo.valueperfInfo.value elementReference information about the perfInfo.value element.DescriptionValue of the statistic.ValuesLongXPathCommonBaseEvent/extendedDataElements[@name='perfInfo']/children [@name='value']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

perfInfo.value

Reference information about the perfInfo.value element.

Description

Value of the statistic.

Values

Long

XPath

CommonBaseEvent/extendedDataElements[@name='perfInfo']/children
[@name='value']/values

Parent topic: Reference information about elements and element types

permissionInfopermissionInfo elementReference information about the permissionInfo element.DescriptionA container represents information about access permissions.This element uses the children of permissionInfoType:permissionInfoType.checkedpermissionInfoType.deniedpermissionInfoType.grantedpermissionInfoType.J2EERolesCheckedpermissionInfoType.J2EERolesGrantedXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

permissionInfo

Reference information about the permissionInfo element.

Description

A container represents information about access permissions.

This element uses the children of permissionInfoType:

permissionInfoType.checked

permissionInfoType.denied

permissionInfoType.granted

permissionInfoType.J2EERolesChecked

permissionInfoType.J2EERolesGranted

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

permissionInfo.checkedpermissionInfo.checked elementReference information about the permissionInfo.checked element.DescriptionPermission that are being checked during the authorization call.ValuesString[]Any arbitrary string allowed by the application can be provided as an element of the String[].XPathThe XPath accesses the first checked element from an array of checked elements.CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children [@name='checked']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

permissionInfo.checked

Reference information about the permissionInfo.checked element.

Description

Permission that are being checked during the authorization call.

Values

String[]

Any arbitrary string allowed by the application can be provided as an element of the String[].

XPath

The XPath accesses the first checked element from an array of checked elements.

CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children
[@name='checked']/values[1]

Parent topic: Reference information about elements and element types

permissionInfo.deniedpermissionInfo.denied elementReference information about the permissionInfo.denied element.DescriptionPermissions that are denied out of the ones requested.ValuesString[]Any arbitrary string allowed by the application can be provided as an element of the String[].XPathThe XPath accesses the first denied element from an array of denied elements.CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children [@name='denied']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

permissionInfo.denied

Reference information about the permissionInfo.denied element.

Description

Permissions that are denied out of the ones requested.

Values

String[]

Any arbitrary string allowed by the application can be provided as an element of the String[].

XPath

The XPath accesses the first denied element from an array of denied elements.

CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children
[@name='denied']/values[1]

Parent topic: Reference information about elements and element types

permissionInfo.grantedpermissionInfo.granted elementReference information about the permissionInfo.granted element.DescriptionPermissions that are granted.ValuesString[]Any arbitrary string allowed by the application can be provided as an element of the String[].XPathThe XPath accesses the first granted element from an array of granted elements.CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children [@name='granted']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

permissionInfo.granted

Reference information about the permissionInfo.granted element.

Description

Permissions that are granted.

Values

String[]

Any arbitrary string allowed by the application can be provided as an element of the String[].

XPath

The XPath accesses the first granted element from an array of granted elements.

CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children
[@name='granted']/values[1]

Parent topic: Reference information about elements and element types

permissionInfo.J2EERolesCheckedpermissionInfo.J2EERolesChecked elementReference information about the permissionInfo.J2EERolesChecked element.DescriptionJ2EE roles being checked.ValuesString[]Any arbitrary string allowed by the application can be provided as an element of the String[].XPathThe XPath accesses the first J2EERolesChecked element from an array of J2EERolesChecked elements.CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children [@name='J2EERolesChecked']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

permissionInfo.J2EERolesChecked

Reference information about the permissionInfo.J2EERolesChecked element.

Description

J2EE roles being checked.

Values

String[]

Any arbitrary string allowed by the application can be provided as an element of the String[].

XPath

The XPath accesses the first J2EERolesChecked element from an array of J2EERolesChecked elements.

CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children
[@name='J2EERolesChecked']/values[1]

Parent topic: Reference information about elements and element types

permissionInfo.J2EERolesGrantedpermissionInfo.J2EERolesGranted elementReference information about the permissionInfo.J2EERolesGranted element.DescriptionJ2EE roles granted.ValuesString[]Any arbitrary string allowed by the application can be provided as an element of the String[].XPathThe XPath accesses the first J2EERolesGranted element from an array of J2EERolesGranted elements.CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children [@name='J2EERolesGranted']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

permissionInfo.J2EERolesGranted

Reference information about the permissionInfo.J2EERolesGranted element.

Description

J2EE roles granted.

Values

String[]

Any arbitrary string allowed by the application can be provided as an element of the String[].

XPath

The XPath accesses the first J2EERolesGranted element from an array of J2EERolesGranted elements.

CommonBaseEvent/extendedDataElements[@name='permissionInfo']/children
[@name='J2EERolesGranted']/values[1]

Parent topic: Reference information about elements and element types

policyDescriptionpolicyDescription elementReference information about the policyDescription element.DescriptionDescription of the policy that contains violation specification.ValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='policyDescription']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyDescription

Reference information about the policyDescription element.

Description

Description of the policy that contains violation specification.

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='policyDescription']/values

Parent topic: Reference information about elements and element types

policyInfopolicyInfo elementReference information about the policyInfo element.DescriptionA container for information about the policy object, which can includes policies that are attached to the resource or policies that are the container of a resource.This element type represents a policy associated with an authorization resource or policy management event.The element uses the children of policyInfoType:policyInfo.attributespolicyInfo.branchpolicyInfo.descriptionpolicyInfo.namepolicyInfo.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyInfo

Reference information about the policyInfo element.

Description

A container for information about the policy object, which can includes policies that are attached to the resource or policies that are the container of a resource.

This element type represents a policy associated with an authorization resource or policy management event.

The element uses the children of policyInfoType:

policyInfo.attributes

policyInfo.branch

policyInfo.description

policyInfo.name

policyInfo.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

policyInfo.attributespolicyInfo.attributes elementReference information about the policyInfo.attributes element.DescriptionAttributes associated with a policy.ValuesattributeType[]See attributes elementReference information about the attributes element. for details.XPathThe XPath accesses the first source element from an array of attributes elements.CommonBaseEvent/extendedDataElements [@name='policyInfo']/children[5]/children [@name='source']/valuesThe index is 5, for the attributes element must come after thebranch, description, name, and type elements:Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyInfo.attributes

Reference information about the policyInfo.attributes element.

Description

Attributes associated with a policy.

Values

attributeType[]

See attributes element for details.

XPath

The XPath accesses the first source element from an array of attributes elements.

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children[5]/children
[@name='source']/values

Note: The index is 5, for the attributes element must come after thebranch, description, name, and type elements:

Parent topic: Reference information about elements and element types

policyInfo.branchpolicyInfo.branch elementReference information about the policyInfo.branch element.DescriptionName of the branch to which the policy applies.ValuesStringFor example: The product lets you group the policy for similar machines under user-defined policy branches.XPathCommonBaseEvent/extendedDataElements[@name='policyInfo']/children [@name='branch']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyInfo.branch

Reference information about the policyInfo.branch element.

Description

Name of the branch to which the policy applies.

Values

String

For example: The product lets you group the policy for similar machines under user-defined policy branches.

XPath

CommonBaseEvent/extendedDataElements[@name='policyInfo']/children
[@name='branch']/values

Parent topic: Reference information about elements and element types

policyInfo.descriptionpolicyInfo.description elementReference information about the policyInfo.description element.DescriptionDescription of the policy.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='policyInfo']/children [@name='description']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyInfo.description

Reference information about the policyInfo.description element.

Description

Description of the policy.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='policyInfo']/children
[@name='description']/values

Parent topic: Reference information about elements and element types

policyInfo.name elementpolicyInfo.name elementReference information about the policyInfo.name element.DescriptionName of the policy.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='policyInfo']/children [@name='name']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyInfo.name element

Reference information about the policyInfo.name element.

Description

Name of the policy.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='policyInfo']/children
[@name='name']/values

Parent topic: Reference information about elements and element types

policyInfo.type elementpolicyInfo.type elementReference information about the policyInfo.type element.DescriptionType of the policy.ValuesStringThe following strings are suggested values:accountPolicyAccount policy:Account expiry dateMaximum account ageTime of day (TOD) accessaclAccess control list.actionRepresents a permission.actionGroupRepresents a collection of permissions.authzRuleAuthorization rule.federationA collection of groups or organizations that participate in a trust relationship.identityPolicySpecifies how identities, or user IDs, are generated when provisioning one or more resources.keyA cryptographic key, either symmetric or asymmetric.loginPolicyPolicy that controls login behavior:Login failure countLogin disable time intervalpartnerA group or organization that is participating in a federation. passwordPolicyA set of rules in which all passwords for one or more services must conform.policyGeneric policy value to be used for policies that are not defined in the other values.popProtected object policy (POP) controls.Audit levelAdditional attributesQuality of protection (QoP)provisioningPolicy Used to associate one or multiple groups of users with one or multiple entitlements. The group of users can be identified by organization or organization role. The entitlement is a construct to define a set of permissions, or privileges, on a managed provisioning resource.serviceSelectionPolicyUsed in situations where the instance of a provisioning resource, on which the provisioning of an account is to take place, is determined dynamically based on account owner's attributes.spsModuleA Single Sign-On (SSO) Protocol Service module (for example, the Liberty module).stsChainA grouping of Security Token Service (STS) module instances.stsModuleSecurity Token Service (STS) module (for example, SAML module).XPathCommonBaseEvent/extendedDataElements[@name='policyInfo']/children [@name='type']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyInfo.type element

Reference information about the policyInfo.type element.

Description

Type of the policy.

Values

String

The following strings are suggested values:

accountPolicy

Account policy:

Account expiry date

Maximum account age

Time of day (TOD) access

acl

Access control list.

action

Represents a permission.

actionGroup

Represents a collection of permissions.

authzRule

Authorization rule.

federation

A collection of groups or organizations that participate in a trust relationship.

identityPolicy

Specifies how identities, or user IDs, are generated when provisioning one or more resources.

key

A cryptographic key, either symmetric or asymmetric.

loginPolicy

Policy that controls login behavior:

Login failure count

Login disable time interval

partner

A group or organization that is participating in a federation.

passwordPolicy

A set of rules in which all passwords for one or more services must conform.

policy

Generic policy value to be used for policies that are not defined in the other values.

pop

Protected object policy (POP) controls.

Audit level

Additional attributes

Quality of protection (QoP)

provisioningPolicy

Used to associate one or multiple groups of users with one or multiple entitlements. The group of users can be identified by organization or organization role. The entitlement is a construct to define a set of permissions, or privileges, on a managed provisioning resource.

serviceSelectionPolicy

Used in situations where the instance of a provisioning resource, on which the provisioning of an account is to take place, is determined dynamically based on account owner's attributes.

spsModule

A Single Sign-On (SSO) Protocol Service module (for example, the Liberty module).

stsChain

A grouping of Security Token Service (STS) module instances.

stsModule

Security Token Service (STS) module (for example, SAML module).

XPath

CommonBaseEvent/extendedDataElements[@name='policyInfo']/children
[@name='type']/values

Parent topic: Reference information about elements and element types

policyNamepolicyName elementReference information about the policyName element.DescriptionName of policy. Example: ITCS104AIX.ValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='policyName']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

policyName

Reference information about the policyName element.

Description

Name of policy. Example: "ITCS104AIX".

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='policyName']/values

Parent topic: Reference information about elements and element types

progNameprogName elementReference information about the progName element.DescriptionName of the program that is involved in the event.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='progName']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

progName

Reference information about the progName element.

Description

Name of the program that is involved in the event.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='progName']/values

Parent topic: Reference information about elements and element types

provisioningInfoprovisioningInfo elementReference information about the provisioningInfo element.DescriptionA container for the information about a provisioned resource that is the target of the operation.This element uses the children of provisioningInfoType:provisioningInfoType.accountIdprovisioningInfoType.resourceIdprovisioningInfoType.resourceTypeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

provisioningInfo

Reference information about the provisioningInfo element.

Description

A container for the information about a provisioned resource that is the target of the operation.

This element uses the children of provisioningInfoType:

provisioningInfoType.accountId

provisioningInfoType.resourceId

provisioningInfoType.resourceType

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

provisioningInfo.accountIdprovisioningInfo.accountId elementReference information about the provisioningInfo.accountId element.DescriptionUnique identifier of the target account.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='provisioningInfo']/children [@name='accountId']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

provisioningInfo.accountId

Reference information about the provisioningInfo.accountId element.

Description

Unique identifier of the target account.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='provisioningInfo']/children
[@name='accountId']/values

Parent topic: Reference information about elements and element types

provisioningInfo.resourceIdprovisioningInfo.resourceId elementReference information about the provisioningInfo.resourceId element.DescriptionUnique identifier of the target resource.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='provisioningInfo']/children [@name='resourceId']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

provisioningInfo.resourceId

Reference information about the provisioningInfo.resourceId element.

Description

Unique identifier of the target resource.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='provisioningInfo']/children
[@name='resourceId']/values

Parent topic: Reference information about elements and element types

provisioningInfo.resourceTypeprovisioningInfo.resourceType elementReference information about the provisioningInfo.resourceType element.DescriptionType of the target. For example, the type of the user, or the type of the provisioning resource.ValuesAn arbitrary string.See suggested values for resourceInfo.type elementReference information about the resourceInfo.type element. audit element.XPathCommonBaseEvent/extendedDataElements[@name='provisioningInfo']/children [@name='resourceType']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

provisioningInfo.resourceType

Reference information about the provisioningInfo.resourceType element.

Description

Type of the target. For example, the type of the user, or the type of the provisioning resource.

Values

An arbitrary string.

See suggested values for resourceInfo.type element audit element.

XPath

CommonBaseEvent/extendedDataElements[@name='provisioningInfo']/children
[@name='resourceType']/values

Parent topic: Reference information about elements and element types

provisioningTargetInfoprovisioningTargetInfo elementReference information about the provisioningTargetInfo element.DescriptionA container for target provisioning account.This element uses the children of provisioningInfoType:provisioningInfoType.accountIdprovisioningInfoType.resourceIdprovisioningInfoType.resourceTypeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

provisioningTargetInfo

Reference information about the provisioningTargetInfo element.

Description

A container for target provisioning account.

This element uses the children of provisioningInfoType:

provisioningInfoType.accountId

provisioningInfoType.resourceId

provisioningInfoType.resourceType

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

recommendationrecommendation elementReference information about the recommendation element.DescriptionProvides information related to remedial actions to take to protect against the vulnerability.ValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='recommendation']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

recommendation

Reference information about the recommendation element.

Description

Provides information related to remedial actions to take to protect against the vulnerability.

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='recommendation']/values

Parent topic: Reference information about elements and element types

registryInforegistryInfo elementReference information about the registryInfo element.DescriptionA container for information about the user registry that is involved in the operation.This element uses the children of the registryInfoType element:registryInfo.serverLocationregistryInfo.serverLocationTyperegistryInfo.serverPortregistryInfo.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryInfo

Reference information about the registryInfo element.

Description

A container for information about the user registry that is involved in the operation.

This element uses the children of the registryInfoType element:

registryInfo.serverLocation

registryInfo.serverLocationType

registryInfo.serverPort

registryInfo.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

registryInfo.serverLocationregistryInfo.serverLocation elementReference information about the registryInfo.serverLocation element.DescriptionLocation of the registry server.Valuesxsd:stringRefer to the location field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='registryInfo']/children [@name='serverLocation']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryInfo.serverLocation

Reference information about the registryInfo.serverLocation element.

Description

Location of the registry server.

Values

xsd:string

Refer to the location field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='registryInfo']/children
[@name='serverLocation']/values

Parent topic: Reference information about elements and element types

registryInfo.serverLocationTyperegistryInfo.serverLocationType elementReference information about the registryInfo.serverLocationType element.DescriptionType of server location.Valuesxsd:NameRefer to the locationType field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='registryInfo']/children [@name='serverLocationType']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryInfo.serverLocationType

Reference information about the registryInfo.serverLocationType element.

Description

Type of server location.

Values

xsd:Name

Refer to the locationType field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='registryInfo']/children
[@name='serverLocationType']/values

Parent topic: Reference information about elements and element types

registryInfo.serverPortregistryInfo.serverPort elementReference information about the registryInfo.serverPort element.DescriptionPort on which the registry server is listening.ValuesStringPort numberXPathCommonBaseEvent/extendedDataElements[@name='registryInfo']/children [@name='serverPort']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryInfo.serverPort

Reference information about the registryInfo.serverPort element.

Description

Port on which the registry server is listening.

Values

String

Port number

XPath

CommonBaseEvent/extendedDataElements[@name='registryInfo']/children
[@name='serverPort']/values

Parent topic: Reference information about elements and element types

registryInfo.type elementregistryInfo.type elementReference information about the registryInfo.type element.DescriptionType of registry.ValuesStringThe following strings are suggested values:ActiveDirActive Directory registry.AIXAIX user registry.LDAPLDAP registry.LinuxLinux user registry.SolarisSolaris user registry.WindowsWindows user registry.XPathCommonBaseEvent/extendedDataElements[@name='registryInfo']/children [@name='type']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryInfo.type element

Reference information about the registryInfo.type element.

Description

Type of registry.

Values

String

The following strings are suggested values:

ActiveDir

Active Directory registry.

AIX

AIX user registry.

LDAP

LDAP registry.

Linux

Linux user registry.

Solaris

Solaris user registry.

Windows

Windows user registry.

XPath

CommonBaseEvent/extendedDataElements[@name='registryInfo']/children
[@name='type']/values

Parent topic: Reference information about elements and element types

registryObjectInforegistryObjectInfo elementReference information about the registryObjectInfo element.DescriptionA container for information about the registry object that is being managed.This container uses the children of the registryObjectInfoType element:registryObjectInfo.attributesregistryObjectInfo.descriptionregistryObjectInfo.nameregistryObjectInfo.registryNameregistryObjectInfo.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryObjectInfo

Reference information about the registryObjectInfo element.

Description

A container for information about the registry object that is being managed.

This container uses the children of the registryObjectInfoType element:

registryObjectInfo.attributes

registryObjectInfo.description

registryObjectInfo.name

registryObjectInfo.registryName

registryObjectInfo.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

registryObjectInfo.attributesregistryObjectInfo.attributes elementReference information about the registryObjectInfo.attributes element.DescriptionAttributes associated with a registry object.ValuesattributeType[]See attributes elementReference information about the attributes element. for details.XPathThe XPath accesses the first name element from an array of attributes elements.CommonBaseEvent/extendedDataElements [@name='registryObjectInfo']/children[5] [@name='name']/values The index is 5, for the attributes element must come after thedescription, name, registryName, and type elements:Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryObjectInfo.attributes

Reference information about the registryObjectInfo.attributes element.

Description

Attributes associated with a registry object.

Values

attributeType[]

See attributes element for details.

XPath

The XPath accesses the first name element from an array of attributes elements.

CommonBaseEvent/extendedDataElements
[@name='registryObjectInfo']/children[5]
[@name='name']/values

Note: The index is 5, for the attributes element must come after thedescription, name, registryName, and type elements:

Parent topic: Reference information about elements and element types

registryObjectInfo.descriptionregistryObjectInfo.description elementReference information about the registryObjectInfo.description element.DescriptionDescription of the policy.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children [@name='description']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryObjectInfo.description

Reference information about the registryObjectInfo.description element.

Description

Description of the policy.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children
[@name='description']/values

Parent topic: Reference information about elements and element types

registryObjectInfo.name elementregistryObjectInfo.name elementReference information about the registryObjectInfo.name element.DescriptionApplication name for the registry object.ValuesStringAny string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children [@name='name']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryObjectInfo.name element

Reference information about the registryObjectInfo.name element.

Description

Application name for the registry object.

Values

String

Any string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children
[@name='name']/values

Parent topic: Reference information about elements and element types

registryObjectInfo.registryNameregistryObjectInfo.registryName elementReference information about the registryObjectInfo.registryName element.DescriptionRegistry name for the registry object.ValuesStringAny string allowed by the registry.XPathCommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children [@name='registryName']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryObjectInfo.registryName

Reference information about the registryObjectInfo.registryName element.

Description

Registry name for the registry object.

Values

String

Any string allowed by the registry.

XPath

CommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children
[@name='registryName']/values

Parent topic: Reference information about elements and element types

registryObjectInfo.type elementregistryObjectInfo.type elementReference information about the registryObjectInfo.type element.DescriptionType of the registry object.ValuesStringThe following strings are suggested values:domainA registry object that represents a domain.groupA registry object that represents a group.gsoResourceA registry object that represents a global sign-on (GSO) resource.orgContainerIdentifies the organization hierarchy for the user.userA registry object that represents a user.XPathCommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children [@name='type']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

registryObjectInfo.type element

Reference information about the registryObjectInfo.type element.

Description

Type of the registry object.

Values

String

The following strings are suggested values:

domain

A registry object that represents a domain.

group

A registry object that represents a group.

gsoResource

A registry object that represents a global sign-on (GSO) resource.

orgContainer

Identifies the organization hierarchy for the user.

user

A registry object that represents a user.

XPath

CommonBaseEvent/extendedDataElements[@name='registryObjectInfo']/children
[@name='type']/values

Parent topic: Reference information about elements and element types

reporterComponentIdreporterComponentId elementReference information about the reporterComponentId element.DescriptionA container for the reporter of the audit record on behalf of the source component. This container element is used when the reporting component is different from the source component.When displayed in output, this element uses the children of the auditComponentIdType element:applicationcomponentcomponentIdTypecomponentTypeexecutionEnvironmentinstanceIdlocationlocationTypeprocessedsubcomponentthreadIdXPathThis element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

reporterComponentId

Reference information about the reporterComponentId element.

Description

A container for the reporter of the audit record on behalf of the source component. This container element is used when the reporting component is different from the source component.

When displayed in output, this element uses the children of the auditComponentIdType element:

application

component

componentIdType

componentType

executionEnvironment

instanceId

location

locationType

processed

subcomponent

threadId

XPath

This element, nor its children, should be defined in the shredder configuration file. These elements are generated by the code.

Parent topic: Reference information about elements and element types

resourceInforesourceInfo elementReference information about the resourceInfo element.DescriptionThe container for information about the resource that is being accessed or that to which the policy applies.This element uses the children of the resourceInfoType element:resourceInfo.attributesresourceInfo.nameInAppresourceInfo.nameInPolicyresourceInfo.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

resourceInfo

Reference information about the resourceInfo element.

Description

The container for information about the resource that is being accessed or that to which the policy applies.

This element uses the children of the resourceInfoType element:

resourceInfo.attributes

resourceInfo.nameInApp

resourceInfo.nameInPolicy

resourceInfo.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

resourceInfo.attributesresourceInfo.attributes elementReference information about the resourceInfo.attributes element.DescriptionArray of attributes for the resource.ValuesattributeType []Refer to attributes elementReference information about the attributes element. for details.XPathThe XPath accesses the first name element from an array of attributes elements.CommonBaseEvent/extendedDataElements [@name='registryObjectInfo']/children[4] [@name='name']/values The index is 4, for the attributes element must come after thenameInApp, nameInPolicy, and type elements:CommonBaseEvent/extendedDataElements[@name='resourceInfo']/children [@name='attributes']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

resourceInfo.attributes

Reference information about the resourceInfo.attributes element.

Description

Array of attributes for the resource.

Values

attributeType []

Refer to attributes element for details.

XPath

The XPath accesses the first name element from an array of attributes elements.

CommonBaseEvent/extendedDataElements
[@name='registryObjectInfo']/children[4]
[@name='name']/values

Note: The index is 4, for the attributes element must come after thenameInApp, nameInPolicy, and type elements:

CommonBaseEvent/extendedDataElements[@name='resourceInfo']/children
[@name='attributes']/values

Parent topic: Reference information about elements and element types

resourceInfo.nameInAppresourceInfo.nameInApp elementReference information about the resourceInfo.nameInApp element.DescriptionName of the resource in the context of the application.ValuesAny arbitrary stringUser Not Available when not available.XPathCommonBaseEvent/extendedDataElements[@name='resourceInfo']/children [@name='nameInApp']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

resourceInfo.nameInApp

Reference information about the resourceInfo.nameInApp element.

Description

Name of the resource in the context of the application.

Values

Any arbitrary string

User "Not Available" when not available.

XPath

CommonBaseEvent/extendedDataElements[@name='resourceInfo']/children
[@name='nameInApp']/values

Parent topic: Reference information about elements and element types

resourceInfo.nameInPolicyresourceInfo.nameInPolicy elementReference information about the resourceInfo.nameInPolicy element.DescriptionName of the resource when applying a policy to it. For example, Security Access Manager protected object name.ValuesAny arbitrary stringUser Not Available when not available.XPathCommonBaseEvent/extendedDataElements[@name='resourceInfo']/children [@name='nameInPolicy']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

resourceInfo.nameInPolicy

Reference information about the resourceInfo.nameInPolicy element.

Description

Name of the resource when applying a policy to it. For example, Security Access Manager protected object name.

Values

Any arbitrary string

User "Not Available" when not available.

XPath

CommonBaseEvent/extendedDataElements[@name='resourceInfo']/children
[@name='nameInPolicy']/values

Parent topic: Reference information about elements and element types

resourceInfo.type elementresourceInfo.type elementReference information about the resourceInfo.type element.DescriptionType of the resource.ValuesStringThe following strings are suggested values:applicationAn application such as Security Access Manager server, Directory Server, Identity Manager server, or any executable process.fileFile system resource. For example, /OSSEAL/policy-branch/File/filespec.groupUsed to group users for Role Based Access Control.identityPolicyIdentify policy specifies how user identities are generated when provisioning one or more resources.junctionDescribes a WebSEAL junction.loginPolicies that are related to login. For example, password expiry, account suspension due to failed login attempts, or account lockouts due to account inactivity.managementAuthorization of a management command. The specific management object type is contained in the resourceName.messageQueueA message queue.netIncomingIncoming network accesses are controlled by network resources: NetIncoming resource:/OSSEAL/policy-branch/NetIncoming/protocol[/service[/host]]netOutgoingOutgoing network accesses are controlled by the following network resource. NetOutgoing resource:/OSSEAL/policy-branch/NetOutgoing/[/hostspec[/protocol[/service]]]orgContainerThe organization container defines the organization hierarchy for the managed resources. passwordPolicySpecifies a set of rules in which all passwords for one or more services must conform. For example, password strength and password aging.policyUpdateIndicates a policy update. For example, the product might receive a policy update (downloaded from the policy database).protectedResourceA generic value for a protected resource. For example, Security Access Manager protected object or Security Access Manager protected object space.provisioningAccountRepresents a user's identity on the target provisioning resource.provisioningPolicyUsed to associate one or multiple groups of users with one or multiple entitlements. The group of users can be identified by organization or organization role. The entitlement is a construct to define a set of permissions, or privileges, on a managed provisioning resource.provisioningResourceA resource for which Identity Provisioning is enabled.serviceSelectionPolicyUsed in situations where the instance of a provisioning resource, on which the provisioning of an account is to take place, is determined dynamically based on account owner's attributes.sudoDescribe commands that require more stringent access control than whether a particular program can be run. Sudo commands allow access control based not only on a command but also on the parameters passed to that command. You can use Sudo commands to remove the requirements for a user to become the root user on a system in order to perform administrative tasks. Sudo resources are identified in the Security Access Manager namespace in the following way: /OSSEAL/policy-branch/Sudo/sudo-command[/sudo-orglass]surrogateSurrogate resources. Operations that can change the user identity or group identity of a process are referred to as surrogate operations and are controlled by resources of type surrogate. Surrogate resource names follow the form: /OSSEAL/policy-branch/Surrogate/User/user-name.tcbTrusted Computing Base resources.workflowTemplateDefines the flow of a business workflow process.urlAn absolute URL identifying the resource accessed. Use the File resource type for file:// URLs.userThe user entity that application manages in the registry.XPathCommonBaseEvent/extendedDataElements[@name='resourceInfo']/children [@name='type']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

resourceInfo.type element

Reference information about the resourceInfo.type element.

Description

Type of the resource.

Values

String

The following strings are suggested values:

application

An application such as Security Access Manager server, Directory Server, Identity Manager server, or any executable process.

file

File system resource. For example, /OSSEAL/policy-branch/File/filespec.

group

Used to group users for Role Based Access Control.

identityPolicy

Identify policy specifies how user identities are generated when provisioning one or more resources.

junction

Describes a WebSEAL junction.

login

Policies that are related to login. For example, password expiry, account suspension due to failed login attempts, or account lockouts due to account inactivity.

management

Authorization of a management command. The specific management object type is contained in the resourceName.

messageQueue

A message queue.

netIncoming

Incoming network accesses are controlled by network resources: NetIncoming resource:/OSSEAL/policy-branch/NetIncoming/protocol[/service[/host]]

netOutgoing

Outgoing network accesses are controlled by the following network resource. NetOutgoing resource:/OSSEAL/policy-branch/NetOutgoing/[/hostspec[/protocol[/service]]]

orgContainer

The organization container defines the organization hierarchy for the managed resources.

passwordPolicy

Specifies a set of rules in which all passwords for one or more services must conform. For example, password strength and password aging.

policyUpdate

Indicates a policy update. For example, the product might receive a policy update (downloaded from the policy database).

protectedResource

A generic value for a protected resource. For example, Security Access Manager protected object or Security Access Manager protected object space.

provisioningAccount

Represents a user's identity on the target provisioning resource.

provisioningPolicy

Used to associate one or multiple groups of users with one or multiple entitlements. The group of users can be identified by organization or organization role. The entitlement is a construct to define a set of permissions, or privileges, on a managed provisioning resource.

provisioningResource

A resource for which Identity Provisioning is enabled.

serviceSelectionPolicy

Used in situations where the instance of a provisioning resource, on which the provisioning of an account is to take place, is determined dynamically based on account owner's attributes.

sudo

Describe commands that require more stringent access control than whether a particular program can be run. Sudo commands allow access control based not only on a command but also on the parameters passed to that command.

You can use Sudo commands to remove the requirements for a user to become the root user on a system in order to perform administrative tasks.

Sudo resources are identified in the Security Access Manager namespace in the following way: /OSSEAL/policy-branch/Sudo/sudo-command[/sudo-orglass]

surrogate

Surrogate resources. Operations that can change the user identity or group identity of a process are referred to as surrogate operations and are controlled by resources of type surrogate. Surrogate resource names follow the form: /OSSEAL/policy-branch/Surrogate/User/user-name.

tcb

Trusted Computing Base resources.

workflowTemplate

Defines the flow of a business workflow process.

url

An absolute URL identifying the resource accessed. Use the File resource type for file:// URLs.

user

The user entity that application manages in the registry.

XPath

CommonBaseEvent/extendedDataElements[@name='resourceInfo']/children
[@name='type']/values

Parent topic: Reference information about elements and element types

sequenceNumberuserInfo elementReference information about the sequenceNumber element.DescriptionAn internal identifier for an audit event as shown in the XML output.This information is not related to the following line in the CARSShredder.conf file:cars_t_event, cars_seq_number, #RECORD_IDReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sequenceNumber

Reference information about the sequenceNumber element.

Description

An internal identifier for an audit event as shown in the XML output.

This information is not related to the following line in the CARSShredder.conf file:

cars_t_event, cars_seq_number, #RECORD_ID

Parent topic: Reference information about elements and element types

severityseverity elementReference information about the severity element.DescriptionIdentifies severity of the violation.ValuesStringThe following strings are suggested values:highViolation of high severity.lowViolation of low severity.mediumViolation of medium severity.XPathCommonBaseEvent/extendedDataElements[@name='severity']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

severity

Reference information about the severity element.

Description

Identifies severity of the violation.

Values

String

The following strings are suggested values:

high

Violation of high severity.

low

Violation of low severity.

medium

Violation of medium severity.

XPath

CommonBaseEvent/extendedDataElements[@name='severity']/values

Parent topic: Reference information about elements and element types

sourceComponentIdsourceComponentId elementReference information about the sourceComponentId element.DescriptionA container for the information about what originated the audit record.When displayed in output, this element uses the children of the auditComponentIdType element:sourceComponentId/@applicationsourceComponentId/@componentsourceComponentId/@componentIdTypesourceComponentId/@componentTypesourceComponentId/@executionEnvironmentsourceComponentId/@instanceIdsourceComponentId/@locationsourceComponentId/@locationTypesourceComponentId/@processedsourceComponentId/@subComponentsourceComponentId/@threadIdXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId

Reference information about the sourceComponentId element.

Description

A container for the information about what originated the audit record.

When displayed in output, this element uses the children of the auditComponentIdType element:

sourceComponentId/@application

sourceComponentId/@component

sourceComponentId/@componentIdType

sourceComponentId/@componentType

sourceComponentId/@executionEnvironment

sourceComponentId/@instanceId

sourceComponentId/@location

sourceComponentId/@locationType

sourceComponentId/@processed

sourceComponentId/@subComponent

sourceComponentId/@threadId

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

sourceComponentId/@applicationsourceComponentId/@application elementReference information about the sourceComponentId/@application element.DescriptionRefer to the Common Base Event specification.Valuesxsd:stringRefer to same field in the ComponentIdentification in the Common Base Event specification. For example: WebSEAL is an application within the component IBM Security Access Manager.XPathCommonBaseEvent/sourceComponentId/@applicationReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@application

Reference information about the sourceComponentId/@application element.

Description

Refer to the Common Base Event specification.

Values

xsd:string

Refer to same field in the ComponentIdentification in the Common Base Event specification. For example: WebSEAL is an application within the component IBM Security Access Manager.

XPath

CommonBaseEvent/sourceComponentId/@application

Parent topic: Reference information about elements and element types

sourceComponentId/@componentsourceComponentId/@component elementReference information about the sourceComponentId/@component element.DescriptionProduct name, version, and fix pack level.ValuesStringFor example, WebSEAL is an application within the component IBM Security Access Manager, version 9.0, FixPack x. Refer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@componentReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@component

Reference information about the sourceComponentId/@component element.

Description

Product name, version, and fix pack level.

Values

String

For example, WebSEAL is an application within the component IBM Security Access Manager, version 9.0, FixPack x.

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@component

Parent topic: Reference information about elements and element types

sourceComponentId/@componentIdTypesourceComponentId/@componentIdType elementReference information about the sourceComponentId/@componentIdType element.DescriptionSpecifies the format and meaning of the component identified by this componentIdentification.Valuesxsd:stringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@componentIdTypeReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@componentIdType

Reference information about the sourceComponentId/@componentIdType element.

Description

Specifies the format and meaning of the component identified by this componentIdentification.

Values

xsd:string

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@componentIdType

Parent topic: Reference information about elements and element types

sourceComponentId/@componentTypesourceComponentId/@componentType elementReference information about the sourceComponentId/@componentType element.DescriptionA well-defined name that is used to characterize all instances of a given kind of component.Valuesxsd:stringRefer to same field in the ComponentType in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@componentTypeReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@componentType

Reference information about the sourceComponentId/@componentType element.

Description

A well-defined name that is used to characterize all instances of a given kind of component.

Values

xsd:string

Refer to same field in the ComponentType in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@componentType

Parent topic: Reference information about elements and element types

sourceComponentId/@executionEnvironmentsourceComponentId/@executionEnvironment elementReference information about the sourceComponentId/@executionEnvironment element.DescriptionThe immediate environment that an application is running in.Valuesxsd:stringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@executionEnvironmentReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@executionEnvironment

Reference information about the sourceComponentId/@executionEnvironment element.

Description

The immediate environment that an application is running in.

Values

xsd:string

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@executionEnvironment

Parent topic: Reference information about elements and element types

sourceComponentId/@instanceIdsourceComponentId/@instanceId elementReference information about the sourceComponentId/@instanceId element.DescriptionModule instance information, for example, port number.ValuesStringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@instanceIdReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@instanceId

Reference information about the sourceComponentId/@instanceId element.

Description

Module instance information, for example, port number.

Values

String

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@instanceId

Parent topic: Reference information about elements and element types

sourceComponentId/@locationsourceComponentId/@location elementReference information about the sourceComponentId/@location element.DescriptionPhysical location of the reporting component.Valuesxsd:stringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@locationReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@location

Reference information about the sourceComponentId/@location element.

Description

Physical location of the reporting component.

Values

xsd:string

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@location

Parent topic: Reference information about elements and element types

sourceComponentId/@locationTypesourceComponentId/@locationType elementReference information about the sourceComponentId/@locationType element.DescriptionType of location.Valuesxsd:stringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@locationTypeReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@locationType

Reference information about the sourceComponentId/@locationType element.

Description

Type of location.

Values

xsd:string

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@locationType

Parent topic: Reference information about elements and element types

sourceComponentId/@processIdsourceComponentId/@processId elementReference information about the sourceComponentId/@processId element.DescriptionProcess ID.ValuesStringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@processIdReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@processId

Reference information about the sourceComponentId/@processId element.

Description

Process ID.

Values

String

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@processId

Parent topic: Reference information about elements and element types

sourceComponentId/@subComponentsourceComponentId/@subComponent elementReference information about the sourceComponentId/@subComponent element.DescriptionModule name.ValuesStringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@subComponentReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@subComponent

Reference information about the sourceComponentId/@subComponent element.

Description

Module name.

Values

String

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@subComponent

Parent topic: Reference information about elements and element types

sourceComponentId/@threadIdsourceComponentId/@threadId elementReference information about the sourceComponentId/@threadId element.DescriptionThread ID.ValuesStringRefer to same field in the ComponentIdentification in the Common Base Event specification.XPathCommonBaseEvent/sourceComponentId/@threadIdReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

sourceComponentId/@threadId

Reference information about the sourceComponentId/@threadId element.

Description

Thread ID.

Values

String

Refer to same field in the ComponentIdentification in the Common Base Event specification.

XPath

CommonBaseEvent/sourceComponentId/@threadId

Parent topic: Reference information about elements and element types

startTimestartTime elementReference information about the startTime element.DescriptionStart time of the operation.Valuesxsd:DateTimeRefer to the creationTime field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='startTime'][@type='dateTime']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

startTime

Reference information about the startTime element.

Description

Start time of the operation.

Values

xsd:DateTime

Refer to the creationTime field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='startTime'][@type='dateTime']/values

Parent topic: Reference information about elements and element types

suppressedsuppressed elementReference information about the suppressed element.DescriptionIdentifies if the violation was suppressed.ValuesStringUse one of the following strings:yesnoXPathCommonBaseEvent/extendedDataElements[@name='suppressed']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

suppressed

Reference information about the suppressed element.

Description

Identifies if the violation was suppressed.

Values

String

Use one of the following strings:

yes

no

XPath

CommonBaseEvent/extendedDataElements[@name='suppressed']/values

Parent topic: Reference information about elements and element types

targetAccounttargetAccount elementReference information about the targetAccount element.DescriptionName of the user account.ValuesStringAny string allowed by targetResource.XPathCommonBaseEvent/extendedDataElements[@name='targetAccount']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetAccount

Reference information about the targetAccount element.

Description

Name of the user account.

Values

String

Any string allowed by targetResource.

XPath

CommonBaseEvent/extendedDataElements[@name='targetAccount']/values

Parent topic: Reference information about elements and element types

targetInfoTypetargetInfoType elementReference information about the targetInfoType element.DescriptionThis element type represents information about the target of a management action, such as associating an access control list with a protected resource.When displayed in output, this element uses the children of the targetInfoType element:targetInfoType.attributestargetInfoType.targetNamesXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetInfoType

Reference information about the targetInfoType element.

Description

This element type represents information about the target of a management action, such as associating an access control list with a protected resource.

When displayed in output, this element uses the children of the targetInfoType element:

targetInfoType.attributes

targetInfoType.targetNames

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

targetInfo.attributestargetInfo.attributes elementReference information about the targetInfo.attributes element.DescriptionArray of attributes for the values for the target.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetInfo.attributes

Reference information about the targetInfo.attributes element.

Description

Array of attributes for the values for the target.

Parent topic: Reference information about elements and element types

targetInfo.targetNamestargetInfo.targetNames elementReference information about the targetInfo.targetNames element.DescriptionObject this operation is targeted against.StringString allowed for the target object name by the application.Examples:For group associate, target is a list of users added to a group.For ACL associate, target is a resource name associated with an ACL.For ACL disassociate, target is a resource name disassociated with the ACL.XPathCommonBaseEvent/extendedDataElements[@name='mgmtInfo']/children [@name='targetInfo']/children [@name='targetNames']/values[1]This XPath assumes that the targetInfo is part of mgmtInfo.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetInfo.targetNames

Reference information about the targetInfo.targetNames element.

Description

Object this operation is targeted against.

String

String allowed for the target object name by the application.

Examples:

For group associate, target is a list of users added to a group.

For ACL associate, target is a resource name associated with an ACL.

For ACL disassociate, target is a resource name disassociated with the ACL.

XPath

CommonBaseEvent/extendedDataElements[@name='mgmtInfo']/children
[@name='targetInfo']/children
[@name='targetNames']/values[1]

Note: This XPath assumes that the targetInfo is part of mgmtInfo.

Parent topic: Reference information about elements and element types

targetResourcetargetResource elementReference information about the targetResource element.DescriptionName of the resource on which the account exists.ValuesStringAny string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='targetResource']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetResource

Reference information about the targetResource element.

Description

Name of the resource on which the account exists.

Values

String

Any string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='targetResource']/values

Parent topic: Reference information about elements and element types

targetUsertargetUser elementReference information about the targetUser element.DescriptionName of the user.ValuesStringAny string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='targetUser']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetUser

Reference information about the targetUser element.

Description

Name of the user.

Values

String

Any string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='targetUser']/values

Parent topic: Reference information about elements and element types

targetUserInfo (1)targetUserInfo (1) elementReference information about the targetUserInfo element when used with the AUDIT_WORKFLOW event type.DescriptionA container for information about the target users when used with the AUDIT_WORKFLOW event type.This element uses the children of userInfoType:userInfo.appUserNameuserInfo.attributesuserInfo.callerListuserInfo.domainuserInfo.locationuserInfo.locationTypeuserInfo.realmuserInfo.registryUserNameuserInfo.sessionIduserInfo.uniqueIdXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetUserInfo (1)

Reference information about the targetUserInfo element when used with the AUDIT_WORKFLOW event type.

Description

A container for information about the target users when used with the AUDIT_WORKFLOW event type.

This element uses the children of userInfoType:

userInfo.appUserName

userInfo.attributes

userInfo.callerList

userInfo.domain

userInfo.location

userInfo.locationType

userInfo.realm

userInfo.registryUserName

userInfo.sessionId

userInfo.uniqueId

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

targetUserInfo (2)targetUserInfo (2) elementReference information about the targetUserInfo element when used with the AUDIT_MGMT_PROVISIONING event type.DescriptionA container for information about the target users when used with the AUDIT_MGMT_PROVISIONING event type.For AUDIT_MGMT_PROVISIONING events, registryObjectInfo.type must be User.This element uses the children of registryObjectInfoType:registryObjectInfo.attributesregistryObjectInfo.descriptionregistryObjectInfo.nameregistryObjectInfo.registryNameregistryObjectInfo.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetUserInfo (2)

Reference information about the targetUserInfo element when used with the AUDIT_MGMT_PROVISIONING event type.

Description

A container for information about the target users when used with the AUDIT_MGMT_PROVISIONING event type.

For AUDIT_MGMT_PROVISIONING events, registryObjectInfo.type must be User.

This element uses the children of registryObjectInfoType:

registryObjectInfo.attributes

registryObjectInfo.description

registryObjectInfo.name

registryObjectInfo.registryName

registryObjectInfo.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

targetUserRegistryInfotargetUserRegistryInfo elementReference information about the targetUserRegistryInfo element.DescriptionA container for information about the registry to which the target user belongs.This element uses the children of the registryInfoType element:registryInfo.serverLocationregistryInfo.serverLocationTyperegistryInfo.serverPortregistryInfo.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

targetUserRegistryInfo

Reference information about the targetUserRegistryInfo element.

Description

A container for information about the registry to which the target user belongs.

This element uses the children of the registryInfoType element:

registryInfo.serverLocation

registryInfo.serverLocationType

registryInfo.serverPort

registryInfo.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

terminateReasonterminateReason elementReference information about the terminateReason element.DescriptionThe reason for the termination.ValuesStringThe following strings are suggested values:idleTimeoutThe session was terminated because it was inactive for too long.sessionExpiredThe session was terminated because its maximum lifetime was exceeded.sessionDisplacedThe session was terminated because the session's user created a new session displacing this one.sessionTerminatedByAdminThe session was terminated by an administrative action.userLoggedOutThe session was terminated at the user's request.XPathCommonBaseEvent/extendedDataElements[@name='terminateReason']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

terminateReason

Reference information about the terminateReason element.

Description

The reason for the termination.

Values

String

The following strings are suggested values:

idleTimeout

The session was terminated because it was inactive for too long.

sessionExpired

The session was terminated because its maximum lifetime was exceeded.

sessionDisplaced

The session was terminated because the session's user created a new session displacing this one.

sessionTerminatedByAdmin

The session was terminated by an administrative action.

userLoggedOut

The session was terminated at the user's request.

XPath

CommonBaseEvent/extendedDataElements[@name='terminateReason']/values

Parent topic: Reference information about elements and element types

timestamptimestamp elementReference information about the timestamp element.DescriptionEnd time of the operation.Valuesxsd:DateTimeIf not specified, it is generated automatically. The timestamp is used in reports to determine when the audit event occurred. If the caller specifies the timestamp, it is the caller's responsibility to ensure that the timestamp provided is not spoofed.Refer to the creationTime field in the Common Base Event specification.XPathCommonBaseEvent/@creationTimeReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

timestamp

Reference information about the timestamp element.

Description

End time of the operation.

Values

xsd:DateTime

If not specified, it is generated automatically. The timestamp is used in reports to determine when the audit event occurred. If the caller specifies the timestamp, it is the caller's responsibility to ensure that the timestamp provided is not spoofed.

Refer to the creationTime field in the Common Base Event specification.

XPath

CommonBaseEvent/@creationTime

Parent topic: Reference information about elements and element types

typetype elementReference information about the type element.DescriptionThe type of command.ValuesStringThe following strings suggested values:configConfiguration object.serverObject that represents an application server.XPathCommonBaseEvent/extendedDataElements[@name='type']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

type

Reference information about the type element.

Description

The type of command.

Values

String

The following strings suggested values:

config

Configuration object.

server

Object that represents an application server.

XPath

CommonBaseEvent/extendedDataElements[@name='type']/values

Parent topic: Reference information about elements and element types

userInfouserInfo elementReference information about the userInfo element.DescriptionThe container for information about the user.This element uses the children of userInfoType:userInfo.appUserNameuserInfo.attributesuserInfo.callerListuserInfo.domainuserInfo.locationuserInfo.locationTypeuserInfo.realmuserInfo.registryUserNameuserInfo.sessionIduserInfo.uniqueIdXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo

Reference information about the userInfo element.

Description

The container for information about the user.

This element uses the children of userInfoType:

userInfo.appUserName

userInfo.attributes

userInfo.callerList

userInfo.domain

userInfo.location

userInfo.locationType

userInfo.realm

userInfo.registryUserName

userInfo.sessionId

userInfo.uniqueId

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

userInfo.appUserNameuserInfo.appUserName elementReference information about the userInfo.appUserName element.DescriptionUser's name within a given application.ValuesStringAny arbitrary string allowed by the application. For example, a Security Access Manager user name.The following strings are suggested values:unauthenticatedAn unauthenticated userXPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='appUserName']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.appUserName

Reference information about the userInfo.appUserName element.

Description

User's name within a given application.

Values

String

Any arbitrary string allowed by the application. For example, a Security Access Manager user name.

The following strings are suggested values:

unauthenticated

An unauthenticated user

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='appUserName']/values

Parent topic: Reference information about elements and element types

userInfo.attributesuserInfo.attributes elementReference information about the userInfo.attributes element.DescriptionArray of attributes in the user's credential.ValuesattributeTypeRefer to attributes elementReference information about the attributes element. for details.XPathThe XPath is the first name element from an array of attributes elements.CommonBaseEvent/extendedDataElements [@name='userInfo']/children[10]/children [@name='name']/values The index is 10, for the attributes element must come after the appUserName, callerList, domain, location, locationType, realm, registryUserName, sessionId, and uniqueId elementsReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.attributes

Reference information about the userInfo.attributes element.

Description

Array of attributes in the user's credential.

Values

attributeType

Refer to attributes element for details.

XPath

The XPath is the first name element from an array of attributes elements.

CommonBaseEvent/extendedDataElements
[@name='userInfo']/children[10]/children
[@name='name']/values

Note: The index is 10, for the attributes element must come after the appUserName, callerList, domain, location, locationType, realm, registryUserName, sessionId, and uniqueId elements

Parent topic: Reference information about elements and element types

userInfo.callerListuserInfo.callerList elementReference information about the userInfo.callerList element.DescriptionA list of names representing the user's identities.ValuesString[]Any arbitrary string allowed by the application can be used in the String[].XPathThe XPath is the first callerList element from an array of callerList elements.CommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='callerList']/values[1]Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.callerList

Reference information about the userInfo.callerList element.

Description

A list of names representing the user's identities.

Values

String[]

Any arbitrary string allowed by the application can be used in the String[].

XPath

The XPath is the first callerList element from an array of callerList elements.

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='callerList']/values[1]

Parent topic: Reference information about elements and element types

userInfo.domainuserInfo.domain elementReference information about the userInfo.domain element.DescriptionDomain in which user belongs.ValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='domain']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.domain

Reference information about the userInfo.domain element.

Description

Domain in which user belongs.

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='domain']/values

Parent topic: Reference information about elements and element types

userInfo.locationuserInfo.location elementReference information about the userInfo.location element.DescriptionLocation of the user. Example: In the case of WebSEAL, where the user authenticated from.Valuesxsd:stringRefer to the location field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='location']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.location

Reference information about the userInfo.location element.

Description

Location of the user. Example: In the case of WebSEAL, where the user authenticated from.

Values

xsd:string

Refer to the location field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='location']/values

Parent topic: Reference information about elements and element types

userInfo.locationTypeuserInfo.locationType elementReference information about the userInfo.locationType element.DescriptionType of location.Valuesxsd:NameRefer to the locationType field in the Common Base Event specification.XPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='locationType']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.locationType

Reference information about the userInfo.locationType element.

Description

Type of location.

Values

xsd:Name

Refer to the locationType field in the Common Base Event specification.

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='locationType']/values

Parent topic: Reference information about elements and element types

userInfo.realmuserInfo.realm elementReference information about the userInfo.realm element.DescriptionThe registry partition to which the user belongs.ValuesStringAny arbitrary string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='realm']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.realm

Reference information about the userInfo.realm element.

Description

The registry partition to which the user belongs.

Values

String

Any arbitrary string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='realm']/values

Parent topic: Reference information about elements and element types

userInfo.registryUserNameuserInfo.registryUserName elementReference information about the userInfo.registryUserName element.DescriptionThe registry partition to which the user belongs.ValuesStringAny arbitrary string allowed by the application.Use Not Available when not available.XPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='registryUserName']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.registryUserName

Reference information about the userInfo.registryUserName element.

Description

The registry partition to which the user belongs.

Values

String

Any arbitrary string allowed by the application.

Use "Not Available" when not available.

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='registryUserName']/values

Parent topic: Reference information about elements and element types

userInfo.sessionIduserInfo.sessionId elementReference information about the userInfo.sessionId element.DescriptionID for the user's session.ValuesAny arbitrary stringXPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='sessionId']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.sessionId

Reference information about the userInfo.sessionId element.

Description

ID for the user's session.

Values

Any arbitrary string

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='sessionId']/values

Parent topic: Reference information about elements and element types

userInfo.uniqueIduserInfo.uniqueId elementReference information about the userInfo.uniqueId element.DescriptionUser's unique identifier.ValuesInteger UUIDA value of -99999 means that a unique ID is not available.For events generated by Security Access Manager, the unique ID is not available and is always set to 0. When using the distributed session cache component of Security Access Manager, the unique ID is always set to -99999.XPathCommonBaseEvent/extendedDataElements[@name='userInfo']/children [@name='uniqueId']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInfo.uniqueId

Reference information about the userInfo.uniqueId element.

Description

User's unique identifier.

Values

Integer UUID

A value of -99999 means that a unique ID is not available.

For events generated by Security Access Manager, the unique ID is not available and is always set to 0. When using the distributed session cache component of Security Access Manager, the unique ID is always set to -99999.

XPath

CommonBaseEvent/extendedDataElements[@name='userInfo']/children
[@name='uniqueId']/values

Parent topic: Reference information about elements and element types

userInputsuserInputs elementReference information about the userInputs element.DescriptionA container for information about the user inputs that are related to the work item. The inputs are collected as a list of attributes. For example, for approval and reject, one attribute could be the comment.This element uses the children of the attributeType element:attributeType.nameattributeType.sourceattributeType.valueXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

userInputs

Reference information about the userInputs element.

Description

A container for information about the user inputs that are related to the work item. The inputs are collected as a list of attributes. For example, for approval and reject, one attribute could be the comment.

This element uses the children of the attributeType element:

attributeType.name

attributeType.source

attributeType.value

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

violationClassificationviolationClassification elementReference information about the violationClassification element.DescriptionIdentifies the type of violation.ValuesStringThe following strings suggested values:accountGeneric classification for policy violations related to an account, or attributes associated with an account, that does not fit in one of the specific account violation classifications.accountDisallowedAccount was disallowed. Example: Guest accounts could be forbidden.aclRestrictionThe authorization settings on a protected resource violate the policy. Example: The ACL settings on the executables for a Web server might be improperly set.antiVirusThe proper antivirus protection is not in place. Example: Versionx.y of antivirus product ABC may be required, or the antivirus scan must be configured to run at least once per week.auditThe audit settings on a system may not comply with the policy. Example: The policy may require that all failed authentication attempts be audited. If audit settings do not comply, a violation is logged.netConfigNetwork configuration settings are not set as required by the policy. Example: The -s option must be specified when using the netlsd daemon in AIX.passwordThe password policy is not being adhered to. Example: All passwords must be 8 characters or longer.prohibitedServiceCertain services might be prohibited. Example: Policy may require that TFTP never be active on a system.softwareVersionPolicy may require that specific versions of software be installed. Example: A down-level version of Microsoft IIS or a version that requires a patch might be installed on a production server.sysConfigSystem configuration settings are not set as required by the policy. Example: Certain system log files may be required to exist.XPathCommonBaseEvent/extendedDataElements[@name='violationClassification']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

violationClassification

Reference information about the violationClassification element.

Description

Identifies the type of violation.

Values

String

The following strings suggested values:

account

Generic classification for policy violations related to an account, or attributes associated with an account, that does not fit in one of the specific account violation classifications.

accountDisallowed

Account was disallowed. Example: Guest accounts could be forbidden.

aclRestriction

The authorization settings on a protected resource violate the policy. Example: The ACL settings on the executables for a Web server might be improperly set.

antiVirus

The proper antivirus protection is not in place. Example: Versionx.y of antivirus product ABC may be required, or the antivirus scan must be configured to run at least once per week.

audit

The audit settings on a system may not comply with the policy. Example: The policy may require that all failed authentication attempts be audited. If audit settings do not comply, a violation is logged.

netConfig

Network configuration settings are not set as required by the policy. Example: The -s option must be specified when using the netlsd daemon in AIX.

password

The password policy is not being adhered to. Example: All passwords must be 8 characters or longer.

prohibitedService

Certain services might be prohibited. Example: Policy may require that TFTP never be active on a system.

softwareVersion

Policy may require that specific versions of software be installed. Example: A down-level version of Microsoft IIS or a version that requires a patch might be installed on a production server.

sysConfig

System configuration settings are not set as required by the policy. Example: Certain system log files may be required to exist.

XPath

CommonBaseEvent/extendedDataElements[@name='violationClassification']/values

Parent topic: Reference information about elements and element types

violationDescriptionviolationDescription elementReference information about the violationDescription element.DescriptionPredefined description of the particular violation.ValuesStringAny string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='violationDescription']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

violationDescription

Reference information about the violationDescription element.

Description

Predefined description of the particular violation.

Values

String

Any string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='violationDescription']/values

Parent topic: Reference information about elements and element types

violationNameviolationName elementReference information about the violationName element.DescriptionName of specific policy violation. Example: Win2K Guest Account Restriction.ValuesStringAny string allowed by the application.XPathCommonBaseEvent/extendedDataElements[@name='violationName']/valuesReference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

violationName

Reference information about the violationName element.

Description

Name of specific policy violation. Example: "Win2K Guest Account Restriction".

Values

String

Any string allowed by the application.

XPath

CommonBaseEvent/extendedDataElements[@name='violationName']/values

Parent topic: Reference information about elements and element types

workItemInfoworkItemInfo elementReference information about the workItemInfo element.DescriptionAn element type that represents information about a work item used in events related to workflow operations.This container uses the children of workItemInfoType:workItemInfoType.idworkItemInfoType.typeXPathNo valid XPath for the shredder configuration file. A valid XPath requires a values declaration.Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

workItemInfo

Reference information about the workItemInfo element.

Description

An element type that represents information about a work item used in events related to workflow operations.

This container uses the children of workItemInfoType:

workItemInfoType.id

workItemInfoType.type

XPath

No valid XPath for the shredder configuration file. A valid XPath requires a values declaration.

Parent topic: Reference information about elements and element types

workItemInfoType.id elementworkItemInfoType.id elementReference information about the workItemInfoType.id element.DescriptionUnique identifier of the work item.ValuesStringXPathCommonBaseEvent/extendedDataElements[@name='workItemInfoType']/children [@name='id']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

workItemInfoType.id element

Reference information about the workItemInfoType.id element.

Description

Unique identifier of the work item.

Values

String

XPath

CommonBaseEvent/extendedDataElements[@name='workItemInfoType']/children
[@name='id']/values

Parent topic: Reference information about elements and element types

workItemInfoType.type elementworkItemInfoType.type elementReference information about the workItemInfoType.type element.DescriptionType of the work item.ValuesStringThe following strings are suggested values:approvalThis type of work item allows a user to either approve or reject a specific request.requestForInfoThis type of work item allows a user to provide additional information for a specific request.workOrderThis type of work item is used to request manual operations for the user. For example, a work order to manually create a specific account on a resource.XPathCommonBaseEvent/extendedDataElements[@name='workItemInfoType']/children [@name='type']/values Reference information about elements and element typesThis section defines the various elements and element types that are available for the common audit event types.

workItemInfoType.type element

Reference information about the workItemInfoType.type element.

Description

Type of the work item.

Values

String

The following strings are suggested values:

approval

This type of work item allows a user to either approve or reject a specific request.

requestForInfo

This type of work item allows a user to provide additional information for a specific request.

workOrder

This type of work item is used to request manual operations for the user. For example, a work order to manually create a specific account on a resource.

XPath

CommonBaseEvent/extendedDataElements[@name='workItemInfoType']/children
[@name='type']/values

Parent topic: Reference information about elements and element types

Routing filesrouting filesmessagesrouting filestracesoverviewfilesroutingRouting files are ASCII files that you can use to customize the logging events for C language-based servers, daemons, and other C-language programs and applications. You can use the contents of routing files to control aspects of event logging, such as: Whether to enable logging for specific event classesWhere to direct the output for each event classHow many log files to use for each event classHow large each log file can be for each event classAuditingThe IBM Security Access Manager provides information about configuring and managing audit events.Locations of routing filesRouting file entries

Routing files

Routing files are ASCII files that you can use to customize the logging events for C language-based servers, daemons, and other C-language programs and applications. You can use the contents of routing files to control aspects of event logging, such as:

Whether to enable logging for specific event classes

Where to direct the output for each event class

How many log files to use for each event class

How large each log file can be for each event class

Locations of routing files

Routing file entries

Parent topic: Auditing

Locations of routing filesrouting fileslocationsTable 1 lists the default locations for the routing files. The routing and routing.template files are in the same default directory. The routing files control the logging of events. Default locations of routing filesComponentDefault name and location of routing fileRuntime environment Windows%PD_HOME%\etc\routingAIX, Linux, and Solaris/opt/PolicyDirector/etc/routingIf you do not want to modify the default routing file (/etc/routing), you can use the PD_SVC_ROUTING_FILE environment variable to define an alternative routing file. If the file defined by this environment variable does not exist or is not accessible, the default routing file (/etc/routing) is used.Routing files

Locations of routing files

Table 255 lists the default locations for the routing files. The routing and routing.template files are in the same default directory. The routing files control the logging of events.

Table 255. Default locations of routing files

Component
Default name and location of routing file

Runtime environment

Windows

%PD_HOME%\etc\routing

AIX®, Linux, and Solaris

/opt/PolicyDirector/etc/routing

If you do not want to modify the default routing file (/etc/routing), you can use the PD_SVC_ROUTING_FILE environment variable to define an alternative routing file. If the file defined by this environment variable does not exist or is not accessible, the default routing file (/etc/routing) is used.

Parent topic: Routing files

Routing file entriestracesrouting filesrouting filestracesentry formatDISCARD destinationlog eventsDISCARDeventslogsDISCARDFILE destinationlog eventsFILEeventslogsFILESTDERR destinationlog eventsSTDERReventslogsSTDERRSTDOUT destinationlog eventsSTDOUTeventslogsSTDOUTTEXTFILE destinationlog eventsTEXTFILEeventslogsTEXTFILEUTF8FILE destinationlog eventsUTF8FILEeventslogsUTF8FILEXMLFILE destinationlog eventsXMLFILEeventslogsXMLFILEXMLSTDERR destinationlog eventsXMLSTDERReventslogsXMLSTDERRXMLSTDOUT destinationlog eventsXMLSTDOUTeventslogsXMLSTDOUTGOESTO destinationlog eventsGOESTOeventslogsGOESTOEach routing file contains entries that control the logging of events. Use the following format (entered on a single line without spaces) when you define entries in routing files:component:subcomponent.level[[,subcomponent.level]...] :destination:location [[;destination:location]...] [;GOESTO:{other_severity | other_component}]Where: component:subcomponent [[,subcomponent ]...]Specifies the component, subcomponents, and reporting levels of events to log. For the component portion, you can specify an asterisk (*) to log data for all components. For the subcomponent portion, you can specify an asterisk (*) to log data for all subcomponents of the specified component.destinationSpecifies where to log the events. For each destination, you must specify a location. When you specify multiple destination-location pairs, separate each pair with a semicolon (;). The following destinations are valid: DISCARDDiscards the events.FILEWrites the events as ASCII text in the current code page and locale to the specified location. When you use this destination on the appliance, do not include any path information.. Optionally, you can follow the FILE destination by a period and two numbers that are separated by a period (for example, FILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only 1 log file that grows without limit.The average size of an ASCII event is 200 bytes. Because the maximum size of a log file is 2 GB, the maximum number of events must be limited to approximately 10,000,000 events.STDERRWrites the events as ASCII text in the current code page and locale to the standard error device.STDOUTWrites the events as ASCII text in the current code page and locale to the standard output device.TEXTFILESame a FILE.UTF8FILEWrites the events as UTF-8 text to the specified location. When you use this destination, do not include any path information. Optionally, you can follow the UTF8FILE destination by a period and two numbers that are separated by a period (for example, UTF8FILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only 1 log file that grows without limit. The average size of a UTF-8 event is 200 bytes. Because the maximum size of a log file is 2 GB, the maximum number of events must be limited to approximately 10,000,000 events.When the operating system does not use a UTF-8 code page, the conversion to UTF-8 can result in data loss. When data loss occurs, the log file contains a series of question mark (?) characters at the location where the data conversion was problematic.XMLFILEWrites events to the specified location in the XML log format. When you use this destination, do not include any path information. Optionally, you can follow the XMLFILE destination by a period and two numbers that are separated by a period (for example, XMLFILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only 1 log file that grows without limit. The maximum size of a log file is 2 GB.XMLSTDERRWrites events to the standard error device in the XML log format.XMLSTDOUTWrites events to the standard output device in the XML log format.GOESTO:{other_severity | other_component}]Specifies that events must additionally be routed to the same destination and location as events of the specified component.locationSpecifies the name and location of the log file. When the destination is TEXT, TEXTFILE, UTF8FILE or XMLFILE, you must specify a location. When the destination is DISCARD, STDERR, STDOUT, XMLSTDERR, or XMLSTDOUT, you must specify a hyphen (-). When you specify a fully qualified file name, you can use the %ld character string to insert the process ID into the file name. When the number of files is specified as part of the destination, a period and the file number are appended to the specified log file. On Windows operating systems, the file name must not end with a period. If the file name ends with a period, when the file number is appended, the file name contains two consecutive periods. File names with two consecutive periods are not valid. On AIX, Linux, and Solaris operating systems, the file name must be followed by: File permissions.The user who owns the file.The group that owns the file. Use the following format: location:permissions:owner:groupRouting files

Routing file entries

Each routing file contains entries that control the logging of events. Use the following format (entered on a single line without spaces) when you define entries in routing files:

component:subcomponent.level[[,subcomponent.level]...] :destination:location [[;destination:location]...] [;GOESTO:{other_severity | other_component}]

Where:

component:subcomponent [[,subcomponent ]...]

Specifies the component, subcomponents, and reporting levels of events to log.

For the component portion, you can specify an asterisk (*) to log data for all components.

For the subcomponent portion, you can specify an asterisk (*) to log data for all subcomponents of the specified component.

destination

Specifies where to log the events. For each destination, you must specify a location. When you specify multiple destination-location pairs, separate each pair with a semicolon (;). The following destinations are valid:

DISCARD

Discards the events.

FILE

Writes the events as ASCII text in the current code page and locale to the specified location.

When you use this destination on the appliance, do not include any path information.. Optionally, you can follow the FILE destination by a period and two numbers that are separated by a period (for example, FILE.10.100).

The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only 1 log file that grows without limit.

The average size of an ASCII event is 200 bytes. Because the maximum size of a log file is 2 GB, the maximum number of events must be limited to approximately 10,000,000 events.

STDERR

Writes the events as ASCII text in the current code page and locale to the standard error device.

STDOUT

Writes the events as ASCII text in the current code page and locale to the standard output device.

TEXTFILE

Same a FILE.

UTF8FILE

Writes the events as UTF-8 text to the specified location.

When you use this destination, do not include any path information. Optionally, you can follow the UTF8FILE destination by a period and two numbers that are separated by a period (for example, UTF8FILE.10.100).

The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only 1 log file that grows without limit.

The average size of a UTF-8 event is 200 bytes. Because the maximum size of a log file is 2 GB, the maximum number of events must be limited to approximately 10,000,000 events.

Note: When the operating system does not use a UTF-8 code page, the conversion to UTF-8 can result in data loss. When data loss occurs, the log file contains a series of question mark (?) characters at the location where the data conversion was problematic.

XMLFILE

Writes events to the specified location in the XML log format.

When you use this destination, do not include any path information. Optionally, you can follow the XMLFILE destination by a period and two numbers that are separated by a period (for example, XMLFILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain.

If you do not specify these values, there is only 1 log file that grows without limit.

The maximum size of a log file is 2 GB.

XMLSTDERR

Writes events to the standard error device in the XML log format.

XMLSTDOUT

Writes events to the standard output device in the XML log format.

GOESTO:{other_severity | other_component}]

Specifies that events must additionally be routed to the same destination and location as events of the specified component.

location

Specifies the name and location of the log file. When the destination is TEXT, TEXTFILE, UTF8FILE or XMLFILE, you must specify a location. When the destination is DISCARD, STDERR, STDOUT, XMLSTDERR, or XMLSTDOUT, you must specify a hyphen (-).

When you specify a fully qualified file name, you can use the %ld character string to insert the process ID into the file name.

When the number of files is specified as part of the destination, a period and the file number are appended to the specified log file.

Note: On Windows operating systems, the file name must not end with a period. If the file name ends with a period, when the file number is appended, the file name contains two consecutive periods. File names with two consecutive periods are not valid.

On AIX, Linux, and Solaris operating systems, the file name must be followed by:

File permissions.

The user who owns the file.

The group that owns the file.

Use the following format:

location:permissions:owner:group

Parent topic: Routing files

Configuration stanzasconfigurationstanzasThis appendix describes the guidelines for changing the following files:Configuration files.The location of the configuration files.The contents of the configuration files.These files are used for auditing and statistic gathering purposes.AuditingThe IBM Security Access Manager provides information about configuring and managing audit events.Guidelines for changing configuration filesConfiguration file referenceConfiguration file stanza reference

Configuration stanzas

This appendix describes the guidelines for changing the following files:

Configuration files.

The location of the configuration files.

The contents of the configuration files.

These files are used for auditing and statistic gathering purposes.

Guidelines for changing configuration files

Configuration file reference

Configuration file stanza reference

Parent topic: Auditing

Guidelines for changing configuration filesThese guidelines are provided to help you update the Security Access Manager configuration files. The guidelines are divided into the following categories: Configuration stanzasGeneral guidelinesDefault valuesStringsDefined stringsFile namesIntegersBoolean values

Guidelines for changing configuration files

These guidelines are provided to help you update the Security Access Manager configuration files. The guidelines are divided into the following categories:

General guidelines

Default values

Strings

Defined strings

File names

Integers

Boolean values

Parent topic: Configuration stanzas

General guidelinesconfigurationfilesguidelinesUse the following general guidelines when you change the configuration settings:There is no order dependency or location dependency for stanzas in any configuration file.Stanza entries are marked as required or optional. When an entry is required, the entry must contain a valid key and value.Do not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results for the servers.Stanza entries and key names are case-sensitive. For example, usessl and UseSSL are treated as different entries.Spaces are not allowed for names of keys.For the key value pair format of key = value, the spaces that surround the equal sign (=) are not required.Non-printable characters (such as tabs, carriage returns, and line feeds) that occur at the end of a stanza entry are ignored. Non-printable characters are ASCII characters with a decimal value less than 32.Guidelines for changing configuration files

General guidelines

Use the following general guidelines when you change the configuration settings:

There is no order dependency or location dependency for stanzas in any configuration file.

Stanza entries are marked as required or optional. When an entry is required, the entry must contain a valid key and value.

Do not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results for the servers.

Stanza entries and key names are case-sensitive. For example, usessl and UseSSL are treated as different entries.

Spaces are not allowed for names of keys.

For the key value pair format of key = value, the spaces that surround the equal sign (=) are not required.

Non-printable characters (such as tabs, carriage returns, and line feeds) that occur at the end of a stanza entry are ignored. Non-printable characters are ASCII characters with a decimal value less than 32.

Parent topic: Guidelines for changing configuration files

Default valuesconfigurationfilesvalues, defaultUse the following guidelines when you change default configuration settings: Many values are created or modified only by using configuration programs. Do not manually edit these stanzas or values.Some values are added automatically during configuration. These values are needed for the initialization of the server after the configuration.The default values for a stanza entry might be different, depending on the server configuration. Some key value pairs are not applicable to certain servers and are omitted from the default configuration file for this server.Guidelines for changing configuration files

Default values

Use the following guidelines when you change default configuration settings:

Many values are created or modified only by using configuration programs. Do not manually edit these stanzas or values.

Some values are added automatically during configuration. These values are needed for the initialization of the server after the configuration.

The default values for a stanza entry might be different, depending on the server configuration. Some key value pairs are not applicable to certain servers and are omitted from the default configuration file for this server.

Parent topic: Guidelines for changing configuration files

Stringsconfigurationfilesstring valuesSome values accept a string value. When you manually edit the configuration file, use the following guidelines to change configuration settings that require a string: String values are expected to be characters that are part of the local code set.Additional or different restrictions on the set of allowable string characters might be imposed. For example, many strings are restricted to ASCII characters. Consult each stanza entry description for any restrictions.Double quotation marks are sometimes, but not always, required when you use spaces or more than one word for values. See the descriptions or examples for each stanza entry when in doubt.The minimum and maximum lengths of user registry-related string values, if there are limits, are imposed by the underlying registry. For example, for Active Directory the maximum length is 256 alphanumeric characters.Guidelines for changing configuration files

Strings

Some values accept a string value. When you manually edit the configuration file, use the following guidelines to change configuration settings that require a string:

String values are expected to be characters that are part of the local code set.

Additional or different restrictions on the set of allowable string characters might be imposed. For example, many strings are restricted to ASCII characters. Consult each stanza entry description for any restrictions.

Double quotation marks are sometimes, but not always, required when you use spaces or more than one word for values. See the descriptions or examples for each stanza entry when in doubt.

The minimum and maximum lengths of user registry-related string values, if there are limits, are imposed by the underlying registry. For example, for Active Directory the maximum length is 256 alphanumeric characters.

Parent topic: Guidelines for changing configuration files

Defined stringsconfigurationfilesdefined stringsSome values accept a string value, but the value must be a set of defined strings. When you manually edit the configuration file, make sure that the string value you type matches one of the valid defined strings values.For example, the [aznapi-configuration] stanza section contains the following entry: mode = {local|remote}The value for mode is expected to be local or remote. Any other value is invalid and results in an error.Guidelines for changing configuration files

Defined strings

Some values accept a string value, but the value must be a set of defined strings. When you manually edit the configuration file, make sure that the string value you type matches one of the valid defined strings values.

For example, the [aznapi-configuration] stanza section contains the following entry:

mode = {local|remote}

The value for mode is expected to be local or remote. Any other value is invalid and results in an error.

Parent topic: Guidelines for changing configuration files

File namesconfigurationfilesnamesSome values are file names. For each stanza entry that expects a file name as a value, the description of the stanza entry specifies which of the following constructs are valid: FilenameNo directory path included.Relative filenameA directory path is allowed but not mandatory. These files typically are expected to be located relative to the location of a standard Security Access Manager directory. The stanza entry for each relative path name lists the root directory to which the file name is relative.Fully qualified absolute pathAn absolute directory path is required.Some stanza entries allow more than one of the file name choices.The set of characters that is permitted in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks (").Guidelines for changing configuration files

File names

Some values are file names. For each stanza entry that expects a file name as a value, the description of the stanza entry specifies which of the following constructs are valid:

Filename

No directory path included.

Relative filename

A directory path is allowed but not mandatory.

These files typically are expected to be located relative to the location of a standard Security Access Manager directory. The stanza entry for each relative path name lists the root directory to which the file name is relative.

Fully qualified absolute path

An absolute directory path is required.

Some stanza entries allow more than one of the file name choices.

The set of characters that is permitted in a file name can be determined by the file system and by the local code set. For Windows operating systems, file names cannot have a backward slash (\), a colon (:), a question mark (?), or double quotation marks (").

Parent topic: Guidelines for changing configuration files

Integersconfigurationfilesinteger valuesMany stanza entries expect the value for the entry to be expressed as an integer. When you define an entry with an integer, consider the following guidelines: Stanza entries that take an integer value expect integer values within a valid range. The range is described in terms of a minimum value and a maximum value. For example, in the [ivmgrd] stanza, the max-notifier-thread stanza entry has a minimum value of 1 second and a maximum value of 128 threads. For some entries, the integer value must be positive, and the minimum value is 1. For other entries, a minimum integer value of 0 is allowed. Use caution when you set an integer value to 0. For example, an integer value of 0 might disable the function that is controlled by that stanza entry. For example, in the [ivacld] stanza, the entry tcp-req-port = 0 disables the port number. Or, an integer value of 0 might indicate that the number is unlimited. For example, in the [ldap] stanza, the entry max-search-size = 0 means that there is no limit to the maximum search size.For some entries that require integer values, Security Access Manager does not impose an upper limit for the maximum number allowed. For example, there is typically no maximum for timeout-related values, such as timeout = number in the [ldap] stanza. For this type of entry, the maximum number is limited only by the size of memory that is allocated for an integer data type. This number can vary, based on the type of operating system. For systems that allocate 4 bytes for an integer, this value is 2147483647. However, as the administrator, use a number that represents the value that is most logical for the value you are trying to set.Guidelines for changing configuration files

Integers

Many stanza entries expect the value for the entry to be expressed as an integer. When you define an entry with an integer, consider the following guidelines:

Stanza entries that take an integer value expect integer values within a valid range. The range is described in terms of a minimum value and a maximum value.

For example, in the [ivmgrd] stanza, the max-notifier-thread stanza entry has a minimum value of 1 second and a maximum value of 128 threads.

For some entries, the integer value must be positive, and the minimum value is 1. For other entries, a minimum integer value of 0 is allowed.

Use caution when you set an integer value to 0. For example, an integer value of 0 might disable the function that is controlled by that stanza entry. For example, in the [ivacld] stanza, the entry tcp-req-port = 0 disables the port number. Or, an integer value of 0 might indicate that the number is unlimited. For example, in the [ldap] stanza, the entry max-search-size = 0 means that there is no limit to the maximum search size.

For some entries that require integer values, Security Access Manager does not impose an upper limit for the maximum number allowed. For example, there is typically no maximum for timeout-related values, such as timeout = number in the [ldap] stanza.

For this type of entry, the maximum number is limited only by the size of memory that is allocated for an integer data type. This number can vary, based on the type of operating system. For systems that allocate 4 bytes for an integer, this value is 2147483647.

However, as the administrator, use a number that represents the value that is most logical for the value you are trying to set.

Parent topic: Guidelines for changing configuration files

Boolean valuesconfigurationfilesBoolean valuesMany stanza entries represent a Boolean value. Security Access Manager recognizes the Boolean values yes and no.Some of the entries in the configuration files are read by other servers and utilities. For example, many entries in the [ldap] stanza are read by the LDAP client. Some of these other programs recognize more Boolean characters: yes or trueno or falseAnything other than yes|true, including a blank value, is interpreted as no|false.The recognized Boolean entries are listed for each stanza entry. See the individual descriptions to determine when true or false are also recognized.Guidelines for changing configuration files

Boolean values

Many stanza entries represent a Boolean value. Security Access Manager recognizes the Boolean values yes and no.

Some of the entries in the configuration files are read by other servers and utilities. For example, many entries in the [ldap] stanza are read by the LDAP client. Some of these other programs recognize more Boolean characters:

yes or true

no or false

Anything other than yes|true, including a blank value, is interpreted as no|false.

The recognized Boolean entries are listed for each stanza entry. See the individual descriptions to determine when true or false are also recognized.

Parent topic: Guidelines for changing configuration files

Configuration file referenceconfigurationfilesreferenceThe operation of the Security Access Manager server is controlled by using configuration files. Each configuration file contains sections that are called stanzas.Server configuration files are ASCII text-based and contain stanza entries. Configuration files are processed only when the servers start.Configuration stanzasLocation of configuration filesContents of configuration files

Configuration file reference

The operation of the Security Access Manager server is controlled by using configuration files. Each configuration file contains sections that are called stanzas.

Server configuration files are ASCII text-based and contain stanza entries. Configuration files are processed only when the servers start.

Location of configuration files

Contents of configuration files

Parent topic: Configuration stanzas

Location of configuration filesconfigurationfileslocation, defaultfilesconfigurationdefault locationThis section provides information about the server-specific location of the configuration files.Configuration file referenceSecurity Access Manager runtime

Location of configuration files

This section provides information about the server-specific location of the configuration files.

Security Access Manager runtime

Parent topic: Configuration file reference

Security Access Manager runtimeruntime configuration file locationIf you installed Security Access Manager in the default directories, the configuration files for the runtime are in one of the following platform-specific directories: AIX, Linux, and Solaris operating systems/opt/PolicyDirector/etcWindows operating systemsC:\Program Files\Tivoli\Policy Director\etcLocation of configuration files

Security Access Manager runtime

If you installed Security Access Manager in the default directories, the configuration files for the runtime are in one of the following platform-specific directories:

AIX, Linux, and Solaris operating systems

/opt/PolicyDirector/etc

Windows operating systems

C:\Program Files\Tivoli\Policy Director\etc

Parent topic: Location of configuration files

Contents of configuration filesThis section provides information about the stanzas and stanza entries in the available configuration files. The configuration files are used for auditing and statistic gathering purposes.Configuration file referenceSecurity Access Manager configuration files

Contents of configuration files

This section provides information about the stanzas and stanza entries in the available configuration files. The configuration files are used for auditing and statistic gathering purposes.

Security Access Manager configuration files

Parent topic: Configuration file reference

Security Access Manager configuration filesconfigurationfilesserver contentWithin the configuration files for the Security Access Manager servers, you can define auditing and statistics characteristics. All C-based servers have the [aznapi-configuration] stanza, and WebSEAL has an additional [logging] stanza.Contents of configuration files

Security Access Manager configuration files

Within the configuration files for the Security Access Manager servers, you can define auditing and statistics characteristics. All C-based servers have the [aznapi-configuration] stanza, and WebSEAL has an additional [logging] stanza.

Parent topic: Contents of configuration files

Configuration file stanza referenceconfigurationstanzasstanzasgeneral formatWithin configuration files, stanza labels are shown within brackets, such as [stanza-name]. For example, the [ssl] stanza in the ivmgrd.conf configuration file defines the Secure Sockets Layer (SSL) configuration settings for the policy server. The [ldap] stanza defines the configuration settings that are required by the policy server to communicate with an LDAP-based user registry.Each stanza in a Security Access Manager configuration file contains one or more key value pairs, which contain information that is expressed as a paired set of parameters. Each stanza entry is a key-value pair in the following format: key = valueYou must not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results in the servers. The spaces that surround the equal sign (=) are not required.The initial installation of Security Access Manager establishes many of the default values. Some values are static and never change; other values can be modified to customize server functionality and performance.The following stanza descriptions provide a list of the valid stanza entries. Each stanza entry consists of key value pairs. Each stanza entry includes a description of its default behavior, when applicable.Configuration stanzas[aznapi-configuration] stanza[logging] stanza[pdaudit-filter] stanza

Configuration file stanza reference

Within configuration files, stanza labels are shown within brackets, such as [stanza-name]. For example, the [ssl] stanza in the ivmgrd.conf configuration file defines the Secure Sockets Layer (SSL) configuration settings for the policy server. The [ldap] stanza defines the configuration settings that are required by the policy server to communicate with an LDAP-based user registry.

Each stanza in a Security Access Manager configuration file contains one or more key value pairs, which contain information that is expressed as a paired set of parameters. Each stanza entry is a key-value pair in the following format:

key = value

You must not change the names of the keys in the configuration files. Changing the name of the key might cause unpredictable results in the servers. The spaces that surround the equal sign (=) are not required.

The initial installation of Security Access Manager establishes many of the default values. Some values are static and never change; other values can be modified to customize server functionality and performance.

The following stanza descriptions provide a list of the valid stanza entries. Each stanza entry consists of key value pairs. Each stanza entry includes a description of its default behavior, when applicable.

[aznapi-configuration] stanza

[logging] stanza

[pdaudit-filter] stanza

Parent topic: Configuration stanzas

[aznapi-configuration] stanzastanzasaznapi-configurationaznapi-configuration stanzadescriptionThe stanza entries for native Security Access Manager auditing and statistics gathering are in the [aznapi-configuration] stanza of the server-specific configuration file. The [aznapi-configuration] stanza contains more entries than the ones that are listed. For a complete list of entries that can be used in the server-specific configuration files, see the administration guide for that server or plug-in.Configuration file stanza referencelogcfg

[aznapi-configuration] stanza

The stanza entries for native Security Access Manager auditing and statistics gathering are in the [aznapi-configuration] stanza of the server-specific configuration file. The [aznapi-configuration] stanza contains more entries than the ones that are listed. For a complete list of entries that can be used in the server-specific configuration files, see the administration guide for that server or plug-in.

logcfg

Parent topic: Configuration file stanza reference

logcfglogcfg entryaznapi-configuration stanzaentrieslogcfgaznapi-configuration stanzaaznapi-configuration stanzalogcfg entrySyntax logcfg = category:[log-agent][[parameter[=value]] ...]Description Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events. Each server provides its own event logging setting in its corresponding configuration file.Options category:log-agentThe category of the auditing event and the destination. log-agent is one of the following agents: stdoutstderrfile path=piperemoteparameter=valueAllowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing you want to perform. See Audit event loggingTo enable logging, define entries in the configuration file. for information about the log agents and the configuration parameters. Each log agent supports different parameters.Usage OptionalDefault value Remove the pound signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application.Example logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log[aznapi-configuration] stanza

logcfg

Syntax

logcfg = category:[log-agent][[parameter[=value]] ...]

Description

Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events.

Each server provides its own event logging setting in its corresponding configuration file.

Options

category:log-agent

The category of the auditing event and the destination. log-agent is one of the following agents:

stdout

stderr

file path=

pipe

remote

parameter=value

Allowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing you want to perform.

See Audit event logging for information about the log agents and the configuration parameters. Each log agent supports different parameters.

Usage

Optional

Default value

Remove the pound signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application.

Example

logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log

Parent topic: [aznapi-configuration] stanza

[logging] stanzalogging stanzadescriptionstanzasloggingThe [logging] stanza contains the configuration details for logging HTTP audit events for WebSEAL servers. WebSEAL can be configured to maintain the following HTTP activities: agentsreferersrequestersThe [logging] stanza is in the WebSEAL webseald.conf configuration file. Assume that the configuration file contains auditing entries in both the [aznapi-configuration] stanza and the [logging] stanza. Then, the logging details in the [aznapi-configuration] stanza take precedence over repeated details in the [logging] stanza.For details about WebSEAL event processing, see Process flow for logcfg loggingThe following example process flow assumes the [aznapi-configuration] stanza of a WebSEAL configuration file. . For information about the [aznapi-configuration] stanza entries in the WebSEAL webseald.conf configuration file, see the Stanza Reference topics in the IBM Knowledge Center.Configuration file stanza referenceabsolute-uri-in-request-logagentsagents-fileconfig-data-logflush-timegmt-timehost-header-in-request-log (deprecated)max-sizereferersreferers-filerequestsrequests-fileserver-log

[logging] stanza

The [logging] stanza contains the configuration details for logging HTTP audit events for WebSEAL servers. WebSEAL can be configured to maintain the following HTTP activities:

agents

referers

requesters

The [logging] stanza is in the WebSEAL webseald.conf configuration file. Assume that the configuration file contains auditing entries in both the [aznapi-configuration] stanza and the [logging] stanza. Then, the logging details in the [aznapi-configuration] stanza take precedence over repeated details in the [logging] stanza.

For details about WebSEAL event processing, see Process flow for logcfg logging. For information about the [aznapi-configuration] stanza entries in the WebSEAL webseald.conf configuration file, see the Stanza Reference topics in the IBM® Knowledge Center.

absolute-uri-in-request-log

agents

agents-file

config-data-log

flush-time

gmt-time

host-header-in-request-log (deprecated)

max-size

referers

referers-file

requests

requests-file

server-log

Parent topic: Configuration file stanza reference

absolute-uri-in-request-logabsolute-uri-in-request-log stanza entrylogging stanzaentriesabsolute-uri-in-request-log logging stanzaabsolute-uri-in-request-log entrySyntax absolute-uri-in-request-log = {yes|no} Description Logs the absolute URI in the HTTP audit records. Adds protocol and host to the path. Options yesLog the absolute URI.noDo not log the absolute URI. Usage This stanza entry is required. Default value no Example absolute-uri-in-request-log = no [logging] stanza

absolute-uri-in-request-log

Syntax

absolute-uri-in-request-log = {yes|no}

Description

Logs the absolute URI in the HTTP audit records. Adds protocol and host to the path.

Options

yes

Log the absolute URI.

no

Do not log the absolute URI.

Usage

This stanza entry is required.

Default value

no

Example

absolute-uri-in-request-log = no

Parent topic: [logging] stanza

agentsagentslogging stanza entryentriesagentslogging stanzaagents entrySyntax agents = {yes|no} Description Enables or disables the agents log. This log records the contents of the User_Agent: header of each HTTP request. Options yesThe value yes enables logging for the agents.noThe value no disables logging for the agents. Usage This stanza entry is required. Default value yes Example agents = yes [logging] stanza

agents

Syntax

agents = {yes|no}

Description

Enables or disables the agents log. This log records the contents of the User_Agent: header of each HTTP request.

Options

yes

The value yes enables logging for the agents.

no

The value no disables logging for the agents.

Usage

This stanza entry is required.

Default value

yes

Example

agents = yes

Parent topic: [logging] stanza

agents-fileentriesagents-filelogging stanzaagents-file entrySyntax agents-file = file_name Description Fully qualified path to the agents log file. Options file_nameName of the agents log file. Usage This stanza entry is required. Default value The default location is agent.log, located under the WebSEAL installation directory. Example Example on AIX, Linux, and Solaris: agents-file = agent.log [logging] stanza

agents-file

Syntax

agents-file = file_name

Description

Fully qualified path to the agents log file.

Options

file_name

Name of the agents log file.

Usage

This stanza entry is required.

Default value

The default location is agent.log, located under the WebSEAL installation directory.

Example

Example on AIX®, Linux, and Solaris:

agents-file = agent.log

Parent topic: [logging] stanza

config-data-logconfig-data-log stanza entrylogging stanzaentriesconfig-data-loglogging stanzaconfig-data-log entrySyntax config-data-log = fully_qualified_path Description Fully qualified path to the configuration data log file. Options fully_qualified_pathFully qualified path to the configuration data log file. Usage This stanza entry is required. Default value The default location is log/config_data.log, located under the WebSEAL installation directory. Example Example on AIX, Linux, and Solaris: config-data-log = /var/pdweb/log/config_data.log [logging] stanza

config-data-log

Syntax

config-data-log = fully_qualified_path

Description

Fully qualified path to the configuration data log file.

Options

fully_qualified_path

Fully qualified path to the configuration data log file.

Usage

This stanza entry is required.

Default value

The default location is log/config_data.log, located under the WebSEAL installation directory.

Example

Example on AIX®, Linux, and Solaris:

config-data-log = /var/pdweb/log/config_data.log

Parent topic: [logging] stanza

flush-timeflush-time stanza entrylogging stanzaentriesflush-timelogging stanzaflush-time entrySyntax flush-time = number_of_seconds Description Integer value that indicates the frequency, in seconds, to force a flush of log buffers. Options number_of_secondsInteger value that indicates the frequency, in seconds, to force a flush of log buffers. The minimum value is 1 second. The maximum value is 600 seconds. Usage This stanza entry is optional. Default value 20 Example flush-time = 20 [logging] stanza

flush-time

Syntax

flush-time = number_of_seconds

Description

Integer value that indicates the frequency, in seconds, to force a flush of log buffers.

Options

number_of_seconds

Integer value that indicates the frequency, in seconds, to force a flush of log buffers. The minimum value is 1 second. The maximum value is 600 seconds.

Usage

This stanza entry is optional.

Default value

20

Example

flush-time = 20

Parent topic: [logging] stanza

gmt-timegmt-time stanza entryentriesgmt-timelogging stanzagmt-time entrySyntax gmt-time = {yes|no} Description Enables or disables logging requests in Greenwich Mean Time (GMT) instead of the local time zone. Options yesA value of yes means to use GMT.no A value of no means to use the local time zone. Usage This stanza entry is required. Default value no Example gmt-time = no [logging] stanza

gmt-time

Syntax

gmt-time = {yes|no}

Description

Enables or disables logging requests in Greenwich Mean Time (GMT) instead of the local time zone.

Options

yes

A value of yes means to use GMT.

no

A value of no means to use the local time zone.

Usage

This stanza entry is required.

Default value

no

Example

gmt-time = no

Parent topic: [logging] stanza

host-header-in-request-log (deprecated)host-header-in-request-log stanza entryentrieshost-header-in-request-loglogging stanzahost-header-in-request-log entrySyntax host-header-in-request-log = {yes|no} Description Log the Host header at the front of each line in the request log and the combined log. Options yesLog the Host header.noDo not log the Host header. Usage This stanza entry is required. Default value no Example host-header-in-request-log = no [logging] stanza

host-header-in-request-log (deprecated)

Syntax

host-header-in-request-log = {yes|no}

Description

Log the Host header at the front of each line in the request log and the combined log.

Options

yes

Log the Host header.

no

Do not log the Host header.

Usage

This stanza entry is required.

Default value

no

Example

host-header-in-request-log = no

Parent topic: [logging] stanza

max-sizemax-size stanza entryentriesmax-sizelogging stanzamax-size entrySyntax max-size = number_of_bytes Description Integer value that indicates the size limit of the log files. This value applies to the request, referrer, and agent logs. The size limit is also known as the rollover threshold. When the log file reaches this threshold, the original log file is renamed, and a new log file with the original name is created. Options number_of_bytes When the value is zero (0), no rollover log file is created. When the value is a negative integer, the logs are rolled over daily, regardless of the size. When the value is a positive integer, the value indicates the maximum size, in bytes, of the log file before the rollover occurs. The allowable range is from 1 byte to 2 MB. Usage This stanza entry is required. Default value 2000000 Example max-size = 2000000 [logging] stanza

max-size

Syntax

max-size = number_of_bytes

Description

Integer value that indicates the size limit of the log files. This value applies to the request, referrer, and agent logs. The size limit is also known as the rollover threshold. When the log file reaches this threshold, the original log file is renamed, and a new log file with the original name is created.

Options

number_of_bytes

When the value is zero (0), no rollover log file is created.

When the value is a negative integer, the logs are rolled over daily, regardless of the size.

When the value is a positive integer, the value indicates the maximum size, in bytes, of the log file before the rollover occurs. The allowable range is from 1 byte to 2 MB.

Usage

This stanza entry is required.

Default value

2000000

Example

max-size = 2000000

Parent topic: [logging] stanza

referersreferers stanza entrylogging stanzaentriesrefererslogging stanzareferers entrySyntax referers = {yes|no}Description Enables or disables the referers log. This log records the Referer: header of each HTTP request. Options yesThe value yes enables referers logging. noThe value no disables referers logging.Usage This stanza entry is required.Default value yesExample referers = yes[logging] stanza

referers

Syntax

referers = {yes|no}

Description

Enables or disables the referers log. This log records the Referer: header of each HTTP request.

Options

yes

The value yes enables referers logging.

no

The value no disables referers logging.

Usage

This stanza entry is required.

Default value

yes

Example

referers = yes

Parent topic: [logging] stanza

referers-filereferers-file stanza entrylogging stanzaentriesreferers-filelogging stanzareferers-file entrySyntax referers-file = file_name Description Name of the referers log file. Options file_nameName of the referers log file. Usage This stanza entry is required. Default value The default location is referer.log, located under the WebSEAL installation directory. Example Example on AIX, Linux, and Solaris: referers-file = referer.log [logging] stanza

referers-file

Syntax

referers-file = file_name

Description

Name of the referers log file.

Options

file_name

Name of the referers log file.

Usage

This stanza entry is required.

Default value

The default location is referer.log, located under the WebSEAL installation directory.

Example

Example on AIX®, Linux, and Solaris:

referers-file = referer.log

Parent topic: [logging] stanza

requestsrequests stanza entryentriesrequestslogging stanzarequests entrySyntax requests = {yes|no} Description Enables or disables the requests log. This log records standard logging of HTTP requests. Options yesThe value yes enables requests logging.noThe value no disables requests logging. Usage This stanza entry is required. Default value yes Example requests = yes [logging] stanza

requests

Syntax

requests = {yes|no}

Description

Enables or disables the requests log. This log records standard logging of HTTP requests.

Options

yes

The value yes enables requests logging.

no

The value no disables requests logging.

Usage

This stanza entry is required.

Default value

yes

Example

requests = yes

Parent topic: [logging] stanza

requests-filerequests-file stanza entryentriesrequests-filelogging stanzarequests-file entrySyntax requests-file = file_name Description Name of the request log file. Options file_nameName of the request log file. Usage This stanza entry is required. Default value The default location is request.log, located under the WebSEAL installation directory. Example Example on AIX, Linux, and Solaris: requests-file = request.log [logging] stanza

requests-file

Syntax

requests-file = file_name

Description

Name of the request log file.

Options

file_name

Name of the request log file.

Usage

This stanza entry is required.

Default value

The default location is request.log, located under the WebSEAL installation directory.

Example

Example on AIX®, Linux, and Solaris:

requests-file = request.log

Parent topic: [logging] stanza

server-logserver-log stanza entrylogging stanzaentriesserver-loglogging stanzaserver-log entrySyntax server-log = file_name Description Name of the server error log file. Options file_nameName of the server error log file. Usage This stanza entry is required. Default value The default location is webseald.log, located under the WebSEAL installation directory. Example Example on AIX, Linux, and Solaris: server-log = msg__webseald.log [logging] stanza

server-log

Syntax

server-log = file_name

Description

Name of the server error log file.

Options

file_name

Name of the server error log file.

Usage

This stanza entry is required.

Default value

The default location is webseald.log, located under the WebSEAL installation directory.

Example

Example on AIX®, Linux, and Solaris:

server-log = msg__webseald.log

Parent topic: [logging] stanza

[pdaudit-filter] stanzapdaudit-filter stanzadescriptionstanzaspdaudit-filterThe stanza entries for native Security Access Manager auditing are in the [pdaudit-filter] stanza of the server-specific pdaudit.conf configuration file. Configuration file stanza referencelogcfg

[pdaudit-filter] stanza

The stanza entries for native Security Access Manager auditing are in the [pdaudit-filter] stanza of the server-specific pdaudit.conf configuration file.

logcfg

Parent topic: Configuration file stanza reference

logcfglogcfg entrypdaudit-filter stanzaentrieslogcfgpdaudit-filter stanzapdaudit-filter stanzalogcfg entrySyntax logcfg = category:[log-agent][[parameter[=value]] ...] Description Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events. Each server provides its own event log setting in its corresponding configuration file. Options category:log-agentThe category of the auditing event and the destination. log-agent is one of the following agents: stdoutstderrfile path=piperemoteparameter=valueAllowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing that you want to complete. See Audit event loggingTo enable logging, define entries in the configuration file. for information about the log agents and the configuration parameters. Each log agent supports different parameters. Usage Optional Default value Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application. Example logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log [pdaudit-filter] stanza

logcfg

Syntax

logcfg = category:[log-agent][[parameter[=value]] ...]

Description

Enables logging and auditing for the application. Category, destination, and other parameters are used to capture Security Access Manager auditing and logging events.

Each server provides its own event log setting in its corresponding configuration file.

Options

category:log-agent

The category of the auditing event and the destination. log-agent is one of the following agents:

stdout

stderr

file path=

pipe

remote

parameter=value

Allowable parameters. The parameters vary, depending on the category, the destination of events, and the type of auditing that you want to complete.

See Audit event logging for information about the log agents and the configuration parameters. Each log agent supports different parameters.

Usage

Optional

Default value

Remove the number signs (#) at the beginning of the configuration file lines to enable authentication or authorization auditing (or both) for the application.

Example

logcfg = audit.azn:file path=audit.log,flush_interval=20,log_id=audit_log

Parent topic: [pdaudit-filter] stanza

Commands and utilitiesThis section provides reference information about the commands and utilities that are used for auditing, statistics gathering, and for viewing and changing entries in configuration files.AuditingThe IBM Security Access Manager provides information about configuring and managing audit events.Reading syntax statementsCommandsloginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. server listLists all registered Security Access Manager servers. server task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances.

Commands and utilities

This section provides reference information about the commands and utilities that are used for auditing, statistics gathering, and for viewing and changing entries in configuration files.

Reading syntax statements

Commands

login
Establishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done.

server list
Lists all registered Security Access Manager servers.

server task stats
Manages the gathering and reporting of statistics for Security Access Manager servers and server instances.

Parent topic: Auditing

Reading syntax statementssyntax, readThe reference documentation uses the following special characters to define syntax: [ ]Identifies optional options. Options that are not enclosed in brackets are required....Indicates that you can specify multiple values for the previous option.|Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.{ }Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).\Indicates that the command line wraps to the next line. It is a continuation character.The options for each command or utility are listed alphabetically in the Options section or in the Parameters section. When the order of the options or parameters must be used in a specific order, this order is shown in the syntax statements.Commands and utilities

Reading syntax statements

The reference documentation uses the following special characters to define syntax:

[ ]

Identifies optional options. Options that are not enclosed in brackets are required.

...

Indicates that you can specify multiple values for the previous option.

|

Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.

{ }

Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).

\

Indicates that the command line wraps to the next line. It is a continuation character.

The options for each command or utility are listed alphabetically in the Options section or in the Parameters section. When the order of the options or parameters must be used in a specific order, this order is shown in the syntax statements.

Parent topic: Commands and utilities

CommandscommandsoverviewTable 1 lists the pdadmin commands that can be used during auditing and gathering of statistics activities. Auditing and statistics commandsCommandDescriptionloginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. Establishes authentication credentials that are used during communication with the Security Access Manager policy server.server listLists all registered Security Access Manager servers. Lists all registered Security Access Manager servers.server task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. Enables the gathering of statistical information for an installed Security Access Manager server or server instance.Commands and utilities

Commands

Table 256 lists the pdadmin commands that can be used during auditing and gathering of statistics activities.

Table 256. Auditing and statistics commands

Command | Description
login | Establishes authentication credentials that are used during communication with the Security Access Manager policy server.
server list | Lists all registered Security Access Manager servers.
server task stats | Enables the gathering of statistical information for an installed Security Access Manager server or server instance.

Parent topic: Commands and utilities

loginloginloginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. pdadmin loginThis command does not require a login or authentication to use.Syntaxlogin –a admin_id [–p password] [–d domain]login –a admin_id [–p password] [–m]login –l DescriptionCredentials are used to determine user access privileges to policy server data. Except the context, errtext, exit, help, login, logout, and quit commands, and the local configuration commands, a user ID, and a password are needed for authentication.Credentials are not accumulated or stacked. A login command completely replaces any existing credentials.In interactive mode, the pdadmin prompt changes, depending on how the user logs in: Not interactive mode. This command starts the pdadmin utility. In interactive mode, the login commands are entered from the pdadmin> prompt. c:\> pdadmin pdadmin>A user local login that is performed for local configuration. No authentication is required. pdadmin> login -l pdadmin local>An administrator login that is performed to the local domain. In some cases, the local domain might be the management domain, which is named Default. Authentication is required. pdadmin> login -a sec_master -p secmstrpw pdadmin sec_master>A user login that is performed to the local domain. Authentication is required. pdadmin> login -a dlucas -p lucaspw pdadmin dlucas>A user login that is performed to another domain other than their local domain. Authentication is required. pdadmin> login -a dlucas -p lucaspw -d domain_a pdadmin dlucas@domain_a>A user login that is performed to the management domain. Authentication is required. pdadmin> login -a dlucas -p lucaspw -m pdadmin dlucas@Default> Options–a admin_idSpecifies an administrator ID.–d domainSpecifies the Security Access Manager secure domain for the login. The admin_id user must exist in this domain.–mSpecifies that the login operation must be directed to the management domain. The admin_id user must exist in this domain. Only one of the following domain options can be specified: –d domain or –m. If neither option is specified, the target domain is the local domain that is configured for the system. The admin_id user must exist in the target domain, whether it is explicitly specified.–p passwordSpecifies the password for the admin_id user. If this option is not specified, the user is prompted for the password. The password cannot be specified if the admin_id is not specified.–lSpecifies a local login operation. When modifications are made to local configuration files by using the config commands, a local login is required before you can run commands. The user can run the context show command to view more authentication information. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example logs the sec_master user in to the management domain and then displays the authentication context for the user: pdadmin> login -a sec_master -p pa55w0rd -m pdadmin sec_master> context show User: sec_master Domain: Default The user is logged in to the management domain.The following example logs in a user to the domain1 domain and then displays the authentication context for the user: pdadmin> login -a domain1_admin -p d0main1pwd -d domain1 pdadmin domain1_admin@domain1> context show User: domain1_admin Domain: domain1 The user is not logged in to the management domainThe following example interactively logs in the user to their local domain that is configured for the system. The domain name is testdomain. The example then displays the authentication context of the user: pdadmin> login Enter User ID: testdomain_admin Enter password: adminpwd pdadmin testdomain_admin> context show User: testdomain_admin Domain: testdomain The user is not logged in to the management domainThe following example of a local login demonstrates how the prompt changes, depending on the type of interactive login: c:\> pdadmin login -lProvides this prompt:pdadmin local> Commands and utilities

login

Establishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done.

This command does not require a login or authentication to use.

Syntax

login –a admin_id [–p password] [–d domain]

login –a admin_id [–p password] [–m]

login –l

Description

Credentials are used to determine user access privileges to policy server data. Except the context, errtext, exit, help, login, logout, and quit commands, and the local configuration commands, a user ID, and a password are needed for authentication.

Credentials are not accumulated or stacked. A login command completely replaces any existing credentials.

In interactive mode, the pdadmin prompt changes, depending on how the user logs in:

Not interactive mode. This command starts the pdadmin utility. In interactive mode, the login commands are entered from the pdadmin> prompt.

c:\> pdadmin
pdadmin>

A user local login that is performed for local configuration. No authentication is required.

pdadmin> login -l
pdadmin local>

An administrator login that is performed to the local domain. In some cases, the local domain might be the management domain, which is named Default. Authentication is required.

pdadmin> login -a sec_master -p secmstrpw
pdadmin sec_master>

A user login that is performed to the local domain. Authentication is required.

pdadmin> login -a dlucas -p lucaspw
pdadmin dlucas>

A user login that is performed to another domain other than their local domain. Authentication is required.

pdadmin> login -a dlucas -p lucaspw -d domain_a
pdadmin dlucas@domain_a>

A user login that is performed to the management domain. Authentication is required.

pdadmin> login -a dlucas -p lucaspw -m
pdadmin dlucas@Default>

Options

–a admin_id

Specifies an administrator ID.

–d domain

Specifies the Security Access Manager secure domain for the login. The admin_id user must exist in this domain.

–m

Specifies that the login operation must be directed to the management domain. The admin_id user must exist in this domain.

Note: Only one of the following domain options can be specified: –d domain or –m. If neither option is specified, the target domain is the local domain that is configured for the system. The admin_id user must exist in the target domain, whether it is explicitly specified.

–p password

Specifies the password for the admin_id user. If this option is not specified, the user is prompted for the password. The password cannot be specified if the admin_id is not specified.

–l

Specifies a local login operation. When modifications are made to local configuration files by using the config commands, a local login is required before you can run commands. The user can run the context show command to view more authentication information.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM® Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example logs the sec_master user in to the management domain and then displays the authentication context for the user:

pdadmin> login -a sec_master -p pa55w0rd -m

pdadmin sec_master> context show

User: sec_master
Domain: Default
The user is logged in to the management domain.

The following example logs in a user to the domain1 domain and then displays the authentication context for the user:

pdadmin> login -a domain1_admin -p d0main1pwd -d domain1

pdadmin domain1_admin@domain1> context show

User: domain1_admin
Domain: domain1
The user is not logged in to the management domain

The following example interactively logs in the user to their local domain that is configured for the system. The domain name is testdomain. The example then displays the authentication context of the user:

pdadmin> login
Enter User ID: testdomain_admin
Enter password: adminpwd

pdadmin testdomain_admin> context show

User: testdomain_admin
Domain: testdomain
The user is not logged in to the management domain

The following example of a local login demonstrates how the prompt changes, depending on the type of interactive login:

c:\> pdadmin login -l

Provides this prompt:

pdadmin local>

Parent topic: Commands and utilities

server listserver listserver listLists all registered Security Access Manager servers. server commandsserver listserver commandsserver listRequires authentication (administrator ID and password) to use this command.Syntaxserver list DescriptionLists all registered Security Access Manager servers. The name of the server for all server commands must be entered in the exact format as it is displayed in the output of this command. The server list command does not have such a requirement. OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example lists registered servers: pdadmin> server list The output is as follows: ivmgrd-master ivacld-server1 ivacld-server2where ivmgrd-master represents the Policy server; ivacld-server2 and ivacld-server1 represent Authorization server instances. Commands and utilities

server list

Lists all registered Security Access Manager servers.

Requires authentication (administrator ID and password) to use this command.

Syntax

server list

Description

Lists all registered Security Access Manager servers. The name of the server for all server commands must be entered in the exact format as it is displayed in the output of this command. The server list command does not have such a requirement.

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example lists registered servers:

pdadmin> server list

The output is as follows:

ivmgrd-master
ivacld-server1
ivacld-server2

where ivmgrd-master represents the Policy server; ivacld-server2 and ivacld-server1 represent Authorization server instances.

Parent topic: Commands and utilities

server task statsserver task statsserver task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. server commandsserver task statsserver commandsserver task statsRequires authentication (administrator ID and password) to use this command.Syntaxserver task server_name–host_name stats get [component]server task server_name–host_name stats listserver task server_name–host_name stats off [component]server task server_name–host_name stats on component [interval [count]] [destination]server task server_name–host_name stats reset [component]server task server_name–host_name stats show [component] DescriptionThe server task stats command manages the gathering and reporting of statistics for Security Access Manager servers and server instances. You can use the stats commands with configuration setting that are defined by the stanza entries in the server configuration file to manage statistics.Statistics gathering is enabled through: The stats on command.The defined configuration settings.Then, you can use the stats on commands to modify the behavior for gathering and reporting statistics.For example, statistics are enabled to create five statistics reports with each report generated each day. You can use the stats on command to change the frequency to every 12 hours. For this example, assume that the following command started statistics gathering: pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \ pdwebpi.stats 86400 5 file path=stats.logTo modify the interval to 12 hours and create 10 reports, issue the following command: pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \ pdwebpi.stats 43200 10Although the destination is not specified, the statistics infrastructure assumes any preexisting value. Entering the previous command does disable statistics from being written to the previously defined log file. However, if you specified a different destination, statistics reports would be written to the new destination only. You cannot use the stats on command to write statistics reports to more than one destination.For more information about gathering statistics, see the Auditing topics in the Knowledge Center. OptionscomponentSpecifies the component about which to gather or report statistics. countSpecifies the number of reports to send to a log file. When you use the count option, you must specify the interval option. If you specify the interval option without the count option, the duration of reporting is indefinite. After the count value is reached, reporting to a log file stops. Although statistics are no longer sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.destinationSpecifies where the gathered statistics are written, where destination can be one of the following options: file path=file_nameSpecifies the fully qualified name of the log file.log_agentSpecifies a directory where statistics information is gathered. For more information about logging events, see the Troubleshooting topics in the Knowledge Center.getDisplays the current report for a specific component or for all enabled components. If you specify the component option, displays the current report for that component; otherwise, displays the current report for all enabled components.intervalSpecifies the interval in seconds when statistics are sent from memory to a log file. When this option is specified, statistics are sent, by default, to the server-specific log file designated by the logcfg entry in the server configuration file. You can specify another location by using the destination option. If an interval is not specified, statistics are not sent to a log file, but remain in memory. Although statistics are not sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.listLists all components that are available to gather and report statistics.offDisables gathering of statistics for a specific component or for all components. If you specify the component option, disables gathering of statistics for that component; otherwise, disables gathering of statistics for all components.onEnables gathering of statistics for a specific component. When you enable gathering of statistics, you can also set the reporting frequency, count, and log file.resetResets gathering of statistics for a specific component or for all enabled components. If you specify the component option, resets gathering of statistics for that component; otherwise, resets gathering of statistics for all components.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.showLists all enabled components or indicates whether a specific component is enabled. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components. Return codes0The command completed successfully.1The command failed. See the Messages topics in the Knowledge Center for more information. ExamplesThe following example uses the stats list command to lists all enabled components on the ivacld-mogman.admogman.com authorization server: #pdadmin sec_master> server task ivacld-mogman.admogman.com stats list pd.ras.stats.monitor pd.log.EventPool.queueThe following example: Uses the status on command to enable gathering of statistics for the pd.log.EventPool.queue component on the ivacld-mogman.admogman.com authorization server.Sets the reporting frequency to 30 days, that is, 2592000 seconds.Sets the destination to the myEPstats.log log file.#pdadmin sec_master> server task ivacld-mogman.admogman.com stats on \ pd.log.EventPool.queue 2592000 file path=myEPstats.log See alsoserver listLists all registered Security Access Manager servers. Commands and utilities

server task stats

Manages the gathering and reporting of statistics for Security Access Manager servers and server instances.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task server_name–host_name stats get [component]

server task server_name–host_name stats list

server task server_name–host_name stats off [component]

server task server_name–host_name stats on component [interval [count]] [destination]

server task server_name–host_name stats reset [component]

server task server_name–host_name stats show [component]

Description

The server task stats command manages the gathering and reporting of statistics for Security Access Manager servers and server instances. You can use the stats commands with configuration setting that are defined by the stanza entries in the server configuration file to manage statistics.

Statistics gathering is enabled through:

The stats on command.

The defined configuration settings.

Then, you can use the stats on commands to modify the behavior for gathering and reporting statistics.

For example, statistics are enabled to create five statistics reports with each report generated each day. You can use the stats on command to change the frequency to every 12 hours. For this example, assume that the following command started statistics gathering:

pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \
pdwebpi.stats 86400 5 file path=stats.log

To modify the interval to 12 hours and create 10 reports, issue the following command:

pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \
pdwebpi.stats 43200 10

Although the destination is not specified, the statistics infrastructure assumes any preexisting value. Entering the previous command does disable statistics from being written to the previously defined log file. However, if you specified a different destination, statistics reports would be written to the new destination only. You cannot use the stats on command to write statistics reports to more than one destination.

For more information about gathering statistics, see the Auditing topics in the Knowledge Center.

Options

component

Specifies the component about which to gather or report statistics.

count

Specifies the number of reports to send to a log file. When you use the count option, you must specify the interval option. If you specify the interval option without the count option, the duration of reporting is indefinite.

After the count value is reached, reporting to a log file stops. Although statistics are no longer sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.

destination

Specifies where the gathered statistics are written, where destination can be one of the following options:

file path=file_name

Specifies the fully qualified name of the log file.

log_agent

Specifies a directory where statistics information is gathered. For more information about logging events, see the Troubleshooting topics in the Knowledge Center.

get

Displays the current report for a specific component or for all enabled components. If you specify the component option, displays the current report for that component; otherwise, displays the current report for all enabled components.

interval

Specifies the interval in seconds when statistics are sent from memory to a log file. When this option is specified, statistics are sent, by default, to the server-specific log file designated by the logcfg entry in the server configuration file. You can specify another location by using the destination option. If an interval is not specified, statistics are not sent to a log file, but remain in memory.

Although statistics are not sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.

list

Lists all components that are available to gather and report statistics.

off

Disables gathering of statistics for a specific component or for all components. If you specify the component option, disables gathering of statistics for that component; otherwise, disables gathering of statistics for all components.

on

Enables gathering of statistics for a specific component. When you enable gathering of statistics, you can also set the reporting frequency, count, and log file.

reset

Resets gathering of statistics for a specific component or for all enabled components. If you specify the component option, resets gathering of statistics for that component; otherwise, resets gathering of statistics for all components.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

show

Lists all enabled components or indicates whether a specific component is enabled. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components.

Return codes

0

The command completed successfully.

1

The command failed. See the Messages topics in the Knowledge Center for more information.

Examples

The following example uses the stats list command to lists all enabled components on the ivacld-mogman.admogman.com authorization server:

#pdadmin sec_master> server task ivacld-mogman.admogman.com stats list

pd.ras.stats.monitor
pd.log.EventPool.queue

The following example:

Uses the status on command to enable gathering of statistics for the pd.log.EventPool.queue component on the ivacld-mogman.admogman.com authorization server.

Sets the reporting frequency to 30 days, that is, 2592000 seconds.

Sets the destination to the myEPstats.log log file.

#pdadmin sec_master> server task ivacld-mogman.admogman.com stats on \
pd.log.EventPool.queue 2592000 file path=myEPstats.log

See also

server list

Parent topic: Commands and utilities

Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.AuditingThe IBM Security Access Manager provides information about configuring and managing audit events.Advanced Access Control auditing eventsThis section lists the audit elements that are available for each audit event type.IBM_SECURITY_AUTHN_eventsThis event type is generated by the authentication service when it authenticates a user accessing a protected resource. IBM_SECURITY_TRUST eventsThis event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.IBM_SECURITY_RUNTIME eventsThis event type is generated when the runtime is started.IBM_SECURITY_CBA_AUDIT_MGMT eventsThis event type identifies the security context-based management events, such as the creation of risk profiles.IBM_SECURITY_CBA_AUDIT_RTE eventsThis event type identifies the security context-based authorization events, such as device registration.IBM_SECURITY_RTSS_AUDIT_AUTHZ eventsThis event type identifies the authorization decision events for runtime security services.Deploying pending changesSome configuration and administration changes require an extra deployment step.

Auditing Advanced Access Control

These topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

Advanced Access Control auditing events
This section lists the audit elements that are available for each audit event type.

IBM_SECURITY_AUTHN_events
This event type is generated by the authentication service when it authenticates a user accessing a protected resource.

IBM_SECURITY_TRUST events
This event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.

IBM_SECURITY_RUNTIME events
This event type is generated when the runtime is started.

IBM_SECURITY_CBA_AUDIT_MGMT events
This event type identifies the security context-based management events, such as the creation of risk profiles.

IBM_SECURITY_CBA_AUDIT_RTE events
This event type identifies the security context-based authorization events, such as device registration.

IBM_SECURITY_RTSS_AUDIT_AUTHZ events
This event type identifies the authorization decision events for runtime security services.

Deploying pending changes
Some configuration and administration changes require an extra deployment step.

Parent topic: Auditing

Advanced Access Control auditing eventsAdvanced Access Control auditing eventsAdvanced Access Control auditing eventsThis section lists the audit elements that are available for each audit event type.auditeventscommon elementsaudit eventsaudit eventscommon elementsUse the instructions in Configuring auditing on the applianceUse the Audit Configuration feature to enable logging of audit events. to configure auditing on the appliance.Advanced Access Control supports the following auditing events:IBM_SECURITY_TRUSTIBM_SECURITY_RUNTIMEIBM_SECURITY_CBA_AUDIT_MGMTIBM_SECURITY_CBA_AUDIT_RTEIBM_SECURITY_RTSS_AUDIT_AUTHZThis section describes the available elements for each event type.Common elements for all eventsThe following elements are included with all security events:ContextDataElementsSourceComponentIdelementsSituationOutcomeContextDataElementsThe contextId value, which is specified on the type attribute, is included in the ContextDataElements element to correlate all events that are associated with a single transaction.Attributes and elements of the ContextDataElements elementAttributeValuenameSecurity Event FactoryThe XPath is:CommonBaseEvent/contextDataElements/@nametypeeventTrailIdThe XPath is:CommonBaseEvent/contextDataElements/@typecontextId This element is a container element for the eventTrailId value; it does not have an XPath value.eventTrailIdThe event trail identifier value, for example, FIM_116320b90110104ab7ce9df3453615a1+729829786 The XPath is:CommonBaseEvent/contextDataElements/[@type='eventTrailId']/contextIdThe following are XML-formatted examples of CBE event headers containing entries for the ContextDataElements element. These entries illustrate how separate events are correlated for a single transaction.<CommonBaseEvent creationTime="2007-01-31T20:59:57.625Z" extensionName="IBM_SECURITY_TRUST" globalInstanceId="CE4454A122E10AB044A1DBB16E020E1D80" sequenceNumber="1" version="1.0.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId> </contextDataElements> ... </CommonBaseEvent><CommonBaseEvent creationTime="2007-01-31T20:59:57.765Z" extensionName="IBM_SECURITY_TRUST" globalInstanceId="CE4454A122E10AB044A1DBB16E02213050" sequenceNumber="2" version="1.0.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId> </contextDataElements> ... </CommonBaseEvent>SourceComponentId elementThe SourceComponentId is an identifier that represents the source that generates the event.Attributes for the SourceComponentId elementAttributeValueapplicationITFIM#8.0.0The XPath is:CommonBaseEvent/sourceComponentId/ @applicationcomponentThe XPath is:CommonBaseEvent/sourceComponentId/ @componentcomponentIdType ProductNameThe XPath is:CommonBaseEvent/sourceComponentId/ @componentIdTypecomponentTypehttp://www.ibm.com/namespaces/autonomic/Tivoli_componentTypesThe XPath is:CommonBaseEvent/sourceComponentId/ @componentTypeexecutionEnvironment<OS name>#<OS Architecture>#<OS.version>The XPath is:CommonBaseEvent/sourceComponentId/ @executionEnvironmentlocation<hostname>The XPath is:CommonBaseEvent/extendedDataElements [@name='registryInfo']/children [@name='location']/valueslocationTypeFQHostnameThe XPath is:CommonBaseEvent/sourceComponentId/ @locationTypesubComponent<classname>The XPath is:CommonBaseEvent/sourceComponentId/ @subComponentSituation elementThe Situation element describes the circumstance that caused the audit event.Attributes for the Situation elementAttributeValuecategoryNameReportSituationThe XPath is:CommonBaseEvent/situation/ @categoryNamereasoningScopeINTERNALThe XPath is:CommonBaseEvent/situation/situationType/ @reasoningScopereportCategorySECURITYThe XPath is:CommonBaseEvent/situation/situationType/ @reportCategoryOutcome elementThe Outcome element is the result of the action for which the security event is being generated.Attributes for the Outcome elementAttributeValuefailureReason The XPath is:CommonBaseEvent/extendedDataElements [@name='outcome']/children [@name='failureReason']/values majorStatus The XPath is:CommonBaseEvent/extendedDataElements [@name='outcome']/children [@name='majorStatus']/values result The XPath is:CommonBaseEvent/extendedDataElements [@name='outcome']/children [@name='result']/values Advanced Access Control does not use the ReporterComponentId field.Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

Advanced Access Control auditing events

This section lists the audit elements that are available for each audit event type.

Use the instructions in Configuring auditing on the appliance to configure auditing on the appliance.

Advanced Access Control supports the following auditing events:

IBM_SECURITY_TRUST

IBM_SECURITY_RUNTIME

IBM_SECURITY_CBA_AUDIT_MGMT

IBM_SECURITY_CBA_AUDIT_RTE

IBM_SECURITY_RTSS_AUDIT_AUTHZ

This section describes the available elements for each event type.

Common elements for all events

The following elements are included with all security events:

ContextDataElements

SourceComponentIdelements

Situation

Outcome

ContextDataElements

The contextId value, which is specified on the type attribute, is included in the ContextDataElements element to correlate all events that are associated with a single transaction.

Table 257. Attributes and elements of the ContextDataElements element

Attribute
Value

name
Security Event Factory

The XPath is:

CommonBaseEvent/contextDataElements/@name

type
eventTrailId

The XPath is:

CommonBaseEvent/contextDataElements/@type

contextId
This element is a container element for the eventTrailId value; it does not have an XPath value.

eventTrailId
The event trail identifier value, for example, FIM_116320b90110104ab7ce9df3453615a1+729829786

The XPath is:

CommonBaseEvent/contextDataElements/[@type='eventTrailId']/contextId

The following are XML-formatted examples of CBE event headers containing entries for the ContextDataElements element. These entries illustrate how separate events are correlated for a single transaction.

<CommonBaseEvent
	creationTime="2007-01-31T20:59:57.625Z"
	extensionName="IBM_SECURITY_TRUST"
	globalInstanceId="CE4454A122E10AB044A1DBB16E020E1D80"
	sequenceNumber="1" version="1.0.1">
	<contextDataElements name="Security Event Factory" 	type="eventTrailId">
		<contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId>
	</contextDataElements>
...
</CommonBaseEvent>

<CommonBaseEvent
	creationTime="2007-01-31T20:59:57.765Z"
	extensionName="IBM_SECURITY_TRUST"
	globalInstanceId="CE4454A122E10AB044A1DBB16E02213050"
	sequenceNumber="2" version="1.0.1">
	<contextDataElements name="Security Event Factory" type="eventTrailId">
		<contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId>
	</contextDataElements>
...
</CommonBaseEvent>

SourceComponentId element

The SourceComponentId is an identifier that represents the source that generates the event.

Table 258. Attributes for the SourceComponentId element

Attribute
Value

application
ITFIM#8.0.0

The XPath is:

CommonBaseEvent/sourceComponentId/
@application

component

The XPath is:

CommonBaseEvent/sourceComponentId/
@component

componentIdType
ProductName

The XPath is:

CommonBaseEvent/sourceComponentId/
@componentIdType

componentType
http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes

The XPath is:

CommonBaseEvent/sourceComponentId/
@componentType

executionEnvironment
<OS name>#<OS Architecture>#<OS.version>

The XPath is:

CommonBaseEvent/sourceComponentId/
@executionEnvironment

location
<hostname>

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='registryInfo']/children
[@name='location']/values

locationType
FQHostname

The XPath is:

CommonBaseEvent/sourceComponentId/
@locationType

subComponent
<classname>

The XPath is:

CommonBaseEvent/sourceComponentId/
@subComponent

Situation element

The Situation element describes the circumstance that caused the audit event.

Table 259. Attributes for the Situation element

Attribute
Value

categoryName
ReportSituation

The XPath is:

CommonBaseEvent/situation/
@categoryName

reasoningScope
INTERNAL

The XPath is:

CommonBaseEvent/situation/situationType/
@reasoningScope

reportCategory
SECURITY

The XPath is:

CommonBaseEvent/situation/situationType/
@reportCategory

Outcome element

The Outcome element is the result of the action for which the security event is being generated.

Table 260. Attributes for the Outcome element

Attribute
Value

failureReason

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='outcome']/children
[@name='failureReason']/values

majorStatus

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='outcome']/children
[@name='majorStatus']/values

result

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='outcome']/children
[@name='result']/values

Note: Advanced Access Control does not use the ReporterComponentId field.

Parent topic: Auditing Advanced Access Control

IBM_SECURITY_AUTHN_eventsIBM_SECURITY_AUTHN_eventsIBM_SECURITY_AUTHN_eventsThis event type is generated by the authentication service when it authenticates a user accessing a protected resource. IBM_SECURITY_AUTHN eventsThe following table lists the elements that can be shown in the output of an IBM_SECURITY_AUTHN event. All elements are included in the output, unless indicated otherwise. Elements for an IBM_SECURITY_AUTHN eventElementDescriptionactionOptionally specifies the HTTP method on the requested resource or the operation that is performed by the provider of the authentication service.The XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesauthnProviderThe provider of the authentication service.Sample data: com.tivoli.am.fim.authsvc.protocol.delegate.AuthSvcDelegate com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthnticatorThe XPath is:CommonBaseEvent/extendedDataElements [@name='authnProvider']/valuesauthnScopeOptionally specifies the transaction identifier of the authentication policy. Sample data: 94434b2a-748e-42fe-af3d-67db04aa4ba0The XPath is:CommonBaseEvent/extendedDataElements [@name='authnScope']/valuesauthnTypeThe URI identifier of the authentication policy. Sample data: urn:ibm:security:authentication:asf:password_hotpThe XPath is:CommonBaseEvent/extendedDataElements [@name='authnType']/valuespartnerThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='partner']/valuesprogNameOptionally specifies the URL of the requested resource. Sample data: http://www.example.comThe XPath is:CommonBaseEvent/extendedDataElements [@name='progName']/valuestokenTypeThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='tokenType']/valuestrustRelationshipThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as 'Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='trustRelationship']/valuesuserInfo.appUserNameOptionally specifies information about the user who is authenticating.The XPath is:CommonBaseEvent/extendedDataElements [@name='userInfoList']/children[1]/children [@name='appUserName']/valuesuserInfo.attributesOptionally specifies the following types of additional information about user data that are audited during authentication: licenseFileMetadata Metadata that is defined in the license agreement.licenseFileNameThe license file name. userActionThe action that the user takes when the End-User License Agreement authentication mechanism presents the license agreement. The user can accept the license agreement or decline the license agreement. The XPath is: CommonBaseEvent/extendedDataElements [@name='userInfoList']/children [@name='userInfo'] /children [@name='attributes']/childrenxmlTokenTypeThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='xmlTokenType']/valuesSample of an IBM_SECURITY_AUTHN eventThe following example shows one event generated by the runtime for a two-factor authentication policy requiring both username password and one-time password authentications: <CommonBaseEvent creationTime="2014-02-15T18:50:05.026Z" extensionName="IBM_SECURITY_AUTHN" globalInstanceId="FIM36e24f6301441708947ceef443526" sequenceNumber="2" version="1.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_36e24f62014415f59913eef443526e68+1246005647</contextId> </contextDataElements> <extendedDataElements name="userInfoList" type="noValue"> <children name="userInfo" type="noValue"> <children name="registryUserName" type="string"> <values>Not Available</values> </children> <children name="appUserName" type="string"> <values>test_user</values> </children> </children> </extendedDataElements> <extendedDataElements name="tokenType" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="authnProvider" type="string"> <values>com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator</values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>verify</values> </extendedDataElements> <extendedDataElements name="authnType" type="string"> <values>urn:ibm:security:authentication:asf:password_hotp</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"> <values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"> <values>0</values> </children> </extendedDataElements> <extendedDataElements name="trustRelationship" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="progName" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="authnScope" type="string"> <values>Not Available</values> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64" location="example" locationType="FQHostname" subComponent="com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator" threadId="Default Executor-thread-60" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

IBM_SECURITY_AUTHN_events

This event type is generated by the authentication service when it authenticates a user accessing a protected resource.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_AUTHN event. All elements are included in the output, unless indicated otherwise.

Table 261. Table 271. Elements for an IBM_SECURITY_AUTHN event

Element
Description

action
Optionally specifies the HTTP method on the requested resource or the operation that is performed by the provider of the authentication service.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

authnProvider
The provider of the authentication service.

Sample data: com.tivoli.am.fim.authsvc.protocol.delegate.AuthSvcDelegate com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthnticator

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnProvider']/values

authnScope
Optionally specifies the transaction identifier of the authentication policy.

Sample data: 94434b2a-748e-42fe-af3d-67db04aa4ba0

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnScope']/values

authnType
The URI identifier of the authentication policy.

Sample data: urn:ibm:security:authentication:asf:password_hotp

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnType']/values

partner
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='partner']/values

progName
Optionally specifies the URL of the requested resource.

Sample data: http://www.example.com

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='progName']/values

tokenType
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='tokenType']/values

trustRelationship
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as 'Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='trustRelationship']/values

userInfo.appUserName
Optionally specifies information about the user who is authenticating.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='userInfoList']/children[1]/children
[@name='appUserName']/values

userInfo.attributes
Optionally specifies the following types of additional information about user data that are audited during authentication:

licenseFileMetadata

Metadata that is defined in the license agreement.

licenseFileName

The license file name.

userAction

The action that the user takes when the End-User License Agreement authentication mechanism presents the license agreement. The user can accept the license agreement or decline the license agreement.

The XPath is:

 CommonBaseEvent/extendedDataElements
[@name='userInfoList']/children [@name='userInfo']
/children [@name='attributes']/children

xmlTokenType
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='xmlTokenType']/values

Sample of an IBM_SECURITY_AUTHN event

The following example shows one event generated by the runtime for a two-factor authentication policy requiring both username password and one-time password authentications:

<CommonBaseEvent
  creationTime="2014-02-15T18:50:05.026Z"
  extensionName="IBM_SECURITY_AUTHN"
  globalInstanceId="FIM36e24f6301441708947ceef443526"
  sequenceNumber="2"
  version="1.1">
  <contextDataElements
    name="Security Event Factory"
    type="eventTrailId">
        <contextId>FIM_36e24f62014415f59913eef443526e68+1246005647</contextId>
  </contextDataElements>
  <extendedDataElements name="userInfoList" type="noValue">
   <children name="userInfo" type="noValue">
     <children name="registryUserName" type="string">
       <values>Not Available</values>
     </children>
     <children name="appUserName" type="string">
       <values>test_user</values>
     </children>
   </children>
 </extendedDataElements>
 <extendedDataElements name="tokenType" type="string">
   <values>Not Available</values>
 </extendedDataElements>
 <extendedDataElements name="authnProvider" type="string">
   <values>com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator</values>
 </extendedDataElements>
 <extendedDataElements name="action" type="string">
      <values>verify</values>
 </extendedDataElements>
 <extendedDataElements name="authnType" type="string">
      <values>urn:ibm:security:authentication:asf:password_hotp</values>
 </extendedDataElements>
 <extendedDataElements name="outcome" type="noValue">
      <children name="result" type="string">
        <values>SUCCESSFUL</values>
      </children>
      <children name="majorStatus" type="int">
        <values>0</values>
      </children>
 </extendedDataElements>
 <extendedDataElements name="trustRelationship" type="string">
      <values>Not Available</values>
 </extendedDataElements>
 <extendedDataElements name="progName" type="string">
      <values>Not Available</values>
 </extendedDataElements>
 <extendedDataElements name="authnScope" type="string">
      <values>Not Available</values>
 </extendedDataElements>
 <sourceComponentId
      application="IBM Security Access Manager"
      component="Authentication and Federated Identity"
      componentIdType="ProductName"
      executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64"
      location="example"
      locationType="FQHostname"
      subComponent="com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator"
      threadId="Default Executor-thread-60"
      componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
  <situation categoryName="ReportSituation">
     <situationType
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:type="ReportSituation"
       reasoningScope="INTERNAL"
       reportCategory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Advanced Access Control

IBM_SECURITY_TRUST eventsIBM_SECURITY_TRUST eventssecurity trust eventsThis event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.security trust eventsevents IBM_SECURITY_TRUSTIBM_SECURITY_TRUSTdescriptionThe following table lists the elements that can be shown in the output of an IBM_SECURITY_TRUST event.Elements for an IBM_SECURITY_TRUST eventElementDescriptionaccessDecisionFor the authorization module, it is the result of the authorization decision. This element is filled out only when the action is authorized.The XPath is:CommonBaseEvent/extendedDataElements [@name='accessDecision']/valuesactionThe action being performed. Possible actions are:authorizeissuemapvalidateThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesappliesToThe destination or resource that the request or token applies to.The XPath is:CommonBaseEvent/extendedDataElements [@name='appliesTo']/valuesissuerThe party responsible for issuing the token.The XPath is:CommonBaseEvent/extendedDataElements [@name='issuer']/valuesmoduleNameThe module in the STS module chain that the action is taken on.The XPath is:CommonBaseEvent/extendedDataElements [@name='moduleName']/valuesruleNameThe rule name used for the mapping module. This element is filled out only when specified action is set to map. The XPath is:CommonBaseEvent/extendedDataElements [@name='ruleName']/valuestokenThe incoming token that the action is being taken on. Only the first 1024 characters of the token are set. When the action is set to map, this element represents the incoming principal.The XPath is:CommonBaseEvent/extendedDataElements [@name='token']/valuestokenInfoThe internal representation of the user information after changes are made by the module. Only the first 1024 characters of the token are set. When action is set to map, this element represents the outgoing principal. When the action is set to authorize, this element represents the principal for whom the access decision was made.The XPath is:CommonBaseEvent/extendedDataElements [@name='tokenInfo']/valuestokenTypeThe type of token the module is using.The XPath is:CommonBaseEvent/extendedDataElements [@name='tokenType']/valuesSamples of IBM_SECURITY_TRUST eventsThe following example shows an event generated by a Trust request. <CommonBaseEvent creationTime="2013-07-19T06:21:05.256Z" extensionName="IBM_SECURITY_TRUST" globalInstanceId="FIMf596c16e013f12d38eb0b66d4d925" sequenceNumber="1" version="1.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_f596bda0013f188f9983b66d4d92542a+971185751</contextId> </contextDataElements> <extendedDataElements name="tokenType" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="issuer" type="string"> <values>/otpfed/otp/get/delivery/options/issuer</values> </extendedDataElements> <extendedDataElements name="token" type="string"> <values>user1 [ Attribute 1 name [ value 1 user1 ] ]</values> </extendedDataElements> <extendedDataElements name="ruleName" type="string"> <values>otp_get_methods.js </values> </extendedDataElements> <extendedDataElements name="moduleName" type="string"> <values>com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault</values> </extendedDataElements> <extendedDataElements name="appliesTo" type="string"> <values>/otpfed/otp/get/delivery/options/appliesto</values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>Map</values> </extendedDataElements> <extendedDataElements name="tokenInfo" type="string"> <values>user1 [ Attribute 1 name [ value 1 user1 ] ]</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"> <values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"> <values>0</values> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64" location="localhost" locationType="FQHostname" subComponent="com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault" threadId="Default Executor-thread-6" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

IBM_SECURITY_TRUST events

This event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_TRUST event.

Table 262. Elements for an IBM_SECURITY_TRUST event

Element
Description

accessDecision
For the authorization module, it is the result of the authorization decision. This element is filled out only when the action is authorized.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='accessDecision']/values

action
The action being performed. Possible actions are:

authorize

issue

map

validate

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

appliesTo
The destination or resource that the request or token applies to.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='appliesTo']/values

issuer
The party responsible for issuing the token.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='issuer']/values

moduleName
The module in the STS module chain that the action is taken on.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='moduleName']/values

ruleName
The rule name used for the mapping module. This element is filled out only when specified action is set to map.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='ruleName']/values

token
The incoming token that the action is being taken on. Only the first 1024 characters of the token are set. When the action is set to map, this element represents the incoming principal.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='token']/values

tokenInfo
The internal representation of the user information after changes are made by the module. Only the first 1024 characters of the token are set. When action is set to map, this element represents the outgoing principal. When the action is set to authorize, this element represents the principal for whom the access decision was made.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='tokenInfo']/values

tokenType
The type of token the module is using.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='tokenType']/values

Samples of IBM_SECURITY_TRUST events

The following example shows an event generated by a Trust request.

<CommonBaseEvent creationTime="2013-07-19T06:21:05.256Z"
extensionName="IBM_SECURITY_TRUST"
globalInstanceId="FIMf596c16e013f12d38eb0b66d4d925"
sequenceNumber="1" version="1.1">
	<contextDataElements name="Security Event Factory"
type="eventTrailId">
		<contextId>FIM_f596bda0013f188f9983b66d4d92542a+971185751</contextId>
	</contextDataElements>
	<extendedDataElements name="tokenType" type="string">
		<values>Not Available</values>
	</extendedDataElements>
	<extendedDataElements name="issuer" type="string">
		<values>/otpfed/otp/get/delivery/options/issuer</values>
	</extendedDataElements>
	<extendedDataElements name="token" type="string">
		<values>user1 [ Attribute 1 name   [ value 1 user1 ] ]</values>
	</extendedDataElements>
	<extendedDataElements name="ruleName" type="string">
		<values>otp_get_methods.js </values>
	</extendedDataElements>
	<extendedDataElements name="moduleName" type="string">
		<values>com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault</values>
	</extendedDataElements>
	<extendedDataElements name="appliesTo" type="string">
		<values>/otpfed/otp/get/delivery/options/appliesto</values>
	</extendedDataElements>
	<extendedDataElements name="action" type="string">
		<values>Map</values>
	</extendedDataElements>
	<extendedDataElements name="tokenInfo" type="string">
		<values>user1 [ Attribute 1 name   [ value 1 user1 ] ]</values>
	</extendedDataElements>
	<extendedDataElements name="outcome" type="noValue">
		<children name="result" type="string">
			<values>SUCCESSFUL</values>
		</children>
		<children name="majorStatus" type="int">
			<values>0</values>
		</children>
	</extendedDataElements>
	<sourceComponentId application="IBM Security Access Manager"
component="Authentication and Federated Identity"
componentIdType="ProductName"
executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64"
location="localhost" locationType="FQHostname"
subComponent="com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault"
threadId="Default Executor-thread-6"
componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
	<situation categoryName="ReportSituation">
		<situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/>
	</situation>
</CommonBaseEvent>

Parent topic: Auditing Advanced Access Control

IBM_SECURITY_RUNTIME eventsIBM_SECURITY_RUNTIME eventssecurity runtime eventsThis event type is generated when the runtime is started.security runtime eventsevents IBM_SECURITY_RUNTIMEIBM_SECURITY_RUNTIMEdescriptionThe following table lists the elements that can be shown in the output of an IBM_SECURITY_RUNTIME event.Elements for an IBM_SECURITY_RUNTIME eventElements for an IBM_SECURITY_RUNTIME eventElementDescriptionDomainThe XPath is:CommonBaseEvent/extendedDataElements [@name='Domain']/valuesIsMgmtAuditThe XPath is:CommonBaseEvent/extendedDataElements [@name='IsMgmtAudit']/valuesnameInAppThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='nameInApp']/values nameInPolicyThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='nameInPolicy']/values typeThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='type']/values uniqueIDThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='uniqueID']/values actionThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesSamples of IBM_SECURITY_RUNTIME eventsThe following example shows an events generated by a runtime request. <CommonBaseEvent creationTime="2013-07-19T06:20:18.361Z" extensionName="IBM_SECURITY_RUNTIME" globalInstanceId="FIMf5960a71013f15479e82b66d4d925" sequenceNumber="0" version="1.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_f5960938013f1eba8b40b66d4d92542a+1655973824</contextId> </contextDataElements> <extendedDataElements name="Domain" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="IsMgmtAudit" type="boolean"> <values>false</values> </extendedDataElements> <extendedDataElements name="resourceInfo" type="noValue"> <children name="nameInApp" type="string"> <values/> </children> <children name="nameInPolicy" type="string"> <values/> </children> <children name="type" type="string"> <values>application</values> </children> <children name="uniqueId" type="long"> <values>0</values> </children> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>auditStart</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"> <values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"> <values>0</values> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64" location="localhost" locationType="FQHostname" subComponent="com.tivoli.am.fim.audit.event.impl.RuntimeAuditAdapterImpl" threadId="Start Level Event Dispatcher" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

IBM_SECURITY_RUNTIME events

This event type is generated when the runtime is started.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_RUNTIME event.

Table 263. Elements for an IBM_SECURITY_RUNTIME event.

Element
Description

Domain

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='Domain']/values

IsMgmtAudit

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='IsMgmtAudit']/values

nameInApp

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='nameInApp']/values

nameInPolicy

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='nameInPolicy']/values

type

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='type']/values

uniqueID

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='uniqueID']/values

action

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

Samples of IBM_SECURITY_RUNTIME events

The following example shows an events generated by a runtime request.

<CommonBaseEvent
creationTime="2013-07-19T06:20:18.361Z"
extensionName="IBM_SECURITY_RUNTIME"
globalInstanceId="FIMf5960a71013f15479e82b66d4d925"
sequenceNumber="0"
version="1.1">
	<contextDataElements name="Security Event Factory"
type="eventTrailId">
		<contextId>FIM_f5960938013f1eba8b40b66d4d92542a+1655973824</contextId>
	</contextDataElements>
	<extendedDataElements name="Domain" type="string">
		<values>Not Available</values>
	</extendedDataElements>
	<extendedDataElements name="IsMgmtAudit" type="boolean">
		<values>false</values>
	</extendedDataElements>
	<extendedDataElements name="resourceInfo" type="noValue">
		<children name="nameInApp" type="string">
			<values/>
		</children>
		<children name="nameInPolicy" type="string">
			<values/>
		</children>
		<children name="type" type="string">
			<values>application</values>
		</children>
		<children name="uniqueId" type="long">
			<values>0</values>
		</children>
	</extendedDataElements>
	<extendedDataElements name="action" type="string">
		<values>auditStart</values>
	</extendedDataElements>
	<extendedDataElements name="outcome" type="noValue">
		<children name="result" type="string">
			<values>SUCCESSFUL</values>
		</children>
		<children name="majorStatus" type="int">
			<values>0</values>
		</children>
	</extendedDataElements>
	<sourceComponentId application="IBM Security Access Manager"
component="Authentication and Federated Identity"
componentIdType="ProductName"
executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64"
location="localhost" locationType="FQHostname"
subComponent="com.tivoli.am.fim.audit.event.impl.RuntimeAuditAdapterImpl"
threadId="Start Level Event Dispatcher"
componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
	<situation categoryName="ReportSituation">
		<situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/>
	</situation>
</CommonBaseEvent>

Parent topic: Auditing Advanced Access Control

IBM_SECURITY_CBA_AUDIT_MGMT eventsIBM_SECURITY_CBA_AUDIT_MGMT eventsIBM_SECURITY_CBA_AUDIT_MGMT eventsThis event type identifies the security context-based management events, such as the creation of risk profiles.IBM_SECURITY_CBA_AUDIT_MGMT events The following table lists the elements that can be displayed in the output of a IBM_SECURITY_CBA_AUDIT_MGMT event. All elements are included in the output, unless indicated otherwise. Elements used in IBM_ SECURITY_CBA_AUDIT_MGMT eventsElementDescriptioncreationTime Specifies the date and time when the event was issued. For example: 2013-09-11T19:18:04.140Z The letter Z in the sample that is shown indicates the UTC format. All time stamps are issued in UTC format. There is no provision for specifying local time. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. actionInfo Provides information about the management action that is performed on a resource. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. actionInfo action-idSpecifies the action that caused this management event. Possible actions include: API protection client related eventsAPI_PROTECTION_CLIENT_CREATE_EVENT, API_PROTECTION_CLIENT_DELETE_EVENT, API_PROTECTION_CLIENT_SEARCH_EVENT, API_PROTECTION_CLIENT_SECRET_GENERATE_EVENT, API_PROTECTION_CLIENT_UPDATE_EVENT API protection definition related eventsAPI_PROTECTION_DEFINITION_CREATE_EVENT, API_PROTECTION_DEFINITION_DELETE_EVENT, API_PROTECTION_DEFINITION_SEARCH_EVENT, API_PROTECTION_DEFINITION_UPDATE_EVENT Attribute matcher related eventsATTRIBUTE_MATCHER_CREATE_EVENT, ATTRIBUTE_MATCHER_DELETE_EVENT, ATTRIBUTE_MATCHER_SEARCH_EVENT, ATTRIBUTE_MATCHER_UPDATE_EVENTAttribute related eventsATTRIBUTE_CREATE_EVENT, ATTRIBUTE_DELETE_EVENT, ATTRIBUTE_SEARCH_EVENT, ATTRIBUTE_UPDATE_EVENTAudit related eventsAUDIT_SEARCH_EVENT, AUDIT_UPDATE_EVENT Authentication mechanism instances related events AUTH_MECH_INSTANCE_UPDATE_EVENT, AUTH_MECH_INSTANCE_SEARCH_EVENTAuthentication mechanism types related events AUTH_MECH_TYPE_SEARCH_EVENT Authentication policy related eventsAUTH_POLICY_CREATE_EVENT, AUTH_POLICY_UPDATE_EVENT, AUTH_POLICY_DELETE_EVENT, AUTH_POLICY_SEARCH_EVENT Bundle related events BUNDLE_SEARCH_EVENT, BUNDLE_CREATE_EVENT, BUNDLE_UPDATE_EVENT, BUNDLE_DELETE_EVENT, BUNDLE_EXPORT_EVENT, BUNDLE_IMPORT_EVENT Device related events DEVICE_DELETE_EVENT, DEVICE_SEARCH_EVENT, DEVICES_FOR_USER_SEARCH_EVENT, DEVICE_USER_ID_SEARCH_EVENTExtension instances related eventsEXTENSION_INSTANCE_SEARCH_EVENT, EXTENSION_INSTANCE_CREATE_EVENT, EXTENSION_INSTANCE_UPDATE_EVENT, EXTENSION_INSTANCE_DELETE_EVENTExtension related eventsEXTENSION_SEARCH_EVENTGeolocation data related events GEOLOCATION_DATA_CANCEL_IMPORT_EVENT, GEOLOCATION_DATA_IMPORT_EVENT, GEOLOCATION_DATA_STATUS_IMPORT_EVENTHVDB related eventsHVDB_DELETE_ALL_DATA_EVENT, HVDB_DELETE_USER_DATA_EVENT, HVDB_CANCEL_DELETE_DATA_EVENT, HVDB_DELETE_DEVICES_EVENT, HVDB_STATUS_DELETE_DATA_EVENT, HVDB_DELETE_USER_FROM_DBMapping rule related eventsMAPPING_RULE_EXPORT_EVENT, MAPPING_RULE_IMPORT_EVENT , MAPPING_RULE_SEARCH_EVENT, MAPPING_RULE_UPDATE_EVENT, MAPPING_RULE_CREATE_EVENT, MAPPING_RULE_DELETE_EVENT Obligation related eventsOBLIGATION_CREATE_EVENT, OBLIGATION_DELETE_EVENT, OBLIGATION_SEARCH_EVENT, OBLIGATION_UPDATE_EVENTOverride configuration related events OVERRIDE_CONFIG_SEARCH_EVENT, OVERRIDE_CONFIG_UPDATE_EVENTPolicy information point instances related eventsPIP_INSTANCE_EXPORT_EVENT, PIP_INSTANCE_IMPORT_EVENT, PIP_INSTANCE_CREATE_EVENT, PIP_INSTANCE_UPDATE_EVENT, PIP_INSTANCE_DELETE_EVENT, PIP_INSTANCE_SEARCH_EVENTPolicy information point types related eventsPIP_TYPE_SEARCH_EVENTPolicy attachment related eventsPOLICY_ATTACHMENT_CREATE_EVENT, POLICY_ATTACHMENT_DELETE_EVENT, POLICY_ATTACHMENT_PDADMIN_EVENT, POLICY_ATTACHMENT_POLICIES_ SEARCH_EVENT, POLICY_ATTACHMENT_POLICIES_UPDATE _EVENT, POLICY_ATTACHMENT_PUBLISH_EVENT, POLICY_ATTACHMENT_SEARCH_EVENT, POLICY_ATTACHMENT_UNPUBLISH_EVENT, POLICY_ATTACHMENT_UPDATE_EVENT, POLICY_ATTACHMENT_UPDATE_PROPERTIES _EVENTPolicy related eventsPOLICY_CREATE_EVENT POLICY_DELETE_EVENT, POLICY_SEARCH_EVENT, POLICY_UPDATE_EVENTPolicy set related eventsPOLICY_SET_CREATE_EVENT, POLICY_SET_DELETE_EVENT, POLICY_SET_POLICIES_SEARCH_EVENT, POLICY_SET_POLICIES_UPDATE_EVENT, POLICY_SET_SEARCH_EVENT, POLICY_SET_UPDATE_EVENT Risk profile related eventsRISK_PROFILE_CREATE_EVENT, RISK_PROFILE_DELETE_EVENT, RISK_PROFILE_SEARCH_EVENT, RISK_PROFILE_UPDATE_EVENT Runtime policy related eventsRUNTIME_POLICY_DEPLOY_EVENT, RUNTIME_POLICY_IS_DEPLOYED_EVENT, RUNTIME_POLICY_SEARCH_EVENT, RUNTIME_POLICY_UNDEPLOY_EVENTUser knowledge questions related eventsKNOWLEDGE_QUESTIONS_UPDATE_EVENT, KNOWLEDGE_QUESTIONS_DELETE_EVENT, KNOWLEDGE_QUESTIONS_SEARCH_EVENT XPath: CommonBaseEvent/extendedDataElements /[@name= ’ actionInfo’]/children[@name=’ urn:oasis:names:tc:xacml:1.0:action:action-id’]/valuesoutcome Specifies the outcome of the action for which the security event is generated. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type outcome failureReason Provides more information about the outcome. This element is included in the output when the result is FAILURE. XPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’failureReason’ ]/values outcome result Specifies the overall status of the event that is commonly used for filtering. The following values are possible for the status of this element: FAILURE SUCCESSFULXPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’result’]/values userInfoList Provides information about the user who accesses the resource. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. userInfoList appUserName Specifies the name of the user. XPath: CommonBaseEvent/extendedDataElements /[@name=’userInfoList’]/children[@name=’appUserName’]/values resourceInfo Provides information about the resource that is accessed. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. resourceInfo RESTInvocationURI Specifies the URI of the REST interface that is accessed for this management event. XPath: CommonBaseEvent/extendedDataElements /[@name=’resourceInfo’]/children[@name=’RESTInvocationURI’]/values resourceInfo nameOfPolicy Specifies the policies and policy sets that are associated with the policy attachment for the resource as specified by the nameOfResource property. This element is included in the output for policy attachment action-ids. XPath: CommonBaseEvent/extendedDataElements /[@name=’resourceInfo’]/children[@name=’nameOfPolicy’]/values resourceInfo nameOfResource Specifies the name of the resource for a policy attachment. For example: /WebSEAL/security-default/index.html This element is included in the output for policy attachment action-ids. XPath: CommonBaseEvent/extendedDataElements /[@name=’resourceInfo’]/children[@name=’nameOfResource’]/values restManagement Provides optional information regarding the input JSON for this management request. This element is included in the output for some management audit events. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. restManagement json JSON for this management request. This element is included in the output for some management audit events. To enable the inclusion of additional data in an audit event, the administrator must select Enable verbose audit events in the Audit Configuration panel. XPath: CommonBaseEvent/extendedDataElements /[@name=’restManagement’]/children[@name=’json’]/values extensionName Specifies the name of the event class that this event represents. The name indicates any additional elements that are expected to be present within the event. The value for context-based authorization management events is IBM_SECURITY_CBA_AUDIT_MGMT. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. globalInstanceId Specifies the primary identifier for the event. This property must be globally unique and can be used as the primary key for the event. For example: f0c93637-ada2-4afb-9687-47a7ec1fa3a7 This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. msg Specifies more information when the outcome is SUCCESSFUL. This element: Is optional.Is a container element.Does not have a valid XPath. A valid XPath requires a values declaration. Uses the children of the ComponentIdentification element type. reporterComponentId This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. reporterComponentId application Specifies the name of the application that reports the event. For context-based authorization events, the value is set to IBM Security Access Manager. reporterComponentId component Specifies the logical identity of a component. For context-based authorization events, the value is set to Context-Based Authorization. reporterComponentId componentIdType Specifies the format and meaning of the component that is identified by this component identification. For example: ProductName reporterComponentId location Specifies the physical address that corresponds to the location of a component. For example: host name, IP address, or MAC address. reporterComponentId locationType Specifies the format and meaning of the value in the location property. For context-based authorization events, the value is set to FQHostname. sourceComponentId Identifies the component that is affected or was impacted by the event. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. sourceComponentId component Specifies the logical identity of a component. sourceComponentId componentIdType Specifies the format and meaning of the component that is identified by this component identification. For example: ProductName sourceComponentId location Specifies the physical address that corresponds to the location of a component. For example: host name, IP address, or MAC address. sourceComponentId locationType Specifies the format and meaning of the value in the location property. For context-based authorization events, the value is set to FQHostname. Configuring auditingUse the Audit Configuration feature to enable logging of audit events.Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

IBM_SECURITY_CBA_AUDIT_MGMT events

This event type identifies the security context-based management events, such as the creation of risk profiles.

The following table lists the elements that can be displayed in the output of a IBM_SECURITY_CBA_AUDIT_MGMT event. All elements are included in the output, unless indicated otherwise.

Table 264. Elements used in IBM_ SECURITY_CBA_AUDIT_MGMT events

Element
Description

creationTime

Specifies the date and time when the event was issued.

For example: 2013-09-11T19:18:04.140Z

The letter Z in the sample that is shown indicates the UTC format. All time stamps are issued in UTC format. There is no provision for specifying local time.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

actionInfo

Provides information about the management action that is performed on a resource.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

actionInfo action-id
Specifies the action that caused this management event. Possible actions include:

API protection client related events

API_PROTECTION_CLIENT_CREATE_EVENT, API_PROTECTION_CLIENT_DELETE_EVENT, API_PROTECTION_CLIENT_SEARCH_EVENT, API_PROTECTION_CLIENT_SECRET_GENERATE_EVENT, API_PROTECTION_CLIENT_UPDATE_EVENT

API protection definition related events

API_PROTECTION_DEFINITION_CREATE_EVENT, API_PROTECTION_DEFINITION_DELETE_EVENT, API_PROTECTION_DEFINITION_SEARCH_EVENT, API_PROTECTION_DEFINITION_UPDATE_EVENT

Attribute matcher related events

ATTRIBUTE_MATCHER_CREATE_EVENT, ATTRIBUTE_MATCHER_DELETE_EVENT, ATTRIBUTE_MATCHER_SEARCH_EVENT, ATTRIBUTE_MATCHER_UPDATE_EVENT

Attribute related events

ATTRIBUTE_CREATE_EVENT, ATTRIBUTE_DELETE_EVENT, ATTRIBUTE_SEARCH_EVENT, ATTRIBUTE_UPDATE_EVENT

Audit related events

AUDIT_SEARCH_EVENT, AUDIT_UPDATE_EVENT

Authentication mechanism instances related events

AUTH_MECH_INSTANCE_UPDATE_EVENT, AUTH_MECH_INSTANCE_SEARCH_EVENT

Authentication mechanism types related events

AUTH_MECH_TYPE_SEARCH_EVENT

Authentication policy related events

AUTH_POLICY_CREATE_EVENT, AUTH_POLICY_UPDATE_EVENT, AUTH_POLICY_DELETE_EVENT, AUTH_POLICY_SEARCH_EVENT

Bundle related events

BUNDLE_SEARCH_EVENT, BUNDLE_CREATE_EVENT, BUNDLE_UPDATE_EVENT, BUNDLE_DELETE_EVENT, BUNDLE_EXPORT_EVENT, BUNDLE_IMPORT_EVENT

Device related events

DEVICE_DELETE_EVENT, DEVICE_SEARCH_EVENT, DEVICES_FOR_USER_SEARCH_EVENT, DEVICE_USER_ID_SEARCH_EVENT

Extension instances related events

EXTENSION_INSTANCE_SEARCH_EVENT, EXTENSION_INSTANCE_CREATE_EVENT, EXTENSION_INSTANCE_UPDATE_EVENT, EXTENSION_INSTANCE_DELETE_EVENT

Extension related events

EXTENSION_SEARCH_EVENT

Geolocation data related events

GEOLOCATION_DATA_CANCEL_IMPORT_EVENT, GEOLOCATION_DATA_IMPORT_EVENT, GEOLOCATION_DATA_STATUS_IMPORT_EVENT

HVDB related events

HVDB_DELETE_ALL_DATA_EVENT, HVDB_DELETE_USER_DATA_EVENT, HVDB_CANCEL_DELETE_DATA_EVENT, HVDB_DELETE_DEVICES_EVENT, HVDB_STATUS_DELETE_DATA_EVENT, HVDB_DELETE_USER_FROM_DB

Mapping rule related events

MAPPING_RULE_EXPORT_EVENT, MAPPING_RULE_IMPORT_EVENT , MAPPING_RULE_SEARCH_EVENT, MAPPING_RULE_UPDATE_EVENT, MAPPING_RULE_CREATE_EVENT, MAPPING_RULE_DELETE_EVENT 

Obligation related events

OBLIGATION_CREATE_EVENT, OBLIGATION_DELETE_EVENT, OBLIGATION_SEARCH_EVENT, OBLIGATION_UPDATE_EVENT

Override configuration related events

OVERRIDE_CONFIG_SEARCH_EVENT, OVERRIDE_CONFIG_UPDATE_EVENT

Policy information point instances related events

PIP_INSTANCE_EXPORT_EVENT, PIP_INSTANCE_IMPORT_EVENT, PIP_INSTANCE_CREATE_EVENT, PIP_INSTANCE_UPDATE_EVENT, PIP_INSTANCE_DELETE_EVENT, PIP_INSTANCE_SEARCH_EVENT

Policy information point types related events

PIP_TYPE_SEARCH_EVENT

Policy attachment related events

POLICY_ATTACHMENT_CREATE_EVENT, POLICY_ATTACHMENT_DELETE_EVENT, POLICY_ATTACHMENT_PDADMIN_EVENT, POLICY_ATTACHMENT_POLICIES_ SEARCH_EVENT, POLICY_ATTACHMENT_POLICIES_UPDATE _EVENT, POLICY_ATTACHMENT_PUBLISH_EVENT, POLICY_ATTACHMENT_SEARCH_EVENT, POLICY_ATTACHMENT_UNPUBLISH_EVENT, POLICY_ATTACHMENT_UPDATE_EVENT, POLICY_ATTACHMENT_UPDATE_PROPERTIES _EVENT

Policy related events

POLICY_CREATE_EVENT POLICY_DELETE_EVENT, POLICY_SEARCH_EVENT, POLICY_UPDATE_EVENT

Policy set related events

POLICY_SET_CREATE_EVENT, POLICY_SET_DELETE_EVENT, POLICY_SET_POLICIES_SEARCH_EVENT, POLICY_SET_POLICIES_UPDATE_EVENT, POLICY_SET_SEARCH_EVENT, POLICY_SET_UPDATE_EVENT

Risk profile related events

RISK_PROFILE_CREATE_EVENT, RISK_PROFILE_DELETE_EVENT, RISK_PROFILE_SEARCH_EVENT, RISK_PROFILE_UPDATE_EVENT

Runtime policy related events

RUNTIME_POLICY_DEPLOY_EVENT, RUNTIME_POLICY_IS_DEPLOYED_EVENT, RUNTIME_POLICY_SEARCH_EVENT, RUNTIME_POLICY_UNDEPLOY_EVENT

User knowledge questions related events

KNOWLEDGE_QUESTIONS_UPDATE_EVENT, KNOWLEDGE_QUESTIONS_DELETE_EVENT, KNOWLEDGE_QUESTIONS_SEARCH_EVENT

XPath: CommonBaseEvent/extendedDataElements /[@name= ’ actionInfo’]/children[@name=’ urn:oasis:names:tc:xacml:1.0:action:action-id’]/values

outcome

Specifies the outcome of the action for which the security event is generated.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type

outcome failureReason

Provides more information about the outcome.

This element is included in the output when the result is FAILURE.

XPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’failureReason’ ]/values

outcome result

Specifies the overall status of the event that is commonly used for filtering.

The following values are possible for the status of this element:

FAILURE

SUCCESSFUL

XPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’result’]/values

userInfoList

Provides information about the user who accesses the resource.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

userInfoList appUserName

Specifies the name of the user.

XPath: CommonBaseEvent/extendedDataElements /[@name=’userInfoList’]/children[@name=’appUserName’]/values

resourceInfo

Provides information about the resource that is accessed.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

resourceInfo RESTInvocationURI

Specifies the URI of the REST interface that is accessed for this management event.

XPath: CommonBaseEvent/extendedDataElements /[@name=’resourceInfo’]/children[@name=’RESTInvocationURI’]/values

resourceInfo nameOfPolicy

Specifies the policies and policy sets that are associated with the policy attachment for the resource as specified by the nameOfResource property.

This element is included in the output for policy attachment action-ids.

XPath: CommonBaseEvent/extendedDataElements /[@name=’resourceInfo’]/children[@name=’nameOfPolicy’]/values

resourceInfo nameOfResource

Specifies the name of the resource for a policy attachment. For example: /WebSEAL/security-default/index.html

This element is included in the output for policy attachment action-ids.

XPath: CommonBaseEvent/extendedDataElements /[@name=’resourceInfo’]/children[@name=’nameOfResource’]/values

restManagement

Provides optional information regarding the input JSON for this management request.

This element is included in the output for some management audit events.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

restManagement json

JSON for this management request.

This element is included in the output for some management audit events.

Note: To enable the inclusion of additional data in an audit event, the administrator must select Enable verbose audit events in the Audit Configuration panel.

XPath: CommonBaseEvent/extendedDataElements /[@name=’restManagement’]/children[@name=’json’]/values

extensionName

Specifies the name of the event class that this event represents. The name indicates any additional elements that are expected to be present within the event. The value for context-based authorization management events is IBM_SECURITY_CBA_AUDIT_MGMT.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

globalInstanceId

Specifies the primary identifier for the event. This property must be globally unique and can be used as the primary key for the event.

For example: f0c93637-ada2-4afb-9687-47a7ec1fa3a7

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

msg

Specifies more information when the outcome is SUCCESSFUL.

This element:

Is optional.

Is a container element.

Does not have a valid XPath. A valid XPath requires a values declaration.

Uses the children of the ComponentIdentification element type.

reporterComponentId

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

reporterComponentId application

Specifies the name of the application that reports the event. For context-based authorization events, the value is set to IBM Security Access Manager.

reporterComponentId component

Specifies the logical identity of a component. For context-based authorization events, the value is set to Context-Based Authorization.

reporterComponentId componentIdType

Specifies the format and meaning of the component that is identified by this component identification.

For example: ProductName

reporterComponentId location

Specifies the physical address that corresponds to the location of a component.

For example: host name, IP address, or MAC address.

reporterComponentId locationType

Specifies the format and meaning of the value in the location property. For context-based authorization events, the value is set to FQHostname.

sourceComponentId

Identifies the component that is affected or was impacted by the event.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

sourceComponentId component

Specifies the logical identity of a component.

sourceComponentId componentIdType

Specifies the format and meaning of the component that is identified by this component identification.

For example: ProductName

sourceComponentId location

Specifies the physical address that corresponds to the location of a component.

For example: host name, IP address, or MAC address.

sourceComponentId locationType

Specifies the format and meaning of the value in the location property. For context-based authorization events, the value is set to FQHostname.

Parent topic: Auditing Advanced Access Control

Related tasks:

Configuring auditing

IBM_SECURITY_CBA_AUDIT_RTE eventsIBM_SECURITY_CBA_AUDIT_RTE eventsIBM_SECURITY_CBA_AUDIT_RTE eventsThis event type identifies the security context-based authorization events, such as device registration.IBM_SECURITY_CBA_AUDIT_RTE eventseventsIBM_SECURITY_CBA_AUDIT_RTE eventsauthorization eventsIBM_SECURITY_CBA_AUDIT_RTE eventsaudit eventsIBM_SECURITY_CBA_AUDIT_RTE events The following table lists the elements that can be shown in the output of an IBM_SECURITY_CBA_AUDIT_RTE event. All elements are included in the output, unless indicated otherwise. Elements used in IBM_SECURITY_CBA_AUDIT_RTE eventsElementDescriptioncreationTime Specifies the date and time when the event was issued. For example: 2013-09-11T19:18:04.140Z The letter Z in the sample that is shown indicates the UTC format. All time stamps are issued in UTC format. There is no provision for specifying local time. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. actionInfo Provides information about the management action that is performed on a resource. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. actionInfo action-id Specifies the action that caused this event. Possible actions include: CALCULATE_RISK_SCORE_EVENTDEVICE_DELETION_EVENTDEVICE_REGISTRATION_EVENTJAVASCRIPT_EVENT XPath: CommonBaseEvent/extendedDataElements /[@name= ’ actionInfo’]/children[@name=’ urn:oasis:names:tc:xacml:1.0:action:action-id’ ]/values outcome Specifies the outcome of the action for which the security event is generated. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type outcome failureReason Provides additional information about the outcome. Included in the output when the result is FAILURE. XPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’failureReason’]/values outcome result Specifies the overall status of the event that is commonly used for filtering. The following values are possible for the status: FAILURE SUCCESSFULXPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’result’]/values userInfoList Provides information about the user who accesses the resource. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. userInfoList appUserName Specifies the name of the user. XPath: CommonBaseEvent/extendedDataElements /[@name=’userInfoList’]/children[@name=’appUserName’]/values extensionName Specifies the name of the event class that this event represents. The name indicates any additional elements that are expected to be present within the event. The value for context-based authorization runtime events is IBM_SECURITY_CBA_AUDIT_RTE. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. globalInstanceId Specifies the primary identifier for the event. This property must be globally unique and can be used as the primary key for the event. For example: f0c93637-ada2-4afb-9687-47a7ec1fa3a7 This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. msg Specifies additional information when the outcome is SUCCESSFUL. This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type. Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

IBM_SECURITY_CBA_AUDIT_RTE events

This event type identifies the security context-based authorization events, such as device registration.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_CBA_AUDIT_RTE event. All elements are included in the output, unless indicated otherwise.

Table 265. Elements used in IBM_SECURITY_CBA_AUDIT_RTE events

Element
Description

creationTime

Specifies the date and time when the event was issued.

For example: 2013-09-11T19:18:04.140Z

The letter Z in the sample that is shown indicates the UTC format. All time stamps are issued in UTC format. There is no provision for specifying local time.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

actionInfo

Provides information about the management action that is performed on a resource.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

actionInfo action-id

Specifies the action that caused this event.

Possible actions include:

CALCULATE_RISK_SCORE_EVENT

DEVICE_DELETION_EVENT

DEVICE_REGISTRATION_EVENT

JAVASCRIPT_EVENT

XPath: CommonBaseEvent/extendedDataElements /[@name= ’ actionInfo’]/children[@name=’ urn:oasis:names:tc:xacml:1.0:action:action-id’ ]/values

outcome

Specifies the outcome of the action for which the security event is generated.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type

outcome failureReason

Provides additional information about the outcome.

Included in the output when the result is FAILURE.

XPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’failureReason’]/values

outcome result

Specifies the overall status of the event that is commonly used for filtering.

The following values are possible for the status:

FAILURE

SUCCESSFUL

XPath: CommonBaseEvent/extendedDataElements /[@name=’outcome’]/children[@name=’result’]/values

userInfoList

Provides information about the user who accesses the resource.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

userInfoList appUserName

Specifies the name of the user.

XPath: CommonBaseEvent/extendedDataElements /[@name=’userInfoList’]/children[@name=’appUserName’]/values

extensionName

Specifies the name of the event class that this event represents. The name indicates any additional elements that are expected to be present within the event. The value for context-based authorization runtime events is IBM_SECURITY_CBA_AUDIT_RTE.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

globalInstanceId

Specifies the primary identifier for the event. This property must be globally unique and can be used as the primary key for the event.

For example: f0c93637-ada2-4afb-9687-47a7ec1fa3a7

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

msg

Specifies additional information when the outcome is SUCCESSFUL.

This element is a container element and has no valid XPath. A valid XPath requires a values declaration. This container element uses the children of the ComponentIdentification element type.

Parent topic: Auditing Advanced Access Control

IBM_SECURITY_RTSS_AUDIT_AUTHZ eventsIBM_SECURITY_RTSS_AUDIT_AUTHZ eventsIBM_SECURITY_RTSS_AUDIT_AUTHZ eventsThis event type identifies the authorization decision events for runtime security services.IBM_SECURITY_RTSS_AUDIT_AUTHZ eventsRuntime security services generates an authorization decision event record if both of the following conditions occur:The runtime security services component is asked for an access decision Auditing is enabledIn addition to the base Common Base Event content, runtime security services authorization decision records contain authorization-specific properties. These authorization-specific properties are defined in the Common Base Event Extensions for Security Events specification with the ExtendedDataElement.The following table lists the event properties that are included in the output of an IBM_SECURITY_RTSS_AUDIT_AUTHZ event record. All elements are included in the output, unless indicated otherwise.Properties used in IBM_SECURITY_RTSS_AUDIT_AUTHZ eventsElementDescription and valuesaccessDecisionPresent when the result is SUCCESSFULThis property specifies the decision of the authorization call.Possible element values include: PermitDeny NotApplicable IndeterminateIf a Permit decision is returned with obligations, then a ConditionalPermit decision is recorded in the event.accessDecisionReasonPresent when accessDecision is DENY This property provides more information about the denial of the access decision.actionNot always in output. This property specifies the action that caused the authorization event.outcomeSpecifies the outcome of the action for which the security event is being generated.This ExtendedDataElement element does not have a value declaration.This container element uses the children of the outcomeType element type.outcome failureReasonNot always in output. This property provides more information about the outcome.outcome majorStatusSpecifies the major status code.outcome minorStatusNot always in output. This property specifies the minor status code.outcome resultSpecifies the overall status of the event. This element is also used for filtering.Element values are UNSUCCESSFUL if an error condition occurs that prevents standard processing. Element values are SUCCESSFUL when the error condition starts standard processing.permissionInfoProvides information about access permissions.This ExtendedDataElement element has no value declaration. This container element uses the children of the PermissionInfoType element type.permissionInfo checked Specifies permissions that are checked during the authorization call.permissionInfo deniedNot always in output. This property specifies the permissions that are denied among the permissions that are requested.permissionInfo grantedNot always in output. This property specifies permissions that are granted.policyInfoNot always in output. This property provides information about policies that are attached to the resource or the container of a resource.This ExtendedDataElement element does not have a value declaration.This container element uses the children of the PolicyInfoType element type.policyInfo attributesNot always in output. This property specifies attributes that are associated with a policy.policyInfo descriptionNot always in output. This property provides a description of the policy.policyInfonameNot always in output. This property specifies the name of the policy.policyInfo typeNot always in output. This property specifies the type of the policy.registryInfo Not always in output. This property provides information about the registry that is involved in the authentication. This ExtendedDataElement element does not have a value declaration.This container element uses the children of the RegistryInfoType element type.registryInfo serverLocationNot always in output. This property specifies where the registry server is located.resourceInfo Provides information about the resource that is accessed.This ExtendedDataElement element has no a value declaration.This container element uses the children of the resourceInfoType element type.resourceInfo attributes Specifies the attributes for the resource.resourceInfo nameInApp Not always in output.This property specifies the name of the resource in the context of the application.resourceInfo nameInPolicy Specifies the name of the resource when it applies a policy to the resource. resourceInfo type Specifies the type of the resource.userInfoProvides information about each user in the delegation chain.This ExtendedDataElement element has no a value declaration. This container element uses the children of the UserInfoType element type.userInfo appUserNamePresent when the accessing subject is authenticated. This property specifies the name of a user within an application.userInfo attributesNot always in output. This property provides more user information.userInfo callerList Not always in output. This property specifies a list of names that represents the identities of a user.userInfo location Not always in output. This property specifies the location of the user.userInfo locationType Not always in output. This property specifies the type of location.userInfo realm Not always in output. This property specifies the registry partition to which the user belongs.userInfo registryUserName Not always in output. This property specifies the name of the user in the registry.userInfo sessionId Not always in output. This property specifies the ID for the session that belongs to the user.userInfo uniqueId Not always in output. This property specifies the unique identifier that belongs to the user within an application.creationTime Specifies the date and time when the event was issued. For example: 2008-09-11T19:18:04.140Z The letter Z in the example indicates the UTC format. All time stamps are issued in UTC format. There is no provision for specifying local time. contextDataElementSpecifies the ContextDataElement type, which defines the contexts that each event references. This element contains data that assists with problem diagnostic procedures by correlating messages or events that are generated during the execution of a unit of work.contextDataElement typeSpecifies the data type of the contextValue property.contextDataElement name Specifies the name of the application that created the contextDataElement.contextDataElement contextValueSpecifies the value of the context regarding the implementation of the context.extensionName Specifies the name of the event class that the extensionName event represents.The extensionName event indicates more elements that are expected to be present within the event. The value for runtime security services is the following value: IBM_SECURITY_RTSS_ AUDIT_AUTHZ globalInstanceId Specifies the primary identifier for the event. This property must be globally unique and can be used as the primary key for the event.For example:f5e6bcc5-d1e8-4638- 8f84-3ba29ca950b2msgProvides the text that accompanies the event.This element is typically the resolved message string in human readable format that is rendered for a specific locale.The following example uses runtime security services data: Subject cn=wasadmin,c=us requests access to the http://localhost:9081/rtss/test/jaxws/echo/EchoService protected resource.situation Specifies the situation that caused the event to be reported.situation categoryName Specifies the category type of the situation that caused the event to be reported.situation situationType Specifies the type of situation that caused the event to be reported.situation reportCategorySpecifies the category of the reported situation. This element is used if the value that belongs to the element is STATUS.situation reasoningScopeDefines whether this situation has either of the following impacts:Internal-only impact.Potential external impact.This element is used if the element value is either of the following values: INTERNALEXTERNALsourceComponentId Identifies the component that is impacted by the event. This element has no a value declaration. This container element uses the children of the ComponentIdType element type.sourceComponentId application Specifies the name of the application. The value that belongs to this element is the following: IBM runtime security servicessourceComponentId component Specifies the logical identity of a component.sourceComponentId componentIdTypeSpecifies the format of the component and meaning of the component that is identified by this componentIdentification. For example: ProductNamesourceComponentId componentType Specifies a well-defined name that is used to characterize all of the instances that belong to this component.sourceComponentIdlocationSpecifies the physical address that corresponds to the location of a component. For example: Host name, IP address, or MAC address.sourceComponentIdlocationTypePresent if available. This property specifies the format and meaning of the value in the location property.For runtime security services, the value is set to Not available if the meaning of the location element value is not determined. The following is sample runtime security services data: ipAddress.sourceComponentId processIdNot always in output. This property identifies the process ID of the running component or subcomponent that generated the event.sourceComponentId subComponentNot always in output. This property specifies a further distinction for the logical component property of the event. version Specifies a string that identifies the version of the event. The element value is 2.0.Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.

IBM_SECURITY_RTSS_AUDIT_AUTHZ events

This event type identifies the authorization decision events for runtime security services.

Runtime security services generates an authorization decision event record if both of the following conditions occur:

The runtime security services component is asked for an access decision

Auditing is enabled

In addition to the base Common Base Event content, runtime security services authorization decision records contain authorization-specific properties. These authorization-specific properties are defined in the Common Base Event Extensions for Security Events specification with the ExtendedDataElement.

The following table lists the event properties that are included in the output of an IBM_SECURITY_RTSS_AUDIT_AUTHZ event record. All elements are included in the output, unless indicated otherwise.

Table 266. Properties used in IBM_SECURITY_RTSS_AUDIT_AUTHZ events

Element
Description and values

accessDecision
Present when the result is SUCCESSFUL

This property specifies the decision of the authorization call.

Possible element values include:

Permit

Deny

NotApplicable

Indeterminate

If a Permit decision is returned with obligations, then a ConditionalPermit decision is recorded in the event.

accessDecisionReason
Present when accessDecision is DENY

This property provides more information about the denial of the access decision.

action
Not always in output.

This property specifies the action that caused the authorization event.

outcome
Specifies the outcome of the action for which the security event is being generated.

This ExtendedDataElement element does not have a value declaration.

This container element uses the children of the outcomeType element type.

outcome failureReason
Not always in output.

This property provides more information about the outcome.

outcome majorStatus
Specifies the major status code.

outcome minorStatus
Not always in output.

This property specifies the minor status code.

outcome result
Specifies the overall status of the event. This element is also used for filtering.

Element values are UNSUCCESSFUL if an error condition occurs that prevents standard processing. Element values are SUCCESSFUL when the error condition starts standard processing.

permissionInfo
Provides information about access permissions.

This ExtendedDataElement element has no value declaration.

This container element uses the children of the PermissionInfoType element type.

permissionInfo checked
Specifies permissions that are checked during the authorization call.

permissionInfo denied
Not always in output.

This property specifies the permissions that are denied among the permissions that are requested.

permissionInfo granted
Not always in output.

This property specifies permissions that are granted.

policyInfo
Not always in output.

This property provides information about policies that are attached to the resource or the container of a resource.

This ExtendedDataElement element does not have a value declaration.

This container element uses the children of the PolicyInfoType element type.

policyInfo attributes
Not always in output.

This property specifies attributes that are associated with a policy.

policyInfo description
Not always in output.

This property provides a description of the policy.

policyInfoname
Not always in output.

This property specifies the name of the policy.

policyInfo type
Not always in output.

This property specifies the type of the policy.

registryInfo
Not always in output.

This property provides information about the registry that is involved in the authentication.

This ExtendedDataElement element does not have a value declaration.

This container element uses the children of the RegistryInfoType element type.

registryInfo serverLocation
Not always in output.

This property specifies where the registry server is located.

resourceInfo
Provides information about the resource that is accessed.

This ExtendedDataElement element has no a value declaration.

This container element uses the children of the resourceInfoType element type.

resourceInfo attributes
Specifies the attributes for the resource.

resourceInfo nameInApp
Not always in output.

This property specifies the name of the resource in the context of the application.

resourceInfo nameInPolicy
Specifies the name of the resource when it applies a policy to the resource.

resourceInfo type
Specifies the type of the resource.

userInfo
Provides information about each user in the delegation chain.

This ExtendedDataElement element has no a value declaration.

This container element uses the children of the UserInfoType element type.

userInfo appUserName
Present when the accessing subject is authenticated.

This property specifies the name of a user within an application.

userInfo attributes
Not always in output.

This property provides more user information.

userInfo callerList
Not always in output.

This property specifies a list of names that represents the identities of a user.

userInfo location
Not always in output.

This property specifies the location of the user.

userInfo locationType
Not always in output.

This property specifies the type of location.

userInfo realm
Not always in output.

This property specifies the registry partition to which the user belongs.

userInfo registryUserName
Not always in output.

This property specifies the name of the user in the registry.

userInfo sessionId
Not always in output.

This property specifies the ID for the session that belongs to the user.

userInfo uniqueId
Not always in output.

This property specifies the unique identifier that belongs to the user within an application.

creationTime
Specifies the date and time when the event was issued.

For example: 2008-09-11T19:18:04.140Z

The letter Z in the example indicates the UTC format. All time stamps are issued in UTC format. There is no provision for specifying local time.

contextDataElement
Specifies the ContextDataElement type, which defines the contexts that each event references.

This element contains data that assists with problem diagnostic procedures by correlating messages or events that are generated during the execution of a unit of work.

contextDataElement type
Specifies the data type of the contextValue property.

contextDataElement name
Specifies the name of the application that created the contextDataElement.

contextDataElement contextValue
Specifies the value of the context regarding the implementation of the context.

extensionName
Specifies the name of the event class that the extensionName event represents.

The extensionName event indicates more elements that are expected to be present within the event.

The value for runtime security services is the following value:

IBM_SECURITY_RTSS_

AUDIT_AUTHZ

globalInstanceId
Specifies the primary identifier for the event.

This property must be globally unique and can be used as the primary key for the event.

For example:f5e6bcc5-d1e8-4638- 8f84-3ba29ca950b2

msg
Provides the text that accompanies the event.

This element is typically the resolved message string in human readable format that is rendered for a specific locale.

The following example uses runtime security services data: Subject cn=wasadmin,c=us requests access to the http://localhost:9081/rtss/test/jaxws/echo/EchoService protected resource.

situation
Specifies the situation that caused the event to be reported.

situation categoryName
Specifies the category type of the situation that caused the event to be reported.

situation situationType
Specifies the type of situation that caused the event to be reported.

situation reportCategory
Specifies the category of the reported situation.

This element is used if the value that belongs to the element is STATUS.

situation reasoningScope

Defines whether this situation has either of the following impacts:

Internal-only impact.

Potential external impact.

This element is used if the element value is either of the following values:

INTERNAL

EXTERNAL

sourceComponentId
Identifies the component that is impacted by the event.

This element has no a value declaration.

This container element uses the children of the ComponentIdType element type.

sourceComponentId application
Specifies the name of the application.

The value that belongs to this element is the following: IBM® runtime security services

sourceComponentId component
Specifies the logical identity of a component.

sourceComponentId componentIdType
Specifies the format of the component and meaning of the component that is identified by this componentIdentification.

For example: ProductName

sourceComponentId componentType
Specifies a well-defined name that is used to characterize all of the instances that belong to this component.

sourceComponentIdlocation
Specifies the physical address that corresponds to the location of a component.

For example: Host name, IP address, or MAC address.

sourceComponentIdlocationType
Present if available.

This property specifies the format and meaning of the value in the location property.

For runtime security services, the value is set to Not available if the meaning of the location element value is not determined.

The following is sample runtime security services data: ipAddress.

sourceComponentId processId
Not always in output.

This property identifies the process ID of the running component or subcomponent that generated the event.

sourceComponentId subComponent
Not always in output.

This property specifies a further distinction for the logical component property of the event.

version
Specifies a string that identifies the version of the event.

The element value is 2.0.

Parent topic: Auditing Advanced Access Control

Deploying pending changesDeploying pending changesDeploying changesSome configuration and administration changes require an extra deployment step.deploying changespending changesWhen you use the graphical user interface on the appliance to specify changes, some configuration and administration tasks take effect immediately. Other tasks require a deployment step to take effect. For these tasks, the appliance gives you a choice of deploying immediately or deploying later. When you must make multiple changes, you can wait until all changes are complete, and then deploy all of them at one time.When a deployment step is required, the user interface presents a message that says that there is an undeployed change. The number of pending changes is displayed in the message, and increments for each change you make.If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.When you finish making configuration changes, select Click here to review the changes or apply them to the system.The Deploy Pending Changes window is displayed.Select one of the following options:CancelDo not deploy the changes now. Retain the undeployed configuration changes. The appliance user interface returns to the previous panel.Roll BackAbandon configuration changes. A message is displayed, stating that the pending changes were reverted. The appliance user interface returns to the previous panel.DeployDeploy all configuration changes.When you select Deploy, a system message is displayed, stating that the changes were deployed.If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.Auditing Advanced Access ControlThese topics describe auditing for Advanced Access Control. With the Advanced Access Control activation level, you can configure and manage audit events for context-based access.Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

Deploying pending changes

Some configuration and administration changes require an extra deployment step.

About this task

When you use the graphical user interface on the appliance to specify changes, some configuration and administration tasks take effect immediately. Other tasks require a deployment step to take effect. For these tasks, the appliance gives you a choice of deploying immediately or deploying later. When you must make multiple changes, you can wait until all changes are complete, and then deploy all of them at one time.

When a deployment step is required, the user interface presents a message that says that there is an undeployed change. The number of pending changes is displayed in the message, and increments for each change you make.

Note: If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.

Procedure

When you finish making configuration changes, select Click here to review the changes or apply them to the system.

The Deploy Pending Changes window is displayed.

Select one of the following options:

Option
Description

Cancel
Do not deploy the changes now.

Retain the undeployed configuration changes. The appliance user interface returns to the previous panel.

Roll Back
Abandon configuration changes.

A message is displayed, stating that the pending changes were reverted. The appliance user interface returns to the previous panel.

Deploy
Deploy all configuration changes.

When you select Deploy, a system message is displayed, stating that the changes were deployed.

If any of the changes require the runtime server to be restarted, the restart occurs automatically when you select Deploy. The runtime server will then be unavailable for a period of time until the restart completes.

Parent topic: Auditing Advanced Access Control

Parent topic: Auditing Federation

Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.AuditingThe IBM Security Access Manager provides information about configuring and managing audit events.Federation auditing eventsThis section lists the audit elements that are available for each audit event type.IBM_SECURITY_AUTHN_eventsThis event type is generated by the authentication service when it authenticates a user accessing a protected resource. IBM_SECURITY_AUTHN_TERMINATE eventThis audit event is generated when a user is logged off.IBM_SECURITY_ENCRYPTION eventsThis event is generated whenever data is encrypted.IBM_SECURITY_FEDERATION eventsThis event type is generated when a federation event occurs.IBM_SECURITY_MGMT_AUDIT eventsThis event type provides information about changes to the auditing settings; for example, if auditing is enabled or disabled or if auditing is set for specific transactions.IBM_SECURITY_MGMT_POLICY eventsThis event type is generated by federation runtime management calls.IBM_SECURITY_RUNTIME events (Runtime start)This event type is generated when the runtime is started.IBM_SECURITY_RUNTIME events (SAML2 message transmission)This event type is generated when transmitting SAML2 authentication request and response messages.IBM_SECURITY_TRUST eventsThis event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.Deploying pending changesSome configuration and administration changes require an extra deployment step.

Auditing Federation

These topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

Federation auditing events
This section lists the audit elements that are available for each audit event type.

IBM_SECURITY_AUTHN_events
This event type is generated by the authentication service when it authenticates a user accessing a protected resource.

IBM_SECURITY_AUTHN_TERMINATE event
This audit event is generated when a user is logged off.

IBM_SECURITY_ENCRYPTION events
This event is generated whenever data is encrypted.

IBM_SECURITY_FEDERATION events
This event type is generated when a federation event occurs.

IBM_SECURITY_MGMT_AUDIT events
This event type provides information about changes to the auditing settings; for example, if auditing is enabled or disabled or if auditing is set for specific transactions.

IBM_SECURITY_MGMT_POLICY events
This event type is generated by federation runtime management calls.

IBM_SECURITY_RUNTIME events (Runtime start)
This event type is generated when the runtime is started.

IBM_SECURITY_RUNTIME events (SAML2 message transmission)
This event type is generated when transmitting SAML2 authentication request and response messages.

IBM_SECURITY_TRUST events
This event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.

Deploying pending changes
Some configuration and administration changes require an extra deployment step.

Parent topic: Auditing

Federation auditing eventsThis section lists the audit elements that are available for each audit event type.auditeventscommon elementsaudit eventsaudit eventscommon elementsUse the instructions in Configuring auditing on the applianceUse the Audit Configuration feature to enable logging of audit events. to configure auditing on the appliance.Federation supports the following auditing events:IBM_SECURITY_TRUSTIBM_SECURITY_RUNTIMEThis section describes the available elements for each event type.Common elements for all eventsThe following elements are included with all security events:ContextDataElementsSourceComponentIdelementsSituationOutcomeContextDataElementsThe contextId value, which is specified on the type attribute, is included in the ContextDataElements element to correlate all events that are associated with a single transaction.Attributes and elements of the ContextDataElements elementAttributeValuenameSecurity Event FactoryThe XPath is:CommonBaseEvent/contextDataElements/@nametypeeventTrailIdThe XPath is:CommonBaseEvent/contextDataElements/@typecontextId This element is a container element for the eventTrailId value; it does not have an XPath value.eventTrailIdThe event trail identifier value, for example, FIM_116320b90110104ab7ce9df3453615a1+729829786 The XPath is:CommonBaseEvent/contextDataElements/[@type='eventTrailId']/contextIdThe following are XML-formatted examples of CBE event headers containing entries for the ContextDataElements element. These entries illustrate how separate events are correlated for a single transaction.<CommonBaseEvent creationTime="2007-01-31T20:59:57.625Z" extensionName="IBM_SECURITY_TRUST" globalInstanceId="CE4454A122E10AB044A1DBB16E020E1D80" sequenceNumber="1" version="1.0.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId> </contextDataElements> ... </CommonBaseEvent><CommonBaseEvent creationTime="2007-01-31T20:59:57.765Z" extensionName="IBM_SECURITY_TRUST" globalInstanceId="CE4454A122E10AB044A1DBB16E02213050" sequenceNumber="2" version="1.0.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId> </contextDataElements> ... </CommonBaseEvent>SourceComponentId elementThe SourceComponentId is an identifier that represents the source that generates the event.Attributes for the SourceComponentId elementAttributeValueapplicationITFIM#8.0.0The XPath is:CommonBaseEvent/sourceComponentId/ @applicationcomponentThe XPath is:CommonBaseEvent/sourceComponentId/ @componentcomponentIdType ProductNameThe XPath is:CommonBaseEvent/sourceComponentId/ @componentIdTypecomponentTypehttp://www.ibm.com/namespaces/autonomic/Tivoli_componentTypesThe XPath is:CommonBaseEvent/sourceComponentId/ @componentTypeexecutionEnvironment<OS name>#<OS Architecture>#<OS.version>The XPath is:CommonBaseEvent/sourceComponentId/ @executionEnvironmentlocation<hostname>The XPath is:CommonBaseEvent/extendedDataElements [@name='registryInfo']/children [@name='location']/valueslocationTypeFQHostnameThe XPath is:CommonBaseEvent/sourceComponentId/ @locationTypesubComponent<classname>The XPath is:CommonBaseEvent/sourceComponentId/ @subComponentSituation elementThe Situation element describes the circumstance that caused the audit event.Attributes for the Situation elementAttributeValuecategoryNameReportSituationThe XPath is:CommonBaseEvent/situation/ @categoryNamereasoningScopeINTERNALThe XPath is:CommonBaseEvent/situation/situationType/ @reasoningScopereportCategorySECURITYThe XPath is:CommonBaseEvent/situation/situationType/ @reportCategoryOutcome elementThe Outcome element is the result of the action for which the security event is being generated.Attributes for the Outcome elementAttributeValuefailureReasonThe XPath is:CommonBaseEvent/extendedDataElements [@name='outcome']/children [@name='failureReason']/valuesmajorStatusThe XPath is:CommonBaseEvent/extendedDataElements [@name='outcome']/children [@name='majorStatus']/valuesresultThe XPath is:CommonBaseEvent/extendedDataElements [@name='outcome']/children [@name='result']/valuesFederation does not use the ReporterComponentId field.Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

Federation auditing events

This section lists the audit elements that are available for each audit event type.

Use the instructions in Configuring auditing on the appliance to configure auditing on the appliance.

Federation supports the following auditing events:

IBM_SECURITY_TRUST

IBM_SECURITY_RUNTIME

This section describes the available elements for each event type.

Common elements for all events

The following elements are included with all security events:

ContextDataElements

SourceComponentIdelements

Situation

Outcome

ContextDataElements

The contextId value, which is specified on the type attribute, is included in the ContextDataElements element to correlate all events that are associated with a single transaction.

Table 267. Attributes and elements of the ContextDataElements element

Attribute
Value

name
Security Event Factory

The XPath is:

CommonBaseEvent/contextDataElements/@name

type
eventTrailId

The XPath is:

CommonBaseEvent/contextDataElements/@type

contextId
This element is a container element for the eventTrailId value; it does not have an XPath value.

eventTrailId
The event trail identifier value, for example, FIM_116320b90110104ab7ce9df3453615a1+729829786

The XPath is:

CommonBaseEvent/contextDataElements/[@type='eventTrailId']/contextId

The following are XML-formatted examples of CBE event headers containing entries for the ContextDataElements element. These entries illustrate how separate events are correlated for a single transaction.

<CommonBaseEvent
	creationTime="2007-01-31T20:59:57.625Z"
	extensionName="IBM_SECURITY_TRUST"
	globalInstanceId="CE4454A122E10AB044A1DBB16E020E1D80"
	sequenceNumber="1" version="1.0.1">
	<contextDataElements name="Security Event Factory" 	type="eventTrailId">
		<contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId>
	</contextDataElements>
...
</CommonBaseEvent>

<CommonBaseEvent
	creationTime="2007-01-31T20:59:57.765Z"
	extensionName="IBM_SECURITY_TRUST"
	globalInstanceId="CE4454A122E10AB044A1DBB16E02213050"
	sequenceNumber="2" version="1.0.1">
	<contextDataElements name="Security Event Factory" type="eventTrailId">
		<contextId>FIM_79f4e4c801101db5aba48cd8e0212be7+656317861</contextId>
	</contextDataElements>
...
</CommonBaseEvent>

SourceComponentId element

The SourceComponentId is an identifier that represents the source that generates the event.

Table 268. Attributes for the SourceComponentId element

Attribute
Value

application
ITFIM#8.0.0

The XPath is:

CommonBaseEvent/sourceComponentId/
@application

component

The XPath is:

CommonBaseEvent/sourceComponentId/
@component

componentIdType
ProductName

The XPath is:

CommonBaseEvent/sourceComponentId/
@componentIdType

componentType
http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes

The XPath is:

CommonBaseEvent/sourceComponentId/
@componentType

executionEnvironment
<OS name>#<OS Architecture>#<OS.version>

The XPath is:

CommonBaseEvent/sourceComponentId/
@executionEnvironment

location
<hostname>

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='registryInfo']/children
[@name='location']/values

locationType
FQHostname

The XPath is:

CommonBaseEvent/sourceComponentId/
@locationType

subComponent
<classname>

The XPath is:

CommonBaseEvent/sourceComponentId/
@subComponent

Situation element

The Situation element describes the circumstance that caused the audit event.

Table 269. Attributes for the Situation element

Attribute
Value

categoryName
ReportSituation

The XPath is:

CommonBaseEvent/situation/
@categoryName

reasoningScope
INTERNAL

The XPath is:

CommonBaseEvent/situation/situationType/
@reasoningScope

reportCategory
SECURITY

The XPath is:

CommonBaseEvent/situation/situationType/
@reportCategory

Outcome element

The Outcome element is the result of the action for which the security event is being generated.

Table 270. Attributes for the Outcome element

Attribute
Value

failureReason

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='outcome']/children
[@name='failureReason']/values

majorStatus

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='outcome']/children
[@name='majorStatus']/values

result

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='outcome']/children
[@name='result']/values

Note: Federation does not use the ReporterComponentId field.

Parent topic: Auditing Federation

IBM_SECURITY_AUTHN_eventsIBM_SECURITY_AUTHN_eventsIBM_SECURITY_AUTHN_eventsThis event type is generated by the authentication service when it authenticates a user accessing a protected resource. IBM_SECURITY_AUTHN eventsThe following table lists the elements that can be shown in the output of an IBM_SECURITY_AUTHN event. All elements are included in the output, unless indicated otherwise. Elements for an IBM_SECURITY_AUTHN eventElementDescriptionactionOptionally specifies the HTTP method on the requested resource or the operation that is performed by the provider of the authentication service.The XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesauthnProviderThe provider of the authentication service.Sample data: com.tivoli.am.fim.authsvc.protocol.delegate.AuthSvcDelegate com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthnticatorThe XPath is:CommonBaseEvent/extendedDataElements [@name='authnProvider']/valuesauthnScopeOptionally specifies the transaction identifier of the authentication policy. Sample data: 94434b2a-748e-42fe-af3d-67db04aa4ba0The XPath is:CommonBaseEvent/extendedDataElements [@name='authnScope']/valuesauthnTypeThe URI identifier of the authentication policy. Sample data: urn:ibm:security:authentication:asf:password_hotpThe XPath is:CommonBaseEvent/extendedDataElements [@name='authnType']/valuespartnerThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='partner']/valuesprogNameOptionally specifies the URL of the requested resource. Sample data: http://www.example.comThe XPath is:CommonBaseEvent/extendedDataElements [@name='progName']/valuestokenTypeThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='tokenType']/valuestrustRelationshipThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as 'Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='trustRelationship']/valuesuserInfo.appUserNameOptionally specifies information about the user who is authenticating.The XPath is:CommonBaseEvent/extendedDataElements [@name='userInfoList']/children[1]/children [@name='appUserName']/valuesuserInfo.attributesOptionally specifies the following types of additional information about user data that are audited during authentication: licenseFileMetadata Metadata that is defined in the license agreement.licenseFileNameThe license file name. userActionThe action that the user takes when the End-User License Agreement authentication mechanism presents the license agreement. The user can accept the license agreement or decline the license agreement. The XPath is: CommonBaseEvent/extendedDataElements [@name='userInfoList']/children [@name='userInfo'] /children [@name='attributes']/childrenxmlTokenTypeThe authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.The XPath is:CommonBaseEvent/extendedDataElements [@name='xmlTokenType']/valuesSample of an IBM_SECURITY_AUTHN eventThe following example shows one event generated by the runtime for a two-factor authentication policy requiring both username password and one-time password authentications: <CommonBaseEvent creationTime="2014-02-15T18:50:05.026Z" extensionName="IBM_SECURITY_AUTHN" globalInstanceId="FIM36e24f6301441708947ceef443526" sequenceNumber="2" version="1.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_36e24f62014415f59913eef443526e68+1246005647</contextId> </contextDataElements> <extendedDataElements name="userInfoList" type="noValue"> <children name="userInfo" type="noValue"> <children name="registryUserName" type="string"> <values>Not Available</values> </children> <children name="appUserName" type="string"> <values>test_user</values> </children> </children> </extendedDataElements> <extendedDataElements name="tokenType" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="authnProvider" type="string"> <values>com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator</values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>verify</values> </extendedDataElements> <extendedDataElements name="authnType" type="string"> <values>urn:ibm:security:authentication:asf:password_hotp</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"> <values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"> <values>0</values> </children> </extendedDataElements> <extendedDataElements name="trustRelationship" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="progName" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="authnScope" type="string"> <values>Not Available</values> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64" location="example" locationType="FQHostname" subComponent="com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator" threadId="Default Executor-thread-60" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_AUTHN_events

This event type is generated by the authentication service when it authenticates a user accessing a protected resource.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_AUTHN event. All elements are included in the output, unless indicated otherwise.

Table 261. Table 271. Elements for an IBM_SECURITY_AUTHN event

Element
Description

action
Optionally specifies the HTTP method on the requested resource or the operation that is performed by the provider of the authentication service.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

authnProvider
The provider of the authentication service.

Sample data: com.tivoli.am.fim.authsvc.protocol.delegate.AuthSvcDelegate com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthnticator

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnProvider']/values

authnScope
Optionally specifies the transaction identifier of the authentication policy.

Sample data: 94434b2a-748e-42fe-af3d-67db04aa4ba0

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnScope']/values

authnType
The URI identifier of the authentication policy.

Sample data: urn:ibm:security:authentication:asf:password_hotp

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnType']/values

partner
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='partner']/values

progName
Optionally specifies the URL of the requested resource.

Sample data: http://www.example.com

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='progName']/values

tokenType
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='tokenType']/values

trustRelationship
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as 'Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='trustRelationship']/values

userInfo.appUserName
Optionally specifies information about the user who is authenticating.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='userInfoList']/children[1]/children
[@name='appUserName']/values

userInfo.attributes
Optionally specifies the following types of additional information about user data that are audited during authentication:

licenseFileMetadata

Metadata that is defined in the license agreement.

licenseFileName

The license file name.

userAction

The action that the user takes when the End-User License Agreement authentication mechanism presents the license agreement. The user can accept the license agreement or decline the license agreement.

The XPath is:

 CommonBaseEvent/extendedDataElements
[@name='userInfoList']/children [@name='userInfo']
/children [@name='attributes']/children

xmlTokenType
The authentication service does not utilize this element and will appear in the IBM_SECURITY_AUTHN event as ‘Not Available’.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='xmlTokenType']/values

Sample of an IBM_SECURITY_AUTHN event

The following example shows one event generated by the runtime for a two-factor authentication policy requiring both username password and one-time password authentications:

<CommonBaseEvent
  creationTime="2014-02-15T18:50:05.026Z"
  extensionName="IBM_SECURITY_AUTHN"
  globalInstanceId="FIM36e24f6301441708947ceef443526"
  sequenceNumber="2"
  version="1.1">
  <contextDataElements
    name="Security Event Factory"
    type="eventTrailId">
        <contextId>FIM_36e24f62014415f59913eef443526e68+1246005647</contextId>
  </contextDataElements>
  <extendedDataElements name="userInfoList" type="noValue">
   <children name="userInfo" type="noValue">
     <children name="registryUserName" type="string">
       <values>Not Available</values>
     </children>
     <children name="appUserName" type="string">
       <values>test_user</values>
     </children>
   </children>
 </extendedDataElements>
 <extendedDataElements name="tokenType" type="string">
   <values>Not Available</values>
 </extendedDataElements>
 <extendedDataElements name="authnProvider" type="string">
   <values>com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator</values>
 </extendedDataElements>
 <extendedDataElements name="action" type="string">
      <values>verify</values>
 </extendedDataElements>
 <extendedDataElements name="authnType" type="string">
      <values>urn:ibm:security:authentication:asf:password_hotp</values>
 </extendedDataElements>
 <extendedDataElements name="outcome" type="noValue">
      <children name="result" type="string">
        <values>SUCCESSFUL</values>
      </children>
      <children name="majorStatus" type="int">
        <values>0</values>
      </children>
 </extendedDataElements>
 <extendedDataElements name="trustRelationship" type="string">
      <values>Not Available</values>
 </extendedDataElements>
 <extendedDataElements name="progName" type="string">
      <values>Not Available</values>
 </extendedDataElements>
 <extendedDataElements name="authnScope" type="string">
      <values>Not Available</values>
 </extendedDataElements>
 <sourceComponentId
      application="IBM Security Access Manager"
      component="Authentication and Federated Identity"
      componentIdType="ProductName"
      executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64"
      location="example"
      locationType="FQHostname"
      subComponent="com.tivoli.am.fim.authsvc.action.authenticator.hotp.HOTPAuthenticator"
      threadId="Default Executor-thread-60"
      componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
  <situation categoryName="ReportSituation">
     <situationType
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:type="ReportSituation"
       reasoningScope="INTERNAL"
       reportCategory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_AUTHN_TERMINATE eventThis audit event is generated when a user is logged off.IBM_SECURITY_AUTHN_ TERMINATE eventdescriptioneventsIBM_SECURITY_AUTHN_ TERMINATEeventssingle logoutsingle logoutelement descriptionThe following table lists the elements that can be shown in the output of an IBM_SECURITY_AUTHN_TERMINATE event. Elements for an IBM_SECURITY_AUTHN_TERMINATE eventElementDescriptionactionThe operation that caused the termination of the authentication to occur - log offThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesauthnProviderThe provider of the authentication service. The default is WebSEAL.The XPath is:CommonBaseEvent/extendedDataElements [@name='authnProvider']/valuesauthnTypeThe type of authentication that is used by the user - trustRelationship.The XPath is:CommonBaseEvent/extendedDataElements [@name='authnType']/valuesterminateReasonThe reason the session was terminated. For example, the user logged off.The XPath is:CommonBaseEvent/extendedDataElements [@name='terminateReason']/valuesuserInfo.appUserNameInformation about the user who is logging off. The XPath is:CommonBaseEvent/extendedDataElements [@name='userInfoList']/children[1]/children [@name='appUserName']/valuesSample of a IBM_SECURITY_AUTHN_TERMINATE eventThe following example shows an IBM_SECURITY_AUTHN_TERMINATE event: <CommonBaseEvent creationTime="2006-04-19T18:13:15.916Z" extensionName="IBM_SECURITY_AUTHN_TERMINATE" globalInstanceId="CE11DACFD02C005F20EE33FA70BA750567" sequenceNumber="10" version="1.0.1"> <extendedDataElements name="authnType" type="string"> <values>trustRelationship</values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>logout</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="majorStatus" type="int"> <values>0</values></children> <children name="result" type="string"> <values>SUCCESSFUL</values></children> </extendedDataElements> <extendedDataElements name="terminateReason" type="string"> <values>UserLoggedOut</values> </extendedDataElements> <extendedDataElements name="authnProvider" type="string"> <values>webseal</values> </extendedDataElements> <extendedDataElements name="userInfoList" type="noValue"> <children name="userInfo" type="noValue"> <children name="appUserName" type="string"> <values>me_elain</values></children> <children name="registryUserName" type="string"> <values>Not Available</values></children> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[x86]#2.4.21-4.EL" location="fimtest.au.ibm.com" locationType="FQHostname" subComponent= "com.tivoli.am.fim.saml20.protocol.actions.SAML20LocalLogoutAction" threadId="WebContainer : 0" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCatagory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_AUTHN_TERMINATE event

This audit event is generated when a user is logged off.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_AUTHN_TERMINATE event.

Table 272. Elements for an IBM_SECURITY_AUTHN_TERMINATE event

Element
Description

action
The operation that caused the termination of the authentication to occur - log off

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

authnProvider
The provider of the authentication service. The default is WebSEAL.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnProvider']/values

authnType
The type of authentication that is used by the user - trustRelationship.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='authnType']/values

terminateReason
The reason the session was terminated. For example, the user logged off.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='terminateReason']/values

userInfo.appUserName
Information about the user who is logging off.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='userInfoList']/children[1]/children
[@name='appUserName']/values

Sample of a IBM_SECURITY_AUTHN_TERMINATE event

The following example shows an IBM_SECURITY_AUTHN_TERMINATE event:

<CommonBaseEvent
 creationTime="2006-04-19T18:13:15.916Z"
 extensionName="IBM_SECURITY_AUTHN_TERMINATE"
 globalInstanceId="CE11DACFD02C005F20EE33FA70BA750567"
 sequenceNumber="10"
 version="1.0.1">
 <extendedDataElements name="authnType" type="string">
  <values>trustRelationship</values>
 </extendedDataElements>
 <extendedDataElements name="action" type="string">
  <values>logout</values>
 </extendedDataElements>
 <extendedDataElements name="outcome" type="noValue">
  <children name="majorStatus" type="int">
   <values>0</values></children>
  <children name="result" type="string">
   <values>SUCCESSFUL</values></children>
 </extendedDataElements>
 <extendedDataElements name="terminateReason" type="string">
  <values>UserLoggedOut</values>
 </extendedDataElements>
 <extendedDataElements name="authnProvider" type="string">
  <values>webseal</values>
 </extendedDataElements>
 <extendedDataElements name="userInfoList" type="noValue">
  <children name="userInfo" type="noValue">
   <children name="appUserName" type="string">
    <values>me_elain</values></children>
   <children name="registryUserName" type="string">
    <values>Not Available</values></children>
  </children>
 </extendedDataElements>
<sourceComponentId
 application="IBM Security Access Manager"
 component="Authentication and Federated Identity"
 componentIdType="ProductName"
 executionEnvironment="Linux[x86]#2.4.21-4.EL"
 location="fimtest.au.ibm.com"
 locationType="FQHostname"
 subComponent=
 "com.tivoli.am.fim.saml20.protocol.actions.SAML20LocalLogoutAction"
 threadId="WebContainer : 0"
 componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
 <situation categoryName="ReportSituation">
   <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:type="ReportSituation"
                  reasoningScope="INTERNAL"
                  reportCatagory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_ENCRYPTION eventsThis event is generated whenever data is encrypted.encryption eventIBM_SECURITY_ENCRYPTION eventdescriptioneventsIBM_SECURITY_ENCRYPTIONeventsencryptionencryptionelementsThe following table lists the elements that can be shown in the output of an IBM_SECURITY_ENCRYPTION event. Elements for an IBM_SECURITY_ENCRYPTION eventElementDescriptionactionThe operation that is being performed, either encryption or decryption.The XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valueskeyInfoThe key used to perform the action.The XPath is:CommonBaseEvent/extendedDataElements [@name='keyInfo']/valuesmsgInfoThe pertinent parts of the SOAP messages.The XPath is:CommonBaseEvent/extendedDataElements [@name='msgInfo']/valuesSample of a IBM_SECURITY_ENCRYPTION eventThe following example shows an IBM_SECURITY_ENCRYPTION event:<CommonBaseEvent creationTime="2006-04-18T18:02:09.824Z" extensionName="IBM_SECURITY_ENCRYPTION" globalInstanceId="CE11DECF0574918190EA65C3F4A1F4E637" sequenceNumber="23" version="1.0.1"> <extendedDataElements name="keyInfo" type="string"> <values>DefaultKeyStore_testkey</values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>Encrypt</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="majorStatus" type="int"> <values>0</values></children> <children name="result" type="string"> <values>SUCCESSFUL</values></children> </extendedDataElements> <extendedDataElements name="msgInfo" type="string"> <values>[{urn:oasis:names:tc:SAML:2.0:protocol}Response[0] {http://www.w3.org/2000/09/xmldsig#}Signature[0]]</values> </extendedDataElements> <extendedDataElements name="userInfo" type="noValue"> <children name="appUserName" type="string"> <values>Not Available</values></children> <children name="registryUserName" type="string"> <values>Not Available</values></children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[x86]#2.4.21-4.EL" location="fimtest.au.ibm.com" locationType="FQHostname" subComponent= "com.tivoli.am.fim.kess.service.jks.worker.impl.KessServiceJksWorkerImpl" threadId="WebContainer : 1" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCatagory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_ENCRYPTION events

This event is generated whenever data is encrypted.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_ENCRYPTION event.

Table 273. Elements for an IBM_SECURITY_ENCRYPTION event

Element
Description

action
The operation that is being performed, either encryption or decryption.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

keyInfo
The key used to perform the action.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='keyInfo']/values

msgInfo
The pertinent parts of the SOAP messages.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='msgInfo']/values

Sample of a IBM_SECURITY_ENCRYPTION event

The following example shows an IBM_SECURITY_ENCRYPTION event:

<CommonBaseEvent
 creationTime="2006-04-18T18:02:09.824Z"
 extensionName="IBM_SECURITY_ENCRYPTION"
 globalInstanceId="CE11DECF0574918190EA65C3F4A1F4E637"
 sequenceNumber="23"
 version="1.0.1">
 <extendedDataElements name="keyInfo" type="string">
  <values>DefaultKeyStore_testkey</values>
 </extendedDataElements>
 <extendedDataElements name="action" type="string">
  <values>Encrypt</values>
 </extendedDataElements>
 <extendedDataElements name="outcome" type="noValue">
  <children name="majorStatus" type="int">
   <values>0</values></children>
  <children name="result" type="string">
   <values>SUCCESSFUL</values></children>
 </extendedDataElements>
 <extendedDataElements name="msgInfo" type="string">
  <values>[{urn:oasis:names:tc:SAML:2.0:protocol}Response[0]
   {http://www.w3.org/2000/09/xmldsig#}Signature[0]]</values>
 </extendedDataElements>
 <extendedDataElements name="userInfo" type="noValue">
  <children name="appUserName" type="string">
   <values>Not Available</values></children>
  <children name="registryUserName" type="string">
   <values>Not Available</values></children>
 </extendedDataElements>
<sourceComponentId
 application="IBM Security Access Manager"
 component="Authentication and Federated Identity"
 componentIdType="ProductName"
 executionEnvironment="Linux[x86]#2.4.21-4.EL"
 location="fimtest.au.ibm.com"
 locationType="FQHostname"
 subComponent=
"com.tivoli.am.fim.kess.service.jks.worker.impl.KessServiceJksWorkerImpl"
 threadId="WebContainer : 1"
 componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
 <situation categoryName="ReportSituation">
   <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:type="ReportSituation"
                  reasoningScope="INTERNAL"
                  reportCatagory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_FEDERATION eventsThis event type is generated when a federation event occurs.federation eventsname identifier managementIBM_SECURITY_FEDERATION eventdescriptioneventsIBM_SECURITY_FEDERATIONname identifier managementelementsAn IBM_SECURITY_FEDERATION event is generated by the following actions:When a user identity mapping is created, that is, when a user is federated.When a user consents to federate.When a user identity mapping is deleted, that is, when a user is de-federated.When a user mapping is updated, for example, an RNI operation.The following table lists the elements that can be shown in the output of an IBM_SECURITY_FEDERATION event. Elements for an IBM_SECURITY_FEDERATION eventElementDescriptionactionThe type of federation action:CreateMappingConsentToFederateDeleteMappingUpdateMappingThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesmessageActionThe type of action that is associated with the message.The XPath is:CommonBaseEvent/extendedDataElements [@name='messageAction']/valuespartnerThe partner that sends or receives the message.The XPath is:CommonBaseEvent/extendedDataElements [@name='partner']/valuesprofileThe profile within the federation.The XPath is:CommonBaseEvent/extendedDataElements [@name='profile']/valuesprotocolNameThe type of federation protocol.The XPath is:CommonBaseEvent/extendedDataElements [@name='protocolName']/valuesroleThe role that the audit generating component takes.The XPath is:CommonBaseEvent/extendedDataElements [@name='role']/valuesuserInfo.appUserNameInformation about the user who is performing this operation.The XPath is:CommonBaseEvent/extendedDataElements [@name='userInfoList']/children[1]/children[ @name='appUserName']/valuesAction-dependent additional attributesDepending on the type of federation event action, the following attributes are available:IBM_SECURITY_FEDERATION action-dependent additional attributesActionAdditional attributesDescriptionCreateMappingselfAliasIf a self alias is set for the user, then this attribute shows that value.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'consentToFederate')] /../../children [@name='value']/valuesThe XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'selfAlias')] /../../children [@name='value']/valuespartnerAliasIf a partner alias is set for the user, then this attribute shows that value.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'partnerAlias')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'partnerAlias')] /../../children [@name='value']/valuesConsentToFederateConsentToFederateThis attribute specifies whether the user consented to federate. This event applies to Liberty and SAML20 protocol flows.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute'/children [@name='name']/values [contains(.,'consentToFederate')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'consentToFederate')] /../../children [@name='value']/valuesDeleteMappingNoneNoneUpdateMappingselfAliasIf a self alias is set for the user, then this attribute shows the updated value.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'consentToFederate')] /../../children [@name='value']/valuesThe XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'selfAlias')] /../../children [@name='value']/valuespartnerAliasIf a partner alias is set for the user, then this attribute shows the updated value.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'partnerAlias')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='attributes']/ children [@name='attribute']/children [@name='name']/values [contains(.,'partnerAlias')] /../../children [@name='value']/valuesSample of a IBM_SECURITY_FEDERATION eventThe following example shows an IBM_SECURITY_FEDERATION event:<CommonBaseEvent creationTime="2006-04-05T20:09:41.983Z" extensionName="IBM_SECURITY_FEDERATION" globalInstanceId="CE11DAC4E01E4BBF50E69681063F1AA1AF" sequenceNumber="7" version="1.0.1"> <extendedDataElements name="action" type="string"> <values>DeleteMapping</values> </extendedDataElements> <extendedDataElements name="partner" type="string"> <values>https://sp:444/FIM/sps/saml20-sp/saml20</values> </extendedDataElements> <extendedDataElements name="relayState" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="majorStatus" type="int"><values>0</values></children> <children name="result" type="string"><values>SUCCESSFUL</values></children> </extendedDataElements> <extendedDataElements name="clientInfo" type="boolean"> <values>false</values> </extendedDataElements> <extendedDataElements name="role" type="string"> <values>IP</values> </extendedDataElements> <extendedDataElements name="messageAction" type="string"> <values>RECEIVED</values> </extendedDataElements> <extendedDataElements name="profile" type="string"> <values>urn:oasis:names:tc:SAML:2.0:profiles:SSO:nameid-mgmt</values> </extendedDataElements> <extendedDataElements name="protocolName" type="string"> <values>urn:oasis:names:tc:SAML:2.0:protocol</values> </extendedDataElements> <extendedDataElements name="userInfoList" type="noValue"> <children name="userInfo" type="noValue"> <children name="appUserName" type="string"><values>Elain</values></children> <children name="registryUserName" type="string"> <values>Not Available</values></children> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[x86]#2.4.21-4.EL" location="fimtest.au.ibm.com" locationType="FQHostname" subComponent= "com.tivoli.am.fim.saml20.protocol.actions.nimgmt. SAML20ProcessManageNameIDMessageAction" threadId="WebContainer : 1" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCatagory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_FEDERATION events

This event type is generated when a federation event occurs.

An IBM_SECURITY_FEDERATION event is generated by the following actions:

When a user identity mapping is created, that is, when a user is federated.

When a user consents to federate.

When a user identity mapping is deleted, that is, when a user is de-federated.

When a user mapping is updated, for example, an RNI operation.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_FEDERATION event.

Table 274. Elements for an IBM_SECURITY_FEDERATION event

Element
Description

action
The type of federation action:

CreateMapping

ConsentToFederate

DeleteMapping

UpdateMapping

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

messageAction
The type of action that is associated with the message.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='messageAction']/values

partner
The partner that sends or receives the message.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='partner']/values

profile
The profile within the federation.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='profile']/values

protocolName
The type of federation protocol.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='protocolName']/values

role
The role that the audit generating component takes.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='role']/values

userInfo.appUserName
Information about the user who is performing this operation.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='userInfoList']/children[1]/children[
@name='appUserName']/values

Action-dependent additional attributes

Depending on the type of federation event action, the following attributes are available:

Table 275. IBM_SECURITY_FEDERATION action-dependent additional attributes

Action
Additional attributes
Description

CreateMapping
selfAlias
If a self alias is set for the user, then this attribute shows that value.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'consentToFederate')]
/../../children
[@name='value']/values

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'selfAlias')]
/../../children
[@name='value']/values

partnerAlias
If a partner alias is set for the user, then this attribute shows that value.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'partnerAlias')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'partnerAlias')]
/../../children
[@name='value']/values

ConsentToFederate
ConsentToFederate
This attribute specifies whether the user consented to federate. This event applies to Liberty and SAML20 protocol flows.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute'/children
[@name='name']/values
[contains(.,'consentToFederate')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'consentToFederate')]
/../../children
[@name='value']/values

DeleteMapping
None
None

UpdateMapping
selfAlias
If a self alias is set for the user, then this attribute shows the updated value.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'consentToFederate')]
/../../children
[@name='value']/values

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'selfAlias')]
/../../children
[@name='value']/values

partnerAlias
If a partner alias is set for the user, then this attribute shows the updated value.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'partnerAlias')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='attributes']/ children
[@name='attribute']/children
[@name='name']/values
[contains(.,'partnerAlias')]
/../../children
[@name='value']/values

Sample of a IBM_SECURITY_FEDERATION event

The following example shows an IBM_SECURITY_FEDERATION event:

<CommonBaseEvent
 creationTime="2006-04-05T20:09:41.983Z"
 extensionName="IBM_SECURITY_FEDERATION"
 globalInstanceId="CE11DAC4E01E4BBF50E69681063F1AA1AF"
 sequenceNumber="7"
 version="1.0.1">
 <extendedDataElements name="action" type="string">
  <values>DeleteMapping</values>
 </extendedDataElements>
 <extendedDataElements name="partner" type="string">
  <values>https://sp:444/FIM/sps/saml20-sp/saml20</values>
 </extendedDataElements>
 <extendedDataElements name="relayState" type="string">
  <values>Not Available</values>
 </extendedDataElements>
 <extendedDataElements name="outcome" type="noValue">
  <children name="majorStatus" type="int"><values>0</values></children>
  <children name="result" type="string"><values>SUCCESSFUL</values></children>
 </extendedDataElements>
 <extendedDataElements name="clientInfo" type="boolean">
  <values>false</values>
 </extendedDataElements>
 <extendedDataElements name="role" type="string">
  <values>IP</values>
 </extendedDataElements>
 <extendedDataElements name="messageAction" type="string">
  <values>RECEIVED</values>
 </extendedDataElements>
 <extendedDataElements name="profile" type="string">
  <values>urn:oasis:names:tc:SAML:2.0:profiles:SSO:nameid-mgmt</values>
 </extendedDataElements>
 <extendedDataElements name="protocolName" type="string">
  <values>urn:oasis:names:tc:SAML:2.0:protocol</values>
 </extendedDataElements>
 <extendedDataElements name="userInfoList" type="noValue">
  <children name="userInfo" type="noValue">
   <children name="appUserName" type="string"><values>Elain</values></children>
   <children name="registryUserName" type="string">
    <values>Not Available</values></children>
  </children>
 </extendedDataElements>
<sourceComponentId
 application="IBM Security Access Manager"
 component="Authentication and Federated Identity"
 componentIdType="ProductName"
 executionEnvironment="Linux[x86]#2.4.21-4.EL"
 location="fimtest.au.ibm.com"
 locationType="FQHostname"
 subComponent=
"com.tivoli.am.fim.saml20.protocol.actions.nimgmt.
 SAML20ProcessManageNameIDMessageAction"
 threadId="WebContainer : 1"
 componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
 <situation categoryName="ReportSituation">
   <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:type="ReportSituation"
                  reasoningScope="INTERNAL"
                  reportCatagory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_MGMT_AUDIT eventsThis event type provides information about changes to the auditing settings; for example, if auditing is enabled or disabled or if auditing is set for specific transactions.audit configuration eventIBM_SECURITY_MGMT_AUDIT eventdescriptioneventsIBM_SECURITY_MGMT_AUDITeventsaudit configurationaudit configuration managementelements forIBM_SECURITY_MGMT_AUDIT events are generated when the audit configuration is modified. Changes to the following data are audited:User nameActionDomainAudit configuration properties:Enable auditingEnable auditing for specific audit event types. Event types are shown in the following table under the mgmtInfo element.Audit log locationMaximum number of audit filesMaximum audit file sizeDisk cache locationWeb service SSL keystoreEnable Web service basic authenticationDisable auditing:User nameActionThe following table lists the elements that can be displayed in the output of an IBM_SECURITY_MGMT_AUDIT event.Elements used in IBM_SECURITY_MGMT_AUDIT eventsElementDescriptionactionThe type of action that occurred against the audit settings. Possible values are Modify and Disable.The XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesmgmtInfoInformation about the auditing operation. The supported items and values are:EnableAudit=true | falseDomain=domain_ nameAuditLogLocation=pathCacheLocation=pathWebServiceBasicAuthUsername=usernameWebServiceBasicAuthPassword=passwordWebServiceKeyIdentifier=keynameWebServiceURL=URLMaxAuditFiles=numberAuditFileSize=numberUseWebServiceBasicAuth=true | falseWebServiceKeystore=keystore_nameAuditSecurityAuthnEvents=true | falseAuditSecurityAuthnTerminateEvents=true | falseAuditSecurityEncryptionEvents=true | falseAuditSecuritySigningEvents=true | falseAuditSecurityFederationEvents=true | falseAuditSecurityTrustEvents=true | falseAuditSecurityMgmtPolicyEvents=true | falseAuditSecurityMgmtAuditEvents=true | falseThe XPath is:CommonBaseEvent/extendedDataElements [@name='mgmtInfo']/children [@name='command']/valuesuserInfoInformation about the user who is performing the operation.The XPath is:CommonBaseEvent/extendedDataElements [@name='userInfo']/children [@name='appUserName']/children [@name='registryUserName']/valuestypeAlways set to the audit value.The XPath is:CommonBaseEvent/extendedDataElements [@name='type']/valuesSample of an IBM_SECURITY_MGMT_AUDIT eventThe following example shows an IBM_SECURITY_MGMT_AUDIT event:<CommonBaseEvent creationTime="2007-04-25T07:01:51.726Z" extensionName="IBM_SECURITY_MGMT_AUDIT" globalInstanceId="CEFA81F627EBCFC5DFA1DBF2FAD8573020" sequenceNumber="1" version="1.0.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_278bcbef011213a9865f8a816f9717a6+1969112872</contextId> </contextDataElements> <extendedDataElements name="mgmtInfo" type="noValue"> <children name="command" type="string"> <values>EnableAudit=true; Domain=mydomain-server1; AuditLogLocation=audit_location; AuditFileSize=10; MaxAuditFiles=100;AuditAuthnEvents=true; AuditAuthnTerminateEvents=true; AuditFederationEvents=true; AuditTrustEvents=true; AuditSigningEvents=true; AuditEncryptionEvents=true; AuditMgmtPolicyEvents=true; AuditMgmtAuditEvents=true; </values> </children> </extendedDataElements> <extendedDataElements name="type" type="string"> <values>audit</values> </extendedDataElements> <extendedDataElements name="userInfo" type="noValue"> <children name="appUserName" type="string"> <values>unauthenticatedUser</values> </children> <children name="registryUserName" type="string"> <values>Not Available</values> </children> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>Modify</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"> <values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"> <values>0</values> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[x86]#2.6.9-34.ELsmp" location="fimfun2.austin.ibm.com" locationType="FQHostname" subComponent="com.tivoli.am.fim.mgmt.fim.FIMManagementImpl" threadId="SoapConnectorThreadPool : 0" componentType= "http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_MGMT_AUDIT events

This event type provides information about changes to the auditing settings; for example, if auditing is enabled or disabled or if auditing is set for specific transactions.

IBM_SECURITY_MGMT_AUDIT events are generated when the audit configuration is modified. Changes to the following data are audited:

User name

Action

Domain

Audit configuration properties:

Enable auditing

Enable auditing for specific audit event types. Event types are shown in the following table under the mgmtInfo element.

Audit log location

Maximum number of audit files

Maximum audit file size

Disk cache location

Web service SSL keystore

Enable Web service basic authentication

Disable auditing:

User name

Action

The following table lists the elements that can be displayed in the output of an IBM_SECURITY_MGMT_AUDIT event.

Table 276. Elements used in IBM_SECURITY_MGMT_AUDIT events

Element
Description

action
The type of action that occurred against the audit settings. Possible values are Modify and Disable.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

mgmtInfo
Information about the auditing operation. The supported items and values are:

EnableAudit=true | false

Domain=domain_ name

AuditLogLocation=path

CacheLocation=path

WebServiceBasicAuthUsername=username

WebServiceBasicAuthPassword=password

WebServiceKeyIdentifier=keyname

WebServiceURL=URL

MaxAuditFiles=number

AuditFileSize=number

UseWebServiceBasicAuth=true | false

WebServiceKeystore=keystore_name

AuditSecurityAuthnEvents=true | false

AuditSecurityAuthnTerminateEvents=true | false

AuditSecurityEncryptionEvents=true | false

AuditSecuritySigningEvents=true | false

AuditSecurityFederationEvents=true | false

AuditSecurityTrustEvents=true | false

AuditSecurityMgmtPolicyEvents=true | false

AuditSecurityMgmtAuditEvents=true | false

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='mgmtInfo']/children
[@name='command']/values

userInfo
Information about the user who is performing the operation.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='userInfo']/children
[@name='appUserName']/children
[@name='registryUserName']/values

type
Always set to the audit value.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='type']/values

Sample of an IBM_SECURITY_MGMT_AUDIT event

The following example shows an IBM_SECURITY_MGMT_AUDIT event:

<CommonBaseEvent
 creationTime="2007-04-25T07:01:51.726Z"
 extensionName="IBM_SECURITY_MGMT_AUDIT"
 globalInstanceId="CEFA81F627EBCFC5DFA1DBF2FAD8573020"
 sequenceNumber="1"
 version="1.0.1">
 <contextDataElements name="Security Event Factory" type="eventTrailId">
  <contextId>FIM_278bcbef011213a9865f8a816f9717a6+1969112872</contextId>
 </contextDataElements>
 <extendedDataElements name="mgmtInfo" type="noValue">
  <children name="command" type="string">
   <values>EnableAudit=true;
    Domain=mydomain-server1;
    AuditLogLocation=audit_location;
    AuditFileSize=10;
    MaxAuditFiles=100;AuditAuthnEvents=true;
    AuditAuthnTerminateEvents=true;
    AuditFederationEvents=true;
    AuditTrustEvents=true;
    AuditSigningEvents=true;
    AuditEncryptionEvents=true;
    AuditMgmtPolicyEvents=true;
    AuditMgmtAuditEvents=true;
   </values>
  </children>
 </extendedDataElements>
 <extendedDataElements name="type" type="string">
  <values>audit</values>
 </extendedDataElements>
 <extendedDataElements name="userInfo" type="noValue">
  <children name="appUserName" type="string">
   <values>unauthenticatedUser</values>
  </children>
  <children name="registryUserName" type="string">
   <values>Not Available</values>
  </children>
 </extendedDataElements>
 <extendedDataElements name="action" type="string">
  <values>Modify</values>
 </extendedDataElements>
 <extendedDataElements name="outcome" type="noValue">
  <children name="result" type="string">
   <values>SUCCESSFUL</values>
  </children>
  <children name="majorStatus" type="int">
   <values>0</values>
  </children>
 </extendedDataElements>
 <sourceComponentId
  application="IBM Security Access Manager"
  component="Authentication and Federated Identity"
  componentIdType="ProductName"
  executionEnvironment="Linux[x86]#2.6.9-34.ELsmp"
  location="fimfun2.austin.ibm.com"
  locationType="FQHostname"
  subComponent="com.tivoli.am.fim.mgmt.fim.FIMManagementImpl"
  threadId="SoapConnectorThreadPool : 0"
  componentType=
  "http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
  <situation categoryName="ReportSituation">
   <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:type="ReportSituation"
                  reasoningScope="INTERNAL"
                  reportCategory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_MGMT_POLICY eventsThis event type is generated by federation runtime management calls.IBM_SECURITY_MGMT_POLICY eventdescriptioneventsIBM_SECURITY_MGMT_POLICYeventsmanagementconfiguration managementelements forAn IBM_SECURITY_MGMT_POLICY event is generated by the following actions:When a new federation is created. When an existing federation is modified.When a federation is deleted.When a partner is added to a federation.When a partner is deleted from a federation.When the properties of a partner are modified.When a Web Service partner is created.When a Web Service partner is modified.The following table lists the elements that can be shown in the output of an IBM_SECURITY_MGMT_POLICY event. Elements for an IBM_SECURITY_MGMT_POLICY eventElementDescriptionactionThe type of operation that is being performed. The supported operations are:createdeletemodifyThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesmgmtInfo.commandInformation about the management operation. The supported management operations are:CreateFederationModifyFederationDeleteFederationCreateFederationPartnerModifyFederationPartner DeleteFederationPartnerCreateWebServicePartnerModifyWebServicePartnerModifying or deleting a Web service partner generates a ModifyWebServicePartner operation.The XPath is:CommonBaseEvent/extendedDataElements [@name='mgmtInfo']/children [@name='command']/valuespolicyInfo.attributesThe different attributes for this policyInfo object. See the tables in Attributes determined by policy profile type for attributes that might be present in the event. Each attribute consists of a name and a value. The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/valuesThe XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='value']/valuespolicyInfo.nameThe name of the federation, the name of the partner, or the name of the Web service partner.The XPath is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='name']/valuespolicyInfo.typeInformation about the policy object. The type can be either federation or partner.The XPath is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='type']/valuesuserInfo.appUserNameInformation about the user who is performing this operation.The XPath is:CommonBaseEvent/extendedDataElements [@name='userInfoList']/children[1]/children [@name='appUserName']/valuesAttributes determined by policy profile typeDepending on the type of profile used, policyInfo contains different attributes. These attributes can be shredded or extracted for custom reports.Different partner attributes are specified as partner id_attribute name, where partner id is the uuid assigned to a partner and attribute name is an attribute from the following tables. Shredding and staging attributesThis example shows how the data can be shredded by using the contains keyword. It requires an XPath for each attribute.To stage the following name-value pairs for FederationName, FederationId and SAML1.SigningKey Identifier from the attributes fields of a policyInfo, use the following XPaths:XPaths for shredding and staging attributesFieldXPathpolicyInfo attributes FederationIdCommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'FederationId')]policyInfo attributes FederationId valueCommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'FederationId')] /../../children [@name='value']/valuespolicyInfo attributes FederationNameCommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'FederationName')]policyInfo attributes FederationName valueCommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'FederationName')] /../../children [@name='value']/valuespolicyInfo attributes SAML1.SigningKeyIdentifierCommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML1.SigningKeyIdentifier')]policyInfo attributes SAML1.SigningKeyIdentifier valueCommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML1.SigningKeyIdentifier')] /../../children [@name='value']/valuesSAML20 self attributesThe following table lists the SAML20 self attributes that are audited in profiles for service providers and identity providers.Policy information attributes for a SAML20 self profile.Common attributes for service providers and identity providersDefinitionsSAML2.SigningKeyIdentifier The identifier for the key used to sign outgoing messages.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SigningKeyIdentifier')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SigningKeyIdentifier')] /../../children [@name='value']/valuesSAML2.DecryptionKeyIdentifier The pointer to the private key used to decrypt the symmetric encryption key in encrypted messages from a partner.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.DecryptionKeyIdentifier')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.DecryptionKeyIdentifier')] /../../children [@name='value']/valuesSAML2.EncryptionKeyTransportAlgorithm The algorithm used to encrypt the symmetric encryption key.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. EncryptionKeyTransportAlgorithm)]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. EncryptionKeyTransportAlgorithm')] /../../children [@name='value']/valuesSAML2.SignArtifactRequest The indicator for whether the provider signs outgoing artifact requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignArtifactRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignArtifactRequest')] /../../children [@name='value']/valuesSAML2.SignArtifactResponse The indicator for whether the provider signs outgoing artifact responses.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignArtifactResponse')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignArtifactResponse')] /../../children [@name='value']/valuesSAML2.SignLogoutRequest The indicator for whether the provider signs outgoing logout requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignLogoutRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignLogoutRequest')] /../../children [@name='value']/valuesSAML2.SignLogoutResponse The indicator for whether the provider signs outgoing logout responses.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignLogoutResponse')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignLogoutResponse')] /../../children [@name='value']/valuesSAML2.SignNameIDManagementRequest The indicator for whether the provider signs outgoing name identifier management requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignNameIDManagementRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignNameIDManagementRequest')] /../../children [@name='value']/valuesSAML2.SignNameIDManagementResponse The indicator for whether the provider signs outgoing name identifier management responses.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignNameIDManagementResponse')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignNameIDManagementResponse')] /../../children [@name='value']/valuesSAML2.PresentFederationConsentThe indicator for whether the identity provider presents a consent to federate page when the federation occurs.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.PresentFederationConsent')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.PresentFederationConsent')] /../../children [@name='value']/valuesAdditional self attributes for service providers onlySAML2.SignAuthnRequest The indicator for whether the provider signs outgoing authentication requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignAuthnRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignAuthnRequest')] /../../children [@name='value']/valuesSAML2.WantAssertionsSignedThe indicator for whether the provider wants to receive signed assertions.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.WantAssertionsSigned')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.WantAssertionsSigned')] /../../children [@name='value']/valuesAdditional self attributes for identity providers onlySAML2.ValidateAuthnRequest The indicator for whether the provider validates incoming authentication requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateAuthnRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateAuthnRequest')] /../../children [@name='value']/valuesSAML2.SignAuthnResponse The indicator for whether the provider signs authentication responses.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignAuthnResponse')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignAuthnResponse')] /../../children [@name='value']/valuesSAML20 partner attributesThe following table lists the SAML20 partner attributes that are audited in profiles for service providers and identity providers.Policy information attributes for a SAML20 partner profile.Common attributes for service providers and identity providersDefinitionsSAML2.SoapRequestClientBasicAuth The indicator for whether client basic authentication is used for the SOAP backchannels.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SoapRequestClientBasicAuth')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SoapRequestClientBasicAuth')] /../../children [@name='value']/valuesSAML2.SoapRequestClientCertAuthThe indicator for whether client certificate authentication is used for the SOAP backchannels.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SoapRequestClientCertAuth')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SoapRequestClientCertAuth')] /../../children [@name='value']/valuesSAML2.SoapRequestServerCertAuthThe indicator for whether server certificate authentication is used for the SOAP backchannels.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SoapRequestServerCertAuth')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SoapRequestServerCertAuth')] /../../children [@name='value']/valuesSAML2. SoapRequestServerCertAuthKeyIdentifierThe identifier for the key used when using server certificate authentication.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. SoapRequestServerCertAuthKeyIdentifier')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. SoapRequestServerCertAuthKeyIdentifier')] /../../children [@name='value']/valuesSAML2. SoapRequestClientCertAuthKeyIdentifierThe identifier for the key used when using client certificate authentication.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. SoapRequestClientCertAuthKeyIdentifier')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. SoapRequestClientCertAuthKeyIdentifier')] /../../children [@name='value']/valuesSAML2.ValidateKeyIdentifierThe identifier for the key used to validate signatures on incoming messages from a partner. This attribute is the signing public key of the partner.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateKeyIdentifier)]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateKeyIdentifier')] /../../children [@name='value']/valuesSAML2.EncryptionKeyIdentifierThe identifier for the key used to encrypt outgoing messages to a partner. This attribute is the encrypting public key of the partner.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.EncryptionKeyIdentifier')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.EncryptionKeyIdentifier')] /../../children [@name='value']/valuesSAML2.ValidateArtifactRequestThe indicator for whether the provider validates incoming artifact requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateArtifactRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateArtifactRequest')] /../../children [@name='value']/valuesSAML2.ValidateArtifactResponseThe indicator for whether the provider validates incoming artifact responses.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateArtifactResponse')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateArtifactResponse')] /../../children [@name='value']/valuesSAML2.ValidateLogoutRequestThe indicator for whether the provider validates incoming logout requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateLogoutRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateLogoutRequest')] /../../children [@name='value']/valuesSAML2.ValidateLogoutResponseThe indicator for whether the provider validates incoming logout responses.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateLogoutResponse')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.ValidateLogoutResponse')] /../../children [@name='value']/valuesSAML2. ValidateNameIDManagementRequestThe indicator for whether the provider validates incoming name identifier management requests.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. ValidateNameIDManagementRequest')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. ValidateNameIDManagementRequest')] /../../children [@name='value']/valuesSAML2. ValidateNameIDManagementResponseThe indicator for whether the provider validates incoming name identifier management responses.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. ValidateNameIDManagementResponse')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2. ValidateNameIDManagementResponse')] /../../children [@name='value']/valuesSAML2.EncryptNameIdentifiersThe indicator for whether name identifiers must be encrypted for the partner.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.EncryptNameIdentifiers')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.EncryptNameIdentifiers)] /../../children [@name='value']/valuesSAML2.BlockEncryptionAlgorithmThe algorithm used to encrypt the data.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.BlockEncryptionAlgorithm')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.BlockEncryptionAlgorithm')] /../../children [@name='value']/valuesAdditional partner attributes for service providers onlySAML2.WantAssertionsSignedThe indicator for whether the provider wants to receive signed assertions.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.WantAssertionsSigned')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.WantAssertionsSigned')] /../../children [@name='value']/valuesAdditional partner attributes for identity providers onlySAML2.SignAssertionsThe indicator for whether the provider signs assertions.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignAssertions')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.SignAssertions')] /../../children [@name='value']/valuesSAML2.EncryptAssertionsThe indicator for whether the provider encrypts assertions.The XPath for the attribute name is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.EncryptAssertions')]The XPath for the attribute value is:CommonBaseEvent/extendedDataElements [@name='policyInfo']/children [@name='attributes']/children [@name='attribute']/children [@name='name']/values [contains (.,'SAML2.EncryptAssertions')] /../../children [@name='value']/valuesSample of a IBM_SECURITY_MGMT_POLICY eventThe following is an example of a IBM_SECURITY_MGMT_POLICY event:<CommonBaseEvent creationTime="2006-04-26T12:22:25.874Z" extensionName="IBM_SECURITY_MGMT_POLICY" globalInstanceId="CE11DAD51F526D53D0E30FDAA2C9637F07" sequenceNumber="1" version="1.0.1"> <extendedDataElements name="action" type="string"> <values>Create</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="majorStatus" type="int"> <values>0</values></children> <children name="result" type="string"> <values>SUCCESSFUL</values></children> </extendedDataElements> <extendedDataElements name="policyInfo" type="noValue"> <children name="attributes" type="noValue"> <children name="attribute" type="noValue"> <children name="value" type="string"> <values>saml11-ip</values></children> <children name="name" type="string"> <values>FederationName</values></children> </children> <children name="attribute" type="noValue"> <children name="value" type="string"> <values>enabled</values></children> <children name="name" type="string"> <values>State</values></children> </children> <children name="attribute" type="noValue"> <children name="value" type="string"> <values>saml11-ip</values></children> <children name="name" type="string"> <values>FederationId</values></children> </children> <children name="attribute" type="noValue"> <children name="value" type="string"> <values>DefaultKeyStore_testkey</values></children> <children name="name" type="string"> <values>SAML1.SigningKeyIdentifier</values></children> </children> <children name="attribute" type="noValue"> <children name="value" type="string"> <values>true</values></children> <children name="name" type="string"> <values>SAML1.SignArtifactResponse</values></children> </children> <children name="attribute" type="noValue"> <children name="value" type="string"> <values>SAML1_1</values></children> <children name="name" type="string"> <values>FederationProtocol</values></children> </children> </children> <children name="type" type="string"> <values>federation</values></children> <children name="name" type="string"> <values>saml11-ip</values></children> </extendedDataElements> <extendedDataElements name="mgmtInfo" type="noValue"> <children name="command" type="string"> <values>CreateFederation</values></children> </extendedDataElements> <extendedDataElements name="userInfo" type="noValue"> <children name="appUserName" type="string"> <values>Not Available</values></children> <children name="registryUserName" type="string"> <values>Not Available</values></children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[x86]#2.4.21-4.EL" location="localhost.localdomain" locationType="FQHostname" subComponent="com.tivoli.am.fim.mgmt.fim.FIMManagementImpl" threadId="SoapConnectorThreadPool : 1" componentType= "http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCatagory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_MGMT_POLICY events

This event type is generated by federation runtime management calls.

An IBM_SECURITY_MGMT_POLICY event is generated by the following actions:

When a new federation is created.

When an existing federation is modified.

When a federation is deleted.

When a partner is added to a federation.

When a partner is deleted from a federation.

When the properties of a partner are modified.

When a Web Service partner is created.

When a Web Service partner is modified.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_MGMT_POLICY event.

Table 277. Elements for an IBM_SECURITY_MGMT_POLICY event

Element
Description

action
The type of operation that is being performed. The supported operations are:

create

delete

modify

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

mgmtInfo.command
Information about the management operation. The supported management operations are:

CreateFederation

ModifyFederation

DeleteFederation

CreateFederationPartner

ModifyFederationPartner

DeleteFederationPartner

CreateWebServicePartner

ModifyWebServicePartner

Note: Modifying or deleting a Web service partner generates a ModifyWebServicePartner operation.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='mgmtInfo']/children
[@name='command']/values

policyInfo.attributes
The different attributes for this policyInfo object. See the tables in Attributes determined by policy profile type for attributes that might be present in the event. Each attribute consists of a name and a value.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='value']/values

policyInfo.name
The name of the federation, the name of the partner, or the name of the Web service partner.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='name']/values

policyInfo.type
Information about the policy object. The type can be either federation or partner.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='type']/values

userInfo.appUserName
Information about the user who is performing this operation.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='userInfoList']/children[1]/children
[@name='appUserName']/values

Attributes determined by policy profile type

Depending on the type of profile used, policyInfo contains different attributes. These attributes can be shredded or extracted for custom reports.

Note: Different partner attributes are specified as partner id_attribute name, where partner id is the uuid assigned to a partner and attribute name is an attribute from the following tables.

Shredding and staging attributes

This example shows how the data can be shredded by using the contains keyword. It requires an XPath for each attribute.

To stage the following name-value pairs for FederationName, FederationId and SAML1.SigningKey Identifier from the attributes fields of a policyInfo, use the following XPaths:

Table 278. XPaths for shredding and staging attributes

Field
XPath

policyInfo attributes FederationId

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'FederationId')]

policyInfo attributes FederationId value

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'FederationId')]
/../../children
[@name='value']/values

policyInfo attributes FederationName

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'FederationName')]

policyInfo attributes FederationName value

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'FederationName')]
/../../children
[@name='value']/values

policyInfo attributes SAML1.SigningKeyIdentifier

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML1.SigningKeyIdentifier')]

policyInfo attributes SAML1.SigningKeyIdentifier value

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML1.SigningKeyIdentifier')]
/../../children
[@name='value']/values

SAML20 self attributes

The following table lists the SAML20 self attributes that are audited in profiles for service providers and identity providers.

Table 279. Policy information attributes for a SAML20 self profile.

Common attributes for service providers and identity providers
Definitions

SAML2.SigningKeyIdentifier
The identifier for the key used to sign outgoing messages.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SigningKeyIdentifier')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SigningKeyIdentifier')]
/../../children
[@name='value']/values

SAML2.DecryptionKeyIdentifier
The pointer to the private key used to decrypt the symmetric encryption key in encrypted messages from a partner.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.DecryptionKeyIdentifier')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.DecryptionKeyIdentifier')]
/../../children
[@name='value']/values

SAML2.EncryptionKeyTransportAlgorithm
The algorithm used to encrypt the symmetric encryption key.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
EncryptionKeyTransportAlgorithm)]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
EncryptionKeyTransportAlgorithm')]
/../../children
[@name='value']/values

SAML2.SignArtifactRequest
The indicator for whether the provider signs outgoing artifact requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignArtifactRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignArtifactRequest')]
/../../children
[@name='value']/values

SAML2.SignArtifactResponse
The indicator for whether the provider signs outgoing artifact responses.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignArtifactResponse')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignArtifactResponse')]
/../../children
[@name='value']/values

SAML2.SignLogoutRequest
The indicator for whether the provider signs outgoing logout requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignLogoutRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignLogoutRequest')]
/../../children
[@name='value']/values

SAML2.SignLogoutResponse
The indicator for whether the provider signs outgoing logout responses.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignLogoutResponse')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignLogoutResponse')]
/../../children
[@name='value']/values

SAML2.SignNameIDManagementRequest
The indicator for whether the provider signs outgoing name identifier management requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignNameIDManagementRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignNameIDManagementRequest')]
/../../children
[@name='value']/values

SAML2.SignNameIDManagementResponse
The indicator for whether the provider signs outgoing name identifier management responses.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignNameIDManagementResponse')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignNameIDManagementResponse')]
/../../children
[@name='value']/values

SAML2.PresentFederationConsent
The indicator for whether the identity provider presents a consent to federate page when the federation occurs.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.PresentFederationConsent')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.PresentFederationConsent')]
/../../children
[@name='value']/values

Additional self attributes for service providers only

SAML2.SignAuthnRequest
The indicator for whether the provider signs outgoing authentication requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignAuthnRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignAuthnRequest')]
/../../children
[@name='value']/values

SAML2.WantAssertionsSigned
The indicator for whether the provider wants to receive signed assertions.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.WantAssertionsSigned')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.WantAssertionsSigned')]
/../../children
[@name='value']/values

Additional self attributes for identity providers only

SAML2.ValidateAuthnRequest
The indicator for whether the provider validates incoming authentication requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateAuthnRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateAuthnRequest')]
/../../children
[@name='value']/values

SAML2.SignAuthnResponse
The indicator for whether the provider signs authentication responses.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignAuthnResponse')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignAuthnResponse')]
/../../children
[@name='value']/values

SAML20 partner attributes

The following table lists the SAML20 partner attributes that are audited in profiles for service providers and identity providers.

Table 280. Policy information attributes for a SAML20 partner profile.

Common attributes for service providers and identity providers
Definitions

SAML2.SoapRequestClientBasicAuth
The indicator for whether client basic authentication is used for the SOAP backchannels.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SoapRequestClientBasicAuth')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SoapRequestClientBasicAuth')]
/../../children
[@name='value']/values

SAML2.SoapRequestClientCertAuth
The indicator for whether client certificate authentication is used for the SOAP backchannels.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SoapRequestClientCertAuth')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SoapRequestClientCertAuth')]
/../../children
[@name='value']/values

SAML2.SoapRequestServerCertAuth
The indicator for whether server certificate authentication is used for the SOAP backchannels.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SoapRequestServerCertAuth')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SoapRequestServerCertAuth')]
/../../children
[@name='value']/values

SAML2. SoapRequestServerCertAuthKeyIdentifier
The identifier for the key used when using server certificate authentication.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
SoapRequestServerCertAuthKeyIdentifier')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
SoapRequestServerCertAuthKeyIdentifier')]
/../../children
[@name='value']/values

SAML2. SoapRequestClientCertAuthKeyIdentifier
The identifier for the key used when using client certificate authentication.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
SoapRequestClientCertAuthKeyIdentifier')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
SoapRequestClientCertAuthKeyIdentifier')]
/../../children
[@name='value']/values

SAML2.ValidateKeyIdentifier
The identifier for the key used to validate signatures on incoming messages from a partner. This attribute is the signing public key of the partner.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateKeyIdentifier)]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateKeyIdentifier')]
/../../children
[@name='value']/values

SAML2.EncryptionKeyIdentifier
The identifier for the key used to encrypt outgoing messages to a partner. This attribute is the encrypting public key of the partner.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.EncryptionKeyIdentifier')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.EncryptionKeyIdentifier')]
/../../children
[@name='value']/values

SAML2.ValidateArtifactRequest
The indicator for whether the provider validates incoming artifact requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateArtifactRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateArtifactRequest')]
/../../children
[@name='value']/values

SAML2.ValidateArtifactResponse
The indicator for whether the provider validates incoming artifact responses.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateArtifactResponse')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateArtifactResponse')]
/../../children
[@name='value']/values

SAML2.ValidateLogoutRequest
The indicator for whether the provider validates incoming logout requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateLogoutRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateLogoutRequest')]
/../../children
[@name='value']/values

SAML2.ValidateLogoutResponse
The indicator for whether the provider validates incoming logout responses.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateLogoutResponse')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.ValidateLogoutResponse')]
/../../children
[@name='value']/values

SAML2. ValidateNameIDManagementRequest
The indicator for whether the provider validates incoming name identifier management requests.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
ValidateNameIDManagementRequest')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
ValidateNameIDManagementRequest')]
/../../children
[@name='value']/values

SAML2. ValidateNameIDManagementResponse
The indicator for whether the provider validates incoming name identifier management responses.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
ValidateNameIDManagementResponse')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.
ValidateNameIDManagementResponse')]
/../../children
[@name='value']/values

SAML2.EncryptNameIdentifiers
The indicator for whether name identifiers must be encrypted for the partner.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.EncryptNameIdentifiers')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.EncryptNameIdentifiers)]
/../../children
[@name='value']/values

SAML2.BlockEncryptionAlgorithm
The algorithm used to encrypt the data.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.BlockEncryptionAlgorithm')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.BlockEncryptionAlgorithm')]
/../../children
[@name='value']/values

Additional partner attributes for service providers only

SAML2.WantAssertionsSigned
The indicator for whether the provider wants to receive signed assertions.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.WantAssertionsSigned')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.WantAssertionsSigned')]
/../../children
[@name='value']/values

Additional partner attributes for identity providers only

SAML2.SignAssertions
The indicator for whether the provider signs assertions.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignAssertions')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.SignAssertions')]
/../../children
[@name='value']/values

SAML2.EncryptAssertions
The indicator for whether the provider encrypts assertions.

The XPath for the attribute name is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.EncryptAssertions')]

The XPath for the attribute value is:

CommonBaseEvent/extendedDataElements
[@name='policyInfo']/children
[@name='attributes']/children
[@name='attribute']/children
[@name='name']/values
[contains
(.,'SAML2.EncryptAssertions')]
/../../children
[@name='value']/values

Sample of a IBM_SECURITY_MGMT_POLICY event

The following is an example of a IBM_SECURITY_MGMT_POLICY event:

<CommonBaseEvent
 creationTime="2006-04-26T12:22:25.874Z"
 extensionName="IBM_SECURITY_MGMT_POLICY"
 globalInstanceId="CE11DAD51F526D53D0E30FDAA2C9637F07"
 sequenceNumber="1"
 version="1.0.1">
 <extendedDataElements name="action" type="string">
  <values>Create</values>
 </extendedDataElements>
 <extendedDataElements name="outcome" type="noValue">
  <children name="majorStatus" type="int">
   <values>0</values></children>
  <children name="result" type="string">
   <values>SUCCESSFUL</values></children>
 </extendedDataElements>
 <extendedDataElements name="policyInfo" type="noValue">
  <children name="attributes" type="noValue">
   <children name="attribute" type="noValue">
   <children name="value" type="string">
    <values>saml11-ip</values></children>
   <children name="name" type="string">
    <values>FederationName</values></children>
  </children>
  <children name="attribute" type="noValue">
   <children name="value" type="string">
    <values>enabled</values></children>
   <children name="name" type="string">
    <values>State</values></children>
  </children>
  <children name="attribute" type="noValue">
   <children name="value" type="string">
    <values>saml11-ip</values></children>
   <children name="name" type="string">
    <values>FederationId</values></children>
  </children>
  <children name="attribute" type="noValue">
   <children name="value" type="string">
    <values>DefaultKeyStore_testkey</values></children>
   <children name="name" type="string">
    <values>SAML1.SigningKeyIdentifier</values></children>
  </children>
  <children name="attribute" type="noValue">
   <children name="value" type="string">
    <values>true</values></children>
   <children name="name" type="string">
    <values>SAML1.SignArtifactResponse</values></children>
  </children>
  <children name="attribute" type="noValue">
   <children name="value" type="string">
    <values>SAML1_1</values></children>
   <children name="name" type="string">
    <values>FederationProtocol</values></children>
  </children>
 </children>
 <children name="type" type="string">
  <values>federation</values></children>
 <children name="name" type="string">
  <values>saml11-ip</values></children>
 </extendedDataElements>
 <extendedDataElements name="mgmtInfo" type="noValue">
  <children name="command" type="string">
   <values>CreateFederation</values></children>
 </extendedDataElements>
 <extendedDataElements name="userInfo" type="noValue">
  <children name="appUserName" type="string">
   <values>Not Available</values></children>
  <children name="registryUserName" type="string">
   <values>Not Available</values></children>
 </extendedDataElements>
 <sourceComponentId
  application="IBM Security Access Manager"
  component="Authentication and Federated Identity"
  componentIdType="ProductName"
  executionEnvironment="Linux[x86]#2.4.21-4.EL"
  location="localhost.localdomain"
  locationType="FQHostname"
  subComponent="com.tivoli.am.fim.mgmt.fim.FIMManagementImpl"
  threadId="SoapConnectorThreadPool : 1"
  componentType=
  "http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
  <situation categoryName="ReportSituation">
   <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:type="ReportSituation"
                  reasoningScope="INTERNAL"
                  reportCatagory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_RUNTIME events (Runtime start)This event type is generated when the runtime is started.security runtime eventsevents IBM_SECURITY_RUNTIMEIBM_SECURITY_RUNTIMEdescriptionThe following table lists the elements that can be shown in the output of an IBM_SECURITY_RUNTIME event.Elements for an IBM_SECURITY_RUNTIME eventElements for an IBM_SECURITY_RUNTIME eventElementDescriptionDomainThe XPath is:CommonBaseEvent/extendedDataElements [@name='Domain']/valuesIsMgmtAuditThe XPath is:CommonBaseEvent/extendedDataElements [@name='IsMgmtAudit']/valuesnameInAppThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='nameInApp']/values nameInPolicyThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='nameInPolicy']/values typeThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='type']/values uniqueIDThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='uniqueID']/values actionThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesSamples of IBM_SECURITY_RUNTIME eventsThe following example shows an events generated by a runtime request. <CommonBaseEvent creationTime="2016-09-20T03:45:55.838Z" extensionName="IBM_SECURITY_RUNTIME" globalInstanceId="FIM45b338ad015712f2ad5cd6c9d3998" sequenceNumber="0" version="1.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_45b337ec01571ef29f4cd6c9d3998025+1092518090</contextId> </contextDataElements> <extendedDataElements name="Domain" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="IsMgmtAudit" type="boolean"> <values>false</values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>auditStart</values> </extendedDataElements> <extendedDataElements name="resourceInfo" type="noValue"> <children name="nameInApp" type="string"><values></values> </children> <children name="nameInPolicy" type="string"><values></values> </children> <children name="type" type="string"><values>application</values> </children> <children name="uniqueId" type="long"><values>0</values> </children> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"><values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"><values>0</values> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[amd64]#2.6.32-279.14.1.91.iss7_3.x86_64" location="isam.myidp.ibm.com" locationType="FQHostname" subComponent="com.tivoli.am.fim.audit.event.impl.RuntimeAuditAdapterImpl" threadId="Default Executor-thread-10" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_RUNTIME events (Runtime start)

This event type is generated when the runtime is started.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_RUNTIME event.

Table 281. Elements for an IBM_SECURITY_RUNTIME event.

Element
Description

Domain

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='Domain']/values

IsMgmtAudit

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='IsMgmtAudit']/values

nameInApp

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='nameInApp']/values

nameInPolicy

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='nameInPolicy']/values

type

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='type']/values

uniqueID

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='uniqueID']/values

action

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

Samples of IBM_SECURITY_RUNTIME events

The following example shows an events generated by a runtime request.

<CommonBaseEvent
  creationTime="2016-09-20T03:45:55.838Z"
  extensionName="IBM_SECURITY_RUNTIME"
  globalInstanceId="FIM45b338ad015712f2ad5cd6c9d3998"
  sequenceNumber="0" version="1.1">
<contextDataElements
  name="Security Event Factory"
  type="eventTrailId">
  <contextId>FIM_45b337ec01571ef29f4cd6c9d3998025+1092518090</contextId>
</contextDataElements>
<extendedDataElements name="Domain" type="string">
  <values>Not Available</values>
</extendedDataElements>
<extendedDataElements name="IsMgmtAudit" type="boolean">
  <values>false</values>
</extendedDataElements>
<extendedDataElements name="action" type="string">
  <values>auditStart</values>
</extendedDataElements>
<extendedDataElements name="resourceInfo" type="noValue">
  <children name="nameInApp" type="string"><values></values>
  </children>
  <children name="nameInPolicy" type="string"><values></values>
  </children>
  <children name="type" type="string"><values>application</values>
  </children>
  <children name="uniqueId" type="long"><values>0</values>
  </children>
</extendedDataElements>
<extendedDataElements name="outcome" type="noValue">
  <children name="result" type="string"><values>SUCCESSFUL</values>
  </children>
  <children name="majorStatus" type="int"><values>0</values>
  </children>
</extendedDataElements>
<sourceComponentId
  application="IBM Security Access Manager"
  component="Authentication and Federated Identity"
  componentIdType="ProductName"
  executionEnvironment="Linux[amd64]#2.6.32-279.14.1.91.iss7_3.x86_64"
  location="isam.myidp.ibm.com"
  locationType="FQHostname"
  subComponent="com.tivoli.am.fim.audit.event.impl.RuntimeAuditAdapterImpl"
  threadId="Default Executor-thread-10"
  componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
<situation categoryName="ReportSituation">
  <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="ReportSituation"
    reasoningScope="INTERNAL"
    reportCategory="SECURITY"/>
  </situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_RUNTIME events (SAML2 message transmission)This event type is generated when transmitting SAML2 authentication request and response messages.security runtime eventsevents IBM_SECURITY_RUNTIMEIBM_SECURITY_RUNTIMEdescriptionThe following table lists the elements that can be shown in the output of an IBM_SECURITY_RUNTIME event.Elements for an IBM_SECURITY_RUNTIME eventElements for an IBM_SECURITY_RUNTIME eventElementDescriptiontypeThe XPath is:CommonBaseEvent/extendedDataElements [@name='resourceInfo']/children [@name='type']/values actionThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesMessageContentThe XPath is:CommonBaseEvent/extendedDataElements [@name='MessageContent']/valuesSamples of IBM_SECURITY_RUNTIME eventsThe following example shows an events generated by a runtime request. <CommonBaseEvent creationTime="2016-09-13T02:54:22.612Z" extensionName="IBM_SECURITY_RUNTIME" globalInstanceId="FIM2177819501571d34a705ed4ca920c" sequenceNumber="10" version="1.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_2177814701571a92875fed4ca920ca5a+1206972288</contextId> </contextDataElements> <extendedDataElements name="MessageContent" type="string"> <values><samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" AssertionConsumerServiceURL="https://sp-wga/isam/sps/saml20sp/saml20/login" Destination="https://ip-wga/isam/sps/saml20ip/saml20/login" ForceAuthn="false" ID="FIMREQ_217780c5-0157-1645-a617-f796a7dfc338" IsPassive="false" IssueInstant="2016-09-13T02:54:22Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0"><saml:Issuer Format=" urn:oasis:names:tc:SAML:2.0:nameid-format:entity"> https://sp-wga/isam/sps/saml20sp/saml20</saml:Issuer> <samlp:NameIDPolicy AllowCreate="false" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"> </samlp:NameIDPolicy></samlp:AuthnRequest></values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>Received</values> </extendedDataElements> <extendedDataElements name="resourceInfo" type="noValue"> <children name="nameInApp" type="string"> <values/> </children> <children name="nameInPolicy" type="string"> <values/> </children> <children name="type" type="string"> <values>Saml20AuthnRequest</values> </children> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"> <values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"> <values>0</values> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[amd64]#2.6.32-279.14.1.91.iss7_3.x86_64" location="ip" locationType="FQHostname" subComponent="com.tivoli.am.fim.saml20.protocol.actions.sso.SAML20ValidateAuthnRequestAction" threadId="Default Executor-thread-61" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_RUNTIME events (SAML2 message transmission)

This event type is generated when transmitting SAML2 authentication request and response messages.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_RUNTIME event.

Table 282. Elements for an IBM_SECURITY_RUNTIME event.

Element
Description

type

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='resourceInfo']/children
[@name='type']/values

action

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

MessageContent
The XPath is:

CommonBaseEvent/extendedDataElements
[@name='MessageContent']/values

Samples of IBM_SECURITY_RUNTIME events

The following example shows an events generated by a runtime request.

<CommonBaseEvent creationTime="2016-09-13T02:54:22.612Z"
extensionName="IBM_SECURITY_RUNTIME" globalInstanceId="FIM2177819501571d34a705ed4ca920c"
sequenceNumber="10" version="1.1">
<contextDataElements name="Security Event Factory" type="eventTrailId">
<contextId>FIM_2177814701571a92875fed4ca920ca5a+1206972288</contextId>
</contextDataElements>
<extendedDataElements name="MessageContent" type="string">
<values><samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
AssertionConsumerServiceURL="https://sp-wga/isam/sps/saml20sp/saml20/login"
Destination="https://ip-wga/isam/sps/saml20ip/saml20/login"
ForceAuthn="false" ID="FIMREQ_217780c5-0157-1645-a617-f796a7dfc338"
IsPassive="false" IssueInstant="2016-09-13T02:54:22Z"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Version="2.0"><saml:Issuer Format="
urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
https://sp-wga/isam/sps/saml20sp/saml20</saml:Issuer>
<samlp:NameIDPolicy AllowCreate="false"
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
</samlp:NameIDPolicy></samlp:AuthnRequest></values>
</extendedDataElements>
<extendedDataElements name="action" type="string">
<values>Received</values>
</extendedDataElements>
<extendedDataElements name="resourceInfo" type="noValue">
<children name="nameInApp" type="string">
<values/>
</children>
<children name="nameInPolicy" type="string">
<values/>
</children>
<children name="type" type="string">
<values>Saml20AuthnRequest</values>
</children>
</extendedDataElements>
<extendedDataElements name="outcome" type="noValue">
<children name="result" type="string">
<values>SUCCESSFUL</values>
</children>
<children name="majorStatus" type="int">
<values>0</values>
</children>
</extendedDataElements>
<sourceComponentId application="IBM Security Access Manager"
component="Authentication and Federated Identity" componentIdType="ProductName"
executionEnvironment="Linux[amd64]#2.6.32-279.14.1.91.iss7_3.x86_64"
location="ip" locationType="FQHostname"
subComponent="com.tivoli.am.fim.saml20.protocol.actions.sso.SAML20ValidateAuthnRequestAction"
threadId="Default Executor-thread-61"
componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
<situation categoryName="ReportSituation">
<situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/>
</situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

IBM_SECURITY_TRUST eventsThis event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.security trust eventsevents IBM_SECURITY_TRUSTIBM_SECURITY_TRUSTdescriptionThe following table lists the elements that can be shown in the output of an IBM_SECURITY_TRUST event.Elements for an IBM_SECURITY_TRUST eventElementDescriptionaccessDecisionFor the authorization module, it is the result of the authorization decision. This element is filled out only when the action is authorized.The XPath is:CommonBaseEvent/extendedDataElements [@name='accessDecision']/valuesactionThe action being performed. Possible actions are:authorizeissuemapvalidateThe XPath is:CommonBaseEvent/extendedDataElements [@name='action']/valuesappliesToThe destination or resource that the request or token applies to.The XPath is:CommonBaseEvent/extendedDataElements [@name='appliesTo']/valuesissuerThe party responsible for issuing the token.The XPath is:CommonBaseEvent/extendedDataElements [@name='issuer']/valuesmoduleNameThe module in the STS module chain that the action is taken on.The XPath is:CommonBaseEvent/extendedDataElements [@name='moduleName']/valuesruleNameThe rule name used for the mapping module. This element is filled out only when specified action is set to map. The XPath is:CommonBaseEvent/extendedDataElements [@name='ruleName']/valuestokenThe incoming token that the action is being taken on. Only the first 1024 characters of the token are set. When the action is set to map, this element represents the incoming principal.The XPath is:CommonBaseEvent/extendedDataElements [@name='token']/valuestokenInfoThe internal representation of the user information after changes are made by the module. Only the first 1024 characters of the token are set. When action is set to map, this element represents the outgoing principal. When the action is set to authorize, this element represents the principal for whom the access decision was made.The XPath is:CommonBaseEvent/extendedDataElements [@name='tokenInfo']/valuestokenTypeThe type of token the module is using.The XPath is:CommonBaseEvent/extendedDataElements [@name='tokenType']/valuesSamples of IBM_SECURITY_TRUST eventsThe following example shows an event generated by a Trust request. <CommonBaseEvent creationTime="2013-07-19T06:21:05.256Z" extensionName="IBM_SECURITY_TRUST" globalInstanceId="FIMf596c16e013f12d38eb0b66d4d925" sequenceNumber="1" version="1.1"> <contextDataElements name="Security Event Factory" type="eventTrailId"> <contextId>FIM_f596bda0013f188f9983b66d4d92542a+971185751</contextId> </contextDataElements> <extendedDataElements name="tokenType" type="string"> <values>Not Available</values> </extendedDataElements> <extendedDataElements name="issuer" type="string"> <values>/otpfed/otp/get/delivery/options/issuer</values> </extendedDataElements> <extendedDataElements name="token" type="string"> <values>user1 [ Attribute 1 name [ value 1 user1 ] ]</values> </extendedDataElements> <extendedDataElements name="ruleName" type="string"> <values>otp_get_methods.js </values> </extendedDataElements> <extendedDataElements name="moduleName" type="string"> <values>com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault</values> </extendedDataElements> <extendedDataElements name="appliesTo" type="string"> <values>/otpfed/otp/get/delivery/options/appliesto</values> </extendedDataElements> <extendedDataElements name="action" type="string"> <values>Map</values> </extendedDataElements> <extendedDataElements name="tokenInfo" type="string"> <values>user1 [ Attribute 1 name [ value 1 user1 ] ]</values> </extendedDataElements> <extendedDataElements name="outcome" type="noValue"> <children name="result" type="string"> <values>SUCCESSFUL</values> </children> <children name="majorStatus" type="int"> <values>0</values> </children> </extendedDataElements> <sourceComponentId application="IBM Security Access Manager" component="Authentication and Federated Identity" componentIdType="ProductName" executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64" location="localhost" locationType="FQHostname" subComponent="com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault" threadId="Default Executor-thread-6" componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/> <situation categoryName="ReportSituation"> <situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/> </situation> </CommonBaseEvent>Auditing FederationThese topics describe auditing for Federation. With the Federation activation level, you can configure and manage audit events for federated access.

IBM_SECURITY_TRUST events

This event type is generated by the trust server when it validates a token, issues a token, maps an identity, or authorizes a Web service call.

The following table lists the elements that can be shown in the output of an IBM_SECURITY_TRUST event.

Table 283. Elements for an IBM_SECURITY_TRUST event

Element
Description

accessDecision
For the authorization module, it is the result of the authorization decision. This element is filled out only when the action is authorized.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='accessDecision']/values

action
The action being performed. Possible actions are:

authorize

issue

map

validate

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='action']/values

appliesTo
The destination or resource that the request or token applies to.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='appliesTo']/values

issuer
The party responsible for issuing the token.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='issuer']/values

moduleName
The module in the STS module chain that the action is taken on.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='moduleName']/values

ruleName
The rule name used for the mapping module. This element is filled out only when specified action is set to map.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='ruleName']/values

token
The incoming token that the action is being taken on. Only the first 1024 characters of the token are set. When the action is set to map, this element represents the incoming principal.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='token']/values

tokenInfo
The internal representation of the user information after changes are made by the module. Only the first 1024 characters of the token are set. When action is set to map, this element represents the outgoing principal. When the action is set to authorize, this element represents the principal for whom the access decision was made.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='tokenInfo']/values

tokenType
The type of token the module is using.

The XPath is:

CommonBaseEvent/extendedDataElements
[@name='tokenType']/values

Samples of IBM_SECURITY_TRUST events

The following example shows an event generated by a Trust request.

<CommonBaseEvent creationTime="2013-07-19T06:21:05.256Z"
extensionName="IBM_SECURITY_TRUST"
globalInstanceId="FIMf596c16e013f12d38eb0b66d4d925"
sequenceNumber="1" version="1.1">
	<contextDataElements name="Security Event Factory"
type="eventTrailId">
		<contextId>FIM_f596bda0013f188f9983b66d4d92542a+971185751</contextId>
	</contextDataElements>
	<extendedDataElements name="tokenType" type="string">
		<values>Not Available</values>
	</extendedDataElements>
	<extendedDataElements name="issuer" type="string">
		<values>/otpfed/otp/get/delivery/options/issuer</values>
	</extendedDataElements>
	<extendedDataElements name="token" type="string">
		<values>user1 [ Attribute 1 name   [ value 1 user1 ] ]</values>
	</extendedDataElements>
	<extendedDataElements name="ruleName" type="string">
		<values>otp_get_methods.js </values>
	</extendedDataElements>
	<extendedDataElements name="moduleName" type="string">
		<values>com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault</values>
	</extendedDataElements>
	<extendedDataElements name="appliesTo" type="string">
		<values>/otpfed/otp/get/delivery/options/appliesto</values>
	</extendedDataElements>
	<extendedDataElements name="action" type="string">
		<values>Map</values>
	</extendedDataElements>
	<extendedDataElements name="tokenInfo" type="string">
		<values>user1 [ Attribute 1 name   [ value 1 user1 ] ]</values>
	</extendedDataElements>
	<extendedDataElements name="outcome" type="noValue">
		<children name="result" type="string">
			<values>SUCCESSFUL</values>
		</children>
		<children name="majorStatus" type="int">
			<values>0</values>
		</children>
	</extendedDataElements>
	<sourceComponentId application="IBM Security Access Manager"
component="Authentication and Federated Identity"
componentIdType="ProductName"
executionEnvironment="Linux[amd64]#2.6.32-279.14.1.30.iss7_3.x86_64"
location="localhost" locationType="FQHostname"
subComponent="com.tivoli.am.fim.trustserver.sts.modules.STSMapDefault"
threadId="Default Executor-thread-6"
componentType="http://www.ibm.com/namespaces/autonomic/Tivoli_componentTypes"/>
	<situation categoryName="ReportSituation">
		<situationType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ReportSituation" reasoningScope="INTERNAL" reportCategory="SECURITY"/>
	</situation>
</CommonBaseEvent>

Parent topic: Auditing Federation

TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Icon: troubleshootingGetting started with troubleshootingProblem determination, or troubleshooting, is a process of determining why a product is not functioning in the expected manner. Diagnosing problems with diagnostic toolsWhen problems do occur, use the information about diagnostic tools to learn how to identify and possibly resolve them. Troubleshooting on the applianceUse appliance options to view system resources and logs. Verifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites. Collecting events to diagnose or audit server operationsYou can collect events for diagnostic and auditing purposes of the servers. Customize logging events with routing filesRouting files are ASCII files that customize the logging of message and trace events for C language-based servers, daemons, and other C-language programs and applications.Java properties filesJava properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.Common Security Access Manager problemsCommon user registry problemsThis chapter details common user registry or directory server problems that you might encounter when you use Security Access Manager.Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGOUse the following information to troubleshoot and resolve single sign-on issues that involve Windows Desktop single sign-on, Kerberos, and SPNEGO.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers. Risk-Based Access External Authorization Service plug-inThe Risk-Based Access (RBA) External Authorization Service (EAS) component provides a runtime XACML EAS plug-in for WebSEAL to enforce a policy decision. WebSEAL becomes the authorization enforcement point to access resources protected by RBA. Troubleshooting certificate compliance issuesWhen you enable Security Access Manager applications to implement a security compliance standard, certain settings are required. Serviceability commandsTroubleshooting Advanced Access ControlUse the known problems, solutions, and limitations to troubleshoot the Advanced Access Control module.Support InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.

Troubleshooting

The Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.

Getting started with troubleshooting
Problem determination, or troubleshooting, is a process of determining why a product is not functioning in the expected manner.

Diagnosing problems with diagnostic tools
When problems do occur, use the information about diagnostic tools to learn how to identify and possibly resolve them.

Troubleshooting on the appliance
Use appliance options to view system resources and logs.

Verifying the deployment
The installation of Security Access Manager involves the installation and configuration of a number of prerequisites.

Collecting events to diagnose or audit server operations
You can collect events for diagnostic and auditing purposes of the servers.

Customize logging events with routing files
Routing files are ASCII files that customize the logging of message and trace events for C language-based servers, daemons, and other C-language programs and applications.

Java properties files
Java™ properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.

Message event logging
The contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers.

Trace event logs
Security Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Common Security Access Manager problems

Common user registry problems
This chapter details common user registry or directory server problems that you might encounter when you use Security Access Manager.

Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGO
Use the following information to troubleshoot and resolve single sign-on issues that involve Windows Desktop single sign-on, Kerberos, and SPNEGO.

Common problems with WebSEAL servers
The following information details the common problems with WebSEAL servers.

Risk-Based Access External Authorization Service plug-in
The Risk-Based Access (RBA) External Authorization Service (EAS) component provides a runtime XACML EAS plug-in for WebSEAL to enforce a policy decision. WebSEAL becomes the authorization enforcement point to access resources protected by RBA.

Troubleshooting certificate compliance issues
When you enable Security Access Manager applications to implement a security compliance standard, certain settings are required.

Serviceability commands

Troubleshooting Advanced Access Control
Use the known problems, solutions, and limitations to troubleshoot the Advanced Access Control module.

Support Information
To isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.

Getting started with troubleshootingGetting started with troubleshootingGetting started with troubleshootingProblem determination, or troubleshooting, is a process of determining why a product is not functioning in the expected manner. problem determinationoverviewtroubleshootoverviewThese topics provide information to help you identify and resolve problems. The troubleshooting process, in general, requires that you isolate and identify a problem, then seek a resolution. You can use a troubleshooting checklist to help you. If the checklist does not lead you to a resolution, you can collect additional diagnostic data and analyze it yourself. You can also submit the data to IBM Software Support for analysis.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Avoiding potential problemsIf you plan the deployment of your software, you can often prevent problems before they happen.

Getting started with troubleshooting

Problem determination, or troubleshooting, is a process of determining why a product is not functioning in the expected manner.

These topics provide information to help you identify and resolve problems.

The troubleshooting process, in general, requires that you isolate and identify a problem, then seek a resolution. You can use a troubleshooting checklist to help you. If the checklist does not lead you to a resolution, you can collect additional diagnostic data and analyze it yourself. You can also submit the data to IBM® Software Support for analysis.

Avoiding potential problems
If you plan the deployment of your software, you can often prevent problems before they happen.

Parent topic: Troubleshooting

Avoiding potential problemsAvoiding common problemsAvoiding common problemsIf you plan the deployment of your software, you can often prevent problems before they happen.common problemsavoidBefore you install or upgrade Security Access Manager, review the product requirements. You can access these from a link on the Welcome page in the Knowledge Center. The link connects you with the following information: Supported operating system levelsPrerequisite software requirementsRequired software patchesMinimum memory requirementsDisk space requirementsAfter you install Security Access Manager, ensure that you have a comprehensive backup and system recovery strategy in place. When you create your backup and recovery strategy, include the following information to help avoid the possibility of running into problems: Periodically back up the user registry by following the instructions that are provided by the user registry vendor.Maintain information about your environment, including system topology, IP addresses, host names, and which components are installed on each system.Maintain updated information that describes the key system resources that are being managed by Security Access Manager and the security policies that are being applied to them by Security Access Manager.Periodically check that all systems that are running Security Access Manager have sufficient disk space for runtime and problem determination data. As your security policy grows, and the number of users, groups, and protected objects increase, the space requirements for the policy databases, message logs, trace logs, and any auditing information can increase as well.Regularly check for the availability of fix packs and install them as they become available. Information about fix packs and other useful information can be found on the IBM Software Support Site.Getting started with troubleshootingProblem determination, or troubleshooting, is a process of determining why a product is not functioning in the expected manner.

Avoiding potential problems

If you plan the deployment of your software, you can often prevent problems before they happen.

Before you install or upgrade Security Access Manager, review the product requirements. You can access these from a link on the Welcome page in the Knowledge Center. The link connects you with the following information:

Supported operating system levels

Prerequisite software requirements

Required software patches

Minimum memory requirements

Disk space requirements

After you install Security Access Manager, ensure that you have a comprehensive backup and system recovery strategy in place. When you create your backup and recovery strategy, include the following information to help avoid the possibility of running into problems:

Periodically back up the user registry by following the instructions that are provided by the user registry vendor.

Maintain information about your environment, including system topology, IP addresses, host names, and which components are installed on each system.

Maintain updated information that describes the key system resources that are being managed by Security Access Manager and the security policies that are being applied to them by Security Access Manager.

Periodically check that all systems that are running Security Access Manager have sufficient disk space for runtime and problem determination data. As your security policy grows, and the number of users, groups, and protected objects increase, the space requirements for the policy databases, message logs, trace logs, and any auditing information can increase as well.

Regularly check for the availability of fix packs and install them as they become available. Information about fix packs and other useful information can be found on the IBM Software Support Site.

Parent topic: Getting started with troubleshooting

Diagnosing problems with diagnostic toolsDiagnosing problems with diagnostic toolsDiagnosing problems with diagnostic toolsWhen problems do occur, use the information about diagnostic tools to learn how to identify and possibly resolve them. problem determinationdiagnose with toolsdiagnostic toolsIf you are unable to correct the problem, gather the relevant diagnostic information and then contact IBM Support to get further assistance.MessagesAll messages issued by IBM Security Access Manager adhere to a Message Standard. LogsUse log files to retrieve information about a problem in your environment.Using the error messages to resolve errorsUse the unique message ID associated with a message to locate detailed explanations and suggested operator responses.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.MessagesAll messages issued by IBM Security Access Manager adhere to a Message Standard. LogsUse log files to retrieve information about a problem in your environment.Using the error messages to resolve errorsUse the unique message ID associated with a message to locate detailed explanations and suggested operator responses.

Diagnosing problems with diagnostic tools

When problems do occur, use the information about diagnostic tools to learn how to identify and possibly resolve them.

If you are unable to correct the problem, gather the relevant diagnostic information and then contact IBM® Support to get further assistance.

Messages

Logs

Using the error messages to resolve errors

Messages
All messages issued by IBM Security Access Manager adhere to a Message Standard.

Logs
Use log files to retrieve information about a problem in your environment.

Using the error messages to resolve errors
Use the unique message ID associated with a message to locate detailed explanations and suggested operator responses.

Parent topic: Troubleshooting

MessagesMessagesMessagesAll messages issued by IBM Security Access Manager adhere to a Message Standard. messagesoverviewmessagesserviceability improvementsmessagesmessage standardserviceability improvementsmessagesIBM Message StandardThe Message Standard specifies a standard format for all messages issued by this product. The standard, based on the IBM Message Standard, is intended to provide a consistent and meaningful way for identifying messages across the entire IBM product set. Messages issued by IBM Security Access Manager, along with detailed explanations and suggested actions, can be found in the Error messages section of the IBM Knowledge Center.Diagnosing problems with diagnostic toolsWhen problems do occur, use the information about diagnostic tools to learn how to identify and possibly resolve them. Message typesSecurity Access Manager is written in both the C and Java programming languages, with different types of messages for each programming language.Message formatA message consists of a message identifier (ID) and message text and an error code. The error code is a unique 32-bit value. The error code is either a decimal or hexadecimal number and indicates that an operation was not successful.Message identifiersA message ID consists of 10 alphanumeric characters that uniquely identify the message.

Messages

All messages issued by IBM Security Access Manager adhere to a Message Standard.

The Message Standard specifies a standard format for all messages issued by this product. The standard, based on the IBM Message Standard, is intended to provide a consistent and meaningful way for identifying messages across the entire IBM product set. Messages issued by IBM Security Access Manager, along with detailed explanations and suggested actions, can be found in the Error messages section of the IBM Knowledge Center.

Message types
Security Access Manager is written in both the C and Java™ programming languages, with different types of messages for each programming language.

Message format
A message consists of a message identifier (ID) and message text and an error code. The error code is a unique 32-bit value. The error code is either a decimal or hexadecimal number and indicates that an operation was not successful.

Message identifiers
A message ID consists of 10 alphanumeric characters that uniquely identify the message.

Parent topic: Diagnosing problems with diagnostic tools

Message typesMessage typesMessage typesSecurity Access Manager is written in both the C and Java programming languages, with different types of messages for each programming language.messagestypesmessagesruntimeruntimemessage overviewmessagesruntimeJava, forruntime for Javamessage overviewmessagesserverpolicy servermessage overviewauthorization servermessage typesWebSEAL servermessage overviewmessagesinstallationmessagesconfigurationinstallationmessage overviewconfigurationmessage overviewmessagesWebSEAL HTTPWebSEALHTTP, message overviewApplications that use the Security Access Manager APIs are also written in these programming languages.Security Access Manager produces the following types of messages: Runtime messagesMessages that are generated by applications, commands, and utilities that use the Security Access Manager Runtime component, and messages that are generated from the C language-based Security Access Manager components, such as WebSEAL. These messages are written to the runtime message logs based on their severity levels.IBM Security Access Manager Runtime for Java messagesMessages that are generated by applications, commands, and utilities that use the IBM Security Access Manager Runtime for Java component, and messages that are generated from the Java language-based Security Access Manager components. These messages are written to the IBM Security Access Manager Runtime for Java message logs. These messages tend to provide exception and stack trace information from the JRE.Server messagesMessages that are generated by the Security Access Manager daemons and servers. Messages from the policy server, authorization server, and WebSEAL servers are written to the server message logs. Installation and configuration messagesMessages that are generated during installation and by the configuration utilities. Some of these messages follow the message standard and have an associated ID. WebSEAL HTTP messagesWebSEAL provides the capability of logging HTTP messages. This message log capability is described in the Auditing topics in the Knowledge Center.MessagesAll messages issued by IBM Security Access Manager adhere to a Message Standard.

Message types

Security Access Manager is written in both the C and Java™ programming languages, with different types of messages for each programming language.

Applications that use the Security Access Manager APIs are also written in these programming languages.

Security Access Manager produces the following types of messages:

Runtime messages

Messages that are generated by applications, commands, and utilities that use the Security Access Manager Runtime component, and messages that are generated from the C language-based Security Access Manager components, such as WebSEAL. These messages are written to the runtime message logs based on their severity levels.

IBM Security Access Manager Runtime for Java messages

Messages that are generated by applications, commands, and utilities that use the IBM Security Access Manager Runtime for Java component, and messages that are generated from the Java language-based Security Access Manager components. These messages are written to the IBM Security Access Manager Runtime for Java message logs. These messages tend to provide exception and stack trace information from the JRE.

Server messages

Messages that are generated by the Security Access Manager daemons and servers. Messages from the policy server, authorization server, and WebSEAL servers are written to the server message logs.

Installation and configuration messages

Messages that are generated during installation and by the configuration utilities. Some of these messages follow the message standard and have an associated ID.

WebSEAL HTTP messages

WebSEAL provides the capability of logging HTTP messages. This message log capability is described in the Auditing topics in the Knowledge Center.

Parent topic: Messages

Message formatMessage formatMessage formatA message consists of a message identifier (ID) and message text and an error code. The error code is a unique 32-bit value. The error code is either a decimal or hexadecimal number and indicates that an operation was not successful.messagesstandard formatformatmessagesAll messages that follow the message standard are listed in the Error messages section of the IBM Knowledge Center. Each of these messages has a detailed explanation and suggested actions.MessagesAll messages issued by IBM Security Access Manager adhere to a Message Standard.

Message format

A message consists of a message identifier (ID) and message text and an error code. The error code is a unique 32-bit value. The error code is either a decimal or hexadecimal number and indicates that an operation was not successful.

All messages that follow the message standard are listed in the Error messages section of the IBM Knowledge Center. Each of these messages has a detailed explanation and suggested actions.

Parent topic: Messages

Message identifiersMessage identifiersMessage IDA message ID consists of 10 alphanumeric characters that uniquely identify the message. messagesID formatformatmessage IDID format, messagesThe message ID consists of the following parts: A 3-character product identifier A 2-character component or subsystem identifierA 4-digit serial or message numberA 1-character type code that indicated one of the following message severities: WWarningEErrorIInformationMessagesAll messages issued by IBM Security Access Manager adhere to a Message Standard.

Message identifiers

A message ID consists of 10 alphanumeric characters that uniquely identify the message.

The message ID consists of the following parts:

A 3-character product identifier

A 2-character component or subsystem identifier

A 4-digit serial or message number

A 1-character type code that indicated one of the following message severities:

W

Warning

E

Error

I

Information

Parent topic: Messages

LogsLogsLogsUse log files to retrieve information about a problem in your environment.Enable the collection of detailed log and trace information to troubleshoot problems. You can collect and review standard informational log messages or detailed trace messages to help determine the root cause of a problem. For information about viewing event logs, see Viewing the event logSystem events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.. For information about viewing the appliance log files, see Viewing application log filesUse the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.Diagnosing problems with diagnostic toolsWhen problems do occur, use the information about diagnostic tools to learn how to identify and possibly resolve them.

Logs

Use log files to retrieve information about a problem in your environment.

Enable the collection of detailed log and trace information to troubleshoot problems. You can collect and review standard informational log messages or detailed trace messages to help determine the root cause of a problem.

For information about viewing event logs, see Viewing the event log.

For information about viewing the appliance log files, see Viewing application log files

Parent topic: Diagnosing problems with diagnostic tools

Using the error messages to resolve errorsUsing the Messages Guide to resolve errorsUsing the Messages Guide to resolve errorsUse the unique message ID associated with a message to locate detailed explanations and suggested operator responses.The Error message section of the IBM Knowledge Center contains a list of messages in the IBM Security Access Manager logs, graphical user interfaces, and the command line. For example, if you see the following error message in the message log: CTGSI0311E The distributed session cache server was unable to generate a new key. Search for CTGSI0311E in the Error messages section for information about why the error occurred and how to resolve it. For example, the previous error message has the following information in the IBM Knowledge Center:Explanation: The distributed session cache server was unable to generate a new key. Administrator response: Examine the distributed session cache server logs for further details. It may be necessary to restart the distributed session cache server completely to correct this condition.Diagnosing problems with diagnostic toolsWhen problems do occur, use the information about diagnostic tools to learn how to identify and possibly resolve them.

Using the error messages to resolve errors

Use the unique message ID associated with a message to locate detailed explanations and suggested operator responses.

The Error message section of the IBM Knowledge Center contains a list of messages in the IBM® Security Access Manager logs, graphical user interfaces, and the command line.

For example, if you see the following error message in the message log:

CTGSI0311E The distributed session cache server was
unable to generate a new key.

Search for CTGSI0311E in the Error messages section for information about why the error occurred and how to resolve it. For example, the previous error message has the following information in the IBM Knowledge Center:

Explanation: The distributed session cache server was
unable to generate a new key.
Administrator response: Examine the distributed
session cache server logs for further details. It may be
necessary to restart the distributed session cache server
completely to correct this condition.

Parent topic: Diagnosing problems with diagnostic tools

Troubleshooting on the applianceTroubleshooting on the applianceUse appliance options to view system resources and logs. troubleshooting applianceYou can use the Monitoring: Analysis and Diagnostics appliance menus to view the use of resources such as memory, CPU, and storage. Also, review the known problems and limitations with deployment on the appliance.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Running self-diagnostic tests (hardware appliance only)The hardware appliance provides a self-diagnostic program to assist with troubleshooting. This feature is not available with the virtual appliance.Viewing the event logSystem events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.Viewing memory statisticsView the memory graph to see the memory utilization of the IBM Security Access Manager appliance.Viewing CPU utilizationView the CPU graph to see the CPU utilization of IBM Security Access Manager.Viewing storage utilizationView the storage graph to see the percentage of disk space that is used by the boot and root partitions of the IBM Security Access Manager appliance.Viewing application interface statisticsTo view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.Viewing application log filesUse the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. Monitoring log files in the command-line interfaceUse the monitor menu in the command-line interface so that you can easily monitor the status of the log files.Known issues and solutionsUse the solutions to troubleshoot issues that you might encounter.Known limitationsConsider these known limitations when you are configuring the IBM Security Access Manager environment.

Troubleshooting on the appliance

Use appliance options to view system resources and logs.

You can use the Monitoring: Analysis and Diagnostics appliance menus to view the use of resources such as memory, CPU, and storage. Also, review the known problems and limitations with deployment on the appliance.

Running self-diagnostic tests (hardware appliance only)
The hardware appliance provides a self-diagnostic program to assist with troubleshooting. This feature is not available with the virtual appliance.

Viewing the event log
System events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.

Viewing memory statistics
View the memory graph to see the memory utilization of the IBM Security Access Manager appliance.

Viewing CPU utilization
View the CPU graph to see the CPU utilization of IBM Security Access Manager.

Viewing storage utilization
View the storage graph to see the percentage of disk space that is used by the boot and root partitions of the IBM Security Access Manager appliance.

Viewing application interface statistics
To view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.

Viewing application log files
Use the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.

Tuning runtime application parameters and tracing specifications
To manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page.

Monitoring log files in the command-line interface
Use the monitor menu in the command-line interface so that you can easily monitor the status of the log files.

Known issues and solutions
Use the solutions to troubleshoot issues that you might encounter.

Known limitations
Consider these known limitations when you are configuring the IBM Security Access Manager environment.

Parent topic: Troubleshooting

Running self-diagnostic tests (hardware appliance only)Running self-diagnostic tests (hardware appliance only)Access Manager Appliance: Running self-diagnostic tests (hardware appliance only)The hardware appliance provides a self-diagnostic program to assist with troubleshooting. This feature is not available with the virtual appliance.self_diagnostictroubleshootingself_diagnosticReboot the appliance.From the console, select the Hardware Diagnostics option from the GNU GRUB menu.The diagnostics program starts running after this option is selected. After the appliance finishes booting, the diagnostics program is accessible from the console.To run a diagnostic test, enter phdiag <test_name>, where <test_name> is one of the following values in bold:allRun all standard tests (No storage bad blocks test, default)lcdRun LCD testssystemRun standard system tests (MTM-Serial, Inventory, PSU, FAN, SEL)networkRun network port tests (Selftest, Traffic)storageRun storage tests (SMART, FSCK)badblocksRun storage bad blocks testTroubleshooting on the applianceUse appliance options to view system resources and logs.

Running self-diagnostic tests (hardware appliance only)

The hardware appliance provides a self-diagnostic program to assist with troubleshooting. This feature is not available with the virtual appliance.

Procedure

Reboot the appliance.

From the console, select the Hardware Diagnostics option from the GNU GRUB menu. The diagnostics program starts running after this option is selected. After the appliance finishes booting, the diagnostics program is accessible from the console.

To run a diagnostic test, enter phdiag <test_name>, where <test_name> is one of the following values in bold:

all

Run all standard tests (No storage bad blocks test, default)

lcd

Run LCD tests

system

Run standard system tests (MTM-Serial, Inventory, PSU, FAN, SEL)

network

Run network port tests (Selftest, Traffic)

storage

Run storage tests (SMART, FSCK)

badblocks

Run storage bad blocks test

Parent topic: Troubleshooting on the appliance

Viewing the event logViewing the event logAccess Manager Appliance: Viewing the event logSystem events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.event logviewClick Monitor Analysis and DiagnosticsLogsEvent Log.The system events displayed.Click Pause Live Streaming to stop the live updating of the event log.Click Start Live Streaming to resume live updating of the event log.Troubleshooting on the applianceUse appliance options to view system resources and logs.

Viewing the event log

System events are logged when the system settings are changed and when problems occur with the system. Use the Event Log management page to view system events.

Procedure

Click Monitor Analysis and Diagnostics > Logs > Event Log. The system events displayed.

Click Pause Live Streaming to stop the live updating of the event log.

Click Start Live Streaming to resume live updating of the event log.

Parent topic: Troubleshooting on the appliance

Viewing memory statisticsViewing memory statisticsViewing memory statisticsView the memory graph to see the memory utilization of the IBM Security Access Manager appliance.memory graphmemory statisticsviewClick Monitor Analysis and DiagnosticsSystem GraphsMemory.Select a Date Range:1 DayDisplays data points for every minute during the last 24 hours.3 DaysDisplays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.7 DaysDisplays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.30 DaysDisplays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.In the Legend box, select Memory Used to review total memory utilization.Troubleshooting on the applianceUse appliance options to view system resources and logs.

Viewing memory statistics

View the memory graph to see the memory utilization of the IBM Security Access Manager appliance.

Procedure

Click Monitor Analysis and Diagnostics > System Graphs > Memory.

Select a Date Range:

Option | Description
1 Day | Displays data points for every minute during the last 24 hours.
3 Days | Displays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.
7 Days | Displays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.
30 Days | Displays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.

In the Legend box, select Memory Used to review total memory utilization.

Parent topic: Troubleshooting on the appliance

Viewing CPU utilizationViewing CPU utilizationAccess Manager Appliance: Viewing CPU utilizationView the CPU graph to see the CPU utilization of IBM Security Access Manager.CPU graphClick Monitor Analysis and DiagnosticsSystem GraphsCPU.Select a Date Range:1 DayDisplays data points for every minute during the last 24 hours.3 DaysDisplays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.7 DaysDisplays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.30 DaysDisplays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.In the Legend box, select the CPU utilization data that you want to review:UserSystemIdleTroubleshooting on the applianceUse appliance options to view system resources and logs.

Viewing CPU utilization

View the CPU graph to see the CPU utilization of IBM Security Access Manager.

Procedure

Click Monitor Analysis and Diagnostics > System Graphs > CPU.

Select a Date Range:

Option | Description
1 Day | Displays data points for every minute during the last 24 hours.
3 Days | Displays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.
7 Days | Displays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.
30 Days | Displays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.

In the Legend box, select the CPU utilization data that you want to review:

User

System

Idle

Parent topic: Troubleshooting on the appliance

Viewing storage utilizationViewing storage utilizationAccess Manager Appliance: Viewing storage utilizationView the storage graph to see the percentage of disk space that is used by the boot and root partitions of the IBM Security Access Manager appliance.storage graphdisk spacestorageutilizationrootpartitionClick Monitor Analysis and DiagnosticsSystem GraphsStorage.Select a Date Range:1 DayDisplays data points for every minute during the last 24 hours.3 DaysDisplays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.7 DaysDisplays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.30 DaysDisplays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.In the Legend box, select which partitions you want to review:BootThe boot partition.RootThe base file system, where the system user is root.Troubleshooting on the applianceUse appliance options to view system resources and logs.

Viewing storage utilization

View the storage graph to see the percentage of disk space that is used by the boot and root partitions of the IBM Security Access Manager appliance.

Procedure

Click Monitor Analysis and Diagnostics > System Graphs > Storage.

Select a Date Range:

Option | Description
1 Day | Displays data points for every minute during the last 24 hours.
3 Days | Displays data points for every 5 minutes during the last three days. Each data point is an average of the activity that occurred in that hour.
7 Days | Displays data points every 20 minutes during the last seven days. Each data point is an average of the activity that occurred in that hour.
30 Days | Displays data points for every hour during the last 30 days. Each data point is an average of the activity that occurred in that hour.

In the Legend box, select which partitions you want to review:

Boot

The boot partition.

Root

The base file system, where the system user is root.

Parent topic: Troubleshooting on the appliance

Viewing application interface statisticsViewing application interface statisticsAccess Manager Appliance: Viewing application interface statisticsTo view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.application interface statisticsviewFrom the top menu, select Monitor Analysis and DiagnosticsNetwork GraphsApplication Interface Statistics.In the Date Range field, select the period to display the statistics for.1 DayDisplays data for every 20-minute interval in one day.3 DaysDisplays data for every 20-minute interval during the last three days. 7 DaysDisplays data for every 20-minute interval during the last seven days. 30 DaysDisplays data for every day during the last 30 days. Troubleshooting on the applianceUse appliance options to view system resources and logs.

Viewing application interface statistics

To view the bandwidth and frames that are being used on your application interfaces, use the Application Interface Statistics management page.

Procedure

From the top menu, select Monitor Analysis and Diagnostics > Network Graphs > Application Interface Statistics.

In the Date Range field, select the period to display the statistics for.

Option | Description
1 Day | Displays data for every 20-minute interval in one day.
3 Days | Displays data for every 20-minute interval during the last three days.
7 Days | Displays data for every 20-minute interval during the last seven days.
30 Days | Displays data for every day during the last 30 days.

Parent topic: Troubleshooting on the appliance

Viewing application log filesViewing application log filesViewing application log filesUse the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.application logmanageFrom the top menu, select Monitor Analysis and DiagnosticsApplication Log Files.The displayed directories contain the application log files that can be viewed and downloaded:access_control: Log files for the Advanced Access Control Module.cluster: Logs files for the cluster manager.dsc: Log files for distributed session cache.federation: Log files for the Federation Module.felb: Log files for the front-end load balancer.isam_runtime: Log files for the runtime.management_ui: Log files for the management interface.snmp: Log files for the SNMP manager.Click Refresh to get the most up-to-date data.You can then view or download the displayed log files.To view the log fileSelect the file of interest.Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Alternatively, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.Optional: Click Export to download the log file. To download the log fileSelect the file of interest.Click Download to save the file to your local drive.Confirm the save operation in the browser window that pops up.Troubleshooting on the applianceUse appliance options to view system resources and logs.

Viewing application log files

Use the Application Log Files management page to view and download log files that are produced by IBM Security Access Manager.

Procedure

From the top menu, select Monitor Analysis and Diagnostics > Application Log Files. The displayed directories contain the application log files that can be viewed and downloaded:

access_control: Log files for the Advanced Access Control Module.

cluster: Logs files for the cluster manager.

dsc: Log files for distributed session cache.

federation: Log files for the Federation Module.

felb: Log files for the front-end load balancer.

isam_runtime: Log files for the runtime.

management_ui: Log files for the management interface.

snmp: Log files for the SNMP manager.

Optional: Click Refresh to get the most up-to-date data.

You can then view or download the displayed log files.

To view the log file

Select the file of interest.

Click View. The content of the log file is displayed. By default, the last 100 lines of a log file are displayed if the file is longer than 100 lines. You can define the number of lines to display by entering the number in the Number of lines to view field and then click Reload. Alternatively, you can provide a value in the Starting from line field to define the start of the lines. If the Starting from line field is set, then the Number of lines to view field determines how many lines to view forward from the starting line. If the Starting from line field is not set, then the Number of lines to view field determines how many lines to view from the end of the log file.

Note: The maximum size that can be returned is 214800000 lines. If a size greater than that is specified, then the maximum (214800000 lines) is returned.

Optional: Click Export to download the log file.

To download the log file

Select the file of interest.

Click Download to save the file to your local drive.

Confirm the save operation in the browser window that pops up.

Parent topic: Troubleshooting on the appliance

Tuning runtime application parameters and tracing specificationsTuning runtime application parameters and tracing specificationsAccess Manager Appliance: Tuning runtime application parameters and tracing specificationsTo manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page. From the top menu, select Secure Access ControlGlobal SettingsRuntime Parameters or Secure FederationGlobal SettingsRuntime Parameters.This page contains three panels: Runtime Status, Runtime Tuning Parameters, and Runtime Tracing. Perform one or more of the following actions to tune your runtime.Certain changes might require a restart of the runtime before they can take effect. Disable automatic restart of the runtimeBy default, the runtime is automatically restarted after certain changes are made. You can disable this automatic restart function if you prefer manual restarts.On the Runtime Tuning Parameters panel, select Auto Restart.Click Edit.In the Auto Restart window, define the value as False.Click OK.View the status of and restart the runtimeSelect the Runtime Status panel. The status of local and clustered runtimes are displayed.Under Local Runtime Status, you can view the runtime operational status, when it was last started, and whether a restart is outstanding. If the value of the Restart Required field is True, it means that the runtime must be restarted for some changes to take effect.Under Clustered Runtime Status, all nodes in the cluster are listed.The Master column indicates whether a node is the cluster master.The Runtime Status column indicates whether a node is running or stopped.The Changes Active column indicates whether changes made to the cluster configuration are active on this node. Having a green indicator in this column means that all changes made are already active. Having a yellow indicator in this column means that this node must be restarted before some changes can take effect.Depending on which runtime you want to restart, click Restart Local Runtime or Restart All Clustered Runtimes.Modify the maximum or initial heap sizeThese parameters indicate the maximum and initial heap size in megabytes for the runtime Java virtual machine.On the Runtime Tuning Parameters panel, select Max Heap Size or Initial Heap Size.Click Edit.In the Max Heap Size or Initial Heap Size window, enter the heap size value as needed.Click OK.Modify whether to suppress sensitive traceEnabling this parameter prevents sensitive information from being exposed in log and trace files. Examples of such sensitive information include bytes received over a network connection.On the Runtime Tuning Parameters panel, select Suppress Sensitive Trace.Click Edit.In the Suppress Sensitive Trace window, select or clear the check box as needed.Click OK.Modify console log levelConsole log level controls the granularity of messages that go to the console.log file.On the Runtime Tuning Parameters panel, select Console Log Level. Click Edit.In the Console Log Level window, select the new value from the list.Click OK.Set whether to accept client certificatesThis parameter controls whether the server accepts client certificates as a form of authentication.On the Runtime Tuning Parameters panel, select Accept Client Certificates. Click Edit.In the Accept Client Certificates window, select or clear the check box as needed.Click OK.Set session invalidation timeoutThis parameter defines the amount of time a session can remain unused before it is no longer valid.The default setting is Unset. When this setting is used, the session invalidation timeout is 1800 seconds.On the Runtime Tuning Parameters panel, select Session Invalidation Timeout. Click Edit.In the Session Invalidation Timeout window, define the value in seconds.Click OK.Set session reaper poll intervalThis parameter defines the wake-up interval in seconds for the process that removes invalid sessions. The minimum value is 30 seconds.The default setting is Unset. When this setting is used, or if a value less than the minimum is entered, an appropriate value is automatically determined and used. This value overrides the default installation value, which is 30 - 360 seconds, based on the session invalidation timeout value. Because the default session invalidation timeout is 1800 seconds, the reaper interval is usually between 120 and 180 seconds.On the Runtime Tuning Parameters panel, select Session Reaper Poll Interval. Click Edit.In the Session Reaper Poll Interval window, define the value in seconds.Click OK.Set the keystore that is used by the runtime serverThis parameter defines the key database that contains the runtime server's private key.On the Runtime Tuning Parameters panel, select Keystore. Click Edit.In the Keystore window, select the key database from the list.Click OK.Set the truststore that is used by the runtime serverThis parameter defines the key database that contains keys that are trusted by the runtime serverOn the Runtime Tuning Parameters panel, select Truststore. Click Edit.In the Truststore window, select the key database from the list.Click OK.Delete the value of a parameterUse this button to delete the existing value of a parameter.Select the parameter to reset the value for.Click Delete. The value of the parameter is then changed to Unset.Manage the application interface on which the runtime listensOn the Runtime Tuning Parameters panel, under Runtime Listening Interfaces, you can add, edit, or delete a listening interface.To add a listening interfaceClick Add.In the Runtime Listening Interfaces window, select the listening interface from the list.Specify the listening port.Select the SSL check box if security is required.Click OK.To modify a listening interfaceSelect the listening interface to edit.Click Edit.In the Runtime Listening Interfaces window, edit the values as needed.Click OK to save the changes.To delete a listening interfaceSelect the listening interface to delete.Select Delete.Confirm the deletion.Manage tracing specificationSelect the Runtime Tracing link from the top of this page. You can also access this panel from the top menu by selecting Monitor Analysis and DiagnosticsLogsRuntime Tracing.Use one of the following ways to edit the trace level of a component.Select the component name from the Component list. Select the ideal trace level for this component from the Trace Level list. Then, click Add. Repeat this process to modify trace levels for other components if needed. To clear all of the tracing levels, click Clear.To log all events, select ALL as the trace level.This setting increases the amount of data in logs, so use this level when necessary.com.tivoli.am.fim.authsvc.* com.tivoli.am.fim.trustserver.sts.modules.*Valid trace levelsThe following table contains the valid trace levels. LevelSignificanceALLAll events are logged. If you create custom levels, ALL includes those levels and can provide a more detailed trace than FINEST.FINESTDetailed trace information that includes all of the details that are necessary to debug problems.FINERDetailed trace information.FINEGeneral trace information that includes methods entry, exit, and return values.DETAILGeneral information that details sub task progress.CONFIGConfiguration change or status.INFOGeneral information that outlines the overall task progress.AUDITSignificant event that affects the server state or resources.WARNINGPotential error or impending error. This level can also indicate a progressive failure. For example: the potential leaking of resourcesSEVEREThe task cannot continue, but component, application, and server can still function. This level can also indicate an impending unrecoverable error.FATALThe task cannot continue, and component, application, and server cannot function.OFFLogging is turned off.Enter the name and value of the trace component in the Trace Specification field. To modify multiple components, separate two strings with a colon (:). Here is an example.com.x.y.*=WARNING:com.a.b.*=WARNING:com.ibm.isam.*=INFOClick Save.When you make changes, the appliance displays a message that there are undeployed changes. If you have finished making changes, deploy them.Troubleshooting on the applianceUse appliance options to view system resources and logs.

Tuning runtime application parameters and tracing specifications

To manually tune selected runtime application parameters and tracing specifications, use the Runtime Parameters management page.

Procedure

From the top menu, select Secure Access Control > Global Settings > Runtime Parameters or Secure Federation > Global Settings > Runtime Parameters. This page contains three panels: Runtime Status, Runtime Tuning Parameters, and Runtime Tracing.

Perform one or more of the following actions to tune your runtime.

Note: Certain changes might require a restart of the runtime before they can take effect.

Disable automatic restart of the runtime

By default, the runtime is automatically restarted after certain changes are made. You can disable this automatic restart function if you prefer manual restarts.

On the Runtime Tuning Parameters panel, select Auto Restart.

Click Edit.

In the Auto Restart window, define the value as False.

Click OK.

View the status of and restart the runtime

Select the Runtime Status panel. The status of local and clustered runtimes are displayed.

Under Local Runtime Status, you can view the runtime operational status, when it was last started, and whether a restart is outstanding. If the value of the Restart Required field is True, it means that the runtime must be restarted for some changes to take effect.

Under Clustered Runtime Status, all nodes in the cluster are listed.

The Master column indicates whether a node is the cluster master.

The Runtime Status column indicates whether a node is running or stopped.

The Changes Active column indicates whether changes made to the cluster configuration are active on this node. Having a green indicator in this column means that all changes made are already active. Having a yellow indicator in this column means that this node must be restarted before some changes can take effect.

Depending on which runtime you want to restart, click Restart Local Runtime or Restart All Clustered Runtimes.

Modify the maximum or initial heap size

These parameters indicate the maximum and initial heap size in megabytes for the runtime Java virtual machine.

On the Runtime Tuning Parameters panel, select Max Heap Size or Initial Heap Size.

Click Edit.

In the Max Heap Size or Initial Heap Size window, enter the heap size value as needed.

Click OK.

Modify whether to suppress sensitive trace

Enabling this parameter prevents sensitive information from being exposed in log and trace files. Examples of such sensitive information include bytes received over a network connection.

On the Runtime Tuning Parameters panel, select Suppress Sensitive Trace.

Click Edit.

In the Suppress Sensitive Trace window, select or clear the check box as needed.

Click OK.

Modify console log level

Console log level controls the granularity of messages that go to the console.log file.

On the Runtime Tuning Parameters panel, select Console Log Level.

Click Edit.

In the Console Log Level window, select the new value from the list.

Click OK.

Set whether to accept client certificates

This parameter controls whether the server accepts client certificates as a form of authentication.

On the Runtime Tuning Parameters panel, select Accept Client Certificates.

Click Edit.

In the Accept Client Certificates window, select or clear the check box as needed.

Click OK.

Set session invalidation timeout

This parameter defines the amount of time a session can remain unused before it is no longer valid.

Note: The default setting is Unset. When this setting is used, the session invalidation timeout is 1800 seconds.

On the Runtime Tuning Parameters panel, select Session Invalidation Timeout.

Click Edit.

In the Session Invalidation Timeout window, define the value in seconds.

Click OK.

Set session reaper poll interval

This parameter defines the wake-up interval in seconds for the process that removes invalid sessions. The minimum value is 30 seconds.

The default setting is Unset. When this setting is used, or if a value less than the minimum is entered, an appropriate value is automatically determined and used. This value overrides the default installation value, which is 30 - 360 seconds, based on the session invalidation timeout value. Because the default session invalidation timeout is 1800 seconds, the reaper interval is usually between 120 and 180 seconds.

On the Runtime Tuning Parameters panel, select Session Reaper Poll Interval.

Click Edit.

In the Session Reaper Poll Interval window, define the value in seconds.

Click OK.

Set the keystore that is used by the runtime server

This parameter defines the key database that contains the runtime server's private key.

On the Runtime Tuning Parameters panel, select Keystore.

Click Edit.

In the Keystore window, select the key database from the list.

Click OK.

Set the truststore that is used by the runtime server

This parameter defines the key database that contains keys that are trusted by the runtime server

On the Runtime Tuning Parameters panel, select Truststore.

Click Edit.

In the Truststore window, select the key database from the list.

Click OK.

Delete the value of a parameter

Use this button to delete the existing value of a parameter.

Select the parameter to reset the value for.

Click Delete. The value of the parameter is then changed to Unset.

Manage the application interface on which the runtime listens

On the Runtime Tuning Parameters panel, under Runtime Listening Interfaces, you can add, edit, or delete a listening interface.

To add a listening interface

Click Add.

In the Runtime Listening Interfaces window, select the listening interface from the list.

Specify the listening port.

Select the SSL check box if security is required.

Click OK.

To modify a listening interface

Select the listening interface to edit.

Click Edit.

In the Runtime Listening Interfaces window, edit the values as needed.

Click OK to save the changes.

To delete a listening interface

Select the listening interface to delete.

Select Delete.

Confirm the deletion.

Manage tracing specification

Select the Runtime Tracing link from the top of this page. You can also access this panel from the top menu by selecting Monitor Analysis and Diagnostics > Logs > Runtime Tracing.

Use one of the following ways to edit the trace level of a component.

Select the component name from the Component list. Select the ideal trace level for this component from the Trace Level list. Then, click Add. Repeat this process to modify trace levels for other components if needed. To clear all of the tracing levels, click Clear.

To log all events, select ALL as the trace level.

Note: This setting increases the amount of data in logs, so use this level when necessary.

com.tivoli.am.fim.authsvc.*
com.tivoli.am.fim.trustserver.sts.modules.*

Table 284. Valid trace levels. The following table contains the valid trace levels.

Level | Significance
ALL | All events are logged. If you create custom levels, ALL includes those levels and can provide a more detailed trace than FINEST.
FINEST | Detailed trace information that includes all of the details that are necessary to debug problems.
FINER | Detailed trace information.
FINE | General trace information that includes methods entry, exit, and return values.
DETAIL | General information that details sub task progress.
CONFIG | Configuration change or status.
INFO | General information that outlines the overall task progress.
AUDIT | Significant event that affects the server state or resources.
WARNING | Potential error or impending error. This level can also indicate a progressive failure. For example: the potential leaking of resources
SEVERE | The task cannot continue, but component, application, and server can still function. This level can also indicate an impending unrecoverable error.
FATAL | The task cannot continue, and component, application, and server cannot function.
OFF | Logging is turned off.

Enter the name and value of the trace component in the Trace Specification field. To modify multiple components, separate two strings with a colon (:). Here is an example.

com.x.y.*=WARNING:com.a.b.*=WARNING:com.ibm.isam.*=INFO

Click Save.

When you make changes, the appliance displays a message that there are undeployed changes. If you have finished making changes, deploy them.

Parent topic: Troubleshooting on the appliance

Monitoring log files in the command-line interfaceMonitoring log files in the command-line interfaceMonitoring log files in the command-line interfaceUse the monitor menu in the command-line interface so that you can easily monitor the status of the log files.logsmonitoringcommand-line interfaceAccess the command-line interface of the appliance by using either an ssh session or the console.Enter isam.Enter logs.Enter monitor.Select the log file that you want to monitor.Troubleshooting on the applianceUse appliance options to view system resources and logs.

Monitoring log files in the command-line interface

Use the monitor menu in the command-line interface so that you can easily monitor the status of the log files.

Procedure

Access the command-line interface of the appliance by using either an ssh session or the console.

Enter isam.

Enter logs.

Enter monitor.

Select the log file that you want to monitor.

Parent topic: Troubleshooting on the appliance

Known issues and solutionsKnown issues and solutionsKnown issues and solutionsUse the solutions to troubleshoot issues that you might encounter.Internet ExplorerCompatibility View known issueHelp System known issueMicrosoft Internet ExplorerCompatibility View known issueHelp System known issueCompatibility Viewknown issuesHelp System solutiondatabase deletionsknown issuecluster updateknown issuebrowserknown issues Help Systemknown issuewga.cmd.timeout tuning parameterKerberos configurationreset to defaultscluster configurationKerberos values reset issueThe known issues are:Enabling Compatibility View in Internet Explorer 9 returns the Browser not Supported messageHelp page content does not displayOn Windows operating systems, you cannot use basic authentication for WebSEAL from IBM Security Access Manager for WebDatabase rolls back with an error when you attempt to remove a large quantity of records from a DB2 runtime databaseA cluster configuration update fails to deploy and generates a timeout error messageDatabase Maintenance panel returns a retrieval errorCannot export and import a template page file in the same sessionKerberos Configuration is reset to the default values on the applianceEnabling Compatibility View in Internet Explorer 9 returns the Browser not Supported messageThe IBM Security Access Manager appliance does not support the browser operating in this mode. The following message is displayed in the local management interface: Browser not Supported. The IBM Security Access Manager appliance does not support this browser. The following browsers are currently supported: - Internet Explorer 9 or later - Firefox 17.0 or later - Google Chrome 27.0 or laterSolution:The appliance does not support Internet Explorer if the Compatibility View is turned on. Ensure that the Compatibility View in Internet Explorer is turned off. The Compatibility View option is under the Tools menu in the Internet Explorer browser.Help page content does not display When you click the Help link from the appliance user interface while using Microsoft Internet Explorer version 9.0 or later, the topic content might not display. Solution: Ensure that the Compatibility View in Internet Explorer is turned on. The Compatibility View option is under the Tools menu in the Internet Explorer browser. The Help System supports compatibility mode.On Windows operating systems, you cannot use basic authentication for WebSEAL from IBM Security Access Manager for Web WebSEAL does not start properly if your configuration meets all of these conditions: Windows operating systemWebSEAL from IBM Security Access Manager for Web 7.0.0.1 Basic authentication configured in the WebSEAL configuration file with basic-auth-user and basic-auth-passwd entries in the [rtss-cluster:cluster1] stanza Solution: To work around this issue, configure certificate authentication for WebSEAL. See the WebSEAL administration information in the Knowledge Center. If you are using the isamcfg tool to configure WebSEAL, be sure to select certificate authentication for the authentication method response.Database rolls back with an error when you attempt to remove a large quantity of records from a DB2 runtime database When you try to delete many device fingerprints or user session data records from an external DB2 runtime database, the following error might occur:Error occurred. The database was rolled back to the previous version. The transaction log for the database is full. SQLCODE=-964, SQLSTATE=57011 Solution: Increase the log capacity by completing the following actions: Increase the number of primary and secondary transaction log files.Increase the size of each transaction log. For information about the available transaction log configuration parameters, see the DB2 documentation.A cluster configuration update fails to deploy and generates a timeout error message An update to the cluster configuration, such as the External Reference Entity IP address or First Port value, might fail to deploy in the allotted time. The following error message is printed in the event log: WGASY0007E The pending changes failed to deploy within the allotted time. Solution: Increase the wga.cmd.timeout value. In the local management interface, select Manage System Settings > System Settings > Advanced Tuning Parameters. Add a parameter that is called wga.cmd.timeout and set the timeout value in seconds. The default value is 300 seconds.Database Maintenance panel returns a retrieval error The following error message returns in the Database Maintenance panel after the location of the runtime database is changed:System Error FBTRBA091E The retrieval failed because the resource cannot be found.This error message returns after the location of the runtime database is changed from Local to the cluster to Remote to the cluster under the Database tab in the Cluster Configuration panel. Solution: Complete the following steps to restart the local management interface: Use an ssh session to access the local management interface. Log in as the administrator.Type lmi, and press Enter.Type restart, and press Enter.Type exit, and press Enter.Cannot export and import a template page file in the same session If you export a template page file and immediately try to import a file, no action occurs, and the file is not imported. Solution: After you export a file, refresh the browser before you try to import a file.Kerberos Configuration is reset to the default values on the appliance After saving and deploying the Kerberos Configuration settings, you might find that the values of these Kerberos settings are reset to the defaults. For example default_realm is set back to tbd. In a clustered Security Access Manager environment, when you configure the Kerberos settings on a node appliance, the values you modified are set back to the default values. Or, the settings are overwritten by the values set on the primary master of the cluster. This happens after some time. Specifically, propagation of the values happens once one of the following conditions is met: The Replicate with Cluster option is toggled on from the local management interface runtime component panel. And, the settings are changed on the master.Sufficient time has elapsed since the last propagation (approximately 15 minutes). The resetting of these values is evident on the Defaults, Realms, Domains, and CA Paths tabs, but not on the Keyfiles tab. In general, when you choose to replicate the runtime environment with the cluster, these values are synchronized from the primary master. Therefore, if you change these values on a node other than the primary master, they are overwritten with the values from the primary master during the next synchronization operation. Solution: When your configuration is set to replicate the runtime environment with the cluster, always update the Kerberos Configuration settings on the primary master of the cluster, instead of on a node. You must also import the keytab file on each node that is using the Kerberos Configuration settings.Troubleshooting on the applianceUse appliance options to view system resources and logs.

Known issues and solutions

Use the solutions to troubleshoot issues that you might encounter.

The known issues are:

Enabling Compatibility View in Internet Explorer 9 returns the Browser not Supported message

Help page content does not display

On Windows operating systems, you cannot use basic authentication for WebSEAL from IBM Security Access Manager for Web

Database rolls back with an error when you attempt to remove a large quantity of records from a DB2 runtime database

A cluster configuration update fails to deploy and generates a timeout error message

Database Maintenance panel returns a retrieval error

Cannot export and import a template page file in the same session

Kerberos Configuration is reset to the default values on the appliance

Enabling Compatibility View in Internet Explorer 9 returns the Browser not Supported message

The IBM® Security Access Manager appliance does not support the browser operating in this mode. The following message is displayed in the local management interface:

Browser not Supported. The IBM Security Access Manager appliance does
not support this browser.

The following browsers are currently supported:

- Internet Explorer 9 or later
- Firefox 17.0 or later
- Google Chrome 27.0 or later

Solution:

The appliance does not support Internet Explorer if the Compatibility View is turned on. Ensure that the Compatibility View in Internet Explorer is turned off. The Compatibility View option is under the Tools menu in the Internet Explorer browser.

Help page content does not display

When you click the Help link from the appliance user interface while using Microsoft Internet Explorer version 9.0 or later, the topic content might not display.

Solution:

Ensure that the Compatibility View in Internet Explorer is turned on. The Compatibility View option is under the Tools menu in the Internet Explorer browser. The Help System supports compatibility mode.

On Windows operating systems, you cannot use basic authentication for WebSEAL from IBM Security Access Manager for Web

WebSEAL does not start properly if your configuration meets all of these conditions:

Windows operating system

WebSEAL from IBM Security Access Manager for Web 7.0.0.1

Basic authentication configured in the WebSEAL configuration file with basic-auth-user and basic-auth-passwd entries in the [rtss-cluster:cluster1] stanza

Solution:

To work around this issue, configure certificate authentication for WebSEAL. See the WebSEAL administration information in the Knowledge Center.

If you are using the isamcfg tool to configure WebSEAL, be sure to select certificate authentication for the authentication method response.

Database rolls back with an error when you attempt to remove a large quantity of records from a DB2 runtime database

When you try to delete many device fingerprints or user session data records from an external DB2® runtime database, the following error might occur:

Error occurred. The database was rolled back to the previous version.
The transaction log for the database is full. SQLCODE=-964, SQLSTATE=57011

Solution:

Increase the log capacity by completing the following actions:

Increase the number of primary and secondary transaction log files.

Increase the size of each transaction log.

For information about the available transaction log configuration parameters, see the DB2 documentation.

A cluster configuration update fails to deploy and generates a timeout error message

An update to the cluster configuration, such as the External Reference Entity IP address or First Port value, might fail to deploy in the allotted time. The following error message is printed in the event log:

WGASY0007E The pending changes failed to deploy within the allotted time.

Solution:

Increase the wga.cmd.timeout value. In the local management interface, select Manage System Settings > System Settings > Advanced Tuning Parameters. Add a parameter that is called wga.cmd.timeout and set the timeout value in seconds. The default value is 300 seconds.

Database Maintenance panel returns a retrieval error

The following error message returns in the Database Maintenance panel after the location of the runtime database is changed:

System Error FBTRBA091E The retrieval failed because the resource cannot be found.

This error message returns after the location of the runtime database is changed from Local to the cluster to Remote to the cluster under the Database tab in the Cluster Configuration panel.

Solution: Complete the following steps to restart the local management interface:

Use an ssh session to access the local management interface.

Log in as the administrator.

Type lmi, and press Enter.

Type restart, and press Enter.

Type exit, and press Enter.

Cannot export and import a template page file in the same session

If you export a template page file and immediately try to import a file, no action occurs, and the file is not imported.

Solution: After you export a file, refresh the browser before you try to import a file.

Kerberos Configuration is reset to the default values on the appliance

After saving and deploying the Kerberos Configuration settings, you might find that the values of these Kerberos settings are reset to the defaults. For example default_realm is set back to tbd.

In a clustered Security Access Manager environment, when you configure the Kerberos settings on a node appliance, the values you modified are set back to the default values. Or, the settings are overwritten by the values set on the primary master of the cluster. This happens after some time.

Specifically, propagation of the values happens once one of the following conditions is met:

The Replicate with Cluster option is toggled on from the local management interface runtime component panel. And, the settings are changed on the master.

Sufficient time has elapsed since the last propagation (approximately 15 minutes).

The resetting of these values is evident on the Defaults, Realms, Domains, and CA Paths tabs, but not on the Keyfiles tab.

In general, when you choose to replicate the runtime environment with the cluster, these values are synchronized from the primary master. Therefore, if you change these values on a node other than the primary master, they are overwritten with the values from the primary master during the next synchronization operation.

Solution: When your configuration is set to replicate the runtime environment with the cluster, always update the Kerberos Configuration settings on the primary master of the cluster, instead of on a node. You must also import the keytab file on each node that is using the Kerberos Configuration settings.

Parent topic: Troubleshooting on the appliance

Known limitationsKnown limitationsKnown limitationsConsider these known limitations when you are configuring the IBM Security Access Manager environment.session timeoutsLocal management interface (LMI) session timeoutsLMI sessions expire after the duration of time that is specified by the Session Timeout field on the Administrator Settings page. When a session timeout occurs, you are automatically logged out and any unsaved data on the current page is lost.Save your configuration updates in the LMI regularly to avoid data loss in the event of a session timeout. Troubleshooting on the applianceUse appliance options to view system resources and logs.

Known limitations

Consider these known limitations when you are configuring the IBM Security Access Manager environment.

Local management interface (LMI) session timeouts

LMI sessions expire after the duration of time that is specified by the Session Timeout field on the Administrator Settings page. When a session timeout occurs, you are automatically logged out and any unsaved data on the current page is lost.

Save your configuration updates in the LMI regularly to avoid data loss in the event of a session timeout.

Parent topic: Troubleshooting on the appliance

Verifying the deploymentVerifying the deploymentVerifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites. deploymentverifyThese prerequisites can include Security Access Manager components. Operational failures can result from the failure to install or correctly configure a prerequisite.If you have a failure in the following instances, always examine your installed software: A new Security Access Manager installation fails to work properlyAn existing Security Access Manager installation fails to work properly after you update a prerequisite or Security Access Manager componentsFor more information, see the product requirements link on the Welcome page in the Knowledge Center.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.System types in a deploymentA typical deployment of Security Access Manager involves the installation and configuration of a number of systems. Checking installed softwareSecurity Access Manager provides commands and utilities to help you determine whether the correct software, and software level, is installed on any operating system.Verifying Global Security KitEnsure that the Global Security Kit is installed and working properly for your environment.Verifying user registriesThis section provides information about verifying the different Security Access Manager user registries.Verifying base systemsAt a high level, you can determine which Security Access Manager servers are configured and which are running.Verifying Web security systemsYou can verify whether Web security systems are operating properly by connecting from your browser to a URL.

Verifying the deployment

The installation of Security Access Manager involves the installation and configuration of a number of prerequisites.

These prerequisites can include Security Access Manager components. Operational failures can result from the failure to install or correctly configure a prerequisite.

If you have a failure in the following instances, always examine your installed software:

A new Security Access Manager installation fails to work properly

An existing Security Access Manager installation fails to work properly after you update a prerequisite or Security Access Manager components

For more information, see the product requirements link on the Welcome page in the Knowledge Center.

System types in a deployment
A typical deployment of Security Access Manager involves the installation and configuration of a number of systems.

Checking installed software
Security Access Manager provides commands and utilities to help you determine whether the correct software, and software level, is installed on any operating system.

Verifying Global Security Kit
Ensure that the Global Security Kit is installed and working properly for your environment.

Verifying user registries
This section provides information about verifying the different Security Access Manager user registries.

Verifying base systems
At a high level, you can determine which Security Access Manager servers are configured and which are running.

Verifying Web security systems
You can verify whether Web security systems are operating properly by connecting from your browser to a URL.

Parent topic: Troubleshooting

System types in a deploymentSystem types in a deploymentSystem types in a deploymentA typical deployment of Security Access Manager involves the installation and configuration of a number of systems. system typesin deploymentdeploymentsystem typesAll Security Access Manager deployments include several types of Security Access Manager systems that are set up in a secure domain, including:Base systemsWeb Security systemsEach system type has software prerequisites that include Security Access Manager components. You must successfully install and configure both the prerequisites and Security Access Manager components to avoid operational problems in your environment.For example, the Security Access Manager policy server requires installation of the following components:IBM Global Security Kit (GSKit)IBM Security Directory Server client (depending on the registry used)IBM Security UtilitiesSecurity Access Manager LicenseSecurity Access Manager RuntimeSecurity Access Manager Policy ServerVerifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites. Base systems

System types in a deployment

A typical deployment of Security Access Manager involves the installation and configuration of a number of systems.

All Security Access Manager deployments include several types of Security Access Manager systems that are set up in a secure domain, including:

Base systems

Web Security systems

Each system type has software prerequisites that include Security Access Manager components. You must successfully install and configure both the prerequisites and Security Access Manager components to avoid operational problems in your environment.

For example, the Security Access Manager policy server requires installation of the following components:

IBM® Global Security Kit (GSKit)

IBM Security Directory Server client (depending on the registry used)

IBM Security Utilities

Security Access Manager License

Security Access Manager Runtime

Security Access Manager Policy Server

Base systems

Parent topic: Verifying the deployment

Base systemsBase systemsdevelopment systemsbasesystem typesprerequisitessystem typesbase systemsprerequisitesbase systemsTable 1 lists the types of Security Access Manager base systems that you can set up in your secure domain. You must install the Security Directory Server client on each system that runs Security Access Manager, with the following exceptions: The Security Access Manager system is on a supported Windows operating system that is either the Active Directory domain or is joined to the Active Directory domain where the policy server is to be configured.You are setting up an attribute retrieval service or IBM Security Access Manager Runtime for Java, Required components for the Security Access Manager base systemsSystem typeRequired software componentsC developmentrequired componentsrequired componentsC developmentdevelopment systemsC applicationsrequired componentsC development Global Security KitSecurity Directory Server client (depending on the registry used)Security Access Manager RuntimeSecurity Access Manager Application Development Kit Security Directory Serverrequired componentsrequired componentsSecurity Directory ServerSecurity Directory ServerIf you plan to install the Security Directory Server as your Security Access Manager registry, the following components are required: Global Security KitSecurity Directory Server clientDB2 Enterprise Server Edition Refer to the Security Directory Server documentation for information about which versions of the server are supported.runtime for Javarequired componentsrequired componentsruntime for JavaRuntime for Java IBM Security Access Manager Runtime for Java runtimerequired componentsrequired componentsruntimeRuntime Global Security KitSecurity Directory Server client (depending on the registry used)Security Access Manager RuntimeSystem types in a deploymentA typical deployment of Security Access Manager involves the installation and configuration of a number of systems.

Base systems

Table 285 lists the types of Security Access Manager base systems that you can set up in your secure domain.

Note:

You must install the Security Directory Server client on each system that runs Security Access Manager, with the following exceptions:

The Security Access Manager system is on a supported Windows operating system that is either the Active Directory domain or is joined to the Active Directory domain where the policy server is to be configured.

You are setting up an attribute retrieval service or IBM Security Access Manager Runtime for Java,

Table 285. Required components for the Security Access Manager base systems

System type
Required software components

C development

Global Security Kit

Security Directory Server client (depending on the registry used)

Security Access Manager Runtime

Security Access Manager Application Development Kit

Security Directory Server
If you plan to install the Security Directory Server as your Security Access Manager registry, the following components are required:

Global Security Kit

Security Directory Server client

DB2® Enterprise Server Edition

Note: Refer to the Security Directory Server documentation for information about which versions of the server are supported.

Runtime for Java

IBM Security Access Manager Runtime for Java

Runtime

Global Security Kit

Security Directory Server client (depending on the registry used)

Security Access Manager Runtime

Parent topic: System types in a deployment

Checking installed softwareChecking installed softwareChecking installed softwareSecurity Access Manager provides commands and utilities to help you determine whether the correct software, and software level, is installed on any operating system.prerequisites, checkpdversion utilitycommandspdversionutilitiespdversionswlist commandrpm -qa commandpkginfo -l commandcommandsswlistcommandsrpm -qacommandspkginfo -lAIXlslpp –l commandcommandslslpp –llslpp –l commandLinuxrpm –qa commandSolarispkginfo –l commandWindowsAdd/Remove Program facilityUse the pdversion utility to list Security Access Manager components that are installed on the system along with their version number. This utility does not list prerequisite software, such as IBM Global Security Kit (GSKit).You can also determine the presence or absence of prerequisite software with operating system utilities. The utilities, by operating system, are as follows: AIXThe lslpp –l commandLinuxThe rpm –qa commandSolarisThe pkginfo –l commandWindowsThe Add/Remove Programs facility from the Control PanelUse these tools with the product requirements that are listed in the Clearinghouse reports you can obtain from the product requirement link on the Welcome page in the Knowledge Center. Ensure that all the required software is installed on each system in your Security Access Manager deployment. Verifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites.

Checking installed software

Security Access Manager provides commands and utilities to help you determine whether the correct software, and software level, is installed on any operating system.

Use the pdversion utility to list Security Access Manager components that are installed on the system along with their version number. This utility does not list prerequisite software, such as IBM® Global Security Kit (GSKit).

You can also determine the presence or absence of prerequisite software with operating system utilities. The utilities, by operating system, are as follows:

AIX®

The lslpp –l command

Linux

The rpm –qa command

Solaris

The pkginfo –l command

Windows

The Add/Remove Programs facility from the Control Panel

Use these tools with the product requirements that are listed in the Clearinghouse reports you can obtain from the product requirement link on the Welcome page in the Knowledge Center. Ensure that all the required software is installed on each system in your Security Access Manager deployment.

Parent topic: Verifying the deployment

Verifying Global Security KitVerifying the Global Security KitVerifying the Global Security KitEnsure that the Global Security Kit is installed and working properly for your environment.Global Security KitGSKitverifyThe two most common problems with the IBM Global Security Kit (GSKit) include: GSKit was not installedThe wrong version of GSKit is installed, left over from a previous installationGSKit on Windows operating systems does not add an entry to the Add/Remove Program list. On Windows operating systems, GSKit is typically installed in the following directory: C:\Program Files\IBM\gsk8Use the following command on Windows operating systems to display the GSKit version: C:\Program Files\IBM\gsk8\bin\gsk8ver_64Verifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites.

Verifying Global Security Kit

Ensure that the Global Security Kit is installed and working properly for your environment.

The two most common problems with the IBM® Global Security Kit (GSKit) include:

GSKit was not installed

The wrong version of GSKit is installed, left over from a previous installation

GSKit on Windows operating systems does not add an entry to the Add/Remove Program list. On Windows operating systems, GSKit is typically installed in the following directory:

C:\Program Files\IBM\gsk8

Use the following command on Windows operating systems to display the GSKit version:

C:\Program Files\IBM\gsk8\bin\gsk8ver_64

Parent topic: Verifying the deployment

Verifying user registriesVerifying user registriesVerifying user registriesThis section provides information about verifying the different Security Access Manager user registries.user registriesverifyVerifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites. Security Directory ServerThis section provides information about verifying Security Directory Server when it is used as the Security Access Manager user registry.Microsoft Active DirectoryThis section provides information about verifying Microsoft Active Directory when it is used as the Security Access Manager user registry.

Verifying user registries

This section provides information about verifying the different Security Access Manager user registries.

Security Directory Server
This section provides information about verifying Security Directory Server when it is used as the Security Access Manager user registry.

Microsoft Active Directory
This section provides information about verifying Microsoft Active Directory when it is used as the Security Access Manager user registry.

Parent topic: Verifying the deployment

Security Directory ServerSecurity Directory ServerSecurity Directory ServerThis section provides information about verifying Security Directory Server when it is used as the Security Access Manager user registry.Security Directory Serververifyuser registriesLDAP serverSecurity Directory Serveruser registries, verify user registriesSecurity Directory SerververifyVerifying user registriesThis section provides information about verifying the different Security Access Manager user registries.Verifying the serverCommunication between the Security Directory Server client and the LDAP server can be tested by using the ldapsearch command. This command also reveals the version of the LDAP server software. Verifying the client

Security Directory Server

This section provides information about verifying Security Directory Server when it is used as the Security Access Manager user registry.

Verifying the server
Communication between the Security Directory Server client and the LDAP server can be tested by using the ldapsearch command. This command also reveals the version of the LDAP server software.

Verifying the client

Parent topic: Verifying user registries

Verifying the serverVerifying the serverVerifying the serverCommunication between the Security Directory Server client and the LDAP server can be tested by using the ldapsearch command. This command also reveals the version of the LDAP server software. Security Directory SerververifyserverSecurity Directory Serververify versionSecurity Directory Serverconnection confirmationLDAP serverSecurity Directory Serverserver, verifycommandsldapsearchThis command (entered as one line) can be run from any machine with Security Directory Server client installed. The structure of the ldapsearch command different when you use SSL. Without SSLThe following sample command is appropriate when the LDAP server is configured for non-SSL communication: ldapsearch -h ldapserver-hostname -p 389 -D "ldapadminDN" \ -w ldapadmin-password -b "" -s base objectclass=* If this command fails on a Windows operating system, check that the ldapsearch command is the one that is provided by Security Directory Server client. The output of this command varies depending on which supported LDAP server you are using.With SSLThe following sample command is appropriate when the LDAP server is configured for SSL communication: ldapsearch -h ldapserver-hostname -p 636 -D "ldapadminDN" \ -w ldapadmin-password -Z -K client-keyfile \ -P key-password -b "" -s base objectclass=* The output of this command varies depending on which supported LDAP server you are using.Security Directory ServerThis section provides information about verifying Security Directory Server when it is used as the Security Access Manager user registry.

Verifying the server

Communication between the Security Directory Server client and the LDAP server can be tested by using the ldapsearch command. This command also reveals the version of the LDAP server software.

This command (entered as one line) can be run from any machine with Security Directory Server client installed. The structure of the ldapsearch command different when you use SSL.

Without SSL

The following sample command is appropriate when the LDAP server is configured for non-SSL communication:

ldapsearch -h ldapserver-hostname -p 389 -D "ldapadminDN" \
-w ldapadmin-password -b "" -s base objectclass=*

Note: If this command fails on a Windows operating system, check that the ldapsearch command is the one that is provided by Security Directory Server client.

The output of this command varies depending on which supported LDAP server you are using.

With SSL

The following sample command is appropriate when the LDAP server is configured for SSL communication:

ldapsearch -h ldapserver-hostname -p 636 -D "ldapadminDN" \
-w ldapadmin-password -Z -K client-keyfile \
-P key-password -b "" -s base objectclass=*

The output of this command varies depending on which supported LDAP server you are using.

Parent topic: Security Directory Server

Verifying the clientVerifying the clientVerifying the clientSecurity Directory SerververifyclientLDAP serverSecurity Directory Serverclient, verifyThe previous verification procedure for the LDAP server used the Security Directory Server client that was installed on the LDAP server system itself. However, unless you are using Active Directory server for your Security Access Manager user registry, each Security Access Manager system requires the installation of the Security Directory Server client, not just the machine with the LDAP server installed.The previous verification procedure for the LDAP server is also appropriate for verifying the functions of the Security Directory Server client on each Security Access Manager system.Security Directory ServerThis section provides information about verifying Security Directory Server when it is used as the Security Access Manager user registry.

Verifying the client

The previous verification procedure for the LDAP server used the Security Directory Server client that was installed on the LDAP server system itself. However, unless you are using Active Directory server for your Security Access Manager user registry, each Security Access Manager system requires the installation of the Security Directory Server client, not just the machine with the LDAP server installed.

The previous verification procedure for the LDAP server is also appropriate for verifying the functions of the Security Directory Server client on each Security Access Manager system.

Parent topic: Security Directory Server

Microsoft Active DirectoryMicrosoft Active DirectoryMicrosoft Active DirectoryThis section provides information about verifying Microsoft Active Directory when it is used as the Security Access Manager user registry.Active Directoryverifyuser registriesActive Directoryuser registries, verify user registriesActive DirectoryVerifying user registriesThis section provides information about verifying the different Security Access Manager user registries.Verifying the configurationVerify that the configuration of the server and client completed successfully.Verifying version numbersConfirming connectivityInstall Windows 2008 Support Tools from the \support\tools directory on the Windows 2008 operating system DVD. From that directory, run setup.exe and follow the installation guide to complete the installation.

Microsoft Active Directory

This section provides information about verifying Microsoft Active Directory when it is used as the Security Access Manager user registry.

Verifying the configuration
Verify that the configuration of the server and client completed successfully.

Verifying version numbers

Confirming connectivity
Install Windows 2008 Support Tools from the \support\tools directory on the Windows 2008 operating system DVD. From that directory, run setup.exe and follow the installation guide to complete the installation.

Parent topic: Verifying user registries

Verifying the configurationVerifying the configurationVerifying the configurationVerify that the configuration of the server and client completed successfully.Active DirectoryverifyconfigurationActive Directoryconfiguration, verify ServerStart the MMC for Active Directory by selecting Start → Program → Administrative Tools → Active Directory Users and Computers. If the Active Directory management console started and you can browse all the objects in Active Directory, the Active Directory server completed its configuration correctly. Otherwise, you can complete the procedures to unconfigure and reconfigure Active Directory as described in the ADK Installation topics in the Knowledge Center.ClientConfigure the client into an existing Active Directory domain to complete Security Access Manager configuration. To ensure that the client system is part of the Active Directory domain, you can use System Properties to ensure the correct configuration of the client machine by selecting Start → Settings → Control Panel → System → System Properties. In the Control Panel, double-click on System icon. The System Properties window is displayed. On the System Properties windows, click the Network Identification menu. If the Domain on the Network Identification contains the correct Active Directory domain, it indicates that the client machine is properly configured into the Active Directory domain.Microsoft Active DirectoryThis section provides information about verifying Microsoft Active Directory when it is used as the Security Access Manager user registry.

Verifying the configuration

Verify that the configuration of the server and client completed successfully.

Server

Start the MMC for Active Directory by selecting Start → Program → Administrative Tools → Active Directory Users and Computers.

If the Active Directory management console started and you can browse all the objects in Active Directory, the Active Directory server completed its configuration correctly. Otherwise, you can complete the procedures to unconfigure and reconfigure Active Directory as described in the ADK Installation topics in the Knowledge Center.

Client

Configure the client into an existing Active Directory domain to complete Security Access Manager configuration. To ensure that the client system is part of the Active Directory domain, you can use System Properties to ensure the correct configuration of the client machine by selecting Start → Settings → Control Panel → System → System Properties.

In the Control Panel, double-click on System icon. The System Properties window is displayed. On the System Properties windows, click the Network Identification menu. If the Domain on the Network Identification contains the correct Active Directory domain, it indicates that the client machine is properly configured into the Active Directory domain.

Parent topic: Microsoft Active Directory

Verifying version numbersVerifying version numbersVerifying version numbersActive DirectoryverifyversionActive Directoryversion, verify ServerActive Directory is included with Windows Advanced Server installation. Therefore, only one version of this software is possible. After successfully configuring the Active Directory server, it is started automatically during the reboot process.ClientActive Directory is included with Windows Advanced Server installation. Therefore, only one version of this software is possible.Microsoft Active DirectoryThis section provides information about verifying Microsoft Active Directory when it is used as the Security Access Manager user registry.

Verifying version numbers

Server

Active Directory is included with Windows Advanced Server installation. Therefore, only one version of this software is possible. After successfully configuring the Active Directory server, it is started automatically during the reboot process.

Client

Active Directory is included with Windows Advanced Server installation. Therefore, only one version of this software is possible.

Parent topic: Microsoft Active Directory

Confirming connectivityConfirming connectivityConfirming connectivityInstall Windows 2008 Support Tools from the \support\tools directory on the Windows 2008 operating system DVD. From that directory, run setup.exe and follow the installation guide to complete the installation.Active DirectoryverifyconnectionActive DirectoryADSI EditActive Directoryconnection, confirmADSI EditActivate the ADSI Edit MMC window by selecting Start → Programs → Windows 2008 Support Tools → Tools → ADSI Edit.The user can set up the server connection by selecting Action → Settings.Additionally, click Advanced on the Connection window to input the administrator ID and password to connect to the remote Active Directory server. If the connection is successful, the client machine will be able to communicate with the Active Directory server using ADSI.Microsoft Active DirectoryThis section provides information about verifying Microsoft Active Directory when it is used as the Security Access Manager user registry.

Confirming connectivity

Install Windows 2008 Support Tools from the \support\tools directory on the Windows 2008 operating system DVD. From that directory, run setup.exe and follow the installation guide to complete the installation.

Activate the ADSI Edit MMC window by selecting Start → Programs → Windows 2008 Support Tools → Tools → ADSI Edit.

The user can set up the server connection by selecting Action → Settings.

Additionally, click Advanced on the Connection window to input the administrator ID and password to connect to the remote Active Directory server. If the connection is successful, the client machine will be able to communicate with the Active Directory server using ADSI.

Parent topic: Microsoft Active Directory

Verifying base systemsVerifying base systemsVerifying base systemsAt a high level, you can determine which Security Access Manager servers are configured and which are running.policy serververify base systemsauthorization serveravailability verificationpd_start commandcommandspd_startVerifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites. Verifying the policy serverThe pdadmin command can be used to verify the correct operation of the policy server. Verifying the authorization serverThe Security Access Manager application development toolkit (ADK) includes the authzn_demo demonstration program. You can use this program, in remote mode, to validate the correct operation of the authorization server. Verifying the runtimeThe Security Access Manager Runtime can be installed on a system with only GSKit and Security Directory Server client.

Verifying base systems

At a high level, you can determine which Security Access Manager servers are configured and which are running.

Verifying the policy server
The pdadmin command can be used to verify the correct operation of the policy server.

Verifying the authorization server
The Security Access Manager application development toolkit (ADK) includes the authzn_demo demonstration program. You can use this program, in remote mode, to validate the correct operation of the authorization server.

Verifying the runtime
The Security Access Manager Runtime can be installed on a system with only GSKit and Security Directory Server client.

Parent topic: Verifying the deployment

Verifying the policy serverVerifying the policy serverVerifying the policy serverThe pdadmin command can be used to verify the correct operation of the policy server. servercommandslistcommandsserver listobjectslist commandobjectslistingcommandsobject listcommandsacl listACLsverifyuser list commanduserslistcommandsuser listEnter the following command to log in as a Security Access Manager administrator: pdadmin –a sec_master –p passwordAssuming that WebSEAL is configured on the machine, at the pdadmin prompt, complete the following steps: List the servers with the server list command. For this purpose, this command has the following syntax:pdadmin> server list webseald-machinenameList the objects with the object list command without options, as follows:pdadmin> object listList ACLs with the acl list command without options, as follows:pdadmin> acl listList users with the user list command. For this purpose, this command has the following syntax:pdadmin> user list name countVerifying base systemsAt a high level, you can determine which Security Access Manager servers are configured and which are running.

Verifying the policy server

The pdadmin command can be used to verify the correct operation of the policy server.

About this task

Enter the following command to log in as a Security Access Manager administrator:

pdadmin –a sec_master –p password

Assuming that WebSEAL is configured on the machine, at the pdadmin prompt, complete the following steps:

List the servers with the server list command. For this purpose, this command has the following syntax:

pdadmin> server list webseald-machinename

List the objects with the object list command without options, as follows:

pdadmin> object list

List ACLs with the acl list command without options, as follows:

pdadmin> acl list

List users with the user list command. For this purpose, this command has the following syntax:

pdadmin> user list name count

Parent topic: Verifying base systems

Verifying the authorization serverVerifying the authorization serverVerifying the authorization serverThe Security Access Manager application development toolkit (ADK) includes the authzn_demo demonstration program. You can use this program, in remote mode, to validate the correct operation of the authorization server. authorization servertest operationdemonstration programauthzn_demo programfilesauthzn_demoSee the README file that accompanies this demonstration program for setup and execution instructions. The README file is in the following directory:authzn-adk-install-dir/example/auth_demo/cppVerifying base systemsAt a high level, you can determine which Security Access Manager servers are configured and which are running.

Verifying the authorization server

The Security Access Manager application development toolkit (ADK) includes the authzn_demo demonstration program. You can use this program, in remote mode, to validate the correct operation of the authorization server.

See the README file that accompanies this demonstration program for setup and execution instructions. The README file is in the following directory:

authzn-adk-install-dir/example/auth_demo/cpp

Parent topic: Verifying base systems

Verifying the runtimeVerifying the runtimeVerifying the runtimeThe Security Access Manager Runtime can be installed on a system with only GSKit and Security Directory Server client. runtimetesting operationIn this case, the verification procedure for the Security Access Manager Runtime is the same as that described in Verifying the policy serverThe pdadmin command can be used to verify the correct operation of the policy server. .Verifying base systemsAt a high level, you can determine which Security Access Manager servers are configured and which are running.

Verifying the runtime

The Security Access Manager Runtime can be installed on a system with only GSKit and Security Directory Server client.

In this case, the verification procedure for the Security Access Manager Runtime is the same as that described in Verifying the policy server.

Parent topic: Verifying base systems

Verifying Web security systemsVerifying Web security systemsVerifying Web security systemsYou can verify whether Web security systems are operating properly by connecting from your browser to a URL.Web security system, verifyVerifying the deploymentThe installation of Security Access Manager involves the installation and configuration of a number of prerequisites. Verifying WebSEALYou can use a browser to verify that WebSEAL is operating properly.

Verifying Web security systems

You can verify whether Web security systems are operating properly by connecting from your browser to a URL.

Verifying WebSEAL
You can use a browser to verify that WebSEAL is operating properly.

Parent topic: Verifying the deployment

Verifying WebSEALVerifying WebSEALVerifying WebSEALYou can use a browser to verify that WebSEAL is operating properly. WebSEALverifyTo verify, enter the following URL into your browser:https://webseal-machinenameBecause a port number is not specified, it is assumed that WebSEAL is listening on port 443 (HTTPS). Your browser might give you the following warnings: The certificate received from this Web server is issued by a company that you have not yet chosen to trustThe name within the certificate received from WebSEAL does not match the name of the system from which it was receivedIf these warnings occur, they indicate that you did not yet purchase your own server certificate for your WebSEAL server. Your browser is complaining that it received a default server certificate from WebSEAL which contains default names for the issuing certificate authority and the name of the Web server.Next, the browser prompts you to specify a Security Access Manager user name and password. Enter sec_master for the user name and the password that you configured for sec_master during installation. If authentication is successful, an image that is labeled Security Access Manager for WebSEAL displays.Verifying Web security systemsYou can verify whether Web security systems are operating properly by connecting from your browser to a URL.

Verifying WebSEAL

You can use a browser to verify that WebSEAL is operating properly.

To verify, enter the following URL into your browser:

https://webseal-machinename

Because a port number is not specified, it is assumed that WebSEAL is listening on port 443 (HTTPS).

Your browser might give you the following warnings:

The certificate received from this Web server is issued by a company that you have not yet chosen to trust

The name within the certificate received from WebSEAL does not match the name of the system from which it was received

If these warnings occur, they indicate that you did not yet purchase your own server certificate for your WebSEAL server. Your browser is complaining that it received a default server certificate from WebSEAL which contains default names for the issuing certificate authority and the name of the Web server.

Next, the browser prompts you to specify a Security Access Manager user name and password. Enter sec_master for the user name and the password that you configured for sec_master during installation. If authentication is successful, an image that is labeled Security Access Manager for WebSEAL displays.

Parent topic: Verifying Web security systems

Collecting events to diagnose or audit server operationsCollecting events to diagnose or audit server operationsCollecting events to diagnose or audit server operationsYou can collect events for diagnostic and auditing purposes of the servers. eventscollectEvents for diagnostics and auditing are for operations of the Security Access Manager servers. These events are not for installation of the servers.To enable diagnostics and auditing, you define which types of events to capture. When events are captured, they can be written to:Log fileStandard output (STDOUT) deviceStandard error (STDERR) deviceCombination of these destinations.Beyond these destinations, when events are captured, they can be redirected to a remote server or redirected to an application for processing with log agents.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Diagnostic eventsFor collecting diagnostic information, define which message events and which trace events to capture. These events can help you troubleshoot problems.Auditing eventsFor auditing purposes, define audit, statistic, or other type of events for capture in a log file.

Collecting events to diagnose or audit server operations

You can collect events for diagnostic and auditing purposes of the servers.

Events for diagnostics and auditing are for operations of the Security Access Manager servers.

These events are not for installation of the servers.

To enable diagnostics and auditing, you define which types of events to capture. When events are captured, they can be written to:

Log file

Standard output (STDOUT) device

Standard error (STDERR) device

Combination of these destinations.

Beyond these destinations, when events are captured, they can be redirected to a remote server or redirected to an application for processing with log agents.

Diagnostic events
For collecting diagnostic information, define which message events and which trace events to capture. These events can help you troubleshoot problems.

Auditing events
For auditing purposes, define audit, statistic, or other type of events for capture in a log file.

Parent topic: Troubleshooting

Diagnostic eventsDiagnostic eventsDiagnostic eventsFor collecting diagnostic information, define which message events and which trace events to capture. These events can help you troubleshoot problems.diagnostic eventsmessagestrace dataeventsdiagnosticeventsmessageseventstraceA message event is a record of a noteworthy event that occurred, such as a failure to connect error message.A trace event is a capture of information about the current operating environment at the time that a component or application failed to operate as intended. Trace event logs provide IBM Support with information that relates to the condition of the system at the time a problem occurred. Trace logging enablement can cause large amounts of data to collect in a short amount of time. Therefore, enable trace events only at the direction of IBM Support. To configure message or trace events, define statements in the routing file or Java properties file for the server:For message events, define the statements by severity level. For trace events, define the statements by trace level and, optionally, by component. Collecting events to diagnose or audit server operationsYou can collect events for diagnostic and auditing purposes of the servers.

Diagnostic events

For collecting diagnostic information, define which message events and which trace events to capture. These events can help you troubleshoot problems.

A message event is a record of a noteworthy event that occurred, such as a failure to connect error message.

A trace event is a capture of information about the current operating environment at the time that a component or application failed to operate as intended.

Trace event logs provide IBM® Support with information that relates to the condition of the system at the time a problem occurred. Trace logging enablement can cause large amounts of data to collect in a short amount of time. Therefore, enable trace events only at the direction of IBM Support.

To configure message or trace events, define statements in the routing file or Java™ properties file for the server:

For message events, define the statements by severity level.

For trace events, define the statements by trace level and, optionally, by component.

Parent topic: Collecting events to diagnose or audit server operations

Auditing eventsAuditing eventsAuditing eventsFor auditing purposes, define audit, statistic, or other type of events for capture in a log file.audit eventsstatisticsaudit eventseventsauditeventsstatisticsAuditing provides tracking and archiving of auditable events. These events create records of various server activities. Configure audit event logs by using r the base Security Access Manager.Configure audit events by defining stanza entries in configuration files. Define stanza entries in configuration files: For base Security Access Manager auditing: define logcfg entries in the [pdaudit-filter] stanza. For WebSEAL, you can also log HTTP events by using the [logging] stanza in the WebSEAL configuration file.For more information about audit events, see the Auditing topics in the Knowledge Center.Collecting events to diagnose or audit server operationsYou can collect events for diagnostic and auditing purposes of the servers.

Auditing events

For auditing purposes, define audit, statistic, or other type of events for capture in a log file.

Auditing provides tracking and archiving of auditable events. These events create records of various server activities. Configure audit event logs by using r the base Security Access Manager.

Configure audit events by defining stanza entries in configuration files. Define stanza entries in configuration files:

For base Security Access Manager auditing: define logcfg entries in the [pdaudit-filter] stanza.

For WebSEAL, you can also log HTTP events by using the [logging] stanza in the WebSEAL configuration file.

For more information about audit events, see the Auditing topics in the Knowledge Center.

Parent topic: Collecting events to diagnose or audit server operations

Customize logging events with routing filesCustomize logging events with routing filesCustomize logging events with routing filesRouting files are ASCII files that customize the logging of message and trace events for C language-based servers, daemons, and other C-language programs and applications.routing filesmessagesoverviewrouting filestracesoverviewfilesroutingTo customize logging of message and trace events for Java applications, see Java properties filesJava properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application..At application startup, the application-specific routing file is read. With the routing file content, you can control the following aspects of logging event activity: Whether to enable logging for specific event classes.Where to direct the output for each event class.How many log files to use for each event class.How large each log file can be for each event class.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Location of routing filesYou can locate routing files to control the logging of both message events and trace events.Routing file entriesEach routing file contains entries that control the logging of message events and trace events. However, the format of these entries differs by event type.

Customize logging events with routing files

Routing files are ASCII files that customize the logging of message and trace events for C language-based servers, daemons, and other C-language programs and applications.

To customize logging of message and trace events for Java™ applications, see Java properties files.

At application startup, the application-specific routing file is read. With the routing file content, you can control the following aspects of logging event activity:

Whether to enable logging for specific event classes.

Where to direct the output for each event class.

How many log files to use for each event class.

How large each log file can be for each event class.

Location of routing files
You can locate routing files to control the logging of both message events and trace events.

Routing file entries
Each routing file contains entries that control the logging of message events and trace events. However, the format of these entries differs by event type.

Parent topic: Troubleshooting

Location of routing filesLocation of routing filesLocation of routing filesYou can locate routing files to control the logging of both message events and trace events.routing fileslocationrouting filesrouting.template (WebSEAL)routing.template file (WebSEAL)WebSEALrouting.template fileRouting files can be edited through the appliance Web interface.Runtime ComponentFrom the main menu select Secure Web Settings -> Manage -> Runtime Component. In the Runtime Component panel select Manage -> Configuration Files -> Routing File.WebSEAL serversFrom the main menu select Secure Web Settings -> Manage -> Reverse Proxy. In the Reverse Proxy panel select a reverse proxy instance, then select Manage -> Configuration -> Edit Routing File. Authorization ServerFrom the main menu select Secure Web Settings -> Manage -> Authorization Server. In the Authorization Server panel select an authorization server instance, then select Manage -> Configuration -> Edit Routing File.Customize logging events with routing filesRouting files are ASCII files that customize the logging of message and trace events for C language-based servers, daemons, and other C-language programs and applications.

Location of routing files

You can locate routing files to control the logging of both message events and trace events.

Routing files can be edited through the appliance Web interface.

Runtime Component

From the main menu select Secure Web Settings -> Manage -> Runtime Component. In the Runtime Component panel select Manage -> Configuration Files -> Routing File.

WebSEAL servers

From the main menu select Secure Web Settings -> Manage -> Reverse Proxy. In the Reverse Proxy panel select a reverse proxy instance, then select Manage -> Configuration -> Edit Routing File.

Authorization Server

From the main menu select Secure Web Settings -> Manage -> Authorization Server. In the Authorization Server panel select an authorization server instance, then select Manage -> Configuration -> Edit Routing File.

Parent topic: Customize logging events with routing files

Routing file entriesRouting file entriesRouting file entriesEach routing file contains entries that control the logging of message events and trace events. However, the format of these entries differs by event type. tracerouting filesentry formatrouting filestracesentry formatDISCARD destinationlogseventsDISCARDeventslogsDISCARDFILE destinationlogseventsFILEeventslogsFILESTDERR destinationlogseventsSTDERReventslogsSTDERRSTDOUT destinationlogseventsSTDOUTeventslogsSTDOUTTEXTFILE destinationlogseventsTEXTFILEeventslogsTEXTFILEUTF8FILE destinationlogseventsUTF8FILEeventslogsUTF8FILEXMLFILE destinationlogseventsXMLFILEeventslogsXMLFILEXMLSTDERR destinationlogseventsXMLSTDERReventslogsXMLSTDERRXMLSTDOUT destinationlogseventsXMLSTDOUTeventslogsXMLSTDOUTGOESTO destinationlogseventsGOESTOeventslogsGOESTOUse one of the following formats (entered on a single line without spaces) when you define entries in routing files: Message eventsseverity:destination:location [[;destination:location]...] [;GOESTO:{other_severity | other_component}]Trace eventscomponent:subcomponent.level[[,subcomponent.level]...] :destination:location [[;destination:location]...] [;GOESTO:{other_severity | other_component}]Where: component:subcomponent.level[[,subcomponent.level]...]Specifies the component, subcomponents, and reporting levels of trace events to log. For trace events only. For the component portion, you can specify an asterisk (*) to log trace data for all components.Do not set a single entry that contains an asterisk for all components as it might prevent the Web Reverse Proxy from starting. For example, the following entry prevents the Web Reverse Proxy from starting after the change is deployed:*:*.9:UTF8FILE:pdweb_trace.log Instead set multiple lines that contain specific component names, for example:mgr:*.9:UTF8FILE:pdweb_trace.log ras:*.9:UTF8FILE:pdweb_trace.log acl:*.9:UTF8FILE:pdweb_trace.log idb:*.9:UTF8FILE:pdweb_trace.log ira:*.9:UTF8FILE:pdweb_trace.log wiv:*.9:UTF8FILE:pdweb_trace.log wns:*.9:UTF8FILE:pdweb_trace.log wwa:*.9:UTF8FILE:pdweb_trace.log bas:*.9:UTF8FILE:pdweb_trace.log bcf:*.9:UTF8FILE:pdweb_trace.logSetting these entries in the routing file permits the Web Reverse Proxy to start after the change is deployed.For the subcomponent portion, you can specify an asterisk (*) to log trace data for all subcomponents of the specified component.For the level portion, specify the reporting level to log. This value is a number 1 - 9. A level of 1 indicates the least number of details, and a level of 9 indicates the greatest number of details.destinationSpecifies where to log the events. For each destination, you need to specify a location. When you specify multiple destination-location pairs, separate each pair with a semicolon (;). The following destinations are valid: DISCARDDiscards the events.FILEWrites the events as ASCII text in the current code page and locale to the specified location. When you use this destination, you must specify a location for the file. Optionally, you can follow the FILE destination by a period and two numbers that are separated by a period (for example, FILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only one log file that grows without limit. The average size of an ASCII event is 200 bytes. Because the maximum size of a log file is 2 GB, limit the maximum number of events to approximately 10,000,000 events.STDERRWrites the events as ASCII text in the current code page and locale to the standard error device.STDOUTWrites the events as ASCII text in the current code page and locale to the standard output device.TEXTFILESame as FILE.UTF8FILEWrites the events as UTF-8 text to the specified location. When you use this destination, you must specify a location for the file. Optionally, you can follow the UTF8FILE destination by a period and two numbers that are separated by a period (for example, UTF8FILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only one log file that grows without limit. The average size of a UTF-8 event is 200 bytes. Because the maximum size of a log file is 2 GB, limit the maximum number of events to approximately 10,000,000 events.When the operating system does not use a UTF-8 code page, the conversion to UTF-8 can result in data loss. When data loss occurs, the log file contains a series of question mark (?) characters at the location where the data conversion was problematic.XMLFILEWrites events to the specified location in the XML log format. When you use this destination, you must specify a location for the file. Optionally, you can follow the XMLFILE destination by a period and two numbers that are separated by a period (for example, XMLFILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only one log file that grows without limit. The average size of an XML message event is 650 bytes, and the average size of an XML trace event is 500 bytes. Because the maximum size of a log file is 2 GB, limit the maximum number of events to approximately 3,000,000 message events or 4,000,000 trace events.XMLSTDERRWrites events to the standard error device in the XML log format.XMLSTDOUTWrites events to the standard output device in the XML log format.GOESTO:{other_severity | other_component}]Specifies to route events to the same destination and location as either message events of the specified severity or trace events of the specified component.locationSpecifies the name and location of the log file. When the destination is TEXT, TEXTFILE, UTF8FILE or XMLFILE, you must specify a location. When the destination is DISCARD, STDERR, STDOUT, XMLSTDERR or XMLSTDOUT, you must specify a hyphen (-). When you specify a fully qualified file name, you can use the %ld character string to insert the process ID into the file name.When the number of files is specified as part of the destination, a period and the file number are appended to the specified log file. On Windows operating systems, the file name must not end with a period. If the file name ends with a period, when the file number is appended, the file name contains two consecutive periods. File names with two consecutive periods are not valid.On AIX, Linux, and Solaris operating systems, the file name must be followed by file permissions, the user who owns the file, and the group that owns the file. Use the following format: location:permissions:owner:groupTo specify the location for message events from the policy server and write them to the default UTF-8 log file, you can specify the following location: /var/PolicyDirector/log/msg__pdmgrd_utf8.log:644:ivmgr:ivmgrseveritySpecifies the severity of the message events to log. For message events only. The following message severities are valid: FATALERRORWARNINGNOTICENOTICE_VERBOSEYou can specify an asterisk (*) to log messages regardless of severity.For complete details about the severity of message events, see Severity of message eventsIn the message log file, each message event has an associated severity level. .Customize logging events with routing filesRouting files are ASCII files that customize the logging of message and trace events for C language-based servers, daemons, and other C-language programs and applications.

Routing file entries

Each routing file contains entries that control the logging of message events and trace events. However, the format of these entries differs by event type.

Use one of the following formats (entered on a single line without spaces) when you define entries in routing files:

Message events

severity:destination:location [[;destination:location]...] [;GOESTO:{other_severity | other_component}]

Trace events

component:subcomponent.level[[,subcomponent.level]...] :destination:location [[;destination:location]...] [;GOESTO:{other_severity | other_component}]

Where:

component:subcomponent.level[[,subcomponent.level]...]

Specifies the component, subcomponents, and reporting levels of trace events to log. For trace events only.

For the component portion, you can specify an asterisk (*) to log trace data for all components.

Note: Do not set a single entry that contains an asterisk for all components as it might prevent the Web Reverse Proxy from starting. For example, the following entry prevents the Web Reverse Proxy from starting after the change is deployed:

*:*.9:UTF8FILE:pdweb_trace.log

Instead set multiple lines that contain specific component names, for example:

mgr:*.9:UTF8FILE:pdweb_trace.log
ras:*.9:UTF8FILE:pdweb_trace.log
acl:*.9:UTF8FILE:pdweb_trace.log
idb:*.9:UTF8FILE:pdweb_trace.log
ira:*.9:UTF8FILE:pdweb_trace.log
wiv:*.9:UTF8FILE:pdweb_trace.log
wns:*.9:UTF8FILE:pdweb_trace.log
wwa:*.9:UTF8FILE:pdweb_trace.log
bas:*.9:UTF8FILE:pdweb_trace.log
bcf:*.9:UTF8FILE:pdweb_trace.log

Setting these entries in the routing file permits the Web Reverse Proxy to start after the change is deployed.

For the subcomponent portion, you can specify an asterisk (*) to log trace data for all subcomponents of the specified component.

For the level portion, specify the reporting level to log. This value is a number 1 - 9. A level of 1 indicates the least number of details, and a level of 9 indicates the greatest number of details.

destination

Specifies where to log the events. For each destination, you need to specify a location. When you specify multiple destination-location pairs, separate each pair with a semicolon (;). The following destinations are valid:

DISCARD

Discards the events.

FILE

Writes the events as ASCII text in the current code page and locale to the specified location. When you use this destination, you must specify a location for the file. Optionally, you can follow the FILE destination by a period and two numbers that are separated by a period (for example, FILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only one log file that grows without limit.

The average size of an ASCII event is 200 bytes. Because the maximum size of a log file is 2 GB, limit the maximum number of events to approximately 10,000,000 events.

STDERR

Writes the events as ASCII text in the current code page and locale to the standard error device.

STDOUT

Writes the events as ASCII text in the current code page and locale to the standard output device.

TEXTFILE

Same as FILE.

UTF8FILE

Writes the events as UTF-8 text to the specified location. When you use this destination, you must specify a location for the file. Optionally, you can follow the UTF8FILE destination by a period and two numbers that are separated by a period (for example, UTF8FILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only one log file that grows without limit.

The average size of a UTF-8 event is 200 bytes. Because the maximum size of a log file is 2 GB, limit the maximum number of events to approximately 10,000,000 events.

Note: When the operating system does not use a UTF-8 code page, the conversion to UTF-8 can result in data loss. When data loss occurs, the log file contains a series of question mark (?) characters at the location where the data conversion was problematic.

XMLFILE

Writes events to the specified location in the XML log format. When you use this destination, you must specify a location for the file. Optionally, you can follow the XMLFILE destination by a period and two numbers that are separated by a period (for example, XMLFILE.10.100). The first value indicates the number of files to use. The second value indicates the number of events each file can contain. If you do not specify these values, there is only one log file that grows without limit.

The average size of an XML message event is 650 bytes, and the average size of an XML trace event is 500 bytes. Because the maximum size of a log file is 2 GB, limit the maximum number of events to approximately 3,000,000 message events or 4,000,000 trace events.

XMLSTDERR

Writes events to the standard error device in the XML log format.

XMLSTDOUT

Writes events to the standard output device in the XML log format.

GOESTO:{other_severity | other_component}]

Specifies to route events to the same destination and location as either message events of the specified severity or trace events of the specified component.

location

Specifies the name and location of the log file. When the destination is TEXT, TEXTFILE, UTF8FILE or XMLFILE, you must specify a location. When the destination is DISCARD, STDERR, STDOUT, XMLSTDERR or XMLSTDOUT, you must specify a hyphen (-).

When you specify a fully qualified file name, you can use the %ld character string to insert the process ID into the file name.

When the number of files is specified as part of the destination, a period and the file number are appended to the specified log file.

Note: On Windows operating systems, the file name must not end with a period. If the file name ends with a period, when the file number is appended, the file name contains two consecutive periods. File names with two consecutive periods are not valid.

On AIX, Linux, and Solaris operating systems, the file name must be followed by file permissions, the user who owns the file, and the group that owns the file. Use the following format:

location:permissions:owner:group

To specify the location for message events from the policy server and write them to the default UTF-8 log file, you can specify the following location:

/var/PolicyDirector/log/msg__pdmgrd_utf8.log:644:ivmgr:ivmgr

severity

Specifies the severity of the message events to log. For message events only.

The following message severities are valid:

FATAL

ERROR

WARNING

NOTICE

NOTICE_VERBOSE

You can specify an asterisk (*) to log messages regardless of severity.

For complete details about the severity of message events, see Severity of message events.

Parent topic: Customize logging events with routing files

Java properties filesJava properties filesJava properties filesJava properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.properties fileseventsoverviewproperties filestracesovervieweventsproperties filesoverviewThe contents of the properties file enables the user to control the following aspects of message logs: Whether event logs are enabledWhere to direct the outputIf the output is to a file, the number of files to use and the size of each fileLines in the file that start with a number sign (#) are comments and do not affect logging.The application name (app_name) is part of each logging property for a Java application. The application name is specified when you use the com.tivoli.pd.jcfg.SvrSslCfg command.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Location of Java properties filesApplication-specific logging of Java applicationsConfiguration of message and trace logs for the IBM Security Access Manager Runtime for Java (AMJRTE) component is completed on a per-application basis. This configuration removes the file contention and ownership problems that are encountered in previous versions of Security Access Manager. Configuring message events with the Java properties fileTo capture message events for Java applications, you need to configure the Java properties file.Configuring trace events with the Java properties fileTo capture trace events for Java applications, you need to configure the Java properties file.

Java properties files

Java™ properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.

The contents of the properties file enables the user to control the following aspects of message logs:

Whether event logs are enabled

Where to direct the output

If the output is to a file, the number of files to use and the size of each file

Lines in the file that start with a number sign (#) are comments and do not affect logging.

The application name (app_name) is part of each logging property for a Java application. The application name is specified when you use the com.tivoli.pd.jcfg.SvrSslCfg command.

Location of Java properties files

Application-specific logging of Java applications
Configuration of message and trace logs for the IBM Security Access Manager Runtime for Java (AMJRTE) component is completed on a per-application basis. This configuration removes the file contention and ownership problems that are encountered in previous versions of Security Access Manager.

Configuring message events with the Java properties file
To capture message events for Java applications, you need to configure the Java properties file.

Configuring trace events with the Java properties file
To capture trace events for Java applications, you need to configure the Java properties file.

Parent topic: Troubleshooting

Location of Java properties filesLocation of Java properties filesLocation of Java properties filesproperties fileseventslocationeventsproperties fileslocationThe default locations for the Java properties files for Security Access Manager components are shown in Table 1.Location of Java properties filesComponentDefault file nameJava application that is configured by using the com.tivoli.pd.jcfg.SvrSslCfg class.The output application configuration file as specified in the com.tivoli.pd.jcfg.SvrSslCfg class.Java based Security Access Manager commands, such as the pdjrtecfg command and com.tivoli.pd.jcfg.SvrSslCfg or applications not explicitly configured.$JAVA_HOME/PolicyDirector/PDJLog.propertiesIf the com.tivoli.pd.jcfg.SvrSslCfg command was not run, no application-specific configuration file exists. If there is no configuration file, the PDJLog.properties file is used.Java properties filesJava properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.

Location of Java properties files

The default locations for the Java™ properties files for Security Access Manager components are shown in Table 286.

Table 286. Location of Java properties files

Component | Default file name
Java application that is configured by using the com.tivoli.pd.jcfg.SvrSslCfg class. | The output application configuration file as specified in the com.tivoli.pd.jcfg.SvrSslCfg class.
Java based Security Access Manager commands, such as the pdjrtecfg command and com.tivoli.pd.jcfg.SvrSslCfg or applications not explicitly configured. | $JAVA_HOME/PolicyDirector/PDJLog.properties

Note: If the com.tivoli.pd.jcfg.SvrSslCfg command was not run, no application-specific configuration file exists. If there is no configuration file, the PDJLog.properties file is used.

Parent topic: Java properties files

Application-specific logging of Java applicationsApplication-specific logging of Java applicationsApplication-specific logging of Java applicationsConfiguration of message and trace logs for the IBM Security Access Manager Runtime for Java (AMJRTE) component is completed on a per-application basis. This configuration removes the file contention and ownership problems that are encountered in previous versions of Security Access Manager. logging, application-specificIn addition to existing configuration properties, the application properties file created by the com.tivoli.pd.jcfg.SvrSslCfg command contains logging properties that are associated with the application-logging properties for the application. The names of the logging objects and the log files in this configuration file contain the application server name that is supplied by the appSvr parameter of com.tivoli.pd.jcfg.SvrSslCfg. Thus, each application has a unique set of objects and log files. If the configuration file for an application is not being used (for instance, when the pdjrtecfg command is used), message log and tracing properties are taken from the existing PDJLog.properties file.In addition, the size and the number of files that are used for messages and trace entries are now configurable.Java properties filesJava properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.

Application-specific logging of Java applications

Configuration of message and trace logs for the IBM Security Access Manager Runtime for Java (AMJRTE) component is completed on a per-application basis. This configuration removes the file contention and ownership problems that are encountered in previous versions of Security Access Manager.

In addition to existing configuration properties, the application properties file created by the com.tivoli.pd.jcfg.SvrSslCfg command contains logging properties that are associated with the application-logging properties for the application.

The names of the logging objects and the log files in this configuration file contain the application server name that is supplied by the appSvr parameter of com.tivoli.pd.jcfg.SvrSslCfg. Thus, each application has a unique set of objects and log files. If the configuration file for an application is not being used (for instance, when the pdjrtecfg command is used), message log and tracing properties are taken from the existing PDJLog.properties file.

In addition, the size and the number of files that are used for messages and trace entries are now configurable.

Parent topic: Java properties files

Configuring message events with the Java properties fileConfiguring message events with the Java properties fileConfiguring message events with the Java properties fileTo capture message events for Java applications, you need to configure the Java properties file.Java properties filesJava properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.Message loggers and file handlersEach properties file contains properties for one or more message loggers. The isLogging property specifies whether message logs are enabled. When PDJLog.properties is usedConsole handler and console message loggingA console handler and a message console handler also are configured in the $JAVA_HOME/PolicyDirector/PDJLog.properties file. Both are disabled by default.

Configuring message events with the Java properties file

To capture message events for Java™ applications, you need to configure the Java properties file.

Message loggers and file handlers
Each properties file contains properties for one or more message loggers. The isLogging property specifies whether message logs are enabled.

When PDJLog.properties is used

Console handler and console message logging
A console handler and a message console handler also are configured in the $JAVA_HOME/PolicyDirector/PDJLog.properties file. Both are disabled by default.

Parent topic: Java properties files

Message loggers and file handlersMessage loggers and file handlersMessage loggers and file handlersEach properties file contains properties for one or more message loggers. The isLogging property specifies whether message logs are enabled. properties filesmessagingmessage loggersproperties filesmessagingfile handlersmessagesproperties filesmessage loggersmessagesproperties filesfile handlersloggersmessagefileshandlershandlersfileisLogging propertypropertiesisLoggingfilesfileName propertypropertiesfileNameTo turn on logging for a specific message logger, use: baseGroup.PDJapp_nameMessageLogger.isLogging=trueTo disable logging for a specific message logger, use: baseGroup.PDJapp_nameMessageLogger.isLogging=falseAssociated with each message logger is at least one file handler. A file handler specifies the destination for messages. After message logs are enabled by the message logger, the file handler properties are examined to determine whether to log messages, and if so, how and where. The properties that are associated with a file handler are: baseGroup.PDJapp_nameFileHandler.fileName= baseGroup.PDJapp_nameFileHandler.maxFileSize= baseGroup.PDJapp_nameFileHandler.maxFiles=where: fileNameSpecifies the fully qualified file name to be used as the base name for message log files. The file can be in any location accessible by the Java application.maxFileSizemaxFileSize propertypropertiesmaxFileSizeSpecifies the maximum size, in kilobytes, of each message log file. Default is 512.maxFilesmaxFiles propertypropertiesmaxFilesSpecifies the maximum number of files to be used for message logs. Default is 3.To specify what classes of messages to log, use the MessageAllMaskFilter.mask property as illustrated in Figure 1. Specifying what messages to log in a properties filebaseGroup.PDJapp_nameMessageAllMaskFilter.mask=FATAL | ERROR | WARNING | NOTICE | NOTICE_VERBOSEConfiguring message events with the Java properties fileTo capture message events for Java applications, you need to configure the Java properties file.

Message loggers and file handlers

Each properties file contains properties for one or more message loggers. The isLogging property specifies whether message logs are enabled.

To turn on logging for a specific message logger, use:

baseGroup.PDJapp_nameMessageLogger.isLogging=true

To disable logging for a specific message logger, use:

baseGroup.PDJapp_nameMessageLogger.isLogging=false

Associated with each message logger is at least one file handler. A file handler specifies the destination for messages. After message logs are enabled by the message logger, the file handler properties are examined to determine whether to log messages, and if so, how and where. The properties that are associated with a file handler are:

baseGroup.PDJapp_nameFileHandler.fileName=
baseGroup.PDJapp_nameFileHandler.maxFileSize=
baseGroup.PDJapp_nameFileHandler.maxFiles=

where:

fileName

Specifies the fully qualified file name to be used as the base name for message log files. The file can be in any location accessible by the Java™ application.

maxFileSize

Specifies the maximum size, in kilobytes, of each message log file. Default is 512.

maxFiles

Specifies the maximum number of files to be used for message logs. Default is 3.

To specify what classes of messages to log, use the MessageAllMaskFilter.mask property as illustrated in Figure 94..

Figure 94. Specifying what messages to log in a properties file

baseGroup.PDJapp_nameMessageAllMaskFilter.mask=FATAL
 | ERROR | WARNING | NOTICE | NOTICE_VERBOSE

Parent topic: Configuring message events with the Java properties file

When PDJLog.properties is usedWhen PDJLog.properties is usedWhen PDJLog.properties is usedproperties filesmessagingPDJLog.propertiesmessagesproperties filesPDJLog.propertiestraceproperties filesPDJLog.propertiesPDJLog.properties filemessage properties, define PDJLog.properties filetrace properties, define filesPDJLog.propertiesmessage filesPDJLog.propertiestrace The $JAVA_HOME/PolicyDirector/PDJLog.properties file is used to define message and trace log properties in the following cases: For non-application-related Java commands, such as pdjrtecfg and com.tivoli.pd.jcfg.SvrSslCfg.If a Java application was not explicitly configured with the com.tivoli.pd.jcfg.SvrSslCfg command.If the application-specific properties file is inaccessible or does not exist.If a required property in the application-specific properties file is not found.When you use the default PDJLog.properties file, message logs are enabled only for FATAL, ERROR, and WARNING messages. This is shown in the portion of the PDJLog.properties file in Figure 1. Logging can be enabled for NOTICE and NOTICE_VERBOSE messages by changing the isLogging property to true for the last two properties that are shown in Figure 1.Portion of the default PDJLog.properties filebaseGroup.PDJMessageLogger.isLogging=true baseGroup.PDJFatalFileHandler.isLogging=true baseGroup.PDJErrorFileHandler.isLogging=true baseGroup.PDJWarningFileHandler.isLogging=true baseGroup.PDJNoticeFileHandler.isLogging=false baseGroup.PDJNoticeVerboseFileHandler.isLogging=falseOn a AIX, Linux, or Solaris operating system, to enable both NOTICE and NOTICE_VERBOSE messages, and to change the destination properties of NOTICE_VERBOSE messages, the following changes can be made, as indicated in bold: baseGroup.PDJNoticeFileHandler.isLogging=true baseGroup.PDJNoticeVerboseFileHandler.fileName= /tmp/logs/msg__amjrte_verbose.log baseGroup.PDJNoticeVerboseFileHandler.maxFileSize=1024 baseGroup.PDJNoticeVerboseFileHandler.maxFiles=4 baseGroup. PDJNoticeVerboseFileHandler.isLogging=trueAfter you make these changes, NOTICE_VERBOSE messages are written to the /tmp/logs/msg__amjrte_verbose.log1 file. After that file reaches 1024 KB, the file is renamed /tmp/logs/msg__amjrte_verbose.log2 and logging continues with a new /tmp/logs/msg__amjrte_verbose.log1 log file. A maximum of four message log files is used.(The procedure would be the same on a Windows operating system. The file name just needs to be changed to reflect a fully qualified file name on Windows operating systems.)Configuring message events with the Java properties fileTo capture message events for Java applications, you need to configure the Java properties file.

When PDJLog.properties is used

The $JAVA_HOME/PolicyDirector/PDJLog.properties file is used to define message and trace log properties in the following cases:

For non-application-related Java™ commands, such as pdjrtecfg and com.tivoli.pd.jcfg.SvrSslCfg.

If a Java application was not explicitly configured with the com.tivoli.pd.jcfg.SvrSslCfg command.

If the application-specific properties file is inaccessible or does not exist.

If a required property in the application-specific properties file is not found.

When you use the default PDJLog.properties file, message logs are enabled only for FATAL, ERROR, and WARNING messages. This is shown in the portion of the PDJLog.properties file in Figure 95.. Logging can be enabled for NOTICE and NOTICE_VERBOSE messages by changing the isLogging property to true for the last two properties that are shown in Figure 95..

Figure 95. Portion of the default PDJLog.properties file

baseGroup.PDJMessageLogger.isLogging=true
baseGroup.PDJFatalFileHandler.isLogging=true
baseGroup.PDJErrorFileHandler.isLogging=true
baseGroup.PDJWarningFileHandler.isLogging=true
baseGroup.PDJNoticeFileHandler.isLogging=false
baseGroup.PDJNoticeVerboseFileHandler.isLogging=false

On a AIX, Linux, or Solaris operating system, to enable both NOTICE and NOTICE_VERBOSE messages, and to change the destination properties of NOTICE_VERBOSE messages, the following changes can be made, as indicated in bold:

baseGroup.PDJNoticeFileHandler.isLogging=true

baseGroup.PDJNoticeVerboseFileHandler.fileName=
/tmp/logs/msg__amjrte_verbose.log
baseGroup.PDJNoticeVerboseFileHandler.maxFileSize=1024
baseGroup.PDJNoticeVerboseFileHandler.maxFiles=4
baseGroup.
PDJNoticeVerboseFileHandler.isLogging=true

After you make these changes, NOTICE_VERBOSE messages are written to the /tmp/logs/msg__amjrte_verbose.log1 file. After that file reaches 1024 KB, the file is renamed /tmp/logs/msg__amjrte_verbose.log2 and logging continues with a new /tmp/logs/msg__amjrte_verbose.log1 log file. A maximum of four message log files is used.

(The procedure would be the same on a Windows operating system. The file name just needs to be changed to reflect a fully qualified file name on Windows operating systems.)

Parent topic: Configuring message events with the Java properties file

Console handler and console message loggingConsole handler and console message loggingConsole handler and console message loggingA console handler and a message console handler also are configured in the $JAVA_HOME/PolicyDirector/PDJLog.properties file. Both are disabled by default. properties filesmessagingconsole message loggersproperties filesmessagingconsole handlersmessagesproperties filesconsole message loggersmessagesproperties filesconsole handlersconsole handlershandlersconsoleconsole message loggersloggersconsole messageTo send messages to the console, set both isLogging properties to true: baseGroup.PDJConsoleHandler.isLogging=true baseGroup.PDJMessageConsoleHandler.isLogging=trueConfiguring message events with the Java properties fileTo capture message events for Java applications, you need to configure the Java properties file.

Console handler and console message logging

A console handler and a message console handler also are configured in the $JAVA_HOME/PolicyDirector/PDJLog.properties file. Both are disabled by default.

To send messages to the console, set both isLogging properties to true:

baseGroup.PDJConsoleHandler.isLogging=true
baseGroup.PDJMessageConsoleHandler.isLogging=true

Parent topic: Configuring message events with the Java properties file

Configuring trace events with the Java properties fileConfiguring trace events with the Java properties fileConfiguring trace events with the Java properties fileTo capture trace events for Java applications, you need to configure the Java properties file.Java properties filesJava properties files are ASCII files that are used to customize event logs for Java based Security Access Manager servers, daemons, and other Java-language programs and applications. Beyond customizing logs, these properties files are used to configure other aspects of the application.Trace loggers and file handlersEach properties file contains properties for one or more trace loggers. The isLogging property specifies whether trace logs are enabled. Enabling trace in a Runtime for Java environmentTrace logging for components that use the Security Access Manager Runtime for Java environment is controlled through the application-specific properties file or, for applications that are not explicitly configured with the com.tivoli.pd.jcfg.SvrSslCfg command, the $JAVA_HOME/PolicyDirector/PDJLog.properties file.

Configuring trace events with the Java properties file

To capture trace events for Java™ applications, you need to configure the Java properties file.

Trace loggers and file handlers
Each properties file contains properties for one or more trace loggers. The isLogging property specifies whether trace logs are enabled.

Enabling trace in a Runtime for Java environment
Trace logging for components that use the Security Access Manager Runtime for Java environment is controlled through the application-specific properties file or, for applications that are not explicitly configured with the com.tivoli.pd.jcfg.SvrSslCfg command, the $JAVA_HOME/PolicyDirector/PDJLog.properties file.

Parent topic: Java properties files

Trace loggers and file handlersTrace loggers and file handlersTrace loggers and file handlersEach properties file contains properties for one or more trace loggers. The isLogging property specifies whether trace logs are enabled. traceproperties filesloggersproperties filestracesloggersloggerstraceisLogging propertytracesTo turn on tracing for a specific trace logger, use: baseGroup.trace_logger_name.isLogging=trueTo disable logging for a specific trace logger, use: baseGroup.PDJapp_nameTraceLogger.isLogging=falseAssociated with each trace logger is at least one file handler. A file handler specifies the destination for a specific class, or severity, of messages. After trace logs are enabled by the trace logger, the file handler properties are examined to determine whether to log traces, and if so, how and where. The properties for a file handler are: baseGroup.PDJapp_nameTraceFileHandler.fileName= baseGroup.PDJapp_nameTraceFileHandler.maxFileSize= baseGroup.PDJapp_nameTraceFileHandler.maxFiles=where: fileNameSpecifies the fully qualified file name to be used as the base name for trace log files. The file can be in any location accessible by the Java application.maxFileSizeSpecifies the maximum size, in KB, of each trace log file. Default is 512.maxFilesSpecifies the maximum number of files to be used for trace logs. Default is 3.Configuring trace events with the Java properties fileTo capture trace events for Java applications, you need to configure the Java properties file.

Trace loggers and file handlers

Each properties file contains properties for one or more trace loggers. The isLogging property specifies whether trace logs are enabled.

To turn on tracing for a specific trace logger, use:

baseGroup.trace_logger_name.isLogging=true

To disable logging for a specific trace logger, use:

baseGroup.PDJapp_nameTraceLogger.isLogging=false

Associated with each trace logger is at least one file handler. A file handler specifies the destination for a specific class, or severity, of messages. After trace logs are enabled by the trace logger, the file handler properties are examined to determine whether to log traces, and if so, how and where. The properties for a file handler are:

baseGroup.PDJapp_nameTraceFileHandler.fileName=
baseGroup.PDJapp_nameTraceFileHandler.maxFileSize=
baseGroup.PDJapp_nameTraceFileHandler.maxFiles=

where:

fileName

Specifies the fully qualified file name to be used as the base name for trace log files. The file can be in any location accessible by the Java™ application.

maxFileSize

Specifies the maximum size, in KB, of each trace log file. Default is 512.

maxFiles

Specifies the maximum number of files to be used for trace logs. Default is 3.

Parent topic: Configuring trace events with the Java properties file

Enabling trace in a Runtime for Java environmentEnabling trace in a Runtime for Java environmentEnabling trace in a Runtime for Java environmentTrace logging for components that use the Security Access Manager Runtime for Java environment is controlled through the application-specific properties file or, for applications that are not explicitly configured with the com.tivoli.pd.jcfg.SvrSslCfg command, the $JAVA_HOME/PolicyDirector/PDJLog.properties file.runtime for Javaenable traceTo enable tracing: baseGroup.PDJapp_nameTraceLogger.isLogging=trueFor each trace logger, the properties file defines a mask attribute, baseGroup.PDJapp_nameTraceAllMaskFilter.mask, that determines what levels of tracing are enabled. Valid mask values are 1 through 9. The precise meaning of any specified mask value is unimportant. The general intention is that ascending from a lower mask value to a higher mask value (for example, 1 to 2) increases the level of information detail that is traced.Setting the mask value to a particular level means that all tracing levels up to and including the specified level are enabled. For example, if the mask value is 4, then tracing levels 1, 2, 3, and 4 are traced.Configuring trace events with the Java properties fileTo capture trace events for Java applications, you need to configure the Java properties file.

Enabling trace in a Runtime for Java environment

Trace logging for components that use the Security Access Manager Runtime for Java™ environment is controlled through the application-specific properties file or, for applications that are not explicitly configured with the com.tivoli.pd.jcfg.SvrSslCfg command, the $JAVA_HOME/PolicyDirector/PDJLog.properties file.

To enable tracing:

baseGroup.PDJapp_nameTraceLogger.isLogging=true

For each trace logger, the properties file defines a mask attribute, baseGroup.PDJapp_nameTraceAllMaskFilter.mask, that determines what levels of tracing are enabled. Valid mask values are 1 through 9. The precise meaning of any specified mask value is unimportant. The general intention is that ascending from a lower mask value to a higher mask value (for example, 1 to 2) increases the level of information detail that is traced.

Setting the mask value to a particular level means that all tracing levels up to and including the specified level are enabled. For example, if the mask value is 4, then tracing levels 1, 2, 3, and 4 are traced.

Parent topic: Configuring trace events with the Java properties file

Message event loggingMessage event loggingMessage event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. eventslogsmessageslogsoverviewYou can use log files to capture any Security Access Manager message.Message logging for the C-language portions of Security Access Manager is controlled through routing files. Message logging for the Java language portions is controlled through Java properties files. When relevant, the distinctions between these methods are mentioned.Use the statements within routing files to control which messages to log, the location of the log files, and format of the messages. Use the information in this chapter to learn the configuration syntax that is used in the routing files and defines the default file name and location of the message log files. The directory location for message log files can be different, depending on whether Tivoli Common Directory is configured.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Severity of message eventsIn the message log file, each message event has an associated severity level. Names of message logsThe names of the message log files depend on whether the log is for the Runtime component or a server component. Format of messages in logsMessages in logs are recorded in a specific format.Environment variablesThe message log behavior that is specified by a routing file can be changed by using environment variables. Routing files for message eventsLogging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log. Message routing filesTo understand how default message logs work, review several of the default routing files.Limiting the size of message logsBy default, message logs grow without limit. Limiting message log size requires that the directories and file systems that contain message log files must be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.Estimating the size of message logsEach entry in a message log file with a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size. The maximum size of any log file is 2 GB. Logging all messages the same wayYou can log messages to a single file.Changing the message format in log filesYou can change the message format for a server-specific message log file.Sending messages to multiple places in different formatsYou can send messages to multiple locations with different message formats.

Message event logging

The contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers.

You can use log files to capture any Security Access Manager message.

Message logging for the C-language portions of Security Access Manager is controlled through routing files.

Message logging for the Java™ language portions is controlled through Java properties files.

When relevant, the distinctions between these methods are mentioned.

Use the statements within routing files to control which messages to log, the location of the log files, and format of the messages. Use the information in this chapter to learn the configuration syntax that is used in the routing files and defines the default file name and location of the message log files. The directory location for message log files can be different, depending on whether Tivoli Common Directory is configured.

Severity of message events
In the message log file, each message event has an associated severity level.

Names of message logs
The names of the message log files depend on whether the log is for the Runtime component or a server component.

Format of messages in logs
Messages in logs are recorded in a specific format.

Environment variables
The message log behavior that is specified by a routing file can be changed by using environment variables.

Routing files for message events
Logging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log.

Message routing files
To understand how default message logs work, review several of the default routing files.

Limiting the size of message logs
By default, message logs grow without limit. Limiting message log size requires that the directories and file systems that contain message log files must be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.

Estimating the size of message logs
Each entry in a message log file with a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size. The maximum size of any log file is 2 GB.

Logging all messages the same way
You can log messages to a single file.

Changing the message format in log files
You can change the message format for a server-specific message log file.

Sending messages to multiple places in different formats
You can send messages to multiple locations with different message formats.

Parent topic: Troubleshooting

Severity of message eventsSeverity of message eventsSeverity of message eventsIn the message log file, each message event has an associated severity level. messagesseverity levelseverity, messagesThe following message severities are valid: FATALERRORWARNINGNOTICENOTICE_VERBOSEMessage event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. FATAL messagesAn unrecoverable error occurred, such as a database corruption. The process that encounters the error usually terminates and might produce a core file. ERROR messagesAn unexpected or nonterminal event, such as a timeout, or correctable event that requires manually intervention occurred. WARNING messagesAn event occurred that is possibly not the wanted or requested result, such as a configuration file not being found and a default value used instead. NOTICE messagesAn event took place that does not directly require action, such as starting a server. The event conveys general information about running state or normal actions.NOTICE_VERBOSE messagesThis event is similar to NOTICE, but the events that are logged might contain more detailed information.

Severity of message events

In the message log file, each message event has an associated severity level.

The following message severities are valid:

FATAL

ERROR

WARNING

NOTICE

NOTICE_VERBOSE

FATAL messages
An unrecoverable error occurred, such as a database corruption. The process that encounters the error usually terminates and might produce a core file.

ERROR messages
An unexpected or nonterminal event, such as a timeout, or correctable event that requires manually intervention occurred.

WARNING messages
An event occurred that is possibly not the wanted or requested result, such as a configuration file not being found and a default value used instead.

NOTICE messages
An event took place that does not directly require action, such as starting a server. The event conveys general information about running state or normal actions.

NOTICE_VERBOSE messages
This event is similar to NOTICE, but the events that are logged might contain more detailed information.

Parent topic: Message event logging

FATAL messagesFATAL messagesFATAL messagesAn unrecoverable error occurred, such as a database corruption. The process that encounters the error usually terminates and might produce a core file. FATAL severity, messagesThis error might require manual intervention to recover or require special recovery actions. Depending on the nature of the failure, IBM Software Support might need to be consulted.The identifier for these messages uses the error (E) message severity.Severity of message eventsIn the message log file, each message event has an associated severity level.

FATAL messages

An unrecoverable error occurred, such as a database corruption. The process that encounters the error usually terminates and might produce a core file.

This error might require manual intervention to recover or require special recovery actions. Depending on the nature of the failure, IBM® Software Support might need to be consulted.

The identifier for these messages uses the error (E) message severity.

Parent topic: Severity of message events

ERROR messagesERROR messagesERROR messagesAn unexpected or nonterminal event, such as a timeout, or correctable event that requires manually intervention occurred. error severity, messagesThe product continues to function, but some services or functions might not be available. This severity also indicates that a particular request or action was not completed. Administrative action might be required.The identifier for these messages uses the error (E) message severity.Severity of message eventsIn the message log file, each message event has an associated severity level.

ERROR messages

An unexpected or nonterminal event, such as a timeout, or correctable event that requires manually intervention occurred.

The product continues to function, but some services or functions might not be available. This severity also indicates that a particular request or action was not completed. Administrative action might be required.

The identifier for these messages uses the error (E) message severity.

Parent topic: Severity of message events

WARNING messagesWARNING messagesWARNING messagesAn event occurred that is possibly not the wanted or requested result, such as a configuration file not being found and a default value used instead. WARNING severity, messagesThe program continues to function normally. This severity also indicates a condition that might be an error if the effects are unwanted or indicates a condition, which if not corrected, can result in an error. For example, a low memory or disk space condition.The identifier for these messages uses the warning (W) message severity.Severity of message eventsIn the message log file, each message event has an associated severity level.

WARNING messages

An event occurred that is possibly not the wanted or requested result, such as a configuration file not being found and a default value used instead.

The program continues to function normally. This severity also indicates a condition that might be an error if the effects are unwanted or indicates a condition, which if not corrected, can result in an error. For example, a low memory or disk space condition.

The identifier for these messages uses the warning (W) message severity.

Parent topic: Severity of message events

NOTICE messagesNOTICE messagesNOTICE messagesAn event took place that does not directly require action, such as starting a server. The event conveys general information about running state or normal actions.NOTICE severity, messagesThe identifier for these messages uses the information (I) message severity.Severity of message eventsIn the message log file, each message event has an associated severity level.

NOTICE messages

An event took place that does not directly require action, such as starting a server. The event conveys general information about running state or normal actions.

The identifier for these messages uses the information (I) message severity.

Parent topic: Severity of message events

NOTICE_VERBOSE messagesNOTICE_VERBOSE messagesNOTICE_VERBOSE messagesThis event is similar to NOTICE, but the events that are logged might contain more detailed information.NOTICE_VERBOSE severity, messagesThe identifier for these messages uses the information (I) message severity.Severity of message eventsIn the message log file, each message event has an associated severity level.

NOTICE_VERBOSE messages

This event is similar to NOTICE, but the events that are logged might contain more detailed information.

The identifier for these messages uses the information (I) message severity.

Parent topic: Severity of message events

Names of message logsNames of message logsNames of message logsThe names of the message log files depend on whether the log is for the Runtime component or a server component. The messages for the Runtime component are separated into severity-specific files, while the messages for the server components are written to the same file.Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. Names of runtime logsIBM Security Access Manager runtime messages are messages that are produced by applications, commands, and utilities that use the Security Access Manager Runtime component. The sources include the C language-based utilities, such as the pdadmin commands and the svrsslcfg utility.Names of server logsServer messages are messages that are generated by the daemons and servers that are associated with Security Access Manager.

Names of message logs

The names of the message log files depend on whether the log is for the Runtime component or a server component.

The messages for the Runtime component are separated into severity-specific files, while the messages for the server components are written to the same file.

Names of runtime logs
IBM Security Access Manager runtime messages are messages that are produced by applications, commands, and utilities that use the Security Access Manager Runtime component. The sources include the C language-based utilities, such as the pdadmin commands and the svrsslcfg utility.

Names of server logs
Server messages are messages that are generated by the daemons and servers that are associated with Security Access Manager.

Parent topic: Message event logging

Names of runtime logsNames of runtime logsNames of runtime logsIBM Security Access Manager runtime messages are messages that are produced by applications, commands, and utilities that use the Security Access Manager Runtime component. The sources include the C language-based utilities, such as the pdadmin commands and the svrsslcfg utility.runtimemessage logsmessageslogsruntime filesmsg__fatal.log filemsg__error.log filemsg__warning.log filemsg__notice.log filemsg__verbose.log filemsg__<app_nameN>.log filemsg__verbose_<pid>.log filefilesmsg__fatal.logfilesmsg__error.logfilesmsg__warning.logfilesmsg__notice.logfilesmsg__verbose.logfilesmsg__<app_nameN>.logfilesmsg__verbose_<pid>.loglog filesmsg__fatal.loglog filesmsg__error.loglog filesmsg__warning.loglog filesmsg__notice.loglog filesmsg__verbose.loglog filesmsg__<app_nameN>.loglog filesmsg__verbose_<pid>.logTable 1 lists the names of the default message log files for both C and Java language applications.Message severity levels and associated message logsMessage severityDefault log nameFATALC runtime log namemsg__fatal.logJava runtime log namemsg__app_nameN.logWebSEAL log nameWritten to the standard error file (STDERR)ERRORC runtime log namemsg__error.logJava runtime log namemsg__app_nameN.logWebSEAL log nameWritten to the standard error file (STDERR)WARNINGC runtime log namemsg__warning.logJava runtime log namemsg__app_nameN.logWebSEAL log nameWritten to the standard error file (STDERR)NOTICEC runtime log namemsg__notice.logJava runtime log namemsg__app_nameN.logWebSEAL log namemsg__notice_PID.log Logging is not enabled by default.NOTICE_VERBOSEC runtime log namemsg__verbose.log Logging is not enabled by default.Java runtime log namemsg__app_nameN.logWebSEAL log namemsg__verbose_PID.log Logging is not enabled by default. When WebSEAL is running as a background process, FATAL, ERROR, and WARNING messages are redirected to the server message log file for that WebSEAL instance (msg__webseald–instance_name.log).If an application-specific configuration file does not exist for a Java application, message logs are controlled by the $JAVA_HOME/PolicyDirector/PDJLog.properties file. In these cases, messages are written to the following files: FATALmsg__amj_fatalN.logERRORmsg__amj_errorN.logWARNINGmsg__amj_warningN.logNOTICEmsg__amj_noticeN.logNOTICE_VERBOSEmsg__amj_verboseN.log By default, logging of NOTICE and NOTICE_VERBOSE messages is not enabled.Based on the severity level, runtime messages from C-language applications are written to different log files. For example, WARNING messages are written to the msg__warning.log file and FATAL messages are written to msg__fatal.log file. Error messages from WebSEAL are written to STDERR, unless WebSEAL is running in the background. In this case, the messages are written to the WebSEAL server log file.Runtime message log files that are associated with C-language applications are allowed to grow without bound. Periodically check the available disk space and adjust as necessary, perhaps by archiving or pruning the log files. You can change the name, location, and put size constraints on the runtime message log files, as explained in Routing file entriesEach routing file contains entries that control the logging of message events and trace events. However, the format of these entries differs by event type. .Runtime message log files for Java language applications can grow to a maximum size of 512 KB. A maximum of three message files can exist, with the most recent messages always being in the file that ends in 1. When the file reaches its maximum size, the files are renamed. For example, when the msg__appname1.log file reaches 512 KB, the following process occurs: The msg__appname3.log file is deleted, if it existsThe msg__appname2.log file, if it exists, is renamed to msg__appname3.logThe msg__appname1.log file is renamed msg__appname2.logA new msg__appname1.log file is createdThe names, location, number, and size of the Java runtime logs can be changed, as explained in Table 1.Names of message logsThe names of the message log files depend on whether the log is for the Runtime component or a server component.

Names of runtime logs

IBM Security Access Manager runtime messages are messages that are produced by applications, commands, and utilities that use the Security Access Manager Runtime component. The sources include the C language-based utilities, such as the pdadmin commands and the svrsslcfg utility.

Table 287 lists the names of the default message log files for both C and Java™ language applications.

Table 287. Message severity levels and associated message logs

Message severity
Default log name

FATAL

C runtime log name

msg__fatal.log

Java runtime log name

msg__app_nameN.log

WebSEAL log name

Written to the standard error file (STDERR)

ERROR

C runtime log name

msg__error.log

Java runtime log name

msg__app_nameN.log

WebSEAL log name

Written to the standard error file (STDERR)

WARNING

C runtime log name

msg__warning.log

Java runtime log name

msg__app_nameN.log

WebSEAL log name

Written to the standard error file (STDERR)

NOTICE

C runtime log name

msg__notice.log

Java runtime log name

msg__app_nameN.log

WebSEAL log name

msg__notice_PID.log

Note: Logging is not enabled by default.

NOTICE_VERBOSE

C runtime log name

msg__verbose.log

Note: Logging is not enabled by default.

Java runtime log name

msg__app_nameN.log

WebSEAL log name

msg__verbose_PID.log

Note: Logging is not enabled by default.

Notes:

When WebSEAL is running as a background process, FATAL, ERROR, and WARNING messages are redirected to the server message log file for that WebSEAL instance (msg__webseald–instance_name.log).

If an application-specific configuration file does not exist for a Java application, message logs are controlled by the $JAVA_HOME/PolicyDirector/PDJLog.properties file. In these cases, messages are written to the following files:

FATAL

msg__amj_fatalN.log

ERROR

msg__amj_errorN.log

WARNING

msg__amj_warningN.log

NOTICE

msg__amj_noticeN.log

NOTICE_VERBOSE

msg__amj_verboseN.log

Note: By default, logging of NOTICE and NOTICE_VERBOSE messages is not enabled.

Based on the severity level, runtime messages from C-language applications are written to different log files. For example, WARNING messages are written to the msg__warning.log file and FATAL messages are written to msg__fatal.log file. Error messages from WebSEAL are written to STDERR, unless WebSEAL is running in the background. In this case, the messages are written to the WebSEAL server log file.

Runtime message log files that are associated with C-language applications are allowed to grow without bound. Periodically check the available disk space and adjust as necessary, perhaps by archiving or pruning the log files. You can change the name, location, and put size constraints on the runtime message log files, as explained in Routing file entries.

Runtime message log files for Java language applications can grow to a maximum size of 512 KB. A maximum of three message files can exist, with the most recent messages always being in the file that ends in "1". When the file reaches its maximum size, the files are renamed. For example, when the msg__appname1.log file reaches 512 KB, the following process occurs:

The msg__appname3.log file is deleted, if it exists

The msg__appname2.log file, if it exists, is renamed to msg__appname3.log

The msg__appname1.log file is renamed msg__appname2.log

A new msg__appname1.log file is created

The names, location, number, and size of the Java runtime logs can be changed, as explained in Table 286.

Parent topic: Names of message logs

Names of server logsNames of server logsNames of server logsServer messages are messages that are generated by the daemons and servers that are associated with Security Access Manager. servermessage logsmessageslogsserver filespolicy servermsg__pdmgrd_utf8.logpolicy servermessage logsfilepdmgrdserver logmsg__pdmgrd_utf8.log fileauthorization servermsg__pdacld_utf8.logauthorization servermessage log filepdacld server logmsg__pdacld_utf8.log fileWebSEAL servermsg__webseald–<instance>.logWebSEAL servermessage log filewebsealdmsg__webseald–<instance>.log fiel<server_name>.logAttribute Retrieval Servicemsg__amwebars_exceptions.logAttribute Retrieval Servicemessage log filemsg__amwebars_exceptions.log filePlug-in for Web Serversmsg__pdwebpi.logPlug-in for Web Serversmessage log fileWebPImsg__pdwebpi.log filefilesmsg__pdmgrd_utf8.logfilesmsg__pdacld_utf8.logfilesmsg__webseald–<instance>.logfiles<server_name>.logfilesedge.<date> filefilesmsg__amwebars_exceptions.logfilesmsg__pdwebpi.loglog filesmsg__pdmgrd_utf8.loglog filesmsg__pdacld_utf8.loglog filesmsg__webseald–<instance>.loglog files<server_name>.loglog filesmsg__amwebars_exceptions.loglog filesmsg__pdwebpi.logUnlike runtime messages from C applications, which are written to different log files based on severity, server messages are always written to the message log for that particular server. Thus, all FATAL, WARNING, ERROR, NOTICE, and NOTICE_VERBOSE messages for the policy server are written to the msg__pdmgrd_utf8.log file. Similarly, WebSEAL messages are written to the msg__webseald–instance_name.log file.Table 1 lists the default names for the server message log files.Message log files that are associated with serversServerDefault message log fileSecurity Access Manager policy servermsg__pdmgrd_utf8.logSecurity Access Manager authorization servermsg__pdacld_utf8.logSecurity Access Manager WebSEALmsg__webseald–instance_name.logSecurity Access Manager Attribute Retrieval Servicemsg__amwebars_exceptions.logBy default, the Security Access Manager server message log files (the ones that start with msg__) are allowed to grow without bound. Be sure to periodically check the available disk space and adjust as necessary. You might want to archive or prune the log files on a periodic basis as well.You can change the name, location, and put size constraints on the server message log files as explained in Routing file entriesEach routing file contains entries that control the logging of message events and trace events. However, the format of these entries differs by event type. .Names of message logsThe names of the message log files depend on whether the log is for the Runtime component or a server component.

Names of server logs

Server messages are messages that are generated by the daemons and servers that are associated with Security Access Manager.

Unlike runtime messages from C applications, which are written to different log files based on severity, server messages are always written to the message log for that particular server. Thus, all FATAL, WARNING, ERROR, NOTICE, and NOTICE_VERBOSE messages for the policy server are written to the msg__pdmgrd_utf8.log file. Similarly, WebSEAL messages are written to the msg__webseald–instance_name.log file.

Table 288 lists the default names for the server message log files.

Table 288. Message log files that are associated with servers

Server | Default message log file
Security Access Manager policy server | msg__pdmgrd_utf8.log
Security Access Manager authorization server | msg__pdacld_utf8.log
Security Access Manager WebSEAL | msg__webseald–instance_name.log
Security Access Manager Attribute Retrieval Service | msg__amwebars_exceptions.log

By default, the Security Access Manager server message log files (the ones that start with msg__) are allowed to grow without bound. Be sure to periodically check the available disk space and adjust as necessary. You might want to archive or prune the log files on a periodic basis as well.

You can change the name, location, and put size constraints on the server message log files as explained in Routing file entries.

Parent topic: Names of message logs

Format of messages in logsFormat of messages in logsFormat of messages in logsMessages in logs are recorded in a specific format.formatmessage log entryoverviewmessageslogsentry formatlog entry formatmessagesTo configure Security Access Manager message logs and trace logs to produce output in an XML log format, see Sending messages to multiple places in different formatsYou can send messages to multiple locations with different message formats. and Trace logging in XML log formatTo send trace output for the authorization server to a single file in XML log format, the install_dir/etc/msg__pdacld.routing file can be modified as follows: .Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. Messages in text formatThis log entry is a sample of a server message in text format.Messages in XML log format

Format of messages in logs

Messages in logs are recorded in a specific format.

To configure Security Access Manager message logs and trace logs to produce output in an XML log format, see Sending messages to multiple places in different formats and Trace logging in XML log format.

Messages in text format
This log entry is a sample of a server message in text format.

Messages in XML log format

Parent topic: Message event logging

Messages in text formatMessages in text formatMessages in text formatThis log entry is a sample of a server message in text format.formatmessage log entrytextFigure 1 shows an example of a message log entry. Sample message log entry in text format2005-10-26-20:09:10.984-06:00I----- 0x1354A41E pdmgrd ERROR ivc socket e:\am600\src\mts\mtsclient.cpp 1832 0x000001c4 HPDCO1054E Could not connect to the server acld2 on port 7137. The following list explains the log entry fields that are shown in Figure 1: 2005-10-26-20:09:10.984-06:00IIndicates the timestamp of the message entry. The timestamp is in the following format: YYYY–MM–DD–hh:mm:ss.fff[+|–]hh:mmI where: YYYY-MM-DDSpecifies the date in year, month, and day.hh:mm:ss.fffSpecifies the time in hours, minutes, seconds, and fractional seconds.hh:mmISpecifies the time inaccuracy factor.0x1354A41EIndicates the 32-bit message number in hexadecimal.pdmgrdIndicates the name of the process that created the entry.ERRORIndicates the severity of the message.ivcIndicates the component for the process that generated the entry.socketIndicates the subcomponent for the process that generated the entry.e:\am600\src\mts\mtsclient.cppIndicates the name of the source file that generated the entry.1832Indicates the exact line number in the source file.0x000001c4Indicates the 32–bit thread ID in hexadecimal.HPDCO1054EIndicates the message ID.Could not connect to the server acld2 on port 7137.Indicates the message text.Format of messages in logsMessages in logs are recorded in a specific format.

Messages in text format

This log entry is a sample of a server message in text format.

Figure 96. shows an example of a message log entry.

Figure 96. Sample message log entry in text format

2005-10-26-20:09:10.984-06:00I----- 0x1354A41E pdmgrd ERROR
ivc socket e:\am600\src\mts\mtsclient.cpp 1832 0x000001c4
HPDCO1054E  Could not connect to the server acld2 on port 7137.

The following list explains the log entry fields that are shown in Figure 96.:

2005-10-26-20:09:10.984-06:00I

Indicates the timestamp of the message entry. The timestamp is in the following format:

YYYY–MM–DD–hh:mm:ss.fff[+|–]hh:mmI

where:

YYYY-MM-DD

Specifies the date in year, month, and day.

hh:mm:ss.fff

Specifies the time in hours, minutes, seconds, and fractional seconds.

hh:mmI

Specifies the time inaccuracy factor.

0x1354A41E

Indicates the 32-bit message number in hexadecimal.

pdmgrd

Indicates the name of the process that created the entry.

ERROR

Indicates the severity of the message.

ivc

Indicates the component for the process that generated the entry.

socket

Indicates the subcomponent for the process that generated the entry.

e:\am600\src\mts\mtsclient.cpp

Indicates the name of the source file that generated the entry.

1832

Indicates the exact line number in the source file.

0x000001c4

Indicates the 32–bit thread ID in hexadecimal.

HPDCO1054E

Indicates the message ID.

Could not connect to the server acld2 on port 7137.

Indicates the message text.

Parent topic: Format of messages in logs

Messages in XML log formatMessages in XML log formatMessages in XML log formatformatmessage log entryXMLFigure 1 uses the message from Figure 1, but shows the message in the XML log format. Sample message entry in the XML log format<Message Id="HPDCO1054E" Severity="ERROR"> <Time Millis="1067220550984">2005-10-26-20:09:10.984</Time> <Component>ivc/socket</Component> <LogAttribs><KeyName><![CDATA[Message Number]]]</KeyName> <Value><![CDATA[0x1354A41E]]]</Value> </LogAttribs> <Source FileName="e:\am600\src\mts\mtsclient.cpp" Method="unknown" Line="1832"> </Source> <Process>pdmgrd</Process> <Thread>0x000001c4</Thread> <TranslationInfo Type="XPG4" Catalog="pdbivc.cat" SetId="1" MsgKey="1354a41e"> <Param><![CDATA[acld2]]]</Param> <Param><![CDATA[7137]]]</Param> </TranslationInfo> <LogText> <![CDATA[HPDCO1054E Could not connect to the server acld2 on port 7137.]] </LogText> </Message>Format of messages in logsMessages in logs are recorded in a specific format.

Messages in XML log format

Figure 97. uses the message from Figure 96., but shows the message in the XML log format.

Figure 97. Sample message entry in the XML log format

<Message Id="HPDCO1054E" Severity="ERROR">
<Time Millis="1067220550984">2005-10-26-20:09:10.984</Time>
<Component>ivc/socket</Component>
<LogAttribs><KeyName><![CDATA[Message Number]]]</KeyName>
<Value><![CDATA[0x1354A41E]]]</Value>
</LogAttribs>
<Source
FileName="e:\am600\src\mts\mtsclient.cpp"
Method="unknown" Line="1832">
</Source>
<Process>pdmgrd</Process>
<Thread>0x000001c4</Thread>
<TranslationInfo
Type="XPG4" Catalog="pdbivc.cat" SetId="1" MsgKey="1354a41e">
<Param><![CDATA[acld2]]]</Param>
<Param><![CDATA[7137]]]</Param>
</TranslationInfo>
<LogText>
<![CDATA[HPDCO1054E Could not connect to the server acld2 on port 7137.]]
</LogText>
</Message>

Parent topic: Format of messages in logs

Environment variablesEnvironment variablesEnvironment variablesThe message log behavior that is specified by a routing file can be changed by using environment variables. environment variablesSVC_FATALenvironment variablesSVC_ERRORenvironment variablesSVC_WARNINGenvironment variablesSVC_NOTICEenvironment variablesSVC_NOTICE_VERBOSESVC_FATAL environment variableSVC_ERROR environment variableSVC_WARNING environment variableSVC_NOTICE environment variableSVC_NOTICE_VERBOSE environment variableThe PD_SVC_ROUTING_FILE environment variable can specify a fully qualified file name for a routing file to replace the one currently in use. If the file is not accessible, or does not exist, no change in logging messages is made.Routing for messages of a specific severity can be manipulated by using environment variables as well. Set the appropriate message log entry format string to the wanted environment variable: SVC_FATALSVC_ERRORSVC_WARNINGSVC_NOTICESVC_NOTICE_VERBOSEFor example, on Windows operating systems, the following command overrides the setting in the corresponding routing file and directs WARNING messages to the standard error device and a file: SET SVC_WARNING="STDERR:-;FILE:D:\MSGS\MSG__WARNING.LOG"See Routing file entriesEach routing file contains entries that control the logging of message events and trace events. However, the format of these entries differs by event type. for a description of message log entry format strings.Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. Displaying and not displaying environment variables in the logOn the computer on which the Security Access Manager server is running, you can configure environment variables to display or not display in the server log.

Environment variables

The message log behavior that is specified by a routing file can be changed by using environment variables.

The PD_SVC_ROUTING_FILE environment variable can specify a fully qualified file name for a routing file to replace the one currently in use. If the file is not accessible, or does not exist, no change in logging messages is made.

Routing for messages of a specific severity can be manipulated by using environment variables as well. Set the appropriate message log entry format string to the wanted environment variable:

SVC_FATAL

SVC_ERROR

SVC_WARNING

SVC_NOTICE

SVC_NOTICE_VERBOSE

For example, on Windows operating systems, the following command overrides the setting in the corresponding routing file and directs WARNING messages to the standard error device and a file:

SET SVC_WARNING="STDERR:-;FILE:D:\MSGS\MSG__WARNING.LOG"

See Routing file entries for a description of message log entry format strings.

Displaying and not displaying environment variables in the log
On the computer on which the Security Access Manager server is running, you can configure environment variables to display or not display in the server log.

Parent topic: Message event logging

Displaying and not displaying environment variables in the logDisplaying and not displaying environment variables in the logDisplaying and not displaying environment variables in the logOn the computer on which the Security Access Manager server is running, you can configure environment variables to display or not display in the server log. Use the PD_SVC_DISPLAY_ENV_VARS or PD_SVC_DONT_DISPLAY_ENV_VARS environment variable to display or not display environment variables as required. Separate the environment variable keys by the "|" character.PD_SVC_DISPLAY_ENV_VARSDisplays only the specified environment variables. The following example shows how to set this environment variable on an AIX, Linux, or Solaris system: export PD_SVC_DISPLAY_ENV_VARS="PATH|HOME|PWD"The log displays only the PATH, HOME, and PWD environment variables display when the Security Access Manager server starts.PD_SVC_DONT_DISPLAY_ENV_VARSDisplays all available environment variables except the specified environment variables. The following example shows how to use this environment variable on an AIX, Linux, or Solaris system: export PD_SVC_DONT_DISPLAY_ENV_VARS="LANG|PATH|PWD" The log displays all environment variables except LANG, PATH, and PWD when the Security Access Manager server starts.Notes: The PD_SVC_DISPLAY_ENV_VARS option takes precedence over the PD_SVC_DONT_DISPLAY_ENV_VARS option.If the value of one of the specified environment variables keys does not exist, Security Access Manager ignores that key.Environment variablesThe message log behavior that is specified by a routing file can be changed by using environment variables.

Displaying and not displaying environment variables in the log

On the computer on which the Security Access Manager server is running, you can configure environment variables to display or not display in the server log.

Use the PD_SVC_DISPLAY_ENV_VARS or PD_SVC_DONT_DISPLAY_ENV_VARS environment variable to display or not display environment variables as required. Separate the environment variable keys by the "|" character.

PD_SVC_DISPLAY_ENV_VARS

Displays only the specified environment variables.

The following example shows how to set this environment variable on an AIX®, Linux, or Solaris system:

export PD_SVC_DISPLAY_ENV_VARS="PATH|HOME|PWD"

The log displays only the PATH, HOME, and PWD environment variables display when the Security Access Manager server starts.

PD_SVC_DONT_DISPLAY_ENV_VARS

Displays all available environment variables except the specified environment variables.

The following example shows how to use this environment variable on an AIX, Linux, or Solaris system:

export PD_SVC_DONT_DISPLAY_ENV_VARS="LANG|PATH|PWD"

The log displays all environment variables except LANG, PATH, and PWD when the Security Access Manager server starts.

Notes:

The PD_SVC_DISPLAY_ENV_VARS option takes precedence over the PD_SVC_DONT_DISPLAY_ENV_VARS option.

If the value of one of the specified environment variables keys does not exist, Security Access Manager ignores that key.

Parent topic: Environment variables

Routing files for message eventsRouting files for message eventsRouting files for message eventsLogging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log. The server configuration files pick up the information from the routing files. If for any reason a routing file is deleted, the log-file stanza entry for the appropriate server is used instead.Within routing files, you can disable or enable any type of message logs by adding or removing the comment character (#) at the beginning of the line in the routing file.Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. C runtime routing filePolicy server pdmgrd_routing fileAuthorization server pdacld_routing fileWebSEAL routing fileBy default WebSEAL writes all messages to the standard error device.

Routing files for message events

Logging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log.

The server configuration files pick up the information from the routing files. If for any reason a routing file is deleted, the log-file stanza entry for the appropriate server is used instead.

Within routing files, you can disable or enable any type of message logs by adding or removing the comment character (#) at the beginning of the line in the routing file.

C runtime routing file

Policy server pdmgrd_routing file

Authorization server pdacld_routing file

WebSEAL routing file
By default WebSEAL writes all messages to the standard error device.

Parent topic: Message event logging

C runtime routing fileC runtime routing fileC runtime routing fileC runtimemessage logsC runtimerouting filelog filesC runtimemsg__fatal.loglog filesC runtimemsg__error.loglog filesC runtimemsg__warninglog filesC runtimemsg__notice.loglog filesC runtimemsg__verbosemsg__fatal.log filemsg__error.log filemsg__warning filemsg__notice.log filemsg__verbose fileRouting files for message eventsLogging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log. AIX, Linux, or Solaris: default routing fileWindows: default routing file

C runtime routing file

AIX, Linux, or Solaris: default routing file

Windows: default routing file

Parent topic: Routing files for message events

AIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing filerouting filesFATAL:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log :644:ivmgr:ivmgr ERROR:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log :644:ivmgr:ivmgr WARNING:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log :644:ivmgr:ivmgr NOTICE:FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log :644:ivmgr:ivmgr #NOTICE_VERBOSE:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__verbose.log :644:ivmgr:ivmgrC runtime routing file

AIX, Linux, or Solaris: default routing file

FATAL:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log
:644:ivmgr:ivmgr
ERROR:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log
:644:ivmgr:ivmgr
WARNING:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log
:644:ivmgr:ivmgr
NOTICE:FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log
:644:ivmgr:ivmgr
#NOTICE_VERBOSE:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__verbose.log
:644:ivmgr:ivmgr

Parent topic: C runtime routing file

Windows: default routing fileWindows: default routing fileWindows: default routing fileFATAL:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log ERROR:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log WARNING:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log NOTICE:FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log #NOTICE_VERBOSE:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__verbose.logC runtime routing file

Windows: default routing file

FATAL:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log
ERROR:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log
WARNING:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log
NOTICE:FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log
#NOTICE_VERBOSE:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__verbose.log

Parent topic: C runtime routing file

Policy server pdmgrd_routing filePolicy server pdmgrd_routing filePolicy server pdmgrd_routing filepolicy servermessage logspolicy serverrouting filelog filespolicy servermsg__pdmgrd_utf8.log fileRouting files for message eventsLogging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log. AIX, Linux, or Solaris: default routing fileWindows: default routing file

Policy server pdmgrd_routing file

AIX, Linux, or Solaris: default routing file

Windows: default routing file

Parent topic: Routing files for message events

AIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing fileFATAL:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log :644:ivmgr:ivmgr ERROR:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log :644:ivmgr:ivmgr WARNING:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log :644:ivmgr:ivmgr NOTICE:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log :644:ivmgr:ivmgr #NOTICE_VERBOSE:STDOUT:-;UTF8FILE:/pd_install_dir/log/ msg__pdmgrd_utf8.log:644:ivmgr:ivmgrwhere pd_install_dir is either /var/PolicyDirector or the Tivoli Common Directory location.Policy server pdmgrd_routing file

AIX®, Linux, or Solaris: default routing file

FATAL:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log
:644:ivmgr:ivmgr
ERROR:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log
:644:ivmgr:ivmgr
WARNING:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log
:644:ivmgr:ivmgr
NOTICE:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdmgrd_utf8.log
:644:ivmgr:ivmgr
#NOTICE_VERBOSE:STDOUT:-;UTF8FILE:/pd_install_dir/log/
msg__pdmgrd_utf8.log:644:ivmgr:ivmgr

where pd_install_dir is either /var/PolicyDirector or the Tivoli Common Directory location.

Parent topic: Policy server pdmgrd_routing file

Windows: default routing fileWindows: default routing fileWindows: default routing fileFATAL:STDERR:-;FILE:pd_install_dir\log\msg__pdmgrd_utf8.log ERROR:STDERR:-;FILE:pd_install_dir\log\msg__pdmgrd_utf8.log WARNING:STDERR:-;FILE:pd_install_dir\mog\msg__pdmgrd_utf8.log NOTICE:FILE:pd_install_dir\log\msg__pdmgrd_utf8.log #NOTICE_VERBOSE:STDOUT:-;UTF8FILE:pd_install_dir\log\ msg__pdmgrd_utf8.logwhere pd_install_dir is either the directory where Security Access Manager is installed or the Tivoli Common Directory.Policy server pdmgrd_routing file

Windows: default routing file

FATAL:STDERR:-;FILE:pd_install_dir\log\msg__pdmgrd_utf8.log
ERROR:STDERR:-;FILE:pd_install_dir\log\msg__pdmgrd_utf8.log
WARNING:STDERR:-;FILE:pd_install_dir\mog\msg__pdmgrd_utf8.log
NOTICE:FILE:pd_install_dir\log\msg__pdmgrd_utf8.log
#NOTICE_VERBOSE:STDOUT:-;UTF8FILE:pd_install_dir\log\
msg__pdmgrd_utf8.log

where pd_install_dir is either the directory where Security Access Manager is installed or the Tivoli Common Directory.

Parent topic: Policy server pdmgrd_routing file

Authorization server pdacld_routing fileAuthorization server pdacld_routing fileAuthorization server pdacld_routing fileauthorization servermessage logsauthorization serverrouting filelog filesauthorization servermsg__pdacld_utf8.logmsg__pdacld_utf8.log fileRouting files for message eventsLogging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log. AIX, Linux, or Solaris: default routing fileWindows: default routing file

Authorization server pdacld_routing file

AIX, Linux, or Solaris: default routing file

Windows: default routing file

Parent topic: Routing files for message events

AIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing fileFATAL:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log :644:ivmgr:ivmgr ERROR:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log :644:ivmgr:ivmgr WARNING:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log :644:ivmgr:ivmgr NOTICE:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log :644:ivmgr:ivmgr #NOTICE_VERBOSE:STDOUT:-;UTF8FILE:/pd_install_dir/log/ msg__pdacld_utf8.log:644:ivmgr:ivmgrwhere pd_install_dir is either /var/PolicyDirector or the Tivoli Common Directory location.A log file name such as msg__pdacld_utf8.log applies to a default instance of the authorization server. If multiple instances of the authorization server exist, each log file contains the specified instance name. For example, if an authorization server instance name is instance1, the log file is called msg__instance1-pdacld_utf8.log.Authorization server pdacld_routing file

AIX®, Linux, or Solaris: default routing file

FATAL:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log
:644:ivmgr:ivmgr
ERROR:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log
:644:ivmgr:ivmgr
WARNING:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log
:644:ivmgr:ivmgr
NOTICE:STDOUT:-;UTF8FILE:/pd_install_dir/log/msg__pdacld_utf8.log
:644:ivmgr:ivmgr
#NOTICE_VERBOSE:STDOUT:-;UTF8FILE:/pd_install_dir/log/
msg__pdacld_utf8.log:644:ivmgr:ivmgr

where pd_install_dir is either /var/PolicyDirector or the Tivoli Common Directory location.

Note: A log file name such as msg__pdacld_utf8.log applies to a default instance of the authorization server. If multiple instances of the authorization server exist, each log file contains the specified instance name. For example, if an authorization server instance name is instance1, the log file is called msg__instance1-pdacld_utf8.log.

Parent topic: Authorization server pdacld_routing file

Windows: default routing fileWindows: default routing fileWindows: default routing fileWindowsdefault routing fileFATAL:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log ERROR:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log WARNING:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log NOTICE:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log #NOTICE_VERBOSE:STDOUT:-;UTF8FILE:pd_install_dir\log\ msg__pdacld_utf8.logwhere pd_install_dir is either the directory where Security Access Manager is installed or the Tivoli Common Directory.A log file name such as msg__pdacld_utf8.log applies to a default instance of the authorization server. If multiple instances of the authorization server exist, each log file contains the specified instance name. For example, if an authorization server instance name is instance1, the log file is called msg__instance1-pdacld_utf8.log.Authorization server pdacld_routing file

Windows: default routing file

FATAL:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log
ERROR:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log
WARNING:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log
NOTICE:STDOUT:-;UTF8FILE:pd_install_dir\log\msg__pdacld_utf8.log
#NOTICE_VERBOSE:STDOUT:-;UTF8FILE:pd_install_dir\log\
msg__pdacld_utf8.log

where pd_install_dir is either the directory where Security Access Manager is installed or the Tivoli Common Directory.

Note: A log file name such as msg__pdacld_utf8.log applies to a default instance of the authorization server. If multiple instances of the authorization server exist, each log file contains the specified instance name. For example, if an authorization server instance name is instance1, the log file is called msg__instance1-pdacld_utf8.log.

Parent topic: Authorization server pdacld_routing file

WebSEAL routing fileWebSEAL routing fileWebSEAL routing fileBy default WebSEAL writes all messages to the standard error device. WebSEALmessage logsWebSEALrouting filelog filesWebSEALmsg__notice_%ld.log filelog filesWebSEALmsg__verbose_%ld.log filelog filesWebSEALmsg__webseald-<instance>.logmsg__notice_%ld.log filemsg__verbose_%ld.log filemsg__webseald-<instance>.logWhen WebSEAL is running in the background, standard error is redirected to the msg__webseald-instance_name.log file.Routing files for message eventsLogging of message events is controlled by a routing file. Entries in the routing file for a server determine which message events to log. AIX, Linux, or Solaris: default routing fileWindows: default routing file

WebSEAL routing file

By default WebSEAL writes all messages to the standard error device.

When WebSEAL is running in the background, standard error is redirected to the msg__webseald-instance_name.log file.

AIX, Linux, or Solaris: default routing file

Windows: default routing file

Parent topic: Routing files for message events

AIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing fileAIX, Linux, or Solaris: default routing fileFATAL:STDERR:- ERROR:STDERR:- WARNING:STDERR:- #NOTICE:FILE.10.100:pdweb_install_dir/log/msg__notice_%ld.log :644:ivmgr:ivmgr #NOTICE_VERBOSE:FILE.10.100:pdweb_install_dir/log/msg__verbose_%ld.log :644:ivmgr:ivmgrwhere pdweb_install_dir is either /var/pdweb or the Tivoli Common Directory location.WebSEAL routing fileBy default WebSEAL writes all messages to the standard error device.

AIX, Linux, or Solaris: default routing file

FATAL:STDERR:-
ERROR:STDERR:-
WARNING:STDERR:-
#NOTICE:FILE.10.100:pdweb_install_dir/log/msg__notice_%ld.log
:644:ivmgr:ivmgr
#NOTICE_VERBOSE:FILE.10.100:pdweb_install_dir/log/msg__verbose_%ld.log
:644:ivmgr:ivmgr

where pdweb_install_dir is either /var/pdweb or the Tivoli Common Directory location.

Parent topic: WebSEAL routing file

Windows: default routing fileWindows: default routing fileWindows: default routing fileenvironment variablesPD_WEBPD_WEB environment variableFATAL:STDERR:- ERROR:STDERR:- WARNING:STDERR:- #NOTICE:FILE.10.100:pdweb_install_dir/log/msg__notice_%ld.log #NOTICE_VERBOSE:FILE.10.100:pdweb_install_dir/log/msg__verbose_%ld.logwhere pdweb_install_dir is the value of the PD_WEB environment variable. The PD_WEB environment variable is set the WebSEAL installation directory during the initialization of the WebSEAL runtime environment.WebSEAL routing fileBy default WebSEAL writes all messages to the standard error device.

Windows: default routing file

FATAL:STDERR:-
ERROR:STDERR:-
WARNING:STDERR:-
#NOTICE:FILE.10.100:pdweb_install_dir/log/msg__notice_%ld.log
#NOTICE_VERBOSE:FILE.10.100:pdweb_install_dir/log/msg__verbose_%ld.log

where pdweb_install_dir is the value of the PD_WEB environment variable. The PD_WEB environment variable is set the WebSEAL installation directory during the initialization of the WebSEAL runtime environment.

Parent topic: WebSEAL routing file

Message routing filesMessage routing filesMessage routing filesTo understand how default message logs work, review several of the default routing files.routing filesunderstandingMessage event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers. C runtime routing file on WindowsPolicy server routing file on AIX, Linux, or SolarisWebSEAL routing file

Message routing files

To understand how default message logs work, review several of the default routing files.

C runtime routing file on Windows

Policy server routing file on AIX, Linux, or Solaris

WebSEAL routing file

Parent topic: Message event logging

C runtime routing file on WindowsC runtime routing file on WindowsC runtime routing file on Windowsrouting filesdefaultC runtimeWindowsrouting file, C runtimeC runtimeWindows routing fileThe default routing file for the C runtime on a Windows operating system, %PD_HOME%\etc\routing, contains message log specifications similar to the specifications in Figure 1.Sample C runtime routing fileFATAL:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log ERROR:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log WARNING:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log NOTICE:FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log #NOTICE_VERBOSE:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__verbose.logUsing this routing file, messages are logged in the following manner: FATAL messages are sent to the standard error device as ASCII text in the current code page and locale and also are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log file in the same format.ERROR messages are sent to the standard error device as ASCII text in the current code page and locale and also are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log file in the same format.WARNING messages are sent to the standard error device as ASCII text in the current code page and locale and also are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log file in the same format. NOTICE messages are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log file only.NOTICE_VERBOSE messages are not captured, because this line starts with the number sign (#).Message routing filesTo understand how default message logs work, review several of the default routing files.

C runtime routing file on Windows

The default routing file for the C runtime on a Windows operating system, %PD_HOME%\etc\routing, contains message log specifications similar to the specifications in Figure 98..

Figure 98. Sample C runtime routing file

FATAL:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log
ERROR:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log
WARNING:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log
NOTICE:FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log
#NOTICE_VERBOSE:STDERR:-;FILE:C:/PROGRA~1/Tivoli/POLICY~1/log/msg__verbose.log

Using this routing file, messages are logged in the following manner:

FATAL messages are sent to the standard error device as ASCII text in the current code page and locale and also are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__fatal.log file in the same format.

ERROR messages are sent to the standard error device as ASCII text in the current code page and locale and also are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__error.log file in the same format.

WARNING messages are sent to the standard error device as ASCII text in the current code page and locale and also are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__warning.log file in the same format.

NOTICE messages are written to the C:/PROGRA~1/Tivoli/POLICY~1/log/msg__notice.log file only.

NOTICE_VERBOSE messages are not captured, because this line starts with the number sign (#).

Parent topic: Message routing files

Policy server routing file on AIX, Linux, or SolarisPolicy server routing file on AIX, Linux, or SolarisPolicy server routing file on AIX, Linux, or Solarisrouting filesdefaultAIX, Linux, or Solaris policy serverAIXrouting filepolicy serverpolicy serverrouting file, AIX, Linux, or Solaris The default routing file for the policy server on a AIX, Linux, or Solaris operating system, /opt/PolicyDirector/etc/pdmgrd_routing, contains message log specifications similar to the specifications in Figure 1.Sample policy server routing fileFATAL:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.log: 644:ivmgr:ivmgr ERROR:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.log: 644:ivmgr:ivmgr WARNING:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.lo g:644:ivmgr:ivmgr NOTICE:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.log :644:ivmgr:ivmgr #NOTICE_VERBOSE:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd _utf8.log:644:ivmgr:ivmgrWith this routing file, messages are logged as follows: FATAL messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission. ERROR messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission. WARNING messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission. NOTICE messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission.NOTICE_VERBOSE messages are not written, because this line starts with the number sign (#).Message routing filesTo understand how default message logs work, review several of the default routing files.

Policy server routing file on AIX®, Linux, or Solaris

The default routing file for the policy server on a AIX, Linux, or Solaris operating system, /opt/PolicyDirector/etc/pdmgrd_routing, contains message log specifications similar to the specifications in Figure 99..

Figure 99. Sample policy server routing file

FATAL:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.log:
644:ivmgr:ivmgr
ERROR:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.log:
644:ivmgr:ivmgr
WARNING:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.lo
g:644:ivmgr:ivmgr
NOTICE:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd_utf8.log
:644:ivmgr:ivmgr
#NOTICE_VERBOSE:STDOUT:-;UTF8FILE:/var/PolicyDirector/log/msg__pdmgrd
_utf8.log:644:ivmgr:ivmgr

With this routing file, messages are logged as follows:

FATAL messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission.

ERROR messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission.

WARNING messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission.

NOTICE messages are written to the standard output device as ASCII text in the current code page and locale and written as UTF-8 text to the /var/PolicyDirector/log/msg__pdmgrd_utf8.log file. When the file is initially created, user ivmgr is the owner, ivmgr is the group, and 644 is the file permission.

NOTICE_VERBOSE messages are not written, because this line starts with the number sign (#).

Parent topic: Message routing files

WebSEAL routing fileWebSEAL routing fileWebSEAL routing filerouting filesdefaultWebSEAL serverAIXrouting fileWebSEALWebSEALrouting fileThe default routing file for a WebSEAL server contains message log specifications similar to the specifications in Figure 1.Sample WebSEAL routing fileFATAL:STDERR:- ERROR:STDERR:- WARNING:STDERR:- #NOTICE:FILE.10.100:/var/pdweb/log/msg__notice_%ld.log :644:ivmgr:ivmgr #NOTICE_VERBOSE:FILE.10.100:/var/pdweb/log/msg__verbose_%ld.log :644:ivmgr:ivmgrBy removing the number sign (#) from the NOTICE specification and stopping and then restarting the WebSEAL server, NOTICE messages are written to a set of 10 files. Assuming that the process ID of the WebSEAL server is 1017, the names of the 10 files would be: /var/pdweb/log/msg__notice_1017.log.1 /var/pdweb/log/msg__notice_1017.log.2 /var/pdweb/log/msg__notice_1017.log.3 /var/pdweb/log/msg__notice_1017.log.4 /var/pdweb/log/msg__notice_1017.log.5 /var/pdweb/log/msg__notice_1017.log.6 /var/pdweb/log/msg__notice_1017.log.7 /var/pdweb/log/msg__notice_1017.log.8 /var/pdweb/log/msg__notice_1017.log.9 /var/pdweb/log/msg__notice_1017.log.10Message logging starts with the first file, /var/pdweb/log/msg__notice_1017.log.1. After 100 NOTICE messages are logged to that file, messages are written to the next file, /var/pdweb/log/msg__notice_1017.log.2. Message logging continues in this manner until 100 messages are written to the /var/pdweb/log/msg__notice_1017.log.10 file. At that point, the messages in the first file are deleted, and logging resumes again to the /var/pdweb/log/msg__notice_1017.log.1 file.By default WebSEAL writes all messages to the standard error device. When WebSEAL is running in the background, standard error is redirected to the msg__webseald-instance_name.log file.Message routing filesTo understand how default message logs work, review several of the default routing files.

WebSEAL routing file

The default routing file for a WebSEAL server contains message log specifications similar to the specifications in Figure 100..

Figure 100. Sample WebSEAL routing file

FATAL:STDERR:-
ERROR:STDERR:-
WARNING:STDERR:-
#NOTICE:FILE.10.100:/var/pdweb/log/msg__notice_%ld.log
:644:ivmgr:ivmgr
#NOTICE_VERBOSE:FILE.10.100:/var/pdweb/log/msg__verbose_%ld.log
:644:ivmgr:ivmgr

By removing the number sign (#) from the NOTICE specification and stopping and then restarting the WebSEAL server, NOTICE messages are written to a set of 10 files. Assuming that the process ID of the WebSEAL server is 1017, the names of the 10 files would be:

/var/pdweb/log/msg__notice_1017.log.1
/var/pdweb/log/msg__notice_1017.log.2
/var/pdweb/log/msg__notice_1017.log.3
/var/pdweb/log/msg__notice_1017.log.4
/var/pdweb/log/msg__notice_1017.log.5
/var/pdweb/log/msg__notice_1017.log.6
/var/pdweb/log/msg__notice_1017.log.7
/var/pdweb/log/msg__notice_1017.log.8
/var/pdweb/log/msg__notice_1017.log.9
/var/pdweb/log/msg__notice_1017.log.10

Message logging starts with the first file, /var/pdweb/log/msg__notice_1017.log.1. After 100 NOTICE messages are logged to that file, messages are written to the next file, /var/pdweb/log/msg__notice_1017.log.2. Message logging continues in this manner until 100 messages are written to the /var/pdweb/log/msg__notice_1017.log.10 file. At that point, the messages in the first file are deleted, and logging resumes again to the /var/pdweb/log/msg__notice_1017.log.1 file.

Note: By default WebSEAL writes all messages to the standard error device. When WebSEAL is running in the background, standard error is redirected to the msg__webseald-instance_name.log file.

Parent topic: Message routing files

Limiting the size of message logsLimiting the size of message logsLimiting the size of message logsBy default, message logs grow without limit. Limiting message log size requires that the directories and file systems that contain message log files must be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.routing filesmessage logs, limit size ofmessageslimit sizelogsmessageslimit sizeThe routing files can be modified to limit the amount of disk space that is used for message logs.Consider the routing specification that is shown in Figure 1.Multiple log filesFATAL:STDOUT:-;UTF8FILE.10.100:/var/PolicyDirector/log/msg__pd mgrd_fatal_utf8.log:644:ivmgr:ivmgr ERROR:STDOUT:-;UTF8FILE.10.100:/var/PolicyDirector/log/msg__pd mgrd__error_utf8.log:644:ivmgr:ivmgr WARNING:STDOUT:-;UTF8FILE.5.1000:/var/PolicyDirector/log/msg__ pdmgrd_warning_utf8.log:644:ivmgr:ivmgr NOTICE:STDOUT:-;UTF8FILE.5.1000:/var/PolicyDirector/log/msg__p dmgrd_notice_utf8.log:644:ivmgr:ivmgr NOTICE_VERBOSE:STDOUT:-;XMLFILE.10.500:/var/PolicyDirector/log /msg__pdmgrd_verbose_utf8.xml:644:ivmgr:ivmgrAll message files that are produced by this message log specification are of a determinate size, thus the maximum disk space that can be used by all of the files can be calculated.Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers.

Limiting the size of message logs

By default, message logs grow without limit. Limiting message log size requires that the directories and file systems that contain message log files must be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.

The routing files can be modified to limit the amount of disk space that is used for message logs.

Consider the routing specification that is shown in Figure 101..

Figure 101. Multiple log files

FATAL:STDOUT:-;UTF8FILE.10.100:/var/PolicyDirector/log/msg__pd
mgrd_fatal_utf8.log:644:ivmgr:ivmgr
ERROR:STDOUT:-;UTF8FILE.10.100:/var/PolicyDirector/log/msg__pd
mgrd__error_utf8.log:644:ivmgr:ivmgr
WARNING:STDOUT:-;UTF8FILE.5.1000:/var/PolicyDirector/log/msg__
pdmgrd_warning_utf8.log:644:ivmgr:ivmgr
NOTICE:STDOUT:-;UTF8FILE.5.1000:/var/PolicyDirector/log/msg__p
dmgrd_notice_utf8.log:644:ivmgr:ivmgr
NOTICE_VERBOSE:STDOUT:-;XMLFILE.10.500:/var/PolicyDirector/log
/msg__pdmgrd_verbose_utf8.xml:644:ivmgr:ivmgr

All message files that are produced by this message log specification are of a determinate size, thus the maximum disk space that can be used by all of the files can be calculated.

Parent topic: Message event logging

Estimating the size of message logsEstimating the size of message logsEstimating the size of message logsEach entry in a message log file with a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size. The maximum size of any log file is 2 GB. messageslogsestimate sizelogsmessagesestimate sizeTivoli XML Log Viewerfile size estimationTo estimate the size of all the log files, in bytes, use the following equation: 200 × (Number of log files) × (Number of entries per log file)For example, given the following specification: NOTICE:UTF8FILE.10.1000:E:\LOGS\PDPROXYMGRD.LOGThe maximum size for the PDPROXYMGRD.LOG file would be approximately (200 × 10 × 1000) or 2,000,000 bytes.Each entry in a message log file with a destination of XMLFILE is an average of 650 bytes in size. Therefore, the maximum size of a log file, in bytes, can be estimated using the following equation: 650 × (Number of log files) × (Number of entries per log file)For example, given the following specification: NOTICE:XMLFILE.10.500:E:\LOGS\MSG__NOTICE.XMLThe maximum size for the MSG__NOTICE.XML file would be approximately (650 × 10 × 500) or 3,250,000 bytes.Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers.

Estimating the size of message logs

Each entry in a message log file with a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size. The maximum size of any log file is 2 GB.

To estimate the size of all the log files, in bytes, use the following equation:

200 × (Number of log files) × (Number of entries per log file)

For example, given the following specification:

NOTICE:UTF8FILE.10.1000:E:\LOGS\PDPROXYMGRD.LOG

The maximum size for the PDPROXYMGRD.LOG file would be approximately (200 × 10 × 1000) or 2,000,000 bytes.

Each entry in a message log file with a destination of XMLFILE is an average of 650 bytes in size. Therefore, the maximum size of a log file, in bytes, can be estimated using the following equation:

650 × (Number of log files) × (Number of entries per log file)

For example, given the following specification:

NOTICE:XMLFILE.10.500:E:\LOGS\MSG__NOTICE.XML

The maximum size for the MSG__NOTICE.XML file would be approximately (650 × 10 × 500) or 3,250,000 bytes.

Parent topic: Message event logging

Logging all messages the same wayLogging all messages the same wayLogging all messages the same wayYou can log messages to a single file.routing fileslocation, specifying one To send all runtime messages to a single file regardless of severity, the routing specification that is shown in Figure 1 can be used in the /opt/PolicyDirector/etc/routing file.Sending all messages to one location*:UTF8FILE:/tmp/msg__amrte_utf8.log:666:ivmgr:ivmgrMessage event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers.

Logging all messages the same way

You can log messages to a single file.

To send all runtime messages to a single file regardless of severity, the routing specification that is shown in Figure 102. can be used in the /opt/PolicyDirector/etc/routing file.

Figure 102. Sending all messages to one location

*:UTF8FILE:/tmp/msg__amrte_utf8.log:666:ivmgr:ivmgr

Parent topic: Message event logging

Changing the message format in log filesChanging the message format in log filesChanging the message format in log filesYou can change the message format for a server-specific message log file.To change the message format for a server-specific message log file, complete the following steps:Go to the directory where the routing file is located. The default location for the Security Access Manager servers is one of the following operating system-specific locations:AIX, Linux, and Solaris operating systems/opt/PolicyDirector/etc/Windows operating systems%PD_HOME%\etc\ The default location for a WebSEAL server is one of the following operating system-specific locations:AIX, Linux, and Solaris operating systems/opt/pdweb/etc/Windows operating systems%PD_WEB%\etc\Edit the appropriate server-related routing file. The following list contains the names of the routing files:pdmgrd_routingThe routing file for the policy serverpdacld_routingThe routing file for the authorization serverroutingThe routing file that is used for the C runtimeroutingThe routing file for the WebSEAL serverNote: Although the routing file for the C runtime and the WebSEAL server have the same file name, these files are in different directories.Find the statement that defines how to log messages of a specific severity. For example, find the ERROR statement in the routing file to change the logging of error messages. The ERROR statement might be similar the following statement:ERROR:STDOUT:-;UTF8FILE:pd_install_dir/log/msg__pdmgrd_utf8.log :644:ivmgr:ivmgrwhere pd_install_dir is either /var/PolicyDirector or the directory that is defined by the tivoli_common_dir stanza entry of the pd.conf configuration file (/var/ibm/tivoli/common).For example, to log error messages in the XML format and to log these messages to the msg__error.log file, make the following changes: Change UTF8FILE to XMLFILEChange msg__pdmgrd_utf8.log to msg__error.logThe following statement is the result of these changes: ERROR:STDOUT:-;XMLFILE:pd_install_dir/log/msg__error.log :644:ivmgr:ivmgrSave and exit the routing file.After this statement is changed, ERROR messages are written to the standard output device in ASCII text and written to the msg__error.log file in the XML format.Message event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers.

Changing the message format in log files

You can change the message format for a server-specific message log file.

About this task

To change the message format for a server-specific message log file, complete the following steps:

Procedure

Go to the directory where the routing file is located. The default location for the Security Access Manager servers is one of the following operating system-specific locations:

AIX, Linux, and Solaris operating systems

/opt/PolicyDirector/etc/

Windows operating systems

%PD_HOME%\etc\

The default location for a WebSEAL server is one of the following operating system-specific locations:

AIX, Linux, and Solaris operating systems

/opt/pdweb/etc/

Windows operating systems

%PD_WEB%\etc\

Edit the appropriate server-related routing file. The following list contains the names of the routing files:

pdmgrd_routing

The routing file for the policy server

pdacld_routing

The routing file for the authorization server

routing

The routing file that is used for the C runtime

routing

The routing file for the WebSEAL server

Note: Although the routing file for the C runtime and the WebSEAL server have the same file name, these files are in different directories.

Find the statement that defines how to log messages of a specific severity. For example, find the ERROR statement in the routing file to change the logging of error messages. The ERROR statement might be similar the following statement:

ERROR:STDOUT:-;UTF8FILE:pd_install_dir/log/msg__pdmgrd_utf8.log
:644:ivmgr:ivmgr

where pd_install_dir is either /var/PolicyDirector or the directory that is defined by the tivoli_common_dir stanza entry of the pd.conf configuration file (/var/ibm/tivoli/common).

For example, to log error messages in the XML format and to log these messages to the msg__error.log file, make the following changes:

Change UTF8FILE to XMLFILE

Change msg__pdmgrd_utf8.log to msg__error.log

The following statement is the result of these changes:

ERROR:STDOUT:-;XMLFILE:pd_install_dir/log/msg__error.log
:644:ivmgr:ivmgr

Save and exit the routing file.

Results

After this statement is changed, ERROR messages are written to the standard output device in ASCII text and written to the msg__error.log file in the XML format.

Parent topic: Message event logging

Sending messages to multiple places in different formatsSending messages to multiple places in different formatsSending messages to multiple places in different formatsYou can send messages to multiple locations with different message formats.routing filesdestinations, specifying multiple To send FATAL, ERROR, and WARNING messages from the authorization server to the standard output device as ASCII text, to a file as UTF-8 text, and to another file in XML log format, the specification that is shown in Figure 1 can be used in the %PD_HOME%\etc\msg__pdacld.routing file. Sending messages to standard output to file in UTF-8, and to file in XML formatFATAL:STDOUT:-;UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLO GS\MSG__PDACLD_%LD.XML ERROR:STDOUT:-;UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLO GS\MSG__PDACLD_%LD.XML WARNING:STDOUT:-;UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XML LOGS\MSG__PDACLD_%LD.XML NOTICE:UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLOGS\MSG__ PDACLD_%LD.XML NOTICE_VERBOSE:UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLO GS\MSG__PDACLD_%LD.XMLAfter you stop and restart the authorization server to pick up the changes to the routing file and assuming that the process ID of the authorization server is 1253, the following files are created to contain messages: C:\PDACLD_LOGS\MSG__PDACLD_1253.LOGC:\PDACLD_XMLLOGS\MSG__PDACLD_1253.XMLMessage event loggingThe contents of log files can be useful sources of information when you monitor or troubleshoot Security Access Manager servers.

Sending messages to multiple places in different formats

You can send messages to multiple locations with different message formats.

To send FATAL, ERROR, and WARNING messages from the authorization server to the standard output device as ASCII text, to a file as UTF-8 text, and to another file in XML log format, the specification that is shown in Figure 103. can be used in the %PD_HOME%\etc\msg__pdacld.routing file.

Figure 103. Sending messages to standard output to file in UTF-8, and to file in XML format

FATAL:STDOUT:-;UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLO
GS\MSG__PDACLD_%LD.XML
ERROR:STDOUT:-;UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLO
GS\MSG__PDACLD_%LD.XML
WARNING:STDOUT:-;UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XML
LOGS\MSG__PDACLD_%LD.XML
NOTICE:UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLOGS\MSG__
PDACLD_%LD.XML
NOTICE_VERBOSE:UTF8FILE:C:\LOGS\MSG__PDACLD_%LD.LOG;XMLFILE:C:\XMLLO
GS\MSG__PDACLD_%LD.XML

After you stop and restart the authorization server to pick up the changes to the routing file and assuming that the process ID of the authorization server is 1253, the following files are created to contain messages:

C:\PDACLD_LOGS\MSG__PDACLD_1253.LOG

C:\PDACLD_XMLLOGS\MSG__PDACLD_1253.XML

Parent topic: Message event logging

Trace event logsTrace event logsTrace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.Trace data is intended primarily for use by IBM Software Support. Trace data might be requested as part of diagnosing a reported problem. However, experienced product administrators can use trace data to diagnose and correct problems in a Security Access Manager environment. Use trace with caution. It is intended as a tool to use under the direction of IBM Software Support. Messages from tracing are sometimes cryptic, are not translated, and can severely degrade system performance.Trace logs are best suited to situations where a problem is easily reproduced, is short-lived in duration, and can be produced without significant trace generation from other system activity. Enabling tracing can adversely affect the performance of Security Access Manager and its associated products and applications.Tracing can be activated when servers, daemons, and applications start by using routing files and Java properties files. In some cases, tracing can be activated dynamically by using the server task trace command with the set option.Tracing from the C-language portions of Security Access Manager is controlled through routing files. Similarly, tracing from the Java language portions of Security Access Manager is controlled through Java properties files. When relevant, the distinction between these two methods of trace handling is mentioned.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Mechanisms for controlling trace logsThere are different trace log techniques that are used, depending on which component is being logged.Managing TraceTracing can be activated either through a routing file or through a Security Access Manager server task administrative command. Routing file examplesTo illustrate features available with the routing files, several examples are provided.Determining maximum size of a trace logEach entry that is made to a trace log file created that uses a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size. Enabling traceYou can enable tracing during startup and be able to view trace records.Using the trace commandsUse the server tasks trace command that is provided as by the pdadmin utility to manage trace components. Format of trace entry in logsTrace entries are recorded in a specific format.Trace logging for WebSEALThis section describes some of the options available for trace logs for WebSEAL.Available trace componentsThe following table contains all trace components that are common to all Security Access Manager servers:

Trace event logs

Security Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Trace data is intended primarily for use by IBM® Software Support. Trace data might be requested as part of diagnosing a reported problem. However, experienced product administrators can use trace data to diagnose and correct problems in a Security Access Manager environment.

Attention: Use trace with caution. It is intended as a tool to use under the direction of IBM Software Support. Messages from tracing are sometimes cryptic, are not translated, and can severely degrade system performance.

Trace logs are best suited to situations where a problem is easily reproduced, is short-lived in duration, and can be produced without significant trace generation from other system activity. Enabling tracing can adversely affect the performance of Security Access Manager and its associated products and applications.

Tracing can be activated when servers, daemons, and applications start by using routing files and Java™ properties files. In some cases, tracing can be activated dynamically by using the server task trace command with the set option.

Note: Tracing from the C-language portions of Security Access Manager is controlled through routing files. Similarly, tracing from the Java language portions of Security Access Manager is controlled through Java properties files. When relevant, the distinction between these two methods of trace handling is mentioned.

Mechanisms for controlling trace logs
There are different trace log techniques that are used, depending on which component is being logged.

Managing Trace
Tracing can be activated either through a routing file or through a Security Access Manager server task administrative command.

Routing file examples
To illustrate features available with the routing files, several examples are provided.

Determining maximum size of a trace log
Each entry that is made to a trace log file created that uses a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size.

Enabling trace
You can enable tracing during startup and be able to view trace records.

Using the trace commands
Use the server tasks trace command that is provided as by the pdadmin utility to manage trace components.

Format of trace entry in logs
Trace entries are recorded in a specific format.

Trace logging for WebSEAL
This section describes some of the options available for trace logs for WebSEAL.

Available trace components
The following table contains all trace components that are common to all Security Access Manager servers:

Parent topic: Troubleshooting

Mechanisms for controlling trace logsMechanisms for controlling trace logsMechanisms for controlling trace logsThere are different trace log techniques that are used, depending on which component is being logged.tracemechanisms for controllingtracemechanisms for controllingrouting filetracerouting filespurposerouting filestracespurposetracemechanisms for controllingproperties filetraceproperties filespurposeproperties filestracespurposeTracing can be controlled by using the following mechanisms: routing fileA routing file can be used to control tracing of the policy server, authorization server, WebSEAL, and runtime components. An affected component must be stopped and restarted for modifications to the routing file to take effect. Java properties fileA Java properties file can be used to control tracing of the IBM Security Access Manager Runtime for Java components.trace commandThe server task trace command can be used to dynamically control trace operations for the authorization server and WebSEAL components. This command can also be used to control trace operations for custom C applications that were developed by using the Security Access Manager authorization C APIs.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Mechanisms for controlling trace logs

There are different trace log techniques that are used, depending on which component is being logged.

Tracing can be controlled by using the following mechanisms:

routing file

A routing file can be used to control tracing of the policy server, authorization server, WebSEAL, and runtime components. An affected component must be stopped and restarted for modifications to the routing file to take effect.

Java™ properties file

A Java properties file can be used to control tracing of the IBM Security Access Manager Runtime for Java components.

trace command

The server task trace command can be used to dynamically control trace operations for the authorization server and WebSEAL components. This command can also be used to control trace operations for custom C applications that were developed by using the Security Access Manager authorization C APIs.

Parent topic: Trace event logs

Managing TraceManaging TraceManaging TraceTracing can be activated either through a routing file or through a Security Access Manager server task administrative command. tracemanageThe following information outlines details of the second method. For details on how to activate tracing through a routing file, see Customize logging events with routing filesRouting files are ASCII files that customize the logging of message and trace events for C language-based servers, daemons, and other C-language programs and applications..The server task trace command can be used to dynamically control trace operations. As with other Security Access Manager administrative functions, the trace command can be issued through either the pdadmin utility or programmatically through the Security Access Manager Administrative API. Different pdadmin commands are available to: List all of the available trace points.Change the level and destination for specific trace points.Retrieve the trace point level for specific trace points.Listing all trace commandsTo list all of the trace components that are offered by a server, issue the trace list command: server task server name trace list Where server name specifies the name of the server on which you want to collect trace information.pdadmin> server task PDWebPI-webpi.gc.au.ibm.com trace list pdwebpi.request pdwebpi.response ...Adjusting the trace level of a componentTo change the level and destination for a specific trace point, use the following command: server task <server name> trace set <component> \ <level> [file path=file|other-log-agent-config] Where:server nameSpecifies the name of the server on which you want to collect trace information.componentSpecifies the name of trace component as shown by the list command.levelControls the amount of detail to be gathered, in the range of 1 to 9, with 1 collecting the least number of traces, and 9 collecting the most number of traces.file pathThe optional file path parameter specifies the location for trace output. If this parameter is not supplied, the trace output is sent to the stdout stream of the server. The following example sets the trace level to 9 for the pdwebpi.request component. Any output that is generated is sent to the /tmp/log.txt file on the WebPI server.pdadmin> server task PDWebPI-wpi.com trace set pdwebpi.request 9 file path=/tmp/log.txtRetrieving the current trace level of a componentTo show the names and levels for all enabled trace components, use the following command: server task server-name trace show [component] If the optional component parameter is omitted, the output lists the name and level of all of the enabled trace components.pdadmin>server task PDWebPI-wpi.ibm.com trace show pdwebpi.request 9Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Managing Trace

Tracing can be activated either through a routing file or through a Security Access Manager server task administrative command.

The following information outlines details of the second method. For details on how to activate tracing through a routing file, see Customize logging events with routing files.

The server task trace command can be used to dynamically control trace operations. As with other Security Access Manager administrative functions, the trace command can be issued through either the pdadmin utility or programmatically through the Security Access Manager Administrative API.

Different pdadmin commands are available to:

List all of the available trace points.

Change the level and destination for specific trace points.

Retrieve the trace point level for specific trace points.

Listing all trace commands

To list all of the trace components that are offered by a server, issue the trace list command:

server task server name trace list

Where server name specifies the name of the server on which you want to collect trace information.

pdadmin> server task PDWebPI-webpi.gc.au.ibm.com trace list
pdwebpi.request
pdwebpi.response
...

Adjusting the trace level of a component

To change the level and destination for a specific trace point, use the following command:

server task <server name> trace set <component> \
<level> [file path=file|other-log-agent-config]

Where:

server name

Specifies the name of the server on which you want to collect trace information.

component

Specifies the name of trace component as shown by the list command.

level

Controls the amount of detail to be gathered, in the range of 1 to 9, with 1 collecting the least number of traces, and 9 collecting the most number of traces.

file path

The optional file path parameter specifies the location for trace output. If this parameter is not supplied, the trace output is sent to the stdout stream of the server.

The following example sets the trace level to 9 for the pdwebpi.request component. Any output that is generated is sent to the /tmp/log.txt file on the WebPI server.

pdadmin> server task PDWebPI-wpi.com trace set pdwebpi.request 9
file path=/tmp/log.txt

Retrieving the current trace level of a component

To show the names and levels for all enabled trace components, use the following command:

server task server-name trace show [component]

If the optional component parameter is omitted, the output lists the name and level of all of the enabled trace components.

pdadmin>server task PDWebPI-wpi.ibm.com trace show pdwebpi.request 9

Parent topic: Trace event logs

Routing file examplesRouting file examplesRouting file examplesTo illustrate features available with the routing files, several examples are provided.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.Trace logging in XML log formatTo send trace output for the authorization server to a single file in XML log format, the install_dir/etc/msg__pdacld.routing file can be modified as follows: Trace logging to multiple filesBy default, trace logs grow without limit. This requires that the directories and file systems that contain trace log files be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.Tracing a particular componentAt the direction of IBM Software Support, you might be asked to enable tracing for a particular component of Security Access Manager.

Routing file examples

To illustrate features available with the routing files, several examples are provided.

Trace logging in XML log format
To send trace output for the authorization server to a single file in XML log format, the install_dir/etc/msg__pdacld.routing file can be modified as follows:

Trace logging to multiple files
By default, trace logs grow without limit. This requires that the directories and file systems that contain trace log files be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.

Tracing a particular component
At the direction of IBM® Software Support, you might be asked to enable tracing for a particular component of Security Access Manager.

Parent topic: Trace event logs

Trace logging in XML log formatTrace logging in XML log formatTrace logging in XML log formatTo send trace output for the authorization server to a single file in XML log format, the install_dir/etc/msg__pdacld.routing file can be modified as follows: tracerouting filesexample, XML formatrouting filestracesexample, XML formatexamples, routing filesXML formatXML log formatexample*:*.9:XMLFILE:E:\PDACLD_XMLTRACE\TRACE__PDACLD_%LD.XMLAfter you stop and restart the authorization server to pick up the routing file change, and assuming that the process ID of the authorization server is 412, trace output is written to the following file: E:\PDACLD_XMLTRACE\TRACE__PDACLD_412.XMLRouting file examplesTo illustrate features available with the routing files, several examples are provided.

Trace logging in XML log format

To send trace output for the authorization server to a single file in XML log format, the install_dir/etc/msg__pdacld.routing file can be modified as follows:

*:*.9:XMLFILE:E:\PDACLD_XMLTRACE\TRACE__PDACLD_%LD.XML

After you stop and restart the authorization server to pick up the routing file change, and assuming that the process ID of the authorization server is 412, trace output is written to the following file:

E:\PDACLD_XMLTRACE\TRACE__PDACLD_412.XML

Parent topic: Routing file examples

Trace logging to multiple filesTrace logging to multiple filesTrace logging to multiple filesBy default, trace logs grow without limit. This requires that the directories and file systems that contain trace log files be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.tracerouting filesexample, multiple filesrouting filestracesexample, multiple filesexamples, routing filesfiles, multipleThe routing files can be modified to limit the amount of disk space that is used for trace logs.To send runtime trace output, from reporting levels 1 through 5, to 10 different files, each containing a maximum of 10000 trace entries, the routing specification that is shown in Figure 1 can be used in the /opt/PolicyDirector/etc/routing file.Sending trace output to multiple files*:*.5:UTF8FILE.10.10000:/tmp/trace__am_utf8.log:666:ivmgr:ivmgrTracing starts with the first file, /tmp/trace__am_utf8.log.1. After 10000 trace entries are logged to that file, trace entries are written to the second file, /tmp/trace__am_utf8.log.2. Tracing continues in this manner until 10000 trace entries are written to the /tmp/trace__am_utf8.log.10 file. At that point, the trace entries in the first file are deleted, and tracing resumes again to the /tmp/trace__am_utf8.log.1 file.Routing file examplesTo illustrate features available with the routing files, several examples are provided.

Trace logging to multiple files

By default, trace logs grow without limit. This requires that the directories and file systems that contain trace log files be checked on a periodic basis to ensure that enough space is available, and to prune the log files or make more space available as necessary.

The routing files can be modified to limit the amount of disk space that is used for trace logs.

To send runtime trace output, from reporting levels 1 through 5, to 10 different files, each containing a maximum of 10000 trace entries, the routing specification that is shown in Figure 104. can be used in the /opt/PolicyDirector/etc/routing file.

Figure 104. Sending trace output to multiple files

*:*.5:UTF8FILE.10.10000:/tmp/trace__am_utf8.log:666:ivmgr:ivmgr

Tracing starts with the first file, /tmp/trace__am_utf8.log.1. After 10000 trace entries are logged to that file, trace entries are written to the second file, /tmp/trace__am_utf8.log.2. Tracing continues in this manner until 10000 trace entries are written to the /tmp/trace__am_utf8.log.10 file. At that point, the trace entries in the first file are deleted, and tracing resumes again to the /tmp/trace__am_utf8.log.1 file.

Parent topic: Routing file examples

Tracing a particular componentTracing a particular componentTracing a particular componentAt the direction of IBM Software Support, you might be asked to enable tracing for a particular component of Security Access Manager. tracerouting filesexample, by componentrouting filestracesexample, by componentexamples, routing filescomponent, by For example, if asked to trace the mgr component of the policy server, the /opt/PolicyDirector/etc/pdmgrd_routing file can be modified as shown in Figure 1.Tracing a componentmgr:*.9:UTF8FILE:/tmp/trace__pdmgrd_mgr_9_utf8.log:644:ivmgr:ivmgrRouting file examplesTo illustrate features available with the routing files, several examples are provided.

Tracing a particular component

At the direction of IBM® Software Support, you might be asked to enable tracing for a particular component of Security Access Manager.

For example, if asked to trace the mgr component of the policy server, the /opt/PolicyDirector/etc/pdmgrd_routing file can be modified as shown in Figure 105..

Figure 105. Tracing a component

mgr:*.9:UTF8FILE:/tmp/trace__pdmgrd_mgr_9_utf8.log:644:ivmgr:ivmgr

Parent topic: Routing file examples

Determining maximum size of a trace logDetermining maximum size of a trace logDetermining maximum size of a trace logEach entry that is made to a trace log file created that uses a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size. tracerouting filessize, determinerouting filestracessize, determining The maximum size of a log file, in bytes, can be estimated as follows: 200 × (Number of log files) × (Number of entries per log file)For example, given a specification of: *:*.9:TEXTFILE.10.10000:C:/PROGRA~1/Tivoli/POLICY~1/log/trace__%ld.logThe maximum size would be approximately (200 × 10 × 10000) or 20,000,000 bytes.Trace entries that are written in XML log format are an average of 500 bytes in size, thus for a specification of: *:*.9:XMLFILE.10.10000:/var/dbug20031028A/trace__%ld.xmlThe maximum size would be approximately (500 × 10 × 10000) or 50,000,000 bytes.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Determining maximum size of a trace log

Each entry that is made to a trace log file created that uses a destination of FILE, TEXTFILE, or UTF8FILE is an average of 200 bytes in size.

The maximum size of a log file, in bytes, can be estimated as follows:

200 × (Number of log files) × (Number of entries per log file)

For example, given a specification of:

*:*.9:TEXTFILE.10.10000:C:/PROGRA~1/Tivoli/POLICY~1/log/trace__%ld.log

The maximum size would be approximately (200 × 10 × 10000) or 20,000,000 bytes.

Trace entries that are written in XML log format are an average of 500 bytes in size, thus for a specification of:

*:*.9:XMLFILE.10.10000:/var/dbug20031028A/trace__%ld.xml

The maximum size would be approximately (500 × 10 × 10000) or 50,000,000 bytes.

Parent topic: Trace event logs

Enabling traceEnabling traceEnabling traceYou can enable tracing during startup and be able to view trace records.traceenableTo enable tracing during startup and be able to view trace records, complete the following steps:Edit the appropriate routing file for the server. The following list contains the names of the routing filespdmgrd_routingThe routing file for the Security Access Manager policy serverpdacld_routingThe routing file for the Security Access Manager authorization serverAdd a line similar to the following to the routing file:*:*.9:TEXTFILE:pd_install_dir/log/trace_%ld.logwhere, on a Windows operating system, pd_install_dir is either the directory where Security Access Manager is installed or the Tivoli Common Directory location. Or, remove the number sign (#) at the beginning of this line, if it exists in the routing file, to allow viewing of trace records.Change this line, if you want to log in this debug trace data XML log format. For example, you can change the line to send the output to an XML file instead of a text file:*:*.9:XMLFILE.10.1000:pd_install_dir/log/trace__%ld.log;XMLSTDERR:-where, on a AIX, Linux, or Solaris operating system, pd_install_dir is either /var/PolicyDirector or the Tivoli Common Directory location.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Enabling trace

You can enable tracing during startup and be able to view trace records.

About this task

To enable tracing during startup and be able to view trace records, complete the following steps:

Procedure

Edit the appropriate routing file for the server. The following list contains the names of the routing files

pdmgrd_routing

The routing file for the Security Access Manager policy server

pdacld_routing

The routing file for the Security Access Manager authorization server

Add a line similar to the following to the routing file:

*:*.9:TEXTFILE:pd_install_dir/log/trace_%ld.log

where, on a Windows operating system, pd_install_dir is either the directory where Security Access Manager is installed or the Tivoli Common Directory location.

Or, remove the number sign (#) at the beginning of this line, if it exists in the routing file, to allow viewing of trace records.

Change this line, if you want to log in this debug trace data XML log format. For example, you can change the line to send the output to an XML file instead of a text file:

*:*.9:XMLFILE.10.1000:pd_install_dir/log/trace__%ld.log;XMLSTDERR:-

where, on a AIX, Linux, or Solaris operating system, pd_install_dir is either /var/PolicyDirector or the Tivoli Common Directory location.

Parent topic: Trace event logs

Using the trace commandsUsing the trace commandsUsing the trace commandsUse the server tasks trace command that is provided as by the pdadmin utility to manage trace components. tracecommandsoverviewcommandstracesoverviewserver task trace commandoverviewYou can use the trace command to complete the following operations: trace listList all available trace componentstrace setEnable the trace level and trace message destination for a component and its subordinatestrace showShow the name and level for all enabled trace components or for the specified componentFor more information about the server task trace command, see server task trace.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.Listing available trace componentsYou can list the specified component or all components that are available to gather and report trace information. Enabling traceUse the server task trace set command to enable the gathering of trace information for the specified component and level.Showing enabled trace componentsYou can list all enabled trace components or a specific enabled component. Changing the name and location of trace filesTrace log file locations and names depends on which Security Access Manager component is being traced.

Using the trace commands

Use the server tasks trace command that is provided as by the pdadmin utility to manage trace components.

You can use the trace command to complete the following operations:

trace list

List all available trace components

trace set

Enable the trace level and trace message destination for a component and its subordinates

trace show

Show the name and level for all enabled trace components or for the specified component

For more information about the server task trace command, see server task trace.

Listing available trace components
You can list the specified component or all components that are available to gather and report trace information.

Enabling trace
Use the server task trace set command to enable the gathering of trace information for the specified component and level.

Showing enabled trace components
You can list all enabled trace components or a specific enabled component.

Changing the name and location of trace files
Trace log file locations and names depends on which Security Access Manager component is being traced.

Parent topic: Trace event logs

Listing available trace componentsListing available trace componentsListing available trace componentsYou can list the specified component or all components that are available to gather and report trace information. tracecommandscomponents, listcommandstracescomponents, listserver task trace commandcomponentslist trace componentslistTo list the specified component or all components available to gather and report trace information, run the following command:trace list [component]The trace components themselves are organized in a hierarchical fashion. If trace is activated for a parent trace component, it will automatically be activated for all children trace components. As an example, if you activate trace for the component: pdweb.snoop, tracing for the sub-component, pdweb.snoop.jct will also be activated.Using the trace commandsUse the server tasks trace command that is provided as by the pdadmin utility to manage trace components.

Listing available trace components

You can list the specified component or all components that are available to gather and report trace information.

To list the specified component or all components available to gather and report trace information, run the following command:

trace list [component]

The trace components themselves are organized in a hierarchical fashion. If trace is activated for a parent trace component, it will automatically be activated for all children trace components. As an example, if you activate trace for the component: pdweb.snoop, tracing for the sub-component, pdweb.snoop.jct will also be activated.

Parent topic: Using the trace commands

Enabling traceEnabling traceEnabling traceUse the server task trace set command to enable the gathering of trace information for the specified component and level.tracecommandsenabling componentscommandstracescomponents, enableserver task trace commandtrace, enable trace componentsenabletrace set component level [file path=file | log_agent]where: componentThe trace component name. This required argument indicates the component to be enabled. WebSEAL components are prefixed with pdweb.levelReporting level. This required argument must be in the range of 1 to 9. The level argument specifies the number of details that are gathered by the trace command. Level 1 indicates the least detailed output, and level 9 indicates the most detailed output. fileThe fully qualified name of the file to which trace data is written.log_agentOptionally specifies a destination for the trace information that is gathered for the specified component. See the event log information in the Administering topics in the IBM Knowledge Center.Using the trace commandsUse the server tasks trace command that is provided as by the pdadmin utility to manage trace components.

Enabling trace

Use the server task trace set command to enable the gathering of trace information for the specified component and level.

trace set component level [file path=file | log_agent]

where:

component

The trace component name. This required argument indicates the component to be enabled. WebSEAL components are prefixed with pdweb.

level

Reporting level. This required argument must be in the range of 1 to 9. The level argument specifies the number of details that are gathered by the trace command. Level 1 indicates the least detailed output, and level 9 indicates the most detailed output.

file

The fully qualified name of the file to which trace data is written.

log_agent

Optionally specifies a destination for the trace information that is gathered for the specified component. See the event log information in the Administering topics in the IBM Knowledge Center.

Parent topic: Using the trace commands

Showing enabled trace componentsShowing enabled trace componentsShowing enabled trace componentsYou can list all enabled trace components or a specific enabled component. tracecommandsenabled components, listcommandstracescomponents, list enabledserver task trace commandcomponentsshow enabled trace componentsshow enabledIf a specified component is not enabled, no output is displayed.trace show [component]Example: pdadmin> server task webseald-instance trace set pdweb.debug 2 pdadmin> server task webseald-instance trace show pdweb.debug 2Using the trace commandsUse the server tasks trace command that is provided as by the pdadmin utility to manage trace components.

Showing enabled trace components

You can list all enabled trace components or a specific enabled component.

If a specified component is not enabled, no output is displayed.

trace show [component]

Example:

pdadmin> server task webseald-instance trace set pdweb.debug 2
pdadmin> server task webseald-instance trace show pdweb.debug 2

Parent topic: Using the trace commands

Changing the name and location of trace filesChanging the name and location of trace filesChanging the name and location of trace filesTrace log file locations and names depends on which Security Access Manager component is being traced. tracelog fileslocationtracelog filesnameFor the Security Access Manager authorization server, the trace log file can be explicitly specified by the user in the following command:pdadmin> server task server-name trace set component level [file path=file] where server-name is the name of the authorization server that is displayed by the server list command, and file is the fully qualified trace file name.Alternatively, if the Security Access Manager routing file is being used to enable and disable tracing, then the location and name of this trace log file can be defined within the routing file.For WebSEAL, the trace log file can be explicitly specified by the user in the following command:pdadmin> server task server-name trace set component level [file path=file]where server-name is the name of the WebSEAL server that is displayed by the server list command, and file is the fully qualified trace file name.Alternatively, if the WebSEAL routing file is being used to enable and disable tracing, then the location and name of this trace log file can be defined within the routing file.Using the trace commandsUse the server tasks trace command that is provided as by the pdadmin utility to manage trace components.

Changing the name and location of trace files

Trace log file locations and names depends on which Security Access Manager component is being traced.

For the Security Access Manager authorization server, the trace log file can be explicitly specified by the user in the following command:

pdadmin> server task server-name trace set component level [file path=file]

where server-name is the name of the authorization server that is displayed by the server list command, and file is the fully qualified trace file name.

Alternatively, if the Security Access Manager routing file is being used to enable and disable tracing, then the location and name of this trace log file can be defined within the routing file.

For WebSEAL, the trace log file can be explicitly specified by the user in the following command:

pdadmin> server task server-name trace set component level [file path=file]

where server-name is the name of the WebSEAL server that is displayed by the server list command, and file is the fully qualified trace file name.

Alternatively, if the WebSEAL routing file is being used to enable and disable tracing, then the location and name of this trace log file can be defined within the routing file.

Parent topic: Using the trace commands

Format of trace entry in logsFormat of trace entry in logsFormat of trace entry in logsTrace entries are recorded in a specific format.tracelog filesentry formatFigure 1 shows an example of a trace entry that is taken from a Security Access Manager trace log file.Sample trace log entry in text format2005-10-29-18:01:06.984-06:00I——- pdmgrd DEBUG8 mgr general e:\am600\src\ivmgrd\pdmgrapi\MrMgmtDomainMan.cpp 736 0x000007d0 CII ENTRY: MrMgmtDomainMan::setCurrentDomainNameThe following list describes the trace entry that is shown in Figure 1. 2005-10-29-18:01:06.984-06:00IIndicates the timestamp of the trace entry. Timestamp is in the following format: YYYY–MM–DD–hh:mm:ss.fff[+|–]hh:mmI where: YYYY-MM-DDSpecifies the date in year, month, and day.hh:mm:ss.fffSpecifies the time in hours, minutes, seconds, and fractional seconds.hh:mmISpecifies the time inaccuracy factorpdmgrdIndicates the name of the process which created the entry.DEBUG8Indicates the reporting level of the trace entry.mgrIndicates the component for the process that generated the entry.generalIndicates the subcomponent for the process that generated the entry.e:\am600\src\ivmgrd\pdmgrapi\MrMgmtDomainMan.cppIndicates the name of the product source file that generated the entry.736Indicates the exact line number in source file.0x000007d0Indicates the thread ID in hexadecimal.CII ENTRY: MrMgmtDomainMan:setCurrentDomainNameIndicates the text of the trace entry.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Format of trace entry in logs

Trace entries are recorded in a specific format.

Figure 106. shows an example of a trace entry that is taken from a Security Access Manager trace log file.

Figure 106. Sample trace log entry in text format

2005-10-29-18:01:06.984-06:00I——- pdmgrd DEBUG8 mgr general
e:\am600\src\ivmgrd\pdmgrapi\MrMgmtDomainMan.cpp 736 0x000007d0
CII ENTRY: MrMgmtDomainMan::setCurrentDomainName

The following list describes the trace entry that is shown in Figure 106..

2005-10-29-18:01:06.984-06:00I

Indicates the timestamp of the trace entry. Timestamp is in the following format: YYYY–MM–DD–hh:mm:ss.fff[+|–]hh:mmI

where:

YYYY-MM-DD

Specifies the date in year, month, and day.

hh:mm:ss.fff

Specifies the time in hours, minutes, seconds, and fractional seconds.

hh:mmI

Specifies the time inaccuracy factor

pdmgrd

Indicates the name of the process which created the entry.

DEBUG8

Indicates the reporting level of the trace entry.

mgr

Indicates the component for the process that generated the entry.

general

Indicates the subcomponent for the process that generated the entry.

e:\am600\src\ivmgrd\pdmgrapi\MrMgmtDomainMan.cpp

Indicates the name of the product source file that generated the entry.

736

Indicates the exact line number in source file.

0x000007d0

Indicates the thread ID in hexadecimal.

CII ENTRY: MrMgmtDomainMan:setCurrentDomainName

Indicates the text of the trace entry.

Parent topic: Trace event logs

Trace logging for WebSEALTrace logging for WebSEALTrace logging for WebSEALThis section describes some of the options available for trace logs for WebSEAL.trace log filesWebSEALWebSEALtrace logWebSEAL provides the following components to trace HTTP requests: pdweb.debugpdweb.snoop The amount of data that is produced by the trace options, especially by the snoop trace command, can be large.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.pd.ivc.ira trace for LDAP server interactionThe pd.ivc.ira component traces Security Access Manager interaction with the LDAP server.pdweb.debug trace of HTTP header requests and responsesThe pdweb.debug component traces the HTTP headers for requests and responses.pdweb.snoop trace of HTTP traffic with WebSEALThe pdweb.snoop component traces HTTP traffic. This component logs the HTTP headers and the message body for requests and responses. pdweb.wan.azn trace for transaction authorization decisionsThe pdweb.wan.azn component traces authorization decisions for all transactions.Setting trace for Security Access Manager SPNEGO issuesEnable trace for SPNEGO so that you can retrieve more details about WebSEAL issues.

Trace logging for WebSEAL

This section describes some of the options available for trace logs for WebSEAL.

WebSEAL provides the following components to trace HTTP requests:

pdweb.debug

pdweb.snoop

Note: The amount of data that is produced by the trace options, especially by the snoop trace command, can be large.

pd.ivc.ira trace for LDAP server interaction
The pd.ivc.ira component traces Security Access Manager interaction with the LDAP server.

pdweb.debug trace of HTTP header requests and responses
The pdweb.debug component traces the HTTP headers for requests and responses.

pdweb.snoop trace of HTTP traffic with WebSEAL
The pdweb.snoop component traces HTTP traffic. This component logs the HTTP headers and the message body for requests and responses.

pdweb.wan.azn trace for transaction authorization decisions
The pdweb.wan.azn component traces authorization decisions for all transactions.

Setting trace for Security Access Manager SPNEGO issues
Enable trace for SPNEGO so that you can retrieve more details about WebSEAL issues.

Parent topic: Trace event logs

pd.ivc.ira trace for LDAP server interactionpd.ivc.ira trace for LDAP server interactionpd.ivc.ira trace for LDAP server interactionThe pd.ivc.ira component traces Security Access Manager interaction with the LDAP server.pd.ivc.iraThe trace helps with determining problems that occur during authentication. This trace can show the following information: The LDAP search path that is used during the search for a userWhether authentication succeeded for the userWhether any policy (for example, password, time-of-day) took effectThis information helps to identify Security Access Manager problems that originate from the LDAP server. The trace also shows the general interaction with the local user registry cache.If the trace level is set to 7, approximately 30 lines of trace are produced for every transaction. This trace level mostly shows the authentication process. It can be used to determine whether a DN for the user was successfully located, and whether authentication for the user succeeded.If the trace level is set to 8, approximately 170 lines of trace are produced for every transaction. In addition to the authentication process, this trace level logs the steps that are involved in validating the user policy. It also shows some interaction with the local user registry cache. The following sample output is an extract of the trace that is produced during a standard authentication for a trace level of 8. The output shows that the user, scotte, was successfully authenticated and that the DN of the user is cn=Scott Exton,o=ibm,c=au.Example pd.ivc.ira output (extract) ... 2007-03-09-14:31:00.329+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61 0/src/ivrgy/ira_auth.c:1221: CII ENTRY: ira_get_dn_utf8() parm: scotte ... 2007-03-09-14:31:00.329+10:00I----- thread(2) trace.pd.ivc.ira:7 /project/am610/build/am61 0/src/ivrgy/ira_entry.c:2879: ira_ldap_search_ext_s() base: SECAUTHORITY=DEFAULT scope: 2 filter: (secDomainId=Default%scotte) 2007-03-09-14:31:00.329+10:00I----- thread(2) trace.pd.ivc.ira:7 /project/am610/build/am61 0/src/ivrgy/ira_ldap.c:3009: ira_ldap_search_ext_s(): No timeout - calling ldap_search_ext _s 2007-03-09-14:31:00.331+10:00I----- thread(2) trace.pd.ivc.ira:7 /project/am610/build/am61 0/src/ivrgy/ira_ldap.c:3029: ira_ldap_search_ext_s: Returning LDAP rc x0 ... 2007-03-09-14:31:00.332+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61 0/src/ivrgy/ira_auth.c:1738: CII ENTRY: ira_authenticate_user3() parm: cn=Scott Exton,o=ib m,c=au ... 2007-03-09-14:31:00.334+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61 0/src/ivrgy/ira_auth.c:1596: CII EXIT ira_auth_passwd_compare() with status: 0x00000000 ... 2007-03-09-14:31:00.334+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61 0/src/ivrgy/ira_cache.c:1588: CII EXIT ira_cache_user_get_account_state() with status: 0x 00000000 ... 2007-03-09-14:31:00.340+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61 0/src/ivrgy/ira_auth.c:2160: CII EXIT ira_authenticate_user3() with status: 0x00000000Trace logging for WebSEALThis section describes some of the options available for trace logs for WebSEAL.

pd.ivc.ira trace for LDAP server interaction

The pd.ivc.ira component traces Security Access Manager interaction with the LDAP server.

The trace helps with determining problems that occur during authentication. This trace can show the following information:

The LDAP search path that is used during the search for a user

Whether authentication succeeded for the user

Whether any policy (for example, password, time-of-day) took effect

This information helps to identify Security Access Manager problems that originate from the LDAP server. The trace also shows the general interaction with the local user registry cache.

If the trace level is set to 7, approximately 30 lines of trace are produced for every transaction. This trace level mostly shows the authentication process. It can be used to determine whether a DN for the user was successfully located, and whether authentication for the user succeeded.

If the trace level is set to 8, approximately 170 lines of trace are produced for every transaction. In addition to the authentication process, this trace level logs the steps that are involved in validating the user policy. It also shows some interaction with the local user registry cache.

The following sample output is an extract of the trace that is produced during a standard authentication for a trace level of 8. The output shows that the user, scotte, was successfully authenticated and that the DN of the user is cn=Scott Exton,o=ibm,c=au.

Example pd.ivc.ira output (extract)

...
2007-03-09-14:31:00.329+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61
0/src/ivrgy/ira_auth.c:1221: CII ENTRY: ira_get_dn_utf8() parm: scotte
...
2007-03-09-14:31:00.329+10:00I----- thread(2) trace.pd.ivc.ira:7 /project/am610/build/am61
0/src/ivrgy/ira_entry.c:2879: ira_ldap_search_ext_s() base: SECAUTHORITY=DEFAULT scope: 2
filter: (secDomainId=Default%scotte)
2007-03-09-14:31:00.329+10:00I----- thread(2) trace.pd.ivc.ira:7 /project/am610/build/am61
0/src/ivrgy/ira_ldap.c:3009: ira_ldap_search_ext_s(): No timeout - calling ldap_search_ext
_s
2007-03-09-14:31:00.331+10:00I----- thread(2) trace.pd.ivc.ira:7 /project/am610/build/am61
0/src/ivrgy/ira_ldap.c:3029: ira_ldap_search_ext_s: Returning LDAP rc x0
...
2007-03-09-14:31:00.332+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61
0/src/ivrgy/ira_auth.c:1738: CII ENTRY: ira_authenticate_user3() parm: cn=Scott Exton,o=ib
m,c=au
...
2007-03-09-14:31:00.334+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61
0/src/ivrgy/ira_auth.c:1596: CII EXIT ira_auth_passwd_compare() with status:  0x00000000
...
2007-03-09-14:31:00.334+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61
0/src/ivrgy/ira_cache.c:1588: CII EXIT ira_cache_user_get_account_state() with status:  0x
00000000
...
2007-03-09-14:31:00.340+10:00I----- thread(2) trace.pd.ivc.ira:8 /project/am610/build/am61
0/src/ivrgy/ira_auth.c:2160: CII EXIT ira_authenticate_user3() with status:  0x00000000

Parent topic: Trace logging for WebSEAL

pdweb.debug trace of HTTP header requests and responsespdweb.debug trace of HTTP header requests and responsespdweb.debug trace of HTTP header requests and responsesThe pdweb.debug component traces the HTTP headers for requests and responses.WebSEALtrace componentspdweb.debugWebSEALtraceHTTP headersHTTPWebSEAL traceheaderstraceWebSEAL componentspdweb.debugpdweb.debug componentThe pdweb.debug component operates at level 2 only. To log the message body, see pdweb.snoop trace of HTTP traffic with WebSEALThe pdweb.snoop component traces HTTP traffic. This component logs the HTTP headers and the message body for requests and responses. .The following example command starts the trace utility for the pdweb.debug component at level 2 and directs the output to a file: pdadmin> server task webseald-instance trace set pdweb.debug 2 \ file path=debug.logSample output of this command as it displays in the debug.log file: 2012-08-10-23:42:19.725+00:00I----- thread(7) trace.pdweb.debug:2 /amweb600/src/wand/wand/log.c:278: ------------- Browser ===> PD ------------- Thread_ID:27 GET /junction/footer.gif HTTP/1.1 Accept: */* Referer: https://bevan/junction/ Accept-Language: en-us Accept-Encoding: gzip, deflate If-Modified-Since: Wed, 11 Jul 2009 21:11:14 GMT If-None-Match: "abe09-3c8-3b4cc0f2" User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.0.3705) Host: bevan Connection: Keep-Alive --------------------------------------------------- 2012-08-10-23:42:19.736+00:00I----- thread(7) trace.pdweb.debug:2 /amweb600/src/wand/wand/log.c:278: ------------- PD ===> BackEnd ------------- Thread_ID:27 GET /footer.gif HTTP/1.1 via: HTTP/1.1 bevan:443 host: blade.cruz.ibm.com:444 user-agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.0.3705) accept: */* accept-language: en-us accept-encoding: gzip, deflate if-none-match: "abe09-3c8-3b4cc0f2" referer: https://bevan/blade/ if-modified-since: Wed, 11 Jul 2009 21:11:14 GMT connection: close --------------------------------------------------- 2012-08-10-23:42:19.739+00:00I----- thread(7) trace.pdweb.debug:2 /amweb600/src/wand/wand/log.c:278: ------------- PD <=== BackEnd ------------- Thread_ID:27 HTTP/1.1 304 Not Modified date: Wed, 10 Aug 2012 23:34:17 GMT etag: "abe09-3c8-3b4cc0f2" server: IBM_HTTP_SERVER/1.3.19.1Apache/1.3.20 (Unix) connection: close --------------------------------------------------- 2012-08-10-23:42:19.740+00:00I----- thread(7) trace.pdweb.debug:2 /amweb600/src/wand/wand/log.c:278: ------------- Browser <=== PD ------------ Thread_ID:27 HTTP/1.1 304 Not Modified date: Wed, 10 Aug 2012 23:34:17 GMT etag: "abe09-3c8-3b4cc0f2" server: IBM_HTTP_SERVER/1.3.19.1Apache/1.3.20 (Unix) ---------------------------------------------------Trace logging for WebSEALThis section describes some of the options available for trace logs for WebSEAL.

pdweb.debug trace of HTTP header requests and responses

The pdweb.debug component traces the HTTP headers for requests and responses.

The pdweb.debug component operates at level 2 only. To log the message body, see pdweb.snoop trace of HTTP traffic with WebSEAL.

The following example command starts the trace utility for the pdweb.debug component at level 2 and directs the output to a file:

pdadmin> server task webseald-instance trace set pdweb.debug 2 \
file path=debug.log

Sample output of this command as it displays in the debug.log file:

2012-08-10-23:42:19.725+00:00I----- thread(7) trace.pdweb.debug:2
/amweb600/src/wand/wand/log.c:278: ------------- Browser ===> PD -------------
Thread_ID:27
GET /junction/footer.gif HTTP/1.1
Accept: */*
Referer: https://bevan/junction/
Accept-Language: en-us
Accept-Encoding: gzip, deflate
If-Modified-Since: Wed, 11 Jul 2009 21:11:14 GMT
If-None-Match: "abe09-3c8-3b4cc0f2"
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.0.3705)
Host: bevan
Connection: Keep-Alive
---------------------------------------------------

2012-08-10-23:42:19.736+00:00I----- thread(7) trace.pdweb.debug:2
/amweb600/src/wand/wand/log.c:278: ------------- PD ===> BackEnd -------------
Thread_ID:27
GET /footer.gif HTTP/1.1
via: HTTP/1.1 bevan:443
host: blade.cruz.ibm.com:444
user-agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.0.3705)
accept: */*
accept-language: en-us
accept-encoding: gzip, deflate
if-none-match: "abe09-3c8-3b4cc0f2"
referer: https://bevan/blade/
if-modified-since: Wed, 11 Jul 2009 21:11:14 GMT
connection: close
---------------------------------------------------

2012-08-10-23:42:19.739+00:00I----- thread(7) trace.pdweb.debug:2
/amweb600/src/wand/wand/log.c:278: ------------- PD <=== BackEnd -------------
Thread_ID:27
HTTP/1.1 304 Not Modified
date: Wed, 10 Aug 2012 23:34:17 GMT
etag: "abe09-3c8-3b4cc0f2"
server: IBM_HTTP_SERVER/1.3.19.1Apache/1.3.20 (Unix)
connection: close
---------------------------------------------------

2012-08-10-23:42:19.740+00:00I----- thread(7) trace.pdweb.debug:2
/amweb600/src/wand/wand/log.c:278: ------------- Browser <=== PD ------------
Thread_ID:27
HTTP/1.1 304 Not Modified
date: Wed, 10 Aug 2012 23:34:17 GMT
etag: "abe09-3c8-3b4cc0f2"
server: IBM_HTTP_SERVER/1.3.19.1Apache/1.3.20 (Unix)
---------------------------------------------------

Parent topic: Trace logging for WebSEAL

pdweb.snoop trace of HTTP traffic with WebSEALpdweb.snoop trace of HTTP traffic with WebSEALpdweb.snoop trace of HTTP traffic with WebSEALThe pdweb.snoop component traces HTTP traffic. This component logs the HTTP headers and the message body for requests and responses. WebSEALtrace componentspdweb.snoopWebSEALtrace componentspdweb.snoop.clientWebSEALtrace componentspdweb.snoop.jctWebSEALtraceHTTP trafficHTTPWebSEAL tracetraffictraceWebSEAL componentspdweb.snooptraceWebSEAL componentspdweb.snoop.clienttraceWebSEAL componentspdweb.snoop.jctpdweb.snoop componentpdweb.snoop.client componentpdweb.snoop.jct componentThe snoop component traces the entire request and response as it is read off the socket. This trace might contain sensitive information.The pdweb.snoop component has the following subcomponents: pdweb.snoop.clientTraces data that is sent between WebSEAL and clients.pdweb.snoop.jct Traces data that is sent between WebSEAL and junctions.To trace only the message headers, see pdweb.debug trace of HTTP header requests and responsesThe pdweb.debug component traces the HTTP headers for requests and responses..The following example command starts the trace utility for the pdweb.snoop component at level 9 and directs the output to a file: pdadmin> server task webseald-instance trace set pdweb.snoop 9 \ file path=snoop.outThe following sample output shows the WebSEAL server that is sending 2137 bytes of data to a client at IP address 10.4.5.12: ---------------------------------------- 2012-08-10-19:35:18.541+00:00I----- thread(5) trace.pdweb.snoop.client:1 /home/amweb600/src/pdwebrte/webcore/amw_snoop.cpp:159: ---------------------------------------- Thread 2828; fd 22; local 10.4.5.10:443; remote 10.4.5.12:1250 Sending 2137 bytes 0x0000 4854 5450 2f31 2e31 2034 3033 2046 6f72 HTTP/1.1.403.For 0x0010 6269 6464 656e 0d0a 6461 7465 3a20 5475 bidden..date:.We 0x0020 652c 2032 3820 4f63 7420 3230 3033 2031 d,.10.Aug.2005.1 0x0030 393a 3335 3a31 3820 474d 540d 0a73 6572 9:35:18.GMT..ser 0x0040 7665 723a 2057 6562 5345 414c 2f35 2e31 ver:.WebSEAL/5.1 0x0050 2e30 2e30 2028 4275 696c 6420 3033 3130 .0.0.(Build.0310 0x0060 3230 290d 0a63 6163 6865 2d63 6f6e 7472 20)..cache-contr 0x0070 6f6c 3a20 6e6f 2d63 6163 6865 0d0a 7072 ol:.no-cache..pr 0x0080 6167 6d61 3a20 6e6f 2d63 6163 6865 0d0a agma:.no-cache.. 0x0090 636f 6e74 656e 742d 6c65 6e67 7468 3a20 content-length:. 0x00a0 3139 3038 0d0a 7033 703a 2043 503d 224e 1908..p3p:.CP="N 0x00b0 4f4e 2043 5552 204f 5450 6920 4f55 5220 ON.CUR.OTPi.OUR. 0x00c0 4e4f 5220 554e 4922 0d0a 636f 6e74 656e NOR.UNI"..conten ...Trace logging for WebSEALThis section describes some of the options available for trace logs for WebSEAL.

pdweb.snoop trace of HTTP traffic with WebSEAL

The pdweb.snoop component traces HTTP traffic. This component logs the HTTP headers and the message body for requests and responses.

Note: The snoop component traces the entire request and response as it is read off the socket. This trace might contain sensitive information.

The pdweb.snoop component has the following subcomponents:

pdweb.snoop.client

Traces data that is sent between WebSEAL and clients.

pdweb.snoop.jct

Traces data that is sent between WebSEAL and junctions.

To trace only the message headers, see pdweb.debug trace of HTTP header requests and responses.

The following example command starts the trace utility for the pdweb.snoop component at level 9 and directs the output to a file:

pdadmin> server task webseald-instance trace set pdweb.snoop 9 \
file path=snoop.out

The following sample output shows the WebSEAL server that is sending 2137 bytes of data to a client at IP address 10.4.5.12:

----------------------------------------
2012-08-10-19:35:18.541+00:00I----- thread(5) trace.pdweb.snoop.client:1
/home/amweb600/src/pdwebrte/webcore/amw_snoop.cpp:159:
----------------------------------------
Thread 2828; fd 22; local 10.4.5.10:443; remote 10.4.5.12:1250
Sending 2137 bytes
0x0000   4854 5450 2f31 2e31 2034 3033 2046 6f72        HTTP/1.1.403.For
0x0010   6269 6464 656e 0d0a 6461 7465 3a20 5475        bidden..date:.We
0x0020   652c 2032 3820 4f63 7420 3230 3033 2031        d,.10.Aug.2005.1
0x0030   393a 3335 3a31 3820 474d 540d 0a73 6572        9:35:18.GMT..ser
0x0040   7665 723a 2057 6562 5345 414c 2f35 2e31        ver:.WebSEAL/5.1
0x0050   2e30 2e30 2028 4275 696c 6420 3033 3130        .0.0.(Build.0310
0x0060   3230 290d 0a63 6163 6865 2d63 6f6e 7472        20)..cache-contr
0x0070   6f6c 3a20 6e6f 2d63 6163 6865 0d0a 7072        ol:.no-cache..pr
0x0080   6167 6d61 3a20 6e6f 2d63 6163 6865 0d0a        agma:.no-cache..
0x0090   636f 6e74 656e 742d 6c65 6e67 7468 3a20        content-length:.
0x00a0   3139 3038 0d0a 7033 703a 2043 503d 224e        1908..p3p:.CP="N
0x00b0   4f4e 2043 5552 204f 5450 6920 4f55 5220        ON.CUR.OTPi.OUR.
0x00c0   4e4f 5220 554e 4922 0d0a 636f 6e74 656e        NOR.UNI"..conten
...

Parent topic: Trace logging for WebSEAL

pdweb.wan.azn trace for transaction authorization decisionspdweb.wan.azn trace for transaction authorization decisionspdweb.wan.azn trace for transaction authorization decisionsThe pdweb.wan.azn component traces authorization decisions for all transactions.pdweb.wan.azntracetransaction authorization decsionstransaction authorizationsThe trace information includes: Credential details upon which the authorization decision is made.The resource that is accessed.The result of the authorization decision.The following sample output is an extract of the trace which is produced from a single authorization decision.Example pdweb.wan.azn output (extract)... 2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:95: [10.251.140.1] Dumping attrlist: creds 2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AUTHENTICATI ON_LEVEL , Value: 1 2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_AUT HNMECH_INFO , Value: LDAP Registry 2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_AUT HZN_ID , Value: cn=Scott Exton,o=ibm,c=au 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_AUT H_METHOD , Value: password 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_BRO WSER_INFO , Value: curl/7.12.1 (i386-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/ 1.2.1.2 libidn/0.5.6 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_IP_ FAMILY , Value: AF_INET 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_MEC H_ID , Value: IV_LDAP_V3.0 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_NET WORK_ADDRESS_BIN , Value: 0x0afb8c01 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_NET WORK_ADDRESS_STR , Value: 10.251.140.1 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_PRI NCIPAL_DOMAIN , Value: Default 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_PRI NCIPAL_NAME , Value: scotte 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_PRI NCIPAL_UUID , Value: ad987b08-cdf4-11db-a51a-000c29e9c358 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_QOP _INFO , Value: SSK: TLSV1: 35 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_REG ISTRY_ID , Value: cn=Scott Exton,o=ibm,c=au 2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_USE R_INFO , Value: 2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_VER SION , Value: 0x00000600 2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:tagvalue_log in_user_name , Value: scotte 2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:tagvalue_ses sion_index , Value: 2c5bfdba-ce05-11db-bba0-000c29e9c358 ... 2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:233: [10.251.140.1] INPUTS - protected_res ource=/WebSEAL/webpi.vwasp.gc.au.ibm.com-default/index.html, operation=r ... 2007-03-09-16:12:35.198+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:254: [10.251.140.1] OUTPUT - permission=0 ... 2007-03-09-16:12:35.198+10:00I----- thread(5) trace.pdweb.wan.azn:8 /project/amwebrte610/b uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:261: [10.251.140.1] CII EXIT amw_azn_decis ion_access_allowed_ext with status=0x00000000 Trace logging for WebSEALThis section describes some of the options available for trace logs for WebSEAL.

pdweb.wan.azn trace for transaction authorization decisions

The pdweb.wan.azn component traces authorization decisions for all transactions.

The trace information includes:

Credential details upon which the authorization decision is made.

The resource that is accessed.

The result of the authorization decision.

The following sample output is an extract of the trace which is produced from a single authorization decision.

Example pdweb.wan.azn output (extract)

...
2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:95: [10.251.140.1] Dumping attrlist: creds
2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AUTHENTICATI
ON_LEVEL , Value: 1

2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_AUT
HNMECH_INFO , Value: LDAP Registry

2007-03-09-16:12:35.195+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_AUT
HZN_ID , Value: cn=Scott Exton,o=ibm,c=au

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_AUT
H_METHOD , Value: password

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_BRO
WSER_INFO , Value: curl/7.12.1 (i386-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/
1.2.1.2 libidn/0.5.6

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_IP_
FAMILY , Value: AF_INET

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_MEC
H_ID , Value: IV_LDAP_V3.0

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_NET
WORK_ADDRESS_BIN , Value: 0x0afb8c01

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_NET
WORK_ADDRESS_STR , Value: 10.251.140.1

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_PRI
NCIPAL_DOMAIN , Value: Default

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_PRI
NCIPAL_NAME , Value: scotte

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_PRI
NCIPAL_UUID , Value: ad987b08-cdf4-11db-a51a-000c29e9c358

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_QOP
_INFO , Value: SSK: TLSV1: 35

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_REG
ISTRY_ID , Value: cn=Scott Exton,o=ibm,c=au

2007-03-09-16:12:35.196+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_USE
R_INFO , Value:

2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:AZN_CRED_VER
SION , Value: 0x00000600

2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:tagvalue_log
in_user_name , Value: scotte

2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:117: [10.251.140.1] Attr Name:tagvalue_ses
sion_index , Value: 2c5bfdba-ce05-11db-bba0-000c29e9c358

...

2007-03-09-16:12:35.197+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:233: [10.251.140.1] INPUTS - protected_res
ource=/WebSEAL/webpi.vwasp.gc.au.ibm.com-default/index.html, operation=r

...

2007-03-09-16:12:35.198+10:00I----- thread(5) trace.pdweb.wan.azn:9 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:254: [10.251.140.1] OUTPUT - permission=0

...

2007-03-09-16:12:35.198+10:00I----- thread(5) trace.pdweb.wan.azn:8 /project/amwebrte610/b
uild/amwebrte610/src/pdwebrte/webcore/amw_azn.c:261: [10.251.140.1] CII EXIT amw_azn_decis
ion_access_allowed_ext with status=0x00000000

Parent topic: Trace logging for WebSEAL

Setting trace for Security Access Manager SPNEGO issuesSetting trace for Security Access Manager SPNEGO issuesSetting trace for Security Access Manager SPNEGO issuesEnable trace for SPNEGO so that you can retrieve more details about WebSEAL issues.SPNEGOtrace logstraceSPNEGOWhen directed by IBM Support, collect the SPNEGO diagnostic data when WebSEAL does not start. Log in to the local management interface.From the top menu, select Secure Web SettingsManageReverse Proxy.Select your reverse proxy.Select ManageConfigurationEdit Tracing Configuration File.Add an entry to the file. Example entry that directs output to the spnegotrace.log file:bst:*.9:TEXTFILE:spnegotrace.logTurn on per-process trace to diagnose WebSEAL start issues:Uncomment the last line by removing the # symbol. #Route to a per-process text file *:*.9:TEXTFILE.10.1000:trace.logStop and restart WebSEAL.Check the output in trace.log. If you start WebSEAL with the pdweb_start command, there are two traces with different pids.Trace logging for WebSEALThis section describes some of the options available for trace logs for WebSEAL.

Setting trace for Security Access Manager SPNEGO issues

Enable trace for SPNEGO so that you can retrieve more details about WebSEAL issues.

About this task

When directed by IBM Support, collect the SPNEGO diagnostic data when WebSEAL does not start.

Procedure

Log in to the local management interface.

From the top menu, select Secure Web Settings > Manage > Reverse Proxy.

Select your reverse proxy.

Select Manage > Configuration > Edit Tracing Configuration File.

Add an entry to the file. Example entry that directs output to the spnegotrace.log file:

bst:*.9:TEXTFILE:spnegotrace.log

Turn on per-process trace to diagnose WebSEAL start issues:

Uncomment the last line by removing the # symbol.

#Route to a per-process text file
*:*.9:TEXTFILE.10.1000:trace.log

Stop and restart WebSEAL.

Check the output in trace.log.

Note: If you start WebSEAL with the pdweb_start command, there are two traces with different pids.

Parent topic: Trace logging for WebSEAL

Available trace componentsAvailable trace componentsAvailable trace componentsThe following table contains all trace components that are common to all Security Access Manager servers:tracecomponentsCommon trace componentsComponentDescriptionpd.bst.generalUsed to trace the Kerberos authentication process. pd.acl.generalThe general trace for the authorization API. pd.acl.clientUsed to trace the plug-in services for the authorization server. pd.acl.authznUsed to trace the authorization decision. pd.acl.adminsvcUsed to trace the interface into the administration service plug-in. pd.acl.remsvcUsed to trace the authorization decision during remote mode operation. pd.acl.aznapiUsed to trace the usage of the Security Access Manager authorization API.pd.acl.aznsvcUsed to trace the plug-in services that are provided by the authorization server. pd.idb.databaseUsed to trace access to the Security Access Manager policy database. pd.ivc.iraThe IRA is the Security Access Manager interface into the LDAP server. This trace component is used to trace the Security Access Manager communication with the LDAP server. pd.mgr.generalUsed to trace the Security Access Managerr administration commands in the Policy Server. pd.mgr.svrmgmtUsed to trace the management of the authorization servers within the policy server.pd.ias.generalUser to trace the Security Access Manager supplied authentication mechanisms, otherwise known as CDASs.pd.ras.exception.traceUsed to trace any exceptions that might be caught by the server.The following table contains all available pdadmin trace components:The pdadmin trace componentsComponentDescriptionpdweb.bca.generalUsed to trace the client side of the Security Access Manager authorization API.pdweb.bca.userUsed to trace the client side of user pdadmin command.pdweb.bca.groupUsed to trace the client side of group pdadmin command.pdweb.bca.aclUsed to trace the client side of acl pdadmin command.pdweb.bca.protobjUsed to trace the client side of object pdadmin command.pdweb.bca.protobjspaceUsed to trace the client side of objectspace pdadmin command.pdweb.bca.appsvrcfgUsed to trace the client side of user config command.pdweb.bca.ssoresourceUsed to trace the client side of user rsrc command.pdweb.bca.ssoresourcegroupUsed to trace the client side of rsrcgroup pdadmin command.pdweb.bca.ssocredUsed to trace the client side of rscrcred pdadmin command.pdweb.bca.actionUsed to trace the client side of action pdadmin command.pdweb.bca.serverUsed to trace the client side of server pdadmin command.pdweb.bca.popUsed to trace the client side of pop pdadmin command.pdweb.bca.domainUsed to trace the client side of domain pdadmin command.pdweb.bca.authzruleUsed to trace the client side of authzrule pdadmin commandThe following table contains all available WebSEAL trace components:The WebSEAL trace componentsComponentDescriptionpdweb.wan.sslUsed to trace the SSL connection between WebSEAL and junctioned web servers. pdweb.wns.sessionUsed to trace the WebSEAL sessions, as they are stored within the session cache and retrieved or removed from the session cache.pdweb.wns.authnUsed to trace the authentication processing. This trace component includes the header information that WebSEAL uses for header-based authentication. This header might contain sensitive information. For example, a BA header. pdweb.adm.configUsed to trace the configuration for e-community SSO.pdweb.wan.boolUsed to trace the WebSEAL processing of Security Access Manager authorization rules. pdweb.wns.compressUsed to trace the WebSEAL compression of HTTP messages. pdweb.cas.generalUsed to trace the interface between WebSEAL and a custom-written CDAS shared library.pdweb.wco.aznUsed to trace the entitlements service, which manages the maximum concurrent web session policy. The policy is used with SMS to limit the number of times a particular user can create a session concurrently.pdweb.debugUsed to trace the HTTP headers sent between WebSEAL and the client. The pdweb.debug trace could contain sensitive information.pdweb.snoop.clientUsed to trace the HTTP packets that are transmitted between WebSEAL and the client.This component traces each request and response in its entirety as it is read off the socket. This trace might contain sensitive information. pdweb.snoop.jctUsed to trace the HTTP packets that are transmitted between WebSEAL and the junctioned back-end web server.This component traces each request and response in its entirety as it is read off the socket. This trace might contain sensitive information. pdweb.urlUsed to trace the creation and parsing of the URL.pdweb.wan.aznUsed to trace the WebSEAL authorization decision. pdweb.wan.ltpaUsed to trace the management of LTPA cookies.pdweb.oauthUsed to trace OAuth EAS authorization decisions.This component traces the data that passes into the EAS, which is governed by the [azn-decision-info] stanza. This trace might contain sensitive information.pdweb.http.transformationUsed to trace HTTP transformation processing.This component traces the header information in the request, which might contain sensitive information. For example, a Basic Authentication header.Trace event logsSecurity Access Manager provides configurable tracing capabilities that can aid in problem determination. Unlike message logs, trace logs (or tracing) are not enabled by default.

Available trace components

The following table contains all trace components that are common to all Security Access Manager servers:

Table 289. Common trace components

Component | Description
pd.bst.general | Used to trace the Kerberos authentication process.
pd.acl.general | The general trace for the authorization API.
pd.acl.client | Used to trace the plug-in services for the authorization server.
pd.acl.authzn | Used to trace the authorization decision.
pd.acl.adminsvc | Used to trace the interface into the administration service plug-in.
pd.acl.remsvc | Used to trace the authorization decision during remote mode operation.
pd.acl.aznapi | Used to trace the usage of the Security Access Manager authorization API.
pd.acl.aznsvc | Used to trace the plug-in services that are provided by the authorization server.
pd.idb.database | Used to trace access to the Security Access Manager policy database.
pd.ivc.ira | The IRA is the Security Access Manager interface into the LDAP server. This trace component is used to trace the Security Access Manager communication with the LDAP server.
pd.mgr.general | Used to trace the Security Access Managerr administration commands in the Policy Server.
pd.mgr.svrmgmt | Used to trace the management of the authorization servers within the policy server.
pd.ias.general | User to trace the Security Access Manager supplied authentication mechanisms, otherwise known as CDASs.
pd.ras.exception.trace | Used to trace any exceptions that might be caught by the server.

The following table contains all available pdadmin trace components:

Table 290. The pdadmin trace components

Component | Description
pdweb.bca.general | Used to trace the client side of the Security Access Manager authorization API.
pdweb.bca.user | Used to trace the client side of user pdadmin command.
pdweb.bca.group | Used to trace the client side of group pdadmin command.
pdweb.bca.acl | Used to trace the client side of acl pdadmin command.
pdweb.bca.protobj | Used to trace the client side of object pdadmin command.
pdweb.bca.protobjspace | Used to trace the client side of objectspace pdadmin command.
pdweb.bca.appsvrcfg | Used to trace the client side of user config command.
pdweb.bca.ssoresource | Used to trace the client side of user rsrc command.
pdweb.bca.ssoresourcegroup | Used to trace the client side of rsrcgroup pdadmin command.
pdweb.bca.ssocred | Used to trace the client side of rscrcred pdadmin command.
pdweb.bca.action | Used to trace the client side of action pdadmin command.
pdweb.bca.server | Used to trace the client side of server pdadmin command.
pdweb.bca.pop | Used to trace the client side of pop pdadmin command.
pdweb.bca.domain | Used to trace the client side of domain pdadmin command.
pdweb.bca.authzrule | Used to trace the client side of authzrule pdadmin command

The following table contains all available WebSEAL trace components:

Table 291. The WebSEAL trace components

Component
Description

pdweb.wan.ssl
Used to trace the SSL connection between WebSEAL and junctioned web servers.

pdweb.wns.session
Used to trace the WebSEAL sessions, as they are stored within the session cache and retrieved or removed from the session cache.

pdweb.wns.authn
Used to trace the authentication processing.

Note: This trace component includes the header information that WebSEAL uses for header-based authentication. This header might contain sensitive information. For example, a BA header.

pdweb.adm.config
Used to trace the configuration for e-community SSO.

pdweb.wan.bool
Used to trace the WebSEAL processing of Security Access Manager authorization rules.

pdweb.wns.compress
Used to trace the WebSEAL compression of HTTP messages.

pdweb.cas.general
Used to trace the interface between WebSEAL and a custom-written CDAS shared library.

pdweb.wco.azn
Used to trace the entitlements service, which manages the maximum concurrent web session policy. The policy is used with SMS to limit the number of times a particular user can create a session concurrently.

pdweb.debug
Used to trace the HTTP headers sent between WebSEAL and the client.

Note: The pdweb.debug trace could contain sensitive information.

pdweb.snoop.client
Used to trace the HTTP packets that are transmitted between WebSEAL and the client.

Note: This component traces each request and response in its entirety as it is read off the socket. This trace might contain sensitive information.

pdweb.snoop.jct
Used to trace the HTTP packets that are transmitted between WebSEAL and the junctioned back-end web server.

Note: This component traces each request and response in its entirety as it is read off the socket. This trace might contain sensitive information.

pdweb.url
Used to trace the creation and parsing of the URL.

pdweb.wan.azn
Used to trace the WebSEAL authorization decision.

pdweb.wan.ltpa
Used to trace the management of LTPA cookies.

pdweb.oauth
Used to trace OAuth EAS authorization decisions.

Note: This component traces the data that passes into the EAS, which is governed by the [azn-decision-info] stanza. This trace might contain sensitive information.

pdweb.http.transformation
Used to trace HTTP transformation processing.

Note: This component traces the header information in the request, which might contain sensitive information. For example, a Basic Authentication header.

Parent topic: Trace event logs

Common Security Access Manager problemsCommon Security Access Manager problemsCommon Security Access Manager problemscommon problemscomponents, allCheck the following information for issues with any of the following Security Access Manager base components: Security Access Manager policy serverSecurity Access Manager authorization serverSecurity Access Manager RuntimeSecurity Access Manager Runtime for JavaTroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Environment information messages in the server log file at startupIn Security Access Manager, the severity level of the startup environment dump information added to the server process log is WARNING. Unable to create new userUnable to authenticate userAfter you create a user, this user cannot authenticate immediately with the new Security Access Manager user identity until the account is modified. Unexpected access to resourcesAccesses to a protected system resource are either being unexpectedly granted or denied. It is always wise to first validate that the Security Access Manager processes are started and running normally. Password change does not work in a multidomain environmentSpecific configuration conditions for policy server, subdomains, and WebSEAL can cause password changes to fail.Product pages might not display in browser if website is not trustedProduct pages might not display in a browser if the website is not trusted. For example, if the administrative console pages for Security Access Manager are empty even though the product is working, the issue might be caused by an untrusted website.Errors occur with in pdjrte startup when Java 2 security is enabledErrors might occur at application startup when Java 2 security is enabled.Network connectivity issues or unresponsive interfacesConfiguring multiple interfaces on the same subnet might cause certain interfaces to appear unresponsive or other network connectivity issues.

Common Security Access Manager problems

Check the following information for issues with any of the following Security Access Manager base components:

Security Access Manager policy server

Security Access Manager authorization server

Security Access Manager Runtime

Security Access Manager Runtime for Java™

Environment information messages in the server log file at startup
In Security Access Manager, the severity level of the startup environment dump information added to the server process log is WARNING.

Unable to create new user

Unable to authenticate user
After you create a user, this user cannot authenticate immediately with the new Security Access Manager user identity until the account is modified.

Unexpected access to resources
Accesses to a protected system resource are either being unexpectedly granted or denied. It is always wise to first validate that the Security Access Manager processes are started and running normally.

Password change does not work in a multidomain environment
Specific configuration conditions for policy server, subdomains, and WebSEAL can cause password changes to fail.

Product pages might not display in browser if website is not trusted
Product pages might not display in a browser if the website is not trusted. For example, if the administrative console pages for Security Access Manager are empty even though the product is working, the issue might be caused by an untrusted website.

Errors occur with in pdjrte startup when Java 2 security is enabled
Errors might occur at application startup when Java 2 security is enabled.

Network connectivity issues or unresponsive interfaces
Configuring multiple interfaces on the same subnet might cause certain interfaces to appear unresponsive or other network connectivity issues.

Parent topic: Troubleshooting

Environment information messages in the server log file at startupEnvironment information messages in the server log file at startupEnvironment information messages in the server log file at startupIn Security Access Manager, the severity level of the startup environment dump information added to the server process log is WARNING. When a Security Access Manager server starts, a series of WARNING messages display information about the environment and AIX, Linux, or Solaris ulimit. These messages are informational. The support team uses these messages to diagnose problems.The following example shows a warning: 2009-08-27-03:54:43.017+00:00I----- 0x1354A0CD pdmgrd WARNING ivc general azn_maint.cpp 4977 0x00000001 HPDCO0205W ------------------------- 2009-08-27-03:54:43.017+00:00I----- 0x1354A0CC pdmgrd WARNING ivc general azn_maint.cpp 4998 0x00000001 HPDCO0204W Informational Message - The environment variable for the running process : _=/opt/PolicyDirector/bin/pdmgrd ... TCD_PRODNAME=HPD MAILMSG=[You have new mail] PDCONFOBF=/opt/PolicyDirector/etc/pd.conf.obf PWD=/ TZ=CST6CDT PD_SVC_ROUTING_FILE=/opt/PolicyDirector/etc/pdmgrd_routing .... 2009-08-27-03:54:43.018+00:00I----- 0x1354A0CD pdmgrd WARNING ivc general azn_maint.cpp 505 0 0x00000001 HPDCO0205W getrlimit(): RLIMIT_DATA (rlim_cur: 134217728 ; rlim_max: 2147483647) 2009-08-27-03:54:43.019+00:00I----- 0x1354A0CD pdmgrd WARNING ivc general azn_maint.cpp 505 0 0x00000001 HPDCO0205W getrlimit(): RLIMIT_STACK (rlim_cur: 33554432 ; rlim_max: 2147483646) 2009-08-27-03:54:43.019+00:00I----- 0x1354A0CD pdmgrd WARNING ivc general azn_maint.cpp 505 0 0x00000001 HPDCO0205W getrlimit(): RLIMIT_AS (rlim_cur: 2147483647 ; rlim_max: 2147483647) 2009-08-27-03:54:43.019+00:00I----- 0x1354A0CD pdmgrd WARNING ivc general azn_maint.cpp 503 1 0x00000001 HPDCO0205W -------------------- ----------------------------Common Security Access Manager problems

Environment information messages in the server log file at startup

In Security Access Manager, the severity level of the startup environment dump information added to the server process log is WARNING.

When a Security Access Manager server starts, a series of WARNING messages display information about the environment and AIX®, Linux, or Solaris ulimit. These messages are informational. The support team uses these messages to diagnose problems.

The following example shows a warning:

2009-08-27-03:54:43.017+00:00I----- 0x1354A0CD pdmgrd WARNING ivc
general azn_maint.cpp 4977 0x00000001 HPDCO0205W  -------------------------
2009-08-27-03:54:43.017+00:00I----- 0x1354A0CC pdmgrd WARNING ivc
general azn_maint.cpp 4998 0x00000001 HPDCO0204W  Informational Message -
The environment variable for the running process :
_=/opt/PolicyDirector/bin/pdmgrd
...
TCD_PRODNAME=HPD
MAILMSG=[You have new mail]
PDCONFOBF=/opt/PolicyDirector/etc/pd.conf.obf
PWD=/
TZ=CST6CDT
PD_SVC_ROUTING_FILE=/opt/PolicyDirector/etc/pdmgrd_routing
....
2009-08-27-03:54:43.018+00:00I-----
0x1354A0CD pdmgrd WARNING ivc general azn_maint.cpp 505
0 0x00000001 HPDCO0205W  getrlimit():
RLIMIT_DATA (rlim_cur: 134217728 ; rlim_max: 2147483647)
2009-08-27-03:54:43.019+00:00I----- 0x1354A0CD
pdmgrd WARNING ivc general azn_maint.cpp 505
0 0x00000001 HPDCO0205W  getrlimit(): RLIMIT_STACK
(rlim_cur: 33554432 ; rlim_max: 2147483646)
2009-08-27-03:54:43.019+00:00I----- 0x1354A0CD
pdmgrd WARNING ivc general azn_maint.cpp 505
0 0x00000001 HPDCO0205W  getrlimit():
RLIMIT_AS (rlim_cur: 2147483647 ; rlim_max: 2147483647)
2009-08-27-03:54:43.019+00:00I-----
0x1354A0CD pdmgrd WARNING ivc general azn_maint.cpp 503
1 0x00000001 HPDCO0205W  --------------------
----------------------------

Parent topic: Common Security Access Manager problems

Unable to create new userUnable to create new userUnable to create new user0x13212131 error error 0x13212131password rejecteduserscreate, unable to userspolicyset userspolicygetpolicy set commandpolicy get commandcommandspolicy getcommandspolicy setOne of the most common error messages that you might see when you create a user is as follows: Could not perform the administration request. Error: Password rejected due to the Minimum Non-Alphabetic Characters policy (status 0x13212131)This error indicates, for example, that the password "abc" that was specified when you attempt to create the user does not comply with one of the user password policies that is defined. To view the help text for the Security Access Manager policy commands, enter the following command: pdadmin> help policy The previous password policy error can be solved by using one of the following solutions: Determine the minimum non-alphabetic character policy with the following command: pdadmin> policy get min-password-non-alphas Using this value, create the user with a password that contains the required minimum number of non-alphabetic characters.Modify the Security Access Manager non-alphabetic character policy before creating the user with the following command: pdadmin> policy set min-password-non-alphas numberCommon Security Access Manager problems

Unable to create new user

One of the most common error messages that you might see when you create a user is as follows:

Could not perform the administration request.
Error: Password rejected due to the Minimum Non-Alphabetic Characters policy
(status 0x13212131)

This error indicates, for example, that the password "abc" that was specified when you attempt to create the user does not comply with one of the user password policies that is defined. To view the help text for the Security Access Manager policy commands, enter the following command:

pdadmin> help policy

The previous password policy error can be solved by using one of the following solutions:

Determine the minimum non-alphabetic character policy with the following command:

pdadmin> policy get min-password-non-alphas

Using this value, create the user with a password that contains the required minimum number of non-alphabetic characters.

Modify the Security Access Manager non-alphabetic character policy before creating the user with the following command:

pdadmin> policy set min-password-non-alphas number

Parent topic: Common Security Access Manager problems

Unable to authenticate userUnable to authenticate userUnable to authenticate userAfter you create a user, this user cannot authenticate immediately with the new Security Access Manager user identity until the account is modified. usersauthenticate, unable to usersenable accountusersmodifyusersshowaccountsenableaccountscreateuser modify commanduser show commandcommandsuser modifycommandsuser show Security Access Manager user definitions are initially created with the account disabled (Account valid = no). This condition is frequently the cause of authentication failures. To modify the account, complete the following steps: Use the user modify command to enable the account:pdadmin> user modify user-name account-valid yesUse the user show command to verify this change:pdadmin> user show user-nameCommon Security Access Manager problems

Unable to authenticate user

After you create a user, this user cannot authenticate immediately with the new Security Access Manager user identity until the account is modified.

About this task

Security Access Manager user definitions are initially created with the account disabled (Account valid = no).

This condition is frequently the cause of authentication failures. To modify the account, complete the following steps:

Use the user modify command to enable the account:

pdadmin> user modify user-name account-valid yes

Use the user show command to verify this change:

pdadmin> user show user-name

Parent topic: Common Security Access Manager problems

Unexpected access to resourcesUnexpected access to resourcesUnexpected access to resourcesAccesses to a protected system resource are either being unexpectedly granted or denied. It is always wise to first validate that the Security Access Manager processes are started and running normally. resourcesunable to accessresourcesobject hierarchyaccess controlgrantaccess controldenyaccess controlobject hierarchyobjectshierarchy, access controlAlso check to ensure that the Security Access Manager message log files do not flag any operational problems. If Security Access Manager seems operationally sound, the problem is likely due to the policies that have been defined and applied to that system resource.There are three Security Access Manager policy mechanisms that can be used to control access to your protected resources: ACLs, POPs, and authorization rules. Use the pdadmin commands to learn which ACL in your protected object space hierarchy has control over the access to the protected resource.Common Security Access Manager problemsACL commandsSecurity Access Manager access control depends on the following conditions: POP commandsA protected object is accessible to a requester if the requester possesses the traverse permission on each ACL attached to container objects above the requested resource on the path towards root and including root.Authorization rule commandsIf an authorization rule is directly attached to the protected object in question, this authorization rule defines the rule policy for that object. If an authorization rule is not directly attached to the protected object in question, the controlling rule is the nearest one that is above it in the protected object hierarchy.

Unexpected access to resources

Accesses to a protected system resource are either being unexpectedly granted or denied. It is always wise to first validate that the Security Access Manager processes are started and running normally.

Also check to ensure that the Security Access Manager message log files do not flag any operational problems. If Security Access Manager seems operationally sound, the problem is likely due to the policies that have been defined and applied to that system resource.

There are three Security Access Manager policy mechanisms that can be used to control access to your protected resources: ACLs, POPs, and authorization rules. Use the pdadmin commands to learn which ACL in your protected object space hierarchy has control over the access to the protected resource.

ACL commands
Security Access Manager access control depends on the following conditions:

POP commands
A protected object is accessible to a requester if the requester possesses the traverse permission on each ACL attached to container objects above the requested resource on the path towards root and including root.

Authorization rule commands
If an authorization rule is directly attached to the protected object in question, this authorization rule defines the rule policy for that object. If an authorization rule is not directly attached to the protected object in question, the controlling rule is the nearest one that is above it in the protected object hierarchy.

Parent topic: Common Security Access Manager problems

ACL commandsACL commandsACL commandsSecurity Access Manager access control depends on the following conditions: access controlpolicy commandsACL ACLsaccess control policytraverse (T) permissionpermissions, traverse (T)commandsacl listcommandsacl findACLsfindcommandsacl showACLsshowThe ACL that controls the requested object must contain appropriate access permissions for the requesting user.The requested object must be accessible to the requesting user. Accessibility to protected objects is controlled by the traverse (T) permission. The traverse permission is only applied to container objects in the protected object space. The traverse permission specifies that a user, group, any-other, or unauthenticated user, that is identified in the ACL entry, has permission to pass through this container object to gain access to a protected resource object that is below it in the hierarchy.If an ACL is directly attached to the protected object, this ACL defines the ACL policy for that object. If an ACL is not directly attached to the protected object, the controlling ACL is the nearest one that is above it in the protected object hierarchy. Listing ACLsLists all ACLs that are defined in Security Access Manager: padmin> acl listFinding ACLsDisplays where each of those ACLs is attached within the protected object space hierarchy:pdadmin> acl find acl_nameShowing ACLsExamines the controlling ACL to check that it is correct for the type of enforcement wanted: pdadmin> acl show acl_nameCorrect the ACL definition if needed.Unexpected access to resourcesAccesses to a protected system resource are either being unexpectedly granted or denied. It is always wise to first validate that the Security Access Manager processes are started and running normally.

ACL commands

Security Access Manager access control depends on the following conditions:

The ACL that controls the requested object must contain appropriate access permissions for the requesting user.

The requested object must be accessible to the requesting user.

Accessibility to protected objects is controlled by the traverse (T) permission. The traverse permission is only applied to container objects in the protected object space. The traverse permission specifies that a user, group, any-other, or unauthenticated user, that is identified in the ACL entry, has permission to pass through this container object to gain access to a protected resource object that is below it in the hierarchy.

If an ACL is directly attached to the protected object, this ACL defines the ACL policy for that object. If an ACL is not directly attached to the protected object, the controlling ACL is the nearest one that is above it in the protected object hierarchy.

Listing ACLs

Lists all ACLs that are defined in Security Access Manager:

padmin> acl list

Finding ACLs

Displays where each of those ACLs is attached within the protected object space hierarchy:

pdadmin> acl find acl_name

Showing ACLs

Examines the controlling ACL to check that it is correct for the type of enforcement wanted:

pdadmin> acl show acl_name

Correct the ACL definition if needed.

Parent topic: Unexpected access to resources

POP commandsPOP commandsPOP commandsA protected object is accessible to a requester if the requester possesses the traverse permission on each ACL attached to container objects above the requested resource on the path towards root and including root.access controlpolicy commandsPOP POP commandsaccess control policycommandspop listPOP commandslistcommandspop findPOP commandsfindcommandspop showPOP commandsshowAdditionally, use the pdadmin command to learn which POP (if any) within your protected object space hierarchy controls access to the protected resource in question.If a POP is directly attached to the protected object in question, this POP defines the POP policy for that object. If a POP is not directly attached to the protected object in question, the controlling POP is the nearest one that is above it in the protected object hierarchy. Listing POPsThe following command lists all of the POPs which are defined for Security Access Manager: padmin> pop listFinding POPs The following command enables you to learn where a particular POP is attached within the protected object space hierarchy: pdadmin> pop find pop_nameShowing POPsExamine the controlling POP with the following command to ensure that it is correct for the type of enforcement desired: pdadmin> pop show pop_name Correct the POP definition if needed.Unexpected access to resourcesAccesses to a protected system resource are either being unexpectedly granted or denied. It is always wise to first validate that the Security Access Manager processes are started and running normally.

POP commands

A protected object is accessible to a requester if the requester possesses the traverse permission on each ACL attached to container objects above the requested resource on the path towards root and including root.

Additionally, use the pdadmin command to learn which POP (if any) within your protected object space hierarchy controls access to the protected resource in question.

If a POP is directly attached to the protected object in question, this POP defines the POP policy for that object. If a POP is not directly attached to the protected object in question, the controlling POP is the nearest one that is above it in the protected object hierarchy.

Listing POPs

The following command lists all of the POPs which are defined for Security Access Manager:

padmin> pop list

Finding POPs

The following command enables you to learn where a particular POP is attached within the protected object space hierarchy:

pdadmin> pop find pop_name

Showing POPs

Examine the controlling POP with the following command to ensure that it is correct for the type of enforcement desired:

pdadmin> pop show pop_name

Correct the POP definition if needed.

Parent topic: Unexpected access to resources

Authorization rule commandsAuthorization rule commandsAuthorization rule commandsIf an authorization rule is directly attached to the protected object in question, this authorization rule defines the rule policy for that object. If an authorization rule is not directly attached to the protected object in question, the controlling rule is the nearest one that is above it in the protected object hierarchy.access controlpolicy commandsauthorization rule authorization rulesaccess control policycommandsauthzrule listauthzrule commandlist authorization ruleslistcommandsauthzrule findauthzrule commandfind authorization rulesfindcommandsauthzrule showauthzrule commandshow Listing rulesThe following command lists all of the authorization rules defined for Security Access Manager: padmin> authzrule list Finding rulesThe following command enables you to learn where a particular authorization rule is attached within the protected object space hierarchy: pdadmin> authzrule find authznrule_nameShowing rulesUse the following command to examine the controlling authorization rule and to ensure that it is correct for the type of enforcement required: pdadmin> authzrule show authznrule_nameCorrect the rule definition if needed.Unexpected access to resourcesAccesses to a protected system resource are either being unexpectedly granted or denied. It is always wise to first validate that the Security Access Manager processes are started and running normally.

Authorization rule commands

If an authorization rule is directly attached to the protected object in question, this authorization rule defines the rule policy for that object. If an authorization rule is not directly attached to the protected object in question, the controlling rule is the nearest one that is above it in the protected object hierarchy.

Listing rules

The following command lists all of the authorization rules defined for Security Access Manager:

padmin> authzrule list

Finding rules

The following command enables you to learn where a particular authorization rule is attached within the protected object space hierarchy:

pdadmin> authzrule find authznrule_name

Showing rules

Use the following command to examine the controlling authorization rule and to ensure that it is correct for the type of enforcement required:

pdadmin> authzrule show authznrule_name

Correct the rule definition if needed.

Parent topic: Unexpected access to resources

Password change does not work in a multidomain environmentPassword change does not work in a multidomain environmentPassword change does not work in a multidomain environmentSpecific configuration conditions for policy server, subdomains, and WebSEAL can cause password changes to fail.management domains password changesA WebSEAL instance cannot change user passwords under all the following conditions because of the absence of ACL settings that are required to search domain locations: You configured the policy server in a nondefault location that is a location other than secAuthority=Default.You create Security Access Manager subdomains under the new location.You configured a WebSEAL instance in any of the new subdomains.Complete the following steps to set the correct ACL with the following assumptions: The management domain name is Default.The Default domain is in an LDAP suffix that is called O=IBM,C=US.The subdomain names are Domain1, Domain2, and so on. Place the following in a file called aclEntry.ldif:##------ START: Do not include this line -----## dn: secAuthority=Default,o=ibm,c=us changetype: modifyI add: aclentry aclentry:group:cn=SecurityGroup,SecAuthority=Domain1,cn=SubDomains,SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad:normal:rwsc:sensitive:rwsc:critical:rwsc:system:rsc aclentry:group:cn=SecurityGroup,SecAuthority=Domain2,cn=SubDomains, SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad :normal:rwsc:sensitive:rwsc:critical:rwsc:system:rsc ##------ END: Do not include this line -------##You must replace the management domain name Default, suffix O=IBM,C=US, and subdomains Domain1, Domain2, and so on, with the corresponding name of the current installation.Update the ACL by running the following command:ldapmodify -h host -p port -D cn=root -w pwd -i aclEntry.ldifCommon Security Access Manager problems

Password change does not work in a multidomain environment

Specific configuration conditions for policy server, subdomains, and WebSEAL can cause password changes to fail.

About this task

A WebSEAL instance cannot change user passwords under all the following conditions because of the absence of ACL settings that are required to search domain locations:

You configured the policy server in a nondefault location that is a location other than secAuthority=Default.

You create Security Access Manager subdomains under the new location.

You configured a WebSEAL instance in any of the new subdomains.

Complete the following steps to set the correct ACL with the following assumptions:

The management domain name is Default.

The Default domain is in an LDAP suffix that is called O=IBM,C=US.

The subdomain names are Domain1, Domain2, and so on.

Place the following in a file called aclEntry.ldif:
##------ START: Do not include this line -----##
dn: secAuthority=Default,o=ibm,c=us
changetype: modifyI
add: aclentry
aclentry:group:cn=SecurityGroup,SecAuthority=Domain1,cn=SubDomains
,SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad:normal
:rwsc:sensitive:rwsc:critical:rwsc:system:rsc aclentry:group:cn=SecurityGroup,SecAuthority=Domain2,cn=SubDomains, SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad :normal:rwsc:sensitive:rwsc:critical:rwsc:system:rsc
##------ END: Do not include this line -------##

You must replace the management domain name Default, suffix O=IBM,C=US, and subdomains Domain1, Domain2, and so on, with the corresponding name of the current installation.

Update the ACL by running the following command:ldapmodify -h host -p port -D cn=root -w pwd -i aclEntry.ldif

Parent topic: Common Security Access Manager problems

Product pages might not display in browser if website is not trustedProduct pages might not display in browser if website is not trustedProduct pages might not display in browser if website is not trustedProduct pages might not display in a browser if the website is not trusted. For example, if the administrative console pages for Security Access Manager are empty even though the product is working, the issue might be caused by an untrusted website.cannot view pagesTo resolve this issue, add the product website to the list of trusted websites in the security settings of your browser.For example, if your URL to access Web Portal Manager is http://wpm14.example.com:9060/ibm/console, add the website to your list of trusted websites in the security settings of your browser.Common Security Access Manager problems

Product pages might not display in browser if website is not trusted

Product pages might not display in a browser if the website is not trusted. For example, if the administrative console pages for Security Access Manager are empty even though the product is working, the issue might be caused by an untrusted website.

To resolve this issue, add the product website to the list of trusted websites in the security settings of your browser.

For example, if your URL to access Web Portal Manager is http://wpm14.example.com:9060/ibm/console, add the website to your list of trusted websites in the security settings of your browser.

Parent topic: Common Security Access Manager problems

Errors occur with in pdjrte startup when Java 2 security is enabledpdjrte startup errorErrors might occur at application startup when Java 2 security is enabled.pdjrtestartup errorOn startup, Security Access Manager for Java ensures that the JVM is properly configured for refreshing certificate expirations. If Java 2 security is enabled, invoke some security methods with privileged security enabled.A workaround is update either the JVM java.policy file or the was.policy file for a WebSphere Application Server with the following entries:permission java.security.SecurityPermission "insertProvider.IBMJCE"; permission java.security.SecurityPermission "putProviderProperty.IBMJCE";Common Security Access Manager problems

Errors occur with in pdjrte startup when Java 2 security is enabled

Errors might occur at application startup when Java 2 security is enabled.

On startup, Security Access Manager for Java ensures that the JVM is properly configured for refreshing certificate expirations. If Java 2 security is enabled, invoke some security methods with privileged security enabled.

A workaround is update either the JVM java.policy file or the was.policy file for a WebSphere Application Server with the following entries:

permission java.security.SecurityPermission "insertProvider.IBMJCE";
permission java.security.SecurityPermission "putProviderProperty.IBMJCE";

Parent topic: Common Security Access Manager problems

Network connectivity issues or unresponsive interfaces Configuring multiple interfaces on the same subnet might cause certain interfaces to appear unresponsive or other network connectivity issues.When you configure interfaces on an 8.0.0.x appliance, it is advisable to not configure IP addresses that in the same subnet across multiple interfaces. Starting from the 8.0.1.1 release, by default the appliance validates that overlapping subnets do not span multiple interfaces. But such validation can be manually overridden if you choose to do so. Having a single subnet that spans multiple interfaces is discouraged in general networking terms. The appliance environment is no exception to this rule. Configuring the same subnet on multiple interfaces causes the routing table to contain duplicate routes, one for each interface.Diagnosing the problem If some interfaces seem to become unresponsive or when the packet trace seems to capture traffic only on one side, you might consider this problem.Resolving the problem Preferred method The preferred way to rectify this problem is to configure different interfaces to be in different subnets. For example, changing the P.1 interface to a different subnet such as 192.168.150.250 / 24 creates distinct routing table entries. Alternate method This approach is not advisable if the appliance is being installed in the DMZ. Since the management interface and any reverse proxy instances have the same IP address, management services might possibly be exposed to the public. Starting with IBM Security Access Manager 8.0.0.5, reverse proxy instances can listen on all interfaces and do not need to be tied to a specific application interface. Therefore, it is no longer mandatory to configure application interfaces on the appliance. During configuration of a new reverse proxy instance, specifying 0.0.0.0 for the IP address of the primary interface ensures that the new instance listens on all the interfaces, including the management interface M.1. For existing reverse proxy instances, the primary interface can be changed by selecting the instance, clicking Edit, and then modifying the values on the Server tab. When you change the network interface on which an existing reverse proxy instance is listening, ensure that no other services are listening on the ports that are specified under HTTPS Port and HTTP Port. Otherwise, the reverse proxy instance might fail to start. By default, ports 80 and 443 on the management interface are used by the local management interface. If a reverse proxy instance needs to listen on those ports, you can change the default port values that are used by the local management interface through the Administrator Settings panel. Common Security Access Manager problems

Network connectivity issues or unresponsive interfaces

Configuring multiple interfaces on the same subnet might cause certain interfaces to appear unresponsive or other network connectivity issues.

When you configure interfaces on an 8.0.0.x appliance, it is advisable to not configure IP addresses that in the same subnet across multiple interfaces. Starting from the 8.0.1.1 release, by default the appliance validates that overlapping subnets do not span multiple interfaces. But such validation can be manually overridden if you choose to do so.

Having a single subnet that spans multiple interfaces is discouraged in general networking terms. The appliance environment is no exception to this rule. Configuring the same subnet on multiple interfaces causes the routing table to contain duplicate routes, one for each interface.

Diagnosing the problem

If some interfaces seem to become unresponsive or when the packet trace seems to capture traffic only on one side, you might consider this problem.

Resolving the problem

Preferred method

The preferred way to rectify this problem is to configure different interfaces to be in different subnets. For example, changing the P.1 interface to a different subnet such as 192.168.150.250 / 24 creates distinct routing table entries.

Alternate method

Note: This approach is not advisable if the appliance is being installed in the DMZ. Since the management interface and any reverse proxy instances have the same IP address, management services might possibly be exposed to the public.

Starting with IBM Security Access Manager 8.0.0.5, reverse proxy instances can listen on all interfaces and do not need to be tied to a specific application interface. Therefore, it is no longer mandatory to configure application interfaces on the appliance.

During configuration of a new reverse proxy instance, specifying 0.0.0.0 for the IP address of the primary interface ensures that the new instance listens on all the interfaces, including the management interface M.1.

For existing reverse proxy instances, the primary interface can be changed by selecting the instance, clicking Edit, and then modifying the values on the Server tab.

Note: When you change the network interface on which an existing reverse proxy instance is listening, ensure that no other services are listening on the ports that are specified under HTTPS Port and HTTP Port. Otherwise, the reverse proxy instance might fail to start.

By default, ports 80 and 443 on the management interface are used by the local management interface. If a reverse proxy instance needs to listen on those ports, you can change the default port values that are used by the local management interface through the Administrator Settings panel.

Parent topic: Common Security Access Manager problems

Common user registry problemsCommon user registry problemsCommon user registry problemsThis chapter details common user registry or directory server problems that you might encounter when you use Security Access Manager.common problemsuser registriesuser registriescommon problemsTroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Security Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.Active Directory common problemsThis section details common problems that you might encounter when you use Active Directory as the user registry.

Common user registry problems

This chapter details common user registry or directory server problems that you might encounter when you use Security Access Manager.

Security Directory Server common problems
This section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.

Active Directory common problems
This section details common problems that you might encounter when you use Active Directory as the user registry.

Parent topic: Troubleshooting

Security Directory Server common problemsSecurity Directory Server common problemsSecurity Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.Security Directory Servercommon problemscommon problemsTivoli Directory ServerCommon user registry problemsThis chapter details common user registry or directory server problems that you might encounter when you use Security Access Manager.Location of error logsWhen a problem occurs that seems to be related to Security Directory Server, check for error messages that are related to that product. Security Directory Server error log warningsSecurity Directory Server error log indicates several does not exist warnings.Security Directory Server Instance Administration tool does not display instance on Red Hat Enterprise Linux 6After you install Security Directory Server with the installation wizard typical installation path, the default instance is created. However, on Red Hat Linux, version 6, the Instance Administration tool started at the end of installation does not display the instance.Setting up SSLFor information about configuring IBM Directory Server to use SSL communication, see the IBM Knowledge Center.LDAP common problemsThis section details common problems that you might encounter when you use an LDAP-based user registry, such as Security Directory Server.

Security Directory Server common problems

This section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.

Location of error logs
When a problem occurs that seems to be related to Security Directory Server, check for error messages that are related to that product.

Security Directory Server error log warnings
Security Directory Server error log indicates several "does not exist" warnings.

Security Directory Server Instance Administration tool does not display instance on Red Hat Enterprise Linux 6
After you install Security Directory Server with the installation wizard typical installation path, the default instance is created. However, on Red Hat Linux, version 6, the Instance Administration tool started at the end of installation does not display the instance.

Setting up SSL
For information about configuring IBM Directory Server to use SSL communication, see the IBM Knowledge Center.

LDAP common problems
This section details common problems that you might encounter when you use an LDAP-based user registry, such as Security Directory Server.

Parent topic: Common user registry problems

Location of error logsLocation of error logsLocation of error logsWhen a problem occurs that seems to be related to Security Directory Server, check for error messages that are related to that product. Security Directory Servererror logsYou can find locations of Security Directory Server log files in the Knowledge Center for your version of the product.Security Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.

Location of error logs

When a problem occurs that seems to be related to Security Directory Server, check for error messages that are related to that product.

You can find locations of Security Directory Server log files in the Knowledge Center for your version of the product.

Parent topic: Security Directory Server common problems

Security Directory Server error log warningsSecurity Directory Server error log warningsSecurity Directory Server error log warningsSecurity Directory Server error log indicates several does not exist warnings.Security Directory Servererror log warningswarningsSecurity Directory Server error logWhen the policy server is configured, the policy server is first unconfigured as part of this configuration process to ensure that it was cleaned up completely.The unconfiguration step attempts to remove entries in the directory server.When the policy server configuration is not yet completed, these entries are not yet created and might not exist in the LDAP registry. The Security Directory Server logs these entry removal attempts as warnings in its error log. These warnings are therefore normal and can be safely ignored.Security Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.

Security Directory Server error log warnings

Security Directory Server error log indicates several "does not exist" warnings.

When the policy server is configured, the policy server is first unconfigured as part of this configuration process to ensure that it was cleaned up completely.

The unconfiguration step attempts to remove entries in the directory server.

When the policy server configuration is not yet completed, these entries are not yet created and might not exist in the LDAP registry. The Security Directory Server logs these entry removal attempts as warnings in its error log. These warnings are therefore normal and can be safely ignored.

Parent topic: Security Directory Server common problems

Security Directory Server Instance Administration tool does not display instance on Red Hat Enterprise Linux 6Security Directory Server Instance Administration tool does not display default instance on Red Hat Enterprise Linux 6Security Directory Server Instance Administration tool does not display default instance on Red Hat Enterprise Linux 6After you install Security Directory Server with the installation wizard typical installation path, the default instance is created. However, on Red Hat Linux, version 6, the Instance Administration tool started at the end of installation does not display the instance.Security Directory Serverinstance does not displayTo verify that the default instance is listed in the configuration, use the idsilist command. By default, this command is in the /opt/ibm/ldap/V6.3/sbin/ directory. For details about the command, see the IBM Security Directory Server, product documentation.Although the instance does not display in the UI, you can follow the command-line tool configuration steps as documented in the ADK Installation topics in the Knowledge Center.To use an instance other than the default instance that is created by the Security Directory Server installer, use command-line tools to create and configure a non-default instance. See the Security Directory Server documentation for more information.Security Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.

Security Directory Server Instance Administration tool does not display instance on Red Hat Enterprise Linux 6

After you install Security Directory Server with the installation wizard typical installation path, the default instance is created. However, on Red Hat Linux, version 6, the Instance Administration tool started at the end of installation does not display the instance.

To verify that the default instance is listed in the configuration, use the idsilist command. By default, this command is in the /opt/ibm/ldap/V6.3/sbin/ directory. For details about the command, see the IBM Security Directory Server, product documentation.

Although the instance does not display in the UI, you can follow the command-line tool configuration steps as documented in the ADK Installation topics in the Knowledge Center.

To use an instance other than the default instance that is created by the Security Directory Server installer, use command-line tools to create and configure a non-default instance. See the Security Directory Server documentation for more information.

Parent topic: Security Directory Server common problems

Setting up SSLSetting up SSLSetting up SSLFor information about configuring IBM Directory Server to use SSL communication, see the IBM Knowledge Center.Go to the following URL: http://www-01.ibm.com/support/knowledgecenter/SSVJJU/welcomeSecurity Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.

Setting up SSL

For information about configuring IBM Directory Server to use SSL communication, see the IBM Knowledge Center.

Go to the following URL: http://www-01.ibm.com/support/knowledgecenter/SSVJJU/welcome

Parent topic: Security Directory Server common problems

LDAP common problemsLDAP common problemsLDAP common problemsThis section details common problems that you might encounter when you use an LDAP-based user registry, such as Security Directory Server. common problemsLDAP serverLDAP servercommon problems For common problems that are specific to Security Directory Server, see Security Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry..Security Directory Server common problemsThis section details common problems that you might encounter when you use IBM Security Directory Server as the user registry.LDAP does not start after suffix is createdAfter you create the secAuthority=Default suffix Security Directory Server does not start.Insufficient privileges to perform operations

LDAP common problems

This section details common problems that you might encounter when you use an LDAP-based user registry, such as Security Directory Server.

About this task

For common problems that are specific to Security Directory Server, see Security Directory Server common problems.

LDAP does not start after suffix is created
After you create the secAuthority=Default suffix Security Directory Server does not start.

Insufficient privileges to perform operations

Parent topic: Security Directory Server common problems

LDAP does not start after suffix is createdLDAP does not start after suffix is createdLDAP does not start after suffix is createdAfter you create the secAuthority=Default suffix Security Directory Server does not start.secAuthority=Default suffixunable to start LDAP serverLDAP serverunable to startLDAP serversecAuthority=Default suffixLDAP serverslapd.errors fileslapd.errors filefilesslapd.errorsThe following steps are required to prepare an LDAP server for use with Security Access Manager. These steps must be completed before you configure Security Access Manager: Create the secAuthority=Default suffix.Stop and restart the Security Directory Server to enable the server to recognize the newly created suffixWhen command-line installation is used, these steps must be completed manually.If the user attempts to create the secAuthority=Default suffix and restart Security Directory Server before you apply the schema modifications that are required by Security Access Manager, Security Directory Server fails to restart.When the server fails to restart it logs an error message to the slapd.errors file. This message indicates that the secAuthority attribute is not defined. The slapd.errors file is in the /tmp directory on AIX, Linux, and Solaris operating systems and in the ldap_install_dir\tmp directory on Windows operating systems, where ldap_install_dir is the directory where Security Directory Server was installed.LDAP common problemsThis section details common problems that you might encounter when you use an LDAP-based user registry, such as Security Directory Server.

LDAP does not start after suffix is created

After you create the secAuthority=Default suffix Security Directory Server does not start.

The following steps are required to prepare an LDAP server for use with Security Access Manager. These steps must be completed before you configure Security Access Manager:

Create the secAuthority=Default suffix.

Stop and restart the Security Directory Server to enable the server to recognize the newly created suffix

When command-line installation is used, these steps must be completed manually.

If the user attempts to create the secAuthority=Default suffix and restart Security Directory Server before you apply the schema modifications that are required by Security Access Manager, Security Directory Server fails to restart.

When the server fails to restart it logs an error message to the slapd.errors file. This message indicates that the secAuthority attribute is not defined. The slapd.errors file is in the /tmp directory on AIX, Linux, and Solaris operating systems and in the ldap_install_dir\tmp directory on Windows operating systems, where ldap_install_dir is the directory where Security Directory Server was installed.

Parent topic: LDAP common problems

Insufficient privileges to perform operationsInsufficient privileges to perform operationsInsufficient privileges to perform operationsLDAP serverinsufficient privilegesmessagesinsufficient LDAP privilegesYou are receiving the following error: Insufficient LDAP access privileges to perform operation.This message indicates that a supplied LDAP suffix does not have the correct ACLs attached. The following reasons are possible causes for this problem: During configuration, Security Access Manager was unable to attach ACLs to the existing suffix because the directory entries necessary to instantiate the suffix were not created.The suffix was added after the initial configuration of the Security Access Manager management server and the required ACLs were not added manually.The Web Administration Tool provided with the Security Directory Server client can be used to check the suffix and to add the appropriate ACLs manually. For information about how to accomplish this, see the Administering topics in the Knowledge Center. Correct the ACLs on the suffix, and run the command again.LDAP common problemsThis section details common problems that you might encounter when you use an LDAP-based user registry, such as Security Directory Server.

Insufficient privileges to perform operations

You are receiving the following error:

Insufficient LDAP access privileges to perform operation.

This message indicates that a supplied LDAP suffix does not have the correct ACLs attached. The following reasons are possible causes for this problem:

During configuration, Security Access Manager was unable to attach ACLs to the existing suffix because the directory entries necessary to instantiate the suffix were not created.

The suffix was added after the initial configuration of the Security Access Manager management server and the required ACLs were not added manually.

The Web Administration Tool provided with the Security Directory Server client can be used to check the suffix and to add the appropriate ACLs manually. For information about how to accomplish this, see the Administering topics in the Knowledge Center.

Correct the ACLs on the suffix, and run the command again.

Parent topic: LDAP common problems

Active Directory common problemsActive Directory common problemsActive Directory common problemsThis section details common problems that you might encounter when you use Active Directory as the user registry.common problemsActive DirectoryActive Directorycommon problemsCommon user registry problemsThis chapter details common user registry or directory server problems that you might encounter when you use Security Access Manager.Receiving HPDRG0100E for Active Directory operationsReceiving HPDRG0101E The user password violates the Active Directory user password policies

Active Directory common problems

This section details common problems that you might encounter when you use Active Directory as the user registry.

Receiving HPDRG0100E for Active Directory operations

Receiving HPDRG0101E The user password violates the Active Directory user password policies

Parent topic: Common user registry problems

Receiving HPDRG0100E for Active Directory operationsActive DirectoryHPDRG0100E messageHPDRG0100EmessagesHPDRG0100EDuring Security Access Manager configuration, you might receive the following HPDRG0100E error message: HPDRG0100E The operation in the Active Directory registry for operation_id failed with return error nnnnnnnn.This message is issued when an Active Directory error cannot be resolved during configuration.Use the following problem determination suggestions to resolve this error before you restart configuration. An error message HPDRG0100E that is similar to the following content refers to a schema write failure: HPDRG0100E The operation in the Active Directory registry for adschema_update.exe: ADSCHEMA_SET_SCHEMA_WRITE failed with return error 35.For this case, ensure that the Remote Registry Windows service is running on the root Active Directory domain controller system. During configuration, the Active Directory schema is updated, which requires the Remote Registry Windows service to be running. If the service is not running, start the service and complete configuration. You can stop the service after the configuration is finished.If the HPDRG0100E error message contains an 8-digit return code that begins with 8007, use the Microsoft net helpmsg command to display relevant help text. Convert the last four digits (digits that are nnnn of the return code of the form 8007nnnn) from hexadecimal format to decimal format and issue the command by using decimal format for the last four digits of the return code: net helpmsg nnnnPursue the problem with Microsoft support by using the Active Directory return code value provided in the HPDRG0100E error message.After you resolve the cause of this error, you can restart the configuration operation.Active Directory common problemsThis section details common problems that you might encounter when you use Active Directory as the user registry.

Receiving HPDRG0100E for Active Directory operations

During Security Access Manager configuration, you might receive the following HPDRG0100E error message:

HPDRG0100E The operation in the Active Directory registry for operation_id failed with return error nnnnnnnn.

This message is issued when an Active Directory error cannot be resolved during configuration.

Use the following problem determination suggestions to resolve this error before you restart configuration.

An error message HPDRG0100E that is similar to the following content refers to a schema write failure:

HPDRG0100E The operation in the Active Directory registry for adschema_update.exe: ADSCHEMA_SET_SCHEMA_WRITE failed with return error 35.

For this case, ensure that the Remote Registry Windows service is running on the root Active Directory domain controller system. During configuration, the Active Directory schema is updated, which requires the Remote Registry Windows service to be running. If the service is not running, start the service and complete configuration. You can stop the service after the configuration is finished.

If the HPDRG0100E error message contains an 8-digit return code that begins with 8007, use the Microsoft net helpmsg command to display relevant help text. Convert the last four digits (digits that are nnnn of the return code of the form 8007nnnn) from hexadecimal format to decimal format and issue the command by using decimal format for the last four digits of the return code:

net helpmsg nnnn

Pursue the problem with Microsoft support by using the Active Directory return code value provided in the HPDRG0100E error message.

After you resolve the cause of this error, you can restart the configuration operation.

Parent topic: Active Directory common problems

Receiving HPDRG0101E The user password violates the Active Directory user password policiesActive DirectoryHPDRG0101E messageActive Directorypassword policyHPDRG0101EmessagesHPDRG0101Epassword policy, Active DirectoryThe Security Access Manager HPDRG0101E error message can occur during Security Access Manager configuration or during password change operations. This error can occur even if the Active Directory Domain account password policy "Password must meet complexity requirements" is set to "Disabled."To resolve this error, ensure that the password meets the requirements of the Microsoft account password complexity policy. To learn more about Microsoft account password complexity policy, search the Microsoft knowledge base. Active Directory common problemsThis section details common problems that you might encounter when you use Active Directory as the user registry.

Receiving HPDRG0101E The user password violates the Active Directory user password policies

The Security Access Manager HPDRG0101E error message can occur during Security Access Manager configuration or during password change operations. This error can occur even if the Active Directory Domain account password policy "Password must meet complexity requirements" is set to "Disabled."

To resolve this error, ensure that the password meets the requirements of the Microsoft account password complexity policy. To learn more about Microsoft account password complexity policy, search the Microsoft knowledge base.

Parent topic: Active Directory common problems

Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGOSingle sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGOSingle sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGOUse the following information to troubleshoot and resolve single sign-on issues that involve Windows Desktop single sign-on, Kerberos, and SPNEGO.Single sign-on, common problemscommon problemsDesktop single sign-oncommon problemsKerberoscommon problemsSPNEGOSimple and Protected Negotiation (SPNEGO)SPNEGOsingle sign-on issueKerberosWindows Desktop single sign-on, on the client end, uses the Simple and Protected GSS-API Negotiation (SPNEGO) authentication protocol over HTTP to authenticate with WebSEAL.SPNEGO authentication works by wrapping a Kerberos authentication token, obtained by the windows Desktop browser, and sending it in an HTTP header to the target web server without the need for user action. The user signs on to their Windows Desktop, and the browser can use the sign on to send the Kerberos token by means of SPNEGO to the web server for single sign-on, assuming the Web Server can handle SPNEGO or Kerberos.WebSEAL on AIX, Linux, or Solaris use Kerberos to validate SPNEGO authentication data.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Problems with SPNEGOUse the following troubleshooting tips for issues that involve SPNEGO authentication.Problems with KerberosThe following information can assist you when troubleshooting issues that concern Kerberos authentication.Unable to authenticate

Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGO

Use the following information to troubleshoot and resolve single sign-on issues that involve Windows Desktop single sign-on, Kerberos, and SPNEGO.

Windows Desktop single sign-on, on the client end, uses the Simple and Protected GSS-API Negotiation (SPNEGO) authentication protocol over HTTP to authenticate with WebSEAL.

SPNEGO authentication works by wrapping a Kerberos authentication token, obtained by the windows Desktop browser, and sending it in an HTTP header to the target web server without the need for user action. The user signs on to their Windows Desktop, and the browser can use the sign on to send the Kerberos token by means of SPNEGO to the web server for single sign-on, assuming the Web Server can handle SPNEGO or Kerberos.

WebSEAL on AIX®, Linux, or Solaris use Kerberos to validate SPNEGO authentication data.

Problems with SPNEGO
Use the following troubleshooting tips for issues that involve SPNEGO authentication.

Problems with Kerberos
The following information can assist you when troubleshooting issues that concern Kerberos authentication.

Unable to authenticate

Parent topic: Troubleshooting

Problems with SPNEGOProblems with SPNEGOProblems with SPNEGOUse the following troubleshooting tips for issues that involve SPNEGO authentication.SPNEGO common problemsSingle sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGOUse the following information to troubleshoot and resolve single sign-on issues that involve Windows Desktop single sign-on, Kerberos, and SPNEGO.Web security server not startingAlgorithm to resolve host names

Problems with SPNEGO

Use the following troubleshooting tips for issues that involve SPNEGO authentication.

Web security server not starting

Algorithm to resolve host names

Parent topic: Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGO

Web security server not startingThe following information describes debugging SPNEGO configuration problems with WebSEAL configuration where one of the Web security servers does not start. If the WebSEAL server fails to start, the server log file for that server contains messages that describe the problem.Problems with SPNEGOUse the following troubleshooting tips for issues that involve SPNEGO authentication.Collecting data for Security Access Manager: WebSEAL (SPNEGO issues)When WebSEAL does not start because of a SPNEGO issue, you might need to collect data for problem determination.No match to principal in key table

Web security server not starting

The following information describes debugging SPNEGO configuration problems with WebSEAL configuration where one of the Web security servers does not start. If the WebSEAL server fails to start, the server log file for that server contains messages that describe the problem.

Collecting data for Security Access Manager: WebSEAL (SPNEGO issues)
When WebSEAL does not start because of a SPNEGO issue, you might need to collect data for problem determination.

No match to principal in key table

Parent topic: Problems with SPNEGO

Collecting data for Security Access Manager: WebSEAL (SPNEGO issues)Collecting data for Security Access Manager: WebSEAL (SPNEGO issues)Collecting data for Security Access Manager: WebSEAL (SPNEGO issues)When WebSEAL does not start because of a SPNEGO issue, you might need to collect data for problem determination.SPNEGOcollect dataWebSEALdoes not startWhen directed by IBM Support, collect the SPNEGO diagnostic data when WebSEAL does not start. Turn on trace for each process by removing the # on the last line of the /opt/pdweb/etc/routing file.The last three lines of the routing file are shown: # # Route to a per-process text file #*:*.9:TEXTFILE.10.1000:/var/pdweb/log/trace__%ld.trace.log:644:ivmgr:ivmgr This will create a file in '/var/pdweb/log/trace __%ld.trace.log'Ensure that enough disk space is available in the /var directory. If WebSEAL is started with the pdweb_start command, there are two traces with different pids.Start WebSEAL to recreate the issue.Turn off trace for each process by replacing the # at the beginning of the last line of the /opt/pdweb/etc/routing file.Collect the following files:Webseald-instance_name.confmsg__webseald-instance_name.logtrace_pid.trace.logThe krb5.conf file if WebSEAL is on AIX, Linux, or SolarisThe Keytab file if WebSEAL is on AIX, Linux, or Solarisldap.conf for WebSEALActivedir_ldap.conf if Active Directory is the user registryCollect the following information:The output of the pdversion command on the WebSEAL server systemIf WebSEAL is on AIX, Linux, or Solaris: kinit output when you use the keytab fileThe ktpass command that is issued to create the keytab fileActive Directory Server versionArchive the data and send to support as directed by IBM Support.Web security server not starting

Collecting data for Security Access Manager: WebSEAL (SPNEGO issues)

When WebSEAL does not start because of a SPNEGO issue, you might need to collect data for problem determination.

About this task

When directed by IBM® Support, collect the SPNEGO diagnostic data when WebSEAL does not start.

Procedure

Turn on trace for each process by removing the # on the last line of the /opt/pdweb/etc/routing file. The last three lines of the routing file are shown:

#
# Route to a per-process text file
#*:*.9:TEXTFILE.10.1000:/var/pdweb/log/trace__%ld.trace.log:644:ivmgr:ivmgr
This will create a file in '/var/pdweb/log/trace __%ld.trace.log'

Note: Ensure that enough disk space is available in the /var directory. If WebSEAL is started with the pdweb_start command, there are two traces with different pids.

Start WebSEAL to recreate the issue.

Turn off trace for each process by replacing the # at the beginning of the last line of the /opt/pdweb/etc/routing file.

Collect the following files:

Webseald-instance_name.conf

msg__webseald-instance_name.log

trace_pid.trace.log

The krb5.conf file if WebSEAL is on AIX®, Linux, or Solaris

The Keytab file if WebSEAL is on AIX, Linux, or Solaris

ldap.conf for WebSEAL

Activedir_ldap.conf if Active Directory is the user registry

Collect the following information:

The output of the pdversion command on the WebSEAL server system

If WebSEAL is on AIX, Linux, or Solaris: kinit output when you use the keytab file

The ktpass command that is issued to create the keytab file

Active Directory Server version

Archive the data and send to support as directed by IBM Support.

Parent topic: Web security server not starting

No match to principal in key table0x1cff2901 error 486484225 error gss_import_name messages0x1cff2901 error gss_import_name messages486484225 error error 0x1cff2901error 486484225Kerberoserror 0x1cff2901Kerberoserror 486484225WebSEALserver cannot startHPDST0130Eprincipal not in key tablemessagesHPDST0130Eprincipal not in key tableKerberosprincipal not in key tableThe server did not start, and the log file contains the following error: HPDST0130E The security service function gss_import_name returned the error 'No principal in keytab matches desired name' (code 0x1cff2901/486484225) The principal name for the SPNEGO service that is defined in the Security Access Manager server configuration file does not have a matching key in the SPNEGO key table. This error can occur for various reasons.The algorithm to map the service principal name to the key in the SPNEGO key table completes the following processes: Completes forward and reverse name resolution for the host name that is defined in the spnego-krb-service-name entry of the [spnego] stanza to discover the canonical host name.Compares canonical host name to the realms defined in the [domain_realm] stanza of the krb5.conf configuration file.Validates the principal key in the SPNEGO key table.For details about these processes, see Algorithm to resolve host names.The server configuration file for WebSEAL contains the [spnego] stanza. This stanza contains the following entries to examine: spnego-krb-service-nameDefines the service principal name in the following format: HTTP@hostname The following example shows a definition of this entry in the configuration file: HTTP@diamond.subnet2.ibm.comspnego-krb-keytab-fileDefines the SPNEGO key table. This file contains principal keys in the following format: HTTP/canonical_hostname@realm The following example shows a key in the key table: HTTP/diamond.subnet2.ibm.com@IBM.COMThe Kerberos krb5.conf configuration file contains the [domain_realm] stanza. This stanza contains entries that define the supported Kerberos realms. For details about this configuration file, see your Kerberos documentation.Web security server not starting

No match to principal in key table

The server did not start, and the log file contains the following error:

HPDST0130E The security service function gss_import_name returned
the error 'No principal in keytab matches desired name'
(code 0x1cff2901/486484225)

The principal name for the SPNEGO service that is defined in the Security Access Manager server configuration file does not have a matching key in the SPNEGO key table. This error can occur for various reasons.

The algorithm to map the service principal name to the key in the SPNEGO key table completes the following processes:

Completes forward and reverse name resolution for the host name that is defined in the spnego-krb-service-name entry of the [spnego] stanza to discover the canonical host name.

Compares canonical host name to the realms defined in the [domain_realm] stanza of the krb5.conf configuration file.

Validates the principal key in the SPNEGO key table.

For details about these processes, see Algorithm to resolve host names.

The server configuration file for WebSEAL contains the [spnego] stanza. This stanza contains the following entries to examine:

spnego-krb-service-name

Defines the service principal name in the following format:

HTTP@hostname

The following example shows a definition of this entry in the configuration file:

HTTP@diamond.subnet2.ibm.com

spnego-krb-keytab-file

Defines the SPNEGO key table. This file contains principal keys in the following format:

HTTP/canonical_hostname@realm

The following example shows a key in the key table:

HTTP/diamond.subnet2.ibm.com@IBM.COM

The Kerberos krb5.conf configuration file contains the [domain_realm] stanza. This stanza contains entries that define the supported Kerberos realms. For details about this configuration file, see your Kerberos documentation.

Parent topic: Web security server not starting

Algorithm to resolve host namesThe following process is used to map a service principal name to a key in the SPNEGO key table: Resolve the host name to an IP address. The mapping process depends on your host name resolution configuration. Typically, the /etc/hosts file is checked first followed by the DNS server that is configured in the resolv.conf file. If the resolution succeeds, the process continues with step 2. If the resolution fails, the canonical name is assumed to be the same as the host name. The process continues with step 3.Resolve the IP address to the canonical name. The mapping process depends on your host name resolution configuration. Typically, the /etc/hosts file is checked first followed by the DNS server that is configured in the resolv.conf file. If the IP address is found in the /etc/hosts file, the canonical name is set to the first host name that is listed. If the IP address is not found in the /etc/hosts file, the DNS server is queried to complete a reverse lookup on the IP address. If the DNS server returns a host name for this IP address, this host name becomes the canonical name. If the IP address is not found in the /etc/hosts file and if the DNS server does not return a host name for this IP address, the canonical name is assumed to be the same as the host name. Common errorThe /etc/hosts file lists the short name of the host before the fully qualified host name, the format of the /etc/hosts file is incorrect. Entries in the /etc/hosts file are in the following format: IP_address fully_qualified_hostname short_nameWhen the format is incorrect, host name resolution might return the short name. The canonical name is then set to this short name. When this issue occurs, the Web server searches for the wrong key in the key table. The canonical name must be set to match the host name that clients use to contact the Web server.ResolutionContact your AIX, Linux, or Solaris system administrator on how to change entries in the following files: /etc/hostsresolv.confMap the canonical name from step 1 or step 2 to the realm name by checking the [domain_realm] stanza of the /opt/PolicyDirector/etc/krb5.conf file. Each entry in this stanza maps a host name or domain name to a realm name. The canonical host name if checked against each of the host entries. If a matching host entry is found, the realm name becomes the realm that is specified for the host. If no matching host entry is found, the domain entries are checked. If a matching domain entry is found, the realm name becomes the realm that is specified for that domain. If no matching domain entry is found, the realm name becomes the value of the [libdefaults] default_realm entry in the /opt/PolicyDirector/etc/krb5.conf file. Common errorThe entries in the [domain_realm] stanza of the /opt/PolicyDirector/etc/krb5.conf file are incorrect.ResolutionVerify that the realm name specified in the [domain_realm] stanza is correct, and verify that the canonical name matches a host or domain entry in this stanza.Verify that the key table contains this entry. Common errorThe key table does not contain a matching entry.ResolutionUse the am_klist command or the am_ktutil program to check the SPNEGO key table for an entry in the following format: HTTP/canonical_name@realm_name For details about using the am_ktutil program, see Validating keys in key tables.Problems with SPNEGOUse the following troubleshooting tips for issues that involve SPNEGO authentication.

Algorithm to resolve host names

The following process is used to map a service principal name to a key in the SPNEGO key table:

Resolve the host name to an IP address. The mapping process depends on your host name resolution configuration. Typically, the /etc/hosts file is checked first followed by the DNS server that is configured in the resolv.conf file.

If the resolution succeeds, the process continues with step 2.

If the resolution fails, the canonical name is assumed to be the same as the host name. The process continues with step 3.

Resolve the IP address to the canonical name. The mapping process depends on your host name resolution configuration. Typically, the /etc/hosts file is checked first followed by the DNS server that is configured in the resolv.conf file.

If the IP address is found in the /etc/hosts file, the canonical name is set to the first host name that is listed.

If the IP address is not found in the /etc/hosts file, the DNS server is queried to complete a reverse lookup on the IP address. If the DNS server returns a host name for this IP address, this host name becomes the canonical name.

If the IP address is not found in the /etc/hosts file and if the DNS server does not return a host name for this IP address, the canonical name is assumed to be the same as the host name.

Common error

The /etc/hosts file lists the short name of the host before the fully qualified host name, the format of the /etc/hosts file is incorrect. Entries in the /etc/hosts file are in the following format:

IP_address fully_qualified_hostname short_name

When the format is incorrect, host name resolution might return the short name. The canonical name is then set to this short name. When this issue occurs, the Web server searches for the wrong key in the key table. The canonical name must be set to match the host name that clients use to contact the Web server.

Resolution

Contact your AIX®, Linux, or Solaris system administrator on how to change entries in the following files:

/etc/hosts

resolv.conf

Map the canonical name from step 1 or step 2 to the realm name by checking the [domain_realm] stanza of the /opt/PolicyDirector/etc/krb5.conf file. Each entry in this stanza maps a host name or domain name to a realm name.

The canonical host name if checked against each of the host entries. If a matching host entry is found, the realm name becomes the realm that is specified for the host. If no matching host entry is found, the domain entries are checked. If a matching domain entry is found, the realm name becomes the realm that is specified for that domain.

If no matching domain entry is found, the realm name becomes the value of the [libdefaults] default_realm entry in the /opt/PolicyDirector/etc/krb5.conf file.

Common error

The entries in the [domain_realm] stanza of the /opt/PolicyDirector/etc/krb5.conf file are incorrect.

Resolution

Verify that the realm name specified in the [domain_realm] stanza is correct, and verify that the canonical name matches a host or domain entry in this stanza.

Verify that the key table contains this entry.

Common error

The key table does not contain a matching entry.

Resolution

Use the am_klist command or the am_ktutil program to check the SPNEGO key table for an entry in the following format:

HTTP/canonical_name@realm_name

For details about using the am_ktutil program, see Validating keys in key tables.

Parent topic: Problems with SPNEGO

Problems with KerberosProblems with KerberosProblems with KerberosThe following information can assist you when troubleshooting issues that concern Kerberos authentication.Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGOUse the following information to troubleshoot and resolve single sign-on issues that involve Windows Desktop single sign-on, Kerberos, and SPNEGO.Kerberos initialization failingUseful Kerberos procedures

Problems with Kerberos

The following information can assist you when troubleshooting issues that concern Kerberos authentication.

Kerberos initialization failing

Useful Kerberos procedures

Parent topic: Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGO

Kerberos initialization failingam_kinit commandKerberos initialization failcommandsam_kinitKerberosam_kinit command initialization failureKerberosinitialization problemsThe following information describes debugging problems with the Kerberos am_kinit command. If the am_kinit command completes, it generates no output, but you can use the Kerberos am_klist command to view the principals in the ticket cache. If the am_kinit command fails, the error message provides the following details: The primary cause for the failureA hexadecimal status codeThe specific reason for the failureThe most common primary causes for the am_kinit command to fail are the following reasons: Failure to initialize the Kerberos librariesUnable to obtain initial credentialsProblems with KerberosThe following information can assist you when troubleshooting issues that concern Kerberos authentication.Kerberos configurationUnable to initialize Kerberos librariesUnable to obtain initial credentials

Kerberos initialization failing

The following information describes debugging problems with the Kerberos am_kinit command. If the am_kinit command completes, it generates no output, but you can use the Kerberos am_klist command to view the principals in the ticket cache. If the am_kinit command fails, the error message provides the following details:

The primary cause for the failure

A hexadecimal status code

The specific reason for the failure

The most common primary causes for the am_kinit command to fail are the following reasons:

Failure to initialize the Kerberos libraries

Unable to obtain initial credentials

Kerberos configuration

Unable to initialize Kerberos libraries

Unable to obtain initial credentials

Parent topic: Problems with Kerberos

Kerberos configurationKerberos configurationKerberos configurationam_kinit commandKerberos configurationProblem: am_kinit crashes when running am_kinit -k -tSolution: Some versions of am_kinit do not deal properly with problems when an entry is not found in a keytab file. Double-check that the keytab file has the exact same entry you are passing to am_kinit.Kerberos initialization failing

Kerberos configuration

Problem: am_kinit crashes when running am_kinit -k -t

Solution: Some versions of am_kinit do not deal properly with problems when an entry is not found in a keytab file. Double-check that the keytab file has the exact same entry you are passing to am_kinit.

Parent topic: Kerberos initialization failing

Unable to initialize Kerberos librariesKerberosinitialization librariesWhen you run the am_kinit command, you might receive an error message that states the following primary reason: Initializing kerberos libraries failed.The most common causes that the initial credentials cannot be obtained are the following reasons: Cannot open configuration fileImproper format of configuration fileKerberos initialization failingCannot open configuration fileImproper format of configuration fileOther configuration items to check when problems occurProblems can result because of configuration errors. Check the following configuration items when problems occur.

Unable to initialize Kerberos libraries

When you run the am_kinit command, you might receive an error message that states the following primary reason:

Initializing kerberos libraries failed.

The most common causes that the initial credentials cannot be obtained are the following reasons:

Cannot open configuration file

Improper format of configuration file

Cannot open configuration file

Improper format of configuration file

Other configuration items to check when problems occur
Problems can result because of configuration errors. Check the following configuration items when problems occur.

Parent topic: Kerberos initialization failing

Cannot open configuration file0x96c73a87 error error 0x96c73a87Kerberoserror 0x96c73a87Kerberosconfiguration filecannot openfileskrb5.confcannot openkrb5.conf filecannot openWhen you use the am_kinit command, you receive the following error: Initializing kerberos libraries failed. Status 0x96c73a87 Cannot open or find the Network Authentication Service configuration file. The /opt/PolicyDirector/etc/krb5.conf file does not exist or cannot be opened. Verify that file exists and is readable by all users.Unable to initialize Kerberos libraries

Cannot open configuration file

When you use the am_kinit command, you receive the following error:

Initializing kerberos libraries failed. Status 0x96c73a87
Cannot open or find the Network Authentication Service
configuration file.

The /opt/PolicyDirector/etc/krb5.conf file does not exist or cannot be opened. Verify that file exists and is readable by all users.

Parent topic: Unable to initialize Kerberos libraries

Improper format of configuration file0x96c73a88 error error 0x96c73a88Kerberoserror 0x96c73a88Kerberosconfiguration fileimproper formatfileskrb5.confimproper formatkrb5.conf fileformat, improperWhen you use the am_kinit command, you receive the following error: Initializing kerberos libraries failed. Status 0x96c73a88 Improper format of Network Authentication Service configuration file.The /opt/PolicyDirector/etc/krb5.conf file contains a syntax error. No details about the syntax error are available. Edit the configuration file to identify and correct the syntax error.Unable to initialize Kerberos libraries

Improper format of configuration file

When you use the am_kinit command, you receive the following error:

Initializing kerberos libraries failed. Status 0x96c73a88
Improper format of Network Authentication Service
configuration file.

The /opt/PolicyDirector/etc/krb5.conf file contains a syntax error. No details about the syntax error are available. Edit the configuration file to identify and correct the syntax error.

Parent topic: Unable to initialize Kerberos libraries

Other configuration items to check when problems occurProblems can result because of configuration errors. Check the following configuration items when problems occur.am_ktutil commandOther configuration items to check when problems occur:Check that the file permissions and ownership of the keytab file allow access by the plug-in authorization server. Check that the keytab file contains valid data and keys for the correct principal name by using the am_ktutil utility to display information that is contained in the keytab file. Check that the DNS configuration for the entire domain (domain controller and clients) is correct and that names resolve correctly and match the values in the service principal name configuration items in various locations (such as keytab file, and plug-in configuration file). Check that system clocks are synchronized and that a distributed time service is maintaining clock synchronization on all systems in the domain.Check that the network configuration is correct and that there are no issues such as congestion, incorrect routing, or name collision. Ensure that the latency is within tolerable limits. Be sure that firewalls, NAT, and other network security services do not interfere with the operation of the domain.Unable to initialize Kerberos libraries

Other configuration items to check when problems occur

Problems can result because of configuration errors. Check the following configuration items when problems occur.

Other configuration items to check when problems occur:

Check that the file permissions and ownership of the keytab file allow access by the plug-in authorization server.

Check that the keytab file contains valid data and keys for the correct principal name by using the am_ktutil utility to display information that is contained in the keytab file.

Check that the DNS configuration for the entire domain (domain controller and clients) is correct and that names resolve correctly and match the values in the service principal name configuration items in various locations (such as keytab file, and plug-in configuration file).

Check that system clocks are synchronized and that a distributed time service is maintaining clock synchronization on all systems in the domain.

Check that the network configuration is correct and that there are no issues such as congestion, incorrect routing, or name collision. Ensure that the latency is within tolerable limits. Be sure that firewalls, NAT, and other network security services do not interfere with the operation of the domain.

Parent topic: Unable to initialize Kerberos libraries

Unable to obtain initial credentialsKDCWhen you run the am_kinit command, you might receive an error message that states the following primary reason: Unable to obtain initial credentials.The most common causes that the initial credentials cannot be obtained are the following reasons: Cannot resolve the network address of the key distribution center (KDC)Cannot contact the KDCClocks are not synchronizedPre-authentication failureClient not found in authentication database, or client that is locked outKerberos initialization failingCannot resolve address of key distribution centerCannot contact the key distribution centerClocks are not synchronizedPre-authentication failureClient not found or locked out

Unable to obtain initial credentials

When you run the am_kinit command, you might receive an error message that states the following primary reason:

Unable to obtain initial credentials.

The most common causes that the initial credentials cannot be obtained are the following reasons:

Cannot resolve the network address of the key distribution center (KDC)

Cannot contact the KDC

Clocks are not synchronized

Pre-authentication failure

Client not found in authentication database, or client that is locked out

Cannot resolve address of key distribution center

Cannot contact the key distribution center

Clocks are not synchronized

Pre-authentication failure

Client not found or locked out

Parent topic: Kerberos initialization failing

Cannot resolve address of key distribution center0x96c73adc error error 0x96c73adcKerberoserror 0x96c73adckeysdistribution centerresolve addressfileskrb5.confKDC host, modifykrb5.conf fileKDC host, modify When you use the am_kinit command, you receive the following error: Unable to obtain initial credentials. Status 0x96c73adc Cannot resolve network address for KDC in requested realm.The host name for the key distribution center (KDC) that is defined in the /opt/PolicyDirector/etc/krb5.conf file is not valid. Edit this configuration file to correct the host name for the KDC.Unable to obtain initial credentials

Cannot resolve address of key distribution center

When you use the am_kinit command, you receive the following error:

Unable to obtain initial credentials. Status 0x96c73adc
Cannot resolve network address for KDC in requested realm.

The host name for the key distribution center (KDC) that is defined in the /opt/PolicyDirector/etc/krb5.conf file is not valid. Edit this configuration file to correct the host name for the KDC.

Parent topic: Unable to obtain initial credentials

Cannot contact the key distribution center0x96c73a9c error error 0x96c73a9cKerberoserror 0x96c73a9ckeysdistribution centercontactKerberoskeysdistribution centerWhen you use the am_kinit command, you receive the following error: Unable to obtain initial credentials. Status 0x96c73a9c Cannot contact any KDC in requested realm.The host name for the key distribution center (KDC) that is defined in the /opt/PolicyDirector/etc/krb5.conf file is valid, but the KDC cannot be contacted. Verify the following conditions: Ensure that the krb5.conf configuration file defines the correct host name and port for the KDC.Ensure that the KDC is running.Ensure that there is network connectivity between the client and the KDC.Unable to obtain initial credentials

Cannot contact the key distribution center

When you use the am_kinit command, you receive the following error:

Unable to obtain initial credentials. Status 0x96c73a9c
Cannot contact any KDC in requested realm.

The host name for the key distribution center (KDC) that is defined in the /opt/PolicyDirector/etc/krb5.conf file is valid, but the KDC cannot be contacted. Verify the following conditions:

Ensure that the krb5.conf configuration file defines the correct host name and port for the KDC.

Ensure that the KDC is running.

Ensure that there is network connectivity between the client and the KDC.

Parent topic: Unable to obtain initial credentials

Clocks are not synchronized0x96c73a25 error error 0x96c73a25Kerberoserror 0x96c73a25clock synchronizationKerberosKerberosclock skewWhen you use the am_kinit command to test an AIX, Linux, or Solaris server key table, you receive the following error: Unable to obtain initial credentials. Status 0x96c73a25 Clock skew too great.To resolve this condition, keep system clocks synchronized. For a permanent solution, deploy a time synchronization service on your systems. For a temporary solution, adjust the clocks on the systems so they are within one minute of each other.Unable to obtain initial credentials

Clocks are not synchronized

When you use the am_kinit command to test an AIX®, Linux, or Solaris server key table, you receive the following error:

Unable to obtain initial credentials. Status 0x96c73a25
Clock skew too great.

To resolve this condition, keep system clocks synchronized. For a permanent solution, deploy a time synchronization service on your systems. For a temporary solution, adjust the clocks on the systems so they are within one minute of each other.

Parent topic: Unable to obtain initial credentials

Pre-authentication failure0x96c73a18 error error 0x96c73a18Kerberoserror 0x96c73a18Kerberospre-authentication failureKerberospassword, incorrect authenticationpre-authentication failure (Kerberos)When you use the am_kinit command to test an AIX, Linux, or Solaris server key table, you receive the following error: Unable to obtain initial credentials. Status 0x96c73a18 Preauthentication failed. The key in the key table is incorrect. A common reason is that the password for the principal in the Active Directory server was changed. In this case, regenerate the key table. If the password was not changed, make sure that you generated the key table correctly by using the correct principal name, Active Directory user name, and path.Unable to obtain initial credentials

Pre-authentication failure

When you use the am_kinit command to test an AIX®, Linux, or Solaris server key table, you receive the following error:

Unable to obtain initial credentials. Status 0x96c73a18
Preauthentication failed.

The key in the key table is incorrect. A common reason is that the password for the principal in the Active Directory server was changed. In this case, regenerate the key table. If the password was not changed, make sure that you generated the key table correctly by using the correct principal name, Active Directory user name, and path.

Parent topic: Unable to obtain initial credentials

Client not found or locked out0x96c73a06 error error 0x96c73a06Kerberoserror 0x96c73a06Kerberosclient not foundKerberosclient locked outWhen you use the am_kinit command to test an AIX, Linux, or Solaris server key table, you receive the following error: Unable to obtain initial credentials. Status 0x96c73a06 Client not found in Network Authentication Service database or client locked out. The key table does not have a key for the specified principal. Check whether an error was made when the principal was typed, or whether the key table was generated incorrectly. You can use the Kerberos am_ktutil commands to check which keys are in the key table. For details about this procedure, see Validating keys in key tables.Unable to obtain initial credentials

Client not found or locked out

When you use the am_kinit command to test an AIX®, Linux, or Solaris server key table, you receive the following error:

Unable to obtain initial credentials. Status 0x96c73a06
Client not found in Network Authentication Service database
or client locked out.

The key table does not have a key for the specified principal. Check whether an error was made when the principal was typed, or whether the key table was generated incorrectly. You can use the Kerberos am_ktutil commands to check which keys are in the key table. For details about this procedure, see Validating keys in key tables.

Parent topic: Unable to obtain initial credentials

Useful Kerberos proceduresKerberoscommandsUse the following procedures to help troubleshoot a SPNEGO or Kerberos problem.Problems with KerberosThe following information can assist you when troubleshooting issues that concern Kerberos authentication.Validating keys in key tables

Useful Kerberos procedures

Use the following procedures to help troubleshoot a SPNEGO or Kerberos problem.

Validating keys in key tables

Parent topic: Problems with Kerberos

Validating keys in key tablesThere is a test function available in the appliance Web interface to test Kerberos keyfiles.From the main menu select Secure Web Settings -> Global Settings -> Kerberos Configuration. In the Kerberos Configuration panel select the Keyfiles tab and click on the Test button.Useful Kerberos procedures

Validating keys in key tables

About this task

There is a test function available in the appliance Web interface to test Kerberos keyfiles.

From the main menu select Secure Web Settings -> Global Settings -> Kerberos Configuration. In the Kerberos Configuration panel select the Keyfiles tab and click on the Test button.

Parent topic: Useful Kerberos procedures

Unable to authenticateIf a user attempts to authenticate to WebSEAL by using SPNEGO authentication and the authentication fails, an HTML error page is displayed and a message is added to the log.Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGOUse the following information to troubleshoot and resolve single sign-on issues that involve Windows Desktop single sign-on, Kerberos, and SPNEGO.Ticket not yet validCannot acquire credentialsWrong principal in requestEncryption type not permittedKey version is incorrectCannot authenticate by using NTLMCannot complete authentication

Unable to authenticate

If a user attempts to authenticate to WebSEAL by using SPNEGO authentication and the authentication fails, an HTML error page is displayed and a message is added to the log.

Ticket not yet valid

Cannot acquire credentials

Wrong principal in request

Encryption type not permitted

Key version is incorrect

Cannot authenticate by using NTLM

Cannot complete authentication

Parent topic: Single sign-on Issues: Windows Desktop single sign-on, Kerberos, and SPNEGO

Ticket not yet valid0x96c73a21 error -1765328351 error 0x96c73a25 error -1765328347 error gss_accept_sec_context messages0x96c73a21 error gss_accept_sec_context messages-1765328351 error gss_accept_sec_context messages0x96c73a25 error gss_accept_sec_context messages-1765328347 error error 0x96c73a21 error-1765328351error 0x96c73a25error -1765328347 Kerberoserror 0x96c73a21 Kerberoserror -1765328351Kerberoserror 0x96c73a25 Kerberoserror -1765328347 HPDST0130Eticket not yet validHPDST0130Eclock skew too greatmessagesHPDST0130Eticket not yet validmessagesHPDST0130Eclock skew too greatHPDIA0100Eticket not yet validHPDIA0100Eclock skew too greatmessagesHPDIA0100Eticket not yet validmessagesHPDIA0100Eclock skew too greatKerberosclock skewKerberosticket not yet validA user attempts to access WebSEAL and receives an HTML page with the following error: HPDIA0100E An internal error has occurred.The trace log file contains the following one of the following messages: HPDST0130E The security service function gss_accept_sec_context returned the error 'Ticket not yet valid' (code 0x96c73a21/-1765328351).HPDST0130E The security service function gss_accept_sec_context returned the error 'Clock skew too great' (code 0x96c73a25/-1765328347).The system clock on the client system is not synchronized with the system clock on the Active Directory server. When you use Kerberos, these clocks must be synchronized. For a permanent solution, deploy a time synchronization service on your system. For a temporary solution, adjust the clocks on the system so that they are within one minute of each other.Unable to authenticate

Ticket not yet valid

A user attempts to access WebSEAL and receives an HTML page with the following error:

HPDIA0100E An internal error has occurred.

The trace log file contains the following one of the following messages:

HPDST0130E The security service function gss_accept_sec_context returned the error 'Ticket not yet valid' (code 0x96c73a21/-1765328351).

HPDST0130E The security service function gss_accept_sec_context returned the error 'Clock skew too great' (code 0x96c73a25/-1765328347).

The system clock on the client system is not synchronized with the system clock on the Active Directory server. When you use Kerberos, these clocks must be synchronized. For a permanent solution, deploy a time synchronization service on your system. For a temporary solution, adjust the clocks on the system so that they are within one minute of each other.

Parent topic: Unable to authenticate

Cannot acquire credentialsHPDIA0114EmessagesHPDIA0114EKerberoscredentialscannot acquire A user attempts to access WebSEAL and receives an HTML page with the following error: HPDIA0114E Could not acquire a client credential.This same message is written to the log file.The user exists in the Active Directory user registry and presented valid SPNEGO authentication data, but the user does not exist in the Security Access Manager user registry.SPNEGO authentication requires that the user exists in both the Active Directory and the Security Access Manager user registries. If you believe that the user exists in both user registries, verify that the user ID produced by SPNEGO authentication matches what you expect.To see the user ID, complete the following steps: Enable the pd.ias authentication trace by using the following pdadmin command: pdadmin sec_master> server task serverName trace set \ pd.ias 9 file path=/tmp/ias.logHave the same user attempt to access the Web server again. After this user receives the HPDIA0114E message, disable the authentication trace by using the following pdadmin command: pdadmin sec_master> server task server trace set pd.ias 0Examine the /tmp/ias.log file for a message that is similar to the following message: Mapped name user@realm to am_userEnsure that the am_user user is a defined user in the Security Access Manager user registry.Unable to authenticate

Cannot acquire credentials

A user attempts to access WebSEAL and receives an HTML page with the following error:

HPDIA0114E Could not acquire a client credential.

This same message is written to the log file.

The user exists in the Active Directory user registry and presented valid SPNEGO authentication data, but the user does not exist in the Security Access Manager user registry.

SPNEGO authentication requires that the user exists in both the Active Directory and the Security Access Manager user registries. If you believe that the user exists in both user registries, verify that the user ID produced by SPNEGO authentication matches what you expect.

To see the user ID, complete the following steps:

Enable the pd.ias authentication trace by using the following pdadmin command:

pdadmin sec_master> server task serverName trace set  \
			pd.ias 9 file path=/tmp/ias.log

Have the same user attempt to access the Web server again. After this user receives the HPDIA0114E message, disable the authentication trace by using the following pdadmin command:

pdadmin sec_master> server task server trace set pd.ias 0

Examine the /tmp/ias.log file for a message that is similar to the following message:

Mapped name user@realm to am_user

Ensure that the am_user user is a defined user in the Security Access Manager user registry.

Parent topic: Unable to authenticate

Wrong principal in request0x96c73a90 error -1765328240 error gss_accept_sec_context messages0x96c73a90 error gss_accept_sec_context messages-1765328240 error error 0x96c73a90 error -1765328240Kerberoserror 0x96c73a90 Kerberoserror -1765328240HPDST0130Ewrong principalmessagesHPDST0130Ewrong principalHPDIA0100Eprincipal, wrong messagesHPDIA0100Ewrong principalKerberoswrong principalA user attempts to access WebSEAL and receives an HTML page with the following error: HPDIA0100E An internal error has occurred.The trace log file contains the following message: HPDST0130E The security service function gss_accept_sec_context returned the error 'Wrong principal in request' (code 0x96c73a90/-1765328240). The server principal name (SPN) supplied by the client in the SPNEGO authentication header does not match the SPN being used by the Web security server. This error can be caused in the following situations: The user did not specify the fully qualified host name (FQHN) when you contact the Web security server. Clients must use the FQHN so that the Active Directory server can provide the client with an appropriate Kerberos authentication ticket.The Web security server is configured to use the wrong SPN. The host name portion of the principal in the Kerberos key table must match the host name that is being used by the client to contact the Web security server. If the principal name in the key table is incorrect, the key table must regenerate on the key distribution center (KDC) by using the ktpass command with the –princ option. The value that is specified for the –princ option must be the same host name that client uses to contact the Web security server. For example, for clients to contact the Web security server at https://diamond.example.ibm.com and the Web security server is in the IBM.COM Kerberos realm, specify the following value for the –princ option: HTTP/diamond.example.ibm.com@IBM.COM You can use the am_ktutil program to examine the contents of the Kerberos key table.Unable to authenticate

Wrong principal in request

A user attempts to access WebSEAL and receives an HTML page with the following error:

HPDIA0100E An internal error has occurred.

The trace log file contains the following message:

HPDST0130E The security service function gss_accept_sec_context returned
the error 'Wrong principal in request' (code 0x96c73a90/-1765328240).

The server principal name (SPN) supplied by the client in the SPNEGO authentication header does not match the SPN being used by the Web security server. This error can be caused in the following situations:

The user did not specify the fully qualified host name (FQHN) when you contact the Web security server. Clients must use the FQHN so that the Active Directory server can provide the client with an appropriate Kerberos authentication ticket.

The Web security server is configured to use the wrong SPN. The host name portion of the principal in the Kerberos key table must match the host name that is being used by the client to contact the Web security server. If the principal name in the key table is incorrect, the key table must regenerate on the key distribution center (KDC) by using the ktpass command with the –princ option. The value that is specified for the –princ option must be the same host name that client uses to contact the Web security server.

For example, for clients to contact the Web security server at https://diamond.example.ibm.com and the Web security server is in the IBM.COM Kerberos realm, specify the following value for the –princ option:

HTTP/diamond.example.ibm.com@IBM.COM

You can use the am_ktutil program to examine the contents of the Kerberos key table.

Parent topic: Unable to authenticate

Encryption type not permitted0x96c73ae9 error -1765328151 error gss_accept_sec_context messages0x96c73ae9 error gss_accept_sec_context messages-1765328151 error error 0x96c73ae9error -1765328151Kerberoserror 0x96c73ae9 Kerberoserror -1765328151HPDST0130Eencryption type, invalid messagesHPDST0130Einvalid encryption typeHPDIA0100Eencryption type, invalid messagesHPDIA0100Einvalid encryption typelibdefaults stanzadefault_tkt_enctypes entrylibdefaults stanzadefault_tgs_enctypes entrydefault_tkt_enctypes entrydefault_tgs_enctypes entryKerberosinvalid encryption typekrb5.conf filedefault_tkt_enctypes entrykrb5.conf filedefault_tgs_enctypes entrykrb5.conf filelibdefaults stanzakrb5.conf filelibraries, modify fileskrb5.conflibraries, modifyA user attempts to access WebSEAL and receives an HTML page with the following error: HPDIA0100E An internal error has occurred.The trace log file contains the following message: HPDST0130E The security service function gss_accept_sec_context returned the error 'Encryption type not permitted' (code 0x96c73ae9/-1765328151).The encryption type in the SPNEGO authentication header does not match any of the encryption types that the Kerberos libraries are configured to accept. To resolve the issue, ensure that the /opt/PolicyDirector/etc/krb5.conf configuration file defines the following entries in the [libdefaults] stanza: default_tkt_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes256-cts aes128-cts default_tgs_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes256-cts aes128-ctsAfter you save these changes, restart the Web security serverUnable to authenticate

Encryption type not permitted

A user attempts to access WebSEAL and receives an HTML page with the following error:

HPDIA0100E An internal error has occurred.

The trace log file contains the following message:

HPDST0130E The security service function gss_accept_sec_context returned
the error 'Encryption type not permitted' (code 0x96c73ae9/-1765328151).

The encryption type in the SPNEGO authentication header does not match any of the encryption types that the Kerberos libraries are configured to accept. To resolve the issue, ensure that the /opt/PolicyDirector/etc/krb5.conf configuration file defines the following entries in the [libdefaults] stanza:

default_tkt_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes256-cts aes128-cts
default_tgs_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc aes256-cts aes128-cts

After you save these changes, restart the Web security server

Parent topic: Unable to authenticate

Key version is incorrect0x96c73ae3 error -1765328157 error gss_accept_sec_context messages0x96c73ae3 error gss_accept_sec_context messages-1765328157 error error 0x96c73ae3 error -1765328157Kerberoserror 0x96c73ae3 Kerberoserror -1765328157 HPDST0130Ekey version, incorrect messagesHPDST0130Eincorrect key versionHPDIA0100Ekey version, incorrect messagesHPDIA0100Eincorrect key versionKerberoskeysversion, incorrect A user attempts to access WebSEAL and receives an HTML page with the following error: HPDIA0100E An internal error has occurred.The trace log file contains the following message: HPDST0130E The security service function gss_accept_sec_context returned the error 'Key version number for principal in key table is incorrect' (code 0x96c73ae3/-1765328157).The key version in the Kerberos authentication header does not match the key version in the SPNEGO key table. This error might occur after the password for the Kerberos principal for the Web security server is changed in the Active Directory server. After you change this password, complete the following steps: Regenerate the SPNEGO key table.Replace this key table on the Web security server.Restart the Web security serverFor more information, see item 870987 in the Microsoft knowledge base.Unable to authenticate

Key version is incorrect

A user attempts to access WebSEAL and receives an HTML page with the following error:

HPDIA0100E An internal error has occurred.

The trace log file contains the following message:

HPDST0130E The security service function gss_accept_sec_context returned
the error 'Key version number for principal in key table is incorrect'
(code 0x96c73ae3/-1765328157).

The key version in the Kerberos authentication header does not match the key version in the SPNEGO key table. This error might occur after the password for the Kerberos principal for the Web security server is changed in the Active Directory server. After you change this password, complete the following steps:

Regenerate the SPNEGO key table.

Replace this key table on the Web security server.

Restart the Web security server

For more information, see item 870987 in the Microsoft knowledge base.

Parent topic: Unable to authenticate

Cannot authenticate by using NTLMDPWWA2403EmessagesDPWWA2403EKerberosNT LAN ManagerNT LAN Manager (NTLM)master authentication serverNT LAN Managermaster authentication serverKerberosWhen you attempt to access a Web security server, you receive the following error messages: DPWWA2403E Your browser supplied NTLM authentication data. NTLM is not supported by WebSEAL. Ensure that your browser is configured to use Integrated Windows Authentication. WebSEAL does not support NT LAN Manager (NTLM) authentication. Some browsers support NTLM authentication only or are configured to send NTLM authentication tokens instead of SPNEGO tokens. A browser that supports SPNEGO might be sending NTLM tokens for the following reasons: Microsoft Internet Explorer is not configured with the WebSEAL server in the Trusted sites or Local intranet zone.Microsoft Internet Explorer is not configured for Integrated Windows Authentication.The client workstation and the WebSEAL server might be a member of different Active Directory domains (Kerberos realms).The client workstation is not logged in to the Active Directory domain.The client workstation is not specifying the correct host name to access the WebSEAL server. The value that is specified for the –princ option of the ktpass command must be the same host name that client uses to contact the Web security server. For example, for clients to contact the Web security server at https://diamond.subnet2.ibm.com and the Web security server is in the IBM.COM Kerberos realm, specify the following value for the –princ option: HTTP/diamond.subnet2.ibm.com@IBM.COMUnder certain circumstances, clients cannot be prevented from sending NTLM authentication tokens. Under these circumstances, you might not be able to directly use SPNEGO authentication with the WebSEAL server. Instead, you can configure the Web Server Plug-in for IIS to serve as an e-community SSO (ECSSO) master authentication server (MAS). In this configuration, the Web server plug-in must be configured to support both NTLM and SPNEGO tokens. The WebSEAL server can now receive ECSSO tokens from the MAS.Unable to authenticate

Cannot authenticate by using NTLM

When you attempt to access a Web security server, you receive the following error messages:

DPWWA2403E Your browser supplied NTLM authentication data.
NTLM is not supported by WebSEAL. Ensure that your browser
is configured to use Integrated Windows Authentication.

WebSEAL does not support NT LAN Manager (NTLM) authentication. Some browsers support NTLM authentication only or are configured to send NTLM authentication tokens instead of SPNEGO tokens. A browser that supports SPNEGO might be sending NTLM tokens for the following reasons:

Microsoft Internet Explorer is not configured with the WebSEAL server in the "Trusted sites" or "Local intranet" zone.

Microsoft Internet Explorer is not configured for Integrated Windows Authentication.

The client workstation and the WebSEAL server might be a member of different Active Directory domains (Kerberos realms).

The client workstation is not logged in to the Active Directory domain.

The client workstation is not specifying the correct host name to access the WebSEAL server. The value that is specified for the –princ option of the ktpass command must be the same host name that client uses to contact the Web security server.

For example, for clients to contact the Web security server at https://diamond.subnet2.ibm.com and the Web security server is in the IBM.COM Kerberos realm, specify the following value for the –princ option:

HTTP/diamond.subnet2.ibm.com@IBM.COM

Under certain circumstances, clients cannot be prevented from sending NTLM authentication tokens. Under these circumstances, you might not be able to directly use SPNEGO authentication with the WebSEAL server. Instead, you can configure the Web Server Plug-in for IIS to serve as an e-community SSO (ECSSO) master authentication server (MAS). In this configuration, the Web server plug-in must be configured to support both NTLM and SPNEGO tokens. The WebSEAL server can now receive ECSSO tokens from the MAS.

Parent topic: Unable to authenticate

Cannot complete authenticationHPDIA0220ImessagesHPDIA0220IKerberosauthentication, cannot complete When you attempt to access a security Web server, you receive the following error messages: HPDIA0220I Authentication requires continuation before completion status can be determined.This error occurs when the password used to encrypt the SPNEGO authentication data is not synchronized with the password that is used by the Web security server to decrypt the SPNEGO authentication data.On AIX, Linux, and Solaris operating systems, this error can be caused for the following reasons: The password for the Web security principal in Active Directory changed. When this password is changed, you must regenerate the SPNEGO key table.The SPNEGO key table was updated, but the client is still presenting an old authentication token. To clear the cached copy of the authentication token because SPNEGO authentication tokens are cached, log the client out of the workstation and log back in or restart the workstation.On Windows operating systems, this error can be caused for the following reasons: The Web security server might be running in the foreground instead of as a service. The Web security server must be running as a service to have access to the correct password needed to decrypt the security token.The password for the Web security principal in Active Directory changed. If the Windows service for the Web security server is configured to log on as the Local System account, you might need to restart the system. If the Windows service for the Web security server is configured to log on using a particular Active Directory domain account, you might need to update the Windows service Logon as configuration to specify the correct account and password.Both the password and the Windows service configuration were updated, but the client is still presenting an old authentication token. To clear the cached copy of the authentication token because SPNEGO authentication tokens are cached, log the client out of the workstation and log back in, or restart the workstation.Unable to authenticate

Cannot complete authentication

When you attempt to access a security Web server, you receive the following error messages:

HPDIA0220I Authentication requires continuation before
completion status can be determined.

This error occurs when the password used to encrypt the SPNEGO authentication data is not synchronized with the password that is used by the Web security server to decrypt the SPNEGO authentication data.

On AIX, Linux, and Solaris operating systems, this error can be caused for the following reasons:

The password for the Web security principal in Active Directory changed. When this password is changed, you must regenerate the SPNEGO key table.

The SPNEGO key table was updated, but the client is still presenting an old authentication token. To clear the cached copy of the authentication token because SPNEGO authentication tokens are cached, log the client out of the workstation and log back in or restart the workstation.

On Windows operating systems, this error can be caused for the following reasons:

The Web security server might be running in the foreground instead of as a service. The Web security server must be running as a service to have access to the correct password needed to decrypt the security token.

The password for the Web security principal in Active Directory changed. If the Windows service for the Web security server is configured to log on as the Local System account, you might need to restart the system. If the Windows service for the Web security server is configured to log on using a particular Active Directory domain account, you might need to update the Windows service "Logon as" configuration to specify the correct account and password.

Both the password and the Windows service configuration were updated, but the client is still presenting an old authentication token. To clear the cached copy of the authentication token because SPNEGO authentication tokens are cached, log the client out of the workstation and log back in, or restart the workstation.

Parent topic: Unable to authenticate

Common problems with WebSEAL serversCommon problems with WebSEAL serversCommon problems with WebSEAL serversThe following information details the common problems with WebSEAL servers. WebSEALcommon problemscommon problemsWebSEALFor more information about Security Access Manager WebSEAL, see the Administrating topics in the Knowledge Center.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Cannot customize basic authentication responseWebSEAL not responding on ports 80 or 443Servers fail to start because of exceeded LDAP replica server limitSecurity Access Manager supports a maximum of one host and nine LDAP replica servers, which are in the ldap.conf file. Multiple logins with e-communitye-Community SSO Master Authentication Server configured with EAIVerifying junctioned, third-party Web serverWebSEAL performance is degraded during file downloadsDPWWA0305E inconsistent message severityError when you create an LTPA junctionWhen you create a lightweight third-party authentication (LTPA) junction, you might receive an error that WebSEAL is unable to parse the LTPA key. Password change fails in a multi-domain environmentIn a multi-domain environment, WebSEAL can fail to change a user password because of insufficient ACL settings.Firefox does not send JSON POST requests correctlyWhen using the Firefox browser, JSON POST requests specified in the WebSEAL configuration file are not parsed. Your policies might produce incorrect or unexpected results.

Common problems with WebSEAL servers

The following information details the common problems with WebSEAL servers.

For more information about Security Access Manager WebSEAL, see the Administrating topics in the Knowledge Center.

Cannot customize basic authentication response

WebSEAL not responding on ports 80 or 443

Servers fail to start because of exceeded LDAP replica server limit
Security Access Manager supports a maximum of one host and nine LDAP replica servers, which are in the ldap.conf file.

Multiple logins with e-community

e-Community SSO Master Authentication Server configured with EAI

Verifying junctioned, third-party Web server

WebSEAL performance is degraded during file downloads

DPWWA0305E inconsistent message severity

Error when you create an LTPA junction
When you create a lightweight third-party authentication (LTPA) junction, you might receive an error that WebSEAL is unable to parse the LTPA key.

Password change fails in a multi-domain environment
In a multi-domain environment, WebSEAL can fail to change a user password because of insufficient ACL settings.

Firefox does not send JSON POST requests correctly
When using the Firefox browser, JSON POST requests specified in the WebSEAL configuration file are not parsed. Your policies might produce incorrect or unexpected results.

Parent topic: Troubleshooting

Cannot customize basic authentication responseuserscustomize response, unable to basic authentication, cannot customizecustom response to basic authenticationacct_locked.htmlWhen you use basic authentication (BA-auth) with Security Access Manager, you cannot customize the acct_locked.html file to contain more images. Although you can embed images in the file, subsequent requests to access the embedded images fail.To customize user authentication for your environment, use other authentication methods. For example, you can use forms authentication to bypass the authentication check when images from the error page are requested.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

Cannot customize basic authentication response

When you use basic authentication (BA-auth) with Security Access Manager, you cannot customize the acct_locked.html file to contain more images. Although you can embed images in the file, subsequent requests to access the embedded images fail.

To customize user authentication for your environment, use other authentication methods. For example, you can use forms authentication to bypass the authentication check when images from the error page are requested.

Parent topic: Common problems with WebSEAL servers

WebSEAL not responding on ports 80 or 443WebSEALportsports, WebSEALWebSEAL does not respond on either port 80 or port 443.Determine whether you have another web server that is installed on the WebSEAL system. For example, the IBM HTTP Server is commonly installed during the installation of Security Directory Server. If another Web server is on the same system as WebSEAL, reconfigure it to listen on ports other than the ports that are used by WebSEAL.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

WebSEAL not responding on ports 80 or 443

WebSEAL does not respond on either port 80 or port 443.

Determine whether you have another web server that is installed on the WebSEAL system. For example, the IBM® HTTP Server is commonly installed during the installation of Security Directory Server. If another Web server is on the same system as WebSEAL, reconfigure it to listen on ports other than the ports that are used by WebSEAL.

Parent topic: Common problems with WebSEAL servers

Servers fail to start because of exceeded LDAP replica server limitServers fail to start because of exceeded LDAP replica server limitSecurity Access Manager supports a maximum of one host and nine LDAP replica servers, which are in the ldap.conf file. LDAP serverldap.confHPDC00190EDPWWA0314EHPDAC0180E0x1005b3a3 errorIf more than nine LDAP replica entries are listed in the ldap.conf file, the Security Access Manager servers cannot start. The following errors indicate this problem:For the policy server:HPDC00190E Unable to configure LDAP replica "ldap10.ibm.com,3899,readonly,5" \ into server, errorcode=0xe9.where "ldap10.ibm.com,3899,readonly,5" indicates the 10th replica entry in the ldap.conf file.For WebSEAL:DPWWA0314E Initialization of authorization API failed. Major status =0x1, \ minor status = 0x1005b3a3For the authorization server:HPDAC0180E The Security Access Manager authorization server could not be started (0x1005b3a3). Please consult "Error Message Reference Guide" for explanation of minor error status 0x1005b3a3.To resolve the error, specify no more than nine replica LDAP servers in the replica entry of the [ldap] stanza in the ldap.conf file. For information about the replica entry of the [ldap] stanza in the ldap.conf file, see the Configuring topics in the Knowledge Center.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

Servers fail to start because of exceeded LDAP replica server limit

Security Access Manager supports a maximum of one host and nine LDAP replica servers, which are in the ldap.conf file.

If more than nine LDAP replica entries are listed in the ldap.conf file, the Security Access Manager servers cannot start. The following errors indicate this problem:

For the policy server:

HPDC00190E  Unable to configure LDAP replica
"ldap10.ibm.com,3899,readonly,5" \
into server, errorcode=0xe9.

where "ldap10.ibm.com,3899,readonly,5" indicates the 10th replica entry in the ldap.conf file.

For WebSEAL:

DPWWA0314E Initialization of authorization API failed. Major status =0x1, \
minor status = 0x1005b3a3

For the authorization server:

HPDAC0180E The Security Access Manager authorization server could not
be started (0x1005b3a3).
Please consult "Error Message Reference Guide" for explanation of
minor error status 0x1005b3a3.

To resolve the error, specify no more than nine replica LDAP servers in the replica entry of the [ldap] stanza in the ldap.conf file.

For information about the replica entry of the [ldap] stanza in the ldap.conf file, see the Configuring topics in the Knowledge Center.

Parent topic: Common problems with WebSEAL servers

Multiple logins with e-communityWebSEALe-communityWebSEALclock synchronizationWebSEALmaster authentication servere-community clock synchronizationclock synchronizatione-communitymaster authentication serverWebSEALWebSEAL e-community users are prompted to log in more than one time.This problem can occur if two WebSEAL servers are configured in the same domain. In these cases, one WebSEAL server is configured as the Master Authentication Server (MAS), and the other WebSEAL server is configured to use the MAS for authentication. Attempts to access the latter might require the user to log in more than one time if the difference in system times between the two WebSEAL servers is too great.To address this concern, synchronize the system time on each WebSEAL server that participates in an e-community.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

Multiple logins with e-community

WebSEAL e-community users are prompted to log in more than one time.

This problem can occur if two WebSEAL servers are configured in the same domain. In these cases, one WebSEAL server is configured as the Master Authentication Server (MAS), and the other WebSEAL server is configured to use the MAS for authentication. Attempts to access the latter might require the user to log in more than one time if the difference in system times between the two WebSEAL servers is too great.

To address this concern, synchronize the system time on each WebSEAL server that participates in an e-community.

Parent topic: Common problems with WebSEAL servers

e-Community SSO Master Authentication Server configured with EAIYou can configure e-Community single sign-on (SSO) so that the master authentication server (MAS) uses an external authentication service (EAI) to create a token for a consumer server. To use this configuration:Specify the MAS server as the default server.Enable EAI in the WebSEAL default configuration file.If you use virtual hosts, configure the WebSEAL virtual hosts configuration file (webseal-vh.conf) to use e-Community SSO. This configuration works for any virtual host junction that is defined in the virtual hosts configuration that is in the same domain that is defined for e-Community SSO.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

e-Community SSO Master Authentication Server configured with EAI

You can configure e-Community single sign-on (SSO) so that the master authentication server (MAS) uses an external authentication service (EAI) to create a token for a consumer server.

To use this configuration:

Specify the MAS server as the default server.

Enable EAI in the WebSEAL default configuration file.

If you use virtual hosts, configure the WebSEAL virtual hosts configuration file (webseal-vh.conf) to use e-Community SSO.

This configuration works for any virtual host junction that is defined in the virtual hosts configuration that is in the same domain that is defined for e-Community SSO.

Parent topic: Common problems with WebSEAL servers

Verifying junctioned, third-party Web serverjunctions, verifythird-party Web servers, verifyservercommandsserver task createcommandsserver task createVerifying the correct operation of a junctioned, third-party Web application server is similar to the procedure for WebSEAL. Enter the following URL into your browser to verify that the third-party Web server is functioning properly:http://junctioned-webserver-machinenameDo not specify a port number so that you can determine if the server is listening on port 80 (HTTP). If successful, the index.html page of the third-party Web server is displayed.The WebSEAL junction for the Web server is created with a pdadmin command. In the following example, the junction points to the third-party Web server in the WebSEAL /myjunction file space: pdadmin> server task webseald-webseal-machinename create -t tcp \ -p junctioned-server-port -h junctioned-webserver-machinename \ -c iv_user,iv_groups /myjunctionTry to access the index.html page on the junctioned Web server through WebSEAL with the following URL: webseal-machinename/myjunctionIf you configured the junction to use secure communication (–t ssl), your browser might issue warnings about the WebSEAL server certificate and prompt you for a user name and password. Enter sec_master for the user name and the appropriate password. If successful, the index.html page of the third-party Web server is displayed.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

Verifying junctioned, third-party Web server

Verifying the correct operation of a junctioned, third-party Web application server is similar to the procedure for WebSEAL. Enter the following URL into your browser to verify that the third-party Web server is functioning properly:

http://junctioned-webserver-machinename

Do not specify a port number so that you can determine if the server is listening on port 80 (HTTP). If successful, the index.html page of the third-party Web server is displayed.

The WebSEAL junction for the Web server is created with a pdadmin command. In the following example, the junction points to the third-party Web server in the WebSEAL /myjunction file space:

pdadmin> server task webseald-webseal-machinename create -t tcp \
-p junctioned-server-port -h junctioned-webserver-machinename \
-c iv_user,iv_groups /myjunction

Try to access the index.html page on the junctioned Web server through WebSEAL with the following URL:

webseal-machinename/myjunction

If you configured the junction to use secure communication (–t ssl), your browser might issue warnings about the WebSEAL server certificate and prompt you for a user name and password. Enter sec_master for the user name and the appropriate password. If successful, the index.html page of the third-party Web server is displayed.

Parent topic: Common problems with WebSEAL servers

WebSEAL performance is degraded during file downloadsIn Security Access Manager, you can use the io-buffer-size parameter in the [junction] stanza to configure the buffer size for reading and writing data to-and-from the junction. This value limits the amount of data that can be written from the socket to a junctioned server. The optimum value for this io-buffer-size parameter is 8191 bytes (one byte less than the typical TCP buffer size of 8 KB). Severe performance degradation might occur if the value of the io-buffer-size is larger than 8191.Similarly, you can use the io-buffer-size parameter in the [server] stanza to control the buffer size to read and write data to-and-from the client. The amount of data that can be written from the socket to an HTTP browser depends on the value of this parameter. For either of these io-buffer-size parameters, a small value (for instance, 10 bytes) can hurt performance by causing frequent calls to the low-level read/write APIs. Up to a certain point, larger values improve performance. However, if the io-buffer-size exceeds the size of low-level I/O functions, there is no longer any improvement in performance. Using an io-buffer-size value that is too high degrades performance.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

WebSEAL performance is degraded during file downloads

In Security Access Manager, you can use the io-buffer-size parameter in the [junction] stanza to configure the buffer size for reading and writing data to-and-from the junction. This value limits the amount of data that can be written from the socket to a junctioned server.

The optimum value for this io-buffer-size parameter is 8191 bytes (one byte less than the typical TCP buffer size of 8 KB). Severe performance degradation might occur if the value of the io-buffer-size is larger than 8191.

Similarly, you can use the io-buffer-size parameter in the [server] stanza to control the buffer size to read and write data to-and-from the client. The amount of data that can be written from the socket to an HTTP browser depends on the value of this parameter.

For either of these io-buffer-size parameters, a small value (for instance, 10 bytes) can hurt performance by causing frequent calls to the low-level read/write APIs. Up to a certain point, larger values improve performance. However, if the io-buffer-size exceeds the size of low-level I/O functions, there is no longer any improvement in performance. Using an io-buffer-size value that is too high degrades performance.

Parent topic: Common problems with WebSEAL servers

DPWWA0305E inconsistent message severityThe WebSEAL message log might include an entry such as the following that is recorded as a WARNING but that the code indicates is an ERROR and the error reference reports as FATAL. 2006-09-04-07:17:35.188+02:00I----- 0x38CF0131 webseald WARNING wwaserver s:\amweb600\src\pdweb\webseald\http\server\WsTcpListener.cpp 3930x000007c8 DPWWA0305E The 'pd_tcp_write' routine failed for 'WsTcpConnector::write', errno = 10054This issue is a common connection reset error. The error message reports that the other end of the connection terminated the connection. The correct severity level is WARNING. For more information about severity levels, see Severity of message eventsIn the message log file, each message event has an associated severity level. .Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

DPWWA0305E inconsistent message severity

The WebSEAL message log might include an entry such as the following that is recorded as a WARNING but that the code indicates is an ERROR and the error reference reports as FATAL.

2006-09-04-07:17:35.188+02:00I----- 0x38CF0131 webseald WARNING wwaserver
s:\amweb600\src\pdweb\webseald\http\server\WsTcpListener.cpp
3930x000007c8	DPWWA0305E     The 'pd_tcp_write' routine failed for
'WsTcpConnector::write', errno = 10054

This issue is a common connection reset error. The error message reports that the other end of the connection terminated the connection. The correct severity level is WARNING.

For more information about severity levels, see Severity of message events.

Parent topic: Common problems with WebSEAL servers

Error when you create an LTPA junctionWhen you create a lightweight third-party authentication (LTPA) junction, you might receive an error that WebSEAL is unable to parse the LTPA key. WebSphere Application Server does not add the "realm" component to a token unless global security is enabled, and WebSEAL expects this component to be present. To resolve this issue, configure global security for the LDAP registry in WebSphere and then regenerate the LTPA keyfile; WebSEAL can then successfully load the keyfile.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

Error when you create an LTPA junction

When you create a lightweight third-party authentication (LTPA) junction, you might receive an error that WebSEAL is unable to parse the LTPA key.

WebSphere® Application Server does not add the "realm" component to a token unless global security is enabled, and WebSEAL expects this component to be present. To resolve this issue, configure global security for the LDAP registry in WebSphere and then regenerate the LTPA keyfile; WebSEAL can then successfully load the keyfile.

Parent topic: Common problems with WebSEAL servers

Password change fails in a multi-domain environmentIn a multi-domain environment, WebSEAL can fail to change a user password because of insufficient ACL settings.Password change failsUpdate WebSEAL ACLsWebSEAL does not have correct ACL settings to search the Management Domain information in environments where: Security Access Manager Policy Server is configured in a non-default location. That is, a location other than secAuthority=Default.Security Access Manager subdomains exist.The WebSEAL instance is configured in one of the subdomains.In this situation, WebSEAL cannot successfully change user passwords because of the lack of correct ACL settings. You must set the correct ACLs so that WebSEAL can search the Management Domain and change user passwords in a multi-domain environment.The provided procedure is based on the following environment:The Management Domain name is Default.The Management Domain is in an LDAP Suffix that is called O=IBM,C=US.There are two subdomains that are called Domain1 and Domain2.You must modify the following steps to use the domain names and locations that match your environment.Create a file called aclEntry.ldif. Copy the following contents into the file: The two entries that start with aclentry: must each be entered as one line. ##------ START: Do not include this line -----## dn: secAuthority=Default,o=ibm,c=us changetype: modify add: aclentry aclentry:group:cn=SecurityGroup,SecAuthority=Domain1,cn=SubDomains, SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad:normal: rwsc:sensitive:rwsc:critical:rwsc:system:rsc aclentry:group:cn=SecurityGroup,SecAuthority=Domain2,cn=SubDomains, SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad:normal: rwsc:sensitive:rwsc:critical:rwsc:system:rsc ##------ END: Do not include this line -------##Save the file.Run the following command to update the ACL:ldapmodify -h host -p port -D cn=root -w pwd -i aclEntry.ldifWebSEAL can now successfully change user passwords.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

Password change fails in a multi-domain environment

In a multi-domain environment, WebSEAL can fail to change a user password because of insufficient ACL settings.

About this task

WebSEAL does not have correct ACL settings to search the Management Domain information in environments where:

Security Access Manager Policy Server is configured in a non-default location. That is, a location other than secAuthority=Default.

Security Access Manager subdomains exist.

The WebSEAL instance is configured in one of the subdomains.

In this situation, WebSEAL cannot successfully change user passwords because of the lack of correct ACL settings.

You must set the correct ACLs so that WebSEAL can search the Management Domain and change user passwords in a multi-domain environment.

The provided procedure is based on the following environment:

The Management Domain name is Default.

The Management Domain is in an LDAP Suffix that is called O=IBM,C=US.

There are two subdomains that are called Domain1 and Domain2.

Note: You must modify the following steps to use the domain names and locations that match your environment.

Procedure

Create a file called aclEntry.ldif.

Copy the following contents into the file:

Note: The two entries that start with aclentry: must each be entered as one line.

   ##------ START: Do not include this line -----##
   dn: secAuthority=Default,o=ibm,c=us
   changetype: modify
   add: aclentry
   aclentry:group:cn=SecurityGroup,SecAuthority=Domain1,cn=SubDomains,
					SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad:normal:
					rwsc:sensitive:rwsc:critical:rwsc:system:rsc
   aclentry:group:cn=SecurityGroup,SecAuthority=Domain2,cn=SubDomains,
					SecAuthority=Default,O=IBM,C=US,O=IBM,C=US:object:ad:normal:
					rwsc:sensitive:rwsc:critical:rwsc:system:rsc
   ##------ END: Do not include this line -------##

Save the file.

Run the following command to update the ACL:

ldapmodify -h host -p port -D cn=root -w pwd -i aclEntry.ldif

Results

WebSEAL can now successfully change user passwords.

Parent topic: Common problems with WebSEAL servers

Firefox does not send JSON POST requests correctlyFirefox does not send JSON POST requests correctlyFirefox does not send JSON POST requests correctlyWhen using the Firefox browser, JSON POST requests specified in the WebSEAL configuration file are not parsed. Your policies might produce incorrect or unexpected results. JSON POSTFirefox issueFirefox issueJSON POST requestsWebSEAL configuration fileJSON POST requestsIn the WebSEAL configuration file, you can capture JSON data for a custom attribute by using the [azn-decision-info] stanza. In that stanza, if you have an entry for post-data that specifies JSON POST data, it will not be parsed.Use an alternate browser when you have custom attributes configured that specify JSON POST requests. For example, use Chrome or Internet Explorer.Common problems with WebSEAL serversThe following information details the common problems with WebSEAL servers.

Firefox does not send JSON POST requests correctly

When using the Firefox browser, JSON POST requests specified in the WebSEAL configuration file are not parsed. Your policies might produce incorrect or unexpected results.

In the WebSEAL configuration file, you can capture JSON data for a custom attribute by using the [azn-decision-info] stanza. In that stanza, if you have an entry for post-data that specifies JSON POST data, it will not be parsed.

Use an alternate browser when you have custom attributes configured that specify JSON POST requests. For example, use Chrome or Internet Explorer.

Parent topic: Common problems with WebSEAL servers

Risk-Based Access External Authorization Service plug-inRisk-Based Access External Authorization Service plug-inThe Risk-Based Access (RBA) External Authorization Service (EAS) component provides a runtime XACML EAS plug-in for WebSEAL to enforce a policy decision. WebSEAL becomes the authorization enforcement point to access resources protected by RBA. Risk-Based AccessExternal Authorization Service (EAS) plug-inXACMLThe EAS collects context information about the user and the request, creates an XACML over SOAP decision request, and sends the information to the server. Manage the EAS with entries in the webseald.conf file.For more information about the risk-based EAS, see the Configuring topics in the IBM Knowledge Center. Search for Runtime security services external authorization service for details. For assistance in troubleshooting RBA EAS issues, you can enable tracing, then review the logs for information about any issue that might be occurring.Enabling External Authorization Service tracing on WebSEALTo enable tracing and logging for the XACML EAS plug-in, issue the following pdadmin command:pdadmin > server task WebSEAL_server_name trace set xacml_eas_comp_name 9 filepath=path_to_log_filewhere:webseal_server_nameIs the name of the WebSEAL server.xacml_eas_comp_nameIs the name of the XACML EAS component.path_to_log_fileIs the directory where you want to store the trace log file.For example:pdadmin > server task default-webseald-localhost trace set pdweb.xacml 9 file path=/tmp/xacml.log Tracing is disabled when you restart WebSEAL.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.

Risk-Based Access External Authorization Service plug-in

The Risk-Based Access (RBA) External Authorization Service (EAS) component provides a runtime XACML EAS plug-in for WebSEAL to enforce a policy decision. WebSEAL becomes the authorization enforcement point to access resources protected by RBA.

The EAS collects context information about the user and the request, creates an XACML over SOAP decision request, and sends the information to the server.

Manage the EAS with entries in the webseald.conf file.

For more information about the risk-based EAS, see the Configuring topics in the IBM Knowledge Center. Search for Runtime security services external authorization service for details.

For assistance in troubleshooting RBA EAS issues, you can enable tracing, then review the logs for information about any issue that might be occurring.

Enabling External Authorization Service tracing on WebSEAL

To enable tracing and logging for the XACML EAS plug-in, issue the following pdadmin command:

pdadmin > server task WebSEAL_server_name trace set xacml_eas_comp_name 9
filepath=path_to_log_file

where:

webseal_server_name

Is the name of the WebSEAL server.

xacml_eas_comp_name

Is the name of the XACML EAS component.

path_to_log_file

Is the directory where you want to store the trace log file.

For example:

pdadmin > server task default-webseald-localhost
trace set pdweb.xacml 9 file path=/tmp/xacml.log

Note: Tracing is disabled when you restart WebSEAL.

Parent topic: Troubleshooting

Troubleshooting certificate compliance issuesTroubleshooting compliance issuesTroubleshooting compliance issuesWhen you enable Security Access Manager applications to implement a security compliance standard, certain settings are required. certificate complianceFIPS 140-2NIST Special Publications 800-131aNational Security Agency (NSA) Suite BSuite BThe required settings apply to the standards of the following security settings: FIPS 140-2NIST Special Publications 800-131a (or SP 800-131a) TransitionNIST SP800-131a StrictNational Security Agency (NSA) Suite B 128 bitNSA Suite B 192 bitTo ensure a successful regeneration of the Security Access Manager side of the certificates, see the Administering topics in the IBM Knowledge Center. WebSphere Application Server, version 8.0, requires certain settings to properly enable compliance. See http://publib.boulder.ibm.com/infocenter/ieduasst/v1r1m0/index.jsp?topic=/com.ibm.iea.was_v8/was/8.0.0.3/Security/WASV8003_SecurityCryptoSignatureAlgorithm/player.htmlFor support for NIST SP 800-131 and NSA Suite B, you must use IBM WebSphere Application Server, version 8.0.0.3 or later.Other troubleshooting tips:Check browser configuration Your browser might not support or not be configured to support the TLS protocol.TLS 1.2 is not enabled by default. Check your browser documentation for instructions on how to enable TLS version 1.2. For example, for Internet Explorer, version 8 on Windows 7 and Windows 2008, go to ToolsInternet OptionsAdvanced (Tab)Security and select Use TLS 1.2.Check user registry configurationChanging an SSL protocol to TLS, version 1.2, can affect communication between WebSphere Application Server and the user registry. If you receive an error message about failed connection, check your user registry configuration. The user registry must support TLS, version 1.2, if you use an SSL connection.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.

Troubleshooting certificate compliance issues

When you enable Security Access Manager applications to implement a security compliance standard, certain settings are required.

The required settings apply to the standards of the following security settings:

FIPS 140-2

NIST Special Publications 800-131a (or SP 800-131a) Transition

NIST SP800-131a Strict

National Security Agency (NSA) Suite B 128 bit

NSA Suite B 192 bit

To ensure a successful regeneration of the Security Access Manager side of the certificates, see the Administering topics in the IBM Knowledge Center.

WebSphere® Application Server, version 8.0, requires certain settings to properly enable compliance. See

http://publib.boulder.ibm.com/infocenter/ieduasst/v1r1m0/index.jsp?topic=/com.ibm.iea.was_v8/was/8.0.0.3/Security/WASV8003_SecurityCryptoSignatureAlgorithm/player.html

For support for NIST SP 800-131 and NSA Suite B, you must use IBM® WebSphere Application Server, version 8.0.0.3 or later.

Other troubleshooting tips:

Check browser configuration

Your browser might not support or not be configured to support the TLS protocol.

TLS 1.2 is not enabled by default. Check your browser documentation for instructions on how to enable TLS version 1.2.

For example, for Internet Explorer, version 8 on Windows 7 and Windows 2008, go to Tools > Internet Options > Advanced (Tab) > Security and select Use TLS 1.2.

Check user registry configuration

Changing an SSL protocol to TLS, version 1.2, can affect communication between WebSphere Application Server and the user registry. If you receive an error message about failed connection, check your user registry configuration.

The user registry must support TLS, version 1.2, if you use an SSL connection.

Parent topic: Troubleshooting

Serviceability commandsThe following reference information describes the serviceability and problem determination pdadmin commands and utilities.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Reading syntax statementsServiceability and problem determination commandsserver listLists all registered Security Access Manager servers. server task traceServiceability and problem determination utilitiespdjservicelevelReturns the service level of installed Security Access Manager files that use the IBM Security Access Manager Runtime for Java package. pdservicelevelpdversionLists the current version of Security Access Manager components that are installed on the system.

Serviceability commands

The following reference information describes the serviceability and problem determination pdadmin commands and utilities.

Reading syntax statements

Serviceability and problem determination commands

server list
Lists all registered Security Access Manager servers.

server task trace

Serviceability and problem determination utilities

pdjservicelevel
Returns the service level of installed Security Access Manager files that use the IBM Security Access Manager Runtime for Java package.

pdservicelevel

pdversion
Lists the current version of Security Access Manager components that are installed on the system.

Parent topic: Troubleshooting

Reading syntax statementssyntax, readThe reference documentation uses the following special characters to define syntax: [ ]Identifies optional options. Options that are not enclosed in brackets are required....Indicates that you can specify multiple values for the previous option.|Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.{ }Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).\Indicates that the command line wraps to the next line. It is a continuation character.The options for each command or utility are listed alphabetically in the Options section or Parameters section. When the order of the options or parameters must be used in a specific order, this order is shown in the syntax statements.Serviceability commands

Reading syntax statements

The reference documentation uses the following special characters to define syntax:

[ ]

Identifies optional options. Options that are not enclosed in brackets are required.

...

Indicates that you can specify multiple values for the previous option.

|

Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.

{ }

Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).

\

Indicates that the command line wraps to the next line. It is a continuation character.

The options for each command or utility are listed alphabetically in the Options section or Parameters section. When the order of the options or parameters must be used in a specific order, this order is shown in the syntax statements.

Parent topic: Serviceability commands

Serviceability and problem determination commandsTable 1 lists the serviceability and problem determination commands that are available with the pdadmin utility. Serviceability and problem determination commandsCommandDescriptionserver listLists all registered Security Access Manager servers. Lists all registered Security Access Manager servers.server task traceEnables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing.For information about the command modes for the pdadmin utility, see the Command Reference topics in the Knowledge Center.Serviceability commands

Serviceability and problem determination commands

Table 292 lists the serviceability and problem determination commands that are available with the pdadmin utility.

Table 292. Serviceability and problem determination commands

Command | Description
server list | Lists all registered Security Access Manager servers.
server task trace | Enables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing.

For information about the command modes for the pdadmin utility, see the Command Reference topics in the Knowledge Center.

Parent topic: Serviceability commands

server listserver listserver listLists all registered Security Access Manager servers. server commandsserver listserver commandsserver listRequires authentication (administrator ID and password) to use this command.Syntaxserver list DescriptionLists all registered Security Access Manager servers. The name of the server for all server commands must be entered in the exact format as it is displayed in the output of this command. The server list command does not have such a requirement. OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See the Message topics in the Knowledge Center for more information. ExampleThe following example lists registered servers: pdadmin> server list The output is as follows: ivmgrd-master ivacld-server1 ivacld-server2where ivmgrd-master represents the Policy server; ivacld-server2 and ivacld-server1 represent Authorization server instances. Serviceability commands

server list

Lists all registered Security Access Manager servers.

Requires authentication (administrator ID and password) to use this command.

Syntax

server list

Description

Lists all registered Security Access Manager servers. The name of the server for all server commands must be entered in the exact format as it is displayed in the output of this command. The server list command does not have such a requirement.

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See the Message topics in the Knowledge Center for more information.

Example

The following example lists registered servers:

pdadmin> server list

The output is as follows:

ivmgrd-master
ivacld-server1
ivacld-server2

where ivmgrd-master represents the Policy server; ivacld-server2 and ivacld-server1 represent Authorization server instances.

Parent topic: Serviceability commands

server task traceserver commandsserver task traceserver commandsserver task tracetraceenableEnables the gathering of trace information for components of installed Security Access Manager servers or server instances. Requires authentication (administrator ID and password) to use this command.Syntax server task server_name–host_name trace list [component] server task server_name–host_name trace set component level [destination] server task server_name–host_name trace show [component] Description The server task trace command enables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing. The content of trace messages is generally undocumented and is intended to be used for debugging purposes only. The format and content of trace messages might vary between product releases. Options componentSpecifies the component for which to enable (set) tracing.destinationSpecifies where the gathered statistics are written, where destination can be one of the following: file path=file_nameSpecifies the fully qualified file name.log_agentSpecifies a destination for the statistics information gathered for the specified component. For more information about event logging, see the Administering topics in the Knowledge Center.levelSpecifies the level of tracing. The supported values for this option are 1 through 9, with 9 reporting the most detailed level of information in the trace log.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host cruz.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be cruz.dallas.ibm.com. For this example, the name of the server would be default-webseald-cruz.dallas.ibm.com. If there are multiple configured server instances on the same machine, for example, the host cruz.dallas.ibm.com, and the configured name of the WebSEAL server instance is webseal2-webseald, the server_name would be webseal2-webseald and the host_name would be cruz.dallas.ibm.com. For this example, the name of the server instance would be webseal2-webseald-cruz.dallas.ibm.com.trace list [component]Lists all enabled trace components that are available to gather and report trace information. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components.trace set component level [destination]Sets the trace level and trace message destination for a specific component and its subordinates. The value for the level option is a single integer from 1 to 9, with 9 reporting the most detailed level of information. The destination option specifies where the gathered trace information is written.trace show [component]Shows the names and levels for all enabled trace components. If you specify the component option, the output lists the name and level for the specified component. Return codes 0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). For more information, refer to the Messages topics in the Knowledge Center. Examples The following example enables the pdweb.debug trace component to level 2. Then displays the output for all enabled components. Note that WebSEAL–specific components are prefixed with pdweb. pdadmin sec_master> server task webseald-instance_name trace set pdweb.debug 2 pdadmin sec_master> server task webseald-instance_name trace showOutput from the trace show command is similar to: pdweb.debug 2The following example enables the pdwebpi.module.session-cookie trace component to level 9. Then displays the output for all enabled components. Components that are specific to the Web server plug-ins are prefixed with pdwebpi. pdadmin sec_master> server task pdwpi-tivoli.com trace set pdwebpi.module.session-cookie 9 pdadmin sec_master> server task pdwpi-tivoli.com trace showOutput from the trace show command is similar to: pdwebpi.module.session-cookie 9 See also server listLists all registered Security Access Manager servers. Serviceability commands

server task trace

Enables the gathering of trace information for components of installed Security Access Manager servers or server instances.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task server_name–host_name trace list [component]

server task server_name–host_name trace set component level [destination]

server task server_name–host_name trace show [component]

Description

The server task trace command enables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing. The content of trace messages is generally undocumented and is intended to be used for debugging purposes only. The format and content of trace messages might vary between product releases.

Options

component

Specifies the component for which to enable (set) tracing.

destination

Specifies where the gathered statistics are written, where destination can be one of the following:

file path=file_name

Specifies the fully qualified file name.

log_agent

Specifies a destination for the statistics information gathered for the specified component. For more information about event logging, see the Administering topics in the Knowledge Center.

level

Specifies the level of tracing. The supported values for this option are 1 through 9, with 9 reporting the most detailed level of information in the trace log.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host cruz.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be cruz.dallas.ibm.com. For this example, the name of the server would be default-webseald-cruz.dallas.ibm.com.

If there are multiple configured server instances on the same machine, for example, the host cruz.dallas.ibm.com, and the configured name of the WebSEAL server instance is webseal2-webseald, the server_name would be webseal2-webseald and the host_name would be cruz.dallas.ibm.com. For this example, the name of the server instance would be webseal2-webseald-cruz.dallas.ibm.com.

trace list [component]

Lists all enabled trace components that are available to gather and report trace information. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components.

trace set component level [destination]

Sets the trace level and trace message destination for a specific component and its subordinates. The value for the level option is a single integer from 1 to 9, with 9 reporting the most detailed level of information. The destination option specifies where the gathered trace information is written.

trace show [component]

Shows the names and levels for all enabled trace components. If you specify the component option, the output lists the name and level for the specified component.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). For more information, refer to the Messages topics in the Knowledge Center.

Examples

The following example enables the pdweb.debug trace component to level 2. Then displays the output for all enabled components. Note that WebSEAL–specific components are prefixed with pdweb.

pdadmin sec_master> server task webseald-instance_name trace set
pdweb.debug 2

pdadmin sec_master> server task webseald-instance_name trace show

Output from the trace show command is similar to:

pdweb.debug 2

The following example enables the pdwebpi.module.session-cookie trace component to level 9. Then displays the output for all enabled components. Components that are specific to the Web server plug-ins are prefixed with pdwebpi.

pdadmin sec_master> server task pdwpi-tivoli.com trace set
pdwebpi.module.session-cookie 9

pdadmin sec_master> server task pdwpi-tivoli.com trace show

Output from the trace show command is similar to:

pdwebpi.module.session-cookie 9

See also

server list

Parent topic: Serviceability commands

Serviceability and problem determination utilitiesTable 1 lists the serviceability and problem determination utilities. Serviceability and problem determination utilitiesUtilityDescriptionpdjservicelevelReturns the service level of installed Security Access Manager files that use the IBM Security Access Manager Runtime for Java package. Returns the service level of installed Security Access Manager files that use the IBM Security Access Manager Runtime for Java package.pdservicelevelReturns the service level of installed Security Access Manager files that use the Security Access Manager Runtime package.pdversionLists the current version of Security Access Manager components that are installed on the system.Lists the current version of Security Access Manager components that are installed on the system.Serviceability commands

Serviceability and problem determination utilities

Table 293 lists the serviceability and problem determination utilities.

Table 293. Serviceability and problem determination utilities

Utility | Description
pdjservicelevel | Returns the service level of installed Security Access Manager files that use the IBM Security Access Manager Runtime for Java package.
pdservicelevel | Returns the service level of installed Security Access Manager files that use the Security Access Manager Runtime package.
pdversion | Lists the current version of Security Access Manager components that are installed on the system.

Parent topic: Serviceability commands

pdjservicelevelpdjservicelevelpdjservicelevelReturns the service level of installed Security Access Manager files that use the IBM Security Access Manager Runtime for Java package. utilitiespdservicelevelpdservicelevel utilityThis utility is for use by support personnel.Syntaxpdjservicelevel directory DescriptionThe pdjservicelevel utility recursively scans the specified directory and returns the name and service level for each file to standard output. Only executable programs, shared libraries, archives, and other such files have a service level.If the service level for a file cannot be determined, the string "Unknown" is written to standard output. Generally, ASCII files and other such files do not have service levels.For this utility to determine the service level of a JAR file, the Java jar utility must exist in the system PATH statement. When the jar utility cannot be found, the service level that is reported for all JAR files is "Unknown". ParametersdirectorySpecifies the fully qualified name of the directory. AvailabilityThis utility is installed as part of the IBM Security Access Manager Runtime for Java package. It is in one of the following default installation directories: On AIX, Linux, and Solaris operating systems: /opt/PolicyDirector/sbinOn Windows operating systems: C:\Program Files\Tivoli\Policy Director\sbin When an installation directory other than the default is selected, this utility is in the /sbin directory under the installation directory (for example, installation_directory/sbin). Return codes0The utility completed successfully.1The utility failed. When a utility fails, a description of the error and an error status code in hexadecimal format is provided (for example, 0x15c3a00c). See the Messages topics in the Knowledge Center. Serviceability commands

pdjservicelevel

Returns the service level of installed Security Access Manager files that use the IBM Security Access Manager Runtime for Java package.

Note: This utility is for use by support personnel.

Syntax

pdjservicelevel directory

Description

The pdjservicelevel utility recursively scans the specified directory and returns the name and service level for each file to standard output. Only executable programs, shared libraries, archives, and other such files have a service level.

If the service level for a file cannot be determined, the string "Unknown" is written to standard output. Generally, ASCII files and other such files do not have service levels.

Note: For this utility to determine the service level of a JAR file, the Java™ jar utility must exist in the system PATH statement. When the jar utility cannot be found, the service level that is reported for all JAR files is "Unknown".

Parameters

directory

Specifies the fully qualified name of the directory.

Availability

This utility is installed as part of the IBM Security Access Manager Runtime for Java package. It is in one of the following default installation directories:

On AIX, Linux, and Solaris operating systems:

/opt/PolicyDirector/sbin

On Windows operating systems:

C:\Program Files\Tivoli\Policy Director\sbin

When an installation directory other than the default is selected, this utility is in the /sbin directory under the installation directory (for example, installation_directory/sbin).

Return codes

0

The utility completed successfully.

1

The utility failed. When a utility fails, a description of the error and an error status code in hexadecimal format is provided (for example, 0x15c3a00c). See the Messages topics in the Knowledge Center.

Parent topic: Serviceability commands

pdservicelevelpdservicelevelutilitiespdservicelevelpdservicelevel utilityReturns the service level of installed Security Access Manager files that use the Security Access Manager Runtime package. This utility is for use by support personnel.Syntax pdservicelevel directory Description The pdservicelevel utility recursively scans the specified directory and returns the name and service level for each file to standard output. Only executable programs, shared libraries, archives, and other such files have a service level. If the service level for a file cannot be determined, the string "Unknown" is written to standard output. Generally, ASCII files and other such files do not have service levels. For this utility to determine the service level of a JAR file, the Java jar utility must exist in the system PATH statement. When the jar utility cannot be found, the service level that is reported for all JAR files is "Unknown". Parameters directorySpecifies the fully qualified name of the directory. Availability This utility is installed as part of the Security Access Manager Runtime package. It is located in one of the following default installation directories: On AIX, Linux, and Solaris operating systems: /opt/PolicyDirector/sbinOn Windows operating systems: C:\Program Files\Tivoli\Policy Director\sbin When an installation directory other than the default is selected, this utility is located in the /sbin directory under the installation directory (for example, installation_directory/sbin). Return codes 0The utility completed successfully.1The utility failed. When a utility fails, a description of the error and an error status code in hexadecimal format is provided (for example, 0x15c3a00c). For more information, see the Messages topics in the Knowledge Center. Serviceability commands

pdservicelevel

Returns the service level of installed Security Access Manager files that use the Security Access Manager Runtime package.

Note: This utility is for use by support personnel.

Syntax

pdservicelevel directory

Description

The pdservicelevel utility recursively scans the specified directory and returns the name and service level for each file to standard output. Only executable programs, shared libraries, archives, and other such files have a service level.

If the service level for a file cannot be determined, the string "Unknown" is written to standard output. Generally, ASCII files and other such files do not have service levels.

Note: For this utility to determine the service level of a JAR file, the Java™ jar utility must exist in the system PATH statement. When the jar utility cannot be found, the service level that is reported for all JAR files is "Unknown".

Parameters

directory

Specifies the fully qualified name of the directory.

Availability

This utility is installed as part of the Security Access Manager Runtime package. It is located in one of the following default installation directories:

On AIX, Linux, and Solaris operating systems:

/opt/PolicyDirector/sbin

On Windows operating systems:

C:\Program Files\Tivoli\Policy Director\sbin

When an installation directory other than the default is selected, this utility is located in the /sbin directory under the installation directory (for example, installation_directory/sbin).

Return codes

0

The utility completed successfully.

1

The utility failed. When a utility fails, a description of the error and an error status code in hexadecimal format is provided (for example, 0x15c3a00c). For more information, see the Messages topics in the Knowledge Center.

Parent topic: Serviceability commands

pdversionpdversionpdversionLists the current version of Security Access Manager components that are installed on the system.utilitiespdversionpdversion utilitySyntaxpdversion [–key key1, key2...keyX] [–separator delimiter_character] Parameters–key key1, key2...keyXSpecifies the component or components of the current version. (Optional) The following are possible values of –key: pdacld – Security Access Manager Authorization Serverpdauthadk – Security Access Manager Application Developer Kitpdjrte – Security Access Manager Runtime for Javapdmgr – Security Access Manager Policy Serverpdrte – Security Access Manager Runtimepdsms – Security Access Manager Session Manager Serverpdweb – Security Access Manager WebSEALpdwebars – Security Access Manager Attribute Retrieval Servicepdwebadk – Security Access Manager Web Security ADKpdwebrte – Security Access Manager Web Security Runtimetivsecutl – IBM Tivoli Security UtilitiesThe version information for the various blades shows up when the blade packages are installed on the system. The following components are basic components:Security Access Manager RuntimeSecurity Access Manager Policy ServerSecurity Access ManagerWeb Portal ManagerSecurity Access Manager Application Developer KitSecurity Access Manager Authorization ServerSecurity Access Manager Runtime for Java The following components are blades:Security Access Manager WebSEALSecurity Access Manager web Security RuntimeSecurity Access Manager web Security ADK Security Access Manager Session Manager ServerSecurity Access Manager Attribute Retrieval Service–separator delimiter_characterSpecifies the separator that is used to delimit the description of the component from its version. (Optional) AvailabilityThis utility is in one of the following default installation directories: On AIX, Linux, and Solaris operating systems: /opt/PolicyDirector/binOn Windows operating systems: C:\Program Files\Tivoli\Policy Director\bin When an installation directory other than the default is selected, this utility is in the /bin directory under the installation directory (for example, installation directory/bin). Return codes0The utility completed successfully.1The utility failed. When a utility fails, a description of the error and an error status code in hexadecimal format is provided (for example, 0x15c3a00c). See the Messages topics in the Knowledge Center for more information. Serviceability commands

pdversion

Lists the current version of Security Access Manager components that are installed on the system.

Syntax

pdversion [–key key1, key2...keyX] [–separator delimiter_character]

Parameters

–key key1, key2...keyX

Specifies the component or components of the current version. (Optional) The following are possible values of –key:

pdacld – Security Access Manager Authorization Server

pdauthadk – Security Access Manager Application Developer Kit

pdjrte – Security Access Manager Runtime for Java™

pdmgr – Security Access Manager Policy Server

pdrte – Security Access Manager Runtime

pdsms – Security Access Manager Session Manager Server

pdweb – Security Access Manager WebSEAL

pdwebars – Security Access Manager Attribute Retrieval Service

pdwebadk – Security Access Manager Web Security ADK

pdwebrte – Security Access Manager Web Security Runtime

tivsecutl – IBM® Tivoli® Security Utilities

The version information for the various blades shows up when the blade packages are installed on the system. The following components are basic components:

Security Access Manager Runtime

Security Access Manager Policy Server

Security Access ManagerWeb Portal Manager

Security Access Manager Application Developer Kit

Security Access Manager Authorization Server

Security Access Manager Runtime for Java

The following components are blades:

Security Access Manager WebSEAL

Security Access Manager web Security Runtime

Security Access Manager web Security ADK

Security Access Manager Session Manager Server

Security Access Manager Attribute Retrieval Service

–separator delimiter_character

Specifies the separator that is used to delimit the description of the component from its version. (Optional)

Availability

This utility is in one of the following default installation directories:

On AIX, Linux, and Solaris operating systems:

/opt/PolicyDirector/bin

On Windows operating systems:

C:\Program Files\Tivoli\Policy Director\bin

When an installation directory other than the default is selected, this utility is in the /bin directory under the installation directory (for example, installation directory/bin).

Return codes

0

The utility completed successfully.

1

The utility failed. When a utility fails, a description of the error and an error status code in hexadecimal format is provided (for example, 0x15c3a00c). See the Messages topics in the Knowledge Center for more information.

Parent topic: Serviceability commands

Troubleshooting Advanced Access ControlUse the known problems, solutions, and limitations to troubleshoot the Advanced Access Control module.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Advanced Access Control known issues and solutionsDetermine if an issue you are having has a fix or a workaround.Advanced Access Control known limitationsConsider these known limitations when you are configuring an Advanced Access Control environment on the appliance.

Troubleshooting Advanced Access Control

Use the known problems, solutions, and limitations to troubleshoot the Advanced Access Control module.

Advanced Access Control known issues and solutions
Determine if an issue you are having has a fix or a workaround.

Advanced Access Control known limitations
Consider these known limitations when you are configuring an Advanced Access Control environment on the appliance.

Parent topic: Troubleshooting

Advanced Access Control known issues and solutionsKnown issues and solutionsKnown issues and solutionsDetermine if an issue you are having has a fix or a workaround.database deletionsknown issuecluster updateknown issuebrowserknown issues Help Systemknown issueWGASY0007E errorwga.cmd.timeout tuning parameterisamcfg SSL keyfileSSL keyfile stashWebSEAL configuration filedeploy request failsknown issuesadvanced access controlruntime server unable to obtain federated directory informationknown issuesadvanced access control Troubleshooting PIP server connections To troubleshoot connection errors, ensure that runtime tracing for the PIPs is enabled. In the local management interface, click Secure Access ControlGlobal SettingsRuntime ParametersRuntime Tracing.In the Tracing Specification field, type the tracing specifications for the PIPs: For JNDI (LDAP PIP) com.tivoli.am.rba.pip.LdapPIP=FINE javax.naming.*=FINE For JDBC (Database PIP) com.tivoli.am.rba.pip.JdbcPIP=FINE java.sql.*=FINE A trace level of FINE provides general trace, method entry, exit, and return values. For more detailed information, consider using FINER or FINEST as the trace level.Click Save. Removal of a server connection defined for a PIP causes a problem A problem with a policy information point (PIP) can be caused by: Deleting a server connection, especially if it is defined by a PIP and being used to return attributes in a policy or risk score.Updating the JNDI ID or host name of a server connection after it was already referenced in a PIP definition.Updating any of the server connection properties that are not valid after it was already referenced in a PIP definition. Solution: Review the list of server connections to determine whether any were deleted, and re-create any deleted server connections. Ensure that the PIP specifies the correct server connection: In the local management interface, click Secure Access Control.Under Policy, click Information Points.Select the server connection PIP and click Modify.In the Connection tab, locate the Server Connection field and determine whether it contains the correct server connection.Update the server connection, if necessary. WebSEAL sends client certificate by default The isamcfg tool can configure a WebSEAL or Web Reverse Proxy instance to use client certificate authentication to the run time. The run time can be configured to optionally accept client certificates. When configured in this mode, WebSEAL or the Web Reverse Proxy sends a client certificate regardless of whether a certificate label is specified in the configuration. Solution: If you require client certificate authentication, ensure that a valid client certificate is specified in the ssl-keyfile-label entry of the [rtss-cluser:<cluster name>] stanza. If you do not require client certificate authentication, either disable the optional acceptance of client certificates or specify an invalid client certificate label in the ssl-keyfile-label entry of the [rtss-cluser:<cluster name>] stanza. This method ensures that WebSEAL does not send a client certificate. A junction error occurs when a duplicate dn or certificate label is detected The isamcfg tool imports the Access Manager server certificate to the WebSEAL or Web Reverse Proxy keystore when it uses an SSL connection. If an entry exists in this keystore with the same dn or the same certificate label, an error can occur when it creates the junction to the Access Manager server. Solution: You must manually export the certificate that is presented by the run time and import it to the WebSEAL key database as a signer certificate. The junction then becomes accessible. The appliance fails to connect to the authorization service endpoint When the appliance is configured in FIPS and NIST SP800-131A compliant mode, the RBA EAS configured in the POC appliance fails to connect to the authorization service endpoint. This failure causes the RBA flow to fail. This issue also affects the ping call that is issued regularly. The connection fails because the authorization service EAS uses SSLv2, which is not supported by the appliance when it operates in the NIST SP800-131A strict compliant mode. Solution: In the appliance local management interface, select Reverse Proxy Settings<your instance>ManageConfigurationEdit configuration file. The Advanced Configuration File Editor opens. Add the parameter to the existing stanza.[rtss-cluster:cluster1] gsk-attr-name = enum:438:1Click Save.Deploy the changes.Restart the instance. Incorrectly formatted FORM or JSON data in custom attributes causes policy failure If a policy contains a custom attribute with incorrect FORM or JSON data, the policy fails and the user is not permitted to access the resource. Specifically, all of the following conditions apply:The WebSEAL configuration file contains a post-data entry in the [azn-decision-info] stanza.The <post-data-name> value for the post-data entry is not formatted properly. For example, the date format is not correct.The .datatype entry in the [user-attribute-definitions] stanza for this azn-decision-info attribute is a type other than string. Solution: Ensure that you specify the correct format for the data. For example: Valid date format is: yyyy-mm-ddzzzzzzFor example: 2013-05-20−06:00 Valid time format is: hh:mm:sszzzzzz For example: 13:12:36-06:00 Advanced Access Control cookies are not removed when a user logs out by using non-standard junction name or cookie namesThe Advanced Access Control runtime sets cookies for attribute collection purposes. The isamcfg tool configures a WebSEAL or Web Reverse Proxy configuration option to clean these cookies upon session termination. It uses the Advanced Access Control advanced configuration to determine which cookie values to clear. Solution:When the junction name attributeCollection.serviceLocation or cookie name attributeCollection.cookieName in the advanced configuration changes, you must run the isamcfg tool so that these changes are picked up.Access tokens are not cleared in a failed resource owner password credential flowThe access tokens that are generated from resource owner password credential flow are not cleared when resource owner password validation fails. These tokens must be removed so that malicious users cannot use the resource owner password credential flow to fill up the token cache by using a public client. Solution:In the pre-mapping rule, make a validate request to the user directory with the user name and password that you want to verify. This method stops the resource owner password credential flow before it generates the access token if the user name and password verification fails.For more information, see OAuth 2.0 mapping rule methodsCustomize the PreTokenGeneration and PostTokenGeneration mapping rules using these methods..The one-time password value cannot be validatedPolicies that permit one-time password obligations might result in an error if the user who made the access request did not set a secret key on the self-care secret key page.Solution: To ensure that users who encounter this error are directed to create their secret key, edit the error_could_not_validate_otp.html file and add a link that opens the self-care secret key page at /sps/mga/user/mgmt/html/otp/otp.html. For example, add the following link: <a "href="/sps/mga/user/mgmt/html/otp/otp.html"> Generate your Secret Key..</a>Attributes cause errors when hashed in attributeCollection.attributesHashEnabledIn the Advanced Configuration settings, any attribute that uses a matcher other than the exact matcher causes an error if it is hashed.Solution: Do not hash the following attributes with the attributeCollection.attributesHashEnabled setting of Advanced Configuration: ipAddressgeoLocationaccessTimePolicies with X.500 namesIf your LDAP root DN is secauthority=default, you can use the = (equal) operator only in policies that use X.500 names userDN and groupsDN. IP addresses are granted access despite their IP reputations Despite their IP reputation classifications, IP addresses are granted access. When the appliance cannot resolve the domain name for the license server, the IP reputation database cannot update. When the IP reputation database cannot update, it either contains inaccurate IP reputation data or no IP reputation data. You know that the IP reputation database cannot contact the license server when all IP addresses are granted access despite their IP reputations. If the following conditions are true, the IP reputation policy information point (PIP) might return an incorrect reputation: An administrator writes a policy that denies access based on IP reputation.The database cannot contact the license server. Solution: Configure direct access to the license server or indirect access to the license server. See the Administrating topics about the license server for more information. Error message is returned when IBM solidDB is used to deploy an external runtime database When you deploy an external runtime database with IBM solidDB, isam_access_control_soliddb.sql attempts to create a duplicate index on the RBA_USER_DEVICE table. The following error message is returned: SOLID Table Error 13199: Duplicate index definition Solution: Ignore this error message. Investigate any other error messages about the deployment of the run time database. Authentication alias message in startup logThe following message might be displayed in the runtime server startup log:I J2CA8050I: An authentication alias should be used instead of defining a user name and password on com.ibm.ws.jdbc.dataSource-config/properties-0Solution: Ignore this message. Creating access control policies during switch between daylight saving time and standard time If you create an access control policy when the appliance clock switches from daylight saving time (DST) to standard time (ST), the policy might not work as you expect. For example: Create an access control policy at 1:45 am on the Sunday when DST returns to ST.Modify the policy at 2:15 am DST, which is 1:15 am ST and within 1 hour of the creating the policy. The policy that you created in step 1 is used because it is newer (more recently created) than the modified policy in step 2. Solution: To correct this issue, modify and republish the policy that you want to use after 1:45 am standard time. Filter stops working after changing a parameter on the Advanced Configuration panel You can filter the data displayed on the Advanced Configuration panel. After you change a parameter and click the Change button, the filter is no longer applied to the displayed data. Solution: Click Enter next to the filter field to reapply the filter. Reverse proxy user password page is inaccessible After authenticating with the authentication mechanisms, the reverse proxy user password change page (/pkmspasswd) becomes inaccessible. Solution:This page is working as designed. The reverse proxy makes this page inaccessible for users who are authenticated with the External Authentication Interface (EAI). The authentication service relies on EAI to establish the authenticated session. Database failover capabilities vary during a cluster upgradeThe distributed session cache, runtime database, and configuration database have different failover capabilities during cluster upgrades. Database capabilitiesDatabase capabilitiesDatabaseBehaviour Distributed session cacheRuntime databaseIf the primary master fails, failover goes to secondary master. Changes are done in the secondary master and reconciliation occurs when primary master is restored.Configuration databaseIf the primary master fails, there is no failover to the secondary master. No changes are possible on the primary or secondary master until the primary master is back online.Issue 1When a high availability cluster is active, a situation exists during the firmware upgrade on the primary node where the configuration database is read-only. A read-only database prevents the upgrade process from writing to the configuration database when creating new tables, modifying schema of existing tables, and inserting or updating rows on tables.The reason the database on the primary node becomes read-only is the firmware upgrade requires the appliance to be rebooted. During a reboot, the high availability controller switches the secondary master to be read-write and act as the temporary primary master. When the primary node reboots and the database starts:It recognizes that the secondary node is in control and starts in read-only mode. The appliance cluster manager includes a background thread which will eventually switch the primary node to resume its role as the primary master database.The database on the primary node becomes writeable.However, during an upgrade, the database upgrade scripts are executed before the primary database has become writeable.Issue 2For the distributed session cache and runtime database, a situation exists where changes to the secondary databases are not reflected in the primary database after the completion of a cluster upgrade. Solution:To address Issue 1, make the cluster a single master cluster for the duration of the firmware upgrade: On the master node, use the Cluster Configuration panel to remove secondary settings and another high availability cluster member if applicable. Do not change the Primary setting.Wait for the cluster to synchronize.Upload and install the firmware .pkg on the primary node appliance. Restart the appliance.Upload and install the firmware .pkg to other cluster member appliances. Reboot each cluster member appliance.On the master node, use the Cluster Configuration panel to set high availability cluster members back to the original settings. Wait for the cluster to synchronize.The appliance firmwares have now been upgraded and the cluster is operational.To address Issue 2, stop traffic to the cluster before starting the upgrade.Error occurs after switching the runtime database in the applianceAfter you switch the runtime database from local to remote and deploying the pending changes, SQL-related runtime errors occur in the appliance. Solution: Restart the runtime.In the local management interface, select Secure Access ControlGlobal SettingsRuntime ParametersRuntime Status. Click Restart All Clustered Runtimes. Error code does not display for type mismatch of RESTful PIP The message.log contains an error message without an error code when the response type does not match the RESTful web service type. In the message log, you might see messages without an error code from com.tivoli.am.rba.pip.RestPIP. This problem occurs during RESTful PIP configuration if: You manually type a response type instead of selecting a predefined type. The type that you entered does not match the type received from the RESTful web service. Solution:Correct the RESTful PIP configuration in the local management interface. Verify that the response type you specify is correct for the PIP. Whenever possible, select a predefined type from the list instead of typing the response type. Firmware version and Last update information not displayed in Update History and Overview sectionFirmware information is not displayed in the Update History section of the user interface. Information on Last update is not displayed in the Overview section of the user interface. This is the case for firmware upgrades and fixpacks.The firmware version can be determined using the Firmware Settings user interface on the appliance. To determine the firmware version:Logon to the appliance as the administrator.Click Manage System Settings Firmware Settings. The active partition is reported. The Details column includes the firmware version.Alternatively, you can verify the firmware version from Manage System Settings Updates and LicensingOverview.Information on Last update not displaying is a known limitation. Default component port number usageWhen you assign port numbers during installation or configuration, do not use port numbers already assigned to other components. You might see unpredictable behavior if the same port number is assigned to multiple components.This is important when there are two Security Access Manager appliances and one of them has Advanced Access Control.Solution: Consider the following situation:If you set up external WebSEAL servers as part of the cluster configuration, do not assign port 9080 to the cluster configuration if the Support internal and external clients option is selected. Port 9080 is the default port assigned to WebSphere Application Server.The following table lists the default port numbers that you must be aware of when configuring components on a Security Access Manager appliance that also has Advanced Access Control. Do not assign them to other components. Default port numbers for Access Manager componentsComponentPort numberWebSphere Application Server9080, 9443Security Access Manager Policy Server7135Security Access Manager Authorization Server7136, 7137WebSEAL listening port7234Cluster configuration2020-2050LDAP server, SSL port 636Remote syslog514Local management interface (LMI)443WebSEAL HTTPS 443LDAP server, non-SSL port389WebSEAL HTTP80Deploy request fails A call to the Deploy the pending configuration changes web service (pending_changes/deploy) might fail.A call to the Deploy the pending configuration changes (pending_changes/deploy) web service returns an HTTP Internal Server Error.Solution: Retry the operation.Runtime server unable to obtain federated directory information from the local management interfaceIf the runtime server cannot contact the local management interface (LMI) under the following configuration settings, federated directory users cannot authenticate: Federated directories are used for username and password authentication. Resource owner password credentials (ROPC) are used for API protection.A user whose information is housed in a federated directory cannot authenticate through the username and password authentication mechanism or access API protection definitions that use resource owner password credentials. The runtime server attempts to contact the local management interface one time to obtain all federated directory information to authenticate federated directory users. If the runtime server cannot contact the local management interface for any reason, it cannot obtain the required federated directory information to authenticate federated directory users. For example: If the local management interface server is not running, the runtime server cannot obtain the necessary federated directory information to authenticate users in a federated directory. Solution: Follow these steps to ensure that this issue is resolved: Restart the local management interface:Use an ssh session to access the local management interface.Log in as the administrator.Type lmi and press Enter. Type restart and press Enter.Type exit and press Enter. Restart the runtime server: Log in to the local management interface.Select Secure Access ControlGlobal SettingsRuntime ParametersRuntime Status. Click Restart Local Runtime. Ensure that the runtime server can communicate with the local management interface so that it can obtain all of the necessary federated directory information.Troubleshooting Advanced Access ControlUse the known problems, solutions, and limitations to troubleshoot the Advanced Access Control module.

Advanced Access Control known issues and solutions

Determine if an issue you are having has a fix or a workaround.

Troubleshooting PIP server connections

To troubleshoot connection errors, ensure that runtime tracing for the PIPs is enabled.

In the local management interface, click Secure Access Control > Global Settings > Runtime Parameters > Runtime Tracing.

In the Tracing Specification field, type the tracing specifications for the PIPs:

For JNDI (LDAP PIP)

com.tivoli.am.rba.pip.LdapPIP=FINE
javax.naming.*=FINE

For JDBC (Database PIP)

com.tivoli.am.rba.pip.JdbcPIP=FINE
java.sql.*=FINE

Note: A trace level of FINE provides general trace, method entry, exit, and return values. For more detailed information, consider using FINER or FINEST as the trace level.

Click Save.

Removal of a server connection defined for a PIP causes a problem

A problem with a policy information point (PIP) can be caused by:

Deleting a server connection, especially if it is defined by a PIP and being used to return attributes in a policy or risk score.

Updating the JNDI ID or host name of a server connection after it was already referenced in a PIP definition.

Updating any of the server connection properties that are not valid after it was already referenced in a PIP definition.

Solution:

Review the list of server connections to determine whether any were deleted, and re-create any deleted server connections.

Ensure that the PIP specifies the correct server connection:

In the local management interface, click Secure Access Control.

Under Policy, click Information Points.

Select the server connection PIP and click Modify.

In the Connection tab, locate the Server Connection field and determine whether it contains the correct server connection.

Update the server connection, if necessary.

WebSEAL sends client certificate by default

The isamcfg tool can configure a WebSEAL or Web Reverse Proxy instance to use client certificate authentication to the run time. The run time can be configured to optionally accept client certificates. When configured in this mode, WebSEAL or the Web Reverse Proxy sends a client certificate regardless of whether a certificate label is specified in the configuration.

Solution:

If you require client certificate authentication, ensure that a valid client certificate is specified in the ssl-keyfile-label entry of the [rtss-cluser:<cluster name>] stanza. If you do not require client certificate authentication, either disable the optional acceptance of client certificates or specify an invalid client certificate label in the ssl-keyfile-label entry of the [rtss-cluser:<cluster name>] stanza. This method ensures that WebSEAL does not send a client certificate.

A junction error occurs when a duplicate dn or certificate label is detected

The isamcfg tool imports the Access Manager server certificate to the WebSEAL or Web Reverse Proxy keystore when it uses an SSL connection. If an entry exists in this keystore with the same dn or the same certificate label, an error can occur when it creates the junction to the Access Manager server.

Solution:

You must manually export the certificate that is presented by the run time and import it to the WebSEAL key database as a signer certificate. The junction then becomes accessible.

The appliance fails to connect to the authorization service endpoint

When the appliance is configured in FIPS and NIST SP800-131A compliant mode, the RBA EAS configured in the POC appliance fails to connect to the authorization service endpoint. This failure causes the RBA flow to fail. This issue also affects the ping call that is issued regularly. The connection fails because the authorization service EAS uses SSLv2, which is not supported by the appliance when it operates in the NIST SP800-131A strict compliant mode.

Solution:

In the appliance local management interface, select Reverse Proxy Settings > <your instance> > Manage > Configuration > Edit configuration file. The Advanced Configuration File Editor opens.

Add the parameter to the existing stanza.

[rtss-cluster:cluster1]
gsk-attr-name = enum:438:1

Click Save.

Deploy the changes.

Restart the instance.

Incorrectly formatted FORM or JSON data in custom attributes causes policy failure

If a policy contains a custom attribute with incorrect FORM or JSON data, the policy fails and the user is not permitted to access the resource. Specifically, all of the following conditions apply:

The WebSEAL configuration file contains a post-data entry in the [azn-decision-info] stanza.

The <post-data-name> value for the post-data entry is not formatted properly. For example, the date format is not correct.

The .datatype entry in the [user-attribute-definitions] stanza for this azn-decision-info attribute is a type other than string.

Solution:

Ensure that you specify the correct format for the data. For example:

Valid date format is: yyyy-mm-ddzzzzzz

For example: 2013-05-20−06:00

Valid time format is: hh:mm:sszzzzzz

For example: 13:12:36-06:00

Advanced Access Control cookies are not removed when a user logs out by using non-standard junction name or cookie names

The Advanced Access Control runtime sets cookies for attribute collection purposes. The isamcfg tool configures a WebSEAL or Web Reverse Proxy configuration option to clean these cookies upon session termination. It uses the Advanced Access Control advanced configuration to determine which cookie values to clear.

Solution:

When the junction name attributeCollection.serviceLocation or cookie name attributeCollection.cookieName in the advanced configuration changes, you must run the isamcfg tool so that these changes are picked up.

Access tokens are not cleared in a failed resource owner password credential flow

The access tokens that are generated from resource owner password credential flow are not cleared when resource owner password validation fails. These tokens must be removed so that malicious users cannot use the resource owner password credential flow to fill up the token cache by using a public client.

Solution:

In the pre-mapping rule, make a validate request to the user directory with the user name and password that you want to verify. This method stops the resource owner password credential flow before it generates the access token if the user name and password verification fails.

For more information, see OAuth 2.0 mapping rule methods.

The one-time password value cannot be validated

Policies that permit one-time password obligations might result in an error if the user who made the access request did not set a secret key on the self-care secret key page.

Solution: To ensure that users who encounter this error are directed to create their secret key, edit the error_could_not_validate_otp.html file and add a link that opens the self-care secret key page at /sps/mga/user/mgmt/html/otp/otp.html. For example, add the following link:

<a "href="/sps/mga/user/mgmt/html/otp/otp.html">
Generate your Secret Key..</a>

Attributes cause errors when hashed in attributeCollection.attributesHashEnabled

In the Advanced Configuration settings, any attribute that uses a matcher other than the exact matcher causes an error if it is hashed.

Solution: Do not hash the following attributes with the attributeCollection.attributesHashEnabled setting of Advanced Configuration:

ipAddress

geoLocation

accessTime

Policies with X.500 names

If your LDAP root DN is secauthority=default, you can use the = (equal) operator only in policies that use X.500 names userDN and groupsDN.

IP addresses are granted access despite their IP reputations

Despite their IP reputation classifications, IP addresses are granted access. When the appliance cannot resolve the domain name for the license server, the IP reputation database cannot update. When the IP reputation database cannot update, it either contains inaccurate IP reputation data or no IP reputation data.

You know that the IP reputation database cannot contact the license server when all IP addresses are granted access despite their IP reputations. If the following conditions are true, the IP reputation policy information point (PIP) might return an incorrect reputation:

An administrator writes a policy that denies access based on IP reputation.

The database cannot contact the license server.

Solution: Configure direct access to the license server or indirect access to the license server. See the Administrating topics about the license server for more information.

Error message is returned when IBM solidDB is used to deploy an external runtime database

When you deploy an external runtime database with IBM® solidDB®, isam_access_control_soliddb.sql attempts to create a duplicate index on the RBA_USER_DEVICE table. The following error message is returned:

SOLID Table Error 13199: Duplicate index definition

Solution: Ignore this error message. Investigate any other error messages about the deployment of the run time database.

Authentication alias message in startup log

The following message might be displayed in the runtime server startup log:

I J2CA8050I: An authentication alias should be used instead of defining a user name and password on com.ibm.ws.jdbc.dataSource-config/properties-0

Solution: Ignore this message.

Creating access control policies during switch between daylight saving time and standard time

If you create an access control policy when the appliance clock switches from daylight saving time (DST) to standard time (ST), the policy might not work as you expect. For example:

Create an access control policy at 1:45 am on the Sunday when DST returns to ST.

Modify the policy at 2:15 am DST, which is 1:15 am ST and within 1 hour of the creating the policy. The policy that you created in step 1 is used because it is newer (more recently created) than the modified policy in step 2.

Solution: To correct this issue, modify and republish the policy that you want to use after 1:45 am standard time.

Filter stops working after changing a parameter on the Advanced Configuration panel

You can filter the data displayed on the Advanced Configuration panel. After you change a parameter and click the Change button, the filter is no longer applied to the displayed data.

Solution: Click Enter next to the filter field to reapply the filter.

Reverse proxy user password page is inaccessible

After authenticating with the authentication mechanisms, the reverse proxy user password change page (/pkmspasswd) becomes inaccessible.

Solution:This page is working as designed. The reverse proxy makes this page inaccessible for users who are authenticated with the External Authentication Interface (EAI). The authentication service relies on EAI to establish the authenticated session.

Database failover capabilities vary during a cluster upgrade

The distributed session cache, runtime database, and configuration database have different failover capabilities during cluster upgrades.

Table 294. Database capabilities.

Database
Behaviour

Distributed session cache

Runtime database

If the primary master fails, failover goes to secondary master. Changes are done in the secondary master and reconciliation occurs when primary master is restored.

Configuration database
If the primary master fails, there is no failover to the secondary master. No changes are possible on the primary or secondary master until the primary master is back online.

Issue 1

When a high availability cluster is active, a situation exists during the firmware upgrade on the primary node where the configuration database is read-only.

A read-only database prevents the upgrade process from writing to the configuration database when creating new tables, modifying schema of existing tables, and inserting or updating rows on tables.

The reason the database on the primary node becomes read-only is the firmware upgrade requires the appliance to be rebooted. During a reboot, the high availability controller switches the secondary master to be read-write and act as the temporary primary master.

When the primary node reboots and the database starts:

It recognizes that the secondary node is in control and starts in read-only mode.

The appliance cluster manager includes a background thread which will eventually switch the primary node to resume its role as the primary master database.

The database on the primary node becomes writeable.

However, during an upgrade, the database upgrade scripts are executed before the primary database has become writeable.

Issue 2

For the distributed session cache and runtime database, a situation exists where changes to the secondary databases are not reflected in the primary database after the completion of a cluster upgrade.

Solution:

To address Issue 1, make the cluster a single master cluster for the duration of the firmware upgrade:

On the master node, use the Cluster Configuration panel to remove secondary settings and another high availability cluster member if applicable. Do not change the Primary setting.

Wait for the cluster to synchronize.

Upload and install the firmware .pkg on the primary node appliance.

Restart the appliance.

Upload and install the firmware .pkg to other cluster member appliances.

Reboot each cluster member appliance.

On the master node, use the Cluster Configuration panel to set high availability cluster members back to the original settings. Wait for the cluster to synchronize.

The appliance firmwares have now been upgraded and the cluster is operational.

To address Issue 2, stop traffic to the cluster before starting the upgrade.

Error occurs after switching the runtime database in the appliance

After you switch the runtime database from local to remote and deploying the pending changes, SQL-related runtime errors occur in the appliance.

Solution: Restart the runtime.

In the local management interface, select Secure Access Control > Global Settings > Runtime Parameters > Runtime Status.

Click Restart All Clustered Runtimes.

Error code does not display for type mismatch of RESTful PIP

The message.log contains an error message without an error code when the response type does not match the RESTful web service type. In the message log, you might see messages without an error code from com.tivoli.am.rba.pip.RestPIP.

This problem occurs during RESTful PIP configuration if:

You manually type a response type instead of selecting a predefined type.

The type that you entered does not match the type received from the RESTful web service.

Solution:

Correct the RESTful PIP configuration in the local management interface.

Verify that the response type you specify is correct for the PIP.

Whenever possible, select a predefined type from the list instead of typing the response type.

Firmware version and Last update information not displayed in Update History and Overview section

Firmware information is not displayed in the Update History section of the user interface. Information on Last update is not displayed in the Overview section of the user interface. This is the case for firmware upgrades and fixpacks.

The firmware version can be determined using the Firmware Settings user interface on the appliance.

To determine the firmware version:

Logon to the appliance as the administrator.

Click Manage System Settings > Firmware Settings. The active partition is reported. The Details column includes the firmware version.

Alternatively, you can verify the firmware version from Manage System Settings > Updates and Licensing > Overview.

Information on Last update not displaying is a known limitation.

Default component port number usage

When you assign port numbers during installation or configuration, do not use port numbers already assigned to other components. You might see unpredictable behavior if the same port number is assigned to multiple components.

This is important when there are two Security Access Manager appliances and one of them has Advanced Access Control.

Solution: Consider the following situation:

If you set up external WebSEAL servers as part of the cluster configuration, do not assign port 9080 to the cluster configuration if the Support internal and external clients option is selected. Port 9080 is the default port assigned to WebSphere Application Server.

The following table lists the default port numbers that you must be aware of when configuring components on a Security Access Manager appliance that also has Advanced Access Control. Do not assign them to other components.

Table 295. Default port numbers for Access Manager components

Component | Port number
WebSphere Application Server | 9080, 9443
Security Access Manager Policy Server | 7135
Security Access Manager Authorization Server | 7136, 7137
WebSEAL listening port | 7234
Cluster configuration | 2020-2050
LDAP server, SSL port | 636
Remote syslog | 514
Local management interface (LMI) | 443
WebSEAL HTTPS | 443
LDAP server, non-SSL port | 389
WebSEAL HTTP | 80

Deploy request fails

A call to the Deploy the pending configuration changes web service (pending_changes/deploy) might fail.

A call to the Deploy the pending configuration changes (pending_changes/deploy) web service returns an HTTP Internal Server Error.

Solution: Retry the operation.

Runtime server unable to obtain federated directory information from the local management interface

If the runtime server cannot contact the local management interface (LMI) under the following configuration settings, federated directory users cannot authenticate:

Federated directories are used for username and password authentication.

Resource owner password credentials (ROPC) are used for API protection.

A user whose information is housed in a federated directory cannot authenticate through the username and password authentication mechanism or access API protection definitions that use resource owner password credentials.

The runtime server attempts to contact the local management interface one time to obtain all federated directory information to authenticate federated directory users. If the runtime server cannot contact the local management interface for any reason, it cannot obtain the required federated directory information to authenticate federated directory users. For example: If the local management interface server is not running, the runtime server cannot obtain the necessary federated directory information to authenticate users in a federated directory.

Solution: Follow these steps to ensure that this issue is resolved:

Restart the local management interface:

Use an ssh session to access the local management interface.

Log in as the administrator.

Type lmi and press Enter.

Type restart and press Enter.

Type exit and press Enter.

Restart the runtime server:

Log in to the local management interface.

Select Secure Access Control > Global Settings > Runtime Parameters > Runtime Status.

Click Restart Local Runtime.

Ensure that the runtime server can communicate with the local management interface so that it can obtain all of the necessary federated directory information.

Parent topic: Troubleshooting Advanced Access Control

Advanced Access Control known limitationsKnown limitationsKnown limitationsConsider these known limitations when you are configuring an Advanced Access Control environment on the appliance.external clientslimitationdistributed session cachesupports internal clients onlysupport internal and external clients optionExternal clients cannot use the session cacheThe distributed session cache in the Advanced Access Control does not support external clients.The Support internal and external clients option on the Session Cache tab on the Cluster Configuration management page is not relevant in an Advanced Access Control environment. Advanced Access Control disregards the Port, Keyfile, and Label fields, which relate to external clients.Descriptions of default attribute and obligations might not display in the correct languageIf you clear your browser cache while logged into an appliance session, you might not see the descriptions of default attributes and obligations in the correct language. This scenario happens when you perform steps similar to these:Log in to the appliance.Change the language of the local management interface.Clear the browser cache.Display obligations or attributes. For example, to display the attributes:Select Secure Access Control.Under Policy, select Attributes. Under the name of each default attribute is the description. This description might display in an incorrect language.Therefore, do not clear the browser cache during an appliance session because you might see an incorrect language displayed in this scenario.Certain characters in JSON messages are displayed in UnicodeNon-ASCII characters are escaped in the JSON response from the REST API endpoints. This format is specified in RFC 4627. The non-ASCII character is represented as a six-character sequence: a reverse solidus, followed by the lowercase letter u, and followed by four hexadecimal digits that encode the code point of the character. For example, \u00e9. For more information, see RFC 4627.The Quick Response (QR) Code generator in Advanced Access Control only accepts US-ASCII alphanumeric characters as valid inputs Advanced Access Control can display the OAuth 2.0 authorization code as a QR code image.The QR code endpoint creates the QR code image. The endpoint is designed to accept US-ASCII alphanumeric characters only. This is to ensure maximum interoperability with existing QR code scanners.Ensure that only US-ASCII alphanumeric characters are used to create the QR code image.Authentication service cannot use the group information in the credentialYou can create a custom authentication mechanism by using the authentication mechanism Software Development Kit. Aside from authenticating the user, the authentication mechanism can modify the credential of the current user. After the user completes the execution of the authentication policy, which contains your custom authentication mechanism, the authentication service logs in the current user to IBM Security Access Manager by using the resulting credential. Advanced Access Control has a limitation that the group information in the resulting credential is not used by the authentication service to log in the current user to IBM Security Access Manager.Troubleshooting Advanced Access ControlUse the known problems, solutions, and limitations to troubleshoot the Advanced Access Control module.

Advanced Access Control known limitations

Consider these known limitations when you are configuring an Advanced Access Control environment on the appliance.

External clients cannot use the session cache

The distributed session cache in the Advanced Access Control does not support external clients.

The Support internal and external clients option on the Session Cache tab on the Cluster Configuration management page is not relevant in an Advanced Access Control environment.

Advanced Access Control disregards the Port, Keyfile, and Label fields, which relate to external clients.

Descriptions of default attribute and obligations might not display in the correct language

If you clear your browser cache while logged into an appliance session, you might not see the descriptions of default attributes and obligations in the correct language. This scenario happens when you perform steps similar to these:

Log in to the appliance.

Change the language of the local management interface.

Clear the browser cache.

Display obligations or attributes. For example, to display the attributes:

Select Secure Access Control.

Under Policy, select Attributes. Under the name of each default attribute is the description. This description might display in an incorrect language.

Therefore, do not clear the browser cache during an appliance session because you might see an incorrect language displayed in this scenario.

Certain characters in JSON messages are displayed in Unicode

Non-ASCII characters are escaped in the JSON response from the REST API endpoints. This format is specified in RFC 4627.

The non-ASCII character is represented as a six-character sequence: a reverse solidus, followed by the lowercase letter u, and followed by four hexadecimal digits that encode the code point of the character. For example, \u00e9. For more information, see RFC 4627.

The Quick Response (QR) Code generator in Advanced Access Control only accepts US-ASCII alphanumeric characters as valid inputs

Advanced Access Control can display the OAuth 2.0 authorization code as a QR code image.

The QR code endpoint creates the QR code image. The endpoint is designed to accept US-ASCII alphanumeric characters only. This is to ensure maximum interoperability with existing QR code scanners.

Ensure that only US-ASCII alphanumeric characters are used to create the QR code image.

Authentication service cannot use the group information in the credential

You can create a custom authentication mechanism by using the authentication mechanism Software Development Kit. Aside from authenticating the user, the authentication mechanism can modify the credential of the current user.

After the user completes the execution of the authentication policy, which contains your custom authentication mechanism, the authentication service logs in the current user to IBM Security Access Manager by using the resulting credential. Advanced Access Control has a limitation that the group information in the resulting credential is not used by the authentication service to log in the current user to IBM Security Access Manager.

Parent topic: Troubleshooting Advanced Access Control

Support InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.TroubleshootingThe Troubleshooting and support topics provide strategies for diagnosing and solving problems with IBM Security Access Manager.Techniques for troubleshooting problemsTroubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why something does not work as expected and how to resolve the problem. Certain common techniques can help with the task of troubleshooting.Searching knowledge basesYou can often find solutions to problems by searching IBM knowledge bases. You can optimize your results by using available resources, support tools, and search methods.Getting fixesA product fix might be available to resolve your problem.Contacting IBM SupportIBM Support assists with product defects, answers FAQs, and helps users resolve problems with the product.Exchanging information with IBMTo diagnose or identify a problem, you might need to provide IBM Support with data and information from your system. In other cases, IBM Support might provide you with tools or utilities to use for problem determination.Subscribing to Support updatesTo stay informed of important information about the IBM products that you use, you can subscribe to updates.

Support Information

To isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.

Techniques for troubleshooting problems
Troubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why something does not work as expected and how to resolve the problem. Certain common techniques can help with the task of troubleshooting.

Searching knowledge bases
You can often find solutions to problems by searching IBM knowledge bases. You can optimize your results by using available resources, support tools, and search methods.

Getting fixes
A product fix might be available to resolve your problem.

Contacting IBM Support
IBM Support assists with product defects, answers FAQs, and helps users resolve problems with the product.

Exchanging information with IBM
To diagnose or identify a problem, you might need to provide IBM Support with data and information from your system. In other cases, IBM Support might provide you with tools or utilities to use for problem determination.

Subscribing to Support updates
To stay informed of important information about the IBM products that you use, you can subscribe to updates.

Parent topic: Troubleshooting

Techniques for troubleshooting problemsTroubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why something does not work as expected and how to resolve the problem. Certain common techniques can help with the task of troubleshooting.troubleshootsupporttroubleshoot techniquestroubleshootidentifying problems, techniques forThe first step in the troubleshooting process is to describe the problem completely. Problem descriptions help you and the IBM technical-support representative know where to start to find the cause of the problem. This step includes asking yourself basic questions:What are the symptoms of the problem?Where does the problem occur?When does the problem occur?Under which conditions does the problem occur?Can the problem be reproduced? The answers to these questions typically lead to a good description of the problem, which can then lead you to a problem resolution. What are the symptoms of the problem?When you start to describe a problem, the most obvious question is What is the problem? This question might seem straightforward; however, you can break it down into several more-focused questions that create a more descriptive picture of the problem. These questions can include:Who, or what, is reporting the problem?What are the error codes and messages?How does the system fail? For example, is it a loop, hang, crash, performance degradation, or incorrect result?Where does the problem occur?Determining where the problem originates is not always easy, but it is one of the most important steps in resolving a problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and drivers are only a few of the components to consider when you are investigating problems.The following questions help you to focus on where the problem occurs to isolate the problem layer:Is the problem specific to one platform or operating system, or is it common across multiple platforms or operating systems?Is the current environment and configuration supported?Do all users have the problem?(For multi-site installations.) Do all sites have the problem?If one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a problem originates is understanding the environment in which it exists. Take some time to completely describe the problem environment, including the operating system and version, all corresponding software and versions, and hardware information. Confirm that you are running within an environment that is a supported configuration; many problems can be traced back to incompatible levels of software that are not intended to run together or were not fully tested together.When does the problem occur?Develop a detailed timeline of events that led up to a failure, especially for those cases that are one-time occurrences. You can most easily develop a timeline by working backward: Start at the time an error was reported (as precisely as possible, even down to the millisecond), and work backward through the available logs and information. Typically, you need to look only as far as the first suspicious event that you find in a diagnostic log.To develop a detailed timeline of events, answer these questions:Does the problem happen only at a certain time of day or night?How often does the problem happen?What sequence of events leads up to the time that the problem is reported?Does the problem happen after an environment change, such as upgrading or installing software or hardware?Responding to these types of questions can give you a frame of reference in which to investigate the problem.Under which conditions does the problem occur?Knowing which systems and applications are running at the time that a problem occurs is an important part of troubleshooting. These questions about your environment can help you to identify the root cause of the problem:Does the problem always occur when the same task is being completed? Does a certain sequence of events need to happen for the problem to occur?Do any other applications fail at the same time? Answering these types of questions can help you explain the environment in which the problem occurs and correlate any dependencies. Remember that just because multiple problems might occur around the same time, the problems are not necessarily related.Can the problem be reproduced?From a troubleshooting standpoint, the ideal problem is one that can be reproduced. Typically, when a problem can be reproduced you have a larger set of tools or procedures at your disposal to help you investigate. Problems that you can reproduce are often easier to debug and solve.However, problems that you can reproduce can have a disadvantage: If the problem is of significant business affect, you do not want it to recur. If possible, re-create the problem in a test or development environment, which typically offers you more flexibility and control during your investigation. Can the problem be re-created on a test system?Are multiple users or applications that encounter the same type of problem?Can the problem be re-created by running a single command, a set of commands, or a particular application?Support InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.

Techniques for troubleshooting problems

Troubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why something does not work as expected and how to resolve the problem. Certain common techniques can help with the task of troubleshooting.

The first step in the troubleshooting process is to describe the problem completely. Problem descriptions help you and the IBM technical-support representative know where to start to find the cause of the problem. This step includes asking yourself basic questions:

What are the symptoms of the problem?

Where does the problem occur?

When does the problem occur?

Under which conditions does the problem occur?

Can the problem be reproduced?

The answers to these questions typically lead to a good description of the problem, which can then lead you to a problem resolution.

What are the symptoms of the problem?

When you start to describe a problem, the most obvious question is "What is the problem?" This question might seem straightforward; however, you can break it down into several more-focused questions that create a more descriptive picture of the problem. These questions can include:

Who, or what, is reporting the problem?

What are the error codes and messages?

How does the system fail? For example, is it a loop, hang, crash, performance degradation, or incorrect result?

Where does the problem occur?

Determining where the problem originates is not always easy, but it is one of the most important steps in resolving a problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and drivers are only a few of the components to consider when you are investigating problems.

The following questions help you to focus on where the problem occurs to isolate the problem layer:

Is the problem specific to one platform or operating system, or is it common across multiple platforms or operating systems?

Is the current environment and configuration supported?

Do all users have the problem?

(For multi-site installations.) Do all sites have the problem?

If one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a problem originates is understanding the environment in which it exists. Take some time to completely describe the problem environment, including the operating system and version, all corresponding software and versions, and hardware information. Confirm that you are running within an environment that is a supported configuration; many problems can be traced back to incompatible levels of software that are not intended to run together or were not fully tested together.

When does the problem occur?

Develop a detailed timeline of events that led up to a failure, especially for those cases that are one-time occurrences. You can most easily develop a timeline by working backward: Start at the time an error was reported (as precisely as possible, even down to the millisecond), and work backward through the available logs and information. Typically, you need to look only as far as the first suspicious event that you find in a diagnostic log.

To develop a detailed timeline of events, answer these questions:

Does the problem happen only at a certain time of day or night?

How often does the problem happen?

What sequence of events leads up to the time that the problem is reported?

Does the problem happen after an environment change, such as upgrading or installing software or hardware?

Responding to these types of questions can give you a frame of reference in which to investigate the problem.

Under which conditions does the problem occur?

Knowing which systems and applications are running at the time that a problem occurs is an important part of troubleshooting. These questions about your environment can help you to identify the root cause of the problem:

Does the problem always occur when the same task is being completed?

Does a certain sequence of events need to happen for the problem to occur?

Do any other applications fail at the same time?

Answering these types of questions can help you explain the environment in which the problem occurs and correlate any dependencies. Remember that just because multiple problems might occur around the same time, the problems are not necessarily related.

Can the problem be reproduced?

From a troubleshooting standpoint, the ideal problem is one that can be reproduced. Typically, when a problem can be reproduced you have a larger set of tools or procedures at your disposal to help you investigate. Problems that you can reproduce are often easier to debug and solve.

However, problems that you can reproduce can have a disadvantage: If the problem is of significant business affect, you do not want it to recur. If possible, re-create the problem in a test or development environment, which typically offers you more flexibility and control during your investigation.

Can the problem be re-created on a test system?

Are multiple users or applications that encounter the same type of problem?

Can the problem be re-created by running a single command, a set of commands, or a particular application?

Parent topic: Support Information

Searching knowledge basesYou can often find solutions to problems by searching IBM knowledge bases. You can optimize your results by using available resources, support tools, and search methods.troubleshootsupportsearch knowledge basesYou can find useful information by searching the IBM Knowledge Center for this product. However, sometimes you need to look beyond the IBM Knowledge Center to answer your questions or resolve problems.To search knowledge bases for information that you need, use one or more of the following approaches: Search for content by using the IBM Support Assistant (ISA). ISA is a no-charge software serviceability workbench that helps you answer questions and resolve problems with IBM software products. You can find instructions for downloading and installing ISA on the ISA website.Find the content that you need by using the IBM Support Portal.The IBM Support Portal is a unified, centralized view of all technical support tools and information for all IBM systems, software, and services. The IBM Support Portal lets you access the IBM electronic support portfolio from one place. You can tailor the pages to focus on the information and resources that you need for problem prevention and faster problem resolution. Familiarize yourself with the IBM Support Portal by viewing the demo videos (https://www.ibm.com/blogs/SPNA/entry/the_ibm_support_portal_videos) about this tool. These videos introduce you to the IBM Support Portal, explore troubleshooting and other resources, and demonstrate how you can tailor the page by moving, adding, and deleting portlets. Search for content by using the IBM masthead search. You can use the IBM masthead search by typing your search string into the Search field at the top of any ibm.com page. Search for content by using any external search engine, such as Google, Yahoo, or Bing. If you use an external search engine, your results are more likely to include information that is outside the ibm.com domain. However, sometimes you can find useful problem-solving information about IBM products in newsgroups, forums, and blogs that are not on ibm.com.Include IBM and the name of the product in your search if you are looking for information about an IBM product.Support InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.

Searching knowledge bases

You can often find solutions to problems by searching IBM knowledge bases. You can optimize your results by using available resources, support tools, and search methods.

About this task

You can find useful information by searching the IBM® Knowledge Center for this product. However, sometimes you need to look beyond the IBM Knowledge Center to answer your questions or resolve problems.

Procedure

To search knowledge bases for information that you need, use one or more of the following approaches:

Search for content by using the IBM Support Assistant (ISA).

ISA is a no-charge software serviceability workbench that helps you answer questions and resolve problems with IBM software products. You can find instructions for downloading and installing ISA on the ISA website.

Find the content that you need by using the IBM Support Portal.

The IBM Support Portal is a unified, centralized view of all technical support tools and information for all IBM systems, software, and services. The IBM Support Portal lets you access the IBM electronic support portfolio from one place. You can tailor the pages to focus on the information and resources that you need for problem prevention and faster problem resolution. Familiarize yourself with the IBM Support Portal by viewing the demo videos (https://www.ibm.com/blogs/SPNA/entry/the_ibm_support_portal_videos) about this tool. These videos introduce you to the IBM Support Portal, explore troubleshooting and other resources, and demonstrate how you can tailor the page by moving, adding, and deleting portlets.

Search for content by using the IBM masthead search. You can use the IBM masthead search by typing your search string into the Search field at the top of any ibm.com® page.

Search for content by using any external search engine, such as Google, Yahoo, or Bing. If you use an external search engine, your results are more likely to include information that is outside the ibm.com domain. However, sometimes you can find useful problem-solving information about IBM products in newsgroups, forums, and blogs that are not on ibm.com.

Tip: Include "IBM" and the name of the product in your search if you are looking for information about an IBM product.

Parent topic: Support Information

Getting fixesA product fix might be available to resolve your problem.troubleshoot supportFix CentralTo find and install fixes:Obtain the tools required to get the fix.This step is optional, depending on whether your product requires the use of installation tools (for example, an update installer). If you include this step, describe all of the sub-steps that are required to obtain and configure these tools.Determine which fix you need.Many Support teams maintain a Recommended fixes document in DCF. Alternately, if your product Support team recommends using Fix Central to find fixes, see the Getting fixes from Fix Central topic template. If your team does not use either of these processes, you need to provide details here about how users decide what fix to obtain or refer to the Searching knowledge bases topic. Download the fix. Open the download document and follow the link in the Download package section.Instructions for this step are likely to be specific to your product. Apply the fix. Follow the instructions in the Installation Instructions section of the download document.Instructions for this step are likely to be specific to your product. Subscribe to receive weekly email notifications about fixes and other IBM Support information.Assuming that you include this step (which is optional for users to perform but highly recommended for authoring teams to include), be sure to provide a related link to your Subscribing to Support updates topic.Support InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.Getting fixes from Fix CentralYou can use Fix Central to find the fixes for IBM products. With Fix Central, you can search, select, order, and download fixes for your system with a choice of delivery options. A product fix might be available to resolve your problem.

Getting fixes

A product fix might be available to resolve your problem.

About this task

Procedure

To find and install fixes:

Obtain the tools required to get the fix.

Determine which fix you need.

Download the fix. Open the download document and follow the link in the "Download package" section.

Apply the fix. Follow the instructions in the "Installation Instructions" section of the download document.

Subscribe to receive weekly email notifications about fixes and other IBM Support information.

Getting fixes from Fix Central
You can use Fix Central to find the fixes for IBM products. With Fix Central, you can search, select, order, and download fixes for your system with a choice of delivery options. A product fix might be available to resolve your problem.

Parent topic: Support Information

Getting fixes from Fix CentralYou can use Fix Central to find the fixes for IBM products. With Fix Central, you can search, select, order, and download fixes for your system with a choice of delivery options. A product fix might be available to resolve your problem. troubleshootsupportfixesFix Central, get fixesTo find and install fixes:Obtain the tools that are required to get the fix. If it is not installed, obtain your product update installer. You can download the installer from Fix Central. This site provides download, installation, and configuration instructions for the update installer.Select the product, and select one or more check box that are relevant to the problem that you want to resolve. Explain initial and subsequent drill-down selections to determine the fixes for a product, based on either system or software specifications. For details, see: http://www.ibm.com/systems/support/fixes/en/fixcentral/help/faq_sw.htmlIdentify and select the fix that is required.Instructions for this step are likely to be specific to your product. Download the fix. Instructions for this step are likely to be specific to your product. Explain how to download or order fixes on media.Open the download document and follow the link in the Download Package section. When downloading the file, ensure that the name of the maintenance file is not changed. This change might be intentional, or it might be an inadvertent change that is caused by certain web browsers or download utilities.Apply the fix. Instructions for this step are likely to be specific to your product. Follow the instructions in the Installation Instructions section of the download document.For more information, see the Installing fixes with the Update Installer topic in the product documentation. Subscribe to receive weekly email notifications about fixes and other IBM Support updates.Assuming that you include this step (which is optional for users to perform but highly recommended for authoring teams to include), be sure to provide a related link to your Subscribing to Support updates topic.Getting fixesA product fix might be available to resolve your problem.

Getting fixes from Fix Central

You can use Fix Central to find the fixes for IBM products. With Fix Central, you can search, select, order, and download fixes for your system with a choice of delivery options. A product fix might be available to resolve your problem.

Procedure

To find and install fixes:

Obtain the tools that are required to get the fix. If it is not installed, obtain your product update installer. You can download the installer from Fix Central. This site provides download, installation, and configuration instructions for the update installer.

Select the product, and select one or more check box that are relevant to the problem that you want to resolve.

Identify and select the fix that is required.

Download the fix.

Open the download document and follow the link in the "Download Package" section.

When downloading the file, ensure that the name of the maintenance file is not changed. This change might be intentional, or it might be an inadvertent change that is caused by certain web browsers or download utilities.

Apply the fix.

Follow the instructions in the "Installation Instructions" section of the download document.

For more information, see the "Installing fixes with the Update Installer" topic in the product documentation.

Optional: Subscribe to receive weekly email notifications about fixes and other IBM Support updates.

Parent topic: Getting fixes

Contacting IBM SupportContacting IBM SupportContacting IBM SupportIBM Support assists with product defects, answers FAQs, and helps users resolve problems with the product.support, contact IBM SupportAfter you try to find your answer or solution by using other self-help options such as technotes, you can contact IBM Support. Before you contact IBM Support, your company or organization must have an active IBM software subscription and support contract, and you must be authorized to submit problems to IBM. For information about the types of available support, see the Support portfolio topic in the Software Support Handbook.Insert all of the instructions that are relevant for your product. For hardware products, the support process depends on the product offering. The following procedure is based on IBM Software Support details. To contact IBM Support about a problem:Define the problem, gather background information, and determine the severity of the problem. For more information, see the Getting IBM support topic in the Software Support Handbook.Gather diagnostic information. If your product has enabled the automatic data collection feature in ISA, describe how to use that feature. If you have created Collecting data troubleshooting topics, refer to them here.Submit the problem to IBM Support in one of the following ways:Using IBM Support Assistant (ISA): Describe how to submit a problem with ISA, if your product has enabled the Service Request feature. Here is some sample text (which should be reviewed by your Support team before you use it): Any data that has been collected can be attached to the service request. Using ISA in this way can expedite the analysis and reduce the time to resolution.Online through the IBM Support Portal: You can open, update, and view all of your service requests from the Service Request portlet on the Service Request page.By telephone for critical, system down, or severity 1 issues: For the phone number to call in your region, see the Directory of worldwide contacts web page.If the problem that you submit is for a software defect or for missing or inaccurate documentation, IBM Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the IBM Support website daily, so that other users who experience the same problem can benefit from the same resolution.Suggest including related links to the Contacting IBM Support and Exchanging information with IBM topics.Support InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.

Contacting IBM Support

IBM Support assists with product defects, answers FAQs, and helps users resolve problems with the product.

Before you begin

After you try to find your answer or solution by using other self-help options such as technotes, you can contact IBM Support. Before you contact IBM Support, your company or organization must have an active IBM software subscription and support contract, and you must be authorized to submit problems to IBM®. For information about the types of available support, see the Support portfolio topic in the "Software Support Handbook".

Procedure

To contact IBM Support about a problem:

Define the problem, gather background information, and determine the severity of the problem. For more information, see the Getting IBM support topic in the Software Support Handbook.

Gather diagnostic information.

Submit the problem to IBM Support in one of the following ways:

Using IBM Support Assistant (ISA):

Online through the IBM Support Portal: You can open, update, and view all of your service requests from the Service Request portlet on the Service Request page.

By telephone for critical, system down, or severity 1 issues: For the phone number to call in your region, see the Directory of worldwide contacts web page.

Results

If the problem that you submit is for a software defect or for missing or inaccurate documentation, IBM Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the IBM Support website daily, so that other users who experience the same problem can benefit from the same resolution.

What to do next

Parent topic: Support Information

Exchanging information with IBMTo diagnose or identify a problem, you might need to provide IBM Support with data and information from your system. In other cases, IBM Support might provide you with tools or utilities to use for problem determination.troubleshoot supportIBM Support, send informationproblem determinationexchange information with IBM SupportSupport InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.Sending information to IBM SupportTo reduce the time that is required to resolve your problem, you can send trace and diagnostic information to IBM Support. To submit diagnostic information to IBM Support:Open a problem management record (PMR).If you provide a topic to help users open a PMR (such as a topic about IBM Support Assistant or the Service Request tool), link to that topic in step 1. If you do not provide a topic about opening a PMR, you can either add a sentence here and provide external links to these tools (links can be copied from step 4 in this task) or add nothing else to the step.Collect the diagnostic data that you need. Diagnostic data helps reduce the time that it takes to resolve your PMR. You can collect the diagnostic data manually or automatically: The content in the choice list assumes that users can collect data manually or automatically. If that is not the case, rewrite the introduction to the list and remove the choice list, keeping only the method that applies.Collect the data manually. If you provide Collecting data topics in your troubleshooting information, add a sentence "See <link to Collecting data for Product X. Edit the sentence as appropriate, for example if you have multiple Collecting data topics, you can include links to all of them.Collect the data automatically. You need to fill in the details here. If you mention the ISA Lite or ISA WB tools in your set of troubleshooting topics, mention the tools that apply here and link to the topics for those tools. For example, "Use ISA Lite to collect the data that you need. See <link to your tools topic that mentions ISA Lite>." If you do not mention the ISA Lite or ISA WB tools in your set of topics, add external links to the web pages for the ISA Lite or ISA WB tools on the IBM Support site here. If automatic data collection is not available for your product, remove the choice list and mention only the manual method for step 2.Compress the files by using the .zip or .tar file format.Transfer the files to IBM. You can use one of the following methods to transfer the files to IBM:Remove any of the following list items that do not apply directly to your product. If only one bullet remains, remove the list and use a paragraph format.IBM Support AssistantThe Service Request toolStandard data upload methods: FTP, HTTPSecure data upload methods: FTPS, SFTP, HTTPSEmailAll of these data exchange methods are explained on the IBM Support website.Verify that the link is current. Receiving information from IBM SupportOccasionally an IBM technical-support representative might ask you to download diagnostic tools or other files. You can use FTP to download these files.Ensure that your IBM technical-support representative provided you with the preferred server to use for downloading the files and the exact directory and file names to access.To download files from IBM Support:Use FTP to connect to the site that your IBM technical-support representative provided and log in as anonymous. Use your email address as the password.Change to the appropriate directory: Change to the /fromibm directory. cd fromibmChange to the directory that your IBM technical-support representative provided.cd nameofdirectoryEnable binary mode for your session.binaryUse the get command to download the file that your IBM technical-support representative specified.get filename.extensionEnd your FTP session.quit

Exchanging information with IBM

To diagnose or identify a problem, you might need to provide IBM Support with data and information from your system. In other cases, IBM Support might provide you with tools or utilities to use for problem determination.

Parent topic: Support Information

Sending information to IBM Support

To reduce the time that is required to resolve your problem, you can send trace and diagnostic information to IBM Support.

Procedure

To submit diagnostic information to IBM Support:

Open a problem management record (PMR).

Collect the diagnostic data that you need. Diagnostic data helps reduce the time that it takes to resolve your PMR. You can collect the diagnostic data manually or automatically:

Collect the data manually.

Collect the data automatically.

Compress the files by using the .zip or .tar file format.

Transfer the files to IBM. You can use one of the following methods to transfer the files to IBM:

IBM® Support Assistant

The Service Request tool

Standard data upload methods: FTP, HTTP

Secure data upload methods: FTPS, SFTP, HTTPS

Email

All of these data exchange methods are explained on the IBM Support website.

Receiving information from IBM Support

Occasionally an IBM technical-support representative might ask you to download diagnostic tools or other files. You can use FTP to download these files.

Before you begin

Ensure that your IBM technical-support representative provided you with the preferred server to use for downloading the files and the exact directory and file names to access.

Procedure

To download files from IBM Support:

Use FTP to connect to the site that your IBM technical-support representative provided and log in as anonymous. Use your email address as the password.

Change to the appropriate directory:

Change to the /fromibm directory.

cd fromibm

Change to the directory that your IBM technical-support representative provided.

cd nameofdirectory

Enable binary mode for your session.

binary

Use the get command to download the file that your IBM technical-support representative specified.

get filename.extension

End your FTP session.

quit

Subscribing to Support updates To stay informed of important information about the IBM products that you use, you can subscribe to updates. troubleshootsupportsubscribe to Support updatesBy subscribing to receive updates about this product, you can receive important technical information and updates for specific IBM Support tools and resources. You can subscribe to updates by using one of two approaches:RSS feeds and social media subscriptionsFor general information about RSS, including steps for getting started and a list of RSS-enabled IBM web pages, visit the IBM Software Support RSS feeds site.My NotificationsWith My Notifications, you can subscribe to Support updates for any IBM product. (My Notifications replaces My Support, which is a similar tool that you might have used in the past.) With My Notifications, you can specify that you want to receive daily or weekly email announcements. You can specify what type of information you want to receive (such as publications, hints, and tips, product flashes (also known as alerts), downloads, and drivers). My Notifications enable you to customize and categorize the products about which you want to be informed and the delivery methods that best suit your needs. To subscribe to Support updates: If your Support team has already published instructions to help users register for My Notifications, replace the steps about My Notifications with a link to the existing information.Subscribe to the RSS feeds by accessing the IBM Software Support RSS feeds site and subscribe to the product feed.If you have no RSS feeds to mention, delete this step. If you have one RSS feed to mention, provide that information in this step. If you have multiple RSS feeds, add another step for the second (or nth) RSS feed.Subscribe to My Notifications by going to the IBM Support Portal and click My Notifications in the Notifications portlet.Sign in using your IBM ID and password, and click Submit.Identify what and how you want to receive updates.Click the Subscribe tab.Select the appropriate software brand or type of hardware. If your topic is for one particular product in one particular brand, you can change the text in this and next substep to be more precise. If you tell the user to click a specific brand or product name, use the <uicontrol> element.Select one or more products by name and click Continue.Select your preferences for how to receive updates, whether by email, online in a designated folder, or as an RSS or Atom feed.Select the types of documentation updates that you want to receive, for example, new information about product downloads and discussion group comments. Click Submit.If your topic does not include RSS feed or social media information, modify the text in this paragraph accordingly.Until you modify your RSS feeds and My Notifications preferences, you receive notifications of updates that you requested. You can modify your preferences when needed (for example, if you stop using one product and begin using another product).Delete the related link about RSS feeds if you do not include any RSS feed information in this topic.Related informationIBM Software Support RSS feedsSubscribe to My Notifications support content updatesMy Notifications for IBM technical supportMy Notifications for IBM technical support overviewSupport InformationTo isolate and resolve problems with your IBM products, you can use the troubleshooting and support information. This information contains instructions for using the problem-determination resources that are provided with your IBM products.

Subscribing to Support updates

To stay informed of important information about the IBM products that you use, you can subscribe to updates.

About this task

By subscribing to receive updates about this product, you can receive important technical information and updates for specific IBM Support tools and resources. You can subscribe to updates by using one of two approaches:

RSS feeds and social media subscriptions

For general information about RSS, including steps for getting started and a list of RSS-enabled IBM web pages, visit the IBM Software Support RSS feeds site.

My Notifications

With My Notifications, you can subscribe to Support updates for any IBM product. (My Notifications replaces My Support, which is a similar tool that you might have used in the past.) With My Notifications, you can specify that you want to receive daily or weekly email announcements. You can specify what type of information you want to receive (such as publications, hints, and tips, product flashes (also known as alerts), downloads, and drivers). My Notifications enable you to customize and categorize the products about which you want to be informed and the delivery methods that best suit your needs.

Procedure

To subscribe to Support updates:

Subscribe to the RSS feeds by accessing the IBM Software Support RSS feeds site and subscribe to the product feed.

Subscribe to My Notifications by going to the IBM® Support Portal and click My Notifications in the Notifications portlet.

Sign in using your IBM ID and password, and click Submit.

Identify what and how you want to receive updates.

Click the Subscribe tab.

Select the appropriate software brand or type of hardware.

Select one or more products by name and click Continue.

Select your preferences for how to receive updates, whether by email, online in a designated folder, or as an RSS or Atom feed.

Select the types of documentation updates that you want to receive, for example, new information about product downloads and discussion group comments.

Click Submit.

Results

Until you modify your RSS feeds and My Notifications preferences, you receive notifications of updates that you requested. You can modify your preferences when needed (for example, if you stop using one product and begin using another product).

Parent topic: Support Information

Related information

IBM Software Support RSS feeds

Subscribe to My Notifications support content updates

My Notifications for IBM technical support

My Notifications for IBM technical support overview

ReferenceReference information is organized to provide quick access to specific information, such as the description of a certain command-line parameter.ReferenceWeb command referenceThese reference topics describe IBM Security Access Manager commands.Web Reverse Proxy Stanza ReferenceThese reference topics describe configuration parameters that you can specify for the Web Reverse Proxy.

Reference

Reference information is organized to provide quick access to specific information, such as the description of a certain command-line parameter.

Web command reference
These reference topics describe IBM Security Access Manager commands.

Web Reverse Proxy Stanza Reference
These reference topics describe configuration parameters that you can specify for the Web Reverse Proxy.

Web command referenceThese reference topics describe IBM Security Access Manager commands.ReferenceReference information is organized to provide quick access to specific information, such as the description of a certain command-line parameter.pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package. Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed. Using response filesA response file is a text file that contains product and system information, sometimes used in configuration.

Web command reference

These reference topics describe IBM Security Access Manager commands.

pdadmin commands
The pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

Password limitations and characters allowed in object names
When you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Using response files
A response file is a text file that contains product and system information, sometimes used in configuration.

Parent topic: Reference

pdadmin commandspdadmin commandspdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package. pdadmincommandsUse this interface to manage access control lists, groups, servers, users, objects, and other resources in your secure domain. You can also automate certain management functions by writing scripts that use pdadmin commands.Use the Web Portal Manager interface to complete remotely similar administrative tasks. When you use Web Portal Manager, no special network configuration is needed to connect and complete these management tasks.Web command referenceThese reference topics describe IBM Security Access Manager commands.How to read syntax statementsSyntax diagrams pictorially display the order and parameters for the command utility. Syntax for pdadmin commandsThe following syntax is used with the pdadmin command:Command modesYou can use the pdadmin utility in three different command modes: single, interactive, or multiple. Non-English localesFor Security Access Manager software, you can specify localized behavior by setting the required locale. Error handlingAfter a command finishes processing, a return code is displayed or logged to provide the success or failure of the command.Local or other domainUse the pdadmin command to authenticate your user ID and password. You must authenticate before you log in to the local domain or to a domain other than the local domain.Command option processingSome pdadmin command options use specific symbols or characters.Commands by categoryThe pdadmin commands are listed here by major category.acl attachAttaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one. acl createCreates an ACL policy in the ACL database. This command does not create ACL entries. acl deleteDeletes an ACL policy from the ACL database. acl detachDetaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database. acl findReturns a list of protected objects, which have the specified ACL attached.acl listLists the names of all defined access control lists. Alternatively, lists the extended attribute keys that are associated with a specific ACL. acl modifyModifies access control list (ACL) policies. acl showLists the complete set of entries for a specific access control list (ACL) policy. Alternatively, lists the values of a specific extended attribute that is associated with an ACL policy.action createCreates and adds an action (permission) to an action group. action deleteDeletes an action (permission) from an action group. action group createCreates an action group.action group deleteDeletes an action group. action group listLists all action groups. action listLists all actions (permissions) in an action group. admin show confDisplays the current policy server configuration information, such as the type of registry or whether global sign-on is enabled. authzrule attachAttaches an authorization rule to the specified protected object. authzrule createCreates an authorization rule. authzrule deleteDeletes an authorization rule. authzrule detachDetaches an authorization rule from the specified protected object. authzrule findFinds and lists all protected objects that have the specified authorization rule attached. authzrule listLists all the authorization rules. authzrule modifyauthzrule showShows all the attributes of an authorization rule, including description, rule text, and fail reason code. context showDisplays the user ID and domain ID used to establish the current authentication context. Also, specifies whether the domain is the management domain or a domain other than the management domain.domain createCreates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command. domain deleteDeletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator. domain listLists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command. domain modifyChanges the description of a domain. You must log in to the management domain as an administrator to perform this command. domain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. errtextDisplays the error message of a specific error number. exit or quitExits from the pdadmin utility interactive command-line mode.group createCreates a Security Access Manager group. group deleteDeletes the specified Security Access Manager group. Optionally deletes the information of the group, from the user registry. ACL entries that are associated with the group are also deleted. group importCreates a Security Access Manager group by importing group data that exists in the user registry. group listGenerates a list of all groups, by group names, whose names match the specified pattern. group modifyChanges an existing group by adding or changing a group description, adding members to the group, or removing members from the group. group showShows the properties of the specified group. helpObtains system help for pdadmin commands and options. loginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. logoutDiscards any authentication credentials that are in effect. object accessConfirms whether the specified access is permitted on the specified object. The access is determined based on the permissions of this user. object copyRecursively copy the policy from one protected object space to another. The policy that is copied includes ACLs, POPs, authorization rules, and extended attributes.object createCreates a protected object. object deleteDeletes a protected object. object existsIndicates whether a protected object exists. object listLists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object. object listandshowLists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy. object modifyModifies an existing object. object showShows values for the protected object. objectspace createCreates a protected object space under which protected objects can be placed. objectspace deleteDeletes the specified protected object space. objectspace listLists all the existing protected object spaces in the policy server. policy getDisplays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.policy setSets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.pop attachAttaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached. pop createCreates a protected object policy (POP). pop deleteDeletes the specified protected object policy (POP). pop detachDetaches a protected object policy (POP) from the specified protected object. pop findFinds and lists all protected objects that have a protected object policy (POP) attached. pop listLists all protected object policies that are created. Alternatively, lists all extended attributes that are associated with a protected object policy. pop modifyModifies protected object policies. pop showShows details about the protected object policy (POP). Alternatively, displays the values for the specified extended attribute from the specified protected object policy. rsrc createCreates and names a web server single sign-on resource. rsrc deleteDeletes the specified single sign-on resource. rsrc listReturns a list of all the single sign-on resource names. rsrc showDisplays the resource information for the named resource. rsrccred createCreates a single sign-on credential. rsrccred deleteDeletes a single sign-on credential. rsrccred list userReturns the list of single sign-on credentials for the specified user. The user must exist, or an error is displayed. rsrccred modifyChanges a single sign-on credential. rsrccred showDisplays the attributes of a single sign-on credential. The credential identifier is composed of a resource name, a resource type, and a user name. rsrcgroup createCreates and names a resource group. rsrcgroup deleteDeletes a single sign-on resource group. rsrcgroup listDisplays the names of all resource groups that are defined in the user registry. rsrcgroup modifyAdds or removes a single sign-on resource to or from a single sign-on resource group. rsrcgroup showDisplays the resource group information for the specified resource group. server listLists all registered Security Access Manager servers. server listtasksRetrieves the list of tasks (commands) available for the specified installed Security Access Manager server or server instance. server replicateNotifies the installed Security Access Manager authorization server or server instance to receive database updates. server showDisplays the properties for the specified installed Security Access Manager server or server instance. The server must exist, or an error is displayed. server task addAdds an application server to an existing WebSEAL junction. server task cache flush allFlushes the HTML document cache. server task createCreates a WebSEAL junction point. server task deleteDeletes a WebSEAL junction point. server task dynurl updateReloads the dynamic URL configuration file. server task helpLists detailed help information about a specific server task command. server task jmtClears or loads the junction mapping table data. server task listLists all junction points on a WebSEAL server or server instance. server task offlinePlaces the server that is at this junction in an offline operational state.server task onlinePlaces the server that is at this junction in an online operational state.server task refresh all_sessionsRefreshes the credential for all sessions for a specified user. server task reloadReloads the junction mapping table from the database. server task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. server task showDisplays detailed information about the specified WebSEAL junction. server task sms key changeForces the creation of a new session management key. server task sms key showLists detailed information about the current session management key.server task sms realm listLists all session management realms in the domain.server task sms realm showLists all replica sets in the specified session management realm.server task sms session refresh all_sessionsRefreshes the credential for sessions for a specific user.server task sms session refresh sessionRefreshes the credential for a session.server task sms replica set listLists all session management replica sets in the domain.server task sms replica set showLists all session management replicas in the specified replica set with the time and date that each joined the realm.server task sms session listLists all session management sessions.server task sms session terminate all_sessionsTerminates all user sessions for a specific user.server task sms session terminate sessionTerminates a user session by using a session ID.server task sms trace getDisplays the trace level for the session management server.server task sms trace setSets the trace level for the distributed session cache.server task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. server task terminate all_sessionsTerminates all user sessions for a specific user. server task terminate sessionTerminates a user session by using a session ID. server task throttlePlaces the server that is at this junction in a throttled operational state.server task traceEnables the gathering of trace information for components of installed Security Access Manager servers or server instances. server task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. server task virtualhost createCreates a virtual host junction. server task virtualhost deleteDeletes a virtual host junction. server task virtualhost listLists all configured virtual host junctions by label name. server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. server task virtualhost removeRemoves the specified server from a virtual host junction. server task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. server task server restartRestarts a WebSEAL server by using the Security Access Manager server task framework. server task server syncSynchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework. server task file catReturns the contents of a specified file to the administration console. This command requires authentication of administrator ID and password.user createCreates a Security Access Manager user. user deleteDeletes the specified Security Access Manager user. Optionally deletes the information of the user in the user registry. user importCreates a Security Access Manager user by importing user data that exists in the user registry. user listLists users by Security Access Manager user name or by registry identifier. user modifyChanges various user account attributes. user showDisplays the properties of the specified user.

pdadmin commands

The pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

Use this interface to manage access control lists, groups, servers, users, objects, and other resources in your secure domain. You can also automate certain management functions by writing scripts that use pdadmin commands.

Use the Web Portal Manager interface to complete remotely similar administrative tasks. When you use Web Portal Manager, no special network configuration is needed to connect and complete these management tasks.

How to read syntax statements
Syntax diagrams pictorially display the order and parameters for the command utility.

Syntax for pdadmin commands
The following syntax is used with the pdadmin command:

Command modes
You can use the pdadmin utility in three different command modes: single, interactive, or multiple.

Non-English locales
For Security Access Manager software, you can specify localized behavior by setting the required locale.

Error handling
After a command finishes processing, a return code is displayed or logged to provide the success or failure of the command.

Local or other domain
Use the pdadmin command to authenticate your user ID and password. You must authenticate before you log in to the local domain or to a domain other than the local domain.

Command option processing
Some pdadmin command options use specific symbols or characters.

Commands by category
The pdadmin commands are listed here by major category.

acl attach
Attaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one.

acl create
Creates an ACL policy in the ACL database. This command does not create ACL entries.

acl delete
Deletes an ACL policy from the ACL database.

acl detach
Detaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database.

acl find
Returns a list of protected objects, which have the specified ACL attached.

acl list
Lists the names of all defined access control lists. Alternatively, lists the extended attribute keys that are associated with a specific ACL.

acl modify
Modifies access control list (ACL) policies.

acl show
Lists the complete set of entries for a specific access control list (ACL) policy. Alternatively, lists the values of a specific extended attribute that is associated with an ACL policy.

action create
Creates and adds an action (permission) to an action group.

action delete
Deletes an action (permission) from an action group.

action group create
Creates an action group.

action group delete
Deletes an action group.

action group list
Lists all action groups.

action list
Lists all actions (permissions) in an action group.

admin show conf
Displays the current policy server configuration information, such as the type of registry or whether global sign-on is enabled.

authzrule attach
Attaches an authorization rule to the specified protected object.

authzrule create
Creates an authorization rule.

authzrule delete
Deletes an authorization rule.

authzrule detach
Detaches an authorization rule from the specified protected object.

authzrule find
Finds and lists all protected objects that have the specified authorization rule attached.

authzrule list
Lists all the authorization rules.

authzrule modify

authzrule show
Shows all the attributes of an authorization rule, including description, rule text, and fail reason code.

context show
Displays the user ID and domain ID used to establish the current authentication context. Also, specifies whether the domain is the management domain or a domain other than the management domain.

domain create
Creates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command.

domain delete
Deletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator.

domain list
Lists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command.

domain modify
Changes the description of a domain. You must log in to the management domain as an administrator to perform this command.

domain show
Displays the properties of a domain. You must log in to the management domain as an administrator to perform this command.

errtext
Displays the error message of a specific error number.

exit or quit
Exits from the pdadmin utility interactive command-line mode.

group create
Creates a Security Access Manager group.

group delete
Deletes the specified Security Access Manager group. Optionally deletes the information of the group, from the user registry. ACL entries that are associated with the group are also deleted.

group import
Creates a Security Access Manager group by importing group data that exists in the user registry.

group list
Generates a list of all groups, by group names, whose names match the specified pattern.

group modify
Changes an existing group by adding or changing a group description, adding members to the group, or removing members from the group.

group show
Shows the properties of the specified group.

help
Obtains system help for pdadmin commands and options.

login
Establishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done.

logout
Discards any authentication credentials that are in effect.

object access
Confirms whether the specified access is permitted on the specified object. The access is determined based on the permissions of this user.

object copy
Recursively copy the policy from one protected object space to another. The policy that is copied includes ACLs, POPs, authorization rules, and extended attributes.

object create
Creates a protected object.

object delete
Deletes a protected object.

object exists
Indicates whether a protected object exists.

object list
Lists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object.

object listandshow
Lists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy.

object modify
Modifies an existing object.

object show
Shows values for the protected object.

objectspace create
Creates a protected object space under which protected objects can be placed.

objectspace delete
Deletes the specified protected object space.

objectspace list
Lists all the existing protected object spaces in the policy server.

policy get
Displays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.

policy set
Sets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.

pop attach
Attaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached.

pop create
Creates a protected object policy (POP).

pop delete
Deletes the specified protected object policy (POP).

pop detach
Detaches a protected object policy (POP) from the specified protected object.

pop find
Finds and lists all protected objects that have a protected object policy (POP) attached.

pop list
Lists all protected object policies that are created. Alternatively, lists all extended attributes that are associated with a protected object policy.

pop modify
Modifies protected object policies.

pop show
Shows details about the protected object policy (POP). Alternatively, displays the values for the specified extended attribute from the specified protected object policy.

rsrc create
Creates and names a web server single sign-on resource.

rsrc delete
Deletes the specified single sign-on resource.

rsrc list
Returns a list of all the single sign-on resource names.

rsrc show
Displays the resource information for the named resource.

rsrccred create
Creates a single sign-on credential.

rsrccred delete
Deletes a single sign-on credential.

rsrccred list user
Returns the list of single sign-on credentials for the specified user. The user must exist, or an error is displayed.

rsrccred modify
Changes a single sign-on credential.

rsrccred show
Displays the attributes of a single sign-on credential. The credential identifier is composed of a resource name, a resource type, and a user name.

rsrcgroup create
Creates and names a resource group.

rsrcgroup delete
Deletes a single sign-on resource group.

rsrcgroup list
Displays the names of all resource groups that are defined in the user registry.

rsrcgroup modify
Adds or removes a single sign-on resource to or from a single sign-on resource group.

rsrcgroup show
Displays the resource group information for the specified resource group.

server list
Lists all registered Security Access Manager servers.

server listtasks
Retrieves the list of tasks (commands) available for the specified installed Security Access Manager server or server instance.

server replicate
Notifies the installed Security Access Manager authorization server or server instance to receive database updates.

server show
Displays the properties for the specified installed Security Access Manager server or server instance. The server must exist, or an error is displayed.

server task add
Adds an application server to an existing WebSEAL junction.

server task cache flush all
Flushes the HTML document cache.

server task create
Creates a WebSEAL junction point.

server task delete
Deletes a WebSEAL junction point.

server task dynurl update
Reloads the dynamic URL configuration file.

server task help
Lists detailed help information about a specific server task command.

server task jmt
Clears or loads the junction mapping table data.

server task list
Lists all junction points on a WebSEAL server or server instance.

server task offline
Places the server that is at this junction in an offline operational state.

server task online
Places the server that is at this junction in an online operational state.

server task refresh all_sessions
Refreshes the credential for all sessions for a specified user.

server task reload
Reloads the junction mapping table from the database.

server task remove
Removes the specified installed WebSEAL server or server instance from a WebSEAL junction point.

server task show
Displays detailed information about the specified WebSEAL junction.

server task sms key change
Forces the creation of a new session management key.

server task sms key show
Lists detailed information about the current session management key.

server task sms realm list
Lists all session management realms in the domain.

server task sms realm show
Lists all replica sets in the specified session management realm.

server task sms session refresh all_sessions
Refreshes the credential for sessions for a specific user.

server task sms session refresh session
Refreshes the credential for a session.

server task sms replica set list
Lists all session management replica sets in the domain.

server task sms replica set show
Lists all session management replicas in the specified replica set with the time and date that each joined the realm.

server task sms session list
Lists all session management sessions.

server task sms session terminate all_sessions
Terminates all user sessions for a specific user.

server task sms session terminate session
Terminates a user session by using a session ID.

server task sms trace get
Displays the trace level for the session management server.

server task sms trace set
Sets the trace level for the distributed session cache.

server task stats
Manages the gathering and reporting of statistics for Security Access Manager servers and server instances.

server task terminate all_sessions
Terminates all user sessions for a specific user.

server task terminate session
Terminates a user session by using a session ID.

server task throttle
Places the server that is at this junction in a throttled operational state.

server task trace
Enables the gathering of trace information for components of installed Security Access Manager servers or server instances.

server task virtualhost add
Adds an additional installed WebSEAL server or server instance to an existing virtual host junction.

server task virtualhost create
Creates a virtual host junction.

server task virtualhost delete
Deletes a virtual host junction.

server task virtualhost list
Lists all configured virtual host junctions by label name.

server task virtualhost offline
Places the server that is at this virtual host junction in an offline operational state.

server task virtualhost online
Places the server that is at this virtual host junction in an online operational state.

server task virtualhost remove
Removes the specified server from a virtual host junction.

server task virtualhost show
Displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed.

server task virtualhost throttle
Places the server that is at this virtual host junction in a throttled operational state.

server task server restart
Restarts a WebSEAL server by using the Security Access Manager server task framework.

server task server sync
Synchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework.

server task file cat
Returns the contents of a specified file to the administration console. This command requires authentication of administrator ID and password.

user create
Creates a Security Access Manager user.

user delete
Deletes the specified Security Access Manager user. Optionally deletes the information of the user in the user registry.

user import
Creates a Security Access Manager user by importing user data that exists in the user registry.

user list
Lists users by Security Access Manager user name or by registry identifier.

user modify
Changes various user account attributes.

user show
Displays the properties of the specified user.

Parent topic: Web command reference

How to read syntax statementsHow to read syntax statementsHow to read syntax statementsSyntax diagrams pictorially display the order and parameters for the command utility. syntaxread syntax statementsstatementThe reference documentation uses the following special characters to define syntax: [ ]Identifies optional options. Options that are not enclosed in brackets are required....Indicates that you can specify multiple values for the previous option.|Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.{ }Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).\Indicates that the command line wraps to the next line. It is a continuation character.The options for each command are listed alphabetically in the Options section. The options for each utility are listed alphabetically in the Parameters section. When the order of the options or parameters must be used in a specific order, this order is shown in the syntax statements.pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

How to read syntax statements

Syntax diagrams pictorially display the order and parameters for the command utility.

The reference documentation uses the following special characters to define syntax:

[ ]

Identifies optional options. Options that are not enclosed in brackets are required.

...

Indicates that you can specify multiple values for the previous option.

|

Indicates mutually exclusive information. You can use the option to the left of the separator or the option to the right of the separator. You cannot use both options in a single use of the command.

{ }

Delimits a set of mutually exclusive options when one of the options is required. If the options are optional, they are enclosed in brackets ([ ]).

\

Indicates that the command line wraps to the next line. It is a continuation character.

The options for each command are listed alphabetically in the Options section. The options for each utility are listed alphabetically in the Parameters section. When the order of the options or parameters must be used in a specific order, this order is shown in the syntax statements.

Parent topic: pdadmin commands

Syntax for pdadmin commandsSyntax for pdadmin commandsSyntax for pdadmin commandsThe following syntax is used with the pdadmin command:pdadminutilitypdadminsyntaxpdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–d domain]] [–linelen max-linelen] [–histsize history size] [–v] [command]pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–d domain]] [–linelen max-linelen] [–v] [file]pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–m]] [–linelen max-linelen] [–v] [command]pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–m]] [–linelen max-linelen] [–v] [file]pdadmin [–l] [–linelen max-linelen] [–v] [command]pdadmin [–l] [–linelen max-linelen] [–v] [file]The following list explains the options for the pdadmin utility: commandSpecifies the single pdadmin command to run. The command is run one time. The pdadmin utility does not enter interactive mode. The command option is mutually exclusive with the file option.fileSpecifies the fully qualified name of the file that contains a list of commands to run. These commands are run one time. The pdadmin utility does not enter interactive mode. The file option is mutually exclusive with the command option. For Windows operating systems, file names cannot contain the backward slash (\), colon (:), question mark (?), or double quotation mark characters.–a admin_idLogs you in as the user admin_id. This administrator must exist in the domain. If you do not specify this option on the command line, you are considered unauthenticated, and your access to other commands is limited. If you specify this option without specify the –p option, you are prompted for the password. The –a option is mutually exclusive with the –l option. If you do not specify either option, you are logged in as an unauthenticated user. Unauthenticated users can use the context, errtext, exit, help, login, logout and quit commands only.–d domainSpecifies the Security Access Manager secure domain to log in. Log in to this domain requires authentication. The admin_id user that is specified must exist in this domain. The –d option is mutually exclusive with the –m option. If neither options are specified, the target domain is the local domain that is configured for the system.–I configuration-instance-nameSpecifies the pd.conf file instance that the pdadmin command should use. The configuration-instance-name value is the hostname that is provided to the pdadmin_host command that generated the configuration file. This option allows pdadmin to communicate with multiple policy servers.–lSpecifies a local login operation. When modifications are made to local configuration files by using the pdadmin config commands, a local login is required before you can run commands.The –l option is mutually exclusive with the –a option. If you do not specify either option, you are logged in as an unauthenticated user. Unauthenticated users can use the context, errtext, exit, help, login, logout and quit commands only.–linelen max-linelenCurrently, the –linelen option is ignored.–mSpecifies that the login operation must be directed to the management domain. Log in to this domain requires authentication. The admin_id user that is specified must exist in this domain. The –m option is mutually exclusive with the –d option. If neither options are specified, the target domain is the local domain that is configured for the system.–p passwordSpecifies the password for the user admin_id. Using this option might show your password to others because the password is visible on the screen and also in the process table. If you do not specify this option on the command line, you are prompted for a password. This option cannot be used unless the –a option is used.–vPrints the version number of the pdadmin utility. If this option is specified, all other valid options are ignored. The following example is the output that you might see when you use this option:Security Access Manager Administrative Tool v7.0.0.0 (Build 111215) Copyright (C) IBM Corporation 2012. All Rights Reserved.–histsizeSpecifies the command history size. The default command history size is 64. The minimum size of the command history is 1 and the maximum size is 1024. The command history option is available only in the interactive mode and on operating systems other than Windows.If you specify the –a and –p options, you are logged in as that user. Using this method might show your password to others. For example, one user is using pdadmin with this command. Another user lists the processes that are running. Then, the full command that includes the password, might be visible to the second user.Users can run the pdadmin context show command to view their authentication information. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

Syntax for pdadmin commands

The following syntax is used with the pdadmin command:

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–d domain]] [–linelen max-linelen] [–histsize history size] [–v] [command]

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–d domain]] [–linelen max-linelen] [–v] [file]

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–m]] [–linelen max-linelen] [–v] [command]

pdadmin [–I configuration-instance-name] [[–a admin_id [–p password] [–m]] [–linelen max-linelen] [–v] [file]

pdadmin [–l] [–linelen max-linelen] [–v] [command]

pdadmin [–l] [–linelen max-linelen] [–v] [file]

The following list explains the options for the pdadmin utility:

command

Specifies the single pdadmin command to run. The command is run one time. The pdadmin utility does not enter interactive mode. The command option is mutually exclusive with the file option.

file

Specifies the fully qualified name of the file that contains a list of commands to run. These commands are run one time. The pdadmin utility does not enter interactive mode. The file option is mutually exclusive with the command option.

Note: For Windows operating systems, file names cannot contain the backward slash (\), colon (:), question mark (?), or double quotation mark characters.

–a admin_id

Logs you in as the user admin_id. This administrator must exist in the domain. If you do not specify this option on the command line, you are considered unauthenticated, and your access to other commands is limited. If you specify this option without specify the –p option, you are prompted for the password.

The –a option is mutually exclusive with the –l option. If you do not specify either option, you are logged in as an unauthenticated user. Unauthenticated users can use the context, errtext, exit, help, login, logout and quit commands only.

–d domain

Specifies the Security Access Manager secure domain to log in. Log in to this domain requires authentication. The admin_id user that is specified must exist in this domain. The –d option is mutually exclusive with the –m option. If neither options are specified, the target domain is the local domain that is configured for the system.

–I configuration-instance-name

Specifies the pd.conf file instance that the pdadmin command should use. The configuration-instance-name value is the hostname that is provided to the pdadmin_host command that generated the configuration file. This option allows pdadmin to communicate with multiple policy servers.

–l

Specifies a local login operation. When modifications are made to local configuration files by using the pdadmin config commands, a local login is required before you can run commands.

The –l option is mutually exclusive with the –a option. If you do not specify either option, you are logged in as an unauthenticated user. Unauthenticated users can use the context, errtext, exit, help, login, logout and quit commands only.

–linelen max-linelen

Currently, the –linelen option is ignored.

–m

Specifies that the login operation must be directed to the management domain. Log in to this domain requires authentication. The admin_id user that is specified must exist in this domain. The –m option is mutually exclusive with the –d option. If neither options are specified, the target domain is the local domain that is configured for the system.

–p password

Specifies the password for the user admin_id. Using this option might show your password to others because the password is visible on the screen and also in the process table. If you do not specify this option on the command line, you are prompted for a password. This option cannot be used unless the –a option is used.

–v

Prints the version number of the pdadmin utility. If this option is specified, all other valid options are ignored.

The following example is the output that you might see when you use this option:

Security Access Manager Administrative Tool v7.0.0.0 (Build 111215)
Copyright (C) IBM Corporation 2012. All Rights Reserved.

–histsize

Specifies the command history size. The default command history size is 64. The minimum size of the command history is 1 and the maximum size is 1024. The command history option is available only in the interactive mode and on operating systems other than Windows.

Note:

If you specify the –a and –p options, you are logged in as that user. Using this method might show your password to others. For example, one user is using pdadmin with this command. Another user lists the processes that are running. Then, the full command that includes the password, might be visible to the second user.

Users can run the pdadmin context show command to view their authentication information.

Parent topic: pdadmin commands

Command modesCommand modesCommand modesYou can use the pdadmin utility in three different command modes: single, interactive, or multiple. pdadminmodessingle command modeinteractive command modemultiple command modeThese modes are described in the following sections.For details about the command options that are displayed in the following sections, see Syntax for pdadmin commandsThe following syntax is used with the pdadmin command:.pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package. Single command modeIn single command mode, the CLI runs only the specified command, and ends after it receives the response message for that command.Interactive command modeInteractive command mode uses an interactive command-line session where, after the command starts, you are prompted to enter required information.Multiple command modeWith multiple command mode, you can create a file that contains multiple pdadmin commands, one per line, that together complete a task or series of tasks.

Command modes

You can use the pdadmin utility in three different command modes: single, interactive, or multiple.

These modes are described in the following sections.

For details about the command options that are displayed in the following sections, see Syntax for pdadmin commands.

Single command mode
In single command mode, the CLI runs only the specified command, and ends after it receives the response message for that command.

Interactive command mode
Interactive command mode uses an interactive command-line session where, after the command starts, you are prompted to enter required information.

Multiple command mode
With multiple command mode, you can create a file that contains multiple pdadmin commands, one per line, that together complete a task or series of tasks.

Parent topic: pdadmin commands

Single command modeSingle command modeSingle command modeIn single command mode, the CLI runs only the specified command, and ends after it receives the response message for that command.single command modecommandsmodessingleTo run a single pdadmin command, enter one of the following commands:pdadmin [–a admin_id [–p password] [–d domain]] [–v] [command]pdadmin [–a admin_id [–p password] [–m]] [–v] [command]pdadmin [–l] [–v] [command]For details about the command options, see Syntax for pdadmin commandsThe following syntax is used with the pdadmin command:.Command modesYou can use the pdadmin utility in three different command modes: single, interactive, or multiple.

Single command mode

In single command mode, the CLI runs only the specified command, and ends after it receives the response message for that command.

To run a single pdadmin command, enter one of the following commands:

pdadmin [–a admin_id [–p password] [–d domain]] [–v] [command]

pdadmin [–a admin_id [–p password] [–m]] [–v] [command]

pdadmin [–l] [–v] [command]

For details about the command options, see Syntax for pdadmin commands.

Parent topic: Command modes

Interactive command modeInteractive command modeInteractive command modeInteractive command mode uses an interactive command-line session where, after the command starts, you are prompted to enter required information.interactive command modecommandsmodesinteractiveTo start pdadmin in interactive mode, type the pdadmin command.This command starts pdadmin without any authentication that is required, where your access to other pdadmin commands is limited for unauthenticated users, such as context, errtext, exit, help, login, logout, and quit. c:\> pdadmin pdadmin> limited_pdadmin_commandThis command starts pdadmin and login authentication is required before you can use other pdadmin commands. You can be prompted for both the administrator ID and the password: c:\> pdadmin pdadmin> login Enter User ID:sec_master Enter Password: secmstrpw pdadmin sec_master> pdadmin_commandOr, you can be prompted for just the administrator password: c:\> pdadmin pdadmin> login -a sec_master Enter Password: secmstrpw pdadmin sec_master> pdadmin_commandOr, you can bypass being prompted, which is less secure because your password is visible: c:\> pdadmin pdadmin> login -a sec_master -p secmstrpw pdadmin sec_master> pdadmin_commandTo start pdadmin in interactive mode: With a login to a management or other domain.Where the ID and password are authenticated before access is permitted.Where user privileges are verified before users can issue commands.For example, to log in to the management domain (Default) and authenticate, type: pdadmin login -a admin_id -p password -m pdadmin sec_master@Default> pdadmin_command For example, to log in to another domain domain01 and authenticate, type: rpdadmin login -a sec_master -p secmstrpw -d domain01 pdadmin sec_master@domain01> pdadmin_commandAt the pdadmin prompt, type the appropriate commands and their associated options. The pdadmin prompt changes, depending on the type of login. See Login and logout commandsLogin and logout commands are used to log in to, and log out of, a Security Access Manager secure domain. for more information about the login command and prompt changes.In this release, the length of a command line that is used in pdadmin interactive mode is limited to 1023 characters.Command modesYou can use the pdadmin utility in three different command modes: single, interactive, or multiple.

Interactive command mode

Interactive command mode uses an interactive command-line session where, after the command starts, you are prompted to enter required information.

To start pdadmin in interactive mode, type the pdadmin command.

This command starts pdadmin without any authentication that is required, where your access to other pdadmin commands is limited for unauthenticated users, such as context, errtext, exit, help, login, logout, and quit.

c:\> pdadmin

pdadmin> limited_pdadmin_command

This command starts pdadmin and login authentication is required before you can use other pdadmin commands. You can be prompted for both the administrator ID and the password:

c:\> pdadmin

pdadmin> login
Enter User ID:sec_master
Enter Password: secmstrpw

pdadmin sec_master> pdadmin_command

Or, you can be prompted for just the administrator password:

c:\> pdadmin

pdadmin> login -a sec_master
Enter Password: secmstrpw

pdadmin sec_master> pdadmin_command

Or, you can bypass being prompted, which is less secure because your password is visible:

c:\> pdadmin

pdadmin> login -a sec_master -p secmstrpw

pdadmin sec_master> pdadmin_command

To start pdadmin in interactive mode:

With a login to a management or other domain.

Where the ID and password are authenticated before access is permitted.

Where user privileges are verified before users can issue commands.

For example, to log in to the management domain (Default) and authenticate, type:

pdadmin login -a admin_id -p password -m

pdadmin sec_master@Default> pdadmin_command

For example, to log in to another domain domain01 and authenticate, type:

rpdadmin login -a sec_master -p secmstrpw -d domain01

pdadmin sec_master@domain01> pdadmin_command

At the pdadmin prompt, type the appropriate commands and their associated options. The pdadmin prompt changes, depending on the type of login. See Login and logout commands for more information about the login command and prompt changes.

Note: In this release, the length of a command line that is used in pdadmin interactive mode is limited to 1023 characters.

Parent topic: Command modes

Multiple command modeMultiple command modeMultiple command modeWith multiple command mode, you can create a file that contains multiple pdadmin commands, one per line, that together complete a task or series of tasks. multiple command modecommandsmodesmultipleLogin commands can be included in a command file to switch between local and remote login, as needed.To run commands in this file, provide one of the following commands:pdadmin [–a admin_id [–p password] [–d domain]] filepdadmin [–a admin_id [–p password] [–m]] fileLogin commands can be included in a command file to switch between pdadmin login –l local login: Where no authentication is required.Where authentication is required.For details about the command options that are displayed in the following sections, see Syntax for pdadmin commandsThe following syntax is used with the pdadmin command:.Command modesYou can use the pdadmin utility in three different command modes: single, interactive, or multiple.

Multiple command mode

With multiple command mode, you can create a file that contains multiple pdadmin commands, one per line, that together complete a task or series of tasks.

Login commands can be included in a command file to switch between local and remote login, as needed.

To run commands in this file, provide one of the following commands:

pdadmin [–a admin_id [–p password] [–d domain]] file

pdadmin [–a admin_id [–p password] [–m]] file

Login commands can be included in a command file to switch between pdadmin login –l local login:

Where no authentication is required.

Where authentication is required.

For details about the command options that are displayed in the following sections, see Syntax for pdadmin commands.

Parent topic: Command modes

Non-English localesNon-English localesNon-English localesFor Security Access Manager software, you can specify localized behavior by setting the required locale. locale, non-EnglishDifferent operating systems often encode text in different ways. For example, Windows operating systems use SJIS (code page 932) for Japanese text while AIX, Linux, and Solaris operating systems often use eucJP.However, be aware of the following issues when you are running the pdadmin utility in a non-English locale.On Windows operating systems, you can enter commands to pdadmin through a command file argument. The command file must be encoded in the system's local (ANSI) code page. For example: C:> pdadmin -a sec_master -p password cmds.textYou can determine the local code page of the system by viewing the value of the Nls/CodePage/ACP key in the Windows registry. Files that are created by standard Windows editing tools (such as Notepad or WordPad) are encoded in this way.On AIX, Linux, and Solaris operating systems, you must run the pdadmin command in the same locale that was used to create the command file.On Windows operating systems, you can enter commands to pdadmin by redirecting a command file. The command file must be encoded in a Microsoft Original Equipment Manufacturer (OEM) code page. The OEM code page corresponds to the active code page in the command window in which the pdadmin command is run. For example: C:> pdadmin -a sec_master -p password < cmds.textThe active code page can be determined by issuing the chcp command in the pdadmin command window.Alternatively, you can redirect a file that is encoded in the local code page of the system. However, you must change the active code page of the command window to correspond to the encoding of the file. Change the active code page of the window by using the chcp command. For example, entering the command chcp 1252 changes the active code page to the ANSI code page for Western Europe and the United States.On AIX, Linux, and Solaris operating systems, you must run the pdadmin command in the same locale that was used to create the redirected command file.Security Access Manager data that is created in one locale might not display correctly on a system that is configured to another locale. Whether data displays correctly depends on the configuration of the second system. For example, correct display depends on what the current locale is, and whether the necessary code pages and fonts are installed.pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

Non-English locales

For Security Access Manager software, you can specify localized behavior by setting the required locale.

Different operating systems often encode text in different ways. For example, Windows operating systems use SJIS (code page 932) for Japanese text while AIX, Linux, and Solaris operating systems often use eucJP.

However, be aware of the following issues when you are running the pdadmin utility in a non-English locale.

On Windows operating systems, you can enter commands to pdadmin through a command file argument. The command file must be encoded in the system's local (ANSI) code page. For example:

C:> pdadmin -a sec_master -p password cmds.text

You can determine the local code page of the system by viewing the value of the Nls/CodePage/ACP key in the Windows registry. Files that are created by standard Windows editing tools (such as Notepad or WordPad) are encoded in this way.

On AIX, Linux, and Solaris operating systems, you must run the pdadmin command in the same locale that was used to create the command file.

On Windows operating systems, you can enter commands to pdadmin by redirecting a command file. The command file must be encoded in a Microsoft Original Equipment Manufacturer (OEM) code page. The OEM code page corresponds to the active code page in the command window in which the pdadmin command is run. For example:

C:> pdadmin -a sec_master -p password < cmds.text

The active code page can be determined by issuing the chcp command in the pdadmin command window.

Alternatively, you can redirect a file that is encoded in the local code page of the system. However, you must change the active code page of the command window to correspond to the encoding of the file. Change the active code page of the window by using the chcp command. For example, entering the command chcp 1252 changes the active code page to the ANSI code page for Western Europe and the United States.

On AIX, Linux, and Solaris operating systems, you must run the pdadmin command in the same locale that was used to create the redirected command file.

Security Access Manager data that is created in one locale might not display correctly on a system that is configured to another locale. Whether data displays correctly depends on the configuration of the second system. For example, correct display depends on what the current locale is, and whether the necessary code pages and fonts are installed.

Parent topic: pdadmin commands

Error handlingError handlingError handlingAfter a command finishes processing, a return code is displayed or logged to provide the success or failure of the command.errorhandlingerrorreturn codeThe pdadmin command has the following return code values: 0The command that completed successfully.1The command failed. When a command fails, the pdadmin command displays a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).See Error messages in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.For information about how to use the message number that is associated with a message to display only the descriptive text, see errtextDisplays the error message of a specific error number. .pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package. Return codes for a single commandA single command is normally typed from a command prompt such as a DOS command prompt, Korn shell prompt, and C shell prompt. Single command mode does not automatically display the 0 or 1 return code values; the operating system must be queried for the return code value.Return codes for an interactive commandInteractive command mode does not automatically display the 0 or 1 return code values. Also, you cannot follow an interactive command with the AIX, Linux, and Solaris echo or the Windows errorlevel command.Return codes for multiple commandsYou can use a text file containing pdadmin commands to run those commands in a single pdadmin invocation.

Error handling

After a command finishes processing, a return code is displayed or logged to provide the success or failure of the command.

The pdadmin command has the following return code values:

0

The command that completed successfully.

1

The command failed. When a command fails, the pdadmin command displays a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM® Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

For information about how to use the message number that is associated with a message to display only the descriptive text, see errtext.

Return codes for a single command
A single command is normally typed from a command prompt such as a DOS command prompt, Korn shell prompt, and C shell prompt. Single command mode does not automatically display the 0 or 1 return code values; the operating system must be queried for the return code value.

Return codes for an interactive command
Interactive command mode does not automatically display the 0 or 1 return code values. Also, you cannot follow an interactive command with the AIX®, Linux, and Solaris echo or the Windows errorlevel command.

Return codes for multiple commands
You can use a text file containing pdadmin commands to run those commands in a single pdadmin invocation.

Parent topic: pdadmin commands

Return codes for a single commandReturn codes for a single commandReturn codes for a single commandA single command is normally typed from a command prompt such as a DOS command prompt, Korn shell prompt, and C shell prompt. Single command mode does not automatically display the 0 or 1 return code values; the operating system must be queried for the return code value.return code commandsingle commandFor command failures, the hexadecimal error code status with its associated error message is shown in addition to the error message ID (for example, HPDMG0754W). You can redirect the error that is normally displayed on the screen out to a text file. When a single command fails, you see an error message that is like the one displayed: C:> pdadmin -a admin_id -p password user show oogleCould not perform the administration request. Error: HPDMG0754WThe entry was not found. If ... (status 0x14c012f2)To display the 0 or 1 return code values, you must type the pdadmin command, followed by either the AIX, Linux, or Solaris echo or the Windows errorlevel command: For AIX, Linux, and Solaris operating systems: # pdadmin_command # echo $?For Windows operating systems: C:>pdadmin_command C:>echo %errorlevel%Error handlingAfter a command finishes processing, a return code is displayed or logged to provide the success or failure of the command.

Return codes for a single command

A single command is normally typed from a command prompt such as a DOS command prompt, Korn shell prompt, and C shell prompt. Single command mode does not automatically display the 0 or 1 return code values; the operating system must be queried for the return code value.

For command failures, the hexadecimal error code status with its associated error message is shown in addition to the error message ID (for example, HPDMG0754W). You can redirect the error that is normally displayed on the screen out to a text file. When a single command fails, you see an error message that is like the one displayed:

C:> pdadmin -a admin_id -p password user show oogle

Could not perform the administration request.
Error: HPDMG0754WThe entry was not found. If ...
(status 0x14c012f2)

To display the 0 or 1 return code values, you must type the pdadmin command, followed by either the AIX®, Linux, or Solaris echo or the Windows errorlevel command:

For AIX, Linux, and Solaris operating systems:

# pdadmin_command
# echo $?

For Windows operating systems:

C:>pdadmin_command
C:>echo %errorlevel%

Parent topic: Error handling

Return codes for an interactive commandReturn codes for an interactive commandReturn codes for an interactive commandInteractive command mode does not automatically display the 0 or 1 return code values. Also, you cannot follow an interactive command with the AIX, Linux, and Solaris echo or the Windows errorlevel command.return code commandinteractiveFor a command failure, you see a message that is like: pdadmin sec_master> user show oogleCould not perform the administration request. Error: HPDMG0754WThe entry was not found. If ... (status 0x14c012f2)Only the hexadecimal exit status code is displayed.Error handlingAfter a command finishes processing, a return code is displayed or logged to provide the success or failure of the command.

Return codes for an interactive command

Interactive command mode does not automatically display the 0 or 1 return code values. Also, you cannot follow an interactive command with the AIX®, Linux, and Solaris echo or the Windows errorlevel command.

For a command failure, you see a message that is like:

pdadmin sec_master> user show oogle

Could not perform the administration request.
Error: HPDMG0754WThe entry was not found. If ...
(status 0x14c012f2)

Only the hexadecimal exit status code is displayed.

Parent topic: Error handling

Return codes for multiple commandsReturn codes for multiple commandsReturn codes for multiple commandsYou can use a text file containing pdadmin commands to run those commands in a single pdadmin invocation. return code commandmultipleConsider that an error occurs for a command while the commands run in multiple command mode. Then, an error message for the failed command is provided.Processing of the remaining commands in the file continues after an error. At the end of multiple command processing, a final status is provided. The final status code at the termination of multiple command processing is only for the last command that was attempted. For example, if the last command was successful, the final status is 0. If the last command failed, the final status is 1. For example, a text file might contain these pdadmin commands: user show cwright user show oogleTo run the commands, run the following command: pdadmin –a admin_id -p password cmd_filename The command file would produce results like: cmd> user show cwright Login ID: cwright LDAP DN: cn=Claude Wright,ou=Dallas,o=Tivoli,c=us LDAP CN: Claude Wright LDAP SN: Wright Description: Is SecUser: yes Is GSO user: no Account valid: yes Password valid: yes Authorization mechanism: Default:LDAP cmd:> user show oogleCould not perform the administration request. Error: HPDMG0754WThe entry was not found. If ... (status 0x14c012f2)Error handlingAfter a command finishes processing, a return code is displayed or logged to provide the success or failure of the command.

Return codes for multiple commands

You can use a text file containing pdadmin commands to run those commands in a single pdadmin invocation.

Consider that an error occurs for a command while the commands run in multiple command mode. Then, an error message for the failed command is provided.

Processing of the remaining commands in the file continues after an error. At the end of multiple command processing, a final status is provided. The final status code at the termination of multiple command processing is only for the last command that was attempted. For example, if the last command was successful, the final status is 0. If the last command failed, the final status is 1.

For example, a text file might contain these pdadmin commands:

user show cwright
user show oogle

To run the commands, run the following command:

pdadmin –a admin_id -p password cmd_filename

The command file would produce results like:

cmd> user show cwright

Login ID: cwright
LDAP DN: cn=Claude Wright,ou=Dallas,o=Tivoli,c=us
LDAP CN: Claude Wright
LDAP SN: Wright
Description:
Is SecUser: yes
Is GSO user: no
Account valid: yes
Password valid: yes
Authorization mechanism: Default:LDAP

cmd:> user show oogle

Could not perform the administration request.
Error: HPDMG0754WThe entry was not found. If ...
(status 0x14c012f2)

Parent topic: Error handling

Local or other domainLocal or other domainLocal or other domainUse the pdadmin command to authenticate your user ID and password. You must authenticate before you log in to the local domain or to a domain other than the local domain.domainloginlocaldomainloginotherTo authenticate and log in to your local domain, in interactive mode, enter: pdadmin> login -a dlucas -p lucaspwd pdadmin dlucas>In the example, user_name logs you in as the authenticated user dlucas to your own local domain.To authenticate and log in to a domain with a name that is different from the local domain, enter: pdadmin> login -a dlucas -p lucaspwd -d domain_a pdadmin dlucas@domain_a>In the example, user_name logs you in as the authenticated user dlucas. domain_a is the domain_name to which you are logging on, in interactive mode.pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

Local or other domain

Use the pdadmin command to authenticate your user ID and password. You must authenticate before you log in to the local domain or to a domain other than the local domain.

To authenticate and log in to your local domain, in interactive mode, enter:

pdadmin> login -a dlucas -p lucaspwd

pdadmin dlucas>

In the example, user_name logs you in as the authenticated user dlucas to your own local domain.

To authenticate and log in to a domain with a name that is different from the local domain, enter:

pdadmin> login -a dlucas -p lucaspwd -d domain_a

pdadmin dlucas@domain_a>

In the example, user_name logs you in as the authenticated user dlucas. domain_a is the domain_name to which you are logging on, in interactive mode.

Parent topic: pdadmin commands

Command option processingCommand option processingCommand option processingSome pdadmin command options use specific symbols or characters.commands option processingpdadmincommands, option processingSome pdadmin command options begin with a hyphen (-). For example, the following command uses the –gsouser option: pdadmin sec_master> user import –gsouser mlucaser cn=mlucaser,o=Tivoli,c=USThe pdadmin command interprets any token beginning with a hyphen as a command option, even if the hyphen is placed within double quotation marks.Occasionally, you might want a token that begins with a – to be interpreted as an argument rather than as a command option. For example, you might want to name the user –mlucaser or "–mlucaser" by entering: pdadmin sec_master> user import –gsouser –mlucaser cn=mlucaser,o=tivoli,c=usIn this example, the first –gsouser option in the command is still processed. However, because the user name token begins with a hyphen, the user name would be interpreted as a command option. The command would fail because the —mlucaser command option does not exist.Specify the single hyphen character to turn off the interpretation of the optional arguments, by the pdadmin command. Following the single hyphen character, –mlucaser is now interpreted as the user name. For example: pdadmin sec_master> user import –gsouser – –mlucaser cn=mlucaser,o=Tivoli,c=usOptions on the command line are position-independent. You can change the order so that all tokens that begin with a hyphen, which are not command options, follow the single hyphen character.pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

Command option processing

Some pdadmin command options use specific symbols or characters.

Some pdadmin command options begin with a hyphen (-). For example, the following command uses the –gsouser option:

pdadmin sec_master> user import –gsouser mlucaser cn=mlucaser,o=Tivoli,c=US

The pdadmin command interprets any token beginning with a hyphen as a command option, even if the hyphen is placed within double quotation marks.

Occasionally, you might want a token that begins with a – to be interpreted as an argument rather than as a command option. For example, you might want to name the user –mlucaser or "–mlucaser" by entering:

pdadmin sec_master> user import –gsouser –mlucaser cn=mlucaser,o=tivoli,c=us

In this example, the first –gsouser option in the command is still processed. However, because the user name token begins with a hyphen, the user name would be interpreted as a command option. The command would fail because the —mlucaser command option does not exist.

Specify the single hyphen character to turn off the interpretation of the optional arguments, by the pdadmin command. Following the single hyphen character, –mlucaser is now interpreted as the user name.

For example:

pdadmin sec_master> user import –gsouser – –mlucaser cn=mlucaser,o=Tivoli,c=us

Options on the command line are position-independent. You can change the order so that all tokens that begin with a hyphen, which are not command options, follow the single hyphen character.

Parent topic: pdadmin commands

Commands by categoryCommands by categoryCommands by categoryThe pdadmin commands are listed here by major category.commandscategoryThis section lists the pdadmin commands by the following categories:pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package. Access control list commandsUse acl commands to manage access control list (ACL) policies and extended attributes.Action commandsThe action commands define more authorization actions (permissions) and action groups. Authorization rule commandsThe authzrule commands manage authorization rules.Context commandsContext commands display the context (authentication) information for the user who is running the pdadmin utility. Domain commandsDomain commands manage Security Access Manager secure domains. Group commandsGroup commands manage Security Access Manager groups.Login and logout commandsLogin and logout commands are used to log in to, and log out of, a Security Access Manager secure domain.Object commandsObject commands can protect objects by attaching ACLs or protected object policy (POP).Object space commandsObject space commands allow the creation of more object spaces that contain protected objects that are used by third-party applications.Policy commandsPolicy commands manage user password and account policies.Protected object policy commandsProtected object policy commands allow the creation of a protected object policy (POP) and extended attributes for the protected object policiesResource and resource group commandsResource and resource group commands manage resource-related information.Server commandsServer commands perform management tasks on Security Access Manager servers. Distributed session cache commandsDistributed session cache commands perform session management tasks. These commands are available only when a Web security server and distributed session cache are configured. User commandsUser commands manage Security Access Manager users.WebSEAL commandsWebSEAL commands perform management tasks on WebSEAL servers and instances. These commands are available only when WebSEAL is installed.

Commands by category

The pdadmin commands are listed here by major category.

This section lists the pdadmin commands by the following categories:

Access control list commands
Use acl commands to manage access control list (ACL) policies and extended attributes.

Action commands
The action commands define more authorization actions (permissions) and action groups.

Authorization rule commands
The authzrule commands manage authorization rules.

Context commands
Context commands display the context (authentication) information for the user who is running the pdadmin utility.

Domain commands
Domain commands manage Security Access Manager secure domains.

Group commands
Group commands manage Security Access Manager groups.

Login and logout commands
Login and logout commands are used to log in to, and log out of, a Security Access Manager secure domain.

Object commands
Object commands can protect objects by attaching ACLs or protected object policy (POP).

Object space commands
Object space commands allow the creation of more object spaces that contain protected objects that are used by third-party applications.

Policy commands
Policy commands manage user password and account policies.

Protected object policy commands
Protected object policy commands allow the creation of a protected object policy (POP) and extended attributes for the protected object policies

Resource and resource group commands
Resource and resource group commands manage resource-related information.

Server commands
Server commands perform management tasks on Security Access Manager servers.

Distributed session cache commands
Distributed session cache commands perform session management tasks. These commands are available only when a Web security server and distributed session cache are configured.

User commands
User commands manage Security Access Manager users.

WebSEAL commands
WebSEAL commands perform management tasks on WebSEAL servers and instances. These commands are available only when WebSEAL is installed.

Parent topic: pdadmin commands

Access control list commandsAccess control list commandsAccess control list commandsUse acl commands to manage access control list (ACL) policies and extended attributes.commandsaccess control listTable 1 lists acl commands.Access control list (ACL) commandsCommandDescriptionacl attachAttaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one. Attaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one.acl createCreates an ACL policy in the ACL database. This command does not create ACL entries. Creates an ACL policy in the ACL database. This command does not create ACL entries.acl deleteDeletes an ACL policy from the ACL database. Deletes an ACL policy from the ACL database.acl detachDetaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database. Detaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database.acl findReturns a list of protected objects, which have the specified ACL attached.Finds and lists all protected objects that have a specific ACL policy attached.acl listLists the names of all defined access control lists. Alternatively, lists the extended attribute keys that are associated with a specific ACL. Lists the names of all defined ACLs. Also lists the extended attribute keys that are associated with a specific ACL.acl modifyModifies access control list (ACL) policies. Modifies ACLs, their extended attributes, and associated values. acl showLists the complete set of entries for a specific access control list (ACL) policy. Alternatively, lists the values of a specific extended attribute that is associated with an ACL policy.Lists the complete set of entries for a specific ACL policy. Also lists the values of a specific extended attribute that is associated with an ACL policy.Commands by categoryThe pdadmin commands are listed here by major category.

Access control list commands

Use acl commands to manage access control list (ACL) policies and extended attributes.

Table 296 lists acl commands.

Table 296. Access control list (ACL) commands

Command | Description
acl attach | Attaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one.
acl create | Creates an ACL policy in the ACL database. This command does not create ACL entries.
acl delete | Deletes an ACL policy from the ACL database.
acl detach | Detaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database.
acl find | Finds and lists all protected objects that have a specific ACL policy attached.
acl list | Lists the names of all defined ACLs. Also lists the extended attribute keys that are associated with a specific ACL.
acl modify | Modifies ACLs, their extended attributes, and associated values.
acl show | Lists the complete set of entries for a specific ACL policy. Also lists the values of a specific extended attribute that is associated with an ACL policy.

Parent topic: Commands by category

Action commandsAction commandsAction commandsThe action commands define more authorization actions (permissions) and action groups. commandsactionTable 1 lists action commands. Action commandsCommandDescriptionaction createCreates and adds an action (permission) to an action group. Creates and adds an action to an action group.action deleteDeletes an action (permission) from an action group. Deletes an action from an action group.action group createCreates an action group.Creates an action group.action group deleteDeletes an action group. Deletes an action group.action group listLists all action groups. Lists all action groups.action listLists all actions (permissions) in an action group. Lists all defined actions in an action group.Commands by categoryThe pdadmin commands are listed here by major category.

Action commands

The action commands define more authorization actions (permissions) and action groups.

Table 297 lists action commands.

Table 297. Action commands

Command | Description
action create | Creates and adds an action to an action group.
action delete | Deletes an action from an action group.
action group create | Creates an action group.
action group delete | Deletes an action group.
action group list | Lists all action groups.
action list | Lists all defined actions in an action group.

Parent topic: Commands by category

Authorization rule commandsAuthorization rule commandsAuthorization rule commandsThe authzrule commands manage authorization rules.commandsauthorization ruleTable 1 lists authzrule commands. Authorization rule commandsCommandDescriptionauthzrule attachAttaches an authorization rule to the specified protected object. Attaches an authorization rule to the specified protected object.authzrule createCreates an authorization rule. Creates an authorization rule.authzrule deleteDeletes an authorization rule. Deletes an authorization rule.authzrule detachDetaches an authorization rule from the specified protected object. Detaches an authorization rule from the specified protected object.authzrule findFinds and lists all protected objects that have the specified authorization rule attached. Finds and lists all the protected objects that have the specified authorization rule attached.authzrule listLists all the authorization rules. Lists all the registered authorization rules.authzrule modifyModifies an authorization rule.authzrule showShows all the attributes of an authorization rule, including description, rule text, and fail reason code. Shows all the attributes of an authorization rule, including description, rule text, and fail reason code.Commands by categoryThe pdadmin commands are listed here by major category.

Authorization rule commands

The authzrule commands manage authorization rules.

Table 298 lists authzrule commands.

Table 298. Authorization rule commands

Command | Description
authzrule attach | Attaches an authorization rule to the specified protected object.
authzrule create | Creates an authorization rule.
authzrule delete | Deletes an authorization rule.
authzrule detach | Detaches an authorization rule from the specified protected object.
authzrule find | Finds and lists all the protected objects that have the specified authorization rule attached.
authzrule list | Lists all the registered authorization rules.
authzrule modify | Modifies an authorization rule.
authzrule show | Shows all the attributes of an authorization rule, including description, rule text, and fail reason code.

Parent topic: Commands by category

Context commandsContext commandsContext commandsContext commands display the context (authentication) information for the user who is running the pdadmin utility. commandscontextTable 1 lists context commands.Context commandsCommandDescriptioncontext showDisplays the user ID and domain ID used to establish the current authentication context. Also, specifies whether the domain is the management domain or a domain other than the management domain.Displays the user ID and domain ID used to establish the current context.Commands by categoryThe pdadmin commands are listed here by major category.

Context commands

Context commands display the context (authentication) information for the user who is running the pdadmin utility.

Table 299 lists context commands.

Table 299. Context commands

Command | Description
context show | Displays the user ID and domain ID used to establish the current context.

Parent topic: Commands by category

Domain commandsDomain commandsDomain commandsDomain commands manage Security Access Manager secure domains. commandsdomainTable 1 lists domain commands. Domain commandsCommandDescriptiondomain createCreates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command. Creates a Security Access Manager secure domain.domain deleteDeletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator. Deletes the specified Security Access Manager secure domain, and optionally deletes the information about the domain from the user registry.domain listLists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command. Lists all the domains except for the management domain.domain modifyChanges the description of a domain. You must log in to the management domain as an administrator to perform this command. Modifies the description of the specified domain.domain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. Displays the specified attributes of the domain, including name and description.Commands by categoryThe pdadmin commands are listed here by major category.

Domain commands

Domain commands manage Security Access Manager secure domains.

Table 300 lists domain commands.

Table 300. Domain commands

Command | Description
domain create | Creates a Security Access Manager secure domain.
domain delete | Deletes the specified Security Access Manager secure domain, and optionally deletes the information about the domain from the user registry.
domain list | Lists all the domains except for the management domain.
domain modify | Modifies the description of the specified domain.
domain show | Displays the specified attributes of the domain, including name and description.

Parent topic: Commands by category

Group commandsGroup commandsGroup commandsGroup commands manage Security Access Manager groups.commandsgroupA group is a set of Security Access Manager user accounts that have similar attributes. By using groups, you can use a group name in an access control list (ACL) instead of listing all users individually. When an LDAP-based user registry is used, group names are not case-sensitive.Table 1 lists group commands. Group commandsCommandDescriptiongroup createCreates a Security Access Manager group. Creates a group.group deleteDeletes the specified Security Access Manager group. Optionally deletes the information of the group, from the user registry. ACL entries that are associated with the group are also deleted. Deletes the specified Security Access Manager group and optionally deletes the information about the group from the user registry. ACL entries that are associated with the group are also deleted.group importCreates a Security Access Manager group by importing group data that exists in the user registry. Imports the information about an existing registry group to create a Security Access Manager group.group listGenerates a list of all groups, by group names, whose names match the specified pattern. Generates a list of all groups, by group names, whose names match the specified pattern.group modifyChanges an existing group by adding or changing a group description, adding members to the group, or removing members from the group. Changes an existing group by adding a description, or adding or removing a list of members.group showShows the properties of the specified group. Displays details about a specified group.Commands by categoryThe pdadmin commands are listed here by major category.

Group commands

Group commands manage Security Access Manager groups.

A group is a set of Security Access Manager user accounts that have similar attributes. By using groups, you can use a group name in an access control list (ACL) instead of listing all users individually. When an LDAP-based user registry is used, group names are not case-sensitive.

Table 301 lists group commands.

Table 301. Group commands

Command | Description
group create | Creates a group.
group delete | Deletes the specified Security Access Manager group and optionally deletes the information about the group from the user registry. ACL entries that are associated with the group are also deleted.
group import | Imports the information about an existing registry group to create a Security Access Manager group.
group list | Generates a list of all groups, by group names, whose names match the specified pattern.
group modify | Changes an existing group by adding a description, or adding or removing a list of members.
group show | Displays details about a specified group.

Parent topic: Commands by category

Login and logout commandsLogin and logout commandsLogin and logout commandsLogin and logout commands are used to log in to, and log out of, a Security Access Manager secure domain.commandslogincommandslogoutTable 1 lists login and logout commands. Logon commandsCommandDescriptionloginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. Authenticates the user to the Security Access Manager policy server as a given administrative identity in a domain.logoutDiscards any authentication credentials that are in effect. Discards any authentication credentials that are in effect.Commands by categoryThe pdadmin commands are listed here by major category.

Login and logout commands

Login and logout commands are used to log in to, and log out of, a Security Access Manager secure domain.

Table 302 lists login and logout commands.

Table 302. Logon commands

Command | Description
login | Authenticates the user to the Security Access Manager policy server as a given administrative identity in a domain.
logout | Discards any authentication credentials that are in effect.

Parent topic: Commands by category

Object commandsObject commandsObject commandsObject commands can protect objects by attaching ACLs or protected object policy (POP).commandsobjectTable 1 lists objects commands.Object commandsCommandDescriptionobject accessConfirms whether the specified access is permitted on the specified object. The access is determined based on the permissions of this user. Confirms whether a specified access is permitted on the named protected object.object createCreates a protected object. Creates a protected object.object deleteDeletes a protected object. Deletes a protected object.object existsIndicates whether a protected object exists. Confirms whether a protected object is in either the policy database or in an object space that is managed by an administration service plug-in.object listLists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object. Lists any objects that are grouped under the specified protected object. Also lists all the extended attributes that are associated with the specified protected object.object listandshowLists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy. Lists any child objects that are grouped under the specified protected object and shows all values that are associated with each of those objects.object modifyModifies an existing object. Modifies an existing object.object showShows values for the protected object. Shows all values that are associated with a protected object.object copyRecursively copy the policy from one protected object space to another. The policy that is copied includes ACLs, POPs, authorization rules, and extended attributes.Recursively copy the policy from one protected object space to another.Commands by categoryThe pdadmin commands are listed here by major category.

Object commands

Object commands can protect objects by attaching ACLs or protected object policy (POP).

Table 303 lists objects commands.

Table 303. Object commands

Command | Description
object access | Confirms whether a specified access is permitted on the named protected object.
object create | Creates a protected object.
object delete | Deletes a protected object.
object exists | Confirms whether a protected object is in either the policy database or in an object space that is managed by an administration service plug-in.
object list | Lists any objects that are grouped under the specified protected object. Also lists all the extended attributes that are associated with the specified protected object.
object listandshow | Lists any child objects that are grouped under the specified protected object and shows all values that are associated with each of those objects.
object modify | Modifies an existing object.
object show | Shows all values that are associated with a protected object.
object copy | Recursively copy the policy from one protected object space to another.

Parent topic: Commands by category

Object space commandsObject space commandsObject space commandsObject space commands allow the creation of more object spaces that contain protected objects that are used by third-party applications.commandsobject spaceTable 1 lists objectspace commands. Objectspace commandsCommandDescriptionobjectspace createCreates a protected object space under which protected objects can be placed. Creates a protected object space under which protected objects can be placed.objectspace deleteDeletes the specified protected object space. Deletes an existing protected object space and all associated protected objects.objectspace listLists all the existing protected object spaces in the policy server. Lists all the existing protected object spaces in the policy server.Commands by categoryThe pdadmin commands are listed here by major category.

Object space commands

Object space commands allow the creation of more object spaces that contain protected objects that are used by third-party applications.

Table 304 lists objectspace commands.

Table 304. Objectspace commands

Command | Description
objectspace create | Creates a protected object space under which protected objects can be placed.
objectspace delete | Deletes an existing protected object space and all associated protected objects.
objectspace list | Lists all the existing protected object spaces in the policy server.

Parent topic: Commands by category

Policy commandsPolicy commandsPolicy commandsPolicy commands manage user password and account policies.commandspolicyTable 1 lists policy commands. Policy commandsCommandDescriptionpolicy getDisplays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.Displays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.policy setSets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.Sets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.Commands by categoryThe pdadmin commands are listed here by major category.

Policy commands

Policy commands manage user password and account policies.

Table 305 lists policy commands.

Table 305. Policy commands

Command | Description
policy get | Displays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.
policy set | Sets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.

Parent topic: Commands by category

Protected object policy commandsProtected object policy commandsProtected object policy commandsProtected object policy commands allow the creation of a protected object policy (POP) and extended attributes for the protected object policiescommandsprotected object policy (POP)commandsPOPTable 1 lists pop commands. Protected object policy (POP) commandsCommandDescriptionpop attachAttaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached. Attaches a protected object policy to a specified protected object.pop createCreates a protected object policy (POP). Creates a protected object policy.pop deleteDeletes the specified protected object policy (POP). Deletes the specified protected object policy.pop detachDetaches a protected object policy (POP) from the specified protected object. Detaches a protected object policy from the specified protected object.pop findFinds and lists all protected objects that have a protected object policy (POP) attached. Finds and lists all protected objects with protected object policies attached.pop listLists all protected object policies that are created. Alternatively, lists all extended attributes that are associated with a protected object policy. Lists all created protected object policies.pop modifyModifies protected object policies. Modifies the protected object policy.pop showShows details about the protected object policy (POP). Alternatively, displays the values for the specified extended attribute from the specified protected object policy. Shows details about the protected object policy.Commands by categoryThe pdadmin commands are listed here by major category.

Protected object policy commands

Protected object policy commands allow the creation of a protected object policy (POP) and extended attributes for the protected object policies

Table 306 lists pop commands.

Table 306. Protected object policy (POP) commands

Command | Description
pop attach | Attaches a protected object policy to a specified protected object.
pop create | Creates a protected object policy.
pop delete | Deletes the specified protected object policy.
pop detach | Detaches a protected object policy from the specified protected object.
pop find | Finds and lists all protected objects with protected object policies attached.
pop list | Lists all created protected object policies.
pop modify | Modifies the protected object policy.
pop show | Shows details about the protected object policy.

Parent topic: Commands by category

Resource and resource group commandsResource and resource group commandsResource and resource group commandsResource and resource group commands manage resource-related information.commandsresource, listcommandsresource credential, listcommandsresource group, listTable 1 lists rsrc, rsrccred, and rsrcgroup commands.Resource commandsCommandDescriptionrsrc createCreates and names a web server single sign-on resource. Creates and names a server as a resource.rsrc deleteDeletes the specified single sign-on resource. Deletes the specified single sign-on resource.rsrc listReturns a list of all the single sign-on resource names. Returns a list of all the single sign-on resource names.rsrc showDisplays the resource information for the named resource. Displays the resource information for the named resource.rsrccred createCreates a single sign-on credential. Creates and names a resource credential.rsrccred deleteDeletes a single sign-on credential. Deletes only the resource credential information for an existing user.rsrccred list userReturns the list of single sign-on credentials for the specified user. The user must exist, or an error is displayed. Displays the names of all defined resource credentials and their type for the specified user. rsrccred modifyChanges a single sign-on credential. Changes the user ID and password resource credential information for the named resource. rsrccred showDisplays the attributes of a single sign-on credential. The credential identifier is composed of a resource name, a resource type, and a user name. Displays the resource credential information for a specified user.rsrcgroup createCreates and names a resource group. Creates and names a resource group.rsrcgroup deleteDeletes a single sign-on resource group. Deletes the named resource group, including any description information. rsrcgroup listDisplays the names of all resource groups that are defined in the user registry. Displays the names of all resource groups that are defined in the user registry.rsrcgroup modifyAdds or removes a single sign-on resource to or from a single sign-on resource group. Adds or removes a single sign-on resource to or from a single sign-on resource group.rsrcgroup showDisplays the resource group information for the specified resource group. Displays the resource group information for the specified resource group.Commands by categoryThe pdadmin commands are listed here by major category.

Resource and resource group commands

Resource and resource group commands manage resource-related information.

Table 307 lists rsrc, rsrccred, and rsrcgroup commands.

Table 307. Resource commands

Command | Description
rsrc create | Creates and names a server as a resource.
rsrc delete | Deletes the specified single sign-on resource.
rsrc list | Returns a list of all the single sign-on resource names.
rsrc show | Displays the resource information for the named resource.
rsrccred create | Creates and names a resource credential.
rsrccred delete | Deletes only the resource credential information for an existing user.
rsrccred list user | Displays the names of all defined resource credentials and their type for the specified user.
rsrccred modify | Changes the user ID and password resource credential information for the named resource.
rsrccred show | Displays the resource credential information for a specified user.
rsrcgroup create | Creates and names a resource group.
rsrcgroup delete | Deletes the named resource group, including any description information.
rsrcgroup list | Displays the names of all resource groups that are defined in the user registry.
rsrcgroup modify | Adds or removes a single sign-on resource to or from a single sign-on resource group.
rsrcgroup show | Displays the resource group information for the specified resource group.

Parent topic: Commands by category

Server commandsServer commandsServer commandsServer commands perform management tasks on Security Access Manager servers. commandsserverTable 1 lists server and server task commands, and the admin show config command. Server commandsCommandDescriptionadmin show confDisplays the current policy server configuration information, such as the type of registry or whether global sign-on is enabled. Displays current policy server configuration information.server listLists all registered Security Access Manager servers. Lists all registered servers.server listtasksRetrieves the list of tasks (commands) available for the specified installed Security Access Manager server or server instance. Retrieves the list of tasks (commands) available for this server.server replicateNotifies the installed Security Access Manager authorization server or server instance to receive database updates. Notifies authorization servers to receive database updates.server showDisplays the properties for the specified installed Security Access Manager server or server instance. The server must exist, or an error is displayed. Displays the specified properties of the server.server task helpLists detailed help information about a specific server task command. Lists detailed help information about a specific server task command.server task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. Manages the gathering and reporting of statistics for Security Access Manager servers and server instances.server task traceEnables the gathering of trace information for components of installed Security Access Manager servers or server instances. Enables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing.Commands by categoryThe pdadmin commands are listed here by major category.

Server commands

Server commands perform management tasks on Security Access Manager servers.

Table 308 lists server and server task commands, and the admin show config command.

Table 308. Server commands

Command | Description
admin show conf | Displays current policy server configuration information.
server list | Lists all registered servers.
server listtasks | Retrieves the list of tasks (commands) available for this server.
server replicate | Notifies authorization servers to receive database updates.
server show | Displays the specified properties of the server.
server task help | Lists detailed help information about a specific server task command.
server task stats | Manages the gathering and reporting of statistics for Security Access Manager servers and server instances.
server task trace | Enables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing.

Parent topic: Commands by category

Distributed session cache commandsDistributed session cache commandsDistributed session cache commandsDistributed session cache commands perform session management tasks. These commands are available only when a Web security server and distributed session cache are configured. commandsserver taskdistributed session cacheTable 1 lists server task commands.Server task commandsCommandDescriptionserver task sms replica set listLists all session management replica sets in the domain.Lists all session management replica sets in the domain.server task sms replica set showLists all session management replicas in the specified replica set with the time and date that each joined the realm.Lists all session management replica sets in the domain with the time and date each joined the realm.server task sms session listLists all session management sessions.Lists all session management sessions.server task sms session terminate all_sessionsTerminates all user sessions for a specific user.Terminates all user sessions for a specific user.server task sms session terminate sessionTerminates a user session by using a session ID.Terminates a specific session.Commands by categoryThe pdadmin commands are listed here by major category.

Distributed session cache commands

Distributed session cache commands perform session management tasks. These commands are available only when a Web security server and distributed session cache are configured.

Table 309 lists server task commands.

Table 309. Server task commands

Command | Description
server task sms replica set list | Lists all session management replica sets in the domain.
server task sms replica set show | Lists all session management replica sets in the domain with the time and date each joined the realm.
server task sms session list | Lists all session management sessions.
server task sms session terminate all_sessions | Terminates all user sessions for a specific user.
server task sms session terminate session | Terminates a specific session.

Parent topic: Commands by category

User commandsUser commandsUser commandsUser commands manage Security Access Manager users.commandsuser commandscommandsuser commandsuser createcommandsuser commandsuser importcommandsuser commandsuser modifycommandsuser commandsuser deletecommandsuser commandsuser showcommandsuser commandsuser listTable 1 lists user commands.User commandsCommandDescriptionuser createCreates a Security Access Manager user. Creates a Security Access Manager user account.user deleteDeletes the specified Security Access Manager user. Optionally deletes the information of the user in the user registry. Deletes a Security Access Manager user and optionally deletes the user information from the user registry. ACL entries that are associated with the user are also deleted.user importCreates a Security Access Manager user by importing user data that exists in the user registry. Imports the information about an existing registry user to create a Security Access Manager user.user listLists users by Security Access Manager user name or by registry identifier. Generates a list of all users whose names match the specified pattern, which is listed by user names.user modifyChanges various user account attributes. Modifies various user account parameters.user showDisplays the properties of the specified user. Displays details about a specified user.Commands by categoryThe pdadmin commands are listed here by major category.

User commands

User commands manage Security Access Manager users.

Table 310 lists user commands.

Table 310. User commands

Command | Description
user create | Creates a Security Access Manager user account.
user delete | Deletes a Security Access Manager user and optionally deletes the user information from the user registry. ACL entries that are associated with the user are also deleted.
user import | Imports the information about an existing registry user to create a Security Access Manager user.
user list | Generates a list of all users whose names match the specified pattern, which is listed by user names.
user modify | Modifies various user account parameters.
user show | Displays details about a specified user.

Parent topic: Commands by category

WebSEAL commandsWebSEAL commandsWebSEAL commandsWebSEAL commands perform management tasks on WebSEAL servers and instances. These commands are available only when WebSEAL is installed.commandsserver task WebSEALTable 1 lists server task commands. WebSEAL server task commandsCommandDescriptionserver task addAdds an application server to an existing WebSEAL junction. Adds an application server to an existing WebSEAL junction.server task cache flush allFlushes the HTML document cache. Flushes the HTML document cache.server task createCreates a WebSEAL junction point. Creates a WebSEAL junction point.server task deleteDeletes a WebSEAL junction point. Deletes a WebSEAL junction point.server task dynurl updateReloads the dynamic URL configuration file. Reloads the dynamic URL configuration file.server task helpLists detailed help information about a specific server task command. Lists detailed help information about a specific server task command.server task jmtClears or loads the junction mapping table data. Clears or loads the junction mapping table data.server task listLists all junction points on a WebSEAL server or server instance. Lists all junction points on a WebSEAL server or server instance.server task offlinePlaces the server that is at this junction in an offline operational state.Places the server that is at this junction in an offline operational state.server task onlinePlaces the server that is at this junction in an online operational state.Places the server that is at this junction in an online operational state.server task refresh all_sessionsRefreshes the credential for all sessions for a specified user. Refreshes the credential for all sessions for a specified user.server task reloadReloads the junction mapping table from the database. Reloads the junction mapping table from the database.server task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. Removes the specified installed WebSEAL server or server instance from a WebSEAL junction point.server task showDisplays detailed information about the specified WebSEAL junction. Displays detailed information about the specified WebSEAL junction.server task terminate all_sessionsTerminates all user sessions for a specific user. Terminates all user sessions for a specific user.server task terminate sessionTerminates a user session by using a session ID. Terminates a user session by using a session ID.server task throttlePlaces the server that is at this junction in a throttled operational state.Places the server that is at this junction in a throttled operational state.server task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. Adds an additional installed WebSEAL server or server instance to an existing virtual host junction. server task virtualhost createCreates a virtual host junction. Creates a virtual host junction.server task virtualhost deleteDeletes a virtual host junction. Deletes a virtual host junction.server task virtualhost listLists all configured virtual host junctions by label name. Lists all configured virtual host junctions by label name.server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. Places the server that is at this virtual host junction in an offline operational state.server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. Places the server that is at this virtual host junction in an online operational state.server task virtualhost removeRemoves the specified server from a virtual host junction. Removes the specified server from a virtual host junction.server task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. Displays information about the specified virtual host junction.server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. Places the server that is at this virtual host junction in a throttled operational state.server task server restartRestarts a WebSEAL server by using the Security Access Manager server task framework. Restarts the WebSEAL instance. server task server syncSynchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework. Synchronizes the configuration of the supplied WebSEAL authorization server to the current WebSEAL server. server task file catReturns the contents of a specified file to the administration console. This command requires authentication of administrator ID and password.Obtains the string content of the specified file. A flag controls whether the contents of the file are base64 encoded or not encoded. A WebSEAL configuration item defines the maximum allowable size of the file.Commands by categoryThe pdadmin commands are listed here by major category.

WebSEAL commands

WebSEAL commands perform management tasks on WebSEAL servers and instances. These commands are available only when WebSEAL is installed.

Table 311 lists server task commands.

Table 311. WebSEAL server task commands

Command | Description
server task add | Adds an application server to an existing WebSEAL junction.
server task cache flush all | Flushes the HTML document cache.
server task create | Creates a WebSEAL junction point.
server task delete | Deletes a WebSEAL junction point.
server task dynurl update | Reloads the dynamic URL configuration file.
server task help | Lists detailed help information about a specific server task command.
server task jmt | Clears or loads the junction mapping table data.
server task list | Lists all junction points on a WebSEAL server or server instance.
server task offline | Places the server that is at this junction in an offline operational state.
server task online | Places the server that is at this junction in an online operational state.
server task refresh all_sessions | Refreshes the credential for all sessions for a specified user.
server task reload | Reloads the junction mapping table from the database.
server task remove | Removes the specified installed WebSEAL server or server instance from a WebSEAL junction point.
server task show | Displays detailed information about the specified WebSEAL junction.
server task terminate all_sessions | Terminates all user sessions for a specific user.
server task terminate session | Terminates a user session by using a session ID.
server task throttle | Places the server that is at this junction in a throttled operational state.
server task virtualhost add | Adds an additional installed WebSEAL server or server instance to an existing virtual host junction.
server task virtualhost create | Creates a virtual host junction.
server task virtualhost delete | Deletes a virtual host junction.
server task virtualhost list | Lists all configured virtual host junctions by label name.
server task virtualhost offline | Places the server that is at this virtual host junction in an offline operational state.
server task virtualhost online | Places the server that is at this virtual host junction in an online operational state.
server task virtualhost remove | Removes the specified server from a virtual host junction.
server task virtualhost show | Displays information about the specified virtual host junction.
server task virtualhost throttle | Places the server that is at this virtual host junction in a throttled operational state.
server task server restart | Restarts the WebSEAL instance.
server task server sync | Synchronizes the configuration of the supplied WebSEAL authorization server to the current WebSEAL server.
server task file cat | Obtains the string content of the specified file. A flag controls whether the contents of the file are base64 encoded or not encoded. A WebSEAL configuration item defines the maximum allowable size of the file.

Parent topic: Commands by category

acl attachacl attachacl attachAttaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one. access control list (ACL) commandsacl attachattachaccess control list (ACL)Requires authentication (administrator ID and password) to use this command.Syntaxacl attach object_name acl_name DescriptionAt most, one ACL can be attached to a given protected object. The same ACL can be attached to multiple protected objects. Ensure that you are familiar with ACL management before you use this function. Optionsacl_nameSpecifies the ACL policy that is applied to the named object. The ACL policy must exist, or an error is displayed. Examples of the ACL names are default-root, test, default-management, and pubs_acl3.object_nameSpecifies the object to which to apply the named ACL policy. The object name must exist, or an error is displayed. Examples of object names are:/Management/Groups/Travel/WebSEAL/Management Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example attaches the ACL policy, pubs_acl3, to the protected object, /Management: pdadmin sec_master> acl attach /Management pubs_acl3See alsoacl createCreates an ACL policy in the ACL database. This command does not create ACL entries. acl detachDetaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl attach

Attaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl attach object_name acl_name

Description

At most, one ACL can be attached to a given protected object. The same ACL can be attached to multiple protected objects. Ensure that you are familiar with ACL management before you use this function.

Options

acl_name

Specifies the ACL policy that is applied to the named object. The ACL policy must exist, or an error is displayed.

Examples of the ACL names are default-root, test, default-management, and pubs_acl3.

object_name

Specifies the object to which to apply the named ACL policy. The object name must exist, or an error is displayed.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example attaches the ACL policy, pubs_acl3, to the protected object, /Management:

pdadmin sec_master> acl attach /Management pubs_acl3

See also

acl create

acl detach

Parent topic: pdadmin commands

acl createacl createacl createCreates an ACL policy in the ACL database. This command does not create ACL entries. access control list (ACL) commandsacl createRequires authentication (administrator ID and password) to use this command.Syntaxacl create acl_name Optionsacl_nameSpecifies the name of the ACL policy that is being created. A valid ACL policy name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. The following characters cannot be used in the name of the ACL policy: ! " # & ( ) * + , ; : < > = @ / \ | .Examples: default-root, test, default-management, and pubs_acl3 Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates an ACL policy named pubs_acl3: pdadmin sec_master> acl create pubs_acl3The following example creates an ACL policy named Test-ACL: pdadmin sec_master> acl create Test-ACL See also acl attachAttaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one. acl deleteDeletes an ACL policy from the ACL database. acl modifyModifies access control list (ACL) policies. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl create

Creates an ACL policy in the ACL database. This command does not create ACL entries.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl create acl_name

Options

acl_name

Specifies the name of the ACL policy that is being created. A valid ACL policy name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. The following characters cannot be used in the name of the ACL policy:

! " # & ( ) * + , ; : < > = @ / \ | .

Examples: default-root, test, default-management, and pubs_acl3

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates an ACL policy named pubs_acl3:

pdadmin sec_master> acl create pubs_acl3

The following example creates an ACL policy named Test-ACL:

pdadmin sec_master> acl create Test-ACL

See also

acl attach

acl delete

acl modify

Parent topic: pdadmin commands

acl deleteacl deleteacl deleteDeletes an ACL policy from the ACL database. access control list (ACL) commandsacl deleteRequires authentication (administrator ID and password) to use this command.Syntaxacl delete acl_name Optionsacl_nameSpecifies the name of the ACL policy that is being deleted from the ACL database. The ACL policy must exist, or an error is displayed. Examples: default-root, test, default-management, and pubs_acl3. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the ACL policy that is named pubs_acl3: pdadmin sec_master> acl delete pubs_acl3The following example deletes the ACL policy that is named Test-ACL: pdadmin sec_master> acl delete Test-ACL See alsoacl detachDetaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl delete

Deletes an ACL policy from the ACL database.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl delete acl_name

Options

acl_name

Specifies the name of the ACL policy that is being deleted from the ACL database. The ACL policy must exist, or an error is displayed.

Examples: default-root, test, default-management, and pubs_acl3.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the ACL policy that is named pubs_acl3:

pdadmin sec_master> acl delete pubs_acl3

The following example deletes the ACL policy that is named Test-ACL:

pdadmin sec_master> acl delete Test-ACL

See also

acl detach

Parent topic: pdadmin commands

acl detachacl detachacl detachDetaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database. access control list (ACL) commandsacl detachRequires authentication (administrator ID and password) to use this command.Syntaxacl detach object_name DescriptionOnly one access control list at a time can be attached to an object. Therefore, the currently attached access control list is detached. If the object does not have an attached ACL policy, an error is displayed. Optionsobject_nameSpecifies the object from which the current ACL policy is being removed. The object must exist and have an ACL attached, or an error is displayed. Examples of object names are:/Management/Groups/Travel/WebSEAL/Management Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example detaches the ACL from the protected object /Management: pdadmin sec_master> acl detach /Management See alsoacl attachAttaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one. acl deleteDeletes an ACL policy from the ACL database. acl modifyModifies access control list (ACL) policies. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl detach

Detaches the current ACL policy from a protected object. This command does not delete the ACL policy from the ACL database.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl detach object_name

Description

Only one access control list at a time can be attached to an object. Therefore, the currently attached access control list is detached. If the object does not have an attached ACL policy, an error is displayed.

Options

object_name

Specifies the object from which the current ACL policy is being removed. The object must exist and have an ACL attached, or an error is displayed.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example detaches the ACL from the protected object /Management:

pdadmin sec_master> acl detach /Management

See also

acl attach

acl delete

acl modify

Parent topic: pdadmin commands

acl findacl findacl findReturns a list of protected objects, which have the specified ACL attached.access control list (ACL) commandsacl findRequires authentication (administrator ID and password) to use this command.Syntaxacl find acl_name DescriptionA user must have the browse (b) and view (v) permissions for the object to be listed when the pdadmin object show command is issued. Otherwise, an error is returned: The user is not authorized to view one or more protected objects where the requested acl is attached. Optionsacl_nameSpecifies the name of the ACL policy that you want to find. The ACL policy must exist, or an error is displayed. Examples: default-root, test, default-management, and pubs_acl3 Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example lists the protected object that has the default-config ACL attached: pdadmin sec_master> acl find default-configProvides output like:/Management/ConfigThe following example lists the protected objects that have the user-defined ACL, _WebAppServer_deployedResources_CosNamingDelete_admin_ACL, attached: pdadmin sec_master> acl find _WebAppServer_deployedResources_CosNamingDelete_admin_ACLProvides output like: /WebAppServer/deployedResources/CosNamingDelete/admin See alsoacl listLists the names of all defined access control lists. Alternatively, lists the extended attribute keys that are associated with a specific ACL. acl showLists the complete set of entries for a specific access control list (ACL) policy. Alternatively, lists the values of a specific extended attribute that is associated with an ACL policy. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl find

Returns a list of protected objects, which have the specified ACL attached.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl find acl_name

Description

A user must have the browse (b) and view (v) permissions for the object to be listed when the pdadmin object show command is issued. Otherwise, an error is returned:

The user is not authorized to view one or more protected objects where the
requested acl is attached.

Options

acl_name

Specifies the name of the ACL policy that you want to find. The ACL policy must exist, or an error is displayed.

Examples: default-root, test, default-management, and pubs_acl3

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists the protected object that has the default-config ACL attached:

pdadmin sec_master> acl find default-config

Provides output like:

/Management/Config

The following example lists the protected objects that have the user-defined ACL, _WebAppServer_deployedResources_CosNamingDelete_admin_ACL, attached:

pdadmin sec_master> acl find
_WebAppServer_deployedResources_CosNamingDelete_admin_ACL

Provides output like:

 /WebAppServer/deployedResources/CosNamingDelete/admin

See also

acl list

acl show

Parent topic: pdadmin commands

acl listacl listacl listLists the names of all defined access control lists. Alternatively, lists the extended attribute keys that are associated with a specific ACL. access control list (ACL) commandsacl listRequires authentication (administrator ID and password) to use this command.Syntaxacl listacl list [acl_name attribute]acl list [pattern max-return] Optionsacl_name attributeSpecifies the ACL policy for which to list the attributes. The ACL policy must exist, or an error is displayed. (Optional)Examples: default-root, test, default-management and pubs_acl3. pattern max-returnSpecifies the pattern and the maximum number of access control lists to be returned. (Optional) Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example lists ACL policies: pdadmin sec_master> acl list The output is like: default-webseal default-root test default-replica default-management See alsoacl findReturns a list of protected objects, which have the specified ACL attached. acl showLists the complete set of entries for a specific access control list (ACL) policy. Alternatively, lists the values of a specific extended attribute that is associated with an ACL policy. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl list

Lists the names of all defined access control lists. Alternatively, lists the extended attribute keys that are associated with a specific ACL.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl list

acl list [acl_name attribute]

acl list [pattern max-return]

Options

acl_name attribute

Specifies the ACL policy for which to list the attributes. The ACL policy must exist, or an error is displayed. (Optional)

Examples: default-root, test, default-management and pubs_acl3.

pattern max-return

Specifies the pattern and the maximum number of access control lists to be returned. (Optional)

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example lists ACL policies:

pdadmin sec_master> acl list

The output is like:

default-webseal
default-root
test
default-replica
default-management

See also

acl find

acl show

Parent topic: pdadmin commands

acl modifyacl modifyacl modifyModifies access control list (ACL) policies. access control list (ACL) commandsacl modifyRequires authentication (administrator ID and password) to use this command.Syntax acl modify acl_name delete attribute attribute_name [attribute_value] acl modify acl_name description description acl modify acl_name remove any-other acl modify acl_name remove group group_name acl modify acl_name remove unauthenticated acl modify acl_name remove user user_name acl modify acl_name set any-other [permissions] acl modify acl_name set attribute attribute_name attribute_value acl modify acl_name set description description acl modify acl_name set group group_name [permissions] acl modify acl_name set unauthenticated [permissions] acl modify acl_name set user user_name [permissions] Optionsacl_nameSpecifies the ACL policy that you want to be modified. The ACL policy must exist, or an error is displayed. Examples: default-root, test, default-management, and pubs_acl3delete attribute attribute_name [attribute_value]Deletes the specified extended attribute name and value from the specified ACL. The attribute must exist, or an error is displayed. The attribute_value deletes the specified value from the specified extended attribute key in the specified ACL. (Optional)Examples of extended attribute names and values: Dept_No 445 Employee_Name "Diana Lucas"description descriptionSets or modifies the description for the specified ACL. This option is equivalent to the acl modify set description command. Use the acl modify description command instead of the acl modify set description command. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed.If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.Example of description: "Department number of employee"permissionsSecurity Access Manager uses a set of default actions (known as primary action tasks and permissions) that cover a wide range of operations. You can also create your own action tasks and permissions. A complete list of primary action tasks and their associated permissions includes: T Traverse Base c Control Base g Delegation Base m Modify Generic d Delete Generic b Browse Base s Server Admin Generic v View Generic a Attach Base B Bypass POP Base t Trace Base r Read WebSEAL x Execute WebSEAL l List Directory WebSEAL N Create Base W Password Base A Add Base R Bypass AuthzRule BaseFor more information on actions, see Action groups and actionsA domain administrator defines the actions that requesters can perform on objects in the protected object spaces. An action is a permission in an action group that is defined in the action group by an action bit. . For a description of default permissions, see Default permissions in the primary action groupSecurity Access Manager defines permissions with action bits. When you install Security Access Manager, the default primary action group is created. This action group contains 17 permissions. . remove any-otherRemoves the ACL entry for the any-other user category from the specified ACL.remove group group_nameRemoves the ACL entry for the specified group from the specified ACL. The group must exist, or an error is displayed. Examples of group names are Credit, Sales, and Test-group.remove unauthenticatedRemoves the ACL entry for the unauthenticated user category from the specified ACL.remove user user_nameRemoves the ACL entry for the specified user from the specified ACL. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones".set any-other [permissions]Sets or modifies the ACL entry for the any-other user category in the ACL. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z).set attribute attribute_name attribute_valueSets the extended attribute value for the specified extended attribute key in the specified ACL. The attribute must exist, or an error is displayed. If the attribute exists, the attribute value is added as an additional value if the same value does not exist for this attribute. If the same value exists for this attribute, it does not get added again (duplicate values are not allowed), and no error is returned. The optional attribute_value sets the specified value from the specified extended attribute key in the specified ACL.Examples of extended attribute names and values: Dept_No 445 Employee_name "Diana Lucas"set description descriptionSets or modifies the description for the specified ACL. This option is equivalent to the acl modify description command. Use the acl modify description command instead of the acl modify set description command.set group group_name [permissions]Sets or modifies the ACL entry for the specified group in the specified ACL. The group must exist, or an error is displayed. Examples of group names are Credit, Sales, and Test-group.Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for the list of possible permissions.set unauthenticated [permissions]Sets or modifies the ACL entry for the unauthenticated user category in the specified ACL. Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for examples of permissions.set user user_name [permissions]Sets permissions that the user is permitted to perform. The user must exist or an error is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones".Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for examples of permissions. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example sets the any-other user entry in the pubs ACL to have r, the Read (WebSEAL) permission: pdadmin sec_master> acl modify pubs set any-other rThe following example sets the sales group entry in the pubs ACL to have the Tr permissions, which are the Traverse and Read (Base) permissions: pdadmin sec_master> acl modify pubs set group sales TrThe following example sets the unauthenticated user entry in the docs ACL to have the r permission, which is the Read (WebSEAL) permission: pdadmin sec_master> acl modify docs set unauthenticated rThe following example sets the peter user entry in the pubs ACL to have the Tr permissions, which are the Traverse (Base) and Read (WebSEAL) permissions: pdadmin sec_master> acl modify pubs set user peter TrThe following example sets the kathy user entry in the test ACL to have Tbr permissions, which are the Traverse (Base), Browse (Base) and Read (WebSEAL) permissions. It also sets custom permissions PS for the existing test-group action group. It then displays the results. pdadmin sec_master> acl modify test set user kathy Tbr[test-group]PS pdadmin sec_master> acl show test ACL Name: test Description: Entries: User sec_master TcmdbsvaBl Group ivmgrd-servers Tl Any-other r User kathy Tbr[test-group]PSThe following example sets the kathy user entry in the test ACL to have Tbr permissions, which are the Traverse (Base), Browse (Base), and Read (WebSEAL) permissions. It then displays the results. pdadmin sec_master> acl modify test set user kathy Tbr pdadmin sec_master> acl show test ACL Name: test Description: Entries: User sec_master TcmdbsvaBl Group ivmgrd-servers Tl Any-other r User kathy Tbr See alsoacl attachAttaches an ACL policy to a protected object. If the protected object already has an ACL attached, the ACL is replaced with a new one. acl createCreates an ACL policy in the ACL database. This command does not create ACL entries. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl modify

Modifies access control list (ACL) policies.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl modify acl_name delete attribute attribute_name [attribute_value]

acl modify acl_name description description

acl modify acl_name remove any-other

acl modify acl_name remove group group_name

acl modify acl_name remove unauthenticated

acl modify acl_name remove user user_name

acl modify acl_name set any-other [permissions]

acl modify acl_name set attribute attribute_name attribute_value

acl modify acl_name set description description

acl modify acl_name set group group_name [permissions]

acl modify acl_name set unauthenticated [permissions]

acl modify acl_name set user user_name [permissions]

Options

acl_name

Specifies the ACL policy that you want to be modified. The ACL policy must exist, or an error is displayed.

Examples: default-root, test, default-management, and pubs_acl3

delete attribute attribute_name [attribute_value]

Deletes the specified extended attribute name and value from the specified ACL. The attribute must exist, or an error is displayed.

The attribute_value deletes the specified value from the specified extended attribute key in the specified ACL. (Optional)

Examples of extended attribute names and values:

Dept_No 445
Employee_Name "Diana Lucas"

description description

Sets or modifies the description for the specified ACL. This option is equivalent to the acl modify set description command. Use the acl modify description command instead of the acl modify set description command.

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed.

If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

Example of description: "Department number of employee"

permissions

Security Access Manager uses a set of default actions (known as primary action tasks and permissions) that cover a wide range of operations. You can also create your own action tasks and permissions.

A complete list of primary action tasks and their associated permissions includes:

T Traverse Base
c Control Base
g Delegation Base
m Modify Generic
d Delete Generic
b Browse Base
s Server Admin Generic
v View Generic
a Attach Base
B Bypass POP Base
t Trace Base
r Read WebSEAL
x Execute WebSEAL
l List Directory WebSEAL
N Create Base
W Password Base
A Add Base
R Bypass AuthzRule Base

For more information on actions, see Action groups and actions. For a description of default permissions, see Default permissions in the primary action group.

remove any-other

Removes the ACL entry for the any-other user category from the specified ACL.

remove group group_name

Removes the ACL entry for the specified group from the specified ACL. The group must exist, or an error is displayed.

Examples of group names are Credit, Sales, and Test-group.

remove unauthenticated

Removes the ACL entry for the unauthenticated user category from the specified ACL.

remove user user_name

Removes the ACL entry for the specified user from the specified ACL. The user must exist, or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

set any-other [permissions]

Sets or modifies the ACL entry for the any-other user category in the ACL. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z).

set attribute attribute_name attribute_value

Sets the extended attribute value for the specified extended attribute key in the specified ACL. The attribute must exist, or an error is displayed. If the attribute exists, the attribute value is added as an additional value if the same value does not exist for this attribute. If the same value exists for this attribute, it does not get added again (duplicate values are not allowed), and no error is returned.

The optional attribute_value sets the specified value from the specified extended attribute key in the specified ACL.

Examples of extended attribute names and values:

Dept_No 445
Employee_name "Diana Lucas"

set description description

Sets or modifies the description for the specified ACL. This option is equivalent to the acl modify description command. Use the acl modify description command instead of the acl modify set description command.

set group group_name [permissions]

Sets or modifies the ACL entry for the specified group in the specified ACL. The group must exist, or an error is displayed.

Examples of group names are Credit, Sales, and Test-group.

Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for the list of possible permissions.

set unauthenticated [permissions]

Sets or modifies the ACL entry for the unauthenticated user category in the specified ACL.

Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for examples of permissions.

set user user_name [permissions]

Sets permissions that the user is permitted to perform. The user must exist or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for examples of permissions.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example sets the any-other user entry in the pubs ACL to have r, the Read (WebSEAL) permission:

pdadmin sec_master> acl modify pubs set any-other r

The following example sets the sales group entry in the pubs ACL to have the Tr permissions, which are the Traverse and Read (Base) permissions:

pdadmin sec_master> acl modify pubs set group sales Tr

The following example sets the unauthenticated user entry in the docs ACL to have the r permission, which is the Read (WebSEAL) permission:

pdadmin sec_master> acl modify docs set unauthenticated r

The following example sets the peter user entry in the pubs ACL to have the Tr permissions, which are the Traverse (Base) and Read (WebSEAL) permissions:

pdadmin sec_master> acl modify pubs set user peter Tr

The following example sets the kathy user entry in the test ACL to have Tbr permissions, which are the Traverse (Base), Browse (Base) and Read (WebSEAL) permissions. It also sets custom permissions PS for the existing test-group action group. It then displays the results.

pdadmin sec_master> acl modify test set user kathy Tbr[test-group]PS

pdadmin sec_master> acl show test

ACL Name: test
Description:
Entries:
User sec_master TcmdbsvaBl
Group ivmgrd-servers Tl
Any-other r
User kathy Tbr[test-group]PS

The following example sets the kathy user entry in the test ACL to have Tbr permissions, which are the Traverse (Base), Browse (Base), and Read (WebSEAL) permissions. It then displays the results.

pdadmin sec_master> acl modify test set user kathy Tbr

pdadmin sec_master> acl show test

ACL Name: test
Description:
Entries:
User sec_master TcmdbsvaBl
Group ivmgrd-servers Tl
Any-other r
User kathy Tbr

See also

acl attach

acl create

Parent topic: pdadmin commands

acl showacl showacl showLists the complete set of entries for a specific access control list (ACL) policy. Alternatively, lists the values of a specific extended attribute that is associated with an ACL policy.access control list (ACL) commandsacl show Requires authentication (administrator ID and password) to use this command.Syntaxacl show acl_name [attribute attribute_name] Optionsacl_nameSpecifies the name of the ACL policy for which the extended attribute values are displayed. The ACL policy must exist, or an error is displayed. Examples of ACL names are default-root, test, default-management, and pubs_acl3.attribute attribute_nameSpecifies the name of the extended attribute whose values are displayed. (Optional) The system handles this command as follows: If the ACL either has an attribute or had an attribute in the past, no error is displayed.If the ACL never had an attribute, then an error is displayed.Examples of extended attribute names are Dept_No and Employee_Name. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example shows details about ACL test-acl: pdadmin sec_master> acl show test-acl ACL Name: test-acl Description: Entries: User sec_master Tcmdbva Group ivmgrd-servers Tl Any-other r See alsoacl findReturns a list of protected objects, which have the specified ACL attached. acl listLists the names of all defined access control lists. Alternatively, lists the extended attribute keys that are associated with a specific ACL. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

acl show

Lists the complete set of entries for a specific access control list (ACL) policy. Alternatively, lists the values of a specific extended attribute that is associated with an ACL policy.

Requires authentication (administrator ID and password) to use this command.

Syntax

acl show acl_name [attribute attribute_name]

Options

acl_name

Specifies the name of the ACL policy for which the extended attribute values are displayed. The ACL policy must exist, or an error is displayed.

Examples of ACL names are default-root, test, default-management, and pubs_acl3.

attribute attribute_name

Specifies the name of the extended attribute whose values are displayed. (Optional) The system handles this command as follows:

If the ACL either has an attribute or had an attribute in the past, no error is displayed.

If the ACL never had an attribute, then an error is displayed.

Examples of extended attribute names are Dept_No and Employee_Name.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example shows details about ACL test-acl:

pdadmin sec_master> acl show test-acl

ACL Name: test-acl
Description:
Entries:
User sec_master Tcmdbva
Group ivmgrd-servers Tl
Any-other r

See also

acl find

acl list

Parent topic: pdadmin commands

action createaction createaction createCreates and adds an action (permission) to an action group. action commandsaction createRequires authentication (administrator ID and password) to use this command.Syntaxaction create action_name action_label action_type [action_group_name] DescriptionAction codes (permissions) consist of one alphabetic character (a-z or A-Z) and are case-sensitive. Each action code can be used only once within an action group. Ensure that you do not attempt to redefine the default action codes when you add custom codes to the primary group. Optionsaction_group_nameSpecifies the name of the action group to which the action code is to be added. If no action group is specified, the action is added to the primary action group. Supports a maximum of 32 action groups. Examples of action group names are primary and test-group. (Optional) action_labelSpecifies the label or description for the action. Each default permission is displayed with a label that describes the operation that it governs. In addition, the ACLs are grouped in one of the following ways, according to their use: In a particular part of the objectspace, such as, WebSEAL.Across the entire objectspace, such as, Base, Generic.For example, time is the action label in the following example: k time Ext-AuthznA valid action label is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.Examples of action labels: time, Generic, Base, and WebSEALaction_nameSpecifies the new single-character permission that is being created, which can be specified by using any case. Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). For example, k is the action name in the following example: k time Ext-Authznaction_typeSpecifies the organizational category for this action within a specified action group. The action type can be a description of the action, such as what application the action is specific to. The action type is application-specific and typically refers to: The application that defined the action, such as, WebSEAL.The function that uses the action, such as, Ext-Authzn, for extended authorization checks.A valid action type is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.For example, Ext-Authzn is the action type in the following example: k time Ext-Authzn Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates an action code named k with an action label of time and an action type of Ext-Authzn within the primary action group: pdadmin sec_master> action create k time Ext-AuthznThe following example creates a customized action named P and an action label of Test-Action with an action type of Special within the test-group action group: pdadmin sec_master> action create P Test-Action Special test-group See alsoaction deleteDeletes an action (permission) from an action group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

action create

Creates and adds an action (permission) to an action group.

Requires authentication (administrator ID and password) to use this command.

Syntax

action create action_name action_label action_type [action_group_name]

Description

Action codes (permissions) consist of one alphabetic character (a-z or A-Z) and are case-sensitive. Each action code can be used only once within an action group. Ensure that you do not attempt to redefine the default action codes when you add custom codes to the primary group.

Options

action_group_name

Specifies the name of the action group to which the action code is to be added. If no action group is specified, the action is added to the primary action group. Supports a maximum of 32 action groups. Examples of action group names are primary and test-group. (Optional)

action_label

Specifies the label or description for the action. Each default permission is displayed with a label that describes the operation that it governs. In addition, the ACLs are grouped in one of the following ways, according to their use:

In a particular part of the objectspace, such as, WebSEAL.

Across the entire objectspace, such as, Base, Generic.

For example, time is the action label in the following example:

k time Ext-Authzn

A valid action label is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

Examples of action labels: time, Generic, Base, and WebSEAL

action_name

Specifies the new single-character permission that is being created, which can be specified by using any case.

Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z).

For example, k is the action name in the following example:

k time Ext-Authzn

action_type

Specifies the organizational category for this action within a specified action group. The action type can be a description of the action, such as what application the action is specific to. The action type is application-specific and typically refers to:

The application that defined the action, such as, WebSEAL.

The function that uses the action, such as, Ext-Authzn, for extended authorization checks.

A valid action type is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

For example, Ext-Authzn is the action type in the following example:

k time Ext-Authzn

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates an action code named k with an action label of time and an action type of Ext-Authzn within the primary action group:

pdadmin sec_master> action create k time Ext-Authzn

The following example creates a customized action named P and an action label of Test-Action with an action type of Special within the test-group action group:

pdadmin sec_master> action create P Test-Action Special test-group

See also

action delete

Parent topic: pdadmin commands

action deleteaction deleteaction deleteDeletes an action (permission) from an action group. action commandsaction deleteRequires authentication (administrator ID and password) to use this command.Syntaxaction delete action_name [action_group_name] Optionsaction_group_nameSpecifies the name of the action group from which the specified action must be deleted. Examples of action group names are primary and test-group. (Optional)action_nameSpecifies the name of the action to be deleted. The action code must exist, or an error is displayed. Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). For example, k is the action name in the following example: k time Ext-Authzn Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes action k from the primary action group: pdadmin sec_master> action delete kThe following example deletes the action z from the agz action group: pdadmin sec_master> action delete z agz See alsoaction createCreates and adds an action (permission) to an action group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

action delete

Deletes an action (permission) from an action group.

Requires authentication (administrator ID and password) to use this command.

Syntax

action delete action_name [action_group_name]

Options

action_group_name

Specifies the name of the action group from which the specified action must be deleted. Examples of action group names are primary and test-group. (Optional)

action_name

Specifies the name of the action to be deleted. The action code must exist, or an error is displayed.

Security Access Manager uses a set of default actions that cover a wide range of operations. Valid actions, or permissions, are represented by single alphabetic ASCII characters (a-z, A-Z). For example, k is the action name in the following example:

k time Ext-Authzn

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes action k from the primary action group:

pdadmin sec_master> action delete k

The following example deletes the action z from the agz action group:

pdadmin sec_master> action delete z agz

See also

action create

Parent topic: pdadmin commands

action group createaction group createaction group createCreates an action group.action commandsaction group createRequires authentication (administrator ID and password) to use this command.Syntaxaction group create action_group_name Optionsaction_group_nameSpecifies the name of the action group to create. Supports a maximum of 32 action groups. The action group must not exist, or an error is displayed. A valid action group name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.Examples of action group names are primary and test-group. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example creates the test action group: pdadmin sec_master> action group create testpdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

action group create

Creates an action group.

Requires authentication (administrator ID and password) to use this command.

Syntax

action group create action_group_name

Options

action_group_name

Specifies the name of the action group to create. Supports a maximum of 32 action groups. The action group must not exist, or an error is displayed.

A valid action group name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

Examples of action group names are primary and test-group.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example creates the test action group:

pdadmin sec_master> action group create test

Parent topic: pdadmin commands

action group deleteaction group deleteaction group deleteDeletes an action group. action commandsaction group deleteRequires authentication (administrator ID and password) to use this command.Syntaxaction group delete action_group_name Optionsaction_group_nameSpecifies the name of the action group to delete. All the actions that belong to the specified group are also deleted. The action group must exist, or an error is displayed. Examples of action group names are primary and test-group. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example deletes the test action group: pdadmin sec_master> action group delete testpdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

action group delete

Deletes an action group.

Requires authentication (administrator ID and password) to use this command.

Syntax

action group delete action_group_name

Options

action_group_name

Specifies the name of the action group to delete. All the actions that belong to the specified group are also deleted. The action group must exist, or an error is displayed. Examples of action group names are primary and test-group.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example deletes the test action group:

pdadmin sec_master> action group delete test

Parent topic: pdadmin commands

action group listaction group listaction group listLists all action groups. action commandsaction group listRequires authentication (administrator ID and password) to use this command.Syntaxaction group list DescriptionThe action group list command lists all the defined names of action groups OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example lists the names of all defined action groups: pdadmin sec_master> action group list primary test-grouppdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

action group list

Lists all action groups.

Requires authentication (administrator ID and password) to use this command.

Syntax

action group list

Description

The action group list command lists all the defined names of action groups

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example lists the names of all defined action groups:

pdadmin sec_master> action group list
		 primary
		 test-group

Parent topic: pdadmin commands

action listaction listaction listLists all actions (permissions) in an action group. action commandsaction listRequires authentication (administrator ID and password) to use this command.Syntaxaction list [action_group_name] Optionsaction_group_nameSpecifies the name of the action group for which all actions are displayed. If this option is not specified, actions that are defined in the primary action group are listed. The action group must exist, or an error is displayed. Examples of action group names are primary and test-group. (Optional) Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example displays all existing actions in the primary action group:pdadmin sec_master> action listTTraverseBase cControlBase gDelegationBase mModifyGeneric dDeleteGeneric bBrowseBase sServer AdminGeneric vViewGeneric aAttachBase BBypass POPBase tTraceBase rReadWebSEAL xExecuteWebSEAL lList DirectoryWebSEAL NCreateBase WPasswordBase AAddBase RBypass AuthzRuleBasepdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

action list

Lists all actions (permissions) in an action group.

Requires authentication (administrator ID and password) to use this command.

Syntax

action list [action_group_name]

Options

action_group_name

Specifies the name of the action group for which all actions are displayed. If this option is not specified, actions that are defined in the primary action group are listed. The action group must exist, or an error is displayed.

Examples of action group names are primary and test-group. (Optional)

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example displays all existing actions in the primary action group:

pdadmin sec_master> action list

TTraverseBase
cControlBase
gDelegationBase
mModifyGeneric
dDeleteGeneric
bBrowseBase
sServer AdminGeneric
vViewGeneric
aAttachBase
BBypass POPBase
tTraceBase
rReadWebSEAL
xExecuteWebSEAL
lList DirectoryWebSEAL
NCreateBase
WPasswordBase
AAddBase
RBypass AuthzRuleBase

Parent topic: pdadmin commands

admin show confadmin show confadmin show confDisplays the current policy server configuration information, such as the type of registry or whether global sign-on is enabled. server commandsadmin show confRequires authentication (administrator ID and password) to use this command.Syntaxadmin show conf OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example displays the current server configuration information: pdadmin sec_master> admin show conf LDAP: yes secAuthority GSO: yes pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

admin show conf

Displays the current policy server configuration information, such as the type of registry or whether global sign-on is enabled.

Requires authentication (administrator ID and password) to use this command.

Syntax

admin show conf

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example displays the current server configuration information:

pdadmin sec_master> admin show conf

LDAP: yes
secAuthority
GSO: yes

Parent topic: pdadmin commands

authzrule attachauthzrule attachauthzrule attachAttaches an authorization rule to the specified protected object. authorization commandsauthzrule attachRequires authentication (administrator ID and password) to use this command.Syntaxauthzrule attach protobjid ruleid DescriptionAt most, one rule can be attached to a given protected object. If the object already has a rule that is attached to it, the specified rule replaces the existing one. The same rule can be attached to multiple protected objects. Ensure that the protected object exists in the protected object space before you attach a rule. OptionsprotobjidSpecifies the fully qualified name of the protected object to which the authorization rule is attached. The object must exist, or an error is displayed.ruleidSpecifies the name of the authorization rule to attach. The rule must exist, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example attaches the r1 rule to the /Test-Space/folder1 protected object named: pdadmin sec_master> authzrule attach /Test-Space/folder1 r1See alsoauthzrule createCreates an authorization rule. authzrule detachDetaches an authorization rule from the specified protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule attach

Attaches an authorization rule to the specified protected object.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule attach protobjid ruleid

Description

At most, one rule can be attached to a given protected object. If the object already has a rule that is attached to it, the specified rule replaces the existing one. The same rule can be attached to multiple protected objects. Ensure that the protected object exists in the protected object space before you attach a rule.

Options

protobjid

Specifies the fully qualified name of the protected object to which the authorization rule is attached. The object must exist, or an error is displayed.

ruleid

Specifies the name of the authorization rule to attach. The rule must exist, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example attaches the r1 rule to the /Test-Space/folder1 protected object named:

pdadmin sec_master> authzrule attach /Test-Space/folder1 r1

See also

authzrule create

authzrule detach

Parent topic: pdadmin commands

authzrule createauthzrule createauthzrule createCreates an authorization rule. authorization commandsauthzrule createRequires authentication (administrator ID and password) to use this command.Syntaxauthzrule create rule_id rule_text [–desc description] [–failreason fail_reason] DescriptionYou can attach an authorization rule to a protected object. To authorize access to the protected object, the user credential and application context attributes are compared against the rule. Quotation marks within an authorization rule must be escaped by using the backward slash (\) character. Options –desc descriptionSpecifies the description of the authorization rule. (Optional)A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.Example of description: "time-of-day rule for engineering object space"–failreason fail_reasonSpecifies the message that is returned if the rule denies access to a protected object. Consider that the authorization is denied as a result of the evaluation of this rule. However, other authorization checks succeed. In this case, the reason code is returned to the application that makes the authorization check. (Optional)rule_idSpecifies the name of the authorization rule to create. A valid authorization rule is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. The following characters cannot be used in the name of an authorization rule: ! " # & ( ) * + , ; : < > = @ / \ | .rule_textSpecifies the rule policy that is used to evaluate the rule in XSL format. The rule must be enclosed in double quotation mark (") character. If the rule specifies a double quotation mark as part of the rule text, precede the double quotation mark with a backward slash (\) character. Doing so instructs the system to ignore the double quotation mark. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleWhen providing rule text with the pdadmin utility, enclose the rule text in double quotation marks ("). Double quotation marks embedded within the rule text must be escaped with a backward slash (\) so that they are ignored by the pdadmin utility. The XSL processor treats single and double quotation marks equally for defining text strings. They can be used interchangeably, but they must always be paired appropriately. For example: pdadmin sec_master> authzrule create testrule1 "<xsl:if test='some_piece_of_ADI =\"any string\"'>!TRUE!</xsl:if>"See alsoauthzrule deleteDeletes an authorization rule. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule create

Creates an authorization rule.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule create rule_id rule_text [–desc description] [–failreason fail_reason]

Description

You can attach an authorization rule to a protected object. To authorize access to the protected object, the user credential and application context attributes are compared against the rule.

Note: Quotation marks within an authorization rule must be escaped by using the backward slash (\) character.

Options

–desc description

Specifies the description of the authorization rule. (Optional)

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

Example of description: "time-of-day rule for engineering object space"

–failreason fail_reason

Specifies the message that is returned if the rule denies access to a protected object. Consider that the authorization is denied as a result of the evaluation of this rule. However, other authorization checks succeed. In this case, the reason code is returned to the application that makes the authorization check. (Optional)

rule_id

Specifies the name of the authorization rule to create.

A valid authorization rule is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. The following characters cannot be used in the name of an authorization rule:

! " # & ( ) * + , ; : < > = @ / \ | .

rule_text

Specifies the rule policy that is used to evaluate the rule in XSL format. The rule must be enclosed in double quotation mark (") character. If the rule specifies a double quotation mark as part of the rule text, precede the double quotation mark with a backward slash (\) character. Doing so instructs the system to ignore the double quotation mark.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

When providing rule text with the pdadmin utility, enclose the rule text in double quotation marks ("). Double quotation marks embedded within the rule text must be escaped with a backward slash (\) so that they are ignored by the pdadmin utility. The XSL processor treats single and double quotation marks equally for defining text strings. They can be used interchangeably, but they must always be paired appropriately. For example:

pdadmin sec_master> authzrule create testrule1
"<xsl:if test='some_piece_of_ADI =\"any string\"'>!TRUE!</xsl:if>"

See also

authzrule delete

Parent topic: pdadmin commands

authzrule deleteauthzrule deleteauthzrule deleteDeletes an authorization rule. authorization commandsauthzrule deleteRequires authentication (administrator ID and password) to use this command.Syntaxauthzrule delete rule_id Optionsrule_idSpecifies the name of the authorization rule to delete. The authorization rule must exist, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the eng-test rule: pdadmin sec_master> authzrule delete eng-testThe following example deletes the myRule rule: pdadmin sec_master> authzrule delete myRule See alsoauthzrule createCreates an authorization rule. authzrule detachDetaches an authorization rule from the specified protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule delete

Deletes an authorization rule.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule delete rule_id

Options

rule_id

Specifies the name of the authorization rule to delete. The authorization rule must exist, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the eng-test rule:

pdadmin sec_master> authzrule delete eng-test

The following example deletes the myRule rule:

pdadmin sec_master> authzrule delete myRule

See also

authzrule create

authzrule detach

Parent topic: pdadmin commands

authzrule detachauthzrule detachauthzrule detachDetaches an authorization rule from the specified protected object. authorization commandsauthzrule detachRequires authentication (administrator ID and password) to use this command.Syntaxauthzrule detach protobjid OptionsprotobjidSpecifies the name of the protected object from which the authorization rule is detached. The object must exist and have an authorization rule that is attached, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example detaches a rule from the /WebSEAL/tivoli.com/w3junction/index.html protected object: pdadmin sec_master> authzrule detach /WebSEAL/tivoli.com/w3junction/index.htmlSee alsoauthzrule attachAttaches an authorization rule to the specified protected object. authzrule deleteDeletes an authorization rule. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule detach

Detaches an authorization rule from the specified protected object.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule detach protobjid

Options

protobjid

Specifies the name of the protected object from which the authorization rule is detached. The object must exist and have an authorization rule that is attached, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example detaches a rule from the /WebSEAL/tivoli.com/w3junction/index.html protected object:

pdadmin sec_master> authzrule detach /WebSEAL/tivoli.com/w3junction/index.html

See also

authzrule attach

authzrule delete

Parent topic: pdadmin commands

authzrule findauthzrule findauthzrule findFinds and lists all protected objects that have the specified authorization rule attached. authorization commandsauthzrule findRequires authentication (administrator ID and password) to use this command.Syntaxauthzrule find rule_id DescriptionA user must have the browse (b) and view (v) permissions for the object to be listed when the pdadmin object show command is issued. Otherwise, an error is returned: The user is not authorized to view one or more protected objects where the requested authzrule is attached. Optionsrule_idSpecifies the name of the authorization rule to find. The authorization rule must exist, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example finds protected objects that are attached to the r2 rule: pdadmin sec_master> authzrule find r2 /Marketing/Folder1See alsoauthzrule listLists all the authorization rules. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule find

Finds and lists all protected objects that have the specified authorization rule attached.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule find rule_id

Description

A user must have the browse (b) and view (v) permissions for the object to be listed when the pdadmin object show command is issued. Otherwise, an error is returned:

The user is not authorized to view one or more protected objects where the
requested authzrule is attached.

Options

rule_id

Specifies the name of the authorization rule to find. The authorization rule must exist, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example finds protected objects that are attached to the r2 rule:

pdadmin sec_master> authzrule find r2

/Marketing/Folder1

See also

authzrule list

Parent topic: pdadmin commands

authzrule listauthzrule listauthzrule listLists all the authorization rules. authorization commandsauthzrule listRequires authentication (administrator ID and password) to use this command.Syntaxauthzrule list OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example lists authorization rules: pdadmin sec_master> authzrule list r1 r2 r3 r4See alsoauthzrule findFinds and lists all protected objects that have the specified authorization rule attached. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule list

Lists all the authorization rules.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule list

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example lists authorization rules:

pdadmin sec_master> authzrule list

r1
r2
r3
r4

See also

authzrule find

Parent topic: pdadmin commands

authzrule modifyauthzrule modifyauthorization commandsauthzrule modifyChanges an authorization rule. Requires authentication (administrator ID and password) to use this command.Syntaxauthzrule modify rule_id ruletext rule_textauthzrule modify rule_id description descriptionauthzrule modify rule_id failreason fail_reason Optionsdescription descriptionSpecifies the new description of the rule. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.Example of description: "time-of-day access"failreason fail_reasonSpecifies the fail reason code. Consider that authorization is denied as a result of the evaluation of this rule. However, other authorization checks succeed. In this case, the reason code is returned to the application that makes the authorization check. You can specify an empty string ("") to clear an existing fail reason.rule_idSpecifies the name of the authorization rule to change. The authorization rule must exist, or an error is displayed.ruletext rule_textSpecifies the new rule text in XSL format. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example changes the description of a rule named r2: pdadmin sec_master> authzrule modify r2 description "time-of-day access"See alsoauthzrule attachAttaches an authorization rule to the specified protected object. authzrule createCreates an authorization rule. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule modify

Changes an authorization rule.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule modify rule_id ruletext rule_text

authzrule modify rule_id description description

authzrule modify rule_id failreason fail_reason

Options

description description

Specifies the new description of the rule.

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

Example of description: "time-of-day access"

failreason fail_reason

Specifies the fail reason code. Consider that authorization is denied as a result of the evaluation of this rule. However, other authorization checks succeed. In this case, the reason code is returned to the application that makes the authorization check. You can specify an empty string ("") to clear an existing fail reason.

rule_id

Specifies the name of the authorization rule to change. The authorization rule must exist, or an error is displayed.

ruletext rule_text

Specifies the new rule text in XSL format.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example changes the description of a rule named r2:

pdadmin sec_master> authzrule modify r2 description "time-of-day access"

See also

authzrule attach

authzrule create

Parent topic: pdadmin commands

authzrule showauthzrule showauthzrule showShows all the attributes of an authorization rule, including description, rule text, and fail reason code. authorization commandsauthzrule showRequires authentication (administrator ID and password) to use this command.Syntaxauthzrule show rule_id Optionsrule_idSpecifies the name of the authorization rule to show. The rule must exist, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example shows attributes for a rule named r2: pdadmin sec_master> authzrule show r2The output is like: Authorization Rule Name: r2 Description: time-of-day access Rule Text: <xsl:if test="/XMLADI/session[contains(status,'login')]"> <xsl:for-each select="/XMLADI/userid/level"> <xsl:if test=". = 'administrator'"> <xsl:choose> <xsl:when test="../paid = 'in-full'"> !TRUE! </xsl:when> <xsl:when test="../paid = 'partial'"> !FALSE! </xsl:when> <xsl:when test="../paid = 'introductory'"> !TRUE! </xsl:when> <xsl:otherwise> !FALSE! </xsl:otherwise> </xsl:choose> </xsl:if> </xsl:for-each> </xsl:if> Fail Reason:Error when creating R2See alsoauthzrule findFinds and lists all protected objects that have the specified authorization rule attached. authzrule listLists all the authorization rules. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

authzrule show

Shows all the attributes of an authorization rule, including description, rule text, and fail reason code.

Requires authentication (administrator ID and password) to use this command.

Syntax

authzrule show rule_id

Options

rule_id

Specifies the name of the authorization rule to show. The rule must exist, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example shows attributes for a rule named r2:

pdadmin sec_master> authzrule show r2

The output is like:

Authorization Rule Name: r2
Description: time-of-day access
Rule Text: <xsl:if test="/XMLADI/session[contains(status,'login')]">
<xsl:for-each select="/XMLADI/userid/level">
<xsl:if test=". = 'administrator'">
<xsl:choose>
<xsl:when test="../paid = 'in-full'">
!TRUE!
</xsl:when>
<xsl:when test="../paid = 'partial'">
!FALSE!
</xsl:when>
<xsl:when test="../paid = 'introductory'">
!TRUE!
</xsl:when>
<xsl:otherwise>
!FALSE!
</xsl:otherwise>
</xsl:choose>
</xsl:if>
</xsl:for-each>
</xsl:if>
Fail Reason:Error when creating R2

See also

authzrule find

authzrule list

Parent topic: pdadmin commands

context showcontext showcontext showDisplays the user ID and domain ID used to establish the current authentication context. Also, specifies whether the domain is the management domain or a domain other than the management domain.context commands, showThis command does not require a login or authentication to use.Syntaxcontext show OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example shows that no login and no authentication are being performed: c:\> pdadmin context show The output is like: No login information The following example shows local authentication before the context show command is issued: c:\> pdadmin -l pdadmin local> context show The output is like: The user is logged in to the local systemThe following example shows local authentication, like the previous example, except the command in issued interactively: pdadmin sec_master> login -l pdadmin local> context show The output is like: The user is logged in to the local systemThe following example shows authentication context information for a user who is logged in to the management domain (non-local authentication). c:\> pdadmin -a sec_master -p mypwd -m pdadmin sec_master> context show The output is like: User: sec_master Domain: Default The user is logged into the management domainThe following example shows authentication context information for the testdomain_admin administrator who logs in interactively to a domain (testdomain) other than the management domain: pdadmin> login -a testdomain_admin -p testpwd -d testdomain pdadmin testdomain_admin@testdomain_admin> context showThe output is like:User: testdomain_admin Domain: testdomain The user is not logged in to the management domain See alsodomain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. user showDisplays the properties of the specified user. loginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. logoutDiscards any authentication credentials that are in effect. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

context show

Displays the user ID and domain ID used to establish the current authentication context. Also, specifies whether the domain is the management domain or a domain other than the management domain.

This command does not require a login or authentication to use.

Syntax

context show

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example shows that no login and no authentication are being performed:

c:\> pdadmin

context show

The output is like:

No login information

The following example shows local authentication before the context show command is issued:

c:\> pdadmin -l
pdadmin local> context show

The output is like:

The user is logged in to the local system

The following example shows local authentication, like the previous example, except the command in issued interactively:

pdadmin sec_master> login -l

pdadmin local> context show

The output is like:

The user is logged in to the local system

The following example shows authentication context information for a user who is logged in to the management domain (non-local authentication).

c:\> pdadmin -a sec_master -p mypwd -m

pdadmin sec_master> context show

The output is like:

User: sec_master
Domain: Default
The user is logged into the management domain

The following example shows authentication context information for the testdomain_admin administrator who logs in interactively to a domain (testdomain) other than the management domain:

pdadmin> login -a testdomain_admin -p testpwd -d testdomain

pdadmin testdomain_admin@testdomain_admin> context show

The output is like:

User: testdomain_admin
Domain: testdomain
The user is not logged in to the management domain

See also

domain show

user show

login

logout

Parent topic: pdadmin commands

domain createdomain createdomain createCreates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command. domain commandscreateRequires authentication (administrator ID and password) to use this command.This command applies to LDAP registries only.Syntaxdomain create domain domain_admin_id domain_admin_password [–desc description] DescriptionAn initial domain is created when the policy server is configured. This domain, called the management domain, is the default domain in which Security Access Manager enforces security policies for authentication, authorization, and access control. You must log in to the management domain to create more policy domains.When you create a domain, you must specify an administrative ID and password for the domain. The administrator of the management domain later assigns the new ID and password. The new credentials are assigned to the administrator responsible for handling policy management tasks for the specific domain. The administrator of the domain is responsible for updating the security policy for that particular domain if: Users change.Groups change.Resources change.This domain administrator can also delegate administration tasks to others within that specific domain. For more information about managing domains, see the Administering topics in the IBM Knowledge Center. Options–desc descriptionSpecifies an optional description for the domain. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description. Examples of description: "accounting area". (Optional)domainSpecifies the name of the domain to be created. Characteristics of the name are: Limited to 64 characters in length.Case sensitive. Can contain a-z, A–Z, 0–9, hyphen (-), underscore (_), period (.), at sign (@), or ampersand(&).Can contain any character from a double-byte character set. The underlying user registry might also restrict certain characters. Some registries are not case-sensitive.domain_admin_idSpecifies an administrator ID, which is created in the specified domain.domain_admin_passwordSpecifies the password for the domain_admin_id user. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates a domain named Marketing, a domain administrator ID Admin1, and an initial password to log in to the domain: pdadmin sec_master> domain create Marketing Admin1 passwordThe following example creates a domain named Finance, a domain administrator ID Admin2, a password, and a domain description: pdadmin sec_master> domain create Finance Admin2 password -desc "accounting area" See alsodomain deleteDeletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator. domain listLists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command. domain modifyChanges the description of a domain. You must log in to the management domain as an administrator to perform this command. domain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

domain create

Creates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command.

Requires authentication (administrator ID and password) to use this command.

This command applies to LDAP registries only.

Syntax

domain create domain domain_admin_id domain_admin_password [–desc description]

Description

An initial domain is created when the policy server is configured. This domain, called the management domain, is the default domain in which Security Access Manager enforces security policies for authentication, authorization, and access control. You must log in to the management domain to create more policy domains.

When you create a domain, you must specify an administrative ID and password for the domain. The administrator of the management domain later assigns the new ID and password. The new credentials are assigned to the administrator responsible for handling policy management tasks for the specific domain. The administrator of the domain is responsible for updating the security policy for that particular domain if:

Users change.

Groups change.

Resources change.

This domain administrator can also delegate administration tasks to others within that specific domain. For more information about managing domains, see the Administering topics in the IBM Knowledge Center.

Options

–desc description

Specifies an optional description for the domain. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description. Examples of description: "accounting area". (Optional)

domain

Specifies the name of the domain to be created. Characteristics of the name are:

Limited to 64 characters in length.

Case sensitive.

Can contain a-z, A–Z, 0–9, hyphen (-), underscore (_), period (.), at sign (@), or ampersand(&).

Can contain any character from a double-byte character set.

The underlying user registry might also restrict certain characters. Some registries are not case-sensitive.

domain_admin_id

Specifies an administrator ID, which is created in the specified domain.

domain_admin_password

Specifies the password for the domain_admin_id user.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates a domain named Marketing, a domain administrator ID Admin1, and an initial password to log in to the domain:

pdadmin sec_master> domain create Marketing Admin1 password

The following example creates a domain named Finance, a domain administrator ID Admin2, a password, and a domain description:

pdadmin sec_master> domain create Finance Admin2 password
-desc "accounting area"

See also

domain delete

domain list

domain modify

domain show

Parent topic: pdadmin commands

domain deletedomain deletedomain deleteDeletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator. domain commandsdeleteRequires authentication (administrator ID and password) to use this command.This command applies to LDAP registries only.Syntaxdomain delete domain [–registry] DescriptionA domain can be deleted within the management domain only by an administrator with the appropriate privileges. Options–registrySpecifies that the information of the domain, including user and group data, be deleted from the user registry. (Optional) If this option is not selected, user and group data for the specified domain: Remains in the registry.Can be used again if the domain is re-created.domainSpecifies the name of the domain to be deleted. The domain must exist, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes a domain named Marketing: pdadmin sec_master> domain delete Marketing The following example deletes a domain named Finance and removes any user and group information in the user registry: pdadmin sec_master> domain delete Finance -registry See alsodomain createCreates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command. domain listLists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command. domain modifyChanges the description of a domain. You must log in to the management domain as an administrator to perform this command. domain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

domain delete

Deletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator.

Requires authentication (administrator ID and password) to use this command.

This command applies to LDAP registries only.

Syntax

domain delete domain [–registry]

Description

A domain can be deleted within the management domain only by an administrator with the appropriate privileges.

Options

–registry

Specifies that the information of the domain, including user and group data, be deleted from the user registry. (Optional) If this option is not selected, user and group data for the specified domain:

Remains in the registry.

Can be used again if the domain is re-created.

domain

Specifies the name of the domain to be deleted. The domain must exist, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes a domain named Marketing:

pdadmin sec_master> domain delete Marketing

The following example deletes a domain named Finance and removes any user and group information in the user registry:

pdadmin sec_master> domain delete Finance -registry

See also

domain create

domain list

domain modify

domain show

Parent topic: pdadmin commands

domain listdomain listdomain listLists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command. domain commandslistRequires authentication (administrator ID and password) to use this command.This command applies to LDAP registries only.Syntaxdomain list OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example lists existing domains other than the management domain (Default): pdadmin sec_master> domain list The output is like: Marketing Finance Advertising Receiving See alsodomain createCreates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command. domain deleteDeletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator. domain modifyChanges the description of a domain. You must log in to the management domain as an administrator to perform this command. domain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

domain list

Lists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command.

Requires authentication (administrator ID and password) to use this command.

This command applies to LDAP registries only.

Syntax

domain list

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example lists existing domains other than the management domain (Default):

pdadmin sec_master> domain list

The output is like:

Marketing
Finance
Advertising
Receiving

See also

domain create

domain delete

domain modify

domain show

Parent topic: pdadmin commands

domain modifydomain modifydomain modifyChanges the description of a domain. You must log in to the management domain as an administrator to perform this command. domain commandsmodifyRequires authentication (administrator ID and password) to use this command.This command applies to LDAP registries only.Syntaxdomain modify domain description description Optionsdescription descriptionSpecifies a new description for the domain. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.Example of description: "marketing and advertising areas"domainSpecifies the name of the domain to modify. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example changes the description that is specified for the Marketing domain: pdadmin sec_master> domain modify Marketing description "marketing and advertising areas" See alsodomain createCreates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command. domain deleteDeletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator. domain listLists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command. domain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

domain modify

Changes the description of a domain. You must log in to the management domain as an administrator to perform this command.

Requires authentication (administrator ID and password) to use this command.

This command applies to LDAP registries only.

Syntax

domain modify domain description description

Options

description description

Specifies a new description for the domain.

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

Example of description: "marketing and advertising areas"

domain

Specifies the name of the domain to modify.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example changes the description that is specified for the Marketing domain:

pdadmin sec_master> domain modify Marketing description "marketing and
advertising areas"

See also

domain create

domain delete

domain list

domain show

Parent topic: pdadmin commands

domain showdomain showdomain showDisplays the properties of a domain. You must log in to the management domain as an administrator to perform this command. domain commandsshowRequires authentication (administrator ID and password) to use this command.This command applies to LDAP registries only.Syntaxdomain show domain OptionsdomainSpecifies the name of the domain for which to display properties. The domain must exist, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example displays properties for the Marketing domain: pdadmin sec_master> domain show Marketing The output is like: Domain Name: Marketing Description: marketing and advertising areas See alsodomain createCreates a domain, including an administrator ID and password to log in to the specified domain. You must log in to the management domain as an administrator to perform this command. domain deleteDeletes a domain, excluding the management domain. Optionally deletes the user and group information of the domain, from the user registry. To perform this command, you must log in to the management domain as an administrator. domain listLists all domains, excluding the management domain. You must log in to the management domain as an administrator to perform this command. domain modifyChanges the description of a domain. You must log in to the management domain as an administrator to perform this command. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

domain show

Displays the properties of a domain. You must log in to the management domain as an administrator to perform this command.

Requires authentication (administrator ID and password) to use this command.

This command applies to LDAP registries only.

Syntax

domain show domain

Options

domain

Specifies the name of the domain for which to display properties. The domain must exist, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example displays properties for the Marketing domain:

pdadmin sec_master> domain show Marketing

The output is like:

Domain Name: Marketing
Description: marketing and advertising areas

See also

domain create

domain delete

domain list

domain modify

Parent topic: pdadmin commands

errtexterrtexterrtextDisplays the error message of a specific error number. errtext commanderror messages For detailed information about messages, see "Error messages" in the IBM Knowledge Center.This command does not require a login or authentication to use.Syntaxerrtext error_numberDescriptionThe message ID is also displayed (for example, HPDMS4047E) The message ID consists of 10 alphanumeric characters that uniquely identify the message. The message ID is composed of the following pieces: A three-character product identifier (for example, HPD indicates that this message is for Security Access Manager base or Web Portal Manager)A two-character component or subsystem identifierA four-digit message numberA one-character type code indicates the severity of the message (I for informational, W for warning, and E for error) Optionserror_numberSpecifies the number, in either decimal or hexadecimal, of the error for which to generate the error text. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays the error message that is associated with a specific hexadecimal number: pdadmin sec_master> errtext 0x14c52fcfThe output is like: HPDMS4047E:Non-local authentication (login) is required to perform this operation (status 0x14c52fcf)The following example displays the error message that is associated with a specific decimal number: pdadmin> errtext 268808652The output is like: HPDAC0460E The protected object space specified already exists in the authorization policy database (status 0x1005b1cc) pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

errtext

Displays the error message of a specific error number.

For detailed information about messages, see "Error messages" in the IBM Knowledge Center.

This command does not require a login or authentication to use.

Syntax

errtext error_number

Description

The message ID is also displayed (for example, HPDMS4047E) The message ID consists of 10 alphanumeric characters that uniquely identify the message. The message ID is composed of the following pieces:

A three-character product identifier (for example, HPD indicates that this message is for Security Access Manager base or Web Portal Manager)

A two-character component or subsystem identifier

A four-digit message number

A one-character type code indicates the severity of the message (I for informational, W for warning, and E for error)

Options

error_number

Specifies the number, in either decimal or hexadecimal, of the error for which to generate the error text.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays the error message that is associated with a specific hexadecimal number:

pdadmin sec_master> errtext 0x14c52fcf

The output is like:

HPDMS4047E:Non-local authentication (login) is required to perform
this operation (status 0x14c52fcf)

The following example displays the error message that is associated with a specific decimal number:

pdadmin> errtext 268808652

The output is like:

HPDAC0460E The protected object space specified already exists in the
authorization policy database (status 0x1005b1cc)

Parent topic: pdadmin commands

exit or quitexit or quitexit or quitExits from the pdadmin utility interactive command-line mode.pdadmin utilitiesexit command line modepdadmin utilitiesquit command line mode This command does not require a login or authentication to use.Syntaxexitquit OptionsNone. ExamplesThe following example displays how to exit the pdadmin utility: pdadmin> exitThe following example displays how to quit the pdadmin utility: pdadmin> quit See alsologinEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. logoutDiscards any authentication credentials that are in effect. context showDisplays the user ID and domain ID used to establish the current authentication context. Also, specifies whether the domain is the management domain or a domain other than the management domain. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

exit or quit

Exits from the pdadmin utility interactive command-line mode.

This command does not require a login or authentication to use.

Syntax

exit

quit

Options

None.

Examples

The following example displays how to exit the pdadmin utility:

pdadmin> exit

The following example displays how to quit the pdadmin utility:

pdadmin> quit

See also

login

logout

context show

Parent topic: pdadmin commands

group creategroup creategroup createCreates a Security Access Manager group. group commandsgroup createRequires authentication of administrator ID and password to use this command.Groups that are created in the Active Directory Lightweight Directory Service (AD LDS) user registry must be created in the same AD LDS partition where the Access Manager Management Domain information is stored.Syntaxgroup create group_name dn cn [group_container]OptionscnSpecifies the common name that is assigned to the group that is being created. For example, cwright.dnSpecifies the registry identifier that is assigned to the group that is being created. The format for a distinguished name is like: cn=credit,ou=Austin,o=Tivoli,c=USgroup_containerSpecifies the group container object that is assigned to the group that is being created. If this option is not specified, the group by default is placed in the object space under /Management/Groups. (Optional)Examples of group containers are Credit and Sales_Teams.group_nameSpecifies the name of the group that is being created. This name must be unique within the domain. A valid group name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.Examples of group names are Credit, Sales, and Test-group. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates a group named credit1 with a common name of credit01 within the Credit group container object: pdadmin sec_master> group create credit1 "cn=credit01,o=Tivoli,c=US" credit01 CreditThe following example creates a group named salesteam with a common name of sales within the Sales_Teams group container: pdadmin sec_master> group create salesteam "cn=sales,o=tivoli,c=us" sales Sales_Teams See alsogroup deleteDeletes the specified Security Access Manager group. Optionally deletes the information of the group, from the user registry. ACL entries that are associated with the group are also deleted. group importCreates a Security Access Manager group by importing group data that exists in the user registry. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

group create

Creates a Security Access Manager group.

Requires authentication of administrator ID and password to use this command.

Groups that are created in the Active Directory Lightweight Directory Service (AD LDS) user registry must be created in the same AD LDS partition where the Access Manager Management Domain information is stored.

Syntax

group create group_name dn cn [group_container]

Options

cn

Specifies the common name that is assigned to the group that is being created. For example, cwright.

dn

Specifies the registry identifier that is assigned to the group that is being created.

The format for a distinguished name is like:

cn=credit,ou=Austin,o=Tivoli,c=US

group_container

Specifies the group container object that is assigned to the group that is being created. If this option is not specified, the group by default is placed in the object space under /Management/Groups. (Optional)

Examples of group containers are Credit and Sales_Teams.

group_name

Specifies the name of the group that is being created. This name must be unique within the domain.

A valid group name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

Examples of group names are Credit, Sales, and Test-group.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates a group named credit1 with a common name of credit01 within the Credit group container object:

pdadmin sec_master> group create credit1 "cn=credit01,o=Tivoli,c=US"
credit01 Credit

The following example creates a group named salesteam with a common name of sales within the Sales_Teams group container:

pdadmin sec_master> group create salesteam "cn=sales,o=tivoli,c=us"
sales Sales_Teams

See also

group delete

group import

Parent topic: pdadmin commands

group deletegroup deletegroup deleteDeletes the specified Security Access Manager group. Optionally deletes the information of the group, from the user registry. ACL entries that are associated with the group are also deleted. group commandsgroup deleteRequires authentication (administrator ID and password) to use this command.Syntaxgroup delete [–registry] group_name Options–registryDeletes the entire group object from the user registry. (Optional)group_nameSpecifies the name of the Security Access Manager group to be deleted. The group must exist, or an error is displayed. Examples of group names are Credit, Sales, and Test-group. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the existing engineering group: pdadmin sec_master> group delete engineeringThe following example deletes the group object from the user registry and also deletes the existing Test-group group: pdadmin sec_master> group delete -registry Test-group See alsogroup createCreates a Security Access Manager group. group importCreates a Security Access Manager group by importing group data that exists in the user registry. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

group delete

Deletes the specified Security Access Manager group. Optionally deletes the information of the group, from the user registry. ACL entries that are associated with the group are also deleted.

Requires authentication (administrator ID and password) to use this command.

Syntax

group delete [–registry] group_name

Options

–registry

Deletes the entire group object from the user registry. (Optional)

group_name

Specifies the name of the Security Access Manager group to be deleted. The group must exist, or an error is displayed.

Examples of group names are Credit, Sales, and Test-group.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the existing engineering group:

pdadmin sec_master> group delete engineering

The following example deletes the group object from the user registry and also deletes the existing Test-group group:

pdadmin sec_master> group delete -registry Test-group

See also

group create

group import

Parent topic: pdadmin commands

group importgroup importgroup importCreates a Security Access Manager group by importing group data that exists in the user registry. group commandsgroup importimportgroupYou can import an Active Directory dynamic group under this condition:The name of the Security Access Manager group (excluding the @domain suffix) is the same as the common name (CN) of the Active Directory dynamic group.If Active Directory Lightweight Directory Service (AD LDS) is the user registry, import groups from the AD LDS partition where the Security Access Manager management domain information is stored.Requires authentication (administrator ID and password) to use this command.Syntaxgroup import group_name dn [group_container] OptionsdnSpecifies the registry identifier of the group to import. The distinguished name must exist, or an error is displayed. The format for a distinguished name is like "cn=engineering,ou=Austin,o=Tivoli,c=us"group_containerSpecifies the group container object that is assigned to the group that is being created. By default, the group is placed in the object space under /Management/Groups. If the container object does not currently exist, it is automatically created. (Optional)group_nameSpecifies the name of the group to create. A valid group name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. Examples of group names are Credit, Sales, and Test-group. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates a Security Access Manager group by importing a group that exists in the user registry: pdadmin sec_master> group import engineering "cn=engineering,o=Tivoli,c=US"This example:Creates a Security Access Manager group named sales. Places the sales group in the Sales2003 group container object by importing a group that exists in the user registry.pdadmin sec_master> group import sales "cn=sales,o=tivoli,c=us" Sales2003This example creates a group named dyngroup1 by importing the group from an Active Directory dynamic group with the following characteristics: cndyngroup1distinguishedName cn=dyngroup1, cn=AzGroupObjectContainer-myAuthorizationStore, cn=myAuthorizationStore, cn=ProgramData, dc=domain, dc=compdadmin sec_master> group import dyngroup1 "cn=dyngroup1, cn=AzGroupObjectContainer-myAuthorizationStore, cn=myAuthorizationStore,cn=ProgramData, dc=domain,dc=com"If Security Access Manager is configured in an environment that uses multiple Active Directory domains, enter the following command to create the same group: pdadmin sec_master> group import dyngroup1@domain.com "cn=dyngroup1, cn=AzGroupObjectContainer-myAuthorizationStore, cn=myAuthorizationStore,cn=ProgramData, dc=domain,dc=com" See alsogroup createCreates a Security Access Manager group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

group import

Creates a Security Access Manager group by importing group data that exists in the user registry.

You can import an Active Directory dynamic group under this condition:

The name of the Security Access Manager group (excluding the @domain suffix) is the same as the common name (CN) of the Active Directory dynamic group.

If Active Directory Lightweight Directory Service (AD LDS) is the user registry, import groups from the AD LDS partition where the Security Access Manager management domain information is stored.

Requires authentication (administrator ID and password) to use this command.

Syntax

group import group_name dn [group_container]

Options

dn

Specifies the registry identifier of the group to import. The distinguished name must exist, or an error is displayed. The format for a distinguished name is like "cn=engineering,ou=Austin,o=Tivoli,c=us"

group_container

Specifies the group container object that is assigned to the group that is being created. By default, the group is placed in the object space under /Management/Groups. If the container object does not currently exist, it is automatically created. (Optional)

group_name

Specifies the name of the group to create. A valid group name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. Examples of group names are Credit, Sales, and Test-group.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates a Security Access Manager group by importing a group that exists in the user registry:

pdadmin sec_master> group import engineering "cn=engineering,o=Tivoli,c=US"

This example:

Creates a Security Access Manager group named sales.

Places the sales group in the Sales2003 group container object by importing a group that exists in the user registry.

pdadmin sec_master> group import sales "cn=sales,o=tivoli,c=us" Sales2003

This example creates a group named dyngroup1 by importing the group from an Active Directory dynamic group with the following characteristics:

cn

dyngroup1

distinguishedName

cn=dyngroup1,

cn=AzGroupObjectContainer-myAuthorizationStore,

cn=myAuthorizationStore,

cn=ProgramData,

dc=domain,

dc=com

pdadmin sec_master> group import dyngroup1 "cn=dyngroup1,
cn=AzGroupObjectContainer-myAuthorizationStore,
cn=myAuthorizationStore,cn=ProgramData,
dc=domain,dc=com"

If Security Access Manager is configured in an environment that uses multiple Active Directory domains, enter the following command to create the same group:

pdadmin sec_master> group import dyngroup1@domain.com "cn=dyngroup1,
cn=AzGroupObjectContainer-myAuthorizationStore,
cn=myAuthorizationStore,cn=ProgramData,
dc=domain,dc=com"

See also

group create

Parent topic: pdadmin commands

group listgroup listgroup listGenerates a list of all groups, by group names, whose names match the specified pattern. group commandsgroup listRequires authentication (administrator ID and password) to use this command.Syntaxgroup list pattern max_returngroup list-dn pattern max_return Optionslist pattern max_returnSpecifies the pattern for the group name for which to be searched. The pattern can include a mixture of wildcard and string constants, and is not case-sensitive (for example, *austin*). The max_return option specifies the limit of how many entries must be returned for a single request; for example, 2. The number that is returned is also governed by the server configuration. The configuration specifies the maximum number of results that can be returned as part of a search operation. The actual maximum returned entries is the minimum of max_return and the configured value on the server.list-dn pattern max_returnLists user registry identifiers whose user registry common name attribute matches the pattern specified. The returned list contains groups, which are defined in the user registry. The groups might not necessarily be Security Access Manager groups. You can import groups that are not Security Access Manager groups into Security Access Manager by using the group import command. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example lists 3 groups that match the specified pattern of a group name that contains the letter a: pdadmin sec_master> group list *a* 3 The output is like: Sales Marketing AlexThe following example lists 2 groups that match the specified pattern of a distinguished name that contains the letter t: pdadmin sec_master> group list-dn *t* 2 The output is like: cn=credit,ou=Austin,o=Tivoli,c=US Sales cn=marketing,ou=Boston,o=Austin Sale,c=US Marketing See alsogroup showShows the properties of the specified group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

group list

Generates a list of all groups, by group names, whose names match the specified pattern.

Requires authentication (administrator ID and password) to use this command.

Syntax

group list pattern max_return

group list-dn pattern max_return

Options

list pattern max_return

Specifies the pattern for the group name for which to be searched. The pattern can include a mixture of wildcard and string constants, and is not case-sensitive (for example, *austin*).

The max_return option specifies the limit of how many entries must be returned for a single request; for example, 2. The number that is returned is also governed by the server configuration. The configuration specifies the maximum number of results that can be returned as part of a search operation. The actual maximum returned entries is the minimum of max_return and the configured value on the server.

list-dn pattern max_return

Lists user registry identifiers whose user registry common name attribute matches the pattern specified. The returned list contains groups, which are defined in the user registry. The groups might not necessarily be Security Access Manager groups. You can import groups that are not Security Access Manager groups into Security Access Manager by using the group import command.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists 3 groups that match the specified pattern of a group name that contains the letter a:

pdadmin sec_master> group list *a* 3

The output is like:

Sales
Marketing
Alex

The following example lists 2 groups that match the specified pattern of a distinguished name that contains the letter t:

pdadmin sec_master> group list-dn *t* 2

The output is like:

cn=credit,ou=Austin,o=Tivoli,c=US Sales
cn=marketing,ou=Boston,o=Austin Sale,c=US Marketing

See also

group show

Parent topic: pdadmin commands

group modifygroup modifygroup modifyChanges an existing group by adding or changing a group description, adding members to the group, or removing members from the group. group commandsgroup modifyRequires authentication (administrator ID and password) to use this command.Syntaxgroup modify group_name add usergroup modify group_name add (user_1 user_2 [... user_n])group modify group_name description descriptiongroup modify group_name remove usergroup modify group_name remove (user_1 user_2 [... user_n]) Optionsadd user or add (user_1 user_2 [... user_n])Adds a user or a list of users to the group. For a single user, do not include the user name in parentheses. For multiple users, the format of the user list is a parenthesized list of user names, which are separated by spaces. The following list shows examples of user names: dlucas"Bob Smith"(dlucas "Mary Jones" mlucaser)description descriptionChanges the description for the specified group. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description. For example, you can specify "Credit, Dept HCUS" as the description.group_nameSpecifies the name of the group. The group must exist, or an error is displayed. Examples of group names are Credit, Sales, and Test-group.remove user or remove (user_1 user_2 [... user_n])Removes a user or a list of users from the group. For a single user, do not include the user name in parentheses. For multiple users, the format of the user list is a parenthesized list of user names, which are separated by spaces. The following list shows examples of user names: dlucas"Bob Smith"(dlucas "Mary Jones" mlucaser) Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example adds a user dlucas to the engineering group: pdadmin sec_master> group modify engineering add dlucasThe following example adds three new users to the engineering group: pdadmin sec_master> group modify engineering add ("Mary Jones" dsmith mlucaser)The following example deletes three existing users from the engineering group: pdadmin sec_master> group modify engineering remove ("Mary Jones" dlucas mlucaser)The following example changes the description of the credit group: pdadmin sec_master> group modify credit description "Credit, Dept HCUS" See alsogroup createCreates a Security Access Manager group. group importCreates a Security Access Manager group by importing group data that exists in the user registry. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

group modify

Changes an existing group by adding or changing a group description, adding members to the group, or removing members from the group.

Requires authentication (administrator ID and password) to use this command.

Syntax

group modify group_name add user

group modify group_name add (user_1 user_2 [... user_n])

group modify group_name description description

group modify group_name remove user

group modify group_name remove (user_1 user_2 [... user_n])

Options

add user or add (user_1 user_2 [... user_n])

Adds a user or a list of users to the group. For a single user, do not include the user name in parentheses. For multiple users, the format of the user list is a parenthesized list of user names, which are separated by spaces.

The following list shows examples of user names:

dlucas

"Bob Smith"

(dlucas "Mary Jones" mlucaser)

description description

Changes the description for the specified group. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description. For example, you can specify "Credit, Dept HCUS" as the description.

group_name

Specifies the name of the group. The group must exist, or an error is displayed.

Examples of group names are Credit, Sales, and Test-group.

remove user or remove (user_1 user_2 [... user_n])

Removes a user or a list of users from the group. For a single user, do not include the user name in parentheses. For multiple users, the format of the user list is a parenthesized list of user names, which are separated by spaces. The following list shows examples of user names:

dlucas

"Bob Smith"

(dlucas "Mary Jones" mlucaser)

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example adds a user dlucas to the engineering group:

pdadmin sec_master> group modify engineering add dlucas

The following example adds three new users to the engineering group:

pdadmin sec_master> group modify engineering add ("Mary Jones" dsmith mlucaser)

The following example deletes three existing users from the engineering group:

pdadmin sec_master> group modify engineering remove ("Mary Jones"
dlucas mlucaser)

The following example changes the description of the credit group:

pdadmin sec_master> group modify credit description "Credit, Dept HCUS"

See also

group create

group import

Parent topic: pdadmin commands

group showgroup showgroup showShows the properties of the specified group. group commandsgroup showRequires authentication (administrator ID and password) to use this command.Syntaxgroup show group_namegroup show-dn dngroup show-members group_name Optionsshow group_nameShows the properties of the group that is specified by group_name. The group must exist, or an error is displayed. Examples of group names are Credit, Sales, and Test-group.show-dn dnShows the group that is specified by the group identifier in the user registry. The returned group is defined in the user registry, but it is not necessarily a Security Access Manager group. Groups that are not Security Access Manager groups can be imported into Security Access Manager by use of the group import command. For example, the format for a distinguished name is like "cn=engineering,ou=Austin,o=Tivoli,c=us".show-members group_nameLists the user names of the members of the specified group. The group must exist, or an error is displayed. Examples of group names are Credit, Sales, and Test-group. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays properties of the credit group: pdadmin sec_master> group show creditThe output is like: Group ID: credit LDAP dn: cn=credit,ou=Austin,o=Tivoli,c=US Description: Credit, Dept HCUS LDAP cn: credit Is SecGroup: yesThe following example displays properties that are specified by the identifier of the group, cn=credit,ou=Austin,o=Tivoli,c=US in the user registry: pdadmin sec_master> group show-dn cn=credit,ou=Austin,o=Tivoli,c=USThe output is like: Group ID: credit LDAP dn: cn=credit,ou=Austin,o=Tivoli,c=US Description: Credit, Dept HCUS LDAP cn: credit Is SecGroup: yesThe following example lists the user names of the members of the credit group: pdadmin sec_master> group show-members creditThe output is like: dlucas mlucaser See alsogroup listGenerates a list of all groups, by group names, whose names match the specified pattern. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

group show

Shows the properties of the specified group.

Requires authentication (administrator ID and password) to use this command.

Syntax

group show group_name

group show-dn dn

group show-members group_name

Options

show group_name

Shows the properties of the group that is specified by group_name. The group must exist, or an error is displayed.

Examples of group names are Credit, Sales, and Test-group.

show-dn dn

Shows the group that is specified by the group identifier in the user registry. The returned group is defined in the user registry, but it is not necessarily a Security Access Manager group. Groups that are not Security Access Manager groups can be imported into Security Access Manager by use of the group import command. For example, the format for a distinguished name is like "cn=engineering,ou=Austin,o=Tivoli,c=us".

show-members group_name

Lists the user names of the members of the specified group. The group must exist, or an error is displayed.

Examples of group names are Credit, Sales, and Test-group.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays properties of the credit group:

pdadmin sec_master> group show credit

The output is like:

Group ID: credit
LDAP dn: cn=credit,ou=Austin,o=Tivoli,c=US
Description: Credit, Dept HCUS
LDAP cn: credit
Is SecGroup: yes

The following example displays properties that are specified by the identifier of the group, cn=credit,ou=Austin,o=Tivoli,c=US in the user registry:

pdadmin sec_master> group show-dn cn=credit,ou=Austin,o=Tivoli,c=US

The output is like:

Group ID: credit
LDAP dn: cn=credit,ou=Austin,o=Tivoli,c=US
Description: Credit, Dept HCUS
LDAP cn: credit
Is SecGroup: yes

The following example lists the user names of the members of the credit group:

pdadmin sec_master> group show-members credit

The output is like:

dlucas
mlucaser

See also

group list

Parent topic: pdadmin commands

helphelphelpObtains system help for pdadmin commands and options. pdadminhelpThis command does not require a login or authentication to use.Syntaxhelp {topic | command} OptionscommandSpecifies the miscellaneous command for which help is needed.topicSpecifies the help command topic for which help is needed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example lists help topics and commands: pdadmin> help The output is like: Type 'help <topic>' or 'help <command> for more information Topics: acl action admin authzrule config context domain errtext exit group help login logout object objectspace policy pop quit rsrc rsrccred rsrcgroup server user Miscellaneous Commands: exit help quitThe following example lists the options and descriptions that are available whether you specify the topic action or action create: pdadmin> help action Or: pdadmin> help action create The output is like: action create <action-name> <action-label> <action-type> Creates a new ACL action definition action create <action-name> <action-label> <action-type> <action-group-name> Creates a new ACL action definition in a group ... pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

help

Obtains system help for pdadmin commands and options.

This command does not require a login or authentication to use.

Syntax

help {topic | command}

Options

command

Specifies the miscellaneous command for which help is needed.

topic

Specifies the help command topic for which help is needed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists help topics and commands:

pdadmin> help

The output is like:

Type 'help <topic>' or 'help <command> for more information

Topics:
acl
action
admin
authzrule
config
context
domain
errtext
exit
group
help
login
logout
object
objectspace
policy
pop
quit
rsrc
rsrccred
rsrcgroup
server
user

Miscellaneous Commands:
exit
help
quit

The following example lists the options and descriptions that are available whether you specify the topic action or action create:

pdadmin> help action

Or:

pdadmin> help action create

The output is like:

action create <action-name> <action-label> <action-type>
Creates a new ACL action definition
action create <action-name> <action-label> <action-type> <action-group-name>
Creates a new ACL action definition in a group
...

Parent topic: pdadmin commands

loginloginloginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. pdadmin loginThis command does not require a login or authentication to use.Syntaxlogin –a admin_id [–p password] [–d domain]login –a admin_id [–p password] [–m]login –l DescriptionCredentials are used to determine user access privileges to policy server data. Except the context, errtext, exit, help, login, logout, and quit commands, and the local configuration commands, a user ID, and a password are needed for authentication.Credentials are not accumulated or stacked. A login command completely replaces any existing credentials.In interactive mode, the pdadmin prompt changes, depending on how the user logs in: Not interactive mode. This command starts the pdadmin utility. In interactive mode, the login commands are entered from the pdadmin> prompt. c:\> pdadmin pdadmin>A user local login that is performed for local configuration. No authentication is required. pdadmin> login -l pdadmin local>An administrator login that is performed to the local domain. In some cases, the local domain might be the management domain, which is named Default. Authentication is required. pdadmin> login -a sec_master -p secmstrpw pdadmin sec_master>A user login that is performed to the local domain. Authentication is required. pdadmin> login -a dlucas -p lucaspw pdadmin dlucas>A user login that is performed to another domain other than their local domain. Authentication is required. pdadmin> login -a dlucas -p lucaspw -d domain_a pdadmin dlucas@domain_a>A user login that is performed to the management domain. Authentication is required. pdadmin> login -a dlucas -p lucaspw -m pdadmin dlucas@Default> Options–a admin_idSpecifies an administrator ID.–d domainSpecifies the Security Access Manager secure domain for the login. The admin_id user must exist in this domain.–mSpecifies that the login operation must be directed to the management domain. The admin_id user must exist in this domain. Only one of the following domain options can be specified: –d domain or –m. If neither option is specified, the target domain is the local domain that is configured for the system. The admin_id user must exist in the target domain, whether it is explicitly specified.–p passwordSpecifies the password for the admin_id user. If this option is not specified, the user is prompted for the password. The password cannot be specified if the admin_id is not specified.–lSpecifies a local login operation. When modifications are made to local configuration files by using the config commands, a local login is required before you can run commands. The user can run the context show command to view more authentication information. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example logs the sec_master user in to the management domain and then displays the authentication context for the user: pdadmin> login -a sec_master -p pa55w0rd -m pdadmin sec_master> context show User: sec_master Domain: Default The user is logged in to the management domain.The following example logs in a user to the domain1 domain and then displays the authentication context for the user: pdadmin> login -a domain1_admin -p d0main1pwd -d domain1 pdadmin domain1_admin@domain1> context show User: domain1_admin Domain: domain1 The user is not logged in to the management domainThe following example interactively logs in the user to their local domain that is configured for the system. The domain name is testdomain. The example then displays the authentication context of the user: pdadmin> login Enter User ID: testdomain_admin Enter password: adminpwd pdadmin testdomain_admin> context show User: testdomain_admin Domain: testdomain The user is not logged in to the management domainThe following example of a local login demonstrates how the prompt changes, depending on the type of interactive login: c:\> pdadmin login -lProvides this prompt:pdadmin local> pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

login

Establishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done.

This command does not require a login or authentication to use.

Syntax

login –a admin_id [–p password] [–d domain]

login –a admin_id [–p password] [–m]

login –l

Description

Credentials are used to determine user access privileges to policy server data. Except the context, errtext, exit, help, login, logout, and quit commands, and the local configuration commands, a user ID, and a password are needed for authentication.

Credentials are not accumulated or stacked. A login command completely replaces any existing credentials.

In interactive mode, the pdadmin prompt changes, depending on how the user logs in:

Not interactive mode. This command starts the pdadmin utility. In interactive mode, the login commands are entered from the pdadmin> prompt.

c:\> pdadmin
pdadmin>

A user local login that is performed for local configuration. No authentication is required.

pdadmin> login -l
pdadmin local>

An administrator login that is performed to the local domain. In some cases, the local domain might be the management domain, which is named Default. Authentication is required.

pdadmin> login -a sec_master -p secmstrpw
pdadmin sec_master>

A user login that is performed to the local domain. Authentication is required.

pdadmin> login -a dlucas -p lucaspw
pdadmin dlucas>

A user login that is performed to another domain other than their local domain. Authentication is required.

pdadmin> login -a dlucas -p lucaspw -d domain_a
pdadmin dlucas@domain_a>

A user login that is performed to the management domain. Authentication is required.

pdadmin> login -a dlucas -p lucaspw -m
pdadmin dlucas@Default>

Options

–a admin_id

Specifies an administrator ID.

–d domain

Specifies the Security Access Manager secure domain for the login. The admin_id user must exist in this domain.

–m

Specifies that the login operation must be directed to the management domain. The admin_id user must exist in this domain.

Note: Only one of the following domain options can be specified: –d domain or –m. If neither option is specified, the target domain is the local domain that is configured for the system. The admin_id user must exist in the target domain, whether it is explicitly specified.

–p password

Specifies the password for the admin_id user. If this option is not specified, the user is prompted for the password. The password cannot be specified if the admin_id is not specified.

–l

Specifies a local login operation. When modifications are made to local configuration files by using the config commands, a local login is required before you can run commands. The user can run the context show command to view more authentication information.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example logs the sec_master user in to the management domain and then displays the authentication context for the user:

pdadmin> login -a sec_master -p pa55w0rd -m

pdadmin sec_master> context show

User: sec_master
Domain: Default
The user is logged in to the management domain.

The following example logs in a user to the domain1 domain and then displays the authentication context for the user:

pdadmin> login -a domain1_admin -p d0main1pwd -d domain1

pdadmin domain1_admin@domain1> context show

User: domain1_admin
Domain: domain1
The user is not logged in to the management domain

The following example interactively logs in the user to their local domain that is configured for the system. The domain name is testdomain. The example then displays the authentication context of the user:

pdadmin> login
Enter User ID: testdomain_admin
Enter password: adminpwd

pdadmin testdomain_admin> context show

User: testdomain_admin
Domain: testdomain
The user is not logged in to the management domain

The following example of a local login demonstrates how the prompt changes, depending on the type of interactive login:

c:\> pdadmin login -l

Provides this prompt:

pdadmin local>

Parent topic: pdadmin commands

logoutlogoutlogoutDiscards any authentication credentials that are in effect. pdadmin utilitieslogoutThis command does not require a login or authentication to use.Syntaxlogout OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example first shows a local login and then demonstrates how the prompt changes: pdadmin login -l pdadmin local>The following example demonstrates the logout command:pdadmin local> logoutThe following example displays: Context information about the user ID.Context information about the domain ID.Whether the domain is a management domain.pdadmin domain1_admin@domain1> context show User: domain1_admin Domain: domain1 The user is not logged in to the management domain. The following example shows a logout command, and then displays context information after the logout command was issued: pdadmin domain1_admin@domain1> logout The user has been logged out and credentials have been discarded. pdadmin>context show No login information. See alsoexit or quitExits from the pdadmin utility interactive command-line mode. loginEstablishes authentication credentials that are used for communication with the Security Access Manager policy server. These credentials are used to determine access privileges for the user to policy server data. Most commands cannot be performed unless an explicit login is done. context showDisplays the user ID and domain ID used to establish the current authentication context. Also, specifies whether the domain is the management domain or a domain other than the management domain. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

logout

Discards any authentication credentials that are in effect.

This command does not require a login or authentication to use.

Syntax

logout

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example first shows a local login and then demonstrates how the prompt changes:

pdadmin login -l
pdadmin local>

The following example demonstrates the logout command:

pdadmin local> logout

The following example displays:

Context information about the user ID.

Context information about the domain ID.

Whether the domain is a management domain.

pdadmin domain1_admin@domain1> context show
User: domain1_admin
Domain: domain1
The user is not logged in to the management domain.

The following example shows a logout command, and then displays context information after the logout command was issued:

pdadmin domain1_admin@domain1> logout
The user has been logged out and credentials have been discarded.

pdadmin>context show
No login information.

See also

exit or quit

login

context show

Parent topic: pdadmin commands

object accessobject accessobject accessConfirms whether the specified access is permitted on the specified object. The access is determined based on the permissions of this user. object commandsexistsexists, objectRequires authentication (administrator ID and password) to use this command.Syntaxobject access object_name permissions Optionsobject_nameSpecifies the protected object, which is the fully qualified name of the object, including the object space within which it is located. Examples of object names are:/Management/Groups/Travel/WebSEAL/ManagementpermissionsSpecifies the permission or permissions to check. Security Access Manager uses a set of default actions that cover a wide range of operations. Actions are represented by single alphabetic ASCII characters (a-z, A-Z). For example, a list of primary action tasks and associated permissions for the user sec_master, with WebSEAL as the web server, might include: TTraverseBase cControlBase gDelegationBase mModifyGeneric dDeleteGeneric bBrowseBase sServer AdminGeneric vViewGeneric aAttachBase BBypass POPBase tTraceBase rReadWebSEAL xExecuteWebSEAL lList DirectoryWebSEAL NCreateBase WPasswordBase AAddBase RBypass AuthzRuleBase Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example confirms whether the user who is running pdadmin has the Bypass POP (B) permission on the object named /Management: pdadmin sec_master> object access /Management B The output is like: Access: NoThe following example confirms whether the user who is running pdadmin has action Password (W) permission on the object named /Management/test-object: pdadmin sec_master> object access /Management/test-object W The output is like: Access: Yes See alsoobject listandshowLists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy. object showShows values for the protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object access

Confirms whether the specified access is permitted on the specified object. The access is determined based on the permissions of this user.

Requires authentication (administrator ID and password) to use this command.

Syntax

object access object_name permissions

Options

object_name

Specifies the protected object, which is the fully qualified name of the object, including the object space within which it is located.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

permissions

Specifies the permission or permissions to check. Security Access Manager uses a set of default actions that cover a wide range of operations. Actions are represented by single alphabetic ASCII characters (a-z, A-Z).

For example, a list of primary action tasks and associated permissions for the user sec_master, with WebSEAL as the web server, might include:

TTraverseBase
cControlBase
gDelegationBase
mModifyGeneric
dDeleteGeneric
bBrowseBase
sServer AdminGeneric
vViewGeneric
aAttachBase
BBypass POPBase
tTraceBase
rReadWebSEAL
xExecuteWebSEAL
lList DirectoryWebSEAL
NCreateBase
WPasswordBase
AAddBase
RBypass AuthzRuleBase

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example confirms whether the user who is running pdadmin has the Bypass POP (B) permission on the object named /Management:

pdadmin sec_master> object access /Management B

The output is like:

Access: No

The following example confirms whether the user who is running pdadmin has action Password (W) permission on the object named /Management/test-object:

pdadmin sec_master> object access /Management/test-object W

The output is like:

Access: Yes

See also

object listandshow

object show

Parent topic: pdadmin commands

object copyRecursively copy the policy from one protected object space to another. The policy that is copied includes ACLs, POPs, authorization rules, and extended attributes.Requires authentication (administrator ID and password) to use this command. Both source and destination objects must exist under an object space. The recursive copy occurs in the background and the command will immediately return. Only one copy operation occurs at a time. So extra copy operations are queued until the copy operation that preceded it is completed. A message is logged in the policy server's log file when the copy operation starts and when it completes. The completion message also indicates whether the copy operation is a success or failure.Syntaxobject copy -recursive src_object_name dst_object_nameOptions src_object_nameThe source object name. Specifies the protected object, which is the fully qualified name of the object, including the object space within which it is located. The src_object_name and all its child objects are copied to the dst_object_name including ACLs, POPs, authorization rules, and extended attributes that are attached to them.An example object name is: /WebSEAL/abc.ibm.com-defaultdst_object_nameThe destination object name. Specifies the protected object, which is the fully qualified name of the object, including the object space within which it is located. The src_object_name and all its child objects are copied to the dst_object_name including ACLs, POPs, authorization rules, and extended attributes that are attached to them.An example object name is: /WebSEAL/new.ibm.com-defaultReturn codes 0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.Examples The following example performs a recursive copy of the contents of the /WebSEAL/abc.ibm.com-default object to the /WebSEAL/new.ibm.com-default object. pdadmin sec_master> object copy -recursive /WebSEAL/abc.ibm.com-default /WebSEAL/new.ibm.com-defaultpdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object copy

Recursively copy the policy from one protected object space to another. The policy that is copied includes ACLs, POPs, authorization rules, and extended attributes.

Requires authentication (administrator ID and password) to use this command.

Both source and destination objects must exist under an object space.

The recursive copy occurs in the background and the command will immediately return. Only one copy operation occurs at a time. So extra copy operations are queued until the copy operation that preceded it is completed.

A message is logged in the policy server's log file when the copy operation starts and when it completes. The completion message also indicates whether the copy operation is a success or failure.

Syntax

object copy -recursive src_object_name dst_object_name

Options

src_object_name

The source object name. Specifies the protected object, which is the fully qualified name of the object, including the object space within which it is located. The src_object_name and all its child objects are copied to the dst_object_name including ACLs, POPs, authorization rules, and extended attributes that are attached to them.

An example object name is: /WebSEAL/abc.ibm.com-default

dst_object_name

The destination object name. Specifies the protected object, which is the fully qualified name of the object, including the object space within which it is located. The src_object_name and all its child objects are copied to the dst_object_name including ACLs, POPs, authorization rules, and extended attributes that are attached to them.

An example object name is: /WebSEAL/new.ibm.com-default

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example performs a recursive copy of the contents of the /WebSEAL/abc.ibm.com-default object to the /WebSEAL/new.ibm.com-default object.

pdadmin sec_master> object copy -recursive /WebSEAL/abc.ibm.com-default
/WebSEAL/new.ibm.com-default

Parent topic: pdadmin commands

object createobject createobject createCreates a protected object. object commandscreateAuthentication (administrator ID and password) required to use this command.Syntaxobject create object_name object_description type ispolicyattachable {yes|no} Optionsobject_descriptionSpecifies any text string that describes the object that is being created. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.An example of a description is "Travel Groups".ispolicyattachable {yes|no}Specifies whether an ACL, a protected object policy, or an authorization rule can be attached to this object. Valid values are yes or no.object_nameSpecifies the name for the protected object that is being created. This name is the fully qualified name of the object, including the object space within which it is located. This name must be unique. A valid object name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.Examples of object names are:/Management/Groups/Travel/WebSEAL/ManagementtypeSpecifies the type of object to be created. Types range from 0 to 17. For example, types 10 or 16 are appropriate for container objects. Object types are described in the Administering topics in the IBM Knowledge Center.You can assign any of the following types: 0Unknown1Secure domain2File3Executable program4Directory5Junction6WebSEAL server7Unused8Unused9HTTP server10Nonexistent object11Container object12Leaf object13Port14Application container object15Application leaf object16Management object17Unused Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates the object named /Management/test-object that has a description of Test Object and is an application container object (14). An ACL or a protected object policy can be attached to this object: pdadmin sec_master> object create /Management/test-object "Test Object" 14 ispolicyattachable yesThe following example creates the object named /Management/Groups/Travel that has a description of Travel Container Object and is an application container object (14). An ACL or a protected object policy cannot be attached to this object: pdadmin sec_master> object create /Management/Groups/Travel "Travel Container Object" 14 ispolicyattachable no See alsoobject existsIndicates whether a protected object exists. object deleteDeletes a protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object create

Creates a protected object.

Authentication (administrator ID and password) required to use this command.

Syntax

object create object_name object_description type ispolicyattachable {yes|no}

Options

object_description

Specifies any text string that describes the object that is being created.

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

An example of a description is "Travel Groups".

ispolicyattachable {yes|no}

Specifies whether an ACL, a protected object policy, or an authorization rule can be attached to this object. Valid values are yes or no.

object_name

Specifies the name for the protected object that is being created. This name is the fully qualified name of the object, including the object space within which it is located. This name must be unique.

A valid object name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

type

Specifies the type of object to be created. Types range from 0 to 17. For example, types 10 or 16 are appropriate for container objects. Object types are described in the Administering topics in the IBM Knowledge Center.

You can assign any of the following types:

0

Unknown

1

Secure domain

2

File

3

Executable program

4

Directory

5

Junction

6

WebSEAL server

7

Unused

8

Unused

9

HTTP server

10

Nonexistent object

11

Container object

12

Leaf object

13

Port

14

Application container object

15

Application leaf object

16

Management object

17

Unused

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates the object named /Management/test-object that has a description of Test Object and is an application container object (14). An ACL or a protected object policy can be attached to this object:

pdadmin sec_master> object create /Management/test-object "Test Object" 14
ispolicyattachable yes

The following example creates the object named /Management/Groups/Travel that has a description of Travel Container Object and is an application container object (14). An ACL or a protected object policy cannot be attached to this object:

pdadmin sec_master> object create /Management/Groups/Travel "Travel
Container Object" 14 ispolicyattachable no

See also

object exists

object delete

Parent topic: pdadmin commands

object deleteobject deleteobject deleteDeletes a protected object. object commandsdeleteRequires authentication (administrator ID and password) to use this command.Syntaxobject delete object_name Optionsobject_nameSpecifies the protected object to be deleted, which is the fully qualified name of the object, including the object space in which it is located. The object must exist, or an error is displayed. Examples of object names are:/Management/Groups/Travel/WebSEAL/Management Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the object named /Management/test-object: pdadmin sec_master> object delete /Management/test-objectThe following example deletes the object named /Management/Groups/Travel: pdadmin sec_master> object delete /Management/Groups/Travel See alsoobject existsIndicates whether a protected object exists. object createCreates a protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object delete

Deletes a protected object.

Requires authentication (administrator ID and password) to use this command.

Syntax

object delete object_name

Options

object_name

Specifies the protected object to be deleted, which is the fully qualified name of the object, including the object space in which it is located. The object must exist, or an error is displayed.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the object named /Management/test-object:

pdadmin sec_master> object delete /Management/test-object

The following example deletes the object named /Management/Groups/Travel:

pdadmin sec_master> object delete /Management/Groups/Travel

See also

object exists

object create

Parent topic: pdadmin commands

object existsobject existsobject existsIndicates whether a protected object exists. object commandsexistsexists, objectThe protected object might be located either in: The policy database, or inAn object space that is managed by an administration service plug-in.The administration service plug-in might be registered by an authorization application, such as WebSEAL. Use this command to determine whether the specified object was created. Authentication (administrator ID and password) is required to use this command.Syntaxobject exists object_name Optionsobject_nameSpecifies the protected object, which is the fully qualified name of the object, including the object space within which it is located. Examples of object names are:/Management/Groups/Travel/WebSEAL/Management Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example confirms whether the object named /Management/protected_object1 exists: pdadmin sec_master> object exists /Management/protected_object1The output is like: Exists: YesThe following example confirms whether the object named /Management/notAnObject exists: pdadmin sec_master> object exists /Management/notAnObjectThe output is like: Exists: No See alsoobject listandshowLists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy. object showShows values for the protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object exists

Indicates whether a protected object exists.

The protected object might be located either in:

The policy database, or in

An object space that is managed by an administration service plug-in.

The administration service plug-in might be registered by an authorization application, such as WebSEAL. Use this command to determine whether the specified object was created.

Authentication (administrator ID and password) is required to use this command.

Syntax

object exists object_name

Options

object_name

Specifies the protected object, which is the fully qualified name of the object, including the object space within which it is located.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example confirms whether the object named /Management/protected_object1 exists:

pdadmin sec_master> object exists /Management/protected_object1

The output is like:

Exists: Yes

The following example confirms whether the object named /Management/notAnObject exists:

pdadmin sec_master> object exists /Management/notAnObject

The output is like:

Exists: No

See also

object listandshow

object show

Parent topic: pdadmin commands

object listobject listobject listLists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object. object commandslistRequires authentication (administrator ID and password) to use this command.Syntaxobject listobject list object_nameobject list object_name attribute Optionsobject listLists all protected objects. The output is the same as if you issued the objectspace list command. object list object_nameLists all objects that are grouped under the specified protected object. The specified object is the fully qualified name of the object, including the object space within which it is located.object list object_name attributeLists all extended attributes that are associated with the specified protected object. The object must exist, or an error is displayed. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example lists all the protected object spaces under the root of the object namespace (/): pdadmin sec_master> object list Displays a list like: /Management /MyObjectSpace_1 ... /WebSEALThe following example lists all the protected objects under the protected object named /Management. In this example, both /Management and /Management/ACL are object spaces: pdadmin sec_master> object list /Management Displays a list like: /Management/ACL /Management/Action /Management/Config ... /Management/test-objectThe following example lists the extended attributes for the object named /Management/test-object: pdadmin sec_master> object list /Management/test-object attribute Displays a list of attributes like: test1 See alsoobject listandshowLists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy. object showShows values for the protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object list

Lists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object.

Requires authentication (administrator ID and password) to use this command.

Syntax

object list

object list object_name

object list object_name attribute

Options

object list

Lists all protected objects. The output is the same as if you issued the objectspace list command.

object list object_name

Lists all objects that are grouped under the specified protected object. The specified object is the fully qualified name of the object, including the object space within which it is located.

object list object_name attribute

Lists all extended attributes that are associated with the specified protected object. The object must exist, or an error is displayed.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists all the protected object spaces under the root of the object namespace (/):

pdadmin sec_master> object list

Displays a list like:

/Management
/MyObjectSpace_1
...
/WebSEAL

The following example lists all the protected objects under the protected object named /Management. In this example, both /Management and /Management/ACL are object spaces:

pdadmin sec_master> object list /Management

Displays a list like:

/Management/ACL
/Management/Action
/Management/Config
...
/Management/test-object

The following example lists the extended attributes for the object named /Management/test-object:

pdadmin sec_master> object list /Management/test-object attribute

Displays a list of attributes like:

test1

See also

object listandshow

object show

Parent topic: pdadmin commands

object listandshowobject listandshowobject listandshowLists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy. object commandslistandshowRequires authentication (administrator ID and password) to use this command.Syntaxobject listandshow object_name Optionsobject_nameSpecifies the protected object for which the child objects and associated values are to be displayed. The specified protected object is the fully qualified name of the object, including the object space within which it is located. Examples of object names are:/Management/Groups/Travel/WebSEAL/Management Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example lists the object named /Management/Groups/Travel and also automatically lists extended attributes, if any: pdadmin sec_master> object listandshow /Management/Groups/Travel Displays information like: Name : /Management/Groups/Travel Description : Travel Container Object Type : 14 (Application Container Object) Is Policy Attachable : no Extended Attributes : test1 1111The following example displays the object named /Management/test-object and lists any attached policies (myrule) and effective policies (myacl and mypop): pdadmin sec_master> object listandshow /Management/test-object Displays information like: Name : /Management/test-object Description : Test Object Type : 14 (Application Container Object) Is Policy Attachable : yes Attached ACL : Attached POP : Attached AuthzRule : myrule Effective ACL : myacl Effective POP : mypop Effective AuthzRule : myrule See alsoobject listLists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object. object showShows values for the protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object listandshow

Lists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy.

Requires authentication (administrator ID and password) to use this command.

Syntax

object listandshow object_name

Options

object_name

Specifies the protected object for which the child objects and associated values are to be displayed. The specified protected object is the fully qualified name of the object, including the object space within which it is located.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists the object named /Management/Groups/Travel and also automatically lists extended attributes, if any:

pdadmin sec_master> object listandshow /Management/Groups/Travel

Displays information like:

Name : /Management/Groups/Travel
Description : Travel Container Object
Type : 14 (Application Container Object)
Is Policy Attachable : no
Extended Attributes :
test1
1111

The following example displays the object named /Management/test-object and lists any attached policies (myrule) and effective policies (myacl and mypop):

pdadmin sec_master> object listandshow /Management/test-object

Displays information like:

Name : /Management/test-object
Description : Test Object
Type : 14 (Application Container Object)
Is Policy Attachable : yes
Attached ACL :
Attached POP :
Attached AuthzRule : myrule
Effective ACL : myacl
Effective POP : mypop
Effective AuthzRule : myrule

See also

object list

object show

Parent topic: pdadmin commands

object modifyobject modifyobject modifyModifies an existing object. object commandsmodifyRequires authentication (administrator ID and password) to use this command.Syntaxobject modify object_name delete attribute attribute_name [attribute_value]object modify object_name set attribute attribute_name attribute_valueobject modify object_name set description descriptionobject modify object_name set ispolicyattachable {yes|no}object modify object_name set type type Optionsdelete attribute attribute_name [attribute_value]Deletes the specified extended attribute (name and value) from the specified protected object. The attribute must exist, or an error is displayed. When you delete the last value for an attribute, it also deletes the attribute from the specified protected object. The optional attribute_value deletes the specified value from the specified extended attribute key in the specified protected object. Examples of attribute names and values: test11111 Dept_No445 Employee_name"Diana Lucas"object_nameSpecifies the protected object to be modified. The specified protected object is the fully qualified name of the object, including the object space within which it is located. The object must exist, or an error is displayed. Examples of object names are:/Management/Groups/Travel/WebSEAL/Managementset attribute attribute_name attribute_valueCreates an extended attribute, with the specified name and value, and adds it to the specified protected object. If the attribute exists, the attribute value is added as an additional value if the same value does not exist for this attribute. If the same value exists for this attribute, it does not get added again (duplicate values are not allowed), and no error is returned. The optional attribute_value sets the specified value from the specified extended attribute key in the specified protected object. The attribute value must exist, or an error is displayed.Examples of extended attribute names and values: attr1valueA attr1valueB attr2valueCset description descriptionSets the description field of the specified protected object. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.Example of description: "Travel Group aaa"set ispolicyattachable {yes|no}Sets whether the protected object can have an ACL, a POP, or an authorization rule attached or not. Valid values are yes or no.set type typeSpecifies the type of the object space to be created. Types range from 0 to 17. For example, types 10 or 16 are appropriate for objects. You can assign any of the following types: 0Unknown1Secure domain2File3Executable program4Directory5Junction6WebSEAL server7Unused8Unused9HTTP server10Nonexistent object11Container object12Leaf object13Port14Application container object15Application leaf object16Management object17Unused Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example sets the ispolicyattachable option for the /Management/Groups/Travel object: pdadmin sec_master> object modify /Management/Groups/Travel set ispolicyattachable yesThe following example sets the attributes for the /Management/test-object object: pdadmin sec_master> object modify /Management/test-object set attribute test1 1111 See alsoobject createCreates a protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object modify

Modifies an existing object.

Requires authentication (administrator ID and password) to use this command.

Syntax

object modify object_name delete attribute attribute_name [attribute_value]

object modify object_name set attribute attribute_name attribute_value

object modify object_name set description description

object modify object_name set ispolicyattachable {yes|no}

object modify object_name set type type

Options

delete attribute attribute_name [attribute_value]

Deletes the specified extended attribute (name and value) from the specified protected object. The attribute must exist, or an error is displayed. When you delete the last value for an attribute, it also deletes the attribute from the specified protected object. The optional attribute_value deletes the specified value from the specified extended attribute key in the specified protected object. Examples of attribute names and values:

test11111
Dept_No445
Employee_name"Diana Lucas"

object_name

Specifies the protected object to be modified. The specified protected object is the fully qualified name of the object, including the object space within which it is located. The object must exist, or an error is displayed.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

set attribute attribute_name attribute_value

Creates an extended attribute, with the specified name and value, and adds it to the specified protected object. If the attribute exists, the attribute value is added as an additional value if the same value does not exist for this attribute. If the same value exists for this attribute, it does not get added again (duplicate values are not allowed), and no error is returned.

The optional attribute_value sets the specified value from the specified extended attribute key in the specified protected object. The attribute value must exist, or an error is displayed.

Examples of extended attribute names and values:

attr1valueA
attr1valueB
attr2valueC

set description description

Sets the description field of the specified protected object.

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are allowed. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

Example of description: "Travel Group aaa"

set ispolicyattachable {yes|no}

Sets whether the protected object can have an ACL, a POP, or an authorization rule attached or not. Valid values are yes or no.

set type type

Specifies the type of the object space to be created. Types range from 0 to 17. For example, types 10 or 16 are appropriate for objects.

You can assign any of the following types:

0

Unknown

1

Secure domain

2

File

3

Executable program

4

Directory

5

Junction

6

WebSEAL server

7

Unused

8

Unused

9

HTTP server

10

Nonexistent object

11

Container object

12

Leaf object

13

Port

14

Application container object

15

Application leaf object

16

Management object

17

Unused

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example sets the ispolicyattachable option for the /Management/Groups/Travel object:

pdadmin sec_master> object modify /Management/Groups/Travel set
ispolicyattachable yes

The following example sets the attributes for the /Management/test-object object:

pdadmin sec_master> object modify /Management/test-object set attribute
test1 1111

See also

object create

Parent topic: pdadmin commands

object showobject showobject showShows values for the protected object. object commandsshowIf the protected object name specified does not exist, default values are shown. To determine whether a protected object exists, use the object show command.Requires authentication (administrator ID and password) to use this command.Syntaxobject show object_name [attribute attribute_name] DescriptionThe object show command shows values that are associated with the protected object.The object values shown can include: ACLs.POPs.Authorization rules. Extended attributes, such as attribute name and value pairs.These extended attributes can be attached directly to the object or inherited from protected objects in the hierarchy of this object. When the attribute option is specified, the attribute_name value or values are shown if the attribute is attached to the protected object specified. This command limits the output for POPs, ACLs, and authorization rules, which are based on the permissions of the user. A user must have the view (v) permission on the object to show it. Optionsobject_nameSpecifies the protected object. The specified protected object is the fully qualified name of the object, including the object space within which it is located. Examples of object names are:/Management/Groups/Travel/WebSEAL/Managementattribute attribute_nameSpecifies the name of the extended attribute whose values are to be displayed. (Optional) The extended attribute must exist for the object name that is specified, or an error is displayed. In the example that is listed for the /object-text object in Examples, the following extended attributes are shown: test1test2abc Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays the /object-test object and lists all attached and effective ACLs, POPs, authzrules, and extended attributes: pdadmin sec_master> object show /object-test Displays information like: Name: /object-test Description: Test object Type: 12 (Leaf Object) Is Policy Attachable : Yes Extended Attributes: Name:test1 Value(s): 1111 Name:test2 Value(s): abc 2222 second Attached ACL: Attached POP: Attached AuthzRule: Effective Extended Attributes: Protected Object Location: /object-test Name:test1 Value(s): 1111 Name:test2 Value(s): abc 2222 second Effective ACL: default-root Effective POP: Effective AuthzRule:The following example displays the /object-test/child1 object and lists all attached and effective ACLs, POPs, AuthzRules, and extended attributes: pdadmin sec_master> object show /object-test/child1 Displays information like: Name: /object-test/child1 Description: Child 1 Type: 12 (Leaf Object) Is Policy Attachable : Yes Extended Attributes: Attached ACL: Attached POP: Attached AuthzRule: Effective Extended Attributes: Protected Object Location: /object-test Name:test1 Value(s): 1111 Name:test2 Value(s): abc 2222 second Effective ACL: default-root Effective POP: Effective AuthzRule:The following example displays information about the test1 attribute that is listed for object/object-test/child1: pdadmin sec_master> object show /object-test/child1 attribute test1 Because the test1 attribute is an extended attribute of the /object-test object, the command returns the following message: Could not perform the administration requestError: HPDAC0463E There are no extended attributes associated with the specified protected object or authorization policy object. (status 0x1005b1cf)To view the information about the test1 attribute of the /object-test object, enter the following command: pdadmin sec_master> object show /object-test attribute test1 Displays information like:test1 1111The following example displays the /Management/test-object object, which lists any attached (myrule) and effective (myacl and mypop) policies: pdadmin sec_master> object show /Management/test-object Displays information like: Name: /Management/test-object/ Description : Test object Type: 14 (Application Container Object) Is Policy Attachable: Yes Extended Attributes: Attached ACL: myacl Attached POP: mypop Attached AuthzRule: myrule Effective Extended Attributes: Effective ACL: myacl Effective POP: mypop Effective AuthzRule: myruleThe following example creates a protected object and then performs an object show of that protected object. An object show is then performed for an object that has not been created. Then the object exists command is issued for both of these objects. pdadmin sec_master> object create /Management/new_object1" "0ispoly pdadmin sec_master> object show /Management/new_object1 Name: /Management/new_object1 Description: Type: 0 (Unknown) Is Policy Attachable: Yes Extended Attributes: Attached ACL: Attached POP: Attached AuthzRule: Effective Extended Attributes: Effective ACL: default-management Effective POP: Effective AuthzRule: pdadmin sec_master> object show /Management/not_there_object Name: /Management/not_there_object Description: Type: 0 (Unknown) Is Policy Attachable: Yes Extended Attributes: Attached ACL: Attached POP: Attached AuthzRule: Effective Extended Attributes: Effective ACL: default-management Effective POP: Effective AuthzRule: pdadmin sec_master> object exists /Management/new_object1 Exists: Yes pdadmin sec_master> object exists /Management/not_there_object Exists: No See alsoobject listLists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object. object listLists any objects that are grouped under the specified protected object. Alternatively, lists all the extended attributes that are associated with the specified protected object. object listandshowLists any child objects that are grouped under the specified protected object and displays all values that are associated with each object. Shows all values that are associated with the protected object, including the attached ACLs, POPs, and authorization rules. Also shows any policies that are inherited from protected objects higher in the hierarchy. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

object show

Shows values for the protected object.

If the protected object name specified does not exist, default values are shown. To determine whether a protected object exists, use the object show command.

Requires authentication (administrator ID and password) to use this command.

Syntax

object show object_name [attribute attribute_name]

Description

The object show command shows values that are associated with the protected object.

The object values shown can include:

ACLs.

POPs.

Authorization rules.

Extended attributes, such as attribute name and value pairs.

These extended attributes can be attached directly to the object or inherited from protected objects in the hierarchy of this object.

When the attribute option is specified, the attribute_name value or values are shown if the attribute is attached to the protected object specified.

This command limits the output for POPs, ACLs, and authorization rules, which are based on the permissions of the user. A user must have the view (v) permission on the object to show it.

Options

object_name

Specifies the protected object. The specified protected object is the fully qualified name of the object, including the object space within which it is located.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

attribute attribute_name

Specifies the name of the extended attribute whose values are to be displayed. (Optional) The extended attribute must exist for the object name that is specified, or an error is displayed. In the example that is listed for the /object-text object in Examples, the following extended attributes are shown:

test1

test2

abc

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays the /object-test object and lists all attached and effective ACLs, POPs, authzrules, and extended attributes:

pdadmin sec_master> object show /object-test

Displays information like:

Name: /object-test
Description: Test object
Type: 12 (Leaf Object)
Is Policy Attachable : Yes
Extended Attributes:
Name:test1
Value(s): 1111
Name:test2
Value(s): abc
2222
second
Attached ACL:
Attached POP:
Attached AuthzRule:

Effective Extended Attributes:
Protected Object Location: /object-test
Name:test1
Value(s): 1111
Name:test2
Value(s): abc
2222
second
Effective ACL: default-root
Effective POP:
Effective AuthzRule:

The following example displays the /object-test/child1 object and lists all attached and effective ACLs, POPs, AuthzRules, and extended attributes:

pdadmin sec_master> object show /object-test/child1

Displays information like:

Name: /object-test/child1
Description: Child 1
Type: 12 (Leaf Object)
Is Policy Attachable : Yes
Extended Attributes:
Attached ACL:
Attached POP:
Attached AuthzRule:

Effective Extended Attributes:
Protected Object Location: /object-test
Name:test1
Value(s): 1111
Name:test2
Value(s): abc
2222
second
Effective ACL: default-root
Effective POP:
Effective AuthzRule:

The following example displays information about the test1 attribute that is listed for object/object-test/child1:

pdadmin sec_master> object show /object-test/child1 attribute test1

Because the test1 attribute is an extended attribute of the /object-test object, the command returns the following message:

Could not perform the administration request
Error: HPDAC0463E There are no extended attributes associated with the specified protected object or authorization policy object. (status 0x1005b1cf)

To view the information about the test1 attribute of the /object-test object, enter the following command:

pdadmin sec_master> object show /object-test attribute test1

Displays information like:

test1
1111

The following example displays the /Management/test-object object, which lists any attached (myrule) and effective (myacl and mypop) policies:

pdadmin sec_master> object show /Management/test-object

Displays information like:

Name: /Management/test-object/
Description : Test object
Type: 14 (Application Container Object)
Is Policy Attachable: Yes
Extended Attributes:
Attached ACL: myacl
Attached POP: mypop
Attached AuthzRule: myrule

Effective Extended Attributes:
Effective ACL: myacl
Effective POP: mypop
Effective AuthzRule: myrule

The following example creates a protected object and then performs an object show of that protected object. An object show is then performed for an object that has not been created. Then the object exists command is issued for both of these objects.

pdadmin sec_master> object create /Management/new_object1" "0ispoly

pdadmin sec_master> object show /Management/new_object1
Name: /Management/new_object1
Description:
Type: 0 (Unknown)
Is Policy Attachable: Yes
Extended Attributes:
Attached ACL:
Attached POP:
Attached AuthzRule:

Effective Extended Attributes:
Effective ACL: default-management
Effective POP:
Effective AuthzRule:

pdadmin sec_master> object show /Management/not_there_object
Name: /Management/not_there_object
Description:
Type: 0 (Unknown)
Is Policy Attachable: Yes
Extended Attributes:
Attached ACL:
Attached POP:
Attached AuthzRule:

Effective Extended Attributes:
Effective ACL: default-management
Effective POP:
Effective AuthzRule:

pdadmin sec_master> object exists /Management/new_object1
Exists: Yes
pdadmin sec_master> object exists /Management/not_there_object
Exists: No

See also

object list

object list

object listandshow

Parent topic: pdadmin commands

objectspace createobjectspace createobjectspace createCreates a protected object space under which protected objects can be placed. object space commandsobjectspace createRequires authentication (administrator ID and password) to use this command.Syntaxobjectspace create objectspace_name description type Description The root of the new protected object space automatically has the ispolicyattachable option that is set to true. OptionsdescriptionSpecifies the description of the new object space. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.An example description is "Accounting".objectspace_name Specifies the name of the object space to be created. A valid object space name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.Examples of object space names are /Management and /WebSEAL.typeSpecifies the type of the object space to be created. Types range from 0 to 17. For example, types 10 or 16 are appropriate for objects and object spaces. You can assign any of the following types: 0Unknown1Secure domain2File3Executable program4Directory5Junction6WebSEAL server7Unused8Unused9HTTP server10Nonexistent object11Container object12Leaf object13Port14Application container object15Application leaf object16Management object17Unused Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates an object space named /Test-Space that is an application container object (type 14): pdadmin sec_master> objectspace create /Test-Space "New Object Space" 14The following example creates an object space named /Dept4D4 that is a management object (type 16): pdadmin sec_master> objectspace create /Dept4D4 "Department 4D4" 16 See alsoobjectspace deleteDeletes the specified protected object space. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

objectspace create

Creates a protected object space under which protected objects can be placed.

Requires authentication (administrator ID and password) to use this command.

Syntax

objectspace create objectspace_name description type

Description

The root of the new protected object space automatically has the ispolicyattachable option that is set to true.

Options

description

Specifies the description of the new object space.

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

An example description is "Accounting".

objectspace_name

Specifies the name of the object space to be created.

A valid object space name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.

Examples of object space names are /Management and /WebSEAL.

type

Specifies the type of the object space to be created. Types range from 0 to 17. For example, types 10 or 16 are appropriate for objects and object spaces.

You can assign any of the following types:

0

Unknown

1

Secure domain

2

File

3

Executable program

4

Directory

5

Junction

6

WebSEAL server

7

Unused

8

Unused

9

HTTP server

10

Nonexistent object

11

Container object

12

Leaf object

13

Port

14

Application container object

15

Application leaf object

16

Management object

17

Unused

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates an object space named /Test-Space that is an application container object (type 14):

pdadmin sec_master> objectspace create /Test-Space "New Object Space" 14

The following example creates an object space named /Dept4D4 that is a management object (type 16):

pdadmin sec_master> objectspace create /Dept4D4 "Department 4D4" 16

See also

objectspace delete

Parent topic: pdadmin commands

objectspace deleteobjectspace deleteobjectspace deleteDeletes the specified protected object space. object space commandsobjectspace deleteRequires authentication (administrator ID and password) to use this command.Syntaxobjectspace delete objectspace_name Optionsobjectspace_nameSpecifies the name of the object space to be deleted. The object space must exist or an error is displayed. Examples of object space names are /Management and /WebSEAL. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the object space named /Test-Space: pdadmin sec_master> objectspace delete /Test-SpaceThe following example deletes the object space named /Dept4D4: pdadmin sec_master> objectspace delete /Dept4D4 See alsoobjectspace createCreates a protected object space under which protected objects can be placed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

objectspace delete

Deletes the specified protected object space.

Requires authentication (administrator ID and password) to use this command.

Syntax

objectspace delete objectspace_name

Options

objectspace_name

Specifies the name of the object space to be deleted. The object space must exist or an error is displayed.

Examples of object space names are /Management and /WebSEAL.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the object space named /Test-Space:

pdadmin sec_master> objectspace delete /Test-Space

The following example deletes the object space named /Dept4D4:

pdadmin sec_master> objectspace delete /Dept4D4

See also

objectspace create

Parent topic: pdadmin commands

objectspace listobjectspace listobjectspace listLists all the existing protected object spaces in the policy server. object space commandsobjectspace listRequires authentication (administrator ID and password) to use this command.Syntaxobjectspace list OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example lists all the protected object spaces: pdadmin sec_master> objectspace list Displays a list like: /Management /MyObjectSpace_1 ... /WebSEAL pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

objectspace list

Lists all the existing protected object spaces in the policy server.

Requires authentication (administrator ID and password) to use this command.

Syntax

objectspace list

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example lists all the protected object spaces:

pdadmin sec_master> objectspace list

Displays a list like:

/Management
/MyObjectSpace_1
...
/WebSEAL

Parent topic: pdadmin commands

policy getpolicy getpolicy getDisplays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.policy commandspolicy getSyntaxpolicy get account-expiry-date [–user user_name]policy get disable-time-interval [–user user_name]policy get max-concurrent-web-sessions [–user user_name]policy get max-login-failures [–user user_name]policy get max-password-age [–user user_name]policy get max-password-repeated-chars [–user user_name]policy get min-password-alphas [–user user_name]policy get min-password-length [–user user_name]policy get min-password-non-alphas [–user user_name]policy get password-spaces [–user user_name]policy get tod-access [–user user_name] Options –user user_nameSpecifies the user whose policy information is to be displayed. If this option is not specified, the general policy is displayed. For any specified policy, if a user has a specific policy that is applied, this specific policy takes precedence over any general policy that might also be defined. The precedence applies regardless of whether the specific policy is more or less restrictive than the general policy. Examples of user names are dlucas, sec_master, and "Mary Jones". (Optional)account-expiry-dateDisplays the account expiration date.disable-time-intervalDisplays the time, in seconds, to disable user accounts when the maximum number of login failures is exceeded.max-concurrent-web-sessionsDisplays the maximum number of concurrent web sessions. The value is a number equal to or greater than 1 or one of the following values: displaceAll existing web sessions end when the user starts a new web session.unlimitedThe user can start an unlimited number of web sessions.unsetThe web session policy is not set.This policy applies only to certain components. A web session is a user session that is maintained by a web security solution, such as WebSEAL or the plug-in for web servers. See the IBM Knowledge Center to determine whether this setting is applicable and whether specific configuration options are required to enforce this policy.max-login-failuresDisplays the maximum number of login failures. To enforce maximum login failures, the disable-time-interval parameter must be set. For more information, see the disable time interval section.max-password-ageDisplays the maximum time that a password is valid. The time is indicated in days, expressed as 000–00:00:00. For example, 31-08:30:00 for 31 days, 8 hours, 30 minutes, 0 seconds. This time is relative to the last time the password was changed.max-password-repeated-charsDisplays the maximum number of repeated characters that are allowed in a password.min-password-alphasDisplays the minimum number of alphabetic characters that are required in a password.min-password-lengthDisplays the minimum password length.min-password-non-alphasDisplays the minimum number of non-alphabetic characters that are required in a password.password-spacesDisplays whether spaces are allowed in passwords.tod-accessDisplays the time of day access policy. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example returns the account expiration date of unlimited for the specified user dlucas: pdadmin sec_master> policy get account-expiry-date -user dlucas Account expiry date: unlimitedThe following example returns the maximum time of 0 days, where zero indicates unlimited, that the password is valid for the specified user dlucas: pdadmin sec_master> policy get max-password-age -user dlucasFor unlimited password age, returns information like: Maximum password age: 0-0:0:0 See alsopolicy setSets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

policy get

Displays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.

Syntax

policy get account-expiry-date [–user user_name]

policy get disable-time-interval [–user user_name]

policy get max-concurrent-web-sessions [–user user_name]

policy get max-login-failures [–user user_name]

policy get max-password-age [–user user_name]

policy get max-password-repeated-chars [–user user_name]

policy get min-password-alphas [–user user_name]

policy get min-password-length [–user user_name]

policy get min-password-non-alphas [–user user_name]

policy get password-spaces [–user user_name]

policy get tod-access [–user user_name]

Options

–user user_name

Specifies the user whose policy information is to be displayed. If this option is not specified, the general policy is displayed. For any specified policy, if a user has a specific policy that is applied, this specific policy takes precedence over any general policy that might also be defined. The precedence applies regardless of whether the specific policy is more or less restrictive than the general policy. Examples of user names are dlucas, sec_master, and "Mary Jones". (Optional)

account-expiry-date

Displays the account expiration date.

disable-time-interval

Displays the time, in seconds, to disable user accounts when the maximum number of login failures is exceeded.

max-concurrent-web-sessions

Displays the maximum number of concurrent web sessions. The value is a number equal to or greater than 1 or one of the following values:

displace

All existing web sessions end when the user starts a new web session.

unlimited

The user can start an unlimited number of web sessions.

unset

The web session policy is not set.

This policy applies only to certain components. A web session is a user session that is maintained by a web security solution, such as WebSEAL or the plug-in for web servers. See the IBM Knowledge Center to determine whether this setting is applicable and whether specific configuration options are required to enforce this policy.

max-login-failures

Displays the maximum number of login failures. To enforce maximum login failures, the disable-time-interval parameter must be set. For more information, see the disable time interval section.

max-password-age

Displays the maximum time that a password is valid. The time is indicated in days, expressed as 000–00:00:00. For example, 31-08:30:00 for 31 days, 8 hours, 30 minutes, 0 seconds. This time is relative to the last time the password was changed.

max-password-repeated-chars

Displays the maximum number of repeated characters that are allowed in a password.

min-password-alphas

Displays the minimum number of alphabetic characters that are required in a password.

min-password-length

Displays the minimum password length.

min-password-non-alphas

Displays the minimum number of non-alphabetic characters that are required in a password.

password-spaces

Displays whether spaces are allowed in passwords.

tod-access

Displays the time of day access policy.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example returns the account expiration date of unlimited for the specified user dlucas:

pdadmin sec_master> policy get account-expiry-date -user dlucas
Account expiry date: unlimited

The following example returns the maximum time of 0 days, where zero indicates unlimited, that the password is valid for the specified user dlucas:

pdadmin sec_master> policy get max-password-age -user dlucas

For unlimited password age, returns information like:

Maximum password age: 0-0:0:0

See also

policy set

Parent topic: pdadmin commands

policy setpolicy setpolicy setSets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.policy commandspolicy setSyntaxpolicy set account-expiry-date {unlimited|absolute_time|unset} [–user user_name]policy set disable-time-interval {number|unset|disable} [–user user_name]policy set max-concurrent-web-sessions {number|displace|unlimited|unset} [–user user_name]policy set max-login-failures {number|unset} [–user user_name]policy set max-password-age {unset|relative_time} [–user user_name]policy set max-password-repeated-chars {number|unset} [–user user_name]policy set min-password-alphas {unset|number} [–user user_name]policy set min-password-length {unset|number} [–user user_name]policy set min-password-non-alphas {unset|number} [–user user_name]policy set password-spaces {v|no|unset} [–user user_name]policy set tod-access {{anyday|weekday|day_list}:{anytime|time_spec} [:{utc|local}]|unset} [–user user_name] DescriptionThe valid range for numbers can be any number. However, use a reasonable number for the task that you want to complete. For example, a minimum password length must be long enough to protect your system. In addition, the password must not be so short as to make it easy for someone to determine your password by trying different combinations.When you define the password policy, ensure that this definition complies with the password policy of the underlying operating systems and user registries.Optionsaccount-expiry-date {unlimited|absolute_time|unset}Sets the account expiration date. The absolute_time format is specified in the following format: YYYY-MM-DD-hh:mm:ss The hours must be entered by using a 24-hour clock (for example, 09 for 9 a.m. or 14 for 2 p.m.). The default value is unset. If you set the account expiration date, it is set for all accounts that do not use the –user user_name option. By default, the sec_master user account has a per-user account expiration date of unlimited. If you set the account expiration date to unlimited, do the following actions:Set max-password-age to 0 for unlimited.Set tod-access to anyday:anytime:local.Use the –user user_name option.disable-time-interval {number|unset|disable}Sets the time, in seconds, to disable each user account when the maximum number of login failures is exceeded. Security Access Manager does not impose an upper limit for the maximum number allowed. Use a range from 0 (unlimited) to a number that represents the value that is most logical for the parameter you are trying to set. The default value is 180 seconds.max-concurrent-web-sessions {number|displace|unlimited|unset}Sets the maximum number of concurrent web sessions. This policy applies only to certain components. A web session is a user session that is maintained by a web security solution, such as WebSEAL or the plug-in for web Servers. See the IBM Knowledge Center to determine whether this setting is applicable and whether specific configuration options are required to enforce this policy. This option supports the following values: numberSpecifies the maximum number of concurrent web sessions that can be established. This value is a number that is equal to or greater than one.displaceSpecifies that if a user starts a new web session, any existing web session ends.unlimitedAllows unlimited concurrent web sessions.unsetSpecifies to unset concurrent web session policy.max-login-failures {number|unset}Sets the maximum number of login failures allowed. Security Access Manager does not impose an upper limit for the maximum number allowed. Instead, use a range from zero to a number that represents the value that is most logical for the parameter you are trying to set. If the number is too large, it might render the login policy ineffective. The default value is 10. To enforce maximum login failures, the disable-time-interval parameter must be set. See disable-time-interval for more information about disable-time-interval.max-password-age {unset|relative_time}Sets the maximum time, in days, that a password is valid. This policy is a global password policy as opposed to the individual user policy. The individual user policy: Is set by using the user modify command with the user_name password-valid option.Enables or disables the validity of a password for the specified user account.The relative_time option is relative to the number of days since the last password change occurred. The relative_time format is specified in the following format: DDD-hh:mm:ssThe valid range is from 000–00:00:00 to 999–23:59:59. A value of zero (000–00:00:00) indicates that the password never expires. The default value is 91 days. This value is expressed as 91–00:00:00. max-password-repeated-chars {number|unset}Sets the maximum number of consecutively, repeated characters that are allowed in a password. Security Access Manager does not impose an upper limit on the maximum number allowed. Instead, use a range from 0 to a number that represents the most logical value for the parameter you are trying to set. If the number is too large, it might render the password policy ineffective. The default value is 2. Example: If max-password-repeated-chars is set to 2, then password and pspassword are both valid values. However, passsword is not valid because the character s occurs three times consecutively.min-password-alphas {unset|number}Sets the minimum number of alphabetic characters that are required in a password. Security Access Manager does not impose an upper limit for the minimum number allowed. Instead, use a number that represents the value that is most logical for the parameter you are trying to set. If the number is too small, it might render the password policy ineffective. The default value is 4.min-password-length {unset|number}Sets the minimum password length. Security Access Manager does not impose an upper limit for the minimum number allowed. Instead, use a number that represents the value that is most logical for the parameter you are trying to set. If the number is too large, the password policy might be difficult to adhere to. The default value is 8.min-password-non-alphas {unset|number}Sets the minimum number of non-alphabetic characters that are required in a password. Security Access Manager does not impose an upper limit for the minimum number allowed. Instead, use a number that represents the value that is most logical for the parameter you are trying to set. If the number is too large, the password policy might be difficult to adhere to. The default value is 1.password-spaces {v|no|unset}Sets the policy of whether spaces are allowed in passwords. The default value is unset.tod-access {{anyday|weekday|day_list}:{anytime|time_spec} [:{utc|local}]|unset}Sets the time of day access policy. The day_list is a comma-separated list of days of the week, each of which is represented by a three-character value (for example, mon,wed,fri). The day_list specifies which days of the week you can log in to the account. If you want to list every day of the week, specify anyday; if you do not want to include the weekend days, specify weekday.The time_spec format is specified in the following format: hhmmThe format is expressed by using a 24-hour clock. For example, 0900 for 9 a.m. or 1430 for 2:30 p.m. The default value is unset, and the optional time zone is local by default. The time_spec value and time zone specify the time of day when you can log in to the account.utc=GMTWhen you modify a password policy, you provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.–user user_nameSpecifies the user whose policy information is to be set. If this option is not specified, the general policy is set. For any specified policy, if a user has a specific policy that is applied, this specific policy takes precedence over any general policy that might also be defined. The precedence applies regardless of whether the specific policy is more or less restrictive than the general policy. A valid user name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.Examples of user names are dlucas, sec_master, and "Mary Jones". (Optional) Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example sets the account expiration date of December 30, 1999, at 11:30 p.m. for the specified user dlucas: pdadmin sec_master> policy set account-expiry-date 1999-12-30-23:30:00 -user dlucasThe following example sets the maximum password age of 31 days, 8 hours, 30 minutes, and 0 seconds for the specified user dlucas: pdadmin sec_master> policy set max-password-age 031-08:30:00 -user dlucasThe following example sets the maximum of 12 concurrent web sessions: pdadmin sec_master> policy set max-c 12 See alsopolicy getDisplays the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

policy set

Sets the policy for user passwords, account rules, and conditions. Requires authentication (administrator ID and password) to use this command.

Syntax

policy set account-expiry-date {unlimited|absolute_time|unset} [–user user_name]

policy set disable-time-interval {number|unset|disable} [–user user_name]

policy set max-concurrent-web-sessions {number|displace|unlimited|unset} [–user user_name]

policy set max-login-failures {number|unset} [–user user_name]

policy set max-password-age {unset|relative_time} [–user user_name]

policy set max-password-repeated-chars {number|unset} [–user user_name]

policy set min-password-alphas {unset|number} [–user user_name]

policy set min-password-length {unset|number} [–user user_name]

policy set min-password-non-alphas {unset|number} [–user user_name]

policy set password-spaces {v|no|unset} [–user user_name]

policy set tod-access {{anyday|weekday|day_list}:{anytime|time_spec} [:{utc|local}]|unset} [–user user_name]

Description

The valid range for numbers can be any number. However, use a reasonable number for the task that you want to complete. For example, a minimum password length must be long enough to protect your system. In addition, the password must not be so short as to make it easy for someone to determine your password by trying different combinations.

When you define the password policy, ensure that this definition complies with the password policy of the underlying operating systems and user registries.

Options

account-expiry-date {unlimited|absolute_time|unset}

Sets the account expiration date. The absolute_time format is specified in the following format:

YYYY-MM-DD-hh:mm:ss

The hours must be entered by using a 24-hour clock (for example, 09 for 9 a.m. or 14 for 2 p.m.). The default value is unset.

If you set the account expiration date, it is set for all accounts that do not use the –user user_name option. By default, the sec_master user account has a per-user account expiration date of unlimited. If you set the account expiration date to unlimited, do the following actions:

Set max-password-age to 0 for unlimited.

Set tod-access to anyday:anytime:local.

Use the –user user_name option.

disable-time-interval {number|unset|disable}

Sets the time, in seconds, to disable each user account when the maximum number of login failures is exceeded. Security Access Manager does not impose an upper limit for the maximum number allowed. Use a range from 0 (unlimited) to a number that represents the value that is most logical for the parameter you are trying to set. The default value is 180 seconds.

max-concurrent-web-sessions {number|displace|unlimited|unset}

Sets the maximum number of concurrent web sessions. This policy applies only to certain components. A web session is a user session that is maintained by a web security solution, such as WebSEAL or the plug-in for web Servers. See the IBM Knowledge Center to determine whether this setting is applicable and whether specific configuration options are required to enforce this policy.

This option supports the following values:

number

Specifies the maximum number of concurrent web sessions that can be established. This value is a number that is equal to or greater than one.

displace

Specifies that if a user starts a new web session, any existing web session ends.

unlimited

Allows unlimited concurrent web sessions.

unset

Specifies to unset concurrent web session policy.

max-login-failures {number|unset}

Sets the maximum number of login failures allowed. Security Access Manager does not impose an upper limit for the maximum number allowed. Instead, use a range from zero to a number that represents the value that is most logical for the parameter you are trying to set. If the number is too large, it might render the login policy ineffective. The default value is 10.

To enforce maximum login failures, the disable-time-interval parameter must be set. See disable-time-interval for more information about disable-time-interval.

max-password-age {unset|relative_time}

Sets the maximum time, in days, that a password is valid. This policy is a global password policy as opposed to the individual user policy. The individual user policy:

Is set by using the user modify command with the user_name password-valid option.

Enables or disables the validity of a password for the specified user account.

The relative_time option is relative to the number of days since the last password change occurred. The relative_time format is specified in the following format:

DDD-hh:mm:ss

The valid range is from 000–00:00:00 to 999–23:59:59. A value of zero (000–00:00:00) indicates that the password never expires. The default value is 91 days. This value is expressed as 91–00:00:00.

max-password-repeated-chars {number|unset}

Sets the maximum number of consecutively, repeated characters that are allowed in a password. Security Access Manager does not impose an upper limit on the maximum number allowed. Instead, use a range from 0 to a number that represents the most logical value for the parameter you are trying to set. If the number is too large, it might render the password policy ineffective. The default value is 2.

Example: If max-password-repeated-chars is set to 2, then password and pspassword are both valid values. However, passsword is not valid because the character s occurs three times consecutively.

min-password-alphas {unset|number}

Sets the minimum number of alphabetic characters that are required in a password. Security Access Manager does not impose an upper limit for the minimum number allowed. Instead, use a number that represents the value that is most logical for the parameter you are trying to set. If the number is too small, it might render the password policy ineffective. The default value is 4.

min-password-length {unset|number}

Sets the minimum password length. Security Access Manager does not impose an upper limit for the minimum number allowed. Instead, use a number that represents the value that is most logical for the parameter you are trying to set. If the number is too large, the password policy might be difficult to adhere to. The default value is 8.

min-password-non-alphas {unset|number}

Sets the minimum number of non-alphabetic characters that are required in a password. Security Access Manager does not impose an upper limit for the minimum number allowed. Instead, use a number that represents the value that is most logical for the parameter you are trying to set. If the number is too large, the password policy might be difficult to adhere to. The default value is 1.

password-spaces {v|no|unset}

Sets the policy of whether spaces are allowed in passwords. The default value is unset.

tod-access {{anyday|weekday|day_list}:{anytime|time_spec} [:{utc|local}]|unset}

Sets the time of day access policy.

The day_list is a comma-separated list of days of the week, each of which is represented by a three-character value (for example, mon,wed,fri). The day_list specifies which days of the week you can log in to the account. If you want to list every day of the week, specify anyday; if you do not want to include the weekend days, specify weekday.

The time_spec format is specified in the following format:

hhmm

The format is expressed by using a 24-hour clock. For example, 0900 for 9 a.m. or 1430 for 2:30 p.m. The default value is unset, and the optional time zone is local by default. The time_spec value and time zone specify the time of day when you can log in to the account.

Note:

utc=GMT

When you modify a password policy, you provide a list of days, start time, and end time. The start time and end time apply to each day on the list. If the specified start time is greater than the specified end time, then the access is allowed until the specified end time of the next day.

–user user_name

Specifies the user whose policy information is to be set. If this option is not specified, the general policy is set. For any specified policy, if a user has a specific policy that is applied, this specific policy takes precedence over any general policy that might also be defined. The precedence applies regardless of whether the specific policy is more or less restrictive than the general policy.

A valid user name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set.

Examples of user names are dlucas, sec_master, and "Mary Jones". (Optional)

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example sets the account expiration date of December 30, 1999, at 11:30 p.m. for the specified user dlucas:

pdadmin sec_master> policy set account-expiry-date 1999-12-30-23:30:00
-user dlucas

The following example sets the maximum password age of 31 days, 8 hours, 30 minutes, and 0 seconds for the specified user dlucas:

pdadmin sec_master> policy set max-password-age 031-08:30:00 -user dlucas

The following example sets the maximum of 12 concurrent web sessions:

pdadmin sec_master> policy set max-c 12

See also

policy get

Parent topic: pdadmin commands

pop attachpop attachpop attachAttaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached. protected object policy (POP) commandspop attachattachprotected object policy (POP)Requires authentication (administrator ID and password) to use this command.Syntaxpop attach object_name pop_name DescriptionAt most, one POP can be attached to a given protected object. If the object already has a POP attached to it, the specified POP replaces the existing one. The same POP can be attached to multiple protected objects. Ensure that the protected object exists in the protected object space before you attempt to attach a POP. Optionsobject_nameSpecifies the name of the protected object to which the protected object policy is attached. The object must exist, or an error is displayed. Examples of object names are:/Management/Groups/Travel/WebSEAL/Managementpop_nameSpecifies the name of the protected object policy to be attached. The POP must exist, or an error is displayed. Examples of POP names are poptest and pop1. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example attaches the POP pop1 to the protected object named /Management/test-object: pdadmin sec_master> pop attach /Management/test-object pop1The following example attaches the POP poptest to the protected object named /Test-Space: pdadmin sec_master> pop attach /Test-Space poptest See alsopop createCreates a protected object policy (POP). pop detachDetaches a protected object policy (POP) from the specified protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop attach

Attaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached.

Requires authentication (administrator ID and password) to use this command.

Syntax

pop attach object_name pop_name

Description

At most, one POP can be attached to a given protected object. If the object already has a POP attached to it, the specified POP replaces the existing one. The same POP can be attached to multiple protected objects. Ensure that the protected object exists in the protected object space before you attempt to attach a POP.

Options

object_name

Specifies the name of the protected object to which the protected object policy is attached. The object must exist, or an error is displayed.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

pop_name

Specifies the name of the protected object policy to be attached. The POP must exist, or an error is displayed.

Examples of POP names are poptest and pop1.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example attaches the POP pop1 to the protected object named /Management/test-object:

pdadmin sec_master> pop attach /Management/test-object pop1

The following example attaches the POP poptest to the protected object named /Test-Space:

pdadmin sec_master> pop attach /Test-Space poptest

See also

pop create

pop detach

Parent topic: pdadmin commands

pop createpop createpop createCreates a protected object policy (POP). protected object policy (POP) commandspop createRequires authentication (administrator ID and password) to use this command.Syntaxpop create pop_name Optionspop_nameSpecifies the name of the POP to be created. A valid protected object policy name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. Avoid the following characters in the POP name: ! " # & ( ) * + , ; : < > = @ / \ | .Although a POP name can contain 1 or more of these characters, the results of using such a POP are undefined.Examples of POP names are poptest and pop1. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example shows how to create and display a POP: pdadmin sec_master> pop create test The new POP contains new POP settings like: pdadmin sec_master> pop show test Protected object policy:test Description: Warning:no Audit Level:none Quality of protection: none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime: local IP Endpoint Authentication Method Policy Any Other Network 0 See alsopop attachAttaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached. pop deleteDeletes the specified protected object policy (POP). pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop create

Creates a protected object policy (POP).

Requires authentication (administrator ID and password) to use this command.

Syntax

pop create pop_name

Options

pop_name

Specifies the name of the POP to be created. A valid protected object policy name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed. Avoid the following characters in the POP name:

! " # & ( ) * + , ; : < > = @ / \ | .

Note: Although a POP name can contain 1 or more of these characters, the results of using such a POP are undefined.

Examples of POP names are poptest and pop1.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example shows how to create and display a POP:

pdadmin sec_master> pop create test

The new POP contains new POP settings like:

pdadmin sec_master> pop show test

Protected object policy:test
Description:
Warning:no
Audit Level:none
Quality of protection: none
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime: local
IP Endpoint Authentication Method Policy
Any Other Network 0

See also

pop attach

pop delete

Parent topic: pdadmin commands

pop deletepop deletepop deleteDeletes the specified protected object policy (POP). protected object policy (POP) commandspop deleteRequires authentication (administrator ID and password) to use this command.Syntaxpop delete pop_name Optionspop_nameSpecifies the name of the POP to be deleted. The POP must exist, or an error is displayed. Examples of POP names are poptest and pop1. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the POP pop1: pdadmin sec_master> pop delete pop1The following example deletes the POP poptest: pdadmin sec_master> pop delete poptest See alsopop createCreates a protected object policy (POP). pop detachDetaches a protected object policy (POP) from the specified protected object. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop delete

Deletes the specified protected object policy (POP).

Requires authentication (administrator ID and password) to use this command.

Syntax

pop delete pop_name

Options

pop_name

Specifies the name of the POP to be deleted. The POP must exist, or an error is displayed. Examples of POP names are poptest and pop1.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the POP pop1:

pdadmin sec_master> pop delete pop1

The following example deletes the POP poptest:

pdadmin sec_master> pop delete poptest

See also

pop create

pop detach

Parent topic: pdadmin commands

pop detachpop detachpop detachDetaches a protected object policy (POP) from the specified protected object. protected object policy (POP) commandspop detachRequires authentication (administrator ID and password) to use this command.Syntaxpop detach object_name Optionsobject_nameSpecifies the protected object from which the POP is to be detached. The object must exist and have a POP attached, or an error is displayed. Examples of object names are:/Management/Groups/Travel/WebSEAL/Management Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example detaches all POPs from the protected object named /Management/test-object: pdadmin sec_master> pop detach /Management/test-objectThe following example detaches all POPs from the protected object named /Test-Space: pdadmin sec_master> pop detach /Test-Space See alsopop attachAttaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached. pop deleteDeletes the specified protected object policy (POP). pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop detach

Detaches a protected object policy (POP) from the specified protected object.

Requires authentication (administrator ID and password) to use this command.

Syntax

pop detach object_name

Options

object_name

Specifies the protected object from which the POP is to be detached. The object must exist and have a POP attached, or an error is displayed.

Examples of object names are:

/Management/Groups/Travel

/WebSEAL

/Management

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example detaches all POPs from the protected object named /Management/test-object:

pdadmin sec_master> pop detach /Management/test-object

The following example detaches all POPs from the protected object named /Test-Space:

pdadmin sec_master> pop detach /Test-Space

See also

pop attach

pop delete

Parent topic: pdadmin commands

pop findpop findpop findFinds and lists all protected objects that have a protected object policy (POP) attached. protected object policy (POP) commandspop findRequires authentication (administrator ID and password) to use this command.Syntaxpop find pop_name DescriptionA user must have the browse (b) and view (v) permissions for the object to be listed when the object show command is issued. Otherwise, an error is returned: The user is not authorized to view one or more protected objects where the requested POP is attached. Optionspop_nameSpecifies the name of the POP for which to search. The POP must exist, or an error is displayed. Examples of POP names are poptest and pop1. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example finds all objects to which the POP pop1 is attached: pdadmin sec_master> pop find pop1 /Management/test-objectThe following example finds all objects to which the POP poptest is attached: pdadmin sec_master> pop find poptest /Test-Space See alsopop listLists all protected object policies that are created. Alternatively, lists all extended attributes that are associated with a protected object policy. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop find

Finds and lists all protected objects that have a protected object policy (POP) attached.

Requires authentication (administrator ID and password) to use this command.

Syntax

pop find pop_name

Description

A user must have the browse (b) and view (v) permissions for the object to be listed when the object show command is issued. Otherwise, an error is returned:

The user is not authorized to view one or more protected objects where the
requested POP is attached.

Options

pop_name

Specifies the name of the POP for which to search. The POP must exist, or an error is displayed. Examples of POP names are poptest and pop1.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example finds all objects to which the POP pop1 is attached:

pdadmin sec_master> pop find pop1

/Management/test-object

The following example finds all objects to which the POP poptest is attached:

pdadmin sec_master> pop find poptest

/Test-Space

See also

pop list

Parent topic: pdadmin commands

pop listpop listpop listLists all protected object policies that are created. Alternatively, lists all extended attributes that are associated with a protected object policy. protected object policy (POP) commandspop listRequires authentication (administrator ID and password) to use this command.Syntaxpop list [pop_name attribute] Optionspop_name attributeSpecifies the POP for which to list the attributes. The POP must exist, or an error is displayed. (Optional)Examples of POP names are poptest and pop1. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example shows how to list all POPs: pdadmin sec_master> pop list test pop1 poptestThe following example shows how to list all the attributes for the POP named pop1: pdadmin sec_master> pop list pop1 attribute attr1 See alsopop findFinds and lists all protected objects that have a protected object policy (POP) attached. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop list

Lists all protected object policies that are created. Alternatively, lists all extended attributes that are associated with a protected object policy.

Requires authentication (administrator ID and password) to use this command.

Syntax

pop list [pop_name attribute]

Options

pop_name attribute

Specifies the POP for which to list the attributes. The POP must exist, or an error is displayed. (Optional)

Examples of POP names are poptest and pop1.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example shows how to list all POPs:

pdadmin sec_master> pop list

test
pop1
poptest

The following example shows how to list all the attributes for the POP named pop1:

pdadmin sec_master> pop list pop1 attribute

attr1

See also

pop find

Parent topic: pdadmin commands

pop modifypop modifypop modifyModifies protected object policies. protected object policy (POP) commandspop modifyRequires authentication (administrator ID and password) to use this command.Syntaxpop modify pop_name delete attribute attribute_name [attribute_value]pop modify pop_name set attribute attribute_name attribute_value pop modify pop_name set audit-level {all|none|audit_level_list}pop modify pop_name set description descriptionpop modify pop_name set ipauth add network netmask levelpop modify pop_name set ipauth anyothernw levelpop modify pop_name set ipauth remove network netmaskpop modify pop_name set qop {none|integrity|privacy}pop modify pop_name set tod-access {anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}] pop modify pop_name set warning {yes|no} DescriptionThe pop modify command modifies a protected object policy (POP). When you use the set ipauth add or set ipauth remove options, you can specify the IP addresses. The values for the network and netmask options are TCP/IP addresses. These IP addresses can be specified by using either version 4 (IPv4) or version 6 (IPv6) notation. Both the network and netmask options must be specified in the same IP version.When you use IPv6 notation, do not use prefix notation when you specify IP addresses.When you specify IP addresses, be aware of the following restrictions: For administration commands, IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.For C APIs, IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.For C APIs, IPv6 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.For Java methods, IPv4 and IPv6 clients must provide addresses in IPv4 format to IPv4 servers.For Java methods, IPv4 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.For an IPv6 address to be accepted (commands, C APIs, and Java methods), the server must be IPv6. You cannot provide an IPv6 address to an IPv4 server.The operating system functions that are provided to Security Access Manager have certain limitations. Regardless of C or Java clients, IPv4 addresses must be in IPv4 format when you add addresses to a POP. Optionsdelete attribute attribute_name [attribute_value]Deletes the specified value from the specified extended attribute key in the specified POP. The attribute must exist, or an error is displayed. The optional attribute_value deletes the specified value from the specified extended attribute key in the specified POP.Examples of extended attribute names and values: Dept_No445 Employee_Name"Diana Lucas"pop_nameSpecifies the name of the protected object policy to be modified. The POP must exist, or an error is displayed.set attribute attribute_name attribute_value Sets or modifies the specified value from the specified extended attribute key in the specified POP. If the attribute exists, the attribute value is added as an additional value if the same value does not exist for this attribute. If the same value exists for this attribute, it does not get added again (duplicate values are not allowed), and no error is returned. The attribute_value sets the specified value from the specified extended attribute key in the specified POP.Example: "Credit Card"set audit-level {all|none|audit_level_list}Sets the audit level for the specified POP. The format of an audit_level_list is a comma-separated list that contains one or more of these audit levels: permit,deny,error,admin.set description descriptionSets the description of the specified POP.A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.Example of description: "Policies of Jenson Corp."set ipauth add network netmask levelSets the IP endpoint authentication settings in the specified POP. The values for the network and netmask options are TCP/IP addresses. These IP addresses can be specified by using either version 4 (IPv4) or version 6 (IPv6) addresses. Both the network and netmask options must be specified in the same IP version. The following values are supported for level: forbiddenA value that prohibits object access.integer_valuesApplication-specific integer values that define the step-up authentication levels. All integer values, except 1000, are supported. For more information about step-up authentication, see the Administering topics in the IBM Knowledge Center. set ipauth anyothernw levelSets the anyothernw (any other network setting) for the IP authentication level in the specified POP. If controlling access by IP address is not important, use the anyothernw option to set the authentication level for: All IP addresses, andIP address ranges not listed explicitly in the POP.The following values are supported for level: forbiddenA value that prohibits object access.integer_valuesApplication-specific integer values that define the step-up authentication levels. All integer values, except 1000, are supported. For more information about step-up authentication, see the Administering topics in the IBM Knowledge Center. set ipauth remove network netmaskRemoves the IP endpoint authentication settings from the specified POP. The values for the network and netmask options are TCP/IP addresses. These IP addresses can be specified by using either version 4 (IPv4) or version 6 (IPv6) notation. Both the network and netmask options must be specified in the same IP version.set qop {none|integrity|privacy} Sets the quality of protection level for the specified POP. The following string values are supported: noneintegrityprivacy set tod-access {anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}] Sets the time of day range for the specified protected object policy. The day_list is a comma-separated list of days of the week, each of which is represented by a three-character value (for example, mon,wed,fri). The day_list specifies which days of the week the object can be accessed. If you want to list every day of the week, specify anyday; if you do not want to include the weekend days, specify weekday.The time_spec format is specified as hhmm and is expressed by using a 24-hour clock (for example, 0900 for 9 a.m. or 1430 for 2:30 p.m.). The default value is not defined, and the optional time zone is local by default. The time_spec value and time zone specify the time of day the object can be accessed.utc=GMTset warning {yes|no}Sets the warning mode for the specified protected object policy. Valid values are yes or no. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThis example shows how to modify the description for the POP named test: pdadmin sec_master> pop modify test description "Test POP"This example shows how to turn on the warning mode for the POP named test: pdadmin sec_master> pop modify test set warning yesThis example shows how to set the audit level to audit all requests on a protected object that result in successful: Access by using permit.Denial of access by using deny.pdadmin sec_master> pop modify test set audit-level permit,denyThis example shows how to set an attribute named attr1 with a value of valueA for the POP named pop1: pdadmin sec_master> pop modify pop1 set attribute attr1 valueA See alsopop attachAttaches a protected object policy (POP) to the specified protected object. The POP must be created before it can be attached. pop createCreates a protected object policy (POP). pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop modify

Modifies protected object policies.

Requires authentication (administrator ID and password) to use this command.

Syntax

pop modify pop_name delete attribute attribute_name [attribute_value]

pop modify pop_name set attribute attribute_name attribute_value

pop modify pop_name set audit-level {all|none|audit_level_list}

pop modify pop_name set description description

pop modify pop_name set ipauth add network netmask level

pop modify pop_name set ipauth anyothernw level

pop modify pop_name set ipauth remove network netmask

pop modify pop_name set qop {none|integrity|privacy}

pop modify pop_name set tod-access {anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}]

pop modify pop_name set warning {yes|no}

Description

The pop modify command modifies a protected object policy (POP). When you use the set ipauth add or set ipauth remove options, you can specify the IP addresses. The values for the network and netmask options are TCP/IP addresses. These IP addresses can be specified by using either version 4 (IPv4) or version 6 (IPv6) notation. Both the network and netmask options must be specified in the same IP version.

Note: When you use IPv6 notation, do not use prefix notation when you specify IP addresses.

When you specify IP addresses, be aware of the following restrictions:

For administration commands, IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.

For C APIs, IPv4 clients must provide addresses in IPv4 format even with IPv6 servers.

For C APIs, IPv6 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.

For Java™ methods, IPv4 and IPv6 clients must provide addresses in IPv4 format to IPv4 servers.

For Java methods, IPv4 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.

For an IPv6 address to be accepted (commands, C APIs, and Java methods), the server must be IPv6. You cannot provide an IPv6 address to an IPv4 server.

The operating system functions that are provided to Security Access Manager have certain limitations. Regardless of C or Java clients, IPv4 addresses must be in IPv4 format when you add addresses to a POP.

Options

delete attribute attribute_name [attribute_value]

Deletes the specified value from the specified extended attribute key in the specified POP. The attribute must exist, or an error is displayed.

The optional attribute_value deletes the specified value from the specified extended attribute key in the specified POP.

Examples of extended attribute names and values:

Dept_No445
Employee_Name"Diana Lucas"

pop_name

Specifies the name of the protected object policy to be modified. The POP must exist, or an error is displayed.

set attribute attribute_name attribute_value

Sets or modifies the specified value from the specified extended attribute key in the specified POP. If the attribute exists, the attribute value is added as an additional value if the same value does not exist for this attribute. If the same value exists for this attribute, it does not get added again (duplicate values are not allowed), and no error is returned.

The attribute_value sets the specified value from the specified extended attribute key in the specified POP.

Example: "Credit Card"

set audit-level {all|none|audit_level_list}

Sets the audit level for the specified POP. The format of an audit_level_list is a comma-separated list that contains one or more of these audit levels: permit,deny,error,admin.

set description description

Sets the description of the specified POP.

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. You can specify an empty string ("") to clear an existing description.

Example of description: "Policies of Jenson Corp."

set ipauth add network netmask level

Sets the IP endpoint authentication settings in the specified POP. The values for the network and netmask options are TCP/IP addresses. These IP addresses can be specified by using either version 4 (IPv4) or version 6 (IPv6) addresses. Both the network and netmask options must be specified in the same IP version.

The following values are supported for level:

forbidden

A value that prohibits object access.

integer_values

Application-specific integer values that define the step-up authentication levels. All integer values, except 1000, are supported. For more information about step-up authentication, see the Administering topics in the IBM Knowledge Center.

set ipauth anyothernw level

Sets the anyothernw (any other network setting) for the IP authentication level in the specified POP. If controlling access by IP address is not important, use the anyothernw option to set the authentication level for:

All IP addresses, and

IP address ranges not listed explicitly in the POP.

The following values are supported for level:

forbidden

A value that prohibits object access.

integer_values

Application-specific integer values that define the step-up authentication levels. All integer values, except 1000, are supported. For more information about step-up authentication, see the Administering topics in the IBM Knowledge Center.

set ipauth remove network netmask

Removes the IP endpoint authentication settings from the specified POP. The values for the network and netmask options are TCP/IP addresses. These IP addresses can be specified by using either version 4 (IPv4) or version 6 (IPv6) notation. Both the network and netmask options must be specified in the same IP version.

set qop {none|integrity|privacy}

Sets the quality of protection level for the specified POP. The following string values are supported:

none

integrity

privacy

set tod-access {anyday|weekday|day_list}:{anytime|time_spec-time_spec}[:{utc|local}]

Sets the time of day range for the specified protected object policy.

The day_list is a comma-separated list of days of the week, each of which is represented by a three-character value (for example, mon,wed,fri). The day_list specifies which days of the week the object can be accessed. If you want to list every day of the week, specify anyday; if you do not want to include the weekend days, specify weekday.

The time_spec format is specified as hhmm and is expressed by using a 24-hour clock (for example, 0900 for 9 a.m. or 1430 for 2:30 p.m.). The default value is not defined, and the optional time zone is local by default. The time_spec value and time zone specify the time of day the object can be accessed.

Note: utc=GMT

set warning {yes|no}

Sets the warning mode for the specified protected object policy. Valid values are yes or no.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

This example shows how to modify the description for the POP named test:

pdadmin sec_master> pop modify test description "Test POP"

This example shows how to turn on the warning mode for the POP named test:

pdadmin sec_master> pop modify test set warning yes

This example shows how to set the audit level to audit all requests on a protected object that result in successful:

Access by using permit.

Denial of access by using deny.

pdadmin sec_master> pop modify test set audit-level permit,deny

This example shows how to set an attribute named attr1 with a value of valueA for the POP named pop1:

pdadmin sec_master> pop modify pop1 set attribute attr1 valueA

See also

pop attach

pop create

Parent topic: pdadmin commands

pop showpop showpop showShows details about the protected object policy (POP). Alternatively, displays the values for the specified extended attribute from the specified protected object policy. protected object policy (POP) commandspop showRequires authentication (administrator ID and password) to use this command.Syntaxpop show pop_name [attribute attribute_name] Optionsattribute attribute_nameSpecifies the name of the extended attribute whose values you want to display. The attribute must exist, or an error is displayed. Examples of attribute names are Dept_No and Employee_Name. (Optional)pop_nameSpecifies the POP to display. The POP must exist, or an error is displayed. Examples of POP names are poptest and pop1. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. Examples The following example shows how to show POP information, including the description: pdadmin sec_master> pop show test Protected object policy:test Description:Test POP Warning:no Audit level:none Quaility of protection:none Time of day access: sun, mon, tue, wed, thu, fri, sat: anytime: local IP Endpoint Authentication Method Policy Any Other Network 0The following example shows attribute attr1 information for the POP named pop1: pdadmin sec_master> pop show pop1 attribute attr attr1 valueA See alsopop findFinds and lists all protected objects that have a protected object policy (POP) attached. pop listLists all protected object policies that are created. Alternatively, lists all extended attributes that are associated with a protected object policy. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

pop show

Shows details about the protected object policy (POP). Alternatively, displays the values for the specified extended attribute from the specified protected object policy.

Requires authentication (administrator ID and password) to use this command.

Syntax

pop show pop_name [attribute attribute_name]

Options

attribute attribute_name

Specifies the name of the extended attribute whose values you want to display. The attribute must exist, or an error is displayed. Examples of attribute names are Dept_No and Employee_Name. (Optional)

pop_name

Specifies the POP to display. The POP must exist, or an error is displayed. Examples of POP names are poptest and pop1.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example shows how to show POP information, including the description:

pdadmin sec_master> pop show test

Protected object policy:test
Description:Test POP
Warning:no
Audit level:none
Quaility of protection:none
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime: local
IP Endpoint Authentication Method Policy
Any Other Network 0

The following example shows attribute attr1 information for the POP named pop1:

pdadmin sec_master> pop show pop1 attribute attr

attr1
valueA

See also

pop find

pop list

Parent topic: pdadmin commands

rsrc creatersrc creatersrc createCreates and names a web server single sign-on resource. resource commandsrsrc createRequires authentication (administrator ID and password) to use this command.Syntaxrsrc create resource_name [–desc description] DescriptionA web resource is a web server that serves as the back-end of a WebSEAL GSO-enabled junction. The web resource name must be specified with the –T option when the GSO-enabled WebSEAL junction is created. Options–desc descriptionSpecifies a description for the resource. Descriptions containing a space must be enclosed in double quotation marks. (Optional)A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks.Examples of descriptions are “Engineering Web server – Room 4807” and “Printer in room 345, Bldg 2”.resource_nameSpecifies the name of the resource to be created. A valid resource name is an alphanumeric string that is not case-sensitive. If the resource is a GSO resource, certain characters are not allowed. See Characters disallowed for GSO namesCertain characters are disallowed for GSO names. for the list of these characters.Examples of resource names are engwebs01 and JonesData. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example is entered as one line. This example creates and names a web resource engwebs01 with an associated description "Engineering Web server – Room 4807": pdadmin sec_master> rsrc create engwebs01 –desc "Engineering Web server – Room 4807"The following example is entered as one line. This example creates and names a printer resource "Mary Jones Printer" with an associated description "Printer in room 345, Bldg 2": pdadmin sec_master> rsrc create "Mary Jones Printer" –desc "Printer in room 345, Bldg 2" See alsorsrc deleteDeletes the specified single sign-on resource. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrc create

Creates and names a web server single sign-on resource.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrc create resource_name [–desc description]

Description

A web resource is a web server that serves as the back-end of a WebSEAL GSO-enabled junction. The web resource name must be specified with the –T option when the GSO-enabled WebSEAL junction is created.

Options

–desc description

Specifies a description for the resource. Descriptions containing a space must be enclosed in double quotation marks. (Optional)

A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks.

Examples of descriptions are “Engineering Web server – Room 4807” and “Printer in room 345, Bldg 2”.

resource_name

Specifies the name of the resource to be created.

A valid resource name is an alphanumeric string that is not case-sensitive. If the resource is a GSO resource, certain characters are not allowed. See Characters disallowed for GSO names for the list of these characters.

Examples of resource names are engwebs01 and JonesData.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example is entered as one line. This example creates and names a web resource engwebs01 with an associated description "Engineering Web server – Room 4807":

pdadmin sec_master> rsrc create engwebs01 –desc "Engineering Web
server – Room 4807"

The following example is entered as one line. This example creates and names a printer resource "Mary Jones Printer" with an associated description "Printer in room 345, Bldg 2":

pdadmin sec_master> rsrc create "Mary Jones Printer" –desc "Printer in
room 345, Bldg 2"

See also

rsrc delete

Parent topic: pdadmin commands

rsrc deletersrc deletersrc deleteDeletes the specified single sign-on resource. resource commandsrsrc deleteRequires authentication (administrator ID and password) to use this command.Syntaxrsrc delete resource_name Optionsresource_nameSpecifies the name of the resource to be deleted. The resource must exist, or an error is displayed. Examples of resource names are engwebs01 and JonesData. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the named resource engwebs01: pdadmin sec_master> rsrc delete engwebs01The following example deletes the named resource "Mary Jones Printer": pdadmin sec_master> rsrc delete "Mary Jones Printer" See alsorsrc createCreates and names a web server single sign-on resource. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrc delete

Deletes the specified single sign-on resource.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrc delete resource_name

Options

resource_name

Specifies the name of the resource to be deleted. The resource must exist, or an error is displayed.

Examples of resource names are engwebs01 and JonesData.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the named resource engwebs01:

pdadmin sec_master> rsrc delete engwebs01

The following example deletes the named resource "Mary Jones Printer":

pdadmin sec_master> rsrc delete "Mary Jones Printer"

See also

rsrc create

Parent topic: pdadmin commands

rsrc listrsrc listrsrc listReturns a list of all the single sign-on resource names. resource commandsrsrc listrsrc, listRequires authentication (administrator ID and password) to use this command.Syntaxrsrc list OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example returns a list of all the single sign-on web resource names: pdadmin sec_master> rsrc listThe output is like: engwebs01 Mary Jones Printer See alsorsrc createCreates and names a web server single sign-on resource. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrc list

Returns a list of all the single sign-on resource names.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrc list

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example returns a list of all the single sign-on web resource names:

pdadmin sec_master> rsrc list

The output is like:

engwebs01
Mary Jones Printer

See also

rsrc create

Parent topic: pdadmin commands

rsrc showrsrc showrsrc showDisplays the resource information for the named resource. resource commandsrsrc showRequires authentication (administrator ID and password) to use this command.Syntaxrsrc show resource_name Optionsresource_nameSpecifies the name of the resource for which information is shown. The resource must exist, or an error is displayed. Examples of resource names are engwebs01 and JonesData. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example returns information for the specified resource engwebs01: pdadmin sec_master> rsrc show engwebs01 The output is like: Web Resource Name: engwebs01 Description: Engineering Web server - Room 4807The following example returns information for the specified resource "Mary Jones Printer": pdadmin sec_master> rsrc show "Mary Jones Printer" Output is like: Web Resource Name: Mary Jones Printer Description: Printer in room 345, Bldg 2 See alsorsrc listReturns a list of all the single sign-on resource names. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrc show

Displays the resource information for the named resource.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrc show resource_name

Options

resource_name

Specifies the name of the resource for which information is shown. The resource must exist, or an error is displayed.

Examples of resource names are engwebs01 and JonesData.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example returns information for the specified resource engwebs01:

pdadmin sec_master> rsrc show engwebs01

The output is like:

Web Resource Name: engwebs01
Description: Engineering Web server - Room 4807

The following example returns information for the specified resource "Mary Jones Printer":

pdadmin sec_master> rsrc show "Mary Jones Printer"

Output is like:

Web Resource Name: Mary Jones Printer
Description: Printer in room 345, Bldg 2

See also

rsrc list

Parent topic: pdadmin commands

rsrccred creatersrccred creatersrccred createCreates a single sign-on credential. resource commandsrsrccred createRequires authentication (administrator ID and password) to use this command.Syntaxrsrccred create resource_name rsrcuser resource_userid rsrcpwd resource_password rsrctype {web|group} user user_name DescriptionA resource credential is a credential that is used to identify the authentication information of a user. WebSEAL uses the authentication information when it accesses a back-end web resource or resource group through a GSO-enabled junction. WebSEAL accesses these resources on behalf of that user.For example, a user dlucas might require the authentication identity 4807ws01 and password pwd4lucas when accessing the engwebs01 web resource that is junctioned through WebSEAL.A resource credential can be created with this authentication information. Then, WebSEAL automatically uses this information to access the engwebs01 server whenever the user dlucas accesses that resource. Optionsresource_nameSpecifies the name that is given to the resource or resource group when the resource or resource group was created. The resource or resource group must exist to create the resource credential. If the resource or resource group does not exist or is not specified, an error message is displayed. Examples of resource names are engwebs01 and "Mary Jones Printer".rsrcpwd resource_passwordSpecifies the password for a user at the web server.rsrctype {web|group}Specifies whether the resource type named is web (resource) or group (resource group).rsrcuser resource_useridSpecifies the unique user identification (user ID) for the user at the web server. Examples of user identifications are 4807ws01 and userD4D.user user_nameSpecifies the name of the user for whom the resource credential information applies. If the user does not exist or is not specified, an error message is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates the web resource credential named engwebs01 for the resource user ID 4807ws01 and password pwd4lucas given to user dlucas: pdadmin sec_master> rsrccred create engwebs01 rsrcuser 4807ws01 rsrcpwd pwd4lucas rsrctype web user dlucasThe following example creates the group resource credential named printerusers for the resource user ID userD4D and password pwd4mjones given to user "Mary Jones": pdadmin sec_master> rsrccred create printerusers rsrcuser userD4D rsrcpwd pwd4mjones rsrctype group user "Mary Jones" See alsorsrccred deleteDeletes a single sign-on credential. rsrccred modifyChanges a single sign-on credential. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrccred create

Creates a single sign-on credential.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrccred create resource_name rsrcuser resource_userid rsrcpwd resource_password rsrctype {web|group} user user_name

Description

A resource credential is a credential that is used to identify the authentication information of a user. WebSEAL uses the authentication information when it accesses a back-end web resource or resource group through a GSO-enabled junction. WebSEAL accesses these resources on behalf of that user.

For example, a user dlucas might require the authentication identity 4807ws01 and password pwd4lucas when accessing the engwebs01 web resource that is junctioned through WebSEAL.

A resource credential can be created with this authentication information. Then, WebSEAL automatically uses this information to access the engwebs01 server whenever the user dlucas accesses that resource.

Options

resource_name

Specifies the name that is given to the resource or resource group when the resource or resource group was created. The resource or resource group must exist to create the resource credential. If the resource or resource group does not exist or is not specified, an error message is displayed.

Examples of resource names are engwebs01 and "Mary Jones Printer".

rsrcpwd resource_password

Specifies the password for a user at the web server.

rsrctype {web|group}

Specifies whether the resource type named is web (resource) or group (resource group).

rsrcuser resource_userid

Specifies the unique user identification (user ID) for the user at the web server.

Examples of user identifications are 4807ws01 and userD4D.

user user_name

Specifies the name of the user for whom the resource credential information applies. If the user does not exist or is not specified, an error message is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates the web resource credential named engwebs01 for the resource user ID 4807ws01 and password pwd4lucas given to user dlucas:

pdadmin sec_master> rsrccred create engwebs01 rsrcuser 4807ws01
rsrcpwd pwd4lucas rsrctype web user dlucas

The following example creates the group resource credential named printerusers for the resource user ID userD4D and password pwd4mjones given to user "Mary Jones":

pdadmin sec_master> rsrccred create printerusers rsrcuser userD4D rsrcpwd
pwd4mjones rsrctype group user "Mary Jones"

See also

rsrccred delete

rsrccred modify

Parent topic: pdadmin commands

rsrccred deletersrccred deletersrccred deleteDeletes a single sign-on credential. resource commandsrsrccred deleteRequires authentication (administrator ID and password) to use this command.Syntaxrsrccred delete resource_name rsrctype {web|group} user user_name Optionsresource_nameSpecifies the name that is given to the resource or resource group when the resource was created. The resource or resource group must exist, or an error is displayed. Examples of resource names are engwebs01 and "Mary Jones Printer".rsrctype {web|group}Specifies whether the resource type named is web (resource) or group (resource group) for the single sign-on resource that is associated with the credential. The type of resource must match the resource type that is assigned when the resource or resource group was first created.user user_nameSpecifies the name of the user for whom the resource credential information applies. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example deletes the resource credential information for the resource engwebs01, resource type web, and user name dlucas: pdadmin sec_master> rsrccred delete engwebs01 rsrctype web user dlucasThe following example deletes the resource credential information for the resource printerusers, resource type group, and user name "Mary Jones": pdadmin sec_master> rsrccred delete printerusers rsrctype group user "Mary Jones" See alsorsrccred createCreates a single sign-on credential. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrccred delete

Deletes a single sign-on credential.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrccred delete resource_name rsrctype {web|group} user user_name

Options

resource_name

Specifies the name that is given to the resource or resource group when the resource was created. The resource or resource group must exist, or an error is displayed.

Examples of resource names are engwebs01 and "Mary Jones Printer".

rsrctype {web|group}

Specifies whether the resource type named is web (resource) or group (resource group) for the single sign-on resource that is associated with the credential. The type of resource must match the resource type that is assigned when the resource or resource group was first created.

user user_name

Specifies the name of the user for whom the resource credential information applies. The user must exist, or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example deletes the resource credential information for the resource engwebs01, resource type web, and user name dlucas:

pdadmin sec_master> rsrccred delete engwebs01 rsrctype web user dlucas

The following example deletes the resource credential information for the resource printerusers, resource type group, and user name "Mary Jones":

pdadmin sec_master> rsrccred delete printerusers rsrctype group
user "Mary Jones"

See also

rsrccred create

Parent topic: pdadmin commands

rsrccred list userrsrccred list userrsrccred list userReturns the list of single sign-on credentials for the specified user. The user must exist, or an error is displayed. resource commandsrsrccred list userrsrccred, list userRequires authentication (administrator ID and password) to use this command.Syntaxrsrccred list user user_name Optionsuser_nameSpecifies the name of the user for whom the resource credential information applies. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example returns the list of single sign-on credentials for the specified user dlucas: pdadmin sec_master> rsrccred list user dlucas The output is like: Resource Name: engwebs01 Resource Type: web See alsorsrccred showDisplays the attributes of a single sign-on credential. The credential identifier is composed of a resource name, a resource type, and a user name. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrccred list user

Returns the list of single sign-on credentials for the specified user. The user must exist, or an error is displayed.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrccred list user user_name

Options

user_name

Specifies the name of the user for whom the resource credential information applies. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example returns the list of single sign-on credentials for the specified user dlucas:

pdadmin sec_master> rsrccred list user dlucas

The output is like:

Resource Name: engwebs01
Resource Type: web

See also

rsrccred show

Parent topic: pdadmin commands

rsrccred modifyrsrccred modifyrsrccred modifyChanges a single sign-on credential. resource commandsrsrccred modifyRequires authentication (administrator ID and password) to use this command.Syntaxrsrccred modify resource_name rsrctype {web|group} set [–rsrcuser new_resource_userid [–rsrcpwd new_resource_password]] user user_name Options–rsrcpwd new_resource_passwordSpecifies the new password for a user at the web server. To change or reset the password information, this optional command must be preceded by a dash (-). Specifying this option without specifying the –rsrcpwd option clears both the resource user ID and the resource password from the resource credential. To set the resource password, you must specify both the resource user ID and the resource password. (Optional)–rsrcuser new_resource_useridSpecifies the new unique user identification (user ID) for the user at the web server. To change or reset the resource user ID of the user, this optional command must be preceded by a dash (-). (Optional)A valid new resource user ID is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.Examples of user identifications are 4807ws01 and userD4D.resource_nameSpecifies the name that is given to the resource or resource group when the resource was created. The resource or resource group must exist, or an error is displayed. Examples of resource names are engwebs01 and "Mary Jones Printer".rsrctype {web|group}Specifies whether the resource type named is web (resource) or group (resource group) for the single sign-on resource that is associated with the credential. The type of resource must match the resource type that is assigned when the resource or resource group credential was first created.user user_nameSpecifies the name of the user for whom the resource credential information applies. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example modifies the password of the user dlucas to newrsrpw for the specified resource engwebs01: pdadmin sec_master> rsrccred modify engwebs01 rsrctype web set -rsrcuser 4807ws01 -rsrcpwd newrsrpw user dlucasThe following example, entered as one line, modifies the group resource user ID to user888 for the specified resource printerusers: pdadmin sec_master> rsrccred modify printerusers rsrctype group set -rsrcuser user888 user "Mary Jones" See alsorsrccred createCreates a single sign-on credential. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrccred modify

Changes a single sign-on credential.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrccred modify resource_name rsrctype {web|group} set [–rsrcuser new_resource_userid [–rsrcpwd new_resource_password]] user user_name

Options

–rsrcpwd new_resource_password

Specifies the new password for a user at the web server. To change or reset the password information, this optional command must be preceded by a dash (-). Specifying this option without specifying the –rsrcpwd option clears both the resource user ID and the resource password from the resource credential. To set the resource password, you must specify both the resource user ID and the resource password. (Optional)

–rsrcuser new_resource_userid

Specifies the new unique user identification (user ID) for the user at the web server. To change or reset the resource user ID of the user, this optional command must be preceded by a dash (-). (Optional)

A valid new resource user ID is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

Examples of user identifications are 4807ws01 and userD4D.

resource_name

Specifies the name that is given to the resource or resource group when the resource was created. The resource or resource group must exist, or an error is displayed.

Examples of resource names are engwebs01 and "Mary Jones Printer".

rsrctype {web|group}

Specifies whether the resource type named is web (resource) or group (resource group) for the single sign-on resource that is associated with the credential. The type of resource must match the resource type that is assigned when the resource or resource group credential was first created.

user user_name

Specifies the name of the user for whom the resource credential information applies. The user must exist, or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example modifies the password of the user dlucas to newrsrpw for the specified resource engwebs01:

pdadmin sec_master> rsrccred modify engwebs01 rsrctype web set
-rsrcuser 4807ws01 -rsrcpwd newrsrpw user dlucas

The following example, entered as one line, modifies the group resource user ID to user888 for the specified resource printerusers:

pdadmin sec_master> rsrccred modify printerusers rsrctype group set
-rsrcuser user888 user "Mary Jones"

See also

rsrccred create

Parent topic: pdadmin commands

rsrccred showrsrccred showrsrccred showDisplays the attributes of a single sign-on credential. The credential identifier is composed of a resource name, a resource type, and a user name. resource commandsrsrccred showRequires authentication (administrator ID and password) to use this command.Syntaxrsrccred show resource_name rsrctype {web|group} user user_name Optionsresource_nameSpecifies the name of the single sign-on resource or resource group that is associated with the credential. The resource or resource group must exist, or an error is displayed. Examples of resource names are engwebs01 and printerusers.rsrctype {web|group} Specifies whether the resource type named is web (resource) or group (resource group) for the single sign-on resource that is associated with the credential. The type of resource must match the resource type that is assigned when the resource or resource group was first created.user user_nameSpecifies the name of the user that is associated with this credential. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays the specified single sign-on credential: pdadmin sec_master> rsrccred show engwebs01 rsrctype web user dlucas The output is like: Resource Name: engwebs01 Resource Type: web Resource User Id: dlucasThe following example displays the specified single sign-on credential: pdadmin sec_master> rsrccred show user888 rsrctype group user "Mary Jones" The output is like: Resource Name: printerusers Resource Type: group Resource User Id: Mary Jones See alsorsrccred list userReturns the list of single sign-on credentials for the specified user. The user must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrccred show

Displays the attributes of a single sign-on credential. The credential identifier is composed of a resource name, a resource type, and a user name.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrccred show resource_name rsrctype {web|group} user user_name

Options

resource_name

Specifies the name of the single sign-on resource or resource group that is associated with the credential. The resource or resource group must exist, or an error is displayed.

Examples of resource names are engwebs01 and printerusers.

rsrctype {web|group}

Specifies whether the resource type named is web (resource) or group (resource group) for the single sign-on resource that is associated with the credential. The type of resource must match the resource type that is assigned when the resource or resource group was first created.

user user_name

Specifies the name of the user that is associated with this credential. The user must exist, or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays the specified single sign-on credential:

pdadmin sec_master> rsrccred show engwebs01 rsrctype web user dlucas

The output is like:

Resource Name: engwebs01
Resource Type: web
Resource User Id: dlucas

The following example displays the specified single sign-on credential:

pdadmin sec_master> rsrccred show user888 rsrctype group user "Mary Jones"

The output is like:

Resource Name: printerusers
Resource Type: group
Resource User Id: Mary Jones

See also

rsrccred list user

Parent topic: pdadmin commands

rsrcgroup creatersrcgroup creatersrcgroup createCreates and names a resource group. resource commandsrsrcgroup createRequires authentication (administrator ID and password) to use this command.Syntaxrsrcgroup create resource_group_name [–desc description] DescriptionYou can use a resource group to represent a set of web servers when the sign-on credential for the set of web servers is the same. In this case, web servers are considered resources.For example, if the user dlucas has the same identity for web servers engwebs01 and engwebs02, these resources can be added to a resource group called webs4807. Use the rsrcgroup modify command to add the resources to the group.Then, you can create a single sign-on credential for the webs4807 resource group for dlucas. Then, that single sign-on credential can be used to access all the web servers in the webs4807 group. Options–desc descriptionSpecifies the description to identify this resource group. This parameter is optional. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. (Optional)Examples of descriptions are "Engineering Web server – Room 4807" and "Printer in room 345, Bldg 2".resource_group_nameSpecifies the name of the resource group. A valid resource group name is an alphanumeric string that is not case-sensitive. If the resource is a GSO resource, certain characters are not allowed. See Characters disallowed for GSO namesCertain characters are disallowed for GSO names. for the list of these characters. Examples of resource group names are webs4807, engwebs01, and IBMprinters. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example creates and names a web resource group IBMprinters: pdadmin sec_master> rsrcgroup create IBMprinters The following example creates and names a web resource group named webs4807 and provides a description ("Web servers, Room 4807") for that resource: pdadmin sec_master> rsrcgroup create webs4807 –desc "Web servers, Room 4807" See alsorsrcgroup deleteDeletes a single sign-on resource group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrcgroup create

Creates and names a resource group.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrcgroup create resource_group_name [–desc description]

Description

You can use a resource group to represent a set of web servers when the sign-on credential for the set of web servers is the same. In this case, web servers are considered resources.

For example, if the user dlucas has the same identity for web servers engwebs01 and engwebs02, these resources can be added to a resource group called webs4807. Use the rsrcgroup modify command to add the resources to the group.

Then, you can create a single sign-on credential for the webs4807 resource group for dlucas. Then, that single sign-on credential can be used to access all the web servers in the webs4807 group.

Options

–desc description

Specifies the description to identify this resource group. This parameter is optional. A valid description is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. If the description contains a space, ensure that you enclose the description in double quotation marks. (Optional)

Examples of descriptions are "Engineering Web server – Room 4807" and "Printer in room 345, Bldg 2".

resource_group_name

Specifies the name of the resource group. A valid resource group name is an alphanumeric string that is not case-sensitive. If the resource is a GSO resource, certain characters are not allowed. See Characters disallowed for GSO names for the list of these characters.

Examples of resource group names are webs4807, engwebs01, and IBMprinters.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example creates and names a web resource group IBMprinters:

pdadmin sec_master> rsrcgroup create IBMprinters

The following example creates and names a web resource group named webs4807 and provides a description ("Web servers, Room 4807") for that resource:

pdadmin sec_master> rsrcgroup create webs4807 –desc "Web servers, Room 4807"

See also

rsrcgroup delete

Parent topic: pdadmin commands

rsrcgroup deletersrcgroup deletersrcgroup deleteDeletes a single sign-on resource group. resource commandsrsrcgroup deleteRequires authentication (administrator ID and password) to use this command.Syntaxrsrcgroup delete resource_group_name Optionsresource_group_nameSpecifies the name of the resource group. The resource must exist, or an error is displayed. Examples of resource group names are webs4807, engwebs01, and IBMprinters. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example deletes the named resource group and its associated description information: pdadmin sec_master> rsrcgroup delete webs4807 See alsorsrcgroup createCreates and names a resource group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrcgroup delete

Deletes a single sign-on resource group.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrcgroup delete resource_group_name

Options

resource_group_name

Specifies the name of the resource group. The resource must exist, or an error is displayed.

Examples of resource group names are webs4807, engwebs01, and IBMprinters.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example deletes the named resource group and its associated description information:

pdadmin sec_master> rsrcgroup delete webs4807

See also

rsrcgroup create

Parent topic: pdadmin commands

rsrcgroup listrsrcgroup listrsrcgroup listDisplays the names of all resource groups that are defined in the user registry. resource commandsrsrcgroup listrsrcgroup, listRequires authentication (administrator ID and password) to use this command.Syntaxrsrcgroup list OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example returns a list of all single sign-on resource group names: pdadmin sec_master> rsrcgroup listThe output is like: webs4807 websbld3 See alsorsrcgroup showDisplays the resource group information for the specified resource group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrcgroup list

Displays the names of all resource groups that are defined in the user registry.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrcgroup list

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example returns a list of all single sign-on resource group names:

pdadmin sec_master> rsrcgroup list

The output is like:

webs4807
websbld3

See also

rsrcgroup show

Parent topic: pdadmin commands

rsrcgroup modifyrsrcgroup modifyrsrcgroup modifyAdds or removes a single sign-on resource to or from a single sign-on resource group. resource commandsrsrcgroup modifyRequires authentication (administrator ID and password) to use this command.Syntaxrsrcgroup modify resource_group_name add rsrcname resource_namersrcgroup modify resource_group_name remove rsrcname resource_name Optionsadd rsrcname resource_nameAdds a single sign-on resource to the specified single sign-on resource group. A valid resource name is an alphanumeric string that is not case-sensitive. If the resource is a GSO resource, certain characters are not allowed. See Characters disallowed for GSO namesCertain characters are disallowed for GSO names. for the list of these characters.Examples of resource names are engwebs01 and "Mary Jones Printer".remove rsrcname resource_nameRemoves a single sign-on resource from the specified single sign-on resource group. Examples of resource names are engwebs01 and "Mary Jones Printer".Depending on the LDAP server in your environment, any attempt to remove a non-existing resource from a group, might generate an error.resource_group_nameSpecifies the name of the resource group to be modified. The resource group must exist, or an error is displayed. Examples of resource group names are webs4807, engwebs01, and IBMprinters. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example adds the resource named engwebs02 to the existing web resource group webs4807: pdadmin sec_master> rsrcgroup modify webs4807 add rsrcname engwebs02The following example deletes the resource named engwebs02 from the existing web resource group webs4807: pdadmin sec_master> rsrcgroup modify webs4807 remove rsrcname engwebs02 See alsorsrcgroup createCreates and names a resource group. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrcgroup modify

Adds or removes a single sign-on resource to or from a single sign-on resource group.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrcgroup modify resource_group_name add rsrcname resource_name

rsrcgroup modify resource_group_name remove rsrcname resource_name

Options

add rsrcname resource_name

Adds a single sign-on resource to the specified single sign-on resource group.

A valid resource name is an alphanumeric string that is not case-sensitive. If the resource is a GSO resource, certain characters are not allowed. See Characters disallowed for GSO names for the list of these characters.

Examples of resource names are engwebs01 and "Mary Jones Printer".

remove rsrcname resource_name

Removes a single sign-on resource from the specified single sign-on resource group.

Examples of resource names are engwebs01 and "Mary Jones Printer".

Note: Depending on the LDAP server in your environment, any attempt to remove a non-existing resource from a group, might generate an error.

resource_group_name

Specifies the name of the resource group to be modified. The resource group must exist, or an error is displayed.

Examples of resource group names are webs4807, engwebs01, and IBMprinters.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example adds the resource named engwebs02 to the existing web resource group webs4807:

pdadmin sec_master> rsrcgroup modify webs4807 add rsrcname engwebs02

The following example deletes the resource named engwebs02 from the existing web resource group webs4807:

pdadmin sec_master> rsrcgroup modify webs4807 remove rsrcname engwebs02

See also

rsrcgroup create

Parent topic: pdadmin commands

rsrcgroup showrsrcgroup showrsrcgroup showDisplays the resource group information for the specified resource group. resource commandsrsrcgroup showRequires authentication (administrator ID and password) to use this command.Syntaxrsrcgroup show resource_group_name DescriptionThe resource group name, the resource group description, and a list of all resource group members names are displayed. The resource group members are the individual web resources (servers). Optionsresource_group_nameSpecifies the name of the resource group. Examples of resource group names are webs4807, engwebs01, and IBMprinters. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example returns the specified single sign-on resource group named webs4807: pdadmin sec_master> rsrcgroup show webs4807The output is like: Resource Group Name: webs4807 Description: Web servers, Room 4807 Resource Members: engwebs01 engwebs02 engwebs03 See alsorsrcgroup listDisplays the names of all resource groups that are defined in the user registry. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

rsrcgroup show

Displays the resource group information for the specified resource group.

Requires authentication (administrator ID and password) to use this command.

Syntax

rsrcgroup show resource_group_name

Description

The resource group name, the resource group description, and a list of all resource group members names are displayed. The resource group members are the individual web resources (servers).

Options

resource_group_name

Specifies the name of the resource group.

Examples of resource group names are webs4807, engwebs01, and IBMprinters.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example returns the specified single sign-on resource group named webs4807:

pdadmin sec_master> rsrcgroup show webs4807

The output is like:

Resource Group Name: webs4807
Description: Web servers, Room 4807
Resource Members:
engwebs01
engwebs02
engwebs03

See also

rsrcgroup list

Parent topic: pdadmin commands

server listserver listserver listLists all registered Security Access Manager servers. server commandsserver listserver commandsserver listRequires authentication (administrator ID and password) to use this command.Syntaxserver list DescriptionLists all registered Security Access Manager servers. The name of the server for all server commands must be entered in the exact format as it is displayed in the output of this command. The server list command does not have such a requirement. OptionsNone. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example lists registered servers: pdadmin> server list The output is as follows: ivmgrd-master ivacld-server1 ivacld-server2where ivmgrd-master represents the Policy server; ivacld-server2 and ivacld-server1 represent Authorization server instances. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server list

Lists all registered Security Access Manager servers.

Requires authentication (administrator ID and password) to use this command.

Syntax

server list

Description

Lists all registered Security Access Manager servers. The name of the server for all server commands must be entered in the exact format as it is displayed in the output of this command. The server list command does not have such a requirement.

Options

None.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example lists registered servers:

pdadmin> server list

The output is as follows:

ivmgrd-master
ivacld-server1
ivacld-server2

where ivmgrd-master represents the Policy server; ivacld-server2 and ivacld-server1 represent Authorization server instances.

Parent topic: pdadmin commands

server listtasksserver listtasksserver listtasksRetrieves the list of tasks (commands) available for the specified installed Security Access Manager server or server instance. server commandsserver listtasksserver commandsserver listtasksRequires authentication (administrator ID and password) to use this command.Syntaxserver listtasks server_name-host_name Optionsserver_name-host_nameSpecifies the name of the installed Security Access Manager server or server instance. You must specify the server_name in the exact format as displayed in the output of the server list command. For example, if the configured name of a single WebSEAL server is default, the server_name is default-webseald followed by -host_name. The full server name–host name is default-webseald-cruz.dallas.ibm.com.For multiple server instances on the same computer, if the configured name of a WebSEAL server instance is webseal2-webseald, the instance_name is followed by -host_name. The full server instance name–host name is webseal2-webseald-cruz.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays the list of tasks available from the authorization server: pdadmin sec_master> server listtasks ivacld-mogman.admogman.com The output is like: trace set component level [file path=file| other-log-agent-config] trace show [component] trace list [component] stats show [component] stats list stats on [component] [interval] [count] [file path= file|other-log-agent-config] stats off [component] stats reset [component] stats get [component] You can run the command server listtasks ivmgrd-master to view the list of tasks available from the Policy server. The output is similar to the output listed for the authorization server.The following example displays the list of tasks available from the WebSEAL server default-webseald-cruz: pdadmin sec_master server listtasks default-webseald-cruzThe output is like: dynurl update jmt load jmt clear cache flush all create add remove delete <junction point> list show <junction point> reload terminate all_sessions <user_id> terminate session <user_session_id> refresh all_sessions <user_id> help command trace set component level [file path=file| other-log-agent-config] trace show [component] trace list [component] stats show [component] stats list stats on [component][interval][count] [file path= file|other-log-agent-config] stats off [component] stats reset [component] stats get [component] See alsoserver listLists all registered Security Access Manager servers. server showDisplays the properties for the specified installed Security Access Manager server or server instance. The server must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server listtasks

Retrieves the list of tasks (commands) available for the specified installed Security Access Manager server or server instance.

Requires authentication (administrator ID and password) to use this command.

Syntax

server listtasks server_name-host_name

Options

server_name-host_name

Specifies the name of the installed Security Access Manager server or server instance. You must specify the server_name in the exact format as displayed in the output of the server list command.

For example, if the configured name of a single WebSEAL server is default, the server_name is default-webseald followed by -host_name. The full server name–host name is default-webseald-cruz.dallas.ibm.com.

For multiple server instances on the same computer, if the configured name of a WebSEAL server instance is webseal2-webseald, the instance_name is followed by -host_name. The full server instance name–host name is webseal2-webseald-cruz.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays the list of tasks available from the authorization server:

pdadmin sec_master> server listtasks ivacld-mogman.admogman.com

The output is like:

trace set component level [file path=file|
other-log-agent-config]
trace show [component]
trace list [component]
stats show [component]
stats list
stats on [component] [interval] [count]
[file path= file|other-log-agent-config]
stats off [component]
stats reset [component]
stats get [component]

Note: You can run the command server listtasks ivmgrd-master to view the list of tasks available from the Policy server. The output is similar to the output listed for the authorization server.

The following example displays the list of tasks available from the WebSEAL server default-webseald-cruz:

pdadmin sec_master server listtasks default-webseald-cruz

The output is like:

dynurl update
jmt load
jmt clear
cache flush all
create
add
remove
delete <junction point>
list
show <junction point>
reload
terminate all_sessions <user_id>
terminate session <user_session_id>
refresh all_sessions <user_id>
help command
trace set component level [file path=file|
other-log-agent-config]
trace show [component]
trace list [component]
stats show [component]
stats list
stats on [component][interval][count]
[file path= file|other-log-agent-config]
stats off [component]
stats reset [component]
stats get [component]

See also

server list

server show

Parent topic: pdadmin commands

server replicateserver replicateserver replicateNotifies the installed Security Access Manager authorization server or server instance to receive database updates. server commandsserver replicatereplicate serverRequires authentication (administrator ID and password) to use this command.Syntaxserver replicate [–server server_name-host_name] Options–server server_name-host_nameSpecifies the name of the installed Security Access Manager server or server instance. You must specify the server_name in the exact format as displayed in the output of the server list command. (Optional)For example, if the configured name of a single WebSEAL server is default, the server_name is default-webseald followed by -host_name. The full server name–host name is default-webseald-cruz.dallas.ibm.com.For multiple server instances on the same computer, if the configured name of a WebSEAL server instance is webseal2-webseald, the instance_name is followed by -host_name. The full server instance name–host name is webseal2-webseald-cruz.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleHere is an example of this command when the server name is specified: pdadmin sec_master> server replicate -server ivacld-topserver See alsoserver listLists all registered Security Access Manager servers. server showDisplays the properties for the specified installed Security Access Manager server or server instance. The server must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server replicate

Notifies the installed Security Access Manager authorization server or server instance to receive database updates.

Requires authentication (administrator ID and password) to use this command.

Syntax

server replicate [–server server_name-host_name]

Options

–server server_name-host_name

Specifies the name of the installed Security Access Manager server or server instance. You must specify the server_name in the exact format as displayed in the output of the server list command. (Optional)

For example, if the configured name of a single WebSEAL server is default, the server_name is default-webseald followed by -host_name. The full server name–host name is default-webseald-cruz.dallas.ibm.com.

For multiple server instances on the same computer, if the configured name of a WebSEAL server instance is webseal2-webseald, the instance_name is followed by -host_name. The full server instance name–host name is webseal2-webseald-cruz.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

Here is an example of this command when the server name is specified:

pdadmin sec_master> server replicate -server ivacld-topserver

See also

server list

server show

Parent topic: pdadmin commands

server showserver showserver showDisplays the properties for the specified installed Security Access Manager server or server instance. The server must exist, or an error is displayed. server commandsserver showRequires authentication (administrator ID and password) to use this command.Syntaxserver show server_name-host_name Optionsserver_name-host_nameSpecifies the name of the installed Security Access Manager server or server instance. You must specify the server_name in the exact format as displayed in the output of the server list command. For example, if the configured name of a single WebSEAL server is default, the server_name is default-webseald followed by -host_name. The full server name–host name is default-webseald-cruz.dallas.ibm.com.For multiple server instances on the same computer, if the configured name of a WebSEAL server instance is webseal2-webseald, the instance_name is followed by -host_name. The full server instance name–host name is webseal2-webseald-cruz.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays the specified properties for the authorization server (ivacld) on the mogman computer:pdadmin sec_master> server show ivacld-mogman The output is like: ivacld-mogman Description: ivacld/mogman Hostname: mogman Principal: ivacld/mogman Administration Request Port: 7137 Listening for authorization database update notifications: yes AZN Administration Services: AZN_ADMIN_SVC_TRACEThe following example displays the properties of the WebSEAL server default-webseald-cruz: pdadmin sec_master> server show default-webseald-cruz The output is like: default-webseald-cruz Description: default-webseald-cruz Hostname: cruz.dallas.ibm.com Principal: default-webseald/cruz Administration Request Port: 7234 Listening for authorization database update notifications: yes AZN Administration Services: webseal-admin-svc azn_admin_svc_traceThe following example displays the ivmgrd-master policy server properties: pdadmin sec_master> server show ivmgrd-master The output is like: ivmgrd-master Description: ivmgrd-master Hostname: localhost Principal: Administration Request Port: 7135 Listening for authorization database update notifications: no AZN Administration Services: azn_admin_svc_traceThe Administration Request Port, 7135 in the output, is the same port that is set for the policy server during policy server configuration. See alsoserver listLists all registered Security Access Manager servers. server task showDisplays detailed information about the specified WebSEAL junction. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server show

Displays the properties for the specified installed Security Access Manager server or server instance. The server must exist, or an error is displayed.

Requires authentication (administrator ID and password) to use this command.

Syntax

server show server_name-host_name

Options

server_name-host_name

Specifies the name of the installed Security Access Manager server or server instance. You must specify the server_name in the exact format as displayed in the output of the server list command.

For example, if the configured name of a single WebSEAL server is default, the server_name is default-webseald followed by -host_name. The full server name–host name is default-webseald-cruz.dallas.ibm.com.

For multiple server instances on the same computer, if the configured name of a WebSEAL server instance is webseal2-webseald, the instance_name is followed by -host_name. The full server instance name–host name is webseal2-webseald-cruz.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays the specified properties for the authorization server (ivacld) on the mogman computer:

pdadmin sec_master> server show ivacld-mogman

The output is like:

ivacld-mogman
Description: ivacld/mogman
Hostname: mogman
Principal: ivacld/mogman
Administration Request Port: 7137
Listening for authorization database update notifications: yes
AZN Administration Services:
AZN_ADMIN_SVC_TRACE

The following example displays the properties of the WebSEAL server default-webseald-cruz:

pdadmin sec_master> server show default-webseald-cruz

The output is like:

default-webseald-cruz
Description: default-webseald-cruz
Hostname: cruz.dallas.ibm.com
Principal: default-webseald/cruz
Administration Request Port: 7234
Listening for authorization database update notifications: yes
AZN Administration Services:
webseal-admin-svc
azn_admin_svc_trace

The following example displays the ivmgrd-master policy server properties:

pdadmin sec_master> server show ivmgrd-master

The output is like:

ivmgrd-master
Description: ivmgrd-master
Hostname: localhost
Principal:
Administration Request Port: 7135
Listening for authorization database update notifications: no
AZN Administration Services:
azn_admin_svc_trace

Note: The Administration Request Port, 7135 in the output, is the same port that is set for the policy server during policy server configuration.

See also

server list

server task show

Parent topic: pdadmin commands

server task addserver task addserver task addAdds an application server to an existing WebSEAL junction. server commandsserver task addjunctioned serversaddRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name add –h host_name [options] junction_point Options–h host_nameSpecifies the DNS host name or IP address of the target application server. Valid values for host_name include any valid IP host name. For example: www.example.cominstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.optionsSpecifies the options that you can use with the server task add command. (Optional) These options include: –D "dn"Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have the following DN: "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US"This option is valid only with junctions that were created with the type of ssl or sslproxy.–H host_nameSpecifies the DNS host name or IP address of the proxy server. Valid values for host_name include any valid IP host name. For example: www.example.comThis option is used for junctions that were created with the type of tcpproxy or sslproxy.–iIndicates that the WebSEAL server does not treat URLs as case-sensitive. This option is used for junctions that were created with the type of tcp or ssl.–p portSpecifies the TCP port of the server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.–P portSpecifies the TCP port of the HTTP proxy server. The default value is 7138. Use this option for junctions that were created with the type of tcpproxy or sslproxy. For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater than 1000 that is not being used.This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.–q urlSpecifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file. Required for Windows servers. This option is used for junctions that were created with the type of tcp or ssl.–u uuidSpecifies the UUID of this server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.–v virtual_hostnameSpecifies the virtual host name that is represented on the server. This option supports a virtual host setup on the server. Use this option when the junction server expects a host name header, because you are junctioning to one virtual instance of that server. The default HTTP header request from the browser does not know that the server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information in requests that are destined for a server that is set up as a virtual host. This option is used for junctions that were created with the type of tcp or ssl.–V virtual_hostnameSpecifies the virtual host name that is represented on the back-end server. This option: Supports a virtual host setup on the back-end server.Is used only for mutual junctions.Corresponds to the virtual host that is used for HTTPS requests.You can use –V when the back-end junction server expects a host name header and you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information. This header information applies to requests destined for a back-end server that is set up as a virtual host.–wIndicates Microsoft Windows 32 bit (Win32) file system support. This option is used for junctions that were created with the type of tcp or ssl. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command, and returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about how to add servers to existing junctions, see the Administering topics in the IBM Knowledge Center.ExampleThe following example creates a junction for the WebSEAL server named WS1 to the server named APP1. The example adds another server named APP2 to the same junction point: pdadmin> server task default-webseald-WS1 create -t tcp -h APP1 -s /mnt pdadmin> server task default-webseald-WS1 add -h APP2 /mnt See alsoserver task createCreates a WebSEAL junction point. server task deleteDeletes a WebSEAL junction point. server task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. server task showDisplays detailed information about the specified WebSEAL junction. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task add

Adds an application server to an existing WebSEAL junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name add –h host_name [options] junction_point

Options

–h host_name

Specifies the DNS host name or IP address of the target application server. Valid values for host_name include any valid IP host name. For example:

www.example.com

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

options

Specifies the options that you can use with the server task add command. (Optional) These options include:

–D "dn"

Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have the following DN:

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–H host_name

Specifies the DNS host name or IP address of the proxy server. Valid values for host_name include any valid IP host name. For example:

www.example.com

This option is used for junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL server does not treat URLs as case-sensitive. This option is used for junctions that were created with the type of tcp or ssl.

–p port

Specifies the TCP port of the server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.

–P port

Specifies the TCP port of the HTTP proxy server. The default value is 7138. Use this option for junctions that were created with the type of tcpproxy or sslproxy.

For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater than 1000 that is not being used.

This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.

–q url

Specifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file. Required for Windows servers.

This option is used for junctions that were created with the type of tcp or ssl.

–u uuid

Specifies the UUID of this server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.

–v virtual_hostname

Specifies the virtual host name that is represented on the server. This option supports a virtual host setup on the server. Use this option when the junction server expects a host name header, because you are junctioning to one virtual instance of that server.

The default HTTP header request from the browser does not know that the server has multiple names and multiple virtual servers.

You must configure WebSEAL to supply that extra header information in requests that are destined for a server that is set up as a virtual host.

This option is used for junctions that were created with the type of tcp or ssl.

–V virtual_hostname

Specifies the virtual host name that is represented on the back-end server. This option:

Supports a virtual host setup on the back-end server.

Is used only for mutual junctions.

Corresponds to the virtual host that is used for HTTPS requests.

You can use –V when the back-end junction server expects a host name header and you are junctioning to one virtual instance of that server. The default HTTPS header request from the browser does not know that the back-end server has multiple names and multiple virtual servers. You must configure WebSEAL to supply that extra header information. This header information applies to requests destined for a back-end server that is set up as a virtual host.

–w

Indicates Microsoft Windows 32 bit (Win32) file system support.

This option is used for junctions that were created with the type of tcp or ssl.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command, and returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

For more information about how to add servers to existing junctions, see the Administering topics in the IBM Knowledge Center.

Example

The following example creates a junction for the WebSEAL server named WS1 to the server named APP1. The example adds another server named APP2 to the same junction point:

pdadmin> server task default-webseald-WS1 create -t tcp -h APP1 -s /mnt

pdadmin> server task default-webseald-WS1 add -h APP2 /mnt

See also

server task create

server task delete

server task remove

server task show

Parent topic: pdadmin commands

server task cache flush allserver task cache flush allserver task cache flush allFlushes the HTML document cache. server commandsserver task cache flush allcaches, flushing HTML documentHTML document cache, flushdocument cache, HTML flushingRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name cache flush all Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about the WebSEAL content caching, see the Administering topics in the IBM Knowledge Center.ExampleThe following example flushes all web document caches: pdadmin> server task default-webseald-abc.ibm.com cache flush all pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task cache flush all

Flushes the HTML document cache.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name cache flush all

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note:

This command is available only when WebSEAL is installed.

For more information about the WebSEAL content caching, see the Administering topics in the IBM Knowledge Center.

Example

The following example flushes all web document caches:

pdadmin> server task default-webseald-abc.ibm.com cache flush all

Parent topic: pdadmin commands

server task createserver task createserver task createCreates a WebSEAL junction point. junctioned serverscreateserver commandsserver task createRequires authentication (administrator ID and password) to use this command.SyntaxFor local junctions:server task instance_name-webseald-host_name create –t type –d dir [options] junction_pointFor non-local junctions:server task instance_name-webseald-host_name create –t type –h host_name [options] junction_point Options–d dirSpecifies the local directory to the junction. This option is required if the junction type is local. This option is valid only with junctions that were created with the type of local.–h host_nameSpecifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example: www.example.com–T {resource | resource_group}Specifies the name of the resource or resource group. This option is required only when the –b gso option is used. This option is valid for all junctions except for the type of local.instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host machine name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.optionsSpecifies the options that you can use with the server task create command. (Optional) These options include: –a addressSpecifies the local IP address that WebSEAL uses to communicate with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system. If an address is supplied for a particular junction, WebSEAL is modified to bind to this local address for all communication with the junctioned server.–AEnables or disables lightweight third-party authentication mechanism (LTPA) junctions. This option requires the –F and –Z options. The –A, –F, and –Z options all must be used together. This option is valid for all junctions except for the type of local.–2You can use this option with the –A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The –A option without the –2 option specifies that LTPA version 1 cookies (LtpaToken) are used.–b BA_valueDefines how the WebSEAL server passes the HTTP BA authentication information to the server, which is one of the following values: filter (default)ignoresupplygsoThis option is valid for all junctions except for the type of local.–BIndicates that WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option requires the –U and –W options. This option is valid only with junctions that were created with the type of ssl or sslproxy.–c header_typeInserts the Security Access Manager client identity in HTTP headers across the junction. The header_type argument can include any combination of the Security Access Manager HTTP header types: {iv_user|iv_user_l}iv_groupsiv_credsallThe header types must be comma-separated, and cannot have a space between the types. For example: -c iv_user,iv_groupsSpecifying –c all is the same as specifying –c iv_user,iv_groups,iv_creds. This option is valid for all junctions except for the type of local.–C Indicates single sign-on from a front-end WebSEAL server to a back-end WebSEAL server. The –C option is not mutual authentication. This option is valid only with junctions that were created with the type of ssl or sslproxy.–D "dn"Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US"This option is valid only with junctions that were created with the type of ssl or sslproxy.–e encoding_typeSpecifies the encoding to use when HTTP headers are generated for junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. The following values for encoding are supported: utf8_binWebSEAL sends the headers in UTF-8.utf8_uriWebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.lcp_binWebSEAL sends the headers in the local code page of the WebSEAL server.lcp_uriWebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them.This option is valid for all junctions except for the type of local.–fForces the replacement of an existing junction. This option is used for junctions that were created with any junction type.–F keyfileSpecifies the location of the key file that is used to encrypt LTPA cookie data. The –F option requires –A and –Z options. The –A, –F, and –Z options all must be used together.This option is valid for all junctions except for the type of local.–H host_nameSpecifies the DNS host name or IP address of the proxy server. The –P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example, proxy.www.example.com This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.–iIndicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file. Junctions to such a Web server must be created with the –i or –w option. ACLs or POPs that are attached to objects beneath the junction point must use the lowercase object name. An ACL attached to /junction/index.htm applies to all the following requests if the –i or –w option is used: /junction/INDEX.HTM/junction/index.htm/junction/InDeX.HtMThis option is valid for all junctions except for the type of local. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.–I Ensures a unique Set-Cookie header name attribute when the –j option is used to modify server-relative URLs in requests. This option is valid for all junctions except for the type of local.–jSupplies junction identification in a cookie to handle script-generated server-relative URLs. This option is valid for all junctions except for the type of local.–J trailer,inhead,onfocus,xhtml10Controls the junction cookie JavaScript block. Use –J trailer to append the junction cookie JavaScript to HTML page returned from back-end server.Use –J inhead to insert the Javascript block between <head> </head> tags for HTML 4.01 compliance.Use –J onfocus to use the onfocus event handler in the JavaScript to ensure that the correct junction cookie is used in a multiple-junction/multiple-browser-window scenario.Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and XHTML 1.0 compliant.–kSends WebSEAL session cookies to the junction server. By default, cookies are removed from requests that are sent to the server. This option is valid for all junctions except for the type of local.–K "key_label"Specifies the key label of the client personal certificate that WebSEAL must present to the server. Use of this option allows the junction server to authenticate the WebSEAL server by using client certificates. This option is valid only with junctions that were created with the type of ssl and sslproxy.–l percentDefines the soft limit for consumption of worker threads. This option is valid for all junctions except for the type of local.–L percentDefines the hard limit for consumption of worker threads. This option is valid for all junctions except for the type of local.–nIndicates that no modifications of the names of non-domain cookies are to be made. Use when client side scripts depend on the names of cookies. WebSEAL modifies the names of non-domain cookies that are returned from the junction to prefix with AMWEBJCT!junction_point. WebSEAL does this action by default, if a junction is listed in the JMT or if the –j junction option is used.This option is valid for all junctions except for the type of local.–p portSpecifies the TCP port of the back end third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is valid for all junctions except for the type of local.–P portFor proxy junctions that were created with the type of tcpproxy or sslproxy this option specifies the TCP port number for the HTTP proxy server. The –P option is required when the –H option is used. This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.–q path Specifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option indicates to WebSEAL the new URL to the file. Required for back end Windows servers. This option is valid for all junctions except for the type of local.–rInserts the incoming IP address into the HTTP header across the junction. This option is valid for all junctions except for the type of local.–R Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the –R option is not used and a rule failure occurs, WebSEAL does not allow the request to proceed. This option is valid for all junctions except for the type of local.–sIndicates that the junction support stateful applications. By default, junctions are not stateful. This option is valid for all junctions except for the type of local.–S pathSpecifies the location of the forms single sign-on configuration file. This option is valid for all junctions except for the type of local.–t typeSpecifies the type of junction; must be one of the following types: tcptcpproxysslsslproxylocal–u uuidSpecifies the Universally Unique Identifier (UUID) of a server that is connected to WebSEAL by using a stateful junction (–s option). This option is valid for all junctions except for the type of local.–U "user_name"Specifies the WebSEAL server user name. This option requires the –B and –W options. WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.–v virtual_hostname[:HTTP-port]Specifies the virtual host name for the server. This option supports multiple virtual hosts that are served from the same Web server. Use –v when the junction server expects a host name header different from the DNS name of the server. This option is valid for all junctions except for the type of local. For mutual junctions, this value corresponds to the virtual host that is used for HTTP requests.–V virtual_hostname[:HTTPS-port]Specifies the virtual host name for the back-end server. This option supports multiple virtual hosts that are served from the same Web server. Use –V when the back-end junction server expects a host name header that is different from the DNS name of the server. This option is used only for mutual junctions and corresponds to the virtual host that is used for HTTPS requests.–wIndicates Microsoft Windows 32-bit (Win32) file system support. This option: Provides all the functionality that is provided by the –i junction option.Disallows requests that contain file names that might be interpreted as Win32 file name aliases.The option is valid for all junctions except for the type of local. Local junctions prohibit URLs that contain Win32 file name aliases on Win32 but allow such URLs on other platforms.–W "password"Specifies the WebSEAL server password. This option requires the –B and –U options. WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.–x Creates a path junction that is not apparent. This option is valid for all junctions except for the type of local.–YEnables Tivoli Federated Identity Manager single sign-on (SSO) for the junction. Indicates that Kerberos SSO is enabled for the junction. Before you use this command, configure the WebSEAL configuration file to support Kerberos single sign-on over junctions.–Z keyfile_pwdSpecifies the password of the key file that is used to encrypt LTPA cookie data. This option requires the –A and –F options. The –A, –F, and –Z options all must be used together. This option is valid for all junctions except for the type of local. AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about creating a junctioned server, see the Administering topics in the IBM Knowledge Center.For more information about gathering statistics, see the Auditing topics in the IBM Knowledge Center. ExamplesThe following example creates a basic WebSEAL junction /pubs on the default-webseald-cruz WebSEAL server. The junction type is TCP, and the host name is doc.tivoli.com: pdadmin> server task default-webseald-cruz create -t tcp \ -h doc.tivoli.com /pubs Output is like: Created junction at /pubsThe following example creates a new local junction / to replace the current junction point. The –f option is required to force a new junction that overwrites an existing junction at the /tmp/docs directory: pdadmin> server task default-webseald-cruz create -t local \ -f -d /tmp/docs / Output is like: Created junction at /The following example limits worker thread consumption on a per junction basis with a: Soft thread limit of 60.Hard thread limit of 80.The junction in this example is /myjunction. pdadmin> server task default-webseald-cruz create -t tcp \ -h cruz.dallas.ibm.com -l 60 -L 80 /myjunction See alsoserver task addAdds an application server to an existing WebSEAL junction. server task deleteDeletes a WebSEAL junction point. server task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. server task showDisplays detailed information about the specified WebSEAL junction. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task create

Creates a WebSEAL junction point.

Requires authentication (administrator ID and password) to use this command.

Syntax

For local junctions:

server task instance_name-webseald-host_name create –t type –d dir [options] junction_point

For non-local junctions:

server task instance_name-webseald-host_name create –t type –h host_name [options] junction_point

Options

–d dir

Specifies the local directory to the junction. This option is required if the junction type is local.

This option is valid only with junctions that were created with the type of local.

–h host_name

Specifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example:

www.example.com

–T {resource | resource_group}

Specifies the name of the resource or resource group. This option is required only when the –b gso option is used. This option is valid for all junctions except for the type of local.

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical machine where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host machine name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

options

Specifies the options that you can use with the server task create command. (Optional) These options include:

–a address

Specifies the local IP address that WebSEAL uses to communicate with the target back-end server. If this option is not provided, WebSEAL uses the default address as determined by the operating system.

If an address is supplied for a particular junction, WebSEAL is modified to bind to this local address for all communication with the junctioned server.

–A

Enables or disables lightweight third-party authentication mechanism (LTPA) junctions. This option requires the –F and –Z options. The –A, –F, and –Z options all must be used together.

This option is valid for all junctions except for the type of local.

–2

You can use this option with the –A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The –A option without the –2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

–b BA_value

Defines how the WebSEAL server passes the HTTP BA authentication information to the server, which is one of the following values:

filter (default)

ignore

supply

gso

This option is valid for all junctions except for the type of local.

–B

Indicates that WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option requires the –U and –W options.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–c header_type

Inserts the Security Access Manager client identity in HTTP headers across the junction. The header_type argument can include any combination of the Security Access Manager HTTP header types:

{iv_user|iv_user_l}

iv_groups

iv_creds

all

The header types must be comma-separated, and cannot have a space between the types. For example: -c iv_user,iv_groups

Specifying –c all is the same as specifying –c iv_user,iv_groups,iv_creds.

This option is valid for all junctions except for the type of local.

–C

Indicates single sign-on from a front-end WebSEAL server to a back-end WebSEAL server. The –C option is not mutual authentication.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–D "dn"

Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–e encoding_type

Specifies the encoding to use when HTTP headers are generated for junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. The following values for encoding are supported:

utf8_bin

WebSEAL sends the headers in UTF-8.

utf8_uri

WebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.

lcp_bin

WebSEAL sends the headers in the local code page of the WebSEAL server.

lcp_uri

WebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them.

This option is valid for all junctions except for the type of local.

–f

Forces the replacement of an existing junction.

This option is used for junctions that were created with any junction type.

–F keyfile

Specifies the location of the key file that is used to encrypt LTPA cookie data.

The –F option requires –A and –Z options. The –A, –F, and –Z options all must be used together.

This option is valid for all junctions except for the type of local.

–H host_name

Specifies the DNS host name or IP address of the proxy server. The –P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example,

proxy.www.example.com

This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a Web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file.

Junctions to such a Web server must be created with the –i or –w option. ACLs or POPs that are attached to objects beneath the junction point must use the lowercase object name. An ACL attached to /junction/index.htm applies to all the following requests if the –i or –w option is used:

/junction/INDEX.HTM

/junction/index.htm

/junction/InDeX.HtM

This option is valid for all junctions except for the type of local. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.

–I

Ensures a unique Set-Cookie header name attribute when the –j option is used to modify server-relative URLs in requests.

This option is valid for all junctions except for the type of local.

–j

Supplies junction identification in a cookie to handle script-generated server-relative URLs.

This option is valid for all junctions except for the type of local.

–J trailer,inhead,onfocus,xhtml10

Controls the junction cookie JavaScript block.

Use –J trailer to append the junction cookie JavaScript to HTML page returned from back-end server.

Use –J inhead to insert the Javascript block between <head> </head> tags for HTML 4.01 compliance.

Use –J onfocus to use the onfocus event handler in the JavaScript to ensure that the correct junction cookie is used in a multiple-junction/multiple-browser-window scenario.

Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and XHTML 1.0 compliant.

–k

Sends WebSEAL session cookies to the junction server. By default, cookies are removed from requests that are sent to the server.

This option is valid for all junctions except for the type of local.

–K "key_label"

Specifies the key label of the client personal certificate that WebSEAL must present to the server. Use of this option allows the junction server to authenticate the WebSEAL server by using client certificates.

This option is valid only with junctions that were created with the type of ssl and sslproxy.

–l percent

Defines the soft limit for consumption of worker threads.

This option is valid for all junctions except for the type of local.

–L percent

Defines the hard limit for consumption of worker threads.

This option is valid for all junctions except for the type of local.

–n

Indicates that no modifications of the names of non-domain cookies are to be made. Use when client side scripts depend on the names of cookies.

WebSEAL modifies the names of non-domain cookies that are returned from the junction to prefix with AMWEBJCT!junction_point. WebSEAL does this action by default, if a junction is listed in the JMT or if the –j junction option is used.

This option is valid for all junctions except for the type of local.

–p port

Specifies the TCP port of the back end third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions.

This option is valid for all junctions except for the type of local.

–P port

For proxy junctions that were created with the type of tcpproxy or sslproxy this option specifies the TCP port number for the HTTP proxy server. The –P option is required when the –H option is used.

This option is also valid for mutual junctions to specify the HTTPS port of the back-end third-party server.

–q path

Specifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option indicates to WebSEAL the new URL to the file. Required for back end Windows servers.

This option is valid for all junctions except for the type of local.

–r

Inserts the incoming IP address into the HTTP header across the junction. This option is valid for all junctions except for the type of local.

–R

Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the –R option is not used and a rule failure occurs, WebSEAL does not allow the request to proceed. This option is valid for all junctions except for the type of local.

–s

Indicates that the junction support stateful applications. By default, junctions are not stateful. This option is valid for all junctions except for the type of local.

–S path

Specifies the location of the forms single sign-on configuration file. This option is valid for all junctions except for the type of local.

–t type

Specifies the type of junction; must be one of the following types:

tcp

tcpproxy

ssl

sslproxy

local

–u uuid

Specifies the Universally Unique Identifier (UUID) of a server that is connected to WebSEAL by using a stateful junction (–s option). This option is valid for all junctions except for the type of local.

–U "user_name"

Specifies the WebSEAL server user name. This option requires the –B and –W options. WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.

–v virtual_hostname[:HTTP-port]

Specifies the virtual host name for the server. This option supports multiple virtual hosts that are served from the same Web server. Use –v when the junction server expects a host name header different from the DNS name of the server. This option is valid for all junctions except for the type of local. For mutual junctions, this value corresponds to the virtual host that is used for HTTP requests.

–V virtual_hostname[:HTTPS-port]

Specifies the virtual host name for the back-end server. This option supports multiple virtual hosts that are served from the same Web server. Use –V when the back-end junction server expects a host name header that is different from the DNS name of the server. This option is used only for mutual junctions and corresponds to the virtual host that is used for HTTPS requests.

–w

Indicates Microsoft Windows 32-bit (Win32) file system support. This option:

Provides all the functionality that is provided by the –i junction option.

Disallows requests that contain file names that might be interpreted as Win32 file name aliases.

The option is valid for all junctions except for the type of local. Local junctions prohibit URLs that contain Win32 file name aliases on Win32 but allow such URLs on other platforms.

–W "password"

Specifies the WebSEAL server password. This option requires the –B and –U options. WebSEAL uses the BA header information to authenticate to the server and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.

–x

Creates a path junction that is not apparent.

This option is valid for all junctions except for the type of local.

–Y

Enables Tivoli® Federated Identity Manager single sign-on (SSO) for the junction.

Indicates that Kerberos SSO is enabled for the junction. Before you use this command, configure the WebSEAL configuration file to support Kerberos single sign-on over junctions.

–Z keyfile_pwd

Specifies the password of the key file that is used to encrypt LTPA cookie data. This option requires the –A and –F options. The –A, –F, and –Z options all must be used together. This option is valid for all junctions except for the type of local.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note:

This command is available only when WebSEAL is installed.

For more information about creating a junctioned server, see the Administering topics in the IBM Knowledge Center.

For more information about gathering statistics, see the Auditing topics in the IBM Knowledge Center.

Examples

The following example creates a basic WebSEAL junction /pubs on the default-webseald-cruz WebSEAL server. The junction type is TCP, and the host name is doc.tivoli.com:

pdadmin> server task default-webseald-cruz create -t tcp \
-h doc.tivoli.com /pubs

Output is like:

Created junction at /pubs

The following example creates a new local junction / to replace the current junction point. The –f option is required to force a new junction that overwrites an existing junction at the /tmp/docs directory:

pdadmin> server task default-webseald-cruz create -t local \
-f -d /tmp/docs /

Output is like:

Created junction at /

The following example limits worker thread consumption on a per junction basis with a:

Soft thread limit of 60.

Hard thread limit of 80.

The junction in this example is /myjunction.

pdadmin> server task default-webseald-cruz create -t tcp \
-h cruz.dallas.ibm.com -l 60 -L 80 /myjunction

See also

server task add

server task delete

server task remove

server task show

Parent topic: pdadmin commands

server task deleteserver task deleteserver task deleteDeletes a WebSEAL junction point. junctioned serversdeleteserver commandsserver task deleteRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name delete junction_point Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about how to delete WebSEAL junctions, see the Administering topics in the IBM Knowledge Center. ExampleThe following example deletes the junction point /pubs from the WebSEAL server default-webseald-abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com delete /pubs See alsoserver task addAdds an application server to an existing WebSEAL junction. server task createCreates a WebSEAL junction point. server task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. server task showDisplays detailed information about the specified WebSEAL junction. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task delete

Deletes a WebSEAL junction point.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name delete junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note:

This command is available only when WebSEAL is installed.

For more information about how to delete WebSEAL junctions, see the Administering topics in the IBM Knowledge Center.

Example

The following example deletes the junction point /pubs from the WebSEAL server default-webseald-abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com delete /pubs

See also

server task add

server task create

server task remove

server task show

Parent topic: pdadmin commands

server task dynurl updateserver task dynurl updateserver task dynurl updateReloads the dynamic URL configuration file. server commandsserver task dynurl updatedynamic URL, reloadingURL, reloading dynamicRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name dynurl update Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about how WebSEAL handles dynamic URLs, see the Administering topics in the IBM Knowledge Center.ExampleThe following example reloads the dynamic URL configuration file: pdadmin> server task default-webseald-abc.ibm.com dynurl update pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task dynurl update

Reloads the dynamic URL configuration file.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name dynurl update

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

For more information about how WebSEAL handles dynamic URLs, see the Administering topics in the IBM Knowledge Center.

Example

The following example reloads the dynamic URL configuration file:

pdadmin> server task default-webseald-abc.ibm.com dynurl update

Parent topic: pdadmin commands

server task helpserver task helpserver task helpLists detailed help information about a specific server task command. server commandsserver task helpRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name help task Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.taskLists detailed help for the specified task, such as the command syntax, the description, and the valid options. AuthorizationNo special authorization required. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays output after help is requested for the server task add command at the abc.ibm.com WebSEAL server: pdadmin> server task default-webseald-abc.ibm.com help add Output is like: Command: add <options> <junction point> Description: Adds an additional server to a junction Usage: TCP and SSL Junction Flags -i Server treats URLs as case insensitive. -h <hostname> Target host (required flag). -p <port> TCP port of server. Default is 80 for TCP junctions 443 for SSL junctions. -H <hostname> Proxy hostname. -P <port> Port of proxy server. -D <"DN"> The Distinguished Name of the server -q <relative url> URL for query_contents script. -u <UUID> (stateful junctions only). -v <hostname> Virtual hostname for server. -w Win32 file system support. -j Scripting support for junction. Common Flags <junction point> Where to create the junctionThe following example displays the output after help is requested for the server task create command at the abc.ibm.com WebSEAL server: pdadmin> server task default-webseald-abc.ibm.com help create Output is like: Command: create -t <type> <options> <junction point> Description: Creates a new junction Usage: create -t <type> <options> <junction point> TCP and SSL Junction Flags ... Common Flags -t <type>Type of junction. One of: tcp, tcpproxy, ssl, sslproxy, local. -f Force the creation: overwrite existing junction. -R WebSEAL will send the Boolean Rule Header to these junctions when a rule failure reason is provided. <junction point> Where to create the junction See alsohelpObtains system help for pdadmin commands and options. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task help

Lists detailed help information about a specific server task command.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name help task

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

task

Lists detailed help for the specified task, such as the command syntax, the description, and the valid options.

Authorization

No special authorization required.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays output after help is requested for the server task add command at the abc.ibm.com WebSEAL server:

pdadmin> server task default-webseald-abc.ibm.com help add

Output is like:

Command:
add <options> <junction point>
Description:
Adds an additional server to a junction
Usage:
TCP and SSL Junction Flags
-i Server treats URLs as case insensitive.
-h <hostname> Target host (required flag).
-p <port> TCP port of server.
Default is 80 for TCP junctions
443 for SSL junctions.
-H <hostname> Proxy hostname.
-P <port> Port of proxy server.
-D <"DN"> The Distinguished Name of the server
-q <relative url> URL for query_contents script.
-u <UUID> (stateful junctions only).
-v <hostname> Virtual hostname for server.
-w Win32 file system support.
-j Scripting support for junction.
Common Flags
<junction point> Where to create the junction

The following example displays the output after help is requested for the server task create command at the abc.ibm.com WebSEAL server:

pdadmin> server task default-webseald-abc.ibm.com help create

Output is like:

Command:
create -t <type> <options> <junction point>
Description:
Creates a new junction
Usage:
create -t <type> <options> <junction point>

TCP and SSL Junction Flags
...
Common Flags
-t <type>Type of junction.
One of: tcp, tcpproxy, ssl, sslproxy, local.
-f Force the creation: overwrite existing junction.
-R WebSEAL will send the Boolean Rule Header to these
junctions when a rule failure reason is provided.
<junction point> Where to create the junction

See also

help

Parent topic: pdadmin commands

server task jmtserver task jmtserver task jmtClears or loads the junction mapping table data. server commandsserver task jmtjunction mapping tableloadjunction mapping tableclearJMTRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name jmt loadserver task instance_name-webseald-host_name jmt clear OptionsclearClears the junction mapping table data.instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.loadLoads the junction mapping table data, which is in the jmt.conf file. This file does not exist by default, so you must create the file and add data. AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about the WebSEAL junction mapping table, see the Administering topics in the IBM Knowledge Center. ExampleThe following example loads the junction mapping table data from the jmt.conf file. As a result, WebSEAL has the new information: pdadmin> server task default-webseald-abc.ibm.com jmt load Output is like: JMT table successfully loaded. See alsoserver task reloadReloads the junction mapping table from the database. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task jmt

Clears or loads the junction mapping table data.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name jmt load

server task instance_name-webseald-host_name jmt clear

Options

clear

Clears the junction mapping table data.

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

load

Loads the junction mapping table data, which is in the jmt.conf file. This file does not exist by default, so you must create the file and add data.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

For more information about the WebSEAL junction mapping table, see the Administering topics in the IBM Knowledge Center.

Example

The following example loads the junction mapping table data from the jmt.conf file. As a result, WebSEAL has the new information:

pdadmin> server task default-webseald-abc.ibm.com jmt load

Output is like:

JMT table successfully loaded.

See also

server task reload

Parent topic: pdadmin commands

server task listserver task listserver task listLists all junction points on a WebSEAL server or server instance. server commandsserver task listjunctioned serverslistRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name list Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, if the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. AuthorizationUsers and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/per_junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command, and returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about WebSEAL junctions, see the Administering topics in the IBM Knowledge Center.ExampleThe following example lists all junction points on the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz list Output is like: / /ssljct /tcpjct See alsoserver task addAdds an application server to an existing WebSEAL junction. server task createCreates a WebSEAL junction point. server task deleteDeletes a WebSEAL junction point. server task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. server task showDisplays detailed information about the specified WebSEAL junction. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task list

Lists all junction points on a WebSEAL server or server instance.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name list

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, if the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/per_junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command, and returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

For more information about WebSEAL junctions, see the Administering topics in the IBM Knowledge Center.

Example

The following example lists all junction points on the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz list

Output is like:

/
/ssljct
/tcpjct

See also

server task add

server task create

server task delete

server task remove

server task show

Parent topic: pdadmin commands

server task offlineserver task offlineserver task offlinePlaces the server that is at this junction in an offline operational state.server commandsserver task offlinejunctioned serversoffline operational stateSyntaxserver task instance_name-webseald-host_name offline [–i server_uuid] junction_point DescriptionThe server task offline command places the server that is at this junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are at this junction are placed in an offline operational state. Options–i server_uuidSpecifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are at this junction are placed in an offline operational state. Use the server task show command to determine the ID of a specific server. (Optional)instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleThe following example places the backappl server at the /pubs junction point in an offline operational state. To determine the UUID of this junctioned server, run the server task show command: pdadmin> server task default-webseald-cruz show /pubs Output is like: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Throttled Throttled at: 2005-03-01-17:07:24 Hostname: backapp1.diamond.example.com ... Current requests: 0 ...Place this server in an offline operational state: pdadmin> server task default-webseald-cruz offline \ -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See alsoserver task onlinePlaces the server that is at this junction in an online operational state. server task throttlePlaces the server that is at this junction in a throttled operational state. server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task offline

Places the server that is at this junction in an offline operational state.

Syntax

server task instance_name-webseald-host_name offline [–i server_uuid] junction_point

Description

The server task offline command places the server that is at this junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are at this junction are placed in an offline operational state.

Options

–i server_uuid

Specifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are at this junction are placed in an offline operational state. Use the server task show command to determine the ID of a specific server. (Optional)

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The following example places the backappl server at the /pubs junction point in an offline operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is like:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Place this server in an offline operational state:

pdadmin> server task default-webseald-cruz offline \
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task online

server task throttle

server task virtualhost offline

server task virtualhost online

server task virtualhost throttle

Parent topic: pdadmin commands

server task onlineserver task onlineserver task onlinePlaces the server that is at this junction in an online operational state.server commandsserver task onlinejunctioned serversonline operational stateSyntaxserver task instance_name-webseald-host_name online [–i server_uuid] junction_point DescriptionThe server task online command places the server that is at this junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are at this junction are placed in an online operational state. Options–i server_uuidSpecifies the UUID of the server to place in an online operational state. If a server is not specified, all servers that are at this junction are placed in an online operational state. Use the server task show command to determine the ID of a specific server. (Optional)instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleThe following example places the backappl server at the /pubs junction point in an online operational state. To determine the UUID of this junctioned server, run the server task show command: pdadmin> server task default-webseald-cruz show /pubs Output is like: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Offline Hostname: backapp1.diamond.example.com ... Current requests: 0 ...Place this server in an online operational state: pdadmin> server task default-webseald-cruz online \ -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See alsoserver task offlinePlaces the server that is at this junction in an offline operational state. server task throttlePlaces the server that is at this junction in a throttled operational state. server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task online

Places the server that is at this junction in an online operational state.

Syntax

server task instance_name-webseald-host_name online [–i server_uuid] junction_point

Description

The server task online command places the server that is at this junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are at this junction are placed in an online operational state.

Options

–i server_uuid

Specifies the UUID of the server to place in an online operational state. If a server is not specified, all servers that are at this junction are placed in an online operational state. Use the server task show command to determine the ID of a specific server. (Optional)

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The following example places the backappl server at the /pubs junction point in an online operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is like:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Offline
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Place this server in an online operational state:

pdadmin> server task default-webseald-cruz online \
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task offline

server task throttle

server task virtualhost offline

server task virtualhost online

server task virtualhost throttle

Parent topic: pdadmin commands

server task refresh all_sessionsserver task refresh all_sessionsserver task refresh all_sessionsRefreshes the credential for all sessions for a specified user. server commandsserver task refresh all_sessionscredentials, refresh WebSEALRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name refresh all_sessions user_id Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.user_idRefreshes the credential for all sessions that are associated with the specified user. Examples of user names are dlucas, sec_master, and "Mary Jones". AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. This command is available only when WebSEAL is installed. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. For more information about the WebSEAL credential refresh, see the Administering topics in the IBM Knowledge Center.ExampleThe following example refreshes all sessions for the test_user user: pdadmin> server task default-webseald-cruz refresh all_sessions test_user See alsoserver task terminate sessionTerminates a user session by using a session ID. server task terminate all_sessionsTerminates all user sessions for a specific user. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task refresh all_sessions

Refreshes the credential for all sessions for a specified user.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name refresh all_sessions user_id

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

user_id

Refreshes the credential for all sessions that are associated with the specified user. Examples of user names are dlucas, sec_master, and "Mary Jones".

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Note: This command is available only when WebSEAL is installed.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: For more information about the WebSEAL credential refresh, see the Administering topics in the IBM Knowledge Center.

Example

The following example refreshes all sessions for the test_user user:

pdadmin> server task default-webseald-cruz refresh all_sessions test_user

See also

server task terminate session

server task terminate all_sessions

Parent topic: pdadmin commands

server task reloadserver task reloadserver task reloadReloads the junction mapping table from the database. server commandsserver task reloadjunction mapping tablereloadRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name reload Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about the WebSEAL junction mapping table, see the Administering topics in the IBM Knowledge Center. ExampleThe following example reloads the junction mapping table from the database: pdadmin> server task default-webseald-abc.ibm.com reload See alsoserver task jmtClears or loads the junction mapping table data. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task reload

Reloads the junction mapping table from the database.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name reload

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

For more information about the WebSEAL junction mapping table, see the Administering topics in the IBM Knowledge Center.

Example

The following example reloads the junction mapping table from the database:

pdadmin> server task default-webseald-abc.ibm.com reload

See also

server task jmt

Parent topic: pdadmin commands

server task removeserver task removeserver task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. server commandsserver task removejunctioned serversremoveRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name remove –i server_uuid junction_point Options–i server_uuidSpecifies the UUID of the server to be removed from the junction point. See the server task show command for details about obtaining the UUID.instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. For more information about how to remove a server from a WebSEAL junction, see the Administering topics in the IBM Knowledge Center.This command is available only when WebSEAL is installed.ExampleThe following example removes the backappl junctioned server from the /pubs junction point. To determine the UUID of the server to be removed, run the server task show command: pdadmin> server task default-webseald-cruz show /pubs Output is like: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running ... Hostname: backapp1.cruz.ibm.com ...Remove the server from the junction: pdadmin> server task default-webseald-cruz remove \ -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See alsoserver task addAdds an application server to an existing WebSEAL junction. server task createCreates a WebSEAL junction point. server task deleteDeletes a WebSEAL junction point. server task showDisplays detailed information about the specified WebSEAL junction. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task remove

Removes the specified installed WebSEAL server or server instance from a WebSEAL junction point.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name remove –i server_uuid junction_point

Options

–i server_uuid

Specifies the UUID of the server to be removed from the junction point. See the server task show command for details about obtaining the UUID.

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: For more information about how to remove a server from a WebSEAL junction, see the Administering topics in the IBM Knowledge Center.

This command is available only when WebSEAL is installed.

Example

The following example removes the backappl junctioned server from the /pubs junction point. To determine the UUID of the server to be removed, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is like:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
...
Hostname: backapp1.cruz.ibm.com
...

Remove the server from the junction:

pdadmin> server task default-webseald-cruz remove \
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task add

server task create

server task delete

server task show

Parent topic: pdadmin commands

server task showserver task showserver task showDisplays detailed information about the specified WebSEAL junction. junctioned serverslist detailsserver commandsserver task showRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name show junction_point Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted. AuthorizationUsers and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about WebSEAL junctions, see the Administering topics in the IBM Knowledge Center. ExampleThe following example shows information for the local root junction point / on the WebSEAL server abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com show Output is like: Junction point: / Type: Local Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Root Directory: /opt/pdweb/www-default/docs ... Server 1: ID: 78a1eb8c-074a-11d9-abda-00096bda9439 ... See alsoserver task addAdds an application server to an existing WebSEAL junction. server task createCreates a WebSEAL junction point. server task deleteDeletes a WebSEAL junction point. server task removeRemoves the specified installed WebSEAL server or server instance from a WebSEAL junction point. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task show

Displays detailed information about the specified WebSEAL junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name show junction_point

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

For more information about WebSEAL junctions, see the Administering topics in the IBM Knowledge Center.

Example

The following example shows information for the local root junction point / on the WebSEAL server abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com show

Output is like:

Junction point: /
Type: Local
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Root Directory: /opt/pdweb/www-default/docs
...
Server 1:
ID: 78a1eb8c-074a-11d9-abda-00096bda9439
...

See also

server task add

server task create

server task delete

server task remove

Parent topic: pdadmin commands

server task sms key changeserver task sms key changeserver task sms key changeForces the creation of a new session management key. server commandsserver task sms key changesession management serverkeyscreatekeys, session management servercreateYou might want to forcibly create a key when you suspect that the existing key was compromised.Syntaxserver task server_name–host_name sms key change Optionsserver_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host cruz.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If there are multiple configured server instances on the same computer, for example, the host cruz.dallas.ibm.com, and the configured name of the WebSEAL server instance is webseal2-webseald, the server_name is webseal2-webseald and the host_name is example.dallas.ibm.com. For this example, the name of the server instance would be webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example forcibly creates a session management key for the abc.ibm.com server: pdadmin> server task default-webseald-abc.ibm.com key change See alsoserver listLists all registered Security Access Manager servers. server task sms key showLists detailed information about the current session management key. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms key change

Forces the creation of a new session management key.

You might want to forcibly create a key when you suspect that the existing key was compromised.

Syntax

server task server_name–host_name sms key change

Options

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host cruz.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If there are multiple configured server instances on the same computer, for example, the host cruz.dallas.ibm.com, and the configured name of the WebSEAL server instance is webseal2-webseald, the server_name is webseal2-webseald and the host_name is example.dallas.ibm.com. For this example, the name of the server instance would be webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example forcibly creates a session management key for the abc.ibm.com server:

pdadmin> server task default-webseald-abc.ibm.com key change

See also

server list

server task sms key show

Parent topic: pdadmin commands

server task sms key showserver task sms key showserver task sms key showLists detailed information about the current session management key.server commandsserver task sms key showsession management serverkeysdisplay detailskeys, session management serverdisplay detailsSyntaxserver task server_name–host_name sms key show Optionsserver_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same machine, for example: The host is cruz.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name would be webseal2-webseald.The host_name would be example.dallas.ibm.com.The name of the server instance would be webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example returns detailed information about the current session management key for the abc.ibm.com server: pdadmin> server task default-webseald-abc.ibm.com sms key show Output is like: ID: 1 Created: 2004-03-03-09:00:03 Expires: 2004-09-03-09:00:03 See alsoserver listLists all registered Security Access Manager servers. server task sms key changeForces the creation of a new session management key. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms key show

Lists detailed information about the current session management key.

Syntax

server task server_name–host_name sms key show

Options

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same machine, for example:

The host is cruz.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name would be webseal2-webseald.

The host_name would be example.dallas.ibm.com.

The name of the server instance would be webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example returns detailed information about the current session management key for the abc.ibm.com server:

pdadmin> server task default-webseald-abc.ibm.com sms key show

Output is like:

ID: 1
Created: 2004-03-03-09:00:03
Expires: 2004-09-03-09:00:03

See also

server list

server task sms key change

Parent topic: pdadmin commands

server task sms realm listserver task sms realm listserver task sms realm listLists all session management realms in the domain.server commandsserver task sms realm listsession management serverrealms, listrealms, session management serverlistSyntaxserver task server_name–host_name sms realm list Optionsserver_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If there are multiple configured server instances on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server.ExampleThe following example lists the realms for the abc.ibm.com server: pdadmin> server task default-webseald-abc.ibm.com sms realm list See alsoserver listLists all registered Security Access Manager servers. server task sms realm showLists all replica sets in the specified session management realm. server task sms replica set listLists all session management replica sets in the domain. server task sms replica set showLists all session management replicas in the specified replica set with the time and date that each joined the realm. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms realm list

Lists all session management realms in the domain.

Syntax

server task server_name–host_name sms realm list

Options

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If there are multiple configured server instances on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example lists the realms for the abc.ibm.com server:

pdadmin> server task default-webseald-abc.ibm.com sms realm list

See also

server list

server task sms realm show

server task sms replica set list

server task sms replica set show

Parent topic: pdadmin commands

server task sms realm showserver task sms realm showserver task sms realm showLists all replica sets in the specified session management realm.server commandsserver task sms realm showsession management serverreplica sets in realms, displayrealms, session management serverdetails, display Syntaxserver task server_name–host_name sms realm show realm_name Optionsrealm_nameSpecifies the name of the realm. When you specify a realm, the output contains only those replica sets in that realm.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example returns the replica sets in the ibm.com realm of the abc.ibm.com server: pdadmin> server task default-webseald-abc.ibm.com sms realm show ibm.com See alsoserver listLists all registered Security Access Manager servers. server task sms realm listLists all session management realms in the domain. server task sms replica set listLists all session management replica sets in the domain. server task sms replica set showLists all session management replicas in the specified replica set with the time and date that each joined the realm. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms realm show

Lists all replica sets in the specified session management realm.

Syntax

server task server_name–host_name sms realm show realm_name

Options

realm_name

Specifies the name of the realm. When you specify a realm, the output contains only those replica sets in that realm.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example returns the replica sets in the ibm.com realm of the abc.ibm.com server:

pdadmin> server task default-webseald-abc.ibm.com sms realm show ibm.com

See also

server list

server task sms realm list

server task sms replica set list

server task sms replica set show

Parent topic: pdadmin commands

server task sms session refresh all_sessionsserver task sms session refresh all_sessionsserver task sms session refresh all_sessionsRefreshes the credential for sessions for a specific user.server commandsserver task sms refresh all_sessionssession management servercredentials, refresh allSyntaxserver task server_name–host_name sms session refresh all_sessions user_name –realm realm_name Options–realm realm_nameSpecifies that name of the realm. The credentials of only those sessions that belong to the specified realm are refreshed.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host isexample.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.user_nameRefreshes the credential for all sessions that are associated with the specified user. Examples of user names are dlucas, sec_master, and “Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example refreshes all sessions for user johnq in the ibm.com realm: pdadmin> server task default-webseald-cruz sms session refresh all_sessions johnq \ -realm ibm.com See alsoserver task sms session terminate sessionTerminates a user session by using a session ID. server task sms session terminate all_sessionsTerminates all user sessions for a specific user. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms session refresh all_sessions

Refreshes the credential for sessions for a specific user.

Syntax

server task server_name–host_name sms session refresh all_sessions user_name –realm realm_name

Options

–realm realm_name

Specifies that name of the realm. The credentials of only those sessions that belong to the specified realm are refreshed.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host isexample.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

user_name

Refreshes the credential for all sessions that are associated with the specified user. Examples of user names are dlucas, sec_master, and “Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example refreshes all sessions for user johnq in the ibm.com realm:

pdadmin> server task default-webseald-cruz sms session refresh all_sessions johnq \
-realm ibm.com

See also

server task sms session terminate session

server task sms session terminate all_sessions

Parent topic: pdadmin commands

server task sms session refresh sessionserver task sms session refresh sessionserver task sms session refresh sessionRefreshes the credential for a session.server commandsserver task sms refresh sessionsession management servercredentials, refreshSyntaxserver task server_name–host_name sms session refresh session session_id –realm realm_name Options–realm realm_nameSpecifies that name of the realm. The credentials of only those sessions that belong to the specified realm are refreshed.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.session_idSpecifies the identifier for the session to refresh. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example refreshes session 678 in the ibm.com realm: pdadmin> server task default-webseald-cruz sms session refresh session 678 \ -realm ibm.com See alsoserver task sms session terminate sessionTerminates a user session by using a session ID. server task sms session terminate all_sessionsTerminates all user sessions for a specific user. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms session refresh session

Refreshes the credential for a session.

Syntax

server task server_name–host_name sms session refresh session session_id –realm realm_name

Options

–realm realm_name

Specifies that name of the realm. The credentials of only those sessions that belong to the specified realm are refreshed.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

session_id

Specifies the identifier for the session to refresh.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example refreshes session 678 in the ibm.com realm:

pdadmin> server task default-webseald-cruz sms session refresh session 678 \
-realm ibm.com

See also

server task sms session terminate session

server task sms session terminate all_sessions

Parent topic: pdadmin commands

server task sms replica set listserver task sms replica set listserver task sms replica set listLists all session management replica sets in the domain.server commandsserver task sms replica set listsession management serverreplica sets, listreplica sets, session management serverlistSyntaxserver task server_name–host_name sms replica set list [–realm realm_name] Options–realm realm_nameIndicates that the returned list of replica sets is limited to those replica sets in the specified realm. (Optional)server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example lists the replica sets in the ibm realm of the abc.ibm.com server: pdadmin> server task default-webseald-abc.ibm.com sms replica set list -realm ibm See alsoserver listLists all registered Security Access Manager servers. server task sms realm listLists all session management realms in the domain. server task sms realm showLists all replica sets in the specified session management realm. server task sms replica set showLists all session management replicas in the specified replica set with the time and date that each joined the realm. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms replica set list

Lists all session management replica sets in the domain.

Syntax

server task server_name–host_name sms replica set list [–realm realm_name]

Options

–realm realm_name

Indicates that the returned list of replica sets is limited to those replica sets in the specified realm. (Optional)

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example lists the replica sets in the ibm realm of the abc.ibm.com server:

pdadmin> server task default-webseald-abc.ibm.com sms replica set list -realm ibm

See also

server list

server task sms realm list

server task sms realm show

server task sms replica set show

Parent topic: pdadmin commands

server task sms replica set showserver task sms replica set showserver task sms replica set showLists all session management replicas in the specified replica set with the time and date that each joined the realm.server commandsserver task sms replica set showsession management serverreplica sets, display detailreplica sets, session management serverdetails, display Syntaxserver task server_name–host_name sms replica set show replica_set_name Optionsreplica_set_nameSpecifies the name of the replica set.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server.ExampleThe following example returns details about the ibm.com replica that is set of the abc.ibm.com server: pdadmin> server task default-webseald-abc.ibm.com sms replica set show ibm.com See alsoserver listLists all registered Security Access Manager servers. server task sms realm listLists all session management realms in the domain. server task sms realm showLists all replica sets in the specified session management realm. server task sms replica set listLists all session management replica sets in the domain. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms replica set show

Lists all session management replicas in the specified replica set with the time and date that each joined the realm.

Syntax

server task server_name–host_name sms replica set show replica_set_name

Options

replica_set_name

Specifies the name of the replica set.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example returns details about the ibm.com replica that is set of the abc.ibm.com server:

pdadmin> server task default-webseald-abc.ibm.com sms replica set show ibm.com

See also

server list

server task sms realm list

server task sms realm show

server task sms replica set list

Parent topic: pdadmin commands

server task sms session listserver task sms session listserver task sms session listLists all session management sessions.server commandsserver task sms session listsession management serversessions, listSyntaxserver task server_name–host_name sms session list –realm realm_name pattern maximum_return Options–realm realm_nameSpecifies the name of the session management realm.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com. If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.maximum_returnSpecifies the maximum number of sessions to return. When there are more matches than designated by this option, the output contains the number of matches.patternSpecifies the pattern for returning user names. The pattern can include a combination of wildcard and string constant characters. The pattern is case-sensitive. For example, you can specify *luca* as the pattern to find all users that contain the substring luca within the user name. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example is entered as one line. The example: Lists the user sessions in the ibm.com realm of the abc.ibm.com server.Lists sessions for users that contain the string ons.Limits the number of matches to 100.pdadmin> server task default-webseald-abc.ibm.com sms session list -realm ibm.com *ons* 100 See alsoserver listLists all registered Security Access Manager servers. server task sms realm listLists all session management realms in the domain. server task sms realm showLists all replica sets in the specified session management realm. server task sms replica set showLists all session management replicas in the specified replica set with the time and date that each joined the realm. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms session list

Lists all session management sessions.

Syntax

server task server_name–host_name sms session list –realm realm_name pattern maximum_return

Options

–realm realm_name

Specifies the name of the session management realm.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

maximum_return

Specifies the maximum number of sessions to return. When there are more matches than designated by this option, the output contains the number of matches.

pattern

Specifies the pattern for returning user names. The pattern can include a combination of wildcard and string constant characters. The pattern is case-sensitive. For example, you can specify *luca* as the pattern to find all users that contain the substring luca within the user name.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example is entered as one line. The example:

Lists the user sessions in the ibm.com realm of the abc.ibm.com server.

Lists sessions for users that contain the string ons.

Limits the number of matches to 100.

pdadmin> server task default-webseald-abc.ibm.com
sms session list -realm ibm.com *ons* 100

See also

server list

server task sms realm list

server task sms realm show

server task sms replica set show

Parent topic: pdadmin commands

server task sms session terminate all_sessionsserver task sms session terminate all_sessionsserver task sms session terminate all_sessionsTerminates all user sessions for a specific user.server commandsserver task terminate all_sessionsuser sessionsterminate all smsSyntaxserver task server_name–host_name sms session terminate all_sessions user_id –realm realm_name Options–realm realm_nameSpecifies that name of the session management realm.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.user_idSpecifies the name of the user. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server.ExampleThe following example terminates all sessions for the dlucas user in the ibm.com realm of the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz sms session terminate \ all_sessions dlucas -realm ibm.com See alsoserver task sms session refresh sessionRefreshes the credential for a session. server task sms session refresh all_sessionsRefreshes the credential for sessions for a specific user. server task sms session terminate sessionTerminates a user session by using a session ID. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms session terminate all_sessions

Terminates all user sessions for a specific user.

Syntax

server task server_name–host_name sms session terminate all_sessions user_id –realm realm_name

Options

–realm realm_name

Specifies that name of the session management realm.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

user_id

Specifies the name of the user. Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example terminates all sessions for the dlucas user in the ibm.com realm of the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz sms session terminate \
 all_sessions dlucas -realm ibm.com

See also

server task sms session refresh session

server task sms session refresh all_sessions

server task sms session terminate session

Parent topic: pdadmin commands

server task sms session terminate sessionserver task sms session terminate sessionserver task sms session terminate sessionTerminates a user session by using a session ID.server commandsserver task terminate sessionuser sessionsterminate smsSyntaxserver task server_name–host_name sms session terminate session session_id –realm realm_name Optionsserver_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com. If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.session_idSpecifies the ID of a user session. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example terminates session 678 in the ibm.com realm of the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz sms session terminate \ session 678 -realm ibm.com See alsoserver task sms session refresh all_sessionsRefreshes the credential for sessions for a specific user. server task sms session terminate all_sessionsTerminates all user sessions for a specific user. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms session terminate session

Terminates a user session by using a session ID.

Syntax

server task server_name–host_name sms session terminate session session_id –realm realm_name

Options

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

session_id

Specifies the ID of a user session.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example terminates session 678 in the ibm.com realm of the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz sms session terminate \
session 678 -realm ibm.com

See also

server task sms session refresh all_sessions

server task sms session terminate all_sessions

Parent topic: pdadmin commands

server task sms trace getserver task sms trace getserver task sms trace getDisplays the trace level for the session management server.server commandsserver task sms trace gettrace leveldisplayingSyntaxserver task server_name–host_name sms trace get Optionsserver_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server. ExampleThe following example returns the tracing level for the ivacld-cruz authorization server: pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace get See alsoserver task sms trace setSets the trace level for the distributed session cache. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms trace get

Displays the trace level for the session management server.

Syntax

server task server_name–host_name sms trace get

Options

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example returns the tracing level for the ivacld-cruz authorization server:

pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace get

See also

server task sms trace set

Parent topic: pdadmin commands

server task sms trace setserver task sms trace setserver task sms trace setSets the trace level for the distributed session cache.server commandsserver task sms trace settrace levelsettingSyntaxserver task server_name–host_name sms trace set level OptionslevelSpecifies the level of tracing. A valid setting is an integer between 0 and 3, with 3 being the most detailed level of trace.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when the session management command-line extensions are installed to a hosting authorization server.ExampleThe following example sets the tracing level to 1 on the ivacld-cruz authorization server: pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace set 1 See alsoserver task sms trace getDisplays the trace level for the session management server. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task sms trace set

Sets the trace level for the distributed session cache.

Syntax

server task server_name–host_name sms trace set level

Options

level

Specifies the level of tracing. A valid setting is an integer between 0 and 3, with 3 being the most detailed level of trace.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when the session management command-line extensions are installed to a hosting authorization server.

Example

The following example sets the tracing level to 1 on the ivacld-cruz authorization server:

pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace set 1

See also

server task sms trace get

Parent topic: pdadmin commands

server task statsserver task statsserver task statsManages the gathering and reporting of statistics for Security Access Manager servers and server instances. server commandsserver task statsserver commandsserver task statsRequires authentication (administrator ID and password) to use this command.Syntaxserver task server_name–host_name stats get [component]server task server_name–host_name stats listserver task server_name–host_name stats off [component]server task server_name–host_name stats on component [interval [count]] [destination]server task server_name–host_name stats reset [component]server task server_name–host_name stats show [component] DescriptionThe server task stats command manages the gathering and reporting of statistics for Security Access Manager servers and server instances. You can use the stats commands with configuration setting that are defined by the stanza entries in the server configuration file to manage statistics.Statistics gathering is enabled through: The stats on command.The defined configuration settings.Then, you can use the stats on commands to modify the behavior for gathering and reporting statistics.For example, statistics are enabled to create five statistics reports with each report generated each day. You can use the stats on command to change the frequency to every 12 hours. For this example, assume that the following command started statistics gathering: pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \ pdwebpi.stats 86400 5 file path=/tmp/stats.logTo modify the interval to 12 hours and create 10 reports, issue the following command: pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \ pdwebpi.stats 43200 10Although the destination is not specified, the statistics infrastructure assumes any preexisting value. Entering the previous command does disable statistics from being written to the previously defined log file. However, if you specified a different destination, statistics reports would be written to the new destination only. You cannot use the stats on command to write statistics reports to more than one destination.For more information about gathering statistics, see the Auditing topics in the IBM Knowledge Center. OptionscomponentSpecifies the component about which to gather or report statistics. countSpecifies the number of reports to send to a log file. When you use the count option, you must specify the interval option. If you specify the interval option without the count option, the duration of reporting is indefinite. After the count value is reached, reporting to a log file stops. Although statistics are no longer sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.destinationSpecifies where the gathered statistics are written, where destination can be one of the following options: file path=file_nameSpecifies the fully qualified name of the log file.log_agentSpecifies a directory where statistics information is gathered. For more information about logging events, see the Troubleshooting topics in the IBM Knowledge Center.getDisplays the current report for a specific component or for all enabled components. If you specify the component option, displays the current report for that component; otherwise, displays the current report for all enabled components.intervalSpecifies the interval in seconds when statistics are sent from memory to a log file. When this option is specified, statistics are sent, by default, to the server-specific log file designated by the logcfg entry in the server configuration file. You can specify another location by using the destination option. If an interval is not specified, statistics are not sent to a log file, but remain in memory. Although statistics are not sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.listLists all components that are available to gather and report statistics.offDisables gathering of statistics for a specific component or for all components. If you specify the component option, disables gathering of statistics for that component; otherwise, disables gathering of statistics for all components.onEnables gathering of statistics for a specific component. When you enable gathering of statistics, you can also set the reporting frequency, count, and log file.resetResets gathering of statistics for a specific component or for all enabled components. If you specify the component option, resets gathering of statistics for that component; otherwise, resets gathering of statistics for all components.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.showLists all enabled components or indicates whether a specific component is enabled. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components. Return codes0The command completed successfully.1The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example uses the stats list command to lists all enabled components on the ivacld-mogman.admogman.com authorization server: #pdadmin sec_master> server task ivacld-mogman.admogman.com stats list pd.ras.stats.monitor pd.log.EventPool.queueThe following example: Uses the stats on command to enable gathering of statistics for the pd.log.EventPool.queue component on the ivacld-mogman.admogman.com authorization server.Sets the reporting frequency to 30 days, that is, 2592000 seconds.Sets the destination to the c:\myEPstats.log log file.#pdadmin sec_master> server task ivacld-mogman.admogman.com stats on \ pd.log.EventPool.queue 2592000 file path=c:\myEPstats.log See alsoserver listLists all registered Security Access Manager servers. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task stats

Manages the gathering and reporting of statistics for Security Access Manager servers and server instances.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task server_name–host_name stats get [component]

server task server_name–host_name stats list

server task server_name–host_name stats off [component]

server task server_name–host_name stats on component [interval [count]] [destination]

server task server_name–host_name stats reset [component]

server task server_name–host_name stats show [component]

Description

The server task stats command manages the gathering and reporting of statistics for Security Access Manager servers and server instances. You can use the stats commands with configuration setting that are defined by the stanza entries in the server configuration file to manage statistics.

Statistics gathering is enabled through:

The stats on command.

The defined configuration settings.

Then, you can use the stats on commands to modify the behavior for gathering and reporting statistics.

For example, statistics are enabled to create five statistics reports with each report generated each day. You can use the stats on command to change the frequency to every 12 hours. For this example, assume that the following command started statistics gathering:

pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \
pdwebpi.stats 86400 5 file path=/tmp/stats.log

To modify the interval to 12 hours and create 10 reports, issue the following command:

pdadmin sec_master> server task PDWebPI-linuxweb.wasp.ibm.com stats on \
pdwebpi.stats 43200 10

Although the destination is not specified, the statistics infrastructure assumes any preexisting value. Entering the previous command does disable statistics from being written to the previously defined log file. However, if you specified a different destination, statistics reports would be written to the new destination only. You cannot use the stats on command to write statistics reports to more than one destination.

For more information about gathering statistics, see the Auditing topics in the IBM Knowledge Center.

Options

component

Specifies the component about which to gather or report statistics.

count

Specifies the number of reports to send to a log file. When you use the count option, you must specify the interval option. If you specify the interval option without the count option, the duration of reporting is indefinite.

After the count value is reached, reporting to a log file stops. Although statistics are no longer sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.

destination

Specifies where the gathered statistics are written, where destination can be one of the following options:

file path=file_name

Specifies the fully qualified name of the log file.

log_agent

Specifies a directory where statistics information is gathered. For more information about logging events, see the Troubleshooting topics in the IBM Knowledge Center.

get

Displays the current report for a specific component or for all enabled components. If you specify the component option, displays the current report for that component; otherwise, displays the current report for all enabled components.

interval

Specifies the interval in seconds when statistics are sent from memory to a log file. When this option is specified, statistics are sent, by default, to the server-specific log file designated by the logcfg entry in the server configuration file. You can specify another location by using the destination option. If an interval is not specified, statistics are not sent to a log file, but remain in memory.

Although statistics are not sent to a log file, the statistic component is still enabled. You can obtain reports from memory by using the stats get command.

list

Lists all components that are available to gather and report statistics.

off

Disables gathering of statistics for a specific component or for all components. If you specify the component option, disables gathering of statistics for that component; otherwise, disables gathering of statistics for all components.

on

Enables gathering of statistics for a specific component. When you enable gathering of statistics, you can also set the reporting frequency, count, and log file.

reset

Resets gathering of statistics for a specific component or for all enabled components. If you specify the component option, resets gathering of statistics for that component; otherwise, resets gathering of statistics for all components.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

show

Lists all enabled components or indicates whether a specific component is enabled. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components.

Return codes

0

The command completed successfully.

1

The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example uses the stats list command to lists all enabled components on the ivacld-mogman.admogman.com authorization server:

#pdadmin sec_master> server task ivacld-mogman.admogman.com stats list

pd.ras.stats.monitor
pd.log.EventPool.queue

The following example:

Uses the stats on command to enable gathering of statistics for the pd.log.EventPool.queue component on the ivacld-mogman.admogman.com authorization server.

Sets the reporting frequency to 30 days, that is, 2592000 seconds.

Sets the destination to the c:\myEPstats.log log file.

#pdadmin sec_master> server task ivacld-mogman.admogman.com stats on \
pd.log.EventPool.queue 2592000 file path=c:\myEPstats.log

See also

server list

Parent topic: pdadmin commands

server task terminate all_sessionsserver task terminate all_sessionsserver task terminate all_sessionsTerminates all user sessions for a specific user. server commandsserver task terminate all_sessionsuser sessionsterminate allRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name terminate all_sessions user_id Options instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, The configured name of a single WebSEAL instance is default.The host computer name that has the WebSEAL server that is installed is abc.ibm.com.Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.user_idSpecifies the name of the user. Examples of user names are dlucas, sec_master, and "Mary Jones". AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. This command is available only when WebSEAL is installed. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. For more information about the WebSEAL server tasks and junction points, see the Administering topics in the IBM Knowledge Center.ExampleThe following example terminates all sessions for the dlucas user on the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz terminate all_sessions dlucas See alsoserver task terminate sessionTerminates a user session by using a session ID. server task refresh all_sessionsRefreshes the credential for all sessions for a specified user. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task terminate all_sessions

Terminates all user sessions for a specific user.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name terminate all_sessions user_id

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example,

The configured name of a single WebSEAL instance is default.

The host computer name that has the WebSEAL server that is installed is abc.ibm.com.

Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

user_id

Specifies the name of the user. Examples of user names are dlucas, sec_master, and "Mary Jones".

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Note: This command is available only when WebSEAL is installed.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: For more information about the WebSEAL server tasks and junction points, see the Administering topics in the IBM Knowledge Center.

Example

The following example terminates all sessions for the dlucas user on the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz terminate all_sessions dlucas

See also

server task terminate session

server task refresh all_sessions

Parent topic: pdadmin commands

server task terminate sessionserver task terminate sessionserver task terminate sessionTerminates a user session by using a session ID. server commandsserver task terminate sessionuser sessionsterminateRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name terminate session session_id Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example: The configured name of a single WebSEAL instance is default.The host computer name where the WebSEAL server is installed is abc.ibm.com.Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.session_idSpecifies the ID of a user session. AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default. This command is available only when WebSEAL is installed.Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. For more information about the WebSEAL server tasks and junction points, see the Administering topics in the IBM Knowledge Center. ExampleThe following example (entered as one line) terminates a specific session on the default-webseald-cruz WebSEAL server: pdadmin> server task default-webseald-cruz terminate session 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 See alsoserver task refresh all_sessionsRefreshes the credential for all sessions for a specified user. server task terminate all_sessionsTerminates all user sessions for a specific user. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task terminate session

Terminates a user session by using a session ID.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name terminate session session_id

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example:

The configured name of a single WebSEAL instance is default.

The host computer name where the WebSEAL server is installed is abc.ibm.com.

Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

session_id

Specifies the ID of a user session.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/ object. For example, the sec_master administrative user is given this permission by default.

Note: This command is available only when WebSEAL is installed.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: For more information about the WebSEAL server tasks and junction points, see the Administering topics in the IBM Knowledge Center.

Example

The following example (entered as one line) terminates a specific session on the default-webseald-cruz WebSEAL server:

pdadmin> server task default-webseald-cruz terminate
session 6fc3187a-ea1c-11d7-8f4e-09267e38aa77

See also

server task refresh all_sessions

server task terminate all_sessions

Parent topic: pdadmin commands

server task throttleserver task throttleserver task throttlePlaces the server that is at this junction in a throttled operational state.server commandsserver task throttlejunctioned serversthrottle operational stateSyntaxserver task instance_name-webseald-host_name throttle [–i server_uuid] junction_point DescriptionThe server task throttle command places the server that is at this junction in a throttled operational state. Users can create a session with WebSEAL before the invocation of this command. Only requests from such users are processed by the specified server. If a server is not specified, all servers that are at this junction are placed in a throttled operational state. Options–i server_uuidSpecifies the UUID of the server to throttle. If a server is not specified, all servers that are at this junction are placed in a throttled operational state. Use the server task show command to determine the ID of a specific server. (Optional)instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example: The configured name of a single WebSEAL server instance is default.The host computer name where the WebSEAL server is installed is abc.ibm.com.Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.junction_pointSpecifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleThe following example places the backappl server that is located at the /pubs junction point in a throttled operational state. To determine the UUID of this junctioned server, run the server task show command: pdadmin> server task default-webseald-cruz show /pubs Output is like: Junction point: /pubs ... Server 1: ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 Server State: running Operational State: Online Hostname: backapp1.diamond.example.com ... Current requests: 0 ...Place this server in a throttled operational state: pdadmin> server task default-webseald-cruz throttle \ -i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs See alsoserver task offlinePlaces the server that is at this junction in an offline operational state. server task onlinePlaces the server that is at this junction in an online operational state. server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task throttle

Places the server that is at this junction in a throttled operational state.

Syntax

server task instance_name-webseald-host_name throttle [–i server_uuid] junction_point

Description

The server task throttle command places the server that is at this junction in a throttled operational state. Users can create a session with WebSEAL before the invocation of this command. Only requests from such users are processed by the specified server. If a server is not specified, all servers that are at this junction are placed in a throttled operational state.

Options

–i server_uuid

Specifies the UUID of the server to throttle. If a server is not specified, all servers that are at this junction are placed in a throttled operational state. Use the server task show command to determine the ID of a specific server. (Optional)

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example:

The configured name of a single WebSEAL server instance is default.

The host computer name where the WebSEAL server is installed is abc.ibm.com.

Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

junction_point

Specifies the name of the directory in the WebSEAL protected object space where the document space of the server is mounted.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/junction_point object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The following example places the backappl server that is located at the /pubs junction point in a throttled operational state. To determine the UUID of this junctioned server, run the server task show command:

pdadmin> server task default-webseald-cruz show /pubs

Output is like:

Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server State: running
Operational State: Online
Hostname: backapp1.diamond.example.com
...
Current requests: 0
...

Place this server in a throttled operational state:

pdadmin> server task default-webseald-cruz throttle \
-i 6fc3187a-ea1c-11d7-8f4e-09267e38aa77 /pubs

See also

server task offline

server task online

server task virtualhost offline

server task virtualhost online

server task virtualhost throttle

Parent topic: pdadmin commands

server task traceserver task traceserver task traceEnables the gathering of trace information for components of installed Security Access Manager servers or server instances. server commandsserver task tracetrace, enablingRequires authentication (administrator ID and password) to use this command.Syntaxserver task server_name–host_name trace list [component]server task server_name–host_name trace set component level [destination]server task server_name–host_name trace show [component] DescriptionThe server task stats command enables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing. The content of trace messages is undocumented and is intended to be used for debugging purposes only. The format and content of trace messages might vary between product releases. Optionslist [component]Lists all enabled trace components that are available to gather and report trace information. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components.server_name–host_nameSpecifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command. For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.If multiple server instances are configured on the same computer, for example: The host is example.dallas.ibm.com.The configured name of the WebSEAL server instance is webseal2-webseald.Then, The server_name is webseal2-webseald.The host_name is example.dallas.ibm.com.The name of the server instance is webseal2-webseald-example.dallas.ibm.com.set component level [destination]Sets the trace level and trace message destination for a specific component and its subordinates. The value for the level option is a single integer from 1 to 9, with 9 reporting the most detailed level of information. The destination option specifies where the gathered trace information is written and can be one of the following options: file path=file_nameSpecifies the fully qualified file name.log_agentSpecifies a destination for the statistics information that is gathered for the specified component. For more information about logging events, see the Administering topics in the IBM Knowledge Center.show [component]Shows the names and levels for all enabled trace components. If you specify the component option, the output lists the name and level for the specified component. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example enables the pdweb.debug trace component to level 2 and then displays the output for all enabled components. WebSEAL–specific components are prefixed with pdweb. pdadmin sec_master> server task webseald-instance_name trace set pdweb.debug 2 pdadmin sec_master> server task webseald-instance_name trace show Output from the trace show command is like: pdweb.debug 2The following example enables the pdwebpi.module.session-cookie trace component to level 9. Then, the output for all enabled components is displayed. Components that are specific to the web server plug-ins are prefixed with pdwebpi. pdadmin sec_master> server task pdwpi-tivoli.com trace set pdwebpi.module.session-cookie 9 pdadmin sec_master> server task pdwpi-tivoli.com trace show Output from the trace show command is like: pdwebpi.module.session-cookie 9 See alsoserver listLists all registered Security Access Manager servers. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task trace

Enables the gathering of trace information for components of installed Security Access Manager servers or server instances.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task server_name–host_name trace list [component]

server task server_name–host_name trace set component level [destination]

server task server_name–host_name trace show [component]

Description

The server task stats command enables the gathering of trace information for components of installed Security Access Manager servers or server instances that support debug event tracing. The content of trace messages is undocumented and is intended to be used for debugging purposes only. The format and content of trace messages might vary between product releases.

Options

list [component]

Lists all enabled trace components that are available to gather and report trace information. If you specify the component option and the component is enabled, the output lists that component; otherwise, no output is displayed. If you do not specify the component option, the output lists all enabled components.

server_name–host_name

Specifies the name of the server or server instance. You must specify the server name in the exact format as it is shown in the output of the server list command.

For example, if the configured name of a single WebSEAL server on host example.dallas.ibm.com is default, the server_name would be default-webseald and the host_name would be example.dallas.ibm.com. For this example, the name of the server would be default-webseald-example.dallas.ibm.com.

If multiple server instances are configured on the same computer, for example:

The host is example.dallas.ibm.com.

The configured name of the WebSEAL server instance is webseal2-webseald.

Then,

The server_name is webseal2-webseald.

The host_name is example.dallas.ibm.com.

The name of the server instance is webseal2-webseald-example.dallas.ibm.com.

set component level [destination]

Sets the trace level and trace message destination for a specific component and its subordinates. The value for the level option is a single integer from 1 to 9, with 9 reporting the most detailed level of information. The destination option specifies where the gathered trace information is written and can be one of the following options:

file path=file_name

Specifies the fully qualified file name.

log_agent

Specifies a destination for the statistics information that is gathered for the specified component. For more information about logging events, see the Administering topics in the IBM Knowledge Center.

show [component]

Shows the names and levels for all enabled trace components. If you specify the component option, the output lists the name and level for the specified component.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example enables the pdweb.debug trace component to level 2 and then displays the output for all enabled components. WebSEAL–specific components are prefixed with pdweb.

pdadmin sec_master> server task webseald-instance_name trace set
pdweb.debug 2

pdadmin sec_master> server task webseald-instance_name trace show

Output from the trace show command is like:

pdweb.debug 2

The following example enables the pdwebpi.module.session-cookie trace component to level 9. Then, the output for all enabled components is displayed. Components that are specific to the web server plug-ins are prefixed with pdwebpi.

pdadmin sec_master> server task pdwpi-tivoli.com trace set
pdwebpi.module.session-cookie 9

pdadmin sec_master> server task pdwpi-tivoli.com trace show

Output from the trace show command is like:

pdwebpi.module.session-cookie 9

See also

server list

Parent topic: pdadmin commands

server task virtualhost addserver task virtualhost addserver task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. server commandsserver task virtualhost addjunctioned servers virtual hostjunctionsaddRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost add –h host_name [options] vhost_label Options–h host_nameSpecifies the DNS host name or IP address of the target server. Valid values for host_name include any valid IP host name. This option is required. For example: www.example.cominstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.options Specifies the options that you can use with the server task virtualhost add command. (Optional) These options include: –D "dn"Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US"This option is valid only with junctions that were created with the type of ssl or sslproxy.–H host_nameSpecifies the DNS host name or IP address of the proxy server. Valid values for host_name include any valid IP host name. For example: proxy.www.example.comThis option is used for junctions that were created with the type of tcpproxy or sslproxy.–iIndicates that the WebSEAL server does not treat URLs as case-sensitive. This option is used for junctions that were created with the type of tcp or ssl.–p portSpecifies the TCP port of the server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.–P portSpecifies the TCP port of the proxy server. The default value is 7138. For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater than 1000 that is not being used.This option is used for junctions that were created with the type of tcpproxy or sslproxy.–q pathSpecifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file. Required for Windows virtual hosts. This option is valid for all junction types except localtcp and localssl. –u uuidSpecifies the UUID of this server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.–wIndicates Microsoft Windows 32 bit (Win32) file system support. This option is used for junctions that were created with the type of tcp or ssl.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleThe following example adds a server with host name xyz.ibm.com to an existing virtual host junction with the label support-vhost-http, on the WebSEAL server abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com virtualhost add \ -h xyz.ibm.com support-vhost-http See alsoserver task virtualhost createCreates a virtual host junction. server task virtualhost deleteDeletes a virtual host junction. server task virtualhost listLists all configured virtual host junctions by label name. server task virtualhost removeRemoves the specified server from a virtual host junction. server task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost add

Adds an additional installed WebSEAL server or server instance to an existing virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost add –h host_name [options] vhost_label

Options

–h host_name

Specifies the DNS host name or IP address of the target server. Valid values for host_name include any valid IP host name. This option is required. For example:

www.example.com

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

options

Specifies the options that you can use with the server task virtualhost add command. (Optional) These options include:

–D "dn"

Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–H host_name

Specifies the DNS host name or IP address of the proxy server.

Valid values for host_name include any valid IP host name. For example:

proxy.www.example.com

This option is used for junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL server does not treat URLs as case-sensitive.

This option is used for junctions that were created with the type of tcp or ssl.

–p port

Specifies the TCP port of the server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is used for junctions that were created with the type of tcp or ssl.

–P port

Specifies the TCP port of the proxy server. The default value is 7138.

For port, use any valid port number. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application. Use the default port number value, or use a port number that is greater than 1000 that is not being used.

This option is used for junctions that were created with the type of tcpproxy or sslproxy.

–q path

Specifies the relative path for the query_contents script. By default, Security Access Manager looks for this script in the /cgi_bin subdirectory. If this directory is different or the query_contents file is renamed, use this option to indicate to WebSEAL the new URL to the file. Required for Windows virtual hosts.

This option is valid for all junction types except localtcp and localssl.

–u uuid

Specifies the UUID of this server when connected to WebSEAL over a stateful junction that was using the –s option. This option is used for junctions that were created with the type of tcp or ssl.

–w

Indicates Microsoft Windows 32 bit (Win32) file system support.

This option is used for junctions that were created with the type of tcp or ssl.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The following example adds a server with host name xyz.ibm.com to an existing virtual host junction with the label support-vhost-http, on the WebSEAL server abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com virtualhost add \
-h xyz.ibm.com support-vhost-http

See also

server task virtualhost create

server task virtualhost delete

server task virtualhost list

server task virtualhost remove

server task virtualhost show

Parent topic: pdadmin commands

server task virtualhost createserver task virtualhost createserver task virtualhost createCreates a virtual host junction. junctioned servers virtual hostjunctionscreateserver commandsserver task virtualhost createRequires authentication (administrator ID and password) to use this command.SyntaxFor local junctions:server task instance_name-webseald-host_name virtualhost create –t type –d dir –v virtual_host_name [options] vhost_labelFor non-local junctions:server task instance_name-webseald-host_name virtualhost create –t type –h host_name [options] vhost_label Options–d dirSpecifies the local directory for a local virtual host junction. This option is required for localtcp and localssl junction types.–h host_nameSpecifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example: www.example.com–t typeSpecifies the type of virtual host junction. This option is required and must be one of the following types: tcptcpproxysslsslproxylocaltcplocalssl–v virtual_host_name[:port] WebSEAL selects a virtual host junction to process a request if the HTTP Host header of the request matches:The virtual host name by the -v option andThe port number that is specified by the -v option.The –v option is also used to specify the value of the Host header of the request sent to the server.The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.If –v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions, the junction is selected from the information that is contained in the –h host_name and –p port options.The –v option is required for localtcp and localssl type junctionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.optionsSpecifies the options that you can use with the server task virtualhost create command. (Optional) These options include: –AEnables a virtual host junction to support the lightweight third-party authentication mechanism (LTPA). This option requires the –F and –Z options. The –A, –F, and –Z options all must be used together. This option is valid for all junction types except localtcp and localssl.–2You can use this option with the –A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The –A option without the –2 option specifies that LTPA version 1 cookies (LtpaToken) are used.–b BA_valueDefines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the virtual host, which is one of the following values: filterignoresupplygsoThis option is valid for all junction types except localtcp and localssl. The default value is filter.–BIndicates that WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL. This option requires the –U and –W options. This option is valid only with junctions that were created with the type of ssl or sslproxy.–c header_typeInserts the Security Access Manager client identity in HTTP headers across the virtual host junction. The header_type argument can include any combination of the listed Security Access Manager HTTP header types: {iv_user|iv_user-l}iv_groupsiv_credsallThe header types must be comma-separated, and cannot have a space between the types. For example: -c iv_user,iv_groupsSpecifying –c all is the same as specifying –c iv_user,iv_groups,iv_creds.This option is valid for all junction types except localtcp and localssl.–C Supports mutual authentication by enabling the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server. The front-end WebSEAL server passes information in a Basic Authentication (BA) header. Additionally, the –C option enables the single sign-on functionality that is provided by the –c option. This option is valid only with junctions that were created with the type of ssl or sslproxy.–D "dn"Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of "CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin, ST=Texas,C=US"This option is valid only with junctions that were created with the type of ssl or sslproxy.–e encoding_typeSpecifies the encoding to use when HTTP headers is generated for virtual host junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. Possible values for encoding are as follows: utf8_binWebSEAL sends the headers in UTF-8.utf8_uriWebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.lcp_binWebSEAL sends the headers in the local code page of the WebSEAL server.lcp_uriWebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them.This option is valid for all junction types except localtcp and localssl.–fForces the replacement (overwrite) of an existing virtual host junction. This option is used for junctions that were created with any junction type.–F "keyfile"Specifies the location of the key file that is used to encrypt LTPA cookie data. The –F option requires –A and –Z options. The –A, –F, and –Z options all must be used together.This option is valid for all junction types except localtcp and localssl.–g vhost_labelThe –g option causes a second more virtual host junction to share a protected object space as the initial virtual host junction. This option is appropriate for junction pairs only (two junctions by using complementary protocols). The option does not support the association of more than two junctions.–H host_nameSpecifies the DNS host name or IP address of the proxy server. The –P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example: proxy.www.example.com This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.–iIndicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file. Junctions to such a web server must be created with the –i or –w option. ACLs or POPs that are attached to objects beneath the junction point must use the lowercase object name. An ACL attached to /junction/index.htm applies to all the following requests if the –i or –w option is used: /junction/INDEX.HTM/junction/index.htm/junction/InDeX.HtMThis option is valid for all junction except for the type of localtcp and localssl. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.–kSends WebSEAL session cookies to the back-end virtual host. By default, cookies are removed from requests that are sent to the server. This option is valid for all junction types except localtcp and localssl.–K "key_label"Specifies the key label of the client-side certificate that WebSEAL must present to the server. Use of this option allows the virtual host to authenticate the WebSEAL server by using client certificates. This option is valid only with junctions that were created with the type of ssl and sslproxy.–l percentDefines the soft limit for consumption of worker threads. This option is valid for all junction types except localtcp and localssl.–L percentDefines the hard limit for consumption of worker threads. This option is valid for all junction types except localtcp and localssl.–p portSpecifies the TCP port of the third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions. This option is valid for all junction types except localtcp and localssl.–P portSpecifies the TCP port number for the HTTP proxy server. The –P option is required when the –H option is used. This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.–q –SSpecifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option indicates to WebSEAL the new URL to the file. Required for Windows virtual hosts. This option is valid for all junction types except localtcp and localssl.–rInserts the incoming IP address into the HTTP header across the junction. This option is valid for all junction types except localtcp and localssl.–R Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the –R option is not used and a rule failure occurs, WebSEAL does not allow the request to proceed. This option is valid for all junction types except localtcp and localssl.–sIndicates that the virtual host junction support stateful applications. By default, virtual host junctions are not stateful. This option is valid for all junction types except localtcp and localssl.–SIndicates the location of the forms single sign-on configuration file. This option is valid for all junction types except localtcp and localssl.–T {resource | resource_group}Specifies the name of the GSO resource or resource group. This option is required only when the –b gso option is used. This option is valid for all junction types except localtcp and localssl.–u uuidSpecifies the Universally Unique Identifier (UUID) of a server that is connected to WebSEAL by using a stateful virtual host junction (–s option). This option is valid for all junction types except localtcp and localssl.–U "user_name"Specifies the WebSEAL server user name. This option requires the –B and –W options. WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.–wIndicates Microsoft Windows 32 bit (Win32) file system support. This option provides all the functionality that is provided by the –i junction option. The option disallows requests that contain file names that might be interpreted as Win32 file name aliases. This option is valid for all junction types except localtcp and localssl. Local junctions prohibit URLs that contain Win32 file name aliases on Win32 but allow such URLs on other platforms.–W "password"Specifies the WebSEAL server password. This option requires the –B and –U options. WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL. This option is valid only with junctions that were created with the type of ssl or sslproxy.–YEnables Tivoli Federated Identity Manager single sign-on (SSO) for the junction. Before you use this option, you must first configure the WebSEAL configuration file to support Tivoli Federated Identity Manager single sign-on over junctions.–z replica_setSpecifies the replica set, as follows: For SMS environments:Sessions on the virtual host junction are managed under the specified replica set. Used to group or separate login sessions among multiple virtual hosts.For non-SMS environments:Sessions on the virtual host junction are managed under the specified replica set. Controls the partitioning of the WebSEAL session cache. The virtual host can be part of the same replica set as any standard junction that is assigned to that same replica set. Standard junctions are assigned to replica sets through the standard-junction-replica-set entry of the [session] stanza.–Z keyfile_pwdSpecifies the password of the key file that is used to encrypt LTPA cookie data. This option requires the –A and –F options. The –A, –F, and –Z options all must be used together. This option is valid for all junction types except localtcp and localssl.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.For more information about gathering statistics, see the Troubleshooting topics in the IBM Knowledge Center. ExampleThe following example creates an SSL type virtual host junction with the vhost-xy-https label. This junction serves the virtual host x.y.com on the junctioned server cruz1.ibm.com. WebSEAL responds to the Host: x.y.com header in SSL (HTTPS) requests by forwarding the requests across this virtual host junction: pdadmin> server task default-webseald-abc.ibm.com virtualhost create \ -t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-https See alsoserver task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. server task virtualhost deleteDeletes a virtual host junction. server task virtualhost listLists all configured virtual host junctions by label name. server task virtualhost removeRemoves the specified server from a virtual host junction. server task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost create

Creates a virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

For local junctions:

server task instance_name-webseald-host_name virtualhost create –t type –d dir –v virtual_host_name [options] vhost_label

For non-local junctions:

server task instance_name-webseald-host_name virtualhost create –t type –h host_name [options] vhost_label

Options

–d dir

Specifies the local directory for a local virtual host junction.

This option is required for localtcp and localssl junction types.

–h host_name

Specifies the DNS host name or IP address of the target server. This option is valid only for non-local junctions; local junctions do not need a host name. Valid values for host_name include any valid IP host name. For example:

www.example.com

–t type

Specifies the type of virtual host junction. This option is required and must be one of the following types:

tcp

tcpproxy

ssl

sslproxy

localtcp

localssl

–v virtual_host_name[:port]

WebSEAL selects a virtual host junction to process a request if the HTTP Host header of the request matches:

The virtual host name by the -v option and

The port number that is specified by the -v option.

The –v option is also used to specify the value of the Host header of the request sent to the server.

The port number is required if the virtual host uses a non-standard port for the protocol. Standard port for TCP is 80; standard port for SSL is 443.

If –v is not specified for tcp, ssl, tcpproxy, and sslproxy type junctions, the junction is selected from the information that is contained in the –h host_name and –p port options.

The –v option is required for localtcp and localssl type junctions

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

options

Specifies the options that you can use with the server task virtualhost create command. (Optional) These options include:

–A

Enables a virtual host junction to support the lightweight third-party authentication mechanism (LTPA). This option requires the –F and –Z options. The –A, –F, and –Z options all must be used together.

This option is valid for all junction types except localtcp and localssl.

–2

You can use this option with the –A option to specify that LTPA version 2 cookies (LtpaToken2) are used. The –A option without the –2 option specifies that LTPA version 1 cookies (LtpaToken) are used.

–b BA_value

Defines how the WebSEAL server passes client identity information in HTTP basic authentication (BA) headers to the virtual host, which is one of the following values:

filter

ignore

supply

gso

This option is valid for all junction types except localtcp and localssl. The default value is filter.

–B

Indicates that WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL. This option requires the –U and –W options.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–c header_type

Inserts the Security Access Manager client identity in HTTP headers across the virtual host junction. The header_type argument can include any combination of the listed Security Access Manager HTTP header types:

{iv_user|iv_user-l}

iv_groups

iv_creds

all

The header types must be comma-separated, and cannot have a space between the types. For example: -c iv_user,iv_groups

Specifying –c all is the same as specifying –c iv_user,iv_groups,iv_creds.

This option is valid for all junction types except localtcp and localssl.

–C

Supports mutual authentication by enabling the front-end WebSEAL server to pass its identity information to the back-end WebSEAL server. The front-end WebSEAL server passes information in a Basic Authentication (BA) header. Additionally, the –C option enables the single sign-on functionality that is provided by the –c option.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–D "dn"

Specifies the distinguished name of the server certificate. This value, matched with the actual certificate DN, enhances authentication and provides mutual authentication over SSL. For example, the certificate for www.example.com might have a DN of

"CN=WWW.EXAMPLE.COM,OU=Software,O=example.com\, Inc,L=Austin,
ST=Texas,C=US"

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–e encoding_type

Specifies the encoding to use when HTTP headers is generated for virtual host junctions. This encoding applies to headers that are generated with both the –c junction option and tag-value. Possible values for encoding are as follows:

utf8_bin

WebSEAL sends the headers in UTF-8.

utf8_uri

WebSEAL sends the headers in UTF-8 but URI also encodes them. This behavior is the default behavior.

lcp_bin

WebSEAL sends the headers in the local code page of the WebSEAL server.

lcp_uri

WebSEAL sends the headers in the local code page of the WebSEAL server, but URI also encodes them.

This option is valid for all junction types except localtcp and localssl.

–f

Forces the replacement (overwrite) of an existing virtual host junction.

This option is used for junctions that were created with any junction type.

–F "keyfile"

Specifies the location of the key file that is used to encrypt LTPA cookie data.

The –F option requires –A and –Z options. The –A, –F, and –Z options all must be used together.

This option is valid for all junction types except localtcp and localssl.

–g vhost_label

The –g option causes a second more virtual host junction to share a protected object space as the initial virtual host junction.

This option is appropriate for junction pairs only (two junctions by using complementary protocols). The option does not support the association of more than two junctions.

–H host_name

Specifies the DNS host name or IP address of the proxy server. The –P option also supports proxy server junctions. Valid values for host_name include any valid IP host name. For example:

proxy.www.example.com

This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.

–i

Indicates that the WebSEAL junction does not treat URLs as case-sensitive. To correctly authorize requests for junctions that are not case-sensitive, WebSEAL does the authorization check on a lowercase version of the URL. For example, a web server that is running on a Windows operating system treats requests for INDEX.HTM and index.htm as requests for the same file.

Junctions to such a web server must be created with the –i or –w option. ACLs or POPs that are attached to objects beneath the junction point must use the lowercase object name. An ACL attached to /junction/index.htm applies to all the following requests if the –i or –w option is used:

/junction/INDEX.HTM

/junction/index.htm

/junction/InDeX.HtM

This option is valid for all junction except for the type of localtcp and localssl. Local junctions are not case-sensitive only on Win32 platforms; all other platforms are case-sensitive.

–k

Sends WebSEAL session cookies to the back-end virtual host. By default, cookies are removed from requests that are sent to the server.

This option is valid for all junction types except localtcp and localssl.

–K "key_label"

Specifies the key label of the client-side certificate that WebSEAL must present to the server. Use of this option allows the virtual host to authenticate the WebSEAL server by using client certificates.

This option is valid only with junctions that were created with the type of ssl and sslproxy.

–l percent

Defines the soft limit for consumption of worker threads.

This option is valid for all junction types except localtcp and localssl.

–L percent

Defines the hard limit for consumption of worker threads.

This option is valid for all junction types except localtcp and localssl.

–p port

Specifies the TCP port of the third-party server. The default value is 80 for TCP junctions and 443 for SSL junctions.

This option is valid for all junction types except localtcp and localssl.

–P port

Specifies the TCP port number for the HTTP proxy server. The –P option is required when the –H option is used.

This option is valid only with junctions that were created with the type of tcpproxy or sslproxy.

–q –S

Specifies the relative path for the query_contents script. By default, Security Access Manager looks for the query_contents script in the /cgi_bin directory. If this directory is different or the query_contents file name is renamed, this option indicates to WebSEAL the new URL to the file. Required for Windows virtual hosts.

This option is valid for all junction types except localtcp and localssl.

–r

Inserts the incoming IP address into the HTTP header across the junction.

This option is valid for all junction types except localtcp and localssl.

–R

Allows the request to proceed but provides the rule failure reason to the junction in an HTTP header. If the –R option is not used and a rule failure occurs, WebSEAL does not allow the request to proceed.

This option is valid for all junction types except localtcp and localssl.

–s

Indicates that the virtual host junction support stateful applications. By default, virtual host junctions are not stateful.

This option is valid for all junction types except localtcp and localssl.

–S

Indicates the location of the forms single sign-on configuration file.

This option is valid for all junction types except localtcp and localssl.

–T {resource | resource_group}

Specifies the name of the GSO resource or resource group. This option is required only when the –b gso option is used.

This option is valid for all junction types except localtcp and localssl.

–u uuid

Specifies the Universally Unique Identifier (UUID) of a server that is connected to WebSEAL by using a stateful virtual host junction (–s option).

This option is valid for all junction types except localtcp and localssl.

–U "user_name"

Specifies the WebSEAL server user name. This option requires the –B and –W options. WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–w

Indicates Microsoft Windows 32 bit (Win32) file system support. This option provides all the functionality that is provided by the –i junction option. The option disallows requests that contain file names that might be interpreted as Win32 file name aliases.

This option is valid for all junction types except localtcp and localssl. Local junctions prohibit URLs that contain Win32 file name aliases on Win32 but allow such URLs on other platforms.

–W "password"

Specifies the WebSEAL server password. This option requires the –B and –U options. WebSEAL uses the BA header information to authenticate to the virtual host and to provide mutual authentication over SSL.

This option is valid only with junctions that were created with the type of ssl or sslproxy.

–Y

Enables Tivoli® Federated Identity Manager single sign-on (SSO) for the junction.

Note: Before you use this option, you must first configure the WebSEAL configuration file to support Tivoli Federated Identity Manager single sign-on over junctions.

–z replica_set

Specifies the replica set, as follows:

For SMS environments:

Sessions on the virtual host junction are managed under the specified replica set. Used to group or separate login sessions among multiple virtual hosts.

For non-SMS environments:

Sessions on the virtual host junction are managed under the specified replica set. Controls the partitioning of the WebSEAL session cache. The virtual host can be part of the same replica set as any standard junction that is assigned to that same replica set. Standard junctions are assigned to replica sets through the standard-junction-replica-set entry of the [session] stanza.

–Z keyfile_pwd

Specifies the password of the key file that is used to encrypt LTPA cookie data. This option requires the –A and –F options. The –A, –F, and –Z options all must be used together.

This option is valid for all junction types except localtcp and localssl.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the s (server administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

For more information about gathering statistics, see the Troubleshooting topics in the IBM Knowledge Center.

Example

The following example creates an SSL type virtual host junction with the vhost-xy-https label. This junction serves the virtual host x.y.com on the junctioned server cruz1.ibm.com. WebSEAL responds to the Host: x.y.com header in SSL (HTTPS) requests by forwarding the requests across this virtual host junction:

pdadmin> server task default-webseald-abc.ibm.com virtualhost create \
-t ssl -h cruz1.ibm.com -v x.y.com vhost-xy-https

See also

server task virtualhost add

server task virtualhost delete

server task virtualhost list

server task virtualhost remove

server task virtualhost show

Parent topic: pdadmin commands

server task virtualhost deleteserver task virtualhost deleteserver task virtualhost deleteDeletes a virtual host junction. junctioned servers virtual hostjunctionsdeleteserver commandsserver task virtualhost deleteRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost delete vhost_label DescriptionThe server task virtualhost delete command deletes a virtual host junction. A virtual host junction cannot be deleted if a second virtual host junction refers to it through the –g option. An error message is returned at such an attempt. Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes 0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed. ExampleThe following example deletes the virtual host junction support-vhost-https from the WebSEAL server abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com virtualhost delete \ support-vhost-https See alsoserver task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. server task virtualhost createCreates a virtual host junction. server task virtualhost listLists all configured virtual host junctions by label name. server task virtualhost removeRemoves the specified server from a virtual host junction. server task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost delete

Deletes a virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost delete vhost_label

Description

The server task virtualhost delete command deletes a virtual host junction. A virtual host junction cannot be deleted if a second virtual host junction refers to it through the –g option. An error message is returned at such an attempt.

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The following example deletes the virtual host junction support-vhost-https from the WebSEAL server abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com virtualhost delete \
support-vhost-https

See also

server task virtualhost add

server task virtualhost create

server task virtualhost list

server task virtualhost remove

server task virtualhost show

Parent topic: pdadmin commands

server task virtualhost listserver task virtualhost listserver task virtualhost listLists all configured virtual host junctions by label name. server commandsserver task virtualhost listjunctioned servers virtual hostlistRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost list Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com. AuthorizationUsers and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@per_vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully.For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleThe following example lists the label names of all virtual host junctions that are configured on the abc.ibm.com WebSEAL server: pdadmin> server task default-webseald-abc.ibm.com virtualhost list Output is like: pubs-vhost-http sales-vhost-https support-vhost-http See alsoserver task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. server task virtualhost createCreates a virtual host junction. server task virtualhost deleteDeletes a virtual host junction. server task virtualhost removeRemoves the specified server from a virtual host junction. server task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost list

Lists all configured virtual host junctions by label name.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost list

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@per_vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The following example lists the label names of all virtual host junctions that are configured on the abc.ibm.com WebSEAL server:

pdadmin> server task default-webseald-abc.ibm.com virtualhost list

Output is like:

pubs-vhost-http
sales-vhost-https
support-vhost-http

See also

server task virtualhost add

server task virtualhost create

server task virtualhost delete

server task virtualhost remove

server task virtualhost show

Parent topic: pdadmin commands

server task virtualhost offlineserver task virtualhost offlineserver task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. server commandsserver task virtualhost offlinejunctioned servers virtual hostofflineRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost offline [–i server_uuid] vhost_label DescriptionThe server task virtualhost offline command places the server that is at this virtual host junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are at this virtual host junction are placed in an offline operational state. Options–i server_uuidSpecifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are at this virtual host junction are placed in an offline operational state. Use the server task virtualhost show command to determine the ID of a specific server. (Optional)instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExamplesIn the following example: The virtual host junction: Has the label support-vhost-https.Is configured on the WebSEAL server abc.ibm.com.Supports the virtual host support.ibm.com.The virtual host support.ibm.com is on the junctioned server int3.ibm.com.There is a requirement to place the int3.ibm.com server in an offline operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command: pdadmin> server task default-webseald-abc.ibm.com \ virtualhost show support-vhost-https Output is like: Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Throttled Throttled at: 2005-03-01-17:07:24 Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1Place this server in an offline operational state by using the following command: pdadmin> server task default-webseald-cruz virtualhost offline \ -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https See alsoserver task offlinePlaces the server that is at this junction in an offline operational state. server task onlinePlaces the server that is at this junction in an online operational state. server task throttlePlaces the server that is at this junction in a throttled operational state. server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost offline

Places the server that is at this virtual host junction in an offline operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost offline [–i server_uuid] vhost_label

Description

The server task virtualhost offline command places the server that is at this virtual host junction in an offline operational state. No additional requests are sent to the specified server. If a server is not specified, all servers that are at this virtual host junction are placed in an offline operational state.

Options

–i server_uuid

Specifies the UUID of the server to place in an offline operational state. If a server is not specified, all servers that are at this virtual host junction are placed in an offline operational state. Use the server task virtualhost show command to determine the ID of a specific server. (Optional)

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Examples

In the following example:

The virtual host junction:

Has the label support-vhost-https.

Is configured on the WebSEAL server abc.ibm.com.

Supports the virtual host support.ibm.com.

The virtual host support.ibm.com is on the junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an offline operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:

pdadmin> server task default-webseald-abc.ibm.com \
virtualhost show support-vhost-https

Output is like:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in an offline operational state by using the following command:

pdadmin> server task default-webseald-cruz virtualhost offline \
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

server task offline

server task online

server task throttle

server task virtualhost online

server task virtualhost throttle

Parent topic: pdadmin commands

server task virtualhost onlineserver task virtualhost onlineserver task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. server commandsserver task virtualhost onlinejunctioned servers virtual hostonlineRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost online [–i server_uuid] vhost_label DescriptionThe server task virtualhost online command places the server that is at this virtual host junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are at this virtual host junction are placed in an online operational state. Options–i server_uuidUUID of the server to place in an online operational state. If a server is not specified, all servers that are at this virtual host junction are placed in an online operational state. Use the server task virtualhost show command to determine the ID of a specific server. (Optional)instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleIn the following example: The virtual host junction: Has the label support-vhost-https.Is configured on the WebSEAL server abc.ibm.com.Supports the virtual host support.ibm.comThe virtual host support.ibm.com is on the junctioned server int3.ibm.com.There is a requirement to place the int3.ibm.com server in an online operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command: pdadmin> server task default-webseald-abc.ibm.com \ virtualhost show support-vhost-https Output is like: Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Offline Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1Place this server in an online operational state by using the following command: pdadmin> server task default-webseald-cruz virtualhost online \ -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https See alsoserver task offlinePlaces the server that is at this junction in an offline operational state. server task onlinePlaces the server that is at this junction in an online operational state. server task throttlePlaces the server that is at this junction in a throttled operational state. server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. server task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost online

Places the server that is at this virtual host junction in an online operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost online [–i server_uuid] vhost_label

Description

The server task virtualhost online command places the server that is at this virtual host junction in an online operational state. The server now resumes normal operation. If a server is not specified, all servers that are at this virtual host junction are placed in an online operational state.

Options

–i server_uuid

UUID of the server to place in an online operational state. If a server is not specified, all servers that are at this virtual host junction are placed in an online operational state. Use the server task virtualhost show command to determine the ID of a specific server. (Optional)

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

In the following example:

The virtual host junction:

Has the label support-vhost-https.

Is configured on the WebSEAL server abc.ibm.com.

Supports the virtual host support.ibm.com

The virtual host support.ibm.com is on the junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in an online operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:

pdadmin> server task default-webseald-abc.ibm.com \
virtualhost show support-vhost-https

Output is like:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Offline
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in an online operational state by using the following command:

pdadmin> server task default-webseald-cruz virtualhost online \
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

server task offline

server task online

server task throttle

server task virtualhost offline

server task virtualhost throttle

Parent topic: pdadmin commands

server task virtualhost removeserver task virtualhost removeserver task virtualhost removeRemoves the specified server from a virtual host junction. server commandsserver task virtualhost removejunctioned servers virtual hostremoveRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost remove –i server_uuid vhost_label Options–i server_uuidSpecifies the UUID of the server to be removed from the virtual host junction. For this command, the –i option, normally used to treat URLs as case-sensitive, operates like the –u option. See the server task show command for details about obtaining the UUID.instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleThe following example removes the junctioned server int4.ibm.com from the virtual host junction support-vhost-https. To determine the UUID of the server to be removed, run the server task virtualhost show command: pdadmin> server task default-webseald-abc.ibm.com \ virtualhost show support-vhost-https Output is like: Virtual Host label: support-vhost-https Type: SSL Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Basic authentication mode: filter Forms based SSO: disabled Authentication HTTP header: do not insert Remote Address HTTP header: do not insert Stateful junction: no Boolean Rule Header: no Delegation support: no Mutually authenticated: no Insert WebSphere LTPA cookies: no Insert WebSEAL session cookies: no Request Encoding: UTF-8, URI Encoded Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Total requests: 1 Server 2: ID: xycecc77-19ve-81y5-4h0a-90267hj5nn57 Server State: running Hostname: int4.ibm.com Port: 444 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Total requests: 1Remove the server from the virtual host junction: pdadmin> server task default-webseald-abc.ibm.com \ virtualhost remove -i xycecc77-19ve-81y5-4h0a-90267hj5nn57 support-vhost-https See alsoserver task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. server task virtualhost createCreates a virtual host junction. server task virtualhost deleteDeletes a virtual host junction. server task virtualhost listLists all configured virtual host junctions by label name. server task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost remove

Removes the specified server from a virtual host junction.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost remove –i server_uuid vhost_label

Options

–i server_uuid

Specifies the UUID of the server to be removed from the virtual host junction. For this command, the –i option, normally used to treat URLs as case-sensitive, operates like the –u option. See the server task show command for details about obtaining the UUID.

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The following example removes the junctioned server int4.ibm.com from the virtual host junction support-vhost-https. To determine the UUID of the server to be removed, run the server task virtualhost show command:

pdadmin> server task default-webseald-abc.ibm.com \
virtualhost show support-vhost-https

Output is like:

Virtual Host label: support-vhost-https
Type: SSL
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Basic authentication mode: filter
Forms based SSO: disabled
Authentication HTTP header: do not insert
Remote Address HTTP header: do not insert
Stateful junction: no
Boolean Rule Header: no
Delegation support: no
Mutually authenticated: no
Insert WebSphere LTPA cookies: no
Insert WebSEAL session cookies: no
Request Encoding: UTF-8, URI Encoded
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1
Server 2:
ID: xycecc77-19ve-81y5-4h0a-90267hj5nn57
Server State: running
Hostname: int4.ibm.com
Port: 444
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1

Remove the server from the virtual host junction:

pdadmin> server task default-webseald-abc.ibm.com \
virtualhost remove -i xycecc77-19ve-81y5-4h0a-90267hj5nn57 support-vhost-https

See also

server task virtualhost add

server task virtualhost create

server task virtualhost delete

server task virtualhost list

server task virtualhost show

Parent topic: pdadmin commands

server task virtualhost showserver task virtualhost showserver task virtualhost showDisplays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed. junctioned servers virtual hostjunctionslist detailsserver commandsserver task virtualhost showRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost show vhost_label Optionsinstance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleThe example shows information for the virtual host junction: With the label support-vhost-https.Configured on the WebSEAL server abc.ibm.com.That supports the virtual host support.ibm.com.The virtual host support.ibm.com is on the junctioned server int3.ibm.com. pdadmin> server task default-webseald-abc.ibm.com \ virtualhost show support-vhost-https Output is like: Virtual Host label: support-vhost-https Type: SSL Junction hard limit: 0 - using global value Junction soft limit: 0 - using global value Active worker threads: 0 Basic authentication mode: filter Forms based SSO: disabled Authentication HTTP header: do not insert Remote Address HTTP header: do not insert Stateful junction: no Boolean Rule Header: no Delegation support: no Mutually authenticated: no Insert WebSphere LTPA cookies: no Insert WebSEAL session cookies: no Request Encoding: UTF-8, URI Encoded Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Total requests: 1 See alsoserver task virtualhost addAdds an additional installed WebSEAL server or server instance to an existing virtual host junction. server task virtualhost createCreates a virtual host junction. server task virtualhost deleteDeletes a virtual host junction. server task virtualhost listLists all configured virtual host junctions by label name. server task virtualhost removeRemoves the specified server from a virtual host junction. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost show

Displays information about the specified virtual host junction. The virtual host junction must exist, or an error is displayed.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost show vhost_label

Options

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the l (list) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

The example shows information for the virtual host junction:

With the label support-vhost-https.

Configured on the WebSEAL server abc.ibm.com.

That supports the virtual host support.ibm.com.

The virtual host support.ibm.com is on the junctioned server int3.ibm.com.

pdadmin> server task default-webseald-abc.ibm.com \
virtualhost show support-vhost-https

Output is like:

Virtual Host label: support-vhost-https
Type: SSL
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Basic authentication mode: filter
Forms based SSO: disabled
Authentication HTTP header: do not insert
Remote Address HTTP header: do not insert
Stateful junction: no
Boolean Rule Header: no
Delegation support: no
Mutually authenticated: no
Insert WebSphere LTPA cookies: no
Insert WebSEAL session cookies: no
Request Encoding: UTF-8, URI Encoded
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1

See also

server task virtualhost add

server task virtualhost create

server task virtualhost delete

server task virtualhost list

server task virtualhost remove

Parent topic: pdadmin commands

server task virtualhost throttleserver task virtualhost throttleserver task virtualhost throttlePlaces the server that is at this virtual host junction in a throttled operational state. server commandsserver task virtualhost throttlejunctioned servers virtual hostthrottleRequires authentication (administrator ID and password) to use this command.Syntaxserver task instance_name-webseald-host_name virtualhost throttle [–i server_uuid] vhost_label DescriptionThe server task virtualhost throttle command places the server that is at this virtual host junction in a throttled operational state. Users can create a session with WebSEAL before the invocation of this command. Only requests from such users continue to be processed by the specified server. If a server is not specified, all servers that are at this virtual host junction are placed in a throttled operational state. Options–i server_uuidSpecifies the UUID of the server to throttle. If a server is not specified, all servers that are at this virtual host junction are placed in a throttled operational state. Use the server task virtualhost show command to determine the ID of a specific server. (Optional)instance_name-webseald-host_nameSpecifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command. The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.vhost_labelSpecifies the label name of the virtual host junction. AuthorizationUsers and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. This command is available only when WebSEAL is installed.ExampleIn the following example, the virtual host junction: Has the label support-vhost-https.Is configured on the WebSEAL server abc.ibm.com.Supports the virtual host support.ibm.com.The virtual host support.ibm.com is on the junctioned server int3.ibm.com.There is a requirement to place the int3.ibm.com server in a throttled operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command: pdadmin> server task default-webseald-abc.ibm.com \ virtualhost show support-vhost-https Output is like: Virtual Host label: support-vhost-https Type: SSL ... Virtual hostname: support.ibm.com Alias: ibm.com Alias: support Virtual Host junction protocol partner: support-vhost-http Server 1: ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77 Server State: running Operational State: Online Hostname: int3.ibm.com Port: 443 Server DN: Query_contents URL: /cgi-bin/query_contents Query-contents: unknown Case insensitive URLs: no Allow Windows-style URLs: yes Current requests: 0 Total requests: 1Place this server in a throttled operational state by using the following command: pdadmin> server task default-webseald-cruz virtualhost throttle \ -i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https See alsoserver task throttlePlaces the server that is at this junction in a throttled operational state. server task offlinePlaces the server that is at this junction in an offline operational state. server task onlinePlaces the server that is at this junction in an online operational state. server task virtualhost offlinePlaces the server that is at this virtual host junction in an offline operational state. server task virtualhost onlinePlaces the server that is at this virtual host junction in an online operational state. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task virtualhost throttle

Places the server that is at this virtual host junction in a throttled operational state.

Requires authentication (administrator ID and password) to use this command.

Syntax

server task instance_name-webseald-host_name virtualhost throttle [–i server_uuid] vhost_label

Description

The server task virtualhost throttle command places the server that is at this virtual host junction in a throttled operational state. Users can create a session with WebSEAL before the invocation of this command. Only requests from such users continue to be processed by the specified server. If a server is not specified, all servers that are at this virtual host junction are placed in a throttled operational state.

Options

–i server_uuid

Specifies the UUID of the server to throttle. If a server is not specified, all servers that are at this virtual host junction are placed in a throttled operational state. Use the server task virtualhost show command to determine the ID of a specific server. (Optional)

instance_name-webseald-host_name

Specifies the full server name of the installed WebSEAL server instance. You must specify this full server name in the exact format as displayed in the output of the server list command.

The instance_name specifies the configured name of the WebSEAL server instance. The webseald designation indicates that the WebSEAL service performs the command task. The host_name is the name of the physical computer where the WebSEAL server is installed.

For example, the configured name of a single WebSEAL server instance is default. The host computer name where the WebSEAL server is installed is abc.ibm.com. Then, the full WebSEAL server name is default-webseald-abc.ibm.com.

If an additional WebSEAL server instance is configured and named web2, the full WebSEAL server name is web2-webseald-abc.ibm.com.

vhost_label

Specifies the label name of the virtual host junction.

Authorization

Users and groups that require access to this command must be given the c (control) permission in the ACL that governs the /WebSEAL/host_name-instance_name/@vhost_label object. For example, the sec_master administrative user is given this permission by default.

Return codes

0

The command completed successfully.

Note: For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not be able to successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: This command is available only when WebSEAL is installed.

Example

In the following example, the virtual host junction:

Has the label support-vhost-https.

Is configured on the WebSEAL server abc.ibm.com.

Supports the virtual host support.ibm.com.

The virtual host support.ibm.com is on the junctioned server int3.ibm.com.

There is a requirement to place the int3.ibm.com server in a throttled operational state. To determine the UUID of this junctioned server, run the server task virtualhost show command:

pdadmin> server task default-webseald-abc.ibm.com \
virtualhost show support-vhost-https

Output is like:

Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Online
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total requests: 1

Place this server in a throttled operational state by using the following command:

pdadmin> server task default-webseald-cruz virtualhost throttle \
-i bacecc66-13ce-11d8-8f0a-09267ea5aa77 support-vhost-https

See also

server task throttle

server task offline

server task online

server task virtualhost offline

server task virtualhost online

Parent topic: pdadmin commands

server task server restartserver task server restartserver task server restartRestarts a WebSEAL server by using the Security Access Manager server task framework. junctioned serversrestartserver commandsserver task server restartThis command requires authentication of administrator ID and password.Syntaxserver task server_name server restart Optionsserver_nameSpecifies the name of the Security Access Manager authorization server restart. AuthorizationUsers and groups that require access to this command must have the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format, for example, 0x14c012f2. See "Error messages" in the IBM Knowledge Center for a list of the Security Access Manager error messages by decimal or hexadecimal codes. The restart is successful only if the WebSEAL server was started by using the pdweb_start script. The script must be running as a daemon on AIX, Linux, or Solaris, or as a service on Windows). The restart command does not work if the WebSEAL server is running in the foreground.The result of the restart is not displayed on the administration console. You must examine the WebSEAL log files to confirm that the server restart was successful.ExampleThe following example restarts server03: pdadmin> server task server03 server restart pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task server restart

Restarts a WebSEAL server by using the Security Access Manager server task framework.

This command requires authentication of administrator ID and password.

Syntax

server task server_name server restart

Options

server_name

Specifies the name of the Security Access Manager authorization server restart.

Authorization

Users and groups that require access to this command must have the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format, for example, 0x14c012f2. See "Error messages" in the IBM Knowledge Center for a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: The restart is successful only if the WebSEAL server was started by using the pdweb_start script. The script must be running as a daemon on AIX®, Linux, or Solaris, or as a service on Windows). The restart command does not work if the WebSEAL server is running in the foreground.

The result of the restart is not displayed on the administration console. You must examine the WebSEAL log files to confirm that the server restart was successful.

Example

The following example restarts server03:

pdadmin> server task server03 server restart

Parent topic: pdadmin commands

server task server syncserver task server syncserver task server syncSynchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework. junctioned serverssynchronizeserver commandsserver task server syncThis command requires authentication of administrator ID and password.Syntaxserver task webseal_server server sync server_name Optionswebseal_serverSpecifies the fully qualified server name of the installed WebSEAL instance.server_nameSpecifies the name of the Security Access Manager authorization server from which data is extracted. Configuration data on the host system is backed up and then synchronized with this data. AuthorizationUsers and groups that require access to this command must have the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format, for example, 0x14c012f2. See "Error messages" in the IBM Knowledge Center for a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example synchronizes configuration data with server default-webseald-abc.ibm.com: pdadmin> server task default-webseald-abc.ibm.com server sync master-webseald-abc.ibm.com pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task server sync

Synchronizes configuration data between two WebSEAL servers by using the Security Access Manager server task framework.

This command requires authentication of administrator ID and password.

Syntax

server task webseal_server server sync server_name

Options

webseal_server

Specifies the fully qualified server name of the installed WebSEAL instance.

server_name

Specifies the name of the Security Access Manager authorization server from which data is extracted. Configuration data on the host system is backed up and then synchronized with this data.

Authorization

Users and groups that require access to this command must have the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format, for example, 0x14c012f2. See "Error messages" in the IBM Knowledge Center for a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example synchronizes configuration data with server default-webseald-abc.ibm.com:

pdadmin> server task default-webseald-abc.ibm.com server sync
master-webseald-abc.ibm.com

Parent topic: pdadmin commands

server task file catserver task file catserver task file catReturns the contents of a specified file to the administration console. This command requires authentication of administrator ID and password.junctioned serverstransfer contentsserver commandsserver task file catSyntaxserver task server_name file cat file_name byte_offset [-max bytes] [-encode] Optionsserver_nameSpecifies the name of the Security Access Manager authorization server on which the file is hosted.file_nameSpecifies the fully qualified name of the file which is to be retrieved.byte_offsetSpecifies the offset in bytes from the start of the file at which the data is retrieved.-max bytesSpecifies the maximum number of bytes to be returned from the file. If you do not specify this parameter, the maximum number of bytes returned is controlled by the max-file-cat-command-length value in the [server] stanza. The max-file-cat-command-length value takes precedence over the -max bytes value. If the specified file is larger than the max-file-cat-command-length value, the returned data is truncated. --encodeDesignates that the contents of the file must be base-64 encoded before it is returned. (Optional) AuthorizationUsers and groups that require access to this command must have the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has this permission by default. Return codes0The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not successfully complete the command. The WebSEAL server returns an error message.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format, for example, 0x14c012f2. See "Error messages" in the IBM Knowledge Center for a list of the Security Access Manager error messages by decimal or hexadecimal codes. For more information about WebSEAL junctions, see the Administering topics in the IBM Knowledge Center.This command is available only when WebSEAL is installed.ExampleThe following example requests the first 512 bytes of data (base-64 encoded) from the readme.txt file. The file is in the /temp/ folder on server03: pdadmin> server task server03 file cat /temp/readme.txt 0 -max 512 -encode The output is the content of the specified file. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

server task file cat

Returns the contents of a specified file to the administration console. This command requires authentication of administrator ID and password.

Syntax

server task server_name file cat file_name byte_offset [-max bytes] [-encode]

Options

server_name

Specifies the name of the Security Access Manager authorization server on which the file is hosted.

file_name

Specifies the fully qualified name of the file which is to be retrieved.

byte_offset

Specifies the offset in bytes from the start of the file at which the data is retrieved.

-max bytes

Specifies the maximum number of bytes to be returned from the file. If you do not specify this parameter, the maximum number of bytes returned is controlled by the max-file-cat-command-length value in the [server] stanza. The max-file-cat-command-length value takes precedence over the -max bytes value. If the specified file is larger than the max-file-cat-command-length value, the returned data is truncated.

--encode

Designates that the contents of the file must be base-64 encoded before it is returned. (Optional)

Authorization

Users and groups that require access to this command must have the s (administration) permission in the ACL that governs the /WebSEAL/host_name-instance_name object. For example, the sec_master administrative user has this permission by default.

Return codes

0

The command completed successfully. For WebSEAL server task commands, the return code is 0 when the command is sent to the WebSEAL server without errors. However, even after the command was successfully sent, the WebSEAL server might not successfully complete the command. The WebSEAL server returns an error message.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format, for example, 0x14c012f2. See "Error messages" in the IBM Knowledge Center for a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Note: For more information about WebSEAL junctions, see the Administering topics in the IBM Knowledge Center.

This command is available only when WebSEAL is installed.

Example

The following example requests the first 512 bytes of data (base-64 encoded) from the readme.txt file. The file is in the /temp/ folder on server03:

pdadmin> server task server03 file cat /temp/readme.txt 0 -max 512 -encode

The output is the content of the specified file.

Parent topic: pdadmin commands

user createuser createuser createCreates a Security Access Manager user. user commandsuser createRequires authentication (administrator ID and password) to use this command.Syntaxuser create [–gsouser] [–no-password-policy] user_name dn cn sn password [groups] DescriptionA user is a registered participant of the secure domain. A GSO user is a Security Access Manager user that additionally has the authority to use single sign-on to work with web resources.You can create users in the Active Directory Lightweight Directory Service (AD LDS) user registry. You must create such users in the same AD LDS partition where the Access Manager Management Domain information is stored.The –gsouser option enables global sign-on capabilities. Users that are created in an Active Directory are automatically given the capability to own single sign-on credentials. This capability cannot be removed. When you use an LDAP user registry, this capability must be explicitly granted. After this capability is granted, it can be removed.The –no-password-policy option allows the administrator to create the user with an initial password that is not checked by the existing global password policies. If this option is not present in the command, the password that is provided is checked against the global password policies. In this case, the user create command fails if the password is invalid, and the error message includes information about what conditions were not met.However, if the administrator applies the password option on the user modify command, the -no-password-policy option is not available. Therefore, the modified password is always checked against the global password policy settings. Options–gsouserEnables the global sign-on (GSO) capabilities for the user. Applies only to users created in an LDAP user registry.–no-password-policyIndicates that password policy is not enforced during the creation of the user account. The non-enforcement does not affect password policy enforcement after user creation. (Optional)cnSpecifies the common name that is assigned to the user that is being created. For example: "Mary"dnSpecifies the registry identifier that is assigned to the user that is being created. The registry identifier must be known before a new user account can be created. The registry identifier must be unique within the user registry. If the user registry is Active Directory, certain characters are not allowed. See Characters disallowed for distinguished namesCertain characters are treated differently by the different user registries. for the list of these characters. The format for a distinguished name is like: "cn=Mary Jones,ou=Austin,o=Tivoli,c=us"groupsSpecifies a list of groups to which the new user is assigned. The format of the group list is a parenthesized list of group names, which are separated by spaces. The groups must exist, or an error is displayed. Examples of groups: deptD4D and printerusers. (Optional)passwordSpecifies the password that is set for the new user. Passwords must adhere to the password policies set by the administrator.snSpecifies the short name of the user that is being created. For example: "Jones"user_nameSpecifies the name for the user to create. This name must be unique. A valid user name is an alphanumeric string that is not case-sensitive. If the user registry is Active Directory, certain characters are not allowed. See Characters disallowed for user and group nameEnvironment aspects such as registries and command shells can affect special character handling. Because of the variability of special character handling in general, avoid the use of special characters. for the list of these characters. If the user is a GSO user, certain characters are not allowed. See Characters disallowed for GSO namesCertain characters are disallowed for GSO names. for the list of these characters. Consider that you did not change the 7 - bit checking default value during configuration of the Sun web server. In this case, turn off checking so that non-ASCII characters can be stored in attributes.Examples of user names are dlucas, sec_master, "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example, entered as one line, creates user dlucas: pdadmin sec_master> user create –gsouser dlucas "cn=Diana Lucas,ou=Austin,o=Tivoli,c=US" "Diana Lucas" Lucas lucaspwdThe following example, entered as one line, creates user maryj: pdadmin sec_master> user create –gsouser maryj "cn=Mary Jones,o=tivoli,c=us" Mary Jones maryjpwd To make the user accounts valid, you must use the user modify command to set the account-valid option to yes. See alsouser deleteDeletes the specified Security Access Manager user. Optionally deletes the information of the user in the user registry. user importCreates a Security Access Manager user by importing user data that exists in the user registry. user modifyChanges various user account attributes. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

user create

Creates a Security Access Manager user.

Requires authentication (administrator ID and password) to use this command.

Syntax

user create [–gsouser] [–no-password-policy] user_name dn cn sn password [groups]

Description

A user is a registered participant of the secure domain. A GSO user is a Security Access Manager user that additionally has the authority to use single sign-on to work with web resources.

You can create users in the Active Directory Lightweight Directory Service (AD LDS) user registry. You must create such users in the same AD LDS partition where the Access Manager Management Domain information is stored.

The –gsouser option enables global sign-on capabilities. Users that are created in an Active Directory are automatically given the capability to own single sign-on credentials. This capability cannot be removed. When you use an LDAP user registry, this capability must be explicitly granted. After this capability is granted, it can be removed.

The –no-password-policy option allows the administrator to create the user with an initial password that is not checked by the existing global password policies. If this option is not present in the command, the password that is provided is checked against the global password policies. In this case, the user create command fails if the password is invalid, and the error message includes information about what conditions were not met.

However, if the administrator applies the password option on the user modify command, the -no-password-policy option is not available. Therefore, the modified password is always checked against the global password policy settings.

Options

–gsouser

Enables the global sign-on (GSO) capabilities for the user. Applies only to users created in an LDAP user registry.

–no-password-policy

Indicates that password policy is not enforced during the creation of the user account. The non-enforcement does not affect password policy enforcement after user creation. (Optional)

cn

Specifies the common name that is assigned to the user that is being created. For example: "Mary"

dn

Specifies the registry identifier that is assigned to the user that is being created. The registry identifier must be known before a new user account can be created. The registry identifier must be unique within the user registry. If the user registry is Active Directory, certain characters are not allowed. See Characters disallowed for distinguished names for the list of these characters.

The format for a distinguished name is like:

"cn=Mary Jones,ou=Austin,o=Tivoli,c=us"

groups

Specifies a list of groups to which the new user is assigned. The format of the group list is a parenthesized list of group names, which are separated by spaces. The groups must exist, or an error is displayed. Examples of groups: deptD4D and printerusers. (Optional)

password

Specifies the password that is set for the new user. Passwords must adhere to the password policies set by the administrator.

sn

Specifies the short name of the user that is being created. For example: "Jones"

user_name

Specifies the name for the user to create. This name must be unique. A valid user name is an alphanumeric string that is not case-sensitive. If the user registry is Active Directory, certain characters are not allowed. See Characters disallowed for user and group name for the list of these characters. If the user is a GSO user, certain characters are not allowed. See Characters disallowed for GSO names for the list of these characters.

Note: Consider that you did not change the 7 - bit checking default value during configuration of the Sun web server. In this case, turn off checking so that non-ASCII characters can be stored in attributes.

Examples of user names are dlucas, sec_master, "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example, entered as one line, creates user dlucas:

pdadmin sec_master> user create –gsouser dlucas "cn=Diana
Lucas,ou=Austin,o=Tivoli,c=US" "Diana Lucas" Lucas lucaspwd

The following example, entered as one line, creates user maryj:

pdadmin sec_master> user create –gsouser maryj "cn=Mary Jones,o=tivoli,c=us"
Mary Jones maryjpwd

To make the user accounts valid, you must use the user modify command to set the account-valid option to yes.

See also

user delete

user import

user modify

Parent topic: pdadmin commands

user deleteuser deleteuser deleteDeletes the specified Security Access Manager user. Optionally deletes the information of the user in the user registry. user commandsuser deleteRequires authentication (administrator ID and password) to use this command.Syntaxuser delete [–registry] user_name Options–registryDeletes the information of the user from the user registry. If this option is not specified, the registry user information can be used to create another Security Access Manager user by using the user import command. (Optional)user_nameSpecifies the name of the account to be deleted. Any resource credentials that are associated with a user account are automatically removed at the same time the user account is deleted. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example deletes the dlucas user: pdadmin sec_master> user delete dlucas See alsouser createCreates a Security Access Manager user. user importCreates a Security Access Manager user by importing user data that exists in the user registry. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

user delete

Deletes the specified Security Access Manager user. Optionally deletes the information of the user in the user registry.

Requires authentication (administrator ID and password) to use this command.

Syntax

user delete [–registry] user_name

Options

–registry

Deletes the information of the user from the user registry. If this option is not specified, the registry user information can be used to create another Security Access Manager user by using the user import command. (Optional)

user_name

Specifies the name of the account to be deleted. Any resource credentials that are associated with a user account are automatically removed at the same time the user account is deleted. The user must exist, or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example deletes the dlucas user:

pdadmin sec_master> user delete dlucas

See also

user create

user import

Parent topic: pdadmin commands

user importuser importuser importCreates a Security Access Manager user by importing user data that exists in the user registry. user commandsuser importimportuserRequires authentication (administrator ID and password) to use this command.If the user registry is Active Directory Lightweight Directory Service (AD LDS), import within the AD LDS partition where the Security Access Manager management domain information is stored.Syntaxuser import [–gsouser] user_name dn [group_name] DescriptionImported user accounts are created invalid by default. To make the user account valid, you must use the user modify command to set the account-valid option to yes. Options–gsouserSpecifies that the user has single sign-on capabilities. (Optional)dnSpecifies the registry identifier of the user that is being imported. This identifier must exist in the user registry and must not be associated with another user in the same Security Access Manager secure domain. The format for a distinguished name is like: cn=Claude Wright,ou=Austin,o=Tivoli,c=usgroup_nameSpecifies an optional group to which the user is being added. The group must exist, or an error is displayed. (Optional)Examples of group names are Credit, Sales, and Test-group.user_nameSpecifies a unique Security Access Manager user name. This user is created from information that exists in the user registry. A valid user name is an alphanumeric string that is not case-sensitive. If the user is a GSO user, certain characters are not allowed. See Characters disallowed for GSO namesCertain characters are disallowed for GSO names. for the list of these characters. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExampleThe following example creates the user mlucaser by importing information from the registry user cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US: pdadmin sec_master> user import –gsouser mlucaser "cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US" See alsouser createCreates a Security Access Manager user. user modifyChanges various user account attributes. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

user import

Creates a Security Access Manager user by importing user data that exists in the user registry.

Requires authentication (administrator ID and password) to use this command.

If the user registry is Active Directory Lightweight Directory Service (AD LDS), import within the AD LDS partition where the Security Access Manager management domain information is stored.

Syntax

user import [–gsouser] user_name dn [group_name]

Description

Imported user accounts are created invalid by default. To make the user account valid, you must use the user modify command to set the account-valid option to yes.

Options

–gsouser

Specifies that the user has single sign-on capabilities. (Optional)

dn

Specifies the registry identifier of the user that is being imported. This identifier must exist in the user registry and must not be associated with another user in the same Security Access Manager secure domain. The format for a distinguished name is like:

cn=Claude Wright,ou=Austin,o=Tivoli,c=us

group_name

Specifies an optional group to which the user is being added. The group must exist, or an error is displayed. (Optional)

Examples of group names are Credit, Sales, and Test-group.

user_name

Specifies a unique Security Access Manager user name. This user is created from information that exists in the user registry. A valid user name is an alphanumeric string that is not case-sensitive. If the user is a GSO user, certain characters are not allowed. See Characters disallowed for GSO names for the list of these characters.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Example

The following example creates the user mlucaser by importing information from the registry user cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US:

pdadmin sec_master> user import –gsouser mlucaser
"cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US"

See also

user create

user modify

Parent topic: pdadmin commands

user listuser listuser listLists users by Security Access Manager user name or by registry identifier. user commandsuser listuser commandsuser listRequires authentication (administrator ID and password) to use this command.Syntaxuser list pattern max_returnuser list-dn pattern max_return Optionslist pattern max_returnSpecifies the pattern for the principal name. The pattern can include a mixture of wildcard and string constants. The specified pattern is case-sensitive. For example: *luca* The pattern max_return options specify the maximum number of entries that are found and returned for a single request. The number that is returned is also governed by the server configuration, which specifies the maximum number of results that can be returned as part of a search operation.The actual maximum returned entries is the minimum number of results between the pattern max_return and the configured value on the server. The configured value is taken from the max-search-size=[0|num_entries] entry in the [ldap] stanza. The [ldap] stanza is in the ldap.conf configuration file.list-dn pattern max_returnSpecifies the pattern for the common name (CN) portion of the registry identifier of the user. When you specify the pattern, you can exclude the cn= component. The pattern can include a mixture of wildcard and string constants, and is case-sensitive. For example, *luca*. The returned list contains users that are defined in the user registry but are not necessarily Security Access Manager users. Users that are not Security Access Manager users can be imported into Security Access Manager by using the user import command.When the user registry contains many user definitions, use wildcard characters with discretion. When a pattern includes one or more wildcard characters, the command attempts to find all user definitions that match the specified pattern. However, the command displays only the specified number of matching definitions in the user registry. For example, if the user registry contains 10,000 definitions, specifying a single wildcard (user list * 100) displays only the first 100 matching definitions but finds all 10,000 definitions. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example lists the users that match the specified pattern: pdadmin sec_master> user list *luca* 2 The output is like: dlucas mlucaserThe following example lists the users that match the specified registry identifier: pdadmin sec_master> user list-dn *luca* 2 The output is like: cn=Diana Lucas,ou=Austin,o=Tivoli,c=US cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US See alsouser showDisplays the properties of the specified user. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

user list

Lists users by Security Access Manager user name or by registry identifier.

Requires authentication (administrator ID and password) to use this command.

Syntax

user list pattern max_return

user list-dn pattern max_return

Options

list pattern max_return

Specifies the pattern for the principal name. The pattern can include a mixture of wildcard and string constants. The specified pattern is case-sensitive. For example: *luca*

The pattern max_return options specify the maximum number of entries that are found and returned for a single request. The number that is returned is also governed by the server configuration, which specifies the maximum number of results that can be returned as part of a search operation.

The actual maximum returned entries is the minimum number of results between the pattern max_return and the configured value on the server. The configured value is taken from the max-search-size=[0|num_entries] entry in the [ldap] stanza. The [ldap] stanza is in the ldap.conf configuration file.

list-dn pattern max_return

Specifies the pattern for the common name (CN) portion of the registry identifier of the user. When you specify the pattern, you can exclude the cn= component. The pattern can include a mixture of wildcard and string constants, and is case-sensitive. For example, *luca*.

The returned list contains users that are defined in the user registry but are not necessarily Security Access Manager users. Users that are not Security Access Manager users can be imported into Security Access Manager by using the user import command.

Note: When the user registry contains many user definitions, use wildcard characters with discretion. When a pattern includes one or more wildcard characters, the command attempts to find all user definitions that match the specified pattern. However, the command displays only the specified number of matching definitions in the user registry.

For example, if the user registry contains 10,000 definitions, specifying a single wildcard (user list * 100) displays only the first 100 matching definitions but finds all 10,000 definitions.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2).

See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example lists the users that match the specified pattern:

pdadmin sec_master> user list *luca* 2

The output is like:

dlucas
mlucaser

The following example lists the users that match the specified registry identifier:

pdadmin sec_master> user list-dn *luca* 2

The output is like:

cn=Diana Lucas,ou=Austin,o=Tivoli,c=US
cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US

See also

user show

Parent topic: pdadmin commands

user modifyuser modifyuser modifyChanges various user account attributes. user commandsuser modifyRequires authentication (administrator ID and password) to use this command.Syntaxuser modify user_name account-valid {yes|no}user modify user_name password passworduser modify user_name password-valid {yes|no}user modify user_name description descriptionuser modify user_name gsouser {yes|no} Optionsaccount-valid {yes|no}Enables or disables the specified user account. A user cannot log in with a disabled account. Valid values are yes and no.password passwordModifies the user password. The new password must comply with password policies in effect. When a password is set or changed, the password must comply to:The defined Security Access Manager password policy andThe password policies for any underlying operating systems or user registry.When the password policy is enforced, Security Access Manager first validates compliance against the Security Access Manager password policy currently in effect. Then, Security Access Manager validates compliance against the underlying user registry. Although a password complies to the defined Security Access Manager policy, it might fail against the password policy of the underlying user registry. Old passwords can still be used after a password change when: You are using Active Directory as your user registry.The Active Directory server is running on Windows 2003 SP1 or later.For more information, see the following web page:http://support.microsoft.com/?id=906305password-valid {yes|no}Validates or invalidates the password for the specified user account. Valid values are yes and no. If the value is no, the password seems expired and the user cannot log in using the password. For a user to log in, an administrator must set the valid state to yes. The user can also authenticate by using another method, such as using a certificate. Another reason a user might not be able to authenticate with a specified password is because the maximum password age was exceeded. If you check and find that the password-valid is set to yes, then try changing the value for the policy set max-password-age parameter. Only an administrator or a user that has the authority can set the max-password-age policy on a user account. A user cannot set this policy on their own account. This policy sets the maximum time, in days, that a password is valid. Time is relative to the last time the password was changed.When you change the value for password-valid or reset policy set max-password-age, you do not have to change the password.If you reset a password, the password-valid parameter automatically switches to back to yes, and the max-password-age parameter resets the age to expire. For example, if the maximum password age is set to 30 days, another 30 days begins from the time you reset the password.user_nameSpecifies the name of the account to be modified. The user must exist, or an error is displayed. A valid user name is an alphanumeric string that is not case-sensitive. If the user is a GSO user, certain characters are not allowed. See Characters disallowed for GSO namesCertain characters are disallowed for GSO names. for the list of these characters. Examples of user names are dlucas, sec_master, and "Mary Jones"description descriptionSpecifies any text string that describes the user that is being created. Examples of user description are "Head of department" and "Department number of employee".gsouser {yes|no}Enables global sign-on (GSO) capabilities for the specified user. Valid values are yes and no. Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example enables the specified user account: pdadmin sec_master> user modify dlucas account-valid yesThe following example changes the password for a user account: pdadmin sec_master> user modify dlucas password newpasswd See alsouser createCreates a Security Access Manager user. user importCreates a Security Access Manager user by importing user data that exists in the user registry. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

user modify

Changes various user account attributes.

Requires authentication (administrator ID and password) to use this command.

Syntax

user modify user_name account-valid {yes|no}

user modify user_name password password

user modify user_name password-valid {yes|no}

user modify user_name description description

user modify user_name gsouser {yes|no}

Options

account-valid {yes|no}

Enables or disables the specified user account. A user cannot log in with a disabled account. Valid values are yes and no.

password password

Modifies the user password. The new password must comply with password policies in effect.

When a password is set or changed, the password must comply to:

The defined Security Access Manager password policy and

The password policies for any underlying operating systems or user registry.

When the password policy is enforced, Security Access Manager first validates compliance against the Security Access Manager password policy currently in effect. Then, Security Access Manager validates compliance against the underlying user registry. Although a password complies to the defined Security Access Manager policy, it might fail against the password policy of the underlying user registry.

Note: Old passwords can still be used after a password change when:

You are using Active Directory as your user registry.

The Active Directory server is running on Windows 2003 SP1 or later.

For more information, see the following web page:

http://support.microsoft.com/?id=906305

password-valid {yes|no}

Validates or invalidates the password for the specified user account. Valid values are yes and no. If the value is no, the password seems expired and the user cannot log in using the password. For a user to log in, an administrator must set the valid state to yes. The user can also authenticate by using another method, such as using a certificate.

Another reason a user might not be able to authenticate with a specified password is because the maximum password age was exceeded. If you check and find that the password-valid is set to yes, then try changing the value for the policy set max-password-age parameter. Only an administrator or a user that has the authority can set the max-password-age policy on a user account. A user cannot set this policy on their own account. This policy sets the maximum time, in days, that a password is valid. Time is relative to the last time the password was changed.

When you change the value for password-valid or reset policy set max-password-age, you do not have to change the password.

If you reset a password, the password-valid parameter automatically switches to back to yes, and the max-password-age parameter resets the age to expire. For example, if the maximum password age is set to 30 days, another 30 days begins from the time you reset the password.

user_name

Specifies the name of the account to be modified. The user must exist, or an error is displayed. A valid user name is an alphanumeric string that is not case-sensitive. If the user is a GSO user, certain characters are not allowed. See Characters disallowed for GSO names for the list of these characters. Examples of user names are dlucas, sec_master, and "Mary Jones"

description description

Specifies any text string that describes the user that is being created. Examples of user description are "Head of department" and "Department number of employee".

gsouser {yes|no}

Enables global sign-on (GSO) capabilities for the specified user. Valid values are yes and no.

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example enables the specified user account:

pdadmin sec_master> user modify dlucas account-valid yes

The following example changes the password for a user account:

pdadmin sec_master> user modify dlucas password newpasswd

See also

user create

user import

Parent topic: pdadmin commands

user showuser showuser showDisplays the properties of the specified user. user commandsuser showThis command requires authentication of administrator ID and password.Syntaxuser show user_nameuser show-dn dnuser show-groups user_name Optionsshow user_nameSpecifies the name of the user to display. The user must exist, or an error is displayed. Based on the Policy Server and WebSEAL configuration settings, the following information is displayed: Last login: YYYY-mm-dd-HH:MM:SS Last Password Change: YYYY-mm-dd-HH:MM:SSThe system displays the local time of the computer where pdadmin was run. For more information about the last login and last password change configuration settings, see the Stanza Reference topics in the IBM Knowledge Center.Examples of user names are dlucas, sec_master, and "Mary Jones".show-dn dnDisplays the user that is specified by the identifier of the user in the user registry. The returned user is defined in the user registry, but it is not necessarily a Security Access Manager user. Users that are not Security Access Manager users can be imported into Security Access Manager by use of the user import command. The format for a distinguished name is like: cn=Claude Wright,ou=Austin,o=Tivoli,c=usBased on the Policy Server and WebSEAL configuration settings, the following information is displayed: Last login: YYYY-mm-dd-HH:MM:SS Last Password Change: YYYY-mm-dd-HH:MM:SSThe system displays the local time of the computer where pdadmin was run. For more information about last login and last password change configuration settings, see the Stanza Reference topics in the IBM Knowledge Center.show-groups user_nameDisplays the groups in which the specified user is a member. The user must exist, or an error is displayed. Examples of user names are dlucas, sec_master, and "Mary Jones". Return codes0The command completed successfully.1The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes. ExamplesThe following example displays the user account information for testuser: pdadmin sec_master> user show testuser The output is like: Login ID: testuser LDAP DN: cn=testuser,o=tivoli,c=us LDAP CN: test LDAP SN: test Description: a test user Is SecUser: yes Is GSO user: no Account valid: no Password valid: yes Last login: 1999-09-05-01:08:55 Last Password Change: 1999-09-04-05:06:45The following example displays the groups of which the specified user is a member: pdadmin sec_master> user show-groups dlucas The output is like: sales credit engineeringThe following example provides more information about the user when the registry identifier is specified: pdadmin sec_master> user show-dn "cn=Diana Lucas,ou=Austin,o=Tivoli,c=US" The output is like: Login ID: dlucas LDAP dn: cn=Diana Lucas,ou=Austin,o=Tivoli Inc,c=US LDAP cn: Diana Lucas LDAP sn: Lucas Description: Diana Lucas, Credit Dept HCUS IS SecUser: true IS GSO user: false Account valid: true Password valid: true Last login: 1999-09-05-01:08:55 Last Password Change: 1999-09-04-05:06:45 Authentication mechanism: Default:LDAP See alsouser listLists users by Security Access Manager user name or by registry identifier. pdadmin commandsThe pdadmin command-line utility is installed as part of the IBM Security Access Manager runtime package.

user show

Displays the properties of the specified user.

This command requires authentication of administrator ID and password.

Syntax

user show user_name

user show-dn dn

user show-groups user_name

Options

show user_name

Specifies the name of the user to display. The user must exist, or an error is displayed.

Based on the Policy Server and WebSEAL configuration settings, the following information is displayed:

Last login: YYYY-mm-dd-HH:MM:SS
Last Password Change: YYYY-mm-dd-HH:MM:SS

The system displays the local time of the computer where pdadmin was run. For more information about the last login and last password change configuration settings, see the Stanza Reference topics in the IBM Knowledge Center.

Examples of user names are dlucas, sec_master, and "Mary Jones".

show-dn dn

Displays the user that is specified by the identifier of the user in the user registry. The returned user is defined in the user registry, but it is not necessarily a Security Access Manager user. Users that are not Security Access Manager users can be imported into Security Access Manager by use of the user import command. The format for a distinguished name is like:

cn=Claude Wright,ou=Austin,o=Tivoli,c=us

Based on the Policy Server and WebSEAL configuration settings, the following information is displayed:

Last login: YYYY-mm-dd-HH:MM:SS
Last Password Change: YYYY-mm-dd-HH:MM:SS

The system displays the local time of the computer where pdadmin was run. For more information about last login and last password change configuration settings, see the Stanza Reference topics in the IBM Knowledge Center.

show-groups user_name

Displays the groups in which the specified user is a member. The user must exist, or an error is displayed.

Examples of user names are dlucas, sec_master, and "Mary Jones".

Return codes

0

The command completed successfully.

1

The command failed. When a command fails, the pdadmin command provides a description of the error and an error status code in hexadecimal format (for example, 0x14c012f2). See "Error messages" in the IBM Knowledge Center. This reference provides a list of the Security Access Manager error messages by decimal or hexadecimal codes.

Examples

The following example displays the user account information for testuser:

pdadmin sec_master> user show testuser

The output is like:

Login ID: testuser
LDAP DN: cn=testuser,o=tivoli,c=us
LDAP CN: test
LDAP SN: test
Description: a test user
Is SecUser: yes
Is GSO user: no
Account valid: no
Password valid: yes
Last login: 1999-09-05-01:08:55
Last Password Change: 1999-09-04-05:06:45

The following example displays the groups of which the specified user is a member:

pdadmin sec_master> user show-groups dlucas

The output is like:

sales
credit
engineering

The following example provides more information about the user when the registry identifier is specified:

pdadmin sec_master> user show-dn "cn=Diana Lucas,ou=Austin,o=Tivoli,c=US"

The output is like:

Login ID: dlucas
LDAP dn: cn=Diana Lucas,ou=Austin,o=Tivoli
Inc,c=US
LDAP cn: Diana Lucas
LDAP sn: Lucas
Description: Diana Lucas, Credit Dept HCUS
IS SecUser: true
IS GSO user: false
Account valid: true
Password valid: true
Last login: 1999-09-05-01:08:55
Last Password Change: 1999-09-04-05:06:45
Authentication mechanism: Default:LDAP

See also

user list

Parent topic: pdadmin commands

Password limitations and characters allowed in object namesPassword limitations and characters allowed in object namesPassword limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed. passwordslimitationsobject namecharactersobject namecharacters allowedSome factors that affect which characters are allowed are restrictions of the underlying user registry, server, or operating system.This section describes the following limitations: Web command referenceThese reference topics describe IBM Security Access Manager commands.General password policiesYou can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies. Additionally, you can override global password policies by setting individual password policies for the specified user. Character limitations for passwords and user namesThere are password characters that are valid, but must be treated differently when you run the pdadmin utility. These special characters have special meaning to the utility.Characters allowed for secure domain namesA valid local domain name is an alphanumeric, case-sensitive string. String characters are expected to be characters that are part of the local code set. Characters disallowed for user and group nameEnvironment aspects such as registries and command shells can affect special character handling. Because of the variability of special character handling in general, avoid the use of special characters.Characters disallowed for distinguished namesCertain characters are treated differently by the different user registries. Characters disallowed for GSO namesCertain characters are disallowed for GSO names.Characters disallowed for authorization rule namesCertain characters are disallowed for authorization rule names.Characters disallowed for ACL policy namesCertain characters are disallowed for ACL policy names.Characters disallowed for POP namesCertain characters are disallowed for POP names.

Password limitations and characters allowed in object names

When you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Some factors that affect which characters are allowed are restrictions of the underlying user registry, server, or operating system.

This section describes the following limitations:

General password policies
You can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies. Additionally, you can override global password policies by setting individual password policies for the specified user.

Character limitations for passwords and user names
There are password characters that are valid, but must be treated differently when you run the pdadmin utility. These special characters have special meaning to the utility.

Characters allowed for secure domain names
A valid local domain name is an alphanumeric, case-sensitive string. String characters are expected to be characters that are part of the local code set.

Characters disallowed for user and group name
Environment aspects such as registries and command shells can affect special character handling. Because of the variability of special character handling in general, avoid the use of special characters.

Characters disallowed for distinguished names
Certain characters are treated differently by the different user registries.

Characters disallowed for GSO names
Certain characters are disallowed for GSO names.

Characters disallowed for authorization rule names
Certain characters are disallowed for authorization rule names.

Characters disallowed for ACL policy names
Certain characters are disallowed for ACL policy names.

Characters disallowed for POP names
Certain characters are disallowed for POP names.

Parent topic: Web command reference

General password policiesGeneral password policiesGeneral password policiesYou can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies. Additionally, you can override global password policies by setting individual password policies for the specified user. passwordsgeneral policiesFor example, you can change a password policy so that the password policy: Is set only for a specific user.Overrides any password policy that is set globally for all users.Using the Web Portal Manager or pdadmin commands, you can provide the following types of global password policies for all users: Minimum length that is allowed for a passwordMaximum age that is allowed for a passwordMinimum number of alphanumeric characters that are allowed in a passwordMinimum number of non-alphanumeric characters that are allowed in a passwordMaximum number of repeated characters that are allowed in a passwordWhether spaces are allowed in the passwordBy default, passwords must meet the following criteria: A minimum of eight alphanumeric characters, with a minimum of one number and four letters.A maximum of two repeated characters.The valid range for minimum and maximum numbers can be any number. However, a reasonable number must be used for the task you are wanting to complete. For example, a minimum password length must: Be long enough to protect your system.Not be so short as to make it easy for someone to determine your password by trying different combinations.Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

General password policies

You can change global user settings, such as password policies, login-failure policies, access policies, and account expiration policies. Additionally, you can override global password policies by setting individual password policies for the specified user.

For example, you can change a password policy so that the password policy:

Is set only for a specific user.

Overrides any password policy that is set globally for all users.

Using the Web Portal Manager or pdadmin commands, you can provide the following types of global password policies for all users:

Minimum length that is allowed for a password

Maximum age that is allowed for a password

Minimum number of alphanumeric characters that are allowed in a password

Minimum number of non-alphanumeric characters that are allowed in a password

Maximum number of repeated characters that are allowed in a password

Whether spaces are allowed in the password

By default, passwords must meet the following criteria:

A minimum of eight alphanumeric characters, with a minimum of one number and four letters.

A maximum of two repeated characters.

The valid range for minimum and maximum numbers can be any number. However, a reasonable number must be used for the task you are wanting to complete. For example, a minimum password length must:

Be long enough to protect your system.

Not be so short as to make it easy for someone to determine your password by trying different combinations.

Parent topic: Password limitations and characters allowed in object names

Character limitations for passwords and user namesCharacter limitations for passwords and user namesCharacter limitations for passwords and user namesThere are password characters that are valid, but must be treated differently when you run the pdadmin utility. These special characters have special meaning to the utility.passwordscharacter limitationsuser namescharacter limitationscharacter limitationspasswordscharacter limitationsuser nameslimitations, characterspasswordslimitations, charactersuser namesEnclose the password or user name in double quotation marks (") to escape the special character when: Setting or changing user passwords by using user modify.Logging in using login.Otherwise, you receive an error message.To escape the double quotation mark special character, enclose the password or user name in double quotation marks and use the backward slash (\) escape character. For example, to escape the password abc"123, type the string "abc\"123" in the pdadmin command when you type the password by using the –p option. When the interactive login command is used, no double quotation marks and escape character are needed.The following special characters either must not be used or they must be escaped when using the pdadmin command: Comma (,)Double quotation (")Left parenthesis (()Number sign (#)Right parenthesis ())Avoid the use of these characters as the first character in the password when setting or modifying the password with the user modify command: Hyphen (-)Left brace ({)Number sign (#)Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Character limitations for passwords and user names

There are password characters that are valid, but must be treated differently when you run the pdadmin utility. These special characters have special meaning to the utility.

Enclose the password or user name in double quotation marks (") to escape the special character when:

Setting or changing user passwords by using user modify.

Logging in using login.

Otherwise, you receive an error message.

To escape the double quotation mark special character, enclose the password or user name in double quotation marks and use the backward slash (\) escape character. For example, to escape the password abc"123, type the string "abc\"123" in the pdadmin command when you type the password by using the –p option. When the interactive login command is used, no double quotation marks and escape character are needed.

The following special characters either must not be used or they must be escaped when using the pdadmin command:

Comma (,)

Double quotation (")

Left parenthesis (()

Number sign (#)

Right parenthesis ())

Avoid the use of these characters as the first character in the password when setting or modifying the password with the user modify command:

Hyphen (-)

Left brace ({)

Number sign (#)

Parent topic: Password limitations and characters allowed in object names

Characters allowed for secure domain namesCharacters allowed for secure domain namesCharacters allowed for secure domain namesA valid local domain name is an alphanumeric, case-sensitive string. String characters are expected to be characters that are part of the local code set. secure domain names, characters alloweddomain names, allowed charactersspecial characters, allowed for secure domain namesThe following characters, numbers, and special characters can be used for secure domain names during use of the Web Portal Manager or pdadmin commands. For example, for US English, secure domain names can contain a combination of the following characters: Letters (a-z A-Z)Numbers (0–9)Ampersand (&)Asterisk (*)At sign (@)Hyphen (-)Period (.)Plus sign (+)Underscore (_)You cannot use a space in the domain name. The minimum and maximum lengths of the domain name, if there are limits, are imposed by the underlying registry. Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Characters allowed for secure domain names

A valid local domain name is an alphanumeric, case-sensitive string. String characters are expected to be characters that are part of the local code set.

The following characters, numbers, and special characters can be used for secure domain names during use of the Web Portal Manager or pdadmin commands.

For example, for US English, secure domain names can contain a combination of the following characters:

Letters (a-z A-Z)

Numbers (0–9)

Ampersand (&)

Asterisk (*)

At sign (@)

Hyphen (-)

Period (.)

Plus sign (+)

Underscore (_)

You cannot use a space in the domain name. The minimum and maximum lengths of the domain name, if there are limits, are imposed by the underlying registry.

Parent topic: Password limitations and characters allowed in object names

Characters disallowed for user and group nameCharacters disallowed for user and group nameCharacters disallowed for user and group nameEnvironment aspects such as registries and command shells can affect special character handling. Because of the variability of special character handling in general, avoid the use of special characters.user namesdisallowed charactersgroup names, disallowed charactersspecial characters, disalloweduser namesspecial characters, disallowedgroup namescharacter, disallowed user namescharacter, disallowed group namesAvoid the following character in user and group names that are defined by using distinguished name strings: Forward slash (/)If Microsoft Active Directory is the user registry, care must be taken with user names and group names that contain the following character: Period (.)A period (.) cannot be the last character of a user or group short name; for example: jdoe. and jdoe.@my_ad_domain.com are invalid user names. If Microsoft Active Directory is the user registry, user names and group names can contain all Unicode characters except for the following characters: Asterisk (*)At sign (@)Colon (:)Equal sign (=)Forward slash (/)Left square bracket ([)Question mark (?)Right square bracket (])Vertical bar (|)Backward slash (\)Double quotation (")Left angle bracket (<)Right angle bracket (>)Plus sign (+)Semicolon (;)An at sign (@) is not allowed unless it is used to specify the domain. For example, user@mydomain.com is allowed; user@name@mydomain.com is not allowed.The following characters are accepted in LDAP:Comma (,)Plus sign (+)Double quotation (")Add a prefix with a backward slash (\) to escape any double quotation character in the user name.Backward slash (\)Left angle bracket (<)Right angle bracket (>)Semicolon (;)If you use special characters with the pdadmin utility, enclose each argument of the user or group command with double quotation marks. The double quotation marks allow the argument to be entered without being subject to interpretation by the operating system shell command processor.Because of the variability of special character handling in general, avoid the use of special characters.Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Characters disallowed for user and group name

Environment aspects such as registries and command shells can affect special character handling. Because of the variability of special character handling in general, avoid the use of special characters.

Avoid the following character in user and group names that are defined by using distinguished name strings:

Forward slash (/)

If Microsoft Active Directory is the user registry, care must be taken with user names and group names that contain the following character:

Period (.)

A period (.) cannot be the last character of a user or group short name; for example: jdoe. and jdoe.@my_ad_domain.com are invalid user names.

If Microsoft Active Directory is the user registry, user names and group names can contain all Unicode characters except for the following characters:

Asterisk (*)

At sign (@)

Colon (:)

Equal sign (=)

Forward slash (/)

Left square bracket ([)

Question mark (?)

Right square bracket (])

Vertical bar (|)

Backward slash (\)

Double quotation (")

Left angle bracket (<)

Right angle bracket (>)

Plus sign (+)

Semicolon (;)

Note: An at sign (@) is not allowed unless it is used to specify the domain. For example, user@mydomain.com is allowed; user@name@mydomain.com is not allowed.

The following characters are accepted in LDAP:

Comma (,)

Plus sign (+)

Double quotation (")

Note: Add a prefix with a backward slash (\) to escape any double quotation character in the user name.

Backward slash (\)

Left angle bracket (<)

Right angle bracket (>)

Semicolon (;)

If you use special characters with the pdadmin utility, enclose each argument of the user or group command with double quotation marks. The double quotation marks allow the argument to be entered without being subject to interpretation by the operating system shell command processor.

Because of the variability of special character handling in general, avoid the use of special characters.

Parent topic: Password limitations and characters allowed in object names

Characters disallowed for distinguished namesCharacters disallowed for distinguished namesCharacters disallowed for distinguished namesCertain characters are treated differently by the different user registries. special characters, disalloweddistinguished namescharacter, disallowed distinguished namesIn general, you can use special characters within a distinguished name (DN). However, certain special characters require an additional escape character. The following special characters must be escaped when used in a distinguished name: Comma (,)Plus sign (+)Semicolon (;)Because of differences in registries and command shell processors, avoid the backward slash (\) character in distinguished names.Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed. Characters disallowed for Microsoft Active Directory distinguished namesIf Microsoft Active Directory is the user registry, certain special characters are not allowed in a distinguished name (DN). However, if the character is preceded by an additional escape character or is encoded in hexadecimal, then, it is allowed in a DN.

Characters disallowed for distinguished names

Certain characters are treated differently by the different user registries.

In general, you can use special characters within a distinguished name (DN). However, certain special characters require an additional escape character. The following special characters must be escaped when used in a distinguished name:

Comma (,)

Plus sign (+)

Semicolon (;)

Because of differences in registries and command shell processors, avoid the backward slash (\) character in distinguished names.

Characters disallowed for Microsoft Active Directory distinguished names
If Microsoft Active Directory is the user registry, certain special characters are not allowed in a distinguished name (DN). However, if the character is preceded by an additional escape character or is encoded in hexadecimal, then, it is allowed in a DN.

Parent topic: Password limitations and characters allowed in object names

Characters disallowed for Microsoft Active Directory distinguished namesCharacters disallowed for Microsoft Active Directory distinguished namesCharacters disallowed for Microsoft Active Directory distinguished namesIf Microsoft Active Directory is the user registry, certain special characters are not allowed in a distinguished name (DN). However, if the character is preceded by an additional escape character or is encoded in hexadecimal, then, it is allowed in a DN. Microsoft Active Directory, disalloweddistinguished namescharacter, disallowed distinguished namesTo encode in hexadecimal, replace the character with a backward slash (\) followed by two hexadecimal digits.The following characters must be escaped by using the backward slash (\) character before they are used in a distinguished name: Number sign (#) at the beginning of the stringA space at the end of the stringComma (,) Double quotation (")Left angle bracket (<)Plus sign (+)Right angle bracket (>)Semicolon (;)Because of differences in registries and command shell processors, avoid the backward slash (\) character in distinguished names.For other reserved characters, such as an equal sign (=), asterisk (*), or a non-UTF-8 character, the character must be encoded in hexadecimal. Example 1To create a user with a distinguished name that contains a comma next to the separator: pdadmin sec_master> user create "johndoe" "cn=doe\,john,cn=users,dc=mydomain,dc=com" John Doe password1Example 2To create a user with a distinguished name that contains a carriage return, which is a reserved character: pdadmin sec_master> user create "johndoe" "cn=doe\ODJohn,cn=users,dc=mydomain,dc=com" John Doe password1 The hexadecimal representation of a carriage return is 0D.Example 3To create a user with a distinguished name that contains a number sign (#): pdadmin sec_master>user create "#pounduser" "cn=\#pounduser,cn=users,dc=mydomain,dc=com" "#pound" "user" password1Characters disallowed for distinguished namesCertain characters are treated differently by the different user registries.

Characters disallowed for Microsoft Active Directory distinguished names

If Microsoft Active Directory is the user registry, certain special characters are not allowed in a distinguished name (DN). However, if the character is preceded by an additional escape character or is encoded in hexadecimal, then, it is allowed in a DN.

To encode in hexadecimal, replace the character with a backward slash (\) followed by two hexadecimal digits.

The following characters must be escaped by using the backward slash (\) character before they are used in a distinguished name:

Number sign (#) at the beginning of the string

A space at the end of the string

Comma (,)

Double quotation (")

Left angle bracket (<)

Plus sign (+)

Right angle bracket (>)

Semicolon (;)

Because of differences in registries and command shell processors, avoid the backward slash (\) character in distinguished names.

For other reserved characters, such as an equal sign (=), asterisk (*), or a non-UTF-8 character, the character must be encoded in hexadecimal.

Example 1

To create a user with a distinguished name that contains a comma next to the separator:

pdadmin sec_master> user create "johndoe"
"cn=doe\,john,cn=users,dc=mydomain,dc=com" John Doe password1

Example 2

To create a user with a distinguished name that contains a carriage return, which is a reserved character:

pdadmin sec_master> user create "johndoe"
"cn=doe\ODJohn,cn=users,dc=mydomain,dc=com" John Doe password1

The hexadecimal representation of a carriage return is 0D.

Example 3

To create a user with a distinguished name that contains a number sign (#):

pdadmin sec_master>user create "#pounduser"
"cn=\#pounduser,cn=users,dc=mydomain,dc=com" "#pound" "user"
password1

Parent topic: Characters disallowed for distinguished names

Characters disallowed for GSO namesCharacters disallowed for GSO namesCharacters disallowed for GSO namesCertain characters are disallowed for GSO names.GSO names, disallowed charactersspecial characters, disallowedGSO namescharacter, disallowed GSO namesYou cannot use the following characters to create a global sign-on (GSO) user name, GSO resource name, or GSO resource group name: Asterisk (*)At sign (@)Backward slash (\)Colon (:)Comma (,)Double quotation (")Equal sign (=)Exclamation point (!)Left angle bracket (<)Left parenthesis (()Plus sign (+)Number sign (#)Right angle bracket (>)Right parenthesis ())Semicolon (;)Vertical bar (|)It is possible to use most of these characters for other LDAP-related data. However, these characters have special meaning in LDAP DN syntax and filters. Examples of other LDAP-related data are: common name (CN), distinguished name (DN), and short name (SN) of a user.Before you use any of these characters in user and group names, consult the documentation for your user registry to determine the effect of special characters.Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Characters disallowed for GSO names

Certain characters are disallowed for GSO names.

You cannot use the following characters to create a global sign-on (GSO) user name, GSO resource name, or GSO resource group name:

Asterisk (*)

At sign (@)

Backward slash (\)

Colon (:)

Comma (,)

Double quotation (")

Equal sign (=)

Exclamation point (!)

Left angle bracket (<)

Left parenthesis (()

Plus sign (+)

Number sign (#)

Right angle bracket (>)

Right parenthesis ())

Semicolon (;)

Vertical bar (|)

It is possible to use most of these characters for other LDAP-related data. However, these characters have special meaning in LDAP DN syntax and filters. Examples of other LDAP-related data are: common name (CN), distinguished name (DN), and short name (SN) of a user.

Before you use any of these characters in user and group names, consult the documentation for your user registry to determine the effect of special characters.

Parent topic: Password limitations and characters allowed in object names

Characters disallowed for authorization rule namesCharacters disallowed for authorization rule namesCharacters disallowed for authorization rule namesCertain characters are disallowed for authorization rule names.authorization rule names, disallowed charactersspecial characters, disallowedauthorization rule namescharacter, disallowed authorization rule namesThese characters cannot be used in the name of an authorization rule when you use the Web Portal Manager or pdadmin commands.Ampersand (&)Asterisk (*)At sign (@)Backward slash (\)Colon (:)Comma (,)Double quotation (")Equal sign (=)Exclamation point (!)Left angle bracket (<)Left parenthesis (()Plus sign (+)Number sign (#)Right angle bracket (>)Right parenthesis ())Semicolon (;)Vertical bar (|)A valid authorization rule name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Characters disallowed for authorization rule names

Certain characters are disallowed for authorization rule names.

These characters cannot be used in the name of an authorization rule when you use the Web Portal Manager or pdadmin commands.

Ampersand (&)

Asterisk (*)

At sign (@)

Backward slash (\)

Colon (:)

Comma (,)

Double quotation (")

Equal sign (=)

Exclamation point (!)

Left angle bracket (<)

Left parenthesis (()

Plus sign (+)

Number sign (#)

Right angle bracket (>)

Right parenthesis ())

Semicolon (;)

Vertical bar (|)

A valid authorization rule name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

Parent topic: Password limitations and characters allowed in object names

Characters disallowed for ACL policy namesCharacters disallowed for ACL policy namesCharacters disallowed for ACL policy namesCertain characters are disallowed for ACL policy names.ACL policy names, disallowed charactersspecial characters, disallowedACL policy namescharacter, disallowed ACL policy namesThese characters cannot be used in the name of an access control list (ACL) policy when you use the Web Portal Manager or pdadmin commands: Ampersand (&)Asterisk (*)At sign (@)Backward slash (\)Colon (:)Comma (,)Double quotation (")Equal sign (=)Exclamation point (!)Forward slash (/)Left angle bracket (<)Left parenthesis (()Period (.)Plus sign (+)Number sign (#)Right angle bracket (>)Right parenthesis ())Semicolon (;)Vertical bar (|)A valid ACL policy name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Characters disallowed for ACL policy names

Certain characters are disallowed for ACL policy names.

These characters cannot be used in the name of an access control list (ACL) policy when you use the Web Portal Manager or pdadmin commands:

Ampersand (&)

Asterisk (*)

At sign (@)

Backward slash (\)

Colon (:)

Comma (,)

Double quotation (")

Equal sign (=)

Exclamation point (!)

Forward slash (/)

Left angle bracket (<)

Left parenthesis (()

Period (.)

Plus sign (+)

Number sign (#)

Right angle bracket (>)

Right parenthesis ())

Semicolon (;)

Vertical bar (|)

A valid ACL policy name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

Parent topic: Password limitations and characters allowed in object names

Characters disallowed for POP namesCharacters disallowed for POP namesCharacters disallowed for POP namesCertain characters are disallowed for POP names.protected object policy (POP) characters, disallowed special characters, disallowedPOPscharacter, disallowed POPsAvoid the use of the following characters in the name of a protected object policy (POP) when you use the Web Portal Manager or pdadmin commands: Ampersand (&)Asterisk (*)At sign (@)Backward slash (\)Colon (:)Comma (,)Double quotation (")Equal sign (=)Exclamation point (!)Forward slash (/)Left angle bracket (<)Left parenthesis (()Period (.)Plus sign (+)Number sign (#)Right angle bracket (>)Right parenthesis ())Semicolon (;)Vertical bar (|)A valid POP name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.Although a POP name can contain 1 or more of these characters, the results of using such a POP are undefined.Password limitations and characters allowed in object namesWhen you specify Security Access Manager user names, group names, distinguished names, POP names, ACL policies, authorization rules, and domain names, certain characters might be disallowed.

Characters disallowed for POP names

Certain characters are disallowed for POP names.

Avoid the use of the following characters in the name of a protected object policy (POP) when you use the Web Portal Manager or pdadmin commands:

Ampersand (&)

Asterisk (*)

At sign (@)

Backward slash (\)

Colon (:)

Comma (,)

Double quotation (")

Equal sign (=)

Exclamation point (!)

Forward slash (/)

Left angle bracket (<)

Left parenthesis (()

Period (.)

Plus sign (+)

Number sign (#)

Right angle bracket (>)

Right parenthesis ())

Semicolon (;)

Vertical bar (|)

A valid POP name is an alphanumeric string that is not case-sensitive. String values are expected to be characters that are part of the local code set. Spaces are not allowed.

Note: Although a POP name can contain 1 or more of these characters, the results of using such a POP are undefined.

Parent topic: Password limitations and characters allowed in object names

Using response filesUsing response filesUsing response filesA response file is a text file that contains product and system information, sometimes used in configuration. response filesSome utilities can be run in either command-line mode or response file mode. In command-line mode, all parameters must be specified from the command line. In response file mode, the utility obtains the necessary parameters from the response file. You must manually create the response file by entering all parameters.Within response files, stanza labels display within brackets, such as [stanza-name]. Each stanza in a Security Access Manager response file contains one or more key value pairs. Key value pairs express information as a paired set of parameters. Each stanza entry is a key-value pair in the following format: key = value In the response file, the key is equal to the parameter in command-line mode. The following example shows that when there is a -parameter specified in command-line mode, the key in response file mode is the same, but without the preceding dash.ExamplesThe following example uses the /tmp/rspfile/cars_pdacld.rsp response file to configure an audit server by using SSL and password authentication: amauditcfg –rspfile /tmp/rspfile/cars_pdacld.rspThe /tmp/rspfile/cars_pdacld.rsp response file contains the following data: [amauditcfg] action = config srv_cfg_file = /opt/PolicyDirector/etc/ivacld.conf audit_srv_url = https://hostname:9443/CommonAuditService/services/Emitter enable_ssl = yes audit_key_file = /certs/WSclient.kdb audit_stash_file = /certs/WSclient.sth enable_pwd_auth = yes audit_id = administrator_id audit_pwd = passwordIn contrast, the following example uses command-line mode to configure an audit server by using SSL and password authentication: amauditcfg -action config \ -srv_cfg_file /opt/PolicyDirector/etc/ivacld.conf \ -audit_srv_url https://hostname:9443/CommonAuditService/services/Emitter \ -enable_ssl yes -audit_key_file /certs/WSclient.kdb \ -audit_stash_file /certs/WSclient.sth -enable_pwd_auth yes \ -audit_id administrator_id -auditpwd password Web command referenceThese reference topics describe IBM Security Access Manager commands.

Using response files

A response file is a text file that contains product and system information, sometimes used in configuration.

Some utilities can be run in either command-line mode or response file mode.

In command-line mode, all parameters must be specified from the command line.

In response file mode, the utility obtains the necessary parameters from the response file. You must manually create the response file by entering all parameters.

Within response files, stanza labels display within brackets, such as [stanza-name]. Each stanza in a Security Access Manager response file contains one or more key value pairs. Key value pairs express information as a paired set of parameters. Each stanza entry is a key-value pair in the following format:

key = value

In the response file, the key is equal to the parameter in command-line mode. The following example shows that when there is a -parameter specified in command-line mode, the key in response file mode is the same, but without the preceding dash.

Examples

The following example uses the /tmp/rspfile/cars_pdacld.rsp response file to configure an audit server by using SSL and password authentication:

amauditcfg –rspfile /tmp/rspfile/cars_pdacld.rsp

The /tmp/rspfile/cars_pdacld.rsp response file contains the following data:

[amauditcfg]
action = config
srv_cfg_file = /opt/PolicyDirector/etc/ivacld.conf
audit_srv_url = https://hostname:9443/CommonAuditService/services/Emitter
enable_ssl = yes
audit_key_file = /certs/WSclient.kdb
audit_stash_file = /certs/WSclient.sth
enable_pwd_auth = yes
audit_id = administrator_id
audit_pwd = password

In contrast, the following example uses command-line mode to configure an audit server by using SSL and password authentication:

amauditcfg -action config \
  -srv_cfg_file /opt/PolicyDirector/etc/ivacld.conf \
  -audit_srv_url https://hostname:9443/CommonAuditService/services/Emitter \
  -enable_ssl yes -audit_key_file /certs/WSclient.kdb \
  -audit_stash_file /certs/WSclient.sth -enable_pwd_auth yes \
  -audit_id administrator_id -auditpwd password

Parent topic: Web command reference

Web Reverse Proxy Stanza ReferenceThese reference topics describe configuration parameters that you can specify for the Web Reverse Proxy.ReferenceReference information is organized to provide quick access to specific information, such as the description of a certain command-line parameter.Stanza reference

Web Reverse Proxy Stanza Reference

These reference topics describe configuration parameters that you can specify for the Web Reverse Proxy.

Stanza reference

Parent topic: Reference

Stanza referenceStanza referencestanza referenceThis guide provides a complete stanza reference for the WebSEAL configuration file, alphabetized by stanza name.You can use the appliance Local Management Interface (LMI) to edit the WebSEAL configuration file. On the Reverse Proxy management page, select the appropriate WebSEAL instance and click Manage > Configuration > Edit Configuration File to open the Advanced Configuration File Editor. You can use this editor to directly edit the WebSEAL configuration file. Web Reverse Proxy Stanza ReferenceThese reference topics describe configuration parameters that you can specify for the Web Reverse Proxy.[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.[authentication-levels] stanzaUse the [authentication-levels] stanza to define the step-up authentication levels.[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.[azn-decision-info] stanzaUse the [azn-decision-info] stanza to define any extra information for the authorization framework to use when it is making authorization decisions. This extra information is obtained from elements of the HTTP request.[aznapi-external-authzn-services] stanzaUse the [aznapi-external-authzn-services] stanza to configure the OAuth External Authorization Service (EAS). [ba] stanzaUse the [ba] stanza to configure basic authentication.[cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.[cdsso-incoming-attributes] stanzaUse the [cdsso-incoming-attributes] stanza to specify the handling (extract or ignore) of each attribute in the cross-domain single sign-on token.[cdsso-peers] stanzaUse the [cdsso-peers] stanza to specify the peer servers that are participating in cross-domain single sign-on.[cdsso-token-attributes] stanzaUse the [cdsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single sign-on token.[certificate] stanzaUse the [certificate] stanza to configure certificate authentication.[cert-map-authn] stanzaUse the [cert-map-authn] stanza to configure the Cross Domain Authentication Service (CDAS).[cfg-db-cmd:entries] stanzaUse the [cfg-db-cmd:entries] stanza to define configuration entry settings when you use the server sync commands.[cfg-db-cmd:files] stanzaUse the [cfg-db-cmd:files] stanza entry to define settings for files that are included in the configuration database.[cluster] stanzaUse the [cluster] stanza to configure a clustered WebSEAL server environment.[compress-mime-types] stanzaUse the [compress-mime-types] stanza to control the HTTP data compression for specific MIME types.[compress-user-agents] stanzaUse the [compress-user-agents] stanza to explicitly enable or disable compression for various browsers. You can configure WebSEAL to use the user-agent header that is sent by the client to determine whether to enable or disable HTTP compression.[content] stanzaUse the [content] stanza to specify the format of macro data strings that are inserted into HTML server response pages. The data is inserted into the WebSEAL HTML files in either UTF-8 format or local code page format.[content-cache] stanzaUse the [content-cache] stanza to configure WebSEAL content caching.[content-encodings] stanzaUse the [content-encodings] stanza to map document extensions to encoding types. WebSEAL uses this mapping to determine the correct MIME type to report in its response content-type header for local junction files.[content-mime-types] stanzaUse the [content-mime-types] stanza to define the MIME type for specific document extensions. [credential-policy-attributes] stanzaUse the [credential-policy-attributes] stanza to specify the Security Access Manager policy values that are stored in credentials during authentication.[credential-refresh-attributes] stanzaUse the [credential-refresh-attributes] stanza to configure the credential refresh behavior in WebSEAL.[dsess] stanzaUse the [dsess] stanza to configure the distributed session cache.[dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.[eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).[eai-trigger-urls] stanzaUse the [eai-trigger-urls] stanza to specify trigger URL strings for the external authentication interface (EAI). When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.[e-community-domains] stanzaUse the [e-community-domains] stanza to list the e-community cookie domains that are used by virtual host junctions.[e-community-domain-keys] stanzaUse the [e-community-domain-keys] stanza to list the key files that WebSEAL can use to encrypt and decrypt the tokens that are sent between the servers in the e-community.[e-community-domain-keys:domain] stanzaUse the [e-community-domain-keys:domain] stanza to specify the appropriate keys for each domain that is defined in the [e-community-domains] stanza.[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on. [ecsso-incoming-attributes] stanzaUse the [ecsso-incoming-attributes] stanza to specify how the token consume module handles extended attributes in the e-community single sign-on token. The attributes can either be extracted or ignored.[ecsso-token-attributes] stanzaUse the [ecsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that WebSEAL adds to an extended attribute list when it creates a user credential.[enable-redirects] stanzaUse the [enable-redirects] stanza to enable automatic redirection for each of the applicable authentication methods. The authentication methods include forms authentication, basic authentication, certificate authentication, and EAI authentication.[failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.[failover-add-attributes] stanzaUse the [failover-add-attributes] stanza to add attributes to the failover authentication cookie. These attributes can include extended attributes from a user credential and session time stamps.[failover-restore-attributes] stanzaUse the [failover-restore-attributes] stanza to configure WebSEAL to extract certain attributes from the failover authentication cookie and place them into the user credential. [filter-advanced-encodings] stanzaUse the [filter-advanced-encodings] stanza to configure the types of URL encoding that are detected and filtered.[filter-content-types] stanzaUse the [filter-content-types] stanza to specify the content (MIME) types of the documents in which WebSEAL filters tag-based static URLs.[filter-events] stanzaUse the [filter-events] stanza to identify HTML tags that might contain JavaScript. WebSEAL searches these tags to filter any absolute URLs embedded in JavaScript event handlers.[filter-request-headers] stanzaUse the [filter-request-headers] stanza to configure extra HTTP headers for WebSEAL to filter before it sends a request to a junctioned server.[filter-schemes] stanzaUse the [filter-schemes] stanza to list URL schemes that are not to be filtered by WebSEAL in responses from junctioned application servers.[filter-url] stanzaUse the [filter-url] stanza to specify the HTML tags and attributes that WebSEAL filters in responses from junctioned servers.[flow-data] stanzaUse the [flow-data] stanza to configure the recording of flow data statistics in WebSEAL.[forms] stanzaUse the [forms] stanza to configure forms authentication in WebSEAL.[gso-cache] stanzaUse the [gso-cache] stanza to define Global Signon (GSO) settings.[header-names] stanzaUse the [header-names] stanza to define the HTTP header information in the request that WebSEAL sends to junctioned applications.[http-method-perms] stanzaUse this stanza to define the permissions that are required to perform a request with a particular HTTP method.[http-transformations] stanzaUse the [http-transformations] stanza to define the HTTP transformation settings.[http-transformations:<resource-name>] stanzaUse this stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name> component of the stanza name must be changed to the actual name of the resource.[http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files. [ICAP:<resource>] stanzaUse the [ICAP:<resource>] stanza to define a single ICAP resource. [interfaces] stanza[itim] stanza[jdb-cmd:replace] stanza[junction] stanza[junction:junction_name] stanza[ldap] stanza[local-response-macros] stanza[local-response-redirect] stanza[logging] stanza[ltpa] stanza[ltpa-cache] stanza[mpa] stanza[oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.[oauth-eas] stanza[obligations-levels-mapping] stanza[obligations-urls-mapping] stanzaUse this stanza to define a URL to be used to satisfy an obligation.[p3p-header] stanza[PAM] stanza[pam-resource:<URI>] stanza[password-strength] stanzaUse the [password-strength] stanza to define settings for the password strength module.[preserve-cookie-names] stanza[process-root-filter] stanza[reauthentication] stanza[replica-sets] stanza[rsp-header-names] stanzaDefines static HTTP headers that will be added to every HTTP response from the WebSEAL server.[rtss-eas] stanza[rtss-cluster:<cluster>] stanza[script-filtering] stanza[server] stanza[session] stanza[server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.[session-cookie-domains] stanza[session-http-headers] stanza[snippet-filter] stanzaUse the [snippet-filter] stanza to configure parameters associated with the snippet filter.[snippet-filter:<uri>] stanzaUse the [snippet-filter:<uri>] stanza to configure the snippet filter for a particular resource.[spnego] stanzaUse the [spnego] stanza to configure Kerberos authentication.[ssl] stanza[ssl-qop] stanza[ssl-qop-mgmt-default] stanza[ssl-qop-mgmt-networks] stanza[step-up] stanza[system-environment-variables] stanza[tfimsso:<jct-id>] stanza[tfim-cluster:<cluster>] stanza[token] stanzaUse this stanza to define your token settings.[user-agent] stanzaUse the [user-agent] stanza to specify a category name for a particular user-agent string in the HTTP Request header. WebSEAL uses the user-agent string to categorize the incoming requests to make flow data statistics more meaningful.[user-attribute-definitions] stanzaUse this stanza to modify the data type, the category, or both of a custom attribute. [user-map-authn] stanzaUse the [user-map-authn] stanza to define authenticated user mapping settings.[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.Appendix: Supported GSKit attributesYou can configure the these GSKit attributes with Security Access Manager.

Stanza reference

This guide provides a complete stanza reference for the WebSEAL configuration file, alphabetized by stanza name.

You can use the appliance Local Management Interface (LMI) to edit the WebSEAL configuration file. On the Reverse Proxy management page, select the appropriate WebSEAL instance and click Manage > Configuration > Edit Configuration File to open the Advanced Configuration File Editor. You can use this editor to directly edit the WebSEAL configuration file.

[acnt-mgt] stanza
Use the [acnt-mgt] stanza to configure the WebSEAL account management pages.

[authentication-levels] stanza
Use the [authentication-levels] stanza to define the step-up authentication levels.

[aznapi-configuration] stanza
Use the [aznapi-configuration] stanza to configure the authorization API services.

[azn-decision-info] stanza
Use the [azn-decision-info] stanza to define any extra information for the authorization framework to use when it is making authorization decisions. This extra information is obtained from elements of the HTTP request.

[aznapi-external-authzn-services] stanza
Use the [aznapi-external-authzn-services] stanza to configure the OAuth External Authorization Service (EAS).

[ba] stanza
Use the [ba] stanza to configure basic authentication.

[cdsso] stanza
Use the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

[cdsso-incoming-attributes] stanza
Use the [cdsso-incoming-attributes] stanza to specify the handling (extract or ignore) of each attribute in the cross-domain single sign-on token.

[cdsso-peers] stanza
Use the [cdsso-peers] stanza to specify the peer servers that are participating in cross-domain single sign-on.

[cdsso-token-attributes] stanza
Use the [cdsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single sign-on token.

[certificate] stanza
Use the [certificate] stanza to configure certificate authentication.

[cert-map-authn] stanza
Use the [cert-map-authn] stanza to configure the Cross Domain Authentication Service (CDAS).

[cfg-db-cmd:entries] stanza
Use the [cfg-db-cmd:entries] stanza to define configuration entry settings when you use the server sync commands.

[cfg-db-cmd:files] stanza
Use the [cfg-db-cmd:files] stanza entry to define settings for files that are included in the configuration database.

[cluster] stanza
Use the [cluster] stanza to configure a clustered WebSEAL server environment.

[compress-mime-types] stanza
Use the [compress-mime-types] stanza to control the HTTP data compression for specific MIME types.

[compress-user-agents] stanza
Use the [compress-user-agents] stanza to explicitly enable or disable compression for various browsers. You can configure WebSEAL to use the user-agent header that is sent by the client to determine whether to enable or disable HTTP compression.

[content] stanza
Use the [content] stanza to specify the format of macro data strings that are inserted into HTML server response pages. The data is inserted into the WebSEAL HTML files in either UTF-8 format or local code page format.

[content-cache] stanza
Use the [content-cache] stanza to configure WebSEAL content caching.

[content-encodings] stanza
Use the [content-encodings] stanza to map document extensions to encoding types. WebSEAL uses this mapping to determine the correct MIME type to report in its response content-type header for local junction files.

[content-mime-types] stanza
Use the [content-mime-types] stanza to define the MIME type for specific document extensions.

[credential-policy-attributes] stanza
Use the [credential-policy-attributes] stanza to specify the Security Access Manager policy values that are stored in credentials during authentication.

[credential-refresh-attributes] stanza
Use the [credential-refresh-attributes] stanza to configure the credential refresh behavior in WebSEAL.

[dsess] stanza
Use the [dsess] stanza to configure the distributed session cache.

[dsess-cluster] stanza
Use the [dsess-cluster] to configure a distributed session cache cluster.

[eai] stanza
Use the [eai] stanza to configure the external authentication interface (EAI).

[eai-trigger-urls] stanza
Use the [eai-trigger-urls] stanza to specify trigger URL strings for the external authentication interface (EAI). When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.

[e-community-domains] stanza
Use the [e-community-domains] stanza to list the e-community cookie domains that are used by virtual host junctions.

[e-community-domain-keys] stanza
Use the [e-community-domain-keys] stanza to list the key files that WebSEAL can use to encrypt and decrypt the tokens that are sent between the servers in the e-community.

[e-community-domain-keys:domain] stanza
Use the [e-community-domain-keys:domain] stanza to specify the appropriate keys for each domain that is defined in the [e-community-domains] stanza.

[e-community-sso] stanza
Use the [e-community-sso] stanza to configure e-community single sign-on.

[ecsso-incoming-attributes] stanza
Use the [ecsso-incoming-attributes] stanza to specify how the token consume module handles extended attributes in the e-community single sign-on token. The attributes can either be extracted or ignored.

[ecsso-token-attributes] stanza
Use the [ecsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that WebSEAL adds to an extended attribute list when it creates a user credential.

[enable-redirects] stanza
Use the [enable-redirects] stanza to enable automatic redirection for each of the applicable authentication methods. The authentication methods include forms authentication, basic authentication, certificate authentication, and EAI authentication.

[failover] stanza
Use the [failover] stanza to configure the use of failover cookies in WebSEAL.

[failover-add-attributes] stanza
Use the [failover-add-attributes] stanza to add attributes to the failover authentication cookie. These attributes can include extended attributes from a user credential and session time stamps.

[failover-restore-attributes] stanza
Use the [failover-restore-attributes] stanza to configure WebSEAL to extract certain attributes from the failover authentication cookie and place them into the user credential.

[filter-advanced-encodings] stanza
Use the [filter-advanced-encodings] stanza to configure the types of URL encoding that are detected and filtered.

[filter-content-types] stanza
Use the [filter-content-types] stanza to specify the content (MIME) types of the documents in which WebSEAL filters tag-based static URLs.

[filter-events] stanza
Use the [filter-events] stanza to identify HTML tags that might contain JavaScript. WebSEAL searches these tags to filter any absolute URLs embedded in JavaScript event handlers.

[filter-request-headers] stanza
Use the [filter-request-headers] stanza to configure extra HTTP headers for WebSEAL to filter before it sends a request to a junctioned server.

[filter-schemes] stanza
Use the [filter-schemes] stanza to list URL schemes that are not to be filtered by WebSEAL in responses from junctioned application servers.

[filter-url] stanza
Use the [filter-url] stanza to specify the HTML tags and attributes that WebSEAL filters in responses from junctioned servers.

[flow-data] stanza
Use the [flow-data] stanza to configure the recording of flow data statistics in WebSEAL.

[forms] stanza
Use the [forms] stanza to configure forms authentication in WebSEAL.

[gso-cache] stanza
Use the [gso-cache] stanza to define Global Signon (GSO) settings.

[header-names] stanza
Use the [header-names] stanza to define the HTTP header information in the request that WebSEAL sends to junctioned applications.

[http-method-perms] stanza
Use this stanza to define the permissions that are required to perform a request with a particular HTTP method.

[http-transformations] stanza
Use the [http-transformations] stanza to define the HTTP transformation settings.

[http-transformations:<resource-name>] stanza
Use this stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name> component of the stanza name must be changed to the actual name of the resource.

[http-updates] stanza
Use the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

[ICAP:<resource>] stanza
Use the [ICAP:<resource>] stanza to define a single ICAP resource.

[interfaces] stanza

[itim] stanza

[jdb-cmd:replace] stanza

[junction] stanza

[junction:junction_name] stanza

[ldap] stanza

[local-response-macros] stanza

[local-response-redirect] stanza

[logging] stanza

[ltpa] stanza

[ltpa-cache] stanza

[mpa] stanza

[oauth] stanza
Use the [oauth] stanza to configure Open Authentication (OAuth) settings.

[oauth-eas] stanza

[obligations-levels-mapping] stanza

[obligations-urls-mapping] stanza
Use this stanza to define a URL to be used to satisfy an obligation.

[p3p-header] stanza

[PAM] stanza

[pam-resource:<URI>] stanza

[password-strength] stanza
Use the [password-strength] stanza to define settings for the password strength module.

[preserve-cookie-names] stanza

[process-root-filter] stanza

[reauthentication] stanza

[replica-sets] stanza

[rsp-header-names] stanza
Defines static HTTP headers that will be added to every HTTP response from the WebSEAL server.

[rtss-eas] stanza

[rtss-cluster:<cluster>] stanza

[script-filtering] stanza

[server] stanza

[session] stanza

[server:<instance>] stanza
This stanza defines a back-end LDAP server that can be used for federated registries.

[session-cookie-domains] stanza

[session-http-headers] stanza

[snippet-filter] stanza
Use the [snippet-filter] stanza to configure parameters associated with the snippet filter.

[snippet-filter:<uri>] stanza
Use the [snippet-filter:<uri>] stanza to configure the snippet filter for a particular resource.

[spnego] stanza
Use the [spnego] stanza to configure Kerberos authentication.

[ssl] stanza

[ssl-qop] stanza

[ssl-qop-mgmt-default] stanza

[ssl-qop-mgmt-networks] stanza

[step-up] stanza

[system-environment-variables] stanza

[tfimsso:<jct-id>] stanza

[tfim-cluster:<cluster>] stanza

[token] stanza
Use this stanza to define your token settings.

[user-agent] stanza
Use the [user-agent] stanza to specify a category name for a particular user-agent string in the HTTP Request header. WebSEAL uses the user-agent string to categorize the incoming requests to make flow data statistics more meaningful.

[user-attribute-definitions] stanza
Use this stanza to modify the data type, the category, or both of a custom attribute.

[user-map-authn] stanza
Use the [user-map-authn] stanza to define authenticated user mapping settings.

[websocket] stanza
Use the [websocket] stanza to define settings for WebsSocket support.

Appendix: Supported GSKit attributes
You can configure the these GSKit attributes with Security Access Manager.

Parent topic: Web Reverse Proxy Stanza Reference

[acnt-mgt] stanza[acnt-mgt] stanzaIBM Security Access Manager for Web WebSEAL [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.acnt-mgt stanzastanzasacnt-mgtStanza referenceaccount-expiry-notificationUse the account-expiry-notification stanza entry to control how WebSEAL reports login failures that are caused by invalid or expired accounts.account-inactivatedUse the account-inactivated stanza entry to configure the page that WebSEAL displays when a user with an inactive account tries to log in with the correct password.account-lockedUse the account-locked stanza entry to configure the page that WebSEAL displays when a user authentication fails because the account is locked.allow-unauthenticated-logoutUse the allow-unauthenticated-logout stanza entry to control whether unauthenticated users can request the pkmslogout resource.allowed-referersUse the allowed-referers stanza entry to specify which referrers can request management pages.cert-failureUse the cert-failure stanza entry to specify the page that is displayed if certificates are required and a client fails to authenticate with a certificate.cert-stepup-httpUse the cert-stepup-http stanza entry to specify the error page that WebSEAL displays if a user attempts to increase the authentication strength level to certificate authentication from an HTTP session.certificate-loginUse the certificate-login stanza entry to specify the login request form that WebSEAL uses for client-side certificate authentication.change-password-authUse the change-password-auth stanza entry to control whether the user is automatically authenticated, if required, during a change password request.client-notify-todUse the client-notify-tod stanza entry to control whether WebSEAL displays an error page if authorization is denied as a result of a POP time of day check.enable-html-redirectUse the enable-html-redirect stanza entry to enable HTML redirection. You can use HTML redirection, in conjunction with some JavaScript code, to preserve the HTML fragment in the response.enable-local-response-redirectUse the enable-local-response-redirect stanza entry to enable or disable local response redirection. When local response redirection is enabled, the redirection is used for all local WebSEAL response types: login, error, informational, and password management.enable-passwd-warnUse the enable-passwd-warn stanza entry to configure WebSEAL to display a password warning form when it detects the REGISTRY_PASSWORD_EXPIRE_TIME attribute in the user credential at login. This attribute indicates that the user password is soon to expire.enable-secret-token-validationUse the enable-secret-token-validation stanza entry to enable secret token validation, which protects certain WebSEAL account management pages against cross-site request forgery (CSRF) attacks.helphttp-rsp-headerhtml-redirectloginlogin-redirect-pagelogin-successlogoutpasswd-changepasswd-change-failurepasswd-change-successpasswd-expiredpasswd-warnpasswd-warn-failuresingle-signoff-uristepup-loginswitch-usertemp-cache-responsetoo-many-sessionsuse-restrictive-logout-filenamesuse-filename-for-pkmslogout

[acnt-mgt] stanza

Use the [acnt-mgt] stanza to configure the WebSEAL account management pages.

account-expiry-notification
Use the account-expiry-notification stanza entry to control how WebSEAL reports login failures that are caused by invalid or expired accounts.

account-inactivated
Use the account-inactivated stanza entry to configure the page that WebSEAL displays when a user with an inactive account tries to log in with the correct password.

account-locked
Use the account-locked stanza entry to configure the page that WebSEAL displays when a user authentication fails because the account is locked.

allow-unauthenticated-logout
Use the allow-unauthenticated-logout stanza entry to control whether unauthenticated users can request the pkmslogout resource.

allowed-referers
Use the allowed-referers stanza entry to specify which referrers can request management pages.

cert-failure
Use the cert-failure stanza entry to specify the page that is displayed if certificates are required and a client fails to authenticate with a certificate.

cert-stepup-http
Use the cert-stepup-http stanza entry to specify the error page that WebSEAL displays if a user attempts to increase the authentication strength level to certificate authentication from an HTTP session.

certificate-login
Use the certificate-login stanza entry to specify the login request form that WebSEAL uses for client-side certificate authentication.

change-password-auth
Use the change-password-auth stanza entry to control whether the user is automatically authenticated, if required, during a change password request.

client-notify-tod
Use the client-notify-tod stanza entry to control whether WebSEAL displays an error page if authorization is denied as a result of a POP time of day check.

enable-html-redirect
Use the enable-html-redirect stanza entry to enable HTML redirection. You can use HTML redirection, in conjunction with some JavaScript code, to preserve the HTML fragment in the response.

enable-local-response-redirect
Use the enable-local-response-redirect stanza entry to enable or disable local response redirection. When local response redirection is enabled, the redirection is used for all local WebSEAL response types: login, error, informational, and password management.

enable-passwd-warn
Use the enable-passwd-warn stanza entry to configure WebSEAL to display a password warning form when it detects the REGISTRY_PASSWORD_EXPIRE_TIME attribute in the user credential at login. This attribute indicates that the user password is soon to expire.

enable-secret-token-validation
Use the enable-secret-token-validation stanza entry to enable secret token validation, which protects certain WebSEAL account management pages against cross-site request forgery (CSRF) attacks.

help

http-rsp-header

html-redirect

login

login-redirect-page

login-success

logout

passwd-change

passwd-change-failure

passwd-change-success

passwd-expired

passwd-warn

passwd-warn-failure

single-signoff-uri

stepup-login

switch-user

temp-cache-response

too-many-sessions

use-restrictive-logout-filenames

use-filename-for-pkmslogout

Parent topic: Stanza reference

account-expiry-notificationaccount-expiry-notificationIBM Security Access Manager for Web WebSEAL account-expiry-notification stanza entryUse the account-expiry-notification stanza entry to control how WebSEAL reports login failures that are caused by invalid or expired accounts.account-expiry-notification stanza entryacnt-mgt stanzaentriesaccount-expiry-notificationacnt-mgt stanzaacnt-mgt stanzaaccount-expiry-notification entrySyntax account-expiry-notification = {yes|no} Description Specifies whether WebSEAL informs the user of the reason for a login failure when the failure is caused by an invalid or expired account. When this entry is set to no, the user receives the same error message as the message that is sent when a login fails as a result of invalid authentication information, such as an invalid user name or password. Options yesEnable.noDisable. Usage This stanza entry is required. Default value no Example account-expiry-notification = yes [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

account-expiry-notification

Use the account-expiry-notification stanza entry to control how WebSEAL reports login failures that are caused by invalid or expired accounts.

Syntax

account-expiry-notification = {yes|no}

Description

Specifies whether WebSEAL informs the user of the reason for a login failure when the failure is caused by an invalid or expired account. When this entry is set to no, the user receives the same error message as the message that is sent when a login fails as a result of invalid authentication information, such as an invalid user name or password.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

no

Example

account-expiry-notification = yes

Parent topic: [acnt-mgt] stanza

account-inactivatedaccount-inactivatedIBM Security Access Manager for Web WebSEAL account-inactivated stanza entryUse the account-inactivated stanza entry to configure the page that WebSEAL displays when a user with an inactive account tries to log in with the correct password.account-inactivated stanza entryacnt-mgt stanzaentriesaccount-inactivatedacnt-mgt stanzaacnt-mgt stanzaaccount-inactivated entrySyntax account-inactivated = filename Description Page that is displayed when nsAccountLock is true for a user (in Sun Directory Server) when they attempt to log in. WebSEAL displays the specified page only if the user provides the correct password during login. This option has no effect unless the corresponding Security Access Manager LDAP option is enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type. Options filenamePage that is displayed when nsAccountLock is true for the user who provides the correct password during login. Usage This stanza entry is required. Default value None. The value for this option in the template configuration file is acct_locked.html. Example account-inactivated = acct_locked.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

account-inactivated

Use the account-inactivated stanza entry to configure the page that WebSEAL displays when a user with an inactive account tries to log in with the correct password.

Syntax

account-inactivated = filename

Description

Page that is displayed when nsAccountLock is true for a user (in Sun Directory Server) when they attempt to log in. WebSEAL displays the specified page only if the user provides the correct password during login.

Note: This option has no effect unless the corresponding Security Access Manager LDAP option is enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type.

Options

filename

Page that is displayed when nsAccountLock is true for the user who provides the correct password during login.

Usage

This stanza entry is required.

Default value

None.

Note: The value for this option in the template configuration file is acct_locked.html.

Example

account-inactivated = acct_locked.html

Parent topic: [acnt-mgt] stanza

account-lockedaccount-lockedIBM Security Access Manager for Web WebSEAL account-locked stanza entryUse the account-locked stanza entry to configure the page that WebSEAL displays when a user authentication fails because the account is locked.account-locked stanza entryacnt-mgt stanzaentriesaccount-lockedacnt-mgt stanzaacnt-mgt stanzaaccount-locked entrySyntax account-locked = filename Description Page that is displayed when the user authentication fails as a result of a locked user account. Options filenamePage that is displayed when the user authentication fails as a result of a locked user account. Usage This stanza entry is required. Default value acct_locked.html Example account-locked = acct_locked.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

account-locked

Use the account-locked stanza entry to configure the page that WebSEAL displays when a user authentication fails because the account is locked.

Syntax

account-locked = filename

Description

Page that is displayed when the user authentication fails as a result of a locked user account.

Options

filename

Page that is displayed when the user authentication fails as a result of a locked user account.

Usage

This stanza entry is required.

Default value

acct_locked.html

Example

account-locked = acct_locked.html

Parent topic: [acnt-mgt] stanza

allow-unauthenticated-logoutallow-unauthenticated-logoutIBM Security Access Manager for Web allow-unauthenticated-logout WebSEAL stanza entryUse the allow-unauthenticated-logout stanza entry to control whether unauthenticated users can request the pkmslogout resource.allow-unauthenticated-logout stanza entryacnt-mgt stanzaentriesallow-unauthenticated-logoutacnt-mgt stanzaacnt-mgt stanzaallow-unauthenticated-logout entrySyntax allow-unauthenticated-logout = {yes|no} Description Determines whether unauthenticated users are able to request the pkmslogout resource without authenticating first. Options yesUnauthenticated users can request the pkmslogout resource.noUnauthenticated users must authenticate before the pkmslogout resource is returned. Usage This stanza entry is required. Default value no Example allow-unauthenticated-logout = no [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

allow-unauthenticated-logout

Use the allow-unauthenticated-logout stanza entry to control whether unauthenticated users can request the pkmslogout resource.

Syntax

allow-unauthenticated-logout = {yes|no}

Description

Determines whether unauthenticated users are able to request the pkmslogout resource without authenticating first.

Options

yes

Unauthenticated users can request the pkmslogout resource.

no

Unauthenticated users must authenticate before the pkmslogout resource is returned.

Usage

This stanza entry is required.

Default value

no

Example

allow-unauthenticated-logout = no

Parent topic: [acnt-mgt] stanza

allowed-referersallowed-referersIBM Security Access Manager for Web WebSEAL allowed-referers stanza entryUse the allowed-referers stanza entry to specify which referrers can request management pages.allowed-referers stanza entryacnt-mgt stanzaentriesallowed-referersacnt-mgt stanzaacnt-mgt stanzaallowed-referers entrySyntax allowed-referers = referer_filter DescriptionFor protection against cross-site request forgery (CSRF) attacks, you can configure WebSEAL to validate the HTTP Request referer header for all account management pages. WebSEAL uses the value that is provided for this configuration entry to determine whether the referrer host name in an incoming request is "valid". If this entry is configured, when WebSEAL receives a request for an account management page, WebSEAL: Checks whether the referer header is present in the HTTP Request header.Validates the host name portion of that referrer against the allowed-referers entries.If WebSEAL finds that an incoming request does not match any of the configured allowed-referers filters, the request fails and WebSEAL returns an error page. Entries can contain the following wildcard characters: * - match 0 or more characters.? - match any single character.\ - Literal match of the following character.You can use the value %HOST% for this entry. This value is a special filter, which indicates to WebSEAL that a referrer is "valid" if the host name portion of the referer header matches the host header.If there are no allowed-referers entries then WebSEAL does not complete this validation.You can specify this entry multiple times to define multiple "allowed" referrer filters. WebSEAL uses all of these entries to validate the referrer.For more information about referrer validation, search for "CSRF" in the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.Optionsreferer_filterSpecifies a filter for a referrer host name that WebSEAL can accept as "valid". Usage This stanza entry is optional. Default value None. ExampleThe following entry matches any referrer host name that begins with the characters ac, followed by zero or more characters, and ends with the characters me. allowed-referers = ac*meThe following entry indicates that a referrer is "valid" if the host name portion of the referer header matches the host header.allowed-referers = %HOST% [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

allowed-referers

Use the allowed-referers stanza entry to specify which referrers can request management pages.

Syntax

allowed-referers = referer_filter

Description

For protection against cross-site request forgery (CSRF) attacks, you can configure WebSEAL to validate the HTTP Request referer header for all account management pages. WebSEAL uses the value that is provided for this configuration entry to determine whether the referrer host name in an incoming request is "valid".

If this entry is configured, when WebSEAL receives a request for an account management page, WebSEAL:

Checks whether the referer header is present in the HTTP Request header.

Validates the host name portion of that referrer against the allowed-referers entries.

If WebSEAL finds that an incoming request does not match any of the configured allowed-referers filters, the request fails and WebSEAL returns an error page.

Entries can contain the following wildcard characters:

* - match 0 or more characters.

? - match any single character.

\ - Literal match of the following character.

You can use the value %HOST% for this entry. This value is a special filter, which indicates to WebSEAL that a referrer is "valid" if the host name portion of the referer header matches the host header.

If there are no allowed-referers entries then WebSEAL does not complete this validation.

Note: You can specify this entry multiple times to define multiple "allowed" referrer filters. WebSEAL uses all of these entries to validate the referrer.

For more information about referrer validation, search for "CSRF" in the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Options

referer_filter

Specifies a filter for a referrer host name that WebSEAL can accept as "valid".

Usage

This stanza entry is optional.

Default value

None.

Example

The following entry matches any referrer host name that begins with the characters ac, followed by zero or more characters, and ends with the characters me.

allowed-referers = ac*me

The following entry indicates that a referrer is "valid" if the host name portion of the referer header matches the host header.

allowed-referers = %HOST%

Parent topic: [acnt-mgt] stanza

cert-failurecert-failureIBM Security Access Manager for Web WebSEAL cert-failure stanza entryUse the cert-failure stanza entry to specify the page that is displayed if certificates are required and a client fails to authenticate with a certificate.cert-failure stanza entryacnt-mgt stanzaentriescert-failureacnt-mgt stanzaacnt-mgt stanzacert-failure entrySyntax cert-failure = filename Description Page displayed when certificates are required and a client fails to authenticate with a certificate. Options filenamePage displayed when certificates are required and a client fails to authenticate with a certificate. Usage This stanza entry is required. Default value certfailure.html Example cert-failure = certfailure.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

cert-failure

Use the cert-failure stanza entry to specify the page that is displayed if certificates are required and a client fails to authenticate with a certificate.

Syntax

cert-failure = filename

Description

Page displayed when certificates are required and a client fails to authenticate with a certificate.

Options

filename

Page displayed when certificates are required and a client fails to authenticate with a certificate.

Usage

This stanza entry is required.

Default value

certfailure.html

Example

cert-failure = certfailure.html

Parent topic: [acnt-mgt] stanza

cert-stepup-httpcert-stepup-httpIBM Security Access Manager for Web WebSEAL cert-stepup-http stanza entryUse the cert-stepup-http stanza entry to specify the error page that WebSEAL displays if a user attempts to increase the authentication strength level to certificate authentication from an HTTP session.cert-stepup-http stanza entryacnt-mgt stanzaentriescert-stepup-httpacnt-mgt stanzaacnt-mgt stanzacert-stepup-http entrySyntax cert-stepup-http = filename Description WebSEAL displays this HTML page when a client attempts to increase authentication strength level (step-up) to certificates while using HTTP protocol. Options filenameWebSEAL displays this HTML page when a client attempts to increase authentication strength level (step-up) to certificates while using HTTP protocol. Usage This stanza entry is required. Default value certstepuphttp.html Example cert-stepup-http = certstepuphttp.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

cert-stepup-http

Use the cert-stepup-http stanza entry to specify the error page that WebSEAL displays if a user attempts to increase the authentication strength level to certificate authentication from an HTTP session.

Syntax

cert-stepup-http = filename

Description

WebSEAL displays this HTML page when a client attempts to increase authentication strength level (step-up) to certificates while using HTTP protocol.

Options

filename

WebSEAL displays this HTML page when a client attempts to increase authentication strength level (step-up) to certificates while using HTTP protocol.

Usage

This stanza entry is required.

Default value

certstepuphttp.html

Example

cert-stepup-http = certstepuphttp.html

Parent topic: [acnt-mgt] stanza

certificate-logincertificate-loginIBM Security Access Manager for Web WebSEAL certificate-login stanza entryUse the certificate-login stanza entry to specify the login request form that WebSEAL uses for client-side certificate authentication.certificate-login stanza entryacnt-mgt stanzaentriescertificate-loginacnt-mgt stanzaacnt-mgt stanzacertificate-login entrySyntax certificate-login = filename Description Form requesting client-side certificate authentication login. This form is used only when the accept-client-certs key in the [certificate] stanza is set to prompt_as_needed. Options filenameForm requesting client-side certificate authentication login. Usage This stanza entry is required when delayed certificate authentication or authentication strength level (step-up) for certificates is enabled. Default value certlogin.html Example certificate-login = certlogin.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

certificate-login

Use the certificate-login stanza entry to specify the login request form that WebSEAL uses for client-side certificate authentication.

Syntax

certificate-login = filename

Description

Form requesting client-side certificate authentication login.

This form is used only when the accept-client-certs key in the [certificate] stanza is set to prompt_as_needed.

Options

filename

Form requesting client-side certificate authentication login.

Usage

This stanza entry is required when delayed certificate authentication or authentication strength level (step-up) for certificates is enabled.

Default value

certlogin.html

Example

certificate-login = certlogin.html

Parent topic: [acnt-mgt] stanza

change-password-authchange-password-authIBM Security Access Manager for Web WebSEAL change-password-auth stanza entryUse the change-password-auth stanza entry to control whether the user is automatically authenticated, if required, during a change password request.change-password-auth stanza entryacnt-mgt stanzaentrieschange-password-authacnt-mgt stanzaacnt-mgt stanzachange-password-auth entrySyntax change-password-auth = {yes|no} Description Enable this option to automatically authenticate users during password change operations. If the password for the user is expired, and this option is enabled, then WebSEAL completes the following tasks:Authenticates the user with the expired password.Changes the password.Automatically authenticates the user as required during the password change operation.This configuration is helpful in failover situations. The user might be served the password change form from one WebSEAL replica, but the form posts to another replica where the user session does not exist. Options yesEnable.noDisable. Usage This stanza entry is required. Default value no Example change-password-auth = yes [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

change-password-auth

Use the change-password-auth stanza entry to control whether the user is automatically authenticated, if required, during a change password request.

Syntax

change-password-auth = {yes|no}

Description

Enable this option to automatically authenticate users during password change operations. If the password for the user is expired, and this option is enabled, then WebSEAL completes the following tasks:

Authenticates the user with the expired password.

Changes the password.

Automatically authenticates the user as required during the password change operation.

This configuration is helpful in failover situations. The user might be served the password change form from one WebSEAL replica, but the form posts to another replica where the user session does not exist.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

no

Example

change-password-auth = yes

Parent topic: [acnt-mgt] stanza

client-notify-todIBM Security Access Manager for Web WebSEAL client-notify-tod stanza entryUse the client-notify-tod stanza entry to control whether WebSEAL displays an error page if authorization is denied as a result of a POP time of day check.client-notify-tod stanza entryacnt-mgt stanzaentriesclient-notify-todacnt-mgt stanzaacnt-mgt stanzaclient-notify-tod entrySyntax client-notify-tod = {yes|no} Description Enable the display of an error page when authorization is denied due to a POP time of day check. The error page is 38cf08cc.html. Options yesEnable.noDisable. Usage This stanza entry is required. Default value no Example client-notify-tod = yes [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

client-notify-tod

Use the client-notify-tod stanza entry to control whether WebSEAL displays an error page if authorization is denied as a result of a POP time of day check.

Syntax

client-notify-tod = {yes|no}

Description

Enable the display of an error page when authorization is denied due to a POP time of day check. The error page is 38cf08cc.html.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

no

Example

client-notify-tod = yes

Parent topic: [acnt-mgt] stanza

enable-html-redirectenable-html-redirectIBM Security Access Manager for Web WebSEAL enable-html-redirect stanza entryUse the enable-html-redirect stanza entry to enable HTML redirection. You can use HTML redirection, in conjunction with some JavaScript code, to preserve the HTML fragment in the response.enable-html-redirect stanza entryacnt-mgt stanzaentriesenable-html-redirectacnt-mgt stanzaacnt-mgt stanzaenable-html-redirect entrySyntax enable-html-redirect = {yes|no} DescriptionConfigures WebSEAL to use the HTML redirect page to handle redirections rather than returning an HTTP 302 response redirect.When a user successfully authenticates, WebSEAL typically uses an HTTP 302 response to redirect the user back to the resource that was originally requested. HTML redirection causes WebSEAL to send a static page back to the browser instead of a 302 redirect. WebSEAL can then use the JavaScript or any other code that is embedded in this static page to process the redirect. You can use the html-redirect configuration entry, which is also in the [acnt-mgt] stanza, to specify the page that contains the HTML redirection.For more information about HTML redirection, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.If you enable this configuration entry, you must not specify a value for the login-redirect-page entry, which is also in the [acnt-mgt] stanza. Options yesEnable.noDisable. Usage This stanza entry is required. Default value no Example enable-html-redirect = no [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

enable-html-redirect

Use the enable-html-redirect stanza entry to enable HTML redirection. You can use HTML redirection, in conjunction with some JavaScript code, to preserve the HTML fragment in the response.

Syntax

enable-html-redirect = {yes|no}

Description

Configures WebSEAL to use the HTML redirect page to handle redirections rather than returning an HTTP 302 response redirect.

When a user successfully authenticates, WebSEAL typically uses an HTTP 302 response to redirect the user back to the resource that was originally requested.

HTML redirection causes WebSEAL to send a static page back to the browser instead of a 302 redirect. WebSEAL can then use the JavaScript or any other code that is embedded in this static page to process the redirect.

You can use the html-redirect configuration entry, which is also in the [acnt-mgt] stanza, to specify the page that contains the HTML redirection.

For more information about HTML redirection, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Note: If you enable this configuration entry, you must not specify a value for the login-redirect-page entry, which is also in the [acnt-mgt] stanza.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

no

Example

enable-html-redirect = no

Parent topic: [acnt-mgt] stanza

enable-local-response-redirectenable-local-response-redirectIBM Security Access Manager for Web WebSEAL enable-local-response-redirect stanza entryUse the enable-local-response-redirect stanza entry to enable or disable local response redirection. When local response redirection is enabled, the redirection is used for all local WebSEAL response types: login, error, informational, and password management.enable-local-response-redirect stanza entryacnt-mgt stanzaentriesenable-local-response-redirectacnt-mgt stanzaacnt-mgt stanzaenable-local-response-redirect entrySyntax enable-local-response-redirect = {yes|no} DescriptionEnable or disable sending a redirection to a response application instead of serving management or error pages from the local system. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [acnt-mgt:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. OptionsyesEnable.noDisable. Usage This stanza entry is required. Default value no Example enable-local-response-redirect = no [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

enable-local-response-redirect

Use the enable-local-response-redirect stanza entry to enable or disable local response redirection. When local response redirection is enabled, the redirection is used for all local WebSEAL response types: login, error, informational, and password management.

Syntax

enable-local-response-redirect = {yes|no}

Description

Enable or disable sending a redirection to a response application instead of serving management or error pages from the local system.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [acnt-mgt:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

no

Example

enable-local-response-redirect = no

Parent topic: [acnt-mgt] stanza

enable-passwd-warnenable-passwd-warnIBM Security Access Manager for Web WebSEAL enable-passwd-warn stanza entryUse the enable-passwd-warn stanza entry to configure WebSEAL to display a password warning form when it detects the REGISTRY_PASSWORD_EXPIRE_TIME attribute in the user credential at login. This attribute indicates that the user password is soon to expire.enable-passwd-warn stanza entryacnt-mgt stanzaentriesenable-passwd-warnacnt-mgt stanzaacnt-mgt stanzaenable-passwd-warn entrySyntax enable-passwd-warn = {yes|no} Description Enable WebSEAL to detect the attribute REGISTRY_PASSWORD_EXPIRE_TIME added to a users' credential when the LDAP password policy indicates that their password is soon to expire. The value of this attribute is the number of seconds until their password expires. When this attribute is detected, at login to WebSEAL, a password warning form will appear. NOTE: This option must be set in order to use the associated options, which are also in the [acnt-mgt] stanza: passwd-warn and passwd-warn-failure. The corresponding Security Access Manager LDAP option must be enabled ([ldap] enhanced-pwd-policy=yes) and supported for the particular LDAP registry type. Options yesEnable the detection of the REGISTRY_PASSWORD_EXPIRE_TIME to ultimately warn the user when their password is soon to expire.noDisable the detection of the REGISTRY_PASSWORD_EXPIRE_TIME attribute. WebSEAL will not be able to notify users when their passwords are soon to expire. Usage This stanza entry is optional. Default value The option will default to yes if it is not specified in the configuration file. NOTE: The value for this option in the template configuration file is no. Example enable-passwd-warn = yes [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

enable-passwd-warn

Use the enable-passwd-warn stanza entry to configure WebSEAL to display a password warning form when it detects the REGISTRY_PASSWORD_EXPIRE_TIME attribute in the user credential at login. This attribute indicates that the user password is soon to expire.

Syntax

enable-passwd-warn = {yes|no}

Description

Enable WebSEAL to detect the attribute REGISTRY_PASSWORD_EXPIRE_TIME added to a users' credential when the LDAP password policy indicates that their password is soon to expire. The value of this attribute is the number of seconds until their password expires. When this attribute is detected, at login to WebSEAL, a password warning form will appear.

NOTE: This option must be set in order to use the associated options, which are also in the [acnt-mgt] stanza: passwd-warn and passwd-warn-failure. The corresponding Security Access Manager LDAP option must be enabled ([ldap] enhanced-pwd-policy=yes) and supported for the particular LDAP registry type.

Options

yes

Enable the detection of the REGISTRY_PASSWORD_EXPIRE_TIME to ultimately warn the user when their password is soon to expire.

no

Disable the detection of the REGISTRY_PASSWORD_EXPIRE_TIME attribute. WebSEAL will not be able to notify users when their passwords are soon to expire.

Usage

This stanza entry is optional.

Default value

The option will default to yes if it is not specified in the configuration file.

NOTE: The value for this option in the template configuration file is no.

Example

enable-passwd-warn = yes

Parent topic: [acnt-mgt] stanza

enable-secret-token-validationenable-secret-token-validationIBM Security Access Manager for Web WebSEAL enable-secret-token-validation stanza entryUse the enable-secret-token-validation stanza entry to enable secret token validation, which protects certain WebSEAL account management pages against cross-site request forgery (CSRF) attacks.enable-secret-token-validation stanza entryacnt-mgt stanzaentriesenable-secret-token-validationacnt-mgt stanzaacnt-mgt stanzaenable-secret-token-validation entrySyntax enable-secret-token-validation = {true|false} DescriptionUse this entry to enable secret token validation, which protects certain WebSEAL account management pages against cross-site request forgery (CSRF) attacks. If you set this entry to true, WebSEAL adds a token to each session and validates the "token" query argument for the following account management requests: /pkmslogin.form/pkmslogout/pkmslogout-nomas/pkmssu.form/pkmsskip/pkmsdisplace/pkmspaswd.formFor example, you must change the /pkmslogout request to pkmslogout?token=<value>, where <value> is the unique session token.If secret token validation is enabled and the token argument is missing from the request or does not match the session token, WebSEAL returns an error page. For more information about secret token validation, search for "CSRF" in the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.OptionstrueWebSEAL uses secret token validation to protect against CSRF attacks.This setting modifies the URLs for the affected WebSEAL management pages. Each of these management requests must contain a "token" argument with the current session token.falseWebSEAL does not use secret token validation. Usage This stanza entry is optional. Default value false Example enable-secret-token-validation = true [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

enable-secret-token-validation

Use the enable-secret-token-validation stanza entry to enable secret token validation, which protects certain WebSEAL account management pages against cross-site request forgery (CSRF) attacks.

Syntax

enable-secret-token-validation = {true|false}

Description

Use this entry to enable secret token validation, which protects certain WebSEAL account management pages against cross-site request forgery (CSRF) attacks. If you set this entry to true, WebSEAL adds a token to each session and validates the "token" query argument for the following account management requests:

/pkmslogin.form

/pkmslogout

/pkmslogout-nomas

/pkmssu.form

/pkmsskip

/pkmsdisplace

/pkmspaswd.form

For example, you must change the /pkmslogout request to pkmslogout?token=<value>, where <value> is the unique session token.

If secret token validation is enabled and the token argument is missing from the request or does not match the session token, WebSEAL returns an error page. For more information about secret token validation, search for "CSRF" in the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Options

true

WebSEAL uses secret token validation to protect against CSRF attacks.

Note: This setting modifies the URLs for the affected WebSEAL management pages. Each of these management requests must contain a "token" argument with the current session token.

false

WebSEAL does not use secret token validation.

Usage

This stanza entry is optional.

Default value

false

Example

enable-secret-token-validation = true

Parent topic: [acnt-mgt] stanza

helphelphelp stanza entryacnt-mgt stanzaentrieshelpacnt-mgt stanzaacnt-mgt stanzahelp entrySyntax help = filenameDescription Page containing links to valid administration pages.Options filenamePage containing links to valid administration pages.Usage This stanza entry is required.Default value help.htmlExample help = help.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

help

Syntax

help = filename

Description

Page containing links to valid administration pages.

Options

filename

Page containing links to valid administration pages.

Usage

This stanza entry is required.

Default value

help.html

Example

help = help.html

Parent topic: [acnt-mgt] stanza

http-rsp-headerhttp-rsp-headerhttp-rsp-header stanza entryacnt-mgt stanzaentrieshttp-rsp-headeracnt-mgt stanzaacnt-mgt stanzahttp-rsp-header entrySyntax http-rsp-header = header-name:macro Description Inserts custom headers whenever WebSEAL returns a custom response to the client. Options header-nameThe name of the header that holds the value.macroThat type of value to be inserted. This parameter can be one of the following values: TAM_OPAUTHNLEVELERROR_CODEERROR_TEXTCREDATTR(<name>), where <name> is the name of the credential attribute.USERNAME Usage This stanza entry is optional.You can specify this entry multiple times to include multiple headers in the response. Default value None. Example The following example inserts the Security Access Manager error code in a response header named tam-error-code:http-rsp-header = tam-error-code:ERROR_CODE [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

http-rsp-header

Syntax

http-rsp-header = header-name:macro

Description

Inserts custom headers whenever WebSEAL returns a custom response to the client.

Options

header-name

The name of the header that holds the value.

macro

That type of value to be inserted. This parameter can be one of the following values:

TAM_OP

AUTHNLEVEL

ERROR_CODE

ERROR_TEXT

CREDATTR(<name>), where <name> is the name of the credential attribute.

USERNAME

Usage

This stanza entry is optional.

Note: You can specify this entry multiple times to include multiple headers in the response.

Default value

None.

Example

The following example inserts the Security Access Manager error code in a response header named tam-error-code:

http-rsp-header = tam-error-code:ERROR_CODE

Parent topic: [acnt-mgt] stanza

html-redirecthtml-redirecthtml-redirect stanza entryacnt-mgt stanzaentrieshtml-redirectacnt-mgt stanzaacnt-mgt stanzahtml-redirect entrySyntax html-redirect = filename DescriptionSpecifies the standard HTML redirection page. Options filenameStandard HTML redirection page. Usage This stanza entry is required. Default value redirect.html. Example html-redirect = redirect.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

html-redirect

Syntax

html-redirect = filename

Description

Specifies the standard HTML redirection page.

Options

filename

Standard HTML redirection page.

Usage

This stanza entry is required.

Default value

redirect.html.

Example

html-redirect = redirect.html

Parent topic: [acnt-mgt] stanza

loginloginlogin stanza entryacnt-mgt stanzaentriesloginacnt-mgt stanzaacnt-mgt stanzalogin entrySyntax login = filenameDescription Standard login form.Options filenameStandard login form.Usage This stanza entry is required.Default value login.htmlExample login = login.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

login

Syntax

login = filename

Description

Standard login form.

Options

filename

Standard login form.

Usage

This stanza entry is required.

Default value

login.html

Example

login = login.html

Parent topic: [acnt-mgt] stanza

login-redirect-pagelogin-redirect-pagelogin-redirect-page stanza entryacnt-mgt stanzaentrieslogin-redirect-pageacnt-mgt stanzaacnt-mgt stanzalogin-redirect-page entrySyntax login-redirect-page = destination Description Page to which users are automatically redirected after completing a successful authentication. The configured redirect destination can be either: A server-relative Uniform Resource Locator (URL), or An absolute URL, orA macro which allows dynamic substitution of information from WebSEAL. The supported macros include: %AUTHNLEVEL% Level at which the session is currently authenticated.%HOSTNAME%Fully qualified host name.%PROTOCOL%The client connection protocol used. Can be HTTP or HTTPS.%URL% The original URL requested by the client.%USERNAME% The name of the logged in user.%HTTPHDR{name}%The HTTP header that corresponds to the specified name. For example: %HTTPHDR{Host}%%CREDATTR{name}%The credential attribute with the specified name. For example: %CREDATTR{tagvalue_session_index}%You cannot use this configuration entry if the enable-js-redirect entry (also in the [acnt-mgt] stanza) is set to yes. These redirects are not compatible with one another. Options destinationUniform Resource Locator (URL) to which users are automatically redirected after login, or a macro for dynamic substitution of information from WebSEAL. Usage This stanza entry is optional. Default value None. Example Example of a server relative URL: login-redirect-page = /jct/page.html Example of an absolute URL: login-redirect-page = http://www.ibm.com/ Example that uses a macro: login-redirect-page = /jct/intro-page.html?level=%AUTHNLEVEL%&url=%URL% [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

login-redirect-page

Syntax

login-redirect-page = destination

Description

Page to which users are automatically redirected after completing a successful authentication. The configured redirect destination can be either:

A server-relative Uniform Resource Locator (URL), or

An absolute URL, or

A macro which allows dynamic substitution of information from WebSEAL.

The supported macros include:

%AUTHNLEVEL%

Level at which the session is currently authenticated.

%HOSTNAME%

Fully qualified host name.

%PROTOCOL%

The client connection protocol used. Can be HTTP or HTTPS.

%URL%

The original URL requested by the client.

%USERNAME%

The name of the logged in user.

%HTTPHDR{name}%

The HTTP header that corresponds to the specified name. For example: %HTTPHDR{Host}%

%CREDATTR{name}%

The credential attribute with the specified name. For example: %CREDATTR{tagvalue_session_index}%

Note: You cannot use this configuration entry if the enable-js-redirect entry (also in the [acnt-mgt] stanza) is set to yes. These redirects are not compatible with one another.

Options

destination

Uniform Resource Locator (URL) to which users are automatically redirected after login, or a macro for dynamic substitution of information from WebSEAL.

Usage

This stanza entry is optional.

Default value

None.

Example

Example of a server relative URL:

login-redirect-page = /jct/page.html

Example of an absolute URL:

login-redirect-page = http://www.ibm.com/

Example that uses a macro:

login-redirect-page = /jct/intro-page.html?level=%AUTHNLEVEL%&url=%URL%

Parent topic: [acnt-mgt] stanza

login-successlogin-successlogin-success stanza entryacnt-mgt stanzaentrieslogin-successacnt-mgt stanzaacnt-mgt stanzalogin-success entrySyntax login-success = filenameDescription Page displayed after successful login.Options filenamePage displayed after successful login.Usage This stanza entry is required.Default value login_success.htmlExample login-success = login_success.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

login-success

Syntax

login-success = filename

Description

Page displayed after successful login.

Options

filename

Page displayed after successful login.

Usage

This stanza entry is required.

Default value

login_success.html

Example

login-success = login_success.html

Parent topic: [acnt-mgt] stanza

logoutlogoutlogout stanza entryacnt-mgt stanzaentrieslogoutacnt-mgt stanzaacnt-mgt stanzalogout entrySyntax logout = filenameDescription Page displayed after successful logout.Options filenamePage displayed after successful logout.Usage This stanza entry is required.Default value logout.htmlExample logout = logout.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

logout

Syntax

logout = filename

Description

Page displayed after successful logout.

Options

filename

Page displayed after successful logout.

Usage

This stanza entry is required.

Default value

logout.html

Example

logout = logout.html

Parent topic: [acnt-mgt] stanza

passwd-changepasswd-changepasswd-change stanza entryacnt-mgt stanzaentriespasswd-changeacnt-mgt stanzaacnt-mgt stanzapasswd-change entrySyntax passwd-change = filenameDescription Page containing a change password form.Options filenamePage containing a change password form.Usage This stanza entry is required.Default value passwd.htmlExample passwd-change = passwd.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

passwd-change

Syntax

passwd-change = filename

Description

Page containing a change password form.

Options

filename

Page containing a change password form.

Usage

This stanza entry is required.

Default value

passwd.html

Example

passwd-change = passwd.html

Parent topic: [acnt-mgt] stanza

passwd-change-failurepasswd-change-failurepasswd-change-failure stanza entryacnt-mgt stanzaentriespasswd-change-failureacnt-mgt stanzaacnt-mgt stanzapasswd-change-failure entrySyntax passwd-change-failure = filenameDescription Page displayed when password change request fails.Options filenamePage displayed when password change request fails.Usage This stanza entry is required.Default value passwd.htmlExample passwd-change-failure = passwd.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

passwd-change-failure

Syntax

passwd-change-failure = filename

Description

Page displayed when password change request fails.

Options

filename

Page displayed when password change request fails.

Usage

This stanza entry is required.

Default value

passwd.html

Example

passwd-change-failure = passwd.html

Parent topic: [acnt-mgt] stanza

passwd-change-successpasswd-change-successpasswd-change-success stanza entryacnt-mgt stanzaentriespasswd-change-successacnt-mgt stanzaacnt-mgt stanzapasswd-change-success entrySyntax passwd-change-success = filenameDescription Page displayed when password change request succeeds.Options filenamePage displayed when password change request succeeds.Usage This stanza entry is required.Default value passwd_rep.htmlExample passwd-change-success = passwd_rep.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

passwd-change-success

Syntax

passwd-change-success = filename

Description

Page displayed when password change request succeeds.

Options

filename

Page displayed when password change request succeeds.

Usage

This stanza entry is required.

Default value

passwd_rep.html

Example

passwd-change-success = passwd_rep.html

Parent topic: [acnt-mgt] stanza

passwd-expiredpasswd-expiredpasswd-expired stanza entryacnt-mgt stanzaentriespasswd-expiredacnt-mgt stanzaacnt-mgt stanzapasswd-expired entrySyntax passwd-expired = filenameDescription Page displayed when the user authentication fails due to an expired user password.Options filenamePage displayed when the user authentication fails due to an expired user password.Usage This stanza entry is required.Default value passwd_exp.htmlExample passwd-expired = passwd_exp.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

passwd-expired

Syntax

passwd-expired = filename

Description

Page displayed when the user authentication fails due to an expired user password.

Options

filename

Page displayed when the user authentication fails due to an expired user password.

Usage

This stanza entry is required.

Default value

passwd_exp.html

Example

passwd-expired = passwd_exp.html

Parent topic: [acnt-mgt] stanza

passwd-warnpasswd-warnpasswd-warn stanza entryacnt-mgt stanzaentriespasswd-warnacnt-mgt stanzaacnt-mgt stanzapasswd-warn entrySyntax passwd-warn = filename Description Page displayed after login if WebSEAL detects the LDAP password is soon to expire. NOTE: This option has no effect unless enable-passwd-warn (also in the [acnt-mgt] stanza) is set to yes and the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type. Options filenamePage displayed as a warning that the LDAP password is soon to expire. Usage This stanza entry is required. Default value None. NOTE: The value for this option in the template configuration file is passwd_warn.html. Example passwd-warn = passwd_warn.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

passwd-warn

Syntax

passwd-warn = filename

Description

Page displayed after login if WebSEAL detects the LDAP password is soon to expire.

NOTE: This option has no effect unless enable-passwd-warn (also in the [acnt-mgt] stanza) is set to yes and the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type.

Options

filename

Page displayed as a warning that the LDAP password is soon to expire.

Usage

This stanza entry is required.

Default value

None.

NOTE: The value for this option in the template configuration file is passwd_warn.html.

Example

passwd-warn = passwd_warn.html

Parent topic: [acnt-mgt] stanza

passwd-warn-failurepasswd-warn-failurepasswd-warn-failure stanza entryacnt-mgt stanzaentriespasswd-warn-failureacnt-mgt stanzaacnt-mgt stanzapasswd-warn-failure entrySyntax passwd-warn-failure = filename Description Page displayed if the user fails to change their password after being notified that the LDAP password is soon to expire. This page gives the user another chance to change their password and indicates the cause of the error. NOTE: This option has no effect unless enable-passwd-warn (also in the [acnt-mgt] stanza) is set to yes and the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type. Options filenamePage displayed if the user does not change their password after receiving notification that the LDAP password is soon to expire. Usage This stanza entry is required. Default value None. NOTE: The value for this option in the template configuration file is passwd_warn.html. Example passwd-warn-failure = passwd_warn.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

passwd-warn-failure

Syntax

passwd-warn-failure = filename

Description

Page displayed if the user fails to change their password after being notified that the LDAP password is soon to expire. This page gives the user another chance to change their password and indicates the cause of the error.

NOTE: This option has no effect unless enable-passwd-warn (also in the [acnt-mgt] stanza) is set to yes and the corresponding Security Access Manager LDAP option is also enabled ([ldap] enhanced-pwd-policy=yes). This LDAP option must be supported for the particular LDAP registry type.

Options

filename

Page displayed if the user does not change their password after receiving notification that the LDAP password is soon to expire.

Usage

This stanza entry is required.

Default value

None.

NOTE: The value for this option in the template configuration file is passwd_warn.html.

Example

passwd-warn-failure = passwd_warn.html

Parent topic: [acnt-mgt] stanza

single-signoff-urisingle-signoff-urisingle-signoff-uri stanza entryacnt-mgt stanzaentriessingle-signoff-uriacnt-mgt stanzaacnt-mgt stanzasingle-signoff-uri entrySyntax single-signoff-uri = URI Description When a user session is terminated in WebSEAL, any sessions that might exist on backend application servers are not destroyed. You can use this configuration entry to change this default behavior. When a WebSEAL user session is terminated and this stanza entry is configured, WebSEAL sends a request to the resource specified by the configured URI. The request contains any configured headers and cookies for the junction point on which the resource resides. The backend application can use this information to terminate any sessions for that user.You can configure more than one single-sign-off-uri entry to send a request to multiple URIs. Options URIThe resource identifier of the application that receives the single signoff request from WebSEAL. The URI must be server relative and correspond to a resource on a standard junction. Usage This stanza entry is optional. Default value None. Example single-signoff-uri = /management/logoff [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

single-signoff-uri

Syntax

single-signoff-uri = URI

Description

When a user session is terminated in WebSEAL, any sessions that might exist on backend application servers are not destroyed. You can use this configuration entry to change this default behavior.

When a WebSEAL user session is terminated and this stanza entry is configured, WebSEAL sends a request to the resource specified by the configured URI. The request contains any configured headers and cookies for the junction point on which the resource resides. The backend application can use this information to terminate any sessions for that user.

Note: You can configure more than one single-sign-off-uri entry to send a request to multiple URIs.

Options

URI

The resource identifier of the application that receives the single signoff request from WebSEAL.

Note: The URI must be server relative and correspond to a resource on a standard junction.

Usage

This stanza entry is optional.

Default value

None.

Example

single-signoff-uri = /management/logoff

Parent topic: [acnt-mgt] stanza

stepup-loginstepup-loginstepup-login stanza entryacnt-mgt stanzaentriesstepup-loginacnt-mgt stanzaacnt-mgt stanzastepup-login entrySyntax stepup-login = filenameDescription Step-up authentication login form.Options filenameStep-up authentication login form.Usage This stanza entry is required.Default value stepuplogin.htmlExample stepup-login = stepuplogin.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

stepup-login

Syntax

stepup-login = filename

Description

Step-up authentication login form.

Options

filename

Step-up authentication login form.

Usage

This stanza entry is required.

Default value

stepuplogin.html

Example

stepup-login = stepuplogin.html

Parent topic: [acnt-mgt] stanza

switch-userswitch-userswitch-user stanza entryacnt-mgt stanzaentriesswitch-useracnt-mgt stanzaacnt-mgt stanzaswitch-user entrySyntax switch-user = filenameDescription Switch user management form.Options filenameSwitch user management form.Usage This stanza entry is required.Default value switchuser.htmlExample switch-user = switchuser.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

switch-user

Syntax

switch-user = filename

Description

Switch user management form.

Options

filename

Switch user management form.

Usage

This stanza entry is required.

Default value

switchuser.html

Example

switch-user = switchuser.html

Parent topic: [acnt-mgt] stanza

temp-cache-responsetemp-cache-responsetemp-cache-response stanza entryacnt-mgt stanzaentriestemp-cache-responseacnt-mgt stanzaacnt-mgt stanzatemp-cache-response entrySyntax temp-cache-response = filename Description The default page that WebSEAL returns if no URL redirect is supplied with the pkmstempsession request. The pkmstempsession page is accessed to achieve session sharing with Microsoft Office applications. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy. Options filenameThe default page that WebSEAL returns for a pkmstempsession request. Usage This stanza entry is optional. Default value temp_cache_response.html Example temp-cache-response = temp_cache_response.html [acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

temp-cache-response

Syntax

temp-cache-response = filename

Description

The default page that WebSEAL returns if no URL redirect is supplied with the pkmstempsession request. The pkmstempsession page is accessed to achieve session sharing with Microsoft Office applications. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Options

filename

The default page that WebSEAL returns for a pkmstempsession request.

Usage

This stanza entry is optional.

Default value

temp_cache_response.html

Example

temp-cache-response = temp_cache_response.html

Parent topic: [acnt-mgt] stanza

too-many-sessionstoo-many-sessionstoo-many-sessions stanza entryacnt-mgt stanzaentriestoo-many-sessionsacnt-mgt stanzaacnt-mgt stanzatoo-many-sessions entrySyntax too-many-sessions = filenameDescription Page displayed when a user has too many concurrent sessions and must either cancel their new login or terminate the other sessions.Options filenamePage displayed when a user has too many concurrent sessions and must either cancel their new login or terminate the other sessions.Usage This stanza entry is required.Default value too_many_sessions.htmlExample too-many-sessions = too_many_sessions.html[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

too-many-sessions

Syntax

too-many-sessions = filename

Description

Page displayed when a user has too many concurrent sessions and must either cancel their new login or terminate the other sessions.

Options

filename

Page displayed when a user has too many concurrent sessions and must either cancel their new login or terminate the other sessions.

Usage

This stanza entry is required.

Default value

too_many_sessions.html

Example

too-many-sessions = too_many_sessions.html

Parent topic: [acnt-mgt] stanza

use-restrictive-logout-filenamesuse-restrictive-logout-filenamesuse-restrictive-logout-filenames stanza entryacnt-mgt stanzaentriesuse-restrictive-logout-filenamesacnt-mgt stanzaacnt-mgt stanzause-restrictive-logout-filenames entrySyntax use-restrictive-logout-filenames = {yes|no}Description Control the restrictions normally enforced on the name of the /pkmslogout custom response file.Options yesUse default restrictions to enforce the name of the /pkmslogout custom response file.no Only slash (/), backslash (\), characters outside of the ASCII range 0x20 - 0x7E, and filenames that begin with a period (.) will be disallowed.Usage This stanza entry is required.Default value yesExample use-restrictive-logout-filenames = yes[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

use-restrictive-logout-filenames

Syntax

use-restrictive-logout-filenames = {yes|no}

Description

Control the restrictions normally enforced on the name of the /pkmslogout custom response file.

Options

yes

Use default restrictions to enforce the name of the /pkmslogout custom response file.

no

Only slash (/), backslash (\), characters outside of the ASCII range 0x20 - 0x7E, and filenames that begin with a period (.) will be disallowed.

Usage

This stanza entry is required.

Default value

yes

Example

use-restrictive-logout-filenames = yes

Parent topic: [acnt-mgt] stanza

use-filename-for-pkmslogoutuse-filename-for-pkmslogoutuse-filename-for-pkmslogout stanza entryacnt-mgt stanzaentriesuse-filename-for-pkmslogoutacnt-mgt stanzaacnt-mgt stanzause-filename-for-pkmslogout entrySyntax use-filename-for-pkmslogout = {yes|no}Description Controls whether or not the appended query string (specifying a custom response page) in a pkmslogout command is used to override the default response page.Options yesEnables the operation of the query string. If a query string in a pkmslogout URL specifies a custom response page, that custom page is used instead of the default page.noDisables the operation of the query string. Any query string in a pkmslogout URL that specifies a custom response page is ignored. Only the default response page is used upon logout. Usage This stanza entry is required.Default value noExample use-filename-for-pkmslogout = yes[acnt-mgt] stanzaUse the [acnt-mgt] stanza to configure the WebSEAL account management pages.

use-filename-for-pkmslogout

Syntax

use-filename-for-pkmslogout = {yes|no}

Description

Controls whether or not the appended query string (specifying a custom response page) in a pkmslogout command is used to override the default response page.

Options

yes

Enables the operation of the query string. If a query string in a pkmslogout URL specifies a custom response page, that custom page is used instead of the default page.

no

Disables the operation of the query string. Any query string in a pkmslogout URL that specifies a custom response page is ignored. Only the default response page is used upon logout.

Usage

This stanza entry is required.

Default value

no

Example

use-filename-for-pkmslogout = yes

Parent topic: [acnt-mgt] stanza

[authentication-levels] stanza[authentication-levels] stanzaIBM Security Access Manager for Web WebSEAL [authentication-levels] stanzaUse the [authentication-levels] stanza to define the step-up authentication levels.authentication-levels stanzastanzasauthentication-levelsStanza referencelevel

[authentication-levels] stanza

Use the [authentication-levels] stanza to define the step-up authentication levels.

level

Parent topic: Stanza reference

levellevellevel stanza entryauthentication-levels stanzaentrieslevelauthentication-levels stanzaauthentication-levels stanzalevel entrySyntax level = method-name Description Step-up authentication levels. WebSEAL enables authenticated users to increase the authentication level by use of step-up authentication. This key=value pair specifies which step-up authentication levels are supported by this WebSEAL server. Do not specify an authentication level unless the authentication method is enabled. For example, you must enable either basic authentication or forms authentication before you set level = password. Enter a separate key=value pair for each supported level. Supported levels include: unauthenticatedpasswordsslext-auth-interfaceltpaThe position of the entry in the file dictates the associated authentication level. The first row, typically unauthenticated, is associated with authentication level of 0. Each subsequent line is associated with the next higher level. You can add multiple entries for the same method. It is possible for the method to set the authentication level itself. For example, an External Authentication Interface (EAI) implementation might set either authentication level of 2 or 3 depending on the authentication transaction that the client undertakes.The EAI can set this authentication level directly in the identity attributes returned to WebSEAL. To support this implementation, you can create two identical lines in positions 3 and 4. For example:level = unauthenticated (associated with level 0) level = password (associated with level 1) level = ext-auth-interface (associated with level 2) level = ext-auth-interface (associated with level 3) Options method-nameName of authentication method. Usage This stanza entry is required. Default value unauthenticated password Example level = unauthenticated level = password [authentication-levels] stanzaUse the [authentication-levels] stanza to define the step-up authentication levels.

level

Syntax

level = method-name

Description

Step-up authentication levels. WebSEAL enables authenticated users to increase the authentication level by use of step-up authentication. This key=value pair specifies which step-up authentication levels are supported by this WebSEAL server.

Do not specify an authentication level unless the authentication method is enabled. For example, you must enable either basic authentication or forms authentication before you set level = password.

Enter a separate key=value pair for each supported level. Supported levels include:

unauthenticated

password

ssl

ext-auth-interface

ltpa

The position of the entry in the file dictates the associated authentication level. The first row, typically unauthenticated, is associated with authentication level of 0. Each subsequent line is associated with the next higher level. You can add multiple entries for the same method.

It is possible for the method to set the authentication level itself. For example, an External Authentication Interface (EAI) implementation might set either authentication level of 2 or 3 depending on the authentication transaction that the client undertakes.

The EAI can set this authentication level directly in the identity attributes returned to WebSEAL. To support this implementation, you can create two identical lines in positions 3 and 4. For example:

level = unauthenticated 		(associated with level 0)
level = password 						(associated with level 1)
level = ext-auth-interface	(associated with level 2)
level = ext-auth-interface  (associated with level 3)

Options

method-name

Name of authentication method.

Usage

This stanza entry is required.

Default value

unauthenticated

password

Example

level = unauthenticated
level = password

Parent topic: [authentication-levels] stanza

[aznapi-configuration] stanza[aznapi-configuration] stanzaIBM Security Access Manager for Web WebSEAL [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.aznapi-configuration stanzastanzasaznapi-configurationStanza referenceaudit-attributeUse the audit-attribute stanza entry to list the attributes to audit.auditcfgUse the auditcfg stanza entry to configure which events WebSEAL audits.cache-refresh-intervalUse the cache-refresh-interval stanza entry to specify the interval in seconds between polls to the master authorization server to check for updates.input-adi-xml-prologlisten-flagslogauditlogclientidlogcfglogflushlogsizelog-max-audit-filesThis entry defines the integer value that indicates the maximum number of rollover audit log files to store on disk. permission-info-returnedpolicy-attr-separatorpolicy-cache-sizeresource-manager-provided-adiskip-eas-on-bypass-popUse the skip-eas-on-bypass-pop entry to control whether the BypassPop setting is ignored if an EAS is to be called.special-easUse the special-eas stanza entry to allow the path to the effective POP for the protected resource being accessed, to be passed to the EAS. xsl-stylesheet-prolog

[aznapi-configuration] stanza

Use the [aznapi-configuration] stanza to configure the authorization API services.

audit-attribute
Use the audit-attribute stanza entry to list the attributes to audit.

auditcfg
Use the auditcfg stanza entry to configure which events WebSEAL audits.

cache-refresh-interval
Use the cache-refresh-interval stanza entry to specify the interval in seconds between polls to the master authorization server to check for updates.

input-adi-xml-prolog

listen-flags

logaudit

logclientid

logcfg

logflush

logsize

log-max-audit-files
This entry defines the integer value that indicates the maximum number of rollover audit log files to store on disk.

permission-info-returned

policy-attr-separator

policy-cache-size

resource-manager-provided-adi

skip-eas-on-bypass-pop
Use the skip-eas-on-bypass-pop entry to control whether the BypassPop setting is ignored if an EAS is to be called.

special-eas
Use the special-eas stanza entry to allow the path to the effective POP for the protected resource being accessed, to be passed to the EAS.

xsl-stylesheet-prolog

Parent topic: Stanza reference

audit-attributeaudit-attributeIBM Security Access Manager for Web WebSEAL audit-attribute stanza entryUse the audit-attribute stanza entry to list the attributes to audit.audit-attribute stanza entryaznapi-configuration stanzaentriesaudit-attributeaznapi-configuration stanzaaznapi-configuration stanzaaudit-attribute entrySyntax audit-attribute = attribute Description Attributes to be audited. You can configure multiple audit-attribute entries. Create a separate audit-attribute entry for each attribute to be audited. Options attributeAttributes to be audited. Usage This stanza entry is required. Default value tagvalue_su-admin Example audit-attribute = tagvalue_su-admin [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

audit-attribute

Use the audit-attribute stanza entry to list the attributes to audit.

Syntax

audit-attribute = attribute

Description

Attributes to be audited.

Note: You can configure multiple audit-attribute entries. Create a separate audit-attribute entry for each attribute to be audited.

Options

attribute

Attributes to be audited.

Usage

This stanza entry is required.

Default value

tagvalue_su-admin

Example

audit-attribute =   tagvalue_su-admin

Parent topic: [aznapi-configuration] stanza

auditcfgauditcfgIBM Security Access Manager for Web WebSEAL auditcfg stanza entryUse the auditcfg stanza entry to configure which events WebSEAL audits.auditcfg stanza entryaznapi-configuration stanzaentriesauditcfgaznapi-configuration stanzaaznapi-configuration stanzaauditcfg entrySyntax auditcfg = {azn|authn|http} Description Indicates the components for which auditing of events is configured. To enable component-specific audit records, add the appropriate definition. Options aznCapture authorization events.authnCapture authentication events.httpCapture HTTP events. These events correspond to the events logged by the request, referrer, and agent logging clients. Usage This stanza entry is optional for WebSEAL. However, this stanza entry is required when auditing is enabled (logaudit = yes). Default value There is no default value for WebSEAL because auditing is disabled by default. Example Create a separate stanza entry for each component to be activated. The components are included in the default configuration file, but are commented out. To activate a commented out entry, remove the pound sign (#) from the start of the entry. Example: auditcfg = azn #auditcfg = authn #auditcfg = http [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

auditcfg

Use the auditcfg stanza entry to configure which events WebSEAL audits.

Syntax

auditcfg = {azn|authn|http}

Description

Indicates the components for which auditing of events is configured. To enable component-specific audit records, add the appropriate definition.

Options

azn

Capture authorization events.

authn

Capture authentication events.

http

Capture HTTP events. These events correspond to the events logged by the request, referrer, and agent logging clients.

Usage

This stanza entry is optional for WebSEAL. However, this stanza entry is required when auditing is enabled (logaudit = yes).

Default value

There is no default value for WebSEAL because auditing is disabled by default.

Example

Create a separate stanza entry for each component to be activated. The components are included in the default configuration file, but are commented out. To activate a commented out entry, remove the pound sign (#) from the start of the entry.

Example:

auditcfg = azn
#auditcfg = authn
#auditcfg = http

Parent topic: [aznapi-configuration] stanza

cache-refresh-intervalcache-refresh-intervalIBM Security Access Manager for Web WebSEAL cache-refresh-interval stanza entryUse the cache-refresh-interval stanza entry to specify the interval in seconds between polls to the master authorization server to check for updates.cache-refresh-interval stanza entryaznapi-configuration stanzaentriescache-refresh-intervalaznapi-configuration stanzaaznapi-configuration stanzacache-refresh-interval entrySyntax cache-refresh-interval = {disable|default|number_of_seconds} Description Poll interval between checks for updates to the master authorization server. Options disableThe interval value in seconds is not set.defaultWhen value is to default, an interval of 600 seconds is used.number_of_secondsInteger value indicating the number of seconds between polls to the master authorization server to check for updates. The minimum number of seconds is 0. There is no maximum value. Usage This stanza entry is optional. Default value disable Example cache-refresh-interval = disable [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

cache-refresh-interval

Use the cache-refresh-interval stanza entry to specify the interval in seconds between polls to the master authorization server to check for updates.

Syntax

cache-refresh-interval = {disable|default|number_of_seconds}

Description

Poll interval between checks for updates to the master authorization server.

Options

disable

The interval value in seconds is not set.

default

When value is to default, an interval of 600 seconds is used.

number_of_seconds

Integer value indicating the number of seconds between polls to the master authorization server to check for updates.

The minimum number of seconds is 0. There is no maximum value.

Usage

This stanza entry is optional.

Default value

disable

Example

cache-refresh-interval = disable

Parent topic: [aznapi-configuration] stanza

input-adi-xml-prologinput-adi-xml-prologinput-adi-xml-prolog stanza entryaznapi-configuration stanzaentriesinput-adi-xml-prologaznapi-configuration stanzaaznapi-configuration stanzainput-adi-xml-prolog entrySyntax input-adi-xml-prolog = prolog Description The prolog to be added to the top of the XML document that is created using the Authorization Decision Information (ADI) needed to evaluate a boolean authorization rule. Options prologThe prolog to be added to the top of the XML document that is created using the Authorization Decision Information (ADI) needed to evaluate a boolean authorization rule. Usage This stanza entry is optional. Default value <?xml version='1.0' encoding='UTF-8'?> Example input-adi-xml-prolog = <?xml version='1.0' encoding='UTF-8'?> [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

input-adi-xml-prolog

Syntax

input-adi-xml-prolog = prolog

Description

The prolog to be added to the top of the XML document that is created using the Authorization Decision Information (ADI) needed to evaluate a boolean authorization rule.

Options

prolog

The prolog to be added to the top of the XML document that is created using the Authorization Decision Information (ADI) needed to evaluate a boolean authorization rule.

Usage

This stanza entry is optional.

Default value

<?xml version='1.0' encoding='UTF-8'?>

Example

input-adi-xml-prolog = <?xml version='1.0' encoding='UTF-8'?>

Parent topic: [aznapi-configuration] stanza

listen-flagslisten-flagslisten-flags stanza entryaznapi-configuration stanzaentrieslisten-flagsaznapi-configuration stanzaaznapi-configuration stanzalisten-flags entrySyntax listen-flags = {enable|disable}Description Enables or disables the reception by WebSEAL of policy cache update notifications from the master authorization server. Options enableActivates the notification listener.disableDeactivates the notification listener.Usage This stanza entry is required.Default value disableExample listen-flags = enable[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

listen-flags

Syntax

listen-flags = {enable|disable}

Description

Enables or disables the reception by WebSEAL of policy cache update notifications from the master authorization server.

Options

enable

Activates the notification listener.

disable

Deactivates the notification listener.

Usage

This stanza entry is required.

Default value

disable

Example

listen-flags = enable

Parent topic: [aznapi-configuration] stanza

logauditlogauditlogaudit stanza entryaznapi-configuration stanzaentrieslogauditaznapi-configuration stanzaaznapi-configuration stanzalogaudit entrySyntax logaudit = {yes|true|no|false}Description Enables or disables auditing.Options yesEnable auditing.trueEnable auditing.noDisable auditing.falseDisable auditing.Usage This stanza entry is required.Default value noExample logaudit = no[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

logaudit

Syntax

logaudit = {yes|true|no|false}

Description

Enables or disables auditing.

Options

yes

Enable auditing.

true

Enable auditing.

no

Disable auditing.

false

Disable auditing.

Usage

This stanza entry is required.

Default value

no

Example

logaudit = no

Parent topic: [aznapi-configuration] stanza

logclientidlogclientidlogclientid stanza entryaznapi-configuration stanzaentrieslogclientidaznapi-configuration stanzaaznapi-configuration stanzalogclientid entrySyntax logclientid = websealdDescription Name of the daemon whose activities are audited through use of authorization API logging.Options websealdName of the daemon whose activities are audited through use of authorization API logging.Usage This stanza entry is required.Default value websealdExample logclientid = webseald[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

logclientid

Syntax

logclientid = webseald

Description

Name of the daemon whose activities are audited through use of authorization API logging.

Options

webseald

Name of the daemon whose activities are audited through use of authorization API logging.

Usage

This stanza entry is required.

Default value

webseald

Example

logclientid = webseald

Parent topic: [aznapi-configuration] stanza

logcfglogcfglogcfg stanza entryaznapi-configuration stanzaentrieslogcfgaznapi-configuration stanzaaznapi-configuration stanzalogcfg entrySyntax logcfg = category:{stdout|stderr|file|remote|rsyslog}[ [parameter=value ] [,parameter=value]...] Description Specifies event logging for the specified category. Options Specifies event logging for the specified category. For WebSEAL, the categories are: audit.azn Authorization events.audit.authn Credentials acquisition authentication.httpAll HTTP logging information.http.clf HTTP request information as defined by the request-log-format configuration entry in the [logging] stanza.http.ref HTTP Referer header information.http.agent HTTP User_Agent header information{stdout|stderr|file|remote|rsyslog}Event logging supports a number of output destination types. WebSEAL auditing typically is configured to use the file type.parameter = value Each event logging type supports a number of optional parameter = value options. For more information about output destination types and optional parameter = value settings, see the IBM Security Access Manager for Web: Administration Guide. Usage This stanza entry is optional. Default value None. Example Example entry for request.log (common log format) (entered as one line): logcfg = http.clf:file path=request_file, flush=time,rollover=max_size, max_rollover_files=max_files,log_id=httpclf,buffer_size=8192, queue_size=48 [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

logcfg

Syntax

logcfg = category:{stdout|stderr|file|remote|rsyslog}[ [parameter=value ]
[,parameter=value]...]

Description

Specifies event logging for the specified category.

Options

Specifies event logging for the specified category.

For WebSEAL, the categories are:

audit.azn

Authorization events.

audit.authn

Credentials acquisition authentication.

http

All HTTP logging information.

http.clf

HTTP request information as defined by the request-log-format configuration entry in the [logging] stanza.

http.ref

HTTP Referer header information.

http.agent

HTTP User_Agent header information

{stdout|stderr|file|remote|rsyslog}

Event logging supports a number of output destination types. WebSEAL auditing typically is configured to use the file type.

parameter = value

Each event logging type supports a number of optional parameter = value options.

For more information about output destination types and optional parameter = value settings, see the IBM Security Access Manager for Web: Administration Guide.

Usage

This stanza entry is optional.

Default value

None.

Example

Example entry for request.log (common log format) (entered as one line):

logcfg = http.clf:file path=request_file,
flush=time,rollover=max_size,
max_rollover_files=max_files,log_id=httpclf,buffer_size=8192,
queue_size=48

Parent topic: [aznapi-configuration] stanza

logflushlogflushlogflush stanza entryaznapi-configuration stanzaentrieslogflushaznapi-configuration stanzaaznapi-configuration stanzalogflush entrySyntax logflush = number_of_secondsDescription Integer value indicating the frequency, in seconds, to force a flush of log buffers.Options number_of_secondsThe minimum value is 1 second. The maximum value is 600 seconds.Usage This stanza entry is optional.Default value 20Example logflush = 20[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

logflush

Syntax

logflush = number_of_seconds

Description

Integer value indicating the frequency, in seconds, to force a flush of log buffers.

Options

number_of_seconds

The minimum value is 1 second.

The maximum value is 600 seconds.

Usage

This stanza entry is optional.

Default value

20

Example

logflush = 20

Parent topic: [aznapi-configuration] stanza

logsizelogsizelogsize stanza entryaznapi-configuration stanzaentrieslogsizeaznapi-configuration stanzaaznapi-configuration stanzalogsize entrySyntax logsize = number_of_bytesDescription Integer value indicating the size limit of audit log files. The size limit is also referred to as the rollover threshold. When the audit log file reaches this threshold, the original audit log file is renamed and a new log file with the original name will be created.Options number_of_bytesWhen the value is zero (0), no rollover log file is created. When the value is a negative integer, the logs are rolled over daily, regardless of the size. When the value is a positive integer, the value indicates the maximum size, in bytes, of the audit log file before the rollover occurs. The allowable range is from 1 byte to 2 megabytesUsage This stanza entry is optional.Default value 2000000Example logsize = 2000000 [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

logsize

Syntax

logsize = number_of_bytes

Description

Integer value indicating the size limit of audit log files. The size limit is also referred to as the rollover threshold. When the audit log file reaches this threshold, the original audit log file is renamed and a new log file with the original name will be created.

Options

number_of_bytes

When the value is zero (0), no rollover log file is created.

When the value is a negative integer, the logs are rolled over daily, regardless of the size.

When the value is a positive integer, the value indicates the maximum size, in bytes, of the audit log file before the rollover occurs. The allowable range is from 1 byte to 2 megabytes

Usage

This stanza entry is optional.

Default value

2000000

Example

logsize = 2000000

Parent topic: [aznapi-configuration] stanza

log-max-audit-filesThis entry defines the integer value that indicates the maximum number of rollover audit log files to store on disk. Syntax log-max-audit-files = number_of_filesDescription When the number of rollover audit log files reaches this threshold, the oldest rollover audit log files are deleted until the number of files is equal to log-max-audit-files.Options number_of_filesWhen the value is empty, no rollover log files are deleted. When the value is equal to zero, then only the current log file is kept, and all rollover log files are deleted. When the value is a positive integer, the value indicates the maximum number of rollover files to store on disk.Usage This stanza entry is optional.Default value NoneExample log-max-audit-files = 5[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

log-max-audit-files

This entry defines the integer value that indicates the maximum number of rollover audit log files to store on disk.

Syntax

log-max-audit-files = number_of_files

Description

When the number of rollover audit log files reaches this threshold, the oldest rollover audit log files are deleted until the number of files is equal to log-max-audit-files.

Options

number_of_files

When the value is empty, no rollover log files are deleted.

When the value is equal to zero, then only the current log file is kept, and all rollover log files are deleted.

When the value is a positive integer, the value indicates the maximum number of rollover files to store on disk.

Usage

This stanza entry is optional.

Default value

None

Example

log-max-audit-files = 5

Parent topic: [aznapi-configuration] stanza

permission-info-returnedpermission-info-returnedpermission-info-returned stanza entryaznapi-configuration stanzaentriespermission-info-returnedaznapi-configuration stanzaaznapi-configuration stanzapermission-info-returned entrySyntax permission-info-returned = permission-attributeDescription Specifies the permission information returned to the resource manager (for example, WebSEAL) from the authorization service.Options permission-attributeThe azn_perminfo_rules_adi_request setting allows the authorization service to request ADI from the current WebSEAL client request. The azn_perminfo_reason_rule_failed setting specifies that rule failure reasons be returned to the resource manager (this setting is required for –R junctions). To enable the Privacy Redirection capabilities of the AMWebARS Web Service, the azn_perminfo_amwebars_redirect_url must be included.Usage This stanza entry is optional.Default value azn_perminfo_rules_adi_request azn_perminfo_reason_rule_failedExample permission-info-returned = azn_perminfo_rules_adi_request azn_perminfo_reason_rule_failed[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

permission-info-returned

Syntax

permission-info-returned = permission-attribute

Description

Specifies the permission information returned to the resource manager (for example, WebSEAL) from the authorization service.

Options

permission-attribute

The azn_perminfo_rules_adi_request setting allows the authorization service to request ADI from the current WebSEAL client request. The azn_perminfo_reason_rule_failed setting specifies that rule failure reasons be returned to the resource manager (this setting is required for –R junctions).

To enable the Privacy Redirection capabilities of the AMWebARS Web Service, the azn_perminfo_amwebars_redirect_url must be included.

Usage

This stanza entry is optional.

Default value

azn_perminfo_rules_adi_request azn_perminfo_reason_rule_failed

Example

permission-info-returned = azn_perminfo_rules_adi_request
azn_perminfo_reason_rule_failed

Parent topic: [aznapi-configuration] stanza

policy-attr-separatorpolicy-attr-separatorpolicy-attr-separator stanza entryaznapi-configuration stanzaentriespolicy-attr-separatoraznapi-configuration stanzaaznapi-configuration stanzapolicy-attr-separator entrySyntax policy-attr-separator = separator Description Specifies the character that WebSEAL uses for the following services: Credential policy entitlements service.Registry entitlements service.For the credential policy entitlements service to work properly, a user's DN cannot contain the specified separator. If the user DN contains this separator then WebSEAL fails when attempting to retrieve the user's policy attributes. Options separator The character that WebSEAL uses for the credential policy entitlements service and the registry entitlements service. Ensure that the chosen character is not present in any User DN values. Usage This stanza entry is optional. Default value By default, WebSEAL uses colon (:) as the separator for these services. Example policy-attr-separator = # [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

policy-attr-separator

Syntax

policy-attr-separator = separator

Description

Specifies the character that WebSEAL uses for the following services:

Credential policy entitlements service.

Registry entitlements service.

Note: For the credential policy entitlements service to work properly, a user's DN cannot contain the specified separator. If the user DN contains this separator then WebSEAL fails when attempting to retrieve the user's policy attributes.

Options

separator

The character that WebSEAL uses for the credential policy entitlements service and the registry entitlements service. Ensure that the chosen character is not present in any User DN values.

Usage

This stanza entry is optional.

Default value

By default, WebSEAL uses colon (:) as the separator for these services.

Example

policy-attr-separator = #

Parent topic: [aznapi-configuration] stanza

policy-cache-sizepolicy-cache-sizepolicy-cache-size stanza entryaznapi-configuration stanzaentriespolicy-cache-sizeaznapi-configuration stanzaaznapi-configuration stanzapolicy-cache-size entrySyntax policy-cache-size = cache_size Description The maximum size of the in-memory policy cache is configurable. The cache consists of policy and the relationships between policy and resources. The knowledge that a resource has no directly associated policy is also cached. Options cache_size The maximum cache size should be relative to the number of policy objects defined and the number of resources protected and the available memory. A reasonable algorithm to begin with is: (number of policy objects * 3) + (number of protected resources * 3) This value controls how much information is cached. A larger cache will potentially improve the application performance but use additional memory as well. Size is specified as the number of entries. Usage This stanza entry is optional. Default value None. Example policy-cache-size = 32768 [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

policy-cache-size

Syntax

policy-cache-size = cache_size

Description

The maximum size of the in-memory policy cache is configurable. The cache consists of policy and the relationships between policy and resources. The knowledge that a resource has no directly associated policy is also cached.

Options

cache_size

The maximum cache size should be relative to the number of policy objects defined and the number of resources protected and the available memory.

A reasonable algorithm to begin with is: (number of policy objects * 3) + (number of protected resources * 3)

This value controls how much information is cached. A larger cache will potentially improve the application performance but use additional memory as well.

Size is specified as the number of entries.

Usage

This stanza entry is optional.

Default value

None.

Example

policy-cache-size = 32768

Parent topic: [aznapi-configuration] stanza

resource-manager-provided-adiresource-manager-provided-adiresource-manager-provided-adi stanza entryaznapi-configuration stanzaentriesresource-manager-provided-adiaznapi-configuration stanzaaznapi-configuration stanzaresource-manager-provided-adi entrySyntax resource-manager-provided-adi = prefix Description A list of string prefixes that identify Authorization Decision Information (ADI) to be supplied by the resource manager (in this case, WebSEAL). Options prefixThe default settings below tell the authorization engine that when it requires ADI with the prefixes AMWS_hd_, AMWS_qs_ ,or AMWS_pb_ to evaluate a boolean authorization rule, and the ADI is not available in either the credential or application context passed in with the access decision call, that the engine should fail the access decision and request that the resource manager retry the request and provide the required data in the application context of the next request. Usage This stanza entry is optional. Default value AMWS_hd_, AMWS_pb_, AMWS_qs_ Example resource-manager-provided-adi = AMWS_hd_ resource-manager-provided-adi = AMWS_pb_ resource-manager-provided-adi = AMWS_qs_ [aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

resource-manager-provided-adi

Syntax

resource-manager-provided-adi = prefix

Description

A list of string prefixes that identify Authorization Decision Information (ADI) to be supplied by the resource manager (in this case, WebSEAL).

Options

prefix

The default settings below tell the authorization engine that when it requires ADI with the prefixes AMWS_hd_, AMWS_qs_ ,or AMWS_pb_ to evaluate a boolean authorization rule, and the ADI is not available in either the credential or application context passed in with the access decision call, that the engine should fail the access decision and request that the resource manager retry the request and provide the required data in the application context of the next request.

Usage

This stanza entry is optional.

Default value

AMWS_hd_, AMWS_pb_, AMWS_qs_

Example

resource-manager-provided-adi = AMWS_hd_
resource-manager-provided-adi = AMWS_pb_
resource-manager-provided-adi = AMWS_qs_

Parent topic: [aznapi-configuration] stanza

skip-eas-on-bypass-popUse the skip-eas-on-bypass-pop entry to control whether the BypassPop setting is ignored if an EAS is to be called.aznapi-configuration stanzaskip-eas-on-bypass-popskip-eas-on-bypass-popaznapi-configuration stanzaSyntax skip-eas-on-bypass-pop = {yes|no}Description This configuration entry takes effect only when the authenticated user's effective ACL to the requested resource has the BypassPOP flag turned on. Setting this configuration entry to yes might affect normal EAS usage that makes authorization decisions for the access of protected resources. For example, if the skip-eas-on-bypass-pop entry is set to no or not present, the BypassPOP flag is ignored and the EAS is called for authorization when a protected resource is accessed. If this entry is set to yes, the BypassPOP flag takes effect and the EAS is no longer called to make the authorization decision. Take this fact into consideration when you set this configuration entry.Options yesDo not ignore the BypassPop flag when the system decides whether to call into the EAS.noIgnore the BypassPOP flag when the system decides whether to call into the EAS.Usage This stanza entry is optional. If this entry is not present, the BypassPOP flag is ignored when the system decides whether to call into EAS.Default valuenoExample skip-eas-on-bypass-pop = no[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

skip-eas-on-bypass-pop

Use the skip-eas-on-bypass-pop entry to control whether the BypassPop setting is ignored if an EAS is to be called.

Syntax

skip-eas-on-bypass-pop = {yes|no}

Description

This configuration entry takes effect only when the authenticated user's effective ACL to the requested resource has the BypassPOP flag turned on.

Note: Setting this configuration entry to yes might affect normal EAS usage that makes authorization decisions for the access of protected resources. For example, if the skip-eas-on-bypass-pop entry is set to no or not present, the BypassPOP flag is ignored and the EAS is called for authorization when a protected resource is accessed. If this entry is set to yes, the BypassPOP flag takes effect and the EAS is no longer called to make the authorization decision. Take this fact into consideration when you set this configuration entry.

Options

yes

Do not ignore the BypassPop flag when the system decides whether to call into the EAS.

no

Ignore the BypassPOP flag when the system decides whether to call into the EAS.

Usage

This stanza entry is optional. If this entry is not present, the BypassPOP flag is ignored when the system decides whether to call into EAS.

Default value

no

Example

skip-eas-on-bypass-pop = no

Parent topic: [aznapi-configuration] stanza

special-easspecial-easspecial-easUse the special-eas stanza entry to allow the path to the effective POP for the protected resource being accessed, to be passed to the EAS. aznapi-configuration stanzaspecial-easspecial-easaznapi-configuration stanzaPOPeffectivepathSyntax special-eas = EAS-triggerDescription Adding the special-eas entry to the [aznapi-configuration] stanza activates the process to pass the path of the effective POP to EAS. Setting this value is necessary for multiple policy support.Options EAS-triggerSpecify the value that is set by the policy trigger defined in the [aznapi-external-authzn-services] stanza.Usage This stanza entry is not required.Default value None.ExampleIf the following rba_pop_trigger trigger is defined:[aznapi-external-authzn-services] rba_pop_trigger = /opt/pdweb/librtsseas.so Then, use the following stanza and entry to indicate that the rba_pop_trigger is a special trigger:[aznapi-configuration] special-eas = rba_pop_trigger[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

special-eas

Use the special-eas stanza entry to allow the path to the effective POP for the protected resource being accessed, to be passed to the EAS.

Syntax

special-eas = EAS-trigger

Description

Adding the special-eas entry to the [aznapi-configuration] stanza activates the process to pass the path of the effective POP to EAS. Setting this value is necessary for multiple policy support.

Options

EAS-trigger

Specify the value that is set by the policy trigger defined in the [aznapi-external-authzn-services] stanza.

Usage

This stanza entry is not required.

Default value

None.

Example

If the following rba_pop_trigger trigger is defined:

[aznapi-external-authzn-services]
rba_pop_trigger = /opt/pdweb/librtsseas.so

Then, use the following stanza and entry to indicate that the rba_pop_trigger is a special trigger:

[aznapi-configuration]
special-eas = rba_pop_trigger

Parent topic: [aznapi-configuration] stanza

xsl-stylesheet-prologxsl-stylesheet-prologxsl-stylesheet-prolog stanza entryaznapi-configuration stanzaentriesxsl-stylesheet-prologaznapi-configuration stanzaaznapi-configuration stanzaxsl-stylesheet-prolog entrySyntax xsl-stylesheet-prolog = prologDescription The prolog to be added to the top of the XSL stylesheet that is created using the XSL text that defines a boolean authorization rule. Options prologThe prolog to be added to the top of the XSL stylesheet that is created using the XSL text that defines a boolean authorization rule.Usage This stanza entry is optional.Default value <?xml version='1.0' encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> <xsl:output method = 'text' omit-xml-declaration='yes' indent='no'/> <xsl:template match='text()'> </xsl:template>Example xsl-stylesheet-prolog = <?xml version='1.0' encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> <xsl:output method = 'text' omit-xml-declaration='yes' indent='no'/> <xsl:template match='text()'> </xsl:template>[aznapi-configuration] stanzaUse the [aznapi-configuration] stanza to configure the authorization API services.

xsl-stylesheet-prolog

Syntax

xsl-stylesheet-prolog = prolog

Description

The prolog to be added to the top of the XSL stylesheet that is created using the XSL text that defines a boolean authorization rule.

Options

prolog

The prolog to be added to the top of the XSL stylesheet that is created using the XSL text that defines a boolean authorization rule.

Usage

This stanza entry is optional.

Default value

<?xml version='1.0' encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> <xsl:output method = 'text' omit-xml-declaration='yes' indent='no'/> <xsl:template match='text()'> </xsl:template>

Example

xsl-stylesheet-prolog = <?xml version='1.0' encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
version='1.0'> <xsl:output method = 'text' omit-xml-declaration='yes'
indent='no'/> <xsl:template match='text()'> </xsl:template>

Parent topic: [aznapi-configuration] stanza

[azn-decision-info] stanza[azn-decision-info] stanzaIBM Security Access Manager for Web WebSEAL [azn-decision-info] stanzaUse the [azn-decision-info] stanza to define any extra information for the authorization framework to use when it is making authorization decisions. This extra information is obtained from elements of the HTTP request.azn-decision-info stanzastanzasazn-decision-infoStanza referenceazn-decision-infoUse the azn-decision-info stanza entry to add extra information from the HTTP request, such as the method, to the authorization decision information.

[azn-decision-info] stanza

Use the [azn-decision-info] stanza to define any extra information for the authorization framework to use when it is making authorization decisions. This extra information is obtained from elements of the HTTP request.

azn-decision-info
Use the azn-decision-info stanza entry to add extra information from the HTTP request, such as the method, to the authorization decision information.

Parent topic: Stanza reference

azn-decision-infoazn-decision-infoIBM Security Access Manager for Web WebSEAL azn-decision-info stanza entryUse the azn-decision-info stanza entry to add extra information from the HTTP request, such as the method, to the authorization decision information.azn-decision-info stanza entryazn-decision-info stanzaentriesazn-decision-infoazn-decision-info stanzaazn-decision-info stanzaSyntax <attr-name> = <http-info> Description This stanza defines any extra information that is available to the authorization framework when it makes authorization decisions. This extra information can be obtained from the following elements of the HTTP request: HTTP methodHTTP schemeHTTP cookiesRequest URIClient IP addressHTTP headersQuery stringPOST data If the requested element is not in the HTTP request, no corresponding attribute is added to the authorization decision information. Options <attr-name>The name of the attribute that contains the HTTP information.<http-info>The source of the information. It can be one of the following values: methodschemeuriclient_ipheader:<header-name>Where <header-name> is the name of the header that contains information for WebSEAL to add to the authorization decision information. For example, Host.cookie:<cookie-name>Where<cookie-name> is the name of the cookie that contains information for WebSEAL to add to the authorization decision information.query-arg:<query-arg-name>Where <query-arg-name> is the query string parameter that contains information for WebSEAL to add to the authorization decision information. This entry indicates to WebSEAL that the query string parameters that are part of the requested resource URL are used for the access decision. If the specified value is found, it is sent to the EAS for the decision-making process. post-data:<post-data-name>Where the format of the <post-data-name> depends on the type of POST data.WebSEAL supports two types of POST data:Normal FORM data, which is the application/x-www-form-urlencoded content-type. To add normal FORM data to the HTTP request, use the following format for this entry:post-data:<post-data-name>Where the <post-data-name> is the name of the selected form data field in the request. WebSEAL adds the corresponding value for this field to the authorization decision information.JavaScript Object Notation (JSON) data, which is the application/json content-type. For more information about the JSON syntax, see http://www.json.org.To search for a key in the JSON data and add its value to the HTTP request, use the following format:post-data:/"<JSON-node-id>"[[/"<JSON-node-id>"][<JSON-array-indx>]]...Where:"<JSON-node-id>"The name of a node in the JSON data. JSON data is essentially a hierarchy of name-value pairs. The forward slash character (/) that precedes each "<JSON-node-id>" identifies a level of the JSON hierarchy. You can repeatedly add [/<JSON-node-id>] elements to move through the JSON data hierarchy. Identify the node that contains the value that you want WebSEAL to add to the authorization decision information.Each <JSON-node-id> must be:Enclosed in double quotation marks.Preceded by a forward slash character (/).A case-sensitive match with a node in the JSON data hierarchy.If WebSEAL does not find a matching node name in the POST data, no corresponding attribute is added to the authorization decision information. <JSON-array-indx> The contents of a node in the JSON data might be a JSON array. If you configure WebSEAL to search for a JSON node that contains an array, specify the array index of the value that you want WebSEAL to use. Use a base of 0. In other words, the first entry in the array has an index of 0. The <JSON-array-indx> is not enclosed in double quotation marks. The square brackets ([]) in this syntax indicate an optional element. Do not include square brackets in your configuration entry. Similarly, the ellipsis (...) indicates that you can repeat the optional elements that precede it. Do not include the ellipsis in your configuration entry.WebSEAL returns only node values of the following JSON types:StringNumbertrue or falsenullIf the value of the selected node is not one of the types in this list, WebSEAL does not return it as authorization decision information. Object and Array types cannot be added to the authorization decision information. Usage This stanza entry is optional. Default value None. Example 1: Standard HTTP elements HTTP_REQUEST_METHOD = method HTTP_HOST_HEADER= header:HostIf these example configuration entries are set in the [azn-decision-info] stanza, WebSEAL adds the following attributes to the authorization decision information:HTTP_REQUEST_METHODContains the HTTP method.HTTP_HOST_HEADERContains the data from the Host header. Example 2: JSON POST dataFor this example, consider the following JSON form data:{ "userid": "jdoe", "transactionValue": "146.67", "accountBalances": { "chequing": "4345.45", "savings": "12432.23", "creditLine": "19999.12" } }The following configuration entries in the [azn-decision-info] stanza extract information from this JSON form data. USERID = post-data:/"userid" SAVINGS = post-data:/"accountBalances"/"savings"The first entry prompts WebSEAL to search for the JSON node called "userid". In this example, the value that is associated with the "userid" node is jdoe. WebSEAL adds this value to the HTTP request in an attribute called USERID.When WebSEAL processes the second entry, it searches for a top-level JSON node called "accountBalances". Under the "accountBalances" hierarchy, WebSEAL locates the "savings" JSON node. In the example data, the value that is associated with this node is 12432.23. WebSEAL adds this value to the HTTP request in an attribute called SAVINGS.WebSEAL adds the following attributes to the authorization decision information:USERIDContains the value jdoe.SAVINGSContains the value 12432.23.Example 3: JSON POST data with a JSON array valueFor this example, consider the following JSON form data:{ "userid": "jdoe", "transactionValue": "146.67", "accounts": [ {"name": "chequing", "balance": "4350.45"}, {"name": "savings", "balance": "4350.46"} ] } The following configuration entry is included in the [azn-decision-info] stanza:SAVINGSBAL = post-data:/"accounts"/1/"balance"WebSEAL processes this entry as follows: Searches for a top-level node in the JSON data called "accounts". Locates the element in position 1 of the JSON array (base 0). Searches for the "balance" name-value pair in this array element.Adds the associated value to the authorization decision information.In this example, WebSEAL adds the following attribute to the authorization decision information:SAVINGSBALContains the value 4350.46.Example 4: Query stringFor this example, consider the following entry in the [azn-decision-info] stanza:urn:company:user:name = query-arg:usernameIf a user attempts to access the EAS protected resource:http://www.example.com/t1.html?type=1&username=ann&dept=testWebSEAL sends the following value to the EAS for use in the decision-making process:urn:company:user:name=ann[azn-decision-info] stanzaUse the [azn-decision-info] stanza to define any extra information for the authorization framework to use when it is making authorization decisions. This extra information is obtained from elements of the HTTP request.

azn-decision-info

Use the azn-decision-info stanza entry to add extra information from the HTTP request, such as the method, to the authorization decision information.

Syntax

<attr-name> = <http-info>

Description

This stanza defines any extra information that is available to the authorization framework when it makes authorization decisions. This extra information can be obtained from the following elements of the HTTP request:

HTTP method

HTTP scheme

HTTP cookies

Request URI

Client IP address

HTTP headers

Query string

POST data

If the requested element is not in the HTTP request, no corresponding attribute is added to the authorization decision information.

Options

<attr-name>

The name of the attribute that contains the HTTP information.

<http-info>

The source of the information. It can be one of the following values:

method

scheme

uri

client_ip

header:<header-name>

Where <header-name> is the name of the header that contains information for WebSEAL to add to the authorization decision information. For example, Host.

cookie:<cookie-name>

Where<cookie-name> is the name of the cookie that contains information for WebSEAL to add to the authorization decision information.

query-arg:<query-arg-name>

Where <query-arg-name> is the query string parameter that contains information for WebSEAL to add to the authorization decision information. This entry indicates to WebSEAL that the query string parameters that are part of the requested resource URL are used for the access decision. If the specified value is found, it is sent to the EAS for the decision-making process.

post-data:<post-data-name>

Where the format of the <post-data-name> depends on the type of POST data.

WebSEAL supports two types of POST data:

Normal FORM data, which is the application/x-www-form-urlencoded content-type.

To add normal FORM data to the HTTP request, use the following format for this entry:

post-data:<post-data-name>

Where the <post-data-name> is the name of the selected form data field in the request. WebSEAL adds the corresponding value for this field to the authorization decision information.

JavaScript Object Notation (JSON) data, which is the application/json content-type. For more information about the JSON syntax, see http://www.json.org.

To search for a key in the JSON data and add its value to the HTTP request, use the following format:

post-data:/"<JSON-node-id>"[[/"<JSON-node-id>"][<JSON-array-indx>]]...

Where:

"<JSON-node-id>"

The name of a node in the JSON data.

JSON data is essentially a hierarchy of name-value pairs. The forward slash character (/) that precedes each "<JSON-node-id>" identifies a level of the JSON hierarchy. You can repeatedly add [/<JSON-node-id>] elements to move through the JSON data hierarchy. Identify the node that contains the value that you want WebSEAL to add to the authorization decision information.

Each <JSON-node-id> must be:

Enclosed in double quotation marks.

Preceded by a forward slash character (/).

A case-sensitive match with a node in the JSON data hierarchy.

If WebSEAL does not find a matching node name in the POST data, no corresponding attribute is added to the authorization decision information.

<JSON-array-indx>

The contents of a node in the JSON data might be a JSON array. If you configure WebSEAL to search for a JSON node that contains an array, specify the array index of the value that you want WebSEAL to use. Use a base of 0. In other words, the first entry in the array has an index of 0.

Note: The <JSON-array-indx> is not enclosed in double quotation marks.

Usage notes:

The square brackets ([]) in this syntax indicate an optional element. Do not include square brackets in your configuration entry. Similarly, the ellipsis (...) indicates that you can repeat the optional elements that precede it. Do not include the ellipsis in your configuration entry.

WebSEAL returns only node values of the following JSON types:

String

Number

true or false

null

If the value of the selected node is not one of the types in this list, WebSEAL does not return it as authorization decision information.

Object and Array types cannot be added to the authorization decision information.

Usage

This stanza entry is optional.

Default value

None.

Example 1: Standard HTTP elements

HTTP_REQUEST_METHOD = method
HTTP_HOST_HEADER= header:Host

If these example configuration entries are set in the [azn-decision-info] stanza, WebSEAL adds the following attributes to the authorization decision information:

HTTP_REQUEST_METHOD

Contains the HTTP method.

HTTP_HOST_HEADER

Contains the data from the Host header.

Example 2: JSON POST data

For this example, consider the following JSON form data:

{ "userid": "jdoe",
  "transactionValue": "146.67",
  "accountBalances": {
        "chequing": "4345.45",
        "savings": "12432.23",
        "creditLine": "19999.12"
    }
}

The following configuration entries in the [azn-decision-info] stanza extract information from this JSON form data.

USERID = post-data:/"userid"
SAVINGS = post-data:/"accountBalances"/"savings"

The first entry prompts WebSEAL to search for the JSON node called "userid". In this example, the value that is associated with the "userid" node is jdoe. WebSEAL adds this value to the HTTP request in an attribute called USERID.

When WebSEAL processes the second entry, it searches for a top-level JSON node called "accountBalances". Under the "accountBalances" hierarchy, WebSEAL locates the "savings" JSON node. In the example data, the value that is associated with this node is 12432.23. WebSEAL adds this value to the HTTP request in an attribute called SAVINGS.

WebSEAL adds the following attributes to the authorization decision information:

USERID

Contains the value jdoe.

SAVINGS

Contains the value 12432.23.

Example 3: JSON POST data with a JSON array value

For this example, consider the following JSON form data:

{
    "userid": "jdoe",
    "transactionValue": "146.67",
    "accounts": [
        {"name": "chequing", "balance": "4350.45"},
        {"name": "savings", "balance": "4350.46"}
    ]
}

The following configuration entry is included in the [azn-decision-info] stanza:

SAVINGSBAL = post-data:/"accounts"/1/"balance"

WebSEAL processes this entry as follows:

Searches for a top-level node in the JSON data called "accounts".

Locates the element in position 1 of the JSON array (base 0).

Searches for the "balance" name-value pair in this array element.

Adds the associated value to the authorization decision information.

In this example, WebSEAL adds the following attribute to the authorization decision information:

SAVINGSBAL

Contains the value 4350.46.

Example 4: Query string

For this example, consider the following entry in the [azn-decision-info] stanza:

urn:company:user:name = query-arg:username

If a user attempts to access the EAS protected resource:

http://www.example.com/t1.html?type=1&username=ann&dept=test

WebSEAL sends the following value to the EAS for use in the decision-making process:

urn:company:user:name=ann

Parent topic: [azn-decision-info] stanza

[aznapi-external-authzn-services] stanza[aznapi-external-authzn-services] stanzaIBM Security Access Manager for Web WebSEAL [aznapi-external-authzn-services] stanzaUse the [aznapi-external-authzn-services] stanza to configure the OAuth External Authorization Service (EAS). aznapi-external-authzn-services stanzastanzasaznapi-external-authzn-servicesStanza referencepolicy-triggerUse the policy-trigger stanza entry to define the external authorization service.

[aznapi-external-authzn-services] stanza

Use the [aznapi-external-authzn-services] stanza to configure the OAuth External Authorization Service (EAS).

policy-trigger
Use the policy-trigger stanza entry to define the external authorization service.

Parent topic: Stanza reference

policy-triggerpolicy-triggerIBM Security Access Manager for Web WebSEAL policy-trigger stanza entryUse the policy-trigger stanza entry to define the external authorization service.policy-trigger stanza entryaznapi-external-authzn-services stanzaentriespolicy-triggeraznapi-external-authzn-services stanzaaznapi-external-authzn-services stanzapolicy-trigger entrySyntax policy-trigger = plug-in_location [-weight N [& plug-in_parameters]] DescriptionDefines the external authorization service. Options policy-trigger Any string that is recognized as a valid key name. Stanza key names cannot contain white space or the open bracket ([) and close bracket (]) characters. The bracket characters are used to define new stanza names. The policy-trigger is case-sensitive for action set definitions because the actions themselves are case-sensitive. However, the policy-trigger is not case-sensitive if the trigger is a protected object policy (POP) attribute. plug-in_location The path name to the shared library or DLL module that contains the implementation of the plug-in for the specified policy trigger. The path name can be in a truncated form if the external authorization service is to be loaded by clients on multiple platforms. In this case, the service dispatcher searches for the plug-in using platform-specific prefixes and suffixes to match DLL names. The name of the OAuth EAS plug-in is amwoautheas. For example:libamwoautheas.soN The weight parameter is an unsigned size_t value and is optional. The value signifies the weight that any decision returned by this external authorization service is given in the entire decision process.plug-in_parameters Optionally, the external authorization service can be passed more initialization information in the form of arguments. The arguments must be preceded by the ampersand "&". The authorization service takes the remainder of the string that follows the ampersand &, breaks up the string into white space separated tokens, and passes the tokens directly to the administration service's initialization interface, azn_svc_initialize(), in the argv array parameter. The number of strings in the argv array is indicated by the argc function parameter. A single parameter is required by the OAuth EAS. This parameter corresponds to the name of the OAuth EAS configuration file. That is, the file that contains the [oauth-eas] stanza and the corresponding [tfim-cluster:<cluster>] stanza. Usage This stanza entry is required when you are configuring OAuth EAS authentication. Default value None. Example The following example is an operation-based trigger with a user-defined action group of Printer and the actions rxT in that group. To specify the primary action group, specify only :rxT. The primary action group can be represented with an empty action group name or the string primary can be used explicitly. All lowercase letters are required if primary is used explicitly. Any policy-trigger that does not contain a colon (:) character is considered to be a POP attribute name.Printer:rxT = eas_plugin -weight 60 & -server barneyThe following example is for a POP attribute trigger called webseal_pop_trigger. When a POP that contains a reference to this string is encountered, the appropriate external authorization service is called to take part in the access decision. webseal_pop_trigger = eas_plugin_2 -weight 70 & -hostname fred In order for the above POP attribute trigger to work, POP configuration must first be completed by the secure domain administrator, by using the pdadmin pop commands. The following is an example configuration for the OAuth EAS, where the file oauth_eas.conf contains the [oauth-eas] stanza and the corresponding [tfim-cluster:<cluster>] stanza. This example is entered as one line in the WebSEAL configuration file:webseal_pop_trigger = libamwoautheas.so & oauth_eas.conf[aznapi-external-authzn-services] stanzaUse the [aznapi-external-authzn-services] stanza to configure the OAuth External Authorization Service (EAS).

policy-trigger

Use the policy-trigger stanza entry to define the external authorization service.

Syntax

policy-trigger = plug-in_location [-weight N [& plug-in_parameters]]

Description

Defines the external authorization service.

Options

policy-trigger

Any string that is recognized as a valid key name. Stanza key names cannot contain white space or the open bracket ([) and close bracket (]) characters. The bracket characters are used to define new stanza names. The policy-trigger is case-sensitive for action set definitions because the actions themselves are case-sensitive. However, the policy-trigger is not case-sensitive if the trigger is a protected object policy (POP) attribute.

plug-in_location

The path name to the shared library or DLL module that contains the implementation of the plug-in for the specified policy trigger. The path name can be in a truncated form if the external authorization service is to be loaded by clients on multiple platforms. In this case, the service dispatcher searches for the plug-in using platform-specific prefixes and suffixes to match DLL names.

The name of the OAuth EAS plug-in is amwoautheas. For example:

libamwoautheas.so

N

The weight parameter is an unsigned size_t value and is optional. The value signifies the weight that any decision returned by this external authorization service is given in the entire decision process.

plug-in_parameters

Optionally, the external authorization service can be passed more initialization information in the form of arguments. The arguments must be preceded by the ampersand "&". The authorization service takes the remainder of the string that follows the ampersand &, breaks up the string into white space separated tokens, and passes the tokens directly to the administration service's initialization interface, azn_svc_initialize(), in the argv array parameter. The number of strings in the argv array is indicated by the argc function parameter.

A single parameter is required by the OAuth EAS. This parameter corresponds to the name of the OAuth EAS configuration file. That is, the file that contains the [oauth-eas] stanza and the corresponding [tfim-cluster:<cluster>] stanza.

Usage

This stanza entry is required when you are configuring OAuth EAS authentication.

Default value

None.

Example

The following example is an operation-based trigger with a user-defined action group of Printer and the actions rxT in that group. To specify the primary action group, specify only :rxT. The primary action group can be represented with an empty action group name or the string primary can be used explicitly. All lowercase letters are required if primary is used explicitly. Any policy-trigger that does not contain a colon (:) character is considered to be a POP attribute name.

Printer:rxT = eas_plugin -weight 60 & -server barney

The following example is for a POP attribute trigger called webseal_pop_trigger. When a POP that contains a reference to this string is encountered, the appropriate external authorization service is called to take part in the access decision.

webseal_pop_trigger = eas_plugin_2 -weight 70 & -hostname fred

Note: In order for the above POP attribute trigger to work, POP configuration must first be completed by the secure domain administrator, by using the pdadmin pop commands.

The following is an example configuration for the OAuth EAS, where the file oauth_eas.conf contains the [oauth-eas] stanza and the corresponding [tfim-cluster:<cluster>] stanza. This example is entered as one line in the WebSEAL configuration file:

webseal_pop_trigger = libamwoautheas.so & oauth_eas.conf

Parent topic: [aznapi-external-authzn-services] stanza

[ba] stanza[ba] stanzaIBM Security Access Manager for Web WebSEAL [ba] stanzaUse the [ba] stanza to configure basic authentication.ba stanzastanzasbaStanza referenceba-authUse the ba-auth stanza entry to enable basic authentication.basic-auth-realmUse the basic-auth-realm stanza entry to specify the basic authentication realm name.

[ba] stanza

Use the [ba] stanza to configure basic authentication.

ba-auth
Use the ba-auth stanza entry to enable basic authentication.

basic-auth-realm
Use the basic-auth-realm stanza entry to specify the basic authentication realm name.

Parent topic: Stanza reference

ba-authba-authIBM Security Access Manager for Web WebSEAL ba-auth stanza entryUse the ba-auth stanza entry to enable basic authentication.ba-auth stanza entryba stanzaentriesba-authba stanzaba stanzaba-auth entrySyntax ba-auth = {none|http|https|both} Description Enables the use of the Basic Authentication mechanism for authentication. Options {none|http|https|both} Specifies which protocols are supported. The value both means both HTTP and HTTPS. Usage This stanza entry is required. Default value https Example ba-auth = https [ba] stanzaUse the [ba] stanza to configure basic authentication.

ba-auth

Use the ba-auth stanza entry to enable basic authentication.

Syntax

ba-auth = {none|http|https|both}

Description

Enables the use of the Basic Authentication mechanism for authentication.

Options

{none|http|https|both}

Specifies which protocols are supported. The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

https

Example

ba-auth = https

Parent topic: [ba] stanza

basic-auth-realmbasic-auth-realmIBM Security Access Manager for Web WebSEAL basic-auth-realm stanza entryUse the basic-auth-realm stanza entry to specify the basic authentication realm name.basic-auth-realm stanza entryba stanzaentriesbasic-auth-realmba stanzaba stanzabasic-auth-realm entrySyntax basic-auth-realm = realm_name Description String value that specifies the realm name. Options realm_name This name is displayed in the browser dialog box when the user is prompted for login information. The string must consist of ASCII characters and can contain spaces. Usage This stanza entry is optional. Default value Access Manager Example basic-auth-realm = Access Manager [ba] stanzaUse the [ba] stanza to configure basic authentication.

basic-auth-realm

Use the basic-auth-realm stanza entry to specify the basic authentication realm name.

Syntax

basic-auth-realm = realm_name

Description

String value that specifies the realm name.

Options

realm_name

This name is displayed in the browser dialog box when the user is prompted for login information. The string must consist of ASCII characters and can contain spaces.

Usage

This stanza entry is optional.

Default value

Access Manager

Example

basic-auth-realm = Access Manager

Parent topic: [ba] stanza

[cdsso] stanza[cdsso] stanzaIBM Security Access Manager for Web WebSEAL [cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.cdsso stanzastanzascdssoStanza referenceauthtoken-lifetimeUse the authtoken-lifetime stanza entry to specify the lifetime of the single sign-on authentication token.cdsso-argumentUse the cdsso-argument stanza entry to specify the name of the query string argument that contains the cross-domain single sign-on token in the request.cdsso-authUse the cdsso-auth stanza entry to enable the CDSSO token consume module.cdsso-createUse the cdsso-create stanza entry to enable the CDSSO token create module.clean-cdsso-urlsUse the clean-cdsso-urls stanza entry to control whether the PD-ID and PD-REFERER query string arguments are removed from the URI that WebSEAL passes to the junction.propagate-cdmf-errorsuse-utf8

[cdsso] stanza

Use the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

authtoken-lifetime
Use the authtoken-lifetime stanza entry to specify the lifetime of the single sign-on authentication token.

cdsso-argument
Use the cdsso-argument stanza entry to specify the name of the query string argument that contains the cross-domain single sign-on token in the request.

cdsso-auth
Use the cdsso-auth stanza entry to enable the CDSSO token consume module.

cdsso-create
Use the cdsso-create stanza entry to enable the CDSSO token create module.

clean-cdsso-urls
Use the clean-cdsso-urls stanza entry to control whether the PD-ID and PD-REFERER query string arguments are removed from the URI that WebSEAL passes to the junction.

propagate-cdmf-errors

use-utf8

Parent topic: Stanza reference

authtoken-lifetimeauthtoken-lifetimeIBM Security Access Manager for Web WebSEAL authtoken-lifetime stanza entryUse the authtoken-lifetime stanza entry to specify the lifetime of the single sign-on authentication token.authtoken-lifetime stanza entrycdsso stanzaentriesauthtoken-lifetimecdsso stanzacdsso stanzaauthtoken-lifetime entrySyntax authtoken-lifetime = number_of_seconds Description Positive integer that expresses the number of seconds for which the single signon authentication token is valid. Options number_of_secondsMinimum value: 1. There is no maximum value. Usage This stanza entry is required. Default value 180 Example authtoken-lifetime = 180 [cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

authtoken-lifetime

Use the authtoken-lifetime stanza entry to specify the lifetime of the single sign-on authentication token.

Syntax

authtoken-lifetime = number_of_seconds

Description

Positive integer that expresses the number of seconds for which the single signon authentication token is valid.

Options

number_of_seconds

Minimum value: 1. There is no maximum value.

Usage

This stanza entry is required.

Default value

180

Example

authtoken-lifetime = 180

Parent topic: [cdsso] stanza

cdsso-argumentcdsso-argumentIBM Security Access Manager for Web WebSEAL cdsso-argument stanza entryUse the cdsso-argument stanza entry to specify the name of the query string argument that contains the cross-domain single sign-on token in the request.cdsso-argument stanza entrycdsso stanzaentriescdsso-argumentcdsso stanzacdsso stanzacdsso-argument entrySyntax cdsso-argument = argument_name Description Name of the argument containing the cross-domain single signon token in a query string in a request. This is used to identify incoming requests that contain CDSSO authentication information. Options argument_nameName of the argument containing the cross-domain single signon token in a query string in a request. Valid characters are any ASCII characters, except for question mark ( ? ), ampersand ( & ), and equals sign ( = ). Usage This stanza entry is required. Default value PD-ID Example cdsso-argument = PD-ID [cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

cdsso-argument

Use the cdsso-argument stanza entry to specify the name of the query string argument that contains the cross-domain single sign-on token in the request.

Syntax

cdsso-argument = argument_name

Description

Name of the argument containing the cross-domain single signon token in a query string in a request. This is used to identify incoming requests that contain CDSSO authentication information.

Options

argument_name

Name of the argument containing the cross-domain single signon token in a query string in a request. Valid characters are any ASCII characters, except for question mark ( ? ), ampersand ( & ), and equals sign ( = ).

Usage

This stanza entry is required.

Default value

PD-ID

Example

cdsso-argument = PD-ID

Parent topic: [cdsso] stanza

cdsso-authcdsso-authIBM Security Access Manager for Web WebSEAL cdsso-auth stanza entryUse the cdsso-auth stanza entry to enable the CDSSO token consume module.cdsso-auth stanza entrycdsso stanzaentriescdsso-authcdsso stanzacdsso stanzacdsso-auth entrySyntax cdsso-auth = {none|http|https|both} Description Enables WebSEAL to accept tokens. Options {none|http|https|both}Specifies which protocols are supported. The value both means both HTTP and HTTPS. Usage This stanza entry is required. Default value none Example cdsso-auth = none [cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

cdsso-auth

Use the cdsso-auth stanza entry to enable the CDSSO token consume module.

Syntax

cdsso-auth = {none|http|https|both}

Description

Enables WebSEAL to accept tokens.

Options

{none|http|https|both}

Specifies which protocols are supported. The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

none

Example

cdsso-auth = none

Parent topic: [cdsso] stanza

cdsso-createcdsso-createIBM Security Access Manager for Web WebSEAL cdsso-create stanza entryUse the cdsso-create stanza entry to enable the CDSSO token create module.cdsso-create stanza entrycdsso stanzaentriescdsso-createcdsso stanzacdsso stanzacdsso-create entrySyntax cdsso-create = {none|http|https|both} Description Enables WebSEAL to accept tokens. Options {none|http|https|both}Specifies which protocols are supported. The value both means both HTTP and HTTPS. Usage This stanza entry is required. Default value none Example cdsso-create = none [cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

cdsso-create

Use the cdsso-create stanza entry to enable the CDSSO token create module.

Syntax

cdsso-create = {none|http|https|both}

Description

Enables WebSEAL to accept tokens.

Options

{none|http|https|both}

Specifies which protocols are supported. The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

none

Example

cdsso-create = none

Parent topic: [cdsso] stanza

clean-cdsso-urlsclean-cdsso-urlsIBM Security Access Manager for Web WebSEAL clean-cdsso-urls stanza entryUse the clean-cdsso-urls stanza entry to control whether the PD-ID and PD-REFERER query string arguments are removed from the URI that WebSEAL passes to the junction.clean-cdsso-urls stanza entrycdsso stanzaentriesclean-cdsso-urlscdsso stanzacdsso stanzaclean-cdsso-urls entrySyntax clean-cdsso-urls = {yes|no} Description The cdsso-argument (PD-ID) and PD-REFERER query string arguments can be passed to junctions. When this option is set to yes, these will be removed from the URI before the request is passed to the junction. Options yesThe argument containing the CDSSO token in a request query string and the PD-REFERER query string argument are removed from the URI before the request is passed to the junction.noThe CDSSO and PD-REFERER arguments are not removed from the URI before the request is passed to the junction. Usage This stanza entry is required. Default value no Example clean-cdsso-urls = no [cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

clean-cdsso-urls

Use the clean-cdsso-urls stanza entry to control whether the PD-ID and PD-REFERER query string arguments are removed from the URI that WebSEAL passes to the junction.

Syntax

clean-cdsso-urls = {yes|no}

Description

The cdsso-argument (PD-ID) and PD-REFERER query string arguments can be passed to junctions. When this option is set to yes, these will be removed from the URI before the request is passed to the junction.

Options

yes

The argument containing the CDSSO token in a request query string and the PD-REFERER query string argument are removed from the URI before the request is passed to the junction.

no

The CDSSO and PD-REFERER arguments are not removed from the URI before the request is passed to the junction.

Usage

This stanza entry is required.

Default value

no

Example

clean-cdsso-urls = no

Parent topic: [cdsso] stanza

propagate-cdmf-errorspropagate-cdmf-errorspropagate-cdmf-errors stanza entrycdsso stanzaentriespropagate-cdmf-errorscdsso stanzacdsso stanzapropagate-cdmf-errors entrySyntax propagate-cdmf-errors = {yes|no}Description Controls subsequent behavior of the token creation process when the cdmf_get_usr_attributes call fails to obtain the required extended attribute information and returns an error.Options yesA "yes" value forces the token creation process to abort when CDMF fails to obtain attributes and returns an error.noA "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error.Usage This stanza entry is not required.Default value noExample propagate-cdmf-errors = no[cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

propagate-cdmf-errors

Syntax

propagate-cdmf-errors = {yes|no}

Description

Controls subsequent behavior of the token creation process when the cdmf_get_usr_attributes call fails to obtain the required extended attribute information and returns an error.

Options

yes

A "yes" value forces the token creation process to abort when CDMF fails to obtain attributes and returns an error.

no

A "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error.

Usage

This stanza entry is not required.

Default value

no

Example

propagate-cdmf-errors = no

Parent topic: [cdsso] stanza

use-utf8use-utf8use-utf8 stanza entrycdsso stanzaentriesuse-utf8cdsso stanzacdsso stanzause-utf8 entrySyntax use-utf8 = {true|false} Description Use UTF–8 encoding for tokens used in cross domain single signon. Beginning with version 5.1, WebSEAL servers use UTF-8 encoding by default. For more information about multi-locale support with UTF-8, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy. Options trueWhen this stanza entry is set to true, tokens can be exchanged with other WebSEAL servers that use UTF-8 encoding. This configuration enables tokens to be used across different code pages (such as for a different language).falseFor backward compatibility with tokens created by WebSEAL servers from version prior to 5.1, set this stanza entry to false. Usage This stanza entry is required. Default value true Example use-utf8 = true [cdsso] stanzaUse the [cdsso] stanza to configure cross-domain single sign-on (CDSSO) authentication.

use-utf8

Syntax

use-utf8 = {true|false}

Description

Use UTF–8 encoding for tokens used in cross domain single signon. Beginning with version 5.1, WebSEAL servers use UTF-8 encoding by default. For more information about multi-locale support with UTF-8, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Options

true

When this stanza entry is set to true, tokens can be exchanged with other WebSEAL servers that use UTF-8 encoding. This configuration enables tokens to be used across different code pages (such as for a different language).

false

For backward compatibility with tokens created by WebSEAL servers from version prior to 5.1, set this stanza entry to false.

Usage

This stanza entry is required.

Default value

true

Example

use-utf8 = true

Parent topic: [cdsso] stanza

[cdsso-incoming-attributes] stanza[cdsso-incoming-attributes] stanzaIBM Security Access Manager for Web WebSEAL [cdsso-incoming-attributes] stanzaUse the [cdsso-incoming-attributes] stanza to specify the handling (extract or ignore) of each attribute in the cross-domain single sign-on token.cdsso-incoming-attributes stanzastanzascdsso-incoming-attributesStanza referenceattribute_patternUse the attribute_pattern stanza entry to control the attributes that WebSEAL accepts from the incoming CDSSO authentication token.

[cdsso-incoming-attributes] stanza

Use the [cdsso-incoming-attributes] stanza to specify the handling (extract or ignore) of each attribute in the cross-domain single sign-on token.

attribute_pattern
Use the attribute_pattern stanza entry to control the attributes that WebSEAL accepts from the incoming CDSSO authentication token.

Parent topic: Stanza reference

attribute_patternattribute_patternIBM Security Access Manager for Web WebSEAL attribute_pattern stanza entryUse the attribute_pattern stanza entry to control the attributes that WebSEAL accepts from the incoming CDSSO authentication token.attribute_pattern stanza entrycdsso-incoming-attributes stanzaentriesattribute_patterncdsso-incoming-attributes stanzacdsso-incoming-attributes stanzaattribute_pattern entrySyntax attribute_pattern = {preserve|refresh} Description Attributes to accept from incoming CDSSO authentication tokens. The attributes typically match those attributes declared in the [cdsso-token-attributes] stanza for the WebSEAL server in the source domain. The attribute_pattern can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters (*, [], ^, \,?). The order of attribute_pattern entries is important. WebSEAL uses the first entry that matches the attribute. Other entries are ignored. Options preserveAttributes matching a preserve entry, or matching none of the entries, are kept. If no entries are configured, then all attributes are kept. refreshAttributes in CDSSO authentication tokens that match a refresh entry are removed from the token. These attributes are removed before the CDMF library is called to map the remote user into the local domain. Usage This stanza entry is optional. Default value None. Example my_cred_attr1 = preserve [cdsso-incoming-attributes] stanzaUse the [cdsso-incoming-attributes] stanza to specify the handling (extract or ignore) of each attribute in the cross-domain single sign-on token.

attribute_pattern

Use the attribute_pattern stanza entry to control the attributes that WebSEAL accepts from the incoming CDSSO authentication token.

Syntax

attribute_pattern = {preserve|refresh}

Description

Attributes to accept from incoming CDSSO authentication tokens.

The attributes typically match those attributes declared in the [cdsso-token-attributes] stanza for the WebSEAL server in the source domain.

The attribute_pattern can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters (*, [], ^, \,?).

The order of attribute_pattern entries is important. WebSEAL uses the first entry that matches the attribute. Other entries are ignored.

Options

preserve

Attributes matching a preserve entry, or matching none of the entries, are kept. If no entries are configured, then all attributes are kept.

refresh

Attributes in CDSSO authentication tokens that match a refresh entry are removed from the token. These attributes are removed before the CDMF library is called to map the remote user into the local domain.

Usage

This stanza entry is optional.

Default value

None.

Example

my_cred_attr1 = preserve

Parent topic: [cdsso-incoming-attributes] stanza

[cdsso-peers] stanza[cdsso-peers] stanzaIBM Security Access Manager for Web WebSEAL [cdsso-peers] stanzaUse the [cdsso-peers] stanza to specify the peer servers that are participating in cross-domain single sign-on.cdsso-peers stanzastanzascdsso-peersStanza referencefully_qualified_hostnameUse the fully_qualified_hostname stanza entry to list the peer servers that are participating in cross-domain single sign-on and their associated key files.

[cdsso-peers] stanza

Use the [cdsso-peers] stanza to specify the peer servers that are participating in cross-domain single sign-on.

fully_qualified_hostname
Use the fully_qualified_hostname stanza entry to list the peer servers that are participating in cross-domain single sign-on and their associated key files.

Parent topic: Stanza reference

fully_qualified_hostnamefully_qualified_hostnameIBM Security Access Manager for Web WebSEAL fully_qualified_hostname stanza entryUse the fully_qualified_hostname stanza entry to list the peer servers that are participating in cross-domain single sign-on and their associated key files.fully_qualified_hostname stanza entrycdsso-peers stanzaentriesfully_qualified_hostnamecdsso-peers stanzacdsso-peers stanzafully_qualified_hostname entrySyntax fully_qualified_hostname = key_file Description List of peer servers that are participating in cross-domain single-sign on. Options key_fileThe name of server's key file. Usage This stanza entry is optional. Default value None. Example webhost2.ibm.com = cdsso.key [cdsso-peers] stanzaUse the [cdsso-peers] stanza to specify the peer servers that are participating in cross-domain single sign-on.

fully_qualified_hostname

Use the fully_qualified_hostname stanza entry to list the peer servers that are participating in cross-domain single sign-on and their associated key files.

Syntax

fully_qualified_hostname = key_file

Description

List of peer servers that are participating in cross-domain single-sign on.

Options

key_file

The name of server's key file.

Usage

This stanza entry is optional.

Default value

None.

Example

webhost2.ibm.com = cdsso.key

Parent topic: [cdsso-peers] stanza

[cdsso-token-attributes] stanza[cdsso-token-attributes] stanzaIBM Security Access Manager for Web WebSEAL [cdsso-token-attributes] stanzaUse the [cdsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single sign-on token.cdsso-token-attributes stanzastanzascdsso-token-attributesStanza reference<default>Use the <default> entry in the [cdsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in CDSSO authentication tokens.domain_nameUse the domain_name entry in the [cdsso-token-attributes] stanza to specify the credential attributes that WebSEAL includes in CDSSO authentication tokens.

[cdsso-token-attributes] stanza

Use the [cdsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single sign-on token.

<default>
Use the <default> entry in the [cdsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in CDSSO authentication tokens.

domain_name
Use the domain_name entry in the [cdsso-token-attributes] stanza to specify the credential attributes that WebSEAL includes in CDSSO authentication tokens.

Parent topic: Stanza reference

<default><default>IBM Security Access Manager for Web WebSEAL <default> stanza entryUse the <default> entry in the [cdsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in CDSSO authentication tokens.stanza entryentriescdsso-token-attributes stanzacdsso-token-attributes stanzaentrySyntax <default> = pattern1 [<default> = pattern2 ] ... [<default> = patternN] Description Credential attributes to include in CDSSO authentication tokens. When WebSEAL cannot find a domain_name entry to match the domain, the entries in <default> are used. The word <default> is a key word and must not be modified. Options patternThe value for each <default> entry can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?). Usage This stanza entry is optional. Default value None. Example <default> = my_cdas_attr_* [cdsso-token-attributes] stanzaUse the [cdsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single sign-on token.

<default>

Use the <default> entry in the [cdsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in CDSSO authentication tokens.

Syntax

<default> = pattern1
[<default> = pattern2 ]
...
[<default> = patternN]

Description

Credential attributes to include in CDSSO authentication tokens.

When WebSEAL cannot find a domain_name entry to match the domain, the entries in <default> are used. The word <default> is a key word and must not be modified.

Options

pattern

The value for each <default> entry can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?).

Usage

This stanza entry is optional.

Default value

None.

Example

<default> = my_cdas_attr_*

Parent topic: [cdsso-token-attributes] stanza

domain_namedomain_nameIBM Security Access Manager for Web WebSEAL domain_name stanza entryUse the domain_name entry in the [cdsso-token-attributes] stanza to specify the credential attributes that WebSEAL includes in CDSSO authentication tokens.domain_name stanza entrycdsso-token-attributes stanzaentriesdomain_namecdsso-token-attributes stanzacdsso-token-attributes stanzadomain_name entrySyntax domain_name = pattern1 [domain_name = pattern2] ... [domain_name = patternN] Description Credential attributes to include in CDSSO authentication tokens. Options domain_nameThe domain_name specifies the destination domain containing the server that will consume the token. patternThe value for each domain_name entry can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?). Usage This stanza entry is optional. Default value None. Example example1.com = my_cdas_attr_* example1.com = some_exact_attribute [cdsso-token-attributes] stanzaUse the [cdsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single sign-on token.

domain_name

Use the domain_name entry in the [cdsso-token-attributes] stanza to specify the credential attributes that WebSEAL includes in CDSSO authentication tokens.

Syntax

domain_name = pattern1
[domain_name = pattern2]
...
[domain_name = patternN]

Description

Credential attributes to include in CDSSO authentication tokens.

Options

domain_name

The domain_name specifies the destination domain containing the server that will consume the token.

pattern

The value for each domain_name entry can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?).

Usage

This stanza entry is optional.

Default value

None.

Example

example1.com = my_cdas_attr_*
example1.com = some_exact_attribute

Parent topic: [cdsso-token-attributes] stanza

[certificate] stanza[certificate] stanzaIBM Security Access Manager for Web WebSEAL [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.certificate stanzastanzascertificateStanza referenceaccept-client-certsUse the accept-client-certs stanza entry to control how WebSEAL handles client certificates from HTTPS clients.cert-cache-max-entriesUse the cert-cache-max-entries stanza entry to specify the maximum number of concurrent entries in the Certificate SSL ID cache.cert-cache-timeoutUse the cert-cache-timeout stanza entry to specify the maximum lifetime, in seconds, for an entry in the Certificate SSL ID cache.cert-prompt-max-triesUse the cert-prompt-max-tries stanza entry to specify how many times WebSEAL attempts to negotiate the SSL certificate before it assumes that the client cannot provide a certificate.disable-cert-login-pageUse the disable-cert-login-page stanza entry to control whether WebSEAL bypasses the initial login page and directly prompts for the certificate.eai-dataUse the eai-data stanza entry to specify which client certificate data elements are passed to the external authentication interface (EAI) application by WebSEAL.eai-uriUse the eai-uri stanza entry to specify the URI of the external authentication interface (EAI) application that WebSEAL can use for certificate authentication. Configure this entry if you do not want to use the standard CDAS authentication mechanism.omit-root-certBy default the complete certificate chain is sent as part of an SSL/TLS Certificate Message. An optional mode is allowed by the TLS RFC in which the root certificate (anchor) is omitted from the Certificate Message. Setting this option to true causes the root cert to be omitted from the message.

[certificate] stanza

Use the [certificate] stanza to configure certificate authentication.

accept-client-certs
Use the accept-client-certs stanza entry to control how WebSEAL handles client certificates from HTTPS clients.

cert-cache-max-entries
Use the cert-cache-max-entries stanza entry to specify the maximum number of concurrent entries in the Certificate SSL ID cache.

cert-cache-timeout
Use the cert-cache-timeout stanza entry to specify the maximum lifetime, in seconds, for an entry in the Certificate SSL ID cache.

cert-prompt-max-tries
Use the cert-prompt-max-tries stanza entry to specify how many times WebSEAL attempts to negotiate the SSL certificate before it assumes that the client cannot provide a certificate.

disable-cert-login-page
Use the disable-cert-login-page stanza entry to control whether WebSEAL bypasses the initial login page and directly prompts for the certificate.

eai-data
Use the eai-data stanza entry to specify which client certificate data elements are passed to the external authentication interface (EAI) application by WebSEAL.

eai-uri
Use the eai-uri stanza entry to specify the URI of the external authentication interface (EAI) application that WebSEAL can use for certificate authentication. Configure this entry if you do not want to use the standard CDAS authentication mechanism.

omit-root-cert
By default the complete certificate chain is sent as part of an SSL/TLS Certificate Message. An optional mode is allowed by the TLS RFC in which the root certificate (anchor) is omitted from the Certificate Message. Setting this option to true causes the root cert to be omitted from the message.

Parent topic: Stanza reference

accept-client-certsaccept-client-certsaccept-client-certs stanza entryUse the accept-client-certs stanza entry to control how WebSEAL handles client certificates from HTTPS clients.accept-client-certs stanza entrycertificate stanzaentriesaccept-client-certscertificate stanzacertificate stanzaaccept-client-certs entrySyntax accept-client-certs = {never|critical|required|optional|prompt_as_needed} DescriptionSpecifies how to handle certificates from HTTPS clients. Options neverNever request a client certificate.critical Always request a client certificate. If a valid certificate is not presented, the SSL handshake fails.requiredAlways request a client certificate. If a valid certificate is not presented, the SSL handshake succeeds but an error HTTP response is sent back to the client.optional Always request a client certificate. If a valid certificate is presented, use it.prompt_as_needed Only prompt for and process certificates when certificate authentication is necessary. An example of such situation is an ACL or POP check failure. When this value is set, ensure that the ssl-id-sessions stanza entry in the [session] stanza is set to no. UsageThis stanza entry is required. Default value never Exampleaccept-client-certs = never [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

accept-client-certs

Use the accept-client-certs stanza entry to control how WebSEAL handles client certificates from HTTPS clients.

Syntax

accept-client-certs = {never|critical|required|optional|prompt_as_needed}

Description

Specifies how to handle certificates from HTTPS clients.

Options

never

Never request a client certificate.

critical

Always request a client certificate. If a valid certificate is not presented, the SSL handshake fails.

required

Always request a client certificate. If a valid certificate is not presented, the SSL handshake succeeds but an error HTTP response is sent back to the client.

optional

Always request a client certificate. If a valid certificate is presented, use it.

prompt_as_needed

Only prompt for and process certificates when certificate authentication is necessary. An example of such situation is an ACL or POP check failure.

Note: When this value is set, ensure that the ssl-id-sessions stanza entry in the [session] stanza is set to no.

Usage

This stanza entry is required.

Default value

never

Example

accept-client-certs = never

Parent topic: [certificate] stanza

cert-cache-max-entriescert-cache-max-entriesIBM Security Access Manager for Web WebSEAL cert-cache-max-entries stanza entryUse the cert-cache-max-entries stanza entry to specify the maximum number of concurrent entries in the Certificate SSL ID cache.cert-cache-max-entries stanza entrycertificate stanzaentriescert-cache-max-entriescertificate stanzacertificate stanzacert-cache-max-entries entrySyntax cert-cache-max-entries = number_of_entries Description Maximum number of concurrent entries in the Certificate SSL ID cache. Options number_of_entriesThere is no absolute maximum size for the cache. However, the size of the cache cannot exceed the size of the SSL ID cache. A maximum size of 0 allows an unlimited cache size. Usage This stanza entry is required only when the accept-client-certs key is set to prompt_as_needed. Default value 1024 Example cert-cache-max-entries = 1024 [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

cert-cache-max-entries

Use the cert-cache-max-entries stanza entry to specify the maximum number of concurrent entries in the Certificate SSL ID cache.

Syntax

cert-cache-max-entries = number_of_entries

Description

Maximum number of concurrent entries in the Certificate SSL ID cache.

Options

number_of_entries

There is no absolute maximum size for the cache. However, the size of the cache cannot exceed the size of the SSL ID cache. A maximum size of 0 allows an unlimited cache size.

Usage

This stanza entry is required only when the accept-client-certs key is set to prompt_as_needed.

Default value

1024

Example

cert-cache-max-entries = 1024

Parent topic: [certificate] stanza

cert-cache-timeoutcert-cache-timeoutIBM Security Access Manager for Web WebSEAL cert-cache-timeout stanza entryUse the cert-cache-timeout stanza entry to specify the maximum lifetime, in seconds, for an entry in the Certificate SSL ID cache.cert-cache-timeout stanza entrycertificate stanzaentriescert-cache-timeoutcertificate stanzacertificate stanzacert-cache-timeout entrySyntax cert-cache-timeout = number_of_seconds Description Maximum lifetime, in seconds, for an entry in the Certificate SSL ID cache. Options number_of_secondsThe minimum value is zero (0). A value of zero mean that when the cache is full, the entries are cleared based on a Least Recently Used algorithm. Usage This stanza entry is required only when the accept-client-certs key is set to prompt_as_needed. Default value 120 Example cert-cache-timeout = 120 [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

cert-cache-timeout

Use the cert-cache-timeout stanza entry to specify the maximum lifetime, in seconds, for an entry in the Certificate SSL ID cache.

Syntax

cert-cache-timeout = number_of_seconds

Description

Maximum lifetime, in seconds, for an entry in the Certificate SSL ID cache.

Options

number_of_seconds

The minimum value is zero (0). A value of zero mean that when the cache is full, the entries are cleared based on a Least Recently Used algorithm.

Usage

This stanza entry is required only when the accept-client-certs key is set to prompt_as_needed.

Default value

120

Example

cert-cache-timeout = 120

Parent topic: [certificate] stanza

cert-prompt-max-triescert-prompt-max-triesIBM Security Access Manager for Web WebSEAL cert-prompt-max-tries stanza entryUse the cert-prompt-max-tries stanza entry to specify how many times WebSEAL attempts to negotiate the SSL certificate before it assumes that the client cannot provide a certificate.cert-prompt-max-tries stanza entrycertificate stanzaentriescert-prompt-max-triescertificate stanzacertificate stanzacert-prompt-max-tries entrySyntax cert-prompt-max-tries = number_of_tries Description During certificate authentication, WebSEAL prompts the browser to present the client's certificate. The SSL certificate negotiation process requires that the browser open and use a new (not existing) TCP connection. Browsers typically maintain several open TCP connections to a given server. When WebSEAL tries to prompt the browser for a certificate, the browser often tries to reuse an existing TCP connection instead of opening a new TCP connection. Therefore, the prompting process must be retried. WebSEAL might need to prompt for a certificate several times before the browser opens a new TCP connection and allows the prompting process to succeed. This configuration option controls how many times WebSEAL attempts to begin the SSL certificate negotiation process with the browser before assuming the client cannot provide a certificate. Options number_of_tries Set the value to 5 because most browsers maintain a maximum of four TCP connections to a Web server. As each attempt by the browser to process the certificate prompts on an existing TCP connection fails, that TCP connection is closed. On the fifth attempt, with all TCP connections closed, the browser's only option is to open a new TCP connection. If the value is set to less to 5, intermittent failures of certificate authentication might occur because the browser reuses existing TCP connections instead of opening a new TCP connection. These failures are more likely to occur in environments where login or other pages contain images that browsers access immediately before triggering the certificate prompts. Values less than 2 or greater than 15 are not permitted. This value is not used unless accept-client-certs =prompt_as_needed. Usage This stanza entry is required. Default value 5 Example cert-prompt-max-tries = 5 [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

cert-prompt-max-tries

Use the cert-prompt-max-tries stanza entry to specify how many times WebSEAL attempts to negotiate the SSL certificate before it assumes that the client cannot provide a certificate.

Syntax

cert-prompt-max-tries = number_of_tries

Description

During certificate authentication, WebSEAL prompts the browser to present the client's certificate. The SSL certificate negotiation process requires that the browser open and use a new (not existing) TCP connection.

Browsers typically maintain several open TCP connections to a given server. When WebSEAL tries to prompt the browser for a certificate, the browser often tries to reuse an existing TCP connection instead of opening a new TCP connection. Therefore, the prompting process must be retried. WebSEAL might need to prompt for a certificate several times before the browser opens a new TCP connection and allows the prompting process to succeed.

This configuration option controls how many times WebSEAL attempts to begin the SSL certificate negotiation process with the browser before assuming the client cannot provide a certificate.

Options

number_of_tries

Set the value to 5 because most browsers maintain a maximum of four TCP connections to a Web server. As each attempt by the browser to process the certificate prompts on an existing TCP connection fails, that TCP connection is closed. On the fifth attempt, with all TCP connections closed, the browser's only option is to open a new TCP connection.

If the value is set to less to 5, intermittent failures of certificate authentication might occur because the browser reuses existing TCP connections instead of opening a new TCP connection. These failures are more likely to occur in environments where login or other pages contain images that browsers access immediately before triggering the certificate prompts.

Values less than 2 or greater than 15 are not permitted.

This value is not used unless accept-client-certs =prompt_as_needed.

Usage

This stanza entry is required.

Default value

5

Example

cert-prompt-max-tries = 5

Parent topic: [certificate] stanza

disable-cert-login-pagedisable-cert-login-pageIBM Security Access Manager for Web WebSEAL disable-cert-login-page stanza entryUse the disable-cert-login-page stanza entry to control whether WebSEAL bypasses the initial login page and directly prompts for the certificate.disable-cert-login-page stanza entrycertificate stanzaentriesdisable-cert-login-pagecertificate stanzacertificate stanzadisable-cert-login-page entrySyntax disable-cert-login-page = {yes|no} Description Determines whether the initial login page with an option to prompt for certificate is presented or if WebSEAL will bypass the page and directly prompt for the certificate. Options yesThe initial login page with an option to prompt for certificate is not presented; instead, WebSEAL bypasses this page and directly prompts for the certificate. noThe initial login page with an option to prompt for certificate is presented. Usage This stanza entry is required. Default value no Example disable-cert-login-page = no [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

disable-cert-login-page

Use the disable-cert-login-page stanza entry to control whether WebSEAL bypasses the initial login page and directly prompts for the certificate.

Syntax

disable-cert-login-page = {yes|no}

Description

Determines whether the initial login page with an option to prompt for certificate is presented or if WebSEAL will bypass the page and directly prompt for the certificate.

Options

yes

The initial login page with an option to prompt for certificate is not presented; instead, WebSEAL bypasses this page and directly prompts for the certificate.

no

The initial login page with an option to prompt for certificate is presented.

Usage

This stanza entry is required.

Default value

no

Example

disable-cert-login-page = no

Parent topic: [certificate] stanza

eai-dataeai-dataIBM Security Access Manager for Web WebSEAL eai-data stanza entryUse the eai-data stanza entry to specify which client certificate data elements are passed to the external authentication interface (EAI) application by WebSEAL.eai-datacertificate stanzaentrieseai-datacertificate stanzacertificate stanzaeai-dataSyntax eai-data = data:header_name Description The client certificate data elements that will be passed to the EAI application. Multiple pieces of client certificate data can be passed to the EAI application by including multiple eai-data configuration entries. Options header_nameUsed to indicate the name of the HTTP header which will contain the data.dataUsed to indicate the data that will be included in the header. It should be one of the following: Base64CertificateSerialNumberSubjectCNSubjectLocalitySubjectStateSubjectCountrySubjectOrganizationSubjectOrganizationalUnitSubjectDNSubjectPostalCodeSubjectEmailSubjectUniqueIDIssuerCNIssuerLocalityIssuerStateIssuerCountryIssuerOrganizationIssuerOrganizationUnitIssuerDNIssuerPostalCodeIssuerEmailIssuerUniqueIDVersionSignatureAlgorithmValidFromValidFromExValidToValidToExPublicKeyAlgorithmPublicKeyPublicKeySizeFingerprintAlgorithmFingerprint Usage This stanza entry is required for EAI based client certificate authentication. Default value no Example eai-data = SubjectCN:eai-cn eai-data = SubjectDN:eai-dn [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

eai-data

Use the eai-data stanza entry to specify which client certificate data elements are passed to the external authentication interface (EAI) application by WebSEAL.

Syntax

eai-data = data:header_name

Description

The client certificate data elements that will be passed to the EAI application. Multiple pieces of client certificate data can be passed to the EAI application by including multiple eai-data configuration entries.

Options

header_name

Used to indicate the name of the HTTP header which will contain the data.

data

Used to indicate the data that will be included in the header. It should be one of the following:

Base64Certificate

SerialNumber

SubjectCN

SubjectLocality

SubjectState

SubjectCountry

SubjectOrganization

SubjectOrganizationalUnit

SubjectDN

SubjectPostalCode

SubjectEmail

SubjectUniqueID

IssuerCN

IssuerLocality

IssuerState

IssuerCountry

IssuerOrganization

IssuerOrganizationUnit

IssuerDN

IssuerPostalCode

IssuerEmail

IssuerUniqueID

Version

SignatureAlgorithm

ValidFrom

ValidFromEx

ValidTo

ValidToEx

PublicKeyAlgorithm

PublicKey

PublicKeySize

FingerprintAlgorithm

Fingerprint

Usage

This stanza entry is required for EAI based client certificate authentication.

Default value

no

Example

eai-data = SubjectCN:eai-cn
eai-data = SubjectDN:eai-dn

Parent topic: [certificate] stanza

eai-urieai-uriIBM Security Access Manager for Web WebSEAL eai-uri stanza entryUse the eai-uri stanza entry to specify the URI of the external authentication interface (EAI) application that WebSEAL can use for certificate authentication. Configure this entry if you do not want to use the standard CDAS authentication mechanism.eai-uri stanza entrycertificate stanzaentrieseai-uricertificate stanzacertificate stanzaeai-uri entrySyntax eai-uri = uri Description The resource identifier of the application which will be invoked to perform the certificate authentication. This URI should be relative to the root web space of the WebSEAL server. If this configuration entry is not defined, the standard CDAS authentication mechanism will be used to handle the authentication. Options uriThe resource identifier of the application which will be invoked to perform the certificate authentication. This URI should be relative to the root web space of the WebSEAL server. Usage This stanza entry is required for EAI based client certificate authentication. Default value no Example eai-uri = /jct/cgi-bin/eaitest/eaitest.pl [certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

eai-uri

Use the eai-uri stanza entry to specify the URI of the external authentication interface (EAI) application that WebSEAL can use for certificate authentication. Configure this entry if you do not want to use the standard CDAS authentication mechanism.

Syntax

eai-uri = uri

Description

The resource identifier of the application which will be invoked to perform the certificate authentication. This URI should be relative to the root web space of the WebSEAL server. If this configuration entry is not defined, the standard CDAS authentication mechanism will be used to handle the authentication.

Options

uri

The resource identifier of the application which will be invoked to perform the certificate authentication. This URI should be relative to the root web space of the WebSEAL server.

Usage

This stanza entry is required for EAI based client certificate authentication.

Default value

no

Example

eai-uri = /jct/cgi-bin/eaitest/eaitest.pl

Parent topic: [certificate] stanza

omit-root-certBy default the complete certificate chain is sent as part of an SSL/TLS Certificate Message. An optional mode is allowed by the TLS RFC in which the root certificate (anchor) is omitted from the Certificate Message. Setting this option to true causes the root cert to be omitted from the message.Syntax omit-root-cert = {true|false}Description This configuration entry is a global option and affects all web connections to the server. Options trueOmit the root certificate from the message.falseDo not omit the root certificate from the message.Usage This stanza entry is optional.Default value falseExample omit-root-cert = false[certificate] stanzaUse the [certificate] stanza to configure certificate authentication.

omit-root-cert

By default the complete certificate chain is sent as part of an SSL/TLS Certificate Message. An optional mode is allowed by the TLS RFC in which the root certificate (anchor) is omitted from the Certificate Message. Setting this option to true causes the root cert to be omitted from the message.

Syntax

omit-root-cert = {true|false}

Description

This configuration entry is a global option and affects all web connections to the server.

Options

true

Omit the root certificate from the message.

false

Do not omit the root certificate from the message.

Usage

This stanza entry is optional.

Default value

false

Example

omit-root-cert = false

Parent topic: [certificate] stanza

[cert-map-authn] stanza[cert-map-authn] stanzaIBM Security Access Manager for Web WebSEAL [cert-map-authn] stanzaUse the [cert-map-authn] stanza to configure the Cross Domain Authentication Service (CDAS).cert-map-authn stanzastanzascert-map-authnStanza referencedebug-levelUse the debug-level stanza entry to control the trace level for the authentication module.rules-file

[cert-map-authn] stanza

Use the [cert-map-authn] stanza to configure the Cross Domain Authentication Service (CDAS).

debug-level
Use the debug-level stanza entry to control the trace level for the authentication module.

rules-file

Parent topic: Stanza reference

debug-leveldebug-levelIBM Security Access Manager for Web WebSEAL debug-level stanza entryUse the debug-level stanza entry to control the trace level for the authentication module.debug-level stanza entrycert-map-authn stanzaentriesdebug-levelcert-map-authn stanzacert-map-authn stanzadebug-level entrySyntax debug-level = level Description Controls the trace level for the authentication module. Options levelSpecifies the initial trace level, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing.You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.certmap. This trace component is only available after the first HTTP request is processed. Usage This stanza entry is optional. Default value 0 A debug level of 0 results in no tracing output. Example debug-level = 5 [cert-map-authn] stanzaUse the [cert-map-authn] stanza to configure the Cross Domain Authentication Service (CDAS).

debug-level

Use the debug-level stanza entry to control the trace level for the authentication module.

Syntax

debug-level = level

Description

Controls the trace level for the authentication module.

Options

level

Specifies the initial trace level, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing.

Note: You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.certmap. This trace component is only available after the first HTTP request is processed.

Usage

This stanza entry is optional.

Default value

0

Note: A debug level of 0 results in no tracing output.

Example

debug-level = 5

Parent topic: [cert-map-authn] stanza

rules-filerules-filerules-file stanza entrycert-map-authn stanzaentriesrules-filecert-map-authn stanzacert-map-authn stanzarules-file entrySyntax rules-file = file-name Description The name of the rules file that the CDAS can use for certificate mapping. Options file-nameThe name of the rules file for the certificate mapping CDAS. Usage This stanza entry is required. Default value None. Example rules-file = cert-rules.txt [cert-map-authn] stanzaUse the [cert-map-authn] stanza to configure the Cross Domain Authentication Service (CDAS).

rules-file

Syntax

rules-file = file-name

Description

The name of the rules file that the CDAS can use for certificate mapping.

Options

file-name

The name of the rules file for the certificate mapping CDAS.

Usage

This stanza entry is required.

Default value

None.

Example

rules-file = cert-rules.txt

Parent topic: [cert-map-authn] stanza

[cfg-db-cmd:entries] stanza[cfg-db-cmd:entries] stanzaUse the [cfg-db-cmd:entries] stanza to define configuration entry settings when you use the server sync commands.cfg-db-cmd:entries stanzastanzascfg-db-cmd:entriesexclude stanza entrycfg-db-cmd:entries stanzaStanza referencestanza::entryUse the stanza::entry stanza entry to specify the configuration entries that are imported or exported from the configuration database.

[cfg-db-cmd:entries] stanza

Use the [cfg-db-cmd:entries] stanza to define configuration entry settings when you use the server sync commands.

stanza::entry
Use the stanza::entry stanza entry to specify the configuration entries that are imported or exported from the configuration database.

Parent topic: Stanza reference

stanza::entrystanza::entryUse the stanza::entry stanza entry to specify the configuration entries that are imported or exported from the configuration database. stanza entrySyntax stanza::entry = {include|exclude} Description Each configuration entry is checked sequentially against each item in the [cfg-db-cmd:entries] stanza until a match is found. This first match then controls whether the configuration entry is included in, or excluded from, the configuration database. If no match is found, the configuration entry is excluded from the configuration database. Syntax entryThis field defines the stanza entry to be included or excluded. It may contain any pattern matching characters.stanzaThis field defines the stanza containing the data entry to be included or excluded. It may contain any pattern matching characters. Options includeInclude the specified configuration entries when importing or exporting data from the configuration database.excludeExclude the specified configuration entries when importing or exporting data from the configuration database. Usage This stanza entry is not required. Default value WebSEAL uses the values configured in the WebSEAL configuration file. See the WebSEAL configuration file template for the default entries. Example server::worker-threads = include ldap::* = exclude *::* = include [cfg-db-cmd:entries] stanzaUse the [cfg-db-cmd:entries] stanza to define configuration entry settings when you use the server sync commands.

stanza::entry

Use the stanza::entry stanza entry to specify the configuration entries that are imported or exported from the configuration database.

Syntax

stanza::entry = {include|exclude}

Description

Each configuration entry is checked sequentially against each item in the [cfg-db-cmd:entries] stanza until a match is found. This first match then controls whether the configuration entry is included in, or excluded from, the configuration database. If no match is found, the configuration entry is excluded from the configuration database.

Syntax

entry

This field defines the stanza entry to be included or excluded. It may contain any pattern matching characters.

stanza

This field defines the stanza containing the data entry to be included or excluded. It may contain any pattern matching characters.

Options

include

Include the specified configuration entries when importing or exporting data from the configuration database.

exclude

Exclude the specified configuration entries when importing or exporting data from the configuration database.

Usage

This stanza entry is not required.

Default value

WebSEAL uses the values configured in the WebSEAL configuration file. See the WebSEAL configuration file template for the default entries.

Example

server::worker-threads = include
ldap::* = exclude
 *::* = include

Parent topic: [cfg-db-cmd:entries] stanza

[cfg-db-cmd:files] stanza[cfg-db-cmd:files] stanzaUse the [cfg-db-cmd:files] stanza entry to define settings for files that are included in the configuration database.cfg-db-cmd:files stanzastanzascfg-db-cmd:filesStanza referencefilesUse the files stanza entry to specify the files that WebSEAL includes in the configuration database. These files are replicated across WebSEAL servers in a cluster. Replication occurs when the pdadmin server task cluster restart command runs.

[cfg-db-cmd:files] stanza

Use the [cfg-db-cmd:files] stanza entry to define settings for files that are included in the configuration database.

files
Use the files stanza entry to specify the files that WebSEAL includes in the configuration database. These files are replicated across WebSEAL servers in a cluster. Replication occurs when the pdadmin server task cluster restart command runs.

Parent topic: Stanza reference

filesfilesIBM Security Access Manager for Web WebSEAL files stanza entryUse the files stanza entry to specify the files that WebSEAL includes in the configuration database. These files are replicated across WebSEAL servers in a cluster. Replication occurs when the pdadmin server task cluster restart command runs.include stanza entrycfg-db-cmd:files stanzafilesincludecfg-db-cmd:files stanzacfg-db-cmd:files stanzainclude entrySyntax Either: files = cfg(stanza::entry) Or: files = file_name Description Defines the files that will be included (that is, imported or exported ) in the configuration database. Options stanzaThis field specifies the name of the stanza that contains the entry with the name of the file to be included in the configuration database. The configuration value defined by stanza and entry must contain the name of the file.entryThis field specifies the stanza entry that contains the name of the file to be included in the configuration database. The configuration value defined by stanza and entry must contain the name of the file.file_nameThe name of the file. Usage This stanza entry is not required. Default value files = cfg(ssl::webseal-cert-keyfile) files = cfg(ssl::webseal-cert-keyfile-stash) files = cfg(junction::jmt-map) files = cfg(server::dynurl-map) Example files = cert-rules.txt files = jmt.conf files = cfg(junction::jmt-map) [cfg-db-cmd:files] stanzaUse the [cfg-db-cmd:files] stanza entry to define settings for files that are included in the configuration database.

files

Use the files stanza entry to specify the files that WebSEAL includes in the configuration database. These files are replicated across WebSEAL servers in a cluster. Replication occurs when the pdadmin server task cluster restart command runs.

Syntax

Either:

files = cfg(stanza::entry)

Or:

files = file_name

Description

Defines the files that will be included (that is, imported or exported ) in the configuration database.

Options

stanza

This field specifies the name of the stanza that contains the entry with the name of the file to be included in the configuration database. The configuration value defined by stanza and entry must contain the name of the file.

entry

This field specifies the stanza entry that contains the name of the file to be included in the configuration database. The configuration value defined by stanza and entry must contain the name of the file.

file_name

The name of the file.

Usage

This stanza entry is not required.

Default value

files = cfg(ssl::webseal-cert-keyfile)
files = cfg(ssl::webseal-cert-keyfile-stash)
files = cfg(junction::jmt-map)
files = cfg(server::dynurl-map)

Example

files = cert-rules.txt
files = jmt.conf
files = cfg(junction::jmt-map)

Parent topic: [cfg-db-cmd:files] stanza

[cluster] stanza[cluster] stanzaIBM Security Access Manager for Web WebSEAL [cluster] stanzaUse the [cluster] stanza to configure a clustered WebSEAL server environment.cluster stanzastanzasclusterIt is vital that this configuration stanza is not included in the configuration database. The cluster::* = exclude configuration entry in the [cfg-db-cmd:entries] stanza ensures this exclusion.In addition to the configuration entries listed here, a config-version entry is added at run time in a clustered environment. This configuration entry contains version information about the current configuration. Do NOT manually edit this version information.All cluster members must be the same server type. You can cluster either:WebSEAL servers that are running on appliances.WebSEAL servers that are running on standard operating systems.Stanza referenceis-masterUse the is-master stanza entry to set the master server for the WebSEAL cluster.master-nameUse the master-name stanza entry to define the authorization server name of the master for the WebSEAL cluster.max-wait-timeUse the max-wait-time stanza entry to specify the maximum amount of time, in seconds, that the master server waits for a slave server to restart.

[cluster] stanza

Use the [cluster] stanza to configure a clustered WebSEAL server environment.

Notes:

It is vital that this configuration stanza is not included in the configuration database. The cluster::* = exclude configuration entry in the [cfg-db-cmd:entries] stanza ensures this exclusion.

In addition to the configuration entries listed here, a config-version entry is added at run time in a clustered environment. This configuration entry contains version information about the current configuration. Do NOT manually edit this version information.

All cluster members must be the same server type. You can cluster either:

WebSEAL servers that are running on appliances.

WebSEAL servers that are running on standard operating systems.

is-master
Use the is-master stanza entry to set the master server for the WebSEAL cluster.

master-name
Use the master-name stanza entry to define the authorization server name of the master for the WebSEAL cluster.

max-wait-time
Use the max-wait-time stanza entry to specify the maximum amount of time, in seconds, that the master server waits for a slave server to restart.

Parent topic: Stanza reference

is-masteris-masterIBM Security Access Manager for Web WebSEAL is-master stanza entryUse the is-master stanza entry to set the master server for the WebSEAL cluster.is-master stanza entrycluster stanzaentriesis-mastercluster stanzacluster stanzais-master entrySyntax is-master = {yes|no} Description Is this server the master for the WebSEAL cluster? You need to have a single master for each cluster. Any modifications to the configuration of a cluster must be made on the master. Options yes This server is the master for the WebSEAL cluster.noThis server is not the master for the WebSEAL cluster. The name of the master server must be specified in the master-name configuration entry that is also in the [cluster] stanza. Usage This stanza entry is required in a clustered environment. This stanza entry is not required for a single server environment. Default value There is no default value. Example is-master = no [cluster] stanzaUse the [cluster] stanza to configure a clustered WebSEAL server environment.

is-master

Use the is-master stanza entry to set the master server for the WebSEAL cluster.

Syntax

is-master = {yes|no}

Description

Is this server the master for the WebSEAL cluster? You need to have a single master for each cluster. Any modifications to the configuration of a cluster must be made on the master.

Options

yes

This server is the master for the WebSEAL cluster.

no

This server is not the master for the WebSEAL cluster. The name of the master server must be specified in the master-name configuration entry that is also in the [cluster] stanza.

Usage

This stanza entry is required in a clustered environment. This stanza entry is not required for a single server environment.

Default value

There is no default value.

Example

is-master = no

Parent topic: [cluster] stanza

master-nameIBM Security Access Manager for Web WebSEAL master-name stanza entryUse the master-name stanza entry to define the authorization server name of the master for the WebSEAL cluster.master-name stanza entrycluster stanzaentriesmaster-namecluster stanzacluster stanzamaster-name entrySyntax master-name = azn-name Description Defines the authorization server name of the master for the WebSEAL cluster. Options azn-name The authorization server name of the master. Usage This stanza entry is required if the value for is-master (also in the [cluster] stanza) is set to no. If the is-master entry is set to yes, WebSEAL ignores this master-name entry. Default value There is no default value. Example master-name = default-webseald-master.ibm.com [cluster] stanzaUse the [cluster] stanza to configure a clustered WebSEAL server environment.

master-name

Use the master-name stanza entry to define the authorization server name of the master for the WebSEAL cluster.

Syntax

master-name = azn-name

Description

Defines the authorization server name of the master for the WebSEAL cluster.

Options

azn-name

The authorization server name of the master.

Usage

This stanza entry is required if the value for is-master (also in the [cluster] stanza) is set to no. If the is-master entry is set to yes, WebSEAL ignores this master-name entry.

Default value

There is no default value.

Example

master-name = default-webseald-master.ibm.com

Parent topic: [cluster] stanza

max-wait-timemax-wait-timeIBM Security Access Manager for Web WebSEAL max-wait-time stanza entryUse the max-wait-time stanza entry to specify the maximum amount of time, in seconds, that the master server waits for a slave server to restart.max-wait-time stanza entrycluster stanzaentriesmax-wait-timecluster stanzacluster stanzamax-wait-time entrySyntax max-wait-time = number Description Specifies the maximum amount of time to wait, in seconds, for a slave server to be restarted. This configuration entry is only applicable to the master server. Options number The maximum number of seconds to wait for a slave server to be restarted. Usage This configuration entry is required if is-master (also in the [cluster] stanza) is set to yes. Default value 60 Example max-wait-time = 60 [cluster] stanzaUse the [cluster] stanza to configure a clustered WebSEAL server environment.

max-wait-time

Use the max-wait-time stanza entry to specify the maximum amount of time, in seconds, that the master server waits for a slave server to restart.

Syntax

max-wait-time = number

Description

Specifies the maximum amount of time to wait, in seconds, for a slave server to be restarted. This configuration entry is only applicable to the master server.

Options

number

The maximum number of seconds to wait for a slave server to be restarted.

Usage

This configuration entry is required if is-master (also in the [cluster] stanza) is set to yes.

Default value

60

Example

max-wait-time = 60

Parent topic: [cluster] stanza

[compress-mime-types] stanza[compress-mime-types] stanzaIBM Security Access Manager for Web WebSEAL [compress-mime-types] stanzaUse the [compress-mime-types] stanza to control the HTTP data compression for specific MIME types.compress-mime-types stanzastanzascompress-mime-typesStanza referencemime_type

[compress-mime-types] stanza

Use the [compress-mime-types] stanza to control the HTTP data compression for specific MIME types.

mime_type

Parent topic: Stanza reference

mime_typemime_typemime_type stanza entrycompress-mime-types stanzaentriesmime_typecompress-mime-types stanzacompress-mime-types stanzamime_type entrySyntax mime_type = minimum_doc_size:[compression_level] Description Enables or disables HTTP compression based on the mime-type of the response and the size of the returned document. Options mime_typeThe mime_type can contain a wild card pattern such as an asterisk ( * ) for the subtype, or it can be "*/*" to match all mime-types.minimum_doc_sizeThe minimum_doc_size is an integer than can be positive, negative or zero. A size of -1 means do not compress this mime-type. A size of 0 means to compress the document regardless of its size. A size greater than 0 means to compress the document only when its initial size is greater than or equal to minimum_doc_size.compression_levelThe compression_level is an integer value between 1 and 9. The larger number results in a higher amount of compression. When compression-level is not specified, a default level of 1 is used. Usage This stanza entry is optional. Default value */* = -1 Example image/* = -1 text/html = 1000 [compress-mime-types] stanzaUse the [compress-mime-types] stanza to control the HTTP data compression for specific MIME types.

mime_type

Syntax

mime_type = minimum_doc_size:[compression_level]

Description

Enables or disables HTTP compression based on the mime-type of the response and the size of the returned document.

Options

mime_type

The mime_type can contain a wild card pattern such as an asterisk ( * ) for the subtype, or it can be "*/*" to match all mime-types.

minimum_doc_size

The minimum_doc_size is an integer than can be positive, negative or zero. A size of -1 means do not compress this mime-type. A size of 0 means to compress the document regardless of its size. A size greater than 0 means to compress the document only when its initial size is greater than or equal to minimum_doc_size.

compression_level

The compression_level is an integer value between 1 and 9. The larger number results in a higher amount of compression. When compression-level is not specified, a default level of 1 is used.

Usage

This stanza entry is optional.

Default value

*/* = -1

Example

image/* = -1
text/html = 1000

Parent topic: [compress-mime-types] stanza

[compress-user-agents] stanza[compress-user-agents] stanzaIBM Security Access Manager for Web WebSEAL [compress-user-agents] stanzaUse the [compress-user-agents] stanza to explicitly enable or disable compression for various browsers. You can configure WebSEAL to use the user-agent header that is sent by the client to determine whether to enable or disable HTTP compression.compress-user-agents stanzastanzascompress-user-agentsStanza referencepattern

[compress-user-agents] stanza

Use the [compress-user-agents] stanza to explicitly enable or disable compression for various browsers. You can configure WebSEAL to use the user-agent header that is sent by the client to determine whether to enable or disable HTTP compression.

pattern

Parent topic: Stanza reference

patternpatternpattern stanza entrycompress-user-agents stanzaentriespatterncompress-user-agents stanzacompress-user-agents stanzapattern entrySyntax pattern = {yes|no} Description Enables or disables HTTP compression based on the user-agent header sent by clients. This entry is used to disable compression for clients which send an "accept-encoding: gzip" HTTP header but do not actually handle gzip content-encodings properly. An example of a user agent is a browser, such as Microsoft Internet Explorer 6.0 Options yesEnables HTTP compression based on the user-agent header sent by clients. noDisables HTTP compression based on the user-agent header sent by clients. Usage This stanza entry is optional. Default value None. Example *MSIE 6.0* = yes [compress-user-agents] stanzaUse the [compress-user-agents] stanza to explicitly enable or disable compression for various browsers. You can configure WebSEAL to use the user-agent header that is sent by the client to determine whether to enable or disable HTTP compression.

pattern

Syntax

pattern = {yes|no}

Description

Enables or disables HTTP compression based on the user-agent header sent by clients. This entry is used to disable compression for clients which send an "accept-encoding: gzip" HTTP header but do not actually handle gzip content-encodings properly. An example of a user agent is a browser, such as Microsoft Internet Explorer 6.0

Options

yes

Enables HTTP compression based on the user-agent header sent by clients.

no

Disables HTTP compression based on the user-agent header sent by clients.

Usage

This stanza entry is optional.

Default value

None.

Example

*MSIE 6.0* = yes

Parent topic: [compress-user-agents] stanza

[content] stanza[content] stanzaIBM Security Access Manager for Web WebSEAL [content] stanzaUse the [content] stanza to specify the format of macro data strings that are inserted into HTML server response pages. The data is inserted into the WebSEAL HTML files in either UTF-8 format or local code page format.content stanzastanzascontentStanza referenceutf8-template-macros-enabled

[content] stanza

Use the [content] stanza to specify the format of macro data strings that are inserted into HTML server response pages. The data is inserted into the WebSEAL HTML files in either UTF-8 format or local code page format.

utf8-template-macros-enabled

Parent topic: Stanza reference

utf8-template-macros-enabledutf8-template-macros-enabledutf8-template-macros-enabled stanza entrycontent stanzaentriesutf8-template-macros-enabledcontent stanzacontent stanzautf8-template-macros-enabled entrySyntax utf8-template-macros-enabled = {yes|no} Description Specifies how standard WebSEAL HTML files, such as login.html, have data inserted into them when %MACRO% strings are encountered. This entry affects files in the management and errors directories. You can manage these directories from the Manage Reverse Proxy Management Root page of the LMI. WebSEAL HTML pages use a UTF-8 character set by default. If you modify the character set to specify the local code page, set this entry to no. Options yesWhen set to yes, data is inserted in UTF-8 format. noWhen set to no, data is inserted in the local code page format. Usage This stanza entry is required. Default value yes Example utf8-template-macros-enabled = yes [content] stanzaUse the [content] stanza to specify the format of macro data strings that are inserted into HTML server response pages. The data is inserted into the WebSEAL HTML files in either UTF-8 format or local code page format.

utf8-template-macros-enabled

Syntax

utf8-template-macros-enabled = {yes|no}

Description

Specifies how standard WebSEAL HTML files, such as login.html, have data inserted into them when %MACRO% strings are encountered.

This entry affects files in the management and errors directories. You can manage these directories from the Manage Reverse Proxy Management Root page of the LMI.

WebSEAL HTML pages use a UTF-8 character set by default. If you modify the character set to specify the local code page, set this entry to no.

Options

yes

When set to yes, data is inserted in UTF-8 format.

no

When set to no, data is inserted in the local code page format.

Usage

This stanza entry is required.

Default value

yes

Example

utf8-template-macros-enabled = yes

Parent topic: [content] stanza

[content-cache] stanza[content-cache] stanzaIBM Security Access Manager for Web WebSEAL [content-cache] stanzaUse the [content-cache] stanza to configure WebSEAL content caching.content-cache stanzastanzascontent-cacheStanza referenceMIME_type

[content-cache] stanza

Use the [content-cache] stanza to configure WebSEAL content caching.

MIME_type

Parent topic: Stanza reference

MIME_typeMIME_typeMIME_type stanza entrycontent-cache stanzaentriesMIME_typecontent-cache stanzacontent-cache stanzaMIME_type entrySyntax MIME_type = cache_type:cache_size:maximum_ageDescription List of entries that define the caches which WebSEAL uses to store documents in memory.Options MIME_typeAny valid MIME type conveyed in an HTTP Content-Type: response header. This value may contain an asterisk to denote a wildcard ( * ). A value of */* represents a default object cache that holds any object that does not correspond to an explicitly configured cache.cache_typeDefines the type of backing store to use for the cache. Only memory caches are supported.cache_sizeThe maximum size, in kilobytes, to which the cache grows before objects are removed according to a least-recently-used algorithm. The minimum allowable value is 1 kilobyte. WebSEAL reports an error and fails to start if the value is less than or equal to zero (0). WebSEAL does not impose a maximum allowable value.def-max-ageSpecifies the maximum age (in seconds) if expiry information is missing from the original response. If no value is provided, a default maximum age of 3600 (one hour) will be applied. The configured default maximum age is only used when the cached response is missing the cache control headers: Cache-Control, Expires, and Last-Modified. If only Last-Modified is present, the maximum age will be calculated as ten percent of the difference between the current time and the last-modified time.Usage This stanza entry is optional.Default value None.Example text/html = memory:2000:3600 # image/* = memory:5000:3600 # */* = memory:1000:3600[content-cache] stanzaUse the [content-cache] stanza to configure WebSEAL content caching.

MIME_type

Syntax

MIME_type = cache_type:cache_size:maximum_age

Description

List of entries that define the caches which WebSEAL uses to store documents in memory.

Options

MIME_type

Any valid MIME type conveyed in an HTTP Content-Type: response header. This value may contain an asterisk to denote a wildcard ( * ). A value of */* represents a default object cache that holds any object that does not correspond to an explicitly configured cache.

cache_type

Defines the type of backing store to use for the cache. Only memory caches are supported.

cache_size

The maximum size, in kilobytes, to which the cache grows before objects are removed according to a least-recently-used algorithm. The minimum allowable value is 1 kilobyte. WebSEAL reports an error and fails to start if the value is less than or equal to zero (0). WebSEAL does not impose a maximum allowable value.

def-max-age

Specifies the maximum age (in seconds) if expiry information is missing from the original response. If no value is provided, a default maximum age of 3600 (one hour) will be applied. The configured default maximum age is only used when the cached response is missing the cache control headers: Cache-Control, Expires, and Last-Modified.

Note: If only Last-Modified is present, the maximum age will be calculated as ten percent of the difference between the current time and the last-modified time.

Usage

This stanza entry is optional.

Default value

None.

Example

text/html = memory:2000:3600
# image/* = memory:5000:3600
# */* = memory:1000:3600

Parent topic: [content-cache] stanza

[content-encodings] stanza[content-encodings] stanzaIBM Security Access Manager for Web WebSEAL [content-encodings] stanzaUse the [content-encodings] stanza to map document extensions to encoding types. WebSEAL uses this mapping to determine the correct MIME type to report in its response content-type header for local junction files.content-encodings stanzastanzascontent-encodingsStanza referenceextensionUse the extension stanza entry to map document extensions to encoding types. WebSEAL uses this mapping to report the correct MIME type in its response content-type header for local junction files.

[content-encodings] stanza

Use the [content-encodings] stanza to map document extensions to encoding types. WebSEAL uses this mapping to determine the correct MIME type to report in its response content-type header for local junction files.

extension
Use the extension stanza entry to map document extensions to encoding types. WebSEAL uses this mapping to report the correct MIME type in its response content-type header for local junction files.

Parent topic: Stanza reference

extensionextensionIBM Security Access Manager for Web WebSEAL extension stanza entryUse the extension stanza entry to map document extensions to encoding types. WebSEAL uses this mapping to report the correct MIME type in its response content-type header for local junction files.extension stanza entrycontent-encodings stanzaentriesextensioncontent-encodings stanzacontent-encodings stanzaextension entrySyntax extension = encoding_type Description Entries in this stanza map a document extension to an encoding type. This mapping is used by WebSEAL to report the correct MIME type in its response content-type header for local junction files. This mapping is necessary so that WebSEAL can communicate to a browser that encoded (binary) data is being returned. The MIME types defined in this stanza must also be defined in [content-mime-types]. When WebSEAL encounters a document with two extensions, such as: .txt.Z, it produces two headers: content-type: text/plain content-encoding: x-compress Thus even though the data is compressed, the response to the browser says text/plain. However, the extra content-encoding header tells the browser that the data is compressed text/plain. In most cases, the administrator does not need to add additional entries. However, if the administrator introduces a new extension type that requires more than a text/plain response, the extension and encoding_type should be added to this stanza. Options encoding_typeEncoding type. Usage This stanza entry is required. Default value gz = x-gzip Z = x-compress Example gz = x-gzip Z = x-compress [content-encodings] stanzaUse the [content-encodings] stanza to map document extensions to encoding types. WebSEAL uses this mapping to determine the correct MIME type to report in its response content-type header for local junction files.

extension

Use the extension stanza entry to map document extensions to encoding types. WebSEAL uses this mapping to report the correct MIME type in its response content-type header for local junction files.

Syntax

extension = encoding_type

Description

Entries in this stanza map a document extension to an encoding type. This mapping is used by WebSEAL to report the correct MIME type in its response content-type header for local junction files. This mapping is necessary so that WebSEAL can communicate to a browser that encoded (binary) data is being returned.

The MIME types defined in this stanza must also be defined in [content-mime-types].

When WebSEAL encounters a document with two extensions, such as: .txt.Z, it produces two headers:

content-type: text/plain
content-encoding: x-compress

Thus even though the data is compressed, the response to the browser says text/plain. However, the extra content-encoding header tells the browser that the data is compressed text/plain.

In most cases, the administrator does not need to add additional entries. However, if the administrator introduces a new extension type that requires more than a text/plain response, the extension and encoding_type should be added to this stanza.

Options

encoding_type

Encoding type.

Usage

This stanza entry is required.

Default value

gz = x-gzip
Z = x-compress

Example

gz = x-gzip
Z = x-compress

Parent topic: [content-encodings] stanza

[content-mime-types] stanza[content-mime-types] stanzaIBM Security Access Manager for Web WebSEAL [content-mime-types] stanzaUse the [content-mime-types] stanza to define the MIME type for specific document extensions. content-mime-types stanzastanzascontent-mime-typesStanza referencedeftypeUse the deftype stanza entry to specify the default type that WebSEAL assigns to pages that do not match any of the extension = MIME_type entries in the content-mime-types stanza.extension

[content-mime-types] stanza

Use the [content-mime-types] stanza to define the MIME type for specific document extensions.

deftype
Use the deftype stanza entry to specify the default type that WebSEAL assigns to pages that do not match any of the extension = MIME_type entries in the content-mime-types stanza.

extension

Parent topic: Stanza reference

deftypedeftypeIBM Security Access Manager for Web WebSEAL deftype stanza entryUse the deftype stanza entry to specify the default type that WebSEAL assigns to pages that do not match any of the extension = MIME_type entries in the content-mime-types stanza.deftype stanza entrycontent-mime-types stanzaentriesdeftypecontent-mime-types stanzacontent-mime-types stanzadeftype entrySyntax deftype = MIME_type Description Default type to assign to pages that do not match any of the extension = MIME_type entries defined in this stanza. Options MIME_typeDefault type to assign to pages that don't match any of the extension = MIME_type entries defined in this stanza. Usage This stanza entry is required. Default value text/plain The administrator should not change this value. Example deftype = text/plain [content-mime-types] stanzaUse the [content-mime-types] stanza to define the MIME type for specific document extensions.

deftype

Use the deftype stanza entry to specify the default type that WebSEAL assigns to pages that do not match any of the extension = MIME_type entries in the content-mime-types stanza.

Syntax

deftype = MIME_type

Description

Default type to assign to pages that do not match any of the extension = MIME_type entries defined in this stanza.

Options

MIME_type

Default type to assign to pages that don't match any of the extension = MIME_type entries defined in this stanza.

Usage

This stanza entry is required.

Default value

text/plain

The administrator should not change this value.

Example

deftype = text/plain

Parent topic: [content-mime-types] stanza

extensionextensionextension stanza entrycontent-mime-types stanzaentriesextensioncontent-mime-types stanzacontent-mime-types stanzaextension entrySyntax extension = MIME_typeDescription This stanza defines the MIME type for specific document extensions. The stanza contains a list of extension = MIME_type pairs. Many common MIME types are defined by default. Administrators can add additional entries. Both extensions and MIME_types must be declared using the ASCII character set. The entry of invalid MIME types does not affect WebSEAL, but may cause difficulty for client browsers.Options extensionThe file name extension of documents of this MIME type.MIME_typeThe corresponding MIME type.Usage The entries in this stanza are required.Default value There following MIME types are defined by default: html = text/html htm = text/html gif = image/gif jpeg = image/jpeg ps = application/postscript shtml = text/x-server-parsed-html jpg = image/jpeg jpe = image/jpeg mpeg = video/mpeg mpe = video/mpeg mpg = video/mpeg bin = application/octet-stream exe = application/octet-stream Z = application/octet-stream EXE = application/octet-stream dll = application/octet-stream DLL = application/octet-stream ivsrv = application/octet-stream pdf = application/pdf au = audio/basic snd = audio/basic aiff = audio/x-aiff aifc = audio/x-aiff aif = audio/x-aiff wav = audio/x-wav ai = application/postscript eps = application/postscript rtf = application/rtf zip = application/zip ief = image/ief tiff = image/tiff tif = image/tiff ras = image/x-cmu-raster pnm = image/x-portable-anymap pbm = image/x-portable-bitmap pgm = image/x-portable-graymap ppm = image/x-portable-pixmap rgb = image/x-rgb xbm = image/x-xbitmap xpm = image/x-xpixmap xwd = image/x-xwindowdump txt = text/plain rtx = text/richtext tsv = text/tab-separated-values etx = text/x-setext qt = video/quicktime mov = video/quicktime avi = video/x-msvideo movie = video/x-sgi-movie js = application/x-javascript ls = application/x-javascript mocha = application/x-javascript wrl = x-world/x-vrml dir = application/x-director dxr = application/x-director dcr = application/x-director crt = application/x-x509-ca-cert tar = application/x-tarExample zip = application/zip[content-mime-types] stanzaUse the [content-mime-types] stanza to define the MIME type for specific document extensions.

extension

Syntax

extension = MIME_type

Description

This stanza defines the MIME type for specific document extensions. The stanza contains a list of extension = MIME_type pairs. Many common MIME types are defined by default. Administrators can add additional entries. Both extensions and MIME_types must be declared using the ASCII character set. The entry of invalid MIME types does not affect WebSEAL, but may cause difficulty for client browsers.

Options

extension

The file name extension of documents of this MIME type.

MIME_type

The corresponding MIME type.

Usage

The entries in this stanza are required.

Default value

There following MIME types are defined by default:

html = text/html
htm = text/html
gif = image/gif
jpeg = image/jpeg
ps = application/postscript
shtml = text/x-server-parsed-html
jpg = image/jpeg
jpe = image/jpeg
mpeg = video/mpeg
mpe = video/mpeg
mpg = video/mpeg
bin = application/octet-stream
exe = application/octet-stream
Z = application/octet-stream
EXE = application/octet-stream
dll = application/octet-stream
DLL = application/octet-stream
ivsrv = application/octet-stream
pdf = application/pdf
au = audio/basic
snd = audio/basic
aiff = audio/x-aiff
aifc = audio/x-aiff
aif = audio/x-aiff
wav = audio/x-wav
ai = application/postscript
eps = application/postscript
rtf = application/rtf
zip = application/zip

ief = image/ief
tiff = image/tiff
tif = image/tiff
ras = image/x-cmu-raster
pnm = image/x-portable-anymap
pbm = image/x-portable-bitmap
pgm = image/x-portable-graymap
ppm = image/x-portable-pixmap
rgb = image/x-rgb
xbm = image/x-xbitmap
xpm = image/x-xpixmap
xwd = image/x-xwindowdump
txt = text/plain
rtx = text/richtext
tsv = text/tab-separated-values
etx = text/x-setext
qt = video/quicktime
mov = video/quicktime
avi = video/x-msvideo
movie = video/x-sgi-movie
js = application/x-javascript
ls = application/x-javascript
mocha = application/x-javascript
wrl = x-world/x-vrml
dir = application/x-director
dxr = application/x-director
dcr = application/x-director
crt = application/x-x509-ca-cert
tar = application/x-tar

Example

zip = application/zip

Parent topic: [content-mime-types] stanza

[credential-policy-attributes] stanza[credential-policy-attributes] stanzaIBM Security Access Manager for Web WebSEAL [credential-policy-attributes] stanzaUse the [credential-policy-attributes] stanza to specify the Security Access Manager policy values that are stored in credentials during authentication.credential-policy-attributes stanzastanzascredential-policy-attributesStanza referencepolicy-name

[credential-policy-attributes] stanza

Use the [credential-policy-attributes] stanza to specify the Security Access Manager policy values that are stored in credentials during authentication.

policy-name

Parent topic: Stanza reference

policy-namepolicy-namepolicy-name stanza entrycredential-policy-attributes stanzaentriespolicy-namecredential-policy-attributes stanzacredential-policy-attributes stanzapolicy-name entrySyntax policy-name = credential-attribute-nameDescription Controls which Access Manager policy values are stored in credentials during authenticationOptions credential-attribute-nameCredential attribute name.Usage This stanza entry is optional.Default value None.Example AZN_POLICY_MAX_FAILED_LOGIN = tagvalue_max_failed_login[credential-policy-attributes] stanzaUse the [credential-policy-attributes] stanza to specify the Security Access Manager policy values that are stored in credentials during authentication.

policy-name

Syntax

policy-name = credential-attribute-name

Description

Controls which Access Manager policy values are stored in credentials during authentication

Options

credential-attribute-name

Credential attribute name.

Usage

This stanza entry is optional.

Default value

None.

Example

AZN_POLICY_MAX_FAILED_LOGIN = tagvalue_max_failed_login

Parent topic: [credential-policy-attributes] stanza

[credential-refresh-attributes] stanza[credential-refresh-attributes] stanzaIBM Security Access Manager for Web WebSEAL [credential-refresh-attributes] stanzaUse the [credential-refresh-attributes] stanza to configure the credential refresh behavior in WebSEAL.credential-refresh-attributes stanzastanzascredential-refresh-attributesStanza referenceattribute_name_patternUse the attribute_name_pattern stanza entry to specify whether attributes are preserved or refreshed during a credential refresh.authentication_levelUse the authentication_level stanza entry to control whether the authentication level is preserved or refreshed during a credential refresh.

[credential-refresh-attributes] stanza

Use the [credential-refresh-attributes] stanza to configure the credential refresh behavior in WebSEAL.

attribute_name_pattern
Use the attribute_name_pattern stanza entry to specify whether attributes are preserved or refreshed during a credential refresh.

authentication_level
Use the authentication_level stanza entry to control whether the authentication level is preserved or refreshed during a credential refresh.

Parent topic: Stanza reference

attribute_name_patternattribute_name_patternIBM Security Access Manager for Web WebSEAL attribute_name_pattern stanza entryUse the attribute_name_pattern stanza entry to specify whether attributes are preserved or refreshed during a credential refresh.attribute_name_pattern stanza entrycredential-refresh-attributes stanzaentriesattribute_name_patterncredential-refresh-attributes stanzacredential-refresh-attributes stanzaattribute_name_pattern entrySyntax attribute_name_pattern = {preserve|refresh} Description Specifies whether an attribute, or group of attributes that match a pattern, are preserved or refreshed during a credential refresh. Options preserveOriginal attribute value is preserved in the new credential.refreshOriginal attribute value is refreshed in the new credential. Usage This stanza entry is optional. Default value preserve Example tagvalue_* = preserve [credential-refresh-attributes] stanzaUse the [credential-refresh-attributes] stanza to configure the credential refresh behavior in WebSEAL.

attribute_name_pattern

Use the attribute_name_pattern stanza entry to specify whether attributes are preserved or refreshed during a credential refresh.

Syntax

attribute_name_pattern = {preserve|refresh}

Description

Specifies whether an attribute, or group of attributes that match a pattern, are preserved or refreshed during a credential refresh.

Options

preserve

Original attribute value is preserved in the new credential.

refresh

Original attribute value is refreshed in the new credential.

Usage

This stanza entry is optional.

Default value

preserve

Example

tagvalue_* = preserve

Parent topic: [credential-refresh-attributes] stanza

authentication_levelauthentication_levelIBM Security Access Manager for Web WebSEAL authentication_level stanza entryUse the authentication_level stanza entry to control whether the authentication level is preserved or refreshed during a credential refresh.authentication_level stanza entrycredential-refresh-attributes stanzaentriesauthentication_levelcredential-refresh-attributes stanzacredential-refresh-attributes stanzaauthentication_level entrySyntax authentication_level = {preserve|refresh} Description Specifies whether the authentication level for the user is preserved or refreshed during a credential refresh. The authentication level can reflect the results of an authentication strength policy (step-up authentication). In most cases, it is best to preserve this level during a credential refresh. Options preserveThe original attribute value is preserved in the new credential.refreshThe original attribute value is refreshed in the new credential. Usage This stanza entry is required. Default value preserve Example authentication_level = preserve [credential-refresh-attributes] stanzaUse the [credential-refresh-attributes] stanza to configure the credential refresh behavior in WebSEAL.

authentication_level

Use the authentication_level stanza entry to control whether the authentication level is preserved or refreshed during a credential refresh.

Syntax

authentication_level = {preserve|refresh}

Description

Specifies whether the authentication level for the user is preserved or refreshed during a credential refresh. The authentication level can reflect the results of an authentication strength policy (step-up authentication). In most cases, it is best to preserve this level during a credential refresh.

Options

preserve

The original attribute value is preserved in the new credential.

refresh

The original attribute value is refreshed in the new credential.

Usage

This stanza entry is required.

Default value

preserve

Example

authentication_level = preserve

Parent topic: [credential-refresh-attributes] stanza

[dsess] stanza[dsess] stanzaIBM Security Access Manager for Web WebSEAL [dsess] stanzaUse the [dsess] stanza to configure the distributed session cache.dsess stanzastanzasdsessStanza referencedsess-sess-id-pool-sizeUse the dsess-sess-id-pool-size stanza entry to set the maximum number of pre-allocated session IDs in the replica set.dsess-cluster-nameUse the dsess-cluster-name stanza entry to specify the name of the distributed session cache cluster to which this server belongs.

[dsess] stanza

Use the [dsess] stanza to configure the distributed session cache.

dsess-sess-id-pool-size
Use the dsess-sess-id-pool-size stanza entry to set the maximum number of pre-allocated session IDs in the replica set.

dsess-cluster-name
Use the dsess-cluster-name stanza entry to specify the name of the distributed session cache cluster to which this server belongs.

Parent topic: Stanza reference

dsess-sess-id-pool-sizedsess-sess-id-pool-sizeIBM Security Access Manager for Web WebSEAL dsess-sess-id-pool-size stanza entryUse the dsess-sess-id-pool-size stanza entry to set the maximum number of pre-allocated session IDs in the replica set.dsess-sess-id-pool-size stanza entrydsess stanzaentriesdsess-sess-id-pool-sizedsess stanzadsess stanzadsess-sess-id-pool-size entrySyntax dsess-sess-id-pool-size = number Description The maximum number of session IDs that are pre-allocated within the replica set. This option is used by the [dsess-cluster] stanza. Options numberThe maximum number of session IDs that are pre-allocated within the replica set. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value 125 Example dsess-sess-id-pool-size = 125 [dsess] stanzaUse the [dsess] stanza to configure the distributed session cache.

dsess-sess-id-pool-size

Use the dsess-sess-id-pool-size stanza entry to set the maximum number of pre-allocated session IDs in the replica set.

Syntax

dsess-sess-id-pool-size = number

Description

The maximum number of session IDs that are pre-allocated within the replica set.

Note: This option is used by the [dsess-cluster] stanza.

Options

number

The maximum number of session IDs that are pre-allocated within the replica set.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

125

Example

dsess-sess-id-pool-size = 125

Parent topic: [dsess] stanza

dsess-cluster-namedsess-cluster-nameIBM Security Access Manager for Web WebSEAL dsess-cluster-name stanza entryUse the dsess-cluster-name stanza entry to specify the name of the distributed session cache cluster to which this server belongs.dsess-cluster-name stanza entrydsess stanzaentriesdsess-cluster-namedsess stanzadsess stanzadsess-cluster-name entrySyntax dsess-cluster-name = cluster name Description Specifies the name of the distributed session cache cluster to which this server belongs. Options cluster nameThe name of the distributed session cache cluster to which this server belongs. This field must be defined and reference an existing dsess-cluster stanza qualified by the value of this entry. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value dsess Example dsess-cluster-name = dsess [dsess] stanzaUse the [dsess] stanza to configure the distributed session cache.

dsess-cluster-name

Use the dsess-cluster-name stanza entry to specify the name of the distributed session cache cluster to which this server belongs.

Syntax

dsess-cluster-name = cluster name

Description

Specifies the name of the distributed session cache cluster to which this server belongs.

Options

cluster name

The name of the distributed session cache cluster to which this server belongs. This field must be defined and reference an existing dsess-cluster stanza qualified by the value of this entry.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

dsess

Example

dsess-cluster-name = dsess

Parent topic: [dsess] stanza

[dsess-cluster] stanza[dsess-cluster] stanzaIBM Security Access Manager for Web WebSEAL [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.dsess-cluster stanzastanzasdsess-clusterStanza referencebasic-auth-userUse the basic-auth-user stanza entry to specify the user name that WebSEAL includes in the basic authentication header.basic-auth-passwdUse the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header.gsk-attr-nameUse the gsk-attr-name stanza entry to specify additional GSKit attributes to use when initializing an SSL connection with the distributed session cache.handle-idle-timeouthandle-pool-sizeload-balanceControls the behavior when multiple servers with the same configured priority are available. response-byUse the response-by stanza entry to specify the length of time in seconds that the dsess client waits for updates from the distributed session cache.serverUse the server entry in the [dsess-cluster] stanza to specify each distributed session cache server and its priority in the cluster.ssl-fips-enabledUse the ssl-fips-enabled entry in the [dsess-cluster] stanza to control whether WebSEAL uses TLSv1 or SSLv3 communication with the distributed session cache.ssl-keyfilessl-keyfile-labelssl-keyfile-stashssl-nist-complianceUse the ssl-nist-compliance stanza entry in the [dsess-cluster] stanza to enable or disable NIST SP800-131A compliance for the distributed session cache.ssl-valid-server-dntimeoutUse the timeout entry in the [dsess-cluster] stanza to specify the number of seconds that WebSEAL waits for a response from the distributed session cache.

[dsess-cluster] stanza

Use the [dsess-cluster] to configure a distributed session cache cluster.

basic-auth-user
Use the basic-auth-user stanza entry to specify the user name that WebSEAL includes in the basic authentication header.

basic-auth-passwd
Use the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header.

gsk-attr-name
Use the gsk-attr-name stanza entry to specify additional GSKit attributes to use when initializing an SSL connection with the distributed session cache.

handle-idle-timeout

handle-pool-size

load-balance
Controls the behavior when multiple servers with the same configured priority are available.

response-by
Use the response-by stanza entry to specify the length of time in seconds that the dsess client waits for updates from the distributed session cache.

server
Use the server entry in the [dsess-cluster] stanza to specify each distributed session cache server and its priority in the cluster.

ssl-fips-enabled
Use the ssl-fips-enabled entry in the [dsess-cluster] stanza to control whether WebSEAL uses TLSv1 or SSLv3 communication with the distributed session cache.

ssl-keyfile

ssl-keyfile-label

ssl-keyfile-stash

ssl-nist-compliance
Use the ssl-nist-compliance stanza entry in the [dsess-cluster] stanza to enable or disable NIST SP800-131A compliance for the distributed session cache.

ssl-valid-server-dn

timeout
Use the timeout entry in the [dsess-cluster] stanza to specify the number of seconds that WebSEAL waits for a response from the distributed session cache.

Parent topic: Stanza reference

basic-auth-userbasic-auth-userIBM Security Access Manager for Web WebSEAL basic-auth-user stanza entryUse the basic-auth-user stanza entry to specify the user name that WebSEAL includes in the basic authentication header.basic-auth-user stanza entrydsess-cluster stanzaentriesbasic-auth-userdsess-cluster stanzadsess-cluster stanzabasic-auth-user entrySyntax basic-auth-user = user_name Description Specifies the name of the user that is included in the basic authentication header. Options user_nameThe user name to include in the basic authentication header. Usage This stanza entry is optional. Default value None. Example basic-auth-user = admin [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

basic-auth-user

Use the basic-auth-user stanza entry to specify the user name that WebSEAL includes in the basic authentication header.

Syntax

basic-auth-user = user_name

Description

Specifies the name of the user that is included in the basic authentication header.

Options

user_name

The user name to include in the basic authentication header.

Usage

This stanza entry is optional.

Default value

None.

Example

basic-auth-user = admin

Parent topic: [dsess-cluster] stanza

basic-auth-passwdbasic-auth-passwdIBM Security Access Manager for Web WebSEAL basic-auth-passwd stanza entryUse the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header.basic-auth-passwd stanza entrydsess-cluster stanzaentriesbasic-auth-passwddsess-cluster stanzadsess-cluster stanzabasic-auth-passwd entrySyntax basic-auth-passwd = password Description Specifies the password that is included in the basic authentication header. Options passwordThe password to include in the basic authentication header. Usage This stanza entry is optional. Default value None. Example basic-auth-passwd = myPassword1 [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

basic-auth-passwd

Use the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header.

Syntax

basic-auth-passwd = password

Description

Specifies the password that is included in the basic authentication header.

Options

password

The password to include in the basic authentication header.

Usage

This stanza entry is optional.

Default value

None.

Example

basic-auth-passwd = myPassword1

Parent topic: [dsess-cluster] stanza

gsk-attr-namegsk-attr-nameUse the gsk-attr-name stanza entry to specify additional GSKit attributes to use when initializing an SSL connection with the distributed session cache.gsk-attr-name stanza entrydsess-cluster stanzaentriesgsk-attr-namedsess-cluster stanzadsess-cluster stanzagsk-attr-name entrySyntax gsk-attr-name = {enum | string | number}:id:value Description This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute. Options {enum | string | number}The GSKit attribute type.idThe identity associated with the GSKit attribute.valueThe value for the GSKit attribute. Usage This stanza entry is optional. See Appendix: Supported GSKit attributesYou can configure the these GSKit attributes with Security Access Manager. for a list of GSKit attributes that can be configured.You cannot configure the following restricted GSKit attributes: GSK_KEYRING_FILE, GSK_KEYRING_PW, GSK_KEYRING_STASH_FILE, GSK_V2_SIDCACHE_SIZE, GSK_V3_SIDCACHE_SIZE, GSK_V2_SESSION_TIMEOUT, GSK_V3_SESSION_TIMEOUT, GSK_PROTOCOL_SSLV2, GSK_PROTOCOL_SSLV3, GSK_PROTOCOL_TLSV1, GSK_PROTOCOL_TLSV11, GSK_PROTOCOL_TLSV12, GSK_LDAP_SERVER, GSK_LDAP_SERVER_PORT, GSK_LDAP_USER, GSK_LDAP_USER_PW, GSK_CRL_CACHE_SIZE, GSK_CRL_CACHE_ENTRY_LIFETIME, GSK_ACCELERATOR_NCIPHER_NF, GSK_ACCELERATOR_RAINBOW_CS, GSK_PKCS11_DRIVER_PATH, GSK_PKCS11_TOKEN_LABEL, GSK_PKCS11_TOKEN_PWD, GSK_PKCS11_ACCELERATOR_MODE, GSK_BASE_CRYPTO_LIBRARY, GSK_OCSP_ENABLE, GSK_OCSP_URL, GSK_OCSP_NONCE_GENERATION_ENABLE, GSK_OCSP_NONCE_CHECK_ENABLE, GSK_OCSP_REQUEST_SIGKEYLABEL, GSK_OCSP_REQUEST_SIGALG, GSK_OCSP_PROXY_SERVER_NAME, GSK_OCSP_PROXY_SERVER_PORT, GSK_OCSP_RETRIEVE_VIA_GET, GSK_OCSP_MAX_RESPONSE_SIZE, GSK_USE_IO_EVENTS, GSK_USER_DATA, GSK_NO_RENEGOTIATION, GSK_ALLOW_ANY_RENEGOTIATION, GSK_ALLOW_ABBREVIATED_RENEGOTIATION, GSK_ALLOW_ONLY_EXTENDED_RENEGOTIATION,If you attempt to modify any of these attributes then an error message will be generated. Default value None. Example The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:gsk-attr-name = string:225:proxy.ibm.com See alsogsk-attr-name jct-gsk-attr-name gsk-attr-name[dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

gsk-attr-name

Use the gsk-attr-name stanza entry to specify additional GSKit attributes to use when initializing an SSL connection with the distributed session cache.

Syntax

gsk-attr-name = {enum | string | number}:id:value

Description

This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute.

Options

{enum | string | number}

The GSKit attribute type.

id

The identity associated with the GSKit attribute.

value

The value for the GSKit attribute.

Usage

This stanza entry is optional.

See Appendix: Supported GSKit attributes for a list of GSKit attributes that can be configured.

You cannot configure the following restricted GSKit attributes:

   GSK_KEYRING_FILE,
   GSK_KEYRING_PW,
   GSK_KEYRING_STASH_FILE,
   GSK_V2_SIDCACHE_SIZE,
   GSK_V3_SIDCACHE_SIZE,
   GSK_V2_SESSION_TIMEOUT,
   GSK_V3_SESSION_TIMEOUT,
   GSK_PROTOCOL_SSLV2,
   GSK_PROTOCOL_SSLV3,
   GSK_PROTOCOL_TLSV1,
   GSK_PROTOCOL_TLSV11,
   GSK_PROTOCOL_TLSV12,
   GSK_LDAP_SERVER,
   GSK_LDAP_SERVER_PORT,
   GSK_LDAP_USER,
   GSK_LDAP_USER_PW,
   GSK_CRL_CACHE_SIZE,
   GSK_CRL_CACHE_ENTRY_LIFETIME,
   GSK_ACCELERATOR_NCIPHER_NF,
   GSK_ACCELERATOR_RAINBOW_CS,
   GSK_PKCS11_DRIVER_PATH,
   GSK_PKCS11_TOKEN_LABEL,
   GSK_PKCS11_TOKEN_PWD,
   GSK_PKCS11_ACCELERATOR_MODE,
   GSK_BASE_CRYPTO_LIBRARY,
   GSK_OCSP_ENABLE,
   GSK_OCSP_URL,
   GSK_OCSP_NONCE_GENERATION_ENABLE,
   GSK_OCSP_NONCE_CHECK_ENABLE,
   GSK_OCSP_REQUEST_SIGKEYLABEL,
   GSK_OCSP_REQUEST_SIGALG,
   GSK_OCSP_PROXY_SERVER_NAME,
   GSK_OCSP_PROXY_SERVER_PORT,
   GSK_OCSP_RETRIEVE_VIA_GET,
   GSK_OCSP_MAX_RESPONSE_SIZE,
   GSK_USE_IO_EVENTS,
   GSK_USER_DATA,
   GSK_NO_RENEGOTIATION,
   GSK_ALLOW_ANY_RENEGOTIATION,
   GSK_ALLOW_ABBREVIATED_RENEGOTIATION,
   GSK_ALLOW_ONLY_EXTENDED_RENEGOTIATION,

If you attempt to modify any of these attributes then an error message will be generated.

Default value

None.

Example

The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:

gsk-attr-name = string:225:proxy.ibm.com

See also

gsk-attr-name

jct-gsk-attr-name

gsk-attr-name

Parent topic: [dsess-cluster] stanza

handle-idle-timeouthandle-idle-timeouthandle-idle-timeout stanza entrydsess-cluster stanzaentries dsess-cluster stanzahandle-idle-timeoutdsess-cluster stanzahandle-idle-timeout entrySyntax handle-idle-timeout = number Description Limits the length of time that a handle remains idle before it is removed from the handle pool cache. Options numberThe length of time, in seconds, before an idle handle will be removed from the handle pool cache. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value 240 Example handle-idle-timeout = 240 [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

handle-idle-timeout

Syntax

handle-idle-timeout = number

Description

Limits the length of time that a handle remains idle before it is removed from the handle pool cache.

Options

number

The length of time, in seconds, before an idle handle will be removed from the handle pool cache.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

240

Example

handle-idle-timeout = 240

Parent topic: [dsess-cluster] stanza

handle-pool-sizehandle-pool-sizehandle-pool-size stanza entrydsess-cluster stanzaentrieshandle-pool-sizedsess-cluster stanzadsess-cluster stanzahandle-pool-size entrySyntax handle-pool-size = numberDescription The maximum number of idle Simple Access Object Protocol (SOAP) handles that the dsess client will maintain at any given time.Options numberThe maximum number of idle SOAP handles that the dsess client will maintain at any given time.Usage This stanza entry is required when: [session] dsess-enabled = yesDefault value 10Example handle-pool-size = 10[dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

handle-pool-size

Syntax

handle-pool-size = number

Description

The maximum number of idle Simple Access Object Protocol (SOAP) handles that the dsess client will maintain at any given time.

Options

number

The maximum number of idle SOAP handles that the dsess client will maintain at any given time.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

10

Example

handle-pool-size = 10

Parent topic: [dsess-cluster] stanza

load-balanceControls the behavior when multiple servers with the same configured priority are available. Syntax load-balance = {yes | no}Description This stanza entry impacts all of the SOAP web service stanzas, which are shown in the following list: [dsess-cluster] [rtss-cluster:<cluster>] [tfim-cluster:<cluster>]Options yesAll requests are sent to matching servers in a round-robin fashion. noAll requests are sent to the first matching server until that server becomes unavailable. Usage This stanza entry is optional. Default value The default value is yes.Example load-balance = yes[dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

load-balance

Controls the behavior when multiple servers with the same configured priority are available.

Syntax

load-balance = {yes | no}

Description

This stanza entry impacts all of the SOAP web service stanzas, which are shown in the following list:

[dsess-cluster]
[rtss-cluster:<cluster>]
[tfim-cluster:<cluster>]

Options

yes

All requests are sent to matching servers in a round-robin fashion.

no

All requests are sent to the first matching server until that server becomes unavailable.

Usage

This stanza entry is optional.

Default value

The default value is yes.

Example

load-balance = yes

Parent topic: [dsess-cluster] stanza

response-byresponse-byUse the response-by stanza entry to specify the length of time in seconds that the dsess client waits for updates from the distributed session cache.response-by stanza entrydsess-cluster stanzaentriesresponse-bydsess-cluster stanzadsess-cluster stanzaresponse-by entrySyntax response-by = seconds Description The length of time (in seconds) that the dsess client blocks to wait for updates from the distributed session cache. Options secondsThe length of time (in seconds) that the dsess client blocks to wait for updates from the distributed session cache. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value 60 Example response-by = 60 [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

response-by

Use the response-by stanza entry to specify the length of time in seconds that the dsess client waits for updates from the distributed session cache.

Syntax

response-by = seconds

Description

The length of time (in seconds) that the dsess client blocks to wait for updates from the distributed session cache.

Options

seconds

The length of time (in seconds) that the dsess client blocks to wait for updates from the distributed session cache.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

60

Example

response-by = 60

Parent topic: [dsess-cluster] stanza

serverserverUse the server entry in the [dsess-cluster] stanza to specify each distributed session cache server and its priority in the cluster.server stanza entrydsess-cluster stanzaentriesserverdsess-cluster stanzadsess-cluster stanzaserver entrySyntax server = {[0-9],}<URL> Description Specifies a priority level and URL for each distributed session cache server that is a member of this cluster. Multiple server entries can be specified for a given cluster. Options 0-9A digit, 0-9, that represents the priority of the server within the cluster (9 being the highest, 0 being the lowest). If the priority is not specified, a priority of 9 is assumed. There can be no space between the comma (,) and the URL. If no priority is specified, the comma is omitted.URLA well-formed HTTP or HTTPS uniform resource locator for the server. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value This entry is disabled by default. Example server = 9,http://dsc.example.com/DSess/services/DSess [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

server

Use the server entry in the [dsess-cluster] stanza to specify each distributed session cache server and its priority in the cluster.

Syntax

server = {[0-9],}<URL>

Description

Specifies a priority level and URL for each distributed session cache server that is a member of this cluster. Multiple server entries can be specified for a given cluster.

Options

0-9

A digit, 0-9, that represents the priority of the server within the cluster (9 being the highest, 0 being the lowest). If the priority is not specified, a priority of 9 is assumed.

Note: There can be no space between the comma (,) and the URL. If no priority is specified, the comma is omitted.

URL

A well-formed HTTP or HTTPS uniform resource locator for the server.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

This entry is disabled by default.

Example

server = 9,http://dsc.example.com/DSess/services/DSess

Parent topic: [dsess-cluster] stanza

ssl-fips-enabledssl-fips-enabledUse the ssl-fips-enabled entry in the [dsess-cluster] stanza to control whether WebSEAL uses TLSv1 or SSLv3 communication with the distributed session cache.ssl-fips-enabled stanza entrydsess-cluster stanzaentriesssl-fips-enableddsess-cluster stanzadsess-cluster stanzassl-fips-enabled entryFederal Information Process Standards (FIPS)ssl-fips-enabled stanza entryFIPS (Federal Information Process Standards )ssl-fips-enabled stanza entrySyntax ssl-fips-enabled = {yes|no} Description Determines whether Federal Information Process Standards (FIPS) mode is enabled on the distributed session cache. If no configuration entry is present, the setting from the global setting—as determined by the ssl-fips-enabled entry in the [ssl] stanza of the policy server—takes effect. When set to yes or the setting in the policy server configuration file is set to yes, Transport Layer Security (TLS) version 1 (TLSv1) is the secure communication protocol used. When set to no or the setting in the policy server configuration file is set to no, SSL version 3 (SSLv3) is the secure communication protocol used. The [dsess-cluster] ssl-nist-compliance setting can override this entry. If ssl-nist-compliance is set to yes, FIPS mode processing is automatically enabled. Options yesIndicates that TLSv1 is the secure communication protocol.noIndicates that SSLv3 is the secure communication protocol. Usage This stanza entry is optional. Default value None. If a different FIPS level than that of the policy server is required, it is the responsibility of the administrator to edit the configuration file, uncomment the stanza entry, and specify this value. Example ssl-fips-enabled = yes [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

ssl-fips-enabled

Use the ssl-fips-enabled entry in the [dsess-cluster] stanza to control whether WebSEAL uses TLSv1 or SSLv3 communication with the distributed session cache.

Syntax

ssl-fips-enabled = {yes|no}

Description

Determines whether Federal Information Process Standards (FIPS) mode is enabled on the distributed session cache. If no configuration entry is present, the setting from the global setting—as determined by the ssl-fips-enabled entry in the [ssl] stanza of the policy server—takes effect.

When set to yes or the setting in the policy server configuration file is set to yes, Transport Layer Security (TLS) version 1 (TLSv1) is the secure communication protocol used. When set to no or the setting in the policy server configuration file is set to no, SSL version 3 (SSLv3) is the secure communication protocol used.

Note: The [dsess-cluster] ssl-nist-compliance setting can override this entry. If ssl-nist-compliance is set to yes, FIPS mode processing is automatically enabled.

Options

yes

Indicates that TLSv1 is the secure communication protocol.

no

Indicates that SSLv3 is the secure communication protocol.

Usage

This stanza entry is optional.

Default value

None.

If a different FIPS level than that of the policy server is required, it is the responsibility of the administrator to edit the configuration file, uncomment the stanza entry, and specify this value.

Example

ssl-fips-enabled = yes

Parent topic: [dsess-cluster] stanza

ssl-keyfilessl-keyfilessl-keyfile stanza entrydsess-cluster stanzaentriesssl-keyfiledsess-cluster stanzadsess-cluster stanzassl-keyfile entrySyntax ssl-keyfile = file_name Description The name of the key database file, which houses the client certificate to be used. Options file_nameThe name of the key database file that houses the client certificate for WebSEAL to use. Usage This stanza entry is only required if one or more of the cluster server URLs specified in the server entries uses SSL (that is, contains an HTTPS protocol specification in the URL). If no cluster server uses the HTTPS protocol, this entry is not required. [session] dsess-enabled = yes Default value None. Example ssl-keyfile = keyfile.kdb [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

ssl-keyfile

Syntax

ssl-keyfile = file_name

Description

The name of the key database file, which houses the client certificate to be used.

Options

file_name

The name of the key database file that houses the client certificate for WebSEAL to use.

Usage

This stanza entry is only required if one or more of the cluster server URLs specified in the server entries uses SSL (that is, contains an HTTPS protocol specification in the URL). If no cluster server uses the HTTPS protocol, this entry is not required.

[session]
dsess-enabled = yes

Default value

None.

Example

ssl-keyfile = keyfile.kdb

Parent topic: [dsess-cluster] stanza

ssl-keyfile-labelssl-keyfile-labelssl-keyfile-label stanza entrydsess-cluster stanzaentriesssl-keyfile-labeldsess-cluster stanzadsess-cluster stanzassl-keyfile-label entrySyntax ssl-keyfile-label = label_name Description The label of the client certificate within the key database. Options label_nameClient certificate label name. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value None. Example ssl-keyfile-label = WS6 [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

ssl-keyfile-label

Syntax

ssl-keyfile-label = label_name

Description

The label of the client certificate within the key database.

Options

label_name

Client certificate label name.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

None.

Example

ssl-keyfile-label = WS6

Parent topic: [dsess-cluster] stanza

ssl-keyfile-stashssl-keyfile-stashssl-keyfile-stash stanza entrydsess-cluster stanzaentries dsess-cluster stanzassl-keyfile-stashdsess-cluster stanzassl-keyfile-stash entrySyntax ssl-keyfile-stash = file_name Description The name of the password stash file for the key database file. Options file_nameThe password stash file. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value None. Example ssl-keyfile-stash = pdsrv.sth [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

ssl-keyfile-stash

Syntax

ssl-keyfile-stash = file_name

Description

The name of the password stash file for the key database file.

Options

file_name

The password stash file.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

None.

Example

ssl-keyfile-stash = pdsrv.sth

Parent topic: [dsess-cluster] stanza

ssl-nist-compliancessl-nist-complianceIBM Security Access Manager for Web WebSEAL ssl-nist-compliance stanza entryUse the ssl-nist-compliance stanza entry in the [dsess-cluster] stanza to enable or disable NIST SP800-131A compliance for the distributed session cache.ssl-nist-compliance stanza entrydsess-cluster stanzaentriesssl-nist-compliancedsess-cluster stanzadsess-cluster stanzassl-nist-compliance entrySyntax ssl-nist-compliance = {yes|no} Description Enables or disables NIST SP800-131A compliance for the distributed session cache.Enabling NIST SP800-131A compliance results in the following automatic configuration:Enables FIPS mode processing. When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the [dsess-cluster] ssl-fips-enabled configuration entry.Enables TLS v1.2. TLS v1 and TLS v1.1 are not disabled.Enables the appropriate signature algorithms.Sets the minimum RSA key size to 2048 bytes.If this ssl-nist-compliance configuration entry is not present, WebSEAL uses the global nist-compliance setting in the [ssl] stanza. Options yesA value of yes enables NIST SP800-131A compliance. noA value of no disables NIST SP800-131A compliance. Usage This stanza entry is optional. Default value no Example ssl-nist-compliance = no [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

ssl-nist-compliance

Use the ssl-nist-compliance stanza entry in the [dsess-cluster] stanza to enable or disable NIST SP800-131A compliance for the distributed session cache.

Syntax

ssl-nist-compliance = {yes|no}

Description

Enables or disables NIST SP800-131A compliance for the distributed session cache.

Enabling NIST SP800-131A compliance results in the following automatic configuration:

Enables FIPS mode processing.

Note: When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the [dsess-cluster] ssl-fips-enabled configuration entry.

Enables TLS v1.2.

Note: TLS v1 and TLS v1.1 are not disabled.

Enables the appropriate signature algorithms.

Sets the minimum RSA key size to 2048 bytes.

If this ssl-nist-compliance configuration entry is not present, WebSEAL uses the global nist-compliance setting in the [ssl] stanza.

Options

yes

A value of yes enables NIST SP800-131A compliance.

no

A value of no disables NIST SP800-131A compliance.

Usage

This stanza entry is optional.

Default value

no

Example

ssl-nist-compliance = no

Parent topic: [dsess-cluster] stanza

ssl-valid-server-dnssl-valid-server-dnssl-valid-server-dn stanza entrydsess-cluster stanzaentriesssl-valid-server-dndsess-cluster stanzadsess-cluster stanzassl-valid-server-dn entrySyntax ssl-valid-server-dn = certificate_DNDescription Specifies the DN of the server (obtained from the server SSL certificate) that is accepted. If no entry is configured, any valid certificate signed by a CA in the key file is accepted. Options valueSpecifies the DN of the server (obtained from the server SSL certificate) that is accepted. If no entry is configured, any valid certificate signed by a CA in the key file is accepted. Usage This stanza entry is required when: [session] dsess-enabled = yesDefault value None.Example ssl-valid-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US[dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

ssl-valid-server-dn

Syntax

ssl-valid-server-dn = certificate_DN

Description

Specifies the DN of the server (obtained from the server SSL certificate) that is accepted. If no entry is configured, any valid certificate signed by a CA in the key file is accepted.

Options

value

Specifies the DN of the server (obtained from the server SSL certificate) that is accepted. If no entry is configured, any valid certificate signed by a CA in the key file is accepted.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

None.

Example

ssl-valid-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US

Parent topic: [dsess-cluster] stanza

timeouttimeoutUse the timeout entry in the [dsess-cluster] stanza to specify the number of seconds that WebSEAL waits for a response from the distributed session cache.timeout stanza entrydsess-cluster stanzaentriestimeoutdsess-cluster stanzadsess-cluster stanzatimeout entrySyntax timeout = seconds Description The length of time, in seconds, to wait for a response to be received back from the distributed session cache. Options secondsThe length of time, in seconds, to wait for a response to be received back from the distributed session cache. Usage This stanza entry is required when: [session] dsess-enabled = yes Default value 30 Example timeout = 30 [dsess-cluster] stanzaUse the [dsess-cluster] to configure a distributed session cache cluster.

timeout

Use the timeout entry in the [dsess-cluster] stanza to specify the number of seconds that WebSEAL waits for a response from the distributed session cache.

Syntax

timeout = seconds

Description

The length of time, in seconds, to wait for a response to be received back from the distributed session cache.

Options

seconds

The length of time, in seconds, to wait for a response to be received back from the distributed session cache.

Usage

This stanza entry is required when:

[session]
dsess-enabled = yes

Default value

30

Example

timeout = 30

Parent topic: [dsess-cluster] stanza

[eai] stanza[eai] stanzaIBM Security Access Manager for Web WebSEAL [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).eai stanzastanzaseaiStanza referenceeai-authUse the eai-auth stanza entry to enable the external authentication interface.eai-auth-level-headerUse the eai-auth-level-header stanza entry to specify the name of the header that contains the authentication strength level for the generated credential.eai-ext-user-id-headerUse the eai-ext-user-id-header stanza entry to specify the name of the header that contains the ID of the external user to use when creating a credential.eai-ext-user-groups-headerUse the eai-ext-user-groups-header stanza entry to specify the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential.eai-pac-headerUse the eai-pac-header stanza entry to specify the name of the HTTP header that contains the authentication data in Privilege Attribute Certificate (PAC) format. eai-pac-svc-headerUse the eai-pac-svc-header stanza entry to specify the name of the header that contains the service ID, which WebSEAL uses to convert the Privilege Attribute Certificate (PAC) into a credential.eai-redir-url-headerUse the eai-redir-url-header stanza entry to specify the name of the header that contains the URL to which WebSEAL redirects the client after successful authentication.eai-session-id-headerUse the eai-session-id-header stanza entry to specify the name of the header that contains the session identifier of the distributed session.eai-user-id-headerUse the eai-user-id-header stanza entry to specify the header that contains the user ID for which WebSEAL generates the credential. The specified header must precede all others in the HTTP response.eai-verify-user-identityUse the eai-verify-user-identity stanza entry to control whether the user identity is verified during reauthentication. EAI applications can reauthenticate a user by returning new authentication information for a previously authenticated session. By default, WebSEAL does not ensure that the new user identity matches the user identity from the previous authentication.eai-xattrs-headerUse the eai-xattrs-header stanza entry to specify the HTTP headers in the response from the external authentication interface (EAI) server that contain authentication data. WebSEAL uses these headers to add extended attributes to the credential.retain-eai-session

[eai] stanza

Use the [eai] stanza to configure the external authentication interface (EAI).

eai-auth
Use the eai-auth stanza entry to enable the external authentication interface.

eai-auth-level-header
Use the eai-auth-level-header stanza entry to specify the name of the header that contains the authentication strength level for the generated credential.

eai-ext-user-id-header
Use the eai-ext-user-id-header stanza entry to specify the name of the header that contains the ID of the external user to use when creating a credential.

eai-ext-user-groups-header
Use the eai-ext-user-groups-header stanza entry to specify the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential.

eai-pac-header
Use the eai-pac-header stanza entry to specify the name of the HTTP header that contains the authentication data in Privilege Attribute Certificate (PAC) format.

eai-pac-svc-header
Use the eai-pac-svc-header stanza entry to specify the name of the header that contains the service ID, which WebSEAL uses to convert the Privilege Attribute Certificate (PAC) into a credential.

eai-redir-url-header
Use the eai-redir-url-header stanza entry to specify the name of the header that contains the URL to which WebSEAL redirects the client after successful authentication.

eai-session-id-header
Use the eai-session-id-header stanza entry to specify the name of the header that contains the session identifier of the distributed session.

eai-user-id-header
Use the eai-user-id-header stanza entry to specify the header that contains the user ID for which WebSEAL generates the credential. The specified header must precede all others in the HTTP response.

eai-verify-user-identity
Use the eai-verify-user-identity stanza entry to control whether the user identity is verified during reauthentication. EAI applications can reauthenticate a user by returning new authentication information for a previously authenticated session. By default, WebSEAL does not ensure that the new user identity matches the user identity from the previous authentication.

eai-xattrs-header
Use the eai-xattrs-header stanza entry to specify the HTTP headers in the response from the external authentication interface (EAI) server that contain authentication data. WebSEAL uses these headers to add extended attributes to the credential.

retain-eai-session

Parent topic: Stanza reference

eai-autheai-authIBM Security Access Manager for Web WebSEAL eai-auth stanza entryUse the eai-auth stanza entry to enable the external authentication interface.eai-auth stanza entryeai stanzaentrieseai-autheai stanzaeai stanzaeai-auth entrySyntax eai-auth = {none|http|https|both} Description Enables the external authentication interface. Options {none|http|https|both}Enables the external authentication interface. No other external authentication interface parameters will take effect if set to "none". Usage This stanza entry is required. Default value none Example eai-auth = none [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-auth

Use the eai-auth stanza entry to enable the external authentication interface.

Syntax

eai-auth = {none|http|https|both}

Description

Enables the external authentication interface.

Options

{none|http|https|both}

Enables the external authentication interface. No other external authentication interface parameters will take effect if set to "none".

Usage

This stanza entry is required.

Default value

none

Example

eai-auth = none

Parent topic: [eai] stanza

eai-auth-level-headereai-auth-level-headerIBM Security Access Manager for Web WebSEAL eai-auth-level-header stanza entryUse the eai-auth-level-header stanza entry to specify the name of the header that contains the authentication strength level for the generated credential.eai-auth-level-header stanza entryeai stanzaentrieseai-auth-level-headereai stanzaeai stanzaeai-auth-level-header entrySyntax eai-auth-level-header = header-name Description Specifies the name of the header that contains the authentication strength level for the generated credential. Options header-nameThe name of the header that contains the authentication strength level for the generated credential. Usage This stanza entry is optional. Default value am-eai-auth-level Example eai-auth-level-header = am-eai-auth-level [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-auth-level-header

Use the eai-auth-level-header stanza entry to specify the name of the header that contains the authentication strength level for the generated credential.

Syntax

eai-auth-level-header = header-name

Description

Specifies the name of the header that contains the authentication strength level for the generated credential.

Options

header-name

The name of the header that contains the authentication strength level for the generated credential.

Usage

This stanza entry is optional.

Default value

am-eai-auth-level

Example

eai-auth-level-header = am-eai-auth-level

Parent topic: [eai] stanza

eai-ext-user-id-headereai-ext-user-id-headerIBM Security Access Manager for Web WebSEAL eai-ext-user-id-header stanza entryUse the eai-ext-user-id-header stanza entry to specify the name of the header that contains the ID of the external user to use when creating a credential.eai-ext-user-id-header stanza entryeai stanzaentrieseai-ext-user-id-headereai stanzaeai stanzaeai-ext-user-id-header entrySyntax eai-ext-user-id-header = header-name Description Specifies the name of the header that contains the ID of the external (not in the Security Access Manager user registry) user to use when creating a credential. Options header-nameThe name of the header that contains the ID of the external user that is used when generating a credential. Usage This stanza entry is optional. Default value am-eai-ext-user-id Example eai-ext-user-id-header = am-eai-ext-user-id [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-ext-user-id-header

Use the eai-ext-user-id-header stanza entry to specify the name of the header that contains the ID of the external user to use when creating a credential.

Syntax

eai-ext-user-id-header = header-name

Description

Specifies the name of the header that contains the ID of the external (not in the Security Access Manager user registry) user to use when creating a credential.

Options

header-name

The name of the header that contains the ID of the external user that is used when generating a credential.

Usage

This stanza entry is optional.

Default value

am-eai-ext-user-id

Example

eai-ext-user-id-header = am-eai-ext-user-id

Parent topic: [eai] stanza

eai-ext-user-groups-headereai-ext-user-groups-headerIBM Security Access Manager for Web WebSEAL eai-ext-user-groups-header stanza entryUse the eai-ext-user-groups-header stanza entry to specify the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential.eai-ext-user-groups-header stanza entryeai stanzaentrieseai-ext-user-groups-headereai stanzaeai stanzaeai-ext-user-groups-header entrySyntax eai-ext-user-groups-header = header-name Description Specifies the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential. This entry is only used when the eai-ext-user-id-header stanza entry's value is provided. Options header-nameThe name of the header that contains the group or comma separated list of groups, that the external user is to be considered a member of, when generating a credential. Usage This stanza entry is optional. Default value am-eai-ext-user-groups Example eai-ext-user-groups-header = am-eai-ext-user-groups [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-ext-user-groups-header

Use the eai-ext-user-groups-header stanza entry to specify the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential.

Syntax

eai-ext-user-groups-header = header-name

Description

Specifies the name of the header that contains the group or groups an external user is to be considered a member of when generating a credential. This entry is only used when the eai-ext-user-id-header stanza entry's value is provided.

Options

header-name

The name of the header that contains the group or comma separated list of groups, that the external user is to be considered a member of, when generating a credential.

Usage

This stanza entry is optional.

Default value

am-eai-ext-user-groups

Example

eai-ext-user-groups-header = am-eai-ext-user-groups

Parent topic: [eai] stanza

eai-pac-headereai-pac-headerIBM Security Access Manager for Web WebSEAL eai-pac-header stanza entryUse the eai-pac-header stanza entry to specify the name of the HTTP header that contains the authentication data in Privilege Attribute Certificate (PAC) format. eai-pac-header stanza entryeai stanzaentrieseai-pac-headereai stanzaeai stanzaeai-pac-header entrySyntax eai-pac-header = header-name Description Specifies the name of the HTTP header that contains the authentication data that is returned from the external authentication interface server in PAC format. Options header-nameThe name of HTTP header that contains the authentication data that is returned from the external authentication interface server in PAC format. Usage This stanza entry is optional. Default value am-eai-pac Example eai-pac-header = am-eai-pac [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-pac-header

Use the eai-pac-header stanza entry to specify the name of the HTTP header that contains the authentication data in Privilege Attribute Certificate (PAC) format.

Syntax

eai-pac-header = header-name

Description

Specifies the name of the HTTP header that contains the authentication data that is returned from the external authentication interface server in PAC format.

Options

header-name

The name of HTTP header that contains the authentication data that is returned from the external authentication interface server in PAC format.

Usage

This stanza entry is optional.

Default value

am-eai-pac

Example

eai-pac-header = am-eai-pac

Parent topic: [eai] stanza

eai-pac-svc-headereai-pac-svc-headerIBM Security Access Manager for Web WebSEAL eai-pac-svc-header stanza entryUse the eai-pac-svc-header stanza entry to specify the name of the header that contains the service ID, which WebSEAL uses to convert the Privilege Attribute Certificate (PAC) into a credential.eai-pac-svc-header stanza entryeai stanzaentrieseai-pac-svc-headereai stanzaeai stanzaeai-pac-svc-header entrySyntax eai-pac-svc-header = header-name Description Specifies the name of the header that contains the service ID that is used to convert the PAC into a credential. Options header-nameThe name of the header that contains the service ID that is used to convert the PAC into a credential. Usage This stanza entry is optional. Default value am-eai-pac-svc Example eai-pac-svc-header = am-eai-pac-svc [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-pac-svc-header

Use the eai-pac-svc-header stanza entry to specify the name of the header that contains the service ID, which WebSEAL uses to convert the Privilege Attribute Certificate (PAC) into a credential.

Syntax

eai-pac-svc-header = header-name

Description

Specifies the name of the header that contains the service ID that is used to convert the PAC into a credential.

Options

header-name

The name of the header that contains the service ID that is used to convert the PAC into a credential.

Usage

This stanza entry is optional.

Default value

am-eai-pac-svc

Example

eai-pac-svc-header = am-eai-pac-svc

Parent topic: [eai] stanza

eai-redir-url-headereai-redir-url-headerIBM Security Access Manager for Web WebSEAL eai-redir-url-header stanza entryUse the eai-redir-url-header stanza entry to specify the name of the header that contains the URL to which WebSEAL redirects the client after successful authentication.eai-redir-url-header stanza entryeai stanzaentrieseai-redir-url-headereai stanzaeai stanzaeai-redir-url-header entrySyntax eai-redir-url-header = header-name Description Specifies the name of the header that contains the URL a client is redirected to upon successful authentication. Options header-nameThe name of the header that contains the URL a client is redirected to upon successful authentication. Usage This stanza entry is optional. Default value am-eai-redir-url Example eai-redir-url-header = am-eai-redir-url [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-redir-url-header

Use the eai-redir-url-header stanza entry to specify the name of the header that contains the URL to which WebSEAL redirects the client after successful authentication.

Syntax

eai-redir-url-header = header-name

Description

Specifies the name of the header that contains the URL a client is redirected to upon successful authentication.

Options

header-name

The name of the header that contains the URL a client is redirected to upon successful authentication.

Usage

This stanza entry is optional.

Default value

am-eai-redir-url

Example

eai-redir-url-header = am-eai-redir-url

Parent topic: [eai] stanza

eai-session-id-headereai-session-id-headerIBM Security Access Manager for Web WebSEAL eai-session-id-header stanza entryUse the eai-session-id-header stanza entry to specify the name of the header that contains the session identifier of the distributed session.eai-session-id-header stanza entryeai stanzaentrieseai-session-id-headereai stanzaeai stanzaeai-session-id-header entrySyntax eai-session-id-header = header-name Description The name of the header that contains the session identifier of the distributed session to be shared across multiple DNS domains. Options header-nameThe session identifier of the distributed session to be shared across multiple DNS domains. Usage This stanza entry is required. Default value am-eai-session-id Example eai-session-id-header = am-eai-session-id [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-session-id-header

Use the eai-session-id-header stanza entry to specify the name of the header that contains the session identifier of the distributed session.

Syntax

eai-session-id-header = header-name

Description

The name of the header that contains the session identifier of the distributed session to be shared across multiple DNS domains.

Options

header-name

The session identifier of the distributed session to be shared across multiple DNS domains.

Usage

This stanza entry is required.

Default value

am-eai-session-id

Example

eai-session-id-header = am-eai-session-id

Parent topic: [eai] stanza

eai-user-id-headereai-user-id-headerIBM Security Access Manager for Web WebSEAL eai-user-id-header stanza entryUse the eai-user-id-header stanza entry to specify the header that contains the user ID for which WebSEAL generates the credential. The specified header must precede all others in the HTTP response.eai-user-id-header stanza entryeai stanzaentrieseai-user-id-headereai stanzaeai stanzaeai-user-id-header entrySyntax eai-user-id-header = header-name Description Specifies the name of the header that contains the ID of the user used when generating a credential. Options header-nameThe name of the header that contains the ID of the user used when generating a credential. Usage This stanza entry is optional. Default value am-eai-user-id Example eai-user-id-header = am-eai-user-id [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-user-id-header

Use the eai-user-id-header stanza entry to specify the header that contains the user ID for which WebSEAL generates the credential. The specified header must precede all others in the HTTP response.

Syntax

eai-user-id-header = header-name

Description

Specifies the name of the header that contains the ID of the user used when generating a credential.

Options

header-name

The name of the header that contains the ID of the user used when generating a credential.

Usage

This stanza entry is optional.

Default value

am-eai-user-id

Example

eai-user-id-header = am-eai-user-id

Parent topic: [eai] stanza

eai-verify-user-identityeai-verify-user-identityIBM Security Access Manager for Web WebSEAL eai-verify-user-identity stanza entryUse the eai-verify-user-identity stanza entry to control whether the user identity is verified during reauthentication. EAI applications can reauthenticate a user by returning new authentication information for a previously authenticated session. By default, WebSEAL does not ensure that the new user identity matches the user identity from the previous authentication.eai-verify-user-identity stanza entryeai stanzaentrieseai-verify-user-identityeai stanzaeai stanzaeai-verify-user-identity entrySyntax eai-verify-user-identity = {yes|no} Description During the EAI re-authentication process, this configuration entry determines whether the new user identity must match the user identity from the previous authentication. Options yesDuring EAI authentication, the new user identity is compared with the user identity from the previous authentication. If the user identities do not match, an error is returned.noEAI authentication proceeds without verifying the new user identity. Usage This stanza entry is optional. Default value no Example eai-verify-user-identity = yes [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-verify-user-identity

Use the eai-verify-user-identity stanza entry to control whether the user identity is verified during reauthentication. EAI applications can reauthenticate a user by returning new authentication information for a previously authenticated session. By default, WebSEAL does not ensure that the new user identity matches the user identity from the previous authentication.

Syntax

eai-verify-user-identity = {yes|no}

Description

During the EAI re-authentication process, this configuration entry determines whether the new user identity must match the user identity from the previous authentication.

Options

yes

During EAI authentication, the new user identity is compared with the user identity from the previous authentication. If the user identities do not match, an error is returned.

no

EAI authentication proceeds without verifying the new user identity.

Usage

This stanza entry is optional.

Default value

no

Example

eai-verify-user-identity = yes

Parent topic: [eai] stanza

eai-xattrs-headereai-xattrs-headerIBM Security Access Manager for Web WebSEAL eai-xattrs-header stanza entryUse the eai-xattrs-header stanza entry to specify the HTTP headers in the response from the external authentication interface (EAI) server that contain authentication data. WebSEAL uses these headers to add extended attributes to the credential.eai-xattrs-header stanza entryeai stanzaentrieseai-xattrs-headereai stanzaeai stanzaeai-xattrs-header entrySyntax eai-xattrs-header = header-name[,header-name...] Description Specifies a comma-delimited list of header names. WebSEAL examines the response for headers with the specified names and creates extended attributes using the name of the header as the attribute name and the value of the header as the attribute value. For example, if the following headers are returned in the HTTP response: am-eai-xattrs: creditcardexpiry, streetaddress creditcardexpiry: 090812 streetaddress: 555 homewood lane WebSEAL will: Examine the am-eai-xattrs header Detect two headers to look for in the responseFind those headers and their values Add the two specified attributes to the credential Options header-name[,header-name...]One or more (comma delimited) header names that are added to the credential as extended attributes. Usage This stanza entry is optional. Default value am-eai-xattrs Example eai-xattrs-header = am-eai-xattrs [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

eai-xattrs-header

Use the eai-xattrs-header stanza entry to specify the HTTP headers in the response from the external authentication interface (EAI) server that contain authentication data. WebSEAL uses these headers to add extended attributes to the credential.

Syntax

eai-xattrs-header = header-name[,header-name...]

Description

Specifies a comma-delimited list of header names. WebSEAL examines the response for headers with the specified names and creates extended attributes using the name of the header as the attribute name and the value of the header as the attribute value.

For example, if the following headers are returned in the HTTP response:

 am-eai-xattrs: creditcardexpiry, streetaddress
 creditcardexpiry: 090812
 streetaddress: 555 homewood lane

WebSEAL will:

Examine the am-eai-xattrs header

Detect two headers to look for in the response

Find those headers and their values

Add the two specified attributes to the credential

Options

header-name[,header-name...]

One or more (comma delimited) header names that are added to the credential as extended attributes.

Usage

This stanza entry is optional.

Default value

am-eai-xattrs

Example

eai-xattrs-header = am-eai-xattrs

Parent topic: [eai] stanza

retain-eai-sessionretain-eai-sessionretain-eai-session stanza entryeai stanzaentriesretain-eai-sessioneai stanzaeai stanzaretain-eai-session entrySyntax retain-eai-session = {yes|no} Description Specifies whether the existing session and session cache entry for a client are retained or replaced when an already-authenticated EAI client authenticates through an EAI a second time. Options yesIf an already-authenticated EAI client authenticates through an EAI a second time, the existing session and session cache entry for the client are retained, and the new credential is stored in the existing cache entry.noIf an already-authenticated EAI client authenticates through an EAI a second time, the existing session and session cache entry for the client are completely replaced and the new credential is stored in the new cache entry. Usage This stanza entry is required. Default value no Example retain-eai-session = no [eai] stanzaUse the [eai] stanza to configure the external authentication interface (EAI).

retain-eai-session

Syntax

retain-eai-session = {yes|no}

Description

Specifies whether the existing session and session cache entry for a client are retained or replaced when an already-authenticated EAI client authenticates through an EAI a second time.

Options

yes

If an already-authenticated EAI client authenticates through an EAI a second time, the existing session and session cache entry for the client are retained, and the new credential is stored in the existing cache entry.

no

If an already-authenticated EAI client authenticates through an EAI a second time, the existing session and session cache entry for the client are completely replaced and the new credential is stored in the new cache entry.

Usage

This stanza entry is required.

Default value

no

Example

retain-eai-session = no

Parent topic: [eai] stanza

[eai-trigger-urls] stanza[eai-trigger-urls] stanzaIBM Security Access Manager for Web WebSEAL [eai-trigger-urls] stanzaUse the [eai-trigger-urls] stanza to specify trigger URL strings for the external authentication interface (EAI). When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.eai-trigger-urls stanzastanzaseai-trigger-urlsStanza referencetriggerUse this trigger stanza entry to specify trigger URL strings for standard WebSEAL junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data. triggerUse this trigger stanza entry to specify trigger URL strings for virtual host junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data.

[eai-trigger-urls] stanza

Use the [eai-trigger-urls] stanza to specify trigger URL strings for the external authentication interface (EAI). When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.

trigger
Use this trigger stanza entry to specify trigger URL strings for standard WebSEAL junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data.

trigger
Use this trigger stanza entry to specify trigger URL strings for virtual host junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data.

Parent topic: Stanza reference

triggertriggerUse this trigger stanza entry to specify trigger URL strings for standard WebSEAL junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data. trigger stanza entryeai-trigger-urls stanzaentriestriggereai-trigger-urls stanzaeai-trigger-urls stanzatrigger entrySyntax trigger = url-pattern Description Format for standard WebSEAL junctions. Specifies the trigger URL that causes WebSEAL to set a special flag on the request. Responses to this request also contain the flag, which causes WebSEAL to intercept and examine the response for authentication data in special HTTP headers. Options url-patternThe trigger URL (format for standard WebSEAL junctions) that causes WebSEAL to set a special flag on the request. This url-pattern is a case-sensitive pattern that can include wildcard characters. Usage There must be at least one entry when eai-auth is not none. Default value None. Example trigger = /jct/cgi-bin/eaitest/* [eai-trigger-urls] stanzaUse the [eai-trigger-urls] stanza to specify trigger URL strings for the external authentication interface (EAI). When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.

trigger

Use this trigger stanza entry to specify trigger URL strings for standard WebSEAL junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data.

Syntax

trigger = url-pattern

Description

Format for standard WebSEAL junctions. Specifies the trigger URL that causes WebSEAL to set a special flag on the request. Responses to this request also contain the flag, which causes WebSEAL to intercept and examine the response for authentication data in special HTTP headers.

Options

url-pattern

The trigger URL (format for standard WebSEAL junctions) that causes WebSEAL to set a special flag on the request.

This url-pattern is a case-sensitive pattern that can include wildcard characters.

Usage

There must be at least one entry when eai-auth is not none.

Default value

None.

Example

trigger = /jct/cgi-bin/eaitest/*

Parent topic: [eai-trigger-urls] stanza

triggertriggerUse this trigger stanza entry to specify trigger URL strings for virtual host junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data. trigger stanza entryeai-trigger-urls stanzaentriestriggereai-trigger-urls stanzaeai-trigger-urls stanzatrigger entrySyntax trigger = http[s]://virtual-host-name[:port_number]/url-pattern Description Format for virtual host junctions. Specifies the trigger URL that causes WebSEAL to set a special flag on the request. Responses to this request also contain the flag, which causes WebSEAL to intercept and examine the response for authentication data in special HTTP headers. For virtual host junctions to match a trigger, they must use the same protocol and the same virtual-host-name and port number as the trigger. Options http[s]://virtual-host-name[:port_number]/url-patternThe trigger URL (format for virtual host junctions) that causes WebSEAL to set a special flag on the request. The url-pattern is case-sensitive. The rest of the trigger is not case-sensitive. Usage There must be at least one entry when eai-auth is not none. Default value None. Example trigger = https://vhost1.example.com:4344/jct/cgi-bin/eaitest/* [eai-trigger-urls] stanzaUse the [eai-trigger-urls] stanza to specify trigger URL strings for the external authentication interface (EAI). When WebSEAL detects the trigger URL in a request, it intercepts the corresponding response and examines it for authentication data in special HTTP headers.

trigger

Use this trigger stanza entry to specify trigger URL strings for virtual host junctions. WebSEAL examines each server response to these trigger URLs to determine whether the response contains authentication data.

Syntax

trigger = http[s]://virtual-host-name[:port_number]/url-pattern

Description

Format for virtual host junctions. Specifies the trigger URL that causes WebSEAL to set a special flag on the request. Responses to this request also contain the flag, which causes WebSEAL to intercept and examine the response for authentication data in special HTTP headers.

For virtual host junctions to match a trigger, they must use the same protocol and the same virtual-host-name and port number as the trigger.

Options

http[s]://virtual-host-name[:port_number]/url-pattern

The trigger URL (format for virtual host junctions) that causes WebSEAL to set a special flag on the request.

Note: The url-pattern is case-sensitive. The rest of the trigger is not case-sensitive.

Usage

There must be at least one entry when eai-auth is not none.

Default value

None.

Example

trigger = https://vhost1.example.com:4344/jct/cgi-bin/eaitest/*

Parent topic: [eai-trigger-urls] stanza

[e-community-domains] stanza[e-community-domains] stanzaIBM Security Access Manager for Web WebSEAL [e-community-domains] stanzaUse the [e-community-domains] stanza to list the e-community cookie domains that are used by virtual host junctions.e-community-domains stanzastanzase-community-domainsStanza referencename

[e-community-domains] stanza

Use the [e-community-domains] stanza to list the e-community cookie domains that are used by virtual host junctions.

name

Parent topic: Stanza reference

namenamename stanza entrye-community-domains stanzaentriesnamee-community-domains stanzae-community-domains stanzaname entrySyntax name = domainDescription The e-community cookie domains used by virtual host junctions. The domain used by a particular virtual host junction is chosen by finding the longest domain in the table that matches the virtual host name. Each of these domains must also have a corresponding table of keys defined by creating a stanza of the format [e-community-domain-keys:domain].Options domainThe e-community cookie domain used by virtual host junctions.Usage This stanza entry is optional.Default value None.Example name = www.example.com[e-community-domains] stanzaUse the [e-community-domains] stanza to list the e-community cookie domains that are used by virtual host junctions.

name

Syntax

name = domain

Description

The e-community cookie domains used by virtual host junctions. The domain used by a particular virtual host junction is chosen by finding the longest domain in the table that matches the virtual host name. Each of these domains must also have a corresponding table of keys defined by creating a stanza of the format [e-community-domain-keys:domain].

Options

domain

The e-community cookie domain used by virtual host junctions.

Usage

This stanza entry is optional.

Default value

None.

Example

name = www.example.com

Parent topic: [e-community-domains] stanza

[e-community-domain-keys] stanza[e-community-domain-keys] stanzaIBM Security Access Manager for Web WebSEAL [e-community-domain-keys] stanzaUse the [e-community-domain-keys] stanza to list the key files that WebSEAL can use to encrypt and decrypt the tokens that are sent between the servers in the e-community.e-community-domain-keys stanzastanzase-community-domain-keysStanza referencedomain_nameUse the domain_name entry in the [e-community-domain-keys] stanza to specify the keys for domains that are participating in the e-community.

[e-community-domain-keys] stanza

Use the [e-community-domain-keys] stanza to list the key files that WebSEAL can use to encrypt and decrypt the tokens that are sent between the servers in the e-community.

domain_name
Use the domain_name entry in the [e-community-domain-keys] stanza to specify the keys for domains that are participating in the e-community.

Parent topic: Stanza reference

domain_namedomain_nameIBM Security Access Manager for Web WebSEAL domain_name stanza entryUse the domain_name entry in the [e-community-domain-keys] stanza to specify the keys for domains that are participating in the e-community.domain_name stanza entrye-community-domain-keys stanzaentriesdomain_namee-community-domain-keys stanzae-community-domain-keys stanzadomain_name entrySyntax domain_name = key_file Description File names for keys for any domains that are participating in the e-community. This includes the domain in which the WebSEAL server is running. These are shared on a pair-wise-by-domain basis. Options domain_nameA domain that is participating in the e-community.key_fileFile name for key for any domain that is participating in the e-community. Usage This stanza entry is optional. Default value None. Example ecssoserver.subnet.example.com = ecsso.key [e-community-domain-keys] stanzaUse the [e-community-domain-keys] stanza to list the key files that WebSEAL can use to encrypt and decrypt the tokens that are sent between the servers in the e-community.

domain_name

Use the domain_name entry in the [e-community-domain-keys] stanza to specify the keys for domains that are participating in the e-community.

Syntax

domain_name = key_file

Description

File names for keys for any domains that are participating in the e-community. This includes the domain in which the WebSEAL server is running. These are shared on a pair-wise-by-domain basis.

Options

domain_name

A domain that is participating in the e-community.

key_file

File name for key for any domain that is participating in the e-community.

Usage

This stanza entry is optional.

Default value

None.

Example

ecssoserver.subnet.example.com = ecsso.key

Parent topic: [e-community-domain-keys] stanza

[e-community-domain-keys:domain] stanza[e-community-domain-keys:domain] stanzaIBM Security Access Manager for Web WebSEAL [e-community-domain-keys:domain] stanzaUse the [e-community-domain-keys:domain] stanza to specify the appropriate keys for each domain that is defined in the [e-community-domains] stanza.e-community-domain-keys:domain stanzastanzase-community-domain-keys:domainStanza referencedomain_nameUse the domain_name entry in the [e-community-domain-keys:domain] stanza to specify the keys for the domains that are participating in the e-community.

[e-community-domain-keys:domain] stanza

Use the [e-community-domain-keys:domain] stanza to specify the appropriate keys for each domain that is defined in the [e-community-domains] stanza.

domain_name
Use the domain_name entry in the [e-community-domain-keys:domain] stanza to specify the keys for the domains that are participating in the e-community.

Parent topic: Stanza reference

domain_namedomain_nameIBM Security Access Manager for Web WebSEAL domain_name stanza entryUse the domain_name entry in the [e-community-domain-keys:domain] stanza to specify the keys for the domains that are participating in the e-community. domain_name stanza entrye-community-domain-keys:domain stanzaentriesdomain_namee-community-domain-keys:domain stanzae-community-domain-keys:domain stanzadomain_name entrySyntax domain_name = key_file Description Keys for any domains that are participating in the e-community, including the domain in which the virtual host junction is running. These are shared on a pair-wise-by-domain basis. Options domain_nameDomain that is participating in the e-community, including the domain in which the virtual host junction is running.key_fileKey for any domain that is participating in the e-community, including the domain in which the virtual host junction is running. Usage This stanza entry is optional. Default value None. Example [e-community-domain-keys:www.example.com] ecssoserver.subnet.example.com = ecsso.key [e-community-domain-keys:domain] stanzaUse the [e-community-domain-keys:domain] stanza to specify the appropriate keys for each domain that is defined in the [e-community-domains] stanza.

domain_name

Use the domain_name entry in the [e-community-domain-keys:domain] stanza to specify the keys for the domains that are participating in the e-community.

Syntax

domain_name = key_file

Description

Keys for any domains that are participating in the e-community, including the domain in which the virtual host junction is running. These are shared on a pair-wise-by-domain basis.

Options

domain_name

Domain that is participating in the e-community, including the domain in which the virtual host junction is running.

key_file

Key for any domain that is participating in the e-community, including the domain in which the virtual host junction is running.

Usage

This stanza entry is optional.

Default value

None.

Example

[e-community-domain-keys:www.example.com]
ecssoserver.subnet.example.com = ecsso.key

Parent topic: [e-community-domain-keys:domain] stanza

[e-community-sso] stanza[e-community-sso] stanzaIBM Security Access Manager for Web WebSEAL [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on. e-community-sso stanzastanzase-community-ssoStanza referencecache-requests-for-ecssoUse the cache-requests-for-ecsso stanza entry to control whether WebSEAL caches request data from an unauthenticated request while the e-community master authentication server authenticates the user.e-community-nameUse the e-community-name stanza entry to specify the unifying name of the e-community for all participating servers across the participating domains. disable-ec-cookieUse the disable-ec-cookie stanza entry to control whether WebSEAL can use the e-community-cookie in an e-Community Single Sign-On (eCSSO) environment. You can use this entry to limit the ability to generate vouch-for tokens to the Master Authentication Server (MAS) only.e-community-sso-authUse the e-community-sso-auth stanza entry to enable the e-community authentication method and specify the type of communication that is used by e-community participants.ec-cookie-domainUse the ec-cookie-domain stanza entry to specify the domain for WebSEAL to include in the e-community cookie in an e-community single sign-on (eCSSO) environment.ec-cookie-lifetimeUse the ec-cookie-lifetime stanza entry to specify the lifetime, in minutes, of an e-community cookie.ecsso-allow-unauthUse the ecsso-allow-unauth stanza entry to control whether unauthenticated users can access unprotected resources on e-community SSO participating servers. When authenticated users are granted unauthenticated access, the participating server can serve the resource without requiring the user to authenticate through the master authentication server.ecsso-propagate-errorsUse the ecsso-propagate-errors stanza entry to control whether authentication errors that are returned by the master-authn-server in vouch-for tokens are propagated to the ERROR_CODE and ERROR_TEXT macros. handle-auth-failure-at-masis-master-authn-servermaster-authn-servermaster-http-portmaster-https-portpropagate-cdmf-errorsuse-utf8vf-argumentvf-token-lifetimevf-url

[e-community-sso] stanza

Use the [e-community-sso] stanza to configure e-community single sign-on.

cache-requests-for-ecsso
Use the cache-requests-for-ecsso stanza entry to control whether WebSEAL caches request data from an unauthenticated request while the e-community master authentication server authenticates the user.

e-community-name
Use the e-community-name stanza entry to specify the unifying name of the e-community for all participating servers across the participating domains.

disable-ec-cookie
Use the disable-ec-cookie stanza entry to control whether WebSEAL can use the e-community-cookie in an e-Community Single Sign-On (eCSSO) environment. You can use this entry to limit the ability to generate vouch-for tokens to the Master Authentication Server (MAS) only.

e-community-sso-auth
Use the e-community-sso-auth stanza entry to enable the e-community authentication method and specify the type of communication that is used by e-community participants.

ec-cookie-domain
Use the ec-cookie-domain stanza entry to specify the domain for WebSEAL to include in the e-community cookie in an e-community single sign-on (eCSSO) environment.

ec-cookie-lifetime
Use the ec-cookie-lifetime stanza entry to specify the lifetime, in minutes, of an e-community cookie.

ecsso-allow-unauth
Use the ecsso-allow-unauth stanza entry to control whether unauthenticated users can access unprotected resources on e-community SSO participating servers. When authenticated users are granted unauthenticated access, the participating server can serve the resource without requiring the user to authenticate through the master authentication server.

ecsso-propagate-errors
Use the ecsso-propagate-errors stanza entry to control whether authentication errors that are returned by the master-authn-server in vouch-for tokens are propagated to the ERROR_CODE and ERROR_TEXT macros.

handle-auth-failure-at-mas

is-master-authn-server

master-authn-server

master-http-port

master-https-port

propagate-cdmf-errors

use-utf8

vf-argument

vf-token-lifetime

vf-url

Parent topic: Stanza reference

cache-requests-for-ecssocache-requests-for-ecssoIBM Security Access Manager for Web WebSEAL cache-requests-for-ecsso stanza entryUse the cache-requests-for-ecsso stanza entry to control whether WebSEAL caches request data from an unauthenticated request while the e-community master authentication server authenticates the user.cache-requests-for-ecsso stanza entrye-community-sso stanzaentriescache-requests-for-ecssoe-community-sso stanzae-community-sso stanzacache-requests-for-ecsso entrySyntax cache-requests-for-ecsso = {yes|no} Description Specifies whether or not to cache request data from an unauthenticated request while the e-community master authentication server (MAS) authenticates the user. Options yesIf an unauthenticated request is made, the request data is cached while the e-community master authentication server (MAS) authenticates the user.noIf an unauthenticated request is made, the request data is not cached while the e-community master authentication server (MAS) authenticates the user. The original request data will be lost. Usage This stanza entry is required. Default value yes Example cache-requests-for-ecsso = yes [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

cache-requests-for-ecsso

Use the cache-requests-for-ecsso stanza entry to control whether WebSEAL caches request data from an unauthenticated request while the e-community master authentication server authenticates the user.

Syntax

cache-requests-for-ecsso = {yes|no}

Description

Specifies whether or not to cache request data from an unauthenticated request while the e-community master authentication server (MAS) authenticates the user.

Options

yes

If an unauthenticated request is made, the request data is cached while the e-community master authentication server (MAS) authenticates the user.

no

If an unauthenticated request is made, the request data is not cached while the e-community master authentication server (MAS) authenticates the user. The original request data will be lost.

Usage

This stanza entry is required.

Default value

yes

Example

cache-requests-for-ecsso = yes

Parent topic: [e-community-sso] stanza

e-community-namee-community-nameIBM Security Access Manager for Web WebSEAL e-community-name stanza entryUse the e-community-name stanza entry to specify the unifying name of the e-community for all participating servers across the participating domains. e-community-name stanza entrye-community-sso stanzaentriese-community-namee-community-sso stanzae-community-sso stanzae-community-name entrySyntax e-community-name = name Description String value that specifies an e-community name. When e-community single signon is supported, this name must match any vouch-for tokens or e-community cookies that are received. Options nameString value that specifies an e-community name. The string must not contain the equals sign ( = ) or ampersand ( & ). Usage This stanza entry is optional. Default value None. Example e-community-name = company1 [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

e-community-name

Use the e-community-name stanza entry to specify the unifying name of the e-community for all participating servers across the participating domains.

Syntax

e-community-name = name

Description

String value that specifies an e-community name. When e-community single signon is supported, this name must match any vouch-for tokens or e-community cookies that are received.

Options

name

String value that specifies an e-community name. The string must not contain the equals sign ( = ) or ampersand ( & ).

Usage

This stanza entry is optional.

Default value

None.

Example

e-community-name = company1

Parent topic: [e-community-sso] stanza

disable-ec-cookiedisable-ec-cookieIBM Security Access Manager for Web WebSEAL disable-ec-cookie stanza entryUse the disable-ec-cookie stanza entry to control whether WebSEAL can use the e-community-cookie in an e-Community Single Sign-On (eCSSO) environment. You can use this entry to limit the ability to generate vouch-for tokens to the Master Authentication Server (MAS) only.disable-ec-cookie stanza entrye-community-sso stanzaentriesdisable-ec-cookiee-community-sso stanzae-community-sso stanzadisable-ec-cookie entrySyntax disable-ec-cookie = {yes|no} Description Provides an option to override default eCSSO behavior and prohibit WebSEAL from using e-community-cookies. Options yesProhibits WebSEAL from using the e-community-cookie; only the MAS is permitted to generate vouch-for tokens.noThe default eCSSO behavior in WebSEAL is left unchanged. Usage This stanza entry is optional. Default value no Example disable-ec-cookie = no [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

disable-ec-cookie

Use the disable-ec-cookie stanza entry to control whether WebSEAL can use the e-community-cookie in an e-Community Single Sign-On (eCSSO) environment. You can use this entry to limit the ability to generate vouch-for tokens to the Master Authentication Server (MAS) only.

Syntax

disable-ec-cookie = {yes|no}

Description

Provides an option to override default eCSSO behavior and prohibit WebSEAL from using e-community-cookies.

Options

yes

Prohibits WebSEAL from using the e-community-cookie; only the MAS is permitted to generate vouch-for tokens.

no

The default eCSSO behavior in WebSEAL is left unchanged.

Usage

This stanza entry is optional.

Default value

no

Example

disable-ec-cookie = no

Parent topic: [e-community-sso] stanza

e-community-sso-authe-community-sso-authIBM Security Access Manager for Web WebSEAL e-community-sso-auth stanza entryUse the e-community-sso-auth stanza entry to enable the e-community authentication method and specify the type of communication that is used by e-community participants.e-community-sso-auth stanza entrye-community-sso stanzaentriese-community-sso-authe-community-sso stanzae-community-sso stanzae-community-sso-auth entrySyntax e-community-sso-auth = {none|http|https|both} Description Enables participation in e-community single signon. Options {none|http|https|both}Specifies which protocols are supported. The value both means both HTTP and HTTPS. Usage This stanza entry is required. Default value none Example e-community-sso-auth = none [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

e-community-sso-auth

Use the e-community-sso-auth stanza entry to enable the e-community authentication method and specify the type of communication that is used by e-community participants.

Syntax

e-community-sso-auth = {none|http|https|both}

Description

Enables participation in e-community single signon.

Options

{none|http|https|both}

Specifies which protocols are supported. The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

none

Example

e-community-sso-auth = none

Parent topic: [e-community-sso] stanza

ec-cookie-domainec-cookie-domainIBM Security Access Manager for Web WebSEAL ec-cookie-domain stanza entryUse the ec-cookie-domain stanza entry to specify the domain for WebSEAL to include in the e-community cookie in an e-community single sign-on (eCSSO) environment.ec-cookie-domain stanza entrye-community-sso stanzaentriesec-cookie-domaine-community-sso stanzae-community-sso stanzaec-cookie-domain entrySyntax ec-cookie-domain = domain Description If not set, WebSEAL uses the domain from the automatically determined host name (or web-host-name if specified). Options domainIf not set, WebSEAL uses the domain from the automatically determined host name (or web-host-name if specified). Usage If not set, WebSEAL uses the domain from the automatically determined host name (or web-host-name if specified). Default value None. Example ec-cookie-domain = www.example.com [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

ec-cookie-domain

Use the ec-cookie-domain stanza entry to specify the domain for WebSEAL to include in the e-community cookie in an e-community single sign-on (eCSSO) environment.

Syntax

ec-cookie-domain = domain

Description

If not set, WebSEAL uses the domain from the automatically determined host name (or web-host-name if specified).

Options

domain

If not set, WebSEAL uses the domain from the automatically determined host name (or web-host-name if specified).

Usage

If not set, WebSEAL uses the domain from the automatically determined host name (or web-host-name if specified).

Default value

None.

Example

ec-cookie-domain = www.example.com

Parent topic: [e-community-sso] stanza

ec-cookie-lifetimeec-cookie-lifetimeIBM Security Access Manager for Web WebSEAL ec-cookie-lifetime stanza entryUse the ec-cookie-lifetime stanza entry to specify the lifetime, in minutes, of an e-community cookie.ec-cookie-lifetime stanza entrye-community-sso stanzaentriesec-cookie-lifetimee-community-sso stanzae-community-sso stanzaec-cookie-lifetime entrySyntax ec-cookie-lifetime = number_of_minutes Description Positive integer value indicating the lifetime of an e-community cookie. Options number_of_minutesPositive integer value indicating the lifetime, in minutes, of an e-community cookie. Minimum value is 1. There is no maximum value. Usage This stanza entry is required. Default value 300 Example ec-cookie-lifetime = 300 [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

ec-cookie-lifetime

Use the ec-cookie-lifetime stanza entry to specify the lifetime, in minutes, of an e-community cookie.

Syntax

ec-cookie-lifetime = number_of_minutes

Description

Positive integer value indicating the lifetime of an e-community cookie.

Options

number_of_minutes

Positive integer value indicating the lifetime, in minutes, of an e-community cookie. Minimum value is 1. There is no maximum value.

Usage

This stanza entry is required.

Default value

300

Example

ec-cookie-lifetime = 300

Parent topic: [e-community-sso] stanza

ecsso-allow-unauthecsso-allow-unauthIBM Security Access Manager for Web WebSEAL ecsso-allow-unauth stanza entryUse the ecsso-allow-unauth stanza entry to control whether unauthenticated users can access unprotected resources on e-community SSO participating servers. When authenticated users are granted unauthenticated access, the participating server can serve the resource without requiring the user to authenticate through the master authentication server.ecsso-allow-unauth stanza entrye-community-sso stanzaentriesecsso-allow-unauthe-community-sso stanzae-community-sso stanzaecsso-allow-unauth entrySyntax ecsso-allow-unauth = {yes|no} Description Enables or disables unauthenticated access to unprotected resources on an e-community SSO slave server. Options yesThe value yes enables unauthenticated access.noThe value no disables access. For compatibility with versions of WebSEAL prior to version 5.1 set this value to no. Usage This stanza entry is required. Default value yes Example ecsso-allow-unauth = yes [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

ecsso-allow-unauth

Use the ecsso-allow-unauth stanza entry to control whether unauthenticated users can access unprotected resources on e-community SSO participating servers. When authenticated users are granted unauthenticated access, the participating server can serve the resource without requiring the user to authenticate through the master authentication server.

Syntax

ecsso-allow-unauth = {yes|no}

Description

Enables or disables unauthenticated access to unprotected resources on an e-community SSO slave server.

Options

yes

The value yes enables unauthenticated access.

no

The value no disables access. For compatibility with versions of WebSEAL prior to version 5.1 set this value to no.

Usage

This stanza entry is required.

Default value

yes

Example

ecsso-allow-unauth = yes

Parent topic: [e-community-sso] stanza

ecsso-propagate-errorsecsso-propagate-errorsIBM Security Access Manager for Web WebSEAL ecsso-propagate-errors stanza entryUse the ecsso-propagate-errors stanza entry to control whether authentication errors that are returned by the master-authn-server in vouch-for tokens are propagated to the ERROR_CODE and ERROR_TEXT macros. ecsso-propagate-errors stanza entrye-community-sso stanzaentriesecsso-propagate-errorse-community-sso stanzae-community-sso stanzaecsso-propagate-errors entrySyntax ecsso-propagate-errors = {yes|no} Description Specifies whether authentication errors returned by the master-authn-server in vouch-for tokens are propagated to the ERROR_CODE and ERROR_TEXT macros used by facilities such as local response redirect. Options yesAuthentication errors are propagated to ERROR_CODE and ERROR_TEXT macros.noAuthentication errors are not propagated to ERROR_CODE and ERROR_TEXT macros. Usage This stanza entry is required. Default value no Example ecsso-propagate-errors = no [e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

ecsso-propagate-errors

Use the ecsso-propagate-errors stanza entry to control whether authentication errors that are returned by the master-authn-server in vouch-for tokens are propagated to the ERROR_CODE and ERROR_TEXT macros.

Syntax

ecsso-propagate-errors = {yes|no}

Description

Specifies whether authentication errors returned by the master-authn-server in vouch-for tokens are propagated to the ERROR_CODE and ERROR_TEXT macros used by facilities such as local response redirect.

Options

yes

Authentication errors are propagated to ERROR_CODE and ERROR_TEXT macros.

no

Authentication errors are not propagated to ERROR_CODE and ERROR_TEXT macros.

Usage

This stanza entry is required.

Default value

no

Example

ecsso-propagate-errors = no

Parent topic: [e-community-sso] stanza

handle-auth-failure-at-mashandle-auth-failure-at-mashandle-auth-failure-at-mas stanza entrye-community-sso stanzaentrieshandle-auth-failure-at-mase-community-sso stanzae-community-sso stanzahandle-auth-failure-at-mas entrySyntax handle-auth-failure-at-mas = {yes|no}Description Provides an option to override default eCSSO behavior and allow the MAS to handle login failures without redirecting the Web browser back to the requesting host.Options yesEnables the MAS to handle login failures directly without redirecting the Web browser back to the requesting host.noThe default eCSSO behavior in WebSEAL is left unchanged. On a login failure, the MAS will generate a vouch-for token and redirect the Web browser back to the requesting host.Usage This stanza entry is optional.Default value noExample handle-auth-failure-at-mas = no[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

handle-auth-failure-at-mas

Syntax

handle-auth-failure-at-mas = {yes|no}

Description

Provides an option to override default eCSSO behavior and allow the MAS to handle login failures without redirecting the Web browser back to the requesting host.

Options

yes

Enables the MAS to handle login failures directly without redirecting the Web browser back to the requesting host.

no

The default eCSSO behavior in WebSEAL is left unchanged. On a login failure, the MAS will generate a vouch-for token and redirect the Web browser back to the requesting host.

Usage

This stanza entry is optional.

Default value

no

Example

handle-auth-failure-at-mas = no

Parent topic: [e-community-sso] stanza

is-master-authn-serveris-master-authn-serveris-master-authn-server stanza entrye-community-sso stanzaentriesis-master-authn-servere-community-sso stanzae-community-sso stanzais-master-authn-server entrySyntax is-master-authn-server = {yes|no}Description Specifies whether this WebSEAL server accepts vouch-for requests from other WebSEAL instances. The WebSEAL instances must have domain keys listed in the [e-community-domain-keys] stanza. Options yesThis WebSEAL server accepts vouch-for requests from other WebSEAL instances. When this value is yes, this WebSEAL server is the master authentication server.noThis WebSEAL server does not accept vouch-for requests from other WebSEAL instances. Usage This stanza entry is optional.Default value None.Example is-master-authn-server = no[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

is-master-authn-server

Syntax

is-master-authn-server = {yes|no}

Description

Specifies whether this WebSEAL server accepts vouch-for requests from other WebSEAL instances. The WebSEAL instances must have domain keys listed in the [e-community-domain-keys] stanza.

Options

yes

This WebSEAL server accepts vouch-for requests from other WebSEAL instances. When this value is yes, this WebSEAL server is the master authentication server.

no

This WebSEAL server does not accept vouch-for requests from other WebSEAL instances.

Usage

This stanza entry is optional.

Default value

None.

Example

is-master-authn-server = no

Parent topic: [e-community-sso] stanza

master-authn-servermaster-authn-servermaster-authn-server stanza entrye-community-sso stanzaentriesmaster-authn-servere-community-sso stanzae-community-sso stanzamaster-authn-server entrySyntax master-authn-server = fully_qualified_hostnameDescription Location of the master authentication server. This value must be specified when is-master-authn-server is set to no. If a local domain login has not been performed then authentication attempts are routed through the master machine. The master machine will vouch for the user identity. The domain key for the master-authn-server needs to be listed in the [e-community-domain-keys] stanza.Options fully_qualified_hostnameLocation of the master authentication server. Usage This stanza entry is optional.Default value None.Example master-authn-server = diamond.dev.example.com[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

master-authn-server

Syntax

master-authn-server = fully_qualified_hostname

Description

Location of the master authentication server. This value must be specified when is-master-authn-server is set to no. If a local domain login has not been performed then authentication attempts are routed through the master machine. The master machine will vouch for the user identity. The domain key for the master-authn-server needs to be listed in the [e-community-domain-keys] stanza.

Options

fully_qualified_hostname

Location of the master authentication server.

Usage

This stanza entry is optional.

Default value

None.

Example

master-authn-server = diamond.dev.example.com

Parent topic: [e-community-sso] stanza

master-http-portmaster-http-portmaster-http-port stanza entrye-community-sso stanzaentriesmaster-http-porte-community-sso stanzae-community-sso stanzamaster-http-port entrySyntax master-http-port = port_numberDescription Integer value specifying the port number on which the master-authn-server listens for HTTP request. The setting is necessary when e-community-sso-auth permits use of the HTTP protocol, and the master-authn-server listens for HTTP requests on a port other than the standard HTTP port (port 80). This stanza entry is ignored if this WebSEAL server is the master authentication server.Options port_numberInteger value specifying the port number on which the master-authn-server listens for HTTP request.Usage This stanza entry is optional.Default value None.Example master-http-port = 81[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

master-http-port

Syntax

master-http-port = port_number

Description

Integer value specifying the port number on which the master-authn-server listens for HTTP request. The setting is necessary when e-community-sso-auth permits use of the HTTP protocol, and the master-authn-server listens for HTTP requests on a port other than the standard HTTP port (port 80). This stanza entry is ignored if this WebSEAL server is the master authentication server.

Options

port_number

Integer value specifying the port number on which the master-authn-server listens for HTTP request.

Usage

This stanza entry is optional.

Default value

None.

Example

master-http-port = 81

Parent topic: [e-community-sso] stanza

master-https-portmaster-https-portmaster-https-port stanza entrye-community-sso stanzaentriesmaster-https-porte-community-sso stanzae-community-sso stanzamaster-https-port entrySyntax master-https-port = port_numberDescription Integer value specifying the port number on which the master-authn-server listens for HTTPS requests. The setting is necessary when e-community-sso-auth permits use of the HTTPS protocol, and the master-authn-server listens for HTTPS requests on a port other than the standard HTTPS port (port 443). This stanza entry is ignored if this WebSEAL server is the master authentication server.Options port_numberInteger value specifying the port number on which the master-authn-server listens for HTTPS requests.Usage This stanza entry is optional.Default value None.Example master-https-port = 444[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

master-https-port

Syntax

master-https-port = port_number

Description

Integer value specifying the port number on which the master-authn-server listens for HTTPS requests. The setting is necessary when e-community-sso-auth permits use of the HTTPS protocol, and the master-authn-server listens for HTTPS requests on a port other than the standard HTTPS port (port 443). This stanza entry is ignored if this WebSEAL server is the master authentication server.

Options

port_number

Integer value specifying the port number on which the master-authn-server listens for HTTPS requests.

Usage

This stanza entry is optional.

Default value

None.

Example

master-https-port = 444

Parent topic: [e-community-sso] stanza

propagate-cdmf-errorspropagate-cdmf-errorspropagate-cdmf-errors stanza entrye-community-sso stanzaentriespropagate-cdmf-errorse-community-sso stanzae-community-sso stanzapropagate-cdmf-errors entrySyntax propagate-cdmf-errors = {yes|no}Description Controls subsequent behavior of the token creation process when the cdmf_get_usr_attributes call fails to obtain the required extended attribute information and returns an error.Options yesA "yes" value forces the token creation process to abort when CDMF fails to obtain attributes and returns an error.noA "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error.Usage This stanza entry is required.Default value noExample propagate-cdmf-errors = no[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

propagate-cdmf-errors

Syntax

propagate-cdmf-errors = {yes|no}

Description

Controls subsequent behavior of the token creation process when the cdmf_get_usr_attributes call fails to obtain the required extended attribute information and returns an error.

Options

yes

A "yes" value forces the token creation process to abort when CDMF fails to obtain attributes and returns an error.

no

A "no" value (default) allows the token creation process to proceed even when CDMF fails to obtain attributes and returns an error.

Usage

This stanza entry is required.

Default value

no

Example

propagate-cdmf-errors = no

Parent topic: [e-community-sso] stanza

use-utf8use-utf8use-utf8 stanza entrye-community-sso stanzaentriesuse-utf8e-community-sso stanzae-community-sso stanzause-utf8 entrySyntax use-utf8 = {yes|no}Description Use UTF–8 encoding for tokens used in e-community single signon. Options yesBeginning with version 5.1, WebSEAL servers use UTF-8 encoding by default. When this stanza entry is set to yes, tokens can be exchanged with other WebSEAL servers that use UTF-8 encoding. This enables tokens to used across different code pages (such as for a different language).noFor backward compatibility with tokens created by WebSEAL servers from version prior to 5.1, set this stanza entry to no.Usage This stanza entry is required.Default value yesExample use-utf8 = yes[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

use-utf8

Syntax

use-utf8 = {yes|no}

Description

Use UTF–8 encoding for tokens used in e-community single signon.

Options

yes

Beginning with version 5.1, WebSEAL servers use UTF-8 encoding by default. When this stanza entry is set to yes, tokens can be exchanged with other WebSEAL servers that use UTF-8 encoding. This enables tokens to used across different code pages (such as for a different language).

no

For backward compatibility with tokens created by WebSEAL servers from version prior to 5.1, set this stanza entry to no.

Usage

This stanza entry is required.

Default value

yes

Example

use-utf8 = yes

Parent topic: [e-community-sso] stanza

vf-argumentvf-argumentvf-argument stanza entrye-community-sso stanzaentriesvf-argumente-community-sso stanzae-community-sso stanzavf-argument entrySyntax vf-argument = vouch-for_token_nameDescription String value containing the name of the vouch-for token contained in a vouch-for reply. This is used to construct the vouch-for replies by the master authentication server, and to distinguish incoming requests as ones with vouch-for information by participating e-community single signon servers.Options vouch-for_token_nameValid characters for the string are ASCII characters except for ampersand ( & ), equals sign ( = ), and question mark ( ? ).Usage This stanza entry is optional.Default value PD-VFExample vf-argument = PD-VF[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

vf-argument

Syntax

vf-argument = vouch-for_token_name

Description

String value containing the name of the vouch-for token contained in a vouch-for reply. This is used to construct the vouch-for replies by the master authentication server, and to distinguish incoming requests as ones with vouch-for information by participating e-community single signon servers.

Options

vouch-for_token_name

Valid characters for the string are ASCII characters except for ampersand ( & ), equals sign ( = ), and question mark ( ? ).

Usage

This stanza entry is optional.

Default value

PD-VF

Example

vf-argument = PD-VF

Parent topic: [e-community-sso] stanza

vf-token-lifetimevf-token-lifetimevf-token-lifetime stanza entrye-community-sso stanzaentriesvf-token-lifetimee-community-sso stanzae-community-sso stanzavf-token-lifetime entrySyntax vf-token-lifetime = number_of_secondsDescription Positive integer indicating the lifetime, in seconds, of the vouch-for token. This is set to account for clock skew between participant servers.Options number_of_secondsPositive integer indicating the lifetime, in seconds, of the vouch-for token. The minimum value is 1 second. There is no maximum value. Usage This stanza entry is optional.Default value 180Example vf-token-lifetime = 180[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

vf-token-lifetime

Syntax

vf-token-lifetime = number_of_seconds

Description

Positive integer indicating the lifetime, in seconds, of the vouch-for token. This is set to account for clock skew between participant servers.

Options

number_of_seconds

Positive integer indicating the lifetime, in seconds, of the vouch-for token. The minimum value is 1 second. There is no maximum value.

Usage

This stanza entry is optional.

Default value

180

Example

vf-token-lifetime = 180

Parent topic: [e-community-sso] stanza

vf-urlvf-urlvf-url stanza entrye-community-sso stanzaentriesvf-urle-community-sso stanzae-community-sso stanzavf-url entrySyntax vf-url = URL_designationDescription Designator for vouch-for URL. This specifies the start of a URL relative to the server root. This is used to construct vouch-for requests for participating e-community single signon servers, and to distinguish requests for vouch-for information from other requests by the master authentication server.Options URL_designationThe URL_designation string can contain alphanumeric characters and the following special characters: dollar sign ( $ ), hyphen ( - ), underscore ( _ ), period ( . ), plus sign ( + ), exclamation point ( ! ), asterisk ( * ), single quote ( ' ), parentheses " ( ) " and comma ( , ). Questions marks ( ? ) are not allowed.Usage This stanza entry is optional.Default value When the stanza entry is not present in the configuration file, the default value is /pkmsvouchfor.Example vf-url = /pkmsvouchfor[e-community-sso] stanzaUse the [e-community-sso] stanza to configure e-community single sign-on.

vf-url

Syntax

vf-url = URL_designation

Description

Designator for vouch-for URL. This specifies the start of a URL relative to the server root. This is used to construct vouch-for requests for participating e-community single signon servers, and to distinguish requests for vouch-for information from other requests by the master authentication server.

Options

URL_designation

The URL_designation string can contain alphanumeric characters and the following special characters: dollar sign ( $ ), hyphen ( - ), underscore ( _ ), period ( . ), plus sign ( + ), exclamation point ( ! ), asterisk ( * ), single quote ( ' ), parentheses " ( ) " and comma ( , ). Questions marks ( ? ) are not allowed.

Usage

This stanza entry is optional.

Default value

When the stanza entry is not present in the configuration file, the default value is /pkmsvouchfor.

Example

vf-url = /pkmsvouchfor

Parent topic: [e-community-sso] stanza

[ecsso-incoming-attributes] stanza[ecsso-incoming-attributes] stanzaIBM Security Access Manager for Web WebSEAL [ecsso-incoming-attributes] stanzaUse the [ecsso-incoming-attributes] stanza to specify how the token consume module handles extended attributes in the e-community single sign-on token. The attributes can either be extracted or ignored.ecsso-incoming-attributes stanzastanzasecsso-incoming-attributesStanza referenceattribute_patternUse the attribute_pattern stanza entry to specify whether attributes are preserved or refreshed during an eCSSO authentication operation.

[ecsso-incoming-attributes] stanza

Use the [ecsso-incoming-attributes] stanza to specify how the token consume module handles extended attributes in the e-community single sign-on token. The attributes can either be extracted or ignored.

attribute_pattern
Use the attribute_pattern stanza entry to specify whether attributes are preserved or refreshed during an eCSSO authentication operation.

Parent topic: Stanza reference

attribute_patternattribute_patternIBM Security Access Manager for Web WebSEAL attribute_pattern stanza entryUse the attribute_pattern stanza entry to specify whether attributes are preserved or refreshed during an eCSSO authentication operation.attribute_pattern stanza entryecsso-incoming-attributes stanzaentriesattribute_patternecsso-incoming-attributes stanzaecsso-incoming-attributes stanzaattribute_pattern entrySyntax attribute_pattern = {preserve|refresh} Description Extended attributes to extract from incoming eCSSO authentication tokens. The attributes typically match those attributes declared in the [cdsso-token-attributes] stanza for the WebSEAL server in the source domain. The attribute_pattern can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters (*, [], ^, \,?). The order of attribute_pattern entries is important. The first entry that matches the attribute is used. Other entries are ignored. Options preserveAttributes in eCSSO vouch-for tokens that match a "preserve" entry, or matching none of the entires, are kept. If no entries are configured, then all attributes are kept.refreshAttributes in eCSSO vouch-for tokens that match a "refresh" entry are removed from the token. WebSEAL removes these attributes before the CDMF library is called to map the remote user into the local domain. Usage This stanza entry is optional. Default value None. Example my_cred_attr1 = preserve [ecsso-incoming-attributes] stanzaUse the [ecsso-incoming-attributes] stanza to specify how the token consume module handles extended attributes in the e-community single sign-on token. The attributes can either be extracted or ignored.

attribute_pattern

Use the attribute_pattern stanza entry to specify whether attributes are preserved or refreshed during an eCSSO authentication operation.

Syntax

attribute_pattern = {preserve|refresh}

Description

Extended attributes to extract from incoming eCSSO authentication tokens.

The attributes typically match those attributes declared in the [cdsso-token-attributes] stanza for the WebSEAL server in the source domain.

The attribute_pattern can be either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters (*, [], ^, \,?).

The order of attribute_pattern entries is important. The first entry that matches the attribute is used. Other entries are ignored.

Options

preserve

Attributes in eCSSO vouch-for tokens that match a "preserve" entry, or matching none of the entires, are kept. If no entries are configured, then all attributes are kept.

refresh

Attributes in eCSSO vouch-for tokens that match a "refresh" entry are removed from the token. WebSEAL removes these attributes before the CDMF library is called to map the remote user into the local domain.

Usage

This stanza entry is optional.

Default value

None.

Example

my_cred_attr1 = preserve

Parent topic: [ecsso-incoming-attributes] stanza

[ecsso-token-attributes] stanza[ecsso-token-attributes] stanzaIBM Security Access Manager for Web WebSEAL [ecsso-token-attributes] stanzaUse the [ecsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that WebSEAL adds to an extended attribute list when it creates a user credential.ecsso-token-attributes stanzastanzasecsso-token-attributesStanza reference<default>Use the <default> entry in the [ecsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in eCSSO authentication tokens.domain_nameUse the domain_name stanza entry in the ecsso-token-attributes stanza to specify the credential attributes that WebSEAL includes in eCSSO authentication tokens.

[ecsso-token-attributes] stanza

Use the [ecsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that WebSEAL adds to an extended attribute list when it creates a user credential.

<default>
Use the <default> entry in the [ecsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in eCSSO authentication tokens.

domain_name
Use the domain_name stanza entry in the ecsso-token-attributes stanza to specify the credential attributes that WebSEAL includes in eCSSO authentication tokens.

Parent topic: Stanza reference

<default><default>IBM Security Access Manager for Web WebSEAL <default> stanza entryUse the <default> entry in the [ecsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in eCSSO authentication tokens.stanza entryentriesecsso-token-attributes stanzaentryentriesecsso-token-attributes stanzaecsso-token-attributes stanzaSyntax <default> = pattern1 [<default> = pattern2] ... [<default> = patternN] Description Credential attributes to include in eCSSO authentication tokens. When WebSEAL cannot find a domain_name entry to match the domain, the entries in "<default>" are used. The word <default> is a key word and must not be modified. Options patternThe pattern can either be a specific value or a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?). Usage This stanza entry is optional. Default value None. Example <default> = my_cdas_attr_* [ecsso-token-attributes] stanzaUse the [ecsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that WebSEAL adds to an extended attribute list when it creates a user credential.

<default>

Use the <default> entry in the [ecsso-token-attributes] stanza to specify the credential attributes for WebSEAL to include in eCSSO authentication tokens.

Syntax

<default> = pattern1
[<default> = pattern2]
...
[<default> = patternN]

Description

Credential attributes to include in eCSSO authentication tokens. When WebSEAL cannot find a domain_name entry to match the domain, the entries in "<default>" are used. The word <default> is a key word and must not be modified.

Options

pattern

The pattern can either be a specific value or a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?).

Usage

This stanza entry is optional.

Default value

None.

Example

<default> = my_cdas_attr_*

Parent topic: [ecsso-token-attributes] stanza

domain_namedomain_nameIBM Security Access Manager for Web WebSEAL domain_name stanza entryUse the domain_name stanza entry in the ecsso-token-attributes stanza to specify the credential attributes that WebSEAL includes in eCSSO authentication tokens.domain_name stanza entryecsso-token-attributes stanzaentriesdomain_nameecsso-token-attributes stanzaecsso-token-attributes stanzadomain_name entrySyntax domain_name = pattern1 [domain_name = pattern2] ... [domain_name = patternN] Description Credential attributes to include in eCSSO authentication tokens. Options domain_nameThe domain_name specifies the destination domain containing the server that will consume the token. patternThe pattern for each entry can either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?). Usage This stanza entry is optional. Default value None. Example example1.com = my_cdas_attr_* example1.com = some_exact_attribute [ecsso-token-attributes] stanzaUse the [ecsso-token-attributes] stanza to specify extended attributes from a user credential to add to the cross-domain single signon token. Extended attributes consist of information about a user identity that WebSEAL adds to an extended attribute list when it creates a user credential.

domain_name

Use the domain_name stanza entry in the ecsso-token-attributes stanza to specify the credential attributes that WebSEAL includes in eCSSO authentication tokens.

Syntax

domain_name = pattern1
[domain_name = pattern2]
...
[domain_name = patternN]

Description

Credential attributes to include in eCSSO authentication tokens.

Options

domain_name

The domain_name specifies the destination domain containing the server that will consume the token.

pattern

The pattern for each entry can either a specific value or can be a pattern that uses standard Security Access Manager wildcard characters ( *, [], ^, \, ?).

Usage

This stanza entry is optional.

Default value

None.

Example

example1.com = my_cdas_attr_*
example1.com = some_exact_attribute

Parent topic: [ecsso-token-attributes] stanza

[enable-redirects] stanza[enable-redirects] stanzaIBM Security Access Manager for Web WebSEAL stanzaUse the [enable-redirects] stanza to enable automatic redirection for each of the applicable authentication methods. The authentication methods include forms authentication, basic authentication, certificate authentication, and EAI authentication.enable-redirects stanzastanzasenable-redirectsStanza referenceredirect

[enable-redirects] stanza

Use the [enable-redirects] stanza to enable automatic redirection for each of the applicable authentication methods. The authentication methods include forms authentication, basic authentication, certificate authentication, and EAI authentication.

redirect

Parent topic: Stanza reference

redirectredirectredirect stanza entryenable-redirects stanzaentriesredirectenable-redirects stanzaenable-redirects stanzaredirect entrySyntax redirect = {forms-auth|basic-auth|cert-auth|ext-auth-interface} Description Enables redirection for use with one or more authentication mechanism. Options {forms-auth|basic-auth|cert-auth|ext-auth-interface}Redirection is supported for: Forms authenticationBasic authenticationCertificate authenticationExternal authentication interface The configuration file must contain a separate entry for each authentication mechanism for which redirection is enabled. Usage This stanza entry is optional. Default value None. Example Example entries that enables redirection for forms authentication and basic authentication: redirect = forms-auth redirect = basic-auth [enable-redirects] stanzaUse the [enable-redirects] stanza to enable automatic redirection for each of the applicable authentication methods. The authentication methods include forms authentication, basic authentication, certificate authentication, and EAI authentication.

redirect

Syntax

redirect = {forms-auth|basic-auth|cert-auth|ext-auth-interface}

Description

Enables redirection for use with one or more authentication mechanism.

Options

{forms-auth|basic-auth|cert-auth|ext-auth-interface}

Redirection is supported for:

Forms authentication

Basic authentication

Certificate authentication

External authentication interface

The configuration file must contain a separate entry for each authentication mechanism for which redirection is enabled.

Usage

This stanza entry is optional.

Default value

None.

Example

Example entries that enables redirection for forms authentication and basic authentication:

redirect = forms-auth
redirect = basic-auth

Parent topic: [enable-redirects] stanza

[failover] stanza[failover] stanzaIBM Security Access Manager for Web WebSEAL [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.failover stanzastanzasfailoverStanza referenceclean-ecsso-urls-for-failoverUse the clean-ecsso-urls-for-failover stanza entry to control whether the URL that WebSEAL sends during failover authentication includes query arguments that contain the PD-VFHOST and PD-VF tokens.enable-failover-cookie-for-domainUse the enable-failover-cookie-for-domain stanza entry to enable the failover cookie for the domain. When enabled, the failover authentication cookie can be used by any WebSEAL server that is in the same domain as the WebSEAL server that creates the cookie. failover-authUse the failover-auth stanza entry to enable failover cookies. The configured value specifies the protocol over which WebSEAL accepts cookies for authentication during a failover authentication event.failover-cookie-lifetimeUse the failover-cookie-lifetime stanza entry to specify the lifetime, in minutes, of the failover cookie contents.failover-cookie-nameUse the failover-cookie-name stanza entry to specify the name of the cookie that stores the failover token. If the WebSEAL server that is hosting the user session fails, this cookie is presented to a replicated WebSEAL server to automatically reauthenticate the user. failover-cookies-keyfileUse the failover-cookies-keyfile stanza entry to specify the key file that WebSEAL can use to encrypt and decrypt the data in failover cookies.failover-include-session-idUse the failover-include-session-id stanza entry to enable WebSEAL to reuse the original session ID of a client by storing it as an attribute in the failover cookie. Reusing session IDs can improve failover authentication response and performance in a non-sticky load-balancing environment.failover-require-activity-timestamp-validationUse the failover-require-activity-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session activity timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.failover-require-lifetime-timestamp-validationUse the failover-require-lifetime-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session lifetime timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.failover-update-cookieUse the failover-update-cookie stanza entry to specify the frequency at which WebSEAL updates the session activity timestamp in failover cookies.reissue-missing-failover-cookieuse-utf8

[failover] stanza

Use the [failover] stanza to configure the use of failover cookies in WebSEAL.

clean-ecsso-urls-for-failover
Use the clean-ecsso-urls-for-failover stanza entry to control whether the URL that WebSEAL sends during failover authentication includes query arguments that contain the PD-VFHOST and PD-VF tokens.

enable-failover-cookie-for-domain
Use the enable-failover-cookie-for-domain stanza entry to enable the failover cookie for the domain. When enabled, the failover authentication cookie can be used by any WebSEAL server that is in the same domain as the WebSEAL server that creates the cookie.

failover-auth
Use the failover-auth stanza entry to enable failover cookies. The configured value specifies the protocol over which WebSEAL accepts cookies for authentication during a failover authentication event.

failover-cookie-lifetime
Use the failover-cookie-lifetime stanza entry to specify the lifetime, in minutes, of the failover cookie contents.

failover-cookie-name
Use the failover-cookie-name stanza entry to specify the name of the cookie that stores the failover token. If the WebSEAL server that is hosting the user session fails, this cookie is presented to a replicated WebSEAL server to automatically reauthenticate the user.

failover-cookies-keyfile
Use the failover-cookies-keyfile stanza entry to specify the key file that WebSEAL can use to encrypt and decrypt the data in failover cookies.

failover-include-session-id
Use the failover-include-session-id stanza entry to enable WebSEAL to reuse the original session ID of a client by storing it as an attribute in the failover cookie. Reusing session IDs can improve failover authentication response and performance in a non-sticky load-balancing environment.

failover-require-activity-timestamp-validation
Use the failover-require-activity-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session activity timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.

failover-require-lifetime-timestamp-validation
Use the failover-require-lifetime-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session lifetime timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.

failover-update-cookie
Use the failover-update-cookie stanza entry to specify the frequency at which WebSEAL updates the session activity timestamp in failover cookies.

reissue-missing-failover-cookie

use-utf8

Parent topic: Stanza reference

clean-ecsso-urls-for-failoverclean-ecsso-urls-for-failoverIBM Security Access Manager for Web WebSEAL clean-ecsso-urls-for-failover stanza entryUse the clean-ecsso-urls-for-failover stanza entry to control whether the URL that WebSEAL sends during failover authentication includes query arguments that contain the PD-VFHOST and PD-VF tokens.clean-ecsso-urls-for-failover stanza entryfailover stanzaentriesclean-ecsso-urls-for-failoverfailover stanzafailover stanzaclean-ecsso-urls-for-failover entrySyntax clean-ecsso-urls-for-failover = {yes|no} Description You can enable Failover Authentication and eCSSO in your environment. During failover authentication, if a user was originally authenticated using eCSSO, WebSEAL updates the URL that it sends to the back-end server. WebSEAL sends PD-VFHOST and PD-VF tokens as query arguments, along with the original URL.Use the clean-ecsso-urls-for-failover configuration entry to control whether these tokens are removed from the URL. Options yesThe query arguments that contain the PD-VFHOST and PD-VF tokens are removed from the URL.noThe query arguments that contain the PD-VFHOST and PD-VF tokens are not removed from the URL. Usage This stanza entry is optional. Default value no Example clean-ecsso-urls-for-failover = no [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

clean-ecsso-urls-for-failover

Use the clean-ecsso-urls-for-failover stanza entry to control whether the URL that WebSEAL sends during failover authentication includes query arguments that contain the PD-VFHOST and PD-VF tokens.

Syntax

clean-ecsso-urls-for-failover = {yes|no}

Description

You can enable Failover Authentication and eCSSO in your environment. During failover authentication, if a user was originally authenticated using eCSSO, WebSEAL updates the URL that it sends to the back-end server. WebSEAL sends PD-VFHOST and PD-VF tokens as query arguments, along with the original URL.

Use the clean-ecsso-urls-for-failover configuration entry to control whether these tokens are removed from the URL.

Options

yes

The query arguments that contain the PD-VFHOST and PD-VF tokens are removed from the URL.

no

The query arguments that contain the PD-VFHOST and PD-VF tokens are not removed from the URL.

Usage

This stanza entry is optional.

Default value

no

Example

clean-ecsso-urls-for-failover = no

Parent topic: [failover] stanza

enable-failover-cookie-for-domainenable-failover-cookie-for-domainIBM Security Access Manager for Web WebSEAL enable-failover-cookie-for-domain stanza entryUse the enable-failover-cookie-for-domain stanza entry to enable the failover cookie for the domain. When enabled, the failover authentication cookie can be used by any WebSEAL server that is in the same domain as the WebSEAL server that creates the cookie. enable-failover-cookie-for-domain stanza entryfailover stanzaentriesenable-failover-cookie-for-domainfailover stanzafailover stanzaenable-failover-cookie-for-domain entrySyntax enable-failover-cookie-for-domain = {yes|no} Description Enables the failover cookie for the domain. Options yesEnables the failover cookie for the domain.noDisables the failover cookie for the domain. Usage This stanza entry is required. Default value no Example enable-failover-cookie-for-domain = no [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

enable-failover-cookie-for-domain

Use the enable-failover-cookie-for-domain stanza entry to enable the failover cookie for the domain. When enabled, the failover authentication cookie can be used by any WebSEAL server that is in the same domain as the WebSEAL server that creates the cookie.

Syntax

enable-failover-cookie-for-domain = {yes|no}

Description

Enables the failover cookie for the domain.

Options

yes

Enables the failover cookie for the domain.

no

Disables the failover cookie for the domain.

Usage

This stanza entry is required.

Default value

no

Example

enable-failover-cookie-for-domain = no

Parent topic: [failover] stanza

failover-authfailover-authIBM Security Access Manager for Web WebSEAL failover-auth stanza entryUse the failover-auth stanza entry to enable failover cookies. The configured value specifies the protocol over which WebSEAL accepts cookies for authentication during a failover authentication event.failover-auth stanza entryfailover stanzaentriesfailover-authfailover stanzafailover stanzafailover-auth entrySyntax failover-auth = {none|http|https|both} Description Enables WebSEAL to accept failover cookies. Options {none|http|https|both}Specifies which protocols are supported. The value both means both HTTP and HTTPS. Usage This stanza entry is required. Default value none Example failover-auth = none [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-auth

Use the failover-auth stanza entry to enable failover cookies. The configured value specifies the protocol over which WebSEAL accepts cookies for authentication during a failover authentication event.

Syntax

failover-auth = {none|http|https|both}

Description

Enables WebSEAL to accept failover cookies.

Options

{none|http|https|both}

Specifies which protocols are supported. The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

none

Example

failover-auth = none

Parent topic: [failover] stanza

failover-cookie-lifetimefailover-cookie-lifetimeIBM Security Access Manager for Web WebSEAL failover-cookie-lifetime stanza entryUse the failover-cookie-lifetime stanza entry to specify the lifetime, in minutes, of the failover cookie contents.failover-cookie-lifetime stanza entryfailover stanzaentriesfailover-cookie-lifetimefailover stanzafailover stanzafailover-cookie-lifetime entrySyntax failover-cookie-lifetime = number_of_minutes Description An integer value specifying the number of minutes that failover cookie contents are valid. Options number_of_minutesAn integer value specifying the number of minutes that failover cookie contents are valid. Must be a positive integer. There is no maximum value. Usage This stanza entry is required. Default value 60 Example failover-cookie-lifetime = 60 [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-cookie-lifetime

Use the failover-cookie-lifetime stanza entry to specify the lifetime, in minutes, of the failover cookie contents.

Syntax

failover-cookie-lifetime = number_of_minutes

Description

An integer value specifying the number of minutes that failover cookie contents are valid.

Options

number_of_minutes

An integer value specifying the number of minutes that failover cookie contents are valid. Must be a positive integer. There is no maximum value.

Usage

This stanza entry is required.

Default value

60

Example

failover-cookie-lifetime = 60

Parent topic: [failover] stanza

failover-cookie-namefailover-cookie-nameIBM Security Access Manager for Web WebSEAL failover-cookie-name stanza entryUse the failover-cookie-name stanza entry to specify the name of the cookie that stores the failover token. If the WebSEAL server that is hosting the user session fails, this cookie is presented to a replicated WebSEAL server to automatically reauthenticate the user. failover-cookie-name stanza entryfailover stanzaentriesfailover-cookie-namefailover stanzafailover stanzafailover-cookie-name entrySyntax failover-cookie-name = <cookie_name> Description The name of the cookie that WebSEAL uses to store the failover token. The token includes details of the user session, which WebSEAL can use for single sign-on to a different WebSEAL instance in the event of failover.Options cookie_nameThe name of the failover cookie. Usage This stanza entry is optional. Default value PD-ID Example failover-cookie-name = fail_ckie [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-cookie-name

Use the failover-cookie-name stanza entry to specify the name of the cookie that stores the failover token. If the WebSEAL server that is hosting the user session fails, this cookie is presented to a replicated WebSEAL server to automatically reauthenticate the user.

Syntax

failover-cookie-name = <cookie_name>

Description

The name of the cookie that WebSEAL uses to store the failover token. The token includes details of the user session, which WebSEAL can use for single sign-on to a different WebSEAL instance in the event of failover.

Options

cookie_name

The name of the failover cookie.

Usage

This stanza entry is optional.

Default value

PD-ID

Example

failover-cookie-name = fail_ckie

Parent topic: [failover] stanza

failover-cookies-keyfilefailover-cookies-keyfileIBM Security Access Manager for Web WebSEAL failover-cookies-keyfile stanza entryUse the failover-cookies-keyfile stanza entry to specify the key file that WebSEAL can use to encrypt and decrypt the data in failover cookies.failover-cookies-keyfile stanza entryfailover stanzaentriesfailover-cookies-keyfilefailover stanzafailover stanzafailover-cookies-keyfile entrySyntax failover-cookies-keyfile = file_name Description A key file for failover cookie encryption. Use the SSO Keys management page of the LMI to generate this file.Options file_nameName of the key file for failover cookie encryption. Usage This stanza entry is optional. Default value None. Example failover-cookies-keyfile = failover.key [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-cookies-keyfile

Use the failover-cookies-keyfile stanza entry to specify the key file that WebSEAL can use to encrypt and decrypt the data in failover cookies.

Syntax

failover-cookies-keyfile = file_name

Description

A key file for failover cookie encryption. Use the SSO Keys management page of the LMI to generate this file.

Options

file_name

Name of the key file for failover cookie encryption.

Usage

This stanza entry is optional.

Default value

None.

Example

failover-cookies-keyfile = failover.key

Parent topic: [failover] stanza

failover-include-session-idfailover-include-session-idIBM Security Access Manager for Web WebSEAL failover-include-session-id stanza entryUse the failover-include-session-id stanza entry to enable WebSEAL to reuse the original session ID of a client by storing it as an attribute in the failover cookie. Reusing session IDs can improve failover authentication response and performance in a non-sticky load-balancing environment.failover-include-session-id stanza entryfailover stanzaentriesfailover-include-session-idfailover stanzafailover stanzafailover-include-session-id entrySyntax failover-include-session-id = {yes|no} Description Enable or disable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment. WebSEAL reuses the original session ID by storing the ID as an extended attribute to the failover cookie. Options yesEnable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment. noDisable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment. Usage This stanza entry is required. Default value no Example failover-include-session-id = no [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-include-session-id

Use the failover-include-session-id stanza entry to enable WebSEAL to reuse the original session ID of a client by storing it as an attribute in the failover cookie. Reusing session IDs can improve failover authentication response and performance in a non-sticky load-balancing environment.

Syntax

failover-include-session-id = {yes|no}

Description

Enable or disable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment. WebSEAL reuses the original session ID by storing the ID as an extended attribute to the failover cookie.

Options

yes

Enable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment.

no

Disable WebSEAL to reuse a client's original session ID to improve failover authentication response and performance in a non-sticky load-balancing environment.

Usage

This stanza entry is required.

Default value

no

Example

failover-include-session-id = no

Parent topic: [failover] stanza

failover-require-activity-timestamp-validationfailover-require-activity-timestamp-validationIBM Security Access Manager for Web WebSEAL failover-require-activity-timestamp-validation stanza entryUse the failover-require-activity-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session activity timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.failover-require-activity-timestamp-validation stanza entryfailover stanzaentriesfailover-require-activity-timestamp-validationfailover stanzafailover stanzafailover-require-activity-timestamp-validation entrySyntax failover-require-activity-timestamp-validation = {yes|no} Description Enables or disables the requirement of a session activity timestamp validation in the failover cookie. Options yesEnables the requirement of a session activity timestamp validation in the failover cookie.noDisables the requirement of a session activity timestamp validation in the failover cookie. For backward compatibility with versions of WebSEAL server prior to version 5.1, set this stanza entry to no. Versions prior to version 5.1 did not create the session activity timestamp in the failover cookie. Usage This stanza entry is required. Default value no Example failover-require-activity-timestamp-validation = no [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-require-activity-timestamp-validation

Use the failover-require-activity-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session activity timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.

Syntax

failover-require-activity-timestamp-validation = {yes|no}

Description

Enables or disables the requirement of a session activity timestamp validation in the failover cookie.

Options

yes

Enables the requirement of a session activity timestamp validation in the failover cookie.

no

Disables the requirement of a session activity timestamp validation in the failover cookie. For backward compatibility with versions of WebSEAL server prior to version 5.1, set this stanza entry to no. Versions prior to version 5.1 did not create the session activity timestamp in the failover cookie.

Usage

This stanza entry is required.

Default value

no

Example

failover-require-activity-timestamp-validation = no

Parent topic: [failover] stanza

failover-require-lifetime-timestamp-validationfailover-require-lifetime-timestamp-validationIBM Security Access Manager for Web WebSEAL failover-require-lifetime-timestamp-validation stanza entryUse the failover-require-lifetime-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session lifetime timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.failover-require-lifetime-timestamp-validation stanza entryfailover stanzaentriesfailover-require-lifetime-timestamp-validationfailover stanzafailover stanzafailover-require-lifetime-timestamp-validation entrySyntax failover-require-lifetime-timestamp-validation = {yes|no} Description Enables or disables the requirement of a session lifetime timestamp validation in the failover cookie. Options yesEnables the requirement of a session lifetime timestamp validation in the failover cookie.noDisables the requirement of a session lifetime timestamp validation in the failover cookie. For backward compatibility with versions of WebSEAL server prior to version 5.1, set this stanza entry to no. Versions prior to version 5.1 did not create the session lifetime timestamp in the failover cookie. Usage This stanza entry is required. Default value no Example failover-require-lifetime-timestamp-validation = no [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-require-lifetime-timestamp-validation

Use the failover-require-lifetime-timestamp-validation stanza entry to control whether WebSEAL requires each failover authentication cookie to contain a session lifetime timestamp. This stanza entry is used primarily for compatibility with prior versions of WebSEAL.

Syntax

failover-require-lifetime-timestamp-validation = {yes|no}

Description

Enables or disables the requirement of a session lifetime timestamp validation in the failover cookie.

Options

yes

Enables the requirement of a session lifetime timestamp validation in the failover cookie.

no

Disables the requirement of a session lifetime timestamp validation in the failover cookie. For backward compatibility with versions of WebSEAL server prior to version 5.1, set this stanza entry to no. Versions prior to version 5.1 did not create the session lifetime timestamp in the failover cookie.

Usage

This stanza entry is required.

Default value

no

Example

failover-require-lifetime-timestamp-validation = no

Parent topic: [failover] stanza

failover-update-cookiefailover-update-cookieIBM Security Access Manager for Web WebSEAL failover-update-cookie stanza entryUse the failover-update-cookie stanza entry to specify the frequency at which WebSEAL updates the session activity timestamp in failover cookies.failover-update-cookie stanza entryfailover stanzaentriesfailover-update-cookiefailover stanzafailover stanzafailover-update-cookie entrySyntax failover-update-cookie = number_of_seconds Description The maximum interval, in number of seconds, allowed between updates of the session activity timestamp in the failover cookies. The value is an integer. When the server receives a request, if the number of seconds specified for this parameter has passed, the session activity timestamp is updated. If you set a value greater than zero, ensure that you also set session-activity-timestamp = add in the [failover-add-attributes] stanza. If you do not set this additional value, WebSEAL decodes the failover cookie on each user access, which can adversely affect performance.Options number_of_secondsWhen the value is 0, the session activity timestamp is updated on every request. When the value is less than zero (negative number), the session activity timestamp is never updated. There is no maximum value. Usage This stanza entry is required. Default value -1 Example failover-cookie-update = 60 [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

failover-update-cookie

Use the failover-update-cookie stanza entry to specify the frequency at which WebSEAL updates the session activity timestamp in failover cookies.

Syntax

failover-update-cookie = number_of_seconds

Description

The maximum interval, in number of seconds, allowed between updates of the session activity timestamp in the failover cookies. The value is an integer. When the server receives a request, if the number of seconds specified for this parameter has passed, the session activity timestamp is updated.

Note: If you set a value greater than zero, ensure that you also set session-activity-timestamp = add in the [failover-add-attributes] stanza. If you do not set this additional value, WebSEAL decodes the failover cookie on each user access, which can adversely affect performance.

Options

number_of_seconds

When the value is 0, the session activity timestamp is updated on every request. When the value is less than zero (negative number), the session activity timestamp is never updated. There is no maximum value.

Usage

This stanza entry is required.

Default value

-1

Example

failover-cookie-update = 60

Parent topic: [failover] stanza

reissue-missing-failover-cookiereissue-missing-failover-cookiereissue-missing-failover-cookie stanza entryfailover stanzaentriesreissue-missing-failover-cookiefailover stanzafailover stanzareissue-missing-failover-cookie entrySyntax reissue-missing-failover-cookie = {yes|no}Description Allows WebSEAL to reissue a cached original failover cookie in the response to a client, if the client makes a request that does not include the failover cookie.Options yesEnables the failover cookie reissue mechanism.noDisables the failover cookie reissue mechanism.Usage This stanza entry is required.Default value noExample reissue-missing-failover-cookie = no [failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

reissue-missing-failover-cookie

Syntax

reissue-missing-failover-cookie = {yes|no}

Description

Allows WebSEAL to reissue a cached original failover cookie in the response to a client, if the client makes a request that does not include the failover cookie.

Options

yes

Enables the failover cookie reissue mechanism.

no

Disables the failover cookie reissue mechanism.

Usage

This stanza entry is required.

Default value

no

Example

reissue-missing-failover-cookie = no

Parent topic: [failover] stanza

use-utf8use-utf8use-utf8 stanza entryfailover stanzaentriesuse-utf8failover stanzafailover stanzause-utf8 entrySyntax use-utf8 = {yes|no}Description Use UTF–8 encoding for strings in the failover authentication cookie.Options yesBeginning with version 5.1, WebSEAL servers use UTF-8 encoding by default. When this stanza entry is set to yes, cookies can be exchanged with other WebSEAL servers that use UTF-8 encoding. This enables cookies to used across different code pages (such as for a different language).noFor backward compatibility with cookies created by WebSEAL servers from version prior to 5.1, set this stanza entry to no.Usage This stanza entry is required.Default value yesExample use-utf8 = yes[failover] stanzaUse the [failover] stanza to configure the use of failover cookies in WebSEAL.

use-utf8

Syntax

use-utf8 = {yes|no}

Description

Use UTF–8 encoding for strings in the failover authentication cookie.

Options

yes

Beginning with version 5.1, WebSEAL servers use UTF-8 encoding by default. When this stanza entry is set to yes, cookies can be exchanged with other WebSEAL servers that use UTF-8 encoding. This enables cookies to used across different code pages (such as for a different language).

no

For backward compatibility with cookies created by WebSEAL servers from version prior to 5.1, set this stanza entry to no.

Usage

This stanza entry is required.

Default value

yes

Example

use-utf8 = yes

Parent topic: [failover] stanza

[failover-add-attributes] stanza[failover-add-attributes] stanzaIBM Security Access Manager for Web WebSEAL [failover-add-attributes] stanzaUse the [failover-add-attributes] stanza to add attributes to the failover authentication cookie. These attributes can include extended attributes from a user credential and session time stamps.failover-add-attributes stanzastanzasfailover-add-attributesStanza referenceattribute_patternUse the attribute_pattern stanza entry to specify the credential attributes that WebSEAL preserves in the failover cookie.session-activity-timestampsession-lifetime-timestamp

[failover-add-attributes] stanza

Use the [failover-add-attributes] stanza to add attributes to the failover authentication cookie. These attributes can include extended attributes from a user credential and session time stamps.

attribute_pattern
Use the attribute_pattern stanza entry to specify the credential attributes that WebSEAL preserves in the failover cookie.

session-activity-timestamp

session-lifetime-timestamp

Parent topic: Stanza reference

attribute_patternattribute_patternIBM Security Access Manager for Web WebSEAL attribute_pattern stanza entryUse the attribute_pattern stanza entry to specify the credential attributes that WebSEAL preserves in the failover cookie.attribute_pattern stanza entryfailover-add-attributes stanzaentriesattribute_patternfailover-add-attributes stanzafailover-add-attributes stanzaattribute_pattern entrySyntax attribute_pattern = add Description List of attributes from the original credential that must be preserved in the failover cookie. The order of entries in the stanza is important. Rules (patterns) that are listed earlier in the stanza take precedence over those entries that are listed later in the stanza. Attributes that do not match any pattern are not added to the failover cookie. Options attribute_patternThe attribute pattern is a not case-sensitive wildcard pattern.addAdd attribute. Usage Entries in this stanza are optional. Default value There are no default entries in this stanza. However, the attributes AUTHENTICATION_LEVEL and AZN_CRED_AUTH_METHOD are added to the failover cookie by default. You do not need to include these attributes in the configuration stanza. Example tagvalue_failover_amweb_session_id = add [failover-add-attributes] stanzaUse the [failover-add-attributes] stanza to add attributes to the failover authentication cookie. These attributes can include extended attributes from a user credential and session time stamps.

attribute_pattern

Use the attribute_pattern stanza entry to specify the credential attributes that WebSEAL preserves in the failover cookie.

Syntax

attribute_pattern = add

Description

List of attributes from the original credential that must be preserved in the failover cookie.

The order of entries in the stanza is important. Rules (patterns) that are listed earlier in the stanza take precedence over those entries that are listed later in the stanza. Attributes that do not match any pattern are not added to the failover cookie.

Options

attribute_pattern

The attribute pattern is a not case-sensitive wildcard pattern.

add

Add attribute.

Usage

Entries in this stanza are optional.

Default value

There are no default entries in this stanza. However, the attributes AUTHENTICATION_LEVEL and AZN_CRED_AUTH_METHOD are added to the failover cookie by default. You do not need to include these attributes in the configuration stanza.

Example

tagvalue_failover_amweb_session_id = add

Parent topic: [failover-add-attributes] stanza

session-activity-timestampsession-activity-timestampsession-activity-timestamp stanza entryfailover-add-attributes stanzaentriessession-activity-timestampfailover-add-attributes stanzafailover-add-attributes stanzasession-activity-timestamp entrySyntax session-activity-timestamp = addDescription This entry specifies that the timestamp for the last user activity be taken from the failover cookie and added to the new session on the replicated server. This attribute cannot be specified by pattern matching. This entry must be added exactly as it is written.Options addAdd attribute.Usage This stanza entry is optional and must be manually added to the configuration file.Default value None.Example session-activity-timestamp = add[failover-add-attributes] stanzaUse the [failover-add-attributes] stanza to add attributes to the failover authentication cookie. These attributes can include extended attributes from a user credential and session time stamps.

session-activity-timestamp

Syntax

session-activity-timestamp = add

Description

This entry specifies that the timestamp for the last user activity be taken from the failover cookie and added to the new session on the replicated server.

This attribute cannot be specified by pattern matching. This entry must be added exactly as it is written.

Options

add

Add attribute.

Usage

This stanza entry is optional and must be manually added to the configuration file.

Default value

None.

Example

session-activity-timestamp = add

Parent topic: [failover-add-attributes] stanza

session-lifetime-timestampsession-lifetime-timestampsession-lifetime-timestamp stanza entryfailover-add-attributes stanzaentriessession-lifetime-timestampfailover-add-attributes stanzafailover-add-attributes stanzasession-lifetime-timestamp entrySyntax session-lifetime-timestamp = addDescription This entry specifies that the timestamp for creation of the original session be taken from the failover cookie and added to the new session on the replicated server. This attribute cannot be specified by pattern matching. This entry must be added exactly as it is written.Options addAdd attribute.Usage This stanza entry is optional and must be manually added to the configuration file.Default value None.Example session-lifetime-timestamp = add[failover-add-attributes] stanzaUse the [failover-add-attributes] stanza to add attributes to the failover authentication cookie. These attributes can include extended attributes from a user credential and session time stamps.

session-lifetime-timestamp

Syntax

session-lifetime-timestamp = add

Description

This entry specifies that the timestamp for creation of the original session be taken from the failover cookie and added to the new session on the replicated server.

This attribute cannot be specified by pattern matching. This entry must be added exactly as it is written.

Options

add

Add attribute.

Usage

This stanza entry is optional and must be manually added to the configuration file.

Default value

None.

Example

session-lifetime-timestamp = add

Parent topic: [failover-add-attributes] stanza

[failover-restore-attributes] stanza[failover-restore-attributes] stanzaIBM Security Access Manager for Web WebSEAL [failover-restore-attributes] stanzaUse the [failover-restore-attributes] stanza to configure WebSEAL to extract certain attributes from the failover authentication cookie and place them into the user credential. failover-restore-attributes stanzastanzasfailover-restore-attributesStanza referenceattribute_patternUse the attribute_pattern stanza entry with a value of preserve to specify the failover cookie attributes that WebSEAL adds to the re-created user credential.attribute_patternUse the attribute_pattern stanza entry with a value of refresh to specify failover cookie attributes that WebSEAL must refresh rather than preserve.

[failover-restore-attributes] stanza

Use the [failover-restore-attributes] stanza to configure WebSEAL to extract certain attributes from the failover authentication cookie and place them into the user credential.

attribute_pattern
Use the attribute_pattern stanza entry with a value of preserve to specify the failover cookie attributes that WebSEAL adds to the re-created user credential.

attribute_pattern
Use the attribute_pattern stanza entry with a value of refresh to specify failover cookie attributes that WebSEAL must refresh rather than preserve.

Parent topic: Stanza reference

attribute_patternattribute_patternIBM Security Access Manager for Web WebSEAL attribute_pattern stanza entryUse the attribute_pattern stanza entry with a value of preserve to specify the failover cookie attributes that WebSEAL adds to the re-created user credential.attribute_pattern stanza entryfailover-restore-attributes stanzaentriesattribute_patternfailover-restore-attributes stanzafailover-restore-attributes stanzaattribute_pattern entrySyntax attribute_pattern = preserve Description List of attributes to put in the new credential when re-creating a credential from a failover cookie. The order of entries in the stanza is important. Rules (patterns) that are listed earlier in the stanza take precedence the entries that are listed later in the stanza. Attributes that do not match any pattern are not added to the credential. Options attribute_patternThe attribute pattern is a not case-sensitive wildcard pattern.preserveWhen WebSEAL recreates a credential, all failover cookie attributes are ignored unless specified by an entry with the value preserve. Usage Entries in this stanza are optional. Default value None. Example tagvalue_failover_amweb_session_id = preserve [failover-restore-attributes] stanzaUse the [failover-restore-attributes] stanza to configure WebSEAL to extract certain attributes from the failover authentication cookie and place them into the user credential.

attribute_pattern

Use the attribute_pattern stanza entry with a value of preserve to specify the failover cookie attributes that WebSEAL adds to the re-created user credential.

Syntax

attribute_pattern = preserve

Description

List of attributes to put in the new credential when re-creating a credential from a failover cookie.

The order of entries in the stanza is important. Rules (patterns) that are listed earlier in the stanza take precedence the entries that are listed later in the stanza. Attributes that do not match any pattern are not added to the credential.

Options

attribute_pattern

The attribute pattern is a not case-sensitive wildcard pattern.

preserve

When WebSEAL recreates a credential, all failover cookie attributes are ignored unless specified by an entry with the value preserve.

Usage

Entries in this stanza are optional.

Default value

None.

Example

tagvalue_failover_amweb_session_id = preserve

Parent topic: [failover-restore-attributes] stanza

attribute_patternattribute_patternIBM Security Access Manager for Web WebSEAL attribute_pattern stanza entryUse the attribute_pattern stanza entry with a value of refresh to specify failover cookie attributes that WebSEAL must refresh rather than preserve.attribute_pattern stanza entryfailover-restore-attributes stanzaentriesattribute_patternfailover-restore-attributes stanzafailover-restore-attributes stanzaattribute_pattern entrySyntax attribute_pattern = refresh Description A list of failover cookie attributes to omit from the recreated user credential. This list is not needed in all configurations. The default behavior when WebSEAL recreates a user credential is to omit all attributes that are not specified with a value of preserve. In some cases, it might be necessary to specify an exception to a wildcard pattern matching to ensure that a specific attribute gets refreshed, not preserved. To do so, configure the pattern with the value refresh. This specification might be necessary, for example, when you are using a custom external authentication C API module.The order of entries in the stanza is important. Rules (patterns) that are listed earlier in the stanza take precedence over the entries that are listed later in the stanza. Options attribute_patternThe attribute pattern is a not case-sensitive wildcard pattern.refreshSpecifies an exception to a wildcard pattern matching to ensure that a specific attribute gets refreshed, not preserved. Usage Entries in this stanza are optional. Default value None. Example tagvalue_failover_amweb_session_id = refresh [failover-restore-attributes] stanzaUse the [failover-restore-attributes] stanza to configure WebSEAL to extract certain attributes from the failover authentication cookie and place them into the user credential.

attribute_pattern

Use the attribute_pattern stanza entry with a value of refresh to specify failover cookie attributes that WebSEAL must refresh rather than preserve.

Syntax

attribute_pattern = refresh

Description

A list of failover cookie attributes to omit from the recreated user credential.

This list is not needed in all configurations. The default behavior when WebSEAL recreates a user credential is to omit all attributes that are not specified with a value of preserve.

In some cases, it might be necessary to specify an exception to a wildcard pattern matching to ensure that a specific attribute gets refreshed, not preserved. To do so, configure the pattern with the value refresh. This specification might be necessary, for example, when you are using a custom external authentication C API module.

The order of entries in the stanza is important. Rules (patterns) that are listed earlier in the stanza take precedence over the entries that are listed later in the stanza.

Options

attribute_pattern

The attribute pattern is a not case-sensitive wildcard pattern.

refresh

Specifies an exception to a wildcard pattern matching to ensure that a specific attribute gets refreshed, not preserved.

Usage

Entries in this stanza are optional.

Default value

None.

Example

tagvalue_failover_amweb_session_id = refresh

Parent topic: [failover-restore-attributes] stanza

[filter-advanced-encodings] stanza[filter-advanced-encodings] stanzaWebSEAL [filter-advanced-encodings] stanzaUse the [filter-advanced-encodings] stanza to configure the types of URL encoding that are detected and filtered.filter-advanced-encodings stanzastanzasfilter-advanced-encodingsSyntax [filter-advanced-encodings] <escaping method> = <chars to escape> <escaping method> = <chars to escape> ... DescriptionThe WebSEAL advanced filtering can process a number of URL encoding types. Use this stanza to define the types of encoding to be detected and filtered. Options <escaping method>ampersandAmpersand encoded. For example:HTTP://host:port/path?V1=D1&V2=D2ampersand-hexAmpersand just hex encoded. For example: HTTP&amp;#x3a;&amp;#x2f;&amp;#x2f;host&amp;#x3a;port&amp;#x2f;ampersand-decAmpersand just dec encoded. For example:HTTP&amp;#58;&amp;#57;&amp;#57;host&amp;#58;port&amp;#57;escapedBackslash encoded. For example:HTTP:\/\/host:port\/percentPercent hex encoded. For example:HTTP%3A%2F%2Fhost%3Aport%2Fescaped-uBackslash U hex encoded. For example:HTTP:\u002f\u002fhost:port\u002fpercent-uPercent U hex encoded. For example:HTTP%u003a//host%u003aport/escaped-x Backslash X hex encoded. For example:HTTP\x3A\x2F\x2Fhost\x3Aport\x2F<chars to escape>A list of characters that need encoding, which are governed by the following rules:If two characters are separated by a '-' (hyphen) character, then this is a range of characters to encode. For example, "A-Z" indicates all characters from 'A' to 'Z' including 'A' and 'Z'.If the first character in the list is the '^' character, then the list of characters are those not to encode. For example "^A-Za-z" indicates all characters excluding characters from 'A' to 'Z' and excluding characters from 'a' to 'z'.If the first character (excluding the '^' character) is a '-' (hyphen) character, then that is taken as the literal '-' character rather than representing a range of characters. Usage It is permissible to have multiple entries with the same <escaping method>, if they produce different encodings of the "://" string.WebSEAL uses the <escaping method> against <chars to escape> to encode the string "://" and use that encoded value in combination with "http" or "https" to detect encoded URLs. The very first entry should be to define the "ampersand" encoding method and not list the character ':' and '/' in the <chars to escape>. This then matches URLs with an un-encoded "://". Default value None. Example [filter-advanced-encodings] ampersand = &amp;<&gt;"' ampersand-hex = ^a-zA-Z0-9. ampersand-dec = ^a-zA-Z0-9. percent = ^a-zA-Z0-9. escaped-x = ^a-zA-Z0-9. This example specifies the following behavior:ampersand = &<>"'This allows WebSEAL to find and filter unencoded links such as "http://backend.com:80/". It identifies the link by looking for "http" or "https" followed by "://". Any WebSEAL host name or junction path replaced in the filtered link will have the characters &<>"' replaced by their encoded forms, &amp; &lt; &gt; &quot; and &#x2c; respectively.ampersand-hex = ^a-zA-Z0-9.This allows WebSEAL to find and filter ampersand hex encoded links such as "http&#x3a;&#x2f;&#x2f;backend.com&#x3a;80&#x2f;". It identifies the link embedded in java script by looking for "http" or "https" followed by "&#x3a;&#x2f;&#x2f;". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms &#xHH;.ampersand-dec = ^a-zA-Z0-9.This allows WebSEAL to find and filter ampersand hex encoded links such as "http&#58;&#47;&#47;backend.com&#58;80&#47;". It identifies the link embedded in java script by looking for "http" or "https" followed by "&#58;&#47;&#47;". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms &#DDD;.percent = ^a-zA-Z0-9.This allows WebSEAL to find and filter ampersand hex encoded links such as "http%3a%2f%2fbackend.com%3a80%2f". It identifies the link embedded in java script by looking for "http" or "https" followed by "%3a%2f%2f". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms %HH. This may be required for attributes with Flash URLs.escaped-x = ^a-zA-Z0-9.This allows WebSEAL to find and filter ampersand hex encoded links such as "http\x3a\x2f\x2fbackend.com\x3a80\x2f". It identifies the link embedded in java script by looking for "http" or "https" followed by "\x3a\x2f\x2f". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms \xHH. This may be required for Javascript encoded URLs.Stanza reference

[filter-advanced-encodings] stanza

Use the [filter-advanced-encodings] stanza to configure the types of URL encoding that are detected and filtered.

Syntax

[filter-advanced-encodings]
     <escaping method> = <chars to escape>
     <escaping method> = <chars to escape>
     ...

Description

The WebSEAL advanced filtering can process a number of URL encoding types. Use this stanza to define the types of encoding to be detected and filtered.

Options

<escaping method>

ampersand

Ampersand encoded. For example:

HTTP://host:port/path?V1=D1&V2=D2

ampersand-hex

Ampersand just hex encoded. For example:

HTTP&amp;#x3a;&amp;#x2f;&amp;#x2f;host&amp;#x3a;port&amp;#x2f;

ampersand-dec

Ampersand just dec encoded. For example:

HTTP&amp;#58;&amp;#57;&amp;#57;host&amp;#58;port&amp;#57;

escaped

Backslash encoded. For example:

HTTP:\/\/host:port\/

percent

Percent hex encoded. For example:

HTTP%3A%2F%2Fhost%3Aport%2F

escaped-u

Backslash U hex encoded. For example:

HTTP:\u002f\u002fhost:port\u002f

percent-u

Percent U hex encoded. For example:

HTTP%u003a//host%u003aport/

escaped-x

Backslash X hex encoded. For example:

HTTP\x3A\x2F\x2Fhost\x3Aport\x2F

<chars to escape>

A list of characters that need encoding, which are governed by the following rules:

If two characters are separated by a '-' (hyphen) character, then this is a range of characters to encode. For example, "A-Z" indicates all characters from 'A' to 'Z' including 'A' and 'Z'.

If the first character in the list is the '^' character, then the list of characters are those not to encode. For example "^A-Za-z" indicates all characters excluding characters from 'A' to 'Z' and excluding characters from 'a' to 'z'.

If the first character (excluding the '^' character) is a '-' (hyphen) character, then that is taken as the literal '-' character rather than representing a range of characters.

Usage

It is permissible to have multiple entries with the same <escaping method>, if they produce different encodings of the "://" string.

WebSEAL uses the <escaping method> against <chars to escape> to encode the string "://" and use that encoded value in combination with "http" or "https" to detect encoded URLs. The very first entry should be to define the "ampersand" encoding method and not list the character ':' and '/' in the <chars to escape>. This then matches URLs with an un-encoded "://".

Default value

None.

Example

[filter-advanced-encodings]
ampersand     = &amp;<&gt;"'
ampersand-hex = ^a-zA-Z0-9.
ampersand-dec = ^a-zA-Z0-9.
percent       = ^a-zA-Z0-9.
escaped-x     = ^a-zA-Z0-9.

This example specifies the following behavior:

ampersand = &<>"'

This allows WebSEAL to find and filter unencoded links such as "http://backend.com:80/". It identifies the link by looking for "http" or "https" followed by "://". Any WebSEAL host name or junction path replaced in the filtered link will have the characters &<>"' replaced by their encoded forms, &amp; &lt; &gt; &quot; and &#x2c; respectively.

ampersand-hex = ^a-zA-Z0-9.

This allows WebSEAL to find and filter ampersand hex encoded links such as "http&#x3a;&#x2f;&#x2f;backend.com&#x3a;80&#x2f;". It identifies the link embedded in java script by looking for "http" or "https" followed by "&#x3a;&#x2f;&#x2f;". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms &#xHH;.

ampersand-dec = ^a-zA-Z0-9.

This allows WebSEAL to find and filter ampersand hex encoded links such as "http&#58;&#47;&#47;backend.com&#58;80&#47;". It identifies the link embedded in java script by looking for "http" or "https" followed by "&#58;&#47;&#47;". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms &#DDD;.

percent = ^a-zA-Z0-9.

This allows WebSEAL to find and filter ampersand hex encoded links such as "http%3a%2f%2fbackend.com%3a80%2f". It identifies the link embedded in java script by looking for "http" or "https" followed by "%3a%2f%2f". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms %HH. This may be required for attributes with Flash URLs.

escaped-x = ^a-zA-Z0-9.

This allows WebSEAL to find and filter ampersand hex encoded links such as "http\x3a\x2f\x2fbackend.com\x3a80\x2f". It identifies the link embedded in java script by looking for "http" or "https" followed by "\x3a\x2f\x2f". Any WebSEAL host name or junction path replaced in the filtered link will have the characters not in the set a-zA-Z0-9. replaced by their encoded forms \xHH. This may be required for Javascript encoded URLs.

Parent topic: Stanza reference

[filter-content-types] stanza[filter-content-types] stanzaIBM Security Access Manager for Web WebSEAL [filter-content-types] stanzaUse the [filter-content-types] stanza to specify the content (MIME) types of the documents in which WebSEAL filters tag-based static URLs.filter-content-types stanzastanzasfilter-content-typesStanza referencetype

[filter-content-types] stanza

Use the [filter-content-types] stanza to specify the content (MIME) types of the documents in which WebSEAL filters tag-based static URLs.

type

Parent topic: Stanza reference

typetypetype stanza entryfilter-content-types stanzaentriestypefilter-content-types stanzafilter-content-types stanzatype entrySyntax type = type_nameDescription List of entries that specify MIME types to be filtered by WebSEAL when received from junctioned servers. Administrators can add additional MIME types that refer to a document that contains HTML or HTML-like content.Options type_nameMIME type.Usage This list of stanza entries is required.Default value Do not remove the default entries. type = text/html type = text/vnd.wap.wmlExample type = text/html type = text/vnd.wap.wml[filter-content-types] stanzaUse the [filter-content-types] stanza to specify the content (MIME) types of the documents in which WebSEAL filters tag-based static URLs.

type

Syntax

type = type_name

Description

List of entries that specify MIME types to be filtered by WebSEAL when received from junctioned servers.

Administrators can add additional MIME types that refer to a document that contains HTML or HTML-like content.

Options

type_name

MIME type.

Usage

This list of stanza entries is required.

Default value

Do not remove the default entries.

type = text/html
type = text/vnd.wap.wml

Example

type = text/html
type = text/vnd.wap.wml

Parent topic: [filter-content-types] stanza

[filter-events] stanza[filter-events] stanzaIBM Security Access Manager for Web WebSEAL [filter-events] stanzaUse the [filter-events] stanza to identify HTML tags that might contain JavaScript. WebSEAL searches these tags to filter any absolute URLs embedded in JavaScript event handlers.filter-events stanzastanzasfilter-eventsStanza referenceHTML_tag

[filter-events] stanza

Use the [filter-events] stanza to identify HTML tags that might contain JavaScript. WebSEAL searches these tags to filter any absolute URLs embedded in JavaScript event handlers.

HTML_tag

Parent topic: Stanza reference

HTML_tagHTML_tagHTML_tag stanza entryfilter-events stanzaentriesHTML_tagfilter-events stanzafilter-events stanzaHTML_tag entrySyntax HTML_tag = event_handler Description List of HTML tags used by WebSEAL to identify and filter absolute URLs embedded in JavaScript. JavaScript allows HTML tags to contain event handlers that are invoked when certain events occur. For example, the HTML tag: <form onsubmit="javascript:doSomething()"> causes the JavaScript function doSomething() to be called when the form is submitted. The entries in this stanza are used to identify HTML tags that may contain JavaScript code. When such a tag is discovered, WebSEAL searches the tag to filter any absolute URLs embedded in the JavaScript. For example, if the "form onsubmit" example looked like: <form onsubmit="javaScript:doSomething('http://junction.server.com')"> WebSEAL HTML filtering would modify the tag to look like: <form onsubmit="javaScript:doSomething('/junction')"> Administrators can add additional entries when necessary. New entries must consist of valid HTML tags that are built into JavaScript. When adding new entries, maintain alphabetical order. Options HTML_tagHTML tag.event_handlerJavaScript event handler. Usage This list is required. Although not all tags are required by all applications, the unused tags do no harm. Leave the default entries in this list. Default value Default HTML tags and event handlers: A = ONCLICK A = ONDBLCLICK A = ONMOUSEDOWN A = ONMOUSEOUT A = ONMOUSEOVER A = ONMOUSEUP AREA = ONCLICK AREA = ONMOUSEOUT AREA = ONMOUSEOVER BODY = ONBLUR BODY = ONCLICK BODY = ONDRAGDROP BODY = ONFOCUS BODY = ONKEYDOWN BODY = ONKEYPRESS BODY = ONKEYUP BODY = ONLOAD BODY = ONMOUSEDOWN BODY = ONMOUSEUP BODY = ONMOVE BODY = ONRESIZE BODY = ONUNLOAD FORM = ONRESET FORM = ONSUBMIT FRAME = ONBLUR FRAME = ONDRAGDROP FRAME = ONFOCUS FRAME = ONLOAD FRAME = ONMOVE FRAME = ONRESIZE FRAME = ONUNLOAD IMG = ONABORT IMG = ONERROR IMG = ONLOAD INPUT = ONBLUR INPUT = ONCHANGE INPUT = ONCLICK INPUT = ONFOCUS INPUT = ONKEYDOWN INPUT = ONKEYPRESS INPUT = ONKEYUP INPUT = ONMOUSEDOWN INPUT = ONMOUSEUP INPUT = ONSELECT LAYER = ONBLUR LAYER = ONLOAD LAYER = ONMOUSEOUT LAYER = ONMOUSEOVER SELECT = ONBLUR SELECT = ONCHANGE SELECT = ONFOCUS TEXTAREA = ONBLUR TEXTAREA = ONCHANGE TEXTAREA = ONFOCUS TEXTAREA = ONKEYDOWN TEXTAREA = ONKEYPRESS TEXTAREA = ONKEYUP TEXTAREA = ONSELECT Example IMG = ONABORT [filter-events] stanzaUse the [filter-events] stanza to identify HTML tags that might contain JavaScript. WebSEAL searches these tags to filter any absolute URLs embedded in JavaScript event handlers.

HTML_tag

Syntax

HTML_tag = event_handler

Description

List of HTML tags used by WebSEAL to identify and filter absolute URLs embedded in JavaScript. JavaScript allows HTML tags to contain event handlers that are invoked when certain events occur. For example, the HTML tag:

<form onsubmit="javascript:doSomething()">

causes the JavaScript function doSomething() to be called when the form is submitted.

The entries in this stanza are used to identify HTML tags that may contain JavaScript code. When such a tag is discovered, WebSEAL searches the tag to filter any absolute URLs embedded in the JavaScript. For example, if the "form onsubmit" example looked like:

<form onsubmit="javaScript:doSomething('http://junction.server.com')">

WebSEAL HTML filtering would modify the tag to look like:

<form onsubmit="javaScript:doSomething('/junction')">

Administrators can add additional entries when necessary. New entries must consist of valid HTML tags that are built into JavaScript. When adding new entries, maintain alphabetical order.

Options

HTML_tag

HTML tag.

event_handler

JavaScript event handler.

Usage

This list is required. Although not all tags are required by all applications, the unused tags do no harm. Leave the default entries in this list.

Default value

Default HTML tags and event handlers:

A = ONCLICK
A = ONDBLCLICK
A = ONMOUSEDOWN
A = ONMOUSEOUT
A = ONMOUSEOVER
A = ONMOUSEUP
AREA = ONCLICK
AREA = ONMOUSEOUT
AREA = ONMOUSEOVER
BODY = ONBLUR
BODY = ONCLICK
BODY = ONDRAGDROP
BODY = ONFOCUS
BODY = ONKEYDOWN
BODY = ONKEYPRESS
BODY = ONKEYUP
BODY = ONLOAD
BODY = ONMOUSEDOWN
BODY = ONMOUSEUP
BODY = ONMOVE
BODY = ONRESIZE
BODY = ONUNLOAD
FORM = ONRESET
FORM = ONSUBMIT
FRAME = ONBLUR
FRAME = ONDRAGDROP
FRAME = ONFOCUS
FRAME = ONLOAD
FRAME = ONMOVE

FRAME = ONRESIZE
FRAME = ONUNLOAD
IMG = ONABORT
IMG = ONERROR
IMG = ONLOAD
INPUT = ONBLUR
INPUT = ONCHANGE
INPUT = ONCLICK
INPUT = ONFOCUS
INPUT = ONKEYDOWN
INPUT = ONKEYPRESS
INPUT = ONKEYUP
INPUT = ONMOUSEDOWN
INPUT = ONMOUSEUP
INPUT = ONSELECT
LAYER = ONBLUR
LAYER = ONLOAD
LAYER = ONMOUSEOUT
LAYER = ONMOUSEOVER
SELECT = ONBLUR
SELECT = ONCHANGE
SELECT = ONFOCUS
TEXTAREA = ONBLUR
TEXTAREA = ONCHANGE
TEXTAREA = ONFOCUS
TEXTAREA = ONKEYDOWN
TEXTAREA = ONKEYPRESS
TEXTAREA = ONKEYUP
TEXTAREA = ONSELECT

Example

IMG = ONABORT

Parent topic: [filter-events] stanza

[filter-request-headers] stanza[filter-request-headers] stanzaIBM Security Access Manager for Web WebSEAL [filter-request-headers] stanzaUse the [filter-request-headers] stanza to configure extra HTTP headers for WebSEAL to filter before it sends a request to a junctioned server.filter-request-headers stanzastanzasfilter-request-headersStanza referenceheader

[filter-request-headers] stanza

Use the [filter-request-headers] stanza to configure extra HTTP headers for WebSEAL to filter before it sends a request to a junctioned server.

header

Parent topic: Stanza reference

headerheaderheader stanza entryfilter-request-headers stanzaentriesheaderfilter-request-headers stanzafilter-request-headers stanzaheader entrySyntax header = header_nameDescription List of HTTP headers that WebSEAL filters before sending the request to a junctioned server. A default list is built-in to WebSEAL. The default entries are not included in the configuration file. The addition of new entries in this stanza is optional. For example, an administrator could add the accept-encoding header. This would instruct WebSEAL to remove any accept-encoding headers from requests before forwarding the request to the junction. The removal of the accept-encoding header would cause the junction server to return the document in an unencoded form, allowing WebSEAL to filter the document if necessary. New entries must consist of valid HTTP headers.Options header_nameHTTP header name.Usage The addition of new entries in this stanza is optional.Default value Default built-in header list: host connection proxy-connection expect te iv-ssl-jct iv-user iv_user iv-groups iv_groups iv-creds iv_creds iv_remote_address iv-remote-addressExample header = accept-encoding[filter-request-headers] stanzaUse the [filter-request-headers] stanza to configure extra HTTP headers for WebSEAL to filter before it sends a request to a junctioned server.

header

Syntax

header = header_name

Description

List of HTTP headers that WebSEAL filters before sending the request to a junctioned server. A default list is built-in to WebSEAL. The default entries are not included in the configuration file.

The addition of new entries in this stanza is optional. For example, an administrator could add the accept-encoding header. This would instruct WebSEAL to remove any accept-encoding headers from requests before forwarding the request to the junction. The removal of the accept-encoding header would cause the junction server to return the document in an unencoded form, allowing WebSEAL to filter the document if necessary.

New entries must consist of valid HTTP headers.

Options

header_name

HTTP header name.

Usage

The addition of new entries in this stanza is optional.

Default value

Default built-in header list:

host
connection
proxy-connection
expect
te
iv-ssl-jct
iv-user
iv_user
iv-groups
iv_groups
iv-creds
iv_creds
iv_remote_address
iv-remote-address

Example

header = accept-encoding

Parent topic: [filter-request-headers] stanza

[filter-schemes] stanza[filter-schemes] stanzaIBM Security Access Manager for Web WebSEAL [filter-schemes] stanzaUse the [filter-schemes] stanza to list URL schemes that are not to be filtered by WebSEAL in responses from junctioned application servers.filter-schemes stanzastanzasfilter-schemesStanza referencescheme

[filter-schemes] stanza

Use the [filter-schemes] stanza to list URL schemes that are not to be filtered by WebSEAL in responses from junctioned application servers.

scheme

Parent topic: Stanza reference

schemeschemescheme stanza entryfilter-schemes stanzaentriesschemefilter-schemes stanzafilter-schemes stanzascheme entrySyntax scheme = scheme_name Description List of URL schemes that are not to be filtered by WebSEAL. A scheme is a protocol identifier. This list is used when WebSEAL encounters a document containing a base URL. For example: <head> <base href="http://www.foo.com"> </head> <a href="mailto:bee@bee.com>Send me mail",/a> WebSEAL identifies the scheme mailto because this scheme is included by default in the [filter-schemes] stanza. If mailto was not identified as a scheme, WebSEAL would interpret it as document and perform normal filtering. WebSEAL would then rewrite the link as: <a href="http://www.foo.com/mailto:bee@bee.com" This would be incorrect. Options scheme_nameScheme name. Usage WebSEAL provides a set of default schemes. The administrator can extend the list if additional protocols are used. Do not delete entries from the list. Default value Default list entries: scheme = file scheme = ftp scheme = https scheme = mailto scheme = news scheme = telnet Example scheme = telnet [filter-schemes] stanzaUse the [filter-schemes] stanza to list URL schemes that are not to be filtered by WebSEAL in responses from junctioned application servers.

scheme

Syntax

scheme = scheme_name

Description

List of URL schemes that are not to be filtered by WebSEAL. A scheme is a protocol identifier.

This list is used when WebSEAL encounters a document containing a base URL. For example:

<head>
<base href="http://www.foo.com">
</head>
<a href="mailto:bee@bee.com>Send me mail",/a>

WebSEAL identifies the scheme mailto because this scheme is included by default in the [filter-schemes] stanza. If mailto was not identified as a scheme, WebSEAL would interpret it as document and perform normal filtering. WebSEAL would then rewrite the link as:

<a href="http://www.foo.com/mailto:bee@bee.com"

This would be incorrect.

Options

scheme_name

Scheme name.

Usage

WebSEAL provides a set of default schemes. The administrator can extend the list if additional protocols are used. Do not delete entries from the list.

Default value

Default list entries:

scheme = file
scheme = ftp
scheme = https
scheme = mailto
scheme = news
scheme = telnet

Example

scheme = telnet

Parent topic: [filter-schemes] stanza

[filter-url] stanza[filter-url] stanzaIBM Security Access Manager for Web WebSEAL [filter-url] stanzaUse the [filter-url] stanza to specify the HTML tags and attributes that WebSEAL filters in responses from junctioned servers.filter-url stanzastanzasfilter-urlStanza referenceHTML_tag

[filter-url] stanza

Use the [filter-url] stanza to specify the HTML tags and attributes that WebSEAL filters in responses from junctioned servers.

HTML_tag

Parent topic: Stanza reference

HTML_tagHTML_tagHTML_tag stanza entryfilter-url stanzaentriesHTML_tagfilter-url stanzafilter-url stanzaHTML_tag entrySyntax HTML_tag = URL_attribute Description List of URL attributes that WebSEAL server filters in responses from junctioned servers. Administrators can add additional entries when necessary. New entries must consist of valid HTML tags and attributes. When adding new entries, maintain alphabetical order. Options URL_attributeURL attribute. Usage This list is required. Although not all tags are required by all applications, the unused tags do no harm. Leave the default entries in this list. Default value Default HTML tags and attributes: A = HREF APPLET = CODEBASE AREA = HREF BASE = HREF BGSOUND = SRC BLOCKQUOTE = CITE BODY = BACKGROUND DEL = CITE DIV = EMPTYURL DIV = IMAGEPATH DIV = URL DIV = VIEWCLASS EMBED = PLUGINSPAGE EMBED = SRC FORM = ACTION FRAME = LONGDESC FRAME = SRC HEAD = PROFILE IFRAME = LONGDESC IFRAME = SRC ILAYER = BACKGROUND ILAYER = SRC IMG = SRC IMG = LOWSRC IMG = LONGDESC IMG = USEMAP IMG = DYNSRC INPUT = SRC INPUT = USEMAP INS = CITE ISINDEX = ACTION ISINDEX = HREF LAYER = BACKGROUND LAYER = SRC LINK = HREF LINK = SRC OBJECT = CODEBASE OBJECT = DATA OBJECT = USEMAP Q = CITE SCRIPT = SRC TABLE = BACKGROUND TD = BACKGROUND TH = BACKGROUND TR = BACKGROUND WM:CALENDARPICKER = FOLDERURL WM:CALENDARPICKER = IMAGEPREVARROW WM:CALENDARPICKER = IMAGENEXTARROW WM:CALENDARVIEW = FOLDERURL WM:MESSAGE = DRAFTSURL WM:MESSAGE = URL WM:NOTIFY = FOLDER WM:REMINDER = FOLDER ?IMPORT = IMPLEMENTATION Example IMG = SRC [filter-url] stanzaUse the [filter-url] stanza to specify the HTML tags and attributes that WebSEAL filters in responses from junctioned servers.

HTML_tag

Syntax

HTML_tag = URL_attribute

Description

List of URL attributes that WebSEAL server filters in responses from junctioned servers.

Administrators can add additional entries when necessary. New entries must consist of valid HTML tags and attributes. When adding new entries, maintain alphabetical order.

Options

URL_attribute

URL attribute.

Usage

This list is required. Although not all tags are required by all applications, the unused tags do no harm. Leave the default entries in this list.

Default value

Default HTML tags and attributes:

A = HREF
APPLET = CODEBASE
AREA = HREF
BASE = HREF
BGSOUND = SRC
BLOCKQUOTE = CITE
BODY = BACKGROUND
DEL = CITE
DIV = EMPTYURL
DIV = IMAGEPATH
DIV = URL
DIV = VIEWCLASS
EMBED = PLUGINSPAGE
EMBED = SRC
FORM = ACTION
FRAME = LONGDESC
FRAME = SRC
HEAD = PROFILE
IFRAME = LONGDESC
IFRAME = SRC
ILAYER = BACKGROUND
ILAYER = SRC
IMG = SRC
IMG = LOWSRC
IMG = LONGDESC
IMG = USEMAP
IMG = DYNSRC

INPUT = SRC
INPUT = USEMAP
INS = CITE
ISINDEX = ACTION
ISINDEX = HREF
LAYER = BACKGROUND
LAYER = SRC
LINK = HREF
LINK = SRC
OBJECT = CODEBASE
OBJECT = DATA
OBJECT = USEMAP
Q = CITE
SCRIPT = SRC
TABLE = BACKGROUND
TD = BACKGROUND
TH = BACKGROUND
TR = BACKGROUND
WM:CALENDARPICKER = FOLDERURL
WM:CALENDARPICKER = IMAGEPREVARROW
WM:CALENDARPICKER = IMAGENEXTARROW
WM:CALENDARVIEW = FOLDERURL
WM:MESSAGE = DRAFTSURL
WM:MESSAGE = URL
WM:NOTIFY = FOLDER
WM:REMINDER = FOLDER
?IMPORT = IMPLEMENTATION

Example

IMG = SRC

Parent topic: [filter-url] stanza

[flow-data] stanza[flow-data] stanzaIBM Security Access Manager for Web WebSEAL [flow-data] stanzaUse the [flow-data] stanza to configure the recording of flow data statistics in WebSEAL.flow-data stanzastanzasflow-dataStanza referenceflow-data-enabledUse the flow-data-enabled stanza entry to control whether WebSEAL records flow data statistics.flow-data-stats-intervalUse the flow-data-stats-interval stanza entry to control how frequently the appliance collects flow data statistics.

[flow-data] stanza

Use the [flow-data] stanza to configure the recording of flow data statistics in WebSEAL.

flow-data-enabled
Use the flow-data-enabled stanza entry to control whether WebSEAL records flow data statistics.

flow-data-stats-interval
Use the flow-data-stats-interval stanza entry to control how frequently the appliance collects flow data statistics.

Parent topic: Stanza reference

flow-data-enabledflow-data-enabledIBM Security Access Manager for Web WebSEAL flow-data-enabled stanza entryUse the flow-data-enabled stanza entry to control whether WebSEAL records flow data statistics.flow-data-enabled stanza entryflow-data stanzaentriesflow-data-enabledflow-data stanzaflow-data stanzaflow-data-enabled entrySyntax flow-data-enabled = {yes|no} Description The appliance can record statistical information about incoming WebSEAL requests. Use this parameter to enable or disable the recording of flow data statistics.If you set this parameter to yes, you can also use the flow-data-stats-interval parameter in the [flow-data] stanza to set the frequency for gathering statistics. You can configure the [user-agent] stanza to categorize the incoming user-agent requests and make the statistical data more useful. You can then view a statistical breakdown of all requests that is based on user-agent and junction. Options yesWebSEAL records statistics about incoming requests.noWebSEAL does not record statistics about incoming requests. Usage This stanza entry is optional. Default value yes Example flow-data-enabled = yes [flow-data] stanzaUse the [flow-data] stanza to configure the recording of flow data statistics in WebSEAL.

flow-data-enabled

Use the flow-data-enabled stanza entry to control whether WebSEAL records flow data statistics.

Syntax

flow-data-enabled = {yes|no}

Description

The appliance can record statistical information about incoming WebSEAL requests. Use this parameter to enable or disable the recording of flow data statistics.

If you set this parameter to yes, you can also use the flow-data-stats-interval parameter in the [flow-data] stanza to set the frequency for gathering statistics.

Note: You can configure the [user-agent] stanza to categorize the incoming user-agent requests and make the statistical data more useful. You can then view a statistical breakdown of all requests that is based on user-agent and junction.

Options

yes

WebSEAL records statistics about incoming requests.

no

WebSEAL does not record statistics about incoming requests.

Usage

This stanza entry is optional.

Default value

yes

Example

flow-data-enabled = yes

Parent topic: [flow-data] stanza

flow-data-stats-intervalflow-data-stats-intervalIBM Security Access Manager for Web WebSEAL flow-data-stats-interval stanza entryUse the flow-data-stats-interval stanza entry to control how frequently the appliance collects flow data statistics.flow-data-stats-interval stanza entryflow-data stanzaentriesflow-data-stats-intervalflow-data stanzaflow-data stanzaflow-data-stats-interval entrySyntax flow-data-stats-interval = number_of_seconds Description This parameter specifies the statistics interval in seconds. At each time interval, WebSEAL records statistical information about incoming requests. The default value of 600 records statistics every 10 minutes.To gather statistics at the specified interval, you must use the flow-data-enabled parameter, also in the [flow-data] stanza, to enable the flow data statistics on the appliance. You can configure the [user-agent] stanza to categorize the incoming user-agent requests and make the statistical data more meaningful. You can then view a statistical breakdown of all requests that is based on user-agent and junction. Options number_of_secondsSpecifies the interval that the appliance uses to collect flow data statistics. Usage This stanza entry is optional. Default value 600 Example flow-data-stats-interval = 600 [flow-data] stanzaUse the [flow-data] stanza to configure the recording of flow data statistics in WebSEAL.

flow-data-stats-interval

Use the flow-data-stats-interval stanza entry to control how frequently the appliance collects flow data statistics.

Syntax

flow-data-stats-interval = number_of_seconds

Description

This parameter specifies the statistics interval in seconds. At each time interval, WebSEAL records statistical information about incoming requests. The default value of 600 records statistics every 10 minutes.

To gather statistics at the specified interval, you must use the flow-data-enabled parameter, also in the [flow-data] stanza, to enable the flow data statistics on the appliance.

Note: You can configure the [user-agent] stanza to categorize the incoming user-agent requests and make the statistical data more meaningful. You can then view a statistical breakdown of all requests that is based on user-agent and junction.

Options

number_of_seconds

Specifies the interval that the appliance uses to collect flow data statistics.

Usage

This stanza entry is optional.

Default value

600

Example

flow-data-stats-interval = 600

Parent topic: [flow-data] stanza

[forms] stanza[forms] stanzaIBM Security Access Manager for Web WebSEAL [forms] stanzaUse the [forms] stanza to configure forms authentication in WebSEAL.forms stanzastanzasformsStanza referenceallow-empty-form-fieldsUse the allow-empty-form-fields stanza entry to determine whether WebSEAL returns an error for login requests that contain an empty user name or an empty password.forms-authUse the forms-auth stanza entry to enable the forms authentication method.

[forms] stanza

Use the [forms] stanza to configure forms authentication in WebSEAL.

allow-empty-form-fields
Use the allow-empty-form-fields stanza entry to determine whether WebSEAL returns an error for login requests that contain an empty user name or an empty password.

forms-auth
Use the forms-auth stanza entry to enable the forms authentication method.

Parent topic: Stanza reference

allow-empty-form-fieldsallow-empty-form-fieldsIBM Security Access Manager for Web WebSEAL allow-empty-form-fields stanza entryUse the allow-empty-form-fields stanza entry to determine whether WebSEAL returns an error for login requests that contain an empty user name or an empty password.allow-empty-form-fields stanza entryforms stanzaentriesallow-empty-form-fieldsforms stanzaforms stanzaallow-empty-form-fields entrySyntax allow-empty-form-fields = {true|false} Description If a forms login request is received with either an empty user name or an empty password, WebSEAL returns the login form without stating an error. If you prefer that an error message is displayed with the returned login form, set this value to true. In this case, WebSEAL attempts to authenticate the user and if the values have zero length, the registry returns the appropriate error. Options trueError message is displayed with the returned login form.falseError message is not displayed with the returned login form. Usage This stanza entry is required. Default value false Example allow-empty-form-fields = false [forms] stanzaUse the [forms] stanza to configure forms authentication in WebSEAL.

allow-empty-form-fields

Use the allow-empty-form-fields stanza entry to determine whether WebSEAL returns an error for login requests that contain an empty user name or an empty password.

Syntax

allow-empty-form-fields = {true|false}

Description

If a forms login request is received with either an empty user name or an empty password, WebSEAL returns the login form without stating an error.

If you prefer that an error message is displayed with the returned login form, set this value to true. In this case, WebSEAL attempts to authenticate the user and if the values have zero length, the registry returns the appropriate error.

Options

true

Error message is displayed with the returned login form.

false

Error message is not displayed with the returned login form.

Usage

This stanza entry is required.

Default value

false

Example

allow-empty-form-fields = false

Parent topic: [forms] stanza

forms-authforms-authIBM Security Access Manager for Web WebSEAL forms-auth stanza entryUse the forms-auth stanza entry to enable the forms authentication method.forms-auth stanza entryforms stanzaentriesforms-authforms stanzaforms stanzaforms-auth entrySyntax forms-auth = {none|http|https|both} Description Enables authentication using the Forms Authentication mechanism. Options {none|http|https|both}Specifies which protocols are supported. The value both means both HTTP and HTTPS. Usage This stanza entry is required. Default value none Example forms-auth = none [forms] stanzaUse the [forms] stanza to configure forms authentication in WebSEAL.

forms-auth

Use the forms-auth stanza entry to enable the forms authentication method.

Syntax

forms-auth = {none|http|https|both}

Description

Enables authentication using the Forms Authentication mechanism.

Options

{none|http|https|both}

Specifies which protocols are supported. The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

none

Example

forms-auth = none

Parent topic: [forms] stanza

[gso-cache] stanza[gso-cache] stanzaUse the [gso-cache] stanza to define Global Signon (GSO) settings.gso-cache stanzastanzasgso-cacheStanza referencegso-cache-enabledUse the gso-cache-enabled stanza entry to enable or disable Global Signon (GSO) cache.gso-cache-entry-idle-timeoutUse the gso-cache-entry-idle-timeout stanza entry to specify the timeout for cache entries that are idle.gso-cache-entry-lifetimeUse the gso-cache-entry-lifetime stanza entry to define the lifetime of a GSO cache entry.gso-cache-sizeUse the gso-cache-size stanza entry to specify how many entries are allowed in the GSO cache.

[gso-cache] stanza

Use the [gso-cache] stanza to define Global Signon (GSO) settings.

gso-cache-enabled
Use the gso-cache-enabled stanza entry to enable or disable Global Signon (GSO) cache.

gso-cache-entry-idle-timeout
Use the gso-cache-entry-idle-timeout stanza entry to specify the timeout for cache entries that are idle.

gso-cache-entry-lifetime
Use the gso-cache-entry-lifetime stanza entry to define the lifetime of a GSO cache entry.

gso-cache-size
Use the gso-cache-size stanza entry to specify how many entries are allowed in the GSO cache.

Parent topic: Stanza reference

gso-cache-enabledgso-cache-enabled Use the gso-cache-enabled stanza entry to enable or disable Global Signon (GSO) cache.gso-cache-enabled stanza entrygso-cache stanzaentriesgso-cache-enabledgso-cache stanzagso-cache stanzagso-cache-enabled entrySyntax gso-cache-enabled = {yes|no} Description Enables or disables the Global Signon (GSO) cache. Options yesEnables the Global Signon (GSO) cache.noDisables the Global Signon (GSO) cache. Usage This stanza entry is required. Default value no Example gso-cache-enabled = no [gso-cache] stanzaUse the [gso-cache] stanza to define Global Signon (GSO) settings.

gso-cache-enabled

Use the gso-cache-enabled stanza entry to enable or disable Global Signon (GSO) cache.

Syntax

gso-cache-enabled = {yes|no}

Description

Enables or disables the Global Signon (GSO) cache.

Options

yes

Enables the Global Signon (GSO) cache.

no

Disables the Global Signon (GSO) cache.

Usage

This stanza entry is required.

Default value

no

Example

gso-cache-enabled = no

Parent topic: [gso-cache] stanza

gso-cache-entry-idle-timeoutgso-cache-entry-idle-timeoutUse the gso-cache-entry-idle-timeout stanza entry to specify the timeout for cache entries that are idle.gso-cache-entry-idle-timeout stanza entrygso-cache stanzaentriesgso-cache-entry-idle-timeoutgso-cache stanzagso-cache stanzagso-cache-entry-idle-timeout entrySyntax gso-cache-entry-idle-timeout = number_of_seconds Description Integer value that specifies the timeout, in seconds, for cache entries that are idle. Options number_of_secondsThe value must be greater than or equal to zero (0). A value of 0 means that entries are not removed from the GSO cache due to inactivity. However, they may still be removed due to either the gso-cache-size being exceeded or the gso-cache-entry-lifetime stanza entry being exceeded. WebSEAL does not impose a maximum value. Usage This stanza entry is required, but is ignored when GSO caching is disabled. Default value 120 Example gso-cache-entry-idle-timeout = 120 [gso-cache] stanzaUse the [gso-cache] stanza to define Global Signon (GSO) settings.

gso-cache-entry-idle-timeout

Use the gso-cache-entry-idle-timeout stanza entry to specify the timeout for cache entries that are idle.

Syntax

gso-cache-entry-idle-timeout = number_of_seconds

Description

Integer value that specifies the timeout, in seconds, for cache entries that are idle.

Options

number_of_seconds

The value must be greater than or equal to zero (0). A value of 0 means that entries are not removed from the GSO cache due to inactivity. However, they may still be removed due to either the gso-cache-size being exceeded or the gso-cache-entry-lifetime stanza entry being exceeded. WebSEAL does not impose a maximum value.

Usage

This stanza entry is required, but is ignored when GSO caching is disabled.

Default value

120

Example

gso-cache-entry-idle-timeout = 120

Parent topic: [gso-cache] stanza

gso-cache-entry-lifetimegso-cache-entry-lifetimeUse the gso-cache-entry-lifetime stanza entry to define the lifetime of a GSO cache entry.gso-cache-entry-lifetime stanza entrygso-cache stanzaentriesgso-cache-entry-lifetimegso-cache stanzagso-cache stanzagso-cache-entry-lifetime entrySyntax gso-cache-entry-lifetime = number_of_seconds Description Integer value that specifies the lifetime, in seconds, of a GSO cache entry. Options number_of_secondsThe value must be greater than or equal to zero (0). A value of 0 means that entries are not removed from the GSO cache due to their entry lifetime being exceeded. However, they may still be removed due to either the gso-cache-size being exceeded or the gso-cache-entry-idle-timeout stanza entry being exceeded. WebSEAL does not impose a maximum value. Usage This stanza entry is required, but is ignored when GSO caching is disabled. Default value 900 Example gso-cache-entry-lifetime = 900 [gso-cache] stanzaUse the [gso-cache] stanza to define Global Signon (GSO) settings.

gso-cache-entry-lifetime

Use the gso-cache-entry-lifetime stanza entry to define the lifetime of a GSO cache entry.

Syntax

gso-cache-entry-lifetime = number_of_seconds

Description

Integer value that specifies the lifetime, in seconds, of a GSO cache entry.

Options

number_of_seconds

The value must be greater than or equal to zero (0). A value of 0 means that entries are not removed from the GSO cache due to their entry lifetime being exceeded. However, they may still be removed due to either the gso-cache-size being exceeded or the gso-cache-entry-idle-timeout stanza entry being exceeded. WebSEAL does not impose a maximum value.

Usage

This stanza entry is required, but is ignored when GSO caching is disabled.

Default value

900

Example

gso-cache-entry-lifetime = 900

Parent topic: [gso-cache] stanza

gso-cache-sizegso-cache-sizeUse the gso-cache-size stanza entry to specify how many entries are allowed in the GSO cache.gso-cache-size stanza entrygso-cache stanzaentriesgso-cache-sizegso-cache stanzagso-cache stanzagso-cache-size entrySyntax gso-cache-size = number_of_entries Description Integer value indicating the number of entries allowed in the GSO cache. Options number_of_entriesThe value must be greater than or equal to zero (0). Zero means that there is no limit on the size of the GSO cache. This is not recommended. WebSEAL does not impose a maximum value. Choose your maximum value to stay safely within the bounds of your available system memory. Usage This stanza entry is required, but is ignored when GSO caching is disabled. Default value 1024 Example gso-cache-size = 1024 [gso-cache] stanzaUse the [gso-cache] stanza to define Global Signon (GSO) settings.

gso-cache-size

Use the gso-cache-size stanza entry to specify how many entries are allowed in the GSO cache.

Syntax

gso-cache-size = number_of_entries

Description

Integer value indicating the number of entries allowed in the GSO cache.

Options

number_of_entries

The value must be greater than or equal to zero (0). Zero means that there is no limit on the size of the GSO cache. This is not recommended.

WebSEAL does not impose a maximum value. Choose your maximum value to stay safely within the bounds of your available system memory.

Usage

This stanza entry is required, but is ignored when GSO caching is disabled.

Default value

1024

Example

gso-cache-size = 1024

Parent topic: [gso-cache] stanza

[header-names] stanza[header-names] stanzaUse the [header-names] stanza to define the HTTP header information in the request that WebSEAL sends to junctioned applications.header-names stanzastanzasheader-namesStanza referenceheader-dataUse the header-data stanza entry to add HTTP headers to the request that WebSEAL sends to junctioned applications.

[header-names] stanza

Use the [header-names] stanza to define the HTTP header information in the request that WebSEAL sends to junctioned applications.

header-data
Use the header-data stanza entry to add HTTP headers to the request that WebSEAL sends to junctioned applications.

Parent topic: Stanza reference

header-dataheader-dataIBM Security Access Manager for Web header-data stanza entryUse the header-data stanza entry to add HTTP headers to the request that WebSEAL sends to junctioned applications.header-data stanza entryheader-names stanzaentriesheader-dataheader-names stanzaheader-names stanzaheader-data entrySyntax <header-data> = [+]<header-name> Description Controls the addition of HTTP headers into the request that is passed to junctioned applications. To include the same <header-data> in different headers, specify multiple entries with the same <header-data> value.Do not include more than one entry with the same <header-name> value. The <header-name> values must be unique. If there is more than one entry for a particular <header-name>, WebSEAL processes the last entry for that <header-name>. Any preceding entries are disregarded. Options <header-data>The type of data that WebSEAL adds to the <header-name> header of the request. The valid values for this entry are as follows:server-nameThe Security Access Manager authorization server name for the WebSEAL server. This name is the name of the authorization API administration server that is used in the server task commands.client-ip-v4The IPv4 address of the client of this request.client-ip-v6The IPv6 address of the client of this request.client-portThe port that is used by the client of this request. This port is the client source port and not the destination port.host-nameThe host name of the WebSEAL server. WebSEAL obtains this host name from the web-host-name configuration entry in the [server] stanza if specified. Otherwise, WebSEAL returns the host name of the server itself.httphdr{<name>}An HTTP header from the request as specified by the <name> field. If the HTTP header is not found in the request, WebSEAL uses the value in the [server] tag-value-missing-attr-tag configuration entry as the value for the header.<header-name>The name of the HTTP header that holds the data. The <header-name> can be prefixed with the plus (+) character if you want to append to any existing header instead of overwriting the existing header. Valid strings are limited to the following characters: A-Z, a-z, 0–9, hyphen ( - ), or underscore ( _ ). Usage This stanza entry is required. Default value server-name = iv_server_name Exampleserver-name = iv_server_nameIn this example, WebSEAL passes the following header and value to the junction if the WebSEAL instance is default-webseald-diamond.example.com: iv_server_name:default-webseald-diamond.example.comOther example entries:client-ip-v4 = +X-Forwarded-For client-ip-v4 = X-Header httphdr{host} = X-Forwarded-Host host-name = X-Forwarded-Server [header-names] stanzaUse the [header-names] stanza to define the HTTP header information in the request that WebSEAL sends to junctioned applications.

header-data

Use the header-data stanza entry to add HTTP headers to the request that WebSEAL sends to junctioned applications.

Syntax

<header-data> = [+]<header-name>

Description

Controls the addition of HTTP headers into the request that is passed to junctioned applications.

To include the same <header-data> in different headers, specify multiple entries with the same <header-data> value.

Note: Do not include more than one entry with the same <header-name> value. The <header-name> values must be unique. If there is more than one entry for a particular <header-name>, WebSEAL processes the last entry for that <header-name>. Any preceding entries are disregarded.

Options

<header-data>

The type of data that WebSEAL adds to the <header-name> header of the request. The valid values for this entry are as follows:

server-name

The Security Access Manager authorization server name for the WebSEAL server. This name is the name of the authorization API administration server that is used in the server task commands.

client-ip-v4

The IPv4 address of the client of this request.

client-ip-v6

The IPv6 address of the client of this request.

client-port

The port that is used by the client of this request. This port is the client source port and not the destination port.

host-name

The host name of the WebSEAL server. WebSEAL obtains this host name from the web-host-name configuration entry in the [server] stanza if specified. Otherwise, WebSEAL returns the host name of the server itself.

httphdr{<name>}

An HTTP header from the request as specified by the <name> field. If the HTTP header is not found in the request, WebSEAL uses the value in the [server] tag-value-missing-attr-tag configuration entry as the value for the header.

<header-name>

The name of the HTTP header that holds the data. The <header-name> can be prefixed with the plus (+) character if you want to append to any existing header instead of overwriting the existing header. Valid strings are limited to the following characters: A-Z, a-z, 0–9, hyphen ( - ), or underscore ( _ ).

Usage

This stanza entry is required.

Default value

server-name = iv_server_name

Example

server-name = iv_server_name

In this example, WebSEAL passes the following header and value to the junction if the WebSEAL instance is default-webseald-diamond.example.com:

iv_server_name:default-webseald-diamond.example.com

Other example entries:

client-ip-v4 = +X-Forwarded-For
client-ip-v4 = X-Header
httphdr{host} = X-Forwarded-Host
host-name = X-Forwarded-Server

Parent topic: [header-names] stanza

[http-method-perms] stanzaUse this stanza to define the permissions that are required to perform a request with a particular HTTP method.This stanza can be specified for specific junctions by creating a stanza of the form [http-method-perms:junction]. The values in the global [http-method-perms] stanza apply to any junctions that do not have a junction-specific stanza. A junction-specific stanza [http-method-perms:junction] does not inherit values from a global stanza. If the [http-method-perms:junction] stanza is defined for a junction, the global [http-method-perms] stanza will have no impact.Stanza referencehttp-methodUse the http-method stanza entry to define the ACL permission for a particular HTTP method.

[http-method-perms] stanza

Use this stanza to define the permissions that are required to perform a request with a particular HTTP method.

This stanza can be specified for specific junctions by creating a stanza of the form [http-method-perms:junction]. The values in the global [http-method-perms] stanza apply to any junctions that do not have a junction-specific stanza. A junction-specific stanza [http-method-perms:junction] does not inherit values from a global stanza. If the [http-method-perms:junction] stanza is defined for a junction, the global [http-method-perms] stanza will have no impact.

http-method
Use the http-method stanza entry to define the ACL permission for a particular HTTP method.

Parent topic: Stanza reference

http-methodUse the http-method stanza entry to define the ACL permission for a particular HTTP method.Syntax http-method = permissionDescription The http-method entry defines the mapping of an HTTP request method to an ACL permission bit. Options TcgmdbsvaBtRrxlNWA You can also create custom permissions in custom action groups, for example, [my-action-group]t. See Custom permissions in custom action groupsThe default permissions in the primary action group are available to all applications. If a custom action group uses these default permissions, the associated actions must closely match that of the actual operation that is done by an action in the primary action group..Usage This stanza entry is optional. If this stanza is empty, the Web Reverse Proxy defaults to the following ACL bits: PUT => m DELETE => d All else (GET,POST .. ) => r The <default> entry defines the permissions that are required for any methods that are not explicitly specified elsewhere in this stanza. A <default> entry is required in each [http-method-perms] stanza if any methods are defined in the stanza. In other words, an [http-method-perms] stanza can either be empty or contains entries that include the <default> method. You can define multiple ACL bits for a method. For example, POST = Ax. If multiple ACL bits are defined for a method, then the user must be granted each of those permissions in the effective ACL for the protected object.Default value None. By default, this stanza is not defined.Example <default> = r GET = r HEAD = T PUT = m POST = Ax DELETE = d TRACE = [my-action-group]t[http-method-perms] stanzaUse this stanza to define the permissions that are required to perform a request with a particular HTTP method.

http-method

Use the http-method stanza entry to define the ACL permission for a particular HTTP method.

Syntax

http-method = permission

Description

The http-method entry defines the mapping of an HTTP request method to an ACL permission bit.

Options

T

c

g

m

d

b

s

v

a

B

t

R

r

x

l

N

W

A

You can also create custom permissions in custom action groups, for example, [my-action-group]t. See Custom permissions in custom action groups.

Usage

This stanza entry is optional. If this stanza is empty, the Web Reverse Proxy defaults to the following ACL bits:

PUT => m
DELETE => d
All else (GET,POST .. ) => r

The <default> entry defines the permissions that are required for any methods that are not explicitly specified elsewhere in this stanza. A <default> entry is required in each [http-method-perms] stanza if any methods are defined in the stanza. In other words, an [http-method-perms] stanza can either be empty or contains entries that include the <default> method.

You can define multiple ACL bits for a method. For example, POST = Ax.

If multiple ACL bits are defined for a method, then the user must be granted each of those permissions in the effective ACL for the protected object.

Default value

None. By default, this stanza is not defined.

Example

<default> = r
GET = r
HEAD = T
PUT = m
POST = Ax
DELETE = d
TRACE = [my-action-group]t

Parent topic: [http-method-perms] stanza

[http-transformations] stanza[http-transformations] stanzaUse the [http-transformations] stanza to define the HTTP transformation settings.http-transformations stanzastanzashttp-transformationsStanza referenceresource-nameUse the resource-name stanza entry to define HTTP transformation resources.

[http-transformations] stanza

Use the [http-transformations] stanza to define the HTTP transformation settings.

resource-name
Use the resource-name stanza entry to define HTTP transformation resources.

Parent topic: Stanza reference

resource-nameresource-nameUse the resource-name stanza entry to define HTTP transformation resources.resource-name stanza entryhttp-transformations stanzaentriesresource-namehttp-transformations stanzahttp-transformations stanzaresource-name entrySyntax resource-name = resource-file Description This configuration information is necessary to support WebSEAL HTTP transformations. You can use WebSEAL HTTP transformations to modify HTTP requests and HTTP responses (excluding the HTTP body) using XSLT. To enable the HTTP transformations for a particular resource, attach a POP to the appropriate part of the object space. This POP must contain an extended attribute with the name HTTPTransformation and one of the following values: Request = resource-name Response = resource-name For more details, see the information about HTTP transformations in the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy. Options resource-nameThe name of the HTTP transformation resource.resource-fileThe name of the resource file.You must restart WebSEAL for changes to an XSL rules file to take effect. Usage This stanza entry is optional. CommentsIf an HTTP transformation rule modifies the URI or host header of the request, WebSEAL reprocesses the transformed request. This reprocessing ensures that the transformation does not bypass WebSEAL authorization. This behavior also means that administrators can define HTTP transformations rules to send requests to different junctions.WebSEAL performs reprocessing (and authorization) on the first HTTP transformation only. Transformed requests undergo HTTP transformation again if there is an appropriate POP attached to the associated object space. However, WebSEAL does not reprocess the new requests that result from these subsequent transformations.Default value None. Example resourceOne = resourceOne.xsl [http-transformations] stanzaUse the [http-transformations] stanza to define the HTTP transformation settings.

resource-name

Use the resource-name stanza entry to define HTTP transformation resources.

Syntax

resource-name = resource-file

Description

This configuration information is necessary to support WebSEAL HTTP transformations. You can use WebSEAL HTTP transformations to modify HTTP requests and HTTP responses (excluding the HTTP body) using XSLT.

Note: To enable the HTTP transformations for a particular resource, attach a POP to the appropriate part of the object space. This POP must contain an extended attribute with the name HTTPTransformation and one of the following values:

Request = resource-name

Response = resource-name

For more details, see the information about HTTP transformations in the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Options

resource-name

The name of the HTTP transformation resource.

resource-file

The name of the resource file.

Note: You must restart WebSEAL for changes to an XSL rules file to take effect.

Usage

This stanza entry is optional.

Comments

If an HTTP transformation rule modifies the URI or host header of the request, WebSEAL reprocesses the transformed request. This reprocessing ensures that the transformation does not bypass WebSEAL authorization. This behavior also means that administrators can define HTTP transformations rules to send requests to different junctions.

Note: WebSEAL performs reprocessing (and authorization) on the first HTTP transformation only. Transformed requests undergo HTTP transformation again if there is an appropriate POP attached to the associated object space. However, WebSEAL does not reprocess the new requests that result from these subsequent transformations.

Default value

None.

Example

resourceOne = resourceOne.xsl

Parent topic: [http-transformations] stanza

[http-transformations:<resource-name>] stanzaUse this stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name> component of the stanza name must be changed to the actual name of the resource.http-transformations: resource-name stanzastanzashttp-transformations:<resource-name>Stanza referencecred-attr-nameUse the cred-attr-name stanza entry to define the credential attribute that is included in the XML input document and used when evaluating the HTTP transformation rule.request-matchUse this entry to define the pattern to be matched against the HTTP request line, which includes method, URI, and protocol.

[http-transformations:<resource-name>] stanza

Use this stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name> component of the stanza name must be changed to the actual name of the resource.

cred-attr-name
Use the cred-attr-name stanza entry to define the credential attribute that is included in the XML input document and used when evaluating the HTTP transformation rule.

request-match
Use this entry to define the pattern to be matched against the HTTP request line, which includes method, URI, and protocol.

Parent topic: Stanza reference

cred-attr-namecred-attr-nameIBM Security Access Manager for Web WebSEAL cred-attr-name stanza entryUse the cred-attr-name stanza entry to define the credential attribute that is included in the XML input document and used when evaluating the HTTP transformation rule.cred-attr-namestanzaentriescred-attr-namestanzastanzacred-attr-nameSyntax cred-attr-name = name Description This configuration entry can be specified multiple times if multiple credential attributes are required in the XML input document. The credential attributes are stored in a new XML element within the top level XML container <Credential>. For example:<HTTPResponse> <Credential> <Attributes> <Attribute name=AZN_CRED_PRINCIPAL_NAME>testuser</Attribute> </Attributes> </Credential> … </HTTPResponse> Options nameName of the credential attribute. Usage This stanza entry is optional. Default value None. Example cred-attr-name = AZN_CRED_PRINCIPAL_NAME [http-transformations:<resource-name>] stanzaUse this stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name> component of the stanza name must be changed to the actual name of the resource.

cred-attr-name

Use the cred-attr-name stanza entry to define the credential attribute that is included in the XML input document and used when evaluating the HTTP transformation rule.

Syntax

 cred-attr-name = name

Description

This configuration entry can be specified multiple times if multiple credential attributes are required in the XML input document. The credential attributes are stored in a new XML element within the top level XML container <Credential>. For example:

<HTTPResponse>
  <Credential>
    <Attributes>
      <Attribute name=AZN_CRED_PRINCIPAL_NAME>testuser</Attribute>
    </Attributes>
  </Credential>
       …
</HTTPResponse>

Options

name

Name of the credential attribute.

Usage

This stanza entry is optional.

Default value

None.

Example

cred-attr-name = AZN_CRED_PRINCIPAL_NAME

Parent topic: [http-transformations:<resource-name>] stanza

request-matchUse this entry to define the pattern to be matched against the HTTP request line, which includes method, URI, and protocol.preserve-inactivity-timeouthttp-transformations: resource-name stanzaentriespreserve-inactivity-timeouthttp-transformations:resource-name stanzahttp-transformations: resource-name stanzapreserve-inactivity-timeoutSyntax request-match = {request|response}:<request-line>Description This entry defines the pattern to be matched against the HTTP request line, which includes method, URI, and protocol. You can also match a request by using a host header. Use this option to selectively enable this function for a particular virtual host junction. To selectively match an entry based on a particular host header, add a prefix to the <request-line> with the string [<host>]. If you use this mechanism to match the request to a rule, the evaluation of the rule occurs early in the request processing. As a result, credential attributes are not available in the evaluation of the rule. If you want to use credential attributes in your request transformation, use the alternative POP mechanism for invoking the rule.Options {request | response}Determines whether the processing is conducted on the HTTP request or response. This value can be request or response.request-lineContains the request line to be matched against. The pattern matching is case-sensitive. You can use wildcard characters * and ?.Usage This stanza entry is optional. You can specify multiple entries if needed.Default value None.Example request-match = request:GET /index.html HTTP/1.1 request-match = response:GET /jct/* * request-match = response:[www.ibm.com]GET /login/*[http-transformations:<resource-name>] stanzaUse this stanza to house configuration that is specific to a particular HTTP transformation resource. The <resource-name> component of the stanza name must be changed to the actual name of the resource.

request-match

Use this entry to define the pattern to be matched against the HTTP request line, which includes method, URI, and protocol.

Syntax

request-match = {request|response}:<request-line>

Description

This entry defines the pattern to be matched against the HTTP request line, which includes method, URI, and protocol.

You can also match a request by using a host header. Use this option to selectively enable this function for a particular virtual host junction. To selectively match an entry based on a particular host header, add a prefix to the <request-line> with the string [<host>].

Note: If you use this mechanism to match the request to a rule, the evaluation of the rule occurs early in the request processing. As a result, credential attributes are not available in the evaluation of the rule. If you want to use credential attributes in your request transformation, use the alternative POP mechanism for invoking the rule.

Options

{request | response}

Determines whether the processing is conducted on the HTTP request or response. This value can be request or response.

request-line

Contains the request line to be matched against. The pattern matching is case-sensitive. You can use wildcard characters "*" and "?".

Usage

This stanza entry is optional.

You can specify multiple entries if needed.

Default value

None.

Example

request-match = request:GET /index.html HTTP/1.1
request-match = response:GET /jct/* *
request-match = response:[www.ibm.com]GET /login/*

Parent topic: [http-transformations:<resource-name>] stanza

[http-updates] stanzaIBM Security Access Manager for Web WebSEAL [http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files. http-updates stanzastanzashttp-updatesStanza referenceupdate-urlUse the update-url stanza entry to define the URL that references the HTTP file.proxyUse the proxy stanza entry to define the proxy server that is used when connecting to the HTTP server.replaceUse the replace stanza entry to perform a search and replace operation on text that is contained in the updated files.ssl-keyfile-labelUse the ssl-keyfile-label stanza entry to define the label of the certificate that is used for authentication to the HTTP server. This stanza entry is required only if client certificate authentication is required by the update server.ssl-server-dnUse the ssl-server-dn stanza entry to define the DN of the server. Use this configuration if you want to validate the DN that is contained in the server certificate of the update server.poll-periodUse the poll-period stanza entry to define the frequency that the update server is polled for updates.

[http-updates] stanza

Use the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

update-url
Use the update-url stanza entry to define the URL that references the HTTP file.

proxy
Use the proxy stanza entry to define the proxy server that is used when connecting to the HTTP server.

replace
Use the replace stanza entry to perform a search and replace operation on text that is contained in the updated files.

ssl-keyfile-label
Use the ssl-keyfile-label stanza entry to define the label of the certificate that is used for authentication to the HTTP server. This stanza entry is required only if client certificate authentication is required by the update server.

ssl-server-dn
Use the ssl-server-dn stanza entry to define the DN of the server. Use this configuration if you want to validate the DN that is contained in the server certificate of the update server.

poll-period
Use the poll-period stanza entry to define the frequency that the update server is polled for updates.

Parent topic: Stanza reference

update-urlUse the update-url stanza entry to define the URL that references the HTTP file.update-url stanza entryhttp-updates stanzaentriesupdate-urlhttp-updates stanzahttp-updates stanzaupdate-url entrySyntax update-url = URL Description Use this stanza entry to specify the URL for the HTTP file. Options URLThe URL that contains the HTTP file. Usage This stanza entry is required. Default value None. Example update-url = https://99.n.example.com/74767/api/snippets [http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

update-url

Use the update-url stanza entry to define the URL that references the HTTP file.

Syntax

update-url = URL

Description

Use this stanza entry to specify the URL for the HTTP file.

Options

URL

The URL that contains the HTTP file.

Usage

This stanza entry is required.

Default value

None.

Example

update-url = https://99.n.example.com/74767/api/snippets

Parent topic: [http-updates] stanza

proxyUse the proxy stanza entry to define the proxy server that is used when connecting to the HTTP server.proxy stanza entryhttp-updates stanzaentriesproxyhttp-updates stanzahttp-updates stanzaproxy entrySyntax proxy = host:port Description The proxy server that is used when connecting to the HTTP server. Options host:portSpecify the host name and port number of the proxy server. Usage This stanza entry is optional. If this entry is not present, then traffic goes to the server directly rather than going through a proxy. Default value None. Example proxy = www.example.com:8080 [http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

proxy

Use the proxy stanza entry to define the proxy server that is used when connecting to the HTTP server.

Syntax

proxy = host:port

Description

The proxy server that is used when connecting to the HTTP server.

Options

host:port

Specify the host name and port number of the proxy server.

Usage

This stanza entry is optional. If this entry is not present, then traffic goes to the server directly rather than going through a proxy.

Default value

None.

Example

proxy = www.example.com:8080

Parent topic: [http-updates] stanza

replaceUse the replace stanza entry to perform a search and replace operation on text that is contained in the updated files.replace stanza entryhttp-updates stanzaentriesreplacehttp-updates stanzahttp-updates stanzareplace entrySyntax replace = <search-patten>|<replace-text> Description Define the search pattern and the replacement text. Options <search-patten>The regular expression pattern that is to be matched.The | character cannot be used in the search-pattern text.<replace-text>The text that will replace the matched text. UsageMultiple instances of this configuration entry can be used if multiple substitutions are required. Default value None. Example replace = .*old|new [http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

replace

Use the replace stanza entry to perform a search and replace operation on text that is contained in the updated files.

Syntax

replace = <search-patten>|<replace-text>

Description

Define the search pattern and the replacement text.

Options

<search-patten>

The regular expression pattern that is to be matched.

Note: The "|" character cannot be used in the search-pattern text.

<replace-text>

The text that will replace the matched text.

Usage

Multiple instances of this configuration entry can be used if multiple substitutions are required.

Default value

None.

Example

replace = .*old|new

Parent topic: [http-updates] stanza

ssl-keyfile-labelUse the ssl-keyfile-label stanza entry to define the label of the certificate that is used for authentication to the HTTP server. This stanza entry is required only if client certificate authentication is required by the update server.ssl-keyfile-label stanza entryhttp-updates stanzaentriesssl-keyfile-labelhttp-updates stanzahttp-updates stanzassl-keyfile-label entrySyntax ssl-keyfile-label = label_name Description This certificate must be present in the certificate database that is used for junction communication. Options label_nameThe label of the certificate that is used for authentication to the HTTP server. Usage This stanza entry is optional. Default value None. Example ssl-keyfile-label = "samplelabel" [http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

ssl-keyfile-label

Use the ssl-keyfile-label stanza entry to define the label of the certificate that is used for authentication to the HTTP server. This stanza entry is required only if client certificate authentication is required by the update server.

Syntax

ssl-keyfile-label = label_name

Description

This certificate must be present in the certificate database that is used for junction communication.

Options

label_name

The label of the certificate that is used for authentication to the HTTP server.

Usage

This stanza entry is optional.

Default value

None.

Example

ssl-keyfile-label = "samplelabel"

Parent topic: [http-updates] stanza

ssl-server-dnUse the ssl-server-dn stanza entry to define the DN of the server. Use this configuration if you want to validate the DN that is contained in the server certificate of the update server.ssl-server-dn stanza entryhttp-updates stanzaentriesssl-server-dnhttp-updates stanzahttp-updates stanzassl-server-dn entrySyntax ssl-server-dn = DN_value Description This configuration entry is used only if an SSL connection is established with the server and an SSL key file label has been specified. Options DN_valueThe DN of the server Usage This stanza entry is optional. Default value None. Example ssl-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US [http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

ssl-server-dn

Use the ssl-server-dn stanza entry to define the DN of the server. Use this configuration if you want to validate the DN that is contained in the server certificate of the update server.

Syntax

ssl-server-dn = DN_value

Description

This configuration entry is used only if an SSL connection is established with the server and an SSL key file label has been specified.

Options

DN_value

The DN of the server

Usage

This stanza entry is optional.

Default value

None.

Example

ssl-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US

Parent topic: [http-updates] stanza

poll-periodUse the poll-period stanza entry to define the frequency that the update server is polled for updates. poll-period stanza entryhttp-updates stanzaentriespoll-periodhttp-updates stanzahttp-updates stanzapoll-period entrySyntax poll-period = seconds Description This value is defined in seconds. Options secondsThe frequency in seconds that the update server is polled for updates. Usage This stanza entry is required. Default value None. Example poll-period = 3600 [http-updates] stanzaUse the [http-updates] stanza to configure WebSEAL so that it can communicate with an HTTP server to retrieve updates to files.

poll-period

Use the poll-period stanza entry to define the frequency that the update server is polled for updates.

Syntax

poll-period = seconds

Description

This value is defined in seconds.

Options

seconds

The frequency in seconds that the update server is polled for updates.

Usage

This stanza entry is required.

Default value

None.

Example

poll-period = 3600

Parent topic: [http-updates] stanza

[ICAP:<resource>] stanza[ICAP:<resource>] stanzaUse the [ICAP:<resource>] stanza to define a single ICAP resource. ICAP: <resource> stanzastanzasicapThe <resource> component of the stanza name must be changed to the actual name of the resource. To enable the ICAP resource for a particular object, a POP must be attached to the appropriate part of the object space. This POP must contain an extended attribute with the name ICAP, and a value that is equal to the name of the configured ICAP resource.Stanza referenceURLUse the URL stanza entry to define the complete URL on which the ICAP server is expecting requests and whether to use TCP or SSL for the connection to the server.transactionUse the transaction stanza entry to define the transaction for which the resource is invoked.timeoutUse the timeout stanza entry to define the maximum length of time that WebSEAL waits for a response from the ICAP server.ssl-keyfile-labelIf client certificate authentication is required for the SSL connection to the ICAP server, use this entry to define the label of the certificate to use from the keystore.

[ICAP:<resource>] stanza

Use the [ICAP:<resource>] stanza to define a single ICAP resource.

The <resource> component of the stanza name must be changed to the actual name of the resource. To enable the ICAP resource for a particular object, a POP must be attached to the appropriate part of the object space. This POP must contain an extended attribute with the name ICAP, and a value that is equal to the name of the configured ICAP resource.

URL
Use the URL stanza entry to define the complete URL on which the ICAP server is expecting requests and whether to use TCP or SSL for the connection to the server.

transaction
Use the transaction stanza entry to define the transaction for which the resource is invoked.

timeout
Use the timeout stanza entry to define the maximum length of time that WebSEAL waits for a response from the ICAP server.

ssl-keyfile-label
If client certificate authentication is required for the SSL connection to the ICAP server, use this entry to define the label of the certificate to use from the keystore.

Parent topic: Stanza reference

URLURLUse the URL stanza entry to define the complete URL on which the ICAP server is expecting requests and whether to use TCP or SSL for the connection to the server.internet content adaptation protocolICAP stanzaICAP: resource stanzastanzaICAP: resourceSyntax URL = URL_string Description The complete URL on which the ICAP server is expecting requests. Options URL_stringURL string. To establish a TCP connection to the ICAP server, use the following format:URL = icap://<ICAP Server host/IP[:port]>/<path>To establish an SSL connection to the ICAP server, use the following format:URL = icaps://<ICAP Server host/IP[:port]>/<path>The system uses the keystore that is configured in the [junction] stanza if it exists. If not, the system uses the keystore that is configured in the [ssl] stanza. Usage Required Default value None Example URL = icap://icap.example.net:1344/filter?mode=strict In this example, a TCP connection is established. URL = icaps://icap.example.net:1345/filter?mode=strict In this example, an SSL connection is established.[ICAP:<resource>] stanzaUse the [ICAP:<resource>] stanza to define a single ICAP resource.

URL

Use the URL stanza entry to define the complete URL on which the ICAP server is expecting requests and whether to use TCP or SSL for the connection to the server.

Syntax

URL = URL_string

Description

The complete URL on which the ICAP server is expecting requests.

Options

URL_string

URL string.

To establish a TCP connection to the ICAP server, use the following format:

URL = icap://<ICAP Server host/IP[:port]>/<path>

To establish an SSL connection to the ICAP server, use the following format:

URL = icaps://<ICAP Server host/IP[:port]>/<path>

The system uses the keystore that is configured in the [junction] stanza if it exists. If not, the system uses the keystore that is configured in the [ssl] stanza.

Usage

Required

Default value

None

Example

URL = icap://icap.example.net:1344/filter?mode=strict

Note: In this example, a TCP connection is established.

URL = icaps://icap.example.net:1345/filter?mode=strict

Note: In this example, an SSL connection is established.

Parent topic: [ICAP:<resource>] stanza

transactiontransactionUse the transaction stanza entry to define the transaction for which the resource is invoked.internet content adaptation protocolICAP stanzaICAP: resource stanzastanzaICAP: resourceSyntax transaction = {req | rsp} Description The transaction for which the resource is invoked. Options reqThe ICAP server is invoked on the HTTP request.rspThe ICAP server is invoked on the HTTP response. Usage Required Default value None Example transaction = req [ICAP:<resource>] stanzaUse the [ICAP:<resource>] stanza to define a single ICAP resource.

transaction

Use the transaction stanza entry to define the transaction for which the resource is invoked.

Syntax

transaction = {req | rsp}

Description

The transaction for which the resource is invoked.

Options

req

The ICAP server is invoked on the HTTP request.

rsp

The ICAP server is invoked on the HTTP response.

Usage

Required

Default value

None

Example

transaction = req

Parent topic: [ICAP:<resource>] stanza

timeouttimeoutUse the timeout stanza entry to define the maximum length of time that WebSEAL waits for a response from the ICAP server.internet content adaptation protocolICAP stanzaICAP: resource stanzatstanzaICAP:resourceSyntax timeout = seconds Description The maximum length of time (in seconds) that WebSEAL waits for a response from the ICAP server. Options secondsThe time in seconds, that WebSEAL waits for a response from the ICAP server. Usage Required Default value None Example timeout = 120 [ICAP:<resource>] stanzaUse the [ICAP:<resource>] stanza to define a single ICAP resource.

timeout

Use the timeout stanza entry to define the maximum length of time that WebSEAL waits for a response from the ICAP server.

Syntax

timeout = seconds

Description

The maximum length of time (in seconds) that WebSEAL waits for a response from the ICAP server.

Options

seconds

The time in seconds, that WebSEAL waits for a response from the ICAP server.

Usage

Required

Default value

None

Example

timeout = 120

Parent topic: [ICAP:<resource>] stanza

ssl-keyfile-labelIf client certificate authentication is required for the SSL connection to the ICAP server, use this entry to define the label of the certificate to use from the keystore.ssl-keyfile-label stanza entryICAP:resource stanzaentriesssl-keyfile-labelICAP:resource stanzaICAP: resource stanza ssl-keyfile-label entrySyntax ssl-keyfile-label = labelDescription This entry identifies the label of the certificate in the keystore to use when the reverse proxy establishes an SSL connection to the ICAP server.Options labelThe label of the client certificate to use from the keystore.Usage This entry is required only if client certificate authentication is needed.Default value NoneExample ssl-keyfile-label = my_certificate[ICAP:<resource>] stanzaUse the [ICAP:<resource>] stanza to define a single ICAP resource.

ssl-keyfile-label

If client certificate authentication is required for the SSL connection to the ICAP server, use this entry to define the label of the certificate to use from the keystore.

Syntax

ssl-keyfile-label = label

Description

This entry identifies the label of the certificate in the keystore to use when the reverse proxy establishes an SSL connection to the ICAP server.

Options

label

The label of the client certificate to use from the keystore.

Usage

This entry is required only if client certificate authentication is needed.

Default value

None

Example

ssl-keyfile-label = my_certificate

Parent topic: [ICAP:<resource>] stanza

[interfaces] stanza[interfaces] stanzainterfaces stanzastanzasinterfacesStanza referenceinterface_name

[interfaces] stanza

interface_name

Parent topic: Stanza reference

interface_nameinterface_nameinterface_name stanza entryinterfaces stanzaentriesinterface_nameinterfaces stanzainterfaces stanzainterface_name entrySyntax interface_name = property=value[;property=value...]Description This stanza is used to define additional interfaces on which this WebSEAL instance can receive requests. A network interface is defined as the combined set of values for a specific group of properties that include HTTP or HTTPS port setting, IP address, worker threads setting, and certificate handling setting.Options propertyInterface property. Can be selected from: network-interface=<ipAddress> http-port=<port> | "disabled" https-port=<port> | "disabled" certificate-label=<keyFileLabel> accept-client-certs="never" | "required" | "optional" | "prompt_as_needed" worker-threads=<count> | "default"valueValue of the property. Default values, if not present, include: network-interface=0.0.0.0 http-port ="disabled" https-port ="disabled" certificate-label= (Uses key marked as default in key file.) accept-client-certs="never" worker-threads="default"Usage Entries in this stanza are optional.Default value None.Example (Entered as one line:) support = network-interface=9.0.0.8;https-port=444;certificate-label=WS6; worker-threads=16[interfaces] stanza

interface_name

Syntax

interface_name = property=value[;property=value...]

Description

This stanza is used to define additional interfaces on which this WebSEAL instance can receive requests.

A network interface is defined as the combined set of values for a specific group of properties that include HTTP or HTTPS port setting, IP address, worker threads setting, and certificate handling setting.

Options

property

Interface property. Can be selected from:

network-interface=<ipAddress>
http-port=<port> | "disabled"
https-port=<port> | "disabled"
certificate-label=<keyFileLabel>
accept-client-certs="never" | "required" | "optional" |
"prompt_as_needed"
worker-threads=<count> | "default"

value

Value of the property. Default values, if not present, include:

network-interface=0.0.0.0
http-port	="disabled"
https-port	="disabled"
certificate-label= (Uses key marked as default in key file.)
accept-client-certs="never"
worker-threads="default"

Usage

Entries in this stanza are optional.

Default value

None.

Example

(Entered as one line:)

support = network-interface=9.0.0.8;https-port=444;certificate-label=WS6;
worker-threads=16

Parent topic: [interfaces] stanza

[itim] stanza[itim] stanzaitim stanzastanzasitimThis stanza contains the configuration options for the IBM Security Identity Manager Password Synchronization Plug-in. The Password Synchronization Plug-in synchronizes user passwords from IBM Security Access Manager for Web to IBM Security Identity Manager, previously known as IBM Tivoli Identity Manager.For more information about this plug-in, see the Password Synchronization Plug-in for IBM Security Access Manager Installation and Configuration Guide, which you can find in the IBM Security Identity Manager Knowledge Center.Stanza referenceis-enableditim-server-nameitim-servlet-contextkeydatabase-filekeydatabase-passwordkeydatabase-password-fileprincipal-nameprincipal-passwordservice-password-dnservice-source-dnservice-token-card-dnservlet-port

[itim] stanza

This stanza contains the configuration options for the IBM Security Identity Manager Password Synchronization Plug-in. The Password Synchronization Plug-in synchronizes user passwords from IBM Security Access Manager for Web to IBM Security Identity Manager, previously known as IBM Tivoli Identity Manager.

For more information about this plug-in, see the Password Synchronization Plug-in for IBM Security Access Manager Installation and Configuration Guide, which you can find in the IBM Security Identity Manager Knowledge Center.

is-enabled

itim-server-name

itim-servlet-context

keydatabase-file

keydatabase-password

keydatabase-password-file

principal-name

principal-password

service-password-dn

service-source-dn

service-token-card-dn

servlet-port

Parent topic: Stanza reference

is-enabledis-enabledis-enabled stanza entryitim stanzaentriesis-enableditim stanzaitim stanzais-enabled entrySyntax is-enabled = {true|false} Description Determines whether the Password Synchronization Plug-in for IBM Security Identity Manager, is enabled. Options trueEnables the Password Synchronization Plug-in.falseDisables the Password Synchronization Plug-in. Usage This stanza entry is optional. Default value false Example is-enabled = false [itim] stanza

is-enabled

Syntax

is-enabled = {true|false}

Description

Determines whether the Password Synchronization Plug-in for IBM Security Identity Manager, is enabled.

Options

true

Enables the Password Synchronization Plug-in.

false

Disables the Password Synchronization Plug-in.

Usage

This stanza entry is optional.

Default value

false

Example

is-enabled = false

Parent topic: [itim] stanza

itim-server-nameitim-server-nameitim-server-name stanza entryitim stanzaentriesitim-server-nameitim stanzaitim stanzaitim-server-name entrySyntax itim-server-name = <itim_server> Description Specifies the host name or IP address of the server that is running IBM Security Identity Manager.In a WebSphere Application Server cluster environment, you must configure SSL for the IBM HTTP Server. In a WebSphere Application Server single-server environment, you do not need to configure SSL for the IBM HTTP Server. Options <itim_server>Specifies the host name or IP address of the IBM Security Identity Manager server that communicates with IBM Security Access Manager for Web. Usage This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true. Default value None. Example itim-server-name = identityMgr01.ibm.com [itim] stanza

itim-server-name

Syntax

itim-server-name = <itim_server>

Description

Specifies the host name or IP address of the server that is running IBM Security Identity Manager.

Note: In a WebSphere® Application Server cluster environment, you must configure SSL for the IBM® HTTP Server. In a WebSphere Application Server single-server environment, you do not need to configure SSL for the IBM HTTP Server.

Options

<itim_server>

Specifies the host name or IP address of the IBM Security Identity Manager server that communicates with IBM Security Access Manager for Web.

Usage

This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true.

Default value

None.

Example

itim-server-name = identityMgr01.ibm.com

Parent topic: [itim] stanza

itim-servlet-contextitim-servlet-contextitim-servlet-context stanza entryitim stanzaentriesitim-servlet-contextitim stanzaitim stanzaitim-servlet-context entrySyntax itim-servlet-context = <directory_path> Description Indicates the password synchronization context root on the application server. Options <directory_path>Specifies the directory path for the password synchronization context root on the application server. Usage This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true. Default value /passwordsynch/synch. Exampleitim-servlet-context = /passwordsynch/synch [itim] stanza

itim-servlet-context

Syntax

itim-servlet-context = <directory_path>

Description

Indicates the password synchronization context root on the application server.

Options

<directory_path>

Specifies the directory path for the password synchronization context root on the application server.

Usage

This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true.

Default value

/passwordsynch/synch.

Example

itim-servlet-context = /passwordsynch/synch

Parent topic: [itim] stanza

keydatabase-filekeydatabase-filekeydatabase-file stanza entryitim stanzaentrieskeydatabase-fileitim stanzaitim stanzakeydatabase-file entrySyntax keydatabase-file = <file_name> Description Specifies the name of the key database file. Options <file_name>The name of the key database file. UsageThis stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true. Default value None. Example keydatabase-file = revpwdsync.kdb [itim] stanza

keydatabase-file

Syntax

keydatabase-file = <file_name>

Description

Specifies the name of the key database file.

Options

<file_name>

The name of the key database file.

Usage

This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true.

Default value

None.

Example

keydatabase-file = revpwdsync.kdb

Parent topic: [itim] stanza

keydatabase-passwordkeydatabase-passwordkeydatabase-password stanza entryitim stanzaentrieskeydatabase-passworditim stanzaitim stanzakeydatabase-password entrySyntax keydatabase-password = <db_password> Description Specifies the password for the key database in the keydatabase-file. The IBM Security Web Gateway appliance uses stash files to manage the passwords for key files. As a result, key file passwords are not available to the administrator of the appliance. If you do not know the password for the key database file, you can use the keydatabase-password-file entry to specify the name of the password stash file instead. If you configure the keydatabase-password-file entry, you can leave the keydatabase-password entry unconfigured.The Password Synchronization Plug-in requires knowledge of the database password. Therefore, if you do not configure the keydatabase-password-file entry, you must configure the keydatabase-password entry. To complete this configuration, follow this process: Create the key file externally to the appliance. Use a known password to generate the new key file.Import the key file on to the appliance.Configure the keydatabase-password configuration entry with the known password for the Password Synchronization Plug-in. Options <db_password>Specifies the password for the key database file. UsageIf the is_enabled configuration entry in the [itim] stanza is set to true, you must set one of the following entries for the key database password:keydatabase-passwordkeydatabase-password-file If there is a value configured for both of these entries, WebSEAL uses the keydatabase-password. Default value None. Example keydatabase-password = myPassword1 [itim] stanza

keydatabase-password

Syntax

keydatabase-password = <db_password>

Description

Specifies the password for the key database in the keydatabase-file.

Note: The IBM Security Web Gateway appliance uses stash files to manage the passwords for key files. As a result, key file passwords are not available to the administrator of the appliance.

If you do not know the password for the key database file, you can use the keydatabase-password-file entry to specify the name of the password stash file instead. If you configure the keydatabase-password-file entry, you can leave the keydatabase-password entry unconfigured.

The Password Synchronization Plug-in requires knowledge of the database password. Therefore, if you do not configure the keydatabase-password-file entry, you must configure the keydatabase-password entry. To complete this configuration, follow this process:

Create the key file externally to the appliance. Use a known password to generate the new key file.

Import the key file on to the appliance.

Configure the keydatabase-password configuration entry with the known password for the Password Synchronization Plug-in.

Options

<db_password>

Specifies the password for the key database file.

Usage

If the is_enabled configuration entry in the [itim] stanza is set to true, you must set one of the following entries for the key database password:

keydatabase-password

keydatabase-password-file

Note: If there is a value configured for both of these entries, WebSEAL uses the keydatabase-password.

Default value

None.

Example

keydatabase-password = myPassword1

Parent topic: [itim] stanza

keydatabase-password-filekeydatabase-password-filekeydatabase-password-file stanza entryitim stanzaentrieskeydatabase-password-fileitim stanzaitim stanzakeydatabase-password-file entrySyntax keydatabase-password-file = <password_stash_file> Description Specifies the name of the stash file that stores the password for the key database. Options <password_stash_file>Specifies the name of the stash file that stores the password for the key database. UsageIf the is_enabled configuration entry in the [itim] stanza is set to true, you must set one of the following entries for the key database password:keydatabase-passwordkeydatabase-password-file If there is a value configured for both of these entries, WebSEAL uses the keydatabase-password.Default value None. Example keydatabase-password-file = dbPassword.sth [itim] stanza

keydatabase-password-file

Syntax

keydatabase-password-file = <password_stash_file>

Description

Specifies the name of the stash file that stores the password for the key database.

Options

<password_stash_file>

Specifies the name of the stash file that stores the password for the key database.

Usage

If the is_enabled configuration entry in the [itim] stanza is set to true, you must set one of the following entries for the key database password:

keydatabase-password

keydatabase-password-file

Note: If there is a value configured for both of these entries, WebSEAL uses the keydatabase-password.

Default value

None.

Example

keydatabase-password-file = dbPassword.sth

Parent topic: [itim] stanza

principal-nameprincipal-nameprincipal-name stanza entryitim stanzaentriesprincipal-nameitim stanzaitim stanzaprincipal-name entrySyntax principal-name = <user_name> Description Specifies an IBM Security Identity Manager user ID that has the necessary permissions to complete the check and synchronization operations. Do not use the ITIM manager account for this purpose. Create a separate account on the IBM Security Identity Manager server with the same permissions. Options <user_name>Specifies the name of the IBM Security Identity Manager user that the Password Synchronization Plug-in can use to request synchronization operations. UsageThis stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true. Default value None. Example principal-name = admin_userA [itim] stanza

principal-name

Syntax

principal-name = <user_name>

Description

Specifies an IBM Security Identity Manager user ID that has the necessary permissions to complete the check and synchronization operations.

Note: Do not use the ITIM manager account for this purpose. Create a separate account on the IBM Security Identity Manager server with the same permissions.

Options

<user_name>

Specifies the name of the IBM Security Identity Manager user that the Password Synchronization Plug-in can use to request synchronization operations.

Usage

This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true.

Default value

None.

Example

principal-name = admin_userA

Parent topic: [itim] stanza

principal-passwordprincipal-passwordprincipal-password stanza entryitim stanzaentriesprincipal-passworditim stanzaitim stanzaprincipal-password entrySyntax principal-password = <user_password> Description Specifies the password of the IBM Security Identity Manager user that is specified by principal-name. Options <user_password>Specifies the password for the IBM Security Identity Manager account. UsageThis stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true. Default value None. Example principal-password = myPassword1 [itim] stanza

principal-password

Syntax

principal-password = <user_password>

Description

Specifies the password of the IBM Security Identity Manager user that is specified by principal-name.

Options

<user_password>

Specifies the password for the IBM Security Identity Manager account.

Usage

This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true.

Default value

None.

Example

principal-password = myPassword1

Parent topic: [itim] stanza

service-password-dnservice-password-dnservice-password-dn stanza entryitim stanzaentriesservice-password-dnitim stanzaitim stanzaservice-password-dn entrySyntax service-password-dn = <service_pseudo_dn> Description Defines the pseudo–distinguished name of the service that issues the password synchronization request. The Password Synchronization Plug-in uses the service-password-dn pseudo-distinguished name for requests that use the standard password authentication method. If this configuration entry is specified, it overrides service-source-dn when using the password authentication method. You can specify more than one pseudo-distinguished name. Separate the pseudo-distinguished names with a semicolon (;) character. The Password Synchronization Plug-in iterates through the list of service names until it finds an account for one of the services. If the Password Synchronization Plug-in cannot find an account for the specified services, it returns an error message.Each pseudo-distinguished name is a comma-separated list of the following attributes: The erservicename attribute of the Security Access Manager service name, as defined in IBM Security Identity Manager. For example, erservicename=TAM 6.0 Service.The o attribute of the organization to which the service belongs. For example, o=International Business Machines.The ou and dc attributes from the service distinguished name in IBM Security Identity Manager. For example, ou=IBM,dc=com.The pseudo-distinguished name that is formed from these example values is: erservicename=TAM 6.0 Service,o=International Business Machines, ou=IBM,dc=com. Options <service_pseudo_dn>Specifies the service pseudo–distinguished name for the standard password authentication method. UsageIf the is_enabled configuration entry in the [itim] stanza is set to true, then you must configure at least one of the following configuration entries: service-source-dnservice-password-dnservice-token-card-dn Default value None. Example service-password-dn = erservicename=ISAM Employees Service,o=IBM,ou=IBM,dc=com [itim] stanza

service-password-dn

Syntax

service-password-dn = <service_pseudo_dn>

Description

Defines the pseudo–distinguished name of the service that issues the password synchronization request.

The Password Synchronization Plug-in uses the service-password-dn pseudo-distinguished name for requests that use the standard password authentication method. If this configuration entry is specified, it overrides service-source-dn when using the password authentication method.

Note: You can specify more than one pseudo-distinguished name. Separate the pseudo-distinguished names with a semicolon (;) character. The Password Synchronization Plug-in iterates through the list of service names until it finds an account for one of the services. If the Password Synchronization Plug-in cannot find an account for the specified services, it returns an error message.

Each pseudo-distinguished name is a comma-separated list of the following attributes:

The erservicename attribute of the Security Access Manager service name, as defined in IBM Security Identity Manager. For example, erservicename=TAM 6.0 Service.

The o attribute of the organization to which the service belongs. For example, o=International Business Machines.

The ou and dc attributes from the service distinguished name in IBM Security Identity Manager. For example, ou=IBM,dc=com.

The pseudo-distinguished name that is formed from these example values is: erservicename=TAM 6.0 Service,o=International Business Machines, ou=IBM,dc=com.

Options

<service_pseudo_dn>

Specifies the service pseudo–distinguished name for the standard password authentication method.

Usage

If the is_enabled configuration entry in the [itim] stanza is set to true, then you must configure at least one of the following configuration entries:

service-source-dn

service-password-dn

service-token-card-dn

Default value

None.

Example

service-password-dn = erservicename=ISAM Employees Service,o=IBM,ou=IBM,dc=com

Parent topic: [itim] stanza

service-source-dnservice-source-dnservice-source-dn stanza entryitim stanzaentriesservice-source-dnitim stanzaitim stanzaservice-source-dn entrySyntax service-source-dn = <service_pseudo_dn> Description Defines the pseudo–distinguished name of the service that issues the password synchronization request. The service-source-dn is for the pseudo-distinguished name for all authentication methods.You can specify more than one pseudo-distinguished name in the value of this configuration entry. Separate the pseudo-distinguished names with a semicolon (;) character. The Password Synchronization Plug-in iterates through the list of service names until it finds an account for one of the services. If the Password Synchronization Plug-in cannot find an account for the specified services, it returns an error message.Each pseudo-distinguished name is a comma-separated list of the following attributes: The erservicename attribute of the Security Access Manager service name, as defined in IBM Security Identity Manager. For example, erservicename=TAM 6.0 Service.The o attribute of the organization to which the service belongs. For example, o=International Business Machines.The ou and dc attributes from the service distinguished name in IBM Security Identity Manager. For example, ou=IBM,dc=com.The pseudo-distinguished name that is formed from these example values is: erservicename=TAM 6.0 Service,o=International Business Machines, ou=IBM,dc=com. Options <service_pseudo_dn>Specifies the service pseudo–distinguished name for all authentication methods. UsageIf the is_enabled configuration entry in the [itim] stanza is set to true, then you must configure at least one of the following configuration entries: service-source-dnservice-password-dnservice-token-card-dn Default value None. Example service-source-dn = erservicename=ISAM Employees Service,o=IBM,ou=IBM, dc=com;erservicename=TAM Customers Service,o=IBM,ou=IBM,dc=com [itim] stanza

service-source-dn

Syntax

service-source-dn = <service_pseudo_dn>

Description

Defines the pseudo–distinguished name of the service that issues the password synchronization request. The service-source-dn is for the pseudo-distinguished name for all authentication methods.

Note: You can specify more than one pseudo-distinguished name in the value of this configuration entry. Separate the pseudo-distinguished names with a semicolon (;) character. The Password Synchronization Plug-in iterates through the list of service names until it finds an account for one of the services. If the Password Synchronization Plug-in cannot find an account for the specified services, it returns an error message.

Each pseudo-distinguished name is a comma-separated list of the following attributes:

The erservicename attribute of the Security Access Manager service name, as defined in IBM Security Identity Manager. For example, erservicename=TAM 6.0 Service.

The o attribute of the organization to which the service belongs. For example, o=International Business Machines.

The ou and dc attributes from the service distinguished name in IBM Security Identity Manager. For example, ou=IBM,dc=com.

The pseudo-distinguished name that is formed from these example values is: erservicename=TAM 6.0 Service,o=International Business Machines, ou=IBM,dc=com.

Options

<service_pseudo_dn>

Specifies the service pseudo–distinguished name for all authentication methods.

Usage

If the is_enabled configuration entry in the [itim] stanza is set to true, then you must configure at least one of the following configuration entries:

service-source-dn

service-password-dn

service-token-card-dn

Default value

None.

Example

service-source-dn = erservicename=ISAM Employees Service,o=IBM,ou=IBM,
dc=com;erservicename=TAM Customers Service,o=IBM,ou=IBM,dc=com

Parent topic: [itim] stanza

service-token-card-dnservice-token-card-dnservice-token-card-dn stanza entryitim stanzaentriesservice-token-card-dnitim stanzaitim stanzaservice-token-card-dn entrySyntax service-token-card-dn = <service_pseudo_dn> Description Defines the pseudo–distinguished name of the service that issues the password synchronization request. The Password Synchronization Plug-in uses the service-token-card-dn pseudo-distinguished name for requests that use the token card authentication method. If this configuration entry is specified, it overrides service-source-dn when using the token card authentication method.You can specify more than one pseudo-distinguished name. Separate the pseudo-distinguished names with a semicolon (;). The Password Synchronization Plug-in iterates through the list of service names until it finds an account for one of the services. If the Password Synchronization Plug-in cannot find an account for the specified services, it returns an error message.Each pseudo-distinguished name is a comma-separated list of the following attributes: The erservicename attribute of the Security Access Manager service name, as defined in IBM Security Identity Manager. For example, erservicename=TAM 6.0 Service.The o attribute of the organization to which the service belongs. For example, o=International Business Machines.The ou and dc attributes from the service distinguished name in IBM Security Identity Manager. For example, ou=IBM,dc=com.The pseudo-distinguished name that is formed from these example values is: erservicename=TAM 6.0 Service,o=International Business Machines, ou=IBM,dc=com. Options <service_pseudo_dn>Specifies the service pseudo–distinguished name for the token card authentication method. UsageIf the is_enabled configuration entry in the [itim] stanza is set to true then you must configure at least one of the following configuration entries: service-source-dnservice-password-dnservice-token-card-dn Default value None. Example service-token-card-dn = erservicename=ISAM Employees Service,o=IBM,ou=IBM,dc=com [itim] stanza

service-token-card-dn

Syntax

service-token-card-dn = <service_pseudo_dn>

Description

Defines the pseudo–distinguished name of the service that issues the password synchronization request.

The Password Synchronization Plug-in uses the service-token-card-dn pseudo-distinguished name for requests that use the token card authentication method. If this configuration entry is specified, it overrides service-source-dn when using the token card authentication method.

Note: You can specify more than one pseudo-distinguished name. Separate the pseudo-distinguished names with a semicolon (;). The Password Synchronization Plug-in iterates through the list of service names until it finds an account for one of the services. If the Password Synchronization Plug-in cannot find an account for the specified services, it returns an error message.

Each pseudo-distinguished name is a comma-separated list of the following attributes:

The erservicename attribute of the Security Access Manager service name, as defined in IBM Security Identity Manager. For example, erservicename=TAM 6.0 Service.

The o attribute of the organization to which the service belongs. For example, o=International Business Machines.

The ou and dc attributes from the service distinguished name in IBM Security Identity Manager. For example, ou=IBM,dc=com.

The pseudo-distinguished name that is formed from these example values is: erservicename=TAM 6.0 Service,o=International Business Machines, ou=IBM,dc=com.

Options

<service_pseudo_dn>

Specifies the service pseudo–distinguished name for the token card authentication method.

Usage

If the is_enabled configuration entry in the [itim] stanza is set to true then you must configure at least one of the following configuration entries:

service-source-dn

service-password-dn

service-token-card-dn

Default value

None.

Example

service-token-card-dn = erservicename=ISAM Employees Service,o=IBM,ou=IBM,dc=com

Parent topic: [itim] stanza

servlet-portservlet-portservlet-port stanza entryitim stanzaentriesservlet-portitim stanzaitim stanzaservlet-port entrySyntax servlet-port = <port_number> Description Specifies the port number for communicating with the IBM Security Identity Manager server that is specified by the itim-server-name configuration entry. The default HTTPS port is 9443 for a single server configuration and 443 for a IBM Security Identity Manager cluster with HTTP SSL configured. Options <port_number>Specifies the port number for communication with the IBM Security Identity Manager server. Usage This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true. Default value 9443 Example servlet-port = 9443 [itim] stanza

servlet-port

Syntax

servlet-port = <port_number>

Description

Specifies the port number for communicating with the IBM Security Identity Manager server that is specified by the itim-server-name configuration entry.

The default HTTPS port is 9443 for a single server configuration and 443 for a IBM Security Identity Manager cluster with HTTP SSL configured.

Options

<port_number>

Specifies the port number for communication with the IBM Security Identity Manager server.

Usage

This stanza entry is required when the is_enabled configuration entry in the [itim] stanza is set to true.

Default value

9443

Example

servlet-port = 9443

Parent topic: [itim] stanza

[jdb-cmd:replace] stanza[jdb-cmd:replace] stanzajdb-cmd:replace stanzaStanza referencejct-id=search-attr-value|replace-attr-value

[jdb-cmd:replace] stanza

jct-id=search-attr-value|replace-attr-value

Parent topic: Stanza reference

jct-id=search-attr-value|replace-attr-valuejct-id=search-attr-value|replace-attr-valueipaddr-auth stanza entryipaddr stanzaentriesipaddr-authipaddr stanzaipaddr stanzaipaddr-auth entrySyntax jct-id=search-attr-value|replace-attr-value Description Defines the mapping rules for the jdb import command. These mapping rules are applied to each attribute in the junction archive file before you import the new junction database. Options jct-idRefers to the junction point for a standard junction which includes the leading ’/’ (slash) or the virtual host label for a virtual host junction.search-attr-valueSpecifies the attribute value in the junction definition for which you want to search and replace.replace-attr-valueSpecifies the new attribute value in the junction definition for which you want to search and replace. Usage This stanza entry is not required. Default value None. Example /test-jct = webseal.au.ibm.com|webseal.gc.au.ibm.com [jdb-cmd:replace] stanza

jct-id=search-attr-value|replace-attr-value

Syntax

jct-id=search-attr-value|replace-attr-value

Description

Defines the mapping rules for the jdb import command. These mapping rules are applied to each attribute in the junction archive file before you import the new junction database.

Options

jct-id

Refers to the junction point for a standard junction which includes the leading ’/’ (slash) or the virtual host label for a virtual host junction.

search-attr-value

Specifies the attribute value in the junction definition for which you want to search and replace.

replace-attr-value

Specifies the new attribute value in the junction definition for which you want to search and replace.

Usage

This stanza entry is not required.

Default value

None.

Example

/test-jct = webseal.au.ibm.com|webseal.gc.au.ibm.com

Parent topic: [jdb-cmd:replace] stanza

[junction] stanza[junction] stanzajunction stanzastanzasjunctionStanza referenceallow-backend-domain-cookiesUse the allow-backend-domain-cookies stanza entry to control whether WebSEAL sends domain cookies from a back-end server to a client.always-send-kerberos-tokensIndicates whether WebSEAL sends a security token for every HTTP request or whether WebSEAL waits for a 401 response before it adds the security token.basicauth-dummy-passwdUse the basicauth-dummy-passwd stanza entry to specify the global password for WebSEAL to use when it supplies basic authentication data over junctions that were created with the -b supply argument.crl-ldap-serverUse the crl-ldap-server stanza entry in the [junction] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during authentication across SSL junctions.crl-ldap-server-portUse the crl-ldap-server-port entry in the [junction] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.crl-ldap-userUse the crl-ldap-user entry in the [junction] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server. crl-ldap-user-passwordUse the crl-ldap-user-password entry in the [junction] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.kerberos-service-nameUse the kerberos-service-name entry to set the service principal name of the target.disable-local-junctionsUse the disable-local-junctions stanza entry to control whether WebSEAL serves pages from a local web server through local junctions. disable-ssl-v2Use the disable-ssl-v2 entry in the [junction] stanza to control whether WebSEAL supports SSL version 2 for junction connections.disable-ssl-v3Use the disable-ssl-v3 entry in the [junction] stanza to control whether WebSEAL supports SSL version 3 for junction connections.disable-tls-v1Use the disable-tls-v1 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1 for junction connections.disable-tls-v11Use the disable-tls-v11 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.1 for junction connections.disable-tls-v12Use the disable-tls-v12 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.2 for junction connections.dont-reprocess-jct-404sUse the dont-reprocess-jct-404s stanza entry to control whether WebSEAL reprocesses requests that fail with an HTTP 404 error by prepending the junction name to the URL.dynamic-addressesUse the dynamic-addresses stanza entry to control whether the junction server host name is resolved to its IP address immediately before every communication with the junction server. dynamic-addresses-ttlUse the dynamic-addresses-ttl stanza entry to specify the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live). gso-credential-learningUse this entry to enable or disable the learning capability for GSO junctions. gso-obfuscation-key Use this stanza entry to set the key for obfuscating any passwords that are managed by the GSO RESTful web service.http-timeouthttps-timeoutinsert-client-real-ip-for-option-rio-buffer-sizejct-cert-keyfilejct-cert-keyfile-stashjct-nist-complianceUse the jct-nist-compliance stanza entry to enable or disable NIST SP800-131A compliance for junction connections.jct-ocsp-enablejct-ocsp-max-response-sizejct-ocsp-nonce-check-enablejct-ocsp-nonce-generation-enablejct-ocsp-proxy-server-namejct-ocsp-proxy-server-portjct-ocsp-urljct-ssl-reneg-warning-ratejct-undetermined-revocation-cert-actionjmt-mapkerberos-keytab-fileUse the kerberos-keytab-file entry to set the name of the Kerberos key table file for the WebSEAL server. kerberos-principal-nameUse the kerberos-principal-name entry to set the service principal name of the impersonating user when creating a Kerberos token. kerberos-user-identityUse the kerberos-user-identity stanza entry to enable and define a custom user principal name (UPN). The custom UPN can be constructed from either plain text or the contents of credential attributes.kerberos-sso-enableUse the kerberos-sso-enable entry to enable or disable SSO for junctions.managed-cookies-listmangle-domain-cookiesmatch-vhj-firstHelps determine the order in which WebSEAL searches for a request in a standard or a virtual host junction table.max-cached-persistent-connectionsmax-webseal-header-sizepass-http-only-cookie-attrpersistent-con-timeoutping-methodping-timeping-urirecovery-ping-timereprocess-root-jct-404sreset-cookies-listresponse-code-rulesshare-cookiessupport-virtual-host-domain-cookiesuse-new-stateful-on-errorvalidate-backend-domain-cookiesworker-thread-hard-limitworker-thread-soft-limit

[junction] stanza

allow-backend-domain-cookies
Use the allow-backend-domain-cookies stanza entry to control whether WebSEAL sends domain cookies from a back-end server to a client.

always-send-kerberos-tokens
Indicates whether WebSEAL sends a security token for every HTTP request or whether WebSEAL waits for a 401 response before it adds the security token.

basicauth-dummy-passwd
Use the basicauth-dummy-passwd stanza entry to specify the global password for WebSEAL to use when it supplies basic authentication data over junctions that were created with the -b supply argument.

crl-ldap-server
Use the crl-ldap-server stanza entry in the [junction] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during authentication across SSL junctions.

crl-ldap-server-port
Use the crl-ldap-server-port entry in the [junction] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.

crl-ldap-user
Use the crl-ldap-user entry in the [junction] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server.

crl-ldap-user-password
Use the crl-ldap-user-password entry in the [junction] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.

kerberos-service-name
Use the kerberos-service-name entry to set the service principal name of the target.

disable-local-junctions
Use the disable-local-junctions stanza entry to control whether WebSEAL serves pages from a local web server through local junctions.

disable-ssl-v2
Use the disable-ssl-v2 entry in the [junction] stanza to control whether WebSEAL supports SSL version 2 for junction connections.

disable-ssl-v3
Use the disable-ssl-v3 entry in the [junction] stanza to control whether WebSEAL supports SSL version 3 for junction connections.

disable-tls-v1
Use the disable-tls-v1 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1 for junction connections.

disable-tls-v11
Use the disable-tls-v11 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.1 for junction connections.

disable-tls-v12
Use the disable-tls-v12 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.2 for junction connections.

dont-reprocess-jct-404s
Use the dont-reprocess-jct-404s stanza entry to control whether WebSEAL reprocesses requests that fail with an HTTP 404 error by prepending the junction name to the URL.

dynamic-addresses
Use the dynamic-addresses stanza entry to control whether the junction server host name is resolved to its IP address immediately before every communication with the junction server.

dynamic-addresses-ttl
Use the dynamic-addresses-ttl stanza entry to specify the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live).

gso-credential-learning
Use this entry to enable or disable the learning capability for GSO junctions.

gso-obfuscation-key
Use this stanza entry to set the key for obfuscating any passwords that are managed by the GSO RESTful web service.

http-timeout

https-timeout

insert-client-real-ip-for-option-r

io-buffer-size

jct-cert-keyfile

jct-cert-keyfile-stash

jct-nist-compliance
Use the jct-nist-compliance stanza entry to enable or disable NIST SP800-131A compliance for junction connections.

jct-ocsp-enable

jct-ocsp-max-response-size

jct-ocsp-nonce-check-enable

jct-ocsp-nonce-generation-enable

jct-ocsp-proxy-server-name

jct-ocsp-proxy-server-port

jct-ocsp-url

jct-ssl-reneg-warning-rate

jct-undetermined-revocation-cert-action

jmt-map

kerberos-keytab-file
Use the kerberos-keytab-file entry to set the name of the Kerberos key table file for the WebSEAL server.

kerberos-principal-name
Use the kerberos-principal-name entry to set the service principal name of the impersonating user when creating a Kerberos token.

kerberos-user-identity
Use the kerberos-user-identity stanza entry to enable and define a custom user principal name (UPN). The custom UPN can be constructed from either plain text or the contents of credential attributes.

kerberos-sso-enable
Use the kerberos-sso-enable entry to enable or disable SSO for junctions.

managed-cookies-list

mangle-domain-cookies

match-vhj-first
Helps determine the order in which WebSEAL searches for a request in a standard or a virtual host junction table.

max-cached-persistent-connections

max-webseal-header-size

pass-http-only-cookie-attr

persistent-con-timeout

ping-method

ping-time

ping-uri

recovery-ping-time

reprocess-root-jct-404s

reset-cookies-list

response-code-rules

share-cookies

support-virtual-host-domain-cookies

use-new-stateful-on-error

validate-backend-domain-cookies

worker-thread-hard-limit

worker-thread-soft-limit

Parent topic: Stanza reference

allow-backend-domain-cookiesallow-backend-domain-cookiesIBM Security Access Manager for Web WebSEAL allow-backend-domain-cookies stanza entryUse the allow-backend-domain-cookies stanza entry to control whether WebSEAL sends domain cookies from a back-end server to a client.allow-backend-domain-cookies stanza entryjunction stanzaentriesallow-backend-domain-cookiesjunction stanzajunction stanzaallow-backend-domain-cookies entrySyntaxallow-backend-domain-cookies = {yes|no} DescriptionIndicates whether WebSEAL can send domain cookies from a back-end server to a client.You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. OptionsyesWebSEAL is able to send domain cookies from a back-end server to a client.noWebSEAL is not able to send domain cookies from a back-end server to a client. UsageThis stanza entry is required. Default valueno Exampleallow-backend-domain-cookies = no [junction] stanza

allow-backend-domain-cookies

Use the allow-backend-domain-cookies stanza entry to control whether WebSEAL sends domain cookies from a back-end server to a client.

Syntax

allow-backend-domain-cookies = {yes|no}

Description

Indicates whether WebSEAL can send domain cookies from a back-end server to a client.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

yes

WebSEAL is able to send domain cookies from a back-end server to a client.

no

WebSEAL is not able to send domain cookies from a back-end server to a client.

Usage

This stanza entry is required.

Default value

no

Example

allow-backend-domain-cookies = no

Parent topic: [junction] stanza

always-send-kerberos-tokensIndicates whether WebSEAL sends a security token for every HTTP request or whether WebSEAL waits for a 401 response before it adds the security token.always-send-kerberos-tokens stanza entryjunction stanzaentriesalways-send-kerberos-tokensjunction stanzajunction stanzaalways-send-kerberos-tokens entrySyntax always-send-kerberos-tokens = {yes|true|no|false} Description You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. Options yesEnable.trueEnable.noDisable.falseDisable. Usage This stanza entry is required if Kerberos SSO authentication for junctions is enabled. Default value no.Example always-send-kerberos-tokens = no [junction] stanza

always-send-kerberos-tokens

Indicates whether WebSEAL sends a security token for every HTTP request or whether WebSEAL waits for a 401 response before it adds the security token.

Syntax

always-send-kerberos-tokens = {yes|true|no|false}

Description

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

Options

yes

Enable.

true

Enable.

no

Disable.

false

Disable.

Usage

This stanza entry is required if Kerberos SSO authentication for junctions is enabled.

Default value

no.

Example

always-send-kerberos-tokens = no

Parent topic: [junction] stanza

basicauth-dummy-passwdbasicauth-dummy-passwdIBM Security Access Manager for Web WebSEAL basicauth-dummy-passwd stanza entryUse the basicauth-dummy-passwd stanza entry to specify the global password for WebSEAL to use when it supplies basic authentication data over junctions that were created with the -b supply argument.basicauth-dummy-passwd stanza entryjunction stanzaentriesbasicauth-dummy-passwdjunction stanzajunction stanzabasicauth-dummy-passwd entrySyntax basicauth-dummy-passwd = dummy_password Description Global password that WebSEAL uses when it is supplying basic authentication data over junctions that were created with the -b supply argument. Options dummy_passwordGlobal password that WebSEAL uses when it is supplying basic authentication data over junctions that were created with the -b supply argument. Passwords must consist of ASCII characters. Usage This stanza entry is required. Default value dummy Example basicauth-dummy-passwd = dummy [junction] stanza

basicauth-dummy-passwd

Use the basicauth-dummy-passwd stanza entry to specify the global password for WebSEAL to use when it supplies basic authentication data over junctions that were created with the -b supply argument.

Syntax

basicauth-dummy-passwd = dummy_password

Description

Global password that WebSEAL uses when it is supplying basic authentication data over junctions that were created with the -b supply argument.

Options

dummy_password

Global password that WebSEAL uses when it is supplying basic authentication data over junctions that were created with the -b supply argument. Passwords must consist of ASCII characters.

Usage

This stanza entry is required.

Default value

dummy

Example

basicauth-dummy-passwd = dummy

Parent topic: [junction] stanza

crl-ldap-servercrl-ldap-serverIBM Security Access Manager for Web WebSEAL crl-ldap-server stanza entryUse the crl-ldap-server stanza entry in the [junction] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during authentication across SSL junctions.crl-ldap-server stanza entryjunction stanzaentriescrl-ldap-serverjunction stanzajunction stanzacrl-ldap-server entrySyntax crl-ldap-server = server_name Description Specifies the Server to be contacted to obtain Certificate Revocation Lists (CRL). Options server_nameThis parameter can be set to one of two types of values: The name of the LDAP server to be referenced as a source for Certificate Revocation Lists (CRL) during authentication across SSL junctions. If this is used, you may also need to set the following parameters: crl-ldap-server-portcrl-ldap-usercrl-ldap-user-passwordThe literal string “URI”. In the case where no direct LDAP Server is available, this allows GSKit to obtain revocation information from LDAP or the HTTP Servers as specified by the CA in the CRL Distribution Point (CDP) extension of the certificate. Usage This stanza entry is optional. Default value None. Example crl-ldap-server = diamond.example.com [junction] stanza

crl-ldap-server

Use the crl-ldap-server stanza entry in the [junction] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during authentication across SSL junctions.

Syntax

crl-ldap-server = server_name

Description

Specifies the Server to be contacted to obtain Certificate Revocation Lists (CRL).

Options

server_name

This parameter can be set to one of two types of values:

The name of the LDAP server to be referenced as a source for Certificate Revocation Lists (CRL) during authentication across SSL junctions. If this is used, you may also need to set the following parameters:

crl-ldap-server-port

crl-ldap-user

crl-ldap-user-password

The literal string “URI”. In the case where no direct LDAP Server is available, this allows GSKit to obtain revocation information from LDAP or the HTTP Servers as specified by the CA in the CRL Distribution Point (CDP) extension of the certificate.

Usage

This stanza entry is optional.

Default value

None.

Example

crl-ldap-server = diamond.example.com

Parent topic: [junction] stanza

crl-ldap-server-portcrl-ldap-server-portIBM Security Access Manager for Web WebSEAL crl-ldap-server-port stanza entryUse the crl-ldap-server-port entry in the [junction] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.crl-ldap-server-port stanza entryjunction stanzaentriescrl-ldap-server-portjunction stanzajunction stanzacrl-ldap-server-port entrySyntax crl-ldap-server-port = port_number Description Port number for communication with the LDAP server specified in crl-ldap-server. The LDAP server is referenced for Certificate Revocation List (CRL) checking during authentication across SSL junctions. Options port_numberPort number for communication with the LDAP server specified in crl-ldap-server. Usage This stanza entry is optional. When crl-ldap-server is specified, this stanza entry is required. Default value None. Example crl-ldap-server-port = 389 [junction] stanza

crl-ldap-server-port

Use the crl-ldap-server-port entry in the [junction] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.

Syntax

crl-ldap-server-port = port_number

Description

Port number for communication with the LDAP server specified in crl-ldap-server. The LDAP server is referenced for Certificate Revocation List (CRL) checking during authentication across SSL junctions.

Options

port_number

Port number for communication with the LDAP server specified in crl-ldap-server.

Usage

This stanza entry is optional. When crl-ldap-server is specified, this stanza entry is required.

Default value

None.

Example

crl-ldap-server-port = 389

Parent topic: [junction] stanza

crl-ldap-usercrl-ldap-userIBM Security Access Manager for Web WebSEAL crl-ldap-user stanza entryUse the crl-ldap-user entry in the [junction] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server. crl-ldap-user stanza entryjunction stanzaentriescrl-ldap-userjunction stanzajunction stanzacrl-ldap-user entrySyntax crl-ldap-user = user_DN Description Fully qualified distinguished name (DN) of an LDAP user who has permissions to retrieve the Certificate Revocation List. Options user_DNFully qualified distinguished name (DN) of an LDAP user who has permissions to retrieve the Certificate Revocation List. A null value for crl-ldap-server indicates that the SSL authenticator should bind to the LDAP server anonymously. Usage This stanza entry is optional. Default value None. Example crl-ldap-user = user_DN [junction] stanza

crl-ldap-user

Use the crl-ldap-user entry in the [junction] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server.

Syntax

crl-ldap-user = user_DN

Description

Fully qualified distinguished name (DN) of an LDAP user who has permissions to retrieve the Certificate Revocation List.

Options

user_DN

Fully qualified distinguished name (DN) of an LDAP user who has permissions to retrieve the Certificate Revocation List. A null value for crl-ldap-server indicates that the SSL authenticator should bind to the LDAP server anonymously.

Usage

This stanza entry is optional.

Default value

None.

Example

crl-ldap-user = user_DN

Parent topic: [junction] stanza

crl-ldap-user-passwordcrl-ldap-user-passwordIBM Security Access Manager for Web WebSEAL crl-ldap-user-password stanza entryUse the crl-ldap-user-password entry in the [junction] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.crl-ldap-user-password stanza entryjunction stanzaentriescrl-ldap-user-passwordjunction stanzajunction stanzacrl-ldap-user-password entrySyntax crl-ldap-user-password = password Description The password for the LDAP user specified in the crl-ldap-user stanza entry. Options passwordThe password for the LDAP user specified in the crl-ldap-user stanza entry. Usage This stanza entry is optional. When crl-ldap-user is specified, this stanza entry is required. Default value None. Example crl-ldap-user-password = mypassw0rd [junction] stanza

crl-ldap-user-password

Use the crl-ldap-user-password entry in the [junction] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.

Syntax

crl-ldap-user-password = password

Description

The password for the LDAP user specified in the crl-ldap-user stanza entry.

Options

password

The password for the LDAP user specified in the crl-ldap-user stanza entry.

Usage

This stanza entry is optional. When crl-ldap-user is specified, this stanza entry is required.

Default value

None.

Example

crl-ldap-user-password = mypassw0rd

Parent topic: [junction] stanza

kerberos-service-nameUse the kerberos-service-name entry to set the service principal name of the target.kerberos-service-name stanza entryjunction stanzaentrieskerberos-service-namejunction stanzajunction stanzakerberos-service-name entrySyntax kerberos-service-name = service-name Description You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. Options service-nameThe service principal name of the target. Usage This stanza entry is required when Kerberos SSO authentication for junctions is enabled. Default value None.Example kerberos-service-name = HTTP/myservice@<realm> [junction] stanza

kerberos-service-name

Use the kerberos-service-name entry to set the service principal name of the target.

Syntax

kerberos-service-name = service-name

Description

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

Options

service-name

The service principal name of the target.

Usage

This stanza entry is required when Kerberos SSO authentication for junctions is enabled.

Default value

None.

Example

kerberos-service-name = HTTP/myservice@<realm>

Parent topic: [junction] stanza

disable-local-junctionsdisable-local-junctionsIBM Security Access Manager for Web WebSEAL disable-local-junctions stanza entryUse the disable-local-junctions stanza entry to control whether WebSEAL serves pages from a local web server through local junctions. disable-local-junctions stanza entryjunction stanzaentriesdisable-local-junctionsjunction stanzajunction stanzadisable-local-junctions entrySyntax disable-local-junctions = {yes|no} Description If local junctions are not used, you can disable the functionality with the disable-local-junctions configuration item. Options yesDisables local junction functionality.noEnables local junction functionality. UsageOptional. The following example enables local junction functionality:disable-local-junctions=no [junction] stanza

disable-local-junctions

Use the disable-local-junctions stanza entry to control whether WebSEAL serves pages from a local web server through local junctions.

Syntax

disable-local-junctions = {yes|no}

Description

If local junctions are not used, you can disable the functionality with the disable-local-junctions configuration item.

Options

yes

Disables local junction functionality.

no

Enables local junction functionality.

Usage

Optional.

The following example enables local junction functionality:

disable-local-junctions=no

Parent topic: [junction] stanza

disable-ssl-v2disable-ssl-v2IBM Security Access Manager for Web WebSEAL disable-ssl-v2 stanza entryUse the disable-ssl-v2 entry in the [junction] stanza to control whether WebSEAL supports SSL version 2 for junction connections.disable-ssl-v2 stanza entryjunction stanzaentriesdisable-ssl-v2junction stanzajunction stanzadisable-ssl-v2 entrySyntax disable-ssl-v2 = {yes|no} Description Disables support for SSL Version 2 for junction connections. Support for SSL v2 is disabled by default. Options yesThe value yes means support is disabled. noThe value no means the support is enabled. Usage This stanza entry is optional. When not specified, the default is yes. The WebSEAL configuration sets this value. Default value yes Example disable-ssl-v2 = yes [junction] stanza

disable-ssl-v2

Use the disable-ssl-v2 entry in the [junction] stanza to control whether WebSEAL supports SSL version 2 for junction connections.

Syntax

disable-ssl-v2 = {yes|no}

Description

Disables support for SSL Version 2 for junction connections. Support for SSL v2 is disabled by default.

Options

yes

The value yes means support is disabled.

no

The value no means the support is enabled.

Usage

This stanza entry is optional. When not specified, the default is yes. The WebSEAL configuration sets this value.

Default value

yes

Example

disable-ssl-v2 = yes

Parent topic: [junction] stanza

disable-ssl-v3disable-ssl-v3IBM Security Access Manager for Web WebSEAL disable-ssl-v3 stanza entryUse the disable-ssl-v3 entry in the [junction] stanza to control whether WebSEAL supports SSL version 3 for junction connections.disable-ssl-v3 stanza entryjunction stanzaentriesdisable-ssl-v3junction stanzajunction stanzadisable-ssl-v3 entrySyntax disable-ssl-v3 = {yes|no} Description Disables support for SSL Version 3 for junction connections. Support for SSL V3 is enabled by default. Options yesThe value yes means support is disabled.noThe value no means the support is enabled Usage This stanza entry is optional. When not specified, the default is no. The WebSEAL configuration sets this value. Default value no Example disable-ssl-v3 = no [junction] stanza

disable-ssl-v3

Use the disable-ssl-v3 entry in the [junction] stanza to control whether WebSEAL supports SSL version 3 for junction connections.

Syntax

disable-ssl-v3 = {yes|no}

Description

Disables support for SSL Version 3 for junction connections. Support for SSL V3 is enabled by default.

Options

yes

The value yes means support is disabled.

no

The value no means the support is enabled

Usage

This stanza entry is optional. When not specified, the default is no. The WebSEAL configuration sets this value.

Default value

no

Example

disable-ssl-v3 = no

Parent topic: [junction] stanza

disable-tls-v1disable-tls-v1IBM Security Access Manager for Web WebSEAL disable-tls-v1 stanza entryUse the disable-tls-v1 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1 for junction connections.disable-tls-v1 stanza entryjunction stanzaentriesdisable-tls-v1junction stanzajunction stanzadisable-tls-v1 entrySyntax disable-tls-v1 = {yes|no} Description Disables support for TLS Version 1 for junction connections. Support for TLS V1 is enabled by default. Options yesThe value yes means support is disabled. noThe value no means the support is enabled. Usage This stanza entry is optional. When not specified, the default is no. The WebSEAL configuration sets this value. Default value no Example disable-tls-v1 = no [junction] stanza

disable-tls-v1

Use the disable-tls-v1 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1 for junction connections.

Syntax

disable-tls-v1 = {yes|no}

Description

Disables support for TLS Version 1 for junction connections. Support for TLS V1 is enabled by default.

Options

yes

The value yes means support is disabled.

no

The value no means the support is enabled.

Usage

This stanza entry is optional. When not specified, the default is no. The WebSEAL configuration sets this value.

Default value

no

Example

disable-tls-v1 = no

Parent topic: [junction] stanza

disable-tls-v11disable-tls-v11IBM Security Access Manager for Web WebSEAL disable-tls-v11 stanza entryUse the disable-tls-v11 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.1 for junction connections.disable-tls-v11 stanza entryjunction stanzaentriesdisable-tls-v11junction stanzajunction stanzadisable-tls-v11 entrySyntax disable-tls-v11 = {yes|no} Description Determines whether WebSEAL supports TLS version 1.1 for junction connections. Support for TLS v1.1 is enabled by default. Options yesThe value yes disables support for TLS version 1.1. noThe value no enables support for TLS version 1.1. Usage This stanza entry is optional. If this entry is not specified, the default is no. Default value no Example disable-tls-v11 = no [junction] stanza

disable-tls-v11

Use the disable-tls-v11 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.1 for junction connections.

Syntax

disable-tls-v11 = {yes|no}

Description

Determines whether WebSEAL supports TLS version 1.1 for junction connections. Support for TLS v1.1 is enabled by default.

Options

yes

The value yes disables support for TLS version 1.1.

no

The value no enables support for TLS version 1.1.

Usage

This stanza entry is optional. If this entry is not specified, the default is no.

Default value

no

Example

disable-tls-v11 = no

Parent topic: [junction] stanza

disable-tls-v12disable-tls-v12IBM Security Access Manager for Web WebSEAL disable-tls-v12 stanza entryUse the disable-tls-v12 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.2 for junction connections.disable-tls-v12 stanza entryjunction stanzaentriesdisable-tls-v12junction stanzajunction stanzadisable-tls-v12 entrySyntax disable-tls-v12 = {yes|no} Description Determines whether WebSEAL supports Transport Layer Security (TLS) version 1.2 for junction connections. Support for TLS v1.2 is enabled by default. Options yesThe value yes disables support for TLS version 1.2. noThe value no enables support for TLS version 1.2. Usage This stanza entry is optional. If this entry is not specified, the default is no. Default value no Example disable-tls-v12 = no [junction] stanza

disable-tls-v12

Use the disable-tls-v12 entry in the [junction] stanza to control whether WebSEAL supports Transport Layer Security (TLS) version 1.2 for junction connections.

Syntax

disable-tls-v12 = {yes|no}

Description

Determines whether WebSEAL supports Transport Layer Security (TLS) version 1.2 for junction connections. Support for TLS v1.2 is enabled by default.

Options

yes

The value yes disables support for TLS version 1.2.

no

The value no enables support for TLS version 1.2.

Usage

This stanza entry is optional. If this entry is not specified, the default is no.

Default value

no

Example

disable-tls-v12 = no

Parent topic: [junction] stanza

dont-reprocess-jct-404sdont-reprocess-jct-404sIBM Security Access Manager for Web WebSEAL dont-reprocess-jct-404s stanza entryUse the dont-reprocess-jct-404s stanza entry to control whether WebSEAL reprocesses requests that fail with an HTTP 404 error by prepending the junction name to the URL.dont-reprocess-jct-404s stanza entryjunction stanzaentriesdont-reprocess-jct-404sjunction stanzajunction stanzadont-reprocess-jct-404s entrySyntax dont-reprocess-jct-404s = {yes|no} Description If a resource cannot be found on a back-end server, that server returns an HTTP 404 error. The dont-reprocess-jct-404s stanza entry controls whether or not WebSEAL processes the request again by prepending the junction name to the URL. You should never need to enable this stanza entry if you follow this best practice for junctions: The junction name should not match any directory name used in the Web space of the back-end server if HTML pages from that server contain programs (such as JavaScript or applets) with server-relative URLs to that directory. The following scenario can occur when one does not adhere to this best practice for junctions: A resource is located in the following subdirectory (using the same name as the junction) on the back-end server: /jct/page.html.A page received by the client from this back-end server contains the following URL: /jct/page.html.When the link is followed, WebSEAL can immediately process the request because it recognizes what it thinks is the junction name in the URL. No configured URL modification technique is required.At the time the request is forwarded to the back-end server, the junction name (/jct) removed from the URL. The resource (/page.html) is not found at the root of the back-end server file system. The server returns a 404 error.If WebSEAL is configured for dont-reprocess-jct-404s=no, it reprocesses the URL and prepends the junction name to the original URL: /jct/jct/page.html.Now the resource is successfully located at /jct/page.html on the back-end server. The default behavior in WebSEAL is to reprocess a request URL after an HTTP 404 error is returned from the back-end server. You can set the value of dont-reprocess-jct-404s to yes to override this default behavior.If the reprocess-root-jct-404s entry (also in the [junction] stanza) has been set to yes then root junction resource requests that result in a HTTP 404 error will be reprocessed regardless of the setting of this dont-reprocess-jct-404s stanza entry. Options yesWhen the back-end server returns an HTTP 404 error, do not reprocess the request URL.noWhen the back-end server returns an HTTP 404 error, reprocess the request URL by prepending the junction name to the existing URL. Usage This stanza entry is required. Default value The default value in the template configuration file is yes. Example dont-reprocess-jct-404s = yes [junction] stanza

dont-reprocess-jct-404s

Use the dont-reprocess-jct-404s stanza entry to control whether WebSEAL reprocesses requests that fail with an HTTP 404 error by prepending the junction name to the URL.

Syntax

dont-reprocess-jct-404s = {yes|no}

Description

If a resource cannot be found on a back-end server, that server returns an HTTP 404 error. The dont-reprocess-jct-404s stanza entry controls whether or not WebSEAL processes the request again by prepending the junction name to the URL.

You should never need to enable this stanza entry if you follow this best practice for junctions: The junction name should not match any directory name used in the Web space of the back-end server if HTML pages from that server contain programs (such as JavaScript or applets) with server-relative URLs to that directory.

The following scenario can occur when one does not adhere to this best practice for junctions:

A resource is located in the following subdirectory (using the same name as the junction) on the back-end server: /jct/page.html.

A page received by the client from this back-end server contains the following URL: /jct/page.html.

When the link is followed, WebSEAL can immediately process the request because it recognizes what it thinks is the junction name in the URL. No configured URL modification technique is required.

At the time the request is forwarded to the back-end server, the junction name (/jct) removed from the URL. The resource (/page.html) is not found at the root of the back-end server file system. The server returns a 404 error.

If WebSEAL is configured for dont-reprocess-jct-404s=no, it reprocesses the URL and prepends the junction name to the original URL: /jct/jct/page.html.

Now the resource is successfully located at /jct/page.html on the back-end server.

Notes:

The default behavior in WebSEAL is to reprocess a request URL after an HTTP 404 error is returned from the back-end server. You can set the value of dont-reprocess-jct-404s to yes to override this default behavior.

If the reprocess-root-jct-404s entry (also in the [junction] stanza) has been set to yes then root junction resource requests that result in a HTTP 404 error will be reprocessed regardless of the setting of this dont-reprocess-jct-404s stanza entry.

Options

yes

When the back-end server returns an HTTP 404 error, do not reprocess the request URL.

no

When the back-end server returns an HTTP 404 error, reprocess the request URL by prepending the junction name to the existing URL.

Usage

This stanza entry is required.

Default value

The default value in the template configuration file is yes.

Example

dont-reprocess-jct-404s = yes

Parent topic: [junction] stanza

dynamic-addressesdynamic-addressesdynamic-addresses stanza entryUse the dynamic-addresses stanza entry to control whether the junction server host name is resolved to its IP address immediately before every communication with the junction server. entriesdynamic-addressesjunction stanzajunction stanzadynamic-addressesSyntaxdynamic-addresses = {yes|no} DescriptionIndicates when the junction server host name is resolved to its corresponding IP address and used in communication with the junction server.You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. OptionsyesThe junction server host name is resolved to its corresponding IP address immediately before any communication with the junction server.If this configuration entry is set to yes, you can use the dynamic-addresses-ttl configuration entry to specify the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live).noThe junction server host name is resolved to its corresponding IP address and this address is used for subsequent communication with the junction server. UsageThis stanza entry is required. Default valueno Exampledynamic-addresses = no [junction] stanza

dynamic-addresses

Use the dynamic-addresses stanza entry to control whether the junction server host name is resolved to its IP address immediately before every communication with the junction server.

Syntax

dynamic-addresses = {yes|no}

Description

Indicates when the junction server host name is resolved to its corresponding IP address and used in communication with the junction server.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

yes

The junction server host name is resolved to its corresponding IP address immediately before any communication with the junction server.

If this configuration entry is set to yes, you can use the dynamic-addresses-ttl configuration entry to specify the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live).

no

The junction server host name is resolved to its corresponding IP address and this address is used for subsequent communication with the junction server.

Usage

This stanza entry is required.

Default value

no

Example

dynamic-addresses = no

Parent topic: [junction] stanza

dynamic-addresses-ttlUse the dynamic-addresses-ttl stanza entry to specify the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live). entriesdynamic-addresses-ttljunction stanzajunction stanzadynamic-addresses-ttlSyntax dynamic-addresses-ttl = secondsDescription If the dynamic-addresses configuration entry is set to yes, this configuration entry specifies the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live). You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza, where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.Options secondsThe length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live).Usage This stanza entry is optional.Default value NoneExample dynamic-addresses-ttl = 0[junction] stanza

dynamic-addresses-ttl

Use the dynamic-addresses-ttl stanza entry to specify the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live).

Syntax

dynamic-addresses-ttl = seconds

Description

If the dynamic-addresses configuration entry is set to yes, this configuration entry specifies the length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live).

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza, where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

seconds

The length of time (in seconds) that a resolved IP address will be cached before it is discarded and another name resolution is attempted (time-to-live).

Usage

This stanza entry is optional.

Default value

None

Example

dynamic-addresses-ttl = 0

Parent topic: [junction] stanza

gso-credential-learningUse this entry to enable or disable the learning capability for GSO junctions. Syntax gso-credential-learning = {yes|no|true|false}Description This stanza entry controls whether the learning capability is enabled for GSO junctions. If the learning ability is enabled and existing credential information is not available for the user, the BA prompt is returned to the user. The credential information for the user is then stored for future use on a subsequent successful authentication. An authentication is deemed to be successful if the junctioned web server does not return a 4xx or 5xx response.Options yes/trueEnable the learning ability for GSO junctions.no/falseDisable the learning ability for GSO junctions.Usage This stanza entry is optional.Default value noExample gso-credential-learning = no[junction] stanza

gso-credential-learning

Use this entry to enable or disable the learning capability for GSO junctions.

Syntax

gso-credential-learning = {yes|no|true|false}

Description

This stanza entry controls whether the learning capability is enabled for GSO junctions.

If the learning ability is enabled and existing credential information is not available for the user, the BA prompt is returned to the user. The credential information for the user is then stored for future use on a subsequent successful authentication. An authentication is deemed to be successful if the junctioned web server does not return a 4xx or 5xx response.

Options

yes/true

Enable the learning ability for GSO junctions.

no/false

Disable the learning ability for GSO junctions.

Usage

This stanza entry is optional.

Default value

no

Example

gso-credential-learning = no

Parent topic: [junction] stanza

gso-obfuscation-key Use this stanza entry to set the key for obfuscating any passwords that are managed by the GSO RESTful web service.Syntax gso-obfuscation-key = keyDescription If you want to obfuscate the passwords that are managed by the GSO RESTful web service, set this stanza entry. The passwords are obfuscated by performing an AES-CBC encryption on the data by using the supplied key. The appliance provides a web service to produce the obfuscated GSO password. For more information about this web service, see REST API documentation. The passwords are obfuscated by AES-128-CBC encryption, which is AES cipher-block-chaining encryption with a 128 bit key. If the supplied key is less than 16 bytes in length, the key will be right-padded with one or more 0 characters to bring the key up to 16 bytes in length. If this stanza entry is not set, the passwords that are managed by the GSO RESTful web service are not obfuscated.Options keyThe key for obfuscating the passwords that are managed by the GSO RESTful web service.Usage This stanza entry is optional.Default value NoneExample gso-obfuscation-key = jkhdc879e$*&^jcw98y[junction] stanza

gso-obfuscation-key

Use this stanza entry to set the key for obfuscating any passwords that are managed by the GSO RESTful web service.

Syntax

gso-obfuscation-key = key

Description

If you want to obfuscate the passwords that are managed by the GSO RESTful web service, set this stanza entry. The passwords are obfuscated by performing an AES-CBC encryption on the data by using the supplied key. The appliance provides a web service to produce the obfuscated GSO password. For more information about this web service, see REST API documentation.

Note: The passwords are obfuscated by AES-128-CBC encryption, which is AES cipher-block-chaining encryption with a 128 bit key. If the supplied key is less than 16 bytes in length, the key will be right-padded with one or more "0" characters to bring the key up to 16 bytes in length.

If this stanza entry is not set, the passwords that are managed by the GSO RESTful web service are not obfuscated.

Options

key

The key for obfuscating the passwords that are managed by the GSO RESTful web service.

Usage

This stanza entry is optional.

Default value

None

Example

gso-obfuscation-key = jkhdc879e$*&^jcw98y

Parent topic: [junction] stanza

http-timeouthttp-timeouthttp-timeout stanza entryjunction stanzaentrieshttp-timeoutjunction stanzajunction stanzahttp-timeout entrySyntaxhttp-timeout = number_of_seconds DescriptionInteger value indicating the timeout, in seconds, for sending to and reading from a TCP junction.You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Optionsnumber_of_secondsInteger value indicating the timeout, in seconds, for sending to and reading from a TCP junction. The minimum value is 0. When the value is 0, there is no timeout. WebSEAL does not impose a maximum value. UsageThis stanza entry is required. Default value120 http-timeout = 120 [junction] stanza

http-timeout

Syntax

http-timeout = number_of_seconds

Description

Integer value indicating the timeout, in seconds, for sending to and reading from a TCP junction.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

number_of_seconds

Integer value indicating the timeout, in seconds, for sending to and reading from a TCP junction. The minimum value is 0. When the value is 0, there is no timeout. WebSEAL does not impose a maximum value.

Usage

This stanza entry is required.

Default value

120

http-timeout = 120

Parent topic: [junction] stanza

https-timeouthttps-timeouthttps-timeout stanza entryjunction stanzaentrieshttps-timeoutjunction stanzajunction stanzahttps-timeout entrySyntaxhttps-timeout = number_of_seconds DescriptionInteger value indicating the timeout, in seconds, for sending to and reading from a Secure Socket Layer (SSL) junction. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Optionsnumber_of_secondsInteger value indicating the timeout, in seconds, for sending to and reading from a Secure Socket Layer (SSL) junction. The minimum value is 0. When the value is 0, there is no timeout. WebSEAL does not impose a maximum value. UsageThis stanza entry is required. Default value120 https-timeout = 120 [junction] stanza

https-timeout

Syntax

https-timeout = number_of_seconds

Description

Integer value indicating the timeout, in seconds, for sending to and reading from a Secure Socket Layer (SSL) junction.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

number_of_seconds

Integer value indicating the timeout, in seconds, for sending to and reading from a Secure Socket Layer (SSL) junction. The minimum value is 0. When the value is 0, there is no timeout. WebSEAL does not impose a maximum value.

Usage

This stanza entry is required.

Default value

120

https-timeout = 120

Parent topic: [junction] stanza

insert-client-real-ip-for-option-rinsert-client-real-ip-for-option-rinsert-client-real-ip-for-option-r stanza entryjunction stanzaentriesinsert-client-real-ip-for-option-rjunction stanzajunction stanzainsert-client-real-ip-for-option-r entrySyntax insert-client-real-ip-for-option-r = {yes|no}Description Determines whether to use the current IP address of the client or the one cached in the credentials at authentication time for the value passed in a header to junctions created with the -r option.Options yesUse the current IP address of the client for the value passed in a header to junctions created with the -r option.noUse the client IP address cached in the credentials at authentication time for the value passed in a header to junctions created with the -r option.Usage This stanza entry is required.Default value noExample insert-client-real-ip-for-option-r = no[junction] stanza

insert-client-real-ip-for-option-r

Syntax

insert-client-real-ip-for-option-r = {yes|no}

Description

Determines whether to use the current IP address of the client or the one cached in the credentials at authentication time for the value passed in a header to junctions created with the -r option.

Options

yes

Use the current IP address of the client for the value passed in a header to junctions created with the -r option.

no

Use the client IP address cached in the credentials at authentication time for the value passed in a header to junctions created with the -r option.

Usage

This stanza entry is required.

Default value

no

Example

insert-client-real-ip-for-option-r = no

Parent topic: [junction] stanza

io-buffer-sizeio-buffer-sizeio-buffer-size stanza entryjunction stanzaentriesio-buffer-sizejunction stanzajunction stanzaio-buffer-size entrySyntax io-buffer-size = number_of_bytes Description Positive integer value indicating the buffer size, in bytes, for low-level reads from and writes to a junction. Options number_of_bytes Positive integer value indicating the buffer size, in bytes, for low-level reads from and writes to a junction. The minimum value is 1. WebSEAL does not impose a maximum value. A very small value (for instance, 10 bytes) can hurt performance by causing very frequent calls to the low-level read/write APIs. Up to a certain point, larger values improve performance because they correspondingly reduce the calls to the low-level I/O functions. However, the low-level I/O functions may have their own internal buffers, such as the TCP send and receive buffers. Once io-buffer-size exceeds the size of those buffers (which are typically not large), there is no longer any performance improvement at all because those functions only read part of the buffer at the time. Reasonable values for io-buffer-size range between 1 kB and 8 kB. Values smaller than this range causes calling the low-level I/O functions too frequently. Values larger than this range wastes memory. A 2 MB I/O buffer size uses 4 MB for each worker thread communicating with the junctioned server, since there is both an input and output buffer. Usage This stanza entry is required. Default value 4096 Example io-buffer-size = 4096 [junction] stanza

io-buffer-size

Syntax

io-buffer-size = number_of_bytes

Description

Positive integer value indicating the buffer size, in bytes, for low-level reads from and writes to a junction.

Options

number_of_bytes

Positive integer value indicating the buffer size, in bytes, for low-level reads from and writes to a junction.

The minimum value is 1. WebSEAL does not impose a maximum value.

A very small value (for instance, 10 bytes) can hurt performance by causing very frequent calls to the low-level read/write APIs. Up to a certain point, larger values improve performance because they correspondingly reduce the calls to the low-level I/O functions.

However, the low-level I/O functions may have their own internal buffers, such as the TCP send and receive buffers. Once io-buffer-size exceeds the size of those buffers (which are typically not large), there is no longer any performance improvement at all because those functions only read part of the buffer at the time.

Reasonable values for io-buffer-size range between 1 kB and 8 kB. Values smaller than this range causes calling the low-level I/O functions too frequently. Values larger than this range wastes memory. A 2 MB I/O buffer size uses 4 MB for each worker thread communicating with the junctioned server, since there is both an input and output buffer.

Usage

This stanza entry is required.

Default value

4096

Example

io-buffer-size = 4096

Parent topic: [junction] stanza

jct-cert-keyfilejct-cert-keyfilejct-cert-keyfile stanza entryjunction stanzaentriesjct-cert-keyfilejunction stanzajunction stanzajct-cert-keyfile entrySyntax jct-cert-keyfile = file_name Description WebSEAL provides an option to configure a separate certificate key database for junction SSL operations rather than sharing the one used for client certificates specified in the [ssl] stanza. The jct-cert-keyfile parameter specifies the junction certificate keyfile. If this option is enabled, this is the keyfile used for CA and client certificates when negotiating SSL sessions with junctions. This stanza entry is commented out in the WebSEAL configuration file. To enable the option of using a separate certificate key database for junctioned servers, create the pdjct.kdb keyfile (and optional stash file) using iKeyman, and uncomment the options jct-cert-keyfile and jct-cert-keyfile-stash in the configuration file. Options file_nameThe name of the optional, separate junction certificate keyfile. If jct-cert-keyfile is defined, jct-cert-keyfile-stash must also be defined. Usage This stanza entry is optional. Default value pdjct.kdb Example jct-cert-keyfile = pdjct.kdb [junction] stanza

jct-cert-keyfile

Syntax

jct-cert-keyfile = file_name

Description

WebSEAL provides an option to configure a separate certificate key database for junction SSL operations rather than sharing the one used for client certificates specified in the [ssl] stanza. The jct-cert-keyfile parameter specifies the junction certificate keyfile. If this option is enabled, this is the keyfile used for CA and client certificates when negotiating SSL sessions with junctions.

Note: This stanza entry is commented out in the WebSEAL configuration file. To enable the option of using a separate certificate key database for junctioned servers, create the pdjct.kdb keyfile (and optional stash file) using iKeyman, and uncomment the options jct-cert-keyfile and jct-cert-keyfile-stash in the configuration file.

Options

file_name

The name of the optional, separate junction certificate keyfile.

Note: If jct-cert-keyfile is defined, jct-cert-keyfile-stash must also be defined.

Usage

This stanza entry is optional.

Default value

pdjct.kdb

Example

jct-cert-keyfile = pdjct.kdb

Parent topic: [junction] stanza

jct-cert-keyfile-stashjct-cert-keyfile-stashjct-cert-keyfile-stash stanza entryjunction stanzaentriesjct-cert-keyfile-stashjunction stanzajunction stanzajct-cert-keyfile-stash entrySyntax jct-cert-keyfile-stash = file_name Description WebSEAL provides an option to configure a separate certificate key database for junction SSL operations rather than sharing the one used for client certificates specified in the [ssl] stanza. The jct-cert-keyfile-stash parameter specifies the stash file for the optional, separate junction certificate database. This stanza entry is commented out in the WebSEAL configuration file. To enable the option of using a separate certificate key database for junctioned servers, create the pdjct.kdb keyfile (and optional stash file) using iKeyman, and uncomment the options jct-cert-keyfile and jct-cert-keyfile-stash in the configuration file. Options file_nameThe name of the stash file for the optional, separate junction certificate database. If jct-cert-keyfile is defined, jct-cert-keyfile-stash must also be defined. Usage This stanza entry is optional. Default value pdjct.sth Example jct-cert-keyfile-stash = pdjct.sth [junction] stanza

jct-cert-keyfile-stash

Syntax

jct-cert-keyfile-stash = file_name

Description

WebSEAL provides an option to configure a separate certificate key database for junction SSL operations rather than sharing the one used for client certificates specified in the [ssl] stanza. The jct-cert-keyfile-stash parameter specifies the stash file for the optional, separate junction certificate database.

Note: This stanza entry is commented out in the WebSEAL configuration file. To enable the option of using a separate certificate key database for junctioned servers, create the pdjct.kdb keyfile (and optional stash file) using iKeyman, and uncomment the options jct-cert-keyfile and jct-cert-keyfile-stash in the configuration file.

Options

file_name

The name of the stash file for the optional, separate junction certificate database.

Note: If jct-cert-keyfile is defined, jct-cert-keyfile-stash must also be defined.

Usage

This stanza entry is optional.

Default value

pdjct.sth

Example

jct-cert-keyfile-stash = pdjct.sth

Parent topic: [junction] stanza

jct-nist-compliancejct-nist-complianceIBM Security Access Manager for Web WebSEAL jct-nist-compliance stanza entryUse the jct-nist-compliance stanza entry to enable or disable NIST SP800-131A compliance for junction connections.jct-nist-compliance stanza entryjunction stanzaentriesjct-nist-compliancejunction stanzajunction stanzajct-nist-compliance entrySyntax jct-nist-compliance = {yes|no} Description Enables or disables NIST SP800-131A compliance for junction connections.Enabling NIST SP800-131A compliance results in the following automatic configuration:Enables FIPS mode processing. When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the fips-mode-processing configuration entry.Enables TLS v1.2. When NIST SP800-131A compliance is enabled, TLS v1.2 is enabled regardless of the setting for the disable-tls-v12 configuration entry.TLS v1 and TLS v1.1 are not disabled.Enables the appropriate signature algorithms.Sets the minimum RSA key size to 2048 bytes. Options yesA value of yes enables NIST SP800-131A compliance. noA value of no disables NIST SP800-131A compliance. Usage This stanza entry is optional. Default value no Example jct-nist-compliance = no [junction] stanza

jct-nist-compliance

Use the jct-nist-compliance stanza entry to enable or disable NIST SP800-131A compliance for junction connections.

Syntax

jct-nist-compliance = {yes|no}

Description

Enables or disables NIST SP800-131A compliance for junction connections.

Enabling NIST SP800-131A compliance results in the following automatic configuration:

Enables FIPS mode processing.

Note: When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the fips-mode-processing configuration entry.

Enables TLS v1.2.

Notes:

When NIST SP800-131A compliance is enabled, TLS v1.2 is enabled regardless of the setting for the disable-tls-v12 configuration entry.

TLS v1 and TLS v1.1 are not disabled.

Enables the appropriate signature algorithms.

Sets the minimum RSA key size to 2048 bytes.

Options

yes

A value of yes enables NIST SP800-131A compliance.

no

A value of no disables NIST SP800-131A compliance.

Usage

This stanza entry is optional.

Default value

no

Example

jct-nist-compliance = no

Parent topic: [junction] stanza

jct-ocsp-enablejct-ocsp-enablejct-ocsp-enable stanza entryjunction stanzaentriesjct-ocsp-enablejunction stanzajunction stanzajct-ocsp-enable entrySyntax jct-ocsp-enable = {yes|no} Description Enable Online Certificate Status Protocol (OCSP) for checking the revocation status of certificates supplied by a junction server using the OCSP URL embedded in the certificate using an Authority Information Access (AIA) extension. Options yesEnable OCSP to check the revocation status of junction server supplied certificates.noDisable OCSP checking of junction server supplied certificates. Usage This stanza entry is optional. This option can be used as an alternative to, or in conjunction with, the jct-ocsp-url option. Default value no Example jct-ocsp-enable = no [junction] stanza

jct-ocsp-enable

Syntax

jct-ocsp-enable = {yes|no}

Description

Enable Online Certificate Status Protocol (OCSP) for checking the revocation status of certificates supplied by a junction server using the OCSP URL embedded in the certificate using an Authority Information Access (AIA) extension.

Options

yes

Enable OCSP to check the revocation status of junction server supplied certificates.

no

Disable OCSP checking of junction server supplied certificates.

Usage

This stanza entry is optional.

Note: This option can be used as an alternative to, or in conjunction with, the jct-ocsp-url option.

Default value

no

Example

jct-ocsp-enable = no

Parent topic: [junction] stanza

jct-ocsp-max-response-sizejct-ocsp-max-response-sizejct-ocsp-max-response-size stanza entryjunction stanzaentriesjct-ocsp-max-response-sizejunction stanzajunction stanzajct-ocsp-max-response-size entrySyntax jct-ocsp-max-response-size = number of bytes Description Sets the maximum response size (in bytes) that will be accepted as a response from an OCSP responder. This limit helps protect against a denial of service attack. Options Maximum response size, in bytes. Usage This stanza entry is optional. Default value 204080 Example jct-ocsp-max-response-size = 20480 [junction] stanza

jct-ocsp-max-response-size

Syntax

jct-ocsp-max-response-size = number of bytes

Description

Sets the maximum response size (in bytes) that will be accepted as a response from an OCSP responder. This limit helps protect against a denial of service attack.

Options

Maximum response size, in bytes.

Usage

This stanza entry is optional.

Default value

204080

Example

jct-ocsp-max-response-size = 20480

Parent topic: [junction] stanza

jct-ocsp-nonce-check-enablejct-ocsp-nonce-check-enablejct-ocsp-nonce-check-enable stanza entryjunction stanzaentriesjct-ocsp-nonce-check-enablejunction stanzajunction stanzajct-ocsp-nonce-check-enable entrySyntax jct-ocsp-nonce-check-enable = {yes|no} Description Determines whether WebSEAL checks the nonce in the OCSP response. Enabling this option improves security but can cause OCSP Response validation to fail if there is a caching proxy between WebSEAL and the OCSP Responder. Note that enabling this option automatically enables the jct-ocsp-nonce-generation-enable option. Options yesWebSEAL checks the nonce in the OCSP response to verify that it matches the nonce from the request. noWebSEAL does not check the nonce in the OCSP response. Usage This stanza entry is optional. Default value no Example jct-ocsp-nonce-check-enable = no [junction] stanza

jct-ocsp-nonce-check-enable

Syntax

jct-ocsp-nonce-check-enable = {yes|no}

Description

Determines whether WebSEAL checks the nonce in the OCSP response. Enabling this option improves security but can cause OCSP Response validation to fail if there is a caching proxy between WebSEAL and the OCSP Responder. Note that enabling this option automatically enables the jct-ocsp-nonce-generation-enable option.

Options

yes

WebSEAL checks the nonce in the OCSP response to verify that it matches the nonce from the request.

no

WebSEAL does not check the nonce in the OCSP response.

Usage

This stanza entry is optional.

Default value

no

Example

jct-ocsp-nonce-check-enable = no

Parent topic: [junction] stanza

jct-ocsp-nonce-generation-enablejct-ocsp-nonce-generation-enablejct-ocsp-nonce-generation-enable stanza entryjunction stanzaentriesjct-ocsp-nonce-generation-enablejunction stanzajunction stanzajct-ocsp-nonce-generation-enable entrySyntax jct-ocsp-nonce-generation-enable = {yes|no} Description Determines whether WebSEAL generates a nonce as part of the OCSP request. Enabling this option can improve security by preventing replay attacks on WebSEAL but may cause an excessive load on an OCSP Responder appliance as the responder cannot use cached responses and must sign each response. Options yesWebSEAL generates a nonce as part of the OCSP request. noWebSEAL does not generate a nonce as part of the OCSP request. Usage This stanza entry is optional. Default value no Example jct-ocsp-nonce-generation-enable = no [junction] stanza

jct-ocsp-nonce-generation-enable

Syntax

jct-ocsp-nonce-generation-enable = {yes|no}

Description

Determines whether WebSEAL generates a nonce as part of the OCSP request. Enabling this option can improve security by preventing replay attacks on WebSEAL but may cause an excessive load on an OCSP Responder appliance as the responder cannot use cached responses and must sign each response.

Options

yes

WebSEAL generates a nonce as part of the OCSP request.

no

WebSEAL does not generate a nonce as part of the OCSP request.

Usage

This stanza entry is optional.

Default value

no

Example

jct-ocsp-nonce-generation-enable = no

Parent topic: [junction] stanza

jct-ocsp-proxy-server-namejct-ocsp-proxy-server-namejct-ocsp-proxy-server-name stanza entryjunction stanzaentriesjct-ocsp-proxy-server-namejunction stanzajunction stanzajct-ocsp-proxy-server-name entrySyntax jct-ocsp-proxy-server-name = <proxy host name> Description Specifies the name of the proxy server that provides access to the OCSP responder. Options proxy host nameFully qualified name of the proxy server. Usage This stanza entry is optional. Default value None Example jct-ocsp-proxy-server-name = proxy.ibm.com [junction] stanza

jct-ocsp-proxy-server-name

Syntax

jct-ocsp-proxy-server-name = <proxy host name>

Description

Specifies the name of the proxy server that provides access to the OCSP responder.

Options

proxy host name

Fully qualified name of the proxy server.

Usage

This stanza entry is optional.

Default value

None

Example

jct-ocsp-proxy-server-name = proxy.ibm.com

Parent topic: [junction] stanza

jct-ocsp-proxy-server-portjct-ocsp-proxy-server-portjct-ocsp-proxy-server-port stanza entryjunction stanzaentriesjct-ocsp-proxy-server-portjunction stanzajunction stanzajct-ocsp-proxy-server-port entrySyntax jct-ocsp-proxy-server-port = <proxy host port number> Description Specifies the port number of the proxy server that provides access to the OCSP Responder. Options proxy host port numberPort number used by the proxy server to route OCSP requests and responses. Usage This stanza entry is optional. Default value None Example jct-ocsp-proxy-server-port = 8888 [junction] stanza

jct-ocsp-proxy-server-port

Syntax

jct-ocsp-proxy-server-port = <proxy host port number>

Description

Specifies the port number of the proxy server that provides access to the OCSP Responder.

Options

proxy host port number

Port number used by the proxy server to route OCSP requests and responses.

Usage

This stanza entry is optional.

Default value

None

Example

jct-ocsp-proxy-server-port = 8888

Parent topic: [junction] stanza

jct-ocsp-urljct-ocsp-urljct-ocsp-url stanza entryjunction stanzaentriesjct-ocsp-urljunction stanzajunction stanzajct-ocsp-url entrySyntax jct-ocsp-url = <OCSP Responder URL> Description Specifies the URL for the OCSP Responder. If a URL is provided, WebSEAL uses OCSP for all revocation status checking regardless of whether the certificate has an Authority Information Access (AIA) extension, which means that OCSP works with existing certificates. WebSEAL tries the OCSP Responder that is configured by this method first, rather than using a location specified by AIA extension. If revocation status is undetermined, and if jct-ocsp-enable is set to yes, then WebSEAL tries to obtain revocation status using the access method in the AIA extension. Options OCSP Responder URLURL of the OCSP Responder. Usage This stanza entry is optional. Default value None Example jct-ocsp-url = http://responder.ibm.com/ [junction] stanza

jct-ocsp-url

Syntax

jct-ocsp-url = <OCSP Responder URL>

Description

Specifies the URL for the OCSP Responder. If a URL is provided, WebSEAL uses OCSP for all revocation status checking regardless of whether the certificate has an Authority Information Access (AIA) extension, which means that OCSP works with existing certificates. WebSEAL tries the OCSP Responder that is configured by this method first, rather than using a location specified by AIA extension. If revocation status is undetermined, and if jct-ocsp-enable is set to yes, then WebSEAL tries to obtain revocation status using the access method in the AIA extension.

Options

OCSP Responder URL

URL of the OCSP Responder.

Usage

This stanza entry is optional.

Default value

None

Example

jct-ocsp-url = http://responder.ibm.com/

Parent topic: [junction] stanza

jct-ssl-reneg-warning-ratejct-ssl-reneg-warning-ratejct-ssl-reneg-warning-rate stanza entryjunction stanzaentriesjct-ssl-reneg-warning-ratejunction stanzajunction stanzajct-ssl-reneg-warning-rate entrySyntax jct-ssl-reneg-warning-rate = number_renegotiations/minuteDescription When this option is set to a value greater than zero (0), WebSEAL produces a warning message if the SSL session renegotiation rate between junction servers and WebSEAL reaches this level or greater. The value is specified as the number of renegotiations per minute.Options number_renegotiations/minuteRate of session renegotiations between junction servers and WebSEAL.Usage This stanza entry is required.Default value 0Example jct-ssl-reneg-warning-rate = 0[junction] stanza

jct-ssl-reneg-warning-rate

Syntax

jct-ssl-reneg-warning-rate = number_renegotiations/minute

Description

When this option is set to a value greater than zero (0), WebSEAL produces a warning message if the SSL session renegotiation rate between junction servers and WebSEAL reaches this level or greater. The value is specified as the number of renegotiations per minute.

Options

number_renegotiations/minute

Rate of session renegotiations between junction servers and WebSEAL.

Usage

This stanza entry is required.

Default value

0

Example

jct-ssl-reneg-warning-rate = 0

Parent topic: [junction] stanza

jct-undetermined-revocation-cert-actionjct-undetermined-revocation-cert-actionjct-undetermined-revocation-cert-action stanza entryjunction stanzaentriesjct-undetermined-revocation-cert-actionjunction stanzajunction stanzajct-undetermined-revocation-cert-action entrySyntax jct-undetermined-revocation-cert-action = {ignore | log | reject} Description Controls the action that WebSEAL takes if OCSP or CRL is enabled but the responder cannot determine the revocation status of a certificate (that is, the revocation status is unknown). The appropriate values for this entry should be provided by the OCSP or CRL Responder owner. Options ignoreWebSEAL ignores the undetermined revocation status and permits use of the certificate.logWebSEAL logs the fact that the certificate status is undetermined and permits use of the certificate.rejectWebSEAL logs the fact that the certificate status is undetermined and rejects the certificate. Usage This stanza entry is optional. Default value log Example jct-undetermined-revocation-cert-action = log [junction] stanza

jct-undetermined-revocation-cert-action

Syntax

jct-undetermined-revocation-cert-action = {ignore | log | reject}

Description

Controls the action that WebSEAL takes if OCSP or CRL is enabled but the responder cannot determine the revocation status of a certificate (that is, the revocation status is unknown). The appropriate values for this entry should be provided by the OCSP or CRL Responder owner.

Options

ignore

WebSEAL ignores the undetermined revocation status and permits use of the certificate.

log

WebSEAL logs the fact that the certificate status is undetermined and permits use of the certificate.

reject

WebSEAL logs the fact that the certificate status is undetermined and rejects the certificate.

Usage

This stanza entry is optional.

Default value

log

Example

jct-undetermined-revocation-cert-action = log

Parent topic: [junction] stanza

jmt-mapjmt-mapjmt-map stanza entryjunction stanzaentriesjmt-mapjunction stanzajunction stanzajmt-map entrySyntax jmt-map = file_name Description The name of the file that contains the location of the Junction-to- Request Mapping Table (JMT). The administrator can rename this file if necessary. The file name can be any file name valid for the operating system file system. Options file_nameName of the file that contains the location of the Junction-to- Request Mapping Table (JMT). Usage This stanza entry is required. Default value jmt.conf Example jmt-map = jmt.conf [junction] stanza

jmt-map

Syntax

jmt-map = file_name

Description

The name of the file that contains the location of the Junction-to- Request Mapping Table (JMT).

The administrator can rename this file if necessary. The file name can be any file name valid for the operating system file system.

Options

file_name

Name of the file that contains the location of the Junction-to- Request Mapping Table (JMT).

Usage

This stanza entry is required.

Default value

jmt.conf

Example

jmt-map = jmt.conf

Parent topic: [junction] stanza

kerberos-keytab-fileUse the kerberos-keytab-file entry to set the name of the Kerberos key table file for the WebSEAL server. kerberos-keytab-file stanza entryjunction stanzaentrieskerberos-keytab-filejunction stanzajunction stanzakerberos-keytab-file entrySyntax kerberos-keytab-file = keytab_file_name Description This stanza entry defines the Kerberos key table file for the WebSEAL server. Options keytab_file_nameThe name of the Kerberos key table file. Usage This stanza entry is required when Kerberos SSO authentication for junctions is enabled. Default value None.Example kerberos-keytab-file = example.kdb [junction] stanza

kerberos-keytab-file

Use the kerberos-keytab-file entry to set the name of the Kerberos key table file for the WebSEAL server.

Syntax

kerberos-keytab-file = keytab_file_name

Description

This stanza entry defines the Kerberos key table file for the WebSEAL server.

Options

keytab_file_name

The name of the Kerberos key table file.

Usage

This stanza entry is required when Kerberos SSO authentication for junctions is enabled.

Default value

None.

Example

kerberos-keytab-file = example.kdb

Parent topic: [junction] stanza

kerberos-principal-nameUse the kerberos-principal-name entry to set the service principal name of the impersonating user when creating a Kerberos token. kerberos-principal-name stanza entryjunction stanzaentrieskerberos-principal-namejunction stanzajunction stanzakerberos-principal-name entrySyntax kerberos-principal-name = principal_name Description The service principal name can be determined by executing the Microsoft utility setspn. For example: setspn -L userwhere user is the identity of the WebSEAL account. Options principal_nameThe service principal name of the impersonating user when creating a Kerberos token. Usage This stanza entry is required when Kerberos SSO authentication for junctions is enabled. Default value None.Example kerberos-principal-name = HTTP/webseal@<realm> [junction] stanza

kerberos-principal-name

Use the kerberos-principal-name entry to set the service principal name of the impersonating user when creating a Kerberos token.

Syntax

kerberos-principal-name = principal_name

Description

The service principal name can be determined by executing the Microsoft utility setspn. For example:

setspn -L user

where user is the identity of the WebSEAL account.

Options

principal_name

The service principal name of the impersonating user when creating a Kerberos token.

Usage

This stanza entry is required when Kerberos SSO authentication for junctions is enabled.

Default value

None.

Example

kerberos-principal-name = HTTP/webseal@<realm>

Parent topic: [junction] stanza

kerberos-user-identityUse the kerberos-user-identity stanza entry to enable and define a custom user principal name (UPN). The custom UPN can be constructed from either plain text or the contents of credential attributes.kerberos-user-identity stanza entryjunction stanzaentrieskerberos-user-identityjunction stanzajunction stanzakerberos-user-identity entrySyntax kerberos-user-identity = username@domain kerberos-user-identity = username kerberos-user-identity = @domain kerberos-user-identity = fqdnDescription An administrator can overwrite the UPN or sections of the UPN for Kerberos constrained delegation users with this entry. The replacement information can be either plain text or names of credential attributes that store the required information. If you specify plain text, the text is directly copied into the UPN sections. If you specify names of credential attributes, the replacement text is fetched from the value of the corresponding credential attribute. The domain information can also be extracted from the DC elements of the user's DN through the attribute attr:dn. If no user name is defined, the client credential name is used. If no domain is defined, the WebSEAL service account domain is used. The domain value must be uppercase. Any input data that is not uppercase is automatically converted to uppercase. The domain must also be added as a realm to the Kerberos configuration.Options username@domainReplaces both the user name and the domain separately.usernameReplaces only the user name. The WebSEAL service account domain is used as the user domain.@domainReplaces only the domain. The user name is obtained from the client credential.fqdnReplaces both the user name and domain with a single attribute. The value of this attribute must contain both the user name and the domain.Usage This stanza entry is optional. It can be customized for a particular junction in the [junction: junction_name] stanza.Default value NoneExample kerberos-user-identity = bob@IBM.COM kerberos-user-identity = attr:SamAccountName@IBM.COM kerberos-user-identity = @attr:dn kerberos-user-identity = attr:FQDN[junction] stanza

kerberos-user-identity

Use the kerberos-user-identity stanza entry to enable and define a custom user principal name (UPN). The custom UPN can be constructed from either plain text or the contents of credential attributes.

Syntax

kerberos-user-identity = username@domain
kerberos-user-identity = username
kerberos-user-identity = @domain
kerberos-user-identity = fqdn

Description

An administrator can overwrite the UPN or sections of the UPN for Kerberos constrained delegation users with this entry. The replacement information can be either plain text or names of credential attributes that store the required information. If you specify plain text, the text is directly copied into the UPN sections. If you specify names of credential attributes, the replacement text is fetched from the value of the corresponding credential attribute.

The domain information can also be extracted from the DC elements of the user's DN through the attribute attr:dn.

If no user name is defined, the client credential name is used.

If no domain is defined, the WebSEAL service account domain is used.

The domain value must be uppercase. Any input data that is not uppercase is automatically converted to uppercase. The domain must also be added as a realm to the Kerberos configuration.

Options

username@domain

Replaces both the user name and the domain separately.

username

Replaces only the user name. The WebSEAL service account domain is used as the user domain.

@domain

Replaces only the domain. The user name is obtained from the client credential.

fqdn

Replaces both the user name and domain with a single attribute. The value of this attribute must contain both the user name and the domain.

Usage

This stanza entry is optional. It can be customized for a particular junction in the [junction: junction_name] stanza.

Default value

None

Example

kerberos-user-identity = bob@IBM.COM
kerberos-user-identity = attr:SamAccountName@IBM.COM
kerberos-user-identity = @attr:dn
kerberos-user-identity = attr:FQDN

Parent topic: [junction] stanza

kerberos-sso-enableUse the kerberos-sso-enable entry to enable or disable SSO for junctions.kerberos-sso-enable stanza entryjunction stanzaentrieskerberos-sso-enablejunction stanzajunction stanzakerberos-sso-enable entrySyntax kerberos-sso-enable = {yes|true|no|false} Description You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. Options yesEnable.trueEnable.noDisable.falseDisable. Usage This stanza entry is required. Default value no.Example kerberos-sso-enable = no [junction] stanza

kerberos-sso-enable

Use the kerberos-sso-enable entry to enable or disable SSO for junctions.

Syntax

kerberos-sso-enable = {yes|true|no|false}

Description

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

Options

yes

Enable.

true

Enable.

no

Disable.

false

Disable.

Usage

This stanza entry is required.

Default value

no.

Example

kerberos-sso-enable = no

Parent topic: [junction] stanza

managed-cookies-listmanaged-cookies-listmanaged-cookies-list stanza entryjunction stanzaentriesmanaged-cookies-listjunction stanzajunction stanzamanaged-cookies-list entrySyntax managed-cookies-list = list DescriptionThe managed-cookies-list contains a comma-separated list of patterns that will be matched against the names of cookies returned by junctioned servers. Cookies with names that match the patterns in this list are stored in the WebSEAL cookie jar and not returned to the client. Cookies that do not match these patterns are returned to the client browser. The WebSEAL cookie jar is turned off by not specifying any cookies in the managed-cookies-list.You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.OptionslistA comma-separated list of pattern-matched cookie names. UsageThis stanza entry is optional. Default valueThis option is empty by default. managed-cookies-list = JSESS*,Ltpa* [junction] stanza

managed-cookies-list

Syntax

managed-cookies-list = list

Description

The managed-cookies-list contains a comma-separated list of patterns that will be matched against the names of cookies returned by junctioned servers. Cookies with names that match the patterns in this list are stored in the WebSEAL cookie jar and not returned to the client. Cookies that do not match these patterns are returned to the client browser.

The WebSEAL cookie jar is turned off by not specifying any cookies in the managed-cookies-list.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

list

A comma-separated list of pattern-matched cookie names.

Usage

This stanza entry is optional.

Default value

This option is empty by default.

managed-cookies-list = JSESS*,Ltpa*

Parent topic: [junction] stanza

mangle-domain-cookiesmangle-domain-cookiesmangle-domain-cookies stanza entryjunction stanzaentriesmangle-domain-cookiesjunction stanzajunction stanzamangle-domain-cookies entrySyntax mangle-domain-cookies = {yes | no}Description Enables or disables WebSEAL domain cookie name mangling behavior. This option enables domain cookie mangling on a server-wide basis. The option cannot be configured on a per-junction basis.This option is relevant only for junctions that use a reprocessing solution such as -j or JMT.This option does not affect cookies listed in preserve-cookie-names.Options yesEnables WebSEAL to mangle the names of domain cookies. Information identifying the junction is added to the cookie name, and the cookie is only associated with that junction. If mangle-path-into-cookie-name is set to yes, then the backend path attribute information is also mangled into the cookie name.noWebSEAL will not mangle the names of domain cookies.Usage This stanza entry is optional.Default value This option is disabled by default.Example mangle-domain-cookies = yes[junction] stanza

mangle-domain-cookies

Syntax

mangle-domain-cookies = {yes | no}

Description

Enables or disables WebSEAL domain cookie name mangling behavior.

Note:

This option enables domain cookie mangling on a server-wide basis. The option cannot be configured on a per-junction basis.

This option is relevant only for junctions that use a reprocessing solution such as -j or JMT.

This option does not affect cookies listed in preserve-cookie-names.

Options

yes

Enables WebSEAL to mangle the names of domain cookies. Information identifying the junction is added to the cookie name, and the cookie is only associated with that junction. If mangle-path-into-cookie-name is set to yes, then the backend path attribute information is also mangled into the cookie name.

no

WebSEAL will not mangle the names of domain cookies.

Usage

This stanza entry is optional.

Default value

This option is disabled by default.

Example

mangle-domain-cookies = yes

Parent topic: [junction] stanza

match-vhj-firstmatch-vhj-firstHelps determine the order in which WebSEAL searches for a request in a standard or a virtual host junction table.match-vhj-first stanza entryjunction stanzaentriesmatch-vhj-firstjunction stanzajunction stanzamatch-vhj-first entrySyntax match-vhj-first = {yes|no} DescriptionWebSEAL manages separate junction tables for standard and virtual host junctions. When a request comes in, WebSEAL searches the virtual host junction table first. If WebSEAL does not find a match, it searches the table that manages standard junctions. The match-vhj-first configuration can reverse the search order so that WebSEAL searches the standard junction table before searching the virtual host junction table. OptionsyesWebSEAL searches the virtual host junction table first. noWebSEAL searches the standard junction table first. UsageThis stanza entry is not optional. Default valueyes ExampleThe following example tells WebSEAL to search the standard junction table first:match-vhj-first = no [junction] stanza

match-vhj-first

Helps determine the order in which WebSEAL searches for a request in a standard or a virtual host junction table.

Syntax

match-vhj-first = {yes|no}

Description

WebSEAL manages separate junction tables for standard and virtual host junctions. When a request comes in, WebSEAL searches the virtual host junction table first. If WebSEAL does not find a match, it searches the table that manages standard junctions. The match-vhj-first configuration can reverse the search order so that WebSEAL searches the standard junction table before searching the virtual host junction table.

Options

yes

WebSEAL searches the virtual host junction table first.

no

WebSEAL searches the standard junction table first.

Usage

This stanza entry is not optional.

Default value

yes

Example

The following example tells WebSEAL to search the standard junction table first:

match-vhj-first = no

Parent topic: [junction] stanza

max-cached-persistent-connectionsmax-cached-persistent-connectionsmax-cached-persistent-connectionse stanza entryjunction stanzaentriesmax-cached-persistent-connectionsjunction stanzajunction stanzamax-cached-persistent-connections entrySyntax max-cached-persistent-connections = number_of_connections DescriptionThe maximum number of persistent connections that will be stored in the cache for future use. Connections with junctioned Web servers will be cached for future use unless the configured limit (as defined by this configuration entry) is reached, or unless the connection:close header is received in the HTTP response. If this setting is enabled, there is the potential for different user sessions to use the same connection when processing junction requests. To disable the persistent connection functionality, specify a max-cached-persistent-connections value of zero (0). You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.Optionsnumber_of_connectionsInteger value indicating the maximum number of persistent connections that will be stored in the cache for future use. A value of zero (0) disables this support. WebSEAL imposes no maximum on this value. UsageThis stanza entry is required. Default value0 max-cached-persistent-connections = 0 [junction] stanza

max-cached-persistent-connections

Syntax

max-cached-persistent-connections = number_of_connections

Description

The maximum number of persistent connections that will be stored in the cache for future use. Connections with junctioned Web servers will be cached for future use unless the configured limit (as defined by this configuration entry) is reached, or unless the connection:close header is received in the HTTP response.

Note: If this setting is enabled, there is the potential for different user sessions to use the same connection when processing junction requests. To disable the persistent connection functionality, specify a max-cached-persistent-connections value of zero (0).

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

number_of_connections

Integer value indicating the maximum number of persistent connections that will be stored in the cache for future use. A value of zero (0) disables this support. WebSEAL imposes no maximum on this value.

Usage

This stanza entry is required.

Default value

0

max-cached-persistent-connections = 0

Parent topic: [junction] stanza

max-webseal-header-sizemax-webseal-header-sizemax-webseal-header-size stanza entryjunction stanzaentriesmax-webseal-header-sizejunction stanzajunction stanzamax-webseal-header-size entrySyntax max-webseal-header-size = number_of_bytesDescription Integer value indicating the maximum size, in bytes, of HTTP headers generated by the WebSEAL server. Headers greater in size that this value are split across multiple HTTP Headers. The max-webseal-header-size entry does not limit the maximum size of HTTP-Tag-Value headers.Options number_of_bytesInteger value indicating the maximum size, in bytes, of HTTP headers generated by the WebSEAL server. A value of zero (0) disables this support. WebSEAL imposes no maximum on this value. Usage This stanza entry is required.Default value 0Example max-webseal-header-size = 0[junction] stanza

max-webseal-header-size

Syntax

max-webseal-header-size = number_of_bytes

Description

Integer value indicating the maximum size, in bytes, of HTTP headers generated by the WebSEAL server. Headers greater in size that this value are split across multiple HTTP Headers.

Note: The max-webseal-header-size entry does not limit the maximum size of HTTP-Tag-Value headers.

Options

number_of_bytes

Integer value indicating the maximum size, in bytes, of HTTP headers generated by the WebSEAL server. A value of zero (0) disables this support. WebSEAL imposes no maximum on this value.

Usage

This stanza entry is required.

Default value

0

Example

max-webseal-header-size = 0

Parent topic: [junction] stanza

pass-http-only-cookie-attrpass-http-only-cookie-attrpass-http-only-cookie-attr stanza entryjunction stanzaentriespass-http-only-cookie-attrjunction stanzajunction stanzapass-http-only-cookie-attr entrySyntax pass-http-only-cookie-attr = {yes|no} Description Indicates whether WebSEAL will pass or remove the HTTP-only attribute from the Set-Cookie headers sent by junctioned servers. Options yesEnables WebSEAL to pass the HTTP-only attribute from Set-Cookie headers sent by junctioned servers.noEnables WebSEAL to remove the HTTP-only attribute from Set-Cookie headers sent by junctioned servers. Usage This stanza entry is required. Default value yes Example pass-http-only-cookie-attr = yes [junction] stanza

pass-http-only-cookie-attr

Syntax

pass-http-only-cookie-attr = {yes|no}

Description

Indicates whether WebSEAL will pass or remove the HTTP-only attribute from the Set-Cookie headers sent by junctioned servers.

Options

yes

Enables WebSEAL to pass the HTTP-only attribute from Set-Cookie headers sent by junctioned servers.

no

Enables WebSEAL to remove the HTTP-only attribute from Set-Cookie headers sent by junctioned servers.

Usage

This stanza entry is required.

Default value

yes

Example

pass-http-only-cookie-attr = yes

Parent topic: [junction] stanza

persistent-con-timeoutpersistent-con-timeoutpersistent-con-timeout stanza entryjunction stanzaentriespersistent-con-timeoutjunction stanzajunction stanzapersistent-con-timeout entrySyntax persistent-con-timeout = number_of_seconds Description Indicates the maximum number of seconds a persistent connection can remain idle in a cache before the connection is cleaned up and closed by WebSEAL. Use an integer value lower than the configured maximum connection lifetime for the junctioned web server. For example, the connection lifetime for a junctioned Apache web server is controlled by the KeepAliveTimeout configuration entry. You can customize the persistent-con-timeout configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_id}] stanza. where {junction_id} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. If you do not use an integer value lower than the connection lifetime on the junctioned web server, you might encounter the following problem. If the [junction] max-cached-persistent-connections configuration entry is set to a value greater than zero, WebSEAL reuses its TCP/IP session with the junctioned back-end server. If the junctioned back-end server closes the socket at the same time that WebSEAL starts to use this session to send a request, the request fails.To send the request again, WebSEAL opens a new TCP/IP session. If the request body is larger than the size that WebSEAL can cache, WebSEAL fails to resend the request and generates a 500 error. Options number_of_secondsInteger value that indicates the maximum number of seconds a persistent connection can remain idle in a cache before the connection is closed by WebSEAL. The minimum value is 1. WebSEAL does not impose a maximum value. Usage This stanza entry is required. Default value 5 Examplepersistent-con-timeout = 5 [junction] stanza

persistent-con-timeout

Syntax

persistent-con-timeout = number_of_seconds

Description

Indicates the maximum number of seconds a persistent connection can remain idle in a cache before the connection is cleaned up and closed by WebSEAL.

Use an integer value lower than the configured maximum connection lifetime for the junctioned web server. For example, the connection lifetime for a junctioned Apache web server is controlled by the KeepAliveTimeout configuration entry.

You can customize the persistent-con-timeout configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_id}] stanza.

where {junction_id} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Note: If you do not use an integer value lower than the connection lifetime on the junctioned web server, you might encounter the following problem.

If the [junction] max-cached-persistent-connections configuration entry is set to a value greater than zero, WebSEAL reuses its TCP/IP session with the junctioned back-end server. If the junctioned back-end server closes the socket at the same time that WebSEAL starts to use this session to send a request, the request fails.

To send the request again, WebSEAL opens a new TCP/IP session. If the request body is larger than the size that WebSEAL can cache, WebSEAL fails to resend the request and generates a 500 error.

Options

number_of_seconds

Integer value that indicates the maximum number of seconds a persistent connection can remain idle in a cache before the connection is closed by WebSEAL. The minimum value is 1. WebSEAL does not impose a maximum value.

Usage

This stanza entry is required.

Default value

5

Example

persistent-con-timeout = 5

Parent topic: [junction] stanza

ping-methodping-methodping-method stanza entryjunction stanzaentriesping-methodjunction stanzajunction stanzaping-method entrySyntax ping-method = method Description The WebSEAL server performs a periodic background ping of each junctioned Web server, to determine whether it is running. The optional ping-method entry sets the HTTP request type used in these pings. The valid options include any valid HTTP request method (for example, HEAD or GET, for HTTP HEAD and HTTP GET requests respectively). This configuration item may be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Options methodPerform a HTTP request using the specified method to determine the state of the junctioned server. Usage This stanza entry is optional. Default value HEAD ping-method = GET [junction] stanza

ping-method

Syntax

ping-method = method

Description

The WebSEAL server performs a periodic background ping of each junctioned Web server, to determine whether it is running. The optional ping-method entry sets the HTTP request type used in these pings. The valid options include any valid HTTP request method (for example, HEAD or GET, for HTTP HEAD and HTTP GET requests respectively).

This configuration item may be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

method

Perform a HTTP request using the specified method to determine the state of the junctioned server.

Usage

This stanza entry is optional.

Default value

HEAD

ping-method = GET

Parent topic: [junction] stanza

ping-timeping-timeping-time stanza entryjunction stanzaentriesping-timejunction stanzajunction stanzaping-time entrySyntax ping-time = number_of_seconds Description Integer value indicating the number of seconds between pings issued by the WebSEAL server. The pings are issued periodically in the background to verify that junctioned WebSEAL servers are running. If the server is deemed not running, the recovery-ping-time value determines the interval at which pings are sent until the server is running. The type of ping used is determined by the ping-method value. HTTP response code rules can be defined using the response-code-rules configuration entry. Options number_of_secondsInteger value indicating the number of seconds between pings issued by the WebSEAL server. The minimum value is 1. WebSEAL does not impose a maximum value. Usage To turn this ping off, set this entry to zero. If this entry is set to zero, the recovery-ping-time must be set. Default value 300 Example ping-time = 300 [junction] stanza

ping-time

Syntax

ping-time = number_of_seconds

Description

Integer value indicating the number of seconds between pings issued by the WebSEAL server. The pings are issued periodically in the background to verify that junctioned WebSEAL servers are running.

If the server is deemed not running, the recovery-ping-time value determines the interval at which pings are sent until the server is running. The type of ping used is determined by the ping-method value. HTTP response code rules can be defined using the response-code-rules configuration entry.

Options

number_of_seconds

Integer value indicating the number of seconds between pings issued by the WebSEAL server. The minimum value is 1. WebSEAL does not impose a maximum value.

Usage

To turn this ping off, set this entry to zero. If this entry is set to zero, the recovery-ping-time must be set.

Default value

300

Example

ping-time = 300

Parent topic: [junction] stanza

ping-uriping-uriping-uri stanza entryjunction stanzaentriesping-urijunction stanzajunction stanzaping-uri entrySyntax ping-uri = uri Description The WebSEAL server performs a periodic background ping of each junctioned Web server to determine whether it is running. The optional ping-uri configuration entry defines the URI that is accessed by the ping request. The defined URI is relative to the root Web space of the junctioned Web server. If the URI is missing, this value defaults to a /. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Options uriThe URI that is accessed by the ping request. Usage This stanza entry is optional. Default value / ping-uri = /apps/status [junction] stanza

ping-uri

Syntax

ping-uri = uri

Description

The WebSEAL server performs a periodic background ping of each junctioned Web server to determine whether it is running. The optional ping-uri configuration entry defines the URI that is accessed by the ping request. The defined URI is relative to the root Web space of the junctioned Web server. If the URI is missing, this value defaults to a /.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

uri

The URI that is accessed by the ping request.

Usage

This stanza entry is optional.

Default value

/

ping-uri = /apps/status

Parent topic: [junction] stanza

recovery-ping-timerecovery-ping-timerecovery-ping-time stanza entryjunction stanzaentriesrecovery-ping-timejunction stanzajunction stanzarecovery-ping-time entrySyntax recovery-ping-time = number_of_seconds Description The WebSEAL server performs a periodic background ping of each junctioned Web server, to determine whether it is running. This entry sets the interval, in seconds, between pings when the server is determined to be not running. Options number_of_secondsInteger value indicating the number of seconds between pings issued by the WebSEAL server to a junctioned server that is determined to be not running. The minimum value is 1. WebSEAL does not impose a maximum value. Usage If this entry is not set, the recovery-ping-time defaults to the ping-time value. Default value 300 Example recovery-ping-time = 300 [junction] stanza

recovery-ping-time

Syntax

recovery-ping-time = number_of_seconds

Description

The WebSEAL server performs a periodic background ping of each junctioned Web server, to determine whether it is running. This entry sets the interval, in seconds, between pings when the server is determined to be not running.

Options

number_of_seconds

Integer value indicating the number of seconds between pings issued by the WebSEAL server to a junctioned server that is determined to be not running. The minimum value is 1. WebSEAL does not impose a maximum value.

Usage

If this entry is not set, the recovery-ping-time defaults to the ping-time value.

Default value

300

Example

recovery-ping-time = 300

Parent topic: [junction] stanza

reprocess-root-jct-404sreprocess-root-jct-404sreprocess-root-jct-404s stanza entryjunction stanzaentriesreprocess-root-jct-404sjunction stanzajunction stanzareprocess-root-jct-404s entrySyntax reprocess-root-jct-404s = {yes|no}Description Used to reprocess requests for root junction resources that result in an HTTP 404 error. The dont-reprocess-jct-404s entry (also in the [junction] stanza) can be set to yes to avoid multiple attempts to prepend a junction point to the beginning of the URL string when reprocessing requests that have resulted in an HTTP 404 status code. WebSEAL determines whether the request is already known to be for a non-local junction.However, WebSEAL fails to add a junction point when requests have been made for a root junction created at "/". To modify this behavior and cause requests for root junction resources that result in an HTTP 404 error to be reprocessed, you can use this reprocess-root-jct-404s stanza entry.Options yesCause requests for root junction resources that result in an HTTP 404 error to be reprocessed regardless of the setting of the dont-reprocess-jct-404s entry (also in the [junction] stanza).noThe value for the dont-reprocess-jct-404s entry (also in the [junction] stanza) will determine whether root junction requests that result in an HTTP 404 error are reprocessed. That is, if the value for dont-reprocess-jct-404s is no then the HTTP 404 errors will still be reprocessed.Usage This stanza entry is optional.Default value noExample reprocess-root-jct-404s = yes[junction] stanza

reprocess-root-jct-404s

Syntax

reprocess-root-jct-404s = {yes|no}

Description

Used to reprocess requests for root junction resources that result in an HTTP 404 error.

The dont-reprocess-jct-404s entry (also in the [junction] stanza) can be set to yes to avoid multiple attempts to prepend a junction point to the beginning of the URL string when reprocessing requests that have resulted in an HTTP 404 status code.

WebSEAL determines whether the request is already known to be for a non-local junction.However, WebSEAL fails to add a junction point when requests have been made for a root junction created at "/". To modify this behavior and cause requests for root junction resources that result in an HTTP 404 error to be reprocessed, you can use this reprocess-root-jct-404s stanza entry.

Options

yes

Cause requests for root junction resources that result in an HTTP 404 error to be reprocessed regardless of the setting of the dont-reprocess-jct-404s entry (also in the [junction] stanza).

no

The value for the dont-reprocess-jct-404s entry (also in the [junction] stanza) will determine whether root junction requests that result in an HTTP 404 error are reprocessed. That is, if the value for dont-reprocess-jct-404s is no then the HTTP 404 errors will still be reprocessed.

Usage

This stanza entry is optional.

Default value

no

Example

reprocess-root-jct-404s = yes

Parent topic: [junction] stanza

reset-cookies-listreset-cookies-listreset-cookies-list stanza entryjunction stanzaentriesreset-cookies-listjunction stanzajunction stanzareset-cookies-list entrySyntax reset-cookies-list = list Description Determines which cookies are reset when the user session is logged out. The request received from the client and the response sent back to the client are both examined for matching cookies. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Options listA comma-separated list of patterns. WebSEAL will reset any cookies with names that match the patterns in this list. Usage This stanza entry is required. Default value None. reset-cookies-list = JSESS*,Ltpa* [junction] stanza

reset-cookies-list

Syntax

reset-cookies-list = list

Description

Determines which cookies are reset when the user session is logged out. The request received from the client and the response sent back to the client are both examined for matching cookies.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

list

A comma-separated list of patterns. WebSEAL will reset any cookies with names that match the patterns in this list.

Usage

This stanza entry is required.

Default value

None.

reset-cookies-list = JSESS*,Ltpa*

Parent topic: [junction] stanza

response-code-rulesresponse-code-rulesresponse-code-rules entryjunction stanzaentriesresponse-code-rulesjunction stanzajunction stanzaresponse-code-rules entrySyntax response-code-rules = list Description The WebSEAL server performs a periodic background ping of each junctioned Web server to determine whether it is running. The optional response-code-rules configuration entry defines the rules that are used to determine whether HTTP responses indicate a healthy or an unhealthy junctioned Web server. The configuration entry contains a space separated list of rules. Each rule has the format: [+|-]<code> (e.g. -50?) where: +Indicates that this is a healthy response code.-Indicates that this is an unhealthy response code.<code>The corresponding response code, which can also contain pattern matching characters such as * and ? The HTTP response codes are evaluated against each rule in sequence until a match is found. The corresponding code (+|-) determines whether the junctioned Web server is healthy or not.If the response code matches no configured rules, the junctioned Web server is considered healthy. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Options listA space separated list of response code rules. These rules determine whether the response from a junctioned Web server indicates a healthy or an unhealthy server. Usage This stanza entry is optional. Default value None. response-code-rules = +2?? -* [junction] stanza

response-code-rules

Syntax

response-code-rules = list

Description

The WebSEAL server performs a periodic background ping of each junctioned Web server to determine whether it is running. The optional response-code-rules configuration entry defines the rules that are used to determine whether HTTP responses indicate a healthy or an unhealthy junctioned Web server.

The configuration entry contains a space separated list of rules. Each rule has the format: [+|-]<code> (e.g. -50?)

where:

+

Indicates that this is a healthy response code.

-

Indicates that this is an unhealthy response code.

<code>

The corresponding response code, which can also contain pattern matching characters such as * and ?

The HTTP response codes are evaluated against each rule in sequence until a match is found. The corresponding code (+|-) determines whether the junctioned Web server is healthy or not.If the response code matches no configured rules, the junctioned Web server is considered healthy.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

list

A space separated list of response code rules. These rules determine whether the response from a junctioned Web server indicates a healthy or an unhealthy server.

Usage

This stanza entry is optional.

Default value

None.

response-code-rules = +2?? -*

Parent topic: [junction] stanza

share-cookiesshare-cookiesshare-cookies stanza entryjunction stanzaentriesshare-cookiesjunction stanzajunction stanzashare-cookies entrySyntax share-cookies = {yes|no}Description The share-cookies item is used to control whether the cookie jar will be shared across different junctions or whether each junction will have a dedicated cookie jar. Options yesIf this entry is set to yes, cookies will be sent over all junctions, regardless of the junction from which the cookie originated.noIf this entry is set to no, only cookies received from the junction will be sent in requests to that junction.Usage This stanza entry is required.Default value noExample share-cookies = yes[junction] stanza

share-cookies

Syntax

share-cookies = {yes|no}

Description

The share-cookies item is used to control whether the cookie jar will be shared across different junctions or whether each junction will have a dedicated cookie jar.

Options

yes

If this entry is set to yes, cookies will be sent over all junctions, regardless of the junction from which the cookie originated.

no

If this entry is set to no, only cookies received from the junction will be sent in requests to that junction.

Usage

This stanza entry is required.

Default value

no

Example

share-cookies = yes

Parent topic: [junction] stanza

support-virtual-host-domain-cookiessupport-virtual-host-domain-cookiessupport-virtual-host-domain-cookies stanza entryjunction stanzaentriessupport-virtual-host-domain-cookiesjunction stanzajunction stanzasupport-virtual-host-domain-cookies entrySyntax support-virtual-host-domain-cookies = {yes|no} Description If allow-backend-domain-cookies is set to yes, then this option modifies how WebSEAL validates the domain. This option has no effect if validate-backend-domain-cookies = no. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Options yesIf set to "yes" then the domain cookie is validated by comparing it with the virtual host specified for a backend server with the -v junction option.noIf set to "no", or if no virtual host was specified for a junction, then the fully qualified host name is compared with the domain value of a backend cookie for validation. Usage This stanza entry is required. Default value yes support-virtual-host-domain-cookies = yes [junction] stanza

support-virtual-host-domain-cookies

Syntax

support-virtual-host-domain-cookies = {yes|no}

Description

If allow-backend-domain-cookies is set to yes, then this option modifies how WebSEAL validates the domain. This option has no effect if validate-backend-domain-cookies = no.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

yes

If set to "yes" then the domain cookie is validated by comparing it with the virtual host specified for a backend server with the -v junction option.

no

If set to "no", or if no virtual host was specified for a junction, then the fully qualified host name is compared with the domain value of a backend cookie for validation.

Usage

This stanza entry is required.

Default value

yes

support-virtual-host-domain-cookies = yes

Parent topic: [junction] stanza

use-new-stateful-on-erroruse-new-stateful-on-erroruse-new-stateful-on-error stanza entryjunction stanzaentriesuse-new-stateful-on-errorjunction stanzajunction stanzause-new-stateful-on-error entrySyntax use-new-stateful-on-error = {yes|no}Description Control how WebSEAL responds to a stateful server that becomes unavailable. This configuration item may be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. For example: [junction:/WebApp]Options yesWhen set to "yes" and the original server becomes unavailable during a session, WebSEAL directs the user's next request (containing the original stateful cookie) to a new replica server on the same stateful junction. If a new replica server is found on that stateful junction, and is responsive to the request, WebSEAL sets a new stateful cookie on the user's browser. Subsequent requests during this same session (and containing the new stateful cookie) are directed to this same new server.noWhen set to "no" and the original server becomes unavailable during a session, WebSEAL does not direct the user's subsequent requests to a new replica server on the same stateful junction. Instead, WebSEAL returns an error and attempts to access the same server for subsequent requests by the user during this session.Usage This stanza entry is required.Default value noExample use-new-stateful-on-error = yes[junction] stanza

use-new-stateful-on-error

Syntax

use-new-stateful-on-error = {yes|no}

Description

Control how WebSEAL responds to a stateful server that becomes unavailable.

This configuration item may be customized for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. For example:

[junction:/WebApp]

Options

yes

When set to "yes" and the original server becomes unavailable during a session, WebSEAL directs the user's next request (containing the original stateful cookie) to a new replica server on the same stateful junction. If a new replica server is found on that stateful junction, and is responsive to the request, WebSEAL sets a new stateful cookie on the user's browser. Subsequent requests during this same session (and containing the new stateful cookie) are directed to this same new server.

no

When set to "no" and the original server becomes unavailable during a session, WebSEAL does not direct the user's subsequent requests to a new replica server on the same stateful junction. Instead, WebSEAL returns an error and attempts to access the same server for subsequent requests by the user during this session.

Usage

This stanza entry is required.

Default value

no

Example

use-new-stateful-on-error = yes

Parent topic: [junction] stanza

validate-backend-domain-cookiesvalidate-backend-domain-cookiesvalidate-backend-domain-cookies stanza entryjunction stanzaentriesvalidate-backend-domain-cookiesjunction stanzajunction stanzavalidate-backend-domain-cookies entrySyntax validate-backend-domain-cookies = {yes|no} Description Specifies how WebSEAL validates the domain. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza. where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Options yesIf set to "yes" then domain cookies that adhere to the cookie specification are forwarded to the user. If the fully qualified host name of the originating back-end machine is the domain, then the cookie is forwarded to the user with no domain specified.noIf set to "no", then all domain cookies are forwarded to the user, regardless of their content. Usage This stanza entry is required. Default value yes validate-backend-domain-cookies = yes [junction] stanza

validate-backend-domain-cookies

Syntax

validate-backend-domain-cookies = {yes|no}

Description

Specifies how WebSEAL validates the domain.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [junction:{junction_name}] stanza.

where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

yes

If set to "yes" then domain cookies that adhere to the cookie specification are forwarded to the user. If the fully qualified host name of the originating back-end machine is the domain, then the cookie is forwarded to the user with no domain specified.

no

If set to "no", then all domain cookies are forwarded to the user, regardless of their content.

Usage

This stanza entry is required.

Default value

yes

validate-backend-domain-cookies = yes

Parent topic: [junction] stanza

worker-thread-hard-limitworker-thread-hard-limitworker-thread-hard-limit stanza entryjunction stanzaentriesworker-thread-hard-limitjunction stanzajunction stanzaworker-thread-hard-limit entrySyntax worker-thread-hard-limit = number_of_threadsDescription Integer value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions.Options number_of_threadsInteger value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions. The default value of 100 means that there is no limit. When the value of worker-thread-hard-limit is less than 100, and the limit is exceeded, WebSEAL generates an error message.Usage This stanza entry is required.Default value 100Example worker-thread-hard-limit = 100[junction] stanza

worker-thread-hard-limit

Syntax

worker-thread-hard-limit = number_of_threads

Description

Integer value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions.

Options

number_of_threads

Integer value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions. The default value of 100 means that there is no limit.

When the value of worker-thread-hard-limit is less than 100, and the limit is exceeded, WebSEAL generates an error message.

Usage

This stanza entry is required.

Default value

100

Example

worker-thread-hard-limit = 100

Parent topic: [junction] stanza

worker-thread-soft-limitworker-thread-soft-limitworker-thread-soft-limit stanza entryjunction stanzaentriesworker-thread-soft-limitjunction stanzajunction stanzaworker-thread-soft-limit entrySyntax worker-thread-soft-limit = number_of_threadsDescription Integer value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions.Options number_of_threadsInteger value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions. When the value of worker-thread-soft-limit is less than 100, and the limit is exceeded, WebSEAL generates a warning message.Usage This stanza entry is required.Default value 90Example worker-thread-soft-limit = 90[junction] stanza

worker-thread-soft-limit

Syntax

worker-thread-soft-limit = number_of_threads

Description

Integer value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions.

Options

number_of_threads

Integer value indicating the limit, expressed as a percentage, of the total worker threads that are to be used for processing requests for junctions.

When the value of worker-thread-soft-limit is less than 100, and the limit is exceeded, WebSEAL generates a warning message.

Usage

This stanza entry is required.

Default value

90

Example

worker-thread-soft-limit = 90

Parent topic: [junction] stanza

[junction:junction_name] stanza[junction:junction_name] stanzajunction:junction_name stanzastanzasjunction:junction_nameThis stanza is optional and must be manually inserted into the WebSEAL configuration file. The junction_name in the stanza name is the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. For details about the configuration entries supported in this junction specific stanza, see the description of the corresponding configuration entry in the [junction] stanza.Stanza reference

[junction:junction_name] stanza

Note: This stanza is optional and must be manually inserted into the WebSEAL configuration file. The junction_name in the stanza name is the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. For details about the configuration entries supported in this junction specific stanza, see the description of the corresponding configuration entry in the [junction] stanza.

Parent topic: Stanza reference

[ldap] stanza[ldap] stanzaldap stanzastanzasldapStanza referenceauth-timeoutUse the auth-timeout stanza entry to configure the timeout for authentication operations.auth-using-compareUse the auth-using-compare stanza entry to use a password compare operation for authentication.basic-user-pwd-policyIf basic user support is enabled, use this entry to specify whether global password policy is enabled for basic users.cache-enabledUse the cache-enabled stanza entry to control whether LDAP client-side caching is enabled.cache-group-expire-timeUse the cache-group-expire-time stanza entry to specify the timeout duration in seconds for group entries in the cache.cache-group-membershipUse the cache-group-membership stanza entry to control whether WebSEAL caches group membership information.cache-group-sizeUse the cache-group-size stanza entry to set the size of the LDAP group cache.cache-policy-expire-timeUse the cache-policy-expire-time stanza entry to specify the timeout duration for policy entries in the cache.cache-policy-sizeUse the cache-policy-size stanza entry to set the size of the LDAP policy cache.cache-return-registry-idUse the cache-return-registry-id stanza entry to control whether to cache the user identity as it is stored in the registry or cache the user identity as it is entered during authentication.cache-user-expire-timeUse the cache-user-expire-time stanza entry to specify the timeout duration in seconds for user entries in the cache.cache-user-sizeUse the cache-user-size stanza entry to set the size of the LDAP user cache.cache-use-user-cacheUse the cache-use-user-cache stanza entry to control whether WebSEAL uses information from the user cache.default-policy-override-supportUse the default-policy-override-support stanza entry to control whether the global (default) policy overrides the user level policy during LDAP searches.hostlogin-failures-persistentmax-search-sizeprefer-readwrite-serverportreplicasearch-timeoutssl-enabledssl-keyfilessl-keyfile-dnssl-porttimeoutuser-and-group-in-same-suffix

[ldap] stanza

auth-timeout
Use the auth-timeout stanza entry to configure the timeout for authentication operations.

auth-using-compare
Use the auth-using-compare stanza entry to use a password compare operation for authentication.

basic-user-pwd-policy
If basic user support is enabled, use this entry to specify whether global password policy is enabled for basic users.

cache-enabled
Use the cache-enabled stanza entry to control whether LDAP client-side caching is enabled.

cache-group-expire-time
Use the cache-group-expire-time stanza entry to specify the timeout duration in seconds for group entries in the cache.

cache-group-membership
Use the cache-group-membership stanza entry to control whether WebSEAL caches group membership information.

cache-group-size
Use the cache-group-size stanza entry to set the size of the LDAP group cache.

cache-policy-expire-time
Use the cache-policy-expire-time stanza entry to specify the timeout duration for policy entries in the cache.

cache-policy-size
Use the cache-policy-size stanza entry to set the size of the LDAP policy cache.

cache-return-registry-id
Use the cache-return-registry-id stanza entry to control whether to cache the user identity as it is stored in the registry or cache the user identity as it is entered during authentication.

cache-user-expire-time
Use the cache-user-expire-time stanza entry to specify the timeout duration in seconds for user entries in the cache.

cache-user-size
Use the cache-user-size stanza entry to set the size of the LDAP user cache.

cache-use-user-cache
Use the cache-use-user-cache stanza entry to control whether WebSEAL uses information from the user cache.

default-policy-override-support
Use the default-policy-override-support stanza entry to control whether the global (default) policy overrides the user level policy during LDAP searches.

host

login-failures-persistent

max-search-size

prefer-readwrite-server

port

replica

search-timeout

ssl-enabled

ssl-keyfile

ssl-keyfile-dn

ssl-port

timeout

user-and-group-in-same-suffix

Parent topic: Stanza reference

auth-timeoutauth-timeoutIBM Security Access Manager for Web WebSEAL auth-timeout stanza entryUse the auth-timeout stanza entry to configure the timeout for authentication operations.auth-timeout stanza entryldap stanzaentriesauth-timeoutldap stanzaldap stanzaauth-timeout entrySyntax auth-timeout = {0|number_seconds} Description Amount of time in seconds that are allowed for authentication operations before the LDAP server is considered to be down. If specified, this value overrides any value of timeout for authentication operations. Do not specify this parameter in the ldap.conf server configuration file. Options 0No timeout is allowed.number_secondsA positive integer that represents the number of seconds allowed for authentication. There is no range limitation for timeout values. Usage This stanza entry is optional. Default value 0 Example auth-timeout = 0 [ldap] stanza

auth-timeout

Use the auth-timeout stanza entry to configure the timeout for authentication operations.

Syntax

auth-timeout = {0|number_seconds}

Description

Amount of time in seconds that are allowed for authentication operations before the LDAP server is considered to be down. If specified, this value overrides any value of timeout for authentication operations.

Note: Do not specify this parameter in the ldap.conf server configuration file.

Options

0

No timeout is allowed.

number_seconds

A positive integer that represents the number of seconds allowed for authentication. There is no range limitation for timeout values.

Usage

This stanza entry is optional.

Default value

0

Example

auth-timeout = 0

Parent topic: [ldap] stanza

auth-using-compareauth-using-compareIBM Security Access Manager for Web WebSEAL auth-using-compare stanza entryUse the auth-using-compare stanza entry to use a password compare operation for authentication.auth-using-compare stanza entryldap stanzaentriesauth-using-compareldap stanzaldap stanzaauth-using-compare entrySyntax auth-using-compare = {yes|true|no|false} Description Enables or disables authentication by using password comparison. When disabled, an LDAP bind is used for authentication. For those LDAP servers that allow it, a compare operation might complete faster than a bind operation. Options yes|trueA password compare operation is used to authenticate LDAP users.no|falseA bind operation is used to authenticate LDAP users. Usage This stanza entry is optional. Default value The default value, when LDAP is enabled, is yes. Example auth-using-compare = yes [ldap] stanza

auth-using-compare

Use the auth-using-compare stanza entry to use a password compare operation for authentication.

Syntax

auth-using-compare = {yes|true|no|false}

Description

Enables or disables authentication by using password comparison. When disabled, an LDAP bind is used for authentication.

For those LDAP servers that allow it, a compare operation might complete faster than a bind operation.

Options

yes|true

A password compare operation is used to authenticate LDAP users.

no|false

A bind operation is used to authenticate LDAP users.

Usage

This stanza entry is optional.

Default value

The default value, when LDAP is enabled, is yes.

Example

auth-using-compare = yes

Parent topic: [ldap] stanza

basic-user-pwd-policyIf basic user support is enabled, use this entry to specify whether global password policy is enabled for basic users.Syntax basic-user-pwd-policy = {true|false}Description Not all global password policies are available to basic users. See the following table for which policies are supported for basic users. Global user policies for basic usersPolicyAvailable to basic usersaccount-expiry-dateYesdisable-time-intervalNomax-concurrent-web-sessionsYesmax-login-failuresNomax-password-ageNomax-password-repeated-charsYesmin-password-alphasYesmin-password-lengthYesmin-password-non-alphasYespassword-spacesYestod-accessYes This configuration entry enables or disables the global password policies for basic users.Options trueEnable global password policy for basic users.falseDisable global password policy for basic users. Usage This stanza entry is optional.Default value trueExample basic-user-pwd-policy = true[ldap] stanza

basic-user-pwd-policy

If basic user support is enabled, use this entry to specify whether global password policy is enabled for basic users.

Syntax

basic-user-pwd-policy = {true|false}

Description

Not all global password policies are available to basic users. See the following table for which policies are supported for basic users.

Table 312. Global user policies for basic users

Policy | Available to basic users
account-expiry-date | Yes
disable-time-interval | No
max-concurrent-web-sessions | Yes
max-login-failures | No
max-password-age | No
max-password-repeated-chars | Yes
min-password-alphas | Yes
min-password-length | Yes
min-password-non-alphas | Yes
password-spaces | Yes
tod-access | Yes

This configuration entry enables or disables the global password policies for basic users.

Options

true

Enable global password policy for basic users.

false

Disable global password policy for basic users.

Usage

This stanza entry is optional.

Default value

true

Example

basic-user-pwd-policy = true

Parent topic: [ldap] stanza

cache-enabledcache-enabledIBM Security Access Manager for Web WebSEAL cache-enabled stanza entryUse the cache-enabled stanza entry to control whether LDAP client-side caching is enabled.cache-enabled stanza entryldap stanzaentriescache-enabledldap stanzaldap stanzacache-enabled entrySyntax cache-enabled = {yes|true|no|false} Description Enable and disable LDAP client-side caching. Options yes|trueEnable LDAP client-side caching.no|falseDisable LDAP client-side caching. Anything other than yes|true, including a blank value, is interpreted as no|false. Usage This stanza entry is required. Default value yes Example cache-enabled = yes [ldap] stanza

cache-enabled

Use the cache-enabled stanza entry to control whether LDAP client-side caching is enabled.

Syntax

cache-enabled = {yes|true|no|false}

Description

Enable and disable LDAP client-side caching.

Options

yes|true

Enable LDAP client-side caching.

no|false

Disable LDAP client-side caching. Anything other than yes|true, including a blank value, is interpreted as no|false.

Usage

This stanza entry is required.

Default value

yes

Example

cache-enabled = yes

Parent topic: [ldap] stanza

cache-group-expire-timecache-group-expire-timeIBM Security Access Manager for Web WebSEAL cache-group-expire-time stanza entryUse the cache-group-expire-time stanza entry to specify the timeout duration in seconds for group entries in the cache.cache-group-expire-time stanza entryldap stanzaentriescache-group-expire-timeldap stanzaldap stanzacache-group-expire-time entrySyntax cache-group-expire-time = number_of_seconds Description Specifies the amount of time to elapse before a group entry in the cache is discarded. This entry is used only when cache-enabled = {yes|true}. Options number_of_secondsSpecifies the amount of time to elapse before a group entry in the cache is discarded. Usage This stanza entry is optional. Default value There is no default value, but when not set the default value used is 300 seconds. Example cache-group-expire-time = 300 [ldap] stanza

cache-group-expire-time

Use the cache-group-expire-time stanza entry to specify the timeout duration in seconds for group entries in the cache.

Syntax

cache-group-expire-time = number_of_seconds

Description

Specifies the amount of time to elapse before a group entry in the cache is discarded.

This entry is used only when cache-enabled = {yes|true}.

Options

number_of_seconds

Specifies the amount of time to elapse before a group entry in the cache is discarded.

Usage

This stanza entry is optional.

Default value

There is no default value, but when not set the default value used is 300 seconds.

Example

cache-group-expire-time = 300

Parent topic: [ldap] stanza

cache-group-membershipcache-group-membershipIBM Security Access Manager for Web WebSEAL cache-group-membership stanza entryUse the cache-group-membership stanza entry to control whether WebSEAL caches group membership information.cache-group-membership stanza entryldap stanzaentriescache-group-membershipldap stanzaldap stanzacache-group-membership entrySyntax cache-group-membership = {yes|no} Description Indicates whether group membership information should be cached. This entry is used only when cache-enabled = {yes|true} Options yesCache group membership information.noDo not cache group membership information. Usage This stanza entry is optional. Default value There is no default value, but when not set the group information is cached. Example cache-group-membership = yes [ldap] stanza

cache-group-membership

Use the cache-group-membership stanza entry to control whether WebSEAL caches group membership information.

Syntax

cache-group-membership = {yes|no}

Description

Indicates whether group membership information should be cached.

This entry is used only when cache-enabled = {yes|true}

Options

yes

Cache group membership information.

no

Do not cache group membership information.

Usage

This stanza entry is optional.

Default value

There is no default value, but when not set the group information is cached.

Example

cache-group-membership = yes

Parent topic: [ldap] stanza

cache-group-sizecache-group-sizeIBM Security Access Manager for Web WebSEAL cache-group-size stanza entryUse the cache-group-size stanza entry to set the size of the LDAP group cache.cache-group-size stanza entryldap stanzaentriescache-group-sizeldap stanzaldap stanzacache-group-size entrySyntax cache-group-size = number Description Specifies the number of entries in the LDAP group cache. This entry is used only when cache-enabled = {yes|true}. Options numberSpecifies the number of entries in the LDAP group cache. Usage This stanza entry is optional. Default value There is no default value, but when not set the default value used is 64. Example cache-group-size = 64 [ldap] stanza

cache-group-size

Use the cache-group-size stanza entry to set the size of the LDAP group cache.

Syntax

cache-group-size = number

Description

Specifies the number of entries in the LDAP group cache.

This entry is used only when cache-enabled = {yes|true}.

Options

number

Specifies the number of entries in the LDAP group cache.

Usage

This stanza entry is optional.

Default value

There is no default value, but when not set the default value used is 64.

Example

cache-group-size = 64

Parent topic: [ldap] stanza

cache-policy-expire-timecache-policy-expire-timeIBM Security Access Manager for Web WebSEAL cache-policy-expire-time stanza entryUse the cache-policy-expire-time stanza entry to specify the timeout duration for policy entries in the cache.cache-policy-expire-time stanza entryldap stanzaentriescache-policy-expire-timeldap stanzaldap stanzacache-policy-expire-time entrySyntax cache-policy-expire-time = number_of_seconds Description Specifies the amount of time to elapse before a policy entry in the cache is discarded. This entry is used only when cache-enabled = {yes|true}. Options number_of_secondsSpecifies the amount of time to elapse before a policy entry in the cache is discarded. Usage This stanza entry is optional. Default value There is no default value, but when not set the default value used is 30 seconds. Example cache-policy-expire-time = 30 [ldap] stanza

cache-policy-expire-time

Use the cache-policy-expire-time stanza entry to specify the timeout duration for policy entries in the cache.

Syntax

cache-policy-expire-time = number_of_seconds

Description

Specifies the amount of time to elapse before a policy entry in the cache is discarded.

This entry is used only when cache-enabled = {yes|true}.

Options

number_of_seconds

Specifies the amount of time to elapse before a policy entry in the cache is discarded.

Usage

This stanza entry is optional.

Default value

There is no default value, but when not set the default value used is 30 seconds.

Example

cache-policy-expire-time = 30

Parent topic: [ldap] stanza

cache-policy-sizecache-policy-sizeIBM Security Access Manager for Web WebSEAL cache-policy-size stanza entryUse the cache-policy-size stanza entry to set the size of the LDAP policy cache.cache-policy-size stanza entryldap stanzaentriescache-policy-sizeldap stanzaldap stanzacache-policy-size entrySyntax cache-policy-size = number Description Specifies the number of entries in the LDAP policy cache. This entry is used only when cache-enabled = {yes|true}. Options numberSpecifies the number of entries in the LDAP policy cache. Usage This stanza entry is optional Default value There is no default value, but when not set the default value used is 20. Example cache-policy-size = 20 [ldap] stanza

cache-policy-size

Use the cache-policy-size stanza entry to set the size of the LDAP policy cache.

Syntax

cache-policy-size = number

Description

Specifies the number of entries in the LDAP policy cache.

This entry is used only when cache-enabled = {yes|true}.

Options

number

Specifies the number of entries in the LDAP policy cache.

Usage

This stanza entry is optional

Default value

There is no default value, but when not set the default value used is 20.

Example

cache-policy-size = 20

Parent topic: [ldap] stanza

cache-return-registry-idcache-return-registry-idIBM Security Access Manager for Web WebSEAL cache-return-registry-id stanza entryUse the cache-return-registry-id stanza entry to control whether to cache the user identity as it is stored in the registry or cache the user identity as it is entered during authentication.cache-return-registry-id stanza entryldap stanzaentriescache-return-registry-idldap stanzaldap stanzacache-return-registry-id entrySyntax cache-return-registry-id = {yes|no} Description Indicates whether to cache the user identity as it is stored in the registry or cache the value as entered during authentication. Ignored if the cache is not enabled. If not set, the default is no. Options yesCache the user identity as it is stored in the registry.noCache the user identity as it was entered during authentication. Usage This stanza entry is optional Default value no Example cache-return-registry-id = no [ldap] stanza

cache-return-registry-id

Use the cache-return-registry-id stanza entry to control whether to cache the user identity as it is stored in the registry or cache the user identity as it is entered during authentication.

Syntax

cache-return-registry-id = {yes|no}

Description

Indicates whether to cache the user identity as it is stored in the registry or cache the value as entered during authentication. Ignored if the cache is not enabled. If not set, the default is no.

Options

yes

Cache the user identity as it is stored in the registry.

no

Cache the user identity as it was entered during authentication.

Usage

This stanza entry is optional

Default value

no

Example

cache-return-registry-id = no

Parent topic: [ldap] stanza

cache-user-expire-timecache-user-expire-timeIBM Security Access Manager for Web WebSEAL cache-user-expire-time stanza entryUse the cache-user-expire-time stanza entry to specify the timeout duration in seconds for user entries in the cache.cache-user-expire-time stanza entryldap stanzaentriescache-user-expire-timeldap stanzaldap stanzacache-user-expire-time entrySyntax cache-user-expire-time = number_of_seconds DescriptionSpecifies the amount of time to elapse before a user entry in the cache is discarded.This entry is used only when cache-enabled = {yes|true}. Options number_of_secondsSpecifies the amount of time to elapse before a user entry in the cache is discarded. Usage This stanza entry is optional. Default value There is no default value, but when not set the default value used is 30 seconds. Example cache-user-expire-time = 30 [ldap] stanza

cache-user-expire-time

Use the cache-user-expire-time stanza entry to specify the timeout duration in seconds for user entries in the cache.

Syntax

cache-user-expire-time = number_of_seconds

Description

Specifies the amount of time to elapse before a user entry in the cache is discarded.

This entry is used only when cache-enabled = {yes|true}.

Options

number_of_seconds

Specifies the amount of time to elapse before a user entry in the cache is discarded.

Usage

This stanza entry is optional.

Default value

There is no default value, but when not set the default value used is 30 seconds.

Example

cache-user-expire-time = 30

Parent topic: [ldap] stanza

cache-user-sizecache-user-sizeIBM Security Access Manager for Web WebSEAL cache-user-size stanza entryUse the cache-user-size stanza entry to set the size of the LDAP user cache.cache-user-size stanza entryldap stanzaentriescache-user-sizeldap stanzaldap stanzacache-user-size entrySyntax cache-user-size = number Description Specifies the number of entries in the LDAP user cache. This entry is used only when cache-enabled = {yes|true}. Options number Specifies the number of entries in the LDAP user cache. Usage This stanza entry is optional. Default value There is no default value, but when not set the default value used is 256. Example cache-user-size = 256 [ldap] stanza

cache-user-size

Use the cache-user-size stanza entry to set the size of the LDAP user cache.

Syntax

cache-user-size = number

Description

Specifies the number of entries in the LDAP user cache.

This entry is used only when cache-enabled = {yes|true}.

Options

number

Specifies the number of entries in the LDAP user cache.

Usage

This stanza entry is optional.

Default value

There is no default value, but when not set the default value used is 256.

Example

cache-user-size = 256

Parent topic: [ldap] stanza

cache-use-user-cachecache-use-user-cacheIBM Security Access Manager for Web WebSEAL cache-use-user-cache stanza entryUse the cache-use-user-cache stanza entry to control whether WebSEAL uses information from the user cache.cache-use-user-cache stanza entryldap stanzaentriescache-use-user-cacheldap stanzaldap stanzacache-use-user-cache entrySyntax cache-use-user-cache = {yes|no} Description Indicates whether to use the user cache information or not. This entry is used only when cache-enabled = {yes|true} Options yesUse the user cache information.noDo not use the user cache information. Usage This stanza entry is optional. Default value There is no default value, but when not set the user cache information is used. Example cache-use-user-cache = yes [ldap] stanza

cache-use-user-cache

Use the cache-use-user-cache stanza entry to control whether WebSEAL uses information from the user cache.

Syntax

cache-use-user-cache = {yes|no}

Description

Indicates whether to use the user cache information or not.

This entry is used only when cache-enabled = {yes|true}

Options

yes

Use the user cache information.

no

Do not use the user cache information.

Usage

This stanza entry is optional.

Default value

There is no default value, but when not set the user cache information is used.

Example

cache-use-user-cache = yes

Parent topic: [ldap] stanza

default-policy-override-supportdefault-policy-override-supportIBM Security Access Manager for Web WebSEAL default-policy-override-support stanza entryUse the default-policy-override-support stanza entry to control whether the global (default) policy overrides the user level policy during LDAP searches.default-policy-override-support stanza entryldap stanzaentriesdefault-policy-override-supportldap stanzaldap stanzadefault-policy-override-support entrySyntax default-policy-override-support = {yes|true|no|false} Description Indicates whether default policy overrides user level policy during LDAP searches. When this stanza entry is set to yes, only the default policy is checked. Options yes|trueUser policy support is disabled and only the global (default) policy is checked. This option allows the user policy to be ignored, even when it is specified. no|falseUser policy support is enabled. When a user policy is specified by the administrator, it overrides the global policy. Usage This stanza entry is optional. Default value By default, the value is not specified during WebSEAL configuration. When the value is not specified, the default behavior is enable user policy support. This is equivalent to setting this stanza entry to no. Example default-policy-override-support = yes [ldap] stanza

default-policy-override-support

Use the default-policy-override-support stanza entry to control whether the global (default) policy overrides the user level policy during LDAP searches.

Syntax

default-policy-override-support = {yes|true|no|false}

Description

Indicates whether default policy overrides user level policy during LDAP searches. When this stanza entry is set to yes, only the default policy is checked.

Options

yes|true

User policy support is disabled and only the global (default) policy is checked. This option allows the user policy to be ignored, even when it is specified.

no|false

User policy support is enabled. When a user policy is specified by the administrator, it overrides the global policy.

Usage

This stanza entry is optional.

Default value

By default, the value is not specified during WebSEAL configuration. When the value is not specified, the default behavior is enable user policy support. This is equivalent to setting this stanza entry to no.

Example

default-policy-override-support = yes

Parent topic: [ldap] stanza

hosthosthost stanza entryldap stanzaentrieshostldap stanzaldap stanzahost entrySyntax host = host_nameDescription Host name of the LDAP server.Options host_nameValid values for host_name include any valid IP host name. The host_name does not have to be a fully qualified domain name.Usage This stanza entry is required.Default value The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.Example host = diamond host = diamond.example.com[ldap] stanza

host

Syntax

host = host_name

Description

Host name of the LDAP server.

Options

host_name

Valid values for host_name include any valid IP host name. The host_name does not have to be a fully qualified domain name.

Usage

This stanza entry is required.

Default value

The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.

Example

host = diamond
host = diamond.example.com

Parent topic: [ldap] stanza

login-failures-persistentlogin-failures-persistentlogin-failures-persistent stanza entryldap stanzaentrieslogin-failures-persistentldap stanzaldap stanzalogin-failures-persistent entrySyntax login-failures-persistent = {yes|true|no|false}Description When set to "yes", login hits are tracked in the registry instead of only in the local process cache. Persistent login hit recording impacts performance but allows consistent login hit counting across multiple servers.Options yes|trueWhen set to "yes", login hits are tracked in the registry instead of only in the local process cache.no|falseWhen set to "no", login hits are not tracked in the registry instead of only in the local process cache.Usage This stanza entry is optional. Default value The value is not specified by default during WebSEAL configuration. When the value is not specified, the default value is no.Example login-failures-persistent = yes[ldap] stanza

login-failures-persistent

Syntax

login-failures-persistent = {yes|true|no|false}

Description

When set to "yes", login hits are tracked in the registry instead of only in the local process cache.

Persistent login hit recording impacts performance but allows consistent login hit counting across multiple servers.

Options

yes|true

When set to "yes", login hits are tracked in the registry instead of only in the local process cache.

no|false

When set to "no", login hits are not tracked in the registry instead of only in the local process cache.

Usage

This stanza entry is optional.

Default value

The value is not specified by default during WebSEAL configuration. When the value is not specified, the default value is no.

Example

login-failures-persistent = yes

Parent topic: [ldap] stanza

max-search-sizemax-search-sizemax-search-size stanza entryldap stanzaentriesmax-search-sizeldap stanzaldap stanzamax-search-size entrySyntax max-search-size = {0|number_entries}Description Limit for the maximum search size, specified as the number of entries, that can be returned from the LDAP server. The value for each server can be different, depending on how the server was configured.Options 0The number is unlimited; there is no limit to the maximum search size.number_entriesThe maximum number of entries for search, specified as an integer whole number. This value can be limited by the LDAP server itself.Usage This stanza entry is optional.Default value The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.Example max-search-size = 2048[ldap] stanza

max-search-size

Syntax

max-search-size = {0|number_entries}

Description

Limit for the maximum search size, specified as the number of entries, that can be returned from the LDAP server. The value for each server can be different, depending on how the server was configured.

Options

0

The number is unlimited; there is no limit to the maximum search size.

number_entries

The maximum number of entries for search, specified as an integer whole number. This value can be limited by the LDAP server itself.

Usage

This stanza entry is optional.

Default value

The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.

Example

max-search-size = 2048

Parent topic: [ldap] stanza

prefer-readwrite-serverprefer-readwrite-serverprefer-readwrite-server stanza entryldap stanzaentriesprefer-readwrite-serverldap stanzaldap stanzaprefer-readwrite-server entrySyntax prefer-readwrite-server = {yes|true|no|false}Description Allows or disallows the client to question the Read/Write LDAP server before querying any replica Read-only servers configured in the domain.Options yes|trueEnable the choice. no|falseDisable the choice. Anything other than yes|true, including a blank value, is interpreted as no|false.Usage This stanza entry is optional.Default value noExample prefer-readwrite-server = no[ldap] stanza

prefer-readwrite-server

Syntax

prefer-readwrite-server = {yes|true|no|false}

Description

Allows or disallows the client to question the Read/Write LDAP server before querying any replica Read-only servers configured in the domain.

Options

yes|true

Enable the choice.

no|false

Disable the choice. Anything other than yes|true, including a blank value, is interpreted as no|false.

Usage

This stanza entry is optional.

Default value

no

Example

prefer-readwrite-server = no

Parent topic: [ldap] stanza

portportport stanza entryldap stanzaentriesportldap stanzaldap stanzaport entrySyntax port = port_numberDescription Number of the TCP/IP port used for communicating with the LDAP server. Note that this is not for SSL communication.Options port_numberA valid port number is any positive integer that is allowed by TCP/IP and that is not currently being used by another application.Usage This stanza entry is required when LDAP is enabled.Default value The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.Example port = 389 [ldap] stanza

port

Syntax

port = port_number

Description

Number of the TCP/IP port used for communicating with the LDAP server. Note that this is not for SSL communication.

Options

port_number

A valid port number is any positive integer that is allowed by TCP/IP and that is not currently being used by another application.

Usage

This stanza entry is required when LDAP is enabled.

Default value

The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.

Example

port = 389

Parent topic: [ldap] stanza

replicareplicareplica stanza entryldap stanzaentriesreplicaldap stanzaldap stanzareplica entrySyntaxreplica = ldap-server, port, type, pref DescriptionDefinition of the LDAP user registry replicas in the domain.Security Access Manager supports a maximum of one host and nine LDAP replica servers, which are listed in the ldap.conf file. If more than nine LDAP replica entries are listed, the Security Access Manager servers cannot start. Optionsldap-serverThe network name of the server.portThe port number for the LDAP server. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.typeOne of read-only or read/write.prefA number from 1 to 10 (10 is the highest preference). UsageThis stanza entry is optional. Default valueDefault value is that no replicas are specified.Any value is always taken during WebSEAL initialization from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server. ExampleExample of one replica specified and two replicas commented out:replica = rep1,390,readonly,1 #replica = rep2,391,readwrite,2 #replica = rep3,392,readwrite,3 [ldap] stanza

replica

Syntax

replica = ldap-server, port, type, pref

Description

Definition of the LDAP user registry replicas in the domain.

Security Access Manager supports a maximum of one host and nine LDAP replica servers, which are listed in the ldap.conf file. If more than nine LDAP replica entries are listed, the Security Access Manager servers cannot start.

Options

ldap-server

The network name of the server.

port

The port number for the LDAP server. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.

type

One of read-only or read/write.

pref

A number from 1 to 10 (10 is the highest preference).

Usage

This stanza entry is optional.

Default value

Default value is that no replicas are specified.

Any value is always taken during WebSEAL initialization from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.

Example

Example of one replica specified and two replicas commented out:

replica = rep1,390,readonly,1
#replica = rep2,391,readwrite,2
#replica = rep3,392,readwrite,3

Parent topic: [ldap] stanza

search-timeoutsearch-timeoutsearch-timeout stanza entryldap stanzaentriessearch-timeoutldap stanzaldap stanzasearch-timeout entrySyntax search-timeout = {0|number_seconds}Description Amount of time (in seconds) that will be allowed for search operations before the LDAP server is considered to be down. If specified, this value overrides any value of timeout for search operations. Do not specify this parameter in the ldap.conf server configuration file.Options 0No timeout is allowed.number_secondsThe specified number of seconds allowed for search operations, specified as an integer positive whole number. There is no range limitation for timeout values.Usage This stanza entry is optional.Default value 0Example search-timeout = 0[ldap] stanza

search-timeout

Syntax

search-timeout = {0|number_seconds}

Description

Amount of time (in seconds) that will be allowed for search operations before the LDAP server is considered to be down. If specified, this value overrides any value of timeout for search operations.

Note: Do not specify this parameter in the ldap.conf server configuration file.

Options

0

No timeout is allowed.

number_seconds

The specified number of seconds allowed for search operations, specified as an integer positive whole number. There is no range limitation for timeout values.

Usage

This stanza entry is optional.

Default value

0

Example

search-timeout = 0

Parent topic: [ldap] stanza

ssl-enabledssl-enabledssl-enabled stanza entryldap stanzaentriesssl-enabledldap stanzaldap stanzassl-enabled entrySyntax ssl-enabled = {yes|true|no|false}Description Enables or disables SSL communication between WebSEAL and the LDAP server.Options yes|trueEnable SSL communication.no|falseDisable SSL communication.Usage This stanza entry is optional.Default value SSL communication is disabled by default. During WebSEAL server configuration, the WebSEAL administrator can choose to enable it.Example ssl-enabled = yes[ldap] stanza

ssl-enabled

Syntax

ssl-enabled = {yes|true|no|false}

Description

Enables or disables SSL communication between WebSEAL and the LDAP server.

Options

yes|true

Enable SSL communication.

no|false

Disable SSL communication.

Usage

This stanza entry is optional.

Default value

SSL communication is disabled by default. During WebSEAL server configuration, the WebSEAL administrator can choose to enable it.

Example

ssl-enabled = yes

Parent topic: [ldap] stanza

ssl-keyfilessl-keyfilessl-keyfile stanza entryldap stanzaentriesssl-keyfileldap stanzaldap stanzassl-keyfile entrySyntax ssl-keyfile = file_name Description SSL key file name. The SSL key file handles certificates that are used in LDAP communication. Options file_nameThe WebSEAL administrator specifies this file name during WebSEAL configuration. The file name can be any arbitrary choice, but the extension is usually .kdb. Usage This stanza entry is required when SSL communication is enabled, as specified in the ssl-enabled stanza entry. Default value None. Example Example: ssl-keyfile = webseald.kdb [ldap] stanza

ssl-keyfile

Syntax

ssl-keyfile = file_name

Description

SSL key file name. The SSL key file handles certificates that are used in LDAP communication.

Options

file_name

The WebSEAL administrator specifies this file name during WebSEAL configuration. The file name can be any arbitrary choice, but the extension is usually .kdb.

Usage

This stanza entry is required when SSL communication is enabled, as specified in the ssl-enabled stanza entry.

Default value

None.

Example

Example:

ssl-keyfile = webseald.kdb

Parent topic: [ldap] stanza

ssl-keyfile-dnssl-keyfile-dnssl-keyfile-dn stanza entryldap stanzaentriesssl-keyfile-dnldap stanzaldap stanzassl-keyfile-dn entrySyntax ssl-keyfile-dn = key_labelDescription String that specifies the key label of the client personal certificate within the SSL key file. This key label is used to identify the client certificate that is presented to the LDAP server.Options key_labelString that specifies the key label of the client personal certificate within the SSL key file. Usage This stanza entry is optional. A label is not required when one of the certificates in the keyfile has been identified as the default certificate. The decision whether to identify a certificate as the default was made previously by the LDAP administrator when configuring the LDAP server. The WebSEAL configuration utility prompts the WebSEAL administrator to supply a label. When the administrator knows that the certificate contained in the keyfile is the default certificate, the administrator does not have to specify a label.Default value None.Example ssl-keyfile-dn = "PD_LDAP"[ldap] stanza

ssl-keyfile-dn

Syntax

ssl-keyfile-dn = key_label

Description

String that specifies the key label of the client personal certificate within the SSL key file. This key label is used to identify the client certificate that is presented to the LDAP server.

Options

key_label

String that specifies the key label of the client personal certificate within the SSL key file.

Usage

This stanza entry is optional. A label is not required when one of the certificates in the keyfile has been identified as the default certificate. The decision whether to identify a certificate as the default was made previously by the LDAP administrator when configuring the LDAP server. The WebSEAL configuration utility prompts the WebSEAL administrator to supply a label. When the administrator knows that the certificate contained in the keyfile is the default certificate, the administrator does not have to specify a label.

Default value

None.

Example

ssl-keyfile-dn = "PD_LDAP"

Parent topic: [ldap] stanza

ssl-portssl-portssl-port stanza entryldap stanzaentriesssl-portldap stanzaldap stanzassl-port entrySyntax ssl-port = port_numberDescription SSL IP port that is used to connect to the LDAP server. Note that this is for SSL communication.Options port_numberA valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.Usage This stanza entry is required only when LDAP is enabled and the LDAP server is configured to perform client authentication (ssl-enabled = yes).Default value The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.Example ssl-port = 636[ldap] stanza

ssl-port

Syntax

ssl-port = port_number

Description

SSL IP port that is used to connect to the LDAP server. Note that this is for SSL communication.

Options

port_number

A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.

Usage

This stanza entry is required only when LDAP is enabled and the LDAP server is configured to perform client authentication (ssl-enabled = yes).

Default value

The default value is always taken (during WebSEAL initialization) from the corresponding parameter in the [ldap] stanza of the ldap.conf configuration file for the LDAP server.

Example

ssl-port = 636

Parent topic: [ldap] stanza

timeouttimeouttimeout stanza entryldap stanzaentriestimeoutldap stanzaldap stanzatimeout entrySyntax timeout = {0|number_seconds}Description Amount of time (in seconds) that is allowed for authentication or search operations before the LDAP server is considered to not available. If specified, a value for the stanza entries authn-timeout or search-timeout overrides the value of this stanza entry. Do not specify this parameter in the ldap.conf server configuration file.Options 0No timeout is allowed.number_secondsThe number of seconds allowed for authentication or search, specified as a positive integer whole number. There is no range limitation for timeout values.Usage This stanza entry is optional.Default value 0Example timeout = 0[ldap] stanza

timeout

Syntax

timeout = {0|number_seconds}

Description

Amount of time (in seconds) that is allowed for authentication or search operations before the LDAP server is considered to not available. If specified, a value for the stanza entries authn-timeout or search-timeout overrides the value of this stanza entry.

Note: Do not specify this parameter in the ldap.conf server configuration file.

Options

0

No timeout is allowed.

number_seconds

The number of seconds allowed for authentication or search, specified as a positive integer whole number. There is no range limitation for timeout values.

Usage

This stanza entry is optional.

Default value

0

Example

timeout = 0

Parent topic: [ldap] stanza

user-and-group-in-same-suffixuser-and-group-in-same-suffixuser-and-group-in-same-suffix stanza entryldap stanzaentriesuser-and-group-in-same-suffixldap stanzaldap stanzauser-and-group-in-same-suffix entrySyntax user-and-group-in-same-suffix = {yes|true|no|false}Description Indicates whether the groups, in which a user is a member, are defined in the same LDAP suffix as the user definition. When a user is authenticated, the groups in which the user is a member must be determined in order to build a credential. Normally, all LDAP suffixes are searched to locate the groups of which the user is a member.Options yes|trueThe groups are assumed to be defined in same LDAP suffix as the user definition. Only that suffix is searched for group membership. This behavior can improve the performance of group lookup because only a single suffix is searched for group membership. This option should only be specified if group definitions are restricted to the same suffix as the user definition.no|falseThe groups might be defined in any LDAP suffix.Usage This stanza entry is optional. Default value The value is not specified by default during WebSEAL configuration. When the value is not specified, the default value is no.Example user-and-group-in-same-suffix = yes[ldap] stanza

user-and-group-in-same-suffix

Syntax

user-and-group-in-same-suffix = {yes|true|no|false}

Description

Indicates whether the groups, in which a user is a member, are defined in the same LDAP suffix as the user definition.

When a user is authenticated, the groups in which the user is a member must be determined in order to build a credential. Normally, all LDAP suffixes are searched to locate the groups of which the user is a member.

Options

yes|true

The groups are assumed to be defined in same LDAP suffix as the user definition. Only that suffix is searched for group membership. This behavior can improve the performance of group lookup because only a single suffix is searched for group membership. This option should only be specified if group definitions are restricted to the same suffix as the user definition.

no|false

The groups might be defined in any LDAP suffix.

Usage

This stanza entry is optional.

Default value

The value is not specified by default during WebSEAL configuration. When the value is not specified, the default value is no.

Example

user-and-group-in-same-suffix = yes

Parent topic: [ldap] stanza

[local-response-macros] stanza[local-response-macros] stanzalocal-response-macros stanzastanzaslocal-response-macrosStanza referencemacro

[local-response-macros] stanza

macro

Parent topic: Stanza reference

macromacromacro stanza entrylocal-response-macros stanzaentriesmacrolocal-response-macros stanzalocal-response-macros stanzamacro entrySyntax macro = macro[:name] Description URL-encoded macros to include in the query string for all redirected management page requests. WebSEAL provides a default set of macros. By default, WebSEAL uses the macro values as arguments in the generated query string. Alternatively, you can customize the name of the arguments used in the query string by adding a colon followed by a name value. Options macroURL-encoded macro.nameWebSEAL uses this custom name as an argument in the response URI. If you do not provide a value for this custom name then WebSEAL defaults to using the macro value as an argument in the response URI. For the HTTPHDR macro, the default value is HTTPHDR_<name>, where <name> is the name of the HTTP header defined in the macro. For the CREDATTR macro, the default value is CREDATTR_<name>, where <name> is the name of the attribute defined in the macro. Usage This stanza entry is optional. Default value None. Example The following entry causes WebSEAL to use the default value USERNAME as an argument in the query string.macro = USERNAMEThe following entry causes WebSEAL to use the custom value myUserName as an argument in the query string.macro = USERNAME:myUserName[local-response-macros] stanza

macro

Syntax

macro = macro[:name]

Description

URL-encoded macros to include in the query string for all redirected management page requests. WebSEAL provides a default set of macros.

By default, WebSEAL uses the macro values as arguments in the generated query string. Alternatively, you can customize the name of the arguments used in the query string by adding a colon followed by a name value.

Options

macro

URL-encoded macro.

name

WebSEAL uses this custom name as an argument in the response URI. If you do not provide a value for this custom name then WebSEAL defaults to using the macro value as an argument in the response URI.

Note: For the HTTPHDR macro, the default value is HTTPHDR_<name>, where <name> is the name of the HTTP header defined in the macro. For the CREDATTR macro, the default value is CREDATTR_<name>, where <name> is the name of the attribute defined in the macro.

Usage

This stanza entry is optional.

Default value

None.

Example

The following entry causes WebSEAL to use the default value USERNAME as an argument in the query string.

macro = USERNAME

The following entry causes WebSEAL to use the custom value myUserName as an argument in the query string.

macro = USERNAME:myUserName

Parent topic: [local-response-macros] stanza

[local-response-redirect] stanza[local-response-redirect] stanzalocal-response-redirect stanzastanzaslocal-response-redirectStanza referencelocal-response-redirect-uriUse one or more of this entry to define the URIs to which management page requests are redirected.

[local-response-redirect] stanza

local-response-redirect-uri
Use one or more of this entry to define the URIs to which management page requests are redirected.

Parent topic: Stanza reference

local-response-redirect-urilocal-response-redirect-uriUse one or more of this entry to define the URIs to which management page requests are redirected. local-response-redirect-uri stanza entrylocal-response-redirect stanzaentrieslocal-response-redirect-urilocal-response-redirect stanzalocal-response-redirect stanzalocal-response-redirect-uri entrySyntax local-response-redirect-uri = URIDescription All requests for management pages are redirected to these URIs with a query string that indicates the requested operation, along with any macros (as configured in the [local-response-macros] stanza). You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [local-response-redirect:{junction_name}] stanza, where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.Options URIURI to which management page requests are redirected. The URI can be absolute or server-relative. Use an absolute URI only if the destination server is not accessed through WebSEAL.Valid formats are as follows:http[s]://<server>/<path> /<path>To define the URI for specific operations, prefix the URI in the entry with the operation name in the form [<operation>]. The [ and ] characters are required. Valid values for <operation> are as follows:logout passwd passwd_warn passwd_warn_failure acct_inactivated acct_locked passwd_exp passwd_rep_success passwd_rep_failure help login login_success token_login cert_login next_token switch_user failed_cert cert_stepup_http stepup error too_many_sessions tempsessionIf an entry that does not specify an operation is present, then any operation without a specific entry uses it. If an entry that does not specify an operation is not present, then any operation without a specific entry does not use local response redirection and uses regular WebSEAL behavior instead.Usage This stanza entry is optional.Default value None.Example Example of a server-relative URI: local-response-redirect-uri = /jct/page.html Example of an absolute URI: local-response-redirect-uri = http://www.example.com/ Example of an operation-specific URI:local-response-redirect-uri = [login] /jct/cgi-bin/eai[local-response-redirect] stanza

local-response-redirect-uri

Use one or more of this entry to define the URIs to which management page requests are redirected.

Syntax

local-response-redirect-uri = URI

Description

All requests for management pages are redirected to these URIs with a query string that indicates the requested operation, along with any macros (as configured in the [local-response-macros] stanza).

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [local-response-redirect:{junction_name}] stanza, where {junction_name} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

URI

URI to which management page requests are redirected.

The URI can be absolute or server-relative. Use an absolute URI only if the destination server is not accessed through WebSEAL.

Valid formats are as follows:

http[s]://<server>/<path>
/<path>

To define the URI for specific operations, prefix the URI in the entry with the operation name in the form [<operation>]. The "[" and "]" characters are required. Valid values for <operation> are as follows:

logout
passwd
passwd_warn
passwd_warn_failure
acct_inactivated
acct_locked
passwd_exp
passwd_rep_success
passwd_rep_failure
help
login
login_success
token_login
cert_login
next_token
switch_user
failed_cert
cert_stepup_http
stepup
error
too_many_sessions
tempsession

If an entry that does not specify an operation is present, then any operation without a specific entry uses it. If an entry that does not specify an operation is not present, then any operation without a specific entry does not use local response redirection and uses regular WebSEAL behavior instead.

Usage

This stanza entry is optional.

Default value

None.

Example

Example of a server-relative URI:

local-response-redirect-uri = /jct/page.html

Example of an absolute URI:

local-response-redirect-uri = http://www.example.com/

Example of an operation-specific URI:

local-response-redirect-uri = [login] /jct/cgi-bin/eai

Parent topic: [local-response-redirect] stanza

[logging] stanza[logging] stanzalogging stanzastanzasloggingStanza referenceabsolute-uri-in-request-logUse the absolute-uri-in-request-log stanza entry to log the absolute URI in the request log, combined log, and HTTP audit records.agentsUse the agents stanza entry to enable or disable the agents log.audit-mime-typesUse the audit-mime-types stanza entry to configure WebSEAL to use the mime type to determine whether to generate an audit event for a particular HTTP request.audit-response-codesUse the audit-response-codes stanza entry to control whether WebSEAL generates an audit event that is based on the response code of the HTTP response.flush-timeUse the flush-time stanza entry to specify the frequency at which WebSEAL flushes log buffers.gmt-timehost-header-in-request-loglog-invalid-requestsmax-sizereferersrequestsrequest-log-formatserver-log-cfg

[logging] stanza

absolute-uri-in-request-log
Use the absolute-uri-in-request-log stanza entry to log the absolute URI in the request log, combined log, and HTTP audit records.

agents
Use the agents stanza entry to enable or disable the agents log.

audit-mime-types
Use the audit-mime-types stanza entry to configure WebSEAL to use the mime type to determine whether to generate an audit event for a particular HTTP request.

audit-response-codes
Use the audit-response-codes stanza entry to control whether WebSEAL generates an audit event that is based on the response code of the HTTP response.

flush-time
Use the flush-time stanza entry to specify the frequency at which WebSEAL flushes log buffers.

gmt-time

host-header-in-request-log

log-invalid-requests

max-size

referers

requests

request-log-format

server-log-cfg

Parent topic: Stanza reference

absolute-uri-in-request-logabsolute-uri-in-request-logIBM Security Access Manager for Web WebSEAL absolute-uri-in-request-log stanza entryUse the absolute-uri-in-request-log stanza entry to log the absolute URI in the request log, combined log, and HTTP audit records.absolute-uri-in-request-log stanza entrylogging stanzaentriesabsolute-uri-in-request-loglogging stanzalogging stanzaabsolute-uri-in-request-log entrySyntax absolute-uri-in-request-log = {yes|no} Description Log the absolute URI in the request log, combined log, and HTTP audit records. Adds protocol and host to the path. Options yesLog the absolute URI.noDo not log the absolute URI. Usage This stanza entry is required. Default value no Example absolute-uri-in-request-log = no [logging] stanza

absolute-uri-in-request-log

Use the absolute-uri-in-request-log stanza entry to log the absolute URI in the request log, combined log, and HTTP audit records.

Syntax

absolute-uri-in-request-log = {yes|no}

Description

Log the absolute URI in the request log, combined log, and HTTP audit records. Adds protocol and host to the path.

Options

yes

Log the absolute URI.

no

Do not log the absolute URI.

Usage

This stanza entry is required.

Default value

no

Example

absolute-uri-in-request-log = no

Parent topic: [logging] stanza

agentsagentsIBM Security Access Manager for Web WebSEAL agents stanza entryUse the agents stanza entry to enable or disable the agents log.agents stanza entrylogging stanzaentriesagentslogging stanzalogging stanzaagents entrySyntax agents = {yes|no} Description Enables or disables the agents log. This log records the contents of the User_Agent: header of each HTTP request. Options yesThe value yes enables the agents log.noThe value no disables the agents log. Usage This stanza entry is required. Default value yes Example agents = yes [logging] stanza

agents

Use the agents stanza entry to enable or disable the agents log.

Syntax

agents = {yes|no}

Description

Enables or disables the agents log. This log records the contents of the User_Agent: header of each HTTP request.

Options

yes

The value yes enables the agents log.

no

The value no disables the agents log.

Usage

This stanza entry is required.

Default value

yes

Example

agents = yes

Parent topic: [logging] stanza

audit-mime-typesaudit-mime-typesIBM Security Access Manager for Web WebSEAL audit-mime-types stanza entryUse the audit-mime-types stanza entry to configure WebSEAL to use the mime type to determine whether to generate an audit event for a particular HTTP request.audit-mime-types stanza entrylogging stanzaentriesaudit-mime-typeslogging stanzalogging stanzaaudit-mime-types entrySyntax mime-pattern = {yes|no} Description WebSEAL determines whether the content-type of the HTTP response matches any of the configured MIME patterns. If the HTTP response does match one of the MIME patterns, WebSEAL uses this entry to determine whether to generate an audit event. More specific MIME patterns take precedence over less specific MIME patterns. For example, if image/* = yes (general), but image/jpeg = no (more specific), then an HTTP response with an image MIME-type other than JPEG generates an audit event; a response with a JPEG MIME-type does not generate an audit event.If an HTTP response does not match any of the MIME patterns that are listed in this stanza, WebSEAL does not generate an audit event. Options yesWebSEAL generates an audit event for a response that contains the corresponding content MIME-type.noWebSEAL does not generate an audit event for a response that contains the corresponding content MIME-type. Usage This stanza entry is optional. Default value None. Example image/jpeg = no image/* = no */* = no [logging] stanza

audit-mime-types

Use the audit-mime-types stanza entry to configure WebSEAL to use the mime type to determine whether to generate an audit event for a particular HTTP request.

Syntax

mime-pattern = {yes|no}

Description

WebSEAL determines whether the content-type of the HTTP response matches any of the configured MIME patterns. If the HTTP response does match one of the MIME patterns, WebSEAL uses this entry to determine whether to generate an audit event.

Note:

More specific MIME patterns take precedence over less specific MIME patterns. For example, if image/* = yes (general), but image/jpeg = no (more specific), then an HTTP response with an image MIME-type other than JPEG generates an audit event; a response with a JPEG MIME-type does not generate an audit event.

If an HTTP response does not match any of the MIME patterns that are listed in this stanza, WebSEAL does not generate an audit event.

Options

yes

WebSEAL generates an audit event for a response that contains the corresponding content MIME-type.

no

WebSEAL does not generate an audit event for a response that contains the corresponding content MIME-type.

Usage

This stanza entry is optional.

Default value

None.

Example

image/jpeg = no
image/* = no
*/* = no

Parent topic: [logging] stanza

audit-response-codesaudit-response-codesaudit-response-codesUse the audit-response-codes stanza entry to control whether WebSEAL generates an audit event that is based on the response code of the HTTP response.audit-response-codes stanza entrylogging stanzaentriesaudit-response-codeslogging stanzalogging stanzaaudit-response-codes entrySyntax code = {yes|no} Description Determines whether WebSEAL generates an audit event for an HTTP request that is based on the response code of the HTTP response. Options yesWebSEAL generates an audit event for an HTTP response that matches the corresponding response code.noWebSEAL does not generate an audit event for an HTTP response that matches the corresponding response code. Usage This stanza entry is optional. Default value None. Example 200 = no 304 = no 401 = yes [logging] stanza

audit-response-codes

Use the audit-response-codes stanza entry to control whether WebSEAL generates an audit event that is based on the response code of the HTTP response.

Syntax

code = {yes|no}

Description

Determines whether WebSEAL generates an audit event for an HTTP request that is based on the response code of the HTTP response.

Options

yes

WebSEAL generates an audit event for an HTTP response that matches the corresponding response code.

no

WebSEAL does not generate an audit event for an HTTP response that matches the corresponding response code.

Usage

This stanza entry is optional.

Default value

None.

Example

200 = no
304 = no
401 = yes

Parent topic: [logging] stanza

flush-timeflush-timeIBM Security Access Manager for Web WebSEAL flush-time stanza entryUse the flush-time stanza entry to specify the frequency at which WebSEAL flushes log buffers.flush-time stanza entrylogging stanzaentriesflush-timelogging stanzalogging stanzaflush-time entrySyntax flush-time = number_of_seconds Description Integer value indicating the frequency, in seconds, to force a flush of log buffers. Options number_of_secondsInteger value indicating the frequency, in seconds, to force a flush of log buffers. The minimum value is 1 second. The maximum value is 600 seconds. Usage This stanza entry is optional. Default value 20 Example flush-time = 20 [logging] stanza

flush-time

Use the flush-time stanza entry to specify the frequency at which WebSEAL flushes log buffers.

Syntax

flush-time = number_of_seconds

Description

Integer value indicating the frequency, in seconds, to force a flush of log buffers.

Options

number_of_seconds

Integer value indicating the frequency, in seconds, to force a flush of log buffers. The minimum value is 1 second. The maximum value is 600 seconds.

Usage

This stanza entry is optional.

Default value

20

Example

flush-time = 20

Parent topic: [logging] stanza

gmt-timegmt-timegmt-time stanza entrylogging stanzaentriesgmt-timelogging stanzalogging stanzagmt-time entrySyntax gmt-time = {yes|no}Description Enables or disables logging requests using Greenwich Mean Time (GMT) instead of the local timezone.Options yesA value of yes means to use GMTno A value of no means to use the local timezone.Usage This stanza entry is required.Default value noExample gmt-time = no[logging] stanza

gmt-time

Syntax

gmt-time = {yes|no}

Description

Enables or disables logging requests using Greenwich Mean Time (GMT) instead of the local timezone.

Options

yes

A value of yes means to use GMT

no

A value of no means to use the local timezone.

Usage

This stanza entry is required.

Default value

no

Example

gmt-time = no

Parent topic: [logging] stanza

host-header-in-request-loghost-header-in-request-loghost-header-in-request-log stanza entrylogging stanzaentrieshost-header-in-request-loglogging stanzalogging stanzahost-header-in-request-log entrySyntax host-header-in-request-log = {yes|no}Description Log the Host header at the front of each line in the request log and the combined log.Options yesLog the Host header.noDo not log the Host header.Usage This stanza entry is required.Default value noExample host-header-in-request-log = no[logging] stanza

host-header-in-request-log

Syntax

host-header-in-request-log = {yes|no}

Description

Log the Host header at the front of each line in the request log and the combined log.

Options

yes

Log the Host header.

no

Do not log the Host header.

Usage

This stanza entry is required.

Default value

no

Example

host-header-in-request-log = no

Parent topic: [logging] stanza

log-invalid-requestslog-invalid-requestslog-invalid-requests stanza entrylogging stanzaentrieslog-invalid-requestslogging stanzalogging stanzalog-invalid-requests entrySyntax log-invalid-requests = {yes|no}Description Specifies whether or not WebSEAL logs all requests that are malformed or for some other reason is not processed to completion.Options yesWebSEAL logs every request, even if a request is malformed or for some other reason is not processed to completion.noWebSEAL logs most requests. In some cases, requests that are malformed or for some other reason are not processed to completion will not be logged. This option exists for compatibility with versions of WebSEAL prior to version 6.0.Usage This stanza entry is required.Default value yesExample log-invalid-requests = yes[logging] stanza

log-invalid-requests

Syntax

log-invalid-requests = {yes|no}

Description

Specifies whether or not WebSEAL logs all requests that are malformed or for some other reason is not processed to completion.

Options

yes

WebSEAL logs every request, even if a request is malformed or for some other reason is not processed to completion.

no

WebSEAL logs most requests. In some cases, requests that are malformed or for some other reason are not processed to completion will not be logged. This option exists for compatibility with versions of WebSEAL prior to version 6.0.

Usage

This stanza entry is required.

Default value

yes

Example

log-invalid-requests = yes

Parent topic: [logging] stanza

max-sizemax-sizemax-size stanza entrylogging stanzaentriesmax-sizelogging stanzalogging stanzamax-size entrySyntax max-size = number_of_bytes Description Integer value indicating the size limit of the log files. This value applies to the request, referer, and agent logs. The size limit is also referred to as the rollover threshold. When the log file reaches this threshold, the original log file is renamed and a new log file with the original name is created. Options number_of_bytes When the value is zero (0), no rollover log file is created. When the value is a negative integer, the logs are rolled over daily, regardless of the size. When the value is a positive integer, the value indicates the maximum size, in bytes, of the log file before the rollover occurs. The allowable range is from 1 byte to 2 gigabytes. Usage This stanza entry is required. Default value 2000000 Example max-size = 2000000 [logging] stanza

max-size

Syntax

max-size = number_of_bytes

Description

Integer value indicating the size limit of the log files. This value applies to the request, referer, and agent logs. The size limit is also referred to as the rollover threshold. When the log file reaches this threshold, the original log file is renamed and a new log file with the original name is created.

Options

number_of_bytes

When the value is zero (0), no rollover log file is created.

When the value is a negative integer, the logs are rolled over daily, regardless of the size.

When the value is a positive integer, the value indicates the maximum size, in bytes, of the log file before the rollover occurs. The allowable range is from 1 byte to 2 gigabytes.

Usage

This stanza entry is required.

Default value

2000000

Example

max-size = 2000000

Parent topic: [logging] stanza

referersreferersreferers stanza entrylogging stanzaentriesrefererslogging stanzalogging stanzareferers entrySyntax referers = {yes|no}Description Enables or disables the referers log. This log records the Referer: header of each HTTP request. Options yesThe value yes enables referers logging. noThe value no disables referers logging.Usage This stanza entry is required.Default value yesExample referers = yes[logging] stanza

referers

Syntax

referers = {yes|no}

Description

Enables or disables the referers log. This log records the Referer: header of each HTTP request.

Options

yes

The value yes enables referers logging.

no

The value no disables referers logging.

Usage

This stanza entry is required.

Default value

yes

Example

referers = yes

Parent topic: [logging] stanza

requestsrequestsrequests stanza entrylogging stanzaentriesrequestslogging stanzalogging stanzarequests entrySyntax requests = {yes|no}Description Enables or disables the requests log. This log records standard logging of HTTP requests.Options yesThe value yes enables requests logging. noThe value no disables requests logging.Usage This stanza entry is required.Default value yesExample requests = yes[logging] stanza

requests

Syntax

requests = {yes|no}

Description

Enables or disables the requests log. This log records standard logging of HTTP requests.

Options

yes

The value yes enables requests logging.

no

The value no disables requests logging.

Usage

This stanza entry is required.

Default value

yes

Example

requests = yes

Parent topic: [logging] stanza

request-log-formatrequest-log-formatrequest-log-format stanza entrylogging stanzaentriesrequest-log-formatlogging stanzalogging stanzarequest-log-format entrySyntax request-log-format = directives Description Contains the format in which a customized request log should be created. Options The following directives can be used: %aRemote IP Address.%ALocal IP Address.%bBytes in the reply excluding HTTP headers in CLF format: '-' instead of 0 when no bytes are returned.%BBytes in the reply excluding HTTP headers.%{Attribute}CAttribute from the Security Access Manager credential named "Attribute".%{cookie-name}eContents of the cookie "cookiename" in the request.%{cookie-name}EContents of the cookie "cookiename" in the response.%dTransaction identifier, or session sequence number.%FTime taken to serve the request in microseconds.%hRemote host.%HRequest protocol.%{header-name}iContents of the Header header-name in the request.%jThe name of the junction in the request.%lRemote logname.%mRequest method (that is, GET, POST, HEAD).%{header-name}oContents of the Header header-name in the reply.%pPort of the WebSEAL server the request was served on.%qThe query string (prepended with '?' or empty).%QLogs raw query strings that the user must decode manually.%rFirst line of the request.%RFirst line of the request including HTTP://HOSTNAME.%sStatus.%tTime and date in CLF format.%{format}tThe time and date in the given format.%TTime taken to serve the request in seconds.%uRemote user.%UThe URL requested.%vCanonical ServerName of the server serving the request.%zThe path portion of the URL in decoded form. %ZThe path portion of the URL in raw form. Usage The request-log-format string CANNOT contain the # character. Default value The default of this parameter is equivalent to the normal default log output. It is commented out by default. Example Example on UNIX or Linux: request-log-format = %h %l %u %t "%r" %s %b [logging] stanza

request-log-format

Syntax

request-log-format = directives

Description

Contains the format in which a customized request log should be created.

Options

The following directives can be used:

%a

Remote IP Address.

%A

Local IP Address.

%b

Bytes in the reply excluding HTTP headers in CLF format: '-' instead of 0 when no bytes are returned.

%B

Bytes in the reply excluding HTTP headers.

%{Attribute}C

Attribute from the Security Access Manager credential named "Attribute".

%{cookie-name}e

Contents of the cookie "cookiename" in the request.

%{cookie-name}E

Contents of the cookie "cookiename" in the response.

%d

Transaction identifier, or session sequence number.

%F

Time taken to serve the request in microseconds.

%h

Remote host.

%H

Request protocol.

%{header-name}i

Contents of the Header header-name in the request.

%j

The name of the junction in the request.

%l

Remote logname.

%m

Request method (that is, GET, POST, HEAD).

%{header-name}o

Contents of the Header header-name in the reply.

%p

Port of the WebSEAL server the request was served on.

%q

The query string (prepended with '?' or empty).

%Q

Logs raw query strings that the user must decode manually.

%r

First line of the request.

%R

First line of the request including HTTP://HOSTNAME.

%s

Status.

%t

Time and date in CLF format.

%{format}t

The time and date in the given format.

%T

Time taken to serve the request in seconds.

%u

Remote user.

%U

The URL requested.

%v

Canonical ServerName of the server serving the request.

%z

The path portion of the URL in decoded form.

%Z

The path portion of the URL in raw form.

Usage

The request-log-format string CANNOT contain the # character.

Default value

The default of this parameter is equivalent to the normal default log output. It is commented out by default.

Example

Example on UNIX or Linux:

request-log-format = %h %l %u %t "%r" %s %b

Parent topic: [logging] stanza

server-log-cfgserver-log-cfgserver-log-cfg stanza entrylogging stanzaentriesserver-log-cfglogging stanzalogging stanzaserver-log-cfg entrySyntax server-log-cfg = agent [parameter=value],[parameter=value]...Description Configures the server for logging. You can use the available parameters to configure the logging agents. Options agentSpecifies the logging agent. The agent controls the logging destination for server events. Valid agents include:stdoutstderrfileremotersyslogIf you use the remote agent to send audit events to a remote authorization server, ensure that the destination server is configured to process the received events. In particular, the logcfg configuration entry in the aznapi-configuration stanza must be set on the remote authorization server. You must use the following format for the category value in this logcfg entry: remote.webseal.hostname.websealdwherehostnameThe name of the appliance that originated the event. For example, the following entry configures the remote authorization server to accept logging events from the iswga.au.ibm.com server, and send these events to the event.log file: logcfg = remote.webseal.iswga.au.ibm.com.webseald:file path=/var/ PolicyDirector/log/event.logThe remote authorization server discards any events that originate from a server for which there is no matching logcfg rule.parameterThe different agents support the following configuration parameters:Logging agent configuration parametersParameterSupporting agentsbuffer_sizeremotecompressremotednremoteerror_retryremote, rsyslogflush_intervalallhi_wateralllog_idfile, rsyslogmax_event_lenrsyslogmax_rollover_filesfilemodefilepathallportremote, rsyslogqueue_sizeallrebind_retryremote, rsyslogrollover_sizefileserverremote, rsyslogssl_keyfilersyslogssl_labelrsyslogssl_stashfilersyslogFor a complete description of the available logging agents and the supported configuration parameters, see the Security Access Manager: Auditing Guide. Usage This stanza entry is required. Default value None. Example To log server events in a file called msg__webseald.log: server-log-cfg = file path=msg__webseald.logTo send server events to a remote syslog server: server-log-cfg = rsyslog server=timelord,port=514,log_id=webseal-instance [logging] stanza

server-log-cfg

Syntax

server-log-cfg = agent [parameter=value],[parameter=value]...

Description

Configures the server for logging. You can use the available parameters to configure the logging agents.

Options

agent

Specifies the logging agent. The agent controls the logging destination for server events. Valid agents include:

stdout

stderr

file

remote

rsyslog

Note: If you use the remote agent to send audit events to a remote authorization server, ensure that the destination server is configured to process the received events. In particular, the logcfg configuration entry in the aznapi-configuration stanza must be set on the remote authorization server. You must use the following format for the category value in this logcfg entry:

remote.webseal.hostname.webseald

where

hostname

The name of the appliance that originated the event.

For example, the following entry configures the remote authorization server to accept logging events from the iswga.au.ibm.com server, and send these events to the event.log file:

logcfg = remote.webseal.iswga.au.ibm.com.webseald:file path=/var/
PolicyDirector/log/event.log

The remote authorization server discards any events that originate from a server for which there is no matching logcfg rule.

parameter

The different agents support the following configuration parameters:

Table 313. Logging agent configuration parameters

Parameter | Supporting agents
buffer_size | remote
compress | remote
dn | remote
error_retry | remote, rsyslog
flush_interval | all
hi_water | all
log_id | file, rsyslog
max_event_len | rsyslog
max_rollover_files | file
mode | file
path | all
port | remote, rsyslog
queue_size | all
rebind_retry | remote, rsyslog
rollover_size | file
server | remote, rsyslog
ssl_keyfile | rsyslog
ssl_label | rsyslog
ssl_stashfile | rsyslog

Note: For a complete description of the available logging agents and the supported configuration parameters, see the Security Access Manager: Auditing Guide.

Usage

This stanza entry is required.

Default value

None.

Example

To log server events in a file called msg__webseald.log:

server-log-cfg = file path=msg__webseald.log

To send server events to a remote syslog server:

server-log-cfg = rsyslog server=timelord,port=514,log_id=webseal-instance

Parent topic: [logging] stanza

[ltpa] stanza[ltpa] stanzaltpa stanzastanzasltpaAccept and generate LTPA cookies for authentication. Stanza referenceltpa-authcookie-nameUse the cookie-name stanza entry to specify the name of the LTPA cookie that WebSEAL issues to clients.cookie-domainUse the cookie-domain stanza entry to specify the domain of the LTPA cookie that WebSEAL issues to clients.jct-ltpa-cookie-namekeyfileupdate-cookieuse-full-dn

[ltpa] stanza

Accept and generate LTPA cookies for authentication.

ltpa-auth

cookie-name
Use the cookie-name stanza entry to specify the name of the LTPA cookie that WebSEAL issues to clients.

cookie-domain
Use the cookie-domain stanza entry to specify the domain of the LTPA cookie that WebSEAL issues to clients.

jct-ltpa-cookie-name

keyfile

update-cookie

use-full-dn

Parent topic: Stanza reference

ltpa-authltpa-authltpa-auth stanza entryltpa stanzaentriesltpa-authltpa stanzaltpa stanzaltpa-auth entrySyntax ltpa-auth = {http|https|both|none}Description Enables support for LTPA cookie generation and authentication.Options httpEnables support for http cookies.httpsEnables support for https cookies.bothEnables support for both http and https cookies.noneDisables support for both http and https cookies.Usage This stanza entry is required.Default value noneExample ltpa-auth = https[ltpa] stanza

ltpa-auth

Syntax

ltpa-auth = {http|https|both|none}

Description

Enables support for LTPA cookie generation and authentication.

Options

http

Enables support for http cookies.

https

Enables support for https cookies.

both

Enables support for both http and https cookies.

none

Disables support for both http and https cookies.

Usage

This stanza entry is required.

Default value

none

Example

ltpa-auth = https

Parent topic: [ltpa] stanza

cookie-namecookie-nameIBM Security Access Manager for Web WebSEAL cookie-name stanza entryUse the cookie-name stanza entry to specify the name of the LTPA cookie that WebSEAL issues to clients.cookie-name stanza entryltpa stanzaentriescookie-nameltpa stanzaltpa stanzacookie-name entrySyntax cookie-name = cookie_name Description The name of the LTPA cookie that WebSEAL issues to clients. Options cookie_nameThis must be Ltpatoken2 as only LTPA version 2 cookies are supported. Usage This stanza entry is required. Default value Ltpatoken2 Example cookie-name = Ltpatoken2 [ltpa] stanza

cookie-name

Use the cookie-name stanza entry to specify the name of the LTPA cookie that WebSEAL issues to clients.

Syntax

cookie-name = cookie_name

Description

The name of the LTPA cookie that WebSEAL issues to clients.

Options

cookie_name

This must be Ltpatoken2 as only LTPA version 2 cookies are supported.

Usage

This stanza entry is required.

Default value

Ltpatoken2

Example

cookie-name = Ltpatoken2

Parent topic: [ltpa] stanza

cookie-domaincookie-domainIBM Security Access Manager for Web WebSEAL cookie-domain stanza entryUse the cookie-domain stanza entry to specify the domain of the LTPA cookie that WebSEAL issues to clients.cookie-domain stanza entryltpa stanzaentriescookie-domainltpa stanzaltpa stanzacookie-domain entrySyntax cookie-domain = domain_name Description The domain of the LTPA cookie that WebSEAL issues to clients. If you do not specify a cookie domain, WebSEAL creates the LTPA cookie as a host-only cookie. Options domain_nameThe domain of the LTPA cookie. Usage This stanza entry is required. Default value none Example cookie-domain = ibm.com [ltpa] stanza

cookie-domain

Use the cookie-domain stanza entry to specify the domain of the LTPA cookie that WebSEAL issues to clients.

Syntax

cookie-domain = domain_name

Description

The domain of the LTPA cookie that WebSEAL issues to clients. If you do not specify a cookie domain, WebSEAL creates the LTPA cookie as a host-only cookie.

Options

domain_name

The domain of the LTPA cookie.

Usage

This stanza entry is required.

Default value

none

Example

cookie-domain = ibm.com

Parent topic: [ltpa] stanza

jct-ltpa-cookie-namejct-ltpa-cookie-namejct-ltpa-cookie-name stanza entryltpa stanzaentriesjct-ltpa-cookie-nameltpa stanzaltpa stanzajct-ltpa-cookie-name entrySyntax jct-ltpa-cookie-name = cookie_name Description The name of the cookie containing the LTPA token that WebSEAL sends across the junction to the backend server. If you do not specify a value for this item, WebSEAL uses the following default values: LtpaToken for cookies containing LTPA tokens.LtpaToken2 for cookies containing LTPA version 2 tokens.WebSphere also uses these default values. Options cookie_nameThis name must match the LTPA cookie name that the WebSphere application uses on this junction. Usage This stanza entry is optional. Default value The default value for LTPA tokens is LtpaToken.The default value for LTPA2 tokens is LtpaToken2. Examplejct-ltpa-cookie-name = myCookieName [ltpa] stanza

jct-ltpa-cookie-name

Syntax

jct-ltpa-cookie-name = cookie_name

Description

The name of the cookie containing the LTPA token that WebSEAL sends across the junction to the backend server. If you do not specify a value for this item, WebSEAL uses the following default values:

LtpaToken for cookies containing LTPA tokens.

LtpaToken2 for cookies containing LTPA version 2 tokens.

WebSphere® also uses these default values.

Options

cookie_name

This name must match the LTPA cookie name that the WebSphere application uses on this junction.

Usage

This stanza entry is optional.

Default value

The default value for LTPA tokens is LtpaToken.

The default value for LTPA2 tokens is LtpaToken2.

Example

jct-ltpa-cookie-name = myCookieName

Parent topic: [ltpa] stanza

keyfilekeyfilekeyfile stanza entryltpa stanzaentrieskeyfileltpa stanzaltpa stanzakeyfile entrySyntax keyfile = keyfile_name Description The key file used when accessing LTPA cookies. The value must correspond to a valid LTPA key file, as generated by WebSphere. Options keyfile_nameName of a valid LTPA key file, as generated by WebSphere. Usage This stanza entry is optional. Default value none Example keyfile = keyfile123 [ltpa] stanza

keyfile

Syntax

keyfile = keyfile_name

Description

The key file used when accessing LTPA cookies. The value must correspond to a valid LTPA key file, as generated by WebSphere®.

Options

keyfile_name

Name of a valid LTPA key file, as generated by WebSphere.

Usage

This stanza entry is optional.

Default value

none

Example

keyfile = keyfile123

Parent topic: [ltpa] stanza

update-cookieupdate-cookieltpa-auth stanza entryltpa stanzaentriesltpa-authltpa stanzaltpa stanzaltpa-auth entrySyntax update-cookie = number_of_seconds Description The number of seconds that pass between updates of the LTPA cookie with the lifetime of the cookie.With each request, if n seconds have passed since the last cookie update, another update will occur. A zero value will cause the lifetime timestamp in the LTPA cookie to be updated with each request.Negative values will cause the lifetime of the cookie to be set to the same value as the lifetime of the user session.This setting is used in an attempt to mimic the inactivity timeout of a user session.This configuration entry affects the LTPA cookie that WebSEAL issues to clients. It is the lifetime of the cookie specified by the cookie-name configuration entry in the [ltpa] stanza. Options number_of_secondsThe number of seconds that pass between updates of the LTPA cookie with the lifetime of the cookie. Usage This stanza entry is required. Default value -1 Example update-cookie = 0 [ltpa] stanza

update-cookie

Syntax

update-cookie = number_of_seconds

Description

The number of seconds that pass between updates of the LTPA cookie with the lifetime of the cookie.With each request, if n seconds have passed since the last cookie update, another update will occur. A zero value will cause the lifetime timestamp in the LTPA cookie to be updated with each request.Negative values will cause the lifetime of the cookie to be set to the same value as the lifetime of the user session.This setting is used in an attempt to mimic the inactivity timeout of a user session.

Note: This configuration entry affects the LTPA cookie that WebSEAL issues to clients. It is the lifetime of the cookie specified by the cookie-name configuration entry in the [ltpa] stanza.

Options

number_of_seconds

The number of seconds that pass between updates of the LTPA cookie with the lifetime of the cookie.

Usage

This stanza entry is required.

Default value

-1

Example

update-cookie = 0

Parent topic: [ltpa] stanza

use-full-dnuse-full-dnuse-full-dn stanza entryltpa stanzaentriesuse-full-dnltpa stanzaltpa stanzause-full-dn entrySyntax use-full-dn = {true|false} Description Controls whether the generated LTPA cookie contains the full DN of the user, or the Security Access Manager short name of the user. Options trueWebSEAL inserts the full DN of the user into the LTPA cookie. falseWebSEAL inserts the Security Access Manager short name of the user into the LTPA cookie. Usage This stanza entry is optional. Default value true Example use-full-dn = true [ltpa] stanza

use-full-dn

Syntax

use-full-dn = {true|false}

Description

Controls whether the generated LTPA cookie contains the full DN of the user, or the Security Access Manager short name of the user.

Options

true

WebSEAL inserts the full DN of the user into the LTPA cookie.

false

WebSEAL inserts the Security Access Manager short name of the user into the LTPA cookie.

Usage

This stanza entry is optional.

Default value

true

Example

use-full-dn = true

Parent topic: [ltpa] stanza

[ltpa-cache] stanza[ltpa-cache] stanzaltpa-cache stanzastanzasltpa-cacheStanza referenceltpa-cache-enabledltpa-cache-entry-idle-timeoutltpa-cache-entry-lifetimeltpa-cache-size

[ltpa-cache] stanza

ltpa-cache-enabled

ltpa-cache-entry-idle-timeout

ltpa-cache-entry-lifetime

ltpa-cache-size

Parent topic: Stanza reference

ltpa-cache-enabledltpa-cache-enabledltpa-cache-enabled stanza entryltpa-cache stanzaentriesltpa-cache-enabledltpa-cache stanzaltpa-cache stanzaltpa-cache-enabled entrySyntax ltpa-cache-enabled = {yes|no}Description Enables or disables the Lightweight Third Party Authentication cache.Options yesA value of yes enables caching. noA value of no disables caching.Usage This stanza entry is required.Default value yesExample ltpa-cache-enabled = yes[ltpa-cache] stanza

ltpa-cache-enabled

Syntax

ltpa-cache-enabled = {yes|no}

Description

Enables or disables the Lightweight Third Party Authentication cache.

Options

yes

A value of yes enables caching.

no

A value of no disables caching.

Usage

This stanza entry is required.

Default value

yes

Example

ltpa-cache-enabled = yes

Parent topic: [ltpa-cache] stanza

ltpa-cache-entry-idle-timeoutltpa-cache-entry-idle-timeoutltpa-cache-entry-idle-timeout stanza entryltpa-cache stanzaentriesltpa-cache-entry-idle-timeoutltpa-cache stanzaltpa-cache stanzaltpa-cache-entry-idle-timeout entrySyntax ltpa-cache-entry-idle-timeout = number_of_secondsDescription Integer value that specifies the timeout, in seconds, for cache entries that are idle.Options number_of_secondsInteger value that specifies the timeout, in seconds, for cache entries that are idle. The value must be greater than or equal to zero (0). A value of zero means that entries are not removed from the LTPA cache due to inactivity. However, they may still be removed due to either the ltpa-cache-size being exceeded or the ltpa-cache-entry-lifetime stanza entry being exceeded. WebSEAL does not impose a maximum value. Usage This stanza entry is required, but is ignored when LTPA caching is disabled.Default value 600Example ltpa-cache-entry-idle-timeout = 600[ltpa-cache] stanza

ltpa-cache-entry-idle-timeout

Syntax

ltpa-cache-entry-idle-timeout = number_of_seconds

Description

Integer value that specifies the timeout, in seconds, for cache entries that are idle.

Options

number_of_seconds

Integer value that specifies the timeout, in seconds, for cache entries that are idle. The value must be greater than or equal to zero (0). A value of zero means that entries are not removed from the LTPA cache due to inactivity. However, they may still be removed due to either the ltpa-cache-size being exceeded or the ltpa-cache-entry-lifetime stanza entry being exceeded. WebSEAL does not impose a maximum value.

Usage

This stanza entry is required, but is ignored when LTPA caching is disabled.

Default value

600

Example

ltpa-cache-entry-idle-timeout = 600

Parent topic: [ltpa-cache] stanza

ltpa-cache-entry-lifetimeltpa-cache-entry-lifetimeltpa-cache-entry-lifetime stanza entryltpa-cache stanzaentriesltpa-cache-entry-lifetimeltpa-cache stanzaltpa-cache stanzaltpa-cache-entry-lifetime entrySyntax ltpa-cache-entry-lifetime = number_of_secondsDescription Integer value that specifies the lifetime, in seconds, of a LTPA cache entry.Options number_of_secondsInteger value that specifies the lifetime, in seconds, of a LTPA cache entry. The value must be greater than or equal to zero (0). A value of zero means that entries are not removed from the LTPA cache due to their entry lifetime being exceeded. However, they may still be removed due to either the ltpa-cache-size being exceeded or the ltpa-cache-entry-idle-timeout stanza entry being exceeded. WebSEAL does not impose a maximum value. Usage This stanza entry is required, but is ignored when LTPA caching is disabled.Default value 3600Example ltpa-cache-entry-lifetime = 3600[ltpa-cache] stanza

ltpa-cache-entry-lifetime

Syntax

ltpa-cache-entry-lifetime = number_of_seconds

Description

Integer value that specifies the lifetime, in seconds, of a LTPA cache entry.

Options

number_of_seconds

Integer value that specifies the lifetime, in seconds, of a LTPA cache entry. The value must be greater than or equal to zero (0). A value of zero means that entries are not removed from the LTPA cache due to their entry lifetime being exceeded. However, they may still be removed due to either the ltpa-cache-size being exceeded or the ltpa-cache-entry-idle-timeout stanza entry being exceeded. WebSEAL does not impose a maximum value.

Usage

This stanza entry is required, but is ignored when LTPA caching is disabled.

Default value

3600

Example

ltpa-cache-entry-lifetime = 3600

Parent topic: [ltpa-cache] stanza

ltpa-cache-sizeltpa-cache-sizeltpa-cache-size stanza entryltpa-cache stanzaentriesltpa-cache-sizeltpa-cache stanzaltpa-cache stanzaltpa-cache-size entrySyntax ltpa-cache-size = number_of_entriesDescription Integer value indicating the number of entries allowed in the LTPA cache. Options number_of_entriesInteger value indicating the number of entries allowed in the LTPA cache. The value must be greater than or equal to zero (0). A value of zero means that there is no limit on the size of the LTPA cache. This is not recommended. WebSEAL does not impose a maximum value. Choose your maximum value to stay safely within the bounds of your available system memory.Usage This stanza entry is required, but is ignored when LTPA caching is disabled.Default value 4096Example ltpa-cache-size = 4096[ltpa-cache] stanza

ltpa-cache-size

Syntax

ltpa-cache-size = number_of_entries

Description

Integer value indicating the number of entries allowed in the LTPA cache.

Options

number_of_entries

Integer value indicating the number of entries allowed in the LTPA cache. The value must be greater than or equal to zero (0). A value of zero means that there is no limit on the size of the LTPA cache. This is not recommended.

WebSEAL does not impose a maximum value. Choose your maximum value to stay safely within the bounds of your available system memory.

Usage

This stanza entry is required, but is ignored when LTPA caching is disabled.

Default value

4096

Example

ltpa-cache-size = 4096

Parent topic: [ltpa-cache] stanza

[mpa] stanza[mpa] stanzampa stanzastanzasmpaStanza referencempa

[mpa] stanza

mpa

Parent topic: Stanza reference

mpampampa stanza entrympa stanzaentriesmpampa stanzampa stanzampa entrySyntax mpa = {yes|no}Description Enables support for multiplexing proxy agents.Options yesEnables support for multiplexing proxy agents.noDisables support for multiplexing proxy agents.Usage This stanza entry is required.Default value noExample mpa = no[mpa] stanza

mpa

Syntax

mpa = {yes|no}

Description

Enables support for multiplexing proxy agents.

Options

yes

Enables support for multiplexing proxy agents.

no

Disables support for multiplexing proxy agents.

Usage

This stanza entry is required.

Default value

no

Example

mpa = no

Parent topic: [mpa] stanza

[oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.Stanza referencecluster-nameUse the cluster-name entry in the [oauth] stanza to specify the Tivoli Federated Identity Manager cluster that hosts the OAuth service.default-fed-idUse the default-fed-id stanza entry to specify the default federation provider that WebSEAL uses for OAuth requests.fed-id-paramUse the fed-id-param stanza entry to specify the name of the request parameter whose value specifies the Provider ID for WebSEAL to include in OAuth requests.multivalue-scopeUse the multivalue-scope stanza entry to specify whether OAuth multivalue scope support is enabled.oauth-authUse the oauth-auth stanza entry to specify whether Open Authentication (OAuth) is enabled.user-identity-attributeUse the user-identity-attribute stanza entry to specify the attribute that contains the user identity.

[oauth] stanza

Use the [oauth] stanza to configure Open Authentication (OAuth) settings.

cluster-name
Use the cluster-name entry in the [oauth] stanza to specify the Tivoli Federated Identity Manager cluster that hosts the OAuth service.

default-fed-id
Use the default-fed-id stanza entry to specify the default federation provider that WebSEAL uses for OAuth requests.

fed-id-param
Use the fed-id-param stanza entry to specify the name of the request parameter whose value specifies the Provider ID for WebSEAL to include in OAuth requests.

multivalue-scope
Use the multivalue-scope stanza entry to specify whether OAuth multivalue scope support is enabled.

oauth-auth
Use the oauth-auth stanza entry to specify whether Open Authentication (OAuth) is enabled.

user-identity-attribute
Use the user-identity-attribute stanza entry to specify the attribute that contains the user identity.

Parent topic: Stanza reference

cluster-namecluster-nameIBM Security Access Manager for Web WebSEAL cluster-name stanza entryUse the cluster-name entry in the [oauth] stanza to specify the Tivoli Federated Identity Manager cluster that hosts the OAuth service.cluster-name stanza entryoauth-eas stanzaentriescluster-nameoauth-eas stanzaoauth-eas stanzacluster-name entrySyntax cluster-name = <cluster> Description The name of the Tivoli Federated Identity Manager cluster that hosts this OAuth service. You must also specify a corresponding [tfim-cluster:<cluster>]stanza, which contains the definition of the cluster. Options <cluster>The name of the Tivoli Federated Identity Manager cluster where the OAuth service is hosted. Usage This stanza entry is required when you configure OAuth authentication. Default value None. Example cluster-name = oauth-clusterFor this example, there needs to be a corresponding [tfim-cluster:oauth-cluster] stanza to define the cluster. [oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.

cluster-name

Use the cluster-name entry in the [oauth] stanza to specify the Tivoli Federated Identity Manager cluster that hosts the OAuth service.

Syntax

cluster-name = <cluster>

Description

The name of the Tivoli Federated Identity Manager cluster that hosts this OAuth service. You must also specify a corresponding [tfim-cluster:<cluster>]stanza, which contains the definition of the cluster.

Options

<cluster>

The name of the Tivoli Federated Identity Manager cluster where the OAuth service is hosted.

Usage

This stanza entry is required when you configure OAuth authentication.

Default value

None.

Example

cluster-name = oauth-cluster

For this example, there needs to be a corresponding [tfim-cluster:oauth-cluster] stanza to define the cluster.

Parent topic: [oauth] stanza

default-fed-iddefault-fed-idIBM Security Access Manager for Web WebSEAL default-fed-id stanza entryUse the default-fed-id stanza entry to specify the default federation provider that WebSEAL uses for OAuth requests.default-fed-id stanza entryoauth stanzaentriesdefault-fed-idoauth stanzaoauth stanzadefault-fed-id entrySyntax default-fed-id = <provider_url> Description The Provider ID of the default OAuth federation in Tivoli Federated Identity Manager. By default, WebSEAL uses this provider ID for OAuth requests. You can override this default provider for an individual request by including a request parameter that has the name specified by the fed-id-param configuration entry. Options <provider_url>The IP address for the federation provider that WebSEAL uses for OAuth requests. You can find the Provider ID of a federation on the federation properties page. Usage This stanza entry is required when you configure OAuth authentication. Default value None Example default-fed-id = https://localhost/sps/oauthfed/oauth10 [oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.

default-fed-id

Use the default-fed-id stanza entry to specify the default federation provider that WebSEAL uses for OAuth requests.

Syntax

default-fed-id = <provider_url>

Description

The Provider ID of the default OAuth federation in Tivoli Federated Identity Manager. By default, WebSEAL uses this provider ID for OAuth requests.

You can override this default provider for an individual request by including a request parameter that has the name specified by the fed-id-param configuration entry.

Options

<provider_url>

The IP address for the federation provider that WebSEAL uses for OAuth requests. You can find the Provider ID of a federation on the federation properties page.

Usage

This stanza entry is required when you configure OAuth authentication.

Default value

None

Example

default-fed-id = https://localhost/sps/oauthfed/oauth10

Parent topic: [oauth] stanza

fed-id-paramfed-id-paramIBM Security Access Manager for Web WebSEAL fed-id-param stanza entryUse the fed-id-param stanza entry to specify the name of the request parameter whose value specifies the Provider ID for WebSEAL to include in OAuth requests.fed-id-param stanza entryoauth stanzaentriesfed-id-paramoauth stanzaoauth stanzafed-id-param entrySyntax fed-id-param = <request_param_name> Description The name of the parameter that you can include in a request to override the Provider ID that is specified by the default-fed-id configuration entry. If this fed-id-param configuration entry is set, WebSEAL checks incoming requests for a parameter with the specified name. If this request parameter exists, WebSEAL uses the Provider ID contained in the request rather than the default-fed-id Provider ID. You can delete this configuration entry to ensure that WebSEAL always uses the default provider that is specified by default-fed-id. Options <request_param_name>The name of the request parameter whose value specifies the Provider ID for WebSEAL to include in OAuth requests. If no such parameter exists in the request, WebSEAL uses the Provider ID specified by default-fed-id. Usage This stanza entry is optional.If you do not configure this stanza entry, WebSEAL always uses the provider that is configured as the default-fed-id. Default value None. Example fed-id-param = FederationId [oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.

fed-id-param

Use the fed-id-param stanza entry to specify the name of the request parameter whose value specifies the Provider ID for WebSEAL to include in OAuth requests.

Syntax

fed-id-param = <request_param_name>

Description

The name of the parameter that you can include in a request to override the Provider ID that is specified by the default-fed-id configuration entry. If this fed-id-param configuration entry is set, WebSEAL checks incoming requests for a parameter with the specified name. If this request parameter exists, WebSEAL uses the Provider ID contained in the request rather than the default-fed-id Provider ID.

Note: You can delete this configuration entry to ensure that WebSEAL always uses the default provider that is specified by default-fed-id.

Options

<request_param_name>

The name of the request parameter whose value specifies the Provider ID for WebSEAL to include in OAuth requests. If no such parameter exists in the request, WebSEAL uses the Provider ID specified by default-fed-id.

Usage

This stanza entry is optional.

Note: If you do not configure this stanza entry, WebSEAL always uses the provider that is configured as the default-fed-id.

Default value

None.

Example

fed-id-param = FederationId

Parent topic: [oauth] stanza

multivalue-scopeUse the multivalue-scope stanza entry to specify whether OAuth multivalue scope support is enabled.Syntax multivalue-scope = {true | false}Description The multivalue-scope entry enables or disables OAuth multivalue scope.Options trueOAuth multivalue scope is enabled.falseOAuth multivalue scope is disabled.Usage This stanza entry is optional.Default value The default value is false. By default, OAuth multivalue scope is disabled.Example multivalue-scope = false[oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.

multivalue-scope

Use the multivalue-scope stanza entry to specify whether OAuth multivalue scope support is enabled.

Syntax

multivalue-scope = {true | false}

Description

The multivalue-scope entry enables or disables OAuth multivalue scope.

Options

true

OAuth multivalue scope is enabled.

false

OAuth multivalue scope is disabled.

Usage

This stanza entry is optional.

Default value

The default value is false. By default, OAuth multivalue scope is disabled.

Example

multivalue-scope = false

Parent topic: [oauth] stanza

oauth-authUse the oauth-auth stanza entry to specify whether Open Authentication (OAuth) is enabled.oauth-auth stanza entryoauth stanzaentriesoauth-authoauth stanzaoauth stanzaoauth-auth entrySyntax oauth-auth = {http | https | both | none} DescriptionEnables authentication with OAuth mechanism. Options httpEnable OAuth over HTTP.httpsEnable OAuth over HTTPS.bothEnable OAuth over both HTTP and HTTPS.noneDisable OAuth. Usage This stanza entry is required when you configure OAuth authentication. Default value The default value is none. By default, OAuth authentication is disabled. Example oauth-auth = none [oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.

oauth-auth

Use the oauth-auth stanza entry to specify whether Open Authentication (OAuth) is enabled.

Syntax

oauth-auth = {http | https | both | none}

Description

Enables authentication with OAuth mechanism.

Options

http

Enable OAuth over HTTP.

https

Enable OAuth over HTTPS.

both

Enable OAuth over both HTTP and HTTPS.

none

Disable OAuth.

Usage

This stanza entry is required when you configure OAuth authentication.

Default value

The default value is none. By default, OAuth authentication is disabled.

Example

oauth-auth = none

Parent topic: [oauth] stanza

user-identity-attributeUse the user-identity-attribute stanza entry to specify the attribute that contains the user identity.user-identity-attribute stanza entryoauth stanzaentriesuser-identity-attributeoauth stanzaoauth stanzauser-identity-attribute entrySyntax user-identity-attribute = <attribute_name> DescriptionSpecifies which attribute, within the RSTR from Federated Identity Manager, contains the user identity. The value of this entry is used as the principal when a credential is created. Options <attribute_name>The attribute that contains the user identity. Usage This stanza entry is required. Default value The default value is username. Example user-identity-attribute = username [oauth] stanzaUse the [oauth] stanza to configure Open Authentication (OAuth) settings.

user-identity-attribute

Use the user-identity-attribute stanza entry to specify the attribute that contains the user identity.

Syntax

user-identity-attribute = <attribute_name>

Description

Specifies which attribute, within the RSTR from Federated Identity Manager, contains the user identity. The value of this entry is used as the principal when a credential is created.

Options

<attribute_name>

The attribute that contains the user identity.

Usage

This stanza entry is required.

Default value

The default value is username.

Example

user-identity-attribute = username

Parent topic: [oauth] stanza

[oauth-eas] stanza[oauth-eas] stanzaoauth-eas stanzastanzasoauth-easYou can configure this stanza to support OAuth authorization decisions as part of WebSEAL requests. For more information about OAuth authorization decisions support, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.The OAuth EAS is used for a particular object if the effective POP for the object has an attribute called eas-trigger, with an associated value of trigger_oauth_eas.Stanza referenceapply-tam-native-policyUse the apply-tam-native-policy stanza entry to control whether the OAuth EAS also uses the native Security Access Manager policy when it is determining the access permissions for the resource.bad-gateway-rsp-fileUse the bad-gateway-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 502 Bad Gateway response.bad-request-rsp-fileUse the bad-request-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 400 Bad Request response.cache-sizedefault-modeUse the default-mode stanza entry to specify the default OAuth EAS mode.eas-enabledUse the eas-enabled stanza entry to specify whether OAuth external authorization service (EAS) is enabled.mode-paramThe name of the parameter that you can include in a request to override the mode that is specified by the default-mode configuration entry.realm-nametrace-componentunauthorized-rsp-file

[oauth-eas] stanza

Notes:

You can configure this stanza to support OAuth authorization decisions as part of WebSEAL requests. For more information about OAuth authorization decisions support, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

The OAuth EAS is used for a particular object if the effective POP for the object has an attribute called eas-trigger, with an associated value of trigger_oauth_eas.

apply-tam-native-policy
Use the apply-tam-native-policy stanza entry to control whether the OAuth EAS also uses the native Security Access Manager policy when it is determining the access permissions for the resource.

bad-gateway-rsp-file
Use the bad-gateway-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 502 Bad Gateway response.

bad-request-rsp-file
Use the bad-request-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 400 Bad Request response.

cache-size

default-mode
Use the default-mode stanza entry to specify the default OAuth EAS mode.

eas-enabled
Use the eas-enabled stanza entry to specify whether OAuth external authorization service (EAS) is enabled.

mode-param
The name of the parameter that you can include in a request to override the mode that is specified by the default-mode configuration entry.

realm-name

trace-component

unauthorized-rsp-file

Parent topic: Stanza reference

apply-tam-native-policyapply-tam-native-policyIBM Security Access Manager for Web WebSEAL apply-tam-native-policy stanza entryUse the apply-tam-native-policy stanza entry to control whether the OAuth EAS also uses the native Security Access Manager policy when it is determining the access permissions for the resource.apply-tam-native-policy stanza entryoauth-eas stanzaentriesapply-tam-native-policyoauth-eas stanzaoauth-eas stanzaapply-tam-native-policy entrySyntax apply-tam-native-policy = {true | false} Description Determines whether the Security Access Manager policy still takes effect, in addition to the OAuth authorization. Options trueThe OAuth EAS checks the Security Access Manager policy to determine whether the user has permission to access the resource.falseThe OAuth EAS does not check the Security Access Manager ACL policy to determine whether the user has permission to access the resource. Usage This stanza entry is required when you configure OAuth EAS authentication. Default value None. Example apply-tam-native-policy = false [oauth-eas] stanza

apply-tam-native-policy

Use the apply-tam-native-policy stanza entry to control whether the OAuth EAS also uses the native Security Access Manager policy when it is determining the access permissions for the resource.

Syntax

apply-tam-native-policy = {true | false}

Description

Determines whether the Security Access Manager policy still takes effect, in addition to the OAuth authorization.

Options

true

The OAuth EAS checks the Security Access Manager policy to determine whether the user has permission to access the resource.

false

The OAuth EAS does not check the Security Access Manager ACL policy to determine whether the user has permission to access the resource.

Usage

This stanza entry is required when you configure OAuth EAS authentication.

Default value

None.

Example

apply-tam-native-policy = false

Parent topic: [oauth-eas] stanza

bad-gateway-rsp-filebad-gateway-rsp-fileIBM Security Access Manager for Web WebSEAL bad-gateway-rsp-file stanza entryUse the bad-gateway-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 502 Bad Gateway response.bad-gateway-rsp-file stanza entryoauth-eas stanzaentriesbad-gateway-rsp-fileoauth-eas stanzaoauth-eas stanzabad-gateway-rsp-file entrySyntax bad-gateway-rsp-file = <file_name> Description Specifies the file that contains the body that WebSEAL uses to construct a 502 Bad Gateway response. This response is generated when Tivoli Federated Identity Manager fails to process the request. Options <file_name>The name of the 502 Bad Gateway response file. Usage This stanza entry is required when you configure OAuth EAS authentication. Default value None. Example bad-gateway-rsp-file = bad_gateway.html [oauth-eas] stanza

bad-gateway-rsp-file

Use the bad-gateway-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 502 Bad Gateway response.

Syntax

bad-gateway-rsp-file = <file_name>

Description

Specifies the file that contains the body that WebSEAL uses to construct a 502 Bad Gateway response. This response is generated when Tivoli Federated Identity Manager fails to process the request.

Options

<file_name>

The name of the 502 Bad Gateway response file.

Usage

This stanza entry is required when you configure OAuth EAS authentication.

Default value

None.

Example

bad-gateway-rsp-file = bad_gateway.html

Parent topic: [oauth-eas] stanza

bad-request-rsp-filebad-request-rsp-fileIBM Security Access Manager for Web WebSEAL bad-request-rsp-file stanza entryUse the bad-request-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 400 Bad Request response.bad-request-rsp-file stanza entryoauth-eas stanzaentriesbad-request-rsp-fileoauth-eas stanzaoauth-eas stanzabad-request-rsp-file entrySyntax bad-request-rsp-file = <file_name> Description Specifies the file that contains the body that WebSEAL uses to construct a 400 Bad Request response. This response is generated when required OAuth elements are missing from a request. Options <file_name>The name of the 400 Bad Request response file. Usage This stanza entry is required when you configure OAuth-EAS authentication. Default value None. Example bad-request-rsp-file = bad_rqst.html [oauth-eas] stanza

bad-request-rsp-file

Use the bad-request-rsp-file stanza entry to specify the file that contains the content that WebSEAL uses to construct a 400 Bad Request response.

Syntax

bad-request-rsp-file = <file_name>

Description

Specifies the file that contains the body that WebSEAL uses to construct a 400 Bad Request response. This response is generated when required OAuth elements are missing from a request.

Options

<file_name>

The name of the 400 Bad Request response file.

Usage

This stanza entry is required when you configure OAuth-EAS authentication.

Default value

None.

Example

bad-request-rsp-file = bad_rqst.html

Parent topic: [oauth-eas] stanza

cache-sizecache-sizecache-size stanza entryoauth-eas stanzaentriescache-sizeoauth-eas stanzaoauth-eas stanzacache-size entrySyntax cache-size = <number_decisions> Description Specifies the maximum number of OAuth 2.0 bearer token authorization decisions to cache. This EAS has a built-in cache for storing authorization decisions so that WebSEAL can repeatedly use the same OAuth 2.0 bearer token without sending repeated requests to Tivoli Federated Identity Manager. WebSEAL can cache bearer token decisions because they do not require signing of the request, unlike OAuth 1.0 requests. The lifetime of the cache entry depends on the Expires attribute that Tivoli Federated Identity Manager returns. If Tivoli Federated Identity Manager does not return this attribute, WebSEAL does not cache the decision. This EAS implements a Least Recently Used cache. The decision associated with the least recently used bearer token is forgotten when a new bearer token decision is cached. A cache-size of 0 disables caching of authorization decisions. Options <number_decisions> The maximum number of OAuth 2.0 bearer token authorization decisions that WebSEAL caches. Usage This stanza entry is optional. Default value The default value is 0, which disables caching of authorization decisions. Example cache-size = 0 [oauth-eas] stanza

cache-size

Syntax

cache-size = <number_decisions>

Description

Specifies the maximum number of OAuth 2.0 bearer token authorization decisions to cache. This EAS has a built-in cache for storing authorization decisions so that WebSEAL can repeatedly use the same OAuth 2.0 bearer token without sending repeated requests to Tivoli Federated Identity Manager.

WebSEAL can cache bearer token decisions because they do not require signing of the request, unlike OAuth 1.0 requests. The lifetime of the cache entry depends on the Expires attribute that Tivoli Federated Identity Manager returns. If Tivoli Federated Identity Manager does not return this attribute, WebSEAL does not cache the decision.

This EAS implements a Least Recently Used cache. The decision associated with the least recently used bearer token is forgotten when a new bearer token decision is cached. A cache-size of 0 disables caching of authorization decisions.

Options

<number_decisions>

The maximum number of OAuth 2.0 bearer token authorization decisions that WebSEAL caches.

Usage

This stanza entry is optional.

Default value

The default value is 0, which disables caching of authorization decisions.

Example

cache-size = 0

Parent topic: [oauth-eas] stanza

default-modedefault-modeIBM Security Access Manager for Web WebSEAL default-mode stanza entryUse the default-mode stanza entry to specify the default OAuth EAS mode.default-mode stanza entryoauth-eas stanzaentriesdefault-modeoauth-eas stanzaoauth-eas stanzadefault-mode entrySyntax default-mode = <oauth_mode> Description The mode affects the validation of request parameters and the construction of the RequestSecurityToken (RST) sent to Tivoli Federated Identity Manager. You can override this default mode for an individual request by providing a valid mode value [OAuth10|OAuth20Bearer] in a request parameter. The request parameter must have the name that is specified by the mode-param configuration entry. Options <oauth_mode>The OAuth mode that the OAuth EAS uses by default. Usage This stanza entry is required when you configure OAuth EAS authentication. Default value None. Example default-mode = OAuth10 [oauth-eas] stanza

default-mode

Use the default-mode stanza entry to specify the default OAuth EAS mode.

Syntax

default-mode = <oauth_mode>

Description

The mode affects the validation of request parameters and the construction of the RequestSecurityToken (RST) sent to Tivoli Federated Identity Manager.

You can override this default mode for an individual request by providing a valid mode value [OAuth10|OAuth20Bearer] in a request parameter. The request parameter must have the name that is specified by the mode-param configuration entry.

Options

<oauth_mode>

The OAuth mode that the OAuth EAS uses by default.

Usage

This stanza entry is required when you configure OAuth EAS authentication.

Default value

None.

Example

default-mode = OAuth10

Parent topic: [oauth-eas] stanza

eas-enabledeas-enabledeas-enabled stanza entryUse the eas-enabled stanza entry to specify whether OAuth external authorization service (EAS) is enabled.eas-enabled stanza entryoauth-eas stanzaentrieseas-enabledoauth-eas stanzaoauth-eas stanzaeas-enabled entrySyntax eas-enabled = {true | false} DescriptionEnable or disable OAuth EAS. Options trueOAuth EAS is enabled.falseOAuth EAS is disabled. UsageThis stanza entry is optional. Default value The default value is false. By default, OAuth EAS is disabled. Exampleeas-enabled = true [oauth-eas] stanza

eas-enabled

Use the eas-enabled stanza entry to specify whether OAuth external authorization service (EAS) is enabled.

Syntax

eas-enabled = {true | false}

Description

Enable or disable OAuth EAS.

Options

true

OAuth EAS is enabled.

false

OAuth EAS is disabled.

Usage

This stanza entry is optional.

Default value

The default value is false. By default, OAuth EAS is disabled.

Example

eas-enabled = true

Parent topic: [oauth-eas] stanza

mode-parammode-paramThe name of the parameter that you can include in a request to override the mode that is specified by the default-mode configuration entry.mode-param stanza entryoauth-eas stanzaentriesmode-paramoauth-eas stanzaoauth-eas stanzamode-param entrySyntax mode-param = <mode_name> Description If this mode-param configuration entry is set, WebSEAL checks incoming requests for a parameter with the specified name. If this request parameter exists, WebSEAL uses the mode contained in the request rather than the mode specified by default-mode. You can delete this configuration entry to ensure that WebSEAL always uses the default mode that is specified by default-mode. Options <mode_name>The name of the request parameter whose value specifies the mode for OAuth EAS to use. If no such parameter exists in the request, WebSEAL uses the mode specified by default-mode. Usage This stanza entry is optional.If you do not configure this stanza entry, WebSEAL always uses the mode that is configured as the default-mode. Default value None. Example mode-param = mode [oauth-eas] stanza

mode-param

The name of the parameter that you can include in a request to override the mode that is specified by the default-mode configuration entry.

Syntax

mode-param = <mode_name>

Description

If this mode-param configuration entry is set, WebSEAL checks incoming requests for a parameter with the specified name. If this request parameter exists, WebSEAL uses the mode contained in the request rather than the mode specified by default-mode.

Note: You can delete this configuration entry to ensure that WebSEAL always uses the default mode that is specified by default-mode.

Options

<mode_name>

The name of the request parameter whose value specifies the mode for OAuth EAS to use. If no such parameter exists in the request, WebSEAL uses the mode specified by default-mode.

Usage

This stanza entry is optional.

Note: If you do not configure this stanza entry, WebSEAL always uses the mode that is configured as the default-mode.

Default value

None.

Example

mode-param = mode

Parent topic: [oauth-eas] stanza

realm-namerealm-namerealm-name stanza entryoauth-eas stanzaentriesrealm-nameoauth-eas stanzaoauth-eas stanzarealm-name entrySyntax realm-name = <realm_name> Description The name of the OAuth realm that is used in a 401 request for OAuth data. Options <realm_name>The name of the OAuth realm. Usage This stanza entry is required when you configure OAuth EAS authentication. Default value None. Example realm-name = realmOne [oauth-eas] stanza

realm-name

Syntax

realm-name = <realm_name>

Description

The name of the OAuth realm that is used in a 401 request for OAuth data.

Options

<realm_name>

The name of the OAuth realm.

Usage

This stanza entry is required when you configure OAuth EAS authentication.

Default value

None.

Example

realm-name = realmOne

Parent topic: [oauth-eas] stanza

trace-componenttrace-componenttrace-component stanza entryoauth-eas stanzaentriestrace-componentoauth-eas stanzaoauth-eas stanzatrace-component entrySyntax trace-component = <component_name> Description The name of the Security Access Manager trace component that the OAuth EAS uses. Options <component_name>The name of the Security Access Manager trace component. Usage This stanza entry is required when configuring OAuth EAS authentication. The pdweb.oauth component traces the data that passes into the OAuth EAS, which is governed by the [azn-decision-info] stanza. This trace might contain sensitive information. Default value None. Example trace-component = pdweb.oauth [oauth-eas] stanza

trace-component

Syntax

trace-component = <component_name>

Description

The name of the Security Access Manager trace component that the OAuth EAS uses.

Options

<component_name>

The name of the Security Access Manager trace component.

Usage

This stanza entry is required when configuring OAuth EAS authentication.

Note: The pdweb.oauth component traces the data that passes into the OAuth EAS, which is governed by the [azn-decision-info] stanza. This trace might contain sensitive information.

Default value

None.

Example

trace-component = pdweb.oauth

Parent topic: [oauth-eas] stanza

unauthorized-rsp-fileunauthorized-rsp-fileunauthorized-rsp-file stanza entryoauth-eas stanzaentriesunauthorized-rsp-fileoauth-eas stanzaoauth-eas stanzaunauthorized-rsp-file entrySyntax unauthorized-rsp-file = <file_name> Description Specifies the file that contains the body that is used when constructing a 401 Unauthorized response. This response is generated when either of the following scenarios occur: All OAuth data is missing from a request.The OAuth data fails validation. Options <file_name>The name of the 401 Unauthorized response file. Usage This stanza entry is required when you configure OAuth EAS authentication. Default value None. Example unauthorized-rsp-file = unauth_response.html [oauth-eas] stanza

unauthorized-rsp-file

Syntax

unauthorized-rsp-file = <file_name>

Description

Specifies the file that contains the body that is used when constructing a 401 Unauthorized response. This response is generated when either of the following scenarios occur:

All OAuth data is missing from a request.

The OAuth data fails validation.

Options

<file_name>

The name of the 401 Unauthorized response file.

Usage

This stanza entry is required when you configure OAuth EAS authentication.

Default value

None.

Example

unauthorized-rsp-file = unauth_response.html

Parent topic: [oauth-eas] stanza

[obligations-levels-mapping] stanza[obligations-levels-mapping] stanzaobligations-levels-mapping stanzastanzasobligations-levels-mappingStanza referenceobligation

[obligations-levels-mapping] stanza

obligation

Parent topic: Stanza reference

obligationobligationobligation stanza entryobligations-levels-mapping stanzaentriesobligationobligations-levels-mapping stanzaobligations-levels-mapping stanzaobligation entrySyntax <obligation> = <authentication-level> Description Defines the mappings between the obligation levels that the policy decision point (PDP) returns and the WebSEAL step-up authentication levels. Include a separate entry for each obligation that runtime security services (RTSS) returns to the runtime security services EAS.The mapping between the obligation levels and the WebSEAL authentication levels must be one-to-one. The user must authenticate only through the appropriate obligation mechanisms.The runtime security services EAS maps the obligation to the authentication level specified in this stanza and requests WebSEAL to authenticate the user at that level. Options <obligation>The name of the obligation that RTSS returns to the runtime security services EAS. <authentication-level>The WebSEAL authentication level that the runtime security services EAS includes in the WebSEAL request. This value is a number that represents the authentication level in the [authentication-levels] stanza. Each entry in the [authentication-levels] is assigned a number based on its position in the list; the first entry is level 0. For more information, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy and search for specifying authentication levels. Usage This stanza entry is required. Default value None. Example life_questions=2 otp=3 email=4 voice=5 [obligations-levels-mapping] stanza

obligation

Syntax

<obligation> = <authentication-level>

Description

Defines the mappings between the obligation levels that the policy decision point (PDP) returns and the WebSEAL step-up authentication levels. Include a separate entry for each obligation that runtime security services (RTSS) returns to the runtime security services EAS.

The mapping between the obligation levels and the WebSEAL authentication levels must be one-to-one. The user must authenticate only through the appropriate obligation mechanisms.

The runtime security services EAS maps the obligation to the authentication level specified in this stanza and requests WebSEAL to authenticate the user at that level.

Options

<obligation>

The name of the obligation that RTSS returns to the runtime security services EAS.

<authentication-level>

The WebSEAL authentication level that the runtime security services EAS includes in the WebSEAL request. This value is a number that represents the authentication level in the [authentication-levels] stanza. Each entry in the [authentication-levels] is assigned a number based on its position in the list; the first entry is level 0. For more information, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy and search for specifying authentication levels.

Usage

This stanza entry is required.

Default value

None.

Example

life_questions=2
otp=3
email=4
voice=5

Parent topic: [obligations-levels-mapping] stanza

[obligations-urls-mapping] stanza[obligations-urls-mapping] stanzaWebSEAL [obligations-urls-mapping] stanzaUse this stanza to define a URL to be used to satisfy an obligation.This stanza is not included in the WebSEAL configuration file by default. You can manually add this stanza and the associated entries if you want to configure runtime security services for Advanced Access Control.Stanza referenceobligationDefine a URL to be used to satisfy an obligation.

[obligations-urls-mapping] stanza

Use this stanza to define a URL to be used to satisfy an obligation.

Note: This stanza is not included in the WebSEAL configuration file by default. You can manually add this stanza and the associated entries if you want to configure runtime security services for Advanced Access Control.

obligation
Define a URL to be used to satisfy an obligation.

Parent topic: Stanza reference

obligationobligationobligation stanza entryDefine a URL to be used to satisfy an obligation.obligations-urls-mapping stanzaobligation entry Syntax obligation = URL Description This entry defines the mapping between the obligation that the policy decision point (PDP) returns and the URL that is used to satisfy the obligation. Options obligationDefines the obligation that is returned by runtime security services. This string, or key, is case-sensitive. URLDefines the URL that is used to satisfy the obligation. Usage This stanza entry is not required. The [obligations-urls-mapping] stanza and the obligation entry apply only to Advanced Access Control. Examples The following entry specifies an obligation named auth1. The value of auth1 is a URL that is used to satisfy the obligation. [obligations-urls-mapping] auth1 = https://example.com [obligations-urls-mapping] stanzaUse this stanza to define a URL to be used to satisfy an obligation.

obligation

Define a URL to be used to satisfy an obligation.

Syntax

obligation = URL

Description

This entry defines the mapping between the obligation that the policy decision point (PDP) returns and the URL that is used to satisfy the obligation.

Options

obligation

Defines the obligation that is returned by runtime security services. This string, or key, is case-sensitive.

URL

Defines the URL that is used to satisfy the obligation.

Usage

This stanza entry is not required.

The [obligations-urls-mapping] stanza and the obligation entry apply only to Advanced Access Control.

Examples

The following entry specifies an obligation named auth1. The value of auth1 is a URL that is used to satisfy the obligation.

[obligations-urls-mapping]
auth1 = https://example.com

Parent topic: [obligations-urls-mapping] stanza

[p3p-header] stanza[p3p-header] stanzap3p-header stanzastanzasp3p-headerStanza referenceaccessUse the access stanza entry to specify the type of cookie information that a user can access.categoriesUse the categories stanza entry to specify the type of information that is stored in the cookie or linked to by the cookie.disputesUse the disputes stanza entry to specify whether information about disputes is contained in the P3P policy.non-identifiablep3p-elementpurposerecipientremediesretention

[p3p-header] stanza

access
Use the access stanza entry to specify the type of cookie information that a user can access.

categories
Use the categories stanza entry to specify the type of information that is stored in the cookie or linked to by the cookie.

disputes
Use the disputes stanza entry to specify whether information about disputes is contained in the P3P policy.

non-identifiable

p3p-element

purpose

recipient

remedies

retention

Parent topic: Stanza reference

accessaccessIBM Security Access Manager for Web WebSEAL access stanza entryUse the access stanza entry to specify the type of cookie information that a user can access.access stanza entryp3p-header stanzaentriesaccessp3p-header stanzap3p-header stanzaaccess entrySyntax access = {none|all|nonident|contact-and-other|ident-contact|other-ident} Description Specifies the user access to the information contained in and linked to the cookie. Options noneNo access to identified data is given. allAccess is given to all identified data.contact-and-otherAccess is given to identified online and physical contact information, in addition to certain other identified data.ident-contactAccess is given to identified online and physical contact information. For example, users can access things such as a postal address. nonidentWebsite does not collect identified data. other-identAccess is given to certain other identified data. For example, users can access things such as their online account charges. Usage This stanza entry is required. Default value none Example access = none [p3p-header] stanza

access

Use the access stanza entry to specify the type of cookie information that a user can access.

Syntax

access = {none|all|nonident|contact-and-other|ident-contact|other-ident}

Description

Specifies the user access to the information contained in and linked to the cookie.

Options

none

No access to identified data is given.

all

Access is given to all identified data.

contact-and-other

Access is given to identified online and physical contact information, in addition to certain other identified data.

ident-contact

Access is given to identified online and physical contact information. For example, users can access things such as a postal address.

nonident

Website does not collect identified data.

other-ident

Access is given to certain other identified data. For example, users can access things such as their online account charges.

Usage

This stanza entry is required.

Default value

none

Example

access = none

Parent topic: [p3p-header] stanza

categoriescategoriesIBM Security Access Manager for Web WebSEAL categories stanza entryUse the categories stanza entry to specify the type of information that is stored in the cookie or linked to by the cookie.categories stanza entryp3p-header stanzaentriescategoriesp3p-header stanzap3p-header stanzacategories entrySyntax categories = {physical|online|uniqueid|purchase|financial|computer| navigation|interactive|demographic|content|state|political|health| preference|location|government|other-category} Description Specifies the type of information stored in the cookie or linked to by the cookie. When the non-identifiable stanza entry is set to yes, then no categories need be configured. Options physicalInformation that allows an individual to be contacted or located in the physical world. For example, telephone number or address.onlineInformation that allows an individual to be contacted or located on the Internet. uniqueidNon-financial identifiers, excluding government-issued identifiers, issued for purposes of consistently identifying or recognizing the individual.purchaseInformation actively generated by the purchase of a product or service, including information about the method of payment. financialInformation about an individual's finances including account status and activity information such as account balance, payment or overdraft history, and information about an individual's purchase or use of financial instruments including credit or debit card information. computerInformation about the computer system that the individual is using to access the network. For example, IP number, domain name, browser type or operating system. navigationData passively generated by browsing the Web site. For example, which pages are visited, and how long users stay on each page.interactiveData actively generated from or reflecting explicit interactions with a service provider through its site. For example, queries to a search engine, or logs of account activity. demographicData about an individual's characteristics. For example, gender, age, and income. contentThe words and expressions contained in the body of a communication. For example, the text of email, bulletin board postings, or chat room communications.stateMechanisms for maintaining a stateful session with a user or automatically recognizing users who have visited a particular site or accessed particular content previously. For example, HTTP cookies. politicalMembership in or affiliation with groups such as religious organizations, trade unions, professional associations and political parties. healthInformation about an individual's physical or mental health, sexual orientation, use or inquiry into health care services or products, and purchase of health care services or productspreferenceData about an individual's likes and dislikes. For example, favorite color or musical tastes.locationInformation that can be used to identify an individual's current physical location and track them as their location changes. For example, Global Positioning System position data.governmentIdentifiers issued by a government for purposes of consistently identifying the individual.other-categoryOther types of data not captured by the above definitions. Usage This stanza entry is required. Default value uniqueid Example categories = uniqueid [p3p-header] stanza

categories

Use the categories stanza entry to specify the type of information that is stored in the cookie or linked to by the cookie.

Syntax

categories = {physical|online|uniqueid|purchase|financial|computer|
navigation|interactive|demographic|content|state|political|health|
preference|location|government|other-category}

Description

Specifies the type of information stored in the cookie or linked to by the cookie. When the non-identifiable stanza entry is set to yes, then no categories need be configured.

Options

physical

Information that allows an individual to be contacted or located in the physical world. For example, telephone number or address.

online

Information that allows an individual to be contacted or located on the Internet.

uniqueid

Non-financial identifiers, excluding government-issued identifiers, issued for purposes of consistently identifying or recognizing the individual.

purchase

Information actively generated by the purchase of a product or service, including information about the method of payment.

financial

Information about an individual's finances including account status and activity information such as account balance, payment or overdraft history, and information about an individual's purchase or use of financial instruments including credit or debit card information.

computer

Information about the computer system that the individual is using to access the network. For example, IP number, domain name, browser type or operating system.

navigation

Data passively generated by browsing the Web site. For example, which pages are visited, and how long users stay on each page.

interactive

Data actively generated from or reflecting explicit interactions with a service provider through its site. For example, queries to a search engine, or logs of account activity.

demographic

Data about an individual's characteristics. For example, gender, age, and income.

content

The words and expressions contained in the body of a communication. For example, the text of email, bulletin board postings, or chat room communications.

state

Mechanisms for maintaining a stateful session with a user or automatically recognizing users who have visited a particular site or accessed particular content previously. For example, HTTP cookies.

political

Membership in or affiliation with groups such as religious organizations, trade unions, professional associations and political parties.

health

Information about an individual's physical or mental health, sexual orientation, use or inquiry into health care services or products, and purchase of health care services or products

preference

Data about an individual's likes and dislikes. For example, favorite color or musical tastes.

location

Information that can be used to identify an individual's current physical location and track them as their location changes. For example, Global Positioning System position data.

government

Identifiers issued by a government for purposes of consistently identifying the individual.

other-category

Other types of data not captured by the above definitions.

Usage

This stanza entry is required.

Default value

uniqueid

Example

categories = uniqueid

Parent topic: [p3p-header] stanza

disputesdisputesIBM Security Access Manager for Web WebSEAL disputes stanza entryUse the disputes stanza entry to specify whether information about disputes is contained in the P3P policy.disputes stanza entryp3p-header stanzaentriesdisputesp3p-header stanzap3p-header stanzadisputes entrySyntax disputes = {yes|no} Description Specifies whether the full P3P policy contains some information regarding disputes over the information contained within the cookie. Options yesThe value yes means that information about disputes is contained in the full P3P policy. noThe value no means that no information about disputes is contained in the policy. Usage This stanza entry is required. Default value no Example disputes = no [p3p-header] stanza

disputes

Use the disputes stanza entry to specify whether information about disputes is contained in the P3P policy.

Syntax

disputes = {yes|no}

Description

Specifies whether the full P3P policy contains some information regarding disputes over the information contained within the cookie.

Options

yes

The value yes means that information about disputes is contained in the full P3P policy.

no

The value no means that no information about disputes is contained in the policy.

Usage

This stanza entry is required.

Default value

no

Example

disputes = no

Parent topic: [p3p-header] stanza

non-identifiablenon-identifiablenon-identifiable stanza entryp3p-header stanzaentriesnon-identifiablep3p-header stanzap3p-header stanzanon-identifiable entrySyntax non-identifiable = {yes|no}Description Specifies that no information in the cookie, or linked to by the cookie, personally identifies the user.Options yesData that is collected identifies the user.noNo data is collected (including Web logs), or the information collected does not identify the user.Usage This stanza entry is required.Default value noExample non-identifiable = no[p3p-header] stanza

non-identifiable

Syntax

non-identifiable = {yes|no}

Description

Specifies that no information in the cookie, or linked to by the cookie, personally identifies the user.

Options

yes

Data that is collected identifies the user.

no

No data is collected (including Web logs), or the information collected does not identify the user.

Usage

This stanza entry is required.

Default value

no

Example

non-identifiable = no

Parent topic: [p3p-header] stanza

p3p-elementp3p-elementp3p-element stanza entryp3p-header stanzaentriesp3p-elementp3p-header stanzap3p-header stanzap3p-element entrySyntax p3p-element = policyref=location_of_policy_referenceDescription Specifies elements to add to the P3P header in addition to the elements specified by the other configuration items in this stanza. Typically this is done by referring to the location of a full XML policy.Options policyref=location_of_policy_referenceThe default entry points to a default policy reference located on the World Wide Web Consortium Web site.Usage This stanza entry is required.Default value The default entry points to a default policy reference located on the World Wide Web Consortium Web site. policyref="/w3c/p3p.xml"Example p3p-element = policyref="/w3c/p3p.xml"[p3p-header] stanza

p3p-element

Syntax

p3p-element = policyref=location_of_policy_reference

Description

Specifies elements to add to the P3P header in addition to the elements specified by the other configuration items in this stanza. Typically this is done by referring to the location of a full XML policy.

Options

policyref=location_of_policy_reference

The default entry points to a default policy reference located on the World Wide Web Consortium Web site.

Usage

This stanza entry is required.

Default value

The default entry points to a default policy reference located on the World Wide Web Consortium Web site.

policyref="/w3c/p3p.xml"

Example

p3p-element = policyref="/w3c/p3p.xml"

Parent topic: [p3p-header] stanza

purposepurposepurpose stanza entryp3p-header stanzaentriespurposep3p-header stanzap3p-header stanzapurpose entrySyntax purpose = {current|admin|develop|tailoring|pseudo-analysis| pseudo-decision|individual-analysis|individual-decision| contact|historical|telemarketing|other-purpose} [:[opt-in|opt-out|always]] Description Specifies the purpose of the information in the cookie and linked to by the cookie. Options currentInformation can be used by the service provider to complete the activity for which it was provided.adminInformation can be used for the technical support of the Web site and its computer system. developInformation can be used to enhance, evaluate, or otherwise review the site, service, product, or market. tailoringInformation can be used to tailor or modify content or design of the site where the information is used only for a single visit to the site.pseudo-analysisInformation can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data (such as name, address, phone number, or email address) to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals for purpose of research, analysis and reporting, but it will not be used to attempt to identify specific individuals.pseudo-decisionInformation can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data (such as name, address, phone number, or email address) to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals to make a decision that directly affects that individual, but it will not be used to attempt to identify specific individuals. individual-analysisInformation can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data for the purpose of research, analysis and reporting. individual-decisionInformation can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data to make a decision that directly affects that individual. contactInformation can be used to contact the individual, through a communications channel other than voice telephone, for the promotion of a product or service. historicalInformation can be archived or stored for the purpose of preserving social history as governed by an existing law or policy. telemarketingInformation can be used to contact the individual though a voice telephone call for promotion of a product or service. other-purposeInformation may be used in other ways not captured by the above definitions. For all values except current, an additional option can be specified. The possible values are: alwaysUsers cannot opt-in or opt-out of this use of their data.opt-inData may be used for this purpose only when the user affirmatively requests this use.opt-outData may be used for this purpose unless the user requests that it not be used in this way. When no additional option is specified, the default value is always. Usage This stanza entry is required. Default value The default values are current and other-purpose:opt-in. Example purpose = current purpose = other-purpose:opt-in [p3p-header] stanza

purpose

Syntax

purpose = {current|admin|develop|tailoring|pseudo-analysis|
pseudo-decision|individual-analysis|individual-decision|
contact|historical|telemarketing|other-purpose}
[:[opt-in|opt-out|always]]

Description

Specifies the purpose of the information in the cookie and linked to by the cookie.

Options

current

Information can be used by the service provider to complete the activity for which it was provided.

admin

Information can be used for the technical support of the Web site and its computer system.

develop

Information can be used to enhance, evaluate, or otherwise review the site, service, product, or market.

tailoring

Information can be used to tailor or modify content or design of the site where the information is used only for a single visit to the site.

pseudo-analysis

Information can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data (such as name, address, phone number, or email address) to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals for purpose of research, analysis and reporting, but it will not be used to attempt to identify specific individuals.

pseudo-decision

Information can be used to create or build a record of a particular individual or computer that is tied to a pseudonymous identifier, without tying identified data (such as name, address, phone number, or email address) to the record. This profile will be used to determine the habits, interests, or other characteristics of individuals to make a decision that directly affects that individual, but it will not be used to attempt to identify specific individuals.

individual-analysis

Information can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data for the purpose of research, analysis and reporting.

individual-decision

Information can be used to determine the habits, interests, or other characteristics of individuals and combine it with identified data to make a decision that directly affects that individual.

contact

Information can be used to contact the individual, through a communications channel other than voice telephone, for the promotion of a product or service.

historical

Information can be archived or stored for the purpose of preserving social history as governed by an existing law or policy.

telemarketing

Information can be used to contact the individual though a voice telephone call for promotion of a product or service.

other-purpose

Information may be used in other ways not captured by the above definitions.

For all values except current, an additional option can be specified. The possible values are:

always

Users cannot opt-in or opt-out of this use of their data.

opt-in

Data may be used for this purpose only when the user affirmatively requests this use.

opt-out

Data may be used for this purpose unless the user requests that it not be used in this way.

When no additional option is specified, the default value is always.

Usage

This stanza entry is required.

Default value

The default values are current and other-purpose:opt-in.

Example

purpose = current
purpose = other-purpose:opt-in

Parent topic: [p3p-header] stanza

recipientrecipientrecipient stanza entryp3p-header stanzaentriesrecipientp3p-header stanzap3p-header stanzarecipient entrySyntax recipient = {ours|delivery|same|unrelated|public| other-recipient}[:[opt-in|opt-out|always]] Description Specifies the recipients of the information in the cookie, and linked to by the cookie. Options oursOurselves and/or entities acting as our agents, or entities for whom we are acting as an agent. An agent is a third party that processes data only on behalf of the service provider. deliveryLegal entities performing delivery services that may use data for purposes other than completion of the stated purpose.sameLegal entities following our practices. These are legal entities who use the data on their own behalf under equable practices.unrelatedUnrelated third parties. These are legal entities whose data usage practices are not known by the original service provider.publicPublic forums. These are public forums such as bulletin boards, public directories, or commercial CD-ROM directories. other-recipientLegal entities following different practices. These are legal entities that are constrained by and accountable to the original service provider, but may use the data in a way not specified in the service provider's practices. For all values an additional option can be specified. The possible values are: alwaysUsers cannot opt-in or opt-out of this use of their data.opt-inData may be used for this purpose only when the user affirmatively requests this use.opt-outData may be used for this purpose unless the user requests that it not be used in this way. When no additional option is specified, the default value is always. Usage This stanza entry is required. Default value ours Example recipient = ours recipient = public:opt-in [p3p-header] stanza

recipient

Syntax

recipient = {ours|delivery|same|unrelated|public|
other-recipient}[:[opt-in|opt-out|always]]

Description

Specifies the recipients of the information in the cookie, and linked to by the cookie.

Options

ours

Ourselves and/or entities acting as our agents, or entities for whom we are acting as an agent. An agent is a third party that processes data only on behalf of the service provider.

delivery

Legal entities performing delivery services that may use data for purposes other than completion of the stated purpose.

same

Legal entities following our practices. These are legal entities who use the data on their own behalf under equable practices.

unrelated

Unrelated third parties. These are legal entities whose data usage practices are not known by the original service provider.

public

Public forums. These are public forums such as bulletin boards, public directories, or commercial CD-ROM directories.

other-recipient

Legal entities following different practices. These are legal entities that are constrained by and accountable to the original service provider, but may use the data in a way not specified in the service provider's practices.

For all values an additional option can be specified. The possible values are:

always

Users cannot opt-in or opt-out of this use of their data.

opt-in

Data may be used for this purpose only when the user affirmatively requests this use.

opt-out

Data may be used for this purpose unless the user requests that it not be used in this way.

When no additional option is specified, the default value is always.

Usage

This stanza entry is required.

Default value

ours

Example

recipient = ours
recipient = public:opt-in

Parent topic: [p3p-header] stanza

remediesremediesremedies stanza entryp3p-header stanzaentriesremediesp3p-header stanzap3p-header stanzaremedies entrySyntax remedies = {correct|money|law}Description Specifies the types of remedies in case a policy breach occurs. When this entry has no value, there is no remedy information in the P3P compact policy.Options correctErrors or wrongful actions arising in connection with the privacy policy will be remedied by the service. moneyIf the service provider violates its privacy policy it will pay the individual an amount specified in the human readable privacy policy or the amount of damages. lawRemedies for breaches of the policy statement will be determined based on the law referenced in the human readable description.Usage This stanza entry is required.Default value correctExample remedies = correct[p3p-header] stanza

remedies

Syntax

remedies = {correct|money|law}

Description

Specifies the types of remedies in case a policy breach occurs. When this entry has no value, there is no remedy information in the P3P compact policy.

Options

correct

Errors or wrongful actions arising in connection with the privacy policy will be remedied by the service.

money

If the service provider violates its privacy policy it will pay the individual an amount specified in the human readable privacy policy or the amount of damages.

law

Remedies for breaches of the policy statement will be determined based on the law referenced in the human readable description.

Usage

This stanza entry is required.

Default value

correct

Example

remedies = correct

Parent topic: [p3p-header] stanza

retentionretentionretention stanza entryp3p-header stanzaentriesretentionp3p-header stanzap3p-header stanzaretention entrySyntax retention = {no-retention|stated-purpose|legal-requirement| business-practices|indefinitely}Description Specifies how long the information in the cookie or linked to by the cookie is retained. Options no-retentionInformation is not retained for more than a brief period of time necessary to make use of it during the course of a single online interaction.stated-purposeInformation is retained to meet the stated purpose, and is to be discarded at the earliest time possible. legal-requirementInformation is retained to meet a stated purpose, but the retention period is longer because of a legal requirement or liability.business-practicesInformation is retained under a service provider's stated business practices.indefinitelyInformation is retained for an indeterminate period of time.Usage This stanza entry is required.Default value no-retentionExample retention = no-retention[p3p-header] stanza

retention

Syntax

retention = {no-retention|stated-purpose|legal-requirement|
business-practices|indefinitely}

Description

Specifies how long the information in the cookie or linked to by the cookie is retained.

Options

no-retention

Information is not retained for more than a brief period of time necessary to make use of it during the course of a single online interaction.

stated-purpose

Information is retained to meet the stated purpose, and is to be discarded at the earliest time possible.

legal-requirement

Information is retained to meet a stated purpose, but the retention period is longer because of a legal requirement or liability.

business-practices

Information is retained under a service provider's stated business practices.

indefinitely

Information is retained for an indeterminate period of time.

Usage

This stanza entry is required.

Default value

no-retention

Example

retention = no-retention

Parent topic: [p3p-header] stanza

[PAM] stanza[PAM] stanzaPAM stanzastanzasPAMStanza referencepam-enabledpam-simulation-mode-enabledpam-max-memorypam-use-proxy-headerpam-http-parameterpam-coalescer-parameterpam-log-cfgpam-log-audit-eventspam-disabled-issuespam-resource-rule

[PAM] stanza

pam-enabled

pam-simulation-mode-enabled

pam-max-memory

pam-use-proxy-header

pam-http-parameter

pam-coalescer-parameter

pam-log-cfg

pam-log-audit-events

pam-disabled-issues

pam-resource-rule

Parent topic: Stanza reference

pam-enabledpam-enabledpam-enabled stanza entryPAM stanzaentriespam-enabledPAM stanzaPAM stanzapam-enabled entrySyntax pam-enabled = {true|false} Description Enables or disables the IBM Internet Security Systems Protocol Analysis Module. The module inspects the HTTP content of selected requests, checking for potential security vulnerabilities. Options trueEnables the Protocol Analysis Module.falseDisables the Protocol Analysis Module. Usage This stanza entry is required. Default value false Example pam-enabled = false [PAM] stanza

pam-enabled

Syntax

pam-enabled = {true|false}

Description

Enables or disables the IBM Internet Security Systems Protocol Analysis Module. The module inspects the HTTP content of selected requests, checking for potential security vulnerabilities.

Options

true

Enables the Protocol Analysis Module.

false

Disables the Protocol Analysis Module.

Usage

This stanza entry is required.

Default value

false

Example

pam-enabled = false

Parent topic: [PAM] stanza

pam-simulation-mode-enabledpam-simulation-mode-enabledpam-simulation-mode-enabled stanza entryPAM stanzaentriespam-simulation-mode-enabledPAM stanzaPAM stanzapam-simulation-mode-enabled entrySyntax pam-simulation-mode-enabled = {true|false} Description Enables or disables the IBM Internet Security Systems Protocol Analysis Module simulation mode. If the simulation mode is enabled, any issues that are detected are audited and then ignored. This mode provides a mechanism for administrators to see what issues are being detected without having an impact on the client traffic. Options trueEnables the Protocol Analysis Module simulation mode.falseDisables the Protocol Analysis Module simulation mode. Usage This stanza entry is required. Default value false Example pam-simulation-mode-enabled = false [PAM] stanza

pam-simulation-mode-enabled

Syntax

pam-simulation-mode-enabled = {true|false}

Description

Enables or disables the IBM Internet Security Systems Protocol Analysis Module simulation mode. If the simulation mode is enabled, any issues that are detected are audited and then ignored. This mode provides a mechanism for administrators to see what issues are being detected without having an impact on the client traffic.

Options

true

Enables the Protocol Analysis Module simulation mode.

false

Disables the Protocol Analysis Module simulation mode.

Usage

This stanza entry is required.

Default value

false

Example

pam-simulation-mode-enabled = false

Parent topic: [PAM] stanza

pam-max-memorypam-max-memorypam-max-memory stanza entryPAM stanzaentriespam-max-memoryPAM stanzaPAM stanzapam-max-memory entrySyntax pam-max-memory = memory_size Description The amount of memory, in bytes, that the IBM Internet Security Systems Protocol Analysis Module can use. The module uses this value to tune the size of its caches for the amount of available memory. Options memory_size The amount of memory, in bytes, that is available to the module. Usage This stanza entry is optional. Default value None. Example pam-max-memory = 16777216 [PAM] stanza

pam-max-memory

Syntax

pam-max-memory = memory_size

Description

The amount of memory, in bytes, that the IBM Internet Security Systems Protocol Analysis Module can use. The module uses this value to tune the size of its caches for the amount of available memory.

Options

memory_size

The amount of memory, in bytes, that is available to the module.

Usage

This stanza entry is optional.

Default value

None.

Example

pam-max-memory = 16777216

Parent topic: [PAM] stanza

pam-use-proxy-headerpam-use-proxy-headerpam-use-proxy-header stanza entryPAM stanzaentriespam-use-proxy-headerPAM stanzaPAM stanzapam-use-proxy-header entrySyntax pam-use-proxy-header = {true|false} Description Controls whether the Protocol Analysis Module uses the X-Forwarded-For header to identify the client. This configuration item is useful if a network-terminating proxy is located between the server and the client. If the value is set to false, the module identifies the client based on the socket connection information. Options trueThe module uses the X-Forwarded-For header to identify the client.falseThe module uses the available socket connection information to identify the client. Usage This stanza entry is required. Default value false Example pam-use-proxy-header = false [PAM] stanza

pam-use-proxy-header

Syntax

pam-use-proxy-header = {true|false}

Description

Controls whether the Protocol Analysis Module uses the X-Forwarded-For header to identify the client. This configuration item is useful if a network-terminating proxy is located between the server and the client. If the value is set to false, the module identifies the client based on the socket connection information.

Options

true

The module uses the X-Forwarded-For header to identify the client.

false

The module uses the available socket connection information to identify the client.

Usage

This stanza entry is required.

Default value

false

Example

pam-use-proxy-header = false

Parent topic: [PAM] stanza

pam-http-parameterpam-http-parameterpam-http-parameter stanza entryPAM stanzaentriespam-http-parameterPAM stanzaPAM stanzapam-http-parameter entrySyntax pam-http-parameter = parameter:value Description Defines specific parameters for WebSEAL to pass to the Protocol Analysis Module HTTP interface during initialization. For a list of valid Protocol Analysis Module parameters, see the module documentation at http://www.iss.net/security_center/reference/help/pam.You can specify this configuration entry multiple times, one for each parameter. Options parameter:valueThe Protocol Analysis Module parameter and its assigned value. Usage This stanza entry is optional. Default value None. Example pam-http-parameter = param1:val1 pam-http-parameter = param2:val2 [PAM] stanza

pam-http-parameter

Syntax

pam-http-parameter = parameter:value

Description

Defines specific parameters for WebSEAL to pass to the Protocol Analysis Module HTTP interface during initialization. For a list of valid Protocol Analysis Module parameters, see the module documentation at http://www.iss.net/security_center/reference/help/pam.

Note: You can specify this configuration entry multiple times, one for each parameter.

Options

parameter:value

The Protocol Analysis Module parameter and its assigned value.

Usage

This stanza entry is optional.

Default value

None.

Example

pam-http-parameter = param1:val1
pam-http-parameter = param2:val2

Parent topic: [PAM] stanza

pam-coalescer-parameterpam-coalescer-parameterpam-coalescer-parameter stanza entryPAM stanzaentriespam-coalescer-parameterPAM stanzaPAM stanzapam-coalescer-parameter entrySyntax pam-coalescer-parameter = parameter:value Description Defines specific parameters for WebSEAL to pass to the Protocol Analysis Module coalescer interface during initialization. The Protocol Analysis Module uses this interface to combine module-related issues into a single event. For a list of valid Protocol Analysis Module parameters, see the module documentation at http://www.iss.net/security_center/reference/help/pam.You can specify this configuration entry multiple times, one for each parameter. Options parameter:valueThe Protocol Analysis Module parameter and its assigned value. Usage This stanza entry is optional. Default value None. Example pam-coalescer-parameter = combine:on [PAM] stanza

pam-coalescer-parameter

Syntax

pam-coalescer-parameter = parameter:value

Description

Defines specific parameters for WebSEAL to pass to the Protocol Analysis Module coalescer interface during initialization. The Protocol Analysis Module uses this interface to combine module-related issues into a single event. For a list of valid Protocol Analysis Module parameters, see the module documentation at http://www.iss.net/security_center/reference/help/pam.

Note: You can specify this configuration entry multiple times, one for each parameter.

Options

parameter:value

The Protocol Analysis Module parameter and its assigned value.

Usage

This stanza entry is optional.

Default value

None.

Example

pam-coalescer-parameter = combine:on

Parent topic: [PAM] stanza

pam-log-cfgpam-log-cfgpam-log-cfg stanza entrylogging stanzaentriespam-log-cfglogging stanzalogging stanzapam-log-cfg entrySyntax pam-log-cfg = agent [parameter=value],[parameter=value]...Description Configures the IBM Internet Security Systems Protocol Analysis Module for logging. You can use the available parameters to configure the logging agents. Options agentSpecifies the logging agent. The agent controls the logging destination for server events. Valid agents include:stdoutstderrfileremotersyslogparameterThe different agents support the following configuration parameters:Logging agent configuration parametersParameterSupporting agentsbuffer_sizeremotecompressremotednremoteerror_retryremote, rsyslogflush_intervalallhi_wateralllog_idfile, rsyslogmax_event_lenrsyslogmodefilepathallportremote, rsyslogqueue_sizeallrebind_retryremote, rsyslogrollover_sizefileserverremote, rsyslogssl_keyfilersyslogssl_labelrsyslogssl_stashfilersyslogFor a complete description of the available logging agents and the supported configuration parameters, see the IBM Security Access Manager for Web: Auditing Guide. Usage This stanza entry is required. Default value None. Example To send logging from the Protocol Analysis Module to a file called pam.log: pam-log-cfg = file path=pam.logTo send logging from the module to a remote syslog server: pam-log-cfg = rsyslog server=timelord,port=514,log_id=webseal-instance [PAM] stanza

pam-log-cfg

Syntax

pam-log-cfg = agent [parameter=value],[parameter=value]...

Description

Configures the IBM Internet Security Systems Protocol Analysis Module for logging. You can use the available parameters to configure the logging agents.

Options

agent

Specifies the logging agent. The agent controls the logging destination for server events. Valid agents include:

stdout

stderr

file

remote

rsyslog

parameter

The different agents support the following configuration parameters:

Table 314. Logging agent configuration parameters

Parameter | Supporting agents
buffer_size | remote
compress | remote
dn | remote
error_retry | remote, rsyslog
flush_interval | all
hi_water | all
log_id | file, rsyslog
max_event_len | rsyslog
mode | file
path | all
port | remote, rsyslog
queue_size | all
rebind_retry | remote, rsyslog
rollover_size | file
server | remote, rsyslog
ssl_keyfile | rsyslog
ssl_label | rsyslog
ssl_stashfile | rsyslog

Note: For a complete description of the available logging agents and the supported configuration parameters, see the IBM Security Access Manager for Web: Auditing Guide.

Usage

This stanza entry is required.

Default value

None.

Example

To send logging from the Protocol Analysis Module to a file called pam.log:

pam-log-cfg = file path=pam.log

To send logging from the module to a remote syslog server:

pam-log-cfg = rsyslog server=timelord,port=514,log_id=webseal-instance

Parent topic: [PAM] stanza

pam-log-audit-eventspam-log-audit-eventspam-log-audit-events stanza entryPAM stanzaentriespam-log-audit-eventsPAM stanzaPAM stanzapam-log-audit-events entrySyntax pam-log-audit-events = {true|false} Description Specifies whether audit events are sent to the Protocol Analysis Module log file. You can use the pam-log-cfg entry in the [PAM] stanza to configure the log file for the module. Options trueThe Protocol Analysis Module sends audit events to the log file.This setting dramatically increases the number of logged events.falseThe Protocol Analysis Module does not send audit events to the log file. Usage This stanza entry is required. Default value false Example pam-log-audit-events = false [PAM] stanza

pam-log-audit-events

Syntax

pam-log-audit-events = {true|false}

Description

Specifies whether audit events are sent to the Protocol Analysis Module log file.

Note: You can use the pam-log-cfg entry in the [PAM] stanza to configure the log file for the module.

Options

true

The Protocol Analysis Module sends audit events to the log file.

Note: This setting dramatically increases the number of logged events.

false

The Protocol Analysis Module does not send audit events to the log file.

Usage

This stanza entry is required.

Default value

false

Example

pam-log-audit-events = false

Parent topic: [PAM] stanza

pam-disabled-issuespam-disabled-issuespam-disabled-issues stanza entryPAM stanzaentriespam-disabled-issuesPAM stanzaPAM stanzapam-disabled-issues entrySyntax pam-disabled-issues = list_of_issues Description Specifies a comma-separated list of Protocol Analysis Module issues to disable. By default, all Protocol Analysis Module issues are enabled. Options list_of_issuesA comma-separated list of Protocol Analysis Module issues. The module disables each issue in the list. Usage This stanza entry is optional. Default value None. Example The following entry disables Ace_Filename_Overflow and HTTPS_Apache_ClearText_DoS.pam-disabled-issues = 2121050,2114033 [PAM] stanza

pam-disabled-issues

Syntax

pam-disabled-issues = list_of_issues

Description

Specifies a comma-separated list of Protocol Analysis Module issues to disable. By default, all Protocol Analysis Module issues are enabled.

Options

list_of_issues

A comma-separated list of Protocol Analysis Module issues. The module disables each issue in the list.

Usage

This stanza entry is optional.

Default value

None.

Example

The following entry disables Ace_Filename_Overflow and HTTPS_Apache_ClearText_DoS.

pam-disabled-issues = 2121050,2114033

Parent topic: [PAM] stanza

pam-resource-rulepam-resource-rulepam-resource-rule entryPAM stanzaentriespam-resource-rulePAM stanzaPAM stanzapam-resource-rule entrySyntax pam-resource-rule = [+|-]{URI} Description Specifies the rules that WebSEAL uses to determine whether to pass a particular resource down to the Protocol Analysis Module. WebSEAL examines each rule in sequence until a match is found. The first successful match determines whether WebSEAL passes the request to the module. WebSEAL does not pass the request to the module layer if no match is found. You can define multiple resource rules. Each entry has the format: [+|-]{URI}. For example, -*.gif. Options +Configures WebSEAL to pass matching requests to the Protocol Analysis Module layer.-Configures WebSEAL not to pass matching requests to the Protocol Analysis Module layer. {URI}Contains a pattern that WebSEAL uses to match against the URI that is found in the request. You can use the wildcard characters * and ?. Usage This stanza entry is optional. Default value None. Examplepam-resource-rule = -*.gif pam-resource-rule = +*.html [PAM] stanza

pam-resource-rule

Syntax

pam-resource-rule = [+|-]{URI}

Description

Specifies the rules that WebSEAL uses to determine whether to pass a particular resource down to the Protocol Analysis Module. WebSEAL examines each rule in sequence until a match is found. The first successful match determines whether WebSEAL passes the request to the module. WebSEAL does not pass the request to the module layer if no match is found.

You can define multiple resource rules. Each entry has the format: [+|-]{URI}. For example, -*.gif.

Options

+

Configures WebSEAL to pass matching requests to the Protocol Analysis Module layer.

-

Configures WebSEAL not to pass matching requests to the Protocol Analysis Module layer.

{URI}

Contains a pattern that WebSEAL uses to match against the URI that is found in the request. You can use the wildcard characters * and ?.

Usage

This stanza entry is optional.

Default value

None.

Example

pam-resource-rule = -*.gif
pam-resource-rule = +*.html

Parent topic: [PAM] stanza

[pam-resource:<URI>] stanza[pam-resource:<URI>] stanzapam-resource: URI stanzastanzaspam-resource:URI<URI>You can use this stanza to customize the Protocol Analysis Module processing for individual resources and events. The <URI> value contains a pattern that WebSEAL can match against the URI that is found in the request. You can use the wildcard characters * and ?. For example, [pam-resource:test.html] or [pam-resource:*.js].Stanza referencepam-issue

[pam-resource:<URI>] stanza

You can use this stanza to customize the Protocol Analysis Module processing for individual resources and events. The <URI> value contains a pattern that WebSEAL can match against the URI that is found in the request. You can use the wildcard characters * and ?. For example, [pam-resource:test.html] or [pam-resource:*.js].

pam-issue

Parent topic: Stanza reference

pam-issuepam-issuepam-issue stanza entrypam-resource: URI stanzaURI stanzaentriespam-issuepam-resource:URI stanzapam-resource: URI stanza pam-issue entrySyntax pam-issue = action Description You can use the entries in this stanza to control the processing of certain module-related events. Options pam-issueContains a pattern, which WebSEAL uses to match a Protocol Analysis Module issue. You can use the wildcard characters * and ?.actionThe action to undertake for the issue. The action can be either of the following values: blockBlocks the connection for a specified number of seconds. For example, block:30.ignoreIgnores the issue and continues to process the request. Usage This stanza entry is required. Default value None. Example 212105? = block:0 2119002 = block:20 [pam-resource:<URI>] stanza

pam-issue

Syntax

pam-issue = action

Description

You can use the entries in this stanza to control the processing of certain module-related events.

Options

pam-issue

Contains a pattern, which WebSEAL uses to match a Protocol Analysis Module issue. You can use the wildcard characters * and ?.

action

The action to undertake for the issue. The action can be either of the following values:

block

Blocks the connection for a specified number of seconds. For example, block:30.

ignore

Ignores the issue and continues to process the request.

Usage

This stanza entry is required.

Default value

None.

Example

212105? = block:0
2119002 = block:20

Parent topic: [pam-resource:<URI>] stanza

[password-strength] stanza[password-strength] stanza[password-strength] stanzaUse the [password-strength] stanza to define settings for the password strength module.password-strength stanzastanzaspassword-strengthThe password strength module validates the strength of new passwords. This module is invoked by a password change operation. It evaluates the new password against an XSLT rule to determine whether the new password meets the configured criteria.Stanza referencerules-fileUse the rules-file stanza entry to define the name of the rules file to be used by the password strength module.debug-levelUse the debug-level stanza entry to define the initial tracing level of the password strength module.

[password-strength] stanza

Use the [password-strength] stanza to define settings for the password strength module.

The password strength module validates the strength of new passwords. This module is invoked by a password change operation. It evaluates the new password against an XSLT rule to determine whether the new password meets the configured criteria.

rules-file
Use the rules-file stanza entry to define the name of the rules file to be used by the password strength module.

debug-level
Use the debug-level stanza entry to define the initial tracing level of the password strength module.

Parent topic: Stanza reference

rules-filerules-filerules-file stanza entryUse the rules-file stanza entry to define the name of the rules file to be used by the password strength module.rules-file stanza entrypassword-strength stanzaentriesrules-filepassword-strength stanzapassword-strength stanzarules-file entrySyntax rules-file = file-nameDescription The name of the rules file that is used by the password strength module.Options file-nameName of the rules file.Usage This stanza entry is required.Default value None.Example rules-file = password-rules.txt[password-strength] stanzaUse the [password-strength] stanza to define settings for the password strength module.

rules-file

Use the rules-file stanza entry to define the name of the rules file to be used by the password strength module.

Syntax

rules-file = file-name

Description

The name of the rules file that is used by the password strength module.

Options

file-name

Name of the rules file.

Usage

This stanza entry is required.

Default value

None.

Example

rules-file = password-rules.txt

Parent topic: [password-strength] stanza

debug-leveldebug-leveldebug-level stanza entryUse the debug-level stanza entry to define the initial tracing level of the password strength module.debug-level stanza entrypassword-strength stanzaentriesdebug-levelpassword-strength stanzapassword-strength stanzadebug-level entrySyntax debug-level = levelDescription Controls the initial trace level for the password strength module.Options levelThe level variable that indicates the trace level of the password strength module, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing.You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.pwdstrength. This trace component is only available after the first password change operation is processed. Usage This stanza entry is optional.Default value 0 A debug level of 0 results in no tracing output.Example debug-level = 0[password-strength] stanzaUse the [password-strength] stanza to define settings for the password strength module.

debug-level

Use the debug-level stanza entry to define the initial tracing level of the password strength module.

Syntax

debug-level = level

Description

Controls the initial trace level for the password strength module.

Options

level

The level variable that indicates the trace level of the password strength module, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing.

Note: You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.pwdstrength. This trace component is only available after the first password change operation is processed.

Usage

This stanza entry is optional.

Default value

0

Note: A debug level of 0 results in no tracing output.

Example

debug-level = 0

Parent topic: [password-strength] stanza

[preserve-cookie-names] stanza[preserve-cookie-names] stanzapreserve-cookie-names stanzastanzaspreserve-cookie-namesStanza referencenameUse the name entry in the [preserve-cookie-names] stanza to list specific cookie names that WebSEAL must not modify.

[preserve-cookie-names] stanza

name
Use the name entry in the [preserve-cookie-names] stanza to list specific cookie names that WebSEAL must not modify.

Parent topic: Stanza reference

namenameIBM Security Access Manager for Web WebSEAL name stanza entryUse the name entry in the [preserve-cookie-names] stanza to list specific cookie names that WebSEAL must not modify. name stanza entrypreserve-cookie-names stanzaentriesnamepreserve-cookie-names stanzapreserve-cookie-names stanzaname entrySyntax name = cookie_name Description WebSEAL, by default, modifies the names of cookies returned in responses from junctions created with pdadmin using –j flag. WebSEAL also by default modifies the name of cookies listed in the junction mapping table (JMT). This default modification is done to prevent naming conflicts with cookies returned by other junctions. When a front-end application depends on the names of specific cookies, the administrator can disable the modification of cookie names for those specific cookies. The administrator does this by listing the cookies in this stanza.You can configure more than one name entry to list multiple cookie names that WebSEAL must not modify. Options cookie_nameWhen entering a value for cookie_name, use ASCII characters. Usage This stanza entry is optional. Default value There are no cookie names set by default. Example name = JSESSIONID [preserve-cookie-names] stanza

name

Use the name entry in the [preserve-cookie-names] stanza to list specific cookie names that WebSEAL must not modify.

Syntax

name = cookie_name

Description

WebSEAL, by default, modifies the names of cookies returned in responses from junctions created with pdadmin using –j flag. WebSEAL also by default modifies the name of cookies listed in the junction mapping table (JMT). This default modification is done to prevent naming conflicts with cookies returned by other junctions.

When a front-end application depends on the names of specific cookies, the administrator can disable the modification of cookie names for those specific cookies. The administrator does this by listing the cookies in this stanza.

Note: You can configure more than one name entry to list multiple cookie names that WebSEAL must not modify.

Options

cookie_name

When entering a value for cookie_name, use ASCII characters.

Usage

This stanza entry is optional.

Default value

There are no cookie names set by default.

Example

name = JSESSIONID

Parent topic: [preserve-cookie-names] stanza

[process-root-filter] stanza[process-root-filter] stanzaprocess-root-filter stanzastanzasprocess-root-filterStanza referenceroot

[process-root-filter] stanza

root

Parent topic: Stanza reference

rootrootroot stanza entryprocess-root-filter stanzaentriesrootprocess-root-filter stanzaprocess-root-filter stanzaroot entrySyntax root = patternDescription Specifies the patterns for which you want root junction requests processed at the root junction when process-root-requests = filter. Options patternValues for pattern must be standard WebSEAL wildcard patterns.Usage Entries in this stanza are required when process-root-requests = filter.Default value root = /index.html root = /cgi-bin*Example root = /index.html root = /cgi-bin*[process-root-filter] stanza

root

Syntax

root = pattern

Description

Specifies the patterns for which you want root junction requests processed at the root junction when process-root-requests = filter.

Options

pattern

Values for pattern must be standard WebSEAL wildcard patterns.

Usage

Entries in this stanza are required when process-root-requests = filter.

Default value

root = /index.html
root = /cgi-bin*

Example

root = /index.html
root = /cgi-bin*

Parent topic: [process-root-filter] stanza

[reauthentication] stanza[reauthentication] stanzareauthentication stanzastanzasreauthenticationStanza referencereauth-at-any-levelreauth-extend-lifetimereauth-for-inactivereauth-reset-lifetimeterminate-on-reauth-lockout

[reauthentication] stanza

reauth-at-any-level

reauth-extend-lifetime

reauth-for-inactive

reauth-reset-lifetime

terminate-on-reauth-lockout

Parent topic: Stanza reference

reauth-at-any-levelreauth-at-any-levelreauth-at-any-level stanza entryreauthentication stanzaentriesreauth-at-any-levelreauthentication stanzareauthentication stanzareauth-at-any-level entrySyntax reauth-at-any-level = {yes|no}Description Controls whether a different authentication level or mechanism is permitted during a reauthentication operation.Options yes During a reauthentication operation, a user can be authenticated using a different authentication level or mechanism from that which is currently held by the user. The user's new credential replaces the old one. If this configuration option is set to yes, the credential can change one or more times during the lifetime of the session. Also, the credential will always be updated upon a successful reauthentication regardless of the existing authentication level of the credential.noDuring a reauthentication operation, a user can only be authenticated at the same authentication level or mechanism as the user's current credential.Usage This stanza entry is required.Default value noExample reauth-at-any-level = no[reauthentication] stanza

reauth-at-any-level

Syntax

reauth-at-any-level = {yes|no}

Description

Controls whether a different authentication level or mechanism is permitted during a reauthentication operation.

Options

yes

During a reauthentication operation, a user can be authenticated using a different authentication level or mechanism from that which is currently held by the user. The user's new credential replaces the old one.

Note: If this configuration option is set to yes, the credential can change one or more times during the lifetime of the session. Also, the credential will always be updated upon a successful reauthentication regardless of the existing authentication level of the credential.

no

During a reauthentication operation, a user can only be authenticated at the same authentication level or mechanism as the user's current credential.

Usage

This stanza entry is required.

Default value

no

Example

reauth-at-any-level = no

Parent topic: [reauthentication] stanza

reauth-extend-lifetimereauth-extend-lifetimereauth-extend-lifetime stanza entryreauthentication stanzaentriesreauth-extend-lifetimereauthentication stanzareauthentication stanzareauth-extend-lifetime entrySyntax reauth-extend-lifetime = number_of_secondsDescription Integer value expressing the time in seconds that the credential cache timer should be extended to allow clients to complete a reauthentication.Options number_of_secondsWhen the value is zero (0), the lifetime timer is not extended. WebSEAL imposes no maximum. The maximum value is limited only by the integer data type. Usage This stanza entry is required.Default value 0Example reauth-extend-lifetime = 0[reauthentication] stanza

reauth-extend-lifetime

Syntax

reauth-extend-lifetime = number_of_seconds

Description

Integer value expressing the time in seconds that the credential cache timer should be extended to allow clients to complete a reauthentication.

Options

number_of_seconds

When the value is zero (0), the lifetime timer is not extended. WebSEAL imposes no maximum. The maximum value is limited only by the integer data type.

Usage

This stanza entry is required.

Default value

0

Example

reauth-extend-lifetime = 0

Parent topic: [reauthentication] stanza

reauth-for-inactivereauth-for-inactivereauth-for-inactive stanza entryreauthentication stanzaentriesreauth-for-inactivereauthentication stanzareauthentication stanzareauth-for-inactive entrySyntax reauth-for-inactive = {yes|no}Description Enables WebSEAL to prompt users to reauthenticate when their entry in the WebSEAL credential cache has timed out due to inactivity.Options yesEnable reauthentication.noDisable reauthentication.Usage This stanza entry is required.Default value noExample reauth-for-inactive = no[reauthentication] stanza

reauth-for-inactive

Syntax

reauth-for-inactive = {yes|no}

Description

Enables WebSEAL to prompt users to reauthenticate when their entry in the WebSEAL credential cache has timed out due to inactivity.

Options

yes

Enable reauthentication.

no

Disable reauthentication.

Usage

This stanza entry is required.

Default value

no

Example

reauth-for-inactive = no

Parent topic: [reauthentication] stanza

reauth-reset-lifetimereauth-reset-lifetimereauth-reset-lifetime stanza entryreauthentication stanzaentriesreauth-reset-lifetimereauthentication stanzareauthentication stanzareauth-reset-lifetime entrySyntax reauth-reset-lifetime = {yes|no}Description Enables WebSEAL to reset the lifetime timer for WebSEAL credential cache entries following successful reauthentication.Options yesEnable.noDisable.Usage This stanza entry is required.Default value noExample reauth-reset-lifetime = no[reauthentication] stanza

reauth-reset-lifetime

Syntax

reauth-reset-lifetime = {yes|no}

Description

Enables WebSEAL to reset the lifetime timer for WebSEAL credential cache entries following successful reauthentication.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

no

Example

reauth-reset-lifetime = no

Parent topic: [reauthentication] stanza

terminate-on-reauth-lockoutterminate-on-reauth-lockoutterminate-on-reauth-lockout stanza entryreauthentication stanzaentriesterminate-on-reauth-lockoutreauthentication stanzareauthentication stanzaterminate-on-reauth-lockout entrySyntax terminate-on-reauth-lockout = {yes|no}Description Specifies whether or not to remove the session cache entry of a user who reaches the max-login-failures policy limit during reauthentication. Options yesWhen the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is logged out and the user's session is removed.noWhen the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is locked out as specified by the disable-time-interval setting, and notified of the lockout as specified by the late-lockout-notification setting. The user is not logged out and the initial login session is still valid. The user can still access other resources that are not protected by a reauthn POP.Usage This stanza entry is required.Default value yesExample terminate-on-reauth-lockout = yes[reauthentication] stanza

terminate-on-reauth-lockout

Syntax

terminate-on-reauth-lockout = {yes|no}

Description

Specifies whether or not to remove the session cache entry of a user who reaches the max-login-failures policy limit during reauthentication.

Options

yes

When the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is logged out and the user's session is removed.

no

When the maximum number of failed login attempts (specified by the max-login-failures policy) is reached during reauthentication, the user is locked out as specified by the disable-time-interval setting, and notified of the lockout as specified by the late-lockout-notification setting. The user is not logged out and the initial login session is still valid. The user can still access other resources that are not protected by a reauthn POP.

Usage

This stanza entry is required.

Default value

yes

Example

terminate-on-reauth-lockout = yes

Parent topic: [reauthentication] stanza

[replica-sets] stanza[replica-sets] stanzareplica-sets stanzastanzasreplica-setsStanza referencereplica-setUse the replica-set stanza entry to configure WebSEAL to join replica sets that are managed by the distributed session cache server.

[replica-sets] stanza

replica-set
Use the replica-set stanza entry to configure WebSEAL to join replica sets that are managed by the distributed session cache server.

Parent topic: Stanza reference

replica-setreplica-setUse the replica-set stanza entry to configure WebSEAL to join replica sets that are managed by the distributed session cache server.replica-set stanza entryreplica-sets stanzaentriesreplica-setreplica-sets stanzareplica-sets stanzareplica-set entrySyntax replica-set = replica_set_name Description If WebSEAL is configured to use the distributed session cache for session storage, the WebSEAL server joins each of the replica sets listed in this stanza. The entries listed here must be replica sets configured on the distributed session cache. Options replica_set_nameReplica set name. Usage This stanza entry is optional. Default value None. Example replica-set = setA [replica-sets] stanza

replica-set

Use the replica-set stanza entry to configure WebSEAL to join replica sets that are managed by the distributed session cache server.

Syntax

replica-set = replica_set_name

Description

If WebSEAL is configured to use the distributed session cache for session storage, the WebSEAL server joins each of the replica sets listed in this stanza. The entries listed here must be replica sets configured on the distributed session cache.

Options

replica_set_name

Replica set name.

Usage

This stanza entry is optional.

Default value

None.

Example

replica-set = setA

Parent topic: [replica-sets] stanza

[rsp-header-names] stanzaDefines static HTTP headers that will be added to every HTTP response from the WebSEAL server.rsp-header-names stanzastanzasrsp-header-namesWith this stanza, an administrator can insert some standard security headers into the response, such as strict-transport-security, content-security-policy, and x-frame-options. The headers that are defined in this stanza will replace any matching headers that might have been added to the response by a junctioned application. If multiple headers of the same name are specified in this stanza, all but the last of the matching entries will be ignored. The format of each entry in this stanza is:<header-name> = <header-value> For example:strict-transport-security = max-age=31536000; includeSubDomains A special <header-value> of '%SESSION_EXPIRY%' can be used to designate a header that will contain the remaining length of time, in seconds, before the current local session expires. This value does not include the overall session timeout for sessions that are managed by the distributed session cache (DSC), but just the length of time before the session expires in the local cache. For example:session-timeout = %SESSION_EXPIRY%Stanza reference

[rsp-header-names] stanza

Defines static HTTP headers that will be added to every HTTP response from the WebSEAL server.

With this stanza, an administrator can insert some standard security headers into the response, such as strict-transport-security, content-security-policy, and x-frame-options.

Note: The headers that are defined in this stanza will replace any matching headers that might have been added to the response by a junctioned application.

If multiple headers of the same name are specified in this stanza, all but the last of the matching entries will be ignored.

The format of each entry in this stanza is:

<header-name> = <header-value>

For example:

strict-transport-security = max-age=31536000; includeSubDomains

A special <header-value> of '%SESSION_EXPIRY%' can be used to designate a header that will contain the remaining length of time, in seconds, before the current local session expires. This value does not include the overall session timeout for sessions that are managed by the distributed session cache (DSC), but just the length of time before the session expires in the local cache.

For example:

session-timeout = %SESSION_EXPIRY%

Parent topic: Stanza reference

[rtss-eas] stanza[rtss-eas] stanzartss-eas stanza rtss-easstanzasYou can use the rtss-eas configuration stanza to configure the EAS that communicates with the RBA server. The runtime security services EAS is used for a particular object if the effective POP for the object has an attribute called eas-trigger with an associated value of trigger_rba_eas. Add this stanza and the associated entries if you want to configure runtime security services for Advanced Access Control.Stanza referenceapply-tam-native-policyaudit-log-cfgcluster-namecontext-idSpecify the context ID that the runtime security services EAS uses when sending XACML requests.provide_700_attribute_idsSpecify whether to enable the attribute IDs from Risk-Based Access version 7.0.trace-componentuse_real_client_ipActivate the use of the real client IP address for authorization decisions.

[rtss-eas] stanza

You can use the rtss-eas configuration stanza to configure the EAS that communicates with the RBA server. The runtime security services EAS is used for a particular object if the effective POP for the object has an attribute called eas-trigger with an associated value of trigger_rba_eas.

Add this stanza and the associated entries if you want to configure runtime security services for Advanced Access Control.

apply-tam-native-policy

audit-log-cfg

cluster-name

context-id
Specify the context ID that the runtime security services EAS uses when sending XACML requests.

provide_700_attribute_ids
Specify whether to enable the attribute IDs from Risk-Based Access version 7.0.

trace-component

use_real_client_ip
Activate the use of the real client IP address for authorization decisions.

Parent topic: Stanza reference

apply-tam-native-policyapply-tam-native-policyapply-tam-native-policy stanza entryrtss-eas stanzaentriesapply-tam-native-policyrtss-eas stanzartss-eas stanzaapply-tam-native-policy entrySyntax apply-tam-native-policy = {true | false} Description Determines whether the IBM Security Access Manager for Web ACL policy takes effect. Options trueRuntime security services EAS checks with Security Access Manager whether the user has permission to access the resource based on the ACL policy.falseRuntime security services EAS does not check the Security Access Manager ACL policy to determine whether the user has permission to access the resource. Usage This stanza entry is required. This stanza entry applies to Advanced Access Control. Default value None. Example apply-tam-native-policy = true [rtss-eas] stanza

apply-tam-native-policy

Syntax

apply-tam-native-policy = {true | false}

Description

Determines whether the IBM Security Access Manager for Web ACL policy takes effect.

Options

true

Runtime security services EAS checks with Security Access Manager whether the user has permission to access the resource based on the ACL policy.

false

Runtime security services EAS does not check the Security Access Manager ACL policy to determine whether the user has permission to access the resource.

Usage

This stanza entry is required.

This stanza entry applies to Advanced Access Control.

Default value

None.

Example

apply-tam-native-policy = true

Parent topic: [rtss-eas] stanza

audit-log-cfgaudit-log-cfgaudit-log-cfg stanza entryrtss-eas stanzaentriesaudit-log-cfgrtss-eas stanzartss-eas stanzaaudit-log-cfg entrySyntax audit-log-cfg = <agent>[<parameter>=<value>],[<parameter>=<value>],...Description Configures audit logging for the runtime security service. You can use the available parameters to configure the logging agents. Options <agent>Specifies the logging agent. The agent controls the logging destination for server events. Valid agents include:stdoutstderrfileremotersyslog<parameter>The different agents support the following configuration parameters:Logging agent configuration parametersParameterSupporting agentsbuffer_sizeremotecompressremotednremoteerror_retryremote, rsyslogflush_intervalallhi_wateralllog_idfile, rsyslogmax_event_lenrsyslogmodefilepathallportremote, rsyslogqueue_sizeallrebind_retryremote, rsyslogrollover_sizefileserverremote, rsyslogssl_keyfilersyslogssl_labelrsyslogssl_stashfilersyslogFor a complete description of the available logging agents and the supported configuration parameters, see the Security Access Manager: Auditing Guide. Usage This stanza entry is optional. This stanza entry applies to Advanced Access Control. You must configure this attribute if you want WebSEAL to log runtime security audit events. If there is no value set, then WebSEAL does not log any audit events for the runtime security service. Default value None. Example To log audit events in a file called rtss-audit.log: audit-log-cfg = file path=/tmp/rtss-audit.log,flush_interval=20, rollover_size=2000000,queue_size=48To send audit logs to STDOUT: audit-log-cfg = stdout [rtss-eas] stanza

audit-log-cfg

Syntax

audit-log-cfg = <agent>[<parameter>=<value>],[<parameter>=<value>],...

Description

Configures audit logging for the runtime security service. You can use the available parameters to configure the logging agents.

Options

<agent>

Specifies the logging agent. The agent controls the logging destination for server events. Valid agents include:

stdout

stderr

file

remote

rsyslog

<parameter>

The different agents support the following configuration parameters:

Table 315. Logging agent configuration parameters

Parameter | Supporting agents
buffer_size | remote
compress | remote
dn | remote
error_retry | remote, rsyslog
flush_interval | all
hi_water | all
log_id | file, rsyslog
max_event_len | rsyslog
mode | file
path | all
port | remote, rsyslog
queue_size | all
rebind_retry | remote, rsyslog
rollover_size | file
server | remote, rsyslog
ssl_keyfile | rsyslog
ssl_label | rsyslog
ssl_stashfile | rsyslog

Note: For a complete description of the available logging agents and the supported configuration parameters, see the Security Access Manager: Auditing Guide.

Usage

This stanza entry is optional.

This stanza entry applies to Advanced Access Control.

Note: You must configure this attribute if you want WebSEAL to log runtime security audit events. If there is no value set, then WebSEAL does not log any audit events for the runtime security service.

Default value

None.

Example

To log audit events in a file called rtss-audit.log:

audit-log-cfg = file path=/tmp/rtss-audit.log,flush_interval=20,
rollover_size=2000000,queue_size=48

To send audit logs to STDOUT:

audit-log-cfg = stdout

Parent topic: [rtss-eas] stanza

cluster-namecluster-namecluster-name stanza entryrtss-eas stanzaentriescluster-namertss-eas stanzartss-eas stanzacluster-name entrySyntax cluster-name = <cluster_name> Description The name of the runtime security services SOAP cluster that hosts this runtime security SOAP service. You must also specify a corresponding [rtss-cluster:<cluster>] stanza, which contains the definition of the cluster. Options <cluster_name>The name of the runtime security services SOAP cluster where the runtime security SOAP service is hosted. Usage This stanza entry is required. This stanza entry applies to Advanced Access Control. Default value None. Example cluster-name = cluster1For this example, there needs to be a corresponding [rtss-cluster:cluster1] stanza to define the cluster. [rtss-eas] stanza

cluster-name

Syntax

cluster-name = <cluster_name>

Description

The name of the runtime security services SOAP cluster that hosts this runtime security SOAP service. You must also specify a corresponding [rtss-cluster:<cluster>] stanza, which contains the definition of the cluster.

Options

<cluster_name>

The name of the runtime security services SOAP cluster where the runtime security SOAP service is hosted.

Usage

This stanza entry is required.

This stanza entry applies to Advanced Access Control.

Default value

None.

Example

cluster-name = cluster1

For this example, there needs to be a corresponding [rtss-cluster:cluster1] stanza to define the cluster.

Parent topic: [rtss-eas] stanza

context-idcontext-idSpecify the context ID that the runtime security services EAS uses when sending XACML requests.context-id stanza entryrtss-eas stanzaentriescontext-idrtss-eas stanzartss-eas stanzacontext-id entrySyntax context-id = {other-policy-id | context-inherited-pop | context-server-name} Description Specifies the context ID that the runtime security services EAS uses when sending XACML requests to runtime security services. This value must match the service name of the deployed policy. If the context-id parameter is not set, it defaults to the WebSEAL server name.Options context-inherited-popUse the location of the inherited POP for all requests. Use this value if you require multiple policies for different portions of the protected resource tree.context-server-nameUse the WebSEAL server name for all requests.other-policy-idSpecify the value for the policy ID for all requests. Usage This stanza entry is optional. This stanza entry applies to Advanced Access Control. Default value If there is no value provided for this parameter, it defaults to the WebSEAL server name. Example context-id = context-inherited-pop [rtss-eas] stanza

context-id

Specify the context ID that the runtime security services EAS uses when sending XACML requests.

Syntax

context-id = {other-policy-id | context-inherited-pop | context-server-name}

Description

Specifies the context ID that the runtime security services EAS uses when sending XACML requests to runtime security services. This value must match the service name of the deployed policy.

Note: If the context-id parameter is not set, it defaults to the WebSEAL server name.

Options

context-inherited-pop

Use the location of the inherited POP for all requests. Use this value if you require multiple policies for different portions of the protected resource tree.

context-server-name

Use the WebSEAL server name for all requests.

other-policy-id

Specify the value for the policy ID for all requests.

Usage

This stanza entry is optional.

This stanza entry applies to Advanced Access Control.

Default value

If there is no value provided for this parameter, it defaults to the WebSEAL server name.

Example

context-id = context-inherited-pop

Parent topic: [rtss-eas] stanza

provide_700_attribute_idsprovide_700_attribute_idsprovide_700_attribute_ids stanza entrySpecify whether to enable the attribute IDs from Risk-Based Access version 7.0.rtss-eas stanzaprovide_700_attribute_idsprovide_700_attribute_idsrtss-eas stanzaattribute IDsversion 7.0changes fromversion 7.0Access Manager for Webuse previous attribute IDsSyntax provide_700_attribute_ids = {true | false}Description Several attribute IDs for Risk-Based Access were changed from version 7.0. To use the 7.0 attribute IDs, add this entry to your configuration file. Specify this entry under the [rtss-eas] stanza.Options trueRuntime security services uses the previous attribute IDs from version Risk-Based Access 7.0.falseRuntime security services uses the new attribute IDs defined for the current version.Usage This stanza entry is not required. This stanza entry applies to Advanced Access Control.Default value falseExample provide_700_attribute_ids = true[rtss-eas] stanza

provide_700_attribute_ids

Specify whether to enable the attribute IDs from Risk-Based Access version 7.0.

Syntax

provide_700_attribute_ids = {true | false}

Description

Several attribute IDs for Risk-Based Access were changed from version 7.0. To use the 7.0 attribute IDs, add this entry to your configuration file. Specify this entry under the [rtss-eas] stanza.

Options

true

Runtime security services uses the previous attribute IDs from version Risk-Based Access 7.0.

false

Runtime security services uses the new attribute IDs defined for the current version.

Usage

This stanza entry is not required.

This stanza entry applies to Advanced Access Control.

Default value

false

Example

provide_700_attribute_ids = true

Parent topic: [rtss-eas] stanza

trace-componenttrace-componenttrace-component stanza entryrtss-eas stanzaentriestrace-componentrtss-eas stanzartss-eas stanzatrace-component entrySyntaxtrace-component = <component_name> Description Specifies the name of the Security Access Manager trace component that the EAS uses. Options <component_name>The name of the Security Access Manager trace component. Usage This stanza entry is required. This stanza entry applies to Advanced Access Control. The configured component traces the data that passes into the runtime security services EAS, which is governed by the [azn-decision-info] stanza. This trace might contain sensitive information. Default value None. Example trace-component = pdweb.rtss [rtss-eas] stanza

trace-component

Syntax

trace-component = <component_name>

Description

Specifies the name of the Security Access Manager trace component that the EAS uses.

Options

<component_name>

The name of the Security Access Manager trace component.

Usage

This stanza entry is required.

This stanza entry applies to Advanced Access Control.

Note: The configured component traces the data that passes into the runtime security services EAS, which is governed by the [azn-decision-info] stanza. This trace might contain sensitive information.

Default value

None.

Example

trace-component = pdweb.rtss

Parent topic: [rtss-eas] stanza

use_real_client_ipuse_real_client_ipuse_real_client_ipActivate the use of the real client IP address for authorization decisions.rtss-eas stanzause_real_client_ipuse-real-client-iprtss-eas stanzause-real-client-iprtss-eas stanzaSyntax use_real_client_ip = {true | false}Description Determines whether to activate the current, or real, client IP address. Specify this entry under the [rtss-eas] stanza. If the client_ip = client_ip entry exists in the [azn-decision-info] stanza, then the current client IP address is activated in the AZN_CRED_NETWORK_ADDRESS_STR credential. In IBM Access Manager version 7.0, the value of AZN_CRED_NETWORK_ADDRESS_STR contained the client IP address when the user first authenticated and the credential was built. If the IP address changed during the session, the value was not updated. If you want to use this type of client IP address, you have two options: Do not add the client_ip = client_ip entry to the [azn-decision-info] stanza.Add the client_ip = client_ip entry to the [azn-decision-info] stanza. Also, set use_real_client_ip = false under the [rtss-eas] stanza.Options trueRuntime security services EAS uses the current and real IP address.falseRuntime security services EAS uses the client IP address from when the user first authenticated and the credential was built. If the client IP changes during the session, the client IP is not updated.Usage This stanza entry is not required. This stanza entry applies to Advanced Access Control.Default value trueExample use_real_client_ip = false[rtss-eas] stanza

use_real_client_ip

Activate the use of the real client IP address for authorization decisions.

Syntax

use_real_client_ip = {true | false}

Description

Determines whether to activate the current, or real, client IP address. Specify this entry under the [rtss-eas] stanza.

If the client_ip = client_ip entry exists in the [azn-decision-info] stanza, then the current client IP address is activated in the AZN_CRED_NETWORK_ADDRESS_STR credential.

In IBM Access Manager version 7.0, the value of AZN_CRED_NETWORK_ADDRESS_STR contained the client IP address when the user first authenticated and the credential was built. If the IP address changed during the session, the value was not updated. If you want to use this type of client IP address, you have two options:

Do not add the client_ip = client_ip entry to the [azn-decision-info] stanza.

Add the client_ip = client_ip entry to the [azn-decision-info] stanza. Also, set use_real_client_ip = false under the [rtss-eas] stanza.

Options

true

Runtime security services EAS uses the current and real IP address.

false

Runtime security services EAS uses the client IP address from when the user first authenticated and the credential was built. If the client IP changes during the session, the client IP is not updated.

Usage

This stanza entry is not required.

This stanza entry applies to Advanced Access Control.

Default value

true

Example

use_real_client_ip = false

Parent topic: [rtss-eas] stanza

[rtss-cluster:<cluster>] stanza[rtss-cluster:<cluster>] stanzaxacml-cluster: cluster stanzastanzaxacml-cluster: cluster This stanza contains the configuration entries for the runtime security services SOAP servers.Stanza referencebasic-auth-userbasic-auth-passwdhandle-idle-timeouthandle-pool-sizeserverssl-fips-enabledssl-keyfilessl-keyfile-labelssl-keyfile-stashssl-nist-complianceUse the ssl-nist-compliance stanza entry in the [rtss-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance for runtime security services SOAP communication.ssl-valid-server-dntimeout

[rtss-cluster:<cluster>] stanza

This stanza contains the configuration entries for the runtime security services SOAP servers.

basic-auth-user

basic-auth-passwd

handle-idle-timeout

handle-pool-size

server

ssl-fips-enabled

ssl-keyfile

ssl-keyfile-label

ssl-keyfile-stash

ssl-nist-compliance
Use the ssl-nist-compliance stanza entry in the [rtss-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance for runtime security services SOAP communication.

ssl-valid-server-dn

timeout

Parent topic: Stanza reference

basic-auth-userbasic-auth-userbasic-auth-user stanza entryxacml-cluster: stanzaentriesbasic-auth-userrtss-clustercluster stanzaxacml-cluster: cluster stanzaSyntax basic-auth-user = <user_name> Description Specifies the name of the user for WebSEAL to include in the basic authentication header when communicating with the runtime security services SOAP server. Options <user_name>The user name for WebSEAL to include in the basic authentication header. Usage This stanza entry is optional.Configure this entry if the runtime security services SOAP server is configured to require basic authentication. Default value None. Example basic-auth-user = userA [rtss-cluster:<cluster>] stanza

basic-auth-user

Syntax

basic-auth-user = <user_name>

Description

Specifies the name of the user for WebSEAL to include in the basic authentication header when communicating with the runtime security services SOAP server.

Options

<user_name>

The user name for WebSEAL to include in the basic authentication header.

Usage

This stanza entry is optional.

Note: Configure this entry if the runtime security services SOAP server is configured to require basic authentication.

Default value

None.

Example

basic-auth-user = userA

Parent topic: [rtss-cluster:<cluster>] stanza

basic-auth-passwdbasic-auth-passwdbasic-auth-passwd stanza entryxacml-cluster: stanzaentriesbasic-auth-passwd[rtss-cluster:cluster] stanzaxacml-cluster: cluster stanzabasic-auth-passwd entrySyntax basic-auth-passwd = <password> Description Specifies the password for WebSEAL to include in the basic authentication header when communicating with the runtime security services SOAP server. Options <password>The password that WebSEAL includes in the basic authentication header. Usage This stanza entry is optional.Configure this entry if the runtime security services SOAP server is configured to require basic authentication. Default value None. Example basic-auth-passwd = password [rtss-cluster:<cluster>] stanza

basic-auth-passwd

Syntax

basic-auth-passwd = <password>

Description

Specifies the password for WebSEAL to include in the basic authentication header when communicating with the runtime security services SOAP server.

Options

<password>

The password that WebSEAL includes in the basic authentication header.

Usage

This stanza entry is optional.

Note: Configure this entry if the runtime security services SOAP server is configured to require basic authentication.

Default value

None.

Example

basic-auth-passwd = password

Parent topic: [rtss-cluster:<cluster>] stanza

handle-idle-timeouthandle-idle-timeouthandle-idle-timeout stanza entryxacml-cluster: stanzastanza clusterentrieshandle-idle-timeoutrtss-cluster: stanza cluster stanzaxacml-cluster: cluster stanza handle-idle-timeout entrySyntax handle-idle-timeout = <number> Description Specifies the length of time, in seconds, before an idle handle is removed from the handle pool cache. Options <number>Length of time, in seconds, before an idle handle is removed from the handle pool cache. Usage This stanza entry is required. Default value None. Example handle-idle-timeout = 240 [rtss-cluster:<cluster>] stanza

handle-idle-timeout

Syntax

handle-idle-timeout = <number>

Description

Specifies the length of time, in seconds, before an idle handle is removed from the handle pool cache.

Options

<number>

Length of time, in seconds, before an idle handle is removed from the handle pool cache.

Usage

This stanza entry is required.

Default value

None.

Example

handle-idle-timeout = 240

Parent topic: [rtss-cluster:<cluster>] stanza

handle-pool-sizehandle-pool-sizehandle-pool-size stanza entryxacml-cluster: cluster stanzaentrieshandle-pool-size[rtss-cluster:cluster] stanzacluster>] stanzaxacml-cluster: cluster stanzahandle-pool-size entrySyntax handle-pool-size = <number> Description The maximum number of cached handles that WebSEAL uses to communicate with runtime security services SOAP. Options <number>The maximum number of handles that WebSEAL uses for runtime security services SOAP communication. Usage This stanza entry is required. Default value None. Example handle-pool-size = 10 [rtss-cluster:<cluster>] stanza

handle-pool-size

Syntax

handle-pool-size = <number>

Description

The maximum number of cached handles that WebSEAL uses to communicate with runtime security services SOAP.

Options

<number>

The maximum number of handles that WebSEAL uses for runtime security services SOAP communication.

Usage

This stanza entry is required.

Default value

None.

Example

handle-pool-size = 10

Parent topic: [rtss-cluster:<cluster>] stanza

serverserverserver stanza entryxacml-cluster: cluster stanzaentriesserver[rtss-cluster:cluster] stanzacluster>] stanzaxacml-cluster: cluster stanzaserver entrySyntax server = {[0-9],}<URL> Description Specifies a priority level and URL for each runtime security services SOAP server that is a member of this cluster. Multiple server entries can be specified for a given cluster for failover and load balancing. Options [0-9]A digit, 0-9, that represents the priority of the server in the cluster (9 being the highest, 0 being the lowest). If the priority is not specified, a priority of 9 is assumed. There can be no space between the comma (,) and the URL. If no priority is specified, the comma is omitted.<URL>A well-formed HTTP or HTTPS uniform resource locator for the runtime security services (RTSS). Usage This stanza entry is required. Default value None. Example server = 9,http://localhost:9080/rtss/authz/services/AuthzService [rtss-cluster:<cluster>] stanza

server

Syntax

server = {[0-9],}<URL>

Description

Specifies a priority level and URL for each runtime security services SOAP server that is a member of this cluster. Multiple server entries can be specified for a given cluster for failover and load balancing.

Options

[0-9]

A digit, 0-9, that represents the priority of the server in the cluster (9 being the highest, 0 being the lowest). If the priority is not specified, a priority of 9 is assumed.

Note: There can be no space between the comma (,) and the URL. If no priority is specified, the comma is omitted.

<URL>

A well-formed HTTP or HTTPS uniform resource locator for the runtime security services (RTSS).

Usage

This stanza entry is required.

Default value

None.

Example

server = 9,http://localhost:9080/rtss/authz/services/AuthzService

Parent topic: [rtss-cluster:<cluster>] stanza

ssl-fips-enabledssl-fips-enabledssl-fips-enabled stanza entryrtss-cluster:cluster stanzaentriesssl-fips-enabledrtss-cluster: cluster stanzartss-cluster: cluster stanzassl-fips-enabled entrySyntax ssl-fips-enabled = {yes|no} Description Determines whether Federal Information Process Standards (FIPS) mode is enabled with runtime security services SOAP. If no configuration entry is present, the setting from the global setting, determined by the Access Manager policy server, takes effect.The [rtss-cluster:<cluster>] ssl-nist-compliance setting can override this entry. If ssl-nist-compliance is set to yes, FIPS mode processing is automatically enabled. Options yesFIPS mode is enabled.noFIPS mode is disabled. Usage This stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. If this entry is required, but it is not specified in the [rtss-cluster:<cluster>] stanza, WebSEAL uses the value in the global [ssl] stanza. Default value None.If you want to use a FIPS level that is different to the Access Manager policy server, edit the configuration file and specify a value for this entry. Example ssl-fips-enabled = yes [rtss-cluster:<cluster>] stanza

ssl-fips-enabled

Syntax

ssl-fips-enabled = {yes|no}

Description

Determines whether Federal Information Process Standards (FIPS) mode is enabled with runtime security services SOAP.

Notes:

If no configuration entry is present, the setting from the global setting, determined by the Access Manager policy server, takes effect.

The [rtss-cluster:<cluster>] ssl-nist-compliance setting can override this entry. If ssl-nist-compliance is set to yes, FIPS mode processing is automatically enabled.

Options

yes

FIPS mode is enabled.

no

FIPS mode is disabled.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Note: If this entry is required, but it is not specified in the [rtss-cluster:<cluster>] stanza, WebSEAL uses the value in the global [ssl] stanza.

Default value

None.

Note: If you want to use a FIPS level that is different to the Access Manager policy server, edit the configuration file and specify a value for this entry.

Example

ssl-fips-enabled = yes

Parent topic: [rtss-cluster:<cluster>] stanza

ssl-keyfilessl-keyfilessl-keyfile stanza entryrtss-cluster: cluster stanzacluster> stanzaentriesssl-keyfilertss-cluster:cluster stanzacluster> stanzartss-cluster: cluster stanzacluster> stanzassl-keyfile entrySyntax ssl-keyfile = <file_name> Description The name of the key database file that houses the client certificate for WebSEAL to use. Options <file_name>The name of the key database file that houses the client certificate for WebSEAL to use. Usage This stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-keyfile = webseald.kdb [rtss-cluster:<cluster>] stanza

ssl-keyfile

Syntax

ssl-keyfile = <file_name>

Description

The name of the key database file that houses the client certificate for WebSEAL to use.

Options

<file_name>

The name of the key database file that houses the client certificate for WebSEAL to use.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-keyfile = webseald.kdb

Parent topic: [rtss-cluster:<cluster>] stanza

ssl-keyfile-labelssl-keyfile-labelssl-keyfile-label stanza entryrtss-cluster: cluster stanzacluster> stanzaentriesssl-keyfile-labelrtss-cluster:cluster stanzacluster> stanzartss-cluster: cluster stanzacluster> stanzassl-keyfile-label entrySyntax ssl-keyfile-label = <label_name> Description The label of the client certificate in the key database. Options <label_name>Client certificate label name. UsageThis stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-keyfile-label = WebSEAL-Test [rtss-cluster:<cluster>] stanza

ssl-keyfile-label

Syntax

ssl-keyfile-label = <label_name>

Description

The label of the client certificate in the key database.

Options

<label_name>

Client certificate label name.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-keyfile-label = WebSEAL-Test

Parent topic: [rtss-cluster:<cluster>] stanza

ssl-keyfile-stashssl-keyfile-stashssl-keyfile-stash stanza entryrtss-cluster:cluster stanzacluster> stanzaentriesssl-keyfile-stashrtss-cluster:cluster stanzacluster> stanzartss-cluster: cluster stanzacluster> stanzassl-keyfile-stash entrySyntax ssl-keyfile-stash = <file_name> Description The name of the password stash file for the key database file. Options <file_name>The name of the password stash file for the key database file. UsageThis stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-keyfile-stash = sslstashfile.sth [rtss-cluster:<cluster>] stanza

ssl-keyfile-stash

Syntax

ssl-keyfile-stash = <file_name>

Description

The name of the password stash file for the key database file.

Options

<file_name>

The name of the password stash file for the key database file.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-keyfile-stash = sslstashfile.sth

Parent topic: [rtss-cluster:<cluster>] stanza

ssl-nist-compliancessl-nist-complianceIBM Security Access Manager for Web WebSEAL ssl-nist-compliance stanza entryUse the ssl-nist-compliance stanza entry in the [rtss-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance for runtime security services SOAP communication.ssl-nist-compliance stanza entrytfim-cluster:cluster stanzacluster> stanzaentriesssl-nist-compliancetfim-cluster:cluster stanzacluster> stanzartss-cluster: cluster stanzacluster> stanzassl-nist-compliance entrytfim-cluster: cluster stanzassl-nist-compliance entrytfim-cluster: cluster stanzassl-nist-compliance entryssl-nist-compliance stanza entrytfim-cluster:cluster stanzaentriesssl-nist-compliancetfim-cluster:cluster stanzaSyntax ssl-nist-compliance = {yes|no} Description Enables or disables NIST SP800-131A compliance for runtime security services SOAP communication.Enabling NIST SP800-131A compliance results in the following automatic configuration:Enables FIPS mode processing. When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the [rtss-cluster:<cluster>] ssl-fips-enabled configuration entry.Enables TLS v1.2. TLS v1 and TLS v1.1 are not disabled.Enables the appropriate signature algorithms.Sets the minimum RSA key size to 2048 bytes.If this ssl-nist-compliance configuration entry is not present, WebSEAL uses the global nist-compliance setting in the [ssl] stanza. Options yesA value of yes enables NIST SP800-131A compliance. noA value of no disables NIST SP800-131A compliance. Usage This stanza entry is optional. Default value no Example ssl-nist-compliance = no [rtss-cluster:<cluster>] stanza

ssl-nist-compliance

Use the ssl-nist-compliance stanza entry in the [rtss-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance for runtime security services SOAP communication.

Syntax

ssl-nist-compliance = {yes|no}

Description

Enables or disables NIST SP800-131A compliance for runtime security services SOAP communication.

Enabling NIST SP800-131A compliance results in the following automatic configuration:

Enables FIPS mode processing.

Note: When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the [rtss-cluster:<cluster>] ssl-fips-enabled configuration entry.

Enables TLS v1.2.

Note: TLS v1 and TLS v1.1 are not disabled.

Enables the appropriate signature algorithms.

Sets the minimum RSA key size to 2048 bytes.

If this ssl-nist-compliance configuration entry is not present, WebSEAL uses the global nist-compliance setting in the [ssl] stanza.

Options

yes

A value of yes enables NIST SP800-131A compliance.

no

A value of no disables NIST SP800-131A compliance.

Usage

This stanza entry is optional.

Default value

no

Example

ssl-nist-compliance = no

Parent topic: [rtss-cluster:<cluster>] stanza

ssl-valid-server-dnssl-valid-server-dnssl-valid-server-dn stanza entryrtss-cluster: cluster stanzaentriesssl-valid-server-dnrtss-cluster: cluster stanzartss-cluster: cluster stanzassl-valid-server-dn entrySyntax ssl-valid-server-dn = <DN-value> Description Specifies the distinguished name of the server (obtained from the server SSL certificate) that WebSEAL can accept. Options <DN-value>The distinguished name of the server (obtained from the server SSL certificate) that WebSEAL accepts. If no value is specified, then WebSEAL considers all domain names valid. You can specify multiple domain names by including multiple ssl-valid-server-dn configuration entries. UsageThis stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-valid-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US [rtss-cluster:<cluster>] stanza

ssl-valid-server-dn

Syntax

ssl-valid-server-dn = <DN-value>

Description

Specifies the distinguished name of the server (obtained from the server SSL certificate) that WebSEAL can accept.

Options

<DN-value>

The distinguished name of the server (obtained from the server SSL certificate) that WebSEAL accepts. If no value is specified, then WebSEAL considers all domain names valid. You can specify multiple domain names by including multiple ssl-valid-server-dn configuration entries.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL. That is, at least one server entry specifies a URL that uses the HTTPS protocol.

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-valid-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US

Parent topic: [rtss-cluster:<cluster>] stanza

timeouttimeouttimeout stanza entryxacml-cluster: cluster stanzaentriestimeout[rtss-cluster:cluster] stanzaxacml-cluster: cluster stanzatimeout entrySyntax timeout = <seconds> Description The length of time (in seconds) to wait for a response from runtime security services SOAP. Options <seconds>The length of time (in seconds) to wait for a response from runtime security services SOAP. Usage This stanza entry is required. Default value None. Example timeout = 240 [rtss-cluster:<cluster>] stanza

timeout

Syntax

timeout = <seconds>

Description

The length of time (in seconds) to wait for a response from runtime security services SOAP.

Options

<seconds>

The length of time (in seconds) to wait for a response from runtime security services SOAP.

Usage

This stanza entry is required.

Default value

None.

Example

timeout = 240

Parent topic: [rtss-cluster:<cluster>] stanza

[script-filtering] stanza[script-filtering] stanzascript-filtering stanzastanzasscript-filteringStanza referencehostname-junction-cookierewrite-absolute-with-absolutescript-filter

[script-filtering] stanza

hostname-junction-cookie

rewrite-absolute-with-absolute

script-filter

Parent topic: Stanza reference

hostname-junction-cookiehostname-junction-cookiehostname-junction-cookie stanza entryscript-filtering stanzaentrieshostname-junction-cookiescript-filtering stanzascript-filtering stanzahostname-junction-cookie entrySyntax hostname-junction-cookie = {yes|no}Description Enables WebSEAL to uniquely identify the cookie used for resolving unfiltered links. This is used when another WebSEAL server has created a junction to this WebSEAL server, using a WebSEAL to WebSEAL junction.Options yesEnable.noDisable.Usage This stanza entry is optional, but it is included by default in the configuration file.Default value noExample hostname-junction-cookie = no[script-filtering] stanza

hostname-junction-cookie

Syntax

hostname-junction-cookie = {yes|no}

Description

Enables WebSEAL to uniquely identify the cookie used for resolving unfiltered links. This is used when another WebSEAL server has created a junction to this WebSEAL server, using a WebSEAL to WebSEAL junction.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is optional, but it is included by default in the configuration file.

Default value

no

Example

hostname-junction-cookie = no

Parent topic: [script-filtering] stanza

rewrite-absolute-with-absoluterewrite-absolute-with-absoluterewrite-absolute-with-absolute stanza entryscript-filtering stanzaentriesrewrite-absolute-with-absolutescript-filtering stanzascript-filtering stanzarewrite-absolute-with-absolute entrySyntax rewrite-absolute-with-absolute = {yes|no}Description Enables WebSEAL to rewrite absolute URLs with new absolute URLs that contain the protocol, host, and port (optionally) that represent how the user accessed the WebSEAL server.Options yesEnable.noDisable.Usage This stanza entry is optional.Default value There is no default value, but if the entry is not specified in this configuration file, WebSEAL assumes the value is no.Example rewrite-absolute-with-absolute = no[script-filtering] stanza

rewrite-absolute-with-absolute

Syntax

rewrite-absolute-with-absolute = {yes|no}

Description

Enables WebSEAL to rewrite absolute URLs with new absolute URLs that contain the protocol, host, and port (optionally) that represent how the user accessed the WebSEAL server.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is optional.

Default value

There is no default value, but if the entry is not specified in this configuration file, WebSEAL assumes the value is no.

Example

rewrite-absolute-with-absolute = no

Parent topic: [script-filtering] stanza

script-filterscript-filterscript-filter stanza entryscript-filtering stanzaentriesscript-filterscript-filtering stanzascript-filtering stanzascript-filter entrySyntax script-filter = {yes|no} Description Enables or disables script filtering support. When enabled, WebSEAL can filter absolute URLs encountered in scripts such as JavaScript. Options yesA value of yes means enabled. noA value of no means disabled. Usage This stanza entry is optional, but is included by default. Default value When it is not declared, the value for the script-filter functionality is no by default. Example script-filter = no [script-filtering] stanza

script-filter

Syntax

script-filter = {yes|no}

Description

Enables or disables script filtering support. When enabled, WebSEAL can filter absolute URLs encountered in scripts such as JavaScript.

Options

yes

A value of yes means enabled.

no

A value of no means disabled.

Usage

This stanza entry is optional, but is included by default.

Default value

When it is not declared, the value for the script-filter functionality is no by default.

Example

script-filter = no

Parent topic: [script-filtering] stanza

[server] stanza[server] stanzaserver stanzastanzasserverStanza referenceallow-shift-jis-charsallow-unauth-ba-supplyUse the allow-unauth-ba-supply stanza entry to control whether unauthenticated users can access junctions that were created with the -b supply option.allow-unsolicited-loginsUse the allow-unsolicited-logins stanza entry to control whether WebSEAL accepts unsolicited login requests.auth-challenge-typeUse the auth-challenge-type stanza entry to specify a comma-separated list of authentication types that WebSEAL can use to challenge a client for authentication information.cache-host-headerUse the cache-host-header stanza entry to control whether WebSEAL caches the host and protocol of the original request.capitalize-content-lengthUse the capitalize-content-length stanza entry to control whether WebSEAL capitalizes the first letters in the name of the HTTP content-length header.client-connect-timeoutUse the client-connect-timeout stanza entry to specify the timeout in seconds for a client connection.chunk-responsesconcurrent-session-threads-hard-limitUse the concurrent-session-threads-hard-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL stops processing requests for the session.concurrent-session-threads-soft-limitUse the concurrent-session-threads-soft-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL generates warning messages.connection-request-limitUse the connection-request-limit stanza entry to specify the maximum number of requests that WebSEAL processes on a single persistent connection.cope-with-pipelined-requestUse the cope-with-pipelined-request stanza entry to control whether WebSEAL closes the connection and notifies the browser if it detects pipelined requests. decode-queryUse the decode-query stanza entry to validate the query string in requests according to the utf8-qstring-support-enabled entry.disable-advanced-filteringUse the disable-advanced-filtering stanza entry to control whether encoded URLs are filtered.disable-timeout-reductionUse the disable-timeout-reduction stanza entry to control whether WebSEAL reduces the timeout duration of threads to help control the number of active worker threads.double-byte-encodingUse the double-byte-encoding stanza entry to control whether WebSEAL treats all encoded characters in URLs as Unicode encoded. dynurl-allow-large-postsUse the dynurl-allow-large-posts stanza entry to control whether WebSEAL accepts POST requests with a body larger than the number of bytes specified by the request-body-max-read entry.dynurl-mapUse the dynurl-map stanza entry to specify the file that contains mappings for URLs to protected objects.enable-IE6-2GB-downloadsUse the enable-IE6-2GB-downloads stanza entry to disable the HTTP Keep-Alives Enabled option for responses that are sent back to Internet Explorer, version 6, client browsers. This configuration allows clients that are using Microsoft Internet Explorer, version 6.0 to download files greater than 2 GB, but less than 4 GB. filter-nonhtml-as-xhtmlUse the filter-nonhtml-as-xhtml stanza entry to enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza.follow-redirects-for WebSEAL can examine 302 responses and process the redirects internally if they are destined for the current server. This configuration entry controls the requests for which this redirect function is enabled.force-tag-value-prefixUse the force-tag-value-prefix stanza entry to control whether WebSEAL prefixes each HTTP-Tag-Value attribute that is set on the junction object with "tagvalue_" before it is added to the credential. httphttp-method-disabled-localhttp-method-disabled-remotehttp-porthttpshttps-portignore-missing-last-chunkintra-connection-timeoutio-buffer-sizeip-support-levelipv6-supportlate-lockout-notificationmax-client-readmax-file-cat-command-lengthmaximum-followed-redirectsSets the maximum number of consecutive 302 redirects that are followed internally before WebSEAL concedes and passes the response back to the client.max-idle-persistent-connectionsnetwork-interfacepersistent-con-timeoutpre-800-compatible-tokensIn IBM Security Access Manager for Web version 8.0, the cipher that WebSEAL uses to encode tokens was changed. Use the pre-800-compatible-tokens stanza entry to enable compatibility with earlier versions of WebSEAL.preserve-base-hrefpreserve-base-href2preserve-p3p-policyprocess-root-requestsredirect-using-relativereject-invalid-host-headerreject-request-transfer-encodingsrequest-body-max-readrequest-max-cachesend-header-ba-firstsend-header-spnego-firstserver-nameslash-before-query-on-redirectstrip-www-authenticate-headerssuppress-backend-server-identitysuppress-dynurl-parsing-of-postssuppress-server-identitytag-value-missing-attr-taguse-existing-username-macro-in-custom-redirectsuse-http-only-cookiesutf8-form-support-enabledutf8-qstring-support-enabledutf8-url-support-enabledvalidate-query-as-gaweb-host-nameweb-http-portweb-http-protocolworker-threads

[server] stanza

allow-shift-jis-chars

allow-unauth-ba-supply
Use the allow-unauth-ba-supply stanza entry to control whether unauthenticated users can access junctions that were created with the -b supply option.

allow-unsolicited-logins
Use the allow-unsolicited-logins stanza entry to control whether WebSEAL accepts unsolicited login requests.

auth-challenge-type
Use the auth-challenge-type stanza entry to specify a comma-separated list of authentication types that WebSEAL can use to challenge a client for authentication information.

cache-host-header
Use the cache-host-header stanza entry to control whether WebSEAL caches the host and protocol of the original request.

capitalize-content-length
Use the capitalize-content-length stanza entry to control whether WebSEAL capitalizes the first letters in the name of the HTTP content-length header.

client-connect-timeout
Use the client-connect-timeout stanza entry to specify the timeout in seconds for a client connection.

chunk-responses

concurrent-session-threads-hard-limit
Use the concurrent-session-threads-hard-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL stops processing requests for the session.

concurrent-session-threads-soft-limit
Use the concurrent-session-threads-soft-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL generates warning messages.

connection-request-limit
Use the connection-request-limit stanza entry to specify the maximum number of requests that WebSEAL processes on a single persistent connection.

cope-with-pipelined-request
Use the cope-with-pipelined-request stanza entry to control whether WebSEAL closes the connection and notifies the browser if it detects pipelined requests.

decode-query
Use the decode-query stanza entry to validate the query string in requests according to the utf8-qstring-support-enabled entry.

disable-advanced-filtering
Use the disable-advanced-filtering stanza entry to control whether encoded URLs are filtered.

disable-timeout-reduction
Use the disable-timeout-reduction stanza entry to control whether WebSEAL reduces the timeout duration of threads to help control the number of active worker threads.

double-byte-encoding
Use the double-byte-encoding stanza entry to control whether WebSEAL treats all encoded characters in URLs as Unicode encoded.

dynurl-allow-large-posts
Use the dynurl-allow-large-posts stanza entry to control whether WebSEAL accepts POST requests with a body larger than the number of bytes specified by the request-body-max-read entry.

dynurl-map
Use the dynurl-map stanza entry to specify the file that contains mappings for URLs to protected objects.

enable-IE6-2GB-downloads
Use the enable-IE6-2GB-downloads stanza entry to disable the HTTP Keep-Alives Enabled option for responses that are sent back to Internet Explorer, version 6, client browsers. This configuration allows clients that are using Microsoft Internet Explorer, version 6.0 to download files greater than 2 GB, but less than 4 GB.

filter-nonhtml-as-xhtml
Use the filter-nonhtml-as-xhtml stanza entry to enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza.

follow-redirects-for
WebSEAL can examine 302 responses and process the redirects internally if they are destined for the current server. This configuration entry controls the requests for which this redirect function is enabled.

force-tag-value-prefix
Use the force-tag-value-prefix stanza entry to control whether WebSEAL prefixes each HTTP-Tag-Value attribute that is set on the junction object with "tagvalue_" before it is added to the credential.

http

http-method-disabled-local

http-method-disabled-remote

http-port

https

https-port

ignore-missing-last-chunk

intra-connection-timeout

io-buffer-size

ip-support-level

ipv6-support

late-lockout-notification

max-client-read

max-file-cat-command-length

maximum-followed-redirects
Sets the maximum number of consecutive 302 redirects that are followed internally before WebSEAL concedes and passes the response back to the client.

max-idle-persistent-connections

network-interface

persistent-con-timeout

pre-800-compatible-tokens
In IBM Security Access Manager for Web version 8.0, the cipher that WebSEAL uses to encode tokens was changed. Use the pre-800-compatible-tokens stanza entry to enable compatibility with earlier versions of WebSEAL.

preserve-base-href

preserve-base-href2

preserve-p3p-policy

process-root-requests

redirect-using-relative

reject-invalid-host-header

reject-request-transfer-encodings

request-body-max-read

request-max-cache

send-header-ba-first

send-header-spnego-first

server-name

slash-before-query-on-redirect

strip-www-authenticate-headers

suppress-backend-server-identity

suppress-dynurl-parsing-of-posts

suppress-server-identity

tag-value-missing-attr-tag

use-existing-username-macro-in-custom-redirects

use-http-only-cookies

utf8-form-support-enabled

utf8-qstring-support-enabled

utf8-url-support-enabled

validate-query-as-ga

web-host-name

web-http-port

web-http-protocol

worker-threads

Parent topic: Stanza reference

allow-shift-jis-charsallow-shift-jis-charsallow-shift-jis-chars stanza entryserver stanzaentriesallow-shift-jis-charsserver stanzaserver stanzaallow-shift-jis-chars entrySyntax allow-shift-jis-chars = {yes|no}Description Specifies whether junctions created using -w will allow all Shift-JIS multibyte characters in junction file and path names.Options yesJunctions created using -w will allow all Shift-JIS multibyte characters in junction file and path names.noJunction file and path names using Shift-JIS multibyte characters containing the single byte character '\' will be rejected.Usage This stanza entry is required.Default value noExample allow-shift-jis-chars = no[server] stanza

allow-shift-jis-chars

Syntax

allow-shift-jis-chars = {yes|no}

Description

Specifies whether junctions created using -w will allow all Shift-JIS multibyte characters in junction file and path names.

Options

yes

Junctions created using -w will allow all Shift-JIS multibyte characters in junction file and path names.

no

Junction file and path names using Shift-JIS multibyte characters containing the single byte character '\' will be rejected.

Usage

This stanza entry is required.

Default value

no

Example

allow-shift-jis-chars = no

Parent topic: [server] stanza

allow-unauth-ba-supplyallow-unauth-ba-supplyIBM Security Access Manager for Web WebSEAL allow-unauth-ba-supply stanza entryUse the allow-unauth-ba-supply stanza entry to control whether unauthenticated users can access junctions that were created with the -b supply option.allow-unauth-ba-supply stanza entryserver stanzaentriesallow-unauth-ba-supplyserver stanzaserver stanzaallow-unauth-ba-supplySyntax allow-unauth-ba-supply = {yes|no} Description This parameter determines access to -b supply junctions by unauthenticated users. By default, unauthenticated users are required to log in before they can access any resource on a junctioned server, where that junction was created with the -b supply argument. Options yesWhen allow-unauth-ba-supply is set to yes, unauthenticated users can access -b supply junctions. The basic authentication header that is supplied by WebSEAL in the forwarded request contains the string unauthenticated for the value of the header.noWhen allow-unauth-ba-supply is set to no, unauthenticated users cannot access -b supply junctions. Users receive a login prompt. Usage This stanza entry is required. Default value no Example allow-unauth-ba-supply = no [server] stanza

allow-unauth-ba-supply

Use the allow-unauth-ba-supply stanza entry to control whether unauthenticated users can access junctions that were created with the -b supply option.

Syntax

allow-unauth-ba-supply = {yes|no}

Description

This parameter determines access to -b supply junctions by unauthenticated users. By default, unauthenticated users are required to log in before they can access any resource on a junctioned server, where that junction was created with the -b supply argument.

Options

yes

When allow-unauth-ba-supply is set to yes, unauthenticated users can access -b supply junctions. The basic authentication header that is supplied by WebSEAL in the forwarded request contains the string unauthenticated for the value of the header.

no

When allow-unauth-ba-supply is set to no, unauthenticated users cannot access -b supply junctions. Users receive a login prompt.

Usage

This stanza entry is required.

Default value

no

Example

allow-unauth-ba-supply = no

Parent topic: [server] stanza

allow-unsolicited-loginsallow-unsolicited-loginsIBM Security Access Manager for Web WebSEAL allow-unsolicited-logins stanza entryUse the allow-unsolicited-logins stanza entry to control whether WebSEAL accepts unsolicited login requests.allow-unsolicited-logins stanza entryserver stanzaentriesallow-unsolicited-loginsserver stanzaserver stanzaallow-unsolicited-loginsSyntax allow-unsolicited-logins = {yes | no} Description This parameter controls whether WebSEAL accepts unsolicited authentication requests. If this parameter is set to no, WebSEAL accepts a login request only if WebSEAL sent the login form to the client to prompt authentication. Options yesWhen allow-unsolicited-logins is set to yes, WebSEAL accepts unsolicited logins. noWhen allow-unsolicited-logins is set to no, WebSEAL does not accept unsolicited logins. This setting ensures that WebSEAL always issues a login form to the client as part of the authentication process. Usage This stanza entry is optional. Default value yes Example allow-unsolicited-logins = yes [server] stanza

allow-unsolicited-logins

Use the allow-unsolicited-logins stanza entry to control whether WebSEAL accepts unsolicited login requests.

Syntax

allow-unsolicited-logins = {yes | no}

Description

This parameter controls whether WebSEAL accepts unsolicited authentication requests. If this parameter is set to no, WebSEAL accepts a login request only if WebSEAL sent the login form to the client to prompt authentication.

Options

yes

When allow-unsolicited-logins is set to yes, WebSEAL accepts unsolicited logins.

no

When allow-unsolicited-logins is set to no, WebSEAL does not accept unsolicited logins. This setting ensures that WebSEAL always issues a login form to the client as part of the authentication process.

Usage

This stanza entry is optional.

Default value

yes

Example

allow-unsolicited-logins = yes

Parent topic: [server] stanza

auth-challenge-typeauth-challenge-typeIBM Security Access Manager for Web WebSEAL auth-challenge-type stanza entryUse the auth-challenge-type stanza entry to specify a comma-separated list of authentication types that WebSEAL can use to challenge a client for authentication information.auth-challenge-type stanza entryserver stanzaentriesauth-challenge-typeserver stanzaserver stanzaauth-challenge-type entrySyntax auth-challenge-type = list Description Each authentication type can be customized for particular user agent strings. For more information about authentication challenges based on the user agent, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy. You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [server:{jct_id}] stanza. where {jct-id} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction. Options listA comma-separated list of authentication types that is used when challenging a client for authentication information. The supported authentication types include: baformsspnegocerteaiThe corresponding authentication configuration entry (for example, ba-auth) must be enabled for each specified authentication challenge type.Each authentication type can also be qualified with a set of rules to specify the user agents that receive a given challenge type. These rules are separated by semicolons and placed inside square brackets preceding the authentication type. Each rule consists of a plus (+) or minus (-) symbol to indicate inclusion or exclusion, and the pattern to match on. The pattern can include:Alphanumeric charactersSpacesPeriods (.)Wildcard characters, such as, question mark (?) and asterisk (*) Usage This stanza entry is optional. Default value By default, the list of authentication challenge types matches the list of configured authentication mechanisms. auth-challenge-type = ba auth-challenge-type = forms Exampleauth-challenge-type = ba, forms auth-challenge-type = [-msie;+ms]ba, [+mozilla*;+*explorer*]forms [server] stanza

auth-challenge-type

Use the auth-challenge-type stanza entry to specify a comma-separated list of authentication types that WebSEAL can use to challenge a client for authentication information.

Syntax

auth-challenge-type = list

Description

Each authentication type can be customized for particular user agent strings. For more information about authentication challenges based on the user agent, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

You can customize this configuration item for a particular junction by adding the adjusted configuration item to a [server:{jct_id}] stanza.

where {jct-id} refers to the junction point for a standard junction (including the leading / character) or the virtual host label for a virtual host junction.

Options

list

A comma-separated list of authentication types that is used when challenging a client for authentication information. The supported authentication types include:

ba

forms

spnego

cert

eai

The corresponding authentication configuration entry (for example, ba-auth) must be enabled for each specified authentication challenge type.

Each authentication type can also be qualified with a set of rules to specify the user agents that receive a given challenge type. These rules are separated by semicolons and placed inside square brackets preceding the authentication type. Each rule consists of a plus (+) or minus (-) symbol to indicate inclusion or exclusion, and the pattern to match on. The pattern can include:

Alphanumeric characters

Spaces

Periods (.)

Wildcard characters, such as, question mark (?) and asterisk (*)

Usage

This stanza entry is optional.

Default value

By default, the list of authentication challenge types matches the list of configured authentication mechanisms.

auth-challenge-type = ba
auth-challenge-type = forms

Example

auth-challenge-type = ba, forms
auth-challenge-type = [-msie;+ms]ba, [+mozilla*;+*explorer*]forms

Parent topic: [server] stanza

cache-host-headercache-host-headerIBM Security Access Manager for Web WebSEAL cache-host-header stanza entryUse the cache-host-header stanza entry to control whether WebSEAL caches the host and protocol of the original request.cache-host-header stanza entryserver stanzaentriescache-host-headerserver stanzaserver stanzacache-host-header entrySyntax cache-host-header = {yes|no} Description By default, when caching an original request, WebSEAL only caches the URL. That is, WebSEAL does not cache the host and protocol of the original request. In this case, when returning a redirect to the original URL, WebSEAL simply redirects to the current host. This causes problems if a request for a protected resource on one virtual host, hostA, results in an authentication operation being processed on a different virtual host, hostB. In this case, the client is incorrectly redirected to hostB rather than hostA. This behavior can be corrected by enabling this stanza entry so that WebSEAL can cache the host and protocol of the original request to be used for redirection. Options yesWebSEAL caches the host and protocol of the original request in addition to the URL. In this case: Both the host and protocol are cached and used in redirects. They cannot be separately managed.The protocol is not cached if the host header is not present.Requests will only be recovered from the cache if the protocol, the host and the URL all match the original request. Limitations associated with this caching behavior: The contents of the existing URL macro will not include the protocol and host. No new macros have been added to represent these elements.It is not possible to specify a protocol and host when a switch user administrator specifies a URL.noWebSEAL only caches the URL associated with the original request and redirects to the current host. Usage This stanza entry is optional. Default value no Example cache-host-header = yes [server] stanza

cache-host-header

Use the cache-host-header stanza entry to control whether WebSEAL caches the host and protocol of the original request.

Syntax

cache-host-header = {yes|no}

Description

By default, when caching an original request, WebSEAL only caches the URL. That is, WebSEAL does not cache the host and protocol of the original request. In this case, when returning a redirect to the original URL, WebSEAL simply redirects to the current host. This causes problems if a request for a protected resource on one virtual host, hostA, results in an authentication operation being processed on a different virtual host, hostB. In this case, the client is incorrectly redirected to hostB rather than hostA. This behavior can be corrected by enabling this stanza entry so that WebSEAL can cache the host and protocol of the original request to be used for redirection.

Options

yes

WebSEAL caches the host and protocol of the original request in addition to the URL. In this case:

Both the host and protocol are cached and used in redirects. They cannot be separately managed.

The protocol is not cached if the host header is not present.

Requests will only be recovered from the cache if the protocol, the host and the URL all match the original request.

Limitations associated with this caching behavior:

The contents of the existing URL macro will not include the protocol and host. No new macros have been added to represent these elements.

It is not possible to specify a protocol and host when a switch user administrator specifies a URL.

no

WebSEAL only caches the URL associated with the original request and redirects to the current host.

Usage

This stanza entry is optional.

Default value

no

Example

cache-host-header = yes

Parent topic: [server] stanza

capitalize-content-lengthcapitalize-content-lengthIBM Security Access Manager for Web WebSEAL capitalize-content-length stanza entryUse the capitalize-content-length stanza entry to control whether WebSEAL capitalizes the first letters in the name of the HTTP content-length header.capitalize-content-length stanza entryserver stanzaentriescapitalize-content-lengthserver stanzaserver stanzacapitalize-content-length entrySyntax capitalize-content-length = {yes|no} Description This parameter determines whether WebSEAL uses capitalized first letters in the content-length header. That is, whether the name of the HTTP content-length header is Content-Length or content-length. NOTE: The Documentum client application expects the name of the HTTP content-length header to be Content-Length, with a capitalized "C" and "L". Options yesWebSEAL uses the Documentum-compliant header name Content-Length.noWebSEAL uses all lower case for the content-length header. That is, content-length. Usage This stanza entry is optional. Default value no Example capitalize-content-length = yes [server] stanza

capitalize-content-length

Use the capitalize-content-length stanza entry to control whether WebSEAL capitalizes the first letters in the name of the HTTP content-length header.

Syntax

capitalize-content-length = {yes|no}

Description

This parameter determines whether WebSEAL uses capitalized first letters in the content-length header. That is, whether the name of the HTTP content-length header is Content-Length or content-length.

NOTE: The Documentum client application expects the name of the HTTP content-length header to be Content-Length, with a capitalized "C" and "L".

Options

yes

WebSEAL uses the Documentum-compliant header name Content-Length.

no

WebSEAL uses all lower case for the content-length header. That is, content-length.

Usage

This stanza entry is optional.

Default value

no

Example

capitalize-content-length = yes

Parent topic: [server] stanza

client-connect-timeoutclient-connect-timeoutIBM Security Access Manager for Web WebSEAL client-connect-timeout stanza entryUse the client-connect-timeout stanza entry to specify the timeout in seconds for a client connection.client-connect-timeout stanza entryserver stanzaentriesclient-connect-timeoutserver stanzaserver stanzaclient-connect-timeout entrySyntax client-connect-timeout = number_of_seconds Description After the initial connection handshake has occurred, this parameter dictates how long ( in seconds) WebSEAL holds the connection open for the initial HTTP or HTTPS request. Options number_of_secondsMust be a positive integer. Other values have unpredictable results and should not be used. Maximum allowed value: 2147483647. Usage This stanza entry is required. Default value 120 Example client-connect-timeout = 120 [server] stanza

client-connect-timeout

Use the client-connect-timeout stanza entry to specify the timeout in seconds for a client connection.

Syntax

client-connect-timeout = number_of_seconds

Description

After the initial connection handshake has occurred, this parameter dictates how long ( in seconds) WebSEAL holds the connection open for the initial HTTP or HTTPS request.

Options

number_of_seconds

Must be a positive integer. Other values have unpredictable results and should not be used. Maximum allowed value: 2147483647.

Usage

This stanza entry is required.

Default value

120

Example

client-connect-timeout = 120

Parent topic: [server] stanza

chunk-responseschunk-responseschunk-responses stanza entryserver stanzaentrieschunk-responsesserver stanzaserver stanzachunk-responses entrySyntax chunk-responses = {yes|no} Description Enables WebSEAL to write chunked data to HTTP/1.1 clients. his can improve performance by allowing connections to be reused even when the exact response length is not known before the response is written. Options yesEnable.noDisable. Usage This stanza entry is required. Default value yes Example chunk-responses = yes [server] stanza

chunk-responses

Syntax

chunk-responses = {yes|no}

Description

Enables WebSEAL to write chunked data to HTTP/1.1 clients. his can improve performance by allowing connections to be reused even when the exact response length is not known before the response is written.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

yes

Example

chunk-responses = yes

Parent topic: [server] stanza

concurrent-session-threads-hard-limitconcurrent-session-threads-hard-limitIBM Security Access Manager for Web WebSEAL concurrent-session-threads-hard-limit stanza entryUse the concurrent-session-threads-hard-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL stops processing requests for the session.concurrent-session-threads-hard-limit stanza entryserver stanzaentriesconcurrent-session-threads-hard-limitserver stanzaserver stanzaconcurrent-session-threads-hard-limit entrySyntax concurrent-session-threads-hard-limit = number_of_threads Description The maximum number of concurrent threads that a single user session can consume. When a user session reaches its thread limit, WebSEAL stops processing any new requests for the user session and returns an error to the client. If you do not specify a value for this entry, there is no limit to the number of concurrent threads that a user session can consume. Options number_of_threads The maximum number of concurrent threads that a single user session can consume before WebSEAL returns an error. Usage This stanza entry is optional. Default value Unlimited. Example concurrent-session-threads-hard-limit = 10 [server] stanza

concurrent-session-threads-hard-limit

Use the concurrent-session-threads-hard-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL stops processing requests for the session.

Syntax

concurrent-session-threads-hard-limit = number_of_threads

Description

The maximum number of concurrent threads that a single user session can consume. When a user session reaches its thread limit, WebSEAL stops processing any new requests for the user session and returns an error to the client.

If you do not specify a value for this entry, there is no limit to the number of concurrent threads that a user session can consume.

Options

number_of_threads

The maximum number of concurrent threads that a single user session can consume before WebSEAL returns an error.

Usage

This stanza entry is optional.

Default value

Unlimited.

Example

concurrent-session-threads-hard-limit = 10

Parent topic: [server] stanza

concurrent-session-threads-soft-limitconcurrent-session-threads-soft-limit IBM Security Access Manager for Web WebSEAL concurrent-session-threads-soft-limit stanza entryUse the concurrent-session-threads-soft-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL generates warning messages.concurrent-session-threads-soft-limit stanza entryserver stanzaentriesconcurrent-session-threads-soft-limitserver stanzaserver stanzaconcurrent-session-threads-soft-limit entrySyntax concurrent-session-threads-soft-limit = number_of_threads Description The maximum number of concurrent threads that a single user session can consume before WebSEAL generates warning messages. WebSEAL continues processing requests for this session until it reaches the configured concurrent-session-threads-hard-limit (also in the [server] stanza). Options number_of_threads Integer value representing the maximum number of concurrent threads that a single session can consume before WebSEAL generates warning messages. Usage This stanza entry is optional. Default value Unlimited. Example concurrent-session-threads-soft-limit = 5 [server] stanza

concurrent-session-threads-soft-limit

Use the concurrent-session-threads-soft-limit stanza entry to specify the maximum number of concurrent threads that a single user session can use before WebSEAL generates warning messages.

Syntax

concurrent-session-threads-soft-limit  = number_of_threads

Description

The maximum number of concurrent threads that a single user session can consume before WebSEAL generates warning messages. WebSEAL continues processing requests for this session until it reaches the configured concurrent-session-threads-hard-limit (also in the [server] stanza).

Options

number_of_threads

Integer value representing the maximum number of concurrent threads that a single session can consume before WebSEAL generates warning messages.

Usage

This stanza entry is optional.

Default value

Unlimited.

Example

concurrent-session-threads-soft-limit  = 5

Parent topic: [server] stanza

connection-request-limitconnection-request-limitIBM Security Access Manager for Web WebSEAL connection-request-limit stanza entryUse the connection-request-limit stanza entry to specify the maximum number of requests that WebSEAL processes on a single persistent connection.connection-request-limit stanza entryserver stanzaentriesconnection-request-limitserver stanzaserver stanzaconnection-request-limit entrySyntax connection-request-limit = number_of_requests Description Specifies the maximum number of requests that will be processed on a single persistent connection. Options number_of_requestsThe maximum number of requests that will be processed on a single persistent connection. Usage This stanza entry is required. Default value 100 Example connection-request-limit = 100 [server] stanza

connection-request-limit

Use the connection-request-limit stanza entry to specify the maximum number of requests that WebSEAL processes on a single persistent connection.

Syntax

connection-request-limit = number_of_requests

Description

Specifies the maximum number of requests that will be processed on a single persistent connection.

Options

number_of_requests

The maximum number of requests that will be processed on a single persistent connection.

Usage

This stanza entry is required.

Default value

100

Example

connection-request-limit = 100

Parent topic: [server] stanza

cope-with-pipelined-requestcope-with-pipelined-requestIBM Security Access Manager for Web WebSEAL cope-with-pipelined-request stanza entryUse the cope-with-pipelined-request stanza entry to control whether WebSEAL closes the connection and notifies the browser if it detects pipelined requests. cope-with-pipelined-request stanza entryserver stanzaentriescope-with-pipelined-requestserver stanzaserver stanzacope-with-pipelined-request entrySyntax cope-with-pipelined-request = {yes|no} Description WebSEAL does not support pipelined requests from browsers. If this option is set to yes, when WebSEAL detects pipelined requests it will close the connection and inform the browser that is should re-send the pipelined requests in a normal manner. This parameter should always be set to yes unless the previous WebSEAL behavior is required. Options yesEnable.noDisable. Usage This stanza entry is required. Default value yes Example cope-with-pipelined-request = yes [server] stanza

cope-with-pipelined-request

Use the cope-with-pipelined-request stanza entry to control whether WebSEAL closes the connection and notifies the browser if it detects pipelined requests.

Syntax

cope-with-pipelined-request = {yes|no}

Description

WebSEAL does not support pipelined requests from browsers. If this option is set to yes, when WebSEAL detects pipelined requests it will close the connection and inform the browser that is should re-send the pipelined requests in a normal manner. This parameter should always be set to yes unless the previous WebSEAL behavior is required.

Options

yes

Enable.

no

Disable.

Usage

This stanza entry is required.

Default value

yes

Example

cope-with-pipelined-request = yes

Parent topic: [server] stanza

decode-querydecode-queryIBM Security Access Manager for Web WebSEAL decode-query stanza entryUse the decode-query stanza entry to validate the query string in requests according to the utf8-qstring-support-enabled entry.decode-query stanza entryserver stanzaentriesdecode-queryserver stanzaserver stanzadecode-query entrySyntax decode-query = {yes|no} Description Validates the query string in requests according to the utf8-qstring-support-enabled parameter. Options yesWhen decode-query is set to yes WebSEAL validates the query string in requests according to the utf8-qstring-support-enabled parameter. Otherwise, WebSEAL does not validate the query string.noWhen decode-query is set to no, then dynurl must be disabled. Usage This stanza entry is required. Default value yes Example decode-query = yes [server] stanza

decode-query

Use the decode-query stanza entry to validate the query string in requests according to the utf8-qstring-support-enabled entry.

Syntax

decode-query = {yes|no}

Description

Validates the query string in requests according to the utf8-qstring-support-enabled parameter.

Options

yes

When decode-query is set to yes WebSEAL validates the query string in requests according to the utf8-qstring-support-enabled parameter. Otherwise, WebSEAL does not validate the query string.

no

When decode-query is set to no, then dynurl must be disabled.

Usage

This stanza entry is required.

Default value

yes

Example

decode-query = yes

Parent topic: [server] stanza

disable-advanced-filteringdisable-advanced-filteringdisable-advanced-filtering stanza entryUse the disable-advanced-filtering stanza entry to control whether encoded URLs are filtered.disable-advanced-filtering stanza entryserver stanzaentriesdisable-advanced-filteringserver stanzaserver stanzadisable-advanced-filtering entrySyntax disable-advanced-filtering = {true | false} DescriptionEnable or disable advanced filtering, which filters encoded URLs. Options trueAdvanced filtering is disabled.falseAdvanced filtering is enabled. UsageThis stanza entry is optional. Default value true Exampledisable-advanced-filtering = false [server] stanza

disable-advanced-filtering

Use the disable-advanced-filtering stanza entry to control whether encoded URLs are filtered.

Syntax

disable-advanced-filtering = {true | false}

Description

Enable or disable advanced filtering, which filters encoded URLs.

Options

true

Advanced filtering is disabled.

false

Advanced filtering is enabled.

Usage

This stanza entry is optional.

Default value

true

Example

disable-advanced-filtering = false

Parent topic: [server] stanza

disable-timeout-reductiondisable-timeout-reductionIBM Security Access Manager for Web WebSEAL disable-timeout-reduction stanza entryUse the disable-timeout-reduction stanza entry to control whether WebSEAL reduces the timeout duration of threads to help control the number of active worker threads.disable-timeout-reduction stanza entryserver stanzaentriesdisable-timeout-reductionserver stanzaserver stanzadisable-timeout-reduction entrySyntax disable-timeout-reduction = {yes|no} Description By default, WebSEAL automatically reduces the timeout duration for threads as the number of in-use worker threads increases. The timeout duration is the maximum length of time that a persistent connection with the client can remain inactive before WebSEAL terminates the connection. This configuration option determines whether WebSEAL reduces the timeout duration to help control the number of active worker threads. This option is available on all platforms. Options yesDisables the timeout reduction done by WebSEAL as the number of worker threads in-use increases.noWebSEAL performs timeout reduction as the number of worker threads in-use increases. Usage This stanza entry is optional. Default value no Example disable-timeout-reduction = yes [server] stanza

disable-timeout-reduction

Use the disable-timeout-reduction stanza entry to control whether WebSEAL reduces the timeout duration of threads to help control the number of active worker threads.

Syntax

disable-timeout-reduction = {yes|no}

Description

By default, WebSEAL automatically reduces the timeout duration for threads as the number of in-use worker threads increases. The timeout duration is the maximum length of time that a persistent connection with the client can remain inactive before WebSEAL terminates the connection.

This configuration option determines whether WebSEAL reduces the timeout duration to help control the number of active worker threads. This option is available on all platforms.

Options

yes

Disables the timeout reduction done by WebSEAL as the number of worker threads in-use increases.

no

WebSEAL performs timeout reduction as the number of worker threads in-use increases.

Usage

This stanza entry is optional.

Default value

no

Example

disable-timeout-reduction = yes

Parent topic: [server] stanza

double-byte-encodingdouble-byte-encodingIBM Security Access Manager for Web WebSEAL double-byte-encoding stanza entryUse the double-byte-encoding stanza entry to control whether WebSEAL treats all encoded characters in URLs as Unicode encoded. double-byte-encoding stanza entryserver stanzaentriesdouble-byte-encodingserver stanzaserver stanzadouble-byte-encoding entrySyntax double-byte-encoding = {yes|no} Description Specifies whether WebSEAL assumes that encoded characters within URLs are always encoded in Unicode, and do not contain UTF-8 characters. Options yesWebSEAL assumes that encoded characters within URLs are always encoded in Unicode, and do not contain UTF-8 characters.noWebSEAL does not assume that encoded characters within URLs are always encoded in Unicode, and do not contain UTF-8 characters. Usage This stanza entry is required. Default value no Example double-byte-encoding = no [server] stanza

double-byte-encoding

Use the double-byte-encoding stanza entry to control whether WebSEAL treats all encoded characters in URLs as Unicode encoded.

Syntax

double-byte-encoding = {yes|no}

Description

Specifies whether WebSEAL assumes that encoded characters within URLs are always encoded in Unicode, and do not contain UTF-8 characters.

Options

yes

WebSEAL assumes that encoded characters within URLs are always encoded in Unicode, and do not contain UTF-8 characters.

no

WebSEAL does not assume that encoded characters within URLs are always encoded in Unicode, and do not contain UTF-8 characters.

Usage

This stanza entry is required.

Default value

no

Example

double-byte-encoding = no

Parent topic: [server] stanza

dynurl-allow-large-postsdynurl-allow-large-postsIBM Security Access Manager for Web WebSEAL dynurl-allow-large-posts stanza entryUse the dynurl-allow-large-posts stanza entry to control whether WebSEAL accepts POST requests with a body larger than the number of bytes specified by the request-body-max-read entry.dynurl-allow-large-posts stanza entryserver stanzaentriesdynurl-allow-large-postsserver stanzaserver stanzadynurl-allow-large-posts entrySyntax dynurl-allow-large-posts = {yes|no} Description Allows or disallows POST requests larger than the current value for the stanza entry request-body-max-read in the [server] stanza. Options yesWhen set to yes, WebSEAL compares only up to request-body-max-read bytes of POST request to the URL mappings contained in dynurl configuration file (dynurl.conf).noWhen set to no, WebSEAL disallows POST requests with a body larger than request-body-max-read. Usage This stanza entry is required. Default value no Example dynurl-allow-large-posts = no [server] stanza

dynurl-allow-large-posts

Use the dynurl-allow-large-posts stanza entry to control whether WebSEAL accepts POST requests with a body larger than the number of bytes specified by the request-body-max-read entry.

Syntax

dynurl-allow-large-posts = {yes|no}

Description

Allows or disallows POST requests larger than the current value for the stanza entry request-body-max-read in the [server] stanza.

Options

yes

When set to yes, WebSEAL compares only up to request-body-max-read bytes of POST request to the URL mappings contained in dynurl configuration file (dynurl.conf).

no

When set to no, WebSEAL disallows POST requests with a body larger than request-body-max-read.

Usage

This stanza entry is required.

Default value

no

Example

dynurl-allow-large-posts = no

Parent topic: [server] stanza

dynurl-mapdynurl-mapIBM Security Access Manager for Web WebSEAL dynurl-map stanza entryUse the dynurl-map stanza entry to specify the file that contains mappings for URLs to protected objects.dynurl-map stanza entryserver stanzaentriesdynurl-mapserver stanzaserver stanzadynurl-map entrySyntax dynurl-map = file_name Description Specifies the file that contains mappings for URLs to protected objects. Options file_nameThe name of the file that contains mappings for URLs to protected objects. Usage This stanza entry is optional. Default value None, but this entry is usually configured to dynurl.conf. Example dynurl-map = dynurl.conf [server] stanza

dynurl-map

Use the dynurl-map stanza entry to specify the file that contains mappings for URLs to protected objects.

Syntax

dynurl-map = file_name

Description

Specifies the file that contains mappings for URLs to protected objects.

Options

file_name

The name of the file that contains mappings for URLs to protected objects.

Usage

This stanza entry is optional.

Default value

None, but this entry is usually configured to dynurl.conf.

Example

dynurl-map = dynurl.conf

Parent topic: [server] stanza

enable-IE6-2GB-downloadsenable-IE6-2GB-downloadsIBM Security Access Manager for Web WebSEAL enable-IE6-2GB-downloads stanza entryUse the enable-IE6-2GB-downloads stanza entry to disable the HTTP Keep-Alives Enabled option for responses that are sent back to Internet Explorer, version 6, client browsers. This configuration allows clients that are using Microsoft Internet Explorer, version 6.0 to download files greater than 2 GB, but less than 4 GB. enable-IE6-2GB-downloads stanza entryserver stanzaentriesenable-IE6-2GB-downloadsserver stanzaserver stanzaenable-IE6-2GB-downloads entrySyntax enable-IE6-2GB-downloads = {yes|no} Description Allows you to disable the HTTP Keep-Alives Enabled option for responses sent back to Internet Explorer, version 6, client browsers. The primary purpose of this is to allow WebSEAL to mimic the Internet Information Services workaround published at http://support.microsoft.com/kb/298618. This will allow clients using Microsoft Internet Explorer, version 6.0, to download files greater than 2GB, but less than 4GB. NOTE: This stanza entry is not necessary for Internet Explorer 7 or for other non-Microsoft browsers.Enabling this workaround will cause WebSEAL to not use persistent connections for Internet Explorer, version 6, client connections when the data to be returned in the response is >= 2GB in length. Options yesDisables the HTTP Keep-Alives Enabled option, allowing clients using Internet Explorer, version 6, to download files greater than 2GB, but less than 4GB.noThe HTTP Keep-Alives Enabled is not disabled. Usage This stanza entry is optional. Default value no Example enable-IE6-2GB-downloads = yes [server] stanza

enable-IE6-2GB-downloads

Use the enable-IE6-2GB-downloads stanza entry to disable the HTTP Keep-Alives Enabled option for responses that are sent back to Internet Explorer, version 6, client browsers. This configuration allows clients that are using Microsoft Internet Explorer, version 6.0 to download files greater than 2 GB, but less than 4 GB.

Syntax

enable-IE6-2GB-downloads = {yes|no}

Description

Allows you to disable the HTTP Keep-Alives Enabled option for responses sent back to Internet Explorer, version 6, client browsers. The primary purpose of this is to allow WebSEAL to mimic the Internet Information Services workaround published at http://support.microsoft.com/kb/298618. This will allow clients using Microsoft Internet Explorer, version 6.0, to download files greater than 2GB, but less than 4GB.

NOTE:

This stanza entry is not necessary for Internet Explorer 7 or for other non-Microsoft browsers.

Enabling this workaround will cause WebSEAL to not use persistent connections for Internet Explorer, version 6, client connections when the data to be returned in the response is >= 2GB in length.

Options

yes

Disables the HTTP Keep-Alives Enabled option, allowing clients using Internet Explorer, version 6, to download files greater than 2GB, but less than 4GB.

no

The HTTP Keep-Alives Enabled is not disabled.

Usage

This stanza entry is optional.

Default value

no

Example

enable-IE6-2GB-downloads = yes

Parent topic: [server] stanza

filter-nonhtml-as-xhtmlfilter-nonhtml-as-xhtmlIBM Security Access Manager for Web WebSEAL filter-nonhtml-as-xhtml stanza entryUse the filter-nonhtml-as-xhtml stanza entry to enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza.filter-nonhtml-as-xhtml stanza entryserver stanzaentriesfilter-nonhtml-as-xhtmlserver stanzaserver stanzafilter-nonhtml-as-xhtml entrySyntax filter-nonhtml-as-xhtml = {yes|no} Description Enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza. Options yesEnable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanzanoDisable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza Usage This stanza entry is required. Default value no Example filter-nonhtml-as-xhtml = no [server] stanza

filter-nonhtml-as-xhtml

Use the filter-nonhtml-as-xhtml stanza entry to enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza.

Syntax

filter-nonhtml-as-xhtml = {yes|no}

Description

Enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza.

Options

yes

Enable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza

no

Disable tag-based filtering of static URLs for new MIME types added to the [filter-content-types] stanza

Usage

This stanza entry is required.

Default value

no

Example

filter-nonhtml-as-xhtml = no

Parent topic: [server] stanza

follow-redirects-for WebSEAL can examine 302 responses and process the redirects internally if they are destined for the current server. This configuration entry controls the requests for which this redirect function is enabled.follow-redirects-for stanza entryserver stanzaentriesfollow-redirects-forserver stanzaserver stanzafollow-redirects-for entrySyntax follow-redirects-for = { pattern | !LRR! }Description The configuration entry is pattern-matched against the HTTP request line. Multiple patterns can be specified by including multiple configuration entries of the same name.Options patternThe requests for which the WebSEAL internal redirect function is enabled. You can use shell-style pattern matching characters *, ?, \, and [] in the pattern.!LRR!Match any request that results in a Local Response Redirect action.Usage This entry is required if the maximum-followed-redirects entry in the [server] stanza is set to a value other than 0. Default valueNone.Example follow-redirects-for = GET /jct/cgi-bin/eai* follow-redirects-for = !LRR![server] stanza

follow-redirects-for

WebSEAL can examine 302 responses and process the redirects internally if they are destined for the current server. This configuration entry controls the requests for which this redirect function is enabled.

Syntax

follow-redirects-for = { pattern | !LRR! }

Description

The configuration entry is pattern-matched against the HTTP request line. Multiple patterns can be specified by including multiple configuration entries of the same name.

Options

pattern

The requests for which the WebSEAL internal redirect function is enabled.

You can use shell-style pattern matching characters "*", "?", "\", and "[]" in the pattern.

!LRR!

Match any request that results in a Local Response Redirect action.

Usage

This entry is required if the maximum-followed-redirects entry in the [server] stanza is set to a value other than 0.

Default value

None.

Example

follow-redirects-for = GET /jct/cgi-bin/eai*
follow-redirects-for = !LRR!

Parent topic: [server] stanza

force-tag-value-prefixforce-tag-value-prefixIBM Security Access Manager for Web WebSEAL force-tag-value-prefix stanza entryUse the force-tag-value-prefix stanza entry to control whether WebSEAL prefixes each HTTP-Tag-Value attribute that is set on the junction object with "tagvalue_" before it is added to the credential. force-tag-value-prefixstanza entryserver stanzaentriesforce-tag-value-prefixserver stanzaserver stanzaforce-tag-value-prefix entrySyntax force-tag-value-prefix = {yes|no} Description Determines whether each attribute name set in a junction object's HTTP-Tag-Value is automatically prefixed with "tagvalue_" before it is placed in the credential. This prohibits access to credential attributes that do not have names beginning with "tagvalue_" such as AUTHENTICATION_LEVEL. When this options set to no, the automatic prefixing of "tagvalue_" will not occur so that all credential attributes can be specified in HTTP-Tag-Value. Options yesEnable the automatic prefixing of "tagvalue_" to each attribute name set in a junction object's HTTP-Tag-Value.noDisable the automatic prefixing of "tagvalue_" so that all credential attributes can be specified in HTTP-Tag-Value. Usage This stanza entry is required. Default value yes Example force-tag-value-prefix = yes [server] stanza

force-tag-value-prefix

Use the force-tag-value-prefix stanza entry to control whether WebSEAL prefixes each HTTP-Tag-Value attribute that is set on the junction object with "tagvalue_" before it is added to the credential.

Syntax

force-tag-value-prefix = {yes|no}

Description

Determines whether each attribute name set in a junction object's HTTP-Tag-Value is automatically prefixed with "tagvalue_" before it is placed in the credential. This prohibits access to credential attributes that do not have names beginning with "tagvalue_" such as AUTHENTICATION_LEVEL. When this options set to no, the automatic prefixing of "tagvalue_" will not occur so that all credential attributes can be specified in HTTP-Tag-Value.

Options

yes

Enable the automatic prefixing of "tagvalue_" to each attribute name set in a junction object's HTTP-Tag-Value.

no

Disable the automatic prefixing of "tagvalue_" so that all credential attributes can be specified in HTTP-Tag-Value.

Usage

This stanza entry is required.

Default value

yes

Example

force-tag-value-prefix = yes

Parent topic: [server] stanza

httphttphttp stanza entryserver stanzaentrieshttpserver stanzaserver stanzahttp entrySyntax http = {yes|no}Description Specifies whether HTTP requests will be accepted by the WebSEAL server. This value is set by the administrator during WebSEAL server configuration.Options yesAccept HTTP requests.noDo not accept HTTP requests.Usage This stanza entry is required.Default value noExample http = yes[server] stanza

http

Syntax

http = {yes|no}

Description

Specifies whether HTTP requests will be accepted by the WebSEAL server. This value is set by the administrator during WebSEAL server configuration.

Options

yes

Accept HTTP requests.

no

Do not accept HTTP requests.

Usage

This stanza entry is required.

Default value

no

Example

http = yes

Parent topic: [server] stanza

http-method-disabled-localhttp-method-disabled-localhttp-method-disabled-local stanza entryserver stanzaentrieshttp-method-disabled-localserver stanzaserver stanzahttp-method-disabled-local entrySyntax http-method-disabled-local = [HTTP_methods] Description Specifies the HTTP methods that WebSEAL blocks when processing HTTP requests for local resources. By default, WebSEAL blocks the TRACE HTTP method. Options HTTP_methodsA comma-separated list of HTTP methods that are blocked when requesting local resources. Usage This stanza entry is required. Default value TRACE Example http-method-disabled-local = TRACE [server] stanza

http-method-disabled-local

Syntax

http-method-disabled-local = [HTTP_methods]

Description

Specifies the HTTP methods that WebSEAL blocks when processing HTTP requests for local resources. By default, WebSEAL blocks the TRACE HTTP method.

Options

HTTP_methods

A comma-separated list of HTTP methods that are blocked when requesting local resources.

Usage

This stanza entry is required.

Default value

TRACE

Example

http-method-disabled-local = TRACE

Parent topic: [server] stanza

http-method-disabled-remotehttp-method-disabled-remotehttp-method-disabled-remote stanza entryserver stanzaentrieshttp-method-disabled-remoteserver stanzaserver stanzahttp-method-disabled-remote entrySyntax http-method-disabled-remote = [HTTP_methods] Description Specifies the HTTP methods that WebSEAL blocks when processing HTTP requests for junctioned resources. By default, WebSEAL blocks the TRACE HTTP method. Options HTTP_methodsA comma-separated list of HTTP methods that are blocked when requesting remote resources. Usage This stanza entry is required. Default value TRACE Example http-method-disabled-remote = TRACE [server] stanza

http-method-disabled-remote

Syntax

http-method-disabled-remote = [HTTP_methods]

Description

Specifies the HTTP methods that WebSEAL blocks when processing HTTP requests for junctioned resources. By default, WebSEAL blocks the TRACE HTTP method.

Options

HTTP_methods

A comma-separated list of HTTP methods that are blocked when requesting remote resources.

Usage

This stanza entry is required.

Default value

TRACE

Example

http-method-disabled-remote = TRACE

Parent topic: [server] stanza

http-porthttp-porthttp-port stanza entryserver stanzaentrieshttp-portserver stanzaserver stanzahttp-port entrySyntax http-port = port_numberDescription Port on which WebSEAL listens for HTTPS requests. This value is set during WebSEAL configuration. When the default HTTP port is already in use, WebSEAL configuration suggests the next available (unused) port number.Options port_numberThe administrator can modify this number. Valid values include any port number not already in use on the host.Usage This stanza entry is required.Default value 80Example http-port = 80[server] stanza

http-port

Syntax

http-port = port_number

Description

Port on which WebSEAL listens for HTTPS requests. This value is set during WebSEAL configuration. When the default HTTP port is already in use, WebSEAL configuration suggests the next available (unused) port number.

Options

port_number

The administrator can modify this number. Valid values include any port number not already in use on the host.

Usage

This stanza entry is required.

Default value

80

Example

http-port = 80

Parent topic: [server] stanza

httpshttpshttps stanza entryserver stanzaentrieshttpsserver stanzaserver stanzahttps entrySyntax https = {yes|no}Description Specifies whether HTTPS requests will be accepted by the WebSEAL server. This value is set by the administrator during WebSEAL server configuration.Options yesAccept HTTPS requests.noDo not accept HTTPS requests.Usage This stanza entry is required.Default value noExample https = yes[server] stanza

https

Syntax

https = {yes|no}

Description

Specifies whether HTTPS requests will be accepted by the WebSEAL server. This value is set by the administrator during WebSEAL server configuration.

Options

yes

Accept HTTPS requests.

no

Do not accept HTTPS requests.

Usage

This stanza entry is required.

Default value

no

Example

https = yes

Parent topic: [server] stanza

https-porthttps-porthttps-port stanza entryserver stanzaentrieshttps-portserver stanzaserver stanzahttps-port entrySyntax https-port = port_numberDescription Port on which WebSEAL listens for HTTPS requests. This value is set during WebSEAL configuration. When the default port is already in use, WebSEAL configuration suggests the next available (unused) port number.Options port_numberThe administrator can modify this number. Valid values include any port number not already in use on the host.Usage This stanza entry is required.Default value 443Example https-port = 443[server] stanza

https-port

Syntax

https-port = port_number

Description

Port on which WebSEAL listens for HTTPS requests. This value is set during WebSEAL configuration. When the default port is already in use, WebSEAL configuration suggests the next available (unused) port number.

Options

port_number

The administrator can modify this number. Valid values include any port number not already in use on the host.

Usage

This stanza entry is required.

Default value

443

Example

https-port = 443

Parent topic: [server] stanza

ignore-missing-last-chunkignore-missing-last-chunkignore-missing-last-chunk stanza entryserver stanzaentriesignore-missing-last-chunkserver stanzaserver stanzaignore-missing-last-chunk entrySyntax ignore-missing-last-chunk = {yes|no}Description Controls whether WebSEAL ignores a missing last chunk in a data-stream from a backend server that is using chunked transfer-encoding.Options yesWebSEAL will ignore a missing last-chunk in a data-stream from a backend server that is using chunked transfer-encoding. This matches the behavior in prior releases of WebSEAL.noWebSEAL will RST (reset) the connection to the front-end browser if the last-chunk is not present.Usage This stanza entry is optional.Default value noExample ignore-missing-last-chunk = yes[server] stanza

ignore-missing-last-chunk

Syntax

ignore-missing-last-chunk = {yes|no}

Description

Controls whether WebSEAL ignores a missing last chunk in a data-stream from a backend server that is using chunked transfer-encoding.

Options

yes

WebSEAL will ignore a missing last-chunk in a data-stream from a backend server that is using chunked transfer-encoding. This matches the behavior in prior releases of WebSEAL.

no

WebSEAL will RST (reset) the connection to the front-end browser if the last-chunk is not present.

Usage

This stanza entry is optional.

Default value

no

Example

ignore-missing-last-chunk = yes

Parent topic: [server] stanza

intra-connection-timeoutintra-connection-timeoutintra-connection-timeout stanza entryserver stanzaentriesintra-connection-timeoutserver stanzaserver stanzaintra-connection-timeout entrySyntax intra-connection-timeout = number_of_secondsDescription This parameter affects request and response data sent as two or more fragments. The parameter specifies the timeout (in seconds) between each request data fragment after the first data fragment is received by WebSEAL. The parameter also governs the timeout between response data fragments after the first data fragment is returned by WebSEAL. Options number_of_secondsIf the value of this parameter is set to 0 (or not set), connection timeouts between data fragments are governed instead by the client-connect-timeout parameter. The exception to this rule occurs for responses returned over HTTP (TCP). In this case, there is no timeout between response fragments. If a connection timeout occurs on a non-first data fragment due to the intra-connection-timeout setting, a TCP RST (reset) packet is sent.Usage This stanza entry is required.Default value 60Example intra-connection-timeout = 60[server] stanza

intra-connection-timeout

Syntax

intra-connection-timeout = number_of_seconds

Description

This parameter affects request and response data sent as two or more fragments. The parameter specifies the timeout (in seconds) between each request data fragment after the first data fragment is received by WebSEAL. The parameter also governs the timeout between response data fragments after the first data fragment is returned by WebSEAL.

Options

number_of_seconds

If the value of this parameter is set to 0 (or not set), connection timeouts between data fragments are governed instead by the client-connect-timeout parameter. The exception to this rule occurs for responses returned over HTTP (TCP). In this case, there is no timeout between response fragments. If a connection timeout occurs on a non-first data fragment due to the intra-connection-timeout setting, a TCP RST (reset) packet is sent.

Usage

This stanza entry is required.

Default value

60

Example

intra-connection-timeout = 60

Parent topic: [server] stanza

io-buffer-sizeio-buffer-sizeio-buffer-size stanza entryserver stanzaentriesio-buffer-sizeserver stanzaserver stanzaio-buffer-size entrySyntax io-buffer-size = number_of_bytes Description Positive integer value that indicates the buffer size, in bytes, for low-level reads from and writes to a client. Options number_of_bytes Positive integer value that indicates the buffer size, in bytes, for low-level reads from and writes to a client. The minimum value is 1. WebSEAL does not impose a maximum value. A small value (for instance, 10 bytes) can hurt performance by causing frequent calls to the low-level read/write APIs. Up to a certain point, larger values improve performance because they correspondingly reduce the calls to the low-level I/O functions. However, the low-level I/O functions might have their own internal buffers, such as the TCP send and receive buffers. When io-buffer-size exceeds the size of those buffers, there is no longer any performance improvement because those functions read only part of the buffer at the time. Reasonable values for io-buffer-size range from 1 - 16 kB. Values smaller than this range causes calling the low-level I/O functions too frequently. Values larger than this range wastes memory. A 2 MB I/O buffer size uses 4 MB for each worker thread that communicates with the client, since there is an input and output buffer. Usage This stanza entry is required. Default value 4096 Example io-buffer-size = 4096 [server] stanza

io-buffer-size

Syntax

io-buffer-size = number_of_bytes

Description

Positive integer value that indicates the buffer size, in bytes, for low-level reads from and writes to a client.

Options

number_of_bytes

Positive integer value that indicates the buffer size, in bytes, for low-level reads from and writes to a client.

The minimum value is 1. WebSEAL does not impose a maximum value.

A small value (for instance, 10 bytes) can hurt performance by causing frequent calls to the low-level read/write APIs. Up to a certain point, larger values improve performance because they correspondingly reduce the calls to the low-level I/O functions.

However, the low-level I/O functions might have their own internal buffers, such as the TCP send and receive buffers. When io-buffer-size exceeds the size of those buffers, there is no longer any performance improvement because those functions read only part of the buffer at the time.

Reasonable values for io-buffer-size range from 1 - 16 kB. Values smaller than this range causes calling the low-level I/O functions too frequently. Values larger than this range wastes memory. A 2 MB I/O buffer size uses 4 MB for each worker thread that communicates with the client, since there is an input and output buffer.

Usage

This stanza entry is required.

Default value

4096

Example

io-buffer-size = 4096

Parent topic: [server] stanza

ip-support-levelip-support-levelip-support-level stanza entryserver stanzaentriesip-support-levelserver stanzaserver stanzaip-support-level entrySyntax ip-support-level = {displaced-only|generic-only|displaced-and-generic}Description Controls the amount of network information stored in a credential by specifying the required IP level.Options displaced-onlyWebSEAL only generates the IPv4 attribute when building user credentials and when authenticating users through external authentication C API modules.generic-onlyWebSEAL only generates new generic attributes that support both IPv4 and IPv6 when building user credentials and when authenticating users through external authentication C API modules.displaced-and-genericBoth sets of attribute types (produced by displaced-only and generic-only) are used when building user credentials and when authenticating users through external authentication C API modules.Usage This stanza entry is required.Default value generic-onlyExample ip-support-level = generic-only[server] stanza

ip-support-level

Syntax

ip-support-level = {displaced-only|generic-only|displaced-and-generic}

Description

Controls the amount of network information stored in a credential by specifying the required IP level.

Options

displaced-only

WebSEAL only generates the IPv4 attribute when building user credentials and when authenticating users through external authentication C API modules.

generic-only

WebSEAL only generates new generic attributes that support both IPv4 and IPv6 when building user credentials and when authenticating users through external authentication C API modules.

displaced-and-generic

Both sets of attribute types (produced by displaced-only and generic-only) are used when building user credentials and when authenticating users through external authentication C API modules.

Usage

This stanza entry is required.

Default value

generic-only

Example

ip-support-level = generic-only

Parent topic: [server] stanza

ipv6-supportipv6-supportipv6-support stanza entryserver stanzaentriesipv6-supportserver stanzaserver stanzaipv6-support entrySyntax ipv6-support = {yes|no}Description Enable/disable WebSEAL support for IPv6 format.Options yesEnable WebSEAL support for IPv6 format.noDisable WebSEAL support for IPv6 format.Usage This stanza entry is required.Default value yesExample ipv6-support = yes[server] stanza

ipv6-support

Syntax

ipv6-support = {yes|no}

Description

Enable/disable WebSEAL support for IPv6 format.

Options

yes

Enable WebSEAL support for IPv6 format.

no

Disable WebSEAL support for IPv6 format.

Usage

This stanza entry is required.

Default value

yes

Example

ipv6-support = yes

Parent topic: [server] stanza

late-lockout-notificationlate-lockout-notificationlate-lockout-notification stanza entryserver stanzaentrieslate-lockout-notificationserver stanzaserver stanzalate-lockout-notification entrySyntax late-lockout-notification = {yes|no} Description WebSEAL returns a server response error page (acct_locked.html) that notifies the user of the penalty for reaching or exceeding the maximum value set by the max-login-failures policy. This stanza entry specifies whether this notification occurs when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit. Options yesUpon reaching the maximum value set by the max-login-failures policy, WebSEAL returns another login prompt to the user. WebSEAL does not send the account disabled error page to the user until the next login attempt. This response represents pre-version 6.0 behavior for the max-login-failures policy.noUpon reaching the maximum value set by the max-login-failures policy, WebSEAL immediately sends the account disabled error page to the user. Usage Required Default value The default for new installations is no. The default for migrated installations is yes. Example late-lockout-notification = yes [server] stanza

late-lockout-notification

Syntax

late-lockout-notification = {yes|no}

Description

WebSEAL returns a server response error page (acct_locked.html) that notifies the user of the penalty for reaching or exceeding the maximum value set by the max-login-failures policy. This stanza entry specifies whether this notification occurs when the user reaches the max-login-failures limit, or at the next login attempt after reaching the limit.

Options

yes

Upon reaching the maximum value set by the max-login-failures policy, WebSEAL returns another login prompt to the user. WebSEAL does not send the account disabled error page to the user until the next login attempt. This response represents pre-version 6.0 behavior for the max-login-failures policy.

no

Upon reaching the maximum value set by the max-login-failures policy, WebSEAL immediately sends the account disabled error page to the user.

Usage

Required

Default value

The default for new installations is no. The default for migrated installations is yes.

Example

late-lockout-notification = yes

Parent topic: [server] stanza

max-client-readmax-client-readmax-client-read stanza entryserver stanzaentriesmax-client-readserver stanzaserver stanzamax-client-read entrySyntax max-client-read = number_of_bytesDescription Specifies the maximum number of bytes of request line and header information that WebSEAL holds in internal buffers when reading an HTTP request from a client. One purpose for max-client-read is to help protect WebSEAL from denial-of-service attacks. As of Security Access Manager WebSEAL 6.0, the max-client-read stanza entry no longer impacts the request-body-max-read and request-max-cache stanza entries.Options number_of_bytesThe minimum value for this parameter is 32678 bytes. If the total size of the request line and headers is greater than the value specified for this parameter, WebSEAL closes the connection without reading any more data or sending any response to the client. If the value is set to a number below 32768, the value is ignored and a value of 32768 is used. There is no maximum value. URL and header information in a typical request rarely exceeds 2048 bytes.Usage This stanza entry is required.Default value 32768Example max-client-read = 32768[server] stanza

max-client-read

Syntax

max-client-read = number_of_bytes

Description

Specifies the maximum number of bytes of request line and header information that WebSEAL holds in internal buffers when reading an HTTP request from a client. One purpose for max-client-read is to help protect WebSEAL from denial-of-service attacks.

As of Security Access Manager WebSEAL 6.0, the max-client-read stanza entry no longer impacts the request-body-max-read and request-max-cache stanza entries.

Options

number_of_bytes

The minimum value for this parameter is 32678 bytes. If the total size of the request line and headers is greater than the value specified for this parameter, WebSEAL closes the connection without reading any more data or sending any response to the client.

If the value is set to a number below 32768, the value is ignored and a value of 32768 is used. There is no maximum value. URL and header information in a typical request rarely exceeds 2048 bytes.

Usage

This stanza entry is required.

Default value

32768

Example

max-client-read = 32768

Parent topic: [server] stanza

max-file-cat-command-lengthmax-file-cat-command-lengthmax-file-cat-command-length stanza entryserver stanzaentriesmax-file-cat-command-lengthserver stanzaserver stanzamax-file-cat-command-length entrySyntax max-file-cat-command-length = number_of_bytes Description Specifies the maximum size of the file, specified in bytes, which may be returned from the file cat server task command. If the value of this parameter is less than the size of the file specified in the file cat command, the returned file will be truncated. This parameter takes precedence over the optional -max bytes value in the file cat command. Options number_of_bytes The maximum size of the file, specified in bytes, which may be returned from the file cat command. Usage This stanza entry is required. Default value 1024 Example max-file-cat-command-length = 512 [server] stanza

max-file-cat-command-length

Syntax

max-file-cat-command-length = number_of_bytes

Description

Specifies the maximum size of the file, specified in bytes, which may be returned from the file cat server task command.

If the value of this parameter is less than the size of the file specified in the file cat command, the returned file will be truncated. This parameter takes precedence over the optional -max bytes value in the file cat command.

Options

number_of_bytes

The maximum size of the file, specified in bytes, which may be returned from the file cat command.

Usage

This stanza entry is required.

Default value

1024

Example

max-file-cat-command-length = 512

Parent topic: [server] stanza

maximum-followed-redirectsSets the maximum number of consecutive 302 redirects that are followed internally before WebSEAL concedes and passes the response back to the client.maximum-followed-redirects stanza entryserver stanzaentriesmaximum-followed-redirectsserver stanzaserver stanzamaximum-followed-redirects entrySyntax maximum-followed-redirects = numberDescription In some situations, WebSEAL can send a 302 redirect to the client, which causes a new request to be sent to the same WebSEAL server. This situation can occur for WebSEAL generated responses (for example, the redirect after a forms-based authentication) or for responses that come from junctioned Web servers. WebSEAL can recognize the 302 redirects that are destined for the same server and handle these redirects internally. Enabling this function can help improve the performance of mobile applications by reducing network communication between WebSEAL and the client. Use the maximum-followed-redirects entry to set the maximum number of redirects that WebSEAL handles internally before it sends the redirects to the client for processing.Options numberThe maximum number of consecutive 302 redirects that are followed internally before WebSEAL concedes and passes the response back to the client.A value of 0 indicates that all 302 redirects are sent back to the client for processing.Usage This entry is optional. If this entry is set to a value other than 0, you must also set the redirect-methods entry in the [server] stanza.Default value0Example maximum-followed-redirects = 0[server] stanza

maximum-followed-redirects

Sets the maximum number of consecutive 302 redirects that are followed internally before WebSEAL concedes and passes the response back to the client.

Syntax

maximum-followed-redirects = number

Description

In some situations, WebSEAL can send a 302 redirect to the client, which causes a new request to be sent to the same WebSEAL server. This situation can occur for WebSEAL generated responses (for example, the redirect after a forms-based authentication) or for responses that come from junctioned Web servers.

WebSEAL can recognize the 302 redirects that are destined for the same server and handle these redirects internally. Enabling this function can help improve the performance of mobile applications by reducing network communication between WebSEAL and the client.

Use the maximum-followed-redirects entry to set the maximum number of redirects that WebSEAL handles internally before it sends the redirects to the client for processing.

Options

number

The maximum number of consecutive 302 redirects that are followed internally before WebSEAL concedes and passes the response back to the client.

Note: A value of 0 indicates that all 302 redirects are sent back to the client for processing.

Usage

This entry is optional. If this entry is set to a value other than 0, you must also set the redirect-methods entry in the [server] stanza.

Default value

0

Example

maximum-followed-redirects = 0

Parent topic: [server] stanza

max-idle-persistent-connectionsmax-idle-persistent-connectionsmax-idle-persistent-connections stanza entryserver stanzaentriesmax-idle-persistent-connectionsserver stanzaserver stanzamax-idle-persistent-connections entrySyntax max-idle-persistent-connections = number_of_connections Description The maximum number of idle client persistent connections. Use a value less than the maximum number of connections supported by WebSEAL to ensure that the idle connections do not consume all the available connections. Options number_of_connectionsInteger value indicating the maximum number of idle client persistent connections. Usage This stanza entry is required. Default value 512 Examplemax-idle-persistent-connections = 512 [server] stanza

max-idle-persistent-connections

Syntax

max-idle-persistent-connections = number_of_connections

Description

The maximum number of idle client persistent connections. Use a value less than the maximum number of connections supported by WebSEAL to ensure that the idle connections do not consume all the available connections.

Options

number_of_connections

Integer value indicating the maximum number of idle client persistent connections.

Usage

This stanza entry is required.

Default value

512

Example

max-idle-persistent-connections = 512

Parent topic: [server] stanza

network-interfacenetwork-interfacenetwork-interface stanza entryserver stanzaentriesnetwork-interfaceserver stanzaserver stanzanetwork-interface entrySyntax network-interface = ip-addressDescription Specify an alternative IP address to be used by this instance of WebSEAL. This allows two or more WebSEAL instances to use different IP addresses and host names when running on the same machine .Options ip-addressIP address.Usage This stanza entry is optional.Default value 0.0.0.0Example network-interface = 9.0.0.9[server] stanza

network-interface

Syntax

network-interface = ip-address

Description

Specify an alternative IP address to be used by this instance of WebSEAL. This allows two or more WebSEAL instances to use different IP addresses and host names when running on the same machine .

Options

ip-address

IP address.

Usage

This stanza entry is optional.

Default value

0.0.0.0

Example

network-interface = 9.0.0.9

Parent topic: [server] stanza

persistent-con-timeoutpersistent-con-timeoutpersistent-con-timeout stanza entryserver stanzaentriespersistent-con-timeoutserver stanzaserver stanzapersistent-con-timeout entrySyntax persistent-con-timeout = number_of_seconds Description HTTP/1.1 connection timeout, in seconds. This setting affects connections to clients, not to backend server systems. Options number_of_secondsHTTP/1.1 connection timeout, in seconds. Must be a positive integer. Other values have unpredictable results and should not be used. Maximum allowed value: 2147483647. A value of 0 causes WebSEAL to set the 'Connection: close' header and then close the connection on every response. If the value of this stanza entry is set to 0, the connection does not remain open for future requests. Usage This stanza entry is required. Default value 5 Example persistent-con-timeout = 5 [server] stanza

persistent-con-timeout

Syntax

persistent-con-timeout = number_of_seconds

Description

HTTP/1.1 connection timeout, in seconds. This setting affects connections to clients, not to backend server systems.

Options

number_of_seconds

HTTP/1.1 connection timeout, in seconds. Must be a positive integer. Other values have unpredictable results and should not be used. Maximum allowed value: 2147483647.

A value of 0 causes WebSEAL to set the 'Connection: close' header and then close the connection on every response. If the value of this stanza entry is set to 0, the connection does not remain open for future requests.

Usage

This stanza entry is required.

Default value

5

Example

persistent-con-timeout = 5

Parent topic: [server] stanza

pre-800-compatible-tokenspre-800-compatible-tokensIBM Security Access Manager for Web WebSEAL pre-800-compatible-tokens stanza entryIn IBM Security Access Manager for Web version 8.0, the cipher that WebSEAL uses to encode tokens was changed. Use the pre-800-compatible-tokens stanza entry to enable compatibility with earlier versions of WebSEAL.pre-800-compatible-tokens stanza entryserver stanzaentriespre-800-compatible-tokensserver stanzaserver stanzapre-800-compatible-tokens entrySyntax pre-800-compatible-tokens = {yes|no} Description WebSEAL supports a common method of generating tokens for cross-domain single sign-on, failover, and e-community single sign-on. In WebSEAL version 8.0, the cipher that WebSEAL uses to encode these tokens was changed. This change is not compatible with earlier versions of WebSEAL. When the Security Access Manager deployment includes multiple WebSEAL servers and you want to interoperate with earlier versions of WebSEAL, set this value to yes. Options yesWebSEAL version 8.0 uses the same cipher as earlier versions of WebSEAL to encode tokens that are compatible with earlier versions of WebSEAL.noWebSEAL version 8.0 uses a different cipher to earlier versions of WebSEAL and does not support tokens from earlier versions of WebSEAL. Usage This stanza entry is required. Default value no Example pre-800-compatible-tokens = no [server] stanza

pre-800-compatible-tokens

In IBM Security Access Manager for Web version 8.0, the cipher that WebSEAL uses to encode tokens was changed. Use the pre-800-compatible-tokens stanza entry to enable compatibility with earlier versions of WebSEAL.

Syntax

pre-800-compatible-tokens = {yes|no}

Description

WebSEAL supports a common method of generating tokens for cross-domain single sign-on, failover, and e-community single sign-on. In WebSEAL version 8.0, the cipher that WebSEAL uses to encode these tokens was changed. This change is not compatible with earlier versions of WebSEAL.

When the Security Access Manager deployment includes multiple WebSEAL servers and you want to interoperate with earlier versions of WebSEAL, set this value to yes.

Options

yes

WebSEAL version 8.0 uses the same cipher as earlier versions of WebSEAL to encode tokens that are compatible with earlier versions of WebSEAL.

no

WebSEAL version 8.0 uses a different cipher to earlier versions of WebSEAL and does not support tokens from earlier versions of WebSEAL.

Usage

This stanza entry is required.

Default value

no

Example

pre-800-compatible-tokens = no

Parent topic: [server] stanza

preserve-base-hrefpreserve-base-hrefpreserve-base-href stanza entryserver stanzaentriespreserve-base-hrefserver stanzaserver stanzapreserve-base-href entrySyntax preserve-base-href = {yes|no}Description Specifies whether WebSEAL will remove all BASE HREF tags from filtered HTML documents and prepend the base tag to filtered links.Options yesWhen set to yes, WebSEAL filters the BASE HREF tag.noWhen set to no, WebSEAL removes BASE HREF tags.Usage This stanza entry is required.Default value noExample preserve-base-href = no[server] stanza

preserve-base-href

Syntax

preserve-base-href = {yes|no}

Description

Specifies whether WebSEAL will remove all BASE HREF tags from filtered HTML documents and prepend the base tag to filtered links.

Options

yes

When set to yes, WebSEAL filters the BASE HREF tag.

no

When set to no, WebSEAL removes BASE HREF tags.

Usage

This stanza entry is required.

Default value

no

Example

preserve-base-href = no

Parent topic: [server] stanza

preserve-base-href2preserve-base-href2preserve-base-href2 stanza entryserver stanzaentriespreserve-base-href2server stanzaserver stanzapreserve-base-href2 entrySyntax preserve-base-href2 = {yes|no}Description Used in conjunction with the preserve-base-href option to specify the level of filtering on the BASE HREF tags. NOTE: This option has no effect unless preserve-base-href (also in the [server] stanza) is set to yes.Options yesWhen set to yes, WebSEAL only performs the minimum filtering of the BASE HREF tag necessary to insert the WebSEAL host and junction names.noWhen set to no, WebSEAL completely filters the BASE HREF tags. For BASE tags that do not contain a trailing slash WebSEAL strips the last component. Usage This stanza entry is optional.Default value yesExample preserve-base-href2 = yes[server] stanza

preserve-base-href2

Syntax

preserve-base-href2 = {yes|no}

Description

Used in conjunction with the preserve-base-href option to specify the level of filtering on the BASE HREF tags.

NOTE: This option has no effect unless preserve-base-href (also in the [server] stanza) is set to yes.

Options

yes

When set to yes, WebSEAL only performs the minimum filtering of the BASE HREF tag necessary to insert the WebSEAL host and junction names.

no

When set to no, WebSEAL completely filters the BASE HREF tags. For BASE tags that do not contain a trailing slash WebSEAL strips the last component.

Usage

This stanza entry is optional.

Default value

yes

Example

preserve-base-href2 = yes

Parent topic: [server] stanza

preserve-p3p-policypreserve-p3p-policypreserve-p3p-policy stanza entryserver stanzaentriespreserve-p3p-policyserver stanzaserver stanzapreserve-p3p-policy entrySyntax preserve-p3p-policy = {yes|no}Description Specifies whether to replace or preserve p3p headers from junctioned servers.Options yesThe value yes means that headers are preserved. noA value of no means that headers are replaced.Usage This stanza entry is required.Default value noExample preserve-p3p-policy = no[server] stanza

preserve-p3p-policy

Syntax

preserve-p3p-policy = {yes|no}

Description

Specifies whether to replace or preserve p3p headers from junctioned servers.

Options

yes

The value yes means that headers are preserved.

no

A value of no means that headers are replaced.

Usage

This stanza entry is required.

Default value

no

Example

preserve-p3p-policy = no

Parent topic: [server] stanza

process-root-requestsprocess-root-requestsprocess-root-requests stanza entryserver stanzaentriesprocess-root-requestsserver stanzaserver stanzaprocess-root-requests entrySyntax process-root-requests = {never|always|filter}Description Specifies how WebSEAL responds to requests for resources located at the root ("/") junction. Options neverRoot junction requests are never processed at the root junction. alwaysAlways attempt to process requests for the root junction at the root junction first before attempting to use a junction mapping mechanism.filterExamine all root junction requests to determine whether they start with the patterns specified in the [process-root-filter] stanza.Usage This stanza entry is required.Default value alwaysExample process-root-requests = always[server] stanza

process-root-requests

Syntax

process-root-requests = {never|always|filter}

Description

Specifies how WebSEAL responds to requests for resources located at the root ("/") junction.

Options

never

Root junction requests are never processed at the root junction.

always

Always attempt to process requests for the root junction at the root junction first before attempting to use a junction mapping mechanism.

filter

Examine all root junction requests to determine whether they start with the patterns specified in the [process-root-filter] stanza.

Usage

This stanza entry is required.

Default value

always

Example

process-root-requests = always

Parent topic: [server] stanza

redirect-using-relativeredirect-using-relativeredirect-using-relative stanza entryserver stanzaentriesredirect-using-relativeserver stanzaserver stanzaredirect-using-relative entrySyntax redirect-using-relative = {true|false}Description Specifies that WebSEAL use a server-relative format for the URL in the Location header of an HTTP 302 redirect response. This configuration change affects all redirect responses generated by WebSEAL. These redirect situations include: Redirect after authenticationRedirect after logoutRedirect after changing passwordRedirects during the e-community single signon authentication processRedirects during the cross-domain single signon authentication processSwitch user processingCertificate authentication (prompt-as-needed only)Session displacementOptions trueUse a server-relative format for the URL in the Location header of an HTTP 302 redirect response.falseUse an absolute format for the URL in the Location header of an HTTP 302 redirect response.Usage This stanza entry is not required and is a hidden entry.Default value falseExample redirect-using-relative = true[server] stanza

redirect-using-relative

Syntax

redirect-using-relative = {true|false}

Description

Specifies that WebSEAL use a server-relative format for the URL in the Location header of an HTTP 302 redirect response.

This configuration change affects all redirect responses generated by WebSEAL. These redirect situations include:

Redirect after authentication

Redirect after logout

Redirect after changing password

Redirects during the e-community single signon authentication process

Redirects during the cross-domain single signon authentication process

Switch user processing

Certificate authentication (prompt-as-needed only)

Session displacement

Options

true

Use a server-relative format for the URL in the Location header of an HTTP 302 redirect response.

false

Use an absolute format for the URL in the Location header of an HTTP 302 redirect response.

Usage

This stanza entry is not required and is a hidden entry.

Default value

false

Example

redirect-using-relative = true

Parent topic: [server] stanza

reject-invalid-host-headerreject-invalid-host-headerreject-invalid-host-header stanza entryserver stanzaentriesreject-invalid-host-headerserver stanzaserver stanzareject-invalid-host-header entrySyntax reject-invalid-host-header = {yes|no} Description Determines whether requests to WebSEAL that have an invalid host header (see RFC2616) are rejected with a status of 400, "Bad Request." Options yesAll requests to WebSEAL with an invalid host header will be rejected with a status of 400, "Bad Request."noRequests with an invalid host header are not rejected. Usage This stanza entry is required. Default value no Example reject-invalid-host-header = no [server] stanza

reject-invalid-host-header

Syntax

reject-invalid-host-header = {yes|no}

Description

Determines whether requests to WebSEAL that have an invalid host header (see RFC2616) are rejected with a status of 400, "Bad Request."

Options

yes

All requests to WebSEAL with an invalid host header will be rejected with a status of 400, "Bad Request."

no

Requests with an invalid host header are not rejected.

Usage

This stanza entry is required.

Default value

no

Example

reject-invalid-host-header = no

Parent topic: [server] stanza

reject-request-transfer-encodingsreject-request-transfer-encodingsreject-request-transfer-encodings stanza entryserver stanzaentriesreject-request-transfer-encodingsserver stanzaserver stanzareject-request-transfer-encodings entrySyntax reject-request-transfer-encodings = {yes|no} Description Specifies the WebSEAL response to requests containing the Transfer-Encoding header. Options yesWebSEAL rejects (with error status of 501, Not Implemented) any request with a Transfer-Encoding header value of anything other than "identity" or "chunked".noWebSEAL may reject the request, or may forward it on the junctioned server in a corrupted state. This setting is available for compatibility with versions of WebSEAL prior to version 6.0. Usage This stanza entry is required. Default value yes Example reject-request-transfer-encodings = yes [server] stanza

reject-request-transfer-encodings

Syntax

reject-request-transfer-encodings = {yes|no}

Description

Specifies the WebSEAL response to requests containing the Transfer-Encoding header.

Options

yes

WebSEAL rejects (with error status of 501, Not Implemented) any request with a Transfer-Encoding header value of anything other than "identity" or "chunked".

no

WebSEAL may reject the request, or may forward it on the junctioned server in a corrupted state. This setting is available for compatibility with versions of WebSEAL prior to version 6.0.

Usage

This stanza entry is required.

Default value

yes

Example

reject-request-transfer-encodings = yes

Parent topic: [server] stanza

request-body-max-readrequest-body-max-readrequest-body-max-read stanza entryserver stanzaentriesrequest-body-max-readserver stanzaserver stanzarequest-body-max-read entrySyntax request-body-max-read = number_of_bytesDescription Maximum number of bytes to read in as content from the body of POST requests. The request-body-max-read stanza entry affects the request body only. It does not impose limits on other components of a request, such as request line and headers. Used for dynurl, authentication, and request caching. Options number_of_bytesMaximum number of bytes to read in as content from the body of POST requests. Used for dynurl, authentication, and request caching. Minimum number of bytes: 512. Usage This stanza entry is required.Default value 4096Example request-body-max-read = 4096[server] stanza

request-body-max-read

Syntax

request-body-max-read = number_of_bytes

Description

Maximum number of bytes to read in as content from the body of POST requests. The request-body-max-read stanza entry affects the request body only. It does not impose limits on other components of a request, such as request line and headers. Used for dynurl, authentication, and request caching.

Options

number_of_bytes

Maximum number of bytes to read in as content from the body of POST requests. Used for dynurl, authentication, and request caching. Minimum number of bytes: 512.

Usage

This stanza entry is required.

Default value

4096

Example

request-body-max-read = 4096

Parent topic: [server] stanza

request-max-cacherequest-max-cacherequest-max-cache stanza entryserver stanzaentriesrequest-max-cacheserver stanzaserver stanzarequest-max-cache entrySyntax request-max-cache = number_of_bytesDescription Maximum amount of data to cache. This is used to cache request data when a user is prompted to authenticate before a request can be fulfilled. Options number_of_bytesThis value should be a positive integer. If set to zero (0), the user login succeeds but the request fails because WebSEAL cannot cache the request data. There is no maximum value.Usage This stanza entry is required.Default value 8192Example request-max-cache = 8192[server] stanza

request-max-cache

Syntax

request-max-cache = number_of_bytes

Description

Maximum amount of data to cache. This is used to cache request data when a user is prompted to authenticate before a request can be fulfilled.

Options

number_of_bytes

This value should be a positive integer. If set to zero (0), the user login succeeds but the request fails because WebSEAL cannot cache the request data. There is no maximum value.

Usage

This stanza entry is required.

Default value

8192

Example

request-max-cache = 8192

Parent topic: [server] stanza

send-header-ba-firstsend-header-ba-firstsend-header-ba-first stanza entryserver stanzaentriessend-header-ba-firstserver stanzaserver stanzasend-header-ba-firstSyntax send-header-ba-first = {yes|no} Description By default, WebSEAL selects the authentication challenge to return to the client by sequentially searching the available authentication mechanisms until it finds one that is enabled. You can use the send-header-ba-first entry to ensure that WebSEAL selects the BA header before any of the other configured authentication mechanisms. Options yesWebSEAL sends the header first.noWebSEAL searches sequentially through the available authentication mechanisms and sends the first one that is enabled. Usage This stanza entry is optional. Default value no Example send-header-ba-first = yes See alsosend-header-spnego-first[server] stanza

send-header-ba-first

Syntax

send-header-ba-first = {yes|no}

Description

By default, WebSEAL selects the authentication challenge to return to the client by sequentially searching the available authentication mechanisms until it finds one that is enabled. You can use the send-header-ba-first entry to ensure that WebSEAL selects the BA header before any of the other configured authentication mechanisms.

Options

yes

WebSEAL sends the header first.

no

WebSEAL searches sequentially through the available authentication mechanisms and sends the first one that is enabled.

Usage

This stanza entry is optional.

Default value

no

Example

send-header-ba-first = yes

See also

send-header-spnego-first

Parent topic: [server] stanza

send-header-spnego-firstsend-header-spnego-firstsend-header-spnego-first stanza entryserver stanzaentriessend-header-spnego-firstserver stanzaserver stanzasend-header-spnego-firstSyntax send-header-spnego-first = {yes|no} Description By default, WebSEAL selects the authentication challenge to return to the client by sequentially searching the available authentication mechanisms until it finds one that is enabled. You can use the send-header-spnego-first entry to ensure that WebSEAL selects SPNEGO header first before any of the other configured authentication mechanisms.SPNEGO authentication can use either forms login or a header. If send-header-ba-first is set to yes and send-header-spnego-first is set to no, WebSEAL sends a BA header first, but uses the default search for an SPNEGO forms login. Options yesWebSEAL sends the header first.noWebSEAL searches sequentially through the available authentication mechanisms and sends the first one that is enabled. Usage This stanza entry is optional. Default value no Example send-header-spnego-first = yes See alsosend-header-ba-first[server] stanza

send-header-spnego-first

Syntax

send-header-spnego-first = {yes|no}

Description

By default, WebSEAL selects the authentication challenge to return to the client by sequentially searching the available authentication mechanisms until it finds one that is enabled. You can use the send-header-spnego-first entry to ensure that WebSEAL selects SPNEGO header first before any of the other configured authentication mechanisms.

SPNEGO authentication can use either forms login or a header.

Note: If send-header-ba-first is set to yes and send-header-spnego-first is set to no, WebSEAL sends a BA header first, but uses the default search for an SPNEGO forms login.

Options

yes

WebSEAL sends the header first.

no

WebSEAL searches sequentially through the available authentication mechanisms and sends the first one that is enabled.

Usage

This stanza entry is optional.

Default value

no

Example

send-header-spnego-first = yes

See also

send-header-ba-first

Parent topic: [server] stanza

server-nameserver-nameserver-name stanza entryserver stanzaentriesserver-nameserver stanzaserver stanzaserver-name entrySyntax server-name = host_name-instance_nameDescription The WebSEAL instance name.Options host_name-instance_nameThe WebSEAL instance name, based on the host name of the machine and the instance name of the WebSEAL server. This value is set by the administrator during WebSEAL configuration. WebSEAL instance names must be alphanumeric. The maximum number of characters allowed is 20.Usage This stanza entry is required.Default value None.Example Example initial WebSEAL server with the default instance name accepted, on a host named diamond: server-name = diamond-default Example instance WebSEAL instance, specified as web2, on a host named diamond: server-name = diamond-web2[server] stanza

server-name

Syntax

server-name = host_name-instance_name

Description

The WebSEAL instance name.

Options

host_name-instance_name

The WebSEAL instance name, based on the host name of the machine and the instance name of the WebSEAL server. This value is set by the administrator during WebSEAL configuration. WebSEAL instance names must be alphanumeric. The maximum number of characters allowed is 20.

Usage

This stanza entry is required.

Default value

None.

Example

Example initial WebSEAL server with the default instance name accepted, on a host named diamond:

server-name = diamond-default

Example instance WebSEAL instance, specified as web2, on a host named diamond:

server-name = diamond-web2

Parent topic: [server] stanza

slash-before-query-on-redirectslash-before-query-on-redirectslash-before-query-on-redirect stanza entryserver stanzaentriesslash-before-query-on-redirectserver stanzaserver stanzaslash-before-query-on-redirect entrySyntax slash-before-query-on-redirect = {yes|no}Description When a client URL specifies a directory location that does not end in a trailing slash (/), the client is redirected to the same URL with a trailing slash added.This is necessary for ACL checks to work properly. This stanza entry controls where the slash is added if the original URL contains a query string.Options yesSetting this value to yes causes the trailing slash to be added before the query string. For example: /root/directoryname?query becomes /root/directoryname/?querynoSetting this value to no causes the trailing slash to be added after the query string. For example: /root/directoryname?query becomes /root/directoryname?query/ NOTE: A setting of no could cause browser errors. This option exists for backwards compatibility only.Usage This stanza entry is optional.Default value noExample slash-before-query-on-redirect = yes[server] stanza

slash-before-query-on-redirect

Syntax

slash-before-query-on-redirect = {yes|no}

Description

When a client URL specifies a directory location that does not end in a trailing slash (/), the client is redirected to the same URL with a trailing slash added.This is necessary for ACL checks to work properly.

This stanza entry controls where the slash is added if the original URL contains a query string.

Options

yes

Setting this value to yes causes the trailing slash to be added before the query string.

For example: /root/directoryname?query
becomes /root/directoryname/?query

no

Setting this value to no causes the trailing slash to be added after the query string.

For example: /root/directoryname?query
becomes /root/directoryname?query/

NOTE: A setting of no could cause browser errors. This option exists for backwards compatibility only.

Usage

This stanza entry is optional.

Default value

no

Example

slash-before-query-on-redirect = yes

Parent topic: [server] stanza

strip-www-authenticate-headersstrip-www-authenticate-headersstrip-www-authenticate-headers stanza entryserver stanzaentriesstrip-www-authenticate-headersserver stanzaserver stanzastrip-www-authenticate-headers entrySyntax strip-www-authenticate-headers = {yes|no} Description Controls whether WebSEAL removes the following headers from the responses that it receives from junctioned servers:Negotiate www-authenticate header.NTLM www-authenticate header. Options yesWhen set to yes, WebSEAL removes these www-authenticate headers from junctioned server responses.noWhen set to no, WebSEAL does not remove these www-authenticate headers from junctioned server responses. Usage This stanza entry is optional. Default value yes Example strip-www-authenticate-headers = yes [server] stanza

strip-www-authenticate-headers

Syntax

strip-www-authenticate-headers = {yes|no}

Description

Controls whether WebSEAL removes the following headers from the responses that it receives from junctioned servers:

Negotiate www-authenticate header.

NTLM www-authenticate header.

Options

yes

When set to yes, WebSEAL removes these www-authenticate headers from junctioned server responses.

no

When set to no, WebSEAL does not remove these www-authenticate headers from junctioned server responses.

Usage

This stanza entry is optional.

Default value

yes

Example

strip-www-authenticate-headers = yes

Parent topic: [server] stanza

suppress-backend-server-identitysuppress-backend-server-identitysuppress-backend-server-identity stanza entryserver stanzaentriessuppress-backend-server-identityserver stanzaserver stanzasuppress-backend-server-identity entrySyntax suppress-backend-server-identity = {yes|no} Description Suppresses the identity of the back-end application server from HTTP responses. These responses normally include the line: Server: IBM_HTTP_SERVER/version_number Apache/version_number (Win32) Options yesSetting this value to yes deletes the above header line from the server response.noSetting this value to no leaves the above header line in the server response. Usage This stanza entry is required. Default value no Example suppress-backend-server-identity = no [server] stanza

suppress-backend-server-identity

Syntax

suppress-backend-server-identity = {yes|no}

Description

Suppresses the identity of the back-end application server from HTTP responses. These responses normally include the line:

Server: IBM_HTTP_SERVER/version_number Apache/version_number (Win32)

Options

yes

Setting this value to yes deletes the above header line from the server response.

no

Setting this value to no leaves the above header line in the server response.

Usage

This stanza entry is required.

Default value

no

Example

suppress-backend-server-identity = no

Parent topic: [server] stanza

suppress-dynurl-parsing-of-postssuppress-dynurl-parsing-of-postssuppress-dynurl-parsing-of-posts stanza entryserver stanzaentriessuppress-dynurl-parsing-of-postsserver stanzaserver stanzasuppress-dynurl-parsing-of-posts entrySyntax suppress-dynurl-parsing-of-posts = {yes|no}Description Determines whether POST bodies are used in dynurl processing. Before enabling this option, make certain that no dynurl checked server applications accept arguments from POST bodies so that dynurl checks cannot be bypassed using a POST instead of a Query string.Options yesPOST bodies will not be used in dynurl processing, only Query strings will be used.noPOST bodies can be used in dynurl processing.Usage This stanza entry is required.Default value noExample suppress-dynurl-parsing-of-posts = no[server] stanza

suppress-dynurl-parsing-of-posts

Syntax

suppress-dynurl-parsing-of-posts = {yes|no}

Description

Determines whether POST bodies are used in dynurl processing.

Note: Before enabling this option, make certain that no dynurl checked server applications accept arguments from POST bodies so that dynurl checks cannot be bypassed using a POST instead of a Query string.

Options

yes

POST bodies will not be used in dynurl processing, only Query strings will be used.

no

POST bodies can be used in dynurl processing.

Usage

This stanza entry is required.

Default value

no

Example

suppress-dynurl-parsing-of-posts = no

Parent topic: [server] stanza

suppress-server-identitysuppress-server-identitysuppress-server-identity stanza entryserver stanzaentriessuppress-server-identityserver stanzaserver stanzasuppress-server-identity entrySyntax suppress-server-identity = {yes|no}Description Suppresses the identity of the WebSEAL server from HTTP responses. These responses normally include the line: Server: WebSEAL/version_numberOptions yesSetting this value to yes deletes the above header line from the server response.noSetting this value to no leaves the above header line in the server response.Usage This stanza entry is required.Default value noExample suppress-server-identity = no[server] stanza

suppress-server-identity

Syntax

suppress-server-identity = {yes|no}

Description

Suppresses the identity of the WebSEAL server from HTTP responses. These responses normally include the line:

Server: WebSEAL/version_number

Options

yes

Setting this value to yes deletes the above header line from the server response.

no

Setting this value to no leaves the above header line in the server response.

Usage

This stanza entry is required.

Default value

no

Example

suppress-server-identity = no

Parent topic: [server] stanza

tag-value-missing-attr-tagtag-value-missing-attr-tagtag-value-missing-attr-tag stanza entryserver stanzaentriestag-value-missing-attr-tagserver stanzaserver stanzatag-value-missing-attr-tag entrySyntax tag-value-missing-attr-tag = tag_for_missing_attributeDescription WebSEAL allows credential attributes to be inserted into the HTTP stream as HTTP headers. In the event that a requested attribute is not found in the credential, the HTTP header is still created with a static string. The tag-value-missing-attr-tag configuration entry defines the contents of the header.Options tag_for_missing_attributeTag inserted in the HTTP header in place of a missing attribute.Usage This stanza entry is required.Default value NOT_FOUNDExample tag-value-missing-attr-tag = NOT_FOUND[server] stanza

tag-value-missing-attr-tag

Syntax

tag-value-missing-attr-tag = tag_for_missing_attribute

Description

WebSEAL allows credential attributes to be inserted into the HTTP stream as HTTP headers. In the event that a requested attribute is not found in the credential, the HTTP header is still created with a static string. The tag-value-missing-attr-tag configuration entry defines the contents of the header.

Options

tag_for_missing_attribute

Tag inserted in the HTTP header in place of a missing attribute.

Usage

This stanza entry is required.

Default value

NOT_FOUND

Example

tag-value-missing-attr-tag = NOT_FOUND

Parent topic: [server] stanza

use-existing-username-macro-in-custom-redirectsuse-existing-username-macro-in-custom-redirects use-existing-username-macro-in-custom-redirects stanza entryserver stanzaentriesuse-existing-username-macro-in-custom-redirectsserver stanzaserver stanzause-existing-username-macro-in-custom-redirects entrySyntax use-existing-username-macro-in-custom-redirects = {yes|no} Description When using Local Response Redirection, you can use this configuration option to control how WebSEAL processes the USERNAME macro. By default, WebSEAL sets the USERNAME macro value to the string "unauthenticated" after an inactivity timeout. This processing does not match the behavior when WebSEAL serves static pages. Use this option to override the default behavior and configure WebSEAL to set the USERNAME macro value to the authenticated username. That is, with this option set to yes, WebSEAL processes the USERNAME macro the same when using Local Response Redirection as it does when serving static pages. Options yesWhen using Local Response Redirection, the USERNAME macro value is set to the authenticated username after an inactivity timeout.noWhen using Local Response Redirection, the USERNAME macro value is set to the string "unauthenticated" after an inactivity timeout. Usage This stanza entry is optional. Default value no Example use-existing-username-macro-in-custom-redirects = yes [server] stanza

use-existing-username-macro-in-custom-redirects

Syntax

use-existing-username-macro-in-custom-redirects  = {yes|no}

Description

When using Local Response Redirection, you can use this configuration option to control how WebSEAL processes the USERNAME macro. By default, WebSEAL sets the USERNAME macro value to the string "unauthenticated" after an inactivity timeout. This processing does not match the behavior when WebSEAL serves static pages.

Use this option to override the default behavior and configure WebSEAL to set the USERNAME macro value to the authenticated username. That is, with this option set to yes, WebSEAL processes the USERNAME macro the same when using Local Response Redirection as it does when serving static pages.

Options

yes

When using Local Response Redirection, the USERNAME macro value is set to the authenticated username after an inactivity timeout.

no

When using Local Response Redirection, the USERNAME macro value is set to the string "unauthenticated" after an inactivity timeout.

Usage

This stanza entry is optional.

Default value

no

Example

use-existing-username-macro-in-custom-redirects  = yes

Parent topic: [server] stanza

use-http-only-cookiesuse-http-only-cookiesuse-http-only-cookies stanza entryserver stanzaentriesuse-http-only-cookiesserver stanzaserver stanzause-http-only-cookies entrySyntax use-http-only-cookies = {yes|no}Description Indicates whether WebSEAL will add the HTTP-only attribute to the Session, LTPA and Failover Set-Cookie headers sent by WebSeal.Options yesEnables WebSEAL to add the HTTP-only attribute to Session, LTPA and Failover Set-Cookie headers.noPrevents WebSEAL from adding the HTTP-only attribute to Session, LTPA and Failover Set-Cookie headers.Usage This stanza entry is required.Default value yesExample use-http-only-cookies = yes[server] stanza

use-http-only-cookies

Syntax

use-http-only-cookies = {yes|no}

Description

Indicates whether WebSEAL will add the HTTP-only attribute to the Session, LTPA and Failover Set-Cookie headers sent by WebSeal.

Options

yes

Enables WebSEAL to add the HTTP-only attribute to Session, LTPA and Failover Set-Cookie headers.

no

Prevents WebSEAL from adding the HTTP-only attribute to Session, LTPA and Failover Set-Cookie headers.

Usage

This stanza entry is required.

Default value

yes

Example

use-http-only-cookies = yes

Parent topic: [server] stanza

utf8-form-support-enabledutf8-form-support-enabledutf8-form-support-enabled stanza entryserver stanzaentriesutf8-form-support-enabledserver stanzaserver stanzautf8-form-support-enabled entrySyntax utf8-form-support-enabled = {yes|no|auto}Description UTF-8 encoding support.Options yesWebSEAL only recognizes UTF-8 encoding in forms and the data is used without modification.noWebSEAL does not recognize UTF-8 encoding in forms. Used for local code page only.autoWhen set to auto, WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. When encoding is not recognized as UTF-8, WebSEAL processes the coding as non-UTF-8.Usage This stanza entry is required.Default value yesExample utf8-form-support-enabled = yes[server] stanza

utf8-form-support-enabled

Syntax

utf8-form-support-enabled = {yes|no|auto}

Description

UTF-8 encoding support.

Options

yes

WebSEAL only recognizes UTF-8 encoding in forms and the data is used without modification.

no

WebSEAL does not recognize UTF-8 encoding in forms. Used for local code page only.

auto

When set to auto, WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. When encoding is not recognized as UTF-8, WebSEAL processes the coding as non-UTF-8.

Usage

This stanza entry is required.

Default value

yes

Example

utf8-form-support-enabled = yes

Parent topic: [server] stanza

utf8-qstring-support-enabledutf8-qstring-support-enabledutf8-qstring-support-enabled stanza entryserver stanzaentriesutf8-qstring-support-enabledserver stanzaserver stanzautf8-qstring-support-enabled entrySyntax utf8-qstring-support-enabled = {yes|no|auto}Description UTF-8 encoding support.Options yesWebSEAL only recognizes UTF-8 encoding in strings and the data is used without modification.noWebSEAL does not recognize UTF-8 encoding in strings. Used for local code page only.autoWhen set to auto, WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. When encoding is not recognized as UTF-8, WebSEAL processes the coding as non-UTF-8.Usage This stanza entry is required.Default value noExample utf8-qstring-support-enabled = no[server] stanza

utf8-qstring-support-enabled

Syntax

utf8-qstring-support-enabled = {yes|no|auto}

Description

UTF-8 encoding support.

Options

yes

WebSEAL only recognizes UTF-8 encoding in strings and the data is used without modification.

no

WebSEAL does not recognize UTF-8 encoding in strings. Used for local code page only.

auto

When set to auto, WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. When encoding is not recognized as UTF-8, WebSEAL processes the coding as non-UTF-8.

Usage

This stanza entry is required.

Default value

no

Example

utf8-qstring-support-enabled = no

Parent topic: [server] stanza

utf8-url-support-enabledutf8-url-support-enabledutf8-url-support-enabled stanza entryserver stanzaentriesutf8-url-support-enabledserver stanzaserver stanzautf8-url-support-enabled entrySyntax utf8-url-support-enabled = {yes|no|auto}Description Enable or disable support for UTF-8 encoded characters in URLs.Options yesWebSEAL only recognizes UTF-8 encoding in URLs and the data is used without modification.noWebSEAL does not recognize UTF-8 encoding in URLs. Used for local code page only.autoWhen set to auto, WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. When encoding is not recognized as UTF-8, WebSEAL processes the coding as non-UTF-8.Usage This stanza entry is required.Default value yesExample utf8-url-support-enabled = yes[server] stanza

utf8-url-support-enabled

Syntax

utf8-url-support-enabled = {yes|no|auto}

Description

Enable or disable support for UTF-8 encoded characters in URLs.

Options

yes

WebSEAL only recognizes UTF-8 encoding in URLs and the data is used without modification.

no

WebSEAL does not recognize UTF-8 encoding in URLs. Used for local code page only.

auto

When set to auto, WebSEAL attempts to distinguish between UTF-8 and other forms of language character encoding. When encoding is not recognized as UTF-8, WebSEAL processes the coding as non-UTF-8.

Usage

This stanza entry is required.

Default value

yes

Example

utf8-url-support-enabled = yes

Parent topic: [server] stanza

validate-query-as-gavalidate-query-as-gavalidate-query-as-ga stanza entryserver stanzaentriesvalidate-query-as-gaserver stanzaserver stanzavalidate-query-as-ga entrySyntax validate-query-as-ga = {yes|no} Description Determines whether WebSEAL returns a "Bad Request" error when there is an invalid character present in the query portion of the URL. Options yesWebSEAL does not return a "Bad request" error when there is an invalid character present in the query portion of the URL.noWebSEAL returns a "Bad Request" error when there is an invalid character present in the query portion of the URL. Usage This stanza entry is optional. Default value no Example validate-query-as-ga = yes [server] stanza

validate-query-as-ga

Syntax

validate-query-as-ga = {yes|no}

Description

Determines whether WebSEAL returns a "Bad Request" error when there is an invalid character present in the query portion of the URL.

Options

yes

WebSEAL does not return a "Bad request" error when there is an invalid character present in the query portion of the URL.

no

WebSEAL returns a "Bad Request" error when there is an invalid character present in the query portion of the URL.

Usage

This stanza entry is optional.

Default value

no

Example

validate-query-as-ga = yes

Parent topic: [server] stanza

web-host-nameweb-host-nameweb-host-name stanza entryserver stanzaentriesweb-host-nameserver stanzaserver stanzaweb-host-name entrySyntax web-host-name = manually-set-webseal-hostnameDescription The manual setting for the WebSEAL server's host name.If left unset, WebSEAL attempts to automatically determine the server's host name. On systems with many hostnames, interfaces, or WebSEAL instances, the automatic determination may not always be correct. The manual setting for web-host-name resolves any conflicts.Options manually-set-webseal-hostnameThe manual setting for the WebSEAL server's host name, based on the fully qualified machine name.Usage This stanza entry is optional. Default value www.webseal.comExample web-host-name = abc.example.com[server] stanza

web-host-name

Syntax

web-host-name = manually-set-webseal-hostname

Description

The manual setting for the WebSEAL server's host name.If left unset, WebSEAL attempts to automatically determine the server's host name. On systems with many hostnames, interfaces, or WebSEAL instances, the automatic determination may not always be correct. The manual setting for web-host-name resolves any conflicts.

Options

manually-set-webseal-hostname

The manual setting for the WebSEAL server's host name, based on the fully qualified machine name.

Usage

This stanza entry is optional.

Default value

www.webseal.com

Example

web-host-name = abc.example.com

Parent topic: [server] stanza

web-http-portweb-http-portweb-http-port stanza entryserver stanzaentriesweb-http-portserver stanzaserver stanzaweb-http-port entrySyntax web-http-port = port for web-http-protocolDescription Defines the port that the client Web browser uses to connect to WebSEAL for requests that WebSEAL receives on a TCP interface.Options port for web-http-protocolUsage This stanza entry is optional.Default value same as HTTP portExample web-http-port = 443[server] stanza

web-http-port

Syntax

web-http-port = port for web-http-protocol

Description

Defines the port that the client Web browser uses to connect to WebSEAL for requests that WebSEAL receives on a TCP interface.

Options

port for web-http-protocol

Usage

This stanza entry is optional.

Default value

same as HTTP port

Example

web-http-port = 443

Parent topic: [server] stanza

web-http-protocolweb-http-protocolweb-http-protocol stanza entryserver stanzaentriesweb-http-protocolserver stanzaserver stanzaweb-http-protocol entrySyntax web-http-protocol = {http | https}Description Defines the protocol that the client Web browser uses to connect to WebSEAL for requests that WebSEAL receives on a TCP interface.Options httpWebSEAL functions will behave as if the client is connected to WebSEAL in an HTTP environment (not HTTPS).httpsMost WebSEAL functions will behave as if the client is connected to WebSEAL in an HTTPS environment. There are exceptions and limitations to this rule. You cannot obtain SSL IDs or SSL client certificates using this parameter; therefore, [session] ssl-id-sessions cannot be used as a session key and [certificate] accept-client-certs cannot be used for authentication.Usage This stanza entry is optional.Default value httpExample web-http-protocol = http[server] stanza

web-http-protocol

Syntax

web-http-protocol = {http | https}

Description

Defines the protocol that the client Web browser uses to connect to WebSEAL for requests that WebSEAL receives on a TCP interface.

Options

http

WebSEAL functions will behave as if the client is connected to WebSEAL in an HTTP environment (not HTTPS).

https

Most WebSEAL functions will behave as if the client is connected to WebSEAL in an HTTPS environment. There are exceptions and limitations to this rule. You cannot obtain SSL IDs or SSL client certificates using this parameter; therefore, [session] ssl-id-sessions cannot be used as a session key and [certificate] accept-client-certs cannot be used for authentication.

Usage

This stanza entry is optional.

Default value

http

Example

web-http-protocol = http

Parent topic: [server] stanza

worker-threadsworker-threadsworker-threads stanza entryserver stanzaentriesworker-threadsserver stanzaserver stanzaworker-threads entrySyntax worker-threads = number_of_threads Description Number of WebSEAL worker threads. Options number_of_threadsNumber of WebSEAL worker threads. The minimum value is 1. The maximum number of threads is based on the number of file descriptors set for WebSEAL at compile time. Note that this number varies per operating system. If the value is set to a number larger than the WebSEAL-determined limit, WebSEAL reduces the value to the acceptable limit and issues a warning message. Usage This stanza entry is required. Default value 300 Example worker-threads = 300 [server] stanza

worker-threads

Syntax

worker-threads = number_of_threads

Description

Number of WebSEAL worker threads.

Options

number_of_threads

Number of WebSEAL worker threads. The minimum value is 1. The maximum number of threads is based on the number of file descriptors set for WebSEAL at compile time. Note that this number varies per operating system. If the value is set to a number larger than the WebSEAL-determined limit, WebSEAL reduces the value to the acceptable limit and issues a warning message.

Usage

This stanza entry is required.

Default value

300

Example

worker-threads = 300

Parent topic: [server] stanza

[session] stanza[session] stanzasession stanzastanzassessionStanza referenceclient-identifierUse this entry to designate the client identifier for the session.dsess-enabledUse the dsess-enabled stanza entry to enable or disable the use of the distributed session cache.dsess-last-access-update-intervalUse the dsess-last-access-update-interval stanza entry to specify the frequency, in seconds, at which WebSEAL updates the session last access time at the distributed session cache.enforce-max-sessions-policyUse the enforce-max-sessions-policy stanza entry to control whether a specific WebSEAL instance enforces the max-concurrent-web-sessions policy. The max-concurrent-web-sessions policy controls the number of sessions each user can have at one time in a distributed session cache environment.inactive-timeoutlogout-remove-cookiemax-entriesprompt-for-displacementpreserve-inactivity-timeoutUse the preserve-inactivity-timeout stanza entry to designate the resources that should not impact the inactivity timeout for the session.preserve-inactivity-timeout-match-uriUse this configuration entry to control whether the patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request, or against the full request line.require-mparesend-webseal-cookiessend-constant-sessshared-domain-cookieUse the shared-domain-cookie stanza entry to share a cookie-based session across all standard and virtual host junctions on a single WebSEAL instance.ssl-id-sessionsssl-session-cookie-namestandard-junction-replica-setUse the standard-junction-replica-set stanza entry to specify the replica set to use for sessions that are created when users access standard WebSEAL junctions.tcp-session-cookie-nametemp-session-cookie-nametemp-session-max-lifetimetemp-session-one-time-useUse the temp-session-one-time-use stanza entry to control whether the client can access an entry in the temporary session cache a single time only or multiple times. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie.temp-session-overrides-unauth-sessionThis stanza entry controls the precedence if both a temporary session cookie and a standard session cookie are provided in a request.timeoutupdate-session-cookie-in-login-requestuser-session-idsuser-session-ids-include-replica-setuse-same-session

[session] stanza

client-identifier
Use this entry to designate the client identifier for the session.

dsess-enabled
Use the dsess-enabled stanza entry to enable or disable the use of the distributed session cache.

dsess-last-access-update-interval
Use the dsess-last-access-update-interval stanza entry to specify the frequency, in seconds, at which WebSEAL updates the session last access time at the distributed session cache.

enforce-max-sessions-policy
Use the enforce-max-sessions-policy stanza entry to control whether a specific WebSEAL instance enforces the max-concurrent-web-sessions policy. The max-concurrent-web-sessions policy controls the number of sessions each user can have at one time in a distributed session cache environment.

inactive-timeout

logout-remove-cookie

max-entries

prompt-for-displacement

preserve-inactivity-timeout
Use the preserve-inactivity-timeout stanza entry to designate the resources that should not impact the inactivity timeout for the session.

preserve-inactivity-timeout-match-uri
Use this configuration entry to control whether the patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request, or against the full request line.

require-mpa

resend-webseal-cookies

send-constant-sess

shared-domain-cookie
Use the shared-domain-cookie stanza entry to share a cookie-based session across all standard and virtual host junctions on a single WebSEAL instance.

ssl-id-sessions

ssl-session-cookie-name

standard-junction-replica-set
Use the standard-junction-replica-set stanza entry to specify the replica set to use for sessions that are created when users access standard WebSEAL junctions.

tcp-session-cookie-name

temp-session-cookie-name

temp-session-max-lifetime

temp-session-one-time-use
Use the temp-session-one-time-use stanza entry to control whether the client can access an entry in the temporary session cache a single time only or multiple times. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie.

temp-session-overrides-unauth-session
This stanza entry controls the precedence if both a temporary session cookie and a standard session cookie are provided in a request.

timeout

update-session-cookie-in-login-request

user-session-ids

user-session-ids-include-replica-set

use-same-session

Parent topic: Stanza reference

client-identifierUse this entry to designate the client identifier for the session.client-identifier stanza entrysession stanzaentriesclient-identifiersession stanzasession stanzaclient-identifier entrySyntax client-identifier = client_identifier_valueDescription This identifier is added to the credential as the client_identifier attribute and is validated on subsequent requests to ensure that the client does not change.Options client_identifier_valueThe client identifier value can be in either of the following formats:CLIENT_IPThe client IP address from the network connection is used as the identifier.HTTPHDR{<name>}The contents of the HTTP header, which is identified by <name>, is used as the client identifier. If the HTTP header is missing on the initial request, no identifier is added for the session. Usage This stanza entry is optional. If failover cookies are used, add the client_identifier credential attribute to the failover cookie by modifying the [failover-add-attributes] and [failover-restore-attributes] stanzas. This step ensures that the client identifier can persist across a failover event.Default value NoneExample client-identifier = CLIENT_IP client-identifier = HTTPHDR{X-Forwarded-For}[session] stanza

client-identifier

Use this entry to designate the client identifier for the session.

Syntax

client-identifier = client_identifier_value

Description

This identifier is added to the credential as the client_identifier attribute and is validated on subsequent requests to ensure that the client does not change.

Options

client_identifier_value

The client identifier value can be in either of the following formats:

CLIENT_IP

The client IP address from the network connection is used as the identifier.

HTTPHDR{<name>}

The contents of the HTTP header, which is identified by <name>, is used as the client identifier. If the HTTP header is missing on the initial request, no identifier is added for the session.

Usage

This stanza entry is optional.

Note: If failover cookies are used, add the client_identifier credential attribute to the failover cookie by modifying the [failover-add-attributes] and [failover-restore-attributes] stanzas. This step ensures that the client identifier can persist across a failover event.

Default value

None

Example

client-identifier = CLIENT_IP
client-identifier = HTTPHDR{X-Forwarded-For}

Parent topic: [session] stanza

dsess-enableddsess-enabledIBM Security Access Manager for Web WebSEAL dsess-enabled stanza entryUse the dsess-enabled stanza entry to enable or disable the use of the distributed session cache.dsess-enabled stanza entrysession stanzaentriesdsess-enabledsession stanzasession stanzadsess-enabled entrySyntax dsess-enabled = {yes|no} Description Enable or disable use of the distributed session cache. Options yesEnable use of the distributed session cache. If this is set to yes the [dsess] stanza must have information about how to communicate with the distributed session cache.noDisable use of the distributed session cache. Usage This stanza entry is optional. Default value no Example dsess-enabled = no [session] stanza

dsess-enabled

Use the dsess-enabled stanza entry to enable or disable the use of the distributed session cache.

Syntax

dsess-enabled = {yes|no}

Description

Enable or disable use of the distributed session cache.

Options

yes

Enable use of the distributed session cache. If this is set to yes the [dsess] stanza must have information about how to communicate with the distributed session cache.

no

Disable use of the distributed session cache.

Usage

This stanza entry is optional.

Default value

no

Example

dsess-enabled = no

Parent topic: [session] stanza

dsess-last-access-update-intervaldsess-last-access-update-intervalIBM Security Access Manager for Web WebSEAL dsess-last-access-update-interval stanza entryUse the dsess-last-access-update-interval stanza entry to specify the frequency, in seconds, at which WebSEAL updates the session last access time at the distributed session cache.dsess-last-access-update-interval stanza entrysession stanzaentriesdsess-last-access-update-intervalsession stanzasession stanzadsess-last-access-update-interval entrySyntax dsess-last-access-update-interval = seconds Description Specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache. Options secondsSmaller values offer more accurate inactivity timeout tracking, at the expense of sending updates to the distributed session cache more frequently. Values of less than 1 second are not permitted. Usage This stanza entry is required. Default value 60 Example dsess-last-access-update-interval = 60 [session] stanza

dsess-last-access-update-interval

Use the dsess-last-access-update-interval stanza entry to specify the frequency, in seconds, at which WebSEAL updates the session last access time at the distributed session cache.

Syntax

dsess-last-access-update-interval = seconds

Description

Specifies the frequency at which WebSEAL updates the session last access time at the distributed session cache.

Options

seconds

Smaller values offer more accurate inactivity timeout tracking, at the expense of sending updates to the distributed session cache more frequently. Values of less than 1 second are not permitted.

Usage

This stanza entry is required.

Default value

60

Example

dsess-last-access-update-interval = 60

Parent topic: [session] stanza

enforce-max-sessions-policyenforce-max-sessions-policyIBM Security Access Manager for Web WebSEAL enforce-max-sessions-policy stanza entryUse the enforce-max-sessions-policy stanza entry to control whether a specific WebSEAL instance enforces the max-concurrent-web-sessions policy. The max-concurrent-web-sessions policy controls the number of sessions each user can have at one time in a distributed session cache environment.enforce-max-sessions-policy stanza entrysession stanzaentriesenforce-max-sessions-policysession stanzasession stanzaenforce-max-sessions-policy entrySyntax enforce-max-sessions-policy = {yes|no} Description Control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy. Options yesEnforce the max-concurrent-web-sessions policy.noDo not enforce the max-concurrent-web-sessions policy. Usage This stanza entry is ignored unless WebSEAL is using the distributed session cache for session storage. Default value yes Example enforce-max-sessions-policy = yes [session] stanza

enforce-max-sessions-policy

Use the enforce-max-sessions-policy stanza entry to control whether a specific WebSEAL instance enforces the max-concurrent-web-sessions policy. The max-concurrent-web-sessions policy controls the number of sessions each user can have at one time in a distributed session cache environment.

Syntax

enforce-max-sessions-policy = {yes|no}

Description

Control whether or not a specific WebSEAL instance enforces the max-concurrent-web-sessions policy.

Options

yes

Enforce the max-concurrent-web-sessions policy.

no

Do not enforce the max-concurrent-web-sessions policy.

Usage

This stanza entry is ignored unless WebSEAL is using the distributed session cache for session storage.

Default value

yes

Example

enforce-max-sessions-policy = yes

Parent topic: [session] stanza

inactive-timeoutinactive-timeoutinactive-timeout stanza entrysession stanzaentriesinactive-timeoutsession stanzasession stanzainactive-timeout entrySyntax inactive-timeout = number_of_secondsDescription Integer value for lifetime, in seconds, of inactive entries in the credential cache. The value can be configured for a specific session cache (authenticated or unauthenticated) by adding an additional entry, prefixedby auth or unauth.Options number_of_secondsThe minimum number for this value is 0. WebSEAL does not impose a maximum value. A stanza entry value of "0" disables this inactivity timeout feature (inactivity timeout value is unlimited). The control of cache entries is then governed by the timeout and max-entries stanza entries. When a cache is full, the entries are cleared based on a least-recently-used algorithm. Usage This stanza entry is required.Default value 600Example inactive-timeout = 600 unauth-inactive-timeout = 300[session] stanza

inactive-timeout

Syntax

inactive-timeout = number_of_seconds

Description

Integer value for lifetime, in seconds, of inactive entries in the credential cache.

The value can be configured for a specific session cache (authenticated or unauthenticated) by adding an additional entry, prefixedby auth or unauth.

Options

number_of_seconds

The minimum number for this value is 0. WebSEAL does not impose a maximum value.

A stanza entry value of "0" disables this inactivity timeout feature (inactivity timeout value is unlimited). The control of cache entries is then governed by the timeout and max-entries stanza entries.

When a cache is full, the entries are cleared based on a least-recently-used algorithm.

Usage

This stanza entry is required.

Default value

600

Example

inactive-timeout = 600
unauth-inactive-timeout = 300

Parent topic: [session] stanza

logout-remove-cookielogout-remove-cookielogout-remove-cookie stanza entrysession stanzaentrieslogout-remove-cookiesession stanzasession stanzalogout-remove-cookie entrySyntax logout-remove-cookie = {yes|no}Description Specifies whether or not to remove the session cookie from a user's browser when the user logs out from the WebSEAL domain. Setting this stanza entry to yes is necessary for the correct operation and use of the %OLDSESSION% macro.Options yesRemove the session cookie from a user's browser when the user logs out from the WebSEAL domain.noDo not remove the session cookie from a user's browser when the user logs out from the WebSEAL domain.Usage This stanza entry is required.Default value noExample logout-remove-cookie = no[session] stanza

logout-remove-cookie

Syntax

logout-remove-cookie = {yes|no}

Description

Specifies whether or not to remove the session cookie from a user's browser when the user logs out from the WebSEAL domain. Setting this stanza entry to yes is necessary for the correct operation and use of the %OLDSESSION% macro.

Options

yes

Remove the session cookie from a user's browser when the user logs out from the WebSEAL domain.

no

Do not remove the session cookie from a user's browser when the user logs out from the WebSEAL domain.

Usage

This stanza entry is required.

Default value

no

Example

logout-remove-cookie = no

Parent topic: [session] stanza

max-entriesmax-entriesmax-entries stanza entrysession stanzaentriesmax-entriessession stanzasession stanzamax-entries entrySyntax max-entries = number_of_entriesDescription Maximum number of concurrent entries in the credentials cache. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm to allow new incoming logins. The value can be configured for a specific session cache (authenticated or unauthenticated) by adding an additional entry, prefixedby auth or unauth.Options number_of_entriesThe following conditions affect the specified value: If the specified value is less than or equal to 0, the cache size becomes unlimited.If the specified value is between 0 and 8192, the actual number of entries allowed is rounded up to the next multiple of 32.Any specified value greater than 8192 is accepted as given. WebSEAL does not impose a maximum value. Usage This stanza entry is required.Default value 4096Example max-entries = 4096 unauth-max-entries = 1024[session] stanza

max-entries

Syntax

max-entries = number_of_entries

Description

Maximum number of concurrent entries in the credentials cache. When the cache size reaches this value, entries are removed from the cache according to a least recently used algorithm to allow new incoming logins.

The value can be configured for a specific session cache (authenticated or unauthenticated) by adding an additional entry, prefixedby auth or unauth.

Options

number_of_entries

The following conditions affect the specified value:

If the specified value is less than or equal to 0, the cache size becomes unlimited.

If the specified value is between 0 and 8192, the actual number of entries allowed is rounded up to the next multiple of 32.

Any specified value greater than 8192 is accepted as given.

WebSEAL does not impose a maximum value.

Usage

This stanza entry is required.

Default value

4096

Example

max-entries = 4096
unauth-max-entries = 1024

Parent topic: [session] stanza

prompt-for-displacementprompt-for-displacementprompt-for-displacement stanza entrysession stanzaentriesprompt-for-displacementsession stanzasession stanzaprompt-for-displacement entrySyntax prompt-for-displacement = {yes|no}Description Determines whether or not a user is prompted for appropriate action when the max-concurrent-web-sessions displace policy has been exceeded.Options yesEnables the interactive option, where the user is prompted for appropriate action. When a second login is attempted, the user receives the too_many_sessions.html response page.noEnables the non-interactive option, where the user is not prompted for appropriate action. When a second login is attempted, the original (older) login session is automatically terminated with no prompt. A new session is created for the user and the user is logged in to this new session transparently. The original (older) session is no longer valid.Usage This stanza entry is required.Default value yesExample prompt-for-displacement = yes[session] stanza

prompt-for-displacement

Syntax

prompt-for-displacement = {yes|no}

Description

Determines whether or not a user is prompted for appropriate action when the max-concurrent-web-sessions displace policy has been exceeded.

Options

yes

Enables the interactive option, where the user is prompted for appropriate action. When a second login is attempted, the user receives the too_many_sessions.html response page.

no

Enables the non-interactive option, where the user is not prompted for appropriate action. When a second login is attempted, the original (older) login session is automatically terminated with no prompt. A new session is created for the user and the user is logged in to this new session transparently. The original (older) session is no longer valid.

Usage

This stanza entry is required.

Default value

yes

Example

prompt-for-displacement = yes

Parent topic: [session] stanza

preserve-inactivity-timeout preserve-inactivity-timeout Use the preserve-inactivity-timeout stanza entry to designate the resources that should not impact the inactivity timeout for the session.preserve-inactivity-timeoutlogging stanzaentriespreserve-inactivity-timeoutlogging stanzahttp-transformations: resource-name stanzapreserve-inactivity-timeoutSyntax preserve-inactivity-timeout = uri Description In some circumstances, you might not want the requests for a particular resource to affect the inactivity timeout for a session. For example, you might want to preserve the inactivity timeout when a server is polled by an Ajax script running in the background of a client browser. This configuration entry can be used to designate the resources which, when accessed, should not impact the inactivity timeout for the session. A comparison will be performed against either the full HTTP request line or the decoded URI (controlled by the preserve-inactivity-timeout-match-uri configuration entry). If a match is found, the inactivity timeout for the session will not be affected by the request. Multiple patterns can be specified by including multiple configuration entries of the same name. You also have the option of matching a request by using a host header. This option is useful when you need to selectively enable this functionality for a particular virtual host junction. To selectively match an entry based on a particular host header, prepend the configuration entry with the string [<host>]. Options uriThe URI to pattern match against. Usage This stanza entry is optional. Default value Not applicable. Example preserve-inactivity-timeout = /jct/robot/* preserve-inactivity-timeout = [www.ibm.com]/robot/* [session] stanza

preserve-inactivity-timeout

Use the preserve-inactivity-timeout stanza entry to designate the resources that should not impact the inactivity timeout for the session.

Syntax

 preserve-inactivity-timeout = uri

Description

In some circumstances, you might not want the requests for a particular resource to affect the inactivity timeout for a session. For example, you might want to preserve the inactivity timeout when a server is polled by an Ajax script running in the background of a client browser. This configuration entry can be used to designate the resources which, when accessed, should not impact the inactivity timeout for the session. A comparison will be performed against either the full HTTP request line or the decoded URI (controlled by the preserve-inactivity-timeout-match-uri configuration entry). If a match is found, the inactivity timeout for the session will not be affected by the request. Multiple patterns can be specified by including multiple configuration entries of the same name.

You also have the option of matching a request by using a host header. This option is useful when you need to selectively enable this functionality for a particular virtual host junction. To selectively match an entry based on a particular host header, prepend the configuration entry with the string [<host>].

Options

uri

The URI to pattern match against.

Usage

This stanza entry is optional.

Default value

Not applicable.

Example

preserve-inactivity-timeout = /jct/robot/*
preserve-inactivity-timeout = [www.ibm.com]/robot/*

Parent topic: [session] stanza

preserve-inactivity-timeout-match-uriUse this configuration entry to control whether the patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request, or against the full request line.Syntax preserve-inactivity-timeout-match-uri = {true|false}Description This configuration entry controls whether the patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request, or against the full request line.Options trueThe patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request.falseThe patterns specified by the preserve-inactivity-timeout configuration entry are matched against the full request line.Usage This stanza entry is optional.Default value trueExample preserve-inactivity-timeout-match-uri = true[session] stanza

preserve-inactivity-timeout-match-uri

Use this configuration entry to control whether the patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request, or against the full request line.

Syntax

 preserve-inactivity-timeout-match-uri = {true|false}

Description

This configuration entry controls whether the patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request, or against the full request line.

Options

true

The patterns specified by the preserve-inactivity-timeout configuration entry are matched against the decoded URI from the request.

false

The patterns specified by the preserve-inactivity-timeout configuration entry are matched against the full request line.

Usage

This stanza entry is optional.

Default value

true

Example

preserve-inactivity-timeout-match-uri = true

Parent topic: [session] stanza

require-mparequire-mparequire-mpa stanza entrysession stanzaentriesrequire-mpasession stanzasession stanzarequire-mpa entrySyntax require-mpa = {yes|no}Description Controls whether WebSEAL accepts HTTP headers from requests that are proxied through an authenticated multiplexing proxy agent (MPA).Options yesWebSEAL only accepts HTTP headers from requests that are proxied through an authenticated multiplexing proxy agent (MPA).noWebSEAL accepts HTTP headers under any condition.Usage This stanza entry is required.Default value yesExample require-mpa = yes[session] stanza

require-mpa

Syntax

require-mpa = {yes|no}

Description

Controls whether WebSEAL accepts HTTP headers from requests that are proxied through an authenticated multiplexing proxy agent (MPA).

Options

yes

WebSEAL only accepts HTTP headers from requests that are proxied through an authenticated multiplexing proxy agent (MPA).

no

WebSEAL accepts HTTP headers under any condition.

Usage

This stanza entry is required.

Default value

yes

Example

require-mpa = yes

Parent topic: [session] stanza

resend-webseal-cookiesresend-webseal-cookiesresend-webseal-cookies stanza entrysession stanzaentriesresend-webseal-cookiessession stanzasession stanzaresend-webseal-cookies entrySyntax resend-webseal-cookies = {yes|no}Description When you configure WebSEAL to use session cookies, specifies whether or not WebSEAL sends the session cookie to the browser with every response.Options yesSpecifies that WebSEAL sends the session cookie to the browser with every response. This action helps to ensure that the session cookie remains in the browser memory.noSpecifies that WebSEAL does not send the session cookie to the browser with every response.Usage This stanza entry is required.Default value noExample resend-webseal-cookies = no[session] stanza

resend-webseal-cookies

Syntax

resend-webseal-cookies = {yes|no}

Description

When you configure WebSEAL to use session cookies, specifies whether or not WebSEAL sends the session cookie to the browser with every response.

Options

yes

Specifies that WebSEAL sends the session cookie to the browser with every response. This action helps to ensure that the session cookie remains in the browser memory.

no

Specifies that WebSEAL does not send the session cookie to the browser with every response.

Usage

This stanza entry is required.

Default value

no

Example

resend-webseal-cookies = no

Parent topic: [session] stanza

send-constant-sesssend-constant-sesssend-constant-sess stanza entrysession stanzaentriessend-constant-sesssession stanzasession stanzasend-constant-sess entrySyntax send-constant-sess = {yes|no}Description Determines whether a session cookie containing a separate, constant identifier is issued during step-up operations to enable tracking for each authenticated session. The identifier remains constant across a single session, regardless of whether the session key changes. The name of the cookie is that of the actual session code appended with the suffix -2, for example, PD_S_SESSION_ID_2. This feature is intended to augment the -k junction option.Options yesA session cookie containing a separate, constant identifier is issued during step-up operations to allow tracking for each authenticated session.noNo session cookie is issued during step-up operations.Usage This stanza entry is required.Default value noExample send-constant-sess = no[session] stanza

send-constant-sess

Syntax

send-constant-sess = {yes|no}

Description

Determines whether a session cookie containing a separate, constant identifier is issued during step-up operations to enable tracking for each authenticated session. The identifier remains constant across a single session, regardless of whether the session key changes. The name of the cookie is that of the actual session code appended with the suffix -2, for example, PD_S_SESSION_ID_2. This feature is intended to augment the -k junction option.

Options

yes

A session cookie containing a separate, constant identifier is issued during step-up operations to allow tracking for each authenticated session.

no

No session cookie is issued during step-up operations.

Usage

This stanza entry is required.

Default value

no

Example

send-constant-sess = no

Parent topic: [session] stanza

shared-domain-cookieshared-domain-cookieUse the shared-domain-cookie stanza entry to share a cookie-based session across all standard and virtual host junctions on a single WebSEAL instance.shared-domain-cookie stanza entrysession stanzaentriesshared-domain-cookiesession stanzasession stanzashared-domain-cookie entrySyntax shared-domain-cookie = {yes | no} Description Enables a cookie-based session to be shared across all standard and virtual host junctions on a single WebSEAL instance. To share a session in this manner, the WebSEAL instance must store a single session key as an independent value in a multi-valued domain cookie. The multi-valued domain cookie must be indexed by the instance name. The domain cookie itself is shared across all participating WebSEAL instances, but the session values are specific to each instance.If WebSEAL exists in an environment where the distributed session cache already handles single sign-on across domains, do not enable this configuration item. Options yesEnables single sign-on across virtual host junctions in the same WebSEAL instance.noDisables single sign-on across virtual host junctions in WebSEAL. Usage This stanza entry is optional. Default value no Example shared-domain-cookie = yes [session] stanza

shared-domain-cookie

Use the shared-domain-cookie stanza entry to share a cookie-based session across all standard and virtual host junctions on a single WebSEAL instance.

Syntax

shared-domain-cookie = {yes | no}

Description

Enables a cookie-based session to be shared across all standard and virtual host junctions on a single WebSEAL instance. To share a session in this manner, the WebSEAL instance must store a single session key as an independent value in a multi-valued domain cookie. The multi-valued domain cookie must be indexed by the instance name.

The domain cookie itself is shared across all participating WebSEAL instances, but the session values are specific to each instance.

If WebSEAL exists in an environment where the distributed session cache already handles single sign-on across domains, do not enable this configuration item.

Options

yes

Enables single sign-on across virtual host junctions in the same WebSEAL instance.

no

Disables single sign-on across virtual host junctions in WebSEAL.

Usage

This stanza entry is optional.

Default value

no

Example

shared-domain-cookie = yes

Parent topic: [session] stanza

ssl-id-sessionsssl-id-sessionsssl-id-sessions stanza entrysession stanzaentriesssl-id-sessionssession stanzasession stanzassl-id-sessions entrySyntax ssl-id-sessions = {yes|no}Description Indicates whether to use the SSL ID to maintain a user's HTTP login session.Options yesUse the SSL ID to maintain a user's HTTP login session.noDo not use the SSL ID to maintain a user's HTTP login session. This value must be set to no when the following key = value pair is set: [certificate] accept-client-certs = prompt_as_neededUsage This stanza entry is required.Default value yesExample ssl-id-sessions = yes[session] stanza

ssl-id-sessions

Syntax

ssl-id-sessions = {yes|no}

Description

Indicates whether to use the SSL ID to maintain a user's HTTP login session.

Options

yes

Use the SSL ID to maintain a user's HTTP login session.

no

Do not use the SSL ID to maintain a user's HTTP login session. This value must be set to no when the following key = value pair is set:

[certificate]
accept-client-certs = prompt_as_needed

Usage

This stanza entry is required.

Default value

yes

Example

ssl-id-sessions = yes

Parent topic: [session] stanza

ssl-session-cookie-namessl-session-cookie-namessl-session-cookie-name stanza entrysession stanzaentriesssl-session-cookie-namesession stanzasession stanzassl-session-cookie-name entrySyntax ssl-session-cookie-name = nameDescription Specifies the default or custom name of WebSEAL session cookies.Options nameSpecifies the default or custom name of WebSEAL session cookies.Usage This stanza entry is required.Default value PD-S-SESSION-IDExample ssl-session-cookie-names = PD-S-SESSION-ID[session] stanza

ssl-session-cookie-name

Syntax

ssl-session-cookie-name = name

Description

Specifies the default or custom name of WebSEAL session cookies.

Options

name

Specifies the default or custom name of WebSEAL session cookies.

Usage

This stanza entry is required.

Default value

PD-S-SESSION-ID

Example

ssl-session-cookie-names = PD-S-SESSION-ID

Parent topic: [session] stanza

standard-junction-replica-setstandard-junction-replica-setUse the standard-junction-replica-set stanza entry to specify the replica set to use for sessions that are created when users access standard WebSEAL junctions.standard-junction-replica-set stanza entrysession stanzaentriesstandard-junction-replica-setsession stanzasession stanzastandard-junction-replica-set entrySyntax standard-junction-replica-set = replica_set_name Description The replica set to use for sessions created when users access standard WebSEAL junctions. Virtual host junctions either use the replica set specified with the virtualhost create -z option or the virtual host name for the junction. If you are using the distributed session cache for session storage, the replica set specified here must also be specified in the [replica-sets] stanza. Options valueReplica set name. Usage This stanza entry is required. Default value default Example standard-junction-replica-set = default [session] stanza

standard-junction-replica-set

Use the standard-junction-replica-set stanza entry to specify the replica set to use for sessions that are created when users access standard WebSEAL junctions.

Syntax

standard-junction-replica-set = replica_set_name

Description

The replica set to use for sessions created when users access standard WebSEAL junctions. Virtual host junctions either use the replica set specified with the virtualhost create -z option or the virtual host name for the junction.

If you are using the distributed session cache for session storage, the replica set specified here must also be specified in the [replica-sets] stanza.

Options

value

Replica set name.

Usage

This stanza entry is required.

Default value

default

Example

standard-junction-replica-set = default

Parent topic: [session] stanza

tcp-session-cookie-nametcp-session-cookie-nametcp-session-cookie-name stanza entrysession stanzaentriestcp-session-cookie-namesession stanzasession stanzatcp-session-cookie-name entrySyntax tcp-session-cookie-name = nameDescription Specifies the default or custom name of WebSEAL session cookies.Options nameSpecifies the default or custom name of WebSEAL session cookies.Usage This stanza entry is required.Default value PD-H-SESSION-IDExample tcp-session-cookie-name = PD-H-SESSION-ID[session] stanza

tcp-session-cookie-name

Syntax

tcp-session-cookie-name = name

Description

Specifies the default or custom name of WebSEAL session cookies.

Options

name

Specifies the default or custom name of WebSEAL session cookies.

Usage

This stanza entry is required.

Default value

PD-H-SESSION-ID

Example

tcp-session-cookie-name = PD-H-SESSION-ID

Parent topic: [session] stanza

temp-session-cookie-nametemp-session-cookie-nametemp-session-cookie-name stanza entrysession stanzaentriestemp-session-cookie-namesession stanzasession stanzatemp-session-cookie-name entrySyntax temp-session-cookie-name = cookie_name Description Sets the name of the temporary session cookie that is created for session sharing with Microsoft Office applications. WebSEAL creates a temporary cookie with this name when it responds to a /pkmstempsession management page request. Options cookie_nameA string value that represents the name of the temporary cookie that WebSEAL uses to store session information. This configuration entry must be used in conjunction with a non-zero value for the temp-session-max-lifetime entry, which is also in the [session] stanza. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy. Usage This stanza entry is required. Default value None. Example temp-session-cookie-name = PD-TEMP-SESSION-ID [session] stanza

temp-session-cookie-name

Syntax

temp-session-cookie-name = cookie_name

Description

Sets the name of the temporary session cookie that is created for session sharing with Microsoft Office applications. WebSEAL creates a temporary cookie with this name when it responds to a /pkmstempsession management page request.

Options

cookie_name

A string value that represents the name of the temporary cookie that WebSEAL uses to store session information.

Note: This configuration entry must be used in conjunction with a non-zero value for the temp-session-max-lifetime entry, which is also in the [session] stanza. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Usage

This stanza entry is required.

Default value

None.

Example

temp-session-cookie-name = PD-TEMP-SESSION-ID

Parent topic: [session] stanza

temp-session-max-lifetimetemp-session-max-lifetimetemp-session-max-lifetime stanza entrysession stanzaentriestemp-session-max-lifetimesession stanzasession stanzatemp-session-max-lifetime entrySyntax temp-session-max-lifetime = number_of_seconds Description Positive integer that expresses the maximum lifetime (in seconds) of entries in the temporary session cache. Options number_of_secondsA positive integer that represents the maximum lifetime in seconds. Specify a value of 0 to disable the temporary session cache. A non-zero value must be configured to enable session sharing with Microsoft Office applications. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy. Usage This stanza entry is optional. Default value None. Example temp-session-max-lifetime = 10 [session] stanza

temp-session-max-lifetime

Syntax

temp-session-max-lifetime = number_of_seconds

Description

Positive integer that expresses the maximum lifetime (in seconds) of entries in the temporary session cache.

Options

number_of_seconds

A positive integer that represents the maximum lifetime in seconds. Specify a value of 0 to disable the temporary session cache.

Note: A non-zero value must be configured to enable session sharing with Microsoft Office applications. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Usage

This stanza entry is optional.

Default value

None.

Example

temp-session-max-lifetime = 10

Parent topic: [session] stanza

temp-session-one-time-usetemp-session-one-time-useIBM Security Access Manager for Web WebSEAL temp-session-one-time-use stanza entryUse the temp-session-one-time-use stanza entry to control whether the client can access an entry in the temporary session cache a single time only or multiple times. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie.temp-session-one-time-use stanza entrysession stanzaentriestemp-session-one-time-usesession stanzasession stanzatemp-session-one-time-use entrySyntax temp-session-one-time-use = {true|false} Description WebSEAL creates a temporary session cookie for session sharing with Microsoft Office applications when it responds to a /pkmstempsession management page request.The temp-session-one-time-use configuration entry determines whether this cookie can be used a single time or whether it can be used multiple times.This configuration entry must be used with the temp-session-cookie-name and temp-session-max-lifetime entries, which are also in the [session] stanza. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy. Options trueThe cookie that stores the session information is a single use cookie. The session entry is invalidated and removed from the cache after a single use.falseThe client can use the cookie multiple times to request the session information. The session times out after the configured temp-session-max-lifetime expires. Use this setting if you want to share sessions with Microsoft Office applications, such as Microsoft SharePoint. Usage This stanza entry is required. Default value false Example temp-session-one-time-use = false [session] stanza

temp-session-one-time-use

Use the temp-session-one-time-use stanza entry to control whether the client can access an entry in the temporary session cache a single time only or multiple times. If you are sharing sessions with Microsoft Office applications, configure WebSEAL to accept multiple accesses to the temporary session cookie.

Syntax

temp-session-one-time-use = {true|false}

Description

WebSEAL creates a temporary session cookie for session sharing with Microsoft Office applications when it responds to a /pkmstempsession management page request.

The temp-session-one-time-use configuration entry determines whether this cookie can be used a single time or whether it can be used multiple times.

Note: This configuration entry must be used with the temp-session-cookie-name and temp-session-max-lifetime entries, which are also in the [session] stanza. For more information about sharing sessions with Microsoft Office applications, see the IBM Security Web Gateway appliance: Configuration Guide for Web Reverse Proxy.

Options

true

The cookie that stores the session information is a single use cookie. The session entry is invalidated and removed from the cache after a single use.

false

The client can use the cookie multiple times to request the session information. The session times out after the configured temp-session-max-lifetime expires. Use this setting if you want to share sessions with Microsoft Office applications, such as Microsoft SharePoint.

Usage

This stanza entry is required.

Default value

false

Example

temp-session-one-time-use = false

Parent topic: [session] stanza

temp-session-overrides-unauth-sessionThis stanza entry controls the precedence if both a temporary session cookie and a standard session cookie are provided in a request.temp-session-overrides-unauth-session stanza entrysession stanzaentriestemp-session-overrides-unauth-sessionsession stanzasession stanzatemp-session-overrides-unauth-session entrySyntax temp-session-overrides-unauth-session = {yes|no}Description The temp-session-overrides-unauth-session configuration entry controls whether a temporary session cookie takes precedence over a standard session cookie for an unauthenticated session. Options yes A temporary session takes precedence over an existing unauthenticated session, but not an authenticated session.noA temporary session cookie is ignored if a standard session cookie exists. Usage This stanza entry is optional.Default value noExample temp-session-overrides-unauth-session = no[session] stanza

temp-session-overrides-unauth-session

This stanza entry controls the precedence if both a temporary session cookie and a standard session cookie are provided in a request.

Syntax

temp-session-overrides-unauth-session = {yes|no}

Description

The temp-session-overrides-unauth-session configuration entry controls whether a temporary session cookie takes precedence over a standard session cookie for an unauthenticated session.

Options

yes

A temporary session takes precedence over an existing unauthenticated session, but not an authenticated session.

no

A temporary session cookie is ignored if a standard session cookie exists.

Usage

This stanza entry is optional.

Default value

no

Example

temp-session-overrides-unauth-session = no

Parent topic: [session] stanza

timeouttimeouttimeout stanza entrysession stanzaentriestimeoutsession stanzasession stanzatimeout entrySyntax timeout = number_of_secondsDescription Integer value for maximum lifetime, in seconds, for an entry in the credential cache. The value can be configured for a specific session cache (authenticated or unauthenticated) by adding an additional entry, prefixedby auth or unauth.Options number_of_secondsThe minimum number for this value is 0. WebSEAL does not impose a maximum value. A stanza entry value of "0" disables this timeout feature (lifetime value is unlimited). The control of cache entries is then governed by the inactive-timeout and max-entries stanza entries. When the cache is full, the entries are cleared based on a least-recently-used algorithm. Usage This stanza entry is required.Default value 3600Example timeout = 3600 unauth-timeout = 600[session] stanza

timeout

Syntax

timeout = number_of_seconds

Description

Integer value for maximum lifetime, in seconds, for an entry in the credential cache.

The value can be configured for a specific session cache (authenticated or unauthenticated) by adding an additional entry, prefixedby auth or unauth.

Options

number_of_seconds

The minimum number for this value is 0. WebSEAL does not impose a maximum value.

A stanza entry value of "0" disables this timeout feature (lifetime value is unlimited). The control of cache entries is then governed by the inactive-timeout and max-entries stanza entries.

When the cache is full, the entries are cleared based on a least-recently-used algorithm.

Usage

This stanza entry is required.

Default value

3600

Example

timeout = 3600
unauth-timeout = 600

Parent topic: [session] stanza

update-session-cookie-in-login-requestupdate-session-cookie-in-login-requestupdate-session-cookie-in-login-request stanza entrysession stanzaentriesupdate-session-cookie-in-login-requestsession stanzasession stanzaupdate-session-cookie-in-login-request entrySyntax update-session-cookie-in-login-request = {yes|no}Description Controls whether the existing session cookie, found in the HTTP request, is updated if the session ID is modified during the processing of the request.Options yesThe existing session cookie is updated if the session ID is modified during the processing of the request.noThe existing session cookie is not updated if the session ID is modified during the processing of the request.Usage This stanza entry is optional.Default value noExample update-session-cookie-in-login-request = no[session] stanza

update-session-cookie-in-login-request

Syntax

update-session-cookie-in-login-request = {yes|no}

Description

Controls whether the existing session cookie, found in the HTTP request, is updated if the session ID is modified during the processing of the request.

Options

yes

The existing session cookie is updated if the session ID is modified during the processing of the request.

no

The existing session cookie is not updated if the session ID is modified during the processing of the request.

Usage

This stanza entry is optional.

Default value

no

Example

update-session-cookie-in-login-request = no

Parent topic: [session] stanza

user-session-idsuser-session-idsuser-session-ids stanza entrysession stanzaentriesuser-session-idssession stanzasession stanzauser-session-ids entrySyntax user-session-ids = {yes|no}Description Enables or disables the creation and handling of user session IDs.Options yesEnables the creation and handling of user session IDs.noDisables the creation and handling of user session IDs.Usage This stanza entry is required.Default value noExample user-session-ids = yes[session] stanza

user-session-ids

Syntax

user-session-ids = {yes|no}

Description

Enables or disables the creation and handling of user session IDs.

Options

yes

Enables the creation and handling of user session IDs.

no

Disables the creation and handling of user session IDs.

Usage

This stanza entry is required.

Default value

no

Example

user-session-ids = yes

Parent topic: [session] stanza

user-session-ids-include-replica-setuser-session-ids-include-replica-setuser-session-ids-include-replica-set stanza entrysession stanzaentriesuser-session-ids-include-replica-setsession stanzasession stanzauser-session-ids-include-replica-set entrySyntax user-session-ids-include-replica-set = {yes|no}Description Include the replica set in the user session ID.Options yesIf set to "yes", then user-session-ids = yes includes the replica set.noIf set to "no", then WebSEAL does not include the replica set for user-session-ids = yes and assumes that any user session specified in the pdadmin terminate session command belongs to the default replica set.Usage This stanza entry is required.Default value yesExample user-session-ids-include-replica-set = yes[session] stanza

user-session-ids-include-replica-set

Syntax

user-session-ids-include-replica-set = {yes|no}

Description

Include the replica set in the user session ID.

Options

yes

If set to "yes", then user-session-ids = yes includes the replica set.

no

If set to "no", then WebSEAL does not include the replica set for user-session-ids = yes and assumes that any user session specified in the pdadmin terminate session command belongs to the default replica set.

Usage

This stanza entry is required.

Default value

yes

Example

user-session-ids-include-replica-set = yes

Parent topic: [session] stanza

use-same-sessionuse-same-sessionuse-same-session stanza entrysession stanzaentriesuse-same-sessionsession stanzasession stanzause-same-session entrySyntax use-same-session = {yes|no}Description Indicates whether to use the same session for SSL and HTTP clients.Options yesWhen set to yes, a user who has authenticated over HTTP will be authenticated when connecting over HTTPS. Likewise, the user who has authenticated over HTTPS will be authenticated when connecting over HTTP. Using yes will override ssl-id-sessions = yes, because HTTP clients do not read an SSL ID to maintain sessions.no Do not use the same session for SSL and HTTP clients.Usage This stanza entry is required.Default value noExample use-same-session = no[session] stanza

use-same-session

Syntax

use-same-session = {yes|no}

Description

Indicates whether to use the same session for SSL and HTTP clients.

Options

yes

When set to yes, a user who has authenticated over HTTP will be authenticated when connecting over HTTPS. Likewise, the user who has authenticated over HTTPS will be authenticated when connecting over HTTP. Using yes will override ssl-id-sessions = yes, because HTTP clients do not read an SSL ID to maintain sessions.

no

Do not use the same session for SSL and HTTP clients.

Usage

This stanza entry is required.

Default value

no

Example

use-same-session = no

Parent topic: [session] stanza

[server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.All operations to specific branches of the LDAP DIT can be passed through to this back-end server.You can use multiple instances of this stanza. [ldap] configuration entries that are not configurable in this stanza use the [ldap] stanza values. For example, "tls-v12-enable". For Active Directory back-end, you must use an SSL connection (ssl-enabled = yes, port = 636).Stanza referencebind-auth-and-pwdchgUse the bind-auth-and-pwdchg stanza entry to control whether to force authentication to use the LDAP bind operation and force password change.bind-dnUse the bind-dn stanza entry to define the LDAP user distinguished name (DN) that is used for signing on to the LDAP server. bind-pwdUse the bind-pwd stanza entry to define password for the distinguished name declared in the bind-dn stanza entry. dn-mapUse the dn-map stanza entry to define which areas of the Security Access Manager registry have copies of users from this back-end server.dynamic-groups-enabledUse the dynamic-groups-enabled stanza entry to control whether dynamic groups are supported. group-search-filterUse the group-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.hostUse the host stanza entry to define the host name of the LDAP server. ignore-if-downSet whether Security Access Manager continues to operate with the other federated registries if one of the registries become unavailable.max-server-connectionsUse the max-server-connections stanza entry to define the maximum number of connections that are allowed with the LDAP server. portUse the port stanza entry to define the port appropriate for the ssl-enabled value set in this stanza. replicaUse the replica stanza entry to define the LDAP user registry replicas. static-group-objectclassUse the static-group-objectclass stanza entry to define the static group object class names to set when you create a native group entry in LDAP. ssl-enabledUse the ssl-enabled stanza entry to enable or disable SSL communication between WebSEAL and the LDAP server.ssl-keyfile-dnUse the ssl-keyfile-dn stanza entry to define the key label of the client personal certificate within the SSL key file. suffixUse the suffix stanza entry to define federated registry suffixes.user-objectclassUse the user-objectclass stanza entry to define the object class names to set when you create a native user entry in LDAP. user-search-filterUse the user-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.

[server:<instance>] stanza

This stanza defines a back-end LDAP server that can be used for federated registries.

All operations to specific branches of the LDAP DIT can be passed through to this back-end server.

You can use multiple instances of this stanza.

[ldap] configuration entries that are not configurable in this stanza use the [ldap] stanza values. For example, "tls-v12-enable".

For Active Directory back-end, you must use an SSL connection (ssl-enabled = yes, port = 636).

bind-auth-and-pwdchg
Use the bind-auth-and-pwdchg stanza entry to control whether to force authentication to use the LDAP bind operation and force password change.

bind-dn
Use the bind-dn stanza entry to define the LDAP user distinguished name (DN) that is used for signing on to the LDAP server.

bind-pwd
Use the bind-pwd stanza entry to define password for the distinguished name declared in the bind-dn stanza entry.

dn-map
Use the dn-map stanza entry to define which areas of the Security Access Manager registry have copies of users from this back-end server.

dynamic-groups-enabled
Use the dynamic-groups-enabled stanza entry to control whether dynamic groups are supported.

group-search-filter
Use the group-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.

host
Use the host stanza entry to define the host name of the LDAP server.

ignore-if-down
Set whether Security Access Manager continues to operate with the other federated registries if one of the registries become unavailable.

max-server-connections
Use the max-server-connections stanza entry to define the maximum number of connections that are allowed with the LDAP server.

port
Use the port stanza entry to define the port appropriate for the ssl-enabled value set in this stanza.

replica
Use the replica stanza entry to define the LDAP user registry replicas.

static-group-objectclass
Use the static-group-objectclass stanza entry to define the static group object class names to set when you create a native group entry in LDAP.

ssl-enabled
Use the ssl-enabled stanza entry to enable or disable SSL communication between WebSEAL and the LDAP server.

ssl-keyfile-dn
Use the ssl-keyfile-dn stanza entry to define the key label of the client personal certificate within the SSL key file.

suffix
Use the suffix stanza entry to define federated registry suffixes.

user-objectclass
Use the user-objectclass stanza entry to define the object class names to set when you create a native user entry in LDAP.

user-search-filter
Use the user-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.

Parent topic: Stanza reference

bind-auth-and-pwdchgIBM Security Access Manager for Web WebSEAL bind-auth-and-pwdchg stanza entryUse the bind-auth-and-pwdchg stanza entry to control whether to force authentication to use the LDAP bind operation and force password change.Syntax bind-auth-and-pwdchg = {yes | no} DescriptionThis option, when set to yes, forces authentication to use the LDAP bind operation rather than the LDAP compare operation. It also forces password change (not reset) to occur on a connection to the LDAP server that is bound as the user that is being changed. An example of a password change is the use of /pkmspasswd from WebSEAL.If this option is set to yes, then the LDAP server must allow users to change their own password. But in many cases, allowing user to change their own password is not the default behavior. For example, the IBM Security Directory Server requires an ACL to be set in the Directory Information Tree (DIT) for the affected users. Here is example of an ACL that can be inherited, which allows any user to change their own password: aclEntry: access-id:cn=this:at.userPassword:grant:w Options yesForce LDAP bind operation and password change.noDo not force LDAP bind operation and password change. Usage This stanza entry is optional. Default valueThe default value is no. Example bind-auth-and-pwdchg = yes [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

bind-auth-and-pwdchg

Use the bind-auth-and-pwdchg stanza entry to control whether to force authentication to use the LDAP bind operation and force password change.

Syntax

 bind-auth-and-pwdchg = {yes | no}

Description

This option, when set to yes, forces authentication to use the LDAP bind operation rather than the LDAP compare operation. It also forces password change (not reset) to occur on a connection to the LDAP server that is bound as the user that is being changed. An example of a password change is the use of /pkmspasswd from WebSEAL.

If this option is set to yes, then the LDAP server must allow users to change their own password. But in many cases, allowing user to change their own password is not the default behavior. For example, the IBM Security Directory Server requires an ACL to be set in the Directory Information Tree (DIT) for the affected users. Here is example of an ACL that can be inherited, which allows any user to change their own password:

aclEntry: access-id:cn=this:at.userPassword:grant:w

Options

yes

Force LDAP bind operation and password change.

no

Do not force LDAP bind operation and password change.

Usage

This stanza entry is optional.

Default value

The default value is no.

Example

bind-auth-and-pwdchg = yes

Parent topic: [server:<instance>] stanza

bind-dnIBM Security Access Manager for Web WebSEAL bind-dn stanza entryUse the bind-dn stanza entry to define the LDAP user distinguished name (DN) that is used for signing on to the LDAP server. Syntax bind-dn = LDAP_DN DescriptionLDAP user distinguished name (DN) that is used when binding (or signing on) to the LDAP server. Options LDAP_DNLDAP user distinguished name (DN) that is used for signing on to the LDAP server. Usage This stanza entry is required. Default valueNone. Example bind-dn = CN=Administrator,CN=Users,DC=ibm,DC=com [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

bind-dn

Use the bind-dn stanza entry to define the LDAP user distinguished name (DN) that is used for signing on to the LDAP server.

Syntax

 bind-dn = LDAP_DN

Description

LDAP user distinguished name (DN) that is used when binding (or signing on) to the LDAP server.

Options

LDAP_DN

LDAP user distinguished name (DN) that is used for signing on to the LDAP server.

Usage

This stanza entry is required.

Default value

None.

Example

bind-dn = CN=Administrator,CN=Users,DC=ibm,DC=com

Parent topic: [server:<instance>] stanza

bind-pwdIBM Security Access Manager for Web WebSEAL bind-pwd stanza entryUse the bind-pwd stanza entry to define password for the distinguished name declared in the bind-dn stanza entry. Syntax bind-pwd = LDAP_password DescriptionPassword for the LDAP user distinguished name declared in the bind-dn stanza entry. Options LDAP_passwordPassword for the LDAP user distinguished name declared in the bind-dn stanza entry. Usage This stanza entry is required and stored in the ldap.conf obfuscated file. Default valueNone. Example bind-pwd = zs77WVoLSZn1rKrL [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

bind-pwd

Use the bind-pwd stanza entry to define password for the distinguished name declared in the bind-dn stanza entry.

Syntax

 bind-pwd = LDAP_password

Description

Password for the LDAP user distinguished name declared in the bind-dn stanza entry.

Options

LDAP_password

Password for the LDAP user distinguished name declared in the bind-dn stanza entry.

Usage

This stanza entry is required and stored in the ldap.conf obfuscated file.

Default value

None.

Example

bind-pwd = zs77WVoLSZn1rKrL

Parent topic: [server:<instance>] stanza

dn-mapIBM Security Access Manager for Web WebSEAL dn-map stanza entryUse the dn-map stanza entry to define which areas of the Security Access Manager registry have copies of users from this back-end server.Syntax dn-map = from_dn | to_dn Description The dn-map entries define which areas of the Security Access Manager registry have copies of users from this back-end server. It is only used to pass through password operations. Options from_dnDefines the Security Access Manager registry location of the users copies. This value must be unique across all back-end servers.to_dnDefines the back-end registry location of the real users. Usage This stanza entry is optional. The values must be as specific (longest matching) as possible to contain their matches to include only branches of LDAP that are relevant. Change any value that contains a | character to || so that it is not misinterpreted as the separator character. The || character is reverted to the | character before use.Multiple dn-map values can be provided per back-end server.The most specific (longest matching) dn-map is selected. So overlapping maps can be defined.Multiple entries are allowed. Default valueNone. ExampleThe back-end users are all found under the LDAP location:cn=Users|Groups,o=ibm,c=usand they are replicated to the Security Access Manager registry at:cn=Users|Groups,dc=iswgaThen the dn-map entry would be:dn-map = cn=Users||Groups,dc=iswga | cn=Users||Groups,o=ibm,c=usThus the Security Access Manager registry user DN of:cn=Test User,cn=Users|Groups,dc=iswgawould map to the back-end server user DN of:cn=Test User,cn=Users|Groups,o=ibm,c=us [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

dn-map

Use the dn-map stanza entry to define which areas of the Security Access Manager registry have copies of users from this back-end server.

Syntax

 dn-map = from_dn | to_dn

Description

The dn-map entries define which areas of the Security Access Manager registry have copies of users from this back-end server. It is only used to pass through password operations.

Options

from_dn

Defines the Security Access Manager registry location of the users copies. This value must be unique across all back-end servers.

to_dn

Defines the back-end registry location of the real users.

Usage

This stanza entry is optional.

The values must be as specific (longest matching) as possible to contain their matches to include only branches of LDAP that are relevant.

Change any value that contains a "|" character to "||" so that it is not misinterpreted as the separator character. The "||" character is reverted to the "|" character before use.

Multiple dn-map values can be provided per back-end server.

The most specific (longest matching) dn-map is selected. So overlapping maps can be defined.

Multiple entries are allowed.

Default value

None.

Example

The back-end users are all found under the LDAP location:

cn=Users|Groups,o=ibm,c=us

and they are replicated to the Security Access Manager registry at:

cn=Users|Groups,dc=iswga

Then the dn-map entry would be:

dn-map = cn=Users||Groups,dc=iswga | cn=Users||Groups,o=ibm,c=us

Thus the Security Access Manager registry user DN of:

cn=Test User,cn=Users|Groups,dc=iswga

would map to the back-end server user DN of:

cn=Test User,cn=Users|Groups,o=ibm,c=us

Parent topic: [server:<instance>] stanza

dynamic-groups-enabledIBM Security Access Manager for Web WebSEAL dynamic-groups-enabled stanza entryUse the dynamic-groups-enabled stanza entry to control whether dynamic groups are supported. Syntax dynamic-groups-enabled = {yes|no} DescriptionIndication of whether dynamic groups are supported. This key value pair applies to supported LDAP registries. Security Access Manager supports dynamic groups with IBM Security Directory Server regardless of this setting. Options yesSecurity Access Manager attempts to resolve dynamic group membership.noSecurity Access Manager does not attempt to resolve dynamic group membership. Anything other than yes, including a blank value, is interpreted as no. UsageThis stanza entry is optional. Default valueThe default value is no. Example dynamic-groups-enabled = no [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

dynamic-groups-enabled

Use the dynamic-groups-enabled stanza entry to control whether dynamic groups are supported.

Syntax

 dynamic-groups-enabled = {yes|no}

Description

Indication of whether dynamic groups are supported. This key value pair applies to supported LDAP registries. Security Access Manager supports dynamic groups with IBM Security Directory Server regardless of this setting.

Options

yes

Security Access Manager attempts to resolve dynamic group membership.

no

Security Access Manager does not attempt to resolve dynamic group membership. Anything other than yes, including a blank value, is interpreted as no.

Usage

This stanza entry is optional.

Default value

The default value is no.

Example

dynamic-groups-enabled = no

Parent topic: [server:<instance>] stanza

group-search-filterIBM Security Access Manager for Web WebSEAL group-search-filter stanza entryUse the group-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.Syntaxgroup-search-filter = ldap search filter Description Use this configuration file parameter to specify how to locate Security Access Manager groups in LDAP.OptionsSpecifies the LDAP search filter that is used by Security Access Manager to locate groups in the LDAP directory server. This filter must be a valid LDAP string search filter as described by the Request for Comments (RFC) 2254 document.Use the group-search-filter option with static-group-objectclass so that the Security Access Manager can locate LDAP groups that are created with the LDAP object classes.Do not update the unsupported option with the same name under the [ldap-generic-general] stanza. Usage This stanza entry is optional. Default valueDefault value is specific to the LDAP server that is detected. Example This example specifies a search for a group named mygroup1 or mygroup2 under static-group-objectclass.group-search-filter = (|(static-group-objectclass=mygroup1)(static-group-objectclass=mygroup2)) [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

group-search-filter

Use the group-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.

Syntax

group-search-filter = ldap search filter

Description

Use this configuration file parameter to specify how to locate Security Access Manager groups in LDAP.

Options

Specifies the LDAP search filter that is used by Security Access Manager to locate groups in the LDAP directory server. This filter must be a valid LDAP string search filter as described by the Request for Comments (RFC) 2254 document.

Use the group-search-filter option with static-group-objectclass so that the Security Access Manager can locate LDAP groups that are created with the LDAP object classes.

Do not update the unsupported option with the same name under the [ldap-generic-general] stanza.

Usage

This stanza entry is optional.

Default value

Default value is specific to the LDAP server that is detected.

Example

This example specifies a search for a group named mygroup1 or mygroup2 under static-group-objectclass.

group-search-filter = (|(static-group-objectclass=mygroup1)(static-group-objectclass=mygroup2))

Parent topic: [server:<instance>] stanza

hostIBM Security Access Manager for Web WebSEAL host stanza entryUse the host stanza entry to define the host name of the LDAP server. Syntax host = host_name DescriptionHost name of the LDAP server. Options host_nameValid values for host_name include any valid IP host name. The host_name does not have to be a fully qualified domain name. Usage This stanza entry is required. Default valueNone. Example host = diamond host = diamond.example.com [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

host

Use the host stanza entry to define the host name of the LDAP server.

Syntax

 host = host_name

Description

Host name of the LDAP server.

Options

host_name

Valid values for host_name include any valid IP host name. The host_name does not have to be a fully qualified domain name.

Usage

This stanza entry is required.

Default value

None.

Example

host = diamond
host = diamond.example.com

Parent topic: [server:<instance>] stanza

ignore-if-downSet whether Security Access Manager continues to operate with the other federated registries if one of the registries become unavailable.Syntax ignore-if-down = { yes | no }Description Controls whether Security Access Manager ignores this registry when it fails.Options yesIgnore this registry when it fails. Security Access Manager continues to operate with the other federated registries while this registry is unavailable. If this option is set to yes for a registry, ACLs based on groups in the failed registry will behave as if the group has no members. Duplicate user ID detection is not permitted and must be disabled.noDo not ignore this registry when it fails. The registry component of Security Access Manager stops functioning if this registry is unavailable. For the primary registry, this value cannot be set as primary registry failures cannot be ignored.Usage This stanza entry is optional.Default value noExample ignore-if-down = no[server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

ignore-if-down

Set whether Security Access Manager continues to operate with the other federated registries if one of the registries become unavailable.

Syntax

ignore-if-down = { yes | no }

Description

Controls whether Security Access Manager ignores this registry when it fails.

Options

yes

Ignore this registry when it fails. Security Access Manager continues to operate with the other federated registries while this registry is unavailable.

Note: If this option is set to yes for a registry, ACLs based on groups in the failed registry will behave as if the group has no members. Duplicate user ID detection is not permitted and must be disabled.

no

Do not ignore this registry when it fails. The registry component of Security Access Manager stops functioning if this registry is unavailable.

Note: For the primary registry, this value cannot be set as primary registry failures cannot be ignored.

Usage

This stanza entry is optional.

Default value

no

Example

ignore-if-down = no

Parent topic: [server:<instance>] stanza

max-server-connectionsIBM Security Access Manager for Web WebSEAL max-server-connections stanza entryUse the max-server-connections stanza entry to define the maximum number of connections that are allowed with the LDAP server. Syntax max-server-connections = number_connections DescriptionIndicates the maximum number of connections that are allowed with the LDAP server. The Security Access Manager run time maintains a pool of connections for each LDAP server. From this pool, an available connection is chosen to send requests to the LDAP server. If all connections are busy, a new connection is established with the LDAP server, up to the maximum server connection pool size.This parameter is not available if you use the pdconfig utility. The parameter must be modified manually with the pdadmin utility. Options number_connectionsThe maximum number of connections that are allowed with the LDAP server. The valid range for this parameter is 2-16. Values greater than 16 are set to 16. Usage This stanza entry is optional. Default valueIf this parameter is not specified, the default pool size is 16. Example max-server-connections = 16 [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

max-server-connections

Use the max-server-connections stanza entry to define the maximum number of connections that are allowed with the LDAP server.

Syntax

max-server-connections = number_connections

Description

Indicates the maximum number of connections that are allowed with the LDAP server. The Security Access Manager run time maintains a pool of connections for each LDAP server. From this pool, an available connection is chosen to send requests to the LDAP server. If all connections are busy, a new connection is established with the LDAP server, up to the maximum server connection pool size.

This parameter is not available if you use the pdconfig utility. The parameter must be modified manually with the pdadmin utility.

Options

number_connections

The maximum number of connections that are allowed with the LDAP server. The valid range for this parameter is 2-16. Values greater than 16 are set to 16.

Usage

This stanza entry is optional.

Default value

If this parameter is not specified, the default pool size is 16.

Example

max-server-connections = 16

Parent topic: [server:<instance>] stanza

portIBM Security Access Manager for Web WebSEAL port stanza entryUse the port stanza entry to define the port appropriate for the ssl-enabled value set in this stanza. Syntax port = port_number DescriptionNumber of the TCP/IP port that is used for communicating with the LDAP server. This port must be the port appropriate for the ssl-enabled value set in this stanza. Options port_numberA valid port number is any positive integer that is allowed by TCP/IP and that is not currently being used by another application. Usage This stanza entry is required. Default valueNone. Example port = 389 [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

port

Use the port stanza entry to define the port appropriate for the ssl-enabled value set in this stanza.

Syntax

port = port_number

Description

Number of the TCP/IP port that is used for communicating with the LDAP server. This port must be the port appropriate for the ssl-enabled value set in this stanza.

Options

port_number

A valid port number is any positive integer that is allowed by TCP/IP and that is not currently being used by another application.

Usage

This stanza entry is required.

Default value

None.

Example

port = 389

Parent topic: [server:<instance>] stanza

replicaIBM Security Access Manager for Web WebSEAL replica stanza entryUse the replica stanza entry to define the LDAP user registry replicas. Syntax replica = ldap-server, port, type, pref DescriptionDefinition of the LDAP user registry replicas.Security Access Manager supports a maximum of one host and nine LDAP replica servers. If more than nine LDAP replica entries are listed, the Security Access Manager servers cannot start. Options ldap-serverThe network name of the server.portThe port number for the LDAP server. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.typeOne of readonly or readwrite.prefA number 1 - 10 (10 is the highest preference). Usage This stanza entry is optional. Default valueNone. Example Example of one replica specified and two replicas commented out:replica = rep1,390,readonly,1 #replica = rep2,391,readwrite,2 #replica = rep3,392,readwrite,3 [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

replica

Use the replica stanza entry to define the LDAP user registry replicas.

Syntax

replica = ldap-server, port, type, pref

Description

Definition of the LDAP user registry replicas.

Security Access Manager supports a maximum of one host and nine LDAP replica servers. If more than nine LDAP replica entries are listed, the Security Access Manager servers cannot start.

Options

ldap-server

The network name of the server.

port

The port number for the LDAP server. A valid port number is any positive number that is allowed by TCP/IP and that is not currently being used by another application.

type

One of readonly or readwrite.

pref

A number 1 - 10 (10 is the highest preference).

Usage

This stanza entry is optional.

Default value

None.

Example

Example of one replica specified and two replicas commented out:

replica = rep1,390,readonly,1
#replica = rep2,391,readwrite,2
#replica = rep3,392,readwrite,3

Parent topic: [server:<instance>] stanza

static-group-objectclassIBM Security Access Manager for Web WebSEAL static-group-objectclass stanza entryUse the static-group-objectclass stanza entry to define the static group object class names to set when you create a native group entry in LDAP. Syntax static-group-objectclass = object_class_list DescriptionContain a list of comma-separated object class names to set when you create a native group entry in LDAP. Options object_class_listA list of comma-separated object class names. UsageThis stanza entry is optional. Default valueDefault value is specific to the LDAP server that is detected. Example static-group-objectclass = top,groupOfNames [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

static-group-objectclass

Use the static-group-objectclass stanza entry to define the static group object class names to set when you create a native group entry in LDAP.

Syntax

 static-group-objectclass = object_class_list

Description

Contain a list of comma-separated object class names to set when you create a native group entry in LDAP.

Options

object_class_list

A list of comma-separated object class names.

Usage

This stanza entry is optional.

Default value

Default value is specific to the LDAP server that is detected.

Example

 static-group-objectclass = top,groupOfNames

Parent topic: [server:<instance>] stanza

ssl-enabledIBM Security Access Manager for Web WebSEAL ssl-enabled stanza entryUse the ssl-enabled stanza entry to enable or disable SSL communication between WebSEAL and the LDAP server.Syntax ssl-enabled = {yes|no} DescriptionEnables or disables SSL communication between WebSEAL and the LDAP server. Options yesEnable SSL communication.noDisable SSL communication. Usage This stanza entry is optional. Ensure that the port value is appropriate for the ssl-enabled value. Default valueSSL communication is disabled by default. Example ssl-enabled = yes [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

ssl-enabled

Use the ssl-enabled stanza entry to enable or disable SSL communication between WebSEAL and the LDAP server.

Syntax

 ssl-enabled = {yes|no}

Description

Enables or disables SSL communication between WebSEAL and the LDAP server.

Options

yes

Enable SSL communication.

no

Disable SSL communication.

Usage

This stanza entry is optional. Ensure that the port value is appropriate for the ssl-enabled value.

Default value

SSL communication is disabled by default.

Example

ssl-enabled = yes

Parent topic: [server:<instance>] stanza

ssl-keyfile-dnIBM Security Access Manager for Web WebSEAL ssl-keyfile-dn stanza entryUse the ssl-keyfile-dn stanza entry to define the key label of the client personal certificate within the SSL key file. Syntax ssl-keyfile-dn = key_label DescriptionString that specifies the key label of the client personal certificate within the SSL key file. This key label is used to identify the client certificate that is presented to the LDAP server. Options key_labelString that specifies the key label of the client personal certificate within the SSL key file. Usage This stanza entry is optional. The certificate that is referenced by this stanza entry is from the [ldap] ssl-keyfile entry that is specified in each server's configuration file. If it is specified, then the [ldap] ssl-keyfile referenced in each .conf file on the same server as the ldap.conf containing the [server:<instance>] ssl-keyfile-dn value must contain a certificate with this label. Default valueNone. Example ssl-keyfile-dn = "PD_LDAP" [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

ssl-keyfile-dn

Use the ssl-keyfile-dn stanza entry to define the key label of the client personal certificate within the SSL key file.

Syntax

ssl-keyfile-dn = key_label

Description

String that specifies the key label of the client personal certificate within the SSL key file. This key label is used to identify the client certificate that is presented to the LDAP server.

Options

key_label

String that specifies the key label of the client personal certificate within the SSL key file.

Usage

This stanza entry is optional. The certificate that is referenced by this stanza entry is from the [ldap] ssl-keyfile entry that is specified in each server's configuration file. If it is specified, then the [ldap] ssl-keyfile referenced in each .conf file on the same server as the ldap.conf containing the [server:<instance>] ssl-keyfile-dn value must contain a certificate with this label.

Default value

None.

Example

ssl-keyfile-dn = "PD_LDAP"

Parent topic: [server:<instance>] stanza

suffixIBM Security Access Manager for Web WebSEAL suffix stanza entryUse the suffix stanza entry to define federated registry suffixes.Syntax suffix = dn DescriptionThe suffix stanza entry defines the federated registry suffixes within the Security Access Manager registry that are stored on a back-end server instead. All operations on entries under these suffixes occur on the back-end server.Mapping of the DNs is not possible. So the back-end server must contain a suffix of the same name.The most specific (longest matching) suffix is selected. So overlapping suffixes can be defined.Multiple entries are allowed.Options dnDistinguished name of the federated registry LDAP suffix. Usage This stanza entry is optional. Default valueNone. Examplesuffix = o=ibm,c=us [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

suffix

Use the suffix stanza entry to define federated registry suffixes.

Syntax

 suffix = dn

Description

The suffix stanza entry defines the federated registry suffixes within the Security Access Manager registry that are stored on a back-end server instead. All operations on entries under these suffixes occur on the back-end server.

Mapping of the DNs is not possible. So the back-end server must contain a suffix of the same name.

The most specific (longest matching) suffix is selected. So overlapping suffixes can be defined.

Multiple entries are allowed.

Options

dn

Distinguished name of the federated registry LDAP suffix.

Usage

This stanza entry is optional.

Default value

None.

Example

suffix = o=ibm,c=us

Parent topic: [server:<instance>] stanza

user-objectclassIBM Security Access Manager for Web WebSEAL user-objectclass stanza entryUse the user-objectclass stanza entry to define the object class names to set when you create a native user entry in LDAP. Syntax user-objectclass = object_class_list DescriptionContain a list of comma-separated object class names to set when you create a native user entry in LDAP. Options object_class_listA list of comma-separated object class names. UsageThis stanza entry is optional. Default valueDefault value is specific to the LDAP server that is detected. Example user-objectclass = top,person,organizationalPerson,inetOrgPerson,ePerson [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

user-objectclass

Use the user-objectclass stanza entry to define the object class names to set when you create a native user entry in LDAP.

Syntax

 user-objectclass = object_class_list

Description

Contain a list of comma-separated object class names to set when you create a native user entry in LDAP.

Options

object_class_list

A list of comma-separated object class names.

Usage

This stanza entry is optional.

Default value

Default value is specific to the LDAP server that is detected.

Example

 user-objectclass = top,person,organizationalPerson,inetOrgPerson,ePerson

Parent topic: [server:<instance>] stanza

user-search-filterIBM Security Access Manager for Web WebSEAL user-search-filter stanza entryUse the user-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.Syntaxuser-search-filter = ldap search filter Description Use this configuration file parameter to specify how to locate Security Access Manager users in LDAP.OptionsSpecifies the LDAP search filter that is used by Security Access Manager to locate users in the LDAP directory server. This filter must be a valid LDAP string search filter as described by the Request for Comments (RFC) 2254 document.Use the user-search-filter option with user-objectclass so that the Security Access Manager can locate LDAP users that are created with the LDAP object classes.Do not update the unsupported option with the same name under the [ldap-generic-general] stanza. Usage This stanza entry is optional. Default valueDefault value is specific to the LDAP server that is detected. Example This example specifies a search for a User or Person under user-objectclass.user-search-filter = (|(user-objectclass=User)(user-objectclass=Person)) [server:<instance>] stanzaThis stanza defines a back-end LDAP server that can be used for federated registries.

user-search-filter

Use the user-search-filter entry to specify the LDAP search filter that is used by Security Access Manager.

Syntax

user-search-filter = ldap search filter

Description

Use this configuration file parameter to specify how to locate Security Access Manager users in LDAP.

Options

Specifies the LDAP search filter that is used by Security Access Manager to locate users in the LDAP directory server. This filter must be a valid LDAP string search filter as described by the Request for Comments (RFC) 2254 document.

Use the user-search-filter option with user-objectclass so that the Security Access Manager can locate LDAP users that are created with the LDAP object classes.

Do not update the unsupported option with the same name under the [ldap-generic-general] stanza.

Usage

This stanza entry is optional.

Default value

Default value is specific to the LDAP server that is detected.

Example

This example specifies a search for a User or Person under user-objectclass.

user-search-filter = (|(user-objectclass=User)(user-objectclass=Person))

Parent topic: [server:<instance>] stanza

[session-cookie-domains] stanza[session-cookie-domains] stanzasession-cookie-domains stanzastanzassession-cookie-domainsStanza referencedomainUse the domain stanza entry to specify domains that share the domain session cookie.

[session-cookie-domains] stanza

domain
Use the domain stanza entry to specify domains that share the domain session cookie.

Parent topic: Stanza reference

domaindomainIBM Security Access Manager for Web WebSEAL domain stanza entryUse the domain stanza entry to specify domains that share the domain session cookie.domain stanza entrysession-cookie-domains stanzaentriesdomainsession-cookie-domains stanzasession-cookie-domains stanzadomain entrySyntax domain = url Description Normally WebSEAL session cookies are host cookies that browsers only return to the host that originally set them. This stanza is used to configure domain session cookies that are sent to any host in a particular DNS domain. Options urlDomains that share the domain cookie. Usage This stanza entry is optional. Default value None. Example domain = example.com [session-cookie-domains] stanza

domain

Use the domain stanza entry to specify domains that share the domain session cookie.

Syntax

domain = url

Description

Normally WebSEAL session cookies are host cookies that browsers only return to the host that originally set them.

This stanza is used to configure domain session cookies that are sent to any host in a particular DNS domain.

Options

url

Domains that share the domain cookie.

Usage

This stanza entry is optional.

Default value

None.

Example

domain = example.com

Parent topic: [session-cookie-domains] stanza

[session-http-headers] stanza[session-http-headers] stanzasession-http-headers stanzastanzassession-http-headersStanza referenceheader_name

[session-http-headers] stanza

header_name

Parent topic: Stanza reference

header_nameheader_nameheader_name stanza entrysession-http-headers stanzaentriesheader_namesession-http-headers stanzasession-http-headers stanzaheader_name entrySyntax header_name = {http|https}Description Configures HTTP headers to maintain session state.Options httpConfigures HTTP headers to maintain session state over the HTTP transport.httpsConfigures HTTP headers to maintain session state over the HTTPS transport.Usage This stanza entry is optional.Default value None.Example entrust-client = https[session-http-headers] stanza

header_name

Syntax

header_name = {http|https}

Description

Configures HTTP headers to maintain session state.

Options

http

Configures HTTP headers to maintain session state over the HTTP transport.

https

Configures HTTP headers to maintain session state over the HTTPS transport.

Usage

This stanza entry is optional.

Default value

None.

Example

entrust-client = https

Parent topic: [session-http-headers] stanza

[snippet-filter] stanzaUse the [snippet-filter] stanza to configure parameters associated with the snippet filter.Stanza referencemax-snippet-sizeThe max-snippet-size stanza entry defines the maximum size (in bytes) of snippets that can be cached in memory.

[snippet-filter] stanza

Use the [snippet-filter] stanza to configure parameters associated with the snippet filter.

max-snippet-size
The max-snippet-size stanza entry defines the maximum size (in bytes) of snippets that can be cached in memory.

Parent topic: Stanza reference

max-snippet-sizeThe max-snippet-size stanza entry defines the maximum size (in bytes) of snippets that can be cached in memory.max-snippet-size stanza entrysnippet-filter stanzaentriesmax-snippet-sizesnippet-filter stanzasnippet-filter stanzamax-snippet-size entrySyntax max-snippet-size = size_in_bytes Description If the snippet exceeds the configured maximum size, it cannot be cached. Instead, it will be read from the disk during the construction of each response. Options size_in_bytes The maximum size (in bytes) of snippets that can be cached in memory. Usage This stanza entry is optional. Default value None. Example max-snippet-size = 1024 [snippet-filter] stanzaUse the [snippet-filter] stanza to configure parameters associated with the snippet filter.

max-snippet-size

The max-snippet-size stanza entry defines the maximum size (in bytes) of snippets that can be cached in memory.

Syntax

max-snippet-size = size_in_bytes

Description

If the snippet exceeds the configured maximum size, it cannot be cached. Instead, it will be read from the disk during the construction of each response.

Options

size_in_bytes

The maximum size (in bytes) of snippets that can be cached in memory.

Usage

This stanza entry is optional.

Default value

None.

Example

max-snippet-size = 1024

Parent topic: [snippet-filter] stanza

[snippet-filter:<uri>] stanzaUse the [snippet-filter:<uri>] stanza to configure the snippet filter for a particular resource.Syntax [snippet-filter:<uri>] <location> = <filename> Description This filter allows snippets to be inserted into the response for the specified URI. Options <uri> The URI for which the snippet substitution takes place.<location>The location at which the snippet is inserted. The location is pattern matched against a single line in the response. The snippet is then inserted immediately before the matching line. The value must represent the entire line that the snippet is to be inserted before. You can use the * and ? wildcard characters in the location pattern. The pattern match for this parameter is case-sensitive.<filename>The name of the file which contains the snippet to be inserted. You can specify a path that is relative to the snippet directory in the management root directory. This parameter is case-sensitive. Usage You can specify multiple resources and configure multiple locations for each resource. The entries in the stanza must appear in the order in which they will be inserted in the returned page. Only the first match for each configuration entry is updated with the snippet. After a match has been found, WebSEAL progresses to the next configuration entry. If a match is not found for a particular configuration entry, the subsequent entries in the stanza are not processed.You must include a new line character at the end of the snippet file contents if you want the snippet to be inserted as a separate line. Otherwise, WebSEAL adds the snippet to the start of the matching line.When you configure a snippet-filter stanza for a resource that is accessed over a virtual junction or a local junction, the <uri> value is a forward slash followed by the resource name. For example, [snippet-filter:/myResource.html].As a result, a particular [snippet-filter:<uri>] stanza can represent multiple resources. In the preceding example, WebSEAL inserts snippets into the responses when accessing myResource.html over a local junction or virtual junction.If the configured <filename> value is a non-existent file, WebSEAL fails to restart with a DPWIV0752E Could not open file error. Default value None. Example [snippet-filter:/stdjunction/sampleResource.html] *test* = samplesnippet.html ?hello* = samplesnippet2.html Stanza reference

[snippet-filter:<uri>] stanza

Use the [snippet-filter:<uri>] stanza to configure the snippet filter for a particular resource.

Syntax

[snippet-filter:<uri>]
<location> = <filename>

Description

This filter allows snippets to be inserted into the response for the specified URI.

Options

<uri>

The URI for which the snippet substitution takes place.

<location>

The location at which the snippet is inserted. The location is pattern matched against a single line in the response. The snippet is then inserted immediately before the matching line. The value must represent the entire line that the snippet is to be inserted before. You can use the "*" and "?" wildcard characters in the location pattern. The pattern match for this parameter is case-sensitive.

<filename>

The name of the file which contains the snippet to be inserted. You can specify a path that is relative to the snippet directory in the management root directory. This parameter is case-sensitive.

Usage

You can specify multiple resources and configure multiple locations for each resource. The entries in the stanza must appear in the order in which they will be inserted in the returned page. Only the first match for each configuration entry is updated with the snippet. After a match has been found, WebSEAL progresses to the next configuration entry. If a match is not found for a particular configuration entry, the subsequent entries in the stanza are not processed.

You must include a new line character at the end of the snippet file contents if you want the snippet to be inserted as a separate line. Otherwise, WebSEAL adds the snippet to the start of the matching line.

When you configure a snippet-filter stanza for a resource that is accessed over a virtual junction or a local junction, the <uri> value is a forward slash followed by the resource name. For example, [snippet-filter:/myResource.html].

As a result, a particular [snippet-filter:<uri>] stanza can represent multiple resources. In the preceding example, WebSEAL inserts snippets into the responses when accessing myResource.html over a local junction or virtual junction.

If the configured <filename> value is a non-existent file, WebSEAL fails to restart with a "DPWIV0752E Could not open file" error.

Default value

None.

Example

[snippet-filter:/stdjunction/sampleResource.html]
*test* = samplesnippet.html
?hello* = samplesnippet2.html

Parent topic: Stanza reference

[spnego] stanza[spnego] stanzaIBM Security Access Manager for Web WebSEAL [spnego] stanzaUse the [spnego] stanza to configure Kerberos authentication.spnego stanzastanzasspnegoStanza referencespnego-authUse the spnego-auth stanza entry to enable Kerberos authentication.spnego-krb-keytab-fileUse the spnego-krb-keytab-file stanza entry to specify the Kerberos keytab file.spnego-krb-service-nameUse the spnego-krb-service-name stanza entry to specify the Kerberos service principal names for the server.spnego-sid-attr-nameUse the spnego-sid-attr-name stanza entry to enable and define the credential attribute that stores the security identifier (SID) of the user.use-domain-qualified-nameUse the use-domain-qualified-name stanza entry to control whether Security Access Manager includes the domain from the Kerberos user principal name as part of the Security Access Manager user ID.

[spnego] stanza

Use the [spnego] stanza to configure Kerberos authentication.

spnego-auth
Use the spnego-auth stanza entry to enable Kerberos authentication.

spnego-krb-keytab-file
Use the spnego-krb-keytab-file stanza entry to specify the Kerberos keytab file.

spnego-krb-service-name
Use the spnego-krb-service-name stanza entry to specify the Kerberos service principal names for the server.

spnego-sid-attr-name
Use the spnego-sid-attr-name stanza entry to enable and define the credential attribute that stores the security identifier (SID) of the user.

use-domain-qualified-name
Use the use-domain-qualified-name stanza entry to control whether Security Access Manager includes the domain from the Kerberos user principal name as part of the Security Access Manager user ID.

Parent topic: Stanza reference

spnego-authspnego-authIBM Security Access Manager for Web WebSEAL spnego-auth stanza entryUse the spnego-auth stanza entry to enable Kerberos authentication.spnego-auth stanza entryspnego stanzaentriesspnego-authspnego stanzaspnego stanzaspnego-auth entrySyntax spnego-auth = {none|http|https|both} Description Enables authentication using the SPNEGO authentication mechanism. Options {none|http|https|both}Specifies which protocols are supported. The value both means both HTTP and HTTPS. Usage This stanza entry is required. Default value none Example spnego-auth = none [spnego] stanzaUse the [spnego] stanza to configure Kerberos authentication.

spnego-auth

Use the spnego-auth stanza entry to enable Kerberos authentication.

Syntax

spnego-auth = {none|http|https|both}

Description

Enables authentication using the SPNEGO authentication mechanism.

Options

{none|http|https|both}

Specifies which protocols are supported. The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

none

Example

spnego-auth = none

Parent topic: [spnego] stanza

spnego-krb-keytab-filespnego-krb-keytab-fileIBM Security Access Manager for Web WebSEAL spnego-krb-keytab-file stanza entryUse the spnego-krb-keytab-file stanza entry to specify the Kerberos keytab file.spnego-krb-keytab-file stanza entryspnego stanzaentriesspnego-krb-keytab-filespnego stanzaspnego stanzaspnego-krb-keytab-file entrySyntax spnego-krb-keytab-file = keytab_file_name Description The name of the Kerberos keytab file for the WebSEAL server. Options keytab_file_nameThe name of the Kerberos keytab file for the WebSEAL server. Usage This stanza entry is required. Default value None. Example spnego-krb-keytab-file = diamond_HTTP.keytab [spnego] stanzaUse the [spnego] stanza to configure Kerberos authentication.

spnego-krb-keytab-file

Use the spnego-krb-keytab-file stanza entry to specify the Kerberos keytab file.

Syntax

spnego-krb-keytab-file = keytab_file_name

Description

The name of the Kerberos keytab file for the WebSEAL server.

Options

keytab_file_name

The name of the Kerberos keytab file for the WebSEAL server.

Usage

This stanza entry is required.

Default value

None.

Example

spnego-krb-keytab-file = diamond_HTTP.keytab

Parent topic: [spnego] stanza

spnego-krb-service-namespnego-krb-service-nameIBM Security Access Manager for Web WebSEAL spnego-krb-service-name stanza entryUse the spnego-krb-service-name stanza entry to specify the Kerberos service principal names for the server.spnego-krb-service-name stanza entryspnego stanzaentriesspnego-krb-service-namespnego stanzaspnego stanzaspnego-krb-service-name entrySyntax spnego-krb-service-name = kerberos_server_principal_name Description Specifies the list of Kerberos service principal name (SPNs) for the server. Create a separate entry for each Kerberos service principal name. Options kerberos_server_principal_name This name is created by combining the string HTTP with the hostname. The syntax is: HTTP@host_name The host name is the DNS name by which browsers contact the Web server. Use the fully qualified host name. Usage This stanza entry is required. Default value None. Example spnego-krb-service-name = HTTP@diamond.subnet2.ibm.com spnego-krb-service-name = HTTP@ruby.subnet2.ibm.com [spnego] stanzaUse the [spnego] stanza to configure Kerberos authentication.

spnego-krb-service-name

Use the spnego-krb-service-name stanza entry to specify the Kerberos service principal names for the server.

Syntax

spnego-krb-service-name = kerberos_server_principal_name

Description

Specifies the list of Kerberos service principal name (SPNs) for the server. Create a separate entry for each Kerberos service principal name.

Options

kerberos_server_principal_name

This name is created by combining the string HTTP with the hostname. The syntax is:

HTTP@host_name

The host name is the DNS name by which browsers contact the Web server. Use the fully qualified host name.

Usage

This stanza entry is required.

Default value

None.

Example

spnego-krb-service-name = HTTP@diamond.subnet2.ibm.com
spnego-krb-service-name = HTTP@ruby.subnet2.ibm.com

Parent topic: [spnego] stanza

spnego-sid-attr-nameUse the spnego-sid-attr-name stanza entry to enable and define the credential attribute that stores the security identifier (SID) of the user.spnego-sid-attr-name stanza entryspnego stanzaentriesspnego-sid-attr-namespnego stanzaspnego stanzaspnego-sid-attr-name entrySyntax spnego-sid-attr-name = attribute_nameDescription During authentication, the system can add the SID of the user as an extended attribute to the credential. This stanza entry specifies the name of the attribute that stores the SID. The SID is extracted from the token that is used during Kerberos authentication. Options attribute_nameThe name of the attribute to store the SID in. Usage This stanza entry is optional. If this entry is not present, then the system does not add the SID as an extended attribute to the credential.Default value None.Example spnego-sid-attr-name = kerberos_sid[spnego] stanzaUse the [spnego] stanza to configure Kerberos authentication.

spnego-sid-attr-name

Use the spnego-sid-attr-name stanza entry to enable and define the credential attribute that stores the security identifier (SID) of the user.

Syntax

spnego-sid-attr-name = attribute_name

Description

During authentication, the system can add the SID of the user as an extended attribute to the credential. This stanza entry specifies the name of the attribute that stores the SID. The SID is extracted from the token that is used during Kerberos authentication.

Options

attribute_name

The name of the attribute to store the SID in.

Usage

This stanza entry is optional. If this entry is not present, then the system does not add the SID as an extended attribute to the credential.

Default value

None.

Example

spnego-sid-attr-name = kerberos_sid

Parent topic: [spnego] stanza

use-domain-qualified-nameuse-domain-qualified-nameIBM Security Access Manager for Web WebSEAL use-domain-qualified-name stanza entryUse the use-domain-qualified-name stanza entry to control whether Security Access Manager includes the domain from the Kerberos user principal name as part of the Security Access Manager user ID.use-domain-qualified-name stanza entryspnego stanzaentriesuse-domain-qualified-namespnego stanzaspnego stanzause-domain-qualified-name entrySyntax use-domain-qualified-name = {yes|no} Description Kerberos authentication provides a principal name of the form shortname@domain.com. By default, Security Access Manager uses only the short name as the Security Access Manager user ID. If this parameter is set to yes, then Security Access Manager includes the domain as part of the Security Access Manager user ID. The use-domain-qualified-name stanza entry has no effect if multiple-domain Active Directory is used as the Security Access Manager user registry. In this case, the domain name is always included as part of the Security Access Manager user name. Options yes Security Access Manager includes the domain portion of the principal name as part of the Security Access Manager user ID. For example, say that Kerberos authentication provides a principal name of user@example.com. If use-domain-qualified-name is no, then the Security Access Manager user ID is user. If use-domain-qualified-name is yes, then the Security Access Manager name is user@example.com.no Security Access Manager uses only the short name as the Access Manager user ID, and does not include the domain portion of the principal name. Usage This stanza entry is required. Default value no Example use-domain-qualified-name = yes [spnego] stanzaUse the [spnego] stanza to configure Kerberos authentication.

use-domain-qualified-name

Use the use-domain-qualified-name stanza entry to control whether Security Access Manager includes the domain from the Kerberos user principal name as part of the Security Access Manager user ID.

Syntax

use-domain-qualified-name = {yes|no}

Description

Kerberos authentication provides a principal name of the form shortname@domain.com. By default, Security Access Manager uses only the short name as the Security Access Manager user ID. If this parameter is set to yes, then Security Access Manager includes the domain as part of the Security Access Manager user ID.

Note: The use-domain-qualified-name stanza entry has no effect if multiple-domain Active Directory is used as the Security Access Manager user registry. In this case, the domain name is always included as part of the Security Access Manager user name.

Options

yes

Security Access Manager includes the domain portion of the principal name as part of the Security Access Manager user ID. For example, say that Kerberos authentication provides a principal name of user@example.com. If use-domain-qualified-name is no, then the Security Access Manager user ID is user. If use-domain-qualified-name is yes, then the Security Access Manager name is user@example.com.

no

Security Access Manager uses only the short name as the Access Manager user ID, and does not include the domain portion of the principal name.

Usage

This stanza entry is required.

Default value

no

Example

use-domain-qualified-name = yes

Parent topic: [spnego] stanza

[ssl] stanza[ssl] stanzassl stanzastanzassslStanza referencebase-crypto-libraryUse the base-crypto-library stanza entry to specify the cipher engine that GSKit uses.crl-ldap-serverUse the crl-ldap-server stanza entry in the [ssl] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during client-side certificate authentication.crl-ldap-server-portUse the crl-ldap-server-port entry in the [ssl] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.crl-ldap-userUse the crl-ldap-user entry in the [ssl] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server. crl-ldap-user-passwordUse the crl-ldap-user-password entry in the [ssl] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.disable-ssl-v2Use the disable-ssl-v2 entry in the [ssl] stanza to control whether support for SSL version 2 is enabled in WebSEAL.disable-ssl-v3Use the disable-ssl-v3 entry in the [ssl] stanza to control whether support for SSL version 3 is enabled in WebSEAL.disable-tls-v1Use the disable-tls-v1 entry in the [ssl] stanza to control whether support for TLS version 1 is enabled in WebSEAL.disable-tls-v11Use the disable-tls-v11 entry in the [ssl] stanza to control whether support for TLS version 1.1 is enabled in WebSEAL.disable-tls-v12Use the disable-tls-v12 entry in the [ssl] stanza to control whether support for TLS version 1.2 is enabled in WebSEAL.enable-duplicate-ssl-dn-not-found-msgsUse the enable-duplicate-ssl-dn-not-found-msgs stanza entry to control whether WebSEAL logs a warning whenever you connect to a junction that has the -K or -B flag set without the -D flag. WebSEAL can log duplicate messages every time it opens a connection to the junction or log a single warning only for each affected junction.fips-mode-processingUse the fips-mode-processing stanza entry to enable or disable FIPS mode processing.gsk-attr-namegsk-crl-cache-entry-lifetimegsk-crl-cache-sizejct-gsk-attr-namenist-complianceUse the nist-compliance stanza entry to enable or disable NIST SP800-131A compliance.ocsp-enableocsp-max-response-sizeocsp-nonce-check-enableocsp-nonce-generation-enableocsp-proxy-server-nameocsp-proxy-server-portocsp-urlpkcs11-keyfileUse this entry to define the name of the pkcs11 key file that contains the configuration information for the network HSM device.ssl-complianceSpecifies the SSL compliance mode.ssl-max-entriesssl-v2-timeoutssl-v3-timeoutsuppress-client-ssl-errorsundetermined-revocation-cert-actionwebseal-cert-keyfilewebseal-cert-keyfile-labelwebseal-cert-keyfile-sniUse the webseal-cert-keyfile-sni stanza entry to configure WebSEAL to send a server certificate that contains a host name, which matches the host name in the initial browser request. webseal-cert-keyfile-stash

[ssl] stanza

base-crypto-library
Use the base-crypto-library stanza entry to specify the cipher engine that GSKit uses.

crl-ldap-server
Use the crl-ldap-server stanza entry in the [ssl] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during client-side certificate authentication.

crl-ldap-server-port
Use the crl-ldap-server-port entry in the [ssl] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.

crl-ldap-user
Use the crl-ldap-user entry in the [ssl] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server.

crl-ldap-user-password
Use the crl-ldap-user-password entry in the [ssl] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.

disable-ssl-v2
Use the disable-ssl-v2 entry in the [ssl] stanza to control whether support for SSL version 2 is enabled in WebSEAL.

disable-ssl-v3
Use the disable-ssl-v3 entry in the [ssl] stanza to control whether support for SSL version 3 is enabled in WebSEAL.

disable-tls-v1
Use the disable-tls-v1 entry in the [ssl] stanza to control whether support for TLS version 1 is enabled in WebSEAL.

disable-tls-v11
Use the disable-tls-v11 entry in the [ssl] stanza to control whether support for TLS version 1.1 is enabled in WebSEAL.

disable-tls-v12
Use the disable-tls-v12 entry in the [ssl] stanza to control whether support for TLS version 1.2 is enabled in WebSEAL.

enable-duplicate-ssl-dn-not-found-msgs
Use the enable-duplicate-ssl-dn-not-found-msgs stanza entry to control whether WebSEAL logs a warning whenever you connect to a junction that has the -K or -B flag set without the -D flag. WebSEAL can log duplicate messages every time it opens a connection to the junction or log a single warning only for each affected junction.

fips-mode-processing
Use the fips-mode-processing stanza entry to enable or disable FIPS mode processing.

gsk-attr-name

gsk-crl-cache-entry-lifetime

gsk-crl-cache-size

jct-gsk-attr-name

nist-compliance
Use the nist-compliance stanza entry to enable or disable NIST SP800-131A compliance.

ocsp-enable

ocsp-max-response-size

ocsp-nonce-check-enable

ocsp-nonce-generation-enable

ocsp-proxy-server-name

ocsp-proxy-server-port

ocsp-url

pkcs11-keyfile
Use this entry to define the name of the pkcs11 key file that contains the configuration information for the network HSM device.

ssl-compliance
Specifies the SSL compliance mode.

ssl-max-entries

ssl-v2-timeout

ssl-v3-timeout

suppress-client-ssl-errors

undetermined-revocation-cert-action

webseal-cert-keyfile

webseal-cert-keyfile-label

webseal-cert-keyfile-sni
Use the webseal-cert-keyfile-sni stanza entry to configure WebSEAL to send a server certificate that contains a host name, which matches the host name in the initial browser request.

webseal-cert-keyfile-stash

Parent topic: Stanza reference

base-crypto-librarybase-crypto-libraryIBM Security Access Manager for Web WebSEAL base-crypto-library stanza entryUse the base-crypto-library stanza entry to specify the cipher engine that GSKit uses.base-crypto-library stanza entryssl stanzaentriesbase-crypto-libraryssl stanzassl stanzabase-crypto-library entrySyntax base-crypto-library = {Default|RSA|ICC} Description Specifies the cipher engine that is used by GSKit. Options DefaultThe value Default tells GSKit to use the optimal cryptographic base.RSAUse RSA. Setting this entry to RSA affects the settings possible for fips-mode-processing.ICCUse ICC. Usage This stanza entry is required. Default value Default Example base-crypto-library = Default [ssl] stanza

base-crypto-library

Use the base-crypto-library stanza entry to specify the cipher engine that GSKit uses.

Syntax

base-crypto-library = {Default|RSA|ICC}

Description

Specifies the cipher engine that is used by GSKit.

Options

Default

The value Default tells GSKit to use the optimal cryptographic base.

RSA

Use RSA.

Note: Setting this entry to RSA affects the settings possible for fips-mode-processing.

ICC

Use ICC.

Usage

This stanza entry is required.

Default value

Default

Example

base-crypto-library = Default

Parent topic: [ssl] stanza

crl-ldap-servercrl-ldap-serverIBM Security Access Manager for Web WebSEAL crl-ldap-server stanza entryUse the crl-ldap-server stanza entry in the [ssl] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during client-side certificate authentication.crl-ldap-server stanza entryssl stanzaentriescrl-ldap-serverssl stanzassl stanzacrl-ldap-server entrySyntax crl-ldap-server = server_name Description Specifies the Server to be contacted to obtain Certificate Revocation Lists (CRL). Options server_nameThis parameter can be set to one of two types of values: The name of the LDAP server to be referenced as a source for Certificate Revocation Lists (CRL) during authentication across SSL junctions. If this is used, you may also need to set the following parameters: crl-ldap-server-portcrl-ldap-usercrl-ldap-user-passwordThe literal string “URI”. In the case where no direct LDAP Server is available, this allows GSKit to obtain revocation information from LDAP or the HTTP Servers as specified by the CA in the CRL Distribution Point (CDP) extension of the certificate. Usage This stanza entry is optional. Default value None. Example crl-ldap-server = diamond.example.com [ssl] stanza

crl-ldap-server

Use the crl-ldap-server stanza entry in the [ssl] stanza to specify the LDAP server that WebSEAL can contact for CRL checking during client-side certificate authentication.

Syntax

crl-ldap-server = server_name

Description

Specifies the Server to be contacted to obtain Certificate Revocation Lists (CRL).

Options

server_name

This parameter can be set to one of two types of values:

The name of the LDAP server to be referenced as a source for Certificate Revocation Lists (CRL) during authentication across SSL junctions. If this is used, you may also need to set the following parameters:

crl-ldap-server-port

crl-ldap-user

crl-ldap-user-password

The literal string “URI”. In the case where no direct LDAP Server is available, this allows GSKit to obtain revocation information from LDAP or the HTTP Servers as specified by the CA in the CRL Distribution Point (CDP) extension of the certificate.

Usage

This stanza entry is optional.

Default value

None.

Example

crl-ldap-server = diamond.example.com

Parent topic: [ssl] stanza

crl-ldap-server-portcrl-ldap-server-portIBM Security Access Manager for Web WebSEAL crl-ldap-server-port stanza entryUse the crl-ldap-server-port entry in the [ssl] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.crl-ldap-server-port stanza entryssl stanzaentriescrl-ldap-server-portssl stanzassl stanzacrl-ldap-server-port entrySyntax crl-ldap-server-port = port_number Description Port number for communication with the LDAP server specified in crl-ldap-server. The LDAP server is referenced for Certificate Revocation List (CRL) checking during SSL authentication. Options port_numberPort number for communication with the LDAP server specified in crl-ldap-server. Usage This stanza entry is optional. When crl-ldap-server is set, this stanza entry is required. Default value None. Example crl-ldap-server-port = 389 [ssl] stanza

crl-ldap-server-port

Use the crl-ldap-server-port entry in the [ssl] stanza to set the port number for WebSEAL to use when it communicates with the LDAP server specified in crl-ldap-server.

Syntax

crl-ldap-server-port = port_number

Description

Port number for communication with the LDAP server specified in crl-ldap-server. The LDAP server is referenced for Certificate Revocation List (CRL) checking during SSL authentication.

Options

port_number

Port number for communication with the LDAP server specified in crl-ldap-server.

Usage

This stanza entry is optional. When crl-ldap-server is set, this stanza entry is required.

Default value

None.

Example

crl-ldap-server-port = 389

Parent topic: [ssl] stanza

crl-ldap-usercrl-ldap-userIBM Security Access Manager for Web WebSEAL crl-ldap-user stanza entryUse the crl-ldap-user entry in the [ssl] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server. crl-ldap-user stanza entryssl stanzaentriescrl-ldap-userssl stanzassl stanzacrl-ldap-user entrySyntax crl-ldap-user = user_DN Description Fully qualified distinguished name (DN) of an LDAP user that has access to the Certificate Revocation List. Options user_DNFully qualified distinguished name (DN) of an LDAP user that has access to the Certificate Revocation List. Usage This stanza entry is optional. A null value for crl-ldap-user indicates that the SSL authenticator should bind to the LDAP server anonymously. Default value None. Example crl-ldap-user = cn=webseald/diamond,cn=SecurityDaemons,secAuthority=Default [ssl] stanza

crl-ldap-user

Use the crl-ldap-user entry in the [ssl] stanza to specify an LDAP user who has permissions to retrieve the CRL on the LDAP server that is specified in crl-ldap-server.

Syntax

crl-ldap-user = user_DN

Description

Fully qualified distinguished name (DN) of an LDAP user that has access to the Certificate Revocation List.

Options

user_DN

Fully qualified distinguished name (DN) of an LDAP user that has access to the Certificate Revocation List.

Usage

This stanza entry is optional. A null value for crl-ldap-user indicates that the SSL authenticator should bind to the LDAP server anonymously.

Default value

None.

Example

crl-ldap-user =
cn=webseald/diamond,cn=SecurityDaemons,secAuthority=Default

Parent topic: [ssl] stanza

crl-ldap-user-passwordcrl-ldap-user-passwordIBM Security Access Manager for Web WebSEAL crl-ldap-user-password stanza entryUse the crl-ldap-user-password entry in the [ssl] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.crl-ldap-user-password stanza entryssl stanzaentriescrl-ldap-user-passwordssl stanzassl stanzacrl-ldap-user-password entrySyntax crl-ldap-user-password = password Description Password for the user specified in crl-ldap-user. Options passwordPassword for the user specified in crl-ldap-user. Usage This stanza entry is optional. Default value None. Example crl-ldap-user-password = mypassw0rd [ssl] stanza

crl-ldap-user-password

Use the crl-ldap-user-password entry in the [ssl] stanza to provide the password for the LDAP user that is specified in crl-ldap-user.

Syntax

crl-ldap-user-password = password

Description

Password for the user specified in crl-ldap-user.

Options

password

Password for the user specified in crl-ldap-user.

Usage

This stanza entry is optional.

Default value

None.

Example

crl-ldap-user-password = mypassw0rd

Parent topic: [ssl] stanza

disable-ssl-v2disable-ssl-v2IBM Security Access Manager for Web WebSEAL disable-ssl-v2 stanza entryUse the disable-ssl-v2 entry in the [ssl] stanza to control whether support for SSL version 2 is enabled in WebSEAL.disable-ssl-v2 stanza entryssl stanzaentriesdisable-ssl-v2ssl stanzassl stanzadisable-ssl-v2 entrySyntax disable-ssl-v2 = {yes|no} Description Disables support for SSL version 2. Support for SSL v2 is disabled by default. The WebSEAL configuration sets this value. Options yesSupport is disabled. noSupport is enabled. Usage This stanza entry is optional. When not specified, the default is yes. Default value yes Example disable-ssl-v2 = yes [ssl] stanza

disable-ssl-v2

Use the disable-ssl-v2 entry in the [ssl] stanza to control whether support for SSL version 2 is enabled in WebSEAL.

Syntax

disable-ssl-v2 = {yes|no}

Description

Disables support for SSL version 2. Support for SSL v2 is disabled by default. The WebSEAL configuration sets this value.

Options

yes

Support is disabled.

no

Support is enabled.

Usage

This stanza entry is optional. When not specified, the default is yes.

Default value

yes

Example

disable-ssl-v2 = yes

Parent topic: [ssl] stanza

disable-ssl-v3disable-ssl-v3IBM Security Access Manager for Web WebSEAL disable-ssl-v3 stanza entryUse the disable-ssl-v3 entry in the [ssl] stanza to control whether support for SSL version 3 is enabled in WebSEAL.disable-ssl-v3 stanza entryssl stanzaentriesdisable-ssl-v3ssl stanzassl stanzadisable-ssl-v3 entrySyntax disable-ssl-v3 = {yes|no} Description Disables support for SSL Version 3. Support for SSL V3 is enabled by default. The WebSEAL configuration sets this value. Options yesThe value yes means support is disabled.no The value no means the support is enabled. Usage This stanza entry is optional. When not specified, the default is no. Default value no Example disable-ssl-v3 = no [ssl] stanza

disable-ssl-v3

Use the disable-ssl-v3 entry in the [ssl] stanza to control whether support for SSL version 3 is enabled in WebSEAL.

Syntax

disable-ssl-v3 = {yes|no}

Description

Disables support for SSL Version 3. Support for SSL V3 is enabled by default. The WebSEAL configuration sets this value.

Options

yes

The value yes means support is disabled.

no

The value no means the support is enabled.

Usage

This stanza entry is optional. When not specified, the default is no.

Default value

no

Example

disable-ssl-v3 = no

Parent topic: [ssl] stanza

disable-tls-v1disable-tls-v1IBM Security Access Manager for Web WebSEAL disable-tls-v1 stanza entryUse the disable-tls-v1 entry in the [ssl] stanza to control whether support for TLS version 1 is enabled in WebSEAL.disable-tls-v1 stanza entryssl stanzaentriesdisable-tls-v1ssl stanzassl stanzadisable-tls-v1 entrySyntax disable-tls-v1 = {yes|no} Description Disables support for TLS Version 1. Support for TLS V1 is enabled by default. The WebSEAL configuration sets this value. Options yesThe value yes means support is disablednoThe value no means the support is enabled. Usage This stanza entry is optional. When not specified, the default is no. Default value no Example disable-tls-v1 = no [ssl] stanza

disable-tls-v1

Use the disable-tls-v1 entry in the [ssl] stanza to control whether support for TLS version 1 is enabled in WebSEAL.

Syntax

disable-tls-v1 = {yes|no}

Description

Disables support for TLS Version 1. Support for TLS V1 is enabled by default. The WebSEAL configuration sets this value.

Options

yes

The value yes means support is disabled

no

The value no means the support is enabled.

Usage

This stanza entry is optional. When not specified, the default is no.

Default value

no

Example

disable-tls-v1 = no

Parent topic: [ssl] stanza

disable-tls-v11disable-tls-v11IBM Security Access Manager for Web WebSEAL disable-tls-v11 stanza entryUse the disable-tls-v11 entry in the [ssl] stanza to control whether support for TLS version 1.1 is enabled in WebSEAL.disable-tls-v11 stanza entryssl stanzaentriesdisable-tls-v11ssl stanzassl stanzadisable-tls-v11 entrySyntax disable-tls-v11 = {yes|no} Description Determines whether WebSEAL supports Transport Layer Security (TLS) version 1.1. WebSEAL supports TLS version 1.1 by default. Options yesThe value yes disables support for TLS version 1.1.noThe value no enables support for TLS version 1.1. Usage This stanza entry is optional. If this entry is not specified, the default is no. Default value no Example disable-tls-v11 = no [ssl] stanza

disable-tls-v11

Use the disable-tls-v11 entry in the [ssl] stanza to control whether support for TLS version 1.1 is enabled in WebSEAL.

Syntax

disable-tls-v11 = {yes|no}

Description

Determines whether WebSEAL supports Transport Layer Security (TLS) version 1.1. WebSEAL supports TLS version 1.1 by default.

Options

yes

The value yes disables support for TLS version 1.1.

no

The value no enables support for TLS version 1.1.

Usage

This stanza entry is optional. If this entry is not specified, the default is no.

Default value

no

Example

disable-tls-v11 = no

Parent topic: [ssl] stanza

disable-tls-v12disable-tls-v12IBM Security Access Manager for Web WebSEAL disable-tls-v12 stanza entryUse the disable-tls-v12 entry in the [ssl] stanza to control whether support for TLS version 1.2 is enabled in WebSEAL.disable-tls-v12 stanza entryssl stanzaentriesdisable-tls-v12ssl stanzassl stanzadisable-tls-v12 entrySyntax disable-tls-v12 = {yes|no} Description Determines whether WebSEAL supports Transport Layer Security (TLS) version 1.2. WebSEAL supports TLS version 1.2 by default. Options yesThe value yes disables support for TLS version 1.2.noThe value no enables support for TLS version 1.2. Usage This stanza entry is optional. If this entry is not specified, the default is no. Default value no Example disable-tls-v12 = no [ssl] stanza

disable-tls-v12

Use the disable-tls-v12 entry in the [ssl] stanza to control whether support for TLS version 1.2 is enabled in WebSEAL.

Syntax

disable-tls-v12 = {yes|no}

Description

Determines whether WebSEAL supports Transport Layer Security (TLS) version 1.2. WebSEAL supports TLS version 1.2 by default.

Options

yes

The value yes disables support for TLS version 1.2.

no

The value no enables support for TLS version 1.2.

Usage

This stanza entry is optional. If this entry is not specified, the default is no.

Default value

no

Example

disable-tls-v12 = no

Parent topic: [ssl] stanza

enable-duplicate-ssl-dn-not-found-msgsenable-duplicate-ssl-dn-not-found-msgsIBM Security Access Manager for Web WebSEAL enable-duplicate-ssl-dn-not-found-msgs stanza entryUse the enable-duplicate-ssl-dn-not-found-msgs stanza entry to control whether WebSEAL logs a warning whenever you connect to a junction that has the -K or -B flag set without the -D flag. WebSEAL can log duplicate messages every time it opens a connection to the junction or log a single warning only for each affected junction.enable-duplicate-ssl-dn-not-found-msgs stanza entryssl stanzaentriesenable-duplicate-ssl-dn-not-found-msgsssl stanzassl stanzaenable-duplicate-ssl-dn-not-found-msgs entrySyntax enable-duplicate-ssl-dn-not-found-msgs = {yes | no} Description Determines whether WebSEAL logs a warning message every time you open a connection to a junction that has:Either the -K or the -B flag set, butThe -D flag is not set.By default, WebSEAL logs duplicate messages whenever it opens another connection to the junction. These messages appear in the following format:DPWIV1212W No server DN is defined for 'server.ibm.com'. The junctioned server DN verification is not performed." Options yesDuplicate messages are created. Every time a connection is opened to a junction that has the -K or -B flags specified without the -D option, WebSEAL logs a warning.noWhen the server starts, WebSEAL logs a single warning only for each affected junction. Usage This stanza entry is required. Default value yes Example enable-duplicate-ssl-dn-not-found-msgs = no [ssl] stanza

enable-duplicate-ssl-dn-not-found-msgs

Use the enable-duplicate-ssl-dn-not-found-msgs stanza entry to control whether WebSEAL logs a warning whenever you connect to a junction that has the -K or -B flag set without the -D flag. WebSEAL can log duplicate messages every time it opens a connection to the junction or log a single warning only for each affected junction.

Syntax

enable-duplicate-ssl-dn-not-found-msgs = {yes | no}

Description

Determines whether WebSEAL logs a warning message every time you open a connection to a junction that has:

Either the -K or the -B flag set, but

The -D flag is not set.

By default, WebSEAL logs duplicate messages whenever it opens another connection to the junction. These messages appear in the following format:

DPWIV1212W   No server DN is defined for 'server.ibm.com'.
   The junctioned server DN verification is not performed."

Options

yes

Duplicate messages are created. Every time a connection is opened to a junction that has the -K or -B flags specified without the -D option, WebSEAL logs a warning.

no

When the server starts, WebSEAL logs a single warning only for each affected junction.

Usage

This stanza entry is required.

Default value

yes

Example

enable-duplicate-ssl-dn-not-found-msgs = no

Parent topic: [ssl] stanza

fips-mode-processingfips-mode-processingIBM Security Access Manager for Web WebSEAL fips-mode-processing stanza entryUse the fips-mode-processing stanza entry to enable or disable FIPS mode processing.fips-mode-processing stanza entryssl stanzaentriesfips-mode-processingssl stanzassl stanzafips-mode-processing entrySyntax fips-mode-processing = {yes|no} Description Enables or disables FIPS mode processing. Options yesA value of yes enables FIPS mode processing.noA value of no disables FIPS mode processing. When base-crypto-library = RSA, this value must be no. Usage This stanza entry is required. Default value no Example fips-mode-processing = no [ssl] stanza

fips-mode-processing

Use the fips-mode-processing stanza entry to enable or disable FIPS mode processing.

Syntax

fips-mode-processing = {yes|no}

Description

Enables or disables FIPS mode processing.

Options

yes

A value of yes enables FIPS mode processing.

no

A value of no disables FIPS mode processing. When base-crypto-library = RSA, this value must be no.

Usage

This stanza entry is required.

Default value

no

Example

fips-mode-processing = no

Parent topic: [ssl] stanza

gsk-attr-namegsk-attr-namegsk-attr-name stanza entryssl stanzaentriesgsk-attr-namessl stanzassl stanzagsk-attr-name entrySyntax gsk-attr-name = {enum | string | number}:id:value Description Specify additional GSKit attributes to use when initializing an SSL connection with the client. A complete list of the available attributes is included in the GSKit SSL API documentation. This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute. Options {enum | string | number}The GSKit attribute type.idThe identity associated with the GSKit attribute.valueThe value for the GSKit attribute. Usage This stanza entry is optional. See Appendix: Supported GSKit attributesYou can configure the these GSKit attributes with Security Access Manager. for a list of GSKit attributes that can be configured.You cannot configure the following restricted GSKit attributes: GSK_BASE_CRYPTO_LIBRARY GSK_SSL_FIPS_MODE_PROCESSING GSK_FIPS_MODE_PROCESSING GSK_OCSP_ENABLE GSK_OCSP_URL GSK_OCSP_NONCE_GENERATION_ENABLE GSK_OCSP_NONCE_CHECK_ENABLE GSK_OCSP_REQUEST_SIGKEYLABEL GSK_OCSP_REQUEST_SIGALG GSK_OCSP_PROXY_SERVER_NAME GSK_OCSP_PROXY_SERVER_PORT GSK_OCSP_RETRIEVE_VIA_GET GSK_OCSP_MAX_RESPONSE_SIZE GSK_KEYRING_FILE GSK_KEYRING_PW GSK_CRL_CACHE_SIZE GSK_CRL_CACHE_ENTRY_LIFETIME GSK_KEYRING_STASH_FILE GSK_KEYRING_LABEL GSK_LDAP_SERVER GSK_LDAP_SERVER_PORT GSK_LDAP_USER GSK_LDAP_USER_PW GSK_ACCELERATOR_NCIPHER_NF GSK_ACCELERATOR_RAINBOW_CS GSK_PKCS11_DRIVER_PATH GSK_PKCS11_TOKEN_LABEL GSK_PKCS11_TOKEN_PWD GSK_PKCS11_ACCELERATOR_MODE GSK_V2_SESSION_TIMEOUT GSK_V3_SESSION_TIMEOUT GSK_PROTOCOL_SSLV2 GSK_PROTOCOL_SSLV3 GSK_PROTOCOL_TLSV1 GSK_CLIENT_AUTH_TYPE GSK_SESSION_TYPE GSK_IO_CALLBACK GSK_RESET_SESSION_TYPE_CALLBACK GSK_RESET_SESSION_TYPE_CALLBACK GSK_NO_RENEGOTIATION GSK_ALLOW_ABBREVIATED_RENEGOTIATIONIf you attempt to modify any of these attributes then an error message will be generated. Default value None. Example The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:gsk-attr-name = string:225:proxy.ibm.com See alsogsk-attr-nameUse the gsk-attr-name stanza entry to specify additional GSKit attributes to use when initializing an SSL connection with the distributed session cache. gsk-attr-name jct-gsk-attr-name[ssl] stanza

gsk-attr-name

Syntax

gsk-attr-name = {enum | string | number}:id:value

Description

Specify additional GSKit attributes to use when initializing an SSL connection with the client. A complete list of the available attributes is included in the GSKit SSL API documentation. This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute.

Options

{enum | string | number}

The GSKit attribute type.

id

The identity associated with the GSKit attribute.

value

The value for the GSKit attribute.

Usage

This stanza entry is optional.

See Appendix: Supported GSKit attributes for a list of GSKit attributes that can be configured.

You cannot configure the following restricted GSKit attributes:

GSK_BASE_CRYPTO_LIBRARY
GSK_SSL_FIPS_MODE_PROCESSING
GSK_FIPS_MODE_PROCESSING
GSK_OCSP_ENABLE
GSK_OCSP_URL
GSK_OCSP_NONCE_GENERATION_ENABLE
GSK_OCSP_NONCE_CHECK_ENABLE
GSK_OCSP_REQUEST_SIGKEYLABEL
GSK_OCSP_REQUEST_SIGALG
GSK_OCSP_PROXY_SERVER_NAME
GSK_OCSP_PROXY_SERVER_PORT
GSK_OCSP_RETRIEVE_VIA_GET
GSK_OCSP_MAX_RESPONSE_SIZE
GSK_KEYRING_FILE
GSK_KEYRING_PW
GSK_CRL_CACHE_SIZE
GSK_CRL_CACHE_ENTRY_LIFETIME
GSK_KEYRING_STASH_FILE
GSK_KEYRING_LABEL
GSK_LDAP_SERVER
GSK_LDAP_SERVER_PORT
GSK_LDAP_USER
GSK_LDAP_USER_PW
GSK_ACCELERATOR_NCIPHER_NF
GSK_ACCELERATOR_RAINBOW_CS
GSK_PKCS11_DRIVER_PATH
GSK_PKCS11_TOKEN_LABEL
GSK_PKCS11_TOKEN_PWD
GSK_PKCS11_ACCELERATOR_MODE
GSK_V2_SESSION_TIMEOUT
GSK_V3_SESSION_TIMEOUT
GSK_PROTOCOL_SSLV2
GSK_PROTOCOL_SSLV3
GSK_PROTOCOL_TLSV1
GSK_CLIENT_AUTH_TYPE
GSK_SESSION_TYPE
GSK_IO_CALLBACK
GSK_RESET_SESSION_TYPE_CALLBACK
GSK_RESET_SESSION_TYPE_CALLBACK
GSK_NO_RENEGOTIATION
GSK_ALLOW_ABBREVIATED_RENEGOTIATION

If you attempt to modify any of these attributes then an error message will be generated.

Default value

None.

Example

The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:

gsk-attr-name = string:225:proxy.ibm.com

See also

gsk-attr-name

gsk-attr-name

jct-gsk-attr-name

Parent topic: [ssl] stanza

gsk-crl-cache-entry-lifetimegsk-crl-cache-entry-lifetimegsk-crl-cache-entry-lifetime stanza entryssl stanzaentriesgsk-crl-cache-entry-lifetimessl stanzassl stanzagsk-crl-cache-entry-lifetime entrySyntax gsk-crl-cache-entry-lifetime = number_of_seconds Description Integer value specifying the lifetime timeout, in seconds, for individual entries in the GSKit CRL cache. See also the standards documents for SSL V3 and TLS V1 (RFC 2246) for more information on CRLs. Options number_of_secondsInteger value specifying the lifetime timeout, in seconds, for individual entries in the GSKit CRL cache. The minimum value is 0. The maximum value is 86400. Neither WebSEAL nor GSKit impose a maximum value on the cache entry lifetime. Usage This stanza entry is required. Default value 0 Example gsk-crl-cache-entry-lifetime = 0 [ssl] stanza

gsk-crl-cache-entry-lifetime

Syntax

gsk-crl-cache-entry-lifetime = number_of_seconds

Description

Integer value specifying the lifetime timeout, in seconds, for individual entries in the GSKit CRL cache.

See also the standards documents for SSL V3 and TLS V1 (RFC 2246) for more information on CRLs.

Options

number_of_seconds

Integer value specifying the lifetime timeout, in seconds, for individual entries in the GSKit CRL cache. The minimum value is 0. The maximum value is 86400. Neither WebSEAL nor GSKit impose a maximum value on the cache entry lifetime.

Usage

This stanza entry is required.

Default value

0

Example

gsk-crl-cache-entry-lifetime = 0

Parent topic: [ssl] stanza

gsk-crl-cache-sizegsk-crl-cache-sizegsk-crl-cache-size stanza entryssl stanzaentriesgsk-crl-cache-sizessl stanzassl stanzagsk-crl-cache-size entrySyntax gsk-crl-cache-size = number_of_entriesDescription Integer value indicating the maximum number of entries in the GSKit CRL cache. See the standards documents for SSL V3 and TLS V1 (RFC 2246) for more information on CRLs.Options number_of_entriesInteger value indicating the maximum number of entries in the GSKit CRL cache. Minimum value is 0. A value of 0 means that no entries are cached. Neither WebSEAL nor GSKit impose a maximum value on this cache. Usage This stanza entry is required.Default value 0Example gsk-crl-cache-size = 0[ssl] stanza

gsk-crl-cache-size

Syntax

gsk-crl-cache-size = number_of_entries

Description

Integer value indicating the maximum number of entries in the GSKit CRL cache.

See the standards documents for SSL V3 and TLS V1 (RFC 2246) for more information on CRLs.

Options

number_of_entries

Integer value indicating the maximum number of entries in the GSKit CRL cache. Minimum value is 0. A value of 0 means that no entries are cached. Neither WebSEAL nor GSKit impose a maximum value on this cache.

Usage

This stanza entry is required.

Default value

0

Example

gsk-crl-cache-size = 0

Parent topic: [ssl] stanza

jct-gsk-attr-namejct-gsk-attr-namejct-gsk-attr-name stanza entryssl stanzaentriesjct-gsk-attr-namessl stanzassl stanzajct-gsk-attr-name entrySyntax jct-gsk-attr-name = {enum | string | number}:id:value Description Specify additional GSKit attributes to use when initializing an SSL connection with a junctioned server. A complete list of the available attributes is included in the GSKit SSL API documentation. This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute. This configuration item can be customized for a particular junction by adding the adjusted configuration item to a [ssl:{jct_id}] stanza, where {jct-id} refers to the junction point for a standard junction (include the leading /), or the virtual host label for a virtual host junction. Options {enum | string | number}The GSKit attribute type.idThe identity associated with the GSKit attribute.valueThe value for the GSKit attribute. Usage This stanza entry is optional. See Appendix: Supported GSKit attributesYou can configure the these GSKit attributes with Security Access Manager. for a list of GSKit attributes that can be configured.You cannot configure the following restricted GSKit attributes: GSK_V2_SIDCACHE_SIZE GSK_V3_SIDCACHE_SIZE GSK_V2_SESSION_TIMEOUT GSK_V3_SESSION_TIMEOUT GSK_PROTOCOL_SSLV2 GSK_PROTOCOL_SSLV3 For a junction-specific jct-gsk-attr-name configuration entry, you cannot configure the following restricted GSKit attributes: GSK_V2_SIDCACHE_SIZE GSK_V3_SIDCACHE_SIZEIf you attempt to modify any of these attributes then an error message will be generated. Default value None. Example The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:jct-gsk-attr-name = string:225:proxy.ibm.com See alsogsk-attr-nameUse the gsk-attr-name stanza entry to specify additional GSKit attributes to use when initializing an SSL connection with the distributed session cache. gsk-attr-name gsk-attr-name[ssl] stanza

jct-gsk-attr-name

Syntax

jct-gsk-attr-name = {enum | string | number}:id:value

Description

Specify additional GSKit attributes to use when initializing an SSL connection with a junctioned server. A complete list of the available attributes is included in the GSKit SSL API documentation. This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute.

This configuration item can be customized for a particular junction by adding the adjusted configuration item to a [ssl:{jct_id}] stanza, where {jct-id} refers to the junction point for a standard junction (include the leading /), or the virtual host label for a virtual host junction.

Options

{enum | string | number}

The GSKit attribute type.

id

The identity associated with the GSKit attribute.

value

The value for the GSKit attribute.

Usage

This stanza entry is optional.

See Appendix: Supported GSKit attributes for a list of GSKit attributes that can be configured.

You cannot configure the following restricted GSKit attributes:

GSK_V2_SIDCACHE_SIZE
GSK_V3_SIDCACHE_SIZE
GSK_V2_SESSION_TIMEOUT
GSK_V3_SESSION_TIMEOUT
GSK_PROTOCOL_SSLV2
GSK_PROTOCOL_SSLV3

For a junction-specific jct-gsk-attr-name configuration entry, you cannot configure the following restricted GSKit attributes:

GSK_V2_SIDCACHE_SIZE
GSK_V3_SIDCACHE_SIZE

If you attempt to modify any of these attributes then an error message will be generated.

Default value

None.

Example

The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:

jct-gsk-attr-name = string:225:proxy.ibm.com

See also

gsk-attr-name

gsk-attr-name

gsk-attr-name

Parent topic: [ssl] stanza

nist-compliancenist-complianceIBM Security Access Manager for Web WebSEAL nist-compliance stanza entryUse the nist-compliance stanza entry to enable or disable NIST SP800-131A compliance.nist-compliance stanza entryssl stanzaentriesnist-compliancessl stanzassl stanzanist-compliance entrySyntax nist-compliance = {yes|no} Description Enables or disables NIST SP800-131A compliance.Enabling NIST SP800-131A compliance results in the following automatic configuration:Enables FIPS mode processing. When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the fips-mode-processing configuration entry.Enables TLS v1.2. When NIST SP800-131A compliance is enabled, TLS v1.2 is enabled regardless of the setting for the disable-tls-v12 configuration entry.TLS v1 and TLS v1.1 are not disabled.Enables the appropriate signature algorithms.Sets the minimum RSA key size to 2048 bytes. Options yesA value of yes enables NIST SP800-131A compliance. noA value of no disables NIST SP800-131A compliance. Usage This stanza entry is optional. Default value no Example nist-compliance = no [ssl] stanza

nist-compliance

Use the nist-compliance stanza entry to enable or disable NIST SP800-131A compliance.

Syntax

nist-compliance = {yes|no}

Description

Enables or disables NIST SP800-131A compliance.

Enabling NIST SP800-131A compliance results in the following automatic configuration:

Enables FIPS mode processing.

Note: When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the fips-mode-processing configuration entry.

Enables TLS v1.2.

Notes:

When NIST SP800-131A compliance is enabled, TLS v1.2 is enabled regardless of the setting for the disable-tls-v12 configuration entry.

TLS v1 and TLS v1.1 are not disabled.

Enables the appropriate signature algorithms.

Sets the minimum RSA key size to 2048 bytes.

Options

yes

A value of yes enables NIST SP800-131A compliance.

no

A value of no disables NIST SP800-131A compliance.

Usage

This stanza entry is optional.

Default value

no

Example

nist-compliance = no

Parent topic: [ssl] stanza

ocsp-enableocsp-enableocsp-enable stanza entryssl stanzaentriesocsp-enablessl stanzassl stanzaocsp-enable entrySyntax ocsp-enable = {yes|no} Description Enable Online Certificate Status Protocol (OCSP) for checking the revocation status of certificates supplied by a server using the OCSP URL embedded in the certificate using an Authority Information Access (AIA) extension. Options yesEnable OCSP to check the revocation status of server supplied certificates.noDisable OCSP checking of server supplied certificates. Usage This stanza entry is optional. This option can be used as an alternative to, or in conjunction with, the ocsp-url option. Default value no Example ocsp-enable = no [ssl] stanza

ocsp-enable

Syntax

ocsp-enable = {yes|no}

Description

Enable Online Certificate Status Protocol (OCSP) for checking the revocation status of certificates supplied by a server using the OCSP URL embedded in the certificate using an Authority Information Access (AIA) extension.

Options

yes

Enable OCSP to check the revocation status of server supplied certificates.

no

Disable OCSP checking of server supplied certificates.

Usage

This stanza entry is optional.

Note: This option can be used as an alternative to, or in conjunction with, the ocsp-url option.

Default value

no

Example

ocsp-enable = no

Parent topic: [ssl] stanza

ocsp-max-response-sizeocsp-max-response-sizeocsp-max-response-size stanza entryssl stanzaentriesocsp-max-response-sizessl stanzassl stanzaocsp-max-response-size entrySyntax ocsp-max-response-size = number of bytes Description Sets the maximum response size (in bytes) that will be accepted as a response from an OCSP responder. This limit helps protect against a denial of service attack. Options number of bytesMaximum response size, in bytes. A value of zero (0) indicates that the value is not set in the configuration file and no call to GSKit will be made to adjust its value; in this case, the option will assume the GSKit default of 20480 bytes.Non-zero values will be passed on to GSKit. Usage This stanza entry is optional. Default value 204080 Example ocsp-max-response-size = 20480 [ssl] stanza

ocsp-max-response-size

Syntax

ocsp-max-response-size = number of bytes

Description

Sets the maximum response size (in bytes) that will be accepted as a response from an OCSP responder. This limit helps protect against a denial of service attack.

Options

number of bytes

Maximum response size, in bytes.

Note: A value of zero (0) indicates that the value is not set in the configuration file and no call to GSKit will be made to adjust its value; in this case, the option will assume the GSKit default of 20480 bytes.Non-zero values will be passed on to GSKit.

Usage

This stanza entry is optional.

Default value

204080

Example

ocsp-max-response-size = 20480

Parent topic: [ssl] stanza

ocsp-nonce-check-enableocsp-nonce-check-enableocsp-nonce-check-enable stanza entryssl stanzaentriesocsp-nonce-check-enablessl stanzassl stanzaocsp-nonce-check-enable entrySyntax ocsp-nonce-check-enable = {yes|no} Description Determines whether WebSEAL checks the nonce in the OCSP response. Enabling this option improves security but can cause OCSP Response validation to fail if there is a caching proxy between WebSEAL and the OCSP Responder. Note that enabling this option automatically enables the jct-ocsp-nonce-generation-enable option. Options yesWebSEAL checks the nonce in the OCSP response to verify that it matches the nonce from the request. noWebSEAL does not check the nonce in the OCSP response. Usage This stanza entry is optional. Default value no Example ocsp-nonce-check-enable = no [ssl] stanza

ocsp-nonce-check-enable

Syntax

ocsp-nonce-check-enable = {yes|no}

Description

Determines whether WebSEAL checks the nonce in the OCSP response. Enabling this option improves security but can cause OCSP Response validation to fail if there is a caching proxy between WebSEAL and the OCSP Responder. Note that enabling this option automatically enables the jct-ocsp-nonce-generation-enable option.

Options

yes

WebSEAL checks the nonce in the OCSP response to verify that it matches the nonce from the request.

no

WebSEAL does not check the nonce in the OCSP response.

Usage

This stanza entry is optional.

Default value

no

Example

ocsp-nonce-check-enable = no

Parent topic: [ssl] stanza

ocsp-nonce-generation-enableocsp-nonce-generation-enableocsp-nonce-generation-enable stanza entryssl stanzaentriesocsp-nonce-generation-enablessl stanzassl stanzaocsp-nonce-generation-enable entrySyntax ocsp-nonce-generation-enable = {yes|no} Description Determines whether WebSEAL generates a nonce as part of the OCSP request. Enabling this option can improve security by preventing replay attacks on WebSEAL but may cause an excessive load on an OCSP Responder appliance as the responder cannot use cached responses and must sign each response. Options yesWebSEAL generates a nonce as part of the OCSP request. noWebSEAL does not generate a nonce as part of the OCSP request. Usage This stanza entry is optional. Default value no Example ocsp-nonce-generation-enable = no [ssl] stanza

ocsp-nonce-generation-enable

Syntax

ocsp-nonce-generation-enable = {yes|no}

Description

Determines whether WebSEAL generates a nonce as part of the OCSP request. Enabling this option can improve security by preventing replay attacks on WebSEAL but may cause an excessive load on an OCSP Responder appliance as the responder cannot use cached responses and must sign each response.

Options

yes

WebSEAL generates a nonce as part of the OCSP request.

no

WebSEAL does not generate a nonce as part of the OCSP request.

Usage

This stanza entry is optional.

Default value

no

Example

ocsp-nonce-generation-enable = no

Parent topic: [ssl] stanza

ocsp-proxy-server-nameocsp-proxy-server-nameocsp-proxy-server-name stanza entryssl stanzaentriesocsp-proxy-server-namessl stanzassl stanzaocsp-proxy-server-name entrySyntax ocsp-proxy-server-name = <proxy host name> Description Specifies the name of the proxy server that provides access to the OCSP responder. Options proxy host nameFully qualified name of the proxy server. Usage This stanza entry is optional. Default value None Example ocsp-proxy-server-name = proxy.ibm.com [ssl] stanza

ocsp-proxy-server-name

Syntax

ocsp-proxy-server-name = <proxy host name>

Description

Specifies the name of the proxy server that provides access to the OCSP responder.

Options

proxy host name

Fully qualified name of the proxy server.

Usage

This stanza entry is optional.

Default value

None

Example

ocsp-proxy-server-name = proxy.ibm.com

Parent topic: [ssl] stanza

ocsp-proxy-server-portocsp-proxy-server-portocsp-proxy-server-port stanza entryssl stanzaentriesocsp-proxy-server-portssl stanzassl stanzaocsp-proxy-server-port entrySyntax ocsp-proxy-server-port = <proxy host port number> Description Specifies the port number of the proxy server that provides access to the OCSP Responder. Options proxy host port numberPort number used by the proxy server to route OCSP requests and responses. Usage This stanza entry is optional. Default value None Example ocsp-proxy-server-port = 8888 [ssl] stanza

ocsp-proxy-server-port

Syntax

ocsp-proxy-server-port = <proxy host port number>

Description

Specifies the port number of the proxy server that provides access to the OCSP Responder.

Options

proxy host port number

Port number used by the proxy server to route OCSP requests and responses.

Usage

This stanza entry is optional.

Default value

None

Example

ocsp-proxy-server-port = 8888

Parent topic: [ssl] stanza

ocsp-urlocsp-urlocsp-url stanza entryssl stanzaentriesocsp-urlssl stanzassl stanzaocsp-url entrySyntax ocsp-url = <OCSP Responder URL> Description Specifies the URL for the OCSP Responder. If a URL is provided, WebSEAL uses OCSP for all revocation status checking regardless of whether the certificate has an Authority Information Access (AIA) extension, which means that OCSP works with existing certificates. WebSEAL tries the OCSP Responder that is configured by this method first, rather than using a location specified by AIA extension. If revocation status is undetermined, and if ocsp-enable is set to yes, then WebSEAL tries to obtain revocation status using the access method in the AIA extension. Options OCSP Responder URLURL of the OCSP Responder. Usage This stanza entry is optional. Default value None Example ocsp-url = http://responder.ibm.com/ [ssl] stanza

ocsp-url

Syntax

ocsp-url = <OCSP Responder URL>

Description

Specifies the URL for the OCSP Responder. If a URL is provided, WebSEAL uses OCSP for all revocation status checking regardless of whether the certificate has an Authority Information Access (AIA) extension, which means that OCSP works with existing certificates. WebSEAL tries the OCSP Responder that is configured by this method first, rather than using a location specified by AIA extension. If revocation status is undetermined, and if ocsp-enable is set to yes, then WebSEAL tries to obtain revocation status using the access method in the AIA extension.

Options

OCSP Responder URL

URL of the OCSP Responder.

Usage

This stanza entry is optional.

Default value

None

Example

ocsp-url = http://responder.ibm.com/

Parent topic: [ssl] stanza

pkcs11-keyfileUse this entry to define the name of the pkcs11 key file that contains the configuration information for the network HSM device.pkcs11-keyfile stanza entryssl stanzaentriespkcs11-keyfilessl stanzassl stanzapkcs11-keyfile entrySyntax pkcs11-keyfile = key_fileDescription If you have a network HSM device configured in your environment, use this entry to specify the name of the key file that contains the configuration for the device.Options key_fileThe name of the pkcs11 key file that contains the configuration information for the network HSM device. Usage This stanza entry is optional.Default valueNone.Example pkcs11-keyfile = MyHSM[ssl] stanza

pkcs11-keyfile

Use this entry to define the name of the pkcs11 key file that contains the configuration information for the network HSM device.

Syntax

pkcs11-keyfile = key_file

Description

If you have a network HSM device configured in your environment, use this entry to specify the name of the key file that contains the configuration for the device.

Options

key_file

The name of the pkcs11 key file that contains the configuration information for the network HSM device.

Usage

This stanza entry is optional.

Default value

None.

Example

pkcs11-keyfile = MyHSM

Parent topic: [ssl] stanza

ssl-complianceSpecifies the SSL compliance mode.Syntax ssl-compliance = {fips|none|sp800-131-strict|sp800-131-transition|suite-b-128|suite-b-192}Description This stanza entry specifies the SSL compliance mode. The value of this stanza entry is set during the initial policy server configuration. Do not modify this value.Options fipsEnforces FIPS 140-2 protocols and algorithms. Security Access Manager servers and applications generate and use SHA1 with 2048-bit RSA certificates. Only TLS versions 1.0, 1.1, and 1.2 are available. SSL versions 2 and 3 are disabled and unavailable. This setting option is equivalent to the previous release setting [ssl] ssl-enable-fips = yes. This value is compatible with previous Tivoli Access Manager releases.noneSpecifies that no special compliance criteria are applied to TLS communication. Security Access Manager servers and applications generate and use SHA1 with 2048-bit RSA certificates. This setting option is equivalent to the previous release setting [ssl] ssl-enable-fips = no. This value is compatible with previous Tivoli Access Manager releases.sp800-131-strictEnables strict NIST SP800-131a support. This conformance enforcement is required by some agencies and businesses that start in the year 2014. Security Access Manager servers and applications generate and use SHA256 with 2048-bit RSA certificates. This value is not compatible with prior releases of Tivoli Access Manager. Older Tivoli Access Manager clients cannot interact with Security Access Manager 7.0 running with this compliance setting. Only TLS version 1.2 is available; all others are disabled.sp800-131-transitionEnables NIST SP800-131a support at the transition level. This value is valid until the end of the year 2013. This value has fewer restrictions than the strict enforcement. Only TLS versions 1.0, 1.1, and 1.2 are available. SSL versions 2 and 3 are disabled and unavailable. Security Access Manager servers and applications generate and use SHA256 with 2048-bit RSA certificates. This value is at a higher level than is required by the standard and was chosen as it is a level that is permitted by the strict enforcement that allows easy migration from transition to strict. This value is not compatible with previous Tivoli Access Manager releases. Older Tivoli Access Manager clients cannot interact with Security Access Manager 7.0 running with this compliance setting.suite-b-128Enables NSA Suite B at 128-bit support. Security Access Manager servers and applications generate and use SHA256 with 256-bit ECDSA certificates. This value is not compatible with previous Tivoli Access Manager releases. Older Tivoli Access Manager clients cannot interact with Tivoli Access Manager 7.0 running with this compliance setting. Only TLS version 1.2 is available; all others are disabled.suite-b-192Enables NSA Suite B at 192-bit support. Security Access Manager servers and applications generate and use SHA384 with 384-bit ECDSA certificates. This value is not compatible with previous Tivoli Access Manager releases. Older Tivoli Access Manager clients cannot interact with Security Access Manager 7.0 running with this compliance setting. Only TLS version 1.2 is available; all others are disabled.Usage This stanza entry is optional.Default value None.Example ssl-compliance = fips[ssl] stanza

ssl-compliance

Specifies the SSL compliance mode.

Syntax

ssl-compliance = {fips|none|sp800-131-strict|sp800-131-transition|suite-b-128|suite-b-192}

Description

This stanza entry specifies the SSL compliance mode.

Note: The value of this stanza entry is set during the initial policy server configuration. Do not modify this value.

Options

fips

Enforces FIPS 140-2 protocols and algorithms. Security Access Manager servers and applications generate and use SHA1 with 2048-bit RSA certificates. Only TLS versions 1.0, 1.1, and 1.2 are available. SSL versions 2 and 3 are disabled and unavailable. This setting option is equivalent to the previous release setting [ssl] ssl-enable-fips = yes. This value is compatible with previous Tivoli Access Manager releases.

none

Specifies that no special compliance criteria are applied to TLS communication. Security Access Manager servers and applications generate and use SHA1 with 2048-bit RSA certificates. This setting option is equivalent to the previous release setting [ssl] ssl-enable-fips = no. This value is compatible with previous Tivoli Access Manager releases.

sp800-131-strict

Enables strict NIST SP800-131a support. This conformance enforcement is required by some agencies and businesses that start in the year 2014.

Security Access Manager servers and applications generate and use SHA256 with 2048-bit RSA certificates. This value is not compatible with prior releases of Tivoli Access Manager. Older Tivoli Access Manager clients cannot interact with Security Access Manager 7.0 running with this compliance setting. Only TLS version 1.2 is available; all others are disabled.

sp800-131-transition

Enables NIST SP800-131a support at the transition level. This value is valid until the end of the year 2013. This value has fewer restrictions than the strict enforcement. Only TLS versions 1.0, 1.1, and 1.2 are available. SSL versions 2 and 3 are disabled and unavailable.

Security Access Manager servers and applications generate and use SHA256 with 2048-bit RSA certificates. This value is at a higher level than is required by the standard and was chosen as it is a level that is permitted by the strict enforcement that allows easy migration from transition to strict. This value is not compatible with previous Tivoli Access Manager releases. Older Tivoli Access Manager clients cannot interact with Security Access Manager 7.0 running with this compliance setting.

suite-b-128

Enables NSA Suite B at 128-bit support. Security Access Manager servers and applications generate and use SHA256 with 256-bit ECDSA certificates. This value is not compatible with previous Tivoli Access Manager releases. Older Tivoli Access Manager clients cannot interact with Tivoli Access Manager 7.0 running with this compliance setting. Only TLS version 1.2 is available; all others are disabled.

suite-b-192

Enables NSA Suite B at 192-bit support. Security Access Manager servers and applications generate and use SHA384 with 384-bit ECDSA certificates. This value is not compatible with previous Tivoli Access Manager releases. Older Tivoli Access Manager clients cannot interact with Security Access Manager 7.0 running with this compliance setting. Only TLS version 1.2 is available; all others are disabled.

Usage

This stanza entry is optional.

Default value

None.

Example

ssl-compliance = fips

Parent topic: [ssl] stanza

ssl-max-entriesssl-max-entriesssl-max-entries stanza entryssl stanzaentriesssl-max-entriesssl stanzassl stanzassl-max-entries entrySyntax ssl-max-entries = number_of_entriesDescription Integer value indicating the maximum number of concurrent entries in the SSL cache. Options number_of_entriesInteger value indicating the maximum number of concurrent entries in the SSL cache. The minimum value is zero (0), which means that caching is unlimited. Entries between 0 and 256 are set to 256. There is no maximum limit.Usage This stanza entry is optional. Default value When the stanza entry is not assigned a value, WebSEAL uses a default value of 0. The WebSEAL configuration utility, however, assigns a default value of 4096.Example ssl-max-entries = 4096[ssl] stanza

ssl-max-entries

Syntax

ssl-max-entries = number_of_entries

Description

Integer value indicating the maximum number of concurrent entries in the SSL cache.

Options

number_of_entries

Integer value indicating the maximum number of concurrent entries in the SSL cache. The minimum value is zero (0), which means that caching is unlimited. Entries between 0 and 256 are set to 256. There is no maximum limit.

Usage

This stanza entry is optional.

Default value

When the stanza entry is not assigned a value, WebSEAL uses a default value of 0. The WebSEAL configuration utility, however, assigns a default value of 4096.

Example

ssl-max-entries = 4096

Parent topic: [ssl] stanza

ssl-v2-timeoutssl-v2-timeoutssl-v2-timeout stanza entryssl stanzaentriesssl-v2-timeoutssl stanzassl stanzassl-v2-timeout entrySyntax ssl-v2-timeout = number_of_secondsDescription Session timeout in seconds for SSL v2 connections between clients and servers. This timeout value controls how often a full SSL handshake is completed between clients and WebSEAL. This value is set by the WebSEAL configuration utility.Options number_of_secondsValid range of values for number_of_seconds is from 1-100 seconds.Usage This stanza entry is required when SSL is enabled.Default value 100Example ssl-v2-timeout = 100[ssl] stanza

ssl-v2-timeout

Syntax

ssl-v2-timeout = number_of_seconds

Description

Session timeout in seconds for SSL v2 connections between clients and servers. This timeout value controls how often a full SSL handshake is completed between clients and WebSEAL.

This value is set by the WebSEAL configuration utility.

Options

number_of_seconds

Valid range of values for number_of_seconds is from 1-100 seconds.

Usage

This stanza entry is required when SSL is enabled.

Default value

100

Example

ssl-v2-timeout = 100

Parent topic: [ssl] stanza

ssl-v3-timeoutssl-v3-timeoutssl-v3-timeout stanza entryssl stanzaentriesssl-v3-timeoutssl stanzassl stanzassl-v3-timeout entrySyntax ssl-v3-timeout = number_of_seconds Description Session timeout in seconds for SSL v3 connections between clients and servers. This timeout value controls how often a full SSL handshake is completed between clients and WebSEAL. This value is set by the WebSEAL configuration utility. Options number_of_secondsValid range of values for number_of_seconds is from 1-86400 seconds, where 86400 seconds is equal to 1 day. If you specify a number outside this range, the default number of 7200 seconds will be used. Usage This stanza entry is required when SSL is enabled. Default value 7200 Example ssl-v3-timeout = 7200 [ssl] stanza

ssl-v3-timeout

Syntax

ssl-v3-timeout = number_of_seconds

Description

Session timeout in seconds for SSL v3 connections between clients and servers. This timeout value controls how often a full SSL handshake is completed between clients and WebSEAL.

This value is set by the WebSEAL configuration utility.

Options

number_of_seconds

Valid range of values for number_of_seconds is from 1-86400 seconds, where 86400 seconds is equal to 1 day. If you specify a number outside this range, the default number of 7200 seconds will be used.

Usage

This stanza entry is required when SSL is enabled.

Default value

7200

Example

ssl-v3-timeout = 7200

Parent topic: [ssl] stanza

suppress-client-ssl-errorssuppress-client-ssl-errorssuppress-client-ssl-errors stanza entryssl stanzaentriessuppress-client-ssl-errorsssl stanzassl stanzasuppress-client-ssl-errors entrySyntax suppress-client-ssl-errors = {true|false}Description This stanza entry suppresses error messages that originate from SSL communication problems with the client. Options trueSuppress error messages that originate from SSL communication problems with the client.falseDo not suppress error messages that originate from SSL communication problems with the client.Usage This stanza entry is required when SSL is enabled.Default value falseExample suppress-client-ssl-errors = false[ssl] stanza

suppress-client-ssl-errors

Syntax

suppress-client-ssl-errors = {true|false}

Description

This stanza entry suppresses error messages that originate from SSL communication problems with the client.

Options

true

Suppress error messages that originate from SSL communication problems with the client.

false

Do not suppress error messages that originate from SSL communication problems with the client.

Usage

This stanza entry is required when SSL is enabled.

Default value

false

Example

suppress-client-ssl-errors = false

Parent topic: [ssl] stanza

undetermined-revocation-cert-actionundetermined-revocation-cert-actionundetermined-revocation-cert-action stanza entryssl stanzaentriesundetermined-revocation-cert-actionssl stanzassl stanzaundetermined-revocation-cert-action entrySyntax undetermined-revocation-cert-action = {ignore | log | reject} Description Controls the action that WebSEAL takes if OCSP or CRL is enabled but the responder cannot determine the revocation status of a certificate (that is, the revocation status is unknown). The appropriate values for this entry should be provided by the OCSP or CRL Responder owner. Options ignoreWebSEAL ignores the undetermined revocation status and permits use of the certificate.logWebSEAL logs the fact that the certificate status is undetermined and permits use of the certificate.rejectWebSEAL logs the fact that the certificate status is undetermined and rejects the certificate. Usage This stanza entry is required. Default value The option defaults to ignore if it is not specified in the configuration file. The value for this option in the template configuration file is log. Example undetermined-revocation-cert-action = log [ssl] stanza

undetermined-revocation-cert-action

Syntax

undetermined-revocation-cert-action = {ignore | log | reject}

Description

Controls the action that WebSEAL takes if OCSP or CRL is enabled but the responder cannot determine the revocation status of a certificate (that is, the revocation status is unknown). The appropriate values for this entry should be provided by the OCSP or CRL Responder owner.

Options

ignore

WebSEAL ignores the undetermined revocation status and permits use of the certificate.

log

WebSEAL logs the fact that the certificate status is undetermined and permits use of the certificate.

reject

WebSEAL logs the fact that the certificate status is undetermined and rejects the certificate.

Usage

This stanza entry is required.

Default value

The option defaults to ignore if it is not specified in the configuration file.

Note: The value for this option in the template configuration file is log.

Example

undetermined-revocation-cert-action = log

Parent topic: [ssl] stanza

webseal-cert-keyfilewebseal-cert-keyfilewebseal-cert-keyfile stanza entryssl stanzaentrieswebseal-cert-keyfilessl stanzassl stanzawebseal-cert-keyfile entrySyntax webseal-cert-keyfile = file_name Description Specifies the WebSEAL certificate keyfile. This is the server certificate that WebSEAL exchanges with browsers when negotiating SSL sessions. Options file_nameName of the WebSEAL certificate keyfile. Usage This stanza entry is required. Default value pdsrv.kdb Example webseal-cert-keyfile = pdsrv.kdb [ssl] stanza

webseal-cert-keyfile

Syntax

webseal-cert-keyfile = file_name

Description

Specifies the WebSEAL certificate keyfile. This is the server certificate that WebSEAL exchanges with browsers when negotiating SSL sessions.

Options

file_name

Name of the WebSEAL certificate keyfile.

Usage

This stanza entry is required.

Default value

pdsrv.kdb

Example

webseal-cert-keyfile = pdsrv.kdb

Parent topic: [ssl] stanza

webseal-cert-keyfile-labelwebseal-cert-keyfile-labelwebseal-cert-keyfile-label stanza entryssl stanzaentrieswebseal-cert-keyfile-labelssl stanzassl stanzawebseal-cert-keyfile-label entrySyntax webseal-cert-keyfile-label = label_nameDescription String that specifies a label to use for the WebSEAL certificate keyfile. If this entry is not specified or an invalid label name is configured (that is, there is no certificate associated with the configured label), the label of the default certificate in the keystore is used. The keystore is specified by the webseal-cert-keyfile entry.Options label_nameString that specifies a label to use for the WebSEAL certificate keyfile. Usage This stanza entry is optional, but is set by default during WebSEAL configuration.Default value WebSEAL-Test-OnlyExample webseal-cert-keyfile-label = WebSEAL-Test-Only[ssl] stanza

webseal-cert-keyfile-label

Syntax

webseal-cert-keyfile-label = label_name

Description

String that specifies a label to use for the WebSEAL certificate keyfile. If this entry is not specified or an invalid label name is configured (that is, there is no certificate associated with the configured label), the label of the default certificate in the keystore is used. The keystore is specified by the webseal-cert-keyfile entry.

Options

label_name

String that specifies a label to use for the WebSEAL certificate keyfile.

Usage

This stanza entry is optional, but is set by default during WebSEAL configuration.

Default value

WebSEAL-Test-Only

Example

webseal-cert-keyfile-label = WebSEAL-Test-Only

Parent topic: [ssl] stanza

webseal-cert-keyfile-sniwebseal-cert-keyfile-sniIBM Security Access Manager for Web webseal-cert-keyfile-sniUse the webseal-cert-keyfile-sni stanza entry to configure WebSEAL to send a server certificate that contains a host name, which matches the host name in the initial browser request. webseal-cert-keyfile-sni stanza entryssl stanzaentrieswebseal-cert-keyfile-snissl stanzassl stanzawebseal-cert-keyfile-sni entrySyntax webseal-cert-keyfile-sni = <host_name>:<label> Description This configuration has the following requirements:The user uses TLS over SSL to connect to WebSEAL. SSLv2 and SSLv3 are not supported.The browser supports Server Name Indication.Use the webseal-cert-keyfile-sni configuration entry to specify the certificate that WebSEAL sends for a particular host name. You can specify this configuration entry multiple times. Specify a separate entry for each server certificate.If WebSEAL does not find an entry for the host name in the browser request, WebSEAL sends the default certificate that is specified by the webseal-cert-keyfile-label entry. WebSEAL also uses the default certificate if the request does not meet the Server Name Indication requirements. For example, if the browser does not support Server Name Indication. Options <host_name>The name of the host to which WebSEAL returns the certificate.<label>The label of the certificate for WebSEAL to use.Specify the certificate that contains a dn value of cn=<host_name>. Usage This stanza entry is optional. Default valueNone. Example webseal-cert-keyfile-sni = hostA.abc.ibm.com:hostAcert webseal-cert-keyfile-sni = vhostB.abc.ibm.com:vhostBcert [ssl] stanza

webseal-cert-keyfile-sni

Use the webseal-cert-keyfile-sni stanza entry to configure WebSEAL to send a server certificate that contains a host name, which matches the host name in the initial browser request.

Syntax

webseal-cert-keyfile-sni = <host_name>:<label>

Description

This configuration has the following requirements:

The user uses TLS over SSL to connect to WebSEAL. SSLv2 and SSLv3 are not supported.

The browser supports Server Name Indication.

Use the webseal-cert-keyfile-sni configuration entry to specify the certificate that WebSEAL sends for a particular host name.

You can specify this configuration entry multiple times. Specify a separate entry for each server certificate.

If WebSEAL does not find an entry for the host name in the browser request, WebSEAL sends the default certificate that is specified by the webseal-cert-keyfile-label entry. WebSEAL also uses the default certificate if the request does not meet the Server Name Indication requirements. For example, if the browser does not support Server Name Indication.

Options

<host_name>

The name of the host to which WebSEAL returns the certificate.

<label>

The label of the certificate for WebSEAL to use.

Note: Specify the certificate that contains a dn value of cn=<host_name>.

Usage

This stanza entry is optional.

Default value

None.

Example

webseal-cert-keyfile-sni = hostA.abc.ibm.com:hostAcert
webseal-cert-keyfile-sni = vhostB.abc.ibm.com:vhostBcert

Parent topic: [ssl] stanza

webseal-cert-keyfile-stashwebseal-cert-keyfile-stashwebseal-cert-keyfile-stash stanza entryssl stanzaentrieswebseal-cert-keyfile-stashssl stanzassl stanzawebseal-cert-keyfile-stash entrySyntax webseal-cert-keyfile-stash = file_name Description Name of the file containing an obfuscated version of the password used to protect private keys in the keyfile. Options file_nameName of the file containing an obfuscated version of the password used to protect private keys in the keyfile. Usage This stanza entry is optional. Default value pdsrv.sth Example webseal-cert-keyfile-stash = pdsrv.sth [ssl] stanza

webseal-cert-keyfile-stash

Syntax

webseal-cert-keyfile-stash = file_name

Description

Name of the file containing an obfuscated version of the password used to protect private keys in the keyfile.

Options

file_name

Name of the file containing an obfuscated version of the password used to protect private keys in the keyfile.

Usage

This stanza entry is optional.

Default value

pdsrv.sth

Example

webseal-cert-keyfile-stash = pdsrv.sth

Parent topic: [ssl] stanza

[ssl-qop] stanza[ssl-qop] stanzassl-qop stanzastanzasssl-qopStanza referencessl-qop-mgmt

[ssl-qop] stanza

ssl-qop-mgmt

Parent topic: Stanza reference

ssl-qop-mgmtssl-qop-mgmtssl-qop-mgmt stanza entryssl-qop stanzaentriesssl-qop-mgmtssl-qop stanzassl-qop stanzassl-qop-mgmt entrySyntax ssl-qop-mgmt = {yes|no}Description Enables or disables SSL quality of protection management.Options yesThe value yes enables SSL quality of protection management.noThe value no disables SSL quality of protection management.Usage This stanza entry is required.Default value noExample ssl-qop-mgmt = no[ssl-qop] stanza

ssl-qop-mgmt

Syntax

ssl-qop-mgmt = {yes|no}

Description

Enables or disables SSL quality of protection management.

Options

yes

The value yes enables SSL quality of protection management.

no

The value no disables SSL quality of protection management.

Usage

This stanza entry is required.

Default value

no

Example

ssl-qop-mgmt = no

Parent topic: [ssl-qop] stanza

[ssl-qop-mgmt-default] stanza[ssl-qop-mgmt-default] stanzassl-qop-mgmt-default stanzastanzasssl-qop-mgmt-defaultStanza referencedefaultUse the default entry in the [ssl-qop-mgmt-default] stanza to define the accepted encryption levels for access to WebSEAL over SSL.

[ssl-qop-mgmt-default] stanza

default
Use the default entry in the [ssl-qop-mgmt-default] stanza to define the accepted encryption levels for access to WebSEAL over SSL.

Parent topic: Stanza reference

defaultdefaultIBM Security Access Manager for Web WebSEAL default stanza entryUse the default entry in the [ssl-qop-mgmt-default] stanza to define the accepted encryption levels for access to WebSEAL over SSL.default stanza entryssl-qop-mgmt-default stanzaentriesdefaultssl-qop-mgmt-default stanzassl-qop-mgmt-default stanzadefault entrySyntax default = {ALL|NONE|cipher_level} Description List of string values to specify the allowed encryption levels for HTTPS access. Values specified in this stanza entry are used for all IP addresses that are not matched in the [ssl-qop-mgmt-networks] stanza entries. Options ALLThe value ALL allows all ciphers.NONEThe value NONE disables all ciphers and uses an MD5 MAC check sum.cipher_levelLegal cipher values are: NULL, DES-56, FIPS-DES-56, DES-168, FIPS-DES-168, RC2-40, RC2-128, RC4-40, RC4-56, RC4-128, AES-128, AES-256ValueCipher name in GSKitNULLTLS_RSA_WITH_NULL_MD5DES-56TLS_RSA_WITH_DES_CBC_SHAFIPS-DES-56SSL_RSA_FIPS_WITH_DES_CBC_SHADES-168SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHAFIPS-DES-168TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHARC2-40TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5RC2-128TLS_RC2_CBC_128_CBC_WITH_MD5RC4-40TLS_RSA_EXPORT_WITH_RC4_40_MD5RC4-56TLS_RSA_EXPORT1024_WITH_RC4_56_SHARC4-128TLS_RSA_WITH_RC4_128_MD5AES-128TLS_RSA_WITH_AES_128_CBC_SHAAES-256TLS_RSA_WITH_AES_256_CBC_SHA Usage This stanza entry is required. Default value ALL Example To specify a selected group of ciphers, create a separate entry for each cipher. For example: default = RC4-128 default = RC2-128 default = DES-168 [ssl-qop-mgmt-default] stanza

default

Use the default entry in the [ssl-qop-mgmt-default] stanza to define the accepted encryption levels for access to WebSEAL over SSL.

Syntax

default = {ALL|NONE|cipher_level}

Description

List of string values to specify the allowed encryption levels for HTTPS access.

Values specified in this stanza entry are used for all IP addresses that are not matched in the [ssl-qop-mgmt-networks] stanza entries.

Options

ALL

The value ALL allows all ciphers.

NONE

The value NONE disables all ciphers and uses an MD5 MAC check sum.

cipher_level

Legal cipher values are: NULL, DES-56, FIPS-DES-56, DES-168, FIPS-DES-168, RC2-40, RC2-128, RC4-40, RC4-56, RC4-128, AES-128, AES-256

Value | Cipher name in GSKit
NULL | TLS_RSA_WITH_NULL_MD5
DES-56 | TLS_RSA_WITH_DES_CBC_SHA
FIPS-DES-56 | SSL_RSA_FIPS_WITH_DES_CBC_SHA
DES-168 | SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
FIPS-DES-168 | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
RC2-40 | TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
RC2-128 | TLS_RC2_CBC_128_CBC_WITH_MD5
RC4-40 | TLS_RSA_EXPORT_WITH_RC4_40_MD5
RC4-56 | TLS_RSA_EXPORT1024_WITH_RC4_56_SHA
RC4-128 | TLS_RSA_WITH_RC4_128_MD5
AES-128 | TLS_RSA_WITH_AES_128_CBC_SHA
AES-256 | TLS_RSA_WITH_AES_256_CBC_SHA

Usage

This stanza entry is required.

Default value

ALL

Example

To specify a selected group of ciphers, create a separate entry for each cipher. For example:

default = RC4-128
default = RC2-128
default = DES-168

Parent topic: [ssl-qop-mgmt-default] stanza

[ssl-qop-mgmt-networks] stanza[ssl-qop-mgmt-networks] stanzassl-qop-mgmt-networks stanzastanzasssl-qop-mgmt-networksStanza referencenetwork/netmask

[ssl-qop-mgmt-networks] stanza

network/netmask

Parent topic: Stanza reference

network/netmasknetwork/netmasknetwork/netmask stanza entryssl-qop-mgmt-networks stanzaentriesnetwork/netmaskssl-qop-mgmt-networks stanzassl-qop-mgmt-networks stanzanetwork/netmask entrySyntax network/netmask = {ALL|NONE|cipher_level} Description List of string values to specify the allowed encryption levels for HTTPS access for a specific combination of IP address and netmask. Note that this stanza has been deprecated and is retained only for backward compatibility. Options ALLThe value ALL allows all ciphers.NONEThe value NONE disables all ciphers and uses an MD5 MAC check sum.cipher_levelLegal cipher values are: NULL, DES-56, FIPS-DES-56, DES-168, FIPS-DES-168, RC2-40, RC2-128, RC4-40, RC4-56, RC4-128, AES-128, AES-256ValueCipher name in GSKitNULLTLS_RSA_WITH_NULL_MD5DES-56TLS_RSA_WITH_DES_CBC_SHAFIPS-DES-56SSL_RSA_FIPS_WITH_DES_CBC_SHADES-168SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHAFIPS-DES-168TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHARC2-40TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5RC2-128TLS_RC2_CBC_128_CBC_WITH_MD5RC4-40TLS_RSA_EXPORT_WITH_RC4_40_MD5RC4-56TLS_RSA_EXPORT1024_WITH_RC4_56_SHARC4-128TLS_RSA_WITH_RC4_128_MD5AES-128TLS_RSA_WITH_AES_128_CBC_SHAAES-256TLS_RSA_WITH_AES_256_CBC_SHA Usage This stanza entry is optional. Default value None. Example To specify allowable ciphers for a selected group of IP addresses and netmasks, create a separate entry for each address/netmask combination. For example: 111.222.333.444/255.255.255.0 = RC4-128 222.666.333.111/255.255.0.0 = RC2-128 [ssl-qop-mgmt-networks] stanza

network/netmask

Syntax

network/netmask = {ALL|NONE|cipher_level}

Description

List of string values to specify the allowed encryption levels for HTTPS access for a specific combination of IP address and netmask.

Note that this stanza has been deprecated and is retained only for backward compatibility.

Options

ALL

The value ALL allows all ciphers.

NONE

The value NONE disables all ciphers and uses an MD5 MAC check sum.

cipher_level

Legal cipher values are: NULL, DES-56, FIPS-DES-56, DES-168, FIPS-DES-168, RC2-40, RC2-128, RC4-40, RC4-56, RC4-128, AES-128, AES-256

Value | Cipher name in GSKit
NULL | TLS_RSA_WITH_NULL_MD5
DES-56 | TLS_RSA_WITH_DES_CBC_SHA
FIPS-DES-56 | SSL_RSA_FIPS_WITH_DES_CBC_SHA
DES-168 | SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
FIPS-DES-168 | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
RC2-40 | TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
RC2-128 | TLS_RC2_CBC_128_CBC_WITH_MD5
RC4-40 | TLS_RSA_EXPORT_WITH_RC4_40_MD5
RC4-56 | TLS_RSA_EXPORT1024_WITH_RC4_56_SHA
RC4-128 | TLS_RSA_WITH_RC4_128_MD5
AES-128 | TLS_RSA_WITH_AES_128_CBC_SHA
AES-256 | TLS_RSA_WITH_AES_256_CBC_SHA

Usage

This stanza entry is optional.

Default value

None.

Example

To specify allowable ciphers for a selected group of IP addresses and netmasks, create a separate entry for each address/netmask combination. For example:

111.222.333.444/255.255.255.0 = RC4-128
222.666.333.111/255.255.0.0 = RC2-128

Parent topic: [ssl-qop-mgmt-networks] stanza

[step-up] stanza[step-up] stanzastep-up stanzastanzasstep-upStanza referenceretain-stepup-sessionshow-all-auth-promptsstep-up-at-higher-levelverify-step-up-user

[step-up] stanza

retain-stepup-session

show-all-auth-prompts

step-up-at-higher-level

verify-step-up-user

Parent topic: Stanza reference

retain-stepup-sessionretain-stepup-sessionretain-stepup-session stanza entrystep-up stanzaentriesretain-stepup-sessionstep-up stanzastep-up stanzaretain-stepup-session entrySyntax retain-stepup-session = {yes|no}Description Determines whether a session cookie issued during a step-up operation is allowed to be reused or not. This option is only in effect if the verify-step-up-user option is set to yes.Options yesEnables session cookie to be reused during a step-up operation.noPrevents session cookie from being reused during a step-up operation.Usage This stanza entry is required.Default value noExample retain-stepup-session = no[step-up] stanza

retain-stepup-session

Syntax

retain-stepup-session = {yes|no}

Description

Determines whether a session cookie issued during a step-up operation is allowed to be reused or not. This option is only in effect if the verify-step-up-user option is set to yes.

Options

yes

Enables session cookie to be reused during a step-up operation.

no

Prevents session cookie from being reused during a step-up operation.

Usage

This stanza entry is required.

Default value

no

Example

retain-stepup-session = no

Parent topic: [step-up] stanza

show-all-auth-promptsshow-all-auth-promptsshow-all-auth-prompts stanza entrystep-up stanzaentriesshow-all-auth-promptsstep-up stanzastep-up stanzashow-all-auth-prompts entrySyntax show-all-auth-prompts = {yes|no}Description Controls login prompt response for an unauthenticated user who requests an object protected by a step-up authentication POP attribute.Options yesA value of "yes" provides multiple login prompts—one for each enabled authentication method—on each login page. noA value of "no" provides only the login prompt for the specific authentication level required by the POP(default).Usage This stanza entry is required.Default value noExample show-all-auth-prompts = no[step-up] stanza

show-all-auth-prompts

Syntax

show-all-auth-prompts = {yes|no}

Description

Controls login prompt response for an unauthenticated user who requests an object protected by a step-up authentication POP attribute.

Options

yes

A value of "yes" provides multiple login prompts—one for each enabled authentication method—on each login page.

no

A value of "no" provides only the login prompt for the specific authentication level required by the POP(default).

Usage

This stanza entry is required.

Default value

no

Example

show-all-auth-prompts = no

Parent topic: [step-up] stanza

step-up-at-higher-levelstep-up-at-higher-levelstep-up-at-higher-level stanza entrystep-up stanzaentriesstep-up-at-higher-levelstep-up stanzastep-up stanzastep-up-at-higher-level entrySyntax step-up-at-higher-level = {yes|no} Description This configuration entry controls whether an authentication mechanism that is higher than the requested step-up level is accepted during a step-up operation. Options yesAuthentication levels higher than the level specified in the POP are accepted during step-up operations.noHigher authentication levels are disallowed during step-up operations. Usage This stanza entry is optional. Default value no Example step-up-at-higher-level = no [step-up] stanza

step-up-at-higher-level

Syntax

step-up-at-higher-level = {yes|no}

Description

This configuration entry controls whether an authentication mechanism that is higher than the requested step-up level is accepted during a step-up operation.

Options

yes

Authentication levels higher than the level specified in the POP are accepted during step-up operations.

no

Higher authentication levels are disallowed during step-up operations.

Usage

This stanza entry is optional.

Default value

no

Example

step-up-at-higher-level = no

Parent topic: [step-up] stanza

verify-step-up-userverify-step-up-userverify-step-up-user stanza entrystep-up stanzaentriesverify-step-up-userstep-up stanzastep-up stanzaverify-step-up-user entrySyntax verify-step-up-user = {yes|no}Description Determines whether the identity of the user performing a step-up operation must match the identity of the user that performed the previous authentication.Options yesThe identity of the user performing the step-up operation must match the identity of the user that performed the previous authentication. In this case, the existing session key will be retained during step-up authentication. The value of the retain-stepup-session option controls whether the existing session key will be retained during step-up authentication.noThe identity of the user performing the step-up operation need not match the identity of the user that performed the previous authentication operation. In this case, the session key must change during step-up authentication.Usage This stanza entry is required.Default value yesExample verify-step-up-user = yes[step-up] stanza

verify-step-up-user

Syntax

verify-step-up-user = {yes|no}

Description

Determines whether the identity of the user performing a step-up operation must match the identity of the user that performed the previous authentication.

Options

yes

The identity of the user performing the step-up operation must match the identity of the user that performed the previous authentication. In this case, the existing session key will be retained during step-up authentication. The value of the retain-stepup-session option controls whether the existing session key will be retained during step-up authentication.

no

The identity of the user performing the step-up operation need not match the identity of the user that performed the previous authentication operation. In this case, the session key must change during step-up authentication.

Usage

This stanza entry is required.

Default value

yes

Example

verify-step-up-user = yes

Parent topic: [step-up] stanza

[system-environment-variables] stanza[system-environment-variables] stanzasystem-environment-variables stanzastanzassystem-environment-variablesStanza referenceenv-nameUse the env-name stanza entry to list the system environment variables that the WebSEAL daemon exports during initialization.

[system-environment-variables] stanza

env-name
Use the env-name stanza entry to list the system environment variables that the WebSEAL daemon exports during initialization.

Parent topic: Stanza reference

env-nameenv-nameIBM Security Access Manager for Web WebSEAL env-name stanza entryUse the env-name stanza entry to list the system environment variables that the WebSEAL daemon exports during initialization.env-name stanza entrysystem-environment-variables stanzaentriesenv-namesystem-environment-variables stanzasystem-environment-variables stanzaenv-name entrySyntax env-name = env-value DescriptionDefines system environment variables that are exported by WebSEAL.During initialization, the WebSEAL daemon exports the environment variables that are defined as entries in the [system-environment-variables] stanza. You must include a separate entry for each system environment variable that you want to export. Options env-nameThe name of the system environment variable.env-valueThe value of the system environment variable. Usage This stanza entry is optional.This functionality is not supported on Windows platforms.The environment variable names are case-sensitive.The PD_SVC_ROUTING_FILE environment variable is not supported. Default value None. ExampleThe following example sets the LANG and GSK_TRACE_FILE environment variables.LANG = de GSK_TRACE_FILE = /tmp/gsk.trace [system-environment-variables] stanza

env-name

Use the env-name stanza entry to list the system environment variables that the WebSEAL daemon exports during initialization.

Syntax

env-name = env-value

Description

Defines system environment variables that are exported by WebSEAL.

During initialization, the WebSEAL daemon exports the environment variables that are defined as entries in the [system-environment-variables] stanza. You must include a separate entry for each system environment variable that you want to export.

Options

env-name

The name of the system environment variable.

env-value

The value of the system environment variable.

Usage

This stanza entry is optional.

Notes:

This functionality is not supported on Windows platforms.

The environment variable names are case-sensitive.

The PD_SVC_ROUTING_FILE environment variable is not supported.

Default value

None.

Example

The following example sets the LANG and GSK_TRACE_FILE environment variables.

LANG = de
GSK_TRACE_FILE = /tmp/gsk.trace

Parent topic: [system-environment-variables] stanza

[tfimsso:<jct-id>] stanza[tfimsso:<jct-id>] stanzatfimsso: jct-id stanzastanzastfimsso:Stanza referencealways-send-tokensUse the always-send-tokens stanza entry to control whether WebSEAL sends a security token for every HTTP request.applies-toUse the applies-to stanza entry to specify the location of the Security Token Service module if you are using Tivoli Federated Identity Manager SSO authentication.one-time-tokenpreserve-xml-tokenrenewal-windowservice-nametfim-cluster-nametoken-collection-sizetoken-typetoken-transmit-nametoken-transmit-type

[tfimsso:<jct-id>] stanza

always-send-tokens
Use the always-send-tokens stanza entry to control whether WebSEAL sends a security token for every HTTP request.

applies-to
Use the applies-to stanza entry to specify the location of the Security Token Service module if you are using Tivoli Federated Identity Manager SSO authentication.

one-time-token

preserve-xml-token

renewal-window

service-name

tfim-cluster-name

token-collection-size

token-type

token-transmit-name

token-transmit-type

Parent topic: Stanza reference

always-send-tokensalways-send-tokensIBM Security Access Manager for Web WebSEAL always-send-tokens stanza entryUse the always-send-tokens stanza entry to control whether WebSEAL sends a security token for every HTTP request.always-send-tokens stanza entrytfimsso: stanzaentriesalways-send-tokenstfimsso: jct-id stanzatfimsso: jct-id stanzaalways-send-tokens entrySyntax always-send-tokens = {yes|true|no|false} Description Indicates whether WebSEAL sends a security token for every HTTP request or whether WebSEAL waits for a 401 response before it adds the security token. You can use this configuration item to avoid generating and adding a security token to every request if the back-end web server can maintain user sessions. This configuration item is only useful if the request for authentication involves a 401 response, which currently applies to Tivoli Federated Identity Manager single sign-on only. Options yesWebSEAL sends a security token for every HTTP request.noWebSEAL waits for a 401 response before it sends a security token for an HTTP request. Usage This stanza entry is required when Tivoli Federated Identity Manager single sign-on authentication is used over junctions. Default value None Example always-send-tokens = false [tfimsso:<jct-id>] stanza

always-send-tokens

Use the always-send-tokens stanza entry to control whether WebSEAL sends a security token for every HTTP request.

Syntax

always-send-tokens = {yes|true|no|false}

Description

Indicates whether WebSEAL sends a security token for every HTTP request or whether WebSEAL waits for a 401 response before it adds the security token.

You can use this configuration item to avoid generating and adding a security token to every request if the back-end web server can maintain user sessions. This configuration item is only useful if the request for authentication involves a 401 response, which currently applies to Tivoli® Federated Identity Manager single sign-on only.

Options

yes

WebSEAL sends a security token for every HTTP request.

no

WebSEAL waits for a 401 response before it sends a security token for an HTTP request.

Usage

This stanza entry is required when Tivoli Federated Identity Manager single sign-on authentication is used over junctions.

Default value

None

Example

always-send-tokens = false

Parent topic: [tfimsso:<jct-id>] stanza

applies-toapplies-toIBM Security Access Manager for Web WebSEAL applies-to stanza entryUse the applies-to stanza entry to specify the location of the Security Token Service module if you are using Tivoli Federated Identity Manager SSO authentication.applies-to stanza entrytfimsso: stanzaentriesapplies-totfimsso: jct-id stanzatfimsso: jct-id stanza applies-to entrySyntax applies-to = http://<webseal-server>/<junction> Description Path to specify the location to search for the appropriate Security Token Service (STS) module in Tivoli Federated Identity Manager. Options http://<webseal-server>/<junction>The host name or IP address of the WebSEAL server, along with the junction name. This address is similar to the URL that is used to access the junction. Usage This stanza entry is required when Tivoli Federated Identity Manager SSO authentication is used over junctions. Default value None Example applies-to = http://webseal-server/jct [tfimsso:<jct-id>] stanza

applies-to

Use the applies-to stanza entry to specify the location of the Security Token Service module if you are using Tivoli Federated Identity Manager SSO authentication.

Syntax

applies-to = http://<webseal-server>/<junction>

Description

Path to specify the location to search for the appropriate Security Token Service (STS) module in Tivoli Federated Identity Manager.

Options

http://<webseal-server>/<junction>

The host name or IP address of the WebSEAL server, along with the junction name. This address is similar to the URL that is used to access the junction.

Usage

This stanza entry is required when Tivoli Federated Identity Manager SSO authentication is used over junctions.

Default value

None

Example

applies-to = http://webseal-server/jct

Parent topic: [tfimsso:<jct-id>] stanza

one-time-tokenone-time-tokenone-time-token stanza entrytfimsso: stanzaentriesone-time-tokentfimsso: jct-id stanzatfimsso: jct-id stanzaone-time-token entrySyntax one-time-token = {true | false} Description This boolean value is used to indicate whether the security token that is produced by TFIM is only valid for a single transaction. An example of a one-time-token is a Kerberos token, which can only be used for a single authentication operation. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value True. Example one-time-token = false [tfimsso:<jct-id>] stanza

one-time-token

Syntax

one-time-token = {true | false}

Description

This boolean value is used to indicate whether the security token that is produced by TFIM is only valid for a single transaction. An example of a one-time-token is a Kerberos token, which can only be used for a single authentication operation.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

True.

Example

one-time-token = false

Parent topic: [tfimsso:<jct-id>] stanza

preserve-xml-tokenpreserve-xml-tokenpreserve-xml-token stanza entrytfimsso: stanzaentriespreserve-xml-tokentfimsso:jct-id stanzatfimsso: jct-id stanza preserve-xml-token entrySyntax preserve-xml-token = {true | false} Description This value controls whether to use the requested BinarySecurityToken XML structure in its entirety or whether only the encapsulated token should be used. Set this configuration entry to true only if the junctioned Web server understands and expects the BinarySecurityToken XML structure. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value True. Example preserve-xml-token = false [tfimsso:<jct-id>] stanza

preserve-xml-token

Syntax

preserve-xml-token = {true | false}

Description

This value controls whether to use the requested BinarySecurityToken XML structure in its entirety or whether only the encapsulated token should be used. Set this configuration entry to true only if the junctioned Web server understands and expects the BinarySecurityToken XML structure.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

True.

Example

preserve-xml-token = false

Parent topic: [tfimsso:<jct-id>] stanza

renewal-windowrenewal-windowrenewal-window stanza entrytfimsso: stanzaentriesrenewal-windowtfimsso: jct-id stanzatfimsso: jct-id stanza renewal-window entrySyntax renewal-window = number of seconds Description The length of time, in seconds, by which the expiration of security tokens will be reduced. This entry is used to make allowances for differences in system times and transmission times for the security tokens. Options number of secondsNumber of seconds by which the expiration of security tokens will be reduced to make allowances for differences between system times and transmission times for security tokens. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value None Example renewal-window = 15 [tfimsso:<jct-id>] stanza

renewal-window

Syntax

renewal-window = number of seconds

Description

The length of time, in seconds, by which the expiration of security tokens will be reduced. This entry is used to make allowances for differences in system times and transmission times for the security tokens.

Options

number of seconds

Number of seconds by which the expiration of security tokens will be reduced to make allowances for differences between system times and transmission times for security tokens.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

None

Example

renewal-window = 15

Parent topic: [tfimsso:<jct-id>] stanza

service-nameservice-nameservice-name stanza entrytfimsso: jct-id stanzaentriesservice-nametfimsso: jct-id stanzatfimsso: jct-id stanza service-name entrySyntax service-name = <servicename> Description Used by TFIM when searching for a matching trust chain. This configuration entry will be compared against the configured AppliesTo service name value for each trust chain. The second field within the AppliesTo service name configuration entry should be set to either asterisk (*) to match all service names, or it should be set to the value defined by this configuration item. See the TFIM documentation for further details on configuring Trust Chains.Used as the service principal name of the delegating user when creating a Kerberos token. The service principal name can be determined by executing the Microsoft utility setspn (that is, setspn -L user, where user is the identity of the user on the junctioned Web server). Options <service name>The service name which is used to locate the trust chain within TFIM. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value None service-name = HTTP/bigblue.wma.ibm.com [tfimsso:<jct-id>] stanza

service-name

Syntax

service-name = <servicename>

Description

Used by TFIM when searching for a matching trust chain. This configuration entry will be compared against the configured AppliesTo service name value for each trust chain. The second field within the AppliesTo service name configuration entry should be set to either asterisk (*) to match all service names, or it should be set to the value defined by this configuration item. See the TFIM documentation for further details on configuring Trust Chains.

Used as the service principal name of the delegating user when creating a Kerberos token. The service principal name can be determined by executing the Microsoft utility setspn (that is, setspn -L user, where user is the identity of the user on the junctioned Web server).

Options

<service name>

The service name which is used to locate the trust chain within TFIM.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

None

service-name = HTTP/bigblue.wma.ibm.com

Parent topic: [tfimsso:<jct-id>] stanza

tfim-cluster-nametfim-cluster-nametfim-cluster-name stanza entrytfimsso: stanzaentriestfim-cluster-nametfimsso: jct-id stanzatfimsso: jct-id stanza tfim-cluster-name entrySyntax tfim-cluster-name = name of cluster Description The name of the WebSphere cluster for the Tivoli Federated Identity Manager service. The cluster is defined by this stanza entry along with a corresponding [tfim-cluster:<cluster>] stanza. Options name of clusterThe name of the WebSphere cluster that contains the Tivoli Federated Identity Manager service. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value None tfim-cluster-name = wascluster01 [tfimsso:<jct-id>] stanza

tfim-cluster-name

Syntax

tfim-cluster-name = name of cluster

Description

The name of the WebSphere® cluster for the Tivoli Federated Identity Manager service. The cluster is defined by this stanza entry along with a corresponding [tfim-cluster:<cluster>] stanza.

Options

name of cluster

The name of the WebSphere cluster that contains the Tivoli Federated Identity Manager service.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

None

tfim-cluster-name = wascluster01

Parent topic: [tfimsso:<jct-id>] stanza

token-collection-sizetoken-collection-sizetoken-collection-size stanza entrytfimsso: stanzaentriestoken-collection-sizetfimsso: jct-id stanzatfimsso: jct-id stanza token-collection-size entrySyntax token-collection-size = number Description Specifies the number of security tokens for WebSEAL to retrieve from Tivoli Federated Identity Manager in a single request. This construct is currently only supported for the Kerberos STS module. The number value for this stanza entry should be relatively low. Each token retrieved from Tivoli Federated Identity Manager (TFIM) is quite large; specifying a large number dramatically increases the size of the packets received from TFIM, which in turn increases the size of the session and the amount of memory used by WebSEAL. Options numberThe number of security tokens that WebSEAL will retrieve from Tivoli Federated Identity Manager and cache for subsequent requests. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value None Example token-collection-size = 10 [tfimsso:<jct-id>] stanza

token-collection-size

Syntax

token-collection-size = number

Description

Specifies the number of security tokens for WebSEAL to retrieve from Tivoli Federated Identity Manager in a single request. This construct is currently only supported for the Kerberos STS module.

Note: The number value for this stanza entry should be relatively low. Each token retrieved from Tivoli Federated Identity Manager (TFIM) is quite large; specifying a large number dramatically increases the size of the packets received from TFIM, which in turn increases the size of the session and the amount of memory used by WebSEAL.

Options

number

The number of security tokens that WebSEAL will retrieve from Tivoli Federated Identity Manager and cache for subsequent requests.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

None

Example

token-collection-size = 10

Parent topic: [tfimsso:<jct-id>] stanza

token-typetoken-typetoken-type stanza entrytfimsso: stanzaentriestoken-typetfimsso: jct-id stanzatfimsso: jct-id stanzatoken-type entrySyntax token-type = token_type Description Specifies the type of token to be requested from Tivoli Federated Identity Manager. This value should correspond to the 'Token Type URI' field for the corresponding trust chain within TFIM. Options token_typeIndicates that the type of token to be requested from Tivoli Federated Identity Manager. Available options are Kerberos, SAML and LDAP. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value None Example token-type = http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1. 1#GSS_Kerberosv5_AP_REQ [tfimsso:<jct-id>] stanza

token-type

Syntax

token-type = token_type

Description

Specifies the type of token to be requested from Tivoli Federated Identity Manager. This value should correspond to the 'Token Type URI' field for the corresponding trust chain within TFIM.

Options

token_type

Indicates that the type of token to be requested from Tivoli Federated Identity Manager. Available options are Kerberos, SAML and LDAP.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

None

Example

token-type = http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.
1#GSS_Kerberosv5_AP_REQ

Parent topic: [tfimsso:<jct-id>] stanza

token-transmit-nametoken-transmit-nametoken-transmit-name stanza entrytfimsso: stanzaentriestoken-transmit-nametfimsso: jct-id stanzatfimsso: jct-id stanza token-transmit-name entrySyntax token-transmit-name = text Description The name given to the security token within the junctioned Web server request. Options textThis is a free text field. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value None Example token-transmit-name = Authorization [tfimsso:<jct-id>] stanza

token-transmit-name

Syntax

token-transmit-name = text

Description

The name given to the security token within the junctioned Web server request.

Options

text

This is a free text field.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

None

Example

token-transmit-name = Authorization

Parent topic: [tfimsso:<jct-id>] stanza

token-transmit-typetoken-transmit-typetoken-transmit-type stanza entrytfimsso: stanzaentriestoken-transmit-typetfimsso: jct-id stanzatfimsso: jct-id stanza token-transmit-type entrySyntax token-transmit-type = {header | cookie} Description The type of mechanism which will be used to transmit the security token to the junctioned Web server. Options headerThe security token will be included in a header.cookieThe security token will be included in a cookie. Usage This stanza entry is required when TFIM SSO authentication is used over junctions. Default value None Example token-transmit-type = header [tfimsso:<jct-id>] stanza

token-transmit-type

Syntax

token-transmit-type = {header | cookie}

Description

The type of mechanism which will be used to transmit the security token to the junctioned Web server.

Options

header

The security token will be included in a header.

cookie

The security token will be included in a cookie.

Usage

This stanza entry is required when TFIM SSO authentication is used over junctions.

Default value

None

Example

token-transmit-type = header

Parent topic: [tfimsso:<jct-id>] stanza

[tfim-cluster:<cluster>] stanza[tfim-cluster:<cluster>] stanzatfim-cluster: stanza stanzatfim-cluster: clusterThis stanza contains definitions for a particular cluster of Tivoli Federated Identity Manager servers.Stanza referencebasic-auth-userUse the basic-auth-user stanza entry to specify the user name to include in the basic authentication header when WebSEAL communicates with Tivoli Federated Identity Manager.basic-auth-passwdUse the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header when it communicates with Tivoli Federated Identity Manager.gsk-attr-namehandle-idle-timeouthandle-pool-sizeserverssl-fips-enabledssl-keyfilessl-keyfile-labelssl-keyfile-stashssl-nist-complianceUse the ssl-nist-compliance stanza entry in the [tfim-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance when WebSEAL communicates with Tivoli Federated Identity Manager.ssl-valid-server-dntimeout

[tfim-cluster:<cluster>] stanza

This stanza contains definitions for a particular cluster of Tivoli Federated Identity Manager servers.

basic-auth-user
Use the basic-auth-user stanza entry to specify the user name to include in the basic authentication header when WebSEAL communicates with Tivoli Federated Identity Manager.

basic-auth-passwd
Use the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header when it communicates with Tivoli Federated Identity Manager.

gsk-attr-name

handle-idle-timeout

handle-pool-size

server

ssl-fips-enabled

ssl-keyfile

ssl-keyfile-label

ssl-keyfile-stash

ssl-nist-compliance
Use the ssl-nist-compliance stanza entry in the [tfim-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance when WebSEAL communicates with Tivoli Federated Identity Manager.

ssl-valid-server-dn

timeout

Parent topic: Stanza reference

basic-auth-userbasic-auth-userIBM Security Access Manager for Web WebSEAL basic-auth-user stanza entryUse the basic-auth-user stanza entry to specify the user name to include in the basic authentication header when WebSEAL communicates with Tivoli Federated Identity Manager.basic-auth-user stanza entrytfim-cluster: stanzaentriesbasic-auth-usertfim-cluster: cluster stanzatfim-cluster: cluster stanza basic-auth-user entrySyntax basic-auth-user = <user_name> Description Specifies the name of the user for WebSEAL to include in the basic authentication header when it is communicating with the Tivoli Federated Identity Manager server. Options <user_name>The user name that WebSEAL includes in the basic authentication header. Usage This stanza entry is optional.Configure this entry if the Tivoli Federated Identity Manager server is configured to require basic authentication. Default value None. Example basic-auth-user = user_name [tfim-cluster:<cluster>] stanza

basic-auth-user

Use the basic-auth-user stanza entry to specify the user name to include in the basic authentication header when WebSEAL communicates with Tivoli Federated Identity Manager.

Syntax

basic-auth-user = <user_name>

Description

Specifies the name of the user for WebSEAL to include in the basic authentication header when it is communicating with the Tivoli Federated Identity Manager server.

Options

<user_name>

The user name that WebSEAL includes in the basic authentication header.

Usage

This stanza entry is optional.

Note: Configure this entry if the Tivoli Federated Identity Manager server is configured to require basic authentication.

Default value

None.

Example

basic-auth-user = user_name

Parent topic: [tfim-cluster:<cluster>] stanza

basic-auth-passwdbasic-auth-passwdIBM Security Access Manager for Web WebSEAL basic-auth-passwd stanza entryUse the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header when it communicates with Tivoli Federated Identity Manager.basic-auth-passwd stanza entrytfim-cluster: stanzaentriesbasic-auth-passwdtfim-cluster: cluster stanzatfim-cluster: cluster stanzabasic-auth-passwd entrySyntax basic-auth-passwd = <password> Description Specifies the password for WebSEAL to include in the basic authentication header when it is communicating with the Tivoli Federated Identity Manager server. Options <password>The password that WebSEAL includes in the basic authentication header. Usage This stanza entry is optional.Configure this entry if the Tivoli Federated Identity Manager server is configured to require basic authentication. Default value None. Example basic-auth-passwd = password [tfim-cluster:<cluster>] stanza

basic-auth-passwd

Use the basic-auth-passwd stanza entry to specify the password that WebSEAL includes in the basic authentication header when it communicates with Tivoli Federated Identity Manager.

Syntax

basic-auth-passwd = <password>

Description

Specifies the password for WebSEAL to include in the basic authentication header when it is communicating with the Tivoli Federated Identity Manager server.

Options

<password>

The password that WebSEAL includes in the basic authentication header.

Usage

This stanza entry is optional.

Note: Configure this entry if the Tivoli Federated Identity Manager server is configured to require basic authentication.

Default value

None.

Example

basic-auth-passwd = password

Parent topic: [tfim-cluster:<cluster>] stanza

gsk-attr-namegsk-attr-namegsk-attr-name stanza entrytfim-cluster: cluster stanzaentriesgsk-attr-nametfim-cluster: cluster stanzatfim-cluster: cluster stanza gsk-attr-name entrySyntax gsk-attr-name = {enum | string | number}:id:value Description Specify additional GSKit attributes to use when initializing an SSL connection with Tivoli Federated Identity Manager. This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute. Options {enum | string | number}The GSKit attribute type.idThe identity associated with the GSKit attribute.valueThe value for the GSKit attribute. Usage This stanza entry is optional. See Appendix: Supported GSKit attributesYou can configure the these GSKit attributes with Security Access Manager. for a list of GSKit attributes that can be configured.You cannot configure the following restricted GSKit attributes: GSK_KEYRING_FILE GSK_KEYRING_STASH_FILE GSK_KEYRING_LABEL GSK_CIPHER_V2 GSK_V3_CIPHER_SPECS GSK_PROTOCOL_TLSV1 GSK_FIPS_MODE_PROCESSINGIf you attempt to modify any of these attributes then an error message will be generated. Default value None. Example The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:gsk-attr-name = string:225:proxy.ibm.com See alsogsk-attr-nameUse the gsk-attr-name stanza entry to specify additional GSKit attributes to use when initializing an SSL connection with the distributed session cache. gsk-attr-name jct-gsk-attr-name[tfim-cluster:<cluster>] stanza

gsk-attr-name

Syntax

gsk-attr-name = {enum | string | number}:id:value

Description

Specify additional GSKit attributes to use when initializing an SSL connection with Tivoli® Federated Identity Manager. This configuration entry can be specified multiple times. Configure a separate entry for each GSKit attribute.

Options

{enum | string | number}

The GSKit attribute type.

id

The identity associated with the GSKit attribute.

value

The value for the GSKit attribute.

Usage

This stanza entry is optional.

See Appendix: Supported GSKit attributes for a list of GSKit attributes that can be configured.

You cannot configure the following restricted GSKit attributes:

GSK_KEYRING_FILE
GSK_KEYRING_STASH_FILE
GSK_KEYRING_LABEL
GSK_CIPHER_V2
GSK_V3_CIPHER_SPECS
GSK_PROTOCOL_TLSV1
GSK_FIPS_MODE_PROCESSING

If you attempt to modify any of these attributes then an error message will be generated.

Default value

None.

Example

The following entry is for the GSKit attribute GSK_HTTP_PROXY_SERVER_NAME, which has an identity value of 225:

gsk-attr-name = string:225:proxy.ibm.com

See also

gsk-attr-name

gsk-attr-name

jct-gsk-attr-name

Parent topic: [tfim-cluster:<cluster>] stanza

handle-idle-timeouthandle-idle-timeouthandle-idle-timeout stanza entrytfim-cluster: stanzaentrieshandle-idle-timeouttfim-cluster: cluster stanzatfim-cluster: cluster stanzaSyntax handle-idle-timeout = <number> Description Specifies the length of time, in seconds, before an idle handle is removed from the handle pool cache. Options <number>Length of time, in seconds, before an idle handle is removed from the handle pool cache. Usage This stanza entry is required when Kerberos authentication is used over junctions. Default value None Example handle-idle-timeout = 240 [tfim-cluster:<cluster>] stanza

handle-idle-timeout

Syntax

handle-idle-timeout = <number>

Description

Specifies the length of time, in seconds, before an idle handle is removed from the handle pool cache.

Options

<number>

Length of time, in seconds, before an idle handle is removed from the handle pool cache.

Usage

This stanza entry is required when Kerberos authentication is used over junctions.

Default value

None

Example

handle-idle-timeout = 240

Parent topic: [tfim-cluster:<cluster>] stanza

handle-pool-sizehandle-pool-sizehandle-pool-size stanza entrytfim-cluster: cluster stanzaentrieshandle-pool-sizetfim-cluster: cluster stanzatfim-cluster: cluster stanza handle-pool-size entrySyntax handle-pool-size = <number> Description Specifies the maximum number of cached handles that WebSEAL uses when communicating with Tivoli Federated Identity Manager. Options <number>Maximum number of handles that WebSEAL caches to communicate with Tivoli Federated Identity Manager. Usage This stanza entry is required when Kerberos authentication is used over junctions. Default value 10 Example handle-pool-size = 10 [tfim-cluster:<cluster>] stanza

handle-pool-size

Syntax

handle-pool-size = <number>

Description

Specifies the maximum number of cached handles that WebSEAL uses when communicating with Tivoli Federated Identity Manager.

Options

<number>

Maximum number of handles that WebSEAL caches to communicate with Tivoli Federated Identity Manager.

Usage

This stanza entry is required when Kerberos authentication is used over junctions.

Default value

10

Example

handle-pool-size = 10

Parent topic: [tfim-cluster:<cluster>] stanza

serverserverserver stanza entrytfim-cluster: cluster stanzaentriesservertfim-cluster: cluster stanzatfim-cluster: cluster stanza server entrySyntax server = {[0-9],}<URL> Description Specifies the priority level and URL for a single Tivoli Federated Identity Manager server that is a member of the cluster identified for this [tfim-cluster:<cluster>] stanza. Options [0-9]A digit, 0-9, that represents the priority of this server within the cluster (9 is the highest, 0 is the lowest). If the priority is not specified, a priority of 9 is assumed. There can be no space between the comma (,) and the URL. If no priority is specified, the comma is omitted.<URL>A well-formed HTTP or HTTPS uniform resource locator for the server. Usage This stanza entry is required when Kerberos authentication is used over junctions.You can specify multiple server entries for a particular cluster for failover and load balancing. Default value None Example server = 9,http://tfim-server.example.com/TrustServerWST13/ services/RequestSecurityToken [tfim-cluster:<cluster>] stanza

server

Syntax

server = {[0-9],}<URL>

Description

Specifies the priority level and URL for a single Tivoli Federated Identity Manager server that is a member of the cluster identified for this [tfim-cluster:<cluster>] stanza.

Options

[0-9]

A digit, 0-9, that represents the priority of this server within the cluster (9 is the highest, 0 is the lowest). If the priority is not specified, a priority of 9 is assumed.

Note: There can be no space between the comma (,) and the URL. If no priority is specified, the comma is omitted.

<URL>

A well-formed HTTP or HTTPS uniform resource locator for the server.

Usage

This stanza entry is required when Kerberos authentication is used over junctions.

Note: You can specify multiple server entries for a particular cluster for failover and load balancing.

Default value

None

Example

server = 9,http://tfim-server.example.com/TrustServerWST13/
 services/RequestSecurityToken

Parent topic: [tfim-cluster:<cluster>] stanza

ssl-fips-enabledssl-fips-enabledssl-fips-enabled stanza entrytfim-cluster: cluster stanzaentriesssl-fips-enabledtfim-cluster: cluster stanzatfim-cluster: cluster stanza ssl-fips-enabled entrySyntax ssl-fips-enabled = {yes|no} Description Determines whether Federal Information Process Standards (FIPS) mode is enabled with Tivoli Federated Identity Manager. If no configuration entry is present, the setting from the global setting, determined by the Access Manager policy server, takes effect.The [tfim-cluster:<cluster>] ssl-nist-compliance setting can override this entry. If ssl-nist-compliance is set to yes, FIPS mode processing is automatically enabled. Options yesFIPS mode is enabled.noFIPS mode is disabled. Usage This stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. If this entry is required, but it is not specified in the [tfim-cluster:<cluster>] stanza, WebSEAL uses the value in the global [ssl] stanza. Default value None.If you want to use a FIPS level that is different to the Access Manager policy server, edit the configuration file and specify a value for this entry. Example ssl-fips-enabled = yes [tfim-cluster:<cluster>] stanza

ssl-fips-enabled

Syntax

ssl-fips-enabled = {yes|no}

Description

Determines whether Federal Information Process Standards (FIPS) mode is enabled with Tivoli Federated Identity Manager.

Notes:

If no configuration entry is present, the setting from the global setting, determined by the Access Manager policy server, takes effect.

The [tfim-cluster:<cluster>] ssl-nist-compliance setting can override this entry. If ssl-nist-compliance is set to yes, FIPS mode processing is automatically enabled.

Options

yes

FIPS mode is enabled.

no

FIPS mode is disabled.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Note: If this entry is required, but it is not specified in the [tfim-cluster:<cluster>] stanza, WebSEAL uses the value in the global [ssl] stanza.

Default value

None.

Note: If you want to use a FIPS level that is different to the Access Manager policy server, edit the configuration file and specify a value for this entry.

Example

ssl-fips-enabled = yes

Parent topic: [tfim-cluster:<cluster>] stanza

ssl-keyfilessl-keyfilessl-keyfile stanza entrytfim-cluster: stanzaentriesssl-keyfiletfim-cluster: cluster stanzatfim-cluster: cluster stanza ssl-keyfile entrySyntax ssl-keyfile = <file_name> Description Specifies the name of the key database file that houses the client certificate for WebSEAL to use. Options <file_name>Name of the key database file that contains the client-side certificate for WebSEAL to use when Tivoli Federated Identity Manager single sign-on is enabled for the junction. Usage This stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-keyfile = default-webseald.kdb [tfim-cluster:<cluster>] stanza

ssl-keyfile

Syntax

ssl-keyfile = <file_name>

Description

Specifies the name of the key database file that houses the client certificate for WebSEAL to use.

Options

<file_name>

Name of the key database file that contains the client-side certificate for WebSEAL to use when Tivoli Federated Identity Manager single sign-on is enabled for the junction.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-keyfile = default-webseald.kdb

Parent topic: [tfim-cluster:<cluster>] stanza

ssl-keyfile-labelssl-keyfile-labelssl-keyfile-label stanza entrytfim-cluster: stanzaentriesssl-keyfile-labeltfim-cluster:cluster stanzatfim-cluster: cluster stanza ssl-keyfile-label entrySyntax ssl-keyfile-label = <label-name> Description Specifies the label of the client-side certificate in the key database. Options <label-name>Label of the client-side certificate in the key database. Usage This stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-keyfile-label = WebSEAL-Test [tfim-cluster:<cluster>] stanza

ssl-keyfile-label

Syntax

ssl-keyfile-label = <label-name>

Description

Specifies the label of the client-side certificate in the key database.

Options

<label-name>

Label of the client-side certificate in the key database.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-keyfile-label = WebSEAL-Test

Parent topic: [tfim-cluster:<cluster>] stanza

ssl-keyfile-stashssl-keyfile-stashssl-keyfile-stash stanza entry cluster stanzatfim-cluster: stanzaentriesssl-keyfile-stashtfim-cluster: cluster stanzatfim-cluster: cluster stanza ssl-keyfile-stash entrySyntax ssl-keyfile-stash = <filename.sth> Description Specifies the name of the password stash file for the key database file. Options <filename.sth>The name of the password stash file for the key database file. Usage This stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-keyfile-stash = default-webseald.sth [tfim-cluster:<cluster>] stanza

ssl-keyfile-stash

Syntax

ssl-keyfile-stash = <filename.sth>

Description

Specifies the name of the password stash file for the key database file.

Options

<filename.sth>

The name of the password stash file for the key database file.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-keyfile-stash = default-webseald.sth

Parent topic: [tfim-cluster:<cluster>] stanza

ssl-nist-compliancessl-nist-complianceIBM Security Access Manager for Web WebSEAL ssl-nist-compliance stanza entryUse the ssl-nist-compliance stanza entry in the [tfim-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance when WebSEAL communicates with Tivoli Federated Identity Manager.ssl-nist-compliance stanza entrytfim-cluster:cluster stanzaentriesssl-nist-compliancetfim-cluster:cluster stanzatfim-cluster: cluster stanzassl-nist-compliance entrySyntax ssl-nist-compliance = {yes|no} Description Enables or disables NIST SP800-131A compliance when WebSEAL communicates with Tivoli Federated Identity Manager.Enabling NIST SP800-131A compliance results in the following automatic configuration:Enables FIPS mode processing. When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the [tfim-cluster:<cluster>] ssl-fips-enabled configuration entry.Enables TLS v1.2. TLS v1 and TLS v1.1 are not disabled.Enables the appropriate signature algorithms.Sets the minimum RSA key size to 2048 bytes.If this ssl-nist-compliance configuration entry is not present, WebSEAL uses the global nist-compliance setting in the [ssl] stanza. Options yesA value of yes enables NIST SP800-131A compliance. noA value of no disables NIST SP800-131A compliance. Usage This stanza entry is optional. Default value no Example ssl-nist-compliance = no [tfim-cluster:<cluster>] stanza

ssl-nist-compliance

Use the ssl-nist-compliance stanza entry in the [tfim-cluster:<cluster>] stanza to enable or disable NIST SP800-131A compliance when WebSEAL communicates with Tivoli Federated Identity Manager.

Syntax

ssl-nist-compliance = {yes|no}

Description

Enables or disables NIST SP800-131A compliance when WebSEAL communicates with Tivoli Federated Identity Manager.

Enabling NIST SP800-131A compliance results in the following automatic configuration:

Enables FIPS mode processing.

Note: When NIST SP800-131A compliance is enabled, FIPS mode processing is enabled regardless of the setting for the [tfim-cluster:<cluster>] ssl-fips-enabled configuration entry.

Enables TLS v1.2.

Note: TLS v1 and TLS v1.1 are not disabled.

Enables the appropriate signature algorithms.

Sets the minimum RSA key size to 2048 bytes.

If this ssl-nist-compliance configuration entry is not present, WebSEAL uses the global nist-compliance setting in the [ssl] stanza.

Options

yes

A value of yes enables NIST SP800-131A compliance.

no

A value of no disables NIST SP800-131A compliance.

Usage

This stanza entry is optional.

Default value

no

Example

ssl-nist-compliance = no

Parent topic: [tfim-cluster:<cluster>] stanza

ssl-valid-server-dnssl-valid-server-dnssl-valid-server-dn stanza entrytfim-cluster: cluster stanzaentriesssl-valid-server-dntfim-cluster:cluster stanzatfim-cluster: cluster stanza ssl-valid-server-dn entrySyntax ssl-valid-server-dn = <DN-value> Description Specifies the distinguished name of the server, which is obtained from the server SSL certificate, that WebSEAL can accept. Options <DN-value>The distinguished name of the server, which is obtained from the server SSL certificate, that WebSEAL accepts. If no value is specified, then WebSEAL considers all domain names valid. You can specify multiple domain names by including multiple ssl-valid-server-dn configuration entries. Usage This stanza entry is required if both of the following conditions are true:One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server. Default value None. Example ssl-valid-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US [tfim-cluster:<cluster>] stanza

ssl-valid-server-dn

Syntax

ssl-valid-server-dn = <DN-value>

Description

Specifies the distinguished name of the server, which is obtained from the server SSL certificate, that WebSEAL can accept.

Options

<DN-value>

The distinguished name of the server, which is obtained from the server SSL certificate, that WebSEAL accepts. If no value is specified, then WebSEAL considers all domain names valid. You can specify multiple domain names by including multiple ssl-valid-server-dn configuration entries.

Usage

This stanza entry is required if both of the following conditions are true:

One or more of the cluster server entries use SSL (that is, contains an HTTPS protocol specification in the URL).

A certificate is required other than the default certificate used by WebSEAL when communicating with the policy server.

Default value

None.

Example

ssl-valid-server-dn = CN=Access Manager,OU=SecureWay,O=Tivoli,C=US

Parent topic: [tfim-cluster:<cluster>] stanza

timeouttimeouttimeout stanza entrytfim-cluster: stanzaentriestimeouttfim-cluster: cluster stanzatfim-cluster: cluster stanzatimeout entrySyntax timeout = <number of seconds> Description Specifies the length of time, in seconds, to wait for a response from Tivoli Federated Identity Manager. Options <number of seconds>The length of time, in seconds, to wait for a response from Tivoli Federated Identity Manager. Usage This stanza entry is required when Kerberos authentication is used over junctions. Default value None. Example timeout = 240 [tfim-cluster:<cluster>] stanza

timeout

Syntax

timeout = <number of seconds>

Description

Specifies the length of time, in seconds, to wait for a response from Tivoli Federated Identity Manager.

Options

<number of seconds>

The length of time, in seconds, to wait for a response from Tivoli Federated Identity Manager.

Usage

This stanza entry is required when Kerberos authentication is used over junctions.

Default value

None.

Example

timeout = 240

Parent topic: [tfim-cluster:<cluster>] stanza

[token] stanza[token] stanzaUse this stanza to define your token settings.token stanzastanzastokenStanza referencetoken-authEnables authentication by using the token authentication mechanism.

[token] stanza

Use this stanza to define your token settings.

token-auth
Enables authentication by using the token authentication mechanism.

Parent topic: Stanza reference

token-authtoken-authEnables authentication by using the token authentication mechanism. token-auth stanza entrytoken stanzaentriestoken-authtoken stanzatoken stanzatoken-auth entrySyntax token-auth = {none|http|https|both}Description This entry specifies which protocols are supported.Options {none|http|https|both}The value both means both HTTP and HTTPS.Usage This stanza entry is required.Default value noneExample token-auth = none[token] stanzaUse this stanza to define your token settings.

token-auth

Enables authentication by using the token authentication mechanism.

Syntax

token-auth = {none|http|https|both}

Description

This entry specifies which protocols are supported.

Options

{none|http|https|both}

The value both means both HTTP and HTTPS.

Usage

This stanza entry is required.

Default value

none

Example

token-auth = none

Parent topic: [token] stanza

[user-agent] stanza[user-agent] stanzaIBM Security Access Manager for Web WebSEAL [user-agent] stanzaUse the [user-agent] stanza to specify a category name for a particular user-agent string in the HTTP Request header. WebSEAL uses the user-agent string to categorize the incoming requests to make flow data statistics more meaningful.user-agent stanzastanzasuser-agentStanza referenceuser-agentUse the user-agent stanza entry to configure the category name that WebSEAL uses for a particular user-agent string in the HTTP Request header when it categorizes the incoming requests.

[user-agent] stanza

Use the [user-agent] stanza to specify a category name for a particular user-agent string in the HTTP Request header. WebSEAL uses the user-agent string to categorize the incoming requests to make flow data statistics more meaningful.

user-agent
Use the user-agent stanza entry to configure the category name that WebSEAL uses for a particular user-agent string in the HTTP Request header when it categorizes the incoming requests.

Parent topic: Stanza reference

user-agentuser-agentIBM Security Access Manager for Web WebSEAL user-agent stanza entryUse the user-agent stanza entry to configure the category name that WebSEAL uses for a particular user-agent string in the HTTP Request header when it categorizes the incoming requests.user-agent stanza entryuser-agent stanzaentriesuser-agentuser-agent stanzauser-agent stanzauser-agent entrySyntax user-agent = pattern Description When WebSEAL records flow data statistics, it can use the user-agent string in the HTTP Request header to categorize the incoming requests. Categorizing requests based on the user-agent can make the statistical data more useful. Use this stanza to specify a list of category names and patterns for the user-agent strings to match. You can repeat a category so that multiple patterns match a single category. The patterns are evaluated in the order of their definition. WebSEAL selects the first match to categorize each request. The stanza must always end with an entry that contains the match-all pattern *. Options patternThe appliance uses this pattern to categorize the incoming requests. The appliance categorizes each request by matching the user-agent string value in the HTTP Request header with the defined pattern list.The pattern can contain the wildcard characters * and ?. The patterns are not case-sensitive. Usage This stanza entry is optional. Default value None. ExampleIn this example, both Android and iOS user-agent strings match the MOBILE category. WebSEAL uses the SUNDRY category if a user-agent string does not match any of the other defined patterns. INTERNET_EXPLORER = *msie* FIREFOX = *firefox* CHROME = *chrome* MOBILE = *android* MOBILE = *ios* SUNDRY = * [user-agent] stanzaUse the [user-agent] stanza to specify a category name for a particular user-agent string in the HTTP Request header. WebSEAL uses the user-agent string to categorize the incoming requests to make flow data statistics more meaningful.

user-agent

Use the user-agent stanza entry to configure the category name that WebSEAL uses for a particular user-agent string in the HTTP Request header when it categorizes the incoming requests.

Syntax

user-agent = pattern

Description

When WebSEAL records flow data statistics, it can use the user-agent string in the HTTP Request header to categorize the incoming requests. Categorizing requests based on the user-agent can make the statistical data more useful.

Use this stanza to specify a list of category names and patterns for the user-agent strings to match. You can repeat a category so that multiple patterns match a single category. The patterns are evaluated in the order of their definition. WebSEAL selects the first match to categorize each request.

Note: The stanza must always end with an entry that contains the match-all pattern *.

Options

pattern

The appliance uses this pattern to categorize the incoming requests. The appliance categorizes each request by matching the user-agent string value in the HTTP Request header with the defined pattern list.

Note: The pattern can contain the wildcard characters * and ?. The patterns are not case-sensitive.

Usage

This stanza entry is optional.

Default value

None.

Example

In this example, both Android and iOS user-agent strings match the MOBILE category. WebSEAL uses the SUNDRY category if a user-agent string does not match any of the other defined patterns.

INTERNET_EXPLORER = *msie*
FIREFOX = *firefox*
CHROME = *chrome*
MOBILE = *android*
MOBILE = *ios*
SUNDRY = *

Parent topic: [user-agent] stanza

[user-attribute-definitions] stanza[user-attribute-definitions] stanzaWebSEAL [user-attribute-definitions] stanzaUse this stanza to modify the data type, the category, or both of a custom attribute. This stanza applies only to the IBM Security Access Manager for Mobile product. Stanza referenceattr_IDSpecify attr_ID entries to modify the data type, the category, or both of a custom attribute.

[user-attribute-definitions] stanza

Use this stanza to modify the data type, the category, or both of a custom attribute.

Note: This stanza applies only to the IBM Security Access Manager for Mobile product.

attr_ID
Specify attr_ID entries to modify the data type, the category, or both of a custom attribute.

Parent topic: Stanza reference

attr_IDattr_IDattr_IDSpecify attr_ID entries to modify the data type, the category, or both of a custom attribute. attr_ID stanza entrydata typeattr_ID stanza entrycategoryuser-attribute-definitions stanzaattr_ID stanza entrydata typeuser-attribute-definitions stanzacategoryuser-attribute-definitions stanzaattributesdata typeattributescategorycustom attributesmodify categorycustom attributesmodify data type Syntax attr_ID.datatype = data_type attr_ID.category = category_name Description Use the appropriate stanza entry syntax depending on if you want to set the data type or category of a custom attribute from the default values. Options attr_IDSpecify the attribute identifier for which you want to set the data type or category. The attribute ID must match the name that exists in the [azn-decision-info] stanza entry.datatype data_typeSet the data type of an attribute from the default of string to a specified data_type. Your choices are: stringbooleanintegerdoubletimedatex500nameRequired date and time formatsA list of the data types, the format of each, and examples.Data typeFormatExampleDateDate: yyyy-mm-dd2014-06-10Date with timezone: yyyy-mm-dd{+|-}hh:mm2014-06-10+05:00TimeTime: hh:mm:ss13:00:01Time with timezone: hh:mm:ss{+|-}hh:mm01:34:22-06:00category category_nameSet the category of an attribute from the default of Environment to a specified category_name. Your choices are:EnvironmentSubjectActionResource Usage This stanza entry is not required. The [user-attribute-definitions] stanza and the attr_ID entries apply only to Advanced Access Control. Default value The default value for data type is string. The default value for category is Environment. Example: Updating the data type for JSON data If you defined a custom attribute in the [azn-decision-info] stanza as: urn:example:company:txn:value = post-data:/"accountBalances"/"savings" Then, you can set the data type of urn:example:company:txn:value to double by using the following stanza and entry: [user-attribute-definitions] urn:example:company:txn:value.datatype = double Example: Updating the category for form data If you defined a custom attribute in the [azn-decision-info] stanza as: urn:example:company:txn:userid = post-data:userid Then, you can set the category of urn:example:company:txn:userid to Subject by using the following stanza and entry: [user-attribute-definitions] urn:example:company:txn:userid.category = Subject [user-attribute-definitions] stanzaUse this stanza to modify the data type, the category, or both of a custom attribute.

attr_ID

Specify attr_ID entries to modify the data type, the category, or both of a custom attribute.

Syntax

attr_ID.datatype = data_type
attr_ID.category = category_name

Description

Use the appropriate stanza entry syntax depending on if you want to set the data type or category of a custom attribute from the default values.

Options

attr_ID

Specify the attribute identifier for which you want to set the data type or category. The attribute ID must match the name that exists in the [azn-decision-info] stanza entry.

datatype data_type

Set the data type of an attribute from the default of string to a specified data_type. Your choices are:

string

boolean

integer

double

time

date

x500name

Table 316. Required date and time formats.

Data type | Format | Example
Date | Date: yyyy-mm-dd | 2014-06-10
Date with timezone: yyyy-mm-dd{+|-}hh:mm | 2014-06-10+05:00
Time | Time: hh:mm:ss | 13:00:01
Time with timezone: hh:mm:ss{+|-}hh:mm | 01:34:22-06:00

category category_name

Set the category of an attribute from the default of Environment to a specified category_name. Your choices are:

Environment

Subject

Action

Resource

Usage

This stanza entry is not required.

The [user-attribute-definitions] stanza and the attr_ID entries apply only to Advanced Access Control.

Default value

The default value for data type is string.

The default value for category is Environment.

Example: Updating the data type for JSON data

If you defined a custom attribute in the [azn-decision-info] stanza as:

urn:example:company:txn:value = post-data:/"accountBalances"/"savings"

Then, you can set the data type of urn:example:company:txn:value to double by using the following stanza and entry:

[user-attribute-definitions]
urn:example:company:txn:value.datatype = double

Example: Updating the category for form data

If you defined a custom attribute in the [azn-decision-info] stanza as:

urn:example:company:txn:userid = post-data:userid

Then, you can set the category of urn:example:company:txn:userid to Subject by using the following stanza and entry:

[user-attribute-definitions]
urn:example:company:txn:userid.category = Subject

Parent topic: [user-attribute-definitions] stanza

[user-map-authn] stanza[user-map-authn] stanza[user-map-authn] stanzaUse the [user-map-authn] stanza to define authenticated user mapping settings.user-map-authn stanzastanzasuser-map-authnStanza referencerules-fileUse the rules-file stanza entry to define the name of the rules file to be used by the authenticated user mapping module.debug-levelUse the debug-level stanza entry to define the initial tracing level of the user mapping module.

[user-map-authn] stanza

Use the [user-map-authn] stanza to define authenticated user mapping settings.

rules-file
Use the rules-file stanza entry to define the name of the rules file to be used by the authenticated user mapping module.

debug-level
Use the debug-level stanza entry to define the initial tracing level of the user mapping module.

Parent topic: Stanza reference

rules-filerules-filerules-file stanza entryUse the rules-file stanza entry to define the name of the rules file to be used by the authenticated user mapping module.rules-file stanza entryuser-map-authn stanzaentriesrules-fileuser-map-authn stanzauser-map-authn stanzarules-file entrySyntax rules-file = file-name DescriptionThe name of the rules file that is used by the authenticated user mapping module. Options file-nameName of the rules file. Usage This stanza entry is required. Default valueNone. Example rules-file = auth-rules.txt [user-map-authn] stanzaUse the [user-map-authn] stanza to define authenticated user mapping settings.

rules-file

Use the rules-file stanza entry to define the name of the rules file to be used by the authenticated user mapping module.

Syntax

rules-file = file-name

Description

The name of the rules file that is used by the authenticated user mapping module.

Options

file-name

Name of the rules file.

Usage

This stanza entry is required.

Default value

None.

Example

rules-file = auth-rules.txt

Parent topic: [user-map-authn] stanza

debug-leveldebug-leveldebug-level stanza entryUse the debug-level stanza entry to define the initial tracing level of the user mapping module.debug-level stanza entryuser-map-authn stanzaentriesdebug-leveluser-map-authn stanzauser-map-authn stanzadebug-level entrySyntax debug-level = level DescriptionControls the initial trace level for the user mapping module. Options levelThe level variable that indicates the trace level of the user mapping module, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing.You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.usermap. This trace component is only available after the first HTTP request is processed Usage This stanza entry is optional. Default value0A debug level of 0 results in no tracing output. Exampledebug-level = 0 [user-map-authn] stanzaUse the [user-map-authn] stanza to define authenticated user mapping settings.

debug-level

Use the debug-level stanza entry to define the initial tracing level of the user mapping module.

Syntax

debug-level = level

Description

Controls the initial trace level for the user mapping module.

Options

level

The level variable that indicates the trace level of the user mapping module, with 1 designating a minimal amount of tracing and 9 designating the maximum amount of tracing.

Note: You can also use the Security Access Manager pdadmin trace commands to modify the trace level by using the trace component name of pd.cas.usermap. This trace component is only available after the first HTTP request is processed

Usage

This stanza entry is optional.

Default value

0

Note: A debug level of 0 results in no tracing output.

Example

debug-level = 0

Parent topic: [user-map-authn] stanza

[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.WebSocket is a standard that provides two-way asynchronous data transfer over a TCP or TLS connection.Stanza referencemax-worker-threadsUse the max-worker-threads entry to define the maximum number of threads that are used to proxy WebSocket connections through WebSEAL.idle-worker-threadsUse the idle-worker-threads entry to define the number of worker threads that can be left running idle.jct-read-inactive-timeoutUse the jct-read-inactive-timeout entry to define the number of seconds to wait for data from the junctioned WebSocket server before the connection is closed.clt-read-inactive-timeoutUse the clt-read-inactive-timeout entry to define the number of seconds to wait for data from the WebSocket client before the connection is closed.jct-write-blocked-timeoutUse the jct-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server before the connection is closed.clt-write-blocked-timeoutUse the clt-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client before the connection is closed.

[websocket] stanza

Use the [websocket] stanza to define settings for WebsSocket support.

WebSocket is a standard that provides two-way asynchronous data transfer over a TCP or TLS connection.

max-worker-threads
Use the max-worker-threads entry to define the maximum number of threads that are used to proxy WebSocket connections through WebSEAL.

idle-worker-threads
Use the idle-worker-threads entry to define the number of worker threads that can be left running idle.

jct-read-inactive-timeout
Use the jct-read-inactive-timeout entry to define the number of seconds to wait for data from the junctioned WebSocket server before the connection is closed.

clt-read-inactive-timeout
Use the clt-read-inactive-timeout entry to define the number of seconds to wait for data from the WebSocket client before the connection is closed.

jct-write-blocked-timeout
Use the jct-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server before the connection is closed.

clt-write-blocked-timeout
Use the clt-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client before the connection is closed.

Parent topic: Stanza reference

max-worker-threadsUse the max-worker-threads entry to define the maximum number of threads that are used to proxy WebSocket connections through WebSEAL.Syntax max-worker-threads = numberDescription A value of zero blocks WebSockets from being proxied. Each WebSocket requires two worker threads. If the number of worker threads in use is more than the value of max-worker-threads, WebSEAL immediately closes the WebSocket even if the WebSocket upgrade request to the junction succeeds. These threads operate independently from the [server] worker-threads.Options numberThe maximum number of threads that can be used to proxy WebSocket connections through WebSEAL.Usage This stanza entry is required.Default value 0Example max-worker-threads = 0[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.

max-worker-threads

Use the max-worker-threads entry to define the maximum number of threads that are used to proxy WebSocket connections through WebSEAL.

Syntax

max-worker-threads = number

Description

A value of zero blocks WebSockets from being proxied. Each WebSocket requires two worker threads. If the number of worker threads in use is more than the value of max-worker-threads, WebSEAL immediately closes the WebSocket even if the WebSocket upgrade request to the junction succeeds. These threads operate independently from the [server] worker-threads.

Options

number

The maximum number of threads that can be used to proxy WebSocket connections through WebSEAL.

Usage

This stanza entry is required.

Default value

0

Example

max-worker-threads = 0

Parent topic: [websocket] stanza

idle-worker-threadsUse the idle-worker-threads entry to define the number of worker threads that can be left running idle.Syntax idle-worker-threads = numberDescription To avoid spending extra resource and time on starting and stopping WebSocket worker threads, the threads can be left running idle. Although keeping them alive and idle when not in use consumes memory resources, it saves CPU and thread start-up time when the threads are required.Options numberThe number of threads that can be left running idle.Usage This stanza entry is required.Default value 0Example idle-worker-threads = 0[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.

idle-worker-threads

Use the idle-worker-threads entry to define the number of worker threads that can be left running idle.

Syntax

idle-worker-threads = number

Description

To avoid spending extra resource and time on starting and stopping WebSocket worker threads, the threads can be left running idle. Although keeping them alive and idle when not in use consumes memory resources, it saves CPU and thread start-up time when the threads are required.

Options

number

The number of threads that can be left running idle.

Usage

This stanza entry is required.

Default value

0

Example

idle-worker-threads = 0

Parent topic: [websocket] stanza

jct-read-inactive-timeoutUse the jct-read-inactive-timeout entry to define the number of seconds to wait for data from the junctioned WebSocket server before the connection is closed.Syntax jct-read-inactive-timeout = secondsDescription The jct-read-inactive-timeout entry defines the number of seconds to wait for data from the junctioned WebSocket server. If the timeout is reached, then the WebSocket connection is closed. An inactive timeout occurs when the WebSocket application or browser attempts to read data from the socket, but none becomes available within the timeout period because the other end has not written any data to the socket. In other words, an inactive timeout is a read data operation timeout. This situation might occur because the writing end is hung or the underlying TCP/IP connection was ended without notification by a firewall. However, certain legitimate causes might also trigger the timeout. For example, during user interaction, the user takes a break before responding to the application, which might trigger this timeout. Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources. Options secondsThe number of seconds to wait for data from the junctioned WebSocket server before the WebSocket connection is closed.Usage This stanza entry is required.Default value 120Example jct-read-inactive-timeout = 120[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.

jct-read-inactive-timeout

Use the jct-read-inactive-timeout entry to define the number of seconds to wait for data from the junctioned WebSocket server before the connection is closed.

Syntax

jct-read-inactive-timeout = seconds

Description

The jct-read-inactive-timeout entry defines the number of seconds to wait for data from the junctioned WebSocket server. If the timeout is reached, then the WebSocket connection is closed.

An inactive timeout occurs when the WebSocket application or browser attempts to read data from the socket, but none becomes available within the timeout period because the other end has not written any data to the socket. In other words, an inactive timeout is a read data operation timeout. This situation might occur because the writing end is hung or the underlying TCP/IP connection was ended without notification by a firewall. However, certain legitimate causes might also trigger the timeout. For example, during user interaction, the user takes a break before responding to the application, which might trigger this timeout.

Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources.

Options

seconds

The number of seconds to wait for data from the junctioned WebSocket server before the WebSocket connection is closed.

Usage

This stanza entry is required.

Default value

120

Example

jct-read-inactive-timeout = 120

Parent topic: [websocket] stanza

clt-read-inactive-timeoutUse the clt-read-inactive-timeout entry to define the number of seconds to wait for data from the WebSocket client before the connection is closed.Syntax clt-read-inactive-timeout = secondsDescription The clt-read-inactive-timeout entry defines the number of seconds to wait for data from the WebSocket client or browser. If the timeout is reached, then the WebSocket connection is closed. An inactive timeout occurs when the WebSocket application or browser attempts to read data from the socket, but none becomes available within the timeout period because the other end has not written any data to the socket. In other words, an inactive timeout is a read data operation timeout. This situation might occur because the writing end is hung or the underlying TCP/IP connection was ended without notification by a firewall. However, certain legitimate causes might also trigger the timeout. For example, during user interaction, the user takes a break before responding to the application, which might trigger this timeout. Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources. Options secondsThe number of seconds to wait for data from the WebSocket client before the connection is closed.Usage This stanza entry is required.Default value 120Example clt-read-inactive-timeout = 120[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.

clt-read-inactive-timeout

Use the clt-read-inactive-timeout entry to define the number of seconds to wait for data from the WebSocket client before the connection is closed.

Syntax

clt-read-inactive-timeout = seconds

Description

The clt-read-inactive-timeout entry defines the number of seconds to wait for data from the WebSocket client or browser. If the timeout is reached, then the WebSocket connection is closed.

An inactive timeout occurs when the WebSocket application or browser attempts to read data from the socket, but none becomes available within the timeout period because the other end has not written any data to the socket. In other words, an inactive timeout is a read data operation timeout. This situation might occur because the writing end is hung or the underlying TCP/IP connection was ended without notification by a firewall. However, certain legitimate causes might also trigger the timeout. For example, during user interaction, the user takes a break before responding to the application, which might trigger this timeout.

Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources.

Options

seconds

The number of seconds to wait for data from the WebSocket client before the connection is closed.

Usage

This stanza entry is required.

Default value

120

Example

clt-read-inactive-timeout = 120

Parent topic: [websocket] stanza

jct-write-blocked-timeoutUse the jct-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server before the connection is closed.Syntax jct-write-blocked-timeout = secondsDescription The jct-write-blocked-timeout entry defines the number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server. If the timeout is reached, then the WebSocket connection is closed. A blocked timeout occurs when the WebSocket application or browser writes to a socket, but the socket has a full write data queue due to the other end not reading the data. In other words, a blocked timeout is a write data operation timeout. This situation might occur because the reading end is hung. However, certain legitimate causes might also trigger the timeout. For example, the effective data bandwidth of the connection to the remote end is smaller than the rate at which data is being generated. Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources. Options secondsThe number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server before the connection is closed.Usage This stanza entry is required.Default value 120Example jct-write-blocked-timeout = 120[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.

jct-write-blocked-timeout

Use the jct-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server before the connection is closed.

Syntax

jct-write-blocked-timeout = seconds

Description

The jct-write-blocked-timeout entry defines the number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server. If the timeout is reached, then the WebSocket connection is closed.

A blocked timeout occurs when the WebSocket application or browser writes to a socket, but the socket has a full write data queue due to the other end not reading the data. In other words, a blocked timeout is a write data operation timeout. This situation might occur because the reading end is hung. However, certain legitimate causes might also trigger the timeout. For example, the effective data bandwidth of the connection to the remote end is smaller than the rate at which data is being generated.

Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources.

Options

seconds

The number of seconds to wait while WebSEAL is blocked sending data to the junctioned WebSocket server before the connection is closed.

Usage

This stanza entry is required.

Default value

120

Example

jct-write-blocked-timeout = 120

Parent topic: [websocket] stanza

clt-write-blocked-timeoutUse the clt-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client before the connection is closed.Syntax clt-write-blocked-timeout = secondsDescription The clt-write-blocked-timeout entry defines the number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client or browser. If the timeout is reached, then the WebSocket connection is closed. A blocked timeout occurs when the WebSocket application or browser writes to a socket, but the socket has a full write data queue due to the other end not reading the data. In other words, a blocked timeout is a write data operation timeout. This situation might occur because the reading end is hung. However, certain legitimate causes might also trigger the timeout. For example, the effective data bandwidth of the connection to the remote end is smaller than the rate at which data is being generated. Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources. Options secondsThe number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client or browser before the connection is closed.Usage This stanza entry is required.Default value 120Example clt-write-blocked-timeout = 120[websocket] stanzaUse the [websocket] stanza to define settings for WebsSocket support.

clt-write-blocked-timeout

Use the clt-write-blocked-timeout entry to define the number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client before the connection is closed.

Syntax

clt-write-blocked-timeout = seconds

Description

The clt-write-blocked-timeout entry defines the number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client or browser. If the timeout is reached, then the WebSocket connection is closed.

A blocked timeout occurs when the WebSocket application or browser writes to a socket, but the socket has a full write data queue due to the other end not reading the data. In other words, a blocked timeout is a write data operation timeout. This situation might occur because the reading end is hung. However, certain legitimate causes might also trigger the timeout. For example, the effective data bandwidth of the connection to the remote end is smaller than the rate at which data is being generated.

Set this timeout value to be higher than any timeout that each WebSocket application might employ, allowing the WebSocket client and server components to deal with timeouts themselves. This option is useful in setting an upper limit to help ensure that malicious attacks or unexpected errors cannot permanently consume all the WebSEAL WebSockets resources.

Options

seconds

The number of seconds to wait while WebSEAL is blocked sending data to the WebSocket client or browser before the connection is closed.

Usage

This stanza entry is required.

Default value

120

Example

clt-write-blocked-timeout = 120

Parent topic: [websocket] stanza

Appendix: Supported GSKit attributesYou can configure the these GSKit attributes with Security Access Manager.Strings GSK_HTTP_PROXY_SERVER_NAMESets the http proxy server for http CDP CRL retrieval if required. The numeric identifier is 225.GSK_SSL_EXTN_SERVERNAME_REQUESTSets the server name to be requested. The numeric identifier is 230.GSK_SSL_EXTN_SERVERNAME_CRITICAL_REQUESTSets the server name to be requested. This request must be satisfied. If this request is not satisfied, an error is returned. The numeric identifier is 231.Enums GSK_ALLOW_UNAUTHENTICATED_RESUMEThe numeric identifier is 423. One of the following ENUM values must be specified (The default is GSK_ALLOW_UNAUTHENTICATED_RESUME_OFF):GSK_ALLOW_UNAUTHENTICATED_RESUME_ONIndicates that a session resume can be completed successfully even if the client has not provided a certificate during the initial handshake when the server is configured for client authentication. The numeric identifier is 588.GSK_ALLOW_UNAUTHENTICATED_RESUME_OFFIndicates that a session resume cannot be completed successfully when a client has not provided a certificate during the initial handshake when the server is configured for client authentication. This will cause the connection to complete an entire SSL handshake. This will ensure that server has the opportunity to authenticate the client. The numeric identifier is 589.This ENUM_ID may only be set prior to gsk_environment_init().GSK_SSL_SUITEB_MODE_PROCESSINGThe numeric identifier is 454. One of the following ENUM values must be specified (The default is GSK_FALSE):GSK_TRUESSL Suite B mode is set. The setting will restrict SSL session negotiation to only use TLS Suite B Profile; RFC 5430, approved mode of operation which restricts Cipher Suites, Certificates and Signature and Hash Algorithms. The numeric identifier is 1.This setting enables both 128 bit and 192 bit Security levels of Suite B. Do not make other settings related to CipherSuites, Protocol and Signature and Hash Algorithms once this setting has been made.GSK_FALSESSL Suite B mode is not enabled. The numeric identifier is 0.GSK_SSL_SUITEB_128BIT_MODE_PROCESSINGThe numeric identifier is 455. One of the following ENUM values must be specified (The default is GSK_FALSE):GSK_TRUESSL Suite B 128 bit Security mode is set. The setting will restrict SSL session negotiation to only use TLS Suite B Profile; RFC 5430, approved mode of operation which restricts Cipher Suites, Certificates and Signature and Hash Algorithms. The numeric identifier is 1.This setting enables only 128 bit Security level of Suite B. Do not make other settings related to CipherSuites, Protocol and Signature and Hash Algorithms once this setting has been made.GSK_FALSESSL Suite B mode is not enabled. The numeric identifier is 0.This ENUM may only be set prior to gsk_environment_init(). FIPS-140 certified cryptographic modules should also be configured if using this setting. This setting will enable the TLS12 Protocol and disable all others.GSK_SSL_SUITEB_192BIT_MODE_PROCESSINGThe numeric identifier is 456. One of the following ENUM values must be specified (The default is GSK_FALSE):GSK_TRUESSL Suite B 192 bit Security mode is set. The setting will restrict SSL session negotiation to only use TLS Suite B Profile; RFC 5430, approved mode of operation which restricts Cipher Suites, Certificates and Signature and Hash Algorithms. The numeric identifier is 1.This setting enables only 192 bit Security level of Suite B. Do not make other settings related to CipherSuites, Protocol and Signature and Hash Algorithms once this setting has been made.GSK_FALSESSL Suite B mode is not enabled. The numeric identifier is 0.GSK_LDAP_REQUIRED_AT_INITSpecify the requirements of an LDAP server at environment initialization. The numeric identifier is 412. One of the following ENUM values must be specified (The default is GSK_INIT_CRL_LDAP_REQUIRED_OFF) :GSK_INIT_CRL_LDAP_REQUIRED_ONOperational LDAP server (CRL database) is required during environment initialization. The numeric identifier is 538.GSK_INIT_CRL_LDAP_REQUIRED_OFFAvailability of an active LDAP server (CRL database) is not required during environment initialization. The numeric identifier is 539.GSK_CC_MODE_CONTROLThis group controls the Common Criteria Mode operational requirements. The numeric identifier is 418. One of the following ENUM_VALUE values must be specified (The defaults is OFF for each of these):GSK_CC_MODE_DISABLE_STASH_FILE_ONDisable the use of stash files to open keystores. The numeric identifier is 555.GSK_CC_MODE_DISABLE_STASH_FILE_OFFAllow the use of stash files to open keystores. The numeric identifier is 556.This ENUM may only be set prior to gsk_environment_init(). gsk_environment_init() will fail if the use of stash files have been disallowed but no keystore password has been given. It cannot be set using an environment variable.GSK_CC_MODE_FIPS_ONFIPS mode is set. The numeric value is 557. The enumerated value for GSK_BASE_CRYPTO_LIBRARY must not be GSK_BASE_CRYPTO_RSA (the default is GSK_BASE_CRYPTO_ICC) or an error is returned. This enum has the same effect as setting all of GSK_FIPS_MODE_PROCESSING_ON, GSK_SSL_FIPS_MODE_PROCESSING_ON, GSK_ICC_FIPS_MODE_PROCESSING_ON. Additionally setting this enum will have a similar effect to setting GSK_NIST_DES_FIPS_DEPRECATION except that the deprecation of DES will happen immediately and not wait until May 18 2007.GSK_CC_MODE_FIPS_OFFFIPS mode is not enabled. The numeric identifier is 558. This enum has the same effect as GSK_FIPS_MODE_PROCESSING_OFF. This ENUM may only be set prior to gsk_environment_init(). gsk_environment_init() will fail if FIPS mode is not supported on the platform. It cannot be set using an environment variable.GSK_CC_MODE_ENFORCE_STRONG_PWD_ONEnforce the use of Common Criteria strength passwords for keystore operations. The numeric identifier is 559.GSK_CC_MODE_ENFORCE_STRONG_PWD_OFFRemove the enforcement of the use of Common Criteria strength passwords for keystore operations. The numeric identifier is 560.This ENUM may only be set prior to gsk_environment_init(). gsk_environment_init() will fail if the given password does not meet the strength rules. It cannot be set using an environment variable.GSK_CC_MODE_DISABLE_PKCS11_ONDisable the use of pkcs#11 devices. The numeric identifier is 561.GSK_CC_MODE_DISABLE_PKCS11_OFFAllow the use of pkcs#11 devices. The numeric identifier is 562.This ENUM may only be set prior to gsk_environment_init(). It cannot be set using an environment variable.GSK_CC_MODE_ENFORCE_STRONG_KDB_ONEnforce that only newer version cms keystores that have stronger tamper protection be used. The numeric identifier is 563.GSK_CC_MODE_ENFORCE_STRONG_KDB_OFFRemove the enforcement that only newer version cms keystores that have stronger tamper protection be used. The numeric identifier is 564.GSK_CC_MODE_STRICT_BASIC_CONST_ONEnforce the rule that non end entity certificates that are missing the Basic Constraints extension are not permitted to be used in a validation chain. The numeric identifier is 565.GSK_CC_MODE_STRICT_BASIC_CONST_OFFAllow non end entity certificates that are missing the Basic Constraints extension to be permitted to be used in a validation chain. The numeric identifier is 566.GSK_CC_MODE_ENFORCE_RIP_ONEnsure that GSKit clears residual information for a session when that session encounters ssl errors. The numeric identifier is 567.GSK_CC_MODE_ENFORCE_RIP_OFFDo not enforce that GSKit clears residual information for a session when that session encounters ssl errors. The numeric identifier is 568.GSK_NIST_DES_FIPS_DEPRECATIONOn May 19 2007 NIST have determined that DES will no longer be a FIPS certified cipher. Turning this flag on will cause DES to be removed from the cipher list in FIPS mode after this date. The numeric identifier is 433.GSK_TRUETurn DES deprecation on after May 18 2007. The numeric identifier is 1.GSK_FALSEDo not remove DES from the FIPS cipher list after May 18 2007. The numeric identifier is 0.GSK_BINARY_DN_MATCHING_ENABLEAllows for faster operation by comparing DN names using Binary DER Encoding The default is off (Disabled). The numeric identifier is 441.GSK_TRUETurn Binary Matching On (Not recommended). The numeric identifier is 1.GSK_FALSETurn Binary Matching Off. The numeric identifier is 0.GSK_PROTOCOL_SSLV2Enables or disables the SSL V2 protocol. Note that in FIPs mode of operation (see GSK_FIPS_MODE_PROCESSING) this setting will have no effect. The numeric identifier is 403. ENUM_VALUE must specify one of the following operations (The default is GSK_PROTOCOL_SSLV2_ON):GSK_PROTOCOL_SSLV2_ONEnable SSL V2GSK_PROTOCOL_SSLV2_OFFDisable SSL V2GSK_PROTOCOL_SSLV3Enables or disables the SSL V3 protocol. The numeric identifier is 404. ENUM_VALUE must specify one of the following operations (The default is GSK_PROTOCOL_SSLV3_ON):GSK_PROTOCOL_SSLV3_ONEnable SSL V3GSK_PROTOCOL_SSLV3_OFFDisable SSL V3GSK_PROTOCOL_TLSV10Enables or disables the TLSV10 protocol. The numeric identifier is 436. ENUM_VALUE must specify one of the following operations (The default is on):GSK_TRUEEnable TLSV10GSK_FALSEDisable TLSV10GSK_PROTOCOL_TLSV11Enables or disables the TLSV11 protocol. The numeric identifier is 437. ENUM_VALUE must specify one of the following operations (The default is on):GSK_TRUEEnable TLSV11GSK_FALSEDisable TLSV11GSK_PROTOCOL_TLSV12Enables or disables the TLSV12 protocol. The numeric identifier is 438. ENUM_VALUE must specify one of the following operations (The default is on):GSK_TRUEEnable TLSV12GSK_FALSEDisable TLSV12GSK_V2_CIPHER_SPECSIf multiple connections occur under a SSL session the values set for this field may not be used. The cipher specification negotiated during the first SSL connection of a session will be used until that session expires. Here is the list of available cipher specs. The list contains the string values that can be used with the buf_value for this buffer ID. Any combination of these may be used; none may be used twice.1-RC4 US 2-RC4 Export 3-RC2 US 4-RC2 Export 6-DES 56-Bit 7-Triple DES USIf a NULL string ("") is specified for the cipherspec list, SSL version 2 protocols will not be used.The default cipherspec is "713642". The numeric identifier is 205.GSK_V3_CIPHER_SPECS_EX, GSK_TLSV10_CIPHER_SPECS_EX, GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV12_CIPHER_SPECS_EXAllows the user to specify Cipher Specs for TLS protocol versions. The numeric identifiers are 240, 241, 242, and 243. Different TLS Protocols may have mutually exclusive Cipher Spec.The buffer cotains a list of comma delimted string values that are defined by RFC 2246, 4346, 5246, 4492, 5289.Example : Setting AES TLS Ciphersuite would require a buffer comtaining « TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA”Numbers GSK_LDAP_FAILOVER_RECONNECTION_PERIODIf multiple LDAP servers are specified for the failover function and the first LDAP server on the list is not available, the next one on the list will be queried until one is available or all the LDAP servers are tried. Periodically, an attempt will be made to retry the LDAP server query process. This attribute specifies the time period before the query retry is to begin. The value of int_value must be in the range of 0 - 86400 seconds. Defaults: For a single LDAP server, 0 seconds.When multiple LDAP servers are specified, 300 seconds.The numeric identifier is 307.GSK_V2_SIDCACHE_SIZEThe number of entries in the SID (Session ID) cache used for SSLV2, range 0-2047 (default=256). The numeric identifier is 304.GSK_V3_SIDCACHE_SIZEThe number of entries in the SID (Session ID) cache used for SSLV3 and TLSV1, range 0-MAXINT (default=512). This setting does not impose an upper limit, however GSKit internally imposes a limit that may be reviewed over time. Currently the internal limit is 655360. Note: Very large cache sizes could have adverse impacts on process performance due to the large memory usage. The cache memory allocation is dynamic in that memory is not allocated for cache entries until they are required, thus the memory usage may in fact be far less than the maximum number of cache entries specified. It is suggested that application consider these aspects when setting the cache size. The numeric identifier is 305.GSK_OCSP_TIMEOUTSets the timeout in seconds that we will wait for a response from the server. The default is 30. The numeric identifier is 318.GSK_HTTP_CDP_MAX_RESPONSE_SIZESets the maximum size in bytes that GSKit will accept as a response from a HTTP Server when retrieving a CRL. This may help protect against a denial of service attack. The default is 204800 (200K). The numeric identifier is 316.GSK_HTTP_CDP_TIMEOUTSets the timeout in seconds that we will wait for a response from the server. The default is 30. The numeric identifier is 319.GSK_MAX_SSL_MESSAGE_SIZESets the maximum message size that can be received by GSKit. This setting is design to protect against certain Denial of Service attack where very lare message can be used to exhust memory on a system. The default is 128K bytes. The numeric identifier is 320.GSK_HTTP_PROXY_SERVER_PORTSets the http proxy server port for http CDP CRL retrieval if needed. The numeric identifier is 317.GSK_LDAP_SERVER_VERSIONSets the LDAP protocol version to be used. This should be set to 2 or 3. The numeric identifier is 314.GSK_V2_SESSION_TIMEOUTSSL V2 session time-out. int_value must be in the range 0-100 seconds (default=100). The numeric identifier is 301.GSK_V3_SESSION_TIMEOUTSSL V3 session time-out. int_value must be in the range 0-86400 seconds (default=86400, 24 hours). The numeric identifier is 302.Stanza reference

Appendix: Supported GSKit attributes

You can configure the these GSKit attributes with Security Access Manager.

Strings

GSK_HTTP_PROXY_SERVER_NAME

Sets the http proxy server for http CDP CRL retrieval if required. The numeric identifier is 225.

GSK_SSL_EXTN_SERVERNAME_REQUEST

Sets the server name to be requested. The numeric identifier is 230.

GSK_SSL_EXTN_SERVERNAME_CRITICAL_REQUEST

Sets the server name to be requested. This request must be satisfied. If this request is not satisfied, an error is returned. The numeric identifier is 231.

Enums

GSK_ALLOW_UNAUTHENTICATED_RESUME

The numeric identifier is 423. One of the following ENUM values must be specified (The default is GSK_ALLOW_UNAUTHENTICATED_RESUME_OFF):

GSK_ALLOW_UNAUTHENTICATED_RESUME_ON

Indicates that a session resume can be completed successfully even if the client has not provided a certificate during the initial handshake when the server is configured for client authentication. The numeric identifier is 588.

GSK_ALLOW_UNAUTHENTICATED_RESUME_OFF

Indicates that a session resume cannot be completed successfully when a client has not provided a certificate during the initial handshake when the server is configured for client authentication. This will cause the connection to complete an entire SSL handshake. This will ensure that server has the opportunity to authenticate the client. The numeric identifier is 589.

This ENUM_ID may only be set prior to gsk_environment_init().

GSK_SSL_SUITEB_MODE_PROCESSING

The numeric identifier is 454. One of the following ENUM values must be specified (The default is GSK_FALSE):

GSK_TRUE

SSL Suite B mode is set. The setting will restrict SSL session negotiation to only use TLS Suite B Profile; RFC 5430, approved mode of operation which restricts Cipher Suites, Certificates and Signature and Hash Algorithms. The numeric identifier is 1.

Note: This setting enables both 128 bit and 192 bit Security levels of Suite B. Do not make other settings related to CipherSuites, Protocol and Signature and Hash Algorithms once this setting has been made.

GSK_FALSE

SSL Suite B mode is not enabled. The numeric identifier is 0.

GSK_SSL_SUITEB_128BIT_MODE_PROCESSING

The numeric identifier is 455. One of the following ENUM values must be specified (The default is GSK_FALSE):

GSK_TRUE

SSL Suite B 128 bit Security mode is set. The setting will restrict SSL session negotiation to only use TLS Suite B Profile; RFC 5430, approved mode of operation which restricts Cipher Suites, Certificates and Signature and Hash Algorithms. The numeric identifier is 1.

Note: This setting enables only 128 bit Security level of Suite B. Do not make other settings related to CipherSuites, Protocol and Signature and Hash Algorithms once this setting has been made.

GSK_FALSE

SSL Suite B mode is not enabled. The numeric identifier is 0.

Note: This ENUM may only be set prior to gsk_environment_init(). FIPS-140 certified cryptographic modules should also be configured if using this setting. This setting will enable the TLS12 Protocol and disable all others.

GSK_SSL_SUITEB_192BIT_MODE_PROCESSING

The numeric identifier is 456. One of the following ENUM values must be specified (The default is GSK_FALSE):

GSK_TRUE

SSL Suite B 192 bit Security mode is set. The setting will restrict SSL session negotiation to only use TLS Suite B Profile; RFC 5430, approved mode of operation which restricts Cipher Suites, Certificates and Signature and Hash Algorithms. The numeric identifier is 1.

Note: This setting enables only 192 bit Security level of Suite B. Do not make other settings related to CipherSuites, Protocol and Signature and Hash Algorithms once this setting has been made.

GSK_FALSE

SSL Suite B mode is not enabled. The numeric identifier is 0.

GSK_LDAP_REQUIRED_AT_INIT

Specify the requirements of an LDAP server at environment initialization. The numeric identifier is 412. One of the following ENUM values must be specified (The default is GSK_INIT_CRL_LDAP_REQUIRED_OFF) :

GSK_INIT_CRL_LDAP_REQUIRED_ON

Operational LDAP server (CRL database) is required during environment initialization. The numeric identifier is 538.

GSK_INIT_CRL_LDAP_REQUIRED_OFF

Availability of an active LDAP server (CRL database) is not required during environment initialization. The numeric identifier is 539.

GSK_CC_MODE_CONTROL

This group controls the Common Criteria Mode operational requirements. The numeric identifier is 418. One of the following ENUM_VALUE values must be specified (The defaults is OFF for each of these):

GSK_CC_MODE_DISABLE_STASH_FILE_ON

Disable the use of stash files to open keystores. The numeric identifier is 555.

GSK_CC_MODE_DISABLE_STASH_FILE_OFF

Allow the use of stash files to open keystores. The numeric identifier is 556.

This ENUM may only be set prior to gsk_environment_init(). gsk_environment_init() will fail if the use of stash files have been disallowed but no keystore password has been given. It cannot be set using an environment variable.

GSK_CC_MODE_FIPS_ON

FIPS mode is set. The numeric value is 557. The enumerated value for GSK_BASE_CRYPTO_LIBRARY must not be GSK_BASE_CRYPTO_RSA (the default is GSK_BASE_CRYPTO_ICC) or an error is returned. This enum has the same effect as setting all of GSK_FIPS_MODE_PROCESSING_ON, GSK_SSL_FIPS_MODE_PROCESSING_ON, GSK_ICC_FIPS_MODE_PROCESSING_ON. Additionally setting this enum will have a similar effect to setting GSK_NIST_DES_FIPS_DEPRECATION except that the deprecation of DES will happen immediately and not wait until May 18 2007.

GSK_CC_MODE_FIPS_OFF

FIPS mode is not enabled. The numeric identifier is 558. This enum has the same effect as GSK_FIPS_MODE_PROCESSING_OFF. This ENUM may only be set prior to gsk_environment_init(). gsk_environment_init() will fail if FIPS mode is not supported on the platform. It cannot be set using an environment variable.

GSK_CC_MODE_ENFORCE_STRONG_PWD_ON

Enforce the use of Common Criteria strength passwords for keystore operations. The numeric identifier is 559.

GSK_CC_MODE_ENFORCE_STRONG_PWD_OFF

Remove the enforcement of the use of Common Criteria strength passwords for keystore operations. The numeric identifier is 560.

This ENUM may only be set prior to gsk_environment_init(). gsk_environment_init() will fail if the given password does not meet the strength rules. It cannot be set using an environment variable.

GSK_CC_MODE_DISABLE_PKCS11_ON

Disable the use of pkcs#11 devices. The numeric identifier is 561.

GSK_CC_MODE_DISABLE_PKCS11_OFF

Allow the use of pkcs#11 devices. The numeric identifier is 562.

This ENUM may only be set prior to gsk_environment_init(). It cannot be set using an environment variable.

GSK_CC_MODE_ENFORCE_STRONG_KDB_ON

Enforce that only newer version cms keystores that have stronger tamper protection be used. The numeric identifier is 563.

GSK_CC_MODE_ENFORCE_STRONG_KDB_OFF

Remove the enforcement that only newer version cms keystores that have stronger tamper protection be used. The numeric identifier is 564.

GSK_CC_MODE_STRICT_BASIC_CONST_ON

Enforce the rule that non end entity certificates that are missing the Basic Constraints extension are not permitted to be used in a validation chain. The numeric identifier is 565.

GSK_CC_MODE_STRICT_BASIC_CONST_OFF

Allow non end entity certificates that are missing the Basic Constraints extension to be permitted to be used in a validation chain. The numeric identifier is 566.

GSK_CC_MODE_ENFORCE_RIP_ON

Ensure that GSKit clears residual information for a session when that session encounters ssl errors. The numeric identifier is 567.

GSK_CC_MODE_ENFORCE_RIP_OFF

Do not enforce that GSKit clears residual information for a session when that session encounters ssl errors. The numeric identifier is 568.

GSK_NIST_DES_FIPS_DEPRECATION

On May 19 2007 NIST have determined that DES will no longer be a FIPS certified cipher. Turning this flag on will cause DES to be removed from the cipher list in FIPS mode after this date. The numeric identifier is 433.

GSK_TRUE

Turn DES deprecation on after May 18 2007. The numeric identifier is 1.

GSK_FALSE

Do not remove DES from the FIPS cipher list after May 18 2007. The numeric identifier is 0.

GSK_BINARY_DN_MATCHING_ENABLE

Allows for faster operation by comparing DN names using Binary DER Encoding The default is off (Disabled). The numeric identifier is 441.

GSK_TRUE

Turn Binary Matching On (Not recommended). The numeric identifier is 1.

GSK_FALSE

Turn Binary Matching Off. The numeric identifier is 0.

GSK_PROTOCOL_SSLV2

Enables or disables the SSL V2 protocol. Note that in FIPs mode of operation (see GSK_FIPS_MODE_PROCESSING) this setting will have no effect. The numeric identifier is 403. ENUM_VALUE must specify one of the following operations (The default is GSK_PROTOCOL_SSLV2_ON):

GSK_PROTOCOL_SSLV2_ON

Enable SSL V2

GSK_PROTOCOL_SSLV2_OFF

Disable SSL V2

GSK_PROTOCOL_SSLV3

Enables or disables the SSL V3 protocol. The numeric identifier is 404. ENUM_VALUE must specify one of the following operations (The default is GSK_PROTOCOL_SSLV3_ON):

GSK_PROTOCOL_SSLV3_ON

Enable SSL V3

GSK_PROTOCOL_SSLV3_OFF

Disable SSL V3

GSK_PROTOCOL_TLSV10

Enables or disables the TLSV10 protocol. The numeric identifier is 436. ENUM_VALUE must specify one of the following operations (The default is on):

GSK_TRUE

Enable TLSV10

GSK_FALSE

Disable TLSV10

GSK_PROTOCOL_TLSV11

Enables or disables the TLSV11 protocol. The numeric identifier is 437. ENUM_VALUE must specify one of the following operations (The default is on):

GSK_TRUE

Enable TLSV11

GSK_FALSE

Disable TLSV11

GSK_PROTOCOL_TLSV12

Enables or disables the TLSV12 protocol. The numeric identifier is 438. ENUM_VALUE must specify one of the following operations (The default is on):

GSK_TRUE

Enable TLSV12

GSK_FALSE

Disable TLSV12

GSK_V2_CIPHER_SPECS

If multiple connections occur under a SSL session the values set for this field may not be used. The cipher specification negotiated during the first SSL connection of a session will be used until that session expires. Here is the list of available cipher specs. The list contains the string values that can be used with the buf_value for this buffer ID. Any combination of these may be used; none may be used twice.

1-RC4 US

2-RC4 Export

3-RC2 US

4-RC2 Export

6-DES 56-Bit

7-Triple DES US

If a NULL string ("") is specified for the cipherspec list, SSL version 2 protocols will not be used.

The default cipherspec is "713642". The numeric identifier is 205.

GSK_V3_CIPHER_SPECS_EX, GSK_TLSV10_CIPHER_SPECS_EX, GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV12_CIPHER_SPECS_EX

Allows the user to specify Cipher Specs for TLS protocol versions. The numeric identifiers are 240, 241, 242, and 243. Different TLS Protocols may have mutually exclusive Cipher Spec.

The buffer cotains a list of comma delimted string values that are defined by RFC 2246, 4346, 5246, 4492, 5289.

Example : Setting AES TLS Ciphersuite would require a buffer comtaining « TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA”

Numbers

GSK_LDAP_FAILOVER_RECONNECTION_PERIOD

If multiple LDAP servers are specified for the failover function and the first LDAP server on the list is not available, the next one on the list will be queried until one is available or all the LDAP servers are tried. Periodically, an attempt will be made to retry the LDAP server query process. This attribute specifies the time period before the query retry is to begin. The value of int_value must be in the range of 0 - 86400 seconds. Defaults:

For a single LDAP server, 0 seconds.

When multiple LDAP servers are specified, 300 seconds.

The numeric identifier is 307.

GSK_V2_SIDCACHE_SIZE

The number of entries in the SID (Session ID) cache used for SSLV2, range 0-2047 (default=256). The numeric identifier is 304.

GSK_V3_SIDCACHE_SIZE

The number of entries in the SID (Session ID) cache used for SSLV3 and TLSV1, range 0-MAXINT (default=512). This setting does not impose an upper limit, however GSKit internally imposes a limit that may be reviewed over time. Currently the internal limit is 655360. Note: Very large cache sizes could have adverse impacts on process performance due to the large memory usage. The cache memory allocation is dynamic in that memory is not allocated for cache entries until they are required, thus the memory usage may in fact be far less than the maximum number of cache entries specified. It is suggested that application consider these aspects when setting the cache size. The numeric identifier is 305.

GSK_OCSP_TIMEOUT

Sets the timeout in seconds that we will wait for a response from the server. The default is 30. The numeric identifier is 318.

GSK_HTTP_CDP_MAX_RESPONSE_SIZE

Sets the maximum size in bytes that GSKit will accept as a response from a HTTP Server when retrieving a CRL. This may help protect against a denial of service attack. The default is 204800 (200K). The numeric identifier is 316.

GSK_HTTP_CDP_TIMEOUT

Sets the timeout in seconds that we will wait for a response from the server. The default is 30. The numeric identifier is 319.

GSK_MAX_SSL_MESSAGE_SIZE

Sets the maximum message size that can be received by GSKit. This setting is design to protect against certain Denial of Service attack where very lare message can be used to exhust memory on a system. The default is 128K bytes. The numeric identifier is 320.

GSK_HTTP_PROXY_SERVER_PORT

Sets the http proxy server port for http CDP CRL retrieval if needed. The numeric identifier is 317.

GSK_LDAP_SERVER_VERSION

Sets the LDAP protocol version to be used. This should be set to 2 or 3. The numeric identifier is 314.

GSK_V2_SESSION_TIMEOUT

SSL V2 session time-out. int_value must be in the range 0-100 seconds (default=100). The numeric identifier is 301.

GSK_V3_SESSION_TIMEOUT

SSL V3 session time-out. int_value must be in the range 0-86400 seconds (default=86400, 24 hours). The numeric identifier is 302.

Parent topic: Stanza reference

Developing You can use APIs to develop applications and programs to work with IBM Security Access Manager.DevelopingREST API documentationAuthentication Service Framework for REST API clientsOptimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.Web administration Java classes API documentationUse the IBM Security Access Manager administration Java classes API to add administration tasks to new or existing Java applications.Web authorization Java classes API documentationUse the IBM Security Access Manager authorization Java classes API to add product authorization and security services to new or existing Java applications.Setting up an Access Manager Runtime for Java systemThe Access Manager Runtime for Java offers a reliable environment for developing and deploying Java applications in a Security Access Manager secure domain. Use it to add Security Access Manager authorization and security services to new or existing Java applications.Developing for Advanced Access Control You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.Developing for Federation You can use IBM Security Access Manager Federation Module APIs to develop applications and programs to manage federations and partners.

Developing

You can use APIs to develop applications and programs to work with IBM Security Access Manager.

REST API documentation

Authentication Service Framework for REST API clients
Optimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.

Web administration Java classes API documentation
Use the IBM Security Access Manager administration Java classes API to add administration tasks to new or existing Java applications.

Web authorization Java classes API documentation
Use the IBM Security Access Manager authorization Java classes API to add product authorization and security services to new or existing Java applications.

Setting up an Access Manager Runtime for Java system
The Access Manager Runtime for Java offers a reliable environment for developing and deploying Java™ applications in a Security Access Manager secure domain. Use it to add Security Access Manager authorization and security services to new or existing Java applications.

Developing for Advanced Access Control
You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.

Developing for Federation
You can use IBM Security Access Manager Federation Module APIs to develop applications and programs to manage federations and partners.

Authentication Service Framework for REST API clientsOptimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.The Authentication Service Framework within the Security Access Manager Advanced Access Module provides policy based strong and second factor authentication features and functions. The framework is exposed through two runtime endpoints. Browser endpoint "/mga/sps/authsvc"Configured by default and is optimized for traditional browser-based access and flows. This endpoint responds to clients with HTML and uses browser features such as 302 redirect.REST API endpoint "/mga/sps/apiauthsvc"Configured by default and is targeted to support non-browser REST API clients such as portals and native mobile applications. This endpoint responds to clients with JSON data.The Authentication Service supports direct invocation and Context Based Authorization (CBA) triggered invocation use cases. In the direct invocation case, a REST client issues an HTTP GET of the form "POST /mga/sps/apiauthsvc?PolicyId=<policy urn>", which initiates the authentication policy workflow. Single and multi mechanism policies can be invoked. The responses from this endpoint guide the client through the workflow policy steps. However, in most cases, the client is still required to track JSESSION and PD_* cookies.For the CBA triggered case, a REST client attempts to access a protected resource. This resource is protected by a CBA policy resource attachment. The policy includes an authentication obligation. When triggered, the CBA engine, supported by default configuration of WebSEAL/PEP, responds to the client with a 302 redirect URL of the form "GET /mga/sps/authsvc?TransactionId= <trx ID>". This endpoint is the browser endpoint and not the REST endpoint. The key issues and limitations that are associated with this use case include:Default configuration redirects to the browser-based /authsvc endpoint. Further this endpoint never responds with JSON formatted data.302 redirects place extra processing burden on REST client implementations.CBA requires a session.Developing You can use APIs to develop applications and programs to work with IBM Security Access Manager.Separate REST API channel accessIt is preferred to separate REST client access from traditional browser channel client access. The idea here is to enable separation of configuration options that might conflict with browser and REST API client access.Using request parameters as input to authentication mechanismsConsider using client supplied parameters as input to authentication mechanisms. This configuration helps to reduce the dependency on sessions and cookies to maintain state attributes that are frequently the source of mechanism input parameters such as the user name to be authenticated.OAuth Authentication and Reverse Proxy managed cookies to maintain session and stateWhile REST conventions do not exclude sessions and associated cookies for tracking state, their use and dependency should generally be minimized. Reverse proxy local redirects and /apiauthsvc obligations url mappings for context-based accessContext Based Access (CBA) policies provide dynamic, policy-based authorization to protected resources. Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Authentication Service Framework for REST API clients

Optimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.

The Authentication Service Framework within the Security Access Manager Advanced Access Module provides policy based strong and second factor authentication features and functions. The framework is exposed through two runtime endpoints.

Browser endpoint "/mga/sps/authsvc"

Configured by default and is optimized for traditional browser-based access and flows. This endpoint responds to clients with HTML and uses browser features such as 302 redirect.

REST API endpoint "/mga/sps/apiauthsvc"

Configured by default and is targeted to support non-browser REST API clients such as portals and native mobile applications. This endpoint responds to clients with JSON data.

The Authentication Service supports direct invocation and Context Based Authorization (CBA) triggered invocation use cases. In the direct invocation case, a REST client issues an HTTP GET of the form "POST /mga/sps/apiauthsvc?PolicyId=<policy urn>", which initiates the authentication policy workflow. Single and multi mechanism policies can be invoked. The responses from this endpoint guide the client through the workflow policy steps. However, in most cases, the client is still required to track JSESSION and PD_* cookies.

For the CBA triggered case, a REST client attempts to access a protected resource. This resource is protected by a CBA policy resource attachment. The policy includes an authentication obligation. When triggered, the CBA engine, supported by default configuration of WebSEAL/PEP, responds to the client with a 302 redirect URL of the form "GET /mga/sps/authsvc?TransactionId= <trx ID>". This endpoint is the browser endpoint and not the REST endpoint. The key issues and limitations that are associated with this use case include:

Default configuration redirects to the browser-based /authsvc endpoint. Further this endpoint never responds with JSON formatted data.

302 redirects place extra processing burden on REST client implementations.

CBA requires a session.

Separate REST API channel access
It is preferred to separate REST client access from traditional browser channel client access. The idea here is to enable separation of configuration options that might conflict with browser and REST API client access.

Using request parameters as input to authentication mechanisms
Consider using client supplied parameters as input to authentication mechanisms. This configuration helps to reduce the dependency on sessions and cookies to maintain state attributes that are frequently the source of mechanism input parameters such as the user name to be authenticated.

OAuth Authentication and Reverse Proxy managed cookies to maintain session and state
While REST conventions do not exclude sessions and associated cookies for tracking state, their use and dependency should generally be minimized.

Reverse proxy local redirects and /apiauthsvc obligations url mappings for context-based access
Context Based Access (CBA) policies provide dynamic, policy-based authorization to protected resources.

Example combining CBA, Authentication Service Framework, and OAuth
The onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Parent topic: Developing

Separate REST API channel accessIt is preferred to separate REST client access from traditional browser channel client access. The idea here is to enable separation of configuration options that might conflict with browser and REST API client access.If possible, expose a separate reverse proxy instance. Minimally, create a junction that is separate to the default /mga junction and enables access to the/apiauthsvc endpoint. Example junction settings are as follows:Junction Point Name: /mgaapi Stateful Junction: true/enabled Junction type: SSL Servers: The runtime host and port where Advanced Access Control run time is running. If the reverse proxy and AAC are colocated, then localhost:443 can be set. HTTP Basic Authentication Header: Filter HTTP Header Identity information: 'IVUSER', 'IVGROUPS', 'IVCREDS' HTTP Header Encoding: UTF8 URI Encoded Insert client IP address: true/enabledAccess control lists (ACLs) are configured when the isamcfg utility is run. All of these ACLs are prefixed with "isam_mobile". Unauthenticated access can be enabled for the /apiauthsvc endpoint by attaching the "isam_mobile_rest_unauth" ACL to the /WebSEAL/<instance name>/mgaapi/sps/apiauthsvc. If needed, this endpoint can be protected with the "isam_mobile_rest" authenticated ACL. In most cases, configure this endpoint to require authenticated access unless unauthenticated access is required. It depends on whether authentication policy is being triggered from an already authenticated or unauthenticated state.Authentication Service Framework for REST API clientsOptimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.

Separate REST API channel access

It is preferred to separate REST client access from traditional browser channel client access. The idea here is to enable separation of configuration options that might conflict with browser and REST API client access.

If possible, expose a separate reverse proxy instance. Minimally, create a junction that is separate to the default /mga junction and enables access to the/apiauthsvc endpoint. Example junction settings are as follows:

Junction Point Name: /mgaapi

Stateful Junction: true/enabled

Junction type: SSL

Servers: The runtime host and port where Advanced Access Control run time is running. If the reverse proxy and AAC are colocated, then localhost:443 can be set.

HTTP Basic Authentication Header: Filter

HTTP Header Identity information: 'IVUSER', 'IVGROUPS', 'IVCREDS'

HTTP Header Encoding: UTF8 URI Encoded

Insert client IP address: true/enabled

Access control lists (ACLs) are configured when the isamcfg utility is run. All of these ACLs are prefixed with "isam_mobile". Unauthenticated access can be enabled for the /apiauthsvc endpoint by attaching the "isam_mobile_rest_unauth" ACL to the /WebSEAL/<instance name>/mgaapi/sps/apiauthsvc. If needed, this endpoint can be protected with the "isam_mobile_rest" authenticated ACL. In most cases, configure this endpoint to require authenticated access unless unauthenticated access is required. It depends on whether authentication policy is being triggered from an already authenticated or unauthenticated state.

Parent topic: Authentication Service Framework for REST API clients

Using request parameters as input to authentication mechanismsConsider using client supplied parameters as input to authentication mechanisms. This configuration helps to reduce the dependency on sessions and cookies to maintain state attributes that are frequently the source of mechanism input parameters such as the user name to be authenticated.Most authentication mechanisms support a set of input parameters as part of their execution. The source of values for these parameters can be the internal Authentication Service Framework context, the inbound HTTP request, or the HTTP session. Most of the default policies that are supplied within the Authentication Services Framework use the internal context as the source of mechanism parameters. Except for the Username Password mechanism, the username to be "authenticated" is assumed to be available to mechanisms within an already authenticated context. This situation is suited to step up with second factor type use cases. It is possible for a requesting client to invoke authentication mechanisms and policies (for example, OTP) without a pre-established authenticated session. It is achieved by using an alternative input source for parameter values supported by most mechanisms.The following example illustrates how the requesting client can specify the "username" to validate their TOTP credential. A custom authentication policy is created which references the TOTP mechanism as its only step. The mechanism is configured to obtain its user name input parameter from a client request JSON data parameter.Create a custom authentication policy in the local management interface by going to Access ControlAuthenticationNew Authentication Policy (the plus icon). Set the policy Identifier value as "urn:ibm:security:authentication:asf:mytotp".Add the TOTP One Time Password mechanism as the only step on the policy.Click Parameters next to the mechanism to show the Modify Parameters dialog.Select the Pass checkbox on the username row.Select Request as the source.Enter myuid as the request name and urn:ibm:security:asf:request:parameters as its namespace.Click OK.Click Save.The policy is now available to service and respond to client requests. REST clients can specify "myuid" within their request JSON data to indicate which user is being authenticated for TOTP. Assume that the users have previously initialized their TOTP authenticator applications with their shared secret. A REST client can send requests similar to that shown as follows to initiate the new custom policy and TOTP mechanism. For more information about the Authentication Services REST API, see REST API documentation.An example request is shown as follows:curl -k -v -c cookies.txt -b cookies.txt -X POST -H "Content-Type:application/json" -H "Accept: application/json" --data "{'myuid':'testuser1'}" "https://<isam address> /mgaapi/sps/apiauthsvc?PolicyId=urn:ibm:security:authentication:asf:mytotp"An example response is shown as follows:{ "mechanism": "urn:ibm:security:authentication:asf:mechanism:totp", "message": "", "state": "9b5286e25a9340f989e3b77b24775602", "location": "/mga/sps/apiauthsvc?StateId=9b5286e25a9340f989e3b77b24775602", "execptionMsg": "NA" }Next, the REST client can verify the user's OTP by sending a request as shown in the following example, using the StateId parameter returned from the previous response:curl k v c cookies.txt b cookies.txt X PUT H "Content-Type: application/json" H "Accept: application/json" data "{'otp': '987352'}" "https://<isam address>/mgaapi/sps/apiauthsvc?StateId=9b5286e25a9340f989e3b77b24775602"A successfully verified TOTP is indicated to the client with an HTTP 204 response code.Authentication Service Framework for REST API clientsOptimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.

Using request parameters as input to authentication mechanisms

Consider using client supplied parameters as input to authentication mechanisms. This configuration helps to reduce the dependency on sessions and cookies to maintain state attributes that are frequently the source of mechanism input parameters such as the user name to be authenticated.

Most authentication mechanisms support a set of input parameters as part of their execution. The source of values for these parameters can be the internal Authentication Service Framework context, the inbound HTTP request, or the HTTP session. Most of the default policies that are supplied within the Authentication Services Framework use the internal context as the source of mechanism parameters. Except for the Username Password mechanism, the username to be "authenticated" is assumed to be available to mechanisms within an already authenticated context. This situation is suited to step up with second factor type use cases. It is possible for a requesting client to invoke authentication mechanisms and policies (for example, OTP) without a pre-established authenticated session. It is achieved by using an alternative input source for parameter values supported by most mechanisms.

The following example illustrates how the requesting client can specify the "username" to validate their TOTP credential. A custom authentication policy is created which references the TOTP mechanism as its only step. The mechanism is configured to obtain its user name input parameter from a client request JSON data parameter.

Create a custom authentication policy in the local management interface by going to Access Control > Authentication > New Authentication Policy (the plus icon). Set the policy Identifier value as "urn:ibm:security:authentication:asf:mytotp".

Add the TOTP One Time Password mechanism as the only step on the policy.

Click Parameters next to the mechanism to show the Modify Parameters dialog.

Select the Pass checkbox on the username row.

Select Request as the source.

Enter myuid as the request name and urn:ibm:security:asf:request:parameters as its namespace.

Click OK.

Click Save.

The policy is now available to service and respond to client requests. REST clients can specify "myuid" within their request JSON data to indicate which user is being authenticated for TOTP. Assume that the users have previously initialized their TOTP authenticator applications with their shared secret. A REST client can send requests similar to that shown as follows to initiate the new custom policy and TOTP mechanism. For more information about the Authentication Services REST API, see REST API documentation.

An example request is shown as follows:

curl -k -v -c cookies.txt -b cookies.txt -X POST -H "Content-Type:application/json"
-H "Accept: application/json" --data "{'myuid':'testuser1'}" "https://<isam address>
/mgaapi/sps/apiauthsvc?PolicyId=urn:ibm:security:authentication:asf:mytotp"

An example response is shown as follows:

{
"mechanism": "urn:ibm:security:authentication:asf:mechanism:totp",
"message": "",
"state": "9b5286e25a9340f989e3b77b24775602",
"location": "/mga/sps/apiauthsvc?StateId=9b5286e25a9340f989e3b77b24775602",
"execptionMsg": "NA"
}

Next, the REST client can verify the user's OTP by sending a request as shown in the following example, using the StateId parameter returned from the previous response:

curl k v c cookies.txt b cookies.txt X PUT H "Content-Type: application/json" H "Accept:
application/json" data "{'otp': '987352'}"
"https://<isam address>/mgaapi/sps/apiauthsvc?StateId=9b5286e25a9340f989e3b77b24775602"

A successfully verified TOTP is indicated to the client with an HTTP 204 response code.

Parent topic: Authentication Service Framework for REST API clients

OAuth Authentication and Reverse Proxy managed cookies to maintain session and stateWhile REST conventions do not exclude sessions and associated cookies for tracking state, their use and dependency should generally be minimized. However, the Authentication Service Framework is designed to support traditional browser client use cases in addition to REST API clients. The framework also integrates with Context Based Authorization (CBA) policy enforcement, which has some dependency on server-side state maintenance. This section discusses configuration-based options that remove the need for clients to maintain and track session cookies associated with the Authentication Service Framework.For general REST API use cases, OAuth usage has become standard for authorized access to API resources. The Security Access Manager appliance-based reverse proxy supports a configuration option named oauthauth. Its associated settings enable the reverse proxy point of contact to treat issued OAuth bearer tokens as a form of authentication. The reverse proxy can manage and reference authenticated sessions based on the presence on an OAuth access token within the "Authorization" header of a client request. This feature effectively obviates the need for clients to include PD* cookies that represent an authenticated session.The following reverse proxy configuration file options are suggested:easenabled = false oauthauth = https requirempa = no [session-http-headers] Authorization = httpsThe managed cookies list feature enables the reverse proxy to manage protected resource cookies on behalf of the client. As a result, cookies returned from a protected backend resource server are not seen by the requesting client. Instead, the reverse proxy manages and sends these cookies as needed on the client behalf. When OAuthAuth is combined with the reverse proxy managed cookies, the need for the client to maintain cookies is removed. The combined settings also result in a typical OAuth client design and implementation where a valid access token enables access to protected resources.The following reverse proxy configuration file options are suggested to support reverse proxy managed client sessions:[junction:/mgaapi] managedcookieslist = *JSESSIONID*,PD_*eas-enabledUse the eas-enabled stanza entry to specify whether OAuth external authorization service (EAS) is enabled.oauth-authUse the oauth-auth stanza entry to specify whether Open Authentication (OAuth) is enabled.require-mpaheader_namemanaged-cookies-listAuthentication Service Framework for REST API clientsOptimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.

OAuth Authentication and Reverse Proxy managed cookies to maintain session and state

While REST conventions do not exclude sessions and associated cookies for tracking state, their use and dependency should generally be minimized.

However, the Authentication Service Framework is designed to support traditional browser client use cases in addition to REST API clients. The framework also integrates with Context Based Authorization (CBA) policy enforcement, which has some dependency on server-side state maintenance. This section discusses configuration-based options that remove the need for clients to maintain and track session cookies associated with the Authentication Service Framework.

For general REST API use cases, OAuth usage has become standard for authorized access to API resources. The Security Access Manager appliance-based reverse proxy supports a configuration option named oauthauth. Its associated settings enable the reverse proxy point of contact to treat issued OAuth bearer tokens as a form of authentication. The reverse proxy can manage and reference authenticated sessions based on the presence on an OAuth access token within the "Authorization" header of a client request. This feature effectively obviates the need for clients to include PD* cookies that represent an authenticated session.

The following reverse proxy configuration file options are suggested:

easenabled = false
oauthauth = https
requirempa = no

[session-http-headers]
Authorization = https

The managed cookies list feature enables the reverse proxy to manage protected resource cookies on behalf of the client. As a result, cookies returned from a protected backend resource server are not seen by the requesting client. Instead, the reverse proxy manages and sends these cookies as needed on the client behalf. When OAuthAuth is combined with the reverse proxy managed cookies, the need for the client to maintain cookies is removed. The combined settings also result in a typical OAuth client design and implementation where a valid access token enables access to protected resources.

The following reverse proxy configuration file options are suggested to support reverse proxy managed client sessions:

[junction:/mgaapi]
managedcookieslist
= *JSESSIONID*,PD_*

Parent topic: Authentication Service Framework for REST API clients

Related reference:

eas-enabled

oauth-auth

require-mpa

header_name

managed-cookies-list

Reverse proxy local redirects and /apiauthsvc obligations url mappings for context-based accessContext Based Access (CBA) policies provide dynamic, policy-based authorization to protected resources. A component feature of CBA enables policy rules to permit access to a protected resource if a specified authentication condition exists. This feature is embodied by authentication obligations that integrate CBA with the Authentication Service Framework. The technical implementation of this feature depends on 302 redirects and cookies for tracking session and state. Previous topics discussed options for handling session and state while minimizing its impact for REST client access. This topic discusses extra settings to transparently handle 302 redirects and obligations triggers to optimize REST client access for CBA triggered authentication in the context of protected resource access.When a CBA policy rule triggers an authentication obligation, control is returned to the reverse proxy point of contact for obligation enforcement. The reverse proxy supports configuration file based options within its obligationsurlsmapping, which define how the reverse proxy enforces an obligation. The entries within this stanza effectively result in a 302 redirect to a matched URL, which technically performs the enforcement. There are two issues with this approach and its default configuration, which increase the complexity burden for REST clients:Default configuration of authentication obligations always redirect clients to "/mga/sps/authsvc". This endpoint is optimized for browser client access.302 redirects are difficult for REST API clients to handle.Fortunately, both of these issues can be overridden and controlled with reverse proxy configuration file settings. Assuming previous suggestions were adopted and implemented, obligation URL mappings define redirects to "/mgaapi/sps/apiauthsvc" rather than the default "/mga/sps/authsvc". This can be achieved with the following settings:[obligations-urls-mapping] urn:ibm:security:authentication:asf:* = /mgaapi/sps/apiauthsvcThe name, or left side, represents an authentication policy URI. The value, or right side, specifies the redirect target URL. Additionally, this redirection setting might be limited to a small subset of authentication policy URIs if wanted.The reverse proxy supports a feature known as local redirects. Configuration of this feature instructs the reverse proxy to automatically follow 302 responses received from junctioned servers on behalf of the client. The net effect is that the client does not receive the 302 redirect. The following settings enable this feature:[server] maximumfollowredirects = 4 followredirectsfor = GET /mgaapi/sps/apiauthsvc* followredirectsfor = PUT /mgaapi/sps/apiauthsvc* followredirectsfor = GET /<protected application junction point name> /<path to protected application resource>/*Authentication Service Framework for REST API clientsOptimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.

Reverse proxy local redirects and /apiauthsvc obligations url mappings for context-based access

Context Based Access (CBA) policies provide dynamic, policy-based authorization to protected resources.

A component feature of CBA enables policy rules to permit access to a protected resource if a specified authentication condition exists. This feature is embodied by authentication obligations that integrate CBA with the Authentication Service Framework. The technical implementation of this feature depends on 302 redirects and cookies for tracking session and state. Previous topics discussed options for handling session and state while minimizing its impact for REST client access. This topic discusses extra settings to transparently handle 302 redirects and obligations triggers to optimize REST client access for CBA triggered authentication in the context of protected resource access.

When a CBA policy rule triggers an authentication obligation, control is returned to the reverse proxy point of contact for obligation enforcement. The reverse proxy supports configuration file based options within its obligationsurlsmapping, which define how the reverse proxy enforces an obligation. The entries within this stanza effectively result in a 302 redirect to a matched URL, which technically performs the enforcement. There are two issues with this approach and its default configuration, which increase the complexity burden for REST clients:

Default configuration of authentication obligations always redirect clients to "/mga/sps/authsvc". This endpoint is optimized for browser client access.

302 redirects are difficult for REST API clients to handle.

Fortunately, both of these issues can be overridden and controlled with reverse proxy configuration file settings. Assuming previous suggestions were adopted and implemented, obligation URL mappings define redirects to "/mgaapi/sps/apiauthsvc" rather than the default "/mga/sps/authsvc". This can be achieved with the following settings:

[obligations-urls-mapping]
urn:ibm:security:authentication:asf:* = /mgaapi/sps/apiauthsvc

The name, or left side, represents an authentication policy URI. The value, or right side, specifies the redirect target URL. Additionally, this redirection setting might be limited to a small subset of authentication policy URIs if wanted.

The reverse proxy supports a feature known as local redirects. Configuration of this feature instructs the reverse proxy to automatically follow 302 responses received from junctioned servers on behalf of the client. The net effect is that the client does not receive the 302 redirect. The following settings enable this feature:

[server]
maximumfollowredirects = 4
followredirectsfor = GET /mgaapi/sps/apiauthsvc*
followredirectsfor = PUT /mgaapi/sps/apiauthsvc*
followredirectsfor = GET /<protected application junction point name>
/<path to protected application resource>/*

Parent topic: Authentication Service Framework for REST API clients

Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.The high-level tasks to enable this configuration are shown in the following list:Enable the onboard live demonstration application. Create a reverse proxy instance. Configure all integration options between the reverse proxy and Advanced Access Control by using "isam auto_config config". Create a /demo junction to the localhost runtime to enable access to the "/demo/mobile-demo/rba" resource URL. Create the /mgaapi junction. Customize reverse proxy instance configuration for REST API clients. Set "/mgaapi/sps/apiauthsvc" as an additional EAI authentication trigger. Attach ACLs to junctioned resource URLs. Create API Protection OAuth definitions and clients. Attach API Protection definition to /demo resource. Create a custom context-based access policy with an TOTP authentication obligation. Attach the context-based access policy to the "/demo/mobile-demo/rba" resource URL. Create a test user. Initialize TOTP shared secret for the test user. Use CURL to obtain an OAuth access token. Use CURL to access "/demo/mobile-demo/rba" with the access token.Authentication Service Framework for REST API clientsOptimize the Authentication Service Framework for REST API clients. The optimization uses low-level technical configuration options supported by the Web Reverse Proxy and Advanced Access Control.Enable the onboard live demonstration applicationsUse the demonstration application that is provided by the appliance to complete the settings in this example.Create a reverse proxy instanceThe reverse proxy is used as the point of contact for the demonstration application and Advanced Access Control.Configure all integration options between the reverse proxy and Advanced Access ControlUse the isam auto_config config command of the Security Access Manager configuration utility to configure these settings.Create a /demo junctionCreate a junction to enable access to the onboard demonstration application.Create a /mgaapi junctionCreate a junction to enable access to the Advanced Access Control authentication services framework for REST client access.Customize reverse proxy instance configurationCustomize reverse proxy instance configuration for REST API clients.Set extra EAI authentication triggerSet /mgaapi/sps/apiauthsvc as an extra EAI authentication trigger.Attach ACLs to junctioned resource URLsCreate API Protection OAuth definitions and clientsCreate API Protection OAuth definitions and clients. Then, attach them to the /demo junction.Create a custom context-based access policyCreate a custom context-based access policy with a TOTP authentication obligation.Attach the context-based access policyAttach the context-based access policy to the /demo/mobile-demo/rba resource URL.Create a test userInitialize TOTP shared secret for the test userAccess the following URL as testuser1.Use CURL to obtain an OAuth access tokenUse CURL to run the following OAuth ROPC command in a shell terminal to obtain an access token.Use CURL to access /demo/mobile-demo/rba with the access tokenUse CURL to run the following command in a shell terminal.

Example combining CBA, Authentication Service Framework, and OAuth

The onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

The high-level tasks to enable this configuration are shown in the following list:

Enable the onboard live demonstration application.

Create a reverse proxy instance.

Configure all integration options between the reverse proxy and Advanced Access Control by using "isam auto_config config".

Create a /demo junction to the localhost runtime to enable access to the "/demo/mobile-demo/rba" resource URL.

Create the /mgaapi junction.

Customize reverse proxy instance configuration for REST API clients.

Set "/mgaapi/sps/apiauthsvc" as an additional EAI authentication trigger.

Attach ACLs to junctioned resource URLs.

Create API Protection OAuth definitions and clients.

Attach API Protection definition to /demo resource.

Create a custom context-based access policy with an TOTP authentication obligation.

Attach the context-based access policy to the "/demo/mobile-demo/rba" resource URL.

Create a test user.

Initialize TOTP shared secret for the test user.

Use CURL to obtain an OAuth access token.

Use CURL to access "/demo/mobile-demo/rba" with the access token.

Enable the onboard live demonstration applications
Use the demonstration application that is provided by the appliance to complete the settings in this example.

Create a reverse proxy instance
The reverse proxy is used as the point of contact for the demonstration application and Advanced Access Control.

Configure all integration options between the reverse proxy and Advanced Access Control
Use the isam auto_config config command of the Security Access Manager configuration utility to configure these settings.

Create a /demo junction
Create a junction to enable access to the onboard demonstration application.

Create a /mgaapi junction
Create a junction to enable access to the Advanced Access Control authentication services framework for REST client access.

Customize reverse proxy instance configuration
Customize reverse proxy instance configuration for REST API clients.

Set extra EAI authentication trigger
Set /mgaapi/sps/apiauthsvc as an extra EAI authentication trigger.

Attach ACLs to junctioned resource URLs

Create API Protection OAuth definitions and clients
Create API Protection OAuth definitions and clients. Then, attach them to the /demo junction.

Create a custom context-based access policy
Create a custom context-based access policy with a TOTP authentication obligation.

Attach the context-based access policy
Attach the context-based access policy to the /demo/mobile-demo/rba resource URL.

Create a test user

Initialize TOTP shared secret for the test user
Access the following URL as testuser1.

Use CURL to obtain an OAuth access token
Use CURL to run the following OAuth ROPC command in a shell terminal to obtain an access token.

Use CURL to access /demo/mobile-demo/rba with the access token
Use CURL to run the following command in a shell terminal.

Parent topic: Authentication Service Framework for REST API clients

Enable the onboard live demonstration applicationsUse the demonstration application that is provided by the appliance to complete the settings in this example.In the local management interface, go to Secure Access ControlAdvanced Configuration.Set the live.demos.enabled value to true.Deploy and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Enable the onboard live demonstration applications

Use the demonstration application that is provided by the appliance to complete the settings in this example.

In the local management interface, go to Secure Access Control > Advanced Configuration.

Set the live.demos.enabled value to true.

Deploy and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Create a reverse proxy instanceThe reverse proxy is used as the point of contact for the demonstration application and Advanced Access Control.In the local management interface, go to Secure Web SettingsReverse Proxy.Create a reverse proxy instance named inst1.If possible, set its HTTP listening ports to 80 and HTTPS listening ports to 443.Deploy and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Create a reverse proxy instance

The reverse proxy is used as the point of contact for the demonstration application and Advanced Access Control.

In the local management interface, go to Secure Web Settings > Reverse Proxy.

Create a reverse proxy instance named inst1.

If possible, set its HTTP listening ports to 80 and HTTPS listening ports to 443.

Deploy and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Configure all integration options between the reverse proxy and Advanced Access ControlUse the isam auto_config config command of the Security Access Manager configuration utility to configure these settings.Log in to the appliance command-line interface as an administrator.Run the Security Access Manager configuration utility by using the command isam auto_config config.Enable all feature options.Configure connectivity between the reverse proxy inst1 and the Advanced Access Control Runtime, both of which are running on localhost.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Configure all integration options between the reverse proxy and Advanced Access Control

Use the isam auto_config config command of the Security Access Manager configuration utility to configure these settings.

Log in to the appliance command-line interface as an administrator.

Run the Security Access Manager configuration utility by using the command isam auto_config config.

Enable all feature options.

Configure connectivity between the reverse proxy inst1 and the Advanced Access Control Runtime, both of which are running on localhost.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Create a /demo junctionCreate a junction to enable access to the onboard demonstration application.In the local management interface, go to Secure Web SettingsReverse Proxy.Select inst1.Select ManageJunction Management.Create a standard junction /demo with the following options:Junction Point Name: /demoStateful Junction: true/enabled Junction type: SSL Servers: The runtime host and port where Advanced Access Control run time is running. If the reverse proxy and AAC are colocated, then localhost:443 can be set. HTTP Basic Authentication Header: Filter HTTP Header Identity Information: 'IVUSER', 'IVGROUPS', 'IVCREDS' HTTP Header Encoding: UTF8 URI Encoded Insert client IP address: true/enabledClick Save.Deploy and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Create a /demo junction

Create a junction to enable access to the onboard demonstration application.

In the local management interface, go to Secure Web Settings > Reverse Proxy.

Select inst1.

Select Manage > Junction Management.

Create a standard junction /demo with the following options:

Junction Point Name: /demo

Stateful Junction: true/enabled

Junction type: SSL

Servers: The runtime host and port where Advanced Access Control run time is running. If the reverse proxy and AAC are colocated, then localhost:443 can be set.

HTTP Basic Authentication Header: Filter

HTTP Header Identity Information: 'IVUSER', 'IVGROUPS', 'IVCREDS'

HTTP Header Encoding: UTF8 URI Encoded

Insert client IP address: true/enabled

Click Save.

Deploy and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Create a /mgaapi junctionCreate a junction to enable access to the Advanced Access Control authentication services framework for REST client access.In the local management interface, go to Secure Web SettingsReverse Proxy.Select inst1.Select ManageJunction Management.Create a standard junction /mgaapi with the following options:Junction Point Name: /mgaapiStateful Junction: true/enabled Junction type: SSL Servers: the runtime host and port where Advanced Access Control run time is running. If the reverse proxy and AAC are colocated, then localhost:443 can be set. HTTP Basic Authentication Header: Filter HTTP Header Identity Information: 'IVUSER', 'IVGROUPS', 'IVCREDS' HTTP Header Encoding: UTF8 URI Encoded Insert client IP address: true/enabledClick Save.Deploy and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Create a /mgaapi junction

Create a junction to enable access to the Advanced Access Control authentication services framework for REST client access.

In the local management interface, go to Secure Web Settings > Reverse Proxy.

Select inst1.

Select Manage > Junction Management.

Create a standard junction /mgaapi with the following options:

Junction Point Name: /mgaapi

Stateful Junction: true/enabled

Junction type: SSL

Servers: the runtime host and port where Advanced Access Control run time is running. If the reverse proxy and AAC are colocated, then localhost:443 can be set.

HTTP Basic Authentication Header: Filter

HTTP Header Identity Information: 'IVUSER', 'IVGROUPS', 'IVCREDS'

HTTP Header Encoding: UTF8 URI Encoded

Insert client IP address: true/enabled

Click Save.

Deploy and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Customize reverse proxy instance configurationCustomize reverse proxy instance configuration for REST API clients.In the local management interface, go to Secure Web SettingsReverse Proxy.Select inst1.Select ManageConfigurationEdit Configuration File.Disable oautheas.[oauth-eas] eas-enabled = falseEnable oauthauth [oauth] oauth-auth = https [session] require-mpa = noEnable managed cookies for the /mgaapi junction. Add the following stanza and entries at the end of the configuration file:[junction:/mgaapi] managed-cookies-list = *JSESSIONID*,PD_*Enable authentication obligations to trigger /mgaapi/sps/apiauthsvc.[obligations-urls-mapping] urn:ibm:security:authentication:asf:* = /mgaapi/sps/apiauthsvcExisting entries can be commented out.Enable local redirects for authentication server URLs and CBA protected resources.[server] maximumfollowredirects = 4 follow-redirects-for = !REPLAY! follow-redirects-for = GET /mgaapi/sps/apiauthsvc* follow-redirects-for = PUT /mgaapi/sps/apiauthsvc* follow-redirects-for = GET /demo/mobile-demo/rba*Click Save.Deploy and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Customize reverse proxy instance configuration

Customize reverse proxy instance configuration for REST API clients.

In the local management interface, go to Secure Web Settings > Reverse Proxy.

Select inst1.

Select Manage > Configuration > Edit Configuration File.

Disable oautheas.

[oauth-eas]
eas-enabled = false

Enable oauthauth

[oauth]
oauth-auth = https
[session]
require-mpa = no

Enable managed cookies for the /mgaapi junction. Add the following stanza and entries at the end of the configuration file:

[junction:/mgaapi]
managed-cookies-list = *JSESSIONID*,PD_*

Enable authentication obligations to trigger /mgaapi/sps/apiauthsvc.

[obligations-urls-mapping]
urn:ibm:security:authentication:asf:* = /mgaapi/sps/apiauthsvc

Existing entries can be commented out.

Enable local redirects for authentication server URLs and CBA protected resources.

[server]
maximumfollowredirects = 4
follow-redirects-for = !REPLAY!
follow-redirects-for = GET /mgaapi/sps/apiauthsvc*
follow-redirects-for = PUT /mgaapi/sps/apiauthsvc*
follow-redirects-for = GET /demo/mobile-demo/rba*

Click Save.

Deploy and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Set extra EAI authentication triggerSet /mgaapi/sps/apiauthsvc as an extra EAI authentication trigger.In the local management interface, go to Secure Web SettingsReverse Proxy.Select inst1.Click Edit.On the Authentication tab, add a trigger URL and sets its value as /mgaapi/sps/apiauthsvc*.Click Save.Deploy and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Set extra EAI authentication trigger

Set /mgaapi/sps/apiauthsvc as an extra EAI authentication trigger.

In the local management interface, go to Secure Web Settings > Reverse Proxy.

Select inst1.

Click Edit.

On the Authentication tab, add a trigger URL and sets its value as /mgaapi/sps/apiauthsvc*.

Click Save.

Deploy and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Attach ACLs to junctioned resource URLsIn the local management interface, go to Secure Web SettingsPolicy Administration.Log in as sec_master.Expand ACL and click Search ACLs.Click Search.Click isam_mobile_rest.Select the Attach tab.Click Attach.Set the Protected Object Path value to /WebSEAL/<hostname>inst1/ mgaapi/sps/apiauthsvc.Click Attach.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Attach ACLs to junctioned resource URLs

In the local management interface, go to Secure Web Settings > Policy Administration.

Log in as sec_master.

Expand ACL and click Search ACLs.

Click Search.

Click isam_mobile_rest.

Select the Attach tab.

Click Attach.

Set the Protected Object Path value to /WebSEAL/<hostname>inst1/ mgaapi/sps/apiauthsvc.

Click Attach.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Create API Protection OAuth definitions and clients Create API Protection OAuth definitions and clients. Then, attach them to the /demo junction.In the local management interface, go to Secure Access ControlAPI Protection.Create a definition named MyOAuthDemo.Enable Resource Owner Username Password grant type. Leave the remaining settings as defaults.Click Save.Click Clients.Click the new client icon.Set the Client ID value as mytestclient.Set the API Definition value as MyOAuthDemo.Click OK.Deploy and commit the changes.Click Resources.Attach the MyOAuthDemo definition to the /demo resource.Publish, deploy, and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Create API Protection OAuth definitions and clients

Create API Protection OAuth definitions and clients. Then, attach them to the /demo junction.

In the local management interface, go to Secure Access Control > API Protection.

Create a definition named MyOAuthDemo.

Enable Resource Owner Username Password grant type. Leave the remaining settings as defaults.

Click Save.

Click Clients.

Click the new client icon.

Set the Client ID value as mytestclient.

Set the API Definition value as MyOAuthDemo.

Click OK.

Deploy and commit the changes.

Click Resources.

Attach the MyOAuthDemo definition to the /demo resource.

Publish, deploy, and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Create a custom context-based access policy Create a custom context-based access policy with a TOTP authentication obligation.In the local management interface, go to Secure Access ControlAccess Control.Create a CBA policy named CBA_OTP_Demo.Add the following two policy rules:1. If authenticationMechanismTypes RegExp ".*totp" Then Permit 2. Permit with Authentication TOTP One-time PasswordExample combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Create a custom context-based access policy

Create a custom context-based access policy with a TOTP authentication obligation.

In the local management interface, go to Secure Access Control > Access Control.

Create a CBA policy named CBA_OTP_Demo.

Add the following two policy rules:

1. If authenticationMechanismTypes RegExp ".*totp"
Then Permit
2. Permit with Authentication TOTP One-time Password

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Attach the context-based access policyAttach the context-based access policy to the /demo/mobile-demo/rba resource URL.In the local management interface, go to Secure Access ControlAccess Control.Click Resource.Attach the CBA_OTP_Demo access policy to the resource path /demo/mobile-demo/rba.Publish, deploy, and commit the changes.Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Attach the context-based access policy

Attach the context-based access policy to the /demo/mobile-demo/rba resource URL.

In the local management interface, go to Secure Access Control > Access Control.

Click Resource.

Attach the CBA_OTP_Demo access policy to the resource path /demo/mobile-demo/rba.

Publish, deploy, and commit the changes.

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Create a test userIn the local management interface, go to Secure Web SettingsPolicy Administration.Log in as sec_master.Expand User.Click Create User.Create a user named testuser1. Example settings are shown as follows:UserId: testuser1 Common Name: testuser1 Surname: testuser1 Registry UID: cn=testuser1,dc=iswga Account Valid: Checked Password Valid: CheckedThe pdadmin command for creating this user is as follows:user create testuser1 cn=testuser1,dc=iswga testuser1 testuser1 passw0rd user modify testuser1 accountvalid yes user modify testuser1 passwordvalid yesExample combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Create a test user

In the local management interface, go to Secure Web Settings > Policy Administration.

Log in as sec_master.

Expand User.

Click Create User.

Create a user named testuser1. Example settings are shown as follows:

UserId: testuser1
Common Name: testuser1
Surname: testuser1
Registry UID: cn=testuser1,dc=iswga
Account Valid: Checked
Password Valid: Checked

The pdadmin command for creating this user is as follows:

user create testuser1 cn=testuser1,dc=iswga testuser1 testuser1 passw0rd
user modify testuser1 accountvalid yes
user modify testuser1 passwordvalid yes

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Initialize TOTP shared secret for the test userAccess the following URL as testuser1.Initialize the Google Authenticator app by scanning the QR code.https://<reverse proxy address>/mga/sps/mga/user/mgmt/html/otp/otp.htmlExample combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Initialize TOTP shared secret for the test user

Access the following URL as testuser1.

Initialize the Google Authenticator app by scanning the QR code.

https://<reverse proxy address>/mga/sps/mga/user/mgmt/html/otp/otp.html

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Use CURL to obtain an OAuth access tokenUse CURL to run the following OAuth ROPC command in a shell terminal to obtain an access token.curl k v X POST H "application/xwwwformurlencoded" data "client_id=mytestclient" data "scope=read" data "grant_type=password" data "username=testuser1" data "password=passw0rd" "https://<reverse proxy address>/mga/sps/oauth/oauth20/token"An example response is shown as follows:{ "scope": "read", "refresh_token": "MrnZ4j", "token_type": "bearer", "expires_in": 3599, "access_token": "C57M09" }Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Use CURL to obtain an OAuth access token

Use CURL to run the following OAuth ROPC command in a shell terminal to obtain an access token.

curl k v X POST H "application/xwwwformurlencoded"
data "client_id=mytestclient"
data "scope=read" data "grant_type=password"
data "username=testuser1"
data "password=passw0rd" "https://<reverse proxy
address>/mga/sps/oauth/oauth20/token"

An example response is shown as follows:

{
"scope": "read",
"refresh_token": "MrnZ4j",
"token_type": "bearer",
"expires_in": 3599,
"access_token": "C57M09"
}

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Use CURL to access /demo/mobile-demo/rba with the access tokenUse CURL to run the following command in a shell terminal.The command includes the previously obtained access token with the Authorization header. Use this command to access the protected application resource /demo/mobile-demo/rba.curl k v H "Authorization: Bearer C57M09" H "ContentType: application/json" H "Accept: application/json" https://<reverse proxy address>/demo/mobiledemo/rbaThe response is the result of enforcement of the previously attached CBA policy. The policy requires completion of a TOTP authentication.< HTTP/1.1 200 OK < { "mechanism": "urn:ibm:security:authentication:asf:mechanism:totp", "message": "", "state": "9efd546c5a574d218a027a79110c2f19", "location": "/mga/sps/apiauthsvc?StateId=9efd546c5a574d218a027a79110c2f19", "execptionMsg": "NA" }The next request validates the TOTP for testuser1. The otp value is supplied by testuser1 by reading its Google Authenticator app.curl k v X PUT H "ContentType: application/json" H "Accept: application/json" H "Authorization: Bearer C57M09" data "{'otp': '842998'}" "https://<reverse proxy address>/mgaapi/sps/apiauthsvc?StateId=9efd546c5a574d218a027a79110c2f19"The resulting response is the actual protected resource from /demo/mobile-demo/rba. Its data format is HTML. However, the basic configuration and REST client experience is successfully deployed.< HTTP/1.1 200 OK < contentlanguage: enUS < contenttype: text/html;charset=ISO88591 < date: Mon, 08 Feb 2016 04:06:34 GMT < p3p: CP="NON CUR OTPi OUR NOR UNI" < xoldcontentlength: 1554 < transferencoding: chunked < cachecontrol: nocache="setcookie, setcookie2" < expires: Thu, 01 Dec 1994 16:00:00 GMT<HTML> <BODY> <div class="content"> <div class="contentHeader"> <h1 class="pageTitle">Riskbased access protected resource</h1> <div class="instructions"></div> </div> <div class="pageContent" style="width: 600">If you get the following page, then either you have a match for the device fingerprint or you were already authenticated at a high level (for example, one-time password).</div> </div> </BODY> </HTML>Example combining CBA, Authentication Service Framework, and OAuthThe onboard RBA demonstration application is used to illustrate how to configure the Security Access Manager features that are discussed in previous topics for REST API client access.

Use CURL to access /demo/mobile-demo/rba with the access token

Use CURL to run the following command in a shell terminal.

The command includes the previously obtained access token with the Authorization header. Use this command to access the protected application resource /demo/mobile-demo/rba.

curl k v H "Authorization: Bearer C57M09" H "ContentType: application/json"
H "Accept: application/json" https://<reverse proxy address>/demo/mobiledemo/rba

The response is the result of enforcement of the previously attached CBA policy. The policy requires completion of a TOTP authentication.

< HTTP/1.1 200 OK
<
{
"mechanism": "urn:ibm:security:authentication:asf:mechanism:totp",
"message": "",
"state": "9efd546c5a574d218a027a79110c2f19",
"location": "/mga/sps/apiauthsvc?StateId=9efd546c5a574d218a027a79110c2f19",
"execptionMsg": "NA"
}

The next request validates the TOTP for testuser1. The otp value is supplied by testuser1 by reading its Google Authenticator app.

curl k v X PUT H "ContentType: application/json" H "Accept: application/json" H
"Authorization: Bearer C57M09" data "{'otp': '842998'}"  "https://<reverse  proxy
address>/mgaapi/sps/apiauthsvc?StateId=9efd546c5a574d218a027a79110c2f19"

The resulting response is the actual protected resource from /demo/mobile-demo/rba. Its data format is HTML. However, the basic configuration and REST client experience is successfully deployed.

< HTTP/1.1 200 OK
< contentlanguage: enUS
<  contenttype:  text/html;charset=ISO88591
< date: Mon, 08 Feb 2016 04:06:34 GMT
< p3p: CP="NON CUR OTPi OUR NOR UNI"
< xoldcontentlength: 1554
< transferencoding: chunked
< cachecontrol: nocache="setcookie, setcookie2"
< expires: Thu, 01 Dec 1994 16:00:00 GMT

<HTML>
<BODY>
<div class="content">
<div  class="contentHeader">
<h1 class="pageTitle">Riskbased access protected resource</h1>
<div  class="instructions"></div>
</div>
<div class="pageContent" style="width: 600">

If you get the following page, then either you have a match for the device fingerprint or you were already authenticated at a high level (for example, one-time password).

</div>
</div>
</BODY>
</HTML>

Parent topic: Example combining CBA, Authentication Service Framework, and OAuth

Web administration Java classes API documentationUse the IBM Security Access Manager administration Java classes API to add administration tasks to new or existing Java applications.Java classesWeb administrationAPI documentationWeb administrationJava classesAPI documentationAPI documentationWeb administration Java classesYou can access the following documentation from the Support site:Administration Java Classes Developer ReferenceJavadoc API referenceDeveloping You can use APIs to develop applications and programs to work with IBM Security Access Manager.

Web administration Java classes API documentation

Use the IBM Security Access Manager administration Java classes API to add administration tasks to new or existing Java applications.

You can access the following documentation from the Support site:

Administration Java Classes Developer Reference

Javadoc API reference

Parent topic: Developing

Web authorization Java classes API documentationUse the IBM Security Access Manager authorization Java classes API to add product authorization and security services to new or existing Java applications.Java classesWeb authorizationAPI documentationWeb authorizationJava classesAPI documentationAPI documentationWeb authorization Java classesYou can access the following documentation from the Support site:Authorization Java Classes Developer ReferenceJavadoc API referenceDeveloping You can use APIs to develop applications and programs to work with IBM Security Access Manager.

Web authorization Java classes API documentation

Use the IBM Security Access Manager authorization Java classes API to add product authorization and security services to new or existing Java applications.

You can access the following documentation from the Support site:

Authorization Java Classes Developer Reference

Javadoc API reference

Parent topic: Developing

Setting up an Access Manager Runtime for Java systemThe Access Manager Runtime for Java offers a reliable environment for developing and deploying Java applications in a Security Access Manager secure domain. Use it to add Security Access Manager authorization and security services to new or existing Java applications.runtime for javasetting upSet up this system by following the instructions that are appropriate for your operating system.IBM Security Access Manager Runtime for Java configures additional security features into the specified JRE.IBM Security Access Manager Runtime for Java supports only the following Java runtime environments (JREs): IBM Java RuntimeThe JRE provided with WebSphere Application ServerIf you reinstall and reconfigure the Security Access Manager policy server, or install any IBM WebSphere Application Server patches, you must unconfigure and reconfigure IBM Security Access Manager Runtime for Java.Developing You can use APIs to develop applications and programs to work with IBM Security Access Manager.Installing IBM Security Access Manager Runtime for JavaExtract the contents of the runtime package file to install the IBM Security Access Manager Runtime for Java system and use the pdjrtecfg utility to configure it.

Setting up an Access Manager Runtime for Java system

The Access Manager Runtime for Java offers a reliable environment for developing and deploying Java™ applications in a Security Access Manager secure domain. Use it to add Security Access Manager authorization and security services to new or existing Java applications.

Set up this system by following the instructions that are appropriate for your operating system.

IBM Security Access Manager Runtime for Java configures additional security features into the specified JRE.

Note:

IBM Security Access Manager Runtime for Java supports only the following Java runtime environments (JREs):

IBM® Java Runtime

The JRE provided with WebSphere® Application Server

If you reinstall and reconfigure the Security Access Manager policy server, or install any IBM WebSphere Application Server patches, you must unconfigure and reconfigure IBM Security Access Manager Runtime for Java.

Installing IBM Security Access Manager Runtime for Java
Extract the contents of the runtime package file to install the IBM Security Access Manager Runtime for Java system and use the pdjrtecfg utility to configure it.

Parent topic: Developing

Installing IBM Security Access Manager Runtime for JavaExtract the contents of the runtime package file to install the IBM Security Access Manager Runtime for Java system and use the pdjrtecfg utility to configure it.IBM Security Access Manager Runtime for JavainstallationLog on as root for UNIX systems or a user with Administrator group privileges for Windows systems.Download the runtime package file from the appliance. Go to Manage System SettingsFile Downloads.Download the runtime package file pdjrte-9.0.0-0.zip from the isam directory. Extract the contents of the pdjrte-9.0.0-0.zip file.Ensure that either IBM Java Runtime or the JRE provided with WebSphere Application Server is installed. IBM Security Access Manager Runtime for Java configures extra security features into the specified JRE and only these two JREs are supported.To set up IBM Security Access Manager Runtime for Java with a configuration type of Full, ensure that both the policy server and registry server are running. If the configuration type is standalone, this step is not required.Before you configure the IBM Security Access Manager Runtime for Java component, ensure that either the IBM Java Runtime or the JRE provided with WebSphere Application Server can be located by using the PATH environment variable.To configure the IBM Security Access Manager Runtime for Java component, run the pdjrtecfg utility. On UNIX systems, use the following command: pdjrtecfg -action config -interactive On Windows systems, use the following command: pdjrtecfg.bat -action config -interactive This step completes the setup of the Security Access Manager IBM Security Access Manager Runtime for Java component. Setting up an Access Manager Runtime for Java systemThe Access Manager Runtime for Java offers a reliable environment for developing and deploying Java applications in a Security Access Manager secure domain. Use it to add Security Access Manager authorization and security services to new or existing Java applications.

Installing IBM Security Access Manager Runtime for Java

Extract the contents of the runtime package file to install the IBM Security Access Manager Runtime for Java system and use the pdjrtecfg utility to configure it.

Procedure

Log on as root for UNIX systems or a user with Administrator group privileges for Windows systems.

Download the runtime package file from the appliance.

Go to Manage System Settings > File Downloads.

Download the runtime package file pdjrte-9.0.0-0.zip from the isam directory.

Extract the contents of the pdjrte-9.0.0-0.zip file.

Ensure that either IBM® Java™ Runtime or the JRE provided with WebSphere® Application Server is installed.
IBM Security Access Manager Runtime for Java configures extra security features into the specified JRE and only these two JREs are supported.

To set up IBM Security Access Manager Runtime for Java with a configuration type of Full, ensure that both the policy server and registry server are running. If the configuration type is standalone, this step is not required.

Before you configure the IBM Security Access Manager Runtime for Java component, ensure that either the IBM Java Runtime or the JRE provided with WebSphere Application Server can be located by using the PATH environment variable.

To configure the IBM Security Access Manager Runtime for Java component, run the pdjrtecfg utility.

On UNIX systems, use the following command:

pdjrtecfg -action config -interactive

On Windows systems, use the following command:

pdjrtecfg.bat -action config -interactive

Results

This step completes the setup of the Security Access Manager IBM Security Access Manager Runtime for Java component.

Parent topic: Setting up an Access Manager Runtime for Java system

Developing for Advanced Access Control You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.See the REST API documentation here.You must activate the Advanced Access Control Module to use these features.Developing You can use APIs to develop applications and programs to work with IBM Security Access Manager.REST services for OTP secret keysYou can use the REST services capability to help manage your mobile data, such as your HOTP and TOTP secret keys.REST services for knowledge questionsYou can use REST services to manage knowledge questions.REST services for device fingerprint registrationYou can use the REST services capability to manage your mobile data such as your registered devices.Software Development KitUse the Software Development Kit so that you can create customized components such as your own obligation handler or authentication mechanism.

Developing for Advanced Access Control

You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.

See the REST API documentation here.

Note: You must activate the Advanced Access Control Module to use these features.

REST services for OTP secret keys
You can use the REST services capability to help manage your mobile data, such as your HOTP and TOTP secret keys.

REST services for knowledge questions
You can use REST services to manage knowledge questions.

REST services for device fingerprint registration
You can use the REST services capability to manage your mobile data such as your registered devices.

Software Development Kit
Use the Software Development Kit so that you can create customized components such as your own obligation handler or authentication mechanism.

Parent topic: Developing

REST services for OTP secret keys REST services for OTP secret keys REST services for OTP secret keys You can use the REST services capability to help manage your mobile data, such as your HOTP and TOTP secret keys.rest services for otp secret keys rest services for otp secret keys hotp secret keysrest services for otp secret keys totp secret keysTo help prevent unauthorized users from confiscating and resetting the secrets keys that belong to authorized users, the administrator must complete the following steps: Write a policy that requires a form of two-factor authentication other than the following authentication types:HOTP TOTPAttach the policy to the OTP management URLs. The user must authenticate to use the REST services capability. REST services usage scenarios Depending on your usage scenario, type the following URLs into the web page that calls the REST services: REST services instructionsMethodURLResponseResponse typeGEThttps://hostname/mga/sps/mga/user/mgmt/otp/{otpType} Valid values for otpType include the following values:totphotp {"username": username, "secretKey": secretKey, "secretKeyUrl": secretKeyUrl}If the request completes successfully, the HTTP response code is 200.If the request does not complete successfully, the HTTP response is 500. application/json GEThttps://hostname/mga/sps/mga/user/mgmt/otp/qr/{otpType} Valid values for otpType include the following values:totphotp Quick response (QR) codeIf the request completes successfully, the HTTP response code is 200.If the request does not complete successfully, the HTTP response is 500. image/gifDELETEhttps://hostname/mga/sps/mga/user/mgmt/otp/{otpType} Valid values for otpType include the following values:totphotp {"result": message}If the request completes successfully, the HTTP response code is 200.If the request does not complete successfully, the HTTP response is 500. The following message is in the JSON response: FBTRBA168E The HMAC OTP secret key could not be reset. application /json Developing for Advanced Access Control You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.

REST services for OTP secret keys

You can use the REST services capability to help manage your mobile data, such as your HOTP and TOTP secret keys.

To help prevent unauthorized users from confiscating and resetting the secrets keys that belong to authorized users, the administrator must complete the following steps:

Write a policy that requires a form of two-factor authentication other than the following authentication types:

HOTP

TOTP

Attach the policy to the OTP management URLs.

Note: The user must authenticate to use the REST services capability.

REST services usage scenarios

Depending on your usage scenario, type the following URLs into the web page that calls the REST services:

Table 317. REST services instructions

Method
URL
Response
Response type

GET
https://hostname/mga/sps/mga/user/mgmt/otp/{otpType}

Note: Valid values for otpType include the following values:

totp

hotp

{"username": username, "secretKey": secretKey, "secretKeyUrl": secretKeyUrl}

If the request completes successfully, the HTTP response code is 200.

If the request does not complete successfully, the HTTP response is 500.

application/json

GET
https://hostname/mga/sps/mga/user/mgmt/otp/qr/{otpType}

Note: Valid values for otpType include the following values:

totp

hotp

Quick response (QR) code

If the request completes successfully, the HTTP response code is 200.

If the request does not complete successfully, the HTTP response is 500.

image/gif

DELETE
https://hostname/mga/sps/mga/user/mgmt/otp/{otpType}

Note: Valid values for otpType include the following values:

totp

hotp

{"result": message}

If the request completes successfully, the HTTP response code is 200.

If the request does not complete successfully, the HTTP response is 500. The following message is in the JSON response: FBTRBA168E The HMAC OTP secret key could not be reset.

application /json

Parent topic: Developing for Advanced Access Control

REST services for knowledge questionsREST services for knowledge questionsREST services for knowledge questionsYou can use REST services to manage knowledge questions.knowledge questions rest services Users can perform self care management operations to retrieve, create, update, and delete knowledge questions. You can use REST services to support these operations.The knowledge question attributes are:idThe unique ID of the question answerThe user-supplied answer to the questionquestionThe text of the user defined questionThe base URL for all the self-care management REST interfaces for knowledge questions is: https://<WebSEAL host>:<port>/<junction_name>/sps/mga/user/mgmt/The REST interfaces represent a collection of questions. The URI template is /questions.For all methods, the response type for Accept Header and Content-Type Header is application/json.Sorting, filtering, and paging are not supported.Users must authenticate in order to use the REST services.REST interface for managing knowledge questionsA list of the methods, a description, and the URL for the REST interface.MethodOperation URLResponseGETRetrieve a list of questions for a user.http://<WebSEAL host>:<port>/<junction_name>/sps/mga/user/mgmt/questionsResponse code: 200 OKThe response is a JSON array of questions and JSON objects. To view an example response, see User questions REST modelPOSTCreate all the questions for a user.Response code: 201 CREATEDPUTUpdate all the questions for a user Response code: 204 NO CONTENT DELETEDelete all questions that are registered for a userError responsesA list of the methods and error responses.MethodError ResponsePOSTResponse code: 400 BAD REQUESTResponse type: application/jsonExplanation: Malformed question found. Possible reasons:No answer submitted.Non-Unique Questions ID The ID for each question must be unique for each user. The ID does not have to be globally unique.PUTUser questions REST modelThe following table lists the attributes for user knowledge questions.Attributes for user questionsA list of the attributes, a description of each, and examples.AttributeExamplesName: username Description: the usernameData type: StringOnly provided on the response for a GET"sec_master"Name: questionsDescription: the list of knowledge questionsData Type: JSON array of JSON objectsThe caller supplies the id value. However, for PUT or POST methods if id is not provided the server generates a unique id for the question.The parameter question is optional The answer attribute will be obfuscated (replaced by the asterisk symbol "*") on responses.Example questions:[ { "id": "1", "answer" : "Smith", "question" : "What is your mother's maiden name?" }, { "id": "2", "answer" : "Bandit", "question" : "What is your Pet's name?" } ]Name: result Description: An error message that indicates the nature of the failure. Datatype: String{ "result": "FBTRBA310E The user knowlege questions answer(s) could not be stored because a duplicate question unique identifier [1] was included on the user questions." }Example JSON representation of a collection of knowledge questionsThe following example shows the JSON representation of a collection of knowledge questions that belong to a user.{ "username": "sec_master", "questions" : [ { "id" : "1", "answer" : "******", "question" : "What is your mother's maiden name?" }, { "id" : "2", "answer" : ********, "question" : "What is your Pet's name?" } ] }Developing for Advanced Access Control You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.

REST services for knowledge questions

You can use REST services to manage knowledge questions.

Users can perform self care management operations to retrieve, create, update, and delete knowledge questions. You can use REST services to support these operations.

The knowledge question attributes are:

id

The unique ID of the question

answer

The user-supplied answer to the question

question

The text of the user defined question

The base URL for all the self-care management REST interfaces for knowledge questions is:

https://<WebSEAL host>:<port>/<junction_name>/sps/mga/user/mgmt/

The REST interfaces represent a collection of questions. The URI template is /questions.

Note:

For all methods, the response type for Accept Header and Content-Type Header is application/json.

Sorting, filtering, and paging are not supported.

Users must authenticate in order to use the REST services.

Table 318. REST interface for managing knowledge questions.

Method
Operation
URL
Response

GET

Retrieve a list of questions for a user.

http://<WebSEAL host>:<port>/<junction_name>/sps/mga/user/mgmt/questions

Response code: 200 OK

The response is a JSON array of questions and JSON objects. To view an example response, see User questions REST model

POST

Create all the questions for a user.

Response code: 201 CREATED

PUT

Update all the questions for a user

Response code: 204 NO CONTENT

DELETE

Delete all questions that are registered for a user

Table 319. Error responses.

Method
Error Response

POST

Response code: 400 BAD REQUEST

Response type: application/json

Explanation: Malformed question found. Possible reasons:

No answer submitted.

Non-Unique Questions ID

The ID for each question must be unique for each user. The ID does not have to be globally unique.

PUT

User questions REST model

The following table lists the attributes for user knowledge questions.

Table 320. Attributes for user questions.

Attribute
Examples

Name: username

Description: the username

Data type: String

Note: Only provided on the response for a GET

"sec_master"

Name: questions

Description: the list of knowledge questions

Data Type: JSON array of JSON objects

Note:

The caller supplies the id value. However, for PUT or POST methods if id is not provided the server generates a unique id for the question.

The parameter question is optional

The answer attribute will be obfuscated (replaced by the asterisk symbol "*") on responses.

Example questions:

[
  {
    "id": "1",
    "answer"     : "Smith",
    "question"   : "What is your mother's maiden name?"
  },
  {
    "id": "2",
    "answer"     : "Bandit",
    "question"   : "What is your Pet's name?"
  }
]

Name: result

Description: An error message that indicates the nature of the failure.

Datatype: String

{
    "result": "FBTRBA310E The user knowlege questions
               answer(s) could not be stored because
               a duplicate question unique identifier
               [1] was included on the user questions."
}

Example JSON representation of a collection of knowledge questions

The following example shows the JSON representation of a collection of knowledge questions that belong to a user.

{
  "username": "sec_master",
  "questions" : [
               {
                "id"    : "1",
                "answer"  : "******",
                "question"   : "What is your mother's maiden name?"
               },
               {
                "id"    : "2",
                "answer"  : ********,
                "question"   : "What is your Pet's name?"
               }
              ]
}

Parent topic: Developing for Advanced Access Control

REST services for device fingerprint registrationREST services for device fingerprint registrationREST services for device fingerprint registrationYou can use the REST services capability to manage your mobile data such as your registered devices.rest services for device fingerprint registrationThe user must authenticate to use the REST services capability. REST services usage scenarios Depending on your usage scenario, type the following URLs into the web page that calls the REST services: REST services instructionsMethodURLRequestResponseResponse typeGEThttps://hostname/mga/sps/mga/user/mgmt/deviceThere is no JSON payload included in the request. {"username": username,  "devices":[{"name":device Name, "id":deviceId, "lastUsedTime":lastUsed Time, "isEnabled": {true |false}}, ....]}If the request completes successfully, the HTTP response code is 200.If the request does not complete successfully, the HTTP response is 500. application /json GEThttps://hostname/mga/sps/mga/user/mgmt/device/{deviceId}There is no JSON payload included in the request.{"username": username, "name":deviceName, "attributes":[{"name": attributeName1, "value": attributeValue1}, ... , {"name":attributeNameN, "value":attributeValueN}]}If the request completes successfully, the HTTP response code is 200.If the request does not complete successfully, the HTTP response is 500. application /json DELETEhttps://hostname/mga/sps/mga/user/mgmt/device/{deviceId}There is no JSON payload included in the request.{"result": message}If the request completes successfully, the HTTP response code is 200. If the request does not complete successfully, the HTTP response is 500. One of the following messages is in the JSON response: FBTRBA164E The device device name could not be removed.FBTRBA163I The device device name was removed successfully. application /json PUThttps://hostname/mga/sps/mga/user/mgmt/device/{deviceId} {"name": "new_name", "isEnabled": {true| false}} {"result": message}If the request completes successfully, the HTTP response code is 200. The following message is in the JSON response: FBTRBA165I The device <Variable formatSpec="{0}">name</Variable> was updated successfully.If you give the device an invalid name, the HTTP response code is 400. The following message is in the JSON response: FBTRBA182E The value device name is invalid.If you give the device a name that belongs to another device, the response code is 400. The following message is in the JSON response: FBTRBA186E A device named '<Variable formatSpec="{0}">device name</Variable>' already exists.  application /json Managing your registered devices You can modify the registered device fingerprints that the risk engine compares with incoming request device fingerprints in risk score calculation scenarios. Developing for Advanced Access Control You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.

REST services for device fingerprint registration

You can use the REST services capability to manage your mobile data such as your registered devices.

Note: The user must authenticate to use the REST services capability.

REST services usage scenarios

Depending on your usage scenario, type the following URLs into the web page that calls the REST services:

Table 321. REST services instructions

Method
URL
Request
Response
Response type

GET
https://hostname/mga/sps/mga/user/mgmt/device
There is no JSON payload included in the request.
{"username": username,  "devices":[{"name":device Name, "id":deviceId, "lastUsedTime":lastUsed Time, "isEnabled": {true |false}}, ....]}

If the request completes successfully, the HTTP response code is 200.

If the request does not complete successfully, the HTTP response is 500.

application /json

GET
https://hostname/mga/sps/mga/user/mgmt/device/{deviceId}
There is no JSON payload included in the request.
{"username": username, "name":deviceName, "attributes":[{"name": attributeName1, "value": attributeValue1}, ... , {"name":attributeNameN, "value":attributeValueN}]}

If the request completes successfully, the HTTP response code is 200.

If the request does not complete successfully, the HTTP response is 500.

application /json

DELETE
https://hostname/mga/sps/mga/user/mgmt/device/{deviceId}
There is no JSON payload included in the request.
{"result": message}

If the request completes successfully, the HTTP response code is 200.

If the request does not complete successfully, the HTTP response is 500. One of the following messages is in the JSON response:

FBTRBA164E The device device name could not be removed.

FBTRBA163I The device device name was removed successfully.

application /json

PUT
https://hostname/mga/sps/mga/user/mgmt/device/{deviceId}

{"name": "new_name", "isEnabled": {true| false}}

{"result": message}

If the request completes successfully, the HTTP response code is 200. The following message is in the JSON response: FBTRBA165I The device <Variable formatSpec="{0}">name</Variable> was updated successfully.

If you give the device an invalid name, the HTTP response code is 400. The following message is in the JSON response: FBTRBA182E The value device name is invalid.

If you give the device a name that belongs to another device, the response code is 400. The following message is in the JSON response: FBTRBA186E A device named '<Variable formatSpec="{0}">device name</Variable>' already exists. 

application /json

Parent topic: Developing for Advanced Access Control

Managing your registered devices

Software Development KitSoftware Development KitSoftware Development KitUse the Software Development Kit so that you can create customized components such as your own obligation handler or authentication mechanism.software development kit server-side obligation handlerauthentication mechanismThe Advanced Access Control Software Development Kit includes extensions that you can use to create an obligation handler or an authentication mechanism.Use the obligation handler extension point so that obligations are handled at the policy decision point before it returns the result to the policy enforcement point application. Use the authentication mechanism extension point to create conditions that successfully authenticate a user. Extensions that are created by using the Software Development Kit are run in a restricted environment in to prevent accidental damage to appliance resources. This step is done by denying access to function calls that require certain permissions. If your implementations call to such functions, directly or indirectly, the code execution is stopped and an AccessControlException error is displayed.The following are the restricted permissions that cause exceptions:java.io.FilePermission("<<ALL FILES>>", "read,write"));java.net.SocketPermission("", "listen"));java.lang.RuntimePermission("setSecurityManager"));For information about creating an obligation handler or authentication mechanism, see the Developing section in developerWorks.For information about managing extensions in the local management interface, see ExtensionsUse extensions so that you can implement your own obligation handler and authentication mechanism..Developing for Advanced Access Control You can use IBM Security Access Manager Advanced Access Control APIs to develop applications and programs for context-based access. These topics are specific to the Advanced Access Control activation level.

Software Development Kit

Use the Software Development Kit so that you can create customized components such as your own obligation handler or authentication mechanism.

The Advanced Access Control Software Development Kit includes extensions that you can use to create an obligation handler or an authentication mechanism.

Use the obligation handler extension point so that obligations are handled at the policy decision point before it returns the result to the policy enforcement point application. Use the authentication mechanism extension point to create conditions that successfully authenticate a user.

Extensions that are created by using the Software Development Kit are run in a restricted environment in to prevent accidental damage to appliance resources. This step is done by denying access to function calls that require certain permissions. If your implementations call to such functions, directly or indirectly, the code execution is stopped and an AccessControlException error is displayed.

The following are the restricted permissions that cause exceptions:

java.io.FilePermission("<<ALL FILES>>", "read,write"));

java.net.SocketPermission("", "listen"));

java.lang.RuntimePermission("setSecurityManager"));

For information about creating an obligation handler or authentication mechanism, see the Developing section in developerWorks®.

For information about managing extensions in the local management interface, see Extensions.

Parent topic: Developing for Advanced Access Control

Developing for Federation You can use IBM Security Access Manager Federation Module APIs to develop applications and programs to manage federations and partners. See the REST API documentation here.You must activate the Federation Module to use the federation features.Developing You can use APIs to develop applications and programs to work with IBM Security Access Manager.

Developing for Federation

You can use IBM Security Access Manager Federation Module APIs to develop applications and programs to manage federations and partners.

See the REST API documentation here.

Note: You must activate the Federation Module to use the federation features.

Parent topic: Developing